@sleep2agi/commhub-server 0.9.0-preview.7 → 0.9.0-preview.70

package/src/side-thread-http.ts

@@ -0,0 +1,504 @@
+import {
+  SIDE_THREAD_API_ACTIONS,
+  SIDE_THREAD_API_ROOT,
+  SideThreadCoordinator,
+  SideThreadError,
+  type SideThreadActor,
+  type SideThreadRecord,
+} from "./side-thread.js";
+
+export interface SideThreadHttpContext {
+  req: Request;
+  url: URL;
+  actor: SideThreadActor | null;
+  coordinator: SideThreadCoordinator;
+  resolveCapabilityTarget?: (input: {
+    actor: SideThreadActor;
+    alias?: string;
+    nodeId?: string;
+    networkId?: string;
+  }) => { nodeId: string; networkId: string } | undefined;
+}
+
+export async function handleSideThreadHttpRequest(
+  ctx: SideThreadHttpContext,
+): Promise<Response | null> {
+  const root = ctx.url.pathname === SIDE_THREAD_API_ROOT;
+  const capabilityPath =
+    ctx.url.pathname === `${SIDE_THREAD_API_ROOT}/capability`;
+  const match = ctx.url.pathname.match(
+    new RegExp(
+      `^${SIDE_THREAD_API_ROOT}/([^/]+)(?:/(${SIDE_THREAD_API_ACTIONS.join("|")}))?$`,
+    ),
+  );
+  if (!root && !capabilityPath && !match) return null;
+  if (!ctx.coordinator.isEnabled())
+    return json({ ok: false, error: "SIDE_THREAD_DISABLED" }, 404);
+  if (!ctx.actor)
+    return json({ ok: false, error: "SIDE_THREAD_AUTH_REQUIRED" }, 401);
+
+  try {
+    if (capabilityPath) {
+      if (ctx.req.method !== "GET") return methodNotAllowed("GET");
+      const target = ctx.resolveCapabilityTarget?.({
+        actor: ctx.actor,
+        alias: query(ctx.url, "alias"),
+        nodeId: query(ctx.url, "nodeId", "node_id"),
+        networkId: query(ctx.url, "networkId", "network_id"),
+      });
+      if (!target)
+        throw new SideThreadError(
+          "SIDE_THREAD_NOT_FOUND",
+          "node not found",
+          404,
+        );
+      const sourceThreadId = requiredQueryIdentity(ctx.url, "sourceThreadId");
+      const boundaryKind = query(ctx.url, "boundaryKind");
+      const boundaryTurnId = requiredQueryIdentity(ctx.url, "boundaryTurnId");
+      if (boundaryKind !== "through" && boundaryKind !== "before")
+        throw new SideThreadError(
+          "SIDE_THREAD_INVALID_CONTEXT",
+          "boundaryKind must be through or before",
+          400,
+        );
+      const boundary = { kind: boundaryKind, turnId: boundaryTurnId } as const;
+      const capability = await ctx.coordinator.capability(
+        ctx.actor,
+        target.networkId,
+        target.nodeId,
+        boundary,
+      );
+      return json({
+        ok: true,
+        capability: serializeCapability(capability, {
+          networkId: target.networkId,
+          nodeId: target.nodeId,
+          sourceThreadId,
+          boundary,
+        }),
+      });
+    }
+    if (root && ctx.req.method === "GET") {
+      const rawLimit = ctx.url.searchParams.get("limit");
+      const limit = rawLimit === null ? undefined : parseLimit(rawLimit);
+      if (rawLimit !== null && limit === null)
+        throw new SideThreadError(
+          "SIDE_THREAD_INVALID_LIMIT",
+          "invalid list limit",
+          400,
+        );
+      const records = ctx.coordinator.list(ctx.actor, {
+        networkId: query(ctx.url, "networkId", "network_id"),
+        nodeId: query(ctx.url, "nodeId", "node_id"),
+        limit: limit ?? undefined,
+      });
+      return json({
+        ok: true,
+        sideThreads: records.map(serialize),
+        count: records.length,
+      });
+    }
+    if (root && ctx.req.method === "POST") {
+      const body = await requestJson(ctx.req);
+      const record = await ctx.coordinator.create(ctx.actor, {
+        requestKey: field(body, "requestKey", "request_key"),
+        networkId: field(body, "networkId", "network_id"),
+        nodeId: field(body, "nodeId", "node_id"),
+        sourceThreadId: field(body, "sourceThreadId", "source_thread_id"),
+        boundary: {
+          kind: body.boundary?.kind,
+          turnId: field(body.boundary, "turnId", "turn_id"),
+        },
+        prompt: field(body, "question", "prompt"),
+        attachments: mapAttachments(body.attachments),
+      });
+      return json({ ok: true, sideThread: serialize(record) }, 201);
+    }
+    if (root) return methodNotAllowed("GET, POST");
+
+    const sideChatId = decodeSegment(match![1]);
+    const action = match![2];
+    if (!action && ctx.req.method === "GET") {
+      return json({
+        ok: true,
+        sideThread: serialize(ctx.coordinator.get(ctx.actor, sideChatId)),
+      });
+    }
+    if (!action) return methodNotAllowed("GET");
+
+    if (action === "events" && ctx.req.method === "GET") {
+      // Authorize before opening a long-lived stream. A non-owner gets the
+      // same 404 as an unknown id and cannot infer another user's side chat.
+      ctx.coordinator.get(ctx.actor, sideChatId);
+      const headerCursor = ctx.req.headers.get("Last-Event-ID");
+      const queryCursor = ctx.url.searchParams.get("after");
+      const after = parseCursor(headerCursor ?? queryCursor);
+      if (after === null)
+        throw new SideThreadError(
+          "SIDE_THREAD_INVALID_CURSOR",
+          "invalid event cursor",
+          400,
+        );
+      return sideThreadEventStream(
+        ctx.coordinator,
+        ctx.actor,
+        sideChatId,
+        after,
+      );
+    }
+
+    if (ctx.req.method !== "POST") return methodNotAllowed("POST");
+    const body = await requestJson(ctx.req);
+    const requestKey = field(body, "requestKey", "request_key");
+    if (action === "cancel") {
+      return json({
+        ok: true,
+        sideThread: serialize(
+          await ctx.coordinator.cancel(ctx.actor, sideChatId, { requestKey }),
+        ),
+      });
+    }
+    if (action === "archive") {
+      return json({
+        ok: true,
+        sideThread: serialize(
+          await ctx.coordinator.archive(ctx.actor, sideChatId, { requestKey }),
+        ),
+      });
+    }
+    if (action === "purge") {
+      return json({
+        ok: true,
+        sideThread: serialize(
+          await ctx.coordinator.purge(ctx.actor, sideChatId, { requestKey }),
+        ),
+      });
+    }
+    if (action === "retry") {
+      return json({
+        ok: true,
+        sideThread: serialize(
+          await ctx.coordinator.retry(ctx.actor, sideChatId, {
+            requestKey,
+            prompt: field(body, "question", "prompt"),
+            attachments:
+              body.attachments === undefined
+                ? undefined
+                : mapAttachments(body.attachments),
+          }),
+        ),
+      });
+    }
+    const broughtBack = await ctx.coordinator.bringBack(ctx.actor, sideChatId, {
+      requestKey,
+      destinationThreadId: field(
+        body,
+        "destinationThreadId",
+        "destination_thread_id",
+      ),
+      attemptId: field(body, "attemptId", "attempt_id"),
+    });
+    return json({ ok: true, bringBack: broughtBack });
+  } catch (error) {
+    if (error instanceof SideThreadError) {
+      return json(
+        {
+          ok: false,
+          error: error.code,
+          message: error.message,
+          ...(error.operationId ? { operationId: error.operationId } : {}),
+          ...(error.sideChatId ? { sideThreadId: error.sideChatId } : {}),
+          ...(error.attemptId ? { attemptId: error.attemptId } : {}),
+        },
+        error.status,
+      );
+    }
+    return json({ ok: false, error: "SIDE_THREAD_INTERNAL_ERROR" }, 500);
+  }
+}
+
+function serialize(record: SideThreadRecord) {
+  const completedBringBackAttempts = new Set(
+    record.bringBacks
+      .filter((receipt) => receipt.state === "completed")
+      .map((receipt) => receipt.attemptId),
+  );
+  return {
+    sideThreadId: record.sideChatId,
+    requestKey: record.requestKey,
+    networkId: record.networkId,
+    nodeId: record.nodeId,
+    sourceThreadId: record.sourceThreadId,
+    question: record.question,
+    title: record.question.split(/\r?\n/, 1)[0].slice(0, 120),
+    boundary: { kind: record.boundary.kind, turnId: record.boundary.turnId },
+    threadId: record.threadId ?? null,
+    state: record.state,
+    activeAttemptId: record.activeAttemptId ?? null,
+    capability: {
+      runtime: record.runtime ?? null,
+      runtimeVersion: record.runtimeVersion ?? null,
+      topology: record.topology ?? null,
+      evidenceRevision: record.evidenceRevision ?? null,
+    },
+    attachments: record.attachments.map((a) => ({ fileId: a.fileId })),
+    attempts: record.attempts.map((a) => ({
+      attemptId: a.attemptId,
+      requestKey: a.requestKey,
+      parentAttemptId: a.parentAttemptId ?? null,
+      threadId: a.threadId ?? null,
+      turnId: a.turnId ?? null,
+      state: a.state,
+      result: a.result ?? null,
+      error: a.error ?? null,
+      attachments: a.attachments.map((attachment) => ({
+        fileId: attachment.fileId,
+      })),
+      broughtBack: completedBringBackAttempts.has(a.attemptId),
+      createdAt: a.createdAt,
+      updatedAt: a.updatedAt,
+    })),
+    bringBacks: record.bringBacks.map((receipt) => ({
+      bringBackId: receipt.bringBackId,
+      attemptId: receipt.attemptId,
+      requestKey: receipt.requestKey,
+      destinationThreadId: receipt.destinationThreadId,
+      destinationTurnId: receipt.destinationTurnId ?? null,
+      state: receipt.state,
+      broughtBack: receipt.state === "completed",
+      createdAt: receipt.createdAt,
+      updatedAt: receipt.updatedAt,
+      completedAt: receipt.completedAt ?? null,
+    })),
+    operations: record.operations.map((operation) => ({
+      operationId: operation.operationId,
+      attemptId: operation.attemptId ?? null,
+      kind: operation.kind,
+      requestKey: operation.requestKey,
+      state: operation.state,
+      threadId: operation.threadId ?? null,
+      turnId: operation.turnId ?? null,
+      errorCode: operation.errorCode ?? null,
+      createdAt: operation.createdAt,
+      updatedAt: operation.updatedAt,
+    })),
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+  };
+}
+
+function serializeCapability(
+  capability: Awaited<ReturnType<SideThreadCoordinator["capability"]>>,
+  context: {
+    networkId: string;
+    nodeId: string;
+    sourceThreadId: string;
+    boundary: { kind: "through" | "before"; turnId: string };
+  },
+) {
+  return {
+    enabled: true,
+    supported: capability.supported,
+    mode: capability.mode ?? null,
+    runtime: capability.runtime ?? null,
+    runtimeVersion: capability.runtimeVersion ?? null,
+    topology: capability.topology ?? null,
+    evidenceRevision: capability.evidenceRevision ?? null,
+    exactBoundary: capability.exactBoundary ?? null,
+    reason: capability.reason ?? null,
+    context: capability.supported ? context : null,
+  };
+}
+
+function sideThreadEventStream(
+  coordinator: SideThreadCoordinator,
+  actor: SideThreadActor,
+  sideChatId: string,
+  after: number,
+): Response {
+  const encoder = new TextEncoder();
+  let unsubscribe = () => {};
+  let heartbeat: ReturnType<typeof setInterval> | undefined;
+  let closed = false;
+  const cleanup = () => {
+    if (closed) return;
+    closed = true;
+    unsubscribe();
+    if (heartbeat) clearInterval(heartbeat);
+  };
+  const stream = new ReadableStream<Uint8Array>(
+    {
+      start(controller) {
+        const send = (
+          event: ReturnType<SideThreadCoordinator["listEvents"]>[number],
+        ) => {
+          if (closed) return;
+          if ((controller.desiredSize ?? -262_145) < -262_144) {
+            cleanup();
+            try {
+              controller.close();
+            } catch {}
+            return;
+          }
+          try {
+            controller.enqueue(
+              encoder.encode(
+                `id: ${event.eventId}\nevent: side_thread\ndata: ${JSON.stringify(serializeEvent(event))}\n\n`,
+              ),
+            );
+          } catch {
+            cleanup();
+          }
+        };
+        for (const event of coordinator.listEvents(actor, sideChatId, after))
+          send(event);
+        if (closed) return;
+        unsubscribe = coordinator.subscribe(sideChatId, send);
+        heartbeat = setInterval(() => {
+          if ((controller.desiredSize ?? -262_145) < -262_144) {
+            cleanup();
+            try {
+              controller.close();
+            } catch {}
+            return;
+          }
+          try {
+            controller.enqueue(encoder.encode(": keepalive\n\n"));
+          } catch {
+            cleanup();
+          }
+        }, 30_000);
+      },
+      cancel() {
+        cleanup();
+      },
+    },
+    { highWaterMark: 64 * 1024, size: (chunk) => chunk.byteLength },
+  );
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      "X-Accel-Buffering": "no",
+    },
+  });
+}
+
+function serializeEvent(
+  event: ReturnType<SideThreadCoordinator["listEvents"]>[number],
+) {
+  return {
+    eventId: event.eventId,
+    sideThreadId: event.sideChatId,
+    attemptId: event.attemptId ?? null,
+    threadId: event.threadId ?? null,
+    turnId: event.turnId ?? null,
+    type: event.type,
+    state: event.state ?? null,
+    reason: event.reason ?? null,
+    createdAt: event.createdAt,
+  };
+}
+
+function mapAttachments(value: unknown): Array<{ fileId: string }> | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value))
+    throw new SideThreadError(
+      "SIDE_THREAD_CONFLICT",
+      "invalid attachments",
+      409,
+    );
+  return value.map((entry: any) => {
+    if (!entry || typeof entry !== "object")
+      return { fileId: undefined as any };
+    // Do not forward path/url/name fields even temporarily. The coordinator
+    // rejects the original shape when extra keys are present.
+    const allowed = Object.keys(entry).every(
+      (key) => key === "fileId" || key === "file_id",
+    );
+    return allowed
+      ? { fileId: field(entry, "fileId", "file_id") }
+      : { ...(entry as any), fileId: field(entry, "fileId", "file_id") };
+  });
+}
+
+function field(value: any, camel: string, legacy: string): any {
+  return value?.[camel] ?? value?.[legacy];
+}
+
+function query(url: URL, camel: string, legacy?: string): string | undefined {
+  return (
+    url.searchParams.get(camel) ??
+    (legacy ? url.searchParams.get(legacy) : null) ??
+    undefined
+  );
+}
+
+function requiredQueryIdentity(url: URL, name: string): string {
+  const value = query(url, name);
+  if (!value || value.length > 512 || /[\r\n\0]/.test(value))
+    throw new SideThreadError(
+      "SIDE_THREAD_INVALID_CONTEXT",
+      `invalid ${name}`,
+      400,
+    );
+  return value;
+}
+
+async function requestJson(req: Request): Promise<any> {
+  const contentType = req.headers.get("Content-Type") ?? "";
+  if (!/^application\/json(?:;|$)/i.test(contentType)) {
+    throw new SideThreadError(
+      "SIDE_THREAD_INVALID_BODY",
+      "application/json required",
+      415,
+    );
+  }
+  try {
+    const value = await req.json();
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new SideThreadError(
+        "SIDE_THREAD_INVALID_BODY",
+        "JSON object required",
+        400,
+      );
+    }
+    return value;
+  } catch {
+    throw new SideThreadError("SIDE_THREAD_INVALID_BODY", "invalid JSON", 400);
+  }
+}
+function decodeSegment(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    throw new SideThreadError(
+      "SIDE_THREAD_NOT_FOUND",
+      "side chat not found",
+      404,
+    );
+  }
+}
+function parseCursor(value: string | null): number | null {
+  if (value === null || value === "") return 0;
+  if (!/^\d+$/.test(value)) return null;
+  const n = Number(value);
+  return Number.isSafeInteger(n) ? n : null;
+}
+function parseLimit(value: string): number | null {
+  if (!/^\d+$/.test(value)) return null;
+  const n = Number(value);
+  return Number.isSafeInteger(n) && n >= 1 && n <= 100 ? n : null;
+}
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, {
+    status,
+    headers: { "Cache-Control": "no-store" },
+  });
+}
+function methodNotAllowed(allow: string): Response {
+  return Response.json(
+    { ok: false, error: "SIDE_THREAD_METHOD_NOT_ALLOWED" },
+    { status: 405, headers: { Allow: allow } },
+  );
+}

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 };
+}