@opengeni/runtime 3.0.1 → 4.0.0

package/src/sandbox/providers/modal-command-control.ts

@@ -1,136 +1,67 @@
+import { randomUUID, randomBytes } from "node:crypto";
 import { posix } from "node:path";
-import { ModalClient } from "modal";
-import { SandboxProviderCommand } from "@opengeni/contracts";
-import type { ChannelAExecArgs } from "../channel-a";
 import { shellQuote } from "@openai/agents-core/sandbox/internal";
+import {
+  SandboxProviderCommand,
+  CommandSupervisionReceipt,
+  type ModalRouterProviderCommand,
+} from "@opengeni/contracts";
+import type { ChannelAExecArgs } from "../channel-a";
+import type { ProviderCommandOutput } from "../provider-command-session";
+import {
+  admittedCommandSupervisionReady,
+  markPendingCommandSupervised,
+  reserveSupervisedLaunch,
+} from "../provider-command-session";
+import {
+  ModalCommandControl as LegacyControl,
+  commandControlPlane,
+  decodePage,
+} from "./modal-legacy-command-control";
+import {
+  ModalCommandRouterWire,
+  ModalCommandStartRejectedError,
+} from "./modal-command-router-wire";
 
-type ControlPlane = Pick<
-  ModalClient["cpClient"],
-  "sandboxGetTaskId" | "containerExec" | "containerExecGetOutput" | "containerExecPutInput"
->;
-
-type CommandClient = Pick<ModalClient, "cpClient" | "version"> &
-  Partial<Pick<ModalClient, "profile" | "logger">>;
-type GrpcMiddleware = NonNullable<
-  NonNullable<ConstructorParameters<typeof ModalClient>[0]>["grpcMiddleware"]
->[number];
-/** This dedicated command client never retries a request behind the caller's
- * back and preserves the exact cancellation signal, including streaming RPCs. */
-export const modalCommandAbortMiddleware: GrpcMiddleware = async function* (call, options) {
-  options.signal?.throwIfAborted();
-  return yield* call.next(call.request, options);
-};
-
-// Version-pinned compatibility boundary: 0.9.0's retryMiddleware drops signal
-// for streaming and retries=0. Its public custom middleware runs OUTSIDE that
-// branch, so cannot repair it. Override only this dedicated instance's factory
-// hook before construction; never mutate the SDK's global prototype or use
-// negative/fractional retry counts to manipulate its branch conditions.
-type PublicModalClient = Pick<ModalClient, keyof ModalClient>;
-const ModalClientBase: new (
-  options?: ConstructorParameters<typeof ModalClient>[0],
-) => PublicModalClient = ModalClient;
-class ModalCommandClient extends ModalClientBase {
-  retryMiddleware(): GrpcMiddleware {
-    return modalCommandAbortMiddleware;
-  }
-}
-const controlClients = new WeakMap<object, PublicModalClient>();
-
-function commandControlPlane(client: CommandClient): ControlPlane {
-  // Minimal injected control planes are used by deterministic unit tests.
-  // Production installation requires the authenticated SDK profile below.
-  if (!client.profile) return client.cpClient;
-  if (typeof Reflect.get(ModalClient.prototype, "retryMiddleware") !== "function")
-    throw new Error("Verified Modal command cancellation contract is unavailable");
-  let controlled = controlClients.get(client);
-  if (!controlled) {
-    const profile = client.profile;
-    if (!profile.tokenId || !profile.tokenSecret)
-      throw new Error("Modal command control requires its original authenticated profile");
-    controlled = new ModalCommandClient({
-      tokenId: profile.tokenId,
-      tokenSecret: profile.tokenSecret,
-      endpoint: profile.serverUrl,
-      environment: profile.environment ?? "",
-      ...(profile.maxThrottleWaitSecs !== undefined
-        ? { maxThrottleWaitSecs: profile.maxThrottleWaitSecs }
-        : {}),
-      ...(client.logger ? { logger: client.logger } : {}),
-    });
-    controlClients.set(client, controlled);
-  }
-  return controlled.cpClient;
-}
-export type ModalCommandStream = "stdout" | "stderr";
+export { modalCommandAbortMiddleware } from "./modal-legacy-command-control";
 export type ModalProviderCommand = SandboxProviderCommand;
