@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/lib/secrets/agent.js

@@ -723,6 +723,46 @@ export function agentGetSync(name) {
         return null;
     }
 }
+/** Inline node program for a synchronous liveness ping. Connects, sends one
+ * `{cmd:'ping'}`, exits 0 iff a valid ping response comes back, else 3. A stale
+ * socket file with no listener refuses the connection immediately, so this
+ * fast-fails without riding any cold-start logic. argv after -e: [execPath, <socket>]. */
+const SYNC_PING_PROGRAM = `
+const net = require('net');
+const sock = process.argv[1];
+const c = net.createConnection(sock);
+let buf = '';
+const dead = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
+const timer = setTimeout(dead, 700);
+c.on('error', dead);
+c.on('connect', () => c.write(JSON.stringify({ cmd: 'ping' }) + '\\n'));
+c.setEncoding('utf-8');
+c.on('data', (d) => {
+  buf += d;
+  const nl = buf.indexOf('\\n');
+  if (nl < 0) return;
+  clearTimeout(timer);
+  let r; try { r = JSON.parse(buf.slice(0, nl)); } catch (e) { return dead(); }
+  try { c.destroy(); } catch (e) {}
+  process.exit(r && r.ok && r.cmd === 'ping' ? 0 : 3);
+});
+`;
+/**
+ * Synchronous liveness check: is a broker actually LISTENING and answering (not
+ * just a lingering socket file)? Used to decide whether the auto-cache may take
+ * the synchronous warm path — a dead broker whose socket outlived it (crash,
+ * OOM, version-skew teardown) must NOT drag a foreground read through the
+ * worker's 20s cold-start budget. A stale socket refuses instantly, so this is
+ * fast in both the alive and dead cases. macOS only.
+ */
+export function agentReachableSync() {
+    if (!onDarwin())
+        return false;
+    if (!agentSocketExists())
+        return false;
+    const r = spawnSync(process.execPath, ['-e', SYNC_PING_PROGRAM, socketPath()], { timeout: 1500 });
+    return r.status === 0 && !r.error;
+}
 /**
  * Inline node program for the synchronous evict path. Mirrors SYNC_GET_PROGRAM:
  * writeBundle is synchronous and called synchronously everywhere, so a stale
@@ -817,26 +857,81 @@ export function secretsAgentAutoEnabled() {
         return true;
     }
 }
+/** Minimum / maximum bounds for the configurable hold window. A too-small value
+ * would defeat the broker (constant re-prompts); a too-large one pins secrets in
+ * memory far longer than intended. */
+export const MIN_HOLD_MS = 60 * 1000; // 1m
+export const MAX_HOLD_MS = 30 * 24 * 60 * 60 * 1000; // 30d
+/**
+ * How long an unlocked / auto-cached bundle is held before the next read
+ * re-prompts. Defaults to DEFAULT_TTL_MS (7d); override with
+ * `secrets.agent.holdMs` (milliseconds) in agents.yaml — e.g. 86400000 for a 24h
+ * cap. Clamped to [MIN_HOLD_MS, MAX_HOLD_MS] so a typo can neither disable the
+ * hold nor pin a secret in memory indefinitely. Best-effort: an unreadable or
+ * non-numeric value falls back to the 7d default. Pure except for the meta read.
+ */
+export function secretsHoldMs() {
+    try {
+        return clampHoldMs(readMeta().secrets?.agent?.holdMs);
+    }
+    catch {
+        return DEFAULT_TTL_MS;
+    }
+}
+/** Pure clamp for a configured `holdMs`: a positive finite number is bounded to
+ * [MIN_HOLD_MS, MAX_HOLD_MS]; anything else (absent, 0, negative, NaN, non-number)
+ * falls back to the 7d default. Exported for direct unit testing. */
+export function clampHoldMs(v) {
+    if (typeof v === 'number' && Number.isFinite(v) && v > 0) {
+        return Math.min(Math.max(Math.floor(v), MIN_HOLD_MS), MAX_HOLD_MS);
+    }
+    return DEFAULT_TTL_MS;
+}
 /**
  * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
  * NEXT process reads it without a prompt. Used by the auto-cache path after a
- * real keychain read of a `daily`-policy bundle. Adds no latency to the caller
- * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
- * over stdin, never argv) and returns immediately.
+ * real keychain read of a `daily`-policy bundle, so the NEXT concurrent read is
+ * silent. Env travels over stdin, never argv.
  *
- * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping with a
- * generous budget) rather than a tight inline retry loop: under heavy load the
- * broker is itself a cold-starting full CLI and can take several seconds to bind
- * the socket, so a short fixed budget would give up before it's ready and the
- * cache would silently never populate. Best-effort; never throws. macOS only.
+ * Reliability (this is what makes `daily` actually "stick"): when a broker is
+ * ALREADY listening, warm it SYNCHRONOUSLY with a bounded wait so the bundle is
+ * held by the time this process exits. The old detached-only path lost the race
+ * under load — a short-lived reader (`agents secrets export`, a release-script
+ * loop) exited before the unref'd worker connected, so the cache silently never
+ * populated and every read re-prompted despite the `daily` policy. Only when the
+ * broker must COLD-START (no socket yet) do we fall back to the detached worker,
+ * so a first-ever read never blocks on a multi-second broker boot.
+ *
+ * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
+ * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
 export function agentAutoLoadSync(name, bundle, env, ttlMs) {
     if (!onDarwin())
         return;
+    const payload = JSON.stringify({ name, bundle, env, ttlMs });
+    // Broker actually LISTENING → deterministic synchronous warm (bounded; the read
+    // already paid a Touch ID, so <1s here is invisible). We gate on a real liveness
+    // ping, NOT mere socket-file existence: a broker that died leaving its socket
+    // behind (crash, OOM, or the version-skew teardown in this file) would otherwise
+    // drag this FOREGROUND read through the worker's 20s cold-start budget on every
+    // read. A dead/stale socket fails the ping fast, so we drop straight to the
+    // detached path (which does the cold-start + stale-socket cleanup off the hot
+    // path) — restoring "a dead broker costs the foreground read nothing".
+    if (agentReachableSync()) {
+        try {
+            const { cmd, args } = cliSpawn(['secrets', '_agent-load']);
+            const r = spawnSync(cmd, args, { input: payload, timeout: 3000, stdio: ['pipe', 'ignore', 'ignore'] });
+            if (!r.error && r.status === 0)
+                return;
+        }
+        catch {
+            // fall through to the detached best-effort path
+        }
+    }
     try {
         const { cmd, args } = cliSpawn(['secrets', '_agent-load']);
         const worker = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'], detached: true });
-        worker.stdin?.write(JSON.stringify({ name, bundle, env, ttlMs }));
+        worker.stdin?.write(payload);
         worker.stdin?.end();
         worker.unref();
     }
@@ -847,8 +942,14 @@ export function agentAutoLoadSync(name, bundle, env, ttlMs) {
 /**
  * Body of the hidden `secrets _agent-load` worker. Reads one `{name, bundle,
  * env, ttlMs}` payload from stdin, ensures the broker is up (robust, generous
- * budget), and loads the bundle into it. Detached from the originating read, so
- * its latency is invisible — which is why it can afford a long ensure budget.
+ * budget), and loads the bundle into it.
+ *
+ * Exit code is load-truthful: 0 ONLY when the bundle was actually loaded into a
+ * reachable broker; non-zero on any failure (malformed payload, broker couldn't
+ * be brought up, or the load transport failed). The synchronous caller
+ * (agentAutoLoadSync) relies on this to decide whether to skip the detached
+ * fallback — a bare "process exited 0" would otherwise be a false-positive
+ * success that silently reintroduces the very re-prompt storm this path fixes.
  */
 export async function runAgentLoadFromStdin() {
     if (!onDarwin())
@@ -861,15 +962,22 @@ export async function runAgentLoadFromStdin() {
         payload = JSON.parse(Buffer.concat(chunks).toString('utf-8'));
     }
     catch {
-        return; // malformed payload — nothing to load
+        process.exitCode = 1; // malformed payload — nothing loaded
+        return;
     }
-    if (!payload || !payload.name || !payload.bundle || !payload.env)
+    if (!payload || !payload.name || !payload.bundle || !payload.env) {
+        process.exitCode = 1;
         return;
+    }
     // Generous budget: the broker is a cold-starting full CLI; under load it can
     // take several seconds to bind. We're detached, so waiting costs nothing.
-    if (!(await ensureAgentRunning(20000)))
+    if (!(await ensureAgentRunning(20000))) {
+        process.exitCode = 1; // broker couldn't be brought up — did NOT load
         return;
-    await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS);
+    }
+    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS);
+    if (!loaded)
+        process.exitCode = 1; // transport failed — did NOT load
 }
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
 export async function agentLoad(name, bundle, env, ttlMs) {

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

@@ -221,6 +221,32 @@ export declare function assertRemoteBundleFlagsUnsupported(bundleName: string, h
     allowExpiredFlag: string;
 }): void;
 export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveBundleOptions): Record<string, string>;
