@opengeni/runtime 0.6.0 → 0.7.0

package/src/sandbox/recording.ts

@@ -1,6 +1,6 @@
 // @opengeni/runtime/sandbox — the recording loop (P4.3).
 //
-// ffmpeg x11grab on :0 → mp4/webm artifact on the box → read bytes → PUT to
+// ffmpeg x11grab on :0 → mp4/webm artifact on the box → direct scoped PUT to
 // object storage → recording.available. The "agent films itself proving the fix"
 // loop: ffmpeg reads exactly the :0 framebuffer the agent's computer-use draws to
 // and the human watches over Channel B (zero projection).
@@ -9,22 +9,16 @@
 // Temporal, NO worker RPC, NO actor. They live in the agent-loop-free leaf so the
 // SAME process that already holds the resumed-by-id box (the agent turn's own
 // activity for an on-turn recording, or the API in-process for an off-turn/manual
-// finalize) reads the bytes and PUTs them straight to storage. The bytes go
-// box → process memory → storage PUT and are NEVER serialized as a Temporal
-// activity result — the 256 MB-vs-payload-limit concern dissolves (F10).
+// finalize) authorizes a direct box-to-storage upload. Recording bytes never
+// enter worker memory or a Temporal payload (F10).
 //
 // ── Adversarial-review fixes folded in (module 05 §Adversarial) ──────────────
 //   F1  exec is OPTIONAL on Modal (only execCommand) — every command dual-paths.
-//   F3  exec/execCommand YIELDS — the SIGINT-and-wait loop is bounded well under
-//       the yield window; a direct `base64` exec does the byte transfer.
-//   F8  the byte read does NOT assume any over-limit behavior — we cap the ffmpeg
-//       file by size on the box first (stat) and fail `max-bytes-exceeded` rather
-//       than silently uploading a truncated video.
-//   FR  the byte transfer is a DIRECT exec (`base64 <abs-path>`), NOT readFile:
-//       the recording lives at an absolute /tmp path (never the user's workspace
-//       /git tree), and readFile rejects paths outside the manifest workspace
-//       root ("escapes the workspace root"). The base64 exec passes
-//       maxOutputTokens:null so a large recording is never truncated.
+//   F3  exec/execCommand YIELDS — the stop and direct-upload commands are bounded.
+//   F8  size is gated on the box first (stat); over-limit artifacts fail instead
+//       of being uploaded partially.
+//   FR  curl reads the absolute /tmp artifact in the box and sends it directly to
+//       the short-lived scoped URL. No workspace-root read API is involved.
 //   F9  the box file is deleted ONLY after the storage PUT confirms — never
 //       before (so a failed upload leaves the bytes recoverable for a retry).
 //   F12 ffmpeg/x11vnc backgrounding does not block the yield (nohup … & echo $!).