-export type ModalProviderOutputPage = {
-  command: ModalProviderCommand;
-  chunks: Array<{ stream: ModalCommandStream; chunkId: string; text: string }>;
-  exitCode: number | null;
-  streamFidelity: "separate" | "merged";
-};
+export type ModalProviderOutputPage = ProviderCommandOutput;
 
-// A provider batch may end halfway through a UTF-8 character. Keep only that
-// unfinished suffix in protected cursor state; invalid complete bytes still
-// use the usual replacement-character decoding policy.
-function decodePage(prior: string, input: Uint8Array[], terminal: boolean) {
-  const bytes = Buffer.concat([Buffer.from(prior, "base64"), ...input]);
-  let boundary = bytes.length;
-  if (!terminal) {
-    for (let start = Math.max(0, bytes.length - 3); start < bytes.length; start++) {
-      const first = bytes[start]!;
-      const width =
-        first >= 0xc2 && first <= 0xdf
-          ? 2
-          : first >= 0xe0 && first <= 0xef
-            ? 3
-            : first >= 0xf0 && first <= 0xf4
-              ? 4
-              : 0;
-      if (!width || bytes.length - start >= width) continue;
-      const suffix = bytes.subarray(start + 1);
-      if (!suffix.every((byte) => byte >= 0x80 && byte <= 0xbf)) continue;
-      const second = suffix[0];
-      if (
-        second !== undefined &&
-        ((first === 0xe0 && second < 0xa0) ||
-          (first === 0xed && second > 0x9f) ||
-          (first === 0xf0 && second < 0x90) ||
-          (first === 0xf4 && second > 0x8f))
-      )
-        continue;
-      boundary = start;
-      break;
-    }
-  }
-  return {
-    text: bytes.subarray(0, boundary).toString("utf8"),
-    remainder: bytes.subarray(boundary).toString("base64"),
-  };
-}
+type Client = Parameters<typeof commandControlPlane>[0];
+type RouterEntry = {
+  router: ModalCommandRouterWire;
+  users: number;
+  refreshAt: number;
+  idle?: ReturnType<typeof setTimeout>;
+};
 
