@phnx-labs/agents-cli 1.22.46 → 1.22.47

package/dist/lib/usage-refresh.js

@@ -19,8 +19,8 @@
  *    floor and ceiling are both 5 minutes.
  *  - **Hard hourly cap** (`HOURLY_CALL_CAP`) so a stuck "due" loop cannot
  *    hammer an endpoint past ~12 calls/account/hour.
- *  - **429 backoff.** A provider under `usageRateLimitedUntil` is skipped
- *    entirely — no live fetch, no Touch ID, no re-armed penalty.
+ *  - **429 backoff.** An account (or provider-wide scope) under
+ *    `usageRateLimitedUntil` is skipped — no live fetch or re-armed penalty.
  *  - **File-only credentials on the daemon path.** Refresh never opens the
  *    ACL-bound macOS keychain item (Touch ID storm). It uses the no-ACL
  *    access-token cache / setup-token / `.credentials.json` only
@@ -37,8 +37,8 @@
  *     serializes read-modify-write; no lost updates.
  *  3. **macOS keychain ACL / Touch ID** — fileOnly refresh never calls
  *     `security find-generic-password` on Claude's ACL item.
- *  4. **Provider 429** — whole provider skipped until Retry-After; cache
- *     freezes (visible as aged `capturedAt`) rather than hammering.
+ *  4. **Account 429** — that account is skipped until Retry-After while its
+ *     siblings continue; a provider-wide penalty still skips all accounts.
  *  5. **Expired access token (no refresh)** — usage path never rotates
  *     single-use refresh tokens; counts as `failed`, reschedules 5m later.
  *  6. **No file credential on this host** — account skipped / failed; no
@@ -71,6 +71,12 @@ export const REFRESH_BURN_DIVISOR = 4;
 export const HOURLY_CALL_CAP = 12;
 /** How often the daemon wakes to *consider* a refresh pass (due accounts only). */
 export const USAGE_REFRESH_TICK_MS = 60 * 1000;
+/** Consecutive failed live reads before one broken account is quarantined. */
+export const FAILURE_QUARANTINE_THRESHOLD = 3;
+/** A chronic offender waits this long while healthy siblings keep their cadence. */
+export const FAILURE_QUARANTINE_MS = 30 * 60 * 1000;
+const SKIP_JITTER_MIN_MS = 2_000;
+const SKIP_JITTER_RANGE_MS = 3_001;
 const HOUR_MS = 60 * 60 * 1000;
 /** Test seam for the headroom cache path (see usage.ts `setClaudeUsageCachePathForTest`). */
 let headroomCachePathOverride = null;
@@ -169,8 +175,47 @@ export function nextHeadroomEntry(prev, snapshot, now) {
         nextRefreshAt: now + computeNextRefreshDelayMs(headroom.minutesToLimit),
         callTimestamps,
         computedAt: now,
+        consecutiveFailures: snapshot ? 0 : (prev?.consecutiveFailures ?? 0) + 1,
     };
 }
+/** Stable per-account delay in [2s, 5s], used to spread skipped accounts. */
+function skipJitterMs(usageKey) {
+    let hash = 0;
+    for (const char of usageKey)
+        hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
+    return SKIP_JITTER_MIN_MS + (hash % SKIP_JITTER_RANGE_MS);
+}
+function skippedHeadroomEntry(prev, usageKey, now, index) {
+    return {
+        status: prev?.status ?? null,
+        minutesToLimit: prev?.minutesToLimit ?? null,
+        sessionUsedPercent: prev?.sessionUsedPercent ?? null,
+        capturedAt: prev?.capturedAt ?? null,
+        nextRefreshAt: now + (index + 1) * skipJitterMs(usageKey),
+        callTimestamps: pruneCallTimestamps(prev?.callTimestamps ?? [], now),
+        computedAt: now,
+        consecutiveFailures: prev?.consecutiveFailures ?? 0,
+    };
+}
+function failedHeadroomEntry(prev, now) {
+    const next = nextHeadroomEntry(prev, null, now);
+    if ((next.consecutiveFailures ?? 0) >= FAILURE_QUARANTINE_THRESHOLD) {
+        next.nextRefreshAt = now + FAILURE_QUARANTINE_MS;
+    }
+    return next;
+}
+/** Cold accounts lead each pass; both cold and cached groups rotate every tick. */
+export function orderUsageAccounts(accounts, cache, tick) {
+    const rotate = (group) => {
+        if (group.length < 2)
+            return group;
+        const start = tick % group.length;
+        return [...group.slice(start), ...group.slice(0, start)];
+    };
+    const cold = accounts.filter((account) => cache[account.usageKey] == null);
+    const cached = accounts.filter((account) => cache[account.usageKey] != null);
+    return [...rotate(cold), ...rotate(cached)];
+}
 /**
  * Enumerate the usage accounts whose credentials live on THIS host — one
  * per unique usage key, deduped to the most-recently-active version (the same
@@ -217,7 +262,7 @@ export async function buildLocalUsageAccounts() {
 }
 /**
  * One refresher tick: for each local account that is due, under its hourly cap,
- * and not provider-backed-off, live-fetch its usage, update the cache, and
+ * and not backed off, live-fetch its usage, update the cache, and
  * reschedule from the new burn projection. Never throws — a single account's
  * failed fetch leaves its cache untouched and counts as `failed`.
  */
