tywrap 0.7.0 → 0.9.0

package/src/runtime/subprocess-transport.ts

@@ -17,8 +17,9 @@ import { spawn, type ChildProcess } from 'child_process';
 import type { Writable } from 'stream';
 import { DisposableBase } from './bounded-context.js';
 import { BridgeDisposedError, BridgeProtocolError, BridgeTimeoutError } from './errors.js';
+import { Reassembler, encodeFrames, utf8ByteLength } from './frame-codec.js';
 import { TimedOutRequestTracker } from './timed-out-request-tracker.js';
-import type { Transport, TransportCapabilities } from './transport.js';
+import { type Transport, type TransportCapabilities } from './transport.js';
 
 // =============================================================================
 // CONSTANTS
@@ -36,6 +37,34 @@ const DEFAULT_WRITE_QUEUE_TIMEOUT_MS = 30_000;
 /** Track timed-out/cancelled request IDs long enough to ignore late responses. */
 const TIMED_OUT_REQUEST_TTL_MS = 10 * 60 * 1000;
 
+/**
+ * Per-frame envelope headroom (bytes) reserved on top of a frame's data slice
+ * when sizing the frame-aware stdout line ceiling.
+ *
+ * A `tywrap-frame/1` line is `{"__tywrap_frame__":"chunk","frameProtocol":...,
+ * "stream":"response","id":N,"seq":N,"total":N,"totalBytes":N,
+ * "encoding":"utf8-slice","data":"<slice>"}`. The fixed keys plus the largest
+ * plausible integer fields are well under 256 bytes; 1 KiB is a comfortable
+ * upper bound that never under-allocates.
+ */
+const FRAME_ENVELOPE_HEADROOM = 1024;
+
+/**
+ * Worst-case JSON-escaping expansion of a frame's `data` slice. The slice is a
+ * fragment of a JSON response (already-escaped, printable content), so realistic
+ * expansion is `"`->`\"` / `\`->`\\` (2x). Using 2x keeps the frame-aware line
+ * ceiling sound without over-allocating buffer headroom.
+ */
+const FRAME_DATA_ESCAPE_FACTOR = 2;
+
+/**
+ * Default cap (UTF-8 bytes) on a single chunked response reassembled in memory.
+ * Mirrors the codec's `DEFAULT_MAX_PAYLOAD_BYTES` (10 MiB) so chunking never
+ * buffers more than the codec would ultimately accept; `NodeBridge` overrides it
+ * with the configured `codec.maxPayloadBytes`.
+ */
+const DEFAULT_MAX_REASSEMBLY_BYTES = 10 * 1024 * 1024;
+
 /** Regex for ANSI escape sequences */
 const ANSI_ESCAPE_RE = /\u001b\[[0-9;]*[A-Za-z]/g;
 
@@ -70,6 +99,15 @@ export interface SubprocessTransportOptions {
 
   /** Write queue timeout in milliseconds. Default: 30000ms */
   writeQueueTimeoutMs?: number;
+
+  /**
+   * Cap (UTF-8 bytes) on a single chunked RESPONSE reassembled in memory. A
+   * frame stream whose declared or accumulated payload exceeds this fails loud
+   * instead of buffering, so chunking cannot OOM the process before the codec's
+   * payload cap rejects the result. Should track the codec's `maxPayloadBytes`.
+   * Default: 10 MiB (matches the codec default).
+   */
+  maxReassemblyBytes?: number;
 }
 
 /**
@@ -92,6 +130,15 @@ interface QueuedWrite {
   queuedAt: number;
   /** Timeout handle for write queue timeout */
   timeoutHandle?: NodeJS.Timeout;
+  /**
+   * Liveness predicate. If present and `false` at flush time, the write is
+   * SKIPPED (resolved as a no-op) instead of sent — so a request that timed out
+   * or aborted while its write sat in the stdin backpressure queue never reaches
+   * (and so never executes on) Python.
+   */
+  isLive?: () => boolean;
+  /** True while this entry is waiting to be flushed. */
+  isQueued?: boolean;
 }
 
 // =============================================================================
@@ -129,6 +176,36 @@ function extractMessageId(json: string): number | null {
   return id;
 }
 
+/**
+ * Result of inspecting a stdout line for `tywrap-frame/1` framing.
+ * - `{ kind: 'frame', value }`: the line parsed as JSON carrying a
+ *   `__tywrap_frame__` marker (handed to the reassembler, which validates it).
+ * - `{ kind: 'plain' }`: valid JSON without a framing marker (a normal,
+ *   single-line response).
+ * - `{ kind: 'invalid' }`: not parseable as JSON.
+ */
+type FrameLineProbe = { kind: 'frame'; value: unknown } | { kind: 'plain' } | { kind: 'invalid' };
+
+/**
+ * Classify a stdout line as a frame envelope, a plain response, or invalid JSON.
+ *
+ * A frame envelope is any JSON object carrying a `__tywrap_frame__` key; the
+ * envelope's structural validity (protocol, seq/total ranges, etc.) is enforced
+ * by the {@link Reassembler}, not here — this only routes the line.
+ */
+function probeFrameLine(line: string): FrameLineProbe {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return { kind: 'invalid' };
+  }
+  if (parsed !== null && typeof parsed === 'object' && '__tywrap_frame__' in parsed) {
+    return { kind: 'frame', value: parsed };
+  }
+  return { kind: 'plain' };
+}
+
 // =============================================================================
 // PROCESS IO TRANSPORT
 // =============================================================================
