@sleep2agi/commhub-server 0.9.0-preview.66 → 0.9.0-preview.67

package/src/scheduled-doorbell-nodeless-session.test.ts

@@ -0,0 +1,130 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { createSSEStream } from "./push.js";
+import { dispatchScheduledOccurrence } from "./scheduled-tasks.js";
+
+// A claude-code node's channel server reports status without node_id, so its
+// sessions row has node_id NULL. The scheduler used to look the session up by
+// node_id only, judged every occurrence "queued" and never rang the doorbell:
+// the task sat in the inbox until an unrelated push drained it (20–36 min in
+// production).
+
+const NET = "net_sched_doorbell_nodeless";
+const NODE = "n_sched_doorbell_cc";
+const ALIAS = "sched-doorbell-cc";
+
+function cleanup(): void {
+  for (const table of ["task_events", "inbox", "scheduled_task_runs", "scheduled_tasks", "tasks", "sessions", "nodes"]) {
+    try { db.run(`DELETE FROM ${table} WHERE network_id = ?1`, [NET]); } catch {}
+  }
+}
+
+function seedNode(): void {
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, runtime, network_id, lifecycle_state)
+     VALUES (?1, ?2, ?2, 'claude-code-cli', ?3, 'active')`,
+    [NODE, ALIAS, NET],
+  );
+}
+
+function seedSession(status: string, nodeId: string | null): void {
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, agent, updated_at, last_seen_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, 'claude-code', datetime('now'), datetime('now'))`,
+    [`cc-${crypto.randomUUID()}`, ALIAS, status, nodeId, NET],
+  );
+}
+
+function seedSchedule(): any {
+  const scheduleId = `sched_${crypto.randomUUID()}`;
+  db.run(
+    `INSERT INTO scheduled_tasks
+       (schedule_id, network_id, name, target_node_id, target_alias, task_content, priority,
+        schedule_type, schedule_json, timezone, status, next_run_at)
+     VALUES (?1, ?2, 'doorbell', ?3, ?4, 'scheduled doorbell task', 'normal', 'interval',
+             '{"type":"interval","every_seconds":3600}', 'UTC', 'active', datetime('now', '+1 hour'))`,
+    [scheduleId, NET, NODE, ALIAS],
+  );
+  return db.get("SELECT * FROM scheduled_tasks WHERE schedule_id = ?1", scheduleId);
+}
+
+/** Subscribe like the channel server does and collect decoded SSE frames. */
+function subscribe(): { frames: any[]; close: () => Promise<void> } {
+  const res = createSSEStream(ALIAS, NET);
+  const reader = res.body!.getReader();
+  const decoder = new TextDecoder();
+  const frames: any[] = [];
+  let buffer = "";
+  let open = true;
+  (async () => {
+    while (open) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const blocks = buffer.split("\n\n");
+      buffer = blocks.pop() || "";
+      for (const block of blocks) {
+        const line = block.split("\n").find((l) => l.startsWith("data: "));
+        if (line) frames.push(JSON.parse(line.slice(6)));
+      }
+    }
+  })().catch(() => {});
+  return {
+    frames,
+    close: async () => {
+      open = false;
+      await reader.cancel().catch(() => {});
+    },
+  };
+}
+
+async function settle(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 20));
+}
+
+beforeEach(() => {
+  cleanup();
+  seedNode();
+});
+
+afterAll(cleanup);
+
+describe("scheduler doorbell for sessions reported without node_id", () => {
+  test("idle node_id-less session is delivered and its subscriber receives new_task", async () => {
+    seedSession("idle", null);
+    const sub = subscribe();
+    try {
+      await settle();
+      const result = dispatchScheduledOccurrence(seedSchedule(), new Date().toISOString(), false);
+      await settle();
+      expect(result.status).toBe("delivered");
+      expect(db.get<{ status: string }>("SELECT status FROM scheduled_task_runs WHERE run_id = ?1", result.runId)?.status).toBe("delivered");
+      const wake = sub.frames.filter((f) => f.type === "new_task");
+      expect(wake).toHaveLength(1);
+      expect(wake[0].from).toBe("scheduler");
+      expect(wake[0].inbox_count).toBe(1);
+    } finally {
+      await sub.close();
+    }
+  });
+
+  test("a live subscriber counts even when the session row says offline", async () => {
+    seedSession("offline", null);
+    const sub = subscribe();
+    try {
+      await settle();
+      const result = dispatchScheduledOccurrence(seedSchedule(), new Date().toISOString(), false);
+      await settle();
+      expect(result.status).toBe("delivered");
+      expect(sub.frames.filter((f) => f.type === "new_task")).toHaveLength(1);
+    } finally {
+      await sub.close();
+    }
+  });
+
+  test("offline session with nobody listening stays queued", () => {
+    seedSession("offline", null);
+    const result = dispatchScheduledOccurrence(seedSchedule(), new Date().toISOString(), false);
+    expect(result.status).toBe("queued");
+  });
+});

