@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/dist/lib/browser/service.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { BrowserCdpConnectionError, CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity, } from './cdp.js';
-import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
+import { getProfile, getProfileRuntimeDir, getProfileDownloadsDir, getProfileSessionsDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
 import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
 import { connectLocal } from './drivers/local.js';
 import { connectSSH, shellQuote } from './drivers/ssh.js';
@@ -308,7 +308,9 @@ export class BrowserService {
         }
         else if (!conn) {
             conn = await this.connectProfile(effectiveProfile, resolved.target);
+            conn.profileName = composite;
             this.connections.set(composite, conn);
+            await this.applyDefaultDownloadBehavior(conn, composite);
         }
         // Browsers launch with --no-startup-window (session-cookie persistence,
         // see launchBrowser), so a bare `start` with no --url would otherwise
@@ -645,7 +647,7 @@ export class BrowserService {
         return result.result.value;
     }
     async screenshot(taskId, tabHint, outputPath, quality = 'compressed') {
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
         const target = await this.getTarget(conn, cdpTargetId);
@@ -678,7 +680,7 @@ export class BrowserService {
             }
             extension = 'jpg';
         }
-        const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
+        const sessionsDir = getProfileSessionsDir(profileName, task.name);
         const automaticPath = path.join(sessionsDir, `${Date.now()}.${extension}`);
         const finalPath = resolveScreenshotOutputPath(outputPath, automaticPath);
         await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
@@ -695,7 +697,7 @@ export class BrowserService {
      * — without it, dark-mode pages render on a blank sheet.
      */
     async printToPdf(taskId, tabHint, outputPath) {
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
         const target = await this.getTarget(conn, cdpTargetId);
@@ -705,7 +707,7 @@ export class BrowserService {
         const sessionId = await this.getSessionId(conn, target.targetId);
         const { data } = (await conn.cdp.send('Page.printToPDF', { printBackground: true, preferCSSPageSize: true }, sessionId));
         const buffer = Buffer.from(data, 'base64');
-        const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
+        const sessionsDir = getProfileSessionsDir(profileName, task.name);
         const automaticPath = path.join(sessionsDir, `${Date.now()}.pdf`);
         const finalPath = resolveScreenshotOutputPath(outputPath, automaticPath);
         await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
@@ -723,7 +725,7 @@ export class BrowserService {
         if (this.recordings.has(taskId)) {
             throw new Error(`Task "${taskId}" is already recording. Call record stop first.`);
         }
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
         const target = await this.getTarget(conn, cdpTargetId);
@@ -739,7 +741,7 @@ export class BrowserService {
             throw new Error('--duration must be between 1 and 3600 seconds');
         if (maxMb < 1 || maxMb > 500)
             throw new Error('--max-mb must be between 1 and 500');
-        const recordingsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name, 'recordings');
+        const recordingsDir = path.join(getProfileSessionsDir(profileName, task.name), 'recordings');
         await fs.promises.mkdir(recordingsDir, { recursive: true });
         const outputPath = path.join(recordingsDir, `${Date.now()}.webm`);
         // Resolve ffmpeg lazily so non-recording paths don't pay the import cost.
@@ -1481,20 +1483,50 @@ export class BrowserService {
         throw new Error(`Wait condition "${type}:${value}" not met within ${timeout}ms`);
     }
     // ─── Downloads ───────────────────────────────────────────────────────────────
+    /**
+     * Point the browser's default download destination at the profile's downloads
+     * dir, browser-global, at connect time. Without this a download the agent never
+     * explicitly routed (`browser download --path`) falls to Chromium's own default
+     * — for an attached user browser, wherever that browser was last configured,
+     * which is how downloads used to escape into random locations. Sent on the root
+     * session (no sessionId) so every current and future tab inherits it. Best
+     * effort: a remote CDP endpoint that doesn't expose the Browser domain must not
+     * fail the whole connect.
+     */
+    async applyDefaultDownloadBehavior(conn, profileName) {
+        const downloadPath = getProfileDownloadsDir(profileName);
+        try {
+            await fs.promises.mkdir(downloadPath, { recursive: true });
+            await conn.cdp.send('Browser.setDownloadBehavior', {
+                behavior: 'allow',
+                downloadPath,
+                eventsEnabled: true,
+            });
+        }
+        catch {
+            // Best effort: a remote CDP endpoint (ssh://, ws(s)://) may not expose the
+            // Browser domain. Downloads then keep the endpoint's own default; the connect
+            // must still succeed.
+        }
+    }
     async setDownloadPath(taskId, downloadPath, tabHint) {
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
         const target = await this.getTarget(conn, cdpTargetId);
         if (!target)
             throw new Error(`Tab ${shortId} not found`);
         const sessionId = await this.getSessionId(conn, target.targetId);
+        // No explicit --path: fall back to the profile's downloads dir, the same
+        // destination already set browser-global at connect (applyDefaultDownloadBehavior).
+        const resolvedPath = downloadPath ?? getProfileDownloadsDir(profileName);
+        await fs.promises.mkdir(resolvedPath, { recursive: true });
         await conn.cdp.send('Browser.setDownloadBehavior', {
             behavior: 'allow',
-            downloadPath,
+            downloadPath: resolvedPath,
             eventsEnabled: true,
         }, sessionId);
-        this.pendingDownloads.set(taskId, { path: downloadPath, completed: false });
+        this.pendingDownloads.set(taskId, { path: resolvedPath, completed: false });
         conn.cdp.on('Browser.downloadProgress', (params) => {
             if (params.state === 'completed') {
                 const dl = this.pendingDownloads.get(taskId);
@@ -1504,6 +1536,7 @@ export class BrowserService {
                 }
             }
         });
+        return resolvedPath;
     }
     async waitForDownload(taskId, timeout = 60000) {
         const start = Date.now();
@@ -1590,11 +1623,13 @@ export class BrowserService {
             pid,
             electron: true,
             targetFilter: profile.targetFilter,
+            profileName: forkName,
             forkedFrom: profile.name,
             tasks: new Map(),
             sessionCache: new Map(),
         };
         this.connections.set(forkName, connection);
+        await this.applyDefaultDownloadBehavior(connection, forkName);
         return { forkName, connection };
     }
     /**
@@ -1776,12 +1811,12 @@ export class BrowserService {
             if (!task) {
                 throw new Error(`Task "${taskId}" not found on profile "${profileName}"`);
             }
-            return { conn, task };
+            return { conn, task, profileName };
         }
-        for (const [, conn] of this.connections) {
+        for (const [key, conn] of this.connections) {
             const task = conn.tasks.get(taskId);
             if (task) {
-                return { conn, task };
+                return { conn, task, profileName: conn.profileName ?? key };
             }
         }
         throw new Error(`Task "${taskId}" not found`);

package/dist/lib/browser/sessions-list.d.ts

@@ -0,0 +1,40 @@
+export type ArtifactKind = 'screenshot' | 'pdf' | 'recording' | 'download';
+export interface BrowserArtifact {
+    kind: ArtifactKind;
+    /** Owning task for session captures; undefined for downloads. */
+    task?: string;
+    name: string;
+    path: string;
+    bytes: number;
+    mtimeMs: number;
+}
+export interface ProfileArtifacts {
+    profile: string;
+    artifacts: BrowserArtifact[];
+}
+/** Every capture for one profile, newest first. */
+export declare function listProfileArtifacts(profile: string): BrowserArtifact[];
+/**
+ * Captures grouped by profile. With `only` set, returns just that profile (even
+ * when empty); otherwise every profile dir on disk that has at least one capture.
+ */
+export declare function listBrowserSessions(only?: string): ProfileArtifacts[];
+/** Human table for the CLI. Returns lines (no trailing newline). */
+export declare function renderBrowserSessions(groups: ProfileArtifacts[]): string;
+/**
+ * Resolve `--open <sel>`: `latest` (newest across the groups) or a filename
+ * substring match. Returns the absolute path, or null if nothing matched.
+ */
+export declare function resolveArtifact(groups: ProfileArtifacts[], selector: string): string | null;
+/** Open a file in the OS default app. Returns true on success. */
+export declare function openArtifact(filePath: string): boolean;
+/**
+ * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
+ * `open` is the Commander value for `--open [selector]`: undefined when the flag
+ * is absent, `true` when passed bare (defaults to 'latest'), or the selector string.
+ */
+export declare function runBrowserSessions(opts: {
+    profile?: string;
+    open?: string | boolean;
+    json?: boolean;
+}): void;

package/dist/lib/browser/sessions-list.js

@@ -0,0 +1,190 @@
+/**
+ * Read-only listing of a browser profile's on-disk captures — screenshots, PDFs,
+ * recordings (`<profile>/sessions/<task>/`) and downloads (`<profile>/downloads/`).
+ * Reads straight from `.cache/browser/<profile>/`, so it works whether or not the
+ * browser daemon is running. Backs both `agents browser sessions` and the
+ * `agents sessions --browser` alias.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { getBrowserRuntimeDir, getProfileRuntimeDir } from './profiles.js';
+import { formatRelativeTime } from '../session/relative-time.js';
+const EXT_KIND = {
+    '.png': 'screenshot',
+    '.jpg': 'screenshot',
+    '.jpeg': 'screenshot',
+    '.webp': 'screenshot',
+    '.pdf': 'pdf',
+    '.webm': 'recording',
+};
+function statSafe(p) {
+    try {
+        return fs.statSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+function walkFiles(dir) {
+    let out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            out = out.concat(walkFiles(full));
+        else if (e.isFile())
+            out.push(full);
+    }
+    return out;
+}
+/** Every capture for one profile, newest first. */
+export function listProfileArtifacts(profile) {
+    const root = getProfileRuntimeDir(profile);
+    const artifacts = [];
+    const sessionsRoot = path.join(root, 'sessions');
+    let taskDirs = [];
+    try {
+        taskDirs = fs.readdirSync(sessionsRoot, { withFileTypes: true });
+    }
+    catch { /* none */ }
+    for (const t of taskDirs) {
+        if (!t.isDirectory())
+            continue;
+        for (const file of walkFiles(path.join(sessionsRoot, t.name))) {
+            const kind = EXT_KIND[path.extname(file).toLowerCase()];
+            if (!kind)
+                continue;
+            const st = statSafe(file);
+            if (!st)
+                continue;
+            artifacts.push({ kind, task: t.name, name: path.basename(file), path: file, bytes: st.size, mtimeMs: st.mtimeMs });
+        }
+    }
+    for (const file of walkFiles(path.join(root, 'downloads'))) {
+        const st = statSafe(file);
+        if (!st)
+            continue;
+        artifacts.push({ kind: 'download', name: path.basename(file), path: file, bytes: st.size, mtimeMs: st.mtimeMs });
+    }
+    artifacts.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return artifacts;
+}
+/**
+ * Captures grouped by profile. With `only` set, returns just that profile (even
+ * when empty); otherwise every profile dir on disk that has at least one capture.
+ */
+export function listBrowserSessions(only) {
+    let profiles;
+    if (only) {
+        profiles = [only];
+    }
+    else {
+        try {
+            profiles = fs.readdirSync(getBrowserRuntimeDir(), { withFileTypes: true })
+                .filter((e) => e.isDirectory() && e.name !== 'sessions')
+                .map((e) => e.name)
+                .sort();
+        }
+        catch {
+            profiles = [];
+        }
+    }
+    return profiles
+        .map((p) => ({ profile: p, artifacts: listProfileArtifacts(p) }))
+        .filter((r) => !!only || r.artifacts.length > 0);
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let val = n / 1024;
+    let i = 0;
+    while (val >= 1024 && i < units.length - 1) {
+        val /= 1024;
+        i++;
+    }
+    return `${val < 10 ? val.toFixed(1) : Math.round(val)} ${units[i]}`;
+}
+/** Human table for the CLI. Returns lines (no trailing newline). */
+export function renderBrowserSessions(groups) {
+    if (groups.length === 0)
+        return 'No browser profiles found.';
+    const lines = [];
+    for (const g of groups) {
+        const counts = { screenshot: 0, pdf: 0, recording: 0, download: 0 };
+        for (const a of g.artifacts)
+            counts[a.kind]++;
+        lines.push(`${g.profile}  ` +
+            `screenshots ${counts.screenshot}  pdfs ${counts.pdf}  recordings ${counts.recording}  downloads ${counts.download}`);
+        if (g.artifacts.length === 0) {
+            lines.push('  (no captures yet)');
+            continue;
+        }
+        for (const a of g.artifacts) {
+            const when = formatRelativeTime(new Date(a.mtimeMs).toISOString());
+            const where = a.kind === 'download' ? 'downloads/' : `sessions/${a.task}/`;
+            lines.push(`  ${when.padEnd(12)}  ${a.name.padEnd(28)}  ${formatBytes(a.bytes).padStart(8)}  ${where}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Resolve `--open <sel>`: `latest` (newest across the groups) or a filename
+ * substring match. Returns the absolute path, or null if nothing matched.
+ */
+export function resolveArtifact(groups, selector) {
+    const all = groups.flatMap((g) => g.artifacts).sort((a, b) => b.mtimeMs - a.mtimeMs);
+    if (all.length === 0)
+        return null;
+    if (selector === 'latest')
+        return all[0].path;
+    const hit = all.find((a) => a.name === selector) ?? all.find((a) => a.name.includes(selector));
+    return hit ? hit.path : null;
+}
+/** Open a file in the OS default app. Returns true on success. */
+export function openArtifact(filePath) {
+    const openers = process.platform === 'darwin'
+        ? [['open', [filePath]]]
+        : process.platform === 'win32'
+            ? [['cmd', ['/c', 'start', '""', filePath]]]
+            : [['xdg-open', [filePath]], ['gnome-open', [filePath]]];
+    for (const [cmd, args] of openers) {
+        if (spawnSync(cmd, args, { stdio: 'ignore' }).status === 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
+ * `open` is the Commander value for `--open [selector]`: undefined when the flag
+ * is absent, `true` when passed bare (defaults to 'latest'), or the selector string.
+ */
+export function runBrowserSessions(opts) {
+    const groups = listBrowserSessions(opts.profile);
+    if (opts.open !== undefined && opts.open !== false) {
+        const selector = opts.open === true ? 'latest' : opts.open;
+        const target = resolveArtifact(groups, selector);
+        if (!target) {
+            console.error(`No capture matching "${selector}".`);
+            process.exit(1);
+        }
+        console.log(target);
+        if (!openArtifact(target)) {
+            console.error(`Could not open ${target}`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(groups, null, 2));
+        return;
+    }
+    console.log(renderBrowserSessions(groups));
+}

package/dist/lib/comms-render.d.ts

@@ -0,0 +1,37 @@
+import type { CommsMsg } from './mailbox.js';
+export type { CommsMsg } from './mailbox.js';
+export declare const GLYPH: {
+    readonly live: "●";
+    readonly idle: "○";
+    readonly ask: "▲";
+    readonly delivered: "✓";
+    readonly pending: "⏳";
+    readonly route: "→";
+    readonly stream: "─→";
+    readonly thread: "⇄";
+};
+export type Accent = 'cyan' | 'amber';
+/** Render the shared one-line comms header, with `right` aligned to the terminal edge. */
+export declare function masthead(o: {
+    title: string;
+    host: string;
+    accent: Accent;
+    right?: string;
+    stats?: string[];
+}): string;
+/** Normalize non-negative counts across the eight Unicode sparkline levels. */
+export declare function sparkline(counts: number[]): string;
+/** Flatten mailbox histories into one newest-first communication stream. */
+export declare function aggregate(boxes: {
+    id: string;
+    label: string;
+    messages: import('./mailbox.js').StoredMessage[];
+}[]): CommsMsg[];
+/** Count messages in rolling one-hour buckets, ordered oldest to newest. */
+export declare function hourlyCounts(msgs: CommsMsg[], hours: number, now?: Date): number[];
+/** Aggregate the human-readable sender-to-recipient routes, busiest first. */
+export declare function graphEdges(msgs: CommsMsg[]): {
+    from: string;
+    to: string;
+    count: number;
+}[];

package/dist/lib/comms-render.js

@@ -0,0 +1,89 @@
+import chalk from 'chalk';
+import { stringWidth, terminalWidth } from './session/width.js';
+export const GLYPH = {
+    live: '●',
+    idle: '○',
+    ask: '▲',
+    delivered: '✓',
+    pending: '⏳',
+    route: '→',
+    stream: '─→',
+    thread: '⇄',
+};
+/** Render the shared one-line comms header, with `right` aligned to the terminal edge. */
+export function masthead(o) {
+    const accent = o.accent === 'cyan' ? chalk.cyan : chalk.yellow;
+    const title = `${accent('⌁')} ${chalk.bold(accent(o.title))}`;
+    const host = chalk.dim(` · ${o.host}`);
+    const stats = o.stats?.length ? `   ${o.stats.join(chalk.dim(' · '))}` : '';
+    const left = `${title}${host}${stats}`;
+    if (!o.right)
+        return left;
+    const right = chalk.dim(o.right);
+    const gap = Math.max(1, terminalWidth() - stringWidth(left) - stringWidth(right));
+    return `${left}${' '.repeat(gap)}${right}`;
+}
+const SPARK_LEVELS = '▁▂▃▄▅▆▇█';
+/** Normalize non-negative counts across the eight Unicode sparkline levels. */
+export function sparkline(counts) {
+    if (counts.length === 0)
+        return ' ';
+    const normalized = counts.map((count) => Number.isFinite(count) ? Math.max(0, count) : 0);
+    const max = Math.max(...normalized);
+    if (max === 0)
+        return ' '.repeat(counts.length);
+    return normalized
+        .map((count) => SPARK_LEVELS[Math.round((count / max) * (SPARK_LEVELS.length - 1))])
+        .join('');
+}
+/** Flatten mailbox histories into one newest-first communication stream. */
+export function aggregate(boxes) {
+    return boxes
+        .flatMap((box) => {
+        const toLabel = box.label || box.id.slice(0, 8);
+        return box.messages.map((message) => ({
+            from: message.from || 'operator',
+            to: message.to,
+            toLabel,
+            ts: message.ts,
+            text: message.text,
+            state: message.state,
+            box: box.id,
+        }));
+    })
+        .sort((a, b) => compareText(b.ts, a.ts));
+}
+const HOUR_MS = 60 * 60 * 1_000;
+/** Count messages in rolling one-hour buckets, ordered oldest to newest. */
+export function hourlyCounts(msgs, hours, now = new Date()) {
+    const bucketCount = Number.isFinite(hours) ? Math.max(0, Math.floor(hours)) : 0;
+    const counts = Array.from({ length: bucketCount }, () => 0);
+    const nowMs = now.getTime();
+    if (bucketCount === 0 || !Number.isFinite(nowMs))
+        return counts;
+    for (const message of msgs) {
+        const timestamp = Date.parse(message.ts);
+        const age = nowMs - timestamp;
+        if (!Number.isFinite(timestamp) || age < 0 || age >= bucketCount * HOUR_MS)
+            continue;
+        const bucket = bucketCount - 1 - Math.floor(age / HOUR_MS);
+        counts[bucket]++;
+    }
+    return counts;
+}
+/** Aggregate the human-readable sender-to-recipient routes, busiest first. */
+export function graphEdges(msgs) {
+    const edges = new Map();
+    for (const message of msgs) {
+        const key = JSON.stringify([message.from, message.toLabel]);
+        const existing = edges.get(key);
+        if (existing)
+            existing.count++;
+        else
+            edges.set(key, { from: message.from, to: message.toLabel, count: 1 });
+    }
+    return [...edges.values()].sort((a, b) => b.count - a.count || compareText(a.from, b.from) || compareText(a.to, b.to));
+}
+function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

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

@@ -11,6 +11,7 @@
  * 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 { type SecretsBundle } from '../secrets/bundles.js';
 /** A crabbox machine as reported by `crabbox list --json`. */
 export interface CrabboxBox {
     /** Provider machine name, e.g. `crabbox-blue-hermit-1039689b`. */
@@ -29,6 +30,16 @@ export interface CrabboxBox {
     class?: string;
     /** True when running + bootstrap-complete. */
     ready: boolean;
+    /** crabbox `keep` label — a kept box survives `crabbox cleanup` past its TTL. */
+    keep: boolean;
+    /** Unix seconds the box was created, or null when the label is absent. */
+    createdAt: number | null;
+    /** Unix seconds the lease expires, or null. */
+    expiresAt: number | null;
+    /** Unix seconds the box was last touched (reused / run against), or null. */
+    lastTouchedAt: number | null;
+    /** Idle-timeout window in seconds, or null. */
+    idleTimeoutSecs: number | null;
 }
 export interface CrabboxOptions {
     /**
@@ -41,6 +52,38 @@ export interface CrabboxOptions {
 }
 /** Locate the crabbox binary, or throw an actionable error. */
 export declare function findCrabbox(): string;
+/**
+ * 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.
+ */
+export declare const LEASE_PROVIDER_TOKEN_KEYS: string[];
+/** The first bundle that declares a provider token key, or undefined. Pure over `bundles`. */
+export declare function pickLeaseBundleFromList(bundles: SecretsBundle[]): string | undefined;
+/** A resolved lease bundle: its name, plus (auto-detect only) the exact keys to inject. */
+export interface ResolvedLeaseBundle {
+    name: string;
+    /** When set (auto-detect), inject ONLY these keys — not the whole bundle. */
+    keys?: string[];
+}
+/**
+ * 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 declare function resolveLeaseBundle(): ResolvedLeaseBundle | undefined;
+/** Persist `lease.secretsBundle` in agents config so `--lease` needs no env var. */
+export declare function setLeaseSecretsBundle(name: string): void;
 /** Build the child env for crabbox, injecting a secrets bundle when configured. */
 export declare function crabboxEnv(opts: CrabboxOptions): NodeJS.ProcessEnv;
 /** All crabbox machines the broker knows about. */
@@ -96,3 +139,32 @@ export declare function crabboxRun(slug: string, remoteCmd: string, opts?: Crabb
 export declare function crabboxRunScript(slug: string, script: string, opts?: CrabboxRunOptions): Promise<number | null>;
 /** Release the lease / delete the box. Best-effort; never throws. */
 export declare function crabboxStop(slug: string, opts?: CrabboxOptions): boolean;
+/** Never reap a box touched within this many seconds, regardless of idle-timeout. */
+export declare 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 declare function isReapSafe(box: CrabboxBox, nowSecs: number): boolean;
+/** The reap-safe orphans among `boxes`, most-stale (oldest touch) first. */
+export declare function reapSafeOrphans(boxes: CrabboxBox[], nowSecs: number): CrabboxBox[];
+/**
+ * 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 lease gc` and the 403 auto-reap opt-in.
+ */
+export declare function reapOrphans(opts?: CrabboxOptions & {
+    nowSecs?: number;
+    dryRun?: boolean;
+}): {
+    candidates: CrabboxBox[];
+    reaped: string[];
+};