@phnx-labs/agents-cli 1.20.32 → 1.20.33

package/dist/lib/crabbox/cli.js

@@ -0,0 +1,218 @@
+/**
+ * Typed wrapper over the external `crabbox` binary (github.com/openclaw/crabbox).
+ *
+ * crabbox leases ephemeral cloud boxes (Hetzner/DO/EC2/…), syncs the dirty
+ * checkout, and runs commands on them. We use it as the transport for
+ * `agents run --lease`: warm a box → run the agent on it via `crabbox run` →
+ * stop it. crabbox owns the SSH connection, so agents-cli never needs a direct
+ * ssh target (unlike the `agents hosts` model).
+ *
+ * crabbox talks to its cloud provider's API for list/status/warmup/stop, which
+ * needs a provider token (e.g. HCLOUD_TOKEN) in the environment. We inject it
+ * from a secrets bundle when one is configured (see `crabboxEnv`).
+ */
+import { spawn, spawnSync } from 'child_process';
+import { readAndResolveBundleEnv } from '../secrets/bundles.js';
+/** Locate the crabbox binary, or throw an actionable error. */
+export function findCrabbox() {
+    const r = spawnSync('crabbox', ['--help'], { encoding: 'utf-8' });
+    if (r.error) {
+        throw new Error('crabbox is not installed or not on PATH. Install it and run `crabbox login`, then `crabbox doctor` to verify provider access.');
+    }
+    return 'crabbox';
+}
+/** Build the child env for crabbox, injecting a secrets bundle when configured. */
+export function crabboxEnv(opts) {
+    const bundle = opts.secretsBundle ?? process.env.AGENTS_LEASE_SECRETS_BUNDLE;
+    if (!bundle)
+        return process.env;
+    try {
+        // Reuse the same resolver `agents secrets exec` uses so a keychain-backed
+        // bundle (e.g. hetzner.com → HCLOUD_TOKEN) reaches crabbox without ever
+        // touching disk.
+        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents run --lease (crabbox)' });
+        return { ...process.env, ...env };
+    }
+    catch (e) {
+        throw new Error(`Could not load secrets bundle "${bundle}" for crabbox: ${e.message}. ` +
+            `Fix the bundle (agents secrets view ${bundle}) or unset lease.secretsBundle to use crabbox's own login.`);
+    }
+}
+function normalizeBox(raw) {
+    const labels = (raw.labels ?? {});
+    const slug = labels.slug ?? '';
+    if (!slug)
+        return null;
+    const status = String(raw.status ?? '');
+    const state = String(labels.state ?? '');
+    const publicNet = (raw.public_net ?? {});
+    return {
+        name: String(raw.name ?? ''),
+        status,
+        slug,
+        lease: labels.lease ?? '',
+        state,
+        ip: publicNet.ipv4?.ip || undefined,
+        profile: labels.profile,
+        class: labels.class,
+        ready: status === 'running' && state === 'ready',
+    };
+}
+/** All crabbox machines the broker knows about. */
+export function crabboxList(opts = {}) {
+    findCrabbox();
+    const r = spawnSync('crabbox', ['list', '--json'], { encoding: 'utf-8', env: crabboxEnv(opts) });
+    if (r.status !== 0) {
+        throw new Error(`crabbox list failed: ${(r.stderr || r.stdout || '').trim() || 'unknown error'}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(r.stdout || '[]');
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.map((b) => normalizeBox(b)).filter((b) => b !== null);
+}
+/** Find one box by slug, or null. */
+export function crabboxFind(slug, opts = {}) {
+    return crabboxList(opts).find((b) => b.slug === slug) ?? null;
+}
+/**
+ * Lease a box and block until it is ready. Returns the leased box.
+ *
+ * We diff `crabbox list` before/after so we reliably identify the box this call
+ * created even if warmup's stdout format changes — the new lease id is the one
+ * that wasn't present before.
+ */
+export function crabboxWarmup(opts = {}) {
+    findCrabbox();
+    const env = crabboxEnv(opts);
+    const before = new Set(crabboxList(opts).map((b) => b.lease));
+    const args = ['warmup'];
+    if (opts.class)
+        args.push('--class', opts.class);
+    if (opts.profile)
+        args.push('--profile', opts.profile);
+    if (opts.provider)
+        args.push('--provider', opts.provider);
+    if (opts.code)
+        args.push('--code');
+    const r = spawnSync('crabbox', args, { encoding: 'utf-8', env, stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status !== 0) {
+        const detail = (r.stderr || r.stdout || '').trim();
+        throw new Error(`crabbox warmup failed: ${detail || 'unknown error'}. ` +
+            `Check provider access with \`crabbox doctor\`; a missing cloud token often means \`crabbox login\` or a lease.secretsBundle is needed.`);
+    }
+    // Prefer the freshly-created box (lease absent from the pre-warmup snapshot).
+    const after = crabboxList(opts);
+    const fresh = after.filter((b) => !before.has(b.lease));
+    if (fresh.length === 1)
+        return fresh[0];
+    // Fallback: parse the cbx_ lease id crabbox prints and match it.
+    const m = (r.stdout || '').match(/cbx_[0-9a-f]+/i);
+    if (m) {
+        const byLease = after.find((b) => b.lease === m[0]);
+        if (byLease)
+            return byLease;
+    }
+    if (fresh.length > 1) {
+        // Multiple new boxes (concurrent warmups) — pick the newest ready one.
+        const ready = fresh.filter((b) => b.ready);
+        if (ready.length)
+            return ready[ready.length - 1];
+        return fresh[fresh.length - 1];
+    }
+    throw new Error('crabbox warmup succeeded but the new box could not be located in `crabbox list`.');
+}
+/**
+ * Poll until the box reports ready, or throw after timeoutMs.
+ * `sleep` is injectable so tests don't wall-clock wait.
+ */
+export async function crabboxWaitReady(slug, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const intervalMs = opts.intervalMs ?? 5_000;
+    const sleep = opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
+    const deadline = Date.now() + timeoutMs;
+    let last = null;
+    // First check is immediate (warmup usually returns an already-ready box).
+    for (;;) {
+        last = crabboxFind(slug, opts);
+        if (last?.ready)
+            return last;
+        if (Date.now() >= deadline)
+            break;
+        await sleep(intervalMs);
+    }
+    throw new Error(`crabbox box "${slug}" did not become ready within ${Math.round(timeoutMs / 1000)}s (state: ${last?.state ?? 'gone'}).`);
+}
+/**
+ * Run `remoteCmd` on the leased box via `crabbox run` (crabbox syncs the dirty
+ * checkout and owns the SSH). Streams combined output; resolves with the remote
+ * exit code (or null if crabbox itself failed to dispatch).
+ */
+export function crabboxRun(slug, remoteCmd, opts = {}) {
+    findCrabbox();
+    const args = ['run', '--id', slug, '--reclaim'];
+    if (opts.fullResync)
+        args.push('--full-resync');
+    args.push('--', 'bash', '-lc', remoteCmd);
+    return new Promise((resolve) => {
+        const proc = spawn('crabbox', args, { env: crabboxEnv(opts), stdio: ['ignore', 'pipe', 'pipe'] });
+        const pump = (chunk) => {
+            const s = chunk.toString('utf-8');
+            if (opts.onData)
+                opts.onData(s);
+            else
+                process.stdout.write(s);
+        };
+        proc.stdout.on('data', pump);
+        proc.stderr.on('data', pump);
+        proc.on('error', () => resolve(null));
+        proc.on('close', (code) => resolve(code));
+    });
+}
+/**
+ * Upload `script` to the box via `crabbox run --script-stdin` and run it.
+ *
+ * The script body travels over stdin and is written to a file on the box before
+ * execution — it never appears in argv / `ps` / shell history, which is why this
+ * is the transport for credential provisioning (the token contents live only in
+ * the uploaded script, then the file is removed by the script itself).
+ * Streams combined output; resolves with the remote exit code (null on dispatch failure).
+ */
+export function crabboxRunScript(slug, script, opts = {}) {
+    findCrabbox();
+    const args = ['run', '--id', slug, '--reclaim'];
+    if (opts.fullResync)
+        args.push('--full-resync');
+    args.push('--script-stdin');
+    return new Promise((resolve) => {
+        const proc = spawn('crabbox', args, { env: crabboxEnv(opts), stdio: ['pipe', 'pipe', 'pipe'] });
+        const pump = (chunk) => {
+            const s = chunk.toString('utf-8');
+            if (opts.onData)
+                opts.onData(s);
+            else
+                process.stdout.write(s);
+        };
+        proc.stdout.on('data', pump);
+        proc.stderr.on('data', pump);
+        proc.on('error', () => resolve(null));
+        proc.on('close', (code) => resolve(code));
+        proc.stdin.write(script);
+        proc.stdin.end();
+    });
+}
+/** Release the lease / delete the box. Best-effort; never throws. */
+export function crabboxStop(slug, opts = {}) {
+    try {
+        const r = spawnSync('crabbox', ['stop', '--id', slug], { encoding: 'utf-8', env: crabboxEnv(opts) });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/crabbox/lease.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `agents run --lease` orchestrator.
+ *
+ * Lease an ephemeral crabbox → provision the picked runtime(s) + their
+ * credentials → run the agent on the box (via `crabbox run`, which owns the
+ * SSH) → tear the box down. The whole box-side sequence rides a single
+ * `--script-stdin` body so the token contents never touch argv.
+ */
+import type { AgentId } from '../types.js';
+import { type CrabboxBox } from './cli.js';
+import { type DetectedRuntime } from './runtimes.js';
+export interface LeaseRunOptions {
+    agent: string;
+    prompt: string;
+    mode?: string;
+    model?: string;
+    /** Cloud backend crabbox provisions on (hetzner/aws/do/…). */
+    backend?: string;
+    boxClass?: string;
+    profile?: string;
+    /** Runtimes to install + authenticate on the box (from the picker). */
+    runtimes: AgentId[];
+    detected: DetectedRuntime[];
+    /** Secrets bundle providing crabbox's provider token. */
+    secretsBundle?: string;
+    onData?: (s: string) => void;
+    /** Keep the box after the run instead of stopping it. */
+    keep?: boolean;
+}
+export interface LeaseRunResult {
+    box: CrabboxBox;
+    exitCode: number | null;
+    toreDown: boolean;
+}
+/**
+ * Build the single bootstrap script run on the box: ensure agents-cli, install
+ * the picked runtime CLIs, write their credentials, run the agent, then shred
+ * the credential files. Best-effort install steps never abort the run.
+ */
+export declare function buildBootstrapScript(opts: LeaseRunOptions): string;
+export declare function leaseAndRun(opts: LeaseRunOptions): Promise<LeaseRunResult>;

package/dist/lib/crabbox/lease.js

@@ -0,0 +1,73 @@
+/**
+ * `agents run --lease` orchestrator.
+ *
+ * Lease an ephemeral crabbox → provision the picked runtime(s) + their
+ * credentials → run the agent on the box (via `crabbox run`, which owns the
+ * SSH) → tear the box down. The whole box-side sequence rides a single
+ * `--script-stdin` body so the token contents never touch argv.
+ */
+import { crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop } from './cli.js';
+import { buildCredentialScript } from './runtimes.js';
+/** POSIX single-quote for safe embedding in the generated bootstrap script. */
+function q(s) {
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+/**
+ * Build the single bootstrap script run on the box: ensure agents-cli, install
+ * the picked runtime CLIs, write their credentials, run the agent, then shred
+ * the credential files. Best-effort install steps never abort the run.
+ */
+export function buildBootstrapScript(opts) {
+    const credScript = buildCredentialScript(opts.runtimes, opts.detected);
+    const runParts = ['agents', 'run', q(opts.agent), q(opts.prompt), '--quiet'];
+    if (opts.mode)
+        runParts.push('--mode', q(opts.mode));
+    if (opts.model)
+        runParts.push('--model', q(opts.model));
+    // Credential files to shred after the run (home-level paths written above).
+    const shred = opts.runtimes
+        .map((id) => {
+        const cred = { claude: '.claude.json', codex: '.codex/auth.json', gemini: '.gemini/google_accounts.json', grok: '.grok/auth.json' }[id];
+        return cred ? `rm -f "$HOME/${cred}" 2>/dev/null || true` : '';
+    })
+        .filter(Boolean)
+        .join('\n');
+    const installRuntimes = opts.runtimes.map((id) => `agents add ${q(id)} >/dev/null 2>&1 || true`).join('\n');
+    return [
+        'set -uo pipefail',
+        'if ! command -v agents >/dev/null 2>&1; then npm install -g @phnx-labs/agents-cli >/dev/null 2>&1 || true; fi',
+        installRuntimes,
+        credScript,
+        `${runParts.join(' ')}`,
+        'rc=$?',
+        shred,
+        'exit $rc',
+    ]
+        .filter((l) => l.length > 0)
+        .join('\n');
+}
+export async function leaseAndRun(opts) {
+    const box = crabboxWarmup({
+        class: opts.boxClass,
+        profile: opts.profile,
+        provider: opts.backend,
+        secretsBundle: opts.secretsBundle,
+    });
+    await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+    const script = buildBootstrapScript(opts);
+    let exitCode = null;
+    let toreDown = false;
+    try {
+        exitCode = await crabboxRunScript(box.slug, script, {
+            secretsBundle: opts.secretsBundle,
+            onData: opts.onData,
+        });
+    }
+    finally {
+        // Always attempt teardown (bounds credential lifetime to the run) unless the
+        // caller explicitly asked to keep the box.
+        if (!opts.keep)
+            toreDown = crabboxStop(box.slug, { secretsBundle: opts.secretsBundle });
+    }
+    return { box, exitCode, toreDown };
+}

package/dist/lib/crabbox/runtimes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Runtime detection + picker + credential-script builder for `agents run --lease`.
+ *
+ * The picker asks which coding-agent runtime(s) to provision on a leased box.
+ * The default selection is whatever the user is currently signed into locally
+ * (via `getAccountInfo`, the same source `agents view` uses). The chosen runtimes
+ * drive both what gets installed on the box and which auth token file is copied
+ * over — the token contents ride the uploaded `--script-stdin` body, never argv.
+ *
+ * SECURITY: copying a runtime's auth token to an ephemeral cloud box is a
+ * credential transfer. It is strictly opt-in (a confirm prompt in the command
+ * layer), the token never appears in argv/`ps`, and `--lease` one-shot runs tear
+ * the box down afterward so the credential's lifetime is bounded by the run.
+ */
+import type { AgentId } from '../types.js';
+/**
+ * Credential file locations per runtime. `localCandidates` are read in order
+ * (first existing wins); `remote` is where the box's CLI reads it by default
+ * (home-level — no per-version shim). Source of truth for these paths is
+ * `getAccountInfo` in src/lib/agents.ts; keep them in sync.
+ */
+interface RuntimeCred {
+    id: AgentId;
+    label: string;
+    localCandidates: string[];
+    remote: string;
+}
+export declare const LEASE_RUNTIMES: RuntimeCred[];
+export interface DetectedRuntime {
+    id: AgentId;
+    label: string;
+    email: string | null;
+    signedIn: boolean;
+    /** Absolute local path of the credential file, if found. */
+    credPath: string | null;
+}
+/** Which lease-capable runtimes the user is signed into on this machine. */
+export declare function detectSignedInRuntimes(): Promise<DetectedRuntime[]>;
+/**
+ * Interactive checkbox: which runtimes to provision on the box. Defaults to the
+ * signed-in ones. Runtimes with no local credential are shown disabled.
+ * `prompt` is injected so tests don't require a TTY.
+ */
+export declare function pickRuntimes(detected: DetectedRuntime[], prompt?: (choices: {
+    name: string;
+    value: AgentId;
+    checked: boolean;
+    disabled: boolean | string;
+}[]) => Promise<AgentId[]>): Promise<AgentId[]>;
+/**
+ * Build a bash snippet that writes each picked runtime's token file to the box's
+ * home-level config path (0600), from the token contents read locally. Returns
+ * `''` when no runtimes were selected. The snippet is meant to be embedded in
+ * the `--script-stdin` body (never argv).
+ */
+export declare function buildCredentialScript(picked: AgentId[], detected: DetectedRuntime[]): string;
+export {};

package/dist/lib/crabbox/runtimes.js

@@ -0,0 +1,109 @@
+/**
+ * Runtime detection + picker + credential-script builder for `agents run --lease`.
+ *
+ * The picker asks which coding-agent runtime(s) to provision on a leased box.
+ * The default selection is whatever the user is currently signed into locally
+ * (via `getAccountInfo`, the same source `agents view` uses). The chosen runtimes
+ * drive both what gets installed on the box and which auth token file is copied
+ * over — the token contents ride the uploaded `--script-stdin` body, never argv.
+ *
+ * SECURITY: copying a runtime's auth token to an ephemeral cloud box is a
+ * credential transfer. It is strictly opt-in (a confirm prompt in the command
+ * layer), the token never appears in argv/`ps`, and `--lease` one-shot runs tear
+ * the box down afterward so the credential's lifetime is bounded by the run.
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+import { getAccountInfo } from '../agents.js';
+export const LEASE_RUNTIMES = [
+    { id: 'claude', label: 'Claude Code', localCandidates: ['.claude/.claude.json', '.claude.json'], remote: '.claude.json' },
+    { id: 'codex', label: 'Codex CLI', localCandidates: ['.codex/auth.json'], remote: '.codex/auth.json' },
+    { id: 'gemini', label: 'Gemini CLI', localCandidates: ['.gemini/google_accounts.json'], remote: '.gemini/google_accounts.json' },
+    { id: 'grok', label: 'Grok CLI', localCandidates: ['.grok/auth.json'], remote: '.grok/auth.json' },
+];
+/** First existing candidate path under the real home, or null. */
+function findLocalCred(cred) {
+    const home = process.env.AGENTS_REAL_HOME || os.homedir();
+    for (const rel of cred.localCandidates) {
+        const p = path.join(home, rel);
+        try {
+            if (fs.existsSync(p))
+                return p;
+        }
+        catch {
+            /* unreadable — skip */
+        }
+    }
+    return null;
+}
+/** Which lease-capable runtimes the user is signed into on this machine. */
+export async function detectSignedInRuntimes() {
+    const out = [];
+    for (const cred of LEASE_RUNTIMES) {
+        let info;
+        try {
+            info = await getAccountInfo(cred.id);
+        }
+        catch {
+            info = null;
+        }
+        out.push({
+            id: cred.id,
+            label: cred.label,
+            email: info?.email ?? null,
+            signedIn: !!info?.signedIn,
+            credPath: findLocalCred(cred),
+        });
+    }
+    return out;
+}
+/**
+ * Interactive checkbox: which runtimes to provision on the box. Defaults to the
+ * signed-in ones. Runtimes with no local credential are shown disabled.
+ * `prompt` is injected so tests don't require a TTY.
+ */
+export async function pickRuntimes(detected, prompt) {
+    const choices = detected.map((d) => ({
+        name: `${d.label}${d.email ? ` (${d.email})` : d.signedIn ? ' (signed in)' : ''}`,
+        value: d.id,
+        checked: d.signedIn && !!d.credPath,
+        disabled: d.credPath ? false : 'no local credential — sign in first',
+    }));
+    if (prompt)
+        return prompt(choices);
+    const { checkbox } = await import('@inquirer/prompts');
+    return checkbox({ message: 'Provision which runtime(s) on the leased box?', choices });
+}
+// A long random sentinel makes an accidental (or malicious) collision with a
+// token's contents effectively impossible, so the quoted heredoc can never be
+// closed early by the credential body.
+const CRED_EOF = 'AGENTS_LEASE_CRED_EOF_9f3c1a7b5e2d4068';
+/**
+ * Build a bash snippet that writes each picked runtime's token file to the box's
+ * home-level config path (0600), from the token contents read locally. Returns
+ * `''` when no runtimes were selected. The snippet is meant to be embedded in
+ * the `--script-stdin` body (never argv).
+ */
+export function buildCredentialScript(picked, detected) {
+    const byId = new Map(detected.map((d) => [d.id, d]));
+    const parts = [];
+    for (const id of picked) {
+        const d = byId.get(id);
+        const cred = LEASE_RUNTIMES.find((c) => c.id === id);
+        if (!d?.credPath || !cred)
+            continue;
+        let contents;
+        try {
+            contents = fs.readFileSync(d.credPath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const dir = path.posix.dirname(cred.remote);
+        const mkdir = dir && dir !== '.' ? `mkdir -p "$HOME/${dir}"\n` : '';
+        parts.push(`${mkdir}cat > "$HOME/${cred.remote}" <<'${CRED_EOF}'\n${contents}${contents.endsWith('\n') ? '' : '\n'}${CRED_EOF}\n` +
+            `chmod 600 "$HOME/${cred.remote}"`);
+    }
+    return parts.join('\n');
+}

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

@@ -1,13 +1,20 @@
 /**
- * Dispatch a headless agent run onto a host over SSH.
+ * Dispatch a headless `agents …` command onto a host over SSH.
  *
- * The run is launched detached (`nohup … &`) writing combined output to a remote
- * log and its exit code to a sibling `.exit` file, so progress survives a dropped
- * connection (followed via offset-tail in progress.ts). This is the offload win:
- * the agent's process/thread/file fan-out happens on the host, not the laptop.
+ * The command is launched detached (`nohup … &`) writing combined output to a
+ * remote log and its exit code to a sibling `.exit` file, so progress survives a
+ * dropped connection (followed via offset-tail in progress.ts). This is the
+ * offload win: the process/thread/file fan-out happens on the host, not the
+ * laptop. `agents run` uses it; `agents teams start --watch --host` reuses the
+ * same core so a remote team supervisor keeps running after you disconnect.
  */
 import type { Host } from './types.js';
 import { type HostTask } from './tasks.js';
+export interface DispatchResult {
+    task: HostTask;
+    /** Exit code when followed; undefined when detached (--no-follow). */
+    exitCode?: number;
+}
 export interface DispatchOptions {
     agent: string;
     prompt: string;
@@ -18,9 +25,19 @@ export interface DispatchOptions {
     follow?: boolean;
     timeoutMs?: number;
 }
-export interface DispatchResult {
-    task: HostTask;
-    /** Exit code when followed; undefined when detached (--no-follow). */
-    exitCode?: number;
-}
+/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export declare function dispatchToHost(host: Host, opts: DispatchOptions): Promise<DispatchResult>;
+export interface CommandDispatchOptions {
+    /** `agents …` args (command name first), already stripped of routing flags. */
+    forwardedArgs: string[];
+    remoteCwd?: string;
+    follow?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Dispatch an arbitrary long-running `agents <command>` onto a host detached —
+ * used for `teams start --watch --host`, whose supervisor must outlive the SSH
+ * connection. Reachability is assumed (the caller has already resolved the host);
+ * a launch failure surfaces the remote stderr.
+ */
+export declare function dispatchAgentsCommand(host: Host, opts: CommandDispatchOptions): Promise<DispatchResult>;

package/dist/lib/hosts/dispatch.js

@@ -1,10 +1,12 @@
 /**
- * Dispatch a headless agent run onto a host over SSH.
+ * Dispatch a headless `agents …` command onto a host over SSH.
  *
- * The run is launched detached (`nohup … &`) writing combined output to a remote
- * log and its exit code to a sibling `.exit` file, so progress survives a dropped
- * connection (followed via offset-tail in progress.ts). This is the offload win:
- * the agent's process/thread/file fan-out happens on the host, not the laptop.
+ * The command is launched detached (`nohup … &`) writing combined output to a
+ * remote log and its exit code to a sibling `.exit` file, so progress survives a
+ * dropped connection (followed via offset-tail in progress.ts). This is the
+ * offload win: the process/thread/file fan-out happens on the host, not the
+ * laptop. `agents run` uses it; `agents teams start --watch --host` reuses the
+ * same core so a remote team supervisor keeps running after you disconnect.
  */
 import { randomUUID } from 'crypto';
 import { sshExec, shellQuote } from '../ssh-exec.js';
@@ -16,25 +18,22 @@ import { followHostTask } from './progress.js';
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
 const REMOTE_DIR = '$HOME/.agents/.cache/hosts';
-export async function dispatchToHost(host, opts) {
-    const target = sshTargetFor(host);
-    const { warnings } = ensureHostReady(host, { agent: opts.agent });
-    for (const w of warnings)
-        process.stderr.write(`[hosts] warning: ${w}\n`);
+/**
+ * The launch + task-record + optional follow core. Both `dispatchToHost` (run)
+ * and `dispatchAgentsCommand` (teams) build their `forwardedArgs` and call here,
+ * so the nohup/exit-file/offset-tail machinery lives in exactly one place.
+ */
+async function launchDetached(host, target, opts) {
     const id = randomUUID().slice(0, 8);
     const remoteLog = `${REMOTE_DIR}/${id}.log`;
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
     // Inner command run under a login shell so PATH resolves `agents`.
-    const runParts = ['agents', 'run', shellQuote(opts.agent), shellQuote(opts.prompt), '--quiet'];
-    if (opts.mode)
-        runParts.push('--mode', shellQuote(opts.mode));
-    if (opts.model)
-        runParts.push('--model', shellQuote(opts.model));
+    const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
     const cwd = opts.remoteCwd ? `cd ${shellQuote(opts.remoteCwd)} && ` : '';
-    const inner = `${cwd}${runParts.join(' ')} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
+    const inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
     // Outer: ensure dir, launch detached under bash -lc, print the PID.
     const launch = `mkdir -p ${REMOTE_DIR}; nohup bash -lc ${shellQuote(inner)} >/dev/null 2>&1 & echo $!`;
-    const res = sshExec(target, launch, { timeoutMs: 30000 });
+    const res = sshExec(target, launch, { timeoutMs: 30000, multiplex: true });
     if (res.code !== 0) {
         throw new Error(`Failed to launch on "${host.name}": ${(res.stderr || res.stdout).trim() || 'ssh error'}`);
     }
@@ -43,8 +42,8 @@ export async function dispatchToHost(host, opts) {
         id,
         host: host.name,
         target,
-        agent: opts.agent,
-        prompt: opts.prompt,
+        agent: opts.agentLabel,
+        prompt: opts.promptLabel,
         pid: Number.isFinite(pid) ? pid : undefined,
         remoteLog,
         remoteExit,
@@ -69,3 +68,40 @@ export async function dispatchToHost(host, opts) {
     });
     return { task: finished ?? task, exitCode };
 }
+/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
+export async function dispatchToHost(host, opts) {
+    const target = sshTargetFor(host);
+    const { warnings } = ensureHostReady(host, { agent: opts.agent });
+    for (const w of warnings)
+        process.stderr.write(`[hosts] warning: ${w}\n`);
+    const forwardedArgs = ['run', opts.agent, opts.prompt, '--quiet'];
+    if (opts.mode)
+        forwardedArgs.push('--mode', opts.mode);
+    if (opts.model)
+        forwardedArgs.push('--model', opts.model);
+    return launchDetached(host, target, {
+        forwardedArgs,
+        remoteCwd: opts.remoteCwd,
+        follow: opts.follow,
+        timeoutMs: opts.timeoutMs,
+        agentLabel: opts.agent,
+        promptLabel: opts.prompt,
+    });
+}
+/**
+ * Dispatch an arbitrary long-running `agents <command>` onto a host detached —
+ * used for `teams start --watch --host`, whose supervisor must outlive the SSH
+ * connection. Reachability is assumed (the caller has already resolved the host);
+ * a launch failure surfaces the remote stderr.
+ */
+export async function dispatchAgentsCommand(host, opts) {
+    const target = sshTargetFor(host);
+    return launchDetached(host, target, {
+        forwardedArgs: opts.forwardedArgs,
+        remoteCwd: opts.remoteCwd,
+        follow: opts.follow,
+        timeoutMs: opts.timeoutMs,
+        agentLabel: opts.forwardedArgs[0] ?? 'agents',
+        promptLabel: opts.forwardedArgs.join(' '),
+    });
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Shared `--host` option registrar. Every command that can run on a remote host
+ * declares the flag through here, so its spelling, help text, and companions
+ * (`--remote-cwd`, `--no-tty`, `--any`) stay identical everywhere and show up in
+ * each command's `--help`.
+ *
+ * The flags are consumed centrally by `maybeRunOnHost` (passthrough.ts) *before*
+ * commander parses, so for a real remote run the local action never sees them.
+ * Registering them here still matters: it documents the flag and keeps the local
+ * fall-through (e.g. `--host <this-machine>`) from erroring on an unknown option.
+ */
+import type { Command } from 'commander';
+/** Attach the standard `--host` flag family to a command and return it (chainable). */
+export declare function addHostOption(cmd: Command): Command;