@humwick/server 0.0.0-stage → 0.130.1

package/src/db/notification-subscriptions.ts

@@ -0,0 +1,282 @@
+import { randomUUID } from "node:crypto";
+import { isRecord } from "@humwick/sdk";
+import { DEFAULT_TTL_MS, type NotificationScope, type NotificationType } from "../notification-types";
+import type { AgentCard } from "../types";
+import { parseJson } from "../utils";
+import { getDb, ValidationError } from "./connection";
+
+export const CHILD_STREAMS = ["responses", "toolCalls", "reasoning", "narrative"] as const;
+const CONFIGURABLE_CHILD_STREAMS = ["toolCalls", "reasoning", "narrative"] as const;
+export type ChildStream = (typeof CHILD_STREAMS)[number];
+export type ConfigurableChildStream = (typeof CONFIGURABLE_CHILD_STREAMS)[number];
+type ChildStreamSubscriptionType = `child_stream.${ConfigurableChildStream}`;
+
+const CHILD_STREAM_SUBSCRIPTION_TYPES = CONFIGURABLE_CHILD_STREAMS.map(
+  (stream) => `child_stream.${stream}` as ChildStreamSubscriptionType,
+);
+export const NOTIFICATION_SUBSCRIPTION_TYPES = [
+  "*",
+  ...Object.keys(DEFAULT_TTL_MS),
+  ...CHILD_STREAM_SUBSCRIPTION_TYPES,
+] as Array<NotificationSubscriptionType>;
+export const NOTIFICATION_SUBSCRIPTION_MODES = ["opt_in", "opt_out", "mute"] as const;
+
+type NotificationSubscriptionType = NotificationType | "*" | ChildStreamSubscriptionType;
+export type NotificationSubscriptionMode = (typeof NOTIFICATION_SUBSCRIPTION_MODES)[number];
+type SubscriptionRuleDecision = "deliver" | "suppress" | "abstain";
+interface SubscriptionRuleContext {
+  type: NotificationType;
+  scope: NotificationScope;
+  now: number;
+}
+
+interface NotificationSubscription {
+  id: string;
+  agentId: string;
+  type: NotificationSubscriptionType;
+  mode: NotificationSubscriptionMode;
+  scopeMatch: Partial<NotificationScope> | null;
+  createdAt: number;
+}
+
+interface NotificationSubscriptionRow {
+  id: string;
+  agent_id: string;
+  type: string;
+  mode: string;
+  scope_match: string | null;
+  created_at: number;
+}
+
+const SCOPE_KEYS = ["author", "agentId", "parent", "teamId", "planId", "taskId", "transition", "landKey", "repoRoot", "repository", "branch", "workspaceId", "paths"] as const;
+
+export function addSubscription(input: {
+  agentId: string;
+  type: NotificationSubscriptionType;
+  mode: NotificationSubscriptionMode;
+  scopeMatch?: Partial<NotificationScope> | null;
+  now?: number;
+}): NotificationSubscription {
+  const agentId = cleanAgentId(input.agentId);
+  const type = cleanSubscriptionType(input.type);
+  const mode = cleanSubscriptionMode(input.mode);
+  const scopeMatch = normalizeScopeMatch(input.scopeMatch);
+  const now = input.now ?? Date.now();
+
+  getDb().query(`
+    DELETE FROM notification_subscriptions
+    WHERE agent_id = ? AND type = ? AND mode = ? AND coalesce(scope_match, '') = coalesce(?, '')
+  `).run(agentId, type, mode, scopeMatch);
+
+  const id = `nsub_${randomUUID()}`;
+  getDb().query(`
+    INSERT INTO notification_subscriptions (id, agent_id, type, mode, scope_match, created_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(id, agentId, type, mode, scopeMatch, now);
+
+  return getSubscription(id)!;
+}
+
+export function removeSubscription(input: {
+  agentId: string;
+  id?: string;
+  type?: NotificationSubscriptionType;
+  mode?: NotificationSubscriptionMode;
+  scopeMatch?: Partial<NotificationScope> | null;
+}): number {
+  const agentId = cleanAgentId(input.agentId);
+  const conditions = ["agent_id = ?"];
+  const params: any[] = [agentId];
+
+  if (input.id) {
+    conditions.push("id = ?");
+    params.push(input.id);
+  }
+  if (input.type) {
+    conditions.push("type = ?");
+    params.push(cleanSubscriptionType(input.type));
+  }
+  if (input.mode) {
+    conditions.push("mode = ?");
+    params.push(cleanSubscriptionMode(input.mode));
+  }
+  if (Object.prototype.hasOwnProperty.call(input, "scopeMatch")) {
+    conditions.push("coalesce(scope_match, '') = coalesce(?, '')");
+    params.push(normalizeScopeMatch(input.scopeMatch));
+  }
+  if (conditions.length === 1) throw new ValidationError("id or type required");
+
+  return getDb().query(`DELETE FROM notification_subscriptions WHERE ${conditions.join(" AND ")}`).run(...params).changes;
+}
+
+export function removeSubscriptionsForAgent(agentId: string): number {
+  return getDb()
+    .query("DELETE FROM notification_subscriptions WHERE agent_id = ?")
+    .run(cleanAgentId(agentId))
+    .changes;
+}
+
+export function removeSubscriptionsForTask(taskId: number): number {
+  if (!Number.isSafeInteger(taskId) || taskId <= 0) throw new ValidationError("taskId must be a positive integer");
+  return getDb()
+    .query("DELETE FROM notification_subscriptions WHERE json_extract(scope_match, '$.taskId') = ?")
+    .run(String(taskId))
+    .changes;
+}
+
+export function listSubscriptions(agentId: string): NotificationSubscription[] {
+  const rows = getDb().query(`
+    SELECT * FROM notification_subscriptions
+    WHERE agent_id = ?
+    ORDER BY created_at ASC, id ASC
+  `).all(cleanAgentId(agentId)) as NotificationSubscriptionRow[];
+  return rows.map(rowToSubscription);
+}
+
+export function subscriptionDecisionFor(agent: AgentCard, ctx: SubscriptionRuleContext): SubscriptionRuleDecision {
+  const rows = getDb().query(`
+    SELECT * FROM notification_subscriptions
+    WHERE agent_id = ? AND (type = ? OR type = '*')
+    ORDER BY created_at ASC, id ASC
+  `).all(agent.id, ctx.type) as NotificationSubscriptionRow[];
+
+  let decision: SubscriptionRuleDecision = "abstain";
+  for (const row of rows) {
+    const subscription = rowToSubscription(row);
+    if (!scopeMatches(subscription.scopeMatch, ctx.scope)) continue;
+    decision = subscription.mode === "opt_in" ? "deliver" : "suppress";
+  }
+  return decision;
+}
+
+export function optedInNotificationRecipients(type: NotificationType, scope: NotificationScope): string[] {
+  const rows = getDb().query(`
+    SELECT * FROM notification_subscriptions WHERE type = ? OR type = '*'
+    ORDER BY created_at ASC, id ASC
+  `).all(type) as NotificationSubscriptionRow[];
+  const decisions = new Map<string, boolean>();
+  for (const row of rows) {
+    const subscription = rowToSubscription(row);
+    if (scopeMatches(subscription.scopeMatch, scope)) decisions.set(row.agent_id, row.mode === "opt_in");
+  }
+  return [...decisions].filter(([, deliver]) => deliver).map(([agentId]) => agentId);
+}
+
+export function childStreamSubscriptionType(stream: ConfigurableChildStream): ChildStreamSubscriptionType {
+  return `child_stream.${stream}`;
+}
+
+export function childStreamFromSubscriptionType(type: NotificationSubscriptionType): ConfigurableChildStream | null {
+  if (!type.startsWith("child_stream.")) return null;
+  const stream = type.slice("child_stream.".length);
+  return CONFIGURABLE_CHILD_STREAMS.includes(stream as ConfigurableChildStream)
+    ? stream as ConfigurableChildStream
+    : null;
+}
+
+export function cleanChildStream(value: unknown): ChildStream {
+  if (typeof value !== "string" || !CHILD_STREAMS.includes(value as ChildStream)) {
+    throw new ValidationError(`stream must be one of: ${CHILD_STREAMS.join(", ")}`);
+  }
+  return value as ChildStream;
+}
+
+export function childStreamSubscribed(input: {
+  parentId: string;
+  child: Pick<AgentCard, "id" | "teamId">;
+  stream: ChildStream;
+}): boolean {
+  if (input.stream === "responses") return true;
+  const parentId = cleanAgentId(input.parentId);
+  const type = childStreamSubscriptionType(input.stream);
+  const scope: NotificationScope = {
+    parent: parentId,
+    agentId: input.child.id,
+    ...(input.child.teamId ? { teamId: input.child.teamId } : {}),
+  };
+  const rows = getDb().query(`
+    SELECT * FROM notification_subscriptions
+    WHERE agent_id = ? AND type = ?
+    ORDER BY created_at ASC, id ASC
+  `).all(parentId, type) as NotificationSubscriptionRow[];
+
+  let subscribed = false;
+  for (const row of rows) {
+    const subscription = rowToSubscription(row);
+    if (!scopeMatches(subscription.scopeMatch, scope)) continue;
+    subscribed = subscription.mode === "opt_in";
+  }
+  return subscribed;
+}
+
+function getSubscription(id: string): NotificationSubscription | null {
+  const row = getDb().query("SELECT * FROM notification_subscriptions WHERE id = ?").get(id) as NotificationSubscriptionRow | undefined;
+  return row ? rowToSubscription(row) : null;
+}
+
+export function cleanSubscriptionType(value: unknown): NotificationSubscriptionType {
+  if (typeof value !== "string" || !NOTIFICATION_SUBSCRIPTION_TYPES.includes(value as NotificationSubscriptionType)) {
+    throw new ValidationError(`type must be one of: ${NOTIFICATION_SUBSCRIPTION_TYPES.join(", ")}`);
+  }
+  return value as NotificationSubscriptionType;
+}
+
+export function cleanSubscriptionMode(value: unknown): NotificationSubscriptionMode {
+  if (typeof value !== "string" || !NOTIFICATION_SUBSCRIPTION_MODES.includes(value as NotificationSubscriptionMode)) {
+    throw new ValidationError(`mode must be one of: ${NOTIFICATION_SUBSCRIPTION_MODES.join(", ")}`);
+  }
+  return value as NotificationSubscriptionMode;
+}
+
+function cleanAgentId(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError("agentId required");
+  return value.trim();
+}
+
+function normalizeScopeMatch(scope: Partial<NotificationScope> | null | undefined): string | null {
+  if (scope === undefined || scope === null) return null;
+  if (!isRecord(scope)) throw new ValidationError("scope must be an object");
+  const normalized: Record<string, unknown> = {};
+  for (const key of SCOPE_KEYS) {
+    const value = scope[key];
+    if (value === undefined || value === null) continue;
+    if (key === "paths") {
+      if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new ValidationError("scope.paths must be an array of strings");
+      }
+      const paths = [...new Set(value.map((item) => item.trim()).filter(Boolean))].sort();
+      if (paths.length) normalized.paths = paths;
+      continue;
+    }
+    if (typeof value !== "string" || !value.trim()) throw new ValidationError(`scope.${key} must be a string`);
+    normalized[key] = value.trim();
+  }
+  return Object.keys(normalized).length ? JSON.stringify(normalized) : null;
+}
+
+function rowToSubscription(row: NotificationSubscriptionRow): NotificationSubscription {
+  return {
+    id: row.id,
+    agentId: row.agent_id,
+    type: cleanSubscriptionType(row.type),
+    mode: cleanSubscriptionMode(row.mode),
+    scopeMatch: parseJson<Partial<NotificationScope> | null>(row.scope_match, null),
+    createdAt: row.created_at,
+  };
+}
+
+function scopeMatches(match: Partial<NotificationScope> | null, scope: NotificationScope): boolean {
+  if (!match) return true;
+  const actual = scope as Record<string, unknown>;
+  for (const [key, expected] of Object.entries(match)) {
+    const value = actual[key];
+    if (Array.isArray(expected)) {
+      if (!Array.isArray(value)) return false;
+      const actualSet = new Set(value.filter((item): item is string => typeof item === "string"));
+      if (!expected.every((item) => actualSet.has(item))) return false;
+      continue;
+    }
+    if (value !== expected) return false;
+  }
+  return true;
+}

package/src/db/on-loop-write-transaction.ts

@@ -0,0 +1,34 @@
+import { getDb, isSqliteBusyError, writeTransaction } from "./connection";
+
+/** #3286 — wait for BEGIN asynchronously; never replay a body or a possibly committed write. */
+export async function onLoopWriteTransaction<T>(
+  body: () => T,
+  capture: (attempt: () => T) => T,
+  timeoutMs: number,
+  signal: AbortSignal,
+): Promise<T> {
+  const deadline = performance.now() + timeoutMs;
+  for (;;) {
+    signal.throwIfAborted();
+    let entered = false;
+    try {
+      return capture(() => {
+        const db = getDb();
+        const prior = (db.query("PRAGMA busy_timeout").get() as { timeout: number }).timeout;
+        db.run("PRAGMA busy_timeout = 0");
+        try {
+          return writeTransaction(() => {
+            entered = true;
+            db.run(`PRAGMA busy_timeout = ${prior}`);
+            return body();
+          });
+        } finally {
+          db.run(`PRAGMA busy_timeout = ${prior}`);
+        }
+      });
+    } catch (error) {
+      if (entered || !isSqliteBusyError(error) || performance.now() >= deadline) throw error;
+      await Bun.sleep(15);
+    }
+  }
+}

package/src/db/operator-actions-schema.ts

@@ -0,0 +1,10 @@
+import { getDb } from "./connection";
+import { OPERATOR_DECISIONS_SCHEMA, migrateOperatorDecisionsSchema } from "./operator-decisions";
+import { MACOS_PRIVACY_SCHEMA } from "./macos-privacy";
+
+// Actions and their host prompt correlation must be installed together (#3564).
+export const OPERATOR_ACTIONS_SCHEMA = `${OPERATOR_DECISIONS_SCHEMA}; ${MACOS_PRIVACY_SCHEMA}`;
+export function migrateOperatorActionsSchema(): void {
+  migrateOperatorDecisionsSchema();
+  getDb().run(MACOS_PRIVACY_SCHEMA);
+}

package/src/db/operator-decisions.ts

@@ -0,0 +1,180 @@
+import { getDb } from "./connection.ts";
+import { VAULT_FORM_TTL_MS, type OperatorDecision, type OperatorDecisionAnswers, type OperatorDecisionKind, type OperatorDecisionQuestion, type OperatorDecisionStatus } from "../types";
+
+// #2967 — added after #2885 shipped; upgraded DBs gain it through migrateOperatorDecisionsSchema.
+const KIND_COLUMN = "kind TEXT NOT NULL DEFAULT 'decision' CHECK (kind IN ('decision', 'action'))";
+
+// #2885 — decisions belong to a team's coordinator ROLE; `filed_by` is audit only.
+// Shared by the fresh-DB catalog (schema.ts) and upgraded DBs (migrations.ts).
+export const OPERATOR_DECISIONS_SCHEMA = `CREATE TABLE IF NOT EXISTS operator_decisions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_id TEXT NOT NULL,
+  project_id TEXT,
+  ${KIND_COLUMN},
+  title TEXT NOT NULL,
+  context TEXT,
+  links TEXT NOT NULL DEFAULT '[]',
+  time_critical INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'answered', 'withdrawn')),
+  questions TEXT NOT NULL,
+  workflow TEXT,
+  answers TEXT,
+  note TEXT,
+  filed_by TEXT NOT NULL,
+  answered_by TEXT,
+  answer_message_id INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  answered_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_operator_decisions_status_team ON operator_decisions(status, team_id)`;
+
+export function migrateOperatorDecisionsSchema(): void {
+  getDb().run(OPERATOR_DECISIONS_SCHEMA);
+  const columns = getDb().query("PRAGMA table_info(operator_decisions)").all() as Array<{ name: string }>;
+  if (!columns.some(column => column.name === "workflow")) getDb().run("ALTER TABLE operator_decisions ADD COLUMN workflow TEXT");
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_operator_decisions_workflow_effect ON operator_decisions(json_extract(workflow, '$.effectId')) WHERE workflow IS NOT NULL");
+  if (!columns.some((column) => column.name === "kind")) getDb().run(`ALTER TABLE operator_decisions ADD COLUMN ${KIND_COLUMN}`);
+}
+
+interface DecisionRow {
+  id: number;
+  team_id: string;
+  project_id: string | null;
+  kind: OperatorDecisionKind;
+  title: string;
+  context: string | null;
+  links: string;
+  time_critical: number;
+  status: OperatorDecisionStatus;
+  questions: string;
+  workflow: string | null;
+  answers: string | null;
+  note: string | null;
+  filed_by: string;
+  answered_by: string | null;
+  answer_message_id: number | null;
+  created_at: number;
+  updated_at: number;
+  answered_at: number | null;
+  coordinator_id: string | null;
+  principal_user_id: string;
+}
+
+// A vault request belongs to the chat of the coordinator of the team its filer is on (#3553).
+const SELECT = `SELECT d.*, COALESCE(o.owner_user_id, json_extract(a.ownership, '$.owner_user_id'), 'default') AS principal_user_id
+  FROM (SELECT d.*, CASE
+    WHEN d.team_id = 'vault:global' THEN (SELECT vt.coordinator_id FROM agents va JOIN teams vt ON vt.id = va.team_id AND vt.status = 'active' WHERE va.id = d.filed_by)
+    WHEN t.status = 'active' THEN t.coordinator_id END AS coordinator_id
+  FROM operator_decisions d LEFT JOIN teams t ON t.id = d.team_id) d
+  LEFT JOIN agent_ownership o ON o.agent_id = COALESCE(d.coordinator_id, d.filed_by)
+  LEFT JOIN agent_identity_archive a ON a.id = COALESCE(d.coordinator_id, d.filed_by)
+    AND NOT EXISTS (SELECT 1 FROM agents live WHERE live.id = a.id)`;
+
+interface DecisionReadOptions { includeVaultForm?: boolean }
+
+function rowToDecision(row: DecisionRow, options: DecisionReadOptions = {}): OperatorDecision {
+  // Vault links are write capabilities. Agent-facing reads are safe by default, including MCP.
+  const vault = row.team_id === "vault:global";
+  const links = vault && !options.includeVaultForm ? [] : JSON.parse(row.links) as string[];
+  return {
+    id: row.id,
+    ...(row.workflow ? { workflow: JSON.parse(row.workflow) } : {}),
+    teamId: row.team_id,
+    ...(row.project_id ? { projectId: row.project_id } : {}),
+    kind: row.kind,
+    title: row.title,
+    ...(row.context ? { context: row.context } : {}),
+    links,
+    ...(vault && options.includeVaultForm ? { formUrl: links[0] } : {}),
+    ...(vault ? { expiresAt: row.created_at + VAULT_FORM_TTL_MS } : {}),
+    timeCritical: row.time_critical === 1,
+    status: row.status,
+    questions: JSON.parse(row.questions) as OperatorDecisionQuestion[],
+    ...(row.answers ? { answers: JSON.parse(row.answers) as OperatorDecisionAnswers } : {}),
+    ...(row.note ? { note: row.note } : {}),
+    filedBy: row.filed_by,
+    ...(row.answered_by ? { answeredBy: row.answered_by } : {}),
+    ...(row.answer_message_id !== null ? { answerMessageId: row.answer_message_id } : {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    ...(row.answered_at !== null ? { answeredAt: row.answered_at } : {}),
+    coordinatorId: row.coordinator_id,
+    principalUserId: row.principal_user_id,
+  };
+}
+
+export interface OperatorDecisionContent {
+  /** Fixed at filing; an update never changes it. */
+  kind: OperatorDecisionKind;
+  title: string;
+  context?: string;
+  links: string[];
+  timeCritical: boolean;
+  questions: OperatorDecisionQuestion[];
+}
+
+export function insertOperatorDecision(input: OperatorDecisionContent & { teamId: string; projectId?: string; filedBy: string; now: number; workflow?: OperatorDecision["workflow"] }): OperatorDecision {
+  const row = getDb().query(`
+    INSERT INTO operator_decisions (team_id, project_id, kind, title, context, links, time_critical, questions, filed_by, created_at, updated_at, workflow)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id
+  `).get(input.teamId, input.projectId ?? null, input.kind, input.title, input.context ?? null, JSON.stringify(input.links),
+    input.timeCritical ? 1 : 0, JSON.stringify(input.questions), input.filedBy, input.now, input.now, input.workflow ? JSON.stringify(input.workflow) : null) as { id: number };
+  return getOperatorDecision(row.id)!;
+}
+
+export function getOperatorDecision(id: number, options: DecisionReadOptions = {}): OperatorDecision | null {
+  const row = getDb().query(`${SELECT} WHERE d.id = ?`).get(id) as DecisionRow | null;
+  return row ? rowToDecision(row, options) : null;
+}
+
+/** Open decisions wait longest-first behind the time-critical ones; history is newest-first. */
+export function listOperatorDecisions(filter: { status?: OperatorDecisionStatus; teamId?: string; principalUserId?: string; limit: number }, options: DecisionReadOptions = {}): OperatorDecision[] {
+  const where: string[] = [];
+  const args: Array<string | number> = [];
+  if (filter.status) { where.push("d.status = ?"); args.push(filter.status); }
+  if (filter.teamId) { where.push("d.team_id = ?"); args.push(filter.teamId); }
+  if (filter.principalUserId) { where.push("principal_user_id = ?"); args.push(filter.principalUserId); }
+  const order = filter.status === "open" ? "d.time_critical DESC, d.created_at ASC, d.id ASC" : "d.updated_at DESC, d.id DESC";
+  const rows = getDb().query(`${SELECT} ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY ${order} LIMIT ?`)
+    .all(...args, filter.limit) as DecisionRow[];
+  return rows.map(row => rowToDecision(row, options));
+}
+
+/** Replace an OPEN decision's content. False when it is no longer open. */
+export function updateOpenOperatorDecision(id: number, content: OperatorDecisionContent, now: number): boolean {
+  return getDb().query(`
+    UPDATE operator_decisions SET title = ?, context = ?, links = ?, time_critical = ?, questions = ?, updated_at = ?
+    WHERE id = ? AND status = 'open'
+  `).run(content.title, content.context ?? null, JSON.stringify(content.links), content.timeCritical ? 1 : 0,
+    JSON.stringify(content.questions), now, id).changes > 0;
+}
+
+/** Open vault requests for one name+scope (`title`), with the team of the agent that filed each. */
+export function openVaultDecisionsByTitle(title: string): Array<{ id: number; filedBy: string; teamId: string | null }> {
+  return (getDb().query(`SELECT d.id, d.filed_by, a.team_id FROM operator_decisions d LEFT JOIN agents a ON a.id = d.filed_by
+    WHERE d.team_id = 'vault:global' AND d.status = 'open' AND d.title = ?`).all(title) as Array<{ id: number; filed_by: string; team_id: string | null }>)
+    .map(row => ({ id: row.id, filedBy: row.filed_by, teamId: row.team_id }));
+}
+
+export function withdrawOpenOperatorDecision(id: number, now: number): boolean {
+  return getDb().query("UPDATE operator_decisions SET status = 'withdrawn', updated_at = ? WHERE id = ? AND status = 'open'")
+    .run(now, id).changes > 0;
+}
+
+/** The open→answered compare-and-swap. False when someone else answered or it was withdrawn. */
+export function answerOpenOperatorDecision(id: number, input: { answers: OperatorDecisionAnswers; note?: string; answeredBy: string; now: number }): boolean {
+  return getDb().query(`
+    UPDATE operator_decisions SET status = 'answered', answers = ?, note = ?, answered_by = ?, answered_at = ?, updated_at = ?
+    WHERE id = ? AND status = 'open'
+  `).run(JSON.stringify(input.answers), input.note ?? null, input.answeredBy, input.now, input.now, id).changes > 0;
+}
+
+export function setOperatorDecisionAnswerMessage(id: number, messageId: number): void {
+  getDb().query("UPDATE operator_decisions SET answer_message_id = ? WHERE id = ?").run(messageId, id);
+}
+
+export function getWorkflowOperatorDecision(effectId: string): OperatorDecision | null {
+  const row = getDb().query(`${SELECT} WHERE json_extract(d.workflow, '$.effectId') = ?`).get(effectId) as DecisionRow | null;
+  return row ? rowToDecision(row) : null;
+}

package/src/db/orchestrators-async.ts

@@ -0,0 +1,61 @@
+// Async orchestrator facades. Kept outside the domain module to preserve the one-way
+// gateway -> registry -> domain dependency graph.
+import { getGateway } from "./gateway.ts";
+import { coalesceLifecycleWrite } from "./lifecycle-write-window.ts";
+import { nextLifecycleSeq } from "./lifecycle-seq.ts";
+import { evictPendingPresence } from "./presence-buffer.ts";
+import type { getOrchestrator, listOrchestrators, OrchestratorRosterResult, registerOrchestratorOp, upsertOrchestrator } from "./orchestrators.ts";
+import { finishAgentUpsertAsync } from "./agents-async.ts";
+import { emitWorkspaceUpsert } from "./workspaces.ts";
+import type { ManagedAgent, OrchestratorRuntimeInput, OrchestratorUpgradeState, QueuedSpawn } from "../types.ts";
+import { STALE_TTL_MS } from "../config.ts";
+
+export async function upsertOrchestratorAsync(input: Parameters<typeof upsertOrchestrator>[0]): Promise<ReturnType<typeof upsertOrchestrator>> {
+  const seq = nextLifecycleSeq(); // before the await, per the ordinal-timing rule (lifecycle-seq.ts)
+  const { orchestrator, agent, contextState } = await getGateway().write("orchestrators.register", { input, seq }, { critical: true }) as unknown as ReturnType<typeof registerOrchestratorOp>;
+  await finishAgentUpsertAsync(agent.id, { agent, contextState });
+  return orchestrator;
+}
+
+export function getOrchestratorAsync(id: string): Promise<ReturnType<typeof getOrchestrator>> {
+  return getGateway().read("orchestrators.get", { id }) as Promise<ReturnType<typeof getOrchestrator>>;
+}
+
+export function listOrchestratorsAsync(): Promise<ReturnType<typeof listOrchestrators>> {
+  return getGateway().read("orchestrators.list", undefined) as Promise<ReturnType<typeof listOrchestrators>>;
+}
+/**
+ * #2111 — the ONE op where last-writer-wins collapsing is safe, and it is the storm's 4th-largest
+ * on-loop blocker (74 blocks in the bad window). A heartbeat is pure idempotent liveness: two beats
+ * for the same orchestrator inside one 25ms window are indistinguishable to every caller (they only
+ * null-check the returned row), so the later beat's runtime wins and both callers settle on it.
+ */
+export function orchestratorHeartbeatAsync(id: string, runtime: OrchestratorRuntimeInput = {}): Promise<ReturnType<typeof getOrchestrator>> {
+  // #2111 — allocated synchronously before anything is awaited, per the ordinal-timing rule at the
+  // top of setStatusAsync: an ordinal taken after an await no longer means "when this was submitted".
+  const seq = nextLifecycleSeq();
+  return coalesceLifecycleWrite(
+    "orchestrators.heartbeat",
+    { id, runtime, seq },
+    { dedupeKey: id },
+  ) as Promise<ReturnType<typeof getOrchestrator>>;
+}
+/** #1870 S5 — commits the roster report off-loop, then emits its workspace changes on main. Acks
+ *  resolve in FIFO order, so callers that act right after the await still act in submission order. */
+export async function reportOrchestratorRosterAsync(id: string, agents: ManagedAgent[], queuedSpawns?: QueuedSpawn[]): Promise<OrchestratorRosterResult> {
+  const result = await getGateway().write("orchestrators.reportRoster", { id, agents, ...(queuedSpawns ? { queuedSpawns } : {}) }, { critical: true }) as unknown as OrchestratorRosterResult;
+  for (const workspace of result.workspaces) emitWorkspaceUpsert(workspace);
+  return result;
+}
+export function setOrchestratorUpgradeStateAsync(id: string, state: OrchestratorUpgradeState | null): Promise<ReturnType<typeof getOrchestrator>> {
+  return getGateway().write("orchestrators.upgrade.set", { id, state }) as Promise<ReturnType<typeof getOrchestrator>>;
+}
+export async function reapStaleOrchestratorsAsync(now: number = Date.now()): Promise<string[]> {
+  // #2111 — allocated before the await, per the ordinal-timing rule (lifecycle-seq.ts).
+  const reapSeq = nextLifecycleSeq();
+  const cutoff = now - STALE_TTL_MS;
+  if (!await getGateway().read("orchestrators.hasStale", { cutoff })) return [];
+  const stale = await getGateway().write("orchestrators.reap", { cutoff, seq: reapSeq }) as unknown as Array<{ id: string; agentId: string }>;
+  for (const row of stale) evictPendingPresence(row.agentId);
+  return stale.map((row) => row.id);
+}

package/src/db/orchestrators-read-ops.ts

@@ -0,0 +1,7 @@
+// Orchestrator domain reader operations (ADR 0001 §3.3).
+import { getOrchestrator, listOrchestrators } from "./orchestrators.ts";
+
+export const ORCHESTRATORS_READ_OPS = {
+  "orchestrators.get": (args: { id: string }) => getOrchestrator(args.id),
+  "orchestrators.list": () => listOrchestrators(),
+};

package/src/db/orchestrators-write-ops.ts

@@ -0,0 +1,58 @@
+// Orchestrator writer operations. The heartbeat's meta read/merge/update is one writer op, so a
+// concurrent heartbeat cannot lose fields through an await gap (A/B).
+import {
+  orchestratorHeartbeatInternal,
+  reapStaleOrchestratorsInternal,
+  registerOrchestratorOp,
+  reportOrchestratorRosterRow,
+  setOrchestratorUpgradeState,
+  upsertOrchestrator,
+} from "./orchestrators.ts";
+import { heartbeat } from "./agents.ts";
+import type { ManagedAgent, OrchestratorRuntimeInput, OrchestratorUpgradeState, QueuedSpawn } from "../types.ts";
+import { STALE_TTL_MS } from "../config.ts";
+import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
+
+export const ORCHESTRATORS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
+  "orchestrators.register": {
+    offLoop: true,
+    idempotent: true,
+    // The agent row's follow-ups (presence eviction, pool binding, steward election) run in the facade.
+    fn: (a: { input: Parameters<typeof upsertOrchestrator>[0]; seq: number }, ctx) => registerOrchestratorOp(a.input, ctx.now, a.seq),
+  },
+  "orchestrators.heartbeat": {
+    offLoop: true,
+    idempotent: true,
+    fn: (a: { id: string; runtime: OrchestratorRuntimeInput; seq?: number }, ctx) => {
+      const orchestrator = orchestratorHeartbeatInternal(a.id, a.runtime, ctx.now);
+      // Preserve the sync facade's paired liveness update. The orchestrator is only routable while
+      // its synthetic `orchestrator-<id>` agent is fresh, so both rows advance in this writer op.
+      //
+      // #2111 review BLOCKER 1 — that paired update carries `heartbeat()`'s offline/stale → idle
+      // RESURRECTION case, so a beat the coalescing window deferred could revive an orchestrator agent
+      // a newer synchronous transition had just marked offline. `seq` (taken at the facade, before
+      // buffering) fences it: the beat applies only while no later-submitted lifecycle write has
+      // landed on that row.
+      if (orchestrator) heartbeat(orchestrator.agentId, undefined, undefined, ctx.now, a.seq);
+      return orchestrator;
+    },
+  },
+  // #1870 S5 — the roster report's workspace upserts, steward election and roster write are one
+  // off-loop op. It writes absolute, diffed state, so a replay converges; the route emits the
+  // returned workspace effects after the ack.
+  "orchestrators.reportRoster": {
+    offLoop: true,
+    idempotent: true,
+    fn: (a: { id: string; agents: ManagedAgent[]; queuedSpawns?: QueuedSpawn[] }, ctx) => reportOrchestratorRosterRow(a.id, a.agents, a.queuedSpawns, ctx.now),
+  },
+  "orchestrators.upgrade.set": {
+    offLoop: true,
+    idempotent: true,
+    fn: (a: { id: string; state: OrchestratorUpgradeState | null }) => setOrchestratorUpgradeState(a.id, a.state),
+  },
+  "orchestrators.reap": {
+    offLoop: true,
+    idempotent: true,
+    fn: (a: { cutoff: number; seq: number }, ctx) => reapStaleOrchestratorsInternal(ctx.now - STALE_TTL_MS, a.seq),
+  },
+});