@sleep2agi/commhub-server 0.9.0-preview.113 → 0.9.0-preview.115

package/src/schedule-agent.ts

@@ -0,0 +1,173 @@
+// Board #733 — Agents manage Hub scheduled tasks over MCP (schedule_* tools in tools.ts).
+//
+// REST /api/scheduled-tasks stays people-only (node tokens → 403 user_token_required). This module is the
+// agent surface; every validation / write goes through the same helpers as REST (scheduled-tasks.ts).
+//
+// Permission model (node token = one bound node in one network):
+//   • Scope: only schedules in the token's network that TARGET this node or that this node CREATED
+//     (created_by_node_id). Anything else reads as schedule_not_found (no existence probe).
+//   • Write gate: the owner must be able to write in the network (same canWrite as send_task), and a
+//     read-only node (permission_mode=readonly) cannot mutate schedules at all.
+//   • Target gate: a schedule (create, retarget, update, run-now) aimed at another node needs exactly the
+//     verdict send_task gets for that target (node-permissions.ts dispatchVerdict, owner's Agent grants +
+//     the node's mode). Stricter than send_task in one way: the verdict is enforced even under
+//     COMMHUB_NODE_PERMISSIONS=log, because the scheduler would refuse the run later anyway.
+//   • Mutations (update / pause / resume / cancel / run_now) only on schedules THIS node created
+//     (created_by_node_id = self). A person's schedule that targets the node is read-only for it.
+//   • created_by = the node's owner user id (the identity send_task's dispatchVerdict checks), so the
+//     scheduler's per-run canMessageAgent(created_by, …) keeps re-checking the owner's grants on every run.
+//     A node without a known owner cannot create schedules (a NULL created_by would skip that re-check).
+//   • Quota: ≤ COMMHUB_AGENT_SCHEDULE_QUOTA (default 20) active/paused schedules created per node.
+//     Minimum cadence is the shared parseScheduleSpec rule (interval ≥ 60 s), the same as REST.
+
+import { db } from "./db.js";
+import {
+  cancelSchedule, decodeRowForAgent, dispatchScheduledOccurrence, getScheduleRow, insertSchedule, patchSchedule,
+  scheduleRuns, ScheduleInputError, validateScheduleCreate, type ScheduledRow,
+} from "./scheduled-tasks.js";
+import { SCHEDULED_TASK_STORAGE_SELECT } from "./rest-projections.js";
+import { dispatchVerdict, nodePermissionDeniedBody, recordNodePermission, type NodeIdentity } from "./node-permissions.js";
+
+export type AgentScheduleResult = Record<string, unknown> & { ok: boolean };
+
+export function agentScheduleQuota(): number {
+  const n = Number(process.env.COMMHUB_AGENT_SCHEDULE_QUOTA);
+  return Number.isSafeInteger(n) && n > 0 ? n : 20;
+}
+
+const fail = (error: string, extra: Record<string, unknown> = {}): AgentScheduleResult => ({ ok: false, error, ...extra });
+
+/** The scope rule. Exported so the mutation tests can pin it. */
+export function nodeMaySeeSchedule(id: NodeIdentity, row: ScheduledRow): boolean {
+  if (!id.nodeId || row.network_id !== id.networkId) return false;
+  return row.target_node_id === id.nodeId || row.created_by_node_id === id.nodeId;
+}
+
+function visibleRow(id: NodeIdentity, scheduleId: string): ScheduledRow | null {
+  const row = getScheduleRow(scheduleId);
+  return row && nodeMaySeeSchedule(id, row) ? row : null;
+}
+
+/** Visible AND created by this node; else the error to return. Exported for the mutation tests. */
+export function nodeMayMutateSchedule(id: NodeIdentity, row: ScheduledRow): boolean {
+  return !!id.nodeId && row.created_by_node_id === id.nodeId;
+}
+function ownRow(id: NodeIdentity, scheduleId: string): ScheduledRow | AgentScheduleResult {
+  const row = visibleRow(id, scheduleId);
+  if (!row) return fail("schedule_not_found");
+  if (!nodeMayMutateSchedule(id, row)) return fail("not_schedule_creator", { message: "only schedules this node created can be changed" });
+  return row;
+}
+const isRow = (r: ScheduledRow | AgentScheduleResult): r is ScheduledRow => typeof (r as ScheduledRow).schedule_id === "string";
+
+/** send_task's verdict for this target, always enforced (see header). null = allowed. */
+function targetDenied(id: NodeIdentity, route: string, target: { node_id: string; alias: string }): AgentScheduleResult | null {
+  const verdict = dispatchVerdict(id, { alias: target.alias, nodeId: target.node_id });
+  if (!verdict) return null;
+  recordNodePermission(id, route, verdict.reason, verdict.sample);
+  return { ...nodePermissionDeniedBody(verdict.reason, route) };
+}
+
+function writeGate(id: NodeIdentity, canWrite: boolean, route: string): AgentScheduleResult | null {
+  if (!id.nodeId) return fail("node_identity_unbound");
+  if (!canWrite) return fail("permission_denied", { message: "this node's owner cannot write in this network" });
+  if (id.mode === "readonly") return { ...nodePermissionDeniedBody("mode_readonly", route) };
+  return null;
+}
+
+function inputError(e: any): AgentScheduleResult {
+  if (e instanceof ScheduleInputError) return fail(e.code, e.extra);
+  return fail(String(e?.message || "invalid_schedule"));
+}
+
+export function agentListSchedules(id: NodeIdentity, status?: string): AgentScheduleResult {
+  if (!id.nodeId) return fail("node_identity_unbound");
+  const params: unknown[] = [id.networkId, id.nodeId];
+  let sql = `SELECT ${SCHEDULED_TASK_STORAGE_SELECT} FROM scheduled_tasks WHERE network_id = ?1 AND (target_node_id = ?2 OR created_by_node_id = ?2)`;
+  if (status) { sql += " AND status = ?3"; params.push(status); }
+  sql += " ORDER BY updated_at DESC LIMIT 200";
+  return { ok: true, schedules: db.all<ScheduledRow>(sql, ...params).map(decodeRowForAgent) };
+}
+
+export function agentGetSchedule(id: NodeIdentity, scheduleId: string): AgentScheduleResult {
+  const row = visibleRow(id, scheduleId);
+  return row ? { ok: true, schedule: decodeRowForAgent(row) } : fail("schedule_not_found");
+}
+
+export function agentScheduleRuns(id: NodeIdentity, scheduleId: string, limit?: number): AgentScheduleResult {
+  const row = visibleRow(id, scheduleId);
+  if (!row) return fail("schedule_not_found");
+  return { ok: true, ...scheduleRuns(row, Math.max(1, Math.min(200, Math.floor(Number(limit)) || 50))) };
+}
+
+export function agentCreateSchedule(id: NodeIdentity, canWrite: boolean, body: Record<string, unknown>): AgentScheduleResult {
+  const route = "mcp:schedule_create";
+  const gate = writeGate(id, canWrite, route);
+  if (gate) return gate;
+  if (!id.ownerUserId) return { ...nodePermissionDeniedBody("owner_unknown", route) };
+  const input = { ...body, target_node_id: body.target_node_id ?? id.nodeId };
+  let v: ReturnType<typeof validateScheduleCreate>;
+  try { v = validateScheduleCreate(id.networkId, input); } catch (e) { return inputError(e); }
+  const denied = targetDenied(id, route, v.target);
+  if (denied) return denied;
+  const quota = agentScheduleQuota();
+  const used = Number(db.get<{ n: number | string }>(
+    "SELECT COUNT(*) AS n FROM scheduled_tasks WHERE network_id = ?1 AND created_by_node_id = ?2 AND status IN ('active', 'paused')",
+    id.networkId, id.nodeId,
+  )?.n ?? 0);
+  if (used >= quota) return fail("schedule_quota_exceeded", { quota, active: used, message: "cancel one of this node's schedules first" });
+  const row = insertSchedule(id.networkId, id.ownerUserId, id.nodeId, v);
+  return { ok: true, schedule: decodeRowForAgent(row) };
+}
+
+export function agentUpdateSchedule(id: NodeIdentity, canWrite: boolean, scheduleId: string, body: Record<string, unknown>): AgentScheduleResult {
+  const route = "mcp:schedule_update";
+  const gate = writeGate(id, canWrite, route);
+  if (gate) return gate;
+  const row = ownRow(id, scheduleId);
+  if (!isRow(row)) return row;
+  if (body.base_revision !== undefined && Number(body.base_revision) !== row.revision) {
+    return fail("revision_conflict", { current_revision: row.revision });
+  }
+  const retarget = body.target_node_id !== undefined && body.target_node_id !== row.target_node_id;
+  let target = { node_id: row.target_node_id, alias: row.target_alias };
+  if (retarget) {
+    const node = db.get<{ node_id: string; alias: string | null }>(
+      "SELECT node_id, alias FROM nodes WHERE node_id = ?1 AND network_id = ?2", String(body.target_node_id), row.network_id);
+    if (!node?.alias) return fail("target_node_not_found");
+    target = { node_id: node.node_id, alias: node.alias };
+  }
+  const denied = targetDenied(id, route, target);
+  if (denied) return denied;
+  try {
+    const patched = patchSchedule(row, { ...body, revision: body.revision ?? row.revision });
+    return { ok: true, schedule: decodeRowForAgent(patched) };
+  } catch (e) { return inputError(e); }
+}
+
+export function agentCancelSchedule(id: NodeIdentity, canWrite: boolean, scheduleId: string): AgentScheduleResult {
+  const gate = writeGate(id, canWrite, "mcp:schedule_cancel");
+  if (gate) return gate;
+  const row = ownRow(id, scheduleId);
+  if (!isRow(row)) return row;
+  cancelSchedule(row);
+  return { ok: true, status: "cancelled" };
+}
+
+export function agentRunScheduleNow(id: NodeIdentity, canWrite: boolean, scheduleId: string): AgentScheduleResult {
+  const route = "mcp:schedule_run_now";
+  const gate = writeGate(id, canWrite, route);
+  if (gate) return gate;
+  const row = ownRow(id, scheduleId);
+  if (!isRow(row)) return row;
+  if (row.status === "cancelled") return fail("schedule_cancelled");
+  const denied = targetDenied(id, route, { node_id: row.target_node_id, alias: row.target_alias });
+  if (denied) return denied;
+  try {
+    const result = dispatchScheduledOccurrence(row, new Date().toISOString(), false);
+    const { event: _event, ...rest } = result;
+    return { ok: result.status !== "failed", ...rest };
+  } catch (e: any) {
+    return fail("dispatch_failed", { message: String(e?.message || e).slice(0, 500) });
+  }
+}

