@phnx-labs/agents-cli 1.22.52 → 1.22.54

package/dist/lib/project-key.d.ts

@@ -14,6 +14,15 @@
  * for local ones; {@link resolveProjectKey} adds the filesystem repo-root walk
  * for paths this machine can see.
  */
+/**
+ * Convert an absolute cwd to Claude Code's own project-folder name under
+ * `~/.claude/projects/` (slashes and dots become dashes) — the encoding
+ * Claude Code itself performs to name each project's session-transcript and
+ * native-memory directory. Pure, no filesystem: session discovery and
+ * native-memory sync both derive from this so they agree on one directory
+ * for a given cwd.
+ */
+export declare function claudeProjectDirName(cwd: string): string;
 /**
  * Resolve a stable project key from a working directory, or `undefined` when
  * the path carries nothing usable (empty, `/`, whitespace).

package/dist/lib/project-key.js

@@ -18,6 +18,17 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 const WORKTREE_SEGMENT = '/.agents/worktrees/';
+/**
+ * Convert an absolute cwd to Claude Code's own project-folder name under
+ * `~/.claude/projects/` (slashes and dots become dashes) — the encoding
+ * Claude Code itself performs to name each project's session-transcript and
+ * native-memory directory. Pure, no filesystem: session discovery and
+ * native-memory sync both derive from this so they agree on one directory
+ * for a given cwd.
+ */
+export function claudeProjectDirName(cwd) {
+    return cwd.replace(/[/.]/g, '-');
+}
 /**
  * Resolve a stable project key from a working directory, or `undefined` when
  * the path carries nothing usable (empty, `/`, whitespace).

package/dist/lib/secrets/bundles.d.ts

@@ -101,6 +101,41 @@ export declare const ENV_KEY_PATTERN: RegExp;
 export declare const BUNDLE_KEY_PATTERN: RegExp;
 export declare const BUNDLE_META_PREFIX = "agents-cli.bundles.";
 export declare const RESERVED_ENV_NAMES: Set<string>;
+/**
+ * The reserved FILE-BACKED bundle that holds long-lived Claude setup-tokens.
+ * Usage/probe reads authenticate with these instead of the ACL-bound login item,
+ * so they never pop Touch ID and they can cross the fleet. A keychain- or
+ * vault-backed bundle of this name is a misconfiguration: the consumer used to
+ * return null (SEC-GAP-3) and silently fall through to Touch ID.
+ */
+export declare const AUTH_BUNDLE_NAME = "auth";
+export declare const AUTH_BUNDLE_BACKEND: SecretsBackend;
+export declare const RESERVED_BUNDLE_NAMES: Set<string>;
+export declare function isReservedBundleName(name: string): boolean;
+/** Thrown when a reserved bundle is written or resolved on the wrong backend. */
+export declare class ReservedBundleWrongBackendError extends Error {
+    readonly bundle: string;
+    readonly backend: SecretsBackend;
+    constructor(bundle: string, backend: SecretsBackend);
+}
+/** Fail loud when `name` is reserved and `backend` is not the required one. */
+export declare function assertReservedBundleBackend(name: string, backend: SecretsBackend): void;
+/**
+ * Presence + backend of the reserved `auth` bundle. `ok` is true when the
+ * bundle is absent (nothing to fix) or present and file-backed.
+ */
+export declare function inspectReservedAuthBundle(): {
+    exists: boolean;
+    backend: SecretsBackend | null;
+    ok: boolean;
+};
+/**
+ * After a file-backed import, actually decrypt the keys and fail if any are
+ * unreadable. Import used to print "Imported N key(s)" from the write tally
+ * alone — ciphertext sealed under a forwarded AGENTS_SECRETS_PASSPHRASE that
+ * the destination daemon does not hold still counted as success.
+ */
+export declare function assertFileBundleDecryptable(name: string, keys: string[]): void;
 export declare function bundleToEnvPrefix(name: string): string;
 export declare function isReservedEnvName(key: string): boolean;
 export declare function bundleKeyToEnvKey(key: string): string;

package/dist/lib/secrets/bundles.js

