@humwick/server 0.130.2 → 0.130.4

package/src/db/schema.ts

@@ -1,3 +1,5 @@
+import { COMMAND_RETENTION_SCHEMA } from "./command-retention";
+import { TOKEN_USAGE_RETENTION_SCHEMA } from "./token-usage-retention";
 import { DURABLE_PAYLOAD_SCHEMA } from "./durable-payloads"; import { PLAN_IMPORT_SCHEMA_SQL } from "./plan-import-schema";
 import { PROJECT_ROOTS_SCHEMA } from "./project-root-schema";
 import { seedBuiltInTokenProfiles } from "../token-db";
@@ -964,7 +966,6 @@ export function initDb(path: string = "agent-relay.db"): Database {
       shutdown_requested_at INTEGER
     );
     CREATE INDEX IF NOT EXISTS idx_automation_runs_automation ON automation_runs(automation_id, created_at);
-    CREATE INDEX IF NOT EXISTS idx_automation_runs_status ON automation_runs(status);
     CREATE INDEX IF NOT EXISTS idx_automation_runs_task ON automation_runs(task_id);
 
     CREATE TABLE IF NOT EXISTS task_events (
@@ -1264,6 +1265,8 @@ export function initDb(path: string = "agent-relay.db"): Database {
     ${PLAN_IMPORT_SCHEMA_SQL};
     ${IDLE_DIGEST_SCHEMA_SQL};
     ${TASK_TOKEN_TOTALS_SCHEMA};
+    ${TOKEN_USAGE_RETENTION_SCHEMA};
+    ${COMMAND_RETENTION_SCHEMA};
     ${LONG_RUNNING_WORK_SCHEMA};
     ${SHIPPING_STATS_SCHEMA};
     ${OPERATOR_ACTIONS_SCHEMA};

package/src/db/spawn-budget.ts

@@ -45,6 +45,11 @@ function observedTokens(agentIds: string[]): ObservedSubtreeSpend {
     COALESCE(SUM(usage_status IS NOT NULL), 0) AS unknownReports
     FROM session_token_usage WHERE agent_id IN (SELECT value FROM json_each(?))`)
     .get(ids) as { tokens: number; unknownReports: number };
+  const retired = getDb().query(`SELECT COALESCE(SUM(tokens), 0) AS tokens,
+    COALESCE(SUM(unknown_reports), 0) AS unknownReports FROM retired_token_usage_totals
+    WHERE agent_id IN (SELECT value FROM json_each(?))`).get(ids) as { tokens: number; unknownReports: number };
+  row.tokens += retired.tokens;
+  row.unknownReports += retired.unknownReports;
   const live = getDb().query(`SELECT COALESCE(SUM(status = 'busy'), 0) AS busyAgents,
     COALESCE(SUM(CASE WHEN json_valid(meta) THEN MAX(0, COALESCE(json_extract(meta, '$.unreportedTokenUsage'), 0)) ELSE 0 END), 0) AS unreportedReports
     FROM agents WHERE id IN (SELECT value FROM json_each(?))`)

package/src/db/spawn-delegation.ts

@@ -5,12 +5,11 @@ import { getPersistedAgentRuntimeCard as getAgent } from "./agent-card-read";
 import { getDb, ValidationError } from "./connection";
 import { runnerSpawnGrantForAgent } from "../runtime-grant";
 import { optionalNonNegativeInt } from "../validation";
-import { sameHostIdentity } from "../utils";
-import { getOrchestrator } from "./orchestrators";
 import { stringValue } from "@humwick/sdk";
 import type { CreateCommandInput } from "../types";
 import { getLaunchFact } from "./launch-facts";
 import { spawnProcessGoneSql } from "./spawn-process-evidence";
+import { WORKFLOW_EXECUTIONS_SQL } from "./workflow-execution";
 
 /** Read-only preflight runs before project or Task creation; the writer repeats it. */
 export function assertDelegatedSpawnTarget(input: CreateCommandInput) {
@@ -37,15 +36,7 @@ export function assertDelegatedSpawnTarget(input: CreateCommandInput) {
     return !agent || agent.status === "offline" || agent.meta?.lifecycleAction === "shutting-down";
   })) throw new ValidationError("SPAWN_SUBTREE_STOPPING: caller or ancestor has stopped");
   const projectId = delegatedProjectTarget(input, state);
-  const parentHost = stringValue(getAgent(parentId)?.machine);
-  const targetHost = stringValue(input.params?.orchestratorId);
-  if (parentHost && targetHost) {
-    // #3650: machine is the raw os.hostname() ("WBOX"); orchestrator identity is configured ("wbox"/"wbox-1").
-    const target = getOrchestrator(targetHost);
-    const sameHost = sameHostIdentity(parentHost, targetHost)
-      || (target && [target.id, target.hostname, target.agentId].some(identity => sameHostIdentity(identity, parentHost)));
-    if (!sameHost) throw new ValidationError("SPAWN_PROJECT_MISMATCH: delegated launches stay on their parent's host");
-  }
+  // #3769 — placement owns the host; delegatedProjectTarget checks its registered project checkout.
   if (state.depth === 1 && profile === "sub-coordinator") throw new ValidationError("SPAWN_DEPTH_EXCEEDED: sub-coordinators cannot delegate another coordinator");
   const workflow = Boolean(input.params?.workflowRunId);
   const grant = runnerSpawnGrantForAgent(parentId);
@@ -63,7 +54,7 @@ export function assertDelegatedSpawnAdmission(input: CreateCommandInput, now: nu
   if (input.type !== "agent.spawn") return;
   const workflowRunId = stringValue(input.params?.workflowRunId);
   const run = workflowRunId && getDb().query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'kernel_entity__workflow__run'").get()
-    ? getDb().query("SELECT callerAgentId, coordinator FROM kernel_entity__workflow__run WHERE scope = 'local' AND id = ?")
+    ? getDb().query(`SELECT callerAgentId, coordinator FROM ${WORKFLOW_EXECUTIONS_SQL} WHERE scope = 'local' AND id = ?`)
       .get(workflowRunId) as { callerAgentId: string | null; coordinator: string } | null : null;
   const origin = run?.callerAgentId ?? run?.coordinator;
   if (origin && participatesInSpawnDelegation(origin) && input.params?.spawnedBy !== origin) {

package/src/db/sql-audit-indexes.ts

@@ -44,6 +44,9 @@ export const SQL_AUDIT_INDEXES = [
   `CREATE INDEX IF NOT EXISTS idx_task_events_land_workspace ON task_events(json_extract(metadata, '$.workspaceId'))
     WHERE type = 'deliverable' AND json_extract(metadata, '$.land.requested') = 1`,
   LAND_WITHDRAWN_INDEX_SQL,
+  // #3779 spawnRequestId -> Task resolution (every register/land/deliver auth check): a full task_events scan blocked the loop.
+  `CREATE INDEX IF NOT EXISTS idx_task_events_spawn_request ON task_events(json_extract(metadata, '$.spawnRequestId'))
+    WHERE type = 'agent.spawn_requested'`,
   `CREATE INDEX IF NOT EXISTS idx_task_events_land_bound_workspace ON task_events(${LAND_WORKSPACE_EXPRESSION})
     WHERE type = 'deliverable' AND json_extract(metadata, '$.land.requested') = 1`,
   `CREATE INDEX IF NOT EXISTS idx_task_events_deliverable_workspace ON task_events(${LAND_WORKSPACE_EXPRESSION}, task_id)

package/src/db/stats-async.ts

@@ -117,7 +117,9 @@ export function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
   const detail = [
     `writer=${stats.writerBackend}`,
     `reader=${stats.readerBackend}`,
-    `onLoopOps=${specs.length - offLoop}; writerThreadOps=${offLoop}`,
+    // #3798 — the op split counts executed writes; the registered op definitions are named as such.
+    `onLoopOps=${stats.writer.onLoopOps}; writerThreadOps=${stats.writer.writerThreadOps}`,
+    `opDefinitions onLoop=${specs.length - offLoop} offLoop=${offLoop}`,
     `mainConnectionWrites1h=${JSON.stringify(writes)}`,
     ...(wedged ? [`writer wedged: op ${wedged.op} running ${Math.round(wedged.runningMs / 1000)}s`] : []),
     ...(shedCount > 0 ? [`${shedCount} reader shed(s)`] : []),
@@ -128,8 +130,8 @@ export function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
     deployRole: "load",
     detail,
     metrics: {
-      onLoopOps: specs.length - offLoop,
-      writerThreadOps: offLoop,
+      onLoopOps: stats.writer.onLoopOps,
+      writerThreadOps: stats.writer.writerThreadOps,
       mainConnectionWrites1h: Object.values(writes).reduce((sum, count) => sum + count, 0),
       mainConnectionBootWrites: mainConnectionBootWrites(),
       writerQueued: stats.writer.queued,

package/src/db/task-entity.ts

@@ -1085,14 +1085,15 @@ export function deliverableTaskIdsByOwnerAgent(agentId: string): number[] {
 // event (recorded BEFORE the child registers) carries the spawnRequestId. The landing worker's
 // `meta.spawnRequestId` resolves back through it to the Task. Returns every matching task id so a
 // reused spawnRequestId can't silently drop a link.
+export const TASK_IDS_BY_SPAWN_REQUEST_SQL = `SELECT DISTINCT te.task_id AS id FROM task_events te INDEXED BY idx_task_events_spawn_request
+            JOIN tasks t ON t.id = te.task_id AND t.kind = '${DELIVERABLE_TASK_KIND}'
+            WHERE te.type = 'agent.spawn_requested' AND json_extract(te.metadata, '$.spawnRequestId') = ?
+            ORDER BY te.task_id ASC`;
 export function deliverableTaskIdsBySpawnRequestId(spawnRequestId: string): number[] {
   const cleaned = spawnRequestId?.trim();
   if (!cleaned) return [];
   return (getDb()
-    .query(`SELECT DISTINCT te.task_id AS id FROM task_events te
-            JOIN tasks t ON t.id = te.task_id AND t.kind = '${DELIVERABLE_TASK_KIND}'
-            WHERE te.type = 'agent.spawn_requested' AND json_extract(te.metadata, '$.spawnRequestId') = ?
-            ORDER BY te.task_id ASC`)
+    .query(TASK_IDS_BY_SPAWN_REQUEST_SQL)
     .all(cleaned) as Array<{ id: number }>)
     .map((r) => r.id);
 }

package/src/db/team-claim-policy.ts

@@ -0,0 +1,60 @@
+import { STALE_TTL_MS } from "../config";
+import { getAgent } from "./agents";
+import { countLiveTeamMembers, getTeam, claimTeamWithAdoption, isClaimableTeam } from "./teams";
+import type { Team } from "../types";
+export class TeamAuthError extends Error {}
+export class TeamNotFoundError extends Error {}
+function lineageRootForAgent(agentId: string): string | undefined {
+  let current = getAgent(agentId);
+  const seen = new Set<string>();
+  while (current) {
+    if (seen.has(current.id)) return undefined;
+    seen.add(current.id);
+    if (!current.spawnedBy) return current.id;
+    current = getAgent(current.spawnedBy);
+  }
+  return undefined;
+}
+
+function coordinatorIsLive(team: Team): boolean {
+  if (!team.coordinatorId) return false;
+  const coordinator = getAgent(team.coordinatorId);
+  if (!coordinator || coordinator.status === "offline") return false;
+  if (coordinator.teamId === team.id) return countLiveTeamMembers(team.id, Date.now() - STALE_TTL_MS) > 0;
+  return coordinator.lastSeen > Date.now() - STALE_TTL_MS;
+}
+
+/** How a claim was authorized — carried into the audit trail so an orphan takeover is
+ * distinguishable from a routine same-lineage reclaim. */
+export type TeamClaimMode = "admin" | "same-lineage" | "orphan-takeover";
+
+// #1454 — live owners require same-lineage authority; dead owners permit orphan takeover.
+
+function assertCanClaimTeam(admin: boolean, team: Team, callerAgentId: string): TeamClaimMode {
+  const caller = getAgent(callerAgentId);
+  const callerTeam = caller?.teamId ? getTeam(caller.teamId) : null;
+  if (!admin && callerTeam?.parentTeamId && team.id !== callerTeam.id) {
+    throw new TeamAuthError("a sub-coordinator may claim only its own private team");
+  }
+  const callerRoot = lineageRootForAgent(callerAgentId);
+  const teamRoot = team.rootCoordinatorId ?? team.coordinatorId;
+  // Same-lineage reclaim is the routine fast path (a replacement spawned under the original
+  // founder) and stays allowed regardless of owner liveness.
+  if (callerRoot && teamRoot && callerRoot === teamRoot) return "same-lineage";
+  if (admin) return "admin";
+  // #1454 orphan takeover: a replacement coordinator of a DIFFERENT lineage may adopt the team only
+  // when its owning coordinator is not live (offline, or stale past the heartbeat TTL). This is the
+  // sole security boundary for the cross-lineage path — a healthy owner is never displaced.
+  if (!coordinatorIsLive(team)) return "orphan-takeover";
+  throw new TeamAuthError(`caller ${callerAgentId} cannot claim team ${team.id}`);
+}
+
+
+export function claimAuthorizedTeam(teamId: string, agentId: string, admin: boolean) {
+  if (!isClaimableTeam(getTeam(teamId))) throw new TeamNotFoundError(`active team ${teamId} not found`);
+  let captured: { mode: TeamClaimMode; priorCoordinatorId: string | null } | undefined;
+  const result = claimTeamWithAdoption(teamId, agentId, team => {
+    captured = { mode: assertCanClaimTeam(admin, team, agentId), priorCoordinatorId: team.coordinatorId ?? null };
+  });
+  return { ...result, ...captured! };
+}

package/src/db/teams-async.ts

@@ -56,3 +56,7 @@ export function setTeamBriefAsync(input: Parameters<typeof setTeamBrief>[0]): Pr
 export function dissolveTeamAsync(teamId: string, input?: Parameters<typeof dissolveTeam>[1], requestId: string = randomUUID()): Promise<ReturnType<typeof dissolveTeam>> {
   return getGateway().write("teams.dissolve", { teamId, input }, { idempotencyKey: requestId }) as unknown as Promise<ReturnType<typeof dissolveTeam>>;
 }
+
+export function ensureTeamAsync(agentId: string, opts: { projectId?: string } = {}): Promise<NonNullable<ReturnType<typeof getTeam>>> {
+  return write("teams.ensure", { agentId, id: `team_${randomUUID()}`, ...opts });
+}

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

@@ -1,3 +1,5 @@
+import { claimAuthorizedTeam } from "./team-claim-policy";
+import { ensureTeamInternal } from "./teams";
 // Team writer operations. Guards that were formerly adjacent sync statements now execute inside
 // the writer transaction; async callers submit a main-thread generated id and never rely on worker
 // process-local state.
@@ -10,6 +12,8 @@ import {
 import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
 
 export const TEAMS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
+  "teams.ensure": { offLoop: true, idempotent: true, fn: (a: { agentId: string; id: string; projectId?: string }, ctx) => ensureTeamInternal(a.agentId, a.id, ctx.now, false, a.projectId ?? null) },
+  "teams.claimAuthorized": { offLoop: true, idempotent: true, fn: (a: { teamId: string; agentId: string; admin: boolean }) => claimAuthorizedTeam(a.teamId, a.agentId, a.admin) },
   "teams.zeroMembers.set": { offLoop: true, idempotent: true, fn: (a: { teamId: string; ts: number }) => setTeamZeroMembersSince(a.teamId, a.ts) },
   "teams.zeroMembers.clear": { offLoop: true, idempotent: true, fn: (a: { teamId: string }, ctx) => clearTeamZeroMembersSince(a.teamId, ctx.now) },
   "teams.brief.set": { offLoop: true, idempotent: true, fn: (a: Parameters<typeof setTeamBrief>[0], ctx) => setTeamBrief(a, ctx.now) },

package/src/db/terminal-events.ts

@@ -111,3 +111,18 @@ export function clearAgentNotice(child: Pick<AgentCard, "id" | "epoch" | "meta">
   getDb().query("DELETE FROM agent_exit_notices WHERE agent_id = ? AND epoch = ? AND spawn_request_id = ? AND kind = ?")
     .run(child.id, child.epoch, stringValue(child.meta?.spawnRequestId) ?? "", kind);
 }
+
+export interface AgentNoticeSlot {
+  child: Pick<AgentCard, "id" | "epoch" | "meta">;
+  kind: string;
+}
+
+/** Called inside notifications.agentNotice, so failure rolls back the slot and all sends. */
+export function insertAgentNoticeSlot({ child, kind }: AgentNoticeSlot, now: number): boolean {
+  if (kind === "agent.ready") {
+    getDb().query("DELETE FROM agent_exit_notices WHERE agent_id = ? AND kind = 'agent.ready' AND NOT (epoch = ? AND spawn_request_id = ?)")
+      .run(child.id, child.epoch, stringValue(child.meta?.spawnRequestId) ?? "");
+  }
+  return getDb().query("INSERT OR IGNORE INTO agent_exit_notices (agent_id, epoch, spawn_request_id, kind, created_at) VALUES (?, ?, ?, ?, ?)")
+    .run(child.id, child.epoch, stringValue(child.meta?.spawnRequestId) ?? "", kind, now).changes > 0;
+}

package/src/db/timer-cutover-bodies.ts

@@ -0,0 +1,292 @@
+import { getDb, currentWriteTransactionContext } from "./connection";
+import { clearExpiredLegacyMessageClaimsInTx, timerMessageDeadlineSnapshot } from "./timer-message-cutover";
+import { normalizePhase, readCutover, appendJournal } from "./timer-cutover-state";
+import type { KernelTimersDesiredMode, TimerMessageBackend, TimerMessageCutoverRow } from "./timer-message-flip";
+import type { TimerMessageCutoverPhase, TimerMessageCutoverJournalEntry, TimerMessageDeadlineGuard } from "./timer-cutover-core";
+import type { WriterOpSpec } from "./write-ops";
+
+export interface CutoverWriterState {
+  ownerId: string; epoch?: number; leaseMs: number; quiesceTimeoutMs: number; worstCaseMs: number;
+  authoritativeActivation: boolean; operationLeaseFence?: { requestId: string; ownerId: string };
+}
+export interface CutoverStepArgs {
+  abort: { now: number; reason: string };
+  activate: { now: number; epoch: number };
+  completeLegacy: { now: number; epoch: number };
+  completeTransfer: { now: number; epoch: number; mode: KernelTimersDesiredMode; expectedBackend: TimerMessageBackend };
+  reverse: { now: number; epoch: number; targetMode: KernelTimersDesiredMode; sourceObservedMode: KernelTimersDesiredMode };
+  clearClaims: { now: number };
+  acquire: { now: number; create: boolean };
+  renew: { now: number; epoch: number };
+  closeGate: { epoch: number; now: number };
+  transition: { epoch: number; phase: TimerMessageCutoverPhase; reason: string; now: number };
+  finishAbort: { epoch: number; reason: string; now: number };
+}
+export interface CutoverStepResults {
+  abort: boolean;
+  activate: void;
+  completeLegacy: void;
+  completeTransfer: void;
+  reverse: void;
+  clearClaims: number;
+  acquire: { acquiredEpoch?: number };
+  renew: boolean;
+  closeGate: boolean;
+  transition: void;
+  finishAbort: void;
+}
+function owned(state: CutoverWriterState, epoch: number, now: number): TimerMessageCutoverRow {
+    const row = readCutover();
+    if (!row || row.epoch !== epoch || row.leaseOwner !== state.ownerId || (row.leaseExpiresAt ?? 0) <= now) {
+      throw new Error(`cutover epoch ${epoch} is not owned by ${state.ownerId}`);
+    }
+    return row;
+  }
+function deadlineGuard(state: CutoverWriterState, at: number): TimerMessageDeadlineGuard {
+  const deadlines = timerMessageDeadlineSnapshot();
+  const slackMs = deadlines.earliestDeadline === null ? null : deadlines.earliestDeadline - at;
+  return { safe: slackMs === null || slackMs >= state.worstCaseMs, slackMs, requiredMs: state.worstCaseMs, deadlines };
+}
+const steps = {
+  abort: (state: CutoverWriterState, { now, reason }: CutoverStepArgs["abort"]) => {
+      const row = readCutover();
+      if (!row || normalizePhase(row.phase) === "idle") return false;
+      return getDb().query(`UPDATE timer_message_cutover
+        SET abort_requested = 1, phase_journal = ?, updated_at = ? WHERE id = 1`)
+        .run(appendJournal(row, { epoch: row.epoch, phase: "aborting", at: now, reason }), now).changes === 1;
+
+  },
+  activate: (state: CutoverWriterState, { now, epoch }: CutoverStepArgs["activate"]) => {
+      const row = owned(state, epoch, now);
+      if (normalizePhase(row.phase) !== "quiesced" || row.messageMutationGate !== "closed") {
+        throw new Error("ingress routing activation requires the live quiesced gate owner");
+      }
+      const changed = getDb().query(`UPDATE timer_message_cutover SET ingress_policy = 'ingress',
+        phase_journal = ?, updated_at = ?
+        WHERE id = 1 AND epoch = ? AND lease_owner = ? AND lease_expires_at > ?
+          AND phase = 'quiesced' AND message_mutation_gate = 'closed'`)
+        .run(appendJournal(row, { epoch, phase: "quiesced", at: now, reason: "authoritative ingress routing activated under fence" }),
+          now, epoch, state.ownerId, now);
+      if (changed.changes !== 1) throw new Error("cutover lease lost before ingress routing activation");
+
+  },
+  completeLegacy: (state: CutoverWriterState, { now, epoch }: CutoverStepArgs["completeLegacy"]) => {
+      const row = owned(state, epoch, now);
+      if (normalizePhase(row.phase) !== "quiesced" || row.messageMutationGate !== "closed" || row.ingressPolicy !== "ingress") {
+        throw new Error("G1 completion requires fenced authoritative ingress routing");
+      }
+      const changed = getDb().query(`UPDATE timer_message_cutover SET
+        protocol_version = MAX(COALESCE(protocol_version, 1), 2),
+        phase = 'idle', lease_owner = NULL, lease_expires_at = NULL,
+        quiesce_started_at = NULL, quiesce_deadline = NULL,
+        message_mutation_gate = 'open', gate_epoch = NULL, abort_requested = 0,
+        phase_journal = ?, updated_at = ?
+        WHERE id = 1 AND epoch = ? AND lease_owner = ? AND lease_expires_at > ?
+          AND phase = 'quiesced' AND message_mutation_gate = 'closed' AND ingress_policy = 'ingress'`)
+        .run(appendJournal(row, { epoch, phase: "idle", at: now, reason: "G1 proven; gate reopened under legacy authority" }),
+          now, epoch, state.ownerId, now);
+      if (changed.changes !== 1) throw new Error("cutover lease lost before G1 gate reopen");
+
+  },
+  completeTransfer: (state: CutoverWriterState, { now, epoch, mode, expectedBackend }: CutoverStepArgs["completeTransfer"]) => {
+      const row = owned(state, epoch, now);
+      if (normalizePhase(row.phase) !== "quiesced" || row.messageMutationGate !== "closed"
+        || row.ingressPolicy !== "ingress") {
+        throw new Error("authority-transfer completion requires the live quiesced ingress gate owner");
+      }
+      // Only ACTIVE (scheduled) rows must converge on the target backend — terminal rows never
+      // dispatch, so their backend is irrelevant and must not block completion (an ordinary kernel-mode
+      // cancel terminalizes a kernel-owned row that a reverse would otherwise be unable to move).
+      const wrongOwners = (getDb().query(`SELECT count(*) AS n FROM timer_message_authority
+        WHERE lifecycle='scheduled' AND backend != ?`).get(expectedBackend) as { n: number }).n;
+      if (wrongOwners !== 0) throw new Error(`${wrongOwners} scheduled MESSAGE owners are not ${expectedBackend}`);
+      const expectedFrozen = expectedBackend === "kernel" ? 1 : 0;
+      const projectionMismatch = (getDb().query(`SELECT count(*) AS n FROM timer_message_authority a
+          JOIN scheduled_timers s ON s.id=a.timer_id
+          WHERE a.lifecycle='scheduled' AND (s.command IS NOT NULL OR s.message_authority_frozen != ?)`)
+          .get(expectedFrozen) as { n: number }).n;
+      if (projectionMismatch !== 0) throw new Error(`${projectionMismatch} MESSAGE compatibility projections disagree with ${mode}`);
+      const changed = getDb().query(`UPDATE timer_message_cutover SET
+        desired_mode = ?, observed_mode = ?, phase = 'idle', lease_owner = NULL,
+        lease_expires_at = NULL, quiesce_started_at = NULL, quiesce_deadline = NULL,
+        message_mutation_gate = 'open', gate_epoch = NULL, abort_requested = 0,
+        phase_journal = ?, updated_at = ?
+        WHERE id=1 AND epoch=? AND lease_owner=? AND lease_expires_at>?
+          AND phase='quiesced' AND message_mutation_gate='closed' AND ingress_policy='ingress'`)
+        .run(mode, mode, appendJournal(row, {
+          epoch, phase: "idle", at: now,
+          reason: `${mode} per-row ownership proven; MESSAGE mutation gate reopened`,
+        }), now, epoch, state.ownerId, now);
+      if (changed.changes !== 1) throw new Error("cutover lease lost before authority-transfer completion");
+
+  },
+  reverse: (state: CutoverWriterState, { now, epoch, targetMode, sourceObservedMode }: CutoverStepArgs["reverse"]) => {
+      const row = owned(state, epoch, now);
+      const changed = getDb().query(`UPDATE timer_message_cutover SET desired_mode=?,
+        phase_journal=?, updated_at=?
+        WHERE id=1 AND epoch=? AND lease_owner=? AND lease_expires_at>?
+          AND phase='quiesced' AND message_mutation_gate='closed' AND observed_mode=?`)
+        .run(targetMode, appendJournal(row, {
+          epoch, phase: "quiesced", at: now,
+          reason: `${targetMode} rollback desired; kernel decision commits quiesced for reverse projection`,
+        }), now, epoch, state.ownerId, now, sourceObservedMode);
+      if (changed.changes !== 1) throw new Error(`reverse transfer requires observed ${sourceObservedMode} under the live fence`);
+
+  },
+  clearClaims: (state: CutoverWriterState, { now }: CutoverStepArgs["clearClaims"]) => {return clearExpiredLegacyMessageClaimsInTx(currentWriteTransactionContext()!, now);
+  },
+  acquire: (state: CutoverWriterState, { now, create }: CutoverStepArgs["acquire"]) => {let acquiredEpoch: number | undefined; let takeover = false;
+    (() => {
+      // Stage-10 pins the resolved leg before it asks this independent coordinator to close the
+      // global gate. Check that pin's operation lease under THIS acquisition transaction: if an
+      // abort won after pin but before requestQuiesce, it cannot be followed by a stale gate close.
+      const fence = state.operationLeaseFence;
+      if (fence) {
+        const live = getDb().query(`SELECT 1 FROM timer_message_cutover_operation
+          WHERE id=1 AND request_id=? AND state='running' AND abort_requested=0
+            AND lease_owner=? AND lease_expires_at > ?`)
+          .get(fence.requestId, fence.ownerId, now);
+        if (!live) return;
+      }
+      const row = readCutover();
+      if (!row) {
+        if (!create) return;
+        acquiredEpoch = 1;
+        const journal: TimerMessageCutoverJournalEntry[] = [{ epoch: 1, phase: "leased", at: now, reason: "initial lease acquired" }];
+        getDb().query(`INSERT INTO timer_message_cutover
+          (id, protocol_version, epoch, desired_mode, observed_mode, phase, lease_owner, lease_expires_at,
+           quiesce_started_at, quiesce_deadline, last_completed_timer, ingress_policy,
+           message_mutation_gate, gate_epoch, abort_requested, phase_journal, updated_at)
+          VALUES (1, 1, 1, 'shadow', 'shadow', 'leased', ?, ?, NULL, NULL, NULL, 'legacy', 'open', NULL, 0, ?, ?)`)
+          .run(state.ownerId, now + state.leaseMs, JSON.stringify(journal), now);
+        return;
+      }
+      const rowPhase = normalizePhase(row.phase);
+      const liveForeign = row.leaseOwner !== null && row.leaseOwner !== state.ownerId && (row.leaseExpiresAt ?? 0) > now;
+      if (liveForeign) return;
+      if (row.leaseOwner === state.ownerId && (row.leaseExpiresAt ?? 0) > now && state.epoch === row.epoch) {
+        acquiredEpoch = row.epoch;
+        return;
+      }
+      const nextEpoch = row.epoch + 1;
+      takeover = row.leaseOwner !== null || rowPhase !== "idle" || row.messageMutationGate === "closed";
+      const nextPhase: TimerMessageCutoverPhase = rowPhase === "idle" ? "leased" : rowPhase;
+      const entry: TimerMessageCutoverJournalEntry = {
+        epoch: nextEpoch,
+        phase: takeover ? "takeover" : "leased",
+        at: now,
+        reason: takeover ? `expired epoch ${row.epoch} taken over in phase ${rowPhase}` : "lease acquired",
+      };
+      const result = getDb().query(`UPDATE timer_message_cutover SET
+        protocol_version = COALESCE(protocol_version, 1), epoch = ?, phase = ?, lease_owner = ?, lease_expires_at = ?,
+        gate_epoch = CASE WHEN message_mutation_gate = 'closed' THEN ? ELSE NULL END,
+        phase_journal = ?, updated_at = ?
+        WHERE id = 1 AND (lease_owner IS NULL OR lease_expires_at <= ? OR lease_owner = ?)`)
+        .run(nextEpoch, nextPhase, state.ownerId, now + state.leaseMs, nextEpoch,
+          appendJournal(row, entry), now, now, state.ownerId);
+      if (result.changes === 1) acquiredEpoch = nextEpoch;
+    })();
+    return { acquiredEpoch };
+  },
+  renew: (state: CutoverWriterState, { now, epoch }: CutoverStepArgs["renew"]) => {
+      const row = readCutover();
+      if (!row || row.epoch !== epoch || row.leaseOwner !== state.ownerId || (row.leaseExpiresAt ?? 0) <= now) return false;
+      const deadlineCap = row.messageMutationGate === "closed" && row.quiesceDeadline !== null
+        ? row.quiesceDeadline
+        : Number.MAX_SAFE_INTEGER;
+      const nextExpiry = Math.min(now + state.leaseMs, deadlineCap);
+      return getDb().query(`UPDATE timer_message_cutover SET lease_expires_at = ?, phase_journal = ?, updated_at = ?
+        WHERE id = 1 AND epoch = ? AND lease_owner = ? AND lease_expires_at > ?`)
+        .run(nextExpiry, appendJournal(row, { epoch, phase: "renewed", at: now }), now,
+          epoch, state.ownerId, now).changes === 1;
+
+  },
+  closeGate: (state: CutoverWriterState, { epoch, now }: CutoverStepArgs["closeGate"]) => {
+      const row = owned(state, epoch, now);
+      // `requestQuiesce` acquires the coordinator lease before the following tick closes the gate.
+      // Recheck the Stage-10 operation lease in this close transaction: an abort (or expiry) that
+      // won in that interval must leave this independent coordinator open and unleased, never
+      // permit stale authority to close the MESSAGE gate after the abort's release observed it open.
+      const fence = state.operationLeaseFence;
+      if (fence) {
+        const live = getDb().query(`SELECT 1 FROM timer_message_cutover_operation
+          WHERE id=1 AND request_id=? AND state='running' AND abort_requested=0
+            AND lease_owner=? AND lease_expires_at > ?`)
+          .get(fence.requestId, fence.ownerId, now);
+        if (!live) {
+          const released = getDb().query(`UPDATE timer_message_cutover SET
+            phase = 'idle', lease_owner = NULL, lease_expires_at = NULL,
+            quiesce_started_at = NULL, quiesce_deadline = NULL,
+            message_mutation_gate = 'open', gate_epoch = NULL, abort_requested = 0,
+            desired_mode = observed_mode, phase_journal = ?, updated_at = ?
+            WHERE id=1 AND epoch=? AND lease_owner=? AND lease_expires_at>? AND phase='leased'`)
+            .run(appendJournal(row, {
+              epoch, phase: "idle", at: now,
+              reason: "Stage-10 operation lease no longer authorizes MESSAGE gate close",
+            }), now, epoch, state.ownerId, now);
+          if (released.changes !== 1) throw new Error("cutover lease lost while releasing stale Stage-10 gate request");
+          state.epoch = undefined;
+          return false;
+        }
+      }
+      // Re-read all three deadline sources under the SAME writer lock that closes the gate. A
+      // deadline mutation that won the race is therefore observed here and refuses entry; one that
+      // loses cannot commit until after the closed marker and is caught by the next continuous tick.
+      const guard = deadlineGuard(state, now);
+      if (!guard.safe) {
+        const changed = getDb().query(`UPDATE timer_message_cutover SET phase = 'aborting', abort_requested = 1,
+          phase_journal = ?, updated_at = ? WHERE id = 1 AND epoch = ? AND lease_owner = ? AND phase = 'leased'`)
+          .run(appendJournal(row, {
+            epoch, phase: "aborting", at: now,
+            reason: `deadline guard refused atomic gate close (slack=${guard.slackMs}, required=${guard.requiredMs})`,
+          }), now, epoch, state.ownerId);
+        if (changed.changes !== 1) throw new Error("cutover lease lost while refusing gate close");
+        return false;
+      }
+      const deadline = Math.min(
+        now + state.quiesceTimeoutMs,
+        guard.deadlines.earliestDeadline === null ? Number.MAX_SAFE_INTEGER : guard.deadlines.earliestDeadline - 1,
+      );
+      const changed = getDb().query(`UPDATE timer_message_cutover SET phase = 'quiescing',
+        message_mutation_gate = 'closed', gate_epoch = ?, quiesce_started_at = ?, quiesce_deadline = ?,
+        ingress_policy = CASE WHEN ? THEN 'activating' ELSE ingress_policy END,
+        phase_journal = ?, updated_at = ?
+        WHERE id = 1 AND epoch = ? AND lease_owner = ? AND phase = 'leased'`)
+        .run(epoch, now, deadline, state.authoritativeActivation ? 1 : 0,
+          appendJournal(row, { epoch, phase: "quiescing", at: now, reason: "MESSAGE mutation gate closed" }),
+          now, epoch, state.ownerId);
+      if (changed.changes !== 1) throw new Error("cutover lease lost before gate close");
+      return true;
+
+  },
+  transition: (state: CutoverWriterState, { epoch, phase, reason, now }: CutoverStepArgs["transition"]) => {
+      const row = owned(state, epoch, now);
+      const changed = getDb().query(`UPDATE timer_message_cutover SET phase = ?, phase_journal = ?, updated_at = ?
+        WHERE id = 1 AND epoch = ? AND lease_owner = ? AND lease_expires_at > ?`)
+        .run(phase, appendJournal(row, { epoch, phase, at: now, reason }), now, epoch, state.ownerId, now);
+      if (changed.changes !== 1) throw new Error(`cutover lease lost before phase ${phase}`);
+
+  },
+  finishAbort: (state: CutoverWriterState, { epoch, reason, now }: CutoverStepArgs["finishAbort"]) => {
+      const row = owned(state, epoch, now);
+      const changed = getDb().query(`UPDATE timer_message_cutover SET
+        phase = 'idle', lease_owner = NULL, lease_expires_at = NULL,
+        quiesce_started_at = NULL, quiesce_deadline = NULL,
+        message_mutation_gate = 'open', gate_epoch = NULL, abort_requested = 0,
+        phase_journal = ?, updated_at = ?
+        WHERE id = 1 AND epoch = ? AND lease_owner = ? AND lease_expires_at > ?`)
+        .run(appendJournal(row, { epoch, phase: "idle", at: now, reason: `gate reopened: ${reason}` }),
+          now, epoch, state.ownerId, now);
+      if (changed.changes !== 1) throw new Error("cutover lease lost before abort release");
+
+  },
+};
+export const TIMER_CUTOVER_COORDINATOR_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
+  "timerCutover.coordinatorStep": { offLoop: true, idempotent: false,
+    fn: (input: { step: keyof CutoverStepArgs; state: CutoverWriterState; args: CutoverStepArgs[keyof CutoverStepArgs] }) => {
+      const epoch = input.state.epoch;
+      const body = steps[input.step] as (state: CutoverWriterState, args: typeof input.args) => unknown;
+      const value = body(input.state, input.args);
+      return { value: value ?? null, ...(input.state.epoch !== epoch ? { clearEpoch: true } : {}) };
+    } },
+});