@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/dist/lib/devices/health.js

@@ -0,0 +1,186 @@
+/**
+ * Device resource probing for `agents devices list`.
+ *
+ * One SSH round-trip per device gathers load average, memory pressure, and core
+ * count (mac + linux), parsed into a {@link DeviceStats}. Probes run in parallel
+ * with a bounded timeout so the list stays responsive — a slow or hung box
+ * degrades to "no stats" instead of blocking the whole table.
+ *
+ * The parsers are pure and unit-tested (health.test.ts). They mirror the ones in
+ * the Factory extension (apps/factory/src/core/deviceHealth.ts) — kept as a
+ * separate copy on purpose: the CLI does not import across packages.
+ */
+import { execFile } from 'child_process';
+import { buildSshInvocation, writeAskpassShim } from './connect.js';
+/** Default per-device probe budget. Short enough that the list never hangs on a
+ * wedged box, long enough for a cold relayed SSH handshake. */
+export const PROBE_TIMEOUT_MS = 2_500;
+const SEP = '---AGSTAT---';
+/** One-shot remote snapshot: load, then memory (mac vm_stat else linux
+ * meminfo), then core count (linux nproc else mac hw.ncpu). */
+const PROBE_SNIPPET = `uptime; echo ${SEP}; (vm_stat 2>/dev/null || cat /proc/meminfo 2>/dev/null); echo ${SEP}; (nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null)`;
+/** Compact human byte size: 512M, 64G, 1.5T (binary units, ≤1 decimal). */
+export function fmtBytes(bytes) {
+    if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
+        return '—';
+    const units = ['B', 'K', 'M', 'G', 'T', 'P'];
+    let v = bytes;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    const s = v >= 100 || i <= 1 ? Math.round(v).toString() : v.toFixed(1).replace(/\.0$/, '');
+    return `${s}${units[i]}`;
+}
+export function parseUptime(out) {
+    const m = out.match(/load average[s]?:\s*([0-9]+[.,][0-9]+|[0-9]+)/i);
+    if (!m)
+        return {};
+    const v = parseFloat(m[1].replace(',', '.'));
+    if (!Number.isFinite(v))
+        return {};
+    return { loadAvg1: v };
+}
+export function parseVmStat(out) {
+    const pageSize = parseInt(out.match(/page size of\s+([0-9]+)\s+bytes/)?.[1] ?? '4096', 10);
+    const active = out.match(/Pages active:\s+([0-9]+)/);
+    const wired = out.match(/Pages wired down:\s+([0-9]+)/);
+    const compressed = out.match(/Pages occupied by compressor:\s+([0-9]+)/);
+    const free = out.match(/Pages free:\s+([0-9]+)/);
+    if (!active || !wired || !compressed || !free)
+        return {};
+    // macOS reclaims inactive + speculative pages on demand, so they count as
+    // available — folding them into "free" (as Activity Monitor / vm_pressure do)
+    // rather than "used" keeps the headroom bucket honest on a Mac.
+    const inactive = out.match(/Pages inactive:\s+([0-9]+)/);
+    const speculative = out.match(/Pages speculative:\s+([0-9]+)/);
+    const usedPages = parseInt(active[1], 10) + parseInt(wired[1], 10) + parseInt(compressed[1], 10);
+    const freePages = parseInt(free[1], 10) +
+        parseInt(inactive?.[1] ?? '0', 10) +
+        parseInt(speculative?.[1] ?? '0', 10);
+    const totalPages = usedPages + freePages;
+    if (totalPages <= 0)
+        return {};
+    return {
+        memPercent: (usedPages / totalPages) * 100,
+        memTotalBytes: totalPages * pageSize,
+        memFreeBytes: freePages * pageSize,
+    };
+}
+export function parseLinuxMemInfo(out) {
+    const total = out.match(/^MemTotal:\s+([0-9]+)/im);
+    const available = out.match(/^MemAvailable:\s+([0-9]+)/im);
+    if (!total || !available)
+        return {};
+    const tKb = parseInt(total[1], 10);
+    const aKb = parseInt(available[1], 10);
+    if (tKb <= 0)
+        return {};
+    return {
+        memPercent: Math.max(0, Math.min(100, ((tKb - aKb) / tKb) * 100)),
+        memTotalBytes: tKb * 1024,
+        memFreeBytes: aKb * 1024,
+    };
+}
+export function parseNcpu(out) {
+    const n = parseInt(out.trim().split(/\s+/)[0] ?? '', 10);
+    return Number.isFinite(n) && n > 0 ? { ncpu: n } : {};
+}
+/** Assemble a DeviceStats from the three snippet sections. */
+export function parseProbeOutput(host, stdout, fetchedAt) {
+    const [uptimePart = '', memPart = '', ncpuPart = ''] = stdout.split(SEP);
+    const { loadAvg1 } = parseUptime(uptimePart);
+    const mem = memPart.includes('MemTotal') ? parseLinuxMemInfo(memPart) : parseVmStat(memPart);
+    const { ncpu } = parseNcpu(ncpuPart);
+    const loadPercent = loadAvg1 !== undefined && ncpu ? (loadAvg1 / ncpu) * 100 : undefined;
+    return {
+        host,
+        reachable: true,
+        loadAvg1,
+        ncpu,
+        loadPercent,
+        memPercent: mem.memPercent,
+        memTotalBytes: mem.memTotalBytes,
+        memFreeBytes: mem.memFreeBytes,
+        fetchedAt,
+    };
+}
+/** Sum cores and memory across reachable devices for the summary footer. */
+export function fleetCapacity(statsList) {
+    const cap = { reachable: 0, cores: 0, memTotalBytes: 0, memFreeBytes: 0 };
+    for (const s of statsList) {
+        if (!s.reachable)
+            continue;
+        cap.reachable++;
+        cap.cores += s.ncpu ?? 0;
+        cap.memTotalBytes += s.memTotalBytes ?? 0;
+        cap.memFreeBytes += s.memFreeBytes ?? 0;
+    }
+    return cap;
+}
+export function headroom(stats) {
+    if (!stats || !stats.reachable)
+        return 'unknown';
+    const signals = [stats.loadPercent, stats.memPercent].filter((v) => typeof v === 'number');
+    if (signals.length === 0)
+        return 'unknown';
+    const worst = Math.max(...signals);
+    if (worst < 15)
+        return 'idle';
+    if (worst < 40)
+        return 'light';
+    if (worst < 75)
+        return 'busy';
+    return 'loaded';
+}
+/** Probe one device over the same ssh path as `agents ssh <name>`. Never throws;
+ * an unreachable/slow/misconfigured device resolves to `reachable: false`. */
+export function probeDeviceStats(device, opts = {}) {
+    const host = device.name;
+    const fetchedAt = opts.now ?? Date.now();
+    let args;
+    let env;
+    try {
+        const shim = writeAskpassShim();
+        // buildSshInvocation joins the cmd with spaces and hands the string to the
+        // remote login shell, which evaluates the snippet's `;`/`||` directly — no
+        // `sh -c` wrapper needed (and a wrapper would only re-quote the first token).
+        ({ args, env } = buildSshInvocation(device, [PROBE_SNIPPET], shim));
+    }
+    catch {
+        return Promise.resolve({ host, reachable: false, fetchedAt });
+    }
+    return new Promise((resolve) => {
+        execFile('ssh', args, { encoding: 'utf-8', env: { ...process.env, ...env }, timeout: opts.timeoutMs ?? PROBE_TIMEOUT_MS }, (err, stdout) => {
+            if (err || !stdout)
+                return resolve({ host, reachable: false, fetchedAt });
+            resolve(parseProbeOutput(host, stdout, fetchedAt));
+        });
+    });
+}
+/** Probe the local machine directly (no ssh round-trip) — used for the "this
+ * machine" row so it always shows real numbers even if it isn't ssh-reachable
+ * from itself. */
+export function probeLocalStats(host, opts = {}) {
+    const fetchedAt = opts.now ?? Date.now();
+    return new Promise((resolve) => {
+        execFile('sh', ['-c', PROBE_SNIPPET], { encoding: 'utf-8', timeout: opts.timeoutMs ?? PROBE_TIMEOUT_MS }, (err, stdout) => {
+            if (err || !stdout)
+                return resolve({ host, reachable: false, fetchedAt });
+            resolve(parseProbeOutput(host, stdout, fetchedAt));
+        });
+    });
+}
+/** Probe many devices concurrently; returns a name→stats map. Bounded by the
+ * per-probe timeout, so total wall time ≈ the slowest single probe. The device
+ * named `selfName` is probed locally instead of over ssh. */
+export async function probeFleetStats(devices, opts = {}) {
+    const entries = await Promise.all(devices.map(async (d) => {
+        const stats = d.name === opts.selfName
+            ? await probeLocalStats(d.name, opts)
+            : await probeDeviceStats(d, opts);
+        return [d.name, stats];
+    }));
+    return new Map(entries);
+}

