@sleep2agi/commhub-server 0.9.0-preview.118 → 0.9.0-preview.119

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.118",
+  "version": "0.9.0-preview.119",
   "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",

package/src/codex-fork-contract.ts

@@ -0,0 +1,23 @@
+import { z } from "zod/v4";
+
+export const forkRecoveryRequestSchema = z.object({
+  kind: z.literal("fork_on_missing_ordinal"), confirmed: z.literal(true),
+}).strict();
+const threadId = z.string().length(36).regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+export const forkRecoveryResultSchema = z.discriminatedUnion("state", [
+  z.object({ state: z.literal("forked"), old_thread_id: threadId, new_thread_id: threadId }).strict(),
+  z.object({ state: z.literal("not_observed") }).strict(),
+  z.object({ state: z.literal("unknown"), reason: z.enum([
+    "invalid_request_id", "history_unreadable", "history_invalid", "request_ambiguous", "mapping_invalid",
+    "result_not_reported", "result_invalid",
+  ]) }).strict(),
+]).refine(r => r.state !== "forked" || r.old_thread_id !== r.new_thread_id);
+
+// Read paths re-validate stored data, not just the write-time MCP schema.
+export function publicForkResult(raw: unknown) {
+  try {
+    const parsed = forkRecoveryResultSchema.safeParse(typeof raw === "string" ? JSON.parse(raw) : raw);
+    if (parsed.success) return parsed.data;
+  } catch { /* corrupted/legacy storage must not expose arbitrary fields */ }
+  return { state: "unknown", reason: raw == null ? "result_not_reported" : "result_invalid" } as const;
+}

package/src/codex-fork-migration.test.ts

