@phnx-labs/agents-cli 1.22.31 → 1.22.33

package/dist/commands/update.js

@@ -0,0 +1,148 @@
+import chalk from 'chalk';
+import { formatAgentError, resolveAgentName } from '../lib/agents.js';
+import { setHelpSections } from '../lib/help.js';
+import { describeInstallation, listInstallations, resolveInstallation, selectUpdateStrategy, supportsPinnedUpdate, updateInstallation, } from '../lib/installations/index.js';
+/**
+ * Split `<agent>[@<selector>]`. The selector names an INSTALLATION — its frozen
+ * label, or the release it currently carries — never a release to install; that
+ * is `--to`. Keeping them separate is what lets `agents update claude@2.0.65
+ * --to 2.0.71` read unambiguously.
+ */
+function parseTarget(raw) {
+    const at = raw.indexOf('@');
+    const name = at === -1 ? raw : raw.slice(0, at);
+    const selector = at === -1 ? undefined : raw.slice(at + 1).trim();
+    if (at !== -1 && !selector) {
+        throw new Error(`Missing installation in '${raw}'. Use <agent>@<installed-version>, or just <agent>.`);
+    }
+    const agent = resolveAgentName(name);
+    if (!agent)
+        throw new Error(formatAgentError(name));
+    return { agent, selector };
+}
+function serialize(installation) {
+    return {
+        id: installation.id,
+        agent: installation.agent,
+        label: installation.label,
+        releaseVersion: installation.releaseVersion,
+        createdAt: installation.createdAt,
+        updatedAt: installation.updatedAt,
+    };
+}
+function printOutcome(outcome, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            installation: serialize(outcome.installation),
+            strategy: outcome.strategy,
+            fromRelease: outcome.fromRelease,
+            toRelease: outcome.toRelease,
+            unchanged: outcome.unchanged,
+            alsoUpdated: outcome.alsoUpdated.map(serialize),
+        }, null, 2));
+        return;
+    }
+    const name = `${outcome.installation.agent}@${outcome.installation.label}`;
+    if (outcome.unchanged) {
+        console.log(chalk.gray(`${name} is already on release ${outcome.toRelease}.`));
+        return;
+    }
+    console.log(chalk.green(`Updated ${name}: release ${outcome.fromRelease} -> ${outcome.toRelease}`));
+    console.log(chalk.gray(`Its name is unchanged, so every default, project pin, and routine that names ${name} still resolves to it.`));
+    for (const other of outcome.alsoUpdated) {
+        console.log(chalk.gray(`  ${other.agent}@${other.label} shares the same binary and now also reports release ${other.releaseVersion}.`));
+    }
+}
+function printInstallations(agent, json) {
+    const installations = listInstallations(agent);
+    if (json) {
+        console.log(JSON.stringify(installations.map(serialize), null, 2));
+        return;
+    }
+    if (!installations.length) {
+        console.log(chalk.gray(`No managed ${agent} installations. Install one with: agents add ${agent}@latest`));
+        return;
+    }
+    console.log(chalk.bold(`${agent} installations\n`));
+    for (const installation of installations) {
+        console.log(`  ${chalk.cyan(installation.label)}  release ${installation.releaseVersion}  ${chalk.gray(installation.id)}`);
+    }
+}
+/**
+ * Surface a failure as one red line, not a stack trace. Everything this command
+ * can fail on — an unknown agent, an ambiguous selector, an unpinnable harness,
+ * a release that would not launch — is a message the user acts on, and a
+ * commander async action rejection otherwise reaches the user as a raw Node dump.
+ */
+function fail(err) {
+    console.error(chalk.red(err.message));
+    process.exitCode = 1;
+}
+export function registerUpdateCommand(program) {
+    const update = program
+        .command('update [target]')
+        .description('Move a frozen agent installation to a new release, keeping its name and every reference to it')
+        .option('--to <release>', 'Release to move to: latest (default), oldest, or an exact version')
+        .option('--account <label>', 'Disambiguate by signed-in account when several installations match')
+        .option('--json', 'Machine-readable result')
+        .action(async (target, options) => {
+        try {
+            if (!target) {
+                throw new Error('Which agent? Use: agents update <agent>[@<installed-version>]');
+            }
+            const { agent, selector } = parseTarget(target);
+            if (options.to && options.to !== 'latest' && !supportsPinnedUpdate(agent)) {
+                // Fail loud at the boundary rather than installing the current release
+                // and reporting it as the pin that was asked for.
+                throw new Error(`${agent} is a single self-updating binary with no pinnable releases — drop --to, or pass --to latest.`);
+            }
+            const installation = await resolveInstallation(agent, selector, { account: options.account });
+            const strategy = selectUpdateStrategy(agent);
+            if (!options.json && !strategy.transactional) {
+                console.log(chalk.yellow(`${agent} installs one vendor-managed binary, so this update cannot be staged or rolled back; `
+                    + `a failure leaves whatever its installer wrote.`));
+            }
+            if (!options.json) {
+                console.log(chalk.gray(`Updating ${agent}@${describeInstallation(installation)} via the ${strategy.id} strategy...`));
+            }
+            const outcome = await updateInstallation(installation, {
+                to: options.to,
+                onProgress: options.json ? undefined : (message) => console.log(chalk.gray(`  ${message}`)),
+            });
+            printOutcome(outcome, !!options.json);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    update
+        .command('list <agent>')
+        .description('Show every frozen installation of an agent and the release each carries')
+        .option('--json', 'Machine-readable listing')
+        // `--json` is declared on both `update` and `update list`, and commander
+        // binds a flag the parent also declares to the PARENT's option store — so
+        // reading this subcommand's own opts alone silently drops it. Merge them.
+        .action((rawAgent, _options, command) => {
+        try {
+            const agent = resolveAgentName(rawAgent);
+            if (!agent)
+                throw new Error(formatAgentError(rawAgent));
+            printInstallations(agent, !!command.optsWithGlobals().json);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    setHelpSections(update, {
+        examples: `agents update list claude
+agents update claude@2.0.65
+agents update claude@2.0.65 --to 2.1.220
+agents update claude --account work
+agents update claude@2.0.65 --json`,
+        notes: 'An installation keeps its name for life; only the release inside it moves. That is why a default, a project pin, '
+            + 'a routine version, or a profile that names claude@2.0.65 keeps working after you update it. '
+            + 'The selector matches either the installation name or the release it currently carries — when two installations '
+            + 'share a release, name one or pass --account <label> (see: agents accounts). '
+            + 'The new release is fetched and launched before it replaces the working one, so a bad release leaves your agent running.',
+    });
+}

package/dist/index.js

@@ -94,7 +94,7 @@ 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, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadDaemon, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadAccounts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadBench, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadUpdate, loadImport, loadExport, loadPackages, loadRoutines, loadDaemon, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadAccounts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadBench, loadShare, loadSend, loadFeed, 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';
@@ -292,6 +292,7 @@ Quick start:
 Agent versions:
   add <agent>[@version]           Install an agent CLI (e.g. agents add grok or agents add codex)
   import <agent>                  Adopt an existing global install (npm/homebrew) into agents-cli
+  update <agent>[@version]        Move an installed agent to a new release, keeping its name (agents-cli itself is 'agents upgrade')
   prune <agent>[@version]         Uninstall a version
   remove <agent>[@version]        Alias for prune
   use <agent>@<version>           Set the default version
@@ -942,6 +943,7 @@ async function registerAllEagerCommands() {
     await reg(loadWorkflows);
     await reg(loadWorktree);
     await reg(loadVersions);
+    await reg(loadUpdate);
     await reg(loadImport);
     await reg(loadExport);
     await reg(loadPackages);

package/dist/lib/catchup.js

@@ -139,7 +139,10 @@ export async function runCatchup(opts = {}) {
             continue;
         }
         try {
-            const meta = await executeJobDetached(config);
+            // No `scheduledFor` here on purpose: the missed slot is already claimed by
+            // `claimMissedFire` above (its atomic mkdir IS the catch-up single-fire), so
+            // the late run gets a fresh id rather than colliding with the missed record.
+            const meta = await executeJobDetached(config, undefined, { kind: 'catchup' });
             outcomes.push({
                 name: entry.name,
                 expectedAt: entry.expectedAt,

package/dist/lib/daemon.d.ts

@@ -273,6 +273,23 @@ export interface DaemonStopResult {
     surviving: string[];
     detachedChildren: number[];
 }
+/**
+ * Live `__daemon-run` processes still registered in THIS state dir's instance
+ * registry, excluding `exclude`. State-dir-scoped by construction: the registry
+ * lives inside this daemon dir, so a daemon serving a DIFFERENT state dir (a test
+ * fixture with its own HOME, a separate install/home) registers elsewhere and is
+ * invisible here — it is never a stop/takeover target. POSIX-only (the registry
+ * and its `ps` liveness probe are); `[]` on Windows.
+ *
+ * Exported for `agents daemon status`/`doctor`/`services` (RUSH-2368): those
+ * commands previously flagged every `__daemon-run` on the box (a raw `ps` scan)
+ * as a "duplicate" of this daemon, which misreported test fixtures under their
+ * own HOME — and therefore their own state dir and registry — as strays to
+ * kill. This registry read is the same scope the reaper (`reapStrayDaemons`)
+ * and the stop postcondition (`stopDaemon`) already use, so the display and the
+ * reaper agree on what a duplicate is.
+ */
+export declare function findSurvivingStateDirDaemons(exclude: Set<number>): number[];
 /**
  * Stop the daemon and ASSERT its postcondition (SING-12, RUSH-2355), unloading it
  * from launchd/systemd if applicable.

package/dist/lib/daemon.js

@@ -30,6 +30,7 @@ import { isSchedulerEnabled, assertSchedulerEnabled, isDaemonEnabled } from './d
 import { reapTerminalRoutineProcesses } from './routine-process-cleanup.js';
 import { recordSubsystemOk, recordSubsystemError, SUBSYSTEM_SECRETS_BROKER, SUBSYSTEM_BROWSER_IPC } from './daemon-health.js';
 const PID_FILE = 'daemon.pid';
+const LIFETIME_FILE = 'daemon.lifetime';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
 const HEARTBEAT_FILE = 'heartbeat.json';
@@ -543,6 +544,12 @@ export async function runDaemon() {
         // rather than a failure to restart-flap on.
         process.exit(0);
     }
+    // Unlike the pid and heartbeat files, this marker is written exactly once
+    // for this daemon lifetime. Status probes deliberately repair those other
+    // files, so they cannot prove that the original state tree still exists.
+    const lifetimePath = path.join(getDaemonDirRoot(), LIFETIME_FILE);
+    const lifetimeToken = `${process.pid}:${Date.now()}`;
+    fs.writeFileSync(lifetimePath, lifetimeToken, 'utf-8');
     log('INFO', `Daemon started (PID: ${process.pid})`);
     anchorDaemonCwd();
     warnEphemeralDaemonRoot();
@@ -610,7 +617,7 @@ export async function runDaemon() {
             log('WARN', err.message);
         }
     }
-    const triggerJob = async (config) => {
+    const triggerJob = async (config, ctx) => {
         const jobLabel = config.command
             ? 'command'
             : config.workflow
@@ -644,7 +651,7 @@ export async function runDaemon() {
                     })
                         .catch(() => { });
                 },
-            });
+            }, { kind: 'schedule', scheduledFor: ctx?.scheduledFor });
             log('INFO', `Job '${config.name}' spawned (run: ${meta.runId}, PID: ${meta.pid})`);
         }
         catch (err) {
@@ -847,9 +854,16 @@ export async function runDaemon() {
     const runHealCheck = async () => {
         if (healing)
             return;
+        // The daemon's state directory is its liveness boundary. Once that tree is
+        // removed, background maintenance must not recreate it while the
+        // self-terminate guard is shutting the process down.
+        if (!fs.existsSync(getDaemonDirRoot()))
+            return;
         healing = true;
         try {
             const { runSelfHeal, selfHealChangedAnything, selfHealNeedsAttention, summarizeSelfHeal } = await import('./self-heal/registry.js');
+            if (!fs.existsSync(getDaemonDirRoot()))
+                return;
             // Background heal is conservative (mode: 'safe'): fixes low-risk drift (shims,
             // symlink adoption, PATH, missing resources) and only reports risky ones. The
             // 30s kickoff means shims/PATH settle shortly after the daemon starts. No
@@ -925,6 +939,42 @@ export async function runDaemon() {
         }
     };
     const keychainReapInterval = setInterval(() => { void runKeychainReap(); }, 5 * 60_000);
+    // RUSH-2367: self-terminate if this daemon's own state dir has been removed
+    // out from under it — the shape of a leaked test-fixture daemon whose /tmp
+    // HOME was deleted by its test's own cleanup while the process itself
+    // somehow survived (lost the SIGTERM/SIGKILL race, or outlived a killed
+    // test runner before its `finally` ever ran). Nothing else can reach a
+    // daemon in that state: no `agents daemon` command targets it, since a
+    // different HOME resolves a different getDaemonDir() and therefore a
+    // different instance registry — without this it runs forever. Reads
+    // Reads the lifetime marker directly, never the local getDaemonDir() wrapper,
+    // which recreates the directory as a side effect and would defeat the check.
+    // Heartbeat/status paths may recreate the directory and pid file after a
+    // deletion; they never recreate this per-lifetime token.
+    let checkingStateDir = false;
+    const runStateDirSelfCheck = () => {
+        if (checkingStateDir)
+            return;
+        checkingStateDir = true;
+        try {
+            let markerMatches = false;
+            try {
+                markerMatches = fs.readFileSync(lifetimePath, 'utf-8') === lifetimeToken;
+            }
+            catch {
+                // A missing state tree or marker is the condition this guard detects.
+            }
+            if (!markerMatches) {
+                log('WARN', `Daemon state dir ${getDaemonDirRoot()} no longer exists; exiting (self-terminate guard)`);
+                void handleShutdown();
+            }
+        }
+        finally {
+            checkingStateDir = false;
+        }
+    };
+    const stateDirCheckMs = Number(process.env.AGENTS_DAEMON_STATE_DIR_CHECK_MS) || 60_000;
+    const stateDirCheckInterval = setInterval(runStateDirSelfCheck, stateDirCheckMs);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         // Refresh user-layer copies of opted-in project routines BEFORE the
@@ -975,6 +1025,14 @@ export async function runDaemon() {
         clearTimeout(healKickoff);
         clearInterval(brokerSelfHealInterval);
         clearInterval(keychainReapInterval);
+        clearInterval(stateDirCheckInterval);
+        try {
+            if (fs.readFileSync(lifetimePath, 'utf-8') === lifetimeToken)
+                fs.unlinkSync(lifetimePath);
+        }
+        catch {
+            // Already removed with the state tree, or replaced by a newer owner.
+        }
         hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();
@@ -1356,8 +1414,16 @@ function waitForPid(timeoutMs) {
  * fixture with its own HOME, a separate install/home) registers elsewhere and is
  * invisible here — it is never a stop/takeover target. POSIX-only (the registry
  * and its `ps` liveness probe are); `[]` on Windows.
+ *
+ * Exported for `agents daemon status`/`doctor`/`services` (RUSH-2368): those
+ * commands previously flagged every `__daemon-run` on the box (a raw `ps` scan)
+ * as a "duplicate" of this daemon, which misreported test fixtures under their
+ * own HOME — and therefore their own state dir and registry — as strays to
+ * kill. This registry read is the same scope the reaper (`reapStrayDaemons`)
+ * and the stop postcondition (`stopDaemon`) already use, so the display and the
+ * reaper agree on what a duplicate is.
  */
-function findSurvivingStateDirDaemons(exclude) {
+export function findSurvivingStateDirDaemons(exclude) {
     if (process.platform === 'win32')
         return [];
     const dir = getDaemonInstancesDir();

package/dist/lib/devices/doctor-findings.d.ts

@@ -6,13 +6,13 @@ import { type WindowsSshEnrollmentAudit } from './windows-ssh-enrollment.js';
 import type { SyncStatusRow, OrphanRow } from '../drift.js';
 import type { FetchStatusMarker } from '../auto-pull.js';
 import type { VersionResourceReport } from '../doctor-diff.js';
-import type { FleetDivergence, FleetVersionSignIn } from './fleet-divergence.js';
+import type { FleetDivergence, FleetHookRuntimeState, FleetVersionSignIn } from './fleet-divergence.js';
 export type FindingSeverity = 'critical' | 'warning';
 /** A machine-stable class for a finding — drives {@link remediationFor} and lets
  *  the JSON consumer group by kind. */
 /** Every finding class. Severity is NOT annotated here — {@link FINDING_SEVERITY}
  *  below owns it, and a second copy in these comments is a fourth place to drift. */
-export declare const ALL_FINDING_KINDS: readonly ["logged-out", "logout-unprovable", "missing-hook", "missing-plugin", "unwired-hook", "cli-missing", "missing-resource", "content-drift", "never-synced", "stale", "repo-behind", "repo-drift", "fleet-resource-gap", "host-cli-missing", "host-cli-invalid", "version-skew", "orphan", "duplicate-hook", "duplicate-hook-drift", "rc-secret-export", "env-secret-export", "exec-policy", "ssh-key-enrollment", "stale-cli", "owner-sink-unreachable"];
+export declare const ALL_FINDING_KINDS: readonly ["logged-out", "logout-unprovable", "missing-hook", "missing-plugin", "unwired-hook", "hook-runtime-broken", "hook-runtime-visibility-unavailable", "cli-missing", "missing-resource", "content-drift", "never-synced", "stale", "repo-behind", "repo-drift", "fleet-resource-gap", "host-cli-missing", "host-cli-invalid", "version-skew", "orphan", "duplicate-hook", "duplicate-hook-drift", "rc-secret-export", "env-secret-export", "exec-policy", "ssh-key-enrollment", "stale-cli", "owner-sink-unreachable"];
 /**
  * The severity each kind is emitted with - the SINGLE source of truth, read by
  * the builders below and asserted against both prose rubrics by
@@ -161,6 +161,11 @@ export declare function collapseAcrossVersions(findings: DoctorFinding[], isolat
  * logout provable. Pure.
  */
 export declare function signInToFindings(device: string, signIn: Record<string, FleetVersionSignIn[]>): DoctorFinding[];
+/**
+ * Rebuild remote generated-wrapper findings from the closed enum inventory
+ * state. Remote paths and detector messages never cross the fleet boundary.
+ */
+export declare function hookRuntimeToFindings(device: string, hookRuntime: Record<string, Record<string, FleetHookRuntimeState>> | undefined): DoctorFinding[];
 /**
  * Map cross-device divergence (from {@link compareFleetInventories}) into
  * warnings: an agent version present elsewhere but absent on a device is a

package/dist/lib/devices/doctor-findings.js

@@ -18,11 +18,13 @@
  * with. Keep this list exhaustive; a kind missing from it is a doc that lies.
  *   CRITICAL — logged-out (provable) · missing-hook · missing-plugin ·
  *              unwired-hook (a hook on disk that settings.json never fires) ·
- *              cli-missing · ssh-key-enrollment · owner-sink-unreachable (the feed/notify owner lane
+ *              hook-runtime-broken (a wired hook's generated shim wrapper is
+ *              missing or unusable) · cli-missing · ssh-key-enrollment ·
+ *              owner-sink-unreachable (the feed/notify owner lane
  *              cannot reach the owner from this box).
  *   WARNING  — logout-unprovable (hedged) · missing-resource · content-drift ·
  *              never-synced · stale · repo-behind · repo-drift · version-skew ·
- *              fleet-resource-gap · orphan · duplicate-hook ·
+ *              fleet-resource-gap · hook-runtime-visibility-unavailable · orphan · duplicate-hook ·
  *              duplicate-hook-drift · host-cli-missing · host-cli-invalid ·
  *              rc-secret-export · env-secret-export · exec-policy · stale-cli.
  *   (RUSH-2162 moved never-synced and duplicate-hook-drift to WARNING: both are
@@ -81,6 +83,8 @@ export const ALL_FINDING_KINDS = [
     'missing-hook', // a declared hook absent from a version home
     'missing-plugin', // a declared plugin absent from a version home
     'unwired-hook', // hook present on disk but not wired into settings.json
+    'hook-runtime-broken', // a wired hook's generated shim wrapper is missing/unusable
+    'hook-runtime-visibility-unavailable', // remote CLI cannot report generated wrapper health
     'cli-missing', // a managed agent whose binary won't resolve
     'missing-resource', // a missing command/skill/rule/mcp/permission/subagent
     'content-drift', // a resource diverged from source
@@ -119,6 +123,7 @@ export const FINDING_SEVERITY = {
     'missing-hook': 'critical',
     'missing-plugin': 'critical',
     'unwired-hook': 'critical',
+    'hook-runtime-broken': 'critical',
     'cli-missing': 'critical',
     // A factory that cannot escalate a blocked agent to the owner is not healthy,
     // and the failure is otherwise silent until a block is filed (RUSH-2262/2258).
@@ -127,6 +132,7 @@ export const FINDING_SEVERITY = {
     // the harness right now. RUSH-2162 moved never-synced and duplicate-hook-drift
     // here: both are stale-sync states that one `agents sync` resolves.
     'logout-unprovable': 'warning',
+    'hook-runtime-visibility-unavailable': 'warning',
     'missing-resource': 'warning',
     'content-drift': 'warning',
     'never-synced': 'warning',
@@ -200,10 +206,13 @@ export function remediationFor(finding) {
         case 'missing-hook':
         case 'missing-plugin':
         case 'unwired-hook':
+        case 'hook-runtime-broken':
         case 'missing-resource':
         case 'content-drift':
         case 'stale':
             return idLabel ? `agents doctor ${idLabel} --fix` : 'agents doctor --fix';
+        case 'hook-runtime-visibility-unavailable':
+            return 'upgrade agents-cli on this device';
         case 'never-synced':
             // A bare `agents sync <agent>` targets only the default/sole installed
             // version (`commands/sync.ts:8`), so a row collapsed across versions must
@@ -354,6 +363,15 @@ export function buildLocalFindings(input) {
                 }
             }
         }
+        // Generated shim wrapper missing/unusable for a wired hook — independent of
+        // whether the native settings format itself is understood, so this fires
+        // even for harnesses `w.supported` is false for (RUSH-2382).
+        for (const issue of w?.runtimeBroken ?? []) {
+            out.push(finding({
+                severity: FINDING_SEVERITY['hook-runtime-broken'], kind: 'hook-runtime-broken', device, agent, version,
+                message: `hook '${issue.name}' wired but its generated shim is ${issue.reason}`,
+            }));
+        }
         // A never-synced version has EVERY declared resource "missing" — that's one
         // root cause (never synced), not one emergency per hook. Collapse it to a
         // single critical rather than flooding the top section with 100+ lines. The
@@ -766,6 +784,39 @@ export function signInToFindings(device, signIn) {
     }
     return out;
 }
+/**
+ * Rebuild remote generated-wrapper findings from the closed enum inventory
+ * state. Remote paths and detector messages never cross the fleet boundary.
+ */
+export function hookRuntimeToFindings(device, hookRuntime) {
+    if (!hookRuntime) {
+        return [finding({
+                severity: FINDING_SEVERITY['hook-runtime-visibility-unavailable'],
+                kind: 'hook-runtime-visibility-unavailable',
+                device,
+                message: "older agents-cli — can't report generated hook-wrapper health",
+            })];
+    }
+    const out = [];
+    for (const agent of ALL_AGENT_IDS) {
+        const versions = hookRuntime[agent];
+        if (!versions)
+            continue;
+        for (const [version, state] of Object.entries(versions)) {
+            if (state !== 'broken')
+                continue;
+            out.push(finding({
+                severity: FINDING_SEVERITY['hook-runtime-broken'],
+                kind: 'hook-runtime-broken',
+                device,
+                agent,
+                version,
+                message: 'generated hook wrapper is unusable',
+            }));
+        }
+    }
+    return out;
+}
 /**
  * Map cross-device divergence (from {@link compareFleetInventories}) into
  * warnings: an agent version present elsewhere but absent on a device is a

package/dist/lib/devices/doctor-overview-cache.d.ts

@@ -14,6 +14,13 @@ export declare function readDoctorOverviewCache(deps?: DoctorOverviewCacheDeps):
 } | null;
 /** Persist a fresh overview payload (best-effort; tmp+rename so reads are atomic). */
 export declare function writeDoctorOverviewCache(payload: unknown, deps?: DoctorOverviewCacheDeps): void;
+/**
+ * Drop the cached overview after a doctor repair attempt changes (or fails to
+ * change) live health. Best-effort and deliberately narrow: it never touches
+ * the singleflight lock, so an in-progress overview compute remains owned by
+ * its holder and no repair can create a retry loop.
+ */
+export declare function invalidateDoctorOverviewCache(deps?: DoctorOverviewCacheDeps): void;
 /**
  * Result of {@link enterDoctorOverviewGate}.
  *  - `cached` non-null → the caller MUST print this string and return; no compute.

package/dist/lib/devices/doctor-overview-cache.js

@@ -82,6 +82,21 @@ export function writeDoctorOverviewCache(payload, deps = {}) {
         // best-effort; a failed write just means the next read falls back to live
     }
 }
+/**
+ * Drop the cached overview after a doctor repair attempt changes (or fails to
+ * change) live health. Best-effort and deliberately narrow: it never touches
+ * the singleflight lock, so an in-progress overview compute remains owned by
+ * its holder and no repair can create a retry loop.
+ */
+export function invalidateDoctorOverviewCache(deps = {}) {
+    const dir = deps.dir ?? getCacheDir();
+    try {
+        fs.unlinkSync(cachePath(dir));
+    }
+    catch {
+        // Missing/unlinkable cache is already equivalent to invalidated.
+    }
+}
 /**
  * Enter the doctor-overview singleflight gate. Returns a cached string to print,
  * or a lock token telling the caller to compute (and then write + release).

package/dist/lib/devices/fleet-divergence.d.ts

@@ -57,6 +57,13 @@ export interface FleetVersionSignIn {
      *  AND globally) — the caller gates a critical on this. */
     provable: boolean;
 }
+/**
+ * A deliberately closed summary of one version's generated hook-wrapper
+ * runtime. Fleet payloads carry only this state — never the remote wrapper
+ * path, embedded source path, or detector text.
+ */
+export declare const FLEET_HOOK_RUNTIME_STATES: readonly ["healthy", "broken", "not-applicable"];
+export type FleetHookRuntimeState = typeof FLEET_HOOK_RUNTIME_STATES[number];
 /**
  * The self-reported harness inventory a single device emits in `doctor --json`.
  * Comparable device-to-device with no further probing.
@@ -77,6 +84,10 @@ export interface FleetInventory {
      *  predates this field omits it, and the caller degrades to a warning
      *  ("older agents-cli — can't report per-version sign-in"). */
     signIn?: Record<string, FleetVersionSignIn[]>;
+    /** Generated hook-wrapper health per installed agent/version. Optional for
+     *  wire compatibility with older remotes; a present value is fully validated
+     *  before it is used by fleet doctor. */
+    hookRuntime?: Record<string, Record<string, FleetHookRuntimeState>>;
 }
 /** A device's inventory paired with its name (and reachability). A device that
  *  was unreachable / failed to report carries `inventory: null` and is skipped

package/dist/lib/devices/fleet-divergence.js

@@ -37,6 +37,12 @@ export const FLEET_RESOURCE_KINDS = [
     'promptcuts',
     'workflows',
 ];
+/**
+ * A deliberately closed summary of one version's generated hook-wrapper
+ * runtime. Fleet payloads carry only this state — never the remote wrapper
+ * path, embedded source path, or detector text.
+ */
+export const FLEET_HOOK_RUNTIME_STATES = ['healthy', 'broken', 'not-applicable'];
 function sortedUnique(list) {
     return Array.from(new Set(list)).sort();
 }

package/dist/lib/devices/fleet-inventory.js

@@ -8,7 +8,9 @@
  * FleetInventory} that both the local baseline and every remote box serialize
  * into their doctor payload; the comparator then diffs those payloads.
  */
-import { getAvailableResources, getVersionHomePath, listInstalledVersions } from '../versions.js';
+import { getAvailableResources, getVersionHomePath, isVersionIsolated, listInstalledVersions } from '../versions.js';
+import { supports } from '../capabilities.js';
+import { checkVersionHookWiring } from '../hooks.js';
 import { getUserAgentsDir, getSystemAgentsDir } from '../state.js';
 import { readRepoState } from '../git.js';
 import { ALL_AGENT_IDS, accountDisplayLabel, credentialPresence, getAccountInfo, supportsAccountInspection, } from '../agents.js';
@@ -88,10 +90,21 @@ export async function collectLocalFleetInventory(cwd = process.cwd()) {
         }
     }
     const agentVersions = {};
+    const hookRuntime = {};
     for (const agent of ALL_AGENT_IDS) {
         const versions = listInstalledVersions(agent);
-        if (versions.length > 0)
+        if (versions.length > 0) {
             agentVersions[agent] = [...versions].sort();
+            hookRuntime[agent] = Object.fromEntries(versions.map((version) => {
+                const eligible = supports(agent, 'hooks', version).ok && !isVersionIsolated(agent, version);
+                if (!eligible)
+                    return [version, 'not-applicable'];
+                const state = checkVersionHookWiring(agent, version).runtimeBroken.length > 0
+                    ? 'broken'
+                    : 'healthy';
+                return [version, state];
+            }));
+        }
     }
     return {
         resources,
@@ -101,5 +114,6 @@ export async function collectLocalFleetInventory(cwd = process.cwd()) {
             system: toRepoState(readRepoState(getSystemAgentsDir())),
         },
         signIn: await collectLocalFleetSignIn(),
+        hookRuntime,
     };
 }

package/dist/lib/drift.d.ts

@@ -22,6 +22,8 @@ export interface SyncStatusRow {
      *  (claude/droid). A non-zero value makes the version out-of-sync even when the
      *  manifest reads fresh — the yosemite-s1 blind spot the CI gate must catch. */
     unwiredHooks?: number;
+    /** Generated hooks whose shared runtime wrapper is missing or unusable. */
+    brokenHookRuntime?: number;
 }
 export interface OrphanRow {
     agent: AgentId;
@@ -52,11 +54,14 @@ export interface DriftSummary {
     orphanVersionCount: number;
     /** Versions with hooks present on disk but not wired into settings.json. */
     unwiredHookVersions: number;
+    /** Versions with at least one broken generated hook-runtime wrapper. */
+    brokenHookRuntimeVersions: number;
     /** Source layers behind their upstream (reconciled against stale truth). */
     sourceBehind: SourceLayerBehind[];
     /**
      * True when the install is out of sync: any installed version is stale,
-     * never-synced, or carries unwired hooks, OR a source layer is behind origin.
+     * never-synced, carries unwired hooks, or has a broken generated hook runtime,
+     * OR a source layer is behind origin.
      * `agents doctor` surfaces it as "run `agents status`"; `agents doctor --check`
      * maps it to a non-zero exit. Orphans are a `prune` concern, not sync drift, so they do
      * NOT set this flag (mirrors the sync-status engine: an orphan alone never