@opengeni/runtime 0.6.1 → 0.7.0

package/dist/{chunk-DYBF7ZEB.js → chunk-RYDCVTMW.js}

@@ -1,6 +1,9 @@
 // src/sandbox/index.ts
 import { collectSandboxEnvironment, parseExposedPorts } from "@opengeni/config";
-import { DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT7, TERMINAL_STREAM_PORT as TERMINAL_STREAM_PORT2 } from "@opengeni/contracts";
+import {
+  DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT7,
+  TERMINAL_STREAM_PORT as TERMINAL_STREAM_PORT2
+} from "@opengeni/contracts";
 
 // src/sandbox/providers/index.ts
 import { SandboxBackend as SandboxBackend2 } from "@opengeni/contracts";
@@ -52,6 +55,14 @@ var SandboxConfigError = class extends Error {
     this.backend = backend;
   }
 };
+var SandboxResumeStateUnavailableError = class extends Error {
+  backend;
+  constructor(backend) {
+    super(`Sandbox lease for backend "${backend}" has no resumable provider identity`);
+    this.name = "SandboxResumeStateUnavailableError";
+    this.backend = backend;
+  }
+};
 var SandboxProviderUnavailableError = class extends Error {
   backend;
   constructor(backend) {
@@ -203,7 +214,7 @@ var localProvider = {
 import { ModalImageSelector, ModalSandboxClient } from "@openai/agents-extensions/sandbox/modal";
 import { effectiveModalIdleTimeoutSeconds } from "@opengeni/config";
 var MODAL_ORPHAN_SWEEP_LIMIT = 50;
-var MODAL_UNATTRIBUTED_ORPHAN_GRACE_MS = 30 * 6e4;
+var MODAL_UNATTRIBUTED_ORPHAN_GRACE_MS = 2 * 6e4;
 function modalSandboxAttributionEnvironment(input) {
   return {
     OPENGENI_SANDBOX_LEASE_ID: input.leaseId,
@@ -240,10 +251,11 @@ var modalProvider = {
       sandboxCreateTimeoutS: Math.ceil(settings.sandboxWarmingTimeoutMs / 1e3),
       exposedPorts,
       env: environment,
-      // The Modal JS SDK's sandbox default command already sleeps until timeout
-      // or explicit termination. Do not let the Agents extension stamp a separate
-      // hardcoded sleep command; OPENGENI_MODAL_TIMEOUT_SECONDS owns lifetime.
-      useSleepCmd: false
+      // A registry image's own CMD is not a sandbox keepalive contract (for
+      // example, python:3.12-slim can exit immediately). Keep the provider's
+      // control process alive so exec/resume remains available; Modal's hard
+      // timeout and explicit OpenGeni teardown still own the box lifetime.
+      useSleepCmd: true
     };
     options.idleTimeoutMs = effectiveModalIdleTimeoutSeconds(settings) * 1e3;
     if (settings.modalWorkspacePersistence) {
@@ -312,7 +324,9 @@ function resolveModalImageSelector(settings) {
     return void 0;
   }
   const registryImage = cachedModalRegistryImage(settings);
-  return registryImage ? ModalImageSelector.fromImage(registryImage) : ModalImageSelector.fromTag(settings.modalImageRef);
+  return registryImage ? ModalImageSelector.fromImage(
+    registryImage
+  ) : ModalImageSelector.fromTag(settings.modalImageRef);
 }
 function modalClientOptions(settings) {
   return {
@@ -375,6 +389,9 @@ async function sweepModalOrphanSandboxes(settings, liveLeases, options = {}) {
   const maxTerminations = options.maxTerminations ?? MODAL_ORPHAN_SWEEP_LIMIT;
   const unattributedGraceMs = options.unattributedGraceMs ?? MODAL_UNATTRIBUTED_ORPHAN_GRACE_MS;
   const liveByAttribution = new Map(liveLeases.map((lease) => [attributionKey(lease), lease]));
+  const liveByInstanceId = new Map(
+    liveLeases.filter((lease) => lease.instanceId).map((lease) => [lease.instanceId, lease])
+  );
   const ownedClient = options.client ? null : await createModalClient(settings);
   const modal = options.client ?? ownedClient;
   try {
@@ -408,9 +425,29 @@ async function sweepModalOrphanSandboxes(settings, liveLeases, options = {}) {
         const leaseId = tags.opengeni_lease_id;
         const workspaceId = tags.opengeni_workspace_id;
         const sandboxGroupId = tags.opengeni_sandbox_group_id;
+        const liveByInstance = info.id ? liveByInstanceId.get(info.id) : void 0;
+        if (liveByInstance) {
+          if (leaseId !== liveByInstance.leaseId || workspaceId !== liveByInstance.workspaceId || sandboxGroupId !== liveByInstance.sandboxGroupId) {
+            try {
+              const sandbox = await modal.sandboxes.fromId(info.id);
+              await sandbox.setTags(
+                modalSandboxAttributionTags({
+                  leaseId: liveByInstance.leaseId,
+                  workspaceId: liveByInstance.workspaceId,
+                  sandboxGroupId: liveByInstance.sandboxGroupId
+                })
+              );
+            } catch {
+            }
+          }
+          skipped += 1;
+          continue;
+        }
         let reason = null;
         if (leaseId && workspaceId && sandboxGroupId) {
-          const live = liveByAttribution.get(attributionKey({ leaseId, workspaceId, sandboxGroupId }));
+          const live = liveByAttribution.get(
+            attributionKey({ leaseId, workspaceId, sandboxGroupId })
+          );
           if (!live || live.instanceId && live.instanceId !== info.id) {
             reason = "stale_attribution";
           }
@@ -488,11 +525,7 @@ var runloopProvider = {
 };
 
 // src/sandbox/selfhosted/control-rpc.ts
-import {
-  ControlRequest,
-  ControlResponse,
-  ErrorCode
-} from "@opengeni/agent-proto";
+import { ControlRequest, ControlResponse, ErrorCode } from "@opengeni/agent-proto";
 function subjectFor(workspaceId, agentId) {
   return `agent.${workspaceId}.${agentId}.rpc`;
 }
@@ -505,6 +538,15 @@ var SelfhostedControlError = class extends Error {
   draining;
   agentOffline;
   osNotFound;
+  /** The reply exceeded the transport's max payload (a distinguishing flag so the
+   *  fault renderer can name the size wall + recovery instead of a generic OS error). */
+  payloadTooLarge;
+  /** The transport synthesized this fault PRE-SEND — it KNOWS the request never
+   *  reached the machine (no connection, or no responder on the subject), so the op
+   *  provably did not execute. Only such a fault is safe to re-issue for ANY op kind
+   *  (a post-send timeout is ambiguous — at-least-once — and must not be re-sent
+   *  unless the op is read-only). Never set for an agent-returned error. */
+  neverSent;
   detail;
   constructor(input) {
     super(input.message);
@@ -515,6 +557,8 @@ var SelfhostedControlError = class extends Error {
     this.draining = input.draining ?? false;
     this.agentOffline = input.agentOffline ?? false;
     this.osNotFound = input.osNotFound ?? false;
+    this.payloadTooLarge = input.payloadTooLarge ?? false;
+    this.neverSent = input.neverSent ?? false;
     this.detail = input.detail ?? {};
   }
 };
@@ -529,6 +573,7 @@ function agentErrorToControlError(err) {
         reason: "agent_offline",
         retryable: false,
         agentOffline: true,
+        neverSent: detail[NEVER_SENT_DETAIL_KEY] === "1",
         detail
       });
     case ErrorCode.ERROR_CODE_TIMEOUT:
@@ -549,13 +594,22 @@ function agentErrorToControlError(err) {
       });
     case ErrorCode.ERROR_CODE_DRAINING:
       return new SelfhostedControlError({
-        message: message || "the agent is draining and cannot accept new work",
+        message: drainingMessage(0),
         code: err.code,
         reason: null,
         retryable: true,
         draining: true,
         detail
       });
+    case ErrorCode.ERROR_CODE_PAYLOAD_TOO_LARGE:
+      return new SelfhostedControlError({
+        message: payloadTooLargeMessage(detail),
+        code: err.code,
+        reason: null,
+        retryable: false,
+        payloadTooLarge: true,
+        detail
+      });
     case ErrorCode.ERROR_CODE_FENCED:
       return new SelfhostedControlError({
         message: message || "a stale op was fenced by the epoch guard; re-resolve and retry",
@@ -584,12 +638,37 @@ function agentErrorToControlError(err) {
       });
   }
 }
-function offlineAgentError(message = "no agent responded (offline)") {
+function payloadTooLargeMessage(detail) {
+  const encoded = detail.encoded_bytes;
+  const max = detail.max_payload;
+  const sizes = encoded && max ? `The result was ${encoded} bytes, over the machine link's ${max}-byte per-message limit. ` : "The result was larger than the machine link can deliver in a single message. ";
+  return `${sizes}Redirect the command's output to a file (for example \`<command> > /tmp/out.log 2>&1\`) and then read that file back in ranges or chunks instead of returning it all at once.`;
+}
+function drainingMessage(retries) {
+  const retried = retries > 0 ? ` It was retried ${retries} time${retries === 1 ? "" : "s"} first.` : "";
+  return "The machine is at its concurrent-work capacity and could not accept this command." + retried + " Try again shortly, or reduce the number of commands you run in parallel.";
+}
+function drainingExhaustedError(base, retries) {
+  return new SelfhostedControlError({
+    message: drainingMessage(retries),
+    code: base.code,
+    reason: base.reason,
+    retryable: base.retryable,
+    draining: base.draining,
+    // Carry the retry count in `detail` so the fault renderer can state it.
+    detail: { ...base.detail, retries: String(retries) }
+  });
+}
+function execDeadlineHint(seconds) {
+  return `The command was terminated at the ${seconds}-second execution limit. Run long jobs in the background (for example \`nohup <command> > /tmp/job.log 2>&1 &\`, or start them in a terminal session) and poll the output file instead of blocking on a single command.`;
+}
+var NEVER_SENT_DETAIL_KEY = "_never_sent";
+function offlineAgentError(message = "no agent responded (offline)", neverSent = false) {
   return {
     code: ErrorCode.ERROR_CODE_AGENT_OFFLINE,
     message,
     retryable: false,
-    detail: {}
+    detail: neverSent ? { [NEVER_SENT_DETAIL_KEY]: "1" } : {}
   };
 }
 function timeoutAgentError(message = "the agent did not respond in time") {
@@ -620,24 +699,28 @@ function isRequestTimeoutError(err) {
 var NatsControlRpc = class {
   connect;
   connection;
+  connecting;
   constructor(connect) {
     this.connect = connect;
   }
   async resolveConnection() {
-    if (this.connection === void 0) {
-      try {
-        this.connection = await this.connect();
-      } catch {
-        this.connection = null;
-        return null;
-      }
+    if (this.connection) {
+      return this.connection;
     }
-    return this.connection ?? null;
+    this.connecting ??= this.connect().then((connection) => {
+      if (connection) {
+        this.connection = connection;
+      }
+      return connection;
+    }).catch(() => null).finally(() => {
+      this.connecting = void 0;
+    });
+    return this.connecting;
   }
   async request(subject, req, opts) {
     const conn = await this.resolveConnection();
     if (!conn) {
-      return offlineControlResponse(req.requestId);
+      return offlineControlResponse(req.requestId, true);
     }
     const payload = ControlRequest.encode(req).finish();
     try {
@@ -645,7 +728,7 @@ var NatsControlRpc = class {
       return ControlResponse.decode(reply.data);
     } catch (err) {
       if (isNoRespondersError(err)) {
-        return offlineControlResponse(req.requestId);
+        return offlineControlResponse(req.requestId, true);
       }
       if (isRequestTimeoutError(err)) {
         return timeoutControlResponse(req.requestId);
@@ -655,8 +738,8 @@ var NatsControlRpc = class {
     }
   }
 };
-function offlineControlResponse(requestId) {
-  return { requestId, error: offlineAgentError(), result: void 0 };
+function offlineControlResponse(requestId, neverSent = false) {
+  return { requestId, error: offlineAgentError(void 0, neverSent), result: void 0 };
 }
 function timeoutControlResponse(requestId) {
   return { requestId, error: timeoutAgentError(), result: void 0 };
@@ -664,11 +747,841 @@ function timeoutControlResponse(requestId) {
 
 // src/sandbox/selfhosted/session.ts
 import {
+  ErrorCode as ErrorCode4,
   FsEntryKind,
   StreamKind
 } from "@opengeni/agent-proto";
 import { DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT2 } from "@opengeni/contracts";
 import { Manifest } from "@openai/agents/sandbox";
+
+// src/sandbox/selfhosted/retry-policy.ts
+var SELFHOSTED_IDEMPOTENT_READONLY_OPS = /* @__PURE__ */ new Set([
+  "ping",
+  "metrics",
+  "fsStat",
+  "fsList",
+  "fsRead"
+]);
+var SELFHOSTED_DRAINING_MAX_RETRIES = 3;
+var SELFHOSTED_EXEC_DRAINING_MAX_RETRIES = 10;
+var SELFHOSTED_TIMEOUT_MAX_RETRIES = 1;
+var SELFHOSTED_NEVER_SENT_MAX_RETRIES = 3;
+var SELFHOSTED_RETRY_BACKOFF_BASE_MS = 500;
+var SELFHOSTED_RETRY_BACKOFF_FACTOR = 2;
+var SELFHOSTED_RETRY_BACKOFF_CAP_MS = 8e3;
+function selfhostedRetryBackoffMs(attempt, jitter) {
+  const uncapped = SELFHOSTED_RETRY_BACKOFF_BASE_MS * SELFHOSTED_RETRY_BACKOFF_FACTOR ** attempt;
+  const ceiling = Math.min(SELFHOSTED_RETRY_BACKOFF_CAP_MS, uncapped);
+  const clampedJitter = Math.min(0.999999, Math.max(0, jitter));
+  return Math.floor(clampedJitter * ceiling);
+}
+function decideSelfhostedRetry(input) {
+  const { opKind, error, drainingRetries, timeoutRetries, neverSentRetries = 0, jitter } = input;
+  if (error.neverSent) {
+    if (neverSentRetries >= SELFHOSTED_NEVER_SENT_MAX_RETRIES) {
+      return { action: "fail" };
+    }
+    return { action: "retry", delayMs: selfhostedRetryBackoffMs(neverSentRetries, jitter) };
+  }
+  if (error.draining) {
+    const maxDrainingRetries = opKind === "exec" ? SELFHOSTED_EXEC_DRAINING_MAX_RETRIES : SELFHOSTED_DRAINING_MAX_RETRIES;
+    if (drainingRetries >= maxDrainingRetries) {
+      return { action: "fail" };
+    }
+    return { action: "retry", delayMs: selfhostedRetryBackoffMs(drainingRetries, jitter) };
+  }
+  if (error.reason === "agent_reconnecting") {
+    if (!SELFHOSTED_IDEMPOTENT_READONLY_OPS.has(opKind)) {
+      return { action: "fail" };
+    }
+    if (timeoutRetries >= SELFHOSTED_TIMEOUT_MAX_RETRIES) {
+      return { action: "fail" };
+    }
+    return { action: "retry", delayMs: selfhostedRetryBackoffMs(timeoutRetries, jitter) };
+  }
+  return { action: "fail" };
+}
+var defaultSelfhostedRetryClock = {
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  jitter: () => Math.random()
+};
+
+// src/sandbox/selfhosted/fault-rendering.ts
+import { errorCodeToJSON, ErrorCode as ErrorCode2 } from "@opengeni/agent-proto";
+function selfhostedFaultClass(error) {
+  if (error.agentOffline || error.code === ErrorCode2.ERROR_CODE_AGENT_OFFLINE) return "offline";
+  if (error.draining) return "draining";
+  if (error.payloadTooLarge || error.code === ErrorCode2.ERROR_CODE_PAYLOAD_TOO_LARGE)
+    return "payload_too_large";
+  if (error.reason === "agent_reconnecting") return "reconnecting";
+  if (error.reason === "consent_required") return "consent";
+  if (error.osNotFound || error.code === ErrorCode2.ERROR_CODE_NOT_FOUND) return "not_found";
+  if (error.fenced || error.code === ErrorCode2.ERROR_CODE_FENCED) return "fenced";
+  switch (error.code) {
+    case ErrorCode2.ERROR_CODE_OS:
+      return "os";
+    case ErrorCode2.ERROR_CODE_STREAM:
+      return "stream";
+    case ErrorCode2.ERROR_CODE_PROTOCOL:
+      return "protocol";
+    default:
+      return "unspecified";
+  }
+}
+var SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES = /* @__PURE__ */ new Set([
+  "offline",
+  "draining",
+  "payload_too_large",
+  "reconnecting",
+  "os",
+  "stream",
+  "protocol"
+]);
+var FAULT_FIELD_WHAT_HAPPENED = "What happened:";
+var FAULT_FIELD_WHICH_LAYER = "Which layer:";
+var FAULT_FIELD_WHAT_PRESERVED = "What was preserved:";
+var FAULT_FIELD_WHAT_TO_TRY = "What to try:";
+function assemble(error, f) {
+  const code = errorCodeToJSON(error.code);
+  return [
+    `[connected machine] ${f.headline}`,
+    `${FAULT_FIELD_WHAT_HAPPENED} ${f.happened} (control code ${code}).`,
+    `${FAULT_FIELD_WHICH_LAYER} ${f.layer}`,
+    `${FAULT_FIELD_WHAT_PRESERVED} ${f.preserved}`,
+    `${FAULT_FIELD_WHAT_TO_TRY} ${f.tryNext}`
+  ].join("\n");
+}
+function renderSelfhostedFault(error) {
+  const detail = error.detail;
+  if (error.payloadTooLarge || error.code === ErrorCode2.ERROR_CODE_PAYLOAD_TOO_LARGE) {
+    if (detail.failure_code === "OP_OVERFLOW") {
+      const retained = detail.retained_bytes ? `after retaining ${detail.retained_bytes} bytes of output` : "when its output exceeded what the machine can retain for delivery";
+      return assemble(error, {
+        headline: "the command produced more output than the machine link can deliver",
+        happened: `the machine stopped the command ${retained} \u2014 its output-retention ceiling was reached`,
+        layer: "the machine link's output-retention ceiling \u2014 the command was terminated at the ceiling, not by its own logic",
+        preserved: "no output was returned, and the command did NOT run to completion \u2014 any side effects up to the stop point may have applied.",
+        tryNext: "re-run with the output bounded: redirect to a file (`> /tmp/out.log 2>&1`) then read it back in ranges/chunks, or slice it with `head -c` / `tail -c` / `head` / `tail`."
+      });
+    }
+    const sizes = detail.encoded_bytes && detail.max_payload ? `its ${detail.encoded_bytes}-byte reply exceeded the machine link's ${detail.max_payload}-byte per-message limit` : "its reply was larger than the machine link can deliver in one message";
+    return assemble(error, {
+      headline: "the command's output was too large to return",
+      happened: `the command ran on the machine, but ${sizes}`,
+      layer: "the machine link's per-message size limit \u2014 the command itself executed",
+      preserved: "nothing was returned; the oversized reply was dropped whole.",
+      tryNext: "re-run with the output bounded: redirect to a file (`> /tmp/out.log 2>&1`) then read it back in ranges/chunks, or slice it with `head -c` / `tail -c` / `head` / `tail`."
+    });
+  }
+  if (error.draining) {
+    const retried = detail.retries ? ` after ${detail.retries} retries` : "";
+    return assemble(error, {
+      headline: "the machine is at its concurrent-work capacity",
+      happened: `the machine rejected this command at its admission gate${retried} because its work pool is full`,
+      layer: "the machine's host-work admission \u2014 the machine is online, just saturated",
+      preserved: "nothing ran; the command was rejected before it started.",
+      tryNext: "try again shortly, or reduce the number of commands you run in parallel."
+    });
+  }
+  if (error.reason === "consent_required") {
+    return assemble(error, {
+      headline: "the operation needs consent that has not been granted",
+      happened: "the machine rejected the operation because the required consent is not granted",
+      layer: "the machine's consent gate \u2014 not your command",
+      preserved: "nothing ran; the operation was rejected.",
+      tryNext: "the consent must be granted on the machine itself; retrying will keep failing until it is."
+    });
+  }
+  if (error.agentOffline || error.code === ErrorCode2.ERROR_CODE_AGENT_OFFLINE) {
+    const preserved = error.neverSent ? "nothing ran; the command never reached the machine." : "unknown \u2014 the link dropped and the command may or may not have run.";
+    const tryNext = error.neverSent ? "the machine appears offline; check that it is powered on and connected. Retrying will not help until it reconnects." : "check the machine, and check whether the command already took effect before re-running it.";
+    return assemble(error, {
+      headline: "the machine is unreachable",
+      happened: "the enrolled machine did not respond; it appears offline",
+      layer: "the machine link \u2014 the machine itself, not your command",
+      preserved,
+      tryNext
+    });
+  }
+  if (error.reason === "agent_reconnecting") {
+    return assemble(error, {
+      headline: "the machine link blipped",
+      happened: "the machine did not respond in time; the link may be reconnecting",
+      layer: "the machine link (transport) \u2014 not your command",
+      preserved: "unknown \u2014 the command may or may not have run (its reply was lost).",
+      tryNext: "wait a moment and try again; if this was a state-changing command, check whether it already took effect before re-running it."
+    });
+  }
+  if (error.osNotFound || error.code === ErrorCode2.ERROR_CODE_NOT_FOUND) {
+    return assemble(error, {
+      headline: "the path or reference was not found on the machine",
+      happened: `the machine reported: ${error.message}`,
+      layer: "the command / filesystem on the machine \u2014 not the machine link",
+      preserved: "not applicable; the operation did not apply.",
+      tryNext: "check the path or reference exists on the machine, then re-run."
+    });
+  }
+  if (error.fenced || error.code === ErrorCode2.ERROR_CODE_FENCED) {
+    return assemble(error, {
+      headline: "the active machine session changed",
+      happened: "the machine session was swapped underneath the command",
+      layer: "the session-routing layer \u2014 not your command",
+      preserved: "nothing ran on this session.",
+      tryNext: "re-run the command; it will target the machine's current session."
+    });
+  }
+  return assemble(error, {
+    headline: "the command failed on the machine",
+    happened: `the machine reported: ${error.message}`,
+    layer: "the command / operating system on the machine",
+    preserved: "not applicable; the command did not complete successfully.",
+    tryNext: "read the message above and adjust the command; a blind retry is unlikely to help."
+  });
+}
+
+// src/sandbox/op-correlation.ts
+import { AsyncLocalStorage } from "async_hooks";
+var storage = new AsyncLocalStorage();
+function sanitizeOpIdToken(raw) {
+  return raw.replace(/[^A-Za-z0-9_-]/g, (c) => `_${c.charCodeAt(0).toString(16)}_`);
+}
+function runWithToolCallCorrelation(callId, fn) {
+  return storage.run({ callId: sanitizeOpIdToken(callId), ordinal: 0 }, fn);
+}
+function nextDurableOpId() {
+  const context = storage.getStore();
+  if (!context) {
+    return null;
+  }
+  const ordinal = context.ordinal;
+  context.ordinal += 1;
+  return `${context.callId}:${ordinal}`;
+}
+
+// src/sandbox/selfhosted/op-stream.ts
+import { blake3 } from "@noble/hashes/blake3";
+import { bytesToHex } from "@noble/hashes/utils";
+import {
+  ErrorCode as ErrorCode3,
+  OpAck,
+  OpChannel,
+  OpFrame,
+  OpLostReason,
+  OpState
+} from "@opengeni/agent-proto";
+
+// src/sandbox/selfhosted/op-transport.ts
+function opFrameSubject(workspaceId, agentId, opId) {
+  return `agent.${workspaceId}.${agentId}.op.${opId}`;
+}
+function opAckSubject(workspaceId, agentId) {
+  return `agent.${workspaceId}.${agentId}.ack`;
+}
+var OpStreamUnavailableError = class extends Error {
+  name = "OpStreamUnavailableError";
+};
+var NatsOpStreamTransport = class {
+  connect;
+  connection;
+  connecting;
+  constructor(connect) {
+    this.connect = connect;
+  }
+  async resolveConnection() {
+    if (this.connection) {
+      return this.connection;
+    }
+    this.connecting ??= this.connect().then((connection) => {
+      if (connection) {
+        this.connection = connection;
+      }
+      return connection;
+    }).catch(() => null).finally(() => {
+      this.connecting = void 0;
+    });
+    return this.connecting;
+  }
+  async subscribe(subject, onMessage) {
+    const conn = await this.resolveConnection();
+    if (!conn) {
+      throw new OpStreamUnavailableError("op-stream transport has no live connection");
+    }
+    const subscription = conn.subscribe(subject);
+    void (async () => {
+      try {
+        for await (const message of subscription) {
+          onMessage(message.data);
+        }
+      } catch {
+      }
+    })();
+    let unsubscribed = false;
+    return {
+      unsubscribe: () => {
+        if (unsubscribed) {
+          return;
+        }
+        unsubscribed = true;
+        try {
+          subscription.unsubscribe();
+        } catch {
+        }
+      }
+    };
+  }
+  async publish(subject, payload) {
+    const conn = await this.resolveConnection();
+    if (!conn) {
+      throw new OpStreamUnavailableError("op-stream transport has no live connection");
+    }
+    conn.publish(subject, payload);
+  }
+};
+
+// src/sandbox/selfhosted/op-stream.ts
+var OP_STREAM_DEFAULT_WINDOW_BYTES = 4 * 1024 * 1024;
+var OP_STREAM_ACK_INTERVAL_MS = 5e3;
+var OP_STREAM_SILENCE_TIMEOUT_MS = 3e4;
+var OP_STREAM_RECONNECT_HOLD_MS = 12e4;
+var OP_STREAM_MAX_STASHED_FRAMES = 4096;
+var OP_START_DRAINING_MAX_RETRIES = 10;
+var OP_START_BLIP_MAX_RETRIES = 3;
+var OP_CHANNEL_NAMES = {
+  [OpChannel.OP_CHANNEL_STDOUT]: "stdout",
+  [OpChannel.OP_CHANNEL_STDERR]: "stderr"
+};
+var OpStreamExecClient = class {
+  deps;
+  settled = [];
+  inFlight = /* @__PURE__ */ new Set();
+  constructor(deps) {
+    this.deps = deps;
+  }
+  generation() {
+    return this.deps.journal?.attachGeneration() ?? "1";
+  }
+  /**
+   * Run one exec over the op stream. `opId` is the durable id (B1) — a re-issue
+   * with the same id attaches instead of re-running. `deadlineMs` is the exec
+   * process budget (relative); the runner's enforcement is authoritative.
+   * `wallMs` is the client-side give-up wall (deadline + reply grace).
+   */
+  async exec(opId, exec, deadlineMs, wallMs) {
+    if (this.inFlight.has(opId)) {
+      throw new SelfhostedControlError({
+        message: `op-stream exec: duplicate concurrent op id ${opId}`,
+        code: ErrorCode3.ERROR_CODE_PROTOCOL,
+        reason: null,
+        retryable: false
+      });
+    }
+    this.inFlight.add(opId);
+    try {
+      const consumer = new OpConsumer(this.deps, opId, this.generation());
+      try {
+        const outcome = await consumer.run(exec, deadlineMs, wallMs);
+        this.settled.push({ opId, exitSeq: outcome.exitSeq, generation: consumer.generation });
+        return outcome.outcome;
+      } finally {
+        consumer.teardown();
+      }
+    } finally {
+      this.inFlight.delete(opId);
+    }
+  }
+  /**
+   * The turn-end durability hook (the hard gate's ordering): for every op whose
+   * result the turn has durably consumed — (1) already true when this runs —
+   * (2) persist the settled frontier to the journal, then (3) publish the wire
+   * final ack (`acked_seq = exit_seq, final = true`), which licenses the runner
+   * to GC the op. A kill between (2) and (3) is safe: the re-dispatched turn
+   * does not re-execute a durably-recorded call, and the runner's retention TTL
+   * reaps the never-final-acked op — no loss, bounded residue. Publish failures
+   * are swallowed for the same reason.
+   */
+  async finalizeSettledOps() {
+    const ackSubject = opAckSubject(this.deps.workspaceId, this.deps.agentId);
+    while (this.settled.length > 0) {
+      const op = this.settled.shift();
+      await this.deps.journal?.persistSettled(op.opId, op.exitSeq);
+      const ack = OpAck.encode({
+        opId: op.opId,
+        ackedSeq: op.exitSeq,
+        creditBytes: "0",
+        final: true,
+        attachGeneration: op.generation
+      }).finish();
+      try {
+        await this.deps.transport.publish(ackSubject, ack);
+      } catch {
+      }
+    }
+  }
+};
+var OpConsumer = class {
+  deps;
+  opId;
+  generation;
+  windowBytes;
+  /** Highest contiguously APPLIED seq (frames start at 1; 0 = none yet). */
+  lastApplied = 0n;
+  stash = /* @__PURE__ */ new Map();
+  chunks = {
+    stdout: [],
+    stderr: []
+  };
+  receivedPayloadBytes = 0n;
+  creditAtLastAck = 0n;
+  exit;
+  exitSeq;
+  heals = 0;
+  lastFrameAt;
+  silenceSince;
+  attachInFlight = false;
+  subscription;
+  ackTimer;
+  settleResolve;
+  settleReject;
+  torn = false;
+  constructor(deps, opId, generation) {
+    this.deps = deps;
+    this.opId = opId;
+    this.generation = generation;
+    this.windowBytes = deps.windowBytes ?? OP_STREAM_DEFAULT_WINDOW_BYTES;
+    this.lastFrameAt = Date.now();
+  }
+  get ackIntervalMs() {
+    return this.deps.ackIntervalMs ?? OP_STREAM_ACK_INTERVAL_MS;
+  }
+  get silenceTimeoutMs() {
+    return this.deps.silenceTimeoutMs ?? OP_STREAM_SILENCE_TIMEOUT_MS;
+  }
+  get reconnectHoldMs() {
+    return this.deps.reconnectHoldMs ?? OP_STREAM_RECONNECT_HOLD_MS;
+  }
+  teardown() {
+    this.torn = true;
+    if (this.ackTimer) {
+      clearInterval(this.ackTimer);
+      this.ackTimer = void 0;
+    }
+    this.subscription?.unsubscribe();
+    this.subscription = void 0;
+  }
+  async run(exec, deadlineMs, wallMs) {
+    const settled = new Promise((resolve, reject) => {
+      this.settleResolve = resolve;
+      this.settleReject = reject;
+    });
+    this.subscription = await this.deps.transport.subscribe(
+      opFrameSubject(this.deps.workspaceId, this.deps.agentId, this.opId),
+      (payload) => this.onFramePayload(payload)
+    );
+    const startRetries = await this.startOp(exec, deadlineMs);
+    await this.attach(this.windowBytes);
+    this.ackTimer = setInterval(() => {
+      void this.sendAck();
+    }, this.ackIntervalMs);
+    const liveness = this.watchLiveness(wallMs);
+    try {
+      await Promise.race([settled, liveness.wall]);
+    } finally {
+      liveness.stop();
+    }
+    const exit = this.exit;
+    const exitSeq = this.exitSeq;
+    this.verifyByteExact(exit);
+    if (exit.failureCode) {
+      throw runnerFailureToControlError(exit);
+    }
+    const stdout = concatChunks(this.chunks.stdout);
+    const stderr = concatChunks(this.chunks.stderr);
+    return {
+      outcome: {
+        response: {
+          exitCode: exit.exitCode,
+          stdout,
+          stderr,
+          timedOut: exit.timedOut,
+          durationMs: exit.durationMs
+        },
+        heals: this.heals,
+        startRetries,
+        replyBytes: stdout.byteLength + stderr.byteLength
+      },
+      exitSeq: exitSeq.toString()
+    };
+  }
+  /** OpStart with the patient DRAINING budget and a small blip budget. OpStart
+   *  is IDEMPOTENT BY OP ID (the request id), so a timed-out/never-sent start
+   *  is safe to re-issue even though exec mutates — the runner either never saw
+   *  it or answers the SAME op. The stable request id is what makes that true. */
+  async startOp(exec, deadlineMs) {
+    let drainingRetries = 0;
+    let blipRetries = 0;
+    for (; ; ) {
+      try {
+        const result = await this.controlOp(
+          {
+            $case: "opStart",
+            opStart: {
+              op: { $case: "exec", exec },
+              windowBytes: String(this.windowBytes),
+              // Absolute epoch deadline (the runner's clock decides the actual
+              // budget; host clock skew shifts it — a known wire caveat).
+              deadlineMs: deadlineMs > 0 ? String(Date.now() + deadlineMs) : "0",
+              originId: this.deps.rpcSubject
+            }
+          },
+          this.opId
+        );
+        if (result.$case !== "opStart") {
+          throw protocolError(`op-stream start: unexpected result ${result.$case}`);
+        }
+        const status = result.opStart.status;
+        if (!result.opStart.accepted) {
+          throw this.refusedStart(status);
+        }
+        if (status?.state === OpState.OP_STATE_LOST) {
+          throw lostToControlError(status);
+        }
+        return drainingRetries + blipRetries;
+      } catch (error) {
+        if (!(error instanceof SelfhostedControlError)) {
+          throw error;
+        }
+        if (error.code === ErrorCode3.ERROR_CODE_PROTOCOL || error.code === ErrorCode3.ERROR_CODE_UNSUPPORTED) {
+          throw new OpStreamUnavailableError(
+            `the runner refused OpStart (${error.message}); falling back to the legacy exec`
+          );
+        }
+        const blip = error.reason === "agent_reconnecting" || error.neverSent;
+        if (error.draining && drainingRetries < OP_START_DRAINING_MAX_RETRIES) {
+          await this.deps.retryClock.sleep(
+            selfhostedRetryBackoffMs(drainingRetries, this.deps.retryClock.jitter())
+          );
+          drainingRetries += 1;
+          continue;
+        }
+        if (blip && blipRetries < OP_START_BLIP_MAX_RETRIES) {
+          await this.deps.retryClock.sleep(
+            selfhostedRetryBackoffMs(blipRetries, this.deps.retryClock.jitter())
+          );
+          blipRetries += 1;
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+  refusedStart(status) {
+    if (status?.state === OpState.OP_STATE_LOST) {
+      return lostToControlError(status);
+    }
+    return protocolError("op-stream start: the runner refused the op without a typed reason");
+  }
+  /** One control op on the rpc subject; throws the mapped
+   *  `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()) {
+    const res = await this.deps.controlRpc.request(
+      this.deps.rpcSubject,
+      { requestId, epoch: this.deps.epoch, op },
+      { timeoutMs: this.deps.controlTimeoutMs }
+    );
+    if (res.error || !res.result) {
+      throw agentErrorToControlError(
+        res.error ?? {
+          code: ErrorCode3.ERROR_CODE_PROTOCOL,
+          message: "agent returned an empty control response",
+          retryable: false,
+          detail: {}
+        }
+      );
+    }
+    return res.result;
+  }
+  /** OpAttach from the contiguous frontier. `windowBytes` sizes the fresh
+   *  replay window; 0 = reuse the OpStart grant (the gap-heal path). */
+  async attach(windowBytes) {
+    const result = await this.controlOp({
+      $case: "opAttach",
+      opAttach: {
+        opId: this.opId,
+        fromSeq: this.lastApplied.toString(),
+        attachGeneration: this.generation,
+        windowBytes: String(windowBytes)
+      }
+    });
+    if (result.$case !== "opStatus") {
+      throw protocolError(`op-stream attach: unexpected result ${result.$case}`);
+    }
+    if (result.opStatus.state === OpState.OP_STATE_LOST) {
+      throw lostToControlError(result.opStatus);
+    }
+    return result.opStatus;
+  }
+  /** Gap/silence heal: one re-attach in flight at a time; each success counts
+   *  as a heal (the observer's `healed` breadcrumb). Failures are left to the
+   *  liveness watcher — a dead link fails typed there, not here. */
+  requestAttachHeal() {
+    if (this.attachInFlight || this.torn) {
+      return;
+    }
+    this.attachInFlight = true;
+    void this.attach(0).then(() => {
+      this.heals += 1;
+    }).catch((error) => {
+      if (error instanceof SelfhostedControlError && !error.retryable && !error.agentOffline) {
+        this.settleReject?.(error);
+      }
+    }).finally(() => {
+      this.attachInFlight = false;
+    });
+  }
+  onFramePayload(payload) {
+    let frame;
+    try {
+      frame = OpFrame.decode(payload);
+    } catch {
+      return;
+    }
+    if (frame.opId !== this.opId) {
+      return;
+    }
+    this.lastFrameAt = Date.now();
+    this.silenceSince = void 0;
+    const seq = BigInt(frame.seq);
+    if (seq <= this.lastApplied) {
+      return;
+    }
+    if (seq !== this.lastApplied + 1n) {
+      if (this.stash.size < OP_STREAM_MAX_STASHED_FRAMES) {
+        this.stash.set(seq, frame);
+      }
+      this.requestAttachHeal();
+      return;
+    }
+    this.applyFrame(frame);
+    for (; ; ) {
+      const next = this.stash.get(this.lastApplied + 1n);
+      if (!next) {
+        break;
+      }
+      this.stash.delete(this.lastApplied + 1n);
+      this.applyFrame(next);
+    }
+    this.maybeSettle();
+    this.maybeGrantCredit();
+  }
+  applyFrame(frame) {
+    this.lastApplied = BigInt(frame.seq);
+    const body = frame.body;
+    if (!body) {
+      return;
+    }
+    switch (body.$case) {
+      case "data": {
+        const channel = OP_CHANNEL_NAMES[body.data.channel];
+        if (channel) {
+          this.chunks[channel].push(body.data.bytes);
+        }
+        this.receivedPayloadBytes += BigInt(body.data.bytes.byteLength);
+        break;
+      }
+      case "progress":
+        void this.sendAck();
+        break;
+      case "exit":
+        this.exit = body.exit;
+        this.exitSeq = BigInt(frame.seq);
+        break;
+    }
+  }
+  maybeSettle() {
+    if (this.exitSeq !== void 0 && this.lastApplied >= this.exitSeq) {
+      this.settleResolve?.();
+    }
+  }
+  /** Prompt credit replenishment: the periodic ack alone would stall a fast
+   *  child for up to the ack interval each window; grant as soon as half the
+   *  window has been consumed since the last grant. */
+  maybeGrantCredit() {
+    if (this.receivedPayloadBytes - this.creditAtLastAck >= BigInt(this.windowBytes) / 2n) {
+      void this.sendAck();
+    }
+  }
+  /** The mid-op cumulative ack: CREDIT-ONLY (Δ2 — acked_seq stays 0 so the
+   *  runner retains every frame for a possible successor consumer; the credit
+   *  is an absolute replacement sized to keep ~one window of live headroom). */
+  async sendAck() {
+    if (this.torn) {
+      return;
+    }
+    this.creditAtLastAck = this.receivedPayloadBytes;
+    const ack = OpAck.encode({
+      opId: this.opId,
+      ackedSeq: "0",
+      creditBytes: (this.receivedPayloadBytes + BigInt(this.windowBytes)).toString(),
+      final: false,
+      attachGeneration: this.generation
+    }).finish();
+    try {
+      await this.deps.transport.publish(
+        opAckSubject(this.deps.workspaceId, this.deps.agentId),
+        ack
+      );
+    } catch {
+    }
+  }
+  /**
+   * The liveness watcher: probes a silent op with OpQuery, re-attaches when the
+   * runner is ahead of us (frames lost in flight), holds a quiet-but-alive op
+   * open through the reconnect window, and enforces the client-side wall.
+   * Resolves only by rejection (typed failure) or by `stop()` at settle.
+   */
+  watchLiveness(wallMs) {
+    let stopped = false;
+    let timer;
+    const wall = new Promise((_, reject) => {
+      const startedAt = Date.now();
+      const tick = async () => {
+        if (stopped) {
+          return;
+        }
+        try {
+          if (Date.now() - startedAt >= wallMs) {
+            reject(agentErrorToControlError(timeoutAgentError()));
+            return;
+          }
+          if (Date.now() - this.lastFrameAt >= this.silenceTimeoutMs) {
+            await this.probeSilence(reject);
+          }
+        } catch (error) {
+          reject(error);
+          return;
+        }
+        timer = setTimeout(tick, Math.min(this.silenceTimeoutMs / 3, 2500));
+      };
+      timer = setTimeout(tick, Math.min(this.silenceTimeoutMs / 3, 2500));
+    });
+    return {
+      wall,
+      stop: () => {
+        stopped = true;
+        if (timer) {
+          clearTimeout(timer);
+        }
+      }
+    };
+  }
+  /** One silence probe: OpQuery the op; a definitive answer acts, an offline /
+   *  blip answer holds through the reconnect window, then fails typed. */
+  async probeSilence(reject) {
+    this.silenceSince ??= Date.now();
+    try {
+      const result = await this.controlOp({ $case: "opQuery", opQuery: { opId: this.opId } });
+      if (result.$case !== "opStatus") {
+        throw protocolError(`op-stream query: unexpected result ${result.$case}`);
+      }
+      const status = result.opStatus;
+      if (status.state === OpState.OP_STATE_LOST) {
+        reject(lostToControlError(status));
+        return;
+      }
+      if (BigInt(status.nextSeq) > this.lastApplied + 1n) {
+        this.requestAttachHeal();
+      }
+    } catch (error) {
+      if (!(error instanceof SelfhostedControlError)) {
+        throw error;
+      }
+      const transient = error.agentOffline || error.reason === "agent_reconnecting" || error.draining;
+      if (!transient) {
+        throw error;
+      }
+      const heldFor = Date.now() - (this.silenceSince ?? Date.now());
+      if (heldFor >= this.reconnectHoldMs) {
+        reject(error);
+      }
+    }
+  }
+  /** Byte-exactness proof: totals AND blake3 digests of the reassembled
+   *  channels must match the runner's Exit record exactly. */
+  verifyByteExact(exit) {
+    for (const channel of ["stdout", "stderr"]) {
+      const bytes = concatChunks(this.chunks[channel]);
+      const declaredTotal = exit.totals[channel];
+      if (declaredTotal !== void 0 && BigInt(declaredTotal) !== BigInt(bytes.byteLength)) {
+        throw protocolError(
+          `op-stream reassembly: ${channel} total mismatch (got ${bytes.byteLength}, runner declared ${declaredTotal})`
+        );
+      }
+      const declaredDigest = exit.digests[channel];
+      if (declaredDigest) {
+        const digest = bytesToHex(blake3(bytes));
+        if (digest !== declaredDigest) {
+          throw protocolError(
+            `op-stream reassembly: ${channel} digest mismatch (got ${digest}, runner declared ${declaredDigest})`
+          );
+        }
+      }
+    }
+  }
+};
+function concatChunks(chunks) {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+function protocolError(message) {
+  return new SelfhostedControlError({
+    message,
+    code: ErrorCode3.ERROR_CODE_PROTOCOL,
+    reason: null,
+    retryable: false
+  });
+}
+function lostToControlError(status) {
+  const reason = status.lostReason === OpLostReason.OP_LOST_REASON_EVICTED ? "its retained result was evicted before collection" : status.lostReason === OpLostReason.OP_LOST_REASON_AGENT_RESTARTED ? "the machine agent restarted and the op did not survive" : "the runner reported it lost";
+  return new SelfhostedControlError({
+    message: `The command's result is no longer available on the machine (${reason}). Check whether its effects already took place before re-running it.`,
+    code: ErrorCode3.ERROR_CODE_STREAM,
+    reason: null,
+    retryable: false,
+    detail: { lost_reason: String(status.lostReason) }
+  });
+}
+function runnerFailureToControlError(exit) {
+  if (exit.failureCode === "OP_OVERFLOW") {
+    return new SelfhostedControlError({
+      message: "The command produced more output than the machine link can retain for delivery. Redirect the command's output to a file (for example `<command> > /tmp/out.log 2>&1`) and then read that file back in ranges or chunks instead of returning it all at once.",
+      code: ErrorCode3.ERROR_CODE_PAYLOAD_TOO_LARGE,
+      reason: null,
+      retryable: false,
+      payloadTooLarge: true,
+      // failure_code lets the fault renderer distinguish the retention-ceiling
+      // overflow (command TERMINATED at the ceiling) from the legacy reply-size
+      // wall (command ran to completion) — the four fields must tell the truth.
+      detail: { ...exit.failureDetail, failure_code: exit.failureCode }
+    });
+  }
+  return new SelfhostedControlError({
+    message: `The command failed on the machine's streaming transport (${exit.failureCode}). The machine kept running it, but its output could not be captured intact.`,
+    code: ErrorCode3.ERROR_CODE_STREAM,
+    reason: null,
+    retryable: false,
+    detail: { ...exit.failureDetail, failure_code: exit.failureCode }
+  });
+}
+
+// src/sandbox/selfhosted/session.ts
 var decoder = new TextDecoder();
 var encoder = new TextEncoder();
 var SELFHOSTED_VIRTUAL_ROOT = "/workspace";
@@ -687,7 +1600,12 @@ function setSelfhostedApplyDiff(fn) {
   injectedApplyDiff = fn;
 }
 var SELFHOSTED_DEFAULT_TIMEOUT_MS = 3e4;
-var SELFHOSTED_EXEC_ENV_ALLOWLIST = ["OPENGENI_TOOLSPACE_URL", "OPENGENI_TOOLSPACE_TOKEN_FILE"];
+var SELFHOSTED_EXEC_REPLY_GRACE_MS = 5e3;
+var SELFHOSTED_MAX_EXEC_TIMEOUT_MS = 2147483647 - SELFHOSTED_EXEC_REPLY_GRACE_MS;
+var SELFHOSTED_EXEC_ENV_ALLOWLIST = [
+  "OPENGENI_TOOLSPACE_URL",
+  "OPENGENI_TOOLSPACE_TOKEN_FILE"
+];
 function selfhostedExecEnv(environment) {
   const env = {};
   for (const key of SELFHOSTED_EXEC_ENV_ALLOWLIST) {
@@ -707,7 +1625,14 @@ var SelfhostedSession = class {
   relay;
   epoch;
   timeoutMs;
+  /** The exec process deadline (falls back to `timeoutMs` when unset). */
+  execTimeoutMs;
+  retryClock;
+  onOp;
   subject;
+  /** The op-stream exec client — constructed iff `deps.opStream` was injected
+   *  (= the streaming transport is enabled for this session). */
+  opStreamClient;
   /** The session working directory — the path/cwd base every op is rooted under
    *  (see `toMachinePath`). "" by default ⇒ today's workspace_root behavior. */
   workingDir;
@@ -746,44 +1671,155 @@ var SelfhostedSession = class {
     this.relay = deps.relay;
     this.epoch = deps.epoch ?? 0;
     this.timeoutMs = deps.timeoutMs ?? SELFHOSTED_DEFAULT_TIMEOUT_MS;
+    this.execTimeoutMs = deps.execTimeoutMs;
+    this.retryClock = deps.retryClock ?? defaultSelfhostedRetryClock;
+    this.onOp = deps.onOp;
     this.subject = subjectFor(deps.workspaceId, deps.agentId);
     this.workingDir = deps.workingDir ?? "";
+    this.opStreamClient = deps.opStream ? new OpStreamExecClient({
+      workspaceId: deps.workspaceId,
+      agentId: deps.agentId,
+      epoch: this.epoch,
+      controlRpc: deps.controlRpc,
+      rpcSubject: this.subject,
+      transport: deps.opStream.transport,
+      controlTimeoutMs: this.timeoutMs,
+      retryClock: this.retryClock,
+      ...deps.opStream.journal !== void 0 ? { journal: deps.opStream.journal } : {},
+      ...deps.opStream.windowBytes !== void 0 ? { windowBytes: deps.opStream.windowBytes } : {},
+      ...deps.opStream.ackIntervalMs !== void 0 ? { ackIntervalMs: deps.opStream.ackIntervalMs } : {},
+      ...deps.opStream.silenceTimeoutMs !== void 0 ? { silenceTimeoutMs: deps.opStream.silenceTimeoutMs } : {},
+      ...deps.opStream.reconnectHoldMs !== void 0 ? { reconnectHoldMs: deps.opStream.reconnectHoldMs } : {}
+    }) : void 0;
     this.state = {
       agentId: deps.agentId,
       instanceId: deps.agentId,
-      manifest: new Manifest({ root: "/workspace", entries: {}, environment: deps.environment ?? {} }),
+      manifest: new Manifest({
+        root: "/workspace",
+        entries: {},
+        environment: deps.environment ?? {}
+      }),
       // The SDK `SandboxSessionState.environment` — the run's threaded env (or `{}`).
       // The group client's end-of-turn serialize reads `state.environment` directly
       // (Object.entries), so it must be a defined object, not absent.
       environment: deps.environment ?? {}
     };
   }
-  /** Issue a control op, decoding the agent's reply or throwing the mapped
-   *  `SelfhostedControlError` on an AgentError (incl. a synthesized offline /
-   *  timeout error from the transport). */
-  async call(op) {
-    const req = {
-      requestId: crypto.randomUUID(),
-      epoch: this.epoch,
-      op
-    };
-    const res = await this.controlRpc.request(this.subject, req, { timeoutMs: this.timeoutMs });
-    if (res.error) {
-      throw agentErrorToControlError(res.error);
+  /** Invoke the injected per-op observer, guarded: a telemetry tap must NEVER break
+   *  an op (a throwing sink is swallowed). No-op when no observer is wired. */
+  emitOp(observation) {
+    if (!this.onOp) {
+      return;
+    }
+    try {
+      this.onOp(observation);
+    } catch {
     }
-    if (!res.result) {
-      throw agentErrorToControlError({
+  }
+  /**
+   * Issue a control op, decoding the agent's reply or throwing the mapped
+   * `SelfhostedControlError` on an AgentError (incl. a synthesized offline /
+   * timeout error from the transport).
+   *
+   * Two failure modes are retried in-place (the decision is the pure
+   * `decideSelfhostedRetry` policy):
+   *   - DRAINING — a pre-admission host-work backpressure rejection; the op never
+   *     started, so it is safe to re-issue for ANY op kind (bounded).
+   *   - a TIMEOUT / `agent_reconnecting` blip — re-issued ONCE, and ONLY for a
+   *     read-only idempotent-safe op. A timed-out MUTATION is NEVER re-issued: it
+   *     may already have executed on the machine (at-least-once), which would
+   *     duplicate the write/command. FENCED is intentionally NOT retried here — the
+   *     routing proxy retries it against a re-resolved backend under a fresh epoch.
+   * Each attempt carries a FRESH `requestId` (a retry is a distinct request).
+   */
+  async call(op, timeoutMs = this.timeoutMs) {
+    const opKind = op.$case;
+    const startedAt = Date.now();
+    let drainingRetries = 0;
+    let timeoutRetries = 0;
+    let neverSentRetries = 0;
+    for (; ; ) {
+      const req = {
+        requestId: crypto.randomUUID(),
+        epoch: this.epoch,
+        op
+      };
+      const res = await this.controlRpc.request(this.subject, req, { timeoutMs });
+      if (!res.error && res.result) {
+        const retries = drainingRetries + timeoutRetries + neverSentRetries;
+        this.emitOp({
+          op: opKind,
+          outcome: "ok",
+          healed: retries > 0,
+          retries,
+          durationMs: Date.now() - startedAt,
+          machineId: this.agentId,
+          // A healed op's class is whichever retry budget it recovered from.
+          ...retries > 0 ? {
+            faultClass: neverSentRetries > 0 ? "offline" : drainingRetries > 0 ? "draining" : "reconnecting"
+          } : {}
+        });
+        return res.result;
+      }
+      const error = res.error ? agentErrorToControlError(res.error) : agentErrorToControlError({
         code: 7,
         // ERROR_CODE_PROTOCOL — an empty result is a protocol violation
         message: "agent returned an empty control response",
         retryable: false,
         detail: {}
       });
+      const decision = decideSelfhostedRetry({
+        opKind,
+        error,
+        drainingRetries,
+        timeoutRetries,
+        neverSentRetries,
+        jitter: this.retryClock.jitter()
+      });
+      if (decision.action === "fail") {
+        const retries = drainingRetries + timeoutRetries + neverSentRetries;
+        const encoded = Number(error.detail.encoded_bytes);
+        this.emitOp({
+          op: opKind,
+          outcome: "failed",
+          healed: false,
+          retries,
+          durationMs: Date.now() - startedAt,
+          code: error.code,
+          reason: error.reason,
+          neverSent: error.neverSent,
+          machineId: this.agentId,
+          faultClass: selfhostedFaultClass(error),
+          // Known only on a PAYLOAD_TOO_LARGE fault (the agent's encoded_bytes detail).
+          ...Number.isFinite(encoded) ? { replyBytes: encoded } : {}
+        });
+        if (error.draining && drainingRetries > 0) {
+          throw drainingExhaustedError(error, drainingRetries);
+        }
+        throw error;
+      }
+      await this.retryClock.sleep(decision.delayMs);
+      if (error.neverSent) {
+        neverSentRetries += 1;
+      } else if (error.draining) {
+        drainingRetries += 1;
+      } else {
+        timeoutRetries += 1;
+      }
     }
-    return res.result;
+  }
+  /** The clamped exec process deadline (ms): the exec-specific budget when threaded,
+   *  else the control timeout. Shared by `exec()` (the wire deadline) and
+   *  `execCommand()` (the timed-out hint's "N-second limit"), so the two never drift. */
+  execDeadlineMs() {
+    return Math.max(
+      1,
+      Math.min(Math.trunc(this.execTimeoutMs ?? this.timeoutMs), SELFHOSTED_MAX_EXEC_TIMEOUT_MS)
+    );
   }
   /** Channel-A `exec`: run a command on the machine and return its output. */
   async exec(args) {
+    const executionTimeoutMs = this.execDeadlineMs();
     const execReq = {
       // The agent does NOT shell-interpret unless `shell` — Channel-A passes a
       // single shell command string, so run it through the platform shell.
@@ -800,13 +1836,98 @@ var SelfhostedSession = class {
       // seed hook can find the tool surface. See SELFHOSTED_EXEC_ENV_ALLOWLIST.
       env: selfhostedExecEnv(this.state.environment),
       stdin: new Uint8Array(0),
-      timeoutMs: 0
+      timeoutMs: executionTimeoutMs
     };
-    const result = await this.call({ $case: "exec", exec: execReq });
+    if (this.opStreamClient) {
+      try {
+        return await this.execViaOpStream(this.opStreamClient, execReq, executionTimeoutMs);
+      } catch (error) {
+        if (!(error instanceof OpStreamUnavailableError)) {
+          throw error;
+        }
+      }
+    }
+    return this.execLegacy(execReq, executionTimeoutMs);
+  }
+  /** The legacy monolithic exec request/reply — the permanent fallback wire
+   *  form (and the only form for runners without `op_stream`). */
+  async execLegacy(execReq, executionTimeoutMs) {
+    const result = await this.call(
+      { $case: "exec", exec: execReq },
+      executionTimeoutMs + SELFHOSTED_EXEC_REPLY_GRACE_MS
+    );
     if (result.$case !== "exec") {
       throw new Error(`selfhosted exec: unexpected result ${result.$case}`);
     }
-    return execResultToChannelA(result.exec);
+    return execResultToChannelA(result.exec, executionTimeoutMs);
+  }
+  /**
+   * The op-stream exec path: the SAME `ExecRequest`, streamed (see
+   * op-stream.ts). The durable op id comes from the tool-call correlation
+   * context (`{callId}:{ordinal}` — B1) when this exec runs inside an SDK tool
+   * invocation; a non-tool caller falls back to a random unique id (never
+   * collides, merely not stable across a turn re-dispatch). Emits the SAME
+   * per-op observation the legacy path does, with `replyBytes` filled from the
+   * reassembled stream (the field the framed transport was designed to own).
+   */
+  async execViaOpStream(client, execReq, executionTimeoutMs) {
+    const startedAt = Date.now();
+    const opId = nextDurableOpId() ?? `anon_${crypto.randomUUID()}`;
+    try {
+      const outcome = await client.exec(
+        opId,
+        execReq,
+        executionTimeoutMs,
+        executionTimeoutMs + SELFHOSTED_EXEC_REPLY_GRACE_MS
+      );
+      const retries = outcome.heals + outcome.startRetries;
+      this.emitOp({
+        op: "exec",
+        outcome: "ok",
+        healed: retries > 0,
+        retries,
+        durationMs: Date.now() - startedAt,
+        machineId: this.agentId,
+        replyBytes: outcome.replyBytes,
+        // A healed op's class: attach heals are link blips (reconnecting);
+        // start retries without heals were admission backpressure (draining).
+        ...retries > 0 ? { faultClass: outcome.heals > 0 ? "reconnecting" : "draining" } : {}
+      });
+      return execResultToChannelA(outcome.response, executionTimeoutMs);
+    } catch (error) {
+      if (error instanceof OpStreamUnavailableError) {
+        throw error;
+      }
+      const controlError = error instanceof SelfhostedControlError ? error : new SelfhostedControlError({
+        message: error instanceof Error ? error.message : String(error),
+        code: ErrorCode4.ERROR_CODE_PROTOCOL,
+        reason: null,
+        retryable: false
+      });
+      this.emitOp({
+        op: "exec",
+        outcome: "failed",
+        healed: false,
+        retries: 0,
+        durationMs: Date.now() - startedAt,
+        code: controlError.code,
+        reason: controlError.reason,
+        neverSent: controlError.neverSent,
+        machineId: this.agentId,
+        faultClass: selfhostedFaultClass(controlError)
+      });
+      throw controlError;
+    }
+  }
+  /**
+   * The turn-end op-stream durability hook: persists each settled op's frontier
+   * to the journal, then final-acks it on the wire (licensing the runner to GC
+   * its retained frames). The WORKER calls this after the turn's results are
+   * durably recorded — never mid-turn (the durable-before-wire-ack ordering).
+   * A no-op for sessions without the op-stream transport.
+   */
+  async finalizeOpStreamOps() {
+    await this.opStreamClient?.finalizeSettledOps();
   }
   // ── The agent-turn provided-session contract (over the SAME NATS primitives) ──
   // These are what the @openai/agents shell/filesystem/skills capabilities call on
@@ -814,9 +1935,23 @@ var SelfhostedSession = class {
   // exec/fs ops above; the machine owns its filesystem (materialization is a no-op).
   /** SDK shell capability `execCommand`: run a command and return its stdout (the
    *  `exec_command` tool). Selfhosted exec is non-interactive (no PTY) — `tty` is
-   *  ignored; `supportsPty()` is false so the SDK never offers a stdin session. */
+   *  ignored; `supportsPty()` is false so the SDK never offers a stdin session.
+   *
+   *  On a DEADLINE timeout the SDK path is stdout-only (the model sees `result.output`
+   *  and nothing else), so the deadline hint that `exec()` puts on stderr would be
+   *  invisible — a >deadline command would return `{"output":""}` and the model would
+   *  conclude "no output" with no idea it was killed. So when the result timed out we
+   *  surface the hint HERE, on stdout: the hint alone when stdout is empty, or appended
+   *  after a newline when there is partial output (a timed-out result is already not
+   *  cleanly parseable — silence is worse than an explanatory suffix). The structured
+   *  `exec()` result is left untouched for the Channel-A parsers. */
   async execCommand(args) {
     const result = await this.exec({ cmd: args.cmd, workdir: args.workdir, runAs: args.runAs });
+    if (result.timedOut) {
+      const hint = execDeadlineHint(Math.round(this.execDeadlineMs() / 1e3));
+      return result.output ? `${result.output}
+${hint}` : hint;
+    }
     return result.output;
   }
   /** SDK shell capability never calls this (gated on `supportsPty()` which is
@@ -829,7 +1964,10 @@ var SelfhostedSession = class {
    *  and wrap them in the tool-output image shape (magic-byte sniff + path fallback,
    *  mirroring the SDK's `imageOutputFromBytes`). */
   async viewImage(args) {
-    const bytes = await this.readFile({ path: args.path, ...args.runAs ? { runAs: args.runAs } : {} });
+    const bytes = await this.readFile({
+      path: args.path,
+      ...args.runAs ? { runAs: args.runAs } : {}
+    });
     const mediaType = sniffImageMediaType(bytes, args.path);
     if (!mediaType) {
       throw new Error(`selfhosted view_image: unsupported image format for ${args.path}`);
@@ -877,7 +2015,10 @@ var SelfhostedSession = class {
       await this.writeFile({ path, content, createParents: true });
     };
     const deletePath = async (path) => {
-      await this.exec({ cmd: `rm -rf -- ${shellQuote(toMachinePath(path, ""))}`, ...runAs ? { runAs } : {} });
+      await this.exec({
+        cmd: `rm -rf -- ${shellQuote(toMachinePath(path, ""))}`,
+        ...runAs ? { runAs } : {}
+      });
     };
     return {
       async createFile(operation) {
@@ -940,7 +2081,10 @@ var SelfhostedSession = class {
   async listFiles(args) {
     const result = await this.call({
       $case: "fsList",
-      fsList: { path: toMachinePath(args.path, this.workingDir), recursive: args.recursive ?? false }
+      fsList: {
+        path: toMachinePath(args.path, this.workingDir),
+        recursive: args.recursive ?? false
+      }
     });
     if (result.$case !== "fsList") {
       throw new Error(`selfhosted listFiles: unexpected result ${result.$case}`);
@@ -949,7 +2093,10 @@ var SelfhostedSession = class {
   }
   /** Stat a path on the machine. */
   async statFile(args) {
-    const result = await this.call({ $case: "fsStat", fsStat: { path: toMachinePath(args.path, this.workingDir) } });
+    const result = await this.call({
+      $case: "fsStat",
+      fsStat: { path: toMachinePath(args.path, this.workingDir) }
+    });
     if (result.$case !== "fsStat") {
       throw new Error(`selfhosted statFile: unexpected result ${result.$case}`);
     }
@@ -1031,7 +2178,9 @@ var SelfhostedSession = class {
         desktopEnsure: { width: 0, height: 0 }
       });
       if (result.$case !== "desktopEnsure") {
-        throw new Error(`selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`);
+        throw new Error(
+          `selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`
+        );
       }
       channel = result.desktopEnsure.channel;
     } else {
@@ -1040,10 +2189,19 @@ var SelfhostedSession = class {
         // Open the terminal in the session workingDir (default "" ⇒ the agent's
         // workspace_root, byte-identical to before). A relative workingDir resolves
         // under workspace_root; an absolute one is used as-is by the agent.
-        ptyOpen: { command: [], cwd: this.workingDir, env: {}, cols: 0, rows: 0, term: "xterm-256color" }
+        ptyOpen: {
+          command: [],
+          cwd: this.workingDir,
+          env: {},
+          cols: 0,
+          rows: 0,
+          term: "xterm-256color"
+        }
       });
       if (result.$case !== "ptyOpen") {
-        throw new Error(`selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`);
+        throw new Error(
+          `selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`
+        );
       }
       channel = result.ptyOpen.channel;
     }
@@ -1074,8 +2232,11 @@ var SelfhostedSandboxClient = class {
   defaultAgentId;
   epoch;
   timeoutMs;
+  execTimeoutMs;
   environment;
   workingDir;
+  onOp;
+  opStream;
   controlRpcMemo;
   constructor(opts) {
     this.workspaceId = opts.workspaceId;
@@ -1084,8 +2245,11 @@ var SelfhostedSandboxClient = class {
     this.defaultAgentId = opts.agentId;
     this.epoch = opts.epoch;
     this.timeoutMs = opts.timeoutMs;
+    this.execTimeoutMs = opts.execTimeoutMs;
     this.environment = opts.environment;
     this.workingDir = opts.workingDir;
+    this.onOp = opts.onOp;
+    this.opStream = opts.opStream;
   }
   controlRpc() {
     if (!this.controlRpcMemo) {
@@ -1101,8 +2265,11 @@ var SelfhostedSandboxClient = class {
       relay: this.relay,
       ...this.epoch !== void 0 ? { epoch: this.epoch } : {},
       ...this.timeoutMs !== void 0 ? { timeoutMs: this.timeoutMs } : {},
+      ...this.execTimeoutMs !== void 0 ? { execTimeoutMs: this.execTimeoutMs } : {},
       ...this.environment !== void 0 ? { environment: this.environment } : {},
-      ...this.workingDir !== void 0 ? { workingDir: this.workingDir } : {}
+      ...this.workingDir !== void 0 ? { workingDir: this.workingDir } : {},
+      ...this.onOp !== void 0 ? { onOp: this.onOp } : {},
+      ...this.opStream !== void 0 ? { opStream: this.opStream } : {}
     });
   }
   /** Bind a session to the live agent subject. There is no box to provision. */
@@ -1132,7 +2299,9 @@ var SelfhostedSandboxClient = class {
   }
   requireAgentId() {
     if (!this.defaultAgentId) {
-      throw new Error("selfhosted sandbox client: no agentId bound (create()/resume() need a session state carrying agentId)");
+      throw new Error(
+        "selfhosted sandbox client: no agentId bound (create()/resume() need a session state carrying agentId)"
+      );
     }
     return this.defaultAgentId;
   }
@@ -1145,8 +2314,11 @@ async function buildSelfhostedBackendSession(deps) {
     agentId: deps.agentId,
     epoch: deps.epoch,
     ...deps.timeoutMs !== void 0 ? { timeoutMs: deps.timeoutMs } : {},
+    ...deps.execTimeoutMs !== void 0 ? { execTimeoutMs: deps.execTimeoutMs } : {},
+    ...deps.onOp !== void 0 ? { onOp: deps.onOp } : {},
     ...deps.environment !== void 0 ? { environment: deps.environment } : {},
-    ...deps.workingDir ? { workingDir: deps.workingDir } : {}
+    ...deps.workingDir ? { workingDir: deps.workingDir } : {},
+    ...deps.opStream !== void 0 ? { opStream: deps.opStream } : {}
   });
   const session = await client.resume({ agentId: deps.agentId });
   return { client, session };
@@ -1160,14 +2332,20 @@ function readAgentId(state) {
   }
   return void 0;
 }
-function execResultToChannelA(res) {
+function execResultToChannelA(res, execDeadlineMs) {
   const stdout = decoder.decode(res.stdout);
-  const stderr = decoder.decode(res.stderr);
+  let stderr = decoder.decode(res.stderr);
+  if (res.timedOut) {
+    const hint = execDeadlineHint(Math.round(execDeadlineMs / 1e3));
+    stderr = stderr ? `${stderr}
+${hint}` : hint;
+  }
   return {
     output: stdout,
     stdout,
     stderr,
-    exitCode: res.exitCode
+    exitCode: res.exitCode,
+    timedOut: res.timedOut
   };
 }
 function channelKey(workspaceId, agentId, port) {
@@ -1177,12 +2355,16 @@ function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function sniffImageMediaType(bytes, path) {
-  if (bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71) return "image/png";
+  if (bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71)
+    return "image/png";
   if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return "image/jpeg";
-  if (bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 56) return "image/gif";
-  if (bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80) return "image/webp";
+  if (bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 56)
+    return "image/gif";
+  if (bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80)
+    return "image/webp";
   if (bytes[0] === 66 && bytes[1] === 77) return "image/bmp";
-  if (bytes[0] === 73 && bytes[1] === 73 && bytes[2] === 42 && bytes[3] === 0 || bytes[0] === 77 && bytes[1] === 77 && bytes[2] === 0 && bytes[3] === 42) return "image/tiff";
+  if (bytes[0] === 73 && bytes[1] === 73 && bytes[2] === 42 && bytes[3] === 0 || bytes[0] === 77 && bytes[1] === 77 && bytes[2] === 0 && bytes[3] === 42)
+    return "image/tiff";
   if (looksLikeSvg(bytes)) return "image/svg+xml";
   return mediaTypeFromPath(path);
 }
@@ -1329,14 +2511,20 @@ function assertProviderRegistryInvariants() {
   for (const backend of SandboxBackend2.options) {
     const registration = PROVIDER_REGISTRY[backend];
     if (registration.backend !== backend) {
-      throw new Error(`PROVIDER_REGISTRY["${backend}"].backend mismatch (got "${registration.backend}")`);
+      throw new Error(
+        `PROVIDER_REGISTRY["${backend}"].backend mismatch (got "${registration.backend}")`
+      );
     }
     if (registration.descriptor.backend !== backend) {
-      throw new Error(`PROVIDER_REGISTRY["${backend}"].descriptor.backend mismatch (got "${registration.descriptor.backend}")`);
+      throw new Error(
+        `PROVIDER_REGISTRY["${backend}"].descriptor.backend mismatch (got "${registration.descriptor.backend}")`
+      );
     }
     if (backend === "none") {
       if (registration.descriptor.backendId !== "none") {
-        throw new Error(`"none" descriptor.backendId must be "none" (got "${registration.descriptor.backendId}")`);
+        throw new Error(
+          `"none" descriptor.backendId must be "none" (got "${registration.descriptor.backendId}")`
+        );
       }
       continue;
     }
@@ -1394,7 +2582,14 @@ function negotiateCapabilities(ctx) {
   const osReason = osSupported ? null : "os_unsupported";
   const fileSystem = (() => {
     if (osReason) {
-      return { available: false, readOnly: true, root: descriptor.workspaceRoot, pathSep: "/", treeMode: "lazy", reason: osReason };
+      return {
+        available: false,
+        readOnly: true,
+        root: descriptor.workspaceRoot,
+        pathSep: "/",
+        treeMode: "lazy",
+        reason: osReason
+      };
     }
     const cap = descriptor.capabilities.FileSystem;
     return {
@@ -1409,10 +2604,26 @@ function negotiateCapabilities(ctx) {
   const terminal = (() => {
     const cap = descriptor.capabilities.Terminal;
     if (osReason) {
-      return { transport: null, ptyCapable: false, shell: "/bin/bash", url: null, token: null, expiresAt: null, reason: osReason };
+      return {
+        transport: null,
+        ptyCapable: false,
+        shell: "/bin/bash",
+        url: null,
+        token: null,
+        expiresAt: null,
+        reason: osReason
+      };
     }
     if (!cap.available) {
-      return { transport: null, ptyCapable: false, shell: "/bin/bash", url: null, token: null, expiresAt: null, reason: "backend_unsupported" };
+      return {
+        transport: null,
+        ptyCapable: false,
+        shell: "/bin/bash",
+        url: null,
+        token: null,
+        expiresAt: null,
+        reason: "backend_unsupported"
+      };
     }
     const ptyCapable = cap.pty;
     let transport = ptyCapable ? "pty-ws" : "sse-events";
@@ -1440,7 +2651,11 @@ function negotiateCapabilities(ctx) {
     if (osReason) {
       return { available: false, repos: [], reason: osReason };
     }
-    return { available: cap.available, repos: [], reason: cap.available ? null : "backend_unsupported" };
+    return {
+      available: cap.available,
+      repos: [],
+      reason: cap.available ? null : "backend_unsupported"
+    };
   })();
   const desktop = (() => {
     const cap = descriptor.capabilities.DesktopStream;
@@ -1493,13 +2708,28 @@ function negotiateCapabilities(ctx) {
   const recording = (() => {
     const cap = descriptor.capabilities.Recording;
     if (osReason) {
-      return { available: false, modes: [], codecs: [], reason: osReason };
+      return {
+        available: false,
+        modes: [],
+        codecs: [],
+        reason: osReason
+      };
     }
     if (!cap.available) {
-      return { available: false, modes: [], codecs: [], reason: descriptor.tier === "headless" ? "tier_headless" : "backend_unsupported" };
+      return {
+        available: false,
+        modes: [],
+        codecs: [],
+        reason: descriptor.tier === "headless" ? "tier_headless" : "backend_unsupported"
+      };
     }
     if (!ctx.desktopEnabled) {
-      return { available: false, modes: [], codecs: [], reason: "disabled_by_policy" };
+      return {
+        available: false,
+        modes: [],
+        codecs: [],
+        reason: "disabled_by_policy"
+      };
     }
     return {
       available: true,
@@ -1515,7 +2745,11 @@ function negotiateCapabilities(ctx) {
       return { available: false, readOnly, reason: osReason };
     }
     if (!desktopCapable) {
-      return { available: false, readOnly, reason: descriptor.tier === "headless" ? "tier_headless" : "backend_unsupported" };
+      return {
+        available: false,
+        readOnly,
+        reason: descriptor.tier === "headless" ? "tier_headless" : "backend_unsupported"
+      };
     }
     if (!ctx.desktopEnabled || ctx.computerUseEnabled === false) {
       return { available: false, readOnly, reason: "disabled_by_policy" };
@@ -1546,7 +2780,9 @@ import {
   signStreamToken,
   verifyStreamToken as verifyStreamTokenEnvelope
 } from "@opengeni/contracts";
-import { StreamTokenPayload as StreamTokenPayload2 } from "@opengeni/contracts";
+import {
+  StreamTokenPayload as StreamTokenPayload2
+} from "@opengeni/contracts";
 var STREAM_TOKEN_DEFAULT_TTL_SECONDS = 120;
 async function mintStreamToken(secret, input) {
   const nowSeconds = input.nowSeconds ?? Math.floor(Date.now() / 1e3);
@@ -1580,8 +2816,10 @@ var DisplayStackError = class extends Error {
   stage;
   constructor(exitCode, output) {
     const stage = exitCode === 11 ? "xvfb" : exitCode === 12 ? "x11vnc" : exitCode === 13 ? "websockify" : exitCode === 14 ? "paint" : "unknown";
-    super(`desktop display stack failed at stage "${stage}" (exit ${exitCode})${output ? `:
-${output}` : ""}`);
+    super(
+      `desktop display stack failed at stage "${stage}" (exit ${exitCode})${output ? `:
+${output}` : ""}`
+    );
     this.name = "DisplayStackError";
     this.exitCode = exitCode;
     this.stage = stage;
@@ -1658,7 +2896,11 @@ async function tearDownDisplayStack(session) {
     return;
   }
   if (typeof s?.execCommand === "function") {
-    await s.execCommand({ cmd: "opengeni-desktop-down", yieldTimeMs: 1e4, maxOutputTokens: 4e3 });
+    await s.execCommand({
+      cmd: "opengeni-desktop-down",
+      yieldTimeMs: 1e4,
+      maxOutputTokens: 4e3
+    });
   }
 }
 
@@ -1670,8 +2912,10 @@ var TerminalServerError = class extends Error {
   stage;
   constructor(exitCode, output) {
     const stage = exitCode === 14 ? "ttyd" : "unknown";
-    super(`terminal server failed at stage "${stage}" (exit ${exitCode})${output ? `:
-${output}` : ""}`);
+    super(
+      `terminal server failed at stage "${stage}" (exit ${exitCode})${output ? `:
+${output}` : ""}`
+    );
     this.name = "TerminalServerError";
     this.exitCode = exitCode;
     this.stage = stage;
@@ -1734,7 +2978,11 @@ async function tearDownTerminalServer(session) {
     return;
   }
   if (typeof s?.execCommand === "function") {
-    await s.execCommand({ cmd: "opengeni-terminal-down", yieldTimeMs: 1e4, maxOutputTokens: 4e3 });
+    await s.execCommand({
+      cmd: "opengeni-terminal-down",
+      yieldTimeMs: 1e4,
+      maxOutputTokens: 4e3
+    });
   }
 }
 
@@ -1746,7 +2994,6 @@ var StreamPortUnavailableError = class extends Error {
     this.cause = cause;
     this.name = "StreamPortUnavailableError";
   }
-  cause;
 };
 var DEFAULT_RESOLUTION = [1280, 800];
 function buildStreamUrl(endpoint) {
@@ -1833,7 +3080,6 @@ var RecordingError = class extends Error {
     this.reason = reason;
     this.name = "RecordingError";
   }
-  reason;
 };
 function shq(s) {
   return `'${s.replace(/'/g, `'\\''`)}'`;
@@ -1851,7 +3097,9 @@ async function run(session, cmd, runAs, yieldTimeMs = EXEC_YIELD_MS, maxOutputTo
   if (typeof session.execCommand === "function") {
     return resultOutput(await session.execCommand(args));
   }
-  throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) \u2014 recording unavailable");
+  throw new RecordingUnavailableError(
+    "session cannot run commands (no exec/execCommand) \u2014 recording unavailable"
+  );
 }
 function stripExecBanner(raw) {
   const marker = raw.lastIndexOf("\nOutput:\n");
@@ -1892,12 +3140,18 @@ async function stopRecording(session, proc) {
   const wait = `kill -INT "$(cat ${proc.pidFile})" 2>/dev/null; for i in $(seq 1 80); do kill -0 "$(cat ${proc.pidFile})" 2>/dev/null || break; sleep 0.1; done`;
   await run(s, `bash -lc ${shq(wait)}`, proc.runAs, STOP_YIELD_MS).catch(() => void 0);
 }
-async function readRecordingBytes(session, proc, maxBytes = DEFAULT_MAX_BYTES) {
+async function inspectRecordingArtifact(session, proc, maxBytes = DEFAULT_MAX_BYTES) {
   const s = session;
   if (typeof s.exec !== "function" && typeof s.execCommand !== "function") {
-    throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) \u2014 recording finalize unavailable");
+    throw new RecordingUnavailableError(
+      "session cannot run commands (no exec/execCommand) \u2014 recording finalize unavailable"
+    );
   }
-  const sizeOut = (await run(s, `bash -lc ${shq(`stat -c %s ${proc.boxPath} 2>/dev/null || echo MISSING`)}`, proc.runAs)).trim();
+  const sizeOut = (await run(
+    s,
+    `bash -lc ${shq(`stat -c %s ${proc.boxPath} 2>/dev/null || echo MISSING`)}`,
+    proc.runAs
+  )).trim();
   const sizeLine = sizeOut.split("\n").map((l) => l.trim()).filter(Boolean).pop() ?? "MISSING";
   if (sizeLine === "MISSING" || sizeLine === "") {
     throw new RecordingError(`recording file missing on box: ${proc.boxPath}`, "box-death");
@@ -1909,34 +3163,45 @@ async function readRecordingBytes(session, proc, maxBytes = DEFAULT_MAX_BYTES) {
   if (size > maxBytes) {
     throw new RecordingError(`recording ${size}B exceeds max ${maxBytes}B`, "max-bytes-exceeded");
   }
-  const STOP_YIELD = 6e4;
-  const encoded = stripExecBanner(
-    await run(s, `bash -lc ${shq(`base64 ${proc.boxPath}`)}`, proc.runAs, STOP_YIELD, null)
-  );
-  const base64 = encoded.replace(/\s+/g, "");
-  if (base64.length === 0) {
-    throw new RecordingError(`recording read returned 0 bytes: ${proc.boxPath}`, "ffmpeg-error");
-  }
-  let bytes;
-  try {
-    bytes = Uint8Array.from(Buffer.from(base64, "base64"));
-  } catch (error) {
-    throw new RecordingError(`recording base64 decode failed: ${error instanceof Error ? error.message : String(error)}`, "ffmpeg-error");
-  }
-  if (bytes.length === 0) {
-    throw new RecordingError(`recording read returned 0 bytes: ${proc.boxPath}`, "ffmpeg-error");
-  }
   return {
-    bytes,
     contentType: contentTypeForCodec(proc.codec),
-    sizeBytes: bytes.length,
+    sizeBytes: size,
     durationSeconds: Math.max(0, Math.round((Date.now() - proc.startedAt) / 1e3))
   };
 }
+var RECORDING_UPLOAD_OK = "OPENGENI_RECORDING_UPLOAD_OK";
+var RECORDING_UPLOAD_MAX_SECONDS = 300;
+async function uploadRecordingArtifact(session, proc, input) {
+  const maxSeconds = input.maxSeconds ?? RECORDING_UPLOAD_MAX_SECONDS;
+  if (!Number.isSafeInteger(maxSeconds) || maxSeconds <= 0 || maxSeconds > 300) {
+    throw new Error("recording upload maxSeconds must be an integer between 1 and 300");
+  }
+  const metadata = await inspectRecordingArtifact(session, proc, input.maxBytes);
+  const headers = Object.entries(input.requiredHeaders).sort(([left], [right]) => left.localeCompare(right)).map(([name, value]) => `--header ${shq(`${name}: ${value}`)}`).join(" ");
+  const upload = [
+    "set -euo pipefail",
+    `curl --fail --silent --show-error --connect-timeout 20 --max-time ${maxSeconds} --request PUT ${headers} --upload-file ${shq(proc.boxPath)} ${shq(input.url)}`,
+    `printf '${RECORDING_UPLOAD_OK}\\n'`
+  ].join("; ");
+  const output = stripExecBanner(
+    await run(
+      session,
+      `bash -lc ${shq(upload)}`,
+      proc.runAs,
+      (maxSeconds + 10) * 1e3
+    )
+  );
+  if (!output.includes(RECORDING_UPLOAD_OK)) {
+    throw new Error("recording upload did not confirm success");
+  }
+  return metadata;
+}
 async function deleteRecordingArtifacts(session, proc) {
   const s = session;
   const logFile = proc.boxPath.replace(/\.(mp4|webm)$/, ".log");
-  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(() => void 0);
+  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(
+    () => void 0
+  );
 }
 function recordingStorageKey(workspaceId, sessionId, recordingId, codec) {
   return `recordings/${workspaceId}/${sessionId}/${recordingId}.${extForCodec(codec)}`;
@@ -1967,9 +3232,13 @@ var ChannelAUnsupportedError = class extends Error {
     this.name = "ChannelAUnsupportedError";
   }
 };
+var REPOSITORY_DISCOVERY_LIMIT = 256;
+var REPOSITORY_DISCOVERY_TRUNCATED_SENTINEL = "__OPENGENI_REPOSITORY_DISCOVERY_TRUNCATED__";
+var REPOSITORY_DISCOVERY_STATUS_PREFIX = "__OPENGENI_REPOSITORY_DISCOVERY_STATUS__:";
 var NUL = String.fromCharCode(0);
 var US = String.fromCharCode(31);
 var RS = String.fromCharCode(30);
+var SELFHOSTED_VIRTUAL_ROOT2 = "/workspace";
 var SandboxChannelAService = class {
   session;
   workspaceRoot;
@@ -1991,7 +3260,11 @@ var SandboxChannelAService = class {
     const hasExec = Boolean(s.exec || s.execCommand);
     const hasFs = Boolean(s.readFile && (s.exec || s.execCommand || s.createEditor));
     return {
-      FileSystem: { available: hasFs, readOnly: !(s.exec || s.createEditor), root: this.workspaceRoot },
+      FileSystem: {
+        available: hasFs,
+        readOnly: !(s.exec || s.createEditor),
+        root: this.workspaceRoot
+      },
       Terminal: {
         events: hasExec,
         exec: hasExec,
@@ -2037,7 +3310,10 @@ var SandboxChannelAService = class {
     const depthArg = Math.max(1, req.depth);
     const hidden = req.includeHidden ? "" : ` -not -path '*/.*'`;
     const gnuFind = `find ${findRoot} -mindepth 1 -maxdepth ${depthArg}${hidden} -printf '%y\\t%s\\t%T@\\t%m\\t%p\\0' 2>/dev/null`;
-    let { stdout } = await this.run({ cmd: `bash -lc ${shellQuote2(gnuFind)}`, workdir: this.workspaceRoot || void 0 });
+    let { stdout } = await this.run({
+      cmd: `bash -lc ${shellQuote2(gnuFind)}`,
+      workdir: this.workspaceRoot || void 0
+    });
     if (!stdout) {
       const portableFind = [
         `find ${findRoot} -mindepth 1 -maxdepth ${depthArg}${hidden} -print0 2>/dev/null | while IFS= read -r -d '' p; do`,
@@ -2047,7 +3323,10 @@ var SandboxChannelAService = class {
         `printf '%s\\t%s\\t%s\\t%s\\t%s\\0' "$t" "$size" "$mtime" "$mode" "$p";`,
         `done`
       ].join(" ");
-      ({ stdout } = await this.run({ cmd: `bash -lc ${shellQuote2(portableFind)}`, workdir: this.workspaceRoot || void 0 }));
+      ({ stdout } = await this.run({
+        cmd: `bash -lc ${shellQuote2(portableFind)}`,
+        workdir: this.workspaceRoot || void 0
+      }));
     }
     const entries = stdout.split(NUL).filter((s) => s.length > 0);
     const rootNode = {
@@ -2103,12 +3382,18 @@ var SandboxChannelAService = class {
     }
     let raw;
     try {
-      raw = await this.session.readFile({ path: this.joinRoot(path), maxBytes: req.maxBytes, ...this.runAs ? { runAs: this.runAs } : {} });
+      raw = await this.session.readFile({
+        path: this.joinRoot(path),
+        maxBytes: req.maxBytes,
+        ...this.runAs ? { runAs: this.runAs } : {}
+      });
     } catch (error) {
       if (isWorkspaceEscapeError(error)) {
         return await this.fsReadViaExec(path, req);
       }
-      throw new ChannelANotFoundError(`file not found: ${path} (${error instanceof Error ? error.message : String(error)})`);
+      throw new ChannelANotFoundError(
+        `file not found: ${path} (${error instanceof Error ? error.message : String(error)})`
+      );
     }
     const bytes = typeof raw === "string" ? Buffer.from(raw, "utf8") : Buffer.from(raw);
     return this.shapeRead(path, bytes, req);
@@ -2119,7 +3404,9 @@ var SandboxChannelAService = class {
    *  node itself is in-workspace). `base64 <path>` follows the symlink. */
   async fsReadViaExec(path, req) {
     const abs = this.joinRoot(path);
-    const { stdout, exitCode } = await this.run({ cmd: `base64 ${shellQuote2(abs)} 2>/dev/null | head -c ${Math.ceil(req.maxBytes * 1.4)}` });
+    const { stdout, exitCode } = await this.run({
+      cmd: `base64 ${shellQuote2(abs)} 2>/dev/null | head -c ${Math.ceil(req.maxBytes * 1.4)}`
+    });
     if (exitCode !== null && exitCode !== 0 && stdout === "") {
       throw new ChannelANotFoundError(`file not found: ${path}`);
     }
@@ -2162,13 +3449,21 @@ var SandboxChannelAService = class {
     if (exitCode !== null && exitCode !== 0) {
       if (req.encoding !== "base64" && this.session.createEditor) {
         const ok2 = await this.tryEditorWrite(abs, req.content);
-        if (!ok2) throw new ChannelAValidationError(`failed to write ${path}: ${stderr || `exit ${exitCode}`}`);
+        if (!ok2)
+          throw new ChannelAValidationError(
+            `failed to write ${path}: ${stderr || `exit ${exitCode}`}`
+          );
       } else {
-        throw new ChannelAValidationError(`failed to write ${path}: ${stderr || `exit ${exitCode}`}`);
+        throw new ChannelAValidationError(
+          `failed to write ${path}: ${stderr || `exit ${exitCode}`}`
+        );
       }
     }
     this.revision++;
-    await this.emitFsChanged([{ path, kind: "modified", isDir: false, sizeBytes: bytes.byteLength }], "write");
+    await this.emitFsChanged(
+      [{ path, kind: "modified", isDir: false, sizeBytes: bytes.byteLength }],
+      "write"
+    );
     return { path, sizeBytes: bytes.byteLength, revision: this.revision };
   }
   async tryEditorWrite(absPath, content) {
@@ -2188,7 +3483,9 @@ var SandboxChannelAService = class {
     const flag = req.recursive ? "-rf" : "-f";
     const { exitCode, stderr } = await this.run({ cmd: `rm ${flag} ${shellQuote2(abs)}` });
     if (exitCode !== null && exitCode !== 0) {
-      throw new ChannelAValidationError(`failed to delete ${path}: ${stderr || `exit ${exitCode}`}`);
+      throw new ChannelAValidationError(
+        `failed to delete ${path}: ${stderr || `exit ${exitCode}`}`
+      );
     }
     this.revision++;
     await this.emitFsChanged([{ path, kind: "deleted", isDir: false, sizeBytes: null }], "write");
@@ -2214,7 +3511,9 @@ var SandboxChannelAService = class {
       cmd: `mv ${flag}${shellQuote2(abs)} ${shellQuote2(newAbs)}`
     });
     if (exitCode !== null && exitCode !== 0) {
-      throw new ChannelAValidationError(`failed to move ${path} -> ${newPath}: ${stderr || `exit ${exitCode}`}`);
+      throw new ChannelAValidationError(
+        `failed to move ${path} -> ${newPath}: ${stderr || `exit ${exitCode}`}`
+      );
     }
     this.revision++;
     await this.emitFsChanged(
@@ -2241,11 +3540,26 @@ var SandboxChannelAService = class {
   // ════════════════════════════ Git (A2, read-only) ═════════════════════════
   async gitStatus(req) {
     const repo = this.repoWorkdir(req.path);
-    const inside = await this.run({ cmd: "git rev-parse --is-inside-work-tree 2>/dev/null", workdir: repo });
+    const inside = await this.run({
+      cmd: "git rev-parse --is-inside-work-tree 2>/dev/null",
+      workdir: repo
+    });
     if (inside.stdout.trim() !== "true") {
-      return { isRepo: false, head: null, detached: false, upstream: null, ahead: 0, behind: 0, files: [], revision: this.revision };
+      return {
+        isRepo: false,
+        head: null,
+        detached: false,
+        upstream: null,
+        ahead: 0,
+        behind: 0,
+        files: [],
+        revision: this.revision
+      };
     }
-    const { stdout } = await this.run({ cmd: "git status --porcelain=v2 --branch -z", workdir: repo });
+    const { stdout } = await this.run({
+      cmd: "git status --porcelain=v2 --branch -z",
+      workdir: repo
+    });
     return { ...parsePorcelainV2(stdout), revision: this.revision };
   }
   async gitDiff(req) {
@@ -2256,7 +3570,10 @@ var SandboxChannelAService = class {
     else if (req.fromRef) range = `${shellQuote2(req.fromRef)}`;
     else if (req.staged) range = "--cached";
     const pathspec = req.pathspec.length ? ` -- ${req.pathspec.map(shellQuote2).join(" ")}` : "";
-    const numstat = await this.run({ cmd: `git -c core.quotePath=false diff --no-color -z --numstat ${range}${pathspec}`.trim(), workdir: repo });
+    const numstat = await this.run({
+      cmd: `git -c core.quotePath=false diff --no-color -z --numstat ${range}${pathspec}`.trim(),
+      workdir: repo
+    });
     const stats = parseNumstatZ(numstat.stdout);
     const files = [];
     for (const stat of stats) {
@@ -2343,24 +3660,121 @@ var SandboxChannelAService = class {
       return {
         commit: null,
         files: [],
-        blob: { content: encoding === "base64" ? clamped.toString("base64") : clamped.toString("utf8"), encoding, sizeBytes: clamped.byteLength, truncated },
+        blob: {
+          content: encoding === "base64" ? clamped.toString("base64") : clamped.toString("utf8"),
+          encoding,
+          sizeBytes: clamped.byteLength,
+          truncated
+        },
         revision: this.revision
       };
     }
-    const log = await this.gitLog({ path: req.path, ref: req.ref, maxCount: 1, skip: 0, pathspec: [] });
+    const log = await this.gitLog({
+      path: req.path,
+      ref: req.ref,
+      maxCount: 1,
+      skip: 0,
+      pathspec: []
+    });
     const commit = log.commits[0] ?? null;
-    const diff = await this.gitDiff({ path: req.path, staged: false, fromRef: `${req.ref}^`, toRef: req.ref, pathspec: [], contextLines: 3, maxBytesPerFile: req.maxBytesPerFile });
+    const diff = await this.gitDiff({
+      path: req.path,
+      staged: false,
+      fromRef: `${req.ref}^`,
+      toRef: req.ref,
+      pathspec: [],
+      contextLines: 3,
+      maxBytesPerFile: req.maxBytesPerFile
+    });
     return { commit, files: diff.files, blob: null, revision: this.revision };
   }
-  /** Detect repo roots within the workspace (for the Git.repos capability). */
-  async detectRepos() {
+  /**
+   * Detect repo roots within every supported workspace layout.
+   *
+   * The platform seeds GitHub repositories at
+   * `repos/<owner>/<repo>`, which puts the `.git` marker at depth four from the
+   * workspace root. Do not reintroduce a fixed maxdepth here. Traversal is
+   * bounded instead by pruning known machine/build residue, a wall-clock
+   * timeout, and a result limit. `.git` may be either a directory (ordinary
+   * clone/submodule) or a file (linked worktree).
+   *
+   * Callers that persist an authoritative snapshot must use this detailed
+   * result and surface an incomplete discovery. The compact `detectRepos()`
+   * wrapper remains for capability negotiation, where the best available list
+   * is preferable to failing the whole capabilities document.
+   */
+  async detectReposDetailed() {
     try {
-      const { stdout } = await this.run({ cmd: `find . -maxdepth 3 -name .git -type d 2>/dev/null`, workdir: this.workspaceRoot || void 0 });
-      return stdout.split("\n").map((l) => l.trim()).filter(Boolean).map((g) => dirnameAbs(stripDotSlash(g, "")) || "");
+      const discovery = [
+        "find . -xdev",
+        "\\( -name .git \\( -type d -o -type f \\) -print -prune \\)",
+        "-o \\( -type d \\( -name node_modules -o -name .cache -o -name .local",
+        "-o -name dist -o -name build -o -name target -o -name .venv",
+        "-o -name __pycache__ -o -name .next \\) -prune \\)",
+        "2>/dev/null"
+      ].join(" ");
+      const command = [
+        'results_file=$(mktemp "${TMPDIR:-/tmp}/opengeni-repository-discovery.XXXXXX") || exit 70',
+        'timeout_file="${results_file}.timed-out"',
+        "discovery_pid=",
+        "watchdog_pid=",
+        'cleanup() { if [ -n "$discovery_pid" ]; then kill "$discovery_pid" 2>/dev/null || true; fi; if [ -n "$watchdog_pid" ]; then kill "$watchdog_pid" 2>/dev/null || true; fi; rm -f "$results_file" "$timeout_file"; }',
+        "abort() { trap - EXIT; cleanup; exit 143; }",
+        "trap cleanup EXIT",
+        "trap abort HUP INT TERM",
+        `${discovery} > "$results_file" &`,
+        "discovery_pid=$!",
+        '(sleeper_pid=; stop_watchdog() { if [ -n "$sleeper_pid" ]; then kill "$sleeper_pid" 2>/dev/null || true; wait "$sleeper_pid" 2>/dev/null || true; fi; exit 0; }; trap stop_watchdog HUP INT TERM; sleep 15 & sleeper_pid=$!; wait "$sleeper_pid"; sleeper_pid=; if kill -TERM "$discovery_pid" 2>/dev/null; then : > "$timeout_file"; fi) </dev/null >/dev/null 2>&1 &',
+        "watchdog_pid=$!",
+        'wait "$discovery_pid"',
+        "status=$?",
+        "discovery_pid=",
+        'kill "$watchdog_pid" 2>/dev/null || true',
+        'wait "$watchdog_pid" 2>/dev/null || true',
+        "watchdog_pid=",
+        'if [ "$status" -ne 0 ] && [ -f "$timeout_file" ]; then status=124; fi',
+        `if [ "$status" -eq 0 ]; then awk 'NR <= ${REPOSITORY_DISCOVERY_LIMIT} { print } NR == ${REPOSITORY_DISCOVERY_LIMIT + 1} { print "${REPOSITORY_DISCOVERY_TRUNCATED_SENTINEL}" }' "$results_file"; fi`,
+        `printf '\\n${REPOSITORY_DISCOVERY_STATUS_PREFIX}%s\\n' "$status"`,
+        'exit "$status"'
+      ].join("\n");
+      const { stdout } = await this.run({
+        cmd: `bash -lc ${shellQuote2(command)}`,
+        workdir: this.workspaceRoot || void 0,
+        yieldTimeMs: 2e4,
+        // At most 256 Unix paths (PATH_MAX each) plus the status trailer. This
+        // prevents a provider's ordinary output cap from dropping the trailer
+        // and making a partial list look complete.
+        maxOutputTokens: 3e5
+      });
+      const statusLine = stdout.split("\n").find((line) => line.startsWith(REPOSITORY_DISCOVERY_STATUS_PREFIX));
+      const embeddedStatus = statusLine ? Number.parseInt(statusLine.slice(REPOSITORY_DISCOVERY_STATUS_PREFIX.length), 10) : null;
+      const status = Number.isInteger(embeddedStatus) ? embeddedStatus : null;
+      if (status === 124) {
+        return { repos: [], complete: false, degradedReason: "command_timed_out" };
+      }
+      if (status !== 0) {
+        return { repos: [], complete: false, degradedReason: "command_failed" };
+      }
+      const lines = stdout.split("\n").map((l) => l.trim()).filter((line) => Boolean(line) && !line.startsWith(REPOSITORY_DISCOVERY_STATUS_PREFIX));
+      const truncated = lines.includes(REPOSITORY_DISCOVERY_TRUNCATED_SENTINEL);
+      const repos = [
+        ...new Set(
+          lines.filter((line) => line !== REPOSITORY_DISCOVERY_TRUNCATED_SENTINEL).map((gitMarker) => dirnameAbs(stripDotSlash(gitMarker, "")) || "")
+        )
+      ].sort();
+      return {
+        repos,
+        complete: !truncated,
+        degradedReason: truncated ? "result_limit_exceeded" : null
+      };
     } catch {
-      return [];
+      return { repos: [], complete: false, degradedReason: "command_failed" };
     }
   }
+  /** Detect repo roots within the workspace (for the Git.repos capability). */
+  async detectRepos() {
+    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
@@ -2369,15 +3783,23 @@ var SandboxChannelAService = class {
   async terminalExec(req) {
     const r = await this.run({
       cmd: req.command,
-      workdir: this.repoWorkdir(req.cwd),
+      workdir: this.terminalWorkdir(req.cwd),
       yieldTimeMs: req.timeoutMs
     });
     const running = r.exitCode === null && typeof r.sessionId === "number";
     if (req.emitStream && (r.stdout || r.stderr)) {
       const events = [];
       const commandId = crypto.randomUUID();
-      if (r.stdout) events.push({ type: "sandbox.command.output.delta", payload: { stream: "stdout", chunk: r.stdout, commandId, seq: 0 } });
-      if (r.stderr) events.push({ type: "sandbox.command.output.delta", payload: { stream: "stderr", chunk: r.stderr, commandId, seq: 1 } });
+      if (r.stdout)
+        events.push({
+          type: "sandbox.command.output.delta",
+          payload: { stream: "stdout", chunk: r.stdout, commandId, seq: 0 }
+        });
+      if (r.stderr)
+        events.push({
+          type: "sandbox.command.output.delta",
+          payload: { stream: "stderr", chunk: r.stderr, commandId, seq: 1 }
+        });
       await this.emitEvents(events);
     }
     return {
@@ -2398,7 +3820,7 @@ var SandboxChannelAService = class {
     const shell = req.shell ?? "/bin/bash";
     const r = await this.run({
       cmd: shell,
-      workdir: this.repoWorkdir(req.cwd),
+      workdir: this.terminalWorkdir(req.cwd),
       tty: true,
       login: true,
       yieldTimeMs: 250
@@ -2417,7 +3839,11 @@ var SandboxChannelAService = class {
     if (!this.session.writeStdin) {
       throw new ChannelAUnsupportedError("interactive terminal unsupported on this backend");
     }
-    const out = await this.session.writeStdin({ sessionId: execSessionId, chars: data, yieldTimeMs: 250 });
+    const out = await this.session.writeStdin({
+      sessionId: execSessionId,
+      chars: data,
+      yieldTimeMs: 250
+    });
     if (isExecSessionLostBanner(out, execSessionId)) {
       throw new ChannelAConflictError("pty session lost on the live box; reopen the terminal");
     }
@@ -2427,8 +3853,12 @@ var SandboxChannelAService = class {
    *  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({ sessionId: execSessionId, chars: `stty cols ${req.cols} rows ${req.rows}
-`, yieldTimeMs: 50 });
+    await this.session.writeStdin({
+      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. */
@@ -2454,6 +3884,12 @@ var SandboxChannelAService = class {
     const joined = this.joinRoot(safe);
     return joined === "." ? this.workspaceRoot || void 0 : joined;
   }
+  terminalWorkdir(cwd) {
+    if (cwd === SELFHOSTED_VIRTUAL_ROOT2 || cwd.startsWith(`${SELFHOSTED_VIRTUAL_ROOT2}/`)) {
+      return cwd;
+    }
+    return this.repoWorkdir(cwd);
+  }
   async emitEvents(events) {
     if (!this.emit || events.length === 0) return;
     try {
@@ -2462,7 +3898,12 @@ var SandboxChannelAService = class {
     }
   }
   async emitFsChanged(changes, source) {
-    const payload = { changes, source, revision: this.revision, leaseEpoch: this.leaseEpoch };
+    const payload = {
+      changes,
+      source,
+      revision: this.revision,
+      leaseEpoch: this.leaseEpoch
+    };
     await this.emitEvents([{ type: "fs.changed", payload }]);
   }
   /** Re-probe git after a mutation and emit git.changed (best-effort, used by the
@@ -2523,7 +3964,8 @@ function assertSafeRelPath(p) {
   const norm = normalizeRelPath(p);
   if (norm === "") throw new ChannelAValidationError("path is required");
   if (p.startsWith("/")) throw new ChannelAValidationError(`absolute paths are not allowed: ${p}`);
-  if (norm.split("/").some((seg) => seg === "..")) throw new ChannelAValidationError(`path traversal is not allowed: ${p}`);
+  if (norm.split("/").some((seg) => seg === ".."))
+    throw new ChannelAValidationError(`path traversal is not allowed: ${p}`);
   return norm;
 }
 function shellQuote2(s) {
@@ -2623,11 +4065,29 @@ function parsePorcelainV2(z) {
     } else if (rec.startsWith("u ")) {
       const fields = rec.split(" ");
       const path = fields.slice(10).join(" ");
-      files.push({ path, oldPath: null, index: "conflicted", worktree: "conflicted", isConflicted: true });
+      files.push({
+        path,
+        oldPath: null,
+        index: "conflicted",
+        worktree: "conflicted",
+        isConflicted: true
+      });
     } else if (rec.startsWith("? ")) {
-      files.push({ path: rec.slice(2), oldPath: null, index: null, worktree: "untracked", isConflicted: false });
+      files.push({
+        path: rec.slice(2),
+        oldPath: null,
+        index: null,
+        worktree: "untracked",
+        isConflicted: false
+      });
     } else if (rec.startsWith("! ")) {
-      files.push({ path: rec.slice(2), oldPath: null, index: null, worktree: "ignored", isConflicted: false });
+      files.push({
+        path: rec.slice(2),
+        oldPath: null,
+        index: null,
+        worktree: "ignored",
+        isConflicted: false
+      });
     }
   }
   return { isRepo: true, head, detached, upstream, ahead, behind, files };
@@ -2687,10 +4147,22 @@ function parseNumstatZ(z) {
     if (pathPart === "") {
       const oldPath = fields[i + 1] ?? null;
       const newPath = fields[i + 2] ?? "";
-      out.push({ additions: binary ? 0 : Number(addStr), deletions: binary ? 0 : Number(delStr), binary, oldPath, newPath });
+      out.push({
+        additions: binary ? 0 : Number(addStr),
+        deletions: binary ? 0 : Number(delStr),
+        binary,
+        oldPath,
+        newPath
+      });
       i += 3;
     } else {
-      out.push({ additions: binary ? 0 : Number(addStr), deletions: binary ? 0 : Number(delStr), binary, oldPath: null, newPath: pathPart });
+      out.push({
+        additions: binary ? 0 : Number(addStr),
+        deletions: binary ? 0 : Number(delStr),
+        binary,
+        oldPath: null,
+        newPath: pathPart
+      });
       i++;
     }
   }
@@ -2714,7 +4186,14 @@ function parseUnifiedPatch(patch) {
         const oldLines = m[2] !== void 0 ? Number(m[2]) : 1;
         const newStart = Number(m[3]);
         const newLines = m[4] !== void 0 ? Number(m[4]) : 1;
-        current = { oldStart, oldLines, newStart, newLines, header: (m[5] ?? "").trim(), lines: [] };
+        current = {
+          oldStart,
+          oldLines,
+          newStart,
+          newLines,
+          header: (m[5] ?? "").trim(),
+          lines: []
+        };
         hunks.push(current);
         oldNo = oldStart;
         newNo = newStart;
@@ -2749,6 +4228,9 @@ function selfhostedLiveness(input) {
   }
   const consented = enrollment.exposure === "whole-machine" && enrollment.allowScreenControl;
   const hasDisplay = enrollment.hasDisplay;
+  if (enrollment.wentOfflineAt) {
+    return { state: "offline", consented, hasDisplay };
+  }
   if (input.probeResponded) {
     return { state: "online", consented, hasDisplay };
   }
@@ -2787,7 +4269,14 @@ async function negotiateSelfhostedCapabilities(input) {
     return {
       ...caps,
       FileSystem: { ...caps.FileSystem, available: false, readOnly: true, reason },
-      Terminal: { ...caps.Terminal, transport: null, url: null, token: null, expiresAt: null, reason },
+      Terminal: {
+        ...caps.Terminal,
+        transport: null,
+        url: null,
+        token: null,
+        expiresAt: null,
+        reason
+      },
       Git: { ...caps.Git, available: false, reason },
       DesktopStream: {
         ...caps.DesktopStream,
@@ -2841,7 +4330,7 @@ async function negotiateSelfhostedCapabilities(input) {
 
 // src/sandbox/selfhosted/testing.ts
 import {
-  ErrorCode as ErrorCode2,
+  ErrorCode as ErrorCode5,
   FsEntryKind as FsEntryKind2
 } from "@opengeni/agent-proto";
 var encoder2 = new TextEncoder();
@@ -2862,7 +4351,10 @@ var MockAgentResponder = class {
     this.hostname = opts.hostname ?? "mock-machine";
     this.execHandler = opts.exec ?? ((req) => defaultEcho(req, this.hostname));
     for (const [path, content] of Object.entries(opts.files ?? {})) {
-      this.files.set(normalize(path), typeof content === "string" ? encoder2.encode(content) : content);
+      this.files.set(
+        normalize(path),
+        typeof content === "string" ? encoder2.encode(content) : content
+      );
     }
   }
   /** Flip the responder offline mid-test (a deliberate stop / blip). */
@@ -2877,18 +4369,31 @@ var MockAgentResponder = class {
   async request(subject, req, _opts) {
     this.requests.push({ subject, req });
     if (!this.online) {
-      return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_AGENT_OFFLINE, "the enrolled agent is offline", false);
+      return errorResponse(
+        req.requestId,
+        ErrorCode5.ERROR_CODE_AGENT_OFFLINE,
+        "the enrolled agent is offline",
+        false
+      );
     }
     if (this.draining) {
-      return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_DRAINING, "the agent is draining", true);
+      return errorResponse(
+        req.requestId,
+        ErrorCode5.ERROR_CODE_DRAINING,
+        "the agent is draining",
+        true
+      );
     }
     const op = req.op;
     if (!op) {
-      return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_PROTOCOL, "empty op", false);
+      return errorResponse(req.requestId, ErrorCode5.ERROR_CODE_PROTOCOL, "empty op", false);
     }
     switch (op.$case) {
       case "ping":
-        return ok(req.requestId, { $case: "ping", ping: { nonce: op.ping.nonce, agentMonotonicMs: "0" } });
+        return ok(req.requestId, {
+          $case: "ping",
+          ping: { nonce: op.ping.nonce, agentMonotonicMs: "0" }
+        });
       case "exec": {
         const res = await this.execHandler(op.exec);
         return ok(req.requestId, { $case: "exec", exec: res });
@@ -2896,7 +4401,12 @@ var MockAgentResponder = class {
       case "fsRead": {
         const bytes = this.files.get(normalize(op.fsRead.path));
         if (!bytes) {
-          return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_NOT_FOUND, `no such file: ${op.fsRead.path}`, false);
+          return errorResponse(
+            req.requestId,
+            ErrorCode5.ERROR_CODE_NOT_FOUND,
+            `no such file: ${op.fsRead.path}`,
+            false
+          );
         }
         const res = { content: bytes, totalSize: String(bytes.length) };
         return ok(req.requestId, { $case: "fsRead", fsRead: res });
@@ -2945,7 +4455,13 @@ var MockAgentResponder = class {
         return ok(req.requestId, {
           $case: "desktopEnsure",
           desktopEnsure: {
-            channel: { channelId: "mock-desktop", workspaceId: "", agentId: "", kind: 1, port: 6080 },
+            channel: {
+              channelId: "mock-desktop",
+              workspaceId: "",
+              agentId: "",
+              kind: 1,
+              port: 6080
+            },
             display: { id: ":99", width: 1024, height: 768, virtual: true }
           }
         });
@@ -2960,7 +4476,12 @@ var MockAgentResponder = class {
         });
       }
       default:
-        return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_UNSUPPORTED, `mock does not implement ${op.$case}`, false);
+        return errorResponse(
+          req.requestId,
+          ErrorCode5.ERROR_CODE_UNSUPPORTED,
+          `mock does not implement ${op.$case}`,
+          false
+        );
     }
   }
 };
@@ -3016,9 +4537,17 @@ function isFenceError(error) {
 var RoutingSandboxSession = class {
   deps;
   maxFenceRetries;
-  // The per-epoch resolved-backend cache. Keyed by activeEpoch: a swap bumps the
-  // epoch, invalidating the cache so the NEXT op re-resolves the new backend.
+  // The resolved-backend cache. Keyed by the FULL pointer tuple
+  // `(activeEpoch, activeSandboxId)` — NOT the epoch alone. A swap bumps the epoch,
+  // but a pointer can also change its target id WITHOUT an epoch bump: the
+  // `sessions.active_sandbox_id` FK is `ON DELETE SET NULL`, so a cascade that
+  // deletes the pointed-at sandbox row nulls the id at the SAME epoch. Keying on the
+  // epoch alone would then keep serving the deleted/stale backend for that epoch
+  // (issue #341 §5.2 — a swap-free route to the Shape-3 symptom). Keying on the tuple
+  // makes any target change — epoch-bumped OR not — invalidate the cache so the next
+  // op re-resolves (and, for a null id, re-resolves the session HOME).
   cachedEpoch;
+  cachedSandboxId;
   cached;
   // The last-resolved backend, exposed via the `state` getter (a method-free read
   // of the active backend's `state`). Updated on every resolve.
@@ -3079,12 +4608,18 @@ var RoutingSandboxSession = class {
    */
   async resolve() {
     const pointer = await this.deps.readPointer();
-    if (this.cachedEpoch === pointer.activeEpoch && this.cached) {
+    if (this.cachedEpoch === pointer.activeEpoch && this.cachedSandboxId === pointer.activeSandboxId && this.cached) {
       return this.cached;
     }
     const fromEpoch = this.cachedEpoch ?? pointer.activeEpoch;
     const resolved = await this.deps.resolveActiveBackend(pointer);
+    if (resolved.session === this) {
+      throw new Error(
+        "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."
+      );
+    }
     this.cachedEpoch = pointer.activeEpoch;
+    this.cachedSandboxId = pointer.activeSandboxId;
     this.cached = resolved;
     this.lastResolved = resolved;
     this.deps.onTransition?.({
@@ -3120,6 +4655,7 @@ var RoutingSandboxSession = class {
         }
         lastError = error;
         this.cachedEpoch = void 0;
+        this.cachedSandboxId = void 0;
         this.cached = void 0;
         this.deps.onTransition?.({
           type: "fenced-retry",
@@ -3133,6 +4669,30 @@ var RoutingSandboxSession = class {
     }
     throw lastError ?? new Error(`routing op "${op}" exhausted fence retries`);
   }
+  /**
+   * The failure-visibility boundary for the `exec_command` SDK capability tool — the
+   * dominant fault surface, and the one whose thrown `SelfhostedControlError` reaches
+   * the model wrapped by the SDK's generic tool-error function as
+   * "…Please try again. Error: …" — actively wrong for a machine that is offline, a
+   * consent that is not granted, or an oversized reply. Since the SDK closure-captures
+   * its `errorFunction` (there is no seam to attach one to its internally-built tools),
+   * we render the fault into the doctrine's four fields HERE and return it as the
+   * tool's string result — legible, in-band, and free of the misleading wrapper.
+   * (`apply_patch` already surfaces `error.message` via the SDK's own catch; the
+   * skills / `view_image` tools consume their session methods internally, so they are
+   * rendered elsewhere or left to their own SDK renderers — not this string boundary.)
+   *
+   * A FENCE error is re-thrown, NEVER rendered: `dispatch` already retries it against
+   * a re-resolved backend, and a fence that escapes retries is a routing condition the
+   * turn handles, not a model-facing fault. Any non-selfhosted error (a Modal fault, a
+   * `RoutingUnsupportedError`) is re-thrown unchanged.
+   */
+  renderSelfhostedFaultOrThrow(error) {
+    if (error instanceof SelfhostedControlError && !error.fenced) {
+      return renderSelfhostedFault(error);
+    }
+    throw error;
+  }
   // ── The forwarded structural surface ──────────────────────────────────────
   // Every method is PRESENT on the proxy (the SDK binds presence once) and
   // dispatches to the active backend at call-time. A missing backend method
@@ -3149,16 +4709,20 @@ var RoutingSandboxSession = class {
     });
   }
   async execCommand(args) {
-    return this.dispatch("execCommand", async (s) => {
-      if (s.execCommand) {
-        return s.execCommand(args);
-      }
-      if (s.exec) {
-        const r = await s.exec(args);
-        return r.stdout ?? r.output ?? "";
-      }
-      throw new RoutingUnsupportedError("execCommand", this.cached?.kind ?? "unknown");
-    });
+    try {
+      return await this.dispatch("execCommand", async (s) => {
+        if (s.execCommand) {
+          return s.execCommand(args);
+        }
+        if (s.exec) {
+          const r = await s.exec(args);
+          return r.stdout ?? r.output ?? "";
+        }
+        throw new RoutingUnsupportedError("execCommand", this.cached?.kind ?? "unknown");
+      });
+    } catch (error) {
+      return this.renderSelfhostedFaultOrThrow(error);
+    }
   }
   async writeStdin(args) {
     return this.dispatch("writeStdin", async (s) => {
@@ -3225,12 +4789,34 @@ var RoutingSandboxSession = class {
     const s = (this.lastResolved ?? this.deps.defaultResolved)?.session;
     return Boolean(s?.supportsPty?.());
   }
-  /** createEditor is a synchronous factory in the SDK surface; it binds to the
-   *  last-resolved backend's editor (or the default backend before the first op).
-   *  Returns undefined when the active backend has no editor (channel-a falls back
-   *  to its exec-based write path). */
+  /** createEditor is a synchronous factory in the SDK surface. The SDK's filesystem
+   *  capability calls it ONCE at tool-BIND time — `FilesystemCapability.tools()`,
+   *  every turn, before any tool runs — and throws "Filesystem sandbox sessions must
+   *  provide createEditor()" if it returns falsy. When a backend is already resolved
+   *  (eager/selfhosted routing) we bind to its editor directly, byte-for-byte as
+   *  before. But under LAZY provisioning the backend is not established yet
+   *  (defaultResolved is the synthetic unprovisioned session with no editor), so a
+   *  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. */
   createEditor(runAs) {
-    return (this.lastResolved ?? this.deps.defaultResolved)?.session.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 editor = s.createEditor?.(runAs);
+      if (!editor?.[name]) {
+        throw new RoutingUnsupportedError(`editor.${name}`, this.cached?.kind ?? "unknown");
+      }
+      return editor[name](operation, context);
+    });
+    return {
+      createFile: op("createFile"),
+      updateFile: op("updateFile"),
+      deleteFile: op("deleteFile")
+    };
   }
   async resolveExposedPort(port) {
     return this.dispatch("resolveExposedPort", async (s) => {
@@ -3260,27 +4846,61 @@ var RoutingSandboxSession = class {
 // src/sandbox/routing/backend-resolver.ts
 var ActiveBackendUnresolvableError = class extends Error {
   name = "ActiveBackendUnresolvableError";
-  constructor(message) {
+  code;
+  constructor(code, message) {
     super(message);
+    this.code = code;
   }
 };
+function swapTargetEstablishability(target) {
+  if (target.isSessionGroup) {
+    return { ok: true };
+  }
+  if (target.kind === "selfhosted") {
+    return { ok: true };
+  }
+  if (target.kind === "modal") {
+    return {
+      ok: false,
+      code: "unsupported_backend_context",
+      reason: "a Modal sandbox other than this session's own box cannot be established by a turn yet; swap back to the session default or attach a Connected Machine"
+    };
+  }
+  return {
+    ok: false,
+    code: "unsupported_backend_context",
+    reason: `a sandbox of kind "${target.kind}" cannot be established by a turn`
+  };
+}
 function makeActiveBackendResolver(deps) {
   return async (pointer) => {
     if (pointer.activeSandboxId === null) {
+      if (deps.defaultIsHome === false) {
+        throw new ActiveBackendUnresolvableError(
+          "home_unavailable_this_turn",
+          "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"
+        );
+      }
       return { session: deps.defaultBackend, sandboxId: null, kind: deps.defaultKind };
     }
     if (deps.pinnedSelfhosted && pointer.activeSandboxId === deps.pinnedSelfhosted.sandboxId && pointer.activeEpoch === deps.pinnedSelfhosted.epoch) {
-      return { session: deps.pinnedSelfhosted.session, sandboxId: pointer.activeSandboxId, kind: "selfhosted" };
+      return {
+        session: deps.pinnedSelfhosted.session,
+        sandboxId: pointer.activeSandboxId,
+        kind: "selfhosted"
+      };
     }
     const sandbox = await deps.getSandbox(pointer.activeSandboxId);
     if (!sandbox) {
       throw new ActiveBackendUnresolvableError(
+        "stale_pointer",
         `active sandbox ${pointer.activeSandboxId} not found in workspace ${deps.workspaceId}`
       );
     }
     if (sandbox.kind === "selfhosted") {
       if (!sandbox.enrollmentId) {
         throw new ActiveBackendUnresolvableError(
+          "offline_enrollment",
           `selfhosted sandbox ${sandbox.id} has no enrollment (agent id) to address`
         );
       }
@@ -3291,6 +4911,8 @@ function makeActiveBackendResolver(deps) {
         agentId: sandbox.enrollmentId,
         epoch: pointer.activeEpoch,
         ...deps.selfhostedTimeoutMs !== void 0 ? { timeoutMs: deps.selfhostedTimeoutMs } : {},
+        ...deps.selfhostedExecTimeoutMs !== void 0 ? { execTimeoutMs: deps.selfhostedExecTimeoutMs } : {},
+        ...deps.selfhostedOnOp !== void 0 ? { onOp: deps.selfhostedOnOp } : {},
         // The turn's declared environment → the session's manifest.environment, so
         // the SDK's per-turn manifest-env delta is empty (no "cannot change manifest
         // environment variables" throw on a pin-to-vm turn).
@@ -3299,11 +4921,16 @@ function makeActiveBackendResolver(deps) {
         // for this selfhosted backend. Absent/empty ⇒ the default workspace_root.
         ...pointer.workingDir ? { workingDir: pointer.workingDir } : {}
       });
-      return { session, sandboxId: sandbox.id, kind: "selfhosted" };
+      return {
+        session,
+        sandboxId: sandbox.id,
+        kind: "selfhosted"
+      };
     }
     if (sandbox.kind === "modal") {
       if (!deps.establishModalTarget) {
         throw new ActiveBackendUnresolvableError(
+          "unsupported_backend_context",
           `modal swap target ${sandbox.id} cannot be established in this context (no establisher wired)`
         );
       }
@@ -3311,6 +4938,7 @@ function makeActiveBackendResolver(deps) {
       return { session, sandboxId: sandbox.id, kind: "modal" };
     }
     throw new ActiveBackendUnresolvableError(
+      "unsupported_backend_context",
       `unsupported swap target kind "${sandbox.kind}" for sandbox ${sandbox.id}`
     );
   };
@@ -3318,7 +4946,11 @@ function makeActiveBackendResolver(deps) {
 
 // src/sandbox/index.ts
 function createSandboxClient(settings, environment = collectSandboxEnvironment(settings)) {
-  return createSandboxClientForBackend(settings.sandboxBackend, settings, environment);
+  return createSandboxClientForBackend(
+    settings.sandboxBackend,
+    settings,
+    environment
+  );
 }
 function createSandboxClientForBackend(backend, settings, environment = collectSandboxEnvironment(settings)) {
   const registration = PROVIDER_REGISTRY[backend];
@@ -3355,13 +4987,25 @@ function withDockerNetwork(client, network) {
   return {
     backendId: client.backendId,
     ...client.supportsDefaultOptions !== void 0 ? { supportsDefaultOptions: client.supportsDefaultOptions } : {},
-    ...client.create ? { create: async (...args) => await wrapSession(await client.create(...args)) } : {},
-    ...client.resume ? { resume: async (state) => await wrapSession(await client.resume(state)) } : {},
+    ...client.create ? {
+      create: async (...args) => await wrapSession(await client.create(...args))
+    } : {},
+    ...client.resume ? {
+      resume: async (state) => await wrapSession(await client.resume(state))
+    } : {},
     ...client.delete ? { delete: async (state) => await client.delete(state) } : {},
-    ...client.serializeSessionState ? { serializeSessionState: async (state, options) => await client.serializeSessionState(state, options) } : {},
-    ...client.canPersistOwnedSessionState ? { canPersistOwnedSessionState: async (state) => await client.canPersistOwnedSessionState(state) } : {},
-    ...client.canReusePreservedOwnedSession ? { canReusePreservedOwnedSession: async (state) => await client.canReusePreservedOwnedSession(state) } : {},
-    ...client.deserializeSessionState ? { deserializeSessionState: async (state) => await client.deserializeSessionState(state) } : {}
+    ...client.serializeSessionState ? {
+      serializeSessionState: async (state, options) => await client.serializeSessionState(state, options)
+    } : {},
+    ...client.canPersistOwnedSessionState ? {
+      canPersistOwnedSessionState: async (state) => await client.canPersistOwnedSessionState(state)
+    } : {},
+    ...client.canReusePreservedOwnedSession ? {
+      canReusePreservedOwnedSession: async (state) => await client.canReusePreservedOwnedSession(state)
+    } : {},
+    ...client.deserializeSessionState ? {
+      deserializeSessionState: async (state) => await client.deserializeSessionState(state)
+    } : {}
   };
 }
 async function connectDockerNetwork(network, containerId) {
@@ -3376,7 +5020,9 @@ async function connectDockerNetwork(network, containerId) {
   if (stderr.includes("already exists")) {
     return;
   }
-  throw new Error(`Failed to connect Docker sandbox container to network ${network}: ${stderr.trim()}`);
+  throw new Error(
+    `Failed to connect Docker sandbox container to network ${network}: ${stderr.trim()}`
+  );
 }
 function sandboxStateEntryFromRunState(state) {
   const sandboxState = state?._sandbox;
@@ -3417,6 +5063,20 @@ 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"
@@ -3472,7 +5132,9 @@ async function deserializeSandboxSessionStateEnvelope(client, envelope) {
     return void 0;
   }
   if (!client.deserializeSessionState) {
-    throw new Error("Sandbox client must implement deserializeSessionState() to resume RunState sandbox state");
+    throw new Error(
+      "Sandbox client must implement deserializeSessionState() to resume RunState sandbox state"
+    );
   }
   const state = envelope;
   return await client.deserializeSessionState({
@@ -3521,7 +5183,7 @@ function isProviderSandboxNotFoundError(backendId, error) {
 }
 function readInstanceId(session) {
   const state = session.state ?? {};
-  const candidate = state.sandboxId ?? state.instanceId ?? state.id ?? state.hostId ?? state.containerId;
+  const candidate = state.sandboxId ?? state.instanceId ?? state.id ?? state.hostId ?? state.containerId ?? state.workspaceRootPath;
   return typeof candidate === "string" && candidate.length > 0 ? candidate : "";
 }
 async function terminateCreatedSandbox(client, session, sessionState) {
@@ -3545,15 +5207,19 @@ async function establishSandboxSessionFromEnvelope(settings, envelope, opts) {
   const environment = opts.environment ?? collectSandboxEnvironment(settings);
   const client = createSandboxClientForBackend(backend, settings, environment);
   if (!client) {
-    throw new SandboxConfigError(backend, `Cannot establish a sandbox session for backend "${backend}" (no client; sandboxBackend=none?)`);
+    throw new SandboxConfigError(
+      backend,
+      `Cannot establish a sandbox session for backend "${backend}" (no client; sandboxBackend=none?)`
+    );
   }
-  if (!client.create) {
+  if (opts.recovery === "create-or-restore" && !client.create) {
     throw new SandboxConfigError(backend, `Sandbox backend "${backend}" does not support create()`);
   }
   const createManifest = { environment };
   const envelopeSessionState = envelope && typeof envelope === "object" ? envelope.sessionState : void 0;
-  const workspaceArchive = readWorkspaceArchiveFromEnvelopeSessionState(envelopeSessionState);
-  const coldRestore = async (resumeFallbackState) => {
+  const workspaceArchives = readWorkspaceArchivePairFromEnvelopeSessionState(envelopeSessionState);
+  const workspaceArchive = workspaceArchives.current;
+  const coldRestore = async (resumeFallbackState, skipWorkspaceHydrate = false) => {
     const createStarted = Date.now();
     let restored;
     try {
@@ -3579,15 +5245,37 @@ async function establishSandboxSessionFromEnvelope(settings, envelope, opts) {
         throw createCallbackError;
       }
     }
-    if (workspaceArchive) {
+    let hydrationApplied = false;
+    if (!skipWorkspaceHydrate && (workspaceArchive || workspaceArchives.previous)) {
       const hydrate = restored.hydrateWorkspace;
       if (typeof hydrate === "function") {
-        try {
-          await hydrate.call(restored, workspaceArchive);
-        } catch (hydrateError) {
+        let hydrated = false;
+        for (const candidate of [
+          { archive: workspaceArchive, label: "current" },
+          { archive: workspaceArchives.previous, label: "previous" }
+        ]) {
+          if (!candidate.archive) {
+            continue;
+          }
+          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
+            );
+          }
+        }
+        if (!hydrated) {
           await terminateCreatedSandbox(client, restored, restoredState);
-          throw hydrateError;
+          return await coldRestore(resumeFallbackState, true);
         }
+        hydrationApplied = true;
         const hydratedState = restored.state;
         const hydratedInstanceId = readInstanceId(restored);
         if (hydratedInstanceId && hydratedInstanceId !== established.instanceId) {
@@ -3615,32 +5303,57 @@ async function establishSandboxSessionFromEnvelope(settings, envelope, opts) {
       session: restored,
       sessionState: restoredState ?? resumeFallbackState,
       instanceId: readInstanceId(restored),
-      backendId: client.backendId
+      backendId: client.backendId,
+      origin: hydrationApplied ? "restored" : "created"
     };
   };
   const envelopeProviderState = envelopeSessionState && typeof envelopeSessionState === "object" ? envelopeSessionState.providerState : void 0;
   const hasResumableInstance = Boolean(
-    envelopeProviderState && typeof envelopeProviderState === "object" && (envelopeProviderState.sandboxId || envelopeProviderState.instanceId || envelopeProviderState.id || envelopeProviderState.containerId)
+    envelopeProviderState && typeof envelopeProviderState === "object" && (envelopeProviderState.sandboxId || envelopeProviderState.instanceId || envelopeProviderState.id || envelopeProviderState.containerId || envelopeProviderState.workspaceRootPath)
   );
   if (hasResumableInstance && envelopeSessionState && client.resume && client.deserializeSessionState) {
     let resumedState;
     try {
-      resumedState = await deserializeSandboxSessionStateEnvelope(client, envelopeSessionState);
+      resumedState = await deserializeSandboxSessionStateEnvelope(
+        client,
+        envelopeSessionState
+      );
     } catch (error) {
-      throw new SandboxConfigError(backend, `Failed to deserialize sandbox resume envelope for backend "${backend}": ${error instanceof Error ? error.message : String(error)}`);
+      throw new SandboxConfigError(
+        backend,
+        `Failed to deserialize sandbox resume envelope for backend "${backend}": ${error instanceof Error ? error.message : String(error)}`
+      );
     }
     if (resumedState !== void 0) {
       try {
         const session = await client.resume(resumedState);
-        return { client, session, sessionState: resumedState, instanceId: readInstanceId(session), backendId: client.backendId };
+        return {
+          client,
+          session,
+          sessionState: resumedState,
+          instanceId: readInstanceId(session),
+          backendId: client.backendId,
+          origin: "resumed"
+        };
       } catch (error) {
-        if (!isProviderSandboxNotFoundError(client.backendId, error)) {
+        if (!isProviderSandboxNotFoundError(client.backendId, error) || opts.recovery === "resume-only") {
           throw error;
         }
-        return await coldRestore(resumedState);
+        const lostInstanceId = [
+          envelopeProviderState?.sandboxId,
+          envelopeProviderState?.instanceId,
+          envelopeProviderState?.id,
+          envelopeProviderState?.containerId,
+          envelopeProviderState?.workspaceRootPath
+        ].find((value) => typeof value === "string" && value.length > 0);
+        const restoredSession = await coldRestore(resumedState);
+        return lostInstanceId ? { ...restoredSession, lostInstanceId } : restoredSession;
       }
     }
   }
+  if (opts.recovery === "resume-only") {
+    throw new SandboxResumeStateUnavailableError(backend);
+  }
   return await coldRestore();
 }
 function recordSandboxCreateMetric(metrics, backend, outcome, startedMs) {
@@ -3683,6 +5396,7 @@ export {
   DESKTOP_STREAM_PORT,
   assertDescriptorRegistryInvariants,
   SandboxConfigError,
+  SandboxResumeStateUnavailableError,
   SandboxProviderUnavailableError,
   modalSandboxAttributionEnvironment,
   modalSandboxAttributionTags,
@@ -3693,11 +5407,45 @@ export {
   subjectFor,
   SelfhostedControlError,
   agentErrorToControlError,
+  payloadTooLargeMessage,
+  drainingMessage,
+  drainingExhaustedError,
+  execDeadlineHint,
+  NEVER_SENT_DETAIL_KEY,
   offlineAgentError,
   timeoutAgentError,
   NatsControlRpc,
   offlineControlResponse,
   timeoutControlResponse,
+  SELFHOSTED_IDEMPOTENT_READONLY_OPS,
+  SELFHOSTED_DRAINING_MAX_RETRIES,
+  SELFHOSTED_EXEC_DRAINING_MAX_RETRIES,
+  SELFHOSTED_TIMEOUT_MAX_RETRIES,
+  SELFHOSTED_NEVER_SENT_MAX_RETRIES,
+  SELFHOSTED_RETRY_BACKOFF_BASE_MS,
+  SELFHOSTED_RETRY_BACKOFF_FACTOR,
+  SELFHOSTED_RETRY_BACKOFF_CAP_MS,
+  selfhostedRetryBackoffMs,
+  decideSelfhostedRetry,
+  defaultSelfhostedRetryClock,
+  selfhostedFaultClass,
+  SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES,
+  FAULT_FIELD_WHAT_HAPPENED,
+  FAULT_FIELD_WHICH_LAYER,
+  FAULT_FIELD_WHAT_PRESERVED,
+  FAULT_FIELD_WHAT_TO_TRY,
+  renderSelfhostedFault,
+  sanitizeOpIdToken,
+  runWithToolCallCorrelation,
+  nextDurableOpId,
+  opFrameSubject,
+  opAckSubject,
+  OpStreamUnavailableError,
+  NatsOpStreamTransport,
+  OP_STREAM_DEFAULT_WINDOW_BYTES,
+  OP_STREAM_ACK_INTERVAL_MS,
+  OP_STREAM_SILENCE_TIMEOUT_MS,
+  OP_STREAM_RECONNECT_HOLD_MS,
   setSelfhostedApplyDiff,
   SELFHOSTED_DEFAULT_TIMEOUT_MS,
   SELFHOSTED_RELAY_STREAM_PATH,
@@ -3739,13 +5487,15 @@ export {
   RecordingError,
   startRecording,
   stopRecording,
-  readRecordingBytes,
+  inspectRecordingArtifact,
+  uploadRecordingArtifact,
   deleteRecordingArtifacts,
   recordingStorageKey,
   ChannelAValidationError,
   ChannelAConflictError,
   ChannelANotFoundError,
   ChannelAUnsupportedError,
+  REPOSITORY_DISCOVERY_LIMIT,
   SandboxChannelAService,
   stripExecBanner2 as stripExecBanner,
   isWorkspaceEscapeError,
@@ -3762,6 +5512,7 @@ export {
   RoutingUnsupportedError,
   RoutingSandboxSession,
   ActiveBackendUnresolvableError,
+  swapTargetEstablishability,
   makeActiveBackendResolver,
   createSandboxClient,
   createSandboxClientForBackend,
@@ -3777,4 +5528,4 @@ export {
   collectSandboxEnvironment2 as collectSandboxEnvironment,
   parseExposedPorts2 as parseExposedPorts
 };
-//# sourceMappingURL=chunk-DYBF7ZEB.js.map
+//# sourceMappingURL=chunk-RYDCVTMW.js.map