@@ -0,0 +1,38 @@
+import { expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+test("legacy start table upgrades twice without changing ordinary rows or losing fork receipts", () => {
+  const root = mkdtempSync(join(tmpdir(), "fork-migration-"));
+  const path = join(root, "legacy.db");
+  try {
+    let db = new Database(path);
+    db.exec(`CREATE TABLE node_start_requests (
+      request_id TEXT PRIMARY KEY, network_id TEXT NOT NULL, daemon_node_id TEXT NOT NULL,
+      child_node_id TEXT NOT NULL, child_alias TEXT NOT NULL, created_by_token TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending', error TEXT, child_pid INTEGER,
+      created_at INTEGER NOT NULL, delivered_at INTEGER, acked_at INTEGER);
+      INSERT INTO node_start_requests(request_id,network_id,daemon_node_id,child_node_id,child_alias,created_by_token,status,created_at)
+        VALUES('str_legacy','net_fixture','node_daemon','node_child','fixture','fixture','started',1);`);
+    db.close();
+    const migrate = () => execFileSync(process.execPath, ["-e",
+      `await import(${JSON.stringify(fileURLToPath(new URL("./db.ts", import.meta.url)))}); process.exit(0);`],
+      { env: { ...process.env, COMMHUB_DB: path }, timeout: 15_000, stdio: "pipe" });
+    migrate();
+    db = new Database(path);
+    expect(db.query("SELECT status,fork_recovery_json,fork_result_json FROM node_start_requests WHERE request_id='str_legacy'").get())
+      .toEqual({ status: "started", fork_recovery_json: null, fork_result_json: null });
+    const receipt = JSON.stringify({ state: "not_observed" });
+    db.query("UPDATE node_start_requests SET fork_result_json=? WHERE request_id='str_legacy'").run(receipt);
+    db.close();
+    migrate();
+    db = new Database(path);
+    expect(db.query("SELECT fork_result_json FROM node_start_requests WHERE request_id='str_legacy'").get())
+      .toEqual({ fork_result_json: receipt });
+    db.close();
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});

package/src/db.ts

@@ -504,6 +504,12 @@ db.exec(`
 `);
 db.exec(`CREATE INDEX IF NOT EXISTS idx_start_req_daemon ON node_start_requests(daemon_node_id, status)`);
 db.exec(`CREATE INDEX IF NOT EXISTS idx_start_req_child ON node_start_requests(child_node_id)`);
+// Additive: old rows remain ordinary starts (NULL). Keep the request and the
+// observed side effect separate from launcher status, including startup failure.
+for (const column of ["fork_recovery_json", "fork_result_json"]) {
+  try { db.exec(`ALTER TABLE node_start_requests ADD COLUMN ${column} TEXT`); }
+  catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
+}
 try {
   db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS uniq_start_req_child_inflight
              ON node_start_requests(child_node_id)

package/src/node-lifecycle-read-http.test.ts

@@ -140,6 +140,36 @@ test("cross-network request and node guesses do not disclose data", async () =>
     expect((await get(query(kind, `request_id=${id}&network_id=${a.network_id}`), b.token)).status).toBe(403);
   }
 });
+test("fork receipt uses the same authenticated node visibility and redacts corrupt storage", async () => {
+  const receipt = { state: "forked", old_thread_id: "01a11846-d796-72f1-af68-8d9215a65dc8", new_thread_id: "01a11900-0000-7000-8000-000000000001" };
+  const path = query("start", "request_id=start_read_failed");
+  try {
+    db.run("UPDATE node_start_requests SET fork_recovery_json=?1,fork_result_json=?2 WHERE request_id='start_read_failed'",
+      [JSON.stringify({ kind: "fork_on_missing_ordinal", confirmed: true }), JSON.stringify(receipt)]);
+    expect((await get(path)).body.request.fork_recovery).toEqual({ requested: true, result: receipt });
+    expect((await get(path, b.token)).status).toBe(404);
+    expect((await get(path, limited.token)).status).toBe(404);
+    expect((await get(path, daemonToken)).status).toBe(403);
+    db.run("INSERT INTO network_member_agent_grants(network_id,user_id,node_id,can_message) VALUES(?1,?2,?3,0)", [a.network_id, limited.user.user_id, ids.active]);
+    expect((await get(path, limited.token)).body.request.fork_recovery.result).toEqual(receipt);
+    db.run("UPDATE node_start_requests SET fork_result_json=?1 WHERE request_id='start_read_failed'", [JSON.stringify({ ...receipt, snapshot: "/private/secret" })]);
+    const corrupted = await get(path, limited.token);
+    expect(corrupted.body.request.fork_recovery.result).toEqual({ state: "unknown", reason: "result_invalid" });
+    expect(JSON.stringify(corrupted)).not.toContain("/private");
+    // Corrupt confirmation cannot assert requested:true, but must not erase an
+    // independently valid recorded fork (nor make the request look ordinary).
+    for (const raw of ["broken /private/secret", "null", "{}", JSON.stringify({ kind: "fork_on_missing_ordinal", confirmed: false }),
+      JSON.stringify({ kind: "fork_on_missing_ordinal", confirmed: true, snapshot: "/private/secret" })]) {
+      db.run("UPDATE node_start_requests SET fork_recovery_json=?1,fork_result_json=?2 WHERE request_id='start_read_failed'", [raw, JSON.stringify(receipt)]);
+      const invalid = await get(path, limited.token);
+      expect(invalid.body.request.fork_recovery).toEqual({ requested: null, result: receipt });
+      expect(JSON.stringify(invalid)).not.toContain("/private");
+    }
+  } finally {
+    db.run("DELETE FROM network_member_agent_grants WHERE user_id=?1 AND node_id=?2", [limited.user.user_id, ids.active]);
+    db.run("UPDATE node_start_requests SET fork_recovery_json=NULL,fork_result_json=NULL WHERE request_id='start_read_failed'");
+  }
+});
 test("same-network restricted viewer without node grants cannot read requests", async () => {
   for (const kind of ["adopt", "start", "stop"]) {
     expect((await get(query(kind, `node_id=${ids.active}&network_id=${a.network_id}`), limited.token)).status).toBe(404);

package/src/node-lifecycle-read.ts

@@ -1,8 +1,11 @@
 import { db } from "./db.js";
 import { addAgentNetworkScope, type RestNetworkScope } from "./network-scope.js";
+import { forkRecoveryRequestSchema, publicForkResult } from "./codex-fork-contract.js";
 
 // Exact public codes only; daemon exception text must never reach node viewers.
 const publicLifecycleErrors = new Set([
+  "codex_fork_confirmation_invalid", "codex_fork_recovery_unsupported", "codex_fork_cli_unsupported",
+  "codex_fork_result_invalid", "codex_fork_outcome_unknown",
   "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed",
   "adopt_active_binding_required", "adopt_binding_unavailable",
   "adopt_binding_revoked_during_start", "adopt_explicit_private_socket_required",
@@ -91,9 +94,22 @@ export function lifecycleRequestResponse(url: URL, scope: RestNetworkScope): Res
   const params: any[] = [requestId ?? nodeId];
   const sql = scopeNodes(`SELECT r.request_id,r.${nodeColumn} AS node_id,r.network_id,r.daemon_node_id,
       r.status,r.error,r.created_at,${kind === "adopt" ? "r.updated_at" : "r.acked_at,r.delivered_at"}
+      ${kind === "start" ? ",r.fork_recovery_json,r.fork_result_json" : ""}
     FROM ${table} r JOIN nodes n ON n.node_id=r.${nodeColumn} AND n.network_id=r.network_id
     WHERE r.${requestId ? "request_id" : nodeColumn}=?1${kind === "stop" ? " AND r.action='stop'" : ""}`, params, scope);
   const row = db.get<Record<string, unknown>>(sql + " ORDER BY r.created_at DESC,r.request_id DESC LIMIT 1", ...params);
   if (!row && requestId) return fail("request_not_found", 404);
-  return Response.json({ ok: true, request: row ? { kind, ...row, error: publicLifecycleError(row.error) } : null });
+  if (!row) return Response.json({ ok: true, request: null });
+  const { fork_recovery_json, fork_result_json, ...publicRow } = row;
+  let confirmed: true | null = null;
+  if (kind === "start" && typeof fork_recovery_json === "string") {
+    try {
+      if (forkRecoveryRequestSchema.safeParse(JSON.parse(fork_recovery_json)).success) confirmed = true;
+    } catch { /* damaged confirmation is unknown; keep any independently valid fork evidence */ }
+  }
+  return Response.json({ ok: true, request: { kind, ...publicRow, error: publicLifecycleError(row.error),
+    ...(kind === "start" && fork_recovery_json != null ? { fork_recovery: {
+      requested: confirmed, result: publicForkResult(fork_result_json),
+    } } : {}),
+  } });
 }

package/src/start-node.test.ts

@@ -2,6 +2,15 @@ import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { db } from "./db.js";
 import { registerTools } from "./tools.js";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import { handleStartDoorbell } from "../../agent-node/src/runtime/start-daemon.js";
+import { lifecycleRequestResponse } from "./node-lifecycle-read.js";
+import { z } from "zod/v4";
+import { createCodexForkCapabilityMonitor } from "../../agent-node/src/runtime/codex-fork-capability.js";
+import { attachCodexForkCapability, buildConfigSnapshot } from "../../agent-node/src/runtime/config-apply.js";
 
 const NET = "net_start_node"; const USER = "u_start_node";
 const DAEMON = "node_start_daemon"; const DAEMON_ALIAS = "start-daemon";
@@ -25,18 +34,132 @@ beforeEach(() => { cleanup();
 afterAll(cleanup);
 
 function handlers(user: string | null, daemon = false) {
-  const s = new McpServer({ name: "t", version: "0" }) as any; const out: any = {};
-  const orig = s.tool.bind(s); s.tool = (n: string, d: string, schema: any, h: any) => { out[n] = h; return orig(n,d,schema,h); };
+  const s = new McpServer({ name: "t", version: "0" }) as any; const out: any = { $schemas: {} };
+  const orig = s.tool.bind(s); s.tool = (n: string, d: string, schema: any, h: any) => { out[n] = h; out.$schemas[n] = schema; return orig(n,d,schema,h); };
   registerTools(s, undefined, daemon ? NET : null, user, null, daemon, daemon ? "tok_start_daemon" : null); return out;
 }
 async function call(h: any, args: any) { return JSON.parse((await h(args)).content[0].text); }
 
+describe("confirmed fork request/result transport (#822)", () => {
+  const recovery = { kind: "fork_on_missing_ordinal", confirmed: true };
+  const forked = { state: "forked", old_thread_id: "01a11846-d796-72f1-af68-8d9215a65dc8",
+    new_thread_id: "01a11900-0000-7000-8000-000000000001" };
+  function enable() {
+    db.run(`UPDATE nodes SET config_snapshot=?1 WHERE node_id=?2`, [JSON.stringify({ role: "host_supervisor",
+      daemon_capabilities: { codex_fork_recovery: { protocol: 1, cli_supported: true } } }), DAEMON]);
+  }
+  function read(requestId: string, networkId = NET) {
+    return lifecycleRequestResponse(new URL(`http://hub/api/node-lifecycle-requests?kind=start&request_id=${requestId}`),
+      { networkId, networkIds: null });
+  }
+  test("real capability probe survives report schema/storage and opens only the recovery gate", async () => {
+    const root = mkdtempSync(join(tmpdir(), "fork-capability-report-"));
+    try {
+      const bin = join(root, "anet-fixture");
+      writeFileSync(bin, `#!${process.execPath}\nconsole.log('--fork-on-resume-failure --fork-recovery-request-id <str_id> --yes');`, { mode: 0o700 });
+      const monitor = createCodexForkCapabilityMonitor({ bin: () => bin, cwd: root });
+      await monitor.refresh();
+      const d = handlers(null, true), u = handlers(USER);
+      const snapshot = attachCodexForkCapability(buildConfigSnapshot({ role: "host_supervisor" }, false, 0), monitor.current());
+      const wire = z.object(d.$schemas.report_status).parse({ alias: DAEMON_ALIAS, node_id: DAEMON,
+        resume_id: "fork-capability-daemon", status: "idle", config_snapshot: snapshot });
+      await call(d.report_status, wire);
+      const stored = JSON.parse(db.get<any>(`SELECT config_snapshot FROM nodes WHERE node_id=?1`, DAEMON).config_snapshot);
+      expect(stored.daemon_capabilities.codex_fork_recovery).toEqual({ protocol: 1, cli_supported: true });
+      expect((await call(u.start_node, { node_id: CHILD, fork_recovery: recovery })).ok).toBe(true);
+      // Bad diagnostics are dropped, not a reason to reject the entire heartbeat.
+      for (const bad of [null, { protocol: 2, cli_supported: true }, { protocol: 1, cli_supported: "yes" }]) {
+        const parsed = d.$schemas.report_status.config_snapshot.parse({ ...snapshot,
+          daemon_capabilities: { can_create_nodes: true, codex_fork_recovery: bad } });
+        expect(parsed.daemon_capabilities.can_create_nodes).toBe(true);
+        expect(parsed.daemon_capabilities.codex_fork_recovery).toBeUndefined();
+      }
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+  test("requires explicit confirmation and affirmative capability before creating any request", async () => {
+    const u = handlers(USER);
+    for (const value of [null, {}, { ...recovery, confirmed: false }]) {
+      expect((await call(u.start_node, { node_id: CHILD, fork_recovery: value })).error).toBe("codex_fork_confirmation_invalid");
+    }
+    expect((await call(u.start_node, { node_id: CHILD, fork_recovery: recovery })).error).toBe("codex_fork_recovery_unsupported");
+    expect(db.all(`SELECT * FROM node_start_requests WHERE network_id=?1`, NET)).toEqual([]);
+    expect(db.get<any>(`SELECT lifecycle_state FROM nodes WHERE node_id=?1`, CHILD).lifecycle_state).toBe("stopped");
+    enable();
+    expect((await call(u.start_node, { node_id: CHILD, fork_recovery: recovery })).ok).toBe(true);
+  });
+  test("persists one confirmation and refuses old daemon pull without marking delivered", async () => {
+    enable(); const u = handlers(USER), d = handlers(null, true);
+    const { request_id } = await call(u.start_node, { node_id: CHILD, fork_recovery: recovery });
+    expect((await call(d.get_start_request, { request_id })).error).toBe("codex_fork_recovery_unsupported");
+    const row = db.get<any>(`SELECT * FROM node_start_requests WHERE request_id=?1`, request_id);
+    expect(row.status).toBe("pending"); expect(JSON.parse(row.fork_recovery_json)).toEqual(recovery);
+    expect(await call(d.get_start_request, { request_id, fork_recovery_capable: true })).toMatchObject({
+      ok: true, request_id, managed: "created", fork_recovery: recovery,
+    });
+  });
+  test.each([0, 7])("Hub → daemon → real CLI fixture exit %s → persisted fork and scoped read", async exitCode => {
+    enable(); const u = handlers(USER), d = handlers(null, true);
+    const { request_id } = await call(u.start_node, { node_id: CHILD, fork_recovery: recovery });
+    const root = mkdtempSync(join(tmpdir(), "fork-flow-"));
+    try {
+      const nodeDir = join(root, CHILD_ALIAS); mkdirSync(nodeDir);
+      writeFileSync(join(nodeDir, "config.json"), JSON.stringify({ node_id: CHILD, alias: CHILD_ALIAS,
+        runtime: "codex-app-server", codexCopresence: true }), { mode: 0o600 });
+      const bin = join(root, "anet-fixture");
+      // Real executable: validates argv, writes a CLI-shaped mapping and exits.
+      // It is not a real Codex/model recovery test.
+      writeFileSync(bin, `#!${process.execPath}\nimport {writeFileSync} from 'node:fs';
+        const args=process.argv.slice(2);
+        if(args.join(' ')==='node start --help') { console.log('--fork-on-resume-failure --fork-recovery-request-id <str_id> --yes'); process.exit(0); }
+        if(JSON.stringify(args)!==${JSON.stringify(JSON.stringify(["node", "start", CHILD_ALIAS, "--fork-on-resume-failure", "--yes", "--fork-recovery-request-id", request_id]))}) process.exit(99);
+        writeFileSync(${JSON.stringify(join(nodeDir, "codex-fork-recovery.json"))},JSON.stringify({forks:[{requestId:${JSON.stringify(request_id)},oldThreadId:${JSON.stringify(forked.old_thread_id)},newThreadId:${JSON.stringify(forked.new_thread_id)},snapshot:'/private/snapshot'}]}));
+        process.exit(${exitCode});`, { mode: 0o700 });
+      await handleStartDoorbell({ request_id }, { workDir: root, nodesRoot: root, anetBin: () => bin,
+        callCommHub: (tool, args) => call(d[tool], args), log() {}, warn() {} });
+      const row = db.get<any>(`SELECT * FROM node_start_requests WHERE request_id=?1`, request_id);
+      expect(row.status).toBe(exitCode === 0 ? "started" : "start_failed");
+      expect(JSON.parse(row.fork_result_json)).toEqual(forked);
+      const publicResult = await read(request_id).json();
+      expect(publicResult.request.fork_recovery).toEqual({ requested: true, result: forked });
+      expect(JSON.stringify(publicResult)).not.toContain("/private");
+      expect(JSON.stringify(publicResult)).not.toContain("fork_result_json");
+      expect(read(request_id, "net_unrelated").status).toBe(404);
+      // Terminal replay must not overwrite the original side effect receipt.
+      expect(await call(d.ack_start_request, { request_id, status: "start_failed", fork_recovery: { state: "not_observed" } }))
+        .toMatchObject({ ok: true, idempotent: true });
+      expect(JSON.parse(db.get<any>(`SELECT fork_result_json FROM node_start_requests WHERE request_id=?1`, request_id).fork_result_json)).toEqual(forked);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+  test("missing result is unknown, malformed result rejected; ordinary receipts keep old shape", async () => {
+    const u = handlers(USER), d = handlers(null, true);
+    const ordinary = await call(u.start_node, { node_id: CHILD });
+    expect((await call(d.ack_start_request, { request_id: ordinary.request_id, status: "start_failed", fork_recovery: forked })).error).toBe("codex_fork_result_invalid");
+    await call(d.ack_start_request, { request_id: ordinary.request_id, status: "start_failed" });
+    expect((await read(ordinary.request_id).json()).request).not.toHaveProperty("fork_recovery");
+    enable(); const { request_id } = await call(u.start_node, { node_id: CHILD, fork_recovery: recovery });
+    expect((await call(d.ack_start_request, { request_id, status: "start_failed", fork_recovery: { ...forked, snapshot: "/private" } })).error).toBe("codex_fork_result_invalid");
+    await call(d.ack_start_request, { request_id, status: "start_failed", error: "codex_fork_cli_unsupported" });
+    expect((await read(request_id).json()).request).toMatchObject({ error: "codex_fork_cli_unsupported",
+      fork_recovery: { result: { state: "unknown", reason: "result_not_reported" } } });
+    db.run(`UPDATE node_start_requests SET fork_result_json=?1 WHERE request_id=?2`, [JSON.stringify({ ...forked, snapshot: "/private" }), request_id]);
+    expect((await read(request_id).json()).request.fork_recovery.result).toEqual({ state: "unknown", reason: "result_invalid" });
+  });
+  test("stale recovery cannot be silently superseded by the ordinary start reaper", async () => {
+    enable(); const u = handlers(USER);
+    const { request_id } = await call(u.start_node, { node_id: CHILD, fork_recovery: recovery });
+    db.run(`UPDATE node_start_requests SET created_at=?1 WHERE request_id=?2`, [Date.now() - 70_000, request_id]);
+    expect(await call(u.start_node, { node_id: CHILD })).toMatchObject({ ok: false,
+      error: "codex_fork_outcome_unknown", existing_request_id: request_id });
+    expect(db.get<any>(`SELECT status FROM node_start_requests WHERE request_id=?1`, request_id).status).toBe("pending");
+  });
+});
+
 describe("start_node Hub -> daemon lifecycle", () => {
   test("dispatch, authenticated pull, ack transitions stopped -> starting -> active", async () => {
     const u = handlers(USER); const dispatch = await call(u.start_node, { child_node_id: CHILD, network_id: NET });
     expect(dispatch.ok).toBe(true); expect(dispatch.lifecycle_state).toBe("starting");
     const d = handlers(null, true); const pulled = await call(d.get_start_request, { request_id: dispatch.request_id });
-    expect(pulled).toMatchObject({ ok: true, child_node_id: CHILD, child_alias: CHILD_ALIAS });
+    expect(pulled).toMatchObject({ ok: true, child_node_id: CHILD, child_alias: CHILD_ALIAS, start_completion_capable: true });
     const ack = await call(d.ack_start_request, { request_id: dispatch.request_id, status: "started", child_pid: 4321 });
     expect(ack.ok).toBe(true);
     expect(db.get<any>(`SELECT lifecycle_state FROM nodes WHERE node_id=?1`, CHILD)?.lifecycle_state).toBe("active");
@@ -49,6 +172,38 @@ describe("start_node Hub -> daemon lifecycle", () => {
     db.run(`UPDATE nodes SET lifecycle_state='stopped' WHERE node_id=?1`, CHILD);
     expect((await call(u.start_node, { child_node_id: CHILD, daemon_node_id: "node_wrong", network_id: NET })).error).toBe("daemon_child_mismatch");
   });
+  test("launcher progress refreshes stale-start clock, never marks active, and failure stays stopped", async () => {
+    const u = handlers(USER), d = handlers(null, true);
+    const dispatch = await call(u.start_node, { child_node_id: CHILD, network_id: NET });
+    const request_id = dispatch.request_id;
+    await call(d.get_start_request, { request_id });
+    db.run(`UPDATE node_start_requests SET created_at=?1, delivered_at=?1 WHERE request_id=?2`, [Date.now() - 70_000, request_id]);
+    expect(await call(d.ack_start_request, { request_id, status: "starting" })).toEqual({ ok: true, status: "starting" });
+    expect(db.get<any>(`SELECT lifecycle_state FROM nodes WHERE node_id=?1`, CHILD)?.lifecycle_state).toBe("starting");
+    expect(db.get<any>(`SELECT status FROM node_start_requests WHERE request_id=?1`, request_id)?.status).toBe("delivered");
+    expect((await call(u.start_node, { child_node_id: CHILD, network_id: NET })).error).toBe("node_already_starting");
+    expect(await call(d.ack_start_request, { request_id, status: "start_failed", error: "codex_launcher_exit:1" })).toEqual({ ok: true, status: "start_failed" });
+    expect(db.get<any>(`SELECT lifecycle_state FROM nodes WHERE node_id=?1`, CHILD)?.lifecycle_state).toBe("stopped");
+    expect(db.all<any>(`SELECT action FROM audit_log WHERE target_id=?1`, request_id).map(r => r.action)).toEqual(["start_node_dispatched"]);
+    // A heartbeat already in flight cannot resurrect a terminal request.
+    expect(await call(d.ack_start_request, { request_id, status: "starting" })).toMatchObject({ status: "start_failed", idempotent: true });
+  });
+  test.each([0, 7])("dispatch → daemon → real launcher exit %s → Hub lifecycle", async (exitCode) => {
+    const root = mkdtempSync(join(tmpdir(), "start-flow-"));
+    try {
+      mkdirSync(join(root, CHILD_ALIAS));
+      writeFileSync(join(root, CHILD_ALIAS, "config.json"), JSON.stringify({ node_id: CHILD, alias: CHILD_ALIAS, codexCopresence: true }), { mode: 0o600 });
+      const u = handlers(USER), d = handlers(null, true);
+      const dispatch = await call(u.start_node, { child_node_id: CHILD, network_id: NET });
+      await handleStartDoorbell({ request_id: dispatch.request_id }, {
+        workDir: root, nodesRoot: root, anetBin: () => process.execPath,
+        spawnChild: ((_bin, _args, opts) => spawn(process.execPath, ["-e", `setTimeout(() => process.exit(${exitCode}), 25)`], opts)) as typeof spawn,
+        callCommHub: (tool, args) => call(d[tool], args), log: () => {}, warn: () => {},
+      });
+      expect(db.get<any>(`SELECT status FROM node_start_requests WHERE request_id=?1`, dispatch.request_id)?.status).toBe(exitCode === 0 ? "started" : "start_failed");
+      expect(db.get<any>(`SELECT lifecycle_state FROM nodes WHERE node_id=?1`, CHILD)?.lifecycle_state).toBe(exitCode === 0 ? "active" : "stopped");
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
 });
 
 // #1448 finding-2 — stale-starting reaper（对齐 update_node_config/restart_node 的 60s

package/src/tool-audience-http.test.ts

@@ -192,7 +192,12 @@ describe("bytes per role (#476 ceilings stay meaningful per role)", () => {
   // so any new node tool needs this; ceilings keep the same ~400–750 B margin.
   // Review follow-up: descriptions / schemas cut further → node 59 / 61,100 B, all 85 / 76,749 B (−507 B each),
   // leaving ≥ 700 B node margin even with #2488 (+116 B) merged.
-  const CEILINGS = { node: 62_000, user: 57_500, all: 78_000 } as const;
+  // Board #822 adds confirmed fork fields, not tools. Same-image main 102dd0f2 → candidate:
+  // all 87 / 77,646 B → 78,976 B (+1,330); node 61 / 61,986 B → 62,368 B (+382);
+  // user 58 / 56,950 B → 57,163 B (+213). start_node adds 213 B, report_status 169 B;
+  // hidden pull/ack schemas account for the remaining 948 B. Keep strict receipt validation
+  // and unchanged audiences; budget only this measured addition (~130/520 B node/all margin).
+  const CEILINGS = { node: 62_500, user: 57_500, all: 79_500 } as const;
   test("node / user / all", async () => {
     const node = await listTools(T.node_normal);
     const user = await listTools(T.owner);

package/src/tools.ts

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { requestAdopt, getAdopt, ackAdopt, unadopt, resolveManagedDaemon, activeBinding, createdDaemon } from "./node-daemon-bindings.js";
 import { runtimeReadinessSchema } from "./runtime-readiness.js";
+import { forkRecoveryRequestSchema, forkRecoveryResultSchema, publicForkResult } from "./codex-fork-contract.js";
 import { lockNodeAlias } from "./node-token-ownership.js";
 import { clearNodeFromAgentTeams, agentTeamWhoami } from "./agent-teams.js";
 import { parseDbTimestampMs } from "./db-timestamp.js";
@@ -840,6 +841,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         //    应当 hub 先合)。同一份 schema 里 side_thread_capability / external_schedules
         //    是 `.strict()` 的,后果不同 —— 见 `host:` 上方那段方框注释。
         daemon_capabilities: z.object({
+          codex_fork_recovery: z.object({ protocol: z.literal(1), cli_supported: z.boolean() }).optional().catch(undefined),
           adopt_capable: z.boolean().optional(),
           runtimes_supported: z.array(z.string().max(64)).max(16).optional(),
           allowed_secret_keys: z.array(z.string().max(64)).max(64).optional(),
@@ -5393,9 +5395,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     {
       ...NODE_ID_ALIAS_FIELDS,
       daemon_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/).optional(),
+      fork_recovery: forkRecoveryRequestSchema.optional(),
       network_id: z.string().max(200).optional(),
     },
-    async ({ node_id, child_node_id: child_node_id_arg, daemon_node_id, network_id: clientNetId }) => {
+    async ({ node_id, child_node_id: child_node_id_arg, daemon_node_id, network_id: clientNetId, fork_recovery }) => {
       const idArg = resolveNodeIdArg({ node_id, child_node_id: child_node_id_arg });
       if (!idArg.ok) return { content: [{ type: "text" as const, text: JSON.stringify(idArg) }] };
       const child_node_id = idArg.node_id;
@@ -5414,6 +5417,20 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       );
       if (!child) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "forbidden_cross_tenant" }) }] };
       if (!canWrite(child.network_id)) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "permission_denied" }) }] };
+      if (fork_recovery !== undefined) {
+        const fail = (error: string) => ({ content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error }) }] });
+        if (!forkRecoveryRequestSchema.safeParse(fork_recovery).success) return fail("codex_fork_confirmation_invalid");
+        // Confirmation is additional to the existing caller/child authority.
+        // Require an affirmative new capability; missing means old/unsupported.
+        if (createdDaemon(child_node_id) !== resolvedDaemonId || activeBinding(child_node_id)) return fail("codex_fork_recovery_unsupported");
+        const daemon = db.get<{ config_snapshot: string | null; network_id: string }>(
+          `SELECT config_snapshot, network_id FROM nodes WHERE node_id=?1`, resolvedDaemonId);
+        let snapshot: any;
+        try { snapshot = JSON.parse(daemon?.config_snapshot || "{}"); } catch { /* unsupported */ }
+        const capability = snapshot?.daemon_capabilities?.codex_fork_recovery;
+        if (daemon?.network_id !== child.network_id || snapshot?.role !== "host_supervisor"
+            || capability?.protocol !== 1 || capability?.cli_supported !== true) return fail("codex_fork_recovery_unsupported");
+      }
       // #1448 finding-2 — stale-starting reaper，对齐 update_node_config / restart_node
       // 的 60s single-flight stale-supersede。start 只受理 'stopped';一旦卡 'starting'
       // (门铃丢 / daemon 在 UPDATE 'starting' 后死),config/restart 有 reaper、delete 有
@@ -5426,8 +5443,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "node_not_stopped", current_state: priorState }) }] };
         }
         const STALE_STARTING_MS = 60_000;
-        const inFlight = db.get<{ request_id: string; created_at: number; delivered_at: number | null; acked_at: number | null }>(
-          `SELECT request_id, created_at, delivered_at, acked_at FROM node_start_requests
+        const inFlight = db.get<{ request_id: string; created_at: number; delivered_at: number | null; acked_at: number | null; fork_recovery_json: string | null }>(
+          `SELECT request_id, created_at, delivered_at, acked_at, fork_recovery_json FROM node_start_requests
              WHERE child_node_id = ?1 AND status IN ('pending', 'delivered')
              ORDER BY created_at DESC LIMIT 1`, child.node_id,
         );
@@ -5443,6 +5460,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
               hint: `再等一下;超过 ${STALE_STARTING_MS / 1000}s 仍卡 starting,重试 start 会重新派发`,
             }) }] };
           }
+          // A timed-out receipt cannot prove a confirmed fork did not happen.
+          // Do not create a second recovery generation via the ordinary reaper.
+          if (inFlight.fork_recovery_json) return { content: [{ type: "text" as const, text: JSON.stringify({
+            ok: false, error: "codex_fork_outcome_unknown", existing_request_id: inFlight.request_id,
+          }) }] };
           // Stale — 标旧请求 timeout(autocommit,先于下面 tx 的新 INSERT,解除
           // node_start_requests 对 pending/delivered 的 child 唯一约束),放行重派。
           db.run(
@@ -5472,9 +5494,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           db.run(
             `INSERT INTO node_start_requests
                (request_id, network_id, daemon_node_id, child_node_id, child_alias,
-                created_by_token, status, created_at)
-             VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'pending', ?7)`,
-            [requestId, child.network_id, daemon.node_id, child.node_id, child.alias, callerTokenId || "unknown", now],
+                created_by_token, status, created_at, fork_recovery_json)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'pending', ?7, ?8)`,
+            [requestId, child.network_id, daemon.node_id, child.node_id, child.alias, callerTokenId || "unknown", now,
+              fork_recovery ? JSON.stringify(fork_recovery) : null],
           );
           // #1448 finding-2 — 也接受从 'starting' 重派(stale-supersede 后原态仍是
           // starting);两种入态都合法地转/留到 'starting'。
@@ -5497,19 +5520,27 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   server.tool(
     "get_start_request",
     "Host supervisor pulls an authenticated pending start request.",
-    { request_id: z.string().min(1).max(200) },
-    async ({ request_id }) => {
+    { request_id: z.string().min(1).max(200), fork_recovery_capable: z.boolean().optional() },
+    async ({ request_id, fork_recovery_capable }) => {
       const callerDaemon = resolveCallerDaemonTokenBound();
       if (!callerDaemon.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
-      const row = db.get<{ daemon_node_id: string; network_id: string; child_node_id: string; child_alias: string; status: string }>(
-        `SELECT daemon_node_id, network_id, child_node_id, child_alias, status FROM node_start_requests WHERE request_id = ?1`, request_id,
+      const row = db.get<{ daemon_node_id: string; network_id: string; child_node_id: string; child_alias: string; status: string; fork_recovery_json: string | null }>(
+        `SELECT daemon_node_id, network_id, child_node_id, child_alias, status, fork_recovery_json FROM node_start_requests WHERE request_id = ?1`, request_id,
       );
       if (!row) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_found" }) }] };
       if (row.daemon_node_id !== callerDaemon.daemonNodeId) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "not_your_request" }) }] };
       if (row.network_id !== callerDaemon.networkId) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_request" }) }] };
       if (!['pending', 'delivered'].includes(row.status)) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_startable", status: row.status }) }] };
+      let recovery: unknown;
+      if (row.fork_recovery_json !== null) {
+        if (fork_recovery_capable !== true || createdDaemon(row.child_node_id) !== row.daemon_node_id || activeBinding(row.child_node_id))
+          return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "codex_fork_recovery_unsupported" }) }] };
+        try { recovery = forkRecoveryRequestSchema.parse(JSON.parse(row.fork_recovery_json)); }
+        catch { return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "codex_fork_confirmation_invalid" }) }] }; }
+      }
       db.run(`UPDATE node_start_requests SET status='delivered', delivered_at=?1 WHERE request_id=?2 AND status='pending'`, [Date.now(), request_id]);
