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

package/src/rest-write-network-resolution.test.ts

@@ -0,0 +1,133 @@
+// #819 — `resolveRestWriteNetworkId` 是 network-scope.ts 里唯一没有任何测试点名的
+// 导出函数。同文件的五个兄弟各有 1-2 个测试文件点名它们:
+//
+//   resolveRestNetworkScope  1        canRestWriteNetwork  1
+//   singleNetworkId          2        addNetworkScope      1
+//   getUserNetworkIds        1        resolveRestWriteNetworkId  🔴 0
+//
+// 而它决定的是**一次 REST 写入落到哪个网络**。它的 docstring 说明了一条不显然的
+// 规则:管理员的**读**作用域按设计是全局的(networkIds=null),所以它本身表达不了
+// 「这个管理员恰好只属于一个网络」;而**写**不能继承这个歧义 —— 只有在确实只有
+// 一个成员关系时才用它,0 个或 ≥2 个都必须显式指定网络。
+//
+// 🔴 这条规则的两半都要钉:
+//   - **放行那半**(admin + 恰好 1 个成员关系 → 用它)如果坏了,会退化成「管理员
+//     写任何东西都要显式带 network_id」——很吵,但**安全**,所以没人会急着修;
+//   - **收紧那半**(admin + 0 或 ≥2 → null)如果坏了,一次写入会**落到一个没被
+//     指定的网络里**,而调用方看到的是成功。
+//
+// 只写反向断言是不够的:一个「永远返回 null」的实现能通过所有「收紧」用例。
+// 所以每一条收紧断言都配了正控。
+//
+// Run: COMMHUB_DB=/tmp/819-rest-write-scope.db bun test src/rest-write-network-resolution.test.ts
+
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { resolveRestNetworkScope, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
+
+const NET_A = "net_819_a";
+const NET_B = "net_819_b";
+const U_SINGLE = "u819_single";   // 只属于 NET_A
+const U_MULTI = "u819_multi";     // 属于 NET_A + NET_B
+const U_NONE = "u819_none";       // 一个都不属于
+const ALL_USERS = [U_SINGLE, U_MULTI, U_NONE];
+
+function cleanup() {
+  try { db.run("DELETE FROM network_members WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  for (const u of ALL_USERS) {
+    try { db.run("DELETE FROM users WHERE user_id = ?1", [u]); } catch {}
+  }
+}
+
+function seed() {
+  for (const u of ALL_USERS) {
+    db.run(
+      `INSERT INTO users (user_id, username, password_hash, role, created_at)
+       VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+      [u, u],
+    );
+  }
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_A, U_SINGLE]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_B, U_MULTI]);
+  const member = (u: string, net: string, role: string) =>
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, ?3, datetime('now'))`, [u, net, role]);
+  member(U_SINGLE, NET_A, "owner");
+  member(U_MULTI, NET_A, "member");
+  member(U_MULTI, NET_B, "owner");
+}
+
+beforeEach(() => { cleanup(); seed(); });
+afterAll(() => { cleanup(); });
+
+/** 管理员的读作用域:全局(networkIds=null),这正是歧义的来源。 */
+const ADMIN_SCOPE: RestNetworkScope = { networkIds: null };
+const scopeOf = (...ids: string[]): RestNetworkScope => ({ networkIds: ids });
+const ctx = (userId: string) => ({ userId, networkId: null });
+
+describe("#819 resolveRestWriteNetworkId — 作用域里就能确定时,直接用它", () => {
+  test("作用域恰好一个网络 → 用那一个(与是不是 admin 无关)", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(NET_A), ctx(U_MULTI), false)).toBe(NET_A);
+    expect(resolveRestWriteNetworkId(scopeOf(NET_A), ctx(U_MULTI), true)).toBe(NET_A);
+  });
+
+  test("作用域两个网络 → 歧义,null(即使调用者是 admin)", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(NET_A, NET_B), ctx(U_MULTI), true)).toBeNull();
+  });
+
+  // 🔴 这一条我一开始断错了,留下来当记录:我以为「作用域为空数组 → null」,
+  // 实测是 NET_A。原因是 `[]` 过不了 singleNetworkId,于是落到 admin 的成员关系
+  // 回退分支,而 U_SINGLE 恰好只有一个成员关系。
+  //
+  // 而 `networkIds: []` 在 resolveRestNetworkScope 里有确切含义:`:46` 那一行,
+  // **非 admin 请求了一个自己没有角色的网络** —— 它带着 `denied: "access denied
+  // to requested network"`。也就是说 `[]` 不是「没指定」,是「明确被拒」。
+  //
+  // 现在**没有**问题,因为那一行只对非 admin 产生(admin 在 `:42` 就提前返回
+  // networkIds:null 了),而非 admin 走到这里必然 null —— 见下一条。
+  //
+  // 但它是一个潜伏的形状:如果将来有任何路径让 admin 拿到 networkIds: [],
+  // 这次写入会**忽略那条明确的拒绝**,回退到他的单一成员关系。所以两条都钉住:
+  // 当前行为,以及那条让它安全的前提。
+  test("作用域为空数组 + admin + 恰好一个成员关系 → 回退到成员关系(当前行为,记录)", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(), ctx(U_SINGLE), true)).toBe(NET_A);
+  });
+
+  test("🔴 让上一条安全的前提:空数组作用域只由非 admin 产生,而非 admin → null", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(), ctx(U_SINGLE), false)).toBeNull();
+    // 前提本身也断一次:resolveRestNetworkScope 对 admin 从不产出空数组。
+    const adminScope = resolveRestNetworkScope(NET_B, ctx(U_NONE), true);
+    expect(adminScope.networkIds).toBeNull();
+  });
+});
+
+describe("#819 admin 的全局读作用域不能替写入决定网络", () => {
+  test("🔴 admin + 恰好 1 个成员关系 → 用那一个(放行那半)", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_SINGLE), true)).toBe(NET_A);
+  });
+
+  test("🔴 admin + 2 个成员关系 → null,必须显式指定(收紧那半)", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_MULTI), true)).toBeNull();
+  });
+
+  test("🔴 admin + 0 个成员关系 → null(不能因为读是全局的就随便挑一个)", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_NONE), true)).toBeNull();
+  });
+
+  test("非 admin + 全局作用域 → null(这种组合本身就不该发生,fail closed)", () => {
+    // 正控在上面那条「admin + 单成员 → NET_A」:如果实现改成永远 null,那条会红。
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_SINGLE), false)).toBeNull();
+  });
+
+  test("没有 authCtx + 全局作用域 → null", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, null, true)).toBeNull();
+  });
+});
+
+describe("#819 作用域优先于成员关系回退", () => {
+  test("作用域说 NET_B,而该用户唯一的成员关系是 NET_A → 结果是 NET_B", () => {
+    // 归属由作用域决定,不由「他碰巧属于哪个网络」决定。
+    // 如果实现把两者的优先级搞反,这条会返回 NET_A。
+    expect(resolveRestWriteNetworkId(scopeOf(NET_B), ctx(U_SINGLE), true)).toBe(NET_B);
+  });
+});

