@sleep2agi/commhub-server 0.9.0-preview.30 → 0.9.0-preview.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.30",
+  "version": "0.9.0-preview.31",
   "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/package-version-consistency.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+type PackageManifest = { version: string };
+type PackageLock = {
+  version: string;
+  packages: { "": { version: string } };
+};
+
+const readJson = <T>(name: string): T =>
+  JSON.parse(readFileSync(join(import.meta.dir, "..", name), "utf8")) as T;
+
+describe("server package version consistency", () => {
+  const manifest = readJson<PackageManifest>("package.json");
+  const lock = readJson<PackageLock>("package-lock.json");
+
+  test("package-lock top-level version matches package.json", () => {
+    expect(lock.version).toBe(manifest.version);
+  });
+
+  test("package-lock root package version matches package.json", () => {
+    expect(lock.packages[""].version).toBe(manifest.version);
+  });
+});

package/src/server.ts

@@ -51,6 +51,7 @@ import { handleExternalScheduleEditRequest } from "./external-schedule-edits.js"
 import { recordDeliveredStaleEvents } from "./task-lifecycle-watcher.js";
 import { SIDE_THREAD_FEATURE_FLAG, SideThreadCoordinator, SideThreadPortRegistry, SideThreadStore, type SideThreadActor, type SideThreadAttachmentRef, type SideThreadExecutionPort } from "./side-thread.js";
 import { handleSideThreadHttpRequest } from "./side-thread-http.js";
+import { createProductionSideThreadTransport } from "./side-thread-production.js";
 
 const PORT = resolvePort(process.env.PORT);
 const HOST = process.env.HOST || "127.0.0.1";
@@ -77,6 +78,10 @@ const sideThreadCoordinator = new SideThreadCoordinator(new SideThreadStore(db),
   authorizeNode: (actor, networkId, nodeId) => authorizeSideThreadNode(actor, networkId, nodeId),
   authorizeAttachment: (actor, networkId, ref) => authorizeSideThreadAttachment(actor, networkId, ref),
 });