+/**
+ * True when the current process is a background / non-interactive context that
+ * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
+ * a prompt nobody is watching. Two signals, either sufficient:
+ *   - `AGENTS_RUNTIME` is `headless` or `teams` (set on the child env by
+ *     `agents run --headless`, scheduled routines, and teammates — see
+ *     exec.ts:resolveInteractive, runner.ts, teams/agents.ts).
+ *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
+ *     stdio is redirected to a log — e.g. a release script run in the
+ *     background as `( ... ) >log 2>&1 </dev/null`).
+ * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
+ * even in a non-TTY context. An interactive `eval "$(agents secrets export X)"`
+ * keeps its terminal stdin, so it is NOT classified headless and still prompts.
+ *
+ * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
+ * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
+ * the Windows credential store resolve without any prompt. So off-darwin this
+ * ALWAYS returns false: forcing broker-only there would break every headless
+ * Linux/Windows read (CI, `agents run --headless`, routines, the Linux-driven
+ * release flow) for no benefit — there is no prompt to suppress.
+ *
+ * A read in a macOS headless context resolves broker-only (agentOnly) and fails
+ * fast with an actionable error instead of hijacking Touch ID. This generalizes
+ * the per-caller pattern already used by the daemon (daemon.ts:readDaemonClaudeOAuthToken).
+ */
+export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *

package/dist/lib/secrets/bundles.js

@@ -25,7 +25,7 @@ import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainTo
 import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
 import { readMeta } from '../state.js';
-import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
+import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, secretsHoldMs } from './agent.js';
 import { createHash } from 'node:crypto';
 const keychainStore = {
     has: hasKeychainToken,
@@ -492,8 +492,11 @@ export function listBundles() {
                 for (const bundle of keychainBundles)
                     out.push(bundle);
                 // Populate the broker for the rest of the hold window (fire-and-forget).
+                // Same configurable cap as the value read-path — otherwise `secrets list`
+                // would keep serving a stale metadata snapshot for 7d even when the user
+                // capped the hold at 24h via secrets.agent.holdMs.
                 if (useAgent && keychainBundles.length > 0) {
-                    agentAutoLoadMetaSync(nameSetHash, keychainBundles, DEFAULT_TTL_MS);
+                    agentAutoLoadMetaSync(nameSetHash, keychainBundles, secretsHoldMs());
                 }
             }
         }
@@ -705,6 +708,44 @@ export function resolveBundleEnv(bundle, _opts = {}) {
     void _opts.caller;
     return env;
 }
+/**
+ * True when the current process is a background / non-interactive context that
+ * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
+ * a prompt nobody is watching. Two signals, either sufficient:
+ *   - `AGENTS_RUNTIME` is `headless` or `teams` (set on the child env by
+ *     `agents run --headless`, scheduled routines, and teammates — see
+ *     exec.ts:resolveInteractive, runner.ts, teams/agents.ts).
+ *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
+ *     stdio is redirected to a log — e.g. a release script run in the
+ *     background as `( ... ) >log 2>&1 </dev/null`).
+ * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
+ * even in a non-TTY context. An interactive `eval "$(agents secrets export X)"`
+ * keeps its terminal stdin, so it is NOT classified headless and still prompts.
+ *
+ * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
+ * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
+ * the Windows credential store resolve without any prompt. So off-darwin this
+ * ALWAYS returns false: forcing broker-only there would break every headless
+ * Linux/Windows read (CI, `agents run --headless`, routines, the Linux-driven
+ * release flow) for no benefit — there is no prompt to suppress.
+ *
+ * A read in a macOS headless context resolves broker-only (agentOnly) and fails
+ * fast with an actionable error instead of hijacking Touch ID. This generalizes
+ * the per-caller pattern already used by the daemon (daemon.ts:readDaemonClaudeOAuthToken).
+ */
+export function isHeadlessSecretsContext(env = process.env, platform = process.platform) {
+    if (platform !== 'darwin')
+        return false; // no biometry prompt to suppress off-darwin
+    const override = env.AGENTS_SECRETS_NO_PROMPT;
+    if (override === '1')
+        return true;
+    if (override === '0')
+        return false;
+    const runtime = env.AGENTS_RUNTIME;
+    if (runtime === 'headless' || runtime === 'teams')
+        return true;
+    return !process.stdin.isTTY && !process.stdout.isTTY;
+}
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *
@@ -747,8 +788,15 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             return filtered;
         }
     }