package/src/scheduled-tasks.ts

@@ -4,7 +4,8 @@ import { TASK_CONTENT_MAX, sessionTaskPreview } from "./shared/task-content-limi
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { assertNodeHealthy } from "./node-health-guard.js";
 import { addNetworkScope, canRestWriteNetwork, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
-import { canMessageAgent } from "./agent-access.js";
+import { canMessageAgent, type AgentRef } from "./agent-access.js";
+import { dispatchVerdict } from "./node-permissions.js";
 import { hasSubscribers, pushEvent, pushNetworkObserverEvent } from "./push.js";
 import { SCHEDULED_TASK_STORAGE_SELECT } from "./rest-projections.js";
 import { parseDbTimestampMs } from "./db-timestamp.js";
@@ -19,10 +20,11 @@ export type ScheduleSpec =
 
 export type MisfirePolicy = "catch_up_once" | "skip";
 
-type ScheduledRow = {
+export type ScheduledRow = {
   schedule_id: string;
   network_id: string;
   created_by: string | null;
+  created_by_node_id: string | null;
   name: string;
   target_node_id: string;
   target_alias: string;
@@ -178,13 +180,135 @@ export function nextOccurrence(spec: ScheduleSpec, timezone: string, after: Date
   throw new Error("next_occurrence_unresolvable");
 }
 
+/** REST shape (pinned by rest-explicit-columns-http.test.ts): creator ids stay server-side. */
 function decodeRow(row: ScheduledRow): Record<string, unknown> {
   let schedule: unknown = null;
   try { schedule = JSON.parse(row.schedule_json); } catch {}
-  const { created_by: _createdBy, schedule_json: _scheduleJson, ...publicRow } = row;
+  const { created_by: _createdBy, created_by_node_id: _createdByNode, schedule_json: _scheduleJson, ...publicRow } = row;
   return { ...publicRow, schedule };
 }
 
+/** MCP (agent) shape: REST shape + which node created it (null = a person / old row). Never the user id. */
+export function decodeRowForAgent(row: ScheduledRow): Record<string, unknown> {
+  return { ...decodeRow(row), created_by_node_id: row.created_by_node_id ?? null };
+}
+
+export function getScheduleRow(scheduleId: string): ScheduledRow | null {
+  return db.get<ScheduledRow>(`SELECT ${SCHEDULED_TASK_STORAGE_SELECT} FROM scheduled_tasks WHERE schedule_id = ?1`, scheduleId);
+}
+
+export class ScheduleInputError extends Error {
+  constructor(public code: string, public status: number, public extra: Record<string, unknown> = {}) { super(code); }
+}
+
+export type ValidatedScheduleCreate = {
+  name: string; content: string; priority: string; misfirePolicy: MisfirePolicy;
+  target: { node_id: string; alias: string }; spec: ScheduleSpec; timezone: string; next: Date;
+};
+
+/** Shared by REST POST and MCP schedule_create. Throws Error(code) like before. */
+export function validateScheduleCreate(networkId: string, body: Record<string, unknown>): ValidatedScheduleCreate {
+  const name = typeof body.name === "string" ? body.name.trim() : "";
+  const content = typeof body.task === "string" ? body.task.trim() : "";
+  if (!name || name.length > 120) throw new Error("invalid_name");
+  if (!content || content.length > TASK_CONTENT_MAX) throw new Error("invalid_task");
+  const priority = typeof body.priority === "string" ? body.priority : "normal";
+  if (!PRIORITIES.has(priority)) throw new Error("invalid_priority");
+  const misfirePolicy = parseMisfirePolicy(body.misfire_policy);
+  const target = validateTarget(networkId, body.target_node_id);
+  const { spec, timezone } = parseScheduleSpec(body.schedule, body.timezone);
+  const next = nextOccurrence(spec, timezone, new Date());
+  if (!next) throw new Error("schedule_has_no_future_occurrence");
+  return { name, content, priority, misfirePolicy, target, spec, timezone, next };
+}
+
+export function insertSchedule(networkId: string, createdBy: string | null, createdByNodeId: string | null, v: ValidatedScheduleCreate): ScheduledRow {
+  const scheduleId = `sched_${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, overlap_policy, misfire_policy, next_run_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, 'skip', ?13, ?14)`,
+    [scheduleId, networkId, createdBy, createdByNodeId, v.name, v.target.node_id, v.target.alias, v.content, v.priority, v.spec.type, JSON.stringify(v.spec), v.timezone, v.misfirePolicy, iso(v.next)],
+  );
+  return getScheduleRow(scheduleId)!;
+}
+
+/** Idempotent cancel (shared by REST DELETE / POST cancel and MCP schedule_cancel). */
+export function cancelSchedule(row: ScheduledRow): void {
+  if (row.status === "cancelled") return;
+  db.run("UPDATE scheduled_tasks SET status = 'cancelled', next_run_at = NULL, revision = revision + 1, updated_at = datetime('now') WHERE schedule_id = ?1", [row.schedule_id]);
+}
+
+export function scheduleRuns(row: ScheduledRow, limit: number): Record<string, unknown> {
+  const runs = db.all(
+    // #523 — a task that ended `failed` leaves run.error_message empty; its reason is the task's reply text.
+    `SELECT r.run_id, r.schedule_id, r.scheduled_for, r.task_id, r.status, r.error_code,
+            CASE WHEN r.error_message IS NULL AND r.status = 'failed' THEN SUBSTR(t.result, 1, 500) ELSE r.error_message END AS error_message,
+            r.blocked_by_task_id, r.blocked_by_state, r.created_at, r.completed_at
+       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.created_at DESC, r.scheduled_for DESC LIMIT ?3`,
+    row.schedule_id, row.network_id, limit,
+  );
+  return { runs, ...failureSummary(row.schedule_id) };
+}
+
+/** Shared PATCH semantics (REST PATCH and MCP schedule_update). Throws ScheduleInputError. */
+export function patchSchedule(row: ScheduledRow, body: Record<string, unknown>): ScheduledRow {
+  // Cancellation/completion are terminal states. Editing must never become
+  // an implicit resurrection path (including by supplying status=active).
+  if (row.status === "cancelled") throw new ScheduleInputError("schedule_cancelled", 409);
+  if (row.status === "completed") throw new ScheduleInputError("schedule_completed", 409);
+  if (!Number.isSafeInteger(body.revision) || Number(body.revision) !== row.revision) throw new ScheduleInputError("revision_conflict", 409, { current_revision: row.revision });
+  try {
+    const name = body.name === undefined ? row.name : String(body.name).trim();
+    const content = body.task === undefined ? row.task_content : String(body.task).trim();
+    const priority = body.priority === undefined ? row.priority : String(body.priority);
+    if (!name || name.length > 120) throw new Error("invalid_name");
+    if (!content || content.length > TASK_CONTENT_MAX) throw new Error("invalid_task");
+    if (!PRIORITIES.has(priority)) throw new Error("invalid_priority");
+    const target = body.target_node_id === undefined ? { node_id: row.target_node_id, alias: row.target_alias } : validateTarget(row.network_id, body.target_node_id);
+    const parsed = body.schedule === undefined
+      ? { spec: JSON.parse(row.schedule_json) as ScheduleSpec, timezone: body.timezone === undefined ? row.timezone : String(body.timezone) }
+      : parseScheduleSpec(body.schedule, body.timezone === undefined ? row.timezone : body.timezone);
+    if (!validTimezone(parsed.timezone)) throw new Error("invalid_timezone");
+    const requestedStatus = body.status === undefined ? row.status : String(body.status);
+    if (!new Set(["active", "paused"]).has(requestedStatus)) throw new Error("invalid_status");
+    const misfirePolicy = parseMisfirePolicy(body.misfire_policy, row.misfire_policy);
+    // Editing descriptive fields must not silently reset the schedule's
+    // cadence. Recompute only when the scheduling inputs change, when a
+    // paused schedule resumes, or when repairing an impossible active row
+    // with no next occurrence. The recompute uses the same DST-safe helper
+    // as creation and dispatch advancement.
+    const scheduleJson = JSON.stringify(parsed.spec);
+    const schedulingChanged = scheduleJson !== row.schedule_json || parsed.timezone !== row.timezone;
+    const resumed = row.status !== "active" && requestedStatus === "active";
+    const next = requestedStatus !== "active"
+      ? null
+      : schedulingChanged || resumed || !row.next_run_at
+        ? 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 = 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, keepStoredNext],
+    );
+    if (updated.changes !== 1) throw new ScheduleInputError("revision_conflict", 409);
+    return getScheduleRow(row.schedule_id)!;
+  } catch (e: any) {
+    if (e instanceof ScheduleInputError) throw e;
+    const code = String(e?.message || "invalid_schedule");
+    throw new ScheduleInputError(code, code === "target_node_not_found" ? 404 : 400);
+  }
+}
+
 function scopedSchedule(scheduleId: string, scope: RestNetworkScope): ScheduledRow | null {
   const params: unknown[] = [scheduleId];
   let sql = `SELECT ${SCHEDULED_TASK_STORAGE_SELECT} FROM scheduled_tasks WHERE schedule_id = ?1`;
@@ -215,6 +339,25 @@ function stuckNoticeFor(row: ScheduledRow, reason: StuckNotice["reason"], blocke
   };
 }
 
