@opengeni/runtime 0.6.1 → 0.7.0

package/dist/{index-BTo_bZvN.d.ts → index-DIiiwQY2.d.ts}

@@ -2,7 +2,7 @@ import { Settings } from '@opengeni/config';
 import { SandboxBackend, CapabilityDescriptor, SandboxOs, SessionCapabilities, StreamTokenPayload, SessionEventType, SessionStructuredCapabilities, FsListRequest, FsListResponse, FsReadRequest, FsReadResponse, FsWriteRequest, FsWriteResponse, FsDeleteRequest, FsDeleteResponse, FsMoveRequest, FsMoveResponse, FsMkdirRequest, FsMkdirResponse, GitStatusRequest, GitStatusResponse, GitDiffRequest, GitDiffResponse, GitLogRequest, GitLogResponse, GitShowRequest, GitShowResponse, TerminalExecRequest, TerminalExecResponse, PtyOpenRequest, PtyOpenResponse, PtyWriteRequest, PtyResizeRequest, PtyCloseRequest, GitChangedPayload, GitDiffHunk, GitFileStatusCode, CapabilityUnavailableReason } from '@opengeni/contracts';
 import { Manifest, SandboxClient, SandboxSessionState } from '@openai/agents/sandbox';
 import * as modal from 'modal';
