@opengeni/runtime 0.6.1 → 0.7.0

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}`,
     );
   };

package/src/sandbox/routing/routing-session.ts

@@ -28,6 +28,8 @@
 // `@opengeni/db`.
 
 import type { ExposedPortEndpoint } from "../stream-port";
+import { SelfhostedControlError } from "../selfhosted/control-rpc";
+import { renderSelfhostedFault } from "../selfhosted/fault-rendering";
 
 /** The per-session active-sandbox pointer the proxy re-reads on every op. Mirror
  *  of `@opengeni/db`'s `ActiveSandboxPointer` (structural, so the leaf does not
@@ -74,7 +76,13 @@ export interface RoutableBackendSession {
   // `event` is kept `unknown` (mirroring the interface's structural style + avoiding
   // a proto import into the leaf); the SelfhostedSession takes `DesktopInputRequest["event"]`.
   desktopInput?(event: unknown): Promise<void>;
-  screenshot?(): Promise<{ png: Uint8Array; width: number; height: number; nativeWidth: number; nativeHeight: number }>;
+  screenshot?(): Promise<{
+    png: Uint8Array;
+    width: number;
+    height: number;
+    nativeWidth: number;
+    nativeHeight: number;
+  }>;
 }
 
 /** The resolved active backend for an epoch: the live session + the sandbox id it
@@ -148,10 +156,12 @@ function isFenceError(error: unknown): boolean {
   if ((error as { fenced?: unknown }).fenced === true) {
     return true;
   }
-  const name = typeof (error as { name?: unknown }).name === "string" ? (error as { name: string }).name : "";
-  const message = error instanceof Error ? error.message : String((error as { message?: unknown }).message ?? "");
+  const name =
+    typeof (error as { name?: unknown }).name === "string" ? (error as { name: string }).name : "";
+  const message =
+    error instanceof Error ? error.message : String((error as { message?: unknown }).message ?? "");
   const haystack = `${name} ${message}`.toLowerCase();
-  return haystack.includes("fenced") || haystack.includes("epoch") && haystack.includes("super");
+  return haystack.includes("fenced") || (haystack.includes("epoch") && haystack.includes("super"));
 }
 
 /**
@@ -172,9 +182,17 @@ function isFenceError(error: unknown): boolean {
 export class RoutingSandboxSession implements RoutableBackendSession {
   private readonly deps: RoutingSandboxSessionDeps;
   private readonly maxFenceRetries: number;
-  // 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).
   private cachedEpoch: number | undefined;
+  private cachedSandboxId: string | null | undefined;
   private cached: ResolvedActiveBackend | undefined;
   // The last-resolved backend, exposed via the `state` getter (a method-free read
   // of the active backend's `state`). Updated on every resolve.
@@ -189,7 +207,13 @@ export class RoutingSandboxSession implements RoutableBackendSession {
   // that cannot serve them. So the constructor assigns them ONLY when the
   // construction-time default backend actually implements the native surface (below).
   desktopInput?: (event: unknown) => Promise<void>;
-  screenshot?: () => Promise<{ png: Uint8Array; width: number; height: number; nativeWidth: number; nativeHeight: number }>;
+  screenshot?: () => Promise<{
+    png: Uint8Array;
+    width: number;
+    height: number;
+    nativeWidth: number;
+    nativeHeight: number;
+  }>;
 
   constructor(deps: RoutingSandboxSessionDeps) {
     this.deps = deps;
@@ -252,16 +276,34 @@ export class RoutingSandboxSession implements RoutableBackendSession {
    */
   private async resolve(): Promise<ResolvedActiveBackend> {
     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);
+    // Re-entrancy guard: a resolver that returns THIS proxy as the active backend
+    // makes every op (exec/readFile/…) dispatch back into resolve() -> the same
+    // backend -> forever (a silent async infinite recursion that HANGS the turn,
+    // not a stack overflow). Fail loud instead — a wiring bug must surface as a
+    // legible error, never a hung turn.
+    if ((resolved.session as unknown) === this) {
+      throw new Error(
+        "RoutingSandboxSession.resolveActiveBackend returned the proxy itself as the active backend (re-entrancy) — 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?.({
-      type: this.cachedEpoch !== undefined && fromEpoch !== pointer.activeEpoch ? "epoch-changed" : "resolved",
+      type:
+        this.cachedEpoch !== undefined && fromEpoch !== pointer.activeEpoch
+          ? "epoch-changed"
+          : "resolved",
       fromEpoch,
       toEpoch: pointer.activeEpoch,
       sandboxId: resolved.sandboxId,
@@ -281,7 +323,10 @@ export class RoutingSandboxSession implements RoutableBackendSession {
    * A non-fence error propagates immediately (it is a real op failure, not a swap
    * race).
    */
-  private async dispatch<T>(op: string, fn: (session: RoutableBackendSession) => Promise<T>): Promise<T> {
+  private async dispatch<T>(
+    op: string,
+    fn: (session: RoutableBackendSession) => Promise<T>,
+  ): Promise<T> {
     let attempt = 0;
     let lastError: unknown;
     while (attempt <= this.maxFenceRetries) {
@@ -297,6 +342,7 @@ export class RoutingSandboxSession implements RoutableBackendSession {
         // active sandbox (the fenced-retry role). Bounded by maxFenceRetries.
         lastError = error;
         this.cachedEpoch = undefined;
+        this.cachedSandboxId = undefined;
         this.cached = undefined;
         this.deps.onTransition?.({
           type: "fenced-retry",
@@ -313,6 +359,31 @@ export class RoutingSandboxSession implements RoutableBackendSession {
     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.
+   */
+  private renderSelfhostedFaultOrThrow(error: unknown): string {
+    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
@@ -332,16 +403,22 @@ export class RoutingSandboxSession implements RoutableBackendSession {
   }
 
   async execCommand(args: unknown): Promise<string> {
-    return this.dispatch("execCommand", async (s) => {
-      if (s.execCommand) {
-        return s.execCommand(args);
-      }
-      if (s.exec) {
-        const r = (await s.exec(args)) as { stdout?: string; output?: string };
-        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)) as { stdout?: string; output?: string };
+          return r.stdout ?? r.output ?? "";
+        }
+        throw new RoutingUnsupportedError("execCommand", this.cached?.kind ?? "unknown");
+      });
+    } catch (error) {
+      // Render a terminal selfhosted fault as the tool's result (four fields, correct
+      // verdict) instead of letting the SDK mislabel it "Please try again".
+      return this.renderSelfhostedFaultOrThrow(error);
+    }
   }
 
   async writeStdin(args: unknown): Promise<string> {
@@ -417,12 +494,39 @@ export class RoutingSandboxSession implements RoutableBackendSession {
     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?: string): unknown {
-    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: "createFile" | "updateFile" | "deleteFile") =>
+      (operation: unknown, context?: unknown): Promise<unknown> =>
+        this.dispatch(`editor.${name}`, async (s) => {
+          const editor = s.createEditor?.(runAs) as
+            | Record<string, (operation: unknown, context?: unknown) => Promise<unknown>>
+            | undefined;
+          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: number): Promise<ExposedPortEndpoint> {

package/src/sandbox/select.ts

@@ -165,7 +165,14 @@ export function negotiateCapabilities(ctx: NegotiationContext): SessionCapabilit
 
   const fileSystem = (() => {
     if (osReason) {
-      return { available: false, readOnly: true, root: descriptor.workspaceRoot, pathSep: "/" as const, treeMode: "lazy" as const, reason: osReason };
+      return {
+        available: false,
+        readOnly: true,
+        root: descriptor.workspaceRoot,
+        pathSep: "/" as const,
+        treeMode: "lazy" as const,
+        reason: osReason,
+      };
     }
     const cap = descriptor.capabilities.FileSystem;
     return {
@@ -181,10 +188,26 @@ export function negotiateCapabilities(ctx: NegotiationContext): SessionCapabilit
   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" as const };
+      return {
+        transport: null,
+        ptyCapable: false,
+        shell: "/bin/bash",
+        url: null,
+        token: null,
+        expiresAt: null,
+        reason: "backend_unsupported" as const,
+      };
     }
     // The REAL PTY (ttyd pty-ws) rides the SAME tunnel as the desktop, so it is
     // gated identically: a real-PTY backend (cap.pty), the terminal policy toggle
@@ -231,7 +254,11 @@ export function negotiateCapabilities(ctx: NegotiationContext): SessionCapabilit
     if (osReason) {
       return { available: false, repos: [], reason: osReason };
     }
-    return { available: cap.available, repos: [], reason: cap.available ? null : ("backend_unsupported" as const) };
+    return {
+      available: cap.available,
+      repos: [],
+      reason: cap.available ? null : ("backend_unsupported" as const),
+    };
   })();
 
   const desktop = (() => {
@@ -317,14 +344,32 @@ export function negotiateCapabilities(ctx: NegotiationContext): SessionCapabilit
   const recording = (() => {
     const cap = descriptor.capabilities.Recording;
     if (osReason) {
-      return { available: false, modes: [] as ("manual" | "on-turn" | "on-verify")[], codecs: [] as ("h264-mp4" | "vp9-webm")[], reason: osReason };
+      return {
+        available: false,
+        modes: [] as ("manual" | "on-turn" | "on-verify")[],
+        codecs: [] as ("h264-mp4" | "vp9-webm")[],
+        reason: osReason,
+      };
     }
     if (!cap.available) {
-      return { available: false, modes: [] as ("manual" | "on-turn" | "on-verify")[], codecs: [] as ("h264-mp4" | "vp9-webm")[], reason: descriptor.tier === "headless" ? ("tier_headless" as const) : ("backend_unsupported" as const) };
+      return {
+        available: false,
+        modes: [] as ("manual" | "on-turn" | "on-verify")[],
+        codecs: [] as ("h264-mp4" | "vp9-webm")[],
+        reason:
+          descriptor.tier === "headless"
+            ? ("tier_headless" as const)
+            : ("backend_unsupported" as const),
+      };
     }
     // Recording feasibility tracks desktop; policy-gate it the same way.
     if (!ctx.desktopEnabled) {
-      return { available: false, modes: [] as ("manual" | "on-turn" | "on-verify")[], codecs: [] as ("h264-mp4" | "vp9-webm")[], reason: "disabled_by_policy" as const };
+      return {
+        available: false,
+        modes: [] as ("manual" | "on-turn" | "on-verify")[],
+        codecs: [] as ("h264-mp4" | "vp9-webm")[],
+        reason: "disabled_by_policy" as const,
+      };
     }
     return {
       available: true,
@@ -345,7 +390,14 @@ export function negotiateCapabilities(ctx: NegotiationContext): SessionCapabilit
       return { available: false, readOnly, reason: osReason };
     }
     if (!desktopCapable) {
-      return { available: false, readOnly, reason: descriptor.tier === "headless" ? ("tier_headless" as const) : ("backend_unsupported" as const) };
+      return {
+        available: false,
+        readOnly,
+        reason:
+          descriptor.tier === "headless"
+            ? ("tier_headless" as const)
+            : ("backend_unsupported" as const),
+      };
     }
     if (!ctx.desktopEnabled || ctx.computerUseEnabled === false) {
       return { available: false, readOnly, reason: "disabled_by_policy" as const };