+const productionSideThreadTransport = process.env[SIDE_THREAD_FEATURE_FLAG] === "1"
+  ? createProductionSideThreadTransport(db)
+  : null;
+if (productionSideThreadTransport) installSideThreadExecutionPort(productionSideThreadTransport.port);
 
 if (AUTH_TOKEN) {
   console.warn("[commhub] COMMHUB_AUTH_TOKEN is deprecated and will be removed in v1.0. See RFC-001.");
@@ -1519,11 +1524,22 @@ return Bun.serve({
       return withCors(req, Response.json({ ok: false, error: restScope.denied }, { status: 403 }));
     }
 
+    const sideActor = resolveSideThreadActor(req, resolveRequestAuth(req, { allowQueryToken: false }), isAdmin);
+    const nodeCommandActor = sideActor?.kind === "node" && sideActor.boundNodeId && sideActor.boundNetworkId
+      ? { tokenId: sideActor.tokenId, networkId: sideActor.boundNetworkId, nodeId: sideActor.boundNodeId }
+      : null;
+    if (productionSideThreadTransport) {
+      const attachmentResponse = await productionSideThreadTransport.attachment(req, url, nodeCommandActor);
+      if (attachmentResponse) return withCors(req, attachmentResponse);
+      const commandResponse = await productionSideThreadTransport.handle({ req, url, actor: nodeCommandActor });
+      if (commandResponse) return withCors(req, commandResponse);
+    }
+
     const sideThreadResponse = await handleSideThreadHttpRequest({
       req,
       url,
       // Durable prompts/results never accept query-string credentials.
-      actor: resolveSideThreadActor(req, resolveRequestAuth(req, { allowQueryToken: false }), isAdmin),
+      actor: sideActor,
       coordinator: sideThreadCoordinator,
       resolveCapabilityTarget: resolveSideThreadCapabilityTarget,
     });

package/src/side-thread-command-transport.test.ts

@@ -16,6 +16,168 @@ function fixture() {
 }
 
 describe("Hub durable SideThread command outbox", () => {
+  test("late fork and start ACKs reconcile the coordinator across restart", async () => {
+    const f = fixture();
+    const owner = { userId: "user-1", username: "owner", tokenId: "utok-1", kind: "user" as const };
+    const input = { requestKey: "rk-late-create", networkId: "net-1", nodeId: "node-1", sourceThreadId: "source-1", boundary: { kind: "through" as const, turnId: "source-turn" }, prompt: "late receipt", attachments: [] };
+    const sideStore = new SideThreadStore(f.db);
+    let coordinator = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+    const originalTransaction = f.db.transaction.bind(f.db);
+    const failTransaction = (...nth: number[]) => { let calls = 0; (f.db as any).transaction = (fn: () => unknown) => nth.includes(++calls) ? (() => { throw new Error("injected create apply failure"); })() : originalTransaction(fn); };
+    failTransaction(2);
+    await expect(coordinator.create(owner, input)).rejects.toThrow("injected create apply failure");
+    const side = sideStore.getByCreateKey(owner, input.requestKey)!.record;
+    expect(side).toMatchObject({ state: "creating", attempts: [{ state: "starting" }], operations: [{ kind: "fork", state: "pending" }] });
+    const fork = f.store.claim(actor())!;
+    f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: fork.commandId, operationId: fork.operationId, state: "accepted", errorCode: null, result: { threadId: "derived-late", turnId: null, destinationTurnId: null } });
+    (f.db as any).transaction = originalTransaction;
+    coordinator.close();
+    coordinator = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+    failTransaction(2, 3);
+    await expect(coordinator.create(owner, input)).rejects.toThrow("injected create apply failure");
+    expect(sideStore.getByCreateKey(owner, input.requestKey)!.record).toMatchObject({ state: "reconciling", attempts: [{ state: "reconciling" }], operations: [{ kind: "fork", state: "pending" }] });
+    expect(f.store.claim(actor())).toBeNull();
+    (f.db as any).transaction = originalTransaction;
+    coordinator.close();
+    coordinator = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+    await expect(coordinator.create(owner, input)).rejects.toMatchObject({ code: "SIDE_THREAD_AMBIGUOUS" });
+    const start = f.store.claim(actor())!;
+    expect(start.kind).toBe("start");
+    f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: start.commandId, operationId: start.operationId, state: "accepted", errorCode: null, result: { threadId: null, turnId: "turn-late", destinationTurnId: null } });
+    failTransaction(3);
+    await expect(coordinator.create(owner, input)).rejects.toMatchObject({ code: "SIDE_THREAD_AMBIGUOUS" });
+    expect(f.store.claim(actor())).toBeNull();
+    (f.db as any).transaction = originalTransaction;
+    coordinator.close();
+    coordinator = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+    expect(await coordinator.create(owner, input)).toMatchObject({ state: "running", threadId: "derived-late", attempts: [{ turnId: "turn-late" }] });
+    const terminal = { protocol: "side_thread.terminal.v1", sideThreadId: side.sideChatId, attemptId: side.activeAttemptId!, threadId: "derived-late", turnId: "turn-late", status: "completed" as const, text: "late answer", errorCode: null };
+    expect((await f.port.acceptTerminal(actor(), terminal)).confirmed).toBe(true);
+
+    expect(await coordinator.create(owner, input)).toMatchObject({ sideChatId: side.sideChatId, state: "completed", threadId: "derived-late", attempts: [{ turnId: "turn-late", result: "late answer" }] });
+    expect(coordinator.get(owner, side.sideChatId).operations.filter((operation) => operation.kind === "fork" || operation.kind === "start")).toHaveLength(2);
+    expect(f.store.claim(actor())).toBeNull();
+    expect((await f.port.acceptTerminal(actor(), terminal)).idempotent).toBe(true);
+    expect(coordinator.get(owner, side.sideChatId)).toMatchObject({ state: "completed", attempts: [{ result: "late answer" }] });
+    coordinator.close();
+  });
+
+  for (const receipt of [
+    { state: "unsupported", errorCode: "SIDE_THREAD_UNSUPPORTED", code: "SIDE_THREAD_UNSUPPORTED", status: 501 },
+    { state: "failed", errorCode: "SIDE_THREAD_CONFLICT", code: "SIDE_THREAD_CONFLICT", status: 409 },
+  ] as const) test(`late ${receipt.state} fork ACK converges to stable failed across coordinators`, async () => {
+    const f = fixture();
+    const owner = { userId: "user-1", username: "owner", tokenId: "utok-1", kind: "user" as const };
+    const input = { requestKey: `rk-late-${receipt.state}`, networkId: "net-1", nodeId: "node-1", sourceThreadId: "source-1", boundary: { kind: "through" as const, turnId: "source-turn" }, prompt: "late failure", attachments: [] };
+    const sideStore = new SideThreadStore(f.db);
+    let first = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+    await expect(first.create(owner, input)).rejects.toMatchObject({ code: "SIDE_THREAD_AMBIGUOUS" });
+    const command = f.store.claim(actor())!;
+    f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: command.commandId, operationId: command.operationId, state: receipt.state, errorCode: receipt.errorCode, result: { threadId: null, turnId: null, destinationTurnId: null } });
+    first.close();
+
+    const second = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+    await expect(second.create(owner, input)).rejects.toMatchObject({ code: receipt.code, status: receipt.status });
+    const failed = sideStore.getByCreateKey(owner, input.requestKey)!.record;
+    expect(failed).toMatchObject({ state: "failed", attempts: [{ state: "failed" }], operations: [{ kind: "fork", state: "failed", errorCode: receipt.code }] });
+    expect(failed.activeAttemptId).toBeUndefined();
+    expect(f.db.get<{ active: string | null }>("SELECT active_attempt_id active FROM side_chats WHERE side_chat_id=?1", failed.sideChatId)?.active).toBeNull();
+    expect(await second.create(owner, input)).toMatchObject({ sideChatId: failed.sideChatId, state: "failed" });
+    expect(f.store.claim(actor())).toBeNull();
+    second.close();
+  });
+
+  for (const action of ["cancel", "archive", "purge", "bring-back"] as const)
+    for (const receipt of [
+      { state: "accepted", errorCode: null, code: null },
+      { state: "unsupported", errorCode: "SIDE_THREAD_UNSUPPORTED", code: "SIDE_THREAD_UNSUPPORTED" },
+      { state: "failed", errorCode: "SIDE_THREAD_CONFLICT", code: "SIDE_THREAD_CONFLICT" },
+    ] as const) test(`${action} consumes a late ${receipt.state} receipt after restart`, async () => {
+      const f = fixture();
+      const owner = { userId: "user-1", username: "owner", tokenId: "utok-1", kind: "user" as const };
+      const input = { requestKey: `rk-create-${action}-${receipt.state}`, networkId: "net-1", nodeId: "node-1", sourceThreadId: "source-1", boundary: { kind: "through" as const, turnId: "source-turn" }, prompt: "lifecycle", attachments: [] };
+      const sideStore = new SideThreadStore(f.db);
+      let coordinator = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+      await coordinator.create(owner, input).catch(() => {});
+      const fork = f.store.claim(actor())!;
+      f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: fork.commandId, operationId: fork.operationId, state: "accepted", errorCode: null, result: { threadId: "derived-life", turnId: null, destinationTurnId: null } });
+      await coordinator.create(owner, input).catch(() => {});
+      const start = f.store.claim(actor())!;
+      f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: start.commandId, operationId: start.operationId, state: "accepted", errorCode: null, result: { threadId: null, turnId: "turn-life", destinationTurnId: null } });
+      const running = await coordinator.create(owner, input);
+      if (action !== "cancel") await f.port.acceptTerminal(actor(), { protocol: "side_thread.terminal.v1", sideThreadId: running.sideChatId, attemptId: running.activeAttemptId!, threadId: "derived-life", turnId: "turn-life", status: "completed", text: "answer", errorCode: null });
+      const requestKey = `rk-${action}-${receipt.state}`;
+      const invoke = (c: SideThreadCoordinator) => action === "cancel" ? c.cancel(owner, running.sideChatId, { requestKey })
+        : action === "archive" ? c.archive(owner, running.sideChatId, { requestKey })
+        : action === "purge" ? c.purge(owner, running.sideChatId, { requestKey })
+        : c.bringBack(owner, running.sideChatId, { requestKey, destinationThreadId: "source-1" });
+      await invoke(coordinator).catch(() => {});
+      const command = f.store.claim(actor())!;
+      f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: command.commandId, operationId: command.operationId, state: receipt.state, errorCode: receipt.errorCode, result: { threadId: null, turnId: null, destinationTurnId: action === "bring-back" && receipt.state === "accepted" ? "destination-life" : null } });
+      coordinator.close();
+      coordinator = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+      if (receipt.code) {
+        await expect(invoke(coordinator)).rejects.toMatchObject({ code: receipt.code });
+        await expect(invoke(coordinator)).rejects.toMatchObject({ code: receipt.code });
+      } else {
+        if (action === "archive" || action === "bring-back") {
+          const originalTransaction = f.db.transaction.bind(f.db);
+          let failApply = true;
+          (f.db as any).transaction = (fn: () => unknown) => {
+            if (failApply) { failApply = false; throw new Error("injected local apply failure"); }
+            return originalTransaction(fn);
+          };
+          await expect(invoke(coordinator)).rejects.toMatchObject({ code: "SIDE_THREAD_AMBIGUOUS", status: 202 });
+          const unsettled = sideStore.getByCreateKey(owner, input.requestKey)!.record.operations.find((op) => op.kind === action && op.requestKey === requestKey)!;
+          expect(["ambiguous", "reconciling"]).toContain(unsettled.state);
+          expect(unsettled.state).not.toBe("failed");
+          (f.db as any).transaction = originalTransaction;
+          coordinator.close();
+          coordinator = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+        }
+        const [one, two] = await Promise.all([invoke(coordinator), invoke(coordinator)]);
+        if (action === "bring-back") expect(one).toEqual({ bringBackId: expect.any(String), destinationTurnId: "destination-life" });
+        else expect(one).toMatchObject({ state: action === "cancel" ? "running" : action === "archive" ? "archived" : "purged" });
+        expect(two).toEqual(one);
+        const hydrated = coordinator.get(owner, running.sideChatId);
+        const operation = hydrated.operations.find((op) => op.kind === action && op.requestKey === requestKey)!;
+        expect(operation).toMatchObject({ state: "completed", threadId: action === "bring-back" ? "source-1" : "derived-life" });
+        if (action === "bring-back") expect(operation.turnId).toBe("destination-life");
+        if (action === "cancel") expect(operation.turnId).toBe("turn-life");
+        const domainType = action === "bring-back" ? "side_chat.brought_back" : action === "archive" ? "side_chat.archived" : action === "purge" ? "side_chat.purged" : null;
+        const afterEvents = coordinator.listEvents(owner, running.sideChatId);
+        if (domainType) expect(afterEvents.filter((event) => event.type === domainType)).toHaveLength(1);
+        else expect(afterEvents.filter((event) => ["side_chat.brought_back", "side_chat.archived", "side_chat.purged"].includes(event.type))).toHaveLength(0);
+      }
+      expect(f.store.claim(actor())).toBeNull();
+      coordinator.close();
+    });
+
+  test("two coordinators race a late archive receipt but persist one domain event", async () => {
+    const f = fixture();
+    const owner = { userId: "user-1", username: "owner", tokenId: "utok-1", kind: "user" as const };
+    const input = { requestKey: "rk-multi-archive-create", networkId: "net-1", nodeId: "node-1", sourceThreadId: "source-1", boundary: { kind: "through" as const, turnId: "source-turn" }, prompt: "multi", attachments: [] };
+    const sideStore = new SideThreadStore(f.db);
+    const bootstrap = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+    await bootstrap.create(owner, input).catch(() => {});
+    const fork = f.store.claim(actor())!; f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: fork.commandId, operationId: fork.operationId, state: "accepted", errorCode: null, result: { threadId: "derived-multi", turnId: null, destinationTurnId: null } });
+    await bootstrap.create(owner, input).catch(() => {});
+    const start = f.store.claim(actor())!; f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: start.commandId, operationId: start.operationId, state: "accepted", errorCode: null, result: { threadId: null, turnId: "turn-multi", destinationTurnId: null } });
+    const running = await bootstrap.create(owner, input);
+    await f.port.acceptTerminal(actor(), { protocol: "side_thread.terminal.v1", sideThreadId: running.sideChatId, attemptId: running.activeAttemptId!, threadId: "derived-multi", turnId: "turn-multi", status: "completed", text: "done", errorCode: null });
+    await bootstrap.archive(owner, running.sideChatId, { requestKey: "rk-multi-archive" }).catch(() => {});
+    const archive = f.store.claim(actor())!; f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: archive.commandId, operationId: archive.operationId, state: "accepted", errorCode: null, result: { threadId: null, turnId: null, destinationTurnId: null } });
+    bootstrap.close();
+    const port = () => new DurableSideThreadCommandPort({ store: f.store, networkForNode: () => "net-1", capabilityForNode: () => ({ supported: true, mode: "native-exact-fork", exactBoundary: { through: true, before: true } }), grantAttachment: (_node, ref) => ({ fileId: ref.fileId }) });
+    const a = new SideThreadCoordinator(sideStore, port(), { enabled: true, authorizeNode: () => true });
+    const b = new SideThreadCoordinator(sideStore, port(), { enabled: true, authorizeNode: () => true });
+    const [one, two] = await Promise.all([a.archive(owner, running.sideChatId, { requestKey: "rk-multi-archive" }), b.archive(owner, running.sideChatId, { requestKey: "rk-multi-archive" })]);
+    expect(one.state).toBe("archived"); expect(two.state).toBe("archived");
+    expect(sideStore.events(running.sideChatId).filter((event) => event.type === "side_chat.archived")).toHaveLength(1);
+    expect(f.store.claim(actor())).toBeNull();
+    a.close(); b.close();
+  });
+
   test("fails closed on the currently non-atomic PostgreSQL adapter", () => {
     expect(() => new SideThreadCommandStore({ dialect: "postgres" } as any)).toThrow(/atomic SQLite/);
   });

