@phnx-labs/agents-cli 1.22.24 → 1.22.26

package/dist/lib/browser/stream.js

@@ -0,0 +1,71 @@
+import { createInterface } from 'readline';
+import { connectBrowserIPC } from './ipc.js';
+import { assertRemoteControlAllowed } from './remote-control.js';
+function parseRequest(line) {
+    const parsed = JSON.parse(line);
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        Array.isArray(parsed) ||
+        typeof parsed.action !== 'string') {
+        throw new Error('Each input line must be a JSON object with an action');
+    }
+    return parsed;
+}
+function writeResponse(output, response) {
+    output.write(`${JSON.stringify(response)}\n`);
+}
+function writeErrorResponse(output, error) {
+    writeResponse(output, {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+    });
+}
+/**
+ * Read browser IPC requests as NDJSON and write one NDJSON response per line.
+ * The Node process and daemon connection stay alive until input closes.
+ */
+export async function runBrowserIPCStream(options) {
+    const client = await connectBrowserIPC({ autoStartDaemon: options.autoStartDaemon });
+    const lines = createInterface({ input: options.input, crlfDelay: Infinity });
+    let defaultTask = options.task;
+    try {
+        for await (const line of lines) {
+            if (!line.trim())
+                continue;
+            let request;
+            try {
+                request = parseRequest(line);
+            }
+            catch (error) {
+                writeErrorResponse(options.output, error);
+                continue;
+            }
+            if (request.action === 'start') {
+                try {
+                    assertRemoteControlAllowed();
+                }
+                catch (error) {
+                    writeErrorResponse(options.output, error);
+                    continue;
+                }
+                request = {
+                    ...request,
+                    taskName: request.taskName ?? defaultTask,
+                    actor: request.actor ?? options.actor,
+                    launchId: request.launchId ?? options.launchId,
+                };
+            }
+            else if (!request.task && defaultTask) {
+                request = { ...request, task: defaultTask };
+            }
+            const response = await client.request(request);
+            if (response.task)
+                defaultTask = response.task;
+            writeResponse(options.output, response);
+        }
+    }
+    finally {
+        lines.close();
+        await client.close();
+    }
+}

package/dist/lib/channels/owner-sink.d.ts

@@ -0,0 +1,27 @@
+import type { Meta } from '../types.js';
+/** Why the owner sink cannot deliver from this box. */
+export type OwnerSinkReason = 'rush-not-on-path' | 'rush-signed-out';
+export interface OwnerSinkStatus {
+    /** Owner delivery is configured for this fleet (humans.yaml / notify.owner).
+     *  When false, no finding is emitted — an un-opted-in box is not "broken". */
+    configured: boolean;
+    /** This box can actually deliver an owner notification right now. */
+    reachable: boolean;
+    /** Resolved owner channel (e.g. `imessage`). */
+    channel?: string;
+    /** Resolved transport after `notify.transports` mapping (usually === channel). */
+    transport?: string;
+    /** Set only when `reachable` is false. */
+    reason?: OwnerSinkReason;
+}
+/**
+ * Probe whether THIS box can deliver an owner notification right now. Returns
+ * `configured:false` (and the caller emits no finding) when the fleet has no
+ * owner channel configured — an un-opted-in box is not broken. When configured,
+ * reports whether the resolved transport can actually deliver from here.
+ *
+ * Only the concrete rush-backed failure the lane hits is reported as unreachable;
+ * non-rush transports (desktop / mailbox / …) deliver locally and are treated as
+ * reachable rather than probed, so this never invents a critical it cannot back.
+ */
+export declare function probeOwnerSink(meta: Meta): Promise<OwnerSinkStatus>;

package/dist/lib/channels/owner-sink.js

