@sleep2agi/commhub-server 0.9.0-preview.93 → 0.9.0-preview.95

package/src/requirement-due-reminders.ts

@@ -0,0 +1,310 @@
+// #491 / #492 —— 任务到期提醒(Hub 侧)。
+//
+// 每 COMMHUB_DUE_REMINDER_TICK_MS(默认 10 分钟)扫一次「没完成、没归档、有预计完成时间」的卡,按下面三种发提醒:
+//   due_soon  即将到期:日期型 due = 明天;时刻型 due 在 24 小时内(且不是今天)。每个 due 值一次。
+//   due_today 今天到期:日期型 due = 今天;时刻型 due 落在今天且还没到。每个 due 值一次。
+//   overdue   已逾期 N 天:每个自然日最多一次;逾期超过 COMMHUB_DUE_OVERDUE_MAX_DAYS(默认 7)天后不再提醒
+//             (上线当天不会把几个月前的旧卡一次性刷一遍,也不会天天提醒一张早被遗忘的卡)。
+// 「今天 / 明天 / 自然日」按 COMMHUB_DUE_REMINDER_TZ(默认 Asia/Shanghai)算。网络没有时区设置;due 的存法不变:
+//   日期型原样「YYYY-MM-DD」(requirements.ts normalizeDue:全天,客户端按查看者本地理解),时刻型是 UTC 秒。
+//
+// 收件人:
+//   人 —— 负责人(owner)+ 参与人里的人,去重。走 #462/#464 的 Hub 通知路(agent-notice.ts:user_inbox +
+//         /events/users/me desktop_message)。发信别名 = 负责 Agent 的别名(收件人看得见它时 → 出现在与它的会话里),
+//         否则 DUE_REMINDER_SENDER「任务提醒」。
+//   负责 Agent(agent_owner 节点)—— 一条不需要回复的消息:与 send_message 同一写法(inbox type='message' +
+//         new_message 推送),不是任务。节点不在 active 状态(停了 / 删除中)就不发。
+// 停止:卡完成 / 归档 / 清空 due → 扫描查询本身就选不到它;due 往后挪 → 那一档不再成立,而新 due 值重新上膛。
+// 去重:requirement_due_reminders 主键 (requirement_id, kind, due_on, day),先 INSERT … ON CONFLICT DO NOTHING
+//   抢到这一行(changes = 1)才发 —— 重启、多次扫描、并发都不会重发。宁可漏一次(发送中途崩溃),不发两次。
+// 只加表:旧 Hub 回滚后不认识这张表也不碰它。
+//
+// 上线护栏(生产上有别的团队的网络和节点):
+//   COMMHUB_DUE_REMINDER_NETWORKS=<id,id,…>  只给这些网络发;不设 = 所有网络(自建 Hub 默认就有这个功能)。
+//   COMMHUB_DUE_REMINDER_NODES=1              给负责 Agent 节点发消息;默认关(人照常提醒)。
+//   开通时不补发:每个网络第一次被扫描到时记一行基线(kind='baseline',sent_at = 那一刻)。只有在基线**之后**才变成逾期的卡
+//     会收到「已逾期」提醒;基线之前就已经逾期的卡永远不发逾期提醒(打开功能 / 把网络加进白名单都不会刷一批旧卡)。
+//     选这个而不是「把旧卡逐张记成已发」:不用每卡每天写行,也不怕某张旧卡第一次没被扫到、第二天又冒出来。
+//     即将到期 / 今天到期不受基线影响(它们本来就只在临近时发一次)。
+
+import type { DbAdapter } from "./db-adapter.js";
+import { db, uuidv4 } from "./db.js";
+import { sendAgentNotice } from "./agent-notice.js";
+import { canSeeAgent } from "./agent-access.js";
+import { assertNodeActive } from "./lifecycle-guard.js";
+import { pushEvent } from "./push.js";
+import { pendingInboxCount } from "./inbox-count.js";
+import { parseHubTimestamp } from "./hub-timestamp.js";
+
+export const DUE_REMINDER_KIND = "task_due";
+export const DUE_REMINDER_SENDER = "任务提醒";
+export type DueKind = "due_soon" | "due_today" | "overdue";
+
+const DAY_MS = 86_400_000;
+const RETENTION_DAYS = 60;
+
+/** IF NOT EXISTS:重复执行无副作用;SQLite / PostgreSQL 同一段。 */
+export function ensureDueReminders(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_due_reminders (
+      requirement_id TEXT NOT NULL,
+      kind           TEXT NOT NULL,
+      due_on         TEXT NOT NULL,
+      day            TEXT NOT NULL,
+      network_id     TEXT NOT NULL,
+      sent_at        TEXT NOT NULL,
+      PRIMARY KEY (requirement_id, kind, due_on, day)
+    );
+  `);
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_due_reminders_sent ON requirement_due_reminders(sent_at)");
+  // 扫描查询按 due_on 取一段范围:只给有 due 的行建索引。
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirements_due_on ON requirements(due_on) WHERE due_on IS NOT NULL");
+}
+
+function envNumber(name: string, fallback: number, min: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= min ? n : fallback;
+}
+
+export function dueReminderTimezone(): string {
+  const tz = process.env.COMMHUB_DUE_REMINDER_TZ?.trim() || "Asia/Shanghai";
+  try { new Intl.DateTimeFormat("en-US", { timeZone: tz }); return tz; } catch { return "Asia/Shanghai"; }
+}
+/** COMMHUB_DUE_REMINDER_NETWORKS:逗号分隔的网络 id;没设(或只有空白)→ null = 所有网络。 */
+export function reminderNetworks(): string[] | null {
+  const raw = process.env.COMMHUB_DUE_REMINDER_NETWORKS;
+  if (raw === undefined) return null;
+  const ids = raw.split(",").map((x) => x.trim()).filter(Boolean);
+  return ids.length ? ids : null;
+}
+export function nodeRemindersEnabled(): boolean { return process.env.COMMHUB_DUE_REMINDER_NODES === "1"; }
+export const BASELINE_KIND = "baseline";
+
+export function overdueMaxDays(): number { return Math.floor(envNumber("COMMHUB_DUE_OVERDUE_MAX_DAYS", 7, 0)); }
+
+// ── 时区小工具 ─────────────────────────────────────────────
+/** 某一时刻在 tz 的日期「YYYY-MM-DD」。 */
+export function localDate(ms: number, tz: string): string {
+  return new Intl.DateTimeFormat("en-CA", { timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit" }).format(new Date(ms));
+}
+/** 日期 + n 天(纯日历运算,与时区无关)。 */
+export function addDays(date: string, n: number): string {
+  const [y, m, d] = date.split("-").map(Number);
+  return new Date(Date.UTC(y, m - 1, d) + n * DAY_MS).toISOString().slice(0, 10);
+}
+/** 两个日期相差几天(a - b)。 */
+export function dayDiff(a: string, b: string): number {
+  const ms = (s: string) => { const [y, m, d] = s.split("-").map(Number); return Date.UTC(y, m - 1, d); };
+  return Math.round((ms(a) - ms(b)) / DAY_MS);
+}
+function tzOffsetMs(ms: number, tz: string): number {
+  const p = Object.fromEntries(new Intl.DateTimeFormat("en-US", { timeZone: tz, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit" })
+    .formatToParts(new Date(ms)).filter((x) => x.type !== "literal").map((x) => [x.type, Number(x.value)]));
+  return Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second) - Math.floor(ms / 1000) * 1000;
+}
+/** tz 里某天 00:00 对应的 UTC 时刻(ms)。 */
+export function localMidnightMs(date: string, tz: string): number {
+  const [y, m, d] = date.split("-").map(Number);
+  const guess = Date.UTC(y, m - 1, d);
+  let t = guess - tzOffsetMs(guess, tz);
+  t = guess - tzOffsetMs(t, tz);
+  return t;
+}
+
+const isDateOnly = (due: string) => due.length === 10;
+
+/** 从哪一刻起算逾期:日期型 = tz 里第二天零点;时刻型 = 那个时刻。 */
+export function overdueSinceMs(due: string, tz: string): number {
+  return isDateOnly(due) ? localMidnightMs(addDays(due, 1), tz) : Date.parse(due);
+}
+
+/** 这张卡此刻该发哪一档(没有 → null)。day = 去重用的那一天。 */
+export function dueReminderFor(due: string, nowMs: number, tz: string, maxOverdue = overdueMaxDays()): { kind: DueKind; day: string; overdueDays: number; dueDay: string } | null {
+  const today = localDate(nowMs, tz);
+  if (isDateOnly(due)) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(due)) return null;
+    if (due === today) return { kind: "due_today", day: due, overdueDays: 0, dueDay: due };
+    if (due === addDays(today, 1)) return { kind: "due_soon", day: due, overdueDays: 0, dueDay: due };
+    if (due < today) {
+      const n = dayDiff(today, due);
+      return n <= maxOverdue ? { kind: "overdue", day: today, overdueDays: n, dueDay: due } : null;
+    }
+    return null;
+  }
+  const t = Date.parse(due);
+  if (!Number.isFinite(t)) return null;
+  const dueDay = localDate(t, tz);
+  if (t <= nowMs) {
+    const n = dayDiff(today, dueDay);
+    return n <= maxOverdue ? { kind: "overdue", day: today, overdueDays: n, dueDay } : null;
+  }
+  if (dueDay === today) return { kind: "due_today", day: dueDay, overdueDays: 0, dueDay };
+  if (t - nowMs <= DAY_MS) return { kind: "due_soon", day: dueDay, overdueDays: 0, dueDay };
+  return null;
+}
+
+/**
+ * 列表筛选(requirements.ts listFilters)用的条件:overdue / due_within_days。只看没完成的卡。
+ * 日期型(长度 10)按 tz 的「今天」比日期;时刻型(UTC 字符串)按此刻比时刻。字符串比较:两种形状各自同长、同格式。
+ */
+export function overdueSql(params: unknown[], nowMs: number, tz: string): string {
+  const today = localDate(nowMs, tz);
+  const nowIso = new Date(nowMs).toISOString().replace(/\.\d{3}Z$/, "Z");
+  return `(due_on IS NOT NULL AND column_name <> 'done' AND ((length(due_on) = 10 AND due_on < ?${params.push(today)}) OR (length(due_on) > 10 AND due_on <= ?${params.push(nowIso)})))`;
+}
+/** 没逾期、且在 tz 的「今天 + days」那天结束之前到期(0 = 今天内)。 */
+export function dueWithinSql(params: unknown[], days: number, nowMs: number, tz: string): string {
+  const today = localDate(nowMs, tz);
+  const lastDay = addDays(today, days);
+  const endIso = new Date(localMidnightMs(addDays(lastDay, 1), tz)).toISOString().replace(/\.\d{3}Z$/, "Z");
+  const nowIso = new Date(nowMs).toISOString().replace(/\.\d{3}Z$/, "Z");
+  return `(due_on IS NOT NULL AND column_name <> 'done' AND ((length(due_on) = 10 AND due_on >= ?${params.push(today)} AND due_on <= ?${params.push(lastDay)}) OR (length(due_on) > 10 AND due_on > ?${params.push(nowIso)} AND due_on < ?${params.push(endIso)})))`;
+}
+
+// ── 扫描 ───────────────────────────────────────────────────
+type DueRow = {
+  requirement_id: string; network_id: string; seq: number | null; title: string; due_on: string;
+  owner_json: string | null; participants_json: string | null; agent_owner_json: string | null;
+};
+const parse = (raw: string | null) => { try { return raw ? JSON.parse(raw) : null; } catch { return null; } };
+const userIdOf = (ref: unknown): string | null => {
+  const r = ref as { kind?: unknown; id?: unknown } | null;
+  return r && r.kind === "user" && typeof r.id === "string" ? r.id : null;
+};
+
+export function humanRecipients(row: Pick<DueRow, "owner_json" | "participants_json">): string[] {
+  const ids = new Set<string>();
+  const owner = userIdOf(parse(row.owner_json));
+  if (owner) ids.add(owner);
+  const participants = parse(row.participants_json);
+  if (Array.isArray(participants)) for (const p of participants) { const id = userIdOf(p); if (id) ids.add(id); }
+  return [...ids];
+}
+
+function fmtDue(due: string, tz: string): string {
+  if (isDateOnly(due)) return due;
+  const t = Date.parse(due);
+  const s = new Intl.DateTimeFormat("sv-SE", { timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).format(new Date(t));
+  return s;
+}
+
+export function dueReminderText(row: Pick<DueRow, "seq" | "title" | "due_on">, r: { kind: DueKind; overdueDays: number }, tz: string): { title: string; text: string } {
+  const card = `${row.seq ? `#${row.seq} ` : ""}「${row.title}」`;
+  const when = fmtDue(row.due_on, tz);
+  if (r.kind === "due_soon") return { title: "任务即将到期", text: `任务${card}即将到期(预计完成 ${when})。` };
+  if (r.kind === "due_today") return { title: "任务今天到期", text: `任务${card}今天到期(预计完成 ${when})。` };
+  const late = r.overdueDays >= 1 ? `已逾期 ${r.overdueDays} 天` : "已过预计完成时间";
+  return { title: "任务已逾期", text: `任务${card}${late}(预计完成 ${when}),还没有完成。` };
+}
+
+export type DueReminderSent = { requirement_id: string; kind: DueKind; users: string[]; node: string | null };
+
+/**
+ * 跑一次。now 可注入(测试用假时钟)。返回这次真正发出的提醒。
+ * 一条按 due_on 范围走索引的查询取候选;每个候选先抢去重行,抢到才发。
+ */
+export function runDueReminders(opts: { now?: number } = {}): DueReminderSent[] {
+  const nowMs = opts.now ?? Date.now();
+  const tz = dueReminderTimezone();
+  const maxOverdue = overdueMaxDays();
+  const today = localDate(nowMs, tz);
+  // 范围:最老 = 今天 - maxOverdue - 1(UTC 日期 ≤ 本地日期,多留一天);最新 < 今天 + 2(24 小时内的时刻型 UTC 日期 ≤ 明天)。
+  const lo = addDays(today, -maxOverdue - 1);
+  const hi = addDays(today, 2);
+  const allow = reminderNetworks();
+  const sentAt = new Date(nowMs).toISOString();
+  // 基线:范围内每个网络第一次被扫到的那一刻(已有就不动)。一条 INSERT … SELECT。
+  {
+    const bp: unknown[] = [BASELINE_KIND, sentAt];
+    // WHERE 必须有:SQLite 里「INSERT … SELECT … FROM t ON CONFLICT」会把 ON 读成 JOIN 约束(语法错),要一个 WHERE 隔开。
+    const where = ` WHERE 1=1${allow ? ` AND network_id IN (${allow.map((id) => `?${bp.push(id)}`).join(", ")})` : ""}`;
+    db.run(
+      `INSERT INTO requirement_due_reminders (requirement_id, kind, due_on, day, network_id, sent_at)
+       SELECT '__baseline__:' || network_id, ?1, '', '', network_id, ?2 FROM networks${where}
+       ON CONFLICT DO NOTHING`,
+      bp,
+    );
+  }
+  const baselines = new Map(
+    db.all<{ network_id: string; sent_at: string }>("SELECT network_id, sent_at FROM requirement_due_reminders WHERE kind = ?1", BASELINE_KIND)
+      .map((b) => [b.network_id, parseHubTimestamp(b.sent_at)] as const)
+      .filter((e): e is readonly [string, number] => e[1] !== null),
+  );
+  const params: unknown[] = [lo, hi];
+  const netFilter = allow ? ` AND network_id IN (${allow.map((id) => `?${params.push(id)}`).join(", ")})` : "";
+  const rows = db.all<DueRow>(
+    `SELECT requirement_id, network_id, seq, title, due_on, owner_json, participants_json, agent_owner_json
+       FROM requirements
+      WHERE due_on IS NOT NULL AND due_on >= ?1 AND due_on < ?2 AND column_name <> 'done' AND COALESCE(archived, 0) = 0${netFilter}`,
+    ...params,
+  );
+  const out: DueReminderSent[] = [];
+  for (const row of rows) {
+    const r = dueReminderFor(row.due_on, nowMs, tz, maxOverdue);
+    if (!r) continue;
+    if (r.kind === "overdue") {
+      // 基线之前就已经逾期 → 不发(开通时不补发)。没有基线(网络行不存在)= 当作此刻开通。
+      const base = baselines.get(row.network_id) ?? nowMs;
+      if (overdueSinceMs(row.due_on, tz) < base) continue;
+    }
+    try {
+      const claimed = db.run(
+        `INSERT INTO requirement_due_reminders (requirement_id, kind, due_on, day, network_id, sent_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6) ON CONFLICT DO NOTHING`,
+        [row.requirement_id, r.kind, row.due_on, r.day, row.network_id, sentAt],
+      );
+      if (claimed.changes < 1) continue;
+      out.push(deliver(row, r, tz));
+    } catch (e: any) {
+      console.error(`[due-reminders] ${row.requirement_id} ${r.kind} failed: ${e?.message || e}`);
+    }
+  }
+  // 去重行保留 RETENTION_DAYS 天(比逾期上限长得多,删掉的行不会再被需要)。
+  try { db.run("DELETE FROM requirement_due_reminders WHERE sent_at < ?1 AND kind <> ?2", [new Date(nowMs - RETENTION_DAYS * DAY_MS).toISOString(), BASELINE_KIND]); } catch {}
+  return out;
+}
+
+function deliver(row: DueRow, r: { kind: DueKind; overdueDays: number; dueDay: string }, tz: string): DueReminderSent {
+  const { title, text } = dueReminderText(row, r, tz);
+  const agent = parse(row.agent_owner_json) as { kind?: unknown; id?: unknown } | null;
+  const nodeId = agent?.kind === "node" && typeof agent.id === "string" ? agent.id : null;
+  const node = nodeId
+    ? db.get<{ alias: string | null }>("SELECT alias FROM nodes WHERE node_id = ?1 AND network_id = ?2", nodeId, row.network_id)
+    : null;
+  const alias = node?.alias || null;
+  const meta = { task_notice: { requirement_id: row.requirement_id, seq: row.seq ?? null, network_id: row.network_id, due_reminder: r.kind, due: row.due_on, overdue_days: r.overdueDays } };
+  const users: string[] = [];
+  for (const userId of humanRecipients(row)) {
+    const fromAlias = alias && canSeeAgent(userId, row.network_id, { alias, nodeId }) ? alias : DUE_REMINDER_SENDER;
+    const id = sendAgentNotice({
+      networkId: row.network_id, userId, fromAlias, kind: DUE_REMINDER_KIND, title, text,
+      severity: r.kind === "overdue" ? "warning" : "info", meta, idPrefix: "dm_due_",
+    });
+    if (id) users.push(userId);
+  }
+  let notifiedNode: string | null = null;
+  if (alias && nodeRemindersEnabled() && assertNodeActive(alias, row.network_id).ok) {
+    const id = uuidv4();
+    const message = `[${title}] ${text}\n(这是提醒,不需要回复。requirement_id=${row.requirement_id})`;
+    db.run(
+      `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id)
+       VALUES (?1, ?2, ?3, 'message', 'normal', ?4, ?5, ?6)`,
+      [id, alias, nodeId, message, DUE_REMINDER_SENDER, row.network_id],
+    );
+    pushEvent(alias, { type: "new_message", inbox_count: pendingInboxCount(alias, row.network_id), from: DUE_REMINDER_SENDER, message_id: id }, row.network_id);
+    notifiedNode = alias;
+  }
+  return { requirement_id: row.requirement_id, kind: r.kind as DueKind, users, node: notifiedNode };
+}
+
+/** startHub 里调用。COMMHUB_DUE_REMINDERS=0 关掉;bootServer(测试)不调用它。第一次扫描延后一个间隔外的 30 秒,不和启动抢。 */
+export function startDueReminderTimer(): ReturnType<typeof setInterval> | null {
+  if (process.env.COMMHUB_DUE_REMINDERS === "0") return null;
+  const ms = envNumber("COMMHUB_DUE_REMINDER_TICK_MS", 10 * 60_000, 1_000);
+  const tick = () => { try { runDueReminders(); } catch (e: any) { console.error(`[due-reminders] tick failed: ${e?.message || e}`); } };
+  const first = setTimeout(tick, Math.min(ms, 30_000));
+  (first as any)?.unref?.();
+  return setInterval(tick, ms);
+}

package/src/requirements-errors.ts

@@ -106,6 +106,8 @@ const ENTRIES: Record<string, Entry> = {
   client_id_taken: { field: 'client_id', message: 'That client_id was already used for another task.', hint: 'Generate a new client_id for each new task.' },
   // ── 列表 / 事件 ──
   invalid_view: { field: 'view', message: 'view must be full or summary.' },
+  invalid_overdue: { field: 'overdue', message: 'overdue must be true or false (REST: 1 / 0 / true / false).' },
+  invalid_due_within_days: { field: 'due_within_days', message: 'due_within_days must be an integer from 0 to 365 (0 = due later today).' },
   invalid_limit: { field: 'limit', message: 'limit is out of range.' },
   invalid_cursor: { field: 'cursor', message: 'cursor is not one this hub issued.', hint: 'Pass next_cursor from the previous page unchanged, or start again without cursor.' },
   invalid_updated_since: { field: 'updated_since', message: 'updated_since must be an ISO 8601 time.', hint: 'Use server_time from the previous changes=true response.' },

package/src/requirements.ts

@@ -17,6 +17,7 @@ import {
 } from "./task-access.js";
 import { notifyLeaderDeleted, notifyParticipantChange } from "./requirement-notify.js";
 import { departmentCardsFor, departmentSubtree } from "./department-heads.js";
+import { dueReminderTimezone, dueWithinSql, ensureDueReminders, overdueSql } from "./requirement-due-reminders.js";
 import { diffRequirement, ensureRequirementEvents, eventPublic, recordRequirementEvents, type EventRow } from "./requirement-events.js";
 import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
@@ -31,6 +32,7 @@ ensureRequirementCompletedAt(db);
 ensureNetworkTags(db);
 ensureRequirementTombstones(db);
 ensureRequirementEvents(db);
+ensureDueReminders(db);
 
 type RequestAuth = { userId: string; networkId: string | null; username: string; tokenId?: string | null; tokenName?: string | null } | null;
 
@@ -1132,6 +1134,18 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
     sql += parts.length ? ` AND (${parts.join(" OR ")})` : " AND 1=0";
   }
   if (q.get("top_level") === "1") sql += " AND parent_id IS NULL";
+  // #494 —— 到期筛选(只看没完成的卡;「今天」按到期提醒同一个时区,见 requirement-due-reminders.ts)。
+  const overdue = q.get("overdue");
+  if (overdue !== null) {
+    if (!["1", "true", "0", "false"].includes(overdue)) return jsonError("invalid_overdue", 400);
+    const cond = overdueSql(params, Date.now(), dueReminderTimezone());
+    sql += overdue === "1" || overdue === "true" ? ` AND ${cond}` : ` AND NOT ${cond}`;
+  }
+  const within = q.get("due_within_days");
+  if (within !== null) {
+    if (!/^\d{1,3}$/.test(within) || Number(within) > 365) return jsonError("invalid_due_within_days", 400);
+    sql += ` AND ${dueWithinSql(params, Number(within), Date.now(), dueReminderTimezone())}`;
+  }
   // Explicit archived-only wins over the legacy include-all switch.
   // changes=1 看得见「被归档」这一改动:默认连归档的一起回(行上 archived: true),客户端据此把它移出看板。
   if (q.get("archived") === "true") sql += " AND COALESCE(archived, 0) = 1";
@@ -1480,7 +1494,8 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     // changes 模式:server_time 取在读表之前,下次拿它当 updated_since,读表期间的写入不会漏(>= 会重复回一次,客户端按 id 覆盖)。
     const serverTime = new Date().toISOString();
     nodeReadNote(ctx, "GET /api/requirements", null);
-    const cacheKey = changes || url.searchParams.get("q") ? null : listCacheKey(ctx);
+    // overdue / due_within_days 随时间变化而不随写入变化:不进按 generation 失效的缓存。
+    const cacheKey = changes || url.searchParams.get("q") || url.searchParams.has("overdue") || url.searchParams.has("due_within_days") ? null : listCacheKey(ctx);
     const acl = cacheKey ? listCacheAcl(ctx) : null;
     const generation = requirementsGeneration;
     const cached = cacheKey && acl !== null ? listCache.get(cacheKey) : undefined;

package/src/server.ts

@@ -6,7 +6,7 @@ import { readNodeHealth } from "./node-health-store.js";
 import { wantsAllTools } from "./tool-audience.js";
 import { assertNodeHealthy, degradedLayers } from "./node-health-guard.js";
 import { auditDepartment, createDepartment, deleteDepartment, listDepartments, setMemberDepartment, updateDepartment } from "./departments.js";
-import { addManualMember, canManageGroup, createDepartmentGroup, getDepartmentGroup, groupById, groupViewerCan, isGroupMember, listGroupMembers, listVisibleGroups, readGroup, removeManualMember, renameGroup, syncDepartmentGroups } from "./department-groups.js";
+import { addManualMember, canManageGroup, createDepartmentGroup, getDepartmentGroup, groupById, groupTx, groupViewerCan, isGroupMember, listGroupMembers, listVisibleGroups, readGroup, removeManualMember, renameGroup, syncDepartmentGroups } from "./department-groups.js";
 import { DEPARTMENT_SCOPE_DENIED, departmentLeaders, departmentSubtree, headScope, listDepartmentProjectGrants, managedDepartmentIds, membersIn, replaceDepartmentProjectGrants } from "./department-heads.js";
 import { redactMessageRow } from "./redact-tokens.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -70,6 +70,7 @@ import { resolveRestFromSession } from "./rest-identity.js";
 import { stampTaskAuthOrigin, type TaskAuthOrigin } from "./task-auth-origin.js";
 import { diagnoseTask } from "./task-diagnostic.js";
 import { assertScheduledTaskBackendSupported, handleScheduledTaskRequest, startScheduledTaskScheduler } from "./scheduled-tasks.js";
+import { startDueReminderTimer } from "./requirement-due-reminders.js";
 import { handleRequirementsRequest } from "./requirements.js";
 import { labelRoute, mcpRouteLabel, recordRouteTiming, routeStats, setRouteCallerMasterToken, setRouteCallerTokenReader } from "./route-timing.js";
 import { handleExternalScheduleEditRequest } from "./external-schedule-edits.js";
@@ -1817,7 +1818,7 @@ return Bun.serve({
           if (req.method === "GET") {
             const linked = getDepartmentGroup(netId, deptId);
             // 兜底对账(RFC-042 §4):读之前先把成员对齐,再判「是不是成员」。
-            if (linked) db.transaction(() => { syncDepartmentGroups(netId, linked.id); });
+            if (linked) groupTx(() => { syncDepartmentGroups(netId, linked.id); });
             const group = linked ? getDepartmentGroup(netId, deptId) : null;
             if (!group || (!mayCreate && !isGroupMember(group.id, resolved.user.user_id))) {
               return withCors(req, Response.json({ ok: false, error: "department_group_not_found" }, { status: 404 }));
@@ -4910,6 +4911,8 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
   patrolDeliveredStaleTasks();
   const deliveredStalePatrolTimer = setInterval(patrolDeliveredStaleTasks, deliveredStalePatrolMs);
   const scheduledTaskTimer = startScheduledTaskScheduler();
+  // #492 —— 任务到期提醒(默认每 10 分钟;COMMHUB_DUE_REMINDERS=0 关掉)。bootServer 不起它,测试按需直接调 runDueReminders。
+  const dueReminderTimer = startDueReminderTimer();
 
   // The Bun.serve socket is what keeps the process alive; the periodic
   // jobs must not — otherwise a test (or a future caller) that stops the
@@ -4920,6 +4923,7 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
   (taskPatrolTimer as any)?.unref?.();
   (deliveredStalePatrolTimer as any)?.unref?.();
   (scheduledTaskTimer as any)?.unref?.();
+  (dueReminderTimer as any)?.unref?.();
 
   // ── Graceful shutdown ───────────────────────────────
   function shutdown() {
@@ -4930,6 +4934,7 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
     clearInterval(taskPatrolTimer);
     clearInterval(deliveredStalePatrolTimer);
     clearInterval(scheduledTaskTimer);
+    if (dueReminderTimer) clearInterval(dueReminderTimer);
     db.close();
     process.exit(0);
   }

package/src/tools.ts

@@ -1167,7 +1167,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (node_id) {
         try {
           const nodeRuntime = ag?.includes(":") ? ag.split(":")[1] + "-sdk" : ag ?? null;
-          upsertNodeWithSec1Guard({
+          const upserted = upsertNodeWithSec1Guard({
             node_id,
             callerNetworkId: effectiveNetId ?? null,
             callerUserId: enforceUserId ?? null,
@@ -1182,6 +1182,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             hostname: hn ?? null,
             config_snapshot: cfgSnap ?? null,
           });
+          // The session row above already took node_id; a refused identity claim
+          // must not leave this session pointing at another node's row.
+          if (upserted.result === "refused" && upserted.reason === "identity_mismatch") {
+            db.run("UPDATE sessions SET node_id = NULL WHERE resume_id = ?1 AND node_id = ?2", [resume_id, node_id]);
+          }
         } catch {}
       }
 
@@ -5958,6 +5963,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     parent_id: z.string().max(200).optional().describe("children of this requirement ('none' = top level)"),
     department_id: z.string().max(64).optional().describe("owner (or its Agent's owner) in this department or below"),
     top_level: z.boolean().optional(), q: z.string().max(200).optional(),
+    overdue: z.boolean().optional().describe("true = open tasks past their due (date-only due: before today, Asia/Shanghai); false = everything else"),
+    due_within_days: z.number().int().min(0).max(365).optional().describe("open tasks not yet overdue, due by the end of today + N days (0 = later today)"),
     limit: z.number().int().min(1).max(1000).optional().describe(`page size, default ${REQ_LIST_MCP_DEFAULT_LIMIT}`),
     cursor: z.string().max(600).optional().describe("next_cursor from the previous page"),
     view: z.enum(["full", "summary"]).optional().describe("default summary (no description / checklist bodies; has_description, checklist_count instead); full = everything"),
@@ -5967,7 +5974,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   server.registerTool(
     "requirements_list",
     {
-      description: `List requirement tasks in your network, newest first. Defaults (MCP): view='summary' (no description / checklist bodies; has_description, checklist_count instead; ~0.5 KB per task) and ${REQ_LIST_MCP_DEFAULT_LIMIT} per page; has_more + next_cursor → pass cursor. Full text: requirements_get, or view='full' with a small limit (≤ 1000). Filters: seq (#N), status, project_id ('none'), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), tag (exact), updated_since (ISO), external_ref, parent_id / top_level, department_id (owner in it or below), include_archived; q searches title / description / people / project / tags (terms ANDed). Rows carry children {total, done}. changes=true (with updated_since) returns only tasks changed since then, archived included, plus deleted ids and server_time for the next updated_since. Unknown parameters are rejected (-32602).`,
+      description: `List requirement tasks in your network, newest first. Defaults (MCP): view='summary' (no description / checklist bodies; has_description, checklist_count instead; ~0.5 KB per task) and ${REQ_LIST_MCP_DEFAULT_LIMIT} per page; has_more + next_cursor → pass cursor. Full text: requirements_get, or view='full' with a small limit (≤ 1000). Filters: seq (#N), status, project_id ('none'), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), tag (exact), updated_since (ISO), overdue / due_within_days (open tasks only), external_ref, parent_id / top_level, department_id (owner in it or below), include_archived; q searches title / description / people / project / tags (terms ANDed). Rows carry children {total, done}. changes=true (with updated_since) returns only tasks changed since then, archived included, plus deleted ids and server_time for the next updated_since. Unknown parameters are rejected (-32602).`,
       // Strict: registerTool honours a constructed object's unknownKeys (server.tool() would strip them silently).
       inputSchema: z.strictObject(reqListShape, {
         error: (iss: any) => iss.code === "unrecognized_keys"
@@ -5983,6 +5990,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (args.include_archived) q.set("include_archived", "1");
       if (args.top_level) q.set("top_level", "1");
       if (args.changes) q.set("changes", "1");
+      if (args.overdue !== undefined) q.set("overdue", args.overdue ? "1" : "0");
+      if (args.due_within_days !== undefined) q.set("due_within_days", String(args.due_within_days));
       return requirementsCall("GET", `/api/requirements?${q}`, args.network_id);
     },
   );
@@ -6171,7 +6180,7 @@ export interface UpsertNodeWithSec1GuardInput {
 }
 export type UpsertNodeOutcome =
   | { result: "inserted" | "updated"; node_id: string }
-  | { result: "refused"; reason: "cross_network" | "token_node_mismatch" | "owner_mismatch"; existingNet: string | null; callerNet: string | null }
+  | { result: "refused"; reason: "cross_network" | "token_node_mismatch" | "owner_mismatch" | "identity_mismatch"; existingNet: string | null; callerNet: string | null }
   | { result: "skipped"; reason: "missing_node_id" };
 
 const _norm = (x: string | null | undefined) => (x === null || x === undefined ? "default" : x);
@@ -6200,8 +6209,8 @@ export function trustedConfigSnapshotForNode(
 
 export function upsertNodeWithSec1Guard(input: UpsertNodeWithSec1GuardInput): UpsertNodeOutcome {
   if (!input.node_id) return { result: "skipped", reason: "missing_node_id" };
-  const existing = db.get<{ network_id: string | null; owner_user_id: string | null }>(
-    "SELECT network_id, owner_user_id FROM nodes WHERE node_id = ?1",
+  const existing = db.get<{ network_id: string | null; owner_user_id: string | null; alias: string | null; config_path: string | null }>(
+    "SELECT network_id, owner_user_id, alias, config_path FROM nodes WHERE node_id = ?1",
     input.node_id,
   );
   const callerNet = input.callerNetworkId;
@@ -6224,6 +6233,20 @@ export function upsertNodeWithSec1Guard(input: UpsertNodeWithSec1GuardInput): Up
   if (existing?.owner_user_id && input.callerUserId !== existing.owner_user_id) {
     return { result: "refused", reason: "owner_mismatch", existingNet: existing.network_id, callerNet };
   }
+  // A node_id copied into another node's config (or a hand-backfilled id that
+  // collides) must not relabel the row: the upsert below would COALESCE the
+  // reporter's alias over the owner's. A legit rename moves nodes.alias itself
+  // (rename.ts), so "different alias AND a different config file" is never the
+  // same node. Unowned legacy rows are exactly where this collision lives.
+  if (
+    existing?.alias && input.alias && existing.alias !== input.alias
+    && existing.config_path && input.config_path && existing.config_path !== input.config_path
+  ) {
+    console.warn(
+      `[commhub] 🚫 report_status node upsert refused (identity_mismatch): node_id=${input.node_id} row-alias=${existing.alias} reporter-alias=${input.alias}`,
+    );
+    return { result: "refused", reason: "identity_mismatch", existingNet: existing.network_id, callerNet };
+  }
 
   // Legacy / first-write paths: row missing OR network_id NULL → claim.
   const isLegacy = !existing