@@ -230,14 +275,15 @@ export async function runUsageRefresh(deps) {
         skippedCap: 0,
         failed: 0,
     };
-    const accounts = await deps.listAccounts();
     const cache = readHeadroomCache();
+    const accounts = orderUsageAccounts(await deps.listAccounts(), cache, Math.floor(now / USAGE_REFRESH_TICK_MS));
     const updates = {};
-    for (const account of accounts) {
+    for (const [index, account] of accounts.entries()) {
         const entry = cache[account.usageKey] ?? null;
-        // A provider under a 429 penalty is off-limits — poking it re-arms the
+        // A penalized account/provider is off-limits — poking it re-arms the
         // penalty (the whole reason usage-backoff exists).
-        if ((deps.backoffUntil(account.agentId) ?? 0) > now) {
+        if ((deps.backoffUntil(account.agentId, account.usageKey) ?? 0) > now) {
+            updates[account.usageKey] = skippedHeadroomEntry(entry, account.usageKey, now, index);
             result.skippedBackoff += 1;
             continue;
         }
@@ -259,12 +305,12 @@ export async function runUsageRefresh(deps) {
                 // No live snapshot (expired token / fetch miss): don't rewrite the usage
                 // cache, but still record the call + reschedule so a broken account
                 // isn't retried every tick.
-                updates[account.usageKey] = nextHeadroomEntry(entry, null, now);
+                updates[account.usageKey] = failedHeadroomEntry(entry, now);
                 result.failed += 1;
             }
         }
         catch {
-            updates[account.usageKey] = nextHeadroomEntry(entry, null, now);
+            updates[account.usageKey] = failedHeadroomEntry(entry, now);
             result.failed += 1;
         }
     }

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

@@ -1,7 +1,7 @@
 /** Same path the Fleet reader pulls (apps/ext/src/core/watchdogLog.ts). */
 export declare const WATCHDOG_LOG_PATH: string;
 /** Kinds the Factory reader accepts. Keep in lockstep with watchdogLog.ts. */
-export type WatchdogEventKind = 'tick' | 'decision' | 'nudge' | 'rotate' | 'error';
+export type WatchdogEventKind = 'tick' | 'decision' | 'nudge' | 'undelivered' | 'rotate' | 'error';
 /** JSONL row shape — a verbatim replica of the Factory reader's WatchdogEvent. */
 export interface WatchdogEvent {
     ts: number;

package/dist/lib/watchdog/log.js

@@ -18,7 +18,7 @@ import * as path from 'path';
 import { withFileLock, atomicWriteFileSync, ensureLockTarget } from '../fs-atomic.js';
 /** Same path the Fleet reader pulls (apps/ext/src/core/watchdogLog.ts). */
 export const WATCHDOG_LOG_PATH = path.join(os.homedir(), '.agents', '.cache', 'logs', 'watchdog.log');
-const WATCHDOG_EVENT_KINDS = new Set(['tick', 'decision', 'nudge', 'rotate', 'error']);
+const WATCHDOG_EVENT_KINDS = new Set(['tick', 'decision', 'nudge', 'undelivered', 'rotate', 'error']);
 /** Parse the audit log without letting a partial final append hide valid rows. */
 export function parseWatchdogEvents(text) {
     const events = [];

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

@@ -3,19 +3,23 @@
  * working auto-nudge (RUSH-1415). The `agents watchdog` command drives it, so
  * the whole loop runs WITHOUT the Swift menu-bar.
  *
- * One tick, per session:
+ * One tick:
  *
  *   getActiveSessions()                            (session/active.ts)
- *     -> classifyTerminal(...)                     (watchdog/watchdog.ts)  — stalled?
- *       -> readWatchdogTail(...)                   (watchdog/read.ts)      — the transcript tail
- *         -> isLikelyTrulyBlocked(...)             (watchdog/watchdog.ts)  — promise-without-toolcall, NOT waiting-on-user
+ *     -> classifyTerminal(...) per session         (watchdog/watchdog.ts)  — which are idle?
+ *       -> readWatchdogTail(...) for the idle ones  (watchdog/read.ts)      — task + transcript tail
+ *         -> the watchdog AGENT judges them ALL at once (watchdog/watchdog-agent.ts)
+ *              — idle-but-unfinished -> nudge; idle-and-done / needs-human -> skip
  *           -> resolveInjectTargetForSession(...)  (terminal/resolve.ts)   — THE safety gate: addressable or an honest refusal
- *             -> injectIntoTerminal(target,text)   (terminal/inject.ts)    — deliver "Continue." into the EXACT split
+ *             -> injectIntoTerminal(target,text)   (terminal/inject.ts)    — deliver into the EXACT split, then CONFIRM
  *
- * The safety gate is absolute: a nudge is delivered ONLY when the resolver
- * returns `addressable: true`. On `addressable: false` the reason is recorded to
- * a state file the menu-bar can surface later and the session is SKIPPED — never
- * a guessed / frontmost target.
+ * There is no heuristic decider — no regex over the tail guessing done-vs-stuck.
+ * The agent is the whole decider, given every idle session's task + tail in ONE
+ * `agents run --mode plan` call per tick. The safety gate is absolute: a nudge is
+ * delivered ONLY when the resolver returns `addressable: true`, and it is booked in
+ * the cooldown ledger ONLY when delivery is CONFIRMED. On `addressable: false` the
+ * reason is recorded to a state file the menu-bar can surface and the session is
+ * SKIPPED — never a guessed / frontmost target.
  *
  * Persistence (all under ~/.agents/.cache/state/watchdog/, tray-readable):
  *   - nudges.json  — { [sessionId]: lastNudgeMs } — enforces the cooldown.
@@ -25,15 +29,16 @@
  *   - rotate/<sessionId>.json — the in-place rotate state machine (rotate.ts).
  *   - rotate-skips.json — zero-healthy skip suppression: { [sessionId]: suppressUntilMs }.
  *
- * The pure logic (classifyTerminal / isLikelyTrulyBlocked) is imported and never
- * re-implemented; the runner only supplies its I/O (sessions, tails, clock,
- * policy, injection) — each an injectable seam so runner.test.ts drives real
- * synthetic sessions without a live terminal.
+ * The pure logic (classifyTerminal) is imported and never re-implemented; the
+ * runner only supplies its I/O (sessions, tails, clock, policy, the agent decider,
+ * injection) — each an injectable seam so runner.test.ts drives real synthetic
+ * sessions without a live terminal or a real `agents run`.
  */
 import type { ActiveSession } from '../session/active.js';
 import { type PresenceTransition } from '../session/presence.js';
 import { type InjectRail, type InjectResult, type InjectTarget } from '../terminal/index.js';
 import { type StallStatus, type WatchdogCandidate } from './watchdog.js';
+import { type WatchdogAgentDecider } from './watchdog-agent.js';
 import { type OpenBlock } from '../feed/feed.js';
 import { type RotateGateResult, type RotatePhase, type RotateState } from './rotate.js';
 /** Per-session policy sentinel. `keep` is the default (watchdog may nudge). */
@@ -52,16 +57,7 @@ export interface WatchdogTickOptions {
     nudge?: boolean;
     /** Nudge text delivered into the terminal. Default "Continue." */
     nudgeText?: string;
-    /**
-     * 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 (and the built-in fallback prompt). Default 'claude'. */
+    /** Agent the watchdog decider runs as (and the built-in prompt). Default 'claude'. */
     smartAgent?: string;
     /** Threshold overrides. Missing fields fall back to DEFAULT_THRESHOLDS. */
     thresholds?: Partial<WatchdogThresholds>;
@@ -82,13 +78,20 @@ export interface WatchdogTickOptions {
     /** 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.
+     * The decider seam: given an idle candidate, decide nudge vs skip and craft the
+     * message. Production leaves this unset — the tick judges every idle session in
+     * ONE batched `agents run … --mode plan` call (watchdog-agent.ts). Tests inject a
+     * synthetic per-candidate decider so the decision path is exercised without
+     * shelling out.
      */
     smartDecider?: SmartDecider;
+    /**
+     * The batched agent decider used in production (all idle candidates → one call).
+     * Default `makeWatchdogAgentDecider`. Tests inject one (e.g. returning an empty
+     * map) to exercise the batched path and the no-verdict fallback without shelling
+     * out. Ignored when `smartDecider` (the per-candidate test seam) is set.
+     */
+    agentDecider?: WatchdogAgentDecider;
     /** 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. */
@@ -206,31 +209,19 @@ 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. */
+/** A decision for one idle session. `text` overrides the default nudge text. */
 export interface NudgeDecision {
     nudge: boolean;
     reason: string;
     text?: string;
     /**
-     * Set to `true` when the brain (smart decider) explicitly concluded the session
-     * needs the human — as opposed to a cheap deterministic skip (session is done,
-     * not stalled, etc.). Only `true` when the brain escalation path ran and returned
-     * `nudge: false`. The watchdog uses this to gate the self-file reminder: a
-     * "session is done" skip does NOT trigger a reminder.
+     * On a skip, `true` = the agent judged the session genuinely needs the human
+     * (surface it — self-file reminder / owner page); `false` / absent = idle-and-
+     * done, leave it alone. Gates the self-file reminder so a finished session is
+     * never poked.
      */
     needsHuman?: boolean;
 }
-/**
- * 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

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