@opengeni/runtime 0.13.0 → 0.13.3

package/dist/{chunk-65UDUFUO.js → chunk-JGUQSAG5.js}

@@ -17492,6 +17492,295 @@ function assertProviderRegistryInvariants() {
 }
 assertProviderRegistryInvariants();
 
+// src/sandbox/provider-errors.ts
+var GRPC_TRANSIENT = /* @__PURE__ */ new Set([1, 2, 4, 13, 14]);
+var TRANSIENT_CODES = /* @__PURE__ */ new Set([
+  "CANCELLED",
+  "UNKNOWN",
+  "DEADLINE_EXCEEDED",
+  "INTERNAL",
+  "UNAVAILABLE",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EAI_AGAIN",
+  "ENOTFOUND"
+]);
+var NOT_FOUND_CODES = /* @__PURE__ */ new Set(["404", "NOT_FOUND", "RESOURCE_NOT_FOUND", "SANDBOX_NOT_FOUND"]);
+var SAFE_CODE = /^[A-Z0-9._:-]{1,64}$/;
+function safeRead(record, key) {
+  try {
+    return Reflect.get(record, key);
+  } catch {
+    return void 0;
+  }
+}
+function collectSignals(value) {
+  const out = { numbers: [], codes: [], messages: [] };
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (current, depth) => {
+    if (depth > 3 || current === null || current === void 0) return;
+    if (typeof current === "string") {
+      if (current.length <= 512) out.messages.push(current);
+      return;
+    }
+    if (typeof current !== "object" || seen.has(current)) return;
+    seen.add(current);
+    for (const key of [
+      "status",
+      "statusCode",
+      "httpStatus",
+      "httpStatusCode",
+      "responseStatus",
+      "errorCode",
+      "code"
+    ]) {
+      const signal = safeRead(current, key);
+      if (typeof signal === "number" && Number.isFinite(signal)) out.numbers.push(signal);
+      if (typeof signal === "string") {
+        const code = signal.trim().toUpperCase();
+        if (SAFE_CODE.test(code)) out.codes.push(code);
+      }
+    }
+    for (const key of ["name", "message", "details", "cause"]) {
+      const signal = safeRead(current, key);
+      if (typeof signal === "string" && signal.length <= 512) out.messages.push(signal);
+      else visit(signal, depth + 1);
+    }
+    visit(safeRead(current, "response"), depth + 1);
+    visit(safeRead(current, "error"), depth + 1);
+  };
+  visit(value, 0);
+  return out;
+}
+function safeDiagnostic(signals) {
+  const code = signals.codes.find(Boolean);
+  const numeric = signals.numbers.find((value) => Number.isFinite(value));
+  return [code ? `code=${code}` : "", numeric !== void 0 ? `status=${numeric}` : ""].filter(Boolean).join(" ");
+}
+function hasTransientSignal(signals) {
+  return signals.codes.some((code) => TRANSIENT_CODES.has(code)) || signals.numbers.some((status) => GRPC_TRANSIENT.has(status));
+}
+function hasModalTerminalSandboxMessage(signals) {
+  return signals.messages.some(
+    (message) => /^Modal sandbox [A-Za-z0-9_-]+ is no longer running\.$/.test(message) || /^Modal sandbox [A-Za-z0-9_-]+ not found \(has been terminated\)$/.test(message)
+  );
+}
+function classifyProviderSandboxFailure(backendId, error) {
+  if (backendId === "selfhosted" || !error) {
+    return { kind: "other", diagnostic: "selfhosted-or-empty" };
+  }
+  const signals = collectSignals(error);
+  const diagnostic = safeDiagnostic(signals) || "unclassified_provider_failure";
+  if (hasTransientSignal(signals)) {
+    return { kind: "transient_transport", diagnostic };
+  }
+  if (signals.numbers.some((status) => status === 404) || signals.codes.some((code) => NOT_FOUND_CODES.has(code))) {
+    return { kind: "not_found", diagnostic };
+  }
+  if (backendId === "modal" && hasModalTerminalSandboxMessage(signals)) {
+    return {
+      kind: "not_found",
+      diagnostic: diagnostic === "unclassified_provider_failure" ? "modal_terminal_message" : `${diagnostic} modal_terminal_message`
+    };
+  }
+  return { kind: "other", diagnostic };
+}
+function isProviderSandboxNotFoundError2(backendId, error) {
+  return classifyProviderSandboxFailure(backendId, error).kind === "not_found";
+}
+function isProviderSandboxGoneDuringRoutedOperation(backendId, error) {
+  if (backendId === "selfhosted" || !error) return false;
+  const signals = collectSignals(error);
+  if (hasTransientSignal(signals)) return false;
+  if (signals.codes.includes("SANDBOX_NOT_FOUND")) return true;
+  return backendId === "modal" && hasModalTerminalSandboxMessage(signals);
+}
+function isProviderSandboxTransientError(backendId, error) {
+  return classifyProviderSandboxFailure(backendId, error).kind === "transient_transport";
+}
+
+// src/sandbox/workspace-archive.ts
+import { createHash as createHash4 } from "crypto";
+var WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION = 1;
+var WorkspaceArchiveIntegrityError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.code = code;
+    this.retryable = options.retryable ?? false;
+  }
+  name = "WorkspaceArchiveIntegrityError";
+  retryable;
+};
+var SHA256 = /^[a-f0-9]{64}$/;
+var REVISION = /^wa1:[0-9]{13}:[a-f0-9]{64}$/;
+function sha256(bytes) {
+  return createHash4("sha256").update(bytes).digest("hex");
+}
+function nonnegativeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function parseWorkspaceArchiveDescriptor(value) {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value;
+  const workspace = candidate.workspace;
+  if (candidate.version !== WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION || typeof candidate.revision !== "string" || !REVISION.test(candidate.revision) || typeof candidate.archiveSha256 !== "string" || !SHA256.test(candidate.archiveSha256) || !nonnegativeInteger(candidate.archiveBytes) || candidate.archiveBytes === 0 || typeof candidate.capturedAt !== "string" || !Number.isFinite(Date.parse(candidate.capturedAt)) || !workspace || workspace.algorithm !== "sha256" || typeof workspace.sha256 !== "string" || !SHA256.test(workspace.sha256) || !nonnegativeInteger(workspace.entryCount) || !nonnegativeInteger(workspace.fileCount) || !nonnegativeInteger(workspace.totalFileBytes)) {
+    return null;
+  }
+  return candidate;
+}
+function decodeBase64Strict(value) {
+  if (value.length === 0 || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) {
+    return null;
+  }
+  const bytes = Uint8Array.from(Buffer.from(value, "base64"));
+  return Buffer.from(bytes).toString("base64") === value ? bytes : null;
+}
+function readVerifiedWorkspaceArchive(base642, metadata) {
+  if (base642 === void 0 || base642 === null || base642 === "") return null;
+  if (typeof base642 !== "string") {
+    throw new WorkspaceArchiveIntegrityError(
+      "archive_base64_invalid",
+      "selected workspace archive is not a base64 string"
+    );
+  }
+  if (metadata === void 0 || metadata === null) {
+    throw new WorkspaceArchiveIntegrityError(
+      "archive_metadata_missing",
+      "selected workspace archive has no durable revision/fingerprint metadata"
+    );
+  }
+  const descriptor = parseWorkspaceArchiveDescriptor(metadata);
+  if (!descriptor) {
+    throw new WorkspaceArchiveIntegrityError(
+      "archive_metadata_invalid",
+      "selected workspace archive metadata is invalid"
+    );
+  }
+  const bytes = decodeBase64Strict(base642);
+  if (!bytes) {
+    throw new WorkspaceArchiveIntegrityError(
+      "archive_base64_invalid",
+      `workspace archive revision ${descriptor.revision} has invalid base64 bytes`
+    );
+  }
+  const actualHash = sha256(bytes);
+  if (bytes.length !== descriptor.archiveBytes || actualHash !== descriptor.archiveSha256) {
+    throw new WorkspaceArchiveIntegrityError(
+      "archive_hash_mismatch",
+      `workspace archive revision ${descriptor.revision} failed SHA-256/size verification`
+    );
+  }
+  return { bytes, base64: base642, descriptor };
+}
+function stdoutFromExecResult(value) {
+  if (typeof value === "string") return value;
+  if (!value || typeof value !== "object") return "";
+  const output = value;
+  return typeof output.stdout === "string" ? output.stdout : typeof output.output === "string" ? output.output : "";
+}
+var WORKSPACE_FINGERPRINT_COMMAND = String.raw`bash -o pipefail -c '
+set -eu
+cd /workspace
+digest=$(LC_ALL=C tar --sort=name --mtime="@0" --owner=0 --group=0 --numeric-owner --format=gnu -cf - . | sha256sum | awk "{print \$1}")
+entries=$(find . -xdev -mindepth 1 -printf x | wc -c | tr -d " ")
+files=$(find . -xdev -type f -printf x | wc -c | tr -d " ")
+bytes=$(find . -xdev -type f -printf "%s\n" | awk "{s+=\$1} END {printf \"%.0f\", s+0}")
+printf "OPENGENI_WORKSPACE_FINGERPRINT_V1 %s %s %s %s\n" "$digest" "$entries" "$files" "$bytes"
+'`;
+async function fingerprintSandboxWorkspace(session) {
+  const target = session;
+  const run2 = target.exec ?? target.execCommand;
+  if (!run2) {
+    throw new WorkspaceArchiveIntegrityError(
+      "workspace_fingerprint_unavailable",
+      "sandbox session cannot execute the workspace fingerprint probe"
+    );
+  }
+  const result = await run2.call(target, {
+    cmd: WORKSPACE_FINGERPRINT_COMMAND,
+    yieldTimeMs: 12e4,
+    maxOutputTokens: 1e3
+  });
+  const match = stdoutFromExecResult(result).trim().match(/^OPENGENI_WORKSPACE_FINGERPRINT_V1 ([a-f0-9]{64}) ([0-9]+) ([0-9]+) ([0-9]+)$/);
+  if (!match) {
+    throw new WorkspaceArchiveIntegrityError(
+      "workspace_fingerprint_unavailable",
+      "sandbox workspace fingerprint probe returned no valid digest",
+      { retryable: true }
+    );
+  }
+  const entryCount = Number(match[2]);
+  const fileCount = Number(match[3]);
+  const totalFileBytes = Number(match[4]);
+  if (![entryCount, fileCount, totalFileBytes].every(Number.isSafeInteger)) {
+    throw new WorkspaceArchiveIntegrityError(
+      "workspace_fingerprint_unavailable",
+      "sandbox workspace fingerprint counters exceeded the supported range"
+    );
+  }
+  return {
+    algorithm: "sha256",
+    sha256: match[1],
+    entryCount,
+    fileCount,
+    totalFileBytes
+  };
+}
+function fingerprintsEqual(a, b) {
+  return a.sha256 === b.sha256 && a.entryCount === b.entryCount && a.fileCount === b.fileCount && a.totalFileBytes === b.totalFileBytes;
+}
+async function captureVerifiedWorkspaceArchive(session, capturedAtMs = Date.now()) {
+  const target = session;
+  if (typeof target.persistWorkspace !== "function") {
+    throw new WorkspaceArchiveIntegrityError(
+      "workspace_fingerprint_unavailable",
+      "sandbox session does not support workspace persistence"
+    );
+  }
+  const before = await fingerprintSandboxWorkspace(target);
+  const bytes = await target.persistWorkspace();
+  if (!bytes || bytes.length === 0) {
+    throw new WorkspaceArchiveIntegrityError(
+      "archive_base64_invalid",
+      "sandbox workspace persistence returned an empty archive",
+      { retryable: true }
+    );
+  }
+  const after = await fingerprintSandboxWorkspace(target);
+  if (!fingerprintsEqual(before, after)) {
+    throw new WorkspaceArchiveIntegrityError(
+      "workspace_changed_during_capture",
+      "workspace changed while its durable archive was being captured",
+      { retryable: true }
+    );
+  }
+  const archiveSha256 = sha256(bytes);
+  const descriptor = {
+    version: WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION,
+    revision: `wa1:${String(capturedAtMs).padStart(13, "0")}:${archiveSha256}`,
+    archiveSha256,
+    archiveBytes: bytes.length,
+    capturedAt: new Date(capturedAtMs).toISOString(),
+    workspace: before
+  };
+  return {
+    bytes,
+    base64: Buffer.from(bytes).toString("base64"),
+    descriptor
+  };
+}
+async function verifyRestoredWorkspace(session, descriptor) {
+  const actual = await fingerprintSandboxWorkspace(session);
+  if (!fingerprintsEqual(actual, descriptor.workspace)) {
+    throw new WorkspaceArchiveIntegrityError(
+      "workspace_fingerprint_mismatch",
+      `restored workspace does not match selected archive revision ${descriptor.revision}`
+    );
+  }
+  return actual;
+}
+
 // src/sandbox/index.ts
 import { collectSandboxEnvironment as collectSandboxEnvironment2, parseExposedPorts as parseExposedPorts2 } from "@opengeni/config";
 
