@phnx-labs/agents-cli 1.22.46 → 1.22.47

package/dist/commands/exec.js

@@ -14,6 +14,7 @@ import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection }
 import { getUserAgentsDir, readMeta } from '../lib/state.js';
 import { parseLoopInterval } from '../lib/loop.js';
 import { AGENTS, resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
+import { parseAgentVersionSpec } from '../lib/agent-spec/agents.js';
 import { recordDispatchedRun } from '../lib/audit/log.js';
 import { maybeShowStarNudge } from '../lib/star-nudge.js';
 import { warnUnpushedWork, shouldWarnUnpushed } from '../lib/warn-unpushed.js';
@@ -416,7 +417,7 @@ async function handleTerminalHandoff(agentSpec, options, prompt) {
     // isValidAgent / profileExists / resolveWorkflowRef chain below), so this must
     // accept all three. Gating on the agent table alone rejected every profile —
     // the whole Kimi/DeepSeek/Qwen/GLM path — for `--terminal` runs only.
-    const rawTarget = parseRunAccountPickerRequest(agentSpec).normalizedAgentSpec.split('@')[0];
+    const rawTarget = parseRunAccountPickerRequest(agentSpec).normalizedAgentSpec.split('#')[0].split('@')[0];
     const knownAgent = resolveAgentName(rawTarget);
     const [{ profileExists }, { resolveWorkflowRef }] = await Promise.all([
         import('../lib/profiles.js'),
@@ -490,7 +491,7 @@ export function registerRunCommand(program) {
     const runCmd = program
         .command('run [agent] [prompt]')
         .description('Execute an agent. Pass a prompt for headless runs; omit it to launch the agent interactively. With --broadcast, run the same prompt/task across an agent × model matrix.')
-        .option('-m, --mode <mode>', 'How much the agent can do: plan (read-only), edit (can write files), auto (smart classifier auto-approves safe ops, prompts for risky), skip (bypass all permission prompts). Omitted Codex mode defaults to safe writable edit; other harnesses default to plan. \'full\' accepted as alias for skip.', 'plan')
+        .option('-m, --mode <mode>', 'How much the agent can do: plan (read-only), edit (can write files), auto (more autonomous than edit, mechanism per-harness: smart classifier auto-approves safe ops and still prompts for risky ones on Claude/Copilot; approval_policy=never over the edit sandbox on Codex, which never prompts), skip (bypass all permission prompts). Omitted Codex mode defaults to safe writable edit; other harnesses default to plan. \'full\' accepted as alias for skip.', 'plan')
         .option('-e, --effort <effort>', 'Reasoning effort: low | medium | high | xhigh | max | auto (claude and codex only)', 'auto')
         .option('--model <model>', 'Cost tier (cheap|default|best|ultra) or a concrete model id; tiers resolve per harness+version to a supported model')
         .option('--env <key=value>', 'Pass environment variable to the agent (repeatable, e.g., --env DEBUG=1 --env API_KEY=xyz)', (val, prev) => [...prev, val], [])
@@ -517,14 +518,14 @@ export function registerRunCommand(program) {
         .option('--notify', 'Post a desktop notification when a headless run finishes. Fired by this process on exit, so it survives whatever launched the run (the menu bar dispatching it, a terminal you closed).')
         .option('--terminal [backend]', "Open this run in a real terminal tab instead of here. Without a value the terminal is detected from your live sessions (`agents sessions --active` host), so it lands where you already work — Ghostty for a Ghostty user, iTerm for an iTerm user. Name one to force it: iterm | ghostty | terminal | tmux | vscodium-agent. This is how the menu bar's New Session opens.")
         .option('--verbose', 'Show detailed execution logs')
-        .option('--raw', 'Interactive runs on macOS/Linux launch inside a shared tmux session (for %pane addressing + re-attach). Pass --raw to spawn the agent directly instead. Also disabled by AGENTS_NO_TMUX=1.')
-        .option('--no-tmux', 'Spawn the agent directly instead of wrapping it in the shared tmux session. Same effect as --raw / AGENTS_NO_TMUX=1. Use this to see the agent\'s full startup output when a launch is failing; to turn the wrap off for every run on this machine, set `agents config set devices.<name>.tmux off`.')
-        .option('--disable-tmux', 'Alias for --no-tmux.')
+        .option('--raw', 'Keep this interactive run direct when the device has opted into tmux wrapping. A no-op under the default tmux-off configuration; equivalent to AGENTS_NO_TMUX=1.')
+        .option('--no-tmux', 'Keep this run direct when tmux wrapping is enabled for the device. Same effect as --raw / AGENTS_NO_TMUX=1; it is a no-op under the default tmux-off configuration.')
+        .option('--disable-tmux', 'Compatibility alias for --no-tmux; a no-op when tmux wrapping is already off.')
         .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,antigravity). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
         .option('-b, --balanced', 'Shortcut for --strategy balanced. Ignored when @version is pinned.')
         .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then balanced (spreads load across healthy accounts and skips any that are rate-limited). (Legacy `rotate` accepted as alias for `balanced`.)')
-        .option('--account <name>', 'Use this durable provider credential for the run')
+        .option('--account <label>', 'Use this labeled native login or durable provider credential for the run')
         .option('--acp', 'Route through the Agent Client Protocol instead of direct exec. Supported for claude via @zed-industries/claude-code-acp adapter. Unified event stream; emits ndjson when --json.')
         .option('-y, --yes', 'Skip the interactive budget-confirm prompt (require_confirm_over). Never skips a hard budget block.', false)
         .option('--loop', 'Re-inject the prompt/entrypoint each iteration until a stop condition (issue #332). Guards (--max-iterations, --budget, --until) are enforced outside the agent. Writes a checkpoint after every iteration for --resume-checkpoint.')
@@ -534,7 +535,7 @@ export function registerRunCommand(program) {
         .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('--where <spec>', 'Where this run\'s body executes (one placement door): local | device:<name> | auto | lease[:backend] | cloud[:provider]. Expands to --device/--lease/--cloud. Do not combine with those flags. See docs/00-concepts.md#placement.')
-        .option('-D, --device <name>', 'Offload this run onto another machine over SSH — a registered device, or user@host. Pass "auto" to pick the least-loaded reachable device where the requested agent is installed and signed in, keeping the run local when no remote is better. Same as --where device:<name>. See `agents devices`.')
+        .option('-D, --device <name>', 'Offload this run onto another machine over SSH — a registered device, or user@host. Pass "auto" to pick the least-loaded reachable device where the requested agent is installed and signed in, keeping the run local when no remote is better, or "interactive" for the machine pinned as interactive.host (the box a human is sitting at). Same as --where device:<name>. See `agents devices`.')
         .option('--remote-cwd <dir>', "Explicit device working directory for --device runs, used VERBATIM (overrides --cwd; usually --cwd suffices — it re-roots a local-home path onto the remote home). Pass a single-quoted '$HOME/…' or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you).")
         .option('--no-follow', 'With --device, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
         .option('--any', 'With --device <cap> (a capability tag), pick any matching device instead of erroring when several match.')
@@ -636,7 +637,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
       Modes (not every agent supports every mode — run \`agents modes <agent>\`):
         plan  read-only investigation; no writes, no shell side-effects
         edit  may edit files; prompts for shell / risky operations
-        auto  smart classifier auto-approves safe ops, prompts for risky (claude, copilot)
+        auto  more autonomous than edit; the mechanism is per-harness --
+              claude, copilot: smart classifier auto-approves safe ops and
+                     STILL PROMPTS for risky ones
+              codex: approval_policy=never over the edit sandbox; never
+                     prompts at all, and a denied command fails instead
         skip  bypass every permission prompt (dangerously-skip-permissions)
         Legacy 'full' is silently rewritten to 'skip'.
         List per-harness support + native flags: agents modes · agents modes claude
@@ -829,7 +834,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             process.exit(1);
         }
         // Hard-deprecated harnesses cannot be run — point the user at the successor.
-        const runBaseAgentName = normalizedAgentSpec.split('@')[0];
+        const runBaseAgentName = normalizedAgentSpec.split('#')[0].split('@')[0];
         const runBaseAgentId = resolveAgentName(runBaseAgentName);
         const { profileExists: runProfileExists } = await import('../lib/profiles.js');
         if (runBaseAgentId && !runProfileExists(runBaseAgentName) && isAgentHardDeprecated(runBaseAgentId)) {
@@ -849,7 +854,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         }
         // `agents run auto`: the reserved harness keyword — full-auto dispatch
         // (host affinity → cross-harness balance → account balance, RUSH-2132).
-        if (normalizedAgentSpec.split('@')[0] === RUN_AUTO_KEYWORD && normalizedAgentSpec !== RUN_AUTO_KEYWORD) {
+        if (normalizedAgentSpec.split('#')[0].split('@')[0] === RUN_AUTO_KEYWORD && normalizedAgentSpec !== RUN_AUTO_KEYWORD) {
             console.error(chalk.red(`agents run auto picks the harness itself — a @version pin does not apply. ` +
                 `Pin a concrete harness instead: agents run <harness>@<version>.`));
             process.exit(1);
@@ -896,7 +901,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
             resolvedResumeSource = outcome.session;
-            const [requestedAgent, requestedVersion] = normalizedAgentSpec.split('@');
+            const [requestedAgent, requestedVersion] = normalizedAgentSpec.split('#')[0].split('@');
             if (!autoHarnessRequested && requestedAgent !== resolvedResumeSource.agent) {
                 console.error(chalk.red(`Session ${resolvedResumeSource.shortId} belongs to ${resolvedResumeSource.agent}, not ${requestedAgent}. ` +
                     `Use: agents sessions resume ${resolvedResumeSource.id}`));
@@ -982,9 +987,9 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 accountPickerRequested,
                 // `run auto` selects its harness after placement, so do not filter
                 // candidates against an arbitrary proxy harness at this stage.
-                agent: normalizedAgentSpec.split('@')[0] === RUN_AUTO_KEYWORD
+                agent: normalizedAgentSpec.split('#')[0].split('@')[0] === RUN_AUTO_KEYWORD
                     ? undefined
-                    : (resolveAgentName(normalizedAgentSpec.split('@')[0]) ?? undefined),
+                    : (resolveAgentName(normalizedAgentSpec.split('#')[0].split('@')[0]) ?? undefined),
             });
             if (!options.quiet && result.deprecationSmart) {
                 process.stderr.write(chalk.yellow('[agents] --smart is deprecated; use --device auto\n'));
@@ -1137,7 +1142,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             const { getConfiguredRunStrategy, resolveRunVersion } = await import('../lib/accounting/rotate.js');
             const { profileExists, readProfile, resolveProfileEnv } = await import('../lib/profiles.js');
             const detected = await detectSignedInRuntimes();
-            const [agentName, rawLeaseVersion] = normalizedAgentSpec.split('@');
+            const [agentName, rawLeaseVersion] = normalizedAgentSpec.split('#')[0].split('@');
             let runtime = null;
             let credentialRuntimes = [];
             let dispatchProfile;
@@ -1398,7 +1403,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 throw e;
             }
             try {
-                const [runAgent, rawRunVersion] = normalizedAgentSpec.split('@');
+                const [runAgent, rawRunVersion] = normalizedAgentSpec.split('#')[0].split('@');
                 // Forward the explicit @version pin verbatim. Resolving aliases like
                 // @latest locally would check local installs, but the remote host may
                 // have versions the laptop does not. The remote agents CLI resolves
@@ -1754,12 +1759,33 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             import('../lib/share/config.js'),
         ]);
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
-        // Parse agent@version
-        const [rawAgent, rawVersion] = normalizedAgentSpec.split('@');
+        // Parse agent@version#label. The label selects native auth without pinning
+        // the binary version; --account remains the equivalent flag form.
+        const labelParts = normalizedAgentSpec.split('#');
+        if (labelParts.length > 2 || labelParts[1] === '') {
+            console.error(chalk.red(`Invalid account label in '${normalizedAgentSpec}'.`));
+            process.exit(1);
+        }
+        const [rawAgent, rawVersion] = labelParts[0].split('@');
+        const specAccountLabel = labelParts[1];
+        if (resolveAgentName(rawAgent)) {
+            const parsed = parseAgentVersionSpec(normalizedAgentSpec);
+            if ('error' in parsed) {
+                console.error(chalk.red(parsed.error));
+                process.exit(1);
+            }
+        }
+        if (specAccountLabel && options.account && specAccountLabel !== options.account) {
+            console.error(chalk.red(`Account '${specAccountLabel}' from the agent spec conflicts with --account '${options.account}'.`));
+            process.exit(1);
+        }
+        if (specAccountLabel)
+            options.account = specAccountLabel;
         let agent;
         let version = rawVersion || undefined;
         let profileEnv;
         let accountEnv;
+        let accountConfigVersion;
         let profileProvider;
         let fromProfile = false;
         let profileFallbackModel;
@@ -2126,29 +2152,19 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     console.error(chalk.red(`Account '${spawnAccount.name}' is a device-local ${spawnAccount.agent} login and cannot be forwarded to '${remoteTarget}'. Sign in on that device and name the login there.`));
                     process.exit(1);
                 }
-                if (version) {
-                    // A pinned version must actually be signed in as the named identity.
-                    const { getAccountInfo } = await import('../lib/agents.js');
-                    const info = await getAccountInfo(agent, getVersionHomePath(agent, version));
-                    const liveKey = info.accountKey ?? info.email?.toLowerCase() ?? null;
-                    if (!info.signedIn || liveKey !== spawnAccount.identityKey) {
-                        console.error(chalk.red(`Account '${spawnAccount.name}' names a specific ${spawnAccount.agent} identity, but ${agent}@${version} ${info.signedIn ? 'is signed in as a different identity' : 'is not signed in'}. Sign in as that identity, or re-name the account.`));
-                        process.exit(1);
-                    }
+                const { CONFIG_ENV_ISOLATED_AGENTS } = await import('../lib/installations/shims.js');
+                if (!CONFIG_ENV_ISOLATED_AGENTS.includes(agent)) {
+                    console.error(chalk.red(`${agent} cannot select native accounts independently of its installed version.`));
+                    process.exit(1);
                 }
-                else {
-                    // No version pinned: locate the installed version currently signed in
-                    // as this identity and pin the run to it — do NOT assume the global
-                    // default holds it (the account may live on another installed copy).
-                    const { resolveAccountVersion } = await import('../lib/accounting/rotate.js');
-                    const matched = await resolveAccountVersion(agent, spawnAccount.identityKey);
-                    if (!matched) {
-                        console.error(chalk.red(`No installed ${spawnAccount.agent} version is signed in as the identity named by account '${spawnAccount.name}'. Sign in as that identity, or attach a different account.`));
-                        process.exit(1);
-                    }
-                    version = matched;
+                const { resolveAccountVersion } = await import('../lib/accounting/rotate.js');
+                accountConfigVersion = await resolveAccountVersion(agent, spawnAccount.identityKey) ?? undefined;
+                if (!accountConfigVersion) {
+                    console.error(chalk.red(`No installed ${spawnAccount.agent} version is signed in as the identity labeled '${spawnAccount.name}'. Sign in as that identity, or label a different account.`));
+                    process.exit(1);
                 }
-                // Native identity confirmed live; the harness reads it from its home.
+                if (!options.quiet)
+                    process.stderr.write(chalk.gray(`[agents] account '${spawnAccount.name}' · ${agent} auth from ${accountConfigVersion}\n`));
             }
             else {
                 accountEnv = spawnAccount.env;
@@ -2670,6 +2686,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         const execOptions = {
             agent,
             version,
+            configVersion: accountConfigVersion,
             prompt,
             interactive: options.interactive || forceInteractive,
             mode: requestedMode,

package/dist/commands/feed-watch.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerFeedWatchCommand(parent: Command): void;

package/dist/commands/feed-watch.js

@@ -0,0 +1,28 @@
+import { machineId } from '../lib/machine-id.js';
+import { setHelpSections } from '../lib/help.js';
+import { watchFleetFeed, watchLocalFeed } from '../lib/feed/watch.js';
+export function registerFeedWatchCommand(parent) {
+    const command = parent.command('watch').description('Stream the canonical agent, attention, and activity projection as NDJSON')
+        .option('--json', 'Emit versioned NDJSON envelopes').option('--local', 'Watch only this machine');
+    setHelpSections(command, { examples: `agents feed watch --json\nagents feed watch --json --local`, notes: 'Order by streamId + sequence. Unavailable scopes retain their last rows until reset on reconnect.' });
+    command.action(async (_opts, invoked) => {
+        const opts = invoked.optsWithGlobals();
+        if (!opts.json)
+            invoked.error("error: required option '--json' not specified");
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        const emit = (event) => process.stdout.write(`${JSON.stringify(event)}\n`);
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            if (opts.local)
+                await watchLocalFeed({ scope: machineId(), signal: controller.signal, emit });
+            else
+                await watchFleetFeed({ signal: controller.signal, emit });
+        }
+        finally {
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+        }
+    });
+}

package/dist/commands/feed.js

@@ -13,6 +13,8 @@ import { relTime } from '../lib/format.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { loadPolicy, applyPolicyToBlock, isPhoneUrgent } from '../lib/feed-policy.js';
 import { notifyUrgentBlock } from '../lib/notify.js';
+import { registerFeedWatchCommand } from './feed-watch.js';
+import { claimAndRouteAttentionAnswer, forwardFeedAnswer } from '../lib/feed/answer.js';
 import { gcMailbox } from '../lib/mailbox-gc.js';
 import { isValidMailboxId } from '../lib/mailbox.js';
 import { getActiveSessions } from '../lib/session/active.js';
@@ -323,6 +325,31 @@ export function registerFeedCommand(program) {
         .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');
+    registerFeedWatchCommand(feed);
+    feed.command('answer <attention-key>')
+        .description('Atomically claim and deliver one answer to an open attention item')
+        .option('--choice <choice-id>', 'Stable choice id from the attention item')
+        .option('--text <answer>', 'Free-text answer')
+        .option('--as <operator>', 'Verified operator id for high-consequence answers')
+        .option('--json', 'Emit the delivery result as JSON')
+        .action(async (attentionKey, opts, invoked) => {
+        try {
+            const ownerHost = attentionKey.slice(0, attentionKey.indexOf('/'));
+            const result = ownerHost && ownerHost !== machineId()
+                ? await forwardFeedAnswer({ host: ownerHost, attentionKey, choiceId: opts.choice, text: opts.text, operatorId: opts.as })
+                : await claimAndRouteAttentionAnswer({
+                    attentionKey, choiceId: opts.choice, text: opts.text,
+                    operator: { id: opts.as, verified: Boolean(opts.as), label: opts.as },
+                });
+            if (opts.json || invoked.parent?.opts()?.json)
+                console.log(JSON.stringify(result));
+            else
+                console.log(result.status === 'delivered' ? `Delivered ${result.receipt.msgId}.` : `Already answered (${result.receipt.at}).`);
+        }
+        catch (error) {
+            invoked.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
     feed
         .command('post')
         .description('Post a status update to the fleet activity stream (for agents)')

package/dist/commands/feedback.js

@@ -3,10 +3,10 @@
  * pre-filled with version + OS + agent inventory; falls back to printing the
  * URL when no browser is available.
  */
-import { spawnSync } from 'node:child_process';
 import { arch, platform, release } from 'node:os';
 import { createRequire } from 'node:module';
 import chalk from 'chalk';
+import { showUrl } from '../lib/open-url.js';
 const REPO = 'phnx-labs/agents-cli';
 const DISCUSSION_BASE = `https://github.com/${REPO}/discussions/new`;
 const ISSUE_BASE = `https://github.com/${REPO}/issues/new`;
@@ -20,22 +20,6 @@ function readCliVersion() {
         return 'unknown';
     }
 }
-function openInBrowser(url) {
-    const openers = process.platform === 'darwin'
-        ? [['open', [url]]]
-        : process.platform === 'win32'
-            ? [['cmd', ['/c', 'start', '""', url]]]
-            : [
-                ['xdg-open', [url]],
-                ['gnome-open', [url]]
-            ];
-    for (const [cmd, args] of openers) {
-        const r = spawnSync(cmd, args, { stdio: 'ignore' });
-        if (r.status === 0)
-            return true;
-    }
-    return false;
-}
 function buildPrefill(kind, summary) {
     const version = readCliVersion();
     const os = `${platform()} ${release()} (${arch()})`;
@@ -69,7 +53,7 @@ export function registerFeedbackCommand(program) {
         .option('-i, --idea', 'File as a feature idea (Discussions → Ideas)')
         .option('-q, --question', 'Ask a question (Discussions → Q&A)')
         .option('--print', 'Print the URL instead of opening it')
-        .action((summary, opts) => {
+        .action(async (summary, opts) => {
         const kind = opts.bug ? 'bug' : opts.idea ? 'idea' : 'question';
         const summaryText = (summary ?? []).join(' ').trim();
         const { url } = buildPrefill(kind, summaryText);
@@ -77,7 +61,7 @@ export function registerFeedbackCommand(program) {
             console.log(url);
             return;
         }
-        const opened = openInBrowser(url);
+        const opened = (await showUrl(url)).via !== 'none';
         if (opened) {
             console.log(chalk.dim(`Opened ${kind} form in your browser:\n  ${url}`));
         }

package/dist/commands/insights.d.ts

@@ -14,7 +14,7 @@
  *
  *   agents insights cost    what you spent ($ and duration)
  *   agents insights output  what shipped (burn vs PRs and commits)
- *   agents usage            live quota headroom
+ *   agents view             live quota headroom (per account, with auth state)
  *   agents perf             latency (hooks, CLI commands, agent.run) — not popularity
  *   agents sessions stats   which skills/slash-commands were explicitly invoked
  *

package/dist/commands/insights.js

@@ -14,7 +14,7 @@
  *
  *   agents insights cost    what you spent ($ and duration)
  *   agents insights output  what shipped (burn vs PRs and commits)
- *   agents usage            live quota headroom
+ *   agents view             live quota headroom (per account, with auth state)
  *   agents perf             latency (hooks, CLI commands, agent.run) — not popularity
  *   agents sessions stats   which skills/slash-commands were explicitly invoked
  *
@@ -577,7 +577,7 @@ function configureInsightsCommand(cmd) {
       Two paths under one verb:
         bare \`agents insights\`     — transcript behaviour (tools, friction, rhythm, by account)
         \`agents insights mix\`      — cheap counters from sessions.db + usage.db
-      Latency is \`agents perf\` (not mix). Quota is \`agents usage\`. Spend is
+      Latency is \`agents perf\` (not mix). Quota is \`agents view\`. Spend is
       \`agents insights cost\`; shipped output is \`agents insights output\`. Skill/slash popularity
       is \`agents sessions stats\`. Former top-level \`agents trends\` is \`agents insights mix\`
       (also \`agents insights trends\`).

package/dist/commands/lease.js

@@ -8,7 +8,7 @@
  * so a box a concurrent run just reused is never stopped.
  */
 import chalk from 'chalk';
-import { openUrl } from '../lib/open-url.js';
+import { showUrl } from '../lib/open-url.js';
 import { crabboxList, crabboxStop, reapSafeOrphans, reapOrphans, setLeaseSecretsBundle } from '../lib/crabbox/cli.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { bundleExists, readBundle, writeBundle, keychainRef, bundleItemStore } from '../lib/secrets/bundles.js';
@@ -94,7 +94,7 @@ async function captureTailscaleAuthKey() {
     const { password } = await import('@inquirer/prompts');
     let key;
     try {
-        openUrl(TAILSCALE_KEYS_URL);
+        await showUrl(TAILSCALE_KEYS_URL);
         key = (await password({ message: 'Paste a Tailscale auth key (blank to skip):', mask: true })).trim();
     }
     catch (e) {
@@ -155,7 +155,7 @@ export async function runLeaseSetup(opts = {}) {
     console.error(chalk.bold('\nSet up leasing (Hetzner) — one time (~30s):'));
     console.error(chalk.dim('Opening the Hetzner console. Create/select a project, then Security → API Tokens →'));
     console.error(chalk.dim('Generate a token with Read & Write permission, and copy it.\n'));
-    openUrl(HETZNER_CONSOLE_URL);
+    await showUrl(HETZNER_CONSOLE_URL);
     const { password } = await import('@inquirer/prompts');
     const ora = (await import('ora')).default;
     try {

package/dist/commands/routines.js

@@ -904,7 +904,7 @@ export function registerRoutinesCommands(program) {
         .option('--workflow <name>', 'Run an installed workflow (~/.agents/workflows/<name>) via `agents run`. Mutually exclusive with --agent.')
         .option('--command <sh>', 'Run a plain shell command directly (no agent, no auth, no sandbox) — for deterministic housekeeping routines. Mutually exclusive with --agent and --workflow; --prompt is not used.')
         .option('-p, --prompt <prompt>', 'Task instruction for the agent')
-        .option('-m, --mode <mode>', "Execution mode: plan (read-only), edit (can write files), auto (smart classifier, the default), or skip (bypass all permission prompts). 'full' accepted as alias for skip.", 'auto')
+        .option('-m, --mode <mode>', "Execution mode: plan (read-only), edit (can write files), auto (the default; more autonomous than edit, mechanism per-harness — see `agents modes <agent>`), or skip (bypass all permission prompts). 'full' accepted as alias for skip.", 'auto')
         .option('-e, --effort <effort>', 'Reasoning effort: low | medium | high | xhigh | max | auto', 'auto')
         .option('-t, --timeout <timeout>', 'Kill the agent if it runs longer than this (e.g., 10m, 2h, 3d, 1w; max 1w)', '10m')
         .option('--timezone <tz>', 'Interpret schedule in this timezone (e.g., America/Los_Angeles)')

package/dist/commands/sessions-picker-factory.d.ts

@@ -11,7 +11,8 @@ export interface SessionsPickerCommandSpec<TRow, TOpts extends SessionsPickerGat
      * selector) falls through to the flat printer. Computer has no `--open`.
      */
     requireOpenUndefined?: boolean;
-    runFlat: (opts: TOpts) => void;
+    /** May be async — the browser spec's flat path awaits an artifact open. */
+    runFlat: (opts: TOpts) => void | Promise<void>;
     buildRows: (opts: TOpts) => TRow[];
     emptyMessage: (opts: TOpts) => string;
     message: string;

package/dist/commands/sessions-picker-factory.js

@@ -44,7 +44,7 @@ export function createSessionsPickerCommand(spec) {
         shouldOpen,
         run: async (opts) => {
             if (!shouldOpen(opts, isInteractiveTerminal())) {
-                spec.runFlat(opts);
+                await spec.runFlat(opts);
                 return;
             }
             const rows = spec.buildRows(opts);

package/dist/commands/sessions-stop.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `agents sessions stop <id>` — end a live agent session outright: stop its
+ * interactive process and tear down its tmux/mux session, so the session becomes
+ * done/closed rather than an orphaned idle background process.
+ *
+ * The lifecycle sibling of `detach` that does NOT resume headless. `detach`
+ * backgrounds a still-wanted agent (stop the terminal, keep it working); `stop`
+ * is for when the work is over — the agent's editor tab was closed, or you want
+ * it gone. Both reuse the same live-session resolution and the same
+ * `stopInteractive` teardown (tmux `kill-session`, else SIGTERM→SIGKILL the pid),
+ * so a session killed here reaps its helpers exactly as `detach` does before it
+ * resumes.
+ *
+ * The primary caller is AGI EXT: when a user genuinely closes an agent tab
+ * (Cmd+W), the extension runs this so the underlying agent + its mux are shut
+ * down instead of being left running detached (the "Cmd+W orphans an idle
+ * session" bug). A window RELOAD does NOT call this — the extension distinguishes
+ * the two via `terminal.exitStatus.reason` and only a real user close tears down.
+ */
+import type { Command } from 'commander';
+export declare function registerSessionsStopCommand(program: Command): void;
+export declare function stopSessionAction(id: string, opts?: {
+    local?: boolean;
+}): Promise<void>;

package/dist/commands/sessions-stop.js

@@ -0,0 +1,66 @@
+import chalk from 'chalk';
+import { gatherLiveTargets } from './go.js';
+import { resolveDetachTarget, resolveOne } from './detach-core.js';
+import { stopInteractive } from './detach.js';
+import { runOnPeer } from '../lib/session/remote-list.js';
+import { setHelpSections } from '../lib/help.js';
+export function registerSessionsStopCommand(program) {
+    const cmd = program
+        .command('stop')
+        .argument('<id>', 'Short or full id of the live session to stop')
+        .option('--local', 'Only this machine (skip the cross-host sweep)')
+        .description('Stop a live agent outright — end its process and tear down its tmux/mux session')
+        .action(async (id, opts) => {
+        await stopSessionAction(id, opts);
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # Stop a live session by a short id prefix
+      agents sessions stop 4b2f1a9c
+
+      # Only look on this machine (skip the fleet sweep)
+      agents sessions stop 4b2f1a9c --local
+    `,
+        notes: `
+      stop ENDS the session; it does not background it. To keep an agent working
+      unattended instead, use \`agents sessions detach <id>\`, and bring it back
+      with \`agents sessions resume <id>\`.
+
+      A session that lives on another machine is stopped THERE over SSH — its pid
+      and tmux socket only mean something where it actually runs.
+    `,
+    });
+}
+export async function stopSessionAction(id, opts = {}) {
+    const { self, activeById } = await gatherLiveTargets(!!opts.local, { includeCloud: true });
+    const resolved = resolveOne(activeById, id);
+    if ('error' in resolved) {
+        console.error(chalk.red(resolved.error));
+        process.exitCode = 1;
+        return;
+    }
+    const s = resolved;
+    const target = resolveDetachTarget(s, self);
+    // Cloud/team/id-less sessions have their own lifecycles — refuse rather than
+    // half-stopping one from here (same boundary `detach` enforces).
+    if (target.kind === 'refuse') {
+        console.error(chalk.red(target.reason));
+        process.exitCode = 1;
+        return;
+    }
+    const short = target.sessionId.slice(0, 8);
+    // A session on another host: its pid/tmux socket only mean something where it
+    // runs, so stop it THERE over SSH — never kill locally. Mirrors detach/focus.
+    if (target.kind === 'remote') {
+        console.log(chalk.gray(`${short} lives on ${target.machine} — stopping it there over SSH…`));
+        const rc = await runOnPeer(['sessions', 'stop', target.sessionId, '--local'], target.machine);
+        if (rc === 'no-target') {
+            console.error(chalk.red(`Can't reach ${target.machine} to stop ${short}.`));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // Local: end the interactive process and tear down its tmux/mux session.
+    await stopInteractive(s);
+    console.log(chalk.green(`■ Stopped ${s.kind} ${short}`) + chalk.gray(' — process ended, session closed.'));
+}

package/dist/commands/sessions-trace.d.ts

@@ -0,0 +1,82 @@
+import type { Command } from 'commander';
+import type { SessionTrajectory } from '../lib/session/trajectory.js';
+import type { TrajectoryComparison, TrajectoryDivergence, TrajectorySummary } from '../lib/session/trajectory-compare.js';
+import type { TrajectoryStep } from '../lib/session/trajectory.js';
+import type { LineageEdge, LineageNode, SessionLineage } from '../lib/session/trajectory-lineage.js';
+/** Versioned envelope emitted by `--json` — the stable contract for consumers. */
+export declare const SESSIONS_TRACE_SCHEMA_VERSION = 1;
+/** The `diff` block of a `layout: 'compare'` envelope — everything but the two full trajectories, which already ride `sessions`. */
+export interface SessionsTraceDiffEnvelope {
+    divergence?: TrajectoryDivergence;
+    added: TrajectoryStep[];
+    removed: TrajectoryStep[];
+    summaryA: TrajectorySummary;
+    summaryB: TrajectorySummary;
+    truncatedA: number;
+    truncatedB: number;
+}
+/** The `lineage` block of a `layout: 'lineage'` envelope — the delegation graph. */
+export interface SessionsTraceLineageEnvelope {
+    rootId: string;
+    nodes: LineageNode[];
+    edges: LineageEdge[];
+    teams: string[];
+    unresolvedParentIds: string[];
+}
+/** The `--json` envelope: the versioned contract for the ext / triaging agents. */
+export interface SessionsTraceEnvelope {
+    schemaVersion: typeof SESSIONS_TRACE_SCHEMA_VERSION;
+    kind: 'sessions-trace';
+    layout: 'single' | 'compare' | 'lineage';
+    sessions: SessionTrajectory[];
+    diff?: SessionsTraceDiffEnvelope;
+    lineage?: SessionsTraceLineageEnvelope;
+}
+/** Build the versioned `--json` envelope for a single-session trajectory. */
+export declare function buildTraceEnvelope(models: SessionTrajectory[]): SessionsTraceEnvelope;
+/** Build the versioned `--json` envelope for a two-session compare. */
+export declare function buildCompareTraceEnvelope(cmp: TrajectoryComparison): SessionsTraceEnvelope;
+/**
+ * Build the versioned `--json` envelope for a lineage. `sessions` carries the
+ * ROOT's trajectory only: the graph's own numbers come from the indexed session
+ * rows, so a consumer pays one transcript parse instead of one per teammate —
+ * `agents sessions trace <child>` is how you get a child's full trajectory.
+ */
+export declare function buildLineageTraceEnvelope(lineage: SessionLineage, rootTrajectory: SessionTrajectory): SessionsTraceEnvelope;
+interface TraceOptions {
+    html?: boolean;
+    text?: boolean;
+    json?: boolean;
+    output?: string;
+    open?: boolean;
+    errorsOnly?: boolean;
+    redact?: boolean;
+    all?: boolean;
+    since?: string;
+    limit?: string;
+    agent?: string;
+    compare?: boolean;
+    tree?: boolean;
+}
+export type RenderFormat = 'html' | 'text' | 'json';
+/**
+ * Pick the rendering by audience: explicit `--html/--text/--json` win; otherwise
+ * a person at a TTY gets the visual HTML and a piped/headless caller (an agent)
+ * gets the compact text trajectory.
+ */
+export declare function chooseFormat(options: TraceOptions, isTTY: boolean): RenderFormat;
+/**
+ * Decide the trace layout from what the user TYPED (`selectorCount`) vs what
+ * those selectors RESOLVED to (`resolvedCount`). Keyed on selector count so a
+ * single content-search selector that happens to match two sessions never
+ * silently becomes a compare — every unsupported combination fails loud with a
+ * clear message. Pure, so the boundaries are unit-tested without the command.
+ */
+export declare function decideTraceLayout(options: Pick<TraceOptions, 'tree' | 'compare'>, selectorCount: number, resolvedCount: number): 'single' | 'compare' | 'lineage';
+/** Attach the trace behaviour to a command node (canonical or top-level alias). */
+export declare function configureTraceCommand(cmd: Command): Command;
+/** Canonical `agents sessions trace <selectors...>`. */
+export declare function registerSessionsTraceCommand(sessionsCmd: Command): void;
+/** Top-level alias `agents trace <selectors...>` (mirrors `agents insights`). */
+export declare function registerTraceCommand(program: Command): void;
+export {};