@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/lib/watchdog/runner.js

@@ -3,19 +3,23 @@
  * working auto-nudge (RUSH-1415). The `agents watchdog` command drives it, so
  * the whole loop runs WITHOUT the Swift menu-bar.
  *
- * One tick, per session:
+ * One tick:
  *
  *   getActiveSessions()                            (session/active.ts)
- *     -> classifyTerminal(...)                     (watchdog/watchdog.ts)  — stalled?
- *       -> readWatchdogTail(...)                   (watchdog/read.ts)      — the transcript tail
- *         -> isLikelyTrulyBlocked(...)             (watchdog/watchdog.ts)  — promise-without-toolcall, NOT waiting-on-user
+ *     -> classifyTerminal(...) per session         (watchdog/watchdog.ts)  — which are idle?
+ *       -> readWatchdogTail(...) for the idle ones  (watchdog/read.ts)      — task + transcript tail
+ *         -> the watchdog AGENT judges them ALL at once (watchdog/watchdog-agent.ts)
+ *              — idle-but-unfinished -> nudge; idle-and-done / needs-human -> skip
  *           -> resolveInjectTargetForSession(...)  (terminal/resolve.ts)   — THE safety gate: addressable or an honest refusal
- *             -> injectIntoTerminal(target,text)   (terminal/inject.ts)    — deliver "Continue." into the EXACT split
+ *             -> injectIntoTerminal(target,text)   (terminal/inject.ts)    — deliver into the EXACT split, then CONFIRM
  *
- * The safety gate is absolute: a nudge is delivered ONLY when the resolver
- * returns `addressable: true`. On `addressable: false` the reason is recorded to
- * a state file the menu-bar can surface later and the session is SKIPPED — never
- * a guessed / frontmost target.
+ * There is no heuristic decider — no regex over the tail guessing done-vs-stuck.
+ * The agent is the whole decider, given every idle session's task + tail in ONE
+ * `agents run --mode plan` call per tick. The safety gate is absolute: a nudge is
+ * delivered ONLY when the resolver returns `addressable: true`, and it is booked in
+ * the cooldown ledger ONLY when delivery is CONFIRMED. On `addressable: false` the
+ * reason is recorded to a state file the menu-bar can surface and the session is
+ * SKIPPED — never a guessed / frontmost target.
  *
  * Persistence (all under ~/.agents/.cache/state/watchdog/, tray-readable):
  *   - nudges.json  — { [sessionId]: lastNudgeMs } — enforces the cooldown.
@@ -25,10 +29,10 @@
  *   - rotate/<sessionId>.json — the in-place rotate state machine (rotate.ts).
  *   - rotate-skips.json — zero-healthy skip suppression: { [sessionId]: suppressUntilMs }.
  *
- * The pure logic (classifyTerminal / isLikelyTrulyBlocked) is imported and never
- * re-implemented; the runner only supplies its I/O (sessions, tails, clock,
- * policy, injection) — each an injectable seam so runner.test.ts drives real
- * synthetic sessions without a live terminal.
+ * The pure logic (classifyTerminal) is imported and never re-implemented; the
+ * runner only supplies its I/O (sessions, tails, clock, policy, the agent decider,
+ * injection) — each an injectable seam so runner.test.ts drives real synthetic
+ * sessions without a live terminal or a real `agents run`.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -36,7 +40,8 @@ import * as crypto from 'crypto';
 import { getActiveSessions } from '../session/active.js';
 import { reconcilePresence, loadPresence, savePresence, observedFromActive, } from '../session/presence.js';
 import { resolveInjectTargetForSession, injectIntoTerminal, } from '../terminal/index.js';
-import { classifyTerminal, isLikelyTrulyBlocked, renderWatchdogPrompt, parseWatchdogResponse, } from './watchdog.js';
+import { classifyTerminal, } from './watchdog.js';
+import { makeWatchdogAgentDecider } from './watchdog-agent.js';
 import { readWatchdogTail, WATCHDOG_STALL_MS, WATCHDOG_COOLDOWN_MS, WATCHDOG_DORMANT_MS, WATCHDOG_TAIL_LINES, } from './read.js';
 import { getRuntimeStateDir } from '../state.js';
 import { withFileLock, atomicWriteFileSync, ensureLockTarget } from '../fs-atomic.js';
