@phnx-labs/agents-cli 1.22.8 → 1.22.9

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

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
+export declare const MARKDOWN_RENDER_AGENTS: readonly ["claude", "codex", "gemini", "antigravity", "opencode", "grok", "rush", "hermes", "kimi", "droid", "cursor"];
+export type ReasoningMode = 'omit' | 'fold' | 'include';
+/** Build one shareable Markdown document from the canonical preview and event model. */
+export declare function renderSessionMarkdownDocument(session: SessionMeta, options?: {
+    redact?: boolean;
+    reasoning?: ReasoningMode;
+    knownSecrets?: readonly string[];
+    maxToolOutputChars?: number;
+}): string;
+export declare function registerSessionsRenderCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-render.js

@@ -0,0 +1,124 @@
+/** Render selected normalized session transcripts as redacted Markdown documents. */
+import * as fs from 'fs';
+import { stripVTControlCharacters } from 'node:util';
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { knownSecretValuesFromEnv, redactSecrets } from '../lib/redact.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { parseSession } from '../lib/session/parse.js';
+import { extractSessionTopic, isSyntheticUserMessage } from '../lib/session/prompt.js';
+import { renderConversationMarkdown } from '../lib/session/render.js';
+import { buildPreview } from './sessions-picker.js';
+import { parseAgentFilter } from './sessions.js';
+import { selectSessions } from './sessions-export.js';
+export const MARKDOWN_RENDER_AGENTS = [
+    'claude',
+    'codex',
+    'gemini',
+    'antigravity',
+    'opencode',
+    'grok',
+    'rush',
+    'hermes',
+    'kimi',
+    'droid',
+    'cursor',
+];
+function parseReasoning(value) {
+    if (value === 'omit' || value === 'fold' || value === 'include')
+        return value;
+    throw new Error(`Unknown reasoning mode "${value}". Expected omit, fold, or include.`);
+}
+function quotePreview(preview) {
+    return preview.split('\n').map((line) => `> ${line}`).join('\n');
+}
+/** Build one shareable Markdown document from the canonical preview and event model. */
+export function renderSessionMarkdownDocument(session, options = {}) {
+    if (!MARKDOWN_RENDER_AGENTS.includes(session.agent)) {
+        throw new Error(`Cannot render ${session.agent} session ${session.shortId || session.id}: Markdown rendering supports ${MARKDOWN_RENDER_AGENTS.join(', ')}.`);
+    }
+    // Preserve normalized tool output here so the Markdown renderer owns the
+    // visible cap and can report exactly how much it omitted.
+    const events = parseSession(session.filePath, session.agent, { maxToolOutputChars: Infinity });
+    if (events.length === 0) {
+        throw new Error(`Cannot render ${session.agent} session ${session.shortId || session.id}: transcript produced no normalized events.`);
+    }
+    const shouldRedact = options.redact !== false;
+    const sanitize = (text) => shouldRedact ? redactSecrets(text, options.knownSecrets) : text;
+    const preview = sanitize(stripVTControlCharacters(buildPreview(session)));
+    const shareEvents = events.filter((event) => !(event.type === 'message' && event._synthetic));
+    const firstPrompt = shareEvents.find((event) => event.type === 'message' && event.role === 'user')?.content;
+    const title = sanitize(session.label || (firstPrompt ? extractSessionTopic(firstPrompt) : undefined) ||
+        (session.topic && !isSyntheticUserMessage(session.topic) ? session.topic : undefined) ||
+        `${session.agent} session ${session.shortId || session.id}`);
+    const conversation = renderConversationMarkdown(shareEvents, {
+        redact: shouldRedact,
+        knownSecrets: options.knownSecrets,
+        reasoning: options.reasoning ?? 'omit',
+        maxToolOutputChars: options.maxToolOutputChars,
+    });
+    return `# ${title}\n\n## Session preview\n\n${quotePreview(preview)}\n\n## Conversation\n\n${conversation}\n`;
+}
+export function registerSessionsRenderCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('render <selectors...>')
+        .description('Render one or more sessions as readable, redacted Markdown for review or sharing.')
+        .option('--format <format>', 'Output format (md or markdown)', 'md')
+        .option('-o, --output <path>', 'Write the rendered document to a file instead of stdout')
+        .option('--reasoning <mode>', 'Reasoning visibility: omit, fold, or include', 'omit');
+    setHelpSections(cmd, {
+        examples: `# Render one redacted session for a confidential gist
+agents sessions render a1b2c3d4 -o session.md
+
+# Combine several sessions into one Markdown document
+agents sessions render a1b2c3d4 d4c3b2a1 -o delivery-sessions.md
+
+# Keep reasoning locally in collapsible sections and opt out of redaction
+agents sessions render a1b2c3d4 --reasoning fold --no-redact`,
+        notes: `Markdown is redacted by default, including credential-shaped values and local home paths.
+The preview at the top is the same preview shown by 'agents sessions'. Tool output is truncated
+with an explicit note. Use --no-redact only for local output that will not be shared.`,
+    });
+    cmd.action(async (selectors, options, command) => {
+        const globals = command.optsWithGlobals();
+        if (!['md', 'markdown'].includes(options.format.toLowerCase())) {
+            throw new Error(`Unknown format "${options.format}". Expected md or markdown.`);
+        }
+        const reasoning = parseReasoning(options.reasoning);
+        const limit = Math.max(1, Number.parseInt(globals.limit || '100', 10) || 100);
+        const agent = parseAgentFilter(globals.agent).agent;
+        const sessions = selectSessions(await discoverSessions({
+            all: globals.all !== false,
+            since: globals.since,
+            limit,
+            agent: agent ?? undefined,
+        }), selectors);
+        if (sessions.length === 0) {
+            process.stderr.write(chalk.yellow('No sessions matched the selection.\n'));
+            process.exitCode = 1;
+            return;
+        }
+        const knownSecrets = globals.redact === false ? undefined : knownSecretValuesFromEnv();
+        const rendered = sessions.map((session) => ({
+            id: session.id,
+            agent: session.agent,
+            markdown: renderSessionMarkdownDocument(session, {
+                redact: globals.redact !== false,
+                reasoning,
+                knownSecrets,
+            }),
+        }));
+        const markdown = rendered.map((item) => item.markdown.trimEnd()).join('\n\n---\n\n') + '\n';
+        if (options.output)
+            fs.writeFileSync(options.output, markdown, { mode: 0o600 });
+        if (globals.json) {
+            process.stdout.write(JSON.stringify({ redacted: globals.redact !== false, reasoning, sessions: rendered }, null, 2) + '\n');
+        }
+        else if (!options.output) {
+            process.stdout.write(markdown);
+        }
+        else {
+            process.stderr.write(chalk.green(`Rendered ${rendered.length} session${rendered.length === 1 ? '' : 's'} to ${options.output}\n`));
+        }
+    });
+}