package/dist/lib/funnel.d.ts

@@ -0,0 +1,5 @@
+export declare const FUNNEL_PORTS: readonly [443, 8443, 10000];
+export type FunnelPort = typeof FUNNEL_PORTS[number];
+export declare function parseFunnelPort(value: string | number): FunnelPort;
+export declare function buildFunnelStatusCommand(): string;
+export declare function buildFunnelUpCommand(publicPort: FunnelPort, localPort: number): string;

package/dist/lib/funnel.js

@@ -0,0 +1,23 @@
+import { shellQuote } from './ssh-exec.js';
+export const FUNNEL_PORTS = [443, 8443, 10000];
+export function parseFunnelPort(value) {
+    const port = typeof value === 'number' ? value : Number.parseInt(value, 10);
+    if (FUNNEL_PORTS.includes(port))
+        return port;
+    throw new Error(`Tailscale Funnel public port must be one of: ${FUNNEL_PORTS.join(', ')}`);
+}
+export function buildFunnelStatusCommand() {
+    return 'tailscale funnel status';
+}
+export function buildFunnelUpCommand(publicPort, localPort) {
+    if (!Number.isInteger(localPort) || localPort <= 0 || localPort > 65535) {
+        throw new Error('Local port must be between 1 and 65535');
+    }
+    return [
+        'tailscale',
+        'funnel',
+        '--bg',
+        `--https=${publicPort}`,
+        `http://localhost:${localPort}`,
+    ].map(shellQuote).join(' ');
+}

