@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/lib/secrets/bundles.js

@@ -28,7 +28,7 @@ import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainTo
 import { fileStore } from './filestore.js';
 import { getVaultSession, vaultDeleteItem, vaultExists, vaultGetItems, vaultGetItem, vaultHasItem, vaultListItems, vaultSetItems, vaultSetItem, } from './vault.js';
 import { emit } from '../events.js';
-import { readMeta } from '../state.js';
+import { readMeta, getHelpersDir } from '../state.js';
 import { assertNameActiveInResourceProfile, filterNamesForActiveResourceProfile } from '../resource-profiles.js';
 import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, secretsHoldMs } from './agent.js';
 import { loadSession, deleteSession } from './session-store.js';
@@ -243,6 +243,44 @@ export function bundleExists(name) {
     validateBundleName(name);
     return itemStore(bundleBackend(name)).has(bundleMetaItem(name));
 }
+/**
+ * Thrown by `readBundle` for the one state `readBundleIfDecryptable` may treat
+ * as "present but permanently unreadable": file-store ciphertext on disk that
+ * will not decrypt with the passphrase in effect (lost/rotated key or a tampered
+ * store). It is deliberately narrow — a bundle that is merely *locked for this
+ * run* (headless macOS without `AGENTS_SECRETS_PASSPHRASE`, or a vault that is
+ * not logged in) is recoverable and must not be collapsed into this.
+ */
+export class BundleUndecryptableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BundleUndecryptableError';
+    }
+}
+/**
+ * Read a bundle, or return null when its metadata is present but genuinely
+ * cannot be decrypted — a lost or rotated file-store passphrase, or a tampered
+ * file store (signalled by `BundleUndecryptableError`).
+ *
+ * Deleting such a bundle is the only way out of that state, and deletion needs
+ * no plaintext, so it must not be gated behind a successful decrypt. Every other
+ * failure rethrows: a genuinely missing bundle ("not found"), and — critically —
+ * a bundle that is only *temporarily locked* for this run (headless macOS with no
+ * `AGENTS_SECRETS_PASSPHRASE`, or a not-logged-in vault). Collapsing that
+ * recoverable "set the env / log in" state into "unreadable, safe to delete"
+ * would let `secrets delete <name> --yes` silently destroy a perfectly healthy
+ * bundle from a cron/launchd run that merely forgot to export the passphrase.
+ */
+export function readBundleIfDecryptable(name) {
+    try {
+        return readBundle(name);
+    }
+    catch (err) {
+        if (err instanceof BundleUndecryptableError)
+            return null;
+        throw err;
+    }
+}
 export function readBundle(name) {
     validateBundleName(name);
     const backend = bundleBackend(name);
@@ -258,7 +296,7 @@ export function readBundle(name) {
         // A file-backed bundle whose metadata is on disk but fails to decrypt is a
         // wrong-passphrase error, not a missing bundle — surface that clearly.
         if (backend === 'file' && fileStore.has(bundleMetaItem(name))) {
-            throw new Error(`Bundle '${name}': failed to decrypt — wrong AGENTS_SECRETS_PASSPHRASE or tampered file store. (${err.message})`);
+            throw new BundleUndecryptableError(`Bundle '${name}': failed to decrypt — wrong AGENTS_SECRETS_PASSPHRASE or tampered file store. (${err.message})`);
         }
         if (vaultExists() && !getVaultSession().loggedIn) {
             throw new Error(`Synced secrets are locked. Run: agents login`);
@@ -429,18 +467,40 @@ function finishBundleWrite(bundle, opts) {
 }
 export function writeBundle(bundle, opts = {}) {
     const prepared = prepareBundleWrite(bundle);
-    // A `never` bundle's metadata is stored without the biometry ACL too, so
-    // `view` and the metadata half of a read resolve silently — the whole point
-    // of the tier. On an un-updated pinned helper this write fails loudly (the
-    // no-ACL command is missing) rather than silently landing an ACL'd item.
-    itemStore(prepared.backend).set(prepared.metadataItem, prepared.metadataJson, { noAcl: bundle.policy === 'never' });
+    // Bundle metadata (name, description, policy, var names + refs, and any
+    // non-sensitive `--value` literals) is stored WITHOUT the biometry ACL at
+    // EVERY tier. It is non-sensitive by contract — the real secret values live in
+    // separate agents-cli.secrets.* items that keep the bundle's policy ACL — so a
+    // no-ACL metadata item is what lets `secrets list` and crabbox's `agents
+    // devices list` enumerate bundles with no Touch ID prompt (RUSH-1759). On an
+    // un-updated pinned helper this write fails loudly (the no-ACL command is
+    // missing) rather than silently landing an ACL'd item.
+    itemStore(prepared.backend).set(prepared.metadataItem, prepared.metadataJson, { noAcl: true });
     finishBundleWrite(bundle, opts);
 }
 export function writeBundleWithItems(bundle, items, opts = {}) {
     const prepared = prepareBundleWrite(bundle);
-    const batch = new Map(items);
-    batch.set(prepared.metadataItem, prepared.metadataJson);
-    itemStore(prepared.backend).setBatch(batch, { noAcl: bundle.policy === 'never' });
+    const store = itemStore(prepared.backend);
+    if (prepared.backend === 'keychain') {
+        // Only the keychain backend has a biometry ACL. Secret VALUE items carry the
+        // bundle's policy ACL (`never` ⇒ no-ACL); the metadata item is ALWAYS no-ACL
+        // (see writeBundle). The two must NOT ride one batch flag — a single noAcl
+        // over both would either strip biometry off the real secrets or re-ACL the
+        // metadata. Write the values first, then the metadata last: bundle discovery
+        // keys on the metadata item's presence, so metadata-last means a partial
+        // write reads as "no bundle yet", never as a bundle with missing values.
+        if (items.size > 0) {
+            store.setBatch(new Map(items), { noAcl: bundle.policy === 'never' });
+        }
+        store.set(prepared.metadataItem, prepared.metadataJson, { noAcl: true });
+    }
+    else {
+        // file / vault: no ACL concept (noAcl is ignored), so one batched write is
+        // both correct and cheaper — e.g. a single age re-encrypt for the vault.
+        const batch = new Map(items);
+        batch.set(prepared.metadataItem, prepared.metadataJson);
+        store.setBatch(batch, { noAcl: bundle.policy === 'never' });
+    }
     finishBundleWrite(bundle, opts);
 }
 export function deleteBundle(name) {
@@ -503,6 +563,79 @@ function parseBundleMeta(nameHint, json, backend) {
     }
     return bundle;
 }
+// Sentinel marking the one-time RUSH-1759 metadata-ACL heal as done. Lives under
+// the regenerable helpers dir (same tree as the secrets-agent runtime state), so
+// a cache wipe just re-runs the heal — harmless, since it is idempotent.
+const METADATA_NOACL_SENTINEL = 'bundles-metadata-noacl-healed';
+function metadataNoAclSentinelPath() {
+    return path.join(getHelpersDir(), 'secrets-agent', METADATA_NOACL_SENTINEL);
+}
+function bundleMetadataAclHealed() {
+    try {
+        return fs.existsSync(metadataNoAclSentinelPath());
+    }
+    catch {
+        return false;
+    }
+}
+function markBundleMetadataAclHealed() {
+    try {
+        const file = metadataNoAclSentinelPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, '', 'utf8');
+    }
+    catch {
+        // Best effort — a missing sentinel just means the (idempotent) heal re-runs
+        // on the next broker-miss listing.
+    }
+}
+/**
+ * Re-write already-read keychain bundle metadata items WITHOUT the biometry ACL.
+ * `metaJsonByName` maps bundle name → the exact metadata JSON listBundles just
+ * batch-read, so writing it back only flips the ACL (via the helper's
+ * delete-then-add `set-no-acl`) — contents and updated_at are preserved and no
+ * extra keychain read is issued. Exported for tests. Returns the count healed.
+ */
+export function healKeychainBundleMetadata(metaJsonByName) {
+    let healed = 0;
+    for (const [name, json] of metaJsonByName) {
+        try {
+            // Cleartext meta-item name → hashed by keychainStore.set (#316) to the same
+            // service the read enumerated, so this overwrites the existing item in
+            // place, no-ACL. A per-item failure (e.g. a pinned helper without
+            // set-no-acl) must not abort the rest.
+            keychainStore.set(bundleMetaItem(name), json, { noAcl: true });
+            healed++;
+        }
+        catch {
+            /* keep healing the remaining items */
+        }
+    }
+    return healed;
+}
+/**
+ * One-time driver around healKeychainBundleMetadata (RUSH-1759). macOS + real
+ * keychain only — libsecret/CredMan have no biometry ACL to shed, and a test
+ * backend has no real keychain — and gated by a sentinel so it runs at most
+ * once. Best-effort: a heal failure never breaks bundle listing.
+ */
+function healKeychainBundleMetadataAclOnce(metaJsonByName) {
+    if (metaJsonByName.size === 0)
+        return;
+    if (process.platform !== 'darwin')
+        return;
+    if (isKeychainBackendOverridden())
+        return;
+    if (bundleMetadataAclHealed())
+        return;
+    try {
+        if (healKeychainBundleMetadata(metaJsonByName) > 0)
+            markBundleMetadataAclHealed();
+    }
+    catch {
+        /* never let a heal failure break `secrets list` */
+    }
+}
 export function listBundles() {
     const out = [];
     // Keychain-backed bundles: batch all metadata reads behind ONE Touch ID
@@ -558,6 +691,7 @@ export function listBundles() {
             else {
                 const fetched = getKeychainTokens(keychainServices);
                 const keychainBundles = [];
+                const metaJsonByName = new Map();
                 for (const service of keychainServices) {
                     const json = fetched.get(service);
                     if (json === undefined)
@@ -566,8 +700,10 @@ export function listBundles() {
                         ? service.slice(BUNDLE_META_PREFIX.length)
                         : undefined;
                     const bundle = parseBundleMeta(nameHint, json, 'keychain');
-                    if (bundle)
+                    if (bundle) {
                         keychainBundles.push(bundle);
+                        metaJsonByName.set(bundle.name, json);
+                    }
                 }
                 for (const bundle of keychainBundles)
                     out.push(bundle);
@@ -578,6 +714,13 @@ export function listBundles() {
                 if (useAgent && keychainBundles.length > 0) {
                     agentAutoLoadMetaSync(nameSetHash, keychainBundles, secretsHoldMs());
                 }
+                // One-time RUSH-1759 heal: bundles written before the metadata-no-ACL
+                // change carry an ACL'd metadata item, so this fresh read (a broker miss)
+                // popped Touch ID just to enumerate them. Re-home each metadata item
+                // no-ACL now — reusing the JSON we just read, so the heal adds no extra
+                // prompt — and every later enumeration is silent. Runs at most once (a
+                // sentinel under the regenerable helpers dir).
+                healKeychainBundleMetadataAclOnce(metaJsonByName);
             }
         }
     }
@@ -977,15 +1120,32 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             return filtered;
         }
     }
-    // Only keychain-backed bundles can pop a Touch ID prompt and are the only ones
-    // the broker ever holds. A file-backed bundle resolves via passphrase with no
-    // prompt, so agentOnly must never block it — the broker never holds file
-    // bundles, so the throw would fire unconditionally and break a legitimate read.
+    // The headless guard exists only to keep a Touch ID sheet off the interactive
+    // user's screen — so it must block ONLY reads that can actually raise one.
+    // A file-backed bundle resolves via passphrase with no prompt (handled below,
+    // never held by the broker). A `never`/no-ACL keychain bundle is written
+    // WITHOUT the biometry access control at every tier (see writeBundle), so its
+    // reads are fully silent (no Touch ID, no broker) — exactly like a file
+    // bundle, and exactly the "automation-only" tier a headless daemon reads
+    // (daemon.ts:readDaemonClaudeOAuthToken). Learning the policy here is itself
+    // prompt-less: metadata items are written no-ACL at every tier, so readBundle
+    // reads them silently. An unreadable metadata read is treated as prompt-risky
+    // (throw) — the safe default.
     if (opts.agentOnly && backend === 'keychain') {
-        throw new Error(`Secrets bundle '${name}' is not unlocked in the secrets agent, and this is a ` +
-            `headless/background process that must not raise a Touch ID prompt on the ` +
-            `interactive user's screen. Run 'agents secrets unlock ${name}' in a terminal ` +
-            `first, or set AGENTS_SECRETS_NO_PROMPT=0 to force an interactive prompt.`);
+        let noAclBundle = false;
+        try {
+            noAclBundle = bundlePolicy(readBundle(name)) === 'never';
+        }
+        catch {
+            noAclBundle = false;
+        }
+        if (!noAclBundle) {
+            throw new Error(`Secrets bundle '${name}' is not unlocked in the secrets agent, and this is a ` +
+                `headless/background process that must not raise a Touch ID prompt on the ` +
+                `interactive user's screen. Run 'agents secrets unlock ${name}' in a terminal ` +
+                `first, or set AGENTS_SECRETS_NO_PROMPT=0 to force an interactive prompt.`);
+        }
+        // never/no-ACL ⇒ fall through to the prompt-less keychain read below.
     }
     if (backend === 'file')
         assertFileBackendUsable(name);

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

@@ -187,7 +187,21 @@ export declare function rekeyStatus(): {
      * count is then meaningless. Only probeable once the key record exists. */
     enumerationOk: boolean;
 };
-/** Check if a keychain/keyring item exists. Never prompts for biometry. */
+/**
+ * Check if a keychain/keyring item exists. Never prompts for biometry.
+ *
+ * Throws when the item cannot be reached — on macOS, when the signed helper is
+ * unavailable. That is deliberate: this primitive gates destructive writes as
+ * well as reads. Through `bundleExists()` it guards the `--force` overwrite
+ * checks in `agents secrets create` (`../../commands/secrets.ts`), the
+ * bundle-rename purge (`./bundles.ts`), the pull-rollback bookkeeping
+ * (`./sync.ts`), and the reuse-never-overwrite rule for `R2_SYNC_ENC_KEY`
+ * (`../session/sync/provision.ts`). A false "absent" silently disarms every one
+ * of them, so an unreachable keychain must fail loudly rather than answer "no".
+ *
+ * Tests needing this path without a helper install a backend via
+ * `setKeychainBackendForTest()`, which short-circuits on the next line.
+ */
 export declare function hasKeychainToken(item: string): boolean;
 /**
  * Retrieve a secret value from the keychain/keyring. Throws if not found.

package/dist/lib/secrets/index.js

@@ -481,8 +481,12 @@ export function computeRekeyPlan(services, values, key) {
         try {
             const parsed = JSON.parse(value);
             if (parsed && typeof parsed === 'object') {
-                const tier = parsed.tier;
-                noAcl = tier === 'none' || tier === 'never';
+                // Bundle metadata is non-sensitive by contract and stored no-ACL at
+                // EVERY tier (matches writeBundle in bundles.ts), so `secrets list` /
+                // crabbox's `agents devices list` enumerate bundles with no Touch ID
+                // (RUSH-1759). Re-home metadata no-ACL regardless of the bundle's policy;
+                // the real secret values (second loop) still carry their per-bundle ACL.
+                noAcl = true;
                 payload = JSON.stringify({ ...parsed, name });
             }
         }
@@ -669,7 +673,21 @@ export function rekeyStatus() {
         enumerationOk,
     };
 }
-/** Check if a keychain/keyring item exists. Never prompts for biometry. */
+/**
+ * Check if a keychain/keyring item exists. Never prompts for biometry.
+ *
+ * Throws when the item cannot be reached — on macOS, when the signed helper is
+ * unavailable. That is deliberate: this primitive gates destructive writes as
+ * well as reads. Through `bundleExists()` it guards the `--force` overwrite
+ * checks in `agents secrets create` (`../../commands/secrets.ts`), the
+ * bundle-rename purge (`./bundles.ts`), the pull-rollback bookkeeping
+ * (`./sync.ts`), and the reuse-never-overwrite rule for `R2_SYNC_ENC_KEY`
+ * (`../session/sync/provision.ts`). A false "absent" silently disarms every one
+ * of them, so an unreachable keychain must fail loudly rather than answer "no".
+ *
+ * Tests needing this path without a helper install a backend via
+ * `setKeychainBackendForTest()`, which short-circuits on the next line.
+ */
 export function hasKeychainToken(item) {
     item = prepareServiceName(item);
     if (backend)

package/dist/lib/secrets/rc-hygiene.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Detect credentials exported from shell rc files.
+ *
+ * A secret exported from `~/.zshenv`, `~/.zshrc`, `~/.bashrc`, `~/.profile`, …
+ * is inherited by every process the login shell spawns and is readable from
+ * `/proc/<pid>/environ` by any same-user process — the master passphrase leak
+ * behind RUSH-1968. `.zshenv` in particular is sourced by *every* zsh
+ * invocation, including non-interactive `ssh host 'cmd'`, so the value lands in
+ * the environment of essentially everything the box runs.
+ *
+ * The keychain-backed store (`agents secrets`) is the sanctioned home for
+ * credentials; the file-store master passphrase belongs in the off-env 0600 key
+ * file (`~/.agents/.secrets-key/passphrase`), never a shell rc export.
+ *
+ * This scanner powers a warn-level advisory in `agents doctor`. It reads only
+ * the exported variable *name* and its line number — never the value — so a
+ * finding can be printed, logged, or shipped without leaking the secret.
+ */
+/** Shell rc files sourced at login/startup, in the order a report lists them. */
+export declare const RC_FILENAMES: readonly [".zshenv", ".zprofile", ".zshrc", ".zlogin", ".bash_profile", ".bash_login", ".bashrc", ".profile", ".kshrc"];
+/**
+ * A single credential-shaped export found in an rc file. Carries the variable
+ * NAME and location only — the value is never captured.
+ */
+export interface RcSecretFinding {
+    /** Basename of the rc file, e.g. `.zshenv`. */
+    file: string;
+    /** 1-based line number of the export. */
+    line: number;
+    /** The exported variable name (e.g. `AGENTS_SECRETS_PASSPHRASE`). Never the value. */
+    name: string;
+    /** The file-store master passphrase gets called out separately — it is the highest-severity case. */
+    isMasterPassphrase: boolean;
+}
+/** True if a variable name looks like it holds a credential value. */
+export declare function isCredentialName(name: string): boolean;
+/**
+ * Scan one rc file's contents for credential-shaped exports. Pure — takes the
+ * text, returns findings (names + line numbers only, never values). A trailing
+ * `# comment` is stripped before matching so a commented-out export is ignored;
+ * the variable name always precedes any inline `#`, so stripping never loses it.
+ */
+export declare function scanRcExports(basename: string, content: string): RcSecretFinding[];
+/**
+ * Scan the current user's shell rc files. Reads each file that exists under
+ * `homeDir` (default `os.homedir()`) and aggregates the findings. Missing or
+ * unreadable files are skipped silently — an advisory, not a hard requirement.
+ */
+export declare function scanUserRcFiles(homeDir?: string): RcSecretFinding[];
+/**
+ * Build the advisory lines for `agents doctor` from a set of findings. Returns
+ * `[]` when there is nothing to report. The first line is the headline; the
+ * rest are indented detail. Names only — never values.
+ */
+export declare function rcSecretWarningLines(findings: RcSecretFinding[]): string[];

package/dist/lib/secrets/rc-hygiene.js

@@ -0,0 +1,154 @@
+/**
+ * Detect credentials exported from shell rc files.
+ *
+ * A secret exported from `~/.zshenv`, `~/.zshrc`, `~/.bashrc`, `~/.profile`, …
+ * is inherited by every process the login shell spawns and is readable from
+ * `/proc/<pid>/environ` by any same-user process — the master passphrase leak
+ * behind RUSH-1968. `.zshenv` in particular is sourced by *every* zsh
+ * invocation, including non-interactive `ssh host 'cmd'`, so the value lands in
+ * the environment of essentially everything the box runs.
+ *
+ * The keychain-backed store (`agents secrets`) is the sanctioned home for
+ * credentials; the file-store master passphrase belongs in the off-env 0600 key
+ * file (`~/.agents/.secrets-key/passphrase`), never a shell rc export.
+ *
+ * This scanner powers a warn-level advisory in `agents doctor`. It reads only
+ * the exported variable *name* and its line number — never the value — so a
+ * finding can be printed, logged, or shipped without leaking the secret.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/** Shell rc files sourced at login/startup, in the order a report lists them. */
+export const RC_FILENAMES = [
+    '.zshenv',
+    '.zprofile',
+    '.zshrc',
+    '.zlogin',
+    '.bash_profile',
+    '.bash_login',
+    '.bashrc',
+    '.profile',
+    '.kshrc',
+];
+/** The file-store master key. Its own resolution prefers an off-env 0600 file, so
+ *  a shell-rc export is always wrong once the store exists (RUSH-1968). */
+const MASTER_PASSPHRASE = 'AGENTS_SECRETS_PASSPHRASE';
+/**
+ * Last `_`-delimited segment values that mark a variable as credential-shaped.
+ * Matched against the FINAL segment (segment equality, not substring) so
+ * `X_API_KEY` fires on `KEY` while `SOME_KEY_PATH` (ends `PATH`) and `MONKEY`
+ * (single segment, not equal to `KEY`) do not.
+ */
+const CREDENTIAL_SEGMENTS = new Set([
+    'PASSPHRASE',
+    'PASSWORD',
+    'PASSWD',
+    'SECRET',
+    'SECRETS',
+    'TOKEN',
+    'KEY',
+    'APIKEY',
+    'PAT',
+    'CREDENTIAL',
+    'CREDENTIALS',
+]);
+/**
+ * Final segments that look credential-shaped but name a file path, socket, or
+ * config knob rather than a secret value — excluded to cut false positives.
+ * Applied to the whole name's final segment before the credential check.
+ */
+const BENIGN_FINAL_SEGMENTS = new Set([
+    'PATH',
+    'FILE',
+    'DIR',
+    'SOCK',
+    'SOCKET',
+    'ID',
+    'NAME',
+    'PARALLELISM', // TOKENIZERS_PARALLELISM and friends
+]);
+/** True if a variable name looks like it holds a credential value. */
+export function isCredentialName(name) {
+    if (name === MASTER_PASSPHRASE)
+        return true;
+    const segments = name.toUpperCase().split('_');
+    const last = segments[segments.length - 1];
+    if (BENIGN_FINAL_SEGMENTS.has(last))
+        return false;
+    return CREDENTIAL_SEGMENTS.has(last);
+}
+// Matches an env assignment that puts a value in the environment:
+//   export NAME=...            (sh/bash/zsh)
+//   typeset -x NAME=... / declare -x NAME=...   (bash/zsh export-attribute form)
+const EXPORT_RE = /^\s*(?:export\s+|(?:typeset|declare)\s+-[A-Za-z]*x[A-Za-z]*\s+)([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/**
+ * Scan one rc file's contents for credential-shaped exports. Pure — takes the
+ * text, returns findings (names + line numbers only, never values). A trailing
+ * `# comment` is stripped before matching so a commented-out export is ignored;
+ * the variable name always precedes any inline `#`, so stripping never loses it.
+ */
+export function scanRcExports(basename, content) {
+    const out = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const code = lines[i].replace(/#.*$/, '');
+        const m = EXPORT_RE.exec(code);
+        if (!m)
+            continue;
+        const name = m[1];
+        if (!isCredentialName(name))
+            continue;
+        out.push({
+            file: basename,
+            line: i + 1,
+            name,
+            isMasterPassphrase: name === MASTER_PASSPHRASE,
+        });
+    }
+    return out;
+}
+/**
+ * Scan the current user's shell rc files. Reads each file that exists under
+ * `homeDir` (default `os.homedir()`) and aggregates the findings. Missing or
+ * unreadable files are skipped silently — an advisory, not a hard requirement.
+ */
+export function scanUserRcFiles(homeDir = os.homedir()) {
+    const out = [];
+    for (const name of RC_FILENAMES) {
+        const fp = path.join(homeDir, name);
+        let content;
+        try {
+            content = fs.readFileSync(fp, 'utf8');
+        }
+        catch {
+            continue; // absent or unreadable — nothing to report
+        }
+        out.push(...scanRcExports(name, content));
+    }
+    return out;
+}
+/**
+ * Build the advisory lines for `agents doctor` from a set of findings. Returns
+ * `[]` when there is nothing to report. The first line is the headline; the
+ * rest are indented detail. Names only — never values.
+ */
+export function rcSecretWarningLines(findings) {
+    if (findings.length === 0)
+        return [];
+    const lines = [];
+    const master = findings.filter((f) => f.isMasterPassphrase);
+    const others = findings.filter((f) => !f.isMasterPassphrase);
+    const total = findings.length;
+    lines.push(`${total} credential-shaped export${total === 1 ? '' : 's'} found in shell rc files — ` +
+        `readable from /proc/<pid>/environ by any same-user process.`);
+    for (const f of master) {
+        lines.push(`${f.file}:${f.line} ${f.name} — the file-store master key. Move it off-env to ` +
+            `~/.agents/.secrets-key/passphrase (chmod 600) and delete the export.`);
+    }
+    for (const f of others) {
+        lines.push(`${f.file}:${f.line} ${f.name} — move to \`agents secrets\` and inject via \`agents secrets exec\`.`);
+    }
+    lines.push('Rule: no credentials in env vars or shell config. Use the keychain-backed store.');
+    return lines;
+}

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

@@ -34,11 +34,14 @@ import { type SshExecResult } from '../ssh-exec.js';
  */
 export declare function isDangerousRemoteEnvKey(name: string): boolean;
 /**
- * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
- * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
- * treats the value as a raw ssh target and validates it against injection.
+ * Resolve a `--host` 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 --host` 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.
  */
-export declare function resolveSshTarget(nameOrAlias: string): Promise<string>;
+export declare function resolveHostSshTarget(nameOrAlias: string): Promise<string>;
 /**
  * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
  * list. Both flags compose; either alone works. Empty when neither is set.

package/dist/lib/secrets/remote.js

@@ -59,11 +59,14 @@ function osForTarget(target, lookupName) {
     return byName ?? resolveRemoteOsSync(target.split('@').pop() ?? target);
 }
 /**
- * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
- * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
- * treats the value as a raw ssh target and validates it against injection.
+ * Resolve a `--host` 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 --host` 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.
  */
-export async function resolveSshTarget(nameOrAlias) {
+export async function resolveHostSshTarget(nameOrAlias) {
     const host = await resolveHost(nameOrAlias);
     if (host)
         return sshTargetFor(host);

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

@@ -0,0 +1,21 @@
+/**
+ * The argv tokens for the synchronous secrets-broker clients: the tokens
+ * `agentGetSync`/`agentReachableSync`/`agentEvictSync` spawn, and the tokens
+ * `index.ts` dispatches on before commander.
+ *
+ * This is a LEAF module — it imports nothing, so the CLI entrypoint can bind
+ * these statically without dragging the secrets graph (and its `state.js` /
+ * `install-helper.js` / `session-store.js` imports) into every invocation. That
+ * is the whole reason the file exists: with the tokens in `agent.ts`, `index.ts`
+ * had to repeat them as string literals, and the two could silently drift —
+ * a drift with no visible failure mode, because the CLI answers "unknown
+ * command", the client reads the non-zero exit as "broker down", and every
+ * secret read falls back to a Touch ID prompt. Exactly the bug this subsystem
+ * was fixed for. Sharing one binding makes that divergence a type error rather
+ * than something a test has to notice.
+ *
+ * Same leaf discipline, and same motivation, as `lib/cli-entry.ts`.
+ */
+export declare const SYNC_GET_CMD = "__secrets-get";
+export declare const SYNC_PING_CMD = "__secrets-ping";
+export declare const SYNC_LOCK_CMD = "__secrets-lock";

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

@@ -0,0 +1,21 @@
+/**
+ * The argv tokens for the synchronous secrets-broker clients: the tokens
+ * `agentGetSync`/`agentReachableSync`/`agentEvictSync` spawn, and the tokens
+ * `index.ts` dispatches on before commander.
+ *
+ * This is a LEAF module — it imports nothing, so the CLI entrypoint can bind
+ * these statically without dragging the secrets graph (and its `state.js` /
+ * `install-helper.js` / `session-store.js` imports) into every invocation. That
+ * is the whole reason the file exists: with the tokens in `agent.ts`, `index.ts`
+ * had to repeat them as string literals, and the two could silently drift —
+ * a drift with no visible failure mode, because the CLI answers "unknown
+ * command", the client reads the non-zero exit as "broker down", and every
+ * secret read falls back to a Touch ID prompt. Exactly the bug this subsystem
+ * was fixed for. Sharing one binding makes that divergence a type error rather
+ * than something a test has to notice.
+ *
+ * Same leaf discipline, and same motivation, as `lib/cli-entry.ts`.
+ */
+export const SYNC_GET_CMD = '__secrets-get';
+export const SYNC_PING_CMD = '__secrets-ping';
+export const SYNC_LOCK_CMD = '__secrets-lock';