+/** The line an Agent-created schedule's task always starts with (board #733). */
+export function agentSchedulePrefix(alias: string | null, nodeId: string): string {
+  return `[scheduled by agent ${alias ?? "?"} (${nodeId})]\n`;
+}
+
+function agentCreatorDenial(row: ScheduledRow, target: AgentRef): { code: string; message: string } | null {
+  const creator = db.get<{ alias: string | null; owner_user_id: string | null; permission_mode: string | null }>(
+    "SELECT alias, owner_user_id, permission_mode FROM nodes WHERE node_id = ?1 AND network_id = ?2", row.created_by_node_id, row.network_id);
+  if (!creator) return { code: "creator_node_gone", message: "The node that created this schedule no longer exists in this network" };
+  const mode = creator.permission_mode === "readonly" || creator.permission_mode === "restricted" ? creator.permission_mode : "normal";
+  if (mode === "readonly") return { code: "creator_node_readonly", message: "The node that created this schedule is read-only" };
+  const verdict = dispatchVerdict({
+    networkId: row.network_id, nodeId: row.created_by_node_id, logKey: row.created_by_node_id!,
+    aliases: creator.alias ? [creator.alias] : [], ownerUserId: creator.owner_user_id, mode,
+  }, target);
+  if (verdict) return { code: "creator_access_revoked", message: `The node that created this schedule may not send_task to this agent now (${verdict.reason})` };
+  return null;
+}
+
 type DispatchEvent = { alias: string; networkId: string; taskId: string; priority: string; state: "delivered" | "queued" };
 
 export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: string, advanceSchedule: boolean, advanceAfter = new Date()): { runId: string; taskId?: string; status: string; event?: DispatchEvent } {
@@ -302,15 +445,25 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
     }
     // 多用户 Agent 权限:排程是「建它的人」的委托。建的人后来被设成受限成员、而且没被授权
     // 给目标 Agent 发任务时,不再代他派发(否则受限前建的排程会永远绕过授权)。
