@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/crabbox/cli.js

@@ -1,21 +1,7 @@
-/**
- * Typed wrapper over the external `crabbox` binary (github.com/openclaw/crabbox).
- *
- * crabbox leases ephemeral cloud boxes (Hetzner/DO/EC2/…), syncs the dirty
- * checkout, and runs commands on them. We use it as the transport for
- * `agents run --lease`: warm a box → run the agent on it via `crabbox run` →
- * stop it. crabbox owns the SSH connection, so agents-cli never needs a direct
- * ssh target (unlike the host-dispatch model).
- *
- * crabbox talks to its cloud provider's API for list/status/warmup/stop, which
- * needs a provider token (e.g. HCLOUD_TOKEN) in the environment. We inject it
- * from a secrets bundle when one is configured (see `crabboxEnv`).
- */
 import { spawn, spawnSync } from 'child_process';
 import { readAndResolveBundleEnvSync, listBundlesSync, bundleExistsSync } from '../secrets-client.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' });
     if (r.error) {
@@ -23,14 +9,7 @@ export function findCrabbox() {
     }
     return 'crabbox';
 }
-/**
- * Env keys that mark a secrets bundle as usable for `--lease` — the provider
- * tokens crabbox reads to reach a cloud API. Matching a bundle needs only its
- * declared key NAMES; only the matched key's VALUE is ever injected (see
- * `crabboxEnv`), so an auto-detected bundle can't leak its other secrets.
- */
 const LEASE_PROVIDER_TOKEN_KEYS = ['HCLOUD_TOKEN', 'AWS_ACCESS_KEY_ID', 'DIGITALOCEAN_TOKEN', 'DO_TOKEN'];
-/** The first bundle that declares a provider token key, or undefined. Pure over `bundles`. */
 export function pickLeaseBundleFromList(bundles) {
     for (const b of bundles) {
         if (Object.keys(b.vars ?? {}).some((k) => LEASE_PROVIDER_TOKEN_KEYS.includes(k)))
@@ -38,13 +17,7 @@ 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.
- */
 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));
@@ -53,7 +26,6 @@ export function pickTailscaleBundleFromList(bundles) {
     }
     return undefined;
 }
-/** Process-lifetime memo so the tailscale bundle `listBundles()` scan runs at most once. */
 let tailscaleBundleMemo;
 function resolveTailscaleBundleMemo() {
     if (!tailscaleBundleMemo) {
@@ -62,27 +34,11 @@ function resolveTailscaleBundleMemo() {
             value = pickTailscaleBundleFromList(listBundlesSync());
         }
         catch {
-            /* secrets unreadable — no auto-detect */
         }
         tailscaleBundleMemo = { value };
     }
     return tailscaleBundleMemo.value;
 }
-/**
- * Process-lifetime memo for the RESOLVED tailscale key value, next to the pick
- * memo above. `crabboxEnv` runs several times per lease (list/wait/spawn/stop),
- * and the single-key subset read (`keys: [ts.key]`) is rejected by
- * `canCacheResolvedEnv` for broker auto-cache — so without this memo a
- * non-broker-held tailscale bundle re-read the keychain on EVERY call (and,
- * pre-guard, could pop a Touch ID sheet each time). The read is always
- * `agentOnly: true` (broker-only, SEC-13): tailscale is opt-in plumbing, a
- * `--lease` run is headless by contract, and even an interactive `--lease`
- * invocation must never pop an unwatched Touch ID sheet for this best-effort
- * read — a locked bundle degrades silently to a public-network lease via the
- * catch below. One read per process, success or failure (a failed read
- * memoizes as undefined: the catch below already degrades to a public-network
- * lease, retrying mid-process only repeats the same failure).
- */
 let tailscaleValueMemo;
 function resolveTailscaleKeyValueMemo(ts) {
     if (!tailscaleValueMemo) {
@@ -96,33 +52,17 @@ function resolveTailscaleKeyValueMemo(ts) {
             value = env[ts.key];
         }
         catch {
-            /* best-effort — tailscale is opt-in plumbing, never blocks a public lease */
         }
         tailscaleValueMemo = { value };
     }
     return tailscaleValueMemo.value;
 }
-/** Test seam: drop every crabboxEnv secrets memo so each test resolves fresh. */
 export function resetCrabboxSecretsMemosForTest() {
     tailscaleBundleMemo = undefined;
     tailscaleValueMemo = undefined;
     leaseBundleMemo = undefined;
     leaseEnvMemo = undefined;
 }
