@phnx-labs/agents-cli 1.22.23 → 1.22.24

package/dist/lib/secrets/bundles.js

@@ -294,6 +294,26 @@ export function readBundle(name) {
         if (vaultExists() && !getVaultSession().loggedIn) {
             throw new Error(`Synced secrets are locked. Run: agents login`);
         }
+        // Distinguish a genuinely-absent bundle from a present-but-unreadable one
+        // (a locked login keychain, or a legacy ACL'd metadata item before first
+        // unlock). `has` counts an unreadable item as present, so a metadata item
+        // that exists but could not be read must not report as "not found" — an
+        // existence answer and a read answer may not contradict (RUSH-2253).
+        if (backend === 'keychain') {
+            let present;
+            try {
+                present = hasKeychainToken(bundleMetaItem(name));
+            }
+            catch (probeErr) {
+                // Keychain unreachable (RUSH-2235 fail-loud): neither absent nor
+                // add-the-key — surface the reachability failure, not a false absence.
+                throw new Error(`Secrets bundle '${name}': ${probeErr.message}`);
+            }
+            if (present) {
+                throw new Error(`Secrets bundle '${name}' is present but its metadata could not be read — the keychain is locked. ` +
+                    `Unlock it (log in, or reboot then log in) and retry. (${err.message})`);
+            }
+        }
         throw new Error(`Secrets bundle '${name}' not found.`);
     }
     let parsed;
@@ -1060,6 +1080,91 @@ export function assertRemoteBundleFlagsUnsupported(bundleName, host, opts, flagL
     throw new Error(`Bundle '${bundleName}@${host}': ${flagLabels.keysFlag} and ${flagLabels.allowExpiredFlag} are not supported for remote (bundle@host) bundles yet. ` +
         `Drop the flag or resolve the bundle locally.`);
 }
+/**
+ * A declared `keychain:` ref resolved to NO value in the batch read. Classify
+ * genuinely-absent vs present-but-unreadable before choosing the error, so a
+ * read can never contradict what `agents secrets view` reports (RUSH-2248,
+ * RUSH-2253). `view`'s "stored" badge comes from `hasKeychainToken` — the exact
+ * existence probe used here — which counts a biometry-ACL'd or locked-keychain
+ * item (`errSecInteractionNotAllowed`) as present. So:
+ *
+ *   - present  ⇒ the item exists but this context could not read it (keychain
+ *     locked, or Touch ID not granted). Report HOW to unlock; NEVER
+ *     "add the key", whose remediation (`secrets add`) would overwrite a good
+ *     secret.
+ *   - absent   ⇒ genuinely not stored on this machine — the honest "not found"
+ *     with the `secrets add` remediation.
+ *   - probe throws ⇒ the keychain itself is unreachable (RUSH-2235 fail-loud):
+ *     neither absent nor add-the-key — surface the reachability failure verbatim.
+ *
+ * Only the keychain backend has a locked/biometry state; a file/vault miss is
+ * genuinely absent.
+ */
+function missingBundleKeychainItemError(bundleName, key, item, backendKind) {
+    if (backendKind === 'keychain') {
+        let present;
+        try {
+            present = hasKeychainToken(item);
+        }
+        catch (err) {
+            return new Error(`Bundle '${bundleName}' key '${key}': ${err.message}`);
+        }
+        if (present) {
+            return new Error(`Bundle '${bundleName}' key '${key}': stored item '${item}' is present but could not be read — ` +
+                `the keychain is locked or Touch ID was not granted for this read. ` +
+                `Run: agents secrets unlock ${bundleName}  (or read it once at an interactive terminal so Touch ID can be granted). ` +
+                `Do NOT run 'agents secrets add' — the secret is already stored and adding would overwrite it.`);
+        }
+    }
+    return new Error(`Bundle '${bundleName}' key '${key}': stored item '${item}' not found. ` +
+        `Run: agents secrets add ${bundleName} ${key}`);
+}
+/**
+ * Resolve every selected key of an already-read bundle into a flat env map,
+ * given a pre-fetched keychain batch. The single per-key resolution loop shared
+ * by `resolveBundleEnv` and `readAndResolveBundleEnv` so the keychain lookup and
+ * the missing-item classification can never diverge again (RUSH-2252: the two
+ * paths drifted — one did the hashed-alias fallback lookup and one did not, and
+ * only one classified a missing item honestly).
+ *
+ * The keychain lookup tries the cleartext name first (Linux / file store), then
+ * its hashed storage alias (macOS with #316 hashing active) — the batch keys its
+ * results by the names it was ASKED for, which for the metadata + declared keys
+ * is the cleartext form and for an enumerated leftover is the hashed form.
+ */
+function assembleBundleEnv(bundle, selectedKeys, parsedByKey, fetched, keyMode, backendKind) {
+    const env = {};
+    const owners = new Map();
+    for (const [key] of Object.entries(bundle.vars)) {
+        if (!selectedKeys.has(key))
+            continue;
+        const parsed = parsedByKey.get(key);
+        if ('literal' in parsed) {
+            assignResolvedEnvValue(env, bundle, key, parsed.literal, keyMode, owners);
+            continue;
+        }
+        if (parsed.ref.provider === 'keychain') {
+            const item = secretsKeychainItem(bundle.name, parsed.ref.value);
+            const value = fetched.get(item) ?? fetched.get(keychainServiceAlias(item));
+            if (value === undefined) {
+                throw missingBundleKeychainItemError(bundle.name, key, item, backendKind);
+            }
+            assignResolvedEnvValue(env, bundle, key, value, keyMode, owners);
+            continue;
+        }
+        try {
+            const value = resolveRef(parsed.ref, {
+                allowExec: bundle.allow_exec,
+                keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
+            });
+            assignResolvedEnvValue(env, bundle, key, value, keyMode, owners);
+        }
+        catch (err) {
+            throw new Error(`Bundle '${bundle.name}' key '${key}': ${err.message}`);
+        }
+    }
+    return env;
+}
 // Walk the bundle and produce a flat env map. Every keychain: ref is gathered
 // into a single batch read so macOS shows ONE Touch ID prompt for the whole
 // bundle — including the metadata fetch that already happened in readBundle