package/src/side-thread-command-transport.ts

@@ -225,6 +225,7 @@ export class DurableSideThreadCommandPort implements SideThreadExecutionPort {
     networkForNode: (nodeId: string) => string | null;
     capabilityForNode: (nodeId: string) => SideThreadCapability;
     grantAttachment: (nodeId: string, ref: SideThreadAttachmentRef) => Record<string, unknown>;
+    ackWaitMs?: number;
   }) {}
   capability(nodeId: string) { return this.opts.capabilityForNode(nodeId); }
   fork(input: Parameters<SideThreadExecutionPort["fork"]>[0]) { return this.issue(input, "fork", { sourceThreadId: input.sourceThreadId, boundary: input.boundary }, "threadId") as Promise<{threadId:string}>; }
@@ -261,10 +262,18 @@ export class DurableSideThreadCommandPort implements SideThreadExecutionPort {
       requestKey: input.requestKey ?? input.operationId, nodeId: input.nodeId, sideThreadId: input.sideChatId,
       attemptId: input.attemptId ?? null, kind, payload };
     this.opts.store.enqueue(command, { networkId, nodeId: input.nodeId });
-    const receipt = this.opts.store.receipt(input.operationId);
+    const deadline = Date.now() + (this.opts.ackWaitMs ?? 0);
+    let receipt = this.opts.store.receipt(input.operationId);
+    while (!receipt && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      receipt = this.opts.store.receipt(input.operationId);
+    }
     if (!receipt) throw new SideThreadError("SIDE_THREAD_AMBIGUOUS", "command durably queued; awaiting node ACK", 202, input.operationId, input.sideChatId, input.attemptId);
     if (receipt.state === "accepted") return resultKey ? { [resultKey]: object(receipt.result)[resultKey] } : undefined;
-    throw new SideThreadError(receipt.errorCode === "SIDE_THREAD_UNSUPPORTED" ? "SIDE_THREAD_UNSUPPORTED" : "SIDE_THREAD_AMBIGUOUS", "node command did not complete synchronously", receipt.errorCode === "SIDE_THREAD_UNSUPPORTED" ? 501 : 202, input.operationId, input.sideChatId, input.attemptId);
+    const code = receipt.state === "unsupported" ? "SIDE_THREAD_UNSUPPORTED"
+      : receipt.state === "failed" ? "SIDE_THREAD_CONFLICT" : "SIDE_THREAD_AMBIGUOUS";
+    const status = code === "SIDE_THREAD_UNSUPPORTED" ? 501 : code === "SIDE_THREAD_CONFLICT" ? 409 : 202;
+    throw new SideThreadError(code, "node command returned an authoritative result", status, input.operationId, input.sideChatId, input.attemptId);
   }
 }
 

