@phnx-labs/agents-cli 1.22.45 → 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/view-types.d.ts

@@ -28,8 +28,8 @@ export interface ViewJsonVersion {
         resetsAt: string | null;
     }>;
     unavailable?: {
-        reason: 'session_limit';
-        resetsAt: string;
+        reason: 'session_limit' | 'out_of_credits';
+        resetsAt?: string;
     };
     lastActive: string | null;
     path: string;

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