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

package/src/opencode-v2-catalog.test.ts

@@ -0,0 +1,268 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import "./require-explicit-test-db.js";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import {
+  ackOpenCodeCatalog,
+  expireOpenCodeCatalogForTest,
+  getOpenCodeCatalogResult,
+  queueOpenCodeCatalogRead,
+  resetOpenCodeCatalogForTest,
+  takeOpenCodeCatalogRequest,
+} from "./opencode-v2-catalog.js";
+import { readOwnedOpenCodeV2Catalog } from "../../agent-node/src/runtime/opencode-v2-catalog-daemon.ts";
+import { readOpenCodeV2CatalogEndpoint, writeOpenCodeV2CatalogEndpoint } from "../../agent-node/src/runtime/opencode-v2-catalog-endpoint.ts";
+
+const NET = "net_oc_catalog";
+const OTHER = "net_oc_catalog_other";
+const USER = "u_oc_catalog";
+const VIEWER = "u_oc_catalog_viewer";
+const OUTSIDER = "u_oc_catalog_out";
+const DAEMON = "node_oc_daemon";
+const DAEMON_ALIAS = "oc-daemon";
+const DAEMON_TOK = "tok_oc_daemon";
+const V2_REQ = "cr_ocv2child";
+const V2 = "node_ocv2child";
+const V1 = "node_ocv1child";
+const UNSAFE = "node_ocunsafechild";
+const NULLDIR = "node_ocnullchild";
+const PROJECT = resolve(mkdtempSync(join(tmpdir(), "oc-hub-proj-")));
+
+function cleanup() {
+  resetOpenCodeCatalogForTest();
+  for (const net of [NET, OTHER]) {
+    for (const table of ["node_create_requests", "audit_log", "nodes", "sessions", "api_tokens", "network_members"]) {
+      try { db.run(`DELETE FROM ${table} WHERE network_id = ?1`, [net]); } catch {}
+    }
+    try { db.run("DELETE FROM networks WHERE network_id = ?1", [net]); } catch {}
+  }
+  for (const user of [USER, VIEWER, OUTSIDER]) {
+    try { db.run("DELETE FROM users WHERE user_id = ?1", [user]); } catch {}
+  }
+}
+beforeEach(cleanup);
+afterAll(() => { cleanup(); rmSync(PROJECT, { recursive: true, force: true }); });
+
+function userRow(id: string) {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?1, 'x', 'user', datetime('now'))`, [id]);
+}
+function member(id: string, net: string, role: string) {
+  db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, ?3, datetime('now'))`, [id, net, role]);
+}
+function node(id: string, alias: string, snapshot: unknown) {
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, config_snapshot, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?2, ?3, ?4, 'host-x', datetime('now'), datetime('now'), 'active')`,
+    [id, alias, NET, JSON.stringify(snapshot)],
+  );
+}
+function created(requestId: string, nodeId: string, flags: unknown, workdir: string | null) {
+  node(nodeId, nodeId, {});
+  db.run(
+    `INSERT INTO node_create_requests
+      (request_id, daemon_node_id, child_name, network_id, runtime, model, flags_json, env_keys, status, created_at, created_by_token, workdir)
+     VALUES (?1, ?2, ?3, ?4, 'opencode-cli', 'fixture/fixture-model', ?5, '[]', 'succeeded', ?6, 'tok', ?7)`,
+    [requestId, DAEMON, nodeId, NET, JSON.stringify(flags), Date.now(), workdir],
+  );
+}
+
+function seed() {
+  userRow(USER); userRow(VIEWER); userRow(OUTSIDER);
+  db.run(`INSERT OR REPLACE INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET, USER]);
+  db.run(`INSERT OR REPLACE INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [OTHER, OUTSIDER]);
+  member(USER, NET, "admin");
+  member(VIEWER, NET, "viewer");
+  member(OUTSIDER, OTHER, "admin");
+  node(DAEMON, DAEMON_ALIAS, { role: "host_supervisor" });
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+     VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [DAEMON_TOK, USER, NET, `node:${DAEMON_ALIAS}`, `hash_${DAEMON_TOK}`],
+  );
+  created(V2_REQ, V2, { opencodeGeneration: "v2", opencodeUnsafeTools: true }, PROJECT);
+  created("cr_ocv1child", V1, { opencodeGeneration: "v1" }, PROJECT);
+  created("cr_ocunsafechild", UNSAFE, { opencodeGeneration: "v2", opencodeUnsafeTools: false }, PROJECT);
+  created("cr_ocnullchild", NULLDIR, { opencodeGeneration: "v2", opencodeUnsafeTools: true }, null);
+}
+
+function queue(userId: string, nodeId: string, networkId: string | null = NET, callerIsNode = false) {
+  return queueOpenCodeCatalogRead({ callerUserId: userId, callerIsNode, networkId, daemonNodeId: DAEMON, nodeId });
+}
+
+function handlers(userId: string, isNode: boolean, tokenId: string | null) {
+  const server = new McpServer({ name: "oc-catalog-test", version: "0" }) as any;
+  const out: Record<string, (args: any) => Promise<{ content: Array<{ text: string }> }>> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, d: string, schema: any, handler: any) => { out[name] = handler; return origTool(name, d, schema, handler); };
+  const origRegister = server.registerTool.bind(server);
+  server.registerTool = (name: string, cfg: any, handler: any) => { out[name] = handler; return origRegister(name, cfg, handler); };
+  registerTools(server, undefined, NET, userId, isNode ? DAEMON_ALIAS : null, isNode, tokenId);
+  return { out, server };
+}
+async function call(handler: (args: any) => Promise<{ content: Array<{ text: string }> }>, args: any) {
+  return JSON.parse((await handler(args)).content[0]!.text);
+}
+
+function snapshot(directory = PROJECT, overrides: Record<string, unknown> = {}) {
+  return {
+    scope: { networkId: NET, daemonId: DAEMON, directory },
+    source: "opencode-v2-api",
+    state: "snapshot",
+    invocationVerified: false,
+    completeness: "unknown",
+    observedAt: "2026-10-11T00:00:00.000Z",
+    providers: [{ id: "custom", activation: "enabled" }],
+    models: [{ providerId: "custom", id: "nested/model" }],
+    defaultModel: { providerId: "custom", id: "nested/model" },
+    ...overrides,
+  };
+}
+
+describe("hub authorizes an owned OpenCode V2 catalog read", () => {
+  test("member queues, daemon reads the owned loopback, ready snapshot stays unverified", async () => {
+    seed();
+    const user = handlers(USER, false, null);
+    const queued = await call(user.out.read_opencode_catalog!, { daemon_node_id: DAEMON, node_id: V2 });
+    expect(queued).toEqual({ ok: true, status: "pending", request_id: queued.request_id });
+    expect(JSON.stringify(queued)).not.toContain("daemon_alias");
+    const strict = await (user.server as any)._registeredTools.read_opencode_catalog.inputSchema.safeParseAsync({
+      daemon_node_id: DAEMON, node_id: V2, settings: { apiKey: "sk-FAKE" }, headers: {}, body: {},
+    });
+    expect(strict.success).toBe(false);
+
+    expect(takeOpenCodeCatalogRequest(queued.request_id, "node_other")).toEqual({ ok: false, error: "catalog_request_unavailable" });
+    const daemon = handlers(USER, true, DAEMON_TOK);
+    const pulled = await call(daemon.out.get_opencode_catalog_request!, { request_id: queued.request_id });
+    expect(pulled.ok).toBe(true);
+    expect(pulled.directory).toBe(PROJECT);
+    for (const key of ["url", "authorization", "settings", "headers", "body"]) expect(pulled[key]).toBeUndefined();
+
+    let requests = 0;
+    const server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch(req) {
+      requests++;
+      const url = new URL(req.url);
+      const row = url.pathname === "/api/provider"
+        ? [{ id: "custom", activation: "enabled", settings: { apiKey: "sk-FAKE" } }]
+        : [{ providerID: "custom", id: "nested/model", headers: { Authorization: "sk-FAKE" } }];
+      return Response.json({ location: { directory: PROJECT }, data: url.pathname === "/api/model/default" ? row[0] : row });
+    } });
+    const nodeDir = mkdtempSync(join(tmpdir(), "oc-hub-node-"));
+    try {
+      writeOpenCodeV2CatalogEndpoint(nodeDir, { url: `http://127.0.0.1:${server.port}`, authorization: "Basic fake", directory: PROJECT });
+      const read = await readOwnedOpenCodeV2Catalog({
+        networkId: NET, daemonId: DAEMON, authorizedDirectory: pulled.directory,
+        ownedProjectDirectory: PROJECT, endpoint: readOpenCodeV2CatalogEndpoint(nodeDir),
+      });
+      expect(read.ok).toBe(true);
+      if (!read.ok) return;
+      const acked = await call(daemon.out.ack_opencode_catalog!, { request_id: queued.request_id, snapshot: read.snapshot });
+      expect(acked).toEqual({ ok: true, status: "ready" });
+      const got = await call(user.out.get_opencode_catalog!, { request_id: queued.request_id });
+      expect(got.status).toBe("ready");
+      expect(got.snapshot.invocationVerified).toBe(false);
+      expect(got.snapshot.completeness).toBe("unknown");
+      expect(JSON.stringify(got.snapshot)).not.toContain("sk-FAKE");
+      expect(requests).toBe(3);
+    } finally {
+      server.stop(true);
+      rmSync(nodeDir, { recursive: true, force: true });
+    }
+  });
+
+  test("viewer may queue; outsider, node token, and non-v2 children may not", () => {
+    seed();
+    expect(queue(VIEWER, V2).ok).toBe(true);
+    expect(queue(OUTSIDER, V2, NET)).toEqual({ ok: false, error: "access_denied" });
+    expect(queue(OUTSIDER, V2, OTHER)).toEqual({ ok: false, error: "daemon_not_found" });
+    expect(queue(USER, V2, NET, true)).toEqual({ ok: false, error: "user_token_required" });
+    expect(queue(USER, V1)).toEqual({ ok: false, error: "not_opencode_v2" });
+    expect(queue(USER, UNSAFE)).toEqual({ ok: false, error: "not_opencode_v2" });
+    expect(queue(USER, "node_missing")).toEqual({ ok: false, error: "node_not_found" });
+  });
+
+  test("pending is not a snapshot; expiry, bad acks, and a missing endpoint stay closed", async () => {
+    seed();
+    const queued = queue(USER, V2);
+    expect(queued.ok).toBe(true);
+    if (!queued.ok) return;
+    expect(getOpenCodeCatalogResult({ callerUserId: USER, callerIsNode: false, networkId: NET, requestId: queued.request_id })).toEqual({
+      ok: true, status: "pending", request_id: queued.request_id,
+    });
+    const pulled = takeOpenCodeCatalogRequest(queued.request_id, DAEMON);
+    expect(pulled.ok).toBe(true);
+
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: queued.request_id, snapshot: snapshot(), settings: { apiKey: "sk-FAKE" } })).toEqual({ ok: false, error: "invalid_ack" });
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: queued.request_id, snapshot: snapshot(PROJECT, { invocationVerified: true }) })).toEqual({ ok: false, error: "invalid_ack" });
+    expect(getOpenCodeCatalogResult({ callerUserId: USER, callerIsNode: false, networkId: NET, requestId: queued.request_id }).status).toBe("pending");
+
+    const wrongDir = ackOpenCodeCatalog(DAEMON, { request_id: queued.request_id, snapshot: snapshot("/tmp/other-project") });
+    expect(wrongDir).toEqual({ ok: true, status: "failed", error: "invalid_response" });
+    expect(getOpenCodeCatalogResult({ callerUserId: USER, callerIsNode: false, networkId: NET, requestId: queued.request_id })).toMatchObject({
+      ok: false, status: "failed", error: "invalid_response",
+    });
+
+    const again = queue(USER, V2);
+    expect(again.ok).toBe(true);
+    if (!again.ok) return;
+    takeOpenCodeCatalogRequest(again.request_id, DAEMON);
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: again.request_id, error: "unavailable" })).toEqual({ ok: true, status: "failed", error: "unavailable" });
+    expect(getOpenCodeCatalogResult({ callerUserId: USER, callerIsNode: false, networkId: NET, requestId: again.request_id })).toMatchObject({
+      ok: false, status: "failed", error: "unavailable",
+    });
+
+    const waiting = queue(USER, NULLDIR);
+    expect(waiting.ok).toBe(true);
+    if (!waiting.ok) return;
+    expireOpenCodeCatalogForTest(waiting.request_id);
+    expect(getOpenCodeCatalogResult({ callerUserId: USER, callerIsNode: false, networkId: NET, requestId: waiting.request_id })).toMatchObject({
+      ok: false, status: "expired", error: "unavailable",
+    });
+  });
+
+  test("acks a Windows absolute directory without Hub path.resolve", () => {
+    seed();
+    db.run(`UPDATE node_create_requests SET workdir = ?1 WHERE request_id = ?2`, ["C:\\project", V2_REQ]);
+    const queued = queue(USER, V2);
+    expect(queued.ok).toBe(true);
+    if (!queued.ok) return;
+    takeOpenCodeCatalogRequest(queued.request_id, DAEMON);
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: queued.request_id, snapshot: snapshot("project") })).toEqual({ ok: false, error: "invalid_ack" });
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: queued.request_id, snapshot: snapshot("C:relative") })).toEqual({ ok: false, error: "invalid_ack" });
+    expect(getOpenCodeCatalogResult({ callerUserId: USER, callerIsNode: false, networkId: NET, requestId: queued.request_id }).status).toBe("pending");
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: queued.request_id, snapshot: snapshot("C:/project") })).toEqual({ ok: true, status: "ready" });
+    const got = getOpenCodeCatalogResult({ callerUserId: USER, callerIsNode: false, networkId: NET, requestId: queued.request_id });
+    expect(got.ok).toBe(true);
+    if (!got.ok || got.status !== "ready") return;
+    expect(got.snapshot.scope.directory).toBe("C:/project");
+
+    const other = queue(USER, V2);
+    expect(other.ok).toBe(true);
+    if (!other.ok) return;
+    takeOpenCodeCatalogRequest(other.request_id, DAEMON);
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: other.request_id, snapshot: snapshot("D:\\other") })).toEqual({
+      ok: true, status: "failed", error: "invalid_response",
+    });
+  });
+
+  test("a tilde workdir matches a native absolute report, and lexical .. collapses", () => {
+    seed();
+    db.run(`UPDATE node_create_requests SET workdir = ?1 WHERE request_id = ?2`, ["~/project", V2_REQ]);
+    const queued = queue(USER, V2);
+    expect(queued.ok).toBe(true);
+    if (!queued.ok) return;
+    takeOpenCodeCatalogRequest(queued.request_id, DAEMON);
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: queued.request_id, snapshot: snapshot("/home/user/project") })).toEqual({ ok: true, status: "ready" });
+
+    db.run(`UPDATE node_create_requests SET workdir = ?1 WHERE request_id = ?2`, ["/tmp/foo/../bar", V2_REQ]);
+    const lexical = queue(USER, V2);
+    expect(lexical.ok).toBe(true);
+    if (!lexical.ok) return;
+    takeOpenCodeCatalogRequest(lexical.request_id, DAEMON);
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: lexical.request_id, snapshot: snapshot("/tmp/foo/../bar") })).toEqual({ ok: false, error: "invalid_ack" });
+    expect(ackOpenCodeCatalog(DAEMON, { request_id: lexical.request_id, snapshot: snapshot("/tmp/bar") })).toEqual({ ok: true, status: "ready" });
+  });
+});