package/src/runtime-label.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { normalizeSessionRuntime } from "./runtime-label";
+
+describe("session runtime projection", () => {
+  test("preserves exact co-presence and CLI runtimes", () => {
+    expect(normalizeSessionRuntime("agent-node:codex-app-server")).toBe("codex-app-server");
+    expect(normalizeSessionRuntime("agent-node:grok-build-cli")).toBe("grok-build-cli");
+  });
+  test("keeps legacy labels backward-compatible", () => {
+    expect(normalizeSessionRuntime("agent-node:codex")).toBe("codex-sdk");
+    expect(normalizeSessionRuntime("agent-node:claude")).toBe("claude-agent-sdk");
+    expect(normalizeSessionRuntime("agent-node:grok")).toBe("grok-build-acp");
+    expect(normalizeSessionRuntime("agent-node:opencode")).toBe("opencode-cli");
+    expect(normalizeSessionRuntime("claude-code")).toBe("claude-code-cli");
+  });
+  test("does not invent unknown runtimes", () => {
+    expect(normalizeSessionRuntime("agent-node:future-runtime")).toBeNull();
+    expect(normalizeSessionRuntime("agent-node:codex-app-server-evil")).toBeNull();
+    expect(normalizeSessionRuntime("agent-node:grok-build-cli-preview")).toBeNull();
+    expect(normalizeSessionRuntime(null)).toBeNull();
+  });
+});

package/src/runtime-label.ts

@@ -0,0 +1,21 @@
+/** Preserve exact agent-node runtimes before applying legacy family aliases. */
+export function normalizeSessionRuntime(agent: unknown): string | null {
+  if (typeof agent !== "string" || agent.length === 0) return null;
+  if (agent === "claude-code") return "claude-code-cli";
+  const reported = agent.startsWith("agent-node:") ? agent.slice("agent-node:".length) : "";
+  const exact: Record<string, string> = {
+    "codex-app-server": "codex-app-server",
+    "grok-build-cli": "grok-build-cli",
+    opencode: "opencode-cli",
+    "opencode-cli": "opencode-cli",
+    codex: "codex-sdk",
+    "codex-sdk": "codex-sdk",
+    claude: "claude-agent-sdk",
+    "claude-agent-sdk": "claude-agent-sdk",
+    grok: "grok-build-acp",
+    "grok-build-acp": "grok-build-acp",
+  };
+  if (exact[reported]) return exact[reported];
+  if (agent === "http-api" || agent === "http" || agent === "api") return "http-api";
+  return null;
+}

package/src/scheduled-tasks-http.test.ts

@@ -442,9 +442,28 @@ describe("Hub scheduled task API and dispatcher", () => {
     const manual = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}/run-now?network_id=${encodeURIComponent(networkId)}`, { method: "POST", body: "{}" });
     expect(manual.status).toBe(202);
     expect(manual.body.taskId).toBeTruthy();
-    const cancelled = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`, { method: "DELETE" });
+    // Cancel via POST /cancel (the path the dashboard uses, since some
+    // reverse proxies rewrite DELETE to 405). Then verify the legacy
+    // DELETE endpoint is still accepted and idempotent when the row is
+    // already cancelled — both spellings must reach the same state.
+    const cancelled = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}/cancel?network_id=${encodeURIComponent(networkId)}`, { method: "POST", body: "{}" });
+    expect(cancelled.status).toBe(200);
     expect(cancelled.body.status).toBe("cancelled");
     const cancelledRow = (await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`)).body.schedule;
