@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/crabbox/lease.js

@@ -1,60 +1,18 @@
-/**
- * `agents run --lease` orchestrator.
- *
- * 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 shared warm pool (a ready box carrying
- * the lease profile + netMode labels is reused and kept; `--fresh` opts out and
- * always leases a new, torn-down box). Concurrent callers run from separate
- * `~/workspaces/<repo>-<run>` directories on that box. The whole box-side
- * sequence rides a single `--script-stdin` body so token contents never touch argv.
- *
- * ── Command-layer contract (RUSH-1920/1921/1924) ─────────────────────────────
- * Exports the commands layer (exec.ts / lease.ts / ssh.ts) consumes:
- *   • `buildBootstrapScript(opts)` — `opts.copySetup` (default TRUE; clear for
- *     --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`). `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).
- *   • `CrabboxBox.tailscaleIPv4` / `CrabboxBox.tailscaleFQDN` — populated from
- *     the box labels by `normalizeBox` (cli.ts).
- *   • Step stream (progress.ts): `type LeaseStep`, the `onStep` router option,
- *     and the self-contained `renderStepLine(step)` helper (the lib never prints).
- *   • Setup-copy (setup-copy.ts): `copySetupToBox({ host, user?, port?,
- *     secretsBundle?, userAgentsDir?, onData? }): Promise<CopySetupResult>` — the
- *     push-from-local the command layer runs before the box run.
- */
 import { crabboxFind, crabboxList, crabboxStatusReady, crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop, poolReusableBoxes } from './cli.js';
 import * as yaml from 'yaml';
 import { assertNoNativeOAuthTransfer, buildCredentialScript, buildHomeFileWriteScript, CLAUDE_TOKEN_REMOTE } from './runtimes.js';
 import { LEASE_AGENT_MARKER, leasePhaseSentinel } from './progress.js';
 import { copySetupToBox } from './setup-copy.js';
 import { DEFAULT_CRABBOX_PROFILE } from './config.js';
-/**
- * Exit code the box-side bootstrap raises when `agents setup` did not leave a
- * usable install (`~/.agents/.system` is still not a git repo). The run-side gate
- * (`ensureInitialized`, commands/setup.ts) refuses `agents run` with "agents-cli
- * is not set up" in exactly that state, so the bootstrap aborts with this code
- * instead of running the agent into that refusal. `leaseAndRun` reads it to stop
- * a box THIS run provisioned — a newly created box that can't run is pure cost.
- */
 export const LEASE_BOOTSTRAP_FAILED_CODE = 97;
-/** POSIX single-quote for safe embedding in the generated bootstrap script. */
 function q(s) {
     return "'" + s.replace(/'/g, "'\\''") + "'";
 }
-/** Build a shell-safe, collision-resistant workspace id for one lease run. */
 export function leaseWorkspaceId(repoRoot, startedAtMs = Date.now(), pid = process.pid) {
     const repo = repoRoot.split(/[\\/]/).filter(Boolean).pop() ?? 'repo';
     const safeRepo = repo.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'repo';
     return `${safeRepo}-${startedAtMs.toString(36)}-${pid.toString(36)}`;
 }
-/** Isolated box-home path for one run, relative to the shared box user's home. */
 function leaseHomeDir(workspaceId) {
     return `lease-homes/${workspaceId}`;
 }
@@ -82,16 +40,6 @@ function runtimeInstallSpec(id, dispatchProfile) {
     }
     return id;
 }
