@phnx-labs/agents-cli 1.20.73 → 1.20.76

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

@@ -0,0 +1,44 @@
+/**
+ * The watchdog, expressed as a routine.
+ *
+ * The always-on watchdog is not a bespoke subsystem — it is a plain `command`
+ * routine the daemon's existing scheduler fires: `agents watchdog --nudge`, once
+ * every couple of minutes. Enabling / disabling the watchdog is enabling /
+ * disabling that routine, so there is ONE durable, inspectable concept
+ * (`agents routines list` shows it; the scheduler catches it up if the daemon was
+ * down) instead of a private sentinel file and a hand-rolled `--watch` loop.
+ *
+ * A `command` routine — not `agent`/`workflow` — because the tick is deterministic
+ * housekeeping: no LLM, no auth, no sandbox. Each fire runs ONE bounded tick (the
+ * cron is the loop), so the daemon's per-fire model fits without a long-lived
+ * process.
+ */
+import { type JobConfig } from '../routines.js';
+/** The routine name. `agents routines list` / `readJob` key on this. */
+export declare const WATCHDOG_ROUTINE_NAME = "watchdog";
+/**
+ * Fire every 2 minutes. Mirrors the extension's 120s tick, and is well inside the
+ * 5m stall threshold and 20m nudge cooldown, so a stall is noticed promptly
+ * without the daemon spawning a tick more often than the cooldown can matter.
+ */
+export declare const WATCHDOG_ROUTINE_SCHEDULE = "*/2 * * * *";
+/** The plain shell each fire runs: one bounded, deterministic nudge tick. */
+export declare const WATCHDOG_ROUTINE_COMMAND = "agents watchdog --nudge";
+/**
+ * Build the watchdog routine config. Pure — touches no disk. `mode`/`effort`/
+ * `timeout` are required by JobConfig but ignored for `command` routines;
+ * writeJob() drops the default ('auto'/'10m') values so the on-disk file stays
+ * to the point (name + schedule + command + enabled).
+ */
+export declare function buildWatchdogRoutine(enabled: boolean): JobConfig;
+/** Is the watchdog routine present on disk (user or system layer)? */
+export declare function watchdogRoutineExists(): boolean;
+/** Is the watchdog routine present AND enabled? */
+export declare function isWatchdogRoutineEnabled(): boolean;
+/**
+ * Ensure the watchdog routine exists with the requested enabled state, preserving
+ * any user edits. Absent → create it; present → only flip `enabled` (never clobber
+ * a schedule or command the user tuned). Idempotent: calling it twice with the
+ * same state is a no-op after the first.
+ */
+export declare function ensureWatchdogRoutine(enabled: boolean): void;

package/dist/lib/watchdog/routine.js