-/** Version-pinned Modal control-plane boundary. Execution identity, output
- * batches and exit status come from authenticated provider RPCs, never sandbox
- * files or an SDK object's in-memory process map. Callers must store the
- * returned locator/cursors outside the command's write authority. */
+/** New commands use replayable task-router byte offsets. Legacy identifiers
+ * never cross that protocol boundary and are never used for new starts. */
 export class ModalCommandControl {
+  private readonly routers = new Map<string, Promise<RouterEntry>>();
+  private readonly client: ReturnType<typeof commandControlPlane>;
+  private readonly legacy: LegacyControl;
+  private closed = false;
+
   private constructor(
-    private readonly client: ControlPlane,
+    client: Client,
     private readonly sandboxIdentity: string | (() => string),
     private readonly root: string,
-    private readonly environment: Record<string, string> | (() => Record<string, string>) = {},
-  ) {}
+    private readonly environment: Record<string, string> | (() => Record<string, string>),
+  ) {
+    this.client = commandControlPlane(client);
+    this.legacy = LegacyControl.forSandbox(client, sandboxIdentity, root, environment);
+  }
 
   static forSandbox(
-    client: CommandClient,
+    client: Client,
     sandboxId: string | (() => string),
     root: string,
     environment: Record<string, string> | (() => Record<string, string>) = {},
   ): ModalCommandControl {
     if (client.version() !== "0.9.0")
       throw new Error("Modal command control requires the verified 0.9.0 SDK contract");
-    return new ModalCommandControl(commandControlPlane(client), sandboxId, root, environment);
+    return new ModalCommandControl(client, sandboxId, root, environment);
   }
 
   private get sandboxId(): string {
@@ -139,164 +70,377 @@ export class ModalCommandControl {
       : this.sandboxIdentity;
   }
 
-  async start(args: ChannelAExecArgs, signal?: AbortSignal): Promise<ModalProviderCommand> {
+  private async withRouter<T>(
+    taskId: string,
+    signal: AbortSignal | undefined,
+    run: (router: ModalCommandRouterWire) => Promise<T>,
+  ): Promise<T> {
+    signal?.throwIfAborted();
+    if (this.closed) throw new Error("Modal command control is closed");
+    let pending = this.routers.get(taskId);
+    const reused = Boolean(pending);
+    if (!pending) {
+      pending = (async () => {
+        const access = await this.client.taskGetCommandRouterAccess(
+          { taskId },
+          signal ? { signal } : undefined,
+        );
+        let refreshAt = Date.now() + 60_000;
+        try {
+          // Expiry only shortens cache lifetime; it never authenticates access.
+          const payload = JSON.parse(
+            Buffer.from(access.jwt.split(".")[1] ?? "", "base64url").toString(),
+          );
+          if (typeof payload.exp === "number" && Number.isFinite(payload.exp))
+            refreshAt = Math.min(refreshAt, payload.exp * 1000 - 15_000);
+        } catch {
+          /* Authentication remains the provider's responsibility. */
+        }
+        return { router: new ModalCommandRouterWire(access), users: 0, refreshAt };
+      })();
+      this.routers.set(taskId, pending);
+      void pending.catch(() => {
+        if (this.routers.get(taskId) === pending) this.routers.delete(taskId);
+      });
+    }
+    const entry = await pending;
+    // Refresh credentials between operations, never close another active read.
+    if (reused && !entry.users && Date.now() > entry.refreshAt) {
+      clearTimeout(entry.idle);
+      entry.router.close();
+      this.routers.delete(taskId);
+      return await this.withRouter(taskId, signal, run);
+    }
+    clearTimeout(entry.idle);
+    entry.users++;
+    try {
+      signal?.throwIfAborted();
+      return await run(entry.router);
+    } finally {
+      entry.users--;
+      if (!entry.users) {
+        entry.idle = setTimeout(() => {
+          if (this.routers.get(taskId) === pending && !entry.users) {
+            this.routers.delete(taskId);
+            entry.router.close();
+          }
+        }, 30_000);
+        entry.idle.unref?.();
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    const entries = await Promise.allSettled(this.routers.values());
+    this.routers.clear();
+    for (const entry of entries)
+      if (entry.status === "fulfilled") {
+        clearTimeout(entry.value.idle);
+        entry.value.router.close();
+      }
+  }
+
+  async start(args: ChannelAExecArgs, signal?: AbortSignal): Promise<ModalRouterProviderCommand> {
     signal?.throwIfAborted();
+    const supervised = admittedCommandSupervisionReady() && !args.tty && !args.runAs;
+    if (supervised) markPendingCommandSupervised();
+    const sandboxId = this.sandboxId;
     const workdir = posix.resolve(this.root, args.workdir ?? this.root);
     if (workdir !== this.root && !workdir.startsWith(`${this.root.replace(/\/$/u, "")}/`))
       throw new Error("Command workdir is outside the sandbox workspace");
-    // Hydration replaces the SDK sandbox. Freeze its current identity for this
-    // start so an asynchronous replacement cannot relabel the returned locator.
-    const sandboxId = this.sandboxId;
     const task = await this.client.sandboxGetTaskId({ sandboxId }, signal ? { signal } : undefined);
     if (!task.taskId || task.taskResult) throw new Error("Modal command task is unavailable");
-    if (sandboxId !== this.sandboxId)
+    const taskId = task.taskId;
+    if (this.sandboxId !== sandboxId)
       throw new Error("Modal sandbox changed during command preparation");
-    const login = args.shell ? (args.login ?? true) : false;
-    let command = [args.shell ?? "/bin/sh", login ? "-lc" : "-c", args.cmd];
+    const execId = randomUUID();
+    // PTY and runAs retain their existing explicit unsupported supervision
+    // semantics. Never attach a fabricated descriptor to either path.
+    const invocationId = randomUUID();
+    const supervision = supervised
+      ? {
+          protocol: "native-subreaper-v1" as const,
+          invocationId,
+          nonce: randomBytes(32).toString("hex"),
+          controlPath: `/tmp/opengeni-supervision/${invocationId}.sock`,
+        }
+      : undefined;
+    let commandArgs = [
+      args.shell ?? "/bin/sh",
+      args.shell && (args.login ?? true) ? "-lc" : "-c",
+      args.cmd,
+    ];
     if (args.runAs) {
-      const user = shellQuote(args.runAs);
-      const invocation = command.map(shellQuote).join(" ");
-      const script = `if [ "$(id -u)" = ${user} ] || [ "$(id -un 2>/dev/null)" = ${user} ]; then exec ${invocation}; elif [ "$(id -u)" = 0 ]; then exec su -s /bin/sh ${user} -c ${shellQuote(`exec ${invocation}`)}; else exec sudo -n -u ${user} -- ${invocation}; fi`;
-      command = ["/bin/sh", "-c", script];
+      const user = shellQuote(args.runAs),
+        invocation = commandArgs.map(shellQuote).join(" ");
+      commandArgs = [
+        "/bin/sh",
+        "-c",
+        `if [ "$(id -u)" = ${user} ] || [ "$(id -un 2>/dev/null)" = ${user} ]; then exec ${invocation}; elif [ "$(id -u)" = 0 ]; then exec su -s /bin/sh ${user} -c ${shellQuote(`exec ${invocation}`)}; else exec sudo -n -u ${user} -- ${invocation}; fi`,
+      ];
     }
-    const environment =
-      typeof this.environment === "function" ? this.environment() : this.environment;
-    if (Object.keys(environment).length) {
-      command = [
-        "/usr/bin/env",
+    const env = typeof this.environment === "function" ? this.environment() : this.environment;
+    if (supervision)
+      commandArgs = [
+        "/usr/local/bin/opengeni-command-supervisor",
+        "launch",
+        "--invocation",
+        supervision.invocationId,
+        "--nonce",
+        supervision.nonce,
+        "--socket",
+        supervision.controlPath,
         "--",
-        ...Object.entries(environment).map(([key, value]) => `${key}=${value}`),
-        ...command,
+        ...commandArgs,
       ];
-    }
-    // Do not retry this mutating start on an ambiguous transport error: this
-    // provider API assigns the execution id in its response, not in our request.
-    const result = await this.client.containerExec(
-      {
-        taskId: task.taskId,
-        command,
-        terminateContainerOnExit: false,
-        runtimeDebug: false,
-        stdoutOutput: 2,
-        stderrOutput: 2,
-        timeoutSecs: 0,
-        workdir,
-        secretIds: [],
-        ...(args.tty
-          ? {
-              ptyInfo: {
-                enabled: true,
-                winszRows: 24,
-                winszCols: 80,
-                envTerm: "xterm",
-                envColorterm: "",
-                envTermProgram: "",
-                ptyType: 1,
-                noTerminateOnIdleStdin: true,
-              },
-            }
-          : {}),
-      },
-      { retries: 0, ...(signal ? { signal } : {}) },
-    );
-    if (!result.execId) throw new Error("Modal command start returned no execution identity");
-    return {
-      kind: "modal-control-v1",
+    const command: ModalRouterProviderCommand = {
+      kind: "modal-router-v1",
       sandboxId,
-      taskId: task.taskId,
-      execId: result.execId,
+      taskId,
+      execId,
       ...(args.tty ? { pty: true } : {}),
+      ...(supervision ? { supervision } : {}),
       streams: {
-        stdout: { batchIndex: 0, utf8Remainder: "", exitCode: null },
-        stderr: { batchIndex: 0, utf8Remainder: "", exitCode: null },
+        stdout: { byteOffset: 0, utf8Remainder: "", eof: false, exitCode: null },
+        stderr: { byteOffset: 0, utf8Remainder: "", eof: false, exitCode: null },
       },
     };
+    if (supervision) await reserveSupervisedLaunch(command);
+    try {
+      await this.withRouter(taskId, signal, (router) =>
+        router.start(
+          {
+            taskId,
+            execId,
+            commandArgs,
+            workdir,
+            env,
+            ...(args.tty
+              ? {
+                  ptyInfo: {
+                    enabled: true,
+                    winszRows: 24,
+                    winszCols: 80,
+                    envTerm: "xterm",
+                    ptyType: 1,
+                    noTerminateOnIdleStdin: true,
+                  },
+                }
+              : {}),
+          },
+          signal,
+        ),
+      );
+    } catch (error) {
+      // A client-chosen router id remains the only possible invocation. The
+      // supervisor is idle, so an ambiguous launch never ran user code. Retain
+      // the descriptor and reconcile that id; do not replay the start.
+      if (!supervision || error instanceof ModalCommandStartRejectedError) throw error;
+    }
+    return command;
+  }
+
+  /** Read-only, authenticated control execution on this exact instance. Never
+   * inferred from a fleet image selector or user command stdout. No cache: warm
+   * instances and route/task replacement must each pass before admission. */
+  async verifySupervisionCapability(): Promise<{ sandboxId: string; taskId: string }> {
+    const sandboxId = this.sandboxId;
+    const signal = AbortSignal.timeout(5_000);
+    const task = await this.client.sandboxGetTaskId({ sandboxId }, { signal });
+    if (!task.taskId || task.taskResult) throw new Error("Modal command task is unavailable");
+    await this.withRouter(task.taskId, signal, async (router) => {
+      const identity = { taskId: task.taskId!, execId: randomUUID() };
+      await router.start(
+        {
+          ...identity,
+          commandArgs: ["/usr/local/bin/opengeni-command-supervisor", "capabilities"],
+          workdir: "/tmp",
+          env: {},
+        },
+        signal,
+      );
+      let offset = 0;
+      let output = "";
+      let eof = false;
+      let exit: number | null = null;
+      while (!eof || exit === null) {
+        signal.throwIfAborted();
+        const page = await router.read(identity, "stdout", offset, 250, signal);
+        offset += page.bytes.length;
+        if (offset > 128) throw new Error("Modal supervision capability response exceeds bound");
+        output += page.bytes.toString("utf8");
+        eof = page.eof;
+        exit = await router.poll(identity, signal);
+      }
+      if (exit !== 0 || output !== "native-subreaper-v1")
+        throw new Error(
+          "Exact Modal instance lacks compatible native supervision; command not admitted",
+        );
+    });
+    if (sandboxId !== this.sandboxId)
+      throw new Error("Modal instance changed during supervision capability verification");
+    return { sandboxId, taskId: task.taskId };
+  }
+
+  /** Separate authenticated provider execution of the installed control helper.
+   * User command streams are never inspected for control evidence. */
+  async supervisionControl(
+    command: ModalRouterProviderCommand,
+    action: "release" | "cancel" | "status" | "ack",
+    receiptId?: string,
+  ): Promise<{ state: "idle" | "running" | "quiescent"; receipt?: CommandSupervisionReceipt }> {
+    SandboxProviderCommand.parse(command);
+    const descriptor = command.supervision;
+    if (!descriptor || command.sandboxId !== this.sandboxId)
+      throw new Error("Supervised command identity is unavailable");
+    const identity = { taskId: command.taskId, execId: randomUUID() };
+    const signal = AbortSignal.timeout(5_000);
+    return await this.withRouter(command.taskId, signal, async (router) => {
+      await router.start(
+        {
+          ...identity,
+          commandArgs: [
+            "/usr/local/bin/opengeni-command-supervisor",
+            "control",
+            "--invocation",
+            descriptor.invocationId,
+            "--nonce",
+            descriptor.nonce,
+            "--socket",
+            descriptor.controlPath,
+            "--action",
+            action,
+            ...(receiptId ? ["--receipt", receiptId] : []),
+          ],
+          workdir: "/tmp",
+          env: {},
+        },
+        signal,
+      );
+      const buffers: Buffer[] = [];
+      let offset = 0;
+      let eof = false;
+      let exit: number | null = null;
+      while (!eof || exit === null) {
+        signal.throwIfAborted();
+        const page = await router.read(identity, "stdout", offset, 250, signal);
+        offset += page.bytes.length;
+        if (offset > 4096) throw new Error("Supervisor control response exceeds its bound");
+        buffers.push(page.bytes);
+        eof = page.eof;
+        exit = await router.poll(identity, signal);
+      }
+      if (exit !== 0) throw new Error("Supervisor control is unavailable");
+      const result = JSON.parse(Buffer.concat(buffers).toString("utf8"));
+      if (!result || !["idle", "running", "quiescent"].includes(result.state))
+        throw new Error("Invalid supervisor control response");
+      if (result.receipt !== undefined) {
+        result.receipt = CommandSupervisionReceipt.parse(result.receipt);
+        if (result.receipt.invocationId !== descriptor.invocationId)
+          throw new Error("Supervisor receipt invocation mismatch");
+      }
+      if ((result.state === "quiescent") !== Boolean(result.receipt))
+        throw new Error("Supervisor quiescence response lacks its receipt");
+      return result;
+    });
   }
 
   async read(
     command: ModalProviderCommand,
-    yieldTimeMs: number,
+    waitMs: number,
     signal?: AbortSignal,
   ): Promise<ModalProviderOutputPage> {
-    signal?.throwIfAborted();
-    this.assertIdentity(command);
+    SandboxProviderCommand.parse(command);
+    if (command.sandboxId !== this.sandboxId)
+      throw new Error("Modal command does not belong to this sandbox");
+    if (command.kind === "modal-control-v1") return await this.legacy.read(command, waitMs, signal);
     const next = structuredClone(command);
-    const pages = await Promise.all(
-      (["stdout", "stderr"] as const).map(async (stream) => {
-        const cursor = command.streams[stream];
-        if (cursor.exitCode !== null) return null;
-        const descriptor = stream === "stdout" ? 1 : 2;
-        for await (const batch of this.client.containerExecGetOutput(
-          {
-            execId: command.execId,
-            timeout: Math.max(0, yieldTimeMs) / 1000,
-            lastBatchIndex: cursor.batchIndex,
-            fileDescriptor: descriptor,
-            getRawBytes: true,
-          },
-          signal ? { signal } : undefined,
-        )) {
-          if (batch.batchIndex <= cursor.batchIndex) continue;
-          if (!Number.isSafeInteger(batch.batchIndex))
-            throw new Error("Invalid Modal output cursor");
-          const terminal = batch.exitCode !== undefined;
-          if (terminal && !Number.isSafeInteger(batch.exitCode))
-            throw new Error("Invalid Modal exit status");
-          const decoded = decodePage(
-            cursor.utf8Remainder,
-            batch.items
-              .filter((item) => item.fileDescriptor === descriptor)
-              .map((item) => item.messageBytes),
-            terminal,
-          );
+    const cancellation = new AbortController();
+    const abort = () => cancellation.abort(signal?.reason);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    try {
+      return await this.withRouter(command.taskId, cancellation.signal, async (router) => {
+        const operations = [
+          ...(["stdout", "stderr"] as const).map(async (stream) =>
+            command.streams[stream].eof
+              ? { bytes: Buffer.alloc(0), eof: true }
+              : await router.read(
+                  command,
+                  stream,
+                  command.streams[stream].byteOffset,
+                  waitMs,
+                  cancellation.signal,
+                ),
+          ),
+          router.poll(command, cancellation.signal),
+        ] as const;
+        const results = await Promise.allSettled(
+          operations.map((operation) =>
+            operation.catch((error) => {
+              cancellation.abort(error);
+              throw error;
+            }),
+          ),
+        );
+        const failed = results.find((result) => result.status === "rejected");
+        if (failed?.status === "rejected") throw failed.reason;
+        const stdout = (results[0] as PromiseFulfilledResult<{ bytes: Buffer; eof: boolean }>)
+          .value;
+        const stderr = (results[1] as PromiseFulfilledResult<{ bytes: Buffer; eof: boolean }>)
+          .value;
+        const exit = (results[2] as PromiseFulfilledResult<number | null>).value;
+        const chunks: ModalProviderOutputPage["chunks"] = [];
+        for (const [stream, page] of [
+          ["stdout", stdout],
+          ["stderr", stderr],
+        ] as const) {
+          const old = command.streams[stream];
+          const decoded = decodePage(old.utf8Remainder, [page.bytes], page.eof);
+          const byteOffset = old.byteOffset + page.bytes.length;
+          if (!Number.isSafeInteger(byteOffset)) throw new Error("Modal output offset exhausted");
           next.streams[stream] = {
-            batchIndex: batch.batchIndex,
+            byteOffset,
             utf8Remainder: decoded.remainder,
-            exitCode: terminal ? batch.exitCode! : null,
-          };
-          return {
-            stream,
-            chunkId: `modal:${command.execId}:${stream}:${cursor.batchIndex}:${batch.batchIndex}`,
-            text: decoded.text,
+            eof: page.eof,
+            exitCode: page.eof ? exit : null,
           };
+          if (decoded.text)
+            chunks.push({
+              stream,
+              chunkId: `modal-router:${command.execId}:${stream}:${old.byteOffset}:${byteOffset}:${page.eof ? 1 : 0}`,
+              text: decoded.text,
+            });
         }
-        return null;
-      }),
-    );
-    const stdoutExit = next.streams.stdout.exitCode;
-    const stderrExit = next.streams.stderr.exitCode;
-    if (stdoutExit !== null && stderrExit !== null && stdoutExit !== stderrExit)
-      throw new Error("Modal output streams disagree about command exit status");
-    return {
-      command: next,
-      streamFidelity: command.pty ? "merged" : "separate",
-      chunks: pages.filter((page): page is NonNullable<typeof page> => page !== null),
-      exitCode: stdoutExit !== null && stderrExit !== null ? stdoutExit : null,
-    };
+        return {
+          command: next,
+          expected: structuredClone(command),
+          chunks,
+          exitCode: next.streams.stdout.eof && next.streams.stderr.eof ? exit : null,
+          streamFidelity: command.pty ? "merged" : "separate",
+        };
+      });
+    } finally {
+      signal?.removeEventListener("abort", abort);
+    }
   }
 
-  async write(command: ModalProviderCommand, chars: string, messageIndex: number): Promise<void> {
-    this.assertIdentity(command);
-    if (!chars) return;
-    if (!Number.isSafeInteger(messageIndex) || messageIndex < 1)
-      throw new Error("Modal stdin requires a protected monotonic message index");
-    await this.client.containerExecPutInput(
-      {
-        execId: command.execId,
-        input: { message: Buffer.from(chars), messageIndex, eof: false },
-      },
-      { retries: 0 },
-    );
+  async readProbe(
+    command: ModalProviderCommand,
+    waitMs: number,
+    cancellation: AbortController,
+  ): Promise<ModalProviderOutputPage> {
+    return await this.read(command, waitMs, cancellation.signal);
   }
 
-  private assertIdentity(command: ModalProviderCommand): void {
+  async write(command: ModalProviderCommand, chars: string, index: number): Promise<void> {
     SandboxProviderCommand.parse(command);
-    if (
-      command.kind !== "modal-control-v1" ||
-      command.sandboxId !== this.sandboxId ||
-      !command.taskId ||
-      !command.execId
-    )
-      throw new Error("Modal command locator does not match the original sandbox");
+    if (command.sandboxId !== this.sandboxId)
+      throw new Error("Modal command does not belong to this sandbox");
+    if (command.kind === "modal-control-v1") return await this.legacy.write(command, chars, index);
+    await this.withRouter(command.taskId, undefined, (router) =>
+      router.write(command, index, Buffer.from(chars)),
+    );
   }
 }