package/dist/commands/sessions.js

@@ -56,6 +56,7 @@ import { registerDetachCommand } from './detach.js';
 import { registerAttachCommand } from './attach.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 import { registerSessionsExportCommand } from './sessions-export.js';
+import { registerSessionsRenderCommand } from './sessions-render.js';
 import { registerSessionsImportCommand } from './sessions-import.js';
 import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
 import { registerSessionsBackfillCommand } from './sessions-backfill.js';
@@ -3584,7 +3585,7 @@ export function registerSessionsCommands(program) {
         .option('--query <clause>', 'Search text; repeat with --include tools to require distinct matching calls', collectQueryClause, [])
         .option('--resolve <selector>', 'Resolve one full ID, unique prefix, or keyword query to safe session metadata (requires --json; searches the fleet unless --local)')
         .addOption(new Option('--resolve-safe-v1 <selector>').hideHelp())
-        .description('Find, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode.')
+        .description('Find, browse, and read agent conversation transcripts. Live roster: `agents sessions --active` (alias: `agents roster`).')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
         .option('--claude', 'Shorthand for --agent claude')
         .option('--codex', 'Shorthand for --agent codex')
@@ -3735,11 +3736,37 @@ export function registerSessionsCommands(program) {
     registerAttachCommand(sessionsCmd);
     registerSessionsInjectCommand(sessionsCmd);
     registerSessionsExportCommand(sessionsCmd);
+    registerSessionsRenderCommand(sessionsCmd);
     registerSessionsImportCommand(sessionsCmd);
     registerSessionsMigrateCommand(sessionsCmd);
     registerSessionsMigrationsCommand(sessionsCmd);
     registerSessionsBackfillCommand(sessionsCmd);
     registerSessionsStatsCommand(sessionsCmd);
+    // Observe-umbrella alias (Phase 3): roster → sessions --active.
+    registerSessionsObserveAliases(program);
+}
+/**
+ * `roster` → sessions --active. Registered with the sessions module so the
+ * lazy loader for `roster` also registers the real `sessions` command for re-parse.
+ */
+function registerSessionsObserveAliases(program) {
+    program
+        .command('roster')
+        .description('Live agent roster (alias of `agents sessions --active`). Who is running right now.')
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        const { expandObserveAlias } = await import('../lib/observe-aliases.js');
+        const rest = process.argv.slice(3);
+        const expanded = expandObserveAlias('roster', rest);
+        if (!expanded) {
+            console.error(chalk.red('Unknown observe alias: roster'));
+            process.exit(1);
+        }
+        if (process.stderr.isTTY)
+            process.stderr.write(chalk.gray(`${expanded.note}\n`));
+        await program.parseAsync(['node', 'agents', ...expanded.argv]);
+    });
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();