-    if (row.created_by && !canMessageAgent(row.created_by, row.network_id, { alias: node.alias, nodeId: node.node_id })) {
+    // Board #733 — an Agent-created schedule is that node's standing send_task: every run re-evaluates the
+    // creating node as it is NOW (exists, not read-only, current owner) with send_task's own dispatchVerdict.
+    const creatorDenial = row.created_by_node_id
+      ? agentCreatorDenial(row, { alias: node.alias, nodeId: node.node_id })
+      : row.created_by && !canMessageAgent(row.created_by, row.network_id, { alias: node.alias, nodeId: node.node_id })
+        ? { code: "creator_access_revoked", message: "The schedule creator is no longer allowed to message this agent" }
+        : null;
+    if (creatorDenial) {
       finalStatus = "failed";
       db.run(
-        "UPDATE scheduled_task_runs SET status = 'failed', error_code = 'creator_access_revoked', error_message = 'The schedule creator is no longer allowed to message this agent', completed_at = datetime('now') WHERE run_id = ?1",
-        [runId],
+        "UPDATE scheduled_task_runs SET status = 'failed', error_code = ?1, error_message = ?2, completed_at = datetime('now') WHERE run_id = ?3",
+        [creatorDenial.code, creatorDenial.message, runId],
       );
       if (advanceSchedule) advance(row, scheduledFor, advanceAfter);
       return;
     }
+    const creatorNode = row.created_by_node_id
+      ? db.get<{ alias: string | null }>("SELECT alias FROM nodes WHERE node_id = ?1 AND network_id = ?2", row.created_by_node_id, row.network_id)
+      : null;
     const lifecycle = assertNodeActive(node.alias, row.network_id);
     if (!lifecycle.ok) {
       finalStatus = "failed";
@@ -349,26 +502,32 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
     );
     const deliveryState: "delivered" | "queued" =
       (session && session.status !== "offline") || hasSubscribers(node.alias, row.network_id) ? "delivered" : "queued";
+    // Board #733 — provenance is server-set: an Agent-created schedule names its node in meta and in a
+    // prefix the receiving agent always sees first, so it can never pass as a person's schedule.
     const metaJson = JSON.stringify({
       scheduled_task_id: row.schedule_id,
       scheduled_run_id: runId,
       scheduled_for: scheduledFor,
       auth_origin: "hub_scheduler",
+      ...(row.created_by_node_id ? { scheduled_by_node_id: row.created_by_node_id, scheduled_by_alias: creatorNode?.alias ?? null } : {}),
     });
+    const taskContent = row.created_by_node_id
+      ? `${agentSchedulePrefix(creatorNode?.alias ?? null, row.created_by_node_id)}${row.task_content}`
+      : row.task_content;
     db.run(
       `INSERT INTO inbox (id, task_id, session_name, node_id, type, priority, content, from_session, requires_response, network_id, meta_json)
        VALUES (?1, ?1, ?2, ?3, 'task', ?4, ?5, 'scheduler', 'reply', ?6, ?7)`,
-      [taskId, node.alias, node.node_id, row.priority, row.task_content, row.network_id, metaJson],
+      [taskId, node.alias, node.node_id, row.priority, taskContent, row.network_id, metaJson],
     );
     db.run(
       `INSERT INTO tasks (task_id, from_name, to_node_id, to_name, priority, status, content, requires_response, created_at, delivered_at, expires_at, network_id, meta_json)
        VALUES (?1, 'scheduler', ?2, ?3, ?4, 'delivered', ?5, 'reply', datetime('now'), datetime('now'), datetime('now', '+86400 seconds'), ?6, ?7)`,
-      [taskId, node.node_id, node.alias, row.priority, row.task_content, row.network_id, metaJson],
+      [taskId, node.node_id, node.alias, row.priority, taskContent, row.network_id, metaJson],
     );
     // Dispatch is not completion. Keep the run open until the exact bound
     // task reaches replied/failed/cancelled/expired; db.ts owns that mirror.
     db.run("UPDATE scheduled_task_runs SET task_id = ?1, status = ?2, completed_at = NULL WHERE run_id = ?3", [taskId, deliveryState, runId]);
-    db.run(`UPDATE sessions SET task = ${sessionTaskOnDispatch("?1")}, updated_at = datetime('now') WHERE node_id = ?2 AND network_id = ?3`, [sessionTaskPreview(row.task_content), node.node_id, row.network_id]);
+    db.run(`UPDATE sessions SET task = ${sessionTaskOnDispatch("?1")}, updated_at = datetime('now') WHERE node_id = ?2 AND network_id = ?3`, [sessionTaskPreview(taskContent), node.node_id, row.network_id]);
     db.run("UPDATE scheduled_tasks SET target_alias = ?1, last_run_at = ?2, updated_at = datetime('now') WHERE schedule_id = ?3", [node.alias, scheduledFor, row.schedule_id]);
     if (advanceSchedule) advance({ ...row, target_alias: node.alias }, scheduledFor, advanceAfter);
     createdTaskId = taskId;
@@ -516,25 +675,7 @@ export async function handleScheduledTaskRequest(ctx: ScheduledRequestContext):
     if (!networkId) return jsonError("network_id_required", 400);
     if (!writeAllowed(ctx, networkId)) return jsonError("permission_denied", 403);
     try {
-      const name = typeof body.name === "string" ? body.name.trim() : "";
-      const content = typeof body.task === "string" ? body.task.trim() : "";
-      if (!name || name.length > 120) throw new Error("invalid_name");
-      if (!content || content.length > TASK_CONTENT_MAX) throw new Error("invalid_task");
-      const priority = typeof body.priority === "string" ? body.priority : "normal";
-      if (!PRIORITIES.has(priority)) throw new Error("invalid_priority");
-      const misfirePolicy = parseMisfirePolicy(body.misfire_policy);
-      const target = validateTarget(networkId, body.target_node_id);
-      const { spec, timezone } = parseScheduleSpec(body.schedule, body.timezone);
-      const next = nextOccurrence(spec, timezone, new Date());
-      if (!next) throw new Error("schedule_has_no_future_occurrence");
-      const scheduleId = `sched_${crypto.randomUUID()}`;
-      db.run(
-        `INSERT INTO scheduled_tasks
-         (schedule_id, network_id, created_by, name, target_node_id, target_alias, task_content, priority, schedule_type, schedule_json, timezone, overlap_policy, misfire_policy, next_run_at)
-         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, 'skip', ?12, ?13)`,
-        [scheduleId, networkId, ctx.auth?.userId ?? null, name, target.node_id, target.alias, content, priority, spec.type, JSON.stringify(spec), timezone, misfirePolicy, iso(next)],
-      );
-      const created = db.get<ScheduledRow>(`SELECT ${SCHEDULED_TASK_STORAGE_SELECT} FROM scheduled_tasks WHERE schedule_id = ?1`, scheduleId)!;
+      const created = insertSchedule(networkId, ctx.auth?.userId ?? null, null, validateScheduleCreate(networkId, body));
       return Response.json({ ok: true, schedule: decodeRow(created) }, { status: 201 });
     } catch (e: any) {
       const code = String(e?.message || "invalid_schedule");
@@ -552,17 +693,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(
-      // #523 — a task that ended `failed` leaves run.error_message empty; its reason is the task's reply text.
-      `SELECT r.run_id, r.schedule_id, r.scheduled_for, r.task_id, r.status, r.error_code,
-              CASE WHEN r.error_message IS NULL AND r.status = 'failed' THEN SUBSTR(t.result, 1, 500) ELSE r.error_message END AS error_message,
-              r.blocked_by_task_id, r.blocked_by_state, r.created_at, r.completed_at
-         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.created_at DESC, r.scheduled_for DESC LIMIT ?3`,
-      row.schedule_id, row.network_id, limit,
-    );
-    return Response.json({ ok: true, runs, ...failureSummary(row.schedule_id) });
+    return Response.json({ ok: true, ...scheduleRuns(row, limit) });
   }
   if (!sub && req.method === "GET") return Response.json({ ok: true, schedule: decodeRow(row) });
   if (!writeAllowed(ctx, row.network_id)) return jsonError("permission_denied", 403);
@@ -588,64 +719,18 @@ export async function handleScheduledTaskRequest(ctx: ScheduledRequestContext):
   // "cancelled" between polls) should get the same outcome whether it's the
   // first click or a retry.
   if ((!sub && req.method === "DELETE") || (sub === "cancel" && req.method === "POST")) {
-    if (row.status === "cancelled") return Response.json({ ok: true, status: "cancelled" });
-    db.run("UPDATE scheduled_tasks SET status = 'cancelled', next_run_at = NULL, revision = revision + 1, updated_at = datetime('now') WHERE schedule_id = ?1", [row.schedule_id]);
+    cancelSchedule(row);
     return Response.json({ ok: true, status: "cancelled" });
   }
 
   if (!sub && req.method === "PATCH") {
     let body: Record<string, unknown>;
     try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
-    // Cancellation/completion are terminal states. Editing must never become
-    // an implicit resurrection path (including by supplying status=active).
-    if (row.status === "cancelled") return jsonError("schedule_cancelled", 409);
-    if (row.status === "completed") return jsonError("schedule_completed", 409);
-    if (!Number.isSafeInteger(body.revision) || Number(body.revision) !== row.revision) return jsonError("revision_conflict", 409, { current_revision: row.revision });
     try {
-      const name = body.name === undefined ? row.name : String(body.name).trim();
-      const content = body.task === undefined ? row.task_content : String(body.task).trim();
-      const priority = body.priority === undefined ? row.priority : String(body.priority);
-      if (!name || name.length > 120) throw new Error("invalid_name");
-      if (!content || content.length > TASK_CONTENT_MAX) throw new Error("invalid_task");
-      if (!PRIORITIES.has(priority)) throw new Error("invalid_priority");
-      const target = body.target_node_id === undefined ? { node_id: row.target_node_id, alias: row.target_alias } : validateTarget(row.network_id, body.target_node_id);
-      const parsed = body.schedule === undefined
-        ? { spec: JSON.parse(row.schedule_json) as ScheduleSpec, timezone: body.timezone === undefined ? row.timezone : String(body.timezone) }
-        : parseScheduleSpec(body.schedule, body.timezone === undefined ? row.timezone : body.timezone);
-      if (!validTimezone(parsed.timezone)) throw new Error("invalid_timezone");
-      const requestedStatus = body.status === undefined ? row.status : String(body.status);
-      if (!new Set(["active", "paused"]).has(requestedStatus)) throw new Error("invalid_status");
-      const misfirePolicy = parseMisfirePolicy(body.misfire_policy, row.misfire_policy);
-      // Editing descriptive fields must not silently reset the schedule's
-      // cadence. Recompute only when the scheduling inputs change, when a
-      // paused schedule resumes, or when repairing an impossible active row
-      // with no next occurrence. The recompute uses the same DST-safe helper
-      // as creation and dispatch advancement.
-      const scheduleJson = JSON.stringify(parsed.spec);
-      const schedulingChanged = scheduleJson !== row.schedule_json || parsed.timezone !== row.timezone;
-      const resumed = row.status !== "active" && requestedStatus === "active";
-      const next = requestedStatus !== "active"
-        ? null
-        : schedulingChanged || resumed || !row.next_run_at
-          ? 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 = 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, 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)!) });
+      return Response.json({ ok: true, schedule: decodeRow(patchSchedule(row, body)) });
     } catch (e: any) {
-      const code = String(e?.message || "invalid_schedule");
-      return jsonError(code, code === "target_node_not_found" ? 404 : 400);
+      if (e instanceof ScheduleInputError) return jsonError(e.code, e.status, e.extra);
+      throw e;
     }
   }
   return jsonError("method_not_allowed", 405);

