@phnx-labs/agents-cli 1.22.25 → 1.22.26

package/dist/lib/hooks/cache.js

@@ -505,6 +505,21 @@ if [ "$CACHE_STATUS" = miss ]; then
     if [ "$_in_backoff" -eq 0 ]; then
       # Fix 1: lockdir — only one background refresh runs at a time.
       LOCK_DIR="$CACHE_FILE.bg.lck"
+      # Fix 4 (RUSH-2259): reclaim a stale lock. The lock is released by the bg
+      # subshell's EXIT trap, but a hard kill (SIGKILL, OOM, reboot) skips the
+      # trap and orphans the dir — after which every future mkdir fails and bg
+      # refresh stops FOREVER while stale cache is served indefinitely. The dir
+      # mtime is fixed at mkdir time (the refresh writes elsewhere), so its age
+      # is the time the lock has been held; treat a lock older than LOCK_TTL_SEC
+      # as abandoned and remove it before locking. LOCK_TTL_SEC is set well above
+      # any real hook runtime so a live refresh is never reclaimed out from under.
+      LOCK_TTL_SEC=300
+      if [ -d "$LOCK_DIR" ]; then
+        _lock_mtime=$("$PY" -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$LOCK_DIR" 2>/dev/null || echo 0)
+        _lock_now_s=$(date +%s)
+        _lock_age=$((_lock_now_s - \${_lock_mtime:-0}))
+        [ "$_lock_age" -ge "$LOCK_TTL_SEC" ] && rm -rf "$LOCK_DIR" 2>/dev/null
+      fi
       if mkdir "$LOCK_DIR" 2>/dev/null; then
         tmp="$CACHE_FILE.new.$$"
         # Fix 3: background subshell captures and logs its own real exit code.

package/dist/lib/hosts/passthrough.d.ts

@@ -61,6 +61,29 @@ export declare function runFleetPassthrough(command: string, allArgs: string[],
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
  */
 export declare function maybeRunOnHost(command: string, allArgs: string[], opts?: FleetPassthroughOptions): Promise<boolean>;
+/**
+ * `--host` passthrough for a **standalone binary** whose command name is fixed by
+ * the binary itself (the `browser`/`computer` bins, `dist/browser.js` etc.) rather
+ * than being the first argv token.
+ *
+ * `agents browser … --host <box>` routes through {@link maybeRunOnHost} in
+ * index.ts, but the standalone `browser` binary never enters index.ts — so without
+ * this it dropped `--host` entirely (commander errored with `unknown option
+ * '--host'`). This wires the identical routing: it synthesizes the implicit command
+ * token (`browser`) at the front of the argv so the remote invocation builds as
+ * `agents browser …`, delegates to {@link maybeRunOnHost}, and returns `true` when
+ * it dispatched the run to a remote (the local program must then NOT parse).
+ *
+ * On a local / self-host fall-through it rewrites `process.argv` to the ORIGINAL
+ * args minus the routing flags — never the synthetic command token — so the
+ * standalone commander program parses cleanly and never sees an unknown `--host`.
+ * When no routing flag is present it leaves `process.argv` untouched (the common
+ * case), so an unrelated flag like `--no-tty` is never stripped from a purely local
+ * run.
+ *
+ * @param command the fixed command name the binary stands for (`'browser'`).
+ */
+export declare function maybeRunStandaloneOnHost(command: string, opts?: FleetPassthroughOptions): Promise<boolean>;
 /**
  * Run `agents <forwardedArgs>` on `host` over SSH, streaming its output, and
  * return the exit code. The single place the SSH hop is built, so every remote

package/dist/lib/hosts/passthrough.js

@@ -551,6 +551,51 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     });
     return true;
 }
+/**
+ * `--host` passthrough for a **standalone binary** whose command name is fixed by
+ * the binary itself (the `browser`/`computer` bins, `dist/browser.js` etc.) rather
+ * than being the first argv token.
+ *
+ * `agents browser … --host <box>` routes through {@link maybeRunOnHost} in
+ * index.ts, but the standalone `browser` binary never enters index.ts — so without
+ * this it dropped `--host` entirely (commander errored with `unknown option
+ * '--host'`). This wires the identical routing: it synthesizes the implicit command
+ * token (`browser`) at the front of the argv so the remote invocation builds as
+ * `agents browser …`, delegates to {@link maybeRunOnHost}, and returns `true` when
+ * it dispatched the run to a remote (the local program must then NOT parse).
+ *
+ * On a local / self-host fall-through it rewrites `process.argv` to the ORIGINAL
+ * args minus the routing flags — never the synthetic command token — so the
+ * standalone commander program parses cleanly and never sees an unknown `--host`.
+ * When no routing flag is present it leaves `process.argv` untouched (the common
+ * case), so an unrelated flag like `--no-tty` is never stripped from a purely local
+ * run.
+ *
+ * @param command the fixed command name the binary stands for (`'browser'`).
+ */
+export async function maybeRunStandaloneOnHost(command, opts) {
+    const rawArgs = process.argv.slice(2);
+    const hasRoutingFlag = flagValue(rawArgs, 'host', 'H') !== undefined ||
+        flagValue(rawArgs, 'device') !== undefined ||
+        flagValue(rawArgs, 'hosts') !== undefined ||
+        flagValue(rawArgs, 'devices') !== undefined;
+    // No routing flag → nothing to route or strip. Leave argv alone so a purely
+    // local run keeps every flag it passed.
+    if (!hasRoutingFlag)
+        return false;
+    // Keep --help/--version local (docs must work without a reachable host), mirroring
+    // index.ts's `helpOrVersionRequested` guard, but still strip the routing flags
+    // below so commander doesn't choke on them.
+    const helpOrVersion = rawArgs.some((a) => a === '--help' || a === '-h' || a === '--version' || a === '-V');
+    if (!helpOrVersion && (await maybeRunOnHost(command, [command, ...rawArgs], opts))) {
+        return true;
+    }
+    // Local / self-host fall-through (maybeRunOnHost may have rewritten process.argv
+    // with the synthetic command token). Rebuild argv from the original args minus
+    // the routing flags so the standalone program parses cleanly.
+    process.argv = [process.argv[0], process.argv[1], ...stripRoutingFlags(rawArgs, STRIP_SPECS)];
+    return false;
+}
 /**
  * Run `agents <forwardedArgs>` on `host` over SSH, streaming its output, and
  * return the exit code. The single place the SSH hop is built, so every remote

package/dist/lib/hosts/ready.d.ts

@@ -42,6 +42,8 @@ export interface ReadyProbe {
     version: string | null;
     /** Raw `agents view`/`list` output, for installed-agent checks. */
     view: string;
+    /** True when the ssh probe timed out before the sentinel arrived. */
+    timedOut?: boolean;
 }
 /**
  * Answer every readiness question in ONE ssh round-trip: reachable? (the login

package/dist/lib/hosts/ready.js

@@ -121,7 +121,11 @@ export function buildReadyProbeCommand(os) {
     return `bash -lc ${shellQuote(script)}`;
 }
 export function readyProbe(target, os) {
-    const r = sshExec(target, buildReadyProbeCommand(os), { timeoutMs: 20000 });
+    // Disable multiplexing: a stale control socket can hang the local ssh client
+    // until the timeout fires, just like sshExecAsync does for the same reason.
+    const r = sshExec(target, buildReadyProbeCommand(os), { timeoutMs: 20000, multiplex: false });
+    if (r.timedOut)
+        return { reachable: false, version: null, view: '', timedOut: true };
     return parseReadyProbe(r.stdout);
 }
 /** Pure parser for `readyProbe` output (unit-tested without ssh). */
@@ -146,6 +150,11 @@ export function viewHasAgent(view, agent) {
 export function ensureHostReady(host, opts) {
     const target = sshTargetFor(host);
     const probe = readyProbe(target, host.os ?? resolveRemoteOsSync(host.name));
+    if (probe.timedOut) {
+        throw new Error(`Host "${host.name}" (${target}) did not respond in time — the SSH probe timed out after 20 seconds. ` +
+            `The host may be slow to start a login shell (nvm/sdkman init, cold node startup). ` +
+            `Retry, or run \`agents ssh ${host.name} agents view\` to confirm manually.`);
+    }
     if (!probe.reachable) {
         throw new Error(`Host "${host.name}" (${target}) is not reachable over SSH. Check it's online and key auth works.`);
     }

package/dist/lib/hosts/reconnect.d.ts

@@ -48,7 +48,8 @@ export declare function backoffMs(attempt: number): number;
 export declare function reconnectStep(state: ReconnectState, outcome: ReconnectOutcome): ReconnectDecision;
 /** Human-readable notice shown before each reconnect wait. "13 seconds", not "12.8s". */
 export declare function reconnectNotice(sessionId: string, host: string, attempt: number, waitMs: number): string;
-/** Notice shown once the retry budget is spent. */
+/** Notice shown once the retry budget is spent. Hands back the one verb that
+ *  re-enters the terminal — attach the live pane if it survived, else resume. */
 export declare function exhaustedNotice(sessionId: string, host: string): string;
 /** Notice shown when a reattach stops on a remapped remote-side exit
  *  ({@link REMOTE_EXIT_255_REMAPPED} — a would-be-255 the remote command decided
@@ -75,13 +76,14 @@ export declare function remoteExitNotice(sessionId: string, host: string): strin
  */
 export declare function wrapRemoteExitCode(cmd: string): string;
 /**
- * The remote command a reattach runs — the peer's own reconnect verb
- * (`agents sessions focus <id> --local --attach-only`), wrapped by
- * {@link wrapRemoteExitCode} so a stray remote-origin 255 (from this command,
- * whatever produces it — see the file header) can never masquerade as a
- * network drop. Split out from {@link reattachRemoteSession} so it is
- * unit-tested without SSH — mirrors `remoteAgentsJsonCommand` in
- * lib/remote-agents-json.ts.
+ * The remote command a reattach runs — the peer's own recovery verb
+ * (`agents sessions focus <id> --local`), wrapped by {@link wrapRemoteExitCode}
+ * so a stray remote-origin 255 (from this command, whatever produces it — see the
+ * file header) can never masquerade as a network drop. No `--attach-only`: focus
+ * joins the live pane when it survived, else RESUMES the session in place, so a
+ * reattach landing after the pane died recovers the agent instead of dead-ending
+ * (RUSH-2085). Split out from {@link reattachRemoteSession} so it is unit-tested
+ * without SSH — mirrors `remoteAgentsJsonCommand` in lib/remote-agents-json.ts.
  */
 export declare function reattachRemoteCommand(sessionId: string): string;
 /**
@@ -89,10 +91,10 @@ export declare function reattachRemoteCommand(sessionId: string): string;
  * `agents sessions focus`. A fast, un-multiplexed preflight probe (`ssh … true`)
  * first establishes whether the host is actually reachable this attempt — that
  * `connected` bit, not the call duration, is what the retry policy keys on. Only on
- * a reachable host do we run the interactive attach (which carries no credentials —
- * the agent already runs on the peer — so it rides the normal transport). Returns
- * the ssh exit code (255 = dropped again / unreachable; 0 = clean detach; other =
- * session ended) plus whether this attempt connected.
+ * a reachable host do we run the interactive attach-or-resume (which carries no
+ * credentials — the agent already runs on the peer — so it rides the normal
+ * transport). Returns the ssh exit code (255 = dropped again / unreachable; 0 =
+ * clean detach; other = session ended) plus whether this attempt connected.
  */
 export declare function reattachRemoteSession(host: Host, sessionId: string): ReconnectOutcome;
 export interface ReconnectLoopOpts {

package/dist/lib/hosts/reconnect.js

@@ -11,9 +11,13 @@
  * SSH automatically, with bounded backoff, until the user detaches cleanly (the
  * remote returns 0) or the agent exits (the tmux session is gone; a non-255 code).
  *
- * The re-attach reuses the peer's OWN reconnect verb — `agents sessions focus <id>
- * --local --attach-only` joins the live local tmux pane there (no fork, no resumed
- * copy) — so there is no second re-attach implementation to keep in sync.
+ * The re-attach reuses the peer's OWN recovery verb — `agents sessions focus <id>
+ * --local` — which JOINS the live local tmux pane there (a second client, no fork)
+ * when it still exists, and RESUMES the session in place when the pane is already
+ * gone. Dropping `--attach-only` is deliberate: a reattach that lands after the
+ * remote pane died must not dead-end at a bare shell (the RUSH-2085 bug), it must
+ * fall through to resume so the user is put back into the agent. There is one
+ * re-attach implementation (the peer's focus) to keep in sync.
  *
  * **Why the budget refills on `connected`, not on call duration.** ssh returns 255
  * for BOTH "couldn't connect at all" and "connected, then the link dropped." A
@@ -31,29 +35,24 @@
  *
  * **255 from the REMOTE side should never be trusted as "the link dropped."**
  * `reattachRemoteSession`'s `connected` flag is set as soon as the fast preflight
- * probe succeeds — it says nothing about whether the interactive attach that
- * follows actually reattached a live pane. If the REMOTE command (`agents
- * sessions focus <id> --local --attach-only`) itself ever happened to exit 255
- * for a reason that has nothing to do with the ssh transport, `sshStream` would
- * return that same 255, `reconnectStep` couldn't tell it apart from a genuine
- * drop, and `connected: true` would refill the retry budget forever — "attempt
- * 1/N" printed on every single cycle, the terminal filling with aborted-TTY
- * escape-code garbage, `MAX_ATTEMPTS` never actually bounding anything.
+ * probe succeeds — it says nothing about whether the interactive attach/resume
+ * that follows actually put the user back into the agent. If the REMOTE command
+ * (`agents sessions focus <id> --local`) itself ever happened to exit 255 for a
+ * reason that has nothing to do with the ssh transport, `sshStream` would return
+ * that same 255, `reconnectStep` couldn't tell it apart from a genuine drop, and
+ * `connected: true` would refill the retry budget forever — "attempt 1/N" printed
+ * on every single cycle, the terminal filling with aborted-TTY escape-code
+ * garbage, `MAX_ATTEMPTS` never actually bounding anything.
  *
- * Two candidate producers of that scenario were investigated —
- * `refuseFallback`'s login-shell fallback (commands/go.ts) and `jumpTo`'s
- * nested remote-tmux hop — and both turned out to be UNREACHABLE through this
- * exact remote command: under `--local`, `gatherLiveTargets` never sets a
- * foreign `.machine` (go.ts:61), so `remote` is always `undefined` in both,
- * and neither branch can fire (the same reasoning that made an earlier,
- * narrower fix here dead code — see git history). So this fix does not close
- * a confirmed incident cause; what it closes is the underlying channel-level
- * flaw that would make *any* future remote-side 255 producer — reachable today
- * or not — indistinguishable from a real drop. {@link wrapRemoteExitCode} wraps
- * the entire remote command so that whatever exit code it decides on, a 255 is
- * remapped to {@link REMOTE_EXIT_255_REMAPPED} before `sshStream` ever sees it,
- * regardless of which internal branch produced it and regardless of the peer's
- * `agents` version (the remap happens in the shell wrapper THIS process sends).
+ * The resume fall-through only widens that surface — the peer's focus now runs a
+ * full recovery path (`resumeSessionInPlace` / `runOnPeer`) on a dead pane, any
+ * step of which could in principle exit 255 for its own reasons. So the channel-
+ * level defense is what matters, not an audit of which branch can fire:
+ * {@link wrapRemoteExitCode} wraps the entire remote command so that whatever exit
+ * code it decides on, a 255 is remapped to {@link REMOTE_EXIT_255_REMAPPED} before
+ * `sshStream` ever sees it, regardless of which internal branch produced it and
+ * regardless of the peer's `agents` version (the remap happens in the shell
+ * wrapper THIS process sends).
  *
  * This does NOT close every way `reconnectStep` can loop on a real transport
  * 255: a genuinely recurring LOCAL ssh failure (a fast-flapping link, an
@@ -111,9 +110,10 @@ export function reconnectNotice(sessionId, host, attempt, waitMs) {
     const when = secs <= 1 ? 'now' : `in ${secs} seconds`;
     return `\nConnection to ${host} dropped — the agent is still running there. Reconnecting to ${sessionId.slice(0, 8)} ${when} (attempt ${attempt}/${MAX_ATTEMPTS})…\n`;
 }
-/** Notice shown once the retry budget is spent. */
+/** Notice shown once the retry budget is spent. Hands back the one verb that
+ *  re-enters the terminal — attach the live pane if it survived, else resume. */
 export function exhaustedNotice(sessionId, host) {
-    return `\nCouldn't reconnect to ${host} after ${MAX_ATTEMPTS} attempts. The agent may still be running — reattach when the network is back:\n  agents sessions focus ${sessionId.slice(0, 8)}\n`;
+    return `\nCouldn't reconnect to ${host} after ${MAX_ATTEMPTS} attempts. The agent may still be running — get back in when the network is back:\n  agents reconnect ${sessionId.slice(0, 8)}\n`;
 }
 /** Notice shown when a reattach stops on a remapped remote-side exit
  *  ({@link REMOTE_EXIT_255_REMAPPED} — a would-be-255 the remote command decided
@@ -121,7 +121,7 @@ export function exhaustedNotice(sessionId, host) {
  *  {@link wrapRemoteExitCode}). Distinct from {@link exhaustedNotice}, which is
  *  only for a genuinely spent retry budget. */
 export function remoteExitNotice(sessionId, host) {
-    return `\nReattach to ${sessionId.slice(0, 8)} on ${host} ended (not a network drop) — check whether it's still live:\n  agents sessions ${sessionId.slice(0, 8)}\n`;
+    return `\nReattach to ${sessionId.slice(0, 8)} on ${host} ended (not a network drop) — get back in, or check whether it's still live:\n  agents reconnect ${sessionId.slice(0, 8)}\n`;
 }
 /**
  * Wrap `cmd` in `bash -lc` (the login-shell pattern `buildRemoteAgentsInvocation`
@@ -145,16 +145,17 @@ export function wrapRemoteExitCode(cmd) {
     return `bash -lc ${shellQuote(guarded)}`;
 }
 /**
- * The remote command a reattach runs — the peer's own reconnect verb
- * (`agents sessions focus <id> --local --attach-only`), wrapped by
- * {@link wrapRemoteExitCode} so a stray remote-origin 255 (from this command,
- * whatever produces it — see the file header) can never masquerade as a
- * network drop. Split out from {@link reattachRemoteSession} so it is
- * unit-tested without SSH — mirrors `remoteAgentsJsonCommand` in
- * lib/remote-agents-json.ts.
+ * The remote command a reattach runs — the peer's own recovery verb
+ * (`agents sessions focus <id> --local`), wrapped by {@link wrapRemoteExitCode}
+ * so a stray remote-origin 255 (from this command, whatever produces it — see the
+ * file header) can never masquerade as a network drop. No `--attach-only`: focus
+ * joins the live pane when it survived, else RESUMES the session in place, so a
+ * reattach landing after the pane died recovers the agent instead of dead-ending
+ * (RUSH-2085). Split out from {@link reattachRemoteSession} so it is unit-tested
+ * without SSH — mirrors `remoteAgentsJsonCommand` in lib/remote-agents-json.ts.
  */
 export function reattachRemoteCommand(sessionId) {
-    const inner = ['agents', 'sessions', 'focus', sessionId, '--local', '--attach-only']
+    const inner = ['agents', 'sessions', 'focus', sessionId, '--local']
         .map(shellQuote)
         .join(' ');
     return wrapRemoteExitCode(inner);
@@ -164,10 +165,10 @@ export function reattachRemoteCommand(sessionId) {
  * `agents sessions focus`. A fast, un-multiplexed preflight probe (`ssh … true`)
  * first establishes whether the host is actually reachable this attempt — that
  * `connected` bit, not the call duration, is what the retry policy keys on. Only on
- * a reachable host do we run the interactive attach (which carries no credentials —
- * the agent already runs on the peer — so it rides the normal transport). Returns
- * the ssh exit code (255 = dropped again / unreachable; 0 = clean detach; other =
- * session ended) plus whether this attempt connected.
+ * a reachable host do we run the interactive attach-or-resume (which carries no
+ * credentials — the agent already runs on the peer — so it rides the normal
+ * transport). Returns the ssh exit code (255 = dropped again / unreachable; 0 =
+ * clean detach; other = session ended) plus whether this attempt connected.
  */
 export function reattachRemoteSession(host, sessionId) {
     const target = sshTargetFor(host);

package/dist/lib/routines.js

@@ -14,7 +14,7 @@ import { getRoutinesDir, getSystemRoutinesDir, getRunsDir, ensureAgentsDir, getP
 import { safeJoin, isSafeSegmentName } from './paths.js';
 import { isSafeProjectName } from './projects.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
-import { ALL_AGENT_IDS } from './agents.js';
+import { ALL_AGENT_IDS, ROUTINE_AGENT_IDS } from './agents.js';
 import { machineId, normalizeHost } from './machine-id.js';
 import { resolveActor } from './actor.js';
 import { percentile } from './percentile.js';
@@ -600,6 +600,7 @@ export function validateJob(config) {
     const hasAgent = Boolean(config.agent && typeof config.agent === 'string');
     const hasWorkflow = Boolean(config.workflow && typeof config.workflow === 'string');
     const hasCommand = Boolean(config.command && typeof config.command === 'string');
+    const strategy = resolveHostStrategy(config);
     const set = [hasAgent, hasWorkflow, hasCommand].filter(Boolean).length;
     if (set === 0) {
         errors.push('exactly one of agent, workflow, or command is required');
@@ -613,6 +614,18 @@ export function validateJob(config) {
     if (hasAgent && config.agent && !ALL_AGENT_IDS.includes(config.agent)) {
         errors.push(`agent must be one of: ${ALL_AGENT_IDS.join(', ')}`);
     }
+    else if (hasAgent && config.agent && strategy === 'local' &&
+        !ROUTINE_AGENT_IDS.includes(config.agent)) {
+        // The local daemon only knows how to build a command for the agents in
+        // ROUTINE_AGENT_IDS (runner.ts's AGENT_COMMANDS table) — anything else is a
+        // real, installable agent (it passed the ALL_AGENT_IDS check above) but one
+        // the daemon can't fire itself, so reject it now instead of accepting the
+        // routine and failing at fire time (runner.ts buildJobCommand: "Unsupported
+        // agent for daemon jobs"). host/fleet/cloud placement dispatches through
+        // `agents run`/a cloud provider instead of this table, so they're exempt.
+        errors.push(`agent '${config.agent}' is not supported by the local routine daemon; use one of: ` +
+            `${ROUTINE_AGENT_IDS.join(', ')} (or set hostStrategy: host/fleet/cloud to run it elsewhere)`);
+    }
     if (hasWorkflow && config.workflow) {
         if (!/^[a-z0-9][a-z0-9_-]*$/.test(config.workflow)) {
             errors.push('workflow must be a lowercase alphanumeric name (hyphens and underscores allowed, e.g. autodev)');
@@ -662,7 +675,6 @@ export function validateJob(config) {
             errors.push(`hostStrategy must be one of: ${HOST_STRATEGIES.join(', ')}`);
         }
     }
-    const strategy = resolveHostStrategy(config);
     if (config.host !== undefined) {
         if (typeof config.host !== 'string' || config.host.trim() === '') {
             errors.push('host must be a non-empty machine name (a registered host, device, capability tag, or user@host)');

package/dist/lib/runner.d.ts

@@ -26,9 +26,6 @@ export interface RunResult {
 export declare class RoutineAlreadyRunningError extends Error {
     constructor(jobName: string, runId: string);
 }
-/** Agents the daemon can actually run, derived from the command table above
- * so the `--agent` help and any validation can never drift from it. */
-export declare const ROUTINE_AGENT_IDS: readonly string[];
 /** Stable working directory for routine children, independent of the daemon's launch cwd. */
 export declare function routineSpawnCwd(config: Pick<JobConfig, 'repo'>, configuredRoot?: string | undefined): string;
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */

package/dist/lib/runner.js

@@ -36,7 +36,7 @@ import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, formatNoHealthyAccountError, } from './rotate.js';
 import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
-import { isSelfUpdatingAgent } from './agents.js';
+import { isSelfUpdatingAgent, ROUTINE_AGENT_COMMANDS as AGENT_COMMANDS } from './agents.js';
 import { expandLocalHome, getProjectRoot } from './project-root.js';
 export class RoutineAlreadyRunningError extends Error {
     constructor(jobName, runId) {
@@ -98,19 +98,6 @@ function terminateRoutineTree(pid) {
     }
     catch { /* already exited */ }
 }
-/** CLI command templates per agent, with {prompt} as a placeholder. */
-const AGENT_COMMANDS = {
-    claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
-    codex: ['codex', 'exec', '{prompt}', '--json'],
-    gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
-    cursor: ['cursor-agent', '-p', '{prompt}', '--output-format', 'stream-json'],
-    kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
-    droid: ['droid', 'exec', '{prompt}', '-o', 'stream-json'],
-    muse: ['muse', 'exec', '{prompt}', '--json'],
-};
-/** Agents the daemon can actually run, derived from the command table above
- * so the `--agent` help and any validation can never drift from it. */
-export const ROUTINE_AGENT_IDS = Object.freeze(Object.keys(AGENT_COMMANDS));
 /**
  * Where each agent's transcript files live under an overlay HOME, mirroring
  * `SESSION_ROOT_SPECS` (session/discover.ts) — the CLI's own source of truth

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

@@ -0,0 +1,94 @@
+/**
+ * Serialize a resolved env map to `.env` lines that round-trip losslessly through
+ * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
+ * quote pair and takes the inner bytes verbatim (no unescaping), so any single-line
+ * value survives unchanged with no escaping. Newlines would break its line-based
+ * parse, so multi-line values are rejected rather than silently corrupted.
+ */
+export declare function bundleEnvToDotenv(env: Record<string, string>): string;
+/** Where the bundle should live ON THE REMOTE. */
+export type RemoteBackend = 'keychain' | 'file';
+/** A bundle read once, ready to push to any number of hosts. */
+export interface ResolvedBundleForPush {
+    /** key -> value. Never logged; only its KEY NAMES are ever surfaced. */
+    env: Record<string, string>;
+    /** The same values as a dotenv blob, shipped over ssh stdin (never argv). */
+    dotenv: string;
+    keyCount: number;
+}
+export interface PushBundleOptions {
+    remoteBackend: RemoteBackend;
+    /** Overwrite a key that already exists on the remote. */
+    force?: boolean;
+    /**
+     * Forwarded to the remote as the FIRST stdin line for the FILE backend only,
+     * and only when non-empty.
+     *
+     * Empty is the DEFAULT and the good path: the remote's file store then
+     * auto-provisions its own machine-local key (0600, `~/.agents/.secrets-key/`)
+     * and reads headlessly. Setting this keys the remote bundle under a shared
+     * off-disk secret instead — an opt-in, never a requirement. Requiring one is
+     * what pushed operators toward exporting the master key fleet-wide (RUSH-1968).
+     */
+    passphrase?: string;
+    /** Label for the audit trail — `export --host` vs `fleet apply`. */
+    operation: string;
+}
+export interface PushBundleResult {
+    ok: boolean;
+    host: string;
+    bundle: string;
+    keyCount: number;
+    /** One line for the caller to render. Never contains a secret value. */
+    message: string;
+}
+/**
+ * Read and resolve a bundle once, for pushing to one or more hosts.
+ *
+ * `agentOnly` + `keyMode: 'storage'` match what `export --host` has always
+ * passed: storage-shaped values, and the headless guard that fails fast rather
+ * than popping Touch ID inside an automated run.
+ */
+export declare function resolveBundleForPush(bundle: string, caller: string): ResolvedBundleForPush;
+/**
+ * WHICH transport a (backend, target-OS) pair selects, and the exact bytes it
+ * will send. One of four outcomes, and picking the wrong one is silent: a
+ * Windows target handed a POSIX `bash -lc` produces garbage, and a Windows
+ * target handed `--from -` hangs forever on a stdin the `agents.ps1` shim never
+ * forwards. Neither shows up as a failed ssh, so the selection is the thing
+ * worth pinning.
+ *
+ * Separated from execution so it is decidable without a network: the branch is
+ * chosen from the device registry alone, and `pushResolvedBundleToHost` below
+ * does nothing but run what this returns.
+ */
+export type PushTransport = 
+/** No supported command exists for this pair — fail loud, never a wrong path. */
+{
+    kind: 'refuse';
+    message: string;
+}
+/** A command sent over the raw ssh engine, with the .env on stdin. */
+ | {
+    kind: 'ssh';
+    remoteCmd: string;
+    input: string;
+}
+/** The OS-aware `agents secrets` wrapper, the READ inverse's own path. */
+ | {
+    kind: 'remote-secrets';
+    args: string[];
+    input: string;
+};
+/** Choose the transport for one push. Pure: registry read in, plan out. */
+export declare function planPushTransport(resolved: ResolvedBundleForPush, bundle: string, host: string, opts: PushBundleOptions): PushTransport;
+/**
+ * Push an already-resolved bundle to ONE host.
+ *
+ * Drives the remote's own `agents secrets import --from -`, so the values land
+ * in the remote's chosen backend and the .env is read off ssh stdin rather than
+ * parsed by a remote shell. `import` auto-creates the bundle.
+ */
+export declare function pushResolvedBundleToHost(resolved: ResolvedBundleForPush, bundle: string, host: string, opts: PushBundleOptions): PushBundleResult;
+/** Resolve and push in one call — for a single host. */
+export declare function pushBundleToHost(bundle: string, host: string, opts: PushBundleOptions): PushBundleResult;