@phnx-labs/agents-cli 1.20.32 → 1.20.34

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/doctor-diff.js

@@ -29,6 +29,8 @@ import { pluginInstallDir, repairableManifestFields } from './plugin-marketplace
 import { markdownToToml } from './convert.js';
 import { resolveImports, supportsRulesImports } from './rules/compile.js';
 import { listCommandsInVersionHome, getVersionCommandsDir } from './commands.js';
+import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } from './command-skills.js';
+import { supports } from './capabilities.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './skills.js';
 import { listHooksInVersionHome, listHookEntriesFromDir } from './hooks.js';
 const RULES_DOC_FILENAME = 'README.md';
@@ -87,6 +89,15 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     const isToml = agentConfig.format === 'toml';
     const ext = isToml ? '.toml' : '.md';
     const homeDir = getVersionCommandsDir(agent, version);
+    // Command-as-skill agents (kimi, codex>=0.117, grok) install every command as a
+    // SKILL wrapper at <agentDir>/skills/<cmd>/SKILL.md, not a native command file.
+    // The compare must follow that or every command false-reports as drifted.
+    const asSkill = shouldInstallCommandAsSkill(agent, version);
+    // Agents that hold commands neither natively nor as skills (e.g. goose) must not
+    // report source commands as "missing" — they structurally can't take them.
+    if (!asSkill && !supports(agent, 'commands', version).ok)
+        return [];
+    const agentDir = path.join(getVersionHomePath(agent, version), agentConfigDirName(agent));
     const installed = new Set(listCommandsInVersionHome(agent, version));
     const layerBases = buildLayerBases(cwd, 'commands', { excludeProject });
     const sourceByName = new Map();
