tywrap 0.7.0 → 0.9.0

package/dist/runtime/subprocess-transport.js

@@ -15,6 +15,7 @@
 import { spawn } from 'child_process';
 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';
 // =============================================================================
 // CONSTANTS
@@ -27,6 +28,31 @@ const MAX_STDERR_BYTES = 8 * 1024;
 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;
 /** Regex for control characters */
@@ -61,6 +87,26 @@ function extractMessageId(json) {
     }
     return id;
 }
+/**
+ * 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) {
+    let parsed;
+    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
 // =============================================================================
@@ -96,14 +142,28 @@ export class SubprocessTransport extends DisposableBase {
     envOverrides;
     cwd;
     maxLineLength;
+    maxReassemblyBytes;
     restartAfterRequests;
     writeQueueTimeoutMs;
+    /**
+     * 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.
+     */
+    frameBytes;
+    /**
+     * 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.
+     */
+    responseReassembler = null;
     // Process state
     process = null;
     processExited = false;
     processError = null;
     // Stream buffers
     stdoutBuffer = '';
+    stdoutScanOffset = 0;
     stderrBuffer = '';
     // Request tracking
     pending = new Map();
@@ -112,9 +172,24 @@ export class SubprocessTransport extends DisposableBase {
     });
     requestCount = 0;
     needsRestart = false;
+    /** Serializes restart decisions with dispatch reservations. */
+    dispatchMutex = Promise.resolve();
+    activeDispatches = 0;
+    dispatchDrainWaiters = [];
     // Write queue for backpressure
     writeQueue = [];
+    writeQueueHead = 0;
     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.
+     */
+    writeMutex = Promise.resolve();
     /**
      * Create a new SubprocessTransport.
      *
@@ -129,6 +204,12 @@ export class SubprocessTransport extends DisposableBase {
         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',
+        });
     }
     // ===========================================================================
     // TRANSPORT INTERFACE
@@ -141,7 +222,7 @@ export class SubprocessTransport extends DisposableBase {
      * @param signal - Optional AbortSignal for cancellation
      * @returns The raw JSON response string
      */
-    async send(message, timeoutMs, signal) {
+    async send(message, timeoutMs, signal, requestId) {
         // Check disposed state
         if (this.isDisposed) {
             throw new BridgeDisposedError('Transport has been disposed');
@@ -162,38 +243,52 @@ export class SubprocessTransport extends DisposableBase {
             throw new BridgeTimeoutError('Operation aborted');
         }
         // 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 = () => {
+            if (ownsDispatchReservation && !reservationReleased) {
+                reservationReleased = true;
+                this.releaseDispatch();
+            }
+        };
         // Create promise for response
-        return new Promise((resolve, reject) => {
+        const response = new Promise((resolve, reject) => {
             // Set up timeout if specified
             let timer;
+            // Defined before the timer so the timeout path can also detach it.
+            const abortHandler = () => {
+                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;
                     reject(new BridgeTimeoutError(msg));
                 }, timeoutMs);
             }
-            // Set up abort handler
-            const abortHandler = () => {
-                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 });
             }
@@ -212,14 +307,36 @@ export class SubprocessTransport extends DisposableBase {
                 signal?.removeEventListener('abort', abortHandler);
                 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 = {
                 resolve: wrappedResolve,
                 reject: wrappedReject,
                 timer,
-            });
-            // Write message to stdin
-            this.writeToStdin(`${message}\n`).catch(err => {
+            };
+            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);
@@ -227,23 +344,86 @@ export class SubprocessTransport extends DisposableBase {
                 signal?.removeEventListener('abort', abortHandler);
                 reject(this.classifyError(err));
             });
+        });
+        return response.finally(releaseOwnedReservation);
+    }
+    /**
+     * 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.
+     */
+    async withDispatchMutex(operation) {
+        let unlock;
+        const previous = this.dispatchMutex;
+        this.dispatchMutex = new Promise(resolve => {
+            unlock = resolve;
+        });
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            unlock();
+        }
+    }
+    async reserveDispatch(isLive) {
+        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(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;
         });
     }
