@phnx-labs/agents-cli 1.20.64 → 1.20.66

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/filestore.d.ts

@@ -22,6 +22,15 @@
  */
 import type { KeychainBackend } from './index.js';
 export declare function fileDir(): string;
+/**
+ * Turn off terminal echo on the controlling TTY, or throw — fail CLOSED. If echo
+ * cannot be disabled (`stty` missing, no controlling terminal) we must NOT fall
+ * through and read the passphrase anyway: that echoes the secret to the screen
+ * and into scrollback (RUSH-1764). Refuse and point the user at the environment
+ * variable instead. `run` performs the echo-disable and throws iff it fails.
+ * Exported so the fail-closed contract has direct test coverage.
+ */
+export declare function disableTtyEchoOrThrow(run: () => void): void;
 /** True if a machine-local passphrase has already been provisioned. */
 export declare function machinePassphraseExists(): boolean;
 /**

package/dist/lib/secrets/filestore.js

@@ -65,6 +65,24 @@ finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr) }
     }
     return (res.stdout?.toString() ?? '').replace(/\r?\n$/, '');
 }
+/**
+ * Turn off terminal echo on the controlling TTY, or throw — fail CLOSED. If echo
+ * cannot be disabled (`stty` missing, no controlling terminal) we must NOT fall
+ * through and read the passphrase anyway: that echoes the secret to the screen
+ * and into scrollback (RUSH-1764). Refuse and point the user at the environment
+ * variable instead. `run` performs the echo-disable and throws iff it fails.
+ * Exported so the fail-closed contract has direct test coverage.
+ */
+export function disableTtyEchoOrThrow(run) {
+    try {
+        run();
+    }
+    catch {
+        throw new Error('Refusing to prompt for AGENTS_SECRETS_PASSPHRASE: terminal echo could not be ' +
+            'disabled (stty unavailable or no controlling TTY), so the passphrase would be ' +
+            'shown in cleartext. Set AGENTS_SECRETS_PASSPHRASE in the environment instead.');
+    }
+}
 function readPassphraseFromTty() {
     if (process.platform === 'win32')
         return readPassphraseFromTtyWindows();
@@ -72,14 +90,9 @@ function readPassphraseFromTty() {
     let echoDisabled = false;
     try {
         fs.writeSync(fd, 'Enter AGENTS_SECRETS_PASSPHRASE: ');
-        try {
-            execSync('stty -echo < /dev/tty', { stdio: 'ignore' });
-            echoDisabled = true;
-        }
-        catch {
-            // stty not available — fall through; passphrase will echo. Better
-            // than refusing to function.
-        }
+        // Fail closed: if echo can't be turned off, abort rather than echo the secret.
+        disableTtyEchoOrThrow(() => execSync('stty -echo < /dev/tty', { stdio: 'ignore' }));
+        echoDisabled = true;
         let pass = '';
         const buf = Buffer.alloc(1);
         while (true) {

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

@@ -214,6 +214,13 @@ export declare function getKeychainTokens(items: string[]): Map<string, string>;
  * predates that path rejects the unknown command (exit 2) and this throws,
  * rather than silently falling back to an ACL'd `set` (which would behave like
  * `always`). Ignored by the Linux/Windows/test backends, which have no ACL. */
+/**
+ * argv for writing a bare (non-`agents-cli.`) keychain item via
+ * `/usr/bin/security add-generic-password`, deliberately WITHOUT the value: the
+ * secret travels over stdin (see setKeychainToken) so it never lands in argv or
+ * a `ps` snapshot. Exported so a test can assert the value is absent from argv.
+ */
+export declare function buildAddGenericPasswordArgs(account: string, item: string): string[];
 export declare function setKeychainToken(item: string, value: string, opts?: {
     noAcl?: boolean;
 }): void;

package/dist/lib/secrets/index.js

@@ -844,6 +844,15 @@ function parseBatchRecords(out, record) {
  * predates that path rejects the unknown command (exit 2) and this throws,
  * rather than silently falling back to an ACL'd `set` (which would behave like
  * `always`). Ignored by the Linux/Windows/test backends, which have no ACL. */
+/**
+ * argv for writing a bare (non-`agents-cli.`) keychain item via
+ * `/usr/bin/security add-generic-password`, deliberately WITHOUT the value: the
+ * secret travels over stdin (see setKeychainToken) so it never lands in argv or
+ * a `ps` snapshot. Exported so a test can assert the value is absent from argv.
+ */
+export function buildAddGenericPasswordArgs(account, item) {
+    return ['add-generic-password', '-U', '-a', account, '-s', item, '-w'];
+}
 export function setKeychainToken(item, value, opts) {
     // Validate the CLEARTEXT name (a hashed storage name is always clean), then
     // resolve the storage name.
@@ -872,12 +881,23 @@ export function setKeychainToken(item, value, opts) {
     // /usr/bin/security read can't satisfy without popping the legacy password
     // sheet. -U upserts so repeated sets overwrite in place.
     if (!isOurItem(item)) {
-        const sec = spawnSync('/usr/bin/security', [
-            'add-generic-password', '-U',
-            '-a', os.userInfo().username,
-            '-s', item,
-            '-w', value,
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
+        // The secret VALUE must never appear in argv — a `ps` snapshot on a shared
+        // host would leak it (RUSH-1764). `security add-generic-password` has no
+        // stdin-password flag; instead a BARE `-w` as the LAST option makes it prompt
+        // ("password data for new item:" / "retype...") and read the secret from fd 0
+        // via readpassphrase(3) -- so the value travels over stdin, never on the
+        // command line. The prompt asks twice (enter + confirm), so we pipe the value
+        // TWICE; a single line fails the confirm and would store an empty secret. The
+        // item stays ACL-free (no biometry gate), so the no-prompt /usr/bin/security
+        // read path in getKeychainToken still works. Values are newline-free on darwin
+        // (assertValueStorable above), so each line carries the whole secret verbatim
+        // (no shell/quoting layer). `timeout` bounds the call so a context that cannot
+        // read the prompt fails loudly instead of hanging.
+        const sec = spawnSync('/usr/bin/security', buildAddGenericPasswordArgs(os.userInfo().username, item), {
+            input: `${value}\n${value}\n`,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 10_000,
+        });
         if (sec.status !== 0) {
             const msg = sec.stderr?.toString().trim();
             throw new Error(msg || `Failed to write keychain item '${item}'.`);

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;
+}>;