@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/CHANGELOG.md

@@ -38,6 +38,9 @@
 - Built on the **live-home diff**, not the staleness manifest, so it catches drift the sync fast-guard can't. Heal **fills and fixes, never deletes** (orphans stay `agents prune cleanup`'s job), excludes the project layer (the global home isn't reconciled against per-cwd project resources), and **verifies after writing** — it only claims resources that actually reconciled, so repeated runs converge instead of "fixing" the same item forever.
 - `.source` now records the plugin version at pull time, a baseline that lets the safe path tell an untouched mirror (fast-forward) from a user edit (leave alone).
 - **`agents doctor` overview now covers every installed version, not just defaults.** Sync status and orphans previously reported only each agent's default version — so a stale NON-default version (the exact rot `--fix` heals) was invisible in the readout. Each version is now listed with its default marked. The **Agent CLIs** list also stops nagging: it shows the agents you actually run (ready, or managed-but-broken) and collapses the rest of the supported catalog to a single `+N more supported …` hint instead of a column of red "not installed" lines for tools you never adopted.
+- **Says exactly WHAT is out of sync — plugins first.** A stale version in the overview now lists the specifics under it, prioritizing plugins and their bundled content: `plugin code — 0.6.1→0.7.0, missing skills: ship, learn`. The plugin diff went from presence-only ("installed: yes") to **content-aware** — it compares the version's marketplace mirror against the central source and surfaces a stale mirror version, a Claude-invalid manifest, and the plugin's own skills/commands that never reached the mirror (the system-repo content that matters most). `agents doctor <agent>@<version>` shows the same detail per plugin row.
+- **Fixed a false "drift" that could never be reconciled:** a hook's `.md`/`.rst` doc sibling (e.g. `git-guard.md` next to `git-guard.sh`) was wrongly treated as the hook's runtime *data file*, so the installer's correct omission of docs showed as perpetual drift in `doctor` (and as an un-healable item under `--fix`). Docs are no longer counted as hook data; structured siblings (`.yaml`/`.json`/...) still are.
+- **Corrected a false promise in the sync-status readout.** Stale/cold versions used to say "will sync on next launch" / "first launch will populate" — but version homes are NOT reconciled on launch (the shim hot path only resolves a version and compiles project-scoped resources; v15/v16 moved version-home reconciliation to management commands). The readout now states the fact ("sources changed since last sync" / "never synced") and points at the real fix: `agents doctor <agent>@<version> --fix` or `agents sync <agent>@<version>`.
 
 **Secrets prompt policy: human-readable `always` / `daily`, and `secrets list` now shows it**
 

package/dist/commands/doctor.js

@@ -14,6 +14,36 @@ import { heal, healChangedAnything } from '../lib/heal.js';
 import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
+// Lines naming exactly what's out of sync for a version, plugins prioritized:
+// each divergent plugin gets its own line with specifics (stale mirror version,
+// invalid manifest, or the bundled skills/commands missing from the mirror —
+// the system-repo plugin content that matters most). Other kinds collapse to
+// compact counts so the readout stays scannable.
+function divergenceLines(report) {
+    const lines = [];
+    for (const p of report.kinds.plugins) {
+        if (p.status === 'missing')
+            lines.push(`plugin ${p.name} — not installed`);
+        else if (p.status === 'diff')
+            lines.push(`plugin ${p.name} — ${p.detail ?? 'mirror drifted'}`);
+    }
+    const counts = [];
+    for (const kind of ['commands', 'skills', 'hooks', 'rules', 'mcp', 'permissions', 'subagents']) {
+        const rows = report.kinds[kind];
+        const miss = rows.filter((r) => r.status === 'missing').length;
+        const dif = rows.filter((r) => r.status === 'diff').length;
+        const bits = [];
+        if (miss)
+            bits.push(`${miss} missing`);
+        if (dif)
+            bits.push(`${dif} drifted`);
+        if (bits.length)
+            counts.push(`${kind} ${bits.join('/')}`);
+    }
+    if (counts.length)
+        lines.push(counts.join(' · '));
+    return lines;
+}
 function checkSyncStatus(cwd) {
     const rows = [];
     // Every installed version, not just the default — a stale NON-default version
@@ -27,7 +57,16 @@ function checkSyncStatus(cwd) {
             const status = !manifest
                 ? 'never-synced'
                 : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
-            rows.push({ agent, version, status, isDefault: version === def });
+            const row = { agent, version, status, isDefault: version === def };
+            if (status === 'stale') {
+                // Resolve the specifics against non-project layers (the global home is
+                // never reconciled against per-cwd project resources).
+                const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
+                const lines = divergenceLines(report);
+                if (lines.length)
+                    row.divergence = lines;
+            }
+            rows.push(row);
         }
     }
     return rows;
@@ -97,6 +136,7 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
         console.log(chalk.gray('  (no versions installed; add one with `agents add <agent>@<version>`)'));
     }
     else {
+        let anyOutOfSync = false;
         for (const row of syncRows) {
             const tag = row.isDefault ? chalk.gray(' (default)') : '';
             const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}${tag}`;
@@ -104,12 +144,24 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
                 console.log(`  ${chalk.green('fresh')}  ${label}`);
             }
             else if (row.status === 'stale') {
-                console.log(`  ${chalk.yellow('stale')}  ${label}  ${chalk.gray('— will sync on next launch')}`);
+                anyOutOfSync = true;
+                console.log(`  ${chalk.yellow('stale')}  ${label}  ${chalk.gray('— sources changed since last sync')}`);
+                for (const line of row.divergence ?? []) {
+                    console.log(chalk.gray(`           ${line}`));
+                }
             }
             else {
-                console.log(`  ${chalk.gray('cold ')}  ${label}  ${chalk.gray('— never synced; first launch will populate')}`);
+                anyOutOfSync = true;
+                console.log(`  ${chalk.gray('cold ')}  ${label}  ${chalk.gray('— never synced')}`);
             }
         }
+        // Launching does NOT reconcile a version home — the shim hot path only
+        // resolves a version and compiles project-scoped resources (shims.ts v15/v16).
+        // Version homes are reconciled only by management commands, so point at one
+        // rather than promising an auto-sync that never happens.
+        if (anyOutOfSync) {
+            console.log(chalk.gray('  Reconcile with `agents doctor <agent>@<version> --fix` or `agents sync <agent>@<version>` (not applied on launch).'));
+        }
     }
     console.log();
     console.log(chalk.bold('Orphans (installed versions)'));
@@ -261,7 +313,8 @@ function renderKindSection(kind, rows, layers, options) {
     }
     for (const r of visible) {
         const src = sourceLabel(r, layers);
-        console.log(`    ${statusLabel(r.status)}  ${r.name.padEnd(28)} ${src}`);
+        const detail = r.detail ? chalk.gray(`  ${r.detail}`) : '';
+        console.log(`    ${statusLabel(r.status)}  ${r.name.padEnd(28)} ${src}${detail}`);
         if (options.showDiff && r.status === 'diff' && r.sourcePath && r.homePath) {
             const expected = readExpectedForDiff(kind, r);
             const actual = safeRead(r.homePath);

package/dist/commands/exec.d.ts

@@ -5,7 +5,7 @@
  * or headlessly. Supports profile resolution, version rotation, secrets
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
-import type { Command } from 'commander';
+import { type Command } from 'commander';
 /**
  * Build the LoopConfig the driver consumes from CLI flags and/or a workflow's
  * `loop:` frontmatter block (issue #332). Returns undefined when neither source

package/dist/commands/exec.js

@@ -5,6 +5,7 @@
  * or headlessly. Supports profile resolution, version rotation, secrets
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
+import { Option } from 'commander';
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { parseLoopInterval } from '../lib/loop.js';
@@ -117,7 +118,8 @@ export function registerRunCommand(program) {
         .option('--quiet', 'Suppress preamble (rotation banner, "Running:" line). Useful when piping JSON events to a parser.', false)
         .option('--headless', 'Force headless mode. Auto-enabled when a prompt is provided; pass explicitly to stay headless with no prompt (reads the prompt from stdin).', false)
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
-        .option('--session-id <id>', 'Resume a previous conversation (Claude only)')
+        .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. Pair with a prompt to continue headlessly.')
+        .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
         .option('--verbose', 'Show detailed execution logs')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,gemini). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
@@ -130,7 +132,14 @@ export function registerRunCommand(program) {
         .option('--max-iterations <n>', 'Loop hard cap: stop after N iterations (stoppedBy: max). Loop only.')
         .option('--budget <tokens>', 'Loop token hard-cap: stop once cumulative tokens reach this (stoppedBy: budget), enforced outside the agent. Loop only.')
         .option('--until <signal>', 'Loop stop condition. `signal` reads <runDir>/loop-signal.json {continue,reason} each iteration; absent or continue:false stops (fail-closed). Loop only.')
-        .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.');
+        .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.')
+        .option('--host <name>', 'Offload this run onto a registered agent host over SSH instead of running locally. See `agents hosts`.')
+        .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
+        .option('--no-follow', 'With --host, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
+        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');
+    // `--on` and `--computer` are hidden aliases of `--host` — same behavior.
+    runCmd.addOption(new Option('--on <name>', 'Alias of --host.').hideHelp());
+    runCmd.addOption(new Option('--computer <name>', 'Alias of --host.').hideHelp());
     setHelpSections(runCmd, {
         examples: `
       # Headless, read-only: investigate or summarize without writing files
@@ -171,7 +180,7 @@ export function registerRunCommand(program) {
 
       Fallback: --fallback codex,gemini retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
-      Resume: --session-id <id> continues a prior Claude conversation.
+      Resume: --resume <id> continues a prior conversation (full or partial id; omit to pick interactively). claude/codex resume natively; others replay via a /continue first message. Add a prompt to continue headlessly.
 
       Passthrough: everything after -- is forwarded verbatim to the underlying agent CLI.
         agents run kimi -- --plan --some-native-flag value
@@ -182,6 +191,61 @@ export function registerRunCommand(program) {
         // Use command.args (all positional strings) and strip the declared positional args from the front.
         const declaredArgCount = prompt !== undefined ? 2 : 1;
         const passthroughArgs = command.args.slice(declaredArgCount);
+        // --host/--on/--computer: offload this run onto a registered agent host
+        // over SSH instead of running locally. The three flags are aliases.
+        const hostGiven = [options.host, options.on, options.computer].filter((v) => !!v);
+        if (hostGiven.length > 0) {
+            if (new Set(hostGiven).size > 1) {
+                console.error(chalk.red('Conflicting --host/--on/--computer values — pass just one.'));
+                process.exit(1);
+            }
+            const hostName = hostGiven[0];
+            if (prompt === undefined) {
+                console.error(chalk.red('A prompt is required for host runs: agents run <agent> "<task>" --host <name>'));
+                process.exit(1);
+            }
+            const { resolveHost, resolveHostByCap } = await import('../lib/hosts/registry.js');
+            const { dispatchToHost } = await import('../lib/hosts/dispatch.js');
+            let host = await resolveHost(hostName);
+            if (!host) {
+                // Not a host name — try capability routing (e.g. --host gpu). A
+                // "Multiple hosts tagged…" error is actionable and must surface;
+                // only "no host tagged" falls through to the generic unknown-host msg.
+                try {
+                    host = await resolveHostByCap(hostName, options.any);
+                }
+                catch (e) {
+                    const msg = e.message ?? '';
+                    if (msg.startsWith('Multiple hosts')) {
+                        console.error(chalk.red(msg));
+                        process.exit(1);
+                    }
+                }
+            }
+            if (!host) {
+                console.error(chalk.red(`Unknown host "${hostName}". List hosts: agents hosts list`));
+                process.exit(1);
+            }
+            try {
+                const { exitCode } = await dispatchToHost(host, {
+                    agent: agentSpec.split('@')[0],
+                    prompt,
+                    mode: options.mode,
+                    model: options.model,
+                    remoteCwd: options.remoteCwd,
+                    follow: options.follow !== false,
+                });
+                if (options.follow === false) {
+                    console.log(chalk.green(`Dispatched to ${host.name}.`) + chalk.gray(' Track: agents hosts ps · Follow: agents hosts logs <id> -f'));
+                    process.exit(0);
+                }
+                process.exit(exitCode === undefined || exitCode === -1 ? 1 : exitCode);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         // --resume-checkpoint short-circuits normal dispatch entirely: the
         // checkpoint already carries the agent, version, prompt, session id,
         // iteration, and loop config of the killed run. Reconstruct ExecOptions
@@ -260,11 +324,12 @@ export function registerRunCommand(program) {
             process.stderr.write(chalk.gray(`[loop] stopped: ${result.stoppedBy} after ${result.iterations} iteration(s), ${result.tokens} tokens\n`));
             process.exit(loopExitCode(result.stoppedBy));
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
             import('../lib/secrets/bundles.js'),
+            import('../lib/secrets/remote.js'),
             import('../lib/rotate.js'),
             import('../lib/versions.js'),
             import('../lib/plugins.js'),
@@ -489,6 +554,112 @@ export function registerRunCommand(program) {
             }
         }
         version = resolveVersionAlias(agent, version);
+        // --resume: resolve a prior conversation and rewrite the run target to
+        // continue it. `version` here is already the alias-resolved candidate-version
+        // FILTER (undefined for default/any, concrete for @latest/@oldest/@x.y.z);
+        // it is replaced below by the chosen session's OWN version (isolation).
+        let resumeNative = false;
+        let resumeSessionId;
+        let forceInteractive = false;
+        if (options.resume !== undefined) {
+            if (options.sessionId) {
+                console.error(chalk.red('--resume and --session-id are mutually exclusive. --session-id CREATES a session with a fixed id; --resume continues an existing one.'));
+                process.exit(1);
+            }
+            if (options.loop || options.fallback || options.resumeCheckpoint) {
+                console.error(chalk.red('--resume cannot be combined with --loop, --fallback, or --resume-checkpoint (those are separate continuation mechanisms).'));
+                process.exit(1);
+            }
+            const { findSessionsById } = await import('../lib/session/db.js');
+            const { discoverSessions } = await import('../lib/session/discover.js');
+            const { pickSessionInteractive } = await import('./sessions.js');
+            const { buildContinuePrompt } = await import('../lib/loop.js');
+            // Freshen the index for this agent before any lookup (incremental, cached).
+            // AgentId is wider than SessionAgentId (cursor/amp/… keep no transcripts);
+            // those simply yield no matches and fall through to the not-found error.
+            const sessionAgent = agent;
+            await discoverSessions({ agent: sessionAgent, version });
+            // Resume is interactive unless a follow-on prompt makes it headless.
+            const wantsInteractive = resolveInteractive({ interactive: options.interactive, headless: options.headless, prompt });
+            const idArg = typeof options.resume === 'string' ? options.resume.trim() : '';
+            let scopeCwd;
+            try {
+                scopeCwd = fs.realpathSync(cwd);
+            }
+            catch {
+                scopeCwd = cwd;
+            }
+            let session;
+            if (idArg) {
+                let matches = findSessionsById(idArg, { agent: sessionAgent, version, cwd: scopeCwd });
+                if (matches.length === 0) {
+                    const wide = findSessionsById(idArg, { agent: sessionAgent, version });
+                    if (wide.length > 0) {
+                        if (!options.quiet)
+                            process.stderr.write(chalk.gray(`No match for "${idArg}" in this project; widened to all projects.\n`));
+                        matches = wide;
+                    }
+                }
+                if (matches.length === 0) {
+                    console.error(chalk.red(`No ${agent} session matching "${idArg}".`));
+                    console.error(chalk.gray(`Browse sessions: agents sessions ${idArg}`));
+                    process.exit(1);
+                }
+                else if (matches.length === 1) {
+                    session = matches[0];
+                }
+                else if (wantsInteractive) {
+                    const picked = await pickSessionInteractive(matches, `Multiple sessions match "${idArg}":`);
+                    if (!picked)
+                        process.exit(0);
+                    session = picked.session;
+                }
+                else {
+                    console.error(chalk.red(`"${idArg}" is ambiguous — ${matches.length} sessions match:`));
+                    for (const m of matches.slice(0, 10)) {
+                        console.error(chalk.gray(`  ${m.shortId}  ${m.timestamp.slice(0, 16).replace('T', ' ')}  ${m.topic ?? m.label ?? ''}`));
+                    }
+                    console.error(chalk.gray('Pass more of the id, or resume interactively (drop the prompt).'));
+                    process.exit(1);
+                }
+            }
+            else {
+                // Bare --resume: pick from recent sessions in scope. Needs a TTY.
+                if (!wantsInteractive) {
+                    console.error(chalk.red('--resume with no id needs an interactive terminal. Pass a session id (full or prefix), or run without --headless.'));
+                    process.exit(1);
+                }
+                const recent = await discoverSessions({ agent: sessionAgent, version, limit: 200 });
+                if (recent.length === 0) {
+                    console.error(chalk.red(`No ${agent} sessions found to resume in this project.`));
+                    console.error(chalk.gray('Browse all: agents sessions'));
+                    process.exit(1);
+                }
+                const picked = await pickSessionInteractive(recent, `Resume which ${agent} session?`);
+                if (!picked)
+                    process.exit(0);
+                session = picked.session;
+                forceInteractive = true; // bare resume always lands in the agent's TUI
+            }
+            // Pin to the chosen session's own version (the isolated HOME the transcript
+            // lives in) and route by tier.
+            version = session.version;
+            if (nativeResume(agent)) {
+                resumeNative = true;
+                resumeSessionId = session.id;
+                if (!options.quiet)
+                    process.stderr.write(chalk.gray(`Resuming ${agent} ${session.shortId} (native)${version ? ` @${version}` : ''}\n`));
+            }
+            else {
+                // Tier-2: launch fresh with a /continue <id> first message; the agent
+                // loads the transcript via `agents sessions <id>` and picks up.
+                prompt = buildContinuePrompt(session.id, prompt);
+                if (prompt.trim() === `/continue ${session.id}`)
+                    forceInteractive = true;
+                if (!options.quiet)
+                    process.stderr.write(chalk.gray(`Resuming ${agent} ${session.shortId} (/continue replay)${version ? ` @${version}` : ''}\n`));
+            }
+        }
         const configuredStrategy = getConfiguredRunStrategy(agent, cwd);
         const explicitStrategy = options.strategy ? normalizeRunStrategy(options.strategy) : null;
         if (options.strategy && !explicitStrategy) {
@@ -606,17 +777,28 @@ export function registerRunCommand(program) {
         // ones. Any resolution failure (missing keychain item, blocked exec ref)
         // aborts before spawn so the agent never sees a partial env.
         let secretsEnv = {};
-        for (const bundleName of options.secrets) {
+        for (const bundleRef of options.secrets) {
             try {
-                const { bundle, env: bundleEnv } = readAndResolveBundleEnv(bundleName, { caller: `agent ${agent}` });
-                const entries = describeBundle(bundle);
-                const counts = {};
-                for (const e of entries) {
-                    counts[e.kind] = (counts[e.kind] || 0) + 1;
+                const { bundle: bundleName, host } = splitBundleRef(bundleRef);
+                if (host) {
+                    // Remote bundle (`bundle@host`): resolve over SSH and inject
+                    // ephemerally — values never touch this machine's keychain or disk.
+                    const target = await resolveSshTarget(host);
+                    const bundleEnv = await remoteResolveEnv(target, bundleName);
+                    console.log(chalk.gray(`[secrets] Resolved ${bundleName}@${host}: ${Object.keys(bundleEnv).length} keys (remote, ephemeral)`));
+                    secretsEnv = { ...secretsEnv, ...bundleEnv };
+                }
+                else {
+                    const { bundle, env: bundleEnv } = readAndResolveBundleEnv(bundleName, { caller: `agent ${agent}` });
+                    const entries = describeBundle(bundle);
+                    const counts = {};
+                    for (const e of entries) {
+                        counts[e.kind] = (counts[e.kind] || 0) + 1;
+                    }
+                    const breakdown = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ');
+                    console.log(chalk.gray(`[secrets] Resolved ${bundleName}: ${entries.length} keys (${breakdown})`));
+                    secretsEnv = { ...secretsEnv, ...bundleEnv };
                 }
-                const breakdown = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ');
-                console.log(chalk.gray(`[secrets] Resolved ${bundleName}: ${entries.length} keys (${breakdown})`));
-                secretsEnv = { ...secretsEnv, ...bundleEnv };
             }
             catch (err) {
                 console.error(chalk.red(err.message));
@@ -639,7 +821,7 @@ export function registerRunCommand(program) {
             agent,
             version,
             prompt,
-            interactive: options.interactive,
+            interactive: options.interactive || forceInteractive,
             mode,
             effort,
             cwd: options.cwd,
@@ -647,7 +829,8 @@ export function registerRunCommand(program) {
             addDirs: options.addDir,
             json: options.json,
             headless: options.headless,
-            sessionId: options.sessionId,
+            sessionId: resumeSessionId ?? options.sessionId,
+            resume: resumeNative,
             verbose: options.verbose,
             timeout: options.timeout,
             env,

package/dist/commands/hosts.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `agents hosts` — register and inspect agent hosts (machines you offload runs to).
+ *
+ * The registry is a thin overlay: ssh-config hosts are dispatchable with zero
+ * registration (connection details stay in ~/.ssh/config); enrollment only adds
+ * capability metadata or bootstraps agents-cli, plus inline (non-ssh-config)
+ * hosts. Dispatch itself is `agents run --host <name>` (see commands/exec.ts).
+ */
+import type { Command } from 'commander';
+/** Register the `agents hosts` command tree. */
+export declare function registerHostsCommand(program: Command): void;

package/dist/commands/hosts.js

@@ -0,0 +1,229 @@
+/**
+ * `agents hosts` — register and inspect agent hosts (machines you offload runs to).
+ *
+ * The registry is a thin overlay: ssh-config hosts are dispatchable with zero
+ * registration (connection details stay in ~/.ssh/config); enrollment only adds
+ * capability metadata or bootstraps agents-cli, plus inline (non-ssh-config)
+ * hosts. Dispatch itself is `agents run --host <name>` (see commands/exec.ts).
+ */
+import chalk from 'chalk';
+import { checkbox, confirm } from '@inquirer/prompts';
+import { assertValidSshTarget } from '../lib/ssh-exec.js';
+import { getProvider, listAllHosts, resolveHost } from '../lib/hosts/registry.js';
+import { sshTargetFor } from '../lib/hosts/types.js';
+import { listSshConfigHosts, listKnownHosts, isSshConfigHost } from '../lib/hosts/ssh-config.js';
+import { probeHost, remoteAgentsVersion, bootstrapAgentsCli, localCliVersion, } from '../lib/hosts/ready.js';
+import { listTasks, loadTask, localLogPath } from '../lib/hosts/tasks.js';
+import { followHostTask } from '../lib/hosts/progress.js';
+import * as fs from 'fs';
+/** Parse `user@host` or `host` into its pieces. */
+function parseTarget(target) {
+    const at = target.indexOf('@');
+    if (at === -1)
+        return { address: target };
+    return { user: target.slice(0, at), address: target.slice(at + 1) };
+}
+/** Bootstrap/verify agents-cli on a freshly-enrolled host (best-effort, prompts). */
+async function maybeBootstrap(target, hostName) {
+    const probe = probeHost(target);
+    if (!probe.reachable) {
+        console.log(chalk.yellow(`  Not reachable over SSH yet — skipping bootstrap. Fix key auth, then: agents hosts check ${hostName}`));
+        return;
+    }
+    const remoteVer = remoteAgentsVersion(target);
+    const localVer = localCliVersion();
+    if (!remoteVer) {
+        const ok = await confirm({ message: `  agents-cli not found on ${hostName}. Install ${localVer ? `v${localVer}` : 'latest'} now?`, default: true });
+        if (ok) {
+            console.log(chalk.gray('  Installing agents-cli on the host…'));
+            const r = bootstrapAgentsCli(target, localVer);
+            console.log(r.ok ? chalk.green('  Installed.') : chalk.red(`  Install failed:\n${r.output}`));
+        }
+        return;
+    }
+    const remoteClean = remoteVer.replace(/^v/, '');
+    if (localVer && remoteClean !== localVer) {
+        const ok = await confirm({ message: `  ${hostName} has agents-cli ${remoteClean}, you have ${localVer}. Upgrade to match?`, default: false });
+        if (ok) {
+            const r = bootstrapAgentsCli(target, localVer);
+            console.log(r.ok ? chalk.green('  Upgraded.') : chalk.red(`  Upgrade failed:\n${r.output}`));
+        }
+    }
+}
+async function registerHost(spec) {
+    const provider = getProvider('local');
+    await provider.register(spec);
+}
+async function doAdd(name, target, opts) {
+    // No name + no target → interactive scan of ssh sources.
+    if (!name && !target) {
+        const existing = new Set((await listAllHosts()).filter((h) => h.enrolled).map((h) => h.name));
+        const candidates = [...new Set([...listSshConfigHosts(), ...listKnownHosts()])].filter((c) => !existing.has(c));
+        if (candidates.length === 0) {
+            console.log(chalk.yellow('No SSH hosts found in ~/.ssh/config or ~/.ssh/known_hosts. Add one explicitly: agents hosts add <name> <user@host>'));
+            return;
+        }
+        const picked = await checkbox({
+            message: 'Select hosts to enroll (connection details come from ~/.ssh/config)',
+            choices: candidates.map((c) => ({ value: c, name: c })),
+        });
+        for (const c of picked) {
+            // The ssh target is the candidate name itself either way: ssh resolves it
+            // for ssh-config hosts, and it's a reachable hostname for known_hosts ones.
+            const source = isSshConfigHost(c) ? 'ssh-config' : 'inline';
+            const probe = probeHost(c);
+            await registerHost({ name: c, provider: 'local', source, ...(source === 'inline' ? { address: c } : {}), os: probe.os, caps: opts.cap });
+            console.log(chalk.green(`Enrolled ${c}`) + chalk.gray(` (${source}${probe.os ? `, ${probe.os}` : ''})`));
+            if (opts.enroll !== false)
+                await maybeBootstrap(c, c);
+        }
+        return;
+    }
+    if (!name) {
+        console.log(chalk.red('Usage: agents hosts add <name> [user@host]'));
+        process.exitCode = 1;
+        return;
+    }
+    let spec;
+    let sshTarget;
+    if (target) {
+        assertValidSshTarget(target);
+        const { address, user } = parseTarget(target);
+        spec = { name, provider: 'local', source: 'inline', address, user, caps: opts.cap, os: opts.os };
+        sshTarget = target;
+    }
+    else if (isSshConfigHost(name)) {
+        spec = { name, provider: 'local', source: 'ssh-config', caps: opts.cap, os: opts.os };
+        sshTarget = name;
+    }
+    else {
+        console.log(chalk.red(`"${name}" is not in ~/.ssh/config. Pass a target: agents hosts add ${name} <user@host>`));
+        process.exitCode = 1;
+        return;
+    }
+    const probe = probeHost(sshTarget);
+    if (!spec.os && probe.os)
+        spec.os = probe.os;
+    await registerHost(spec);
+    console.log(chalk.green(`Enrolled ${name}`) + chalk.gray(` (${spec.source}${spec.os ? `, ${spec.os}` : ''}${spec.caps?.length ? `, caps: ${spec.caps.join(',')}` : ''})`));
+    if (opts.enroll !== false)
+        await maybeBootstrap(sshTarget, name);
+}
+async function doList(json) {
+    const hosts = await listAllHosts();
+    if (json) {
+        console.log(JSON.stringify(hosts, null, 2));
+        return;
+    }
+    if (hosts.length === 0) {
+        console.log(chalk.gray('No hosts. Enroll one: agents hosts add <name> <user@host>  (or just: agents hosts add)'));
+        return;
+    }
+    console.log(chalk.bold('NAME').padEnd(20) + chalk.bold('SOURCE').padEnd(13) + chalk.bold('TARGET').padEnd(28) + chalk.bold('CAPS'));
+    for (const h of hosts) {
+        const tgt = h.source === 'ssh-config' ? chalk.gray('(ssh-config)') : `${h.user ? h.user + '@' : ''}${h.address ?? ''}`;
+        const mark = h.enrolled ? '' : chalk.gray(' ·available');
+        console.log(h.name.padEnd(20) + h.source.padEnd(13) + tgt.padEnd(28) + (h.caps?.join(',') ?? '') + mark);
+    }
+}
+async function doCheck(name) {
+    const host = await resolveHost(name);
+    if (!host) {
+        console.log(chalk.red(`Unknown host "${name}". Known: ${(await listAllHosts()).map((h) => h.name).join(', ') || '(none)'}`));
+        process.exitCode = 1;
+        return;
+    }
+    const target = sshTargetFor(host);
+    process.stdout.write(`Probing ${chalk.cyan(name)} (${target})… `);
+    const probe = probeHost(target);
+    if (!probe.reachable) {
+        console.log(chalk.red('unreachable'));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(chalk.green('reachable') + chalk.gray(probe.os ? ` · ${probe.os}` : ''));
+    const ver = remoteAgentsVersion(target);
+    console.log(`  agents-cli: ${ver ? chalk.green(ver) : chalk.yellow('not installed')}`);
+}
+async function doRemove(name) {
+    const host = await resolveHost(name);
+    if (!host || !host.enrolled) {
+        console.log(chalk.yellow(`"${name}" is not enrolled (nothing to remove).`));
+        return;
+    }
+    await getProvider('local').remove(name);
+    console.log(chalk.green(`Removed ${name}`));
+}
+async function doPs(json) {
+    const tasks = listTasks();
+    if (json) {
+        console.log(JSON.stringify(tasks, null, 2));
+        return;
+    }
+    if (tasks.length === 0) {
+        console.log(chalk.gray('No host tasks yet. Dispatch one: agents run <agent> "<task>" --host <name>'));
+        return;
+    }
+    console.log(chalk.bold('ID').padEnd(11) + chalk.bold('HOST').padEnd(16) + chalk.bold('AGENT').padEnd(10) + chalk.bold('STATUS').padEnd(11) + chalk.bold('PROMPT'));
+    for (const t of tasks) {
+        const status = t.status === 'completed' ? chalk.green(t.status) : t.status === 'failed' ? chalk.red(t.status) : chalk.yellow(t.status);
+        console.log(t.id.padEnd(11) + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + t.prompt.slice(0, 50));
+    }
+}
+async function doLogs(id, follow) {
+    const task = loadTask(id);
+    if (!task) {
+        console.log(chalk.red(`Unknown task "${id}".`));
+        process.exitCode = 1;
+        return;
+    }
+    if (follow && task.status === 'running') {
+        const code = await followHostTask(task.target, { remoteLog: task.remoteLog, remoteExit: task.remoteExit, taskId: id, echo: true });
+        process.exitCode = code === -1 ? 1 : code;
+        return;
+    }
+    try {
+        process.stdout.write(fs.readFileSync(localLogPath(id), 'utf-8'));
+    }
+    catch {
+        console.log(chalk.gray('(no local log captured for this task)'));
+    }
+}
+/** Register the `agents hosts` command tree. */
+export function registerHostsCommand(program) {
+    const hosts = program
+        .command('hosts')
+        .description('Register and inspect agent hosts (machines you offload runs to with `agents run --host <name>`).');
+    hosts
+        .command('add [name] [target]')
+        .description('Enroll a host. With no args, pick from ~/.ssh/config + known_hosts. `target` is user@host for hosts not in ssh config.')
+        .option('--cap <cap...>', 'Capability tag(s) for routing (e.g. --cap gpu)')
+        .option('--os <os>', 'Override detected OS label')
+        .option('--no-enroll', 'Register only — skip the remote agents-cli bootstrap/version check')
+        .action((name, target, opts) => doAdd(name, target, opts));
+    hosts
+        .command('list')
+        .alias('ls')
+        .description('List enrolled + ssh-config hosts (metadata only, no probing).')
+        .option('--json', 'Output JSON')
+        .action((opts) => doList(!!opts.json));
+    hosts
+        .command('check <name>')
+        .description('Probe one host: reachable? agents-cli version?')
+        .action((name) => doCheck(name));
+    hosts
+        .command('remove <name>')
+        .alias('rm')
+        .description('Remove a host from the registry (does not touch ~/.ssh/config).')
+        .action((name) => doRemove(name));
+    hosts
+        .command('ps')
+        .description('List dispatched host tasks.')
+        .option('--json', 'Output JSON')
+        .action((opts) => doPs(!!opts.json));
+    hosts
+        .command('logs <id>')
+        .description('Show a host task log; -f to follow a running one.')
+        .option('-f, --follow', 'Follow live output')
+        .action((id, opts) => doLogs(id, !!opts.follow));
+}