package/src/side-thread-production.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SQLiteAdapter } from "./db-adapter";
+import { createProductionSideThreadTransport } from "./side-thread-production";
+
+const roots: string[] = [];
+const priorUploads = process.env.COMMHUB_UPLOADS_DIR;
+afterEach(() => {
+  if (priorUploads === undefined) delete process.env.COMMHUB_UPLOADS_DIR;
+  else process.env.COMMHUB_UPLOADS_DIR = priorUploads;
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("production Hub SideThread wiring", () => {
+  test("advertises only an exact node snapshot and serves a short-lived node-bound grant", async () => {
+    const root = mkdtempSync(join(tmpdir(), "side-hub-prod-")); roots.push(root);
+    process.env.COMMHUB_UPLOADS_DIR = root;
+    const db = new SQLiteAdapter(new Database(":memory:"));
+    db.exec("CREATE TABLE nodes(node_id TEXT PRIMARY KEY, network_id TEXT, config_snapshot TEXT)");
+    db.run("INSERT INTO nodes VALUES (?1,?2,?3)", ["node-1", "net-1", JSON.stringify({ side_thread_capability: {
+      supported: true, runtime: "codex-app-server", runtimeVersion: "0.148.0", topology: "owned-stdio",
+      evidenceRevision: "test1190-wire-v2", mode: "native-exact-fork", exactBoundary: { through: true, before: false },
+    } })]);
+    let now = 1_000;
+    const transport = createProductionSideThreadTransport(db, () => now, 0);
+    expect(transport.port.capability("node-1")).toMatchObject({ supported: true, exactBoundary: { before: false } });
+    expect(transport.port.capability("missing")).toMatchObject({ supported: false, reason: "runtime" });
+
+    const fileId = "file12345678"; const bytes = Buffer.from("image bytes"); const bucket = "2026-08-26";
+    mkdirSync(join(root, ".index"), { recursive: true }); mkdirSync(join(root, bucket), { recursive: true });
+    writeFileSync(join(root, bucket, `${fileId}.png`), bytes);
+    writeFileSync(join(root, ".index", `${fileId}.json`), JSON.stringify({
+      file_id: fileId, date_bucket: bucket, ext: ".png", name: "x.png", mime: "image/png",
+      size: bytes.length, owner_id: "user-1", network_id: "net-1", uploaded_at: new Date().toISOString(),
+    }));
+    await transport.port.start({
+      operationId: "op-start", requestKey: "rk-start", sideChatId: "side-1", attemptId: "attempt-1",
+      nodeId: "node-1", threadId: "derived-1", prompt: "read it",
+      attachments: [{ fileId, mediaType: "image/png", size: bytes.length }],
+    }).catch(() => {});
+    const command = transport.store.claim({ tokenId: "token-1", networkId: "net-1", nodeId: "node-1" }) as any;
+    const grant = command.payload.attachments[0];
+    expect(grant).toMatchObject({ fileId, mediaType: "image/png", size: bytes.length });
+    expect(grant.sha256).toMatch(/^[a-f0-9]{64}$/);
+    const url = new URL(`http://hub/api/side-thread/attachment-grants/${grant.grantId}`);
+    const foreign = await transport.attachment(new Request(url), url, { tokenId: "foreign", networkId: "net-1", nodeId: "node-2" });
+    expect(foreign?.status).toBe(404);
+    const response = await transport.attachment(new Request(url), url, { tokenId: "token-1", networkId: "net-1", nodeId: "node-1" });
+    expect(response?.status).toBe(200); expect(Buffer.from(await response!.arrayBuffer())).toEqual(bytes);
+    now += 5 * 60_000 + 1;
+    expect((await transport.attachment(new Request(url), url, { tokenId: "token-1", networkId: "net-1", nodeId: "node-1" }))?.status).toBe(404);
+    await transport.port.start({
+      operationId: "op-start-2", requestKey: "rk-start-2", sideChatId: "side-2", attemptId: "attempt-2",
+      nodeId: "node-1", threadId: "derived-2", prompt: "read it again",
+      attachments: [{ fileId, mediaType: "image/png", size: bytes.length }],
+    }).catch(() => {});
+    expect(db.get<{ count: number }>("SELECT COUNT(*) AS count FROM side_thread_attachment_grants")?.count).toBe(1);
+  });
+
+  test("rejects forged capability shapes instead of widening the allowlist", () => {
+    const db = new SQLiteAdapter(new Database(":memory:"));
+    db.exec("CREATE TABLE nodes(node_id TEXT PRIMARY KEY, network_id TEXT, config_snapshot TEXT)");
+    db.run("INSERT INTO nodes VALUES (?1,?2,?3)", ["node-1", "net-1", JSON.stringify({ side_thread_capability: {
+      supported: true, runtime: "codex-app-server", runtimeVersion: "latest", topology: "owned-stdio",
+      evidenceRevision: "test1190-wire-v2", mode: "native-exact-fork", exactBoundary: { through: true, before: true },
+    } })]);
+    expect(createProductionSideThreadTransport(db).port.capability("node-1")).toMatchObject({ supported: false });
+  });
+});

package/src/side-thread-production.ts

@@ -0,0 +1,118 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { DbAdapter } from "./db-adapter.js";
+import { indexEntryPath, pathForExistingBlob, validateIndexEntry } from "./uploads.js";
+import type { SideThreadAttachmentRef, SideThreadCapability } from "./side-thread.js";
+import {
+  DurableSideThreadCommandPort,
+  SideThreadCommandStore,
+  handleSideThreadCommandRequest,
+  type NodeCommandActor,
+} from "./side-thread-command-transport.js";
+
+const GRANT_TTL_MS = 5 * 60_000;
+
+type GrantRow = {
+  grant_id: string; file_id: string; network_id: string; node_id: string;
+  sha256: string; size: number; media_type: string; expires_at: number;
+};
+
+/** Production-only SideThread transport. It remains absent unless the public
+ * feature flag is enabled and the configured DB can provide atomic claims. */
+export function createProductionSideThreadTransport(db: DbAdapter, now = Date.now, ackWaitMs = 2_500) {
+  const store = new SideThreadCommandStore(db, now);
+  db.exec(`CREATE TABLE IF NOT EXISTS side_thread_attachment_grants (
+    grant_id TEXT PRIMARY KEY, file_id TEXT NOT NULL, network_id TEXT NOT NULL,
+    node_id TEXT NOT NULL, sha256 TEXT NOT NULL, size INTEGER NOT NULL,
+    media_type TEXT NOT NULL, expires_at INTEGER NOT NULL, created_at INTEGER NOT NULL
+  )`);
+  const port = new DurableSideThreadCommandPort({
+    store,
+    networkForNode(nodeId) {
+      return db.get<{ network_id: string | null }>("SELECT network_id FROM nodes WHERE node_id=?1", nodeId)?.network_id ?? null;
+    },
+    capabilityForNode(nodeId) {
+      const row = db.get<{ config_snapshot: string | null }>("SELECT config_snapshot FROM nodes WHERE node_id=?1", nodeId);
+      if (!row?.config_snapshot) return unsupported("runtime");
+      try {
+        const cap = JSON.parse(row.config_snapshot)?.side_thread_capability;
+        return validateCapability(cap) ? cap : unsupported("runtime");
+      } catch { return unsupported("runtime"); }
+    },
+    grantAttachment(nodeId, ref) { return issueGrant(db, nodeId, ref, now); },
+    // The dedicated node consumer polls asynchronously. Give its durable ACK
+    // a bounded window so the coordinator can advance fork→start atomically;
+    // timeout remains an honest ambiguous result, never a task fallback.
+    ackWaitMs,
+  });
+  return {
+    store,
+    port,
+    handle: (input: { req: Request; url: URL; actor: NodeCommandActor | null }) =>
+      handleSideThreadCommandRequest({ ...input, store, port }),
+    attachment: (req: Request, url: URL, actor: NodeCommandActor | null) =>
+      serveGrant(db, req, url, actor, now),
+  };
+}
+
+function issueGrant(db: DbAdapter, nodeId: string, ref: SideThreadAttachmentRef, now: () => number): Record<string, unknown> {
+  // Grants are deliberately short-lived and must not become an unbounded
+  // metadata cache. Lazy sweeping keeps the hot download path read-only while
+  // ensuring every new issuance bounds accumulated expired rows.
+  db.run("DELETE FROM side_thread_attachment_grants WHERE expires_at < ?1", [now()]);
+  const node = db.get<{ network_id: string | null }>("SELECT network_id FROM nodes WHERE node_id=?1", nodeId);
+  if (!node?.network_id) throw new Error("SideThread attachment node scope unavailable");
+  const indexPath = indexEntryPath(ref.fileId);
+  if (!indexPath) throw new Error("SideThread attachment index unavailable");
+  const entry = JSON.parse(readFileSync(indexPath, "utf8"));
+  if (!validateIndexEntry(entry) || entry.file_id !== ref.fileId || entry.network_id !== node.network_id)
+    throw new Error("SideThread attachment scope mismatch");
+  const path = pathForExistingBlob(entry.date_bucket, entry.file_id, entry.ext).absolutePath;
+  const bytes = readFileSync(path);
+  if (bytes.byteLength !== entry.size) throw new Error("SideThread attachment size changed");
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  const grantId = `stg_${randomUUID().replace(/-/g, "")}`;
+  const mediaType = typeof entry.mime === "string" && entry.mime.length <= 200 ? entry.mime : "application/octet-stream";
+  db.run(
+    "INSERT INTO side_thread_attachment_grants (grant_id,file_id,network_id,node_id,sha256,size,media_type,expires_at,created_at) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)",
+    [grantId, ref.fileId, node.network_id, nodeId, sha256, bytes.byteLength, mediaType, now() + GRANT_TTL_MS, now()],
+  );
+  return { fileId: ref.fileId, grantId, sha256, size: bytes.byteLength, mediaType };
+}
+
+async function serveGrant(db: DbAdapter, req: Request, url: URL, actor: NodeCommandActor | null, now: () => number): Promise<Response | null> {
+  const match = url.pathname.match(/^\/api\/side-thread\/attachment-grants\/([^/]+)$/);
+  if (!match) return null;
+  if (req.method !== "GET") return Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 });
+  if (!actor) return Response.json({ ok: false, error: "node_token_binding_required" }, { status: 403 });
+  let grantId: string;
+  try { grantId = decodeURIComponent(match[1]); } catch { return Response.json({ ok: false, error: "invalid_grant" }, { status: 400 }); }
+  const row = db.get<GrantRow>("SELECT * FROM side_thread_attachment_grants WHERE grant_id=?1", grantId);
+  // 404 deliberately hides existence, ownership and expiry.
+  if (!row || row.node_id !== actor.nodeId || row.network_id !== actor.networkId || row.expires_at < now())
+    return Response.json({ ok: false, error: "not_found" }, { status: 404 });
+  const indexPath = indexEntryPath(row.file_id);
+  if (!indexPath) return Response.json({ ok: false, error: "not_found" }, { status: 404 });
+  try {
+    const entry = JSON.parse(readFileSync(indexPath, "utf8"));
+    if (!validateIndexEntry(entry) || entry.network_id !== row.network_id || entry.size !== row.size)
+      return Response.json({ ok: false, error: "not_found" }, { status: 404 });
+    const bytes = readFileSync(pathForExistingBlob(entry.date_bucket, entry.file_id, entry.ext).absolutePath);
+    if (bytes.byteLength !== row.size || createHash("sha256").update(bytes).digest("hex") !== row.sha256)
+      return Response.json({ ok: false, error: "not_found" }, { status: 404 });
+    return new Response(bytes, { headers: { "Content-Type": row.media_type, "Content-Length": String(row.size), "Cache-Control": "no-store" } });
+  } catch { return Response.json({ ok: false, error: "not_found" }, { status: 404 }); }
+}
+
+function validateCapability(value: unknown): value is SideThreadCapability {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  return v.supported === true && v.runtime === "codex-app-server" && v.runtimeVersion === "0.148.0"
+    && v.topology === "owned-stdio" && v.evidenceRevision === "test1190-wire-v2"
+    && v.mode === "native-exact-fork" && !!v.exactBoundary && typeof v.exactBoundary === "object"
+    && (v.exactBoundary as any).through === true && typeof (v.exactBoundary as any).before === "boolean";
+}
+
+function unsupported(reason: SideThreadCapability["reason"]): SideThreadCapability {
+  return { supported: false, runtime: "unknown", runtimeVersion: "unknown", topology: "unknown", evidenceRevision: "none", reason };
+}

package/src/side-thread.test.ts

@@ -9,6 +9,7 @@ import {
   UnsupportedSideThreadPort,
   type SideThreadActor,
   type SideThreadExecutionPort,
+  type SideThreadEventRecord,
   type SideThreadRuntimeEvent,
 } from "./side-thread.js";
 import { handleSideThreadHttpRequest } from "./side-thread-http.js";
