@phnx-labs/agents-cli 1.20.72 → 1.20.74

package/dist/commands/exec.js

@@ -8,10 +8,12 @@
 import { Option } from 'commander';
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
-import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
+import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
+import { getUserAgentsDir } from '../lib/state.js';
 import { parseLoopInterval } from '../lib/loop.js';
 import { AGENTS } from '../lib/agents.js';
 import { recordDispatchedRun } from '../lib/audit/log.js';
+import { maybeShowStarNudge } from '../lib/star-nudge.js';
 import { warnUnpushedWork, shouldWarnUnpushed } from '../lib/warn-unpushed.js';
 import { isHostPinned, pinHostKey, managedKnownHostsPath } from '../lib/devices/known-hosts.js';
 import { sshResolve } from '../lib/hosts/ssh-config.js';
@@ -19,6 +21,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { randomUUID } from 'crypto';
+import { spawnSync } from 'child_process';
 /** Distinguish a terminal account-picker marker from an explicit @version pin. */
 export function parseRunAccountPickerRequest(agentSpec) {
     const requested = agentSpec.endsWith('@');
@@ -40,6 +43,8 @@ export function runAccountPickerConflicts(options) {
         conflicts.push('--balanced');
     if (options.lease)
         conflicts.push('--lease');
+    if (options.box)
+        conflicts.push('--box');
     if (options.host || options.device || options.on || options.computer)
         conflicts.push('--host/--device');
     return conflicts;
@@ -55,6 +60,77 @@ function formatRotationBanner(result, verb = 'balanced') {
     const ratio = `${healthy.length} of ${healthy.length + excluded.length} healthy`;
     return `[agents] ${verb} picked ${label} (${ratio})`;
 }
+/**
+ * Whether `cwd` is inside a git work tree.
+ *
+ * `--lease` / `--box` sync the working directory to the box through crabbox,
+ * which enumerates the files to copy with `git ls-files`. Outside a git repo
+ * that exits 128 (`fatal: not a git repository`) and the whole run dies at
+ * "build sync file list: exit status 128" — AFTER the box is provisioned and
+ * billed. Checking this up front lets the caller fail fast, before provisioning.
+ */
+export function isInsideGitWorkTree(cwd) {
+    const r = spawnSync('git', ['-C', cwd, 'rev-parse', '--is-inside-work-tree'], {
+        encoding: 'utf-8',
+    });
+    return r.status === 0 && r.stdout.trim() === 'true';
+}
+/** Absolute git toplevel for `cwd`, or null when it is not a git repo. */
+export function gitToplevel(cwd) {
+    const r = spawnSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], { encoding: 'utf-8' });
+    return r.status === 0 ? r.stdout.trim() : null;
+}
+/**
+ * Network mode for a `--lease` run (F5, RUSH-1924). `--tailscale` forces the
+ * tailnet, `--no-tailscale` forces public, and neither (undefined) defaults to
+ * the tailnet ONLY in a reuse context (`--reuse`, `--box`, or a picked warm
+ * box) — a one-shot solo `--lease` stays public. Pure so it is unit-testable;
+ * the caller downgrades to `'public'` when no auth key is configured.
+ */
+export function computeNetMode(opts) {
+    if (opts.tailscale === false)
+        return 'public'; // --no-tailscale wins
+    if (opts.tailscale === true)
+        return 'tailscale'; // explicit --tailscale
+    return opts.reuseContext ? 'tailscale' : 'public';
+}
+// ── "Always provision fresh" per-repo memory (F3, RUSH-1922) ─────────────────
+// The picker's "Always provision fresh (remember for this repo)" choice is
+// persisted as a list of git-toplevel paths in a small state file, so a repo
+// that opted out of the reuse picker is never prompted again.
+/** True when `repoRoot` is in the remembered always-fresh set. Pure. */
+export function isAlwaysFreshRepo(repos, repoRoot) {
+    return repos.includes(repoRoot);
+}
+/** Add `repoRoot` to the always-fresh set (idempotent). Pure. */
+export function addAlwaysFreshRepo(repos, repoRoot) {
+    return repos.includes(repoRoot) ? repos : [...repos, repoRoot];
+}
+/** Path to the always-fresh state file under the USER agents dir (CLI-written per-user preference, never the maintainer-owned `.system` repo). */
+export function leaseFreshReposPath() {
+    return path.join(getUserAgentsDir(), 'lease-fresh-repos.json');
+}
+/** Read the remembered always-fresh repo roots (empty on any read/parse error). */
+export function readAlwaysFreshRepos() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(leaseFreshReposPath(), 'utf-8'));
+        return Array.isArray(parsed) ? parsed.filter((x) => typeof x === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Persist the always-fresh repo roots. Best-effort — never throws. */
+export function writeAlwaysFreshRepos(repos) {
+    try {
+        const p = leaseFreshReposPath();
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(repos, null, 2));
+    }
+    catch {
+        /* best-effort — losing the preference just means the picker shows next time */
+    }
+}
 /**
  * Decide whether `--copy-creds` may ship credentials (and the Claude OAuth
  * token) to `host` (RUSH-1767). Credentials ship only to a host whose SSH host
@@ -313,7 +389,12 @@ export function registerRunCommand(program) {
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.')
         .option('--copy-creds', 'With --host, copy the picked runtime credentials (and Claude OAuth token) to the host, then shred them after the run. Opt-in per run.')
         .option('--lease [backend]', 'Invent a disposable cloud box for this run and tear it down after (via crabbox). Optional backend selects the cloud (hetzner/aws/do). Unlike --host, no machine is registered.')
-        .option('--keep-box', 'With --lease, keep the box after the run instead of stopping it.');
+        .option('--box <slug>', 'Reuse an existing warm crabbox box for this run instead of provisioning a disposable --lease box.')
+        .option('--keep-box', 'With --lease, keep the box after the run instead of stopping it.')
+        .option('--reuse', 'With --lease, reuse the most-recently-used warm box if one exists (else provision fresh). The scriptable form of the interactive reuse picker.')
+        .option('--bare', 'With --lease, skip copying your local ~/.agents setup (skills/hooks/commands/MCP) onto the box.')
+        .option('--tailscale', 'Lease the box onto your tailnet (reachable only over Tailscale) rather than a public IP.')
+        .option('--no-tailscale', 'Force a public-IP lease even when a reuse context would default to Tailscale.');
     // `--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());
@@ -422,17 +503,31 @@ export function registerRunCommand(program) {
             }
         }
         // --lease: invent a disposable cloud box for this run (via crabbox), run
-        // the agent there, then tear it down. Unlike --host, nothing is registered.
-        if (options.lease) {
+        // the agent there, then tear it down. --box: reuse a named warm crabbox
+        // box, run the same bootstrap there, and leave the box running.
+        if (options.lease || options.box) {
             if (prompt === undefined) {
-                console.error(chalk.red('A prompt is required for leased runs: agents run <agent> "<task>" --lease'));
+                console.error(chalk.red(`A prompt is required for crabbox runs: agents run <agent> "<task>" ${options.box ? '--box <slug>' : '--lease'}`));
+                process.exit(1);
+            }
+            if (options.lease && options.box) {
+                console.error(chalk.red('Pass either --lease to provision a disposable box, or --box <slug> to reuse a warm box — not both.'));
                 process.exit(1);
             }
             const backend = typeof options.lease === 'string' ? options.lease : undefined;
+            // crabbox syncs this directory to the box via `git ls-files`; outside a
+            // git repo that fails with "build sync file list: exit status 128" — but
+            // only AFTER the box is provisioned and billed. Fail fast here instead.
+            const leaseCwd = options.cwd ?? process.cwd();
+            if (!isInsideGitWorkTree(leaseCwd)) {
+                console.error(chalk.red(`${options.box ? '--box' : '--lease'} syncs the working directory to the box, but ${leaseCwd} is not a git repository.`));
+                console.error(chalk.yellow(`Run from inside a git repo, or initialize one: (cd ${leaseCwd} && git init)`));
+                process.exit(1);
+            }
             // First-run: no provider credential resolves (no env var, no config, no
             // detectable bundle) → guide the user through one-time setup, then continue.
             const { resolveLeaseBundle } = await import('../lib/crabbox/cli.js');
-            if (!resolveLeaseBundle()) {
+            if (options.lease && !resolveLeaseBundle()) {
                 const { runLeaseSetup } = await import('./lease.js');
                 const ok = await runLeaseSetup({ provider: backend ?? 'hetzner' });
                 if (!ok) {
@@ -440,22 +535,140 @@ export function registerRunCommand(program) {
                     process.exit(1);
                 }
             }
-            const { detectSignedInRuntimes, resolveClaudeCredentialsBlob, inferLeaseRuntime } = await import('../lib/crabbox/runtimes.js');
+            // ── F3 reuse (RUSH-1922) + F5 net-mode (RUSH-1924) ───────────────────
+            // Resolve which box this run targets and how it is networked BEFORE any
+            // provisioning. `--box` is an explicit reuse; otherwise, on an
+            // interactive tty, offer the warm boxes as a reuse picker (headless /
+            // --json never blocks — it provisions fresh unless --reuse/--box).
+            const leaseSecretsBundle = process.env.AGENTS_LEASE_SECRETS_BUNDLE;
+            const nowSecs = Math.floor(Date.now() / 1000);
+            let reuseSlug = options.box;
+            if (options.lease && !reuseSlug) {
+                const { crabboxList } = await import('../lib/crabbox/cli.js');
+                const { reusableBoxes, formatBoxRow } = await import('./lease.js');
+                let warm = [];
+                try {
+                    warm = reusableBoxes(crabboxList({ secretsBundle: leaseSecretsBundle }), nowSecs);
+                }
+                catch {
+                    warm = []; // crabbox unavailable / no creds → just provision fresh
+                }
+                const repoRoot = gitToplevel(leaseCwd);
+                const alwaysFresh = repoRoot ? isAlwaysFreshRepo(readAlwaysFreshRepos(), repoRoot) : false;
+                if (warm.length > 0 && !alwaysFresh) {
+                    if (options.reuse) {
+                        reuseSlug = warm[0].slug; // scriptable: most-recently-touched warm box
+                    }
+                    else if (isInteractiveTerminal() && options.json !== true) {
+                        const { select } = await import('@inquirer/prompts');
+                        try {
+                            const choice = await select({
+                                message: 'Reuse a warm box, or provision a fresh one?',
+                                choices: [
+                                    ...warm.map((b) => ({ name: formatBoxRow(b, nowSecs), value: b.slug })),
+                                    { name: 'Provision a fresh box', value: '__fresh__' },
+                                    { name: 'Always provision fresh (remember for this repo)', value: '__always_fresh__' },
+                                ],
+                            });
+                            if (choice === '__always_fresh__') {
+                                if (repoRoot) {
+                                    writeAlwaysFreshRepos(addAlwaysFreshRepo(readAlwaysFreshRepos(), repoRoot));
+                                    console.error(chalk.dim(`Will always provision fresh for ${repoRoot} (edit ${leaseFreshReposPath()} to undo).`));
+                                }
+                            }
+                            else if (choice !== '__fresh__') {
+                                reuseSlug = choice;
+                            }
+                        }
+                        catch (e) {
+                            if (!isPromptCancelled(e))
+                                throw e;
+                            console.error(chalk.yellow('Selection cancelled — provisioning a fresh box.'));
+                        }
+                    }
+                    // Headless with no --reuse falls through here → provision fresh.
+                }
+                else if (options.reuse && warm.length > 0) {
+                    // --reuse still honors a warm box even when the picker is suppressed.
+                    reuseSlug = warm[0].slug;
+                }
+            }
+            // reuseContext: an existing box (picked, --box, or --reuse) defaults the
+            // network to the tailnet; a solo one-shot --lease stays public.
+            const reuseContext = !!reuseSlug || !!options.reuse;
+            let netMode = computeNetMode({ tailscale: options.tailscale, reuseContext });
+            const copySetup = !options.bare;
+            // Tailscale requested but no auth key configured → downgrade to public
+            // with an actionable hint instead of hard-failing the run (F5).
+            if (netMode === 'tailscale') {
+                const { pickTailscaleBundleFromList } = await import('../lib/crabbox/cli.js');
+                const { listBundles } = await import('../lib/secrets/bundles.js');
+                let hasKey = !!process.env.CRABBOX_TAILSCALE_AUTH_KEY;
+                if (!hasKey) {
+                    try {
+                        hasKey = !!pickTailscaleBundleFromList(listBundles());
+                    }
+                    catch {
+                        hasKey = false;
+                    }
+                }
+                if (!hasKey) {
+                    console.error(chalk.yellow('Tailscale requested but no auth key is configured — falling back to a public-IP lease.'));
+                    console.error(chalk.gray('Set one up with `agents lease setup` (mint an EPHEMERAL, pre-authorized, tag:crabbox key), or store CRABBOX_TAILSCALE_AUTH_KEY in a secrets bundle.'));
+                    netMode = 'public';
+                }
+            }
+            const { detectSignedInRuntimes, resolveClaudeCredentialsBlob, inferLeaseRuntime, profileNeedsBaseRuntimeCredentials } = await import('../lib/crabbox/runtimes.js');
             const { leaseAndRun } = await import('../lib/crabbox/lease.js');
+            const { boxAddress } = await import('./lease.js');
             const { getConfiguredRunStrategy, resolveRunVersion } = await import('../lib/rotate.js');
+            const { profileExists, readProfile, resolveProfileEnv } = await import('../lib/profiles.js');
             const detected = await detectSignedInRuntimes();
-            const agentName = normalizedAgentSpec.split('@')[0];
-            const leaseCwd = options.cwd ?? process.cwd();
+            const [agentName, rawLeaseVersion] = normalizedAgentSpec.split('@');
+            let runtime = null;
+            let credentialRuntimes = [];
+            let dispatchProfile;
             // `--lease` requires a prompt (guarded above), so it is headless by
             // contract — never block on an interactive picker. Provision exactly the
             // one runtime this run needs, inferred from the agent, not every
             // signed-in CLI (which would ship unrelated tokens to a throwaway box).
-            const runtime = inferLeaseRuntime(agentName, detected);
+            if (profileExists(agentName)) {
+                try {
+                    const profile = readProfile(agentName);
+                    const profileEnv = resolveProfileEnv(profile);
+                    runtime = profile.host.agent;
+                    const profileNeedsCredentials = profileNeedsBaseRuntimeCredentials(runtime, profileEnv, profile.auth?.envVar);
+                    credentialRuntimes = profileNeedsCredentials ? [runtime] : [];
+                    dispatchProfile = {
+                        name: profile.name,
+                        agent: profile.host.agent,
+                        version: rawLeaseVersion || profile.host.version,
+                        env: profileEnv,
+                        description: profile.description,
+                        preset: profile.preset,
+                        provider: profile.provider,
+                        fallbackModel: profile.fallback_model,
+                    };
+                }
+                catch (err) {
+                    console.error(chalk.red(err.message));
+                    process.exit(1);
+                }
+            }
+            else {
+                runtime = inferLeaseRuntime(agentName, detected);
+                if (runtime)
+                    credentialRuntimes = [runtime];
+            }
             if (!runtime) {
                 console.error(chalk.yellow('No signed-in runtime to provision on the box. Sign into one locally (e.g. run `claude` once) then retry.'));
                 process.exit(1);
             }
             const runtimes = [runtime];
+            if (credentialRuntimes.length > 0 && !detected.some((d) => d.id === runtime && d.signedIn && d.credPath)) {
+                console.error(chalk.yellow(`Profile '${agentName}' needs ${runtime} credentials, but ${runtime} is not signed in locally. Sign in locally, then retry.`));
+                process.exit(1);
+            }
             // Copy the account the run's OWN strategy would pick (default `balanced`:
             // a healthy, non-rate-limited account weighted by remaining headroom) —
             // never the raw default signed-in one, which could be throttled or out of
@@ -468,7 +681,7 @@ export function registerRunCommand(program) {
             // the notice below would name a balanced-picked account that is NOT the one
             // actually shipped. Best-effort: fall back to the default account on error.
             let leaseEmail = detected.find((d) => d.id === runtime)?.email ?? null;
-            if (runtime === 'claude') {
+            if (credentialRuntimes.includes('claude')) {
                 try {
                     const strategy = getConfiguredRunStrategy(runtime, leaseCwd);
                     const { rotation } = await resolveRunVersion(runtime, strategy, leaseCwd);
@@ -483,43 +696,82 @@ export function registerRunCommand(program) {
             // where — copying an auth token to a cloud box is a credential transfer.
             // The box is destroyed after the run, so the credential's lifetime is
             // bounded by the run.
-            const whatShips = runtime === 'claude' ? 'credentials + Claude OAuth token' : 'credentials';
-            console.error(chalk.gray(`Leasing a ${backend ?? 'hetzner'} box · shipping ${runtime}${leaseEmail ? ` (${leaseEmail})` : ''} ${whatShips}; the box is destroyed after the run.`));
+            const whatShips = credentialRuntimes.includes('claude')
+                ? `${dispatchProfile ? `profile '${dispatchProfile.name}', ` : ''}${runtime} credentials + Claude OAuth token`
+                : credentialRuntimes.length > 0
+                    ? `${dispatchProfile ? `profile '${dispatchProfile.name}', ` : ''}${runtime} credentials`
+                    : dispatchProfile
+                        ? `profile '${dispatchProfile.name}'`
+                        : `${runtime} credentials`;
+            const boxLifecycle = reuseSlug
+                ? `Reusing crabbox box ${reuseSlug}`
+                : `Leasing a ${backend ?? 'hetzner'} box${netMode === 'tailscale' ? ' on your tailnet' : ''}`;
+            const boxAfterRun = reuseSlug
+                ? 'the box is kept after the run'
+                : options.keepBox
+                    ? 'the box is kept after the run'
+                    : 'the box is destroyed after the run';
+            console.error(chalk.gray(`${boxLifecycle} · shipping ${whatShips}${credentialRuntimes.length > 0 && leaseEmail ? ` (${leaseEmail})` : ''}; ${boxAfterRun}.`));
             // Read the Claude OAuth token from the local Keychain (silent) so it can be
             // written to ~/.claude/.credentials.json on the box — otherwise Claude boots
             // "Not logged in". `preferEmail` targets the strategy-picked account so the
             // token matches the account this run resolved to.
             let claudeCredentialsJson = null;
-            if (runtime === 'claude') {
+            if (credentialRuntimes.includes('claude')) {
                 claudeCredentialsJson = await resolveClaudeCredentialsBlob({ preferEmail: leaseEmail });
                 if (!claudeCredentialsJson) {
                     console.error(chalk.yellow('Warning: could not read the local Claude OAuth token — the box may come up "Not logged in".'));
                 }
             }
-            // Progress UI. A self-throttled spinner (NOT ora — see progress.ts) covers
-            // the otherwise-silent provisioning + box-setup phases; the agent's own
-            // output then prints verbatim. The router splits the crabbox stream at the
-            // box-side marker. Rule: only ONE spinner phase is active at a time, and no
-            // other output is written to stderr while it spins — so it can never storm.
-            const { createLeaseOutputRouter, createSpinner } = await import('../lib/crabbox/progress.js');
+            // Progress UI (F2, RUSH-1921). A self-throttled spinner (NOT ora — see
+            // progress.ts) covers provisioning; the box-side bootstrap then streams a
+            // structured step stream (sync → install → runtime → creds → …) via the
+            // router's `onStep`, and each step renders as a checklist line through the
+            // lib's `renderStepLine` (✔ <Step> — <detail> (<elapsed>)). The agent's own
+            // output prints verbatim after the box-side marker. Rule: only ONE spinner
+            // phase is active at a time, so it can never storm.
+            const { createLeaseOutputRouter, createSpinner, renderStepLine } = await import('../lib/crabbox/progress.js');
             const spinner = createSpinner({ stream: process.stderr });
             let warmupTimer;
             const stopTimer = () => { if (warmupTimer) {
                 clearInterval(warmupTimer);
                 warmupTimer = undefined;
             } };
-            const fit = (s) => {
-                const w = Math.max(20, (process.stderr.columns || 80) - 24);
-                return s.length > w ? s.slice(0, w - 1) + '…' : s;
+            const jsonMode = options.json === true;
+            const stepsTty = Boolean(process.stderr.isTTY) && !jsonMode;
+            // The step currently in flight (its label spins on a TTY). It is persisted
+            // as a ✔ line when the NEXT step arrives (whose elapsedMs measures how long
+            // THIS step's block took) — or, for the last step, when agent output or
+            // teardown begins.
+            let activeStep = null;
+            const flushStep = (elapsedMs) => {
+                if (!activeStep)
+                    return;
+                const done = activeStep;
+                activeStep = null;
+                if (jsonMode) {
+                    process.stdout.write(JSON.stringify({ phase: 'setup', name: done.name, elapsedMs: elapsedMs ?? null }) + '\n');
+                }
+                else {
+                    spinner.stopAndPersist('✔', renderStepLine({ ...done, elapsedMs }));
+                }
             };
             const router = createLeaseOutputRouter({
-                // Setup lines only ever update spinner text (no direct stderr writes),
-                // so the spinner stays the single writer during the setup phase.
-                onSetupLine: (line) => spinner.update(`Setting up box — ${fit(line)}`),
+                now: () => Date.now(),
+                // Raw setup lines stay captured for a failure dump (router.setupLines());
+                // the structured step stream drives the visible checklist, so plain lines
+                // are not shown (they would fight the step spinner).
+                onSetupLine: () => { },
+                onStep: (step) => {
+                    flushStep(step.elapsedMs); // persist the previous step, timed by this one
+                    activeStep = step;
+                    if (stepsTty)
+                        spinner.start(renderStepLine(step));
+                },
                 onAgentChunk: (chunk) => {
-                    // First agent byte: stop the setup spinner, THEN stream to stdout.
+                    flushStep(); // last setup step done (no following sentinel to time it)
                     if (spinner.active)
-                        spinner.stopAndPersist('✔', chalk.gray(`Box provisioned — ${agentName} output:`));
+                        spinner.stop();
                     process.stdout.write(chunk);
                 },
             });
@@ -531,30 +783,41 @@ export function registerRunCommand(program) {
                     model: options.model,
                     backend,
                     runtimes,
+                    credentialRuntimes,
                     detected,
+                    dispatchProfile,
                     claudeCredentialsJson,
-                    secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE,
+                    secretsBundle: leaseSecretsBundle,
                     keep: options.keepBox,
+                    reuseBox: reuseSlug,
+                    copySetup,
+                    netMode,
                     onData: (chunk) => router.push(chunk),
                     onPhase: (phase) => {
                         if (phase.kind === 'warmup') {
-                            const label = `Leasing a ${phase.backend ?? 'hetzner'} box`;
+                            const label = `Leasing a ${phase.backend ?? 'hetzner'} box${netMode === 'tailscale' ? ' (tailnet)' : ''}`;
                             spinner.start(`${label}…`);
                             const t0 = Date.now();
                             warmupTimer = setInterval(() => spinner.update(`${label}… (${Math.round((Date.now() - t0) / 1000)}s)`), 1000);
                         }
+                        else if (phase.kind === 'reuse') {
+                            spinner.start(`Reusing crabbox box ${phase.slug}…`);
+                        }
                         else if (phase.kind === 'ready') {
                             stopTimer();
-                            spinner.stopAndPersist('✔', `Box ${phase.box.slug} ready${phase.box.ip ? ` (${phase.box.ip})` : ''} · ${Math.round(phase.elapsedMs / 1000)}s`);
-                            spinner.start('Setting up box…');
+                            const addr = boxAddress(phase.box);
+                            // Steps drive the spinner from here — no generic "Setting up box…".
+                            spinner.stopAndPersist('✔', `Box ${phase.box.slug} ready${addr ? ` (${addr})` : ''} · ${Math.round(phase.elapsedMs / 1000)}s`);
                         }
                         else if (phase.kind === 'teardown') {
+                            flushStep();
                             if (spinner.active)
                                 spinner.stop();
                         }
                     },
                 });
                 router.end();
+                flushStep();
                 stopTimer();
                 if (spinner.active)
                     spinner.stop();
@@ -566,11 +829,13 @@ export function registerRunCommand(program) {
                     if (log.length)
                         process.stderr.write(chalk.dim(log.join('\n')) + '\n');
                 }
-                console.error(chalk.gray(toreDown ? `Box ${box.slug} destroyed.` : `Box ${box.slug} kept${box.ip ? ` (${box.ip})` : ''}. Stop it: crabbox stop ${box.slug}`));
+                const keptAddr = boxAddress(box);
+                console.error(chalk.gray(toreDown ? `Box ${box.slug} destroyed.` : `Box ${box.slug} kept${keptAddr ? ` (${keptAddr})` : ''}. Stop it: agents lease stop ${box.slug}`));
                 process.exit(exitCode === null ? 1 : exitCode);
             }
             catch (err) {
                 stopTimer();
+                flushStep();
                 if (spinner.active)
                     spinner.stopAndPersist('✖', chalk.red('Lease failed'));
                 const log = router.setupLines();
@@ -956,7 +1221,7 @@ export function registerRunCommand(program) {
                 await warnUnpushedWork(resumeExec.cwd ?? process.cwd());
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive }, { 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 },] = 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, 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([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -969,6 +1234,7 @@ export function registerRunCommand(program) {
             import('../lib/run-defaults.js'),
             import('../lib/mcp.js'),
             import('../lib/capabilities.js'),
+            import('../lib/share/config.js'),
         ]);
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
         // Parse agent@version
@@ -1433,7 +1699,14 @@ export function registerRunCommand(program) {
             if (launchTarget) {
                 const healed = await ensureAgentRunnable(agent, launchTarget, options.quiet ? undefined : (m) => process.stderr.write(chalk.yellow(`[agents] ${m}\n`)));
                 if (healed === null) {
-                    console.error(chalk.red(`agents: ${agent}@${launchTarget} is not runnable and could not be repaired. Try: agents add ${agent}@latest`));
+                    // An isolated copy is never repaired by adopting another version, so
+                    // `add <agent>@latest` would build an unrelated NORMAL install rather
+                    // than fix what the user asked to run. Point at the isolated re-add.
+                    const { isVersionIsolated } = await import('../lib/versions.js');
+                    const hint = isVersionIsolated(agent, launchTarget)
+                        ? `agents add ${agent}@${launchTarget} --isolated`
+                        : `agents add ${agent}@latest`;
+                    console.error(chalk.red(`agents: ${agent}@${launchTarget} is not runnable and could not be repaired. Try: ${hint}`));
                     process.exit(1);
                 }
                 // Always adopt the healed version explicitly. In the version-undefined
@@ -1608,12 +1881,17 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
         }
-        // Merge order (later wins): profile env < secrets bundles < --env K=V.
+        const autoShareEnv = options.autoSecrets !== false
+            ? shareRuntimeEnv({ agentOnly: isHeadlessSecretsContext() })
+            : undefined;
+        // Merge order (later wins): profile env < auto share token < secrets bundles < --env K=V.
         // Profile carries provider auth; secrets bundles carry user-defined
-        // values; --env is the per-invocation override.
-        const hasOverrides = profileEnv || options.secrets.length > 0 || userEnv;
+        // values; --env is the per-invocation override. The share token is
+        // best-effort: if it is not already in env or an unlocked bundle, unrelated
+        // runs keep working, and `agents share` itself still fails loudly on use.
+        const hasOverrides = profileEnv || autoShareEnv || options.secrets.length > 0 || userEnv;
         const env = hasOverrides
-            ? { ...(profileEnv ?? {}), ...secretsEnv, ...(userEnv ?? {}) }
+            ? { ...(profileEnv ?? {}), ...(autoShareEnv ?? {}), ...secretsEnv, ...(userEnv ?? {}) }
             : undefined;
         const modelSource = runCmd.getOptionValueSource('model');
         const model = options.model
@@ -1940,6 +2218,22 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
         }
+        // Agent footgun (RUSH-1829): a run with no prompt and no explicit
+        // --interactive resolves to interactive intent, but in a non-TTY shell
+        // (a headless agent, a pipe, CI) there is no terminal to host the REPL —
+        // the TUI attaches to dead stdin and hangs forever. Fail fast with the
+        // headless alternatives instead of launching a doomed interactive session.
+        if (inferredInteractiveWithoutTty(execOptions, isInteractiveTerminal())) {
+            // Tear down the workflow MCP config + subagents staged above before we
+            // exit — same as every sibling exit path; requireInteractiveSelection
+            // process.exits, so cleanup must happen first or it leaks.
+            cleanupWorkflowMcpConfig();
+            cleanupWorkflowSubagents();
+            requireInteractiveSelection(`Launching ${agent} interactively`, [
+                `agents run ${agent} "<your task>"   # headless: prints the agent's result`,
+                `agents run ${agent} --headless        # headless: reads the prompt from stdin`,
+            ]);
+        }
         try {
             let exitCode;
             let ranAgent = agent;
@@ -1968,6 +2262,10 @@ export function registerRunCommand(program) {
             // Governance chokepoint (#347): every dispatched run finalizes here.
             // ONE tamper-evident audit record per run — non-fatal by contract.
             recordDispatchedRun({ agent: ranAgent, version: ranVersion ?? 'unknown', mode, cwd, exitCode });
+            // First-successful-run star nudge (one-time, non-nagging). Only on a
+            // clean run, and never when output is machine-readable/quiet.
+            if (exitCode === 0)
+                maybeShowStarNudge({ quiet: options.json || options.quiet });
             process.exit(exitCode);
         }
         catch (err) {

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;