-      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request_id, child_node_id: row.child_node_id, child_alias: row.child_alias }) }] };
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request_id, child_node_id: row.child_node_id, child_alias: row.child_alias, start_completion_capable: true,
+        ...(recovery ? { managed: "created", fork_recovery: recovery } : {}) }) }] };
     },
   );
 
@@ -5518,15 +5549,16 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "Host supervisor reports start completion or failure.",
     {
       request_id: z.string().min(1).max(200),
-      status: z.enum(["started", "start_failed"]),
+      status: z.enum(["starting", "started", "start_failed"]),
       child_pid: z.number().int().positive().optional(),
       error: z.string().max(1000).optional(),
+      fork_recovery: forkRecoveryResultSchema.optional(),
     },
-    async ({ request_id, status, child_pid, error: ackError }) => {
+    async ({ request_id, status, child_pid, error: ackError, fork_recovery }) => {
       const callerDaemon = resolveCallerDaemonTokenBound();
       if (!callerDaemon.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
-      const row = db.get<{ daemon_node_id: string; network_id: string; child_node_id: string; child_alias: string; status: string }>(
-        `SELECT daemon_node_id, network_id, child_node_id, child_alias, status FROM node_start_requests WHERE request_id=?1`, request_id,
+      const row = db.get<{ daemon_node_id: string; network_id: string; child_node_id: string; child_alias: string; status: string; fork_recovery_json: string | null }>(
+        `SELECT daemon_node_id, network_id, child_node_id, child_alias, status, fork_recovery_json FROM node_start_requests WHERE request_id=?1`, request_id,
       );
       if (!row) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_found" }) }] };
       if (row.daemon_node_id !== callerDaemon.daemonNodeId) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "not_your_request" }) }] };