+    releaseDispatch() {
+        this.activeDispatches = Math.max(0, this.activeDispatches - 1);
+        if (this.activeDispatches === 0) {
+            for (const resolve of this.dispatchDrainWaiters.splice(0)) {
+                resolve();
+            }
+        }
+    }
+    isLifecycleEnding() {
+        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() {
         return {
             backend: 'subprocess',
             supportsArrow: true,
             supportsBinary: true,
-            supportsChunking: false,
+            supportsChunking: true,
             supportsStreaming: false,
             maxFrameBytes: this.maxLineLength,
         };
@@ -252,7 +432,8 @@ export class SubprocessTransport extends DisposableBase {
     // BOUNDED CONTEXT LIFECYCLE
     // ===========================================================================
     /**
-     * Initialize the transport by spawning the Python process.
+     * Initialize the transport by spawning the Python process. The packaged
+     * bridge always speaks `tywrap-frame/1`.
      */
     async doInit() {
         await this.spawnProcess();
@@ -273,18 +454,24 @@ export class SubprocessTransport extends DisposableBase {
         }
         this.pending.clear();
         // Clear write queue
-        for (const queued of this.writeQueue) {
-            this.clearQueuedWriteTimeout(queued);
-            queued.reject(error);
-        }
-        this.writeQueue.length = 0;
-        // Kill process
-        await this.killProcess();
+        this.rejectAllQueuedWrites(error);
+        // 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();
     }
     // ===========================================================================
     // PROCESS MANAGEMENT
@@ -297,6 +484,13 @@ export class SubprocessTransport extends DisposableBase {
         // 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 = {
             ...baseEnv,
             // Ensure Python uses UTF-8
@@ -306,7 +500,7 @@ export class SubprocessTransport extends DisposableBase {
             PYTHONUNBUFFERED: '1',
         };
         // Spawn process
-        this.process = spawn(this.pythonPath, [this.bridgeScript], {
+        this.process = spawn(this.pythonPath, [this.bridgeScript, '--tywrap-max-frame-bytes', String(this.frameBytes)], {
             stdio: ['pipe', 'pipe', 'pipe'],
             env,
             cwd: this.cwd,
@@ -382,14 +576,33 @@ export class SubprocessTransport extends DisposableBase {
      * Restart the Python process.
      */
     async restartProcess() {
+        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;
-        // Spawn new process
+        // 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 a fresh process with the packaged always-on framing protocol.
         await this.spawnProcess();
     }
     /**
@@ -403,40 +616,72 @@ export class SubprocessTransport extends DisposableBase {
     // ===========================================================================
     // 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.
+     */
+    effectiveLineCeiling() {
+        return this.maxLineLength * FRAME_DATA_ESCAPE_FACTOR + FRAME_ENVELOPE_HEADROOM;
+    }
     /**
      * Handle stdout data from the Python process.
      */
     handleStdoutData(chunk) {
         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;
-        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.
      */
     handleResponseLine(line) {
+        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) {
@@ -462,6 +707,70 @@ export class SubprocessTransport extends DisposableBase {
         // Resolve with raw response
         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.
+     */
+    handleResponseFrame(rawFrame, line) {
+        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.id;
+        let reassembled;
+        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.
+     */
+    rejectFrameId(frameId, details, line) {
+        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.
      */
@@ -523,11 +832,7 @@ export class SubprocessTransport extends DisposableBase {
         // EPIPE means process died
         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);
         // Mark for restart on next send
@@ -559,15 +864,13 @@ export class SubprocessTransport extends DisposableBase {
      * Create a queued write entry with a timeout timer.
      * The timer fires if the drain event never comes.
      */
-    createQueuedWrite(data, resolve, reject) {
+    createQueuedWrite(data, resolve, reject, isLive) {
         const queuedAt = Date.now();
-        const entry = { data, resolve, reject, queuedAt };
+        const entry = { 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`));
             }
         }, this.writeQueueTimeoutMs);
@@ -589,15 +892,22 @@ export class SubprocessTransport extends DisposableBase {
     /**
      * Write data to stdin with backpressure handling.
      */
-    writeToStdin(data) {
+    writeToStdin(data, isLive) {
         return new Promise((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;
             }
             // Try direct write (wrap in try-catch for synchronous EPIPE errors)
@@ -621,16 +931,106 @@ export class SubprocessTransport extends DisposableBase {
             }
         });
     }
+    /**
+     * 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`).
+     */
+    writeRequest(message, messageId, signal, pendingEntry) {
+        // 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 = () => !signal?.aborted &&
+            (pendingEntry !== undefined
+                ? this.pending.get(messageId) === pendingEntry
+                : this.pending.has(messageId));
+        const run = () => {
+            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).
+     */
+    async writeChunkedRequest(message, messageId, signal, isLive) {
+        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.
      */
     rejectAllQueuedWrites(error) {
-        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;
     }
     /**
      * Process a single dequeued write entry: enforce the fallback queue timeout,
@@ -648,6 +1048,13 @@ export class SubprocessTransport extends DisposableBase {
             queued.reject(new BridgeTimeoutError(`Write queue timeout: entry waited ${now - queued.queuedAt}ms (limit: ${this.writeQueueTimeoutMs}ms)`));
             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);
             if (canWrite) {
@@ -675,7 +1082,7 @@ export class SubprocessTransport extends DisposableBase {
      */
     flushWriteQueue() {
         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
@@ -683,10 +1090,15 @@ export class SubprocessTransport extends DisposableBase {
                 this.markForRestart();
                 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);
             const status = this.processQueuedWrite(queued, stdin, now);
@@ -694,6 +1106,10 @@ export class SubprocessTransport extends DisposableBase {
                 return;
             }
         }
+        if (this.writeQueueHead === this.writeQueue.length) {
+            this.writeQueue.length = 0;
+            this.writeQueueHead = 0;
+        }
     }
     // ===========================================================================
     // HELPERS
@@ -712,7 +1128,15 @@ export class SubprocessTransport extends DisposableBase {
         return stderrTail ? `${message}. Stderr:\n${stderrTail}` : message;
     }
     /**
-     * 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.
      */
     handleProtocolError(details, line) {
         const snippet = line ? (line.length > 500 ? `${line.slice(0, 500)}...` : line) : undefined;
@@ -722,6 +1146,7 @@ export class SubprocessTransport extends DisposableBase {
             : `Protocol error: ${details}\n${hint}`;
         const error = new BridgeProtocolError(msg);
         this.rejectAllPending(error);
+        this.markForRestart();
     }
     /**
      * Reject all pending requests with an error.