@agent-delivery-harness/mcp 0.7.3

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Kwamina Essuah Mensah
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+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 Kwamina Essuah Mensah
+
+This product includes software developed by the delivery-harness authors
+(https://github.com/kwam1na/agent-delivery-harness).

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@agent-delivery-harness/mcp",
+  "version": "0.7.3",
+  "type": "module",
+  "description": "MCP server exposing the delivery harness submission surface",
+  "license": "FSL-1.1-ALv2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/v26-technologies/agent-delivery-harness.git",
+    "directory": "packages/mcp"
+  },
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "dependencies": {
+    "@agent-delivery-harness/cli": "0.7.3",
+    "@agent-delivery-harness/kernel": "0.7.3"
+  },
+  "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,576 @@
+/**
+ * The MCP tool surface: `review-context`, `submit-evidence`, and the read-only
+ * `managed` projection, 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, IN TWO DIMENSIONS. Three of the CLI's eleven commands are
+ * exposed, and the third — `managed` — exposes only its read-only operations.
+ * 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.
+ *
+ * The second dimension is the one that matters most. A tool surface that could
+ * submit a stage result or run a sensor would be a second orchestrator sitting
+ * beside the host that already owns delegation and sequencing. So the operation
+ * enum below is read-class only, and the facade's contract-inventory sensor
+ * checks that against the product's own operation inventory rather than against
+ * this comment.
+ *
+ * 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,
+  managedCommand,
+  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(", ");
+
+/**
+ * The managed-delivery operations this server will translate, and the whole
+ * set of them.
+ *
+ * WHY ONLY THESE. The facade's boundary is that a tool surface inspects a
+ * delivery rather than orchestrating it: the product owns whether a checkpoint
+ * is valid and what evidence suffices, and the host owns how it delegates and
+ * sequences the work. A tool that could submit a stage result or run a sensor
+ * would be a second orchestrator sitting beside the host — so the CLI's control
+ * operations are simply not reachable from here, and the contract-inventory
+ * sensor checks that every name below is a `read`-class operation in the
+ * facade's own inventory.
+ */
+export const MANAGED_READ_OPERATIONS: readonly string[] = Object.freeze([
+  "status",
+  "deliveries",
+  "next",
+  "explain-blocker",
+  "blockers",
+  "operations",
+]);
+
+/**
+ * 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] };
+    },
+  },
+  {
+    name: managedCommand.name,
+    description:
+      "Inspect the managed delivery: its typed status model, the next valid checkpoint, the current blocker and its remediation, the blocker inventory, this installation's registered deliveries, and the facade's own operation contract. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        operation: {
+          type: "string",
+          enum: [...MANAGED_READ_OPERATIONS],
+          description: "Which read-only projection to return.",
+        },
+      },
+      required: ["operation"],
+      additionalProperties: false,
+    },
+    command: managedCommand,
+    translate(args) {
+      const unknown = rejectUnknownMembers(this, args, ["operation"]);
+      if (unknown !== null) return { ok: false, blocker: unknown };
+      const operation = args["operation"];
+      if (operation === undefined) return { ok: true, argv: [managedCommand.name] };
+      if (typeof operation !== "string") {
+        return {
+          ok: false,
+          blocker: usageBlocker(
+            "invalid_tool_argument",
+            "The managed tool's operation argument must be a string.",
+            `operation was ${operation === null ? "null" : typeof operation}, not a string.`,
+            `Call managed with operation set to one of: ${MANAGED_READ_OPERATIONS.join(", ")}.`,
+          ),
+        };
+      }
+      // The enum is enforced here rather than delegated, because delegating it
+      // would hand a control operation straight to the command. What the CLI
+      // offers an operator at a terminal and what this server offers a model
+      // are deliberately different sets, and this is where that difference is
+      // mechanical rather than documentary.
+      if (!MANAGED_READ_OPERATIONS.includes(operation)) {
+        return {
+          ok: false,
+          blocker: usageBlocker(
+            "operation_not_offered",
+            "This server offers the managed delivery's read-only projections only.",
+            `Requested operation: ${operation}. Offered: ${MANAGED_READ_OPERATIONS.join(", ")}.`,
+            "Drive checkpoints from the bound worktree's CLI; this tool inspects the delivery, it does not orchestrate it.",
+          ),
+        };
+      }
+      return { ok: true, argv: [managedCommand.name, operation] };
+    },
+  },
+];
+
+// ── 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,535 @@
+/**
+ * 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 { createInterface } from "node:readline";
+import { invokedDirectly } from "@agent-delivery-harness/kernel";
+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 — produce no response in this dispatcher. The stdio
+  // loop intercepts a well-formed cancellation first so it can suppress active
+  // responses and queued work; other transports may provide their own request
+  // lifecycle. 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 decoded = decodeRpcLine(line);
+  if (decoded.kind === "blank") return null;
+  if (decoded.kind === "parse-error") return decoded.response;
+  return handleRpcMessage(decoded.message, host, session);
+}
+
+type DecodedRpcLine =
+  | { readonly kind: "blank" }
+  | { readonly kind: "parse-error"; readonly response: JsonRpcResponse }
+  | { readonly kind: "message"; readonly message: unknown };
+
+function decodeRpcLine(line: string): DecodedRpcLine {
+  const trimmed = line.trim();
+  if (trimmed === "") return { kind: "blank" };
+  try {
+    return { kind: "message", message: JSON.parse(trimmed) as unknown };
+  } catch {
+    return { kind: "parse-error", response: fail(null, PARSE_ERROR, "The message could not be parsed as JSON.") };
+  }
+}
+
+/**
+ * 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. Ordinary messages are answered in arrival order,
+ * while a well-formed `notifications/cancelled` is observed immediately. The
+ * split matters: awaiting the active request before reading its cancellation
+ * makes suppression impossible by construction.
+ *
+ * Cancellation is response suppression, not a new tool API. Active work is
+ * allowed to settle but its response is discarded; queued work is skipped
+ * before it reaches the host. Older revisions say a receiver SHOULD stop
+ * processing and suppress the response, while 2026-07-28 strengthens the stdio
+ * rule to no further messages for that request. The same suppression satisfies
+ * all four revisions this server advertises.
+ *
+ * Unknown and completed ids are absent from `pending`, so they are ignored.
+ * Malformed cancellation notifications never reach this branch and are ignored
+ * as ordinary notifications. `initialize` is deliberately non-cancellable, as
+ * the protocol requires: a cancellation naming it is ignored whether queued or
+ * active. These choices are explicit because accidental notification dropping
+ * was the defect this loop previously carried.
+ */
+export async function serveStdio(input: NodeJS.ReadableStream, write: (line: string) => void, host: ToolHostRuntime): Promise<void> {
+  const session = createSession();
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  type PendingRequest = { readonly id: JsonRpcId; readonly method: string; state: "queued" | "active"; cancelled: boolean };
+  const pending = new Map<JsonRpcId, PendingRequest>();
+  let work = Promise.resolve();
+
+  for await (const line of lines) {
+    const decoded = decodeRpcLine(line);
+    if (decoded.kind === "message" && isRecord(decoded.message)) {
+      const message = decoded.message;
+      const params = message["params"];
+      if (
+        message["jsonrpc"] === JSON_RPC_VERSION &&
+        isNotification(message) &&
+        message["method"] === "notifications/cancelled" &&
+        isRecord(params) &&
+        isUsableId(params["requestId"])
+      ) {
+        const target = pending.get(params["requestId"]);
+        if (target !== undefined && target.method !== "initialize") target.cancelled = true;
+        continue;
+      }
+    }
+
+    let tracked: PendingRequest | undefined;
+    if (
+      decoded.kind === "message" &&
+      isRecord(decoded.message) &&
+      decoded.message["jsonrpc"] === JSON_RPC_VERSION &&
+      !isNotification(decoded.message) &&
+      isUsableId(decoded.message["id"]) &&
+      typeof decoded.message["method"] === "string"
+    ) {
+      tracked = { id: decoded.message["id"], method: decoded.message["method"], state: "queued", cancelled: false };
+      pending.set(tracked.id, tracked);
+    }
+
+    work = work.then(async () => {
+      if (tracked?.cancelled === true) {
+        if (pending.get(tracked.id) === tracked) pending.delete(tracked.id);
+        return;
+      }
+      if (tracked !== undefined) tracked.state = "active";
+
+      const response =
+        decoded.kind === "blank"
+          ? null
+          : decoded.kind === "parse-error"
+            ? decoded.response
+            : await handleRpcMessage(decoded.message, host, session);
+
+      if (tracked !== undefined) {
+        if (pending.get(tracked.id) === tracked) pending.delete(tracked.id);
+        if (tracked.cancelled) return;
+      }
+      if (response !== null) write(encodeResponse(response));
+    });
+  }
+  await work;
+}
+
+/** Built inside a function, never at import time: the sensor's env rule. */
+export function defaultToolRuntime(): ToolHostRuntime {
+  return { cwd: process.cwd(), env: process.env };
+}
+
+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;
+    });
+}