@@ -113,11 +124,24 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     const seen = new Set();
     for (const [name, src] of sourceByName) {
         seen.add(name);
-        const homePath = path.join(homeDir, `${name}${ext}`);
         if (!installed.has(name)) {
             rows.push({ kind: 'commands', name, status: 'missing', source: src.layer, sourcePath: src.path });
             continue;
         }
+        if (asSkill) {
+            // Compare against the installed command-skill wrapper, not a native path.
+            const matches = commandSkillMatches(agentDir, name, src.path);
+            rows.push({
+                kind: 'commands',
+                name,
+                status: matches ? 'ok' : 'diff',
+                source: src.layer,
+                sourcePath: src.path,
+                homePath: path.join(agentDir, 'skills', commandSkillName(name), 'SKILL.md'),
+            });
+            continue;
+        }
+        const homePath = path.join(homeDir, `${name}${ext}`);
         const installedContent = readSafe(homePath);
         const sourceContent = readSafe(src.path);
         if (installedContent == null || sourceContent == null) {
@@ -138,7 +162,10 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     for (const name of installed) {
         if (seen.has(name))
             continue;
-        rows.push({ kind: 'commands', name, status: 'extra', homePath: path.join(homeDir, `${name}${ext}`) });
+        const extraHome = asSkill
+            ? path.join(agentDir, 'skills', commandSkillName(name), 'SKILL.md')
+            : path.join(homeDir, `${name}${ext}`);
+        rows.push({ kind: 'commands', name, status: 'extra', homePath: extraHome });
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }

package/dist/lib/drift-sync.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
+ * action, shared by `agents status`, `agents doctor`, and the menu-bar "NEEDS
+ * SYNC" row.
+ *
+ * It composes existing pieces, re-implementing nothing:
+ *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
+ *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
+ *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
+ *   - heal({ mode: 'full' })       — the reconcile engine `doctor --fix` uses
+ *
+ * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
+ * a single "Sync all detected" both pulls `.system` and reconciles the chosen
+ * version homes. The security posture is preserved — the `.system` pull only ever
+ * happens on an explicit user choice here, never silently (see auto-pull-worker.ts
+ * for why system auto-pull is off by default).
+ */
+import { type VersionHealResult } from './heal.js';
+import { type UnifiedSyncStatus } from './sync-status.js';
+export interface DriftSyncOptions {
+    cwd?: string;
+    /** Reconcile everything detected with no prompts — the "kick it" path, also the
+     * non-TTY / menu-bar-launched-with-flag behavior. Pulls `.system` if behind. */
+    yes?: boolean;
+    /** Pre-computed status, to avoid a second scan when the caller already has one. */
+    status?: UnifiedSyncStatus;
+    /** Skip the drift summary — set by callers that already printed their own. */
+    quiet?: boolean;
+}
+export interface DriftSyncResult {
+    systemBehindBefore: number;
+    systemPulled: boolean;
+    healed: VersionHealResult[];
+    /** True when the user declined at the prompt (nothing was changed). */
+    cancelled: boolean;
+    /** True when there was no drift to act on in the first place. */
+    nothingToDo: boolean;
+}
+/**
+ * The unified "drift detected — sync now?" flow. Returns a structured result so
+ * callers (menu-bar, doctor) can report without re-scanning.
+ */
+export declare function promptDriftSync(opts?: DriftSyncOptions): Promise<DriftSyncResult>;

package/dist/lib/drift-sync.js

@@ -0,0 +1,179 @@
+/**
+ * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
+ * action, shared by `agents status`, `agents doctor`, and the menu-bar "NEEDS
+ * SYNC" row.
+ *
+ * It composes existing pieces, re-implementing nothing:
+ *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
+ *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
+ *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
+ *   - heal({ mode: 'full' })       — the reconcile engine `doctor --fix` uses
+ *
+ * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
+ * a single "Sync all detected" both pulls `.system` and reconciles the chosen
+ * version homes. The security posture is preserved — the `.system` pull only ever
+ * happens on an explicit user choice here, never silently (see auto-pull-worker.ts
+ * for why system auto-pull is off by default).
+ */
+import chalk from 'chalk';
+import { select, confirm } from '@inquirer/prompts';
+import { AGENTS } from './agents.js';
+import { pullRepo } from './git.js';
+import { heal } from './heal.js';
+import { promptAgentVersionSelection } from './versions.js';
+import { isInteractiveTerminal, isPromptCancelled } from '../commands/utils.js';
+import { computeSyncStatus, } from './sync-status.js';
+const agentName = (id) => AGENTS[id]?.name ?? id;
+/** "claude@2.1.170  2 drifted · 1 missing" for one version. */
+function versionLine(v) {
+    const bits = [];
+    if (v.counts.drifted)
+        bits.push(`${v.counts.drifted} drifted`);
+    if (v.counts.missing)
+        bits.push(`${v.counts.missing} missing`);
+    const label = `${agentName(v.agent)}@${v.version}`;
+    return `  ${label.padEnd(28)} ${chalk.yellow(bits.join(' · '))}`;
+}
+/** Render the drift summary (system freshness + each version owed a sync). */
+function renderSummary(status, needing) {
+    console.log(chalk.bold('\nSync status'));
+    if (status.system.behind > 0) {
+        console.log(`  ${'.system repo'.padEnd(28)} ${chalk.yellow(`${status.system.behind} commit${status.system.behind === 1 ? '' : 's'} behind`)} ${chalk.gray('— pull recommended')}`);
+    }
+    for (const v of needing)
+        console.log(versionLine(v));
+    if (status.totals.orphan > 0) {
+        console.log(chalk.gray(`  (${status.totals.orphan} orphan${status.totals.orphan === 1 ? '' : 's'} — run \`agents prune cleanup\`)`));
+    }
+}
+/** Fast-forward the `.system` repo. Returns whether it actually moved. */
+async function pullSystem(status) {
+    if (status.system.behind <= 0)
+        return false;
+    const res = await pullRepo(status.system.dir);
+    if (res.success) {
+        console.log(chalk.green(`Pulled .system (+${status.system.behind}).`));
+        return true;
+    }
+    console.log(chalk.red(`Could not pull .system: ${res.error ?? 'unknown error'}`));
+    return false;
+}
+/** Reconcile a set of versions grouped by agent via the shared heal engine. */
+async function healVersions(versionsByAgent, cwd) {
+    const out = [];
+    for (const [agent, versions] of versionsByAgent) {
+        if (versions.length === 0)
+            continue;
+        const res = await heal({ mode: 'full', cwd, agent, versions });
+        out.push(...res.versions);
+    }
+    return out;
+}
+/** Report which agents received what after a heal. */
+function reportHealed(healed) {
+    const touched = healed.filter((v) => v.healed.length > 0);
+    if (touched.length === 0) {
+        console.log(chalk.gray('Nothing to reconcile — homes already matched sources.'));
+        return;
+    }
+    const total = touched.reduce((n, v) => n + v.healed.length, 0);
+    const agents = [...new Set(touched.map((v) => agentName(v.agent)))].join(', ');
+    console.log(chalk.green(`Synced ${total} resource${total === 1 ? '' : 's'} to ${agents}.`));
+}
+function groupNeeding(needing) {
+    const m = new Map();
+    for (const v of needing) {
+        const list = m.get(v.agent) ?? [];
+        list.push(v.version);
+        m.set(v.agent, list);
+    }
+    return m;
+}
+/**
+ * The unified "drift detected — sync now?" flow. Returns a structured result so
+ * callers (menu-bar, doctor) can report without re-scanning.
+ */
+export async function promptDriftSync(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const status = opts.status ?? (await computeSyncStatus({ cwd }));
+    const needing = status.agents.filter((a) => a.needsSync);
+    const systemBehind = status.system.behind;
+    const base = {
+        systemBehindBefore: systemBehind,
+        systemPulled: false,
+        healed: [],
+        cancelled: false,
+        nothingToDo: false,
+    };
+    if (systemBehind <= 0 && needing.length === 0) {
+        console.log(chalk.green('Everything is in sync.'));
+        return { ...base, nothingToDo: true };
+    }
+    if (!opts.quiet)
+        renderSummary(status, needing);
+    // Non-interactive OR explicit --yes: reconcile everything detected.
+    if (opts.yes || !isInteractiveTerminal()) {
+        if (!opts.yes) {
+            // Non-TTY without --yes: report, don't act, don't throw.
+            console.log(chalk.gray('\nRun `agents status --yes` to sync, or `agents status` in a terminal to choose.'));
+            return base;
+        }
+        const systemPulled = await pullSystem(status);
+        const healed = await healVersions(groupNeeding(needing), cwd);
+        reportHealed(healed);
+        return { ...base, systemPulled, healed };
+    }
+    // Interactive gate.
+    let choice;
+    try {
+        choice = await select({
+            message: 'Sync now?',
+            choices: [
+                { name: 'Sync all detected', value: 'all' },
+                { name: 'Choose agents & resources', value: 'choose' },
+                { name: 'No', value: 'no' },
+            ],
+            default: 'all',
+        });
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return { ...base, cancelled: true };
+        throw err;
+    }
+    if (choice === 'no')
+        return { ...base, cancelled: true };
+    if (choice === 'all') {
+        const systemPulled = await pullSystem(status);
+        const healed = await healVersions(groupNeeding(needing), cwd);
+        reportHealed(healed);
+        return { ...base, systemPulled, healed };
+    }
+    // choice === 'choose': optional .system pull, then per-agent/version selection.
+    let systemPulled = false;
+    if (systemBehind > 0) {
+        try {
+            const pull = await confirm({ message: `Pull .system (${systemBehind} behind) first?`, default: true });
+            if (pull)
+                systemPulled = await pullSystem(status);
+        }
+        catch (err) {
+            if (!isPromptCancelled(err))
+                throw err;
+            return { ...base, systemPulled, cancelled: true };
+        }
+    }
+    const needingAgents = [...new Set(needing.map((a) => a.agent))];
+    let selection;
+    try {
+        selection = await promptAgentVersionSelection(needingAgents);
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return { ...base, systemPulled, cancelled: true };
+        throw err;
+    }
+    const healed = await healVersions(selection.versionSelections, cwd);
+    reportHealed(healed);
+    return { ...base, systemPulled, healed };
+}

package/dist/lib/exec.d.ts

@@ -189,6 +189,21 @@ export declare function nativeResume(agent: AgentId): boolean;
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */
 export declare function execAgent(options: ExecOptions): Promise<number>;
+/**
+ * Resolve how to spawn a shim target for a platform. Pure — testable on any host.
+ *
+ * POSIX always execs the binary directly (no shell). On Windows a bare
+ * (non-absolute) name or a `.cmd` companion goes through the shell so cmd.exe
+ * resolves it via PATHEXT — the common, `.cmd`-present path; an absolute `.cmd`
+ * or extensionless path is exec'd through the shell / directly. npm always ships
+ * a `<cmd>.cmd` companion on Windows, so the runnable target `execShimPassthrough`
+ * hands us is the `.cmd` (never a bare `.ps1`).
+ */
+export declare function resolveShimSpawn(platform: NodeJS.Platform, binary: string, extraArgs: string[]): {
+    command: string;
+    args: string[];
+    shell: boolean;
+};
 /**
  * Transparent passthrough exec for generated shims — the node-side delegate that
  * Windows `.cmd` shims call. Resolves the active version (explicit pin, else

package/dist/lib/exec.js

@@ -374,15 +374,6 @@ export const AGENT_COMMANDS = {
             edit: [],
         },
     },
-    roo: {
-        base: ['roo'],
-        promptFlag: 'positional',
-        modeFlags: {
-            plan: ['--mode', 'architect'],
-            edit: ['--mode', 'code'],
-        },
-        modelFlag: '--model',
-    },
     // TODO: --output-format json is documented but currently broken upstream
     // ("flags provided but not defined: -output-format"). Track resolution at
     // https://github.com/google-antigravity/antigravity-cli/issues/7 before
@@ -665,6 +656,25 @@ export async function execAgent(options) {
     const { exitCode } = await spawnAgent(options);
     return exitCode;
 }
+/**
+ * Resolve how to spawn a shim target for a platform. Pure — testable on any host.
+ *
+ * POSIX always execs the binary directly (no shell). On Windows a bare
+ * (non-absolute) name or a `.cmd` companion goes through the shell so cmd.exe
+ * resolves it via PATHEXT — the common, `.cmd`-present path; an absolute `.cmd`
+ * or extensionless path is exec'd through the shell / directly. npm always ships
+ * a `<cmd>.cmd` companion on Windows, so the runnable target `execShimPassthrough`
+ * hands us is the `.cmd` (never a bare `.ps1`).
+ */
+export function resolveShimSpawn(platform, binary, extraArgs) {
+    if (platform === 'win32') {
+        // Use win32 path semantics regardless of the host running this (the platform
+        // is the parameter, not process.platform) so `C:\...` reads as absolute.
+        const useShell = !path.win32.isAbsolute(binary) || binary.endsWith('.cmd');
+        return { command: binary, args: extraArgs, shell: useShell };
+    }
+    return { command: binary, args: extraArgs, shell: false };
+}
 /**
  * Transparent passthrough exec for generated shims — the node-side delegate that
  * Windows `.cmd` shims call. Resolves the active version (explicit pin, else
@@ -691,9 +701,9 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     // mode/effort are required by ExecOptions but unused by buildExecEnv (which only
     // derives the per-version config-dir env); pass the agent's default to satisfy the type.
     const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto' });
-    const useShell = process.platform === 'win32' && (!path.isAbsolute(binary) || binary.endsWith('.cmd'));
+    const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {
-        const child = spawn(binary, [...launchArgs, ...rawArgs], { cwd, stdio: 'inherit', env, shell: useShell });
+        const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
         child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
         child.on('error', (err) => {
             process.stderr.write(`agents: failed to launch ${agent}: ${err.message}\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;

package/dist/lib/hosts/option.js

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+/** Attach the standard `--host` flag family to a command and return it (chainable). */
+export function addHostOption(cmd) {
+    return cmd
+        .option('-H, --host <name>', 'Run this command on a registered host (or user@host) over SSH instead of locally. See `agents hosts`.')
+        .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
+        .option('--no-tty', 'Force non-interactive output for --host runs even from a terminal.')
+        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');
+}