@phnx-labs/agents-cli 1.20.67 → 1.20.69

package/dist/lib/runner.js

@@ -17,7 +17,7 @@ import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, checkJobDeviceEligibility, } from './routines.js';
+import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, checkJobDeviceEligibility, finalizeRunMeta, } from './routines.js';
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
@@ -529,9 +529,8 @@ export async function executeJob(config, deps) {
             agent: effectiveAgent,
             version: primaryVersion,
         }, deps);
-        meta.status = loopResult.stoppedBy === 'error' ? 'failed' : 'completed';
-        meta.completedAt = new Date().toISOString();
-        meta.exitCode = loopResult.stoppedBy === 'error' ? 1 : 0;
+        const loopFailed = loopResult.stoppedBy === 'error';
+        finalizeRunMeta(meta, loopFailed ? 'failed' : 'completed', loopFailed ? 1 : 0, loopFailed ? { errorMessage: `loop stopped: ${loopResult.stoppedBy}` } : undefined);
         writeRunMeta(meta);
         timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
         return { meta, reportPath: null };
@@ -574,17 +573,14 @@ export async function executeJob(config, deps) {
         meta.pid = attempt.pid;
         writeRunMeta(meta);
         if (attempt.status === 'timeout') {
-            meta.status = 'timeout';
-            meta.completedAt = new Date().toISOString();
+            finalizeRunMeta(meta, 'timeout', null, { errorMessage: 'run timed out' });
             writeRunMeta(meta);
             timer.end({ status: 'timeout', runId });
             const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
             return { meta, reportPath };
         }
         if (attempt.status === 'completed') {
-            meta.exitCode = 0;
-            meta.status = 'completed';
-            meta.completedAt = new Date().toISOString();
+            finalizeRunMeta(meta, 'completed', 0);
             writeRunMeta(meta);
             timer.end({ status: 'completed', exitCode: 0, runId });
             const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
@@ -603,9 +599,7 @@ export async function executeJob(config, deps) {
         if (attempt.error) {
             process.stderr.write(`[agents] routine ${config.name}: spawn failed for ${label}: ${attempt.error}\n`);
         }
-        meta.exitCode = attempt.exitCode ?? 1;
-        meta.status = 'failed';
-        meta.completedAt = new Date().toISOString();
+        finalizeRunMeta(meta, 'failed', attempt.exitCode ?? 1, attempt.error ? { errorMessage: attempt.error } : undefined);
         writeRunMeta(meta);
         timer.end({
             status: 'failed',
@@ -617,9 +611,7 @@ export async function executeJob(config, deps) {
         return { meta, reportPath };
     }
     // Unreachable: chain is always non-empty, but keep a safe fallback.
-    meta.status = 'failed';
-    meta.exitCode = 1;
-    meta.completedAt = new Date().toISOString();
+    finalizeRunMeta(meta, 'failed', 1);
     writeRunMeta(meta);
     timer.end({ status: 'failed', exitCode: 1, runId });
     return { meta, reportPath: null };
@@ -676,9 +668,7 @@ async function executeJobOnHost(config, opts) {
     // Sync path: a real exit code finalizes now. -1 (follow window closed) and
     // the detached path leave the meta `running` for the monitor to reconcile.
     if (!opts.detached && exitCode !== null && exitCode !== undefined && exitCode !== -1) {
-        meta.status = exitCode === 0 ? 'completed' : 'failed';
-        meta.exitCode = exitCode;
-        meta.completedAt = new Date().toISOString();
+        finalizeRunMeta(meta, exitCode === 0 ? 'completed' : 'failed', exitCode);
     }
     writeRunMeta(meta);
     timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
@@ -755,9 +745,7 @@ async function executeCommandJobForeground(config) {
             finish({ exitCode: 1, status: 'failed', error: err.message });
         });
     });
-    meta.status = result.status;
-    meta.exitCode = result.exitCode ?? (result.status === 'completed' ? 0 : 1);
-    meta.completedAt = new Date().toISOString();
+    finalizeRunMeta(meta, result.status, result.exitCode ?? (result.status === 'completed' ? 0 : 1), result.error ? { errorMessage: result.error } : undefined);
     writeRunMeta(meta);
     if (result.error) {
         process.stderr.write(`[agents] routine ${config.name}: command spawn failed: ${result.error}\n`);
@@ -847,9 +835,7 @@ export async function executeJobDetached(config) {
             fs.closeSync(stdoutFd);
         }
         catch { /* fd already closed */ }
-        meta.status = 'failed';
-        meta.exitCode = 1;
-        meta.completedAt = new Date().toISOString();
+        finalizeRunMeta(meta, 'failed', 1, { errorMessage: err.message });
         writeRunMeta(meta);
         process.stderr.write(`[agents] daemon: spawn failed for job "${config.name}": ${err.message}\n`);
     });
@@ -907,18 +893,16 @@ function executeCommandJobDetached(config) {
     // fire-and-forget call, so the exit event fires here. (monitorRunningJobs no
     // longer force-fails command jobs; it reads exit-code only on the restart edge.)
     let settled = false;
-    const settle = (status, exitCode) => {
+    const settle = (status, exitCode, errorMessage) => {
         if (settled)
             return;
         settled = true;
-        meta.status = status;
-        meta.exitCode = exitCode;
-        meta.completedAt = new Date().toISOString();
+        finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
     };
     child.on('exit', (code) => settle(code === 0 ? 'completed' : 'failed', code ?? 1));
     child.on('error', (err) => {
-        settle('failed', 1);
+        settle('failed', 1, err.message);
         process.stderr.write(`[agents] daemon: command spawn failed for job "${config.name}": ${err.message}\n`);
     });
     child.unref();
@@ -1072,9 +1056,7 @@ function finalizeHostRun(meta) {
         const healed = reconcileHostTask(task);
         if (healed.status !== 'completed' && healed.status !== 'failed')
             return;
-        meta.status = healed.status;
-        meta.exitCode = healed.exitCode ?? (healed.status === 'completed' ? 0 : 1);
-        meta.completedAt = healed.finishedAt ?? new Date().toISOString();
+        finalizeRunMeta(meta, healed.status, healed.exitCode ?? (healed.status === 'completed' ? 0 : 1), { completedAt: healed.finishedAt ?? undefined });
         writeRunMeta(meta);
     }
     catch { /* unreachable host or unreadable sidecar — retry next sweep */ }
@@ -1114,8 +1096,7 @@ export function monitorRunningJobs() {
                 const isCommandRun = Boolean(meta.command) || !meta.agent;
                 const wallClockMs = Date.now() - Date.parse(meta.startedAt);
                 if (Number.isFinite(wallClockMs) && wallClockMs > MAX_WALL_CLOCK_MS) {
-                    meta.status = 'timeout';
-                    meta.completedAt = new Date().toISOString();
+                    finalizeRunMeta(meta, 'timeout', null, { errorMessage: 'exceeded max wall clock' });
                     writeRunMeta(meta);
                     if (!isCommandRun)
                         extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
@@ -1129,20 +1110,17 @@ export function monitorRunningJobs() {
                         // missed the exit event — recover the true code from the exit-code file
                         // the child wrote; its absence means the child was killed/crashed.
                         const ec = readCommandExitCode(runDirPath);
-                        meta.status = ec === 0 ? 'completed' : 'failed';
-                        meta.exitCode = ec;
+                        finalizeRunMeta(meta, ec === 0 ? 'completed' : 'failed', ec);
                     }
                     else {
                         const inferred = inferFinalStatusFromLog(stdoutPath, meta.agent);
                         if (inferred) {
-                            meta.status = inferred.status;
-                            meta.exitCode = inferred.exitCode;
+                            finalizeRunMeta(meta, inferred.status, inferred.exitCode);
                         }
                         else {
-                            meta.status = 'failed';
+                            finalizeRunMeta(meta, 'failed', null, { errorMessage: 'process exited before final status could be inferred' });
                         }
                     }
-                    meta.completedAt = new Date().toISOString();
                     writeRunMeta(meta);
                     if (!isCommandRun)
                         extractAndSaveReport(stdoutPath, meta.agent, runDirPath);

package/dist/lib/secrets/agent.js

@@ -33,6 +33,7 @@ import { getHelpersDir, readMeta } from '../state.js';
 import { isAlive } from '../platform/process.js';
 import { getKeychainHelperPath } from './install-helper.js';
 import { getCliVersion, getCliVersionFresh } from '../version.js';
+import { getCliLaunch } from '../cli-entry.js';
 /** Bumped when the wire protocol changes; a client that pings a mismatched
  * server kills and respawns it rather than talking a stale dialect. */
 const PROTOCOL_VERSION = 1;
@@ -148,23 +149,18 @@ function writeAgentToken() {
 }
 /**
  * Argv for re-invoking THIS cli with a hidden subcommand, so a side-by-side dev
- * build spawns its own helpers rather than the registry-installed one. We always
- * go through `process.execPath` (the node binary) with the JS entrypoint as the
- * first arg — the entrypoint isn't reliably executable in dev builds (invoked as
- * `node dist/index.js`, no +x), so spawning it directly EACCES'd.
+ * build spawns its own helpers rather than the registry-installed one. Routed
+ * through the shared getCliLaunch so it handles both install shapes — a JS entry
+ * (`node dist/index.js …`) and a Bun standalone binary (run directly). The old
+ * hand-rolled `[process.execPath, process.argv[1], …]` broke on standalone builds:
+ * process.argv[1] is the bun virtual entry `/$bunfs/root/agents` (fs.existsSync
+ * reports it as present), so it was passed as an argv element and the broker died
+ * with `unknown command '/$bunfs/root/agents'` — the daemon-hosted broker never
+ * bound its socket and every unlock reported "Could not start the secrets broker".
  */
 function cliSpawn(sub) {
-    const argv1 = process.argv[1];
-    const entry = argv1 && fs.existsSync(argv1) ? argv1 : null;
-    if (entry)
-        return { cmd: process.execPath, args: [entry, ...sub] };
-    // No resolvable entrypoint (unusual) — fall back to the PATH shim.
-    let bin = 'agents';
-    try {
-        bin = execFileSync('which', ['agents'], { encoding: 'utf-8' }).trim();
-    }
-    catch { /* default */ }
-    return { cmd: bin, args: sub };
+    const { command, args } = getCliLaunch(sub);
+    return { cmd: command, args };
 }
 function brokerSpawn() {
     return cliSpawn(['secrets', '_agent-run']);

package/dist/lib/session/fork.d.ts

@@ -0,0 +1,32 @@
+import type { SessionMeta } from './types.js';
+/** Agents that `fork` can branch today (see the module doc for why). */
+export declare const FORKABLE_AGENTS: readonly ["claude"];
+/** Whether a session's agent can be forked by {@link forkSession}. */
+export declare function isForkableAgent(agent: string): boolean;
+/** Outcome of a successful fork. */
+export interface ForkResult {
+    /** The new session's full id. */
+    newId: string;
+    /** The new session's short id (first 8 chars), for display/resume. */
+    shortId: string;
+    /** Absolute path of the copied transcript. */
+    filePath: string;
+    /** The label applied to the fork. */
+    label: string;
+}
+/**
+ * Fork a Claude session into a new, independent one.
+ *
+ * Copies `source.filePath` to a new `<uuid>.jsonl` beside it, rewrites the
+ * embedded session id, registers the new session in the index, and records a
+ * `--name`-style label. Returns the new ids/path. Throws if the source
+ * transcript is missing.
+ *
+ * @param source  The resolved metadata of the session being forked.
+ * @param opts.name  Optional explicit label; defaults to `fork of <original>`.
+ * @param now  ISO timestamp to stamp the fork with (injectable for tests).
+ */
+export declare function forkSession(source: SessionMeta, opts?: {
+    name?: string;
+    now?: string;
+}): ForkResult;

package/dist/lib/session/fork.js

@@ -0,0 +1,101 @@
+/**
+ * Session forking — branch an existing conversation into a new, independent
+ * session that can be continued separately, leaving the original untouched.
+ *
+ * `resume` continues the SAME conversation (same id, same file — it appends).
+ * `fork` copies the transcript under a FRESH session id, so continuing the fork
+ * diverges from the original instead of mutating it. This is the "git branch"
+ * of conversations.
+ *
+ * v1 supports Claude, whose session id IS its `<id>.jsonl` filename and which
+ * resumes natively via `--resume`. A fork is therefore: copy the transcript to
+ * a new-uuid filename in the same directory, rewrite the embedded `sessionId`
+ * on each line, register the new session in the index, and label it. Other
+ * agents (codex single-file; grok/kimi multi-file; opencode DB-only) are a
+ * natural follow-up and are refused up front for now.
+ */
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { upsertSession } from './db.js';
+import { recordRunName } from './run-names.js';
+/** Agents that `fork` can branch today (see the module doc for why). */
+export const FORKABLE_AGENTS = ['claude'];
+/** Whether a session's agent can be forked by {@link forkSession}. */
+export function isForkableAgent(agent) {
+    return FORKABLE_AGENTS.includes(agent);
+}
+/**
+ * Rewrite the per-line `sessionId` field of a Claude JSONL transcript to a new
+ * id. Claude resolves a conversation by its filename, so this is belt-and-braces
+ * (keeps the in-file id consistent with the new filename); malformed lines are
+ * passed through untouched.
+ */
+function rewriteSessionId(transcript, newId) {
+    return transcript
+        .split('\n')
+        .map((line) => {
+        if (!line.trim())
+            return line;
+        try {
+            const obj = JSON.parse(line);
+            if (typeof obj.sessionId === 'string') {
+                obj.sessionId = newId;
+                return JSON.stringify(obj);
+            }
+            return line;
+        }
+        catch {
+            return line;
+        }
+    })
+        .join('\n');
+}
+/**
+ * Fork a Claude session into a new, independent one.
+ *
+ * Copies `source.filePath` to a new `<uuid>.jsonl` beside it, rewrites the
+ * embedded session id, registers the new session in the index, and records a
+ * `--name`-style label. Returns the new ids/path. Throws if the source
+ * transcript is missing.
+ *
+ * @param source  The resolved metadata of the session being forked.
+ * @param opts.name  Optional explicit label; defaults to `fork of <original>`.
+ * @param now  ISO timestamp to stamp the fork with (injectable for tests).
+ */
+export function forkSession(source, opts = {}) {
+    if (!fs.existsSync(source.filePath)) {
+        throw new Error(`transcript not found for session ${source.shortId}: ${source.filePath}`);
+    }
+    const newId = randomUUID();
+    const shortId = newId.slice(0, 8);
+    const dir = path.dirname(source.filePath);
+    const filePath = path.join(dir, `${newId}.jsonl`);
+    const transcript = fs.readFileSync(source.filePath, 'utf-8');
+    const rewritten = rewriteSessionId(transcript, newId);
+    fs.writeFileSync(filePath, rewritten);
+    const original = source.label || source.topic || source.shortId;
+    const label = opts.name || `fork of ${original}`;
+    // Label sidecar (seeds the DB label; survives rescans until an agent title
+    // supersedes it), mirroring `agents run --name`.
+    recordRunName({ sessionId: newId, name: label, agent: source.agent, cwd: source.cwd });
+    // Register the new session so it resolves immediately (by `agents resume`,
+    // `agents sessions`, etc.) without waiting for the next scan.
+    const stamp = opts.now ?? new Date().toISOString();
+    const meta = {
+        ...source,
+        id: newId,
+        shortId,
+        filePath,
+        label,
+        timestamp: stamp,
+        lastActivity: stamp,
+        // The fork has not opened its own PR / team; drop origin-specific refs.
+        prUrl: undefined,
+        prNumber: undefined,
+        teamOrigin: undefined,
+        spawnedTeam: undefined,
+    };
+    upsertSession(meta, rewritten);
+    return { newId, shortId, filePath, label };
+}

package/dist/lib/share/capture.js

@@ -100,7 +100,17 @@ export async function captureCover(htmlPath, timeoutMs = 15_000) {
     if (!fs.existsSync(abs))
         return null;
     const fileUrl = `file://${abs.split('/').map(encodeURIComponent).join('/')}`;
-    for (const bin of candidateBrowsers()) {
+    const candidates = candidateBrowsers();
+    if (candidates.length === 0) {
+        // A silently-dropped cover reads as "the CLI decided this page needs none",
+        // when in fact no headless browser was found. Say so and point at the escape
+        // hatch instead of leaving the publish coverless with no explanation.
+        process.stderr.write('[agents share] no headless browser found for the OG cover — install Chrome/Chromium ' +
+            'or set AGENTS_SHARE_BROWSER=/path/to/chrome. Publishing without a preview image.\n');
+        return null;
+    }
+    let lastFailure = '';
+    for (const bin of candidates) {
         const outPng = path.join(os.tmpdir(), `agents-share-cover-${process.pid}-${Date.now()}.png`);
         const userDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-share-chrome-'));
         try {
@@ -126,15 +136,23 @@ export async function captureCover(htmlPath, timeoutMs = 15_000) {
                 // A valid PNG starts with the 8-byte signature; guard against 0-byte writes.
                 if (buf.length > 8 && buf[0] === 0x89 && buf[1] === 0x50)
                     return buf;
+                lastFailure = `${path.basename(bin)}: produced no valid PNG`;
+            }
+            else {
+                lastFailure = `${path.basename(bin)}: no screenshot written`;
             }
         }
-        catch {
-            // try the next candidate
+        catch (err) {
+            lastFailure = `${path.basename(bin)}: ${err.message}`;
         }
         finally {
             fs.rmSync(outPng, { force: true });
             fs.rmSync(userDir, { recursive: true, force: true });
         }
     }
+    // Every candidate ran but none yielded a cover — surface the last reason so a
+    // missing preview card is diagnosable (timeout, crash, bad binary) rather than silent.
+    process.stderr.write(`[agents share] OG cover capture failed (${lastFailure || 'unknown error'}) — ` +
+        'publishing without a preview image. Set AGENTS_SHARE_BROWSER to override.\n');
     return null;
 }

package/dist/lib/signin-badge.d.ts

@@ -0,0 +1,41 @@
+import type { AccountInfo } from './agents.js';
+import type { AgentId } from './types.js';
+/**
+ * The exact command that logs a given agent in — for warn banners and nudges.
+ * Driven off the registry `cliCommand` with the per-agent subcommand overrides
+ * (verified against the real CLIs): codex/grok use `<cli> login`, opencode uses
+ * `<cli> auth login`, claude logs in from inside its TUI via `/login`, and the
+ * remaining agents (kimi, gemini, …) start their device/oauth flow on launch.
+ */
+export declare function loginHint(agentId: AgentId): string;
+/**
+ * Whether `agents run` should probe login state before launching. True only for
+ * a launch that actually opens the interactive TUI — where discovering a logged-out
+ * account after the fact wastes time. Suppressed when there is no preamble surface
+ * (`--json`/`--quiet`), when the check is explicitly disabled
+ * (`--no-auth-check` / `AGENTS_NO_AUTH_CHECK=1`), or when a rotation already picked a
+ * signed-in account.
+ *
+ * `forceInteractive` is load-bearing: a resume of a non-native-resume agent
+ * (`agents run kimi --resume`, also grok/opencode/gemini) rewrites the prompt to
+ * `/continue <id>` — so `hasPrompt` is true even though the run still opens the TUI.
+ * Keying only off `hasPrompt` would silently skip the warning on exactly those
+ * agents (the ones the feature is for), so the resume's `forceInteractive` flag is
+ * consulted directly.
+ */
+export declare function shouldCheckLoginBeforeLaunch(o: {
+    interactive?: boolean;
+    forceInteractive?: boolean;
+    headless?: boolean;
+    hasPrompt: boolean;
+    json?: boolean;
+    quiet?: boolean;
+    authCheckDisabled?: boolean;
+    rotated?: boolean;
+}): boolean;
+/**
+ * Colored `✓ signed in <account>` / `✗ logged out` badge. When signed in and an
+ * account label is derivable (email, else an account id), it is appended in cyan;
+ * opaque-credential agents with no email still read as signed in.
+ */
+export declare function formatSignInBadge(info: Pick<AccountInfo, 'signedIn' | 'email' | 'accountId'> | null | undefined): string;

package/dist/lib/signin-badge.js

@@ -0,0 +1,64 @@
+/**
+ * Shared login-state LOOK. One place decides how "signed in / logged out"
+ * renders and what the login command is, so `agents doctor`, `agents view`, and
+ * the `agents run` preflight banner all read identically.
+ *
+ * The signal is `AccountInfo.signedIn` from `getAccountInfo` (file-based, cheap,
+ * no Keychain ACL prompt). It is advisory — opaque-credential agents (Kimi,
+ * Antigravity) and keychain-bound Claude can false-negative — so callers that act
+ * on it (the run preflight) WARN and continue; they never block.
+ */
+import chalk from 'chalk';
+import { AGENTS } from './agents.js';
+/**
+ * The exact command that logs a given agent in — for warn banners and nudges.
+ * Driven off the registry `cliCommand` with the per-agent subcommand overrides
+ * (verified against the real CLIs): codex/grok use `<cli> login`, opencode uses
+ * `<cli> auth login`, claude logs in from inside its TUI via `/login`, and the
+ * remaining agents (kimi, gemini, …) start their device/oauth flow on launch.
+ */
+export function loginHint(agentId) {
+    const cli = AGENTS[agentId]?.cliCommand ?? agentId;
+    switch (agentId) {
+        case 'claude':
+            return `${cli}, then /login`;
+        case 'codex':
+        case 'grok':
+            return `${cli} login`;
+        case 'opencode':
+            return `${cli} auth login`;
+        default:
+            return cli;
+    }
+}
+/**
+ * Whether `agents run` should probe login state before launching. True only for
+ * a launch that actually opens the interactive TUI — where discovering a logged-out
+ * account after the fact wastes time. Suppressed when there is no preamble surface
+ * (`--json`/`--quiet`), when the check is explicitly disabled
+ * (`--no-auth-check` / `AGENTS_NO_AUTH_CHECK=1`), or when a rotation already picked a
+ * signed-in account.
+ *
+ * `forceInteractive` is load-bearing: a resume of a non-native-resume agent
+ * (`agents run kimi --resume`, also grok/opencode/gemini) rewrites the prompt to
+ * `/continue <id>` — so `hasPrompt` is true even though the run still opens the TUI.
+ * Keying only off `hasPrompt` would silently skip the warning on exactly those
+ * agents (the ones the feature is for), so the resume's `forceInteractive` flag is
+ * consulted directly.
+ */
+export function shouldCheckLoginBeforeLaunch(o) {
+    if (o.json || o.quiet || o.authCheckDisabled || o.rotated)
+        return false;
+    return o.interactive === true || o.forceInteractive === true || (!o.hasPrompt && o.headless !== true);
+}
+/**
+ * Colored `✓ signed in <account>` / `✗ logged out` badge. When signed in and an
+ * account label is derivable (email, else an account id), it is appended in cyan;
+ * opaque-credential agents with no email still read as signed in.
+ */
+export function formatSignInBadge(info) {
+    if (!info?.signedIn)
+        return chalk.red('✗ logged out');
+    const who = info.email ?? (info.accountId ? `id:${info.accountId}` : '');
+    return who ? `${chalk.green('✓ signed in')} ${chalk.cyan(who)}` : chalk.green('✓ signed in');
+}

package/dist/lib/ssh-exec.d.ts

@@ -70,6 +70,11 @@ export interface SshExecResult {
  * it); callers that build it from user input must `shellQuote` the pieces.
  */
 export declare function sshExec(target: string, remoteCmd: string, opts?: SshExecOptions): SshExecResult;
+/**
+ * Async variant of {@link sshExec}. Same hardened argv composition, but uses
+ * child_process.spawn so fleet fan-outs can probe multiple hosts concurrently.
+ */
+export declare function sshExecAsync(target: string, remoteCmd: string, opts?: SshExecOptions): Promise<SshExecResult>;
 export interface SshExecRawResult {
     code: number | null;
     stdout: Buffer;

package/dist/lib/ssh-exec.js

@@ -7,7 +7,7 @@
  * target-injection guard live in exactly one place. Target validation is the
  * canonical definition; `commands/secrets.ts` re-exports it.
  */
-import { spawnSync } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
@@ -125,6 +125,60 @@ export function sshExec(target, remoteCmd, opts = {}) {
         timedOut,
     };
 }
+/**
+ * Async variant of {@link sshExec}. Same hardened argv composition, but uses
+ * child_process.spawn so fleet fan-outs can probe multiple hosts concurrently.
+ */
+export function sshExecAsync(target, remoteCmd, opts = {}) {
+    assertValidSshTarget(target);
+    const mux = opts.multiplex === false ? [] : controlOpts();
+    const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...(opts.extraSshArgs ?? []), target, remoteCmd];
+    return new Promise((resolve) => {
+        const child = spawn('ssh', args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let timedOut = false;
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+            }, opts.timeoutMs)
+            : null;
+        child.stdout.setEncoding('utf-8');
+        child.stderr.setEncoding('utf-8');
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        // Guard the stdin pipe: if the child closes stdin early (e.g. exits fast), the
+        // end()/write below emits EPIPE on the stream. With no listener Node escalates
+        // that to an uncaught exception that kills the whole CLI. Swallow it — the real
+        // outcome is still reported by the 'close'/'error' handlers below.
+        child.stdin.on('error', () => { });
+        if (opts.input !== undefined)
+            child.stdin.end(opts.input);
+        else
+            child.stdin.end();
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code: null, stdout, stderr: stderr + err.message, timedOut });
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code, stdout, stderr, timedOut });
+        });
+    });
+}
 /**
  * Like {@link sshExec} but returns raw stdout/stderr Buffers — no UTF-8 decode.
  *

package/dist/lib/startup/command-registry.d.ts

@@ -45,6 +45,7 @@ export declare const loadDaemon: ModuleLoader;
 export declare const loadRoutines: ModuleLoader;
 export declare const loadMonitors: ModuleLoader;
 export declare const loadRun: ModuleLoader;
+export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;
 export declare const loadModels: ModuleLoader;
 export declare const loadPrune: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -23,6 +23,7 @@ export const loadDaemon = async () => (await import('../../commands/daemon.js'))
 export const loadRoutines = async () => (await import('../../commands/routines.js')).registerRoutinesCommands;
 export const loadMonitors = async () => (await import('../../commands/monitors.js')).registerMonitorsCommands;
 export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
+export const loadFork = async () => (await import('../../commands/fork.js')).registerForkCommand;
 export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
 export const loadModels = async () => (await import('../../commands/models.js')).registerModelsCommand;
 export const loadPrune = async () => (await import('../../commands/prune.js')).registerPruneCommand;
@@ -126,6 +127,7 @@ export const COMMAND_LOADERS = {
     routines: [loadRoutines],
     monitors: [loadMonitors],
     run: [loadRun],
+    fork: [loadFork],
     defaults: [loadDefaults],
     models: [loadModels],
     trash: [loadTrash],