@@ -0,0 +1,93 @@
+/**
+ * Owner-delivery-sink reachability probe (RUSH-2262).
+ *
+ * The feed/notify owner-delivery lane (`agents notify`, `agents feed post
+ * --level important` / `--blocked`) reaches the owner over the rush-backed owner
+ * channel (iMessage via `rush message send`). That transport can only deliver
+ * from a context that BOTH finds the `rush` CLI on PATH and can read its
+ * keychain-bound session. So a headless Linux fleet box (no rush) or a non-GUI
+ * SSH session on a mac (login keychain locked) structurally cannot escalate —
+ * and the failure is silent until a block is filed, surfacing only as the
+ * after-the-fact `owner failed: …` line. `agents doctor` had no signal for it,
+ * which is exactly the gap RUSH-2258 / RUSH-2262 flagged.
+ *
+ * This probes the SAME transport the lane uses, from the SAME context doctor runs
+ * in, so `agents doctor` can fail loud when this box cannot reach the owner. It is
+ * deliberately honest about context: `rush whoami` is what tells a real signed-in
+ * session apart from a keychain that is present but unreadable HERE. The session
+ * token is a keychain item, NOT `~/.rush/user.yaml` (RUSH-2262), so this never
+ * reads that file — checking it is the mistake that made a signed-in box look
+ * signed out.
+ *
+ * `agents notify --dry-run` is NOT this probe: it short-circuits before the
+ * `which rush` preflight (`providers/rush.ts`), so it reports `ok:true` on a box
+ * with no rush at all. Resolvability (does the envelope build?) and reachability
+ * (can this box actually deliver?) are different questions; this answers the
+ * second.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { readOwnerDest } from './send.js';
+import { RUSH_CHANNELS } from './providers/rush.js';
+const execFileAsync = promisify(execFile);
+async function rushOnPath() {
+    try {
+        await execFileAsync('which', ['rush'], { timeout: 4000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Signed-in state from `rush whoami`, read with THIS context's keychain access.
+ *  'unknown' (a timeout or output we can't classify) is treated as reachable by
+ *  the caller — a slow or unexpected probe must not cry wolf and paint a false
+ *  critical. Only a definitive "not logged in" is reported as signed out. */
+async function rushSignedIn() {
+    const classify = (s) => {
+        const out = s.toLowerCase();
+        if (/not (logged in|signed in)/.test(out))
+            return 'no';
+        if (/logged in as|session:\s*valid/.test(out))
+            return 'yes';
+        return 'unknown';
+    };
+    try {
+        const { stdout, stderr } = await execFileAsync('rush', ['whoami'], { timeout: 5000 });
+        return classify(`${stdout}\n${stderr}`);
+    }
+    catch (err) {
+        const e = err;
+        if (e.killed)
+            return 'unknown'; // timed out — do not conclude signed-out
+        // A signed-out rush commonly exits non-zero; trust an explicit message only.
+        return classify(`${e.stdout ?? ''}\n${e.stderr ?? ''}`);
+    }
+}
+/**
+ * Probe whether THIS box can deliver an owner notification right now. Returns
+ * `configured:false` (and the caller emits no finding) when the fleet has no
+ * owner channel configured — an un-opted-in box is not broken. When configured,
+ * reports whether the resolved transport can actually deliver from here.
+ *
+ * Only the concrete rush-backed failure the lane hits is reported as unreachable;
+ * non-rush transports (desktop / mailbox / …) deliver locally and are treated as
+ * reachable rather than probed, so this never invents a critical it cannot back.
+ */
+export async function probeOwnerSink(meta) {
+    const dest = readOwnerDest(meta);
+    if (!dest)
+        return { configured: false, reachable: false };
+    const channel = dest.channel;
+    const transport = meta.notify?.transports?.[channel] ?? channel;
+    if (RUSH_CHANNELS.includes(transport)) {
+        if (!(await rushOnPath())) {
+            return { configured: true, reachable: false, channel, transport, reason: 'rush-not-on-path' };
+        }
+        if ((await rushSignedIn()) === 'no') {
+            return { configured: true, reachable: false, channel, transport, reason: 'rush-signed-out' };
+        }
+        return { configured: true, reachable: true, channel, transport };
+    }
+    return { configured: true, reachable: true, channel, transport };
+}

package/dist/lib/cloud/cursor.d.ts

