@phnx-labs/agents-cli 1.22.23 → 1.22.25

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;
 }

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

@@ -3,10 +3,11 @@
  *
  * 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 warm profile pool (a ready box carrying
- * the run's profile + netMode labels is reused and kept; `--fresh` opts out and
- * always leases a new, torn-down box). The whole box-side sequence rides a
- * single `--script-stdin` body so the token contents never touch argv.
+ * 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:
@@ -54,6 +55,8 @@ export interface LeaseRunOptions {
     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`. */
@@ -112,6 +115,10 @@ export interface LeaseRunResult {
     exitCode: number | null;
     toreDown: boolean;
 }
+/** Build a shell-safe, collision-resistant workspace id for one lease run. */
+export declare function leaseWorkspaceId(repoRoot: string, startedAtMs?: number, pid?: number): string;
+/** Isolated box-home path for one run, relative to the shared box user's home. */
+export declare function leaseHomeDir(workspaceId: string): 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

package/dist/lib/crabbox/lease.js

@@ -3,10 +3,11 @@
  *
  * 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 warm profile pool (a ready box carrying
- * the run's profile + netMode labels is reused and kept; `--fresh` opts out and
- * always leases a new, torn-down box). The whole box-side sequence rides a
- * single `--script-stdin` body so the token contents never touch argv.
+ * 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:
@@ -38,6 +39,16 @@ import { DEFAULT_CRABBOX_PROFILE } from './config.js';
 function q(s) {
     return "'" + s.replace(/'/g, "'\\''") + "'";
 }
+/** Build a shell-safe, collision-resistant workspace id for one lease run. */
+export function leaseWorkspaceId(repoRoot, startedAtMs = Date.now(), pid = process.pid) {
+    const repo = repoRoot.split(/[\\/]/).filter(Boolean).pop() ?? 'repo';
+    const safeRepo = repo.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'repo';
+    return `${safeRepo}-${startedAtMs.toString(36)}-${pid.toString(36)}`;
+}
+/** Isolated box-home path for one run, relative to the shared box user's home. */
+export function leaseHomeDir(workspaceId) {
+    return `lease-homes/${workspaceId}`;
+}
 function profileRemotePath(name) {
     return `.agents/profiles/${name}.yml`;
 }
@@ -124,15 +135,35 @@ export function buildBootstrapScript(opts) {
     // them as a structured step stream — they never appear as setup noise.
     const step = (name) => `echo ${q(leasePhaseSentinel(name))}`;
     const copySetup = opts.copySetup !== false; // default TRUE
+    const workspace = opts.workspaceId
+        ? [
+            'BOX_HOME="$HOME"',
+            'REPO_DIR="$(pwd)"',
+            `WORKSPACE_DIR="$BOX_HOME"/${q(`workspaces/${opts.workspaceId}`)}`,
+            'mkdir -p "$WORKSPACE_DIR"',
+            'rsync -a --delete --exclude=node_modules --exclude=.agents/worktrees "$REPO_DIR/" "$WORKSPACE_DIR/"',
+            'cd "$WORKSPACE_DIR"',
+        ].join('\n')
+        : '';
+    const isolatedHome = opts.workspaceId
+        ? [
+            `export HOME="$BOX_HOME"/${q(leaseHomeDir(opts.workspaceId))}`,
+            'mkdir -p "$HOME/.agents"',
+            'ln -sfn "$BOX_HOME/.agents/.system" "$HOME/.agents/.system"',
+            'export PATH="$BOX_HOME/.local/bin:$PATH"',
+        ].join('\n')
+        : '';
     return [
         'set -uo pipefail',
         // crabbox has finished its workspace resync by the time this script runs;
         // the sync sentinel marks the transition out of that (crabbox-driven) phase.
         step('sync'),
+        workspace,
         // Only meaningful on a tailnet lease — the box already joined during warmup.
         opts.netMode === 'tailscale' ? step('joined-tailnet') : '',
         step('install'),
         ENSURE_AGENTS_CLI,
+        isolatedHome,
         step('runtime'),
         installRuntimes,
         step('creds'),
@@ -287,6 +318,7 @@ export async function leaseAndRun(opts) {
                 secretsBundle: opts.secretsBundle,
                 onData: opts.onData,
                 refresh: false,
+                remoteDir: opts.workspaceId ? `${leaseHomeDir(opts.workspaceId)}/.agents/` : undefined,
             });
         }
         catch {
@@ -303,10 +335,10 @@ export async function leaseAndRun(opts) {
         });
     }
     finally {
-        // Always attempt teardown (bounds credential lifetime to the run) unless the
-        // caller explicitly asked to keep the box or the box was reused (an explicit
-        // --box target or a warm pool box — both outlive this run).
-        if (!opts.keep && !reused) {
+        // Normal --lease establishes or reuses the warm pool, so the box outlives
+        // this run; credentials are still shredded inside the script above. Only
+        // --fresh requests the old one-shot lifecycle and tears its new box down.
+        if (!opts.keep && opts.fresh && !reused) {
             opts.onPhase?.({ kind: 'teardown' });
             toreDown = crabboxStop(box.slug, { secretsBundle: opts.secretsBundle });
         }

package/dist/lib/crabbox/setup-copy.d.ts

@@ -31,6 +31,11 @@ export interface CopySetupOptions {
     secretsBundle?: string;
     /** Override the local `~/.agents` dir (defaults to `getUserAgentsDir()`). */
     userAgentsDir?: string;
+    /**
+     * Destination relative to the box user's home. Lease runs set this to their
+     * isolated home; other callers retain the historical `~/.agents/` target.
+     */
+    remoteDir?: string;
     /** Receives combined stdout/stderr of the rsync + refresh, if set. */
     onData?: (chunk: string) => void;
     /**

package/dist/lib/crabbox/setup-copy.js

@@ -109,9 +109,25 @@ export async function copySetupToBox(opts) {
     const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-setup-copy-'));
     const listPath = path.join(tmp, 'files.lst');
     try {
+        if (opts.remoteDir) {
+            if (!/^[a-zA-Z0-9._/-]+$/.test(opts.remoteDir) || opts.remoteDir.startsWith('/') || opts.remoteDir.split('/').includes('..')) {
+                throw new Error(`remote setup directory must stay under the box home: ${opts.remoteDir}`);
+            }
+            const remoteDir = opts.remoteDir.replace(/\/$/, '');
+            const prepareArgs = [
+                ...sshArgv.slice(1),
+                'bash',
+                '-lc',
+                `mkdir -p "$HOME"/${JSON.stringify(remoteDir)}`,
+            ];
+            const prepareExitCode = await runStreaming('ssh', prepareArgs, env, opts.onData);
+            if (prepareExitCode !== 0) {
+                return { files, pushExitCode: prepareExitCode, refreshExitCode: null };
+            }
+        }
         // NUL-separated list, matching `buildSetupRsyncArgs`'s `--from0`.
         fs.writeFileSync(listPath, files.join('\0'), 'utf-8');
-        const rsyncArgs = buildSetupRsyncArgs({ rsh, host, filesFrom: listPath, source: dir });
+        const rsyncArgs = buildSetupRsyncArgs({ rsh, host, filesFrom: listPath, source: dir, remoteDir: opts.remoteDir });
         const pushExitCode = await runStreaming('rsync', rsyncArgs, env, opts.onData);
         let refreshExitCode = null;
         if (pushExitCode === 0 && opts.refresh !== false) {