@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/commands/exec.js

@@ -398,6 +398,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
@@ -1043,6 +1048,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,
@@ -1064,10 +1070,28 @@ 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,
                     });
+                    // 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, or a resumed run) 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. Non-Claude id capture is
+                    // tracked in RUSH-2007.
+                    const reconnectId = hostSessionId ?? 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
@@ -1221,7 +1245,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 +1875,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 };
@@ -1923,6 +1947,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/export.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `agents export <agent>[@<version>]` — copy an isolated install's config out to the
+ * user's real `~/.<agent>`.
+ *
+ * The exit door for `--isolated`. Default is additive: your files are never modified,
+ * and anything that collides is written beside yours so you can diff and take what you
+ * want. A receipt records what came from the export, so "which of these are mine?" has
+ * an answer and the whole thing can be undone.
+ */
+import type { Command } from 'commander';
+export declare function registerExportCommand(program: Command): void;

package/dist/commands/export.js

@@ -0,0 +1,215 @@
+import chalk from 'chalk';
+import { execFileSync } from 'child_process';
+import { confirm, select } from '@inquirer/prompts';
+import { AGENTS, agentLabel, formatAgentError, resolveAgentName } from '../lib/agents.js';
+import { listInstalledVersions, isVersionIsolated } from '../lib/versions.js';
+import { planExport, executeExport, CONFLICT_SUFFIX } from '../lib/export.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+function isolatedVersions(agent) {
+    return listInstalledVersions(agent).filter((v) => isVersionIsolated(agent, v));
+}
+/** Explain a blocker in terms of what the user should do instead. */
+function reportBlocker(plan) {
+    const label = agentLabel(plan.agent);
+    const b = plan.blocker;
+    switch (b.kind) {
+        case 'not-installed':
+            console.log(chalk.red(`${label}@${plan.version} is not installed.`));
+            console.log(chalk.gray(`  Installed: ${listInstalledVersions(plan.agent).join(', ') || 'none'}`));
+            break;
+        case 'not-isolated':
+            console.log(chalk.yellow(`${label}@${plan.version} is not an isolated install.`));
+            console.log(chalk.gray(`  A normal install's config already IS ${plan.dest} (adoption symlinks it),`));
+            console.log(chalk.gray('  so there is nothing to export. To un-adopt it, use: agents uninstall'));
+            break;
+        case 'no-config':
+            console.log(chalk.yellow(`${label}@${plan.version} has no config to export yet (${b.source} is empty).`));
+            console.log(chalk.gray(`  Run it once first: agents run ${plan.agent}@${plan.version}`));
+            break;
+        case 'dest-adopted':
+            console.log(chalk.red(`${b.realPath} is managed by agents-cli (adopted by ${label}@${b.adoptedVersion}).`));
+            console.log(chalk.gray('  Exporting would write into that version\'s home, not your real config.'));
+            console.log(chalk.gray(`  Release it first: agents uninstall  (or agents remove ${plan.agent}@${b.adoptedVersion})`));
+            break;
+    }
+}
+/** Unified diff between the user's file and the incoming one, via git. */
+function printDiff(existing, incoming) {
+    try {
+        execFileSync('git', ['diff', '--no-index', '--color', '--', existing, incoming], {
+            stdio: ['ignore', 'inherit', 'ignore'],
+        });
+    }
+    catch {
+        // git diff --no-index exits 1 when files differ; output already streamed.
+    }
+}
+function printPlan(plan, opts) {
+    const label = agentLabel(plan.agent);
+    console.log(chalk.bold(`Export ${label}@${plan.version} -> ${plan.dest}  ${chalk.gray(`[${plan.mode}]`)}\n`));
+    console.log(`  ${chalk.gray('from')}  ${plan.source}`);
+    console.log(`  ${chalk.gray('to')}    ${plan.stagedPath ?? plan.dest}`);
+    console.log();
+    if (plan.mode === 'replace') {
+        console.log(chalk.yellow(`  Replacing ${plan.dest} wholesale — ${plan.writes.length} file(s).`));
+        if (plan.backupPath)
+            console.log(chalk.gray(`  Your current config moves to: ${plan.backupPath}`));
+        else if (plan.destKind === 'foreign-symlink') {
+            console.log(chalk.yellow(`  ${plan.dest} is a symlink agents-cli does not own; it will be removed.`));
+            console.log(chalk.gray('  Its target is left untouched.'));
+        }
+    }
+    else if (plan.mode === 'staged') {
+        console.log(chalk.gray(`  Writing ${plan.writes.length} file(s) into ${plan.stagedPath}.`));
+        console.log(chalk.gray('  Nothing is activated — your config is untouched.'));
+    }
+    else {
+        if (plan.writes.length > 0) {
+            console.log(chalk.green(`  ${plan.writes.length} new file(s) will be added:`));
+            for (const w of plan.writes.slice(0, 15))
+                console.log(chalk.gray(`      + ${w.rel}`));
+            if (plan.writes.length > 15)
+                console.log(chalk.gray(`      + ${plan.writes.length - 15} more`));
+        }
+        else {
+            console.log(chalk.gray('  No new files to add.'));
+        }
+        if (plan.conflicts.length > 0) {
+            console.log();
+            console.log(chalk.yellow(`  ${plan.conflicts.length} file(s) you already have — YOURS ARE NOT MODIFIED.`));
+            console.log(chalk.gray(`  The incoming version is written beside each as *${CONFLICT_SUFFIX}:`));
+            for (const c of plan.conflicts.slice(0, 15))
+                console.log(chalk.gray(`      ~ ${c.rel}`));
+            if (plan.conflicts.length > 15)
+                console.log(chalk.gray(`      ~ ${plan.conflicts.length - 15} more`));
+        }
+    }
+    if (opts.diff && plan.conflicts.length > 0) {
+        for (const c of plan.conflicts) {
+            console.log(chalk.bold(`\n─── ${c.rel} ───`));
+            printDiff(c.existing, c.source);
+        }
+    }
+    console.log(chalk.gray(`\n  Receipt: ${plan.receiptPath}`));
+}
+export function registerExportCommand(program) {
+    program
+        .command('export <spec>')
+        .description('Copy an isolated install\'s config out to your real ~/.<agent>')
+        .option('--replace', 'Replace your config wholesale (yours is backed up) instead of merging')
+        .option('--staged', 'Write into ~/.<agent>/.agents-export-<ts>/ and activate nothing')
+        .option('--diff', 'Show a unified diff for each file you already have')
+        .option('--dry-run', 'Show what would change without writing anything')
+        .option('-y, --yes', 'Skip the confirmation prompt')
+        .addHelpText('after', `
+Modes:
+  (default)   merge   — additive. Your files are NEVER modified. Anything that
+                        collides is written beside yours as <name>${CONFLICT_SUFFIX}
+                        so you can diff and take the parts you want.
+  --replace           — the isolated config becomes ~/.<agent>; yours is moved to
+                        backups/<agent>/<ts>. For promoting a sandbox wholesale.
+  --staged            — dump the tree into ~/.<agent>/.agents-export-<ts>/ and
+                        activate nothing. For inspecting first.
+
+Every mode writes a receipt to ~/.<agent>/.agents-cli-export.json listing exactly
+what came from the export — so you can tell your settings from the CLI's, and undo it.
+
+Examples:
+  agents export codex --dry-run          # see the plan
+  agents export codex --diff             # ...and the deltas on colliding files
+  agents export codex                    # additive; nothing of yours changes
+  agents export codex@0.144.6 --replace  # promote the sandbox wholesale
+
+Note: file CONTENTS are never auto-merged. The TOML parser here does not preserve
+comments, so merging keys would silently delete them. You get both files and a diff.
+`)
+        .action(async (spec, options) => {
+        if (options.replace && options.staged) {
+            console.error(chalk.red('--replace and --staged are mutually exclusive; pass only one.'));
+            process.exit(1);
+        }
+        const mode = options.replace ? 'replace' : options.staged ? 'staged' : 'merge';
+        const [rawAgent, rawVersion] = spec.split('@');
+        const agent = resolveAgentName(rawAgent);
+        if (!agent) {
+            console.error(chalk.red(formatAgentError(rawAgent)));
+            process.exit(1);
+        }
+        let version = rawVersion;
+        if (!version) {
+            const candidates = isolatedVersions(agent);
+            if (candidates.length === 0) {
+                console.log(chalk.yellow(`No isolated ${agentLabel(agent)} installs to export.`));
+                console.log(chalk.gray(`  Create one with: agents add ${agent}@<version> --isolated`));
+                return;
+            }
+            if (candidates.length === 1) {
+                version = candidates[0];
+            }
+            else if (isInteractiveTerminal()) {
+                version = await select({
+                    message: `Which isolated ${agentLabel(agent)} version?`,
+                    choices: candidates.map((v) => ({ name: v, value: v })),
+                }).catch((err) => {
+                    if (isPromptCancelled(err))
+                        process.exit(130);
+                    throw err;
+                });
+            }
+            else {
+                console.error(chalk.red(`${agentLabel(agent)} has several isolated installs; name one.`));
+                console.error(chalk.gray(`  ${candidates.map((v) => `agents export ${agent}@${v}`).join('\n  ')}`));
+                process.exit(1);
+            }
+        }
+        const timestamp = Date.now();
+        const plan = planExport(agent, version, timestamp, mode);
+        if (plan.blocker) {
+            reportBlocker(plan);
+            process.exit(1);
+        }
+        printPlan(plan, { diff: options.diff });
+        if (options.dryRun) {
+            console.log(chalk.gray('\nDry run — nothing was written.'));
+            return;
+        }
+        // Only `--replace` can destroy anything, so it is the only mode that demands
+        // confirmation. merge and staged are additive by construction.
+        if (mode === 'replace' && !options.yes) {
+            if (!isInteractiveTerminal()) {
+                console.error(chalk.red('\nRefusing to replace your config without confirmation in a non-interactive shell.'));
+                console.error(chalk.gray('  Re-run with --yes once you have checked --dry-run.'));
+                process.exit(1);
+            }
+            const ok = await confirm({ message: `Replace ${plan.dest}?`, default: false }).catch((err) => {
+                if (isPromptCancelled(err))
+                    process.exit(130);
+                throw err;
+            });
+            if (!ok) {
+                console.log(chalk.gray('Aborted.'));
+                return;
+            }
+        }
+        const result = executeExport(plan, timestamp);
+        if (!result.exported) {
+            console.error(chalk.red(`Export failed: ${result.errors.join('; ')}`));
+            process.exit(1);
+        }
+        console.log();
+        if (result.written.length > 0)
+            console.log(chalk.green(`Added ${result.written.length} file(s) to ${result.dest}`));
+        if (result.conflicts.length > 0) {
+            console.log(chalk.yellow(`${result.conflicts.length} of your file(s) were left untouched; incoming copies written as *${CONFLICT_SUFFIX}`));
+            console.log(chalk.gray(`  Compare them with: agents export ${agent}@${version} --diff --dry-run`));
+        }
+        if (result.backupPath)
+            console.log(chalk.gray(`Previous config kept at: ${result.backupPath}`));
+        if (result.stagedPath)
+            console.log(chalk.gray(`Staged (nothing activated): ${result.stagedPath}`));
+        console.log(chalk.gray(`Receipt: ${result.receiptPath}`));
+        if (mode !== 'staged') {
+            console.log(chalk.gray(`  ${AGENTS[plan.agent].cliCommand} reads this config directly.`));
+        }
+    });
+}

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.`));
+    });
+}