@phnx-labs/agents-cli 1.20.35 → 1.20.37

package/dist/lib/watchdog/read.js

@@ -0,0 +1,149 @@
+// Watchdog tail reader: locate a session transcript from its id + agent and
+// pull the last N raw JSONL lines. The raw lines feed the pure detectors in
+// watchdog.ts (isLikelyTrulyBlocked / renderWatchdogPrompt) and the pure
+// summarizer in watchdogTail.ts.
+//
+// Adapted from Swarmify's readTailLines (extension/src/vscode/sessions.vscode.ts)
+// to agents-cli's session layout. Path resolution REUSES getAgentSessionDirs()
+// from src/lib/session/discover.ts — the same resolver the rest of the CLI uses
+// to enumerate per-version transcript roots — instead of hardcoding
+// ~/.agents/.history/versions/<agent>/.../projects/<enc>/<sessionId>.jsonl.
+import * as fs from 'fs';
+import * as path from 'path';
+import { getAgentSessionDirs } from '../session/discover.js';
+import { walkForFiles } from '../fs-walk.js';
+/** Default watchdog thresholds, mirrored from the Swarmify VS Code runtime. */
+export const WATCHDOG_TAIL_LINES = 20;
+export const WATCHDOG_STALL_MS = 300_000; // 5m — stallSeconds default
+export const WATCHDOG_COOLDOWN_MS = 1_200_000; // 20m — cooldownSeconds default
+export const WATCHDOG_DORMANT_MS = 3_600_000; // 1h — DORMANT_MS
+const CHUNK_SIZE = 64 * 1024;
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+/** Cap on files walked per transcript root — matches session/discover.ts. */
+const WATCHDOG_WALK_CAP = 100_000;
+/**
+ * Per-agent transcript layout, mirroring the `getAgentSessionDirs()` call sites
+ * in session/discover.ts so the resolver never diverges from the rest of the CLI:
+ * Claude keeps per-project folders under `projects/` (discover.ts:486); Codex and
+ * Droid date-/work-partition rollout `.jsonl` deep under `sessions/`
+ * (discover.ts:665, :1673); Gemini nests chat `.json` under `tmp/<hash>/chats/`
+ * (discover.ts:820). Subdir + extension are driven from this table instead of the
+ * old hardcoded `codex ? 'sessions' : 'projects'` ternary, which sent every
+ * non-Codex agent (Gemini included) to the wrong root.
+ */
+const WATCHDOG_SESSION_LAYOUT = {
+    claude: { subdir: 'projects', ext: '.jsonl' },
+    codex: { subdir: 'sessions', ext: '.jsonl' },
+    droid: { subdir: 'sessions', ext: '.jsonl' },
+    gemini: { subdir: 'tmp', ext: '.json' },
+};
+const WATCHDOG_SESSION_LAYOUT_DEFAULT = { subdir: 'projects', ext: '.jsonl' };
+/**
+ * Read the last `maxLines` non-empty lines of a JSONL transcript by seeking
+ * backward from EOF in 64KB chunks. A tail that begins mid-line yields one
+ * malformed leading line, which the callers' per-line JSON try/catch tolerates.
+ * Returns `[]` on any read error or empty file.
+ */
+export function readTailLines(filePath, maxLines) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return [];
+    }
+    try {
+        const fileSize = fs.fstatSync(fd).size;
+        if (fileSize === 0)
+            return [];
+        let position = fileSize;
+        let buffer = '';
+        let collected = [];
+        while (position > 0 && collected.length <= maxLines) {
+            const readSize = Math.min(CHUNK_SIZE, position);
+            position -= readSize;
+            const chunk = Buffer.alloc(readSize);
+            fs.readSync(fd, chunk, 0, readSize, position);
+            buffer = chunk.toString('utf-8') + buffer;
+            collected = buffer.split(/\r?\n/).filter((l) => l.trim());
+        }
+        return collected.slice(-maxLines);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            /* fd already gone */
+        }
+    }
+}
+/**
+ * Given candidate transcript-root directories, find the transcript file for a
+ * session. Handles the flat Claude layout (`<sessionId>.jsonl` inside a
+ * per-project `<enc>/` subfolder), Codex-style names that merely embed the uuid
+ * (`rollout-…-<sessionId>.jsonl`), and — critically — the DEEP date partitions
+ * Codex/Droid use (`sessions/YYYY/MM/DD/rollout-…-<uuid>.jsonl`). The scan is
+ * fully recursive via `walkForFiles` (the same walker session/discover.ts uses),
+ * so no fixed number of subdir levels is assumed — a hand-rolled one-level scan
+ * silently missed every Codex transcript. Newest mtime wins when a uuid appears
+ * in more than one root (e.g. across version homes). Pure over its `dirs`
+ * argument, so it is testable without touching the real home directory.
+ */
+export function findSessionJsonlIn(dirs, sessionId, ext = '.jsonl') {
+    if (!sessionId)
+        return undefined;
+    const matches = (name) => {
+        if (!name.endsWith(ext))
+            return false;
+        const stem = name.slice(0, -ext.length);
+        if (stem === sessionId)
+            return true;
+        // Codex embeds the uuid in a longer filename (rollout-<ts>-<uuid>.jsonl).
+        return name.includes(sessionId) || (UUID_RE.test(sessionId) && stem.includes(sessionId));
+    };
+    let best;
+    for (const dir of dirs) {
+        for (const file of walkForFiles(dir, ext, WATCHDOG_WALK_CAP)) {
+            if (!matches(path.basename(file)))
+                continue;
+            let mtime;
+            try {
+                mtime = fs.statSync(file).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (!best || mtime > best.mtime)
+                best = { file, mtime };
+        }
+    }
+    return best?.file;
+}
+/**
+ * Resolve a session transcript path from its id + agent, reusing the CLI's
+ * per-version transcript roots. Returns `undefined` if no transcript is found.
+ */
+export function resolveWatchdogSessionPath(sessionId, agent) {
+    // Subdir + transcript extension are driven per-agent from WATCHDOG_SESSION_LAYOUT
+    // (which mirrors the getAgentSessionDirs() convention in session/discover.ts),
+    // not a hardcoded `codex ? 'sessions' : 'projects'` — that ternary sent Codex to
+    // a root it only scanned one level deep, and every other agent (Gemini included)
+    // to the wrong subdir entirely.
+    const layout = WATCHDOG_SESSION_LAYOUT[agent] ?? WATCHDOG_SESSION_LAYOUT_DEFAULT;
+    const dirs = getAgentSessionDirs(agent, layout.subdir);
+    return findSessionJsonlIn(dirs, sessionId, layout.ext);
+}
+/**
+ * Read the last `maxLines` JSONL lines for a session by id + agent. Returns
+ * `[]` when the transcript cannot be located or read.
+ */
+export function readWatchdogTail(sessionId, agent, maxLines = WATCHDOG_TAIL_LINES) {
+    const filePath = resolveWatchdogSessionPath(sessionId, agent);
+    if (!filePath)
+        return [];
+    return readTailLines(filePath, maxLines);
+}

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

@@ -0,0 +1,127 @@
+/**
+ * Watchdog runner — the CONSUMER that wires the merged pure pieces into a
+ * 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:
+ *
+ *   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
+ *           -> resolveInjectTargetForSession(...)  (terminal/resolve.ts)   — THE safety gate: addressable or an honest refusal
+ *             -> injectIntoTerminal(target,text)   (terminal/inject.ts)    — deliver "Continue." into the EXACT split
+ *
+ * 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.
+ *
+ * Persistence (all under ~/.agents/.cache/state/watchdog/, tray-readable):
+ *   - nudges.json  — { [sessionId]: lastNudgeMs } — enforces the cooldown.
+ *   - flags.json   — { [sessionId]: { reason, host, atMs } } — un-addressable stalls.
+ *   - last-tick.json — the full outcome list from the most recent tick.
+ *   - policy/<sessionId> — per-session sentinel: off | keep | handsoff.
+ *
+ * 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.
+ */
+import type { ActiveSession } from '../session/active.js';
+import { type InjectRail } from '../terminal/resolve.js';
+import { type StallStatus } from './watchdog.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. */
+export interface WatchdogThresholds {
+    stallMs: number;
+    cooldownMs: number;
+    dormantMs: number;
+}
+export declare const DEFAULT_THRESHOLDS: WatchdogThresholds;
+/** The default nudge text — a short imperative, configurable via opts.nudgeText. */
+export declare const DEFAULT_NUDGE_TEXT = "Continue.";
+export interface WatchdogTickOptions {
+    /** Actually inject when a nudge is decided. Default false (dry status). */
+    nudge?: boolean;
+    /** 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.
+     */
+    smart?: boolean;
+    /** Agent the smart decider runs as. Default 'claude'. */
+    smartAgent?: string;
+    /** Threshold overrides. Missing fields fall back to DEFAULT_THRESHOLDS. */
+    thresholds?: Partial<WatchdogThresholds>;
+    /** Permit the coarse, focus-stealing Ghostty path. Off by default. */
+    allowGhosttyFocus?: boolean;
+    /** Pass dryRun through to injectIntoTerminal (tests set true — no real terminal). */
+    injectDryRun?: boolean;
+    /** Session list. Default getActiveSessions(). Tests pass synthetic sessions. */
+    sessions?: ActiveSession[];
+    /** Clock. Default Date.now(). Tests pin it. */
+    nowMs?: number;
+    /** Override the state directory (tests point at a tmpdir). */
+    stateDir?: string;
+    /** lastActivity (ms) for a session. Default = its transcript mtime. */
+    lastActivityFor?: (s: ActiveSession) => number | undefined;
+    /** Transcript tail lines for a session. Default readWatchdogTail(). */
+    tailFor?: (s: ActiveSession) => string[];
+    /** Per-session policy. Default = the on-disk sentinel. */
+    policyFor?: (s: ActiveSession) => WatchdogPolicy;
+}
+/** What the tick decided for a single session — the row `--json` / the tray reads. */
+export interface SessionOutcome {
+    sessionId?: string;
+    kind: string;
+    host?: string;
+    cwd?: string;
+    label?: string;
+    /** classifyTerminal's verdict for this session. */
+    stall: StallStatus['kind'];
+    /** stalled duration (ms), when stalled. */
+    stalledForMs?: number;
+    policy: WatchdogPolicy;
+    decision: 'nudge' | 'skip';
+    reason: string;
+    /** The resolved rail, when addressable. */
+    rail?: InjectRail;
+    /** True when resolveInjectTarget said addressable (only meaningful once we'd nudge). */
+    addressable?: boolean;
+    /** True when a nudge was actually delivered this tick. */
+    injected?: boolean;
+    /** The text that was (or would be) delivered. */
+    nudgeText?: string;
+}
+export interface WatchdogTickResult {
+    atMs: number;
+    /** Whether this tick was allowed to inject (opts.nudge). */
+    didNudge: boolean;
+    outcomes: SessionOutcome[];
+    /** Convenience counts for the menu-bar / status line. */
+    counts: {
+        total: number;
+        stalled: number;
+        nudged: number;
+        unaddressable: number;
+        skipped: number;
+    };
+}
+/**
+ * On-disk per-session policy sentinel: `<stateDir>/policy/<sessionId>` whose
+ * contents are `off` | `keep` | `handsoff`. Absent / unreadable / unknown → keep.
+ */
+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;
+/**
+ * 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
+ * permits. Persists the cooldown ledger, un-addressable flags, and a last-tick
+ * snapshot to the tray-readable state dir.
+ */
+export declare function runWatchdogTick(opts?: WatchdogTickOptions): Promise<WatchdogTickResult>;

package/dist/lib/watchdog/runner.js

@@ -0,0 +1,322 @@
+/**
+ * Watchdog runner — the CONSUMER that wires the merged pure pieces into a
+ * 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:
+ *
+ *   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
+ *           -> resolveInjectTargetForSession(...)  (terminal/resolve.ts)   — THE safety gate: addressable or an honest refusal
+ *             -> injectIntoTerminal(target,text)   (terminal/inject.ts)    — deliver "Continue." into the EXACT split
+ *
+ * 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.
+ *
+ * Persistence (all under ~/.agents/.cache/state/watchdog/, tray-readable):
+ *   - nudges.json  — { [sessionId]: lastNudgeMs } — enforces the cooldown.
+ *   - flags.json   — { [sessionId]: { reason, host, atMs } } — un-addressable stalls.
+ *   - last-tick.json — the full outcome list from the most recent tick.
+ *   - policy/<sessionId> — per-session sentinel: off | keep | handsoff.
+ *
+ * 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.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getActiveSessions } from '../session/active.js';
+import { resolveInjectTargetForSession, } from '../terminal/resolve.js';
+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';
+export const DEFAULT_THRESHOLDS = {
+    stallMs: WATCHDOG_STALL_MS,
+    cooldownMs: WATCHDOG_COOLDOWN_MS,
+    dormantMs: WATCHDOG_DORMANT_MS,
+};
+/** The default nudge text — a short imperative, configurable via opts.nudgeText. */
+export const DEFAULT_NUDGE_TEXT = 'Continue.';
+// --- state persistence ------------------------------------------------------
+function watchdogStateDir(opts) {
+    return opts.stateDir ?? path.join(getRuntimeStateDir(), 'watchdog');
+}
+function readJsonFile(file, fallback) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+function writeJsonFile(file, value) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(value, null, 2));
+    }
+    catch {
+        /* best-effort: the tray tolerates a missing/partial state file */
+    }
+}
+/** Last-nudge timestamps keyed by sessionId (the cooldown ledger). */
+function readNudgeLedger(dir) {
+    return readJsonFile(path.join(dir, 'nudges.json'), {});
+}
+/**
+ * On-disk per-session policy sentinel: `<stateDir>/policy/<sessionId>` whose
+ * contents are `off` | `keep` | `handsoff`. Absent / unreadable / unknown → keep.
+ */
+export function readPolicySentinel(dir, sessionId) {
+    if (!sessionId)
+        return 'keep';
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(dir, 'policy', sessionId), 'utf8').trim().toLowerCase();
+    }
+    catch {
+        return 'keep';
+    }
+    return raw === 'off' || raw === 'handsoff' ? raw : 'keep';
+}
+/** Write a per-session policy sentinel (used by the CLI `agents watchdog policy`). */
+export function writePolicySentinel(dir, sessionId, policy) {
+    const file = path.join(dir, 'policy', sessionId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, policy + '\n');
+}
+// --- helpers ----------------------------------------------------------------
+function defaultLastActivity(s) {
+    if (s.sessionFile) {
+        try {
+            return fs.statSync(s.sessionFile).mtimeMs;
+        }
+        catch {
+            /* file vanished */
+        }
+    }
+    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.
+ */
+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) {
+    if (session.activity === 'waiting_input') {
+        return { nudge: false, reason: `waiting on user${session.awaitingReason ? ` (${session.awaitingReason})` : ''}` };
+    }
+    // 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).
+    if (tailShowsCompletion(candidate)) {
+        return { nudge: false, reason: 'tail shows completion (done / finished / all set) — skip regardless of stall age' };
+    }
+    if (isLikelyTrulyBlocked(candidate)) {
+        return { nudge: true, reason: 'stalled after announcing an action with no follow-through' };
+    }
+    return { nudge: false, reason: 'no promise-without-toolcall signal in tail (completion / question / unclear)' };
+}
+/**
+ * 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.
+ */
+async function smartDecision(candidate, agent) {
+    const prompt = renderWatchdogPrompt([candidate]);
+    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 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)}` };
+    }
+}
+// --- the tick ---------------------------------------------------------------
+/**
+ * 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
+ * permits. Persists the cooldown ledger, un-addressable flags, and a last-tick
+ * snapshot to the tray-readable state dir.
+ */
+export async function runWatchdogTick(opts = {}) {
+    const nowMs = opts.nowMs ?? Date.now();
+    const nudgeText = opts.nudgeText ?? DEFAULT_NUDGE_TEXT;
+    const thresholds = { ...DEFAULT_THRESHOLDS, ...opts.thresholds };
+    const dir = watchdogStateDir(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 sessions = opts.sessions ?? (await getActiveSessions());
+    const ledger = readNudgeLedger(dir);
+    const flags = {};
+    const outcomes = [];
+    for (const session of sessions) {
+        const policy = policyFor(session);
+        const base = {
+            sessionId: session.sessionId,
+            kind: session.kind,
+            host: session.host,
+            cwd: session.cwd,
+            label: session.label,
+            policy,
+            stall: 'active',
+            decision: 'skip',
+            reason: '',
+            nudgeText,
+        };
+        // A session with no id can neither be addressed nor cooldown-tracked.
+        if (!session.sessionId) {
+            outcomes.push({ ...base, reason: 'no session id (cannot address or track)' });
+            continue;
+        }
+        // `off` = fully opted out. We short-circuit here rather than relying on
+        // classifyTerminal (which is always called with optedOut: false below), so the
+        // policy reason is reported explicitly.
+        if (policy === 'off') {
+            outcomes.push({ ...base, stall: 'opted_out', reason: 'policy: off (opted out)' });
+            continue;
+        }
+        const lastActivityMs = lastActivityFor(session);
+        if (lastActivityMs === undefined) {
+            outcomes.push({ ...base, reason: 'no activity timestamp (no transcript / start time)' });
+            continue;
+        }
+        const status = classifyTerminal({
+            lastActivityMs,
+            nowMs,
+            lastNudgeMs: ledger[session.sessionId] ?? null,
+            optedOut: false,
+            stallMs: thresholds.stallMs,
+            cooldownMs: thresholds.cooldownMs,
+            dormantMs: thresholds.dormantMs,
+        });
+        base.stall = status.kind;
+        if (status.kind !== 'stalled') {
+            const reason = status.kind === 'active' ? `active (last activity ${Math.round((nowMs - lastActivityMs) / 1000)}s ago)`
+                : status.kind === 'dormant' ? 'dormant (idle past the dormant window)'
+                    : status.kind === 'rate_limited' ? `cooling down (${Math.round(status.cooldownRemainingMs / 1000)}s left)`
+                        : 'opted out';
+            outcomes.push({ ...base, reason });
+            continue;
+        }
+        base.stalledForMs = status.stalledForMs;
+        // Stalled — read the tail and decide.
+        const tailLines = tailFor(session);
+        const candidate = {
+            terminalId: session.sessionId,
+            agentType: (session.kind === 'codex' || session.kind === 'gemini' ? session.kind : 'claude'),
+            tailLines,
+            stalledForMs: status.stalledForMs,
+        };
+        const decision = opts.smart
+            ? await smartDecision(candidate, opts.smartAgent ?? 'claude')
+            : deterministicDecision(session, candidate);
+        const chosenText = decision.text ?? nudgeText;
+        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 };
+            outcomes.push({
+                ...base, decision: 'skip', addressable: false,
+                reason: `nudge-worthy but un-addressable — ${resolution.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.
+        if (policy === 'handsoff') {
+            flags[session.sessionId] = {
+                reason: `handsoff: would nudge via ${resolution.rail} 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})`,
+                nudgeText: chosenText,
+            });
+            continue;
+        }
+        // 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)`,
+                nudgeText: chosenText,
+            });
+            continue;
+        }
+        // Deliver into the EXACT resolved split.
+        let result;
+        try {
+            result = await injectIntoTerminal(resolution.target, chosenText, { dryRun: opts.injectDryRun });
+        }
+        catch (err) {
+            result = { ok: false, backend: resolution.target.backend, writes: 0, error: err instanceof Error ? err.message : String(err) };
+        }
+        if (result.ok) {
+            ledger[session.sessionId] = nowMs; // start the cooldown clock
+            outcomes.push({
+                ...base, decision: 'nudge', addressable: true, rail: resolution.rail, injected: true,
+                reason: `nudged via ${resolution.rail}`,
+                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'}`,
+                nudgeText: chosenText,
+            });
+        }
+    }
+    // Persist the tray-readable state.
+    writeJsonFile(path.join(dir, 'nudges.json'), ledger);
+    writeJsonFile(path.join(dir, 'flags.json'), flags);
+    const counts = {
+        total: outcomes.length,
+        stalled: outcomes.filter((o) => o.stall === 'stalled').length,
+        nudged: outcomes.filter((o) => o.injected).length,
+        unaddressable: outcomes.filter((o) => o.addressable === false).length,
+        skipped: outcomes.filter((o) => o.decision === 'skip').length,
+    };
+    const result = { atMs: nowMs, didNudge: opts.nudge === true, outcomes, counts };
+    writeJsonFile(path.join(dir, 'last-tick.json'), result);
+    return result;
+}

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

@@ -0,0 +1,40 @@
+export interface WatchdogCandidate {
+    terminalId: string;
+    agentType: 'claude' | 'codex' | 'gemini';
+    tailLines: string[];
+    stalledForMs: number;
+}
+export interface Decision {
+    terminalId: string;
+    action: 'nudge' | 'skip';
+    text: string;
+    reason: string;
+}
+export type StallStatus = {
+    kind: 'active';
+} | {
+    kind: 'dormant';
+} | {
+    kind: 'opted_out';
+} | {
+    kind: 'rate_limited';
+    cooldownRemainingMs: number;
+} | {
+    kind: 'stalled';
+    stalledForMs: number;
+};
+export interface ClassifyInput {
+    lastActivityMs: number;
+    nowMs: number;
+    lastNudgeMs: number | null;
+    optedOut: boolean;
+    stallMs: number;
+    cooldownMs: number;
+    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 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;