@opengeni/runtime 0.14.1 → 0.14.15

package/src/sandbox/providers/modal.ts

@@ -1,11 +1,23 @@
-import { ModalImageSelector, ModalSandboxClient } from "@openai/agents-extensions/sandbox/modal";
+import {
+  ModalImageSelector,
+  ModalSandboxClient,
+  type ModalSandboxSession,
+  type ModalSandboxSessionState,
+} from "@openai/agents-extensions/sandbox/modal";
 import { effectiveModalIdleTimeoutSeconds } from "@opengeni/config";
 import type { Settings } from "@opengeni/config";
+import {
+  canonicalModalCheckpointProviderBinding,
+  type ModalCheckpointProviderBinding,
+} from "@opengeni/contracts";
 import { CAPABILITY_DESCRIPTORS } from "../capabilities";
 import { SandboxConfigError } from "../errors";
 import type { ProviderRegistration } from "./types";
 
+export type { ModalCheckpointProviderBinding } from "@opengeni/contracts";
+
 const MODAL_ORPHAN_SWEEP_LIMIT = 50;
+const OPENGENI_MODAL_SDK_VERSION = "0.9.0";
 // A provider box is invisible to the lease until Modal create + manifest
 // materialization returns and the creation callback records its instance id.
 // Production baseline (2026-07-15, all 8 turn workers): 155/155 completed creates
@@ -63,6 +75,194 @@ export function modalSandboxAttributionTags(
   };
 }
 