-    if (opts.agentOnly) {
-        throw new Error(`Secrets bundle '${name}' is not unlocked in the secrets agent.`);
+    // 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.
+    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.`);
     }
     if (backend === 'file')
         assertFileBackendUsable(name);
@@ -881,15 +929,18 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         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
-        // enabled `secrets.agent.auto`, populate the broker in the background so the
-        // next concurrent run reads silently. Skipped when noAgent (e.g. `unlock`,
-        // which loads the agent itself). Fire-and-forget — never blocks this read.
+        // enabled `secrets.agent.auto`, populate the broker so the next concurrent
+        // run reads silently. Skipped when noAgent (e.g. `unlock`, which loads the
+        // agent itself). When a broker is already up this warms it synchronously
+        // (bounded ~3s) so `daily` reliably sticks; only a cold-start broker uses the
+        // detached fire-and-forget path (see agentAutoLoadSync). The costly Touch ID
+        // prompt already happened, so the bounded wait is invisible.
         if (backend === 'keychain' &&
             !opts.noAgent &&
             process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
             bundlePolicy(bundle) === 'daily' &&
             secretsAgentAutoEnabled()) {
-            agentAutoLoadSync(name, bundle, env, DEFAULT_TTL_MS);
+            agentAutoLoadSync(name, bundle, env, secretsHoldMs());
         }
         return { bundle, env };
     }

package/dist/lib/secrets/mcp.js

@@ -24,7 +24,7 @@
  * unit-testable in-process.
  */
 import * as readline from 'readline';
-import { listBundles, readAndResolveBundleEnv, readBundle, validateBundleName, } from './bundles.js';
+import { listBundles, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, validateBundleName, } from './bundles.js';
 /** MCP protocol revision this server negotiates. */
 export const MCP_PROTOCOL_VERSION = '2024-11-05';
 /** The single tool this server exposes. */
@@ -68,7 +68,9 @@ export function resolveSecret(bundle, key) {
         throw new Error(`Key '${key}' not found in bundle '${bundle}'.` +
             (available.length ? ` Available keys: ${available.join(', ')}.` : ' Bundle has no keys.'));
     }
-    const { env } = readAndResolveBundleEnv(bundle, { caller: 'secrets-mcp' });
+    // The MCP get_secret tool is typically served by a background/headless agent
+    // process; resolve broker-only there so it never raises an unwatched prompt.
+    const { env } = readAndResolveBundleEnv(bundle, { caller: 'secrets-mcp', agentOnly: isHeadlessSecretsContext() });
     const value = env[key];
     if (value === undefined) {
         throw new Error(`Key '${key}' in bundle '${bundle}' could not be resolved.`);

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

@@ -16,6 +16,23 @@
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
  */
 import { type SshExecResult } from '../ssh-exec.js';
+/**
+ * Trust boundary for a remote-resolved env map. A peer's `secrets export` output
+ * is untrusted input: a compromised or misconfigured host could return keys that
+ * silently reshape THIS process's behavior once merged into the agent env
+ * (bundles.ts:251 `sanitizeProcessEnv` only strips loader vars from process.env,
+ * never the remote bundle). Block the dangerous-override classes here — at the
+ * source — so every consumer (`run --secrets b@host`, `secrets exec --host`) is
+ * protected, not just one call site:
+ *   - LD_* / DYLD_* / NODE_OPTIONS and the other loader/interpreter injections
+ *     (reuses the canonical bundles.ts predicate);
+ *   - GIT_*        — GIT_SSH_COMMAND et al. hijack every git subprocess;
+ *   - *_PROXY      — HTTP(S)_PROXY / ALL_PROXY reroute outbound traffic (MITM);
+ *   - *_BASE_URL   — ANTHROPIC_BASE_URL / OPENAI_BASE_URL redirect the model API.
+ * These keys are already rejected on the ADD side (validateEnvKey for loaders),
+ * so a legitimate bundle never carries them — only a hostile peer would.
+ */
+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,

package/dist/lib/secrets/remote.js

@@ -21,7 +21,36 @@ import { emit } from '../events.js';
 import { sshTargetFor } from '../hosts/types.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
+import { isLoaderOrInterpreterEnv } from './bundles.js';
 const REMOTE_TIMEOUT_MS = 30_000;
+/**
+ * Trust boundary for a remote-resolved env map. A peer's `secrets export` output
+ * is untrusted input: a compromised or misconfigured host could return keys that
+ * silently reshape THIS process's behavior once merged into the agent env
+ * (bundles.ts:251 `sanitizeProcessEnv` only strips loader vars from process.env,
+ * never the remote bundle). Block the dangerous-override classes here — at the
+ * source — so every consumer (`run --secrets b@host`, `secrets exec --host`) is
+ * protected, not just one call site:
+ *   - LD_* / DYLD_* / NODE_OPTIONS and the other loader/interpreter injections
+ *     (reuses the canonical bundles.ts predicate);
+ *   - GIT_*        — GIT_SSH_COMMAND et al. hijack every git subprocess;
+ *   - *_PROXY      — HTTP(S)_PROXY / ALL_PROXY reroute outbound traffic (MITM);
+ *   - *_BASE_URL   — ANTHROPIC_BASE_URL / OPENAI_BASE_URL redirect the model API.
+ * These keys are already rejected on the ADD side (validateEnvKey for loaders),
+ * so a legitimate bundle never carries them — only a hostile peer would.
+ */
+export function isDangerousRemoteEnvKey(name) {
+    const upper = name.toUpperCase();
+    if (isLoaderOrInterpreterEnv(upper))
+        return true;
+    if (upper.startsWith('GIT_'))
+        return true;
+    if (upper.endsWith('_PROXY'))
+        return true;
+    if (upper.endsWith('_BASE_URL'))
+        return true;
+    return false;
+}
 /** Remote OS for a host name or target string. Prefer the original host name
  * because enrolled inline hosts resolve to `user@address`, while the OS
  * registry is keyed by the host name. */
@@ -153,9 +182,20 @@ export async function remoteResolveEnv(target, bundle, opts = {}) {
         throw new Error(`Unexpected payload resolving '${bundle}' on ${target}.`);
     }
     const env = {};
+    const blocked = [];
     for (const [k, v] of Object.entries(parsed)) {
+        // Drop dangerous-override keys returned by the (untrusted) peer before they
+        // can reshape this process — see isDangerousRemoteEnvKey.
+        if (isDangerousRemoteEnvKey(k)) {
+            blocked.push(k);
+            continue;
+        }
         env[k] = typeof v === 'string' ? v : String(v);
     }
+    if (blocked.length > 0) {
+        process.stderr.write(`[secrets] Dropped ${blocked.length} dangerous key(s) from '${bundle}'@${target} ` +
+            `(remote override blocked): ${blocked.join(', ')}\n`);
+    }
     // The remote host audits its own `secrets export` read; this emit records the
     // event on the INITIATING host too (values were pulled into this process and
     // injected locally). Covers `secrets exec --host` and `run --secrets b@host`.

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

@@ -83,6 +83,26 @@ export declare function installPackageIntoPrefix(spec: string, prefix: string):
  * package's postinstall hook.
  */
 export declare function installPackageWithBun(spec: string): Promise<void>;
+/**
+ * Verify a downloaded tarball's bytes against a Subresource Integrity (SRI)
+ * string of the form `sha512-<base64>` — npm's `dist.integrity`. Recomputes the
+ * digest over the actual bytes with the named algorithm and compares it, in
+ * constant time, to the decoded expected digest.
+ *
+ * Fails closed: a malformed SRI, an algorithm weaker than sha512, or any digest
+ * mismatch throws. This is the gate that makes self-update refuse a tampered or
+ * corrupted tarball *before* it is ever handed to a package manager to install.
+ */
+export declare function verifyTarballIntegrity(tarball: Buffer, integrity: string): void;
+/**
+ * Download the published tarball at `tarballUrl` and prove its bytes match
+ * `integrity` before returning a path to it on disk. The returned .tgz is safe
+ * to hand to `npm install`/`bun add` — it has been verified byte-for-byte
+ * against the registry attestation. Fails closed: a non-200, a download error,
+ * or a hash mismatch throws and no file path is returned, so the caller never
+ * installs an unverified artifact.
+ */
+export declare function downloadVerifiedTarball(tarballUrl: string, integrity: string, timeoutMs?: number): Promise<string>;
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export declare function readInstalledVersion(packageRoot: string): string;
 /**

package/dist/lib/self-update.js

@@ -14,6 +14,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { createHash, timingSafeEqual } from 'crypto';
 import { spawnSync } from 'child_process';
 import { compareVersions } from './versions.js';
 import { needsWindowsShell } from './platform/index.js';
@@ -164,7 +165,59 @@ export async function installPackageWithBun(spec) {
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
     // On Windows `bun` resolves to `bun.exe`/`bun.cmd`; force shell for the .cmd case.
-    await execFileAsync('bun', ['add', '-g', spec], { shell: needsWindowsShell('bun') });
+    // --ignore-scripts: the tarball has already been integrity-verified, but its
+    // lifecycle scripts must not run at install time (the caller refreshes shims
+    // explicitly via refreshAliasShims()) — same fail-closed posture as the npm path.
+    await execFileAsync('bun', ['add', '-g', spec, '--ignore-scripts'], { shell: needsWindowsShell('bun') });
+}
+/**
+ * Verify a downloaded tarball's bytes against a Subresource Integrity (SRI)
+ * string of the form `sha512-<base64>` — npm's `dist.integrity`. Recomputes the
+ * digest over the actual bytes with the named algorithm and compares it, in
+ * constant time, to the decoded expected digest.
+ *
+ * Fails closed: a malformed SRI, an algorithm weaker than sha512, or any digest
+ * mismatch throws. This is the gate that makes self-update refuse a tampered or
+ * corrupted tarball *before* it is ever handed to a package manager to install.
+ */
+export function verifyTarballIntegrity(tarball, integrity) {
+    const dash = integrity.indexOf('-');
+    if (dash <= 0) {
+        throw new Error(`malformed integrity string: ${JSON.stringify(integrity)}`);
+    }
+    const algorithm = integrity.slice(0, dash);
+    const expectedBase64 = integrity.slice(dash + 1);
+    // npm publishes sha512 SRI; refuse to verify against anything weaker rather
+    // than silently accepting a downgraded (e.g. sha1) attestation.
+    if (algorithm !== 'sha512') {
+        throw new Error(`unsupported integrity algorithm '${algorithm}' (expected sha512)`);
+    }
+    const expected = Buffer.from(expectedBase64, 'base64');
+    const actual = createHash('sha512').update(tarball).digest();
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+        throw new Error(`integrity check failed: tarball hash sha512-${actual.toString('base64')} ` +
+            `does not match expected ${integrity}`);
+    }
+}
+/**
+ * Download the published tarball at `tarballUrl` and prove its bytes match
+ * `integrity` before returning a path to it on disk. The returned .tgz is safe
+ * to hand to `npm install`/`bun add` — it has been verified byte-for-byte
+ * against the registry attestation. Fails closed: a non-200, a download error,
+ * or a hash mismatch throws and no file path is returned, so the caller never
+ * installs an unverified artifact.
+ */
+export async function downloadVerifiedTarball(tarballUrl, integrity, timeoutMs = 60_000) {
+    const response = await fetch(tarballUrl, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) {
+        throw new Error(`could not download tarball from ${tarballUrl} (HTTP ${response.status})`);
+    }
+    const tarball = Buffer.from(await response.arrayBuffer());
+    verifyTarballIntegrity(tarball, integrity);
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-cli-upgrade-'));
+    const file = path.join(dir, path.basename(new URL(tarballUrl).pathname) || 'package.tgz');
+    fs.writeFileSync(file, tarball);
+    return file;
 }
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export function readInstalledVersion(packageRoot) {

package/dist/lib/serve/control.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Authenticated `agents serve --control` server — the "anchor" the iOS/iPadOS
+ * cockpit talks to (RUSH-1731).
+ *
+ * It is the read-only {@link handleServeGet} surface plus a small mutation API,
+ * gated by a bearer token ({@link verifyControlToken}) on EVERY request because,
+ * unlike plain `agents serve`, this variant may bind beyond loopback (a tailnet
+ * address) so the phone can reach it. It adds no new execution machinery: a run
+ * request re-invokes the same `agents run` the CLI uses (inheriting host
+ * offload, secrets, detached dispatch), and a message re-invokes `agents
+ * message`. The server generates the run's session id so the run is immediately
+ * addressable for streaming (Phase 2) and steering.
+ *
+ * Both side-effecting operations are behind DI seams ({@link ControlOptions})
+ * so tests drive them without spawning real agents — mirroring the `snapshot`
+ * seam on the read-only server.
+ */
+import type http from 'http';
+import type { StdioOptions } from 'child_process';
+import { type ServeOptions } from './server.js';
+/** A request to start an agent run on this anchor (local or offloaded). */
+export interface RunRequest {
+    /** Agent to run: 'claude' | 'codex' | 'gemini' | … */
+    agent: string;
+    /** Headless prompt. */
+    prompt: string;
+    /** Permission mode: plan | edit | auto | skip. Defaults to the CLI default. */
+    mode?: string;
+    /** Offload onto a registered device / host (the executor). Omit → run on the anchor. */
+    host?: string;
+    /** Working directory (on the host when `host` is set). */
+    cwd?: string;
+}
+/** Identifiers by which the started run can later be streamed / messaged. */
+export interface RunResult {
+    /** Addressable session id (a UUID for claude; otherwise equals `name`). */
+    sessionId: string;
+    /** Durable run name seeded into the session label. */
+    name: string;
+}
+/** Starts a run and returns its addressable ids. */
+export type RunDispatcher = (req: RunRequest) => Promise<RunResult>;
+/** Delivers a message to a running/parked agent by id. */
+export type Messenger = (id: string, text: string, from?: string) => Promise<void>;
+export interface ControlOptions extends ServeOptions {
+    /** Bearer verifier. Defaults to {@link verifyControlToken}. */
+    verifyToken?: (presented: string | undefined) => boolean;
+    /** Run starter. Defaults to spawning `agents run …` detached. */
+    runner?: RunDispatcher;
+    /** Message sender. Defaults to spawning `agents message …`. */
+    messenger?: Messenger;
+    /** Poll cadence (ms) for the session event stream. Defaults to 300. */
+    streamPollMs?: number;
+    /** Resolve a session id to its NDJSON capture file. Defaults to {@link streamLogPath}. */
+    streamLogPathFor?: (sessionId: string) => string;
+}
+/**
+ * SSE stream of a session's normalized NDJSON events, offset-tailed from its
+ * capture file. Resumes from `?offset=<bytes>` or the `Last-Event-ID` header
+ * (each event's `id:` is its exact byte offset, so resume neither loses nor
+ * duplicates). Closes when a terminal (`result`/`error`) event is seen or the
+ * client disconnects. A not-yet-created file simply yields nothing until the
+ * run starts writing — the phone can open the stream the instant it dispatches.
+ */
+export declare function startSessionStream(file: string, req: http.IncomingMessage, res: http.ServerResponse, pollMs: number): void;
+/**
+ * Spawn a detached child and settle once it has either successfully spawned or
+ * failed to. Attaching an `'error'` listener is mandatory: a `ChildProcess` is
+ * an `EventEmitter`, so an `'error'` event (e.g. ENOENT from a stale/missing
+ * `agents` binary — a real condition `validateDaemonBinary` guards against)
+ * with no listener throws and would take down the whole anchor process, not
+ * just the one request. Mirrors the `once('spawn') / once('error')` pattern in
+ * `teams/agents.ts`. The `'error'` listener registered by `once` survives after
+ * a successful spawn, so a later error is absorbed rather than crashing.
+ */
+export declare function spawnDetached(command: string, args: string[], stdio?: StdioOptions): Promise<void>;
+/**
+ * Default run dispatcher: re-invoke `agents run` with a server-minted id so the
+ * run is addressable, detached so it outlives this request (and the anchor
+ * process). Local runs detach here; `--host` runs detach on the executor via
+ * the existing dispatch path.
+ */
+export declare const defaultRunner: RunDispatcher;
+/** Default messenger: re-invoke `agents message <id> <text>` and await its exit. */
+export declare const defaultMessenger: Messenger;
+/**
+ * Create (but do not start) the authenticated control server. Caller invokes
+ * `.listen(port, bind)`.
+ */
+export declare function createControlServer(opts?: ControlOptions): http.Server;
+/** Start the control server on `port`, bound to `bind`. Resolves the bound port. */
+export declare function startControlServer(port: number, bind: string, opts?: ControlOptions): Promise<{
+    server: http.Server;
+    port: number;
+}>;