@@ -0,0 +1,79 @@
+/** Cursor Cloud Agents provider backed by the public v1 REST API. */
+import type { CloudEvent, CloudProvider, CloudTask, CloudTaskStatus, DispatchOptions, ProviderCapabilities } from './types.js';
+export declare const CURSOR_API_BASE_URL = "https://api.cursor.com/v1";
+interface CursorAgent {
+    id: string;
+    name?: string;
+    status: 'ACTIVE' | 'ARCHIVED';
+    createdAt: string;
+    updatedAt: string;
+    latestRunId?: string;
+    repos?: Array<{
+        url: string;
+        startingRef?: string;
+        prUrl?: string;
+    }>;
+}
+interface CursorRun {
+    id: string;
+    agentId: string;
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+    result?: string;
+    git?: {
+        branches?: Array<{
+            repoUrl: string;
+            branch?: string;
+            prUrl?: string;
+        }>;
+    };
+}
+export interface CursorCreateBody {
+    prompt: {
+        text: string;
+        images?: Array<{
+            data: string;
+            mimeType: string;
+        }>;
+    };
+    model?: {
+        id: string;
+    };
+    repos?: Array<{
+        url: string;
+        startingRef?: string;
+    }>;
+    autoCreatePR?: boolean;
+    envVars?: Record<string, string>;
+}
+/** Translate unified dispatch options into Cursor's documented v1 create shape. */
+export declare function buildCursorCreateBody(options: DispatchOptions): CursorCreateBody;
+/** Map one Cursor agent/run pair into the provider-neutral task shape. */
+export declare function parseCursorTask(agent: CursorAgent, run: CursorRun, prompt?: string): CloudTask;
+/** Parse one complete SSE frame into a shared cloud event. */
+export declare function parseCursorSseFrame(frame: string): CloudEvent | undefined;
+/** Turn Cursor's structured API errors into actionable provider errors. */
+export declare function cursorApiError(action: string, status: number, text: string): Error;
+export declare class CursorCloudProvider implements CloudProvider {
+    id: "cursor";
+    name: string;
+    private secretsBundle?;
+    constructor(config?: {
+        secretsBundle?: string;
+    });
+    private hasKeySource;
+    private resolveApiKey;
+    capabilities(): ProviderCapabilities;
+    private request;
+    private latestRun;
+    dispatch(options: DispatchOptions): Promise<CloudTask>;
+    status(taskId: string): Promise<CloudTask>;
+    list(filter?: {
+        status?: CloudTaskStatus;
+    }): Promise<CloudTask[]>;
+    stream(taskId: string): AsyncIterable<CloudEvent>;
+    cancel(taskId: string): Promise<void>;
+    message(taskId: string, content: string): Promise<void>;
+}
+export {};

package/dist/lib/cloud/cursor.js

