@tangle-network/sandbox 0.10.3 → 0.10.5-develop.20260713235503.8f2cefc

package/dist/{sandbox-BhYmj7L3.d.ts → sandbox-BvNEOnIl.d.ts}

@@ -1,4 +1,4 @@
-import { $ as EventStreamOptions, A as CommitTaskSessionOptions, B as CreateTaskSessionOptions, Bt as IntelligenceReport, Ci as WriteManyFile, Ct as GitBranch, D as CodeLanguage, Dt as GitStatus, E as CodeExecutionResult, Er as SandboxTraceBundle, Et as GitDiff, Gr as SessionMessage, Gt as JsonValue, Hr as SessionForkOptions, Ht as IntelligenceReportCompareTo, In as SandboxEvent, Jr as SnapshotInfo, Kt as ListMessagesOptions, Lr as SendSessionMessageOptions, Mn as SSHCredentials, Nr as SearchMatch, Nt as GpuLeaseManager, On as RestoreSnapshotOptions, Ot as GpuLease, Pn as SandboxConnection, Pr as SearchOptions, Qr as StartupDiagnostics, Rr as SendSessionMessageRequest, Si as WriteFileOptions, T as CodeExecutionOptions, U as DispatchPromptOptions, Ur as SessionInfo, Vr as SessionEventStreamOptions, Vt as IntelligenceReportBudget, W as DispatchedSession, Wr as SessionListOptions, Wt as IntelligenceReportWindow, Xr as SnapshotResult, Y as DriverInfo, Yr as SnapshotOptions, Z as EgressManager, Zt as MintScopedTokenOptions, _n as ProvisionResult, ai as TaskSessionCommitResult, an as PreviewLinkManager, br as SandboxRuntimeProfileList, di as TeeAttestationResponse, dt as FileWriteResult, en as NetworkManager, et as ExecOptions, gi as TurnDriveResult, gn as ProvisionEvent, gr as SandboxResourceUsage, hn as PromptResult, ii as TaskSessionChanges, j as CompletedTurnResult, jn as SSHCommandDescriptor, jr as ScopedToken, kn as ResumeOptions, kr as SandboxTraceOptions, l as BackendManager, li as TeeAttestationOptions, ln as ProcessManager, mn as PromptOptions, ni as TaskOptions, pi as TeePublicKeyResponse, pn as PromptInputPart, pr as SandboxPortBinding, q as DriveTurnOptions, ri as TaskResult, rn as PermissionsManager, s as BackendConfig, si as TaskSessionInfo, st as FileSystem, tr as SandboxFleetTraceBundle, tt as ExecResult, ur as SandboxInfo, vr as SandboxRuntimeHealth, w as BranchOptions, wi as WriteManyOptions, wr as SandboxTerminalManager, wt as GitCommit, xi as WaitForOptions, xr as SandboxStatus, z as CreateSessionOptions, zr as SentSessionMessage, zt as InstalledTool } from "./types-Cmpv-ox_.js";
+import { $ as EventStreamOptions, $r as SessionListOptions, A as CommitTaskSessionOptions, Ai as WaitForOptions, An as RestoreSnapshotOptions, Ar as SandboxStatus, B as CreateTaskSessionOptions, Bn as SSHCommandDescriptor, Br as ScopedToken, Bt as InstalledTool, D as CodeLanguage, Dr as SandboxRuntimeHealth, Dt as GitDiff, E as CodeExecutionResult, Fr as SandboxTraceBundle, Gn as SandboxEvent, Gt as IntelligenceReportWindow, Hr as SearchMatch, Ht as IntelligenceReportBudget, In as RolloutStartResult, Jr as SentSessionMessage, Kr as SendSessionMessageOptions, Kt as JsonValue, Mi as WriteFileOptions, Mn as Rollout, Ni as WriteManyFile, Nr as SandboxTerminalManager, Ot as GitStatus, Pi as WriteManyOptions, Pn as RolloutOptions, Pt as GpuLeaseManager, Qr as SessionInfo, Qt as MintScopedTokenOptions, Rr as SandboxTraceOptions, Si as TeePublicKeyResponse, Sr as SandboxPortBinding, T as CodeExecutionOptions, Ti as TurnDriveResult, Tr as SandboxResourceUsage, Tt as GitCommit, U as DispatchPromptOptions, Un as SandboxConnection, Ur as SearchOptions, Ut as IntelligenceReportCompareTo, Vn as SSHCredentials, Vt as IntelligenceReport, W as DispatchedSession, Xr as SessionEventStreamOptions, Y as DriverInfo, Z as EgressManager, Zr as SessionForkOptions, _n as ProvisionEvent, ai as SnapshotResult, bi as TeeAttestationResponse, ct as FileSystem, di as TaskOptions, ei as SessionMessage, et as ExecOptions, fi as TaskResult, ft as FileWriteResult, gi as TaskSessionInfo, gn as PromptResult, hn as PromptOptions, ii as SnapshotOptions, in as PermissionsManager, j as CompletedTurnResult, ji as WaitForRolloutOptions, jn as ResumeOptions, kr as SandboxRuntimeProfileList, kt as GpuLease, l as BackendManager, mi as TaskSessionCommitResult, mn as PromptInputPart, on as PreviewLinkManager, pi as TaskSessionChanges, q as DriveTurnOptions, qr as SendSessionMessageRequest, qt as ListMessagesOptions, ri as SnapshotInfo, s as BackendConfig, si as StartupDiagnostics, tn as NetworkManager, tt as ExecResult, un as ProcessManager, ur as SandboxFleetTraceBundle, vi as TeeAttestationOptions, vn as ProvisionResult, w as BranchOptions, wt as GitBranch, yr as SandboxInfo, z as CreateSessionOptions } from "./types-yNRVRww-.js";
 
 //#region src/mcp.d.ts
 /**
@@ -900,6 +900,7 @@ declare class SandboxInstance {
   private fsList;
   private fsStat;
   private fsDelete;
+  private fsRename;
   private fsMkdir;
   private fsExists;
   /**
@@ -1236,8 +1237,52 @@ declare class SandboxInstance {
    * ```
    */
   branch(count: number, options?: BranchOptions): Promise<SandboxInstance[]>;