@@ -0,0 +1,69 @@
+/**
+ * The watchdog, expressed as a routine.
+ *
+ * The always-on watchdog is not a bespoke subsystem — it is a plain `command`
+ * routine the daemon's existing scheduler fires: `agents watchdog --nudge`, once
+ * every couple of minutes. Enabling / disabling the watchdog is enabling /
+ * disabling that routine, so there is ONE durable, inspectable concept
+ * (`agents routines list` shows it; the scheduler catches it up if the daemon was
+ * down) instead of a private sentinel file and a hand-rolled `--watch` loop.
+ *
+ * A `command` routine — not `agent`/`workflow` — because the tick is deterministic
+ * housekeeping: no LLM, no auth, no sandbox. Each fire runs ONE bounded tick (the
+ * cron is the loop), so the daemon's per-fire model fits without a long-lived
+ * process.
+ */
+import { readJob, writeJob, setJobEnabled } from '../routines.js';
+/** The routine name. `agents routines list` / `readJob` key on this. */
+export const WATCHDOG_ROUTINE_NAME = 'watchdog';
+/**
+ * Fire every 2 minutes. Mirrors the extension's 120s tick, and is well inside the
+ * 5m stall threshold and 20m nudge cooldown, so a stall is noticed promptly
+ * without the daemon spawning a tick more often than the cooldown can matter.
+ */
+export const WATCHDOG_ROUTINE_SCHEDULE = '*/2 * * * *';
+/** The plain shell each fire runs: one bounded, deterministic nudge tick. */
+export const WATCHDOG_ROUTINE_COMMAND = 'agents watchdog --nudge';
+/**
+ * Build the watchdog routine config. Pure — touches no disk. `mode`/`effort`/
+ * `timeout` are required by JobConfig but ignored for `command` routines;
+ * writeJob() drops the default ('auto'/'10m') values so the on-disk file stays
+ * to the point (name + schedule + command + enabled).
+ */
+export function buildWatchdogRoutine(enabled) {
+    return {
+        name: WATCHDOG_ROUTINE_NAME,
+        schedule: WATCHDOG_ROUTINE_SCHEDULE,
+        command: WATCHDOG_ROUTINE_COMMAND,
+        enabled,
+        mode: 'auto',
+        effort: 'auto',
+        timeout: '10m',
+        prompt: '',
+    };
+}
+/** Is the watchdog routine present on disk (user or system layer)? */
+export function watchdogRoutineExists() {
+    return readJob(WATCHDOG_ROUTINE_NAME) !== null;
+}
+/** Is the watchdog routine present AND enabled? */
+export function isWatchdogRoutineEnabled() {
+    const job = readJob(WATCHDOG_ROUTINE_NAME);
+    return job !== null && job.enabled === true;
+}
+/**
+ * Ensure the watchdog routine exists with the requested enabled state, preserving
+ * any user edits. Absent → create it; present → only flip `enabled` (never clobber
+ * a schedule or command the user tuned). Idempotent: calling it twice with the
+ * same state is a no-op after the first.
+ */
+export function ensureWatchdogRoutine(enabled) {
+    const existing = readJob(WATCHDOG_ROUTINE_NAME);
+    if (existing === null) {
+        writeJob(buildWatchdogRoutine(enabled));
+        return;
+    }
+    if (existing.enabled !== enabled) {
+        setJobEnabled(WATCHDOG_ROUTINE_NAME, enabled);
+    }
+}

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

@@ -30,7 +30,9 @@
  */
 import type { ActiveSession } from '../session/active.js';
 import { type InjectRail } from '../terminal/resolve.js';
-import { type StallStatus } from './watchdog.js';
+import { type InjectResult, type InjectTarget } from '../terminal/inject.js';
+import { type StallStatus, type WatchdogCandidate } from './watchdog.js';
+import { type OpenBlock } from '../feed.js';
 /** Per-session policy sentinel. `keep` is the default (watchdog may nudge). */
 export type WatchdogPolicy = 'off' | 'keep' | 'handsoff';
 /** Stall / cooldown / dormant thresholds (ms). Defaults mirror read.ts. */
