feat(examples): Idle Curator — a senior foreman for your agent: while you're away it verifies the work and wakes stale chats with proof, never with empty pings

[DScoNOIZ]

Issue for this PR

Closes # (none — standalone examples contribution; happy to link a tracking issue if you prefer one).

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Every agent CLI wastes its best compute window: the hours the user is away. This PR adds examples/idle-curator — a complete, working pattern that turns idle time into the highest-quality analysis slot. I have been running it daily on Linux and it changed how stale sessions get handled.

The problem in simple words: today an idle session either gets a dumb timer ping ("are you still there?") or nothing at all. A ping with no analysis is noise; silence wastes the one moment when heavy analysis costs nothing because nobody is waiting.

What this does differently, in three parts:

1. It knows whether you are actually gone. Most watchdogs only see app idle. This one fuses two clocks: agent-loop idle (session events + tool hooks) and OS input idle (GNOME Mutter → KDE → X11 xprintidle → unknown). The result is four states instead of a boolean: AWAY (gone, full analysis), FORGOTTEN_TAB (you work next door but forgot this chat — it may still use the time), BACKGROUND (you are at the PC but not in the app), PRESENT (you are typing right here — it stays silent, logs only). No timer ever fires blind.

2. Nothing reaches the chat unverified. When a session qualifies, a fresh curator session analyzes its digest and must return a parseable [wake:VERDICT] contract (CONTINUE / CORRECT / STOP / ABORT plus a lifecycle vote). Then — and this is the point — a separate fact-check session validates every claim against tool outputs, repo files, or at most 3 web lookups, and returns [factcheck:PASS/FAIL]. Anything without PASS is delivered marked UNVERIFIED, never as fact. The curator never grades its own homework; I added this after catching the curator itself making a factual error in a verdict.

3. Every module is a settings switch. All 13 keys (enabled / curator_enabled / factcheck_enabled / presence_enabled, all timeouts, caps) are re-read from JSON every tick — no restart. One key maps to one future GUI control. The Linux probe is per-user userspace (one D-Bus call or a 15 KB XScreenSaver binary, ~3 ms per minute); turning telemetry off means zero exec, not a stub. Guards included: HIBERNATE after N wakes, exponential backoff on ignored wakes, a blind window so the woken agent's own verification tools never re-trigger the watchdog, stall-push on 3+ consecutive tool errors.

Scenarios it covers: you leave for the day → AWAY, deep multi-agent-quality review by morning; you sit in another tab for an hour → FORGOTTEN_TAB, the old chat still gets its analysis quietly; you type in the chat → PRESENT, zero interruptions; a chat that only asked questions and ran no tools stays invisible by design (nothing to analyze).

Files: wake.js (watchdog plugin), presence.sh + xidle.c (probe + 13-line fallback), curator-agent.md + factcheck.md (agent contracts), wake.json.example, README.md. Additive-only — one new examples/ directory, zero core changes.

How did you verify your code works?

• node --check on the plugin: clean. Config parses, all 13 keys validated with range checks.
• Mock-client harness against the real file (2 s tick): session with tool activity + quiet → exactly 1 wake; session with zero tools → 0 wakes; second fire inside cooldown → blocked. 3/3 green.
• Live Linux probe on X11: 185277 → 188327 ms across a 3 s sleep (counter tracks reality), 847 ms right after keyboard input. presence.sh exit 0 in all paths including unknown-hardware fallback.
• Honest gap: the full live wake → curator → factcheck injection cycle needs a 10-minute real idle window, still under observation. It cannot affect the test suite — no core files touched.

Screenshots / recordings

Not a UI change. Terminal evidence instead:

$ bash presence.sh
{"os_idle_ms":185277,"source":"xprintidle","session_type":"x11","desktop":"XFCE"}
$ sleep 3; bash presence.sh
{"os_idle_ms":188327,"source":"xprintidle","session_type":"x11","desktop":"XFCE"}

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

[github-actions]

Thanks for updating your PR! It now meets our contributing guidelines. 👍