-/**
- * Bash snippet that guarantees `agents` is runnable AND set up on the box. Fresh
- * crabbox images ship without node, and the box user may not own the global npm
- * prefix, so everything installs user-level under ~/.local (node from the official
- * latest-v22.x tarball to satisfy engines.node >=22.5.0). Exits 96 with a
- * diagnostic when the CLI still isn't runnable, and {@link LEASE_BOOTSTRAP_FAILED_CODE}
- * when `agents setup` did not leave a git-repo `~/.agents/.system` — both used to
- * surface only as a downstream failure (`agents: command not found`, or the run-side
- * "agents-cli is not set up" gate) after a swallowed `|| true`.
- */
 const ENSURE_AGENTS_CLI = [
     'export PATH="$HOME/.local/bin:$PATH"',
     'if ! command -v node >/dev/null 2>&1; then',
@@ -108,14 +56,6 @@ const ENSURE_AGENTS_CLI = [
     '  echo "lease bootstrap: agents-cli install failed (node: $(command -v node || echo missing))" >&2',
     '  exit 96',
     'fi',
-    // The run-side gate (`ensureInitialized`, commands/setup.ts) refuses `agents run`
-    // with "agents-cli is not set up" until `~/.agents/.system` is a GIT REPO. Gate
-    // setup on that same postcondition — not a swallowed exit: capture setup's output,
-    // and if the repo still isn't there afterward, print the real cause and abort so
-    // the box is never run into that refusal (a swallowed `|| true` here is what left
-    // a provisioned box dying at "agents-cli is not set up"). `-e` (not `-d`) matches
-    // the gate's `isGitRepo` (git.ts), which is `existsSync('.git')` — true for a
-    // gitfile/gitlink too, so a linked-worktree `.system` never false-aborts here.
     'if [ ! -e "$HOME/.agents/.system/.git" ]; then',
     '  setup_out=$(agents setup 2>&1)',
     '  if [ ! -e "$HOME/.agents/.system/.git" ]; then',
@@ -125,11 +65,6 @@ const ENSURE_AGENTS_CLI = [
     '  fi',
     'fi',
 ].join('\n');
-/**
- * Build the single bootstrap script run on the box: ensure agents-cli, install
- * the picked runtime CLIs, write their credentials, run the agent, then shred
- * the credential files. Best-effort install steps never abort the run.
- */
 export function buildBootstrapScript(opts) {
     const credentialRuntimes = opts.credentialRuntimes ?? opts.runtimes;
     const credScript = buildCredentialScript(credentialRuntimes, opts.detected, {
@@ -141,9 +76,6 @@ export function buildBootstrapScript(opts) {
         runParts.push('--mode', q(opts.mode));
     if (opts.model)
         runParts.push('--model', q(opts.model));
-    // Credential files to shred after the run (home-level paths written above).
-    // Runs regardless of --keep-box (it's in the box body, not teardown), so a kept
-    // box still loses the token after the run — minimizing the credential window.
     const shredPaths = credentialRuntimes.flatMap((id) => {
         const paths = { claude: ['.claude.json', CLAUDE_TOKEN_REMOTE], codex: ['.codex/auth.json'], grok: ['.grok/auth.json'] }[id];
         return paths ?? [];
@@ -154,11 +86,8 @@ export function buildBootstrapScript(opts) {
     const installRuntimes = opts.runtimes
         .map((id) => `agents add ${q(runtimeInstallSpec(id, opts.dispatchProfile))} >/dev/null 2>&1 || true`)
         .join('\n');
-    // `echo`-ed phase sentinels (progress.ts) let the command layer drive a
-    // step-by-step UI. `createLeaseOutputRouter` swallows these lines and surfaces
-    // them as a structured step stream — they never appear as setup noise.
     const step = (name) => `echo ${q(leasePhaseSentinel(name))}`;
-    const copySetup = opts.copySetup !== false; // default TRUE
+    const copySetup = opts.copySetup !== false;
     const workspace = opts.workspaceId
         ? [
             'BOX_HOME="$HOME"',
@@ -179,11 +108,8 @@ export function buildBootstrapScript(opts) {
         : '';
     return [
         'set -uo pipefail',
-        // crabbox has finished its workspace resync by the time this script runs;
-        // the sync sentinel marks the transition out of that (crabbox-driven) phase.
         step('sync'),
         workspace,
-        // Only meaningful on a tailnet lease — the box already joined during warmup.
         opts.netMode === 'tailscale' ? step('joined-tailnet') : '',
         step('install'),
         ENSURE_AGENTS_CLI,
@@ -193,13 +119,7 @@ export function buildBootstrapScript(opts) {
         step('creds'),
         credScript,
         profileScript,
-        // copy-setup: the host already rsync'd the git-tracked ~/.agents onto the box
-        // (leaseAndRun, before this script). Here — after ENSURE_AGENTS_CLI installed
-        // the CLI — we materialize that config into the runtime home. Gated by
-        // copySetup (cleared for --bare). Best-effort; a refresh failure never aborts.
         copySetup ? [step('copy-setup'), 'agents sync --local -y >/dev/null 2>&1 || true'].join('\n') : '',
-        // Marker on its own line: the command layer shows everything before this as
-        // setup progress and everything after (the agent's output) verbatim.
         `echo ${q(LEASE_AGENT_MARKER)}`,
         `${runParts.join(' ')}`,
         'rc=$?',
@@ -209,15 +129,6 @@ 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,
@@ -229,18 +140,7 @@ function pickReadyPoolBox(opts) {
     }
     return null;
 }
-/** Untouched-for-this-long ⇒ no active run holds the box, so an expired one is a stray. */
 export const STRAY_GRACE_SECS = 600;
-/**
- * Whether `box` is an EXPIRED, idle stray in this run's pool — the boxes that
- * accumulate cost. An expired box can never be reused (`poolReusableBoxes` gates
- * on an unexpired lease), yet `keep:true` leaves it running, so without a sweep a
- * fresh provision leaves the old one billing until `gc`'s 1h-idle window. Only a
- * box that is running, in the SAME profile+netMode pool, has an EXPIRED lease, and
- * has been untouched for the grace window is a stray — a mid-boot or in-use box
- * (recent `lastTouchedAt`, or an unexpired lease) is never one. Pure — testable
- * without a shell.
- */
 export function isExpiredPoolStray(box, opts) {
     const profile = opts.profile ?? DEFAULT_CRABBOX_PROFILE;
     const netMode = opts.netMode ?? 'public';
@@ -256,18 +156,13 @@ export function isExpiredPoolStray(box, opts) {
     if (boxNet !== netMode)
         return false;
     if (box.expiresAt === null || box.expiresAt > nowSecs)
-        return false; // unexpired ⇒ reusable
+        return false;
     if (box.lastTouchedAt === null)
-        return false; // unknown age is never reap-safe
+        return false;
     if (nowSecs - box.lastTouchedAt < graceSecs)
-        return false; // maybe active
+        return false;
     return true;
 }
-/**
- * Opportunistically stop expired, idle strays in this run's pool — rides the
- * lease (no scheduler), best-effort (never throws, never blocks the run). Returns
- * how many were stopped.
- */
 function reapExpiredPoolStrays(opts, keepSlug) {
     let boxes;
     try {
@@ -286,18 +181,11 @@ function reapExpiredPoolStrays(opts, keepSlug) {
     return reaped;
 }
 export async function leaseAndRun(opts) {
-    // SING-1b, FAIL FAST: `buildBootstrapScript` below refuses to copy a native OAuth
-    // login (via `buildCredentialScript`), but that runs only AFTER a box has been
-    // leased — and a `--fresh` box would leak because the throw escapes the teardown
-    // `finally`. Refuse HERE, before any box is provisioned or paid for, mirroring how
-    // `--copy-creds` refuses before it opens an SSH connection.
     assertNoNativeOAuthTransfer(opts.credentialRuntimes ?? opts.runtimes, opts.detected, {
         claudeCredentialsJson: opts.claudeCredentialsJson,
     });
     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 });
@@ -310,9 +198,6 @@ export async function leaseAndRun(opts) {
         reused = true;
     }
     else {
-        // 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 });
@@ -332,19 +217,9 @@ export async function leaseAndRun(opts) {
         }
     }
     opts.onPhase?.({ kind: 'ready', box, elapsedMs: Date.now() - startedAt });
-    // Reap expired, idle strays in this pool now that we hold our box. An expired
-    // box can never be reused, so these are pure cost the 1h-idle `gc` window
-    // leaves running. Skip when the caller named an explicit `--box` (they're
-    // driving box lifecycle by hand). Best-effort — never blocks or aborts the run.
     if (!opts.reuseBox) {
         reapExpiredPoolStrays(opts, box.slug);
     }
-    // Setup-copy (F1, RUSH-1920): push the git-tracked ~/.agents config onto the
-    // box from the host, over crabbox's own per-lease ssh (a raw ssh fails
-    // publickey). rsync only here — the box has no agents-cli yet, so the matching
-    // `agents sync --local` runs inside the bootstrap script, after the install
-    // step. Best-effort: a copy failure never aborts the run (the agent just runs
-    // without the config).
     if (opts.copySetup !== false) {
         try {
             await copySetupToBox({
@@ -356,21 +231,12 @@ export async function leaseAndRun(opts) {
             });
         }
         catch (err) {
-            // Best-effort — a config-copy failure never blocks the run (the agent runs
-            // without the pushed ~/.agents config), but surface it instead of swallowing
-            // it silently so a broken sync is visible rather than a mystery.
             opts.onData?.(`lease: setup copy failed — running without pushed ~/.agents config (${err.message})\n`);
         }
     }
     const script = buildBootstrapScript(opts);
     let exitCode = null;
     let toreDown = false;
-    // Track whether the box-side script reached the agent — the bootstrap echoes
-    // LEASE_AGENT_MARKER on its own line immediately before `agents run`, and aborts
-    // (LEASE_BOOTSTRAP_FAILED_CODE) strictly BEFORE that. So "marker never seen" is
-    // how we tell a pre-agent bootstrap abort from an agent that merely happened to
-    // exit with the same numeric code — only the former is an unusable box. A short
-    // rolling tail keeps the check robust if the marker straddles two output chunks.
     let sawAgentMarker = false;
     let markerTail = '';
     const trackedOnData = (chunk) => {
@@ -378,7 +244,6 @@ export async function leaseAndRun(opts) {
             const combined = markerTail + chunk;
             if (combined.includes(LEASE_AGENT_MARKER))
                 sawAgentMarker = true;
-            // Keep only enough tail to catch a marker straddling the NEXT chunk boundary.
             else
                 markerTail = combined.slice(-(LEASE_AGENT_MARKER.length + 8));
         }
@@ -395,16 +260,7 @@ export async function leaseAndRun(opts) {
         });
     }
     finally {
-        // A box this run PROVISIONED (never a reused one) whose BOOTSTRAP failed is
-        // unusable capacity — keep it and it bills until the idle GC window. Stop it
-        // regardless of --keep-box: the user asked to keep a working box, not a broken
-        // one. A reused box is left alone (a concurrent run may share it). The
-        // failed-code check is gated on the agent never having started (marker unseen),
-        // so an agent that legitimately exits with the same code keeps its --keep-box box.
         const bootstrapFailed = exitCode === LEASE_BOOTSTRAP_FAILED_CODE && !sawAgentMarker;
-        // Normal --lease establishes or reuses the warm pool, so a healthy box outlives
-        // this run; credentials are still shredded inside the script above. Only --fresh
-        // requests the old one-shot lifecycle and tears its new box down.
         const teardownHealthy = !opts.keep && opts.fresh && !reused;
         const teardownBroken = bootstrapFailed && !reused;
         if (teardownHealthy || teardownBroken) {

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

@@ -1,58 +1,18 @@
-/**
- * Progress routing for `agents run --lease`.
- *
- * The box-side bootstrap emits `LEASE_AGENT_MARKER` on its own line right before
- * `agents run`. Everything the crabbox run streams BEFORE that marker is setup
- * noise (sync bytes, node/agents install, `agents setup`) — shown as spinner
- * text and captured for a failure dump. Everything AFTER is the agent's own
- * output — printed through verbatim. The marker line itself is swallowed.
- */
-/** Sentinel echoed on the box right before `agents run`. Distinctive + collision-proof. */
 export declare const LEASE_AGENT_MARKER = "___AGENTS_LEASE_AGENT_OUTPUT_b1f4c2___";
-/**
- * A structured setup step, parsed from a `___PHASE_<name>___` sentinel line the
- * bootstrap script echoes before each block (sync/install/runtime/creds/…). The
- * command layer renders these to drive a step-by-step progress UI; the lib never
- * prints (see `renderStepLine`).
- */
 export type LeaseStep = {
     name: string;
     detail?: string;
     elapsedMs?: number;
 };
-/**
- * The sentinel line the bootstrap script echoes to announce phase `name`.
- * Kept distinct from `LEASE_AGENT_MARKER` (which does NOT start with `___PHASE_`).
- */
 export declare function leasePhaseSentinel(name: string): string;
-/**
- * Render one lease step as a single human line the command layer can print
- * (e.g. behind a spinner). Self-contained: the lib never writes to a stream.
- */
 export declare function renderStepLine(step: LeaseStep): string;
 export interface Spinner {
-    /** Begin animating a phase (renders `frame text` on one line, TTY only). */
     start(text: string): void;
-    /** Change the text shown; rendered on the next throttled tick (no write itself). */
     update(text: string): void;
-    /** Finalize the current line with a symbol (e.g. ✔) and a newline. */
     stopAndPersist(symbol: string, text: string): void;
-    /** Clear the current animated line without persisting anything. */
     stop(): void;
-    /** True while a phase is active. */
     readonly active: boolean;
 }
-/**
- * A deliberately minimal, self-throttled spinner. Unlike `ora`, it does NOT hook
- * the stream's `write` to re-render on external output — it writes exactly one
- * short line per fixed tick and nowhere else, so it is structurally incapable of
- * a re-render feedback loop (the failure mode that made `ora` blow up when a
- * lease streamed output past a live spinner). On a non-TTY it prints each phase
- * label once and stays silent on `update`, so piped/CI output never floods.
- *
- * Only ever run ONE phase at a time, and never stream other output to the same
- * stream while a phase is active — stop it first.
- */
 export declare function createSpinner(opts?: {
     stream?: {
         write(s: string): unknown;
@@ -62,28 +22,12 @@ export declare function createSpinner(opts?: {
     intervalMs?: number;
 }): Spinner;
 interface LeaseOutputRouter {
-    /** Feed a raw chunk of the crabbox run's combined stdout/stderr. */
     push(chunk: string): void;
-    /** Flush any buffered partial line (call once the stream closes). */
     end(): void;
-    /** True once the agent-output marker has been seen. */
     sawAgent(): boolean;
-    /** The setup lines seen so far (for a failure dump). */
     setupLines(): string[];
-    /** The structured steps parsed from phase sentinels so far. */
     steps(): LeaseStep[];
 }
-/**
- * Split the crabbox run stream at `LEASE_AGENT_MARKER`. `onSetupLine` fires for
- * each complete non-empty line before the marker; `onAgentChunk` fires with raw
- * text after it (streamed promptly, not line-buffered, so agent output is live).
- *
- * Setup lines matching a `___PHASE_<name>___` sentinel are swallowed (never shown
- * as setup noise) and surfaced through `onStep` instead — a structured step
- * stream the command layer can render via `renderStepLine`. When `now` is
- * provided, each step carries `elapsedMs` since the previous step (or router
- * start for the first); omit `now` for deterministic, timing-free output.
- */
 export declare function createLeaseOutputRouter(cb: {
     onSetupLine: (line: string) => void;
     onAgentChunk: (chunk: string) => void;

package/dist/lib/crabbox/progress.js

@@ -1,35 +1,17 @@
-/**
- * Progress routing for `agents run --lease`.
- *
- * The box-side bootstrap emits `LEASE_AGENT_MARKER` on its own line right before
- * `agents run`. Everything the crabbox run streams BEFORE that marker is setup
- * noise (sync bytes, node/agents install, `agents setup`) — shown as spinner
- * text and captured for a failure dump. Everything AFTER is the agent's own
- * output — printed through verbatim. The marker line itself is swallowed.
- */
-/** Sentinel echoed on the box right before `agents run`. Distinctive + collision-proof. */
 export const LEASE_AGENT_MARKER = '___AGENTS_LEASE_AGENT_OUTPUT_b1f4c2___';
 const PHASE_PREFIX = '___PHASE_';
 const PHASE_SUFFIX = '___';
-/**
- * The sentinel line the bootstrap script echoes to announce phase `name`.
- * Kept distinct from `LEASE_AGENT_MARKER` (which does NOT start with `___PHASE_`).
- */
 export function leasePhaseSentinel(name) {
     return `${PHASE_PREFIX}${name}${PHASE_SUFFIX}`;
 }
-/** Parse a phase name out of a sentinel line, or null when the line is not one. */
 function parsePhaseSentinel(line) {
     const t = line.trim();
     if (!t.startsWith(PHASE_PREFIX) || !t.endsWith(PHASE_SUFFIX) || t.length <= PHASE_PREFIX.length + PHASE_SUFFIX.length) {
         return null;
     }
     const name = t.slice(PHASE_PREFIX.length, t.length - PHASE_SUFFIX.length);
-    // Phase names are lowercase kebab tokens; this also rejects the agent marker's
-    // underscore-laden tail if it ever changed to share the ___PHASE_ prefix.
     return /^[a-z0-9-]+$/.test(name) ? name : null;
 }
-/** Human labels for the known bootstrap phases. Falls back to the raw name. */
 const STEP_LABELS = {
     sync: 'Syncing workspace',
     install: 'Installing agents-cli',
@@ -38,7 +20,6 @@ const STEP_LABELS = {
     'copy-setup': 'Copying your setup',
     'joined-tailnet': 'Joined tailnet',
 };
-/** Human-readable elapsed: "0.8s", "3.4s", "1m 5s". */
 function formatElapsed(ms) {
     if (ms < 10_000)
         return `${(ms / 1000).toFixed(1)}s`;
@@ -47,10 +28,6 @@ function formatElapsed(ms) {
         return `${secs}s`;
     return `${Math.floor(secs / 60)}m ${secs % 60}s`;
 }
-/**
- * Render one lease step as a single human line the command layer can print
- * (e.g. behind a spinner). Self-contained: the lib never writes to a stream.
- */
 export function renderStepLine(step) {
     const label = STEP_LABELS[step.name] ?? step.name;
     const detail = step.detail ? ` — ${step.detail}` : '';
@@ -58,17 +35,6 @@ export function renderStepLine(step) {
     return `${label}${detail}${elapsed}`;
 }
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-/**
- * A deliberately minimal, self-throttled spinner. Unlike `ora`, it does NOT hook
- * the stream's `write` to re-render on external output — it writes exactly one
- * short line per fixed tick and nowhere else, so it is structurally incapable of
- * a re-render feedback loop (the failure mode that made `ora` blow up when a
- * lease streamed output past a live spinner). On a non-TTY it prints each phase
- * label once and stays silent on `update`, so piped/CI output never floods.
- *
- * Only ever run ONE phase at a time, and never stream other output to the same
- * stream while a phase is active — stop it first.
- */
 export function createSpinner(opts = {}) {
     const stream = opts.stream ?? process.stderr;
     const enabled = opts.enabled ?? !!stream.isTTY;
@@ -97,7 +63,7 @@ export function createSpinner(opts = {}) {
             }, intervalMs);
         },
         update(t) {
-            text = t; // next tick renders it; on a non-TTY we stay silent (no flood)
+            text = t;
         },
         stopAndPersist(symbol, t) {
             if (timer) {
@@ -121,17 +87,6 @@ export function createSpinner(opts = {}) {
         },
     };
 }
-/**
- * Split the crabbox run stream at `LEASE_AGENT_MARKER`. `onSetupLine` fires for
- * each complete non-empty line before the marker; `onAgentChunk` fires with raw
- * text after it (streamed promptly, not line-buffered, so agent output is live).
- *
- * Setup lines matching a `___PHASE_<name>___` sentinel are swallowed (never shown
- * as setup noise) and surfaced through `onStep` instead — a structured step
- * stream the command layer can render via `renderStepLine`. When `now` is
- * provided, each step carries `elapsedMs` since the previous step (or router
- * start for the first); omit `now` for deterministic, timing-free output.
- */
 export function createLeaseOutputRouter(cb) {
     const marker = cb.marker ?? LEASE_AGENT_MARKER;
     const now = cb.now;
@@ -171,7 +126,6 @@ export function createLeaseOutputRouter(cb) {
                 buf = buf.slice(idx + 1);
                 if (line.includes(marker)) {
                     seen = true;
-                    // Anything already buffered past the marker is agent output.
                     if (buf) {
                         cb.onAgentChunk(buf);
                         buf = '';
@@ -180,12 +134,11 @@ export function createLeaseOutputRouter(cb) {
                 }
                 const phase = parsePhaseSentinel(line);
                 if (phase !== null) {
-                    emitStep(phase); // swallow the sentinel; report a structured step
+                    emitStep(phase);
                     continue;
                 }
                 emitLine(line);
             }
-            // A trailing partial line stays in `buf` — it may be the marker forming.
         },
         end() {
             if (!seen && buf)

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

@@ -1,24 +1,4 @@
-/**
- * Runtime detection + picker + credential-script builder for `agents run --lease`.
- *
- * The picker asks which coding-agent runtime(s) to provision on a leased box.
- * The default selection is whatever the user is currently signed into locally
- * (via `getAccountInfo`, the same source `agents view` uses). The chosen runtimes
- * drive both what gets installed on the box and which auth token file is copied
- * over — the token contents ride the uploaded `--script-stdin` body, never argv.
- *
- * SECURITY: copying a runtime's auth token to an ephemeral cloud box is a
- * credential transfer. It is strictly opt-in (a confirm prompt in the command
- * layer), the token never appears in argv/`ps`, and `--lease` one-shot runs tear
- * the box down afterward so the credential's lifetime is bounded by the run.
- */
 import type { AgentId } from '../types.js';
-/**
- * Credential file locations per runtime. `localCandidates` are read in order
- * (first existing wins); `remote` is where the box's CLI reads it by default
- * (home-level — no per-version shim). Source of truth for these paths is
- * `getAccountInfo` in src/lib/agents.ts; keep them in sync.
- */
 interface RuntimeCred {
     id: AgentId;
     label: string;
@@ -26,75 +6,26 @@ interface RuntimeCred {
     remote: string;
 }
 export declare const LEASE_RUNTIMES: RuntimeCred[];
-/** True when `id` is a native OAuth / session login that MUST NOT be copied between devices (SING-1b). */
 export declare function isNativeOAuthRuntime(id: AgentId): boolean;
-/** The fail-loud message naming the forbidden runtimes and the portable path to use instead. */
 export declare function nativeOAuthTransferRefusal(nativeRuntimes: AgentId[]): string;
 export interface DetectedRuntime {
     id: AgentId;
     label: string;
     email: string | null;
     signedIn: boolean;
-    /** Absolute local path of the credential file, if found. */
     credPath: string | null;
 }
-/** Which lease-capable runtimes the user is signed into on this machine. */
 export declare function detectSignedInRuntimes(): Promise<DetectedRuntime[]>;
-/**
- * Interactive checkbox: which runtimes to provision on the box. Defaults to the
- * signed-in ones. Runtimes with no local credential are shown disabled.
- * `prompt` is injected so tests don't require a TTY.
- */
 export declare function pickRuntimes(detected: DetectedRuntime[], prompt?: (choices: {
     name: string;
     value: AgentId;
     checked: boolean;
     disabled: boolean | string;
 }[]) => Promise<AgentId[]>): Promise<AgentId[]>;
-/**
- * The lease runtime to provision for a headless run of `agentName`.
- *
- * When the agent is itself a lease-capable runtime (claude/codex/gemini/grok)
- * that IS the runtime to install. Otherwise fall back to the single signed-in
- * lease runtime (preferring claude), or null when none is signed in. This is the
- * non-interactive replacement for the runtime checkbox picker: `--lease` requires
- * a prompt, so it is headless by contract and must never block on a TTY.
- *
- * Profile-dispatch agents (kimi/deepseek) and custom workflow agents that run
- * under a non-obvious runtime are resolved separately — see RUSH-1725.
- */
 export declare function inferLeaseRuntime(agentName: string, detected: DetectedRuntime[]): AgentId | null;
-/** True when a profile already carries auth for its host runtime via env. */
 export declare function profileNeedsBaseRuntimeCredentials(agent: AgentId, env: Record<string, string>, authEnvVar?: string): boolean;
-/** Build a quoted heredoc write to a path under the remote user's home. */
 export declare function buildHomeFileWriteScript(remote: string, contents: string): string;
-/**
- * Where Claude Code reads its OAuth token on the box. `.claude.json` (the file
- * LEASE_RUNTIMES copies) is config/account-metadata ONLY — the actual token
- * lives here, so without it the box boots "Not logged in".
- */
 export declare const CLAUDE_TOKEN_REMOTE = ".claude/.credentials.json";
-/**
- * The RAW wrapped Claude credential payload (`{"claudeAiOauth":{…}}`) to write to
- * the box's `~/.claude/.credentials.json`, or null if no signed-in token is found.
- *
- * On macOS the token is in the login Keychain, read SILENTLY via the standalone
- * `secrets` client's `getKeychainTokenSync` (the `/usr/bin/security … -w` path —
- * Claude's item trusts it, no Touch ID). A default native install uses the bare `Claude Code-credentials`
- * service; an agents-cli managed install (where `~/.claude` symlinks into a
- * versioned home) uses a hash-suffixed service, so we try the bare service first,
- * then enumerate installed version homes (preferring the account whose email
- * matches `preferEmail`, so the token matches the `.claude.json` config we copy).
- * Off macOS the local Claude CLI stores the wrapped rotating blob in
- * `.credentials.json` already. Read that file here with a shape check
- * (`claudeAiOauth.accessToken`). Do not reintroduce a shared helper that
- * also serves Rush Cloud dispatch — dispatch is email-only (SING-1b) and
- * the old `readClaudeCredentialsBlob` path was the #1767 TTY-banner leak
- * (RUSH-2359).
- *
- * The reader/service/version helpers are injected so unit tests never touch the
- * real Keychain.
- */
 export declare function resolveClaudeCredentialsBlob(opts?: {
     preferEmail?: string | null;
     readItem?: (service: string) => string;
@@ -103,34 +34,9 @@ export declare function resolveClaudeCredentialsBlob(opts?: {
     versionHome?: (version: string) => string;
     accountEmail?: (home: string) => Promise<string | null>;
 }): Promise<string | null>;
-/**
- * The credential-provisioning snippet for a `--lease` box.
- *
- * Every runtime this could serialize is a native OAuth / session login
- * (`LEASE_RUNTIMES`), and SING-1b forbids copying one to another device —
- * including an ephemeral leased box, whose refresh of a shared rotating token
- * invalidates every other holder. So this no longer writes a login: it REFUSES
- * (throws, steering to the portable `agents accounts` path) whenever a picked
- * runtime actually has a native credential to copy — signed in locally
- * (`credPath`), or a Claude OAuth blob supplied. A picked runtime with nothing to
- * copy is simply skipped, so `buildCredentialScript` returns `''` (a no-op box
- * bootstrap) rather than throwing on a not-signed-in runtime.
- */
-/**
- * The native OAuth runtimes among `picked` that actually have a credential to copy
- * — signed in locally (`credPath`) or a Claude OAuth blob supplied — i.e. the ones
- * a transfer would leak. A picked runtime with nothing to copy is not refused.
- */
 export declare function refusedNativeOAuthRuntimes(picked: AgentId[], detected: DetectedRuntime[], extras?: {
     claudeCredentialsJson?: string | null;
 }): AgentId[];
-/**
- * Throw the SING-1b refusal if any picked runtime would transfer a native OAuth
- * login. Callers should invoke this at a FAIL-FAST point — before any expensive or
- * costly side effect (e.g. before `crabboxWarmup` leases a paid box) — so a refused
- * `--lease` never leaks infra, mirroring how `--copy-creds` refuses before it opens
- * an SSH connection.
- */
 export declare function assertNoNativeOAuthTransfer(picked: AgentId[], detected: DetectedRuntime[], extras?: {
     claudeCredentialsJson?: string | null;
 }): void;