+    const revisionAfterCancel = cancelledRow.revision;
+    // Idempotency: DELETE on an already-cancelled row must be 200 with the
+    // same revision, not 409, and must not bump revision again.
+    const reCancelledDelete = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`, { method: "DELETE" });
+    expect(reCancelledDelete.status).toBe(200);
+    expect(reCancelledDelete.body.status).toBe("cancelled");
+    const afterDelete = (await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`)).body.schedule;
+    expect(afterDelete.revision).toBe(revisionAfterCancel);
+    // And POST /cancel on an already-cancelled row is also idempotent.
+    const reCancelledPost = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}/cancel?network_id=${encodeURIComponent(networkId)}`, { method: "POST", body: "{}" });
+    expect(reCancelledPost.status).toBe(200);
+    expect(reCancelledPost.body.status).toBe("cancelled");
+    const afterPost = (await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`)).body.schedule;
+    expect(afterPost.revision).toBe(revisionAfterCancel);
     const resurrect = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`, {
       method: "PATCH",
       body: JSON.stringify({ revision: cancelledRow.revision, status: "active", name: "must not revive" }),

package/src/scheduled-tasks.ts

@@ -451,7 +451,7 @@ export async function handleScheduledTaskRequest(ctx: ScheduledRequestContext):
     }
   }
 
-  const match = url.pathname.match(/^\/api\/scheduled-tasks\/([^/]+)(?:\/(runs|run-now))?$/);
+  const match = url.pathname.match(/^\/api\/scheduled-tasks\/([^/]+)(?:\/(runs|run-now|cancel))?$/);
   if (!match) return jsonError("not_found", 404);
   const scheduleId = decodeURIComponent(match[1]);
   const sub = match[2] || null;
@@ -479,7 +479,18 @@ export async function handleScheduledTaskRequest(ctx: ScheduledRequestContext):
     }
   }
 
-  if (!sub && req.method === "DELETE") {
+  // Cancel — accept two spellings for the same operation:
+  //   DELETE /api/scheduled-tasks/:id            (original)
+  //   POST   /api/scheduled-tasks/:id/cancel     (added because some reverse
+  //                                              proxies swallow DELETE and
+  //                                              return 405 HTML; POST is
+  //                                              universally allowed)
+  // Idempotent: re-cancelling an already-cancelled row is a 200 no-op, not a
+  // 409, because a client that just saw the row (still on screen as
+  // "cancelled" between polls) should get the same outcome whether it's the
+  // first click or a retry.
+  if ((!sub && req.method === "DELETE") || (sub === "cancel" && req.method === "POST")) {
+    if (row.status === "cancelled") return Response.json({ ok: true, status: "cancelled" });
     db.run("UPDATE scheduled_tasks SET status = 'cancelled', next_run_at = NULL, revision = revision + 1, updated_at = datetime('now') WHERE schedule_id = ?1", [row.schedule_id]);
     return Response.json({ ok: true, status: "cancelled" });
   }

package/src/server.ts

@@ -1,4 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { resolvePort } from "./resolve-port.js";
+import { normalizeSessionRuntime } from "./runtime-label.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod/v4";
 import { registerTools } from "./tools.js";
@@ -47,8 +49,10 @@ import { diagnoseTask } from "./task-diagnostic.js";
 import { assertScheduledTaskBackendSupported, handleScheduledTaskRequest, startScheduledTaskScheduler } from "./scheduled-tasks.js";
 import { handleExternalScheduleEditRequest } from "./external-schedule-edits.js";
 import { recordDeliveredStaleEvents } from "./task-lifecycle-watcher.js";
+import { SIDE_THREAD_FEATURE_FLAG, SideThreadCoordinator, SideThreadPortRegistry, SideThreadStore, type SideThreadActor, type SideThreadAttachmentRef, type SideThreadExecutionPort } from "./side-thread.js";
+import { handleSideThreadHttpRequest } from "./side-thread-http.js";
 
-const PORT = Number(process.env.PORT) || 9200;
+const PORT = resolvePort(process.env.PORT);
 const HOST = process.env.HOST || "127.0.0.1";
 const AUTH_TOKEN = process.env.COMMHUB_AUTH_TOKEN;
 const DEV_OPEN = process.argv.includes("--dev-open") || process.env.COMMHUB_DEV_OPEN === "1";
@@ -62,6 +66,18 @@ const TMUX_ALLOWLIST = new Set(
 );
 let masterTokenDeprecationLogged = false;
 
+// #175 PR2 starts fail-closed. Only a verified native adapter can be installed;
+// the execution port deliberately has no ordinary task/FIFO delivery method.
+export const sideThreadPortRegistry = new SideThreadPortRegistry();
+export function installSideThreadExecutionPort(port: SideThreadExecutionPort): () => void {
+  return sideThreadPortRegistry.install(port);
+}
+const sideThreadCoordinator = new SideThreadCoordinator(new SideThreadStore(db), sideThreadPortRegistry, {
+  enabled: process.env[SIDE_THREAD_FEATURE_FLAG] === "1",
+  authorizeNode: (actor, networkId, nodeId) => authorizeSideThreadNode(actor, networkId, nodeId),
+  authorizeAttachment: (actor, networkId, ref) => authorizeSideThreadAttachment(actor, networkId, ref),
+});
+
 if (AUTH_TOKEN) {
   console.warn("[commhub] COMMHUB_AUTH_TOKEN is deprecated and will be removed in v1.0. See RFC-001.");
 }
@@ -191,19 +207,7 @@ function isLocalhostIP(ip: string): boolean {
 // Normalize the raw `agent` field into a canonical runtime identifier for the
 // dashboard's Runtime badge. Returns null for unknown/absent agents so the
 // frontend can fall back to a placeholder.
-function normalizeRuntime(agent: unknown): string | null {
-  if (typeof agent !== "string" || agent.length === 0) return null;
-  if (agent === "claude-code") return "claude-code-cli";
-  if (agent.startsWith("agent-node:codex")) return "codex-sdk";
-  if (agent.startsWith("agent-node:claude")) return "claude-agent-sdk";
-  if (agent.startsWith("agent-node:grok")) return "grok-build-acp";
-  // RFC-029 — agent-node reports `agent-node:opencode` when RUNTIME
-  // bucket resolves to "opencode". Dashboard needs the canonical
-  // launcher name so its Runtime badge matches wizard choices.
-  if (agent.startsWith("agent-node:opencode")) return "opencode-cli";
-  if (agent === "http-api" || agent === "http" || agent === "api") return "http-api";
-  return null;
-}
+const normalizeRuntime = normalizeSessionRuntime;
 
 function isTmuxAllowedIP(ip: string): boolean {
   return isLocalhostIP(ip) || TMUX_ALLOWLIST.has(ip);
@@ -234,6 +238,25 @@ function resolveRequestAuth(req: Request, options: RequestTokenOptions = {}): {
   return { userId: resolved.user.user_id, networkId: resolved.networkId, username: resolved.user.username, tokenName: resolved.tokenName, tokenId: resolved.tokenId };
 }
 
+function resolveSideThreadActor(req: Request, auth: ReturnType<typeof resolveRequestAuth>, isAdmin: boolean): SideThreadActor | null {
+  // Legacy master and DEV_OPEN cannot own durable records because neither
+  // supplies a stable per-user identity for later window hydration.
+  if (!auth?.userId || !auth.tokenId) return null;
+  const nodeCredential = requestToken(req).startsWith("ntok_");
+  const tokenRow = nodeCredential
+    ? db.get<{ bound_node_id: string | null }>("SELECT bound_node_id FROM api_tokens WHERE token_id = ?1", auth.tokenId)
+    : null;
+  return {
+    userId: auth.userId,
+    username: auth.username,
+    tokenId: auth.tokenId,
+    kind: nodeCredential ? "node" : "user",
+    ...(auth.networkId ? { boundNetworkId: auth.networkId } : {}),
+    ...(tokenRow?.bound_node_id ? { boundNodeId: tokenRow.bound_node_id } : {}),
+    isAdmin,
+  };
+}
+
 // #503 — the credential kinds that authorization decisions branch on.
 // Resolved once per request at the handler, so the authz helpers stay
 // pure functions of (principal, entry) and every credential kind is a
@@ -336,6 +359,46 @@ export function authorizeFileDownload(
   return false;
 }
 
+function authorizeSideThreadNode(actor: SideThreadActor, networkId: string, nodeId: string): boolean {
+  const node = db.get<{ network_id: string | null; owner_user_id: string | null }>(
+    "SELECT network_id, owner_user_id FROM nodes WHERE node_id = ?1", nodeId,
+  );
+  if (!node || node.network_id !== networkId) return false;
+  if (!getUserNetworkRole(actor.userId, networkId)) return false;
+  if (!node.owner_user_id || node.owner_user_id !== actor.userId) return false;
+  if (actor.boundNetworkId && actor.boundNetworkId !== networkId) return false;
+  if (actor.kind === "node" && actor.boundNodeId !== nodeId) return false;
+  return true;
+}
+
+function resolveSideThreadCapabilityTarget(input: { actor: SideThreadActor; alias?: string; nodeId?: string; networkId?: string }): { nodeId: string; networkId: string } | undefined {
+  if ((!input.alias && !input.nodeId) || (input.alias && input.nodeId)) return undefined;
+  const networkId = input.actor.boundNetworkId ?? input.networkId;
+  const params: unknown[] = [input.nodeId ?? input.alias];
+  let sql = input.nodeId
+    ? "SELECT node_id,network_id FROM nodes WHERE node_id=?1"
+    : "SELECT node_id,network_id FROM nodes WHERE alias=?1";
+  if (networkId) { params.push(networkId); sql += " AND network_id=?2"; }
+  const authorized = db.all<{ node_id: string; network_id: string | null }>(sql, ...params)
+    .filter(row => !!row.network_id && authorizeSideThreadNode(input.actor, row.network_id, row.node_id));
+  if (authorized.length !== 1) return undefined;
+  return { nodeId: authorized[0].node_id, networkId: authorized[0].network_id! };
+}
+
+function authorizeSideThreadAttachment(actor: SideThreadActor, networkId: string, ref: SideThreadAttachmentRef): boolean {
+  if (!FILE_ID_REGEX.test(ref.fileId)) return false;
+  const path = indexEntryPath(ref.fileId);
+  if (!path || !existsSync(path)) return false;
+  try {
+    const entry = JSON.parse(readFileSync(path, "utf8"));
+    if (!validateIndexEntry(entry) || entry.file_id !== ref.fileId) return false;
+    if (entry.network_id !== networkId || entry.owner_id !== actor.userId) return false;
+    if (!isValidCalendarBucket(entry.date_bucket)) return false;
+    const storage = pathForExistingBlob(entry.date_bucket, entry.file_id, entry.ext);
+    return isPathInsideUploadsRoot(storage.absolutePath) && existsSync(storage.absolutePath);
+  } catch { return false; }
+}
+
 type ByteRange =
   | { ok: true; start: number; end: number; length: number }
   | { ok: false };
@@ -496,6 +559,17 @@ type RestDeliveryTarget =
   | { state: "offline"; alias: string; session: any; message: string }
   | { state: "not_found"; alias: string; message: string };
 
+// Build this only after authorization and a network-scoped lookup succeeded.
+// In particular, not-found and permission-denied responses must not become a
+// cross-network alias/node enumeration oracle.
+function restActualTo(target: Exclude<RestDeliveryTarget, { state: "not_found" }>, networkId: string | null) {
+  return {
+    alias: target.alias,
+    to_node_id: target.session?.node_id ?? null,
+    network_id: networkId,
+  };
+}
+
 function resolveRestDeliveryTarget(alias: string, networkId: string | null): RestDeliveryTarget {
   const params: any[] = [alias];
   let sql = "SELECT status, updated_at, last_seen_at, node_id FROM sessions WHERE alias = ?1";
@@ -648,7 +722,10 @@ export function patrolExpiredTasks(): void {
             WHERE task_id = ?1 AND status IN ('created', 'delivered')`,
           [task.task_id],
         );
