@phnx-labs/agents-cli 1.20.35 → 1.20.36

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;

package/dist/lib/watchdog/watchdog.js

@@ -0,0 +1,166 @@
+// Watchdog: pure logic for detecting stalled agent terminals and rendering
+// prompts to a headless decider instance that decides whether to nudge them.
+// Ported from Swarmify (extension/src/core/watchdog.ts) — behavior verbatim.
+// Terminal/session delivery lives elsewhere; this module reads no files and
+// touches no host APIs so it can be unit-tested in isolation.
+const FORCE_REVIEW_STALL_MS = 15 * 60 * 1000;
+const BLOCKED_HINTS = [
+    'blocked',
+    'stuck',
+    "can't",
+    'cannot',
+    'unable',
+    'failed',
+    'error',
+    'exception',
+    'traceback',
+    'timed out',
+    'timeout',
+    'rate limit',
+    'permission denied',
+];
+const WAITING_HINTS = [
+    'waiting on user',
+    'awaiting user',
+    'askuserquestion',
+];
+const COMPLETION_HINTS = [
+    'done',
+    'completed',
+    'all set',
+    'finished',
+];
+const TOOL_CALL_HINTS = [
+    '"type":"tool_use"',
+    '"type":"tool_call"',
+    '"type":"function_call"',
+];
+const ASSISTANT_LINE_HINTS = [
+    '"type":"assistant"',
+    '"role":"assistant"',
+    '"payload":{"type":"message"',
+];
+const PROMISE_HINTS = [
+    "i'll",
+    'i will',
+    'let me',
+    'going to',
+    "next i'll",
+    'next i will',
+];
+export function classifyTerminal(input) {
+    if (input.optedOut)
+        return { kind: 'opted_out' };
+    const age = input.nowMs - input.lastActivityMs;
+    if (age < input.stallMs)
+        return { kind: 'active' };
+    if (age > input.dormantMs)
+        return { kind: 'dormant' };
+    if (input.lastNudgeMs !== null) {
+        const sinceNudge = input.nowMs - input.lastNudgeMs;
+        if (sinceNudge < input.cooldownMs) {
+            return { kind: 'rate_limited', cooldownRemainingMs: input.cooldownMs - sinceNudge };
+        }
+    }
+    return { kind: 'stalled', stalledForMs: age };
+}
+export const WATCHDOG_SYSTEM_PROMPT = `You are a watchdog monitoring AI coding agents that run in terminals.
+For each stalled terminal below, decide: NUDGE (send a short message to unstick it) or SKIP.
+
+Nudge when:
+- The last assistant turn announced an action ("I'll write X", "let me run Y")
+  but no matching tool call followed.
+- The agent appears stuck mid-task with no recent progress and the task is incomplete.
+
+Skip when:
+- The agent asked the user a direct question (waiting on human input).
+- The task looks complete.
+- You cannot tell what the agent is doing.
+
+Nudge text must be:
+- One sentence, imperative ("Show me the file.", "Run the tests.").
+- No emojis. No apologies. Under 120 characters.
+
+Respond with ONLY a JSON array (no prose, no code fence):
+[{"terminalId":"<id>","action":"nudge"|"skip","text":"<message or empty>","reason":"<brief>"}]`;
+// User-editable playbook appended below the built-in prompt. The user maintains
+// the source at ~/.agents/playbooks/watchdog.md (read by the delivery layer);
+// this function is pure so it can be tested without filesystem access.
+export function composePromptWithPlaybook(basePrompt, playbook) {
+    const trimmed = playbook.trim();
+    if (!trimmed)
+        return basePrompt;
+    return `${basePrompt}\n\n## House Rules (user playbook)\n\n${trimmed}`;
+}
+export function renderWatchdogPrompt(candidates, playbook = '') {
+    const systemPrompt = composePromptWithPlaybook(WATCHDOG_SYSTEM_PROMPT, playbook);
+    const parts = [systemPrompt, '', 'STALLED TERMINALS:', ''];
+    for (const c of candidates) {
+        const seconds = Math.round(c.stalledForMs / 1000);
+        parts.push(`--- terminal ${c.terminalId} (${c.agentType}, idle ${seconds}s) ---`);
+        parts.push('last JSONL lines:');
+        for (const line of c.tailLines) {
+            parts.push(line);
+        }
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+export function parseWatchdogResponse(stdout) {
+    if (!stdout || !stdout.trim())
+        return [];
+    const arrayMatch = stdout.match(/\[[\s\S]*\]/);
+    if (!arrayMatch)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(arrayMatch[0]);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const decisions = [];
+    for (const d of parsed) {
+        if (!d || typeof d !== 'object')
+            continue;
+        const obj = d;
+        const terminalId = typeof obj.terminalId === 'string' ? obj.terminalId : '';
+        const action = obj.action === 'nudge' || obj.action === 'skip' ? obj.action : null;
+        const text = typeof obj.text === 'string' ? obj.text : '';
+        const reason = typeof obj.reason === 'string' ? obj.reason : '';
+        if (!terminalId || !action)
+            continue;
+        decisions.push({ terminalId, action, text, reason });
+    }
+    return decisions;
+}
+export function isLikelyTrulyBlocked(candidate) {
+    if (candidate.stalledForMs >= FORCE_REVIEW_STALL_MS)
+        return true;
+    if (candidate.tailLines.length === 0)
+        return false;
+    const lowerTail = candidate.tailLines.join('\n').toLowerCase();
+    if (WAITING_HINTS.some((hint) => lowerTail.includes(hint)))
+        return false;
+    if (COMPLETION_HINTS.some((hint) => lowerTail.includes(hint)))
+        return false;
+    if (BLOCKED_HINTS.some((hint) => lowerTail.includes(hint)))
+        return true;
+    let sawToolAfter = false;
+    for (let i = candidate.tailLines.length - 1; i >= 0; i--) {
+        const line = candidate.tailLines[i].toLowerCase();
+        if (TOOL_CALL_HINTS.some((hint) => line.includes(hint))) {
+            sawToolAfter = true;
+            continue;
+        }
+        if (!sawToolAfter) {
+            const isAssistantLine = ASSISTANT_LINE_HINTS.some((hint) => line.includes(hint));
+            const hasPromise = PROMISE_HINTS.some((hint) => line.includes(hint));
+            if (isAssistantLine && hasPromise)
+                return true;
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,5 @@
+export interface TailSummary {
+    lastUserMessage?: string;
+    lastAssistantMessage?: string;
+}
+export declare function summarizeWatchdogTail(tailLines: string[], agentType: string | undefined): TailSummary;