+type MutableModalSnapshotSandbox = {
+  snapshotFilesystem?: (...args: unknown[]) => Promise<unknown>;
+  snapshotDirectory?: (...args: unknown[]) => Promise<unknown>;
+};
+
+type MutableModalSandboxSession = {
+  modal?: { version?: () => string };
+  sandbox?: MutableModalSnapshotSandbox;
+  state?: {
+    workspacePersistence?: string;
+    snapshotFilesystemTimeoutMs?: number;
+  };
+  persistWorkspace?: () => Promise<Uint8Array>;
+  writeStdin?: (args: {
+    sessionId: number;
+    chars?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  }) => Promise<string>;
+};
+
+const modalRetentionWrappedSessions = new WeakSet<object>();
+const modalFilesystemRetentionWrappedSandboxes = new WeakSet<object>();
+const modalDirectoryRetentionWrappedSandboxes = new WeakSet<object>();
+
+const MODAL_EXEC_STDIN_WRITE_PATH =
+  "/modal.task_command_router.TaskCommandRouter/TaskExecStdinWrite";
+const MODAL_EXEC_ALREADY_COMPLETED_DETAILS =
+  /^Exec has already completed; stdin is no longer accepting writes(?: \(Error code: [A-Z0-9]+\))?$/;
+
+/**
+ * Modal proves that the exact exec has already terminated with a typed
+ * FAILED_PRECONDITION from its stdin-write RPC. Keep this deliberately
+ * structural and exact: other FAILED_PRECONDITION errors are not process
+ * lifetime authority.
+ */
+export function isModalExecAlreadyCompletedError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const record = error as {
+    name?: unknown;
+    path?: unknown;
+    code?: unknown;
+    details?: unknown;
+  };
+  return (
+    record.name === "ClientError" &&
+    record.path === MODAL_EXEC_STDIN_WRITE_PATH &&
+    record.code === 9 &&
+    typeof record.details === "string" &&
+    MODAL_EXEC_ALREADY_COMPLETED_DETAILS.test(record.details)
+  );
+}
+
+function assertPinnedModalSdk(session: MutableModalSandboxSession): void {
+  const actualVersion = session.modal?.version?.();
+  if (actualVersion !== OPENGENI_MODAL_SDK_VERSION) {
+    throw new Error(
+      `OpenGeni Modal snapshot compatibility requires modal@${OPENGENI_MODAL_SDK_VERSION}; ` +
+        `the active session reported ${actualVersion ?? "no version"}`,
+    );
+  }
+}
+
+function installModalNativeSnapshotRetention(session: MutableModalSandboxSession): void {
+  const persistence = session.state?.workspacePersistence;
+  if (persistence !== "snapshot_filesystem" && persistence !== "snapshot_directory") {
+    return;
+  }
+  const sandbox = session.sandbox;
+  if (!sandbox || typeof sandbox !== "object") {
+    throw new Error(`Modal ${persistence} persistence has no active provider sandbox`);
+  }
+
+  if (persistence === "snapshot_filesystem") {
+    if (modalFilesystemRetentionWrappedSandboxes.has(sandbox)) return;
+    const snapshotFilesystem = sandbox.snapshotFilesystem;
+    if (typeof snapshotFilesystem !== "function") {
+      throw new Error("Modal snapshot_filesystem persistence is unavailable");
+    }
+    // Agents Extensions 0.13.x still invokes the Modal 0.7 positional timeout
+    // signature. Modal 0.9 moved timeout into an options object and changed the
+    // default Image retention from indefinite to 30 days. Translate at the
+    // provider boundary and retain the Image until OpenGeni's artifact ledger
+    // proves it unreferenced and garbage-collects its exact provider id.
+    sandbox.snapshotFilesystem = async (legacyParams?: unknown) => {
+      if (legacyParams !== undefined && typeof legacyParams !== "number") {
+        throw new Error("Unexpected Modal snapshot_filesystem adapter call shape");
+      }
+      return await snapshotFilesystem.call(sandbox, {
+        ...(legacyParams === undefined ? {} : { timeoutMs: legacyParams }),
+        ttlMs: null,
+      });
+    };
+    modalFilesystemRetentionWrappedSandboxes.add(sandbox);
+    return;
+  }
+
+  if (modalDirectoryRetentionWrappedSandboxes.has(sandbox)) return;
+  const snapshotDirectory = sandbox.snapshotDirectory;
+  if (typeof snapshotDirectory !== "function") {
+    throw new Error("Modal snapshot_directory persistence is unavailable");
+  }
+  sandbox.snapshotDirectory = async (path?: unknown, legacyParams?: unknown) => {
+    if (typeof path !== "string" || legacyParams !== undefined) {
+      throw new Error("Unexpected Modal snapshot_directory adapter call shape");
+    }
+    return await snapshotDirectory.call(sandbox, path, {
+      ...(session.state?.snapshotFilesystemTimeoutMs === undefined
+        ? {}
+        : { timeoutMs: session.state.snapshotFilesystemTimeoutMs }),
+      ttlMs: null,
+    });
+  };
+  modalDirectoryRetentionWrappedSandboxes.add(sandbox);
+}
+
+function installModalExecCompletionRecovery(session: MutableModalSandboxSession): void {
+  const writeStdin = session.writeStdin;
+  if (typeof writeStdin !== "function") return;
+  session.writeStdin = async (args) => {
+    try {
+      return await writeStdin.call(session, args);
+    } catch (error) {
+      if (
+        !isModalExecAlreadyCompletedError(error) ||
+        !Number.isSafeInteger(args.sessionId) ||
+        args.sessionId <= 0
+      ) {
+        throw error;
+      }
+      // Agents Extensions checks its local active-process map before writing,
+      // but the process can finish before Modal receives TaskExecStdinWrite.
+      // An empty retry performs no side effect: it lets the adapter observe the
+      // already-terminal process, delete its stale map entry, and return the
+      // ordinary exact exit banner consumed by OpenGeni's durable settlement.
+      // If that cleanup poll itself loses transport, the original typed
+      // completion is still authoritative and the canonical lost-session
+      // result lets OpenGeni close the exact retained process without failing
+      // the turn or replaying stdin.
+      try {
+        return await writeStdin.call(session, { ...args, chars: "" });
+      } catch {
+        return `write_stdin failed: session not found: ${args.sessionId}`;
+      }
+    }
+  };
+}
+
+/**
+ * Bridge the pinned Agents Extensions Modal adapter to Modal 0.9's provider
+ * contracts. The wrapper re-checks the private provider sandbox on every
+ * capture because snapshot_filesystem hydration replaces that object.
+ */
+export function installOpenGeniModalSnapshotPolicy<T extends object>(session: T): T {
+  const mutable = session as MutableModalSandboxSession;
+  if (modalRetentionWrappedSessions.has(session)) return session;
+  if (typeof mutable.persistWorkspace !== "function") {
+    throw new Error("Modal session does not expose workspace persistence");
+  }
+  assertPinnedModalSdk(mutable);
+  installModalNativeSnapshotRetention(mutable);
+  installModalExecCompletionRecovery(mutable);
+
+  const persistWorkspace = mutable.persistWorkspace.bind(session);
+  mutable.persistWorkspace = async () => {
+    assertPinnedModalSdk(mutable);
+    installModalNativeSnapshotRetention(mutable);
+    return await persistWorkspace();
+  };
+  modalRetentionWrappedSessions.add(session);
+  return session;
+}
+
+export class OpenGeniModalSandboxClient extends ModalSandboxClient {
+  override async create(
+    args?: Parameters<ModalSandboxClient["create"]>[0],
+    manifestOptions?: Parameters<ModalSandboxClient["create"]>[1],
+  ): Promise<ModalSandboxSession> {
+    const session = await super.create(args, manifestOptions);
+    return installOpenGeniModalSnapshotPolicy(session);
+  }
+
+  override async resume(state: ModalSandboxSessionState): Promise<ModalSandboxSession> {
+    const session = await super.resume(state);
+    return installOpenGeniModalSnapshotPolicy(session);
+  }
+}
+
 export const modalProvider: ProviderRegistration = {
   backend: "modal",
   descriptor: CAPABILITY_DESCRIPTORS.modal,
@@ -116,7 +316,7 @@ export const modalProvider: ProviderRegistration = {
     if (settings.modalEnvironment) {
       options.environment = settings.modalEnvironment;
     }
-    return new ModalSandboxClient(options);
+    return new OpenGeniModalSandboxClient(options);
   },
 };
 
