@opengeni/runtime 0.11.0 → 0.13.3

package/dist/{chunk-YUAFQEFY.js → chunk-JGUQSAG5.js}

@@ -13274,8 +13274,8 @@ async function sweepModalOrphanSandboxes(settings, liveLeases, options = {}) {
         if (liveByInstance) {
           if (leaseId !== liveByInstance.leaseId || workspaceId !== liveByInstance.workspaceId || sandboxGroupId !== liveByInstance.sandboxGroupId) {
             try {
-              const sandbox = await modal.sandboxes.fromId(info.id);
-              await sandbox.setTags(
+              const sandbox2 = await modal.sandboxes.fromId(info.id);
+              await sandbox2.setTags(
                 modalSandboxAttributionTags({
                   leaseId: liveByInstance.leaseId,
                   workspaceId: liveByInstance.workspaceId,
@@ -13306,10 +13306,28 @@ async function sweepModalOrphanSandboxes(settings, liveLeases, options = {}) {
           skipped += 1;
           continue;
         }
+        const candidate = { sandboxId: info.id, reason, tags };
+        let sandbox;
+        try {
+          sandbox = await modal.sandboxes.fromId(info.id);
+        } catch {
+          skipped += 1;
+          continue;
+        }
+        if (options.revalidateTermination) {
+          try {
+            if (!await options.revalidateTermination(candidate)) {
+              skipped += 1;
+              continue;
+            }
+          } catch {
+            skipped += 1;
+            continue;
+          }
+        }
         try {
-          const sandbox = await modal.sandboxes.fromId(info.id);
           await sandbox.terminate();
-          terminated.push({ sandboxId: info.id, reason, tags });
+          terminated.push(candidate);
         } catch {
           skipped += 1;
         }
@@ -14823,11 +14841,11 @@ var NatsControlRpc = class {
     }
   }
 };
-function offlineControlResponse(requestId, neverSent = false) {
-  return { requestId, error: offlineAgentError(void 0, neverSent), result: void 0 };
+function offlineControlResponse(requestId2, neverSent = false) {
+  return { requestId: requestId2, error: offlineAgentError(void 0, neverSent), result: void 0 };
 }
-function timeoutControlResponse(requestId) {
-  return { requestId, error: timeoutAgentError(), result: void 0 };
+function timeoutControlResponse(requestId2) {
+  return { requestId: requestId2, error: timeoutAgentError(), result: void 0 };
 }
 
 // src/sandbox/selfhosted/session.ts
@@ -15407,10 +15425,10 @@ var OpConsumer = class {
    *  `SelfhostedControlError` on any AgentError. `requestId` is overridable
    *  because OpStart's REQUEST ID IS THE OP ID (its idempotency key) and must
    *  be STABLE across retries — every other op uses a fresh UUID per attempt. */
-  async controlOp(op, requestId = crypto.randomUUID()) {
+  async controlOp(op, requestId2 = crypto.randomUUID()) {
     const res = await this.deps.controlRpc.request(
       this.deps.rpcSubject,
-      { requestId, epoch: this.deps.epoch, op },
+      { requestId: requestId2, epoch: this.deps.epoch, op },
       { timeoutMs: this.deps.controlTimeoutMs }
     );
     if (res.error || !res.result) {
@@ -17474,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";
 
@@ -17690,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,
@@ -17732,8 +18042,67 @@ async function verifyStreamToken(secret, token, nowSeconds = Math.floor(Date.now
 
 // src/sandbox/display-stack.ts
 import { DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT4 } from "@opengeni/contracts";
+
+// src/sandbox/exec-banner.ts
+var EXEC_BANNER_HEADER_MAX_CHARS = 16 * 1024;
+var OUTPUT_DELIMITER = /\r?\nOutput:\r?\n/u;
+var SDK_METADATA_LINE = /^(?:Chunk ID:|Wall time:|Original token count:|Output:|Process (?:running with session ID|exited with code))/mu;
+var RUNNING_LINE = /^Process running with session ID (\d+)$/u;
+var EXITED_LINE = /^Process exited with code (-?\d+)$/u;
+var PROCESS_STATUS_PREFIX = /^Process (?:running with session ID|exited with code)/u;
+function parseExecResponseBanner(raw) {
+  const delimiter = OUTPUT_DELIMITER.exec(raw);
+  if (!delimiter) {
+    return SDK_METADATA_LINE.test(raw) ? { kind: "invalid" } : { kind: "absent" };
+  }
+  if (delimiter.index > EXEC_BANNER_HEADER_MAX_CHARS) return { kind: "invalid" };
+  const header = raw.slice(0, delimiter.index);
+  const status = [];
+  for (const line of header.split(/\r?\n/u)) {
+    const running = RUNNING_LINE.exec(line);
+    if (running) {
+      status.push({ kind: "running", value: running[1] });
+      continue;
+    }
+    const exited = EXITED_LINE.exec(line);
+    if (exited) {
+      status.push({ kind: "exited", value: exited[1] });
+      continue;
+    }
+    if (PROCESS_STATUS_PREFIX.test(line)) return { kind: "invalid" };
+  }
+  if (status.length !== 1) return { kind: "invalid" };
+  const terminal = status[0];
+  const value = Number(terminal.value);
+  if (!Number.isSafeInteger(value)) return { kind: "invalid" };
+  if (terminal.kind === "running") {
+    return value >= 0 ? { kind: "running", sessionId: value } : { kind: "invalid" };
+  }
+  return { kind: "exited", exitCode: value };
+}
+function parseExecBannerSessionId(raw) {
+  const banner = parseExecResponseBanner(raw);
+  return banner.kind === "running" ? banner.sessionId : null;
+}
+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;
 var DISPLAY_STACK_TIMEOUT_MS = 9e4;
+var DISPLAY_STACK_PROVIDER_YIELD_MS = 15e3;
+var DISPLAY_STACK_PROVIDER_POLL_MS = 5e3;
+var DISPLAY_STACK_TERMINATION_GRACE_MS = 5e3;
+var DISPLAY_STACK_CLEANUP_CALL_MS = 250;
+var DISPLAY_STACK_DRAIN_GRACE_MS = 100;
 var PAINT_PROBE_ATTEMPTS = 150;
 var PAINT_PROBE_INTERVAL_S = 0.2;
 var PAINT_MIN_BYTES = 6e4;
@@ -17743,7 +18112,7 @@ var DisplayStackError = class extends Error {
   exitCode;
   stage;
   constructor(exitCode, output) {
-    const stage = exitCode === 11 ? "xvfb" : exitCode === 12 ? "x11vnc" : exitCode === 13 ? "websockify" : exitCode === 14 ? "paint" : "unknown";
+    const stage = exitCode === 11 ? "xvfb" : exitCode === 12 ? "x11vnc" : exitCode === 13 ? "websockify" : exitCode === 14 ? "paint" : exitCode === 15 ? "lock" : exitCode === 124 || /OPENGENI_DISPLAY_TIMEOUT/u.test(output) ? "timeout" : "unknown";
     super(
       `desktop display stack failed at stage "${stage}" (exit ${exitCode})${output ? `:
 ${output}` : ""}`
@@ -17763,9 +18132,11 @@ function buildDisplayStackScript(options = {}) {
   const geometry = options.geometry ?? DEFAULT_DESKTOP_GEOMETRY;
   const port = options.port ?? DESKTOP_STREAM_PORT4;
   const env = `DESKTOP_W=${geometry.width} DESKTOP_H=${geometry.height} DESKTOP_DPI=${geometry.dpi} STREAM_PORT=${port}`;
-  const bringUp = `if nc -z 127.0.0.1 ${port} >/dev/null 2>&1 && nc -z 127.0.0.1 5900 >/dev/null 2>&1; then echo "OPENGENI_DESKTOP_UP port=${port} geometry=${geometry.width}x${geometry.height} dpi=${geometry.dpi} (precheck)"; else mkdir -p /tmp/opengeni-desktop && flock -w 45 /tmp/opengeni-desktop/up.outer.lock env ${env} opengeni-desktop-up; fi`;
-  const paintProbe = `p=/tmp/opengeni-desktop/paint-probe.png; prev=0; for i in $(seq 1 ${PAINT_PROBE_ATTEMPTS}); do if DISPLAY=:0 scrot -o "$p" >/dev/null 2>&1; then sz=$(wc -c < "$p" 2>/dev/null || echo 0); else sz=0; fi; rm -f "$p"; if [ "$sz" -ge ${PAINT_MIN_BYTES} ] && [ "$prev" -ge ${PAINT_MIN_BYTES} ]; then d=$((sz-prev)); [ "$d" -lt 0 ] && d=$((0-d)); [ "$d" -le ${PAINT_SETTLE_DELTA_BYTES} ] && break; fi; prev=$sz; if [ "$i" = "${PAINT_PROBE_ATTEMPTS}" ]; then echo "OPENGENI_DESKTOP_NOT_PAINTING scrot below ${PAINT_MIN_BYTES}B or unsettled after warmup (last=$sz)"; exit 14; fi; sleep ${PAINT_PROBE_INTERVAL_S}; done`;
-  return `mkdir -p /tmp/opengeni-desktop; { ${bringUp} ; } && { ${paintProbe} ; }`;
+  const lockedLauncher = `ds_started=$1; fw=$2; ds_class=cold; ds_stage() { ds_now=$(date +%s%3N); echo "OPENGENI_DISPLAY_STAGE stage=$1 elapsed_ms=$((ds_now-ds_started)) classification=$ds_class"; }; fa=$(date +%s%3N); fd=$((fa-fw)); [ "$fd" -ge 50 ] && ds_class=contention; ds_stage outer_flock_acquired; ds_stage launcher_issued; env ${env} opengeni-desktop-up; urc=$?; ds_stage launcher_complete; exit "$urc"`;
+  const bringUp = `if nc -z 127.0.0.1 ${port} >/dev/null 2>&1 && nc -z 127.0.0.1 5900 >/dev/null 2>&1; then ds_class=already_ready; ds_stage precheck_ready; echo "OPENGENI_DESKTOP_UP port=${port} geometry=${geometry.width}x${geometry.height} dpi=${geometry.dpi} (precheck)"; else ds_class=cold; ds_stage precheck_miss; mkdir -p /tmp/opengeni-desktop; ds_stage outer_flock_wait; fw=$(date +%s%3N); flock --close --conflict-exit-code 75 --wait 45 /tmp/opengeni-desktop/up.outer.lock bash -c ${shellQuote3(lockedLauncher)} _ "$ds_started" "$fw"; frc=$?; if [ "$frc" -eq 75 ]; then ds_stage outer_flock_timeout; echo "OPENGENI_DESKTOP_LOCK_TIMEOUT"; exit 15; fi; if [ "$frc" -ne 0 ]; then exit "$frc"; fi; fi`;
+  const paintProbe = `ds_stage paint_probe_started; p=/tmp/opengeni-desktop/paint-probe.png; prev=0; for i in $(seq 1 ${PAINT_PROBE_ATTEMPTS}); do if DISPLAY=:0 scrot -o "$p" >/dev/null 2>&1; then sz=$(wc -c < "$p" 2>/dev/null || echo 0); else sz=0; fi; rm -f "$p"; if [ "$sz" -ge ${PAINT_MIN_BYTES} ] && [ "$prev" -ge ${PAINT_MIN_BYTES} ]; then d=$((sz-prev)); [ "$d" -lt 0 ] && d=$((0-d)); if [ "$d" -le ${PAINT_SETTLE_DELTA_BYTES} ]; then ds_stage paint_ready; break; fi; fi; prev=$sz; if [ "$i" = "${PAINT_PROBE_ATTEMPTS}" ]; then ds_stage paint_failed; echo "OPENGENI_DESKTOP_NOT_PAINTING scrot below ${PAINT_MIN_BYTES}B or unsettled after warmup (last=$sz)"; exit 14; fi; sleep ${PAINT_PROBE_INTERVAL_S}; done`;
+  const trace = `ds_started=$(date +%s%3N); ds_class=unknown; ds_stage() { ds_now=$(date +%s%3N); echo "OPENGENI_DISPLAY_STAGE stage=$1 elapsed_ms=$((ds_now-ds_started)) classification=$ds_class"; }; ds_stage script_entry`;
+  return `${trace}; mkdir -p /tmp/opengeni-desktop; { ${bringUp} ; } && { ${paintProbe} ; }`;
 }
 function execResultOutput(result) {
   if (typeof result === "string") {
@@ -17775,11 +18146,417 @@ function execResultOutput(result) {
 }
 function execResultExitCode(result) {
   if (typeof result === "string") {
-    return null;
+    const banner = parseExecResponseBanner(result);
+    if (banner.kind === "exited") return banner.exitCode;
+    return banner.kind === "invalid" ? -1 : null;
   }
   return typeof result.exitCode === "number" ? result.exitCode : null;
 }
+function execResultSessionId(result) {
+  if (typeof result === "string") {
+    const banner = parseExecResponseBanner(result);
+    return banner.kind === "running" ? banner.sessionId : null;
+  }
+  const value = result.sessionId ?? result.session_id;
+  return typeof value === "number" ? value : null;
+}
+function shellQuote3(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function boundedDisplayStackCommand(command, timeoutMs, markerPath, markerToken) {
+  const graceMs = Math.min(
+    DISPLAY_STACK_TERMINATION_GRACE_MS,
+    Math.max(20, Math.floor(timeoutMs / 4))
+  );
+  const commandTimeoutMs = Math.max(1, timeoutMs - graceMs);
+  const killAfterMs = Math.max(1, Math.floor(graceMs / 2));
+  const commandTimeoutSeconds = (commandTimeoutMs / 1e3).toFixed(3);
+  const killAfterSeconds = (killAfterMs / 1e3).toFixed(3);
+  const managedCommand = `marker=${shellQuote3(markerPath)}; token=${shellQuote3(markerToken)}; cancel="$marker.cancelled"; if [ -e "$cancel" ]; then echo "OPENGENI_DISPLAY_CANCELLED"; exit 124; fi; pid=$$; pgid=$(ps -o pgid= -p "$pid" 2>/dev/null | tr -d ' '); start=$(awk '{print $22}' "/proc/$pid/stat" 2>/dev/null || true); printf '%s %s %s %s\\n' "$pid" "$pgid" "$start" "$token" >"$marker"; if [ -e "$cancel" ]; then rm -f "$marker"; echo "OPENGENI_DISPLAY_CANCELLED"; exit 124; fi; bash -c ${shellQuote3(command)}; rc=$?; rm -f "$marker"; exit "$rc"`;
+  return (
+    // Do not use timeout --foreground here. The display command contains flock
+    // supervisors and launcher children; default process-group mode is required
+    // so a deadline cannot leave a waiter alive to acquire the lock and launch
+    // after the caller has already failed.
+    `timeout --signal=TERM --kill-after=${killAfterSeconds}s ${commandTimeoutSeconds}s bash -c ${shellQuote3(managedCommand)}; rc=$?; if [ "$rc" -eq 124 ]; then echo "OPENGENI_DISPLAY_TIMEOUT elapsed_ms=${commandTimeoutMs}"; fi; exit "$rc"`
+  );
+}
+var DisplayStackWallTimeoutError = class extends Error {
+};
+var DisplayStackOperationFencedError = class extends Error {
+};
+var stableDisplayStackOperationStates = /* @__PURE__ */ new Map();
+var stableSessionStateOperationStates = /* @__PURE__ */ new WeakMap();
+var displayStackOperationStates = /* @__PURE__ */ new WeakMap();
+function asRecord(value) {
+  return value !== null && typeof value === "object" ? value : null;
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function readSessionState(session) {
+  try {
+    return asRecord(session)?.state;
+  } catch {
+    return void 0;
+  }
+}
+function stableSandboxIdentity(session, options) {
+  const explicit = nonEmptyString(options.telemetryContext?.sandboxId);
+  if (explicit) return `sandbox:${explicit}`;
+  const sessionRecord = asRecord(session);
+  const state = asRecord(readSessionState(session));
+  const providerState = state ? asRecord(state.providerState) : null;
+  const candidates = [sessionRecord, state, providerState];
+  const fields = [
+    "sandboxId",
+    "instanceId",
+    "agentId",
+    "hostId",
+    "containerId",
+    "id",
+    "workspaceRootPath"
+  ];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    for (const field of fields) {
+      const value = nonEmptyString(candidate[field]);
+      if (value) return `sandbox:${value}`;
+    }
+  }
+  return null;
+}
+function newOperationState() {
+  return {
+    epoch: 0,
+    owner: null,
+    waiters: [],
+    inFlight: /* @__PURE__ */ new Set(),
+    drain: null,
+    pendingCleanup: /* @__PURE__ */ new Map(),
+    physicallyQuiescent: true
+  };
+}
+function operationState(session, options) {
+  if ((typeof session !== "object" || session === null) && typeof session !== "function") {
+    return null;
+  }
+  const stableKey = stableSandboxIdentity(session, options);
+  if (stableKey) {
+    let state2 = stableDisplayStackOperationStates.get(stableKey);
+    if (!state2) {
+      state2 = newOperationState();
+      stableDisplayStackOperationStates.set(stableKey, state2);
+    }
+    return state2;
+  }
+  const providerState = readSessionState(session);
+  if (providerState && (typeof providerState === "object" || typeof providerState === "function")) {
+    const stateKey = providerState;
+    let state2 = stableSessionStateOperationStates.get(stateKey);
+    if (!state2) {
+      state2 = newOperationState();
+      stableSessionStateOperationStates.set(stateKey, state2);
+    }
+    return state2;
+  }
+  const key = session;
+  let state = displayStackOperationStates.get(key);
+  if (!state) {
+    state = newOperationState();
+    displayStackOperationStates.set(key, state);
+  }
+  return state;
+}
+function settleOperationWaiter(waiter, error) {
+  if (waiter.settled) return;
+  waiter.settled = true;
+  if (waiter.timer) clearTimeout(waiter.timer);
+  if (error === void 0) waiter.resolve();
+  else waiter.reject(error);
+}
+function pumpOperationWaiters(state) {
+  if (state.owner) return;
+  while (state.waiters.length > 0) {
+    const waiter = state.waiters.shift();
+    if (waiter.settled) continue;
+    if (waiter.epoch !== state.epoch) {
+      settleOperationWaiter(waiter, new DisplayStackOperationFencedError());
+      continue;
+    }
+    state.owner = waiter;
+    settleOperationWaiter(waiter);
+    return;
+  }
+}
+function acquireOperation(state, deadline) {
+  return new Promise((resolve5, reject) => {
+    const waiter = {
+      epoch: state.epoch,
+      settled: false,
+      resolve: () => {
+        resolve5(() => {
+          if (state.owner !== waiter) return;
+          state.owner = null;
+          pumpOperationWaiters(state);
+        });
+      },
+      reject
+    };
+    state.waiters.push(waiter);
+    const remainingMs = deadline - monotonicNow();
+    if (remainingMs <= 0) {
+      waiter.settled = true;
+      state.waiters = state.waiters.filter((candidate) => candidate !== waiter);
+      reject(new DisplayStackWallTimeoutError());
+      return;
+    }
+    waiter.timer = setTimeout(() => {
+      if (waiter.settled) return;
+      waiter.settled = true;
+      state.waiters = state.waiters.filter((candidate) => candidate !== waiter);
+      reject(new DisplayStackWallTimeoutError());
+    }, remainingMs);
+    waiter.timer.unref?.();
+    pumpOperationWaiters(state);
+  });
+}
+function invalidateQueuedOperations(state, epoch) {
+  const retained = [];
+  for (const waiter of state.waiters) {
+    if (waiter.epoch === epoch)
+      settleOperationWaiter(waiter, new DisplayStackOperationFencedError());
+    else retained.push(waiter);
+  }
+  state.waiters = retained;
+}
+function monotonicNow() {
+  return performance.now();
+}
+async function waitForFencedOperation(state, deadline) {
+  const drain = state.drain;
+  if (!drain) return true;
+  try {
+    await beforeDeadline(drain, deadline);
+  } catch {
+    return false;
+  }
+  if (state.drain === drain) state.drain = null;
+  return true;
+}
+function trackProviderCall(state, promise) {
+  if (!state) return promise;
+  state.inFlight.add(promise);
+  void promise.then(
+    () => state.inFlight.delete(promise),
+    () => state.inFlight.delete(promise)
+  );
+  return promise;
+}
+function boundedProviderDrain(pending) {
+  if (pending.length === 0) return Promise.resolve();
+  return new Promise((resolve5) => {
+    let remaining = pending.length;
+    let timer;
+    const finish = () => {
+      if (timer) clearTimeout(timer);
+      resolve5();
+    };
+    timer = setTimeout(finish, DISPLAY_STACK_DRAIN_GRACE_MS);
+    timer.unref?.();
+    for (const promise of pending) {
+      void promise.then(
+        () => {
+          remaining -= 1;
+          if (remaining === 0) finish();
+        },
+        () => {
+          remaining -= 1;
+          if (remaining === 0) finish();
+        }
+      );
+    }
+  });
+}
+function fenceOperation(state, epoch, abortController, cleanup) {
+  abortController.abort(new DisplayStackWallTimeoutError());
+  if (!state) return;
+  if (state.epoch !== epoch) return;
+  state.pendingCleanup.set(cleanup.markerToken, cleanup);
+  state.physicallyQuiescent = false;
+  invalidateQueuedOperations(state, epoch);
+  state.epoch += 1;
+  const pending = [...state.inFlight];
+  const drain = boundedProviderDrain(pending);
+  state.drain = state.drain ? Promise.all([state.drain, drain]).then(() => void 0) : drain;
+  void drain.then(() => {
+    for (const promise of pending) state.inFlight.delete(promise);
+  });
+}
+function assertCurrentOperation(state, epoch) {
+  if (state && state.epoch !== epoch) throw new DisplayStackOperationFencedError();
+}
+async function beforeDeadline(promise, deadline, now = monotonicNow) {
+  const remainingMs = deadline - now();
+  if (remainingMs <= 0) throw new DisplayStackWallTimeoutError();
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new DisplayStackWallTimeoutError()), remainingMs);
+        timer.unref?.();
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function displayStackCleanupCommand(markerPath, markerToken) {
+  const marker = shellQuote3(markerPath);
+  const token = shellQuote3(markerToken);
+  const script = `marker=${marker}; token=${token}; cancel="$marker.cancelled"; : >"$cancel" || { echo "OPENGENI_DISPLAY_CLEANUP status=invalid"; exit 75; }; if [ ! -r "$marker" ]; then echo "OPENGENI_DISPLAY_CLEANUP status=stopped"; exit 0; fi; read -r pid pgid start actual <"$marker" || { echo "OPENGENI_DISPLAY_CLEANUP status=invalid"; exit 75; }; [ "$actual" = "$token" ] || { echo "OPENGENI_DISPLAY_CLEANUP status=invalid"; exit 75; }; case "$pid" in ''|*[!0-9]*) echo "OPENGENI_DISPLAY_CLEANUP status=invalid"; exit 75;; esac; case "$pgid" in ''|*[!0-9]*) echo "OPENGENI_DISPLAY_CLEANUP status=invalid"; exit 75;; esac; case "$start" in ''|*[!0-9]*) echo "OPENGENI_DISPLAY_CLEANUP status=invalid"; exit 75;; esac; current=$(awk '{print $22}' "/proc/$pid/stat" 2>/dev/null || true); if [ -z "$current" ] || [ "$current" != "$start" ]; then rm -f "$marker"; echo "OPENGENI_DISPLAY_CLEANUP status=stopped"; exit 0; fi; kill -TERM -- "-$pgid" 2>/dev/null || true; for i in $(seq 1 10); do if ! kill -0 -- "-$pgid" 2>/dev/null; then rm -f "$marker"; echo "OPENGENI_DISPLAY_CLEANUP status=stopped"; exit 0; fi; sleep 0.05; done; kill -KILL -- "-$pgid" 2>/dev/null || true; for i in $(seq 1 20); do if ! kill -0 -- "-$pgid" 2>/dev/null; then rm -f "$marker"; echo "OPENGENI_DISPLAY_CLEANUP status=stopped"; exit 0; fi; sleep 0.05; done; echo "OPENGENI_DISPLAY_CLEANUP status=alive"; exit 75`;
+  return `timeout --signal=TERM --kill-after=0.2s 1.5s bash -c ${shellQuote3(script)}`;
+}
+async function runProviderCommandToDeadline(session, command, deadline) {
+  const controller = new AbortController();
+  let result = await beforeDeadline(
+    Promise.resolve(
+      typeof session.exec === "function" ? session.exec({
+        cmd: command,
+        yieldTimeMs: Math.min(500, DISPLAY_STACK_CLEANUP_CALL_MS),
+        maxOutputTokens: 4e3,
+        signal: controller.signal
+      }) : session.execCommand({
+        cmd: command,
+        yieldTimeMs: Math.min(500, DISPLAY_STACK_CLEANUP_CALL_MS),
+        maxOutputTokens: 4e3,
+        signal: controller.signal
+      })
+    ),
+    deadline
+  );
+  let providerSessionId = execResultSessionId(result);
+  while (providerSessionId !== null) {
+    if (typeof session.writeStdin !== "function") {
+      throw new Error("display cleanup provider yielded without writeStdin");
+    }
+    const remainingMs = deadline - monotonicNow();
+    if (remainingMs <= 1) throw new DisplayStackWallTimeoutError();
+    result = await beforeDeadline(
+      session.writeStdin({
+        sessionId: providerSessionId,
+        chars: "",
+        yieldTimeMs: Math.max(1, Math.min(250, remainingMs - 1)),
+        maxOutputTokens: 4e3,
+        signal: controller.signal
+      }),
+      deadline
+    );
+    providerSessionId = execResultSessionId(result);
+  }
+  return result;
+}
+async function interruptProviderProcess(session, providerSessionId, deadline) {
+  if (providerSessionId === null || typeof session.writeStdin !== "function") return;
+  try {
+    await beforeDeadline(
+      session.writeStdin({
+        sessionId: providerSessionId,
+        chars: "",
+        yieldTimeMs: 100,
+        maxOutputTokens: 256
+      }),
+      deadline
+    );
+  } catch {
+  }
+}
+async function cleanupDisplayStackProcess(session, pending, deadline) {
+  try {
+    const result = await runProviderCommandToDeadline(
+      session,
+      displayStackCleanupCommand(pending.markerPath, pending.markerToken),
+      deadline
+    );
+    const output = execResultOutput(result);
+    const status = /OPENGENI_DISPLAY_CLEANUP status=(stopped|absent|alive|invalid)/u.exec(
+      output
+    )?.[1];
+    return status === "stopped";
+  } catch {
+    return false;
+  }
+}
+async function reconcilePendingCleanup(session, state, deadline) {
+  const entries = [...state.pendingCleanup.values()];
+  if (entries.length === 0) {
+    state.physicallyQuiescent = true;
+    return true;
+  }
+  const results = await Promise.all(
+    entries.map(async (pending) => ({
+      pending,
+      stopped: await cleanupDisplayStackProcess(session, pending, deadline)
+    }))
+  );
+  for (const { pending, stopped } of results) {
+    if (stopped) state.pendingCleanup.delete(pending.markerToken);
+  }
+  state.physicallyQuiescent = state.pendingCleanup.size === 0;
+  return state.physicallyQuiescent;
+}
+function requestId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function telemetryReporter(options, started, now = monotonicNow) {
+  const id = requestId();
+  const context = options.telemetryContext;
+  const sink = options.onTelemetry ?? (context ? (event) => console.info(`[display-stack] ${JSON.stringify(event)}`) : void 0);
+  const emittedSandboxStages = /* @__PURE__ */ new Set();
+  const emit = (stage, status, fields = {}) => {
+    if (!sink) return;
+    const event = {
+      type: "display_stack.stage",
+      requestId: id,
+      stage,
+      status,
+      elapsedMs: fields.elapsedMs ?? now() - started,
+      source: fields.source ?? "host",
+      classification: fields.classification ?? "unknown",
+      callerKind: context?.callerKind ?? "unknown",
+      ...context?.sandboxId ? { sandboxId: context.sandboxId } : {},
+      ...context?.leaseEpoch !== void 0 ? { leaseEpoch: context.leaseEpoch } : {},
+      ...fields.providerSessionId !== void 0 ? { providerSessionId: fields.providerSessionId } : {}
+    };
+    try {
+      void Promise.resolve(sink(event)).catch(() => void 0);
+    } catch {
+    }
+  };
+  const emitSandboxStages = (output) => {
+    for (const match of output.matchAll(
+      /OPENGENI_(?:DISPLAY|DESKTOP)_STAGE stage=([a-z0-9_]+) elapsed_ms=(\d+)(?: classification=(cold|already_ready|contention|unknown))?/gu
+    )) {
+      const [line, stage, elapsed, classification] = match;
+      if (!stage || !elapsed || emittedSandboxStages.has(line)) continue;
+      emittedSandboxStages.add(line);
+      emit(stage, "completed", {
+        source: "sandbox",
+        elapsedMs: Number(elapsed),
+        classification: classification ?? "unknown"
+      });
+    }
+  };
+  return { emit, emitSandboxStages };
+}
 function inferExitFromOutput(output) {
+  if (/OPENGENI_DISPLAY_TIMEOUT/.test(output)) {
+    return 124;
+  }
+  if (/OPENGENI_DESKTOP_LOCK_TIMEOUT/.test(output)) {
+    return 15;
+  }
   if (/OPENGENI_DESKTOP_NOT_PAINTING/.test(output)) {
     return 14;
   }
@@ -17807,15 +18584,163 @@ async function ensureDisplayStack(session, options = {}) {
   const geometry = options.geometry ?? DEFAULT_DESKTOP_GEOMETRY;
   const port = options.port ?? DESKTOP_STREAM_PORT4;
   const timeoutMs = options.timeoutMs ?? DISPLAY_STACK_TIMEOUT_MS;
-  const cmd = buildDisplayStackScript({ geometry, port });
-  const result = typeof s.exec === "function" ? await s.exec({ cmd, yieldTimeMs: timeoutMs, maxOutputTokens: 2e4 }) : await s.execCommand({ cmd, yieldTimeMs: timeoutMs, maxOutputTokens: 2e4 });
-  const output = execResultOutput(result);
-  const exitCode = execResultExitCode(result) ?? inferExitFromOutput(output);
-  if (exitCode !== 0) {
-    throw new DisplayStackError(exitCode, output);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new RangeError("ensureDisplayStack timeoutMs must be a positive finite number");
+  }
+  const started = monotonicNow();
+  const deadline = started + timeoutMs;
+  const telemetry = telemetryReporter(options, started, monotonicNow);
+  const operationToken = requestId();
+  const markerPath = `/tmp/opengeni-desktop/display-stack-${operationToken}.pid`;
+  const cmd = boundedDisplayStackCommand(
+    buildDisplayStackScript({ geometry, port }),
+    timeoutMs,
+    markerPath,
+    operationToken
+  );
+  const outputParts = [];
+  const state = operationState(session, options);
+  let release;
+  if (state) {
+    try {
+      release = await acquireOperation(state, deadline);
+    } catch (error) {
+      if (error instanceof DisplayStackWallTimeoutError || error instanceof DisplayStackOperationFencedError) {
+        throw new DisplayStackError(
+          124,
+          "OPENGENI_DISPLAY_TIMEOUT display operation admission was fenced"
+        );
+      }
+      throw error;
+    }
+  }
+  try {
+    if (state && !state.physicallyQuiescent) {
+      const cleanupDeadline = monotonicNow() + DISPLAY_STACK_CLEANUP_CALL_MS;
+      const quiesced = await reconcilePendingCleanup(s, state, cleanupDeadline);
+      if (!quiesced) {
+        throw new DisplayStackError(
+          124,
+          "OPENGENI_DISPLAY_TIMEOUT physical cleanup is still pending; retry is fenced"
+        );
+      }
+    }
+    const epoch = state?.epoch ?? 0;
+    const abortController = new AbortController();
+    let activeProviderSessionId = null;
+    telemetry.emit("request_entry", "started");
+    telemetry.emit("exec_issued", "started");
+    try {
+      const initialYieldMs = Math.max(1, Math.min(DISPLAY_STACK_PROVIDER_YIELD_MS, timeoutMs - 1));
+      const initialExec = trackProviderCall(
+        state,
+        Promise.resolve(
+          typeof s.exec === "function" ? s.exec({
+            cmd,
+            yieldTimeMs: initialYieldMs,
+            maxOutputTokens: 2e4,
+            signal: abortController.signal
+          }) : s.execCommand({
+            cmd,
+            yieldTimeMs: initialYieldMs,
+            maxOutputTokens: 2e4,
+            signal: abortController.signal
+          })
+        )
+      );
+      let result = await beforeDeadline(
+        initialExec,
+        deadline,
+        monotonicNow
+      );
+      assertCurrentOperation(state, epoch);
+      let chunk = execResultOutput(result);
+      outputParts.push(chunk);
+      telemetry.emitSandboxStages(chunk);
+      telemetry.emit("provider_first_result", "completed");
+      let providerSessionId = execResultSessionId(result);
+      activeProviderSessionId = providerSessionId;
+      while (providerSessionId !== null) {
+        telemetry.emit("provider_yield", "waiting", { providerSessionId });
+        if (typeof s.writeStdin !== "function") {
+          throw new DisplayStackError(
+            -1,
+            `${outputParts.join("\n")}
+provider yielded process ${providerSessionId} but exposes no writeStdin poll surface`
+          );
+        }
+        assertCurrentOperation(state, epoch);
+        const remainingMs = deadline - monotonicNow();
+        if (remainingMs <= 1) throw new DisplayStackWallTimeoutError();
+        const pollYieldMs = Math.max(1, Math.min(DISPLAY_STACK_PROVIDER_POLL_MS, remainingMs - 1));
+        result = await beforeDeadline(
+          trackProviderCall(
+            state,
+            s.writeStdin({
+              sessionId: providerSessionId,
+              chars: "",
+              yieldTimeMs: pollYieldMs,
+              maxOutputTokens: 2e4,
+              signal: abortController.signal
+            })
+          ),
+          deadline,
+          monotonicNow
+        );
+        assertCurrentOperation(state, epoch);
+        chunk = execResultOutput(result);
+        outputParts.push(chunk);
+        telemetry.emitSandboxStages(chunk);
+        providerSessionId = execResultSessionId(result);
+        activeProviderSessionId = providerSessionId;
+      }
+      const output = outputParts.join("\n");
+      const exitCode = execResultExitCode(result) ?? inferExitFromOutput(output);
+      telemetry.emit("process_complete", exitCode === 0 ? "completed" : "failed");
+      if (exitCode !== 0) {
+        throw new DisplayStackError(exitCode, output);
+      }
+      const marker = (output.match(/OPENGENI_DESKTOP_UP[^\n]*/) ?? [""])[0];
+      telemetry.emit("readiness_complete", "completed");
+      return { port, geometry, marker };
+    } catch (error) {
+      if (error instanceof DisplayStackWallTimeoutError || error instanceof DisplayStackOperationFencedError) {
+        const pendingCleanup = {
+          markerPath,
+          markerToken: operationToken
+        };
+        fenceOperation(state, epoch, abortController, pendingCleanup);
+        const cleanupDeadline = monotonicNow() + DISPLAY_STACK_CLEANUP_CALL_MS;
+        telemetry.emit("process_cleanup", "started");
+        await interruptProviderProcess(
+          s,
+          activeProviderSessionId,
+          Math.min(cleanupDeadline, monotonicNow() + 50)
+        );
+        let quiesced = false;
+        if (state) {
+          quiesced = await reconcilePendingCleanup(s, state, cleanupDeadline);
+          if (!quiesced) {
+            await waitForFencedOperation(
+              state,
+              Math.min(cleanupDeadline, monotonicNow() + DISPLAY_STACK_DRAIN_GRACE_MS)
+            );
+          }
+        } else {
+          quiesced = await cleanupDisplayStackProcess(s, pendingCleanup, cleanupDeadline);
+        }
+        telemetry.emit("process_cleanup", quiesced ? "completed" : "failed");
+        const output = `${outputParts.join("\n")}
+OPENGENI_DISPLAY_TIMEOUT wall_ms=${timeoutMs}`;
+        telemetry.emit("wall_deadline", "failed");
+        throw new DisplayStackError(124, output);
+      }
+      telemetry.emit("request_failed", "failed");
+      throw error;
+    }
+  } finally {
+    release?.();
   }
-  const marker = (output.match(/OPENGENI_DESKTOP_UP[^\n]*/) ?? [""])[0];
-  return { port, geometry, marker };
 }
 async function tearDownDisplayStack(session) {
   const s = session;
@@ -18235,7 +19160,7 @@ function runCredentialRoot(sessionId) {
 function runCredentialPointerFile(sessionId) {
   return `${runCredentialRoot(sessionId)}/current`;
 }
-function shellQuote3(value) {
+function shellQuote4(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 function base64(value) {
@@ -18253,8 +19178,8 @@ function portableBase64DecodeCommand() {
   ].join("\n");
 }
 function pointerLockAcquireCommands(root) {
-  const lockFile = shellQuote3(`${root}/.pointer.lock`);
-  const lockDirectory = shellQuote3(`${root}/.pointer.lockdir`);
+  const lockFile = shellQuote4(`${root}/.pointer.lock`);
+  const lockDirectory = shellQuote4(`${root}/.pointer.lockdir`);
   return [
     `if command -v flock >/dev/null 2>&1; then`,
     `  exec 9>${lockFile}`,
@@ -18298,7 +19223,7 @@ async function runCredentialCommand(session, cmd, commandRunner) {
 ${cmd}
 printf '\\n${COMMAND_OK_MARKER}\\n'`;
   const args = {
-    cmd: `env -u BASH_ENV bash --noprofile --norc -c ${shellQuote3(marked)}`,
+    cmd: `env -u BASH_ENV bash --noprofile --norc -c ${shellQuote4(marked)}`,
     yieldTimeMs: 12e4,
     maxOutputTokens: 4e3
   };
@@ -18308,19 +19233,19 @@ printf '\\n${COMMAND_OK_MARKER}\\n'`;
   }
 }
 async function writeCredentialFile(session, path, content, commandRunner) {
-  await runCredentialCommand(session, `: > ${shellQuote3(path)}`, commandRunner);
+  await runCredentialCommand(session, `: > ${shellQuote4(path)}`, commandRunner);
   const encoded = base64(content);
   for (let offset = 0; offset < encoded.length; offset += WRITE_CHUNK_BYTES) {
     const chunk = encoded.slice(offset, offset + WRITE_CHUNK_BYTES);
     await runCredentialCommand(
       session,
-      `printf %s ${shellQuote3(chunk)} | ${portableBase64DecodeCommand()} >> ${shellQuote3(path)}`,
+      `printf %s ${shellQuote4(chunk)} | ${portableBase64DecodeCommand()} >> ${shellQuote4(path)}`,
       commandRunner
     );
   }
   await runCredentialCommand(
     session,
-    `[ "$(wc -c < ${shellQuote3(path)} | tr -d '[:space:]')" = ${shellQuote3(String(byteLength(content)))} ]`,
+    `[ "$(wc -c < ${shellQuote4(path)} | tr -d '[:space:]')" = ${shellQuote4(String(byteLength(content)))} ]`,
     commandRunner
   );
 }
@@ -18345,19 +19270,19 @@ async function materializeRunCredentials(session, material, options) {
     session,
     [
       "umask 077",
-      `mkdir -p -- ${shellQuote3(`${root}/versions`)}`,
-      `chmod 0700 -- ${shellQuote3(root)} ${shellQuote3(`${root}/versions`)}`,
-      `rm -rf -- ${shellQuote3(stage)}`,
-      `mkdir -p -- ${shellQuote3(`${stage}/files`)}`
+      `mkdir -p -- ${shellQuote4(`${root}/versions`)}`,
+      `chmod 0700 -- ${shellQuote4(root)} ${shellQuote4(`${root}/versions`)}`,
+      `rm -rf -- ${shellQuote4(stage)}`,
+      `mkdir -p -- ${shellQuote4(`${stage}/files`)}`
     ].join("\n"),
     options.commandRunner
   );
   const environmentLines = [
     ...Object.entries(material.environment).map(
-      ([name, value]) => `export ${name}=${shellQuote3(value)}`
+      ([name, value]) => `export ${name}=${shellQuote4(value)}`
     ),
     ...Object.entries(material.fileEnvironment).map(
-      ([name, path]) => `export ${name}=${shellQuote3(`${version}/files/${path}`)}`
+      ([name, path]) => `export ${name}=${shellQuote4(`${version}/files/${path}`)}`
     )
   ];
   await writeCredentialFile(
@@ -18369,17 +19294,17 @@ async function materializeRunCredentials(session, material, options) {
   );
   await runCredentialCommand(
     session,
-    `chmod 0600 -- ${shellQuote3(`${stage}/env`)}`,
+    `chmod 0600 -- ${shellQuote4(`${stage}/env`)}`,
     options.commandRunner
   );
   for (const file of material.files) {
     const target = `${stage}/files/${file.path}`;
     const parent = target.slice(0, target.lastIndexOf("/"));
-    await runCredentialCommand(session, `mkdir -p -- ${shellQuote3(parent)}`, options.commandRunner);
+    await runCredentialCommand(session, `mkdir -p -- ${shellQuote4(parent)}`, options.commandRunner);
     await writeCredentialFile(session, target, file.content, options.commandRunner);
     await runCredentialCommand(
       session,
-      `chmod ${shellQuote3(file.mode ?? "0600")} -- ${shellQuote3(target)}`,
+      `chmod ${shellQuote4(file.mode ?? "0600")} -- ${shellQuote4(target)}`,
       options.commandRunner
     );
   }
@@ -18387,19 +19312,19 @@ async function materializeRunCredentials(session, material, options) {
     session,
     [
       ...pointerLockAcquireCommands(root),
-      `previous=$(cat -- ${shellQuote3(`${root}/current`)} 2>/dev/null || :)`,
-      `mv -- ${shellQuote3(stage)} ${shellQuote3(version)}`,
-      `printf '%s\\n' ${shellQuote3(versionName)} > ${shellQuote3(`${root}/.next`)}`,
-      `mv -f -- ${shellQuote3(`${root}/.next`)} ${shellQuote3(`${root}/current`)}`,
+      `previous=$(cat -- ${shellQuote4(`${root}/current`)} 2>/dev/null || :)`,
+      `mv -- ${shellQuote4(stage)} ${shellQuote4(version)}`,
+      `printf '%s\\n' ${shellQuote4(versionName)} > ${shellQuote4(`${root}/.next`)}`,
+      `mv -f -- ${shellQuote4(`${root}/.next`)} ${shellQuote4(`${root}/current`)}`,
       ...options.prunePreviousGenerations ? [
-        `find ${shellQuote3(`${root}/versions`)} -mindepth 1 -maxdepth 1 ! -name ${shellQuote3(versionName)} -exec rm -rf -- {} +`
+        `find ${shellQuote4(`${root}/versions`)} -mindepth 1 -maxdepth 1 ! -name ${shellQuote4(versionName)} -exec rm -rf -- {} +`
       ] : options.pruneOtherAttempts ? [
-        `find ${shellQuote3(`${root}/versions`)} -mindepth 1 -maxdepth 1 ! -name ${shellQuote3(`${attemptId}-${options.executionGeneration}-*`)} -exec rm -rf -- {} +`
+        `find ${shellQuote4(`${root}/versions`)} -mindepth 1 -maxdepth 1 ! -name ${shellQuote4(`${attemptId}-${options.executionGeneration}-*`)} -exec rm -rf -- {} +`
       ] : options.pruneSupersededGenerations ? [
-        `for candidate in ${shellQuote3(`${root}/versions`)}/${prefix}*; do`,
+        `for candidate in ${shellQuote4(`${root}/versions`)}/${prefix}*; do`,
         `  [ -e "$candidate" ] || continue`,
         `  name=\${candidate##*/}`,
-        `  [ "$name" = ${shellQuote3(versionName)} ] || [ "$name" = "$previous" ] || rm -rf -- "$candidate"`,
+        `  [ "$name" = ${shellQuote4(versionName)} ] || [ "$name" = "$previous" ] || rm -rf -- "$candidate"`,
         "done"
       ] : [],
       ...pointerLockReleaseCommands()
@@ -18412,10 +19337,10 @@ async function clearRunCredentials(session, sessionId, commandRunner) {
   await runCredentialCommand(
     session,
     [
-      `if [ -d ${shellQuote3(root)} ]; then`,
+      `if [ -d ${shellQuote4(root)} ]; then`,
       ...pointerLockAcquireCommands(root).map((line) => `  ${line}`),
-      `  rm -f -- ${shellQuote3(`${root}/current`)} ${shellQuote3(`${root}/.next`)}`,
-      `  rm -rf -- ${shellQuote3(`${root}/versions`)}`,
+      `  rm -f -- ${shellQuote4(`${root}/current`)} ${shellQuote4(`${root}/.next`)}`,
+      `  rm -rf -- ${shellQuote4(`${root}/versions`)}`,
       ...pointerLockReleaseCommands().map((line) => `  ${line}`),
       "fi"
     ].join("\n"),
@@ -18432,15 +19357,15 @@ async function clearRunCredentialsForAttempt(session, options, commandRunner) {
   await runCredentialCommand(
     session,
     [
-      `if [ -d ${shellQuote3(root)} ]; then`,
+      `if [ -d ${shellQuote4(root)} ]; then`,
       ...pointerLockAcquireCommands(root).map((line) => `  ${line}`),
-      `  if [ -r ${shellQuote3(`${root}/current`)} ]; then`,
-      `    current=$(cat -- ${shellQuote3(`${root}/current`)} 2>/dev/null || :)`,
-      `    case "$current" in ${shellQuote3(prefix)}*) rm -f -- ${shellQuote3(`${root}/current`)} ;; esac`,
+      `  if [ -r ${shellQuote4(`${root}/current`)} ]; then`,
+      `    current=$(cat -- ${shellQuote4(`${root}/current`)} 2>/dev/null || :)`,
+      `    case "$current" in ${shellQuote4(prefix)}*) rm -f -- ${shellQuote4(`${root}/current`)} ;; esac`,
       "  fi",
-      `  if [ -d ${shellQuote3(`${root}/versions`)} ]; then`,
-      `    find ${shellQuote3(`${root}/versions`)} -mindepth 1 -maxdepth 1 -name ${shellQuote3(`${prefix}*`)} -exec rm -rf -- {} +`,
-      `    find ${shellQuote3(`${root}/versions`)} -mindepth 1 -maxdepth 1 -name ${shellQuote3(`.stage-${prefix}*`)} -exec rm -rf -- {} +`,
+      `  if [ -d ${shellQuote4(`${root}/versions`)} ]; then`,
+      `    find ${shellQuote4(`${root}/versions`)} -mindepth 1 -maxdepth 1 -name ${shellQuote4(`${prefix}*`)} -exec rm -rf -- {} +`,
+      `    find ${shellQuote4(`${root}/versions`)} -mindepth 1 -maxdepth 1 -name ${shellQuote4(`.stage-${prefix}*`)} -exec rm -rf -- {} +`,
       "  fi",
       ...pointerLockReleaseCommands().map((line) => `  ${line}`),
       "fi"
@@ -18452,12 +19377,12 @@ function withRunCredentialEnvironment(cmd, sessionId) {
   const root = runCredentialRoot(sessionId);
   const pointerFile = runCredentialPointerFile(sessionId);
   return [
-    `if [ -r ${shellQuote3(pointerFile)} ]; then`,
-    `  _opengeni_credential_version=$(cat -- ${shellQuote3(pointerFile)} 2>/dev/null || :)`,
+    `if [ -r ${shellQuote4(pointerFile)} ]; then`,
+    `  _opengeni_credential_version=$(cat -- ${shellQuote4(pointerFile)} 2>/dev/null || :)`,
     '  case "$_opengeni_credential_version" in',
     "    ''|*[!A-Za-z0-9_-]*) ;;",
     "    *)",
-    `      _opengeni_credential_env=${shellQuote3(`${root}/versions`)}/"$_opengeni_credential_version/env"`,
+    `      _opengeni_credential_env=${shellQuote4(`${root}/versions`)}/"$_opengeni_credential_version/env"`,
     '      if [ -r "$_opengeni_credential_env" ]; then',
     "        set -a",
     '        . "$_opengeni_credential_env"',
@@ -18525,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 {
@@ -18534,7 +19459,7 @@ var ToolspaceTokenPathError = class extends Error {
     this.name = "ToolspaceTokenPathError";
   }
 };
-function shellQuote4(value) {
+function shellQuote5(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 function assertToolspaceSessionId(sessionId) {
@@ -18548,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) {
@@ -18559,7 +19484,7 @@ function withToolspaceTokenEnvironment(cmd, tokenFile) {
   if (!tokenFile || tokenFile.includes("\0") || !posixPath.isAbsolute(tokenFile)) {
     throw new ToolspaceTokenPathError("Toolspace token file must be absolute");
   }
-  return [`export OPENGENI_TOOLSPACE_TOKEN_FILE=${shellQuote4(tokenFile)}`, cmd].join("\n");
+  return [`export OPENGENI_TOOLSPACE_TOKEN_FILE=${shellQuote5(tokenFile)}`, cmd].join("\n");
 }
 function withToolspaceTokenSession(session, tokenFile) {
   return new Proxy(session, {
@@ -18828,6 +19753,804 @@ 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 wrapCapabilityToolsForTurnCancellation(capability, controller) {
+  const originalTools = capability.tools;
+  capability.tools = function() {
+    return controller.wrapTools(originalTools.call(this), this._session);
+  };
+}
+
 // src/sandbox/channel-a.ts
 var ChannelAValidationError = class extends Error {
   constructor(message) {
@@ -18953,11 +20676,11 @@ var SandboxChannelAService = class {
     const depthArg = Math.max(1, req.depth);
     const maxCommandEntries = req.maxEntries + 1;
     const gnuPrint = `-printf '%y\\t%s\\t%T@\\t%m\\t%p\\0'`;
-    const gnuSelector = pruneNames.length ? `\\( -type d \\( ${pruneNames.map((name) => `-name ${shellQuote5(name)}`).join(" -o ")} \\) ${gnuPrint} -prune \\) -o ${gnuPrint}` : gnuPrint;
+    const gnuSelector = pruneNames.length ? `\\( -type d \\( ${pruneNames.map((name) => `-name ${shellQuote6(name)}`).join(" -o ")} \\) ${gnuPrint} -prune \\) -o ${gnuPrint}` : gnuPrint;
     const gnuVisibleSelector = req.includeHidden ? gnuSelector : `\\( -path '*/.*' -prune \\) -o \\( ${gnuSelector} \\)`;
     const gnuFind = `find ${findRoot} -mindepth 1 -maxdepth ${depthArg} \\( ${gnuVisibleSelector} \\) 2>/dev/null`;
     const portableHiddenGuard = req.includeHidden ? "" : `if [[ "$base" == .* ]]; then continue; fi;`;
-    const portablePruneCase = pruneNames.length ? `case "$base" in ${pruneNames.map(shellQuote5).join("|")}) pruned=1 ;; *) pruned=0 ;; esac;` : "pruned=0;";
+    const portablePruneCase = pruneNames.length ? `case "$base" in ${pruneNames.map(shellQuote6).join("|")}) pruned=1 ;; *) pruned=0 ;; esac;` : "pruned=0;";
     const portableWalk = [
       "shopt -s nullglob dotglob; count=0; stop=0;",
       'walk() { local dir="$1" level="$2" p base t size mtime mode pruned;',
@@ -18986,12 +20709,12 @@ var SandboxChannelAService = class {
       `if [ "$records" -ge ${req.maxEntries} ] || [ $((bytes + record_bytes + 1)) -gt ${FS_LIST_MAX_OUTPUT_BYTES} ]; then truncated=1; break; fi;`,
       `printf '%s\\0' "$record"; bytes=$((bytes + record_bytes + 1)); records=$((records + 1));`,
       "done;",
-      `if [ "$truncated" -eq 1 ]; then printf '%s\\0' ${shellQuote5(FS_LIST_TRUNCATED_MARKER)}; fi`
+      `if [ "$truncated" -eq 1 ]; then printf '%s\\0' ${shellQuote6(FS_LIST_TRUNCATED_MARKER)}; fi`
     ].join(" ");
     const findCommand = [
       `{ ${rawFindCommand}; } | { ${boundedOutput}; };`,
       "producer_status=${PIPESTATUS[0]};",
-      `if [ "$producer_status" -ne 0 ] && [ "$producer_status" -ne 141 ]; then printf '%s\\0' ${shellQuote5(FS_LIST_TRUNCATED_MARKER)}; fi`
+      `if [ "$producer_status" -ne 0 ] && [ "$producer_status" -ne 141 ]; then printf '%s\\0' ${shellQuote6(FS_LIST_TRUNCATED_MARKER)}; fi`
     ].join(" ");
     const { stdout, exitCode } = await this.runInConfinedDirectory(root, {
       cmd: internalBashCommand(findCommand),
@@ -19084,11 +20807,11 @@ var SandboxChannelAService = class {
   async assertConfinedExistingDirectory(path) {
     const root = this.workspaceRoot || ".";
     const abs = this.joinRoot(path);
-    const rejectLink = path ? `test ! -L ${shellQuote5(abs)} || { printf '__OPENGENI_FS_SYMLINK__'; exit 68; }` : ":";
+    const rejectLink = path ? `test ! -L ${shellQuote6(abs)} || { printf '__OPENGENI_FS_SYMLINK__'; exit 68; }` : ":";
     const script = [
-      `root=$(realpath -e -- ${shellQuote5(root)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
+      `root=$(realpath -e -- ${shellQuote6(root)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       rejectLink,
-      `target=$(realpath -e -- ${shellQuote5(abs)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
+      `target=$(realpath -e -- ${shellQuote6(abs)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       `case "$target" in "$root"|"$root"/*) ;; *) printf '__OPENGENI_FS_ESCAPE__'; exit 67 ;; esac`,
       `test -d "$target" || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       `printf '__OPENGENI_FS_CONFINED_OK__'`
@@ -19099,13 +20822,13 @@ var SandboxChannelAService = class {
   async assertConfinedMutationParent(path, options) {
     const root = this.workspaceRoot || ".";
     const abs = this.joinRoot(path);
-    const rejectLink = options.rejectFinalSymlink ? `test ! -L ${shellQuote5(abs)} || { printf '__OPENGENI_FS_SYMLINK__'; exit 68; }` : ":";
+    const rejectLink = options.rejectFinalSymlink ? `test ! -L ${shellQuote6(abs)} || { printf '__OPENGENI_FS_SYMLINK__'; exit 68; }` : ":";
     const locateParent = options.allowMissingParents ? 'probe="$parent"; while [ ! -e "$probe" ] && [ ! -L "$probe" ]; do next=$(dirname -- "$probe"); [ "$next" != "$probe" ] || break; probe="$next"; done' : 'probe="$parent"';
     const requireParent = options.allowMissingParents ? ":" : 'test -d "$parent" || { printf "__OPENGENI_FS_NOT_FOUND__"; exit 66; }';
     const script = [
-      `root=$(realpath -e -- ${shellQuote5(root)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
+      `root=$(realpath -e -- ${shellQuote6(root)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       rejectLink,
-      `parent=$(dirname -- ${shellQuote5(abs)})`,
+      `parent=$(dirname -- ${shellQuote6(abs)})`,
       locateParent,
       `target=$(realpath -e -- "$probe") || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       `case "$target" in "$root"|"$root"/*) ;; *) printf '__OPENGENI_FS_ESCAPE__'; exit 67 ;; esac`,
@@ -19142,8 +20865,8 @@ var SandboxChannelAService = class {
     const root = this.workspaceRoot || ".";
     const abs = this.joinRoot(path);
     const script = [
-      `root=$(realpath -e -- ${shellQuote5(root)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
-      `exec 3<${shellQuote5(abs)} || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
+      `root=$(realpath -e -- ${shellQuote6(root)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
+      `exec 3<${shellQuote6(abs)} || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       `target=$(readlink -f -- "/proc/$$/fd/3") || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       `case "$target" in "$root"|"$root"/*) ;; *) printf '__OPENGENI_FS_ESCAPE__'; exit 67 ;; esac`,
       `test -f "$target" || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
@@ -19212,7 +20935,7 @@ var SandboxChannelAService = class {
     });
     if (!req.overwrite) {
       const { exitCode: exitCode2 } = await this.run({
-        cmd: `test -e ${shellQuote5(abs)} || test -L ${shellQuote5(abs)}`
+        cmd: `test -e ${shellQuote6(abs)} || test -L ${shellQuote6(abs)}`
       });
       if (exitCode2 === 0) {
         throw new ChannelAConflictError(`path exists and overwrite is false: ${path}`);
@@ -19220,7 +20943,7 @@ var SandboxChannelAService = class {
     }
     if (req.createParents) {
       const dir = dirnameAbs(abs);
-      if (dir) await this.run({ cmd: `mkdir -p ${shellQuote5(dir)}` });
+      if (dir) await this.run({ cmd: `mkdir -p ${shellQuote6(dir)}` });
       await this.assertConfinedMutationParent(path, {
         allowMissingParents: false,
         rejectFinalSymlink: true
@@ -19228,7 +20951,7 @@ var SandboxChannelAService = class {
     }
     const b64 = bytes.toString("base64");
     const { exitCode, stderr } = await this.run({
-      cmd: `printf %s ${shellQuote5(b64)} | base64 -d > ${shellQuote5(abs)}`
+      cmd: `printf %s ${shellQuote6(b64)} | base64 -d > ${shellQuote6(abs)}`
     });
     if (exitCode !== null && exitCode !== 0) {
       if (req.encoding !== "base64" && this.session.createEditor) {
@@ -19269,7 +20992,7 @@ var SandboxChannelAService = class {
       rejectFinalSymlink: false
     });
     const flag = req.recursive ? "-rf" : "-f";
-    const { exitCode, stderr } = await this.run({ cmd: `rm ${flag} ${shellQuote5(abs)}` });
+    const { exitCode, stderr } = await this.run({ cmd: `rm ${flag} ${shellQuote6(abs)}` });
     if (exitCode !== null && exitCode !== 0) {
       throw new ChannelAValidationError(
         `failed to delete ${path}: ${stderr || `exit ${exitCode}`}`
@@ -19294,7 +21017,7 @@ var SandboxChannelAService = class {
     });
     if (!req.overwrite) {
       const { exitCode: exitCode2 } = await this.run({
-        cmd: `test -e ${shellQuote5(newAbs)} || test -L ${shellQuote5(newAbs)}`
+        cmd: `test -e ${shellQuote6(newAbs)} || test -L ${shellQuote6(newAbs)}`
       });
       if (exitCode2 === 0) {
         throw new ChannelAConflictError(`destination exists and overwrite is false: ${newPath}`);
@@ -19302,7 +21025,7 @@ var SandboxChannelAService = class {
     }
     if (req.createParents) {
       const dir = dirnameAbs(newAbs);
-      if (dir) await this.run({ cmd: `mkdir -p ${shellQuote5(dir)}` });
+      if (dir) await this.run({ cmd: `mkdir -p ${shellQuote6(dir)}` });
       await this.assertConfinedMutationParent(newPath, {
         allowMissingParents: false,
         rejectFinalSymlink: true
@@ -19310,7 +21033,7 @@ var SandboxChannelAService = class {
     }
     const flag = req.overwrite ? "-f " : "";
     const { exitCode, stderr } = await this.run({
-      cmd: `mv ${flag}${shellQuote5(abs)} ${shellQuote5(newAbs)}`
+      cmd: `mv ${flag}${shellQuote6(abs)} ${shellQuote6(newAbs)}`
     });
     if (exitCode !== null && exitCode !== 0) {
       throw new ChannelAValidationError(
@@ -19335,7 +21058,7 @@ var SandboxChannelAService = class {
       rejectFinalSymlink: true
     });
     const flag = req.recursive ? "-p " : "";
-    const { exitCode, stderr } = await this.run({ cmd: `mkdir ${flag}${shellQuote5(abs)}` });
+    const { exitCode, stderr } = await this.run({ cmd: `mkdir ${flag}${shellQuote6(abs)}` });
     if (exitCode !== null && exitCode !== 0) {
       throw new ChannelAValidationError(`failed to mkdir ${path}: ${stderr || `exit ${exitCode}`}`);
     }
@@ -19371,10 +21094,10 @@ var SandboxChannelAService = class {
     const repo = assertSafeRelPathOrRoot(req.path);
     const ctx = req.contextLines;
     let range = "";
-    if (req.fromRef && req.toRef) range = `${shellQuote5(req.fromRef)} ${shellQuote5(req.toRef)}`;
-    else if (req.fromRef) range = `${shellQuote5(req.fromRef)}`;
+    if (req.fromRef && req.toRef) range = `${shellQuote6(req.fromRef)} ${shellQuote6(req.toRef)}`;
+    else if (req.fromRef) range = `${shellQuote6(req.fromRef)}`;
     else if (req.staged) range = "--cached";
-    const pathspec = req.pathspec.length ? ` -- ${req.pathspec.map(shellQuote5).join(" ")}` : "";
+    const pathspec = req.pathspec.length ? ` -- ${req.pathspec.map(shellQuote6).join(" ")}` : "";
     const numstat = await this.runInConfinedDirectory(repo, {
       cmd: `git -c core.quotePath=false diff --no-color -z --numstat ${range}${pathspec}`.trim()
     });
@@ -19398,7 +21121,7 @@ var SandboxChannelAService = class {
         continue;
       }
       const patch = await this.runInConfinedDirectory(repo, {
-        cmd: `git -c core.quotePath=false diff --no-color -U${ctx} ${range} -- ${shellQuote5(target)}`.trim()
+        cmd: `git -c core.quotePath=false diff --no-color -U${ctx} ${range} -- ${shellQuote6(target)}`.trim()
       });
       const oversized = Buffer.byteLength(patch.stdout, "utf8") > req.maxBytesPerFile;
       const parsed = oversized ? { hunks: [], status: "modified" } : parseUnifiedPatch(patch.stdout);
@@ -19422,7 +21145,7 @@ var SandboxChannelAService = class {
         const fileArg = target.startsWith("./") ? target : `./${target}`;
         const read = await this.runInConfinedDirectory(repo, {
           cmd: [
-            `file=${shellQuote5(fileArg)}`,
+            `file=${shellQuote6(fileArg)}`,
             'if [ -L "$file" ]; then printf "L\\n"; readlink -z -- "$file" | base64 | tr -d "\\n"; exit; fi',
             'size=$(wc -c < "$file") || exit 66',
             'line_count=$(wc -l < "$file") || exit 66',
@@ -19486,9 +21209,9 @@ var SandboxChannelAService = class {
   async gitLog(req) {
     const repo = assertSafeRelPathOrRoot(req.path);
     const fmt = `%H${US}%h${US}%P${US}%an${US}%ae${US}%at${US}%cn${US}%ce${US}%ct${US}%s${US}%b${RS}`;
-    const pathspec = req.pathspec.length ? ` -- ${req.pathspec.map(shellQuote5).join(" ")}` : "";
+    const pathspec = req.pathspec.length ? ` -- ${req.pathspec.map(shellQuote6).join(" ")}` : "";
     const { stdout, exitCode } = await this.runInConfinedDirectory(repo, {
-      cmd: `git log --format=${shellQuote5(fmt)} -n${req.maxCount + 1} --skip=${req.skip} ${shellQuote5(req.ref)}${pathspec}`
+      cmd: `git log --format=${shellQuote6(fmt)} -n${req.maxCount + 1} --skip=${req.skip} ${shellQuote6(req.ref)}${pathspec}`
     });
     if (exitCode !== null && exitCode !== 0) {
       return { commits: [], hasMore: false };
@@ -19515,7 +21238,7 @@ var SandboxChannelAService = class {
     const repo = assertSafeRelPathOrRoot(req.path);
     if (req.filePath) {
       const { stdout, exitCode } = await this.runInConfinedDirectory(repo, {
-        cmd: `git cat-file blob ${shellQuote5(`${req.ref}:${req.filePath}`)} 2>/dev/null | base64`
+        cmd: `git cat-file blob ${shellQuote6(`${req.ref}:${req.filePath}`)} 2>/dev/null | base64`
       });
       if (exitCode !== null && exitCode !== 0 && stdout.trim() === "") {
         throw new ChannelANotFoundError(`blob not found: ${req.ref}:${req.filePath}`);
@@ -19646,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();
@@ -19676,7 +21431,7 @@ var SandboxChannelAService = class {
       stdout: r.stdout,
       stderr: r.stderr,
       exitCode: r.exitCode,
-      running,
+      running: false,
       wallTimeSeconds: r.wallTimeSeconds
     };
   }
@@ -19706,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
@@ -19722,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). */
@@ -19756,11 +21511,11 @@ var SandboxChannelAService = class {
     const safe = assertSafeRelPathOrRoot(rel);
     const root = this.workspaceRoot || ".";
     const abs = this.joinRoot(safe);
-    const rejectLink = safe ? `test ! -L ${shellQuote5(abs)} || { printf '__OPENGENI_FS_SYMLINK__'; exit 68; }` : ":";
+    const rejectLink = safe ? `test ! -L ${shellQuote6(abs)} || { printf '__OPENGENI_FS_SYMLINK__'; exit 68; }` : ":";
     const script = [
-      `root=$(realpath -e -- ${shellQuote5(root)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
+      `root=$(realpath -e -- ${shellQuote6(root)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       rejectLink,
-      `target=$(realpath -e -- ${shellQuote5(abs)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
+      `target=$(realpath -e -- ${shellQuote6(abs)}) || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       `case "$target" in "$root"|"$root"/*) ;; *) printf '__OPENGENI_FS_ESCAPE__'; exit 67 ;; esac`,
       `test -d "$target" || { printf '__OPENGENI_FS_NOT_FOUND__'; exit 66; }`,
       `cd -P -- "$target"`,
@@ -19870,28 +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 parseExecBannerSessionId(raw) {
-  const outputIdx = raw.indexOf("\nOutput:\n");
-  const banner = outputIdx >= 0 ? raw.slice(0, outputIdx) : raw.startsWith("Output:\n") ? "" : raw;
-  const match = banner.match(/Process running with session ID (\d+)/);
-  if (!match) return null;
-  const n = Number.parseInt(match[1], 10);
-  return Number.isFinite(n) ? n : null;
-}
-function parseExecBannerExitCode(raw) {
-  const outputIdx = raw.indexOf("\nOutput:\n");
-  const banner = outputIdx >= 0 ? raw.slice(0, outputIdx) : raw.startsWith("Output:\n") ? "" : raw;
-  const match = banner.match(/Process exited with code (-?\d+)/);
-  if (!match) return null;
-  const exitCode = Number.parseInt(match[1], 10);
-  return Number.isSafeInteger(exitCode) ? exitCode : null;
-}
 function sniffBinary(bytes) {
   const n = Math.min(bytes.byteLength, 8192);
   for (let i = 0; i < n; i++) if (bytes[i] === 0) return true;
@@ -19925,11 +21658,11 @@ function assertSafeRelPath(p) {
   if (norm === "") throw new ChannelAValidationError("path is required");
   return norm;
 }
-function shellQuote5(s) {
+function shellQuote6(s) {
   return `'${s.replace(/'/g, `'\\''`)}'`;
 }
 function internalBashCommand(script) {
-  return `env -u BASH_ENV bash --noprofile --norc -c ${shellQuote5(script)}`;
+  return `env -u BASH_ENV bash --noprofile --norc -c ${shellQuote6(script)}`;
 }
 function assertSafePruneDirectoryName(name) {
   if (name.length > 255 || !/^[A-Za-z0-9._@+-]+$/.test(name) || name === "." || name === "..") {
@@ -20463,12 +22196,12 @@ function defaultEcho(req, hostname) {
     durationMs: "1"
   };
 }
-function ok(requestId, result) {
-  return { requestId, error: void 0, result };
+function ok(requestId2, result) {
+  return { requestId: requestId2, error: void 0, result };
 }
-function errorResponse(requestId, code, message, retryable) {
+function errorResponse(requestId2, code, message, retryable) {
   const error = { code, message, retryable, detail: {} };
-  return { requestId, error, result: void 0 };
+  return { requestId: requestId2, error, result: void 0 };
 }
 function normalize(path) {
   const trimmed = path.replace(/\/+$/, "");
@@ -20488,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;
@@ -20500,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;
@@ -20518,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
@@ -20533,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");
         }
@@ -20584,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
@@ -20608,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`);
   }
@@ -20664,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);
       }
@@ -20676,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);
         }
@@ -20691,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");
       }
@@ -20713,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");
       }
@@ -20721,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");
       }
@@ -20729,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");
       }
@@ -20737,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");
       }
@@ -20745,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");
       }
@@ -20771,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");
@@ -20791,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");
       }
@@ -20801,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;
       }
@@ -20853,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) {
@@ -21035,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"
@@ -21119,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 ?? {};
@@ -21189,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 {
@@ -21218,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 {
@@ -21276,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;
@@ -21362,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,
@@ -21429,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,
@@ -21437,6 +23752,9 @@ export {
   mintStreamToken,
   verifyStreamToken,
   StreamTokenPayload2 as StreamTokenPayload,
+  parseExecBannerSessionId,
+  parseExecBannerExitCode,
+  isExecSessionLostBanner,
   STREAM_PORT,
   DISPLAY_STACK_TIMEOUT_MS,
   DEFAULT_DESKTOP_GEOMETRY,
@@ -21481,6 +23799,9 @@ export {
   uploadRecordingArtifact,
   deleteRecordingArtifacts,
   recordingStorageKey,
+  TurnSandboxCommandCancelledError,
+  createTurnToolCancellationController,
+  wrapCapabilityToolsForTurnCancellation,
   ChannelAValidationError,
   ChannelAUnavailableError,
   ChannelAConflictError,
@@ -21489,9 +23810,6 @@ export {
   REPOSITORY_DISCOVERY_LIMIT,
   SandboxChannelAService,
   stripExecBanner2 as stripExecBanner,
-  isExecSessionLostBanner,
-  parseExecBannerSessionId,
-  parseExecBannerExitCode,
   assertSafeRelPath,
   parsePorcelainV2,
   parseNumstatZ,
@@ -21501,6 +23819,9 @@ export {
   negotiateSelfhostedCapabilities,
   MockAgentResponder,
   RoutingUnsupportedError,
+  RoutingBackendRecoveryRequiredError,
+  RoutingMutationOutcomeUnknownError,
+  RoutingRetainedProcessNotFoundError,
   RoutingSandboxSession,
   ActiveBackendUnresolvableError,
   swapTargetEstablishability,
@@ -21513,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-YUAFQEFY.js.map
+//# sourceMappingURL=chunk-JGUQSAG5.js.map