@phnx-labs/agents-cli 1.20.72 → 1.20.73

package/dist/lib/crabbox/cli.js

@@ -37,6 +37,36 @@ export function pickLeaseBundleFromList(bundles) {
     }
     return undefined;
 }
+/**
+ * Env keys a bundle may use for a Tailscale auth key. crabbox reads
+ * `CRABBOX_TAILSCALE_AUTH_KEY` to join a leased box to the tailnet; we accept the
+ * common alternate names too and rename to that canonical key on injection.
+ */
+export const TAILSCALE_AUTH_KEY_NAMES = ['CRABBOX_TAILSCALE_AUTH_KEY', 'TAILSCALE_AUTH_KEY', 'TS_AUTHKEY'];
+/** The first bundle + key that declares a Tailscale auth key, or undefined. Pure over `bundles`. */
+export function pickTailscaleBundleFromList(bundles) {
+    for (const b of bundles) {
+        const key = Object.keys(b.vars ?? {}).find((k) => TAILSCALE_AUTH_KEY_NAMES.includes(k));
+        if (key)
+            return { name: b.name, key };
+    }
+    return undefined;
+}
+/** Process-lifetime memo so the tailscale bundle `listBundles()` scan runs at most once. */
+let tailscaleBundleMemo;
+function resolveTailscaleBundleMemo() {
+    if (!tailscaleBundleMemo) {
+        let value;
+        try {
+            value = pickTailscaleBundleFromList(listBundles());
+        }
+        catch {
+            /* secrets unreadable — no auto-detect */
+        }
+        tailscaleBundleMemo = { value };
+    }
+    return tailscaleBundleMemo.value;
+}
 /**
  * The secrets bundle to feed crabbox, resolved in priority order:
  *   1. `AGENTS_LEASE_SECRETS_BUNDLE` env var          — explicit, no keychain
@@ -92,30 +122,55 @@ export function setLeaseSecretsBundle(name) {
 }
 /** Build the child env for crabbox, injecting a secrets bundle when configured. */
 export function crabboxEnv(opts) {
+    const out = { ...process.env };
     const resolved = opts.secretsBundle
         ? { name: opts.secretsBundle }
         : resolveLeaseBundleMemo();
-    if (!resolved)
-        return process.env;
-    try {
-        // Auto-detected bundle → inject ONLY the provider token key(s) (least
-        // privilege; an unrelated bundle can't leak its other secrets into crabbox).
-        // An explicitly-named bundle (env/config or `opts.secretsBundle`) injects
-        // whole — the user chose it. Same resolver `agents secrets exec` uses.
-        const { env } = readAndResolveBundleEnv(resolved.name, {
-            caller: 'agents run --lease (crabbox)',
-            keys: resolved.keys,
-            // --lease is headless by contract and crabboxEnv is called several times
-            // per run (list/wait/spawn/stop) — resolve broker-only so a keychain bundle
-            // can't pop repeated unwatched Touch ID sheets mid-lease.
-            agentOnly: isHeadlessSecretsContext(),
-        });
-        return { ...process.env, ...env };
+    if (resolved) {
+        try {
+            // Auto-detected bundle → inject ONLY the provider token key(s) (least
+            // privilege; an unrelated bundle can't leak its other secrets into crabbox).
+            // An explicitly-named bundle (env/config or `opts.secretsBundle`) injects
+            // whole — the user chose it. Same resolver `agents secrets exec` uses.
+            const { env } = readAndResolveBundleEnv(resolved.name, {
+                caller: 'agents run --lease (crabbox)',
+                keys: resolved.keys,
+                // --lease is headless by contract and crabboxEnv is called several times
+                // per run (list/wait/spawn/stop) — resolve broker-only so a keychain bundle
+                // can't pop repeated unwatched Touch ID sheets mid-lease.
+                agentOnly: isHeadlessSecretsContext(),
+            });
+            Object.assign(out, env);
+        }
+        catch (e) {
+            throw new Error(`Could not load secrets bundle "${resolved.name}" for crabbox: ${e.message}. ` +
+                `Fix the bundle (agents secrets view ${resolved.name}) or unset lease.secretsBundle to use crabbox's own login.`);
+        }
     }
-    catch (e) {
-        throw new Error(`Could not load secrets bundle "${resolved.name}" for crabbox: ${e.message}. ` +
-            `Fix the bundle (agents secrets view ${resolved.name}) or unset lease.secretsBundle to use crabbox's own login.`);
+    // Tailscale plumbing (F5): inject CRABBOX_TAILSCALE_AUTH_KEY from a bundle that
+    // declares a tailscale auth key, when the ambient env doesn't already set one.
+    // Best-effort and opt-in — a missing/unreadable tailscale bundle never fails a
+    // public-network lease; `crabboxWarmup({ netMode: 'tailscale' })` is what decides
+    // whether the key is actually used.
+    if (!out.CRABBOX_TAILSCALE_AUTH_KEY) {
+        const ts = resolveTailscaleBundleMemo();
+        if (ts) {
+            try {
+                const { env } = readAndResolveBundleEnv(ts.name, {
+                    caller: 'agents run --lease (crabbox tailscale)',
+                    keys: [ts.key],
+                    agentOnly: isHeadlessSecretsContext(),
+                });
+                const value = env[ts.key];
+                if (value)
+                    out.CRABBOX_TAILSCALE_AUTH_KEY = value;
+            }
+            catch {
+                /* best-effort — tailscale is opt-in plumbing, never blocks a public lease */
+            }
+        }
     }
+    return out;
 }
 function normalizeBox(raw) {
     const labels = (raw.labels ?? {});
@@ -138,6 +193,8 @@ function normalizeBox(raw) {
         lease: labels.lease ?? '',
         state,
         ip: publicNet.ipv4?.ip || undefined,
+        tailscaleIPv4: labels.tailscale_ipv4 || undefined,
+        tailscaleFQDN: labels.tailscale_fqdn || undefined,
         profile: labels.profile,
         class: labels.class,
         ready: status === 'running' && state === 'ready',
@@ -151,7 +208,11 @@ function normalizeBox(raw) {
 /** All crabbox machines the broker knows about. */
 export function crabboxList(opts = {}) {
     findCrabbox();
-    const r = spawnSync('crabbox', ['list', '--json'], { encoding: 'utf-8', env: crabboxEnv(opts) });
+    const timeoutMs = opts.timeoutMs ?? 8000;
+    const r = spawnSync('crabbox', ['list', '--json'], { encoding: 'utf-8', env: crabboxEnv(opts), timeout: timeoutMs });
+    if (r.error && r.error.code === 'ETIMEDOUT') {
+        throw new Error(`crabbox list timed out after ${Math.round(timeoutMs / 1000)}s (provider slow or unreachable)`);
+    }
     if (r.status !== 0) {
         throw new Error(`crabbox list failed: ${(r.stderr || r.stdout || '').trim() || 'unknown error'}`);
     }
@@ -190,6 +251,10 @@ export async function crabboxWarmup(opts = {}) {
         args.push('--provider', opts.provider);
     if (opts.code)
         args.push('--code');
+    // Tailscale plumbing (F5): join the box to the tailnet, tagged tag:crabbox.
+    // The auth key rides the child env as CRABBOX_TAILSCALE_AUTH_KEY (see crabboxEnv).
+    if (opts.netMode === 'tailscale')
+        args.push('--network', 'tailscale', '-tailscale-tags', 'tag:crabbox');
     // Async spawn (not spawnSync): provisioning takes 30-90s and a blocking call
     // would freeze any caller's progress spinner. Output is captured, not streamed.
     const r = await new Promise((resolve) => {
@@ -324,6 +389,41 @@ export function crabboxRunScript(slug, script, opts = {}) {
         proc.stdin.end();
     });
 }
+/**
+ * Parse crabbox's shell-quoted `ssh` command (`'ssh' '-i' '<key>' … 'crabbox@ip'`)
+ * into an argv array. Exported for testing.
+ */
+export function parseCrabboxSshArgv(stdout) {
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith("'ssh'") && !line.startsWith('ssh '))
+            continue;
+        const toks = [...line.matchAll(/'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2]);
+        if (toks[0] === 'ssh' && toks.length >= 3)
+            return toks;
+    }
+    return null;
+}
+/**
+ * The concrete `ssh` argv crabbox uses to reach box `slug` — including the
+ * per-lease identity key and known_hosts crabbox provisions under its own config
+ * dir. A raw `ssh crabbox@ip` fails `publickey`; this is the only auth that works.
+ * `crabbox ssh --id` PRINTS the command (it doesn't connect — that's `crabbox
+ * connect`), and `--reclaim` makes it resolve regardless of which repo holds the
+ * lease claim (matching `crabboxRunScript`). Returns null when crabbox can't
+ * resolve the box (caller treats setup-copy / `agents ssh` as best-effort).
+ */
+export function crabboxSshArgv(slug, opts = {}) {
+    findCrabbox();
+    const r = spawnSync('crabbox', ['ssh', '--id', slug, '--reclaim'], {
+        encoding: 'utf-8',
+        env: crabboxEnv(opts),
+        timeout: opts.timeoutMs ?? 15000,
+    });
+    if (r.status !== 0 || !r.stdout)
+        return null;
+    return parseCrabboxSshArgv(r.stdout);
+}
 /** Release the lease / delete the box. Best-effort; never throws. */
 export function crabboxStop(slug, opts = {}) {
     try {

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

@@ -5,6 +5,24 @@
  * 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.
+ *
+ * ── 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`).
+ *   • `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 type { AgentId } from '../types.js';
 import { type CrabboxBox } from './cli.js';
@@ -13,6 +31,9 @@ import { type DetectedRuntime } from './runtimes.js';
 export type LeasePhase = {
     kind: 'warmup';
     backend?: string;
+} | {
+    kind: 'reuse';
+    slug: string;
 } | {
     kind: 'ready';
     box: CrabboxBox;
@@ -29,16 +50,36 @@ export interface LeaseRunOptions {
     backend?: string;
     boxClass?: string;
     profile?: string;
-    /** Runtimes to install + authenticate on the box (from the picker). */
+    /** Runtimes to install on the box. */
     runtimes: AgentId[];
+    /** Runtime credentials to copy; defaults to `runtimes`. */
+    credentialRuntimes?: AgentId[];
     detected: DetectedRuntime[];
+    /** Profile-dispatch config to materialize on the leased box before the run. */
+    dispatchProfile?: LeaseDispatchProfile;
     /** Secrets bundle providing crabbox's provider token. */
     secretsBundle?: string;
+    /**
+     * Push the git-tracked subset of the local `~/.agents` onto the box before the
+     * run (default TRUE). The command layer sets `false` for `--bare`. When true,
+     * `buildBootstrapScript` emits the `copy-setup` progress sentinel; the actual
+     * push-from-local is `copySetupToBox` (setup-copy.ts), which the command layer
+     * runs before the box run.
+     */
+    copySetup?: boolean;
+    /**
+     * Network mode threaded to `crabboxWarmup` (default `'public'`). `'tailscale'`
+     * leases the box onto the tailnet and adds a `joined-tailnet` progress step.
+     * The command layer decides WHEN to enable it — this is plumbing only.
+     */
+    netMode?: 'public' | 'tailscale';
     onData?: (s: string) => void;
     /** Progress phases (warmup → ready → teardown) for a command-layer spinner. */
     onPhase?: (phase: LeasePhase) => void;
     /** Keep the box after the run instead of stopping it. */
     keep?: boolean;
+    /** Existing warm crabbox slug to reuse instead of provisioning a new lease. */
+    reuseBox?: string;
     /**
      * Raw wrapped Claude OAuth payload (from `resolveClaudeCredentialsBlob`), written
      * to `~/.claude/.credentials.json` on the box. The command layer resolves it
@@ -46,6 +87,16 @@ export interface LeaseRunOptions {
      */
     claudeCredentialsJson?: string | null;
 }
+export interface LeaseDispatchProfile {
+    name: string;
+    agent: AgentId;
+    version?: string;
+    env: Record<string, string>;
+    description?: string;
+    preset?: string;
+    provider?: string;
+    fallbackModel?: string;
+}
 export interface LeaseRunResult {
     box: CrabboxBox;
     exitCode: number | null;

package/dist/lib/crabbox/lease.js

@@ -5,14 +5,58 @@
  * 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.
+ *
+ * ── 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`).
+ *   • `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 { crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop } from './cli.js';
-import { buildCredentialScript, CLAUDE_TOKEN_REMOTE } from './runtimes.js';
-import { LEASE_AGENT_MARKER } from './progress.js';
+import { crabboxFind, crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop } 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';
+import { copySetupToBox } from './setup-copy.js';
 /** POSIX single-quote for safe embedding in the generated bootstrap script. */
 function q(s) {
     return "'" + s.replace(/'/g, "'\\''") + "'";
 }
+function profileRemotePath(name) {
+    return `.agents/profiles/${name}.yml`;
+}
+function buildProfileScript(profile) {
+    const body = yaml.stringify({
+        name: profile.name,
+        ...(profile.description ? { description: profile.description } : {}),
+        host: {
+            agent: profile.agent,
+            ...(profile.version ? { version: profile.version } : {}),
+        },
+        env: profile.env,
+        ...(profile.fallbackModel ? { fallback_model: profile.fallbackModel } : {}),
+        ...(profile.preset ? { preset: profile.preset } : {}),
+        ...(profile.provider ? { provider: profile.provider } : {}),
+    });
+    return buildHomeFileWriteScript(profileRemotePath(profile.name), body);
+}
+function runtimeInstallSpec(id, dispatchProfile) {
+    if (dispatchProfile?.agent === id && dispatchProfile.version) {
+        return `${id}@${dispatchProfile.version}`;
+    }
+    return id;
+}
 /**
  * Bash snippet that guarantees `agents` is runnable on the box. Fresh crabbox
  * images ship without node, and the box user may not own the global npm prefix,
@@ -47,9 +91,11 @@ const ENSURE_AGENTS_CLI = [
  * the credential files. Best-effort install steps never abort the run.
  */
 export function buildBootstrapScript(opts) {
-    const credScript = buildCredentialScript(opts.runtimes, opts.detected, {
+    const credentialRuntimes = opts.credentialRuntimes ?? opts.runtimes;
+    const credScript = buildCredentialScript(credentialRuntimes, opts.detected, {
         claudeCredentialsJson: opts.claudeCredentialsJson,
     });
+    const profileScript = opts.dispatchProfile ? buildProfileScript(opts.dispatchProfile) : '';
     const runParts = ['agents', 'run', q(opts.agent), q(opts.prompt), '--quiet'];
     if (opts.mode)
         runParts.push('--mode', q(opts.mode));
@@ -58,17 +104,40 @@ export function buildBootstrapScript(opts) {
     // 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 = opts.runtimes.flatMap((id) => {
+    const shredPaths = credentialRuntimes.flatMap((id) => {
         const paths = { claude: ['.claude.json', CLAUDE_TOKEN_REMOTE], codex: ['.codex/auth.json'], gemini: ['.gemini/google_accounts.json'], grok: ['.grok/auth.json'] }[id];
         return paths ?? [];
     });
+    if (opts.dispatchProfile)
+        shredPaths.push(profileRemotePath(opts.dispatchProfile.name));
     const shred = shredPaths.map((p) => `rm -f "$HOME/${p}" 2>/dev/null || true`).join('\n');
-    const installRuntimes = opts.runtimes.map((id) => `agents add ${q(id)} >/dev/null 2>&1 || true`).join('\n');
+    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
     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'),
+        // Only meaningful on a tailnet lease — the box already joined during warmup.
+        opts.netMode === 'tailscale' ? step('joined-tailnet') : '',
+        step('install'),
         ENSURE_AGENTS_CLI,
+        step('runtime'),
         installRuntimes,
+        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 repo refresh >/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)}`,
@@ -82,15 +151,47 @@ export function buildBootstrapScript(opts) {
 }
 export async function leaseAndRun(opts) {
     const startedAt = Date.now();
-    opts.onPhase?.({ kind: 'warmup', backend: opts.backend });
-    const box = await crabboxWarmup({
-        class: opts.boxClass,
-        profile: opts.profile,
-        provider: opts.backend,
-        secretsBundle: opts.secretsBundle,
-    });
-    await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+    let box;
+    if (opts.reuseBox) {
+        opts.onPhase?.({ kind: 'reuse', slug: opts.reuseBox });
+        const found = crabboxFind(opts.reuseBox, { secretsBundle: opts.secretsBundle });
+        if (!found)
+            throw new Error(`crabbox box "${opts.reuseBox}" was not found. Check \`crabbox list\` or pass a different --box slug.`);
+        box = found.ready
+            ? found
+            : await crabboxWaitReady(opts.reuseBox, { secretsBundle: opts.secretsBundle });
+    }
+    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
+    // 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 repo refresh` 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({
+                slug: box.slug,
+                secretsBundle: opts.secretsBundle,
+                onData: opts.onData,
+                refresh: false,
+            });
+        }
+        catch {
+            /* best-effort — never block the run on a config-copy failure */
+        }
+    }
     const script = buildBootstrapScript(opts);
     let exitCode = null;
     let toreDown = false;
@@ -102,8 +203,8 @@ export async function leaseAndRun(opts) {
     }
     finally {
         // Always attempt teardown (bounds credential lifetime to the run) unless the
-        // caller explicitly asked to keep the box.
-        if (!opts.keep) {
+        // caller explicitly asked to keep the box or targeted an existing warm box.
+        if (!opts.keep && !opts.reuseBox) {
             opts.onPhase?.({ kind: 'teardown' });
             toreDown = crabboxStop(box.slug, { secretsBundle: opts.secretsBundle });
         }

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

@@ -9,6 +9,27 @@
  */
 /** 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;
@@ -49,14 +70,24 @@ export interface LeaseOutputRouter {
     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;
+    onStep?: (step: LeaseStep) => void;
     marker?: string;
+    now?: () => number;
 }): LeaseOutputRouter;

package/dist/lib/crabbox/progress.js

@@ -9,6 +9,54 @@
  */
 /** 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',
+    runtime: 'Installing agent runtimes',
+    creds: 'Provisioning credentials',
+    '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`;
+    const secs = Math.round(ms / 1000);
+    if (secs < 60)
+        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}` : '';
+    const elapsed = step.elapsedMs !== undefined ? ` (${formatElapsed(step.elapsedMs)})` : '';
+    return `${label}${detail}${elapsed}`;
+}
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 /**
  * A deliberately minimal, self-throttled spinner. Unlike `ora`, it does NOT hook
@@ -77,12 +125,21 @@ 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;
     let seen = false;
     let buf = '';
     const setup = [];
+    const stepList = [];
+    let lastStepAt = now ? now() : undefined;
     const emitLine = (line) => {
         const t = line.replace(/\r$/, '');
         if (t.trim()) {
@@ -90,6 +147,17 @@ export function createLeaseOutputRouter(cb) {
             cb.onSetupLine(t);
         }
     };
+    const emitStep = (name) => {
+        let elapsedMs;
+        if (now) {
+            const t = now();
+            elapsedMs = lastStepAt !== undefined ? t - lastStepAt : undefined;
+            lastStepAt = t;
+        }
+        const step = elapsedMs !== undefined ? { name, elapsedMs } : { name };
+        stepList.push(step);
+        cb.onStep?.(step);
+    };
     return {
         push(chunk) {
             if (seen) {
@@ -110,6 +178,11 @@ export function createLeaseOutputRouter(cb) {
                     }
                     return;
                 }
+                const phase = parsePhaseSentinel(line);
+                if (phase !== null) {
+                    emitStep(phase); // swallow the sentinel; report a structured step
+                    continue;
+                }
                 emitLine(line);
             }
             // A trailing partial line stays in `buf` — it may be the marker forming.
@@ -125,5 +198,8 @@ export function createLeaseOutputRouter(cb) {
         setupLines() {
             return setup;
         },
+        steps() {
+            return stepList;
+        },
     };
 }

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

@@ -60,6 +60,10 @@ export declare function pickRuntimes(detected: DetectedRuntime[], prompt?: (choi
  * 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