@humwick/server 0.130.0 → 0.130.2

package/src/db/spawn-delegation-state.ts

@@ -77,13 +77,20 @@ export function spawnDelegationState(agentId: string, launchProfile?: string) {
     participating: Boolean((ancestors?.length !== 1 || launchProfile === "sub-coordinator")
       && (grant || ownTeam?.parentTeamId || (rootTeam && hasPrivateTeams(rootTeam.id)))), enabled: grant?.enabled === true,
     grant, projectId: ancestors && ancestors.length > 1 ? delegatedProjectId(agentId) ?? projectIdForAgent(agent) : rootTeam?.projectId,
-    displaced: (ancestors ?? [agentId]).some(id => {
-      const ancestor = getAgent(id);
-      return isDisplacedSeat(id, ancestor?.teamId ?? seatTeam(id)?.id);
-    }),
+    displaced: displacedThroughDelegation(ancestors ?? [agentId]),
   };
 }
 
+/** The agent's own seat was claimed, or that of an ancestor it reaches only through delegated launches. An
+ * ordinary child is inherited by the claimant and keeps its standing (#3773). */
+function displacedThroughDelegation(ancestors: readonly string[]): boolean {
+  for (const id of ancestors) {
+    if (isDisplacedSeat(id, getAgent(id)?.teamId ?? seatTeam(id)?.id)) return true;
+    if (!delegatedLaunch(id)) return false;
+  }
+  return false;
+}
+
 /** Ordinary tokens avoid ancestry reads; private-team linkage survives grant removal. */
 export function participatesInSpawnDelegation(agentId: string): boolean {
   return Boolean(getDb().query(`WITH RECURSIVE lineage(id, depth) AS (

package/src/db/spawn-tree-cleanup.ts

@@ -35,12 +35,14 @@ export const SPAWN_TREE_CLEANUP_READ_OPS = {
 
 export const SPAWN_TREE_CLEANUP_WRITE_OPS = {
   "spawnTree.markTransferred": {
+    offLoop: true,
     idempotent: true,
     fn: ({ id }: { id: string }): void => {
       getDb().query("UPDATE spawn_tree_stops SET cleanup_effect_id = id WHERE id = ?").run(id);
     },
   },
   "spawnTree.stopGoneCallers": {
+    offLoop: true,
     idempotent: true,
     fn: (_args: undefined, ctx: { now: number }): void => {
       const rows = getDb().query(`WITH launches AS MATERIALIZED (
@@ -70,6 +72,7 @@ export const SPAWN_TREE_CLEANUP_WRITE_OPS = {
     },
   },
   "spawnTree.prepareCleanup": {
+    offLoop: true,
     idempotent: true,
     fn: ({ agentId }: { agentId: string }, ctx: { now: number }): void => {
       const ids = spawnTreeParentIds(agentId).filter(id => delegatedLaunch(id));

package/src/db/stats-async.ts

@@ -1,4 +1,4 @@
-import { mainConnectionWrites } from "./main-connection-writes";
+import { mainConnectionBootWrites, mainConnectionWrites } from "./main-connection-writes";
 import { allWriterOps } from "./write-ops";
 import { assertMainThreadState } from "./main-thread-state";
 // Async reader-pool facades for DB-only stats. Health is a deliberate documented deferral: its
@@ -105,7 +105,7 @@ async function probeDatabaseLiveness(): Promise<HealthCheck> {
  * `readerBackend`/`writerBackend` plus reader-pool depth/in-flight/shed counts unconditionally (the
  * in-process backend's zeroed pool numbers ARE the "report that plainly" answer, not a special case).
  */
-function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
+export function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
   const reader = stats.reader;
   const readerActive = reader.backend !== "uninitialized";
   const wedged = stats.writer.wedged;
@@ -119,7 +119,7 @@ function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
     `reader=${stats.readerBackend}`,
     `onLoopOps=${specs.length - offLoop}; writerThreadOps=${offLoop}`,
     `mainConnectionWrites1h=${JSON.stringify(writes)}`,
-    ...(wedged ? ["writer wedged"] : []),
+    ...(wedged ? [`writer wedged: op ${wedged.op} running ${Math.round(wedged.runningMs / 1000)}s`] : []),
     ...(shedCount > 0 ? [`${shedCount} reader shed(s)`] : []),
   ].join("; ");
   return {
@@ -131,6 +131,7 @@ function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
       onLoopOps: specs.length - offLoop,
       writerThreadOps: offLoop,
       mainConnectionWrites1h: Object.values(writes).reduce((sum, count) => sum + count, 0),
+      mainConnectionBootWrites: mainConnectionBootWrites(),
       writerQueued: stats.writer.queued,
       writerBusy: stats.writer.busy,
       writerHighWater: stats.writer.highWater,

package/src/db/task-entity.ts

@@ -37,6 +37,7 @@ import {
   type TaskStatus,
 } from "../types";
 import { parseJson } from "../utils";
+import { repoRelativePath } from "@humwick/sdk/spawn-policy";
 import { cleanEnum, cleanStringArray, optionalEnum } from "../validation";
 import { getDb, writeTransaction, ValidationError } from "./connection.ts";
 import { ownerForNewTask } from "./task-owner.ts";
@@ -108,6 +109,16 @@ function cleanTags(value: unknown, field = "tags"): string[] | undefined {
   return cleanStringArray(value, field, { itemMax: 60, maxItems: 30 });
 }
 
+/** #3736 — repo-relative, normalized; a path that leaves the repo is refused. Stored null when empty. */
+function taskPathsColumn(value: unknown): string | null {
+  const paths = (cleanStringArray(value, "paths", { itemMax: 300, maxItems: 50 }) ?? []).map((path, i) => {
+    const rel = repoRelativePath(path);
+    if (rel === undefined) throw new ValidationError(`paths[${i}] must be a repo-relative path inside the repo`);
+    return rel;
+  });
+  return paths.length ? JSON.stringify([...new Set(paths)]) : null;
+}
+
 // #1535 WS3 — backlog lifecycle state. Optional (like priority): absent stays undefined so a
 // non-backlog task's column is NULL; a present-but-invalid value throws rather than silently
 // dropping. The backlog→promoted flip is a distinct writer (setTaskBacklogState in db/backlog.ts).
@@ -196,6 +207,7 @@ export interface CreateDeliverableTaskInput {
   complexity?: TaskComplexity;
   context?: string;
   terminalStage?: Task["terminalStage"];
+  onDeploy?: string;
   doneWhen?: string; branch?: string;
   teamId?: string;
   projectId?: string;
@@ -206,6 +218,7 @@ export interface CreateDeliverableTaskInput {
   latestSteer?: string;
   dispatch?: TaskDispatch;
   tags?: string[];
+  paths?: string[];
   priority?: TaskPriority;
   /** #1535 WS3 — seed the task directly into the backlog (`backlog`) so it shows up in the
    * prioritized backlog query until promoted. Absent ⇒ not backlog-managed. */
@@ -225,6 +238,7 @@ export function createDeliverableTaskBody(input: CreateDeliverableTaskInput, now
   const intent = requireText(input.intent, "intent", 1_000_000);
   const dispatch = cleanTaskDispatch(input.dispatch);
   const complexity = cleanTaskComplexity(input.complexity ?? dispatch?.complexity, "complexity") ?? DEFAULT_TASK_COMPLEXITY;
+  const onDeploy = optionalText(input.onDeploy, "onDeploy", 500);
   const context = optionalText(input.context, "context", 1_000_000);
   const branch = optionalText(input.branch, "branch", 500);
   const taskProject = cleanTaskProject(input);
@@ -237,8 +251,8 @@ export function createDeliverableTaskBody(input: CreateDeliverableTaskInput, now
     INSERT INTO tasks (
       source, title, body, severity, status, target, occurrence_count, metadata,
       created_at, updated_at, last_seen_at,
-      kind, intent, complexity, context, latest_steer, deliverable_stage, done_when, branch, team_id, project_id, repo, created_by, dispatch, tags, priority, backlog_state, owner
-    ) VALUES (?, ?, ?, 'info', 'open', ?, 1, '{}', ?, ?, ?, '${DELIVERABLE_TASK_KIND}', ?, ?, ?, ?, 'none', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      kind, intent, complexity, context, latest_steer, deliverable_stage, done_when, branch, team_id, project_id, repo, created_by, dispatch, tags, paths, priority, backlog_state, owner, on_deploy
+    ) VALUES (?, ?, ?, 'info', 'open', ?, 1, '{}', ?, ?, ?, '${DELIVERABLE_TASK_KIND}', ?, ?, ?, ?, 'none', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     optionalText(input.source, "source", 200) ?? "coordinator",
     title,
@@ -254,9 +268,11 @@ export function createDeliverableTaskBody(input: CreateDeliverableTaskInput, now
     createdBy,
     dispatch ? JSON.stringify(dispatch) : null,
     tags.length ? JSON.stringify(tags) : null,
+    taskPathsColumn(input.paths),
     priority ?? null,
     backlogState ?? null,
     ownerForNewTask(createdBy, teamId),
+    onDeploy ?? null,
   );
   const id = Number(result.lastInsertRowid);
   if (input.terminalStage) getDb().query("UPDATE tasks SET terminal_stage = ? WHERE id = ?").run(input.terminalStage, id);
@@ -282,6 +298,7 @@ export interface UpdateDeliverableTaskInput {
   complexity?: TaskComplexity;
   context?: string;
   latestSteer?: string;
+  onDeploy?: string;
   doneWhen?: string;
   dispatch?: TaskDispatch;
   teamId?: string;
@@ -290,6 +307,8 @@ export interface UpdateDeliverableTaskInput {
   actor?: string;
   /** Absent ⇒ untouched. `[]` (or `null`) ⇒ clear all tags. */
   tags?: string[] | null;
+  /** Absent ⇒ untouched. `[]` (or `null`) ⇒ clear all paths. */
+  paths?: string[] | null;
   /** Absent ⇒ untouched. `null` ⇒ clear (priority has no default, unlike complexity). */
   priority?: TaskPriority | null;
 }
@@ -309,6 +328,7 @@ export function updateDeliverableTaskBody(id: number, input: UpdateDeliverableTa
   if (input.complexity !== undefined) push("complexity", cleanTaskComplexity(input.complexity) ?? null);
   if (input.context !== undefined) push("context", optionalText(input.context, "context", 1_000_000) ?? null);
   if (input.latestSteer !== undefined) push("latest_steer", optionalText(input.latestSteer, "latestSteer", 1_000_000) ?? null);
+  if (input.onDeploy !== undefined) push("on_deploy", optionalText(input.onDeploy, "onDeploy", 500) ?? null);
   if (input.doneWhen !== undefined) push("done_when", optionalText(input.doneWhen, "doneWhen", 1_000_000) ?? null);
   if (input.teamId !== undefined) push("team_id", optionalText(input.teamId, "teamId", 200) ?? null);
   if (input.projectId !== undefined || input.repo !== undefined) {
@@ -321,6 +341,7 @@ export function updateDeliverableTaskBody(id: number, input: UpdateDeliverableTa
     const tags = input.tags === null ? [] : (cleanTags(input.tags) ?? []);
     push("tags", tags.length ? JSON.stringify(tags) : null);
   }
+  if (input.paths !== undefined) push("paths", taskPathsColumn(input.paths ?? []));
   if (input.terminalStage !== undefined) push("terminal_stage", input.terminalStage === null ? null : cleanTaskTerminalStage(input.terminalStage));
   if (input.priority !== undefined) push("priority", input.priority === null ? null : requireTaskPriority(input.priority));
   if (sets.length > 0) {

package/src/db/task-list.ts

@@ -41,7 +41,8 @@ function buildDeliverableTasksWhere(filter: ListDeliverableTasksFilter): { claus
   }
   if (filter.staleOwnerGone) conditions.push(STALE_TASK_OWNER_SQL);
   if (filter.status) { conditions.push("status = ?"); params.push(filter.status); }
-  if (filter.deliverableStage) { conditions.push("deliverable_stage = ?"); params.push(filter.deliverableStage); }
+  if (filter.deliverableStage === "awaiting-deploy") conditions.push("deliverable_stage IN ('landed-on-main', 'deploying')");
+  else if (filter.deliverableStage) { conditions.push("deliverable_stage = ?"); params.push(filter.deliverableStage); }
   if (filter.teamId) { conditions.push("team_id = ?"); params.push(filter.teamId); }
   if (filter.createdBy) { conditions.push("created_by = ?"); params.push(filter.createdBy); }
   if (filter.ownerAgentId) { conditions.push("owner_agent_id = ?"); params.push(filter.ownerAgentId); }
@@ -87,6 +88,7 @@ function taskListItem(task: Task): TaskListItem {
     status: task.status,
     kind: task.kind,
     ...(task.validationItems ? { validationItems: task.validationItems } : {}),
+    ...(task.onDeploy ? { onDeploy: task.onDeploy } : {}),
     ...(task.terminalStage ? { terminalStage: task.terminalStage } : {}),
     ...(task.completedAt ? { completedAt: task.completedAt } : {}),
     ...(task.staleOwnerGone ? { staleOwnerGone: true } : {}),

package/src/db/tasks.ts

@@ -1,19 +1,5 @@
 import { taskVisibilitySql, type ViewerScope } from "./viewer-scope";
-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 { CLAIM_LEASE_MS } from "../config";
 import { getAgent, validateAgentSession } from "./agents.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
 import { ClaimError, getDb, writeTransaction } from "./connection.ts";
@@ -51,7 +37,6 @@ export function taskMessageBody(task: Pick<Task, "id" | "source" | "severity" |
   return lines.join("\n");
 }
 
-
 export function getTask(id: number): Task | null {
   const row = getDb().query(`${TASK_SELECT} WHERE id = ?`).get(id) as any;
   return row ? rowToTask(row) : null;
@@ -85,7 +70,6 @@ export function listTasks(filter?: { viewer?: ViewerScope | null; status?: strin
   return (getDb().query(`${TASK_SELECT} ${where} ORDER BY updated_at DESC LIMIT ?`).all(...params) as any[]).map(rowToTask);
 }
 
-
 /** Deliverable stages meaning the work already left the worker's hands (#2036): a Task sitting in
  *  `in_progress` while its land gate runs is not a stalled worker. Excluded IN SQL, not after the
  *  fact — these rows carry the OLDEST claims, so a post-LIMIT filter would let them consume the

package/src/db/team-spawn-delegation.ts

@@ -45,5 +45,5 @@ export function setTeamSpawnDelegationBody(args: SetTeamDelegationArgs, now: num
 }
 
 export const TEAM_SPAWN_DELEGATION_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = {
-  "teams.spawnDelegation.set": { idempotent: true, fn: (args: SetTeamDelegationArgs, ctx) => setTeamSpawnDelegationBody(args, ctx.now) },
+  "teams.spawnDelegation.set": { offLoop: true, idempotent: true, fn: (args: SetTeamDelegationArgs, ctx) => setTeamSpawnDelegationBody(args, ctx.now) },
 };

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

@@ -10,8 +10,8 @@ import {
 import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
 
 export const TEAMS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
-  "teams.zeroMembers.set": { idempotent: true, fn: (a: { teamId: string; ts: number }) => setTeamZeroMembersSince(a.teamId, a.ts) },
-  "teams.zeroMembers.clear": { idempotent: true, fn: (a: { teamId: string }, ctx) => clearTeamZeroMembersSince(a.teamId, ctx.now) },
-  "teams.brief.set": { idempotent: true, fn: (a: Parameters<typeof setTeamBrief>[0], ctx) => setTeamBrief(a, ctx.now) },
-  "teams.dissolve": { idempotent: false, fn: (a: { teamId: string; input?: Parameters<typeof dissolveTeam>[1] }, ctx) => dissolveTeam(a.teamId, a.input, ctx.now) },
+  "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) },
+  "teams.dissolve": { offLoop: true, idempotent: false, fn: (a: { teamId: string; input?: Parameters<typeof dissolveTeam>[1] }, ctx) => dissolveTeam(a.teamId, a.input, ctx.now) },
 });

package/src/db/timer-cutover-write-ops.ts

@@ -242,6 +242,7 @@ function rebaseBootstrapEpoch(args: {
 
 export const TIMER_CUTOVER_WRITE_OPS = {
   "timers.cutover.releaseInterruptedTransfer": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { now?: number } | undefined, ctx: WriterOpContext) =>
       releaseInterruptedCutoverTransfer(args?.now ?? ctx.now),
@@ -249,26 +250,32 @@ export const TIMER_CUTOVER_WRITE_OPS = {
   // A kernel batch has already durably changed timer state by the time these run. Never shed the
   // resume cursor/journal acknowledgement or a restart will repeat a committed side effect.
   "timers.cutoverOperation.commitBackfillBatch": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Parameters<typeof commitBackfillBatch>[0]) => commitBackfillBatch(args),
   },
   "timers.cutoverOperation.commitBootstrapBatch": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Parameters<typeof commitBootstrapBatch>[0]) => commitBootstrapBatch(args),
   },
   "timers.cutoverOperation.commitTransferBatch": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Parameters<typeof commitTransferBatch>[0]) => commitTransferBatch(args),
   },
   "timers.cutoverOperation.appendJournal": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Parameters<typeof appendOperationJournal>[0]) => appendOperationJournal(args),
   },
   "timers.cutoverOperation.complete": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Parameters<typeof completeOperation>[0]) => completeOperation(args),
   },
   "timers.cutoverOperation.rebaseBootstrapEpoch": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Parameters<typeof rebaseBootstrapEpoch>[0]) => rebaseBootstrapEpoch(args),
   },

package/src/db/timer-ingress-write-ops.ts

@@ -78,12 +78,15 @@ export interface AcceptTimerIngressBootstrapOpArgs {
 
 export const TIMER_INGRESS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
   "timerIngress.acceptCreate": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AcceptTimerIngressCreateOpArgs) =>
       acceptTimerIngressCreateInTx({ source: args.source, storedKey: args.storedKey, at: args.at }),
   },
 
   "timerIngress.acceptCancel": {
+
+    offLoop: true,
     idempotent: true,
     fn: (args: AcceptTimerIngressCancelOpArgs) =>
       acceptTimerIngressCancelInTx({
@@ -95,6 +98,8 @@ export const TIMER_INGRESS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = O
   },
 
   "timerIngress.acceptBootstrapCreate": {
+
+    offLoop: true,
     idempotent: true,
     fn: (args: AcceptTimerIngressBootstrapOpArgs) =>
       acceptTimerIngressBootstrapCreateInTx({
@@ -107,6 +112,7 @@ export const TIMER_INGRESS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = O
 
   /** Collapse one unsettled intent to `terminal` (supersede / tombstone / malformed quarantine). */
   "timerIngress.settleTerminal": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { seq: number; reason: TimerIngressTerminalReason; error?: string; ownerId: string; at: number }) =>
       settleTimerIngressTerminal({
@@ -120,6 +126,7 @@ export const TIMER_INGRESS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = O
 
   /** CAS-claim an intent for apply (state + lease). Returns false when another applier holds it. */
   "timerIngress.claim": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { seq: number; ownerId: string; leaseMs: number; at: number }) =>
       claimTimerIngressIntent({ seq: args.seq, ownerId: args.ownerId, leaseMs: args.leaseMs, at: args.at }),
@@ -127,6 +134,7 @@ export const TIMER_INGRESS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = O
 
   /** Settle a successfully applied intent and advance the terminal-inclusive watermark. */
   "timerIngress.settleApplied": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { seq: number; ownerId: string; at: number }) => {
       settleTimerIngressApplied({ seq: args.seq, ownerId: args.ownerId, at: args.at });
@@ -136,6 +144,7 @@ export const TIMER_INGRESS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = O
 
   /** Drop our lease after a failed apply so the next pass retries immediately, keeping the error. */
   "timerIngress.releaseAfterFailure": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { seq: number; error: string; ownerId: string }) => {
       releaseTimerIngressLeaseAfterFailure({ seq: args.seq, error: args.error, ownerId: args.ownerId });

package/src/db/timer-ingress.ts

@@ -104,13 +104,18 @@ function rowToIntent(row: IntentDbRow): TimerIngressIntentRow {
   };
 }
 
+const installedOn = new WeakSet<object>();
+
 /** Idempotent, crash-safe schema install (one transaction; re-running over existing data is a
  *  no-op). Bootstrap DDL — it runs ONCE at startup as its own committed statement, never lazily
  *  inside an op, so a rolled-back op can never undo the schema it ran against (§4 allowlist). */
 export function installTimerIngressSchema(
-  options: { requestKeyMigrationFaults?: TimerIngressRequestKeyMigrationFaults } = {},
+  options: { requestKeyMigrationFaults?: TimerIngressRequestKeyMigrationFaults; ifNotInstalled?: boolean } = {},
 ): void {
   const db = getDb();
+  // #1870 S7: `startServer` installs it before bind (the boot exception); `createTimerIngress` passes
+  // `ifNotInstalled` so its later call runs no DDL on the main connection. Explicit calls always install.
+  if (options.ifNotInstalled && installedOn.has(db)) return;
   db.transaction(() => {
     // AUTOINCREMENT is deliberate: `seq` must be monotone and NEVER reused (the watermark's meaning
     // depends on it — and it doubles as the per-timer apply FENCE), even if settled rows are pruned.
@@ -165,6 +170,7 @@ export function installTimerIngressSchema(
     db.run("INSERT OR IGNORE INTO timer_ingress_watermark (id, applied_seq, updated_at) VALUES (1, 0, 0)");
     options.requestKeyMigrationFaults?.beforeCommit?.();
   }).immediate();
+  installedOn.add(db);
 }
 
 // ── Reads ───────────────────────────────────────────────────────────────────────────────────────

package/src/db/timer-operator-write-ops.ts

@@ -39,14 +39,17 @@ import {
 export const TIMER_OPERATOR_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
   // --- Dedup-by-construction: idempotent, no key required. ------------------------------------------
   "timerOperator.acceptCommand": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AcceptAuditedCommandArgs, ctx: WriterOpContext) => acceptAuditedCommandBody(args, ctx.now),
   },
   "timerOperator.ensureOperation": {
+    offLoop: true,
     idempotent: true,
     fn: (args: Omit<EnsureOperationArgs, "now">, ctx: WriterOpContext) => ensureOperationBody({ ...args, now: ctx.now }),
   },
   "timerOperator.resetTerminal": {
+    offLoop: true,
     // An occupied terminal slot deletes a row; replaying its body with `acceptAlreadyCleared: false`
     // throws. The facade therefore supplies a durable request-scoped key for retry replay.
     idempotent: false,
@@ -54,48 +57,59 @@ export const TIMER_OPERATOR_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> =
       resetTerminalOperationBody(args.requestId, args.acceptAlreadyCleared),
   },
   "timerOperator.finishAbort": {
+    offLoop: true,
     idempotent: true,
     fn: (_args: Record<string, never> | undefined, ctx: WriterOpContext) => finishAbortBody(ctx.now),
   },
   "timerOperator.pinTransferLeg": {
+    offLoop: true,
     idempotent: true,
     fn: (args: Omit<PinTransferLegArgs, "now">, ctx: WriterOpContext) => pinTransferLegBody({ ...args, now: ctx.now }),
   },
   "timerOperator.finishTransfer": {
+    offLoop: true,
     idempotent: true,
     fn: (args: Omit<FinishTransferArgs, "now">, ctx: WriterOpContext) => finishTransferBody({ ...args, now: ctx.now }),
   },
 
   // --- No in-body dedup guard: idempotent false, facade supplies a per-call key. --------------------
   "timerOperator.claimOperation": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Omit<ClaimOperationArgs, "now">, ctx: WriterOpContext) => claimOperationBody({ ...args, now: ctx.now }),
   },
   "timerOperator.commitBackfillBatch": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Omit<CommitBackfillBatchArgs, "at">, ctx: WriterOpContext) => commitBackfillBatchBody({ ...args, at: ctx.now }),
   },
   "timerOperator.epochRebase": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Omit<EpochRebaseArgs, "at">, ctx: WriterOpContext) => epochRebaseBody({ ...args, at: ctx.now }),
   },
   "timerOperator.commitBootstrapBatch": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Omit<CommitBootstrapBatchArgs, "at">, ctx: WriterOpContext) => commitBootstrapBatchBody({ ...args, at: ctx.now }),
   },
   "timerOperator.completeStage9": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Omit<CompleteStage9Args, "at">, ctx: WriterOpContext) => completeStage9Body({ ...args, at: ctx.now }),
   },
   "timerOperator.beginAbort": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Omit<BeginAbortArgs, "now">, ctx: WriterOpContext) => beginAbortBody({ ...args, now: ctx.now }),
   },
   "timerOperator.recordG1Transfer": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Omit<RecordG1TransferArgs, "now">, ctx: WriterOpContext) => recordG1TransferBody({ ...args, now: ctx.now }),
   },
   "timerOperator.commitTransferBatch": {
+    offLoop: true,
     idempotent: false,
     fn: (args: Omit<CommitTransferBatchArgs, "at">, ctx: WriterOpContext) => commitTransferBatchBody({ ...args, at: ctx.now }),
   },

package/src/db/timer-transfer-write-ops.ts

@@ -21,18 +21,22 @@ function withNow(args: TransferArgs, ctx: WriterOpContext): TimerMessageTransfer
  * the same durable journal row or is refused; it cannot move ownership twice. */
 export const TIMER_TRANSFER_WRITE_OPS = {
   "timers.transfer.prepareForward": {
+    offLoop: true,
     idempotent: true,
     fn: (args: TransferArgs, ctx: WriterOpContext) => prepareForwardTimerMessageTransfer(withNow(args, ctx)),
   },
   "timers.transfer.prepareReverse": {
+    offLoop: true,
     idempotent: true,
     fn: (args: TransferArgs, ctx: WriterOpContext) => prepareReverseTimerMessageTransfer(withNow(args, ctx)),
   },
   "timers.transfer.commitForward": {
+    offLoop: true,
     idempotent: true,
     fn: (args: TransferArgs, ctx: WriterOpContext) => commitForwardTimerMessageTransfer(withNow(args, ctx)),
   },
   "timers.transfer.commitReverse": {
+    offLoop: true,
     idempotent: true,
     fn: (args: TransferArgs, ctx: WriterOpContext) => commitReverseTimerMessageTransfer(withNow(args, ctx)),
   },

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

@@ -136,6 +136,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
    * `row.id` as that key: it is unique per logical create by construction and stable across a retry.
    */
   "timers.create": {
+    offLoop: true,
     idempotent: false,
     fn: (args: CreateTimerOpArgs, ctx: WriterOpContext) =>
       insertScheduledTimerWithinQuota(args.row, args.caps, ctx.now, QUOTA_FAULTS, args.route ?? "direct"),
@@ -143,6 +144,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
 
   /** CAS claim of a due timer. Re-applying either re-wins the same lease or returns null — idempotent. */
   "timers.claim": {
+    offLoop: true,
     idempotent: true,
     fn: (args: ClaimTimerOpArgs, ctx: WriterOpContext) =>
       claimScheduledTimer(args.id, args.owner, args.now ?? ctx.now, args.leaseMs),
@@ -155,6 +157,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
    * matching replay writes the identical row.
    */
   "timers.completeRun": {
+    offLoop: true,
     idempotent: true,
     fn: (args: CompleteTimerRunOpArgs, ctx: WriterOpContext) =>
       completeScheduledTimerRun({ timer: args.timer, messageId: args.messageId, now: args.now ?? ctx.now }),
@@ -162,6 +165,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
 
   /** Same claim-predicate shape as `completeRun`, so a replay is a no-op — idempotent. */
   "timers.recordFailure": {
+    offLoop: true,
     idempotent: true,
     fn: (args: RecordTimerFailureOpArgs, ctx: WriterOpContext) =>
       recordScheduledTimerFailure({
@@ -175,6 +179,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
 
   /** `WHERE enabled = 1` makes the second cancel a no-op that returns the same row — idempotent. */
   "timers.cancel": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { id: string; route?: TimerMessageMutationRoute }) =>
       cancelScheduledTimer(args.id, args.route ?? "direct"),
@@ -182,6 +187,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
 
   /** Unconditional UPDATE to a fixed end state — re-applying reaches the same state. */
   "timers.disable": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { id: string; reason: string }) => disableScheduledTimer(args.id, args.reason),
   },
@@ -189,6 +195,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
   /** UPDATE to a caller-supplied absolute `nextRunAt` — replaying writes the same instant, so it is
    *  the same end state. Idempotent. */
   "timers.deferRun": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { id: string; nextRunAt: number }) => deferScheduledTimerRun(args.id, args.nextRunAt),
   },
@@ -196,6 +203,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
   /** Read-modify-write of the command JSON, folded into the op. Writing the same commandId twice is
    *  the same end state — idempotent. */
   "timers.setCommandId": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { timerId: string; commandId: string }) => setScheduledTimerCommandId(args.timerId, args.commandId),
   },
@@ -203,6 +211,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
   /** Read-modify-write merge of a command patch, folded into the op. Re-merging the same patch onto
    *  the already-merged row is the same end state — idempotent. */
   "timers.updateCommand": {
+    offLoop: true,
     idempotent: true,
     fn: (args: UpdateTimerCommandOpArgs) => updateScheduledTimerCommand(args.timerId, args.patch),
   },
@@ -214,6 +223,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
    * decide the same run twice.
    */
   "timers.decideFire": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { input: Omit<DecideLegacyTimerMessageFireInput, "now">; now?: number }, ctx: WriterOpContext) =>
       decideLegacyTimerMessageFire({ ...args.input, now: args.now ?? ctx.now }, FIRE_DECISION_FAULTS),
@@ -221,6 +231,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
 
   /** Returns `already-sent` on replay rather than re-marking — idempotent. */
   "timers.markFireSent": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { timerId: string; run: number; messageId: number }, ctx: WriterOpContext) =>
       markTimerMessageFireSent(args.timerId, args.run, args.messageId, ctx.now),
@@ -232,6 +243,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
    * therefore requires a key; the facade passes one derived from the failing attempt.
    */
   "timers.recordFireSendFailure": {
+    offLoop: true,
     idempotent: false,
     fn: (args: RecordFireSendFailureOpArgs, ctx: WriterOpContext) =>
       recordTimerMessageFireSendFailure({
@@ -246,6 +258,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
 
   /** DELETE of a transient failure record — re-applying deletes nothing. Idempotent. */
   "timers.clearFireSendFailure": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { timerId: string; run: number }) => {
       clearTimerMessageFireSendFailure(args.timerId, args.run);
@@ -255,6 +268,7 @@ export const TIMER_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.fr
 
   /** Monotone fence advance (`applied_fence < fence` guard) — re-applying is a no-op. Idempotent. */
   "timers.markAuthorityApplied": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { timerId: string; fence: number }, ctx: WriterOpContext) => {
       markLegacyMessageAuthorityApplied(args.timerId, args.fence, ctx.now);