@humwick/server 0.130.0 → 0.130.2

package/src/db/integrations-ops.ts

@@ -0,0 +1,15 @@
+import { listIntegrationTaskStats, reconcileIntegrationRegistry, type IntegrationRegistryInput } from "./integrations.ts";
+import type { WriterOpSpec } from "./write-ops.ts";
+
+export const INTEGRATIONS_READ_OPS = {
+  "integrations.taskStats": () => listIntegrationTaskStats(),
+};
+
+export const INTEGRATIONS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = {
+  "integrations.reconcileRegistry": {
+    offLoop: true,
+    idempotent: true,
+    fn: (args: { configured: IntegrationRegistryInput[]; observedSources: string[] }, ctx) =>
+      reconcileIntegrationRegistry(args.configured, args.observedSources, ctx.now),
+  },
+};

package/src/db/integrations.ts

@@ -1,18 +1,5 @@
-import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "@humwick/sdk";
-import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
+import { stringValue } from "@humwick/sdk";
 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 { normalizeTags, parseStringArray } from "./agents.ts";
 import { linkAttachmentRefs, validateAttachmentRefs } from "./artifacts.ts";
 import { ValidationError, getDb, writeTransaction } from "./connection.ts";
@@ -143,9 +130,7 @@ function integrationTaskMetadata(
   };
 }
 
