@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/commands/view.js

@@ -4,13 +4,13 @@ import { visibleWidth, termLink } from '../lib/format.js';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanagedCliState, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { loginHint } from '../lib/signin-badge.js';
 import { machineId } from '../lib/machine-id.js';
 import { authCacheKey, formatCheckedAge, readAuthHealthCache } from '../lib/auth-health.js';
 import { agentReportsUsage, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { resolveVersionFilter, AgentSpecError } from '../lib/agent-spec/index.js';
@@ -23,6 +23,7 @@ import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
 import { getConfiguredRunStrategy } from '../lib/rotate.js';
 import { resolveRunDefaults } from '../lib/run-defaults.js';
+import { resolveConfiguredModel } from '../lib/models.js';
 import { listProfiles, profileSummary } from '../lib/profiles.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
@@ -243,9 +244,27 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         ? `Checking ${agentLabel(filterAgentId)} agents...`
         : 'Checking installed agents...';
     const spinner = ora({ text: spinnerText, isSilent: !process.stdout.isTTY }).start();
-    const cliStates = await getAllCliStates();
-    spinner.stop();
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
+    // A globally-installed CLI is superseded only by a NORMAL managed version — that
+    // is when agents-cli owns the launcher and a "global" row would just be our own
+    // shim reported back. `--isolated` promises the opposite: no default, no bare
+    // shim, no adopted launcher, the user's own `~/.<agent>` untouched. So an
+    // isolated-only install must not make that still-live global CLI disappear from
+    // `agents view` — the two are genuinely separate installs and both get listed.
+    const hasNonIsolatedVersion = (agentId) => listInstalledVersions(agentId).some((v) => !isVersionIsolated(agentId, v));
+    // Every `cliStates` read in this function feeds the "Not Managed by Agents CLI"
+    // block, so resolve it the way that block means it: the user's own CLI on PATH.
+    // `getCliState` would answer with a version-dir install — including an isolated
+    // copy that is deliberately absent from PATH — and print it as "(global)".
+    //
+    // Resolved only for agents that can actually reach that block. `getCliState`
+    // deliberately avoids subprocesses for a version-managed agent, and PATH
+    // resolution costs a `<cli> --version` spawn on a cold cache — so probing an
+    // agent whose global row is suppressed anyway would be pure added latency.
+    const cliStates = Object.fromEntries(await Promise.all(agentsToShow
+        .filter((agentId) => !hasNonIsolatedVersion(agentId))
+        .map(async (agentId) => [agentId, await getUnmanagedCliState(agentId)])));
+    spinner.stop();
     const showPaths = !!filterAgentId;
     const profilesByAgent = getProfilesByAgent(filterAgentId);
     const profileSummaries = [...profilesByAgent.values()].flat();
@@ -276,19 +295,18 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
     const infoFetches = [];
     const globalInfoFetches = [];
     for (const agentId of agentsToShow) {
-        const versions = listInstalledVersions(agentId);
-        if (versions.length > 0) {
-            for (const ver of versions) {
-                const home = getVersionHomePath(agentId, ver);
-                infoFetches.push(getAccountInfo(agentId, home).then((info) => ({
-                    agentId,
-                    version: ver,
-                    home,
-                    info,
-                })));
-            }
+        for (const ver of listInstalledVersions(agentId)) {
+            const home = getVersionHomePath(agentId, ver);
+            infoFetches.push(getAccountInfo(agentId, home).then((info) => ({
+                agentId,
+                version: ver,
+                home,
+                info,
+            })));
         }
-        else {
+        // Mirrors the classification below: fetch the global account whenever the
+        // global install will still be rendered (no versions at all, or isolated-only).
+        if (!hasNonIsolatedVersion(agentId)) {
             globalInfoFetches.push(getAccountInfo(agentId).then((info) => ({
                 agentId,
                 cliVersion: cliStates[agentId]?.version || null,
@@ -356,10 +374,12 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         if (versions.length > 0) {
             versionManaged.push(agentId);
         }
-        else if (cliState?.installed) {
-            globallyInstalled.push(agentId);
+        if (cliState?.installed) {
+            // Isolated-only installs sit alongside the global CLI rather than replacing it.
+            if (!hasNonIsolatedVersion(agentId))
+                globallyInstalled.push(agentId);
         }
-        else if (hasProfiles) {
+        else if (versions.length === 0 && hasProfiles) {
             profileOnly.push(agentId);
         }
     }
@@ -376,6 +396,22 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             liveVersionByAgent.set(agentId, live);
     }));
     const displayVersion = (agentId, dirVersion) => liveVersionByAgent.get(agentId) ?? dirVersion;
+    // Uncolored row label, shared by the width pass and the render so padding lines
+    // up. An isolated copy is never the global default (installing one deliberately
+    // records no default), so the two tags can't collide.
+    const versionRowLabel = (agentId, version, globalDefault) => {
+        const shown = displayVersion(agentId, version);
+        if (version === globalDefault)
+            return `${shown} (default)`;
+        if (isVersionIsolated(agentId, version)) {
+            // The isolated default is what a bare `agents run <agent>` reaches, so it is
+            // worth distinguishing from the other isolated copies sitting beside it.
+            return getIsolatedDefault(agentId) === version
+                ? `${shown} (isolated default)`
+                : `${shown} (isolated)`;
+        }
+        return shown;
+    };
     // Show version-managed agents
     if (versionManaged.length > 0) {
         // Calculate column widths across all agents for alignment
@@ -384,13 +420,15 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         let maxPlanWidth = 3;
         let maxUsageWidth = 0;
         let maxStatusWidth = 0;
+        // The configured model sits right after the version, at the same priority.
+        // Resolve once here (fs + catalog reads) and reuse in the render loop.
+        let maxModelWidth = 0;
+        const modelByKey = new Map();
         for (const agentId of versionManaged) {
             const versions = listInstalledVersions(agentId);
             const globalDefault = getGlobalDefault(agentId);
             for (const v of versions) {
-                const shown = displayVersion(agentId, v);
-                const label = v === globalDefault ? `${shown} (default)` : shown;
-                maxVerLabel = Math.max(maxVerLabel, label.length);
+                maxVerLabel = Math.max(maxVerLabel, versionRowLabel(agentId, v, globalDefault).length);
                 const rawInfo = infoMap.get(`${agentId}:${v}`);
                 const info = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 const accountLabel = accountColumnLabel(info);
@@ -398,6 +436,11 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                     maxEmail = Math.max(maxEmail, accountLabel.length);
                 if (info?.plan)
                     maxPlanWidth = Math.max(maxPlanWidth, info.plan.length);
+                const model = resolveConfiguredModel(agentId, v)?.model;
+                if (model) {
+                    modelByKey.set(`${agentId}:${v}`, model);
+                    maxModelWidth = Math.max(maxModelWidth, model.length);
+                }
             }
             // Profile rows share these columns with version rows so they line up.
             for (const profile of profilesByAgent.get(agentId) ?? []) {
@@ -431,7 +474,14 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             const globalDefault = getGlobalDefault(agentId);
             const runStrategy = getConfiguredRunStrategy(agentId);
             const strategyLabel = chalk.gray(` (${runStrategy})`);
-            const noDefaultLabel = !globalDefault ? chalk.yellow(' (no default)') : '';
+            // `(no default)` is a nudge to go set one. It would read as a contradiction
+            // directly above a row tagged `(isolated default)`, and it would be bad
+            // advice besides: for an isolated-only agent the pointer below IS how a
+            // bare `agents run <agent>` resolves, and setting a global default is
+            // precisely what `--isolated` exists to avoid.
+            const noDefaultLabel = !globalDefault && !getIsolatedDefault(agentId)
+                ? chalk.yellow(' (no default)')
+                : '';
             console.log(`  ${chalk.bold(agentLabel(agentId))}${strategyLabel}${noDefaultLabel}`);
             // Sort versions with default first, then by semver descending
             const sortedVersions = [...versions].sort((a, b) => {
@@ -443,16 +493,27 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             });
             for (const version of sortedVersions) {
                 const isDefault = version === globalDefault;
+                const isolated = !isDefault && isVersionIsolated(agentId, version);
+                const isolatedTag = getIsolatedDefault(agentId) === version ? ' (isolated default)' : ' (isolated)';
                 const shown = displayVersion(agentId, version);
-                const base = isDefault ? `${shown} (default)` : shown;
-                const padded = base.padEnd(maxVerLabel);
-                const label = isDefault ? `${shown}${chalk.green(' (default)')}${' '.repeat(maxVerLabel - base.length)}` : padded;
+                const base = versionRowLabel(agentId, version, globalDefault);
+                const tagPad = ' '.repeat(maxVerLabel - base.length);
+                const label = isDefault
+                    ? `${shown}${chalk.green(' (default)')}${tagPad}`
+                    : isolated
+                        ? `${shown}${chalk.gray(isolatedTag)}${tagPad}`
+                        : base.padEnd(maxVerLabel);
                 const rawInfo = infoMap.get(`${agentId}:${version}`);
                 const vInfo = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 const usageKey = getUsageLookupKey(vInfo);
                 const usageInfo = usageKey ? usageByKey.get(usageKey) : undefined;
                 // Build columns, trimming trailing whitespace when columns are empty
                 const parts = [`    ${label}`];
+                // Configured model — same priority as the version, right beside it.
+                if (maxModelWidth > 0) {
+                    const model = modelByKey.get(`${agentId}:${version}`) ?? '';
+                    parts.push(chalk.yellow(model.padEnd(maxModelWidth)));
+                }
                 const hasEmail = !!vInfo?.email;
                 const signedIn = !!vInfo?.signedIn;
                 const usageUnavailable = agentReportsUsage(agentId) && signedIn && !usageInfo?.snapshot;
@@ -462,12 +523,11 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 // Otherwise it reflects install time (misleading "just now" for fresh installs).
                 const activeStr = vInfo && hasEmail ? formatLastActive(vInfo.lastActive) : '';
                 const hasActive = activeStr.length > 0;
+                // The model now has its own column above; keep only the run mode here.
                 const runDefaults = resolveRunDefaults(agentId, version);
                 const runDefaultBits = [];
                 if (runDefaults.mode)
                     runDefaultBits.push(`mode:${runDefaults.mode}`);
-                if (runDefaults.model)
-                    runDefaultBits.push(`model:${runDefaults.model}`);
                 if (!hasEmail && !hasUsage && !signedIn) {
                     // Installed but never signed in
                     parts.push(chalk.gray('(logged out — log in with: ' + loginHint(agentId) + ')'));
@@ -509,10 +569,12 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             // No status badge, no last-active — profiles don't accumulate usage state.
             for (const profile of profilesByAgent.get(agentId) ?? []) {
                 const nameCol = chalk.cyan(profile.name.padEnd(maxVerLabel));
+                // Pad the model column so profile rows line up with version rows.
+                const modelPad = maxModelWidth > 0 ? `${' '.repeat(maxModelWidth)}  ` : '';
                 const authCol = chalk.gray(profile.auth.padEnd(maxEmail));
                 const usageEquivalent = profileKindAndModel(profile.model, maxPlanWidth);
                 const usagePad = ' '.repeat(Math.max(0, maxUsageWidth - visibleWidth(usageEquivalent)));
-                console.log(`    ${nameCol}  ${authCol}  ${chalk.gray(usageEquivalent + usagePad)}`);
+                console.log(`    ${nameCol}  ${modelPad}${authCol}  ${chalk.gray(usageEquivalent + usagePad)}`);
                 if (showPaths) {
                     console.log(chalk.gray(`      ${profile.path}`));
                 }
@@ -580,7 +642,9 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             // Profile rows under a globally-installed harness. Use a simpler
             // alignment here since this section doesn't share column state with
             // the version-managed block.
-            const profilesHere = profilesByAgent.get(agentId) ?? [];
+            // An isolated-only agent now appears in BOTH blocks; its profiles already
+            // rendered under the version-managed one, so don't print them twice.
+            const profilesHere = versionManaged.includes(agentId) ? [] : (profilesByAgent.get(agentId) ?? []);
             if (profilesHere.length > 0) {
                 const nameWidth = Math.max(globalMaxVerLabel, ...profilesHere.map((p) => p.name.length));
                 const authWidth = Math.max(...profilesHere.map((p) => p.auth.length));
@@ -833,9 +897,12 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         const accountLabel = accountColumnLabel(accountInfo);
         const emailStr = accountLabel ? chalk.cyan(`  ${accountLabel}`) : '';
         const status = chalk.green(version);
+        // Configured model sits right beside the version, same priority (no label).
+        const configuredModel = resolveConfiguredModel(agentId, version);
+        const modelStr = configuredModel ? chalk.yellow(`  ${configuredModel.model}`) : '';
         const usageStr = formatUsageSummary(usageInfo.snapshot?.plan ?? accountInfo.plan, null);
         const usagePart = usageStr ? `  ${usageStr}` : '';
-        console.log(`  ${colorAgent(agentId)(AGENTS[agentId].name.padEnd(14))} ${status}${emailStr}${usagePart}`);
+        console.log(`  ${colorAgent(agentId)(AGENTS[agentId].name.padEnd(14))} ${status}${modelStr}${emailStr}${usagePart}`);
         const usageLines = formatUsageSection(usageInfo);
         if (usageLines.length > 0) {
             console.log();
@@ -1173,6 +1240,7 @@ async function collectAgentsJson(filterAgentId, resourceSections) {
                 : [],
             lastActive: info.lastActive ? info.lastActive.toISOString() : null,
             path: getVersionDir(agentId, version),
+            configuredModel: resolveConfiguredModel(agentId, version),
         };
         if (wantResources && resourceSync) {
             entry.resources = collectVersionResources(agentId, home, process.cwd(), cliStates?.[agentId]?.installed ?? false, resourceSections, resourceSync);

package/dist/commands/watchdog.d.ts

@@ -8,10 +8,15 @@
  *
  *   agents watchdog                    one tick, dry — prints what it WOULD nudge/skip and why
  *   agents watchdog --nudge            one tick, actually injects (explicit opt-in)
- *   agents watchdog --watch            daemon loop (poll every --interval)
+ *   agents watchdog --watch            manual poll loop (dry unless --nudge)
  *   agents watchdog --json             machine-readable tick output (for the menu-bar)
- *   agents watchdog enable|disable     flip the global auto-nudge sentinel (default OFF)
+ *   agents watchdog enable|disable     turn the always-on watchdog routine on/off
  *   agents watchdog policy <id> <p>    per-session policy: off | keep | handsoff
+ *
+ * The always-on watchdog is a daemon-fired ROUTINE, not a private sentinel + a
+ * hand-rolled loop: `enable` creates/enables a `watchdog` command routine
+ * (`agents watchdog --nudge` every couple of minutes) and reloads the daemon;
+ * `disable` pauses it. See ../lib/watchdog/routine.ts.
  */
 import type { Command } from 'commander';
 /** Register the `agents watchdog` command tree. */

package/dist/commands/watchdog.js

@@ -8,41 +8,41 @@
  *
  *   agents watchdog                    one tick, dry — prints what it WOULD nudge/skip and why
  *   agents watchdog --nudge            one tick, actually injects (explicit opt-in)
- *   agents watchdog --watch            daemon loop (poll every --interval)
+ *   agents watchdog --watch            manual poll loop (dry unless --nudge)
  *   agents watchdog --json             machine-readable tick output (for the menu-bar)
- *   agents watchdog enable|disable     flip the global auto-nudge sentinel (default OFF)
+ *   agents watchdog enable|disable     turn the always-on watchdog routine on/off
  *   agents watchdog policy <id> <p>    per-session policy: off | keep | handsoff
+ *
+ * The always-on watchdog is a daemon-fired ROUTINE, not a private sentinel + a
+ * hand-rolled loop: `enable` creates/enables a `watchdog` command routine
+ * (`agents watchdog --nudge` every couple of minutes) and reloads the daemon;
+ * `disable` pauses it. See ../lib/watchdog/routine.ts.
  */
 import chalk from 'chalk';
-import * as fs from 'fs';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { getRuntimeStateDir } from '../lib/state.js';
+import { setJobEnabled } from '../lib/routines.js';
+import { ensureWatchdogRoutine, isWatchdogRoutineEnabled, watchdogRoutineExists, WATCHDOG_ROUTINE_NAME, WATCHDOG_ROUTINE_SCHEDULE, } from '../lib/watchdog/routine.js';
 import { runWatchdogTick, writePolicySentinel, DEFAULT_THRESHOLDS, } from '../lib/watchdog/runner.js';
 /** Default state dir the runner and these subcommands share. */
 function stateDir() {
     return path.join(getRuntimeStateDir(), 'watchdog');
 }
-/** Global auto-nudge sentinel — present = enabled. Default OFF (opt-in). */
-function enabledSentinelPath() {
-    return path.join(stateDir(), 'enabled');
-}
-function isGloballyEnabled() {
-    return fs.existsSync(enabledSentinelPath());
-}
-function setGloballyEnabled(on) {
-    const p = enabledSentinelPath();
-    if (on) {
-        fs.mkdirSync(path.dirname(p), { recursive: true });
-        fs.writeFileSync(p, 'enabled\n');
-    }
-    else {
-        try {
-            fs.rmSync(p);
-        }
-        catch { /* already off */ }
+/**
+ * (Re)load the daemon so a just-changed routine takes effect without a restart.
+ * Best-effort: enabling starts the daemon if it is not running, then SIGHUPs it.
+ * Dynamic import keeps daemon.ts's heavy deps off the watchdog command's load path.
+ */
+async function reloadDaemonForRoutine(startIfStopped) {
+    const { isDaemonRunning, ensureDaemonStarted, signalDaemonReload } = await import('../lib/daemon.js');
+    if (isDaemonRunning()) {
+        signalDaemonReload();
+        return;
     }
+    if (startIfStopped)
+        ensureDaemonStarted();
 }
 /** Parse a duration flag ("60s", "5m", "1h") to ms, or fall back to `fallbackMs`. */
 function durationMsOr(raw, fallbackMs) {
@@ -97,7 +97,7 @@ export function registerWatchdogCommand(program) {
         .command('watchdog')
         .description('Auto-nudge stalled agent terminals: detect stalls, resolve the exact split, inject "Continue." — no menu-bar needed.')
         .option('--nudge', 'Actually inject (default is a dry run that only reports what it would do)')
-        .option('--watch', 'Daemon loop: run a tick every --interval until interrupted')
+        .option('--watch', 'Manual poll loop: run a tick every --interval (dry unless --nudge; the always-on path is `watchdog enable`)')
         .option('--interval <dur>', 'Poll interval in --watch mode (e.g. 30s, 1m)', '30s')
         .option('--stall <dur>', 'Idle time before a session counts as stalled', humanMs(DEFAULT_THRESHOLDS.stallMs))
         .option('--cooldown <dur>', 'Minimum time between nudges to the same session', humanMs(DEFAULT_THRESHOLDS.cooldownMs))
@@ -113,12 +113,11 @@ export function registerWatchdogCommand(program) {
             cooldownMs: durationMsOr(opts.cooldown, DEFAULT_THRESHOLDS.cooldownMs),
             dormantMs: durationMsOr(opts.dormant, DEFAULT_THRESHOLDS.dormantMs),
         };
-        // Injection gate: --nudge is the explicit per-run opt-in; the global sentinel
-        // enables the automatic daemon. Default OFF: bare `agents watchdog` is dry.
-        // Re-read the sentinel every tick so a running `--watch` daemon reflects a
-        // later `agents watchdog enable`/`disable` (or the Swift menu-bar toggle)
-        // from another shell without a restart.
-        const computeWillInject = () => opts.nudge === true || (opts.watch === true && isGloballyEnabled());
+        // Injection gate: --nudge is the explicit opt-in to actually inject. Bare
+        // `agents watchdog` (and `--watch` without `--nudge`) is dry. The always-on
+        // path is the daemon routine, which runs `agents watchdog --nudge` — so the
+        // routine's enabled state IS the on/off switch, not a flag read here.
+        const computeWillInject = () => opts.nudge === true;
         const tickOnce = async (willInject) => runWatchdogTick({
             nudge: willInject,
             nudgeText: opts.text,
@@ -137,11 +136,11 @@ export function registerWatchdogCommand(program) {
                 printTick(result, willInject);
             return;
         }
-        // Daemon loop.
+        // Manual poll loop (for ad-hoc use; the always-on path is `enable`'s routine).
         const intervalMs = durationMsOr(opts.interval, 30_000);
         if (!computeWillInject() && !opts.json) {
-            console.log(chalk.yellow(`watchdog --watch is DETECT-ONLY (global auto-nudge is ${isGloballyEnabled() ? 'on' : 'off'}). ` +
-                `Pass --nudge or run 'agents watchdog enable' to inject.`));
+            console.log(chalk.yellow(`watchdog --watch is DETECT-ONLY. Pass --nudge to inject, ` +
+                `or run 'agents watchdog enable' for the always-on daemon routine.`));
         }
         // eslint-disable-next-line no-constant-condition
         while (true) {
@@ -163,50 +162,67 @@ export function registerWatchdogCommand(program) {
       # One tick, actually inject "Continue." into stalled+addressable splits
       agents watchdog --nudge
 
-      # Watch loop every 30s, tighter stall threshold
-      agents watchdog --watch --interval 30s --stall 60s --cooldown 5m
+      # Manual watch loop every 30s, tighter stall threshold (ad-hoc; dry unless --nudge)
+      agents watchdog --watch --nudge --interval 30s --stall 60s --cooldown 5m
 
       # Machine-readable for the menu-bar
       agents watchdog --json
 
-      # Turn on the global auto-nudge (so --watch injects without --nudge)
+      # Turn on the ALWAYS-ON watchdog (a daemon-fired routine)
       agents watchdog enable
 
       # Leave one session detected-but-untouched
       agents watchdog policy <sessionId> handsoff
     `,
         notes: `
-      Decision path (default, deterministic): a session is nudged only when its
-      transcript tail shows it ANNOUNCED an action but no tool call followed
-      (promise-without-toolcall) AND it is not waiting on the user. Completions and
-      open questions are skipped.
+      Decision path: a cheap deterministic pre-filter resolves the obvious cases
+      (clearly complete -> skip; a clear promise-without-toolcall -> nudge) and
+      ESCALATES the judgment-heavy cases -- a session parked on a question, or an
+      ambiguous stall -- to a smart brain. The brain drives the agent to finish
+      end-to-end when it asked a needless / already-authorized question or paused
+      with work left, and leaves it for the human on genuine cases (credentials,
+      an irreversible or outward-facing action, a real ambiguous decision, or a
+      completed task). The brain is a customizable 'watchdog' workflow (drop a
+      WORKFLOW.md in project/user workflows/ to override the prompt + model);
+      absent one, the built-in prompt runs via 'agents run --mode plan'. Pass
+      --smart to force every stalled candidate through the brain.
 
-      Safety gate: a nudge is delivered ONLY when the resolver can name the EXACT
-      split the agent lives in (tmux / iTerm / IDE terminal). Un-addressable stalls
-      (e.g. Ghostty with no tmux) are flagged for the menu-bar and SKIPPED — never
-      a guessed or frontmost target.
+      Delivery (answer-router): a running agent is steered via its mailbox; a
+      parked-on-question agent is answered into its EXACT split -- tmux / iTerm /
+      an IDE integrated terminal (VS Codium / Cursor / VS Code) -- or re-entered
+      via resume when headless. A parked agent with no addressable rail (e.g.
+      Ghostty with no tmux) is flagged for the menu-bar and SKIPPED -- never a
+      guessed or frontmost target.
 
-      Policy: global auto-nudge defaults OFF (opt-in via 'enable' or --nudge).
-      Per-session: off (ignore), keep (default), handsoff (detect + flag, never inject).
+      Always-on: 'agents watchdog enable' creates + enables a 'watchdog' command
+      routine ('${WATCHDOG_ROUTINE_SCHEDULE}' -> agents watchdog --nudge) and reloads the
+      daemon; 'disable' pauses it. Inspect it with 'agents routines list'. Defaults
+      OFF. Per-session policy: off (ignore), keep (default), handsoff (detect + flag).
 
       State (tray-readable): ${path.join('~/.agents/.cache/state/watchdog', '{nudges,flags,last-tick}.json')}
     `,
     });
-    // --- global enable/disable/status -----------------------------------------
+    // --- always-on enable/disable/status (backed by the daemon routine) --------
     cmd.command('enable')
-        .description('Turn ON global auto-nudge (so `agents watchdog --watch` injects without --nudge).')
-        .action(() => {
-        setGloballyEnabled(true);
-        console.log(chalk.green('watchdog: global auto-nudge ENABLED'));
+        .description('Turn ON the always-on watchdog: create/enable the `watchdog` routine and (re)load the daemon.')
+        .action(async () => {
+        ensureWatchdogRoutine(true);
+        await reloadDaemonForRoutine(true);
+        console.log(chalk.green(`watchdog: ENABLED — routine '${WATCHDOG_ROUTINE_NAME}' fires ${WATCHDOG_ROUTINE_SCHEDULE} (agents watchdog --nudge)`));
     });
     cmd.command('disable')
-        .description('Turn OFF global auto-nudge (back to detect-only unless --nudge is passed).')
-        .action(() => {
-        setGloballyEnabled(false);
-        console.log(chalk.yellow('watchdog: global auto-nudge DISABLED'));
+        .description('Turn OFF the always-on watchdog (pause the `watchdog` routine).')
+        .action(async () => {
+        if (!watchdogRoutineExists()) {
+            console.log(chalk.dim('watchdog: already off (no routine)'));
+            return;
+        }
+        setJobEnabled(WATCHDOG_ROUTINE_NAME, false);
+        await reloadDaemonForRoutine(false);
+        console.log(chalk.yellow('watchdog: DISABLED (routine paused)'));
     });
     cmd.command('status')
-        .description('Show whether global auto-nudge is on and where state is written.')
+        .description('Show whether the always-on watchdog routine is enabled and where state is written.')
         .option('--json', 'Emit status as JSON (for the menu-bar / scripts)')
         .action((_opts, command) => {
         // The parent `watchdog` command also declares --json and greedily parses it
@@ -214,12 +230,12 @@ export function registerWatchdogCommand(program) {
         // parent, not this subcommand. optsWithGlobals() merges both levels, so we
         // read it correctly regardless of which command commander bound it to.
         const json = command.optsWithGlobals().json === true;
-        const on = isGloballyEnabled();
+        const on = isWatchdogRoutineEnabled();
         if (json) {
-            console.log(JSON.stringify({ enabled: on, stateDir: stateDir() }));
+            console.log(JSON.stringify({ enabled: on, routine: WATCHDOG_ROUTINE_NAME, stateDir: stateDir() }));
             return;
         }
-        console.log(`global auto-nudge: ${on ? chalk.green('ON') : chalk.dim('off')}`);
+        console.log(`always-on watchdog: ${on ? chalk.green('ON') : chalk.dim('off')} (routine '${WATCHDOG_ROUTINE_NAME}')`);
         console.log(`state dir: ${chalk.dim(stateDir())}`);
     });
     // --- per-session policy ----------------------------------------------------

package/dist/index.js

@@ -26,11 +26,49 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = path.join(__dirname, '..', 'package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
+import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './lib/secrets/sync-commands.js';
 if (process.argv[2] === '__vault-age-helper') {
     const { runVaultAgeHelperCli } = await import('./lib/secrets/vault-age-helper.js');
     await runVaultAgeHelperCli();
     process.exit(process.exitCode ?? 0);
 }
+// Synchronous secrets-broker clients (src/lib/secrets/agent.ts). These are the
+// hot read path: `readAndResolveBundleEnv` is synchronous all the way down, so
+// it can't await a socket round-trip — it spawns one of these and reads the
+// exit code (0 = hit/alive, 3 = miss/down).
+//
+// Intercepted HERE, before commander and before the startup STATEMENTS, for the
+// same reason as __daemon-run and __vault-age-helper above. Everything below
+// this point runs `checkForUpdates()` and `spawnDetachedSync()` on every
+// non-help invocation — so registering these as ordinary hidden subcommands
+// would fire an update check and fork a detached background sync on *every
+// cache hit*, which is both a fork storm on the hot path and a source of stdout
+// writes that could corrupt the JSON payload. Keep them above the line;
+// agent.test.ts asserts this ordering so the block can't drift downward.
+//
+// The tokens are imported from the leaf module sync-commands.ts — the SAME
+// bindings the clients spawn with, so this dispatch and those spawns cannot
+// drift apart. It is a leaf precisely so binding them here is free: importing
+// agent.js would pull the whole secrets graph into every invocation. Matching
+// string literals were the earlier design; a text-scanning test could not
+// reliably catch their divergence, and the divergence is silent — the CLI says
+// "unknown command", the client reads that as "broker down", and every read
+// falls back to a Touch ID prompt.
+//
+// "Before the startup statements", not "before all code": ESM hoists the
+// imports below, so those module bodies evaluate first. They are side-effect
+// free today (no top-level stdout write or spawn) — which is what makes this
+// safe, and worth preserving.
+if (process.argv[2] === SYNC_GET_CMD ||
+    process.argv[2] === SYNC_PING_CMD ||
+    process.argv[2] === SYNC_LOCK_CMD) {
+    const { runAgentGetSync, runAgentPingSync, runAgentLockSync } = await import('./lib/secrets/agent.js');
+    const name = process.argv[3] ?? '';
+    const code = process.argv[2] === SYNC_GET_CMD ? await runAgentGetSync(name)
+        : process.argv[2] === SYNC_PING_CMD ? await runAgentPingSync()
+            : await runAgentLockSync(name);
+    process.exit(code);
+}
 import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, installPackageIntoPrefix, installPackageWithBun, verifyInstalledVersion, refreshAliasShims, downloadVerifiedTarball, } from './lib/self-update.js';
 // Detect dev/working-tree builds and default the noisy startup steps off.
 // Three cases trip this:
@@ -55,9 +93,10 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadResources, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadHq, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadResources, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadHq, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
+import { getCliLaunch } from './lib/cli-entry.js';
 import { emit, redactArgs } from './lib/events.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
@@ -294,7 +333,7 @@ async function showWhatsNew(fromVersion, toVersion) {
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir, getRuntimeStateDir } from './lib/state.js';
 import { resolveBrandName, disabledCommandsForActiveBrand } from './lib/brand.js';
-import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, findAgentsCliInstalls, } from './lib/self-update.js';
+import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, findAgentsCliInstalls, resolveRunningPackageRoot, } from './lib/self-update.js';
 const UPDATE_CHECK_FILE = getUpdateCheckPath();
 /**
  * Warn once when PATH resolves `agents` to a different agents-cli install
@@ -306,7 +345,16 @@ const UPDATE_CHECK_FILE = getUpdateCheckPath();
  */
 function maybeWarnMultiInstall() {
     const sentinel = path.join(getRuntimeStateDir(), 'multi-install-warned');
-    const runningRoot = path.resolve(__dirname, '..');
+    let runningRoot;
+    try {
+        runningRoot = resolveRunningPackageRoot(__dirname);
+    }
+    catch {
+        // Without a real root for the running copy there is nothing to compare
+        // against, and a guess here is exactly what produced the phantom
+        // "/$bunfs" install. This warning is advisory — stay silent instead.
+        return;
+    }
     const byRoot = new Map();
     byRoot.set(runningRoot, { version: VERSION, note: 'running' });
     for (const install of findAgentsCliInstalls(process.env.PATH || '')) {
@@ -370,7 +418,7 @@ function printResolvedPackage(metadata) {
     console.log(chalk.gray(`Integrity: ${metadata.integrity}`));
 }
 async function installResolvedPackage(metadata) {
-    const packageRoot = path.resolve(__dirname, '..');
+    const packageRoot = resolveRunningPackageRoot(__dirname);
     // Download the published tarball and prove its bytes match the registry
     // integrity BEFORE installing anything. A `name@version` spec would let the
     // package manager fetch and install whatever the registry serves with no
@@ -466,9 +514,11 @@ async function promptUpgrade(latestVersion) {
             console.log();
             // Re-exec the verified install's entrypoint and exit. PATH lookup of
             // `agents` could resolve a different copy (dev build, another prefix)
-            // than the one that was just upgraded.
-            const entrypoint = path.resolve(__dirname, '..', 'dist', 'index.js');
-            const result = spawnSync(process.execPath, [entrypoint, ...process.argv.slice(2)], {
+            // than the one that was just upgraded. getCliLaunch resolves the JS-vs-
+            // standalone shape — never hand-roll `[process.execPath, entrypoint]`,
+            // which hands the bun virtual entry to a compiled binary as a bogus arg.
+            const { command, args } = getCliLaunch(process.argv.slice(2));
+            const result = spawnSync(command, args, {
                 stdio: 'inherit',
                 shell: false,
             });
@@ -730,6 +780,7 @@ async function registerAllEagerCommands() {
     await reg(loadWorktree);
     await reg(loadVersions);
     await reg(loadImport);
+    await reg(loadExport);
     await reg(loadPackages);
     await reg(loadRoutines);
     await reg(loadMonitors);
@@ -746,6 +797,7 @@ async function registerAllEagerCommands() {
     await reg(loadStatus);
     registerExecAliasCommand(program);
     await reg(loadProfiles);
+    await reg(loadHarness);
     await reg(loadSecrets);
     await reg(loadLogin);
     await reg(loadWallet);