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

package/src/uploads.ts

@@ -53,6 +53,17 @@ export const UPLOAD_RATE_MAX_ENTRIES = 50_000;
 // traversal.
 export const FILE_ID_REGEX = /^[A-Za-z0-9_-]{8,64}$/;
 
+// Stored extension tokens have one invariant at every path boundary:
+// either no extension, or a leading dot followed by 1-16 ASCII
+// alphanumeric characters. Keep this separate from sanitizeExt(), which
+// parses a client filename and therefore deliberately has different
+// capture/anchoring semantics.
+const EXT_TOKEN_REGEX = /^\.[A-Za-z0-9]{1,16}$/;
+
+function isValidExtToken(ext: unknown): ext is string {
+  return typeof ext === "string" && (ext === "" || EXT_TOKEN_REGEX.test(ext));
+}
+
 export type GeneratedFile = {
   fileId: string;
   ext: string;
@@ -94,14 +105,51 @@ export function sanitizeExt(filename: string | undefined | null): string {
   return match ? "." + match[1].toLowerCase() : "";
 }
 
+// YYYY-MM-DD bucket string regex — matches what getDateBucket produces
+// and what an index entry's `date_bucket` field is validated against.
+const DATE_BUCKET_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
 /**
- * Build the per-upload storage path. The file_id and ext are validated
- * against strict regexes; any path-separator or `..` segment from a
- * malicious client gets rejected at the regex layer before any I/O.
+ * Validate a date_bucket string against BOTH shape (YYYY-MM-DD regex)
+ * AND real-calendar semantics: rejects "2026-02-30", "2026-13-01",
+ * "2026-00-15", leap-day-on-non-leap-year, etc. Shape-only check is not
+ * enough because the regex accepts any digit combination in each
+ * position.
+ *
+ * Used as a pre-check by the download handler before it calls into
+ * pathForExistingBlob — a non-calendar bucket is a 404 (invalid input
+ * rejected at the boundary), NOT a 500 (uncaught throw from deep in
+ * the read path). Distinguishing these matters: 500 says "server
+ * failed"; 404 says "we know your request is bad, refused early".
+ */
+export function isValidCalendarBucket(bucket: unknown): bucket is string {
+  if (typeof bucket !== "string") return false;
+  if (!DATE_BUCKET_REGEX.test(bucket)) return false;
+  // Round-trip via Date to reject non-calendar shapes like "2026-02-30"
+  // or "2026-13-01". `Date.UTC` coerces overflow ("2026-02-30" becomes
+  // "2026-03-02") — if the ISO round-trip doesn't equal the input, the
+  // caller supplied a non-calendar bucket.
+  const [yStr, mStr, dStr] = bucket.split("-");
+  const y = Number(yStr), m = Number(mStr), d = Number(dStr);
+  if (m < 1 || m > 12) return false;
+  if (d < 1 || d > 31) return false;
+  const roundtrip = new Date(Date.UTC(y, m - 1, d)).toISOString().slice(0, 10);
+  return roundtrip === bucket;
+}
+
+/**
+ * Build the storage path for a NEW upload. Computes today's date bucket
+ * from the runtime clock (or `opts.now` for tests). Use ONLY for creating
+ * a fresh blob; for reading an existing blob whose bucket is already
+ * recorded in the index, use pathForExistingBlob() instead.
+ *
+ * The file_id and ext are validated against strict regexes; any
+ * path-separator or `..` segment from a malicious client gets rejected
+ * at the regex layer before any I/O.
  */
 export function buildStoragePath(fileId: string, ext: string, opts: { uploadsRoot?: string; now?: Date } = {}): GeneratedFile {
   if (!FILE_ID_REGEX.test(fileId)) throw new Error(`file_id "${fileId}" is invalid`);
-  if (ext && !/^\.[A-Za-z0-9]{1,16}$/.test(ext)) throw new Error(`ext "${ext}" is invalid`);
+  if (!isValidExtToken(ext)) throw new Error(`ext "${ext}" is invalid`);
   const dateBucket = getDateBucket(opts.now);
   const root = opts.uploadsRoot ?? getUploadsRoot();
   const relativePath = join(dateBucket, fileId + ext);
@@ -109,6 +157,32 @@ export function buildStoragePath(fileId: string, ext: string, opts: { uploadsRoo
   return { fileId, ext, dateBucket, relativePath, absolutePath };
 }
 
+/**
+ * Build the storage path for an EXISTING blob, using the caller-supplied
+ * `dateBucket` (typically read from the index entry). Does NOT compute
+ * a date from the runtime clock — that is the write-side concern.
+ *
+ * This split exists because sharing one date-computing function between
+ * write and read semantics caused #509: yesterday's file downloaded
+ * today would look under today's bucket → blob_missing → 404, even
+ * though the blob was still sitting in yesterday's directory.
+ *
+ * The file_id, ext and dateBucket are validated against strict regexes
+ * before any I/O; a poisoned index bucket (e.g. `../etc`) is rejected
+ * here just as file_id path-escape attempts are.
+ */
+export function pathForExistingBlob(dateBucket: string, fileId: string, ext: string, opts: { uploadsRoot?: string } = {}): GeneratedFile {
+  if (!FILE_ID_REGEX.test(fileId)) throw new Error(`file_id "${fileId}" is invalid`);
+  if (!isValidExtToken(ext)) throw new Error(`ext "${ext}" is invalid`);
+  if (typeof dateBucket !== "string" || !DATE_BUCKET_REGEX.test(dateBucket)) {
+    throw new Error(`date_bucket "${dateBucket}" is invalid`);
+  }
+  const root = opts.uploadsRoot ?? getUploadsRoot();
+  const relativePath = join(dateBucket, fileId + ext);
+  const absolutePath = join(root, relativePath);
+  return { fileId, ext, dateBucket, relativePath, absolutePath };
+}
+
 export type UploadIndexEntry = {
   file_id: string;
   date_bucket: string; // YYYY-MM-DD
@@ -117,6 +191,15 @@ export type UploadIndexEntry = {
   mime: string;        // best-effort mime from the multipart Content-Type
   size: number;        // byte length of the binary
   owner?: string;      // upload token id / username, for traceability
+  // Written by the upload handler as `authCtx?.userId ?? null`, so `null`
+  // is a real on-disk value — the type must say so rather than pretend
+  // the field is `string | undefined`.
+  owner_id?: string | null;
+  // #503 — network the upload is attributed to. The key is OMITTED (not
+  // written as null) when there is no attribution, so "absent" and
+  // "unattributed" are the same on-disk shape and legacy entries written
+  // before #503 are indistinguishable from new unattributed ones.
+  network_id?: string;
   uploaded_at: string; // ISO 8601
 };
 
@@ -135,10 +218,16 @@ export function indexEntryPath(fileId: string, opts: { uploadsRoot?: string } =
 export function validateIndexEntry(entry: unknown): entry is UploadIndexEntry {
   if (!entry || typeof entry !== "object") return false;
   const e: any = entry;
+  // #503 — if the network_id key is present it must be a non-empty string.
+  // An absent key is valid (legacy entries + unattributed uploads); that
+  // keeps this in sync with the writer, which omits the key entirely
+  // rather than writing null. owner_id is deliberately NOT constrained
+  // here — existing entries legitimately carry owner_id=null.
+  if ("network_id" in e && !(typeof e.network_id === "string" && e.network_id.length > 0)) return false;
   return (
     typeof e.file_id === "string" && FILE_ID_REGEX.test(e.file_id) &&
     typeof e.date_bucket === "string" && /^\d{4}-\d{2}-\d{2}$/.test(e.date_bucket) &&
-    typeof e.ext === "string" && (e.ext === "" || /^\.[A-Za-z0-9]{1,16}$/.test(e.ext)) &&
+    isValidExtToken(e.ext) &&
     typeof e.size === "number" && e.size >= 0 && e.size <= MAX_UPLOAD_BYTES
   );
 }
@@ -241,6 +330,42 @@ export type TaskAttachment = {
   size?: number;
 };
 
+/**
+ * #222 cross-host attachment safety — strip `path` from meta.attachments
+ * entries that ALSO carry a `file_id`. Reason: the hub's /api/upload
+ * returns `{file_id, path}` where `path` is a hub-machine-local
+ * absolute path. Senders sometimes echo `path` back into meta.attachments.
+ * When the receiving agent runs on a different host (Vincent 2026-06-30
+ * a partner-team host case), that path string is meaningless. agent-node's
+ * fetch-attachment.ts will fetch via `file_id` regardless, but leaving
+ * the stale `path` in the JSON misleads any tooling that reads it.
+ *
+ * CRITICAL — conditional, not unconditional (通信龙 PR #222 pre-review
+ * nit): feishu-bridge currently writes `/work/feishu-attachments/<conn>/
+ * <chat>/` directly and ships path-only attachments (NO file_id). If we
+ * strip path unconditionally those break too. Only strip when file_id
+ * is present (the "safe to drop" signal). Single-host feishu fallback
+ * preserved.
+ *
+ * Shared by tools.ts (MCP send_task) and index.ts (REST /api/task) so
+ * both transports apply the same sanitization to meta.
+ */
+export function stripHostLocalPathsForCrossHostSafe(meta: any): any {
+  if (!meta || typeof meta !== "object") return meta;
+  if (!Array.isArray((meta as any).attachments)) return meta;
+  let mutated = false;
+  const sanitized = (meta as any).attachments.map((a: any) => {
+    if (a && typeof a === "object" && typeof a.file_id === "string" && a.file_id && typeof a.path === "string") {
+      mutated = true;
+      const { path: _stripped, ...rest } = a;
+      return rest;
+    }
+    return a;
+  });
+  if (!mutated) return meta;
+  return { ...meta, attachments: sanitized };
+}
+
 /** Light validator usable from the REST handler. Returns null on success or an error message string. */
 export function validateAttachments(input: unknown): { ok: true; attachments: TaskAttachment[] } | { ok: false; error: string } {
   if (input === undefined || input === null) return { ok: true, attachments: [] };

package/src/user-inbox-by-agent-http.test.ts

@@ -0,0 +1,161 @@
+// #1828 —— /api/messages?scope=user 按 agent 分的未读 + 用户 ack 覆盖 inbox 里的回复行。
+//
+// 生产 hub 24h:admin 收到的 70 条 agent 回复全在 `inbox`(session_name='admin', type='reply',
+// acked 永远 0),`user_inbox` 只有 2 行;角标链只读 user_inbox,所以回复从不进未读(app#260)。
+// 这里让 scope=user 同时给 `unread_by_agent`(两表合并)与 `unread_total`,`unread`/`pending_count`
+// 口径不动(qa-hub-14 钉着);POST /api/messages/ack 也能 ack inbox 里发给调用者用户名的回复行。
+//
+// 承重的是两条边界:
+//   ① 只算/只 ack **调用者自己用户名** 的 inbox 行 —— B 拿 A 的 id 来 ack 匹配不到;
+//   ② 用户名与某节点 alias 撞名时,inbox 那半边整体跳过(那是节点的待办,不是用户的)。
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-user-inbox-by-agent-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
+
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let aToken = "", bToken = "", cToken = "";
+let aUserId = "", bUserId = "", cUserId = "", aNet = "", cNet = "";
+let aName = "", bName = "", cName = "";
+
+const get = async (path: string, token: string) => {
+  const r = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: r.status, body: await r.json() as any };
+};
+const post = async (path: string, token: string, body: unknown) => {
+  const r = await fetch(`${base}${path}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return { status: r.status, body: await r.json() as any };
+};
+
+function seedUserInbox(mid: string, userId: string, netId: string, from: string) {
+  const { db } = require("./db.js");
+  db.run(
+    `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json, acked)
+     VALUES (?1, ?2, ?3, ?4, 'agent_message', NULL, 'dm', 'info', NULL, 0)`,
+    [mid, netId, userId, from],
+  );
+}
+function seedInbox(id: string, sessionName: string, netId: string, from: string, type = "reply", acked = 0) {
+  const { db } = require("./db.js");
+  db.run(
+    `INSERT INTO inbox (id, session_name, type, priority, content, from_session, acked, network_id, created_at)
+     VALUES (?1, ?2, ?3, 'normal', 'reply body', ?4, ?5, ?6, datetime('now'))`,
+    [id, sessionName, type, from, acked, netId],
+  );
+}
+
+beforeAll(async () => {
+  process.env.COMMHUB_AUTH_TOKEN ||= "legacy-master-token-for-test";
+  const { db } = await import("./db.js");
+  const { register, addNetworkMember } = await import("./auth.js");
+  const stamp = Date.now();
+
+  // 首个注册用户 = 全局 admin;探针 A/B/C 都不是 admin(admin 走不过滤分支,隔离断言会白过)。
+  const admin = register(`uba_admin_${stamp}`, "UbaAdmin-Strong-1!");
+  expect(admin.ok).toBe(true);
+  aName = `uba_a_${stamp}`; bName = `uba_b_${stamp}`; cName = `uba_c_${stamp}`;
+  const a = register(aName, "UbaA-Strong-1!");
+  const b = register(bName, "UbaB-Strong-1!");
+  const c = register(cName, "UbaC-Strong-1!");
+  expect(a.ok && b.ok && c.ok).toBe(true);
+  aToken = a.token!; bToken = b.token!; cToken = c.token!;
+  aNet = a.network_id!; cNet = c.network_id!;
+  const uid = (name: string) => db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", name)!.user_id;
+  aUserId = uid(aName); bUserId = uid(bName); cUserId = uid(cName);
+  for (const id of [aUserId, bUserId, cUserId]) {
+    expect(db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", id)?.role).toBe("user");
+  }
+  // B 与 A 同网:user_id / session_name 过滤是唯一的隔离手段。
+  expect(addNetworkMember(aNet, bUserId, "member").ok).toBe(true);
+
+  // A:user_inbox 两条(node-x),inbox 回复两条(peer-1)+ 一条已 ack + 一条 status 类(不算)。
+  seedUserInbox("dm_a1", aUserId, aNet, "node-x");
+  seedUserInbox("dm_a2", aUserId, aNet, "node-x");
+  seedInbox("ib_a1", aName, aNet, "peer-1");
+  seedInbox("ib_a2", aName, aNet, "peer-1");
+  seedInbox("ib_a_acked", aName, aNet, "peer-1", "reply", 1);
+  seedInbox("ib_a_status", aName, aNet, "peer-1", "status");
+  // B 同网:自己的一条回复;不该出现在 A 的数里。
+  seedInbox("ib_b1", bName, aNet, "peer-2");
+  // C:用户名撞节点 alias —— inbox 里那行是节点的待办。
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at)
+     VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [`node_${stamp}`, cName, cName, cNet],
+  );
+  seedInbox("ib_c_node_task", cName, cNet, "leader", "task");
+  seedUserInbox("dm_c1", cUserId, cNet, "node-y");
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+});
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("#1828 GET /api/messages?scope=user unread_by_agent", () => {
+  test("A:user_inbox + inbox 回复按 agent 合并;unread/pending_count 口径不变", async () => {
+    const { status, body } = await get("/api/messages?scope=user", aToken);
+    expect(status).toBe(200);
+    expect(body.unread).toBe(2);                 // 只算 user_inbox(qa-hub-14 钉着)
+    expect(body.pending_count).toBe(2);
+    expect(body.unread_by_agent).toEqual({ "node-x": 2, "peer-1": 2 }); // 已 ack 与 status 类不算
+    expect(body.unread_total).toBe(4);
+  });
+
+  test("B(同网):只看到自己的回复,看不到 A 的", async () => {
+    const { body } = await get("/api/messages?scope=user", bToken);
+    expect(body.unread_by_agent).toEqual({ "peer-2": 1 });
+    expect(body.unread_total).toBe(1);
+  });
+
+  test("🔴 C 的用户名撞节点 alias:inbox 半边整体跳过,只剩 user_inbox", async () => {
+    const { body } = await get("/api/messages?scope=user", cToken);
+    expect(body.unread_by_agent).toEqual({ "node-y": 1 });
+    expect(body.unread_total).toBe(1);
+  });
+});
+
+describe("#1828 POST /api/messages/ack covers inbox reply rows", () => {
+  test("🔴 B 拿 A 的 inbox id 来 ack:匹配不到,A 的数不动", async () => {
+    const { body } = await post("/api/messages/ack", bToken, { message_ids: ["ib_a1"] });
+    expect(body).toMatchObject({ ok: true, acked: 0, acked_inbox: 0 });
+    const a = await get("/api/messages?scope=user", aToken);
+    expect(a.body.unread_by_agent["peer-1"]).toBe(2);
+  });
+
+  test("A ack 一条 inbox 回复 + 一条 user_inbox:两边各减一,响应分开计数", async () => {
+    const { body } = await post("/api/messages/ack", aToken, { message_ids: ["ib_a1", "dm_a1"] });
+    expect(body).toMatchObject({ ok: true, acked: 2, acked_user_inbox: 1, acked_inbox: 1 });
+    const a = await get("/api/messages?scope=user", aToken);
+    expect(a.body.unread).toBe(1);
+    expect(a.body.unread_by_agent).toEqual({ "node-x": 1, "peer-1": 1 });
+    expect(a.body.unread_total).toBe(2);
+    // 再 ack 同一条:幂等,0 行。
+    const again = await post("/api/messages/ack", aToken, { message_ids: ["ib_a1"] });
+    expect(again.body.acked).toBe(0);
+  });
+
+  test("status 类 inbox 行不会被用户 ack 掉(不是发给用户的消息)", async () => {
+    const { body } = await post("/api/messages/ack", aToken, { message_ids: ["ib_a_status"] });
+    expect(body.acked_inbox).toBe(0);
+  });
+
+  test("🔴 C 撞名:节点的待办不能被用户 ack 走", async () => {
+    const { body } = await post("/api/messages/ack", cToken, { message_ids: ["ib_c_node_task"] });
+    expect(body.acked_inbox).toBe(0);
+    const { db } = require("./db.js");
+    expect(db.get<{ acked: number }>("SELECT acked FROM inbox WHERE id = 'ib_c_node_task'")?.acked).toBe(0);
+  });
+});

package/src/user-inbox-netid-notnull.test.ts

@@ -0,0 +1,122 @@
+// #1493 — user_inbox.network_id 升 schema 级 NOT NULL(belt-and-suspenders)。
+//
+// 「不产生 NULL 孤儿」原是代码级三闸(#1492 证不可达)。schema 级 NOT NULL 让**任何**
+// 未来绕过那三闸写 NULL 的回归在 INSERT 处被 DB 直接拒,而不是产出 scoped-unreadable
+// 的静默孤儿。生产 hub 已在 preview.41、user_inbox 有真实行 → 迁移必须:① 新库直接
+// NOT NULL;② 存量库无损重建(建新表→copy→drop→rename);③ 迁移前若发现 NULL 行(理应
+// 为 0)fail-closed 停下,不静默丢。
+//
+// 后两条要预置「旧 schema(nullable)」的库 → 用 bun:sqlite 手造库 + 子进程 import db.js
+// 触发迁移(与 boot-side-effect.test.ts 同款子进程范式)。
+
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { db } from "./db.js";
+
+const OLD_SCHEMA = `CREATE TABLE user_inbox (
+  message_id TEXT PRIMARY KEY, network_id TEXT, user_id TEXT NOT NULL, from_session TEXT,
+  kind TEXT NOT NULL DEFAULT 'info', title TEXT, content TEXT NOT NULL,
+  severity TEXT NOT NULL DEFAULT 'info', meta_json TEXT, acked INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')), acked_at TEXT)`;
+
+/** 预置一个「旧 schema(network_id 可空)」的库文件,可选带若干行。返回文件路径。 */
+function seedOldDb(rows: Array<{ mid: string; net: string | null; user: string }>): string {
+  const file = join(mkdtempSync(join(tmpdir(), "anet-1493-")), "hub.db");
+  const raw = new Database(file);
+  raw.exec(OLD_SCHEMA);
+  for (const r of rows) {
+    raw.run("INSERT INTO user_inbox (message_id, network_id, user_id, content) VALUES (?1, ?2, ?3, 'body')",
+      [r.mid, r.net, r.user]);
+  }
+  raw.close();
+  return file;
+}
+
+/** 子进程里 import db.js(触发迁移),回读一段结果。返回 {exitCode, stdout, stderr}。 */
+function bootWithDb(file: string, probe: string) {
+  const script = `
+    process.env.COMMHUB_DB = ${JSON.stringify(file)};
+    const { db } = await import("./src/db.js");
+    ${probe}
+    process.exit(0);
+  `;
+  const child = Bun.spawnSync({
+    cmd: ["bun", "-e", script],
+    cwd: `${import.meta.dir}/..`,
+    env: { ...process.env, COMMHUB_DB: file },
+    timeout: 20_000,
+  });
+  return {
+    exitCode: child.exitCode,
+    stdout: new TextDecoder().decode(child.stdout),
+    stderr: new TextDecoder().decode(child.stderr),
+  };
+}
+
+describe("#1493 user_inbox.network_id NOT NULL (belt-and-suspenders)", () => {
+  test("new DB: network_id is NOT NULL and rejects a NULL insert", () => {
+    const col = db.all<{ name: string; notnull: number }>("PRAGMA table_info(user_inbox)").find(c => c.name === "network_id");
+    expect(col?.notnull).toBe(1);
+    // 绕过代码闸直接写 NULL → DB 拒(这正是 belt-and-suspenders 的价值)
+    expect(() => db.run(
+      "INSERT INTO user_inbox (message_id, user_id, content) VALUES (?1, ?2, ?3)",
+      [`dm_nn_${Date.now()}`, "u_nn", "hi"],
+    )).toThrow(/NOT NULL/i);
+  });
+
+  test("migration: old nullable table with valid rows → rebuilt NOT NULL, rows preserved, index recreated", () => {
+    const file = seedOldDb([
+      { mid: "dm_1", net: "net_a", user: "u_1" },
+      { mid: "dm_2", net: "net_b", user: "u_2" },
+    ]);
+    const r = bootWithDb(file, `
+      const col = db.all("PRAGMA table_info(user_inbox)").find(c => c.name === "network_id");
+      const rows = db.get("SELECT COUNT(*) AS n FROM user_inbox").n;
+      const idx = db.get("SELECT COUNT(*) AS n FROM sqlite_master WHERE type='index' AND name='idx_user_inbox_user_acked'").n;
+      let nullRejected = false;
+      try { db.run("INSERT INTO user_inbox (message_id, user_id, content) VALUES ('dm_z','u_z','x')"); }
+      catch { nullRejected = true; }
+      console.log("RESULT:" + JSON.stringify({ notnull: col.notnull, rows, idx, nullRejected }));
+    `);
+    expect(r.exitCode).toBe(0);
+    const m = r.stdout.match(/RESULT:(\{.*\})/);
+    expect(m).not.toBeNull();
+    const out = JSON.parse(m![1]);
+    expect(out.notnull).toBe(1);      // 迁移后 NOT NULL
+    expect(out.rows).toBe(2);          // 两行无损保留
+    expect(out.idx).toBe(1);           // 索引重建
+    expect(out.nullRejected).toBe(true);
+  });
+
+  test("migration guard: old table with a network_id IS NULL row → fail-safe (warn + skip, hub boots, data intact)", () => {
+    const file = seedOldDb([
+      { mid: "dm_ok", net: "net_a", user: "u_1" },
+      { mid: "dm_orphan", net: null, user: "u_2" },   // 理应不可达;若真出现 → warn+跳过,不停机
+    ]);
+    const r = bootWithDb(file, `
+      const col = db.all("PRAGMA table_info(user_inbox)").find(c => c.name === "network_id");
+      const rows = db.get("SELECT COUNT(*) AS n FROM user_inbox").n;
+      console.log("RESULT:" + JSON.stringify({ notnull: col.notnull, rows }));
+    `);
+    expect(r.exitCode).toBe(0);                          // hub 照常启动(fail-safe,不停机)
+    expect(r.stderr).toMatch(/migrate #1493/);            // 大声 warn(明确运维信号)
+    expect(r.stderr).toMatch(/network_id IS NULL/);
+    const m = r.stdout.match(/RESULT:(\{.*\})/);
+    expect(m).not.toBeNull();
+    const out = JSON.parse(m![1]);
+    expect(out.notnull).toBe(0);                          // 迁移被跳过 → 列暂保持可空
+    expect(out.rows).toBe(2);                             // 数据没丢(没盲目清空)
+  });
+
+  test("idempotent: booting an already-migrated (NOT NULL) DB twice is a no-op", () => {
+    const file = seedOldDb([{ mid: "dm_a", net: "net_a", user: "u_1" }]);
+    const r1 = bootWithDb(file, `console.log("RESULT:" + db.all("PRAGMA table_info(user_inbox)").find(c=>c.name==="network_id").notnull);`);
+    expect(r1.exitCode).toBe(0);
+    const r2 = bootWithDb(file, `console.log("RESULT:" + db.all("PRAGMA table_info(user_inbox)").find(c=>c.name==="network_id").notnull);`);
+    expect(r2.exitCode).toBe(0);
+    expect(r2.stdout).toContain("RESULT:1");              // 第二次仍 NOT NULL、不炸
+  });
+});