package/dist/commands/ssh.js

@@ -18,6 +18,7 @@ import ora from 'ora';
 import { getCliVersion } from '../lib/version.js';
 import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../lib/secrets/bundles.js';
 import { machineId } from '../lib/session/sync/config.js';
+import { isDeviceAuto, resolveDeviceAffinity } from '../lib/smart-launch.js';
 import { registerFleetCaptureCommand } from './fleet-capture.js';
 import { registerFleetApplyAlias } from './apply.js';
 import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, setAutoLaunchEnabled, setAutoLaunchPreferred, upsertDevice, writeReachability, } from '../lib/devices/registry.js';
@@ -1413,9 +1414,12 @@ Examples:
   agents ssh win-mini                       # interactive login
   agents ssh win-mini hostname              # run a command (PowerShell on Windows)
   agents ssh yosemite-s0 uptime             # run a command (POSIX)
+  agents ssh auto                           # affinity-pick a device (same engine as 'agents run --device auto')
 
 Devices come from 'agents devices'. Password auth pulls the secret from a
 secrets bundle via an askpass shim — the password never touches argv.
+'auto' picks a remote device by 14-day usage; a pick landing on this machine
+is refused with a clear message instead of self-dialing.
 `)
         .action(async (name, cmd) => {
         // Hidden askpass bridge: ssh execs the shim, which re-invokes us here.
@@ -1423,16 +1427,35 @@ secrets bundle via an askpass shim — the password never touches argv.
             await runAskpass();
             return;
         }
+        // `auto` is the same affinity sentinel `agents run --device auto` resolves
+        // (RUSH-2185) — pick the concrete device up front via the SAME engine
+        // (resolveDeviceAffinity), rather than leaning on matchHost's generic
+        // self-resolution (../lib/hosts/registry.js): `agents ssh` connects OUT to
+        // a remote device, so a pick that lands on THIS machine is refused with a
+        // clear message instead of self-SSHing — which also holds when this
+        // machine was never itself enrolled as a device (matchHost would have
+        // nothing to resolve "self" to, and mis-report the pick as "Unknown
+        // device").
+        let target = name;
+        if (isDeviceAuto(name)) {
+            const plan = resolveDeviceAffinity({});
+            if (!plan.host) {
+                console.error(chalk.red(`'auto' picked this machine — 'agents ssh' connects to a remote device. Pass a device name; see 'agents devices list'.`));
+                process.exit(1);
+            }
+            process.stderr.write(chalk.gray(`[agents] device=auto → ${plan.host}\n`));
+            target = plan.host;
+        }
         // Accept the full fleet target grammar: a registered `name`, a
         // `user@device` (same device, login user overridden — dialed via its
         // Tailscale route, not LAN DNS), or an ad-hoc `user@host`/`host` literal.
         // A bare unregistered alias still errors as "Unknown device".
-        const device = await resolveDeviceTarget(name);
+        const device = await resolveDeviceTarget(target);
         if (!device) {
             // Not a registered device — it may be a leased crabbox box slug. ssh into
             // it directly (crabbox@<tailnet|ip>:2222) before giving up.
-            trySshLeasedBox(name, cmd); // exits the process on a match
-            console.error(chalk.red(`Unknown device '${name}'. See 'agents devices list'.`));
+            trySshLeasedBox(target, cmd); // exits the process on a match
+            console.error(chalk.red(`Unknown device '${target}'. See 'agents devices list'.`));
             process.exit(1);
         }
         // Preflight: a device Tailscale last saw offline would otherwise hang

package/dist/commands/teams.js

@@ -17,6 +17,7 @@ import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } f
 import { setHelpSections } from '../lib/help.js';
 import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
 import { resolveHost } from '../lib/hosts/registry.js';
+import { isDeviceAuto, resolveDeviceAffinity } from '../lib/smart-launch.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { ensureHostReady } from '../lib/hosts/ready.js';
 import { remoteShellFor } from '../lib/hosts/remote-cmd.js';
@@ -1330,7 +1331,7 @@ export function registerTeamsCommands(program) {
         // `--device`/`--host` are aliases (addHostOption registers both). For `teams
         // add` the passthrough special-cases them as PLACEMENT, not routing, so the
         // local action reads them here. Reject a conflicting pair.
