@humwick/server 0.0.0-stage → 0.130.1

package/src/db/messages.ts

@@ -0,0 +1,1201 @@
+import { reportVerbosityOf } from "../report-verbosity";
+import { randomUUID } from "node:crypto";
+import {
+  hasWorkFinality,
+  isRecord,
+  isTurnFinalSession,
+  stringValue,
+  USER_NAMESPACE_PREFIX,
+  isMechanicalMessageKind,
+  type MessagePayload,
+  type MessageWorkFinality,
+  type MessageWorkFinalitySource,
+} from "@humwick/sdk";
+import { LIFECYCLE_STATE_WORKING, childSignalKey, stampLifecycleSignal, taskSignalKey } from "../lifecycle-signal-registry";
+
+
+
+
+import { CLAIM_LEASE_MS, DEFAULT_FANOUT_TTL_SECONDS } from "../config";
+import { messageMatchesAgent } from "../agent-ref";
+import { isFanoutTarget } from "../channel-target";
+import { getAgent, validateAgentSession } from "./agents.ts";
+import { getUser } from "./users.ts";
+import { canonicalLineageReportTarget, currentCoordinatorOf, delegatedCoordinatorTarget, resolveTeamCoordinatorAgentId } from "./coordinator-seat.ts";
+import { getTeam, isClaimableTeam } from "./teams.ts";
+import { cleanAttachmentRefs, linkMessageArtifacts, validateAttachmentRefs } from "./artifacts.ts";
+import { ClaimError, ValidationError, getDb, writeTransaction } from "./connection.ts";
+import { CHANNEL_SUPPRESSION_REASON, isDisallowedChannelContent } from "./channel-egress-allowlist.ts";
+import { enforceQueueLimit, isChannelAgentId, isChannelEgressTarget, matchingDeliveryAgents } from "./delivery.ts";
+import { isAgentUnavailable } from "./agent-predicates.ts";
+import { MSG_SELECT, normalizeReactionEmoji, rowToMessage } from "./mappers.ts";
+import { admitUrgentMessage } from "./urgent-intake.ts";
+import { claimMessageRow } from "./message-claims.ts";
+import { firstMessageIdSince, getMessage } from "./message-queries.ts";
+import { deferLineageReport, takeDeferredLineageReports } from "./deferred-lineage-reports.ts";
+import { REPORT_SUPPRESSION_REASON, decideReportSuppression, isReportSuppressed, notReportSuppressedSql } from "./report-suppression.ts";
+import { childTaskIds, lineageDeliveryCoversCapture } from "./delivery-report-echo.ts";
+import { LINEAGE_REPORT_BY_TURN_SQL, RECENT_EXPLICIT_LINEAGE_DUPLICATE_SQL, RECENT_LINEAGE_REPORT_SQL, TURN_EXPLICIT_REPORT_SQL, sameTurnExplicitReportSql } from "./lineage-pair-dedupe-sql.ts";
+import { markRead } from "./message-read-mark.ts";
+import { closeReplyObligationsOnInsert } from "./reply-obligations.ts";
+import { settlesAsHistory } from "./history-delivery-settle.ts";
+import { stampWorkflowContact } from "./workflow-contact.ts";
+import { clearCoordinatorDigestRouting, enqueueCoordinatorDigest, prepareCoordinatorDigest } from "./coordinator-digest";
+import { childStreamSubscribed, type ChildStream } from "./notification-subscriptions.ts";
+import { runningAgentForPolicy } from "./policy-runtime.ts";
+import { getTask, releaseExpiredClaimsBody } from "./tasks.ts";
+import { insertTaskEvent, claimTaskWhere, CLAIM_TASK_KIND } from "./task-core.ts";
+import type {
+  AgentCard,
+  AgentSessionGuard,
+  Message,
+  SendMessageInput,
+  Task,
+} from "../types";
+
+export { claimMessageRow } from "./message-claims.ts";
+export { getMessage } from "./message-queries.ts";
+export { runningAgentForPolicy } from "./policy-runtime.ts";
+
+export function findMessageByIdempotencyKey(from: string, key: string): Message | null {
+  const row = getDb()
+    .query(`${MSG_SELECT} WHERE m.from_agent = ? AND m.idempotency_key = ? LIMIT 1`)
+    .get(from, key) as any;
+  return row ? rowToMessage(row) : null;
+}
+
+function sessionStepId(payload: Record<string, unknown> | undefined): string | undefined {
+  const session = isRecord(payload?.session) ? payload.session : undefined;
+  return stringValue(session?.stepId);
+}
+
+function normalizeMessagePayload(payload: MessagePayload | undefined): MessagePayload {
+  const original = payload ?? {};
+  let next: MessagePayload = original;
+  for (const key of ["session", "responseCapture"] as const) {
+    const value = next[key];
+    if (!isTurnFinalSession(value)) continue;
+    if (value.turnFinal === true && value.final === true) continue;
+    if (next === original) next = { ...original };
+    next[key] = { ...value, turnFinal: true, final: true };
+  }
+  return next;
+}
+
+/**
+ * Codex session-mirror upsert (#parity): a provider step that emits more than once — a
+ * tool's running→completed lifecycle, a reasoning/response row that streams — carries a
+ * stable `payload.session.stepId`. Instead of appending a second row (which renders as a
+ * duplicate on dashboard reload), update the EXISTING row in place: same DB id, so the
+ * dashboard's id-keyed merge replaces it. Gated on stepId presence + matching step, so the
+ * Claude transcript path (no stepId) is byte-identical. The row keeps the first event's
+ * occurredAt so long-running tools stay anchored at their start; completion time rides in
+ * payload.session.completedAt. Lifecycle rank still prevents a late running retry from
+ * clobbering an already-completed row.
+ */
+function upsertSessionStepInPlace(existing: Message, input: SendMessageInput, now: number): Message | null {
+  const incomingStep = sessionStepId(input.payload);
+  if (!incomingStep) return null;
+  if (existing.kind !== "session") return null;
+  if (sessionStepId(existing.payload) !== incomingStep) return null;
+  const incomingAt = sanitizeOccurredAt(input.occurredAt, now) ?? now;
+  if (sessionStepStatusRank(input.payload) < sessionStepStatusRank(existing.payload)) return null;
+  const payload = sessionPayloadWithCompletion(input.payload, incomingAt);
+  getDb().query("UPDATE messages SET body = ?, payload = ? WHERE id = ?").run(input.body, JSON.stringify(payload), existing.id);
+  return getMessage(existing.id);
+}
+
+// #2354 — `cancelled` (an interrupted-before-finished tool) ranks with `completed`/`failed` as a
+// TERMINAL outcome: a late `running` retry must never clobber it, and it carries a `completedAt`.
+function isTerminalSessionStepStatus(status: string | undefined): boolean {
+  return status === "completed" || status === "failed" || status === "cancelled";
+}
+
+function sessionStepStatusRank(payload: MessagePayload | undefined): number {
+  const status = stringValue(isRecord(payload?.session) ? payload.session.status : undefined);
+  return isTerminalSessionStepStatus(status) ? 2 : status === "running" ? 1 : 0;
+}
+
+function sessionPayloadWithCompletion(payload: MessagePayload | undefined, completedAt: number): MessagePayload {
+  const original = payload ?? {};
+  const session = isRecord(original.session) ? original.session : undefined;
+  const status = stringValue(session?.status);
+  return isTerminalSessionStepStatus(status) ? { ...original, session: { ...session, completedAt } } : original;
+}
+
+function policyNameFromTarget(target: string): string | null {
+  if (!target.startsWith("policy:")) return null;
+  const name = target.slice("policy:".length).trim();
+  return name || null;
+}
+
+function spawnPolicyExists(policyName: string): boolean {
+  const row = getDb().query("SELECT 1 FROM config WHERE namespace = 'spawn-policy' AND key = ?").get(policyName);
+  return Boolean(row);
+}
+
+function claimableAllowedForTarget(target: string): boolean {
+  return matchingDeliveryAgents(target).length > 1;
+}
+
+function shouldStoreClaimable(input: SendMessageInput): boolean {
+  if (!input.claimable) return false;
+  if (input.kind === "task" || input.kind === "system") return true;
+  if (input.kind === "channel.event") return true;
+  return claimableAllowedForTarget(input.to);
+}
+
+function inferMessageKind(input: SendMessageInput): Message["kind"] {
+  if (input.kind) return input.kind;
+  if (input.claimable) return "task";
+  if (isChannelAgentId(input.from) || isChannelAgentId(input.to)) return "channel.event";
+  return "chat";
+}
+
+const REPLY_DUPLICATE_WINDOW_MS = 2 * 60 * 1000;
+const LINEAGE_REPORT_DUPLICATE_WINDOW_MS = 2 * 60 * 1000;
+// MED-2 (r2 review): out-of-order session delivery across a turn boundary is only ever a few
+// seconds of skew; anything wider means the explicit belongs to the NEXT turn (fail open).
+const TURN_ORDER_SKEW_MS = 5 * 1000;
+
+function findRecentDuplicateReply(input: SendMessageInput, threadId: number | null, now: number, hasAttachments: boolean): Message | null {
+  if (!input.replyTo || threadId === null || hasAttachments) return null;
+  const kind = inferMessageKind(input);
+  const row = getDb().query(`
+    ${MSG_SELECT}
+    WHERE m.from_agent = ?
+      AND m.to_target = ?
+      AND m.kind = ?
+      AND m.thread_id = ?
+      AND m.body = ?
+      AND coalesce(m.subject, '') = coalesce(?, '')
+      AND coalesce(m.channel, '') = coalesce(?, '')
+      AND m.created_at >= ?
+      AND ${notReportSuppressedSql("m")}
+    ORDER BY m.created_at DESC
+    LIMIT 1
+  `).get(
+    input.from,
+    input.to,
+    kind,
+    threadId,
+    input.body,
+    input.subject ?? null,
+    input.channel ?? null,
+    now - REPLY_DUPLICATE_WINDOW_MS,
+  ) as any;
+  return row ? rowToMessage(row) : null;
+}
+
+function sessionMeta(input: Message | SendMessageInput): Record<string, unknown> | undefined {
+  return isRecord(input.payload?.session) ? input.payload.session : undefined;
+}
+
+function responseCaptureMeta(input: Message | SendMessageInput): Record<string, unknown> | undefined {
+  return isRecord(input.payload?.responseCapture) ? input.payload.responseCapture : undefined;
+}
+
+function isFinalSessionResponse(session: Record<string, unknown>): boolean {
+  return session.type === "response" && isTurnFinalSession(session);
+}
+
+function childStreamForSession(session: Record<string, unknown>): ChildStream | null {
+  if (session.type === "response") return "responses";
+  if (session.type === "tool") return "toolCalls";
+  if (session.type === "reasoning") return "reasoning";
+  if (session.type === "narration" || session.type === "narrative") return "narrative";
+  return null;
+}
+
+function captureTurnId(capture: Record<string, unknown>): string | undefined {
+  return stringValue(capture.turnId);
+}
+
+function lineageResponseTurnId(message: Message, session: Record<string, unknown>): string {
+  return stringValue(session.turnId) ?? `message-${message.id}`;
+}
+
+function lineageResponseReportKeyForTurn(childId: string, turnId: string): string {
+  return `response-report:${childId}:${turnId}`;
+}
+
+function lineageResponseReportKey(message: Message, session: Record<string, unknown>): string {
+  return lineageResponseReportKeyForTurn(message.from, lineageResponseTurnId(message, session));
+}
+
+function lineageStreamTurnId(message: Message, session: Record<string, unknown>): string {
+  return stringValue(session.turnId) ?? `message-${message.id}`;
+}
+
+function lineageStreamEventId(message: Message, session: Record<string, unknown>): string {
+  const occurredAt = typeof session.completedAt === "number" && Number.isFinite(session.completedAt) ? Math.floor(session.completedAt) : message.occurredAt ?? message.createdAt;
+  const stepId = stringValue(session.stepId);
+  return stepId ? `${stepId}:${occurredAt}` : `message:${occurredAt}`;
+}
+
+function lineageStreamReportKey(message: Message, session: Record<string, unknown>, stream: ChildStream): string {
+  if (stream === "responses") return lineageResponseReportKey(message, session);
+  return `${stream}-report:${message.from}:${lineageStreamTurnId(message, session)}:${lineageStreamEventId(message, session)}`;
+}
+
+function findLineageReportByTurn(input: {
+  from: string;
+  to: string;
+  turnId: string;
+  since: number;
+}): Message | null {
+  const lineageKey = lineageResponseReportKeyForTurn(input.from, input.turnId);
+  const row = getDb().query(LINEAGE_REPORT_BY_TURN_SQL).get(
+    input.from,
+    input.to,
+    input.since,
+    lineageKey,
+    `response-report:${input.from}:%:${input.turnId}`,
+    input.turnId,
+  ) as any;
+  return row ? rowToMessage(row) : null;
+}
+
+function findRecentLineageReport(input: SendMessageInput, now: number): Message | null {
+  if ((input.kind ?? "chat") !== "chat") return null;
+  const from = input.from;
+  const to = input.to;
+  if (!from || !to) return null;
+  const child = getAgent(from);
+  if (!child?.spawnedBy || (child.spawnedBy !== to && currentCoordinatorOf(child) !== to && delegatedCoordinatorTarget(child) !== to)) return null;
+  const responseCapture = responseCaptureMeta(input);
+  const turnId = responseCapture ? captureTurnId(responseCapture) : undefined;
+  if (turnId) {
+    const duplicate = findLineageReportByTurn({
+      from,
+      to,
+      turnId,
+      since: now - LINEAGE_REPORT_DUPLICATE_WINDOW_MS,
+    });
+    if (duplicate) return duplicate;
+  }
+  if (responseCapture) return null;
+  const row = getDb().query(RECENT_LINEAGE_REPORT_SQL).get(from, to, input.body, now - LINEAGE_REPORT_DUPLICATE_WINDOW_MS, `response-report:${from}:%`) as any;
+  return row ? rowToMessage(row) : null;
+}
+
+// T4458 (Edin's rule #2844 1a) — the sender's currently-open provider turn: the newest
+// session turnId with no final row yet and a row inside the duplicate window (a live turn
+// streams constantly). Lets a mid-turn explicit carry its turn exactly; a closed, stale or
+// absent turn yields undefined and the forward keeps today's content checks.
+export function senderOpenTurnId(sender: string, now: number): string | undefined {
+  const since = now - LINEAGE_REPORT_DUPLICATE_WINDOW_MS;
+  // MED-3: seed one id bound from the created_at index so both queries below range
+  // idx_msg_from_id on (from_agent, id) instead of filtering created_at per row.
+  const bound = firstMessageIdSince(since);
+  if (bound === null) return undefined;
+  const row = getDb().query(`
+    SELECT json_extract(payload, '$.session.turnId') AS turnId
+    FROM messages
+    WHERE from_agent = ? AND kind = 'session' AND id >= ?
+      AND json_extract(payload, '$.session.turnId') IS NOT NULL
+      AND created_at >= ?
+    GROUP BY turnId
+    ORDER BY MAX(created_at) DESC
+    LIMIT 1
+  `).get(sender, bound, since) as { turnId: string } | undefined;
+  if (!row?.turnId) return undefined;
+  // Time-bound like the turn search above — never a full-sender scan with json_extract
+  // inside the writer txn. A final older than the window with a newer live row is pathological.
+  const closed = getDb().query(`
+    SELECT 1 FROM messages
+    WHERE from_agent = ? AND kind = 'session' AND id >= ?
+      AND json_extract(payload, '$.session.turnId') = ?
+      AND (json_extract(payload, '$.session.final') = 1 OR json_extract(payload, '$.session.turnFinal') = 1)
+      AND created_at >= ?
+    LIMIT 1
+  `).get(sender, bound, row.turnId, since);
+  return closed ? undefined : row.turnId;
+}
+
+// #2844 — unknown-turn fallback: an explicit already carrying this capture's news, newest
+// first. Only the explicit-includes-capture direction adopts; a stamped same-turn explicit is
+// adopted by exact turn equality instead. Bare acks and `responseCapture` rows never count.
+const SAME_TURN_MIN_CHARS = 16;
+
+const normBody = (value: string): string => value.replace(/\s+/g, " ").trim();
+
+function findSameTurnExplicitReport(input: {
+  from: string;
+  to: string;
+  body: string;
+  at: number;
+  turnId?: string;
+}): Message | null {
+  const body = normBody(input.body);
+  // A stub capture ("Landed.") carries no news an explicit could subsume — and must never be
+  // adopted by an explicit that merely contains it ("Not landed. ...").
+  if (body.length < SAME_TURN_MIN_CHARS) return null;
+  // Same-turn keyed on the turn itself (its first session row), so a prior turn's escalation
+  // cannot swallow this final. No turn id → the duplicate window behind the capture. Forwarded
+  // reports, suppressed rows and bare acks never count as explicit.
+  const fallback = input.at - LINEAGE_REPORT_DUPLICATE_WINDOW_MS;
+  const rows = getDb().query(sameTurnExplicitReportSql(Boolean(input.turnId))).all(
+    input.from,
+    input.to,
+    ...(input.turnId ? [input.from, input.turnId, fallback] : [fallback]),
+    input.at + LINEAGE_REPORT_DUPLICATE_WINDOW_MS,
+  ) as any[];
+  for (const row of rows) {
+    const explicit = normBody(String(row?.body ?? ""));
+    if (explicit.length >= SAME_TURN_MIN_CHARS && explicit.includes(body)) return rowToMessage(row);
+  }
+  return null;
+}
+
+// T4458 (Edin's rule + ratio) — the explicit the child sent its parent DURING this turn,
+// adopted whatever the wording ONLY when report-sized (>= half the final's length); a short
+// ack falls through to the content checks. Previous turns, unstamped sends and ambiguous
+// (interleaving) stamps miss here. Sub-16 bodies never count.
+function findTurnExplicitReport(input: {
+  from: string;
+  to: string;
+  turnId: string;
+  before: number;
+  captureId: number;
+  captureLen: number;
+  captureOccurredAt: number;
+}): Message | null {
+  const row = getDb().query(TURN_EXPLICIT_REPORT_SQL).get(input.from, input.to, input.turnId, input.before) as any;
+  if (!row) return null;
+  const message = rowToMessage(row);
+  const explicitLen = normBody(String(message.body ?? "")).length;
+  if (explicitLen < SAME_TURN_MIN_CHARS || explicitLen < 0.5 * input.captureLen) return null;
+  // MED-1 (r1 review): a stamp is turn inference and can go stale — t1's late final can land
+  // after t2 already stamped an explicit with the old id, swallowing t1's final. Refuse the
+  // ambiguous stamp (fail open = forward) when another turn's rows interleave between the
+  // explicit and this capture; a cleanly sequenced turn has none. Ordered by row id, not
+  // wall-clock: same-millisecond sends must not read as ordered either way.
+  const interleaved = getDb().query(`
+    SELECT 1 FROM messages
+    WHERE from_agent = ? AND kind = 'session'
+      AND json_extract(payload, '$.session.turnId') IS NOT NULL
+      AND json_extract(payload, '$.session.turnId') <> ?
+      AND id > ? AND created_at <= ?
+    LIMIT 1
+  `).get(input.from, input.turnId, message.id, input.before);
+  if (interleaved) return null;
+  // MED-1 (r2 review): tool work after the explicit means the final carries more — a
+  // report-sized note must not swallow it. Refuse when more than one same-turn tool row sits
+  // between explicit and capture; the live pair's single send-result row still folds.
+  const toolWork = getDb().query(`
+    SELECT COUNT(*) AS n FROM messages
+    WHERE from_agent = ? AND kind = 'session'
+      AND json_extract(payload, '$.session.turnId') = ?
+      AND json_extract(payload, '$.session.type') = 'tool'
+      AND id > ? AND id < ?
+  `).get(input.from, input.turnId, message.id, input.captureId) as { n: number };
+  // MED-2 (r2 review): out-of-order delivery across a turn boundary — the capture's event
+  // time predates the explicit beyond skew, so the explicit belongs to the NEXT turn despite
+  // its stamp. Refuse (fail open); normal order (explicit first) always passes.
+  if (message.createdAt > input.captureOccurredAt + TURN_ORDER_SKEW_MS) return null;
+  if (toolWork.n > 1) return null;
+  return message;
+}
+
+function findRecentExplicitLineageDuplicate(input: {
+  from: string;
+  to: string;
+  body: string;
+  since: number;
+}): Message | null {
+  const row = getDb().query(RECENT_EXPLICIT_LINEAGE_DUPLICATE_SQL).get(
+    input.from,
+    input.to,
+    input.body,
+    input.since,
+  ) as any;
+  return row ? rowToMessage(row) : null;
+}
+
+// #1084/#3304 — reporting a definitive provider completion does not close its work window.
+// Keep recent captures for work-final metadata and legacy/uncertain captures for fallback delivery.
+const LINEAGE_FINAL_GROUP_RECENCY_MS = 10 * 60 * 1000;
+export { __resetDeferredLineageReports, restoreDeferredLineageReports, takeDeferredLineageReports } from "./deferred-lineage-reports.ts";
+
+export interface WorkFinalFlushResult {
+  /** The chat report(s) forwarded (or found already-forwarded) to the spawner, oldest first. */
+  forwarded: Array<{ message: Message; created: boolean }>;
+  /** The original session-mirror captures retroactively tagged `payload.finality` (for the
+   * `message.finalized` SSE upgrade of already-rendered bubbles). */
+  finalizedOriginals: Message[];
+}
+
+/**
+ * #1084 — close a child's work window: flush its held turn-final group to its spawner as ONE
+ * work-final unit sharing a fresh `windowId`, tagged with `source` (the explicit signal that closed
+ * the window) and an incrementing `groupOrder`. No-op when nothing was held. This is the ONLY path
+ * that marks a capture WORK-final (definitive provider completions can report before this).
+ * Also delivers held captures to the spawner (besides the `verbose` bypass in
+ * promoteLineageCapturedResponse) — call it from the finality service, never from a bus status edge.
+ */
+export function flushWorkFinalReports(childId: string, source: MessageWorkFinalitySource, options: { includeStaleCompletedFinals?: boolean } = {}): WorkFinalFlushResult {
+  const queue = takeDeferredLineageReports([childId])[childId];
+  if (!queue || queue.length === 0) return { forwarded: [], finalizedOriginals: [] };
+  return flushWorkFinalReportsFromQueue(childId, queue, source, options);
+}
+
+/** DB half of a finality flush using a queue captured from the main-thread hold map. */
+export function flushWorkFinalReportsFromQueue(
+  childId: string,
+  queue: number[],
+  source: MessageWorkFinalitySource,
+  options: { includeStaleCompletedFinals?: boolean } = {},
+  markedAt: number = Date.now(),
+): WorkFinalFlushResult {
+  const child = getAgent(childId);
+  const parent = currentCoordinatorOf(child);
+  if (!child || !parent) return { forwarded: [], finalizedOriginals: [] };
+
+  const windowId = randomUUID();
+  const recencyCutoff = markedAt - LINEAGE_FINAL_GROUP_RECENCY_MS;
+  const forwarded: Array<{ message: Message; created: boolean }> = [];
+  const finalizedOriginals: Message[] = [];
+  const held: Array<{ original: Message; session: Record<string, unknown> }> = [];
+  for (const messageId of queue) {
+    const original = getMessage(messageId);
+    if (!original || isReportSuppressed(original)) continue;
+    // #1084 MEDIUM — drop stale mid-work narration the count-capped ring is still holding from an
+    // earlier steer cycle; only captures from the completing sequence ride along in this group.
+    if (!options.includeStaleCompletedFinals && (original.occurredAt ?? original.createdAt) < recencyCutoff) continue;
+    const session = sessionMeta(original);
+    if (!session) continue;
+    held.push({ original, session });
+  }
+  const selected = source === "edge-fallback" ? selectEdgeFallbackLineageReports(held) : held;
+  let groupOrder = 0;
+  for (const { original, session } of selected) {
+    const suppress = reportVerbosityOf(child) === "off" || (reportVerbosityOf(child) !== "verbose" && lineageDeliveryCoversCapture(original, child, parent, markedAt));
+    const finality: MessageWorkFinality = { windowId, source, groupOrder, markedAt };
+    const result = suppress ? null : forwardLineageStreamCapture(original, session, "responses", child, parent, finality);
+    if (!suppress && !result) continue;
+    if (result) forwarded.push(result);
+    groupOrder++;
+    const finalizedOriginal = setMessageWorkFinality(original.id, finality);
+    if (finalizedOriginal) finalizedOriginals.push(finalizedOriginal);
+  }
+  return { forwarded, finalizedOriginals };
+}
+
+// #1469 — a bare acknowledgement / content-free coda a child emits as a turn-final. Anchored and
+// whole-string (allowing only trailing whitespace/punctuation), so a real report that merely
+// CONTAINS one of these words ("Done. Gates green, committed…") is never matched — only a body that
+// is nothing BUT the ack. Deliberately TIGHT — a small explicit set, not a fuzzy "looks short"
+// heuristic: absence of report structure is NOT grounds to drop (that would regress a legitimately
+// short final like "Landed abc123 on main."), only an empty body or a positive ack match is.
+const NON_SUBSTANTIVE_ECHO = /^(?:ok(?:ay)?|ack|acknowledged?|noted|thanks|thank you|got it|will do|done|roger)[\s.!]*$/i;
+
+function selectEdgeFallbackLineageReports<T extends { original: Message }>(held: T[]): T[] {
+  if (held.length === 0) return held;
+  let bestIndex = -1;
+  let bestScore = -Infinity;
+  for (let i = 0; i < held.length; i++) {
+    const score = edgeFallbackReportScore(held[i]!.original.body);
+    if (score > bestScore || (score === bestScore && i > bestIndex)) {
+      bestScore = score;
+      bestIndex = i;
+    }
+  }
+  const selected = bestScore > 0 && bestIndex >= 0 ? held[bestIndex]! : held.at(-1)!;
+  // #1469 — an `edge-fallback` flush fires at teardown/reap/prune, long after the turn was captured
+  // and after the spawner has moved on from (and often reaped) the child. A bare non-substantive
+  // turn-final ("Acknowledged.") carries no report value and lands as pure noise on a spawner that no
+  // longer tracks the child — the recurring #1469 stray. Drop it rather than forward. A SUBSTANTIVE
+  // held final (genuine crash-final-loss recovery, #1136/#1084) scores > 0 above, or is a short-but-
+  // real report the tight ack filter never matches, and rides through untouched.
+  const body = selected.original.body.trim();
+  return body.length === 0 || NON_SUBSTANTIVE_ECHO.test(body) ? [] : [selected];
+}
+
+const EDGE_FALLBACK_REPORT_BOUNDARY = /(^|\n)(#{1,6}\s|\*\*(summary|what changed|rca|fix|tests?|gates?|verification|risk)\b|(?:summary|what changed|rca|fix|tests?|gates?|verification|risk):)/i;
+const EDGE_FALLBACK_REPORT_STRUCTURE = /(^|\n)\s*[-*]\s+\S|`[^`]+`|\b(typecheck|bun test|tests? pass(?:ed)?|gates? green|rca|verified|implemented)\b/i;
+const EDGE_FALLBACK_GENERIC_CODA = /^(?:done|landed(?: on main)?|committed|merged|ready|no further action|nothing further|all set)\b|(?:\bno further action needed\b|\bnothing further needed\b)$/i;
+const EDGE_FALLBACK_NARRATION = /^(?:i(?:'|’)ll|i(?:'|’)m|let me|checking|running|reading|found\b|now\b)/i;
+
+function edgeFallbackReportScore(body: string): number {
+  const trimmed = body.trim();
+  if (!trimmed) return -10;
+  if (trimmed.length <= 180 && EDGE_FALLBACK_GENERIC_CODA.test(trimmed) && !EDGE_FALLBACK_REPORT_BOUNDARY.test(trimmed)) return -5;
+  let score = 0;
+  if (trimmed.length >= 120) score += 2;
+  if (EDGE_FALLBACK_REPORT_BOUNDARY.test(trimmed)) score += 6;
+  if (EDGE_FALLBACK_REPORT_STRUCTURE.test(trimmed)) score += 3;
+  if (EDGE_FALLBACK_NARRATION.test(trimmed)) score -= 3;
+  return score;
+}
+
+// #1032b — a delivered report-up is a first-class lifecycle signal to the spawner. Stamp it so a
+// redundant "Task status pulse" for the same child/task is suppressed rather than double-waking.
+// #1038 — a report-up conveys "the child is progressing", so it is state-keyed to `working`: it
+// supersedes only a redundant `working` pulse, never a later distinct milestone (committed/landed/done).
+function stampReportUpLifecycleSignal(parent: string, child: AgentCard): void {
+  stampLifecycleSignal(parent, childSignalKey(child.id));
+  for (const taskId of childTaskIds(child)) stampLifecycleSignal(parent, taskSignalKey(taskId, LIFECYCLE_STATE_WORKING));
+}
+
+export function promoteLineageCapturedResponse(message: Message): { message: Message; created: boolean } | null {
+  if (message.kind !== "session" || isReportSuppressed(message)) return null;
+  const session = sessionMeta(message);
+  if (!session) return null;
+  const stream = childStreamForSession(session);
+  if (!stream) return null;
+  if (stream === "responses" && !isFinalSessionResponse(session)) return null;
+  const child = getAgent(message.from);
+  const parent = currentCoordinatorOf(child);
+  if (!child || !parent) return null;
+  const verbosity = reportVerbosityOf(child);
+  if (verbosity === "off") return null;
+  // #1037 verbose: forward every child stream without an explicit per-stream subscription.
+  if (stream !== "responses" && verbosity !== "verbose" && !childStreamSubscribed({ parentId: parent, child, stream })) return null;
+
+  // #3304 — provider completion is enough to report a turn, without declaring the Task done.
+  // Keep the ring for later work-final metadata; addressed captures already have a runner reply.
+  if (stream === "responses" && verbosity !== "verbose") {
+    deferLineageReport(child.id, message.id);
+    if (session.confidence !== "definitive" || session.endedBy !== "completed" || message.replyTo) return null;
+    if (lineageDeliveryCoversCapture(message, child, parent, message.createdAt)) return null;
+  }
+
+  return forwardLineageStreamCapture(message, session, stream, child, parent);
+}
+
+/**
+ * Forward one captured child-stream event to its spawner as a `chat` report-up. Shared by the
+ * `verbose` immediate bypass (no `finality`) and `flushWorkFinalReports` (tags the forwarded report
+ * — and, via the caller, the original capture — with the closing work window's `finality`).
+ */
+function forwardLineageStreamCapture(
+  message: Message,
+  session: Record<string, unknown>,
+  stream: ChildStream,
+  child: AgentCard,
+  parent: string,
+  finality?: MessageWorkFinality,
+): { message: Message; created: boolean } | null {
+  const parentAgentId = parent;
+  parent = canonicalLineageReportTarget(child, parent);
+  const idempotencyKey = lineageStreamReportKey(message, session, stream);
+  const existing = findMessageByIdempotencyKey(message.from, idempotencyKey);
+  if (existing) {
+    // #1084 MEDIUM (Lens-3 retroactive-finality) fix-forward — an already-forwarded report (e.g. a
+    // `verbose` bypass, or a duplicate suppressed on an earlier attempt) must still pick up the
+    // finality tag when its window later closes, or its dashboard bubble never upgrades from
+    // ordinary mid-turn narration to a closing message. Only patch when it isn't already tagged —
+    // an existing tag reflects an earlier, equally-valid window close and must not be overwritten.
+    if ((finality && !hasWorkFinality(existing.payload)) || (stream === "responses" && existing.messageType !== "final-turn")) {
+      const updatedPayload: MessagePayload = { ...(existing.payload ?? {}), finality };
+      getDb().query("UPDATE messages SET payload = ?, message_type = ?, source_message_id = ? WHERE id = ?")
+        .run(JSON.stringify(updatedPayload), stream === "responses" ? "final-turn" : existing.messageType ?? null, stream === "responses" ? message.id : existing.sourceMessageId ?? null, existing.id);
+      return { message: getMessage(existing.id) ?? existing, created: false };
+    }
+    return { message: existing, created: false };
+  }
+  if (stream === "responses") {
+    // A child may close its turn by pointing at the full report it already sent to this
+    // parent. The explicit report is the parent delivery; keep this capture in the
+    // dashboard, but do not manufacture a second inbox message for its pointer.
+    const pointer = message.body.trim().match(/^(?:(.{1,160}?)\s*(?:\.{3}|…)\s*)?(?:full\s+)?report\s+(?:sent\s*:\s*(?:message\s+)?(?:id\s*)?|in\s+message\s+(?:id\s*)?)#?(\d+)[.!\s]*$/i);
+    if (pointer) {
+      const explicit = getMessage(Number(pointer[2]));
+      const repeatedSummary = pointer[1]?.trim();
+      if (explicit && explicit.from === message.from && explicit.to === parent && explicit.kind === "chat" && !isReportSuppressed(explicit)
+        && (!repeatedSummary || explicit.body.includes(repeatedSummary))
+        && explicit.id !== message.id && explicit.createdAt <= message.createdAt
+        && message.createdAt - explicit.createdAt <= LINEAGE_REPORT_DUPLICATE_WINDOW_MS) {
+        return { message: explicit, created: false };
+      }
+    }
+    const turnId = captureTurnId(session);
+    if (turnId) {
+      const crossKeyDuplicate = findLineageReportByTurn({
+        from: message.from,
+        to: parent,
+        turnId,
+        since: message.createdAt - LINEAGE_REPORT_DUPLICATE_WINDOW_MS,
+      });
+      if (crossKeyDuplicate) {
+        getDb().query("UPDATE messages SET message_type = 'final-turn', source_message_id = ? WHERE id = ?")
+          .run(message.id, crossKeyDuplicate.id);
+        return { message: getMessage(crossKeyDuplicate.id) ?? crossKeyDuplicate, created: false };
+      }
+    }
+
+    const duplicate = findRecentExplicitLineageDuplicate({
+      from: message.from,
+      to: parent,
+      body: message.body,
+      since: message.createdAt - LINEAGE_REPORT_DUPLICATE_WINDOW_MS,
+    });
+    if (duplicate && !responseCaptureMeta(duplicate)) {
+      const updatedPayload: MessagePayload = {
+        ...(duplicate.payload ?? {}),
+        responseCapture: { ...session },
+        ...(finality ? { finality } : {}),
+      };
+      getDb().query(`
+        UPDATE messages
+        SET idempotency_key = coalesce(idempotency_key, ?),
+            payload = ?,
+            message_type = 'final-turn',
+            source_message_id = ?
+        WHERE id = ?
+      `).run(idempotencyKey, JSON.stringify(updatedPayload), message.id, duplicate.id);
+      return { message: getMessage(duplicate.id) ?? duplicate, created: false };
+    }
+    // T4458 (Edin's rule #2844 1a): the child already told its parent explicitly during THIS
+    // turn (server-stamped senderTurnId) — when report-sized (Edin's ratio) that explicit IS
+    // the parent delivery, so the turn-final stays transcript-only. Same no-new-row shape, no
+    // metadata merge (bodies differ). Previous turns, unstamped sends and short acks fall
+    // through to the content check. The `verbose` firehose bypasses both.
+    if (reportVerbosityOf(child) !== "verbose") {
+      const captureLen = normBody(message.body).length;
+      if (turnId && captureLen >= SAME_TURN_MIN_CHARS) {
+        const turnExplicit = findTurnExplicitReport({ from: message.from, to: parent, turnId, before: message.createdAt, captureId: message.id, captureLen, captureOccurredAt: message.occurredAt ?? message.createdAt });
+        if (turnExplicit) return { message: turnExplicit, created: false };
+      }
+      const sameTurnExplicit = findSameTurnExplicitReport({ from: message.from, to: parent, body: message.body, at: message.createdAt, turnId });
+      if (sameTurnExplicit) return { message: sameTurnExplicit, created: false };
+    }
+  }
+
+  const result = sendMessageWithResult({
+    from: message.from,
+    to: parent,
+    kind: "chat",
+    // #1935 — a final forward is ordinary delivery metadata plus the exact captured turn. Provider
+    // delivery (not the server) owns the single full-vs-stub decision.
+    body: message.body,
+    ...(stream === "responses" ? { messageType: "final-turn" as const, sourceMessageId: message.id } : {}),
+    replyExpected: false,
+    idempotencyKey,
+    payload: stream === "responses"
+      ? { responseCapture: { ...session }, ...(finality ? { finality } : {}) }
+      : { childStreamCapture: { stream, ...session } },
+    occurredAt: message.occurredAt ?? message.createdAt,
+  });
+  if (stream === "responses" && result.created) {
+    stampReportUpLifecycleSignal(parentAgentId, child);
+  }
+  return result;
+}
+
+export function setMessageWorkFinality(messageId: number, finality: MessageWorkFinality): Message | null {
+  const message = getMessage(messageId);
+  if (!message) return null;
+  const payload: MessagePayload = { ...(message.payload ?? {}), finality };
+  getDb().query("UPDATE messages SET payload = ? WHERE id = ?").run(JSON.stringify(payload), messageId);
+  return getMessage(messageId);
+}
+
+/** Mark the durable self-resume recovery artifact only after its matching provider injection was
+ * accepted. Creating the message is storage, not delivery; keeping those facts separate prevents
+ * the dashboard from claiming a cleared agent received context when replay is still pending.
+ * #2550 — ingestion settles the TRANSPORT ledger too: the row was previously left
+ * delivery_status='pending' with zero attempts even after the envelope provably reached the
+ * provider, so it read back as undelivered mail forever and stayed a live candidate for the
+ * ordinary delivery pipeline. One terminal stamp (delivered + one attempt, error/retry/poison
+ * cleared) makes the transport state reflect reality; the caller emits the SSE update. */
+export function markSelfResumeContinuationIngested(messageId: number, now = Date.now()): Message | null {
+  const message = getMessage(messageId);
+  if (!message || message.payload?.kind !== "agent.self_resume_continuation") return null;
+  const delivery = isRecord(message.payload.delivery) ? message.payload.delivery : undefined;
+  if (delivery?.state === "ingested") return message;
+  const payload: MessagePayload = {
+    ...message.payload,
+    delivery: { state: "ingested", ingestedAt: now },
+  };
+  getDb().query(`
+    UPDATE messages
+    SET payload = ?,
+        delivery_status = 'delivered',
+        delivery_attempts = delivery_attempts + 1,
+        delivery_last_error = NULL,
+        delivery_next_retry_at = NULL,
+        delivery_poison_reason = NULL,
+        delivery_updated_at = ?
+    WHERE id = ?
+  `).run(JSON.stringify(payload), now, messageId);
+  return getMessage(messageId);
+}
+
+/** #2545 — true when the self-resume recovery artifact for `messageId` was positively accepted by
+ * the provider (the runner's stored→ingested promotion). This is the DELIVERY ground truth the
+ * re-injection sweep dedupes on: a boundary whose attempt ledger says failed/timed_out but whose
+ * artifact provably landed is a bookkeeping lie, not a missing delivery, and re-delivering it to
+ * an idle agent on every lifecycle epoch is exactly the duplicate-continuation spam #2545 fixes.
+ * A missing/unreadable message or payload answers false — fail toward re-delivering (#1023). */
+export function selfResumeContinuationIngested(messageId: number | undefined): boolean {
+  if (messageId === undefined) return false;
+  const message = getMessage(messageId);
+  if (!message || message.payload?.kind !== "agent.self_resume_continuation") return false;
+  const delivery = isRecord(message.payload.delivery) ? message.payload.delivery : undefined;
+  return delivery?.state === "ingested";
+}
+
+// Event time may be queued-then-backfilled, so it can legitimately be older than the
+// receive time — but it must be a sane epoch-ms value. Returns null (column stays NULL, so
+// readers fall back to created_at) for absent/invalid values or anything more than a minute
+// in the future (clock-skew guard). Only a real backfilled time is stored.
+function sanitizeOccurredAt(occurredAt: number | undefined, receivedAt: number): number | null {
+  if (typeof occurredAt !== "number" || !Number.isFinite(occurredAt)) return null;
+  if (occurredAt <= 0 || occurredAt > receivedAt + 60_000) return null;
+  return Math.floor(occurredAt);
+}
+
+/** Hot send-path read: the next sender-local sequence number. Kept exported so the query-plan
+ * gate exercises this exact production statement rather than a hand-written approximation.
+ * `seq IS NOT NULL` lets the partial idx_msg_from_seq serve MAX() as one seek (#3044). */
+export const NEXT_MESSAGE_SEQ_SQL = "SELECT COALESCE(MAX(seq), 0) + 1 AS seq FROM messages WHERE from_agent = ? AND seq IS NOT NULL";
+
+function nextMessageSeq(from: string): number {
+  const row = getDb().query(NEXT_MESSAGE_SEQ_SQL).get(from) as { seq: number } | undefined;
+  return row?.seq ?? 1;
+}
+
+export interface SendMessageResult {
+  message: Message;
+  created: boolean;
+  updated?: boolean;
+}
+
+export interface SendMessageWriteOptions {
+  /** #1538 — timer-fire-outbox durable replay ONLY. Skip the live sender-registration check because
+   * the send carries a frozen captured identity whose agent may have deregistered. Never set on a
+   * live wire send. */
+  allowUnregisteredSender?: boolean;
+  internalCoordinatorDigest?: boolean;
+}
+
+type ServerMessageInput = SendMessageInput & { messageType?: "final-turn"; sourceMessageId?: number };
+
+export function sendMessageWithResult(input: ServerMessageInput, opts: SendMessageWriteOptions = {}): SendMessageResult {
+  return sendMessageWithResultInternal(input, true, opts);
+}
+
+// The batch body: one INSERT per input under a SINGLE held write lock (ALL-OR-NOTHING — one caller's
+// atomic multi-row request; §3.9.1). `now` is threaded through so a relocated op captures time once at
+// submission (H6). Bounded by MAX_MESSAGE_BATCH (100) so the synchronous lock-hold stays short.
+// Exported so the `messages.sendBatch` writer op (message-write-ops.ts) can relocate the WHOLE batch as
+// ONE atomic op: any input throwing rolls back every sibling (the executor's single BEGIN IMMEDIATE),
+// which is the correct contract for one caller's batch and is DISTINCT from the per-caller SAVEPOINT
+// isolation `messages.send` uses to coalesce INDEPENDENT same-tick callers.
+export function insertMessageBatch(inputs: ServerMessageInput[], now: number = Date.now()): SendMessageResult[] {
+  return inputs.map((input) => sendMessageWithResultInternal(input, false, {}, now));
+}
+
+/** Synchronous batch insert in one BEGIN IMMEDIATE transaction (#1428). Single attempt: a BUSY that
+ * survives busy_timeout throws. Off-loop request paths use `sendMessagesBatchWithResultAsync`
+ * (src/db/message-send.ts), which routes through the async gateway `messages.send` op (L1 seam). */
+export function sendMessagesBatchWithResult(inputs: ServerMessageInput[]): SendMessageResult[] {
+  return writeTransaction(() => insertMessageBatch(inputs));
+}
+
+// The single-send op BODY (registered as `messages.send` in src/db/message-write-ops.ts). Exported so
+// the writer op registry can relocate it onto the worker thread; `wrapTransaction=false` is the op
+// shape (the executor already opened the BEGIN IMMEDIATE / per-caller SAVEPOINT, §3.4). See
+// message-write-ops.ts for the L1 seam rationale (TOCTOU fold, H5 idempotency, coalescing).
+/** A `user:<id>` address of an existing user. */
+function isUserSink(id: string): boolean {
+  const userId = id.startsWith(USER_NAMESPACE_PREFIX) ? id.slice(USER_NAMESPACE_PREFIX.length) : "";
+  return Boolean(userId && getUser(userId));
+}
+
+export function sendMessageWithResultInternal(
+  input: ServerMessageInput,
+  wrapTransaction: boolean,
+  opts: SendMessageWriteOptions = {},
+  // H6 (§3.1/§3.4): wall-clock is captured at op SUBMISSION on the main thread and passed IN, never
+  // re-read `Date.now()` worker-side (which would run at some later worker-scheduling instant). Sync
+  // in-process callers default to now; the `messages.send` writer op passes `ctx.now`.
+  now: number = Date.now(),
+): SendMessageResult {
+  if (wrapTransaction) return writeTransaction(() => sendMessageWithResultInternal(input, false, opts, now));
+  const payload = clearCoordinatorDigestRouting(normalizeMessagePayload(input.payload));
+  input.payload = payload;
+  const attachmentRefs = cleanAttachmentRefs(payload);
+
+  // The registration guard is the LIVE-send anti-spoof: a wire sender must currently exist. The
+  // durable timer-fire-outbox is the single exception (#1538) — it replays a committed decision on a
+  // frozen captured identity, so the creating agent may have deregistered; the `from` was already
+  // authorized (and #362 anti-spoofed) at create time. Only that internal path passes the flag.
+  const sender = getAgent(input.from);
+  // #3567 — a real user's `user:<id>` sink has no agent row; the send service already pinned it to the session.
+  if (!opts.allowUnregisteredSender && !sender && !isUserSink(input.from)) {
+    throw new ValidationError(`sender agent ${input.from} not registered`);
+  }
+  validateAttachmentRefs(attachmentRefs);
+
+  if (sender && responseCaptureMeta(input)) input.to = canonicalLineageReportTarget(sender, input.to);
+  const lineageDuplicate = findRecentLineageReport(input, now);
+  if (lineageDuplicate) return { message: lineageDuplicate, created: false };
+
+  if (input.idempotencyKey) {
+    const existing = findMessageByIdempotencyKey(input.from, input.idempotencyKey);
+    if (existing) {
+      // Session-step upsert: a re-emitted provider step (tool running→completed, streamed
+      // reasoning/response) updates its row in place instead of being dropped as a dup retry.
+      const upserted = upsertSessionStepInPlace(existing, input, now);
+      if (upserted) return { message: upserted, created: false, updated: true };
+      return { message: existing, created: false };
+    }
+  }
+
+  // Resolve thread: if replying, inherit from parent; reject unknown replyTo
+  // rather than silently orphaning the message (leaves thread_id NULL).
+  let threadId: number | null = null;
+  if (input.replyTo !== undefined && input.replyTo !== null) {
+    const parent = getMessage(input.replyTo);
+    if (!parent) throw new ValidationError(`replyTo message ${input.replyTo} not found`);
+    threadId = parent.threadId ?? parent.id;
+  }
+  const duplicateReply = findRecentDuplicateReply(input, threadId, now, attachmentRefs.length > 0);
+  if (duplicateReply) return { message: duplicateReply, created: false };
+
+  // #3060 — a root threads itself in its own single-row INSERT, on the id AUTOINCREMENT would pick: a second UPDATE
+  // would fire the reply-obligation update trigger, and INSERT ... SELECT a statement journal, on every send.
+  const nextId = "(SELECT max(coalesce((SELECT seq FROM sqlite_sequence WHERE name = 'messages'), 0), coalesce((SELECT max(id) FROM messages), 0)) + 1)";
+  const insert = getDb().query(`
+    INSERT INTO messages (
+      id, from_agent, to_target, kind, message_type, source_message_id, channel, subject, body, thread_id, reply_to, reply_expected, claimable,
+      urgent_requested, urgent_throttled,
+      idempotency_key, delivery_status, delivery_last_error, delivery_poison_reason, delivery_updated_at, queued_at, max_age_seconds, resolved_to_agent,
+      payload, meta, created_at, occurred_at, seq
+    )
+    VALUES (
+      ${nextId}, $from, $to, $kind, $messageType, $sourceMessageId, $channel, $subject, $body, coalesce($threadId, ${nextId}), $replyTo, $replyExpected, $claimable,
+      $urgentRequested, $urgentThrottled,
+      $idempotencyKey, $deliveryStatus, $deliveryLastError, $deliveryPoisonReason, $deliveryUpdatedAt, $queuedAt, $maxAgeSeconds, $resolvedToAgent,
+      $payload, $meta, $now, $occurredAt, $seq
+    )
+  `);
+  const claimable = shouldStoreClaimable(input);
+  const kind = inferMessageKind(input);
+  // #2335 (P1 privacy, supersedes #2089) — CHANNEL-EGRESS ALLOWLIST. Anything addressed to a channel
+  // bridge that is not deliberate channel content is stamped here so decideDelivery routes it to
+  // `history` and is NEVER fanned to the channels-host bridge (which would DM it to a real human).
+  // Stamped onto the persisted payload below (`$payload`), so every later live/replay/poll delivery
+  // decides identically. The DECISION is the pure isDisallowedChannelContent in
+  // ./channel-egress-allowlist.ts; only the channel-target read and the insert-time stamp are here.
+  // Pure predicate FIRST: it answers false immediately for the overwhelmingly common send (an ordinary
+  // kind with no payload), so the channel lookup's getAgent + channels SELECT is paid only by a send
+  // that could actually be suppressed — never by every message in the system.
+  const channelSuppressed = isDisallowedChannelContent(input.payload, kind, input.meta) && isChannelEgressTarget(input.to);
+  if (channelSuppressed) payload.channelReportSuppressed = true;
+  // #2831 — decided once here, inside the writer transaction; see ./report-suppression.ts.
+  const { suppression: reportSuppression, answers: answeredQuestion } = decideReportSuppression(input, kind, sender, now);
+  if (reportSuppression) payload.reportSuppression = reportSuppression;
+  // T4458 (Edin's rule #2844 1a) — stamp the sender's open provider turn on an explicit child
+  // chat, so the turn-final forward matches its turn exactly. Cheap gates first: only a spawned
+  // child's plain chat pays the open-turn lookup; mirrors, capture forwards and server notices
+  // never do. Unknown turn → unstamped, and the forward keeps today's content checks.
+  if (kind === "chat" && input.messageType !== "final-turn" && sender?.spawnedBy
+    && !isRecord(payload.responseCapture) && !isRecord(payload.childStreamCapture)) {
+    const openTurn = senderOpenTurnId(input.from, now);
+    if (openTurn) payload.senderTurnId = openTurn;
+  }
+  // A suppressed runner report is permanently undeliverable, exactly like a channel-suppressed row.
+  const suppressionReason = channelSuppressed ? CHANNEL_SUPPRESSION_REASON
+    : reportSuppression && kind !== "session" ? REPORT_SUPPRESSION_REASON : null;
+  const policyName = policyNameFromTarget(input.to);
+  let deliveryStatus: Message["deliveryStatus"] = "pending";
+  let queuedAt: number | null = null;
+  // Distinguish "unspecified" (apply the #451 fan-out default below) from an explicit `null`
+  // (authoritative never-expire — routeNotification sets this for store-ahead notification types,
+  // and the baseline must not override it). Both store as NULL, but only unspecified gets a default.
+  const ttlUnspecified = input.maxAgeSeconds === undefined;
+  let maxAgeSeconds = input.maxAgeSeconds ?? null;
+  let resolvedToAgent: string | null = null;
+
+  if (input.to.startsWith("coordinator:")) {
+    const teamId = input.to.slice(12);
+    if (!isClaimableTeam(getTeam(teamId))) throw new ValidationError(`active team ${teamId} not found`);
+    resolvedToAgent = resolveTeamCoordinatorAgentId(teamId);
+    if (!resolvedToAgent) {
+      deliveryStatus = "queued";
+      queuedAt = now;
+      if (ttlUnspecified) maxAgeSeconds = 86_400;
+    }
+  } else if (policyName) {
+    if (!spawnPolicyExists(policyName)) throw new ValidationError(`spawn policy ${policyName} not found`);
+    resolvedToAgent = runningAgentForPolicy(policyName);
+    if (!resolvedToAgent) {
+      deliveryStatus = "queued";
+      queuedAt = now;
+      if (ttlUnspecified) maxAgeSeconds = 86_400;
+    }
+  } else if (!isFanoutTarget(input.to) && !isMechanicalMessageKind(input.kind)) {
+    // #416 — queue messages to a registered-but-temporarily-unavailable direct target so they
+    // are not silently held as "pending" while the agent cannot process them. The flush fires
+    // when the agent returns to available (heartbeat stale→idle, re-registration, rate-limit
+    // resume). Offline agents use the existing store-ahead path (policyName is null, status
+    // "offline" → resolveQueuedDirectMessages is never called for them — the queue is cleared
+    // only when the agent actually comes back as non-offline).
+    const directAgent = getAgent(input.to);
+    if (directAgent && isAgentUnavailable(directAgent)) {
+      deliveryStatus = "queued";
+      queuedAt = now;
+      if (ttlUnspecified) maxAgeSeconds = 86_400;
+    }
+  }
+
+  // #451/#461 — moderate default TTL for non-claimable FAN-OUT messages the sender didn't bound,
+  // so stale broadcast/tag/cap/label/team chat cannot wake a late-joining agent hours later. Exempt
+  // (never auto-expire, preserving store-ahead #234): direct DMs and policy targets (single
+  // recipient), claimable work, and any message that already carried an explicit TTL — including an
+  // explicit `null` from routeNotification, whose per-type decision (e.g. a store-ahead
+  // `plan.bound_agent_exited` to `team:`) must win here.
+  if (ttlUnspecified && !claimable && isFanoutTarget(input.to)) {
+    maxAgeSeconds = DEFAULT_FANOUT_TTL_SECONDS;
+  }
+
+  // #2395 — a channel-suppressed row is PERMANENTLY undeliverable (isDisallowedChannelContent is a
+  // point-in-time payload-shape decision, not a transient recipient state), so it must not read back
+  // as an ordinary "pending"/"queued" send: that made the earlier silent-loss bug possible — the row
+  // sat at `delivery_status='pending'` with zero attempts forever, indistinguishable from a message
+  // that simply hadn't been polled yet. Overriding to `dead` here (after the policy/offline-queue
+  // resolution above, so it wins over both) makes the outcome OBSERVABLE the same way every other
+  // permanent delivery failure is: excluded from every poll (message-reads.ts's unconditional
+  // `delivery_status NOT IN ('failed','dead')`, on top of the channel poll's own suppression-stamp
+  // filter), surfaced as a dashboard delivery-failure notification (sse.ts notificationForDelivery),
+  // and visible via `GET /messages/:id/delivery`. See channel-egress-allowlist.ts for the reason text.
+  // #3013 — no turn ever attempts or reads a history row either; settle it now so no poll rescans it.
+  stampWorkflowContact({ message: input, kind, payload, sender, resolvedToAgent }); // #3045 — the run's, not its coordinator's
+  const insertDigest = (digest: SendMessageInput) => sendMessageWithResultInternal(digest, false, { internalCoordinatorDigest: true }, now).message;
+  const digestRecipient = opts.internalCoordinatorDigest ? null : prepareCoordinatorDigest(input, kind, payload, resolvedToAgent,
+    Boolean(suppressionReason) || settlesAsHistory({ kind, payload }), now, insertDigest);
+  const settledStatus = suppressionReason ? "dead" : settlesAsHistory({ kind, payload }) ? "history" : null;
+  if (settledStatus) {
+    deliveryStatus = settledStatus;
+    queuedAt = null;
+  }
+
+  const insertMessage = () => {
+    if (input.messageType !== undefined || input.sourceMessageId !== undefined) {
+      if (input.messageType !== "final-turn" || !Number.isSafeInteger(input.sourceMessageId) || input.sourceMessageId! <= 0) {
+        throw new ValidationError("invalid final-turn message lineage");
+      }
+      const source = getMessage(input.sourceMessageId!);
+      const sourceSession = source ? sessionMeta(source) : undefined;
+      if (!source || source.from !== input.from || !sourceSession || !isFinalSessionResponse(sourceSession)) {
+        throw new ValidationError("final-turn source must be a same-sender turn-final response");
+      }
+    }
+    // The debit is inside the message transaction and after all duplicate checks: retries never
+    // consume another token, while any failed insert rolls its budget mutation back with the row.
+    const urgentRequested = input.urgent === true;
+    const urgentThrottled = urgentRequested && !admitUrgentMessage(input.from, input.to, now);
+    const result = insert.run({
+      $from: input.from,
+      $to: input.to,
+      $kind: kind,
+      $messageType: input.messageType ?? null,
+      $sourceMessageId: input.sourceMessageId ?? null,
+      $channel: input.channel ?? null,
+      $subject: input.subject ?? null,
+      $body: input.body,
+      $threadId: threadId,
+      $replyTo: input.replyTo ?? null,
+      // Server-owned reply obligation (#283): true by default; only an explicit false marks
+      // a notification. Stored 0/1 so the footer renderer + reply tracker key off one column.
+      $replyExpected: input.replyExpected === false ? 0 : 1,
+      $claimable: claimable ? 1 : 0,
+      $urgentRequested: urgentRequested ? 1 : 0,
+      $urgentThrottled: urgentThrottled ? 1 : 0,
+      $idempotencyKey: input.idempotencyKey ?? null,
+      $deliveryStatus: deliveryStatus,
+      $deliveryLastError: suppressionReason,
+      $deliveryPoisonReason: suppressionReason,
+      $deliveryUpdatedAt: settledStatus ? now : null,
+      $queuedAt: queuedAt,
+      $maxAgeSeconds: maxAgeSeconds,
+      $resolvedToAgent: resolvedToAgent,
+      $payload: JSON.stringify(payload),
+      $meta: JSON.stringify(input.meta ?? {}),
+      $now: now,
+      // Sanitize: only accept a plausible epoch-ms event time, else fall back to receive time.
+      $occurredAt: sanitizeOccurredAt(input.occurredAt, now),
+      $seq: nextMessageSeq(input.from),
+    });
+    const newId = Number(result.lastInsertRowid);
+    if (digestRecipient) enqueueCoordinatorDigest(newId, digestRecipient, now, insertDigest);
+    closeReplyObligationsOnInsert({ id: newId, from: input.from, replyTo: input.replyTo ?? null, threadId, channel: input.channel ?? null });
+    if (answeredQuestion) markRead(answeredQuestion, input.from, now);
+    linkMessageArtifacts(newId, attachmentRefs, input.body, input.from, now);
+    if (deliveryStatus === "queued") {
+      enforceQueueLimit(input.to);
+    }
+    return newId;
+  };
+  const id = insertMessage();
+
+  return { message: getMessage(id)!, created: true };
+}
+
+export function sendMessage(input: SendMessageInput): Message {
+  return sendMessageWithResult(input).message;
+}
+
+export { getThread } from "./message-thread";
+
+export function setMessageReaction(input: {
+  messageId: number;
+  actorId: string;
+  emoji: string;
+  action?: "add" | "remove";
+}, now: number = Date.now()): { ok: true; message: Message } | { ok: false; error: string } {
+  if (!getMessage(input.messageId)) return { ok: false, error: "message not found" };
+  const actorId = input.actorId.trim();
+  const emoji = normalizeReactionEmoji(input.emoji);
+  if (!actorId) return { ok: false, error: "actorId required" };
+  if (!emoji) return { ok: false, error: "emoji required" };
+
+  if (input.action === "remove") {
+    getDb().query("DELETE FROM message_reactions WHERE message_id = ? AND actor_id = ? AND emoji = ?")
+      .run(input.messageId, actorId, emoji);
+  } else {
+    getDb().query(`
+      INSERT INTO message_reactions (message_id, actor_id, emoji, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(message_id, actor_id, emoji) DO UPDATE SET updated_at = excluded.updated_at
+    `).run(input.messageId, actorId, emoji, now, now);
+  }
+
+  return { ok: true, message: getMessage(input.messageId)! };
+}
+
+export function findMessageByTelegramSource(input: {
+  accountId?: string;
+  chatId: string;
+  messageId: string;
+}): Message | null {
+  const rows = getDb().query(`
+    ${MSG_SELECT}
+    WHERE json_extract(m.payload, '$.source.telegram.chatId') = ?
+      AND json_extract(m.payload, '$.source.telegram.messageId') = ?
+      AND (? IS NULL OR json_extract(m.payload, '$.channel.accountId') = ?)
+    ORDER BY m.id DESC
+    LIMIT 1
+  `).all(input.chatId, input.messageId, input.accountId ?? null, input.accountId ?? null) as any[];
+  const row = rows[0];
+  return row ? rowToMessage(row) : null;
+}
+
+export type MessageClaimResult = { ok: boolean; error?: string; task?: Task; claimExpiresAt?: number };
+
+// The complete claim transition is one writer operation (ADR 0001 §3.4): expiring a stale
+// lease, validating the caller/recipient, claiming the message, and claiming its linked task all
+// share the executor's transaction. Do not split the expiry sweep into an awaited preflight: that
+// would reintroduce the stale-lease/eligibility TOCTOU window this body closes.
+export function claimMessageBody(messageId: number, agentId: string, guard: AgentSessionGuard | undefined, now: number): MessageClaimResult {
+  releaseExpiredClaimsBody(now);
+  const session = validateAgentSession(agentId, guard);
+  if (!session.ok) return { ok: false, error: session.error };
+  const agent = getAgent(agentId);
+  if (!agent) return { ok: false, error: "claiming agent not found" };
+  if (agent.status === "offline") return { ok: false, error: "claiming agent is offline" };
+
+  const msg = getMessage(messageId);
+  if (!msg) return { ok: false, error: "message not found" };
+  if (!msg.claimable) return { ok: false, error: "message is not claimable" };
+  // A same-agent re-claim is allowed (idempotent lease refresh, see claimMessageRow); only a
+  // claim held by a *different* agent blocks (#261).
+  if (msg.claimedBy && msg.claimedBy !== agentId) return { ok: false, error: `already claimed by ${msg.claimedBy}` };
+  // The claimer must actually be a recipient — the same predicate that gates live delivery (bus/sse
+  // push) and poll. Without it an unrelated agent could claim a claimable addressed directly to
+  // someone else, and `pollMessages`/`messageMatchesAgent` then hid it from the rightful recipient,
+  // so the message vanished for its intended owner (#1022 F7). Checked AFTER the claimedBy guard so
+  // a genuine "already claimed" contention still reports that precise reason; a fan-out claimable
+  // (tag:/cap:/broadcast/…) still matches every eligible pool member, and the holder's own re-claim
+  // still matches (claimedBy is null or itself here, so the ownership short-circuit never fires).
+  if (!messageMatchesAgent(msg, agentId, agent)) return { ok: false, error: "message is not addressed to this agent" };
+
+  const expiresAt = now + CLAIM_LEASE_MS;
+  const messageClaim = claimMessageRow(messageId, agentId, now);
+  if (!messageClaim.ok) return messageClaim;
+
+  const taskId = typeof msg.payload?.taskId === "number" && Number.isSafeInteger(msg.payload.taskId)
+    ? msg.payload.taskId
+    : null;
+  if (!taskId) return { ok: true, claimExpiresAt: expiresAt };
+
+  const task = getTask(taskId);
+  if (!task) return { ok: true, claimExpiresAt: expiresAt };
+  // Fence (#834): the claim-lease lane only manages kind='claim' tasks. A deliverable Task
+  // is never lease-managed, so neither the same-agent refresh nor the claim update below may
+  // touch it — even via a stray linked-message payload.
+  if (task.kind !== CLAIM_TASK_KIND) return { ok: true, claimExpiresAt: expiresAt };
+
+  // Same-agent re-claim: this agent already holds the linked task. Refresh the lease in place
+  // rather than re-transitioning (which would throw, since the task is no longer open/blocked).
+  if (task.claimedBy === agentId && ["claimed", "in_progress"].includes(task.status)) {
+    getDb().query(`UPDATE tasks SET claim_expires_at = ?, updated_at = ? WHERE id = ? AND ${claimTaskWhere()} AND claimed_by = ?`)
+      .run(expiresAt, now, taskId, agentId);
+    return { ok: true, task: getTask(taskId)!, claimExpiresAt: expiresAt };
+  }
+
+  if (!["open", "blocked"].includes(task.status)) {
+    throw new ClaimError(`linked task is ${task.status}`);
+  }
+
+  const taskClaim = getDb().query(`
+    UPDATE tasks SET status = 'claimed', claimed_by = ?, claimed_at = ?, claim_expires_at = ?, updated_at = ?
+    WHERE id = ? AND message_id = ? AND ${claimTaskWhere()} AND status IN ('open', 'blocked')
+  `).run(agentId, now, expiresAt, now, taskId, messageId);
+  if (taskClaim.changes === 0) throw new ClaimError("linked task claim race — already claimed");
+
+  insertTaskEvent(taskId, {
+    source: "agent-relay",
+    type: "claimed",
+    severity: task.severity,
+    title: `Task claimed by ${agentId}`,
+    body: `Task claimed by ${agentId}`,
+    metadata: { agentId, messageId },
+  }, now);
+
+  return { ok: true, task: getTask(taskId)!, claimExpiresAt: expiresAt };
+}
+
+export function claimMessage(messageId: number, agentId: string, guard?: AgentSessionGuard): MessageClaimResult {
+  try {
+    return writeTransaction(() => claimMessageBody(messageId, agentId, guard, Date.now()));
+  } catch (e) {
+    if (e instanceof ClaimError) return { ok: false, error: e.message };
+    throw e;
+  }
+}
+
+// Like claimMessageBody, renewal folds expiry cleanup, ownership validation, and both lease updates
+// into the one writer transaction. This matters when a lease crosses its deadline while the request
+// is queued: a reader preflight followed by a writer hop could otherwise renew the wrong owner.
+export function renewMessageClaimBody(messageId: number, agentId: string, guard: AgentSessionGuard | undefined, now: number): MessageClaimResult {
+  releaseExpiredClaimsBody(now);
+  const session = validateAgentSession(agentId, guard);
+  if (!session.ok) return { ok: false, error: session.error };
+  const agent = getAgent(agentId);
+  if (!agent) return { ok: false, error: "claiming agent not found" };
+  if (agent.status === "offline") return { ok: false, error: "claiming agent is offline" };
+  const msg = getMessage(messageId);
+  if (!msg) return { ok: false, error: "message not found" };
+  if (!msg.claimable) return { ok: false, error: "message is not claimable" };
+  if (msg.claimedBy !== agentId) return { ok: false, error: msg.claimedBy ? `claimed by ${msg.claimedBy}` : "message is not claimed" };
+
+  const expiresAt = now + CLAIM_LEASE_MS;
+  let task: Task | undefined;
+  getDb().query("UPDATE messages SET claim_expires_at = ? WHERE id = ? AND claimed_by = ?").run(expiresAt, messageId, agentId);
+  const taskId = typeof msg.payload?.taskId === "number" && Number.isSafeInteger(msg.payload.taskId)
+    ? msg.payload.taskId
+    : null;
+  if (taskId) {
+    // Fenced to the claim lane (#834): never refresh a deliverable Task's (non-existent) lease.
+    getDb().query(`UPDATE tasks SET claim_expires_at = ?, updated_at = ? WHERE id = ? AND ${claimTaskWhere()} AND claimed_by = ?`).run(expiresAt, now, taskId, agentId);
+    task = getTask(taskId) ?? undefined;
+  }
+  return { ok: true, task, claimExpiresAt: expiresAt };
+}
+
+export function renewMessageClaim(messageId: number, agentId: string, guard?: AgentSessionGuard): MessageClaimResult { return writeTransaction(() => renewMessageClaimBody(messageId, agentId, guard, Date.now())); }