package/src/scheduled-skip-blocking-task.test.ts

@@ -0,0 +1,120 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { dispatchScheduledOccurrence, handleScheduledTaskRequest } from "./scheduled-tasks.js";
+
+// A skip used to record only error_code=previous_run_active. The owner saw
+// dozens of identical 「已跳过」 rows while the node sat idle, because the
+// open task had never reached it. The skip record now names the blocking task
+// and whether the node had picked it up.
+
+const NET = "net_sched_skip_blocking";
+const NODE = "n_sched_skip_blocking";
+const ALIAS = "sched-skip-blocking";
+
+function cleanup(): void {
+  for (const table of ["task_events", "inbox", "scheduled_task_runs", "scheduled_tasks", "tasks", "sessions", "nodes"]) {
+    try { db.run(`DELETE FROM ${table} WHERE network_id = ?1`, [NET]); } catch {}
+  }
+}
+
+function seedSchedule(): any {
+  const scheduleId = `sched_${crypto.randomUUID()}`;
+  db.run(
+    `INSERT INTO scheduled_tasks
+       (schedule_id, network_id, name, target_node_id, target_alias, task_content, priority,
+        schedule_type, schedule_json, timezone, status, next_run_at)
+     VALUES (?1, ?2, 'skip detail', ?3, ?4, 'scheduled task', 'normal', 'interval',
+             '{"type":"interval","every_seconds":60}', 'UTC', 'active', datetime('now', '+1 minute'))`,
+    [scheduleId, NET, NODE, ALIAS],
+  );
+  return db.get("SELECT * FROM scheduled_tasks WHERE schedule_id = ?1", scheduleId);
+}
+
+function run(runId: string): any {
+  return db.get(
+    "SELECT status, error_code, error_message, blocked_by_task_id, blocked_by_state FROM scheduled_task_runs WHERE run_id = ?1",
+    runId,
+  );
+}
+
+beforeEach(() => {
+  cleanup();
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, runtime, network_id, lifecycle_state)
+     VALUES (?1, ?2, ?2, 'codex-sdk', ?3, 'active')`,
+    [NODE, ALIAS, NET],
+  );
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+     VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))`,
+    [`r_${crypto.randomUUID()}`, ALIAS, NODE, NET],
+  );
+});
+
+afterAll(cleanup);
+
+describe("skipped run names the task that blocked it", () => {
+  test("open task still unacked in the inbox → not_received", () => {
+    const schedule = seedSchedule();
+    const first = dispatchScheduledOccurrence(schedule, "2026-09-29T08:00:00.000Z", false);
+    expect(first.status).toBe("delivered");
+
+    const second = dispatchScheduledOccurrence(schedule, "2026-09-29T08:01:00.000Z", false);
+    expect(second.status).toBe("skipped");
+    const row = run(second.runId);
+    expect(row.error_code).toBe("previous_run_active");
+    expect(row.blocked_by_task_id).toBe(first.taskId);
+    expect(row.blocked_by_state).toBe("not_received");
+    expect(row.error_message).toContain(first.taskId!);
+    expect(row.error_message).toContain("not been received");
+  });
+
+  test("open task whose inbox row the node acked → in_progress", () => {
+    const schedule = seedSchedule();
+    const first = dispatchScheduledOccurrence(schedule, "2026-09-29T09:00:00.000Z", false);
+    db.run("UPDATE inbox SET acked = 1 WHERE task_id = ?1", [first.taskId]);
+
+    const second = dispatchScheduledOccurrence(schedule, "2026-09-29T09:01:00.000Z", false);
+    expect(second.status).toBe("skipped");
+    const row = run(second.runId);
+    expect(row.blocked_by_task_id).toBe(first.taskId);
+    expect(row.blocked_by_state).toBe("in_progress");
+    expect(row.error_message).toContain("still in progress");
+  });
+
+  test("task status running counts as received even without an acked inbox row", () => {
+    const schedule = seedSchedule();
+    const first = dispatchScheduledOccurrence(schedule, "2026-09-29T10:00:00.000Z", false);
+    db.run("UPDATE tasks SET status = 'running' WHERE task_id = ?1", [first.taskId]);
+
+    const second = dispatchScheduledOccurrence(schedule, "2026-09-29T10:01:00.000Z", false);
+    expect(run(second.runId).blocked_by_state).toBe("in_progress");
+  });
+
+  test("GET /runs exposes the blocking task and state", async () => {
+    const schedule = seedSchedule();
+    const first = dispatchScheduledOccurrence(schedule, "2026-09-29T12:00:00.000Z", false);
+    const second = dispatchScheduledOccurrence(schedule, "2026-09-29T12:01:00.000Z", false);
+    const url = new URL(`http://hub.test/api/scheduled-tasks/${schedule.schedule_id}/runs`);
+    const res = await handleScheduledTaskRequest({
+      req: new Request(url, { method: "GET" }),
+      url,
+      auth: { userId: "u_skip_detail", networkId: NET, username: "skip-detail" },
+      isAdmin: false,
+      isNodeToken: false,
+      scope: { networkId: NET, networkIds: [NET] },
+    });
+    const body = await res!.json() as any;
+    const skipped = body.runs.find((r: any) => r.run_id === second.runId);
+    expect(skipped.blocked_by_task_id).toBe(first.taskId);
+    expect(skipped.blocked_by_state).toBe("not_received");
+  });
+
+  test("a delivered run carries no blocking fields", () => {
+    const schedule = seedSchedule();
+    const first = dispatchScheduledOccurrence(schedule, "2026-09-29T11:00:00.000Z", false);
+    const row = run(first.runId);
+    expect(row.blocked_by_task_id).toBeNull();
+    expect(row.blocked_by_state).toBeNull();
+  });
+});

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

