@phnx-labs/agents-cli 1.20.62 → 1.20.63

package/dist/lib/daemon.js

@@ -419,6 +419,8 @@ export async function runDaemon() {
                 log('INFO', `sessions sync: pushed ${r.pushed}, pulled ${r.pulled}, merged ${r.merged}` +
                     (r.errors.length ? `, ${r.errors.length} error(s): ${r.errors[0]}` : ''));
             }
+            if (r.warnings.length)
+                log('WARN', `sessions sync: ${r.warnings[0]}`);
         }
         catch (err) {
             log('ERROR', `sessions sync failed: ${err.message}`);

package/dist/lib/devices/fleet.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Fleet-wide device operations — pick online targets and run a command on each.
+ *
+ * Used by `agents fleet update` / `agents fleet run` (aliases of the same
+ * subcommands under `agents devices`). Offline devices are skipped with a
+ * reason so a single dead node never blocks the rest of the rollout. Per-device
+ * throws (misconfigured auth, etc.) become `failed` rows — they never abort
+ * the remaining devices.
+ */
+import type { DeviceProfile, DeviceRegistry } from './registry.js';
+export type FleetSkipReason = 'offline' | 'no-address';
+/** npm dist-tags / semver pins only — rejects shell metacharacters. */
+export declare const FLEET_VERSION_RE: RegExp;
+export interface FleetTarget {
+    device: DeviceProfile;
+    /** When set, this device is not reached (skip with reason). */
+    skip?: FleetSkipReason;
+}
+export interface FleetRunResult {
+    name: string;
+    status: 'ok' | 'failed' | 'skipped';
+    code: number | null;
+    reason?: FleetSkipReason | string;
+    /** Truncated combined stderr/stdout for failures. */
+    detail?: string;
+}
+/**
+ * Classify each registered device for a fleet operation.
+ *
+ * - Tailscale-offline → skip `offline`
+ * - No address → skip `no-address`
+ * - Everything else is a target (including this machine, reached over ssh when
+ *   it has a registry address — same path as any other box).
+ */
+export declare function planFleetTargets(reg: DeviceRegistry): FleetTarget[];
+/** Human label for a skip reason. */
+export declare function skipLabel(reason: FleetSkipReason): string;
+/**
+ * Run `cmd` on one device via the same ssh path as `agents ssh <name> …`.
+ * Captures stdout/stderr (not inherited) so the fleet table can summarize.
+ * Throws from buildSshInvocation are returned as a non-zero result so a single
+ * misconfigured device cannot abort the fleet loop.
+ */
+export declare function runOnDevice(device: DeviceProfile, cmd: string[], opts?: {
+    timeoutMs?: number;
+}): {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
+ * Rejects anything that is not a plain npm version/tag token so a version pin
+ * cannot inject shell metacharacters into the remote command line.
+ */
+export declare function upgradeCommand(version?: string): string[];
+/**
+ * Execute a command across planned targets. Pure orchestration over
+ * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
+ * the runner are recorded as `failed` so one bad device never aborts the rest.
+ */
+export declare function runFleet(targets: FleetTarget[], cmd: string[], runner?: typeof runOnDevice): FleetRunResult[];

package/dist/lib/devices/fleet.js

@@ -0,0 +1,128 @@
+/**
+ * Fleet-wide device operations — pick online targets and run a command on each.
+ *
+ * Used by `agents fleet update` / `agents fleet run` (aliases of the same
+ * subcommands under `agents devices`). Offline devices are skipped with a
+ * reason so a single dead node never blocks the rest of the rollout. Per-device
+ * throws (misconfigured auth, etc.) become `failed` rows — they never abort
+ * the remaining devices.
+ */
+import { spawnSync } from 'child_process';
+import { buildSshInvocation, sshTargetFor, writeAskpassShim } from './connect.js';
+/** npm dist-tags / semver pins only — rejects shell metacharacters. */
+export const FLEET_VERSION_RE = /^[A-Za-z0-9._-]+$/;
+/**
+ * Classify each registered device for a fleet operation.
+ *
+ * - Tailscale-offline → skip `offline`
+ * - No address → skip `no-address`
+ * - Everything else is a target (including this machine, reached over ssh when
+ *   it has a registry address — same path as any other box).
+ */
+export function planFleetTargets(reg) {
+    const names = Object.keys(reg).sort();
+    return names.map((name) => {
+        const device = reg[name];
+        if (device.tailscale && !device.tailscale.online) {
+            return { device, skip: 'offline' };
+        }
+        try {
+            sshTargetFor(device);
+        }
+        catch {
+            return { device, skip: 'no-address' };
+        }
+        return { device };
+    });
+}
+/** Human label for a skip reason. */
+export function skipLabel(reason) {
+    switch (reason) {
+        case 'offline':
+            return 'offline';
+        case 'no-address':
+            return 'no address';
+    }
+}
+/**
+ * Run `cmd` on one device via the same ssh path as `agents ssh <name> …`.
+ * Captures stdout/stderr (not inherited) so the fleet table can summarize.
+ * Throws from buildSshInvocation are returned as a non-zero result so a single
+ * misconfigured device cannot abort the fleet loop.
+ */
+export function runOnDevice(device, cmd, opts = {}) {
+    try {
+        const shim = writeAskpassShim();
+        const { args, env } = buildSshInvocation(device, cmd, shim);
+        const res = spawnSync('ssh', args, {
+            encoding: 'utf-8',
+            env: { ...process.env, ...env },
+            timeout: opts.timeoutMs ?? 600_000,
+        });
+        return {
+            code: res.status,
+            stdout: res.stdout?.toString() ?? '',
+            stderr: (res.stderr?.toString() ?? '') + (res.error ? String(res.error.message) : ''),
+        };
+    }
+    catch (err) {
+        return {
+            code: 1,
+            stdout: '',
+            stderr: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
+ * Rejects anything that is not a plain npm version/tag token so a version pin
+ * cannot inject shell metacharacters into the remote command line.
+ */
+export function upgradeCommand(version) {
+    if (version !== undefined && version !== '') {
+        if (!FLEET_VERSION_RE.test(version)) {
+            throw new Error(`Invalid version '${version}'. Use a semver or dist-tag (letters, digits, . _ - only).`);
+        }
+        return ['agents', 'upgrade', version, '--yes'];
+    }
+    return ['agents', 'upgrade', '--yes'];
+}
+/**
+ * Execute a command across planned targets. Pure orchestration over
+ * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
+ * the runner are recorded as `failed` so one bad device never aborts the rest.
+ */
+export function runFleet(targets, cmd, runner = runOnDevice) {
+    const results = [];
+    for (const t of targets) {
+        if (t.skip) {
+            results.push({
+                name: t.device.name,
+                status: 'skipped',
+                code: null,
+                reason: t.skip,
+            });
+            continue;
+        }
+        try {
+            const res = runner(t.device, cmd);
+            const ok = res.code === 0;
+            const detail = (res.stderr || res.stdout).trim().slice(0, 200);
+            results.push({
+                name: t.device.name,
+                status: ok ? 'ok' : 'failed',
+                code: res.code,
+                detail: ok ? undefined : detail || undefined,
+            });
+        }
+        catch (err) {
+            results.push({
+                name: t.device.name,
+                status: 'failed',
+                code: 1,
+                detail: (err instanceof Error ? err.message : String(err)).slice(0, 200),
+            });
+        }
+    }
+    return results;
+}

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.