+  /**
+   * Speculative rollouts: branch this RUNNING sandbox into `n` copy-on-write
+   * children, run the SAME agent turn in every child in parallel, and
+   * optionally score each child by running `scorer.command` inside it (exit 0
+   * passes; stdout is parsed as the numeric score — highest wins).
+   *
+   * Async-op shape: resolves as soon as the children exist (their turns are
+   * still running); poll {@link getRollout} or use {@link waitForRollout} for
+   * results. Children are first-class sandboxes the caller may promote or
+   * delete — each occupies a concurrent-session quota slot like a create.
+   *
+   * @example
+   * ```typescript
+   * const started = await box.rollout({
+   *   n: 4,
+   *   parts: [{ type: "text", text: "make the failing test pass" }],
+   *   scorer: { type: "command", command: "npm test --silent && echo 1" },
+   * });
+   * const settled = await box.waitForRollout(started.rolloutId);
+   * console.log(settled.winner, settled.results);
+   * ```
+   */
+  rollout(options: RolloutOptions): Promise<RolloutStartResult>;
+  /**
+   * Poll a rollout's status and per-child results.
+   *
+   * Failed or timed-out children appear as result entries with `error` set —
+   * partial results are never dropped. Rollout poll-state lives in
+   * orchestrator RAM: after an orchestrator restart this returns 404 while
+   * the children themselves survive as first-class sandboxes.
+   */
+  getRollout(rolloutId: string): Promise<Rollout>;
+  /**
+   * Poll {@link getRollout} until the rollout leaves `running`, then return
+   * the terminal record — including `partial`/`failed` outcomes, whose
+   * per-child `error` entries are results the caller inspects, not
+   * exceptions. Throws {@link TimeoutError} on deadline or abort.
+   */
+  waitForRollout(rolloutId: string, options?: WaitForRolloutOptions): Promise<Rollout>;
   /**
    * Stop the sandbox (keeps state for resume).
+   *
+   * The stop response carries the orchestrator's per-phase stop breakdown
+   * (`stop_metering` / `container_kill` / `stop_complete` /
+   * `stop_unaccounted`); after this resolves, {@link startupDiagnostics}
+   * returns it (replacing the create breakdown).
    */
   stop(): Promise<void>;
   /**
@@ -1246,8 +1291,20 @@ declare class SandboxInstance {
   resume(options?: ResumeOptions): Promise<void>;
   /**
    * Delete the sandbox permanently.
+   *
+   * The delete response carries the orchestrator's per-phase delete breakdown
+   * (`container_remove` / `storage_binding_wait` / `cleanup_parallel` /
+   * `delete_complete` / `delete_unaccounted`); after this resolves,
+   * {@link startupDiagnostics} returns it for post-mortem reads on the
+   * now-gone sandbox.
    */
   delete(): Promise<void>;