@@ -113,80 +118,6 @@ function defaultLastActivity(s) {
     }
     return s.startedAtMs;
 }
-/**
- * COMPLETION_HINTS mirror of watchdog.ts. The deterministic pre-filter screens
- * completions to `skip` before the promise check so a finished-but-idle session
- * is never nudged. (isLikelyTrulyBlocked also guards completion now that its 15m
- * precedence is fixed; this explicit check keeps the pre-filter self-contained.)
- */
-const COMPLETION_HINTS = ['done', 'completed', 'all set', 'finished'];
-function tailShowsCompletion(candidate) {
-    if (candidate.tailLines.length === 0)
-        return false;
-    const lowerTail = candidate.tailLines.join('\n').toLowerCase();
-    return COMPLETION_HINTS.some((hint) => lowerTail.includes(hint));
-}
-function deterministicDecision(session, candidate) {
-    // Parked on a question — the case Muqsit cares about most. Do NOT drop it:
-    // escalate to the brain, which decides drive-forward vs leave-for-human.
-    if (session.activity === 'waiting_input') {
-        return {
-            kind: 'escalate',
-            reason: `parked on a question${session.awaitingReason ? ` (${session.awaitingReason})` : ''} — escalate to the brain`,
-        };
-    }
-    // Clearly complete — cheap skip, no LLM.
-    if (tailShowsCompletion(candidate)) {
-        return { kind: 'skip', reason: 'tail shows completion (done / finished / all set) — skip' };
-    }
-    // Clear promise-without-toolcall — cheap nudge, no LLM.
-    if (isLikelyTrulyBlocked(candidate)) {
-        return { kind: 'nudge', reason: 'stalled after announcing an action with no follow-through' };
-    }
-    // Ambiguous stall — let the brain judge rather than blindly skip.
-    return { kind: 'escalate', reason: 'ambiguous stall — escalate to the brain' };
-}
-/**
- * The smart brain. Resolves a `watchdog` workflow for the session's cwd
- * (project > user > system precedence, via resolveWorkflowRef) so a repo/user
- * override AND `model:` frontmatter come for free; when a workflow resolves it
- * runs `agents run watchdog --mode plan <prompt>`, else it falls back to the
- * improved built-in prompt via `agents run <agent> --mode plan <prompt>`. Plan
- * mode keeps the decider read-only. Best-effort and NON-deterministic: any
- * failure (decider unavailable, no verdict) returns a SAFE skip — a parked
- * question we cannot judge is left for the human, never blindly nudged.
- */
-export function makeDefaultSmartDecider(agent) {
-    return async (session, candidate) => {
-        const prompt = renderWatchdogPrompt([candidate]);
-        try {
-            const [{ resolveWorkflowRef }, { execFile }, { promisify }] = await Promise.all([
-                import('../workflows.js'),
-                import('child_process'),
-                import('util'),
-            ]);
-            const cwd = session.cwd || process.cwd();
-            const workflowPath = resolveWorkflowRef('watchdog', cwd);
-            // A resolved `watchdog` workflow runs by name so its WORKFLOW.md body + model
-            // frontmatter apply; otherwise the bare agent runs the built-in prompt.
-            const runTarget = workflowPath ? 'watchdog' : agent;
-            const execFileAsync = promisify(execFile);
-            const { stdout } = await execFileAsync('agents', ['run', runTarget, '--mode', 'plan', prompt], {
-                encoding: 'utf8',
-                maxBuffer: 4 * 1024 * 1024,
-                timeout: 120_000,
-            });
-            const decisions = parseWatchdogResponse(stdout);
-            const d = decisions.find((x) => x.terminalId === candidate.terminalId) ?? decisions[0];
-            if (!d)
-                return { nudge: false, reason: 'smart decider returned no verdict' };
-            return { nudge: d.action === 'nudge', reason: d.reason || `smart: ${d.action}`, text: d.text || undefined };
-        }
-        catch (err) {
-            return { nudge: false, reason: `smart decider unavailable: ${err instanceof Error ? err.message : String(err)}` };
-        }
-    };
-}
 /**
  * Pick the delivery mechanism. resolveAnswerRoute (answer-router.ts) chooses
  * mailbox vs resume vs refuse; resolveInjectTargetForSession (resolve.ts) supplies
@@ -349,7 +280,6 @@ export async function runWatchdogTick(opts = {}) {
     const lastActivityFor = opts.lastActivityFor ?? defaultLastActivity;
     const tailFor = opts.tailFor ?? ((s) => (s.sessionId ? readWatchdogTail(s.sessionId, s.kind, WATCHDOG_TAIL_LINES) : []));
     const policyFor = opts.policyFor ?? ((s) => (s.sessionId ? readPolicySentinel(dir, s.sessionId) : 'keep'));
-    const smartDecider = opts.smartDecider ?? makeDefaultSmartDecider(opts.smartAgent ?? 'claude');
     const openBlockFor = opts.openBlockFor ?? defaultOpenBlockFor;
     const injectFn = opts.injectFn ?? injectIntoTerminal;
     const publishBlockFn = opts.publishBlockFn ?? publishBlock;
@@ -401,6 +331,103 @@ export async function runWatchdogTick(opts = {}) {
         injectDryRun: opts.injectDryRun,
         logEvents, flags,
     };
+    // --- decide, once, with the AGENT ------------------------------------------
+    // Classify every session up front, collect the idle ones (with their task +
+    // tail), and hand the WHOLE idle set to the watchdog agent in ONE call
+    // (WD-GAP-1: the decider sees the fleet at once, not a lone tail). Tails are
+    // cached so the main loop below does not re-read them. Tests inject a
+    // per-candidate `smartDecider`; production runs one batched
+    // `agents run --mode plan` (watchdog-agent.ts). A session the agent returns no
+    // verdict for is a SAFE skip, never a blind nudge.
+    const tailCache = new Map();
+    const idleCandidates = [];
+    for (const session of sessions) {
+        const sid = session.sessionId;
+        if (!sid)
+            continue;
+        if (policyFor(session) === 'off')
+            continue;
+        const la = lastActivityFor(session);
+        if (la === undefined)
+            continue;
+        const st = classifyTerminal({
+            lastActivityMs: la, nowMs, lastNudgeMs: ledger[sid] ?? null, optedOut: false,
+            stallMs: thresholds.stallMs, cooldownMs: thresholds.cooldownMs, dormantMs: thresholds.dormantMs,
+        });
+        if (st.kind !== 'stalled')
+            continue;
+        const tail = tailFor(session);
+        tailCache.set(sid, tail);
+        // Rotate takes precedence over the nudge agent: a session with an in-flight
+        // rotate (or in the failed-rotate cooldown) or a HARD account-limit tail is
+        // owned by the rotate machine in the loop below — a capped account cannot be
+        // "Continue."d, so the agent must not judge it (and is never even consulted).
+        if (rotateEnabled) {
+            const inflight = readRotateState(dir, sid);
+            if (inflight && (isInflightPhase(inflight.phase) || (inflight.phase === 'failed' && (inflight.suppressUntilMs ?? 0) > nowMs)))
+                continue;
+            if (classifyTailForRotate(tail, nowMs).kind === 'rate_limited')
+                continue;
+        }
+        idleCandidates.push({
+            session,
+            candidate: {
+                terminalId: sid,
+                agentType: session.kind === 'codex' || session.kind === 'gemini' ? session.kind : 'claude',
+                tailLines: tail,
+                stalledForMs: st.stalledForMs,
+                task: session.topic ?? session.label ?? session.name,
+                cwd: session.cwd,
+            },
+        });
+    }
+    const decisionByTerminal = new Map();
+    if (idleCandidates.length > 0) {
+        if (opts.smartDecider) {
+            // Test seam: a synthetic per-candidate decider, called once per candidate. A
+            // skip with no explicit needsHuman defaults to surfacing it (same rule as the
+            // agent path) so an unfinished session is never silently abandoned.
+            for (const { session, candidate } of idleCandidates) {
+                const raw = await opts.smartDecider(session, candidate);
+                decisionByTerminal.set(candidate.terminalId, raw.nudge ? raw : { ...raw, needsHuman: raw.needsHuman ?? true });
+            }
+        }
+        else {
+            // Production: ONE batched agent call for every idle session this tick.
+            const decide = opts.agentDecider ?? makeWatchdogAgentDecider(opts.smartAgent ?? 'claude');
+            const verdicts = await decide(idleCandidates.map((e) => e.candidate));
+            // A decider outage (agent unavailable / timeout) returns no verdicts while
+            // idle sessions exist — surface it as an error so it is not an invisible
+            // no-op tick (the watchdog silently steering nothing is the failure mode
+            // this whole subsystem exists to prevent).
+            if (verdicts.size === 0) {
+                logEvents.push({
+                    ts: nowMs, kind: 'error',
+                    message: `watchdog agent returned no verdicts for ${idleCandidates.length} idle session(s) — decider unavailable this tick`,
+                });
+            }
+            for (const { candidate } of idleCandidates) {
+                const d = verdicts.get(candidate.terminalId);
+                decisionByTerminal.set(candidate.terminalId, d
+                    ? {
+                        nudge: d.action === 'nudge',
+                        reason: d.reason || `agent: ${d.action}`,
+                        text: d.text || undefined,
+                        // A skip with no explicit needsHuman defaults to surfacing it —
+                        // never silently abandon an unfinished session (the highest-risk state).
+                        needsHuman: d.action === 'skip' ? d.needsHuman ?? true : undefined,
+                    }
+                    // No verdict for this session — the agent couldn't decide (partial or a
+                    // decider outage). A NEUTRAL safe-skip: NOT "done" (needsHuman stays
+                    // undefined, so it is never logged as finished and the reminder never
+                    // fires), nothing booked, so the next tick re-evaluates it once the
+                    // decider is back. Marking it done (needsHuman:false) would let an
+                    // outage abandon every idle session; marking it needsHuman would spam a
+                    // "you're stuck" reminder into every idle terminal on any outage.
+                    : { nudge: false, reason: 'watchdog agent returned no verdict — retry next tick' });
+            }
+        }
+    }
     for (const session of sessions) {
         const policy = policyFor(session);
         const base = {
@@ -464,8 +491,8 @@ export async function runWatchdogTick(opts = {}) {
             continue;
         }
         base.stalledForMs = status.stalledForMs;
-        // Stalled — read the tail and decide.
-        const tailLines = tailFor(session);
+        // Stalled — reuse the tail the pre-pass already read for the agent.
+        const tailLines = tailCache.get(session.sessionId) ?? tailFor(session);
         const candidate = {
             terminalId: session.sessionId,
             agentType: (session.kind === 'codex' || session.kind === 'gemini' ? session.kind : 'claude'),
@@ -653,27 +680,10 @@ export async function runWatchdogTick(opts = {}) {
                 continue;
             }
         }
-        // The brain. The cheap deterministic pre-filter resolves the obvious cases;
-        // parked-on-question and ambiguous stalls ESCALATE to the smart brain. `smart`
-        // forces every stalled candidate through the brain.
-        let decision;
-        if (opts.smart) {
-            const d = await smartDecider(session, candidate);
-            // Mark needsHuman when the brain explicitly concluded "leave for human".
-            decision = d.nudge ? d : { ...d, needsHuman: true };
-        }
-        else {
-            const det = deterministicDecision(session, candidate);
-            if (det.kind === 'escalate') {
-                const d = await smartDecider(session, candidate);
-                // Mark needsHuman when the brain escalation path concluded "leave for human".
-                decision = d.nudge ? d : { ...d, needsHuman: true };
-            }
-            else {
-                // Cheap deterministic path — completion or clear stall. Never "needs human".
-                decision = { nudge: det.kind === 'nudge', reason: det.reason };
-            }
-        }
+        // The decision was made up front by the watchdog agent over the whole idle
+        // set (see the pre-pass). A session with no verdict is a safe skip.
+        const decision = decisionByTerminal.get(session.sessionId) ??
+            { nudge: false, reason: 'not evaluated by the watchdog agent', needsHuman: false };
         const chosenText = decision.text ?? nudgeText;
         // Log the decision for the Factory watchdog card.
         const summary = summarizeWatchdogTail(tailLines, candidate.agentType);
@@ -796,34 +806,37 @@ export async function runWatchdogTick(opts = {}) {
         }
         // Deliver. injectDryRun exercises the path without a real side effect: inject
         // still calls injectFn (which honors dryRun), mailbox/resume are short-circuited.
+        // `confirmed` distinguishes a delivery we KNOW reached the agent (tmux/iterm/pty,
+        // mailbox, resume) from one merely dispatched (vscodium's fire-and-forget
+        // --open-url). Only a CONFIRMED delivery is booked as a landed nudge.
         let delivered;
         if (plan.via === 'inject') {
             try {
                 const r = await injectFn(plan.target, chosenText, { dryRun: opts.injectDryRun });
-                delivered = { ok: r.ok, error: r.error };
+                delivered = { ok: r.ok, confirmed: r.confirmed, error: r.error };
             }
             catch (err) {
-                delivered = { ok: false, error: err instanceof Error ? err.message : String(err) };
+                delivered = { ok: false, confirmed: false, error: err instanceof Error ? err.message : String(err) };
             }
         }
         else if (plan.via === 'mailbox') {
             if (opts.injectDryRun) {
-                delivered = { ok: true };
+                delivered = { ok: true, confirmed: true };
             }
             else {
                 try {
                     deliverViaMailbox(plan.mailboxId, chosenText, block);
-                    delivered = { ok: true };
+                    delivered = { ok: true, confirmed: true };
                 }
                 catch (err) {
-                    delivered = { ok: false, error: err instanceof Error ? err.message : String(err) };
+                    delivered = { ok: false, confirmed: false, error: err instanceof Error ? err.message : String(err) };
                 }
             }
         }
         else {
-            delivered = opts.injectDryRun ? { ok: true } : await deliverViaResume(session, chosenText);
+            delivered = opts.injectDryRun ? { ok: true, confirmed: true } : { ...(await deliverViaResume(session, chosenText)), confirmed: true };
         }
-        if (delivered.ok) {
+        if (delivered.ok && delivered.confirmed) {
             ledgerUpdates[session.sessionId] = nowMs; // start the cooldown clock
             logEvents.push({
                 ts: nowMs, kind: 'nudge', terminalId: session.sessionId, agentType: candidate.agentType,
@@ -835,6 +848,24 @@ export async function runWatchdogTick(opts = {}) {
                 nudgeText: chosenText,
             });
         }
+        else if (delivered.ok && !delivered.confirmed) {
+            // Dispatched but UNCONFIRMED (vscodium --open-url handed off, but the ext may
+            // have no-op'd the verb). Do NOT claim it landed — record `undelivered` in
+            // history so the phantom-nudge is visible. Still start the cooldown so a
+            // possibly-working ext session is not re-nudged every tick; the honest
+            // `undelivered` signal tells the operator to ship the swarm-ext ack.
+            ledgerUpdates[session.sessionId] = nowMs;
+            logEvents.push({
+                ts: nowMs, kind: 'undelivered', terminalId: session.sessionId, agentType: candidate.agentType,
+                message: `dispatched via ${viaLabel(plan)} but UNCONFIRMED (needs swarm-ext ack)`,
+                reason: decision.reason, nudgeText: chosenText,
+            });
+            outcomes.push({
+                ...base, decision: 'skip', addressable, rail, via: plan.via, injected: false,
+                reason: `nudge dispatched via ${viaLabel(plan)} but delivery is UNCONFIRMED (swarm-ext ack pending)`,
+                nudgeText: chosenText,
+            });
+        }
         else {
             outcomes.push({
                 ...base, decision: 'skip', addressable, rail, via: plan.via, injected: false,

package/dist/lib/watchdog/service.d.ts

@@ -3,7 +3,6 @@ import { type WatchdogThresholds, type WatchdogTickResult } from './runner.js';
 export interface WatchdogPassOptions {
     nudge: boolean;
     nudgeText?: string;
-    smart?: boolean;
     smartAgent?: string;
     thresholds?: WatchdogThresholds;
     allowGhosttyFocus?: boolean;

package/dist/lib/watchdog/service.js

@@ -26,7 +26,6 @@ export async function runWatchdogPass(opts) {
     const result = await runWatchdogTick({
         nudge: opts.nudge,
         nudgeText: opts.nudgeText,
-        smart: opts.smart,
         smartAgent: opts.smartAgent,
         thresholds: opts.thresholds,
         allowGhosttyFocus: opts.allowGhosttyFocus,

package/dist/lib/watchdog/watchdog-agent.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The watchdog AGENT — the whole decider, in ONE call per tick.
+ *
+ * The watchdog does not use a heuristic script to guess idle-vs-unfinished. It
+ * hands every idle session's task + tail to an agent (via `agents run <target>
+ * --mode plan`, read-only) and asks it, for each, whether it is idle-but-unfinished
+ * (→ nudge) or idle-and-done / needs-human (→ skip). The whole idle set goes in ONE
+ * invocation, so the cost is one bounded plan-mode call per tick regardless of how
+ * many sessions are idle — not one agent per session, and only when something is
+ * actually idle (the caller does not invoke this with an empty list).
+ *
+ * A resolved `watchdog` workflow (repo > user > system, via resolveWorkflowRef)
+ * runs by name so its WORKFLOW.md body + `model:` frontmatter apply; otherwise the
+ * bare agent runs the built-in WATCHDOG_SYSTEM_PROMPT. Best-effort: any failure
+ * (agent unavailable, timeout, no verdict) yields an empty map, and the caller
+ * treats an unlisted terminal as a SAFE skip — never a blind nudge.
+ */
+import { type WatchdogCandidate, type Decision } from './watchdog.js';
+/** Judge every idle candidate at once; returns decisions keyed by terminalId. */
+export type WatchdogAgentDecider = (candidates: WatchdogCandidate[]) => Promise<Map<string, Decision>>;
+/**
+ * Runs the agent once and returns its raw stdout. Injectable so a test can assert
+ * the ONE-call-per-tick property and the assembled prompt without shelling out.
+ * `runTarget` is the resolved `agents run` target (a `watchdog` workflow or the
+ * bare agent id).
+ */
+export type WatchdogAgentRunner = (runTarget: string, prompt: string) => Promise<string>;
+/**
+ * The default agent decider. `agent` is the harness the built-in prompt runs as
+ * (default 'claude'); `workflowCwd` is where a `watchdog` workflow override is
+ * resolved from (the daemon's cwd — the batch spans many projects, so there is no
+ * single per-session cwd to key on); `run` is the injectable subprocess seam
+ * (tests pass a synthetic one). The whole idle set goes to the runner in ONE call.
+ */
+export declare function makeWatchdogAgentDecider(agent: string, opts?: {
+    workflowCwd?: string;
+    run?: WatchdogAgentRunner;
+}): WatchdogAgentDecider;