@@ -312,6 +313,28 @@ describe("SideThread Hub contract", () => {
     ).toHaveLength(3);
   });
 
+  test("throwing observers cannot alter durable truth or starve cursor replay", async () => {
+    const f = fixture();
+    const record = await f.coordinator.create(owner, createInput());
+    const attempt = record.attempts[0];
+    const cursor = f.coordinator.listEvents(owner, record.sideChatId).at(-1)!.eventId;
+    const delivered: SideThreadEventRecord[] = [];
+    const offThrow = f.coordinator.subscribe(record.sideChatId, () => { throw new Error("observer exploded"); });
+    const offGood = f.coordinator.subscribe(record.sideChatId, (event) => delivered.push(event));
+    f.port.emit({ sideChatId: record.sideChatId, attemptId: attempt.attemptId, threadId: record.threadId!, turnId: attempt.turnId!, status: "completed", text: "durable answer" });
+    await Bun.sleep(0);
+    expect(f.coordinator.get(owner, record.sideChatId)).toMatchObject({ state: "completed", attempts: [{ result: "durable answer" }] });
+    expect(delivered.filter((event) => event.type === "attempt.terminal")).toHaveLength(1);
+    const replay = f.coordinator.listEvents(owner, record.sideChatId, cursor);
+    expect(replay.filter((event) => event.type === "attempt.terminal")).toHaveLength(1);
+    expect(f.coordinator.listEvents(owner, record.sideChatId, replay.at(-1)!.eventId)).toHaveLength(0);
+    offThrow(); offGood();
+    f.coordinator.close();
+    const reopened = new SideThreadCoordinator(f.store, f.port, { enabled: true, authorizeNode: () => true, authorizeAttachment: () => true });
+    closers.push(() => reopened.close());
+    expect(reopened.listEvents(owner, record.sideChatId, cursor).filter((event) => event.type === "attempt.terminal")).toHaveLength(1);
+  });
+
   test("a terminal event arriving before start returns settles once", async () => {
     const f = fixture();
     f.port.onStart = (input, turnId) =>
@@ -391,10 +414,10 @@ describe("SideThread Hub contract", () => {
     closers.push(() => second.close());
     const firstCreate = f.coordinator.create(owner, createInput());
     await entered;
-    const replay = await second.create(owner, createInput());
-    expect(replay.state).toBe("creating");
     releaseFork();
     const created = await firstCreate;
+    const replay = await second.create(owner, createInput());
+    expect(replay.state).toBe("running");
     expect(f.port.calls.fork).toBe(1);
 
     let cancelEntered!: () => void;
@@ -420,7 +443,9 @@ describe("SideThread Hub contract", () => {
     expect(concurrent.state).toBe("running");
     expect(f.port.calls.cancel).toBe(1);
     releaseCancel();
-    expect((await firstCancel).state).toBe("cancelled");
+    expect((await firstCancel).state).toBe("running");
+    const cancelledAttempt = created.attempts[0];
+    f.port.emit({ sideChatId: created.sideChatId, attemptId: cancelledAttempt.attemptId, threadId: created.threadId!, turnId: cancelledAttempt.turnId!, status: "interrupted" });
 
     let archiveEntered!: () => void;
     const archiveStarted = new Promise<void>(
@@ -627,7 +652,7 @@ describe("SideThread Hub contract", () => {
     expect(reopened.list(stranger)).toHaveLength(0);
   });
 
-  test("response loss is durable ambiguous and reconciles without a second start RPC", async () => {
+  test("response loss remains ambiguous under the same stable start operation", async () => {
     const port = new FakePort();
     let accepted: Parameters<SideThreadExecutionPort["start"]>[0] | undefined;
     port.start = async (input) => {
@@ -658,11 +683,11 @@ describe("SideThread Hub contract", () => {
       state: "ambiguous",
       errorCode: "SIDE_THREAD_RESPONSE_LOST",
     });
-    expect(await f.coordinator.create(owner, createInput())).toMatchObject({
+    await expect(f.coordinator.create(owner, createInput())).rejects.toMatchObject({
+      code: "SIDE_THREAD_AMBIGUOUS",
       sideChatId: ambiguous.sideChatId,
-      state: "ambiguous",
     });
-    expect(port.calls).toMatchObject({ fork: 1, start: 1 });
+    expect(port.calls).toMatchObject({ fork: 1, start: 2 });
 
     f.coordinator.close();
     const reopened = new SideThreadCoordinator(f.store, port, {
@@ -689,13 +714,13 @@ describe("SideThread Hub contract", () => {
     expect(
       reconciled.operations.find((operation) => operation.kind === "start"),
     ).toMatchObject({ state: "completed", turnId: "turn_authoritative" });
-    expect(port.calls.start).toBe(1);
+    expect(port.calls.start).toBe(2);
     expect(
       JSON.stringify(reopened.listEvents(owner, ambiguous.sideChatId)),
     ).not.toContain("secret transport detail");
   });
 
-  test("ambiguous cancel/archive/purge keep stable claims and never issue a second RPC", async () => {
+  test("ambiguous cancel/archive/purge replay the same stable operation identity", async () => {
     const lose = () =>
       Object.assign(new Error("accepted but ACK lost"), {
         code: "SIDE_THREAD_RESPONSE_LOST",
@@ -728,7 +753,7 @@ describe("SideThread Hub contract", () => {
       code: "SIDE_THREAD_AMBIGUOUS",
       operationId: cancelOperationId,
     });
-    expect(cancelPort.calls.cancel).toBe(1);
+    expect(cancelPort.calls.cancel).toBe(2);
 
     for (const action of ["archive", "purge"] as const) {
       const port = new FakePort();
@@ -767,7 +792,7 @@ describe("SideThread Hub contract", () => {
         code: "SIDE_THREAD_AMBIGUOUS",
         operationId,
       });
-      expect(port.calls[action]).toBe(1);
+      expect(port.calls[action]).toBe(2);
     }
   });
 });
@@ -919,6 +944,10 @@ describe("SideThread HTTP contract", () => {
         coordinator: f.coordinator,
       });
       expect(response?.status).toBe(200);
+      if (action === "cancel") {
+        const attempt = record.attempts[0];
+        f.port.emit({ sideChatId: record.sideChatId, attemptId: attempt.attemptId, threadId: record.threadId!, turnId: attempt.turnId!, status: "interrupted" });
+      }
     }
     const hydrated = f.coordinator.get(owner, record.sideChatId);
     expect(

package/src/side-thread.ts

@@ -770,6 +770,12 @@ export class SideThreadCoordinator {
     if (existing) {
       if (existing.fingerprint !== fingerprint)
         throw conflict("idempotency key reused with different create payload");
+      if (this.createNeedsReconciliation(existing.record)) {
+        return this.singleFlight(
+          `create:${actor.userId}:${input.requestKey}`,
+          () => this.reconcileCreate(actor, input, attachments, fingerprint),
+        );
+      }
       return existing.record;
     }
     return this.singleFlight(
@@ -781,6 +787,8 @@ export class SideThreadCoordinator {
             throw conflict(
               "idempotency key reused with different create payload",
             );
+          if (this.createNeedsReconciliation(replay.record))
+            return this.reconcileCreate(actor, input, attachments, fingerprint);
           return replay.record;
         }
         const capability = await this.assertCapability(
@@ -880,7 +888,7 @@ export class SideThreadCoordinator {
             throw runtimeProtocol(
               "runtime returned source thread as side thread",
             );
-          this.store.db.transaction(() => {
+          this.applyRuntimeReceipt(() => {
             const t = this.now();
             this.store.db.run(
               "UPDATE side_chats SET derived_thread_id=?1,updated_at=?2 WHERE side_chat_id=?3 AND state='creating'",
@@ -921,16 +929,18 @@ export class SideThreadCoordinator {
             attachments,
           });
           requireRuntimeIdentity(started.turnId, "turnId");
-          this.store.db.transaction(() => {
+          const attemptBeforeApply = this.store.db.get<any>(
+            "SELECT state,turn_id FROM side_chat_attempts WHERE attempt_id=?1",
+            attemptId,
+          );
+          if (!attemptBeforeApply) throw conflict("attempt disappeared during start");
+          if (attemptBeforeApply.turn_id && attemptBeforeApply.turn_id !== started.turnId)
+            throw runtimeProtocol("runtime turn identity changed during start");
+          this.applyRuntimeReceipt(() => {
             const attempt = this.store.db.get<any>(
               "SELECT state,turn_id FROM side_chat_attempts WHERE attempt_id=?1",
               attemptId,
             );
-            if (!attempt) throw conflict("attempt disappeared during start");
-            if (attempt.turn_id && attempt.turn_id !== started.turnId)
-              throw runtimeProtocol(
-                "runtime turn identity changed during start",
-              );
             this.settleOperation(startOperationId, "completed", {
               threadId: forked.threadId,
               turnId: started.turnId,
@@ -964,10 +974,7 @@ export class SideThreadCoordinator {
             this.markAmbiguous(sideChatId, attemptId, activeOperationId, error);
             throw ambiguousError(activeOperationId, sideChatId, attemptId);
           }
-          this.settleOperation(activeOperationId, "failed", {
-            errorCode: auditErrorReason(error),
-          });
-          this.failStarting(sideChatId, attemptId, error);
+          this.failStarting(sideChatId, attemptId, error, activeOperationId);
           throw normalizePortError(error);
         }
         return this.mustOwned(sideChatId, actor);
@@ -975,6 +982,132 @@ export class SideThreadCoordinator {
     );
   }
 
+  /**
+   * Resume the stable fork/start operations after an ACK arrived outside the
+   * request window.  All identity needed to resume lives in SQLite; calling
+   * create again from another process therefore consumes the durable receipt
+   * instead of issuing a second native operation.
+   */
+  private async reconcileCreate(
+    actor: SideThreadActor,
+    input: CreateInput,
+    attachments: SideThreadAttachmentRef[],
+    fingerprint: string,
+  ): Promise<SideThreadRecord> {
+    const found = this.store.getByCreateKey(actor, input.requestKey);
+    if (!found) throw conflict("create record disappeared during reconciliation");
+    if (found.fingerprint !== fingerprint)
+      throw conflict("idempotency key reused with different create payload");
+    const sideChatId = found.record.sideChatId;
+    const attemptId = found.record.activeAttemptId;
+    if (!attemptId) throw conflict("create attempt disappeared during reconciliation");
+    const forkOperationId = stableOperationId(sideChatId, "fork", input.requestKey);
+    const startOperationId = stableOperationId(sideChatId, "start", input.requestKey);
+    let activeOperationId = forkOperationId;
+    try {
+      this.applyRuntimeReceipt(() => {
+        const at = this.now();
+        this.store.db.run(
+          "UPDATE side_chats SET state='reconciling',updated_at=?1 WHERE side_chat_id=?2 AND state IN ('creating','ambiguous')",
+          [at, sideChatId],
+        );
+        this.store.db.run(
+          "UPDATE side_chat_attempts SET state='reconciling',updated_at=?1 WHERE attempt_id=?2 AND state IN ('starting','ambiguous')",
+          [at, attemptId],
+        );
+        this.store.db.run(
+          "UPDATE side_chat_operations SET state='reconciling',updated_at=?1 WHERE operation_id=?2 AND state='ambiguous'",
+          [at, forkOperationId],
+        );
+      });
+      const forkOp = this.store.db.get<any>(
+        "SELECT state,thread_id FROM side_chat_operations WHERE operation_id=?1",
+        forkOperationId,
+      );
+      let threadId = forkOp?.state === "completed" ? forkOp.thread_id : undefined;
+      if (!threadId) {
+        const forked = await this.port.fork({
+          operationId: forkOperationId,
+          requestKey: input.requestKey,
+          sideChatId,
+          nodeId: input.nodeId,
+          sourceThreadId: input.sourceThreadId,
+          boundary: input.boundary,
+        });
+        threadId = forked.threadId;
+      }
+      requireRuntimeIdentity(threadId, "threadId");
+      if (threadId === input.sourceThreadId)
+        throw runtimeProtocol("runtime returned source thread as side thread");
+      this.applyRuntimeReceipt(() => {
+        const at = this.now();
+        this.settleOperation(forkOperationId, "completed", { threadId });
+        this.store.db.run(
+          "UPDATE side_chats SET derived_thread_id=?1,updated_at=?2 WHERE side_chat_id=?3 AND state IN ('creating','ambiguous','reconciling')",
+          [threadId, at, sideChatId],
+        );
+        this.store.db.run(
+          "UPDATE side_chat_attempts SET thread_id=?1,updated_at=?2 WHERE attempt_id=?3 AND state IN ('starting','ambiguous','reconciling')",
+          [threadId, at, attemptId],
+        );
+        const existingStart = this.store.db.get<any>(
+          "SELECT operation_id FROM side_chat_operations WHERE operation_id=?1",
+          startOperationId,
+        );
+        if (!existingStart)
+          this.insertOperation({ operationId: startOperationId, sideChatId, attemptId, kind: "start", requestKey: input.requestKey, fingerprint, threadId, at });
+        else
+          this.store.db.run(
+            "UPDATE side_chat_operations SET state='reconciling',updated_at=?1 WHERE operation_id=?2 AND state='ambiguous'",
+            [at, startOperationId],
+          );
+      });
+      activeOperationId = startOperationId;
+      const startOp = this.store.db.get<any>(
+        "SELECT state,turn_id FROM side_chat_operations WHERE operation_id=?1",
+        startOperationId,
+      );
+      let turnId = startOp?.state === "completed" ? startOp.turn_id : undefined;
+      if (!turnId) {
+        const started = await this.port.start({ operationId: startOperationId, requestKey: input.requestKey, sideChatId, attemptId, nodeId: input.nodeId, threadId, prompt: input.prompt, attachments });
+        turnId = started.turnId;
+      }
+      requireRuntimeIdentity(turnId, "turnId");
+      this.applyRuntimeReceipt(() => {
+        const at = this.now();
+        this.settleOperation(startOperationId, "completed", { threadId, turnId });
+        this.store.db.run(
+          "UPDATE side_chat_attempts SET state='running',thread_id=?1,turn_id=?2,updated_at=?3 WHERE attempt_id=?4 AND state IN ('starting','ambiguous','reconciling')",
+          [threadId, turnId, at, attemptId],
+        );
+        this.store.db.run(
+          "UPDATE side_chats SET state='running',derived_thread_id=?1,updated_at=?2 WHERE side_chat_id=?3 AND active_attempt_id=?4 AND state IN ('creating','ambiguous','reconciling')",
+          [threadId, at, sideChatId, attemptId],
+        );
+      });
+      return this.mustOwned(sideChatId, actor);
+    } catch (error) {
+      if (isAmbiguousRuntimeError(error)) {
+        if (this.operationState(activeOperationId) === "completed")
+          return this.mustOwned(sideChatId, actor);
+        this.markAmbiguous(sideChatId, attemptId, activeOperationId, error);
+        throw ambiguousError(activeOperationId, sideChatId, attemptId);
+      }
+      this.failStarting(sideChatId, attemptId, error, activeOperationId);
+      throw normalizePortError(error);
+    }
+  }
+
+  private createNeedsReconciliation(record: SideThreadRecord): boolean {
+    if (["creating", "ambiguous", "reconciling"].includes(record.state)) return true;
+    const active = record.attempts.find((attempt) => attempt.attemptId === record.activeAttemptId);
+    if (active && ["starting", "ambiguous", "reconciling"].includes(active.state)) return true;
+    return record.operations.some((operation) =>
+      (operation.kind === "fork" || operation.kind === "start") &&
+      ["pending", "ambiguous", "reconciling"].includes(operation.state),
+    );
+  }
+
   get(actor: SideThreadActor, sideChatId: string): SideThreadRecord {
     this.assertEnabled();
     this.assertActor(actor);
@@ -1042,19 +1175,35 @@ export class SideThreadCoordinator {
           operation_id: string;
           attempt_id: string | null;
           state: SideThreadOperationRecord["state"];
+          error_code: string | null;
         }>(
-          "SELECT operation_id,attempt_id,state FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind='cancel' AND request_key=?2",
+          "SELECT operation_id,attempt_id,state,error_code FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind='cancel' AND request_key=?2",
           sideChatId,
           input.requestKey,
         );
         if (replay?.state === "completed" || replay?.state === "pending")
           return record;
-        if (replay?.state === "ambiguous" || replay?.state === "reconciling")
-          throw ambiguousError(
-            replay.operation_id,
-            sideChatId,
-            replay.attempt_id ?? undefined,
-          );
+        if (replay?.state === "failed") throw persistedOperationFailure(replay.error_code);
+        if (replay?.state === "ambiguous" || replay?.state === "reconciling") {
+          const attempt = record.attempts.find((a) => a.attemptId === replay.attempt_id);
+          if (!attempt?.threadId || !attempt.turnId) throw conflict("cancel ownership missing");
+          await this.reconcileLifecycleOperation({
+            sideChatId, attemptId: attempt.attemptId, operationId: replay.operation_id,
+            invoke: () => this.port.cancel({ operationId: replay.operation_id, sideChatId, attemptId: attempt.attemptId, nodeId: record.nodeId, threadId: attempt.threadId!, turnId: attempt.turnId! }),
+            receipt: () => ({ threadId: attempt.threadId, turnId: attempt.turnId }),
+            accepted: () => {
+              const t = this.now();
+              this.store.db.run("UPDATE side_chat_attempts SET state='running',updated_at=?1 WHERE attempt_id=?2 AND state IN ('ambiguous','reconciling')", [t, attempt.attemptId]);
+              this.store.db.run("UPDATE side_chats SET state='running',updated_at=?1 WHERE side_chat_id=?2 AND active_attempt_id=?3 AND state IN ('ambiguous','reconciling')", [t, sideChatId, attempt.attemptId]);
+            },
+            failed: () => {
+              const t = this.now();
+              this.store.db.run("UPDATE side_chat_attempts SET state='running',cancel_requested_at=NULL,updated_at=?1 WHERE attempt_id=?2 AND state IN ('ambiguous','reconciling')", [t, attempt.attemptId]);
+              this.store.db.run("UPDATE side_chats SET state='running',updated_at=?1 WHERE side_chat_id=?2 AND active_attempt_id=?3 AND state IN ('ambiguous','reconciling')", [t, sideChatId, attempt.attemptId]);
+            },
+          });
+          return this.mustOwned(sideChatId, actor);
+        }
         const attempt = record.attempts.find(
           (a) => a.attemptId === record.activeAttemptId,
         );
@@ -1141,27 +1290,8 @@ export class SideThreadCoordinator {
           throw normalizePortError(error);
         }
         this.store.db.transaction(() => {
-          const t = this.now();
-          const changed = this.store.db.run(
-            "UPDATE side_chat_attempts SET state='cancelled',updated_at=?1 WHERE attempt_id=?2 AND state='running' AND thread_id=?3 AND turn_id=?4",
-            [t, attempt.attemptId, attempt.threadId, attempt.turnId],
-          );
-          if (changed.changes > 0) {
-            this.store.db.run(
-              "UPDATE side_chats SET state='cancelled',active_attempt_id=NULL,updated_at=?1 WHERE side_chat_id=?2 AND active_attempt_id=?3",
-              [t, sideChatId, attempt.attemptId],
-            );
-            this.emitStored(
-              sideChatId,
-              attempt.attemptId,
-              attempt.threadId,
-              attempt.turnId,
-              "attempt.cancelled",
-              "cancelled",
-              undefined,
-              t,
-            );
-          }
+          // Command acceptance only proves that interrupt was accepted.  The
+          // authoritative terminal event owns the cancelled/completed race.
           this.settleOperation(prepared.operationId, "completed", {
             threadId: attempt.threadId,
             turnId: attempt.turnId,
@@ -1337,10 +1467,7 @@ export class SideThreadCoordinator {
             this.markAmbiguous(sideChatId, attemptId, startOperationId, error);
             throw ambiguousError(startOperationId, sideChatId, attemptId);
           }
-          this.settleOperation(startOperationId, "failed", {
-            errorCode: auditErrorReason(error),
-          });
-          this.failStarting(sideChatId, attemptId, error);
+          this.failStarting(sideChatId, attemptId, error, startOperationId);
           throw normalizePortError(error);
         }
         return this.mustOwned(sideChatId, actor);
@@ -1379,6 +1506,11 @@ export class SideThreadCoordinator {
         if (!r.threadId) throw conflict("side chat has no derived thread");
         if (r.state === "purged") return r;
         if (action === "archive" && r.state === "archived") return r;
+        const priorOperation = this.store.db.get<{ state: string; error_code: string | null }>(
+          "SELECT state,error_code FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind=?2 AND request_key=?3",
+          sideChatId, action, input.requestKey,
+        );
+        if (priorOperation?.state === "failed") throw persistedOperationFailure(priorOperation.error_code);
         await this.assertCapability(r.nodeId);
         const prepared = this.prepareStableOperation({
           sideChatId,
@@ -1388,8 +1520,18 @@ export class SideThreadCoordinator {
           threadId: r.threadId,
         });
         if (prepared.state === "completed") return r;
-        if (prepared.state === "ambiguous" || prepared.state === "reconciling")
-          throw ambiguousError(prepared.operationId, sideChatId);
+        if (prepared.state === "ambiguous" || prepared.state === "reconciling") {
+          await this.reconcileLifecycleOperation({
+            sideChatId, operationId: prepared.operationId,
+            invoke: () => action === "archive"
+              ? this.port.archive({ operationId: prepared.operationId, sideChatId, nodeId: r.nodeId, threadId: r.threadId! })
+              : this.port.purge({ operationId: prepared.operationId, sideChatId, nodeId: r.nodeId, threadId: r.threadId! }),
+            receipt: () => ({ threadId: r.threadId }),
+            accepted: () => this.applyLifecycleAccepted(sideChatId, action, prepared.operationId, r.threadId!),
+            failed: () => this.store.db.run("UPDATE side_chats SET state='failed',lifecycle_operation=NULL,updated_at=?1 WHERE side_chat_id=?2 AND state IN ('ambiguous','reconciling')", [this.now(), sideChatId]),
+          });
+          return this.mustOwned(sideChatId, actor);
+        }
         if (!prepared.callable)
           throw conflict("side chat lifecycle operation already in progress");
         const claim = this.store.db.run(
@@ -1536,21 +1678,33 @@ export class SideThreadCoordinator {
             const operation = this.store.db.get<{
               operation_id: string;
               state: string;
+              error_code: string | null;
             }>(
-              "SELECT operation_id,state FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind='bring-back' AND request_key=?2",
+              "SELECT operation_id,state,error_code FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind='bring-back' AND request_key=?2",
               sideChatId,
               input.requestKey,
             );
-            if (
-              operation &&
-              (operation.state === "ambiguous" ||
-                operation.state === "reconciling")
-            )
-              throw ambiguousError(
-                operation.operation_id,
-                sideChatId,
-                attempt.attemptId,
-              );
+            if (operation && (operation.state === "ambiguous" || operation.state === "reconciling")) {
+              const destinationTurnId = await this.reconcileLifecycleOperation({
+                sideChatId, attemptId: attempt.attemptId, operationId: operation.operation_id,
+                invoke: async () => (await this.port.bringBack({ operationId: operation.operation_id, sideChatId, attemptId: attempt.attemptId, nodeId: r.nodeId, sourceThreadId: attempt.threadId!, sourceTurnId: attempt.turnId!, destinationThreadId: input.destinationThreadId, requestKey: input.requestKey, text: attempt.result! })).destinationTurnId,
+                receipt: (turn) => ({ threadId: input.destinationThreadId, turnId: turn }),
+                accepted: (turn) => {
+                  requireRuntimeIdentity(turn, "destinationTurnId");
+                  const now = this.now();
+                  this.store.db.run("UPDATE side_chat_bring_backs SET state='completed',destination_turn_id=?1,error_text=NULL,updated_at=?2,completed_at=?2 WHERE bring_back_id=?3 AND state IN ('starting','ambiguous','reconciling')", [turn, now, old.bring_back_id]);
+                  this.store.db.run("UPDATE side_chats SET state='completed',updated_at=?1 WHERE side_chat_id=?2 AND state IN ('ambiguous','reconciling')", [now, sideChatId]);
+                  this.emitStored(sideChatId, attempt.attemptId, attempt.threadId, attempt.turnId, "side_chat.brought_back", "completed", undefined, now);
+                },
+                failed: (error) => {
+                  const now = this.now();
+                  this.store.db.run("UPDATE side_chat_bring_backs SET state='failed',error_text=?1,updated_at=?2 WHERE bring_back_id=?3 AND state IN ('starting','ambiguous','reconciling')", [safeReason(error instanceof Error ? error.message : String(error)), now, old.bring_back_id]);
+                  this.store.db.run("UPDATE side_chats SET state='completed',updated_at=?1 WHERE side_chat_id=?2 AND state IN ('ambiguous','reconciling')", [now, sideChatId]);
+                },
+              });
+              return { bringBackId: old.bring_back_id, destinationTurnId };
+            }
+            if (operation?.state === "failed") throw persistedOperationFailure(operation.error_code);
             throw conflict("bring-back is already in progress or failed");
           }
           return {
@@ -1723,6 +1877,84 @@ export class SideThreadCoordinator {
     );
   }
 
+  private applyRuntimeReceipt(apply: () => void): void {
+    try {
+      this.store.db.transaction(apply);
+    } catch {
+      // The runtime receipt remains authoritative and durable; only the local
+      // projection failed. Callers mark the stable operation ambiguous so a
+      // restart can consume the same receipt without another native command.
+      throw new SideThreadError(
+        "SIDE_THREAD_AMBIGUOUS",
+        "runtime receipt accepted; local apply requires reconciliation",
+        202,
+      );
+    }
+  }
+
+  private async reconcileLifecycleOperation<T>(input: {
+    sideChatId: string;
+    attemptId?: string;
+    operationId: string;
+    invoke: () => Promise<T>;
+    receipt: (value: T) => { threadId?: string; turnId?: string };
+    accepted: (value: T) => void;
+    failed: (error: unknown) => void;
+  }): Promise<T> {
+    this.store.db.run(
+      "UPDATE side_chat_operations SET state='reconciling',updated_at=?1 WHERE operation_id=?2 AND state='ambiguous'",
+      [this.now(), input.operationId],
+    );
+    let value: T;
+    try {
+      value = await input.invoke();
+    } catch (error) {
+      if (isAmbiguousRuntimeError(error)) {
+        this.markAmbiguous(input.sideChatId, input.attemptId, input.operationId, error);
+        throw ambiguousError(input.operationId, input.sideChatId, input.attemptId);
+      }
+      try {
+        this.store.db.transaction(() => {
+          const won = this.store.db.run(
+            "UPDATE side_chat_operations SET state='failed',error_code=?1,updated_at=?2 WHERE operation_id=?3 AND state IN ('ambiguous','reconciling')",
+            [auditErrorReason(error), this.now(), input.operationId],
+          );
+          if (won.changes === 1) input.failed(error);
+        });
+      } catch {
+        this.markAmbiguous(input.sideChatId, input.attemptId, input.operationId, { code: "SIDE_THREAD_LOCAL_APPLY_FAILED" });
+        throw ambiguousError(input.operationId, input.sideChatId, input.attemptId);
+      }
+      throw normalizePortError(error);
+    }
+    try {
+      this.store.db.transaction(() => {
+        const receipt = input.receipt(value);
+        const won = this.store.db.run(
+          "UPDATE side_chat_operations SET state='completed',thread_id=COALESCE(?1,thread_id),turn_id=COALESCE(?2,turn_id),error_code=NULL,updated_at=?3 WHERE operation_id=?4 AND state IN ('ambiguous','reconciling')",
+          [receipt.threadId ?? null, receipt.turnId ?? null, this.now(), input.operationId],
+        );
+        if (won.changes === 1) input.accepted(value);
+      });
+      return value;
+    } catch {
+      this.markAmbiguous(input.sideChatId, input.attemptId, input.operationId, { code: "SIDE_THREAD_LOCAL_APPLY_FAILED" });
+      throw ambiguousError(input.operationId, input.sideChatId, input.attemptId);
+    }
+  }
+
+  private applyLifecycleAccepted(sideChatId: string, action: "archive" | "purge", operationId: string, threadId: string): void {
+    const t = this.now();
+    if (action === "purge") {
+      this.store.db.run("UPDATE side_chats SET state='purged',question_text='',attachments_json='[]',lifecycle_operation=NULL,updated_at=?1,purged_at=?1 WHERE side_chat_id=?2 AND active_attempt_id IS NULL", [t, sideChatId]);
+      this.store.db.run("UPDATE side_chat_attempts SET result_text=NULL,error_text=NULL,attachments_json='[]',updated_at=?1 WHERE side_chat_id=?2", [t, sideChatId]);
+      this.store.db.run("UPDATE side_chat_bring_backs SET error_text=NULL,updated_at=?1 WHERE side_chat_id=?2", [t, sideChatId]);
+    } else {
+      this.store.db.run("UPDATE side_chats SET state='archived',lifecycle_operation=NULL,updated_at=?1,archived_at=?1 WHERE side_chat_id=?2 AND active_attempt_id IS NULL", [t, sideChatId]);
+    }
+    this.emitStored(sideChatId, undefined, threadId, undefined, `side_chat.${action === "archive" ? "archived" : "purged"}`, action === "archive" ? "archived" : "purged", undefined, t);
+  }
+
   listEvents(
     actor: SideThreadActor,
     sideChatId: string,
@@ -1983,14 +2215,19 @@ export class SideThreadCoordinator {
     sideChatId: string,
     attemptId: string,
     error: unknown,
+    operationId?: string,
   ): void {
     const t = this.now(),
       reason = safeReason(
         error instanceof Error ? error.message : String(error),
       );
     this.store.db.transaction(() => {
+      if (operationId)
+        this.settleOperation(operationId, "failed", {
+          errorCode: auditErrorReason(error),
+        });
       const changed = this.store.db.run(
-        "UPDATE side_chat_attempts SET state='failed',error_text=?1,updated_at=?2 WHERE attempt_id=?3 AND state='starting'",
+        "UPDATE side_chat_attempts SET state='failed',error_text=?1,updated_at=?2 WHERE attempt_id=?3 AND state IN ('starting','ambiguous','reconciling')",
         [reason, t, attemptId],
       );
       if (changed.changes > 0) {
@@ -2038,7 +2275,7 @@ export class SideThreadCoordinator {
       "SELECT event_id FROM side_chat_events WHERE side_chat_id=?1 ORDER BY event_id DESC LIMIT 1",
       sideChatId,
     );
-    this.emitter.emit(`side:${sideChatId}`, {
+    const event = {
       eventId: row?.event_id ?? 0,
       sideChatId,
       attemptId,
@@ -2048,7 +2285,19 @@ export class SideThreadCoordinator {
       state,
       reason: safeReason(reason),
       createdAt: at,
-    } satisfies SideThreadEventRecord);
+    } satisfies SideThreadEventRecord;
+    // Fanout is deliberately deferred until the current synchronous SQLite
+    // transaction has committed. Observers are never part of durable truth:
+    // one throwing listener cannot roll back state or starve another listener.
+    queueMicrotask(() => {
+      for (const listener of this.emitter.listeners(`side:${sideChatId}`)) {
+        try {
+          listener(event);
+        } catch {
+          // Durable side_chat_events + cursor replay are authoritative.
+        }
+      }
+    });
   }
   private mustOwned(
     sideChatId: string,
@@ -2239,3 +2488,8 @@ function normalizePortError(error: unknown): SideThreadError {
     502,
   );
 }
+function persistedOperationFailure(code: string | null | undefined): SideThreadError {
+  if (code === "SIDE_THREAD_UNSUPPORTED")
+    return new SideThreadError("SIDE_THREAD_UNSUPPORTED", "runtime operation is unsupported", 501);
+  return new SideThreadError(code === "SIDE_THREAD_CONFLICT" ? "SIDE_THREAD_CONFLICT" : "SIDE_THREAD_RUNTIME_ERROR", "runtime operation failed authoritatively", code === "SIDE_THREAD_CONFLICT" ? 409 : 502);
+}

package/src/tools.ts

@@ -526,6 +526,16 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         config_revision: z.number().int().min(0).optional(),
         config_update_capable: z.boolean().optional(),
         peer_reply_inbox_capable: z.literal(true).optional(),
+        side_thread_capability: z.object({
+          supported: z.boolean(),
+          runtime: z.string().max(64),
+          runtimeVersion: z.string().max(64),
+          topology: z.string().max(64),
+          evidenceRevision: z.string().max(100),
+          mode: z.literal("native-exact-fork").optional(),
+          exactBoundary: z.object({ through: z.boolean(), before: z.boolean() }).strict().optional(),
+          reason: z.enum(["runtime", "version", "topology", "experimental-api", "exact-boundary"]).optional(),
+        }).strict().optional(),
         // RFC-026 P2 / #338 — daemon role surfaced for hub /api/nodes
         // discovery (#337 extracts this field). "host_supervisor" =
         // anet daemon. Default-stripping zod would drop this otherwise.