+  /**
+   * Read the per-phase lifecycle breakdown off a stop/resume/delete response
+   * body. Never throws: diagnostics are measurement data — a body that fails
+   * to parse (older API, empty body) must not fail the lifecycle call.
+   */
+  private readLifecycleDiagnostics;
   /**
    * keepAlive is intentionally unavailable until the API exposes timeout updates.
    * @param seconds - Reserved for future support
@@ -1442,15 +1499,10 @@ declare class SandboxInstance {
    */
   driveTurn(message: string | PromptInputPart[], opts: DriveTurnOptions): Promise<TurnDriveResult>;
   /**
-   * Mint a scoped, time-bounded JWT for direct browser access to this
-   * sandbox (Issue #913 Gap 1). Authority is the caller's
-   * `TANGLE_API_KEY` (sk-tan-*) — the Sandbox API mints the token;
-   * signing secrets stay server-side.
-   *
-   * Use this to give a browser direct read access to the sandbox without
-   * leaking the full bearer (`box.connection.authToken`). The returned
-   * token verifies against the same sidecar middleware that already
-   * gates ProductTokenIssuer-issued JWTs — no new sidecar surface.
+   * Mint a scoped, time-bounded JWT for browser access (Issue #913 Gap 1).
+   * Authority is the caller's `TANGLE_API_KEY` (sk-tan-*); signing secrets
+   * stay server-side. Session/project scopes work with SessionGatewayClient,
+   * while session-runtime/read-only scopes work with SandboxRuntimeClient.
    */
   mintScopedToken(opts: MintScopedTokenOptions): Promise<ScopedToken>;
   /** @internal — invoked by SandboxSession.status(). */

package/dist/{sandbox-CxBHIBV1.js → sandbox-CIHssZCH.js}

@@ -1,5 +1,5 @@
-import { n as normalizeSessionInfo, r as normalizeRuntimeBackendConfig, t as SandboxRuntimeApi } from "./runtime-api-CYA2DUQw.js";
-import { c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, p as parseErrorResponse, s as QuotaError, t as AuthError, u as StateError } from "./errors-DSz87Rkk.js";
+import { n as normalizeSessionInfo, r as normalizeRuntimeBackendConfig, t as SandboxRuntimeApi } from "./runtime-api-CaXI7Kl2.js";
+import { c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, p as parseErrorResponse, s as QuotaError, t as AuthError, u as StateError } from "./errors-wd266B9Q.js";
 import { addTokenUsage, readTokenCostUsd, readTokenUsage } from "@tangle-network/agent-core";
 //#region src/lib/sse-parser.ts
 /**
@@ -752,6 +752,13 @@ function isTransientSnapshotVisibilityError(error) {
 	return message.includes("SNAPSHOT_NOT_FOUND") || message.includes("Failed to list snapshot") || message.includes("Storage agent error (404)");
 }
 /**
+* The extra separator is intentional: absolute paths produce `//`, allowing
+* the runtime route wildcard to retain the path's leading slash.
+*/
+function runtimeFilesystemPath(endpoint, path) {
+	return `${endpoint}/${path}`;
+}
+/**
 * Single source of truth for a run's outcome, shared by
 * `prompt`/`task`/`_sessionResult`/turn settling. A run succeeds only when it
 * reached a terminal event, raised no run-level error, hit no approval gate,
@@ -913,6 +920,22 @@ const WRITE_MANY_DEFAULT_PACE_MS = 150;
 const WRITE_MANY_DEFAULT_MAX_RETRIES = 4;
 const WRITE_MANY_RETRY_BASE_MS = 250;
 const WRITE_MANY_RETRY_MAX_MS = 2e3;
+function parseTextFileReadResponse(body) {
+	let payload;
+	try {
+		payload = JSON.parse(body);
+	} catch {
+		throw new ServerError("Runtime returned invalid JSON for file read", 502, {
+			origin: "runtime",
+			endpoint: "/files/read"
+		});
+	}
+	if (typeof payload !== "object" || payload === null || !("success" in payload) || payload.success !== true || !("data" in payload) || typeof payload.data !== "object" || payload.data === null || !("content" in payload.data) || typeof payload.data.content !== "string" || !("encoding" in payload.data) || payload.data.encoding !== "utf8") throw new ServerError("Runtime returned a malformed text file response", 502, {
+		origin: "runtime",
+		endpoint: "/files/read"
+	});
+	return payload.data.content;
+}
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Transient file-write failures worth retrying: rate-limit (quota), 5xx,
 *  transport (network), and request timeouts. A non-transient error (bad path,
@@ -1324,18 +1347,20 @@ var SandboxInstance = class SandboxInstance {
 	*/
 	async read(path, options) {
 		await this.ensureRunning();
-		const headers = {};
-		if (options?.sessionId) headers["X-Session-Id"] = options.sessionId;
+		const headers = options?.sessionId ? { "X-Session-Id": options.sessionId } : void 0;
 		const response = await this.runtimeFetch("/files/read", {
 			method: "POST",
 			headers,
-			body: JSON.stringify({ path })
+			body: JSON.stringify({
+				path,
+				encoding: "utf8"
+			})
 		});
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
-		return (await response.json()).data?.content ?? "";
+		return parseTextFileReadResponse(await response.text());
 	}
 	/**
 	* Write content to a file in the sandbox.
@@ -1537,8 +1562,8 @@ var SandboxInstance = class SandboxInstance {
 	* `error` + `done` so callers never see a thrown generator.
 	*/
 	async *streamPromptInner(message, options) {
+		if (options?.lastEventId && !options.executionId) throw new ValidationError("lastEventId requires executionId so the SDK can replay the correct execution", { executionId: "Required when lastEventId is set" });
 		await this.ensureRunning();
-		const parts = encodePromptForWire(message);
 		const timeoutMs = typeof options?.timeoutMs === "number" && options.timeoutMs > 0 ? options.timeoutMs : void 0;
 		const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : void 0;
 		const streamSignal = timeoutSignal ? options?.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal : options?.signal;
@@ -1556,26 +1581,47 @@ var SandboxInstance = class SandboxInstance {
 				...data
 			});
 		};