-
-export function listIntegrationTaskStats(): IntegrationTaskStats[] {
-  const rows = getDb().query(`
+export const INTEGRATION_TASK_STATS_SQL = `
     SELECT
       coalesce(json_extract(metadata, '$.relayIntegrationName'), source) AS source,
       COUNT(*) AS tasks,
@@ -157,7 +142,10 @@ export function listIntegrationTaskStats(): IntegrationTaskStats[] {
     FROM tasks
     GROUP BY coalesce(json_extract(metadata, '$.relayIntegrationName'), source)
     ORDER BY last_seen_at DESC, source ASC
-  `).all() as any[];
+  `;
+
+export function listIntegrationTaskStats(): IntegrationTaskStats[] {
+  const rows = getDb().query(INTEGRATION_TASK_STATS_SQL).all() as any[];
 
   return rows.map((row) => ({
     source: row.source,
@@ -170,7 +158,7 @@ export function listIntegrationTaskStats(): IntegrationTaskStats[] {
   }));
 }
 
-type IntegrationRegistryInput = {
+export type IntegrationRegistryInput = {
   name: string;
   displayName?: string;
   description?: string;
@@ -220,10 +208,9 @@ function rowToIntegrationRegistry(row: any): Omit<IntegrationSummary, "configure
   };
 }
 
-export function upsertIntegrationRegistry(input: IntegrationRegistryInput): ReturnType<typeof rowToIntegrationRegistry> {
+export function upsertIntegrationRegistry(input: IntegrationRegistryInput, now = Date.now()): ReturnType<typeof rowToIntegrationRegistry> {
   const name = stringValue(input.name);
   if (!name) throw new ValidationError("integration name required");
-  const now = Date.now();
   getDb().query(`
     INSERT INTO integration_registry (
       name, display_name, description, enabled, scopes, targets, channels, type, icon, accent_color,
@@ -295,3 +282,10 @@ export function isIntegrationRegistryEnabled(name: string): boolean {
   const registry = getIntegrationRegistry(name);
   return registry?.enabled !== false;
 }
+
+// GET reconciliation preserves registry precedence, but runs entirely on the writer (#3740).
+export function reconcileIntegrationRegistry(configured: IntegrationRegistryInput[], observedSources: string[], now: number): ReturnType<typeof listIntegrationRegistry> {
+  for (const input of configured) upsertIntegrationRegistry({ ...input, source: "env" }, now);
+  for (const name of observedSources) upsertIntegrationRegistry({ name, enabled: true, source: "observed" }, now);
+  return listIntegrationRegistry();
+}

package/src/db/issue-lifecycle.ts

@@ -5,7 +5,7 @@ const ISSUE_LIFECYCLE_STATUSES = ["succeeded", "failed"] as const;
 type IssueLifecycleAction = (typeof ISSUE_LIFECYCLE_ACTIONS)[number];
 type IssueLifecycleStatus = (typeof ISSUE_LIFECYCLE_STATUSES)[number];
 
-interface IssueLifecycleActionRecord {
+export interface IssueLifecycleActionRecord {
   id: number;
   issueRefId: string;
   action: IssueLifecycleAction;
@@ -24,7 +24,7 @@ interface IssueLifecycleActionRecord {
   updatedAt: number;
 }
 
-interface UpsertIssueLifecycleActionInput {
+export interface UpsertIssueLifecycleActionInput {
   issueRefId: string;
   action: IssueLifecycleAction;
   landKey: string;
@@ -150,8 +150,7 @@ export function listSuccessfulCloseActionsForCommit(input: { commitSha?: string;
   return rows.map(rowToIssueLifecycleAction);
 }
 
-export function upsertIssueLifecycleAction(input: UpsertIssueLifecycleActionInput): IssueLifecycleActionRecord {
-  const now = Date.now();
+export function upsertIssueLifecycleAction(input: UpsertIssueLifecycleActionInput, now: number = Date.now()): IssueLifecycleActionRecord {
   const issueRefId = cleanRequiredText(input.issueRefId, "issueRefId", 120);
   const action = cleanAction(input.action);
   const landKey = cleanRequiredText(input.landKey, "landKey", 240);

package/src/db/issue-refs-async.ts

@@ -0,0 +1,20 @@
+// #1870 S7 — async facades for the issue-ref writer ops (`issue-refs-write-ops.ts`).
+import { randomUUID } from "node:crypto";
+import { getGateway } from "./gateway.ts";
+import type { IssueRef } from "../types";
+import type { IssueTrackerIssueSummary } from "../issue-tracker/adapter";
+import type { ResolveIssueRefByExternalKeyInput, ResolveIssueRefFromStringInput, UpdateIssueRefInput, UpsertIssueRefInput } from "./issue-refs.ts";
+import type { IssueLifecycleActionRecord, UpsertIssueLifecycleActionInput } from "./issue-lifecycle.ts";
+
+const write = <T>(op: string, args: unknown, opts?: { idempotencyKey?: string }) => getGateway().write(op, args as never, opts) as unknown as Promise<T>;
+
+export const upsertIssueRefAsync = (input: UpsertIssueRefInput) => write<IssueRef>("issueRefs.upsert", input);
+export const resolveIssueRefByExternalKeyAsync = (input: ResolveIssueRefByExternalKeyInput) => write<IssueRef>("issueRefs.resolveExternalKey", input);
+export const resolveIssueRefFromStringAsync = (input: ResolveIssueRefFromStringInput) => write<IssueRef>("issueRefs.resolveFromString", input);
+export const updateIssueRefAsync = (id: string, input: UpdateIssueRefInput) => write<IssueRef | null>("issueRefs.update", { id, input });
+export const deleteIssueRefAsync = (id: string) => write<boolean>("issueRefs.delete", { id });
+/** The tracker answered: clear the not-found streak and cache its status, in one write. */
+export const recordIssueRefLiveStatusAsync = (id: string, input: UpdateIssueRefInput) => write<IssueRef | null>("issueRefs.recordLiveStatus", { id, input });
+export const putIssueHierarchyAsync = (id: string, children: IssueTrackerIssueSummary[]) => write<void>("issueRefs.putHierarchy", { id, children });
+export const recordIssueTrackerNotFoundAsync = (id: string) => write<number>("issueRefs.recordNotFound", { id }, { idempotencyKey: randomUUID() });
+export const upsertIssueLifecycleActionAsync = (input: UpsertIssueLifecycleActionInput) => write<IssueLifecycleActionRecord>("issueLifecycle.upsertAction", input);

package/src/db/issue-refs-write-ops.ts

@@ -0,0 +1,29 @@
+// #1870 S7 — issue-ref cache, tracker refresh state and lifecycle ledger writes run on the writer thread.
+// Every body is plain SQL against its own tables. All but `recordNotFound` converge on replay: upserts are
+// keyed by (provider, repo, externalKey) or (issue, action, landKey), updates re-set the same columns.
+import { resolveIssueRefByExternalKey, resolveIssueRefFromString, updateIssueRef, upsertIssueRef, deleteIssueRef, type ResolveIssueRefByExternalKeyInput, type ResolveIssueRefFromStringInput, type UpdateIssueRefInput, type UpsertIssueRefInput } from "./issue-refs.ts";
+import { clearIssueTrackerNotFound, putIssueHierarchy, recordIssueTrackerNotFound } from "./long-running-work.ts";
+import { upsertIssueLifecycleAction, type UpsertIssueLifecycleActionInput } from "./issue-lifecycle.ts";
+import type { IssueTrackerIssueSummary } from "../issue-tracker/adapter";
+import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
+
+export const ISSUE_REFS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
+  "issueRefs.upsert": { offLoop: true, idempotent: true, fn: (args: UpsertIssueRefInput, ctx: WriterOpContext) => upsertIssueRef(args, ctx.now) },
+  "issueRefs.resolveExternalKey": { offLoop: true, idempotent: true, fn: (args: ResolveIssueRefByExternalKeyInput, ctx: WriterOpContext) => resolveIssueRefByExternalKey(args, ctx.now) },
+  "issueRefs.resolveFromString": { offLoop: true, idempotent: true, fn: (args: ResolveIssueRefFromStringInput, ctx: WriterOpContext) => resolveIssueRefFromString(args, ctx.now) },
+  "issueRefs.update": { offLoop: true, idempotent: true, fn: (args: { id: string; input: UpdateIssueRefInput }, ctx: WriterOpContext) => updateIssueRef(args.id, args.input, ctx.now) },
+  "issueRefs.delete": { offLoop: true, idempotent: true, fn: (args: { id: string }) => deleteIssueRef(args.id) },
+  // A tracker answered for this ref: the not-found streak ends and the cached status follows the tracker.
+  "issueRefs.recordLiveStatus": {
+    offLoop: true,
+    idempotent: true,
+    fn: (args: { id: string; input: UpdateIssueRefInput }, ctx: WriterOpContext) => {
+      clearIssueTrackerNotFound(args.id);
+      return updateIssueRef(args.id, args.input, ctx.now);
+    },
+  },
+  "issueRefs.putHierarchy": { offLoop: true, idempotent: true, fn: (args: { id: string; children: IssueTrackerIssueSummary[] }, ctx: WriterOpContext) => putIssueHierarchy(args.id, args.children, ctx.now) },
+  // Increments a counter, so a replay would double-count: keyed.
+  "issueRefs.recordNotFound": { offLoop: true, idempotent: false, fn: (args: { id: string }) => recordIssueTrackerNotFound(args.id) },
+  "issueLifecycle.upsertAction": { offLoop: true, idempotent: true, fn: (args: UpsertIssueLifecycleActionInput, ctx: WriterOpContext) => upsertIssueLifecycleAction(args, ctx.now) },
+});

package/src/db/issue-refs.ts

@@ -151,7 +151,7 @@ export function getIssueRefByExternalKey(provider: IssueProvider, repo: string,
   return row ? rowToIssueRef(row) : null;
 }
 
-export function upsertIssueRef(input: UpsertIssueRefInput): IssueRef {
+export function upsertIssueRef(input: UpsertIssueRefInput, now: number = Date.now()): IssueRef {
   const provider = cleanProvider(input.provider);
   const repo = requiredText(input.repo, "repo", 500);
   const externalKey = requiredText(input.externalKey, "externalKey", 240);
@@ -162,7 +162,6 @@ export function upsertIssueRef(input: UpsertIssueRefInput): IssueRef {
   // An open/unknown upsert clears a stale closeReason; an explicit closeReason requires closed.
   const closeReason = input.closeReason === undefined && status !== "closed" ? undefined : cleanCloseReason(input.closeReason, status) ?? (status === "closed" ? existing?.closeReason : undefined);
   const statusSyncedAt = cleanSyncedAt(input.statusSyncedAt);
-  const now = Date.now();
   if (existing) {
     getDb().query(`
       UPDATE issue_refs
@@ -179,7 +178,7 @@ export function upsertIssueRef(input: UpsertIssueRefInput): IssueRef {
   return getIssueRef(id)!;
 }
 
-export function resolveIssueRefByExternalKey(input: ResolveIssueRefByExternalKeyInput): IssueRef {
+export function resolveIssueRefByExternalKey(input: ResolveIssueRefByExternalKeyInput, now: number = Date.now()): IssueRef {
   const provider = cleanProvider(input.provider);
   const repo = requiredText(input.repo, "repo", 500);
   const externalKey = requiredText(input.externalKey, "externalKey", 240);
@@ -196,7 +195,7 @@ export function resolveIssueRefByExternalKey(input: ResolveIssueRefByExternalKey
     status: input.status ?? existing?.status,
     closeReason: input.closeReason ?? (input.status !== undefined ? undefined : existing?.closeReason),
     statusSyncedAt: input.statusSyncedAt ?? existing?.statusSyncedAt,
-  });
+  }, now);
 }
 
 // A BARE `#123` ref carries no repo, so it only resolves when the caller supplies a
@@ -231,7 +230,7 @@ export function issueRefForRefString(ref: string, defaultRepo?: string): IssueRe
   return getIssueRefByExternalKey("github", parsed.repo, parsed.externalKey);
 }
 
-export function resolveIssueRefFromString(input: ResolveIssueRefFromStringInput): IssueRef {
+export function resolveIssueRefFromString(input: ResolveIssueRefFromStringInput, now: number = Date.now()): IssueRef {
   const ref = requiredText(input.ref, "ref", 1000);
   if (ref.startsWith("issue_")) {
     const existing = getIssueRef(ref);
@@ -250,7 +249,7 @@ export function resolveIssueRefFromString(input: ResolveIssueRefFromStringInput)
     status: input.status,
     closeReason: input.closeReason,
     statusSyncedAt: input.statusSyncedAt,
-  });
+  }, now);
 }
 
 export function listIssueRefs(opts: ListIssueRefsOptions = {}): IssueRef[] {
@@ -281,7 +280,7 @@ export function listIssueRefs(opts: ListIssueRefsOptions = {}): IssueRef[] {
   return rows.map(rowToIssueRef);
 }
 
-export function updateIssueRef(id: string, input: UpdateIssueRefInput): IssueRef | null {
+export function updateIssueRef(id: string, input: UpdateIssueRefInput, now: number = Date.now()): IssueRef | null {
   const existing = getIssueRef(requiredText(id, "id", 120));
   if (!existing) return null;
   const url = optionalText(input.url, "url", 2000) ?? existing.url;
@@ -295,7 +294,7 @@ export function updateIssueRef(id: string, input: UpdateIssueRefInput): IssueRef
     UPDATE issue_refs
     SET url = ?, title = ?, status = ?, close_reason = ?, status_synced_at = ?, updated_at = ?
     WHERE id = ?
-  `).run(url, title ?? null, status, closeReason ?? null, statusSyncedAt ?? null, Date.now(), existing.id);
+  `).run(url, title ?? null, status, closeReason ?? null, statusSyncedAt ?? null, now, existing.id);
   return getIssueRef(existing.id);
 }
 

package/src/db/long-running-work.ts

@@ -49,10 +49,10 @@ export function settlePendingIssueClose(args: PendingIssueCloseKey & { finished:
   else getDb().query("UPDATE pending_issue_closes SET updated_at = ? WHERE issue_ref_id = ? AND land_key = ?").run(now, args.issueRefId, args.landKey);
 }
 
-export function putIssueHierarchy(issueRefId: string, children: IssueTrackerIssueSummary[]): void {
+export function putIssueHierarchy(issueRefId: string, children: IssueTrackerIssueSummary[], now: number = Date.now()): void {
   getDb().query(`INSERT INTO issue_hierarchy_snapshots(issue_ref_id, children, updated_at) VALUES (?, ?, ?)
     ON CONFLICT(issue_ref_id) DO UPDATE SET children = excluded.children, updated_at = excluded.updated_at`)
-    .run(issueRefId, JSON.stringify(children), Date.now());
+    .run(issueRefId, JSON.stringify(children), now);
 }
 
 export function getIssueHierarchy(issueRefId: string): IssueTrackerIssueSummary[] | undefined {

package/src/db/macos-privacy.ts

@@ -68,5 +68,5 @@ export function reconcileMacosPrivacy(args: { orchestratorId: string; prompts: M
 }
 
 export const MACOS_PRIVACY_WRITE_OPS = {
-  "macosPrivacy.reconcile": { idempotent: true, fn: reconcileMacosPrivacy },
+  "macosPrivacy.reconcile": { offLoop: true, idempotent: true, fn: reconcileMacosPrivacy },
 };

package/src/db/main-connection-writes.ts

@@ -34,10 +34,31 @@ export class MainConnectionWriteCounter {
 }
 let counter = new MainConnectionWriteCounter();
 export function resetMainConnectionWrites(): void {
-  if (Bun.isMainThread) counter = new MainConnectionWriteCounter();
+  if (Bun.isMainThread) { counter = new MainConnectionWriteCounter(); bootWrites = 0; loggedLabels.clear(); }
+}
+// #1870 S7: schema, migrations, seeds and pre-bind reconciles write on the main connection before the
+// server binds. That is the documented boot exception (S8 flips query_only after it), so it is tallied
+// apart and never enters the 1 h label window. Only `startServer` opens the phase; tests count from zero.
+let booting = false;
+let bootWrites = 0;
+export function beginMainWriteBootPhase(): void { booting = true; }
+export function endMainWriteBootPhase(): void { booting = false; }
+export function mainConnectionBootWrites(): number { return bootWrites; }
+// The first sighting of each label per process logs its caller once, so the remaining raw writers are named
+// from hub logs without a debugger. Bounded by the counter's own label cap.
+const loggedLabels = new Set<string>();
+function logFirstSighting(label: string): void {
+  if (process.env.NODE_ENV === "test" || loggedLabels.has(label) || loggedLabels.size >= MAX_LABELS) return;
+  loggedLabels.add(label);
+  const site = (new Error().stack ?? "").split("\n").filter((line) => line.includes(" at ") && !/connection|main-connection-writes/.test(line)).slice(0, 4)
+    .map((line) => line.trim().replace(/^at /, "").replace(/\(?\/[^)]*\/(src\/[^):]+:\d+)[^)]*\)?/, "$1")).join(" < ");
+  console.log(`[relay] #1870 main-connection write: ${label} :: ${site}`);
 }
 export function recordMainConnectionWrite(label: string | undefined): void {
-  if (Bun.isMainThread && label) counter.record(label, Date.now());
+  if (!Bun.isMainThread || !label) return;
+  if (booting) { bootWrites++; return; }
+  counter.record(label, Date.now());
+  logFirstSighting(label);
 }
 export function mainConnectionWrites(now: number = Date.now()): Record<string, number> {
   return counter.snapshot(now);

package/src/db/maintenance-job-reconcile.ts

@@ -0,0 +1,61 @@
+import { getDb } from "./connection.ts";
+
+// #1870 S7 — the maintenance job-table reconcile, run-on-start rescheduling and dead-lease reclaim.
+// The scheduler runs the reconcile on every tick, so these were its largest raw main-connection writes.
+
+export interface MaintenanceJobSpec {
+  id: string;
+  title: string;
+  description: string;
+  intervalMs: number;
+  deadlineMs: number;
+  enabled: boolean;
+  critical: boolean;
+  runOnStart: boolean;
+}
+
+/** #1645: `enabled` is code-owned and re-asserted on every reconcile; operator stops live in `maintenance_job_pauses`.
+ *  PRECONDITION: convertManualJobDisablesToPauses() (migrations.ts) ran first. Runs inside the caller's write transaction. */
+export function upsertMaintenanceJobs(jobs: readonly MaintenanceJobSpec[], now: number): void {
+  const stmt = getDb().query(`
+    INSERT INTO maintenance_jobs (id, title, description, interval_ms, timeout_ms, enabled, critical, run_on_start, next_run_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      title = excluded.title,
+      description = excluded.description,
+      interval_ms = excluded.interval_ms,
+      timeout_ms = excluded.timeout_ms,
+      run_on_start = excluded.run_on_start,
+      enabled = excluded.enabled, -- #1645: code-owned, see the note above this query
+      critical = excluded.critical,
+      next_run_at = COALESCE(maintenance_jobs.next_run_at, excluded.next_run_at),
+      updated_at = excluded.updated_at
+  `);
+  // The DB column stays `timeout_ms` (#1728): a rename is a migration. Code-side it is `deadlineMs`.
+  for (const job of jobs) {
+    stmt.run(job.id, job.title, job.description, job.intervalMs, job.deadlineMs, job.enabled ? 1 : 0, job.critical ? 1 : 0, job.runOnStart ? 1 : 0,
+      job.runOnStart ? now : now + job.intervalMs, now);
+  }
+}
+
+/** `runOnStart` means every process start; this is boot-only, never part of the periodic reconcile. */
+export function rescheduleRunOnStartJobs(now: number): void {
+  getDb().query(`
+    UPDATE maintenance_jobs
+    SET next_run_at = ?, updated_at = ?
+    WHERE enabled = 1 AND run_on_start = 1
+  `).run(now, now);
+}
+
+export interface DeadLease { id: string; owner: string; pid: number }
+
+/** #1493/#3645: a confirmed-dead owner is a crash, not a job failure — no failure streak bump, no last_error overwrite. */
+export function reclaimDeadLeases(leases: readonly DeadLease[], now: number): void {
+  const stmt = getDb().query(`
+    UPDATE maintenance_jobs
+    SET lease_owner = NULL, lease_until = NULL, last_status = 'failed',
+        last_error = COALESCE(last_error, ?), run_token = NULL, last_progress_at = ?, updated_at = ?
+    WHERE id = ? AND lease_owner = ?
+  `);
+  for (const lease of leases) stmt.run(`reclaimed stale lease at startup: owner pid ${lease.pid} is confirmed dead`, now, now, lease.id, lease.owner);
+}

package/src/db/maintenance-job-runs-async.ts

@@ -1,4 +1,6 @@
 import { getGateway } from "./gateway.ts";
+import type { ResetCriticalMaintenanceRun } from "./maintenance-health.ts";
+import type { DeadLease, MaintenanceJobSpec } from "./maintenance-job-reconcile.ts";
 import type { MaintenanceRunClaim, MaintenanceRunOutcome } from "./maintenance-job-runs.ts";
 
 // #1870 S3 — lease and outcome writes are critical: a shed claim skips a due job and a shed outcome
@@ -13,3 +15,15 @@ export async function heartbeatMaintenanceRunAsync(args: { id: string; runToken:
 
 export const finishMaintenanceRunAsync = (args: MaintenanceRunOutcome) =>
   getGateway().write("maintenanceJobs.finish", args, { critical: true }) as unknown as Promise<boolean>;
+
+export async function ensureMaintenanceJobsAsync(jobs: MaintenanceJobSpec[]): Promise<void> {
+  await getGateway().write("maintenanceJobs.ensure", { jobs }, { critical: true });
+}
+export async function rescheduleRunOnStartJobsAsync(): Promise<void> {
+  await getGateway().write("maintenanceJobs.rescheduleRunOnStart", {}, { critical: true });
+}
+export async function reclaimDeadLeasesAsync(leases: DeadLease[]): Promise<void> {
+  if (leases.length) await getGateway().write("maintenanceJobs.reclaimDeadLeases", { leases }, { critical: true });
+}
+export const resetExpiredCriticalRunsAsync = (now: number) =>
+  getGateway().write("maintenanceJobs.resetExpiredCritical", { now }, { critical: true }) as unknown as Promise<ResetCriticalMaintenanceRun[]>;

package/src/db/maintenance-job-write-ops.ts

@@ -1,10 +1,19 @@
 import { claimMaintenanceRun, finishMaintenanceRun, heartbeatMaintenanceRun } from "./maintenance-job-runs.ts";
 import type { MaintenanceRunClaim, MaintenanceRunOutcome } from "./maintenance-job-runs.ts";
+import { resetExpiredCriticalMaintenanceRuns } from "./maintenance-health.ts";
+import { reclaimDeadLeases, rescheduleRunOnStartJobs, upsertMaintenanceJobs } from "./maintenance-job-reconcile.ts";
+import type { DeadLease, MaintenanceJobSpec } from "./maintenance-job-reconcile.ts";
 import type { WriterOpSpec } from "./write-ops.ts";
 
 // #1870 S3 — each op is a compare-and-set on the run's own owner/token, so a replay changes nothing.
 export const MAINTENANCE_JOB_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
   "maintenanceJobs.claim": { offLoop: true, idempotent: true, fn: (args: MaintenanceRunClaim) => claimMaintenanceRun(args) },
   "maintenanceJobs.heartbeat": { offLoop: true, idempotent: true, fn: (args: { id: string; runToken: string }, ctx) => heartbeatMaintenanceRun(args, ctx.now) },
+  // Reconcile is a re-assertion of code-owned columns, so a replay changes nothing.
+  "maintenanceJobs.ensure": { offLoop: true, idempotent: true, fn: (args: { jobs: MaintenanceJobSpec[] }, ctx) => upsertMaintenanceJobs(args.jobs, ctx.now) },
+  "maintenanceJobs.rescheduleRunOnStart": { offLoop: true, idempotent: true, fn: (_args: Record<string, never>, ctx) => rescheduleRunOnStartJobs(ctx.now) },
+  "maintenanceJobs.reclaimDeadLeases": { offLoop: true, idempotent: true, fn: (args: { leases: DeadLease[] }, ctx) => reclaimDeadLeases(args.leases, ctx.now) },
+  // A compare-and-set on the observed lease, so a replay finds nothing left to reset.
+  "maintenanceJobs.resetExpiredCritical": { offLoop: true, idempotent: true, fn: (args: { now: number }) => resetExpiredCriticalMaintenanceRuns(args.now) },
   "maintenanceJobs.finish": { offLoop: true, idempotent: true, fn: (args: MaintenanceRunOutcome) => finishMaintenanceRun(args) },
 });

package/src/db/mappers.ts

@@ -1,17 +1,4 @@
-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 { parseStringArray } from "./shared.ts";
 import type {
   AgentCard,
@@ -291,12 +278,14 @@ export function rowToTask(row: any): Task {
     ...(row.dispatch != null ? { dispatch: parseJson(row.dispatch, {}) } : {}),
     ...(row.reaped_at != null ? { reapedAt: row.reaped_at } : {}),
     ...(row.tags != null ? { tags: parseStringArray(row.tags) } : {}),
+    ...(row.paths != null ? { paths: parseStringArray(row.paths) } : {}),
     ...(row.priority != null ? { priority: row.priority as Task["priority"] } : {}),
     ...(row.parent_task_id != null ? { parentTaskId: row.parent_task_id } : {}),
     ...(row.backlog_state != null ? { backlogState: row.backlog_state as Task["backlogState"] } : {}),
     // #2518 — omit false on the wire so legacy payload shapes stay byte-identical for unheld Tasks.
     ...(row.validation_items != null ? { validationItems: parseJson(row.validation_items, []) } : {}),
     ...(row.completed_at != null ? { completedAt: row.completed_at } : {}),
+    ...(row.on_deploy ? { onDeploy: row.on_deploy } : {}),
     ...(row.terminal_stage != null ? { terminalStage: row.terminal_stage as Task["terminalStage"] } : {}),
     ...(row.stale_owner_gone === 1 ? { staleOwnerGone: true } : {}),
     ...(row.review_hold === 1 ? { reviewHold: true } : {}),
@@ -406,7 +395,6 @@ export function rowToActivityEvent(row: any): ActivityEvent {
   };
 }
 
-
 export const MSG_SELECT = `SELECT m.*, (
   SELECT json_group_array(agent_id) FROM message_reads WHERE message_id = m.id
 ) AS read_by_agents, (

package/src/db/merge-lease.ts

@@ -1,19 +1,5 @@
-import { Database } from "bun:sqlite";
 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, MAIN_MERGE_PAUSE_TTL_MS } from "../config";
-import { matchAgents } from "../agent-ref";
+import { WORKSPACE_MERGE_LEASE_MS, MAIN_MERGE_PAUSE_TTL_MS } from "../config";
 import { incidentEligibleSql } from "./land-incident-eligibility";
 import { getDb, writeTransaction } from "./connection.ts";
 

package/src/db/message-reads-write-ops.ts

@@ -6,15 +6,18 @@ export const MESSAGE_READS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = O
   // Both writes converge on retry: INSERT OR IGNORE/read-state updates and deleting an absent row
   // are no-ops, so a phantom-failure retry is safe without a caller key.
   "messageReads.markRead": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { messageId: number; agentId: string }, ctx: WriterOpContext) => markRead(args.messageId, args.agentId, ctx.now),
   },
   "messageReads.delete": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { id: number }) => deleteMessage(args.id, false),
   },
   // #3054 — re-derives each drifted pair from the source tables at write time, so a stale snapshot is harmless.
   "messageReads.reconcileReplyObligations": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { pairs: Array<{ messageId: number; agentId: string }> }) => {
       for (const { messageId, agentId } of args.pairs) reconcileReplyObligation(messageId, agentId);

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

@@ -52,6 +52,7 @@ export interface MessageClaimOpArgs {
 
 export const MESSAGE_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
   "messages.flushCoordinatorDigests": {
+    offLoop: true,
     idempotent: true,
     fn: (_args: unknown, ctx: WriterOpContext) => flushCoordinatorDigestsBody(ctx.now),
   },
@@ -77,6 +78,7 @@ export const MESSAGE_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.
   // A keyed reaction row is an upsert/delete, so replaying the same request converges on the
   // requested state. The lookup and mutation execute in the same writer transaction.
   "messages.reaction": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { input: Parameters<typeof setMessageReaction>[0] }, ctx: WriterOpContext) =>
       setMessageReaction(args.input, ctx.now),
@@ -84,11 +86,13 @@ export const MESSAGE_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.
   // The expiry sweep, eligibility reads, message CAS, linked-task transition, and renewal all run
   // in this single writer transaction. A separate release/read hop would race a concurrent claimer.
   "messages.claim": {
+    offLoop: true,
     idempotent: true,
     fn: (args: MessageClaimOpArgs, ctx: WriterOpContext) =>
       claimMessageBody(args.messageId, args.agentId, args.guard, ctx.now),
   },
   "messages.renewClaim": {
+    offLoop: true,
     idempotent: true,
     fn: (args: MessageClaimOpArgs, ctx: WriterOpContext) =>
       renewMessageClaimBody(args.messageId, args.agentId, args.guard, ctx.now),

package/src/db/migrations.ts

@@ -21,7 +21,6 @@ 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";
@@ -30,20 +29,8 @@ 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 { PROJECT_PROFILE_INSTRUCTIONS_SCHEMA_SQL } from "./project-profile-instructions";
+import { CLAIM_LEASE_MS } from "../config";
 import { COORDINATOR_PROFILE_NAMES } from "../agent-system-tags";
 import { getDb } from "./connection.ts";
 import { normalizeExistingAgentSpawnRequestIds } from "./spawn-request-id-migration.ts";
@@ -154,6 +141,7 @@ function backfillProjectRootRemoteUrls(): void {
 // 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(PROJECT_PROFILE_INSTRUCTIONS_SCHEMA_SQL);
   getDb().run(PLAN_IMPORT_SCHEMA_SQL);
   ensureVaultTokensSchema();
   ensureVaultHealthSchema();
@@ -1281,6 +1269,7 @@ export function applyMigrations(): void {
   // addTaskCol guard as the rest of the #834 batch: existing rows read back as absent.
   addTaskCol("tags", "tags TEXT");
   addTaskCol("priority", "priority TEXT");
+  addTaskCol("paths", "paths TEXT"); // #3736
   // #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.
@@ -1294,10 +1283,13 @@ export function applyMigrations(): void {
   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("on_deploy", "on_deploy 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");
+  // #3740: existing databases need the same covering expression index as fresh schemas.
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_integration_stats ON tasks(coalesce(json_extract(metadata, '$.relayIntegrationName'), source), status, claimed_by, last_seen_at, updated_at, source)");
   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");

package/src/db/orchestrators-async.ts

@@ -4,13 +4,17 @@ import { getGateway } from "./gateway.ts";
 import { coalesceLifecycleWrite } from "./lifecycle-write-window.ts";
 import { nextLifecycleSeq } from "./lifecycle-seq.ts";
 import { evictPendingPresence } from "./presence-buffer.ts";
-import type { getOrchestrator, listOrchestrators, OrchestratorRosterResult, upsertOrchestrator } from "./orchestrators.ts";
+import type { getOrchestrator, listOrchestrators, OrchestratorRosterResult, registerOrchestratorOp, upsertOrchestrator } from "./orchestrators.ts";
+import { finishAgentUpsertAsync } from "./agents-async.ts";
 import { emitWorkspaceUpsert } from "./workspaces.ts";
 import type { ManagedAgent, OrchestratorRuntimeInput, OrchestratorUpgradeState, QueuedSpawn } from "../types.ts";
 import { STALE_TTL_MS } from "../config.ts";
 
-export function upsertOrchestratorAsync(input: Parameters<typeof upsertOrchestrator>[0]): Promise<ReturnType<typeof upsertOrchestrator>> {
-  return getGateway().write("orchestrators.register", input, { critical: true }) as unknown as Promise<ReturnType<typeof upsertOrchestrator>>;
+export async function upsertOrchestratorAsync(input: Parameters<typeof upsertOrchestrator>[0]): Promise<ReturnType<typeof upsertOrchestrator>> {
+  const seq = nextLifecycleSeq(); // before the await, per the ordinal-timing rule (lifecycle-seq.ts)
+  const { orchestrator, agent, contextState } = await getGateway().write("orchestrators.register", { input, seq }, { critical: true }) as unknown as ReturnType<typeof registerOrchestratorOp>;
+  await finishAgentUpsertAsync(agent.id, { agent, contextState });
+  return orchestrator;
 }
 
 export function getOrchestratorAsync(id: string): Promise<ReturnType<typeof getOrchestrator>> {

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

@@ -3,6 +3,7 @@
 import {
   orchestratorHeartbeatInternal,
   reapStaleOrchestratorsInternal,
+  registerOrchestratorOp,
   reportOrchestratorRosterRow,
   setOrchestratorUpgradeState,
   upsertOrchestrator,
@@ -14,10 +15,13 @@ import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
 
 export const ORCHESTRATORS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
   "orchestrators.register": {
+    offLoop: true,
     idempotent: true,
-    fn: (input: Parameters<typeof upsertOrchestrator>[0]) => upsertOrchestrator(input),
+    // The agent row's follow-ups (presence eviction, pool binding, steward election) run in the facade.
+    fn: (a: { input: Parameters<typeof upsertOrchestrator>[0]; seq: number }, ctx) => registerOrchestratorOp(a.input, ctx.now, a.seq),
   },
   "orchestrators.heartbeat": {
+    offLoop: true,
     idempotent: true,
     fn: (a: { id: string; runtime: OrchestratorRuntimeInput; seq?: number }, ctx) => {
       const orchestrator = orchestratorHeartbeatInternal(a.id, a.runtime, ctx.now);
@@ -42,10 +46,12 @@ export const ORCHESTRATORS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = O
     fn: (a: { id: string; agents: ManagedAgent[]; queuedSpawns?: QueuedSpawn[] }, ctx) => reportOrchestratorRosterRow(a.id, a.agents, a.queuedSpawns, ctx.now),
   },
   "orchestrators.upgrade.set": {
+    offLoop: true,
     idempotent: true,
     fn: (a: { id: string; state: OrchestratorUpgradeState | null }) => setOrchestratorUpgradeState(a.id, a.state),
   },
   "orchestrators.reap": {
+    offLoop: true,
     idempotent: true,
     fn: (a: { cutoff: number; seq: number }, ctx) => reapStaleOrchestratorsInternal(ctx.now - STALE_TTL_MS, a.seq),
   },