@sleep2agi/commhub-server 0.9.0-preview.139 → 0.9.0-preview.140

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

@@ -0,0 +1,193 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db, syncScheduledRunForTask } from "./db.js";
+import { refreshScheduledBackoff } from "./scheduled-backoff.js";
+import { getScheduleRow, dispatchScheduledOccurrence, runDueScheduledTasks } from "./scheduled-tasks.js";
+
+if (!process.env.COMMHUB_DB) throw new Error("test1278 requires an explicit disposable SQLite COMMHUB_DB");
+let server: any, base = "", network = "", ownerToken = "", ownerId = "";
+const stamp = Date.now(), nodes: Record<string, { id: string; alias: string; token: string; tokenId: string }> = {};
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const r = await fetch(base + path, { method, headers: { Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  return { status: r.status, body: await r.json() as any };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>) {
+  const r = await fetch(base + "/mcp", { method: "POST", headers: { Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }) });
+  const raw = await r.text(), line = raw.split("\n").find(x => x.startsWith("data: "));
+  const envelope = JSON.parse(line ? line.slice(6) : raw);
+  try { return JSON.parse(envelope.result.content[0].text); }
+  catch { return { ok: false, transportError: true }; }
+}
+const readRun = (taskId: string) => db.get<any>(
+  "SELECT run_id, schedule_id, status, work_outcome, work_outcome_node_id, schedule_revision FROM scheduled_task_runs WHERE task_id = ?1 AND network_id = ?2", taskId, network)!;
+const readTask = (taskId: string) => db.get<any>("SELECT status, result FROM tasks WHERE task_id = ?1", taskId)!;
+const countReplies = (taskId: string) => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM inbox WHERE in_reply_to = ?1 AND type = 'reply'", taskId)!.n;
+async function fire(enabled = true, interval = 120) {
+  const created = await rest(ownerToken, "POST", "/api/scheduled-tasks", { network_id: network,
+    name: `test1278-${crypto.randomUUID()}`, target_node_id: nodes.a.id, task: "fixture1278 work",
+    schedule: { type: "interval", every_seconds: interval }, timezone: "UTC", no_change_backoff: enabled });
+  expect(created.status).toBe(201);
+  const scheduleId = created.body.schedule.schedule_id;
+  db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id != ?2", [new Date(Date.now() + 86400_000).toISOString(), scheduleId]);
+  db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [new Date(Date.now() - 1000).toISOString(), scheduleId]);
+  await runDueScheduledTasks();
+  const run = db.get<any>("SELECT task_id FROM scheduled_task_runs WHERE schedule_id = ?1", scheduleId)!;
+  expect(run.task_id).toBeTruthy();
+  return { taskId: run.task_id as string, scheduleId };
+}
+const reply = (taskId: string, meta?: unknown, status = "replied", token = nodes.a.token, extra = {}) =>
+  mcp(token, "send_reply", { in_reply_to: taskId, text: "本轮无新增", status, ...(meta === undefined ? {} : { meta }), ...extra });
+const cadence = (id: string) => db.get<any>("SELECT next_run_at, last_run_at, revision, schedule_json, target_node_id FROM scheduled_tasks WHERE schedule_id = ?1", id)!;
+
+beforeAll(async () => {
+  const owner = register(`work_owner_${stamp}`, "Fixture1274Only!x"); ownerToken = owner.token!;
+  network = owner.network_id!; ownerId = owner.user!.user_id;
+  for (const key of ["a", "b"]) {
+    const id = `n_work_${key}_${stamp}`, alias = `work-${key}-${stamp}`;
+    const token = createNetworkTokenForNode(ownerId, network, alias, id); expect(token.ok).toBe(true);
+    nodes[key] = { id, alias, token: token.token!, tokenId: token.token_id! };
+    db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, ?2, 'idle', ?3, ?4)", [`r_${id}`, alias, id, network]);
+  }
+  const mod = await import("./server.js"); server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+afterAll(() => server?.stop?.(true));
+
+
+const state = (id: string) => db.get<any>("SELECT no_change_backoff, backoff_streak, backoff_effective_seconds, backoff_last_run_id, next_run_at, revision, schedule_json, status FROM scheduled_tasks WHERE schedule_id = ?1", id)!;
+let occurrence = 0;
+async function nextRun(id: string) {
+  // Isolated fixture accelerates the clock, without touching live schedules.
+  const date = new Date(Date.now() + (++occurrence) * 1000).toISOString();
+  const out = dispatchScheduledOccurrence(getScheduleRow(id)!, date, true);
+  expect(out.taskId).toBeTruthy(); return out.taskId!;
+}
+async function empties(id: string, n: number) {
+  for (let i = 0; i < n; i++) expect((await reply(await nextRun(id), { scheduled_work_outcome: "no_changes" })).ok).toBe(true);
+}
+async function atThree() {
+  const x = await fire(); expect((await reply(x.taskId, { scheduled_work_outcome: "no_changes" })).ok).toBe(true);
+  await empties(x.scheduleId, 2); return x;
+}
+describe("#1278 opt-in durable no-change backoff through real HTTP/MCP", () => {
+  test("3 and 6 exact empty successes change effective cadence, preserving base and revision", async () => {
+    const { taskId, scheduleId } = await fire(), initial = state(scheduleId);
+    expect((await reply(taskId, { scheduled_work_outcome: "no_changes" })).ok).toBe(true);
+    await empties(scheduleId, 1); expect(state(scheduleId).backoff_effective_seconds).toBe(120);
+    await empties(scheduleId, 1); const three = state(scheduleId);
+    expect(three).toMatchObject({ backoff_streak: 3, backoff_effective_seconds: 600, revision: initial.revision, schedule_json: initial.schedule_json });
+    expect(Date.parse(three.next_run_at) - Date.now()).toBeGreaterThan(590_000);
+    await empties(scheduleId, 3); expect(state(scheduleId)).toMatchObject({ backoff_streak: 6, backoff_effective_seconds: 1800 });
+    const wire = await rest(ownerToken, "GET", `/api/scheduled-tasks/${scheduleId}`);
+    expect(wire.body.schedule).toMatchObject({ no_change_backoff: true, schedule: { every_seconds: 120 }, backoff: { streak: 6, effective_seconds: 1800 } });
+    expect(wire.body.schedule.backoff_last_run_id).toBeUndefined();
+  });
+  test("changed restores base and nearer next occurrence; no natural-language inference", async () => {
+    const { scheduleId } = await atThree();
+    expect((await reply(await nextRun(scheduleId), { scheduled_work_outcome: "changed" })).ok).toBe(true);
+    expect(state(scheduleId)).toMatchObject({ backoff_streak: 0, backoff_effective_seconds: 120 });
+    expect(Date.parse(state(scheduleId).next_run_at) - Date.now()).toBeLessThanOrEqual(120_000);
+  });
+  test("unknown success and ordinary failure break the sequence", async () => {
+    for (const status of ["replied", "failed"]) {
+      const { scheduleId } = await atThree();
+      expect((await reply(await nextRun(scheduleId), undefined, status)).ok).toBe(true);
+      expect(state(scheduleId)).toMatchObject({ backoff_streak: 0, backoff_effective_seconds: 120 });
+      await empties(scheduleId, 2); expect(state(scheduleId).backoff_effective_seconds).toBe(120);
+    }
+  });
+  test("legacy disabled schedules preserve exact cadence and wire shape", async () => {
+    const { taskId, scheduleId } = await fire(false), before = state(scheduleId);
+    expect((await reply(taskId, { scheduled_work_outcome: "no_changes" })).ok).toBe(true);
+    expect(state(scheduleId)).toEqual(before);
+    const wire = await rest(ownerToken, "GET", `/api/scheduled-tasks/${scheduleId}`);
+    expect(wire.body.schedule.no_change_backoff).toBeUndefined(); expect(wire.body.schedule.backoff).toBeUndefined();
+  });
+  test("a slower base interval is never accelerated", async () => {
+    const { taskId, scheduleId } = await fire(true, 3600);
+    await reply(taskId, { scheduled_work_outcome: "no_changes" }); await empties(scheduleId, 5);
+    expect(state(scheduleId)).toMatchObject({ backoff_streak: 6, backoff_effective_seconds: 3600 });
+  });
+  test("duplicate callbacks and another DB process cannot increment twice", async () => {
+    const { scheduleId } = await atThree(), before = state(scheduleId);
+    const latest = db.get<any>("SELECT task_id FROM scheduled_task_runs WHERE run_id = ?1", before.backoff_last_run_id)!;
+    expect((await reply(latest.task_id, { scheduled_work_outcome: "no_changes" })).ok).toBe(false);
+    syncScheduledRunForTask(latest.task_id, network); expect(state(scheduleId)).toEqual(before);
+    const child = Bun.spawn([process.execPath, "-e", `import {db} from './server/src/db.ts'; import {refreshScheduledBackoff} from './server/src/scheduled-backoff.ts'; db.transaction(()=>refreshScheduledBackoff(${JSON.stringify(scheduleId)},${JSON.stringify(network)})); console.log(JSON.stringify(db.get('SELECT backoff_streak,backoff_effective_seconds FROM scheduled_tasks WHERE schedule_id=?1',${JSON.stringify(scheduleId)})));`], { cwd: process.cwd(), stdout: "pipe", stderr: "pipe", env: process.env });
+    const output = await new Response(child.stdout).text(); expect(await child.exited).toBe(0);
+    expect(JSON.parse(output.trim().split("\n").at(-1)!)).toEqual({ backoff_streak: 3, backoff_effective_seconds: 600 });
+    expect(state(scheduleId)).toEqual(before);
+  });
+  test("old generation completion after edit cannot rearm", async () => {
+    const { scheduleId } = await atThree(), old = await nextRun(scheduleId), revision = state(scheduleId).revision;
+    const edit = await rest(ownerToken, "PATCH", `/api/scheduled-tasks/${scheduleId}`, { revision, name: "fresh generation" }); expect(edit.status).toBe(200);
+    const before = state(scheduleId); expect(before.backoff_streak).toBe(0);
+    expect((await reply(old, { scheduled_work_outcome: "no_changes" })).ok).toBe(true); expect(state(scheduleId)).toEqual(before);
+  });
+  test("manual wake resets durable state and fences an in-flight old generation", async () => {
+    const { scheduleId } = await atThree(), old = await nextRun(scheduleId), revision = state(scheduleId).revision;
+    // Existing overlap skip remains effective. Wake still resets cadence.
+    const wake = await rest(ownerToken, "POST", `/api/scheduled-tasks/${scheduleId}/run-now`); expect(wake.status).toBe(202);
+    expect(state(scheduleId)).toMatchObject({ backoff_streak: 0, backoff_effective_seconds: null, revision: revision + 1 });
+    const before = state(scheduleId); await reply(old, { scheduled_work_outcome: "no_changes" }); expect(state(scheduleId)).toEqual(before);
+  });
+  test("pause/cancel never resurrect cadence; resumed policy starts a new generation", async () => {
+    const { scheduleId } = await atThree(), old = await nextRun(scheduleId);
+    expect((await rest(ownerToken, "PATCH", `/api/scheduled-tasks/${scheduleId}`, { revision: state(scheduleId).revision, status: "paused" })).status).toBe(200);
+    await reply(old, { scheduled_work_outcome: "changed" }); expect(state(scheduleId)).toMatchObject({ status: "paused", next_run_at: null, backoff_streak: 0 });
+    expect((await rest(ownerToken, "POST", `/api/scheduled-tasks/${scheduleId}/run-now`)).status).toBe(202);
+    expect(state(scheduleId).next_run_at).toBeNull();
+    expect((await rest(ownerToken, "DELETE", `/api/scheduled-tasks/${scheduleId}`)).status).toBe(200);
+    expect((await rest(ownerToken, "POST", `/api/scheduled-tasks/${scheduleId}/run-now`)).status).toBe(409);
+    expect(state(scheduleId)).toMatchObject({ status: "cancelled", next_run_at: null });
+  });
+  test("retry success is excluded from empty streaks and failure breaks prior successes", async () => {
+    const { scheduleId } = await atThree(), task = await nextRun(scheduleId);
+    await reply(task, undefined, "failed"); expect(state(scheduleId).backoff_streak).toBe(0);
+    expect((await mcp(ownerToken, "retry_task", { task_id: task, network_id: network })).ok).toBe(true);
+    expect((await reply(task, { scheduled_work_outcome: "no_changes" })).ok).toBe(true);
+    expect(state(scheduleId).backoff_streak).toBe(0); await empties(scheduleId, 2);
+    expect(state(scheduleId).backoff_streak).toBe(2);
+  });
+  test("overlap skip breaks the sequence and an older completion cannot bypass the skip", async () => {
+    const { scheduleId } = await atThree(), active = await nextRun(scheduleId);
+    const skipped = dispatchScheduledOccurrence(getScheduleRow(scheduleId)!, new Date(Date.now() + (++occurrence) * 1000).toISOString(), true);
+    expect(skipped.status).toBe("skipped"); expect(state(scheduleId).backoff_streak).toBe(0);
+    await reply(active, { scheduled_work_outcome: "no_changes" }); expect(state(scheduleId).backoff_streak).toBe(0);
+  });
+  test("current reporter target mismatch cannot count as empty", async () => {
+    const { scheduleId } = await atThree(), task = await nextRun(scheduleId);
+    // Fixture-only reassignment emulates an authorized assignment change.
+    db.run("UPDATE tasks SET to_node_id = ?1, to_name = ?2 WHERE task_id = ?3", [nodes.b.id, nodes.b.alias, task]);
+    expect((await reply(task, { scheduled_work_outcome: "no_changes" }, "replied", nodes.b.token)).ok).toBe(true);
+    expect(state(scheduleId).backoff_streak).toBe(0);
+  });
+  test("injected cadence-write fault rolls back task, inbox, outcome, and state together", async () => {
+    const { taskId, scheduleId } = await fire(), before = state(scheduleId);
+    db.exec(`CREATE TRIGGER test1278_fault BEFORE UPDATE OF backoff_streak ON scheduled_tasks WHEN NEW.schedule_id='${scheduleId}' BEGIN SELECT RAISE(ABORT,'test1278_fault'); END`);
+    try { expect((await reply(taskId, { scheduled_work_outcome: "no_changes" })).ok).not.toBe(true); }
+    finally { db.exec("DROP TRIGGER test1278_fault"); }
+    expect(state(scheduleId)).toEqual(before); expect(readTask(taskId).status).toBe("delivered");
+    expect(readRun(taskId).work_outcome).toBeNull(); expect(countReplies(taskId)).toBe(0);
+    expect((await reply(taskId, { scheduled_work_outcome: "no_changes" })).ok).toBe(true);
+  });
+  test("REST rejects malformed and non-interval policy; MCP respects creator ownership", async () => {
+    for (const policy of ["true", 1, null]) {
+      const bad = await rest(ownerToken, "POST", "/api/scheduled-tasks", { network_id: network, name: "invalid1278", target_node_id: nodes.a.id, task: "fixture", schedule: { type: "interval", every_seconds: 120 }, no_change_backoff: policy }); expect(bad.status).toBe(400);
+    }
+    const bad = await rest(ownerToken, "POST", "/api/scheduled-tasks", { network_id: network, name: "once1278", target_node_id: nodes.a.id, task: "fixture", schedule: { type: "once", run_at: new Date(Date.now()+86400000).toISOString() }, no_change_backoff: true }); expect(bad.status).toBe(400);
+    const created = await mcp(nodes.a.token, "schedule_create", { name: "agent1278", task: "fixture", schedule: { type: "interval", every_seconds: 120 }, no_change_backoff: true }); expect(created.ok).toBe(true);
+    expect(created.schedule.no_change_backoff).toBe(true);
+    const id = created.schedule.schedule_id;
+    expect((await mcp(nodes.b.token, "schedule_update", { schedule_id: id, no_change_backoff: false })).ok).toBe(false);
+    expect((await mcp(nodes.a.token, "schedule_update", { schedule_id: id, no_change_backoff: false })).ok).toBe(true);
+    expect(state(id).no_change_backoff).toBe(0);
+    const human = await fire(); expect((await mcp(nodes.a.token, "schedule_update", { schedule_id: human.scheduleId, no_change_backoff: false })).ok).toBe(false);
+    db.run("UPDATE scheduled_tasks SET overlap_policy = 'allow' WHERE schedule_id = ?1", human.scheduleId);
+    const allow = await rest(ownerToken, "PATCH", `/api/scheduled-tasks/${human.scheduleId}`, { revision: state(human.scheduleId).revision, no_change_backoff: true });
+    expect(allow.status).toBe(400); expect(allow.body.error).toBe("no_change_backoff_requires_skip_overlap");
+  });
+});

package/src/scheduled-backoff.ts

@@ -0,0 +1,64 @@
+import { db } from "./db.js";
+
+type WakeHook = (id: string, network: string, now: Date) => boolean;
+let requirementWakeHook: WakeHook | null = null;
+export function setRequirementWakeHook(hook: WakeHook): void { requirementWakeHook = hook; }
+
+export function parseBackoffPolicy(raw: unknown, type: string, fallback = false): boolean {
+  if (raw !== undefined && typeof raw !== "boolean") throw new Error("invalid_no_change_backoff");
+  const enabled = raw === undefined ? fallback : raw as boolean;
+  if (enabled && type !== "interval") throw new Error("no_change_backoff_requires_interval");
+  return enabled;
+}
+
+/** SQLite only. Called in the reply/dispatch transaction; no catch-and-continue
+ * on state-write failure. Deriving a capped streak from authoritative runs
+ * makes duplicate or out-of-order callbacks unable to increment it twice. */
+export function refreshScheduledBackoff(scheduleId: string, networkId: string, now = new Date()): void {
+  if (db.transactionalFeaturesRefusal !== null) return;
+  if (requirementWakeHook?.(scheduleId, networkId, now)) return;
+  const row = db.get<any>(`SELECT status, revision, target_node_id, schedule_json,
+    no_change_backoff, overlap_policy, requirement_wake_json, backoff_streak, backoff_effective_seconds,
+    backoff_last_run_id, next_run_at FROM scheduled_tasks
+    WHERE schedule_id = ?1 AND network_id = ?2`, scheduleId, networkId);
+  if (!row || row.status !== "active" || row.no_change_backoff !== 1 || row.overlap_policy !== "skip") return;
+  // A DB-only process with no watcher loaded may not bypass its fence.
+  if (row.requirement_wake_json && !requirementWakeHook) return;
+  const spec = JSON.parse(row.schedule_json);
+  if (spec.type !== "interval") return;
+  // Include failures/skips/unknowns: excluding them would turn separated
+  // successes into a fictitious consecutive empty sequence. Six is a cap.
+  const runs = db.all<any>(`SELECT r.run_id, r.status, r.work_outcome,
+    r.schedule_revision, r.work_outcome_node_id, r.backoff_excluded,
+    t.status AS task_status, t.to_node_id, t.from_name
+    FROM scheduled_task_runs r LEFT JOIN tasks t
+      ON t.task_id = r.task_id AND t.network_id = r.network_id
+    WHERE r.schedule_id = ?1 AND r.network_id = ?2
+    ORDER BY r.scheduled_for DESC, r.created_at DESC, r.run_id DESC LIMIT 6`, scheduleId, networkId);
+  const latest = runs[0];
+  if (!latest || latest.schedule_revision !== row.revision
+    || latest.run_id === row.backoff_last_run_id
+    || ["claiming", "queued", "delivered"].includes(latest.status)) return;
+  let streak = 0;
+  for (const run of runs) {
+    if (run.schedule_revision !== row.revision || run.status !== "replied"
+      || run.task_status !== "replied" || run.work_outcome !== "no_changes"
+      || run.work_outcome_node_id !== row.target_node_id || run.to_node_id !== row.target_node_id
+      || run.from_name !== "scheduler" || run.backoff_excluded !== 0) break;
+    streak++;
+  }
+  const effective = Math.max(spec.every_seconds, streak >= 6 ? 1800 : streak >= 3 ? 600 : 0);
+  const previous = row.backoff_effective_seconds ?? spec.every_seconds;
+  let next = row.next_run_at;
+  if (effective !== previous && next) {
+    const candidate = now.getTime() + effective * 1000;
+    next = new Date(effective > previous ? Math.max(Date.parse(next), candidate)
+      : Math.min(Date.parse(next), candidate)).toISOString();
+  }
+  const result = db.run(`UPDATE scheduled_tasks SET backoff_streak = ?1,
+    backoff_effective_seconds = ?2, backoff_last_run_id = ?3, next_run_at = ?4,
+    updated_at = datetime('now') WHERE schedule_id = ?5 AND network_id = ?6
+    AND revision = ?7 AND status = 'active' AND no_change_backoff = 1`,
+    [streak, effective, latest.run_id, next, scheduleId, networkId, row.revision]);
+  if (result.changes !== 1) throw new Error("scheduled_backoff_atomic_write_failed");
+}

package/src/scheduled-outcome-guidance-http.test.ts

@@ -0,0 +1,139 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db, syncScheduledRunForTask } from "./db.js";
+import { refreshScheduledBackoff } from "./scheduled-backoff.js";
+import { getScheduleRow, dispatchScheduledOccurrence, runDueScheduledTasks } from "./scheduled-tasks.js";
+
+if (!process.env.COMMHUB_DB) throw new Error("test1284 requires an explicit disposable SQLite COMMHUB_DB");
+let server: any, base = "", network = "", ownerToken = "", ownerId = "";
+const stamp = Date.now(), nodes: Record<string, { id: string; alias: string; token: string; tokenId: string }> = {};
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const r = await fetch(base + path, { method, headers: { Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  return { status: r.status, body: await r.json() as any };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>) {
+  const r = await fetch(base + "/mcp", { method: "POST", headers: { Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }) });
+  const raw = await r.text(), line = raw.split("\n").find(x => x.startsWith("data: "));
+  const envelope = JSON.parse(line ? line.slice(6) : raw);
+  try { return JSON.parse(envelope.result.content[0].text); }
+  catch { return { ok: false, transportError: true }; }
+}
+const readRun = (taskId: string) => db.get<any>(
+  "SELECT run_id, schedule_id, status, work_outcome, work_outcome_node_id, schedule_revision FROM scheduled_task_runs WHERE task_id = ?1 AND network_id = ?2", taskId, network)!;
+const readTask = (taskId: string) => db.get<any>("SELECT status, result FROM tasks WHERE task_id = ?1", taskId)!;
+const countReplies = (taskId: string) => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM inbox WHERE in_reply_to = ?1 AND type = 'reply'", taskId)!.n;
+async function fire(enabled = true, interval = 120) {
+  const created = await rest(ownerToken, "POST", "/api/scheduled-tasks", { network_id: network,
+    name: `test1284-${crypto.randomUUID()}`, target_node_id: nodes.a.id, task: "核对实际需求；Owner 原文包含 no_changes 字样。",
+    schedule: { type: "interval", every_seconds: interval }, timezone: "UTC", no_change_backoff: enabled });
+  expect(created.status).toBe(201);
+  const scheduleId = created.body.schedule.schedule_id;
+  db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id != ?2", [new Date(Date.now() + 86400_000).toISOString(), scheduleId]);
+  db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [new Date(Date.now() - 1000).toISOString(), scheduleId]);
+  await runDueScheduledTasks();
+  const run = db.get<any>("SELECT task_id FROM scheduled_task_runs WHERE schedule_id = ?1", scheduleId)!;
+  expect(run.task_id).toBeTruthy();
+  return { taskId: run.task_id as string, scheduleId };
+}
+const reply = (taskId: string, meta?: unknown, status = "replied", token = nodes.a.token, extra = {}) =>
+  mcp(token, "send_reply", { in_reply_to: taskId, text: "本轮无新增", status, ...(meta === undefined ? {} : { meta }), ...extra });
+const cadence = (id: string) => db.get<any>("SELECT next_run_at, last_run_at, revision, schedule_json, target_node_id FROM scheduled_tasks WHERE schedule_id = ?1", id)!;
+
+beforeAll(async () => {
+  const owner = register(`guidance_owner_${stamp}`, "Fixture1274Only!x"); ownerToken = owner.token!;
+  network = owner.network_id!; ownerId = owner.user!.user_id;
+  for (const key of ["a", "b"]) {
+    const id = `n_work_${key}_${stamp}`, alias = `work-${key}-${stamp}`;
+    const token = createNetworkTokenForNode(ownerId, network, alias, id); expect(token.ok).toBe(true);
+    nodes[key] = { id, alias, token: token.token!, tokenId: token.token_id! };
+    db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, ?2, 'idle', ?3, ?4)", [`r_${id}`, alias, id, network]);
+  }
+  const mod = await import("./server.js"); server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+afterAll(() => server?.stop?.(true));
+
+
+const state = (id: string) => db.get<any>("SELECT no_change_backoff, backoff_streak, backoff_effective_seconds, backoff_last_run_id, next_run_at, revision, schedule_json, status FROM scheduled_tasks WHERE schedule_id = ?1", id)!;
+let occurrence = 0;
+async function nextRun(id: string) {
+  // Isolated fixture accelerates the clock, without touching live schedules.
+  const date = new Date(Date.now() + (++occurrence) * 1000).toISOString();
+  const out = dispatchScheduledOccurrence(getScheduleRow(id)!, date, true);
+  expect(out.taskId).toBeTruthy(); return out.taskId!;
+}
+
+const marker = "[Agent Network / scheduled work outcome]";
+const original = "核对实际需求；Owner 原文包含 no_changes 字样。";
+async function received(taskId: string) {
+  const out = await mcp(nodes.a.token,"get_task",{task_id:taskId});
+  expect(out.ok).toBe(true); expect(out.task.task_id).toBe(taskId); return out.task;
+}
+async function syntheticProducer(taskId: string, verified: "changed" | "no_changes") {
+  const task = await received(taskId);
+  expect(task.content).toContain(marker);
+  expect(task.content).toContain(`in_reply_to="${taskId}"`);
+  // This fixture chooses a known synthetic observation. It is not an LLM
+  // classifier and never parses reply prose to manufacture an outcome.
+  return reply(taskId,{scheduled_work_outcome:verified});
+}
+describe("#1284 opted-in dispatch guidance and explicit synthetic producer",()=>{
+  test("disabled schedules retain exact Owner task bytes in both task and inbox",async()=>{
+    const {taskId,scheduleId}=await fire(false), task=await received(taskId);
+    expect(task.content).toBe(original);
+    expect(db.get<any>("SELECT content FROM inbox WHERE task_id=?1",taskId).content).toBe(original);
+    expect(getScheduleRow(scheduleId)!.task_content).toBe(original);
+  });
+  test("human opt-in dispatch exposes exact task binding but does not annotate automatically",async()=>{
+    const {taskId,scheduleId}=await fire(),task=await received(taskId);
+    expect(task.content.startsWith(original)).toBe(true);
+    expect(task.content).toContain(`in_reply_to="${taskId}"`);
+    expect(task.content).toContain('"scheduled_work_outcome":"changed"');
+    expect(task.content).toContain('"scheduled_work_outcome":"no_changes"');
+    expect(task.content).toContain("未核实、失败、超时、过期、跳过");
+    expect(task.content).toContain("保留未知");
+    expect(db.get<any>("SELECT content FROM inbox WHERE task_id=?1",taskId).content).toBe(task.content);
+    expect(getScheduleRow(scheduleId)!.task_content).toBe(original);
+    expect(readRun(taskId).work_outcome).toBeNull(); expect(countReplies(taskId)).toBe(0);
+  });
+  test("three read-guidance explicit empty reports back off, a changed report restores base",async()=>{
+    const {taskId,scheduleId}=await fire();expect((await syntheticProducer(taskId,"no_changes")).ok).toBe(true);
+    for(let i=0;i<2;i++)expect((await syntheticProducer(await nextRun(scheduleId),"no_changes")).ok).toBe(true);
+    expect(state(scheduleId)).toMatchObject({backoff_streak:3,backoff_effective_seconds:600});
+    const changed=await nextRun(scheduleId);expect((await syntheticProducer(changed,"changed")).ok).toBe(true);
+    expect(readRun(changed).work_outcome).toBe("changed");
+    expect(state(scheduleId)).toMatchObject({backoff_streak:0,backoff_effective_seconds:120});
+  });
+  test("normal successful prose-only reply stays unknown despite prompt and no_changes words",async()=>{
+    const {taskId,scheduleId}=await fire();await received(taskId);
+    expect((await reply(taskId)).ok).toBe(true);expect(readRun(taskId).work_outcome).toBeNull();expect(state(scheduleId).backoff_streak).toBe(0);
+  });
+  test("guidance cannot turn a failed result into successful empty",async()=>{
+    const {taskId,scheduleId}=await fire();await received(taskId);
+    expect((await reply(taskId,{scheduled_work_outcome:"no_changes"},"failed")).ok).not.toBe(true);
+    expect(readTask(taskId).status).toBe("delivered");expect(countReplies(taskId)).toBe(0);
+    expect((await reply(taskId,undefined,"failed")).ok).toBe(true);expect(readRun(taskId).work_outcome).toBeNull();expect(state(scheduleId).backoff_streak).toBe(0);
+  });
+  test("revalidated persisted opt-in wins over a stale caller row",async()=>{
+    const {scheduleId,taskId}=await fire();expect((await reply(taskId)).ok).toBe(true);
+    const edit=await rest(ownerToken,"PATCH",`/api/scheduled-tasks/${scheduleId}`,{revision:state(scheduleId).revision,no_change_backoff:false});expect(edit.status).toBe(200);
+    const row={...getScheduleRow(scheduleId)!,no_change_backoff:1};
+    const out=dispatchScheduledOccurrence(row,new Date(Date.now()+(++occurrence)*1000).toISOString(),true);expect(out.taskId).toBeTruthy();
+    expect((await received(out.taskId!)).content).toBe(original);
+  });
+  test("agent-created schedules keep creator provenance ahead of Owner content and guidance",async()=>{
+    const made=await mcp(nodes.b.token,"schedule_create",{name:"agent guidance1284",task:original,target_node_id:nodes.a.id,no_change_backoff:true,schedule:{type:"interval",every_seconds:120}});expect(made.ok).toBe(true);
+    const id=made.schedule.schedule_id,taskId=await nextRun(id),task=await received(taskId);
+    expect(task.content).toContain(nodes.b.alias);expect(task.content.indexOf(nodes.b.alias)).toBeLessThan(task.content.indexOf(original));expect(task.content.indexOf(original)).toBeLessThan(task.content.indexOf(marker));
+    expect((await syntheticProducer(taskId,"changed")).ok).toBe(true);expect(readRun(taskId).work_outcome).toBe("changed");
+  });
+  test("another target cannot reuse the advertised binding; duplicate normal reply never counts twice",async()=>{
+    const {taskId,scheduleId}=await fire();await received(taskId);
+    expect((await reply(taskId,{scheduled_work_outcome:"no_changes"},"replied",nodes.b.token)).ok).not.toBe(true);
+    expect(readRun(taskId).work_outcome).toBeNull();expect((await syntheticProducer(taskId,"no_changes")).ok).toBe(true);
+    const before=state(scheduleId);expect((await reply(taskId,{scheduled_work_outcome:"no_changes"})).ok).not.toBe(true);expect(state(scheduleId)).toEqual(before);expect(countReplies(taskId)).toBe(1);
+  });
+});

package/src/scheduled-outcome-guidance.ts

@@ -0,0 +1,9 @@
+/** Dispatch guidance is not a classifier. Only an authenticated, successful
+ * producer's explicit reply may record an outcome; omissions stay unknown. */
+export function scheduledOutcomeGuidance(taskId: string): string {
+  return `\n\n[Agent Network / scheduled work outcome]\n` +
+    `此计划已显式启用空转退避。完成本轮实际工作并核验范围后，正常 send_reply 回原任务时使用 in_reply_to="${taskId}"。保留工具要求的原收件人、认证身份及 thread/turn 绑定。\n` +
+    `仅当本轮正常成功且确认有实质变更，添加 meta: {"scheduled_work_outcome":"changed"}；仅当正常成功且完成范围检查、确认没有实质变更，添加 meta: {"scheduled_work_outcome":"no_changes"}。\n` +
+    `未核实、失败、超时、过期、跳过或仅在等待输入/权限时，不自报 no_changes；不要从回复措辞或没有工具调用推断结果。缺少支持该字段的正常回复工具时保留未知，由原回复链路收口。\n` +
+    `此字段是本节点自报，不是独立完成证明。不要用 send_task/send_message 或额外消息补记结果，不要为了退避伪造成功或改动计划频率。`;
+}