-/**
- * The secrets bundle to feed crabbox, resolved in priority order:
- *   1. `AGENTS_LEASE_SECRETS_BUNDLE` env var          — explicit, no keychain
- *   2. `lease.secretsBundle` config (set by `lease setup`) — explicit, no keychain
- *   3. auto-detect: the first keychain bundle DECLARING a provider token key
- *
- * Tiers 1–2 are the frictionless steady state (env + config are plain, no keychain
- * read). Tier 3 is a fallback that DOES read bundle metadata via `listBundles()`
- * (one batched keychain unlock, ~7-day broker cache) — so it only runs when
- * neither env nor config is set, and `crabboxEnv` memoizes the result for the
- * process (it is called several times per lease, and we don't want a scan each
- * time). Once `lease setup` persists the choice (tier 2), tier 3 never runs.
- * Returns undefined when nothing matches — crabbox then falls back to `crabbox login`.
- */
 export function resolveLeaseBundle() {
     const env = process.env.AGENTS_LEASE_SECRETS_BUNDLE;
     if (env)
@@ -133,7 +73,6 @@ export function resolveLeaseBundle() {
             return { name: configured };
     }
     catch {
-        /* config unreadable — fall through to auto-detect */
     }
     try {
         const bundles = listBundlesSync();
@@ -145,33 +84,15 @@ export function resolveLeaseBundle() {
         }
     }
     catch {
-        /* secrets unreadable — no auto-detect */
     }
     return undefined;
 }
-/** Process-lifetime memo so the tier-3 `listBundles()` scan runs at most once. */
 let leaseBundleMemo;
 function resolveLeaseBundleMemo() {
     if (!leaseBundleMemo)
         leaseBundleMemo = { value: resolveLeaseBundle() };
     return leaseBundleMemo.value;
 }