@@ -5537,13 +5569,25 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (!['pending', 'delivered'].includes(row.status)) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_ackable", status: row.status }) }] };
       }
+      if (fork_recovery !== undefined && (!row.fork_recovery_json || status === "starting"
+          || !forkRecoveryResultSchema.safeParse(fork_recovery).success)) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "codex_fork_result_invalid" }) }] };
+      }
+      // A finite co-presence launcher can spend minutes restoring a large thread.
+      // Refresh the existing stale-start clock, without claiming startup completed.
+      if (status === "starting") {
+        db.run(`UPDATE node_start_requests SET acked_at=?1 WHERE request_id=?2`, [Date.now(), request_id]);
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, status: "starting" }) }] };
+      }
       if (status === "started" && !child_pid) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "child_pid_required" }) }] };
       }
       const now = Date.now();
       try {
         db.transaction(() => {
-          db.run(`UPDATE node_start_requests SET status=?1,error=?2,child_pid=?3,acked_at=?4 WHERE request_id=?5`, [status, ackError || null, child_pid || null, now, request_id]);
+          db.run(`UPDATE node_start_requests SET status=?1,error=?2,child_pid=?3,acked_at=?4,fork_result_json=?6 WHERE request_id=?5`,
+            [status, ackError || null, child_pid || null, now, request_id,
+              row.fork_recovery_json ? JSON.stringify(publicForkResult(fork_recovery)) : null]);
           db.run(`UPDATE nodes SET lifecycle_state=?1 WHERE node_id=?2`, [status === "started" ? "active" : "stopped", row.child_node_id]);
           if (status === "started") auditCreateNodeStrict({
             action: "start_node_completed", network_id: row.network_id, target_id: request_id,