package/dist/lib/git.d.ts

@@ -76,13 +76,24 @@ export declare function setRemoteUrl(repoPath: string, url: string): Promise<voi
  * Check if a GitHub repo exists.
  */
 export declare function checkGitHubRepoExists(owner: string, repo: string): Promise<boolean>;
-/**
- * Commit and push changes in a repo.
- */
-export declare function commitAndPush(repoPath: string, message: string): Promise<{
+/** Result of {@link commitAndPush}. */
+export type CommitAndPushResult = {
     success: boolean;
     error?: string;
-}>;
+    /** Human detail for success: "already up to date", "pushed abc..def", "committed and pushed …". */
+    detail?: string;
+    branch?: string;
+    committed?: boolean;
+    pushed?: boolean;
+};
+/**
+ * Commit (if dirty) and push a repo.
+ *
+ * Clean tree + local ahead of origin still pushes — "nothing to commit" is not
+ * "nothing to push". Reports "already up to date" only when `ahead === 0` and
+ * there is nothing to commit.
+ */
+export declare function commitAndPush(repoPath: string, message: string): Promise<CommitAndPushResult>;
 /**
  * Check if repo has uncommitted changes.
  */
@@ -166,11 +177,16 @@ export declare function displayHomePath(dir: string): string;
 /**
  * Pull changes in an existing repo.
  * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
+ *
+ * Uses `git pull --rebase` (same strategy as {@link syncRepoGit}) so a diverged
+ * branch reconciles instead of failing with "Need to specify how to reconcile
+ * divergent branches".
  */
 export declare function pullRepo(dir: string): Promise<{
     success: boolean;
     commit: string;
     error?: string;
+    branch?: string;
 }>;
 /**
  * Rebase a repo onto its remote, optionally pushing local commits back up.

package/dist/lib/git.js

@@ -366,23 +366,67 @@ export async function checkGitHubRepoExists(owner, repo) {
     }
 }
 /**
- * Commit and push changes in a repo.
+ * Commit (if dirty) and push a repo.
+ *
+ * Clean tree + local ahead of origin still pushes — "nothing to commit" is not
+ * "nothing to push". Reports "already up to date" only when `ahead === 0` and
+ * there is nothing to commit.
  */
 export async function commitAndPush(repoPath, message) {
     try {
         const git = simpleGit(repoPath);
-        // Check for changes
-        const status = await git.status();
-        if (status.files.length === 0) {
-            return { success: true }; // Nothing to commit
+        let status = await git.status();
+        const branch = status.current || 'main';
+        let committed = false;
+        if (status.files.length > 0) {
+            await git.add('-A');
+            await git.commit(message);
+            committed = true;
+            status = await git.status();
+        }
+        const ahead = status.ahead ?? 0;
+        if (!committed && ahead === 0) {
+            return {
+                success: true,
+                detail: 'already up to date',
+                branch,
+                committed: false,
+                pushed: false,
+            };
+        }
+        // Capture remote tip before push for a real ref range in the detail string.
+        let before = '';
+        try {
+            before = (await git.raw(['rev-parse', '--short=8', `origin/${branch}`])).trim();
+        }
+        catch {
+            /* origin/<branch> may not exist yet (first push) */
         }
-        // Stage all changes
-        await git.add('-A');
-        // Commit
-        await git.commit(message);
-        // Push
-        await git.push('origin', 'main');
-        return { success: true };
+        await git.push('origin', branch);
+        let after = '';
+        try {
+            after = (await git.raw(['rev-parse', '--short=8', 'HEAD'])).trim();
+        }
+        catch {
+            after = 'unknown';
+        }
+        const range = before && after && before !== after
+            ? `${before}..${after}`
+            : after || undefined;
+        const detail = committed
+            ? range
+                ? `committed and pushed ${range}`
+                : 'committed and pushed'
+            : range
+                ? `pushed ${range}`
+                : 'pushed';
+        return {
+            success: true,
+            detail,
+            branch,
+            committed,
+            pushed: true,
+        };
     }
     catch (err) {
         return { success: false, error: err.message };
@@ -630,6 +674,10 @@ export function displayHomePath(dir) {
 /**
  * Pull changes in an existing repo.
  * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
+ *
+ * Uses `git pull --rebase` (same strategy as {@link syncRepoGit}) so a diverged
+ * branch reconciles instead of failing with "Need to specify how to reconcile
+ * divergent branches".
  */
 export async function pullRepo(dir) {
     try {
@@ -642,13 +690,15 @@ export async function pullRepo(dir) {
                 error: `Working tree has uncommitted changes. Commit or discard them before pulling.\n\n  cd ${displayHomePath(dir)} && git status`,
             };
         }
-        await git.fetch();
-        await git.pull();
+        const branch = status.current || 'main';
+        await git.fetch('origin');
+        await git.pull('origin', branch, { '--rebase': 'true' });
         installGithooksSymlinks(dir);
         const log = await git.log({ maxCount: 1 });
         return {
             success: true,
             commit: log.latest?.hash.slice(0, 8) || 'unknown',
+            branch,
         };
     }
     catch (err) {

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

@@ -0,0 +1,28 @@
+/**
+ * Credential provisioning for `agents run --host --copy-creds`.
+ *
+ * Reuses the lease flow's runtime detection + credential-script builder so a
+ * persistent host can boot logged-in the same way an ephemeral leased box does.
+ * Unlike `--lease`, a host is persistent, so copying tokens is strictly opt-in
+ * per run and we shred the files after the run to bound the credential window.
+ */
+import type { AgentId } from '../types.js';
+import { type DetectedRuntime } from '../crabbox/runtimes.js';
+export interface HostCredentials {
+    runtimes: AgentId[];
+    detected: DetectedRuntime[];
+    claudeCredentialsJson?: string | null;
+}
+/**
+ * Build the setup (write credential files) and teardown (shred them) scripts for
+ * a host run. Returns shell snippets meant to be run on the remote host.
+ */
+export declare function buildHostCredentialScript(opts: HostCredentials): {
+    setup: string;
+    teardown: string;
+};
+/**
+ * Wrap a remote command so credentials are written before it runs and shredded
+ * after it exits, regardless of success or failure.
+ */
+export declare function wrapHostCommandWithCredentials(innerCommand: string, opts: HostCredentials): string;

package/dist/lib/hosts/credentials.js

@@ -0,0 +1,48 @@
+/**
+ * Credential provisioning for `agents run --host --copy-creds`.
+ *
+ * Reuses the lease flow's runtime detection + credential-script builder so a
+ * persistent host can boot logged-in the same way an ephemeral leased box does.
+ * Unlike `--lease`, a host is persistent, so copying tokens is strictly opt-in
+ * per run and we shred the files after the run to bound the credential window.
+ */
+import { buildCredentialScript, CLAUDE_TOKEN_REMOTE } from '../crabbox/runtimes.js';
+function getShredPaths(runtimes) {
+    const pathsById = {
+        claude: ['.claude.json', CLAUDE_TOKEN_REMOTE],
+        codex: ['.codex/auth.json'],
+        gemini: ['.gemini/google_accounts.json'],
+        grok: ['.grok/auth.json'],
+    };
+    return runtimes.flatMap((id) => pathsById[id] ?? []);
+}
+/**
+ * Build the setup (write credential files) and teardown (shred them) scripts for
+ * a host run. Returns shell snippets meant to be run on the remote host.
+ */
+export function buildHostCredentialScript(opts) {
+    const setup = buildCredentialScript(opts.runtimes, opts.detected, {
+        claudeCredentialsJson: opts.claudeCredentialsJson,
+    });
+    const teardown = getShredPaths(opts.runtimes)
+        .map((p) => `rm -f "$HOME/${p}" 2>/dev/null || true`)
+        .join('\n');
+    return { setup, teardown };
+}
+/**
+ * Wrap a remote command so credentials are written before it runs and shredded
+ * after it exits, regardless of success or failure.
+ */
+export function wrapHostCommandWithCredentials(innerCommand, opts) {
+    const { setup, teardown } = buildHostCredentialScript(opts);
+    return [
+        'set -uo pipefail',
+        setup,
+        innerCommand,
+        'rc=$?',
+        teardown,
+        'exit $rc',
+    ]
+        .filter((l) => l.length > 0)
+        .join('\n');
+}

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

@@ -10,6 +10,7 @@
  */
 import type { Host } from './types.js';
 import { type HostTask } from './tasks.js';
+import { type HostCredentials } from './credentials.js';
 /**
  * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
  *
@@ -36,6 +37,26 @@ export interface DispatchResult {
 }
 /** Terminate a detached dispatch that its caller could not persist locally. */
 export declare function terminateDispatchedTask(task: HostTask): void;
+/**
+ * Build the remote shell used by {@link stopDispatchedTask}. Exported for
+ * unit tests — the keep-log / no-clobber contract lives in this script.
+ *
+ * Protocol (printed to stdout for the local caller):
+ * - `SIGNALED`  — process group was live; SIGTERM/KILL applied; wrote 143
+ * - `ALREADY` + code — group gone; adopted existing `.exit` (never overwrite)
+ * - `GONE` — group gone and no `.exit`; write 143 as the local stop outcome
+ * Exit 1 if the group is still alive after TERM/KILL (can't stop it).
+ */
+export declare function buildStopRemoteCommand(pid: number, remoteExit: string): string;
+/**
+ * Stop a running host task from the origin machine (`agents hosts stop <id>`).
+ *
+ * Unlike {@link terminateDispatchedTask} (rollback cleanup after a failed
+ * persist), this keeps the remote log so `agents hosts logs <id>` still works,
+ * writes a terminal `.exit` marker only when we actually stopped a live group
+ * (or no code existed), and never clobbers a real completed-run exit code.
+ */
+export declare function stopDispatchedTask(task: HostTask): HostTask;
 export interface DispatchOptions {
     agent: string;
     prompt: string;
@@ -76,6 +97,8 @@ export interface DispatchOptions {
     /** Stream progress and block until completion (default true). */
     follow?: boolean;
     timeoutMs?: number;
+    /** Copy runtime credentials to the host before the run and shred them after. */
+    copyCreds?: HostCredentials;
 }
 /**
  * Build the remote `agents run …` argv for a host dispatch. Pure so the
@@ -116,6 +139,8 @@ export interface InteractiveDispatchOptions {
     raw?: boolean;
     /** Forward `--interactive` to the remote so a prompt-bearing run still starts the TUI. */
     forceInteractive?: boolean;
+    /** Copy runtime credentials to the host before the run and shred them after. */
+    copyCreds?: HostCredentials;
 }
 /**
  * Build the remote `agents run …` argv for an INTERACTIVE host dispatch. The

package/dist/lib/hosts/dispatch.js

@@ -16,6 +16,7 @@ import { remoteShellFor } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { saveTask, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
+import { wrapHostCommandWithCredentials } from './credentials.js';
 // Use $HOME (not ~) so the path is correct whether or not it's quoted and
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
@@ -91,6 +92,64 @@ export function terminateDispatchedTask(task) {
     terminateRemoteLaunch(task);
     updateTask(task.id, terminalPatch(143));
 }
+/**
+ * Build the remote shell used by {@link stopDispatchedTask}. Exported for
+ * unit tests — the keep-log / no-clobber contract lives in this script.
+ *
+ * Protocol (printed to stdout for the local caller):
+ * - `SIGNALED`  — process group was live; SIGTERM/KILL applied; wrote 143
+ * - `ALREADY` + code — group gone; adopted existing `.exit` (never overwrite)
+ * - `GONE` — group gone and no `.exit`; write 143 as the local stop outcome
+ * Exit 1 if the group is still alive after TERM/KILL (can't stop it).
+ */
+export function buildStopRemoteCommand(pid, remoteExit) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        throw new Error(`Invalid remote task pid: ${pid}`);
+    }
+    // Only force-write 143 when we actually signaled a live group (or nothing
+    // left a code). Never `echo 143` over a real completed-run exit code.
+    return (`if kill -TERM -- -${pid} 2>/dev/null; then ` +
+        `sleep 1; kill -KILL -- -${pid} 2>/dev/null || true; ` +
+        `echo 143 > ${remoteExit}; echo SIGNALED; ` +
+        `elif kill -0 -- -${pid} 2>/dev/null; then ` +
+        `exit 1; ` +
+        `else ` +
+        `code=$(cat ${remoteExit} 2>/dev/null | tr -d '[:space:]'); ` +
+        `if [ -n "$code" ]; then echo "ALREADY $code"; ` +
+        `else echo 143 > ${remoteExit}; echo GONE; fi; ` +
+        `fi`);
+}
+/**
+ * Stop a running host task from the origin machine (`agents hosts stop <id>`).
+ *
+ * Unlike {@link terminateDispatchedTask} (rollback cleanup after a failed
+ * persist), this keeps the remote log so `agents hosts logs <id>` still works,
+ * writes a terminal `.exit` marker only when we actually stopped a live group
+ * (or no code existed), and never clobbers a real completed-run exit code.
+ */
+export function stopDispatchedTask(task) {
+    if (task.status !== 'running') {
+        throw new Error(`Task ${task.id} is already ${task.status}`);
+    }
+    if (!task.pid) {
+        throw new Error(`Cannot stop remote task ${task.id}: launch returned no PID.`);
+    }
+    const command = buildStopRemoteCommand(task.pid, task.remoteExit);
+    const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true });
+    if (result.code !== 0) {
+        throw new Error(`Failed to stop remote task ${task.id} on ${task.host}: ` +
+            `${(result.stderr || result.stdout).trim() || 'ssh error'}`);
+    }
+    const line = result.stdout.trim().split('\n').pop() ?? '';
+    let code = 143;
+    if (line.startsWith('ALREADY ')) {
+        const parsed = parseInt(line.slice('ALREADY '.length), 10);
+        if (Number.isFinite(parsed))
+            code = parsed;
+    }
+    // SIGNALED / GONE / ALREADY all end with a terminal local record.
+    return updateTask(task.id, terminalPatch(code)) ?? { ...task, ...terminalPatch(code) };
+}
 /**
  * The launch + task-record + optional follow core. Both `dispatchToHost` (run)
  * and `dispatchAgentsCommand` (teams) build their `forwardedArgs` and call here,
@@ -117,7 +176,10 @@ async function launchDetached(host, target, opts) {
     // Inner command run under a login shell so PATH resolves `agents`.
     const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd);
-    const inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
+    let inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
+    if (opts.copyCreds) {
+        inner = wrapHostCommandWithCredentials(inner, opts.copyCreds);
+    }
     // Outer: ensure dir, launch the login-shell wrapper as a new process-group
     // leader, and print that leader PID.
     const launch = `mkdir -p ${REMOTE_DIR}; ${buildDetachedLaunchCommand(inner)}`;
@@ -268,7 +330,10 @@ export async function runInteractiveOnHost(host, opts) {
         process.stderr.write(`[hosts] warning: ${w}\n`);
     const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd);
-    const remoteCmd = `${cwd}${invocation}`;
+    let remoteCmd = `${cwd}${invocation}`;
+    if (opts.copyCreds) {
+        remoteCmd = wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds);
+    }
     return sshStream(target, remoteCmd, { tty: process.stdin.isTTY, multiplex: true });
 }
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
@@ -288,6 +353,7 @@ export async function dispatchToHost(host, opts) {
         // On resume the remote session keeps its existing id; record that id so the
         // task stays mapped to the same session.
         sessionId: opts.resume ?? opts.sessionId,
+        copyCreds: opts.copyCreds,
     });
 }
 /**

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

@@ -1,10 +1,8 @@
 /**
  * Generic `--host` passthrough — the single choke point that runs an allowlisted
- * `agents <command>` on a remote host instead of locally, so read-only and
- * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
- * and the team lifecycle (`teams …`) all gain remote support with no per-command
- * code. Called once from `index.ts` before commander parses; returns `true` when
- * it handled the invocation (the local command must then NOT run).
+ * `agents <command>` on a remote host instead of locally. Called once from
+ * `index.ts` before commander parses; returns `true` when it handled the
+ * invocation (the local command must then NOT run).
  *
  * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
  * choke point already used everywhere, and it gives auth + encryption + host-key
@@ -12,17 +10,22 @@
  * long-running case — `teams start --watch` — dispatches detached so the remote
  * supervisor outlives a dropped connection.
  *
- * `run`, `sessions`, and `feed` are deliberately absent from the table below:
- * they own richer `--host` handling in their own command actions (detached run
- * dispatch or multi-host fan-out) and must fall through to it.
+ * Commands with their own richer `--host` handling (`run`/`sessions`/`feed`/
+ * `computer`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
+ * fall through to their local actions. Everything else either routes via this
+ * table or, when `--host`/`--device` is present, exits with a clear
+ * "not supported" message — never commander's raw `unknown option`.
  */
 /** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
 export declare function flagValue(args: string[], long: string, short?: string): string | undefined;
 /**
  * Route `agents <command> … --host <name>` to a remote if the command is
  * host-routable and a `--host` (or its `--device` alias) was given. Returns
- * `false` (run locally) when neither flag is present, the command isn't in the
- * table, or the target is this very machine.
+ * `false` (run locally) when neither flag is present, the command owns its own
+ * host handling, the target is this very machine, or placement flags need the
+ * local action. Returns `true` after printing a clear error when the flag is
+ * present on a command that is neither routable nor self-handling — so the user
+ * never sees commander's raw `unknown option '--host'`.
  *
  * @param command the resolved subcommand name (`process.argv`'s first non-flag).
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.