-/**
- * Process-lifetime memo for the RESOLVED provider-token env, resolved ONCE up
- * front. `crabboxEnv` is called on every `crabboxWaitReady` poll iteration
- * (crabboxWaitReady → crabboxFind → crabboxList → crabboxEnv), so without this
- * memo the lease-token keychain read re-ran every ~5s of the ready wait — the
- * per-poll storm this fix exists to kill. The read is now `agentOnly: true`
- * (SEC-13: a `--lease` run is headless by contract and must never pop an
- * unwatched Touch ID sheet). A locked `hold`/`always` bundle makes that read
- * THROW the actionable "unlock <name>" message; we memoize the thrown error too
- * and re-raise it on every subsequent call, so the failure surfaces loud ONCE
- * up front (crabboxWarmup / the first crabboxList, before any poll loop) and the
- * loop never re-issues the read. A `never`/no-ACL or broker-held bundle resolves
- * silently. `undefined` when no lease bundle is configured (crabbox uses its own
- * `crabbox login`). The memo (success OR failure) is cleared per test by
- * resetCrabboxSecretsMemosForTest.
- */
 let leaseEnvMemo;
 function resolveLeaseEnvMemo(explicitBundle) {
     if (!leaseEnvMemo) {
@@ -183,16 +104,9 @@ function resolveLeaseEnvMemo(explicitBundle) {
         }
         else {
             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 } = readAndResolveBundleEnvSync(resolved.name, {
                     caller: 'agents run --lease (crabbox)',
                     keys: resolved.keys,
-                    // --lease is headless by contract and a locked bundle must fail loud with
-                    // an unlock hint, NEVER pop a Touch ID sheet — the read cannot be answered
-                    // in a background lease (SEC-13).
                     agentOnly: true,
                 });
                 leaseEnvMemo = { env };
@@ -209,30 +123,16 @@ function resolveLeaseEnvMemo(explicitBundle) {
         throw leaseEnvMemo.error;
     return leaseEnvMemo.env;
 }
-/** Persist `lease.secretsBundle` in agents config so `--lease` needs no env var. */
 export function setLeaseSecretsBundle(name) {
     const meta = readMeta();
     writeMeta({ ...meta, lease: { ...meta.lease, secretsBundle: name } });
-    leaseBundleMemo = undefined; // invalidate so the next resolve sees the new config
+    leaseBundleMemo = undefined;
 }
-/** Build the child env for crabbox, injecting a secrets bundle when configured. */
 export function crabboxEnv(opts) {
     const out = { ...process.env };
-    // The lease provider-token read is resolved ONCE up front and memoized (env or
-    // thrown error) for the process — crabboxEnv runs on every crabboxWaitReady
-    // poll, so re-reading here was the per-poll storm. A locked bundle re-raises
-    // the memoized "unlock <name>" error every call, so the failure surfaces loud
-    // on the first crabboxEnv (before any poll loop) and never re-issues the read.
     const leaseEnv = resolveLeaseEnvMemo(opts.secretsBundle);
     if (leaseEnv)
         Object.assign(out, leaseEnv);
-    // 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. The resolved value is memoized per process
-    // (see resolveTailscaleKeyValueMemo) so repeated crabboxEnv calls read the
-    // keychain at most once.
     if (!out.CRABBOX_TAILSCALE_AUTH_KEY) {
         const ts = resolveTailscaleBundleMemo();
         if (ts) {
@@ -276,7 +176,6 @@ function normalizeBox(raw) {
         idleTimeoutSecs: num(labels.idle_timeout_secs ?? labels.idle_timeout),
     };
 }
-/** All crabbox machines the broker knows about. */
 export function crabboxList(opts = {}) {
     findCrabbox();
     const timeoutMs = opts.timeoutMs ?? 8000;
@@ -298,17 +197,9 @@ export function crabboxList(opts = {}) {
         return [];
     return parsed.map((b) => normalizeBox(b)).filter((b) => b !== null);
 }
-/** Find one box by slug, or null. */
 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], {
@@ -320,16 +211,6 @@ export function crabboxStatusReady(slug, opts = {}) {
         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';
@@ -347,13 +228,6 @@ export function poolReusableBoxes(boxes, opts = {}) {
     })
         .sort((a, b) => (b.lastTouchedAt ?? 0) - (a.lastTouchedAt ?? 0));
 }
-/**
- * Lease a box and block until it is ready. Returns the leased box.
- *
- * We diff `crabbox list` before/after so we reliably identify the box this call
- * created even if warmup's stdout format changes — the new lease id is the one
- * that wasn't present before.
- */
 export async function crabboxWarmup(opts = {}) {
     findCrabbox();
     const env = crabboxEnv(opts);
@@ -367,12 +241,8 @@ 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) => {
         const proc = spawn('crabbox', args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
         let stdout = '';
@@ -384,9 +254,6 @@ export async function crabboxWarmup(opts = {}) {
     });
     if (r.status !== 0) {
         const detail = (r.stderr || r.stdout || '').trim();
-        // A provider `server_limit` / `resource_limit_exceeded` 403 means the account's
-        // box quota is full. Turn the raw 403 into an actionable message that names the
-        // reap-safe orphans + the one-command fix, instead of a generic failure.
         if (/server_limit|resource_limit_exceeded/i.test(detail)) {
             let hint = ' Stop unused boxes (`crabbox list`) or raise your provider server limit.';
             try {
@@ -398,19 +265,16 @@ export async function crabboxWarmup(opts = {}) {
                 }
             }
             catch {
-                /* best-effort hint; fall back to the generic guidance above */
             }
             throw new Error(`crabbox warmup failed: provider server limit reached.${hint}`);
         }
         throw new Error(`crabbox warmup failed: ${detail || 'unknown error'}. ` +
             `Check provider access with \`crabbox doctor\`; a missing cloud token often means \`crabbox login\` or a lease.secretsBundle is needed.`);
     }
-    // Prefer the freshly-created box (lease absent from the pre-warmup snapshot).
     const after = crabboxList(opts);
     const fresh = after.filter((b) => !before.has(b.lease));
     if (fresh.length === 1)
         return fresh[0];
-    // Fallback: parse the cbx_ lease id crabbox prints and match it.
     const m = (r.stdout || '').match(/cbx_[0-9a-f]+/i);
     if (m) {
         const byLease = after.find((b) => b.lease === m[0]);
@@ -418,7 +282,6 @@ export async function crabboxWarmup(opts = {}) {
             return byLease;
     }
     if (fresh.length > 1) {
-        // Multiple new boxes (concurrent warmups) — pick the newest ready one.
         const ready = fresh.filter((b) => b.ready);
         if (ready.length)
             return ready[ready.length - 1];
@@ -426,17 +289,12 @@ export async function crabboxWarmup(opts = {}) {
     }
     throw new Error('crabbox warmup succeeded but the new box could not be located in `crabbox list`.');
 }
-/**
- * Poll until the box reports ready, or throw after timeoutMs.
- * `sleep` is injectable so tests don't wall-clock wait.
- */
 export async function crabboxWaitReady(slug, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 180_000;
     const intervalMs = opts.intervalMs ?? 5_000;
     const sleep = opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
     const deadline = Date.now() + timeoutMs;
     let last = null;
-    // First check is immediate (warmup usually returns an already-ready box).
     for (;;) {
         last = crabboxFind(slug, opts);
         if (last?.ready)
@@ -447,15 +305,6 @@ export async function crabboxWaitReady(slug, opts = {}) {
     }
     throw new Error(`crabbox box "${slug}" did not become ready within ${Math.round(timeoutMs / 1000)}s (state: ${last?.state ?? 'gone'}).`);
 }
-/**
- * Upload `script` to the box via `crabbox run --script-stdin` and run it.
- *
- * The script body travels over stdin and is written to a file on the box before
- * execution — it never appears in argv / `ps` / shell history, which is why this
- * is the transport for credential provisioning (the token contents live only in
- * the uploaded script, then the file is removed by the script itself).
- * Streams combined output; resolves with the remote exit code (null on dispatch failure).
- */
 export function crabboxRunScript(slug, script, opts = {}) {
     findCrabbox();
     const args = ['run', '--id', slug, '--reclaim'];
@@ -481,10 +330,6 @@ 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();
@@ -496,15 +341,6 @@ export function parseCrabboxSshArgv(stdout) {
     }
     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'], {
@@ -516,12 +352,8 @@ export function crabboxSshArgv(slug, opts = {}) {
         return null;
     return parseCrabboxSshArgv(r.stdout);
 }
-/** Release the lease / delete the box. Best-effort; never throws. */
 export function crabboxStop(slug, opts = {}) {
     try {
-        // Positional target: crabbox's stop subcommand has no --id flag (unlike
-        // status/run/ssh) — `stop --id <slug>` dies with "flag provided but not
-        // defined: -id" and the box leaks past the run it was leased for.
         const r = spawnSync('crabbox', ['stop', slug], { encoding: 'utf-8', env: crabboxEnv(opts) });
         return r.status === 0;
     }
@@ -529,20 +361,7 @@ export function crabboxStop(slug, opts = {}) {
         return false;
     }
 }
-/** Never reap a box touched within this many seconds, regardless of idle-timeout. */
 export const REAP_MIN_IDLE_SECS = 3600;
-/**
- * Whether a box is a genuine orphan that is safe to reap.
- *
- * Reap-safe ONLY when BOTH hold: the lease has already expired (`expiresAt` in the
- * past) AND the box has not been touched for a safety window of
- * `max(2 × idleTimeout, 1h)`. The freshness guard is what makes this safe against
- * a TOCTOU race: a box a concurrent run just reused (`cbx_acquire_box`) has a
- * recent `lastTouchedAt` and is never eligible. Reaping by `profile`/`ready` alone
- * — as `crabbox cleanup` cannot (it skips `keep=true`, which every real orphan is)
- * — would kill in-use boxes. Boxes with unknown age (`expiresAt`/`lastTouchedAt`
- * null) are never reaped. `nowSecs` is injected so tests don't wall-clock.
- */
 export function isReapSafe(box, nowSecs) {
     if (box.expiresAt === null || box.lastTouchedAt === null)
         return false;
@@ -551,17 +370,11 @@ export function isReapSafe(box, nowSecs) {
     const window = Math.max((box.idleTimeoutSecs ?? 0) * 2, REAP_MIN_IDLE_SECS);
     return nowSecs - box.lastTouchedAt >= window;
 }
-/** The reap-safe orphans among `boxes`, most-stale (oldest touch) first. */
 export function reapSafeOrphans(boxes, nowSecs) {
     return boxes
         .filter((b) => isReapSafe(b, nowSecs))
         .sort((a, b) => (a.lastTouchedAt ?? 0) - (b.lastTouchedAt ?? 0));
 }
-/**
- * List reap-safe orphans and (unless `dryRun`) stop them. Returns the candidates
- * considered and the slugs actually stopped. Best-effort per box — a stop failure
- * is skipped, never thrown. Backs `agents devices lease prune` and the 403 auto-reap opt-in.
- */
 export function reapOrphans(opts = {}) {
     const nowSecs = opts.nowSecs ?? Math.floor(Date.now() / 1000);
     const candidates = reapSafeOrphans(crabboxList(opts), nowSecs);

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

@@ -1,20 +1,2 @@
-/**
- * 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` deliberately does NOT inherit
- * that repo/CI label: leases share the default pool unless `leaseProfile:` opts
- * the repo into a dedicated hot box.
- */
-/**
- * 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";
-/**
- * Pool label for `agents run --lease`. The generic `profile:` key remains owned
- * by repo sandbox/CI scripts; only the explicit `leaseProfile:` key opts lease
- * runs out of the shared default pool.
- */
 export declare function readCrabboxLeaseProfile(repoRoot: string): string;

package/dist/lib/crabbox/config.js

@@ -1,19 +1,6 @@
-/**
- * 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` deliberately does NOT inherit
- * that repo/CI label: leases share the default pool unless `leaseProfile:` opts
- * the repo into a dedicated hot box.
- */
 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';
 function readCrabboxRepoConfig(repoRoot) {
     let raw;
@@ -21,7 +8,7 @@ function readCrabboxRepoConfig(repoRoot) {
         raw = fs.readFileSync(path.join(repoRoot, '.crabbox.yaml'), 'utf-8');
     }
     catch {
-        return undefined; // no repo crabbox config — crabbox's own default applies
+        return undefined;
     }
     let parsed;
     try {
@@ -32,11 +19,6 @@ function readCrabboxRepoConfig(repoRoot) {
     }
     return parsed && typeof parsed === 'object' ? parsed : undefined;
 }
-/**
- * Pool label for `agents run --lease`. The generic `profile:` key remains owned
- * by repo sandbox/CI scripts; only the explicit `leaseProfile:` key opts lease
- * runs out of the shared default pool.
- */
 export function readCrabboxLeaseProfile(repoRoot) {
     const profile = readCrabboxRepoConfig(repoRoot)?.leaseProfile;
     return typeof profile === 'string' && profile.length > 0 ? profile : DEFAULT_CRABBOX_PROFILE;

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

@@ -1,38 +1,6 @@
-/**
- * `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 type { AgentId } from '../types.js';
 import { type CrabboxBox } from './cli.js';
 import { type DetectedRuntime } from './runtimes.js';
-/** Phase signal for a lease run, so the command layer can drive a progress UI. */
 type LeasePhase = {
     kind: 'warmup';
     backend?: string;
@@ -51,53 +19,22 @@ interface LeaseRunOptions {
     prompt: string;
     mode?: string;
     model?: string;
-    /** Cloud backend crabbox provisions on (hetzner/aws/do/…). */
     backend?: string;
     boxClass?: string;
     profile?: string;
-    /** Per-run directory under ~/workspaces; isolates concurrent runs on one box. */
     workspaceId?: string;
-    /** 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;
-    /**
-     * 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
-     * (after consent) so this module stays free of Keychain I/O and unit-testable.
-     */
     claudeCredentialsJson?: string | null;
 }
 export interface LeaseDispatchProfile {
@@ -115,47 +52,17 @@ interface LeaseRunResult {
     exitCode: number | null;
     toreDown: boolean;
 }
-/**
- * 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 declare const LEASE_BOOTSTRAP_FAILED_CODE = 97;
-/** Build a shell-safe, collision-resistant workspace id for one lease run. */
 export declare function leaseWorkspaceId(repoRoot: string, startedAtMs?: number, pid?: number): string;
-/**
- * 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 declare function buildBootstrapScript(opts: LeaseRunOptions): string;
-/** Untouched-for-this-long ⇒ no active run holds the box, so an expired one is a stray. */
 export declare const STRAY_GRACE_SECS = 600;
 interface StrayMatchOptions {
-    /** Pool the lease belongs to (defaults to DEFAULT_CRABBOX_PROFILE). */
     profile?: string;
-    /** Network mode of the lease (default 'public'); a box is partitioned by it. */
     netMode?: 'public' | 'tailscale';
-    /** The box this run is using — never a stray. */
     keepSlug: string;
-    /** Injectable clock (unix seconds). */
     nowSecs?: number;
-    /** Idle grace window (defaults to {@link STRAY_GRACE_SECS}). */
     graceSecs?: number;
 }
-/**
- * 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 declare function isExpiredPoolStray(box: CrabboxBox, opts: StrayMatchOptions): boolean;
 export declare function leaseAndRun(opts: LeaseRunOptions): Promise<LeaseRunResult>;
 export {};