@@ -17708,6 +17997,9 @@ function negotiateCapabilities(ctx) {
     os: ctx.os,
     liveness: ctx.liveness,
     leaseEpoch: ctx.leaseEpoch,
+    workspaceGeneration: ctx.workspaceGeneration ?? null,
+    archiveGeneration: ctx.archiveGeneration ?? null,
+    archiveComplete: ctx.archiveComplete ?? false,
     viewerHeartbeatIntervalMs: 3e4,
     FileSystem: fileSystem,
     Terminal: terminal,
@@ -17796,6 +18088,12 @@ function parseExecBannerExitCode(raw) {
   const banner = parseExecResponseBanner(raw);
   return banner.kind === "exited" ? banner.exitCode : null;
 }
+function isExecSessionLostBanner(out, execSessionId) {
+  if (!out || !Number.isSafeInteger(execSessionId) || execSessionId < 0) return false;
+  const match = out.match(/^(?:write_stdin failed: )?session not found: (\d+)$/);
+  if (!match || match[0] !== out) return false;
+  return match[1] === String(execSessionId);
+}
 
 // src/sandbox/display-stack.ts
 var STREAM_PORT = DESKTOP_STREAM_PORT4;
@@ -19152,7 +19450,7 @@ function withRunCredentialsClient(client, sessionId, onSessionReady) {
 }
 
 // src/sandbox/toolspace-token.ts
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 import { posix as posixPath } from "path";
 var MAX_TOOLSPACE_SESSION_ID_BYTES = 512;
 var ToolspaceTokenPathError = class extends Error {
@@ -19175,7 +19473,7 @@ function toolspaceTokenFileForSession(manifestTokenFile, sessionId) {
     throw new ToolspaceTokenPathError("Toolspace manifest token file must be absolute");
   }
   const normalizedManifestFile = posixPath.normalize(manifestTokenFile);
-  const digest = createHash4("sha256").update(assertToolspaceSessionId(sessionId)).digest("hex");
+  const digest = createHash5("sha256").update(assertToolspaceSessionId(sessionId)).digest("hex");
   return posixPath.join(posixPath.dirname(normalizedManifestFile), "toolspace-tokens", digest);
 }
 function toolspaceTokenFileFromEnvironment(environment, sessionId) {
@@ -19442,17 +19740,815 @@ async function uploadRecordingArtifact(session, proc, input) {
   if (!output.includes(RECORDING_UPLOAD_OK)) {
     throw new Error("recording upload did not confirm success");
   }
-  return metadata;
-}
-async function deleteRecordingArtifacts(session, proc) {
-  const s = session;
-  const logFile = proc.boxPath.replace(/\.(mp4|webm)$/, ".log");
-  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(
-    () => void 0
-  );
+  return metadata;
+}
+async function deleteRecordingArtifacts(session, proc) {
+  const s = session;
+  const logFile = proc.boxPath.replace(/\.(mp4|webm)$/, ".log");
+  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(
+    () => void 0
+  );
+}
+function recordingStorageKey(workspaceId, sessionId, recordingId, codec) {
+  return `recordings/${workspaceId}/${sessionId}/${recordingId}.${extForCodec(codec)}`;
+}
+
+// src/sandbox/turn-tool-cancellation.ts
+var TURN_EXEC_YIELD_MS = 250;
+var TURN_WRITE_YIELD_MS = 250;
+var SHELL_HELPER_YIELD_MS = 1e3;
+var SHELL_GRACEFUL_POLLS = 2;
+var SHELL_POLL_MS = 100;
+var SHELL_MARKER_DIR = "/tmp/opengeni-turn-shell";
+var delay = async (milliseconds) => await new Promise((resolve5) => setTimeout(resolve5, milliseconds));
+var TurnSandboxCommandCancelledError = class extends Error {
+  name = "TurnSandboxCommandCancelledError";
+  constructor(reason) {
+    super(
+      reason instanceof Error ? reason.message : String(reason ?? "Turn sandbox tools were cancelled"),
+      {
+        ...reason instanceof Error ? { cause: reason } : {}
+      }
+    );
+  }
+};
+function cancellationError(reason) {
+  return new TurnSandboxCommandCancelledError(reason);
+}
+function parsedObject(input) {
+  try {
+    const parsed = JSON.parse(input);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function cappedYield(value, cap) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? Math.min(value, cap) : cap;
+}
+function execOutput(raw) {
+  const marker = "\nOutput:\n";
+  const index = raw.indexOf(marker);
+  return index >= 0 ? raw.slice(index + marker.length) : "";
+}
+function nativeCommandBanner(result) {
+  if (typeof result === "string") return result;
+  if (!result || typeof result !== "object") {
+    throw new Error("Sandbox command returned an invalid result");
+  }
+  const value = result;
+  const sessionId = typeof value.sessionId === "number" ? value.sessionId : typeof value.session_id === "number" ? value.session_id : null;
+  const exitCode = typeof value.exitCode === "number" ? value.exitCode : typeof value.exit_code === "number" ? value.exit_code : null;
+  const output = [value.output, value.stderr, value.stdout].filter(
+    (candidate) => typeof candidate === "string" && candidate.length > 0
+  ).join("\n");
+  if (sessionId !== null) {
+    return `Process running with session ID ${sessionId}
+
+Output:
+${output}`;
+  }
+  if (exitCode !== null) {
+    return `Process exited with code ${exitCode}
+
+Output:
+${output}`;
+  }
+  throw new Error("Sandbox command did not report a session id or exit code");
+}
+function nativeCommandResult(result) {
+  if (typeof result === "string") {
+    return {
+      stdout: execOutput(result),
+      stderr: "",
+      exitCode: parseExecBannerExitCode(result),
+      sessionId: parseExecBannerSessionId(result),
+      wallTimeSeconds: 0
+    };
+  }
+  if (!result || typeof result !== "object") {
+    throw new Error("Sandbox command returned an invalid result");
+  }
+  const value = result;
+  return {
+    stdout: typeof value.stdout === "string" ? value.stdout : typeof value.output === "string" ? value.output : "",
+    stderr: typeof value.stderr === "string" ? value.stderr : "",
+    exitCode: typeof value.exitCode === "number" ? value.exitCode : typeof value.exit_code === "number" ? value.exit_code : null,
+    sessionId: typeof value.sessionId === "number" ? value.sessionId : typeof value.session_id === "number" ? value.session_id : null,
+    wallTimeSeconds: typeof value.wallTimeSeconds === "number" && value.wallTimeSeconds >= 0 ? value.wallTimeSeconds : 0
+  };
+}
+function completedCommandBanner(exitCode, output) {
+  return `Process exited with code ${exitCode}
+
+Output:
+${output}`;
+}
+function appendBoundedOutput3(current, chunk, maxOutputTokens) {
+  const maxChars = Math.max(512, maxOutputTokens * 4);
+  const combined = current + chunk;
+  return combined.length <= maxChars ? combined : combined.slice(-maxChars);
+}
+function singleQuote(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function shellMarkerPath(token) {
+  return `${SHELL_MARKER_DIR}/${token}`;
+}
+function cancellableGroupLeaderCommand(command, markerPath) {
+  const marker = singleQuote(markerPath);
+  const markerDir = singleQuote(SHELL_MARKER_DIR);
+  return [
+    `__opengeni_marker=${marker}`,
+    "umask 077",
+    `command mkdir -p ${markerDir} || exit 125`,
+    '__opengeni_pid="$$"',
+    `__opengeni_pgid="$(command ps -o pgid= -p "$__opengeni_pid" 2>/dev/null | command tr -d '[:space:]')"`,
+    'case "$__opengeni_pid:$__opengeni_pgid" in *[!0-9:]*|*:|:*) exit 125 ;; esac',
+    '[ "$__opengeni_pid" -gt 1 ] && [ "$__opengeni_pgid" -gt 1 ] || exit 125',
+    // Never signal a provider/container-wide process group. A cancellable PTY
+    // command must be its group's leader; fail the command closed otherwise.
+    '[ "$__opengeni_pid" = "$__opengeni_pgid" ] || exit 125',
+    `command printf '%s %s\\n' "$__opengeni_pid" "$__opengeni_pgid" > "$__opengeni_marker" || exit 125`,
+    `trap 'command rm -f "$__opengeni_marker"' EXIT`,
+    "(",
+    command,
+    ")",
+    "__opengeni_status=$?",
+    'exit "$__opengeni_status"'
+  ].join("\n");
+}
+function cancellableShellCommand(command, markerPath) {
+  const groupLeaderCommand = cancellableGroupLeaderCommand(command, markerPath);
+  return [
+    '__opengeni_outer_pid="$$"',
+    `__opengeni_outer_pgid="$(command ps -o pgid= -p "$__opengeni_outer_pid" 2>/dev/null | command tr -d '[:space:]')"`,
+    'case "$__opengeni_outer_pid:$__opengeni_outer_pgid" in *[!0-9:]*|*:|:*) exit 125 ;; esac',
+    'if [ "$__opengeni_outer_pid" != "$__opengeni_outer_pgid" ]; then',
+    '  __opengeni_setsid="$(command -v setsid 2>/dev/null)"',
+    '  [ -n "$__opengeni_setsid" ] || exit 125',
+    `  exec "$__opengeni_setsid" /bin/sh -c ${singleQuote(groupLeaderCommand)}`,
+    "fi",
+    groupLeaderCommand
+  ].join("\n");
+}
+function shellHelperInput(command) {
+  const args = shellHelperArgs(command);
+  return JSON.stringify({
+    cmd: args.cmd,
+    login: args.login,
+    tty: args.tty,
+    yield_time_ms: args.yieldTimeMs,
+    max_output_tokens: args.maxOutputTokens
+  });
+}
+function shellHelperArgs(command) {
+  return {
+    cmd: command,
+    login: false,
+    tty: false,
+    yieldTimeMs: SHELL_HELPER_YIELD_MS,
+    maxOutputTokens: 128
+  };
+}
+function retainedProcessSession(session, providerSessionId) {
+  return session?.hasRetainedProcess?.(providerSessionId) === true ? session : null;
+}
+function safeProcessIdentity(raw) {
+  if (parseExecBannerExitCode(raw) !== 0) return null;
+  const match = execOutput(raw).trim().match(/^(\d+)\s+(\d+)$/);
+  if (!match) return null;
+  const pid = Number.parseInt(match[1], 10);
+  const processGroupId = Number.parseInt(match[2], 10);
+  return Number.isSafeInteger(pid) && Number.isSafeInteger(processGroupId) && pid > 1 && processGroupId > 1 ? { pid, processGroupId } : null;
+}
+function identityGuardScript(state, body, missingIdentityExitCode) {
+  const identity = state.identity;
+  if (!identity || !state.token) return `exit ${missingIdentityExitCode}`;
+  const token = singleQuote(state.token);
+  return [
+    `__opengeni_pid=${identity.pid}`,
+    `__opengeni_pgid=${identity.processGroupId}`,
+    `__opengeni_token=${token}`,
+    // The randomized token lands late in the wrapped command line. Procps
+    // otherwise truncates `args` to the terminal width, which can make a live
+    // group look stale and open the quiescence fence without signalling it.
+    '__opengeni_args="$(command ps -ww -o args= -p "$__opengeni_pid" 2>/dev/null)"',
+    'case "$__opengeni_args" in *"$__opengeni_token"*) ;; *) exit 0 ;; esac',
+    `__opengeni_live_pgid="$(command ps -o pgid= -p "$__opengeni_pid" 2>/dev/null | command tr -d '[:space:]')"`,
+    '[ "$__opengeni_live_pgid" = "$__opengeni_pgid" ] || exit 0',
+    body
+  ].join("\n");
+}
+function wrapComputer(computer, track) {
+  const wrapped = Object.create(Object.getPrototypeOf(computer));
+  const wrappedRecord = wrapped;
+  Object.assign(wrapped, computer);
+  for (const method of [
+    "initRun",
+    "screenshot",
+    "click",
+    "doubleClick",
+    "scroll",
+    "type",
+    "wait",
+    "move",
+    "keypress",
+    "drag"
+  ]) {
+    const original = computer[method];
+    if (typeof original !== "function") continue;
+    wrappedRecord[method] = (...args) => track(async () => await original.apply(computer, args));
+  }
+  return wrapped;
+}
+var TurnToolCancellationControllerImpl = class {
+  cancelled = false;
+  reason;
+  inFlight = /* @__PURE__ */ new Set();
+  shellSessions = /* @__PURE__ */ new Map();
+  remoteExecs = /* @__PURE__ */ new Set();
+  rawExecInvoke = null;
+  rawWriteInvoke = null;
+  drainPromise = null;
+  signal;
+  onAbort = () => this.cancel(this.signal?.reason);
+  constructor(signal) {
+    this.signal = signal;
+    if (signal?.aborted) {
+      this.cancel(signal.reason);
+    } else {
+      signal?.addEventListener("abort", this.onAbort, { once: true });
+    }
+  }
+  cancel(reason) {
+    if (!this.cancelled) {
+      this.cancelled = true;
+      this.reason = reason;
+      this.signal?.removeEventListener("abort", this.onAbort);
+    }
+    void this.ensureDrain().catch(() => void 0);
+  }
+  async waitForQuiescence() {
+    this.cancel(this.reason);
+    await this.ensureDrain();
+  }
+  runSandboxCommand(session, args) {
+    return this.runSandboxCommandInternal(session, args, false);
+  }
+  async runSandboxCommandStructured(session, args) {
+    return await this.runSandboxCommandInternal(session, args, true);
+  }
+  runSandboxCommandInternal(session, args, structured) {
+    return this.track(async () => {
+      const startedAt = performance.now();
+      if (!session.exec && !session.execCommand) {
+        throw new Error("Sandbox session does not support command execution");
+      }
+      const lifecycleRunContext = {};
+      const invokeExecNative = async (input) => {
+        const parsed = parsedObject(input);
+        if (!parsed || typeof parsed.cmd !== "string") {
+          throw new Error("Sandbox lifecycle command input was invalid");
+        }
+        const commandArgs = {
+          cmd: parsed.cmd,
+          ...typeof parsed.workdir === "string" ? { workdir: parsed.workdir } : {},
+          ...typeof parsed.shell === "string" ? { shell: parsed.shell } : {},
+          ...typeof parsed.login === "boolean" ? { login: parsed.login } : {},
+          ...typeof parsed.tty === "boolean" ? { tty: parsed.tty } : {},
+          ...typeof parsed.yield_time_ms === "number" ? { yieldTimeMs: parsed.yield_time_ms } : {},
+          ...typeof parsed.max_output_tokens === "number" ? { maxOutputTokens: parsed.max_output_tokens } : {},
+          ...typeof parsed.run_as === "string" ? { runAs: parsed.run_as } : {}
+        };
+        const result = session.supportsPty?.() !== false && session.execCommand ? await session.execCommand(commandArgs) : session.exec ? await session.exec(commandArgs) : await session.execCommand(commandArgs);
+        return result;
+      };
+      const invokeExec = async (_runContext, input) => nativeCommandBanner(await invokeExecNative(input));
+      const invokeWrite = session.writeStdin || session.writeStdinForProcessControl ? async (_runContext, input) => {
+        const parsed = parsedObject(input);
+        if (!parsed || typeof parsed.session_id !== "number") {
+          throw new Error("Sandbox lifecycle stdin input was invalid");
+        }
+        const directArgs = {
+          sessionId: parsed.session_id,
+          ...typeof parsed.chars === "string" ? { chars: parsed.chars } : {},
+          ...typeof parsed.yield_time_ms === "number" ? { yieldTimeMs: parsed.yield_time_ms } : {},
+          ...typeof parsed.max_output_tokens === "number" ? { maxOutputTokens: parsed.max_output_tokens } : {}
+        };
+        if (session.hasRetainedProcess?.(parsed.session_id) === true && session.writeStdinForProcessControl) {
+          return await session.writeStdinForProcessControl(directArgs);
+        }
+        if (!session.writeStdin) {
+          throw new Error(
+            "Sandbox lifecycle command yielded an unretained session without stdin support"
+          );
+        }
+        return await session.writeStdin(directArgs);
+      } : null;
+      const correlationId = `turn_lifecycle_${crypto.randomUUID()}`;
+      const useRemoteOpCancellation = Boolean(session.cancelExecCommand) && session.supportsPty?.() === false;
+      const remoteExec = session.cancelExecCommand && useRemoteOpCancellation ? this.registerRemoteExec(
+        { cancelExecCommand: session.cancelExecCommand.bind(session) },
+        `${sanitizeOpIdToken(correlationId)}:0`
+      ) : null;
+      const markerPath = shellMarkerPath(crypto.randomUUID());
+      const commandInput = JSON.stringify({
+        cmd: useRemoteOpCancellation ? args.cmd : cancellableShellCommand(args.cmd, markerPath),
+        ...args.workdir ? { workdir: args.workdir } : {},
+        ...args.shell ? { shell: args.shell } : {},
+        ...args.login !== void 0 ? { login: args.login } : {},
+        ...args.runAs ? { run_as: args.runAs } : {},
+        tty: useRemoteOpCancellation ? args.tty : true,
+        yield_time_ms: useRemoteOpCancellation ? args.yieldTimeMs : cappedYield(args.yieldTimeMs, TURN_EXEC_YIELD_MS),
+        ...args.maxOutputTokens !== void 0 ? { max_output_tokens: args.maxOutputTokens } : {}
+      });
+      let initialNative;
+      try {
+        initialNative = await runWithToolCallCorrelation(
+          correlationId,
+          async () => await invokeExecNative(commandInput)
+        );
+      } finally {
+        remoteExec?.settle();
+      }
+      const initial = nativeCommandBanner(initialNative);
+      const initialResult = nativeCommandResult(initialNative);
+      if (useRemoteOpCancellation) {
+        if (!structured) return initial;
+        if (initialResult.exitCode === null) {
+          throw new Error("Sandbox command did not report a terminal exit code");
+        }
+        return {
+          stdout: initialResult.stdout,
+          stderr: initialResult.stderr,
+          exitCode: initialResult.exitCode,
+          wallTimeSeconds: Math.max(
+            initialResult.wallTimeSeconds,
+            (performance.now() - startedAt) / 1e3
+          )
+        };
+      }
+      const sessionId = parseExecBannerSessionId(initial);
+      if (sessionId === null) {
+        if (!structured) return initial;
+        if (initialResult.exitCode === null) {
+          throw new Error("Sandbox command did not report a terminal exit code");
+        }
+        return {
+          stdout: initialResult.stdout,
+          stderr: initialResult.stderr,
+          exitCode: initialResult.exitCode,
+          wallTimeSeconds: Math.max(
+            initialResult.wallTimeSeconds,
+            (performance.now() - startedAt) / 1e3
+          )
+        };
+      }
+      if (!invokeWrite) {
+        throw new Error("Sandbox lifecycle command yielded without stdin support");
+      }
+      const token = markerPath.slice(markerPath.lastIndexOf("/") + 1);
+      const state = {
+        sessionId,
+        markerPath,
+        token,
+        runContext: lifecycleRunContext,
+        execInvoke: invokeExec,
+        writeInvoke: invokeWrite,
+        processSession: retainedProcessSession(session, sessionId),
+        identity: null,
+        identityValidated: false,
+        cancellation: null
+      };
+      this.shellSessions.set(sessionId, state);
+      const maxOutputTokens = args.maxOutputTokens ?? 2e4;
+      const initialOutput = execOutput(initial);
+      let output = initialOutput ? appendBoundedOutput3("", initialOutput, maxOutputTokens) : "";
+      let stdout = appendBoundedOutput3("", initialResult.stdout, maxOutputTokens);
+      const stderr = appendBoundedOutput3("", initialResult.stderr, maxOutputTokens);
+      while (true) {
+        if (this.cancelled) throw cancellationError(this.reason);
+        const next = await invokeWrite(
+          lifecycleRunContext,
+          JSON.stringify({
+            session_id: sessionId,
+            chars: "",
+            yield_time_ms: TURN_WRITE_YIELD_MS,
+            max_output_tokens: maxOutputTokens
+          }),
+          void 0
+        );
+        if (typeof next !== "string") {
+          throw new Error("Sandbox lifecycle stdin returned an invalid result");
+        }
+        const nextOutput = execOutput(next);
+        if (nextOutput) {
+          output = appendBoundedOutput3(output, nextOutput, maxOutputTokens);
+          stdout = appendBoundedOutput3(stdout, nextOutput, maxOutputTokens);
+        }
+        const exitCode = parseExecBannerExitCode(next);
+        if (exitCode !== null) {
+          this.shellSessions.delete(sessionId);
+          if (!structured) return completedCommandBanner(exitCode, output);
+          return {
+            stdout,
+            stderr,
+            exitCode,
+            wallTimeSeconds: (performance.now() - startedAt) / 1e3
+          };
+        }
+        await delay(SHELL_POLL_MS);
+      }
+    });
+  }
+  wrapTools(tools, session) {
+    const structuralTools = tools;
+    for (const tool of structuralTools) {
+      if (tool.type !== "function") continue;
+      const functionTool = tool;
+      if (functionTool.name === "exec_command") this.rawExecInvoke = functionTool.invoke;
+      if (functionTool.name === "write_stdin") this.rawWriteInvoke = functionTool.invoke;
+    }
+    return structuralTools.map((tool) => {
+      if (tool.type === "function") return this.wrapFunctionTool(tool, session);
+      if (tool.type === "apply_patch") return this.wrapApplyPatchTool(tool);
+      if (tool.type === "computer") return this.wrapComputerTool(tool);
+      return tool;
+    });
+  }
+  wrapFunctionTool(tool, cancellationSession) {
+    if (tool.name === "exec_command") {
+      return {
+        ...tool,
+        invoke: (runContext, input, details) => this.track(async () => {
+          const parsed = parsedObject(input);
+          if (!parsed || typeof parsed.cmd !== "string") {
+            return await this.correlatedInvoke(tool.invoke, runContext, input, details);
+          }
+          const token = crypto.randomUUID();
+          const markerPath = shellMarkerPath(token);
+          const correlationId = details?.toolCall?.callId ?? `turn_exec_${token}`;
+          const cancelExecCommand = cancellationSession?.cancelExecCommand;
+          const useRemoteOpCancellation = Boolean(cancelExecCommand) && cancellationSession?.supportsPty?.() === false;
+          const remoteExec = cancelExecCommand && useRemoteOpCancellation ? this.registerRemoteExec(
+            { cancelExecCommand: cancelExecCommand.bind(cancellationSession) },
+            `${sanitizeOpIdToken(correlationId)}:0`
+          ) : null;
+          const cancellableInput = useRemoteOpCancellation ? input : JSON.stringify({
+            ...parsed,
+            cmd: cancellableShellCommand(parsed.cmd, markerPath),
+            // The SDK's only provider-neutral live-process interrupt is a PTY.
+            // The process marker provides TERM/KILL escalation when Ctrl-C is
+            // ignored; the short yield exposes the provider session promptly.
+            tty: true,
+            yield_time_ms: cappedYield(parsed.yield_time_ms, TURN_EXEC_YIELD_MS)
+          });
+          let output;
+          try {
+            output = await runWithToolCallCorrelation(
+              correlationId,
+              async () => await tool.invoke(runContext, cancellableInput, details)
+            );
+          } finally {
+            remoteExec?.settle();
+          }
+          if (typeof output !== "string") return output;
+          const sessionId = useRemoteOpCancellation ? null : parseExecBannerSessionId(output);
+          if (sessionId !== null) {
+            this.shellSessions.set(sessionId, {
+              sessionId,
+              markerPath,
+              token,
+              runContext,
+              execInvoke: tool.invoke,
+              writeInvoke: this.rawWriteInvoke,
+              processSession: retainedProcessSession(cancellationSession, sessionId),
+              identity: null,
+              identityValidated: false,
+              cancellation: null
+            });
+          }
+          return output;
+        })
+      };
+    }
+    if (tool.name === "write_stdin") {
+      return {
+        ...tool,
+        invoke: (runContext, input, details) => this.track(async () => {
+          const parsed = parsedObject(input);
+          const sessionId = parsed && typeof parsed.session_id === "number" && Number.isSafeInteger(parsed.session_id) ? parsed.session_id : null;
+          const cappedInput = parsed ? JSON.stringify({
+            ...parsed,
+            yield_time_ms: cappedYield(parsed.yield_time_ms, TURN_WRITE_YIELD_MS)
+          }) : input;
+          const directProcessSession = sessionId === null ? null : retainedProcessSession(cancellationSession, sessionId);
+          const output = sessionId !== null && directProcessSession?.writeStdinForProcessMutation ? await directProcessSession.writeStdinForProcessMutation({
+            sessionId,
+            ...typeof parsed?.chars === "string" ? { chars: parsed.chars } : {},
+            yieldTimeMs: cappedYield(parsed?.yield_time_ms, TURN_WRITE_YIELD_MS),
+            ...typeof parsed?.max_output_tokens === "number" ? { maxOutputTokens: parsed.max_output_tokens } : {}
+          }) : await tool.invoke(runContext, cappedInput, details);
+          if (sessionId !== null && typeof output === "string") {
+            if (isExecSessionLostBanner(output, sessionId)) {
+              this.shellSessions.delete(sessionId);
+            } else if (parseExecBannerSessionId(output) === sessionId) {
+              if (!this.shellSessions.has(sessionId)) {
+                this.shellSessions.set(sessionId, {
+                  sessionId,
+                  markerPath: null,
+                  token: null,
+                  runContext,
+                  execInvoke: this.rawExecInvoke ?? tool.invoke,
+                  writeInvoke: tool.invoke,
+                  processSession: directProcessSession,
+                  identity: null,
+                  identityValidated: false,
+                  cancellation: null
+                });
+              }
+            } else if (parseExecBannerExitCode(output) !== null) {
+              this.shellSessions.delete(sessionId);
+            }
+          }
+          return output;
+        })
+      };
+    }
+    return {
+      ...tool,
+      invoke: (runContext, input, details) => this.track(async () => await tool.invoke(runContext, input, details))
+    };
+  }
+  wrapApplyPatchTool(tool) {
+    const editor = tool.editor;
+    const wrappedEditor = {
+      createFile: (operation, context) => this.track(async () => await editor.createFile(operation, context)),
+      updateFile: (operation, context) => this.track(async () => await editor.updateFile(operation, context)),
+      deleteFile: (operation, context) => this.track(async () => await editor.deleteFile(operation, context))
+    };
+    return { ...tool, editor: wrappedEditor };
+  }
+  wrapComputerTool(tool) {
+    const computer = tool.computer;
+    if (typeof computer === "function") {
+      const createComputer = computer;
+      return {
+        ...tool,
+        computer: async (...args) => wrapComputer(
+          await this.track(async () => await createComputer(...args)),
+          (operation) => this.track(operation)
+        )
+      };
+    }
+    if (computer && typeof computer === "object" && "create" in computer) {
+      const provider = computer;
+      if (typeof provider.create !== "function") return tool;
+      const createComputer = provider.create;
+      return {
+        ...tool,
+        computer: {
+          ...provider,
+          create: async (...args) => wrapComputer(
+            await this.track(async () => await createComputer(...args)),
+            (operation) => this.track(operation)
+          )
+        }
+      };
+    }
+    if (!computer || typeof computer !== "object") return tool;
+    return {
+      ...tool,
+      computer: wrapComputer(computer, (operation) => this.track(operation))
+    };
+  }
+  async correlatedInvoke(invoke, runContext, input, details) {
+    const callId = details?.toolCall?.callId;
+    return callId ? await runWithToolCallCorrelation(
+      callId,
+      async () => await invoke(runContext, input, details)
+    ) : await invoke(runContext, input, details);
+  }
+  track(operation) {
+    if (this.cancelled) return Promise.reject(cancellationError(this.reason));
+    const promise = Promise.resolve().then(async () => {
+      if (this.cancelled) throw cancellationError(this.reason);
+      return await operation();
+    });
+    this.inFlight.add(promise);
+    void promise.finally(() => {
+      this.inFlight.delete(promise);
+    }).catch(() => void 0);
+    return promise;
+  }
+  ensureDrain() {
+    this.drainPromise ??= this.drain();
+    return this.drainPromise;
+  }
+  async drain() {
+    while (true) {
+      const remoteCancellations = [...this.remoteExecs].map(async (exec) => await exec.cancel());
+      const inFlight = [...this.inFlight];
+      if (inFlight.length > 0 || remoteCancellations.length > 0) {
+        await Promise.allSettled([...inFlight, ...remoteCancellations]);
+      }
+      const sessions = [...this.shellSessions.values()];
+      if (sessions.length > 0) {
+        await Promise.all(sessions.map(async (session) => await this.cancelShellSession(session)));
+      }
+      if (this.inFlight.size === 0 && this.shellSessions.size === 0 && this.remoteExecs.size === 0)
+        return;
+    }
+  }
+  registerRemoteExec(session, opId) {
+    let resolveSettled;
+    const settledPromise = new Promise((resolve5) => {
+      resolveSettled = resolve5;
+    });
+    let cancellation = null;
+    const entry = {
+      settled: false,
+      settledPromise,
+      settle: () => {
+        if (entry.settled) return;
+        entry.settled = true;
+        resolveSettled();
+        this.remoteExecs.delete(entry);
+      },
+      cancel: () => {
+        cancellation ??= (async () => {
+          while (!entry.settled) {
+            const attempt = session.cancelExecCommand(opId).catch(() => false);
+            await Promise.race([attempt, entry.settledPromise]);
+            await Promise.race([entry.settledPromise, delay(SHELL_POLL_MS)]);
+          }
+        })();
+        return cancellation;
+      }
+    };
+    this.remoteExecs.add(entry);
+    return entry;
+  }
+  cancelShellSession(state) {
+    state.cancellation ??= this.cancelShellSessionOnce(state).finally(() => {
+      state.cancellation = null;
+    });
+    return state.cancellation;
+  }
+  async cancelShellSessionOnce(state) {
+    if (!state.markerPath) {
+      while (true) {
+        if ((state.writeInvoke || state.processSession?.writeStdinForProcessControl) && await this.rawWrite(state, "", SHELL_POLL_MS)) {
+          await this.forgetShellSessionAfterExactSettlement(state);
+          return;
+        }
+        await delay(SHELL_POLL_MS);
+      }
+    }
+    while (!state.identity) {
+      state.identity = await this.readIdentity(state);
+      if (state.identity) break;
+      if (state.writeInvoke || state.processSession?.writeStdinForProcessControl) {
+        const completed = await this.rawWrite(state, "", SHELL_POLL_MS);
+        if (completed) {
+          await this.forgetShellSessionAfterExactSettlement(state);
+          return;
+        }
+      }
+      await delay(SHELL_POLL_MS);
+    }
+    if (!await this.identityAlive(state)) {
+      await this.forgetShellSessionAfterExactSettlement(state);
+      return;
+    }
+    if (!state.processSession && state.writeInvoke) {
+      await this.rawWrite(state, "", SHELL_POLL_MS);
+      if (!await this.identityAlive(state)) {
+        await this.forgetShellSessionAfterExactSettlement(state);
+        return;
+      }
+    }
+    await this.signalIdentity(state, "TERM");
+    for (let attempt = 0; attempt < SHELL_GRACEFUL_POLLS; attempt++) {
+      if (!state.processSession && state.writeInvoke) {
+        await this.rawWrite(state, "", SHELL_POLL_MS);
+      }
+      if (!await this.identityAlive(state)) {
+        await this.forgetShellSessionAfterExactSettlement(state);
+        return;
+      }
+    }
+    await this.signalIdentity(state, "KILL");
+    while (await this.identityAlive(state)) {
+      if (!state.processSession && state.writeInvoke) {
+        await this.rawWrite(state, "", SHELL_POLL_MS);
+      }
+      await this.signalIdentity(state, "KILL");
+      await delay(SHELL_POLL_MS);
+    }
+    await this.forgetShellSessionAfterExactSettlement(state);
+  }
+  async forgetShellSessionAfterExactSettlement(state) {
+    while (state.processSession?.hasRetainedProcess?.(state.sessionId) === true) {
+      if (await this.rawWrite(state, "", SHELL_POLL_MS)) break;
+      await delay(SHELL_POLL_MS);
+    }
+    this.shellSessions.delete(state.sessionId);
+  }
+  async rawWrite(state, chars, yieldTimeMs) {
+    if (!state.writeInvoke && !state.processSession?.writeStdinForProcessControl) return false;
+    try {
+      const output = state.processSession?.writeStdinForProcessControl ? await state.processSession.writeStdinForProcessControl({
+        sessionId: state.sessionId,
+        chars,
+        yieldTimeMs,
+        maxOutputTokens: 128
+      }) : await state.writeInvoke(
+        state.runContext,
+        JSON.stringify({
+          session_id: state.sessionId,
+          chars,
+          yield_time_ms: yieldTimeMs,
+          max_output_tokens: 128
+        }),
+        void 0
+      );
+      if (typeof output !== "string") return false;
+      if (isExecSessionLostBanner(output, state.sessionId)) return true;
+      if (parseExecBannerSessionId(output) === state.sessionId) return false;
+      if (parseExecBannerExitCode(output) !== null) return true;
+    } catch {
+    }
+    return false;
+  }
+  async readIdentity(state) {
+    if (!state.markerPath) return null;
+    try {
+      const command = `command cat ${singleQuote(state.markerPath)} 2>/dev/null`;
+      const output = state.processSession?.execCommandForProcessControl ? await state.processSession.execCommandForProcessControl(
+        state.sessionId,
+        shellHelperArgs(command)
+      ) : await state.execInvoke(state.runContext, shellHelperInput(command), void 0);
+      return typeof output === "string" ? safeProcessIdentity(output) : null;
+    } catch {
+      return null;
+    }
+  }
+  async identityAlive(state) {
+    const script = state.identityValidated ? [
+      `__opengeni_pgid=${state.identity?.processGroupId ?? 0}`,
+      'command kill -0 "-$__opengeni_pgid" 2>/dev/null && exit 75',
+      "exit 0"
+    ].join("\n") : identityGuardScript(
+      state,
+      'command kill -0 "-$__opengeni_pgid" 2>/dev/null && exit 75\nexit 0',
+      76
+    );
+    try {
+      const output = state.processSession?.execCommandForProcessControl ? await state.processSession.execCommandForProcessControl(
+        state.sessionId,
+        shellHelperArgs(script)
+      ) : await state.execInvoke(state.runContext, shellHelperInput(script), void 0);
+      if (typeof output !== "string") return true;
+      const exitCode = parseExecBannerExitCode(output);
+      if (exitCode === 75) {
+        state.identityValidated = true;
+        return true;
+      }
+      return exitCode !== 0;
+    } catch {
+      return true;
+    }
+  }
+  async signalIdentity(state, signal) {
+    const script = state.identityValidated ? `command kill -${signal} "-${state.identity?.processGroupId ?? 0}" 2>/dev/null || exit 76` : identityGuardScript(
+      state,
+      `command kill -${signal} "-$__opengeni_pgid" 2>/dev/null || exit 76
+exit 0`,
+      76
+    );
+    try {
+      if (state.processSession?.execCommandForProcessControl) {
+        await state.processSession.execCommandForProcessControl(
+          state.sessionId,
+          shellHelperArgs(script)
+        );
+      } else {
+        await state.execInvoke(state.runContext, shellHelperInput(script), void 0);
+      }
+    } catch {
+    }
+  }
+};
+function createTurnToolCancellationController(signal) {
+  return new TurnToolCancellationControllerImpl(signal);
 }
-function recordingStorageKey(workspaceId, sessionId, recordingId, codec) {
-  return `recordings/${workspaceId}/${sessionId}/${recordingId}.${extForCodec(codec)}`;
+function wrapCapabilityToolsForTurnCancellation(capability, controller) {
+  const originalTools = capability.tools;
+  capability.tools = function() {
+    return controller.wrapTools(originalTools.call(this), this._session);
+  };
 }
 
 // src/sandbox/channel-a.ts
@@ -20273,17 +21369,49 @@ var SandboxChannelAService = class {
     return (await this.detectReposDetailed()).repos;
   }
   // ════════════════════════ Terminal exec + PTY (A2) ════════════════════════
-  /** Run a bounded command, return buffered stdout/stderr + exit code inline. The
-   *  long-running tail (when the process hasn't exited within timeoutMs) keeps
-   *  running in-box; if emitStream is set the buffered output is also published as
-   *  the agent firehose so other viewers see it. */
+  /** Run a bounded command to physical completion and return buffered output.
+   *  A deadline cancels the exact provider operation, proves its process group
+   *  absent, and settles any retained-process admission before returning 124. */
   async terminalExec(req) {
-    const r = await this.run({
-      cmd: req.command,
-      workdir: this.terminalWorkdir(req.cwd),
-      yieldTimeMs: req.timeoutMs
-    });
-    const running = r.exitCode === null && typeof r.sessionId === "number";
+    const abort = new AbortController();
+    const controller = createTurnToolCancellationController(abort.signal);
+    const timeoutReason = new Error(`Terminal command exceeded ${req.timeoutMs}ms`);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      abort.abort(timeoutReason);
+    }, req.timeoutMs);
+    const terminalWorkdir = this.terminalWorkdir(req.cwd);
+    let r;
+    try {
+      r = await controller.runSandboxCommandStructured(this.session, {
+        cmd: req.command,
+        ...terminalWorkdir ? { workdir: terminalWorkdir } : {},
+        ...this.runAs ? { runAs: this.runAs } : {},
+        yieldTimeMs: req.timeoutMs
+      });
+      if (timedOut) {
+        await controller.waitForQuiescence();
+        r = {
+          stdout: "",
+          stderr: timeoutReason.message,
+          exitCode: 124,
+          wallTimeSeconds: req.timeoutMs / 1e3
+        };
+      }
+    } catch (error) {
+      controller.cancel(error);
+      await controller.waitForQuiescence();
+      if (!timedOut && !(error instanceof TurnSandboxCommandCancelledError)) throw error;
+      r = {
+        stdout: "",
+        stderr: timeoutReason.message,
+        exitCode: 124,
+        wallTimeSeconds: req.timeoutMs / 1e3
+      };
+    } finally {
+      clearTimeout(timer);
+    }
     if (req.emitStream && (r.stdout || r.stderr)) {
       const events = [];
       const commandId = crypto.randomUUID();
@@ -20303,7 +21431,7 @@ var SandboxChannelAService = class {
       stdout: r.stdout,
       stderr: r.stderr,
       exitCode: r.exitCode,
-      running,
+      running: false,
       wallTimeSeconds: r.wallTimeSeconds
     };
   }
@@ -20333,10 +21461,11 @@ var SandboxChannelAService = class {
    *  it as terminal.pty.output.delta). Throws ChannelAUnsupportedError when the
    *  backend has no writeStdin. */
   async ptyWrite(_req, execSessionId, data) {
-    if (!this.session.writeStdin) {
+    const write = this.session.writeStdinForProcessMutation?.bind(this.session) ?? this.session.writeStdin?.bind(this.session);
+    if (!write) {
       throw new ChannelAUnsupportedError("interactive terminal unsupported on this backend");
     }
-    const out = await this.session.writeStdin({
+    const out = await write({
       sessionId: execSessionId,
       chars: data,
       yieldTimeMs: 250
@@ -20349,23 +21478,22 @@ var SandboxChannelAService = class {
   /** Resize an open PTY (SIGWINCH via stty against the exec-session). The SDK has
    *  no resize method; stty in the same tty session updates the geometry. */
   async ptyResize(req, execSessionId) {
-    if (!this.session.writeStdin) return;
-    await this.session.writeStdin({
+    const write = this.session.writeStdinForProcessControl?.bind(this.session) ?? this.session.writeStdin?.bind(this.session);
+    if (!write) return;
+    await write({
       sessionId: execSessionId,
       chars: `stty cols ${req.cols} rows ${req.rows}
 `,
       yieldTimeMs: 50
     });
   }
-  /** Close an open PTY: write exit/EOF. The caller marks the row closed + emits
-   *  terminal.pty.exited. */
+  /** Ask an open PTY to exit and return the exact provider banner. The routing
+   * session settles durable process authority only when that banner proves this
+   * locator exited or was lost; callers must keep metadata open otherwise. */
   async ptyClose(_req, execSessionId) {
-    if (execSessionId !== null && this.session.writeStdin) {
-      try {
-        await this.session.writeStdin({ sessionId: execSessionId, chars: "", yieldTimeMs: 50 });
-      } catch {
-      }
-    }
+    const write = this.session.writeStdinForProcessControl?.bind(this.session) ?? this.session.writeStdin?.bind(this.session);
+    if (execSessionId === null || !write) return "";
+    return await write({ sessionId: execSessionId, chars: "", yieldTimeMs: 250 });
   }
   // ──────────────────────────── helpers ──────────────────────────────────────
   /** The current FS revision (for the caller to persist/seed). */
@@ -20497,12 +21625,6 @@ function isDefinitePathNotFoundError(error) {
   const candidate = error;
   return candidate.osNotFound === true || candidate.code === "ENOENT" || candidate.errno === "ENOENT" || candidate.errno === -2;
 }
-function isExecSessionLostBanner(out, execSessionId) {
-  if (!out || !Number.isSafeInteger(execSessionId) || execSessionId < 0) return false;
-  const match = out.match(/^(?:write_stdin failed: )?session not found: (\d+)$/);
-  if (!match || match[0] !== out) return false;
-  return match[1] === String(execSessionId);
-}
 function sniffBinary(bytes) {
   const n = Math.min(bytes.byteLength, 8192);
   for (let i = 0; i < n; i++) if (bytes[i] === 0) return true;
@@ -21099,6 +22221,35 @@ var RoutingUnsupportedError = class extends Error {
     super(`the active sandbox (${kind}) does not support "${op}"`);
   }
 };
+var RoutingBackendRecoveryRequiredError = class extends Error {
+  constructor(op, leaseEpoch, recovery) {
+    super(
+      `sandbox backend disappeared during ${op}; recovery is ${recovery} at epoch ${leaseEpoch}`
+    );
+    this.op = op;
+    this.leaseEpoch = leaseEpoch;
+    this.recovery = recovery;
+    this.retryable = recovery === "pending" || recovery === "superseded";
+  }
+  name = "RoutingBackendRecoveryRequiredError";
+  retryable;
+};
+var RoutingMutationOutcomeUnknownError = class extends Error {
+  constructor(op, message, options) {
+    super(message, options);
+    this.op = op;
+  }
+  name = "RoutingMutationOutcomeUnknownError";
+  retryable = false;
+};
+var RoutingRetainedProcessNotFoundError = class extends Error {
+  constructor(providerSessionId) {
+    super(`retained sandbox process ${providerSessionId} is not tracked on its original route`);
+    this.providerSessionId = providerSessionId;
+  }
+  name = "RoutingRetainedProcessNotFoundError";
+  retryable = false;
+};
 function isFenceError(error) {
   if (!error || typeof error !== "object") {
     return false;
@@ -21111,6 +22262,59 @@ function isFenceError(error) {
   const haystack = `${name} ${message}`.toLowerCase();
   return haystack.includes("fenced") || haystack.includes("epoch") && haystack.includes("super");
 }
+function positiveProviderSessionId(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : null;
+}
+function canonicalUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function providerSessionIdFromResult(result) {
+  if (typeof result === "string") {
+    return positiveProviderSessionId(parseExecBannerSessionId(result));
+  }
+  if (!result || typeof result !== "object") return null;
+  const record = result;
+  return positiveProviderSessionId(record.sessionId) ?? positiveProviderSessionId(record.session_id);
+}
+function providerSessionIdFromArgs(args) {
+  if (!args || typeof args !== "object") return null;
+  const record = args;
+  return positiveProviderSessionId(record.sessionId) ?? positiveProviderSessionId(record.session_id);
+}
+function retainedProcessTerminalProof(result, providerSessionId) {
+  if (isExecSessionLostBanner(result, providerSessionId)) {
+    return {
+      outcome: "lost",
+      exitCode: null,
+      reason: "provider_session_lost_banner"
+    };
+  }
+  const exitCode = parseExecBannerExitCode(result);
+  return exitCode === null ? null : { outcome: "exited", exitCode, reason: "provider_exit_banner" };
+}
+function formatExecResult(result) {
+  if (typeof result === "string") return result;
+  if (!result || typeof result !== "object") {
+    throw new Error("sandbox process-control exec returned an invalid result");
+  }
+  const record = result;
+  const output = [record.output, record.stderr, record.stdout].filter((value) => typeof value === "string" && value.length > 0).join("\n");
+  const sessionId = positiveProviderSessionId(record.sessionId) ?? positiveProviderSessionId(record.session_id);
+  if (sessionId !== null) {
+    return `Process running with session ID ${sessionId}
+
+Output:
+${output}`;
+  }
+  const exitCode = typeof record.exitCode === "number" ? record.exitCode : typeof record.exit_code === "number" ? record.exit_code : null;
+  if (exitCode !== null && Number.isSafeInteger(exitCode)) {
+    return `Process exited with code ${exitCode}
+
+Output:
+${output}`;
+  }
+  throw new Error("sandbox process-control exec reported neither session id nor exit code");
+}
 var RoutingSandboxSession = class {
   deps;
   maxFenceRetries;
@@ -21129,6 +22333,10 @@ var RoutingSandboxSession = class {
   // The last-resolved backend, exposed via the `state` getter (a method-free read
   // of the active backend's `state`). Updated on every resolve.
   lastResolved;
+  /** Provider session ids are scoped to one backend instance. Each entry copies
+   * that exact resolved route so pointer movement can never redirect stdin,
+   * polling, or process-group helpers to another box. */
+  retainedProcesses = /* @__PURE__ */ new Map();
   // The native-desktop control-plane ops (self-hosted / macOS). Declared as OPTIONAL
   // INSTANCE fields — NOT prototype methods — because their PRESENCE is the selection
   // signal `isNativeDesktopSession` (sandbox-computer.ts) uses to pick the native vs
@@ -21144,13 +22352,13 @@ var RoutingSandboxSession = class {
     this.maxFenceRetries = deps.maxFenceRetries ?? 3;
     const def = deps.defaultResolved?.session;
     if (typeof def?.desktopInput === "function" && typeof def?.screenshot === "function") {
-      this.desktopInput = (event) => this.dispatch("desktopInput", async (s) => {
+      this.desktopInput = (event) => this.dispatch("desktopInput", true, async (s) => {
         if (!s.desktopInput) {
           throw new RoutingUnsupportedError("desktopInput", this.cached?.kind ?? "unknown");
         }
         return s.desktopInput(event);
       });
-      this.screenshot = () => this.dispatch("screenshot", async (s) => {
+      this.screenshot = () => this.dispatch("screenshot", false, async (s) => {
         if (!s.screenshot) {
           throw new RoutingUnsupportedError("screenshot", this.cached?.kind ?? "unknown");
         }
@@ -21195,18 +22403,256 @@ var RoutingSandboxSession = class {
         "RoutingSandboxSession.resolveActiveBackend returned the proxy itself as the active backend (re-entrancy) \u2014 the resolver must return the underlying box session, not the routing proxy."
       );
     }
+    const routed = {
+      ...resolved,
+      activeEpoch: pointer.activeEpoch
+    };
     this.cachedEpoch = pointer.activeEpoch;
     this.cachedSandboxId = pointer.activeSandboxId;
-    this.cached = resolved;
-    this.lastResolved = resolved;
+    this.cached = routed;
+    this.lastResolved = routed;
     this.deps.onTransition?.({
       type: this.cachedEpoch !== void 0 && fromEpoch !== pointer.activeEpoch ? "epoch-changed" : "resolved",
       fromEpoch,
       toEpoch: pointer.activeEpoch,
-      sandboxId: resolved.sandboxId,
-      kind: resolved.kind
+      sandboxId: routed.sandboxId,
+      kind: routed.kind
     });
-    return resolved;
+    return routed;
+  }
+  invalidate(backend) {
+    this.cachedEpoch = void 0;
+    this.cachedSandboxId = void 0;
+    this.cached = void 0;
+    this.deps.onTransition?.({
+      type: "fenced-retry",
+      fromEpoch: backend.activeEpoch ?? 0,
+      toEpoch: 0,
+      sandboxId: backend.sandboxId,
+      kind: backend.kind
+    });
+  }
+  registerRetainedProcess(process2, backend) {
+    if (this.retainedProcesses.has(process2.providerSessionId)) {
+      throw new RoutingMutationOutcomeUnknownError(
+        "retainProcess",
+        `Provider session ${process2.providerSessionId} was yielded while that locator was already retained; neither process was rebound`
+      );
+    }
+    const record = {
+      process: process2,
+      backend,
+      durable: !this.deps.afterMutation,
+      pendingParentPromotion: null,
+      pendingMutationSettlement: null,
+      pendingTerminal: null,
+      settlement: null
+    };
+    this.retainedProcesses.set(process2.providerSessionId, record);
+    return record;
+  }
+  retainedProcess(providerSessionId) {
+    const retained = this.retainedProcesses.get(providerSessionId);
+    if (!retained) throw new RoutingRetainedProcessNotFoundError(providerSessionId);
+    return retained;
+  }
+  /** Reconstruct one process that was already promoted durably by an earlier
+   * request. Adoption never reads the active pointer and never repeats parent
+   * promotion. It can bind only to the exact construction-time default backend;
+   * callers must reject non-default routes until they can independently rebuild
+   * that provider session from its copied durable identity. */
+  adoptRetainedProcess(input) {
+    const providerSessionId = positiveProviderSessionId(input.process.providerSessionId);
+    const seed = this.deps.defaultResolved;
+    if (providerSessionId === null || !canonicalUuid(input.process.id) || !seed || seed.sandboxId !== input.backend.sandboxId || seed.leaseEpoch !== input.backend.leaseEpoch || seed.providerInstanceId !== input.backend.providerInstanceId || !Number.isSafeInteger(input.backend.activeEpoch) || input.backend.activeEpoch < 0) {
+      throw new RoutingMutationOutcomeUnknownError(
+        "adoptRetainedProcess",
+        `Retained provider session ${input.process.providerSessionId} did not match the exact default backend identity`
+      );
+    }
+    const existing = this.retainedProcesses.get(providerSessionId);
+    if (existing) {
+      if (existing.process.id === input.process.id && existing.backend.session === seed.session && existing.backend.sandboxId === input.backend.sandboxId && existing.backend.leaseEpoch === input.backend.leaseEpoch && existing.backend.providerInstanceId === input.backend.providerInstanceId && existing.backend.activeEpoch === input.backend.activeEpoch) {
+        return;
+      }
+      throw new RoutingMutationOutcomeUnknownError(
+        "adoptRetainedProcess",
+        `Provider session ${providerSessionId} is already bound to a different retained process identity`
+      );
+    }
+    this.retainedProcesses.set(providerSessionId, {
+      process: { ...input.process },
+      backend: {
+        ...seed,
+        activeEpoch: input.backend.activeEpoch
+      },
+      durable: true,
+      pendingParentPromotion: null,
+      pendingMutationSettlement: null,
+      pendingTerminal: null,
+      settlement: null
+    });
+  }
+  async ensureParentPromotion(record) {
+    if (record.durable) return;
+    const pending = record.pendingParentPromotion;
+    if (!pending || !this.deps.afterMutation) {
+      throw new RoutingMutationOutcomeUnknownError(
+        "retainProcess",
+        `Retained provider session ${record.process.providerSessionId} has no confirmed durable parent admission`
+      );
+    }
+    try {
+      await this.deps.afterMutation(pending);
+      record.pendingParentPromotion = null;
+      record.durable = true;
+    } catch (error) {
+      throw new RoutingMutationOutcomeUnknownError(
+        pending.op,
+        `Yielded sandbox process ${record.process.providerSessionId} could not confirm its durable promotion; tracking remains pinned to the original backend`,
+        { cause: error }
+      );
+    }
+  }
+  async settleRetainedProcess(record, proof, result) {
+    record.pendingTerminal ??= { proof, result };
+    const pending = record.pendingTerminal;
+    if (pending.proof.outcome !== proof.outcome || pending.proof.exitCode !== proof.exitCode || pending.proof.reason !== proof.reason) {
+      throw new RoutingMutationOutcomeUnknownError(
+        "settleProcess",
+        `Retained provider session ${record.process.providerSessionId} produced conflicting terminal proof`
+      );
+    }
+    record.settlement ??= (async () => {
+      await this.ensureParentPromotion(record);
+      await this.deps.settleProcess?.({
+        backend: record.backend,
+        process: record.process,
+        proof: pending.proof
+      });
+      this.retainedProcesses.delete(record.process.providerSessionId);
+      record.pendingTerminal = null;
+    })();
+    try {
+      await record.settlement;
+    } catch (error) {
+      record.settlement = null;
+      throw new RoutingMutationOutcomeUnknownError(
+        "settleProcess",
+        `Retained provider session ${record.process.providerSessionId} reached a terminal state but durable settlement failed; tracking remains pinned`,
+        { cause: error }
+      );
+    }
+  }
+  async flushPendingProcessMutation(record) {
+    const pending = record.pendingMutationSettlement;
+    if (!pending) return null;
+    try {
+      await this.deps.afterProcessMutation?.(pending);
+      record.pendingMutationSettlement = null;
+    } catch (error) {
+      throw new RoutingMutationOutcomeUnknownError(
+        pending.op,
+        `Retained-process mutation ${pending.op} still lacks durable physical settlement; no later process mutation was admitted`,
+        { cause: error }
+      );
+    }
+    if (pending.outcome === "resolved" && typeof pending.result === "string") {
+      const proof = retainedProcessTerminalProof(pending.result, record.process.providerSessionId);
+      if (proof) {
+        await this.settleRetainedProcess(record, proof, pending.result);
+        return pending.result;
+      }
+    }
+    return null;
+  }
+  async dispatchProcessMutation(args) {
+    const providerSessionId = providerSessionIdFromArgs(args);
+    if (providerSessionId === null) throw new RoutingRetainedProcessNotFoundError(-1);
+    const record = this.retainedProcess(providerSessionId);
+    const priorTerminal = await this.flushPendingProcessMutation(record);
+    if (priorTerminal !== null) return priorTerminal;
+    if (record.pendingTerminal) {
+      const terminal = record.pendingTerminal;
+      await this.settleRetainedProcess(record, terminal.proof, terminal.result);
+      return terminal.result;
+    }
+    await this.ensureParentPromotion(record);
+    const op = "writeStdin";
+    const admission = await this.deps.beforeProcessMutation?.({
+      op,
+      backend: record.backend,
+      process: record.process
+    });
+    const write = record.backend.session.writeStdin;
+    if (!write) throw new RoutingUnsupportedError(op, record.backend.kind);
+    let result;
+    try {
+      result = await write.call(record.backend.session, args);
+    } catch (error) {
+      if (this.deps.afterProcessMutation) {
+        const pending = {
+          op,
+          backend: record.backend,
+          process: record.process,
+          admission,
+          outcome: "rejected"
+        };
+        try {
+          await this.deps.afterProcessMutation(pending);
+        } catch (settlementError) {
+          record.pendingMutationSettlement = pending;
+          throw new RoutingMutationOutcomeUnknownError(
+            op,
+            `Retained-process stdin rejected at the provider but lost durable settlement; it was not replayed`,
+            { cause: settlementError }
+          );
+        }
+      }
+      throw error;
+    }
+    if (this.deps.afterProcessMutation) {
+      const pending = {
+        op,
+        backend: record.backend,
+        process: record.process,
+        admission,
+        outcome: "resolved",
+        result
+      };
+      try {
+        await this.deps.afterProcessMutation(pending);
+      } catch (error) {
+        record.pendingMutationSettlement = pending;
+        throw new RoutingMutationOutcomeUnknownError(
+          op,
+          `Retained-process stdin returned from the provider but lost durable settlement; tracking remains pinned and it was not replayed`,
+          { cause: error }
+        );
+      }
+    }
+    const proof = retainedProcessTerminalProof(result, providerSessionId);
+    if (proof) await this.settleRetainedProcess(record, proof, result);
+    return result;
+  }
+  async dispatchProcessControl(args) {
+    const providerSessionId = providerSessionIdFromArgs(args);
+    if (providerSessionId === null) throw new RoutingRetainedProcessNotFoundError(-1);
+    const record = this.retainedProcess(providerSessionId);
+    const priorTerminal = await this.flushPendingProcessMutation(record);
+    if (priorTerminal !== null) return priorTerminal;
+    if (record.pendingTerminal) {
+      const terminal = record.pendingTerminal;
+      await this.settleRetainedProcess(record, terminal.proof, terminal.result);
+      return terminal.result;
+    }
+    await this.ensureParentPromotion(record);
+    const write = record.backend.session.writeStdin;
+    if (!write) throw new RoutingUnsupportedError("writeStdin", record.backend.kind);
+    const result = await write.call(record.backend.session, args);
+    const proof = retainedProcessTerminalProof(result, providerSessionId);
+    if (proof) await this.settleRetainedProcess(record, proof, result);
+    return result;
   }
   /**
    * Dispatch an op to the currently-active backend, retrying on a stale-epoch
@@ -21219,30 +22665,113 @@ var RoutingSandboxSession = class {
    * A non-fence error propagates immediately (it is a real op failure, not a swap
    * race).
    */
-  async dispatch(op, fn) {
+  async dispatch(op, mutatesWorkspace, fn) {
     let attempt = 0;
     let lastError;
     while (attempt <= this.maxFenceRetries) {
       const backend = await this.resolve();
+      const admission = mutatesWorkspace ? await this.deps.beforeMutation?.({ op, backend }) : void 0;
+      let result;
       try {
-        return await fn(backend.session);
+        result = await fn(backend.session);
       } catch (error) {
+        if (mutatesWorkspace && this.deps.afterMutation) {
+          try {
+            await this.deps.afterMutation({
+              op,
+              backend,
+              admission,
+              outcome: "rejected"
+            });
+          } catch (settlementError) {
+            this.invalidate(backend);
+            throw new RoutingMutationOutcomeUnknownError(
+              op,
+              `Mutating sandbox operation "${op}" rejected at the provider but lost its durable physical settlement; its outcome is unknown and it was not replayed`,
+              { cause: settlementError }
+            );
+          }
+        }
         if (!isFenceError(error)) {
+          if (backend.sandboxId === null && this.deps.onDefaultBackendError) {
+            const loss = await this.deps.onDefaultBackendError({
+              op,
+              error,
+              kind: backend.kind,
+              backend
+            });
+            if (loss) {
+              this.invalidate(backend);
+              throw new RoutingBackendRecoveryRequiredError(op, loss.leaseEpoch, loss.recovery);
+            }
+          }
           throw error;
         }
+        this.invalidate(backend);
+        if (mutatesWorkspace) {
+          throw new RoutingMutationOutcomeUnknownError(
+            op,
+            `Mutating sandbox operation "${op}" was fenced after provider admission; its outcome is unknown and it was not replayed`,
+            { cause: error }
+          );
+        }
         lastError = error;
-        this.cachedEpoch = void 0;
-        this.cachedSandboxId = void 0;
-        this.cached = void 0;
-        this.deps.onTransition?.({
-          type: "fenced-retry",
-          fromEpoch: backend.sandboxId === null ? 0 : 0,
-          toEpoch: 0,
-          sandboxId: backend.sandboxId,
-          kind: backend.kind
-        });
         attempt += 1;
+        continue;
+      }
+      const yieldedSessionId = mutatesWorkspace && (op === "exec" || op === "execCommand") ? providerSessionIdFromResult(result) : null;
+      const retainedProcess = yieldedSessionId === null ? void 0 : { id: crypto.randomUUID(), providerSessionId: yieldedSessionId };
+      const retainedRecord = retainedProcess ? this.registerRetainedProcess(retainedProcess, backend) : null;
+      if (mutatesWorkspace && this.deps.afterMutation) {
+        const settlement = {
+          op,
+          backend,
+          admission,
+          outcome: "resolved",
+          result,
+          ...retainedProcess ? { retainedProcess } : {}
+        };
+        try {
+          await this.deps.afterMutation(settlement);
+          if (retainedRecord) retainedRecord.durable = true;
+        } catch (error) {
+          if (retainedRecord) retainedRecord.pendingParentPromotion = settlement;
+          this.invalidate(backend);
+          throw new RoutingMutationOutcomeUnknownError(
+            op,
+            retainedRecord ? `Mutating sandbox operation "${op}" yielded provider session ${retainedRecord.process.providerSessionId} but lost durable process promotion; exact-backend tracking remains and the operation was not replayed` : `Mutating sandbox operation "${op}" returned from the provider but lost its durable route settlement; its outcome is unknown and it was not replayed`,
+            { cause: error }
+          );
+        }
+      }
+      if (retainedRecord) return result;
+      let current;
+      try {
+        current = await this.deps.readPointer();
+      } catch (error) {
+        if (mutatesWorkspace) {
+          this.invalidate(backend);
+          throw new RoutingMutationOutcomeUnknownError(
+            op,
+            `Mutating sandbox operation "${op}" returned from the provider but its route could not be revalidated; its outcome is unknown and it was not replayed`,
+            { cause: error }
+          );
+        }
+        throw error;
+      }
+      if (current.activeEpoch !== backend.activeEpoch || current.activeSandboxId !== backend.sandboxId) {
+        this.invalidate(backend);
+        if (mutatesWorkspace) {
+          throw new RoutingMutationOutcomeUnknownError(
+            op,
+            `Mutating sandbox operation "${op}" completed on a superseded route; its output was rejected and it was not replayed`
+          );
+        }
+        lastError = new Error(`sandbox route changed while "${op}" was in flight`);
+        attempt += 1;
+        continue;
       }
+      return result;
     }
     throw lastError ?? new Error(`routing op "${op}" exhausted fence retries`);
   }
@@ -21275,7 +22804,7 @@ var RoutingSandboxSession = class {
   // dispatches to the active backend at call-time. A missing backend method
   // degrades via the natural fallback or RoutingUnsupportedError.
   async exec(args) {
-    return this.dispatch("exec", async (s) => {
+    return this.dispatch("exec", true, async (s) => {
       if (s.exec) {
         return s.exec(args);
       }
@@ -21287,7 +22816,7 @@ var RoutingSandboxSession = class {
   }
   async execCommand(args) {
     try {
-      return await this.dispatch("execCommand", async (s) => {
+      return await this.dispatch("execCommand", true, async (s) => {
         if (s.execCommand) {
           return s.execCommand(args);
         }
@@ -21302,21 +22831,72 @@ var RoutingSandboxSession = class {
     }
   }
   async writeStdin(args) {
-    return this.dispatch("writeStdin", async (s) => {
+    const providerSessionId = providerSessionIdFromArgs(args);
+    if (providerSessionId !== null && this.retainedProcesses.has(providerSessionId)) {
+      return await this.dispatchProcessMutation(args);
+    }
+    return this.dispatch("writeStdin", true, async (s) => {
       if (!s.writeStdin) {
         throw new RoutingUnsupportedError("writeStdin", this.cached?.kind ?? "unknown");
       }
       return s.writeStdin(args);
     });
   }
+  /** Whether a positive provider session locator is still pinned to the exact
+   * backend that yielded it. This synchronous probe is used only to select the
+   * process-aware routing surface; it is not itself durable authority. */
+  hasRetainedProcess(providerSessionId) {
+    return positiveProviderSessionId(providerSessionId) !== null && this.retainedProcesses.has(providerSessionId);
+  }
+  /** Return only OpenGeni's durable UUID + provider locator. Backend/session
+   * objects remain private so a caller cannot forge route authority from this
+   * diagnostic handoff. */
+  retainedProcessIdentity(providerSessionId) {
+    const record = this.retainedProcesses.get(providerSessionId);
+    return record ? { ...record.process } : null;
+  }
+  /** Model/user-visible stdin is a distinct workspace mutation admission under
+   * the durable retained-process holder. It never re-reads the active pointer. */
+  async writeStdinForProcessMutation(args) {
+    return await this.dispatchProcessMutation(args);
+  }
+  /** Cancellation and drain polling are control operations. They stay pinned to
+   * the process backend and may prove terminal state, but never advance the
+   * workspace generation. */
+  async writeStdinForProcessControl(args) {
+    return await this.dispatchProcessControl(args);
+  }
+  /** Run a PID/PGID marker or signal helper on the retained process's exact
+   * backend. The helper is control-plane work and therefore has no workspace
+   * mutation admission of its own. */
+  async execCommandForProcessControl(providerSessionId, args) {
+    const exactProviderSessionId = positiveProviderSessionId(providerSessionId);
+    if (exactProviderSessionId === null) throw new RoutingRetainedProcessNotFoundError(-1);
+    const record = this.retainedProcess(exactProviderSessionId);
+    const priorTerminal = await this.flushPendingProcessMutation(record);
+    if (priorTerminal !== null) return priorTerminal;
+    if (record.pendingTerminal) {
+      const terminal = record.pendingTerminal;
+      await this.settleRetainedProcess(record, terminal.proof, terminal.result);
+      return terminal.result;
+    }
+    await this.ensureParentPromotion(record);
+    if (record.backend.session.execCommand) {
+      return await record.backend.session.execCommand(args);
+    }
+    if (record.backend.session.exec) {
+      return formatExecResult(await record.backend.session.exec(args));
+    }
+    throw new RoutingUnsupportedError("execCommand", record.backend.kind);
+  }
   async cancelExecCommand(opId) {
-    return await this.dispatch("cancelExecCommand", async (session) => {
+    return await this.dispatch("cancelExecCommand", false, async (session) => {
       if (!session.cancelExecCommand) return false;
       return await session.cancelExecCommand(opId);
     });
   }
   async readFile(args) {
-    return this.dispatch("readFile", async (s) => {
+    return this.dispatch("readFile", false, async (s) => {
       if (!s.readFile) {
         throw new RoutingUnsupportedError("readFile", this.cached?.kind ?? "unknown");
       }
@@ -21324,7 +22904,7 @@ var RoutingSandboxSession = class {
     });
   }
   async writeFile(args) {
-    return this.dispatch("writeFile", async (s) => {
+    return this.dispatch("writeFile", true, async (s) => {
       if (!s.writeFile) {
         throw new RoutingUnsupportedError("writeFile", this.cached?.kind ?? "unknown");
       }
@@ -21332,7 +22912,7 @@ var RoutingSandboxSession = class {
     });
   }
   async listDir(args) {
-    return this.dispatch("listDir", async (s) => {
+    return this.dispatch("listDir", false, async (s) => {
       if (!s.listDir) {
         throw new RoutingUnsupportedError("listDir", this.cached?.kind ?? "unknown");
       }
@@ -21340,7 +22920,7 @@ var RoutingSandboxSession = class {
     });
   }
   async pathExists(path, runAs) {
-    return this.dispatch("pathExists", async (s) => {
+    return this.dispatch("pathExists", false, async (s) => {
       if (!s.pathExists) {
         throw new RoutingUnsupportedError("pathExists", this.cached?.kind ?? "unknown");
       }
@@ -21348,7 +22928,7 @@ var RoutingSandboxSession = class {
     });
   }
   async viewImage(args) {
-    return this.dispatch("viewImage", async (s) => {
+    return this.dispatch("viewImage", false, async (s) => {
       if (!s.viewImage) {
         throw new RoutingUnsupportedError("viewImage", this.cached?.kind ?? "unknown");
       }
@@ -21356,7 +22936,7 @@ var RoutingSandboxSession = class {
     });
   }
   async materializeEntry(args) {
-    return this.dispatch("materializeEntry", async (s) => {
+    return this.dispatch("materializeEntry", true, async (s) => {
       if (!s.materializeEntry) {
         throw new RoutingUnsupportedError("materializeEntry", this.cached?.kind ?? "unknown");
       }
@@ -21382,13 +22962,12 @@ var RoutingSandboxSession = class {
    *  direct delegate returns undefined and every lazy turn would die at bind. Return a
    *  LAZY EDITOR PROXY instead: a non-null editor whose async ops resolve the active
    *  backend (establishing the box on first use, via `dispatch`) and delegate to its
-   *  real editor — mirroring how this proxy defers exec/readFile. */
+   *  real editor — mirroring how this proxy defers exec/readFile. Even when an
+   *  eager editor already exists, returning it directly would bypass per-edit
+   *  route resolution and mutation-generation admission, so every editor is
+   *  represented by this dispatching proxy. */
   createEditor(runAs) {
-    const eager = (this.lastResolved ?? this.deps.defaultResolved)?.session.createEditor?.(runAs);
-    if (eager) {
-      return eager;
-    }
-    const op = (name) => (operation, context) => this.dispatch(`editor.${name}`, async (s) => {
+    const op = (name) => (operation, context) => this.dispatch(`editor.${name}`, true, async (s) => {
       const editor = s.createEditor?.(runAs);
       if (!editor?.[name]) {
         throw new RoutingUnsupportedError(`editor.${name}`, this.cached?.kind ?? "unknown");
@@ -21402,7 +22981,7 @@ var RoutingSandboxSession = class {
     };
   }
   async resolveExposedPort(port) {
-    return this.dispatch("resolveExposedPort", async (s) => {
+    return this.dispatch("resolveExposedPort", false, async (s) => {
       if (!s.resolveExposedPort) {
         throw new RoutingUnsupportedError("resolveExposedPort", this.cached?.kind ?? "unknown");
       }
@@ -21412,7 +22991,7 @@ var RoutingSandboxSession = class {
   /** Serialize the active backend's session state. Used by the resume-by-id seam
    *  to fold the live box onto the lease. Dispatches to the active backend. */
   async serializeSessionState() {
-    return this.dispatch("serializeSessionState", async (s) => {
+    return this.dispatch("serializeSessionState", false, async (s) => {
       if (!s.serializeSessionState) {
         return void 0;
       }
@@ -21464,6 +23043,9 @@ function makeActiveBackendResolver(deps) {
           "the active sandbox was detached to the session default (home), but this turn started pinned to a machine and established no home box; the detach is accepted and takes effect on the next turn \u2014 this turn has no active home box"
         );
       }
+      if (deps.resolveDefaultBackend) {
+        return await deps.resolveDefaultBackend(pointer);
+      }
       return { session: deps.defaultBackend, sandboxId: null, kind: deps.defaultKind };
     }
     if (deps.pinnedSelfhosted && pointer.activeSandboxId === deps.pinnedSelfhosted.sandboxId && pointer.activeEpoch === deps.pinnedSelfhosted.epoch) {
@@ -21646,20 +23228,6 @@ function readWorkspaceArchiveFromEnvelopeSessionState(sessionState) {
     return void 0;
   }
 }
-function readWorkspaceArchivePairFromEnvelopeSessionState(sessionState) {
-  if (!sessionState || typeof sessionState !== "object") {
-    return {};
-  }
-  const state = sessionState;
-  const current = readWorkspaceArchiveFromEnvelopeSessionState(sessionState);
-  const previous = readWorkspaceArchiveFromEnvelopeSessionState({
-    workspaceArchive: state.workspaceArchivePrev
-  });
-  return {
-    ...current ? { current } : {},
-    ...previous ? { previous } : {}
-  };
-}
 var MODAL_SNAPSHOT_REF_PREFIXES = [
   "MODAL_SANDBOX_FS_SNAPSHOT_V1\n",
   "MODAL_SANDBOX_DIR_SNAPSHOT_V1\n"
@@ -21730,39 +23298,73 @@ async function deserializeSandboxSessionStateEnvelope(client, envelope) {
     ...state.exposedPorts ? { exposedPorts: structuredClone(state.exposedPorts) } : {}
   });
 }
-function isProviderSandboxNotFoundError2(backendId, error) {
-  if (backendId === "selfhosted") {
-    return isSelfhostedProviderNotFoundError(error);
+var SandboxExecReadinessError = class extends Error {
+  constructor(backend, code, timeoutMs, exitCode = null) {
+    super(
+      code === "exec_probe_timeout" ? `sandbox creation timed out waiting for ${backend} command readiness after ${timeoutMs}ms` : code === "exec_probe_unavailable" ? `${backend} sandbox session does not expose an exec readiness probe` : exitCode === null ? `${backend} sandbox exec readiness probe did not return a command exit code` : `${backend} sandbox exec readiness probe failed with exit code ${exitCode}`
+    );
+    this.backend = backend;
+    this.code = code;
+    this.timeoutMs = timeoutMs;
+    this.exitCode = exitCode;
   }
-  if (!error) {
-    return false;
+  name = "SandboxExecReadinessError";
+};
+function sandboxExecProbeExitCode(result) {
+  if (typeof result === "string") {
+    const match = result.match(/Process exited with code (-?\d+)/);
+    return match ? Number(match[1]) : null;
   }
-  const status = error.status ?? error.statusCode;
-  if (status === 404) {
-    return true;
+  if (!result || typeof result !== "object") return null;
+  const candidate = result;
+  for (const value of [candidate.exitCode, candidate.exit_code, candidate.code, candidate.status]) {
+    if (typeof value === "number") return value;
   }
-  const name = typeof error.name === "string" ? error.name : "";
-  const code = typeof error.code === "string" ? error.code : "";
-  const message = error instanceof Error ? error.message : typeof error === "string" ? error : String(error?.message ?? "");
-  const haystack = `${name} ${code} ${message}`.toLowerCase();
-  const goneMarkers = [
-    "not found",
-    "no longer running",
-    "no longer exists",
-    "does not exist",
-    "doesn't exist",
-    "has been terminated",
-    "was terminated",
-    "is terminated",
-    "sandbox terminated",
-    "notfound",
-    "sandbox_not_found",
-    "box no longer running"
-  ];
-  if (haystack.includes("already running") || haystack.includes("still running") || haystack.includes("already exists")) {
-    return false;
+  return null;
+}
+function sandboxExecProbeStillRunning(result) {
+  if (typeof result === "string") return /Process running with session ID \d+/u.test(result);
+  if (!result || typeof result !== "object") return false;
+  const candidate = result;
+  return typeof candidate.sessionId === "number" || typeof candidate.session_id === "number";
+}
+async function verifySandboxExecReadiness(established, timeoutMs = 15e3) {
+  if (established.backendId !== "modal") return;
+  const session = established.session;
+  const run2 = session.exec ?? session.execCommand;
+  if (!run2) {
+    throw new SandboxExecReadinessError(established.backendId, "exec_probe_unavailable", timeoutMs);
+  }
+  let timer;
+  try {
+    const result = await Promise.race([
+      run2.call(session, {
+        cmd: "true",
+        yieldTimeMs: 1e3,
+        maxOutputTokens: 1e3
+      }),
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(
+            new SandboxExecReadinessError(established.backendId, "exec_probe_timeout", timeoutMs)
+          ),
+          timeoutMs
+        );
+        if (timer && "unref" in timer && typeof timer.unref === "function") timer.unref();
+      })
+    ]);
+    const exitCode = sandboxExecProbeExitCode(result);
+    if (sandboxExecProbeStillRunning(result) || exitCode !== 0) {
+      throw new SandboxExecReadinessError(
+        established.backendId,
+        "exec_probe_failed",
+        timeoutMs,
+        exitCode
+      );
+    }
+  } finally {
+    if (timer) clearTimeout(timer);
   }
-  return goneMarkers.some((marker) => haystack.includes(marker));
 }
 function readInstanceId(session) {
   const state = session.state ?? {};
@@ -21800,9 +23402,14 @@ async function establishSandboxSessionFromEnvelope(settings, envelope, opts) {
   }
   const createManifest = { environment };
   const envelopeSessionState = envelope && typeof envelope === "object" ? envelope.sessionState : void 0;
-  const workspaceArchives = readWorkspaceArchivePairFromEnvelopeSessionState(envelopeSessionState);
-  const workspaceArchive = workspaceArchives.current;
-  const coldRestore = async (resumeFallbackState, skipWorkspaceHydrate = false) => {
+  const archiveState = envelopeSessionState && typeof envelopeSessionState === "object" ? envelopeSessionState : void 0;
+  const workspaceArchiveBase64 = archiveState?.workspaceArchive;
+  const workspaceArchiveMetadata = archiveState?.workspaceArchiveMeta;
+  const coldRestore = async (resumeFallbackState) => {
+    const workspaceArchive = readVerifiedWorkspaceArchive(
+      workspaceArchiveBase64,
+      workspaceArchiveMetadata
+    );
     const createStarted = Date.now();
     let restored;
     try {
@@ -21829,56 +23436,68 @@ async function establishSandboxSessionFromEnvelope(settings, envelope, opts) {
       }
     }
     let hydrationApplied = false;
-    if (!skipWorkspaceHydrate && (workspaceArchive || workspaceArchives.previous)) {
+    if (workspaceArchive) {
       const hydrate = restored.hydrateWorkspace;
-      if (typeof hydrate === "function") {
-        let hydrated = false;
-        for (const candidate of [
-          { archive: workspaceArchive, label: "current" },
-          { archive: workspaceArchives.previous, label: "previous" }
-        ]) {
-          if (!candidate.archive) {
-            continue;
-          }
+      if (typeof hydrate !== "function") {
+        await terminateCreatedSandbox(client, restored, restoredState);
+        throw new WorkspaceArchiveIntegrityError(
+          "archive_hydration_failed",
+          `sandbox backend ${client.backendId} cannot hydrate selected archive revision ${workspaceArchive.descriptor.revision}`
+        );
+      }
+      try {
+        await hydrate.call(restored, workspaceArchive.bytes);
+      } catch (error) {
+        await terminateCreatedSandbox(client, restored, restored.state);
+        if (error instanceof WorkspaceArchiveIntegrityError) throw error;
+        throw new WorkspaceArchiveIntegrityError(
+          "archive_hydration_failed",
+          `failed to hydrate selected workspace archive revision ${workspaceArchive.descriptor.revision}`,
+          { retryable: true }
+        );
+      }
+      const hydratedState = restored.state;
+      const hydratedInstanceId = readInstanceId(restored);
+      if (hydratedInstanceId && hydratedInstanceId !== established.instanceId) {
+        established = {
+          client,
+          session: restored,
+          sessionState: hydratedState ?? resumeFallbackState,
+          instanceId: hydratedInstanceId,
+          backendId: client.backendId
+        };
+        if (opts.onSandboxCreated) {
           try {
-            await hydrate.call(restored, candidate.archive);
-            console.info(
-              `[sandbox] cold-restore hydrated workspace from ${candidate.label} archive`
-            );
-            hydrated = true;
-            break;
-          } catch (hydrateError) {
-            console.warn(
-              `[sandbox] cold-restore failed to hydrate workspace from ${candidate.label} archive${candidate.label === "current" && workspaceArchives.previous ? "; trying previous archive" : ""}`,
-              hydrateError
-            );
+            await opts.onSandboxCreated(established);
+          } catch (createCallbackError) {
+            await terminateCreatedSandbox(client, restored, hydratedState);
+            throw createCallbackError;
           }
         }
-        if (!hydrated) {
-          await terminateCreatedSandbox(client, restored, restoredState);
-          return await coldRestore(resumeFallbackState, true);
-        }
-        hydrationApplied = true;
-        const hydratedState = restored.state;
-        const hydratedInstanceId = readInstanceId(restored);
-        if (hydratedInstanceId && hydratedInstanceId !== established.instanceId) {
-          established = {
-            client,
-            session: restored,
-            sessionState: hydratedState ?? resumeFallbackState,
-            instanceId: hydratedInstanceId,
-            backendId: client.backendId
-          };
-          if (opts.onSandboxCreated) {
-            try {
-              await opts.onSandboxCreated(established);
-            } catch (createCallbackError) {
-              await terminateCreatedSandbox(client, restored, hydratedState);
-              throw createCallbackError;
-            }
-          }
+      }
+      if (opts.onWorkspaceRestoreVerifying) {
+        try {
+          await opts.onWorkspaceRestoreVerifying(workspaceArchive.descriptor);
+        } catch (error) {
+          await terminateCreatedSandbox(client, restored, restored.state);
+          throw error;
         }
       }
+      try {
+        await verifyRestoredWorkspace(restored, workspaceArchive.descriptor);
+      } catch (error) {
+        await terminateCreatedSandbox(client, restored, restored.state);
+        if (error instanceof WorkspaceArchiveIntegrityError) throw error;
+        throw new WorkspaceArchiveIntegrityError(
+          "workspace_fingerprint_unavailable",
+          `failed to verify selected workspace archive revision ${workspaceArchive.descriptor.revision}`,
+          { retryable: true }
+        );
+      }
+      hydrationApplied = true;
+      console.info(
+        `[sandbox] cold-restore verified workspace archive revision ${workspaceArchive.descriptor.revision}`
+      );
     }
     restoredState = restored.state;
     return {
@@ -21887,7 +23506,8 @@ async function establishSandboxSessionFromEnvelope(settings, envelope, opts) {
       sessionState: restoredState ?? resumeFallbackState,
       instanceId: readInstanceId(restored),
       backendId: client.backendId,
-      origin: hydrationApplied ? "restored" : "created"
+      origin: hydrationApplied ? "restored" : "created",
+      ...workspaceArchive ? { restoredArchive: workspaceArchive.descriptor } : {}
     };
   };
   const envelopeProviderState = envelopeSessionState && typeof envelopeSessionState === "object" ? envelopeSessionState.providerState : void 0;
@@ -21973,6 +23593,79 @@ async function serializeEstablishedSandboxEnvelope(established) {
     return null;
   }
 }
+var PROVIDER_IDENTITY_FIELDS = [
+  "sandboxId",
+  "instanceId",
+  "id",
+  "hostId",
+  "containerId",
+  "workspaceRootPath",
+  "agentId"
+];
+function hasPersistableSandboxProviderIdentity(envelope) {
+  const sessionState = envelope?.sessionState && typeof envelope.sessionState === "object" ? envelope.sessionState : null;
+  const providerState = sessionState?.providerState && typeof sessionState.providerState === "object" ? sessionState.providerState : null;
+  return Boolean(
+    providerState && PROVIDER_IDENTITY_FIELDS.some(
+      (field) => typeof providerState[field] === "string" && providerState[field].length > 0
+    )
+  );
+}
+var SandboxReplacementProviderStateError = class extends Error {
+  constructor(backend) {
+    super(
+      `sandbox backend "${backend}" replacement provider state could not be serialized; refusing to publish an attachable lease`
+    );
+    this.backend = backend;
+    this.name = "SandboxReplacementProviderStateError";
+  }
+  code = "replacement_provider_state_unpersistable";
+};
+function requirePersistableReplacementSandboxEnvelope(envelope, backend) {
+  if (!hasPersistableSandboxProviderIdentity(envelope)) {
+    throw new SandboxReplacementProviderStateError(backend);
+  }
+  return envelope;
+}
+var DURABLE_WORKSPACE_ARCHIVE_FIELDS = [
+  "workspaceArchive",
+  "workspaceArchiveMeta",
+  "workspaceArchivePrev",
+  "workspaceArchivePrevMeta",
+  "workspaceArchiveAt"
+];
+function durableWorkspaceArchiveFields(envelope) {
+  const sessionState = envelope?.sessionState && typeof envelope.sessionState === "object" ? envelope.sessionState : null;
+  if (!sessionState || typeof sessionState.workspaceArchive !== "string" || sessionState.workspaceArchive.length === 0) {
+    return null;
+  }
+  const fields = {};
+  for (const key of DURABLE_WORKSPACE_ARCHIVE_FIELDS) {
+    if (sessionState[key] !== void 0 && sessionState[key] !== null) {
+      fields[key] = sessionState[key];
+    }
+  }
+  return fields;
+}
+async function serializeReplacementSandboxEnvelope(established, archiveSource) {
+  const serialized = await serializeEstablishedSandboxEnvelope(established);
+  const archiveFields = durableWorkspaceArchiveFields(archiveSource);
+  if (!serialized && !archiveFields) {
+    return null;
+  }
+  const serializedSessionState = serialized?.sessionState && typeof serialized.sessionState === "object" ? serialized.sessionState : {};
+  return {
+    ...serialized ?? {},
+    // Never inherit a historical backend marker when the replacement could not
+    // serialize. The separately-persisted resume_backend_id and this envelope
+    // must both describe the replacement.
+    backendId: established.backendId,
+    sessionState: {
+      ...serializedSessionState,
+      ...archiveFields ?? {}
+    }
+  };
+}
 
 export {
   localDirLazySkillSource,
@@ -22040,6 +23733,17 @@ export {
   isSelfhostedProviderNotFoundError,
   PROVIDER_REGISTRY,
   assertProviderRegistryInvariants,
+  classifyProviderSandboxFailure,
+  isProviderSandboxNotFoundError2 as isProviderSandboxNotFoundError,
+  isProviderSandboxGoneDuringRoutedOperation,
+  isProviderSandboxTransientError,
+  WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION,
+  WorkspaceArchiveIntegrityError,
+  parseWorkspaceArchiveDescriptor,
+  readVerifiedWorkspaceArchive,
+  fingerprintSandboxWorkspace,
+  captureVerifiedWorkspaceArchive,
+  verifyRestoredWorkspace,
   selectBackend,
   backendSupportsOs,
   desktopCapableBackend,
@@ -22050,6 +23754,7 @@ export {
   StreamTokenPayload2 as StreamTokenPayload,
   parseExecBannerSessionId,
   parseExecBannerExitCode,
+  isExecSessionLostBanner,
   STREAM_PORT,
   DISPLAY_STACK_TIMEOUT_MS,
   DEFAULT_DESKTOP_GEOMETRY,
@@ -22094,6 +23799,9 @@ export {
   uploadRecordingArtifact,
   deleteRecordingArtifacts,
   recordingStorageKey,
+  TurnSandboxCommandCancelledError,
+  createTurnToolCancellationController,
+  wrapCapabilityToolsForTurnCancellation,
   ChannelAValidationError,
   ChannelAUnavailableError,
   ChannelAConflictError,
@@ -22102,7 +23810,6 @@ export {
   REPOSITORY_DISCOVERY_LIMIT,
   SandboxChannelAService,
   stripExecBanner2 as stripExecBanner,
-  isExecSessionLostBanner,
   assertSafeRelPath,
   parsePorcelainV2,
   parseNumstatZ,
@@ -22112,6 +23819,9 @@ export {
   negotiateSelfhostedCapabilities,
   MockAgentResponder,
   RoutingUnsupportedError,
+  RoutingBackendRecoveryRequiredError,
+  RoutingMutationOutcomeUnknownError,
+  RoutingRetainedProcessNotFoundError,
   RoutingSandboxSession,
   ActiveBackendUnresolvableError,
   swapTargetEstablishability,
@@ -22124,10 +23834,15 @@ export {
   decodeModalSnapshotId,
   deletePriorPersistedSnapshot,
   deserializeSandboxSessionStateEnvelope,
-  isProviderSandboxNotFoundError2 as isProviderSandboxNotFoundError,
+  SandboxExecReadinessError,
+  verifySandboxExecReadiness,
   establishSandboxSessionFromEnvelope,
   serializeEstablishedSandboxEnvelope,
+  hasPersistableSandboxProviderIdentity,
+  SandboxReplacementProviderStateError,
+  requirePersistableReplacementSandboxEnvelope,
+  serializeReplacementSandboxEnvelope,
   collectSandboxEnvironment2 as collectSandboxEnvironment,
   parseExposedPorts2 as parseExposedPorts
 };
-//# sourceMappingURL=chunk-65UDUFUO.js.map
+//# sourceMappingURL=chunk-JGUQSAG5.js.map