+		const explicitReplay = Boolean(options?.executionId && options.lastEventId);
+		const requestEndpoint = explicitReplay ? `/agents/run/${encodeURIComponent(options?.executionId ?? "")}/events?lastEventId=${encodeURIComponent(options?.lastEventId ?? "")}&format=sse` : "/agents/run/stream";
+		let lastEventId = options?.lastEventId;
+		let executionId = options?.executionId;
+		let sessionId = options?.sessionId;
+		let receivedTerminal = false;
+		const RECONNECT_BACKOFF_MS = [
+			2e3,
+			4e3,
+			8e3,
+			16e3,
+			3e4,
+			3e4
+		];
+		const MAX_RECONNECT_ATTEMPTS = RECONNECT_BACKOFF_MS.length;
+		let lastReplayStatus;
+		let lastExecutionStatus;
+		let firstSseEventSeen = false;
 		let response;
 		try {
 			logStreamCheckpoint("runtime_post_start", {
-				endpoint: "/agents/run/stream",
+				endpoint: requestEndpoint,
 				sessionId: options?.sessionId,
 				executionId: options?.executionId,
 				hasLastEventId: Boolean(options?.lastEventId),
-				detach: options?.detach === true
+				detach: options?.detach === true,
+				replayOnly: explicitReplay
 			});
-			response = await this.runtimeFetch("/agents/run/stream", {
+			const request = explicitReplay ? {
+				method: "GET",
+				signal: streamSignal
+			} : {
 				method: "POST",
 				signal: streamSignal,
 				headers: {
 					...options?.executionId ? { "X-Execution-ID": options.executionId } : {},
-					...options?.lastEventId ? { "Last-Event-ID": options.lastEventId } : {},
 					...options?.detach ? { "x-agent-detach": "true" } : {}
 				},
 				body: JSON.stringify({
 					identifier: "default",
-					parts,
+					parts: encodePromptForWire(message),
 					sessionId: options?.sessionId,
 					turnId: options?.turnId,
 					metadata: options?.context,
@@ -1584,7 +1630,8 @@ var SandboxInstance = class SandboxInstance {
 					...options?.detach ? { detach: true } : {},
 					backend: normalizeRuntimeBackendConfig(options?.backend ?? this.defaultRuntimeBackend, { model: options?.model })
 				})
-			});
+			};
+			response = await this.runtimeFetch(requestEndpoint, request);
 			logStreamCheckpoint("runtime_response_headers", {
 				status: response.status,
 				ok: response.ok
@@ -1594,27 +1641,20 @@ var SandboxInstance = class SandboxInstance {
 			throwIfTimedOut();
 			throw err;
 		}
-		if (!response.ok) {
+		if (!response.ok && !explicitReplay) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
-		let lastEventId = options?.lastEventId;
-		let executionId = options?.executionId;
-		let sessionId = options?.sessionId;
-		let receivedTerminal = false;
-		const RECONNECT_BACKOFF_MS = [
-			2e3,
-			4e3,
-			8e3,
-			16e3,
-			3e4,
-			3e4
-		];
-		const MAX_RECONNECT_ATTEMPTS = RECONNECT_BACKOFF_MS.length;
-		let lastReplayStatus;
-		let lastExecutionStatus;
-		let firstSseEventSeen = false;
-		for await (const event of this.parseSSEStream(response, streamSignal)) {
+		if (!response.ok) {
+			lastReplayStatus = response.status;
+			await response.text();
+			logStreamCheckpoint("replay_response_status", {
+				attempt: 0,
+				status: response.status,
+				ok: false
+			});
+		} else for await (const event of this.parseSSEStream(response, streamSignal)) {
+			if (event.type === "history.replay.start" || event.type === "history.replay.end") continue;
 			if (!firstSseEventSeen) {
 				firstSseEventSeen = true;
 				logStreamCheckpoint("first_sse_event", {
@@ -2092,11 +2132,19 @@ var SandboxInstance = class SandboxInstance {
 	async resourceUsage() {
 		await this.ensureRunning();
 		const response = await this.runtimeFetch("/health/detailed", { method: "GET" });
-		if (!response.ok) {
-			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		const body = await response.text();
+		let data;
+		try {
+			data = JSON.parse(body);
+		} catch (error) {
+			if (response.ok) throw new NetworkError("Detailed health returned a non-JSON response", error instanceof Error ? error : void 0, {
+				endpoint: "/health/detailed",
+				origin: "runtime"
+			});
 		}
-		return (await response.json()).resources ?? null;
+		if (data?.resources) return data.resources;
+		if (!response.ok) throw parseErrorResponse(response.status, body, void 0, response.headers);
+		return null;
 	}
 	/**
 	* Git capability object for repository operations.
@@ -2321,6 +2369,7 @@ var SandboxInstance = class SandboxInstance {
 			list: (path, options) => this.fsList(path, options),
 			stat: (path) => this.fsStat(path),
 			delete: (path, options) => this.fsDelete(path, options),
+			rename: (sourcePath, destinationPath, options) => this.fsRename(sourcePath, destinationPath, options),
 			mkdir: (path, options) => this.fsMkdir(path, options),
 			exists: (path) => this.fsExists(path)
 		};
@@ -2366,7 +2415,7 @@ var SandboxInstance = class SandboxInstance {
 		const fs = await import("node:fs/promises");
 		const path = await import("node:path");
 		await fs.mkdir(path.dirname(localPath), { recursive: true });
-		const response = await this.runtimeFetch(`/fs/download${remotePath}`, { method: "GET" });
+		const response = await this.runtimeFetch(runtimeFilesystemPath("/fs/download", remotePath), { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
@@ -2416,7 +2465,7 @@ var SandboxInstance = class SandboxInstance {
 		const fs = await import("node:fs/promises");
 		const path = await import("node:path");
 		const { execSync } = await import("node:child_process");
-		const response = await this.runtimeFetch(`/fs/download-dir${remoteDir}`, { method: "GET" });
+		const response = await this.runtimeFetch(runtimeFilesystemPath("/fs/download-dir", remoteDir), { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
@@ -2439,7 +2488,8 @@ var SandboxInstance = class SandboxInstance {
 		if (options?.long) params.set("long", "true");
 		if (options?.sessionId) params.set("sessionId", options.sessionId);
 		const query = params.toString();
-		const url = query ? `/fs/list${path}?${query}` : `/fs/list${path}`;
+		const basePath = runtimeFilesystemPath("/fs/list", path);
+		const url = query ? `${basePath}?${query}` : basePath;
 		const response = await this.runtimeFetch(url, { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
@@ -2461,7 +2511,7 @@ var SandboxInstance = class SandboxInstance {
 	}
 	async fsStat(path) {
 		await this.ensureRunning();
-		const response = await this.runtimeFetch(`/fs/stat${path}`, { method: "GET" });
+		const response = await this.runtimeFetch(runtimeFilesystemPath("/fs/stat", path), { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
@@ -2499,19 +2549,24 @@ var SandboxInstance = class SandboxInstance {
 		if (options?.recursive) params.set("recursive", "true");
 		if (options?.sessionId) params.set("sessionId", options.sessionId);
 		const query = params.toString();
-		const url = query ? `/fs${path}?${query}` : `/fs${path}`;
+		const basePath = runtimeFilesystemPath("/fs", path);
+		const url = query ? `${basePath}?${query}` : basePath;
 		const response = await this.runtimeFetch(url, { method: "DELETE" });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
 	}
+	async fsRename(sourcePath, destinationPath, options) {
+		return this.runtime.renameFile(sourcePath, destinationPath, options);
+	}
 	async fsMkdir(path, options) {
 		await this.ensureRunning();
 		const params = new URLSearchParams();
 		if (options?.recursive) params.set("recursive", "true");
 		const query = params.toString();
-		const url = query ? `/fs/mkdir${path}?${query}` : `/fs/mkdir${path}`;
+		const basePath = runtimeFilesystemPath("/fs/mkdir", path);
+		const url = query ? `${basePath}?${query}` : basePath;
 		const response = await this.runtimeFetch(url, { method: "POST" });
 		if (!response.ok) {
 			const body = await response.text();
@@ -2520,7 +2575,7 @@ var SandboxInstance = class SandboxInstance {
 	}
 	async fsExists(path) {
 		await this.ensureRunning();
-		const response = await this.runtimeFetch(`/fs/exists${path}`, { method: "GET" });
+		const response = await this.runtimeFetch(runtimeFilesystemPath("/fs/exists", path), { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
@@ -3721,7 +3776,89 @@ var SandboxInstance = class SandboxInstance {
 		return ((await response.json()).children ?? []).map((child) => new SandboxInstance(this.client, this.parseInfo(child), this.defaultRuntimeBackend));
 	}
 	/**
+	* Speculative rollouts: branch this RUNNING sandbox into `n` copy-on-write
+	* children, run the SAME agent turn in every child in parallel, and
+	* optionally score each child by running `scorer.command` inside it (exit 0
+	* passes; stdout is parsed as the numeric score — highest wins).
+	*
+	* Async-op shape: resolves as soon as the children exist (their turns are
+	* still running); poll {@link getRollout} or use {@link waitForRollout} for
+	* results. Children are first-class sandboxes the caller may promote or
+	* delete — each occupies a concurrent-session quota slot like a create.
+	*
+	* @example
+	* ```typescript
+	* const started = await box.rollout({
+	*   n: 4,
+	*   parts: [{ type: "text", text: "make the failing test pass" }],
+	*   scorer: { type: "command", command: "npm test --silent && echo 1" },
+	* });
+	* const settled = await box.waitForRollout(started.rolloutId);
+	* console.log(settled.winner, settled.results);
+	* ```
+	*/
+	async rollout(options) {
+		if (!Number.isInteger(options.n) || options.n < 1 || options.n > 8) throw new ValidationError(`rollout n must be an integer in [1, 8] (got ${options.n})`);
+		if (!Array.isArray(options.parts) || options.parts.length === 0) throw new ValidationError("rollout parts must be a non-empty array");
+		if (options.scorer?.type === "command" && !options.scorer.command) throw new ValidationError("scorer.command is required when scorer.type is \"command\"");
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/rollouts`, {
+			method: "POST",
+			body: JSON.stringify({
+				n: options.n,
+				parts: options.parts,
+				...options.scorer ? { scorer: options.scorer } : {}
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		if (typeof data.rolloutId !== "string" || data.rolloutId.length === 0) throw new ServerError(`Rollout create returned ${response.status} but body had no rolloutId: ${JSON.stringify(data).slice(0, 200)}`, response.status);
+		return data;
+	}
+	/**
+	* Poll a rollout's status and per-child results.
+	*
+	* Failed or timed-out children appear as result entries with `error` set —
+	* partial results are never dropped. Rollout poll-state lives in
+	* orchestrator RAM: after an orchestrator restart this returns 404 while
+	* the children themselves survive as first-class sandboxes.
+	*/
+	async getRollout(rolloutId) {
+		if (!rolloutId) throw new ValidationError("rolloutId is required");
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/rollouts/${encodeURIComponent(rolloutId)}`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	/**
+	* Poll {@link getRollout} until the rollout leaves `running`, then return
+	* the terminal record — including `partial`/`failed` outcomes, whose
+	* per-child `error` entries are results the caller inspects, not
+	* exceptions. Throws {@link TimeoutError} on deadline or abort.
+	*/
+	async waitForRollout(rolloutId, options) {
+		const timeoutMs = options?.timeoutMs ?? 36e4;
+		const pollIntervalMs = options?.pollIntervalMs ?? 2e3;
+		const startTime = Date.now();
+		while (true) {
+			if (options?.signal?.aborted) throw new TimeoutError(0, "Aborted");
+			const record = await this.getRollout(rolloutId);
+			if (record.status !== "running") return record;
+			if (Date.now() - startTime > timeoutMs) throw new TimeoutError(timeoutMs, `Timed out waiting for rollout ${rolloutId} to settle`);
+			await this.sleep(pollIntervalMs);
+		}
+	}
+	/**
 	* Stop the sandbox (keeps state for resume).
+	*
+	* The stop response carries the orchestrator's per-phase stop breakdown
+	* (`stop_metering` / `container_kill` / `stop_complete` /
+	* `stop_unaccounted`); after this resolves, {@link startupDiagnostics}
+	* returns it (replacing the create breakdown).
 	*/
 	async stop() {
 		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/stop`, { method: "POST" });
@@ -3729,7 +3866,9 @@ var SandboxInstance = class SandboxInstance {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
+		const diagnostics = await this.readLifecycleDiagnostics(response);
 		await this.refresh();
+		if (diagnostics) this.info.startupDiagnostics = diagnostics;
 	}
 	/**
 	* Resume a stopped sandbox.
@@ -3746,10 +3885,18 @@ var SandboxInstance = class SandboxInstance {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
+		const diagnostics = await this.readLifecycleDiagnostics(response);
 		await this.refresh();
+		if (diagnostics) this.info.startupDiagnostics = diagnostics;
 	}
 	/**
 	* Delete the sandbox permanently.
+	*
+	* The delete response carries the orchestrator's per-phase delete breakdown
+	* (`container_remove` / `storage_binding_wait` / `cleanup_parallel` /
+	* `delete_complete` / `delete_unaccounted`); after this resolves,
+	* {@link startupDiagnostics} returns it for post-mortem reads on the
+	* now-gone sandbox.
 	*/
 	async delete() {
 		const response = await this.client.fetch(`/v1/sandboxes/${this.id}`, { method: "DELETE" });
@@ -3757,6 +3904,17 @@ var SandboxInstance = class SandboxInstance {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
+		const diagnostics = await this.readLifecycleDiagnostics(response);
+		if (diagnostics) this.info.startupDiagnostics = diagnostics;
+	}
+	/**
+	* Read the per-phase lifecycle breakdown off a stop/resume/delete response
+	* body. Never throws: diagnostics are measurement data — a body that fails
+	* to parse (older API, empty body) must not fail the lifecycle call.
+	*/
+	async readLifecycleDiagnostics(response) {
+		const data = await response.json().catch(() => null);
+		return data ? normalizeStartupDiagnostics(data.startupDiagnostics) : null;
 	}
 	/**
 	* keepAlive is intentionally unavailable until the API exposes timeout updates.
@@ -4330,15 +4488,10 @@ var SandboxInstance = class SandboxInstance {
 		return { state: "running" };
 	}
 	/**
-	* Mint a scoped, time-bounded JWT for direct browser access to this
-	* sandbox (Issue #913 Gap 1). Authority is the caller's
-	* `TANGLE_API_KEY` (sk-tan-*) — the Sandbox API mints the token;
-	* signing secrets stay server-side.
-	*
-	* Use this to give a browser direct read access to the sandbox without
-	* leaking the full bearer (`box.connection.authToken`). The returned
-	* token verifies against the same sidecar middleware that already
-	* gates ProductTokenIssuer-issued JWTs — no new sidecar surface.
+	* Mint a scoped, time-bounded JWT for browser access (Issue #913 Gap 1).
+	* Authority is the caller's `TANGLE_API_KEY` (sk-tan-*); signing secrets
+	* stay server-side. Session/project scopes work with SessionGatewayClient,
+	* while session-runtime/read-only scopes work with SandboxRuntimeClient.
 	*/
 	async mintScopedToken(opts) {
 		if ((opts.scope === "session" || opts.scope === "session-runtime") && !opts.sessionId) throw new ValidationError(`${opts.scope} scope requires a sessionId`);
@@ -4382,7 +4535,7 @@ var SandboxInstance = class SandboxInstance {
 		const search = new URLSearchParams();
 		search.set("sessionId", id);
 		if (opts?.since) search.set("since", opts.since);
-		const response = await this.runtimeFetch(`/agents/events/?${search.toString()}`, { signal: opts?.signal });
+		const response = await this.runtimeFetch(`/agents/events?${search.toString()}`, { signal: opts?.signal });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);

package/dist/tangle/index.d.ts

@@ -1,2 +1,2 @@
-import { a as TANGLE_JOBS_CONTRACT, c as AgentSandboxBlueprintAbi, d as SandboxCreateParamTypes, f as SandboxCreateResponseParamTypes, i as TANGLE_CHAIN_ID, l as ITangleJobsAbi, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, p as SandboxIdParamTypes, r as JOB_SANDBOX_DELETE, s as TangleSandboxClientConfig, t as TangleSandboxClient, u as JsonResponseParamTypes } from "../index-DzEUjav-.js";
+import { a as TANGLE_JOBS_CONTRACT, c as AgentSandboxBlueprintAbi, d as SandboxCreateParamTypes, f as SandboxCreateResponseParamTypes, i as TANGLE_CHAIN_ID, l as ITangleJobsAbi, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, p as SandboxIdParamTypes, r as JOB_SANDBOX_DELETE, s as TangleSandboxClientConfig, t as TangleSandboxClient, u as JsonResponseParamTypes } from "../index-DFJiN98I.js";
 export { AgentSandboxBlueprintAbi, ITangleJobsAbi, JOB_SANDBOX_CREATE, JOB_SANDBOX_DELETE, JsonResponseParamTypes, SandboxCreateParamTypes, SandboxCreateResponseParamTypes, SandboxIdParamTypes, TANGLE_CHAIN_ID, TANGLE_JOBS_CONTRACT, TANGLE_MAINNET_RPC, TangleSandboxClient, TangleSandboxClientConfig };

package/dist/tangle/index.js

@@ -1,2 +1,2 @@
-import { a as TANGLE_JOBS_CONTRACT, c as ITangleJobsAbi, d as SandboxCreateResponseParamTypes, f as SandboxIdParamTypes, i as TANGLE_CHAIN_ID, l as JsonResponseParamTypes, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, r as JOB_SANDBOX_DELETE, s as AgentSandboxBlueprintAbi, t as TangleSandboxClient, u as SandboxCreateParamTypes } from "../tangle-BdRRHMpX.js";
+import { a as TANGLE_JOBS_CONTRACT, c as ITangleJobsAbi, d as SandboxCreateResponseParamTypes, f as SandboxIdParamTypes, i as TANGLE_CHAIN_ID, l as JsonResponseParamTypes, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, r as JOB_SANDBOX_DELETE, s as AgentSandboxBlueprintAbi, t as TangleSandboxClient, u as SandboxCreateParamTypes } from "../tangle-C-5OvIj8.js";
 export { AgentSandboxBlueprintAbi, ITangleJobsAbi, JOB_SANDBOX_CREATE, JOB_SANDBOX_DELETE, JsonResponseParamTypes, SandboxCreateParamTypes, SandboxCreateResponseParamTypes, SandboxIdParamTypes, TANGLE_CHAIN_ID, TANGLE_JOBS_CONTRACT, TANGLE_MAINNET_RPC, TangleSandboxClient };

package/dist/{tangle-BdRRHMpX.js → tangle-C-5OvIj8.js}

@@ -1,5 +1,5 @@
-import { p as parseErrorResponse } from "./errors-DSz87Rkk.js";
-import { t as SandboxInstance } from "./sandbox-CxBHIBV1.js";
+import { p as parseErrorResponse } from "./errors-wd266B9Q.js";
+import { t as SandboxInstance } from "./sandbox-CIHssZCH.js";
 //#region src/tangle/abi.ts
 /**
 * Tangle Contract ABI Definitions