package/dist/lib/watchdog/watchdog-agent.js

@@ -0,0 +1,59 @@
+/**
+ * The watchdog AGENT — the whole decider, in ONE call per tick.
+ *
+ * The watchdog does not use a heuristic script to guess idle-vs-unfinished. It
+ * hands every idle session's task + tail to an agent (via `agents run <target>
+ * --mode plan`, read-only) and asks it, for each, whether it is idle-but-unfinished
+ * (→ nudge) or idle-and-done / needs-human (→ skip). The whole idle set goes in ONE
+ * invocation, so the cost is one bounded plan-mode call per tick regardless of how
+ * many sessions are idle — not one agent per session, and only when something is
+ * actually idle (the caller does not invoke this with an empty list).
+ *
+ * A resolved `watchdog` workflow (repo > user > system, via resolveWorkflowRef)
+ * runs by name so its WORKFLOW.md body + `model:` frontmatter apply; otherwise the
+ * bare agent runs the built-in WATCHDOG_SYSTEM_PROMPT. Best-effort: any failure
+ * (agent unavailable, timeout, no verdict) yields an empty map, and the caller
+ * treats an unlisted terminal as a SAFE skip — never a blind nudge.
+ */
+import { renderWatchdogPrompt, parseWatchdogResponse } from './watchdog.js';
+/** The real runner: one `agents run <target> --mode plan <prompt>` subprocess. */
+async function defaultAgentRunner(runTarget, prompt) {
+    const [{ execFile }, { promisify }] = await Promise.all([import('child_process'), import('util')]);
+    const execFileAsync = promisify(execFile);
+    const { stdout } = await execFileAsync('agents', ['run', runTarget, '--mode', 'plan', prompt], {
+        encoding: 'utf8',
+        maxBuffer: 4 * 1024 * 1024,
+        timeout: 120_000,
+    });
+    return stdout;
+}
+/**
+ * The default agent decider. `agent` is the harness the built-in prompt runs as
+ * (default 'claude'); `workflowCwd` is where a `watchdog` workflow override is
+ * resolved from (the daemon's cwd — the batch spans many projects, so there is no
+ * single per-session cwd to key on); `run` is the injectable subprocess seam
+ * (tests pass a synthetic one). The whole idle set goes to the runner in ONE call.
+ */
+export function makeWatchdogAgentDecider(agent, opts = {}) {
+    return async (candidates) => {
+        const result = new Map();
+        if (candidates.length === 0)
+            return result;
+        try {
+            const { resolveWorkflowRef } = await import('../workflows.js');
+            const cwd = opts.workflowCwd || process.cwd();
+            const workflowPath = resolveWorkflowRef('watchdog', cwd);
+            const runTarget = workflowPath ? 'watchdog' : agent;
+            const prompt = renderWatchdogPrompt(candidates);
+            const run = opts.run ?? defaultAgentRunner;
+            const stdout = await run(runTarget, prompt);
+            for (const d of parseWatchdogResponse(stdout))
+                result.set(d.terminalId, d);
+        }
+        catch {
+            // Agent unavailable / timed out — return what we have (possibly empty); the
+            // caller safe-skips any terminal with no verdict. Never a blind nudge.
+        }
+        return result;
+    };
+}

