@phnx-labs/agents-cli 1.22.56 → 1.22.58

package/dist/lib/secrets/remote.js

@@ -1,19 +1,9 @@
 /**
  * Remote secrets — read and use `agents secrets` bundles that live on another
- * host, over the same hardened SSH path that `agents secrets export --device`
- * (the write inverse) already uses.
+ * host over the same SSH path that `agents secrets export --device` uses.
  *
- * This is the READ / USE direction:
- *   - browse:  drive the remote `agents secrets list|view` and stream its
- *              stdout back verbatim (lossless, no parsing).
- *   - use:     resolve a remote bundle to an env map (JSON over ssh stdout) and
- *              inject it ephemerally — never written to this machine's keychain.
- *
- * 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. File-backend
- * import never forwards AGENTS_SECRETS_PASSPHRASE (PHNX-2371). Nothing is
- * persisted locally.
+ * Browse streams remote stdout verbatim; use resolves a bundle to an env map
+ * and injects it ephemerally without persisting it locally.
  */
 import { sshExec, sshStream, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
@@ -29,21 +19,8 @@ function hostKeyLookupName(target) {
     return target.split('@').pop() ?? target;
 }
 /**
- * SSH options for a SECRET-carrying transport (RUSH-2527). Every `agents secrets
- * --host` operation moves credential bytes — over ssh stdin (push) or ssh stdout
- * (resolve/read-back) — so it MUST NOT ride the shared `accept-new` baseline
- * against the user's own `~/.ssh/known_hosts` with a reusable control socket.
- * Two hardenings over that baseline, matching the posture the `--copy-creds`
- * dispatch already uses (`hosts/dispatch.ts` -> `hostKeyCheckingOpts`):
- *
- *   - **Managed pinned host keys.** Verify against the CLI-owned known_hosts
- *     store (`known-hosts.ts`), not `~/.ssh/known_hosts`. A CHANGED key on a
- *     known host is refused (`StrictHostKeyChecking` `yes` once pinned,
- *     `accept-new` before that). Callers that copy durable provider credentials
- *     must separately require an existing pin before invoking this transport.
- *   - **No multiplex reuse.** `multiplex: false` — a credential channel never
- *     leaves a persistent `ControlMaster` socket lingering (60s `ControlPersist`)
- *     that any other `agents` invocation to that host would silently reuse.
+ * SSH options for secret-carrying transport. Pins the managed host key and
+ * disables multiplex so no reusable control socket lingers for other invocations.
  */
 export function credentialTransportSshOpts(target) {
     return { hostKeyOpts: hostKeyCheckingOpts(isHostPinned(hostKeyLookupName(target))), multiplex: false };
@@ -56,47 +33,34 @@ export function assertCredentialTransportHostPinned(target, pinned = isHostPinne
         `Connect once with 'agents ssh ${target}' and verify the host, then retry.`);
 }
 /**
- * Trust boundary for a remote-resolved env map. A peer's `secrets export` output
- * is untrusted input: a compromised or misconfigured host could return keys that
- * silently reshape THIS process's behavior once merged into the agent env
- * (bundles.ts:251 `sanitizeProcessEnv` only strips loader vars from process.env,
- * never the remote bundle). Block the dangerous-override classes here — at the
- * source — so every consumer (`run --secrets b@host`, `secrets exec --host`) is
- * protected, not just one call site:
- *   - LD_* / DYLD_* / NODE_OPTIONS and the other loader/interpreter injections
- *     (reuses the canonical bundles.ts predicate);
- *   - GIT_*        — GIT_SSH_COMMAND et al. hijack every git subprocess;
- *   - *_PROXY      — HTTP(S)_PROXY / ALL_PROXY reroute outbound traffic (MITM);
- *   - *_BASE_URL   — ANTHROPIC_BASE_URL / OPENAI_BASE_URL redirect the model API.
- * These keys are already rejected on the ADD side (validateEnvKey for loaders),
- * so a legitimate bundle never carries them — only a hostile peer would.
+ * Trust boundary for a remote-resolved env map. A peer's export output is
+ * untrusted input that could reshape this process once merged into the env, so
+ * block dangerous override classes here for every consumer:
+ * loader/interpreter vars, GIT_*, *_PROXY, and *_BASE_URL.
  */
 export function isDangerousRemoteEnvKey(name) {
     const upper = name.toUpperCase();
     if (isLoaderOrInterpreterEnv(upper))
         return true;
     if (upper.startsWith('GIT_'))
-        return true;
+        return true; // GIT_SSH_COMMAND hijacks git subprocesses
     if (upper.endsWith('_PROXY'))
-        return true;
+        return true; // *_PROXY = MITM
     if (upper.endsWith('_BASE_URL'))
-        return true;
+        return true; // *_BASE_URL = model API redirect
     return false;
 }
 /** Remote OS for a host name or target string. Prefer the original host name
- * because enrolled inline hosts resolve to `user@address`, while the OS
- * registry is keyed by the host name. */
+ *  because enrolled inline hosts resolve to `user@address`, while the OS
+ *  registry is keyed by the host name. */
 function osForTarget(target, lookupName) {
     const byName = lookupName ? resolveRemoteOsSync(lookupName) : undefined;
     return byName ?? resolveRemoteOsSync(target.split('@').pop() ?? target);
 }
 /**
- * Resolve a `--device` value to an ssh target STRING for the remote-secrets path.
- * Delegates to the single host/device resolver (`resolveHost`, RUSH-1967) so a
- * name here dials the exact same box `run --device` does; on a miss, treats the
- * value as a raw ssh target and validates it against injection. Named distinctly
- * from `../devices/resolve-target.ts` (which returns richer shapes) so importing
- * the wrong one can't silently change which machine you dial.
+ * Resolve a `--device` value to an ssh target string for the remote-secrets
+ * path. Delegates to the same resolver `run --device` uses; on a miss, treats
+ * the value as a raw ssh target and validates it.
  */
 export async function resolveHostSshTarget(nameOrAlias) {
     const host = await resolveHost(nameOrAlias);
@@ -106,11 +70,8 @@ export async function resolveHostSshTarget(nameOrAlias) {
     return nameOrAlias;
 }
 /**
- * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
- * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
- * works. `--device`/`--devices` resolve identically to `--device`/`--hosts` so the
- * fleet-wide `--device` vocabulary (see `agents run --device`, `agents feed --host`)
- * works on the secrets remote commands too. Empty when none is set.
+ * Merge `--host` / `--hosts` (and their `--device` / `--devices` aliases) into
+ * an ordered, de-duplicated list. Empty when none is set.
  */
 export function parseHostsOption(opts) {
     const out = [];
@@ -135,11 +96,9 @@ export function parseHostsOption(opts) {
     return out;
 }
 /**
- * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
- * Bundle names can't contain `@` (BUNDLE_NAME_PATTERN), so the FIRST `@`
- * separates the bundle from the ssh target — and the target itself may be a
- * `user@host` (e.g. `r2.backups@muqsit@box` → bundle `r2.backups`, host
- * `muqsit@box`).
+ * Split a `bundle@host` reference. No `@` → a local bundle. Bundle names can't
+ * contain `@`, so the FIRST `@` separates bundle from ssh target; the target
+ * itself may be `user@host` (e.g. `r2.backups@muqsit@box`).
  */
 export function splitBundleRef(ref) {
     const at = ref.indexOf('@');
@@ -154,19 +113,13 @@ export function splitBundleRef(ref) {
 }
 /**
  * Run `agents secrets <args>` on a remote host over ssh and return the raw
- * result. Used by the browse commands — the remote's human-readable stdout is
- * streamed back unchanged. `tty` forces an interactive ssh session (`-tt`) so a
- * remote Touch-ID / passphrase prompt can surface (e.g. `view --reveal`).
+ * result. Used by browse commands; `tty` forces `-tt` so remote passphrase
+ * prompts can surface.
  */
 export function remoteSecretsRaw(target, args, opts = {}) {
     const remoteCmd = buildRemoteAgentsInvocation(['secrets', ...args], undefined, osForTarget(target, opts.osLookupName));
-    // A secret-bearing call (`secret: true`) pins the managed host key and refuses
-    // to multiplex — see `credentialTransportSshOpts` (RUSH-2527). A `-tt` session
-    // (a remote reveal/passphrase prompt) additionally allocates a PTY and never
-    // multiplexes, and it COMPOSES with the secret posture: a `view --reveal` over
-    // `--device` both prompts AND streams the plaintext value back over ssh stdout,
-    // so it needs the managed host-key pin too — `tty` must not short-circuit past
-    // `secret`. A plain browse `list` passes neither and keeps the shared baseline.
+    // `secret: true` pins the managed host key and refuses multiplex; `-tt`
+    // additionally allocates a PTY and never multiplexes. The two compose.
     const posture = opts.secret ? credentialTransportSshOpts(target) : {};
     const conn = opts.tty
         ? { ...posture, extraSshArgs: ['-tt'], multiplex: false }
@@ -178,49 +131,28 @@ export function remoteSecretsRaw(target, args, opts = {}) {
     });
 }
 /**
- * Run a remote `agents secrets <args>` FOREGROUND, with the local stdio wired
- * straight through (`stdio: 'inherit'` + `-tt`), and return its exit code.
- *
- * Unlike `remoteSecretsRaw` — which pipes stdin, so even with `-tt` the remote
- * process's `process.stdin.isTTY` is false and a passphrase prompt refuses to
- * appear (the macOS file-store guard then hard-errors "needs
- * AGENTS_SECRETS_PASSPHRASE") — this inherits the caller's real terminal, so the
- * remote sees a genuine TTY and its hidden passphrase prompt surfaces and reads
- * the keystrokes. This is the transport for `unlock --device`: you type the remote
- * bundle's passphrase at your own terminal. Output is NOT captured (it streams
- * to the terminal); only the exit code is returned.
+ * Run a remote `agents secrets <args>` foreground with local stdio inherited,
+ * so the remote sees a real TTY and its passphrase prompt surfaces and reads
+ * keystrokes. Output streams to the terminal; only the exit code is returned.
  */
 export function remoteSecretsStream(target, args, opts = {}) {
     const remoteCmd = buildRemoteAgentsInvocation(['secrets', ...args], undefined, osForTarget(target, opts.osLookupName));
-    // `unlock --device` carries the remote bundle's passphrase to the destination over
-    // this interactive channel, so it is secret-bearing: pin the managed host key
-    // (a changed key is refused) and never multiplex (RUSH-2527).
     return sshStream(target, remoteCmd, { tty: true, ...credentialTransportSshOpts(target) });
 }
 /**
  * Resolve a remote bundle to a plaintext env map by driving the remote's
  * `agents secrets export <bundle> --plaintext --format json`. Values cross over
- * ssh stdout (encrypted in transit), parsed in memory, never persisted.
+ * ssh stdout, parsed in memory, never persisted.
  *
- * The remote unlocks the bundle with ITS OWN credentials — the owner host's
- * keychain/secrets-agent, or its own `AGENTS_SECRETS_PASSPHRASE` (in the login
- * env) for a file-backed bundle. We deliberately do NOT forward this machine's
- * passphrase: the remote bundle is encrypted with the remote's passphrase, so
- * overriding it would break the read. (A macOS remote under non-interactive
- * SSH will block on Touch-ID — use `view`/`exec` with a remote `file` bundle,
- * an already-unlocked remote secrets-agent, or an interactive `-tt` session.)
+ * The remote unlocks the bundle with its own credentials; this machine does NOT
+ * forward its passphrase because the remote bundle is encrypted with the
+ * remote's passphrase.
  */
 export async function remoteResolveEnv(target, bundle, opts = {}) {
     assertValidSshTarget(target);
-    // AGENTS_SECRETS_REMOTE_TRANSPORT is the marker that lets the remote's
-    // `export --plaintext --format json` emit at all — the public shell-eval
-    // export mode was removed (RUSH-2774), and this machine-to-machine resolve is
-    // the only surviving caller of the JSON emitter. Riding the legacy argv keeps
-    // a new driver compatible with an old remote during a fleet rollout.
+    // AGENTS_SECRETS_REMOTE_TRANSPORT marks this as the machine-to-machine JSON
+    // resolve path (the public shell-eval export mode was removed).
     const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName), { AGENTS_SECRETS_REMOTE_TRANSPORT: '1' });
-    // Resolving a remote bundle streams its plaintext values back over ssh stdout,
-    // so this read is secret-bearing: pin the managed host key and never leave a
-    // reusable control master to the source (RUSH-2527, `credentialTransportSshOpts`).
     const res = sshExec(target, remoteCmd, {
         timeoutMs: REMOTE_TIMEOUT_MS,
         ...credentialTransportSshOpts(target),
@@ -249,8 +181,7 @@ export async function remoteResolveEnv(target, bundle, opts = {}) {
     const env = {};
     const blocked = [];
     for (const [k, v] of Object.entries(parsed)) {
-        // Drop dangerous-override keys returned by the (untrusted) peer before they
-        // can reshape this process — see isDangerousRemoteEnvKey.
+        // Drop dangerous-override keys returned by the (untrusted) peer.
         if (isDangerousRemoteEnvKey(k)) {
             blocked.push(k);
             continue;
@@ -261,10 +192,7 @@ export async function remoteResolveEnv(target, bundle, opts = {}) {
         process.stderr.write(`[secrets] Dropped ${blocked.length} dangerous key(s) from '${bundle}'@${target} ` +
             `(remote override blocked): ${blocked.join(', ')}\n`);
     }
-    // The remote host audits its own `secrets export` read; this emit records the
-    // event on the INITIATING host too (values were pulled into this process and
-    // injected locally). Covers `secrets exec --host` and `run --secrets b@host`.
-    // Values never enter the payload — only the bundle, target host, and count.
+    // Audit the event on the initiating host too; values never enter the payload.
     emitSecretAudit({
         event: 'secrets.get',
         bundle,
@@ -277,56 +205,32 @@ export async function remoteResolveEnv(target, bundle, opts = {}) {
     return env;
 }
 /**
- * The remote's headless read-back raises one of these when a keychain-backed bundle
- * has metadata but no readable value items — the exact locked-login-keychain
- * signature. Anything else (connection refused, timeout, host key error) is a
- * transient/unrelated failure and must NOT be mislabeled as a locked keychain.
+ * True when the remote's headless read-back raised the locked-login-keychain
+ * signature. Anything else must NOT be mislabeled as a locked keychain.
  */
 function isLockedKeychainReadBackError(stderr) {
     const s = stderr.toLowerCase();
-    return (
-    // bundles.ts agentOnly guard: "…is not unlocked in the secrets agent…"
-    s.includes('not unlocked') ||
+    return (s.includes('not unlocked') ||
         s.includes('secrets agent') ||
-        // resolveBundleEnv: "Bundle '<b>' key '<k>': stored item '<item>' not found."
         s.includes('stored item') ||
         s.includes('not found'));
 }
 /**
- * Decide whether a keychain-backed push to a remote actually PERSISTED its secret
- * value items, given the read-back of that bundle from the remote's own store.
- *
- * The silent-failure this guards: pushing `--remote-backend keychain` (default) to
- * a macOS host over headless SSH lands the bundle METADATA but not readable value
- * items — the remote login keychain is locked in the non-interactive SSH context,
- * so Security accepts the item WRITE at the DB level but the biometry-ACL'd item is
- * unreadable, and the remote `import` still reports success (values written first,
- * metadata `noAcl` last — bundles.ts writeBundleWithItems). The metadata-only bundle
- * then fails every later read with the confusing `Bundle '<b>' key '<k>': stored
- * item '<item>' not found` (bundles.ts resolveBundleEnv). We catch it by reading
- * the bundle back the same way a later `secrets exec`/resolve will (the marker-gated
- * json transport, driven headlessly on the remote so its `agentOnly` guard FAILS FAST
- * before any keychain read — no Touch ID prompt) and confirming every pushed key
- * returned.
- *
- * Pure so both branches are unit-testable without a real locked keychain: inject the
- * "read-back failed / key absent" condition through `readBack`.
+ * Decide whether a keychain-backed push to a remote actually persisted its
+ * secret value items by reading the bundle back the same way a later resolve
+ * will. Catches the silent failure where headless SSH writes metadata but not
+ * readable value items to a locked macOS login keychain.
  */
 export function evaluateKeychainWriteVerification(pushedKeys, readBack) {
     if (!readBack.ok) {
         const stderr = readBack.stderr.trim();
         if (isLockedKeychainReadBackError(stderr)) {
-            // The remote's own headless read raised the not-unlocked / not-found signal —
-            // exactly the confusing error the user hits later. Surface it now, at push
-            // time, with the fix.
             return {
                 ok: false,
                 kind: 'locked-keychain',
                 reason: `the remote could not read it back${stderr ? ` (${stderr})` : ''}`,
             };
         }
-        // A transient / unrelated failure (flaky SSH, timeout, bad payload). Re-surface
-        // verbatim — do NOT diagnose a locked keychain from a connection error.
         return {
             ok: false,
             kind: 'error',
@@ -336,8 +240,6 @@ export function evaluateKeychainWriteVerification(pushedKeys, readBack) {
     const present = new Set(readBack.keys);
     const missing = pushedKeys.filter((k) => !present.has(k));
     if (missing.length > 0) {
-        // Read-back succeeded but some pushed keys are absent — the value items didn't
-        // persist. Same locked-keychain cause and fix.
         return {
             ok: false,
             kind: 'locked-keychain',
@@ -348,10 +250,8 @@ export function evaluateKeychainWriteVerification(pushedKeys, readBack) {
     return { ok: true };
 }
 /**
- * The actionable error message for a failed keychain-over-SSH push verification.
- * Names the cause (locked remote login keychain) and steers to the two real fixes:
- * re-run with the headless-readable file backend, or unlock the remote keychain.
- * Pure + exported so the exact guidance is asserted in tests.
+ * Actionable error message for a failed keychain-over-SSH push. Names the cause
+ * (locked remote login keychain) and steers to the two real fixes.
  */
 export function keychainWriteFailureMessage(host, bundle, reason) {
     return (`${host}: pushed '${bundle}' but the keychain items did not persist — ${reason}. ` +
@@ -363,22 +263,12 @@ export function keychainWriteFailureMessage(host, bundle, reason) {
         `(e.g. an interactive login / \`agents secrets unlock\` on ${host}) and retry.`);
 }
 /**
- * Read a bundle back from a remote over SSH (headlessly, so it fails fast rather
- * than prompting Touch ID) and confirm the pushed keys materialized. Drives the
- * remote's marker-gated json transport (`secrets export <bundle> --plaintext
- * --format json` under AGENTS_SECRETS_REMOTE_TRANSPORT) but keeps only the KEY
- * NAMES; the plaintext values are dropped immediately and never retained or
- * logged. Returns a verification verdict; the caller renders
- * `keychainWriteFailureMessage` on failure.
+ * Read a bundle back from a remote over SSH and confirm the pushed keys
+ * materialized. Drives the marker-gated json transport but keeps only KEY NAMES;
+ * plaintext values are discarded immediately. Returns a verification verdict.
  */
 export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {}) {
-    const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName), 
-    // Same transport marker as remoteResolveEnv — see the comment there (RUSH-2774).
-    { AGENTS_SECRETS_REMOTE_TRANSPORT: '1' });
-    // This read-back streams the just-pushed plaintext over ssh stdout, so it is
-    // as secret-bearing as the push itself — the push path passes `secret: true`
-    // so it too pins the managed host key and leaves no reusable control master to
-    // the destination (RUSH-2527).
+    const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName), { AGENTS_SECRETS_REMOTE_TRANSPORT: '1' });
     const res = sshExec(target, remoteCmd, {
         timeoutMs: REMOTE_TIMEOUT_MS,
         ...(opts.secret ? credentialTransportSshOpts(target) : {}),
@@ -388,8 +278,7 @@ export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {})
         const stderr = `${why}${(res.stderr || res.stdout || '').trim() ? `: ${(res.stderr || res.stdout).trim()}` : ''}`;
         return evaluateKeychainWriteVerification(pushedKeys, { ok: false, stderr });
     }
-    // Take the outer { … } object (tolerate login-shell banner noise), read the key
-    // names, and immediately discard the values — we only need presence here.
+    // Tolerate login-shell banner noise; keep only key names and discard values.
     const raw = res.stdout;
     const start = raw.indexOf('{');
     const end = raw.lastIndexOf('}');
@@ -414,24 +303,17 @@ export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {})
     return evaluateKeychainWriteVerification(pushedKeys, { ok: true, keys });
 }
 /**
- * The `bash -lc` command + stdin payload that drives a **file-backed** remote
- * import for `secrets export --device … --remote-backend file`.
+ * `bash -lc` command + stdin payload for a file-backed remote import.
  *
- * 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
+ * The file store is passphrase-free: the remote auto-provisions its own machine-
+ * local key, so reads are headless. AGENTS_SECRETS_PASSPHRASE 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 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}`;
-    // 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.
     return { remoteCmd: `bash -lc ${shellQuote(importCmd)}`, input: dotenv };
 }

package/dist/lib/self-heal/checks/install-staging.d.ts

@@ -0,0 +1,4 @@
+import type { HealCheck } from '../types.js';
+/** A concurrent upgrade must be long finished before an unattended sweep may touch its staging dir. */
+export declare const STALE_INSTALL_STAGING_AGE_MS: number;
+export declare const installStagingCheck: HealCheck;

package/dist/lib/self-heal/checks/install-staging.js

@@ -0,0 +1,96 @@
+// install-staging check — fleet-wide self-heal for the orphaned npm reify
+// staging dir that dead-ends `agents upgrade` forever (PHNX-3393).
+//
+// `agents upgrade` itself sweeps this orphan proactively before every reify
+// (sweepStaleInstallStaging in self-update.ts), so a box that runs `agents
+// upgrade` regularly never accumulates one. This check exists for the box
+// that does NOT: one that stopped upgrading after the crash that left the
+// orphan behind, so the next manual `agents upgrade` would still hit the same
+// ENOTEMPTY the sweep exists to prevent, and nothing runs `agents upgrade` to
+// trigger that sweep in the meantime. Periodic cadence closes that gap
+// fleet-wide (via the daemon's self-heal service) and on demand via
+// `agents doctor --fix`.
+//
+// The age guard is load-bearing: a staging dir can be legitimately mid-write
+// by a CONCURRENT upgrade this instant. Only a dir older than the guard is
+// touched, so an unattended periodic run can never delete a live reify.
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { resultOf } from '../types.js';
+import { resolveRunningPackageRoot } from '../../self-update.js';
+const __installStagingDirname = path.dirname(fileURLToPath(import.meta.url));
+/** A concurrent upgrade must be long finished before an unattended sweep may touch its staging dir. */
+export const STALE_INSTALL_STAGING_AGE_MS = 10 * 60 * 1000;
+/**
+ * Find the retire-path staging dir(s) for `packageRoot` older than
+ * `maxAgeMs`. Reimplements the same matching self-update.ts's
+ * sweepStaleInstallStaging uses, so the age guard can be checked BEFORE
+ * anything is deleted — the sweep helper itself removes unconditionally,
+ * which is correct for the upgrade hot path (nothing else touches that
+ * path while an upgrade you just started is running) but wrong for an
+ * unattended periodic sweep that could race a concurrent upgrade.
+ */
+function findAgedInstallStaging(packageRoot, maxAgeMs, now) {
+    const resolved = path.resolve(packageRoot);
+    const dir = path.dirname(resolved);
+    const base = path.basename(resolved);
+    const escapedBase = base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const stagingPattern = new RegExp(`^\\.${escapedBase}-[a-zA-Z0-9]+$`);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const aged = [];
+    for (const entry of entries) {
+        if (!stagingPattern.test(entry))
+            continue;
+        const full = path.join(dir, entry);
+        let mtimeMs;
+        try {
+            mtimeMs = fs.statSync(full).mtimeMs;
+        }
+        catch {
+            continue; // vanished between readdir and stat — nothing to sweep
+        }
+        if (now - mtimeMs >= maxAgeMs)
+            aged.push(full);
+    }
+    return aged;
+}
+export const installStagingCheck = {
+    id: 'install-staging',
+    title: 'Orphaned npm reify staging dir',
+    cadence: 'periodic',
+    async run(ctx) {
+        let packageRoot;
+        try {
+            packageRoot = resolveRunningPackageRoot(__installStagingDirname);
+        }
+        catch {
+            // Not an npm/bun-managed install (source checkout) — nothing to sweep.
+            return resultOf([], []);
+        }
+        const aged = findAgedInstallStaging(packageRoot, STALE_INSTALL_STAGING_AGE_MS, Date.now());
+        if (aged.length === 0)
+            return resultOf([], []);
+        if (ctx.dryRun) {
+            return resultOf(aged.map((p) => `orphaned reify staging dir: ${p}`), []);
+        }
+        const fixed = [];
+        const needsAttention = [];
+        for (const stagingPath of aged) {
+            try {
+                fs.rmSync(stagingPath, { recursive: true, force: true });
+                fixed.push(`removed orphaned reify staging dir ${stagingPath} — the next 'agents upgrade' can reify cleanly`);
+            }
+            catch (err) {
+                needsAttention.push(`could not remove orphaned reify staging dir ${stagingPath}: ${err.message}`);
+            }
+        }
+        return resultOf(fixed, needsAttention);
+    },
+};

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

@@ -10,6 +10,7 @@ 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';
+import { installStagingCheck } from './checks/install-staging.js';
 // Order matters: cheap structural fixes (shims, shadow adoption, PATH, generated
 // hook wrappers) before the heavier resource reconciliation, so a freshly-
 // repaired shim is in place first.
@@ -22,6 +23,7 @@ export const HEAL_CHECKS = [
     // manifest entry that should have produced it resolves nowhere.
     hookManifestCheck,
     resourcesCheck,
+    installStagingCheck,
 ];
 /** Run the selected checks, isolating per-check failures. */
 export async function runSelfHeal(opts = {}) {

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

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

package/dist/lib/self-update.d.ts

@@ -130,6 +130,29 @@ export declare function resolveRunningPackageRoot(dirname: string, execPath?: st
  * one is exactly the bug this module exists to prevent.
  */
 export declare function deriveGlobalPrefix(packageRoot: string): string;
+/**
+ * Sweep npm arborist's "retired" staging dir for `packageRoot` before a
+ * reify (PHNX-3393).
+ *
+ * npm (@npmcli/arborist) reifies an install by first renaming the tree it is
+ * about to replace out of the way into a sibling directory —
+ * `retirePath(from)` in arborist's own source names it
+ * `.<basename>-<8-char sha1 hash of the full path>`, sibling to `from` — then
+ * stages the new tree and renames it into place. Because the hash is a pure
+ * function of `packageRoot`'s path, that staging path is IDENTICAL on every
+ * reify of this install. A crash between the retire-rename and the final
+ * rename (SIGKILL, a killed terminal, a box that lost power mid-upgrade)
+ * leaves that exact directory behind, non-empty. `rename(2)` cannot replace a
+ * non-empty directory, so every subsequent upgrade's reify fails ENOTEMPTY at
+ * the same path forever — nothing about a plain retry ever clears it.
+ *
+ * Removing any stale `.<basename>-*` sibling before install self-heals this:
+ * npm re-stages cleanly once the collision is gone. Matches only the
+ * retire-path shape (a dot-prefixed sibling starting with the package's own
+ * basename), so an unrelated dotfile in the same directory is left alone.
+ * Best-effort per entry: one unremovable sibling must not block the rest.
+ */
+export declare function sweepStaleInstallStaging(packageRoot: string): string[];
 /**
  * Install `spec` into an explicit global prefix. `--prefix` pins the
  * destination no matter which npm binary PATH resolves. `--ignore-scripts`

package/dist/lib/self-update.js

@@ -292,6 +292,56 @@ export function deriveGlobalPrefix(packageRoot) {
     const parent = path.dirname(nodeModulesDir);
     return path.basename(parent) === 'lib' ? path.dirname(parent) : parent;
 }
+/**
+ * Sweep npm arborist's "retired" staging dir for `packageRoot` before a
+ * reify (PHNX-3393).
+ *
+ * npm (@npmcli/arborist) reifies an install by first renaming the tree it is
+ * about to replace out of the way into a sibling directory —
+ * `retirePath(from)` in arborist's own source names it
+ * `.<basename>-<8-char sha1 hash of the full path>`, sibling to `from` — then
+ * stages the new tree and renames it into place. Because the hash is a pure
+ * function of `packageRoot`'s path, that staging path is IDENTICAL on every
+ * reify of this install. A crash between the retire-rename and the final
+ * rename (SIGKILL, a killed terminal, a box that lost power mid-upgrade)
+ * leaves that exact directory behind, non-empty. `rename(2)` cannot replace a
+ * non-empty directory, so every subsequent upgrade's reify fails ENOTEMPTY at
+ * the same path forever — nothing about a plain retry ever clears it.
+ *
+ * Removing any stale `.<basename>-*` sibling before install self-heals this:
+ * npm re-stages cleanly once the collision is gone. Matches only the
+ * retire-path shape (a dot-prefixed sibling starting with the package's own
+ * basename), so an unrelated dotfile in the same directory is left alone.
+ * Best-effort per entry: one unremovable sibling must not block the rest.
+ */
+export function sweepStaleInstallStaging(packageRoot) {
+    const resolved = path.resolve(packageRoot);
+    const dir = path.dirname(resolved);
+    const base = path.basename(resolved);
+    const escapedBase = base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const stagingPattern = new RegExp(`^\\.${escapedBase}-[a-zA-Z0-9]+$`);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const swept = [];
+    for (const entry of entries) {
+        if (!stagingPattern.test(entry))
+            continue;
+        const full = path.join(dir, entry);
+        try {
+            fs.rmSync(full, { recursive: true, force: true });
+            swept.push(full);
+        }
+        catch {
+            /* best-effort — one unremovable stager must not block the rest */
+        }
+    }
+    return swept;
+}
 /**
  * Install `spec` into an explicit global prefix. `--prefix` pins the
  * destination no matter which npm binary PATH resolves. `--ignore-scripts`