@@ -0,0 +1,228 @@
+/** Cursor Cloud Agents provider backed by the public v1 REST API. */
+import { normalizeProviderStatus, resolveDispatchRepos } from './types.js';
+import { readAndResolveBundleEnv } from '../secrets/bundles.js';
+export const CURSOR_API_BASE_URL = 'https://api.cursor.com/v1';
+const KEY_NAME = 'CURSOR_API_KEY';
+/** Translate unified dispatch options into Cursor's documented v1 create shape. */
+export function buildCursorCreateBody(options) {
+    const repos = resolveDispatchRepos(options);
+    const body = { prompt: { text: options.prompt } };
+    if (options.images?.length) {
+        body.prompt.images = options.images.map(({ data, mimeType }) => ({ data, mimeType }));
+    }
+    if (options.model)
+        body.model = { id: options.model };
+    if (repos.length) {
+        body.repos = repos.map((url) => ({ url, ...(options.branch ? { startingRef: options.branch } : {}) }));
+        body.autoCreatePR = true;
+    }
+    if (options.env && Object.keys(options.env).length)
+        body.envVars = options.env;
+    return body;
+}
+/** Map one Cursor agent/run pair into the provider-neutral task shape. */
+export function parseCursorTask(agent, run, prompt = '') {
+    const branch = run.git?.branches?.[0];
+    return {
+        id: agent.id,
+        provider: 'cursor',
+        status: normalizeProviderStatus('cursor', run.status),
+        agent: 'cursor',
+        prompt: prompt || agent.name || '',
+        repo: agent.repos?.[0]?.url,
+        repos: agent.repos?.map((repo) => repo.url),
+        branch: branch?.branch,
+        prUrl: branch?.prUrl,
+        createdAt: agent.createdAt,
+        updatedAt: run.updatedAt,
+        summary: run.result,
+    };
+}
+/** Parse one complete SSE frame into a shared cloud event. */
+export function parseCursorSseFrame(frame) {
+    let eventName = 'message';
+    const data = [];
+    for (const line of frame.split(/\r?\n/)) {
+        if (line.startsWith('event:'))
+            eventName = line.slice(6).trim();
+        else if (line.startsWith('data:'))
+            data.push(line.slice(5).trimStart());
+    }
+    if (!data.length)
+        return undefined;
+    const raw = data.join('\n');
+    let value = raw;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch { /* Cursor may send plain text. */ }
+    const obj = typeof value === 'object' && value !== null ? value : {};
+    const timestamp = typeof obj.timestamp === 'string' ? obj.timestamp : undefined;
+    if (eventName === 'status') {
+        const status = String(obj.status ?? obj.data ?? raw);
+        return { type: 'status', status: normalizeProviderStatus('cursor', status), timestamp };
+    }
+    if (eventName === 'assistant') {
+        return { type: 'text', content: String(obj.text ?? obj.content ?? obj.data ?? raw), timestamp };
+    }
+    if (eventName === 'thinking') {
+        return { type: 'thinking', content: String(obj.text ?? obj.content ?? obj.data ?? raw), timestamp };
+    }
+    if (eventName === 'tool_call') {
+        if (obj.status === 'completed') {
+            return { type: 'tool_result', tool: String(obj.name ?? 'tool'), output: obj.result ?? obj, timestamp };
+        }
+        return { type: 'tool_use', tool: String(obj.name ?? 'tool'), input: obj.args ?? obj, timestamp };
+    }
+    if (eventName === 'result' || eventName === 'done') {
+        const status = normalizeProviderStatus('cursor', String(obj.status ?? 'FINISHED'));
+        return { type: 'done', status, summary: typeof obj.text === 'string' ? obj.text : undefined, timestamp };
+    }
+    if (eventName === 'error') {
+        return { type: 'error', message: String(obj.message ?? raw), timestamp };
+    }
+    return { type: 'unknown', name: eventName, data: raw, timestamp };
+}
+/** Turn Cursor's structured API errors into actionable provider errors. */
+export function cursorApiError(action, status, text) {
+    let parsed = {};
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch { /* preserve raw body */ }
+    const detail = typeof parsed.error === 'object' ? parsed.error : undefined;
+    const code = detail?.code;
+    const message = detail?.message ?? (typeof parsed.error === 'string' ? parsed.error : text.slice(0, 500));
+    if (code === 'plan_required') {
+        return new Error(`Cursor Cloud Agents requires a paid Cursor plan; this API key belongs to a plan without Cloud Agents access. ${message}`);
+    }
+    if (status === 401 || code === 'unauthorized' || code === 'api_key_not_found') {
+        return new Error(`Cursor Cloud authentication failed (${status}${code ? ` ${code}` : ''}). Check CURSOR_API_KEY in the configured agents secrets bundle. ${message}`);
+    }
+    return new Error(`Cursor Cloud ${action} failed (${status}${code ? ` ${code}` : ''}): ${message}`);
+}
+export class CursorCloudProvider {
+    id = 'cursor';
+    name = 'Cursor Cloud Agents';
+    secretsBundle;
+    constructor(config) {
+        this.secretsBundle = config?.secretsBundle;
+    }
+    hasKeySource() {
+        return Boolean(this.secretsBundle || process.env[KEY_NAME]);
+    }
+    resolveApiKey() {
+        if (this.secretsBundle) {
+            try {
+                const { env } = readAndResolveBundleEnv(this.secretsBundle, { caller: 'cloud:cursor', agentOnly: true });
+                if (env[KEY_NAME])
+                    return env[KEY_NAME];
+                throw new Error(`Secrets bundle '${this.secretsBundle}' has no ${KEY_NAME}. Add one: agents secrets add ${this.secretsBundle} ${KEY_NAME}`);
+            }
+            catch (err) {
+                throw new Error(`Could not read Cursor API key from bundle '${this.secretsBundle}': ${err.message}`);
+            }
+        }
+        if (process.env[KEY_NAME])
+            return process.env[KEY_NAME];
+        throw new Error(`Cursor cloud needs an API key. Set cloud.providers.cursor.secretsBundle in ~/.agents/agents.yaml after running: agents secrets add cursor ${KEY_NAME}`);
+    }
+    capabilities() {
+        const available = this.hasKeySource();
+        return {
+            available,
+            dispatch: available,
+            status: available,
+            list: available,
+            stream: available,
+            cancel: available,
+            message: available,
+            multiRepo: true,
+            skills: false,
+            images: true,
+        };
+    }
+    async request(path, init) {
+        const apiKey = this.resolveApiKey();
+        let response;
+        try {
+            response = await fetch(`${CURSOR_API_BASE_URL}${path}`, {
+                ...init,
+                headers: {
+                    authorization: `Basic ${Buffer.from(`${apiKey}:`).toString('base64')}`,
+                    ...(init?.body ? { 'content-type': 'application/json' } : {}),
+                    ...init?.headers,
+                },
+            });
+        }
+        catch (err) {
+            throw new Error(`Cursor Cloud request failed (network): ${err.message}`);
+        }
+        if (!response.ok)
+            throw cursorApiError(init?.method ?? 'request', response.status, await response.text());
+        return response;
+    }
+    async latestRun(agent) {
+        if (!agent.latestRunId)
+            throw new Error(`Cursor Cloud agent ${agent.id} has no runs.`);
+        return this.request(`/agents/${encodeURIComponent(agent.id)}/runs/${encodeURIComponent(agent.latestRunId)}`)
+            .then((response) => response.json());
+    }
+    async dispatch(options) {
+        const response = await this.request('/agents', { method: 'POST', body: JSON.stringify(buildCursorCreateBody(options)) });
+        const payload = await response.json();
+        return parseCursorTask(payload.agent, payload.run, options.prompt);
+    }
+    async status(taskId) {
+        const agent = await this.request(`/agents/${encodeURIComponent(taskId)}`).then((response) => response.json());
+        return parseCursorTask(agent, await this.latestRun(agent));
+    }
+    async list(filter) {
+        const { items } = await this.request('/agents?limit=100').then((response) => response.json());
+        const tasks = await Promise.all(items.filter((agent) => agent.latestRunId).map(async (agent) => parseCursorTask(agent, await this.latestRun(agent))));
+        return filter?.status ? tasks.filter((task) => task.status === filter.status) : tasks;
+    }
+    async *stream(taskId) {
+        const agent = await this.request(`/agents/${encodeURIComponent(taskId)}`).then((response) => response.json());
+        if (!agent.latestRunId)
+            throw new Error(`Cursor Cloud agent ${taskId} has no run to stream.`);
+        const response = await this.request(`/agents/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(agent.latestRunId)}/stream`, {
+            headers: { accept: 'text/event-stream' },
+        });
+        if (!response.body)
+            throw new Error(`Cursor Cloud stream for ${taskId} returned no response body.`);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        while (true) {
+            const { done, value } = await reader.read();
+            buffer += decoder.decode(value, { stream: !done });
+            const frames = buffer.split(/\r?\n\r?\n/);
+            buffer = frames.pop() ?? '';
+            for (const frame of frames) {
+                const event = parseCursorSseFrame(frame);
+                if (event)
+                    yield event;
+            }
+            if (done)
+                break;
+        }
+        if (buffer.trim()) {
+            const event = parseCursorSseFrame(buffer);
+            if (event)
+                yield event;
+        }
+    }
+    async cancel(taskId) {
+        const agent = await this.request(`/agents/${encodeURIComponent(taskId)}`).then((response) => response.json());
+        if (!agent.latestRunId)
+            throw new Error(`Cursor Cloud agent ${taskId} has no run to cancel.`);
+        await this.request(`/agents/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(agent.latestRunId)}/cancel`, { method: 'POST' });
+    }
+    async message(taskId, content) {
+        await this.request(`/agents/${encodeURIComponent(taskId)}/runs`, {
+            method: 'POST',
+            body: JSON.stringify({ prompt: { text: content } }),
+        });
+    }
+}

