@phnx-labs/agents-cli 1.20.74 → 1.20.76

package/dist/lib/versions.d.ts

@@ -444,8 +444,15 @@ export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: s
  * the exact failure this repairs. Agents with a global/native binary (grok,
  * droid) have no such tarball and are returned unchanged.
  */
-export declare function ensureAgentRunnable(agent: AgentId, version: string, log?: (message: string) => void): Promise<string | null>;
-export declare function healBrokenDefaultLaunches(log?: (m: string) => void): Promise<string[]>;
+export declare function ensureAgentRunnable(agent: AgentId, version: string, log?: (message: string) => void, opts?: {
+    allowDefaultSwitch?: boolean;
+}): Promise<string | null>;
+export declare function healBrokenDefaultLaunches(log?: (m: string) => void, opts?: {
+    allowDefaultSwitch?: boolean;
+}): Promise<{
+    repaired: string[];
+    unhealed: string[];
+}>;
 /** Outcome of syncing resources to a version home, keyed by resource type. */
 export interface SyncResult {
     commands: boolean;

package/dist/lib/versions.js

@@ -37,7 +37,7 @@ import { importInstallScriptBinary } from './import.js';
 import { IS_WINDOWS, composeWin32CommandLine } from './platform/index.js';
 import { listInstalledSubagents } from './subagents.js';
 import { listInstalledWorkflows } from './workflows.js';
-import { pruneVersionHomeHookEntriesFromSettings } from './hooks.js';
+import { parseHookManifest, registerHooksToSettings, selectHookManifest, pruneVersionHomeHookEntriesFromSettings } from './hooks.js';
 import { supports, explainSkip } from './capabilities.js';
 import { discoverPlugins, marketplaceSpecForName } from './plugins.js';
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
@@ -2150,7 +2150,17 @@ export async function verifyInstalledBinaryLaunches(agent, version) {
  * the exact failure this repairs. Agents with a global/native binary (grok,
  * droid) have no such tarball and are returned unchanged.
  */
-export async function ensureAgentRunnable(agent, version, log) {
+export async function ensureAgentRunnable(agent, version, log, opts) {
+    // Whether this heal may REPOINT the global default (adopt another version, or
+    // install `latest` and pin it). Interactive callers (`agents run`, `agents
+    // add`) allow it. The daemon's unattended 6-hourly launch-health pass sets
+    // this false: a background pass that silently switches the default installs a
+    // fresh version home → a fresh, empty Claude credential scope (macOS keychain
+    // keyed off CLAUDE_CONFIG_DIR; Linux per-version token file), i.e. an
+    // "unprovoked logout" at a time uncorrelated with anything the user did. In
+    // refuse-mode we still repair the CURRENT default in place (no scope change),
+    // but never repoint — we return null so the caller can alert instead.
+    const allowDefaultSwitch = opts?.allowDefaultSwitch ?? true;
     const cfg = AGENTS[agent];
     if (!cfg?.npmPackage)
         return version;
@@ -2172,6 +2182,14 @@ export async function ensureAgentRunnable(agent, version, log) {
         log?.(`${cfg.name}@${version} is an isolated install and could not be repaired — leaving your default ${cfg.name} untouched.`);
         return null;
     }
+    // In-place repair failed → normally adopt another installed version and repoint
+    // the default. When default-switching is disallowed (unattended daemon pass),
+    // refuse: repointing would swap the live credential scope out from under the
+    // user with no signal. Surface it so the caller can notify.
+    if (!allowDefaultSwitch) {
+        log?.(`${cfg.name}@${version} won't launch and could not be repaired in place — NOT repointing your default ${cfg.name} unattended. Run \`agents use ${agent} <version>\` or \`agents add ${agent}@latest\` to choose one.`);
+        return null;
+    }
     // In-place repair failed → adopt another installed version that launches.
     // Isolated copies are excluded: they are deliberately not promotable.
     const others = listInstalledVersions(agent)
@@ -2221,14 +2239,18 @@ export async function ensureAgentRunnable(agent, version, log) {
  * `agents run` hits a raw ENOENT — the run-time heal (ensureAgentRunnable) only
  * fires once a run is already starting; this catches it in the background.
  *
- * Returns a label (`agent@broken→healed`) for each version actually repaired, so
- * the daemon can log/notify. A version that already launches costs one cheap
- * `--version` probe and is left untouched.
+ * Returns `{ repaired, unhealed }`: `repaired` is a label (`agent@broken→healed`)
+ * for each version actually fixed; `unhealed` is `agent@version` for each broken
+ * default that could not be fixed (including, under `allowDefaultSwitch:false`,
+ * one that was deliberately not repointed), so the daemon can log/notify. A
+ * version that already launches costs one cheap `--version` probe and is left
+ * untouched.
  */
 const failedRepairAt = new Map();
 const REPAIR_COOLDOWN_MS = 24 * 60 * 60_000;
-export async function healBrokenDefaultLaunches(log) {
+export async function healBrokenDefaultLaunches(log, opts) {
     const repaired = [];
+    const unhealed = [];
     for (const agent of Object.keys(AGENTS)) {
         if (!AGENTS[agent].npmPackage)
             continue; // native/global agents have no gutted-tarball failure mode
@@ -2248,16 +2270,17 @@ export async function healBrokenDefaultLaunches(log) {
             continue;
         }
         log?.(`${AGENTS[agent].name}@${version} won't launch — repairing…`);
-        const healed = await ensureAgentRunnable(agent, version, log);
+        const healed = await ensureAgentRunnable(agent, version, log, opts);
         if (healed) {
             failedRepairAt.delete(key);
             repaired.push(`${agent}@${version}${healed === version ? '' : `→${healed}`}`);
         }
         else {
             failedRepairAt.set(key, Date.now());
+            unhealed.push(key);
         }
     }
-    return repaired;
+    return { repaired, unhealed };
 }
 async function getCliVersionFromPath(agent) {
     const agentConfig = AGENTS[agent];
@@ -2640,6 +2663,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             const hooksToSync = selection
                 ? resolveSelection(selection.hooks, available.hooks)
                 : available.hooks;
+            let hookManifest = {};
             if (hooksToSync.length > 0) {
                 const r = hooksWriter.write({ version, versionHome, selection: hooksToSync, cwd });
                 // Remove orphan files from version home. The trusted set is the
@@ -2657,6 +2681,11 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                     }
                 }
                 result.hooks = r.synced.length > 0;
+                hookManifest = selectHookManifest(parseHookManifest(), hooksToSync);
+            }
+            const hooksInScope = !userPassedSelection || selection?.hooks !== undefined;
+            if (agent === 'opencode' && hooksInScope) {
+                registerHooksToSettings(agent, versionHome, hookManifest);
             }
         }
     }

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

@@ -0,0 +1,43 @@
+/** Same path the Factory reader pulls (apps/factory/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';
+/** JSONL row shape — a verbatim replica of the Factory reader's WatchdogEvent. */
+export interface WatchdogEvent {
+    ts: number;
+    kind: WatchdogEventKind;
+    terminalId?: string;
+    agentType?: string;
+    message: string;
+    reason?: string;
+    /** For 'tick' events: the session lines the watchdog actually read. */
+    tailLines?: string[];
+    /** For 'tick' / 'decision' events: how long the terminal had been stalled. */
+    stalledForMs?: number;
+    /** Carried so the UI can show what the agent was stuck on. */
+    lastUserMessage?: string;
+    lastAssistantMessage?: string;
+    /** For a 'decision'/'nudge' that injects: the exact text delivered. */
+    nudgeText?: string;
+}
+/** Serialize one event to a JSONL line (no trailing newline). */
+export declare function formatEvent(ev: WatchdogEvent): string;
+/**
+ * Cap on retained log lines. Mirrors the Factory reader's expectation that the
+ * writer trims (watchdogLog.ts trimToLast). Large enough to keep a useful
+ * history, small enough to bound the file the UI polls.
+ */
+export declare const WATCHDOG_LOG_MAX_LINES = 2000;
+/** Trim a JSONL body to the last `maxLines` events (same logic as the reader). */
+export declare function trimToLast(text: string, maxLines: number): string;
+/**
+ * Append events to the log under a file lock, trimming to WATCHDOG_LOG_MAX_LINES
+ * so the file never grows unbounded. Concurrent watchdog ticks share the lock so
+ * their appends never interleave into a corrupt line. Best-effort: a filesystem
+ * error is swallowed (the Factory card tolerates a stale/missing log), never
+ * throwing into the tick.
+ */
+export declare function appendWatchdogEvents(events: WatchdogEvent[], opts?: {
+    logPath?: string;
+    maxLines?: number;
+}): void;

package/dist/lib/watchdog/log.js

@@ -0,0 +1,69 @@
+/**
+ * Canonical watchdog event log (watchdog-brain-v2).
+ *
+ * The Factory Floor renders a read-only "Watchdog activity" card from the JSONL
+ * feed at ~/.agents/.cache/logs/watchdog.log. That feed was historically written
+ * by the retired extension-side watchdog; now the always-on CLI watchdog owns it.
+ *
+ * The event SHAPE here is a deliberate, verbatim replica of the reader in
+ * apps/factory/src/core/watchdogLog.ts (WatchdogEvent / WatchdogEventKind /
+ * WATCHDOG_LOG_PATH / the trim cap). The repo forbids cross-app imports
+ * (CLAUDE.md repo map), so the two files are kept in sync by hand — a change to
+ * the Factory reader's shape must be mirrored here. There is no import between
+ * them.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { withFileLock, atomicWriteFileSync, ensureLockTarget } from '../fs-atomic.js';
+/** Same path the Factory reader pulls (apps/factory/src/core/watchdogLog.ts). */
+export const WATCHDOG_LOG_PATH = path.join(os.homedir(), '.agents', '.cache', 'logs', 'watchdog.log');
+/** Serialize one event to a JSONL line (no trailing newline). */
+export function formatEvent(ev) {
+    return JSON.stringify(ev);
+}
+/**
+ * Cap on retained log lines. Mirrors the Factory reader's expectation that the
+ * writer trims (watchdogLog.ts trimToLast). Large enough to keep a useful
+ * history, small enough to bound the file the UI polls.
+ */
+export const WATCHDOG_LOG_MAX_LINES = 2000;
+/** Trim a JSONL body to the last `maxLines` events (same logic as the reader). */
+export function trimToLast(text, maxLines) {
+    const lines = text.split('\n').filter((l) => l.trim().length > 0);
+    if (lines.length <= maxLines)
+        return lines.join('\n') + (lines.length ? '\n' : '');
+    return lines.slice(lines.length - maxLines).join('\n') + '\n';
+}
+/**
+ * Append events to the log under a file lock, trimming to WATCHDOG_LOG_MAX_LINES
+ * so the file never grows unbounded. Concurrent watchdog ticks share the lock so
+ * their appends never interleave into a corrupt line. Best-effort: a filesystem
+ * error is swallowed (the Factory card tolerates a stale/missing log), never
+ * throwing into the tick.
+ */
+export function appendWatchdogEvents(events, opts = {}) {
+    if (events.length === 0)
+        return;
+    const logPath = opts.logPath ?? WATCHDOG_LOG_PATH;
+    const maxLines = opts.maxLines ?? WATCHDOG_LOG_MAX_LINES;
+    const lockPath = path.join(path.dirname(logPath), '.watchdog.log.lock');
+    try {
+        ensureLockTarget(lockPath);
+        withFileLock(lockPath, () => {
+            let existing = '';
+            try {
+                existing = fs.readFileSync(logPath, 'utf8');
+            }
+            catch {
+                /* first write — no file yet */
+            }
+            const appended = events.map(formatEvent).join('\n') + '\n';
+            const body = trimToLast(existing + appended, maxLines);
+            atomicWriteFileSync(logPath, body);
+        });
+    }
+    catch {
+        /* best-effort: never let logging break a tick */
+    }
+}

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

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

package/dist/lib/watchdog/routine.js

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

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

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