@@ -137,6 +137,82 @@ export const RESERVED_ENV_NAMES = new Set([
     'TERM', 'LANG', 'LC_ALL', 'DISPLAY', 'EDITOR', 'VISUAL',
     'TMPDIR', 'TMP', 'TEMP', 'LOGNAME', 'UID', 'EUID', 'HOSTNAME',
 ]);
+/**
+ * The reserved FILE-BACKED bundle that holds long-lived Claude setup-tokens.
+ * Usage/probe reads authenticate with these instead of the ACL-bound login item,
+ * so they never pop Touch ID and they can cross the fleet. A keychain- or
+ * vault-backed bundle of this name is a misconfiguration: the consumer used to
+ * return null (SEC-GAP-3) and silently fall through to Touch ID.
+ */
+export const AUTH_BUNDLE_NAME = 'auth';
+export const AUTH_BUNDLE_BACKEND = 'file';
+export const RESERVED_BUNDLE_NAMES = new Set([AUTH_BUNDLE_NAME]);
+export function isReservedBundleName(name) {
+    return RESERVED_BUNDLE_NAMES.has(name.trim().toLowerCase());
+}
+/** Thrown when a reserved bundle is written or resolved on the wrong backend. */
+export class ReservedBundleWrongBackendError extends Error {
+    bundle;
+    backend;
+    constructor(bundle, backend) {
+        super(`Bundle '${bundle}' is reserved for file-backed setup-tokens (headless, fleet-shareable). ` +
+            `A ${backend}-backed '${bundle}' bundle is ignored by usage/probe instead of authenticating. ` +
+            `Recreate it as file-backed: agents secrets delete ${bundle} --yes && agents secrets create ${bundle} --backend file`);
+        this.name = 'ReservedBundleWrongBackendError';
+        this.bundle = bundle;
+        this.backend = backend;
+    }
+}
+/** Fail loud when `name` is reserved and `backend` is not the required one. */
+export function assertReservedBundleBackend(name, backend) {
+    if (!isReservedBundleName(name))
+        return;
+    if (backend !== AUTH_BUNDLE_BACKEND) {
+        throw new ReservedBundleWrongBackendError(name, backend);
+    }
+}
+/**
+ * Presence + backend of the reserved `auth` bundle. `ok` is true when the
+ * bundle is absent (nothing to fix) or present and file-backed.
+ */
+export function inspectReservedAuthBundle() {
+    if (!bundleExists(AUTH_BUNDLE_NAME)) {
+        return { exists: false, backend: null, ok: true };
+    }
+    const backend = bundleBackend(AUTH_BUNDLE_NAME);
+    return { exists: true, backend, ok: backend === AUTH_BUNDLE_BACKEND };
+}
+/**
+ * After a file-backed import, actually decrypt the keys and fail if any are
+ * unreadable. Import used to print "Imported N key(s)" from the write tally
+ * alone — ciphertext sealed under a forwarded AGENTS_SECRETS_PASSPHRASE that
+ * the destination daemon does not hold still counted as success.
+ */
+export function assertFileBundleDecryptable(name, keys) {
+    if (keys.length === 0)
+        return;
+    if (bundleBackend(name) !== 'file')
+        return;
+    let env;
+    try {
+        ({ env } = readAndResolveBundleEnv(name, { caller: 'import-verify', agentOnly: true, keyMode: 'storage' }));
+    }
+    catch (err) {
+        throw new Error(`Imported '${name}' reported success but the file store could not decrypt it. ` +
+            `${err.message} Typically because AGENTS_SECRETS_PASSPHRASE was forwarded ` +
+            `and this process does not hold it. Re-import without that env var.`);
+    }
+    const missing = keys.filter((k) => {
+        const v = env[k];
+        return typeof v !== 'string' || v.length === 0;
+    });
+    if (missing.length === 0)
+        return;
+    throw new Error(`Imported '${name}' reported success but ${missing.length} key(s) are unreadable ` +
+        `(${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', …' : ''}). ` +
+        `The destination store could not decrypt them — typically because AGENTS_SECRETS_PASSPHRASE ` +
+        `was forwarded and this process does not hold it. Re-import without that env var.`);
+}
 export function bundleToEnvPrefix(name) {
     return name.replace(/[-\.]/g, '_').toUpperCase();
 }
