@humwick/server 0.0.0-stage → 0.130.0

package/src/db/migrations.ts

@@ -0,0 +1,1761 @@
+import { PLAN_DISPATCH_SCHEMA_SQL } from "./plan-dispatch-schema";
+import { PLAN_IMPORT_SCHEMA_SQL } from "./plan-import-schema";
+import { ensureDurablePayloadSchema } from "./durable-payloads"; import { redactProviderConfigHistory } from "./provider-config-history"; import { retireMemoryStorage } from "./memory-retirement";
+import { migrateProjectRootHosts } from "./project-root-schema";
+import { migrateBrokerMemories } from "./broker-memory-migration";
+import { installProjectEntrySearch } from "./project-entry-search";
+import { LONG_RUNNING_WORK_SCHEMA } from "./long-running-work";
+import { CI_GATE_BACKFILL_SCHEMA, repairRerunGateTimings } from "./ci-gate-runs.ts";
+import { ensureCiShaObservationsSchema } from "./ci-sha-observations-schema.ts";
+import { AGENT_GATE_RUNS_SCHEMA, ensureAgentGateCommandSchema } from "./agent-gate-runs.ts";
+import { ensureSpawnTreeStopSchema } from "./spawn-delegation-state";
+import { CLAUDE_APP_OAUTH_SCHEMA } from "./claude-app-oauth";
+import { ensureVaultTokensSchema } from "./vault-tokens";
+import { ensureVaultHealthSchema } from "./vault-health";
+import { ensureWebToolCallsSchema } from "./web-tool-calls";
+import { ensureArtifactRetentionSchema } from "./artifact-retention";
+import { installAgentIdentityArchive } from "./agent-identity-archive";
+import { ensureIssueAssociationRelationSchema } from "./task-issue-relation";
+import { CLAUDE_API_BUDGET_SCHEMA } from "./claude-api-budget";
+import { backfillLegacyMessages } from "./legacy-message-backfill";
+import { installHistoryDeliverySettlement } from "./history-delivery-settle";
+import { installReplyObligations } from "./reply-obligations";
+import { beginStartupPhase, timeStartupPhase } from "../startup-timing";
+import { Database } from "bun:sqlite";
+import { AGENT_EXIT_REPORT_SCHEMA } from "./agent-exit-report";
+import { CONTEXT_RESET_SCHEMA } from "./context-reset-carry";
+import { TASK_TOKEN_TOTALS_SCHEMA } from "./token-usage";
+import { SHIPPING_STATS_SCHEMA } from "./shipping-stats-schema";
+import { migrateOperatorActionsSchema } from "./operator-actions-schema";
+import { SELF_EFFORT_PERMISSIONS_SCHEMA } from "./self-effort-permissions";
+import { AGENT_EFFORT_STATE_SCHEMA, importLegacyEffortCommands } from "./agent-effort-state";
+import { randomUUID } from "node:crypto";
+import { isRecord, stringValue, isMechanicalMessageKind } from "@humwick/sdk";
+import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
+import { parseJson } from "../utils";
+import { isLiveIsolatedWorkspace } from "../workspace-phase";
+import {
+  CONTRACT_REQUIREMENTS,
+  contractCompatibility,
+  parseRuntimeCapabilities,
+  parseRuntimeContracts,
+  parseRuntimePackage,
+  type RuntimeContracts,
+} from "../contracts";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
+import { matchAgents } from "../agent-ref";
+import { COORDINATOR_PROFILE_NAMES } from "../agent-system-tags";
+import { getDb } from "./connection.ts";
+import { normalizeExistingAgentSpawnRequestIds } from "./spawn-request-id-migration.ts";
+import { ensureUsersSchema, seedDefaultUser } from "./users.ts";
+import { ensureAuthIdentitiesSchema } from "./auth-identities.ts";
+import { ensureUserInvitesSchema } from "./user-invites.ts";
+import { ensureAgentOwnershipSchema, seedDefaultAgentOwnership } from "./agent-ownership.ts";
+import { ensureDriveLeaseSchema } from "./drive-leases.ts";
+import { convertManualJobDisablesToPauses, ensureMaintenanceJobPauseSchema } from "./maintenance-pauses.ts";
+import { dropLegacyContinuationArchiveIndex } from "./continuation-archive-search.ts";
+import { ensureCrashReportsSchema } from "./crash-reports.ts";
+import { migrateVaultSchema } from "./secrets-vault-migration";
+import { ensureBudgetLineageSchema } from "./budget-lineage";
+import { ensureLaunchFactsSchema } from "./launch-facts.ts";
+import { ensureTerminalEventsSchema } from "./terminal-events.ts";
+import { seedBundledProvisioningAssets } from "./provisioning-registry.ts";
+import { seedQaSkills } from "./qa-skill-seed.ts";
+import { seedSharedCallmuxProvisioningAssets } from "./provisioning-callmux.ts";
+import { provisioningAssetsColumnNames, provisioningAssetsNeedsRebuild, rebuildProvisioningAssetsTable } from "./provisioning-assets-migration.ts";
+import { ensureWorkflowJournalSchema } from "./workflow-journal-schema.ts";
+import { ensureKernelEventLogSchema } from "./kernel-event-log-schema.ts";
+import { ensureReviewRefCleanupsSchema } from "./review-ref-cleanups.ts";
+import { installTimerMessageFlipSchema } from "./timer-message-flip.ts";
+import { ensureTimerMessageFireDeadLetterSchema } from "./timer-message-fire-deadletter.ts";
+import { ensureIngestedMemoryIndex, ensureSqlAuditIndexes } from "./sql-audit-indexes.ts";
+import { ensureMaintenanceIndexes } from "./maintenance-indexes.ts";
+import { ensureProviderFlapMessagesIndex } from "./provider-flap-messages.ts";
+import { normalizeReactionEmoji } from "./mappers.ts";
+import { normalizeProviderQuotaAccountKeys } from "./provider-quotas.ts";
+import { projectRootsMissingIssueRepo, projectRootsMissingRemoteUrl, setProjectIssueRepo, setProjectRootRemoteUrl } from "./projects.ts";
+import { mergePhantomWorktreeProjectsAtStartup } from "./project-phantom-merge.ts";
+import { migrateTeamProjectSeats } from "./team-project.ts";
+import { ensureArtifactCreatorAgentColumn } from "./artifacts.ts";
+import { rewriteEmptyToolGroupsToAbsent } from "./tool-groups-empty-migration.ts";
+import { backfillProjectMemoryToolGroup } from "./project-memory-group-migration.ts";
+import { removeLegacyProfileProjectInstructions } from "./profile-legacy-project-instructions-migration.ts";
+import { migrateProfileHostSources } from "./profile-host-sources-migration.ts";
+import { migrateProfileProjectAcks } from "./profile-project-ack-migration.ts";
+import { backfillCustomProfileArtifacts } from "./profile-artifact-backfill-migration.ts";
+import { migrateAgentProfileOverridesToV2 } from "./profile-override-migration.ts";
+import { migrateProfileSlimOnStartup } from "./profile-slim-migration.ts";
+import { ensureProfileNameCaseIndex } from "./profile-name-case-migration.ts";
+import { backfillSpawnRegistrationConfirmedOnce } from "./spawn-registration-confirmed-backfill.ts";
+import { auditHostAliases, backfillHostsFromOrchestrators } from "./hosts-backfill.ts";
+import { remoteUrlFromGitRemote, repoFromGitRemote } from "../services/git-remote.ts";
+import { migrateBlockedTaskBacklog, migrateDeployedTaskBacklog } from "./task-validation.ts";
+import { backfillTaskOwners } from "./task-owner.ts";
+import { migratePlanBlurbsOnStartup } from "./plan-blurb-migration.ts";
+import { ensureLandingPhaseOneSchema } from "./landing-schema.ts";
+import { ensureCommandAgentProfileSchema } from "./command-agent-profiles.ts";
+
+// One-time normalization of legacy reaction rows, run on every open (idempotent).
+function normalizeExistingMessageReactions(): void {
+  const rows = getDb().query("SELECT message_id, actor_id, emoji, created_at, updated_at FROM message_reactions").all() as Array<{
+    message_id: number;
+    actor_id: string;
+    emoji: string;
+    created_at: number;
+    updated_at: number;
+  }>;
+  const migrate = getDb().transaction((items: typeof rows) => {
+    const upsert = 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
+        created_at = min(message_reactions.created_at, excluded.created_at),
+        updated_at = max(message_reactions.updated_at, excluded.updated_at)
+    `);
+    const remove = getDb().query("DELETE FROM message_reactions WHERE message_id = ? AND actor_id = ? AND emoji = ?");
+    for (const row of items) {
+      const normalized = normalizeReactionEmoji(row.emoji);
+      if (normalized === row.emoji) continue;
+      upsert.run(row.message_id, row.actor_id, normalized, row.created_at, row.updated_at);
+      remove.run(row.message_id, row.actor_id, row.emoji);
+    }
+  });
+  migrate(rows);
+}
+
+function backfillProjectIssueRepos(): void {
+  const repaired = new Set<string>();
+  for (const row of projectRootsMissingIssueRepo()) {
+    if (repaired.has(row.projectId)) continue;
+    try {
+      const repo = repoFromGitRemote(row.rootPath);
+      if (!repo) continue;
+      setProjectIssueRepo(row.projectId, repo, { onlyIfNull: true });
+      repaired.add(row.projectId);
+    } catch {
+      // Best-effort startup repair: a missing root or unavailable git must not block Relay.
+    }
+  }
+}
+
+function backfillProjectRootRemoteUrls(): void {
+  for (const row of projectRootsMissingRemoteUrl()) {
+    try {
+      const remoteUrl = remoteUrlFromGitRemote(row.rootPath);
+      if (remoteUrl) setProjectRootRemoteUrl(row.projectId, row.rootPath, remoteUrl, { onlyIfNull: true });
+    } catch {
+      // Best-effort startup repair: a missing root or unavailable git must not block Relay.
+    }
+  }
+}
+
+// Incremental schema migrations + one-shot backfills, applied after the base DDL
+// in initDb(). Ordering matters: each block guards on the current column/table
+// shape, so they must run in historical order. Built-in agent seeding and the
+// read_by backfill live here too — both run unconditionally and idempotently.
+export function applyMigrations(): void {
+  getDb().run(PLAN_IMPORT_SCHEMA_SQL);
+  ensureVaultTokensSchema();
+  ensureVaultHealthSchema();
+  const finishSchema = beginStartupPhase("db.migrations.schema-and-seeds");
+  ensureLandingPhaseOneSchema();
+  ensureCommandAgentProfileSchema(); // #3606 — spawn agentProfile stored once by content hash
+  timeStartupPhase("db.backfill.reactions", normalizeExistingMessageReactions);
+  timeStartupPhase("db.backfill.spawn-request-ids", normalizeExistingAgentSpawnRequestIds);
+
+  // Migrations
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS issue_refs (
+      id TEXT PRIMARY KEY,
+      provider TEXT NOT NULL,
+      repo TEXT NOT NULL,
+      external_key TEXT NOT NULL,
+      url TEXT NOT NULL,
+      title TEXT,
+      status TEXT NOT NULL DEFAULT 'unknown',
+      close_reason TEXT,
+      status_synced_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE(provider, repo, external_key)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_refs_external ON issue_refs(provider, repo, external_key)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_refs_updated ON issue_refs(updated_at DESC)");
+  // #2520 — the GitHub close classification (completed|not_planned) cached beside the status so
+  // plan-node terminal propagation can tell a completed close from a not-planned one. The guarded
+  // ALTER converges databases created before the column existed with the CREATE above.
+  const issueRefCols = getDb().query("PRAGMA table_info(issue_refs)").all() as any[];
+  const issueRefColNames = issueRefCols.map((c: any) => c.name);
+  if (!issueRefColNames.includes("close_reason")) {
+    getDb().run("ALTER TABLE issue_refs ADD COLUMN close_reason TEXT");
+  }
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS issue_associations (
+      issue_ref_id TEXT NOT NULL REFERENCES issue_refs(id) ON DELETE CASCADE,
+      entity_type TEXT NOT NULL CHECK (entity_type IN ('team', 'plan-node', 'epic', 'task')),
+      entity_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (issue_ref_id, entity_type, entity_id)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_associations_entity ON issue_associations(entity_type, entity_id, created_at DESC)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_associations_issue ON issue_associations(issue_ref_id, created_at DESC)");
+  getDb().run(`CREATE TABLE IF NOT EXISTS issue_lifecycle_actions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, issue_ref_id TEXT NOT NULL REFERENCES issue_refs(id) ON DELETE CASCADE,
+    action TEXT NOT NULL CHECK (action IN ('close', 'reopen')), land_key TEXT NOT NULL, workspace_id TEXT, branch TEXT, base_ref TEXT, commit_sha TEXT, commit_subject TEXT,
+    agent_id TEXT, source TEXT, comment TEXT, status TEXT NOT NULL CHECK (status IN ('succeeded', 'failed')),
+    error TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, UNIQUE(issue_ref_id, action, land_key))`);
+  getDb().run(LONG_RUNNING_WORK_SCHEMA);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_lifecycle_commit ON issue_lifecycle_actions(commit_sha, action, status)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_lifecycle_subject ON issue_lifecycle_actions(commit_subject, action, status)");
+
+  const activityCols = getDb().query("PRAGMA table_info(activity_events)").all() as any[];
+  const activityColNames = activityCols.map((c: any) => c.name);
+  if (!activityColNames.includes("issue_ref_id")) {
+    getDb().run("ALTER TABLE activity_events ADD COLUMN issue_ref_id TEXT");
+  }
+  if (!activityColNames.includes("issue_action")) {
+    getDb().run("ALTER TABLE activity_events ADD COLUMN issue_action TEXT");
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_activity_issue ON activity_events(issue_ref_id, created_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_activity_agent_issue ON activity_events(agent_id, issue_ref_id, created_at)"); getDb().run("CREATE INDEX IF NOT EXISTS idx_activity_policy_created ON activity_events(json_extract(metadata, '$.policyName'), created_at DESC, id DESC)");
+
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS workspace_merge_pauses (
+      id TEXT PRIMARY KEY,
+      repo_root TEXT NOT NULL,
+      base_ref TEXT NOT NULL,
+      holder TEXT NOT NULL,
+      reason TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      UNIQUE(repo_root, base_ref)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_workspace_merge_pauses_expires ON workspace_merge_pauses(expires_at)");
+
+  const workspaceCols = getDb().query("PRAGMA table_info(workspaces)").all() as any[];
+  const workspaceColNames = workspaceCols.map((c: any) => c.name);
+  if (!workspaceColNames.includes("orchestrator_id")) {
+    getDb().run("ALTER TABLE workspaces ADD COLUMN orchestrator_id TEXT");
+  }
+  if (!workspaceColNames.includes("landed_at")) {
+    getDb().run("ALTER TABLE workspaces ADD COLUMN landed_at INTEGER");
+  }
+  if (!workspaceColNames.includes("landed_sha")) {
+    getDb().run("ALTER TABLE workspaces ADD COLUMN landed_sha TEXT");
+  }
+  if (!workspaceColNames.includes("land_state")) {
+    getDb().run("ALTER TABLE workspaces ADD COLUMN land_state TEXT NOT NULL DEFAULT 'no-changes'");
+    getDb().run(`UPDATE workspaces SET land_state = CASE status
+      WHEN 'ready' THEN 'delivery:complete'
+      WHEN 'review_requested' THEN 'delivery:needs-review'
+      WHEN 'merge_planned' THEN 'gate-running'
+      WHEN 'gate_running' THEN 'gate-running'
+      WHEN 'gate_failed' THEN 'gate-failed'
+      WHEN 'conflict' THEN 'steward-requested'
+      WHEN 'merging' THEN 'merging'
+      WHEN 'landed' THEN 'landed'
+      WHEN 'merged' THEN 'landed'
+      WHEN 'active' THEN CASE WHEN coalesce(json_extract(metadata, '$.gitDirtyCount'), 0) > 0 THEN 'changes' WHEN coalesce(json_extract(metadata, '$.gitAhead'), 0) > 0 THEN 'committed' ELSE 'no-changes' END
+      ELSE 'no-changes' END`);
+  }
+  if (!workspaceColNames.includes("land_state_at")) {
+    getDb().run("ALTER TABLE workspaces ADD COLUMN land_state_at INTEGER");
+    getDb().run(`UPDATE workspaces SET land_state_at = coalesce(updated_at, created_at) WHERE land_state_at IS NULL`);
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_workspaces_orchestrator ON workspaces(orchestrator_id)");
+  getDb().run(`CREATE INDEX IF NOT EXISTS idx_workspaces_steward_cancellation ON workspaces(
+    json_extract(metadata, '$.stewardCancellation.agentId'), json_extract(metadata, '$.stewardCancellation.spawnRequestId'))`);
+  getDb().run(`CREATE INDEX IF NOT EXISTS idx_workspaces_steward_handback_status ON workspaces(
+    json_extract(metadata, '$.stewardCancellation.status'))`);
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS workspace_orphan_alerts (
+      orphan_key TEXT PRIMARY KEY,
+      fingerprint TEXT NOT NULL,
+      alerted_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  // #1525 — durable human-escalation dedupe, independent of the liveness-pruned
+  // workspace_orphan_alerts table (see schema.ts for why).
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS workspace_human_escalation_alerts (
+      alert_key TEXT PRIMARY KEY,
+      alerted_at INTEGER NOT NULL
+    )
+  `);
+
+  const cols = getDb().query("PRAGMA table_info(messages)").all() as any[];
+  const colNames = cols.map((c: any) => c.name);
+  if (!colNames.includes("thread_id")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN thread_id INTEGER");
+  }
+  if (!colNames.includes("reply_to")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN reply_to INTEGER REFERENCES messages(id)");
+  }
+  if (!colNames.includes("reply_expected")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN reply_expected INTEGER NOT NULL DEFAULT 1");
+  }
+  // #2017 — server-owned urgent request facts. These are columns, never payload/meta fields.
+  if (!colNames.includes("urgent_requested")) getDb().run("ALTER TABLE messages ADD COLUMN urgent_requested INTEGER NOT NULL DEFAULT 0");
+  if (!colNames.includes("urgent_throttled")) getDb().run("ALTER TABLE messages ADD COLUMN urgent_throttled INTEGER NOT NULL DEFAULT 0");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS urgent_message_budgets (
+      sender_agent TEXT NOT NULL,
+      recipient_target TEXT NOT NULL,
+      tokens REAL NOT NULL,
+      updated_at INTEGER NOT NULL,
+      PRIMARY KEY (sender_agent, recipient_target)
+    )
+  `);
+  if (!colNames.includes("claimable")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN claimable INTEGER NOT NULL DEFAULT 0");
+    getDb().run("ALTER TABLE messages ADD COLUMN claimed_by TEXT");
+    getDb().run("ALTER TABLE messages ADD COLUMN claimed_at INTEGER");
+  }
+  if (!colNames.includes("claim_expires_at")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN claim_expires_at INTEGER");
+  }
+  if (!colNames.includes("idempotency_key")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN idempotency_key TEXT");
+  }
+  if (!colNames.includes("delivery_status")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN delivery_status TEXT NOT NULL DEFAULT 'pending'");
+  }
+  if (!colNames.includes("delivery_attempts")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN delivery_attempts INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!colNames.includes("delivery_last_error")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN delivery_last_error TEXT");
+  }
+  if (!colNames.includes("delivery_next_retry_at")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN delivery_next_retry_at INTEGER");
+  }
+  if (!colNames.includes("delivery_poison_reason")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN delivery_poison_reason TEXT");
+  }
+  if (!colNames.includes("delivery_updated_at")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN delivery_updated_at INTEGER");
+  }
+  if (!colNames.includes("queued_at")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN queued_at INTEGER");
+  }
+  if (!colNames.includes("max_age_seconds")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN max_age_seconds INTEGER");
+  }
+  if (!colNames.includes("resolved_to_agent")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN resolved_to_agent TEXT");
+  }
+  // #1935 — nullable, server-owned final-turn lineage; old rows use the legacy predicate.
+  if (!colNames.includes("message_type")) getDb().run("ALTER TABLE messages ADD COLUMN message_type TEXT"); if (!colNames.includes("source_message_id")) getDb().run("ALTER TABLE messages ADD COLUMN source_message_id INTEGER"); getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_msg_final_turn_source ON messages(source_message_id) WHERE message_type = 'final-turn'");
+  // Event time (#196): when a Runner queues a message in its durable outbox during an
+  // outage, occurred_at preserves when it really happened vs. the later receive time.
+  if (!colNames.includes("occurred_at")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN occurred_at INTEGER");
+  }
+  if (!colNames.includes("seq")) getDb().run("ALTER TABLE messages ADD COLUMN seq INTEGER");
+  getDb().query(
+    "UPDATE messages SET claim_expires_at = coalesce(claimed_at, ?) + ? WHERE claimed_by IS NOT NULL AND claim_expires_at IS NULL",
+  ).run(Date.now(), CLAIM_LEASE_MS);
+  // #3054 — keyed "a later response from this agent in this thread" probes; a superset of the old thread_id index.
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_thread_from_id ON messages(thread_id, from_agent, id)");
+  getDb().run("DROP INDEX IF EXISTS idx_msg_thread");
+  // (reply_to, from_agent) powers the reply-obligation NOT EXISTS subquery in
+  // listPendingReplyObligations. It must stay migration-owned because reply_to is
+  // an ALTER-added column on legacy DBs (#963).
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_reply_to ON messages(reply_to, from_agent)");
+  // The kernel-timers authority flip depends on this request-key guard remaining UNIQUE.
+  // It also backs retry-dedup and session-step upsert lookups.
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_msg_idempotency ON messages(from_agent, idempotency_key) WHERE idempotency_key IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_delivery_status ON messages(delivery_status)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_claimed_expires ON messages(claimed_by, claim_expires_at, id) WHERE claimed_by IS NOT NULL");
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_msg_from_seq ON messages(from_agent, seq) WHERE seq IS NOT NULL");
+  // (#846) composite replaces the old single-column idx_msg_resolved_to_agent; created
+  // here — AFTER the resolved_to_agent ALTER above — so existing DBs without the column
+  // don't crash (same hazard as idx_msg_from_kind_id / #483/#559).
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_resolved_to_id ON messages(resolved_to_agent, id)");
+
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS agent_continuations (
+      agent_id TEXT PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
+      objective TEXT NOT NULL, objective_epoch INTEGER NOT NULL,
+      generation INTEGER NOT NULL DEFAULT 0,
+      ledger TEXT NOT NULL DEFAULT '[]',
+      working_state TEXT NOT NULL DEFAULT '',
+      archive_refs TEXT NOT NULL DEFAULT '[]',
+      budget TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `); if (!(getDb().query("PRAGMA table_info(agent_continuations)").all() as Array<{ name: string }>).some((column) => column.name === "objective_epoch")) { getDb().run("ALTER TABLE agent_continuations ADD COLUMN objective_epoch INTEGER NOT NULL DEFAULT 0"); getDb().run("UPDATE agent_continuations SET objective_epoch = created_at WHERE objective_epoch = 0"); }
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS continuation_archives (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      generation INTEGER NOT NULL,
+      segment TEXT NOT NULL,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run(`
+    CREATE INDEX IF NOT EXISTS idx_continuation_archives_agent_generation
+    ON continuation_archives(agent_id, generation, created_at DESC)
+  `);
+  dropLegacyContinuationArchiveIndex();
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS task_memories (
+      task_id INTEGER PRIMARY KEY REFERENCES tasks(id) ON DELETE CASCADE,
+      objective TEXT NOT NULL,
+      generation INTEGER NOT NULL DEFAULT 0,
+      ledger TEXT NOT NULL DEFAULT '[]',
+      decisions TEXT NOT NULL DEFAULT '[]',
+      working_state TEXT NOT NULL DEFAULT '',
+      archive_refs TEXT NOT NULL DEFAULT '[]',
+      budget TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  const tokenCols = getDb().query("PRAGMA table_info(tokens)").all() as any[];
+  const tokenColNames = tokenCols.map((c: any) => c.name);
+  if (!tokenColNames.includes("constraints")) {
+    getDb().run("ALTER TABLE tokens ADD COLUMN constraints TEXT");
+  }
+  if (!tokenColNames.includes("profile_id")) {
+    getDb().run("ALTER TABLE tokens ADD COLUMN profile_id TEXT");
+  }
+  // #484: revocation reason distinguishes a stale-on-restart revocation (recoverable via
+  // orchestrator re-mint for a still-live process) from a hard kill (admin/rotation). A NULL
+  // reason on a legacy revoked token is treated as a hard kill — never re-mintable.
+  if (!tokenColNames.includes("revoked_reason")) {
+    getDb().run("ALTER TABLE tokens ADD COLUMN revoked_reason TEXT");
+  }
+  // #1245: handoff links between a token and its successor (token-db.ts handoffTokenInternal); the index serves
+  // the lineage walk of a revocation (token-standing.ts revokeTokenLineage).
+  for (const col of ["successor_jti", "predecessor_jti"]) if (!tokenColNames.includes(col)) getDb().run(`ALTER TABLE tokens ADD COLUMN ${col} TEXT`);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tokens_predecessor_jti ON tokens(predecessor_jti) WHERE predecessor_jti IS NOT NULL");
+
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS message_delivery_attempts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      agent_id TEXT,
+      action TEXT NOT NULL DEFAULT 'attempt',
+      status TEXT NOT NULL,
+      error TEXT,
+      next_retry_at INTEGER,
+      poison_reason TEXT,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_mda_message ON message_delivery_attempts(message_id, created_at DESC)"); getDb().run("CREATE INDEX IF NOT EXISTS idx_mda_agent_created ON message_delivery_attempts(agent_id, created_at DESC)");
+  getDb().run("CREATE TABLE IF NOT EXISTS channel_delivery_releases (message_id INTEGER PRIMARY KEY REFERENCES messages(id) ON DELETE CASCADE)");
+
+  const channelBindingsSql = getDb().query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'channel_bindings'").get() as { sql?: string } | undefined;
+  if (channelBindingsSql?.sql?.includes("UNIQUE(channel_id, conversation_key)")) {
+    getDb().transaction(() => {
+      getDb().run("ALTER TABLE channel_bindings RENAME TO channel_bindings_old");
+      getDb().run(`
+        CREATE TABLE channel_bindings (
+          id TEXT PRIMARY KEY,
+          channel_id TEXT NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
+          conversation_key TEXT NOT NULL DEFAULT '',
+          conversation_id TEXT,
+          target_type TEXT NOT NULL,
+          target_id TEXT NOT NULL,
+          mode TEXT NOT NULL DEFAULT 'exclusive',
+          priority INTEGER NOT NULL DEFAULT 0,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )
+      `);
+      getDb().run(`
+        INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at)
+        SELECT id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at
+        FROM channel_bindings_old
+      `);
+      getDb().run("DROP TABLE channel_bindings_old");
+    })();
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_channel_bindings_channel ON channel_bindings(channel_id, priority)");
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_bindings_target ON channel_bindings(channel_id, conversation_key, target_type, target_id)");
+
+  const bindingColNames = (getDb().query("PRAGMA table_info(channel_bindings)").all() as any[]).map((c: any) => c.name);
+  if (!bindingColNames.includes("pool_selector")) {
+    getDb().run("ALTER TABLE channel_bindings ADD COLUMN pool_selector TEXT");
+    getDb().run("ALTER TABLE channel_bindings ADD COLUMN pool_agent_id TEXT");
+    getDb().run("ALTER TABLE channel_bindings ADD COLUMN pool_agent_epoch INTEGER");
+    getDb().run("ALTER TABLE channel_bindings ADD COLUMN pool_claim_expires_at INTEGER");
+  }
+
+  if (!colNames.includes("kind")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN kind TEXT NOT NULL DEFAULT 'chat'");
+  }
+  if (!colNames.includes("payload")) {
+    getDb().run("ALTER TABLE messages ADD COLUMN payload TEXT NOT NULL DEFAULT '{}'");
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_kind ON messages(kind)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_from_id ON messages(from_agent, id)");
+  // #3644 idx_msg_pair_chat: child→parent chat dedupe reads (db/lineage-pair-dedupe-sql.ts) seek the
+  // pair, not the parent's whole inbox. One-time build before bind on an existing DB (~1 s per GB warm).
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_from_kind_id ON messages(from_agent, kind, id)"); getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_pair_chat ON messages(from_agent, to_target, created_at) WHERE kind = 'chat'"); getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_analytics_created ON messages(created_at, kind, from_agent, claimable, reply_to)"); getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_session_analytics ON messages(kind, created_at, json_extract(payload, '$.session.type'), json_extract(payload, '$.session.label'), json_extract(payload, '$.session.turnId'))");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS teams (
+      id TEXT PRIMARY KEY,
+      coordinator_id TEXT,
+      root_coordinator_id TEXT,
+      title TEXT,
+      brief TEXT,
+      definition_of_done TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      outcome_status TEXT,
+      outcome_summary TEXT,
+      composition TEXT,
+      cost_tokens INTEGER,
+      cost_usd REAL,
+      wall_clock_ms INTEGER,
+      lands_clean INTEGER,
+      zero_members_since INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      dissolved_at INTEGER
+    )
+  `);
+  const teamColNames = (getDb().query("PRAGMA table_info(teams)").all() as any[]).map((c: any) => c.name);
+  if (!teamColNames.includes("zero_members_since")) {
+    getDb().run("ALTER TABLE teams ADD COLUMN zero_members_since INTEGER");
+  }
+  if (!teamColNames.includes("idle_since")) getDb().run("ALTER TABLE teams ADD COLUMN idle_since INTEGER");
+  if (!teamColNames.includes("idle_pinged")) getDb().run("ALTER TABLE teams ADD COLUMN idle_pinged INTEGER");
+  // #2862 — JSON array of agents a claim displaced from the seat (see db/coordinator-seat.ts).
+  if (!teamColNames.includes("parent_team_id")) getDb().run("ALTER TABLE teams ADD COLUMN parent_team_id TEXT");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_teams_parent ON teams(parent_team_id) WHERE parent_team_id IS NOT NULL");
+  if (!teamColNames.includes("former_coordinator_ids")) getDb().run("ALTER TABLE teams ADD COLUMN former_coordinator_ids TEXT");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_teams_coordinator ON teams(coordinator_id)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_teams_status ON teams(status)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS blackboard_entries (
+      id TEXT PRIMARY KEY,
+      team_id TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      supersedes TEXT,
+      tags TEXT,
+      author_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_blackboard_team ON blackboard_entries(team_id)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_blackboard_team_kind ON blackboard_entries(team_id, kind)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS plans (
+      id TEXT PRIMARY KEY, thread_id INTEGER NOT NULL, team_id TEXT, channel TEXT, version INTEGER NOT NULL DEFAULT 1,
+      title TEXT, objective TEXT, nodes TEXT NOT NULL DEFAULT '[]', edges TEXT NOT NULL DEFAULT '[]',
+      created_by TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+    )
+  `);
+  const planColNames = (getDb().query("PRAGMA table_info(plans)").all() as any[]).map((c: any) => c.name);
+  if (!planColNames.includes("team_id")) {
+    getDb().run("ALTER TABLE plans ADD COLUMN team_id TEXT");
+  }
+  if (!planColNames.includes("archived")) getDb().run("ALTER TABLE plans ADD COLUMN archived INTEGER NOT NULL DEFAULT 0");
+  // #2932 plan-level acceptance: nullable, so legacy plans keep no completion state.
+  for (const col of ["acceptance", "conformance", "completion"]) if (!planColNames.includes(col)) getDb().run(`ALTER TABLE plans ADD COLUMN ${col} TEXT`);
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_plans_thread_channel ON plans(thread_id, coalesce(channel, ''))");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_plans_updated ON plans(updated_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_plans_team ON plans(team_id)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS plan_versions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, plan_id TEXT NOT NULL,
+      version INTEGER NOT NULL, title TEXT, objective TEXT, nodes TEXT NOT NULL, edges TEXT NOT NULL,
+      changed_by TEXT, changed_at INTEGER NOT NULL
+    )
+  `);
+  const planVersionFks = getDb().query("PRAGMA foreign_key_list(plan_versions)").all() as any[];
+  if (planVersionFks.some((fk) => fk.table === "plans" && String(fk.on_delete).toUpperCase() === "CASCADE")) {
+    getDb().transaction(() => {
+      getDb().run("ALTER TABLE plan_versions RENAME TO plan_versions_old");
+      getDb().run(`
+        CREATE TABLE plan_versions (
+          id INTEGER PRIMARY KEY AUTOINCREMENT, plan_id TEXT NOT NULL,
+          version INTEGER NOT NULL, title TEXT, objective TEXT, nodes TEXT NOT NULL, edges TEXT NOT NULL,
+          changed_by TEXT, changed_at INTEGER NOT NULL
+        )
+      `);
+      getDb().run(`
+        INSERT INTO plan_versions (id, plan_id, version, title, objective, nodes, edges, changed_by, changed_at)
+        SELECT id, plan_id, version, title, objective, nodes, edges, changed_by, changed_at
+        FROM plan_versions_old
+      `);
+      getDb().run("DROP TABLE plan_versions_old");
+    })();
+  }
+  const planVersionCols = (getDb().query("PRAGMA table_info(plan_versions)").all() as any[]).map((c: any) => c.name);
+  for (const col of ["acceptance", "conformance"]) if (!planVersionCols.includes(col)) getDb().run(`ALTER TABLE plan_versions ADD COLUMN ${col} TEXT`);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_plan_versions_plan ON plan_versions(plan_id, version DESC)");
+
+  // Backfill thread_id for pre-migration rows (self-threaded).
+  getDb().run("UPDATE messages SET thread_id = id WHERE thread_id IS NULL");
+
+  const taskCols = getDb().query("PRAGMA table_info(tasks)").all() as any[];
+  const taskColNames = taskCols.map((c: any) => c.name);
+  if (!taskColNames.includes("claim_expires_at")) {
+    getDb().run("ALTER TABLE tasks ADD COLUMN claim_expires_at INTEGER");
+  }
+  getDb().query(
+    "UPDATE tasks SET claim_expires_at = coalesce(claimed_at, ?) + ? WHERE claimed_by IS NOT NULL AND claim_expires_at IS NULL",
+  ).run(Date.now(), CLAIM_LEASE_MS);
+
+  const providerModelOverrideCols = getDb().query("PRAGMA table_info(provider_model_overrides)").all() as any[];
+  const providerModelOverrideColNames = providerModelOverrideCols.map((c: any) => c.name);
+  if (!providerModelOverrideColNames.includes("disabled")) {
+    getDb().run("ALTER TABLE provider_model_overrides ADD COLUMN disabled INTEGER NOT NULL DEFAULT 0");
+  }
+  getDb().run(`CREATE TABLE IF NOT EXISTS provider_model_defaults (
+    provider TEXT PRIMARY KEY, alias TEXT NOT NULL, updated_at INTEGER NOT NULL, updated_by TEXT
+  )`);
+
+  // Migration: projects.issue_repo (#533) — per-project `owner/repo` for #NNN linkify/land-close.
+  const projectCols = (getDb().query("PRAGMA table_info(projects)").all() as any[]).map((c: any) => c.name);
+  if (!projectCols.includes("issue_repo")) {
+    getDb().run("ALTER TABLE projects ADD COLUMN issue_repo TEXT");
+  }
+  // Migration: projects.scope/anchor_key (#559) — the {project|profile|user} anchor axis.
+  // ADD COLUMN with a DEFAULT is safe on a populated table; existing rows become scope='project'.
+  if (!projectCols.includes("scope")) {
+    getDb().run("ALTER TABLE projects ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'");
+  }
+  if (!projectCols.includes("anchor_key")) {
+    getDb().run("ALTER TABLE projects ADD COLUMN anchor_key TEXT");
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_projects_scope_anchor ON projects(scope, anchor_key)");
+  // Migration: project_roots.remote_url/ref (#410) — clone/sync manifest metadata.
+  const projectRootCols = (getDb().query("PRAGMA table_info(project_roots)").all() as any[]).map((c: any) => c.name);
+  if (!projectRootCols.includes("remote_url")) {
+    getDb().run("ALTER TABLE project_roots ADD COLUMN remote_url TEXT");
+  }
+  if (!projectRootCols.includes("ref")) {
+    getDb().run("ALTER TABLE project_roots ADD COLUMN ref TEXT");
+  }
+  if (!projectRootCols.includes("orchestrator_id")) {
+    getDb().run("ALTER TABLE project_roots ADD COLUMN orchestrator_id TEXT");
+  }
+  migrateProjectRootHosts();
+  // Migration: project_entries audience/inject/expires_at/sensitivity (#1565 P2) — the
+  // unified-memory scope+audience model. Every default is behavior-preserving: an existing row
+  // becomes `audience:'all'`, `sensitivity:'normal'`, no TTL, and its kind-derived inject tier,
+  // which is exactly how the current composer already treats it (nothing reads these yet).
+  const projectEntryCols = (getDb().query("PRAGMA table_info(project_entries)").all() as any[]).map((c: any) => c.name);
+  if (!projectEntryCols.includes("audience")) {
+    getDb().run("ALTER TABLE project_entries ADD COLUMN audience TEXT NOT NULL DEFAULT 'all'");
+  }
+  if (!projectEntryCols.includes("inject")) {
+    getDb().run("ALTER TABLE project_entries ADD COLUMN inject TEXT NOT NULL DEFAULT 'indexed'");
+    // Backfill the kind-derived tier ONCE, at the ALTER (§4.3(1) — a directive that isn't in
+    // context doesn't bind). Guarded by the ALTER so a later hand-edit is never clobbered.
+    getDb().run("UPDATE project_entries SET inject = 'pinned' WHERE kind = 'rule'");
+  }
+  if (!projectEntryCols.includes("expires_at")) {
+    getDb().run("ALTER TABLE project_entries ADD COLUMN expires_at INTEGER");
+  }
+  if (!projectEntryCols.includes("sensitivity")) {
+    getDb().run("ALTER TABLE project_entries ADD COLUMN sensitivity TEXT NOT NULL DEFAULT 'normal'");
+  }
+  // #3408 — the memory's areas (JSON array). Existing rows stay NULL: legacy/untagged.
+  if (!projectEntryCols.includes("areas")) {
+    getDb().run("ALTER TABLE project_entries ADD COLUMN areas TEXT");
+  }
+  timeStartupPhase("db.backfill.project-issue-repos", backfillProjectIssueRepos);
+  timeStartupPhase("db.backfill.project-remote-urls", backfillProjectRootRemoteUrls);
+  timeStartupPhase("db.backfill.phantom-projects", mergePhantomWorktreeProjectsAtStartup);
+  ensureIngestedMemoryIndex();
+  rewriteEmptyToolGroupsToAbsent(); // #1963 N2 — persisted relay.tools.groups:[] meant ALL; honoring [] as NONE requires rewriting existing [] → absent first
+  backfillProjectMemoryToolGroup(); // #2154 follow-up — stored/overridden profiles do not pick up the built-in `project-memory` group on their own
+  removeLegacyProfileProjectInstructions(); // #2133 — remove retired profile policy fields before profile override migration reads legacy rows
+  backfillCustomProfileArtifacts(); // #3171 — Artifact is off by default now; keep the approved custom brainstorm exception
+  migrateAgentProfileOverridesToV2(); // #1963 N10 — back up + migrate persisted override rows to the v2 matrix (D-T=off; G6/G7 leave-untouched-and-report; flag-gated rollback)
+  migrateProfileSlimOnStartup(); // #2982 — marker-gated: promote 4 custom rows to built-in overrides, retire merged/removed presets, canonicalize memory audiences
+  migrateProfileHostSources((line) => console.log(`[profile-host-sources] ${line}`)); // #3387 — stamp Host asset classes whose omission now inherits differently; logs the per-class diff
+  migrateProfileProjectAcks((line) => console.log(`[profile-project-ack] ${line}`)); // #3636 — acks stopped hashing trust.review; re-stamp the ones valid under the old hash
+  ensureProfileNameCaseIndex(); // #2791 — case-insensitive uniqueness for agent-profile keys; throws naming collisions instead of merging them
+
+  // Migration: orchestrators.api_url
+  const orchCols = getDb().query("PRAGMA table_info(orchestrators)").all() as any[];
+  const orchColNames = orchCols.map((c: any) => c.name);
+  if (!orchColNames.includes("api_url")) {
+    getDb().run("ALTER TABLE orchestrators ADD COLUMN api_url TEXT");
+  }
+  // Migration: orchestrators.queued_spawns (#1513) — spawns held back by the host headroom admission
+  // gate, surfaced to the dashboard. Defaults to an empty JSON array for pre-existing rows.
+  if (!orchColNames.includes("queued_spawns")) {
+    getDb().run("ALTER TABLE orchestrators ADD COLUMN queued_spawns TEXT NOT NULL DEFAULT '[]'");
+  }
+  // ADR 0002 (#1925) H2 — orchestrators.host_id, the 1:N link to its Host row (§3.3). The fresh-DB
+  // schema.ts DDL already carries this column; an existing DB gains it here.
+  if (!orchColNames.includes("host_id")) {
+    getDb().run("ALTER TABLE orchestrators ADD COLUMN host_id TEXT REFERENCES hosts(id)");
+  }
+  // ADR 0002 §4.3.1 (#895 U3) — orchestrators.utilization, the per-generation half of the
+  // utilization sample. Nullable: a generation that has never reported (or a pre-upgrade daemon)
+  // has no sample, and the band reads that as "not reporting", never as "idle".
+  if (!orchColNames.includes("utilization")) {
+    getDb().run("ALTER TABLE orchestrators ADD COLUMN utilization TEXT");
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_orchestrators_host ON orchestrators(host_id)");
+
+  // #1977 — retain the latest real report separately from the accepted, first-seen fingerprint.
+  // Existing rows have no pending report, so their accepted fingerprint is the only truthful
+  // baseline until the next registration supplies a newer report.
+  const hostColNames = (getDb().query("PRAGMA table_info(hosts)").all() as any[]).map((c: any) => c.name);
+  if (!hostColNames.includes("reported_hardware")) {
+    getDb().run("ALTER TABLE hosts ADD COLUMN reported_hardware TEXT");
+    getDb().run("UPDATE hosts SET reported_hardware = hardware WHERE reported_hardware IS NULL");
+  }
+  // §3.3.2 backfill: one Host row per distinct hostname, keyed on normalizeHostToken(hostname),
+  // with {hostname, id} claimed as aliases and host_id linked — idempotent (skips already-linked
+  // rows). Then the §3.8 alias audit (RC-6), which must see the just-built alias table.
+  backfillHostsFromOrchestrators(Date.now());
+  auditHostAliases(Date.now());
+
+  const managedStateCols = getDb().query("PRAGMA table_info(managed_agent_state)").all() as any[];
+  const managedStateColNames = managedStateCols.map((c: any) => c.name);
+  if (!managedStateColNames.includes("workspace_id")) {
+    getDb().run("ALTER TABLE managed_agent_state ADD COLUMN workspace_id TEXT");
+    getDb().run("ALTER TABLE managed_agent_state ADD COLUMN workspace_path TEXT");
+    getDb().run("ALTER TABLE managed_agent_state ADD COLUMN workspace_branch TEXT");
+  }
+  // #1623 — retained last-known agent_id for steward provenance across the steward's own stop.
+  // Backfilled from the current agent_id so a steward RUNNING at migration time keeps its binding.
+  if (!managedStateColNames.includes("last_agent_id")) {
+    getDb().run("ALTER TABLE managed_agent_state ADD COLUMN last_agent_id TEXT");
+    getDb().run("UPDATE managed_agent_state SET last_agent_id = agent_id WHERE agent_id IS NOT NULL");
+  }
+
+  // message_reads: relational replacement for the read_by JSON array.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS message_reads (
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      agent_id TEXT NOT NULL,
+      read_at INTEGER NOT NULL,
+      PRIMARY KEY (message_id, agent_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_mr_agent ON message_reads(agent_id);
+  `);
+
+  // Migration: agents.label
+  const agentCols = getDb().query("PRAGMA table_info(agents)").all() as any[];
+  const agentColNames = agentCols.map((c: any) => c.name);
+  if (!agentColNames.includes("label")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN label TEXT");
+  }
+  if (!agentColNames.includes("ready")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN ready INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!agentColNames.includes("instance_id")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN instance_id TEXT");
+  }
+  if (!agentColNames.includes("epoch")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN epoch INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!agentColNames.includes("kind")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN kind TEXT NOT NULL DEFAULT 'provider'");
+    getDb().run(`
+      UPDATE agents
+      SET kind = CASE
+        WHEN id = 'user' THEN 'user'
+        WHEN id = 'system' THEN 'system'
+        WHEN json_extract(meta, '$.kind') = 'channel' THEN 'channel'
+        WHEN EXISTS (SELECT 1 FROM json_each(tags) WHERE value = 'channel') THEN 'channel'
+        ELSE 'provider'
+      END
+    `);
+  }
+  if (!agentColNames.includes("provider_capabilities")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN provider_capabilities TEXT");
+  }
+  if (!agentColNames.includes("context_state")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN context_state TEXT");
+  }
+  if (!agentColNames.includes("quota_state")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN quota_state TEXT");
+  }
+  // #2367 — launch projection is large and immutable. Move it out of the hot meta JSON so status
+  // frames update only runtime fields. The mapper reattaches it at the AgentCard read boundary.
+  if (!agentColNames.includes("profile_projection")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN profile_projection TEXT");
+    getDb().run(`
+      UPDATE agents
+      SET profile_projection = json_extract(meta, '$.agentProfile.projection'),
+          meta = json_remove(meta, '$.agentProfile.projection')
+      WHERE json_type(meta, '$.agentProfile.projection') IS NOT NULL
+    `);
+  }
+  if (!agentColNames.includes("lifecycle")) getDb().run("ALTER TABLE agents ADD COLUMN lifecycle TEXT NOT NULL DEFAULT 'persistent'");
+  // #2111 — the per-column lifecycle submission-ordinal fence. Existing rows start at 0, which is
+  // below every ordinal this process will issue (the counter is seeded from the stored high-water
+  // mark), so an upgraded DB is immediately writable rather than fenced out.
+  if (!agentColNames.includes("status_seq")) getDb().run("ALTER TABLE agents ADD COLUMN status_seq INTEGER NOT NULL DEFAULT 0");
+  if (!agentColNames.includes("ready_seq")) getDb().run("ALTER TABLE agents ADD COLUMN ready_seq INTEGER NOT NULL DEFAULT 0");
+  if (!agentColNames.includes("keep_state")) getDb().run("ALTER TABLE agents ADD COLUMN keep_state TEXT"); // #3428
+  if (!agentColNames.includes("system_tags")) { getDb().run("ALTER TABLE agents ADD COLUMN system_tags TEXT NOT NULL DEFAULT '[]'"); getDb().query(`UPDATE agents SET system_tags = CASE WHEN json_extract(meta, '$.profile') IN (${COORDINATOR_PROFILE_NAMES.map(() => "?").join(",")}) THEN '[\"coordinator\"]' WHEN json_extract(meta, '$.profile') = 'memory-steward' THEN '[\"memory-steward\"]' WHEN EXISTS (SELECT 1 FROM json_each(agents.tags) WHERE value = 'steward') THEN '[\"merge-steward\"]' ELSE system_tags END WHERE system_tags = '[]'`).run(...COORDINATOR_PROFILE_NAMES); }
+
+  // Relay-owned provisioning registry (#554/#555/#556/#694) — see schema.ts for
+  // canonical DDL; mirrored here so existing DBs gain the registry on upgrade.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS provisioning_capabilities (
+      id TEXT PRIMARY KEY,
+      slug TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      title TEXT,
+      description TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      tenant_id TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE(kind, slug)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_provisioning_capabilities_kind ON provisioning_capabilities(kind, status)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS provisioning_assets (
+      id TEXT PRIMARY KEY,
+      kind TEXT NOT NULL,
+      name TEXT NOT NULL,
+      provider TEXT NOT NULL DEFAULT 'any',
+      definition TEXT NOT NULL,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE(kind, name, provider)
+    )
+  `);
+  let provisioningAssetColNames = provisioningAssetsColumnNames();
+  const provisioningAssetAddColumns = [
+    ["capability_id", "capability_id TEXT"],
+    ["source_type", "source_type TEXT"],
+    ["source_url", "source_url TEXT"],
+    ["source_ref", "source_ref TEXT"],
+    ["resolved_ref", "resolved_ref TEXT"],
+    ["source_subpath", "source_subpath TEXT"],
+    ["version_constraint", "version_constraint TEXT"],
+    ["approval_status", "approval_status TEXT NOT NULL DEFAULT 'approved'"],
+    ["validation_status", "validation_status TEXT NOT NULL DEFAULT 'valid'"],
+    ["validation_errors", "validation_errors TEXT NOT NULL DEFAULT '[]'"],
+    ["provenance", "provenance TEXT NOT NULL DEFAULT '{}'"],
+    ["imported_at", "imported_at INTEGER"],
+  ] as const;
+  for (const [name, ddl] of provisioningAssetAddColumns) {
+    if (!provisioningAssetColNames.includes(name)) getDb().run(`ALTER TABLE provisioning_assets ADD COLUMN ${ddl}`);
+  }
+  const existingCapabilities = getDb()
+    .query("SELECT kind, name, min(created_at) AS created_at, max(updated_at) AS updated_at FROM provisioning_assets GROUP BY kind, name")
+    .all() as Array<{ kind: string; name: string; created_at: number; updated_at: number }>;
+  const insertCapability = getDb().query(`
+    INSERT INTO provisioning_capabilities (id, slug, kind, title, status, tenant_id, created_at, updated_at)
+    VALUES (?, ?, ?, ?, 'active', NULL, ?, ?)
+    ON CONFLICT(kind, slug) DO UPDATE SET
+      updated_at = max(provisioning_capabilities.updated_at, excluded.updated_at)
+  `);
+  const backfillCapabilities = getDb().transaction((rows: typeof existingCapabilities) => {
+    for (const row of rows) {
+      insertCapability.run(`pc_${randomUUID().replace(/-/g, "").slice(0, 16)}`, row.name, row.kind, row.name, row.created_at, row.updated_at);
+    }
+    getDb().run(`
+      UPDATE provisioning_assets
+      SET capability_id = (
+        SELECT id FROM provisioning_capabilities
+        WHERE provisioning_capabilities.kind = provisioning_assets.kind
+          AND provisioning_capabilities.slug = provisioning_assets.name
+      )
+      WHERE capability_id IS NULL
+    `);
+    getDb().run("UPDATE provisioning_assets SET imported_at = coalesce(imported_at, created_at)");
+  });
+  backfillCapabilities(existingCapabilities);
+  if (provisioningAssetsNeedsRebuild()) rebuildProvisioningAssetsTable();
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_provisioning_assets_kind ON provisioning_assets(kind, enabled)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_provisioning_assets_capability ON provisioning_assets(capability_id, provider, enabled)");
+  getDb().run(`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_provisioning_assets_capability_provider
+    ON provisioning_assets(capability_id, provider)
+  `);
+  seedBundledProvisioningAssets();
+  seedQaSkills();
+  seedSharedCallmuxProvisioningAssets();
+  if (!agentColNames.includes("spawned_by")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN spawned_by TEXT");
+  }
+  if (!agentColNames.includes("team_id")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN team_id TEXT");
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_team ON agents(team_id)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_spawn_request ON agents(json_extract(meta, '$.spawnRequestId'))");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS notification_subscriptions (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      type TEXT NOT NULL,
+      mode TEXT NOT NULL CHECK (mode IN ('opt_in', 'opt_out', 'mute')),
+      scope_match TEXT,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_notification_subscriptions_agent ON notification_subscriptions(agent_id, type)");
+  getDb().run(`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_subscriptions_unique
+    ON notification_subscriptions(agent_id, type, mode, coalesce(scope_match, ''))
+  `);
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS context_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      utilization REAL NOT NULL,
+      lifecycle_state TEXT NOT NULL,
+      tokens_used INTEGER,
+      tokens_max INTEGER,
+      source TEXT NOT NULL,
+      confidence TEXT NOT NULL,
+      context_state TEXT NOT NULL,
+      captured_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_context_snapshots_agent_time ON context_snapshots(agent_id, captured_at DESC)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS quota_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      provider TEXT NOT NULL,
+      account_key TEXT NOT NULL,
+      agent_id TEXT REFERENCES agents(id) ON DELETE SET NULL,
+      windows TEXT NOT NULL,
+      source TEXT NOT NULL,
+      quota_state TEXT NOT NULL,
+      captured_at INTEGER NOT NULL
+    )
+  `);
+  const quotaSnapshotCols = (getDb().query("PRAGMA table_info(quota_snapshots)").all() as Array<{ name: string }>).map((col) => col.name);
+  if (!quotaSnapshotCols.includes("provider") || !quotaSnapshotCols.includes("account_key")) {
+    getDb().run("ALTER TABLE quota_snapshots RENAME TO quota_snapshots_legacy_agent");
+    getDb().run(`
+      CREATE TABLE quota_snapshots (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        provider TEXT NOT NULL,
+        account_key TEXT NOT NULL,
+        agent_id TEXT REFERENCES agents(id) ON DELETE SET NULL,
+        windows TEXT NOT NULL,
+        source TEXT NOT NULL,
+        quota_state TEXT NOT NULL,
+        captured_at INTEGER NOT NULL
+      )
+    `);
+    getDb().run(`
+      INSERT INTO quota_snapshots (id, provider, account_key, agent_id, windows, source, quota_state, captured_at)
+      SELECT
+        qs.id,
+        CASE
+          WHEN json_extract(a.meta, '$.provider') IS NOT NULL THEN lower(json_extract(a.meta, '$.provider'))
+          WHEN a.tags LIKE '%"codex"%' OR lower(a.id) LIKE '%codex%' OR lower(a.name) LIKE '%codex%' THEN 'codex'
+          ELSE 'claude'
+        END,
+        coalesce(
+          nullif(json_extract(a.meta, '$.accountKey'), ''),
+          nullif(json_extract(a.meta, '$.accountId'), ''),
+          nullif(json_extract(a.meta, '$.orgId'), ''),
+          'host:' || coalesce(a.machine, a.rig, 'unknown')
+        ),
+        qs.agent_id,
+        qs.windows,
+        qs.source,
+        qs.quota_state,
+        qs.captured_at
+      FROM quota_snapshots_legacy_agent qs
+      LEFT JOIN agents a ON a.id = qs.agent_id
+    `);
+    getDb().run("DROP TABLE quota_snapshots_legacy_agent");
+  }
+  // #609 — durable 30-day quota history needs explicit "couldn't collect" markers so gaps are
+  // first-class, not silent absences. An unavailable row carries no quota: `unavailable=1` plus the
+  // skip reason in `last_error` (the NOT NULL windows/source/quota_state columns get inert placeholders
+  // that `rowToSnapshot` never reads when `unavailable=1`).
+  const quotaSnapshotColsNow = (getDb().query("PRAGMA table_info(quota_snapshots)").all() as Array<{ name: string }>).map((col) => col.name);
+  if (!quotaSnapshotColsNow.includes("unavailable")) {
+    getDb().run("ALTER TABLE quota_snapshots ADD COLUMN unavailable INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!quotaSnapshotColsNow.includes("last_error")) {
+    getDb().run("ALTER TABLE quota_snapshots ADD COLUMN last_error TEXT");
+  }
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS provider_quotas (
+      provider TEXT NOT NULL,
+      account_key TEXT NOT NULL,
+      quota_state TEXT,
+      source_agent_ids TEXT NOT NULL DEFAULT '[]',
+      quota_advisory_state TEXT NOT NULL DEFAULT '{}',
+      last_updated_at INTEGER,
+      last_attempt_at INTEGER NOT NULL,
+      last_error TEXT,
+      updated_at INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (provider, account_key)
+    )
+  `);
+  const providerQuotaCols = (getDb().query("PRAGMA table_info(provider_quotas)").all() as Array<{ name: string }>).map((col) => col.name);
+  if (!providerQuotaCols.includes("codex_reset_credits")) getDb().run("ALTER TABLE provider_quotas ADD COLUMN codex_reset_credits TEXT");
+  if (!providerQuotaCols.includes("quota_advisory_state")) getDb().run("ALTER TABLE provider_quotas ADD COLUMN quota_advisory_state TEXT NOT NULL DEFAULT '{}'");
+  // #1074 — persist quota-band hysteresis state so a relay restart doesn't re-fire already-sent
+  // band-degradation notifications to the whole fleet.
+  if (!providerQuotaCols.includes("quota_band_state")) getDb().run("ALTER TABLE provider_quotas ADD COLUMN quota_band_state TEXT NOT NULL DEFAULT '{}'");
+  getDb().run("CREATE TABLE IF NOT EXISTS provider_quota_effect_occurrences (id INTEGER PRIMARY KEY AUTOINCREMENT, provider TEXT NOT NULL, account_key TEXT NOT NULL, event_type TEXT NOT NULL, subject TEXT NOT NULL, created_at INTEGER NOT NULL)");
+  getDb().run(`
+    INSERT INTO provider_quotas (
+      provider, account_key, quota_state, source_agent_ids, last_updated_at,
+      last_attempt_at, last_error, updated_at, created_at
+    )
+    SELECT
+      CASE
+        WHEN json_extract(meta, '$.provider') IS NOT NULL THEN lower(json_extract(meta, '$.provider'))
+        WHEN tags LIKE '%"codex"%' OR lower(id) LIKE '%codex%' OR lower(name) LIKE '%codex%' THEN 'codex'
+        ELSE 'claude'
+      END AS provider,
+      coalesce(
+        nullif(json_extract(meta, '$.accountKey'), ''),
+        nullif(json_extract(meta, '$.accountId'), ''),
+        nullif(json_extract(meta, '$.orgId'), ''),
+        'host:' || coalesce(machine, rig, 'unknown')
+      ) AS account_key,
+      quota_state,
+      json_array(id),
+      coalesce(json_extract(quota_state, '$.updatedAt'), last_seen),
+      coalesce(json_extract(quota_state, '$.updatedAt'), last_seen),
+      NULL,
+      last_seen,
+      created_at
+    FROM agents
+    WHERE quota_state IS NOT NULL
+    ON CONFLICT(provider, account_key) DO UPDATE SET
+      quota_state = excluded.quota_state,
+      source_agent_ids = excluded.source_agent_ids,
+      last_updated_at = max(coalesce(provider_quotas.last_updated_at, 0), coalesce(excluded.last_updated_at, 0)),
+      last_attempt_at = max(provider_quotas.last_attempt_at, excluded.last_attempt_at),
+      updated_at = max(provider_quotas.updated_at, excluded.updated_at)
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_quota_snapshots_account_time ON quota_snapshots(provider, account_key, captured_at DESC)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_quota_snapshots_agent_time ON quota_snapshots(agent_id, captured_at DESC)");
+  normalizeProviderQuotaAccountKeys();
+
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS provider_quota_leases (
+      provider TEXT NOT NULL,
+      account_key TEXT NOT NULL,
+      orchestrator_id TEXT NOT NULL,
+      lease_token TEXT NOT NULL,
+      expires_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (provider, account_key)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_provider_quota_leases_expires ON provider_quota_leases(expires_at)");
+
+  // #1425 finding 2 — durable dedupe for the manual Codex banked-reset trigger. Keyed by the
+  // STABLE idempotency key derived per logical owner action (not a fresh UUID per call): a
+  // lost-response retry of the same logical request is recognized here and returns the original
+  // outcome instead of burning a second scarce reset. A row is written in-flight BEFORE firing
+  // and completed after; the codex-side idempotency (same key) is the backstop for the window
+  // where the fire happened but our recording of it didn't.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS codex_reset_consumes (
+      idempotency_key TEXT PRIMARY KEY,
+      provider TEXT NOT NULL,
+      account_key TEXT,
+      status TEXT NOT NULL,
+      outcome TEXT,
+      burned INTEGER,
+      available_count INTEGER,
+      orchestrator_id TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_codex_reset_consumes_created ON codex_reset_consumes(created_at)");
+
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_label ON agents(label)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_kind ON agents(kind)");
+  getDb().run(`
+    CREATE INDEX IF NOT EXISTS idx_activity_registered_spawn_request
+    ON activity_events(json_extract(metadata, '$.spawnRequestId'))
+    WHERE kind = 'state' AND title = 'Agent registered'
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_spawn_watchdog ON commands(type, status, updated_at)");
+  // #1858 — runs AFTER the commands/agents/activity_events tables and the two spawnRequestId indexes
+  // above exist, so the backfill's registration lookups are indexed point lookups. #3707: once per DB;
+  // registration stamps new spawns, and rescanning every spawn's params took 43 s on a hub restart.
+  timeStartupPhase("db.backfill.spawn-registration", backfillSpawnRegistrationConfirmedOnce);
+
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS integration_registry (
+      name TEXT PRIMARY KEY,
+      display_name TEXT,
+      description TEXT,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      scopes TEXT NOT NULL DEFAULT '[]',
+      targets TEXT NOT NULL DEFAULT '[]',
+      channels TEXT NOT NULL DEFAULT '[]',
+      type TEXT,
+      icon TEXT,
+      accent_color TEXT,
+      tags TEXT NOT NULL DEFAULT '[]',
+      homepage_url TEXT,
+      repository_url TEXT,
+      docs_url TEXT,
+      manifest TEXT NOT NULL DEFAULT '{}',
+      source TEXT NOT NULL DEFAULT 'api',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      last_event_at INTEGER,
+      last_task_at INTEGER,
+      last_auth_success_at INTEGER,
+      last_auth_failure_at INTEGER
+    )
+  `);
+
+  // #636 — persisted crash post-mortems. Own table, no FK to agents, so a death verdict outlives
+  // the offline-prune/reaper and stays retrievable by agentId.
+  ensureCrashReportsSchema();
+  migrateVaultSchema();
+  ensureLaunchFactsSchema();
+  ensureBudgetLineageSchema();
+  ensureSpawnTreeStopSchema();
+
+  // #645 — clean terminal markers (sibling of crash_reports). Own table, no FK, so an EXPECTED
+  // terminus (transient reap after land, graceful shutdown) outlives the reaper and lets the #634
+  // watchdog tell a benign completion from a silent death. Idempotent CREATE IF NOT EXISTS.
+  ensureTerminalEventsSchema();
+  ensureWebToolCallsSchema();
+
+  // First-class human users (#388 keystone #393): ensure the table (single DDL home in users.ts)
+  // and seed the admin-level default user mapped to the existing single human. P0 + idempotent —
+  // bare 'user' == user:default resolve to users.id='default' via the SDK resolver; no bytes move.
+  ensureUsersSchema();
+  seedDefaultUser();
+
+  // Pluggable login identities (#389): the (provider, provider_subject) → users.id map behind real
+  // login + sessions. Ensured right after the user seed (FK → users) and idempotent — an old
+  // single-user DB gains it empty, and the god-token break-glass keeps working with zero rows.
+  ensureAuthIdentitiesSchema();
+  // Single-use invites (#3567): additive, empty until an admin turns invites on.
+  ensureUserInvitesSchema();
+
+  // Agent ownership/visibility table (#392). FK-references both agents and users, so it ensures
+  // AFTER both exist. The backfill (seedDefaultAgentOwnership) runs below, once the built-in
+  // agents are in, so they can be excluded from ownership.
+  ensureAgentOwnershipSchema();
+
+  // Per-agent drive lease — the "X is driving this agent" soft-lock (#394). FK-references agents,
+  // so it ensures after the agents table exists. Empty in a single-user world (the arbiter never
+  // writes it), so it adds nothing to the legacy flow.
+  ensureDriveLeaseSchema();
+
+  // #652 — epoch column on terminal_events: a stale event from a prior epoch must NOT suppress the
+  // heartbeat-gap alert for a genuine silent death in a later epoch (agent_id reuse across epochs).
+  // Default 0 preserves the suppression behaviour for all existing rows written before this migration.
+  const terminalEventCols = (getDb().query("PRAGMA table_info(terminal_events)").all() as any[]).map((c: any) => c.name);
+  if (!terminalEventCols.includes("epoch")) {
+    getDb().run("ALTER TABLE terminal_events ADD COLUMN epoch INTEGER NOT NULL DEFAULT 0");
+    getDb().run("CREATE INDEX IF NOT EXISTS idx_terminal_events_agent ON terminal_events(agent_id, epoch, created_at DESC)");
+  }
+
+  // Built-in agents — registered unconditionally so sends from these ids
+  // pass the sendMessage validation. The reaper exempts these by checking
+  // meta.builtin (or by id for "user").
+  const now = Date.now();
+  const builtinStmt = getDb().query(`
+    INSERT INTO agents (id, name, kind, tags, machine, rig, capabilities, ready, status, meta, lifecycle, last_seen, created_at)
+    VALUES (?, ?, ?, ?, NULL, NULL, '[]', 1, 'online', '{"builtin":true}', 'persistent', ?, ?)
+    ON CONFLICT(id) DO UPDATE SET status = 'online', ready = 1, last_seen = excluded.last_seen
+  `);
+  builtinStmt.run("user", "User", "user", '["human"]', now, now);
+  builtinStmt.run("system", "System", "system", '["system"]', now, now);
+
+  // #3567 H7: legacy agents stay visible to admins; sharing with other users is explicit.
+  seedDefaultAgentOwnership();
+
+  // #652 follow-up — the epoch migration above used CREATE INDEX IF NOT EXISTS, but existing prod
+  // DBs already had idx_terminal_events_agent under the old (agent_id, created_at DESC) shape from
+  // #645; that made the new three-column definition a silent no-op. Drop-and-recreate forces the
+  // correct shape on all DB vintages; fresh DBs already carry the right shape and are unaffected.
+  getDb().run("DROP INDEX IF EXISTS idx_terminal_events_agent");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_terminal_events_agent ON terminal_events(agent_id, epoch, created_at DESC)");
+
+  // #361 — persistent Relay scheduler. Keep this append-only at the end: older DBs may
+  // have reached this point through many schema vintages, and the table references messages.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS scheduled_timers (
+      id TEXT PRIMARY KEY,
+      target TEXT NOT NULL,
+      created_by TEXT NOT NULL,
+      created_by_kind TEXT NOT NULL,
+      created_by_scopes TEXT NOT NULL DEFAULT '[]',
+      created_by_constraints TEXT,
+      delivery_from TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      next_run_at INTEGER NOT NULL,
+      schedule_kind TEXT NOT NULL,
+      schedule_def TEXT NOT NULL,
+      message_kind TEXT,
+      channel TEXT,
+      subject TEXT,
+      body TEXT NOT NULL,
+      claimable INTEGER NOT NULL DEFAULT 0,
+      payload TEXT NOT NULL DEFAULT '{}',
+      meta TEXT NOT NULL DEFAULT '{}',
+      enabled INTEGER NOT NULL DEFAULT 1,
+      run_count INTEGER NOT NULL DEFAULT 0,
+      max_runs INTEGER,
+      expires_at INTEGER,
+      last_run_at INTEGER,
+      last_error TEXT,
+      consecutive_failures INTEGER NOT NULL DEFAULT 0,
+      idempotency_key TEXT,
+      correlation_id TEXT NOT NULL,
+      last_message_id INTEGER REFERENCES messages(id),
+      claimed_by TEXT,
+      claim_expires_at INTEGER,
+      command TEXT,
+      message_authority_frozen INTEGER NOT NULL DEFAULT 0
+        CHECK (message_authority_frozen IN (0, 1) AND (command IS NULL OR message_authority_frozen = 0))
+    )
+  `);
+  const scheduledTimerCols = (getDb().query("PRAGMA table_info(scheduled_timers)").all() as any[]).map((c: any) => c.name);
+  if (!scheduledTimerCols.includes("message_kind")) {
+    getDb().run("ALTER TABLE scheduled_timers ADD COLUMN message_kind TEXT");
+  }
+  if (!scheduledTimerCols.includes("channel")) {
+    getDb().run("ALTER TABLE scheduled_timers ADD COLUMN channel TEXT");
+  }
+  if (!scheduledTimerCols.includes("claimable")) {
+    getDb().run("ALTER TABLE scheduled_timers ADD COLUMN claimable INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!scheduledTimerCols.includes("meta")) {
+    getDb().run("ALTER TABLE scheduled_timers ADD COLUMN meta TEXT NOT NULL DEFAULT '{}'");
+  }
+  if (!scheduledTimerCols.includes("command")) {
+    getDb().run("ALTER TABLE scheduled_timers ADD COLUMN command TEXT");
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_due ON scheduled_timers(enabled, next_run_at, claim_expires_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_creator ON scheduled_timers(created_by, enabled, next_run_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_correlation ON scheduled_timers(correlation_id)");
+
+  // #834 — grow `tasks` into the durable Task entity. Additive, kind-fenced columns:
+  // existing rows default to kind='claim'/deliverable_stage='none', so every legacy
+  // claim path is byte-for-byte unaffected. The claim-lease machinery filters kind='claim'.
+  const durableTaskCols = (getDb().query("PRAGMA table_info(tasks)").all() as any[]).map((c: any) => c.name);
+  const addTaskCol = (name: string, ddl: string) => {
+    if (!durableTaskCols.includes(name)) getDb().run(`ALTER TABLE tasks ADD COLUMN ${ddl}`);
+  };
+  addTaskCol("kind", "kind TEXT NOT NULL DEFAULT 'claim'");
+  addTaskCol("intent", "intent TEXT");
+  addTaskCol("complexity", "complexity TEXT");
+  addTaskCol("context", "context TEXT");
+  addTaskCol("latest_steer", "latest_steer TEXT");
+  addTaskCol("deliverable_stage", "deliverable_stage TEXT NOT NULL DEFAULT 'none'");
+  addTaskCol("blocked_by", "blocked_by TEXT");
+  addTaskCol("branch", "branch TEXT");
+  addTaskCol("commits", "commits TEXT");
+  addTaskCol("done_when", "done_when TEXT");
+  addTaskCol("team_id", "team_id TEXT");
+  addTaskCol("project_id", "project_id TEXT");
+  addTaskCol("repo", "repo TEXT");
+  addTaskCol("created_by", "created_by TEXT");
+  addTaskCol("owner_agent_id", "owner_agent_id TEXT");
+  addTaskCol("owner_agent_label", "owner_agent_label TEXT");
+  addTaskCol("dispatch", "dispatch TEXT");
+  addTaskCol("reaped_at", "reaped_at INTEGER");
+  // #1535 WS2 — tags[] (JSON array of strings) + priority. Additive/idempotent, same
+  // addTaskCol guard as the rest of the #834 batch: existing rows read back as absent.
+  addTaskCol("tags", "tags TEXT");
+  addTaskCol("priority", "priority TEXT");
+  // #1535 WS1 — parent/epic tree edge. Self-referential FK via ALTER TABLE ADD COLUMN is
+  // proven safe in this codebase already (messages.reply_to above); cycle-guarding lives
+  // in application code (task-entity.ts), not a DB constraint.
+  addTaskCol("parent_task_id", "parent_task_id INTEGER REFERENCES tasks(id) ON DELETE SET NULL");
+  // #1535 WS3 — backlog lifecycle axis (backlog|promoted). Additive/idempotent, same guard as
+  // the tags/priority/parent batch above; existing rows read back as NULL (not backlog-managed).
+  addTaskCol("backlog_state", "backlog_state TEXT");
+  // #2518 — coordinator review-hold (temporary landBlocked). Additive/idempotent; the
+  // NOT NULL DEFAULT 0 migration preserves every pre-existing Task as UNHELD, so no legacy
+  // delivery behavior changes until a coordinator explicitly sets the hold.
+  addTaskCol("review_hold", "review_hold INTEGER NOT NULL DEFAULT 0 CHECK (review_hold IN (0, 1))");
+  addTaskCol("validation_items", "validation_items TEXT");
+  addTaskCol("terminal_stage", "terminal_stage TEXT");
+  addTaskCol("completed_at", "completed_at INTEGER");
+  addTaskCol("owner", "owner TEXT"); // #2862 — backfilled by backfillTaskOwners below
+  migratePlanBlurbsOnStartup(); // #2082 S5 — fold legacy bound-node blurbs before stripping them
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_message_status ON tasks(message_id, status) WHERE message_id IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_kind ON tasks(kind, status, updated_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_branch ON tasks(branch) WHERE branch IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_team ON tasks(team_id) WHERE team_id IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_owner ON tasks(owner) WHERE owner IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_assignee ON tasks(owner_agent_id, updated_at) WHERE owner_agent_id IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_project ON tasks(project_id, status, updated_at) WHERE project_id IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_repo ON tasks(repo, status, updated_at) WHERE repo IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority, status, updated_at) WHERE priority IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_parent ON tasks(parent_task_id) WHERE parent_task_id IS NOT NULL");
+  // #1535 WS3 — the per-project prioritized backlog query filters on backlog_state and orders by
+  // priority,updated: a partial index over the backlog-managed rows keyed to that access path.
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_backlog ON tasks(backlog_state, project_id, priority, updated_at) WHERE backlog_state IS NOT NULL");
+  // #1355 — permanent land attribution must outlive ephemeral worker/workspace rows.
+  // No foreign keys by design: retention may delete those source rows at any time.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS landing_receipts (
+      id TEXT PRIMARY KEY,
+      project_id TEXT,
+      repo TEXT NOT NULL,
+      ref TEXT NOT NULL,
+      branch TEXT,
+      base_sha TEXT,
+      tip_sha TEXT,
+      commit_shas TEXT NOT NULL CHECK (json_valid(commit_shas) AND json_type(commit_shas) = 'array'),
+      workspace_id TEXT NOT NULL,
+      task_id INTEGER,
+      worker_agent_id TEXT,
+      coordinator_agent_id TEXT,
+      team_id TEXT,
+      orchestrator_id TEXT,
+      host TEXT,
+      landed_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_landing_receipts_repo_tip ON landing_receipts(repo, tip_sha)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_landing_receipts_repo_landed ON landing_receipts(repo, landed_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_landing_receipts_task ON landing_receipts(task_id) WHERE task_id IS NOT NULL");
+
+  // #1355 U3 — existing relay databases need the CI incident core too. Additive
+  // and independently idempotent, same shape as the fresh-DB bootstrap in
+  // schema.ts. The two partial unique indexes are the durable lease: SQLite
+  // itself rejects a second non-resolved row for the same watch (or the same
+  // watch+fingerprint pair).
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS ci_watch_state (
+      watch_key TEXT PRIMARY KEY,
+      provider TEXT NOT NULL,
+      repository TEXT NOT NULL,
+      branch TEXT NOT NULL,
+      workflow TEXT NOT NULL,
+      status TEXT NOT NULL CHECK (status IN ('green', 'failing', 'cancelled', 'pending', 'missing')),
+      head_sha TEXT NOT NULL,
+      observed_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_ci_watch_state_repo ON ci_watch_state(repository, branch, workflow)");
+
+  // #1609 — never-matched watch visibility, additive to existing ci_watch_state rows.
+  const ciWatchStateCols = getDb().query("PRAGMA table_info(ci_watch_state)").all() as any[];
+  const ciWatchStateColNames = ciWatchStateCols.map((c: any) => c.name);
+  if (!ciWatchStateColNames.includes("first_seen_at")) {
+    getDb().run("ALTER TABLE ci_watch_state ADD COLUMN first_seen_at INTEGER NOT NULL DEFAULT 0");
+    // Backfill: treat every pre-existing row as already seen at its last observation, so an
+    // upgrade never retroactively starts a fresh never-matched grace window for a watch that
+    // already has real history.
+    getDb().run("UPDATE ci_watch_state SET first_seen_at = observed_at WHERE first_seen_at = 0");
+  }
+  const hadHasMatched = ciWatchStateColNames.includes("has_matched");
+  if (!hadHasMatched) {
+    getDb().run("ALTER TABLE ci_watch_state ADD COLUMN has_matched INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!ciWatchStateColNames.includes("never_matched_notified_at")) {
+    getDb().run("ALTER TABLE ci_watch_state ADD COLUMN never_matched_notified_at INTEGER");
+  }
+  if (!ciWatchStateColNames.includes("config_mismatch_notified_at")) {
+    getDb().run("ALTER TABLE ci_watch_state ADD COLUMN config_mismatch_notified_at INTEGER");
+  }
+  if (!ciWatchStateColNames.includes("root_missing_notified_at")) {
+    getDb().run("ALTER TABLE ci_watch_state ADD COLUMN root_missing_notified_at INTEGER");
+  }
+  if (!hadHasMatched) {
+    getDb().run("UPDATE ci_watch_state SET has_matched = 1 WHERE status != 'missing'");
+  }
+  // #1682 — #1616 originally put this inside the `has_matched` ALTER branch, leaving rows on a
+  // database that had already received #1609 with a null fire-once guard. Those rows false-page
+  // on the first post-deploy poll, so seed every still-unseeded pre-existing missing row here.
+  getDb().run("UPDATE ci_watch_state SET never_matched_notified_at = updated_at WHERE has_matched = 0 AND never_matched_notified_at IS NULL");
+
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS ci_incidents (
+      id TEXT PRIMARY KEY,
+      watch_key TEXT NOT NULL,
+      provider TEXT NOT NULL,
+      repository TEXT NOT NULL,
+      branch TEXT NOT NULL,
+      workflow TEXT NOT NULL,
+      fingerprint TEXT NOT NULL,
+      state TEXT NOT NULL CHECK (state IN ('detected', 'attributed', 'notified', 'steward_attempting', 'escalated', 'resolved')),
+      attempt INTEGER NOT NULL DEFAULT 0 CHECK (attempt >= 0),
+      opened_at INTEGER NOT NULL,
+      opened_head_sha TEXT NOT NULL,
+      opened_conclusion TEXT,
+      coordinator_agent_id TEXT,
+      escalated_at INTEGER,
+      escalation_reason TEXT,
+      resolved_at INTEGER,
+      resolved_head_sha TEXT,
+      resolution TEXT,
+      lease_owner TEXT,
+      lease_token TEXT,
+      lease_acquired_at INTEGER,
+      lease_expires_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      CHECK ((state = 'resolved') = (resolved_at IS NOT NULL)),
+      CHECK (
+        (lease_owner IS NULL AND lease_token IS NULL AND lease_acquired_at IS NULL AND lease_expires_at IS NULL)
+        OR
+        (lease_owner IS NOT NULL AND lease_token IS NOT NULL AND lease_acquired_at IS NOT NULL AND lease_expires_at > lease_acquired_at)
+      )
+    )
+  `);
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_ci_incidents_active_watch ON ci_incidents(watch_key) WHERE state != 'resolved'");
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_ci_incidents_active_fingerprint ON ci_incidents(watch_key, fingerprint) WHERE state != 'resolved'");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_ci_incidents_repo ON ci_incidents(repository, branch, workflow, state)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_ci_incidents_lease ON ci_incidents(state, lease_expires_at) WHERE lease_owner IS NOT NULL");
+
+  getDb().run(`
+    UPDATE tasks
+    SET repo = (
+      SELECT ir.repo
+      FROM issue_associations ia
+      JOIN issue_refs ir ON ir.id = ia.issue_ref_id
+      WHERE ia.entity_type = 'task' AND ia.entity_id = CAST(tasks.id AS TEXT)
+      ORDER BY ia.created_at ASC, ir.id ASC
+      LIMIT 1
+    )
+    WHERE kind = 'deliverable'
+      AND (repo IS NULL OR trim(repo) = '')
+      AND EXISTS (
+        SELECT 1 FROM issue_associations ia
+        JOIN issue_refs ir ON ir.id = ia.issue_ref_id
+        WHERE ia.entity_type = 'task' AND ia.entity_id = CAST(tasks.id AS TEXT)
+      )
+  `);
+  getDb().run(`
+    UPDATE tasks
+    SET project_id = (
+      SELECT p.id
+      FROM projects p
+      WHERE p.scope = 'project' AND p.issue_repo = tasks.repo
+      ORDER BY p.created_at ASC, p.id ASC
+      LIMIT 1
+    )
+    WHERE kind = 'deliverable'
+      AND (project_id IS NULL OR trim(project_id) = '')
+      AND repo IS NOT NULL AND trim(repo) <> ''
+      AND EXISTS (
+        SELECT 1 FROM projects p
+        WHERE p.scope = 'project' AND p.issue_repo = tasks.repo
+      )
+  `);
+
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS task_dependencies (
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      depends_on_task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (task_id, depends_on_task_id)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_task_dependencies_depended ON task_dependencies(depends_on_task_id)");
+  // #3692 — per-edge required stage; NULL keeps the original meaning (landed-on-main).
+  if (!(getDb().query("PRAGMA table_info(task_dependencies)").all() as Array<{ name: string }>).some((c) => c.name === "required_stage")) getDb().run("ALTER TABLE task_dependencies ADD COLUMN required_stage TEXT CHECK (required_stage IN ('landed-on-main','deployed'))");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_task_events_task_type ON task_events(task_id, type, id DESC)");
+
+  // #1275 — existing relay databases need the fleet deploy ledger too. Keep this
+  // additive and independently idempotent: a failed/partial deploy must survive
+  // restarts instead of being inferred from ephemeral orchestrator activity.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS deploy_events (
+      id TEXT PRIMARY KEY,
+      commit_sha TEXT NOT NULL,
+      version TEXT,
+      hosts TEXT NOT NULL,
+      status TEXT NOT NULL CHECK (status IN ('pending', 'succeeded', 'failed', 'rolled-back')),
+      initiated_by TEXT NOT NULL,
+      started_at INTEGER NOT NULL,
+      finished_at INTEGER
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_deploy_events_commit ON deploy_events(commit_sha, started_at DESC)");
+  // #1744 / Phase -1 F1 — existing relay databases need the tree-keyed land-gate attestation store
+  // that lets cd-watcher deploy a landed tree without waiting for main's redundant ci.yml re-run.
+  // Purely additive: with the table empty (or absent on an older binary) every deploy decision falls
+  // back to the pre-existing green-ci.yml path, which is the fail-closed default.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS land_gate_attestations (
+      repo TEXT NOT NULL,
+      tree_sha TEXT NOT NULL,
+      commit_sha TEXT NOT NULL,
+      base_ref TEXT NOT NULL,
+      level TEXT NOT NULL CHECK (level IN ('full')),
+      gates_digest TEXT NOT NULL,
+      gate_names TEXT NOT NULL CHECK (json_valid(gate_names) AND json_type(gate_names) = 'array'),
+      gates_ran INTEGER NOT NULL,
+      workspace_id TEXT,
+      attested_at INTEGER NOT NULL,
+      PRIMARY KEY (repo, tree_sha)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_land_gate_attestations_attested ON land_gate_attestations(attested_at)");
+  // #3362 — NULL is a pre-S1 attestation, which only a full land gate produced.
+  if (!(getDb().query("PRAGMA table_info(land_gate_attestations)").all() as Array<{ name: string }>).some((col) => col.name === "suite_coverage")) {
+    getDb().run("ALTER TABLE land_gate_attestations ADD COLUMN suite_coverage TEXT CHECK (suite_coverage IN ('full', 'partial'))");
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_land_gate_attestations_partial_commit ON land_gate_attestations(repo, commit_sha) WHERE suite_coverage = 'partial'");
+  // #1281 — repair historical duplicate pending rows before imposing the
+  // fleet-wide deploy lease invariant.
+  getDb().run(`UPDATE deploy_events SET status = 'failed', finished_at = COALESCE(finished_at, started_at)
+    WHERE status = 'pending' AND id NOT IN (
+      SELECT id FROM deploy_events WHERE status = 'pending' ORDER BY started_at DESC LIMIT 1
+    )`);
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_deploy_events_single_pending ON deploy_events(status) WHERE status = 'pending'");
+  // #1327 — additive column for existing DBs; deploy history reconstructs "what changed" from it.
+  const deployEventsColNames = (getDb().query("PRAGMA table_info(deploy_events)").all() as any[]).map((c: any) => c.name);
+  if (!deployEventsColNames.includes("previous_sha")) {
+    getDb().run("ALTER TABLE deploy_events ADD COLUMN previous_sha TEXT");
+  }
+  // #1799 — durable, range-keyed deploy attribution. Existing successful rows are
+  // deliberately left NULL for the detached cd-watcher's bounded backfill.
+  if (!deployEventsColNames.includes("changes_summary")) {
+    getDb().run("ALTER TABLE deploy_events ADD COLUMN changes_summary TEXT");
+  }
+  // #2105 — the deploy driver's process identity, so a stranded `pending` row can be reclaimed on
+  // EXECUTOR LIVENESS instead of waiting out the 2h lease. Nullable and additive: rows written by an
+  // older driver (and the window before the driver records itself) simply have no executor, and the
+  // reconcile degrades to the pre-existing lease-TTL backstop.
+  if (!deployEventsColNames.includes("executor")) getDb().run("ALTER TABLE deploy_events ADD COLUMN executor TEXT");
+  // #2359 — `started_at` is immutable audit history. Older code reused it as the renewable lease
+  // clock, hiding five minutes from every long deploy shown in the dashboard.
+  if (!deployEventsColNames.includes("lease_renewed_at")) getDb().run("ALTER TABLE deploy_events ADD COLUMN lease_renewed_at INTEGER");
+
+  // #833 — comment-through idempotency outbox (reserve→post→finalize). Existing DBs gain
+  // the table here; the UNIQUE claim is what makes the write-through concurrency/crash-safe.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS task_comment_throughs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      kind TEXT NOT NULL,
+      idempotency_key TEXT NOT NULL,
+      status TEXT NOT NULL,
+      event_id INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE (task_id, kind, idempotency_key)
+    )
+  `);
+
+  // #1452 round-4/round-5 — durable review-ref lifecycle ledger. Schema + its round-5 id-keyed
+  // migration live in the domain module (per epic #291), next to its accessors.
+  ensureReviewRefCleanupsSchema();
+
+  // #834 — issue_associations.entity_type gained 'task'. The CHECK constraint is baked into
+  // the table SQL, so a TS-only enum change would fail at runtime; rebuild the table (SQLite
+  // can't ALTER a CHECK). Guarded on the absence of 'task' in the stored DDL so it runs once.
+  const issueAssocSql = (getDb().query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'issue_associations'").get() as { sql?: string } | undefined)?.sql;
+  if (issueAssocSql && !issueAssocSql.includes("'task'")) {
+    getDb().transaction(() => {
+      getDb().run("ALTER TABLE issue_associations RENAME TO issue_associations_old");
+      getDb().run(`
+        CREATE TABLE issue_associations (
+          issue_ref_id TEXT NOT NULL REFERENCES issue_refs(id) ON DELETE CASCADE,
+          entity_type TEXT NOT NULL CHECK (entity_type IN ('team', 'plan-node', 'epic', 'task')),
+          entity_id TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          PRIMARY KEY (issue_ref_id, entity_type, entity_id)
+        )
+      `);
+      getDb().run(`
+        INSERT INTO issue_associations (issue_ref_id, entity_type, entity_id, created_at)
+        SELECT issue_ref_id, entity_type, entity_id, created_at FROM issue_associations_old
+      `);
+      getDb().run("DROP TABLE issue_associations_old");
+    })();
+    getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_associations_entity ON issue_associations(entity_type, entity_id, created_at DESC)");
+    getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_associations_issue ON issue_associations(issue_ref_id, created_at DESC)");
+  }
+
+  ensureIssueAssociationRelationSchema();
+  // #846 — drop the superseded single-column indexes so the planner is forced to
+  // choose the composite replacements (idx_msg_to_id / idx_msg_resolved_to_id).
+  // When both old and new exist the planner may prefer the old single-column index,
+  // silently defeating the ORDER BY id optimisation.  DROP INDEX IF EXISTS is
+  // idempotent and safe on any populated DB.  Guard ANALYZE on the presence of the
+  // old idx_msg_to: it exists on pre-#846 DBs and is absent once this block has run,
+  // so ANALYZE executes exactly once per DB (on first boot with the new code).
+  // Fresh DBs never create idx_msg_to (removed from base schema), so the guard is
+  // false and ANALYZE is skipped (the first-boot `if (!hasStats)` path in initDb
+  // covers fresh DBs instead).
+  const hasOldToIdx = !!getDb()
+    .query("SELECT 1 FROM sqlite_master WHERE type='index' AND name='idx_msg_to'")
+    .get();
+  getDb().run("DROP INDEX IF EXISTS idx_msg_to");
+  getDb().run("DROP INDEX IF EXISTS idx_msg_resolved_to_agent"); getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_target_updated ON commands(target, updated_at DESC, created_at DESC)"); const commandColNames = (getDb().query("PRAGMA table_info(commands)").all() as Array<{ name: string }>).map((col) => col.name); if (!commandColNames.includes("claim_owner_token")) getDb().run("ALTER TABLE commands ADD COLUMN claim_owner_token TEXT"); getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_claim_recovery ON commands(target, status, claim_owner_token)"); // #1811 ambiguous-claim recovery
+  // T4060 (#2289) — partial index for the scheduler-restart reconcile's awaiting-wake scan
+  // (target + error over failed scheduler.commands only). Idempotent; existing DBs (incl. the
+  // 4.5GB prod hub) build it once at startup. Base schema covers fresh DBs (schema.ts).
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_scheduler_recovery ON commands(target, error) WHERE type = 'scheduler.command' AND status = 'failed'");
+  // Build once, pre-bind on fresh and upgraded DBs, with the actual build timed (#3063).
+  timeStartupPhase("db.index.commands-target-type", () => getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_target_type_created ON commands(target, type, created_at DESC, id DESC)"));
+  timeStartupPhase("db.index.spawn-request", () => getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_spawn_request ON commands(json_extract(params, '$.spawnRequestId')) WHERE type = 'agent.spawn' AND json_valid(params)"));
+  timeStartupPhase("db.index.spawn-resume-branch", () => getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_spawn_resume_branch ON commands(json_extract(params, '$.resumeWorkspace.branch')) WHERE type = 'agent.spawn' AND json_valid(params) AND json_extract(params, '$.resumeWorkspace.branch') IS NOT NULL")); // #3011 reviewer-by-branch link
+  timeStartupPhase("db.index.restart-spawn-request", () => getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_restart_spawn_request ON commands(json_extract(params, '$.restartSpawn.spawnRequestId')) WHERE type IN ('agent.restart', 'agent.resume') AND json_valid(params)")); // #2950 H3
+  timeStartupPhase("db.index.relaunch-agent", () => getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_relaunch_agent ON commands(json_extract(params, '$.agentId')) WHERE type IN ('agent.restart', 'agent.resume') AND json_valid(params)")); // #2712 launch lookup by agent
+  // T4060 (#2289) — composite index serving the project-entries active-only display
+  // ORDER BY from the index, so the sort never visits a cell's ~95% retracted rows.
+  // Idempotent; existing DBs build it once at startup. Base schema covers fresh DBs.
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_project_entries_active_order ON project_entries(project_id, status, updated_at DESC, created_at DESC, id DESC)");
+  installProjectEntrySearch(getDb());
+  migrateBrokerMemories(getDb());
+  if (hasOldToIdx) getDb().run("ANALYZE messages");
+
+  // #1645 — maintenance-job pause storage, and the one-time conversion of any pre-existing
+  // hand-written `UPDATE maintenance_jobs SET enabled=0` into an explicit indefinite pause row.
+  //
+  // ORDER IS LOAD-BEARING. `ensureMaintenanceJobs()` (src/maintenance/scheduler.ts) now re-asserts
+  // `enabled` from `definitions` on every reconcile, which is what makes a manual disable
+  // recoverable instead of permanent. That reconcile runs when the scheduler starts — after
+  // migrations — so this conversion MUST happen here, before it. Landing the upsert change without
+  // this conversion would silently re-enable a job an operator had deliberately stopped.
+  const maintenanceJobCols = (getDb().query("PRAGMA table_info(maintenance_jobs)").all() as Array<{ name: string }>).map((c) => c.name);
+  if (!maintenanceJobCols.includes("critical")) {
+    getDb().run("ALTER TABLE maintenance_jobs ADD COLUMN critical INTEGER NOT NULL DEFAULT 0");
+  }
+  // #1725 P1 — measured per-run synchronous block time (loop occupancy), distinct from the
+  // wall-clock last_duration_ms. Additive/idempotent; existing rows read back NULL until they run.
+  if (!maintenanceJobCols.includes("last_block_ms")) {
+    getDb().run("ALTER TABLE maintenance_jobs ADD COLUMN last_block_ms INTEGER");
+  }
+  // #2317 — deliberately leave existing rows NULL: an upgraded process cannot honestly infer
+  // whether a pre-upgrade run is still making progress, and recovery must fail toward retaining it.
+  if (!maintenanceJobCols.includes("run_token")) {
+    getDb().run("ALTER TABLE maintenance_jobs ADD COLUMN run_token TEXT");
+  }
+  if (!maintenanceJobCols.includes("last_progress_at")) {
+    getDb().run("ALTER TABLE maintenance_jobs ADD COLUMN last_progress_at INTEGER");
+  }
+  ensureMaintenanceJobPauseSchema(); convertManualJobDisablesToPauses();
+
+  // RFC 0001 / S4 §6 — dedicated durable-workflow replay storage. This is
+  // intentionally not bus_outbox: message-bus pruning must never erase an open
+  // instance's execution history. The ensure also rebuilds the original cascading
+  // journal FK so direct parent deletes cannot erase an open replay history.
+  getDb().run(PLAN_DISPATCH_SCHEMA_SQL);
+  ensureWorkflowJournalSchema();
+
+  // KAPI-1 W4c fix 3b — the kernel event log (`kernel_events` / `kernel_event_scope_seq`) is
+  // created at STARTUP alongside the workflow journal, so a lazily-built control host (the
+  // `/api/kernel` mount + the `relay_kernel_*` MCP binding) never runs request-time DDL on an
+  // unauthorized first call. Idempotent against the shared prod schema.
+  ensureKernelEventLogSchema();
+
+  // Kernel timers MESSAGE-authority flip catalog (through Stage 8): dormant until an audited action.
+  installTimerMessageFlipSchema(); ensureProviderFlapMessagesIndex();
+
+  // #1538 — send-layer dead-letter ledger for the fire-outbox. Created alongside (but OUTSIDE) the
+  // flip catalog: it tracks per-fire send attempts so a permanently un-sendable fire dead-letters
+  // and leaves `listPending`, instead of re-failing every drain tick and flooding the logs.
+  ensureTimerMessageFireDeadLetterSchema();
+  ensureSqlAuditIndexes(); ensureMaintenanceIndexes(); ensureDurablePayloadSchema(); // #1725 indexes; ADR 0001 §3.7.1 dedup ledger (#3704 hour-slot layout)
+
+  retireMemoryStorage(getDb());
+
+  // #2591 — the structured project journal tables, installed for upgraded databases.
+  // Byte-identical to the fresh-DB catalog DDL in src/db/schema.ts (schema-parity asserted
+  // by migrations.test).
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS project_journal (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      profile TEXT NOT NULL,
+      field TEXT NOT NULL,
+      value TEXT NOT NULL,
+      updated_at INTEGER NOT NULL,
+      updated_by TEXT NOT NULL,
+      UNIQUE(project_id, profile, field)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_project_journal_scope ON project_journal(project_id, profile)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS project_journal_history (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id TEXT NOT NULL,
+      profile TEXT NOT NULL,
+      field TEXT NOT NULL,
+      old_value TEXT,
+      new_value TEXT,
+      action TEXT NOT NULL,
+      changed_at INTEGER NOT NULL,
+      changed_by TEXT NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_project_journal_history_scope ON project_journal_history(project_id, profile, field)");
+
+  // #2485 — the durable token-usage ledger, installed for upgraded databases. Byte-identical to
+  // the fresh-DB catalog DDL in src/db/schema.ts (schema-parity asserted by migrations.test).
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS session_token_usage (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      turn_id TEXT,
+      provider TEXT NOT NULL,
+      model TEXT NOT NULL,
+      input_tokens INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+      reasoning_output_tokens INTEGER,
+      created_at INTEGER NOT NULL,
+      dedupe_key TEXT NOT NULL
+    )
+  `);
+  if (!(getDb().query("PRAGMA table_info(session_token_usage)").all() as Array<{ name: string }>).some((c) => c.name === "task_id")) {
+    getDb().run("ALTER TABLE session_token_usage ADD COLUMN task_id INTEGER"); // #3011
+  }
+  if (!(getDb().query("PRAGMA table_info(session_token_usage)").all() as Array<{ name: string }>).some((c) => c.name === "subagent_id")) {
+    getDb().run("ALTER TABLE session_token_usage ADD COLUMN subagent_id TEXT"); // #3241
+  }
+  if (!(getDb().query("PRAGMA table_info(session_token_usage)").all() as Array<{ name: string }>).some((c) => c.name === "usage_status")) {
+    getDb().run("ALTER TABLE session_token_usage ADD COLUMN usage_status TEXT"); // #3351
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_session_token_usage_created ON session_token_usage(created_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_session_token_usage_provider_time ON session_token_usage(provider, created_at)");
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_session_token_usage_dedupe ON session_token_usage(dedupe_key)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_session_token_usage_agent ON session_token_usage(agent_id)");
+  getDb().run(CLAUDE_API_BUDGET_SCHEMA);
+  getDb().run(CLAUDE_APP_OAUTH_SCHEMA);
+  getDb().run(AGENT_EXIT_REPORT_SCHEMA);
+  getDb().run(CONTEXT_RESET_SCHEMA); // #3398
+  getDb().run(TASK_TOKEN_TOTALS_SCHEMA);
+  getDb().run(SHIPPING_STATS_SCHEMA);
+  getDb().run(CI_GATE_BACKFILL_SCHEMA); getDb().run(AGENT_GATE_RUNS_SCHEMA); ensureAgentGateCommandSchema(); repairRerunGateTimings(); ensureCiShaObservationsSchema();
+  migrateOperatorActionsSchema();
+  getDb().run(SELF_EFFORT_PERMISSIONS_SCHEMA);
+  getDb().run(AGENT_EFFORT_STATE_SCHEMA);
+  importLegacyEffortCommands();
+  ensureArtifactCreatorAgentColumn(); // #2952
+  ensureArtifactRetentionSchema();
+  installAgentIdentityArchive();
+  redactProviderConfigHistory(); finishSchema(); // #3540 — discard plaintext provider credentials from prior revisions
+  timeStartupPhase("db.backfill.task-autoclose", migrateDeployedTaskBacklog);
+  timeStartupPhase("db.backfill.task-shipped-blocked", migrateBlockedTaskBacklog);
+  timeStartupPhase("db.backfill.task-owner", backfillTaskOwners);
+  timeStartupPhase("db.backfill.team-project-seats", migrateTeamProjectSeats); // #3107
+  timeStartupPhase("db.backfill.legacy-messages", backfillLegacyMessages);
+  timeStartupPhase("db.backfill.history-delivery", () => installHistoryDeliverySettlement());
+  timeStartupPhase("db.projection.reply-obligations", () => installReplyObligations());
+}