@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.131

package/README.md

@@ -7,10 +7,27 @@
 
 CommHub: MCP Streamable HTTP + SSE push + REST API for an AI agent network. Single-process Bun server, SQLite-backed, zero config when launched through `anet`.
 
-The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`, currently v2.2.10 at v0.10.11) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
+The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
 
 ## Quick start (verified)
 
+> ⚠️ **Do not run `bunx @sleep2agi/commhub-server` without a version**
+> Without a version this resolves to the npm `latest` dist-tag, and **`latest` is currently `0.8.8` (published 2026-06-24)**.
+> 
+> On `0.8.8` an anonymous `GET /health` **returns the `{networkId}:{alias}` of every live SSE connection** — no token required.
+> The redaction fix is [`7bacb729`](https://github.com/sleep2agi/agent-network/commit/7bacb729) (`security(#473)`, **2026-07-29**),
+> **35 days after** `0.8.8` shipped, so `0.8.8` does not contain it.
+> 
+> **Pin a version, or use the preview channel:**
+> 
+> ```bash
+> bunx --bun @sleep2agi/commhub-server@preview      # contains the redaction fix
+> ```
+> 
+> Or use the supported path, `anet hub start`, which pulls the version in `PINNED_SERVER_VERSION` rather than `latest`.
+> 
+> Self-check: `curl -sS http://<host>:9200/health | jq 'has("sse_sessions")'` — `true` means you are on an affected build.
+
 ```bash
 # Recommended — through the anet CLI
 npm install -g @sleep2agi/agent-network
@@ -38,13 +55,16 @@ Once running:
 
 ## Pairs with
 
-| Package | Version |
+| Package | |
 |---|---|
-| [`@sleep2agi/agent-network`](https://www.npmjs.com/package/@sleep2agi/agent-network) | 2.1.7 |
-| [`@sleep2agi/agent-network-dashboard`](https://www.npmjs.com/package/@sleep2agi/agent-network-dashboard) | 0.4.2 |
-| [`@sleep2agi/agent-node`](https://www.npmjs.com/package/@sleep2agi/agent-node) | 2.3.0 |
+| [`@sleep2agi/agent-network`](https://www.npmjs.com/package/@sleep2agi/agent-network) | CLI |
+| [`@sleep2agi/agent-network-dashboard`](https://www.npmjs.com/package/@sleep2agi/agent-network-dashboard) | Web UI |
+| [`@sleep2agi/agent-node`](https://www.npmjs.com/package/@sleep2agi/agent-node) | Agent runtime host |
+
+Install the matching versions with `npm install -g <pkg>` — the `latest` dist-tag on npm is
+authoritative. Pinning versions here goes stale on every release and nobody comes back to fix it.
 
-## MCP tools (17)
+## MCP tools
 
 ### Agent-side
 | Tool | Description |
@@ -71,6 +91,8 @@ Once running:
 | `list_tasks` | Task list, filterable by `network_id` |
 | `get_completions` | Completion history |
 
+> The table above lists the 17 **collaboration-core** tools. Node lifecycle / provider ops tools ship on the same MCP surface — the authoritative full list is [docs-site/docs/api/mcp-tools.md](../docs-site/docs/api/mcp-tools.md). Don't read the count above as "17 tools total".
+
 ## REST API
 
 The server exposes ~33 endpoints across health, auth, networks, and observability surfaces. The endpoints in use today by the verified flow are:
@@ -96,7 +118,7 @@ Network-management endpoints (`/api/networks…`) are present and used by the cu
 
 Auth: `Authorization: Bearer <token>` header, or `?token=<token>` query.
 
-## SQLite schema (13 tables)
+## SQLite schema
 
 Auto-created on first run.
 
@@ -128,9 +150,11 @@ delivered/acked/running → reassign → delivered (new agent)
 
 ## PostgreSQL (community extension point — not on the maintained roadmap)
 
+> **PostgreSQL support is still in development and does not work yet** (PostgreSQL 支持尚在开发中，目前不可用). With `DATABASE_URL=postgres://…` the hub builds its schema, but `startHub()` refuses to run on PostgreSQL unless you also set `COMMHUB_PG_EXPERIMENTAL=1` (experimental, for testing only: it switches on the scheduler, task runtime evidence and side-thread commands on PostgreSQL before their PostgreSQL tests exist; RFC-039 S4 removes the flag). Progress: [RFC-039](https://github.com/sleep2agi/agent-network/blob/main/docs/rfcs/RFC-039-hub-postgresql-backend.md).
+
 > v0.8+ product direction is **SQLite only** (see [docs/v3-postgresql-design.md banner](https://github.com/sleep2agi/agent-network/blob/main/docs/v3-postgresql-design.md)). The PostgreSQL adapter interface is preserved as a community extension point — no E2E coverage on the current stable line; **not recommended for mainline production**.
 
-Set `DATABASE_URL` to switch to PostgreSQL — the SQL layer auto-translates SQLite-isms (datetime, parameter placeholders) so application code is unchanged. Requires `bun add pg`.
+Design intent (not working today): setting `DATABASE_URL` switches to PostgreSQL, and the SQL layer translates SQLite-isms (datetime, parameter placeholders). Requires `bun add pg`.
 
 ```bash
 DATABASE_URL=postgres://user:pass@host:5432/commhub bunx @sleep2agi/commhub-server
@@ -144,7 +168,103 @@ DATABASE_URL=postgres://user:pass@host:5432/commhub bunx @sleep2agi/commhub-serv
 | `HOST` | `0.0.0.0` in the server package, `127.0.0.1` when launched by `anet hub start` | listen address |
 | `COMMHUB_AUTH_TOKEN` | (none) | Bearer token gate (legacy) |
 | `COMMHUB_DB` | `~/.commhub/commhub.db` | SQLite path |
-| `DATABASE_URL` | (none) | switches to PostgreSQL when set (unverified) |
+| `DATABASE_URL` | (none) | switches to PostgreSQL when set — **does not work yet**, see above |
+
+## Running the unit tests
+
+### 先说该走哪条路:Docker
+
+仓库规约是测试在 Docker 里跑(`CLAUDE.md`「所有测试在 Docker 里跑:不碰本地
+环境,不改生产」)。`server/src` 的测试在 `tests/` 下已经有 **24 个**按主题分片的
+套件覆盖(实测:遍历 main 上 204 个套件目录,run.sh 里跑 `server/src/*.test.ts`
+的有 24 个),每个都在容器内自带 `COMMHUB_DB`。跑其中任意一个都是这个形状:
+
+```bash
+# 从仓根跑
+docker build --build-arg SOURCE_COMMIT="$(git rev-parse HEAD)" \
+  -t anet-test624 -f tests/test624-task-cursor-pagination/Dockerfile .
+docker run --rm anet-test624
+```
+
+（实跑过:退出码 0,`6 pass / 0 fail`,`RESULT: PASS`。换成 `tests/` 下别的
+`test*-*/Dockerfile` 同理,但 **build-arg 的名字要照抄那个 Dockerfile** ——
+main 上 66 处写的是 `SOURCE_COMMIT`,另有若干写成 `TEST<编号>_SOURCE_COMMIT`
+(如 `TEST686_SOURCE_COMMIT`、`TEST765_SOURCE_COMMIT`)。传错名字不会报错,
+只会让套件收到 `unknown` 然后按它自己的规则红或绿 —— 这不是你想要的那种绿。）
+
+> ⚠️ **目前没有一个套件跑「`server/src` 下的全部」单测。** 上面那些是按主题
+> 分片的;聚合门在 #798 里,尚未合入 main。所以「所有分片套件都绿」**不等于**
+> 69 个单测文件都跑过 —— 在 #798 合入之前,不要把前者当成后者。
+
+### 直接在宿主上跑时的两条契约
+
+下面这两条是上面那些套件在容器内**已经替你满足**的东西。你只有在本地迭代
+单个文件时才需要自己处理它们 —— 而那种跑法不构成任何门禁证据。
+
+
+1. **`COMMHUB_DB` must be set.** It is not optional — `~/.commhub/commhub.db` is a
+   *live* database on any machine that has ever run a hub. This one is enforced:
+   with `NODE_ENV=test` (which `bun test` sets) and no `COMMHUB_DB`, the adapter
+   refuses with `REFUSING to open the default SQLite database`.
+
+2. **Each test *file* needs its own database.** This is *not* enforced — a single
+   shared `COMMHUB_DB` passes the guard above and then fails a handful of tests
+   for reasons that look like product bugs but are not. `scripts/qa.sh` encodes
+   the real contract:
+
+   ```bash
+   # 从仓根跑(见下),每个文件一个全新的库
+   f=server/src/auth-validate.test.ts
+   db=/tmp/anet-$(basename "$f" .test.ts).db
+   rm -f "$db"                       # 复用上一次的库同样会破坏隔离
+   COMMHUB_DB="$db" bun test "$f"
+   ```
+
+   整套跑法:
+
+   ```bash
+   rc=0
+   # 用 find 而不是 `server/src/*.test.ts` —— glob 不进子目录,会漏掉
+   # server/src/shared/ 下的 3 个(实测:深度 1 是 66 个,递归是 69 个)。
+   # scripts/qa.sh 与 test798 用的就是 find,这里保持一致。
+   while IFS= read -r f; do
+     # 用完整路径派生库名,不用 basename:加入子目录之后,
+     # 两个不同目录下的同名文件会派生出同一个库(原来只扫单层时不可能)。
+     db=/tmp/anet-$(printf '%s' "${f%.test.ts}" | tr '/.' '--').db
+     rm -f "$db" "$db-wal" "$db-shm"
+     COMMHUB_DB="$db" bun test "$f" || { echo "FAILED: $f"; rc=1; }
+   done < <(find server/src -type f -name '*.test.ts' | sort)
+   [ "$rc" -eq 0 ]
+   ```
+
+   ⚠️ 最后那行 `[ "$rc" -eq 0 ]` 不是装饰,是这段的**门**。写成
+   `bun test "$f" || echo "FAILED: $f"` 会让循环打印一行然后继续,
+   整段的退出码恒为 0 —— **测试全红,脚本报绿**。用 `[ ... ]` 而不是
+   `exit "$rc"`,是为了这段直接粘进终端时不会把你的 shell 关掉;
+   存成脚本跑时,它是最后一条命令,脚本退出码就等于它。
+
+   ⚠️ 别把 `$name` 之类的占位符原样抄进命令行 —— 未定义的变量会展开成空串,
+   于是每个文件都写进**同一个** `/tmp/…-.db`,正好是这一节要避免的事。
+
+   Symptom if you ignore it: `bun test src/` under one database turns
+   `admin-networks-http` and `scheduled-tasks-http` red. Both are **global-count
+   assertions that are correct under the contract**:
+
+   ```ts
+   // admin-networks-http.test.ts — the admin sees EXACTLY this file's two networks
+   expect(new Set(rows.map((row) => row.network_id)))
+     .toEqual(new Set([adminNetworkId, memberNetworkId]));
+
+   // scheduled-tasks-http.test.ts — EXACTLY one due occurrence was processed
+   expect(runDueScheduledTasks().processed).toBe(1);
+   ```
+
+   Share a database and other files' networks and due schedules join the count.
+   Nothing is broken; the run violated the contract.
+
+   `scripts/qa.sh` 的 L0 目前只点名跑 5 个 server 测试(白名单),不是全量;
+   把 `server/src` 全域逐文件跑起来的那道 CI 门还在评审中(`#798`),
+   未进 `main` —— 所以本节描述的是**契约**,不是「已经有东西在替你执行它」。
 
 ## Auth modes
 
@@ -156,7 +276,7 @@ DATABASE_URL=postgres://user:pass@host:5432/commhub bunx @sleep2agi/commhub-serv
 ## Not verified
 
 - `/api/license*` — experimental legacy trial/pro-license endpoints.
-- PostgreSQL backend — translation layer exists, no E2E run.
+- PostgreSQL backend — in development, does not work yet (the hub refuses to start on it without the experimental opt-in; RFC-039).
 - Telegram / WeChat / Feishu channel endpoints — channel code exists, but only Telegram-oriented agent-node paths are actively exercised.
 
 ## License

package/bin/commhub.ts

@@ -12,19 +12,56 @@
 
 const args = process.argv.slice(2);
 
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === "--port" || args[i] === "-p") process.env.PORT = args[++i];
-  if (args[i] === "--host") process.env.HOST = args[++i];
-  if (args[i] === "--token" || args[i] === "-t") process.env.COMMHUB_AUTH_TOKEN = args[++i];
-  if (args[i] === "--db") process.env.COMMHUB_DB = args[++i];
-  if (args[i] === "--cors") process.env.COMMHUB_CORS_ORIGINS = args[++i];
-  if (args[i] === "--dev-open") process.env.COMMHUB_DEV_OPEN = "1";
-  if (args[i] === "--help" || args[i] === "-h") {
+// RFC-039 S5 — offline SQLite → PostgreSQL copy. Handled before any server
+// option parsing: it never starts a Hub and never opens the default database.
+if (args[0] === "migrate-to-pg") {
+  const flag = (name: string) => args.includes(name);
+  const value = (name: string) => { const i = args.indexOf(name); return i > 0 ? args[i + 1] : undefined; };
+  const MIGRATE_VALUE_FLAGS = new Set(["--from", "--to"]);
+  const MIGRATE_FLAGS = new Set(["--dry-run", "--i-know-this-is-a-copy", "--help", "-h"]);
+  for (let i = 1; i < args.length; i++) {
+    if (MIGRATE_VALUE_FLAGS.has(args[i])) { i++; continue; }
+    if (!MIGRATE_FLAGS.has(args[i])) {
+      console.error(`commhub-server migrate-to-pg: unknown argument ${args[i]}\nRun "commhub-server migrate-to-pg --help" for usage.`);
+      process.exit(2);
+    }
+  }
+  if (flag("--help") || flag("-h") || !value("--from") || !value("--to")) {
     console.log(`
+Usage:
+  commhub-server migrate-to-pg --from <sqlite file> --to <postgres url> [--dry-run] [--i-know-this-is-a-copy]
+
+Copies a stopped Hub's SQLite database into an EMPTY PostgreSQL database, in one
+transaction, verifying per-table row counts and content hashes before COMMIT.
+Experimental (RFC-039); available from commhub-server 0.9.0-preview.73.
+Files under the uploads directory are not copied.
+
+  --dry-run                 do everything, then roll back and leave the target empty
+  --i-know-this-is-a-copy   allow a source under ~/.commhub (refused by default)
+`);
+    process.exit(flag("--help") || flag("-h") ? 0 : 2);
+  }
+  const { migrateSqliteToPg, MigrateRefused } = await import("../src/migrate-sqlite-to-pg.ts");
+  try {
+    await migrateSqliteToPg({
+      from: value("--from")!,
+      to: value("--to")!,
+      dryRun: flag("--dry-run"),
+      allowCommhubCopy: flag("--i-know-this-is-a-copy"),
+    });
+    process.exit(0);
+  } catch (error) {
+    console.error(error instanceof MigrateRefused ? error.message : `[migrate-to-pg] FAILED, rolled back: ${(error as Error)?.message ?? error}`);
+    process.exit(error instanceof MigrateRefused ? 2 : 1);
+  }
+}
+
+const HELP = `
 CommHub MCP Server — AI Agent 通信中枢
 
 Usage:
   commhub-server [options]
+  commhub-server migrate-to-pg --help    Copy a stopped Hub's SQLite database into PostgreSQL (experimental)
 
 Options:
   --port, -p <port>       Port to listen on (default: 9200, env: PORT)
@@ -34,6 +71,7 @@ Options:
   --cors <origins>        CORS origins, comma-separated (env: COMMHUB_CORS_ORIGINS)
   --dev-open              Explicit unauthenticated local development mode
   --help, -h              Show this help
+  --version, -v           Print the version and exit
 
 Environment Variables:
   PORT                    Server port (default: 9200)
@@ -49,10 +87,60 @@ Examples:
   commhub-server --port 9200 --token my-secret-token
   commhub-server --port 9200 --dev-open
   PORT=9200 COMMHUB_AUTH_TOKEN=secret commhub-server
-`);
+`;
+
+// Anything this bin does not recognise is a usage error: exit 2 and never
+// start a Hub. Before this, unknown words and flags were ignored and a Hub
+// started on the defaults — `commhub-server <some-subcommand>` on a version
+// without that subcommand opened ~/.commhub/commhub.db on :9200.
+function usageError(message: string): never {
+  console.error(`commhub-server: ${message}\nRun "commhub-server --help" for usage.`);
+  process.exit(2);
+}
+
+const VALUE_FLAGS: Record<string, string> = {
+  "--port": "PORT", "-p": "PORT",
+  "--host": "HOST",
+  "--token": "COMMHUB_AUTH_TOKEN", "-t": "COMMHUB_AUTH_TOKEN",
+  "--db": "COMMHUB_DB",
+  "--cors": "COMMHUB_CORS_ORIGINS",
+};
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (Object.hasOwn(VALUE_FLAGS, arg)) {
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith("--")) usageError(`${arg} needs a value`);
+    process.env[VALUE_FLAGS[arg]] = value;
+    i++;
+  } else if (arg === "--dev-open") {
+    process.env.COMMHUB_DEV_OPEN = "1";
+  } else if (arg === "--help" || arg === "-h") {
+    console.log(HELP);
     process.exit(0);
+  } else if (arg === "--version" || arg === "-v") {
+    // Set by bin/anet-bin.ts before this file is imported. A compiled binary
+    // has no package.json beside import.meta.url (/$bunfs). npm leaves it unset.
+    const embedded = process.env.ANET_EMBEDDED_COMMHUB_VERSION?.trim() ?? "";
+    if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(embedded)) {
+      console.log(embedded);
+      process.exit(0);
+    }
+    const pkg = (await import("../package.json", { with: { type: "json" } })).default as { version: string };
+    console.log(pkg.version);
+    process.exit(0);
+  } else {
+    usageError(arg.startsWith("-") ? `unknown option ${arg}` : `unknown command ${arg}`);
   }
 }
 
-// Load the server
-import("../src/index.js");
+// Opt into the default production DB path before loading the server graph.
+// Ordinary imports / bun -e probes do not receive this capability.
+process.env.COMMHUB_SERVER = "1";
+
+// Load the server module (side-effect-free since the #438 corrective:
+// importing binds nothing) and start the hub EXPLICITLY. Never rely on
+// import side effects or import.meta.main here — this bin is a dynamic
+// importer, where import.meta.main is false inside the module.
+const { startHub } = await import("../src/server.js");
+startHub();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.13",
-  "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
+  "version": "0.9.0-preview.131",
+  "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",
   "bin": {
@@ -12,9 +12,9 @@
     "bin"
   ],
   "scripts": {
-    "start": "bun run src/index.ts",
-    "dev": "bun --watch run src/index.ts",
-    "test": "COMMHUB_DB=/tmp/test-commhub-$$.db bun test src/"
+    "start": "COMMHUB_SERVER=1 bun run src/index.ts",
+    "dev": "COMMHUB_SERVER=1 bun --watch run src/index.ts",
+    "test": "bun run scripts/test-aggregate.ts"
   },
   "keywords": [
     "commhub",
@@ -46,9 +46,9 @@
     "bun": ">=1.2.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "1.32.0",
     "bun-types": "^1.3.13",
     "hono": "^4.12.25",
-    "zod": "^4.4.3"
+    "zod": "4.6.5"
   }
 }

package/src/ack-create-request-transport.test.ts

@@ -0,0 +1,182 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+
+const NET = "net_ack_transport";
+const DAEMON_NODE_ID = "node_ack_transport_daemon";
+const DAEMON_ALIAS = "ack-transport-daemon";
+const DAEMON_USER = "u_ack_transport_owner";
+const DAEMON_TOKEN_ID = "tok_ack_transport_daemon";
+
+function cleanup() {
+  try { db.run("DELETE FROM audit_log WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM node_create_requests WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM nodes WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [DAEMON_USER]); } catch {}
+}
+
+function seedWorld() {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [DAEMON_USER, DAEMON_USER],
+  );
+  db.run(
+    `INSERT INTO networks (network_id, network_name, owner_id, created_at)
+     VALUES (?1, ?2, ?3, datetime('now'))`,
+    [NET, NET, DAEMON_USER],
+  );
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at)
+     VALUES (?1, ?2, 'owner', datetime('now'))`,
+    [DAEMON_USER, NET],
+  );
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at)
+     VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [DAEMON_NODE_ID, DAEMON_ALIAS, DAEMON_ALIAS, NET],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+     VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [DAEMON_TOKEN_ID, DAEMON_USER, NET, `node:${DAEMON_ALIAS}`, "hash_ack_transport_daemon"],
+  );
+}
+
+function seedRequest(requestId: string) {
+  db.run(
+    `INSERT INTO node_create_requests
+       (request_id, daemon_node_id, child_name, network_id, runtime, model, flags_json, env_keys, status, created_at, created_by_token)
+     VALUES (?1, ?2, ?3, ?4, 'codex-sdk', 'x', '{}', '[]', 'delivered', ?5, ?6)`,
+    [requestId, DAEMON_NODE_ID, `child_${requestId}`, NET, Date.now(), DAEMON_TOKEN_ID],
+  );
+}
+
+async function connectClient() {
+  const server = new McpServer({ name: "ack-transport-test", version: "1" });
+  registerTools(
+    server,
+    undefined,
+    NET,
+    DAEMON_USER,
+    DAEMON_ALIAS,
+    true,
+    DAEMON_TOKEN_ID,
+  );
+  const client = new Client({ name: "ack-transport-client", version: "1" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+  return { client, server };
+}
+
+type ToolResult = { content: Array<{ type: string; text?: string }>; isError?: boolean };
+
+function responseJson(result: ToolResult) {
+  const first = result.content[0];
+  if (!first || first.type !== "text" || typeof first.text !== "string") throw new Error("missing text tool result");
+  return JSON.parse(first.text) as { ok?: boolean; status?: string };
+}
+
+function expectTransportValidationError(result: ToolResult) {
+  expect(result.isError).toBe(true);
+  const first = result.content[0];
+  expect(first?.type).toBe("text");
+  expect(first?.text).toMatch(/Input validation error.*ack_create_request/i);
+}
+
+beforeEach(() => {
+  cleanup();
+  seedWorld();
+});
+afterAll(cleanup);
+
+describe("#344 ack_create_request real in-process MCP transport", () => {
+  test("explicit launch proof survives transport while malformed booleans are rejected", async () => {
+    const requestId = 'cr_transport_verified';
+    seedRequest(requestId);
+    const { client, server } = await connectClient();
+    try {
+      const read = () => db.get<{ launch_verified_at: number | null }>(
+        'SELECT launch_verified_at FROM node_create_requests WHERE request_id=?1', requestId);
+      const bad = await client.callTool({ name: 'ack_create_request', arguments: {
+        request_id: requestId, status: 'started', child_pid: 7777, launch_verified: 'true',
+      } });
+      expectTransportValidationError(bad);
+      expect(read()?.launch_verified_at).toBeNull();
+      const good = await client.callTool({ name: 'ack_create_request', arguments: {
+        request_id: requestId, status: 'started', child_pid: 7777, launch_verified: true,
+      } });
+      expect(responseJson(good).ok).toBe(true);
+      expect(read()?.launch_verified_at).toBeGreaterThan(0);
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+
+  test("accepts runtime_capability_check_failed plus string runtime through the SDK zod gate", async () => {
+    const requestId = "cr_transport_accept";
+    seedRequest(requestId);
+    const { client, server } = await connectClient();
+    try {
+      const result = await client.callTool({
+        name: "ack_create_request",
+        arguments: {
+          request_id: requestId,
+          status: "runtime_capability_check_failed",
+          error: "child died within 5000ms post-spawn",
+          runtime: "codex-sdk",
+        },
+      });
+      expect(responseJson(result)).toMatchObject({ ok: true, status: "runtime_capability_check_failed" });
+      expect(db.get<{ status: string }>("SELECT status FROM node_create_requests WHERE request_id = ?1", requestId)?.status)
+        .toBe("runtime_capability_check_failed");
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+
+  test("rejects unknown status at the transport gate before the handler mutates the row", async () => {
+    const requestId = "cr_transport_bad_status";
+    seedRequest(requestId);
+    const { client, server } = await connectClient();
+    try {
+      const result = await client.callTool({
+        name: "ack_create_request",
+        arguments: { request_id: requestId, status: "capability_failed_typo", runtime: "codex-sdk" },
+      });
+      expectTransportValidationError(result);
+      expect(db.get<{ status: string }>("SELECT status FROM node_create_requests WHERE request_id = ?1", requestId)?.status)
+        .toBe("delivered");
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+
+  test("rejects non-string runtime at the transport gate before the handler mutates the row", async () => {
+    const requestId = "cr_transport_bad_runtime";
+    seedRequest(requestId);
+    const { client, server } = await connectClient();
+    try {
+      const result = await client.callTool({
+        name: "ack_create_request",
+        arguments: { request_id: requestId, status: "runtime_capability_check_failed", runtime: 42 },
+      });
+      expectTransportValidationError(result);
+      expect(db.get<{ status: string }>("SELECT status FROM node_create_requests WHERE request_id = ?1", requestId)?.status)
+        .toBe("delivered");
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+});

package/src/ack-create-request.test.ts

@@ -13,11 +13,11 @@ import { registerTools } from "./tools.js";
 // `daemon_capability_lied` audit was written when in fact the action wasn't
 // in the audit enum and no insert ran.
 //
-// This handler-driven suite drives the registered MCP tool through
-// registerTools() so a daemon's exact ack shape (status + runtime field)
-// flows through the real zod schema + handler branch + audit insert. It
-// would have caught the lane-recurring "single component passes but cross-
-// component path stays broken" failure mode immediately.
+// This handler-driven suite captures and invokes the registered callback
+// directly. It validates handler branches and DB effects, but deliberately
+// does NOT claim to exercise the MCP SDK's zod transport gate. The
+// complementary in-process transport coverage lives in
+// ack-create-request-transport.test.ts (#344).
 
 const NET = "net_ack_t";
 const DAEMON_NODE_ID = "node_ack_daemon";
@@ -138,8 +138,8 @@ async function callAck(handler: ToolHandler, args: any): Promise<AckReply> {
 }
 
 function readRequest(request_id: string) {
-  return db.get<{ status: string; error: string | null; acked_at: number | null }>(
-    `SELECT status, error, acked_at FROM node_create_requests WHERE request_id = ?1`,
+  return db.get<{ status: string; error: string | null; acked_at: number | null; launch_verified_at: number | null }>(
+    `SELECT status, error, acked_at, launch_verified_at FROM node_create_requests WHERE request_id = ?1`,
     request_id,
   );
 }
@@ -297,6 +297,29 @@ describe("ack_create_request HANDLER — B2 audit_log daemon_capability_lied", (
 });
 
 describe("ack_create_request HANDLER — pre-existing happy-path stays green (regression)", () => {
+  for (const status of ['failed', 'rejected', 'runtime_capability_check_failed']) {
+    test(`late ${status} after registration cannot leave succeeded with a revoked token`, async () => {
+      seedDaemonWorld();
+      const request_id = `cr_late_${status}`;
+      const child_token_id = `tok_late_${status}`;
+      seedCreateRequest({ request_id, child_token_id, status: 'succeeded' });
+      const handler = buildAckHandler();
+      await callAck(handler, { request_id, status: 'started', child_pid: 7777, launch_verified: true });
+      expect(readRequest(request_id)?.launch_verified_at).toBeGreaterThan(0);
+      const reply = await callAck(handler, { request_id, status, error: 'post-register launch verdict' });
+      expect(reply).toMatchObject({ ok: true, status });
+      expect(readRequest(request_id)?.status).toBe(status);
+      expect(readRequest(request_id)?.error).toBe('post-register launch verdict');
+      expect(readRequest(request_id)?.acked_at).toBeGreaterThan(0);
+      expect(readToken(child_token_id)?.revoked_at).not.toBeNull();
+      // Delayed success must not resurrect either the request or its token.
+      await callAck(handler, { request_id, status: 'started', child_pid: 7777, launch_verified: true });
+      expect(readRequest(request_id)?.status).toBe(status);
+      expect(readRequest(request_id)?.launch_verified_at).toBeNull();
+      expect(readToken(child_token_id)?.revoked_at).not.toBeNull();
+    });
+  }
+
   test("status='started' still flips acked_at without terminal teardown", async () => {
     seedDaemonWorld();
     const reqId = "cr_ack_started_regression";
@@ -310,10 +333,30 @@ describe("ack_create_request HANDLER — pre-existing happy-path stays green (re
     // 'started' doesn't flip to terminal; status stays 'delivered'.
     expect(row?.status).toBe("delivered");
     expect(row?.acked_at).toBeGreaterThan(0);
+    expect(row?.launch_verified_at).toBeNull();
     // child ntok is NOT revoked on 'started'.
     expect(readToken(childTok)?.revoked_at).toBeNull();
   });
 
+  for (const status of ['pending', 'delivered', 'succeeded'] as const) {
+    test(`verified launch persists independently of registration: ${status}`, async () => {
+      seedDaemonWorld();
+      const request_id = `cr_verified_${status}`;
+      seedCreateRequest({ request_id, child_token_id: `tok_verified_${status}`, status });
+      const handler = buildAckHandler();
+      expect(readRequest(request_id)?.launch_verified_at).toBeNull();
+      const bad = await callAck(handler, { request_id, status: 'started', launch_verified: true });
+      expect(bad.ok).toBe(false);
+      expect(readRequest(request_id)?.launch_verified_at).toBeNull();
+      await callAck(handler, { request_id, status: 'started', child_pid: 7777, launch_verified: true });
+      const first = readRequest(request_id)!;
+      expect(first.status).toBe(status);
+      expect(first.launch_verified_at).toBeGreaterThan(0);
+      await callAck(handler, { request_id, status: 'started', child_pid: 7777, launch_verified: true });
+      expect(readRequest(request_id)?.launch_verified_at).toBe(first.launch_verified_at);
+    });
+  }
+
   test("status='failed' still revokes child + flips to failed (no audit_log daemon_capability_lied)", async () => {
     seedDaemonWorld();
     const reqId = "cr_ack_failed_regression";