-        if (result.changes !== 1) continue;
+        // SQLite may include the AFTER UPDATE terminal-journal trigger write
+        // in this count. The WHERE clause still targets one exact guarded
+        // task, so any positive count proves the task transition happened.
+        if (result.changes < 1) continue;
         syncScheduledRunForTask(task.task_id, task.network_id);
         changed.push(task);
       }
@@ -1442,6 +1519,16 @@ return Bun.serve({
       return withCors(req, Response.json({ ok: false, error: restScope.denied }, { status: 403 }));
     }
 
+    const sideThreadResponse = await handleSideThreadHttpRequest({
+      req,
+      url,
+      // Durable prompts/results never accept query-string credentials.
+      actor: resolveSideThreadActor(req, resolveRequestAuth(req, { allowQueryToken: false }), isAdmin),
+      coordinator: sideThreadCoordinator,
+      resolveCapabilityTarget: resolveSideThreadCapabilityTarget,
+    });
+    if (sideThreadResponse) return withCors(req, sideThreadResponse);
+
     // RFC-036 owner-gated host schedule edits. This handler independently
     // verifies exact node ownership and node-token binding; network admin is
     // deliberately not an override.
@@ -2262,6 +2349,7 @@ return Bun.serve({
       const identity = resolveRestFromSession({
         token: requestToken(req),
         tokenName: restAuth?.tokenName,
+        authenticatedUsername: restAuth?.username,
         requestedFrom: body.from,
       });
       if (!identity.ok) {
@@ -2277,6 +2365,7 @@ return Bun.serve({
       const ttlSeconds = (body as any).ttl_seconds || 3600;
       const fromNodeId = resolveRestNodeIdForAlias(fromSession, taskNetId);
       const targetNodeId = target.session?.node_id ?? null;
+      const actualTo = restActualTo(target, taskNetId);
       // #221 — fold top-level `attachments` into `meta.attachments` so
       // the REST and MCP send_task transports produce identical
       // tasks.meta_json shape downstream. Top-level wins over any
@@ -2377,10 +2466,17 @@ return Bun.serve({
           task_id: id,
           message_id: id,
           session_status: target.session.status ?? "offline",
+          actual_to: actualTo,
           ...(canonical.renamed ? { renamed_from: body.alias, renamed_to: targetAlias } : {}),
         }, { status: 202 }));
       }
-      return withCors(req, Response.json({ ok: true, task_id: id, message_id: id, ...(canonical.renamed ? { renamed_from: body.alias, renamed_to: targetAlias } : {}) }));
+      return withCors(req, Response.json({
+        ok: true,
+        task_id: id,
+        message_id: id,
+        actual_to: actualTo,
+        ...(canonical.renamed ? { renamed_from: body.alias, renamed_to: targetAlias } : {}),
+      }));
     }
 
     // ── REST: broadcast ──
@@ -3044,6 +3140,28 @@ return Bun.serve({
       const targetSession = db.get<{ alias: string; status: string }>(targetSql, ...targetParams);
       const targetAlias = targetSession?.alias ?? canonicalTarget ?? String(task.to_name ?? "");
       const liveSseConnections = getSSEStats().sessions[`${taskNetworkId || "global"}:${targetAlias}`] ?? 0;
+      // 🔴 #1083：这个目标【历史上有没有报过任何一次】运行时证据。
+      //   只用 Hub 自己已有的数据算，不需要 agent 侧任何改动。
+      //   为空时 runtime_submitted_at/consumed_at 是「不会走到」而不是「还没走到」，
+      //   两者处置相反（别等去接线 vs 等）。参数编号沿用上面 targetSql 的写法。
+      const evidenceParams: unknown[] = [];
+      let evidenceSql = "SELECT 1 AS seen FROM tasks WHERE runtime_submitted_at IS NOT NULL AND ";
+      if (task.to_node_id) {
+        evidenceSql += "to_node_id = ?1";
+        evidenceParams.push(task.to_node_id);
+      } else {
+        evidenceSql += "to_node_id IS NULL AND to_name = ?1";
+        evidenceParams.push(canonicalTarget ?? String(task.to_name ?? ""));
+      }
+      if (taskNetworkId) {
+        evidenceSql += " AND network_id = ?2";
+        evidenceParams.push(taskNetworkId);
+      } else {
+        evidenceSql += " AND network_id IS NULL";
+      }
+      evidenceSql += " LIMIT 1";
+      const targetEverReportedRuntimeEvidence =
+        Boolean(db.get<{ seen: number }>(evidenceSql, ...evidenceParams));
       const diagnostic = diagnoseTask({
         status: String(task.status ?? "unknown"),
         runtimeSubmittedAt: typeof task.runtime_submitted_at === "string" ? task.runtime_submitted_at : null,
@@ -3051,6 +3169,7 @@ return Bun.serve({
         targetSessionStatus: targetSession?.status ?? null,
         targetSessionExists: Boolean(targetSession),
         liveSseConnections,
+        targetEverReportedRuntimeEvidence,
       });
       return withCors(req, Response.json({ ok: true, task, diagnostic }));
     }

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

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SQLiteAdapter } from "./db-adapter";
+import { DurableSideThreadCommandPort, SideThreadCommandStore, handleSideThreadCommandRequest } from "./side-thread-command-transport";
+import { SideThreadCoordinator, SideThreadStore } from "./side-thread";
+
+function actor(tokenId = "tok-node") { return { tokenId, networkId: "net-1", nodeId: "node-1" }; }
+function fixture() {
+  const db = new SQLiteAdapter(new Database(":memory:"));
+  db.exec("CREATE TABLE inbox(id TEXT PRIMARY KEY, content TEXT)");
+  const store = new SideThreadCommandStore(db, () => 123);
+  const port = new DurableSideThreadCommandPort({ store, networkForNode: (id) => id === "node-1" ? "net-1" : null,
+    capabilityForNode: () => ({ supported: true, mode: "native-exact-fork", exactBoundary: { through: true, before: true } }),
+    grantAttachment: (_node, ref) => ({ fileId: ref.fileId, grantId: `grant-${ref.fileId}`, sha256: "a".repeat(64), size: 7, mediaType: "image/png" }) });
+  return { db, store, port };
+}
+
+describe("Hub durable SideThread command outbox", () => {
+  test("fails closed on the currently non-atomic PostgreSQL adapter", () => {
+    expect(() => new SideThreadCommandStore({ dialect: "postgres" } as any)).toThrow(/atomic SQLite/);
+  });
+  test("allows exactly one durable terminal applier", () => {
+    const f = fixture(); const close = f.port.subscribe(async () => {});
+    expect(() => f.port.subscribe(async () => {})).toThrow(/exactly one/);
+    close();
+  });
+  test("queues outside inbox/FIFO and only exact node token can retain the delivery", async () => {
+    const f = fixture();
+    await expect(f.port.fork({ operationId: "op-1", requestKey: "rk-1", sideChatId: "side-1", nodeId: "node-1", sourceThreadId: "source-1", boundary: { kind: "through", turnId: "source-turn" } })).rejects.toMatchObject({ code: "SIDE_THREAD_AMBIGUOUS" });
+    expect(f.db.get<{ n: number }>("SELECT COUNT(*) n FROM inbox")!.n).toBe(0);
+    expect(f.store.claim({ ...actor(), nodeId: "node-2" })).toBeNull();
+    const delivered = f.store.claim(actor())!;
+    expect(delivered).toMatchObject({ protocol: "side_thread.command.v1", operationId: "op-1", nodeId: "node-1" });
+    expect(f.store.claim(actor())).toEqual(delivered);
+  });
+
+  test("ACK response loss is idempotent and foreign token/collision cannot rewrite it", async () => {
+    const f = fixture();
+    await f.port.start({ operationId: "op-start", requestKey: "rk-start", sideChatId: "side-1", attemptId: "attempt-1", nodeId: "node-1", threadId: "derived-1", prompt: "q", attachments: [] }).catch(() => {});
+    const command = f.store.claim(actor())!;
+    const ack = { protocol: "side_thread.ack.v1", commandId: command.commandId, operationId: "op-start", state: "accepted", errorCode: null, result: { threadId: null, turnId: "turn-1", destinationTurnId: null } };
+    expect(f.store.ack(actor(), ack).idempotent).toBe(false);
+    expect(f.store.ack(actor(), ack).idempotent).toBe(true);
+    expect(() => f.store.ack(actor("tok-foreign"), ack)).toThrow(/ownership/);
+    expect(() => f.store.ack(actor(), { ...ack, state: "failed", errorCode: "SIDE_THREAD_CONFLICT" })).toThrow(/immutable/);
+  });
+
+  test("terminal receipt requires exact side/attempt/thread/turn tuple and is replay-safe", async () => {
+    const f = fixture(); const events: any[] = []; f.port.subscribe((e) => events.push(e));
+    await f.port.start({ operationId: "op-start", requestKey: "rk-start", sideChatId: "side-1", attemptId: "attempt-1", nodeId: "node-1", threadId: "derived-1", prompt: "q", attachments: [] }).catch(() => {});
+    const command = f.store.claim(actor())!;
+    f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: command.commandId, operationId: "op-start", state: "accepted", errorCode: null, result: { threadId: null, turnId: "turn-1", destinationTurnId: null } });
+    const terminal = { protocol: "side_thread.terminal.v1", sideThreadId: "side-1", attemptId: "attempt-1", threadId: "derived-1", turnId: "turn-1", status: "completed", text: "answer", errorCode: null };
+    await expect(f.port.acceptTerminal(actor(), { ...terminal, turnId: "turn-foreign" })).rejects.toThrow(/four-tuple/);
+    expect((await f.port.acceptTerminal(actor(), terminal)).idempotent).toBe(false);
+    expect((await f.port.acceptTerminal(actor(), terminal)).idempotent).toBe(true);
+    expect(events).toHaveLength(1);
+  });
+
+  test("durable accepted receipt reconciles a later POST retry without a second delivery", async () => {
+    const f = fixture(); const input = { operationId: "op-fork", requestKey: "rk-fork", sideChatId: "side-1", nodeId: "node-1", sourceThreadId: "source-1", boundary: { kind: "before" as const, turnId: "source-turn" } };
+    await f.port.fork(input).catch(() => {});
+    const command = f.store.claim(actor())!;
+    f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: command.commandId, operationId: input.operationId, state: "accepted", errorCode: null, result: { threadId: "derived-1", turnId: null, destinationTurnId: null } });
+    expect(await f.port.fork(input)).toEqual({ threadId: "derived-1" });
+    expect(f.store.claim(actor())).toBeNull();
+  });
+
+  test("HTTP surface binds path node and ACK body to the authenticated node actor", async () => {
+    const f = fixture();
+    await f.port.fork({ operationId: "op-http", requestKey: "rk-http", sideChatId: "side-http", nodeId: "node-1", sourceThreadId: "source-1", boundary: { kind: "through", turnId: "t-1" } }).catch(() => {});
+    const foreign = await handleSideThreadCommandRequest({ req: new Request("http://hub/api/nodes/node-1/side-thread-commands/pending"), url: new URL("http://hub/api/nodes/node-1/side-thread-commands/pending"), actor: { ...actor(), nodeId: "node-2" }, store: f.store, port: f.port });
+    expect(foreign?.status).toBe(403);
+    const pulled = await handleSideThreadCommandRequest({ req: new Request("http://hub/api/nodes/node-1/side-thread-commands/pending"), url: new URL("http://hub/api/nodes/node-1/side-thread-commands/pending"), actor: actor(), store: f.store, port: f.port });
+    const command = (await pulled!.json() as any).command;
+    const badBody = { protocol: "side_thread.ack.v1", commandId: "other-command", operationId: command.operationId, state: "accepted", errorCode: null, result: { threadId: "derived", turnId: null, destinationTurnId: null } };
+    const rejected = await handleSideThreadCommandRequest({ req: new Request(`http://hub/api/nodes/node-1/side-thread-commands/${command.commandId}/ack`, { method: "POST", body: JSON.stringify(badBody) }), url: new URL(`http://hub/api/nodes/node-1/side-thread-commands/${command.commandId}/ack`), actor: actor(), store: f.store, port: f.port });
+    expect(rejected?.status).toBe(409);
+  });
+
+  test("hostile node cannot smuggle extra receipt fields or unbounded terminal text", async () => {
+    const f = fixture(); f.port.subscribe(async () => {});
+    await f.port.start({ operationId: "op-hostile", requestKey: "rk-hostile", sideChatId: "side-hostile", attemptId: "attempt-hostile", nodeId: "node-1", threadId: "derived-hostile", prompt: "q", attachments: [] }).catch(() => {});
+    const command = f.store.claim(actor())!;
+    const clean = { protocol: "side_thread.ack.v1", commandId: command.commandId, operationId: "op-hostile", state: "accepted", errorCode: null, result: { threadId: null, turnId: "turn-hostile", destinationTurnId: null } };
+    expect(() => f.store.ack(actor(), { ...clean, exception: "Bearer ntok_secret" })).toThrow(/unexpected protocol fields/);
+    f.store.ack(actor(), clean);
+    const terminal = { protocol: "side_thread.terminal.v1", sideThreadId: "side-hostile", attemptId: "attempt-hostile", threadId: "derived-hostile", turnId: "turn-hostile", status: "completed", text: "ok", errorCode: null };
+    await expect(f.port.acceptTerminal(actor(), { ...terminal, stack: "secret" })).rejects.toThrow(/unexpected protocol fields/);
+    await expect(f.port.acceptTerminal(actor(), { ...terminal, text: "x".repeat(1_000_001) })).rejects.toThrow(/completed terminal payload/);
+    expect((await f.port.acceptTerminal(actor(), terminal)).idempotent).toBe(false);
+  });
+
+  test("receipt commit followed by listener failure remains durably redeliverable", async () => {
+    const f = fixture(); let calls = 0;
+    f.port.subscribe(async () => { calls++; if (calls === 1) throw new Error("coordinator crashed"); });
+    await f.port.start({ operationId: "op-terminal-crash", requestKey: "rk-terminal-crash", sideChatId: "side-crash", attemptId: "attempt-crash", nodeId: "node-1", threadId: "derived-crash", prompt: "q", attachments: [] }).catch(() => {});
+    const command = f.store.claim(actor())!;
+    f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: command.commandId, operationId: "op-terminal-crash", state: "accepted", errorCode: null, result: { threadId: null, turnId: "turn-crash", destinationTurnId: null } });
+    const terminal = { protocol: "side_thread.terminal.v1", sideThreadId: "side-crash", attemptId: "attempt-crash", threadId: "derived-crash", turnId: "turn-crash", status: "completed", text: "answer", errorCode: null };
+    await expect(f.port.acceptTerminal(actor(), terminal)).rejects.toThrow(/coordinator crashed/);
+    expect((await f.port.acceptTerminal(actor(), terminal)).pending).toBe(false);
+    expect(calls).toBe(2);
+  });
+
+  test("concurrent terminal POST cannot acknowledge WAL deletion while apply is pending", async () => {
+    const f = fixture(); let release!: () => void;
+    const gate = new Promise<void>((resolve) => { release = resolve; });
+    f.port.subscribe(async () => { await gate; throw new Error("late apply failure"); });
+    await f.port.start({ operationId: "op-concurrent-terminal", requestKey: "rk-concurrent-terminal", sideChatId: "side-concurrent", attemptId: "attempt-concurrent", nodeId: "node-1", threadId: "derived-concurrent", prompt: "q", attachments: [] }).catch(() => {});
+    const command = f.store.claim(actor())!;
+    f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: command.commandId, operationId: "op-concurrent-terminal", state: "accepted", errorCode: null, result: { threadId: null, turnId: "turn-concurrent", destinationTurnId: null } });
+    const terminal = { protocol: "side_thread.terminal.v1", sideThreadId: "side-concurrent", attemptId: "attempt-concurrent", threadId: "derived-concurrent", turnId: "turn-concurrent", status: "completed", text: "answer", errorCode: null };
+    const url = new URL("http://hub/api/nodes/node-1/side-thread-commands/terminals");
+    const call = () => handleSideThreadCommandRequest({ req: new Request(url, { method: "POST", body: JSON.stringify(terminal) }), url, actor: actor(), store: f.store, port: f.port });
+    const first = call(); await Bun.sleep(10);
+    const second = await call();
+    expect(second?.status).toBe(503);
+    expect(await second?.json()).toMatchObject({ ok: false, retryable: true });
+    release();
+    expect((await first)?.status).toBe(409);
+    expect(f.store.terminalApplyState(["side-concurrent", "attempt-concurrent", "derived-concurrent", "turn-concurrent"])).toBe("received");
+  });
+
+  test("real coordinator database failure rejects apply and leaves receipt retryable", async () => {
+    const f = fixture();
+    const sideStore = new SideThreadStore(f.db);
+    const coordinator = new SideThreadCoordinator(sideStore, f.port, { enabled: true, authorizeNode: () => true });
+    await f.port.start({ operationId: "op-db-fail", requestKey: "rk-db-fail", sideChatId: "side-db", attemptId: "attempt-db", nodeId: "node-1", threadId: "derived-db", prompt: "q", attachments: [] }).catch(() => {});
+    const command = f.store.claim(actor())!;
+    f.store.ack(actor(), { protocol: "side_thread.ack.v1", commandId: command.commandId, operationId: "op-db-fail", state: "accepted", errorCode: null, result: { threadId: null, turnId: "turn-db", destinationTurnId: null } });
+    const original = f.db.transaction.bind(f.db);
+    (f.db as any).transaction = () => { throw new Error("disk I/O failure"); };
+    const terminal = { protocol: "side_thread.terminal.v1", sideThreadId: "side-db", attemptId: "attempt-db", threadId: "derived-db", turnId: "turn-db", status: "completed", text: "answer", errorCode: null };
+    await expect(f.port.acceptTerminal(actor(), terminal)).rejects.toThrow(/disk I\/O/);
+    expect(f.store.terminalApplyState(["side-db", "attempt-db", "derived-db", "turn-db"])).toBe("received");
+    (f.db as any).transaction = original;
+    coordinator.close();
+  });
+});