-import { ControlRequest, ControlResponse, ErrorCode, AgentError, DesktopInputRequest, ExecRequest, ExecResponse } from '@opengeni/agent-proto';
+import { ControlRequest, ControlResponse, ErrorCode, AgentError, ExecResponse, DesktopInputRequest, ExecRequest } from '@opengeni/agent-proto';
 
 type RuntimeMetricsHooks = {
     onModelCall?: (input: {
@@ -18,6 +18,24 @@ type RuntimeMetricsHooks = {
     onSandboxWarmingTimeout?: (input: {
         backend: string;
     }) => void;
+    /**
+     * One completed Connected Machine (selfhosted) control op — the out-of-band
+     * telemetry twin of the in-band fault rendering. `code` is the typed wire-code
+     * NAME on a failure (bounded label cardinality); `healed` marks a success that
+     * only landed after ≥1 retry (the leading indicator of the next unhealed fault);
+     * `replyBytes` is set only on a payload-wall fault. Wired from the runtime's
+     * `SelfhostedOpObserver` seam.
+     */
+    onSandboxOp?: (input: {
+        backend: string;
+        op: string;
+        outcome: "ok" | "failed";
+        code?: string;
+        healed: boolean;
+        retries: number;
+        durationSeconds: number;
+        replyBytes?: number;
+    }) => void;
 };
 
 /**
@@ -33,6 +51,13 @@ declare class SandboxConfigError extends Error {
     readonly backend: SandboxBackend | string;
     constructor(backend: SandboxBackend | string, message: string);
 }
+/** A resume-only caller was handed a warm lease without a provider identity it
+ * can resume. The lease-aware caller must retire that exact epoch and re-enter
+ * admission; silently creating here would bypass the single-spawner guard. */
+declare class SandboxResumeStateUnavailableError extends Error {
+    readonly backend: SandboxBackend | string;
+    constructor(backend: SandboxBackend | string);
+}
 declare class SandboxProviderUnavailableError extends Error {
     readonly backend: SandboxBackend | string;
     constructor(backend: SandboxBackend | string);
@@ -499,7 +524,7 @@ declare function extForCodec(codec: RecordingCodec): string;
 declare class RecordingUnavailableError extends Error {
     constructor(message: string);
 }
-/** 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. */
 declare class RecordingError extends Error {
     readonly reason: "ffmpeg-error" | "box-death" | "max-bytes-exceeded" | "display-unavailable";
     constructor(message: string, reason: "ffmpeg-error" | "box-death" | "max-bytes-exceeded" | "display-unavailable");
@@ -539,37 +564,29 @@ declare function startRecording(session: unknown, input: StartRecordingInput): P
  * pid file is a no-op.
  */
 declare function stopRecording(session: unknown, proc: RecordingProcess): Promise<void>;
-type FinalizeRecordingResult = {
-    bytes: Uint8Array;
+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.
+ */
+declare function inspectRecordingArtifact(session: unknown, proc: RecordingProcess, maxBytes?: number): Promise<RecordingArtifactMetadata>;
+/**
+ * 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.
  */
-declare function readRecordingBytes(session: unknown, proc: RecordingProcess, maxBytes?: number): Promise<FinalizeRecordingResult>;
+declare function uploadRecordingArtifact(session: unknown, proc: RecordingProcess, input: {
+    url: string;
+    requiredHeaders: Record<string, string>;
+    maxBytes?: number;
+    maxSeconds?: number;
+}): Promise<RecordingArtifactMetadata>;
 /**
  * Delete the box artifacts. F9: call this ONLY after the storage PUT confirmed
  * and the `available` row committed — never before. Best-effort; never throws.
@@ -642,6 +659,13 @@ type SandboxChannelAServiceOptions = {
     emit?: ChannelAEmitter;
     runAs?: string;
 };
+declare const REPOSITORY_DISCOVERY_LIMIT = 256;
+type RepositoryDiscoveryDegradedReason = "command_failed" | "command_timed_out" | "result_limit_exceeded";
+type RepositoryDiscoveryResult = {
+    repos: string[];
+    complete: boolean;
+    degradedReason: RepositoryDiscoveryDegradedReason | null;
+};
 declare class SandboxChannelAService {
     private readonly session;
     private readonly workspaceRoot;
@@ -670,6 +694,22 @@ declare class SandboxChannelAService {
     gitDiff(req: GitDiffRequest): Promise<GitDiffResponse>;
     gitLog(req: GitLogRequest): Promise<GitLogResponse>;
     gitShow(req: GitShowRequest): Promise<GitShowResponse>;
+    /**
+     * 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.
+     */
+    detectReposDetailed(): Promise<RepositoryDiscoveryResult>;
     /** Detect repo roots within the workspace (for the Git.repos capability). */
     detectRepos(): Promise<string[]>;
     /** Run a bounded command, return buffered stdout/stderr + exit code inline. The
@@ -702,6 +742,7 @@ declare class SandboxChannelAService {
     currentRevision(): number;
     private joinRoot;
     private repoWorkdir;
+    private terminalWorkdir;
     private emitEvents;
     private emitFsChanged;
     /** Re-probe git after a mutation and emit git.changed (best-effort, used by the
@@ -776,6 +817,15 @@ declare class SelfhostedControlError extends Error {
     readonly draining: boolean;
     readonly agentOffline: boolean;
     readonly osNotFound: boolean;
+    /** 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). */
+    readonly payloadTooLarge: boolean;
+    /** 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. */
+    readonly neverSent: boolean;
     readonly detail: Record<string, string>;
     constructor(input: {
         message: string;
@@ -786,6 +836,8 @@ declare class SelfhostedControlError extends Error {
         draining?: boolean;
         agentOffline?: boolean;
         osNotFound?: boolean;
+        payloadTooLarge?: boolean;
+        neverSent?: boolean;
         detail?: Record<string, string>;
     });
 }
@@ -804,13 +856,45 @@ declare class SelfhostedControlError extends Error {
  *                             real "file does not exist"), no machine-liveness
  *                             reason. (This is the ONLY NotFound; it is NOT the
  *                             box-gone NotFound that licenses a cold restore.)
+ *   - PAYLOAD_TOO_LARGE     → the reply exceeded the transport's max payload;
+ *                             non-retryable, with actionable copy (the sizes + a
+ *                             redirect-to-file workaround).
  *   - OS / UNSUPPORTED / STREAM / PROTOCOL / UNSPECIFIED → op-level error, no
  *                             reason, non-retryable.
  */
 declare function agentErrorToControlError(err: AgentError): SelfhostedControlError;
+/**
+ * PAYLOAD_TOO_LARGE copy: state the actual sizes (from the agent's `detail` map —
+ * `encoded_bytes` / `max_payload`) and tell the caller how to get the data anyway:
+ * redirect the output to a file and read it back in ranges/chunks.
+ */
+declare function payloadTooLargeMessage(detail: Record<string, string>): string;
+/**
+ * DRAINING copy: the machine is at its concurrent-work capacity. `retries` is the
+ * number of times `SelfhostedSession.call` already re-tried before giving up (0 at
+ * the mapping layer, the final count when it surfaces after exhausting retries).
+ */
+declare function drainingMessage(retries: number): string;
+/** Rebuild a DRAINING error with the final retry count folded into its message —
+ *  used by `SelfhostedSession.call` when the bounded DRAINING retries are exhausted. */
+declare function drainingExhaustedError(base: SelfhostedControlError, retries: number): SelfhostedControlError;
+/**
+ * exec-deadline copy: the command was terminated at the exec time limit. Advise
+ * running long jobs in the background and polling their output rather than blocking
+ * the turn on one long command. Surfaced on a timed-out exec result's stderr.
+ */
+declare function execDeadlineHint(seconds: number): string;
+/** The reserved `detail` key the transport sets to "1" when it KNOWS a synthesized
+ *  AGENT_OFFLINE fault occurred pre-send (no connection / no responder) — so the op
+ *  provably never reached the machine. `agentErrorToControlError` reads it into
+ *  `SelfhostedControlError.neverSent`. Reserved (never sent by the agent). */
+declare const NEVER_SENT_DETAIL_KEY = "_never_sent";
 /** Build a synthesized AGENT_OFFLINE `AgentError` — the control plane uses this
- *  when no agent responds on the subject at all. */
-declare function offlineAgentError(message?: string): AgentError;
+ *  when no agent responds on the subject at all. `neverSent` marks that the request
+ *  provably never reached the machine (no connection / no responder), which makes it
+ *  safe to re-issue for ANY op kind; leave it false for an AMBIGUOUS transport error
+ *  (a connection torn mid-request may have delivered the op). */
+declare function offlineAgentError(message?: string, neverSent?: boolean): AgentError;
 /** Build a synthesized TIMEOUT `AgentError` — the control plane uses this when a
  *  responder existed but the request timed out (a transient blip → reconnecting). */
 declare function timeoutAgentError(message?: string): AgentError;
@@ -844,17 +928,308 @@ interface NatsRequestConnection {
 declare class NatsControlRpc implements ControlRpc {
     private readonly connect;
     private connection;
+    private connecting;
     constructor(connect: () => Promise<NatsRequestConnection | null>);
     private resolveConnection;
     request(subject: string, req: ControlRequest, opts: {
         timeoutMs: number;
     }): Promise<ControlResponse>;
 }
-/** A `ControlResponse` carrying a synthesized AGENT_OFFLINE error. */
-declare function offlineControlResponse(requestId: string): ControlResponse;
+/** A `ControlResponse` carrying a synthesized AGENT_OFFLINE error. `neverSent` marks
+ *  a pre-send synthesis (no connection / no responder) — the op provably never
+ *  reached the machine, so it is safe to re-issue for any op kind. */
+declare function offlineControlResponse(requestId: string, neverSent?: boolean): ControlResponse;
 /** A `ControlResponse` carrying a synthesized TIMEOUT error (→ reconnecting). */
 declare function timeoutControlResponse(requestId: string): ControlResponse;
 
+/**
+ * One completed control-op observation. `outcome` is the terminal result AFTER any
+ * in-call retries: `ok` (the op succeeded) or `failed` (a terminal fault surfaced).
+ * `healed` marks a success that only landed after ≥1 retry — the doctrine's
+ * "healed and invisible in-band, always out-of-band" breadcrumb (drives
+ * `machine.op.recovered`). Every field is derivable at the `SelfhostedSession.call`
+ * exit points with no extra round-trip.
+ */
+interface SelfhostedOpObservation {
+    /** The control-op kind (`ControlRequest["op"].$case`): exec / fsRead / ping / … */
+    op: string;
+    outcome: "ok" | "failed";
+    /** True when `outcome==="ok"` only after ≥1 in-call retry (draining/timeout/never-sent). */
+    healed: boolean;
+    /** Total in-call retries before this outcome (summed across the retry classes). */
+    retries: number;
+    /** Wall time from the first attempt to the terminal outcome, in ms. */
+    durationMs: number;
+    /** The typed wire code — present on `failed`. */
+    code?: ErrorCode;
+    /** The negotiated capability reason (agent_offline / agent_reconnecting / …), if any. */
+    reason?: SelfhostedUnavailableReason | null;
+    /** Whether a failed fault provably never reached the machine (a pre-send synthesis). */
+    neverSent?: boolean;
+    /** The enrolled machine (agent) id the op addressed — for machine-scoped fan-out. */
+    machineId?: string;
+    /** A stable fault-class string (`selfhostedFaultClass`): the fault class on a
+     *  `failed` op, or the class of retries that a `healed` op recovered from. Absent
+     *  on a clean success. Drives the `machine.op.*` event mapping + its infra filter. */
+    faultClass?: string;
+    /** The reply size in bytes when known — set on a PAYLOAD_TOO_LARGE fault (from the
+     *  agent's `encoded_bytes` detail). The op-stream client fills the success-reply
+     *  size once it owns the framed transport; today's request/reply does not surface it. */
+    replyBytes?: number;
+}
+/** A fire-and-forget observer of completed control ops. It MUST NOT throw (the
+ *  session guards the call) and MUST NOT block the op — it is a telemetry tap. */
+type SelfhostedOpObserver = (observation: SelfhostedOpObservation) => void;
+
+/**
+ * A stable, low-cardinality fault-class string for a `SelfhostedControlError` — the
+ * out-of-band twin of the in-band renderer's class taxonomy (single-sourced here).
+ * Used for the `machine.op.*` event class + the metrics label + the infra filter.
+ */
+declare function selfhostedFaultClass(error: SelfhostedControlError): string;
+/**
+ * The fault classes that count as an INFRASTRUCTURE fault (a `machine.op.failed`
+ * event). A semantic miss the model asked about — a missing path (`not_found`), a
+ * consent gate (`consent`), a nonzero exit (never a fault at all) — is an OUTCOME,
+ * not an infra fault, and is DELIBERATELY excluded; `fenced` is a routing/session
+ * condition, not a machine fault. (Doctrine two-planes / the team ruling.)
+ */
+declare const SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES: ReadonlySet<string>;
+/** The four mandatory field labels (exported so tests can assert their presence). */
+declare const FAULT_FIELD_WHAT_HAPPENED = "What happened:";
+declare const FAULT_FIELD_WHICH_LAYER = "Which layer:";
+declare const FAULT_FIELD_WHAT_PRESERVED = "What was preserved:";
+declare const FAULT_FIELD_WHAT_TO_TRY = "What to try:";
+/**
+ * Render a `SelfhostedControlError` into the doctrine's four in-band fields with a
+ * correct retry verdict. The fault CLASS is read from the typed flags (never the
+ * message prose), so each class gets the right "which layer" and "what to try":
+ *
+ *  - PAYLOAD_TOO_LARGE → the command ran but its reply was too big to return; the
+ *    fix is to bound the output, not to retry.
+ *  - DRAINING → pre-admission backpressure; nothing ran; safe to retry shortly.
+ *  - CONSENT_REQUIRED → a machine-side consent gate; retrying cannot help.
+ *  - AGENT_OFFLINE → the machine link is down. If the transport KNOWS the request
+ *    never left (`neverSent`), nothing ran; otherwise the effect is ambiguous and
+ *    the model must check before re-running. Either way "try again" is wrong until
+ *    the machine reconnects.
+ *  - agent_reconnecting (TIMEOUT) → a transient link blip AFTER send: ambiguous, so
+ *    a state-changing command must be checked before re-running (at-least-once).
+ *  - NOT_FOUND → a command/filesystem miss, not a link fault.
+ *  - FENCED → the active machine session changed (a swap); re-run.
+ *  - default (OS/UNSUPPORTED/STREAM/PROTOCOL) → the command/op failed on the machine.
+ */
+declare function renderSelfhostedFault(error: SelfhostedControlError): string;
+
+/**
+ * The read-only, idempotent-safe control ops that MAY be retried after a TIMEOUT
+ * / `agent_reconnecting` blip.
+ *
+ * A timed-out request is AT-LEAST-ONCE on the wire: the agent may have RECEIVED
+ * and fully EXECUTED the op before its reply was lost, so re-issuing it is only
+ * safe when a second execution is observably identical to one — i.e. a pure read.
+ * Every MUTATING op (`exec`, `git`, `fsWrite`/`fsMove`/`fsMkdir`/`fsRemove`, and
+ * the pty/desktop input ops) is DELIBERATELY EXCLUDED: re-running a mutation that
+ * already ran on the machine is a real correctness hazard (a duplicated write, a
+ * second `git push`, a re-applied command). Only DRAINING (a pre-admission
+ * rejection — see `decideSelfhostedRetry`) is safe to retry for those.
+ */
+declare const SELFHOSTED_IDEMPOTENT_READONLY_OPS: ReadonlySet<string>;
+/**
+ * DRAINING is a pre-admission backpressure rejection (the op never started), so it
+ * is safe to retry for ANY op kind. The budget is split by op class:
+ *
+ *  - NON-EXEC control ops (fs/git/desktop/pty) keep a SHORT budget — 3 retries,
+ *    worst-case backoff 500+1000+2000 = 3.5s (≤5s). Their start latency matters
+ *    (fs/git ops gate the model's next step), so a saturated machine should surface
+ *    quickly rather than stall.
+ *  - EXEC gets a LONG, patient budget — 10 retries, worst-case ≈55.5s (<60s). exec
+ *    start is not latency-critical, and the agent-side admission pool is (until a
+ *    later agent release) a FLAT 8 permits with no per-class split: a burst of slow
+ *    execs can hold every permit and blanket-DRAIN all fs/git ops. A patient exec
+ *    retry converts those DRAINING storms into mild queueing instead of a wall of
+ *    failed tool calls, and pairs with the deliberately modest exec deadline (which,
+ *    for the same 8-permit reason, defaults to 2min, not 5).
+ */
+declare const SELFHOSTED_DRAINING_MAX_RETRIES = 3;
+declare const SELFHOSTED_EXEC_DRAINING_MAX_RETRIES = 10;
+/** A read-only op that timed out is retried at most once (see the at-least-once
+ *  note above — even a read gets a single re-issue, not an unbounded loop). */
+declare const SELFHOSTED_TIMEOUT_MAX_RETRIES = 1;
+/** A fault the transport synthesized PRE-SEND (no connection / no responder) — the
+ *  op provably never reached the machine, so it is safe to re-issue for ANY op kind.
+ *  Short bounded budget (≈3.5s summed): enough to ride out a NATS reconnect blip
+ *  quietly, not so long it stalls the model on a machine that is genuinely down. */
+declare const SELFHOSTED_NEVER_SENT_MAX_RETRIES = 3;
+/** Full-jitter backoff base (ms). Delay N is sampled in `[0, base * factor^N)`. */
+declare const SELFHOSTED_RETRY_BACKOFF_BASE_MS = 500;
+declare const SELFHOSTED_RETRY_BACKOFF_FACTOR = 2;
+/** Per-delay ceiling: 500 → 1s → 2s → 4s → 8s, then flat at 8s. Bounds the summed
+ *  backoff — non-exec (3 retries) ≈3.5s ≤5s; exec (10 retries) ≈55.5s <60s. */
+declare const SELFHOSTED_RETRY_BACKOFF_CAP_MS = 8000;
+type SelfhostedRetryDecision = {
+    readonly action: "fail";
+} | {
+    readonly action: "retry";
+    readonly delayMs: number;
+};
+/**
+ * Full-jitter exponential backoff. Returns a delay in
+ * `[0, min(cap, base * factor^attempt))`. `jitter` is an injected sample in
+ * `[0, 1)` so the delay is fully deterministic under test.
+ */
+declare function selfhostedRetryBackoffMs(attempt: number, jitter: number): number;
+/**
+ * PURE retry policy for one selfhosted control-op reply.
+ *
+ *  - `error.draining` (DRAINING — pre-admission host-work backpressure; the op was
+ *    rejected at the pool gate and NEVER started) → retry for ANY op kind, since
+ *    nothing executed. exec gets the long `SELFHOSTED_EXEC_DRAINING_MAX_RETRIES`
+ *    budget (≈60s of patient queueing under the flat 8-permit pool); every other op
+ *    keeps the short `SELFHOSTED_DRAINING_MAX_RETRIES` budget (≤5s).
+ *  - `error.neverSent` (a pre-send AGENT_OFFLINE synthesis — no connection / no
+ *    responder; the op provably never reached the machine) → retry for ANY op kind
+ *    up to `SELFHOSTED_NEVER_SENT_MAX_RETRIES`. At-least-once does NOT apply (nothing
+ *    executed), so even a mutation is safe to re-issue; this heals a NATS reconnect
+ *    blip quietly. A truly-offline machine surfaces honestly after the short budget.
+ *  - `error.reason === "agent_reconnecting"` (a TIMEOUT / transient blip AFTER send)
+ *    → retry at most `SELFHOSTED_TIMEOUT_MAX_RETRIES`, and ONLY for a read-only
+ *    idempotent-safe op (`SELFHOSTED_IDEMPOTENT_READONLY_OPS`). A timed-out
+ *    MUTATION is never retried here — it may already have run (at-least-once).
+ *  - Everything else → no retry at this layer:
+ *      · FENCED is retried by the routing proxy against a RE-RESOLVED backend
+ *        (retrying here under the same stale epoch would just re-fence);
+ *      · AGENT_OFFLINE / OS / PROTOCOL / PAYLOAD_TOO_LARGE / CONSENT_REQUIRED are
+ *        not transient and must surface to the caller.
+ *
+ * The draining and timeout budgets are SEPARATE counters so a read that first hit
+ * backpressure still keeps its single timeout re-issue (and vice versa); both are
+ * bounded, so the total number of attempts — and the summed backoff — is bounded.
+ */
+declare function decideSelfhostedRetry(input: {
+    opKind: string;
+    error: SelfhostedControlError;
+    drainingRetries: number;
+    timeoutRetries: number;
+    /** Prior never-sent retries. Optional (default 0) — only the pre-send AGENT_OFFLINE
+     *  branch reads it, so callers that cannot hit that class may omit it. */
+    neverSentRetries?: number;
+    jitter: number;
+}): SelfhostedRetryDecision;
+/**
+ * The injected clock the retry loop drives — real in production, a deterministic
+ * fake in tests. `jitter()` returns a full-jitter sample in `[0, 1)`.
+ */
+interface SelfhostedRetryClock {
+    sleep(ms: number): Promise<void>;
+    jitter(): number;
+}
+/** The production clock: a real timer + `Math.random()` jitter. */
+declare const defaultSelfhostedRetryClock: SelfhostedRetryClock;
+
+/** The per-op frame subject (runner→server, fire-and-forget). Mirrors the
+ *  runner's wire constant: `agent.<ws>.<id>.op.<op_id>`. */
+declare function opFrameSubject(workspaceId: string, agentId: string, opId: string): string;
+/** The per-agent ack subject (server→runner, fire-and-forget). Mirrors the
+ *  runner's wire constant: `agent.<ws>.<id>.ack`. */
+declare function opAckSubject(workspaceId: string, agentId: string): string;
+/** A live subscription handle. `unsubscribe` is idempotent and never throws. */
+interface OpStreamSubscription {
+    unsubscribe(): void;
+}
+/**
+ * The op-stream transport seam. `subscribe` MUST be established before the
+ * OpStart that makes frames flow (subscription-before-start is a protocol
+ * invariant: no frame is published before the consumer exists on a healthy
+ * path; a missed frame is healed via OpAttach replay regardless). `onMessage`
+ * is invoked in arrival order; a decode failure inside the handler must be
+ * contained by the caller (a torn frame must never kill the subscription).
+ */
+interface OpStreamTransport {
+    subscribe(subject: string, onMessage: (payload: Uint8Array) => void): Promise<OpStreamSubscription>;
+    publish(subject: string, payload: Uint8Array): Promise<void>;
+}
+/** Thrown when the transport has no live connection: the op-stream path is
+ *  UNAVAILABLE (never silently degraded). The session catches this pre-start
+ *  and falls back to the legacy exec — the op provably never started. */
+declare class OpStreamUnavailableError extends Error {
+    readonly name = "OpStreamUnavailableError";
+}
+/**
+ * The minimal NATS surface the transport needs — mirrors the `nats`
+ * `NatsConnection` subscribe/publish WITHOUT importing `nats` into the
+ * agent-loop-free runtime leaf (the worker injects the live `@opengeni/events`
+ * bus connection, exactly like `NatsRequestConnection` in control-rpc.ts).
+ * `subscribe` returns the nats.js Subscription shape: an async iterable of
+ * messages plus `unsubscribe()`.
+ */
+interface NatsOpStreamConnection {
+    subscribe(subject: string): AsyncIterable<{
+        data: Uint8Array;
+    }> & {
+        unsubscribe(): void;
+    };
+    publish(subject: string, payload: Uint8Array): void;
+}
+/**
+ * The NATS-backed transport. Lazy memoized factory (identical discipline to
+ * `NatsControlRpc`): the connection resolves on first use; a null factory
+ * result or a dial failure surfaces `OpStreamUnavailableError` — the caller
+ * (the session) falls back to the LEGACY exec path rather than failing the op,
+ * so a NATS-less boot or a torn bus never strands a turn on a dead transport.
+ */
+declare class NatsOpStreamTransport implements OpStreamTransport {
+    private readonly connect;
+    private connection;
+    private connecting;
+    constructor(connect: () => Promise<NatsOpStreamConnection | null>);
+    private resolveConnection;
+    subscribe(subject: string, onMessage: (payload: Uint8Array) => void): Promise<OpStreamSubscription>;
+    publish(subject: string, payload: Uint8Array): Promise<void>;
+}
+
+/** Initial send-credit window (bytes) when the caller does not size it. Matches
+ *  the wire default OpStart advertises (~4 MiB). */
+declare const OP_STREAM_DEFAULT_WINDOW_BYTES: number;
+/** Cumulative-ack repetition cadence while an op is live (ruling M1: acks are
+ *  best-effort and healed by repetition). */
+declare const OP_STREAM_ACK_INTERVAL_MS = 5000;
+/** Frame-silence threshold before the client starts probing with OpQuery. The
+ *  runner emits Progress every 5s while an op is alive and quiet, so 30s of
+ *  TOTAL silence means frames are not reaching us (or the op is gone). */
+declare const OP_STREAM_SILENCE_TIMEOUT_MS = 30000;
+/** How long a silent op is held open across a machine reconnect window before
+ *  the client fails it typed (PROTOCOL liveness rule: hold ≤120s, then only a
+ *  definitive answer fails the op). */
+declare const OP_STREAM_RECONNECT_HOLD_MS = 120000;
+/**
+ * The durable-resume journal the worker adapts onto Temporal (design delta Δ1:
+ * the attach generation is `Info.currentAttemptScheduledTimestampMs` — strictly
+ * monotonic across worker-death redispatches, which `Info.attempt` is NOT under
+ * `maximumAttempts: 1`). `persistSettled` folds the op's settled frontier into
+ * the activity heartbeat details and MUST complete before the wire final ack
+ * (the durable-before-wire-ack gate); the default no-journal client (tests,
+ * non-activity callers) uses generation "1" and skips persistence.
+ */
+interface OpStreamJournal {
+    /** The consumer's attach generation (u64 decimal string). */
+    attachGeneration(): string;
+    /** Durably record `opId` as settled at `exitSeq` BEFORE its final ack. */
+    persistSettled(opId: string, exitSeq: string): void | Promise<void>;
+}
+/** A completed op-stream exec: the legacy-shaped response plus the healing
+ *  telemetry the session folds into its op observation. */
+interface OpStreamExecOutcome {
+    response: ExecResponse;
+    /** Attach/query heals that occurred after streaming began (gap replays,
+     *  silence probes that re-attached). >0 marks the op `healed`. */
+    heals: number;
+    /** OpStart-level retries (draining/blip) before the op was accepted. */
+    startRetries: number;
+    /** Total reassembled Data payload bytes (the observer's replyBytes). */
+    replyBytes: number;
+}
+
 /** The V4A-diff applier the SDK's apply_patch editor uses. The leaf cannot import
  *  `@openai/agents`'s `applyDiff` (the agent-loop root the leaf forbids), so the
  *  runtime barrel (`packages/runtime/src/index.ts`, which DOES import that root)
@@ -914,17 +1289,54 @@ interface SelfhostedRelayConfig {
 }
 /** The relay's default wss dial path (the `opengeni-relay` server route). */
 declare const SELFHOSTED_RELAY_STREAM_PATH = "/stream";
+/**
+ * The op-stream injection (op-stream protocol v1.1 — see op-stream.ts). PRESENT
+ * = the streaming exec transport is enabled for this session (the worker
+ * injects it only when the runner advertised `Capabilities.op_stream` AND the
+ * server flag is on — the leaf carries no flag logic). ABSENT = the legacy
+ * monolithic exec, byte-identical to before. The timing knobs exist for tests.
+ */
+interface SelfhostedOpStreamDeps {
+    transport: OpStreamTransport;
+    /** The durable-resume journal (attach generation + settled-frontier persist).
+     *  Absent (tests, non-activity callers) ⇒ generation "1", no persistence. */
+    journal?: OpStreamJournal;
+    windowBytes?: number;
+    ackIntervalMs?: number;
+    silenceTimeoutMs?: number;
+    reconnectHoldMs?: number;
+}
 interface SelfhostedSessionDeps {
     workspaceId: string;
     agentId: string;
     controlRpc: ControlRpc;
     relay: SelfhostedRelayConfig;
+    /** Op-stream exec transport (present = enabled; see SelfhostedOpStreamDeps). */
+    opStream?: SelfhostedOpStreamDeps;
     /** The lease/active epoch this session is fenced under (echoed on every
      *  ControlRequest so the agent can reject a stale op with ERROR_CODE_FENCED).
      *  Defaults to 0 (no fence) for the negotiation-only / test path. */
     epoch?: number;
-    /** Override the control-op timeout (tests). */
+    /** The CONTROL-op timeout (ping/fs/desktop/pty and the exec wire fallback). The
+     *  agent's own control liveness must stay responsive, so this is short (the 30s
+     *  default). Override for tests or per-deployment tuning. */
     timeoutMs?: number;
+    /**
+     * The EXEC process deadline — distinct from `timeoutMs`. A real command
+     * (compile, test run, install) routinely outlives the short control timeout, so
+     * exec gets its own, much larger budget: the agent kills the child at this wall,
+     * and the wire waits `execTimeoutMs + SELFHOSTED_EXEC_REPLY_GRACE_MS`. Omitted ⇒
+     * falls back to `timeoutMs` (byte-identical to before this split), so any caller
+     * that does not opt in keeps today's behavior.
+     */
+    execTimeoutMs?: number;
+    /** The clock the bounded control-op retry loop drives (sleep + jitter). Injected
+     *  so tests are deterministic; defaults to a real timer + `Math.random()`. */
+    retryClock?: SelfhostedRetryClock;
+    /** A fire-and-forget observer invoked once per completed control op (out-of-band
+     *  telemetry — metrics + `machine.*` events). The worker/api wire it to the sinks;
+     *  the leaf only invokes it (guarded so it can never break an op). Omitted ⇒ no-op. */
+    onOp?: SelfhostedOpObserver;
     /**
      * The run's declared sandbox environment — the SAME `Record<string,string>` the
      * worker turn passes to `runtime.buildAgent`'s `sandboxEnvironment` (and that the
@@ -955,6 +1367,10 @@ interface SelfhostedExecResult {
     stdout: string;
     stderr: string;
     exitCode: number | null;
+    /** True when the agent killed the child at the exec deadline. Additive to the
+     *  Channel-A superset (consumers that don't read it are unaffected); `execCommand`
+     *  reads it to surface the deadline hint on the stdout-only SDK path. */
+    timedOut?: boolean;
 }
 /** The `exec` args the structural surface accepts (mirrors ChannelAExecArgs). */
 interface SelfhostedExecArgs {
@@ -986,7 +1402,14 @@ declare class SelfhostedSession {
     private readonly relay;
     private readonly epoch;
     private readonly timeoutMs;
+    /** The exec process deadline (falls back to `timeoutMs` when unset). */
+    private readonly execTimeoutMs;
+    private readonly retryClock;
+    private readonly onOp;
     private readonly subject;
+    /** The op-stream exec client — constructed iff `deps.opStream` was injected
+     *  (= the streaming transport is enabled for this session). */
+    private readonly opStreamClient;
     /** The session working directory — the path/cwd base every op is rooted under
      *  (see `toMachinePath`). "" by default ⇒ today's workspace_root behavior. */
     private readonly workingDir;
@@ -1024,15 +1447,65 @@ declare class SelfhostedSession {
         environment: Record<string, string>;
     };
     constructor(deps: SelfhostedSessionDeps);
-    /** 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). */
+    /** 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. */
+    private emitOp;
+    /**
+     * 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).
+     */
     private call;
+    /** 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. */
+    private execDeadlineMs;
     /** Channel-A `exec`: run a command on the machine and return its output. */
     exec(args: SelfhostedExecArgs): Promise<SelfhostedExecResult>;
+    /** The legacy monolithic exec request/reply — the permanent fallback wire
+     *  form (and the only form for runners without `op_stream`). */
+    private execLegacy;
+    /**
+     * 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).
+     */
+    private execViaOpStream;
+    /**
+     * 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.
+     */
+    finalizeOpStreamOps(): Promise<void>;
     /** 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. */
     execCommand(args: {
         cmd: string;
         workdir?: string;
@@ -1171,8 +1644,11 @@ declare class SelfhostedSandboxClient {
     private readonly defaultAgentId;
     private readonly epoch;
     private readonly timeoutMs;
+    private readonly execTimeoutMs;
     private readonly environment;
     private readonly workingDir;
+    private readonly onOp;
+    private readonly opStream;
     private controlRpcMemo;
     constructor(opts: {
         workspaceId: string;
@@ -1183,7 +1659,11 @@ declare class SelfhostedSandboxClient {
          *  resume path supplies it via deserializeSessionState. */
         agentId?: string;
         epoch?: number;
+        /** The control-op timeout threaded into every bound session. */
         timeoutMs?: number;
+        /** The exec process deadline threaded into every bound session (distinct from
+         *  `timeoutMs`; falls back to it when unset). See SelfhostedSessionDeps.execTimeoutMs. */
+        execTimeoutMs?: number;
         /** The run's declared sandbox environment, threaded into every bound session's
          *  `state.manifest.environment` so the SDK's per-turn manifest-env delta is
          *  empty (validateNoEnvironmentDelta). See SelfhostedSessionDeps.environment.
@@ -1193,6 +1673,11 @@ declare class SelfhostedSandboxClient {
          *  cwd base; see SelfhostedSessionDeps.workingDir). Omitted/empty ⇒ the default
          *  workspace_root behavior. */
         workingDir?: string;
+        /** The per-op observer threaded into every bound session (out-of-band telemetry). */
+        onOp?: SelfhostedOpObserver;
+        /** The op-stream exec transport threaded into every bound session (present
+         *  = enabled; see SelfhostedOpStreamDeps). */
+        opStream?: SelfhostedOpStreamDeps;
     });
     private controlRpc;
     private bind;
@@ -1235,8 +1720,17 @@ interface SelfhostedSessionBuild {
     environment?: Record<string, string>;
     /** The session working directory (the path/cwd base). Null/absent ⇒ workspace_root. */
     workingDir?: string | null;
-    /** Override the control-op timeout (tests). */
+    /** The control-op timeout (ping/fs/desktop/pty). Absent ⇒ the 30s default. */
     timeoutMs?: number;
+    /** The exec process deadline, distinct from `timeoutMs`. Absent ⇒ falls back to
+     *  `timeoutMs` (a real turn threads the long exec budget here). */
+    execTimeoutMs?: number;
+    /** The per-op observer (out-of-band telemetry). Absent ⇒ no-op. */
+    onOp?: SelfhostedOpObserver;
+    /** The op-stream exec transport (present = enabled for the session; the
+     *  worker injects it only when the runner advertised the capability AND the
+     *  server flag is on). Absent ⇒ the legacy exec, byte-identical to before. */
+    opStream?: SelfhostedOpStreamDeps;
 }
 /**
  * Build a live selfhosted session bound to a target machine: construct a request-
@@ -1273,6 +1767,31 @@ declare function buildSelfhostedBackendSession(deps: SelfhostedSessionBuild): Pr
  */
 declare function isSelfhostedProviderNotFoundError(_error: unknown): false;
 
+/**
+ * Sanitize a tool call id into a legal NATS subject TOKEN fragment. The op id
+ * is interpolated into the per-op frame subject, whose tokens must not contain
+ * whitespace/control characters or the subject-structure characters (`.`,
+ * `*`, `>`); the runner refuses illegal ids loudly. The mapping is INJECTIVE
+ * (each disallowed char becomes `_<hex>_`), so two distinct call ids can never
+ * collide into one op id — a collision would merge two different execs through
+ * the idempotent-OpStart dedup and return the wrong result.
+ */
+declare function sanitizeOpIdToken(raw: string): string;
+/**
+ * Bind a tool-call correlation context around `fn` (the tool's execute). Every
+ * durable op id minted inside — however deep in the transport — is
+ * `{callId}:{ordinal}` with ordinals starting at 0 per invocation.
+ */
+declare function runWithToolCallCorrelation<T>(callId: string, fn: () => T): T;
+/**
+ * Mint the next durable op id for the current tool invocation, or null when no
+ * correlation context is bound (a non-tool caller, e.g. Channel-A structural
+ * exec). Callers fall back to a random unique id — safe (never collides, never
+ * wrongly dedups), merely not stable across a turn re-dispatch, which degrades
+ * that one op to today's at-least-once semantics.
+ */
+declare function nextDurableOpId(): string | null;
+
 /**
  * The structural slice of the M2 `@opengeni/db` `EnrollmentRecord` the selfhosted
  * negotiation reads. Defined STRUCTURALLY (not imported from `@opengeni/db`) so
@@ -1288,6 +1807,13 @@ interface SelfhostedEnrollment {
     allowScreenControl: boolean;
     hasDisplay: boolean;
     lastSeenAt: string | null;
+    /** An un-cleared clean going-offline marker (the machine announced a typed
+     *  GoingOffline). When set, the derivation reads the machine OFFLINE immediately,
+     *  regardless of a still-fresh `lastSeenAt`. NULL ⇒ no pending goodbye. */
+    wentOfflineAt: string | null;
+    /** The typed reason string of the pending goodbye (rides alongside
+     *  `wentOfflineAt`; NULL when there is no un-cleared marker). */
+    wentOfflineReason: string | null;
 }
 /** The derived liveness state of a selfhosted machine (the online/offline/
  *  reconnecting/consent/display matrix). */
@@ -1313,6 +1839,8 @@ declare const SELFHOSTED_RECONNECT_WINDOW_MS = 30000;
  * (stale / never seen).
  *
  *   - no enrollment / revoked         → offline (the machine isn't enrolled).
+ *   - un-cleared clean goodbye        → offline (an announced GoingOffline beats
+ *                                       last_seen aging AND a lingering probe).
  *   - probe responded                 → online.
  *   - probe missed, lastSeenAt recent → reconnecting (a transient blip).
  *   - probe missed, lastSeenAt stale  → offline.
@@ -1519,6 +2047,7 @@ declare class RoutingSandboxSession implements RoutableBackendSession {
     private readonly deps;
     private readonly maxFenceRetries;
     private cachedEpoch;
+    private cachedSandboxId;
     private cached;
     private lastResolved;
     desktopInput?: (event: unknown) => Promise<void>;
@@ -1565,6 +2094,25 @@ declare class RoutingSandboxSession implements RoutableBackendSession {
      * race).
      */
     private dispatch;
+    /**
+     * 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;
     exec(args: unknown): Promise<unknown>;
     execCommand(args: unknown): Promise<string>;
     writeStdin(args: unknown): Promise<string>;
@@ -1580,10 +2128,17 @@ declare class RoutingSandboxSession implements RoutableBackendSession {
      *  the resolve the surrounding op already performed. Defaults false before the
      *  first resolve. */
     supportsPty(): boolean;
-    /** 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;
     resolveExposedPort(port: number): Promise<ExposedPortEndpoint>;
     /** Serialize the active backend's session state. Used by the resume-by-id seam
@@ -1627,8 +2182,16 @@ 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
@@ -1657,13 +2220,77 @@ interface ActiveBackendResolverDeps {
         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). */
+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. */
 declare class ActiveBackendUnresolvableError extends Error {
     readonly name = "ActiveBackendUnresolvableError";
-    constructor(message: string);
+    readonly code: BackendUnresolvableCode;
+    constructor(code: BackendUnresolvableCode, message: string);
 }
+/** The outcome of {@link swapTargetEstablishability}. */
+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.
+ */
+declare function swapTargetEstablishability(target: {
+    kind: string;
+    isSessionGroup: boolean;
+}): SwapTargetEstablishability;
 /**
  * Build the `resolveActiveBackend(pointer)` closure for a `RoutingSandboxSession`.
  * The returned closure is re-invoked by the proxy whenever the active_epoch moves
@@ -1759,6 +2386,16 @@ type EstablishedSandboxSession = {
     sessionState: unknown;
     instanceId: string;
     backendId: string;
+    /** How this establish reached a live box: warm reattach by id ("resumed"),
+     *  fresh create ("created"), or fresh create + archive hydration
+     *  ("restored"). Callers use it to emit the durable sandbox.box.* lifecycle
+     *  events — box transitions were previously unrecorded, which made both
+     *  2026-07-06 incidents near-unattributable. Optional so external/legacy
+     *  constructors of this shape stay valid. */
+    origin?: "resumed" | "created" | "restored";
+    /** Set when a create-authorized reattach found the envelope's box GONE
+     *  (provider NotFound) and fell through to cold-restore. */
+    lostInstanceId?: string;
 };
 type SandboxCreatedCallback = (established: EstablishedSandboxSession) => Promise<void>;
 /**
@@ -1777,21 +2414,21 @@ type SandboxCreatedCallback = (established: EstablishedSandboxSession) => Promis
  */
 declare function isProviderSandboxNotFoundError(backendId: string, error: unknown): boolean;
 /**
- * Resume the one box by id from its recovery envelope, or cold-restore from the
- * snapshot when the provider reports it gone. The envelope is the lease's
- * box-identity descriptor (the same per-turn `_sandbox` envelope upserted by the
- * turn activity). A null envelope means a cold session that was never warmed →
- * create() directly.
+ * Establish from one recovery envelope under an explicit creation policy. The
+ * envelope is the lease's box-identity descriptor (the same per-turn `_sandbox`
+ * envelope upserted by the turn activity).
  *
  *  - `opts.backendOverride ?? envelope.backendId ?? settings.sandboxBackend`
  *    selects the backend; the client is built for THAT backend (resume-by-id is
  *    fenced to the original provider).
  *  - warm reattach: deserialize the envelope sessionState → client.resume(state)
- *    (no lock; R4-safe). On a provider NotFound, cold-restore via create().
- *  - cold restore / cold session: client.create() — the ONLY create() site.
+ *    (no lock; R4-safe). `resume-only` propagates provider NotFound.
+ *  - `create-or-restore`: the elected owner may replace a missing warm instance,
+ *    or create directly from a cold/null envelope.
  */
 declare function establishSandboxSessionFromEnvelope(settings: Settings, envelope: Record<string, unknown> | null, opts: {
     sessionId: string;
+    recovery: "create-or-restore" | "resume-only";
     backendOverride?: SandboxBackend;
     environment?: Record<string, string>;
     onSandboxCreated?: SandboxCreatedCallback;
@@ -1811,4 +2448,4 @@ declare function establishSandboxSessionFromEnvelope(settings: Settings, envelop
  */
 declare function serializeEstablishedSandboxEnvelope(established: EstablishedSandboxSession): Promise<Record<string, unknown> | null>;
 
-export { RoutingUnsupportedError as $, type ActiveBackendResolverDeps as A, type ModalSandboxAttribution as B, ChannelAConflictError as C, DEFAULT_DESKTOP_GEOMETRY as D, type EnsureDisplayStackOptions as E, type FinalizeRecordingResult as F, type NatsRequestConnection as G, type NegotiationContext as H, type NumstatEntry as I, type ProviderConstructionContext as J, type ProviderRegistration as K, type LiveModalSandboxLeaseAttribution as L, type MintStreamTokenInput as M, NatsControlRpc as N, type RecordingCodec as O, PROVIDER_REGISTRY as P, type RecordingContentType as Q, type RuntimeMetricsHooks as R, RecordingError as S, type RecordingProcess as T, RecordingUnavailableError as U, type ResolvedActiveBackend as V, type RoutableBackendSession as W, type RoutableSandbox as X, RoutingSandboxSession as Y, type RoutingSandboxSessionDeps as Z, type RoutingTransitionEvent as _, ActiveBackendUnresolvableError as a, negotiateSelfhostedCapabilities as a$, SELFHOSTED_DEFAULT_TIMEOUT_MS as a0, SELFHOSTED_RECONNECT_WINDOW_MS as a1, SELFHOSTED_RELAY_STREAM_PATH as a2, STREAM_PORT as a3, STREAM_TOKEN_DEFAULT_TTL_SECONDS as a4, SandboxChannelAService as a5, type SandboxChannelAServiceOptions as a6, SandboxConfigError as a7, type SandboxCreatedCallback as a8, SandboxProviderUnavailableError as a9, buildDisplayStackScript as aA, buildSelfhostedBackendSession as aB, buildStreamUrl as aC, buildTerminalServerScript as aD, contentTypeForCodec as aE, createSandboxClient as aF, createSandboxClientForBackend as aG, decodeModalSnapshotId as aH, deletePriorPersistedSnapshot as aI, deleteRecordingArtifacts as aJ, deserializeSandboxSessionStateEnvelope as aK, desktopCapableBackend as aL, ensureDisplayStack as aM, ensureModalRegistryImage as aN, ensureTerminalServer as aO, establishSandboxSessionFromEnvelope as aP, exposeStreamPort as aQ, extForCodec as aR, isExecSessionLostBanner as aS, isProviderSandboxNotFoundError as aT, isSelfhostedProviderNotFoundError as aU, isWorkspaceEscapeError as aV, makeActiveBackendResolver as aW, mintStreamToken as aX, modalSandboxAttributionEnvironment as aY, modalSandboxAttributionTags as aZ, negotiateCapabilities as a_, type SelfhostedApplyDiff as aa, SelfhostedControlError as ab, type SelfhostedEditor as ac, type SelfhostedEnrollment as ad, type SelfhostedExecArgs as ae, type SelfhostedExecResult as af, type SelfhostedImageOutput as ag, type SelfhostedLivenessState as ah, type SelfhostedNegotiationInput as ai, type SelfhostedRelayConfig as aj, SelfhostedSandboxClient as ak, SelfhostedSession as al, type SelfhostedSessionBuild as am, type SelfhostedSessionDeps as an, type SelfhostedSessionState as ao, type SelfhostedUnavailableReason as ap, type StartRecordingInput as aq, StreamPortUnavailableError as ar, TERMINAL_SERVER_TIMEOUT_MS as as, TerminalServerError as at, TerminalServerUnsupportedError as au, agentErrorToControlError as av, assertDescriptorRegistryInvariants as aw, assertProviderRegistryInvariants as ax, assertSafeRelPath as ay, backendSupportsOs as az, type ActivePointer as b, offlineAgentError as b0, offlineControlResponse as b1, parseExecBannerSessionId as b2, parseNumstatZ as b3, parsePorcelainV2 as b4, parseUnifiedPatch as b5, readRecordingBytes as b6, readWorkspaceArchiveFromEnvelopeSessionState as b7, recordingStorageKey as b8, restoredSandboxSessionStateFromEntry as b9, sandboxStateEntryFromRunState as ba, selectBackend as bb, selfhostedLiveness as bc, serializeEstablishedSandboxEnvelope as bd, setSelfhostedApplyDiff as be, startRecording as bf, stopRecording as bg, stripExecBanner as bh, subjectFor as bi, sweepModalOrphanSandboxes as bj, tagModalSandbox as bk, tearDownDisplayStack as bl, tearDownTerminalServer as bm, terminateModalSandboxById as bn, timeoutAgentError as bo, timeoutControlResponse as bp, verifyStreamToken as bq, type ChannelAEmitter as c, type ChannelAExecArgs as d, type ChannelAExecResult as e, ChannelANotFoundError as f, type ChannelASession as g, ChannelAUnsupportedError as h, ChannelAValidationError as i, type ControlRpc as j, DISPLAY_STACK_TIMEOUT_MS as k, type DesktopGeometry as l, DisplayStackError as m, DisplayStackUnsupportedError as n, type EnsureDisplayStackResult as o, type EnsureTerminalServerOptions as p, type EnsureTerminalServerResult as q, type EstablishedSandboxSession as r, type ExposeStreamPortInput as s, type ExposeStreamPortResult as t, type ExposedPortEndpoint as u, MockAgentResponder as v, type MockAgentResponderOptions as w, type MockExecHandler as x, type ModalModuleLoader as y, type ModalOrphanSweepResult as z };
+export { type OpStreamTransport as $, type ActiveBackendResolverDeps as A, type BackendUnresolvableCode as B, ChannelAConflictError as C, DEFAULT_DESKTOP_GEOMETRY as D, type EnsureDisplayStackOptions as E, FAULT_FIELD_WHAT_HAPPENED as F, type MockExecHandler as G, type ModalModuleLoader as H, type ModalOrphanSweepResult as I, type ModalSandboxAttribution as J, NatsControlRpc as K, type LiveModalSandboxLeaseAttribution as L, type MintStreamTokenInput as M, NEVER_SENT_DETAIL_KEY as N, type NatsOpStreamConnection as O, NatsOpStreamTransport as P, type NatsRequestConnection as Q, type RuntimeMetricsHooks as R, type NegotiationContext as S, type NumstatEntry as T, OP_STREAM_ACK_INTERVAL_MS as U, OP_STREAM_DEFAULT_WINDOW_BYTES as V, OP_STREAM_RECONNECT_HOLD_MS as W, OP_STREAM_SILENCE_TIMEOUT_MS as X, type OpStreamExecOutcome as Y, type OpStreamJournal as Z, type OpStreamSubscription as _, ActiveBackendUnresolvableError as a, type SwapTargetEstablishability as a$, OpStreamUnavailableError as a0, PROVIDER_REGISTRY as a1, type ProviderConstructionContext as a2, type ProviderRegistration as a3, REPOSITORY_DISCOVERY_LIMIT as a4, type RecordingArtifactMetadata as a5, type RecordingCodec as a6, type RecordingContentType as a7, RecordingError as a8, type RecordingProcess as a9, SandboxConfigError as aA, type SandboxCreatedCallback as aB, SandboxProviderUnavailableError as aC, SandboxResumeStateUnavailableError as aD, type SelfhostedApplyDiff as aE, SelfhostedControlError as aF, type SelfhostedEditor as aG, type SelfhostedEnrollment as aH, type SelfhostedExecArgs as aI, type SelfhostedExecResult as aJ, type SelfhostedImageOutput as aK, type SelfhostedLivenessState as aL, type SelfhostedNegotiationInput as aM, type SelfhostedOpObservation as aN, type SelfhostedOpObserver as aO, type SelfhostedOpStreamDeps as aP, type SelfhostedRelayConfig as aQ, type SelfhostedRetryClock as aR, type SelfhostedRetryDecision as aS, SelfhostedSandboxClient as aT, SelfhostedSession as aU, type SelfhostedSessionBuild as aV, type SelfhostedSessionDeps as aW, type SelfhostedSessionState as aX, type SelfhostedUnavailableReason as aY, type StartRecordingInput as aZ, StreamPortUnavailableError as a_, RecordingUnavailableError as aa, type RepositoryDiscoveryDegradedReason as ab, type RepositoryDiscoveryResult as ac, type ResolvedActiveBackend as ad, type RoutableBackendSession as ae, type RoutableSandbox as af, RoutingSandboxSession as ag, type RoutingSandboxSessionDeps as ah, type RoutingTransitionEvent as ai, RoutingUnsupportedError as aj, SELFHOSTED_DEFAULT_TIMEOUT_MS as ak, SELFHOSTED_DRAINING_MAX_RETRIES as al, SELFHOSTED_EXEC_DRAINING_MAX_RETRIES as am, SELFHOSTED_IDEMPOTENT_READONLY_OPS as an, SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES as ao, SELFHOSTED_NEVER_SENT_MAX_RETRIES as ap, SELFHOSTED_RECONNECT_WINDOW_MS as aq, SELFHOSTED_RELAY_STREAM_PATH as ar, SELFHOSTED_RETRY_BACKOFF_BASE_MS as as, SELFHOSTED_RETRY_BACKOFF_CAP_MS as at, SELFHOSTED_RETRY_BACKOFF_FACTOR as au, SELFHOSTED_TIMEOUT_MAX_RETRIES as av, STREAM_PORT as aw, STREAM_TOKEN_DEFAULT_TTL_SECONDS as ax, SandboxChannelAService as ay, type SandboxChannelAServiceOptions as az, type ActivePointer as b, serializeEstablishedSandboxEnvelope as b$, TERMINAL_SERVER_TIMEOUT_MS as b0, TerminalServerError as b1, TerminalServerUnsupportedError as b2, agentErrorToControlError as b3, assertDescriptorRegistryInvariants as b4, assertProviderRegistryInvariants as b5, assertSafeRelPath as b6, backendSupportsOs as b7, buildDisplayStackScript as b8, buildSelfhostedBackendSession as b9, makeActiveBackendResolver as bA, mintStreamToken as bB, modalSandboxAttributionEnvironment as bC, modalSandboxAttributionTags as bD, negotiateCapabilities as bE, negotiateSelfhostedCapabilities as bF, nextDurableOpId as bG, offlineAgentError as bH, offlineControlResponse as bI, opAckSubject as bJ, opFrameSubject as bK, parseExecBannerSessionId as bL, parseNumstatZ as bM, parsePorcelainV2 as bN, parseUnifiedPatch as bO, payloadTooLargeMessage as bP, readWorkspaceArchiveFromEnvelopeSessionState as bQ, recordingStorageKey as bR, renderSelfhostedFault as bS, restoredSandboxSessionStateFromEntry as bT, runWithToolCallCorrelation as bU, sandboxStateEntryFromRunState as bV, sanitizeOpIdToken as bW, selectBackend as bX, selfhostedFaultClass as bY, selfhostedLiveness as bZ, selfhostedRetryBackoffMs as b_, buildStreamUrl as ba, buildTerminalServerScript as bb, contentTypeForCodec as bc, createSandboxClient as bd, createSandboxClientForBackend as be, decideSelfhostedRetry as bf, decodeModalSnapshotId as bg, defaultSelfhostedRetryClock as bh, deletePriorPersistedSnapshot as bi, deleteRecordingArtifacts as bj, deserializeSandboxSessionStateEnvelope as bk, desktopCapableBackend as bl, drainingExhaustedError as bm, drainingMessage as bn, ensureDisplayStack as bo, ensureModalRegistryImage as bp, ensureTerminalServer as bq, establishSandboxSessionFromEnvelope as br, execDeadlineHint as bs, exposeStreamPort as bt, extForCodec as bu, inspectRecordingArtifact as bv, isExecSessionLostBanner as bw, isProviderSandboxNotFoundError as bx, isSelfhostedProviderNotFoundError as by, isWorkspaceEscapeError as bz, type ChannelAEmitter as c, setSelfhostedApplyDiff as c0, startRecording as c1, stopRecording as c2, stripExecBanner as c3, subjectFor as c4, swapTargetEstablishability as c5, sweepModalOrphanSandboxes as c6, tagModalSandbox as c7, tearDownDisplayStack as c8, tearDownTerminalServer as c9, terminateModalSandboxById as ca, timeoutAgentError as cb, timeoutControlResponse as cc, uploadRecordingArtifact as cd, verifyStreamToken as ce, type ChannelAExecArgs as d, type ChannelAExecResult as e, ChannelANotFoundError as f, type ChannelASession as g, ChannelAUnsupportedError as h, ChannelAValidationError as i, type ControlRpc as j, DISPLAY_STACK_TIMEOUT_MS as k, type DesktopGeometry as l, DisplayStackError as m, DisplayStackUnsupportedError as n, type EnsureDisplayStackResult as o, type EnsureTerminalServerOptions as p, type EnsureTerminalServerResult as q, type EstablishedSandboxSession as r, type ExposeStreamPortInput as s, type ExposeStreamPortResult as t, type ExposedPortEndpoint as u, FAULT_FIELD_WHAT_PRESERVED as v, FAULT_FIELD_WHAT_TO_TRY as w, FAULT_FIELD_WHICH_LAYER as x, MockAgentResponder as y, type MockAgentResponderOptions as z };