@agent-delivery-harness/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+delivery-harness
+Copyright the delivery-harness authors
+
+This product includes software developed by the delivery-harness authors
+(https://github.com/kwam1na/agent-delivery-harness).

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@agent-delivery-harness/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server exposing the delivery harness submission surface",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@agent-delivery-harness/cli": "0.1.0",
+    "@agent-delivery-harness/kernel": "0.1.0"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Delivery harness MCP server.
+ *
+ * `server.ts` is the tool surface — a wrapper over the CLI's command core at
+ * strict parity. `stdio.ts` is the transport that carries it: newline-delimited
+ * JSON-RPC 2.0, hand-rolled, no runtime dependency.
+ */
+
+export const PACKAGE_NAME = "@agent-delivery-harness/mcp";
+
+export {
+  HANDSHAKE_PROTOCOL_VERSIONS,
+  LOG_LEVELS,
+  MCP_PROTOCOL_VERSION,
+  MCP_SERVER_CAPABILITIES,
+  MCP_SERVER_INFO,
+  MCP_STATELESS_PROTOCOL_VERSION,
+  META_CLIENT_CAPABILITIES,
+  META_CLIENT_INFO,
+  META_LOG_LEVEL,
+  META_PROTOCOL_VERSION,
+  META_SERVER_INFO,
+  META_STATELESS_KEYS,
+  STATELESS_PROTOCOL_VERSIONS,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  TOOL_LIST_CACHE_SCOPE,
+  TOOL_LIST_TTL_MS,
+  callTool,
+  listTools,
+  toolResultFor,
+  type McpToolResult,
+  type ToolHostRuntime,
+  type ToolListing,
+  type ToolOutcome,
+} from "./server.ts";
+
+export {
+  INVALID_PARAMS,
+  INVALID_REQUEST,
+  JSON_RPC_VERSION,
+  METHOD_NOT_FOUND,
+  PARSE_ERROR,
+  UNSUPPORTED_PROTOCOL_VERSION,
+  createSession,
+  encodeResponse,
+  handleRpcLine,
+  handleRpcMessage,
+  serveStdio,
+  type JsonRpcId,
+  type JsonRpcResponse,
+  type McpSession,
+} from "./stdio.ts";

package/src/server.ts

@@ -0,0 +1,493 @@
+/**
+ * The MCP tool surface: `review-context` and `submit-evidence`, at strict
+ * parity with the CLI.
+ *
+ * THIS IS A WRAPPER, NOT A SECOND IMPLEMENTATION. Every tool call is turned
+ * into the argv the CLI would have been invoked with and handed to
+ * `runCliBoundary` — the same boundary, the same command modules, the same
+ * config loader, the same exit-code classification, the same renderer. The text
+ * an agent reads is literally the bytes the CLI wrote, captured rather than
+ * printed. Parity is therefore a property of the construction, and the parity
+ * table beside this file is what keeps it one.
+ *
+ * WHY NO MCP SDK. The stdio transport is newline-delimited JSON-RPC 2.0 and the
+ * three methods this server answers are small and fully specified, so the SDK
+ * would buy framing this package can write in a page — at the cost of the first
+ * runtime dependency in a repo that refused one on its canonicalizer for
+ * supply-chain reasons. The protocol layer lives in `stdio.ts`; this module is
+ * transport-free so the parity suite drives the same code an agent reaches.
+ *
+ * A DELIBERATE SUBSET. Two of the CLI's seven commands are exposed. The rest
+ * are not tools, and a call naming one is an unknown tool: what a tool call may
+ * reach is the registry below, never the CLI's. Exposing less than the CLI is
+ * within the contract; behaving differently about what is exposed is not.
+ *
+ * WHAT AN AGENT NEVER GETS. No TTY, therefore no waiver prompt — an MCP session
+ * has no human at the other end to answer one, and a prompt nobody can answer
+ * is either a hang or a forged consent. Both TTY flags are hard `false` here.
+ */
+import {
+  CliInterruption,
+  EXIT_OK,
+  EXIT_USAGE,
+  commandBlocker,
+  importHarnessConfig,
+  reviewContextCommand,
+  runCliBoundary,
+  submitEvidenceCommand,
+  type CliRuntime,
+  type CommandDescriptor,
+} from "@agent-delivery-harness/cli";
+import {
+  BlockedError,
+  createInternalErrorBlocker,
+  renderBlockers,
+  serializeBlockers,
+  type ArtifactsPort,
+  type Blocker,
+  type EnvSnapshot,
+  type HarnessConfig,
+  type LiveProviderResult,
+  type SerializedBlockers,
+} from "@agent-delivery-harness/kernel";
+
+// ── Protocol identity ────────────────────────────────────────────────────────
+
+/**
+ * The revision the handshake settles on, and the older ones it will still speak
+ * if a client asks for one. Newest first: `initialize` echoes the client's
+ * version when it is on this list and answers with the newest otherwise, which
+ * is the negotiation the spec asks for.
+ *
+ * 2025-03-26 is missing on purpose. It is the one revision that requires a
+ * server to accept JSON-RPC batches, and the transport refuses every array; a
+ * client asking for it is answered with the newest revision here, where that
+ * refusal is true. 2024-11-05 predates batching and carries no such
+ * requirement.
+ */
+export const MCP_PROTOCOL_VERSION = "2025-11-25";
+export const HANDSHAKE_PROTOCOL_VERSIONS: readonly string[] = Object.freeze([MCP_PROTOCOL_VERSION, "2025-06-18", "2024-11-05"]);
+
+/**
+ * The stateless revision, and the list of stateless revisions — one, today.
+ *
+ * 2026-07-28 removed the handshake rather than extending it. A client no longer
+ * negotiates once and remembers; it declares its protocol version and
+ * capabilities on every request, and the server answers each request on its own
+ * terms. That makes "which revision is this connection speaking" the wrong
+ * question, and `HANDSHAKE_PROTOCOL_VERSIONS` and this list the two answers to
+ * the right one: which revisions arrive through `initialize`, and which arrive
+ * in `_meta`.
+ */
+export const MCP_STATELESS_PROTOCOL_VERSION = "2026-07-28";
+export const STATELESS_PROTOCOL_VERSIONS: readonly string[] = Object.freeze([MCP_STATELESS_PROTOCOL_VERSION]);
+
+/**
+ * Everything this server speaks, newest first — for documentation and for tests
+ * that need the whole set.
+ *
+ * NOT WHAT `server/discover` ANSWERS. That field is `supportedVersions`:
+ * "Protocol versions the server supports. The client should choose one of these
+ * for subsequent requests" — and on stdio, "The server returns a
+ * `DiscoverResult`: the server is modern. Select a mutually supported version
+ * from `supportedVersions` and continue." There is no branch back to
+ * `initialize` from there; a `DiscoverResult` arriving is itself what tells the
+ * client to stay modern. A handshake revision named in that field would
+ * therefore be a trap — a conforming client selects 2024-11-05, continues
+ * modern, and earns a guaranteed `UnsupportedProtocolVersionError`. So the
+ * probe answers `STATELESS_PROTOCOL_VERSIONS`, the same list the error carries,
+ * for the same loop-avoidance reason. What a handshake client can reach is
+ * discovered the way it always was: by sending `initialize`.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = Object.freeze([
+  ...STATELESS_PROTOCOL_VERSIONS,
+  ...HANDSHAKE_PROTOCOL_VERSIONS,
+]);
+
+/** Version tracks the package; the release mechanics keep the two in step. */
+export const MCP_SERVER_INFO = { name: "delivery-harness", version: "0.0.0" } as const;
+
+// ── Per-request protocol metadata ────────────────────────────────────────────
+
+/**
+ * The `_meta` keys 2026-07-28 reserves. Named rather than spelled inline
+ * because a typo in one of these is a request silently read as the wrong era —
+ * the failure mode that has no symptom until a client sees the wrong envelope.
+ */
+export const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+export const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
+export const META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+export const META_LOG_LEVEL = "io.modelcontextprotocol/logLevel";
+export const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+
+/**
+ * The `_meta` members whose presence identifies a request as stateless: the
+ * four per-request protocol fields 2026-07-28 defines, and nothing else.
+ *
+ * WHY NOT THE `io.modelcontextprotocol/` PREFIX. Because that prefix marks MCP
+ * ownership, not the modern era, and the two are not the same set.
+ * 2025-11-25's tasks feature reserves a key under it — "All requests,
+ * notifications, and responses related to a task **MUST** include the
+ * `io.modelcontextprotocol/related-task` key in their `_meta` field" — so a
+ * handshake-era request can carry a prefixed key perfectly legitimately. A
+ * prefix test would route that request into the stateless path and reject it
+ * for a missing protocol version, which is exactly what the same page forbids:
+ * "Receivers that do not declare the task capability for a request type
+ * **MUST** process requests of that type normally, ignoring any
+ * task-augmentation metadata if present." This server declares no `tasks`
+ * capability, so that MUST binds it, and enumerating the four modern members is
+ * what keeps it honoured.
+ *
+ * Keying on the set rather than on `protocolVersion` alone is still what stops
+ * a modern request that omitted a required field from being quietly served as a
+ * legacy one — a request carrying `clientCapabilities` and no version is
+ * unmistakably modern and gets told so.
+ *
+ * WHY `logLevel` BELONGS HERE. The other three are era-exclusive by
+ * construction — no handshake revision has per-request protocol fields at all —
+ * but `logLevel` is a member a reader could plausibly imagine predating the
+ * rewrite, so the premise is named rather than assumed. It does not: through
+ * 2025-11-25 the log level travels as the `logging/setLevel` *method*, and that
+ * revision's `_meta` section defines only the key-name grammar and the reserved
+ * prefix, naming no protocol-field keys whatever. 2026-07-28 is the revision
+ * that moved it: "Log level is now set per-request via
+ * `io.modelcontextprotocol/logLevel` in `_meta`."
+ */
+export const META_STATELESS_KEYS: readonly string[] = Object.freeze([
+  META_PROTOCOL_VERSION,
+  META_CLIENT_INFO,
+  META_CLIENT_CAPABILITIES,
+  META_LOG_LEVEL,
+]);
+
+/** RFC 5424 severities, as the logging utility enumerates them. */
+export const LOG_LEVELS: readonly string[] = Object.freeze([
+  "debug",
+  "info",
+  "notice",
+  "warning",
+  "error",
+  "critical",
+  "alert",
+  "emergency",
+]);
+
+/**
+ * The caching hints on every `CacheableResult` this server returns.
+ *
+ * `"public"` is the honest scope: the advertised surface is two fixed tools,
+ * identical for every caller, carrying nothing user-specific — the spec's own
+ * example of when public is appropriate. The TTL is an hour because the list is
+ * compiled into the binary and cannot change while the process runs; it is a
+ * freshness hint, and this one is generous because there is nothing to go
+ * stale.
+ */
+export const TOOL_LIST_TTL_MS = 3_600_000;
+export const TOOL_LIST_CACHE_SCOPE = "public" as const;
+
+/** What `server/discover` and the handshake both report. */
+export const MCP_SERVER_CAPABILITIES = { tools: { listChanged: false } } as const;
+
+const MCP_SOURCE_ID = "delivery-harness.mcp";
+
+// ── What a tool call may reach ───────────────────────────────────────────────
+
+/** Everything the host provides. No streams: this module never prints. */
+export interface ToolHostRuntime {
+  readonly cwd: string;
+  readonly env: EnvSnapshot;
+  readonly loadConfig?: (rootDir: string) => Promise<HarnessConfig>;
+  readonly artifacts?: ArtifactsPort;
+  readonly liveResults?: readonly LiveProviderResult[];
+}
+
+/**
+ * One tool call, classified the way the CLI classifies an invocation.
+ *
+ * `exitCode` is carried verbatim rather than translated, because the CLI's
+ * three classes are the contract: 0 passed, 2 could not be parsed, anything
+ * else is a policy failure. `outcome` is that same classification named, so an
+ * agent reading structured content does not have to know shell conventions.
+ */
+export interface ToolOutcome {
+  readonly outcome: "ok" | "blocked" | "usage";
+  readonly exitCode: number;
+  readonly text: string;
+  readonly blockers: SerializedBlockers;
+}
+
+export interface ToolListing {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: Record<string, unknown>;
+}
+
+export interface McpToolResult {
+  readonly content: readonly { readonly type: "text"; readonly text: string }[];
+  readonly isError: boolean;
+  readonly structuredContent: {
+    readonly outcome: ToolOutcome["outcome"];
+    readonly exitCode: number;
+    readonly blockers: SerializedBlockers;
+  };
+}
+
+/** Either the argv the boundary runs, or the typed usage failure to report. */
+type ArgumentTranslation = { readonly ok: true; readonly argv: readonly string[] } | { readonly ok: false; readonly blocker: Blocker };
+
+interface ToolDefinition {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: Record<string, unknown>;
+  readonly command: CommandDescriptor;
+  translate(args: Record<string, unknown>): ArgumentTranslation;
+}
+
+// ── Argument translation ─────────────────────────────────────────────────────
+
+function usageBlocker(code: string, summary: string, details: string, remediationSummary: string): Blocker {
+  return commandBlocker({
+    code,
+    sourceId: MCP_SOURCE_ID,
+    summary,
+    details,
+    remediations: [{ id: "correct-the-tool-call", kind: "manual_action", summary: remediationSummary }],
+  });
+}
+
+const TOOL_NAMES_SENTENCE = (): string => TOOLS.map((tool) => tool.name).join(", ");
+
+/**
+ * Rejects members the tool does not define, for the same reason the manifest
+ * validator rejects them: a tolerated stranger is how a caller comes to believe
+ * it configured something. Unlike a manifest, the offending name is caller
+ * text — it reaches an agent's screen through the renderer, never raw.
+ */
+function rejectUnknownMembers(tool: ToolDefinition, args: Record<string, unknown>, defined: readonly string[]): Blocker | null {
+  const unknown = Object.keys(args).filter((name) => !defined.includes(name));
+  if (unknown.length === 0) return null;
+  return usageBlocker(
+    "unknown_tool_argument",
+    `The ${tool.name} tool does not define every argument this call supplied.`,
+    `Undefined argument(s): ${unknown.join(", ")}. Defined: ${defined.length === 0 ? "(none)" : defined.join(", ")}.`,
+    `Call ${tool.name} with only the arguments its input schema declares.`,
+  );
+}
+
+/**
+ * The tools, named exactly as the CLI names its commands.
+ *
+ * That is the naming decision this unit settles: one vocabulary for an operator
+ * reading a terminal and an agent reading a tool list, so guidance that names
+ * `submit-evidence` is executable on both surfaces without translation.
+ */
+const TOOLS: readonly ToolDefinition[] = [
+  {
+    name: reviewContextCommand.name,
+    description:
+      "Show the reviewable-change context for the prepared candidate: its tree, the relevant-line count, whether the gate's obligations activate, and how to submit evidence. Requires a current preparation receipt.",
+    inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false },
+    command: reviewContextCommand,
+    translate(args) {
+      const unknown = rejectUnknownMembers(this, args, []);
+      if (unknown !== null) return { ok: false, blocker: unknown };
+      return { ok: true, argv: [reviewContextCommand.name] };
+    },
+  },
+  {
+    name: submitEvidenceCommand.name,
+    description:
+      "Validate a provider evidence manifest against delivery-evidence/1 and publish its per-claim records. Rejections carry the violated rule's code; nothing is published unless the whole submission is accepted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        manifest: { type: "string", description: "Path to the manifest.json to submit, inside its allocated run root." },
+      },
+      required: ["manifest"],
+      additionalProperties: false,
+    },
+    command: submitEvidenceCommand,
+    translate(args) {
+      const unknown = rejectUnknownMembers(this, args, ["manifest"]);
+      if (unknown !== null) return { ok: false, blocker: unknown };
+      const manifest = args["manifest"];
+      // Absent is deliberately *not* rejected here. The schema says the member
+      // is required, and the command says so too — in its own words, with its
+      // own exit-2 class. Delegating keeps one sentence for both surfaces
+      // instead of two that drift.
+      if (manifest === undefined) return { ok: true, argv: [submitEvidenceCommand.name] };
+      if (typeof manifest !== "string") {
+        return {
+          ok: false,
+          blocker: usageBlocker(
+            "invalid_tool_argument",
+            "The submit-evidence tool's manifest argument must be a filesystem path.",
+            `manifest was ${manifest === null ? "null" : typeof manifest}, not a string.`,
+            "Call submit-evidence with manifest set to the path of the manifest.json to submit.",
+          ),
+        };
+      }
+      return { ok: true, argv: [submitEvidenceCommand.name, "--manifest", manifest] };
+    },
+  },
+];
+
+// ── The advertised surface ───────────────────────────────────────────────────
+
+export function listTools(): readonly ToolListing[] {
+  return TOOLS.map((tool) => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema }));
+}
+
+// ── Running one call through the command core ────────────────────────────────
+
+const EMPTY_BLOCKERS: readonly Blocker[] = Object.freeze([]);
+
+function classify(exitCode: number): ToolOutcome["outcome"] {
+  if (exitCode === EXIT_OK) return "ok";
+  if (exitCode === EXIT_USAGE) return "usage";
+  return "blocked";
+}
+
+function outcomeFor(exitCode: number, text: string, blockers: readonly Blocker[]): ToolOutcome {
+  return { outcome: classify(exitCode), exitCode, text, blockers: serializeBlockers(blockers) };
+}
+
+/** A usage failure this module raised itself, rendered like every other one. */
+function usageOutcome(blocker: Blocker): ToolOutcome {
+  return outcomeFor(EXIT_USAGE, renderBlockers([blocker]), [blocker]);
+}
+
+/**
+ * The structured half of a failure the boundary is about to render as text.
+ *
+ * The boundary reports failures on a stream; it does not hand back the typed
+ * blockers behind them, and an agent context window needs the structured form.
+ * Rather than re-deciding anything, this observes the same values on their way
+ * past: a `BlockedError` carries its blockers, and an unexpected throw is
+ * described with the very constructor the boundary uses, so the code and
+ * summary an agent parses are the ones an operator would have read.
+ */
+function blockersFromThrow(error: unknown, descriptor: CommandDescriptor): readonly Blocker[] {
+  if (error instanceof CliInterruption) return EMPTY_BLOCKERS;
+  if (error instanceof BlockedError) return error.blockers;
+  return [
+    createInternalErrorBlocker({
+      source: { kind: "command", id: descriptor.sourceId },
+      error,
+      reproduce: ["delivery-harness", descriptor.name],
+    }),
+  ];
+}
+
+async function throughCommandCore(tool: ToolDefinition, argv: readonly string[], host: ToolHostRuntime): Promise<ToolOutcome> {
+  const out: string[] = [];
+  const err: string[] = [];
+  let observed: readonly Blocker[] = EMPTY_BLOCKERS;
+
+  // The command, wrapped only to observe. It runs the real `run`, returns the
+  // real result, and rethrows the real error: the boundary sees exactly what it
+  // would have seen with the unwrapped descriptor.
+  const observedCommand: CommandDescriptor = {
+    ...tool.command,
+    async run(context) {
+      try {
+        const result = await tool.command.run(context);
+        if (result.kind === "blocked") observed = result.blockers;
+        return result;
+      } catch (error) {
+        observed = blockersFromThrow(error, tool.command);
+        throw error;
+      }
+    },
+  };
+
+  const loadConfig = host.loadConfig ?? importHarnessConfig;
+  const runtime: CliRuntime = {
+    cwd: host.cwd,
+    env: host.env,
+    // No TTY on either side: stdin and stdout are the transport, and a waiver
+    // prompt would have nobody to answer it.
+    stdinIsTTY: false,
+    stdoutIsTTY: false,
+    stdout: (text) => out.push(text),
+    stderr: (text) => err.push(text),
+    loadConfig: async (rootDir) => {
+      try {
+        return await loadConfig(rootDir);
+      } catch (error) {
+        // A config that will not load blocks before the command runs, so the
+        // wrapper above never sees it.
+        observed = blockersFromThrow(error, tool.command);
+        throw error;
+      }
+    },
+    ...(host.artifacts === undefined ? {} : { artifacts: host.artifacts }),
+    ...(host.liveResults === undefined ? {} : { liveResults: host.liveResults }),
+  };
+
+  const exitCode = await runCliBoundary(argv, [observedCommand], runtime);
+  return outcomeFor(exitCode, `${out.join("")}${err.join("")}`.trimEnd(), observed);
+}
+
+/**
+ * Runs one tool call to a classified outcome. Total, like the boundary it wraps:
+ * an unknown tool, unusable arguments, a policy block and an internal error all
+ * come back as an outcome rather than a throw.
+ */
+export async function callTool(name: string, args: unknown, host: ToolHostRuntime): Promise<ToolOutcome> {
+  const tool = TOOLS.find((candidate) => candidate.name === name);
+  if (tool === undefined) {
+    return usageOutcome(
+      usageBlocker(
+        "unknown_tool",
+        "This server does not offer the tool this call named.",
+        `Requested tool: ${name}. Offered: ${TOOL_NAMES_SENTENCE()}.`,
+        `Call one of the tools this server advertises: ${TOOL_NAMES_SENTENCE()}.`,
+      ),
+    );
+  }
+
+  // Absent arguments are an empty object (the spec's own default); anything
+  // else that is not an object is a usage failure rather than a coerced guess.
+  const supplied = args === undefined || args === null ? {} : args;
+  if (typeof supplied !== "object" || Array.isArray(supplied)) {
+    return usageOutcome(
+      usageBlocker(
+        "invalid_tool_arguments",
+        `The ${tool.name} tool's arguments must be an object.`,
+        `Arguments were ${Array.isArray(supplied) ? "an array" : typeof supplied}.`,
+        `Call ${tool.name} with an arguments object matching its input schema.`,
+      ),
+    );
+  }
+
+  const translation = tool.translate(supplied as Record<string, unknown>);
+  if (!translation.ok) return usageOutcome(translation.blocker);
+  return throughCommandCore(tool, translation.argv, host);
+}
+
+// ── The MCP shape ────────────────────────────────────────────────────────────
+
+/**
+ * Shapes an outcome as an MCP tool result.
+ *
+ * One text block, and it is the renderer's output — an agent's context window
+ * is a rendering surface, so the bytes that reach it are the neutralized ones,
+ * not a raw provider string re-serialized on the way out. `structuredContent`
+ * is the renderer's other face (`serializeBlockers`), which neutralizes the
+ * same way. No `outputSchema` is declared: declaring one obliges a server to
+ * repeat the structured content as JSON text for older clients, and a second
+ * copy of every blocker in an agent's context buys nothing this text block does
+ * not already say.
+ *
+ * `isError` is true for both failure classes. A tool result is how MCP reports
+ * a call that ran and failed, and a policy block is exactly that — the protocol
+ * error channel is for calls that could not run at all.
+ */
+export function toolResultFor(outcome: ToolOutcome): McpToolResult {
+  return {
+    content: [{ type: "text", text: outcome.text }],
+    isError: outcome.outcome !== "ok",
+    structuredContent: { outcome: outcome.outcome, exitCode: outcome.exitCode, blockers: outcome.blockers },
+  };
+}

