@sleep2agi/commhub-server 0.9.0-preview.14 → 0.9.0-preview.141

package/src/scheduled-failures.ts

@@ -0,0 +1,179 @@
+// #523 —— 定时任务连续失败:告诉创建者(可选自动暂停)。
+//
+// 现场:一个每 2 分钟一次的排程,每一次派出去的任务都被节点以 failed 结束(上游模型拒绝),一天 720 次,
+//   排程照样 active,创建者什么都不知道。#464 只管「被上一次卡住」(skipped),不管「每次都失败」。
+//
+// 1. 计数:consecutive_failures = 最近一次成功(run.status='replied')之后,status='failed' 的 run 数。
+//    skipped / cancelled / expired / 还没结束的 run 不算失败,也不打断连续(expired 由 #464 的超时告警负责)。
+//    失败有两种来源,都会走到这里:派发时就失败(节点不在 / 被停用 / 降级 / 创建者无权限,
+//    scheduled-tasks.ts 提交后调用),以及派出去的任务以 failed 结束(db.ts 的 run 镜像触发钩子)。
+// 2. 告警:连续失败 ≥ N(默认 5)→ 给排程创建者发**一条**通知(agent-notice.ts,与 #462/#464 同一条路,
+//    出现在与目标节点的会话里)。去重落在 scheduled_tasks 两列上(条件写,一次只有一个调用方抢得到):
+//    failure_alert_key = 告警那一刻「最近一次成功」的 run_id —— 之后又成功过,key 就变了,下一段失败重新上膛;
+//    failure_alert_at  = 告警时间 —— 一直没成功过,24 小时后再提醒一次。Hub 重启不会重发。
+// 3. 自动暂停:默认关。COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS=M(≥1)时,连续失败 ≥ M 的 active 排程
+//    被置为 paused(next_run_at 清空,revision+1,与用户手动暂停同形),并通知创建者。
+//
+// 环境变量:COMMHUB_SCHEDULE_FAILURE_NOTICE_RUNS(N,默认 5)、COMMHUB_SCHEDULE_FAILURE_RENOTICE_SEC
+//   (默认 86400)、COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS(M,默认 0 = 关)。
+
+import { db, setScheduledRunTerminalHook } from "./db.js";
+import { sendAgentNotice } from "./agent-notice.js";
+
+export const SCHEDULE_FAILING_NOTICE_KIND = "schedule_failing";
+const ERROR_PREVIEW_CHARS = 300;
+
+function envInt(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 ? Math.floor(n) : fallback;
+}
+
+export function failureNoticeRuns(): number { return envInt("COMMHUB_SCHEDULE_FAILURE_NOTICE_RUNS", 5, 1); }
+export function failureRenoticeMs(): number { return envInt("COMMHUB_SCHEDULE_FAILURE_RENOTICE_SEC", 86_400, 1) * 1000; }
+/** 0 = 不自动暂停(默认)。 */
+export function failureAutoPauseRuns(): number { return envInt("COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS", 0, 0); }
+
+export type FailureStreak = { consecutiveFailures: number; lastSuccessRunId: string | null };
+
+/** 最近一次成功之后的失败 run 数。scheduled_for 每个排程唯一(UNIQUE),按它排序是确定的。 */
+export function failureStreak(scheduleId: string): FailureStreak {
+  const lastSuccess = db.get<{ run_id: string; scheduled_for: string }>(
+    "SELECT run_id, scheduled_for FROM scheduled_task_runs WHERE schedule_id = ?1 AND status = 'replied' ORDER BY scheduled_for DESC LIMIT 1",
+    scheduleId,
+  );
+  const n = db.get<{ n: number }>(
+    "SELECT COUNT(*) AS n FROM scheduled_task_runs WHERE schedule_id = ?1 AND status = 'failed' AND scheduled_for > ?2",
+    scheduleId, lastSuccess?.scheduled_for ?? "",
+  )?.n ?? 0;
+  return { consecutiveFailures: Number(n), lastSuccessRunId: lastSuccess?.run_id ?? null };
+}
+
+type ScheduleForAlert = {
+  schedule_id: string;
+  network_id: string;
+  created_by: string | null;
+  name: string;
+  target_alias: string;
+  status: string;
+};
+
+export type FailureNotice = {
+  reason: "failing" | "paused";
+  scheduleId: string;
+  scheduleName: string;
+  networkId: string;
+  createdBy: string;
+  alias: string;
+  failures: number;
+  errorCode: string | null;
+  errorMessage: string | null;
+};
+
+function latestFailure(scheduleId: string): { error_code: string | null; error_message: string | null } {
+  const row = db.get<{ error_code: string | null; error_message: string | null; result: string | null }>(
+    `SELECT r.error_code, r.error_message, t.result
+       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.status = 'failed'
+      ORDER BY r.scheduled_for DESC LIMIT 1`,
+    scheduleId,
+  );
+  // 任务以 failed 结束时 run.error_message 为空,原因在任务的回复正文里。
+  return { error_code: row?.error_code ?? null, error_message: row?.error_message || row?.result || null };
+}
+
+function truncate(s: string, max: number): string {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+export function failureNoticeText(n: FailureNotice): { title: string; text: string } {
+  const err = n.errorMessage ? truncate(n.errorMessage, ERROR_PREVIEW_CHARS) : "(没有错误详情)";
+  const code = n.errorCode ? ` [${n.errorCode}]` : "";
+  const head = `定时任务「${n.scheduleName}」(派给节点 ${n.alias})已经连续 ${n.failures} 次执行失败。\n\n最近一次的错误${code}:${err}\n\n`;
+  if (n.reason === "paused") {
+    return {
+      title: "定时任务连续失败,已自动暂停",
+      text: `${head}按 Hub 的设置,它已被自动暂停,不会再派发。处理好原因后,在定时任务里把它恢复为「启用」即可。`,
+    };
+  }
+  return {
+    title: "定时任务连续失败",
+    text: `${head}它仍在按计划运行。如需停止,在定时任务里暂停它(或 PATCH /api/scheduled-tasks/${n.scheduleId},body 带 {"status":"paused","revision":<当前 revision>})。`
+      + `在它重新成功之前,24 小时内不会再提醒。`,
+  };
+}
+
+export function sendFailureNotice(n: FailureNotice): string | null {
+  try {
+    const { title, text } = failureNoticeText(n);
+    return sendAgentNotice({
+      networkId: n.networkId, userId: n.createdBy, fromAlias: n.alias, kind: SCHEDULE_FAILING_NOTICE_KIND, title, text, severity: "error",
+      meta: { schedule_failing: { reason: n.reason, schedule_id: n.scheduleId, consecutive_failures: n.failures, error_code: n.errorCode } },
+      idPrefix: "dm_sched_",
+    });
+  } catch (e: any) {
+    console.error(`[scheduled-tasks] failure notice failed schedule=${n.scheduleId}: ${e?.message || e}`);
+    return null;
+  }
+}
+
+/**
+ * 一个 run 以 failed 结束之后调用(派发时失败 / 任务 failed 都算)。返回发出的通知(测试用),没有则 null。
+ * 告警与暂停都是条件写:并发的两个调用方只有一个写得进去,所以每段失败恰好一条通知。
+ */
+export function evaluateScheduleFailures(scheduleId: string, now = new Date()): FailureNotice | null {
+  const row = db.get<ScheduleForAlert>(
+    "SELECT schedule_id, network_id, created_by, name, target_alias, status FROM scheduled_tasks WHERE schedule_id = ?1",
+    scheduleId,
+  );
+  if (!row) return null;
+  const streak = failureStreak(scheduleId);
+  const noticeAt = failureNoticeRuns();
+  const pauseAt = failureAutoPauseRuns();
+  const wantsPause = pauseAt > 0 && streak.consecutiveFailures >= pauseAt && row.status === "active";
+  if (streak.consecutiveFailures < noticeAt && !wantsPause) return null;
+
+  let paused = false;
+  if (wantsPause) {
+    paused = db.run(
+      "UPDATE scheduled_tasks SET status = 'paused', next_run_at = NULL, revision = revision + 1, updated_at = datetime('now') WHERE schedule_id = ?1 AND status = 'active'",
+      [scheduleId],
+    ).changes === 1;
+  }
+  const key = streak.lastSuccessRunId ?? "";
+  const cutoff = new Date(now.getTime() - failureRenoticeMs()).toISOString();
+  // 去重:同一段失败(key 没变)且上次告警不到 24 小时 → 不写、不发。暂停是另一件事,照发。
+  const claimed = db.run(
+    `UPDATE scheduled_tasks SET failure_alert_at = ?1, failure_alert_key = ?2
+      WHERE schedule_id = ?3
+        AND (failure_alert_at IS NULL OR COALESCE(failure_alert_key, '') <> ?2 OR failure_alert_at <= ?4)`,
+    [now.toISOString(), key, scheduleId, cutoff],
+  ).changes === 1;
+  if (paused && !claimed) {
+    db.run("UPDATE scheduled_tasks SET failure_alert_at = ?1, failure_alert_key = ?2 WHERE schedule_id = ?3", [now.toISOString(), key, scheduleId]);
+  }
+  if (!paused && !claimed) return null;
+  if (!row.created_by) return null;
+  const latest = latestFailure(scheduleId);
+  const notice: FailureNotice = {
+    reason: paused ? "paused" : "failing",
+    scheduleId, scheduleName: row.name, networkId: row.network_id, createdBy: row.created_by, alias: row.target_alias,
+    failures: streak.consecutiveFailures, errorCode: latest.error_code, errorMessage: latest.error_message,
+  };
+  sendFailureNotice(notice);
+  return notice;
+}
+
+/** GET /runs 的附加字段。 */
+export function failureSummary(scheduleId: string): { consecutive_failures: number; failure_alert_threshold: number; last_failure_alert_at: string | null } {
+  const streak = failureStreak(scheduleId);
+  const alertAt = db.get<{ failure_alert_at: string | null }>("SELECT failure_alert_at FROM scheduled_tasks WHERE schedule_id = ?1", scheduleId)?.failure_alert_at ?? null;
+  return { consecutive_failures: streak.consecutiveFailures, failure_alert_threshold: failureNoticeRuns(), last_failure_alert_at: alertAt };
+}
+
+setScheduledRunTerminalHook((scheduleId, status) => {
+  if (status === "failed") evaluateScheduleFailures(scheduleId);
+});

package/src/scheduled-offline.test.ts

@@ -0,0 +1,131 @@
+// Board #757 — an offline scheduled target produces an auditable skip, not a
+// doomed task; each offline episode warns its human/Agent creator once.
+// Run: COMMHUB_DB=/tmp/board757.db bun test src/scheduled-offline.test.ts
+// PG: registered in tests/test2123-hub-postgres-ladder/run.sh.
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { register } from "./auth.js";
+import { db } from "./db.js";
+import { dispatchScheduledOccurrence, getScheduleRow } from "./scheduled-tasks.js";
+import { SCHEDULE_TARGET_OFFLINE_NOTICE_KIND, scheduledTargetOffline } from "./scheduled-offline.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("scheduled-offline requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+const TARGET_ID = `n_offline_target_${stamp}`;
+const TARGET = `offline-target-${stamp}`;
+const CREATOR_ID = `n_offline_creator_${stamp}`;
+const CREATOR = `offline-creator-${stamp}`;
+let NET = "", USER = "", slot = 0;
+
+function seedSchedule(createdByNodeId: string | null = null): any {
+  const id = `sched_offline_${crypto.randomUUID()}`;
+  db.run(
+    `INSERT INTO scheduled_tasks
+       (schedule_id, network_id, created_by, created_by_node_id, name, target_node_id, target_alias,
+        task_content, priority, schedule_type, schedule_json, timezone, status, next_run_at)
+     VALUES (?1, ?2, ?3, ?4, '离线巡检', ?5, ?6, 'ping', 'normal', 'interval',
+             '{"type":"interval","every_seconds":60}', 'Asia/Shanghai', 'active', datetime('now', '+1 minute'))`,
+    [id, NET, USER, createdByNodeId, TARGET_ID, TARGET],
+  );
+  return getScheduleRow(id)!;
+}
+
+function fire(schedule: any) {
+  const at = new Date(Date.UTC(2026, 9, 8, 0, 0, 0) + (++slot) * 60_000).toISOString();
+  return dispatchScheduledOccurrence(schedule, at, false, new Date());
+}
+
+function setTarget(status: "idle" | "offline", minutesAgo = 0) {
+  const seen = new Date(Date.now() - minutesAgo * 60_000).toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "");
+  db.run("UPDATE sessions SET status = ?1, updated_at = ?2, last_seen_at = ?2 WHERE node_id = ?3 AND network_id = ?4", [status, seen, TARGET_ID, NET]);
+}
+
+const taskCount = () => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM tasks WHERE network_id = ?1 AND to_node_id = ?2", NET, TARGET_ID)!.n;
+const humanNotices = (scheduleId: string) => db.all<{ meta_json: string; content: string }>(
+  "SELECT meta_json, content FROM user_inbox WHERE network_id = ?1 AND user_id = ?2 AND kind = ?3 ORDER BY created_at, message_id",
+  NET, USER, SCHEDULE_TARGET_OFFLINE_NOTICE_KIND,
+).filter((row) => JSON.parse(row.meta_json).schedule_target_offline.schedule_id === scheduleId);
+const agentNotices = (scheduleId: string) => db.all<{ meta_json: string; content: string }>(
+  "SELECT meta_json, content FROM inbox WHERE network_id = ?1 AND node_id = ?2 AND from_session = 'hub' ORDER BY created_at, id",
+  NET, CREATOR_ID,
+).filter((row) => JSON.parse(row.meta_json).schedule_target_offline?.schedule_id === scheduleId);
+
+beforeAll(() => {
+  const owner = register(`offline_owner_${stamp}`, "OfflineOwner123!", undefined, "seed");
+  expect(owner.ok).toBe(true);
+  NET = owner.network_id!; USER = owner.user!.user_id;
+  db.run("INSERT INTO nodes (node_id, node_name, alias, runtime, network_id, owner_user_id) VALUES (?1, ?2, ?2, 'codex', ?3, ?4)", [TARGET_ID, TARGET, NET, USER]);
+  db.run("INSERT INTO nodes (node_id, node_name, alias, runtime, network_id, owner_user_id) VALUES (?1, ?2, ?2, 'codex', ?3, ?4)", [CREATOR_ID, CREATOR, NET, USER]);
+  db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id, last_seen_at) VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'))", [`r_target_${stamp}`, TARGET, TARGET_ID, NET]);
+  db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id, last_seen_at) VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'))", [`r_creator_${stamp}`, CREATOR, CREATOR_ID, NET]);
+});
+
+afterAll(() => {
+  db.run("DELETE FROM user_inbox WHERE network_id = ?1 AND kind = ?2", [NET, SCHEDULE_TARGET_OFFLINE_NOTICE_KIND]);
+});
+
+describe("#757 scheduled target offline", () => {
+  test("offline skips without a task, warns a human once, and online recovery dispatches normally", () => {
+    const schedule = seedSchedule();
+    const online = fire(schedule);
+    expect(online.status).toBe("delivered");
+    db.run("UPDATE tasks SET status = 'replied' WHERE task_id = ?1", [online.taskId]);
+
+    setTarget("offline");
+    const before = taskCount();
+    const first = fire(schedule), second = fire(schedule);
+    expect([first.status, second.status]).toEqual(["skipped", "skipped"]);
+    expect(taskCount()).toBe(before);
+    for (const run of [first, second]) {
+      expect(db.get("SELECT status, error_code, task_id FROM scheduled_task_runs WHERE run_id = ?1", run.runId))
+        .toEqual({ status: "skipped", error_code: "target_offline", task_id: null });
+    }
+    expect(humanNotices(schedule.schedule_id)).toHaveLength(1);
+    expect(humanNotices(schedule.schedule_id)[0].content).toContain("恢复在线后");
+
+    setTarget("idle");
+    const recovered = fire(schedule);
+    expect(recovered.status).toBe("delivered");
+    expect(recovered.taskId).toBeTruthy();
+    db.run("UPDATE tasks SET status = 'replied' WHERE task_id = ?1", [recovered.taskId]);
+
+    setTarget("offline");
+    expect(fire(schedule).status).toBe("skipped");
+    expect(humanNotices(schedule.schedule_id)).toHaveLength(2);
+  });
+
+  test("an Agent-created schedule warns the creator inbox, never the owner's user inbox", () => {
+    const schedule = seedSchedule(CREATOR_ID);
+    setTarget("offline");
+    expect(fire(schedule).status).toBe("skipped");
+    expect(fire(schedule).status).toBe("skipped");
+    expect(agentNotices(schedule.schedule_id)).toHaveLength(1);
+    expect(agentNotices(schedule.schedule_id)[0].content).toContain("不需要回复");
+    expect(humanNotices(schedule.schedule_id)).toHaveLength(0);
+  });
+
+  test("an idle session older than the existing five-minute cutoff is offline", () => {
+    const schedule = seedSchedule();
+    setTarget("idle", 6);
+    const before = taskCount();
+    const run = fire(schedule);
+    expect(run.status).toBe("skipped");
+    expect(taskCount()).toBe(before);
+    expect(db.get<{ error_code: string }>("SELECT error_code FROM scheduled_task_runs WHERE run_id = ?1", run.runId)?.error_code).toBe("target_offline");
+  });
+
+  test("recent SQLite and ISO timestamps all keep an idle target online", () => {
+    const now = Date.now();
+    const isoMs = new Date(now - 1_000).toISOString();
+    const values = [
+      isoMs.slice(0, 19).replace("T", " "),
+      `${isoMs.slice(0, 19)}Z`,
+      isoMs,
+    ];
+    for (const value of values) {
+      db.run("UPDATE sessions SET status = 'idle', last_seen_at = ?1 WHERE node_id = ?2 AND network_id = ?3", [value, TARGET_ID, NET]);
+      expect(scheduledTargetOffline(TARGET_ID, TARGET, NET, now)).toBe(false);
+    }
+  });
+});

