@sentropic/h2a 0.97.2 → 0.97.4

package/dist/runtime/mcp/stdio.js

@@ -1,13 +1,17 @@
 import { createInterface } from "node:readline";
 import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { linkSync, unlinkSync, writeFileSync } from "node:fs";
+import { linkSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { createInboxWakeHandler } from "../drive/inbox-wake.js";
 import { detectLocalLaunchContext, detectTmuxLaunchContext } from "../drive/index.js";
 import { createLocalStore } from "../local-files/index.js";
 import { reapDeadInstancePresence } from "../local-files/presence.js";
 import { agentVersion } from "../version/agent-version.js";
+import { currentCliVersion } from "../upgrade/index.js";
+import { getActiveMcpTrace } from "./phase-trace.js";
 import { createMcpServer, isMcpTransportResult } from "./server.js";
+import { createIdentityController } from "./identity-state.js";
+import { boundNotificationFrame, boundResponseFrame, buildInvalidRequestId, encodeFrame, isAcceptableRequestId } from "./frame-budget.js";
 function envInt(name) {
     const raw = process.env[name];
     if (!raw)
@@ -17,7 +21,23 @@ function envInt(name) {
 }
 const PROTOCOL_VERSION = "2025-06-18";
 const SERVER_NAME = "@sentropic/h2a";
-const SERVER_VERSION = "0.1.1";
+// The MCP `serverInfo.version` MUST be the real package version, not a frozen
+// literal — a stale `0.1.1` made `initialize` disagree with the plugin manifest
+// and `h2a --version`, defeating the version-drift diagnosis (#275). Resolved
+// from package.json via `currentCliVersion()` and cached (initialize is rare,
+// but the read is trivial and total — it falls back to "0.0.0" on any error).
+let cachedServerVersion;
+function serverVersion() {
+    if (cachedServerVersion === undefined) {
+        try {
+            cachedServerVersion = currentCliVersion();
+        }
+        catch {
+            cachedServerVersion = "0.0.0";
+        }
+    }
+    return cachedServerVersion;
+}
 function currentTmuxSessionForSidecar() {
     const pane = process.env.TMUX_PANE;
     if (!pane || !/^%\d+$/.test(pane))
@@ -67,9 +87,6 @@ function publishReadinessAck(readiness, sessionId) {
         }
     }
 }
-function writeResponse(stdout, response) {
-    stdout.write(`${JSON.stringify(response)}\n`);
-}
 function errorResponse(id, code, message, data) {
     const error = { code, message };
     if (data !== undefined)
@@ -83,7 +100,7 @@ function handleMethod(server, method, params) {
     if (method === "initialize") {
         return {
             protocolVersion: PROTOCOL_VERSION,
-            serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+            serverInfo: { name: SERVER_NAME, version: serverVersion() },
             capabilities: { tools: {} }
         };
     }
@@ -126,9 +143,27 @@ class MethodNotFoundError extends Error {
  */
 export function runMcpStdio(options) {
     const { root, stdin, stdout, stderr } = options;
-    if (options.readiness && !options.autoOpen) {
+    // L0 trace: the ambient per-attempt trace installed by bin.ts. Undefined in
+    // unit tests and normal CLI verbs → every call is a no-op. It only ever
+    // writes to stderr, never to the JSON-RPC stdout stream.
+    const trace = getActiveMcpTrace();
+    // Only the FIRST tool response is the calibration milestone; the rest are
+    // still measured but tagged distinctly.
+    let firstToolCallTraced = false;
+    if (options.readiness && !options.autoOpen && !options.identityRequest) {
         throw new Error("structured readiness requires successful auto-open");
     }
+    if (options.autoOpen && options.identityRequest) {
+        throw new Error("autoOpen and identityRequest are mutually exclusive");
+    }
+    // L2: the live signing identity, set only once identity is really bound. The
+    // server reads it on each h2a_send via `getSendContext`, so a signer that only
+    // becomes available after asynchronous activation is picked up with no rebuild.
+    let liveSendContext = options.sendContext;
+    // Forward reference to the identity controller; assigned below when the
+    // deferred identity path is used. The server guards signed/mutating tools by
+    // reading its state on every call.
+    let identityController;
     const heartbeatIntervalMs = options.heartbeatIntervalMs ?? envInt("H2A_HEARTBEAT_INTERVAL_MS");
     const notifyIntervalMs = options.notifyIntervalMs ??
         envInt("H2A_NOTIFY_INTERVAL_MS") ??
@@ -137,11 +172,25 @@ export function runMcpStdio(options) {
     // The stdio transport carries live agent sessions; enable autoHeartbeat so
     // the presence file stays fresh while this mcp-serve process is alive.
     let delegation;
+    // L1: forward reference — the notification sink is installed on the server
+    // below, but the bounded emitter needs `server.frameBudget`/`payloadStore`,
+    // which only exist after creation. Ticks are unref'd and interval-driven, so
+    // the real emitter is always assigned before the first tick fires.
+    let emitNotification = () => ({ accepted: false });
     const server = createMcpServer({
         root,
         workspaceRoot: options.workspaceRoot ?? process.cwd(),
         ...(options.runExecutor ? { runExecutor: options.runExecutor } : {}),
         ...(options.sendContext ? { sendContext: options.sendContext } : {}),
+        // L2: with a deferred identity, the store must not write on boot so
+        // initialize/tools-list/status answer on a read-only or not-yet-created root.
+        ...(options.identityRequest ? { storeInitialize: false } : {}),
+        // L2: the live signer is read on each call so post-activation availability
+        // (or its absence after a failure) is always reflected honestly.
+        getSendContext: () => liveSendContext,
+        get identity() {
+            return identityController;
+        },
         delegationContext: () => delegation,
         sessions: {
             autoHeartbeat: true,
@@ -150,19 +199,112 @@ export function runMcpStdio(options) {
         },
         notifications: {
             ...(notifyIntervalMs !== undefined ? { intervalMs: notifyIntervalMs } : {}),
-            sink: (notification) => {
-                stdout.write(`${JSON.stringify(notification)}\n`);
-            }
+            sink: (notification) => emitNotification(notification, {
+                method: notification.method,
+                topic: typeof notification.params?.topic === "string"
+                    ? notification.params.topic
+                    : undefined
+            })
         }
     });
+    // ---------------------------------------------------------------------------
+    // L1: the SINGLE bounded output writer. Every frame — success, error, parse
+    // error, initialize, tools/list, a preformatted Track result, AND every pushed
+    // notification — is bounded to the frame budget here; there is NO direct write
+    // to `stdout` anywhere else. Writes are ordered and drain-aware (backpressure),
+    // and the queue is byte-bounded so a slow reader cannot grow memory unbounded.
+    // ---------------------------------------------------------------------------
+    const frameBudget = server.frameBudget;
+    const recover = (intactJson) => {
+        try {
+            return server.payloadStore.persistOutput(Buffer.from(intactJson, "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const MAX_QUEUE_BYTES = 8 * 1024 * 1024;
+    let writeChain = Promise.resolve();
+    let queuedBytes = 0;
+    function enqueueLine(line) {
+        const bytes = Buffer.byteLength(line, "utf8");
+        queuedBytes += bytes;
+        writeChain = writeChain
+            .then(() => new Promise((resolve, reject) => {
+            const flushed = stdout.write(line, (err) => {
+                if (err)
+                    reject(err);
+            });
+            if (flushed)
+                resolve();
+            else
+                stdout.once("drain", resolve);
+        }))
+            .then(() => {
+            queuedBytes -= bytes;
+        }, (err) => {
+            queuedBytes -= bytes;
+            throw err;
+        });
+        writeChain.catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            try {
+                stderr.write(`h2a mcp-serve: stdout write error: ${message}\n`);
+            }
+            catch {
+                /* stderr is diagnostic-only; a broken diagnostic sink is not fatal */
+            }
+        });
+    }
+    /** Bound and enqueue a JSON-RPC response; returns the frame ACTUALLY emitted. */
+    function emitResponse(id, responseObject) {
+        const frame = boundResponseFrame(id, responseObject, frameBudget, recover);
+        enqueueLine(frame.line);
+        return frame;
+    }
+    emitNotification = (notification, meta) => {
+        if (queuedBytes > MAX_QUEUE_BYTES) {
+            // Queue bound: drop rather than grow memory unbounded. A response is never
+            // dropped; a notification is retried by the dispatcher (snapshot held).
+            try {
+                stderr.write(`h2a mcp-serve: notification queue full; dropped ${meta.method}\n`);
+            }
+            catch {
+                /* diagnostic only */
+            }
+            return { accepted: false };
+        }
+        const outcome = boundNotificationFrame(notification, meta, frameBudget, recover);
+        if (!outcome) {
+            try {
+                stderr.write(`h2a mcp-serve: dropped unserializable notification ${meta.method}\n`);
+            }
+            catch {
+                /* diagnostic only */
+            }
+            return { accepted: false };
+        }
+        enqueueLine(outcome.frame.line);
+        return { accepted: outcome.accepted };
+    };
     // DEC-052: start the periodic diff scan so subscribed sessions receive
     // pushed presence/inbox/negotiation notifications.
     server.notifications.start();
     let didShutdown = false;
-    function shutdown() {
+    function shutdown(reason = "transport_closed") {
         if (didShutdown)
             return;
         didShutdown = true;
+        try {
+            // L2: the transport is gone — cancel any in-flight identity resolution so
+            // no NEW transaction starts and no late activation/ACK can follow. A
+            // transaction already entered under a lock finishes cooperatively; a
+            // blocked worker is logged, never SIGKILL'd (it may hold a fence).
+            identityController?.cancel(reason);
+        }
+        catch {
+            /* best effort */
+        }
         try {
             server.notifications.stop();
             server.sessions.closeAll("closed");
@@ -175,62 +317,84 @@ export function runMcpStdio(options) {
     // WP-F: the auto-opened session id, so the line loop can mark MCP activity on
     // it (presence-honesty — proof the host→server channel is carrying traffic).
     let autoOpenedSessionId;
-    // DEC-105 (EVO-6): auto-open a presence session at boot when requested, so
-    // the host joins the bus at startup. Historically this is best-effort; a
-    // structured readiness challenge upgrades failure to fatal because no ACK
-    // may be published for an unreachable sidecar.
-    if (options.autoOpen) {
-        try {
-            const opened = server.sessions.open({
-                instance: options.autoOpen.instance,
-                ...(options.autoOpen.host !== undefined ? { host: options.autoOpen.host } : {}),
-                ...(options.autoOpen.workspace !== undefined
-                    ? { workspace: options.autoOpen.workspace }
-                    : {}),
-                ...(options.autoOpen.name !== undefined ? { name: options.autoOpen.name } : {}),
-                version: agentVersion(options.autoOpen.host),
-                // Auto-capture our owning local terminal (native session or inherited
-                // tmux pane) so loop scheduling has an explicit wake target.
-                ...((() => {
-                    const lc = detectLocalLaunchContext(process.env, undefined, `h2a mcp-serve --host ${options.autoOpen.host ?? ""}`.trim());
-                    return lc ? { launchContext: lc } : {};
-                })()),
-                interests: {
-                    scopes: [...(options.autoOpen.scopes ?? ["scope:default"])],
-                    negotiations: []
-                }
-            });
-            autoOpenedSessionId = opened.sessionId;
-            // Spec 2026-07-25-h2a-lane-addressing §D1b: follow the host-native title
-            // for the life of the session, so a rename converges into presence within
-            // one heartbeat instead of staying stale until the host reconnects.
-            // Absent when the operator passed an explicit `--name`.
-            if (options.autoOpen.refreshDisplayName) {
-                server.sessions.setDisplayNameResolver(opened.sessionId, options.autoOpen.refreshDisplayName);
-            }
-            const delegatorTmuxSession = currentTmuxSessionForSidecar();
-            if (delegatorTmuxSession && options.autoOpen.delegationEligible === true) {
-                delegation = {
-                    origin: "mcp:h2a_run",
-                    delegatorInstance: options.autoOpen.instance,
-                    delegatorTmuxSession,
-                };
-                recordTmuxOwner(delegatorTmuxSession, options.autoOpen.instance);
-            }
-            stderr.write(`h2a mcp-serve: auto-opened session for ${options.autoOpen.instance}\n`);
-            // Reap the false-live presence left by a previous connection of THIS
-            // agent that the host dropped without signalling (process lingered,
-            // blind heartbeat kept presence "live"). Best-effort, same-instance only.
-            try {
-                const reaped = reapDeadInstancePresence(root, options.autoOpen.instance, opened.sessionId);
-                if (reaped.length > 0) {
-                    stderr.write(`h2a mcp-serve: reaped ${reaped.length} stale presence file(s) for ${options.autoOpen.instance}\n`);
-                }
+    function openAutoOpenSession(cfg) {
+        const opened = server.sessions.open({
+            instance: cfg.instance,
+            ...(cfg.host !== undefined ? { host: cfg.host } : {}),
+            ...(cfg.workspace !== undefined ? { workspace: cfg.workspace } : {}),
+            ...(cfg.name !== undefined ? { name: cfg.name } : {}),
+            version: agentVersion(cfg.host),
+            // Auto-capture our owning local terminal (native session or inherited
+            // tmux pane) so loop scheduling has an explicit wake target.
+            ...((() => {
+                const lc = detectLocalLaunchContext(process.env, undefined, `h2a mcp-serve --host ${cfg.host ?? ""}`.trim());
+                return lc ? { launchContext: lc } : {};
+            })()),
+            interests: {
+                scopes: [...(cfg.scopes ?? ["scope:default"])],
+                negotiations: []
             }
-            catch {
-                // best-effort
+        });
+        trace?.phase("session_open");
+        // Spec 2026-07-25-h2a-lane-addressing §D1b: follow the host-native title
+        // for the life of the session so a rename converges into presence within
+        // one heartbeat. Absent when the operator passed an explicit `--name`.
+        if (cfg.refreshDisplayName) {
+            server.sessions.setDisplayNameResolver(opened.sessionId, cfg.refreshDisplayName);
+        }
+        const delegatorTmuxSession = currentTmuxSessionForSidecar();
+        if (delegatorTmuxSession && cfg.delegationEligible === true) {
+            delegation = {
+                origin: "mcp:h2a_run",
+                delegatorInstance: cfg.instance,
+                delegatorTmuxSession
+            };
+            recordTmuxOwner(delegatorTmuxSession, cfg.instance);
+        }
+        stderr.write(`h2a mcp-serve: auto-opened session for ${cfg.instance}\n`);
+        // Reap the false-live presence left by a previous connection of THIS agent
+        // that the host dropped without signalling. Best-effort, same-instance only.
+        try {
+            const reaped = reapDeadInstancePresence(root, cfg.instance, opened.sessionId);
+            if (reaped.length > 0) {
+                stderr.write(`h2a mcp-serve: reaped ${reaped.length} stale presence file(s) for ${cfg.instance}\n`);
             }
         }
+        catch {
+            // best-effort
+        }
+        return opened.sessionId;
+    }
+    // EVO-1 wake (bug #3): wake the idle host when a new inbox envelope arrives.
+    function armInboxWake(cfg, wakeCfg) {
+        const wakeInstance = cfg.instance;
+        const wakeStore = createLocalStore({ root });
+        const wake = createInboxWakeHandler({
+            instance: wakeInstance,
+            readInbox: () => wakeStore.readInbox(wakeInstance),
+            privateKeyPem: wakeCfg.privateKeyPem,
+            driver: wakeCfg.driver,
+            ...(cfg.host !== undefined ? { host: cfg.host } : {}),
+            // Self-wake targets THIS process's OWN tmux pane (inherited $TMUX_PANE).
+            resolveLaunchContext: () => detectTmuxLaunchContext(process.env, undefined, `h2a mcp-serve --host ${cfg.host ?? ""}`.trim()),
+            ...(wakeCfg.nativeSessionId !== undefined
+                ? { resolveNativeSessionId: () => wakeCfg.nativeSessionId }
+                : {}),
+            log: (line) => stderr.write(`h2a mcp-serve: ${line}\n`)
+        });
+        server.notifications.setOnInboxArrival((instance) => {
+            if (instance === wakeInstance)
+                void wake();
+        });
+        stderr.write(`h2a mcp-serve: inbox-wake armed for ${wakeInstance}\n`);
+    }
+    // Eager auto-open: identity was resolved synchronously before the transport
+    // (the historical path, kept for existing consumers/tests). Best-effort unless
+    // a structured readiness challenge upgrades failure to fatal.
+    if (options.autoOpen) {
+        try {
+            autoOpenedSessionId = openAutoOpenSession(options.autoOpen);
+        }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             stderr.write(`h2a mcp-serve: auto-open failed: ${message}\n`);
@@ -239,32 +403,99 @@ export function runMcpStdio(options) {
                 throw new Error(`structured auto-open failed: ${message}`);
             }
         }
-        // EVO-1 wake (bug #3): wake the idle host when a new inbox envelope arrives.
-        if (options.wake) {
-            const wakeInstance = options.autoOpen.instance;
-            const wakeStore = createLocalStore({ root });
-            const wake = createInboxWakeHandler({
-                instance: wakeInstance,
-                readInbox: () => wakeStore.readInbox(wakeInstance),
-                privateKeyPem: options.wake.privateKeyPem,
-                driver: options.wake.driver,
-                ...(options.autoOpen.host !== undefined ? { host: options.autoOpen.host } : {}),
-                // Self-wake targets THIS process's OWN tmux pane (inherited $TMUX_PANE),
-                // NOT latestLaunchContext(instance) — with concurrent sessions sharing one
-                // perennial id (durable bug #1), an instance lookup could inject keystrokes
-                // into a DIFFERENT agent's terminal. Native inbox delivery belongs to PR-1.
-                resolveLaunchContext: () => detectTmuxLaunchContext(process.env, undefined, `h2a mcp-serve --host ${options.autoOpen?.host ?? ""}`.trim()),
-                ...(options.wake.nativeSessionId !== undefined
-                    ? { resolveNativeSessionId: () => options.wake?.nativeSessionId }
-                    : {}),
-                log: (line) => stderr.write(`h2a mcp-serve: ${line}\n`)
-            });
-            server.notifications.setOnInboxArrival((instance) => {
-                if (instance === wakeInstance)
-                    void wake();
-            });
-            stderr.write(`h2a mcp-serve: inbox-wake armed for ${wakeInstance}\n`);
-        }
+        if (options.wake)
+            armInboxWake(options.autoOpen, options.wake);
+    }
+    // L2 deferred identity: the transport is already live (initialize / tools/list
+    // / h2a_identity_status answer immediately). The child worker resolves identity
+    // OFF this event loop; only once it is really bound do we open the presence
+    // session, arm the live signer and wake, and publish the correlated readiness
+    // ACK. No provisional key, no early availability ACK.
+    if (options.identityRequest) {
+        const activation = options.identityActivation;
+        const activate = (identity) => {
+            if (!activation) {
+                return { ok: false, cause: "identity_worker_failed", message: "no activation wiring" };
+            }
+            // An explicit --instance override resolves with no key path: presence
+            // opens but no signer is available (h2a_send stays refused, honestly).
+            let privateKeyPem;
+            if (identity.privateKeyPath) {
+                try {
+                    privateKeyPem = readFileSync(identity.privateKeyPath, "utf8");
+                }
+                catch (err) {
+                    return {
+                        ok: false,
+                        cause: "identity_storage_failed",
+                        message: `cannot read identity key: ${err instanceof Error ? err.message : String(err)}`
+                    };
+                }
+            }
+            const cfg = activation.buildAutoOpen(identity);
+            let sessionId;
+            try {
+                sessionId = openAutoOpenSession(cfg);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    cause: "session_open_failed",
+                    message: err instanceof Error ? err.message : String(err)
+                };
+            }
+            autoOpenedSessionId = sessionId;
+            // F1: if any later activation step fails, roll ALL partial work back so a
+            // failed identity never leaves a live presence session, a live signer, an
+            // armed self-wake, or (worse) a published readiness ACK behind it.
+            const rollback = () => {
+                try {
+                    server.sessions.close(sessionId, "closed");
+                }
+                catch {
+                    /* best effort */
+                }
+                // Disarm the inbox-wake (it signs self-wake lines) — a no-op handler.
+                try {
+                    server.notifications.setOnInboxArrival(() => { });
+                }
+                catch {
+                    /* best effort */
+                }
+                liveSendContext = undefined;
+                autoOpenedSessionId = undefined;
+            };
+            if (privateKeyPem !== undefined) {
+                const wakeCfg = activation.buildWake?.(privateKeyPem, cfg.instance, cfg.host);
+                if (wakeCfg)
+                    armInboxWake(cfg, wakeCfg);
+                // Only NOW is a trusted local signer available for h2a_send.
+                liveSendContext = { instance: cfg.instance, privateKeyPem };
+            }
+            if (options.readiness) {
+                try {
+                    publishReadinessAck(options.readiness, sessionId);
+                    trace?.phase("readiness_ack");
+                }
+                catch (err) {
+                    // The ACK is the LAST step; a failure here would otherwise leave the
+                    // session/signer/wake live under a `failed` state — roll them back.
+                    rollback();
+                    return {
+                        ok: false,
+                        cause: "readiness_ack_failed",
+                        message: err instanceof Error ? err.message : String(err)
+                    };
+                }
+            }
+            return { ok: true, sessionId, signer: liveSendContext };
+        };
+        identityController = createIdentityController({
+            request: options.identityRequest,
+            activate,
+            log: (line) => stderr.write(`h2a mcp-serve: ${line}\n`)
+        });
+        identityController.start();
     }
     // Publish only after every synchronous boot step above has completed and
     // immediately before constructing the stdio loop. Auto-upgrade/re-exec runs
@@ -272,6 +503,7 @@ export function runMcpStdio(options) {
     if (options.readiness && autoOpenedSessionId) {
         try {
             publishReadinessAck(options.readiness, autoOpenedSessionId);
+            trace?.phase("readiness_ack");
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -288,14 +520,15 @@ export function runMcpStdio(options) {
         // sessions so presence is marked `closed` immediately rather than lingering
         // as false-live until expiry. Idempotent with the rl `close` path below.
         const onAbort = () => {
-            shutdown();
+            shutdown("signal");
             try {
                 rl.close();
             }
             catch {
                 // ignore
             }
-            resolve();
+            // Flush the bounded writer before resolving so no queued frame is lost.
+            void writeChain.finally(() => resolve());
         };
         if (options.signal) {
             if (options.signal.aborted) {
@@ -318,7 +551,7 @@ export function runMcpStdio(options) {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                writeResponse(stdout, errorResponse(null, -32700, "Parse error", message));
+                emitResponse(null, errorResponse(null, -32700, "Parse error", message));
                 return;
             }
             // JSON-RPC 2.0: a message with NO `id` member is a NOTIFICATION — the
@@ -330,16 +563,61 @@ export function runMcpStdio(options) {
             // at startup. Gate every stdout write on the message actually being a
             // request (DEC-115).
             const isNotification = !("id" in request);
+            // L1: reject an incoming id we cannot correlate within budget (a huge
+            // string, an object, an array) BEFORE building any response — so every
+            // response id below is a finite number, null, or a ≤128-byte string.
+            if (!isNotification && !isAcceptableRequestId(request.id)) {
+                emitResponse(null, buildInvalidRequestId());
+                return;
+            }
             if (request.jsonrpc !== "2.0" || typeof request.method !== "string") {
                 if (!isNotification) {
-                    writeResponse(stdout, errorResponse(request.id ?? null, -32600, "Invalid Request"));
+                    emitResponse((request.id ?? null), errorResponse(request.id ?? null, -32600, "Invalid Request"));
                 }
                 return;
             }
             try {
+                const requestId = typeof request.id === "string" || typeof request.id === "number"
+                    ? request.id
+                    : undefined;
+                if (trace && request.method === "initialize") {
+                    trace.phase("initialize_recv", {
+                        method: "initialize",
+                        ...(requestId !== undefined ? { requestId } : {})
+                    });
+                }
                 const result = handleMethod(server, request.method, request.params);
                 if (!isNotification) {
-                    writeResponse(stdout, successResponse(request.id ?? null, result));
+                    // L1: the SINGLE bounded writer serializes ONCE, bounds the exact UTF-8
+                    // bytes to the frame budget (an oversize result becomes a bounded -32010
+                    // with a recovery ref — never a raw >B write), and returns the frame
+                    // ACTUALLY emitted so the L0 calibration measures the true wire size.
+                    const emitted = emitResponse((request.id ?? null), successResponse(request.id ?? null, result));
+                    // L0 calibration semantics: the PAYLOAD bytes (no trailing newline),
+                    // as before the single-writer refactor. The budget itself counts the
+                    // newline; the trace stays payload-exact so the L0 witness is unchanged.
+                    const bytes = Buffer.byteLength(emitted.json, "utf8");
+                    if (trace) {
+                        const rid = requestId !== undefined ? { requestId } : {};
+                        if (request.method === "initialize") {
+                            trace.phase("initialize_sent", { bytes, ...rid });
+                        }
+                        else if (request.method === "tools/list") {
+                            trace.phase("tools_list_sent", { bytes, ...rid });
+                        }
+                        else if (request.method === "tools/call") {
+                            const rawName = request.params && typeof request.params === "object"
+                                ? request.params.name
+                                : undefined;
+                            const toolField = typeof rawName === "string" ? { tool: rawName } : {};
+                            trace.phase(firstToolCallTraced ? "tool_sent" : "tool_first_sent", {
+                                bytes,
+                                ...rid,
+                                ...toolField
+                            });
+                            firstToolCallTraced = true;
+                        }
+                    }
                 }
             }
             catch (err) {
@@ -353,17 +631,19 @@ export function runMcpStdio(options) {
                     return;
                 }
                 if (err instanceof MethodNotFoundError) {
-                    writeResponse(stdout, errorResponse(request.id ?? null, -32601, `Method not found: ${err.method}`));
+                    emitResponse((request.id ?? null), errorResponse(request.id ?? null, -32601, `Method not found: ${err.method}`));
                     return;
                 }
                 const message = err instanceof Error ? err.message : String(err);
                 stderr.write(`h2a mcp-serve: internal error: ${message}\n`);
-                writeResponse(stdout, errorResponse(request.id ?? null, -32603, `Internal error: ${message}`));
+                emitResponse((request.id ?? null), errorResponse(request.id ?? null, -32603, `Internal error: ${message}`));
             }
         });
         rl.on("close", () => {
             shutdown();
-            resolve();
+            // Flush the bounded writer before resolving so the last frame is on the
+            // wire before the process (bin.ts awaits this promise) can exit.
+            void writeChain.finally(() => resolve());
         });
         rl.on("error", (err) => {
             shutdown();