@@ -1093,37 +1198,7 @@ export function resolveBundleEnv(bundle, _opts = {}) {
             ? getKeychainTokens(keychainItemsToFetch, { silentNoAcl: bundlePolicy(bundle) === 'never' })
             : store.getBatch(keychainItemsToFetch)
         : new Map();
-    const env = {};
-    const owners = new Map();
-    for (const [key, raw] of Object.entries(bundle.vars)) {
-        if (!selectedKeys.has(key))
-            continue;
-        const parsed = parsedByKey.get(key);
-        if ('literal' in parsed) {
-            assignResolvedEnvValue(env, bundle, key, parsed.literal, _opts.keyMode, owners);
-            continue;
-        }
-        if (parsed.ref.provider === 'keychain') {
-            const item = secretsKeychainItem(bundle.name, parsed.ref.value);
-            const value = fetched.get(item);
-            if (value === undefined) {
-                throw new Error(`Bundle '${bundle.name}' key '${key}': stored item '${item}' not found. ` +
-                    `Run: agents secrets add ${bundle.name} ${key}`);
-            }
-            assignResolvedEnvValue(env, bundle, key, value, _opts.keyMode, owners);
-            continue;
-        }
-        try {
-            const value = resolveRef(parsed.ref, {
-                allowExec: bundle.allow_exec,
-                keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
-            });
-            assignResolvedEnvValue(env, bundle, key, value, _opts.keyMode, owners);
-        }
-        catch (err) {
-            throw new Error(`Bundle '${bundle.name}' key '${key}': ${err.message}`);
-        }
-    }
+    const env = assembleBundleEnv(bundle, selectedKeys, parsedByKey, fetched, _opts.keyMode, bundle.backend ?? 'keychain');
     // `caller` is intentionally unused; see ResolveBundleOptions.
     void _opts.caller;
     return env;
@@ -1327,6 +1402,53 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     }
     const keys = [...selectedKeys].sort();
     keychainKeys.sort();
