@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/secrets-client.js

@@ -1,86 +1,12 @@
-/**
- * secrets-client.ts — the ONE process client through which agents-cli talks to
- * the standalone `secrets` CLI (PHNX-3989).
- *
- * This is the agents-owned half of the secrets extraction: a bounded
- * request/response client over the standalone executable's private consumer
- * pipe. It carries NO storage, provider, or broker implementation — every
- * operation is resolved by spawning `secrets __serve` and exchanging one JSON
- * message over inherited pipes (delta-spec RPC-1). The engine lives entirely in
- * the standalone package; agents-cli never rebundles it (DIST-1), so there is
- * deliberately NO fallback to the in-repo `cli/src/lib/secrets/` engine — a
- * missing executable fails loud with install guidance.
- *
- * Transport (matches secrets-cli/src/protocol-server.ts `runProtocolServer`):
- *   - the child reads the request JSON from fd 3 (to EOF) and writes the
- *     response JSON to fd 4; nothing is ever written to the child's stdout.
- *   - async: `spawn` with stdio ['ignore','ignore','inherit','pipe','pipe'];
- *     write+end child.stdio[3], read child.stdio[4] to EOF.
- *   - sync: `spawnSync` only wires stdio 0-2 portably (Bun drops numbered fds
- *     3+), so the fd 3/4 wiring is done in a POSIX shell: the request rides
- *     `spawnSync`'s STDIN — a real pipe/socketpair on every runtime — which the
- *     shell dups onto fd 3 (`3<&0`), and fd 4 is redirected onto the child's
- *     stdout (`4>&1`), which `spawnSync` captures natively. Both fds are then the
- *     SAME anonymous pipe/socketpair the async path hands the standalone, which
- *     is load-bearing: the standalone wraps fd 3 in a `net.Socket`, and a Socket
- *     over a NAMED FIFO reads the request but never fires EOF on macOS, so the
- *     older FIFO wiring hung the read loop for the full timeout. Bounded to
- *     `SYNC_SERVE_TIMEOUT_MS` (30s — sized for a cold Node boot of the
- *     standalone on a loaded box, see the constant) so a broken standalone
- *     fails before the server's 60s deadline. POSIX only; Windows fails loud
- *     pointing at the async path.
- *
- * State root (MIG-1): the standalone selects its state root from `SECRETS_HOME`.
- * agents-cli points it at the user agents dir (`~/.agents`) by default so the
- * user's existing stores are adopted in place — no copy, no re-encryption. An
- * explicit `SECRETS_HOME` in the environment wins (test isolation, power users),
- * matching the standalone's own `state.ts` precedence.
- *
- * Policy (CTX-1): agents-cli passes its harness name as the opaque `scope` and,
- * when a request must be bounded, a resource-profile-filtered `allowedBundles`
- * set. Computing that policy stays in agents-cli (the caller supplies `context`);
- * this client only forwards it.
- *
- * The typed shapes are imported `type`-only from `./secrets-types.js`, a pure
- * re-declaration of the standalone's wire types (no runtime code, nothing in
- * the npm tarball beyond the erased type import) — this repo's own in-process
- * engine (`cli/src/lib/secrets/**`) is gone (PHNX-3989 Track D); the standalone
- * `@phnx-labs/secrets-cli` package is the only implementation.
- */
 import { spawn, spawnSync } from 'node:child_process';
 import { findInPath } from './agent-spec/agents.js';
 import { SECRETS_CLI_INSTALL_HINT } from './secrets-cli.js';
 import { getUserAgentsDir } from './state.js';
-/**
- * Wire contract, mirrored from `secrets-cli/src/protocol.ts`. Both sides MUST
- * agree byte-for-byte; this is the shared schema of the seam, the one thing an
- * independent client legitimately re-declares rather than imports.
- */
 export const PROTOCOL_VERSION = 1;
 const MAX_PROTOCOL_BYTES = 8 * 1024 * 1024;
-/** Just over the server's own 60s deadline, so the server times out first. */
 const SERVE_TIMEOUT_MS = 65_000;
