@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/commands/secrets.d.ts

@@ -7,7 +7,16 @@
  */
 import { type Command } from 'commander';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
+import { quoteWin32ExecArg } from '../lib/platform/index.js';
+import { type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
 export { SSH_TARGET_RE, assertValidSshTarget };
+/**
+ * Build the child environment for `agents secrets exec`. Strips
+ * loader/interpreter hijack vars (matching agent spawns in exec.ts) and never
+ * forwards AGENTS_SECRETS_PASSPHRASE — the master decryption key must not reach
+ * the executed command.
+ */
+export declare function buildSecretsExecEnv(parentEnv: NodeJS.ProcessEnv, secretEnv: Record<string, string>): NodeJS.ProcessEnv;
 /**
  * Serialize a resolved env map to `.env` lines that round-trip losslessly through
  * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
@@ -16,25 +25,29 @@ export { SSH_TARGET_RE, assertValidSshTarget };
  * parse, so multi-line values are rejected rather than silently corrupted.
  */
 export declare function bundleEnvToDotenv(env: Record<string, string>): string;
+/** The POLICY column for `secrets list`: the prompt policy, plus a "Nh left"
+ * hint when a `daily` bundle is currently held by the secrets-agent. `held`
+ * maps bundle name → expiry epoch-ms (from agentStatus()). */
+export declare function renderPolicyCol(b: SecretsBundle, held?: Map<string, number>): string;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;
+/** Validate a prompt-policy value, throwing a clear message on a bad one (the
+ * caller's try/catch renders it and exits). Accepts the legacy `biometry` /
+ * `session` / `none` tokens as aliases for `always` / `daily` / `never` so older
+ * flags and scripts keep working. `never`/`none` is the no-biometry-ACL tier —
+ * accepted here, then gated behind a loud confirmation in the command layer. */
+export declare function parsePolicyOpt(raw: string | undefined): SecretsPolicy;
 /**
- * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
- * `spawn(..., { shell: true })` on win32 (`agents secrets exec`). cmd.exe does
- * NO quoting of its own, so an unquoted arg with a space is split into several
- * args, and a cmd metacharacter (`&|<>()^`) would be interpreted by the shell.
- * We wrap any arg with whitespace, a quote, or a metacharacter in double quotes
- * and escape embedded quotes / trailing backslashes per the CommandLineToArgvW
- * rules, so the *child's* argv parse reconstructs the original argument.
- *
- * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
- * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
- * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
- * `agents secrets exec` runs a caller-supplied command against a bundle the
- * caller owns, so caller-controlled `%`/`!` is not a privilege boundary. If that
- * ever changes (exec'ing an untrusted command line), route through a shell that
- * disables expansion rather than relying on this quoter. An empty arg becomes
- * `""`. Exported for tests. No-ops on non-Windows (the caller only invokes it
- * under `process.platform === 'win32'`).
+ * Gate a create/switch to the `never` prompt-policy behind an explicit,
+ * deliberate acknowledgement — it is the least-safe tier (no user-presence
+ * check on any read). Returns:
+ *   - `'ok'`    — not `never`, or already acknowledged via `--i-understand`.
+ *   - `'prompt'` — interactive shell: caller must run a loud confirm prompt.
+ * Throws in a non-interactive shell when the flag is absent, so a headless
+ * `create --policy never` can't silently downgrade a bundle's protection.
  */
-export declare function quoteWin32ExecArg(arg: string): string;
+export declare function assertNeverPolicyAcknowledged(policy: SecretsPolicy | undefined, opts: {
+    iUnderstand?: boolean;
+    interactive: boolean;
+}): 'ok' | 'prompt';
+export { quoteWin32ExecArg };

package/dist/commands/secrets.js

@@ -10,8 +10,10 @@ import chalk from 'chalk';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import * as fs from 'fs';
 import { SSH_TARGET_RE, assertValidSshTarget, sshExec } from '../lib/ssh-exec.js';
+import { quoteWin32ExecArg, composeWin32CommandLine } from '../lib/platform/index.js';
+import { ensureDaemonStarted } from '../lib/daemon.js';
 import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, resolveSshTarget, } from '../lib/secrets/remote.js';