package/dist/lib/watchdog/watchdog.d.ts

@@ -3,12 +3,22 @@ export interface WatchdogCandidate {
     agentType: 'claude' | 'codex' | 'gemini';
     tailLines: string[];
     stalledForMs: number;
+    /** The originating task / first prompt / topic — so the agent can judge "was given a task but hasn't finished it". */
+    task?: string;
+    /** Working directory of the session, for context. */
+    cwd?: string;
 }
 export interface Decision {
     terminalId: string;
     action: 'nudge' | 'skip';
     text: string;
     reason: string;
+    /**
+     * Set by the agent on a SKIP to distinguish "genuinely needs the human"
+     * (true → surface it) from "the task is actually done" (false/absent → leave
+     * it alone, do not poke). `done` is a distinct terminal state from `idle`.
+     */
+    needsHuman?: boolean;
 }
 export type StallStatus = {
     kind: 'active';
@@ -33,8 +43,7 @@ export interface ClassifyInput {
     dormantMs: number;
 }
 export declare function classifyTerminal(input: ClassifyInput): StallStatus;
-export declare const WATCHDOG_SYSTEM_PROMPT = "You are the watchdog for AI coding agents running in terminals. Your one job is to get\nIDLE agents moving to completion: each agent has a goal and is expected to DRIVE TO\nCOMPLETION end-to-end, but the terminals below have gone idle. Read each one's goal and\nWHY it stopped, then decide NUDGE (send a message that unsticks it and drives it to\nfinish) or SKIP (it genuinely needs the human).\n\nRead the transcript before judging \u2014 an agent that already reached a decision needs \"do\nit,\" not \"decide.\"\n\nNUDGE when the agent went idle and could keep going on its own:\n- It asked permission for an obvious or already-authorized next step\n  (\"should I proceed?\", \"want me to continue?\", \"shall I run the tests?\").\n- It asked a question it could answer itself from the available context or a\n  reasonable default, or by using a tool it already has.\n- It announced an action (\"I'll run X\", \"let me write Y\") but no tool call followed.\n- It already decided what to do, then stalled without doing it.\n- It paused with the task incomplete and no real blocker.\n\nThe nudge text MUST carry context, not shove:\n- Restate the goal and reference the conclusion the agent ALREADY reached.\n- Give ONE concrete next step \u2014 the specific action, the sensible default, or a TOOL it\n  forgot it has (e.g. \"agents computer\" to drive the Mac, \"agents browser\" for the web,\n  \"agents ssh <mac> \\\"agents computer \u2026\\\"\" to drive a Mac from another box).\n- Split the ask: drive the reversible, goal-advancing part now; flag only a genuinely\n  disruptive sub-step for the human.\n- Tell it to use best judgment and finish end-to-end WITHOUT asking again.\n- Imperative, 1-2 sentences, no emojis, under 240 characters.\n\nSKIP when the agent genuinely needs the human (these belong in the user's feed, not a\nnudge):\n- Credentials, auth, login, 2FA, or biometric.\n- An irreversible or outward-facing action that needs sign-off (force-push, delete\n  prod data, publish/release, spend money, send an external message) \u2014 UNLESS the House\n  Rules below authorize it.\n- A real product or intent decision with genuine ambiguity (not a trivial default).\n- The task is actually complete.\n- You cannot tell what the agent is doing.\n\nRespond with ONLY a JSON array (no prose, no code fence):\n[{\"terminalId\":\"<id>\",\"action\":\"nudge\"|\"skip\",\"text\":\"<message or empty>\",\"reason\":\"<brief>\"}]";
+export declare const WATCHDOG_SYSTEM_PROMPT = "You are the watchdog for AI coding agents running in terminals. You are given the idle\nsessions on this machine \u2014 each with its originating TASK, how long it has been idle, and\nthe tail of its transcript. Your one job is to tell, for each one, whether it is\nIDLE-BUT-UNFINISHED (it was given a task, went quiet, and has NOT finished or handed it\noff) or IDLE-AND-DONE (it finished, or it genuinely needs the human). Idle-but-unfinished\nis the dangerous state \u2014 the work is most likely to be silently abandoned \u2014 so those get a\nNUDGE that drives them to finish. Everything else is a SKIP.\n\nRead each transcript before judging \u2014 an agent that already reached a decision needs \"do\nit,\" not \"decide.\" Judge from the task + tail, not from keywords.\n\nNUDGE when the agent went idle and could keep going on its own:\n- It asked permission for an obvious or already-authorized next step\n  (\"should I proceed?\", \"want me to continue?\", \"shall I run the tests?\").\n- It asked a question it could answer itself from the available context or a\n  reasonable default, or by using a tool it already has.\n- It announced an action (\"I'll run X\", \"let me write Y\") but no tool call followed.\n- It already decided what to do, then stalled without doing it.\n- It paused with the task incomplete and no real blocker.\n\nThe nudge text MUST carry context, not shove:\n- Restate the goal and reference the conclusion the agent ALREADY reached.\n- Give ONE concrete next step \u2014 the specific action, the sensible default, or a TOOL it\n  forgot it has (e.g. \"agents computer\" to drive the Mac, \"agents browser\" for the web,\n  \"agents ssh <mac> \\\"agents computer \u2026\\\"\" to drive a Mac from another box).\n- Split the ask: drive the reversible, goal-advancing part now; flag only a genuinely\n  disruptive sub-step for the human.\n- Tell it to use best judgment and finish end-to-end WITHOUT asking again.\n- Imperative, 1-2 sentences, no emojis, under 240 characters.\n\nSKIP in two distinct cases \u2014 mark which with \"needsHuman\":\n- needsHuman=true \u2014 the agent is genuinely blocked on a human (these belong in the user's\n  feed): credentials, auth, login, 2FA, or biometric; an irreversible or outward-facing\n  action needing sign-off (force-push, delete prod data, publish/release, spend money,\n  send an external message) UNLESS the House Rules below authorize it; a real product or\n  intent decision with genuine ambiguity (not a trivial default); or you cannot tell what\n  the agent is doing.\n- needsHuman=false \u2014 the task is actually complete (idle-and-done). Leave it alone; do NOT\n  poke a finished session.\n\nRespond with ONLY a JSON array (no prose, no code fence). Include \"needsHuman\" on every\nskip:\n[{\"terminalId\":\"<id>\",\"action\":\"nudge\"|\"skip\",\"text\":\"<message or empty>\",\"reason\":\"<brief>\",\"needsHuman\":true|false}]";
 export declare function composePromptWithPlaybook(basePrompt: string, playbook: string): string;
 export declare function renderWatchdogPrompt(candidates: WatchdogCandidate[], playbook?: string): string;
 export declare function parseWatchdogResponse(stdout: string): Decision[];
-export declare function isLikelyTrulyBlocked(candidate: WatchdogCandidate): boolean;