-/**
- * The synchronous path serves the surfaces that resolve secrets before they can
- * continue — `agents view`, the account-catalog rows, and the account listing and
- * setup-token read on the `agents run` launch path. Those must never hang for the
- * standalone's own 60s deadline (the exact hang PHNX-3989 hit when the child ran
- * under Bun), so the sync serve carries a hard bound below it instead of the
- * async path's 65s. The bound covers a COLD PROCESS, not just the operation: every
- * request spawns `secrets __serve` afresh, so it pays a Node boot plus the
- * standalone's module load before the tens-of-milliseconds op runs: ~0.3s on a
- * quiet box, 0.4–2.6s and occasionally more on a desktop at load average ~100
- * (measured 2026-09-12), where the previous 3s bound turned load into a failed
- * launch (`secrets request failed: spawnSync sh ETIMEDOUT` from `agents run`).
- * 30s absorbs that boot under load and still fails a broken or wedged standalone
- * well before its 60s self-deadline. It is NOT a fallback to the embedded engine
- * (DIST-1); the standalone stays the only implementation. Exported so the
- * real-standalone test can assert a round-trip beats the bound.
- */
 export const SYNC_SERVE_TIMEOUT_MS = 30_000;
-/** Test seam: a hang test plants a never-answering standalone and must not wait 30s. */
 let syncServeTimeoutMs = SYNC_SERVE_TIMEOUT_MS;