@@ -241,7 +441,6 @@ function modalClientOptions(
     ...(settings.modalTokenId ? { tokenId: settings.modalTokenId } : {}),
     ...(settings.modalTokenSecret ? { tokenSecret: settings.modalTokenSecret } : {}),
     ...(settings.modalEnvironment ? { environment: settings.modalEnvironment } : {}),
-    ...(settings.modalTimeoutSeconds ? { timeoutMs: settings.modalTimeoutSeconds * 1000 } : {}),
   };
 }
 
@@ -250,6 +449,237 @@ async function createModalClient(settings: Settings): Promise<ModalClientLike> {
   return new modal.ModalClient(modalClientOptions(settings));
 }
 
+function isModalNotFoundError(error: unknown): boolean {
+  const candidate = error as {
+    name?: unknown;
+    code?: unknown;
+  };
+  // The pinned Modal SDK normalizes image/sandbox NOT_FOUND and its documented
+  // FAILED_PRECONDITION alias to NotFoundError. Numeric gRPC code 5 is retained
+  // for narrow adapter/fake compatibility. Never classify message text: an auth,
+  // workspace, DNS, or proxy error containing "not found" is not deletion proof.
+  return candidate?.name === "NotFoundError" || candidate?.code === 5;
+}
+
+async function modalCheckpointProviderBindingForClient(
+  settings: Settings,
+  modal: ModalClientLike,
+): Promise<ModalCheckpointProviderBinding> {
+  const identity = await modal.cpClient.workspaceNameLookup({});
+  const workspaceName = identity.workspaceName || identity.username;
+  if (!workspaceName) {
+    throw new Error("Modal credential resolved no workspace identity");
+  }
+  const resolved = canonicalModalCheckpointProviderBinding({
+    version: 1,
+    serverUrl: modal.profile.serverUrl,
+    workspaceName,
+    // Resolve through the authenticated client, not the optional OpenGeni
+    // override alone. When the override is absent Modal may select a profile
+    // environment; persisting "" would fail to fence a later profile change.
+    environment: modal.environmentName(settings.modalEnvironment),
+  });
+  if (!resolved) {
+    throw new Error("Modal credential resolved an invalid checkpoint provider identity");
+  }
+  return resolved.binding;
+}
+
+const modalSessionCheckpointBindings = new WeakMap<
+  object,
+  Promise<{ key: string; binding: ModalCheckpointProviderBinding }>
+>();
+
+/**
+ * Resolve checkpoint ownership through the exact authenticated Modal client
+ * embedded in the session that creates the snapshot. The field is private in
+ * the pinned Agents extension, so this adapter is intentionally fail-closed:
+ * an upstream shape change disables native publication instead of guessing
+ * ownership from a newly-resolved ambient profile.
+ */
+export async function resolveModalCheckpointProviderBindingForSession(
+  settings: Settings,
+  session: unknown,
+): Promise<{ key: string; binding: ModalCheckpointProviderBinding }> {
+  if (!session || typeof session !== "object") {
+    throw new Error("Modal checkpoint session identity is unavailable");
+  }
+  const cached = modalSessionCheckpointBindings.get(session);
+  if (cached) return await cached;
+  const modal = (session as { modal?: unknown }).modal as ModalClientLike | undefined;
+  if (
+    !modal ||
+    typeof modal.cpClient?.workspaceNameLookup !== "function" ||
+    typeof modal.profile?.serverUrl !== "string" ||
+    typeof modal.environmentName !== "function"
+  ) {
+    throw new Error("Pinned Modal session no longer exposes its authenticated checkpoint identity");
+  }
+  const pending = modalCheckpointProviderBindingForClient(settings, modal).then(
+    (binding) => canonicalModalCheckpointProviderBinding(binding)!,
+  );
+  modalSessionCheckpointBindings.set(session, pending);
+  try {
+    return await pending;
+  } catch (error) {
+    modalSessionCheckpointBindings.delete(session);
+    throw error;
+  }
+}
+
+/** Compare a restore receipt against the exact authenticated Modal client
+ * embedded in the created session. This deliberately does not resolve a second
+ * ambient client: the session that will consume the snapshot is the authority. */
+export async function modalSessionMatchesCheckpointProviderBinding(
+  settings: Settings,
+  session: unknown,
+  expectedBindingKey: string,
+): Promise<boolean> {
+  const identity = await resolveModalCheckpointProviderBindingForSession(settings, session);
+  return identity.key === expectedBindingKey;
+}
+
+/** Resolve the authoritative Modal workspace behind the configured credential.
+ * Snapshot ids are workspace-scoped; persisting this non-secret binding lets GC
+ * reject a credential rotation that points at a different workspace instead of
+ * issuing a destructive call under ambient credentials. */
+export async function resolveModalCheckpointProviderBinding(
+  settings: Settings,
+  createClient: (settings: Settings) => Promise<ModalClientLike> = createModalClient,
+): Promise<{ key: string; binding: ModalCheckpointProviderBinding }> {
+  const modal = await createClient(settings);
+  try {
+    const binding = await modalCheckpointProviderBindingForClient(settings, modal);
+    return canonicalModalCheckpointProviderBinding(binding)!;
+  } finally {
+    modal.close();
+  }
+}
+
+/** Prove a legacy lease's live sandbox is visible in the same Modal namespace
+ * whose identity will own the adopted checkpoint row. */
+export async function resolveModalCheckpointProviderBindingForLiveSandbox(
+  settings: Settings,
+  sandboxId: string,
+  createClient: (settings: Settings) => Promise<ModalClientLike> = createModalClient,
+): Promise<{ key: string; binding: ModalCheckpointProviderBinding }> {
+  if (!sandboxId) throw new Error("Modal live-sandbox identity requires a sandbox id");
+  const modal = await createClient(settings);
+  try {
+    const binding = await modalCheckpointProviderBindingForClient(settings, modal);
+    const sandbox = await modal.sandboxes.fromId(sandboxId);
+    const exitCode = await sandbox.poll();
+    if (exitCode !== null) {
+      throw new Error(`Modal sandbox ${sandboxId} is no longer running`);
+    }
+    return canonicalModalCheckpointProviderBinding(binding)!;
+  } finally {
+    modal.close();
+  }
+}
+
+/**
+ * Observe one exact historical Modal sandbox without consulting the current
+ * lease or its (possibly successor-owned) resume envelope. This is deliberately
+ * lifecycle-only: a running sandbox does not prove whether an individual
+ * retained process is still running, while a terminal/missing sandbox proves
+ * that none of its processes can still execute.
+ */
+export async function inspectModalSandboxLifecycle(
+  settings: Settings,
+  sandboxId: string,
+  expectedBindingKey?: string | null,
+  createClient: (settings: Settings) => Promise<ModalClientLike> = createModalClient,
+): Promise<
+  | {
+      status: "running";
+      providerBindingKey: string;
+      providerBinding: ModalCheckpointProviderBinding;
+    }
+  | {
+      status: "terminated";
+      exitCode: number;
+      providerBindingKey: string;
+      providerBinding: ModalCheckpointProviderBinding;
+    }
+  | {
+      status: "not_found";
+      providerBindingKey: string;
+      providerBinding: ModalCheckpointProviderBinding;
+    }
+> {
+  if (!sandboxId) throw new Error("Modal lifecycle inspection requires a sandbox id");
+  const modal = await createClient(settings);
+  try {
+    const binding = canonicalModalCheckpointProviderBinding(
+      await modalCheckpointProviderBindingForClient(settings, modal),
+    )!;
+    if (expectedBindingKey && binding.key !== expectedBindingKey) {
+      throw new Error(
+        "Modal lifecycle inspection refused because the configured credential workspace changed",
+      );
+    }
+    try {
+      const sandbox = await modal.sandboxes.fromId(sandboxId);
+      const exitCode = await sandbox.poll();
+      return exitCode === null
+        ? {
+            status: "running",
+            providerBindingKey: binding.key,
+            providerBinding: binding.binding,
+          }
+        : {
+            status: "terminated",
+            exitCode,
+            providerBindingKey: binding.key,
+            providerBinding: binding.binding,
+          };
+    } catch (error) {
+      if (isModalNotFoundError(error)) {
+        return {
+          status: "not_found",
+          providerBindingKey: binding.key,
+          providerBinding: binding.binding,
+        };
+      }
+      throw error;
+    }
+  } finally {
+    modal.close();
+  }
+}
+
+export async function deleteModalCheckpointSnapshot(
+  settings: Settings,
+  expectedBindingKey: string,
+  snapshotId: string,
+  createClient: (settings: Settings) => Promise<ModalClientLike> = createModalClient,
+): Promise<"deleted" | "not_found"> {
+  if (!snapshotId) throw new Error("Modal checkpoint deletion requires a snapshot id");
+  // Resolve identity and delete through the same authenticated client. A cached
+  // or separately-created identity probe could approve workspace A and then
+  // issue the destructive call through a rotated ambient profile for workspace B.
+  const modal = await createClient(settings);
+  try {
+    const binding = await modalCheckpointProviderBindingForClient(settings, modal);
+    const identity = canonicalModalCheckpointProviderBinding(binding)!;
+    if (expectedBindingKey !== identity.key) {
+      throw new Error(
+        "Modal checkpoint deletion refused because the configured credential workspace changed",
+      );
+    }
+    try {
+      await modal.images.delete(snapshotId);
+      return "deleted";
+    } catch (error) {
+      if (isModalNotFoundError(error)) return "not_found";
+      throw error;
+    }
+  } finally {
+    modal.close();
+  }
+}
+
 export async function tagModalSandbox(
   settings: Settings,
   sandboxId: string,

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

@@ -32,6 +32,7 @@ import { SelfhostedControlError } from "../selfhosted/control-rpc";
 import { renderSelfhostedFault } from "../selfhosted/fault-rendering";
 import { isExecSessionLostBanner } from "../channel-a";
 import { parseExecBannerExitCode, parseExecBannerSessionId } from "../exec-banner";
+import { withSandboxProviderOperation } from "../provider-operation-gate";
 
 /** 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
@@ -794,7 +795,9 @@ export class RoutingSandboxSession implements RoutableBackendSession {
     if (!write) throw new RoutingUnsupportedError(op, record.backend.kind);
     let result: string;
     try {
-      result = await write.call(record.backend.session, args);
+      result = await withSandboxProviderOperation(record.backend.session, () =>
+        write.call(record.backend.session, args),
+      );
     } catch (error) {
       if (this.deps.afterProcessMutation) {
         const pending: PendingProcessMutationSettlement = {
@@ -856,7 +859,9 @@ export class RoutingSandboxSession implements RoutableBackendSession {
     await this.ensureParentPromotion(record);
     const write = record.backend.session.writeStdin;
     if (!write) throw new RoutingUnsupportedError("writeStdin", record.backend.kind);
-    const result = await write.call(record.backend.session, args);
+    const result = await withSandboxProviderOperation(record.backend.session, () =>
+      write.call(record.backend.session, args),
+    );
     const proof = retainedProcessTerminalProof(result, providerSessionId);
     if (proof) await this.settleRetainedProcess(record, proof, result);
     return result;
@@ -890,7 +895,7 @@ export class RoutingSandboxSession implements RoutableBackendSession {
         : undefined;
       let result: T;
       try {
-        result = await fn(backend.session);
+        result = await withSandboxProviderOperation(backend.session, () => fn(backend.session));
       } catch (error) {
         if (mutatesWorkspace && this.deps.afterMutation) {
           try {
@@ -1162,11 +1167,19 @@ export class RoutingSandboxSession implements RoutableBackendSession {
       return terminal.result;
     }
     await this.ensureParentPromotion(record);
-    if (record.backend.session.execCommand) {
-      return await record.backend.session.execCommand(args);
+    const execCommand = record.backend.session.execCommand;
+    if (execCommand) {
+      return await withSandboxProviderOperation(record.backend.session, () =>
+        execCommand.call(record.backend.session, args),
+      );
     }
-    if (record.backend.session.exec) {
-      return formatExecResult(await record.backend.session.exec(args));
+    const exec = record.backend.session.exec;
+    if (exec) {
+      return formatExecResult(
+        await withSandboxProviderOperation(record.backend.session, () =>
+          exec.call(record.backend.session, args),
+        ),
+      );
     }
     throw new RoutingUnsupportedError("execCommand", record.backend.kind);
   }
@@ -1228,7 +1241,22 @@ export class RoutingSandboxSession implements RoutableBackendSession {
       if (!s.materializeEntry) {
         throw new RoutingUnsupportedError("materializeEntry", this.cached?.kind ?? "unknown");
       }
-      return s.materializeEntry(args);
+      await s.materializeEntry(args);
+
+      // The local Docker SDK materializes through a host path and then bind-mounts
+      // that path into the sandbox. A containerized worker using the host Docker
+      // socket can otherwise write into its own container layer while the sandbox
+      // sees a different, empty host directory. `pathExists()` and `readFile()` on
+      // that SDK session inspect the worker-side path, so only a command executed
+      // inside the actual sandbox proves the materialized path is usable by the
+      // agent. Never let lazy `load_skill` report success on a split workspace.
+      const path =
+        args && typeof args === "object" && typeof (args as { path?: unknown }).path === "string"
+          ? (args as { path: string }).path
+          : null;
+      if (path) {
+        await assertProviderCanSeeMaterializedPath(s, path);
+      }
     });
   }
 
@@ -1304,3 +1332,51 @@ export class RoutingSandboxSession implements RoutableBackendSession {
     return this.resolve();
   }
 }
+
+const MATERIALIZED_PATH_MARKER = "__OPENGENI_MATERIALIZED_PATH_VISIBLE__";
+
+async function assertProviderCanSeeMaterializedPath(
+  session: RoutableBackendSession,
+  path: string,
+): Promise<void> {
+  const command = `test -e ${shellSingleQuote(path)} && printf %s ${shellSingleQuote(
+    MATERIALIZED_PATH_MARKER,
+  )}`;
+  const args = {
+    cmd: command,
+    workdir: providerManifestRoot(session) ?? "/workspace",
+    shell: "sh",
+    login: false,
+    tty: false,
+  };
+  let output: string;
+  if (session.execCommand) {
+    output = await session.execCommand(args);
+  } else if (session.exec) {
+    output = formatExecResult(await session.exec(args));
+  } else {
+    throw new RoutingUnsupportedError("materializeEntry.verify", "unknown");
+  }
+  if (!output.includes(MATERIALIZED_PATH_MARKER)) {
+    throw new Error(
+      `Sandbox materialization completed but the provider cannot read the destination path: ${path}`,
+    );
+  }
+}
+
+function providerManifestRoot(session: RoutableBackendSession): string | null {
+  const root = (
+    session.state as
+      | {
+          manifest?: {
+            root?: unknown;
+          };
+        }
+      | undefined
+  )?.manifest?.root;
+  return typeof root === "string" && root.length > 0 ? root : null;
+}
+
+function shellSingleQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}

package/src/sandbox/selfhosted/session.ts

@@ -569,10 +569,11 @@ export class SelfhostedSession {
     }
   }
 
-  /** 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(): number {
+  /** The effective clamped exec process deadline (ms): the exec-specific budget
+   *  when threaded, else the control timeout. Public so adapters that project a
+   *  structured command receipt can report the exact deadline the agent enforces
+   *  instead of repeating (and potentially drifting from) this normalization. */
+  get effectiveExecDeadlineMs(): number {
     // exec gets its OWN (much larger) deadline distinct from the short control
     // timeout — a real command routinely outlives 30s. Falls back to `timeoutMs`
     // when no exec deadline is threaded (unchanged for those callers).
@@ -587,7 +588,7 @@ export class SelfhostedSession {
     // Keep the process deadline inside the request/reply deadline. Previously the
     // wire carried timeoutMs=0 (unbounded) while the caller stopped waiting after
     // ~30s, leaving accepted work invisible and able to starve control liveness.
-    const executionTimeoutMs = this.execDeadlineMs();
+    const executionTimeoutMs = this.effectiveExecDeadlineMs;
     const execReq: ExecRequest = {
       // The agent does NOT shell-interpret unless `shell` — Channel-A passes a
       // single shell command string, so run it through the platform shell.
@@ -736,7 +737,7 @@ export class SelfhostedSession {
   async execCommand(args: { cmd: string; workdir?: string; runAs?: string }): Promise<string> {
     const result = await this.exec({ cmd: args.cmd, workdir: args.workdir, runAs: args.runAs });
     if (result.timedOut) {
-      const hint = execDeadlineHint(Math.round(this.execDeadlineMs() / 1000));
+      const hint = execDeadlineHint(Math.round(this.effectiveExecDeadlineMs / 1000));
       return result.output ? `${result.output}\n${hint}` : hint;
     }
     return result.output;