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

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(