@@ -54,24 +48,44 @@ export function extForCodec(codec: RecordingCodec): string {
 
 /** No exec/execCommand on the session — the box cannot run ffmpeg. */
 export class RecordingUnavailableError extends Error {
-  constructor(message: string) { super(message); this.name = "RecordingUnavailableError"; }
+  constructor(message: string) {
+    super(message);
+    this.name = "RecordingUnavailableError";
+  }
 }
-/** ffmpeg failed, the file is missing, or the byte read failed. */
+/** ffmpeg failed, the file is missing, or the artifact is over its size limit. */
 export class RecordingError extends Error {
-  constructor(message: string, readonly reason: "ffmpeg-error" | "box-death" | "max-bytes-exceeded" | "display-unavailable") {
+  constructor(
+    message: string,
+    readonly reason: "ffmpeg-error" | "box-death" | "max-bytes-exceeded" | "display-unavailable",
+  ) {
     super(message);
     this.name = "RecordingError";
   }
 }
 
 // The structural slice of a provider session the recording loop drives. exec and
-// execCommand are optional (Modal has only execCommand — F1); readFile present on
-// every desktop-capable provider.
-type ExecResultLike = { output?: string; stdout?: string; stderr?: string; exitCode?: number | null; sessionId?: number };
+// execCommand are optional (Modal has only execCommand — F1).
+type ExecResultLike = {
+  output?: string;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  sessionId?: number;
+};
 type RecordingSession = {
-  exec?: (args: { cmd: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number }) => Promise<ExecResultLike>;
-  execCommand?: (args: { cmd: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number }) => Promise<string>;
-  readFile?: (args: { path: string; runAs?: string; maxBytes?: number }) => Promise<string | Uint8Array>;
+  exec?: (args: {
+    cmd: string;
+    runAs?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  }) => Promise<ExecResultLike>;
+  execCommand?: (args: {
+    cmd: string;
+    runAs?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  }) => Promise<string>;
 };
 
 function shq(s: string): string {
@@ -80,11 +94,12 @@ function shq(s: string): string {
 
 function resultOutput(result: ExecResultLike | string): string {
   if (typeof result === "string") return result;
-  return [result.output, result.stderr, result.stdout].filter((v): v is string => typeof v === "string" && v.length > 0).join("\n");
+  return [result.output, result.stderr, result.stdout]
+    .filter((v): v is string => typeof v === "string" && v.length > 0)
+    .join("\n");
 }
 
-// Default per-command output cap (tokens). The byte-read path overrides this to
-// `null` (no truncation) so a base64-encoded recording is never clipped.
+// Default per-command output cap (tokens). Recording transfer does not use stdout.
 const DEFAULT_MAX_OUTPUT_TOKENS = 4_000;
 
 async function run(
@@ -92,20 +107,23 @@ async function run(
   cmd: string,
   runAs?: string,
   yieldTimeMs = EXEC_YIELD_MS,
-  maxOutputTokens: number | null = DEFAULT_MAX_OUTPUT_TOKENS,
+  maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS,
 ): Promise<string> {
-  // `maxOutputTokens: null` disables the provider's output truncation entirely
-  // (SDK truncateOutput returns the raw text when the cap is nullish).
-  const args = { cmd, ...(runAs ? { runAs } : {}), yieldTimeMs, maxOutputTokens } as {
-    cmd: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number;
-  };
+  const args: {
+    cmd: string;
+    runAs?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  } = { cmd, ...(runAs ? { runAs } : {}), yieldTimeMs, maxOutputTokens };
   if (typeof session.exec === "function") {
     return resultOutput(await session.exec(args));
   }
   if (typeof session.execCommand === "function") {
     return resultOutput(await session.execCommand(args));
   }
-  throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) — recording unavailable");
+  throw new RecordingUnavailableError(
+    "session cannot run commands (no exec/execCommand) — recording unavailable",
+  );
 }
 
 // Extract the command body from a provider exec banner. Modal's execCommand
@@ -149,7 +167,10 @@ export type RecordingProcess = {
  * block on the recording). A hard `-t <maxSeconds>` ceiling bounds a runaway file
  * across a multi-day turn. Returns the handle the caller carries to stop+finalize.
  */
-export async function startRecording(session: unknown, input: StartRecordingInput): Promise<RecordingProcess> {
+export async function startRecording(
+  session: unknown,
+  input: StartRecordingInput,
+): Promise<RecordingProcess> {
   const s = session as RecordingSession;
   const codec = input.codec ?? "h264-mp4";
   const dimensions = input.dimensions ?? DEFAULT_DIMENSIONS;
@@ -162,9 +183,10 @@ export async function startRecording(session: unknown, input: StartRecordingInpu
   const pidFile = `${tmp}/og-rec-${input.recordingId}.pid`;
   const logFile = `${tmp}/og-rec-${input.recordingId}.log`;
   const [w, h] = dimensions;
-  const enc = codec === "vp9-webm"
-    ? `-c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1`
-    : `-c:v libx264 -preset veryfast -pix_fmt yuv420p -movflags +faststart`;
+  const enc =
+    codec === "vp9-webm"
+      ? `-c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1`
+      : `-c:v libx264 -preset veryfast -pix_fmt yuv420p -movflags +faststart`;
   const ffmpeg =
     `nohup ffmpeg -hide_banner -loglevel error -f x11grab -draw_mouse 1 -framerate ${framerate} ` +
     `-video_size ${w}x${h} -i ${display}.0 -t ${maxSeconds} ${enc} ${boxPath} ` +
@@ -194,45 +216,41 @@ export async function stopRecording(session: unknown, proc: RecordingProcess): P
   await run(s, `bash -lc ${shq(wait)}`, proc.runAs, STOP_YIELD_MS).catch(() => undefined);
 }
 
-export type FinalizeRecordingResult = {
-  bytes: Uint8Array;
+export type RecordingArtifactMetadata = {
   contentType: RecordingContentType;
   sizeBytes: number;
   durationSeconds: number;
 };
 
 /**
- * Read the finalized recording bytes off the box.
- *
- * TRANSPORT: the bytes are read via a DIRECT exec (`base64 <path>` over stdout),
- * NOT via session.readFile(). The recording artifact lives at an absolute /tmp
- * path on purpose — recordings must never be written inside the user's workspace
- * /git tree — but session.readFile() resolves every path against the manifest
- * workspace root and rejects anything outside it ("Sandbox path … escapes the
- * workspace root"), which fataled finalize. Raw exec runs unrestricted shell, so
- * `base64` reads the /tmp file directly; we decode the base64 back to bytes here.
- * The byte-read exec passes `maxOutputTokens: null` so the provider never
- * truncates a large recording's base64.
- *
- * F8: we DO NOT assume any over-limit behavior. First `stat` the file size on the
- * box; if it exceeds maxBytes, fail `max-bytes-exceeded` (never upload a truncated
- * video). Otherwise read the raw bytes.
- *
- * F9: this does NOT delete the box file. The caller deletes it (deleteRecordingArtifacts)
- * ONLY after the storage PUT + `available` commit — so a failed upload leaves the
- * bytes recoverable on the box for a retry.
- *
- * F14: duration is wall-clock (now − startedAt), a close approximation of the
- * SIGINT-flushed video length.
+ * Inspect and size-gate the finalized recording while it is still on the box.
+ * No recording bytes cross into the worker process.
  */
-export async function readRecordingBytes(session: unknown, proc: RecordingProcess, maxBytes = DEFAULT_MAX_BYTES): Promise<FinalizeRecordingResult> {
+export async function inspectRecordingArtifact(
+  session: unknown,
+  proc: RecordingProcess,
+  maxBytes = DEFAULT_MAX_BYTES,
+): Promise<RecordingArtifactMetadata> {
   const s = session as RecordingSession;
   if (typeof s.exec !== "function" && typeof s.execCommand !== "function") {
-    throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) — recording finalize unavailable");
+    throw new RecordingUnavailableError(
+      "session cannot run commands (no exec/execCommand) — recording finalize unavailable",
+    );
   }
-  // F8: size-gate on the box before reading into memory.
-  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";
+  // F8: size-gate on the box before authorizing the upload.
+  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");
   }
@@ -243,44 +261,82 @@ export async function readRecordingBytes(session: unknown, proc: RecordingProces
   if (size > maxBytes) {
     throw new RecordingError(`recording ${size}B exceeds max ${maxBytes}B`, "max-bytes-exceeded");
   }
-  // Read the bytes via a DIRECT exec (base64, no output truncation), so the
-  // absolute /tmp path is NOT run through the workspace-root-scoped readFile guard.
-  const STOP_YIELD = 60_000; // a large recording's base64 read may take longer than the default exec yield.
-  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: Uint8Array;
-  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) / 1000)),
   };
 }
 
+const RECORDING_UPLOAD_OK = "OPENGENI_RECORDING_UPLOAD_OK";
+const RECORDING_UPLOAD_MAX_SECONDS = 300;
+
+/**
+ * Upload the finalized artifact directly from the sandbox to a scoped object-
+ * storage URL. The worker carries only the short URL/headers and metadata; it
+ * never materializes a base64 string or Uint8Array for a recording that may be
+ * hundreds of megabytes. curl's success marker makes an exec transport that
+ * returns non-zero command output instead of throwing still fail closed.
+ */
+export async function uploadRecordingArtifact(
+  session: unknown,
+  proc: RecordingProcess,
+  input: {
+    url: string;
+    requiredHeaders: Record<string, string>;
+    maxBytes?: number;
+    maxSeconds?: number;
+  },
+): Promise<RecordingArtifactMetadata> {
+  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 as RecordingSession,
+      `bash -lc ${shq(upload)}`,
+      proc.runAs,
+      (maxSeconds + 10) * 1_000,
+    ),
+  );
+  if (!output.includes(RECORDING_UPLOAD_OK)) {
+    throw new Error("recording upload did not confirm success");
+  }
+  return metadata;
+}
+
 /**
  * Delete the box artifacts. F9: call this ONLY after the storage PUT confirmed
  * and the `available` row committed — never before. Best-effort; never throws.
  */
-export async function deleteRecordingArtifacts(session: unknown, proc: RecordingProcess): Promise<void> {
+export async function deleteRecordingArtifacts(
+  session: unknown,
+  proc: RecordingProcess,
+): Promise<void> {
   const s = session as RecordingSession;
   const logFile = proc.boxPath.replace(/\.(mp4|webm)$/, ".log");
-  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(() => undefined);
+  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(
+    () => undefined,
+  );
 }
 
 /** The storage object key for a recording artifact (parallels the file-asset layout). */
-export function recordingStorageKey(workspaceId: string, sessionId: string, recordingId: string, codec: RecordingCodec): string {
+export function recordingStorageKey(
+  workspaceId: string,
+  sessionId: string,
+  recordingId: string,
+  codec: RecordingCodec,
+): string {
   return `recordings/${workspaceId}/${sessionId}/${recordingId}.${extForCodec(codec)}`;
 }

package/src/sandbox/routing/backend-resolver.ts

@@ -19,6 +19,7 @@
 // API/worker pass a resume-by-id closure for the sibling box's lease).
 
 import { buildSelfhostedBackendSession, type SelfhostedRelayConfig } from "../selfhosted/session";
+import type { SelfhostedOpObserver } from "../selfhosted/op-observer";
 import type { ControlRpc } from "../selfhosted/control-rpc";
 import type {
   ActivePointer,
@@ -60,8 +61,16 @@ export interface ActiveBackendResolverDeps {
    *  absent, a modal swap target surfaces as unsupported (the caller validated
    *  liveness, so this is the "modal swap not wired in this context" guard). */
   establishModalTarget?: (sandbox: RoutableSandbox) => Promise<RoutableBackendSession>;
-  /** Override the selfhosted control-op timeout (tests). */
+  /** The selfhosted CONTROL-op timeout (ping/fs/desktop/pty) for a swap/pin target.
+   *  Absent ⇒ the session's 30s default. */
   selfhostedTimeoutMs?: number;
+  /** The selfhosted EXEC process deadline for a swap/pin target, distinct from the
+   *  control timeout (a swapped-to machine runs real commands too). Absent ⇒ falls
+   *  back to the control timeout, as in the session leaf. */
+  selfhostedExecTimeoutMs?: number;
+  /** The per-op observer threaded into a selfhosted swap/pin target (out-of-band
+   *  telemetry — metrics + machine.* events). Absent ⇒ no-op. */
+  selfhostedOnOp?: SelfhostedOpObserver;
   /**
    * The run's declared sandbox environment — the SAME `Record<string,string>` the
    * worker turn threads into the agent's TARGET manifest (and into the group box at
@@ -86,15 +95,104 @@ export interface ActiveBackendResolverDeps {
    * path (which always builds fresh — it has no pre-established turn session).
    */
   pinnedSelfhosted?: { sandboxId: string; epoch: number; session: RoutableBackendSession };
+  /**
+   * Whether `defaultBackend` IS the session's home box — i.e. whether the null pointer
+   * (== home) may resolve to it. Defaults to TRUE (omitted): a genuine machine-HOME turn
+   * (home IS the machine) and a Modal-home turn established on its group box both pass/omit
+   * true, so null resolves to `defaultBackend` as before. Set explicitly FALSE only for a
+   * machine-primary turn of a Modal-HOME session (pinned to a machine, group box never
+   * established this turn): the null pointer then has nothing to resolve to THIS turn, so
+   * rather than silently keep serving the pinned machine as if the detach never happened,
+   * the null branch throws a typed `home_unavailable_this_turn` error — the detach's pointer
+   * commit stands and takes effect on the NEXT turn, which starts null and establishes the
+   * home box normally. Lazily establishing the home box mid-turn on such a clear is a
+   * deferred follow-up (issue #341); until then this makes the gap fail typed-and-specific,
+   * never silent.
+   */
+  defaultIsHome?: boolean;
 }
 
+/** Why a persisted pointer / swap target cannot be turned into a live backend. A
+ *  typed discriminant so callers (turn-start reconcile, the swap tool, future
+ *  reports) can distinguish a stale pointer from an unaddressable enrollment from a
+ *  backend the turn context simply cannot establish — instead of string-matching
+ *  one opaque message (issue #341: "typed diagnostics that distinguish stale
+ *  pointer, offline enrollment, unsupported backend context, transient failure").
+ *   - `stale_pointer`               — the pointed-at sandbox row is gone (deleted/orphaned).
+ *   - `offline_enrollment`          — a selfhosted target carries no enrollment/agent id to address.
+ *   - `unsupported_backend_context` — a target no turn routing context can establish
+ *                                     (a non-group Modal sibling; an unknown kind).
+ *   - `transient_establishment`     — a momentary establish failure worth a retry (reserved;
+ *                                     control-plane timeouts surface as their own typed error).
+ *   - `home_unavailable_this_turn`  — the pointer was cleared to the session default (home)
+ *                                     mid-turn, but this turn started pinned to a machine and
+ *                                     never established the home box, so null has nothing to
+ *                                     resolve to THIS turn (the detach takes effect next turn). */
+export type BackendUnresolvableCode =
+  | "stale_pointer"
+  | "offline_enrollment"
+  | "unsupported_backend_context"
+  | "transient_establishment"
+  | "home_unavailable_this_turn";
+
 /** Thrown when a swap target cannot be resolved (unknown sandbox, or a modal
- *  target with no establisher in this context). The caller maps it to a 409. */
+ *  target with no establisher in this context). The caller maps it to a 409.
+ *  Carries a typed {@link BackendUnresolvableCode} in addition to the message. */
 export class ActiveBackendUnresolvableError extends Error {
   readonly name = "ActiveBackendUnresolvableError";
-  constructor(message: string) {
+  readonly code: BackendUnresolvableCode;
+  constructor(code: BackendUnresolvableCode, message: string) {
     super(message);
+    this.code = code;
+  }
+}
+
+/** The outcome of {@link swapTargetEstablishability}. */
+export type SwapTargetEstablishability =
+  | { ok: true }
+  | { ok: false; code: BackendUnresolvableCode; reason: string };
+
+/**
+ * THE SINGLE SOURCE OF TRUTH for "can a turn's routing context ESTABLISH this swap
+ * target?" — shared by swap/seed ADMISSION (`fleet.resolveTarget`, before the CAS
+ * pointer commit) and turn-time ESTABLISHMENT (this resolver + `wrapTurnBoxWithRouting`).
+ * Admission MUST reject any target this predicate calls unestablishable, so the
+ * pointer is never committed to a backend no turn can resume (issue #341 Shape 1:
+ * a Modal-sibling swap was admitted + epoch-bumped, then every following op
+ * stranded because no context wires an establisher for it).
+ *
+ *  - the session's OWN group box (`isSessionGroup`) is the null/home target and is
+ *    always establishable (it IS the default backend);
+ *  - a `selfhosted` machine target is establishable (`buildSelfhostedBackendSession`);
+ *    admission's separate liveness probe — not this predicate — gates online-ness;
+ *  - a NON-group `modal` target is NOT establishable: no turn context wires
+ *    `establishModalTarget` (cross-group Modal resume-by-id is a future, billing-
+ *    touching feature — sandbox-routing.ts). Wiring that establisher is the ONE
+ *    toggle that flips this branch; keep admission and the resolver in lockstep.
+ */
+export function swapTargetEstablishability(target: {
+  kind: string;
+  isSessionGroup: boolean;
+}): SwapTargetEstablishability {
+  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`,
+  };
 }
 
 /**
@@ -115,9 +213,29 @@ export function makeActiveBackendResolver(
   deps: ActiveBackendResolverDeps,
 ): (pointer: ActivePointer) => Promise<ResolvedActiveBackend> {
   return async (pointer: ActivePointer): Promise<ResolvedActiveBackend> => {
-    // The DEFAULT target: the session's own group sandbox (backward-compat). The
-    // proxy routes to the already-established box; the lease owns its lifecycle.
+    // NULL == the session's HOME backend (issue #341 invariant 1). `defaultBackend`
+    // is the already-established home the wiring handed us — the Modal group box for a
+    // Modal-home turn, or the machine itself for a machine-home turn. It is NEVER a
+    // swap target's SelfhostedSession: a clear-to-null must re-land on the home, never
+    // keep serving the machine a prior op swapped to. (The proxy caches by the FULL
+    // pointer tuple, so a clear-to-null — epoch-bumped OR a same-epoch FK null —
+    // invalidates the cached machine and re-enters this branch.) The lease owns the
+    // home box lifecycle; the proxy does not re-establish it.
     if (pointer.activeSandboxId === null) {
+      // A machine-pinned turn (Modal-home session pinned to a machine) never
+      // established its home box, so a mid-turn clear-to-null has no home to resolve
+      // THIS turn. Fail typed-and-specific — the detach was accepted and its pointer
+      // commit STANDS, taking effect on the next turn (which starts null and
+      // establishes the home box) — instead of silently serving the pinned machine as
+      // if the clear never happened. Only an EXPLICIT `false` throws; omitted (the
+      // common path) resolves to the home default as before. (Lazily establishing the
+      // home box mid-turn on such a clear is a deferred follow-up; issue #341.)
+      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 — this turn has no active home box",
+        );
+      }
       return { session: deps.defaultBackend, sandboxId: null, kind: deps.defaultKind };
     }
 
@@ -129,16 +247,21 @@ export function makeActiveBackendResolver(
     // to a fresh build fenced under the CURRENT epoch (the stale pinned instance is
     // fenced at the old epoch and must not be reused).
     if (
-      deps.pinnedSelfhosted
-      && pointer.activeSandboxId === deps.pinnedSelfhosted.sandboxId
-      && pointer.activeEpoch === deps.pinnedSelfhosted.epoch
+      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}`,
       );
     }
@@ -146,6 +269,7 @@ export function makeActiveBackendResolver(
     if (sandbox.kind === "selfhosted") {
       if (!sandbox.enrollmentId) {
         throw new ActiveBackendUnresolvableError(
+          "offline_enrollment",
           `selfhosted sandbox ${sandbox.id} has no enrollment (agent id) to address`,
         );
       }
@@ -161,6 +285,10 @@ export function makeActiveBackendResolver(
         agentId: sandbox.enrollmentId,
         epoch: pointer.activeEpoch,
         ...(deps.selfhostedTimeoutMs !== undefined ? { timeoutMs: deps.selfhostedTimeoutMs } : {}),
+        ...(deps.selfhostedExecTimeoutMs !== undefined
+          ? { execTimeoutMs: deps.selfhostedExecTimeoutMs }
+          : {}),
+        ...(deps.selfhostedOnOp !== undefined ? { 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).
@@ -169,12 +297,17 @@ export function makeActiveBackendResolver(
         // for this selfhosted backend. Absent/empty ⇒ the default workspace_root.
         ...(pointer.workingDir ? { workingDir: pointer.workingDir } : {}),
       });
-      return { session: session as RoutableBackendSession, sandboxId: sandbox.id, kind: "selfhosted" };
+      return {
+        session: session as RoutableBackendSession,
+        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)`,
         );
       }
@@ -183,6 +316,7 @@ export function makeActiveBackendResolver(
     }
 
     throw new ActiveBackendUnresolvableError(
+      "unsupported_backend_context",
       `unsupported swap target kind "${sandbox.kind}" for sandbox ${sandbox.id}`,
     );
   };