-import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
+import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { DEFAULT_TTL_MS, agentLoad, agentLock, agentStatus, ensureAgentRunning, installSecretsAgentService, runAgentLoadFromStdin, runSecretsAgent, secretsAgentServiceInstalled, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
@@ -139,6 +141,31 @@ function readStdinSync() {
 // SSH target validation is defined canonically in src/lib/ssh-exec.ts and
 // re-exported here for back-compat with existing importers of these symbols.
 export { SSH_TARGET_RE, assertValidSshTarget };
+/**
+ * Build the child environment for `agents secrets exec`. Strips
+ * loader/interpreter hijack vars (matching agent spawns in exec.ts) and never
+ * forwards AGENTS_SECRETS_PASSPHRASE — the master decryption key must not reach
+ * the executed command.
+ */
+export function buildSecretsExecEnv(parentEnv, secretEnv) {
+    const env = { ...sanitizeProcessEnv(parentEnv), ...secretEnv };
+    delete env.AGENTS_SECRETS_PASSPHRASE;
+    return env;
+}
+/**
+ * Resolve the CLI version for the MCP server's `serverInfo.version`. package.json
+ * sits at the repo root — two levels up from both `src/commands/` (bun/tsx dev)
+ * and `dist/commands/` (built). Cosmetic only, so any failure falls back cleanly.
+ */
+function getCliVersion() {
+    try {
+        const pkgPath = new URL('../../package.json', import.meta.url);
+        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
 /** POSIX single-quote a string for safe interpolation into a remote shell command. */
 function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
@@ -264,7 +291,10 @@ function compactRemaining(expiresAt) {
 /** The POLICY column for `secrets list`: the prompt policy, plus a "Nh left"
  * hint when a `daily` bundle is currently held by the secrets-agent. `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
-function renderPolicyCol(b, held) {
+export function renderPolicyCol(b, held) {
+    // `never` is loud on purpose — it's the only tier with no user-presence gate.
+    if (bundlePolicy(b) === 'never')
+        return chalk.red.bold('never · NO ACL');
     if (bundlePolicy(b) === 'always')
         return chalk.yellow('always ask');
     const exp = held?.get(b.name);
@@ -505,7 +535,7 @@ export function registerSecretsCommands(program) {
         { title: 'Agent commands', names: ['start', 'stop', 'unlock', 'lock', 'status', 'policy'] },
         { title: 'Raw item commands', names: ['get', 'set'] },
         { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
-        { title: 'Utilities', names: ['exec', 'generate', 'migrate-acl'] },
+        { title: 'Utilities', names: ['exec', 'mcp', 'generate', 'migrate-acl'] },
     ]);
     cmd
         .command('list')
@@ -588,9 +618,14 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.yellow('allow_exec: true'));
             if (bundle.backend === 'file')
                 console.log(chalk.gray('backend: file (passphrase-encrypted; reads need AGENTS_SECRETS_PASSPHRASE, no Touch ID)'));
-            console.log(bundlePolicy(bundle) === 'daily'
-                ? chalk.gray('policy: daily (ask once, then held ~24h until screen-lock / sleep / logout)')
-                : chalk.gray('policy: always (asks for Touch ID every time — never auto-held)'));
+            if (bundlePolicy(bundle) === 'never') {
+                console.log(chalk.red.bold('policy: never — NO biometry ACL; reads are silent (no Touch ID, no user-presence check). Automation-only.'));
+            }
+            else {
+                console.log(bundlePolicy(bundle) === 'daily'
+                    ? chalk.gray('policy: daily (ask once, then held ~24h until screen-lock / sleep / logout)')
+                    : chalk.gray('policy: always (asks for Touch ID every time — never auto-held)'));
+            }
             if (bundle.created_at)
                 console.log(chalk.gray(`created_at: ${bundle.created_at} (${humanAge(bundle.created_at)})`));
             if (bundle.updated_at)
@@ -712,8 +747,9 @@ export function registerSecretsCommands(program) {
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--policy <policy>', 'prompt policy: daily (default, ask once a day) or always (ask every time)')
+        .option('--policy <policy>', 'prompt policy: daily (default, ask once a day), always (ask every time), or never (silent, NO biometry ACL — needs --i-understand)')
         .addOption(new Option('--tier <policy>', 'deprecated alias for --policy').hideHelp())
+        .option('--i-understand', 'Confirm creating a "never"-policy bundle (no biometry ACL) without an interactive prompt')
         .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
         .option('--force', 'Overwrite an existing bundle')
         .action(async (name, opts) => {
@@ -729,6 +765,13 @@ export function registerSecretsCommands(program) {
                 console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
                 process.exit(1);
             }
+            // The `never` tier is the least-safe option — gate it loudly. Throws in a
+            // headless shell without --i-understand; prompts otherwise.
+            const ack = assertNeverPolicyAcknowledged(policy, { iUnderstand: opts.iUnderstand, interactive: isInteractiveTerminal() });
+            if (ack === 'prompt' && !(await confirmNeverPolicyInteractive(resolvedName))) {
+                console.error(chalk.yellow('Aborted.'));
+                return;
+            }
             const bundle = {
                 name: resolvedName,
                 description: opts.description,
@@ -738,11 +781,16 @@ export function registerSecretsCommands(program) {
                 vars: {},
             };
             writeBundle(bundle);
-            const tags = [
-                bundlePolicy(bundle) === 'daily' ? 'policy: daily' : 'policy: always ask',
-                backend === 'file' ? 'backend: file' : null,
-            ].filter(Boolean);
+            const policyTag = bundlePolicy(bundle) === 'daily'
+                ? 'policy: daily'
+                : bundlePolicy(bundle) === 'always'
+                    ? 'policy: always ask'
+                    : 'policy: never (NO biometry ACL)';
+            const tags = [policyTag, backend === 'file' ? 'backend: file' : null].filter(Boolean);
             console.log(chalk.green(`Bundle '${resolvedName}' created (${tags.join(', ')}).`));
+            if (bundlePolicy(bundle) === 'never') {
+                console.log(chalk.red('Stored without biometry protection — reads are silent. Automation-only; rotate anything sensitive out of it.'));
+            }
             if (backend === 'file') {
                 console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted under AGENTS_SECRETS_PASSPHRASE (no Touch ID).'));
             }
@@ -876,7 +924,7 @@ export function registerSecretsCommands(program) {
                 secretValue = await promptForSecret(`Enter value for ${resolvedBundleName}.${resolvedKey}`);
             }
             const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
-            bundleItemStore(bundle.backend).set(item, secretValue);
+            bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' }).set(item, secretValue);
             bundle.vars[resolvedKey] = keychainRef(resolvedKey);
             applyMeta();
             writeBundle(bundle);
@@ -1122,7 +1170,7 @@ Examples:
                     vars: {},
                 };
             }
-            const store = bundleItemStore(bundle.backend);
+            const store = bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' });
             let added = 0;
             let skipped = 0;
             if (opts.from1password) {
@@ -1332,6 +1380,8 @@ Examples:
         .command('exec <bundle> [command...]')
         .description('Run a command with the bundle\'s secrets injected into the environment (use --host to resolve the bundle from a remote machine, ephemerally)')
         .option('--host <target>', 'Resolve <bundle> on a remote host over SSH and inject it (ephemeral — never stored on this machine)')
+        .option('--keys <keys>', 'Inject only this comma-separated subset of keys (e.g. KEY1,KEY2). Missing keys are an error.')
+        .option('--allow-expired', 'Inject keys even if their expiry date has passed (overrides the pre-run expiry abort).')
         .allowUnknownOption()
         .action(async (bundleName, commandParts, execOpts) => {
         try {
@@ -1340,28 +1390,42 @@ Examples:
                 process.exit(1);
             }
             const [cmd, ...args] = commandParts;
+            const keysSubset = execOpts.keys
+                ? execOpts.keys.split(',').map((k) => k.trim()).filter(Boolean)
+                : undefined;
             let secretEnv;
             if (execOpts.host) {
+                // Least-privilege flags do not yet cross the SSH resolver —
+                // silently applying them would inject the full remote env or an
+                // expired key. Fail loud so the user can drop the flag or run
+                // locally instead.
+                const { assertRemoteBundleFlagsUnsupported } = await import('../lib/secrets/bundles.js');
+                assertRemoteBundleFlagsUnsupported(bundleName, execOpts.host, { keys: keysSubset, allowExpired: execOpts.allowExpired }, { keysFlag: '--keys', allowExpiredFlag: '--allow-expired' });
                 secretEnv = await remoteResolveEnv(await resolveSshTarget(execOpts.host), bundleName);
             }
             else {
                 const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
-                secretEnv = readAndResolveBundleEnv(bundleName, { caller: `command ${cmd}` }).env;
+                secretEnv = readAndResolveBundleEnv(bundleName, {
+                    caller: `command ${cmd}`,
+                    keys: keysSubset,
+                    allowExpired: execOpts.allowExpired,
+                }).env;
             }
             const { spawn } = await import('child_process');
             // On Windows, spawn without a shell ENOENTs for `.cmd`/`.bat` launchers
             // (npm, yarn, most JS CLIs) and shell built-ins, so we set shell:true.
             // With shell:true Node hands cmd.exe a single command line with NO quoting
-            // of its own, so args containing spaces or cmd metacharacters must be
-            // quoted here (quoteWin32ExecArg) or they'd be split. See that helper for
+            // of its own. Compose that line ourselves (composeWin32CommandLine quotes
+            // every token) and pass an EMPTY args array so Node never concatenates the
+            // user-supplied args unescaped (DEP0190 + injection). See that helper for
             // the cmd.exe %VAR%/!VAR! expansion caveat.
             const useShell = process.platform === 'win32';
-            const spawnCmd = useShell ? quoteWin32ExecArg(cmd) : cmd;
-            const spawnArgs = useShell ? args.map(quoteWin32ExecArg) : args;
+            const spawnCmd = useShell ? composeWin32CommandLine(cmd, args) : cmd;
+            const spawnArgs = useShell ? [] : args;
             const proc = spawn(spawnCmd, spawnArgs, {
                 stdio: 'inherit',
                 shell: useShell,
-                env: { ...process.env, ...secretEnv },
+                env: buildSecretsExecEnv(process.env, secretEnv),
             });
             proc.on('close', (code) => process.exit(code ?? 0));
             proc.on('error', (err) => {
@@ -1376,6 +1440,17 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('mcp')
+        .description('Run a stdio MCP server exposing get_secret(bundle, key) — hand credentials to an MCP-speaking agent by name at call time, never through the child process environment')
+        .action(async () => {
+        // JIT credential delivery (#333): unlike `secrets exec`, which bakes every
+        // resolved value into the child's env, this speaks MCP over stdio so a
+        // framework requests one secret at a time and the raw value never enters
+        // process.env. stdout is the JSON-RPC channel — nothing else may print there.
+        const { runSecretsMcpServer } = await import('../lib/secrets/mcp.js');
+        await runSecretsMcpServer({ version: getCliVersion() });
+    });
     cmd
         .command('generate [length]')
         .description('Generate a random password')
@@ -1478,6 +1553,12 @@ Examples:
             console.error(chalk.red('Could not start the secrets-agent.'));
             process.exit(1);
         }
+        // #415: the daemon should be always-on for any background need, not only
+        // after `routines add`. A user who only ever unlocks secrets still gets
+        // the daemon installed + running here. `ensureAgentRunning` above only
+        // brings up the standalone secrets broker, not the daemon. Idempotent
+        // (single-instance start lock, #414) and best-effort — never blocks unlock.
+        ensureDaemonStarted();
         let loaded = 0;
         for (const name of targets) {
             try {
@@ -1547,8 +1628,9 @@ Examples:
     cmd
         .command('policy <bundle> [policy]')
         .alias('tier')
-        .description("Show or set a bundle's prompt policy: daily (default, ask once a day) or always (ask every time).")
-        .action((bundleName, policyArg) => {
+        .description("Show or set a bundle's prompt policy: daily (default, ask once a day), always (ask every time), or never (silent, NO biometry ACL).")
+        .option('--i-understand', 'Confirm switching to the "never" policy (no biometry ACL) without an interactive prompt')
+        .action(async (bundleName, policyArg, opts) => {
         try {
             const bundle = readBundle(bundleName);
             if (policyArg === undefined) {
@@ -1556,15 +1638,24 @@ Examples:
                 return;
             }
             const next = parsePolicyOpt(policyArg);
+            // Switching to `never` drops the biometry ACL — gate it exactly like create.
+            const ack = assertNeverPolicyAcknowledged(next, { iUnderstand: opts.iUnderstand, interactive: isInteractiveTerminal() });
+            if (ack === 'prompt' && !(await confirmNeverPolicyInteractive(bundle.name))) {
+                console.error(chalk.yellow('Aborted.'));
+                return;
+            }
             bundle.policy = next;
             writeBundle(bundle);
             console.log(chalk.green(`${bundle.name} policy set to ${next}.`));
             if (next === 'daily') {
                 console.log(chalk.gray('Held by the secrets-agent for ~24h after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));
             }
-            else {
+            else if (next === 'always') {
                 console.log(chalk.gray('Asks for Touch ID every time — never auto-held.'));
             }
+            else {
+                console.log(chalk.red('Stored without biometry protection — reads are silent. Automation-only.'));
+            }
         }
         catch (err) {
             console.error(chalk.red(err.message));
@@ -1613,23 +1704,52 @@ Examples:
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
 }
-/** Validate a prompt-policy value, exiting with a clear message on a bad one.
- * Accepts the legacy `biometry`/`session` tokens as aliases for `always`/`daily`
- * so older flags and scripts keep working. `never`/`none` (no biometry ACL) is
- * rejected explicitly — it needs a separate signed-helper change (see
- * https://github.com/phnx-labs/agents-cli/issues/421). */
-function parsePolicyOpt(raw) {
+/** Validate a prompt-policy value, throwing a clear message on a bad one (the
+ * caller's try/catch renders it and exits). Accepts the legacy `biometry` /
+ * `session` / `none` tokens as aliases for `always` / `daily` / `never` so older
+ * flags and scripts keep working. `never`/`none` is the no-biometry-ACL tier —
+ * accepted here, then gated behind a loud confirmation in the command layer. */
+export function parsePolicyOpt(raw) {
     const v = (raw ?? 'always').toLowerCase();
     if (v === 'always' || v === 'biometry')
         return 'always';
     if (v === 'daily' || v === 'session')
         return 'daily';
-    if (v === 'never' || v === 'none') {
-        console.error(chalk.red("policy 'never' (no biometry ACL) is not available yet — see https://github.com/phnx-labs/agents-cli/issues/421. Use 'always' or 'daily'."));
-        process.exit(1);
+    if (v === 'never' || v === 'none')
+        return 'never';
+    throw new Error(`Invalid policy '${raw}'. Use 'always', 'daily', or 'never'.`);
+}
+/**
+ * Gate a create/switch to the `never` prompt-policy behind an explicit,
+ * deliberate acknowledgement — it is the least-safe tier (no user-presence
+ * check on any read). Returns:
+ *   - `'ok'`    — not `never`, or already acknowledged via `--i-understand`.
+ *   - `'prompt'` — interactive shell: caller must run a loud confirm prompt.
+ * Throws in a non-interactive shell when the flag is absent, so a headless
+ * `create --policy never` can't silently downgrade a bundle's protection.
+ */
+export function assertNeverPolicyAcknowledged(policy, opts) {
+    if (policy !== 'never')
+        return 'ok';
+    if (opts.iUnderstand)
+        return 'ok';
+    if (!opts.interactive) {
+        throw new Error("Refusing to set the 'never' prompt-policy without confirmation. This tier stores " +
+            'the bundle WITHOUT the biometry access control: every read is silent, with no Touch ID ' +
+            'and no user-presence check — any code running as you can read it. Re-run with ' +
+            '--i-understand to confirm you want an unprotected, automation-only bundle.');
     }
-    console.error(chalk.red(`Invalid policy '${raw}'. Use 'always' or 'daily'.`));
-    process.exit(1);
+    return 'prompt';
+}
+/** Loud confirm prompt shown before creating/switching to `never` in a TTY.
+ * Returns true to proceed. Kept separate from assertNeverPolicyAcknowledged so
+ * the decision logic stays pure and unit-testable. */
+async function confirmNeverPolicyInteractive(bundleName) {
+    console.error(chalk.red.bold('WARNING: policy "never" stores this bundle with NO biometry ACL.'));
+    console.error(chalk.red(`Reads of '${bundleName}' will be fully silent — no Touch ID, no user-presence check.`));
+    console.error(chalk.yellow('Use it only for low-sensitivity, automation-only credentials.'));
+    const { confirm } = await import('@inquirer/prompts');
+    return confirm({ message: `Store '${bundleName}' WITHOUT biometry protection?`, default: false });
 }
 /** Validate a --backend value, exiting with a clear message on a bad one. */
 function parseBackendOpt(raw) {
@@ -1653,48 +1773,9 @@ function humanRemaining(expiresAt) {
     const days = Math.round(hours / 24);
     return `locks in ${days} day${days === 1 ? '' : 's'}`;
 }
-/**
- * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
- * `spawn(..., { shell: true })` on win32 (`agents secrets exec`). cmd.exe does
- * NO quoting of its own, so an unquoted arg with a space is split into several
- * args, and a cmd metacharacter (`&|<>()^`) would be interpreted by the shell.
- * We wrap any arg with whitespace, a quote, or a metacharacter in double quotes
- * and escape embedded quotes / trailing backslashes per the CommandLineToArgvW
- * rules, so the *child's* argv parse reconstructs the original argument.
- *
- * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
- * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
- * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
- * `agents secrets exec` runs a caller-supplied command against a bundle the
- * caller owns, so caller-controlled `%`/`!` is not a privilege boundary. If that
- * ever changes (exec'ing an untrusted command line), route through a shell that
- * disables expansion rather than relying on this quoter. An empty arg becomes
- * `""`. Exported for tests. No-ops on non-Windows (the caller only invokes it
- * under `process.platform === 'win32'`).
- */
-export function quoteWin32ExecArg(arg) {
-    if (arg.length > 0 && !/[\s"&|<>()^]/.test(arg))
-        return arg;
-    let result = '"';
-    let backslashes = 0;
-    for (const ch of arg) {
-        if (ch === '\\') {
-            backslashes += 1;
-            continue;
-        }
-        if (ch === '"') {
-            // Double the run of backslashes, then escape this quote.
-            result += '\\'.repeat(backslashes * 2 + 1) + '"';
-            backslashes = 0;
-            continue;
-        }
-        result += '\\'.repeat(backslashes) + ch;
-        backslashes = 0;
-    }
-    // Trailing backslashes precede the closing quote → must be doubled.
-    result += '\\'.repeat(backslashes * 2) + '"';
-    return result;
-}
+// `quoteWin32ExecArg` now lives in lib/platform/exec.ts (shared with the agent
+// run/shim spawn paths); re-exported here for the colocated secrets tests.
+export { quoteWin32ExecArg };
 /**
  * Copy text to the system clipboard, cross-platform.
  * macOS: `pbcopy`. Windows: `clip`. Linux: tries `wl-copy` (Wayland), then

package/dist/commands/serve.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agents serve` — read-only local web companion.
+ *
+ * Boots a localhost-only (127.0.0.1) HTTP + SSE server that renders a live
+ * dashboard of team status + per-worktree diffs, scheduled routines, and cloud
+ * tasks. Everything is a viewer over data other commands already own — there
+ * are no mutation endpoints. See src/lib/serve/.
+ */
+import type { Command } from 'commander';
+export declare function registerServeCommand(program: Command): void;

package/dist/commands/serve.js

@@ -0,0 +1,37 @@
+import chalk from 'chalk';
+import { startServeServer, DEFAULT_SERVE_PORT, SERVE_HOST } from '../lib/serve/server.js';
+export function registerServeCommand(program) {
+    program
+        .command('serve')
+        .description('Read-only local web companion: team diffs, routines, and cloud status (binds 127.0.0.1 only).')
+        .option('-p, --port <n>', `Port to bind on ${SERVE_HOST}`, String(DEFAULT_SERVE_PORT))
+        .option('--interval <ms>', 'SSE refresh cadence in milliseconds', '3000')
+        .action(async (opts) => {
+        const port = parseInt(opts.port ?? '', 10) || DEFAULT_SERVE_PORT;
+        const intervalMs = parseInt(opts.interval ?? '', 10) || 3000;
+        try {
+            const { server, port: bound } = await startServeServer(port, {
+                cwd: process.cwd(),
+                intervalMs,
+            });
+            const url = `http://${SERVE_HOST}:${bound}`;
+            console.log(`${chalk.green('agents serve')} ${chalk.dim('→')} ${chalk.cyan(url)}`);
+            console.log(chalk.dim('read-only · localhost only · Ctrl-C to stop'));
+            const shutdown = () => {
+                server.close(() => process.exit(0));
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+        }
+        catch (err) {
+            const msg = String(err?.message ?? err);
+            if (msg.includes('EADDRINUSE')) {
+                console.error(chalk.red(`Port ${port} is already in use. Pass --port <n> to pick another.`));
+            }
+            else {
+                console.error(chalk.red(`Could not start serve: ${msg}`));
+            }
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/sessions-inject.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents sessions inject <sessionId> <text>` — deliver text into the terminal a
+ * running session lives in. The CLI face of the Terminal Engine's Gap 2 primitive
+ * (`injectIntoTerminal`, src/lib/terminal/inject.ts), so a native watchdog
+ * (RUSH-1415) can shell out to nudge a stalled agent with "continue".
+ *
+ * Resolution: find the active session by id, map its `provenance.reply` rail
+ * (provenance.ts:47) to an engine `InjectTarget` and inject. Today only tmux rails
+ * are externally addressable; `--pane`/`--pty` target a backend directly when the
+ * handle is already known (skipping the session lookup).
+ */
+import type { Command } from 'commander';
+/** Attach the `inject` subcommand to an existing `sessions` command. */
+export declare function registerSessionsInjectCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-inject.js

@@ -0,0 +1,111 @@
+/**
+ * `agents sessions inject <sessionId> <text>` — deliver text into the terminal a
+ * running session lives in. The CLI face of the Terminal Engine's Gap 2 primitive
+ * (`injectIntoTerminal`, src/lib/terminal/inject.ts), so a native watchdog
+ * (RUSH-1415) can shell out to nudge a stalled agent with "continue".
+ *
+ * Resolution: find the active session by id, map its `provenance.reply` rail
+ * (provenance.ts:47) to an engine `InjectTarget` and inject. Today only tmux rails
+ * are externally addressable; `--pane`/`--pty` target a backend directly when the
+ * handle is already known (skipping the session lookup).
+ */
+import chalk from 'chalk';
+import { getActiveSessions } from '../lib/session/active.js';
+import { injectTargetFromReplyRail } from '../lib/session/inject.js';
+import { injectIntoTerminal } from '../lib/terminal/index.js';
+import { setHelpSections } from '../lib/help.js';
+/** Resolve a session id (short or full) to an addressable terminal target. */
+async function resolveTarget(sessionId) {
+    const sessions = await getActiveSessions();
+    const match = sessions.find((s) => s.sessionId === sessionId || (s.sessionId != null && s.sessionId.startsWith(sessionId)));
+    if (!match)
+        return { target: null, reason: `No active session matches "${sessionId}".` };
+    const rail = match.provenance?.reply;
+    if (!rail) {
+        return {
+            target: null,
+            reason: `Session "${sessionId}" has no addressable reply rail (not running under tmux). Relaunch it under a tmux/pty rail to inject.`,
+        };
+    }
+    const target = injectTargetFromReplyRail(rail);
+    if (!target)
+        return { target: null, reason: `Session "${sessionId}" reply rail is not injectable.` };
+    return { target };
+}
+async function runInject(sessionId, text, options) {
+    // Direct-target shortcuts skip the session lookup — the watchdog often already
+    // holds the pane id or pty session it wants to type into.
+    let target = null;
+    if (options.pty) {
+        target = { backend: 'pty', id: options.pty };
+    }
+    else if (options.pane) {
+        target = { backend: 'tmux', pane: options.pane, socket: options.socket };
+    }
+    else {
+        const resolved = await resolveTarget(sessionId);
+        if (!resolved.target) {
+            if (options.json)
+                console.log(JSON.stringify({ ok: false, error: resolved.reason }));
+            else
+                console.error(chalk.red(resolved.reason));
+            process.exit(1);
+        }
+        target = resolved.target;
+    }
+    const res = await injectIntoTerminal(target, text, {
+        enter: options.enter !== false,
+        combined: options.combined,
+        socket: options.socket,
+        host: options.host,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(res));
+    }
+    else if (res.ok) {
+        console.log(chalk.green(`Injected into ${res.backend} (${res.writes} write${res.writes === 1 ? '' : 's'}).`));
+    }
+    else {
+        console.error(chalk.red(res.error ?? 'injection failed'));
+    }
+    if (!res.ok)
+        process.exit(1);
+}
+/** Attach the `inject` subcommand to an existing `sessions` command. */
+export function registerSessionsInjectCommand(sessionsCmd) {
+    const injectCmd = sessionsCmd
+        .command('inject <sessionId> <text>')
+        .description('Deliver text (+ Enter) into the terminal a running session lives in — nudge a stalled agent.')
+        .option('--pane <id>', 'Target a tmux pane id directly (e.g. %3), skipping session lookup')
+        .option('--pty <id>', 'Target an agents-pty session id directly, skipping session lookup')
+        .option('--socket <path>', 'tmux socket path (defaults to the session/shared socket)')
+        .option('--host <target>', 'Deliver on a remote host over SSH (tmux/AppleScript backends)')
+        .option('--no-enter', 'Send only the text, without a trailing Enter')
+        .option('--combined', 'Fuse text + Enter into ONE write (default: two writes, Ink-TUI safe)')
+        .option('--json', 'Output the InjectResult as JSON');
+    setHelpSections(injectCmd, {
+        examples: `
+      # Nudge a stalled agent by session id (resolves its tmux pane)
+      agents sessions inject a1b2c3d4 "continue"
+
+      # Target a tmux pane directly (what a watchdog already holds)
+      agents sessions inject _ "continue" --pane %3 --socket /tmp/agents/tmux.sock
+
+      # Type into an agents-pty session without submitting
+      agents sessions inject _ "ls" --pty $SID --no-enter
+    `,
+        notes: `
+      - Ink-TUI Enter semantics: by default the text and Enter are two separate
+        writes, which is what Claude's Ink TUI needs. --combined fuses them.
+      - Only sessions running under a tmux pane are addressable by id today
+        (provenance.ts reply rails). Use --pane/--pty for direct targeting.
+      - Built on the Terminal Engine (src/lib/terminal): --host runs the tmux /
+        AppleScript spec over the same SSH transport the launch engine uses.
+    `,
+    });
+    // The parent `sessions` command also defines --json, so it binds there;
+    // optsWithGlobals() merges parent + subcommand options so --json is honored.
+    injectCmd.action(async (sessionId, text, _options, command) => {
+        await runInject(sessionId, text, command.optsWithGlobals());
+    });
+}

package/dist/commands/sessions-picker.d.ts

@@ -5,6 +5,8 @@ export interface PickedSession {
 }
 export interface SessionPickerConfig {
     message: string;
+    /** Dim hint line shown under the header (filters/flags tip). */
+    subtitle?: string;
     sessions: SessionMeta[];
     filter: (query: string) => SessionMeta[];
     labelFor: (s: SessionMeta, query: string) => string;