-/** Serialize `Map`s the way the server's `decodeWire` expects to receive them. */
 function encodeWire(value) {
     if (value instanceof Map) {
         return { $map: [...value.entries()].map(([key, item]) => [key, encodeWire(item)]) };
@@ -92,7 +18,6 @@ function encodeWire(value) {
     }
     return value === undefined ? null : value;
 }
-/** Reconstruct `Map`s from the server's `encodeWire`'d reply. */
 function decodeWire(value) {
     if (Array.isArray(value))
         return value.map(decodeWire);
@@ -108,7 +33,6 @@ function decodeWire(value) {
     }
     return value;
 }
-/** Carries the server's `{code, message}`, or a client-side transport code. */
 export class SecretsClientError extends Error {
     code;
     constructor(code, message) {
@@ -116,28 +40,13 @@ export class SecretsClientError extends Error {
         this.code = code;
         this.name = 'SecretsClientError';
     }
-    /**
-     * Serialize to a plain `{code, message}`. A consumer that folds a failure into
-     * a structure it later `JSON.stringify`s (a teammate's meta.json, a failure
-     * record, a spawn env) must never make the serializer chase this Error's
-     * internal references and throw `Converting circular structure to JSON`
-     * mid-launch — the value here is the two fields a caller actually needs.
-     */
     toJSON() {
         return { code: this.code, message: this.message };
     }
 }
-/** True when `error` is a {@link SecretsClientError}, optionally with the given code. */
 export function isSecretsClientError(error, code) {
     return error instanceof SecretsClientError && (code === undefined || error.code === code);
 }
-/**
- * Client-side TRANSPORT codes — the standalone could not be reached or spoke a
- * broken protocol. These are the ONLY errors a "degrade when the standalone is
- * unavailable" consumer may swallow: a code from the standalone's own reply
- * (`NOT_FOUND`, `LOCKED`, `WRONG_BACKEND`, `OPERATION_FAILED`, `ACCESS_DENIED`, …)
- * is a real answer and must surface, never be hidden as "unavailable".
- */
 const SECRETS_TRANSPORT_CODES = new Set([
     'SECRETS_BIN_MISSING',
     'TIMEOUT',
@@ -148,41 +57,22 @@ const SECRETS_TRANSPORT_CODES = new Set([
     'RESPONSE_TOO_LARGE',
     'IO_ERROR',
 ]);
-/** True when `error` is a {@link SecretsClientError} from the transport itself (the
- * standalone was unreachable/unusable), not a data error it answered with. */
+// Only transport failures may degrade to unavailable; policy and data errors remain authoritative.
 export function isSecretsTransportError(error) {
     return error instanceof SecretsClientError && SECRETS_TRANSPORT_CODES.has(error.code);
 }
-// --- item naming (the shared identifier scheme of the seam) ---------------
-//
-// Raw item identifiers are part of the wire contract, mapped 1:1 across the
-// cutover (delta-spec MIG-1): the standalone stores a bundle's per-key value at
-// `agents-cli.secrets.<bundle>.<KEY>` and a profile provider token at
-// `agents-cli.<provider>.token`, and a bundle var that reads `keychain:<KEY>`
-// refers to the former. agents-cli derives these names whenever it seeds or
-// reads a raw item (account bundles, profile tokens, the reserved `auth`
-// bundle), so they are declared once here beside the protocol schema rather
-// than re-derived per consumer.
 const SERVICE_PREFIX = 'agents-cli';
 const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
-/** The raw item holding one bundle key's value. */
 export function secretsKeychainItem(bundle, key) {
     return `${SECRETS_ITEM_PREFIX}${bundle}.${key}`;
 }
-/** The raw item holding a profile provider's token (`agents-cli.<provider>.token`). */
 export function profileKeychainItem(provider) {
     return `${SERVICE_PREFIX}.${provider}.token`;
 }
-/** The bundle-var form that points a key at its own raw item. */
 export function keychainRef(key) {
     return `keychain:${key}`;
 }
 const REF_PATTERN = /^(keychain|env|file|exec):(.+)$/s;
-/**
- * Parse a bundle value into either a literal string or a typed secret ref. A
- * `{ value }` object is an escaped literal (a URL that happens to start with a
- * ref prefix is never misread as a reference).
- */
 export function parseBundleValue(raw) {
     if (typeof raw === 'object' && raw !== null && typeof raw.value === 'string') {
         return { literal: raw.value };
@@ -195,21 +85,8 @@ export function parseBundleValue(raw) {
         return { literal: raw };
     return { ref: { provider: match[1], value: match[2] } };
 }
-// --- executable resolution -------------------------------------------------
 let cachedBin;
-/**
- * Resolve the standalone `secrets` executable: `$SECRETS_BIN` if set, else the
- * `secrets` command on PATH — resolved with `findInPath`, which skips agents-cli's
- * own shims dir. That skip is load-bearing, not tidiness: before PHNX-3989 the
- * shims dir carried a `secrets` command shim that `exec`s `agents secrets`, it
- * sits FIRST on PATH, and it survives an in-place upgrade (its baked entrypoint
- * still exists). A plain `which secrets` returned that shim, so `agents secrets`
- * → shim → `agents secrets` → … spawned an unbounded process chain on every box
- * upgraded from 1.22.84 (the whole fleet, via R5 auto-update). A `secrets` inside
- * our shims dir can never be the standalone, so it is not a candidate at all.
- * Cached for the process. A miss throws with install guidance — there is NO
- * fallback to the embedded engine (DIST-1).
- */
+// Resolution skips the legacy agents shim to avoid recursive secrets passthrough.
 export function resolveSecretsBin() {
     if (cachedBin)
         return cachedBin;
@@ -223,34 +100,11 @@ export function resolveSecretsBin() {
     cachedBin = resolved;
     return resolved;
 }
-/**
- * How to invoke the resolved binary. A `.js`/`.mjs`/`.cjs` entrypoint (a dev
- * build, or `$SECRETS_BIN` pointing at `dist/index.js`) is run through this
- * process's Node so it works without an executable bit and on Windows; an
- * installed `secrets` shim/binary is spawned directly. Exported so a caller
- * that needs to run an interactive standalone verb directly (e.g. `secrets
- * migrate`, which isn't in this client's op table) can build the same argv.
- */
 export function invocation(bin) {
     if (/\.[mc]?js$/.test(bin))
         return { command: process.execPath, prefix: [bin] };
     return { command: bin, prefix: [] };
 }
-/**
- * Spawn env for the child, applied to a base env (defaults to `process.env`):
- *
- *  - `SECRETS_HOME` defaults to the user agents dir so the standalone adopts the
- *    existing stores in place (MIG-1); an explicit value in the base env wins.
- *  - The standalone renamed every `AGENTS_SECRETS_*` knob to `SECRETS_*`, so a
- *    caller env still carrying the old `AGENTS_SECRETS_PASSPHRASE` (the name
- *    agents-cli's own engine reads — filestore/linux/windows) would be invisible
- *    to `secrets`, which reads only `SECRETS_PASSPHRASE`. Forward it so the child
- *    can decrypt the very file store agents-cli wrote, rather than silently
- *    provisioning a fresh machine-local key. An explicit `SECRETS_PASSPHRASE`
- *    wins — this only bridges the rename, it never overrides.
- *
- * Exported for the seam test (a pure env mapping, no spawn).
- */
 export function buildServeEnv(base = process.env) {
     const env = {
         ...base,
@@ -274,14 +128,6 @@ function buildRequest(op, args, context) {
         request.context = context;
     return request;
 }
-/**
- * Describe what the child actually wrote on fd 4 when it did not parse as JSON,
- * so a wrong `secrets` on PATH (a shim printing usage, an unrelated binary), a
- * child that ran under the wrong runtime and never answered, or a silent write
- * failure is diagnosable from the error alone rather than a bare "non-JSON
- * response". Bounded to 200 bytes; control bytes are stripped so the message
- * stays one readable line.
- */
 function describeNonJson(text) {
     const trimmed = text.trim();
     if (!trimmed)
@@ -301,10 +147,6 @@ function parseResponse(raw) {
     if (!parsed || typeof parsed !== 'object') {
         throw new SecretsClientError('INVALID_RESPONSE', 'secrets returned a malformed response envelope');
     }
-    // Every reply carries the protocol it was written against, so version
-    // negotiation rides the answer itself — there is no separate handshake spawn
-    // to pay a cold Node boot for (PHNX-4082). A mismatch is the standalone being
-    // too old or too new, which is actionable; anything else is a broken envelope.
     if (typeof parsed.v === 'number' && parsed.v !== PROTOCOL_VERSION) {
         throw new SecretsClientError('PROTOCOL_UNSUPPORTED', `secrets speaks protocol ${String(parsed.v)}; this agents-cli needs ${PROTOCOL_VERSION}. ` +
             'Update the standalone CLI (npm i -g @phnx-labs/secrets-cli).');
@@ -316,7 +158,7 @@ function parseResponse(raw) {
         return decodeWire(parsed.result);
     throw new SecretsClientError(parsed.error.code, parsed.error.message);
 }
-// --- raw transport (one spawn per request) ---------------------------------
+// Anonymous fd3/fd4 pipes keep secret bytes off disk; success waits for both response EOF and child exit.
 function serveOnce(op, args, context) {
     const { command, prefix } = invocation(resolveSecretsBin());
     const request = Buffer.from(JSON.stringify(buildRequest(op, args, context)));
@@ -336,19 +178,9 @@ function serveOnce(op, args, context) {
         };
         const timer = setTimeout(() => fail(new SecretsClientError('TIMEOUT', 'secrets request timed out')), SERVE_TIMEOUT_MS);
         child.on('error', (error) => fail(new SecretsClientError('SPAWN_FAILED', `Failed to spawn secrets: ${error.message}`)));
-        // A child that dies before reading gives EPIPE here; the outcome surfaces on
-        // fd 4 / 'error' instead, so this handler just keeps it from throwing.
         const input = child.stdio[3];
         input.on('error', () => { });
         input.end(request);
-        // Settle only when BOTH the response has been read to EOF AND the child has
-        // fully exited. The standalone writes its response to fd 4 and closes it
-        // *before* it finishes: on the way out it still releases its proper-lockfile
-        // lock dir and flushes its meta/events log under the store's `.cache`.
-        // Resolving on fd-4 EOF alone let the caller (e.g. a test tearing down its
-        // throwaway SECRETS_HOME) race those trailing writes — an ENOTEMPTY rmdir.
-        // Awaiting child exit makes the store quiescent the instant secretsRequest
-        // resolves, so no consumer needs a cleanup retry.
         const out = child.stdio[4];
         const chunks = [];
         let size = 0;
@@ -385,7 +217,6 @@ function serveOnce(op, args, context) {
         });
     });
 }
-/** POSIX single-quote a token so the shell passes it to the child verbatim. */
 function shQuote(token) {
     return `'${token.replace(/'/g, `'\\''`)}'`;
 }
@@ -395,36 +226,6 @@ function serveOnceSync(op, args, context) {
     }
     const { command, prefix } = invocation(resolveSecretsBin());
     const request = Buffer.from(JSON.stringify(buildRequest(op, args, context)));
-    // The standalone's private protocol reads the request from fd 3 and writes the
-    // response to fd 4, wrapping BOTH in a `net.Socket` (secrets-cli
-    // `runProtocolServer`). It also REFUSES a plain file or tty for either — fd 3/4
-    // MUST be a pipe or socket (`PRIVATE_PIPE_REQUIRED`) — so no secret is ever
-    // staged to disk. But `spawnSync` only wires stdio 0-2 portably — the Bun
-    // runtime (this repo runs its whole CLI suite as `bun src/index.ts`, so the CLI-
-    // integration tests spawn agents-cli under Bun) silently DROPS numbered fds 3+,
-    // so the numbered-fd wiring is done in a POSIX shell.
-    //
-    // The request rides `spawnSync`'s STDIN, which every runtime backs with a real
-    // pipe/socketpair, and the shell dups it onto fd 3 (`3<&0`); fd 4 is dup'd from
-    // the captured stdout pipe (`4>&1`), then the child's own fd 1 is sent to
-    // /dev/null (`1>/dev/null`, AFTER `4>&1` so fd 4 keeps the pipe) — so the
-    // response channel (fd 4) is structurally the ONLY writer to the captured
-    // stream and a stray write to the standalone's own stdout can never corrupt the
-    // fd-4 bytes. Crucially, fd 3 and fd 4 are now the SAME anonymous
-    // pipe/socketpair the async path hands the standalone via `spawn` numbered
-    // stdio, rather than a named FIFO: a `net.Socket` wrapped around a named FIFO
-    // reads the request but never fires EOF on macOS, so the standalone's
-    // `for await (const chunk of input)` on fd 3 would hang for the full timeout
-    // (the bug the old FIFO wiring hit — spawnSync's stdout IS a socketpair, so fd 4
-    // was fine, but the FIFO on fd 3 never EOF'd). `exec` so the wrapper `sh`
-    // BECOMES the standalone (same PID): `spawnSync` waits on the real process, so
-    // on return the store is fully flushed and its lock dir released, and a timeout
-    // SIGTERM lands on the standalone itself rather than orphaning a wedged child.
-    // The response never touches disk. The shell wiring is parent-runtime-agnostic
-    // — `spawnSync`'s stdio is a socketpair under both Node and Bun — so fd 3 EOFs
-    // whenever the standalone itself runs under Node. (A standalone that `invocation`
-    // launches under BUN still hits its own PHNX-3989 EOF hang regardless of the
-    // wiring; that stays bounded by SYNC_SERVE_TIMEOUT_MS below, as before.)
     const serve = [command, ...prefix, '__serve'].map(shQuote).join(' ');
     const script = `exec ${serve} 3<&0 4>&1 1>/dev/null`;
     const result = spawnSync('sh', ['-c', script], {
@@ -441,12 +242,6 @@ function serveOnceSync(op, args, context) {
                 `(${[command, ...prefix, '__serve'].join(' ')}). The machine may be too loaded to boot it in time, or the install is broken: ` +
                 'check with `secrets --version`.');
         }
-        // A standalone that exits before draining fd 3 leaves `spawnSync`'s stdin
-        // write with EPIPE, yet its exit status and everything it wrote to fd 4 are
-        // still returned. Like the async path (`input.on('error', () => {})`), the
-        // outcome is whatever reached fd 4 — an empty or non-JSON answer is the
-        // diagnostic, not the errno. Seen on the GitHub-hosted runner, where a
-        // planted `exit 0` standalone exits faster than the request is written.
         if (err.code !== 'EPIPE') {
             throw new SecretsClientError('SPAWN_FAILED', `secrets request failed: ${err.message}`);
         }
@@ -457,50 +252,20 @@ function serveOnceSync(op, args, context) {
     }
     return parseResponse(raw);
 }
-// --- primitives ------------------------------------------------------------
-/**
- * Send one operation to the standalone secrets CLI and await its typed result.
- * Spawns `secrets __serve` once for the operation; `parseResponse` checks the
- * protocol on the reply it already carries. Throws a {@link SecretsClientError}
- * carrying the server's `{code, message}` on failure.
- */
 export async function secretsRequest(op, args = [], context) {
     return (await serveOnce(op, args, context));
 }
-/**
- * Synchronous sibling of {@link secretsRequest} for the consumers that resolve
- * secrets on a synchronous path (e.g. building a child env before spawn).
- * Bounded by a spawn timeout. POSIX only.
- */
 export function secretsRequestSync(op, args = [], context) {
     return serveOnceSync(op, args, context);
 }
-/** Test hook: forget the cached binary so a new env is re-resolved. */
 export function _resetSecretsClientForTest() {
     cachedBin = undefined;
     requestCounter = 0;
     syncServeTimeoutMs = SYNC_SERVE_TIMEOUT_MS;
 }
-/** Shorten the sync bound for a test that plants a hanging standalone; reset restores it. */
 export function _setSyncServeTimeoutForTest(ms) {
     syncServeTimeoutMs = ms;
 }
-// --- typed wrappers -------------------------------------------------------
-//
-// The resolve/read/write/raw-CRUD ops today's consumers hit — one thin, typed
-// forward each onto the two primitives above; the standalone remains the single
-// implementation. Async by default; the read-hot operations agents-cli resolves
-// synchronously carry a `*Sync` sibling.
-//
-// This is deliberately NOT the standalone's full op table. The remaining
-// bundle-metadata ops it also exposes — `bundlePolicy`,
-// `readBundleIfDecryptable`, `keychainItemsForBundle`, `migrateLegacyBundles`
-// — get their wrapper as the consumer-conversion wave (tasks.md item 6) lands
-// each caller that needs it, so a wrapper always ships with a real call site
-// and a test rather than as speculative unused surface. (`describeBundle`,
-// `bundleBackend`, `renameBundle`, `rotateBundleSecret`, and the `sync.*` /
-// `rc-hygiene.*` groups have landed with the consumers that needed them.)
-// bundles.*
 export function readAndResolveBundleEnv(name, opts, context) {
     return secretsRequest('bundles.readAndResolveBundleEnv', [name, opts ?? {}], context);
 }
@@ -513,12 +278,6 @@ export function listBundles(context) {
 export function listBundlesSync(context) {
     return secretsRequestSync('bundles.listBundles', [], context);
 }
-/**
- * Per-key kind breakdown (`literal`/`file`/`onepassword`/…) of an already-resolved
- * bundle — the cosmetic `[secrets] Resolved <name>: N keys (…)` summary line. Pure
- * over the bundle document server-side; the wrapper forwards the object the caller
- * already holds from {@link readAndResolveBundleEnv} so the same shape is described.
- */
 export function describeBundle(bundle, context) {
     return secretsRequest('bundles.describeBundle', [bundle], context);
 }
@@ -552,28 +311,24 @@ export function writeBundleWithItemsSync(bundle, items, opts, context) {
 export function deleteBundleSync(name, context) {
     return secretsRequestSync('bundles.deleteBundle', [name], context);
 }
-/** Rename a bundle: metadata and raw items move together; the source is deleted last. */
 export function renameBundle(oldName, newName, opts, context) {
     return secretsRequest('bundles.renameBundle', [oldName, newName, opts ?? {}], context);
 }
 export function renameBundleSync(oldName, newName, opts, context) {
     secretsRequestSync('bundles.renameBundle', [oldName, newName, opts ?? {}], context);
 }
-/** Rotate one keychain-backed key's value in place, preserving or patching its meta. */
 export function rotateBundleSecret(bundle, key, opts, context) {
     return secretsRequest('bundles.rotateBundleSecret', [bundle, key, opts], context);
 }
 export function rotateBundleSecretSync(bundle, key, opts, context) {
     secretsRequestSync('bundles.rotateBundleSecret', [bundle, key, opts], context);
 }
-// agent.*
 export function agentPing() {
     return secretsRequest('agent.agentPing', []);
 }
 export function agentStatus() {
     return secretsRequest('agent.agentStatus', []);
 }
-// index.* (keychain items)
 export function getKeychainToken(item, context) {
     return secretsRequest('index.getKeychainToken', [item, context ?? {}]);
 }
@@ -601,11 +356,6 @@ export function deleteKeychainTokenSync(item) {
 export function listKeychainItems(prefix) {
     return secretsRequest('index.listKeychainItems', [prefix]);
 }
-/**
- * True when `keychain`-backend items are being routed to the standalone's
- * encrypted file store (headless Linux/Windows with no reachable keyring):
- * on such a host no test or probe can reach a real OS keychain.
- */
 export function keychainUsesFileFallback() {
     return secretsRequest('index.keychainUsesFileFallback', []);
 }
@@ -621,22 +371,10 @@ export function storeSet(backend, item, value) {
 export function storeSetSync(backend, item, value) {
     secretsRequestSync('store.set', [backend, item, value]);
 }
-// remote.* / push.*
 export function remoteResolveEnv(target, bundle, opts) {
     return secretsRequest('remote.remoteResolveEnv', [target, bundle, opts ?? {}]);
 }
-/**
- * The user agents dir as the RECEIVING agents-cli resolves it — `~/.agents` on
- * every box, the same root {@link buildServeEnv} pins the local standalone to
- * (MIG-1). A push must name it, because the remote `secrets` otherwise runs
- * under its own default `~/.secrets`: the import succeeds, the file store there
- * is keyed by a different machine-local passphrase, and the receiving daemon's
- * `readReservedCredential` never finds the bundle (yosemite-m0, 2026-09-07:
- * `pushed __cursor__` on the publisher, `no readable durable key` on the worker).
- * Remote-relative on purpose — the local absolute dir means nothing over there.
- */
 export const REMOTE_USER_AGENTS_DIR = '~/.agents';
-/** Fill in the remote state root unless the caller named one. Pure, for the seam test. */
 export function withRemoteStateRoot(opts) {
     return { ...opts, remoteSecretsHome: opts.remoteSecretsHome ?? REMOTE_USER_AGENTS_DIR };
 }
@@ -646,14 +384,12 @@ export function pushBundleToHost(bundle, host, opts) {
 export function pushBundleToHostAsync(bundle, host, opts) {
     return secretsRequest('push.pushBundleToHostAsync', [bundle, host, withRemoteStateRoot(opts)]);
 }
-// sync.* (transport pull, used by the `agents sync --secrets` umbrella stage)
 export function listRemoteBundles(context) {
     return secretsRequest('sync.listRemoteBundles', [], context);
 }
 export function pullBundle(name, opts, context) {
     return secretsRequest('sync.pullBundle', [name, opts], context);
 }
-// rc-hygiene.* (shell-rc credential-export advisory, `agents doctor`)
 export function scanUserRcFiles(homeDir, context) {
     return secretsRequest('rc-hygiene.scanUserRcFiles', homeDir === undefined ? [] : [homeDir], context);
 }
@@ -666,13 +402,6 @@ export function masterPassphraseInEnv(context) {
 export function masterPassphraseInEnvSync(context) {
     return secretsRequestSync('rc-hygiene.masterPassphraseInEnv', [], context);
 }
-// --- env sanitization (EXEC-1: deny loader/interpreter overrides) ----------
-//
-// Pure, engine-free — every spawn boundary strips these before either an
-// injected secrets env or the bare process env reaches a child, so a bundle
-// (or an inherited shell) can never smuggle a loader/interpreter override into
-// an agent's process.
-/** True for a dynamic-loader or language-interpreter override env var. */
 function isLoaderOrInterpreterEnv(name) {
     const upper = name.toUpperCase();
     return (upper.startsWith('LD_') ||
@@ -690,7 +419,7 @@ function isLoaderOrInterpreterEnv(name) {
             'CDPATH',
         ].includes(upper));
 }
-/** Strip loader/interpreter overrides from an env before it reaches a spawned child. */
+// Strip loader/interpreter injection variables before spawning the standalone secrets engine.
 export function sanitizeProcessEnv(env = process.env) {
     const out = {};
     for (const [k, v] of Object.entries(env)) {