package/src/server.ts

@@ -78,6 +78,7 @@ import { resolveRestFromSession } from "./rest-identity.js";
 import { resolveNodeCaller } from "./create-node.js";
 import { stampTaskAuthOrigin, type TaskAuthOrigin } from "./task-auth-origin.js";
 import { diagnoseTask } from "./task-diagnostic.js";
+import { listTaskLateReplies } from "./task-late-replies.js";
 import { assertScheduledTaskBackendSupported, handleScheduledTaskRequest, startScheduledTaskScheduler } from "./scheduled-tasks.js";
 import { startDueReminderTimer } from "./requirement-due-reminders.js";
 import { handleRequirementsRequest } from "./requirements.js";
@@ -3969,7 +3970,9 @@ return Bun.serve({
       const since = url.searchParams.get("since") ?? new Date(Date.now() - 3600000).toISOString().replace("T", " ").slice(0, 19);
       const alias = url.searchParams.get("alias")?.trim() || null;
       const params: any[] = [since];
-      let sql = "SELECT id, session_name as to_alias, from_session as from_alias, type, priority, content, acked, created_at, network_id FROM inbox WHERE created_at >= ?1";
+      let sql = `SELECT id, session_name as to_alias, from_session as from_alias, type, priority, content, acked, created_at, network_id,
+        CASE WHEN EXISTS(SELECT 1 FROM task_late_replies lr WHERE lr.inbox_id=inbox.id) THEN 1 ELSE 0 END AS late
+        FROM inbox WHERE created_at >= ?1`;
       if (alias) {
         params.push(alias);
         sql += ` AND session_name = ?${params.length}`;
@@ -3977,7 +3980,10 @@ return Bun.serve({
       sql = addOwnTrafficScope(sql, params, restScope, { from: "from_session", to: "session_name" });
       sql += ` ORDER BY created_at DESC LIMIT ?${params.length + 1}`;
       params.push(limit);
-      const rows = db.all(sql, ...params);
+      const rows = db.all<any>(sql, ...params).map((row) => {
+        const { late, ...rest } = row;
+        return { ...rest, ...(late === 1 || late === true ? { late: true } : {}) };
+      });
 
       let pendingCount: number | undefined;
       if (alias) {
@@ -4819,6 +4825,7 @@ return Bun.serve({
         liveSseConnections,
         targetEverReportedRuntimeEvidence,
       });
+      task.late_replies = listTaskLateReplies(db, taskId, taskNetworkId);
       return withCors(req, Response.json({ ok: true, task, diagnostic }));
     }
 
@@ -4865,7 +4872,15 @@ return Bun.serve({
       sql += ` ORDER BY created_at DESC, task_id DESC LIMIT ?${params.length + 1}`;
       params.push(limit);
 
-      const rows = db.all(sql, ...params);
+      const rows = db.all<any>(sql, ...params);
+      // Existing desktop clients implement their one-task detail read as
+      // `/api/tasks?task_id=…&limit=1`. Keep broad list responses lean, but
+      // enrich that exact-detail shape as well as `/api/tasks/:id`.
+      if (taskId) {
+        for (const row of rows) {
+          row.late_replies = listTaskLateReplies(db, String(row.task_id), typeof row.network_id === "string" ? row.network_id : null);
+        }
+      }
       if (skipStats) {
         return withCors(req, Response.json({ ok: true, tasks: rows, count: rows.length }));
       }

package/src/shared/reserved-env-drift.test.ts

@@ -17,27 +17,37 @@ import {
 
 const HUB_PATH = join(import.meta.dir, "reserved-env.ts");
 const DAEMON_PATH = join(import.meta.dir, "..", "..", "..", "agent-node", "src", "shared", "reserved-env.ts");
+const CLI_PATH = join(import.meta.dir, "..", "..", "..", "agent-network", "src", "shared", "reserved-env.ts");
 
 describe("RFC-026 v4 §4.4.7 G9 — hub/daemon reserved-env drift guard", () => {
   test("byte-identical source files", () => {
     const hub = readFileSync(HUB_PATH, "utf-8");
     const daemon = readFileSync(DAEMON_PATH, "utf-8");
+    const cli = readFileSync(CLI_PATH, "utf-8");
     expect(daemon).toBe(hub);
+    expect(cli).toBe(hub);
   });
 
   test("imported constants are set-equal at runtime", async () => {
     // Use a dynamic file import path so this test breaks if the file
     // moves but still references the daemon copy.
     const daemonMod = await import(DAEMON_PATH);
+    const cliMod = await import(CLI_PATH);
     const daemonExact = daemonMod.RESERVED_ENV_KEYS_EXACT as Set<string>;
     const daemonPrefixes = daemonMod.RESERVED_ENV_PREFIXES as ReadonlyArray<string>;
+    const cliExact = cliMod.RESERVED_ENV_KEYS_EXACT as Set<string>;
+    const cliPrefixes = cliMod.RESERVED_ENV_PREFIXES as ReadonlyArray<string>;
 
     // EXACT set equality
     expect(daemonExact.size).toBe(HUB_EXACT.size);
     for (const k of HUB_EXACT) expect(daemonExact.has(k)).toBe(true);
     for (const k of daemonExact) expect(HUB_EXACT.has(k)).toBe(true);
+    expect(cliExact.size).toBe(HUB_EXACT.size);
+    for (const k of HUB_EXACT) expect(cliExact.has(k)).toBe(true);
+    for (const k of cliExact) expect(HUB_EXACT.has(k)).toBe(true);
 
     // PREFIX array order-independent equality
     expect(new Set(daemonPrefixes)).toEqual(new Set(HUB_PREFIXES));
+    expect(new Set(cliPrefixes)).toEqual(new Set(HUB_PREFIXES));
   });
 });