-        const explicitDevice = (() => {
+        let explicitDevice = (() => {
             const h = opts.host;
             const d = opts.device;
             if (h && d && h !== d) {
@@ -1338,6 +1339,16 @@ export function registerTeamsCommands(program) {
             }
             return h ?? d ?? null;
         })();
+        // `auto` is the same affinity sentinel `agents run --device auto` resolves
+        // (RUSH-2185) — pick the concrete device name up front so the local-machine
+        // check right below (and every dieFriction message further down) sees the
+        // real target instead of the literal string "auto".
+        if (explicitDevice && isDeviceAuto(explicitDevice)) {
+            const plan = resolveDeviceAffinity({});
+            const picked = plan.host ?? machineId();
+            process.stderr.write(chalk.gray(`[teams] device=auto → ${picked === machineId() ? 'local' : picked}\n`));
+            explicitDevice = picked;
+        }
         // Distributed teams: --device <name> PINS this teammate to a machine over
         // SSH. Resolve + validate the placement here so a bad target fails at `add`
         // time, not silently at launch. Persisted (hostName/hostTarget/repoPath) so

package/dist/index.js

@@ -310,6 +310,15 @@ Run and dispatch:
   browser                         Automate a browser — navigate, click, screenshot, console, network
   pty                             Drive interactive terminal programs (REPLs, TUIs) via a persistent PTY session
 
+Observe (read the fleet — no store merge; aliases point at the real readers):
+  feed / inbox                    Needs-you inbox (open blocks waiting on you)
+  timeline                        Agent progress stream (= feed --filter updates)
+  roster                          Live agents (= sessions --active)
+  events                          Unified ops + activity event trail
+  audit                           Tamper-evident run-dispatch log (not events)
+  snapshot                        One-process inventory + active sessions poll
+  status                          Sync/drift only (not the live fleet snapshot)
+
 Credentials and profiles:
   profile                         Activate resource profiles across skills, MCP, permissions, and secrets
   profiles                        Bundles of (host CLI, endpoint, model, auth)
@@ -317,8 +326,6 @@ Credentials and profiles:
 
 Diagnostics:
   doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence; --check for the CI drift gate
-  status                          Unified sync status (drift/missing) — not the live fleet snapshot
-  snapshot                        One-process poll: inventory + active sessions (+ optional feed/sync)
   usage [agent]                   Show rate-limit and quota usage per agent
   perf                            Latency rollups (hooks, commands, runs) from the disposable perf warehouse
 

package/dist/lib/crabbox/cli.d.ts

@@ -114,6 +114,41 @@ export declare function crabboxEnv(opts: CrabboxOptions): NodeJS.ProcessEnv;
 export declare function crabboxList(opts?: CrabboxOptions): CrabboxBox[];
 /** Find one box by slug, or null. */
 export declare function crabboxFind(slug: string, opts?: CrabboxOptions): CrabboxBox | null;
+/**
+ * Whether `crabbox status` reports the box SSH-ready (`ready=true`). A box whose
+ * cloud-init bootstrap failed still LISTS as `running` but never becomes ready —
+ * selecting it burns the full SSH wait before hard-failing. `crabbox status`
+ * flips ready=true only once sshd answers, so warm-pool reuse gates on it
+ * (mirrors scripts/sandbox.sh's `box_ready`).
+ */
+export declare function crabboxStatusReady(slug: string, opts?: CrabboxOptions): boolean;
+export interface PoolMatchOptions {
+    /**
+     * Profile label this run would warm a box with (from the repo's
+     * `.crabbox.yaml`; see config.ts). Both sides normalize an unset profile to
+     * DEFAULT_CRABBOX_PROFILE, so profile-less runs match unlabeled boxes.
+     */
+    profile?: string;
+    /**
+     * Network mode of the run (default 'public'). A tailnet-joined box is never
+     * handed to a public run, nor a public box to a tailnet run — reachability and
+     * exposure differ, so the pool is partitioned by it.
+     */
+    netMode?: 'public' | 'tailscale';
+    /** Injectable clock (unix seconds) for the expiry check. */
+    nowSecs?: number;
+}
+/**
+ * Warm boxes in the profile pool this run could reuse: `running`, same profile
+ * label, same network mode, lease unexpired — most-recently-touched first.
+ *
+ * Readiness is NOT required here (deliberately mirrors sandbox.sh's
+ * `running_slugs_for_profile`, which filters on `status` only): the list `state`
+ * label can lag, so the caller gates each candidate on `crabboxStatusReady`
+ * before committing. A not-ready box is skipped, never stopped — a concurrent
+ * run may be mid-boot on it, and crabbox's idle timeout reaps genuine duds.
+ */
+export declare function poolReusableBoxes(boxes: CrabboxBox[], opts?: PoolMatchOptions): CrabboxBox[];
 export interface WarmupOptions extends CrabboxOptions {
     class?: string;
     profile?: string;

package/dist/lib/crabbox/cli.js

@@ -14,6 +14,7 @@
 import { spawn, spawnSync } from 'child_process';
 import { readAndResolveBundleEnv, listBundles, bundleExists } from '../secrets/bundles.js';
 import { readMeta, writeMeta } from '../state.js';
+import { DEFAULT_CRABBOX_PROFILE } from './config.js';
 /** Locate the crabbox binary, or throw an actionable error. */
 export function findCrabbox() {
     const r = spawnSync('crabbox', ['--help'], { encoding: 'utf-8' });
@@ -301,6 +302,51 @@ export function crabboxList(opts = {}) {
 export function crabboxFind(slug, opts = {}) {
     return crabboxList(opts).find((b) => b.slug === slug) ?? null;
 }
+/**
+ * Whether `crabbox status` reports the box SSH-ready (`ready=true`). A box whose
+ * cloud-init bootstrap failed still LISTS as `running` but never becomes ready —
+ * selecting it burns the full SSH wait before hard-failing. `crabbox status`
+ * flips ready=true only once sshd answers, so warm-pool reuse gates on it
+ * (mirrors scripts/sandbox.sh's `box_ready`).
+ */
+export function crabboxStatusReady(slug, opts = {}) {
+    findCrabbox();
+    const r = spawnSync('crabbox', ['status', '--id', slug], {
+        encoding: 'utf-8',
+        env: crabboxEnv(opts),
+        timeout: opts.timeoutMs ?? 15000,
+    });
+    if (r.status !== 0 || !r.stdout)
+        return false;
+    return /(^|\s)ready=true(\s|$)/m.test(r.stdout);
+}
+/**
+ * Warm boxes in the profile pool this run could reuse: `running`, same profile
+ * label, same network mode, lease unexpired — most-recently-touched first.
+ *
+ * Readiness is NOT required here (deliberately mirrors sandbox.sh's
+ * `running_slugs_for_profile`, which filters on `status` only): the list `state`
+ * label can lag, so the caller gates each candidate on `crabboxStatusReady`
+ * before committing. A not-ready box is skipped, never stopped — a concurrent
+ * run may be mid-boot on it, and crabbox's idle timeout reaps genuine duds.
+ */
+export function poolReusableBoxes(boxes, opts = {}) {
+    const profile = opts.profile ?? DEFAULT_CRABBOX_PROFILE;
+    const netMode = opts.netMode ?? 'public';
+    const nowSecs = opts.nowSecs ?? Math.floor(Date.now() / 1000);
+    return boxes
+        .filter((b) => {
+        if (b.status !== 'running')
+            return false;
+        if ((b.profile ?? DEFAULT_CRABBOX_PROFILE) !== profile)
+            return false;
+        const boxNet = b.tailscaleIPv4 || b.tailscaleFQDN ? 'tailscale' : 'public';
+        if (boxNet !== netMode)
+            return false;
+        return b.expiresAt === null || b.expiresAt > nowSecs;
+    })
+        .sort((a, b) => (b.lastTouchedAt ?? 0) - (a.lastTouchedAt ?? 0));
+}
 /**
  * Lease a box and block until it is ready. Returns the leased box.
  *

package/dist/lib/crabbox/config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The repo-local crabbox config (`.crabbox.yaml` at the repo root).
+ *
+ * crabbox itself reads this file when warming a box (the `profile:` key becomes
+ * the box's `profile` label). `agents run --lease` reads it too so the warm-pool
+ * reuse check matches on the SAME profile the warmup would have used — a reused
+ * box is then interchangeable with a fresh one (scripts/sandbox.sh's
+ * `pick_ready_box` resolves the pool the same way).
+ */
+/**
+ * The profile label a box warm pool shares. Matches sandbox.sh's
+ * `PROFILE="${PROFILE:-default}"`: a run with no configured profile and a box
+ * with no `profile` label both normalize here, so they still match each other.
+ */
+export declare const DEFAULT_CRABBOX_PROFILE = "default";
+/**
+ * The `profile:` declared by `<repoRoot>/.crabbox.yaml`, or undefined when the
+ * file is missing, unreadable, or has no profile key (crabbox then applies its
+ * own default, which the pool matcher treats as DEFAULT_CRABBOX_PROFILE).
+ */
+export declare function readCrabboxRepoProfile(repoRoot: string): string | undefined;

package/dist/lib/crabbox/config.js

@@ -0,0 +1,43 @@
+/**
+ * The repo-local crabbox config (`.crabbox.yaml` at the repo root).
+ *
+ * crabbox itself reads this file when warming a box (the `profile:` key becomes
+ * the box's `profile` label). `agents run --lease` reads it too so the warm-pool
+ * reuse check matches on the SAME profile the warmup would have used — a reused
+ * box is then interchangeable with a fresh one (scripts/sandbox.sh's
+ * `pick_ready_box` resolves the pool the same way).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+/**
+ * The profile label a box warm pool shares. Matches sandbox.sh's
+ * `PROFILE="${PROFILE:-default}"`: a run with no configured profile and a box
+ * with no `profile` label both normalize here, so they still match each other.
+ */
+export const DEFAULT_CRABBOX_PROFILE = 'default';
+/**
+ * The `profile:` declared by `<repoRoot>/.crabbox.yaml`, or undefined when the
+ * file is missing, unreadable, or has no profile key (crabbox then applies its
+ * own default, which the pool matcher treats as DEFAULT_CRABBOX_PROFILE).
+ */
+export function readCrabboxRepoProfile(repoRoot) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(repoRoot, '.crabbox.yaml'), 'utf-8');
+    }
+    catch {
+        return undefined; // no repo crabbox config — crabbox's own default applies
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    const profile = parsed.profile;
+    return typeof profile === 'string' && profile.length > 0 ? profile : undefined;
+}

package/dist/lib/crabbox/lease.d.ts

@@ -1,10 +1,12 @@
 /**
  * `agents run --lease` orchestrator.
  *
- * Lease an ephemeral crabbox → provision the picked runtime(s) + their
- * credentials → run the agent on the box (via `crabbox run`, which owns the
- * SSH) → tear the box down. The whole box-side sequence rides a single
- * `--script-stdin` body so the token contents never touch argv.
+ * Acquire a box → provision the picked runtime(s) + their credentials → run the
+ * agent on the box (via `crabbox run`, which owns the SSH) → tear the box down.
+ * Acquisition is reuse-first against the warm profile pool (a ready box carrying
+ * the run's profile + netMode labels is reused and kept; `--fresh` opts out and
+ * always leases a new, torn-down box). The whole box-side sequence rides a
+ * single `--script-stdin` body so the token contents never touch argv.
  *
  * ── Command-layer contract (RUSH-1920/1921/1924) ─────────────────────────────
  * Exports the commands layer (exec.ts / lease.ts / ssh.ts) consumes:
@@ -12,7 +14,9 @@
  *     --bare) gates the `copy-setup` progress sentinel; `opts.netMode`
  *     ('public' | 'tailscale', default 'public') adds the `joined-tailnet` step.
  *   • `LeaseRunOptions.copySetup` / `LeaseRunOptions.netMode` — forwarded by
- *     `leaseAndRun` (netMode → `crabboxWarmup`).
+ *     `leaseAndRun` (netMode → `crabboxWarmup`). `LeaseRunOptions.fresh`
+ *     (`--fresh`) skips the warm profile-pool reuse check and always leases a
+ *     new box, torn down after the run.
  *   • `crabboxWarmup(opts.netMode)` — 'tailscale' leases onto the tailnet
  *     (`--network tailscale -tailscale-tags tag:crabbox`); auth key rides the
  *     child env as `CRABBOX_TAILSCALE_AUTH_KEY` (crabboxEnv, cli.ts).
@@ -80,6 +84,12 @@ export interface LeaseRunOptions {
     keep?: boolean;
     /** Existing warm crabbox slug to reuse instead of provisioning a new lease. */
     reuseBox?: string;
+    /**
+     * Force a brand-new box: skip the warm profile-pool reuse check and tear the
+     * box down after the run (the pre-pool `--lease` behavior). `--fresh` at the
+     * command layer.
+     */
+    fresh?: boolean;
     /**
      * Raw wrapped Claude OAuth payload (from `resolveClaudeCredentialsBlob`), written
      * to `~/.claude/.credentials.json` on the box. The command layer resolves it

package/dist/lib/crabbox/lease.js

@@ -1,10 +1,12 @@
 /**
  * `agents run --lease` orchestrator.
  *
- * Lease an ephemeral crabbox → provision the picked runtime(s) + their
- * credentials → run the agent on the box (via `crabbox run`, which owns the
- * SSH) → tear the box down. The whole box-side sequence rides a single
- * `--script-stdin` body so the token contents never touch argv.
+ * Acquire a box → provision the picked runtime(s) + their credentials → run the
+ * agent on the box (via `crabbox run`, which owns the SSH) → tear the box down.
+ * Acquisition is reuse-first against the warm profile pool (a ready box carrying
+ * the run's profile + netMode labels is reused and kept; `--fresh` opts out and
+ * always leases a new, torn-down box). The whole box-side sequence rides a
+ * single `--script-stdin` body so the token contents never touch argv.
  *
  * ── Command-layer contract (RUSH-1920/1921/1924) ─────────────────────────────
  * Exports the commands layer (exec.ts / lease.ts / ssh.ts) consumes:
@@ -12,7 +14,9 @@
  *     --bare) gates the `copy-setup` progress sentinel; `opts.netMode`
  *     ('public' | 'tailscale', default 'public') adds the `joined-tailnet` step.
  *   • `LeaseRunOptions.copySetup` / `LeaseRunOptions.netMode` — forwarded by
- *     `leaseAndRun` (netMode → `crabboxWarmup`).
+ *     `leaseAndRun` (netMode → `crabboxWarmup`). `LeaseRunOptions.fresh`
+ *     (`--fresh`) skips the warm profile-pool reuse check and always leases a
+ *     new box, torn down after the run.
  *   • `crabboxWarmup(opts.netMode)` — 'tailscale' leases onto the tailnet
  *     (`--network tailscale -tailscale-tags tag:crabbox`); auth key rides the
  *     child env as `CRABBOX_TAILSCALE_AUTH_KEY` (crabboxEnv, cli.ts).
@@ -24,7 +28,7 @@
  *     secretsBundle?, userAgentsDir?, onData? }): Promise<CopySetupResult>` — the
  *     push-from-local the command layer runs before the box run.
  */
-import { crabboxFind, crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop } from './cli.js';
+import { crabboxFind, crabboxList, crabboxStatusReady, crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop, poolReusableBoxes } from './cli.js';
 import * as yaml from 'yaml';
 import { buildCredentialScript, buildHomeFileWriteScript, CLAUDE_TOKEN_REMOTE } from './runtimes.js';
 import { LEASE_AGENT_MARKER, leasePhaseSentinel } from './progress.js';
@@ -149,9 +153,32 @@ export function buildBootstrapScript(opts) {
         .filter((l) => l.length > 0)
         .join('\n');
 }
+/**
+ * The first warm box in this run's profile pool that is actually SSH-ready, or
+ * null. Mirrors scripts/sandbox.sh's `pick_ready_box`: list the running boxes
+ * for the run's profile + netMode, then gate each on `crabbox status`
+ * ready=true — a box whose bootstrap failed still lists as `running` and would
+ * burn the whole SSH wait before hard-failing. A skipped box is left alone
+ * (never stopped): a concurrent run may be mid-boot on it, and crabbox's idle
+ * timeout reaps genuine duds.
+ */
+function pickReadyPoolBox(opts) {
+    const candidates = poolReusableBoxes(crabboxList({ secretsBundle: opts.secretsBundle }), {
+        profile: opts.profile,
+        netMode: opts.netMode,
+    });
+    for (const b of candidates) {
+        if (crabboxStatusReady(b.slug, { secretsBundle: opts.secretsBundle }))
+            return b;
+    }
+    return null;
+}
 export async function leaseAndRun(opts) {
     const startedAt = Date.now();
     let box;
+    // A box this run did NOT provision — either the caller named it (`--box`) or
+    // it came out of the warm profile pool. Reused boxes are never torn down.
+    let reused = false;
     if (opts.reuseBox) {
         opts.onPhase?.({ kind: 'reuse', slug: opts.reuseBox });
         const found = crabboxFind(opts.reuseBox, { secretsBundle: opts.secretsBundle });
@@ -160,17 +187,29 @@ export async function leaseAndRun(opts) {
         box = found.ready
             ? found
             : await crabboxWaitReady(opts.reuseBox, { secretsBundle: opts.secretsBundle });
+        reused = true;
     }
     else {
-        opts.onPhase?.({ kind: 'warmup', backend: opts.backend });
-        box = await crabboxWarmup({
-            class: opts.boxClass,
-            profile: opts.profile,
-            provider: opts.backend,
-            secretsBundle: opts.secretsBundle,
-            netMode: opts.netMode,
-        });
-        await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+        // Reuse-first: before paying for a fresh lease, look for a warm box in this
+        // run's profile pool (same profile label the warmup would use, same netMode).
+        // `--fresh` opts out and always provisions.
+        const pooled = opts.fresh ? null : pickReadyPoolBox(opts);
+        if (pooled) {
+            opts.onPhase?.({ kind: 'reuse', slug: pooled.slug });
+            box = pooled;
+            reused = true;
+        }
+        else {
+            opts.onPhase?.({ kind: 'warmup', backend: opts.backend });
+            box = await crabboxWarmup({
+                class: opts.boxClass,
+                profile: opts.profile,
+                provider: opts.backend,
+                secretsBundle: opts.secretsBundle,
+                netMode: opts.netMode,
+            });
+            await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+        }
     }
     opts.onPhase?.({ kind: 'ready', box, elapsedMs: Date.now() - startedAt });
     // Setup-copy (F1, RUSH-1920): push the git-tracked ~/.agents config onto the
@@ -203,8 +242,9 @@ export async function leaseAndRun(opts) {
     }
     finally {
         // Always attempt teardown (bounds credential lifetime to the run) unless the
-        // caller explicitly asked to keep the box or targeted an existing warm box.
-        if (!opts.keep && !opts.reuseBox) {
+        // caller explicitly asked to keep the box or the box was reused (an explicit
+        // --box target or a warm pool box — both outlive this run).
+        if (!opts.keep && !reused) {
             opts.onPhase?.({ kind: 'teardown' });
             toreDown = crabboxStop(box.slug, { secretsBundle: opts.secretsBundle });
         }