package/src/scheduled-offline.ts

@@ -0,0 +1,66 @@
+import { sendAgentNotice } from "./agent-notice.js";
+import { db, uuidv4 } from "./db.js";
+import { parseDbTimestampMs } from "./db-timestamp.js";
+import { pendingInboxCount } from "./inbox-count.js";
+import { pushEvent } from "./push.js";
+
+export const SCHEDULE_TARGET_OFFLINE_NOTICE_KIND = "schedule_target_offline";
+const SESSION_STALE_MS = 5 * 60_000;
+
+type SessionRow = { status: string | null; updated_at: string | null; last_seen_at: string | null };
+
+/** Same status + five-minute timestamp rule as the existing task delivery resolver. */
+export function scheduledTargetOffline(nodeId: string, alias: string, networkId: string, nowMs = Date.now()): boolean {
+  const session = db.get<SessionRow>(
+    "SELECT status, updated_at, last_seen_at FROM sessions WHERE node_id = ?1 AND network_id = ?2 ORDER BY updated_at DESC LIMIT 1",
+    nodeId, networkId,
+  ) ?? db.get<SessionRow>(
+    "SELECT status, updated_at, last_seen_at FROM sessions WHERE alias = ?1 AND network_id = ?2 AND node_id IS NULL ORDER BY updated_at DESC LIMIT 1",
+    alias, networkId,
+  );
+  if (!session) return true;
+  const raw = session.last_seen_at || session.updated_at;
+  const seen = raw ? parseDbTimestampMs(raw) : 0;
+  return String(session.status || "").toLowerCase() === "offline" || !Number.isFinite(seen) || nowMs - seen > SESSION_STALE_MS;
+}
+
+export type OfflineNotice = {
+  scheduleId: string; scheduleName: string; networkId: string;
+  createdBy: string | null; createdByNodeId: string | null;
+  targetAlias: string;
+};
+
+function noticeText(n: OfflineNotice): string {
+  return `定时任务「${n.scheduleName}」的目标节点 ${n.targetAlias} 已离线，本轮已跳过且没有创建任务。节点恢复在线后，后续轮次会自动照常派发。`;
+}
+
+/** Post-commit delivery. The transaction has already claimed this offline episode. */
+export function sendOfflineNotice(n: OfflineNotice): string | null {
+  try {
+    const text = noticeText(n);
+    const meta = { schedule_target_offline: { schedule_id: n.scheduleId, target_alias: n.targetAlias, reason: "target_offline" } };
+    if (!n.createdByNodeId) {
+      if (!n.createdBy) return null;
+      return sendAgentNotice({
+        networkId: n.networkId, userId: n.createdBy, fromAlias: n.targetAlias,
+        kind: SCHEDULE_TARGET_OFFLINE_NOTICE_KIND, title: "定时任务目标节点离线", text,
+        severity: "warning", meta, idPrefix: "dm_sched_offline_",
+      });
+    }
+    const creator = db.get<{ alias: string | null }>(
+      "SELECT alias FROM nodes WHERE node_id = ?1 AND network_id = ?2", n.createdByNodeId, n.networkId,
+    );
+    if (!creator?.alias) return null;
+    const id = `sched_offline_${uuidv4()}`;
+    db.run(
+      `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id, meta_json)
+       VALUES (?1, ?2, ?3, 'message', 'normal', ?4, 'hub', ?5, ?6)`,
+      [id, creator.alias, n.createdByNodeId, `[定时任务目标节点离线] ${text}\n(这是告警，不需要回复。)`, n.networkId, JSON.stringify(meta)],
+    );
+    pushEvent(creator.alias, { type: "new_message", inbox_count: pendingInboxCount(creator.alias, n.networkId), from: "hub", message_id: id }, n.networkId);
+    return id;
+  } catch (e: any) {
+    console.error(`[scheduled-tasks] offline notice failed schedule=${n.scheduleId}: ${e?.message || e}`);
+    return null;
+  }
+}

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 或额外消息补记结果，不要为了退避伪造成功或改动计划频率。`;
+}