@@ -165,9 +242,24 @@ export class SubprocessTransport extends DisposableBase implements Transport {
   private readonly envOverrides: Record<string, string>;
   private readonly cwd: string | undefined;
   private readonly maxLineLength: number;
+  private readonly maxReassemblyBytes: number;
   private readonly restartAfterRequests: number;
   private readonly writeQueueTimeoutMs: number;
 
+  /**
+   * Per-frame UTF-8 data ceiling. The packaged Python peer receives this
+   * transport's `maxLineLength` when it is spawned, so request and response
+   * framing use the same fixed ceiling without runtime negotiation.
+   */
+  private readonly frameBytes: number;
+
+  /**
+   * Reassembles `tywrap-frame/1` response frames into single logical response
+   * lines. Per-id discard tracks
+   * timed-out/aborted streams so late frames cannot desync stdout.
+   */
+  private responseReassembler: Reassembler | null = null;
+
   // Process state
   private process: ChildProcess | null = null;
   private processExited = false;
@@ -175,6 +267,7 @@ export class SubprocessTransport extends DisposableBase implements Transport {
 
   // Stream buffers
   private stdoutBuffer = '';
+  private stdoutScanOffset = 0;
   private stderrBuffer = '';
 
   // Request tracking
@@ -184,11 +277,27 @@ export class SubprocessTransport extends DisposableBase implements Transport {
   });
   private requestCount = 0;
   private needsRestart = false;
+  /** Serializes restart decisions with dispatch reservations. */
+  private dispatchMutex: Promise<void> = Promise.resolve();
+  private activeDispatches = 0;
+  private readonly dispatchDrainWaiters: Array<() => void> = [];
 
   // Write queue for backpressure
   private readonly writeQueue: QueuedWrite[] = [];
+  private writeQueueHead = 0;
   private draining = false;
 
+  /**
+   * Per-logical-request write mutex (W5). When a request is chunked into
+   * `tywrap-frame/1` frames, all of that request's frames must reach stdin
+   * contiguously — no other request's frame (or single line) may interleave —
+   * or the Python reassembler would see frames from two ids mixed on one stream.
+   * `writeChunkedRequest` chains the whole frame burst onto this tail; the
+   * single-line write path also serializes behind it so a small request issued
+   * concurrently never slips between another request's frames.
+   */
+  private writeMutex: Promise<void> = Promise.resolve();
+
   /**
    * Create a new SubprocessTransport.
    *
@@ -204,6 +313,12 @@ export class SubprocessTransport extends DisposableBase implements Transport {
     this.maxLineLength = options.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH;
     this.restartAfterRequests = options.restartAfterRequests ?? 0;
     this.writeQueueTimeoutMs = options.writeQueueTimeoutMs ?? DEFAULT_WRITE_QUEUE_TIMEOUT_MS;
+    this.maxReassemblyBytes = options.maxReassemblyBytes ?? DEFAULT_MAX_REASSEMBLY_BYTES;
+    this.frameBytes = this.maxLineLength;
+    this.responseReassembler = new Reassembler({
+      maxReassemblyBytes: this.maxReassemblyBytes,
+      expectedStream: 'response',
+    });
   }
 
   // ===========================================================================
@@ -218,7 +333,12 @@ export class SubprocessTransport extends DisposableBase implements Transport {
    * @param signal - Optional AbortSignal for cancellation
    * @returns The raw JSON response string
    */
-  async send(message: string, timeoutMs: number, signal?: AbortSignal): Promise<string> {
+  async send(
+    message: string,
+    timeoutMs: number,
+    signal?: AbortSignal,
+    requestId?: number
+  ): Promise<string> {
     // Check disposed state
     if (this.isDisposed) {
       throw new BridgeDisposedError('Transport has been disposed');
@@ -243,27 +363,50 @@ export class SubprocessTransport extends DisposableBase implements Transport {
     }
 
     // Extract message ID for response correlation
-    const messageId = extractMessageId(message);
+    const messageId = requestId ?? extractMessageId(message);
     if (messageId === null) {
       throw new BridgeProtocolError('Message must contain an "id" field');
     }
 
-    // Check for restart condition (either scheduled restart or forced by stream error)
-    if (
-      this.needsRestart ||
-      (this.restartAfterRequests > 0 && this.requestCount >= this.restartAfterRequests)
-    ) {
-      await this.restartProcess();
-    }
+    let ownsDispatchReservation = false;
+    let reservationReleased = false;
+    const releaseOwnedReservation = (): void => {
+      if (ownsDispatchReservation && !reservationReleased) {
+        reservationReleased = true;
+        this.releaseDispatch();
+      }
+    };
 
     // Create promise for response
-    return new Promise<string>((resolve, reject) => {
+    const response = new Promise<string>((resolve, reject) => {
       // Set up timeout if specified
       let timer: NodeJS.Timeout | undefined;
+
+      // Defined before the timer so the timeout path can also detach it.
+      const abortHandler = (): void => {
+        if (timer) {
+          clearTimeout(timer);
+        }
+        this.pending.delete(messageId);
+        this.timedOutRequests.mark(messageId);
+        // Same late-frame discard as the timeout path (see below).
+        this.responseReassembler?.discard(messageId);
+        reject(new BridgeTimeoutError('Operation aborted'));
+      };
+
       if (timeoutMs > 0) {
         timer = setTimeout(() => {
           this.pending.delete(messageId);
           this.timedOutRequests.mark(messageId);
+          // Discard any in-flight chunked response stream for this id so late
+          // frames are dropped rather than desyncing stdout (the single-line
+          // timedOutRequests.consume above is one-shot and insufficient for a
+          // multi-frame stream).
+          this.responseReassembler?.discard(messageId);
+          // Detach the abort listener: on timeout the abort never fires, so
+          // without this it would leak on a long-lived AbortSignal and could
+          // re-enter abortHandler after this promise has already settled.
+          signal?.removeEventListener('abort', abortHandler);
           const stderrTail = this.getStderrTail();
           const baseMsg = `Operation timed out after ${timeoutMs}ms`;
           const msg = stderrTail ? `${baseMsg}. Recent stderr:\n${stderrTail}` : baseMsg;
@@ -271,16 +414,6 @@ export class SubprocessTransport extends DisposableBase implements Transport {
         }, timeoutMs);
       }
 
-      // Set up abort handler
-      const abortHandler = (): void => {
-        if (timer) {
-          clearTimeout(timer);
-        }
-        this.pending.delete(messageId);
-        this.timedOutRequests.mark(messageId);
-        reject(new BridgeTimeoutError('Operation aborted'));
-      };
-
       if (signal) {
         signal.addEventListener('abort', abortHandler, { once: true });
       }
@@ -302,41 +435,130 @@ export class SubprocessTransport extends DisposableBase implements Transport {
         reject(error);
       };
 
-      // Register pending request
-      this.pending.set(messageId, {
+      // Register pending request. Captured by reference so the write path can
+      // bind liveness to THIS exact entry (not just the id) — see writeRequest.
+      const pendingEntry: PendingRequest = {
         resolve: wrappedResolve,
         reject: wrappedReject,
         timer,
-      });
+      };
+      this.pending.set(messageId, pendingEntry);
+
+      // Write message to stdin. When the encoded request exceeds the per-frame
+      // ceiling, it is fragmented into
+      // `tywrap-frame/1` request frames written contiguously under the write
+      // mutex (W5); otherwise it goes out as a single JSONL line. Both paths
+      // serialize through the same mutex so a small request can never slip
+      // between another request's frames.
+      this.reserveDispatch(() => this.pending.get(messageId) === pendingEntry && !signal?.aborted)
+        .then(reserved => {
+          if (!reserved) {
+            return;
+          }
+          ownsDispatchReservation = true;
+          // Timeout/abort may have settled while this reservation waited behind
+          // a generation restart. Do not write the abandoned request, and release
+          // only the reservation this send actually acquired.
+          if (this.pending.get(messageId) !== pendingEntry) {
+            releaseOwnedReservation();
+            return;
+          }
+          return this.writeRequest(message, messageId, signal, pendingEntry);
+        })
+        .catch(err => {
+          this.pending.delete(messageId);
+          if (timer) {
+            clearTimeout(timer);
+          }
+          signal?.removeEventListener('abort', abortHandler);
+          reject(this.classifyError(err));
+        });
+    });
+    return response.finally(releaseOwnedReservation);
+  }
 
-      // Write message to stdin
-      this.writeToStdin(`${message}\n`).catch(err => {
-        this.pending.delete(messageId);
-        if (timer) {
-          clearTimeout(timer);
-        }
-        signal?.removeEventListener('abort', abortHandler);
-        reject(this.classifyError(err));
-      });
+  /**
+   * Atomically reserve the current process generation for one request. A
+   * threshold restart waits for every request reserved on the old generation
+   * to settle before killing it; later callers remain queued behind this lock.
+   */
+  private async withDispatchMutex<T>(operation: () => Promise<T>): Promise<T> {
+    let unlock!: () => void;
+    const previous = this.dispatchMutex;
+    this.dispatchMutex = new Promise<void>(resolve => {
+      unlock = resolve;
+    });
+    await previous;
+    try {
+      return await operation();
+    } finally {
+      unlock();
+    }
+  }
 
+  private async reserveDispatch(isLive: () => boolean): Promise<boolean> {
+    return this.withDispatchMutex(async () => {
+      // Cancellation may win while this request waits behind an earlier
+      // generation. It must consume neither a request slot nor a restart.
+      if (!isLive()) {
+        return false;
+      }
+      if (this.isLifecycleEnding()) {
+        throw new BridgeDisposedError('Transport has been disposed');
+      }
+      if (
+        this.needsRestart ||
+        (this.restartAfterRequests > 0 && this.requestCount >= this.restartAfterRequests)
+      ) {
+        if (this.activeDispatches > 0) {
+          await new Promise<void>(resolve => this.dispatchDrainWaiters.push(resolve));
+        }
+        // The owner or transport can settle while waiting for the old
+        // generation to drain. Do not restart for work that no longer exists.
+        if (!isLive()) {
+          return false;
+        }
+        if (this.isLifecycleEnding()) {
+          throw new BridgeDisposedError('Transport has been disposed');
+        }
+        await this.restartProcess();
+      }
+      this.activeDispatches++;
       this.requestCount++;
+      return true;
     });
   }
 
+  private releaseDispatch(): void {
+    this.activeDispatches = Math.max(0, this.activeDispatches - 1);
+    if (this.activeDispatches === 0) {
+      for (const resolve of this.dispatchDrainWaiters.splice(0)) {
+        resolve();
+      }
+    }
+  }
+
+  private isLifecycleEnding(): boolean {
+    return this.state === 'disposing' || this.isDisposed;
+  }
+
   /**
    * Static capability descriptor for the subprocess backend.
    *
-   * Subprocess carries Arrow IPC and arbitrary binary (bytes envelopes) over the
-   * JSONL stream. Chunking/streaming are not implemented (0.8.0). `maxFrameBytes`
-   * is the configured JSONL line-length limit — the largest single response line
-   * this transport will accept before raising a protocol error.
+   * Per the {@link Transport.capabilities} contract this is lifecycle-independent
+   * (safe before `init()` / after `dispose()`) and never makes a Python round
+   * trip. Subprocess carries Arrow IPC and arbitrary binary (bytes envelopes)
+   * over the JSONL stream. `supportsChunking` is always `true` because the npm
+   * package ships both `tywrap-frame/1` peers. `supportsStreaming` stays `false`.
+   * `maxFrameBytes` is the fixed per-frame data ceiling supplied to the Python
+   * bridge at spawn time.
    */
   capabilities(): TransportCapabilities {
     return {
       backend: 'subprocess',
       supportsArrow: true,
       supportsBinary: true,
-      supportsChunking: false,
+      supportsChunking: true,
       supportsStreaming: false,
       maxFrameBytes: this.maxLineLength,
     };
@@ -347,7 +569,8 @@ export class SubprocessTransport extends DisposableBase implements Transport {
   // ===========================================================================
 
   /**
-   * Initialize the transport by spawning the Python process.
+   * Initialize the transport by spawning the Python process. The packaged
+   * bridge always speaks `tywrap-frame/1`.
    */
   protected async doInit(): Promise<void> {
     await this.spawnProcess();
@@ -371,20 +594,26 @@ export class SubprocessTransport extends DisposableBase implements Transport {
     this.pending.clear();
 
     // Clear write queue
-    for (const queued of this.writeQueue) {
-      this.clearQueuedWriteTimeout(queued);
-      queued.reject(error);
-    }
-    this.writeQueue.length = 0;
+    this.rejectAllQueuedWrites(error);
 
-    // Kill process
-    await this.killProcess();
+    // Fence queued restart work before killing the process. A restart already
+    // holding the mutex observes the disposing state before it can spawn; if it
+    // spawned just before disposal began, this barrier kills that child too.
+    await this.withDispatchMutex(() => this.killProcess());
 
     // Clear buffers
     this.stdoutBuffer = '';
+    this.stdoutScanOffset = 0;
     this.stderrBuffer = '';
     this.timedOutRequests.clear();
     this.requestCount = 0;
+    this.responseReassembler = new Reassembler({
+      maxReassemblyBytes: this.maxReassemblyBytes,
+      expectedStream: 'response',
+    });
+    // Reset the per-request write mutex so a disposed transport starts from a
+    // clean (resolved) tail if reused.
+    this.writeMutex = Promise.resolve();
   }
 
   // ===========================================================================
@@ -399,6 +628,14 @@ export class SubprocessTransport extends DisposableBase implements Transport {
     // If env is provided, it should be the complete environment (already filtered by NodeBridge)
     // We only add Python-specific variables on top
     const baseEnv = Object.keys(this.envOverrides).length > 0 ? this.envOverrides : process.env;
+
+    // Advertise `tywrap-frame/1` chunked transport so the bridge fragments
+    // oversize responses. maxFrameBytes is the JSONL line ceiling: the bridge
+    // caps each frame's *data slice* at this many UTF-8 bytes, and the TS reader
+    // (see the frame-aware line ceiling) allows for the JSON envelope + escaping
+    // on top of it. Spread (rather than dynamic index assignment) keeps the
+    // computed keys off ESLint's object-injection sink. See
+    // docs/transport-framing.md.
     const env: NodeJS.ProcessEnv = {
       ...baseEnv,
       // Ensure Python uses UTF-8
@@ -409,11 +646,15 @@ export class SubprocessTransport extends DisposableBase implements Transport {
     };
 
     // Spawn process
-    this.process = spawn(this.pythonPath, [this.bridgeScript], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env,
-      cwd: this.cwd,
-    });
+    this.process = spawn(
+      this.pythonPath,
+      [this.bridgeScript, '--tywrap-max-frame-bytes', String(this.frameBytes)],
+      {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env,
+        cwd: this.cwd,
+      }
+    );
 
     this.processExited = false;
     this.processError = null;
@@ -499,16 +740,37 @@ export class SubprocessTransport extends DisposableBase implements Transport {
    * Restart the Python process.
    */
   private async restartProcess(): Promise<void> {
+    if (this.isLifecycleEnding()) {
+      throw new BridgeDisposedError('Transport has been disposed');
+    }
+
     // Kill existing process
     await this.killProcess();
 
     // Clear buffers and restart flags
     this.stdoutBuffer = '';
+    this.stdoutScanOffset = 0;
     this.stderrBuffer = '';
     this.requestCount = 0;
     this.needsRestart = false;
+    // Drop any partial reassembly + discard tracking: the new process owns a
+    // fresh stdout stream, so stale per-id state from the dead process must not
+    // leak across the restart boundary.
+    this.responseReassembler = new Reassembler({
+      maxReassemblyBytes: this.maxReassemblyBytes,
+      expectedStream: 'response',
+    });
+    // The new process owns a fresh stdin stream; reset the write mutex so a
+    // pending frame burst against the dead process cannot serialize behind it.
+    this.writeMutex = Promise.resolve();
+
+    // Disposal may begin while the old child is being killed. Never publish a
+    // replacement after lifecycle teardown has started.
+    if (this.isLifecycleEnding()) {
+      throw new BridgeDisposedError('Transport has been disposed');
+    }
 
-    // Spawn new process
+    // Spawn a fresh process with the packaged always-on framing protocol.
     await this.spawnProcess();
   }
 
@@ -525,46 +787,81 @@ export class SubprocessTransport extends DisposableBase implements Transport {
   // STREAM HANDLERS
   // ===========================================================================
 
+  /**
+   * Effective stdout line ceiling.
+   *
+   * A single wire line may be a `tywrap-frame/1` envelope whose
+   * `data` slice is capped at `maxLineLength` UTF-8 bytes by the bridge, but the
+   * JSON envelope adds escaping (`"`/`\`) plus fixed keys; the ceiling is widened
+   * to bound that overhead so a legitimate frame line is never rejected while a
+   * runaway/garbage line still is.
+   */
+  private effectiveLineCeiling(): number {
+    return this.maxLineLength * FRAME_DATA_ESCAPE_FACTOR + FRAME_ENVELOPE_HEADROOM;
+  }
+
   /**
    * Handle stdout data from the Python process.
    */
   private handleStdoutData(chunk: Buffer | string): void {
     this.stdoutBuffer += chunk.toString();
 
-    // Check for excessive line length without newline
-    if (this.stdoutBuffer.length > this.maxLineLength && !this.stdoutBuffer.includes('\n')) {
+    const ceiling = this.effectiveLineCeiling();
+
+    // Scan only bytes newly appended since the last incomplete line.
+    let newlineIndex = this.stdoutBuffer.indexOf('\n', this.stdoutScanOffset);
+    if (this.stdoutBuffer.length > ceiling && newlineIndex === -1) {
       const snippet = this.stdoutBuffer.slice(0, 500);
       this.stdoutBuffer = '';
-      this.handleProtocolError(`Response line exceeded ${this.maxLineLength} bytes`, snippet);
+      this.stdoutScanOffset = 0;
+      this.handleProtocolError(`Response line exceeded ${ceiling} bytes`, snippet);
       return;
     }
 
     // Process complete lines
-    let newlineIndex: number;
-    while ((newlineIndex = this.stdoutBuffer.indexOf('\n')) !== -1) {
+    while (newlineIndex !== -1) {
       const line = this.stdoutBuffer.slice(0, newlineIndex);
       this.stdoutBuffer = this.stdoutBuffer.slice(newlineIndex + 1);
+      this.stdoutScanOffset = 0;
 
       // Skip empty lines
       if (!line.trim()) {
+        newlineIndex = this.stdoutBuffer.indexOf('\n', this.stdoutScanOffset);
         continue;
       }
 
       // Check line length
-      if (line.length > this.maxLineLength) {
+      if (line.length > ceiling) {
         const snippet = line.slice(0, 500);
-        this.handleProtocolError(`Response line exceeded ${this.maxLineLength} bytes`, snippet);
+        this.handleProtocolError(`Response line exceeded ${ceiling} bytes`, snippet);
         return;
       }
 
       this.handleResponseLine(line);
+      newlineIndex = this.stdoutBuffer.indexOf('\n', this.stdoutScanOffset);
     }
+    this.stdoutScanOffset = this.stdoutBuffer.length;
   }
 
   /**
    * Handle a complete response line from stdout.
+   *
+   * A line may be a `tywrap-frame/1` envelope: it is
+   * routed into the per-id {@link Reassembler}, which returns the reassembled
+   * logical response only once the stream is complete and valid. Single-line
+   * (non-frame) responses keep the original fast path unchanged.
    */
   private handleResponseLine(line: string): void {
+    if (this.responseReassembler) {
+      const probe = probeFrameLine(line);
+      if (probe.kind === 'frame') {
+        this.handleResponseFrame(probe.value, line);
+        return;
+      }
+      // probe.kind 'plain'/'invalid' falls through to the legacy single-line
+      // path below, which extracts the id and validates JSON as before.
+    }
+
     // Extract ID to find pending request
     const messageId = extractMessageId(line);
     if (messageId === null) {
@@ -595,6 +892,75 @@ export class SubprocessTransport extends DisposableBase implements Transport {
     pending.resolve(line);
   }
 
+  /**
+   * Route one `tywrap-frame/1` response frame into the reassembler.
+   *
+   * On completion the reassembled logical line resolves the pending request. The
+   * reassembler validates structure, ordering, byte count, and UTF-8 internally
+   * and throws on any framing violation (malformed/duplicate/byte-mismatch/
+   * unknown-protocol) — those reject the pending id and mark the subprocess for
+   * restart, since stdout can no longer be trusted to be frame-aligned. Frames
+   * for a timed-out/aborted id are silently discarded by the reassembler (it
+   * returns `null` and tracks the discard set) so late multi-frame responses
+   * cannot desync the stream.
+   */
+  private handleResponseFrame(rawFrame: unknown, line: string): void {
+    const reassembler = this.responseReassembler;
+    if (!reassembler) {
+      // Unreachable: the always-on framing path constructs the reassembler.
+      this.handleProtocolError('Received frame with no reassembler', line);
+      return;
+    }
+
+    const frameId = (rawFrame as { id?: unknown }).id;
+
+    let reassembled: string | null;
+    try {
+      reassembled = reassembler.accept(rawFrame);
+    } catch (err) {
+      // Framing corruption: stdout is no longer frame-aligned. Reject the
+      // correlated pending request (if any) and force a restart.
+      const message = err instanceof Error ? err.message : String(err);
+      this.rejectFrameId(frameId, `Frame reassembly failed: ${message}`, line);
+      this.markForRestart();
+      return;
+    }
+
+    if (reassembled === null) {
+      // More frames needed, or this frame belonged to a discarded (timed-out)
+      // id and was dropped. Either way: nothing to resolve yet.
+      return;
+    }
+
+    // Stream complete: resolve the correlated pending request with the single
+    // logical response line. extractMessageId is reused so the resolution path
+    // matches the non-chunked case exactly.
+    this.handleResponseLine(reassembled);
+  }
+
+  /**
+   * Reject the pending request correlated to a frame id, if one exists.
+   *
+   * Used when frame reassembly throws. If the id is unknown (e.g. it already
+   * timed out and was dropped from `pending`), the error still surfaces as a
+   * protocol error so the desync is not swallowed silently.
+   */
+  private rejectFrameId(frameId: unknown, details: string, line: string): void {
+    if (typeof frameId === 'number' && Number.isInteger(frameId)) {
+      const pending = this.pending.get(frameId);
+      if (pending) {
+        this.pending.delete(frameId);
+        if (pending.timer) {
+          clearTimeout(pending.timer);
+        }
+        pending.reject(new BridgeProtocolError(this.withStderrTail(details)));
+        return;
+      }
+    }
+    // No correlated pending request: still a protocol-level desync.
+    this.handleProtocolError(details, line);
+  }
+
   /**
    * Handle stderr data from the Python process.
    */
@@ -665,11 +1031,7 @@ export class SubprocessTransport extends DisposableBase implements Transport {
     const error = new BridgeProtocolError(this.withStderrTail(`stdin error: ${err.message}`));
 
     // Reject all pending writes
-    for (const queued of this.writeQueue) {
-      this.clearQueuedWriteTimeout(queued);
-      queued.reject(error);
-    }
-    this.writeQueue.length = 0;
+    this.rejectAllQueuedWrites(error);
 
     // Reject all pending requests
     this.rejectAllPending(error);
@@ -710,17 +1072,16 @@ export class SubprocessTransport extends DisposableBase implements Transport {
   private createQueuedWrite(
     data: string,
     resolve: () => void,
-    reject: (error: Error) => void
+    reject: (error: Error) => void,
+    isLive?: () => boolean
   ): QueuedWrite {
     const queuedAt = Date.now();
-    const entry: QueuedWrite = { data, resolve, reject, queuedAt };
+    const entry: QueuedWrite = { data, resolve, reject, queuedAt, isLive, isQueued: true };
 
     // Set up timeout timer that fires if drain never happens
     entry.timeoutHandle = setTimeout(() => {
-      // Remove this entry from the queue
-      const index = this.writeQueue.indexOf(entry);
-      if (index !== -1) {
-        this.writeQueue.splice(index, 1);
+      if (entry.isQueued) {
+        entry.isQueued = false;
         reject(
           new BridgeTimeoutError(
             `Write queue timeout: entry waited ${this.writeQueueTimeoutMs}ms without drain`
@@ -750,16 +1111,24 @@ export class SubprocessTransport extends DisposableBase implements Transport {
   /**
    * Write data to stdin with backpressure handling.
    */
-  private writeToStdin(data: string): Promise<void> {
+  private writeToStdin(data: string, isLive?: () => boolean): Promise<void> {
     return new Promise<void>((resolve, reject) => {
       if (!this.process?.stdin || this.processExited) {
         reject(new BridgeProtocolError(this.withStderrTail('Process stdin not available')));
         return;
       }
 
-      if (this.draining || this.writeQueue.length > 0) {
-        // Queue the write with timestamp and timeout timer
-        this.writeQueue.push(this.createQueuedWrite(data, resolve, reject));
+      if (this.draining || this.writeQueue.length > this.writeQueueHead) {
+        // Queue the write with timestamp, timeout timer, and liveness predicate
+        // (checked again at flush — see processQueuedWrite).
+        this.writeQueue.push(this.createQueuedWrite(data, resolve, reject, isLive));
+        return;
+      }
+
+      // Skip a write whose request was abandoned (timed out/aborted) before it
+      // reached stdin — never execute an operation the caller gave up on.
+      if (isLive && !isLive()) {
+        resolve();
         return;
       }
 
@@ -784,16 +1153,124 @@ export class SubprocessTransport extends DisposableBase implements Transport {
     });
   }
 
+  /**
+   * Write one logical request to stdin, fragmenting it into `tywrap-frame/1`
+   * request frames when the encoded request exceeds
+   * the per-frame ceiling (W5 — the mirror of W4's response chunking).
+   *
+   * Both the chunked and single-line paths run under {@link writeMutex} so a
+   * logical request's bytes (one line, or a burst of frames) reach stdin
+   * contiguously: a small request issued concurrently can never interleave
+   * between another request's frames, which would desync the Python
+   * reassembler (it correlates frames by id, but the JSONL stream itself must
+   * stay frame-aligned). The mutex tail is advanced regardless of success so a
+   * failed write never wedges every subsequent request.
+   *
+   * @param message - the encoded logical JSON request (no trailing newline)
+   * @param messageId - the request's correlation id (already validated integer)
+   * @param signal - optional abort signal; an abort observed between frames
+   *   stops further frames and rejects this send (the pending entry is rejected
+   *   by the abort handler / the caller's `.catch`).
+   */
+  private writeRequest(
+    message: string,
+    messageId: number,
+    signal?: AbortSignal,
+    pendingEntry?: PendingRequest
+  ): Promise<void> {
+    // The request is "live" only while THIS send's exact pending entry is still
+    // registered (the timeout and abort handlers delete it) and the signal is not
+    // aborted. Binding to the entry IDENTITY — not just the id — closes the
+    // id-reuse hole: if the id is recycled by a later send while this write is
+    // still queued, the stale write sees a different entry and is skipped.
+    // (RpcClient ids are monotonic, but Transport.send is public and does not
+    // enforce id uniqueness.) Gating EVERY write point on this — the run closure,
+    // the direct stdin write, the backpressure-queue flush, and each chunked
+    // frame — prevents an abandoned request from executing on Python, even one
+    // whose write sat queued under backpressure past the cancellation.
+    const isLive = (): boolean =>
+      !signal?.aborted &&
+      (pendingEntry !== undefined
+        ? this.pending.get(messageId) === pendingEntry
+        : this.pending.has(messageId));
+    const run = (): Promise<void> => {
+      if (!isLive()) {
+        return Promise.resolve();
+      }
+      // Chunk when the encoded request exceeds the fixed per-frame ceiling
+      // supplied to the packaged Python peer. Otherwise use one JSONL line.
+      if (utf8ByteLength(message) > this.frameBytes) {
+        return this.writeChunkedRequest(message, messageId, signal, isLive);
+      }
+      return this.writeToStdin(`${message}\n`, isLive);
+    };
+
+    // Serialize the whole logical write onto the mutex tail. We chain the next
+    // tail off the settled (caught) result so one failed/aborted write does not
+    // poison the chain for later requests.
+    const result = this.writeMutex.then(run);
+    this.writeMutex = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+
+  /**
+   * Fragment a logical request into `tywrap-frame/1` request frames and write
+   * them contiguously (one JSONL line per frame). Runs while holding the write
+   * mutex (see {@link writeRequest}), so no other write interleaves.
+   *
+   * Each frame is awaited in turn so backpressure on stdin is respected. Before
+   * every frame the abort signal and process liveness are re-checked: an abort
+   * mid-burst stops the remaining frames and rejects the send LOUD (the Python
+   * reassembler drops the now-incomplete id when the next request's frames /
+   * timeout arrive, exactly as the response side handles a discarded id).
+   */
+  private async writeChunkedRequest(
+    message: string,
+    messageId: number,
+    signal?: AbortSignal,
+    isLive?: () => boolean
+  ): Promise<void> {
+    const frames = encodeFrames(message, {
+      id: messageId,
+      stream: 'request',
+      maxFrameBytes: this.frameBytes,
+    });
+
+    for (const frame of frames) {
+      // Stop the burst if the caller aborted, the request was abandoned (timed
+      // out -> pending deleted, caught by isLive), or the process died between
+      // frames. A partial request stream is dropped by the Python reassembler.
+      if (signal?.aborted || (isLive && !isLive())) {
+        throw new BridgeTimeoutError('Operation aborted');
+      }
+      if (this.processExited || !this.process) {
+        throw new BridgeProtocolError(this.withStderrTail('Process stdin not available'));
+      }
+      // One frame per JSONL line; await each so stdin backpressure is honored.
+      // isLive gates a frame that ends up queued under backpressure past a late
+      // cancellation, so an abandoned chunked request never completes on Python.
+      await this.writeToStdin(`${JSON.stringify(frame)}\n`, isLive);
+    }
+  }
+
   /**
    * Reject and clear every entry currently in the write queue.
    * Clears each entry's timeout before rejecting so no late timer fires.
    */
   private rejectAllQueuedWrites(error: Error): void {
-    for (const q of this.writeQueue) {
-      this.clearQueuedWriteTimeout(q);
-      q.reject(error);
+    for (let index = this.writeQueueHead; index < this.writeQueue.length; index += 1) {
+      const queued = this.writeQueue[index];
+      if (queued?.isQueued) {
+        queued.isQueued = false;
+        this.clearQueuedWriteTimeout(queued);
+        queued.reject(error);
+      }
     }
     this.writeQueue.length = 0;
+    this.writeQueueHead = 0;
   }
 
   /**
@@ -821,6 +1298,14 @@ export class SubprocessTransport extends DisposableBase implements Transport {
       return 'continue';
     }
 
+    // Skip the write if the request was abandoned (timed out/aborted) while it
+    // sat in the backpressure queue — never execute an operation the caller gave
+    // up on. Resolve as a no-op so the mutex chain stays healthy.
+    if (queued.isLive && !queued.isLive()) {
+      queued.resolve();
+      return 'continue';
+    }
+
     try {
       const canWrite = stdin.write(queued.data);
 
@@ -851,7 +1336,7 @@ export class SubprocessTransport extends DisposableBase implements Transport {
   private flushWriteQueue(): void {
     const now = Date.now();
 
-    while (this.writeQueue.length > 0 && !this.draining) {
+    while (this.writeQueueHead < this.writeQueue.length && !this.draining) {
       const stdin = this.process?.stdin;
       if (!stdin || this.processExited) {
         // Process died - reject all queued writes
@@ -862,11 +1347,17 @@ export class SubprocessTransport extends DisposableBase implements Transport {
         return;
       }
 
-      const queued = this.writeQueue.shift();
+      const queued = this.writeQueue[this.writeQueueHead];
+      this.writeQueueHead += 1;
       if (!queued) {
         return;
       }
 
+      if (!queued.isQueued) {
+        continue;
+      }
+      queued.isQueued = false;
+
       // Clear the timeout since we're processing this entry now
       this.clearQueuedWriteTimeout(queued);
 
@@ -875,6 +1366,11 @@ export class SubprocessTransport extends DisposableBase implements Transport {
         return;
       }
     }
+
+    if (this.writeQueueHead === this.writeQueue.length) {
+      this.writeQueue.length = 0;
+      this.writeQueueHead = 0;
+    }
   }
 
   // ===========================================================================
@@ -897,7 +1393,15 @@ export class SubprocessTransport extends DisposableBase implements Transport {
   }
 
   /**
-   * Handle a protocol error by rejecting all pending requests.
+   * Handle a protocol error by rejecting all pending requests and marking the
+   * subprocess for restart.
+   *
+   * Every caller represents genuine stdout-stream corruption (a too-long line, a
+   * response with no `id`, a frame with no reassembler, or a truly unexpected id
+   * — benign late responses from timed-out requests are already filtered upstream
+   * via {@link timedOutRequests}). After such an error stdout can no longer be
+   * trusted to be line/frame-aligned, so the process is marked for restart —
+   * matching the frame-reassembly-corruption path and the framing spec.
    */
   private handleProtocolError(details: string, line?: string): void {
     const snippet = line ? (line.length > 500 ? `${line.slice(0, 500)}...` : line) : undefined;
@@ -910,6 +1414,7 @@ export class SubprocessTransport extends DisposableBase implements Transport {
 
     const error = new BridgeProtocolError(msg);
     this.rejectAllPending(error);
+    this.markForRestart();
   }
 
   /**