@@ -48,12 +50,15 @@ export interface WatchdogTickOptions {
     /** Nudge text delivered into the terminal. Default "Continue." */
     nudgeText?: string;
     /**
-     * Use the LLM decider (`agents run`) to decide + choose nudge text instead of
-     * the deterministic promise-without-toolcall path. Default false so ticks are
-     * reproducible. Best-effort: a decider failure falls back to skip.
+     * Force the LLM decider (`agents run`) on EVERY stalled candidate instead of the
+     * hybrid path. Default false. Even when false the tick still ESCALATES the
+     * judgment-heavy cases (parked-on-question, ambiguous stalls) to the smart brain
+     * — `smart: true` additionally routes the obvious promise-without-toolcall
+     * nudges through it. Non-reproducible; the deterministic pre-filter is the
+     * reproducible default.
      */
     smart?: boolean;
-    /** Agent the smart decider runs as. Default 'claude'. */
+    /** Agent the smart decider runs as (and the built-in fallback prompt). Default 'claude'. */
     smartAgent?: string;
     /** Threshold overrides. Missing fields fall back to DEFAULT_THRESHOLDS. */
     thresholds?: Partial<WatchdogThresholds>;
@@ -73,7 +78,25 @@ export interface WatchdogTickOptions {
     tailFor?: (s: ActiveSession) => string[];
     /** Per-session policy. Default = the on-disk sentinel. */
     policyFor?: (s: ActiveSession) => WatchdogPolicy;
+    /**
+     * The smart brain: given a stalled candidate, decide drive-forward vs
+     * leave-for-human and craft the message. Default resolves a `watchdog` workflow
+     * (repo/user override + `model:` frontmatter) and, failing that, the improved
+     * built-in prompt — both via `agents run … --mode plan`. Tests inject a
+     * synthetic decider so escalation is exercised without shelling out.
+     */
+    smartDecider?: SmartDecider;
+    /** Open feed block for a session (parked-on-question detection). Default reads the feed. */
+    openBlockFor?: (s: ActiveSession) => OpenBlock | null;
+    /** Inject primitive. Default injectIntoTerminal — tests capture the resolved target. */
+    injectFn?: (target: InjectTarget, text: string, opts: {
+        dryRun?: boolean;
+    }) => Promise<InjectResult>;
+    /** Override the canonical watchdog.log path (tests point at a tmp file). */
+    logPath?: string;
 }
+/** The smart brain seam: a stalled candidate in, a nudge decision out. */
+export type SmartDecider = (session: ActiveSession, candidate: WatchdogCandidate) => Promise<NudgeDecision>;
 /** What the tick decided for a single session — the row `--json` / the tray reads. */
 export interface SessionOutcome {
     sessionId?: string;
@@ -88,15 +111,19 @@ export interface SessionOutcome {
     policy: WatchdogPolicy;
     decision: 'nudge' | 'skip';
     reason: string;
-    /** The resolved rail, when addressable. */
+    /** The resolved rail, when delivered by injecting into a terminal split. */
     rail?: InjectRail;
+    /** How the nudge was (or would be) delivered: inject | mailbox | resume. */
+    via?: NudgeVia;
     /** True when resolveInjectTarget said addressable (only meaningful once we'd nudge). */
     addressable?: boolean;
-    /** True when a nudge was actually delivered this tick. */
+    /** True when a nudge was actually delivered this tick (any mechanism). */
     injected?: boolean;
     /** The text that was (or would be) delivered. */
     nudgeText?: string;
 }
+/** Delivery mechanism the answer-router picked for a nudge. */
+export type NudgeVia = 'inject' | 'mailbox' | 'resume';
 export interface WatchdogTickResult {
     atMs: number;
     /** Whether this tick was allowed to inject (opts.nudge). */
@@ -118,6 +145,23 @@ export interface WatchdogTickResult {
 export declare function readPolicySentinel(dir: string, sessionId: string): WatchdogPolicy;
 /** Write a per-session policy sentinel (used by the CLI `agents watchdog policy`). */
 export declare function writePolicySentinel(dir: string, sessionId: string, policy: WatchdogPolicy): void;
+/** A decide result shared by the deterministic and smart paths. `text` overrides the default nudge text. */
+export interface NudgeDecision {
+    nudge: boolean;
+    reason: string;
+    text?: string;
+}
+/**
+ * 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 declare function makeDefaultSmartDecider(agent: string): SmartDecider;
 /**
  * Run ONE watchdog pass. Returns a structured outcome per live session; injects
  * only when `opts.nudge` is set AND the safety gate says addressable AND policy

package/dist/lib/watchdog/runner.js

@@ -36,6 +36,13 @@ import { injectIntoTerminal } from '../terminal/inject.js';
 import { classifyTerminal, isLikelyTrulyBlocked, renderWatchdogPrompt, parseWatchdogResponse, } from './watchdog.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';
+import { resolveAnswerRoute, isOpenQuestionBlock } from '../answer-router.js';
+import { enqueue, mailboxDir } from '../mailbox.js';
+import { mailboxIdForActiveSession } from '../mailbox-target.js';
+import { readBlock, blockIdForSession } from '../feed.js';
+import { summarizeWatchdogTail } from './watchdogTail.js';
+import { appendWatchdogEvents } from './log.js';
 export const DEFAULT_THRESHOLDS = {
     stallMs: WATCHDOG_STALL_MS,
     cooldownMs: WATCHDOG_COOLDOWN_MS,
@@ -103,12 +110,10 @@ function defaultLastActivity(s) {
     return s.startedAtMs;
 }
 /**
- * Minimal local mirror of COMPLETION_HINTS in watchdog.ts:42-47. We cannot lean
- * on isLikelyTrulyBlocked to screen completions out: its FORCE_REVIEW_STALL_MS
- * short-circuit (watchdog.ts:171 — `stalledForMs >= 15m` returns true) fires
- * BEFORE its own COMPLETION_HINTS check (watchdog.ts:176), so a session idle
- * 15m-60m whose tail says "done"/"finished" would be reported as blocked. Keep
- * this list in sync with the core.
+ * 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) {
@@ -118,45 +123,130 @@ function tailShowsCompletion(candidate) {
     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 { nudge: false, reason: `waiting on user${session.awaitingReason ? ` (${session.awaitingReason})` : ''}` };
+        return {
+            kind: 'escalate',
+            reason: `parked on a question${session.awaitingReason ? ` (${session.awaitingReason})` : ''} — escalate to the brain`,
+        };
     }
-    // Completion is checked EXPLICITLY here — never nudge a finished session, even
-    // past the 15m force-review window where isLikelyTrulyBlocked would return true
-    // before reaching its completion check (see COMPLETION_HINTS note above).
+    // Clearly complete — cheap skip, no LLM.
     if (tailShowsCompletion(candidate)) {
-        return { nudge: false, reason: 'tail shows completion (done / finished / all set) — skip regardless of stall age' };
+        return { kind: 'skip', reason: 'tail shows completion (done / finished / all set) — skip' };
     }
+    // Clear promise-without-toolcall — cheap nudge, no LLM.
     if (isLikelyTrulyBlocked(candidate)) {
-        return { nudge: true, reason: 'stalled after announcing an action with no follow-through' };
+        return { kind: 'nudge', reason: 'stalled after announcing an action with no follow-through' };
     }
-    return { nudge: false, reason: 'no promise-without-toolcall signal in tail (completion / question / unclear)' };
+    // Ambiguous stall — let the brain judge rather than blindly skip.
+    return { kind: 'escalate', reason: 'ambiguous stall — escalate to the brain' };
 }
 /**
- * The optional LLM decider. Shells out to `agents run <agent>` with the watchdog
- * prompt and parses its JSON verdict. Best-effort and NON-deterministic — the
- * default path is deterministicDecision. Isolated here so the tick stays pure
- * over its seams; the command layer opts in with --smart.
+ * 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.
  */
-async function smartDecision(candidate, agent) {
-    const prompt = renderWatchdogPrompt([candidate]);
+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
+ * the precise inject target — CRUCIALLY it handles the vscodium rail that the
+ * answer-router's own resolver cannot, so an IDE-terminal (VS Codium / Cursor /
+ * VS Code) session parked on a question is injected into its exact terminal rather
+ * than being downgraded to resume/refuse. When a precise rail exists it wins
+ * (that includes a stalled non-parked agent, so the v1 terminal-inject path is
+ * preserved and no nudge is stranded in a mailbox the agent will never poll).
+ */
+function planDelivery(session, chosenText, block, allowGhosttyFocus) {
+    const sessionId = session.sessionId ?? '';
+    const mailboxId = mailboxIdForActiveSession(session) ?? sessionId;
+    const resolution = resolveInjectTargetForSession(session, { allowGhosttyFocus });
+    const route = resolveAnswerRoute({ mailboxId, answer: chosenText, session, block });
+    // A precise split (tmux / iTerm / vscodium / pty) is the authoritative target.
+    if (resolution.addressable) {
+        return { via: 'inject', rail: resolution.rail, target: resolution.target };
+    }
+    // No precise rail: honor the answer-router's parked-agent decision.
+    if (route.kind === 'resume')
+        return { via: 'resume' };
+    // Mailbox is correct ONLY for a still-looping agent that has an OPEN question
+    // block — it is seen at the next tool call. A stalled agent that simply stopped
+    // (no open block) would never poll the mailbox, so it is flagged instead of
+    // silently dropping a nudge into a spool it will never read.
+    if (route.kind === 'mailbox' && isOpenQuestionBlock(block))
+        return { via: 'mailbox', mailboxId };
+    return { via: 'refuse', reason: route.kind === 'refuse' ? route.reason : resolution.reason };
+}
+/** Default open-block reader — the same lookup `agents message` uses. */
+function defaultOpenBlockFor(session) {
+    const id = mailboxIdForActiveSession(session) ?? session.sessionId;
+    if (!id)
+        return null;
+    const direct = readBlock(blockIdForSession(id));
+    if (direct && direct.mailboxId === id)
+        return direct;
+    return null;
+}
+/** Enqueue a nudge into a session's mailbox (running agent, seen at next tool call). */
+function deliverViaMailbox(mailboxId, text, block) {
+    enqueue(mailboxDir(mailboxId), { to: mailboxId, text, from: 'watchdog', blockId: block?.blockId });
+}
+/** Re-enter a parked headless agent with the nudge as its next user turn. */
+async function deliverViaResume(session, text) {
+    const sid = session.sessionId;
+    if (!sid)
+        return { ok: false, error: 'no session id to resume' };
     try {
-        const { execFile } = await import('child_process');
-        const { promisify } = await import('util');
-        const execFileAsync = promisify(execFile);
-        const { stdout } = await execFileAsync('agents', ['run', agent, '--mode', 'plan', prompt], {
-            encoding: 'utf8',
-            maxBuffer: 4 * 1024 * 1024,
-            timeout: 120_000,
+        const [{ getAgentsInvocation }, { spawn }] = await Promise.all([
+            import('../daemon.js'),
+            import('child_process'),
+        ]);
+        const inv = getAgentsInvocation(['run', session.kind, '--resume', sid, '--', text]);
+        const code = await new Promise((resolve) => {
+            const child = spawn(inv.command, inv.args, { stdio: 'ignore', env: process.env, detached: false });
+            child.on('exit', (c) => resolve(c ?? 1));
+            child.on('error', () => resolve(1));
         });
-        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 };
+        return code === 0 ? { ok: true } : { ok: false, error: `resume exited ${code}` };
     }
     catch (err) {
-        return { nudge: false, reason: `smart decider unavailable: ${err instanceof Error ? err.message : String(err)}` };
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
     }
 }
 // --- the tick ---------------------------------------------------------------
@@ -174,10 +264,18 @@ 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 sessions = opts.sessions ?? (await getActiveSessions());
     const ledger = readNudgeLedger(dir);
+    // Cooldown timestamps this tick decided to (re)start — merged into the ledger
+    // under a lock at the end so a concurrent tick's updates are never lost.
+    const ledgerUpdates = {};
     const flags = {};
     const outcomes = [];
+    const logEvents = [];
+    const viaLabel = (plan) => plan.via === 'inject' ? `inject (${plan.rail})` : plan.via;
     for (const session of sessions) {
         const policy = policyFor(session);
         const base = {
@@ -236,39 +334,66 @@ export async function runWatchdogTick(opts = {}) {
             tailLines,
             stalledForMs: status.stalledForMs,
         };
-        const decision = opts.smart
-            ? await smartDecision(candidate, opts.smartAgent ?? 'claude')
-            : deterministicDecision(session, candidate);
+        // 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) {
+            decision = await smartDecider(session, candidate);
+        }
+        else {
+            const det = deterministicDecision(session, candidate);
+            decision = det.kind === 'escalate'
+                ? await smartDecider(session, candidate)
+                : { nudge: det.kind === 'nudge', reason: det.reason };
+        }
         const chosenText = decision.text ?? nudgeText;
+        // Log the decision for the Factory watchdog card.
+        const summary = summarizeWatchdogTail(tailLines, candidate.agentType);
+        logEvents.push({
+            ts: nowMs,
+            kind: 'decision',
+            terminalId: session.sessionId,
+            agentType: candidate.agentType,
+            message: decision.reason,
+            reason: decision.reason,
+            stalledForMs: status.stalledForMs,
+            tailLines,
+            nudgeText: decision.nudge ? chosenText : undefined,
+            lastUserMessage: summary.lastUserMessage,
+            lastAssistantMessage: summary.lastAssistantMessage,
+        });
         if (!decision.nudge) {
             outcomes.push({ ...base, decision: 'skip', reason: decision.reason });
             continue;
         }
-        // A nudge is warranted — run it past the safety gate BEFORE any delivery.
-        const resolution = resolveInjectTargetForSession(session, {
-            allowGhosttyFocus: opts.allowGhosttyFocus,
-        });
-        if (!resolution.addressable) {
-            // Flag the un-addressable stall for the tray; NEVER guess a target.
-            flags[session.sessionId] = { reason: resolution.reason, host: session.host, atMs: nowMs };
+        // A nudge is warranted — plan delivery (answer-router picks mailbox/resume/
+        // refuse; resolveInjectTargetForSession supplies the vscodium-aware inject
+        // target) BEFORE any side effect.
+        const block = openBlockFor(session);
+        const plan = planDelivery(session, chosenText, block, opts.allowGhosttyFocus);
+        const rail = plan.via === 'inject' ? plan.rail : undefined;
+        const addressable = plan.via === 'inject' ? true : undefined;
+        if (plan.via === 'refuse') {
+            // No addressable rail and not headless-resumable — flag, NEVER guess.
+            flags[session.sessionId] = { reason: plan.reason, host: session.host, atMs: nowMs };
             outcomes.push({
                 ...base, decision: 'skip', addressable: false,
-                reason: `nudge-worthy but un-addressable — ${resolution.reason}`,
+                reason: `nudge-worthy but un-addressable — ${plan.reason}`,
                 nudgeText: chosenText,
             });
             continue;
         }
-        // handsoff = detect + flag, but never inject. Record a flag so the tray can
-        // surface "would-nudge but hands-off" alongside the un-addressable flags.
+        // handsoff = detect + flag, but never deliver.
         if (policy === 'handsoff') {
             flags[session.sessionId] = {
-                reason: `handsoff: would nudge via ${resolution.rail} but policy is hands-off`,
+                reason: `handsoff: would nudge via ${viaLabel(plan)} but policy is hands-off`,
                 host: session.host,
                 atMs: nowMs,
             };
             outcomes.push({
-                ...base, decision: 'nudge', addressable: true, rail: resolution.rail, injected: false,
-                reason: `handsoff: flagged, not injected (would nudge via ${resolution.rail})`,
+                ...base, decision: 'nudge', addressable, rail, via: plan.via, injected: false,
+                reason: `handsoff: flagged, not delivered (would nudge via ${viaLabel(plan)})`,
                 nudgeText: chosenText,
             });
             continue;
@@ -276,38 +401,80 @@ export async function runWatchdogTick(opts = {}) {
         // Dry status (no --nudge): report what WOULD happen, deliver nothing.
         if (!opts.nudge) {
             outcomes.push({
-                ...base, decision: 'nudge', addressable: true, rail: resolution.rail, injected: false,
-                reason: `would nudge via ${resolution.rail} (dry — pass --nudge to inject)`,
+                ...base, decision: 'nudge', addressable, rail, via: plan.via, injected: false,
+                reason: `would nudge via ${viaLabel(plan)} (dry — pass --nudge)`,
                 nudgeText: chosenText,
             });
             continue;
         }
-        // Deliver into the EXACT resolved split.
-        let result;
-        try {
-            result = await injectIntoTerminal(resolution.target, chosenText, { dryRun: opts.injectDryRun });
+        // Deliver. injectDryRun exercises the path without a real side effect: inject
+        // still calls injectFn (which honors dryRun), mailbox/resume are short-circuited.
+        let delivered;
+        if (plan.via === 'inject') {
+            try {
+                const r = await injectFn(plan.target, chosenText, { dryRun: opts.injectDryRun });
+                delivered = { ok: r.ok, error: r.error };
+            }
+            catch (err) {
+                delivered = { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
         }
-        catch (err) {
-            result = { ok: false, backend: resolution.target.backend, writes: 0, error: err instanceof Error ? err.message : String(err) };
+        else if (plan.via === 'mailbox') {
+            if (opts.injectDryRun) {
+                delivered = { ok: true };
+            }
+            else {
+                try {
+                    deliverViaMailbox(plan.mailboxId, chosenText, block);
+                    delivered = { ok: true };
+                }
+                catch (err) {
+                    delivered = { ok: false, error: err instanceof Error ? err.message : String(err) };
+                }
+            }
+        }
+        else {
+            delivered = opts.injectDryRun ? { ok: true } : await deliverViaResume(session, chosenText);
         }
-        if (result.ok) {
-            ledger[session.sessionId] = nowMs; // start the cooldown clock
+        if (delivered.ok) {
+            ledgerUpdates[session.sessionId] = nowMs; // start the cooldown clock
+            logEvents.push({
+                ts: nowMs, kind: 'nudge', terminalId: session.sessionId, agentType: candidate.agentType,
+                message: `nudged via ${viaLabel(plan)}`, reason: decision.reason, nudgeText: chosenText,
+            });
             outcomes.push({
-                ...base, decision: 'nudge', addressable: true, rail: resolution.rail, injected: true,
-                reason: `nudged via ${resolution.rail}`,
+                ...base, decision: 'nudge', addressable, rail, via: plan.via, injected: true,
+                reason: `nudged via ${viaLabel(plan)}`,
                 nudgeText: chosenText,
             });
         }
         else {
             outcomes.push({
-                ...base, decision: 'skip', addressable: true, rail: resolution.rail, injected: false,
-                reason: `inject failed via ${resolution.rail}: ${result.error ?? 'unknown error'}`,
+                ...base, decision: 'skip', addressable, rail, via: plan.via, injected: false,
+                reason: `nudge via ${viaLabel(plan)} failed: ${delivered.error ?? 'unknown error'}`,
                 nudgeText: chosenText,
             });
         }
     }
-    // Persist the tray-readable state.
-    writeJsonFile(path.join(dir, 'nudges.json'), ledger);
+    // Persist the cooldown ledger under a lock: fresh-read + merge this tick's
+    // updates + atomic write, so a concurrent tick's timestamps are never lost
+    // (the old unlocked read-at-start / write-at-end was a lost-update race).
+    if (Object.keys(ledgerUpdates).length > 0) {
+        const nudgesPath = path.join(dir, 'nudges.json');
+        const ledgerLock = path.join(dir, '.ledger.lock');
+        try {
+            ensureLockTarget(ledgerLock);
+            withFileLock(ledgerLock, () => {
+                const current = readNudgeLedger(dir);
+                for (const [sid, ts] of Object.entries(ledgerUpdates))
+                    current[sid] = ts;
+                atomicWriteFileSync(nudgesPath, JSON.stringify(current, null, 2));
+            });
+        }
+        catch {
+            /* best-effort: a lock failure must not throw out of a tick */
+        }
+    }
     writeJsonFile(path.join(dir, 'flags.json'), flags);
     const counts = {
         total: outcomes.length,
@@ -318,5 +485,13 @@ export async function runWatchdogTick(opts = {}) {
     };
     const result = { atMs: nowMs, didNudge: opts.nudge === true, outcomes, counts };
     writeJsonFile(path.join(dir, 'last-tick.json'), result);
+    // Heartbeat + decision/nudge events to the canonical watchdog.log the Factory
+    // Floor reads. Best-effort; never throws into the tick.
+    logEvents.push({
+        ts: nowMs,
+        kind: 'tick',
+        message: `${counts.total} live · ${counts.stalled} stalled · ${counts.nudged} nudged · ${counts.unaddressable} un-addressable`,
+    });
+    appendWatchdogEvents(logEvents, { logPath: opts.logPath });
     return result;
 }

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

@@ -33,7 +33,7 @@ export interface ClassifyInput {
     dormantMs: number;
 }
 export declare function classifyTerminal(input: ClassifyInput): StallStatus;
-export declare const WATCHDOG_SYSTEM_PROMPT = "You are a watchdog monitoring AI coding agents that run in terminals.\nFor each stalled terminal below, decide: NUDGE (send a short message to unstick it) or SKIP.\n\nNudge when:\n- The last assistant turn announced an action (\"I'll write X\", \"let me run Y\")\n  but no matching tool call followed.\n- The agent appears stuck mid-task with no recent progress and the task is incomplete.\n\nSkip when:\n- The agent asked the user a direct question (waiting on human input).\n- The task looks complete.\n- You cannot tell what the agent is doing.\n\nNudge text must be:\n- One sentence, imperative (\"Show me the file.\", \"Run the tests.\").\n- No emojis. No apologies. Under 120 characters.\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. These agents are\nexpected to DRIVE TO COMPLETION end-to-end. They too often stop to ask a needless\nquestion or pause with the task unfinished. For each stalled terminal below, decide\nNUDGE (send a message that unsticks it and pushes it to finish) or SKIP (it genuinely\nneeds the human).\n\nNUDGE when the agent could have continued 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.\n- It announced an action (\"I'll run X\", \"let me write Y\") but no tool call followed.\n- It paused with the task incomplete and no real blocker.\nThe nudge text MUST: restate the goal, tell it to use best judgment and finish\nend-to-end WITHOUT asking again, and give ONE concrete hint \u2014 the specific next\nstep, a tool it forgot, or the sensible default to take. Imperative, 1-2 sentences,\nno emojis, under 200 characters.\n\nSKIP when the agent genuinely needs the human:\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).\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 function composePromptWithPlaybook(basePrompt: string, playbook: string): string;
 export declare function renderWatchdogPrompt(candidates: WatchdogCandidate[], playbook?: string): string;
 export declare function parseWatchdogResponse(stdout: string): Decision[];