package/src/stdio.ts

@@ -0,0 +1,497 @@
+/**
+ * The stdio transport: newline-delimited JSON-RPC 2.0 over stdin and stdout.
+ *
+ * WHY HAND-ROLLED. MCP's stdio transport is one line of JSON per message, and
+ * the methods a tools-only server answers are `initialize`, `server/discover`,
+ * `tools/list`, `tools/call` and `ping`. That is the whole surface, and it is
+ * written below without a dependency — which matters in a repo that declined an
+ * npm canonicalizer on supply-chain grounds and has carried zero runtime
+ * dependencies since. The SDK would own framing this file states in a page,
+ * and would own it behind a transitive tree nobody here reviews.
+ *
+ * TWO ERAS, ONE PROCESS. MCP 2026-07-28 removed the `initialize` handshake:
+ * every request declares its own protocol version and client capabilities in
+ * `_meta`, results carry a `resultType`, list results carry caching hints,
+ * `server/discover` is mandatory, and `ping` is gone. The three revisions
+ * before it still negotiate through `initialize` and still have `ping`. This
+ * server serves both, and the spec says how: "A dual-era server selects its
+ * behavior from how the client opens ... A request carrying modern per-request
+ * `_meta` is served statelessly according to this revision. An `initialize`
+ * request selects legacy semantics." The branch is per request and reads
+ * nothing remembered, because the newer revision forbids inferring context from
+ * an earlier request on the same connection. Nothing from the newer revision
+ * appears in an older revision's result: a client that negotiated 2024-11-05
+ * reads the bytes it read before 2026-07-28 existed.
+ *
+ * THE TWO ERROR CHANNELS ARE NOT INTERCHANGEABLE. A JSON-RPC error means the
+ * call could not run: unparseable bytes, a method this server does not
+ * implement, params that are not even shaped like params. A *tool result* with
+ * `isError` means the call ran and the harness said no — a policy block, a
+ * usage failure, an unknown tool. Reporting a policy block as a protocol error
+ * would strip the blockers, the remediations, and the outcome class an agent
+ * acts on; reporting a protocol fault as a tool result would tell a client its
+ * malformed request succeeded in reaching a tool. Each stays on its own channel.
+ *
+ * STDOUT IS THE WIRE. Nothing here ever prints diagnostics to stdout — a stray
+ * line would be a protocol violation, not a log. Diagnostics go to stderr.
+ *
+ * WHICH REVISIONS ARE ADVERTISED, AND WHY THE MIDDLE ONE IS NOT. MCP added
+ * JSON-RPC batching in 2025-03-26 — a server speaking that revision must accept
+ * an array of messages — and removed it again in 2025-06-18. This transport
+ * refuses arrays outright, so 2025-03-26 is deliberately absent from the
+ * advertised list: a client asking for it is answered with a revision where
+ * the refusal is the truth. 2024-11-05 predates batching entirely and carries
+ * no such requirement, so it stays. Advertising a revision whose requirements
+ * this file does not meet would be the one protocol lie that costs a client its
+ * ability to reason about the connection at all.
+ */
+import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import {
+  HANDSHAKE_PROTOCOL_VERSIONS,
+  LOG_LEVELS,
+  MCP_PROTOCOL_VERSION,
+  MCP_SERVER_CAPABILITIES,
+  MCP_SERVER_INFO,
+  META_CLIENT_CAPABILITIES,
+  META_LOG_LEVEL,
+  META_PROTOCOL_VERSION,
+  META_SERVER_INFO,
+  META_STATELESS_KEYS,
+  STATELESS_PROTOCOL_VERSIONS,
+  TOOL_LIST_CACHE_SCOPE,
+  TOOL_LIST_TTL_MS,
+  callTool,
+  listTools,
+  toolResultFor,
+  type ToolHostRuntime,
+} from "./server.ts";
+
+// ── JSON-RPC ─────────────────────────────────────────────────────────────────
+
+export const JSON_RPC_VERSION = "2.0";
+
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+
+/**
+ * `UnsupportedProtocolVersionError`, at the code 2026-07-28 renumbered it to.
+ *
+ * It is -32022, not the -32004 the draft used. That revision partitioned the
+ * JSON-RPC implementation-defined range: `-32000` to `-32019` is grandfathered
+ * and "new implementations **SHOULD NOT** use codes from this sub-range at
+ * all", while `-32020` to `-32099` is "reserved for the MCP specification" and
+ * implementations "**MUST NOT** emit any code from this sub-range that is not
+ * defined by this specification". This is the only code from that range this
+ * server emits, and it is emitted with the specified meaning.
+ */
+export const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+
+export type JsonRpcId = string | number | null;
+
+export interface JsonRpcResponse {
+  readonly jsonrpc: typeof JSON_RPC_VERSION;
+  readonly id: JsonRpcId;
+  readonly result?: unknown;
+  readonly error?: { readonly code: number; readonly message: string; readonly data?: unknown };
+}
+
+function ok(id: JsonRpcId, result: unknown): JsonRpcResponse {
+  return { jsonrpc: JSON_RPC_VERSION, id, result };
+}
+
+function fail(id: JsonRpcId, code: number, message: string, data?: unknown): JsonRpcResponse {
+  return { jsonrpc: JSON_RPC_VERSION, id, error: { code, message, ...(data === undefined ? {} : { data }) } };
+}
+
+/**
+ * Session state the protocol carries; the tools themselves are stateless.
+ *
+ * NO HANDSHAKE GATE, AND THEREFORE NO `initialized` FLAG. Refusing `tools/list`
+ * or `tools/call` until the handshake completed was the alternative, and it was
+ * declined on two grounds. The spec's ordering rule is a SHOULD addressed to
+ * the *client*, so a hard server-side gate refuses a pipelining client the spec
+ * allows to be answered, and it would need a rejection code the protocol does
+ * not define for the case. And a flag written on every handshake but read by no
+ * decision is state that can only go stale — the kind a later reader trusts
+ * without noticing nothing maintains it. `protocolVersion` stays because it is
+ * the negotiated result the connection is bound to and the `initialize`
+ * response is built from it.
+ */
+export interface McpSession {
+  protocolVersion: string;
+}
+
+export function createSession(): McpSession {
+  return { protocolVersion: MCP_PROTOCOL_VERSION };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The three id shapes JSON-RPC 2.0 permits. Anything else is not an id. */
+function isUsableId(id: unknown): id is JsonRpcId {
+  return typeof id === "string" || typeof id === "number" || id === null;
+}
+
+function idOf(message: Record<string, unknown>): JsonRpcId {
+  const id = message["id"];
+  return isUsableId(id) ? id : null;
+}
+
+/**
+ * A notification is a message with no `id` *member* — not a message whose id
+ * happens to be null. The distinction matters: answering an explicit null id
+ * with silence would hang a client that is waiting for a response it is
+ * entitled to.
+ */
+function isNotification(message: Record<string, unknown>): boolean {
+  return !Object.prototype.hasOwnProperty.call(message, "id");
+}
+
+/**
+ * The handshake's version selection, drawn only from the revisions that *have*
+ * a handshake.
+ *
+ * A client naming 2026-07-28 in `initialize` is answered with 2025-11-25 rather
+ * than its own request. Echoing it would be this server promising a session
+ * under the revision that abolished sessions — the client would then omit the
+ * per-request `_meta` that revision requires and this server would read every
+ * subsequent request as handshake-era. That is the one place backward
+ * compatibility costs something: a stateless-capable client that opens with
+ * `initialize` is served an older revision instead. The spec's own remedy is
+ * the probe, and `server/discover` is implemented for exactly that.
+ */
+function negotiate(requested: unknown): string {
+  return typeof requested === "string" && HANDSHAKE_PROTOCOL_VERSIONS.includes(requested) ? requested : MCP_PROTOCOL_VERSION;
+}
+
+// ── The stateless revision ───────────────────────────────────────────────────
+
+/**
+ * Whether a request carries stateless per-request metadata.
+ *
+ * The era selector is the spec's: "A dual-era server selects its behavior from
+ * how the client opens ... A request carrying modern per-request `_meta` is
+ * served statelessly according to this revision. An `initialize` request
+ * selects legacy semantics." The test is the presence of any of the four
+ * per-request protocol fields that revision defines, not of the protocol
+ * version alone — a request that carries `clientCapabilities` and forgot the
+ * version is still unmistakably a stateless request, and it must be told so
+ * with a -32602 rather than handed a legacy-shaped success for a revision it
+ * never asked for. It is deliberately *not* a test on the
+ * `io.modelcontextprotocol/` prefix, which a handshake-era task-augmented
+ * request may also carry; see `META_STATELESS_KEYS`. Whatever is or is not
+ * there, the answer comes from this request only: "Servers **MUST NOT** rely on
+ * prior requests over the same connection to establish context".
+ */
+function isStatelessRequest(params: unknown): boolean {
+  if (!isRecord(params)) return false;
+  const meta = params["_meta"];
+  if (!isRecord(meta)) return false;
+  return META_STATELESS_KEYS.some((key) => Object.prototype.hasOwnProperty.call(meta, key));
+}
+
+function metaOf(params: unknown): Record<string, unknown> {
+  const meta = isRecord(params) ? params["_meta"] : undefined;
+  return isRecord(meta) ? meta : {};
+}
+
+/** Every stateless result carries the server's identity and its type. */
+function statelessResult(fields: Record<string, unknown>): Record<string, unknown> {
+  return { resultType: "complete", ...fields, _meta: { [META_SERVER_INFO]: MCP_SERVER_INFO } };
+}
+
+/** The two hints a `CacheableResult` must carry. */
+const CACHE_HINTS = { ttlMs: TOOL_LIST_TTL_MS, cacheScope: TOOL_LIST_CACHE_SCOPE } as const;
+
+/**
+ * Answers one request that declared a protocol version in `_meta`.
+ *
+ * WHAT IS NOT HERE. `ping`, `logging/setLevel` and
+ * `notifications/roots/list_changed` were removed by this revision, and
+ * `initialize` with it — none of them is dispatched below, so each falls to
+ * "method not found", which is the truth under 2026-07-28. `ping` remains
+ * answerable through the handshake path, where the revisions that define it
+ * still live.
+ *
+ * WHAT THIS SERVER STILL DOES NOT EMIT. No `notifications/message`, on any
+ * revision. The revision that moved log level onto `_meta` deprecated the
+ * Logging feature in the same release — "New implementations **SHOULD NOT**
+ * adopt it; existing implementations **SHOULD** migrate to logging to `stderr`
+ * for stdio transports" — and this server already logs to stderr. So the
+ * requirement that a server "**MUST NOT** emit `notifications/message` for a
+ * request that does not include this field" holds by construction rather than
+ * by a check, and a request that *does* set the field is answered with its
+ * response and nothing else. An unrecognized level is still rejected: the
+ * logging page asks for `-32602` there, and a value this server cannot name is
+ * not a request it can claim to have understood.
+ *
+ * WHAT IS DELIBERATELY ABSENT. No `resultType: "input_required"`. That belongs
+ * to the multi round-trip pattern, which replaces server-initiated requests —
+ * and this server initiates none: it has no sampling, no elicitation, no roots,
+ * and no waiver prompt an agent could be asked to answer. Likewise no
+ * `subscriptions/listen` (nothing here changes while the process runs) and no
+ * tasks extension (advertising an extension is a promise, and there is no
+ * durable request behind it).
+ */
+async function handleStateless(
+  method: string,
+  id: JsonRpcId,
+  params: unknown,
+  requested: unknown,
+  host: ToolHostRuntime,
+): Promise<JsonRpcResponse> {
+  // A version that is absent, or present but not a string, is a malformed
+  // request rather than an unsupported revision: -32022 means "this version is
+  // one I do not implement", and a missing member names no version at all. Both
+  // fall under the same rule as any other required field — "A request missing
+  // any required field is malformed; the server MUST reject it with JSON-RPC
+  // error code -32602".
+  if (typeof requested !== "string") {
+    return fail(id, INVALID_PARAMS, `A stateless request must carry ${META_PROTOCOL_VERSION} in _meta as a protocol version string.`);
+  }
+
+  if (!STATELESS_PROTOCOL_VERSIONS.includes(requested)) {
+    // "the server ... MUST respond with an UnsupportedProtocolVersionError
+    // listing the versions it does support". `supported` names what *this*
+    // channel can serve, not everything this server speaks: the client's rule
+    // is to "select a mutually supported version from the `supported` list and
+    // retry the request", and a handshake revision offered here would send it
+    // round the same loop, since those revisions have no per-request form. The
+    // full list — both eras — is what `server/discover` is for.
+    return fail(id, UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version", {
+      supported: STATELESS_PROTOCOL_VERSIONS,
+      requested,
+    });
+  }
+
+  const meta = metaOf(params);
+
+  // "A request missing any required field is malformed; the server MUST reject
+  // it with JSON-RPC error code -32602 (Invalid params)." Capabilities are
+  // required; client info is not, and its absence is not a fault.
+  if (!isRecord(meta[META_CLIENT_CAPABILITIES])) {
+    return fail(id, INVALID_PARAMS, `A request under ${requested} must carry ${META_CLIENT_CAPABILITIES} in _meta.`);
+  }
+
+  const logLevel = meta[META_LOG_LEVEL];
+  if (logLevel !== undefined && (typeof logLevel !== "string" || !LOG_LEVELS.includes(logLevel))) {
+    return fail(id, INVALID_PARAMS, `${META_LOG_LEVEL} must be one of: ${LOG_LEVELS.join(", ")}.`);
+  }
+
+  if (method === "server/discover") {
+    return ok(
+      id,
+      statelessResult({
+        supportedVersions: STATELESS_PROTOCOL_VERSIONS,
+        capabilities: MCP_SERVER_CAPABILITIES,
+        ...CACHE_HINTS,
+      }),
+    );
+  }
+
+  if (method === "tools/list") return ok(id, statelessResult({ tools: listTools(), ...CACHE_HINTS }));
+
+  if (method === "tools/call") {
+    if (!isRecord(params)) return fail(id, INVALID_PARAMS, "tools/call requires a params object.");
+    const name = params["name"];
+    if (typeof name !== "string") return fail(id, INVALID_PARAMS, "tools/call requires a string name.");
+    const outcome = await callTool(name, params["arguments"], host);
+    return ok(id, statelessResult({ ...toolResultFor(outcome) }));
+  }
+
+  return fail(id, METHOD_NOT_FOUND, `Method ${JSON.stringify(method)} is not implemented by this server under ${requested}.`);
+}
+
+/**
+ * Answers one decoded message. Returns `null` for a notification — the one
+ * shape the protocol forbids a response to.
+ */
+export async function handleRpcMessage(message: unknown, host: ToolHostRuntime, session: McpSession): Promise<JsonRpcResponse | null> {
+  if (Array.isArray(message)) {
+    // No revision this server advertises supports batching, and answering a
+    // batch anyway would leave a client believing it negotiated something it
+    // did not.
+    return fail(null, INVALID_REQUEST, "JSON-RPC batches are not part of the protocol revisions this server speaks.");
+  }
+  if (!isRecord(message)) return fail(null, INVALID_REQUEST, "A JSON-RPC message must be an object.");
+  if (message["jsonrpc"] !== JSON_RPC_VERSION) return fail(idOf(message), INVALID_REQUEST, 'A JSON-RPC message must declare jsonrpc "2.0".');
+
+  // ID HYGIENE, BEFORE ANY DISPATCH. An id of an unusable shape cannot be
+  // echoed, so the client could never correlate the result — and `tools/call`
+  // is side-effecting. Coercing such an id to null and running the call anyway
+  // would publish evidence on behalf of a request nobody can match a response
+  // to. An absent id member is a notification and is not an id at all.
+  if (!isNotification(message) && !isUsableId(message["id"])) {
+    return fail(null, INVALID_REQUEST, "A JSON-RPC id must be a string, a number, or null.");
+  }
+
+  const method = message["method"];
+  if (typeof method !== "string") return fail(idOf(message), INVALID_REQUEST, "A JSON-RPC message must name a string method.");
+
+  const id = idOf(message);
+  const params = message["params"];
+
+  // SHAPE DECIDES, NOT THE METHOD NAME. Notifications — `initialized`,
+  // cancellation, progress — are accepted and ignored: this server keeps no
+  // handshake gate and starts no work a client can cancel. A message carrying
+  // an id is a request whatever it is named, so an id-bearing
+  // `notifications/initialized` falls through to normal dispatch and is
+  // answered there. Special-casing the name above this check is what used to
+  // swallow it and leave the client waiting.
+  if (isNotification(message)) return null;
+
+  // THE ERA BRANCH, AND THE ONE METHOD THAT DECIDES IT BY NAME. The spec gives
+  // a dual-era server two selectors, not one: "A request carrying modern
+  // per-request `_meta` is served statelessly according to this revision. An
+  // `initialize` request selects legacy semantics." So `initialize` is answered
+  // as a handshake first, whatever `_meta` it happens to carry — a client whose
+  // transport attaches per-request metadata to everything it sends must still
+  // be able to open with the handshake, or the fallback path the spec tells it
+  // to take does not exist. Every other method takes the era from the request:
+  // a declared protocol version means stateless, its absence means handshake.
+  // Either way the decision is made per request and from the request alone — a
+  // client may interleave both on one connection, and this server must not
+  // infer the era from anything it remembers.
+  if (method === "initialize") {
+    session.protocolVersion = negotiate(isRecord(params) ? params["protocolVersion"] : undefined);
+    return ok(id, {
+      protocolVersion: session.protocolVersion,
+      capabilities: MCP_SERVER_CAPABILITIES,
+      serverInfo: MCP_SERVER_INFO,
+    });
+  }
+
+  if (isStatelessRequest(params)) return handleStateless(method, id, params, metaOf(params)[META_PROTOCOL_VERSION], host);
+
+  if (method === "ping") return ok(id, {});
+
+  if (method === "tools/list") return ok(id, { tools: listTools() });
+
+  if (method === "tools/call") {
+    if (!isRecord(params)) return fail(id, INVALID_PARAMS, "tools/call requires a params object.");
+    const name = params["name"];
+    if (typeof name !== "string") {
+      // Not "unknown tool": the request never named one, which is a malformed
+      // request rather than a call this server declined.
+      return fail(id, INVALID_PARAMS, "tools/call requires a string name.");
+    }
+    const outcome = await callTool(name, params["arguments"], host);
+    return ok(id, toolResultFor(outcome));
+  }
+
+  return fail(id, METHOD_NOT_FOUND, `Method ${JSON.stringify(method)} is not implemented by this server.`);
+}
+
+/**
+ * Decodes one line and answers it. Kept separate from the loop so the framing —
+ * blank lines skipped, undecodable lines answered with a parse error rather
+ * than closing the connection — is testable without streams.
+ */
+export async function handleRpcLine(line: string, host: ToolHostRuntime, session: McpSession): Promise<JsonRpcResponse | null> {
+  const trimmed = line.trim();
+  if (trimmed === "") return null;
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(trimmed);
+  } catch {
+    return fail(null, PARSE_ERROR, "The message could not be parsed as JSON.");
+  }
+  return handleRpcMessage(decoded, host, session);
+}
+
+/**
+ * Serializes a response onto one line.
+ *
+ * The framing requires that no message contain an embedded newline. Every
+ * newline this server produces is inside a rendered blocker string, and
+ * `JSON.stringify` escapes those — so the invariant holds by construction
+ * rather than by a scrub pass that could be forgotten.
+ */
+export function encodeResponse(response: JsonRpcResponse): string {
+  return `${JSON.stringify(response)}\n`;
+}
+
+// ── The loop ─────────────────────────────────────────────────────────────────
+
+/**
+ * Serves until the input ends. Messages are answered in arrival order: the
+ * transport is one connection with one client, and interleaving responses buys
+ * nothing but a reordering bug.
+ */
+export async function serveStdio(input: NodeJS.ReadableStream, write: (line: string) => void, host: ToolHostRuntime): Promise<void> {
+  const session = createSession();
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const response = await handleRpcLine(line, host, session);
+    if (response !== null) write(encodeResponse(response));
+  }
+}
+
+/** Built inside a function, never at import time: the sensor's env rule. */
+export function defaultToolRuntime(): ToolHostRuntime {
+  return { cwd: process.cwd(), env: process.env };
+}
+
+/** The spelling the filesystem can vouch for: the realpath where it can answer, the spelling itself where it cannot. */
+function canonicalEntryPath(entryPath: string): string {
+  try {
+    return realpathSync(entryPath);
+  } catch {
+    return entryPath;
+  }
+}
+
+/**
+ * Whether this module is the entry the process was started with.
+ *
+ * argv and `import.meta.url` may spell the same file differently: argv is the
+ * caller's spelling, and Node builds the module URL from the realpath by
+ * default but from the caller's spelling under `--preserve-symlinks-main`. So
+ * each side is canonicalized independently and the canonical forms compared:
+ * a symlinked spelling matches its realpath whenever the link can be read
+ * (`/tmp` → `/private/tmp` on macOS, a client config's stored path, a pnpm
+ * workspace link), and equal spellings still match when neither side resolves.
+ *
+ * What is NOT claimed: a symlink the filesystem cannot resolve cannot be seen
+ * through, and the failing-exit-code floor below sits inside this guard, so an
+ * under-match exits 0 in silence — the server exiting without ever serving,
+ * a dead transport where the client expected one. The floor cannot be hoisted
+ * above the guard: that would stamp a failing exit code on every process that
+ * merely *imports* this module. And a non-`file:` module href (a bundled or
+ * single-executable build) never matches — such a build must invoke `main`
+ * explicitly.
+ */
+export function invokedDirectly(argvEntry: string | undefined, moduleHref: string): boolean {
+  if (argvEntry === undefined) return false;
+  let modulePath: string;
+  try {
+    modulePath = fileURLToPath(moduleHref);
+  } catch {
+    return false;
+  }
+  return canonicalEntryPath(argvEntry) === canonicalEntryPath(modulePath);
+}
+
+export async function main(): Promise<void> {
+  await serveStdio(process.stdin, (line) => process.stdout.write(line), defaultToolRuntime());
+}
+
+if (invokedDirectly(process.argv[1], import.meta.url)) {
+  // Fail closed for the same reason the CLI does: a server that fell over
+  // without saying so must not look like a clean shutdown.
+  process.exitCode = 1;
+  main()
+    .then(() => {
+      process.exitCode = 0;
+    })
+    .catch((error: unknown) => {
+      process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+      process.exitCode = 1;
+    });
+}