@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/commands/exec.js

@@ -20,8 +20,9 @@ import { sshResolve } from '../lib/hosts/ssh-config.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { randomUUID } from 'crypto';
 import { spawnSync } from 'child_process';
+import { randomUUID } from 'crypto';
+import { isSessionTrackedAgent } from '../lib/session/types.js';
 /** Distinguish a terminal account-picker marker from an explicit @version pin. */
 export function parseRunAccountPickerRequest(agentSpec) {
     const requested = agentSpec.endsWith('@');
@@ -398,6 +399,11 @@ export function registerRunCommand(program) {
     // `--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());
+    // Internal: the `--host` dispatch forwards this so the REMOTE run prints its
+    // resolved session id as a one-line stdout sentinel (hosts/session-marker.ts),
+    // letting the launcher relate the remote-created session back to itself for
+    // every agent — not just Claude, whose id it forces up front.
+    runCmd.addOption(new Option('--emit-session-id', 'internal: print the resolved session id for a --host launcher to capture').hideHelp());
     // Required for the documented `agents run <agent> [prompt] -- <native flags>`
     // passthrough: commander >=13 rejects excess operands by default, so any
     // post-`--` token died with "too many arguments" before the action ran. The
@@ -872,7 +878,7 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             const hostName = hostGiven[0];
-            const { resolveHostRunTarget, dispatchPromptToHost, HostResolutionError } = await import('../lib/hosts/run-target.js');
+            const { resolveHostRunTarget, resolveHostSessionId, dispatchPromptToHost, HostResolutionError } = await import('../lib/hosts/run-target.js');
             const { runInteractiveOnHost } = await import('../lib/hosts/dispatch.js');
             const { registerInteractiveHostSession } = await import('../lib/hosts/session-index.js');
             const { RUN_OPTION_REJECT_MESSAGES } = await import('../lib/hosts/remote-cmd.js');
@@ -1030,10 +1036,21 @@ export function registerRunCommand(program) {
                         process.exit(1);
                     }
                     // Mirror the local path (lib/exec.ts): only Claude accepts a forced
-                    // `--session-id`. Generating it here lets us register the run in the
-                    // local index and makes it resumable by id. On resume the remote
-                    // session keeps its existing id — don't mint a new one.
-                    const hostSessionId = runAgent === 'claude' && !resumeId ? randomUUID() : undefined;
+                    // `--session-id`. Adopt the caller's id when present; otherwise mint
+                    // one here. Registering that same id keeps the local index aligned
+                    // with the remote agent. On resume, don't mint a new one.
+                    const hostSessionId = resolveHostSessionId(runAgent, resumeId, options.sessionId);
+                    // For every OTHER agent the remote coins its own id, which we can't
+                    // know up front. Forward a launch id we control as AGENT_LAUNCH_ID:
+                    // the remote `agents run` adopts it (exec.ts resolveLaunchId) and its
+                    // SessionStart hook records the real id under that exact key, so after
+                    // the stream we resolve the id by one ssh read of the remote hook
+                    // record — the same launch-id join used locally (RUSH-2034). Not
+                    // needed for Claude (id forced) or resume (id already known).
+                    const correlationLaunchId = !hostSessionId && !resumeId && isSessionTrackedAgent(runAgent) ? randomUUID() : undefined;
+                    const hostEnv = correlationLaunchId
+                        ? [...options.env, `AGENT_LAUNCH_ID=${correlationLaunchId}`]
+                        : options.env;
                     if (hostSessionId) {
                         registerInteractiveHostSession({
                             cwd: process.cwd(),
@@ -1043,6 +1060,7 @@ export function registerRunCommand(program) {
                             name: options.name,
                         });
                     }
+                    const isRaw = options.raw || options.tmux === false || options.disableTmux === true;
                     const exitCode = await runInteractiveOnHost(host, {
                         agent: runAgent,
                         version: resumeId ? undefined : runVersion,
@@ -1052,7 +1070,7 @@ export function registerRunCommand(program) {
                         mode: options.mode,
                         model: options.model,
                         effort: options.effort,
-                        env: options.env,
+                        env: hostEnv,
                         addDir: hostAddDirs,
                         json: options.json,
                         verbose: options.verbose,
@@ -1064,10 +1082,55 @@ export function registerRunCommand(program) {
                         name: options.name,
                         resume: resumeId,
                         passthroughArgs,
-                        raw: options.raw || options.tmux === false || options.disableTmux === true,
+                        raw: isRaw,
                         forceInteractive: options.interactive,
                         copyCreds: hostCopyCreds,
                     });
+                    // Resolve a non-Claude agent's REAL remote session id now the run has
+                    // booted (its hook has fired on the peer): one ssh read of the remote
+                    // hook record, keyed by the launch id we forwarded. Register it so the
+                    // run shows in `agents sessions` and can be reconnected/focused —
+                    // closing the non-Claude gap RUSH-2033 left. Best-effort: an
+                    // unreachable host or a not-yet-landed record leaves the run un-mapped
+                    // rather than mis-mapped.
+                    let resolvedRemoteId;
+                    if (correlationLaunchId) {
+                        const { resolveRemoteSessionId } = await import('../lib/hosts/remote-session-id.js');
+                        const { sshTargetFor } = await import('../lib/hosts/types.js');
+                        try {
+                            resolvedRemoteId = resolveRemoteSessionId(sshTargetFor(host), correlationLaunchId);
+                        }
+                        catch {
+                            /* ssh read is best-effort — keep the run un-mapped, never guess */
+                        }
+                        if (resolvedRemoteId) {
+                            registerInteractiveHostSession({
+                                cwd: process.cwd(),
+                                host: host.name,
+                                agent: runAgent,
+                                sessionId: resolvedRemoteId,
+                                name: options.name,
+                            });
+                        }
+                    }
+                    // A network drop kills the local ssh client (exit 255) but the remote
+                    // agent survives in its detached tmux session. With a known session id
+                    // (Claude's forced id, a resumed run, or a non-Claude id we just
+                    // resolved from the remote hook record) and a tmux-hosted run,
+                    // re-attach the live pane automatically instead of exiting — the user
+                    // never has to notice the drop and `agents sessions focus` by hand.
+                    // `raw` runs aren't tmux wrapped, so there is nothing to reconnect to.
+                    const reconnectId = hostSessionId ?? resolvedRemoteId ?? resumeId;
+                    if (reconnectId && !isRaw) {
+                        const { reconnectInteractiveSession, SSH_CONN_FAILURE } = await import('../lib/hosts/reconnect.js');
+                        if (exitCode === SSH_CONN_FAILURE) {
+                            process.exit(await reconnectInteractiveSession({
+                                host,
+                                sessionId: reconnectId,
+                                initialExit: exitCode,
+                            }));
+                        }
+                    }
                     process.exit(exitCode);
                 }
                 // Headless host run: launch detached, tail the remote log, and follow
@@ -1103,6 +1166,7 @@ export function registerRunCommand(program) {
                     remoteCwd: hostCwd,
                     name: options.name,
                     resume: resumeId,
+                    sessionId: options.sessionId,
                     follow: options.follow !== false,
                     passthroughArgs,
                     copyCreds: hostCopyCreds,
@@ -1221,7 +1285,7 @@ export function registerRunCommand(program) {
                 await warnUnpushedWork(resumeExec.cwd ?? process.cwd());
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports }, { shareRuntimeEnv },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveHostSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports }, { shareRuntimeEnv },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -1851,7 +1915,7 @@ export function registerRunCommand(program) {
                     assertRemoteBundleFlagsUnsupported(bundleName, host, { keys: secretsKeysSubset, allowExpired: options.allowExpired }, { keysFlag: '--secrets-keys', allowExpiredFlag: '--allow-expired' });
                     // 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 target = await resolveHostSshTarget(host);
                     const bundleEnv = await remoteResolveEnv(target, bundleName, { osLookupName: host });
                     console.log(chalk.gray(`[secrets] Resolved ${bundleName}@${host}: ${Object.keys(bundleEnv).length} keys (remote, ephemeral)`));
                     secretsEnv = { ...secretsEnv, ...bundleEnv };
@@ -1859,11 +1923,13 @@ export function registerRunCommand(program) {
                 else {
                     const { bundle, env: bundleEnv } = readAndResolveBundleEnv(bundleName, {
                         caller: `agent ${agent}`,
+                        agent,
                         keys: secretsKeysSubset,
                         allowExpired: options.allowExpired,
-                        // A headless/background run (routine, teammate, detached) must not
-                        // pop a Touch ID sheet nobody can answer — resolve broker-only and
-                        // fail fast with an actionable error. Interactive runs still prompt.
+                        // The harness identity scopes any cached grant. It no longer lets the
+                        // requesting agent wait for interactive approval — an agent launch
+                        // resolves broker-only and fails fast naming
+                        // `agents secrets unlock <bundle>` (bundles.ts:interactiveUnlock).
                         agentOnly: isHeadlessSecretsContext(),
                     });
                     const entries = describeBundle(bundle);
@@ -1923,6 +1989,10 @@ export function registerRunCommand(program) {
             toolsRestrict: workflowToolsRestrict,
             mcpConfigPath: workflowMcpConfigPath,
             passthroughArgs,
+            // Set only on the REMOTE side of a `--host` dispatch (the launcher
+            // forwards `--emit-session-id`): print the resolved session id as a
+            // stdout sentinel so the launcher captures the id this run coined.
+            emitSessionId: options.emitSessionId === true,
         };
         if (options.interactive && options.headless) {
             console.error(chalk.red('--interactive and --headless are mutually exclusive. Pass one, or neither (mode is inferred from prompt presence).'));

package/dist/commands/feed.d.ts

@@ -1,6 +1,7 @@
 /**
- * `agents feed` -- list open blocks (decisions agents are waiting on).
+ * `agents feed` -- operator inbox + agent status posts.
  *
+ * Default (`agents feed`): list open blocks (decisions agents are waiting on).
  * Aggregates block records from the local feed store and, with --host, from
  * reachable remote hosts via SSH passthrough. Each block carries enough
  * identity for `agents message` to route a reply back to the right agent.
@@ -8,6 +9,11 @@
  * Default view groups by **outcome** (ticket / PR / worktree / Unassigned) so
  * an operator sees dozens of deliverables, not ~1,100 agents. Pass `--flat`
  * for the legacy per-agent list.
+ *
+ * `agents feed post`: agent-callable free-text progress into the activity
+ * stream (milestone `status.posted`). Session/agent/host/runtime/pid identity
+ * is auto-stamped from env + the pid registry — no domain-specific flags.
+ * Humans watch via the feed activity lane / `agents activity`.
  */
 import type { Command } from 'commander';
 import { type OpenBlock } from '../lib/feed.js';

package/dist/commands/feed.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified } from '../lib/feed.js';
 import { ensureActivityLogHook, readRecentActivity, formatActivityLine } from '../lib/activity.js';
+import { postFeedStatus } from '../lib/feed-post.js';
 import { enrichBlocksFromSessions, groupBlocksByOutcome, isUnambiguousOutcomeAnswer, openBlocksForOutcome, stampBlockOutcomes, } from '../lib/feed-outcome.js';
 import { classifyBlock, filterBlocksForFeed, suppressionDigest, } from '../lib/ask-classifier.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
@@ -214,9 +215,9 @@ export function sessionHintsFromActive(sessions) {
     }));
 }
 export function registerFeedCommand(program) {
-    program
+    const feed = program
         .command('feed')
-        .description('List open blocks -- decisions agents are waiting on (grouped by outcome)')
+        .description('Open blocks (needs you) + agent status posts (feed post)')
         .option('--json', 'Output as JSON (each block stamped with its outcome + ask class)')
         .option('--flat', 'List one block per agent instead of grouping by outcome')
         .option('--all', 'Include stalls/FYIs that policy would suppress (default: hide them)')
@@ -225,8 +226,50 @@ export function registerFeedCommand(program) {
         .option('--device <target...>', 'Alias for --host; repeatable')
         .option('--dispatch', 'Run stall suppression + default-on-no-answer policy and urgent notifications')
         .option('--pause <id>', 'Pause a runaway/needy local process (SIGSTOP) or cancel a cloud task')
-        .option('--kill <id>', 'Kill a runaway/needy local process (SIGTERM) or cancel a cloud task')
-        .action(async (opts) => {
+        .option('--kill <id>', 'Kill a runaway/needy local process (SIGTERM) or cancel a cloud task');
+    feed
+        .command('post')
+        .description('Post a status update to the fleet activity stream (for agents)')
+        .argument('<text...>', 'What just happened — one short human line')
+        .option('--session <id>', 'Session id escape hatch (default: auto from env / pid registry)')
+        .option('--json', 'Emit the written event as JSON')
+        .addHelpText('after', `
+Examples:
+  # Inside an agents-cli run (session identity is already in the env):
+  agents feed post "CHANGELOG pushed; watching CI and mac-mini E2E"
+  agents feed post "ready for review" --json
+
+  # Outside a run, pass the session explicitly:
+  agents feed post "manual note" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47
+
+Identity (session, agent, host, runtime, pid, launchId) is stamped automatically.
+Domain facts (tickets, PRs) are not CLI flags — join them on the session at read time.
+`)
+        .action((textParts, opts, cmd) => {
+        // Parent `feed` also declares `--json` (for the list view). Commander
+        // binds the flag on the parent, so a `feed post … --json` lands on
+        // parent.opts().json — not the child. Read both.
+        const flags = {
+            session: opts?.session ?? cmd?.opts?.()?.session,
+            json: Boolean(opts?.json ?? cmd?.opts?.()?.json ?? cmd?.parent?.opts?.()?.json),
+        };
+        try {
+            const { event } = postFeedStatus({
+                text: Array.isArray(textParts) ? textParts.join(' ') : String(textParts ?? ''),
+                sessionId: flags.session,
+            });
+            if (flags.json) {
+                console.log(JSON.stringify(event, null, 2));
+                return;
+            }
+            console.log(formatActivityLine(event, { showHost: true }).trimStart());
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    feed.action(async (opts) => {
         if (opts.device?.length)
             opts.host = [...(opts.host ?? []), ...opts.device];
         const self = machineId();

package/dist/commands/go.d.ts

@@ -17,8 +17,15 @@ import type { Command } from 'commander';
 import { type ActiveSession } from '../lib/session/active.js';
 import type { SessionMeta } from '../lib/session/types.js';
 export declare function registerGoCommand(program: Command): void;
-/** Live jump targets (local + remote), keyed by session id. Cloud excluded (no pid). */
-export declare function gatherLiveTargets(local: boolean): Promise<{
+/**
+ * Live jump targets (local + remote), keyed by session id. Cloud is excluded by
+ * default (it has no local pid to attach), but `detach` opts in with
+ * `includeCloud` so it can resolve a cloud id and refuse it with a clear message
+ * instead of a bare "no live session".
+ */
+export declare function gatherLiveTargets(local: boolean, opts?: {
+    includeCloud?: boolean;
+}): Promise<{
     self: string;
     activeById: Map<string, ActiveSession>;
 }>;

package/dist/commands/go.js

@@ -20,6 +20,7 @@ import { promisify } from 'util';
 import { getActiveSessions, findSessionFileForKind } from '../lib/session/active.js';
 import { gatherRemoteActive } from '../lib/session/remote-active.js';
 import { discoverSessions } from '../lib/session/discover.js';
+import { deriveShortId } from '../lib/session/short-id.js';
 import { dedupeByMachineSession, mergeLocalFirst, pickSessionInteractive } from './sessions.js';
 import { focusAction } from './focus.js';
 import { machineId } from '../lib/session/sync/config.js';
@@ -39,8 +40,13 @@ export function registerGoCommand(program) {
         await focusAction(id, { local: opts.local, attachOnly: true });
     });
 }
-/** Live jump targets (local + remote), keyed by session id. Cloud excluded (no pid). */
-export async function gatherLiveTargets(local) {
+/**
+ * Live jump targets (local + remote), keyed by session id. Cloud is excluded by
+ * default (it has no local pid to attach), but `detach` opts in with
+ * `includeCloud` so it can resolve a cloud id and refuse it with a clear message
+ * instead of a bare "no live session".
+ */
+export async function gatherLiveTargets(local, opts = {}) {
     const self = machineId();
     const localActive = await getActiveSessions();
     for (const s of localActive)
@@ -55,9 +61,13 @@ export async function gatherLiveTargets(local) {
         catch { /* remote sweep is best-effort */ }
     }
     const activeById = new Map();
-    for (const s of active)
-        if (s.context !== 'cloud' && s.sessionId)
-            activeById.set(s.sessionId, s);
+    for (const s of active) {
+        if (!s.sessionId)
+            continue;
+        if (s.context === 'cloud' && !opts.includeCloud)
+            continue;
+        activeById.set(s.sessionId, s);
+    }
     return { self, activeById };
 }
 /** Interactive pick over the live sessions' rich SessionMeta; returns the chosen live session. */
@@ -99,7 +109,7 @@ function synthMeta(s, self) {
     const filePath = remote ? '' : (findSessionFileForKind(s.kind, s.cwd, s.sessionId) ?? '');
     return {
         id: s.sessionId,
-        shortId: s.sessionId.slice(0, 8),
+        shortId: deriveShortId(s.sessionId),
         agent: s.kind,
         timestamp: new Date(s.startedAtMs ?? Date.now()).toISOString(),
         filePath,

package/dist/commands/harness.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Custom harness commands (`agents harness`).
+ *
+ * A "custom harness" is a named (host CLI + model) combo — e.g. OpenCode pinned
+ * to meta/muse-spark-1.1, called `spark`. It runs like a native agent type
+ * (`agents run spark`) and syncs across devices via `agents repo push user`.
+ *
+ * Mechanism: harnesses ARE profiles (same ~/.agents/profiles/*.yml, same run
+ * resolution). This command group is the harness-flavored surface over that
+ * layer + a discovery `list` spanning custom harnesses, addable presets, and the
+ * native harness registry. The `agents profiles` tree stays unchanged.
+ */
+import type { Command } from 'commander';
+export declare function registerHarnessCommands(program: Command): void;

package/dist/commands/harness.js

@@ -0,0 +1,145 @@
+/**
+ * Custom harness commands (`agents harness`).
+ *
+ * A "custom harness" is a named (host CLI + model) combo — e.g. OpenCode pinned
+ * to meta/muse-spark-1.1, called `spark`. It runs like a native agent type
+ * (`agents run spark`) and syncs across devices via `agents repo push user`.
+ *
+ * Mechanism: harnesses ARE profiles (same ~/.agents/profiles/*.yml, same run
+ * resolution). This command group is the harness-flavored surface over that
+ * layer + a discovery `list` spanning custom harnesses, addable presets, and the
+ * native harness registry. The `agents profiles` tree stays unchanged.
+ */
+import chalk from 'chalk';
+import { addProfile } from './profiles.js';
+import { listProfiles, readProfile, deleteProfile, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, getProfilePath, } from '../lib/profiles.js';
+import { listPresets } from '../lib/profiles-presets.js';
+import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
+/** Short capability summary for a native harness — its supported run modes. */
+function nativeModes(id) {
+    const modes = AGENTS[id]?.capabilities?.modes ?? [];
+    return modes.length ? modes.join('/') : '-';
+}
+export function registerHarnessCommands(program) {
+    const cmd = program
+        .command('harness')
+        .alias('harnesses')
+        .description('Custom harnesses — name a (host CLI + model) combo and run it like a native agent type.')
+        .addHelpText('after', `
+A custom harness pins a host CLI (opencode, claude, codex, grok, gemini, ...) to a
+model and gives it a name. 'agents run <name>' then behaves like a native agent
+type, and 'agents repo push user' syncs it to every device.
+
+Examples:
+  # Meta Muse Spark 1.1 through OpenCode, called 'spark'
+  agents harness add spark --host opencode --model meta/muse-spark-1.1
+  agents run spark "refactor api/handlers/checkout.py"
+
+  # Per-run model override still wins
+  agents run spark --model opencode/big-pickle "quick pass"
+
+  # See custom harnesses, addable presets, and native harnesses
+  agents harness list
+
+  # Private OpenAI/Anthropic-compatible endpoint (stores a keychain key)
+  agents harness add corp --host claude --model gpt-x --base-url https://gw.corp/v1 --auth-provider corp
+
+  # Custom harnesses are just profiles — this also works via 'agents profiles'
+`);
+    cmd
+        .command('add <name>')
+        .description('Create a custom harness from a host + model (or apply a built-in preset).')
+        .option('--host <agent>', 'Host CLI to run under (opencode, claude, codex, grok, gemini, ...) — pair with --model')
+        .option('--model <id>', 'Model id to pin on the host (e.g., meta/muse-spark-1.1) — pair with --host')
+        .option('--base-url <url>', 'Custom endpoint base URL (claude/codex hosts)')
+        .option('--auth-provider <provider>', 'Attach a keychain-backed API key under this provider (for private endpoints)')
+        .option('--preset <preset>', 'Apply a built-in preset instead of --host/--model')
+        .option('--version <version>', 'Pin the host CLI version (e.g., 1.16.0)')
+        .option('--key-stdin', 'Read API key from stdin instead of prompting (for scripts/CI)')
+        .option('--force', 'Overwrite an existing harness with the same name')
+        .action(async (name, opts) => {
+        try {
+            await addProfile(name, opts, 'Harness');
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('List custom harnesses, addable presets, and native harnesses.')
+        .option('--json', 'Emit JSON instead of a table')
+        .action((opts) => {
+        const custom = listProfiles();
+        const presets = listPresets();
+        const native = ALL_AGENT_IDS.map((id) => ({ id, name: AGENTS[id].name, modes: nativeModes(id) }));
+        if (opts.json) {
+            console.log(JSON.stringify({
+                custom: custom.map((p) => ({
+                    name: p.name,
+                    host: p.host.agent,
+                    model: profileModelLabel(p),
+                    provider: profileProviderLabel(p),
+                })),
+                presets: presets.map((p) => ({ name: p.name, provider: p.provider, description: p.description })),
+                native,
+            }, null, 2));
+            return;
+        }
+        console.log(chalk.bold('Custom harnesses') + chalk.gray('  (yours — agents run <name>)'));
+        if (custom.length === 0) {
+            console.log(chalk.gray('  none yet — try: agents harness add spark --host opencode --model meta/muse-spark-1.1'));
+        }
+        else {
+            for (const p of custom) {
+                console.log(`  ${chalk.cyan(p.name.padEnd(16))} ${profileHostLabel(p).padEnd(14)} ${chalk.gray(profileModelLabel(p))}`);
+            }
+        }
+        console.log('');
+        console.log(chalk.bold('Presets') + chalk.gray('  (addable — agents harness add <name>)'));
+        for (const p of presets) {
+            console.log(`  ${chalk.cyan(p.name.padEnd(16))} ${p.provider.padEnd(12)} ${chalk.gray(p.description.slice(0, 70))}`);
+        }
+        console.log('');
+        console.log(chalk.bold('Native harnesses') + chalk.gray('  (built-in — agents run <id>)'));
+        for (const n of native) {
+            console.log(`  ${chalk.cyan(n.id.padEnd(16))} ${n.name.padEnd(14)} ${chalk.gray('modes: ' + n.modes)}`);
+        }
+    });
+    cmd
+        .command('view <name>')
+        .alias('show')
+        .description('Show one custom harness (host, model, provider, auth, path).')
+        .action((name) => {
+        try {
+            const p = readProfile(name);
+            console.log(chalk.bold(p.name));
+            if (p.description)
+                console.log(chalk.gray(p.description));
+            console.log('');
+            console.log(`Host:     ${profileHostLabel(p)}`);
+            console.log(`Model:    ${profileModelLabel(p)}`);
+            console.log(`Provider: ${profileProviderLabel(p)}`);
+            console.log(`Auth:     ${profileAuthLabel(p)}`);
+            console.log(chalk.gray(getProfilePath(p.name)));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('remove <name>')
+        .alias('rm')
+        .description('Delete a custom harness (keychain token is kept).')
+        .action((name) => {
+        const existed = deleteProfile(name);
+        if (!existed) {
+            console.error(chalk.red(`Harness '${name}' not found.`));
+            process.exit(1);
+        }
+        console.log(chalk.green(`Harness '${name}' removed.`));
+    });
+}

package/dist/commands/import.js

@@ -134,7 +134,7 @@ async function runImport(agentArg, opts) {
             }
         }
     }
-    let version = opts.version;
+    let version = opts.as;
     if (!version) {
         if (!useDirectBinaryImport && globalPath) {
             try {
@@ -157,7 +157,7 @@ async function runImport(agentArg, opts) {
     }
     if (!version) {
         console.error(chalk.red(`Could not determine version for ${agentLabel(agentId)}.`));
-        console.error(chalk.gray('Pass --version <version> explicitly.'));
+        console.error(chalk.gray('Pass --as <version> explicitly.'));
         process.exit(1);
     }
     if (!isValidImportVersion(version)) {
@@ -167,7 +167,7 @@ async function runImport(agentArg, opts) {
     }
     const versionDir = getVersionDir(agentId, version);
     const fromLabel = useDirectBinaryImport ? installScriptBinary : globalPath;
-    console.log(chalk.bold(`\nImport ${agentLabel(agentId)} v${version}`));
+    console.log(chalk.bold(`\nImport ${agentLabel(agentId)} v${version}${opts.isolated ? ' (isolated copy)' : ''}`));
     console.log(`  from: ${chalk.gray(fromLabel)}`);
     console.log(`  into: ${chalk.gray(versionDir)}`);
     const configDirExists = fs.existsSync(agent.configDir);
@@ -178,6 +178,16 @@ async function runImport(agentArg, opts) {
             configAlreadyManaged = true;
             console.log(`  config: ${chalk.gray(`${agent.configDir} (already managed — will skip)`)}`);
         }
+        else if (opts.isolated) {
+            // This summary is printed BEFORE the branch that does the work, so it has to
+            // describe the mode it is actually about to run. Saying "will be moved" under
+            // --isolated announced the exact adoption the flag exists to prevent — a
+            // confirmation prompt that misdescribes the operation is worse than none.
+            console.log(`  config: ${chalk.gray(`${agent.configDir} (will be COPIED — your original stays put)`)}`);
+            if (!opts.withAuth) {
+                console.log(`          ${chalk.gray('credentials are skipped; pass --with-auth to include them')}`);
+            }
+        }
         else {
             console.log(`  config: ${chalk.gray(`${agent.configDir} (will be moved into version home)`)}`);
         }
@@ -188,7 +198,9 @@ async function runImport(agentArg, opts) {
     if (!opts.yes && isInteractiveTerminal()) {
         console.log();
         const proceed = await confirm({
-            message: `Import ${agentLabel(agentId)} v${version} into agents-cli?`,
+            message: opts.isolated
+                ? `Import ${agentLabel(agentId)} v${version} as an isolated copy?`
+                : `Import ${agentLabel(agentId)} v${version} into agents-cli?`,
             default: true,
         }).catch((err) => {
             if (isPromptCancelled(err))
@@ -205,17 +217,23 @@ async function runImport(agentArg, opts) {
     // want a stranded symlink farm. Binary registration is cheap and reversible
     // — if it fails after config, the next `agents import` call retries cleanly.
     const willImportConfig = configDirExists && !configAlreadyManaged && !opts.isolated;
-    if (opts.isolated && configDirExists) {
+    if (opts.isolated && configDirExists && configAlreadyManaged) {
+        console.log(chalk.gray(`  Skipping config copy: ${agent.configDir} is a managed symlink, not your real settings.`));
+    }
+    else if (opts.isolated && configDirExists) {
         // COPY the user's settings in; never move, never symlink. The original stays
         // exactly where it is — that is what separates this from adoption.
         const seedSpinner = ora(`Copying ${agent.configDir} into the isolated copy...`).start();
-        const seed = seedIsolatedConfigFromLocal(agentId, version, { withAuth: opts.withAuth });
+        const seed = seedIsolatedConfigFromLocal(agentId, version, { withAuth: opts.withAuth, all: opts.all });
         if (seed.error) {
             seedSpinner.fail(`Config: ${seed.error}`);
             process.exit(1);
         }
         else if (seed.seeded) {
             seedSpinner.succeed(`Settings copied (${seed.from} -> ${seed.to}); your original is untouched`);
+            if (seed.skippedRuntime.length > 0) {
+                console.log(chalk.gray(`  Runtime state NOT copied: ${seed.skippedRuntime.join(', ')} (regenerated as you use it; --all to include)`));
+            }
             if (seed.skippedAuth.length > 0) {
                 console.log(chalk.gray(`  Credentials NOT copied: ${seed.skippedAuth.join(', ')}`));
                 console.log(chalk.gray('  The copy signs in separately. Use --with-auth to copy them too.'));
@@ -288,15 +306,22 @@ export function registerImportCommand(program) {
         .command('import')
         .argument('<agent>', 'Agent id (e.g. openclaw, claude, codex)')
         .description('Import an existing unmanaged agent install into agents-cli')
-        .option('--version <version>', 'Pin a version label (otherwise read from package.json)')
+        // NOT `--version`. The program declares `.version(VERSION)` (src/index.ts), which
+        // claims `-V, --version` globally and wins over a subcommand option of the same
+        // name — so `agents import codex --version 1.2.3` printed the CLI's own version
+        // and exited without importing anything. The flag had been unreachable since it
+        // was introduced, and the "could not determine version" error even advised using
+        // it. Renamed so it actually reaches the command.
+        .option('--as <version>', 'Version label to import as (otherwise read from package.json)')
         .option('--from-path <path>', 'Path to the npm package dir (otherwise auto-detected from PATH)')
         .option('--isolated', 'Copy the install into a self-contained isolated version instead of adopting it')
         .option('--with-auth', 'With --isolated, also copy credentials into the sandbox (skipped by default)')
+        .option('--all', 'With --isolated, also copy session history, logs and caches (skipped by default)')
         .option('-y, --yes', 'Skip the confirmation prompt')
         .addHelpText('after', `
 Examples:
   $ agents import openclaw                          Auto-detect via PATH
-  $ agents import openclaw --version 2026.3.8       Pin a version label
+  $ agents import openclaw --as 2026.3.8            Pin a version label
   $ agents import openclaw --from-path /opt/homebrew/lib/node_modules/openclaw
 
   # installScript-based agents (curl/brew installers, no npm package):
@@ -305,6 +330,11 @@ Examples:
   $ agents import cursor                            Adopt ~/.local/bin/cursor-agent
   $ agents import antigravity --from-path ~/.local/bin/agy
 
+  # Copy your setup into a sandbox instead of adopting it:
+  $ agents import codex --isolated                  New isolated copy at the local version
+  $ agents import codex --isolated --as 0.146.0     Re-seed an EXISTING isolated copy
+  $ agents import codex --isolated --with-auth      ...and share credentials with it
+
 When to use:
   When an agent CLI is already installed globally and you want to bring it
   under agents-cli management without reinstalling. Creates a symlink farm