package/dist/lib/cloud/registry.js

@@ -11,6 +11,7 @@ import { RushCloudProvider } from './rush.js';
 import { CodexCloudProvider } from './codex.js';
 import { FactoryCloudProvider } from './factory.js';
 import { AntigravityCloudProvider } from './antigravity.js';
+import { CursorCloudProvider } from './cursor.js';
 import { HostCloudProvider } from './host.js';
 import { getUserAgentsDir } from '../state.js';
 import { AGENTS } from '../agents.js';
@@ -44,6 +45,7 @@ function initProviders() {
     providers.set('codex', new CodexCloudProvider(config.providers?.codex));
     providers.set('factory', new FactoryCloudProvider(config.providers?.factory));
     providers.set('antigravity', new AntigravityCloudProvider(config.providers?.antigravity));
+    providers.set('cursor', new CursorCloudProvider(config.providers?.cursor));
     // Your own machines (agents hosts / agents devices) over SSH. No agent
     // auto-routes here — it's always an explicit --provider host / --host choice.
     providers.set('host', new HostCloudProvider());

package/dist/lib/cloud/types.d.ts

@@ -14,13 +14,14 @@ import type { JobTrigger } from '../routines.js';
  *   - `codex`       — OpenAI Codex Cloud (`codex cloud exec`)
  *   - `factory`     — Factory Droid Computers (`droid computer ssh` + remote `droid exec`)
  *   - `antigravity` — Google Gemini Managed Agents (Interactions API)
+ *   - `cursor`      — Cursor Cloud Agents REST API
  *   - `host`        — a machine you own (`agents hosts` / `agents devices`), over SSH
  *
  * Agents route to their native cloud automatically (see `cloudProvider` in the
  * agent registry); `--provider` overrides. Nothing auto-routes to `host` — it
  * is always an explicit `--provider host` (or `--host <name>`) choice.
  */
-export type CloudProviderId = 'rush' | 'codex' | 'factory' | 'antigravity' | 'host';
+export type CloudProviderId = 'rush' | 'codex' | 'factory' | 'antigravity' | 'cursor' | 'host';
 /**
  * Lifecycle state of a cloud-dispatched task.
  *
@@ -30,7 +31,7 @@ export type CloudProviderId = 'rush' | 'codex' | 'factory' | 'antigravity' | 'ho
  */
 export type CloudTaskStatus = 'queued' | 'allocating' | 'running' | 'idle' | 'input_required' | 'completed' | 'failed' | 'cancelled';
 /** Cloud backends whose wire status is normalized by `normalizeProviderStatus`. */
-export type StatusNormalizingProvider = 'rush' | 'codex' | 'antigravity';
+export type StatusNormalizingProvider = 'rush' | 'codex' | 'antigravity' | 'cursor';
 /**
  * Normalize a provider's raw wire status into the canonical `CloudTaskStatus`.
  *
@@ -302,6 +303,10 @@ export interface CloudProviderConfig {
         secretsBundle?: string;
         model?: string;
     };
+    /** Cursor Cloud Agents API. The API key remains in the named secrets bundle. */
+    cursor?: {
+        secretsBundle?: string;
+    };
 }
 /** Top-level `cloud` section of agents.yaml. */
 export interface CloudConfig {

package/dist/lib/cloud/types.js

@@ -31,6 +31,20 @@ export function normalizeProviderStatus(provider, wireStatus) {
             return normalizeCodexStatus(wireStatus ?? '');
         case 'antigravity':
             return normalizeAntigravityStatus(wireStatus);
+        case 'cursor':
+            return normalizeCursorStatus(wireStatus ?? '');
+    }
+}
+/** Cursor Cloud run status → canonical enum. Unknown non-terminal states remain running. */
+function normalizeCursorStatus(s) {
+    switch (s.toUpperCase()) {
+        case 'CREATING': return 'queued';
+        case 'RUNNING': return 'running';
+        case 'FINISHED': return 'completed';
+        case 'ERROR':
+        case 'EXPIRED': return 'failed';
+        case 'CANCELLED': return 'cancelled';
+        default: return 'running';
     }
 }
 /** Rush Factory Floor status → canonical enum. Default `running`; no `queued`. */

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