package/src/opencode-v2-catalog.ts

@@ -0,0 +1,352 @@
+// Hub authorization for a native OpenCode V2 catalog read.
+//
+// The caller names a daemon and a child node. Identity, generation, and the
+// project directory come from Hub rows. The queued payload has no URL,
+// authorization, settings, headers, or body. The daemon reads its own
+// already-running loopback and acks a whitelist snapshot.
+//
+// `status: "pending"` means the read was authorized and stored. It does not
+// mean a daemon received the doorbell or produced a snapshot. Only
+// `status: "ready"` is a snapshot, and that snapshot stays completeness
+// unknown / invocation unverified.
+
+import { posix, win32 } from "node:path";
+import { z } from "zod/v4";
+import { db, uuidv4 } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+
+const TTL_MS = 60_000;
+const MAX_PENDING = 100;
+const SECRET = /^(sk-|gh[pousr]_|github_pat_|xox[baprs]-|AKIA|AIza|ya29\.|glpat-)/i;
+
+export const CATALOG_ERROR_CODES = [
+  "invalid_target", "unauthorized", "unavailable", "invalid_response", "scope_mismatch", "too_large",
+] as const;
+export type CatalogErrorCode = (typeof CATALOG_ERROR_CODES)[number];
+
+const identifier = z.string().min(1).max(512).refine(value => !/[\s\u0000-\u001f\u007f]/.test(value) && !SECRET.test(value));
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const WINDOWS_DRIVE = /^[A-Za-z]:[\\/]/;
+
+/** Absolute in the path's own format. Hub `path.resolve` is not used: on a
+ * POSIX Hub it treats `C:\project` as a relative path under the process cwd. */
+function windowsStrictAbsolute(value: string): boolean {
+  if (!WINDOWS_DRIVE.test(value)) return false;
+  const parts = value.slice(2).split(/[\\/]/);
+  if (parts[0] !== "" || parts.length < 2) return false;
+  return parts.slice(1).every(part => part !== "" && part !== "." && part !== "..");
+}
+
+export function strictNativeAbsoluteDirectory(value: string): boolean {
+  if (value.length < 1 || value.length > 1024 || CONTROL.test(value)) return false;
+  if (WINDOWS_DRIVE.test(value)) return windowsStrictAbsolute(value);
+  if (value.startsWith("/")) return posix.resolve(value) === value;
+  return false;
+}
+
+function tildeWorkdir(value: string): boolean {
+  const trimmed = value.trim();
+  return trimmed === "~" || trimmed.startsWith("~/") || trimmed.startsWith("~\\");
+}
+
+/** Compare a stored create workdir with the directory the daemon reported.
+ * Windows keys ignore slash style and case. POSIX keys are lexical (`..` and
+ * a trailing slash collapse) and are not realpath'd — Hub does not see the
+ * daemon disk. A `~` / `~/…` workdir has no Hub-side home to expand; a
+ * native-absolute report is accepted because the daemon already refused the
+ * read unless that path is the endpoint it owns. A compromised daemon can
+ * name another absolute path for a tilde row, same as a null workdir. */
+export function catalogDirectoriesMatch(stored: string, reported: string): boolean {
+  if (!strictNativeAbsoluteDirectory(reported)) return false;
+  const storedTrim = stored.trim();
+  if (tildeWorkdir(storedTrim)) return true;
+  const storedWindows = WINDOWS_DRIVE.test(storedTrim);
+  const reportedWindows = WINDOWS_DRIVE.test(reported);
+  if (storedWindows !== reportedWindows) return false;
+  if (storedWindows) {
+    const left = win32.resolve(storedTrim);
+    const right = win32.resolve(reported);
+    return /^[A-Za-z]:\\/.test(left) && left.toLowerCase() === right.toLowerCase();
+  }
+  if (storedTrim.startsWith("/") && reported.startsWith("/")) return posix.resolve(storedTrim) === posix.resolve(reported);
+  return false;
+}
+
+const directoryText = z.string().min(1).max(1024).refine(strictNativeAbsoluteDirectory);
+
+export const opencodeCatalogSnapshotSchema = z.object({
+  scope: z.object({
+    networkId: z.string().min(1).max(200),
+    daemonId: z.string().min(1).max(200),
+    directory: directoryText,
+  }).strict(),
+  source: z.literal("opencode-v2-api"),
+  state: z.literal("snapshot"),
+  invocationVerified: z.literal(false),
+  completeness: z.literal("unknown"),
+  observedAt: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/),
+  providers: z.array(z.object({
+    id: identifier,
+    activation: z.enum(["auto", "enabled", "disabled"]),
+  }).strict()).max(20_000),
+  models: z.array(z.object({
+    providerId: identifier,
+    id: identifier,
+  }).strict()).max(20_000),
+  defaultModel: z.object({ providerId: identifier, id: identifier }).strict().nullable(),
+}).strict();
+
+export type OpenCodeCatalogSnapshotWire = z.infer<typeof opencodeCatalogSnapshotSchema>;
+
+export const opencodeCatalogAckSchema = z.object({
+  request_id: z.string().min(1).max(200),
+  error: z.enum(CATALOG_ERROR_CODES).optional(),
+  snapshot: opencodeCatalogSnapshotSchema.optional(),
+}).strict();
+
+interface PendingCatalogRead {
+  requestId: string;
+  daemonNodeId: string;
+  daemonAlias: string;
+  networkId: string;
+  nodeId: string;
+  alias: string;
+  directory: string | null;
+  expiresAt: number;
+  taken: boolean;
+}
+
+export interface StoredCatalogRead {
+  requestId: string;
+  networkId: string;
+  daemonNodeId: string;
+  nodeId: string;
+  status: "pending" | "ready" | "failed" | "expired";
+  error?: CatalogErrorCode;
+  snapshot?: OpenCodeCatalogSnapshotWire;
+  expiresAt: number;
+}
+
+const pending = new Map<string, PendingCatalogRead>();
+const stored = new Map<string, StoredCatalogRead>();
+
+export function resetOpenCodeCatalogForTest(): void {
+  pending.clear();
+  stored.clear();
+}
+
+export function expireOpenCodeCatalogForTest(requestId: string): void {
+  // Just past the read deadline, still inside the retention window. Setting
+  // the deadline to 0 would also drop the stored row and look like not_found.
+  const expiredAt = Date.now() - 1;
+  const row = pending.get(requestId);
+  if (row) row.expiresAt = expiredAt;
+  const result = stored.get(requestId);
+  if (result) result.expiresAt = expiredAt;
+}
+
+function childNodeId(requestId: string): string | null {
+  return requestId.startsWith("cr_") ? `node_${requestId.slice(3)}` : null;
+}
+
+function supervisorRole(snapshot: string | null): boolean {
+  if (!snapshot) return false;
+  try {
+    const parsed = JSON.parse(snapshot) as { role?: unknown };
+    return parsed.role === "host_supervisor";
+  } catch {
+    return false;
+  }
+}
+
+function v2Flags(flagsJson: string): boolean {
+  try {
+    const flags = JSON.parse(flagsJson) as { opencodeGeneration?: unknown; opencodeUnsafeTools?: unknown };
+    return flags.opencodeGeneration === "v2" && flags.opencodeUnsafeTools === true;
+  } catch {
+    return false;
+  }
+}
+
+export interface QueueCatalogInput {
+  callerUserId: string | null;
+  callerIsNode: boolean;
+  networkId: string | null;
+  daemonNodeId: string;
+  nodeId: string;
+}
+
+function evictExpired(now = Date.now()): void {
+  for (const [id, row] of pending) {
+    if (now > row.expiresAt) pending.delete(id);
+  }
+  for (const [id, row] of stored) {
+    if (row.status === "pending" && now > row.expiresAt) row.status = "expired";
+    if (now > row.expiresAt + TTL_MS) stored.delete(id);
+  }
+}
+
+export function queueOpenCodeCatalogRead(input: QueueCatalogInput):
+  | { ok: true; request_id: string; status: "pending"; daemon_alias: string; network_id: string }
+  | { ok: false; error: string } {
+  evictExpired();
+  if (input.callerIsNode) return { ok: false, error: "user_token_required" };
+  if (!input.callerUserId) return { ok: false, error: "auth_required" };
+  if (!input.networkId) return { ok: false, error: "network_id_required" };
+  const role = getUserNetworkRole(input.callerUserId, input.networkId);
+  if (!role) return { ok: false, error: "access_denied" };
+  if (pending.size >= MAX_PENDING) return { ok: false, error: "catalog_busy" };
+
+  const daemon = db.get<{ node_id: string; alias: string; config_snapshot: string | null }>(
+    `SELECT node_id, alias, config_snapshot FROM nodes WHERE node_id = ?1 AND network_id = ?2`,
+    input.daemonNodeId, input.networkId,
+  );
+  if (!daemon) return { ok: false, error: "daemon_not_found" };
+  if (!supervisorRole(daemon.config_snapshot)) return { ok: false, error: "daemon_not_supervisor" };
+
+  const child = db.get<{ node_id: string }>(
+    `SELECT node_id FROM nodes WHERE node_id = ?1 AND network_id = ?2`,
+    input.nodeId, input.networkId,
+  );
+  if (!child) return { ok: false, error: "node_not_found" };
+
+  const creates = db.all<{
+    request_id: string; daemon_node_id: string; child_name: string; runtime: string;
+    flags_json: string; workdir: string | null; status: string;
+  }>(
+    `SELECT request_id, daemon_node_id, child_name, runtime, flags_json, workdir, status
+       FROM node_create_requests
+      WHERE network_id = ?1 AND daemon_node_id = ?2 AND status IN ('succeeded', 'delivered')`,
+    input.networkId, input.daemonNodeId,
+  );
+  const owned = creates.filter(row => childNodeId(row.request_id) === input.nodeId && row.daemon_node_id === input.daemonNodeId);
+  if (owned.length !== 1) return { ok: false, error: "node_not_found" };
+  const row = owned[0]!;
+  if (row.runtime !== "opencode-cli" || !v2Flags(row.flags_json)) return { ok: false, error: "not_opencode_v2" };
+
+  const requestId = `cat_${uuidv4()}`;
+  const directory = typeof row.workdir === "string" && row.workdir.length > 0 ? row.workdir : null;
+  const record: PendingCatalogRead = {
+    requestId,
+    daemonNodeId: daemon.node_id,
+    daemonAlias: daemon.alias,
+    networkId: input.networkId,
+    nodeId: input.nodeId,
+    alias: row.child_name,
+    directory,
+    expiresAt: Date.now() + TTL_MS,
+    taken: false,
+  };
+  pending.set(requestId, record);
+  stored.set(requestId, {
+    requestId,
+    networkId: input.networkId,
+    daemonNodeId: daemon.node_id,
+    nodeId: input.nodeId,
+    status: "pending",
+    expiresAt: record.expiresAt,
+  });
+  return { ok: true, request_id: requestId, status: "pending", daemon_alias: daemon.alias, network_id: input.networkId };
+}
+
+export function takeOpenCodeCatalogRequest(requestId: string, daemonNodeId: string):
+  | { ok: true; request_id: string; node_id: string; alias: string; directory: string | null; scope: { networkId: string; daemonId: string } }
+  | { ok: false; error: "catalog_request_unavailable" } {
+  const row = pending.get(requestId);
+  if (!row || row.daemonNodeId !== daemonNodeId || row.taken) return { ok: false, error: "catalog_request_unavailable" };
+  if (Date.now() > row.expiresAt) {
+    row.taken = true;
+    const result = stored.get(requestId);
+    if (result && result.status === "pending") result.status = "expired";
+    return { ok: false, error: "catalog_request_unavailable" };
+  }
+  row.taken = true;
+  return {
+    ok: true,
+    request_id: row.requestId,
+    node_id: row.nodeId,
+    alias: row.alias,
+    directory: row.directory,
+    scope: { networkId: row.networkId, daemonId: row.daemonNodeId },
+  };
+}
+
+function consistent(snapshot: OpenCodeCatalogSnapshotWire): boolean {
+  const providers = new Set<string>();
+  for (const row of snapshot.providers) {
+    if (providers.has(row.id)) return false;
+    providers.add(row.id);
+  }
+  const models = new Set<string>();
+  for (const row of snapshot.models) {
+    if (!providers.has(row.providerId)) return false;
+    const key = JSON.stringify([row.providerId, row.id]);
+    if (models.has(key)) return false;
+    models.add(key);
+  }
+  if (snapshot.defaultModel && !models.has(JSON.stringify([snapshot.defaultModel.providerId, snapshot.defaultModel.id]))) return false;
+  return Buffer.byteLength(JSON.stringify(snapshot), "utf8") <= 2 * 1024 * 1024;
+}
+
+export function ackOpenCodeCatalog(daemonNodeId: string, body: unknown):
+  | { ok: true; status: "ready" | "failed"; error?: CatalogErrorCode }
+  | { ok: false; error: "catalog_request_unavailable" | "invalid_ack" } {
+  const parsed = opencodeCatalogAckSchema.safeParse(body);
+  if (!parsed.success) return { ok: false, error: "invalid_ack" };
+  const ack = parsed.data;
+  const hasSnapshot = ack.snapshot !== undefined;
+  const hasError = ack.error !== undefined;
+  if (hasSnapshot === hasError) return { ok: false, error: "invalid_ack" };
+  const row = pending.get(ack.request_id);
+  const result = stored.get(ack.request_id);
+  if (!row || !result || row.daemonNodeId !== daemonNodeId || !row.taken) {
+    return { ok: false, error: "catalog_request_unavailable" };
+  }
+  if (Date.now() > row.expiresAt || result.status !== "pending") {
+    if (result.status === "pending") result.status = "expired";
+    return { ok: false, error: "catalog_request_unavailable" };
+  }
+  if (ack.error) {
+    result.status = "failed";
+    result.error = ack.error;
+    return { ok: true, status: "failed", error: ack.error };
+  }
+  const snapshot = ack.snapshot!;
+  // A stored workdir must match. A null workdir (legacy create) has no
+  // hub-side path to compare; the daemon binds that read to the project
+  // directory it already owns. Hub does not see that filesystem.
+  const directoryOk = row.directory ? catalogDirectoriesMatch(row.directory, snapshot.scope.directory) : true;
+  if (snapshot.scope.networkId !== row.networkId || snapshot.scope.daemonId !== row.daemonNodeId || !directoryOk || !consistent(snapshot)) {
+    result.status = "failed";
+    result.error = "invalid_response";
+    return { ok: true, status: "failed", error: "invalid_response" };
+  }
+  result.status = "ready";
+  result.snapshot = snapshot;
+  return { ok: true, status: "ready" };
+}
+
+export function getOpenCodeCatalogResult(input: {
+  callerUserId: string | null;
+  callerIsNode: boolean;
+  networkId: string | null;
+  requestId: string;
+}):
+  | { ok: true; status: "pending"; request_id: string }
+  | { ok: true; status: "ready"; request_id: string; snapshot: OpenCodeCatalogSnapshotWire }
+  | { ok: false; status?: "failed" | "expired"; error: string; request_id?: string } {
+  if (input.callerIsNode) return { ok: false, error: "user_token_required" };
+  if (!input.callerUserId) return { ok: false, error: "auth_required" };
+  if (!input.networkId) return { ok: false, error: "network_id_required" };
+  if (!getUserNetworkRole(input.callerUserId, input.networkId)) return { ok: false, error: "access_denied" };
+  evictExpired();
+  const result = stored.get(input.requestId);
+  if (!result || result.networkId !== input.networkId) return { ok: false, error: "not_found" };
+  if (result.status === "pending" && Date.now() > result.expiresAt) result.status = "expired";
+  if (result.status === "pending") return { ok: true, status: "pending", request_id: result.requestId };
+  if (result.status === "ready" && result.snapshot) {
+    return { ok: true, status: "ready", request_id: result.requestId, snapshot: result.snapshot };
+  }
+  if (result.status === "expired") return { ok: false, status: "expired", error: "unavailable", request_id: result.requestId };
+  return { ok: false, status: "failed", error: result.error || "unavailable", request_id: result.requestId };
+}

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