@phnx-labs/agents-cli 1.22.30 → 1.22.32

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

package/dist/lib/drift.js

@@ -60,6 +60,12 @@ export function checkSyncStatus(cwd) {
             // never fires. Surface that for every version, fresh or stale, so overview
             // AND `agents doctor --check` flag it (claude/droid; other agents report unsupported).
             const wiring = checkVersionHookWiring(agent, version);
+            if (wiring.runtimeBroken.length > 0) {
+                row.brokenHookRuntime = wiring.runtimeBroken.length;
+                const names = wiring.runtimeBroken.map((issue) => issue.name);
+                const shown = names.slice(0, 3).join(', ');
+                divergence.push(`hooks       ${names.length} generated wrapper${names.length === 1 ? '' : 's'} broken (${shown}${names.length > 3 ? ', …' : ''})`);
+            }
             if (wiring.supported) {
                 const expected = wiring.expected ?? 0;
                 if (wiring.settingsMissing && expected > 0) {
@@ -147,6 +153,7 @@ export function computeDrift(cwd) {
     const staleCount = syncRows.filter((r) => r.status === 'stale').length;
     const neverSyncedCount = syncRows.filter((r) => r.status === 'never-synced').length;
     const unwiredHookVersions = syncRows.filter((r) => (r.unwiredHooks ?? 0) > 0).length;
+    const brokenHookRuntimeVersions = syncRows.filter((r) => (r.brokenHookRuntime ?? 0) > 0).length;
     const sourceBehind = computeSourceBehind();
     return {
         syncRows,
@@ -155,9 +162,11 @@ export function computeDrift(cwd) {
         neverSyncedCount,
         orphanVersionCount: orphanRows.length,
         unwiredHookVersions,
+        brokenHookRuntimeVersions,
         sourceBehind,
         hasDrift: syncRows.some((r) => r.status !== 'fresh') ||
             unwiredHookVersions > 0 ||
+            brokenHookRuntimeVersions > 0 ||
             sourceBehind.length > 0,
     };
 }

package/dist/lib/hooks/cache.js

@@ -18,6 +18,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import * as crypto from 'crypto';
 import { getHookCacheDir, getHookShimsDir, getLogsDir, getPerfDir } from '../state.js';
 /**
  * Parse a `cache:` value from hooks.yaml into the canonical config form.
@@ -128,7 +129,25 @@ export function generateHookShim(args) {
         catch { /* rewrite */ }
     }
     if (existing !== content) {
-        fs.writeFileSync(shimPath, content, { mode: 0o755 });
+        // A hook may fire while a background self-heal repairs another stale shim.
+        // Write in the destination directory and rename only after its mode and
+        // complete contents are ready, so observers see either the old complete
+        // wrapper or the new complete wrapper — never a truncated shell script.
+        const tempPath = path.join(shimsDir, `.${path.basename(shimPath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+        try {
+            fs.writeFileSync(tempPath, content, { mode: 0o755 });
+            fs.chmodSync(tempPath, 0o755);
+            fs.renameSync(tempPath, shimPath);
+        }
+        finally {
+            // Rename removes the temp path on success. On a failed write/rename this
+            // best-effort cleanup prevents a bounded repair failure from leaving
+            // growing debris behind for every periodic pass.
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch { /* already renamed or unavailable */ }
+        }
     }
     else {
         // Ensure exec bit even when content unchanged (file mode can drift).

package/dist/lib/hooks.d.ts

@@ -28,7 +28,7 @@ export declare function toPortableCommand(absPath: string, home?: string, sep?:
  * outside version homes are user-owned and remain untouched.
  */
 export declare function deduplicateVersionHookCommands(commands: string[], activeVersionHome: string): string[];
-import type { AgentId, InstalledHook, ManifestHook } from './types.js';
+import type { AgentId, HookCacheConfig, HookMatches, InstalledHook, ManifestHook } from './types.js';
 export type HookEntry = {
     name: string;
     scriptPath: string;
@@ -110,6 +110,27 @@ export interface HookWiringIssue {
     /** The command the harness-native config should reference under `event`. */
     command: string;
 }
+/** A generated, agents-managed hook wrapper and the inputs needed to recreate it. */
+export interface ManagedHookRuntimeArtifact {
+    agent: AgentId;
+    version: string;
+    name: string;
+    scriptPath: string;
+    shimPath: string;
+    cache: HookCacheConfig | null;
+    matches?: HookMatches;
+}
+/** A generated hook wrapper that is referenced by managed configuration but cannot run. */
+export interface BrokenManagedHookRuntimeArtifact extends ManagedHookRuntimeArtifact {
+    /** Stable, human-readable filesystem failure; the hook is never executed to find it. */
+    reason: string;
+}
+/** Public, doctor-safe shape for a broken generated hook wrapper. */
+export interface HookRuntimeIssue {
+    name: string;
+    path: string;
+    reason: string;
+}
 export interface HookWiringReport {
     /** Whether this agent's hook config format is understood by the inspector. */
     supported: boolean;
@@ -128,7 +149,76 @@ export interface HookWiringReport {
      *  Empty whenever wiring cannot be verified (unsupported family, missing or
      *  unparseable settings). */
     wired: HookWiringIssue[];
+    /** Generated agents-managed wrappers that are absent or unusable. This is
+     * independent of whether the native config format itself is understood. */
+    runtimeBroken: HookRuntimeIssue[];
+}
+/** Inspect managed generated hook wrappers without executing user hook code. */
+export declare function inspectBrokenManagedHookRuntimeArtifacts(filter?: {
+    agent?: AgentId;
+    version?: string;
+}, platform?: NodeJS.Platform): BrokenManagedHookRuntimeArtifact[];
+/** Outcome of one generation attempt for a unique shim path. */
+export interface HookRuntimeRepairAttempt {
+    name: string;
+    path: string;
+    reasonBefore: string;
+    /** True when generateHookShim ran for this path in this pass. */
+    attempted: boolean;
+    repaired: boolean;
+    /** Stable failure text when not repaired after an attempt (or dry-run skip). */
+    reason?: string;
+}
+/**
+ * Result of one bounded repair pass over agents-managed generated hook shims.
+ * Shared by self-heal and doctor --fix; additive types for the doctor track.
+ */
+export interface HookRuntimeRepairReport {
+    /** Broken artifacts found before any write (inspect-only snapshot). */
+    brokenBefore: BrokenManagedHookRuntimeArtifact[];
+    /** Unique shim paths considered for generation in this pass. */
+    attemptedPaths: string[];
+    attempts: HookRuntimeRepairAttempt[];
+    /** Human-readable lines for CheckResult.fixed (includes dry-run would-fix). */
+    fixed: string[];
+    /** Human-readable lines for CheckResult.needsAttention — stable wording. */
+    needsAttention: string[];
 }
+export interface RepairManagedHookRuntimeOptions {
+    /** Detect only — never write. Default false. */
+    dryRun?: boolean;
+    filter?: {
+        agent?: AgentId;
+        version?: string;
+    };
+    platform?: NodeJS.Platform;
+}
+/**
+ * Regenerate one known-broken wrapper and prove the result is usable. Callers
+ * provide a snapshot from inspectBrokenManagedHookRuntimeArtifacts; this never
+ * loops or retries and returns a stable error for the current pass.
+ *
+ * Generation is delegated to generateHookShim (idempotent — preserves mtime when
+ * content already matches). This path never calls registerHooksToSettings,
+ * installHooks, or any sync routine.
+ */
+export declare function repairManagedHookRuntimeArtifact(artifact: ManagedHookRuntimeArtifact, platform?: NodeJS.Platform): {
+    repaired: boolean;
+    reason?: string;
+};
+/**
+ * Bounded repair of all broken agents-managed generated hook shims.
+ *
+ * - Inspect first (read-only, no hook execution).
+ * - One generation attempt per unique shim path per call (no retry, no timer).
+ * - Canonical owner per shared path: global default, else newest non-isolated.
+ * - Post-repair reinspection; unresolved findings become stable needsAttention.
+ * - Never recurses into resource sync / registerHooksToSettings.
+ *
+ * This is the shared routine used by the self-heal `hook-runtime` check and
+ * exported for the doctor track.
+ */
+export declare function repairManagedHookRuntimeArtifacts(opts?: RepairManagedHookRuntimeOptions): HookRuntimeRepairReport;
 /**
  * Verify that every hook the manifest says should be wired is actually
  * referenced in that version's harness-native config, not merely present as a