@@ -124,8 +124,8 @@ export declare function crabboxFind(slug: string, opts?: CrabboxOptions): Crabbo
 export declare function crabboxStatusReady(slug: string, opts?: CrabboxOptions): boolean;
 export interface PoolMatchOptions {
     /**
-     * Profile label this run would warm a box with (from the repo's
-     * `.crabbox.yaml`; see config.ts). Both sides normalize an unset profile to
+     * Lease pool label (shared default, or `.crabbox.yaml leaseProfile:` opt-in;
+     * see config.ts). Both sides normalize an unset profile to
      * DEFAULT_CRABBOX_PROFILE, so profile-less runs match unlabeled boxes.
      */
     profile?: string;

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

@@ -2,10 +2,9 @@
  * The repo-local crabbox config (`.crabbox.yaml` at the repo root).
  *
  * crabbox itself reads this file when warming a box (the `profile:` key becomes
- * the box's `profile` label). `agents run --lease` reads it too so the warm-pool
- * reuse check matches on the SAME profile the warmup would have used — a reused
- * box is then interchangeable with a fresh one (scripts/sandbox.sh's
- * `pick_ready_box` resolves the pool the same way).
+ * the 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
@@ -14,8 +13,8 @@
  */
 export declare const DEFAULT_CRABBOX_PROFILE = "default";
 /**
- * The `profile:` declared by `<repoRoot>/.crabbox.yaml`, or undefined when the
- * file is missing, unreadable, or has no profile key (crabbox then applies its
- * own default, which the pool matcher treats as DEFAULT_CRABBOX_PROFILE).
+ * 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 readCrabboxRepoProfile(repoRoot: string): string | undefined;
+export declare function readCrabboxLeaseProfile(repoRoot: string): string;

package/dist/lib/crabbox/config.js

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