@@ -394,6 +470,7 @@ export function shouldEvictAfterBundleWrite(skipRequested, noAgentEnv, backendOv
 function prepareBundleWrite(bundle) {
     validateBundleName(bundle.name);
     const backend = bundle.backend ?? 'keychain';
+    assertReservedBundleBackend(bundle.name, backend);
     if (backend === 'vault')
         assertVaultBackendUsable(bundle.name);
     for (const key of Object.keys(bundle.vars)) {
@@ -1323,7 +1400,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     // If the secrets broker is explicitly disabled and this bundle would otherwise
     // fall through to a keychain read (Touch ID prompt), fail loud now. Never-policy
     // bundles are verified below and remain silent; vault/file backends are unaffected.
-    if (backend === 'keychain' && !isSecretsBrokerEnabled() && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
+    if (backend === 'keychain' && !verifiedNoAclBundle && !isSecretsBrokerEnabled() && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
         throw new Error(`Secrets broker is disabled — re-enable with 'agents daemon services enable secrets-broker'. ` +
             `If you meant to read directly from the keychain, set AGENTS_SECRETS_NO_AGENT=1.`);
     }

package/dist/lib/secrets/push.d.ts

@@ -21,14 +21,9 @@ export interface PushBundleOptions {
     /** Overwrite a key that already exists on the remote. */
     force?: boolean;
     /**
-     * Forwarded to the remote as the FIRST stdin line for the FILE backend only,
-     * and only when non-empty.
-     *
-     * Empty is the DEFAULT and the good path: the remote's file store then
-     * auto-provisions its own machine-local key (0600, `~/.agents/.secrets-key/`)
-     * and reads headlessly. Setting this keys the remote bundle under a shared
-     * off-disk secret instead — an opt-in, never a requirement. Requiring one is
-     * what pushed operators toward exporting the master key fleet-wide (RUSH-1968).
+     * Ignored. File-backend export never forwards AGENTS_SECRETS_PASSPHRASE
+     * (PHNX-2371); the remote auto-provisions its own machine-local key.
+     * Kept on the options type so existing callers that passed one still compile.
      */
     passphrase?: string;
     /** Label for the audit trail — `export --device` vs `fleet apply`. */

package/dist/lib/secrets/push.js

@@ -87,7 +87,6 @@ export function planPushTransport(resolved, bundle, host, opts) {
             return { kind: 'refuse', message: 'file backend export to a Windows target is not yet supported' };
         }
         const { remoteCmd, input } = buildRemoteFileImportCommand(bundle, resolved.dotenv, {
-            passphrase: opts.passphrase ?? '',
             force: opts.force,
             policyNever: opts.policyNever,
         });
@@ -148,20 +147,25 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
         const msg = (res.stderr || res.stdout || '').trim();
         return fail(`remote import failed (exit ${res.code})${msg ? `: ${msg}` : ''}`);
     }
-    // A keychain-backed push to a macOS remote over headless SSH can land the
-    // bundle metadata but no READABLE value items: the remote login keychain is
-    // locked in the non-interactive SSH context, so Security accepts the write but
-    // the biometry-ACL'd item is unreadable — and the remote `import` still exits
-    // 0. Read it back the way a release will and FAIL LOUDLY, rather than leave a
-    // metadata-only bundle that breaks later with "stored item not found". The
-    // file backend is headless-readable by construction, so it is skipped.
-    if (opts.remoteBackend === 'keychain') {
-        const verdict = verifyRemoteKeychainPush(host, bundle, Object.keys(resolved.env), { osLookupName: host, secret: true });
-        if (!verdict.ok) {
-            return fail(verdict.kind === 'locked-keychain'
-                ? keychainWriteFailureMessage(host, bundle, verdict.reason)
-                : `pushed '${bundle}' but could not verify it on the remote: ${verdict.reason}`);
+    // A successful remote import is not proof the keys are readable. Two silent
+    // failures hide behind exit 0:
+    //   - keychain: a macOS login keychain is locked under headless SSH, so the
+    //     write lands metadata but no readable value items.
+    //   - file: a forwarded AGENTS_SECRETS_PASSPHRASE keys ciphertext to a secret
+    //     the destination daemon does not hold (PHNX-2371).
+    // Read the bundle back the way a later resolve will and FAIL LOUDLY.
+    const verdict = verifyRemoteKeychainPush(host, bundle, Object.keys(resolved.env), { osLookupName: host, secret: true });
+    if (!verdict.ok) {
+        if (opts.remoteBackend === 'keychain' && verdict.kind === 'locked-keychain') {
+            return fail(keychainWriteFailureMessage(host, bundle, verdict.reason));
         }
+        if (opts.remoteBackend === 'file') {
+            return fail(`${host}: pushed '${bundle}' but the remote could not decrypt it (${verdict.reason}). ` +
+                `File-backend export never forwards AGENTS_SECRETS_PASSPHRASE — the remote keys ` +
+                `the bundle under its own machine-local key. If the destination still cannot read, ` +
+                `unset a stale AGENTS_SECRETS_PASSPHRASE there (\`agents doctor\`).`);
+        }
+        return fail(`pushed '${bundle}' but could not verify it on the remote: ${verdict.reason}`);
     }
     for (const step of planLiteralRestoration(bundle, opts.literalValues)) {
         const removed = remoteSecretsRaw(host, step.removeArgs, { osLookupName: host, secret: true });

package/dist/lib/secrets/remote.d.ts

@@ -11,9 +11,9 @@
  *
  * Trust model: relies on the operator's existing SSH access to the host (same
  * boundary as `export --device` / `run --device`). Bundle names are shell-quoted
- * into the remote command; resolved VALUES return over ssh stdout; a forwarded
- * file-backend passphrase travels over ssh stdin (first line) so it never lands
- * in argv / `ps` / remote shell history. Nothing is persisted locally.
+ * into the remote command; resolved VALUES return over ssh stdout. File-backend
+ * import never forwards AGENTS_SECRETS_PASSPHRASE (PHNX-2371). Nothing is
+ * persisted locally.
  */
 import { type SshExecResult } from '../ssh-exec.js';
 /**
@@ -208,26 +208,17 @@ export declare function verifyRemoteKeychainPush(target: string, bundle: string,
  * The `bash -lc` command + stdin payload that drives a **file-backed** remote
  * import for `secrets export --device … --remote-backend file`.
  *
- * The file store is passphrase-free by default: with `AGENTS_SECRETS_PASSPHRASE`
- * unset the remote `agents secrets import --backend file` auto-provisions the
- * remote's own machine-local key (0600 under `~/.agents/.secrets-key/`), so its
- * reads are HEADLESS — no passphrase, no Touch ID. A passphrase is therefore
- * OPTIONAL and only forwarded when the operator sets one locally (opt-in, e.g. to
- * key the bundle off-disk under a shared secret):
- *
- * - **No passphrase** → the remote runs `import … --backend file` directly with
- *   ONLY the .env on stdin. No `read`/`export AGENTS_SECRETS_PASSPHRASE`
- *   prologue, so `AGENTS_SECRETS_PASSPHRASE` stays UNSET on the remote → the
- *   machine-local key path → headless reads.
- * - **Passphrase set** → forward it as the FIRST stdin line, consumed by
- *   `IFS= read -r` (so it never lands in argv / `ps` / remote shell history),
- *   then the .env. The remote then keys the bundle under that shared passphrase.
+ * The file store is passphrase-free: the remote `agents secrets import --backend
+ * file` auto-provisions the remote's own machine-local key (0600 under
+ * `~/.agents/.secrets-key/`), so its reads are HEADLESS — no passphrase, no
+ * Touch ID. AGENTS_SECRETS_PASSPHRASE is a deprecated override and MUST NOT be
+ * forwarded (PHNX-2371): a remote keyed to a secret its daemon does not hold
+ * reports "Imported N key(s)" then fails every later decrypt.
  *
  * Pure — no I/O — so the exact command string and stdin ordering are unit-testable
  * against the SSH boundary the same way `remoteSecretsRaw` is.
  */
 export declare function buildRemoteFileImportCommand(bundle: string, dotenv: string, opts?: {
-    passphrase?: string;
     force?: boolean;
     policyNever?: boolean;
 }): {

package/dist/lib/secrets/remote.js

@@ -11,9 +11,9 @@
  *
  * Trust model: relies on the operator's existing SSH access to the host (same
  * boundary as `export --device` / `run --device`). Bundle names are shell-quoted
- * into the remote command; resolved VALUES return over ssh stdout; a forwarded
- * file-backend passphrase travels over ssh stdin (first line) so it never lands
- * in argv / `ps` / remote shell history. Nothing is persisted locally.
+ * into the remote command; resolved VALUES return over ssh stdout. File-backend
+ * import never forwards AGENTS_SECRETS_PASSPHRASE (PHNX-2371). Nothing is
+ * persisted locally.
  */
 import { sshExec, sshStream, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
@@ -417,20 +417,12 @@ export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {})
  * The `bash -lc` command + stdin payload that drives a **file-backed** remote
  * import for `secrets export --device … --remote-backend file`.
  *
- * The file store is passphrase-free by default: with `AGENTS_SECRETS_PASSPHRASE`
- * unset the remote `agents secrets import --backend file` auto-provisions the
- * remote's own machine-local key (0600 under `~/.agents/.secrets-key/`), so its
- * reads are HEADLESS — no passphrase, no Touch ID. A passphrase is therefore
- * OPTIONAL and only forwarded when the operator sets one locally (opt-in, e.g. to
- * key the bundle off-disk under a shared secret):
- *
- * - **No passphrase** → the remote runs `import … --backend file` directly with
- *   ONLY the .env on stdin. No `read`/`export AGENTS_SECRETS_PASSPHRASE`
- *   prologue, so `AGENTS_SECRETS_PASSPHRASE` stays UNSET on the remote → the
- *   machine-local key path → headless reads.
- * - **Passphrase set** → forward it as the FIRST stdin line, consumed by
- *   `IFS= read -r` (so it never lands in argv / `ps` / remote shell history),
- *   then the .env. The remote then keys the bundle under that shared passphrase.
+ * The file store is passphrase-free: the remote `agents secrets import --backend
+ * file` auto-provisions the remote's own machine-local key (0600 under
+ * `~/.agents/.secrets-key/`), so its reads are HEADLESS — no passphrase, no
+ * Touch ID. AGENTS_SECRETS_PASSPHRASE is a deprecated override and MUST NOT be
+ * forwarded (PHNX-2371): a remote keyed to a secret its daemon does not hold
+ * reports "Imported N key(s)" then fails every later decrypt.
  *
  * Pure — no I/O — so the exact command string and stdin ordering are unit-testable
  * against the SSH boundary the same way `remoteSecretsRaw` is.
@@ -439,14 +431,7 @@ export function buildRemoteFileImportCommand(bundle, dotenv, opts = {}) {
     const force = opts.force ? ' --force' : '';
     const policy = opts.policyNever ? ' --policy never --i-understand' : '';
     const importCmd = `agents secrets import ${shellQuote(bundle)} --from - --backend file${force}${policy}`;
-    const passphrase = opts.passphrase ?? '';
-    if (passphrase) {
-        // Opt-in shared passphrase: read it off the FIRST stdin line, export it, then
-        // let `import --from -` read the .env remainder.
-        const remoteAgents = `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ${importCmd}`;
-        return { remoteCmd: `bash -lc ${shellQuote(remoteAgents)}`, input: `${passphrase}\n${dotenv}` };
-    }
-    // No passphrase: NO prologue — AGENTS_SECRETS_PASSPHRASE stays unset on the
-    // remote, so the file store falls back to its machine-local key (headless).
+    // No prologue — AGENTS_SECRETS_PASSPHRASE stays unset on the remote, so the
+    // file store falls back to its machine-local key (headless).
     return { remoteCmd: `bash -lc ${shellQuote(importCmd)}`, input: dotenv };
 }

package/dist/lib/secrets/reserved-sync.d.ts

@@ -0,0 +1,65 @@
+import { type PushBundleResult } from './push.js';
+import { type DeviceProfile } from '../devices/registry.js';
+import type { DeviceProbe } from '../fleet/types.js';
+export interface AuthSyncDevice {
+    name: string;
+    reachable: boolean;
+    pinned: boolean;
+    remoteHasAuth: boolean;
+}
+export type AuthSyncPlanItem = {
+    action: 'push';
+    device: string;
+} | {
+    action: 'skip';
+    device: string;
+    reason: string;
+};
+export declare function planAuthBundlePush(localAuthOk: boolean, devices: AuthSyncDevice[]): AuthSyncPlanItem[];
+export interface AuthSyncResult {
+    pushed: string[];
+    skipped: Array<{
+        device: string;
+        reason: string;
+    }>;
+    errors: Array<{
+        device: string;
+        message: string;
+    }>;
+}
+export interface AuthSyncProbe {
+    reachable: boolean;
+    remoteHasAuth: boolean;
+}
+export interface AuthSyncDeps {
+    inspectLocal?: () => {
+        exists: boolean;
+        ok: boolean;
+    };
+    listDevices?: () => DeviceProfile[];
+    localName?: string;
+    isPinned?: (name: string) => boolean;
+    /**
+     * Per-device reachability + auth presence. Default: `probeDevice({ withSecrets: true })`
+     * — the same remote-presence probe `fleet apply` uses in `decideSecretPush`.
+     */
+    probe?: (device: DeviceProfile) => AuthSyncProbe;
+    push?: (bundle: string, host: string) => PushBundleResult;
+    sshTarget?: (device: DeviceProfile) => string;
+}
+/**
+ * Map a `fleet apply` device probe onto the auth-sync skip/push inputs.
+ *
+ * Presence is an own-property check on `remoteBundles` (same gate as
+ * `decideSecretPush`): a missing listing, a parse failure, or a prototype
+ * name must all mean "not present, so push" — never "present, so skip".
+ */
+export declare function authPresenceFromProbe(probe: DeviceProbe): AuthSyncProbe;
+/** Production default: live SSH probe of reachability + `secrets list --json`. */
+export declare function defaultAuthSyncProbe(device: DeviceProfile): AuthSyncProbe;
+/**
+ * Push the local file-backed `auth` bundle to every pinned registered device
+ * that does not already have it. No-op when the local bundle is missing or on
+ * the wrong backend (doctor flags that separately).
+ */
+export declare function syncReservedAuthBundle(deps?: AuthSyncDeps): AuthSyncResult;

package/dist/lib/secrets/reserved-sync.js

@@ -0,0 +1,129 @@
+/**
+ * Fleet sync of the reserved file-backed `auth` bundle (PHNX-2371).
+ *
+ * Setup-tokens drift per box when sync is manual. This module plans + executes
+ * a push of the local file-backed `auth` bundle to registered devices that do
+ * not yet have it, always with `--remote-backend file` and never forwarding
+ * AGENTS_SECRETS_PASSPHRASE. Each destination auto-provisions its own
+ * machine-local key and the push read-back-verifies decryptability.
+ *
+ * Double-fire: each device's daemon only writes that device's own store (the
+ * destination). Two boxes that both have `auth` skip each other (already
+ * present). A box without `auth` is a pull target for a provisioned peer.
+ *
+ * The planner is pure so tests cover every skip/push branch with no SSH.
+ */
+import { AUTH_BUNDLE_NAME, inspectReservedAuthBundle } from './bundles.js';
+import { pushBundleToHost } from './push.js';
+import { loadDevicesSync } from '../devices/registry.js';
+import { sshTargetFor } from '../devices/connect.js';
+import { isHostPinned, managedKnownHostsPath } from '../devices/known-hosts.js';
+import { machineId, normalizeHost } from '../session/sync/config.js';
+import { probeDevice } from '../fleet/apply.js';
+export function planAuthBundlePush(localAuthOk, devices) {
+    if (!localAuthOk) {
+        return devices.map((d) => ({
+            action: 'skip',
+            device: d.name,
+            reason: 'no local file-backed auth bundle',
+        }));
+    }
+    return devices.map((d) => {
+        if (!d.reachable)
+            return { action: 'skip', device: d.name, reason: 'unreachable' };
+        if (!d.pinned) {
+            return {
+                action: 'skip',
+                device: d.name,
+                reason: `host key not pinned; run \`agents ssh ${d.name}\` once`,
+            };
+        }
+        if (d.remoteHasAuth)
+            return { action: 'skip', device: d.name, reason: 'already present' };
+        return { action: 'push', device: d.name };
+    });
+}
+/**
+ * Map a `fleet apply` device probe onto the auth-sync skip/push inputs.
+ *
+ * Presence is an own-property check on `remoteBundles` (same gate as
+ * `decideSecretPush`): a missing listing, a parse failure, or a prototype
+ * name must all mean "not present, so push" — never "present, so skip".
+ */
+export function authPresenceFromProbe(probe) {
+    return {
+        reachable: probe.reachable,
+        remoteHasAuth: !!(probe.remoteBundles &&
+            Object.prototype.hasOwnProperty.call(probe.remoteBundles, AUTH_BUNDLE_NAME)),
+    };
+}
+/** Production default: live SSH probe of reachability + `secrets list --json`. */
+export function defaultAuthSyncProbe(device) {
+    return authPresenceFromProbe(probeDevice(device, { withSecrets: true }));
+}
+function defaultDevices() {
+    return Object.values(loadDevicesSync());
+}
+/**
+ * Push the local file-backed `auth` bundle to every pinned registered device
+ * that does not already have it. No-op when the local bundle is missing or on
+ * the wrong backend (doctor flags that separately).
+ */
+export function syncReservedAuthBundle(deps = {}) {
+    const inspect = deps.inspectLocal ?? inspectReservedAuthBundle;
+    const local = inspect();
+    const localOk = local.exists && local.ok;
+    const localName = normalizeHost(deps.localName ?? machineId());
+    const devices = (deps.listDevices ?? defaultDevices)().filter((d) => normalizeHost(d.name) !== localName);
+    const pinned = deps.isPinned ?? ((name) => isHostPinned(name, managedKnownHostsPath()));
+    const probe = deps.probe ?? defaultAuthSyncProbe;
+    const plan = planAuthBundlePush(localOk, devices.map((d) => {
+        // No live probe until we know a push is even possible: missing local auth
+        // skips every device, and an unpinned host is refused before we SSH.
+        if (!localOk) {
+            return { name: d.name, reachable: true, pinned: pinned(d.name), remoteHasAuth: false };
+        }
+        const isPinnedDev = pinned(d.name);
+        if (!isPinnedDev) {
+            return { name: d.name, reachable: true, pinned: false, remoteHasAuth: false };
+        }
+        const p = probe(d);
+        return {
+            name: d.name,
+            reachable: p.reachable,
+            pinned: true,
+            remoteHasAuth: p.remoteHasAuth,
+        };
+    }));
+    const pushed = [];
+    const skipped = [];
+    const errors = [];
+    const push = deps.push ?? ((bundle, host) => pushBundleToHost(bundle, host, {
+        remoteBackend: 'file',
+        operation: 'auth-sync',
+    }));
+    const targetOf = deps.sshTarget ?? sshTargetFor;
+    for (const item of plan) {
+        if (item.action === 'skip') {
+            skipped.push({ device: item.device, reason: item.reason });
+            continue;
+        }
+        const profile = devices.find((d) => d.name === item.device);
+        if (!profile) {
+            skipped.push({ device: item.device, reason: 'not in registry' });
+            continue;
+        }
+        try {
+            const host = targetOf(profile);
+            const out = push(AUTH_BUNDLE_NAME, host);
+            if (out.ok)
+                pushed.push(item.device);
+            else
+                errors.push({ device: item.device, message: out.message });
+        }
+        catch (err) {
+            errors.push({ device: item.device, message: err.message });
+        }
+    }
+    return { pushed, skipped, errors };
+}

package/dist/lib/self-heal/checks/hook-manifest.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const hookManifestCheck: HealCheck;

package/dist/lib/self-heal/checks/hook-manifest.js

@@ -0,0 +1,56 @@
+// hook-manifest check — detects manifest hooks whose `script:` resolves to
+// nothing, so they are registered in config but silently never installed.
+//
+// Why this exists. resolveHookScriptPath only resolves a manifest script under
+// <root>/hooks/, and resolveContainedHookPath rejects any candidate escaping
+// that root. A manifest entry pointing anywhere else returns null and the hook
+// is dropped — no error, no warning, no trace in `agents doctor`.
+//
+// That is not hypothetical. main-branch-guard was declared in agents.yaml as
+//   script: rules/subrules/truly-agentic-git-workflow/main-branch-guard.sh
+// which resolves to hooks/rules/subrules/... — a path that does not exist. The
+// guard was authored, tested with a 100+ case suite, and registered, yet
+// reached zero of 25 settings files across three machines. Nothing surfaced it;
+// it was found only after four agent sessions had written into a primary
+// checkout that this exact hook exists to prevent.
+//
+// A guard that silently does not run is worse than a missing one, because the
+// config says it is there. This check turns that silence into a finding.
+import { resultOf } from '../types.js';
+import { parseHookManifest, resolveHookScriptPath } from '../../hooks/install.js';
+export const hookManifestCheck = {
+    id: 'hook-manifest',
+    title: 'Hook manifest scripts resolve',
+    cadence: 'periodic',
+    async run(_ctx) {
+        const needsAttention = [];
+        let manifest;
+        try {
+            // warn:false — this check reports, it does not double-log.
+            manifest = parseHookManifest({ warn: false });
+        }
+        catch (err) {
+            return resultOf([], [`hook manifest unreadable: ${err.message}`]);
+        }
+        for (const [name, def] of Object.entries(manifest)) {
+            if (!def || typeof def.script !== 'string' || def.script.length === 0)
+                continue;
+            if (def.enabled === false)
+                continue;
+            // An absolute script (a subrule-composed hook) is used as-is by the
+            // installer, so only relative manifest paths go through the hooks/ root
+            // resolver that can silently return null.
+            if (def.script.startsWith('/'))
+                continue;
+            if (resolveHookScriptPath(def.script) === null) {
+                needsAttention.push(`hook '${name}' declares script '${def.script}', which resolves to no file under any hooks/ root — ` +
+                    `it is registered but silently never installed. Move the script under hooks/ (or point the manifest at ` +
+                    `an entrypoint there) so the installer can find it.`);
+            }
+        }
+        // Report only. Repair would mean guessing where the author meant the script
+        // to live, and a wrong guess would wire the wrong file into a PreToolUse
+        // gate. Naming the broken entry is the fix that belongs here.
+        return resultOf([], needsAttention);
+    },
+};

package/dist/lib/self-heal/registry.js

@@ -6,6 +6,7 @@
 // (all, or by id) — call runSelfHeal.
 import { resourcesCheck } from './checks/resources.js';
 import { hookRuntimeCheck } from './checks/hook-runtime.js';
+import { hookManifestCheck } from './checks/hook-manifest.js';
 import { shimsCheck } from './checks/shims.js';
 import { shadowingCheck } from './checks/shadowing.js';
 import { pathCheck } from './checks/path.js';
@@ -17,6 +18,9 @@ export const HEAL_CHECKS = [
     shadowingCheck,
     pathCheck,
     hookRuntimeCheck,
+    // Detect-only, after the runtime shim repair: a shim can be healthy while the
+    // manifest entry that should have produced it resolves nowhere.
+    hookManifestCheck,
     resourcesCheck,
 ];
 /** Run the selected checks, isolating per-check failures. */

package/dist/lib/self-heal/types.d.ts

@@ -1,4 +1,4 @@
-export type HealCheckId = 'resources' | 'hook-runtime' | 'shims' | 'shadowing' | 'path';
+export type HealCheckId = 'resources' | 'hook-runtime' | 'hook-manifest' | 'shims' | 'shadowing' | 'path';
 /** When the daemon schedules a check. */
 export type HealCadence = 'startup' | 'frequent' | 'periodic';
 export interface HealCtx {