@sleep2agi/commhub-server 0.9.0-preview.27 → 0.9.0-preview.29

package/src/server.ts

@@ -2,10 +2,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod/v4";
 import { registerTools } from "./tools.js";
-import { db, logTaskEvent, logAudit } from "./db.js";
+import { db, logTaskEvent, logAudit, syncScheduledRunForTask } from "./db.js";
 import { createSSEStream, createNetworkObserverStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
-import { addNetworkScope, canRestWriteNetwork, getUserNetworkIds, resolveRestNetworkScope, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
+import { addNetworkScope, canRestWriteNetwork, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { validateAvatarUrl } from "./avatar-validate.js";
 import { narrowTags, parseStoredTags, validateScalarAttr } from "./node-attrs-validate.js";
 import { register, login, resolveToken, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getUserNetworkRole, addNetworkMember, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
@@ -29,10 +29,24 @@ import {
   validateAttachments,
   validateIndexEntry,
 } from "./uploads.js";
-import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync } from "fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync, unlinkSync, renameSync } from "fs";
 import { dirname as pathDirname } from "path";
 import { startRetentionSweeper } from "./retention.js";
 import { startStaleSessionSweeper } from "./stale-sweeper.js";
+import {
+  AUDIT_LOG_REST_SELECT,
+  COMPLETION_REST_SELECT,
+  NETWORK_REST_SELECT,
+  SESSION_REST_SELECT,
+  TASK_EVENT_REST_SELECT,
+  TASK_REST_SELECT,
+} from "./rest-projections.js";
+import { resolveRestFromSession } from "./rest-identity.js";
+import { stampTaskAuthOrigin, type TaskAuthOrigin } from "./task-auth-origin.js";
+import { diagnoseTask } from "./task-diagnostic.js";
+import { assertScheduledTaskBackendSupported, handleScheduledTaskRequest, startScheduledTaskScheduler } from "./scheduled-tasks.js";
+import { handleExternalScheduleEditRequest } from "./external-schedule-edits.js";
+import { recordDeliveredStaleEvents } from "./task-lifecycle-watcher.js";
 
 const PORT = Number(process.env.PORT) || 9200;
 const HOST = process.env.HOST || "127.0.0.1";
@@ -124,19 +138,22 @@ function createServer(clientIP?: string, enforceNetworkId?: string | null, enfor
 }
 
 // ── Auth helper ─────────────────────────────────────
-function requestToken(req: Request): string {
+type RequestTokenOptions = { allowQueryToken?: boolean };
+
+function requestToken(req: Request, options: RequestTokenOptions = {}): string {
   const header = req.headers.get("Authorization")?.replace("Bearer ", "");
+  if (options.allowQueryToken === false) return header || "";
   const url = new URL(req.url);
   return header || url.searchParams.get("token") || "";
 }
 
-function isLegacyAuthToken(req: Request): boolean {
-  const token = requestToken(req);
+function isLegacyAuthToken(req: Request, options: RequestTokenOptions = {}): boolean {
+  const token = requestToken(req, options);
   return !!AUTH_TOKEN && token === AUTH_TOKEN;
 }
 
-function requireAuth(req: Request): Response | null {
-  const token = requestToken(req);
+function requireAuth(req: Request, options: RequestTokenOptions = {}): Response | null {
+  const token = requestToken(req, options);
 
   // V3: check api_tokens first
   if (token) {
@@ -209,8 +226,8 @@ function requireTmuxAccess(req: Request, server?: any): Response | null {
 }
 
 // Extract user + network + token-binding identity from request token.
-function resolveRequestAuth(req: Request): { userId: string; networkId: string | null; username: string; tokenName: string | null; tokenId: string | null } | null {
-  const token = requestToken(req);
+function resolveRequestAuth(req: Request, options: RequestTokenOptions = {}): { userId: string; networkId: string | null; username: string; tokenName: string | null; tokenId: string | null } | null {
+  const token = requestToken(req, options);
   if (!token) return null;
   const resolved = resolveToken(token);
   if (!resolved) return null;
@@ -229,14 +246,14 @@ export type Principal =
   | { kind: "ntok"; userId: string; boundNetworkId: string }
   | { kind: "admin-utok"; userId: string; username: string };
 
-export function resolvePrincipal(req: Request): Principal {
-  const authCtx = resolveRequestAuth(req);
+export function resolvePrincipal(req: Request, options: RequestTokenOptions = {}): Principal {
+  const authCtx = resolveRequestAuth(req, options);
   if (!authCtx) {
-    if (isLegacyAuthToken(req)) return { kind: "legacy-master" };
+    if (isLegacyAuthToken(req, options)) return { kind: "legacy-master" };
     if (DEV_OPEN) return { kind: "dev-open-anon" };
     return { kind: "anonymous" };
   }
-  const token = requestToken(req);
+  const token = requestToken(req, options);
   const resolved = token ? resolveToken(token) : null;
   const isAdmin = !!resolved && resolved.user.role === "admin";
   // Bound network wins over admin classification: a ntok_ issued BY an
@@ -366,6 +383,26 @@ function parseSqliteTime(value: string | null | undefined): number {
   return Number.isFinite(ts) ? ts : 0;
 }
 
+function normalizeTaskBeforeCursor(value: string): string | null {
+  const cursor = value.trim();
+  if (!cursor) return null;
+  const sqliteShape = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+  if (sqliteShape.test(cursor)) {
+    const parsed = new Date(`${cursor.replace(" ", "T")}Z`);
+    if (!Number.isFinite(parsed.getTime()) || sqliteTime(parsed) !== cursor) return null;
+    return cursor;
+  }
+  const timestamp = Date.parse(cursor);
+  if (!Number.isFinite(timestamp)) return null;
+  return sqliteTime(new Date(timestamp));
+}
+
+function normalizeTaskBeforeTaskId(value: string): string | null {
+  const taskId = value.trim();
+  if (!taskId || taskId.length > 256 || /[\u0000-\u001f\u007f]/.test(taskId)) return null;
+  return taskId;
+}
+
 function cpuPct(load: number | null | undefined, cores: number | null | undefined): number | null {
   if (typeof load !== "number" || typeof cores !== "number" || cores <= 0) return null;
   return Math.round((load / cores) * 1000) / 10;
@@ -491,6 +528,17 @@ function resolveRestNodeIdForAlias(alias: string, networkId: string | null): str
   return target.state === "not_found" ? null : (target.session?.node_id ?? null);
 }
 
+function withNetworkNameAlias<T extends { network_name?: unknown }>(row: T): T & { name: string | null } {
+  return {
+    ...row,
+    // `network_name` is the canonical V3 storage/API field and remains for
+    // existing CLI/Dashboard clients. `name` is the documented REST-friendly
+    // compatibility alias; never let it drift or serialize as null when the
+    // canonical NOT NULL field is present.
+    name: typeof row.network_name === "string" ? row.network_name : null,
+  };
+}
+
 // ── REST input schema ───────────────────────────────
 const TaskSchema = z.object({
   alias: z.string().min(1).max(200),
@@ -585,23 +633,45 @@ const wsTmuxIntervals = new Map<object, ReturnType<typeof setInterval>>();
 // Registered in startHub() (#476): this WRITES the DB, so it must never
 // run as an import side effect — a tool/test importing this module with
 // COMMHUB_DB unset would patrol the production database.
-function patrolExpiredTasks(): void {
+export function patrolExpiredTasks(): void {
   try {
-    const result = db.run(
-      `UPDATE tasks SET status = 'expired', completed_at = datetime('now')
-       WHERE expires_at IS NOT NULL AND expires_at < datetime('now')
-         AND status IN ('created', 'delivered')`
-    );
-    if (result.changes > 0) {
-      console.log(`[patrol] expired ${result.changes} stale task(s)`);
-      // Log events for expired tasks
-      const expired = db.all<{ task_id: string }>(
-        "SELECT task_id FROM tasks WHERE status = 'expired' AND completed_at >= datetime('now', '-1 minute')");
-      for (const t of expired) logTaskEvent(t.task_id, null, "expired", "patrol");
+    const expired = db.transaction(() => {
+      const due = db.all<{ task_id: string; network_id: string | null }>(
+        `SELECT task_id, network_id FROM tasks
+          WHERE expires_at IS NOT NULL AND expires_at < datetime('now')
+            AND status IN ('created', 'delivered')`,
+      );
+      const changed: Array<{ task_id: string; network_id: string | null }> = [];
+      for (const task of due) {
+        const result = db.run(
+          `UPDATE tasks SET status = 'expired', completed_at = datetime('now')
+            WHERE task_id = ?1 AND status IN ('created', 'delivered')`,
+          [task.task_id],
+        );
+        if (result.changes !== 1) continue;
+        syncScheduledRunForTask(task.task_id, task.network_id);
+        changed.push(task);
+      }
+      return changed;
+    });
+    if (expired.length > 0) {
+      console.log(`[patrol] expired ${expired.length} stale task(s)`);
+      for (const task of expired) logTaskEvent(task.task_id, null, "expired", "patrol");
     }
   } catch {}
 }
 
+function patrolDeliveredStaleTasks(): void {
+  try {
+    const result = recordDeliveredStaleEvents();
+    if (result.inserted > 0) {
+      console.warn(`[patrol] recorded ${result.inserted} delivered-stale task warning(s)`);
+    }
+  } catch (error: any) {
+    console.error(`[patrol] delivered-stale watcher failed: ${error?.message || error}`);
+  }
+}
+
 // #434 — test-safety seam, same signature as PR #438 so the two branches
 // merge cleanly. Wraps the sole Bun.serve config in a factory so
 // integration tests can request an OS-assigned ephemeral port
@@ -814,7 +884,9 @@ return Bun.serve({
 
     // ── V3: License endpoints ──
     if (url.pathname === "/api/license" && req.method === "GET") {
-      const license = db.get<any>("SELECT * FROM licenses ORDER BY created_at LIMIT 1");
+      const license = db.get<any>(
+        "SELECT type, expires_at, max_agents, max_networks, max_tasks_day FROM licenses ORDER BY created_at LIMIT 1",
+      );
       if (!license) return withCors(req, Response.json({ ok: true, status: "no_license" }));
       const now = new Date().toISOString().replace("T", " ").slice(0, 19);
       const expired = license.expires_at && license.expires_at < now;
@@ -966,7 +1038,7 @@ return Bun.serve({
       try {
         const body = await req.json() as any;
         if (!body.network_id || !body.node_name) return withCors(req, Response.json({ ok: false, error: "network_id and node_name required" }, { status: 400 }));
-        const result = createNetworkTokenForNode(resolved.user.user_id, body.network_id, body.node_name);
+        const result = createNetworkTokenForNode(resolved.user.user_id, body.network_id, body.node_name, body.node_id);
         if (result.ok) logAudit(resolved.user.user_id, resolved.user.username, "node_token_created", "network", body.network_id, body.node_name);
         return withCors(req, Response.json(result, { status: result.ok ? 200 : 400 }));
       } catch (e: any) {
@@ -1072,11 +1144,26 @@ return Bun.serve({
       // V3.13: ntok_ can only see its bound network; utok_ sees all member networks
       if (resolved.networkId) {
         // ntok_ — only return the bound network
-        const net = db.get<any>("SELECT * FROM networks WHERE network_id = ?1", resolved.networkId);
-        return withCors(req, Response.json({ ok: true, networks: net ? [net] : [] }));
-      }
-      const networks = getUserAllNetworks(resolved.user.user_id);
-      return withCors(req, Response.json({ ok: true, networks }));
+        const net = db.get<any>(`SELECT ${NETWORK_REST_SELECT} FROM networks WHERE network_id = ?1`, resolved.networkId);
+        return withCors(req, Response.json({ ok: true, networks: net ? [withNetworkNameAlias(net)] : [] }));
+      }
+      // Global Hub admins have cross-network authority throughout the REST
+      // surface, so limiting this discovery endpoint to their membership rows
+      // made otherwise-authorized networks impossible to select (#94). Keep
+      // ordinary utok_ callers membership-scoped; ntok_ returned above stays
+      // bound to exactly one network.
+      const networks = resolved.user.role === "admin"
+        ? db.all<any>(
+            `SELECT ${NETWORK_REST_SELECT},
+                    COALESCE((SELECT nm.role FROM network_members nm
+                              WHERE nm.network_id = networks.network_id
+                                AND nm.user_id = ?1), 'admin') AS member_role
+             FROM networks ORDER BY created_at`,
+            resolved.user.user_id,
+          )
+        : getUserAllNetworks(resolved.user.user_id);
+      const visibleNetworks = networks.map(withNetworkNameAlias);
+      return withCors(req, Response.json({ ok: true, networks: visibleNetworks }));
     }
 
     if (url.pathname === "/api/networks" && req.method === "POST") {
@@ -1178,7 +1265,7 @@ return Bun.serve({
       const resolved = resolveToken(token);
       if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
       const networkId = netDetailMatch[1];
-      const network = db.get<any>("SELECT * FROM networks WHERE network_id = ?1", networkId);
+      const network = db.get<any>(`SELECT ${NETWORK_REST_SELECT} FROM networks WHERE network_id = ?1`, networkId);
       if (!network) return withCors(req, Response.json({ ok: false, error: "network not found" }, { status: 404 }));
       // Membership check: must be a member or system admin
       const viewerRole = getUserNetworkRole(resolved.user.user_id, networkId);
@@ -1329,6 +1416,14 @@ return Bun.serve({
         multi_network: true,
         license: license?.type || "none",
         uptime: Math.floor(process.uptime()),
+        // #496 — public, stable capability data. Dashboard upload proxies
+        // need the Hub's real limits before opening a streaming request;
+        // duplicating these constants client-side creates a silent
+        // lower-limit drift that the Hub can never observe.
+        limits: {
+          max_upload_bytes: MAX_UPLOAD_BYTES,
+          max_request_content_length: MAX_REQUEST_CONTENT_LENGTH,
+        },
       };
       if (scopedSessions !== undefined) body.sse_sessions = scopedSessions;
       return withCors(req, Response.json(body));
@@ -1347,6 +1442,33 @@ return Bun.serve({
       return withCors(req, Response.json({ ok: false, error: restScope.denied }, { status: 403 }));
     }
 
+    // RFC-036 owner-gated host schedule edits. This handler independently
+    // verifies exact node ownership and node-token binding; network admin is
+    // deliberately not an override.
+    const requestCredential = requestToken(req);
+    const externalScheduleEditResponse = await handleExternalScheduleEditRequest({
+      req,
+      url,
+      auth: restAuth,
+      isUserToken: requestCredential.startsWith("utok_"),
+      isNodeToken: requestCredential.startsWith("ntok_"),
+    });
+    if (externalScheduleEditResponse) return withCors(req, externalScheduleEditResponse);
+
+    // Hub-owned scheduled tasks. Dashboard and mobile are management
+    // clients only; each occurrence is dispatched as an ordinary task by the
+    // scheduler started in startHub(). Node tokens are rejected in the
+    // handler so an agent cannot grant itself a persistent execution loop.
+    const scheduledResponse = await handleScheduledTaskRequest({
+      req,
+      url,
+      auth: restAuth,
+      isAdmin,
+      isNodeToken: requestToken(req).startsWith("ntok_"),
+      scope: restScope,
+    });
+    if (scheduledResponse) return withCors(req, scheduledResponse);
+
     // ── #473 REST: SSE connection detail (ops-only) ──
     // The per-key breakdown /health used to expose anonymously: keys are
     // `{networkId}:{alias}` (+ `\0netobs:{networkId}` observer keys via
@@ -1385,10 +1507,10 @@ return Bun.serve({
       const params: any[] = [];
       let sql = isLight
         ? "SELECT alias, status, agent, task, server, updated_at, network_id FROM sessions WHERE 1=1"
-        : "SELECT * FROM sessions WHERE 1=1";
+        : `SELECT ${SESSION_REST_SELECT} FROM sessions WHERE 1=1`;
       sql = addNetworkScope(sql, params, restScope);
       sql += " ORDER BY updated_at DESC";
-      // `model` comes straight from the sessions row (SELECT *); `runtime` is
+      // `model` comes straight from the explicit sessions projection; `runtime` is
       // derived from the raw `agent` field. Both default to null for old nodes
       // that never reported a model — the dashboard falls back to a placeholder.
       const sessions = db.all(sql, ...params).map((s: any) => {
@@ -1404,8 +1526,14 @@ return Bun.serve({
             network_id: s.network_id ?? null,
           };
         }
+        const externalSchedules = (() => {
+          if (typeof s.external_schedules !== "string") return null;
+          try { return JSON.parse(s.external_schedules); } catch { return null; }
+        })();
+        const { external_schedules: _externalSchedulesJson, ...publicSession } = s;
         return {
-          ...s,
+          ...publicSession,
+          external_schedules: externalSchedules,
           model: s.model ?? null,
           runtime: normalizeRuntime(s.agent),
           host: {
@@ -1522,7 +1650,7 @@ return Bun.serve({
       if (detailKind === "agents") {
         const params: any[] = [host, host];
         let sql = `
-          SELECT alias, agent, status, task, progress, model, hostname, ip,
+          SELECT alias, agent, status, task, progress, model, hostname, ip, external_schedules,
                  cpu_load_1min, cpu_cores, mem_avail_gb, mem_used_gb, mem_total_gb,
                  disk_avail_gb, disk_used_gb, disk_total_gb,
                  process_rss_bytes, process_rss_mb, process_cpu_pct, process_uptime_seconds, process_in_flight_count,
@@ -1540,6 +1668,10 @@ return Bun.serve({
           status: s.status ?? "offline",
           task: s.task ?? null,
           progress: s.progress ?? 0,
+          external_schedules: (() => {
+            if (typeof s.external_schedules !== "string") return null;
+            try { return JSON.parse(s.external_schedules); } catch { return null; }
+          })(),
           last_seen: s.last_seen ?? null,
           health: agentHealthChip(s.status, s.last_seen),
           hostname: s.hostname ?? null,
@@ -1786,7 +1918,7 @@ return Bun.serve({
       }
 
       if (uploadNetId !== null) {
-        const networkRow = db.get<any>("SELECT * FROM networks WHERE network_id = ?1", uploadNetId);
+        const networkRow = db.get<any>("SELECT network_id FROM networks WHERE network_id = ?1", uploadNetId);
         if (!networkRow) {
           if (principal.kind === "admin-utok" || principal.kind === "legacy-master") {
             return earlyReject(Response.json({
@@ -1853,14 +1985,14 @@ return Bun.serve({
       try {
         mkdirSync(pathDirname(storage.absolutePath), { recursive: true });
         const buf = Buffer.from(await file.arrayBuffer());
-        writeFileSync(storage.absolutePath, buf);
+        // #693 — write blob to .tmp then rename for crash-safe durability.
+        const tmpPath = storage.absolutePath + ".tmp";
+        writeFileSync(tmpPath, buf);
         // Defense-in-depth: after writing, confirm the path still sits
         // inside the uploads root (catches a symlink swap or root env
         // poisoning across processes).
-        if (!isPathInsideUploadsRoot(storage.absolutePath)) {
-          // Refuse to acknowledge a write that landed outside the root.
-          // Don't try to clean up — better to keep evidence on disk than
-          // chase a symlink for cleanup.
+        if (!isPathInsideUploadsRoot(tmpPath) || !isPathInsideUploadsRoot(storage.absolutePath)) {
+          try { unlinkSync(tmpPath); } catch { /* best-effort */ }
           console.error("[/api/upload] write escaped uploads root:", storage.absolutePath);
           return withCors(req, Response.json({ ok: false, error: "internal_path_escape" }, { status: 500 }));
         }
@@ -1883,6 +2015,18 @@ return Bun.serve({
             ...(uploadNetId ? { network_id: uploadNetId } : {}),
             uploaded_at: new Date().toISOString(),
           }, null, 2));
+        } else {
+          // No index path → refuse to leave an unindexed blob.
+          try { unlinkSync(tmpPath); } catch { /* best-effort */ }
+          return withCors(req, Response.json({ ok: false, error: "index_path_error" }, { status: 500 }));
+        }
+        // Index first, then publish blob via rename — if rename fails, drop index.
+        try {
+          renameSync(tmpPath, storage.absolutePath);
+        } catch (renameErr: any) {
+          try { unlinkSync(tmpPath); } catch { /* best-effort */ }
+          try { if (idxPath) unlinkSync(idxPath); } catch { /* best-effort */ }
+          throw renameErr;
         }
       } catch (e: any) {
         console.error("[/api/upload] write failed:", e?.message);
@@ -1920,7 +2064,11 @@ return Bun.serve({
     // allow-list inline, or the branches will drift.
     const fileMatch = url.pathname.match(/^\/api\/files\/(.+)$/);
     if (fileMatch && (req.method === "GET" || req.method === "HEAD")) {
-      const authErr = requireAuth(req);
+      // #501: file credentials must never travel in the URL. Query tokens
+      // leak through browser history, access/proxy logs, copied links, and
+      // Referer. SSE/EventSource compatibility keeps the global query-token
+      // fallback for now; file GET/HEAD deliberately opt out here.
+      const authErr = requireAuth(req, { allowQueryToken: false });
       if (authErr) return withCors(req, authErr);
 
       const fileId = decodeURIComponent(fileMatch[1]);
@@ -1951,7 +2099,7 @@ return Bun.serve({
       // "no such file". Both branches return the same 404 shape
       // for BOTH GET and HEAD (HEAD honours body-omission but the
       // status code and headers are the authoritative signal).
-      if (!authorizeFileDownload(resolvePrincipal(req), normalizeEntry(entry))) {
+      if (!authorizeFileDownload(resolvePrincipal(req, { allowQueryToken: false }), normalizeEntry(entry))) {
         return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
       }
 
@@ -2066,10 +2214,16 @@ return Bun.serve({
         }
         taskNetId = body.network_id;
       } else {
-        taskNetId = restAuth ? singleNetworkId(restScope) : null;
+        taskNetId = restAuth
+          ? resolveRestWriteNetworkId(restScope, restAuth, isAdmin)
+          : null;
       }
       if (restAuth && !taskNetId) {
-        return withCors(req, Response.json({ ok: false, error: "network_id required for user token when multiple networks are available" }, { status: 400 }));
+        return withCors(req, Response.json({
+          ok: false,
+          error: "network_id_required",
+          message: "network_id is required when the user token has zero or multiple network memberships",
+        }, { status: 400 }));
       }
       if (!canRestWriteNetwork(restAuth, taskNetId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
@@ -2088,7 +2242,38 @@ return Bun.serve({
         }, { status: 404 }));
       }
       const id = crypto.randomUUID();
-      const fromSession = body.from || "api";
+      // Identity binding, mirroring the MCP transport (tools.ts defaultFrom /
+      // fromIdentityMismatchReply). Both transports resolve the same
+      // api_tokens row through resolveToken, and auth.ts already documents the
+      // invariant: "Network-bound node tokens are an identity boundary: they
+      // must not spoof another node via from_session."
+      //
+      // MCP enforced it; this REST handler did not — it took `body.from`
+      // verbatim, so any node could POST /api/task with another node's alias
+      // and be recorded (and, once sender labels ship, *rendered in a human's
+      // TUI*) as that node. Same table, same token, one transport hardened and
+      // its sibling not.
+      //
+      // User tokens keep the previous behaviour: the Dashboard legitimately
+      // posts as its logged-in user, and tightening that is a separate change
+      // with its own compatibility surface.
+      // The decision itself lives in rest-identity.ts as a pure function so the
+      // shipped path and the tested path are the same code.
+      const identity = resolveRestFromSession({
+        token: requestToken(req),
+        tokenName: restAuth?.tokenName,
+        requestedFrom: body.from,
+      });
+      if (!identity.ok) {
+        return withCors(req, Response.json({
+          ok: false,
+          error: identity.error,
+          message: identity.message,
+          token_alias: identity.tokenAlias,
+          requested_from_session: identity.requestedFromSession,
+        }, { status: 403 }));
+      }
+      const fromSession = identity.fromSession;
       const ttlSeconds = (body as any).ttl_seconds || 3600;
       const fromNodeId = resolveRestNodeIdForAlias(fromSession, taskNetId);
       const targetNodeId = target.session?.node_id ?? null;
@@ -2105,7 +2290,13 @@ return Bun.serve({
       const mergedMeta = attachmentsResult.attachments.length
         ? { ...((body as any).meta && typeof (body as any).meta === "object" ? (body as any).meta : {}), attachments: attachmentsResult.attachments }
         : (body as any).meta;
-      const metaJson = normalizeMetaJson(mergedMeta);
+      const rawToken = requestToken(req);
+      const authOrigin: TaskAuthOrigin = rawToken.startsWith("ntok_")
+        ? "node"
+        : restAuth
+          ? "user"
+          : "legacy";
+      const metaJson = normalizeMetaJson(stampTaskAuthOrigin(mergedMeta, authOrigin));
 
       // #212 dedup guardrail. Mirrors the MCP `send_task` tool: same
       // (from_session, target_alias, task) within COMMHUB_SEND_DEDUP_WINDOW_MS
@@ -2143,8 +2334,8 @@ return Bun.serve({
       // dispatched via REST (anet demo, dashboard Dispatch button, etc.).
       db.transaction(() => {
         db.run(
-          `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, requires_response, network_id, meta_json)
-           VALUES (?1, ?2, ?3, 'task', ?4, ?5, ?6, 'reply', ?7, ?8)`,
+          `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, ?6, 'reply', ?7, ?8)`,
           [id, targetAlias, targetNodeId, body.priority, body.task, fromSession, taskNetId, metaJson]
         );
         db.run(
@@ -2369,7 +2560,7 @@ return Bun.serve({
       const limit = Math.min(Number(url.searchParams.get("limit")) || 50, 200);
       const action = url.searchParams.get("action");
       const userId = url.searchParams.get("user_id");
-      let sql = "SELECT * FROM audit_log WHERE 1=1";
+      let sql = `SELECT ${AUDIT_LOG_REST_SELECT} FROM audit_log WHERE 1=1`;
       const params: any[] = [];
       // Non-admin can only see own logs
       if (resolved.user.role !== "admin") { sql += ` AND user_id = ?${params.length + 1}`; params.push(resolved.user.user_id); }
@@ -2385,7 +2576,7 @@ return Bun.serve({
     if (url.pathname === "/api/task_events") {
       const taskId = url.searchParams.get("task_id");
       const limit = Math.min(Number(url.searchParams.get("limit")) || 50, 500);
-      let sql = "SELECT * FROM task_events WHERE 1=1";
+      let sql = `SELECT ${TASK_EVENT_REST_SELECT} FROM task_events WHERE 1=1`;
       const params: any[] = [];
       sql = addNetworkScope(sql, params, restScope);
       if (taskId) { sql += ` AND task_id = ?${params.length + 1}`; params.push(taskId); }
@@ -2400,7 +2591,7 @@ return Bun.serve({
     if (nodeDeleteMatch && req.method === "DELETE") {
       const ref = decodeURIComponent(nodeDeleteMatch[1]);
       const params: any[] = [ref, ref, ref];
-      let sql = "SELECT * FROM nodes WHERE (node_id = ?1 OR node_name = ?2 OR alias = ?3)";
+      let sql = "SELECT node_id, node_name, alias, network_id FROM nodes WHERE (node_id = ?1 OR node_name = ?2 OR alias = ?3)";
       sql = addNetworkScope(sql, params, restScope);
       sql += " ORDER BY updated_at DESC LIMIT 1";
       const node = db.get<any>(sql, ...params);
@@ -2823,14 +3014,45 @@ return Bun.serve({
     if (taskPathMatch && req.method === "GET") {
       const taskId = decodeURIComponent(taskPathMatch[1] ?? "");
       const params: any[] = [taskId];
-      let sql = "SELECT * FROM tasks WHERE task_id = ?1";
+      let sql = `SELECT ${TASK_REST_SELECT} FROM tasks WHERE task_id = ?1`;
       sql = addNetworkScope(sql, params, restScope);
       sql += " LIMIT 1";
       const task = db.get(sql, ...params);
       if (!task) {
         return withCors(req, Response.json({ ok: false, error: "task_not_found", task_id: taskId }, { status: 404 }));
       }
-      return withCors(req, Response.json({ ok: true, task }));
+      const taskNetworkId = typeof task.network_id === "string" ? task.network_id : null;
+      const canonicalTarget = task.to_node_id
+        ? null
+        : resolveCanonicalAlias(taskNetworkId, String(task.to_name ?? "")).alias;
+      const targetParams: unknown[] = [];
+      let targetSql = "SELECT alias, status FROM sessions WHERE ";
+      if (task.to_node_id) {
+        targetSql += "node_id = ?1";
+        targetParams.push(task.to_node_id);
+      } else {
+        targetSql += "alias = ?1";
+        targetParams.push(canonicalTarget);
+      }
+      if (taskNetworkId) {
+        targetSql += " AND network_id = ?2";
+        targetParams.push(taskNetworkId);
+      } else {
+        targetSql += " AND network_id IS NULL";
+      }
+      targetSql += " ORDER BY updated_at DESC LIMIT 1";
+      const targetSession = db.get<{ alias: string; status: string }>(targetSql, ...targetParams);
+      const targetAlias = targetSession?.alias ?? canonicalTarget ?? String(task.to_name ?? "");
+      const liveSseConnections = getSSEStats().sessions[`${taskNetworkId || "global"}:${targetAlias}`] ?? 0;
+      const diagnostic = diagnoseTask({
+        status: String(task.status ?? "unknown"),
+        runtimeSubmittedAt: typeof task.runtime_submitted_at === "string" ? task.runtime_submitted_at : null,
+        consumedAt: typeof task.consumed_at === "string" ? task.consumed_at : null,
+        targetSessionStatus: targetSession?.status ?? null,
+        targetSessionExists: Boolean(targetSession),
+        liveSseConnections,
+      });
+      return withCors(req, Response.json({ ok: true, task, diagnostic }));
     }
 
     // ── REST: tasks table (V2) ──
@@ -2839,6 +3061,16 @@ return Bun.serve({
       const status = url.searchParams.get("status");
       const toName = url.searchParams.get("to_name");
       const fromName = url.searchParams.get("from_name");
+      const rawBefore = url.searchParams.get("before");
+      const before = rawBefore === null ? null : normalizeTaskBeforeCursor(rawBefore);
+      if (rawBefore !== null && before === null) {
+        return withCors(req, Response.json({ ok: false, error: "invalid_before" }, { status: 400 }));
+      }
+      const rawBeforeTaskId = url.searchParams.get("before_task_id");
+      const beforeTaskId = rawBeforeTaskId === null ? null : normalizeTaskBeforeTaskId(rawBeforeTaskId);
+      if (rawBeforeTaskId !== null && (before === null || beforeTaskId === null)) {
+        return withCors(req, Response.json({ ok: false, error: "invalid_before_task_id" }, { status: 400 }));
+      }
       const limit = Math.min(Number(url.searchParams.get("limit")) || 50, 200);
       // #248 — opt-out of the stats GROUP-BY scan. The dashboard chat panel
       // never consumes `stats`; it's a global per-status table scan that
@@ -2847,14 +3079,23 @@ return Bun.serve({
       // {ok, tasks, count, stats} shape — backwards-compatible.
       const skipStats = url.searchParams.get("skip_stats") === "1";
 
-      let sql = "SELECT * FROM tasks WHERE 1=1";
+      let sql = `SELECT ${TASK_REST_SELECT} FROM tasks WHERE 1=1`;
       const params: any[] = [];
       sql = addNetworkScope(sql, params, restScope);
       if (taskId) { sql += ` AND task_id = ?${params.length + 1}`; params.push(taskId); }
       if (status) { sql += ` AND status = ?${params.length + 1}`; params.push(status); }
       if (toName) { sql += ` AND to_name = ?${params.length + 1}`; params.push(toName); }
       if (fromName) { sql += ` AND from_name = ?${params.length + 1}`; params.push(fromName); }
-      sql += ` ORDER BY created_at DESC LIMIT ?${params.length + 1}`;
+      if (before && beforeTaskId) {
+        const createdAtParam = params.length + 1;
+        const taskIdParam = params.length + 2;
+        sql += ` AND (created_at < ?${createdAtParam} OR (created_at = ?${createdAtParam} AND task_id < ?${taskIdParam}))`;
+        params.push(before, beforeTaskId);
+      } else if (before) {
+        sql += ` AND created_at < ?${params.length + 1}`;
+        params.push(before);
+      }
+      sql += ` ORDER BY created_at DESC, task_id DESC LIMIT ?${params.length + 1}`;
       params.push(limit);
 
       const rows = db.all(sql, ...params);
@@ -2873,7 +3114,7 @@ return Bun.serve({
     if (url.pathname === "/api/completions") {
       const since = url.searchParams.get("since") ?? new Date(Date.now() - 86400000).toISOString();
       const params: any[] = [since];
-      let sql = "SELECT * FROM completions WHERE completed_at >= ?1";
+      let sql = `SELECT ${COMPLETION_REST_SELECT} FROM completions WHERE completed_at >= ?1`;
       sql = addNetworkScope(sql, params, restScope);
       sql += " ORDER BY completed_at DESC LIMIT 100";
       const rows = db.all(sql, ...params);
@@ -3023,6 +3264,11 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
       `For an additional throwaway instance use bootServer({ port: 0 }).`
     );
   }
+  // The current PostgreSQL adapter opens a fresh process/connection for each
+  // statement, so its transaction() cannot provide the occurrence claim +
+  // task creation atomicity this scheduler requires. Refuse before opening a
+  // listening socket instead of silently running an unsafe scheduler.
+  assertScheduledTaskBackendSupported();
   const server = bootServer(opts);
 
   // Round-2/4 review ② — periodic retention sweep + incremental VACUUM.
@@ -3054,8 +3300,13 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
     ? Number(process.env.COMMHUB_RATELIMIT_SWEEP_MS) : 300000;
   const taskPatrolMs = Number(process.env.COMMHUB_TASK_PATROL_MS) > 0
     ? Number(process.env.COMMHUB_TASK_PATROL_MS) : 5 * 60 * 1000;
+  const deliveredStalePatrolMs = Number(process.env.COMMHUB_DELIVERED_STALE_PATROL_MS) > 0
+    ? Number(process.env.COMMHUB_DELIVERED_STALE_PATROL_MS) : 5 * 1000;
   const rateLimitSweepTimer = setInterval(sweepStaleRateLimits, rateLimitSweepMs);
   const taskPatrolTimer = setInterval(patrolExpiredTasks, taskPatrolMs);
+  patrolDeliveredStaleTasks();
+  const deliveredStalePatrolTimer = setInterval(patrolDeliveredStaleTasks, deliveredStalePatrolMs);
+  const scheduledTaskTimer = startScheduledTaskScheduler();
 
   // The Bun.serve socket is what keeps the process alive; the periodic
   // jobs must not — otherwise a test (or a future caller) that stops the
@@ -3064,6 +3315,8 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
   (staleSweeperTimer as any)?.unref?.();
   (rateLimitSweepTimer as any)?.unref?.();
   (taskPatrolTimer as any)?.unref?.();
+  (deliveredStalePatrolTimer as any)?.unref?.();
+  (scheduledTaskTimer as any)?.unref?.();
 
   // ── Graceful shutdown ───────────────────────────────
   function shutdown() {
@@ -3072,6 +3325,8 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
     clearInterval(staleSweeperTimer);
     clearInterval(rateLimitSweepTimer);
     clearInterval(taskPatrolTimer);
+    clearInterval(deliveredStalePatrolTimer);
+    clearInterval(scheduledTaskTimer);
     db.close();
     process.exit(0);
   }