+    // RUSH-2252: complete the read set from the bundle's DECLARED keys, not only
+    // from the enumeration above. `store.list()` derives the batch by enumerating
+    // the bundle's namespace, and that enumeration is lossy by construction — the
+    // macOS helper's `list` omits every biometry-ACL'd item
+    // (`kSecUseAuthenticationUISkip`) and skips the whole data-protection pass when
+    // the keychain is locked, so a `hold`-policy bundle's value items never appear
+    // and a present secret reads as "not found" (RUSH-2248). A declared key whose
+    // item did not enumerate is therefore absent from `fetched`; read those exact
+    // items directly — a point read DOES evaluate the ACL, so it triggers Touch ID
+    // and returns the value the enumeration could not see. The enumeration still
+    // earns its place (it catches hashed/aliased storage names and stale leftovers
+    // not named in the metadata), so this is a UNION, not a replacement.
+    //
+    // One Touch ID sheet is preserved: the items missing from `fetched` are exactly
+    // the ACL'd ones the enumeration dropped, so the first batch (metadata plus any
+    // no-ACL / `never` items) raised no sheet, and this second batch raises the
+    // single sheet that covers all of them. When the enumeration is healthy every
+    // declared item is already in `fetched`, `missingDeclared` is empty, and this
+    // is skipped entirely — zero behavior change and no extra spawn on the hot path.
+    if (backend === 'keychain') {
+        const missingDeclared = [];
+        for (const key of keychainKeys) {
+            const p = parsedByKey.get(key);
+            if (!('ref' in p) || p.ref.provider !== 'keychain')
+                continue;
+            const item = secretsKeychainItem(bundle.name, p.ref.value);
+            if (fetched.get(item) === undefined && fetched.get(keychainServiceAlias(item)) === undefined) {
+                missingDeclared.push(item);
+            }
+        }
+        if (missingDeclared.length > 0) {
+            const declaredFetched = getKeychainTokens([...new Set(missingDeclared)], {
+                agent: opts.agent || process.env.AGENTS_AGENT_NAME || 'Agents CLI',
+                bundle: name,
+                sessionId: process.env.AGENT_SESSION_ID || process.env.AGENTS_SESSION_ID,
+                reason: opts.caller ? `to ${opts.caller}` : reason,
+                duration: opts.duration || humanUnlockDuration(secretsHoldMs()),
+                // The policy is known now (metadata parsed), so the prompt names the real
+                // duration instead of the pre-read default the first batch had to guess.
+                defaultPolicy: bundlePolicy(bundle),
+                forceDuration: Boolean(opts.duration),
+                silentNoAcl: verifiedNoAclBundle,
+            });
+            for (const [k, v] of declaredFetched)
+                fetched.set(k, v);
+        }
+    }
     const emitReadAudit = (status, err) => {
         emitSecretAudit({
             event: 'secrets.get',
@@ -1342,40 +1464,10 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         });
     };
     try {
-        const env = {};
-        const owners = new Map();
-        for (const [key] of Object.entries(bundle.vars)) {
-            if (!selectedKeys.has(key))
-                continue;
-            const p = parsedByKey.get(key);
-            if ('literal' in p) {
-                assignResolvedEnvValue(env, bundle, key, p.literal, opts.keyMode, owners);
-                continue;
-            }
-            if (p.ref.provider === 'keychain') {
-                const item = secretsKeychainItem(bundle.name, p.ref.value);
-                // The batch keys results by the names it was ASKED for: the cleartext
-                // metaItem, plus enumerated storage names. Look up the cleartext name
-                // first (Linux / file store), then its hashed storage alias (macOS).
-                const value = fetched.get(item) ?? fetched.get(keychainServiceAlias(item));
-                if (value === undefined) {
-                    throw new Error(`Bundle '${bundle.name}' key '${key}': stored item '${item}' not found. ` +
-                        `Run: agents secrets add ${bundle.name} ${key}`);
-                }
-                assignResolvedEnvValue(env, bundle, key, value, opts.keyMode, owners);
-                continue;
-            }
-            try {
-                const value = resolveRef(p.ref, {
-                    allowExec: bundle.allow_exec,
-                    keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
-                });
-                assignResolvedEnvValue(env, bundle, key, value, opts.keyMode, owners);
-            }
-            catch (err) {
-                throw new Error(`Bundle '${bundle.name}' key '${key}': ${err.message}`);
-            }
-        }
+        // Shared per-key resolver: same keychain lookup (cleartext name, then hashed
+        // storage alias) and same missing-item classification as resolveBundleEnv, so
+        // the two paths can never diverge again (RUSH-2252, RUSH-2253).
+        const env = assembleBundleEnv(bundle, selectedKeys, parsedByKey, fetched, opts.keyMode, backend);
         emitReadAudit('success');
         // Auto-cache: this was a real keychain read (the agent fast-path returned
         // earlier on a hit). If the bundle opts into the `daily` policy and the user

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

@@ -29,9 +29,11 @@ export declare function machinePassphraseExists(): boolean;
  * Resolve the passphrase for the encrypted file store.
  *
  * Order: AGENTS_SECRETS_PASSPHRASE > previously-provisioned machine-local key >
- * a freshly auto-provisioned machine-local key. It NEVER prompts and NEVER
- * hard-fails — the file store must work on every platform (macOS included)
- * without the user setting, typing, or remembering a passphrase. Provisioning
+ * legacy co-located key > a freshly auto-provisioned machine-local key. It NEVER
+ * prompts, and never fails for WANT of a passphrase — the file store must work on
+ * every platform (macOS included) without the user setting, typing, or
+ * remembering one. (It can still throw if provisioning cannot write the key file
+ * at all; that is a disk/permissions failure, not a missing passphrase.) Provisioning
  * writes a 0600 key file (encryption-at-rest, same posture as an SSH key); set
  * AGENTS_SECRETS_PASSPHRASE to opt into an off-disk key.
  */

package/dist/lib/secrets/filestore.js

@@ -110,11 +110,13 @@ function readMachinePassphrase() {
  * the keyring is locked and no AGENTS_SECRETS_PASSPHRASE is set.
  *
  * Security model: this is encryption-at-rest with the key held in a 0600 file —
- * the same posture as an SSH private key, and identical to the common
- * "export AGENTS_SECRETS_PASSPHRASE=… in ~/.zshenv (chmod 600)" workaround. The
- * keyring (key in a daemon's locked memory) is stronger but is unavailable
- * without a graphical/unlocked session. For an off-disk key, set
- * AGENTS_SECRETS_PASSPHRASE (it always takes precedence) or unlock the keyring.
+ * the same posture as an SSH private key. It is NOT equivalent to the common
+ * "export AGENTS_SECRETS_PASSPHRASE=… in ~/.zshenv (chmod 600)" workaround, and
+ * is strictly safer: this file is read by the one process that needs it, while
+ * a shell-rc export is inherited by every process the login shell spawns and is
+ * readable from /proc/<pid>/environ by any same-user process (RUSH-1968; see
+ * rc-hygiene.ts). The keyring (key in a daemon's locked memory) is stronger
+ * still but is unavailable without a graphical/unlocked session.
  */
 function provisionMachinePassphrase() {
     const existing = readMachinePassphrase();
@@ -145,9 +147,11 @@ function provisionMachinePassphrase() {
  * Resolve the passphrase for the encrypted file store.
  *
  * Order: AGENTS_SECRETS_PASSPHRASE > previously-provisioned machine-local key >
- * a freshly auto-provisioned machine-local key. It NEVER prompts and NEVER
- * hard-fails — the file store must work on every platform (macOS included)
- * without the user setting, typing, or remembering a passphrase. Provisioning
+ * legacy co-located key > a freshly auto-provisioned machine-local key. It NEVER
+ * prompts, and never fails for WANT of a passphrase — the file store must work on
+ * every platform (macOS included) without the user setting, typing, or
+ * remembering one. (It can still throw if provisioning cannot write the key file
+ * at all; that is a disk/permissions failure, not a missing passphrase.) Provisioning
  * writes a 0600 key file (encryption-at-rest, same posture as an SSH key); set
  * AGENTS_SECRETS_PASSPHRASE to opt into an off-disk key.
  */

package/dist/lib/secrets/index.js

@@ -781,9 +781,23 @@ export function hasKeychainToken(item) {
         }, KEYCHAIN_SILENT_TIMEOUT_MS).status === 0;
     }
     const bin = getKeychainHelperPath();
-    return spawnKeychainHelper(bin, ['has', item, os.userInfo().username], {
+    const r = spawnKeychainHelper(bin, ['has', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    }, KEYCHAIN_SILENT_TIMEOUT_MS).status === 0;
+    }, KEYCHAIN_SILENT_TIMEOUT_MS);
+    // The helper exits 0 = present (incl. errSecInteractionNotAllowed — a locked or
+    // biometry-ACL'd item still EXISTS), 1 = genuinely absent. Any other outcome
+    // (bad args, helper failure, spawn error) means the keychain could not be
+    // reached — and a false "absent" silently disarms every destructive-write guard
+    // that calls this (see the docblock), so it MUST fail loud rather than answer
+    // "no" (RUSH-2235). Timeouts already throw inside spawnKeychainHelper.
+    if (r.status === 0)
+        return true;
+    if (r.status === 1)
+        return false;
+    const stderr = r.stderr?.toString().trim();
+    throw new Error(stderr ||
+        `keychain existence check for '${item}' failed (helper exit ${r.status ?? 'null'}` +
+            `${r.error ? `: ${r.error.message}` : ''}) — keychain unreachable, not a proven absence.`);
 }
 /**
  * The detector the raw-read storm guard consults, overridable so tests on any
@@ -1175,14 +1189,26 @@ export function deleteKeychainToken(item) {
     if (isWindows())
         return windowsBackend.delete(item);
     const bin = getKeychainHelperPath();
-    const deleted = spawnKeychainHelper(bin, ['delete', item, os.userInfo().username], {
+    const r = spawnKeychainHelper(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    }, KEYCHAIN_SILENT_TIMEOUT_MS).status === 0;
-    // A deleted item must fail its next read as plain "not found", not with a
-    // stale back-off error left over from a pre-delete cancel.
-    if (deleted)
+    }, KEYCHAIN_SILENT_TIMEOUT_MS);
+    // The helper exits 0 = an item was removed from at least one keychain, 1 =
+    // nothing to delete (genuinely absent). Any other outcome means the keychain
+    // could not be reached; like hasKeychainToken this must fail loud rather than
+    // report a false "nothing was there" (RUSH-2235) — a swallowed failure lets a
+    // rename/purge believe it cleared a name it did not.
+    if (r.status === 0) {
+        // A deleted item must fail its next read as plain "not found", not with a
+        // stale back-off error left over from a pre-delete cancel.
         clearKeychainReadBackoff(requested);
-    return deleted;
+        return true;
+    }
+    if (r.status === 1)
+        return false;
+    const stderr = r.stderr?.toString().trim();
+    throw new Error(stderr ||
+        `keychain delete for '${item}' failed (helper exit ${r.status ?? 'null'}` +
+            `${r.error ? `: ${r.error.message}` : ''}) — keychain unreachable, deletion unproven.`);
 }
 /**
  * True when the active keychain backend transparently routes reads/writes to

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

@@ -68,6 +68,16 @@ export interface ReapPlan {
  * not match the helper, or whose parent is no longer in the snapshot.
  */
 export declare function planKeychainReap(snapshots: KeychainProcessSnapshot[], now: number, prevCandidates: ReadonlyMap<number, StuckParentCandidate>): ReapPlan;
+/**
+ * Parse macOS `ps -o etime=` elapsed time into whole seconds.
+ *
+ * BSD `etime` renders as `[[dd-]hh:]mm:ss` (e.g. `05:03`, `01:02:03`,
+ * `14-04:10:52`). This is the portable keyword: `etimes` (raw seconds) is a
+ * GNU/Linux procps extension that macOS `ps` rejects with a non-zero exit, so
+ * the reaper — which only ever runs on darwin — must read `etime`.
+ * Returns null for an unparseable value so the caller drops the row.
+ */
+export declare function parseEtimeToSeconds(raw: string): number | null;
 /** Test seam: reset the persisted candidate state. */
 export declare function resetKeychainReaperCandidatesForTest(): void;
 /**

package/dist/lib/secrets/reaper.js

@@ -90,25 +90,47 @@ export function planKeychainReap(snapshots, now, prevCandidates) {
     }
     return { kill, nextCandidates };
 }
+/**
+ * Parse macOS `ps -o etime=` elapsed time into whole seconds.
+ *
+ * BSD `etime` renders as `[[dd-]hh:]mm:ss` (e.g. `05:03`, `01:02:03`,
+ * `14-04:10:52`). This is the portable keyword: `etimes` (raw seconds) is a
+ * GNU/Linux procps extension that macOS `ps` rejects with a non-zero exit, so
+ * the reaper — which only ever runs on darwin — must read `etime`.
+ * Returns null for an unparseable value so the caller drops the row.
+ */
+export function parseEtimeToSeconds(raw) {
+    const m = raw.match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
+    if (!m)
+        return null;
+    const days = m[1] ? parseInt(m[1], 10) : 0;
+    const hours = m[2] ? parseInt(m[2], 10) : 0;
+    const mins = parseInt(m[3], 10);
+    const secs = parseInt(m[4], 10);
+    if ([days, hours, mins, secs].some(isNaN))
+        return null;
+    return ((days * 24 + hours) * 60 + mins) * 60 + secs;
+}
 /**
  * Parse one `ps` output line.
  *
- * Expected format from `ps -ax -o pid=,ppid=,etimes=,command=`:
- *   "<pid> <ppid> <etimes> <command...>"
- * The command field is the remainder of the line and may contain spaces.
+ * Expected format from `ps -ax -o pid=,ppid=,etime=,command=`:
+ *   "<pid> <ppid> <etime> <command...>"
+ * where `<etime>` is BSD elapsed time (`[[dd-]hh:]mm:ss`). The command field is
+ * the remainder of the line and may contain spaces.
  */
 function parsePsLine(line) {
     const trimmed = line.trim();
     if (!trimmed)
         return null;
-    const m = trimmed.match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/);
+    const m = trimmed.match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
     if (!m)
         return null;
     const pid = parseInt(m[1], 10);
     const ppid = parseInt(m[2], 10);
-    const elapsedSec = parseInt(m[3], 10);
+    const elapsedSec = parseEtimeToSeconds(m[3]);
     const command = m[4];
-    if (isNaN(pid) || isNaN(ppid) || isNaN(elapsedSec))
+    if (isNaN(pid) || isNaN(ppid) || elapsedSec == null)
         return null;
     return { pid, ppid, elapsedSec, command };
 }
@@ -142,7 +164,7 @@ export function reapOrphanedKeychainProcesses() {
     }
     let out;
     try {
-        out = execFileSync('ps', ['-ax', '-o', 'pid=,ppid=,etimes=,command='], {
+        out = execFileSync('ps', ['-ax', '-o', 'pid=,ppid=,etime=,command='], {
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'ignore'],
         });
@@ -150,7 +172,7 @@ export function reapOrphanedKeychainProcesses() {
     catch (err) {
         return { reaped: 0, details: [`ps failed: ${err.message}`], plan: { kill: [], nextCandidates: new Map() } };
     }
-    const snapshots = [];
+    const rows = [];
     for (const line of out.split('\n')) {
         const parsed = parsePsLine(line);
         if (!parsed)
@@ -159,14 +181,27 @@ export function reapOrphanedKeychainProcesses() {
         // Exact path-match: the helper invocation's command line begins with the
         // absolute helper path, followed by a space and its arguments (or nothing).
         const isHelper = command === helperPath || command.startsWith(`${helperPath} `);
-        snapshots.push({
-            pid,
-            ppid,
-            elapsedSec,
-            startTime: captureProcessStartTime(pid),
-            isHelper,
-        });
+        rows.push({ pid, ppid, elapsedSec, isHelper, startTime: null });
+    }
+    const rowByPid = new Map(rows.map((r) => [r.pid, r]));
+    for (const row of rows) {
+        if (!row.isHelper)
+            continue;
+        row.startTime = captureProcessStartTime(row.pid);
+        if (row.ppid !== 1 && row.elapsedSec > STUCK_GRACE_SEC) {
+            const parent = rowByPid.get(row.ppid);
+            if (parent && parent.startTime === null) {
+                parent.startTime = captureProcessStartTime(row.ppid);
+            }
+        }
     }
+    const snapshots = rows.map((r) => ({
+        pid: r.pid,
+        ppid: r.ppid,
+        elapsedSec: r.elapsedSec,
+        startTime: r.startTime,
+        isHelper: r.isHelper,
+    }));
     const plan = planKeychainReap(snapshots, Date.now(), stuckParentCandidates);
     stuckParentCandidates = plan.nextCandidates;
     for (const pid of plan.kill) {

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

@@ -0,0 +1,27 @@
+/** The current variable for transport/sync passphrases. */
+export declare const SYNC_PASSPHRASE_ENV = "AGENTS_SYNC_PASSPHRASE";
+/** The file-store master key, honoured for sync only as a deprecated fallback. */
+export declare const LEGACY_PASSPHRASE_ENV = "AGENTS_SECRETS_PASSPHRASE";
+/** Reset the one-shot warning latches. Tests only — production never re-warns. */
+export declare function resetSyncPassphraseWarnings(): void;
+/** Where a resolved sync passphrase came from, so callers can report honestly. */
+export type SyncPassphraseSource = 'sync-env' | 'legacy-env' | null;
+export interface ResolvedSyncPassphrase {
+    value: string | null;
+    source: SyncPassphraseSource;
+}
+/**
+ * Read the transport passphrase from the environment, preferring the current
+ * variable and falling back to the deprecated one with a single warning.
+ * Returns `{ value: null }` when neither is set — the caller decides whether to
+ * prompt (TTY) or fail (headless). Never prompts, never throws.
+ */
+export declare function resolveSyncPassphraseFromEnv(): ResolvedSyncPassphrase;
+/**
+ * The one-shot reminder that an env-sourced passphrase is readable by other
+ * same-user processes. Separate from the deprecation notice above so a caller
+ * using the CURRENT variable still gets the readability warning exactly once.
+ */
+export declare function warnEnvPassphraseReadableOnce(): void;
+/** The message a headless caller shows when no passphrase is available. */
+export declare function missingSyncPassphraseMessage(): string;

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

@@ -0,0 +1,78 @@
+/**
+ * The passphrase that seals a bundle for TRANSPORT — `secrets push`/`pull` and
+ * the portable `export --to-file` / `import --from-file` envelope.
+ *
+ * This is deliberately a DIFFERENT secret from the file store's master key
+ * (`AGENTS_SECRETS_PASSPHRASE`, `filestore.ts:getPassphrase`). The two were one
+ * variable, and that overload is what put a master key into `~/.zshenv` on seven
+ * worker boxes (RUSH-1968): the file store stopped needing a passphrase once it
+ * auto-provisioned a machine-local key, but headless `push`/`pull` still hard-
+ * failed without one, so an operator exported the master key fleet-wide to make
+ * sync work — handing every same-user process the key to the whole store.
+ *
+ * Splitting them means a box that only needs headless sync sets
+ * `AGENTS_SYNC_PASSPHRASE` and never has the store's master key in its
+ * environment at all.
+ *
+ * Resolution order:
+ *   1. `AGENTS_SYNC_PASSPHRASE`        — the current name.
+ *   2. `AGENTS_SECRETS_PASSPHRASE`     — deprecated fallback, warns once.
+ *   3. (caller prompts, or fails)
+ *
+ * The fallback exists so already-scripted CI and release automation keep working
+ * across the upgrade; it is not a second supported spelling.
+ */
+import chalk from 'chalk';
+/** The current variable for transport/sync passphrases. */
+export const SYNC_PASSPHRASE_ENV = 'AGENTS_SYNC_PASSPHRASE';
+/** The file-store master key, honoured for sync only as a deprecated fallback. */
+export const LEGACY_PASSPHRASE_ENV = 'AGENTS_SECRETS_PASSPHRASE';
+/** Warn at most once per process: a `--all` push over many bundles must not
+ *  flood stderr with the same notice. */
+let deprecatedVarWarned = false;
+/** Same, for the "this came from an env var at all" readability notice. */
+let envPassphraseWarned = false;
+/** Reset the one-shot warning latches. Tests only — production never re-warns. */
+export function resetSyncPassphraseWarnings() {
+    deprecatedVarWarned = false;
+    envPassphraseWarned = false;
+}
+/**
+ * Read the transport passphrase from the environment, preferring the current
+ * variable and falling back to the deprecated one with a single warning.
+ * Returns `{ value: null }` when neither is set — the caller decides whether to
+ * prompt (TTY) or fail (headless). Never prompts, never throws.
+ */
+export function resolveSyncPassphraseFromEnv() {
+    const current = process.env[SYNC_PASSPHRASE_ENV];
+    if (current)
+        return { value: current, source: 'sync-env' };
+    const legacy = process.env[LEGACY_PASSPHRASE_ENV];
+    if (legacy) {
+        if (!deprecatedVarWarned) {
+            deprecatedVarWarned = true;
+            process.stderr.write(chalk.yellow(`warn: ${LEGACY_PASSPHRASE_ENV} is deprecated for sync — it is the file store's master key, ` +
+                `not a transport passphrase. Set ${SYNC_PASSPHRASE_ENV} instead; the old name still works ` +
+                'for now. Keeping the master key in the environment exposes the whole store to every ' +
+                'same-user process (RUSH-1968).\n'));
+        }
+        return { value: legacy, source: 'legacy-env' };
+    }
+    return { value: null, source: null };
+}
+/**
+ * The one-shot reminder that an env-sourced passphrase is readable by other
+ * same-user processes. Separate from the deprecation notice above so a caller
+ * using the CURRENT variable still gets the readability warning exactly once.
+ */
+export function warnEnvPassphraseReadableOnce() {
+    if (envPassphraseWarned)
+        return;
+    envPassphraseWarned = true;
+    process.stderr.write(chalk.yellow('warn: using a sync passphrase from the environment. Env vars are readable by other ' +
+        'same-user processes (/proc, ps, crash dumps, CI logs) — rotate after CI use.\n'));
+}
+/** The message a headless caller shows when no passphrase is available. */
+export function missingSyncPassphraseMessage() {
+    return `A sync passphrase is required. Run from a TTY, or set ${SYNC_PASSPHRASE_ENV}.`;
+}

package/dist/lib/session/recovery.d.ts

@@ -0,0 +1,37 @@
+import { type RotateCandidate } from '../rotate.js';
+import type { AgentId } from '../types.js';
+import type { SessionMeta } from './types.js';
+export type SessionRecoveryTarget = {
+    mode: 'native';
+    agent: AgentId;
+    version: string;
+    reason: string;
+} | {
+    mode: 'continue';
+    agent: AgentId;
+    version: string;
+    reason: string;
+};
+export declare class SessionRecoveryError extends Error {
+    constructor(message: string);
+}
+/** Canonical origin-device label for every recovery consumer. */
+export declare function sessionOriginDevice(session: Pick<SessionMeta, 'machine'>, self?: string): string;
+/** The peer that must execute recovery, or undefined when this is the origin. */
+export declare function sessionRecoveryPeer(session: Pick<SessionMeta, 'machine'>, selfCheck?: (host: string) => boolean): string | undefined;
+/** Whether an explicit placement names the session's origin device. */
+export declare function sessionRecoveryDestinationMatches(session: Pick<SessionMeta, 'machine'>, requestedHost: string, self?: string): boolean;
+/**
+ * Decide how a durable session resumes on the device that owns it.
+ *
+ * Native resume is legal only in the exact origin version's isolated home and
+ * only while that account is healthy. Every other successful path stays on the
+ * same harness and uses `/continue`, whose indexed transcript reader can reach
+ * retained version trash. No healthy same-harness account is a loud failure.
+ */
+export declare function resolveSessionRecoveryFromCandidates(session: SessionMeta, candidates: RotateCandidate[], supportsNative?: (agent: AgentId, version?: string) => boolean): SessionRecoveryTarget;
+export declare function resolveSessionRecovery(session: SessionMeta): Promise<SessionRecoveryTarget>;
+/** Stable self-command used by focus, resume, and attach. The owning device runs
+ * the recovery resolver above; callers must not native-resume another version's
+ * isolated home themselves. */
+export declare function sessionRecoveryRunArgs(session: Pick<SessionMeta, 'id'>): string[];