@phnx-labs/agents-cli 1.22.31 → 1.22.33

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 1.22.33
+
+- **Release tags are annotated with the folded changelog notes.** `scripts/release.sh` now creates `v<version>` as an annotated tag whose message is `Release <version>` plus the body of `.changelog/<version>.md` (the same notes that already become the release PR body). Agents keep writing one fragment under `.changelog/next/`; there is no separate tag-description channel. The already-published missing-tag recovery path uses the same helper with `--force`. Source: `apps/cli/scripts/release.sh`.
+
+`agents sessions --routines` once again opens the routine picker across every working directory instead of an empty current-repository session browser.
+
+## 1.22.32
+
+- **Routines validate execution context before activation and fire once per schedule slot (RUSH-2290).** A routine selects one execution `project` plus a portable `cwd`; add/edit save proven blockers paused, durable slot and active-run claims prevent duplicate or overlapping launches, and every blocked/skipped/pre-spawn attempt remains visible without requiring a session transcript. Source: `apps/cli/src/lib/routine-context.ts`, `apps/cli/src/lib/routine-readiness.ts`, `apps/cli/src/lib/runner.ts`.
+
+- **Daemon: self-terminates if its own state dir disappears; the routines test suite reaps
+  leaked daemons instead of letting them run for days (RUSH-2367).** Three real daemon
+  processes were found alive on a fleet box for up to 3.5 days, each spawned by a
+  vitest fixture under its own `/tmp` `HOME` and invisible to every `agents daemon`
+  guard, since a different `HOME` resolves a different state dir and instance registry.
+  The daemon now polls (`AGENTS_DAEMON_STATE_DIR_CHECK_MS`, default 60s) for a
+  per-lifetime marker and exits gracefully if it disappears — unlike the pid and
+  heartbeat files, status repair cannot recreate that marker after deleting the state
+  tree. This is the only defense
+  that survives the whole test runner being killed externally before any in-test cleanup
+  can run. The routines test suite also gained a leak detector that fails the run and
+  force-kills anything it spawned (or, on CI, any daemon it finds under its own fixture
+  prefix from a previous interrupted run) that survived past its own test. Source:
+  `apps/cli/src/lib/daemon.ts`, `apps/cli/src/commands/routines.test.ts`.
+
+- **Daemon: `status`/`doctor`/`services` no longer misreport test fixtures as duplicate
+  daemons to kill, and no longer render `healthy` for an unreachable service (RUSH-2368).**
+  Duplicate detection used to scan every `__daemon-run` process on the box, so a fixture
+  daemon under its own `HOME` (and therefore its own `getDaemonDir()`/instance registry) —
+  a separate install, or a leaked test process — showed up as a stray for the reader to
+  `kill`, contradicting the reaper (`reapStrayDaemons`) and `stop`'s postcondition, which
+  already scope by the instance registry. Duplicates are now read from that same registry
+  (`findSurvivingStateDirDaemons`), never a raw `ps` match. Separately, the secrets-broker
+  and browser-IPC health lines derived their `healthy`/`down` verdict from the daemon's
+  persisted last-ok record, which is only updated at the daemon's own startup — a broker
+  that went unreachable hours into a still-running daemon rendered `healthy (unreachable)`
+  on one line. The verdict now comes from the live probe; the persisted record supplies
+  only supporting last-ok/last-error context. Source: `apps/cli/src/commands/daemon.ts`,
+  `apps/cli/src/lib/daemon.ts`.
+
+- **Agent installations are frozen, and `agents update <agent>@<installed-version>` moves the release inside one (RUSH-2372).** An installation used to be identified only by its version-dir name, so the vendor release *was* the identity: moving to a new release meant a new directory, which dangled every default, project pin, routine `version:`, and profile that named the old one — and two installations of the same release could not coexist at all. Each install now carries an `installation.json` with a stable opaque id plus the release currently on disk; the name is frozen for life and only the release moves, so every reference keeps resolving. Pre-existing version dirs migrate on first read. `agents update` takes `--to <release>` (`latest` by default), `--account <label>` to disambiguate when several installations match, `--json`, `agents update list <agent>`, and routes through `--host` to update a peer's installation. The target release is fetched into a sibling directory and launched there *before* it replaces the working one, so a release that cannot start is discarded rather than installed; a post-swap failure restores the previous one. Update strategies are chosen from the agent registry's declared capabilities, so every harness `agents add` manages is covered (npm package, shared self-updating binary, install script) — and a harness whose binary lives outside the directory being swapped is refused with the reason instead of being recorded as updated. Not to be confused with `agents upgrade`, which updates agents-cli itself. Source: `apps/cli/src/lib/installations/*`, `apps/cli/src/commands/update.ts`, `apps/cli/src/lib/versions.ts`.
+
+- **`agents doctor` detects and self-heals a hook whose generated shim wrapper is
+  missing or broken, and the menu bar shows it (RUSH-2382).** A native hook command
+  could read as wired when its generated `~/.agents/.cache/shims/hooks/<name>.sh`
+  target was absent, a dangling symlink, empty, or non-executable — the harness
+  silently never ran the hook. `agents doctor` now emits a `hook-runtime-broken`
+  critical finding for every hooks-capable harness (not just the settings formats
+  the wiring inspector understands), and the daemon's safe self-heal regenerates
+  one broken shim per unique path per pass with post-repair verification, never
+  retrying or recursing into resource sync within the same pass. The macOS menu
+  bar System row now reads `N critical · M warnings` (or `all set`) from
+  `agents doctor --json`'s `findings` on the existing 15-minute poll, and the
+  submenu lists up to 5 actionable findings with remediation (any kind, not just
+  this one), with a `+N more — run agents doctor` row past the cap. Source:
+  `apps/cli/src/lib/hooks.ts`, `apps/cli/src/lib/self-heal/checks/hook-runtime.ts`,
+  `apps/cli/src/lib/devices/doctor-findings.ts`,
+  `apps/cli/menubar/Sources/MenubarHelper/{Models,StatusItemController,AgentsCLI}.swift`.
+
+- **Menu bar: the ROUTINES section is now a collapsible project-group accordion.**
+  Routines render the same way ACTIVE sessions do — one collapsible header per
+  project group (a project name, or the `Operations` / `All projects` /
+  `Cross-project` specials the CLI derives from each routine's `projects:` field),
+  collapsed by default, click `▶` to fold every routine in that group inline. Each
+  header carries per-state glyph counts (`◔` upcoming, `✕` failing, `⃠` missed,
+  `⏸` not-ready) and a paused tail, so a collapsed group still shows what is inside
+  it; the header row also names the group count (`ROUTINES · … · N groups`).
+  Expanding a group orders it attention-first, then by next run, then paused last.
+  This replaces the flat group labels plus the single "All routines…" flyout for a
+  CLI that emits `projectGroup`; an older CLI falls back to the previous view.
+  Source: `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`.
+
 ## 1.22.31
 
 - **`agents secrets unlock --keys` folds in the scoped-hold surface; the `secrets lease`/`leases`/`revoke` commands are deleted (RUSH-2350).** `unlock` now takes `--keys K1,K2` to hold ONLY that subset of a bundle behind its own expiry instead of the whole bundle — the one capability `lease` had that `unlock` did not, now on the command agents already reach for. Without `--keys`, `unlock` behaves exactly as before (whole bundle). An unknown or empty key subset fails closed (`Unknown secret lease key(s): …` / `requires at least one key`), `--keys` scopes exactly one local bundle (rejected with `--all`/`--host`), and `secrets status` now names the held keys of a scoped hold; `secrets lock <name>` releases it. The duplicate `secrets lease`/`secrets leases`/`secrets revoke` trio is gone — it had zero consumers, and its jobs (list holdings, release one) are already `secrets status` and `secrets lock`. No alias or deprecation shim (per the repo's no-unasked-shims rule). The underlying lease model (`src/lib/secrets/lease.ts`) is unchanged — `unlock --keys` reuses it. Source: `apps/cli/src/commands/secrets.ts` (`scopeHeldEnv`, the `unlock`/`status` actions), `apps/cli/src/lib/secrets/{agent,session-store}.ts`, `apps/cli/src/commands/secrets.scope.test.ts`, `apps/cli/src/commands/secrets.flags.test.ts`.

package/README.md

@@ -54,7 +54,7 @@ agents run claude "explain this repo"  # run any agent on your existing subscrip
 
 Full path -- installing harnesses, logging in, smoke-testing `agents teams`, and setting up your own fleet: [`apps/cli/docs/QUICKSTART.md`](apps/cli/docs/QUICKSTART.md).
 
-Already installed? `agents upgrade` updates agents-cli itself to the latest version (`agents upgrade 1.2.3` for a specific version or dist-tag, `-y` to skip the confirm prompt). The command is `upgrade` on every platform -- there is no `agents update` (on macOS, `agents helper update` is a different command that reinstalls the keychain helper, not agents-cli).
+Already installed? `agents upgrade` updates agents-cli itself to the latest version (`agents upgrade 1.2.3` for a specific version or dist-tag, `-y` to skip the confirm prompt). The command is `upgrade` on every platform -- do not reach for `agents update`, which updates an installed **agent harness**, not agents-cli (and on macOS, `agents helper update` is a third thing: it reinstalls the keychain helper).
 
 Source: [github.com/phnx-labs/agents-cli](https://github.com/phnx-labs/agents-cli)
 
@@ -1014,23 +1014,29 @@ agents secrets list   # EXPIRING column flags secrets due in the next 30 days
 agents routines add daily-digest \
   --schedule "0 9 * * 1-5" \
   --agent claude \
+  --project-anchor agents-cli \
+  --cwd apps/cli \
   --prompt "Review yesterday's PRs and summarize key changes"
 
 agents routines list                   # All jobs + next run times
 agents routines run daily-digest       # Test it now, ignore the schedule
 agents routines logs daily-digest      # Last execution — status + report (add --full for raw stdout)
+agents routines runs daily-digest      # Every attempt, including blocked/skipped pre-session runs
+agents routines doctor daily-digest    # Project/CWD/trust/write/auth readiness
 agents routines stats                  # Run count, failed, missed, avg/p50/p95 duration — per job or all
 
 # Definitions sync to every device; activation is stored per hostname
 agents routines add nightly-drain --schedule "0 3 * * *" --agent claude \
+  --cwd '~' \
   --prompt "Drain the local work queue"
 
-agents routines devices nightly-drain --set yosemite-s0,mac-mini  # enable on both hosts
+agents routines devices nightly-drain --set yosemite-s0           # one schedule owner
 agents routines list --host yosemite-s0                            # query another device
 
 # Signed webhook trigger: Linear issue labeled "agent" fires a routine
 agents routines add agent-labeled-issue --on linear:Issue --action update \
   --team-key RUSH --label agent --agent claude \
+  --cwd '~' \
   --prompt "Work the Linear issue that was just labeled agent"
 agents webhook serve --secrets-bundle webhooks --port 8787          # /hooks/linear, /hooks/github
 agents funnel up yosemite-s0 --local-port 8787 --port 443           # public HTTPS ingress

package/dist/commands/daemon.js

@@ -19,7 +19,7 @@ import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
-import { getDaemonStatus, isDaemonRunning, isDaemonWedged, readDaemonLog, startDaemon, stopDaemon, signalDaemonReload, } from '../lib/daemon.js';
+import { getDaemonStatus, isDaemonRunning, isDaemonWedged, readDaemonLog, startDaemon, stopDaemon, signalDaemonReload, findSurvivingStateDirDaemons, } from '../lib/daemon.js';
 import { getConfigValue, setConfigValue, isDaemonEnabled } from '../lib/device-config.js';
 import { readSubsystemHealth, SUBSYSTEM_SECRETS_BROKER, SUBSYSTEM_BROWSER_IPC, } from '../lib/daemon-health.js';
 import { listJobs, getLatestRun } from '../lib/routines.js';
@@ -94,8 +94,8 @@ function entryFromTokens(tokens) {
 }
 /**
  * Every live `__daemon-run` process on this box, regardless of which install
- * launched it. POSIX-only (uses `ps`), mirroring `reapStrayDaemons`'s scope —
- * a no-op on Windows.
+ * launched it or which state dir it serves. POSIX-only (uses `ps`); a no-op on
+ * Windows.
  *
  * `getDaemonLaunch` always spawns `<node> <entry> __daemon-run` with nothing
  * after it — the ONLY argv `__daemon-run` ever appears in for a real daemon.
@@ -104,6 +104,14 @@ function entryFromTokens(tokens) {
  * literal text `__daemon-run` (this ticket's own brief does) matches that test
  * too, and was observed producing false "duplicate daemon" rows. Requiring it
  * to be the LAST whitespace-delimited token is the actual invariant.
+ *
+ * This raw box-wide scan is deliberately NOT the duplicate-detection scope
+ * (RUSH-2368): a `__daemon-run` under a different HOME serves a different
+ * `getDaemonDir()` and is not a duplicate of THIS device's daemon, however
+ * `ps` sees it — a leaked vitest fixture under its own `/tmp` HOME matched
+ * this scan and was reported as a stray to `kill`. It is used only to attach
+ * display metadata (entry/version) to pids the registry-scoped
+ * `findSurvivingStateDirDaemons` has already confirmed as real duplicates.
  */
 function scanDaemonProcesses() {
     if (process.platform === 'win32')
@@ -133,6 +141,22 @@ function scanDaemonProcesses() {
     }
     return found;
 }
+/**
+ * Duplicates of THIS device's daemon, scoped to the same instance registry the
+ * reaper and the stop postcondition use (RUSH-2368) — never a raw `ps` match.
+ * `processes` (from `scanDaemonProcesses`) supplies display metadata
+ * (entry/version); `findSurvivingStateDirDaemons` supplies the actual scope, so
+ * a `__daemon-run` under a different HOME (a different `getDaemonDir()`) —
+ * whether a leaked test fixture or a genuinely separate install — never shows
+ * up here even though it is visible to the box-wide `ps` scan.
+ */
+function registryScopedDuplicates(processes, ownerPid) {
+    const exclude = new Set();
+    if (ownerPid)
+        exclude.add(ownerPid);
+    const registered = new Set(findSurvivingStateDirDaemons(exclude));
+    return processes.filter((p) => registered.has(p.pid));
+}
 /** Elapsed wall-clock seconds since `pid` started, or null if unavailable (best-effort, POSIX only). */
 function uptimeSeconds(pid) {
     if (process.platform === 'win32')
@@ -198,12 +222,28 @@ function schedulerSummary() {
     return { routineCount: jobs.length, enabledCount: enabled.length, nextFire, failingCount };
 }
 // ─── Rendering ────────────────────────────────────────────────────────────
-function healthLine(label, record) {
-    if (!record || record.consecutiveFailures === 0) {
+/**
+ * Render one service's health line. `live` is the verdict — a probe run RIGHT
+ * NOW against the actual socket/binding — and is the only thing allowed to say
+ * `healthy` (RUSH-2368). `record` is the daemon's persisted last-ok/last-error
+ * history: supporting context, never the verdict. Before this fix the verdict
+ * came from `record.consecutiveFailures`, which the daemon only updates at its
+ * own startup (`recordSubsystemOk`/`recordSubsystemError` in daemon.ts) — a
+ * broker that went unreachable hours into a still-running daemon rendered
+ * `healthy (unreachable)` on one line, a contradiction that is exactly the
+ * silent-success pattern this command exists to remove.
+ */
+function healthLine(label, live, record) {
+    if (live) {
         const ok = record?.lastOkAt ? chalk.gray(`(last ok ${record.lastOkAt})`) : '';
         return `  ${chalk.green('healthy')}  ${label} ${ok}`;
     }
-    return `  ${chalk.red(`${record.consecutiveFailures} consecutive failure(s)`)}  ${label} ${chalk.gray(`— ${record.lastError}`)}`;
+    const detail = record && record.consecutiveFailures > 0
+        ? chalk.gray(`— ${record.lastError}`)
+        : record?.lastOkAt
+            ? chalk.gray(`(last ok ${record.lastOkAt})`)
+            : '';
+    return `  ${chalk.red('down')}  ${label} ${detail}`;
 }
 async function runStatus(opts) {
     const status = getDaemonStatus();
@@ -214,7 +254,7 @@ async function runStatus(opts) {
     const heartbeatAgeMs = status.heartbeat ? Date.now() - Date.parse(status.heartbeat.lastTick) : null;
     const processes = scanDaemonProcesses();
     const owner = pid ? processes.find((p) => p.pid === pid) : undefined;
-    const duplicates = processes.filter((p) => p.pid !== pid);
+    const duplicates = registryScopedDuplicates(processes, pid ?? null);
     const [secrets, browserIpc] = await Promise.all([probeSecretsBroker(), probeBrowserIPC()]);
     const scheduler = schedulerSummary();
     if (opts.json) {
@@ -277,8 +317,8 @@ async function runStatus(opts) {
         console.log(chalk.gray('\n  Only one install should own the daemon. Stop the stray(s): kill <pid>'));
     }
     console.log(chalk.bold('\nHealth\n'));
-    console.log(healthLine(`secrets broker  ${secrets.reachable ? `(${secrets.socketPath}, ${secrets.heldBundles} bundle(s) held)` : '(unreachable)'}`, secrets.record));
-    console.log(healthLine(`browser IPC     ${browserIpc.bound ? `(${browserIpc.socketPath}, ${browserIpc.sessionCount} session(s))` : '(unbound)'}`, browserIpc.record));
+    console.log(healthLine(`secrets broker  ${secrets.reachable ? `(${secrets.socketPath}, ${secrets.heldBundles} bundle(s) held)` : '(unreachable)'}`, secrets.reachable, secrets.record));
+    console.log(healthLine(`browser IPC     ${browserIpc.bound ? `(${browserIpc.socketPath}, ${browserIpc.sessionCount} session(s))` : '(unbound)'}`, browserIpc.bound, browserIpc.record));
     const schedulerEnabled = getConfigValue('scheduler.enabled').value !== false;
     console.log(`  ${schedulerEnabled ? chalk.green('enabled') : chalk.yellow('disabled')}  scheduler — ${scheduler.enabledCount}/${scheduler.routineCount} routine(s) enabled` +
         (scheduler.nextFire ? `, next ${scheduler.nextFire.toLocaleString()}` : ''));
@@ -299,8 +339,8 @@ async function runServices(opts) {
         return;
     }
     console.log(chalk.bold('Hosted services\n'));
-    console.log(healthLine(`secrets broker  ${secrets.reachable ? `(${secrets.socketPath}, ${secrets.heldBundles} bundle(s) held)` : '(unreachable)'}`, secrets.record));
-    console.log(healthLine(`browser IPC     ${browserIpc.bound ? `(${browserIpc.socketPath}, ${browserIpc.sessionCount} session(s))` : '(unbound)'}`, browserIpc.record));
+    console.log(healthLine(`secrets broker  ${secrets.reachable ? `(${secrets.socketPath}, ${secrets.heldBundles} bundle(s) held)` : '(unreachable)'}`, secrets.reachable, secrets.record));
+    console.log(healthLine(`browser IPC     ${browserIpc.bound ? `(${browserIpc.socketPath}, ${browserIpc.sessionCount} session(s))` : '(unbound)'}`, browserIpc.bound, browserIpc.record));
     console.log(chalk.gray('\nScheduled routines run through `agents routines` — see: agents routines stats'));
 }
 function parseLogLines(raw) {
@@ -379,7 +419,7 @@ async function runDoctor(opts) {
         problems.push('Daemon is not running. Start it: agents daemon start');
     if (status.running && isDaemonWedged())
         problems.push('Daemon is wedged (heartbeat stale). Restart: agents daemon restart');
-    const duplicates = scanDaemonProcesses().filter((p) => p.pid !== status.pid);
+    const duplicates = registryScopedDuplicates(scanDaemonProcesses(), status.pid);
     if (duplicates.length > 0) {
         problems.push(`${duplicates.length} duplicate daemon process(es) running: ${duplicates.map((d) => d.pid).join(', ')}. Stop the stray(s).`);
     }

package/dist/commands/doctor.d.ts

@@ -22,6 +22,7 @@
  * apply pending sync.
  */
 import type { Command } from 'commander';
+import { type FleetInventory } from '../lib/devices/fleet-divergence.js';
 import { type DoctorFinding } from '../lib/devices/doctor-findings.js';
 import { type VersionResourceReport } from '../lib/doctor-diff.js';
 import { type DuplicateVersionHook } from '../lib/hooks.js';
@@ -51,6 +52,24 @@ export declare function asRemoteSecretFindings(raw: unknown, device: string): Do
  * whole-fleet wall time is bounded near the slowest box, not 180s x N.
  */
 export declare const FLEET_INVENTORY_TIMEOUT_MS = 180000;
+/**
+ * Narrow a remote `doctor --json` `.fleet` payload to a usable inventory, or null.
+ *
+ * The remote runs ITS OWN agents-cli, whose version we do not control, so the
+ * payload is untrusted input rather than a typed value — a cast alone let a
+ * partial object (`{"fleet":{}}` from a skewed or truncated remote) reach
+ * `compareFleetInventories`, which indexes `inv.resources[kind]` and
+ * `Object.keys(inv.agentVersions)` unconditionally and throws. Returning null
+ * routes that device into the existing "older agents-cli / no inventory" path,
+ * which is honest and already rendered, instead of aborting the whole fan-out.
+ *
+ * This validates EVERY field of {@link FleetInventory} that anything downstream
+ * reads — `resources`, `agentVersions`, `repos` and each optional `signIn` row.
+ * It was tightened four times during review, each round finding the next
+ * unvalidated layer, so treat partial validation here as a bug: a field added to
+ * the inventory must be checked here in the same change.
+ */
+export declare function asFleetInventory(value: unknown): FleetInventory | null;
 export type IssueSeverity = 'critical' | 'warning' | 'info';
 /**
  * One triaged health finding. `severity`/`category`/`subject`/`impact`/`fix` are

package/dist/commands/doctor.js

@@ -4,11 +4,11 @@ import { addHostOption } from '../lib/hosts/option.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
 import { fanOutDevices, planFleetTargets, remoteFleetTargets } from '../lib/devices/fleet.js';
-import { enterDoctorOverviewGate, writeDoctorOverviewCache } from '../lib/devices/doctor-overview-cache.js';
+import { enterDoctorOverviewGate, invalidateDoctorOverviewCache, writeDoctorOverviewCache } from '../lib/devices/doctor-overview-cache.js';
 import { fleetDialTarget } from '../lib/devices/connect.js';
-import { compareFleetInventories } from '../lib/devices/fleet-divergence.js';
+import { compareFleetInventories, FLEET_HOOK_RUNTIME_STATES } from '../lib/devices/fleet-divergence.js';
 import { collectLocalFleetInventory } from '../lib/devices/fleet-inventory.js';
-import { buildLocalFindings, fleetDivergenceToFindings, signInToFindings, renderFindings, remediationFor, FINDING_SEVERITY, } from '../lib/devices/doctor-findings.js';
+import { buildLocalFindings, fleetDivergenceToFindings, hookRuntimeToFindings, signInToFindings, renderFindings, remediationFor, FINDING_SEVERITY, } from '../lib/devices/doctor-findings.js';
 import { getCliVersion } from '../lib/version.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
@@ -23,7 +23,7 @@ import { getVersionHomePath, listInstalledVersions, } from '../lib/versions.js';
 import { resolveAgentTargets, AgentSpecError } from '../lib/agent-spec/index.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
-import { checkVersionHookWiring, inspectDuplicateVersionHooks, registerHooksToSettings } from '../lib/hooks.js';
+import { checkVersionHookWiring, inspectDuplicateVersionHooks, registerHooksToSettings, repairManagedHookRuntimeArtifacts } from '../lib/hooks.js';
 import { isVersionIsolated } from '../lib/versions.js';
 import { computeDrift, checkSyncStatus, countOrphans, computeSourceBehind } from '../lib/drift.js';
 import { readAuthHealthCache, summarizeHostAuth } from '../lib/auth-health.js';
@@ -281,7 +281,7 @@ async function probeFleetInventory(target) {
  * unvalidated layer, so treat partial validation here as a bug: a field added to
  * the inventory must be checked here in the same change.
  */
-function asFleetInventory(value) {
+export function asFleetInventory(value) {
     // `typeof [] === 'object'`, so a shallow object check is not enough: an array
     // passes it, every `inv.resources[kind] ?? []` then yields empty, and the
     // comparison reports EVERY baseline resource as missing on that device — a
@@ -323,6 +323,33 @@ function asFleetInventory(value) {
         if (!rowsOk)
             return null;
     }
+    // Hook-runtime state is optional for wire compatibility with older remotes,
+    // but a present field is a closed enum map keyed exactly by the installed
+    // agent/version pairs. The fleet never accepts a remote path or diagnostic
+    // string, so an untrusted box cannot inject shell paths/text into this doctor.
+    if (v.hookRuntime !== undefined) {
+        if (!isMap(v.hookRuntime))
+            return null;
+        const validStates = new Set(FLEET_HOOK_RUNTIME_STATES);
+        const agentVersions = v.agentVersions;
+        const hookRuntime = v.hookRuntime;
+        const expectedAgents = Object.keys(agentVersions);
+        if (Object.keys(hookRuntime).length !== expectedAgents.length)
+            return null;
+        for (const agent of expectedAgents) {
+            if (!ALL_AGENT_IDS.includes(agent))
+                return null;
+            const states = hookRuntime[agent];
+            const versions = agentVersions[agent];
+            if (!isMap(states) || Object.keys(states).length !== versions.length)
+                return null;
+            const expectedVersions = new Set(versions);
+            for (const [version, state] of Object.entries(states)) {
+                if (!expectedVersions.has(version) || typeof state !== 'string' || !validStates.has(state))
+                    return null;
+            }
+        }
+    }
     return v;
 }
 async function runDevicesDoctor(opts) {
@@ -443,6 +470,10 @@ async function runDevicesDoctor(opts) {
         // reports a leaking box as clean (RUSH-1968).
         if (r.secretFindings?.length)
             findings.push(...r.secretFindings);
+        // Unlike sign-in, the remote's hook-runtime payload is deliberately just a
+        // closed enum state. Rebuild the finding locally so no remote file path or
+        // detector text reaches this host's output.
+        findings.push(...hookRuntimeToFindings(r.name, r.inventory?.hookRuntime));
         if (r.inventory?.signIn) {
             findings.push(...signInToFindings(r.name, r.inventory.signIn));
             accounts[r.name] = r.inventory.signIn;
@@ -627,7 +658,7 @@ const HOOK_WIRING_FIX_AGENTS = ['claude', 'droid'];
 /** Categories `--fix` reconciles (vs. `agents repo pull` for a behind source, or
  *  `agents prune cleanup` for an orphan). Drives the heal footer. */
 const AUTO_FIXABLE_CATEGORIES = new Set([
-    'unwired-hook', 'settings-missing', 'settings-unparseable', 'missing', 'divergent', 'stale', 'never-synced',
+    'hook-runtime-broken', 'unwired-hook', 'settings-missing', 'settings-unparseable', 'missing', 'divergent', 'stale', 'never-synced',
 ]);
 export function verdictIsAutoFixable(v) {
     return v.issues.some((i) => AUTO_FIXABLE_CATEGORIES.has(i.category));
@@ -646,6 +677,14 @@ export function computeVerdict(report) {
     const syncCmd = `agents sync ${idLabel} --yes`;
     // ── critical: settings.json / unwired hooks (silent breakage) ──
     const w = report.hookWiring;
+    for (const issue of w?.runtimeBroken ?? []) {
+        issues.push({
+            severity: 'critical', category: 'hook-runtime-broken', subject: issue.name,
+            impact: `generated hook wrapper is ${issue.reason}; the hook cannot run`,
+            fix: fixCmd,
+            text: `${issue.name} hook runtime broken`, color: 'red',
+        });
+    }
     if (w?.settingsMissing) {
         const n = w.expected ?? 0;
         issues.push({
@@ -828,8 +867,18 @@ export function computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, d
             color: drift ? 'red' : 'yellow',
         });
     }
-    // critical: unwired hooks / broken settings.json per version
+    // critical: generated hook runtime / unwired hooks / broken settings.json per version
     for (const row of syncRows) {
+        const brokenRuntime = row.brokenHookRuntime ?? 0;
+        if (brokenRuntime > 0) {
+            const label = pretty(row.agent, row.version);
+            issues.push({
+                severity: 'critical', category: 'hook-runtime-broken', subject: label,
+                impact: `${brokenRuntime} generated hook wrapper${brokenRuntime === 1 ? '' : 's'} unusable; affected hooks cannot run`,
+                fix: `agents doctor ${row.agent}@${row.version} --fix`,
+                text: `${label} ${brokenRuntime} hook runtime broken`, color: 'red',
+            });
+        }
         const n = row.unwiredHooks ?? 0;
         if (n <= 0)
             continue;
@@ -890,7 +939,7 @@ export function computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, d
             text: `${label} orphan`, color: 'magenta',
         });
     }
-    const reconciled = syncRows.filter((r) => r.status === 'fresh' && (r.unwiredHooks ?? 0) === 0).length;
+    const reconciled = syncRows.filter((r) => r.status === 'fresh' && (r.unwiredHooks ?? 0) === 0 && (r.brokenHookRuntime ?? 0) === 0).length;
     return { healthy: issues.length === 0, issues, reconciled };
 }
 /**
@@ -1059,10 +1108,22 @@ function rewireUnwiredHooks(parsed) {
             const need = before.unwired.length + (before.settingsMissing ? (before.expected ?? 0) : 0);
             if (need === 0)
                 continue;
-            registerHooksToSettings(agent, getVersionHomePath(agent, version));
-            const after = checkVersionHookWiring(agent, version);
-            const remaining = after.unwired.length + (after.settingsMissing ? (after.expected ?? 0) : 0);
-            out.push({ agent, version, rewired: Math.max(0, need - remaining), remaining });
+            try {
+                const registration = registerHooksToSettings(agent, getVersionHomePath(agent, version));
+                if (registration.errors.length > 0) {
+                    out.push({ agent, version, rewired: 0, remaining: need, failure: 'register-failed' });
+                    continue;
+                }
+                const after = checkVersionHookWiring(agent, version);
+                const remaining = after.unwired.length + (after.settingsMissing ? (after.expected ?? 0) : 0);
+                out.push({ agent, version, rewired: Math.max(0, need - remaining), remaining });
+            }
+            catch {
+                // A shim write can fail before the native config writer gets to return
+                // its own errors. Record the same stable class and keep doctor --fix
+                // moving to the one bounded runtime repair pass below.
+                out.push({ agent, version, rewired: 0, remaining: need, failure: 'register-failed' });
+            }
         }
     }
     return out;
@@ -1070,7 +1131,10 @@ function rewireUnwiredHooks(parsed) {
 function renderHookRewireText(rewired) {
     for (const r of rewired) {
         const label = `${AGENT_NAMES[r.agent] || r.agent}@${r.version}`;
-        if (r.remaining === 0) {
+        if (r.failure) {
+            console.log(`  ${chalk.red('hold  ')} ${label}  ${chalk.gray('native hook wiring could not be updated')}`);
+        }
+        else if (r.remaining === 0) {
             console.log(`  ${chalk.green('rewired')} ${label}  ${chalk.gray(`${r.rewired} hook${r.rewired === 1 ? '' : 's'} wired into settings.json`)}`);
         }
         else {
@@ -1078,6 +1142,24 @@ function renderHookRewireText(rewired) {
         }
     }
 }
+function runtimeRepairFilter(parsed) {
+    if (!parsed)
+        return undefined;
+    // A concrete target can be narrowed to that version. Broad selectors (@all,
+    // @latest, agent-only) still make one bounded repair pass for that harness.
+    return {
+        agent: parsed.agent,
+        ...(parsed.versionExplicit && parsed.versions.length === 1 ? { version: parsed.versions[0] } : {}),
+    };
+}
+function renderHookRuntimeRepairText(repair) {
+    for (const fixed of repair.fixed) {
+        console.log(`  ${chalk.green('fixed ')}  ${chalk.gray(fixed)}`);
+    }
+    for (const unresolved of repair.needsAttention) {
+        console.log(`  ${chalk.red('hold  ')}  ${chalk.gray(unresolved)}`);
+    }
+}
 async function runFix(parsed, opts) {
     // Heal targets the global install — project layer is irrelevant, so cwd is
     // left to heal's neutral default rather than process.cwd().
@@ -1094,12 +1176,27 @@ async function runFix(parsed, opts) {
     });
     // Re-wire hooks the diff-driven heal leaves behind (present file, not wired).
     const rewired = rewireUnwiredHooks(parsed);
+    // One inspect→generate→verify pass, after normal resource and native-wiring
+    // repair have settled. This routine never calls sync/register and never
+    // retries; unresolved wrappers remain an explicit non-zero doctor outcome.
+    const hookRuntimeRepair = repairManagedHookRuntimeArtifacts({ filter: runtimeRepairFilter(parsed) });
+    const rewireFailed = rewired.some((entry) => entry.failure !== undefined);
+    if (healChangedAnything(result) ||
+        rewired.some((entry) => entry.rewired > 0 || entry.remaining > 0 || entry.failure !== undefined) ||
+        hookRuntimeRepair.attempts.length > 0) {
+        invalidateDoctorOverviewCache();
+    }
     if (opts.json) {
-        console.log(JSON.stringify({ ...result, hookRewire: rewired }, null, 2));
+        console.log(JSON.stringify({ ...result, hookRewire: rewired, hookRuntimeRepair }, null, 2));
+        if (rewireFailed || hookRuntimeRepair.needsAttention.length > 0)
+            process.exitCode = 1;
         return;
     }
     renderHealText(result);
     renderHookRewireText(rewired);
+    renderHookRuntimeRepairText(hookRuntimeRepair);
+    if (rewireFailed || hookRuntimeRepair.needsAttention.length > 0)
+        process.exitCode = 1;
 }
 function checkLabel(row) {
     return `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
@@ -1112,6 +1209,7 @@ function runCheckGate(opts, cwd) {
             stale: drift.staleCount,
             neverSynced: drift.neverSyncedCount,
             unwiredHookVersions: drift.unwiredHookVersions,
+            brokenHookRuntimeVersions: drift.brokenHookRuntimeVersions,
             orphanVersions: drift.orphanVersionCount,
             sourceBehind: drift.sourceBehind,
             versions: drift.syncRows.map((r) => ({
@@ -1120,6 +1218,7 @@ function runCheckGate(opts, cwd) {
                 status: r.status,
                 isDefault: r.isDefault,
                 unwiredHooks: r.unwiredHooks ?? 0,
+                brokenHookRuntime: r.brokenHookRuntime ?? 0,
                 divergence: r.divergence ?? [],
             })),
         }, null, 2));
@@ -1149,6 +1248,8 @@ function runCheckGate(opts, cwd) {
         parts.push(`${drift.neverSyncedCount} never-synced`);
     if (drift.unwiredHookVersions > 0)
         parts.push(`${drift.unwiredHookVersions} with unwired hooks`);
+    if (drift.brokenHookRuntimeVersions > 0)
+        parts.push(`${drift.brokenHookRuntimeVersions} with broken hook runtime`);
     if (drift.sourceBehind.length > 0)
         parts.push(`${drift.sourceBehind.length} source layer(s) behind origin`);
     console.error(`${chalk.gray('check:')} ${chalk.red('drift')} — ${parts.join(', ')} across ${drift.syncRows.length} version(s)`);
@@ -1160,11 +1261,12 @@ function runCheckGate(opts, cwd) {
         const STATUS_BADGE_WIDTH = 'never-synced'.length + 2;
         for (const row of drift.syncRows) {
             const unwired = (row.unwiredHooks ?? 0) > 0;
-            if (row.status === 'fresh' && !unwired)
+            const brokenRuntime = (row.brokenHookRuntime ?? 0) > 0;
+            if (row.status === 'fresh' && !unwired && !brokenRuntime)
                 continue;
             const tag = row.status === 'stale' ? chalk.yellow('stale'.padEnd(STATUS_BADGE_WIDTH))
                 : row.status === 'never-synced' ? chalk.gray('never-synced'.padEnd(STATUS_BADGE_WIDTH))
-                    : chalk.red('unwired'.padEnd(STATUS_BADGE_WIDTH)); // fresh but hooks not wired into settings.json
+                    : chalk.red((brokenRuntime ? 'hook-runtime' : 'unwired').padEnd(STATUS_BADGE_WIDTH));
             console.error(`  ${tag}${checkLabel(row)}`);
             for (const line of row.divergence ?? []) {
                 console.error(chalk.gray(`           ${line}`));
@@ -1174,7 +1276,7 @@ function runCheckGate(opts, cwd) {
             console.error(`  ${chalk.red('behind')} source ${b.label}  ${chalk.gray(`${b.behind} commit${b.behind === 1 ? '' : 's'} behind ${b.branch}`)}`);
         }
         const hints = [];
-        if (drift.staleCount > 0 || drift.neverSyncedCount > 0 || drift.unwiredHookVersions > 0) {
+        if (drift.staleCount > 0 || drift.neverSyncedCount > 0 || drift.unwiredHookVersions > 0 || drift.brokenHookRuntimeVersions > 0) {
             hints.push('`agents doctor --fix` (or `agents doctor <agent>@<version> --fix`)');
         }
         if (drift.sourceBehind.length > 0)