@@ -431,6 +431,96 @@ describe("Hub scheduled task API and dispatcher", () => {
     expect(["Concurrent editor A", "Concurrent editor B"]).toContain(latest.name);
   });
 
+  // Owner report 2026-09-29: editing a 2-minute schedule failed with
+  // revision_conflict whenever a run landed while the dialog was open, and the
+  // client dropped the draft. Runs are bookkeeping, not edits.
+  test("a scheduler run between GET and PATCH does not conflict with the edit", async () => {
+    const created = await api(ownerToken, "/api/scheduled-tasks", {
+      method: "POST",
+      body: JSON.stringify({ network_id: networkId, name: "Run-during-edit", target_node_id: nodeId, task: "before edit", timezone: "Asia/Shanghai", schedule: { type: "interval", every_seconds: 120 } }),
+    });
+    expect(created.status).toBe(201);
+    const id = created.body.schedule.schedule_id;
+    const path = `/api/scheduled-tasks/${id}?network_id=${encodeURIComponent(networkId)}`;
+    const opened = (await api(ownerToken, path)).body.schedule;
+
+    const firedAt = new Date(Date.now() - 1_000).toISOString();
+    db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [firedAt, id]);
+    runDueScheduledTasks();
+    const afterRun = (await api(ownerToken, path)).body.schedule;
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM scheduled_task_runs WHERE schedule_id = ?1", id)!.n).toBe(1);
+    expect(afterRun.last_run_at).toBe(firedAt);
+    expect(new Date(afterRun.next_run_at).getTime()).toBeGreaterThan(Date.now());
+    expect(afterRun.revision).toBe(opened.revision);
+
+    const saved = await api(ownerToken, path, {
+      method: "PATCH",
+      body: JSON.stringify({ revision: opened.revision, task: "edited while it ran", name: opened.name, schedule: opened.schedule, timezone: opened.timezone }),
+    });
+    expect(saved.status).toBe(200);
+    expect(saved.body.schedule.task_content).toBe("edited while it ran");
+    expect(saved.body.schedule.revision).toBe(opened.revision + 1);
+    // Cadence edit-preservation must keep the scheduler's advanced slot, not
+    // resurrect the occurrence that already fired.
+    expect(saved.body.schedule.next_run_at).toBe(afterRun.next_run_at);
+
+    // A second device still holding the pre-edit revision is a true conflict.
+    const stale = await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ revision: opened.revision, task: "other device" }) });
+    expect(stale.status).toBe(409);
+    expect(stale.body.error).toBe("revision_conflict");
+    await api(ownerToken, `/api/scheduled-tasks/${id}/cancel?network_id=${encodeURIComponent(networkId)}`, { method: "POST", body: "{}" });
+  });
+
+  test("a run that lands while the PATCH body is in flight keeps the advanced next_run_at", async () => {
+    const created = await api(ownerToken, "/api/scheduled-tasks", {
+      method: "POST",
+      body: JSON.stringify({ network_id: networkId, name: "Run-during-body", target_node_id: nodeId, task: "before", timezone: "Asia/Shanghai", schedule: { type: "interval", every_seconds: 120 } }),
+    });
+    const id = created.body.schedule.schedule_id;
+    const path = `/api/scheduled-tasks/${id}?network_id=${encodeURIComponent(networkId)}`;
+    const firedAt = new Date(Date.now() - 1_000).toISOString();
+    db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [firedAt, id]);
+    const opened = (await api(ownerToken, path)).body.schedule;
+
+    // The handler reads the row before awaiting the body. Hold the body open,
+    // run the scheduler, then release it — the PATCH now carries a stale
+    // row.next_run_at (the slot that just fired).
+    let release!: () => void;
+    const gate = new Promise<void>((r) => { release = r; });
+    const payload = new TextEncoder().encode(JSON.stringify({ revision: opened.revision, task: "edited mid-run" }));
+    const body = new ReadableStream({ async pull(c) { await gate; c.enqueue(payload); c.close(); } });
+    const pending = fetch(`${base}${path}`, { method: "PATCH", body, duplex: "half", headers: { Authorization: `Bearer ${ownerToken}`, "Content-Type": "application/json" } } as any);
+    await new Promise((r) => setTimeout(r, 100));
+    runDueScheduledTasks();
+    const advanced = db.get<{ next_run_at: string }>("SELECT next_run_at FROM scheduled_tasks WHERE schedule_id = ?1", id)!.next_run_at;
+    expect(advanced).not.toBe(firedAt);
+    release();
+    const res = await pending;
+    const saved = await res.json() as any;
+    expect(res.status).toBe(200);
+    expect(saved.schedule.task_content).toBe("edited mid-run");
+    expect(saved.schedule.next_run_at).toBe(advanced);
+    await api(ownerToken, `/api/scheduled-tasks/${id}/cancel?network_id=${encodeURIComponent(networkId)}`, { method: "POST", body: "{}" });
+  });
+
+  test("one-shot auto-complete is a user-visible status change and still bumps revision", async () => {
+    const created = await api(ownerToken, "/api/scheduled-tasks", {
+      method: "POST",
+      body: JSON.stringify({ network_id: networkId, name: "One-shot", target_node_id: nodeId, task: "once", timezone: "Asia/Shanghai", schedule: { type: "once", run_at: new Date(Date.now() + 3_600_000).toISOString() } }),
+    });
+    const id = created.body.schedule.schedule_id;
+    const path = `/api/scheduled-tasks/${id}?network_id=${encodeURIComponent(networkId)}`;
+    const opened = (await api(ownerToken, path)).body.schedule;
+    db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [new Date(Date.now() - 1_000).toISOString(), id]);
+    runDueScheduledTasks();
+    const done = (await api(ownerToken, path)).body.schedule;
+    expect(done.status).toBe("completed");
+    expect(done.revision).toBe(opened.revision + 1);
+    const edit = await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ revision: opened.revision, task: "too late" }) });
+    expect(edit.status).toBe(409);
+    expect(edit.body.error).toBe("schedule_completed");
+  });
+
   test("optimistic revision, pause/resume, run-now and cancel preserve history", async () => {
     const latest = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`);
     revision = latest.body.schedule.revision;

package/src/scheduled-tasks.ts

@@ -1,7 +1,7 @@
 import { db, logTaskEvent } from "./db.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { addNetworkScope, canRestWriteNetwork, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
-import { pushEvent, pushNetworkObserverEvent } from "./push.js";
+import { hasSubscribers, pushEvent, pushNetworkObserverEvent } from "./push.js";
 import { SCHEDULED_TASK_STORAGE_SELECT } from "./rest-projections.js";
 
 export type ScheduleSpec =
@@ -219,8 +219,15 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
 
     if (row.overlap_policy === "skip") {
       const placeholders = OPEN_TASK_STATUSES.map((_, i) => `?${i + 2}`).join(", ");
-      const open = db.get<{ task_id: string }>(
-        `SELECT r.task_id FROM scheduled_task_runs r
+      // received:节点那边有没有把这条任务取走过(inbox 行被 ack,或任务已进 acked/running)。
+      // 跳过记录带上它,客户端才分得清「节点还没收到」和「节点在处理」—— 前者是投递故障,
+      // 后者才是真的上一次还没做完。
+      const open = db.get<{ task_id: string; received: number }>(
+        `SELECT r.task_id,
+                CASE WHEN t.status IN ('acked', 'running')
+                       OR EXISTS (SELECT 1 FROM inbox i WHERE (i.task_id = r.task_id OR i.id = r.task_id) AND i.acked = 1)
+                     THEN 1 ELSE 0 END AS received
+         FROM scheduled_task_runs r
          JOIN tasks t ON t.task_id = r.task_id
          WHERE r.schedule_id = ?1 AND t.status IN (${placeholders})
          ORDER BY r.created_at DESC LIMIT 1`,
@@ -228,9 +235,18 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
       );
       if (open) {
         finalStatus = "skipped";
+        const blockedState = open.received ? "in_progress" : "not_received";
         db.run(
-          "UPDATE scheduled_task_runs SET status = 'skipped', error_code = 'previous_run_active', completed_at = datetime('now') WHERE run_id = ?1",
-          [runId],
+          `UPDATE scheduled_task_runs SET status = 'skipped', error_code = 'previous_run_active', error_message = ?2,
+             blocked_by_task_id = ?3, blocked_by_state = ?4, completed_at = datetime('now') WHERE run_id = ?1`,
+          [
+            runId,
+            blockedState === "not_received"
+              ? `previous run task ${open.task_id} has not been received by the node yet`
+              : `previous run task ${open.task_id} is still in progress on the node`,
+            open.task_id,
+            blockedState,
+          ],
         );
         if (advanceSchedule) advance(row, scheduledFor, advanceAfter);
         return;
@@ -262,11 +278,19 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
     }
 
     const taskId = crypto.randomUUID();
+    // claude-code 裸节点的 node-server 上报 report_status 不带 node_id,它的 sessions 行
+    // node_id 永远是 NULL —— 只按 node_id 找会话,这类节点每一次都判成 queued、门铃不响,
+    // 任务在 inbox 里等到别的消息顺带捎进去(生产上 20–36 分钟)。按 node_id 找不到时退回
+    // 同网同别名、node_id 为空的会话;SSE 订阅者注册表是「有没有人在听」的实测,也算数。
     const session = db.get<{ status: string | null }>(
       "SELECT status FROM sessions WHERE node_id = ?1 AND network_id = ?2 ORDER BY updated_at DESC LIMIT 1",
       row.target_node_id, row.network_id,
+    ) ?? db.get<{ status: string | null }>(
+      "SELECT status FROM sessions WHERE alias = ?1 AND network_id = ?2 AND node_id IS NULL ORDER BY updated_at DESC LIMIT 1",
+      node.alias, row.network_id,
     );
-    const deliveryState: "delivered" | "queued" = session && session.status !== "offline" ? "delivered" : "queued";
+    const deliveryState: "delivered" | "queued" =
+      (session && session.status !== "offline") || hasSubscribers(node.alias, row.network_id) ? "delivered" : "queued";
     const metaJson = JSON.stringify({
       scheduled_task_id: row.schedule_id,
       scheduled_run_id: runId,
@@ -310,6 +334,12 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
   return { runId, taskId: createdTaskId, status: finalStatus, event };
 }
 
+// `revision` is the optimistic-concurrency token for *user edits*. Run
+// bookkeeping (next_run_at/last_run_at) must not bump it: a 2-minute schedule
+// would otherwise turn every edit that spans a run into a 409 and the client
+// would drop the user's draft. Terminal completion still bumps, because it is
+// a status change the user sees and it is what stops an in-flight PATCH (whose
+// UPDATE is guarded by `AND revision = ?`) from reviving a finished one-shot.
 function advance(row: ScheduledRow, scheduledFor: string, after = new Date(), recordLastRun = true): void {
   const spec = JSON.parse(row.schedule_json) as ScheduleSpec;
   const next = nextOccurrence(spec, row.timezone, after);
@@ -321,7 +351,7 @@ function advance(row: ScheduledRow, scheduledFor: string, after = new Date(), re
     );
   } else {
     db.run(
-      "UPDATE scheduled_tasks SET next_run_at = ?1, last_run_at = ?2, revision = revision + 1, updated_at = datetime('now') WHERE schedule_id = ?3",
+      "UPDATE scheduled_tasks SET next_run_at = ?1, last_run_at = ?2, updated_at = datetime('now') WHERE schedule_id = ?3",
       [iso(next), lastRunAt, row.schedule_id],
     );
   }
@@ -461,7 +491,7 @@ export async function handleScheduledTaskRequest(ctx: ScheduledRequestContext):
   if (sub === "runs" && req.method === "GET") {
     const limit = Math.max(1, Math.min(200, Number(url.searchParams.get("limit")) || 50));
     const runs = db.all(
-      "SELECT run_id, schedule_id, scheduled_for, task_id, status, error_code, error_message, created_at, completed_at FROM scheduled_task_runs WHERE schedule_id = ?1 AND network_id = ?2 ORDER BY created_at DESC LIMIT ?3",
+      "SELECT run_id, schedule_id, scheduled_for, task_id, status, error_code, error_message, blocked_by_task_id, blocked_by_state, created_at, completed_at FROM scheduled_task_runs WHERE schedule_id = ?1 AND network_id = ?2 ORDER BY created_at DESC LIMIT ?3",
       row.schedule_id, row.network_id, limit,
     );
     return Response.json({ ok: true, runs });
@@ -532,11 +562,16 @@ export async function handleScheduledTaskRequest(ctx: ScheduledRequestContext):
           ? nextOccurrence(parsed.spec, parsed.timezone, new Date())
           : new Date(row.next_run_at);
       if (requestedStatus === "active" && !next) throw new Error("schedule_has_no_future_occurrence");
+      // Runs no longer bump revision, so the scheduler may have advanced
+      // next_run_at after `row` was read. When cadence is preserved, keep the
+      // stored value instead of writing back the already-fired occurrence.
+      const keepStoredNext = requestedStatus === "active" && !schedulingChanged && !resumed && !!row.next_run_at ? 1 : 0;
       const updated = db.run(
         `UPDATE scheduled_tasks SET name = ?1, target_node_id = ?2, target_alias = ?3, task_content = ?4,
-         priority = ?5, schedule_type = ?6, schedule_json = ?7, timezone = ?8, status = ?9, next_run_at = ?10,
+         priority = ?5, schedule_type = ?6, schedule_json = ?7, timezone = ?8, status = ?9,
+         next_run_at = CASE WHEN ?14 = 1 AND next_run_at IS NOT NULL THEN next_run_at ELSE ?10 END,
          misfire_policy = ?11, revision = revision + 1, updated_at = datetime('now') WHERE schedule_id = ?12 AND revision = ?13`,
-        [name, target.node_id, target.alias, content, priority, parsed.spec.type, scheduleJson, parsed.timezone, requestedStatus, next ? iso(next) : null, misfirePolicy, row.schedule_id, row.revision],
+        [name, target.node_id, target.alias, content, priority, parsed.spec.type, scheduleJson, parsed.timezone, requestedStatus, next ? iso(next) : null, misfirePolicy, row.schedule_id, row.revision, keepStoredNext],
       );
       if (updated.changes !== 1) return jsonError("revision_conflict", 409);
       return Response.json({ ok: true, schedule: decodeRow(db.get<ScheduledRow>(`SELECT ${SCHEDULED_TASK_STORAGE_SELECT} FROM scheduled_tasks WHERE schedule_id = ?1`, row.schedule_id)!) });

package/src/tools.ts

@@ -8,7 +8,8 @@ import { getSSEStats, hasSubscribers, hasUserSubscribers, pushEvent, pushNetwork
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { pendingInboxCount } from "./inbox-count.js";
 import { getUserNetworkRole, createNetworkTokenForNode } from "./auth.js";
-import { canRestWriteNetwork, getUserNetworkIds, singleNetworkId } from "./network-scope.js";
+import { canRestWriteNetwork, getUserNetworkIds, resolveRestNetworkScope, singleNetworkId } from "./network-scope.js";
+import { handleRequirementsRequest } from "./requirements.js";
 import {
   buildAnetArgs as _unused_buildAnetArgs,           // ensure module is loaded
   validateName as validateChildName,
@@ -5674,6 +5675,109 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       }
     },
   );
+
+  // ── 需求池 / 任务看板(Agent 读写任务,例如把 GitHub issue 同步成任务) ──
+  // 全部走 REST 同一个处理函数(requirements.ts handleRequirementsRequest):权限、校验、谁做的记录只有一份。
+  // 节点令牌只在它绑定的网络里读 / 建 / 改 / 勾子任务 / upsert / 读项目;删除和管理项目只给人。
+  const requirementsCall = async (method: string, path: string, clientNetId?: string | null, body?: Record<string, unknown>) => {
+    const scope = resolveRestNetworkScope(enforceNetworkId ? null : (clientNetId ?? null), mcpAuthCtx, false);
+    if (scope.denied) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "access_denied", message: scope.denied }) }] };
+    const url = new URL(`http://mcp.internal${path}`);
+    const req = new Request(url, { method, headers: { "content-type": "application/json" }, body: body ? JSON.stringify(body) : undefined });
+    const res = await handleRequirementsRequest({
+      req, url,
+      auth: mcpAuthCtx ? { ...mcpAuthCtx, username: "", tokenId: callerTokenId ?? null, tokenName: callerTokenIsNetwork && callerAlias ? `node:${callerAlias}` : null } : null,
+      isAdmin: false,
+      isNodeToken: callerTokenIsNetwork,
+      scope,
+    });
+    const data = res ? await res.json() : { ok: false, error: "not_found" };
+    return { content: [{ type: "text" as const, text: JSON.stringify(res && !res.ok && data && typeof data === "object" ? { ...data, status: res.status } : data) }] };
+  };
+  const reqPerson = z.object({ kind: z.enum(["user", "node"]), id: z.string().min(1).max(200) });
+  const reqChecklistItem = z.object({ id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/).optional(), text: z.string().min(1).max(500), done: z.boolean().optional() });
+  const reqFields = {
+    name: z.string().min(1).max(80).optional(),
+    priority: z.enum(["high", "normal", "low"]).optional(),
+    column: z.enum(["pool", "doing", "done"]).optional(),
+    due: z.string().max(40).optional().describe("YYYY-MM-DD (all day) or ISO 8601 with Z / ±HH:MM (stored as UTC seconds); \"\" clears"),
+    description: z.string().max(20_000).optional().describe("markdown"),
+    checklist: z.array(reqChecklistItem).max(100).optional().describe("replaces the whole list"),
+    project_id: z.string().max(200).nullable().optional(),
+    owner: reqPerson.nullable().optional().describe("负责人: must be {kind:'user'}"),
+    agent_owner: reqPerson.nullable().optional().describe("负责 Agent: must be {kind:'node'}"),
+    participants: z.array(reqPerson).max(100).optional(),
+    external_url: z.string().max(500).nullable().optional(),
+    parent_id: z.string().regex(/^[A-Za-z0-9_-]{1,200}$/).nullable().optional().describe("parent requirement (same network, no cycles, ≤ 5 levels); null detaches"),
+  };
+  const pick = (args: Record<string, unknown>, keys: string[]) => Object.fromEntries(keys.filter(k => args[k] !== undefined).map(k => [k, args[k]]));
+  const REQ_WRITE_KEYS = [...Object.keys(reqFields), "external_ref", "archived"];
+
+  server.tool(
+    "requirements_list",
+    "List requirement tasks in your network. Filters: status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), updated_since (ISO), external_ref, parent_id / top_level, include_archived. Newest first, max 500. Each task carries children {total, done}.",
+    {
+      network_id: z.string().max(200).optional(),
+      status: z.enum(["pool", "doing", "done"]).optional(),
+      project_id: z.string().max(200).optional(),
+      owner: z.string().max(210).optional(),
+      agent_owner: z.string().max(210).optional(),
+      updated_since: z.string().max(40).optional(),
+      external_ref: z.string().max(200).optional(),
+      include_archived: z.boolean().optional(),
+      parent_id: z.string().max(200).optional().describe("children of this requirement ('none' = top level)"),
+      top_level: z.boolean().optional(),
+    },
+    async (args) => {
+      const q = new URLSearchParams();
+      for (const k of ["status", "project_id", "owner", "agent_owner", "updated_since", "external_ref", "parent_id"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
+      if (args.include_archived) q.set("include_archived", "1");
+      if (args.top_level) q.set("top_level", "1");
+      return requirementsCall("GET", `/api/requirements${q.size ? `?${q}` : ""}`, args.network_id);
+    },
+  );
+
+  server.tool(
+    "requirements_get",
+    "Get one requirement task by id (with description, checklist, owners, project, external_ref).",
+    { id: z.string().min(1).max(200), network_id: z.string().max(200).optional() },
+    async ({ id, network_id }) => requirementsCall("GET", `/api/requirements/${encodeURIComponent(id)}`, network_id),
+  );
+
+  server.tool(
+    "requirements_create",
+    "Create a requirement task. name is required. A duplicate external_ref in the network returns 409 external_ref_exists with existing_id — use requirements_upsert_by_external_ref for syncing.",
+    { network_id: z.string().max(200).optional(), ...reqFields, name: z.string().min(1).max(80), external_ref: z.string().max(200).optional() },
+    async (args) => requirementsCall("POST", "/api/requirements", args.network_id, pick(args, REQ_WRITE_KEYS)),
+  );
+
+  server.tool(
+    "requirements_update",
+    "Patch a requirement task; omitted fields keep their value. archived=true hides it from the default list (agents cannot delete).",
+    { id: z.string().min(1).max(200), network_id: z.string().max(200).optional(), ...reqFields, external_ref: z.string().max(200).nullable().optional(), archived: z.boolean().optional() },
+    async (args) => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(args.id)}`, args.network_id, pick(args, REQ_WRITE_KEYS)),
+  );
+
+  server.tool(
+    "requirements_checklist_toggle",
+    "Set one checklist item done / not done (only that item is written, so concurrent edits of other items are kept).",
+    { id: z.string().min(1).max(200), item_id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/), done: z.boolean(), network_id: z.string().max(200).optional() },
+    async ({ id, item_id, done, network_id }) => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(id)}/checklist/${encodeURIComponent(item_id)}`, network_id, { done }),
+  );
+
+  server.tool(
+    "requirements_upsert_by_external_ref",
+    "Idempotent sync: create the task for external_ref (e.g. github:owner/repo#123) or, if it already exists in the network, patch it (omitted fields — including status — are kept). Returns { requirement, created }.",
+    { network_id: z.string().max(200).optional(), external_ref: z.string().min(1).max(200), ...reqFields, archived: z.boolean().optional() },
+    async (args) => requirementsCall("POST", "/api/requirements/upsert", args.network_id, pick(args, REQ_WRITE_KEYS)),
+  );
+
+  server.tool(
+    "projects_list",
+    "List requirement projects in your network (id, name, color, sort, archived).",
+    { network_id: z.string().max(200).optional() },
+    async ({ network_id }) => requirementsCall("GET", "/api/requirements/projects", network_id),
+  );
 }
 
 // ────────────────────────────────────────────────────────────────────