@humwick/server 0.130.2 → 0.130.3

package/src/automations/reconcile.ts

@@ -1,29 +1,20 @@
-import { createCommand } from "../commands-db";
-import { getAgent, getTaskAsync, listAgents, listOrchestrators, sendMessage, updateTaskStatusAsync } from "../db";
+import { updateRunAsync } from "./write-async";
+import { sendMessageAsync } from "../db/message-send";
+import { createCommandAsync } from "../commands-write";
+
+import { getAgent, getTaskAsync, listAgents, listOrchestrators, updateTaskStatusAsync } from "../db";
 import { renderTemplate } from "../prompt-resolver";
 import { CLOSED_TASK_STATUS } from "./constants";
 import { settleAutomationPrechecks } from "./precheck";
-import {
-  ensureAutomationTables,
-  getAutomation,
-  getAutomationRun,
-  rowToAutomationRun,
-  updateRun,
-  db,
-} from "./storage";
+import { listReconcilableRunsAsync } from "./read-async";
+import { ensureAutomationTables, getAutomation, getAutomationRun } from "./storage";
 import type { AutomationReconcileResult } from "./types";
 import type { AgentCard, AutomationRun, AutomationRunStatus, AutomationRuntimeBudget, Command, Message, Task } from "../types";
 
 export async function reconcileAutomationRuns(now = Date.now()): Promise<AutomationReconcileResult[]> {
   ensureAutomationTables();
   const results: AutomationReconcileResult[] = await settleAutomationPrechecks(now);
-  const rows = db().query(`
-    SELECT * FROM automation_runs
-    WHERE status IN ('scheduled', 'dispatching', 'waiting_agent', 'running') AND task_id IS NOT NULL
-    ORDER BY created_at ASC
-  `).all() as any[];
-  for (const row of rows) {
-    const run = rowToAutomationRun(row);
+  for (const run of await listReconcilableRunsAsync()) {
     const task = run.taskId ? await getTaskAsync(run.taskId) : null;
     if (!task) continue;
 
@@ -31,12 +22,12 @@ export async function reconcileAutomationRuns(now = Date.now()): Promise<Automat
     const hasRuntimeMetaChange = hasMetaChanges(run.meta, runtimeMeta);
     const nextOpenStatus: AutomationRunStatus = task.status === "open" ? "waiting_agent" : "running";
     if ((task.claimedBy && task.claimedBy !== run.targetAgentId) || run.status !== nextOpenStatus || hasRuntimeMetaChange) {
-      updateRun(run.id, {
+      (await updateRunAsync(run.id, {
         status: nextOpenStatus,
         targetAgentId: task.claimedBy ?? run.targetAgentId,
         spawnedAgentId: run.spawnedAgentId ?? task.claimedBy,
         meta: hasRuntimeMetaChange ? { ...run.meta, ...runtimeMeta } : undefined,
-      }, now);
+      }, now));
     }
 
     if (!CLOSED_TASK_STATUS.has(task.status)) {
@@ -52,22 +43,22 @@ export async function reconcileAutomationRuns(now = Date.now()): Promise<Automat
         results.push(timedOut);
         continue;
       }
-      const warning = maybeWarnRuntimeBudget(updated, task, now);
+      const warning = (await maybeWarnRuntimeBudget(updated, task, now));
       results.push({ run: getAutomationRun(run.id) ?? updated, task, message: warning });
       continue;
     }
 
     const status: AutomationRunStatus = task.status === "done" ? "succeeded" : task.status === "canceled" ? "canceled" : "failed";
-    updateRun(run.id, {
+    (await updateRunAsync(run.id, {
       status,
       finishedAt: now,
       result: { taskStatus: task.status, result: task.result ?? null },
       targetAgentId: task.claimedBy ?? run.targetAgentId,
       spawnedAgentId: run.spawnedAgentId ?? task.claimedBy,
       meta: hasMetaChanges(run.meta, runtimeMeta) ? { ...run.meta, ...runtimeMeta } : undefined,
-    }, now);
+    }, now));
     const updated = getAutomationRun(run.id)!;
-    const command = maybeShutdownOnDemandAgent(updated, task, now);
+    const command = (await maybeShutdownOnDemandAgent(updated, task, now));
     results.push({ run: getAutomationRun(run.id)!, task, command });
   }
   return results;
@@ -140,7 +131,7 @@ function runtimeWarningAt(run: AutomationRun, budget: AutomationRuntimeBudget):
   return run.startedAt + budget.warnAtMs;
 }
 
-function maybeWarnRuntimeBudget(run: AutomationRun, task: Task, now: number): Message | undefined {
+async function maybeWarnRuntimeBudget(run: AutomationRun, task: Task, now: number): Promise<Message | undefined> {
   if (run.meta.runtimeBudgetWarnedAt) return undefined;
   const budget = runtimeBudgetForRun(run);
   if (!budget) return undefined;
@@ -150,7 +141,7 @@ function maybeWarnRuntimeBudget(run: AutomationRun, task: Task, now: number): Me
   const target = runtimeBudgetMessageTarget(run, task);
   if (!target) return undefined;
   const remainingMinutes = Math.max(1, Math.ceil((deadline - now) / 60_000));
-  const message = sendMessage({
+  const message = (await sendMessageAsync({
     from: "system",
     to: target,
     kind: "control",
@@ -173,15 +164,15 @@ function maybeWarnRuntimeBudget(run: AutomationRun, task: Task, now: number): Me
       automationRunId: run.id,
       runtimeBudgetWarning: true,
     },
-  });
-  updateRun(run.id, {
+  }));
+  (await updateRunAsync(run.id, {
     meta: {
       ...run.meta,
       runtimeBudgetWarnedAt: now,
       runtimeBudgetWarningMessageId: message.id,
       runtimeBudgetDeadlineAt: deadline,
     },
-  }, now);
+  }, now));
   return message;
 }
 
@@ -205,7 +196,7 @@ async function maybeFailNeverReadyOfflineTarget(run: AutomationRun, task: Task,
     },
   }, { privileged: true });
   const updatedTask = taskResult.task ?? (await getTaskAsync(task.id)) ?? task;
-  updateRun(run.id, {
+  (await updateRunAsync(run.id, {
     status: "failed",
     finishedAt: now,
     error: reason,
@@ -225,7 +216,7 @@ async function maybeFailNeverReadyOfflineTarget(run: AutomationRun, task: Task,
       runtimeTargetOfflineAt: now,
       runtimeTargetNeverReady: true,
     },
-  }, now);
+  }, now));
   return { run: getAutomationRun(run.id)!, task: (await getTaskAsync(task.id)) ?? updatedTask };
 }
 
@@ -251,8 +242,8 @@ async function maybeTimeoutRuntimeBudget(run: AutomationRun, task: Task, now: nu
     },
   }, { privileged: true });
   const updatedTask = taskResult.task ?? (await getTaskAsync(task.id)) ?? task;
-  const command = requestOnDemandAgentShutdown(run, updatedTask, now, "runtime-budget-timeout");
-  updateRun(run.id, {
+  const command = (await requestOnDemandAgentShutdown(run, updatedTask, now, "runtime-budget-timeout"));
+  (await updateRunAsync(run.id, {
     status: "timed_out",
     finishedAt: now,
     error: "Automation runtime budget elapsed",
@@ -273,7 +264,7 @@ async function maybeTimeoutRuntimeBudget(run: AutomationRun, task: Task, now: nu
       runtimeBudgetDeadlineAt: deadline,
       ...(command ? { shutdownCommandId: command.id } : {}),
     },
-  }, now);
+  }, now));
   return { run: getAutomationRun(run.id)!, task: (await getTaskAsync(task.id)) ?? updatedTask, command };
 }
 
@@ -285,19 +276,19 @@ function runtimeBudgetMessageTarget(run: AutomationRun, task: Task): string | un
   return undefined;
 }
 
-function maybeShutdownOnDemandAgent(run: AutomationRun, task: Task, now: number): Command | undefined {
+async function maybeShutdownOnDemandAgent(run: AutomationRun, task: Task, now: number): Promise<Command | undefined> {
   if (run.shutdownRequestedAt) return undefined;
   const automation = getAutomation(run.automationId);
   if (!automation || automation.targetPolicy.mode !== "on_demand_agent" || automation.targetPolicy.keepAlive) return undefined;
-  const command = requestOnDemandAgentShutdown(run, task, now, "task-complete");
-  if (command) updateRun(run.id, { shutdownRequestedAt: now, meta: { ...run.meta, shutdownCommandId: command.id } }, now);
+  const command = (await requestOnDemandAgentShutdown(run, task, now, "task-complete"));
+  if (command) (await updateRunAsync(run.id, { shutdownRequestedAt: now, meta: { ...run.meta, shutdownCommandId: command.id } }, now));
   return command;
 }
 
-function requestOnDemandAgentShutdown(run: AutomationRun, task: Task, now: number, reason: string): Command | undefined {
+async function requestOnDemandAgentShutdown(run: AutomationRun, task: Task, now: number, reason: string): Promise<Command | undefined> {
   const agentId = task.claimedBy ?? run.targetAgentId ?? run.spawnedAgentId;
   if (!agentId) return undefined;
-  return createCommand({
+  return (await createCommandAsync({
     type: "agent.shutdown",
     source: "automation",
     target: agentId,
@@ -310,5 +301,5 @@ function requestOnDemandAgentShutdown(run: AutomationRun, task: Task, now: numbe
       automationRunId: run.id,
       reason,
     },
-  });
+  }));
 }

package/src/automations/storage.ts

@@ -70,8 +70,8 @@ export function listAutomations(): Automation[] {
     .map(rowToAutomation);
 }
 
-export function listAutomationRuns(filter: { automationId?: string; status?: string; limit?: number } = {}): AutomationRun[] {
-  ensureAutomationTables();
+/** Listing SQL, exported so the query-plan gate pins the production statement (#3799). */
+export function buildListAutomationRunsQuery(filter: { automationId?: string; status?: string; limit?: number } = {}): { sql: string; params: (string | number)[] } {
   const clauses: string[] = [];
   const params: (string | number)[] = [];
   if (filter.automationId) {
@@ -84,8 +84,13 @@ export function listAutomationRuns(filter: { automationId?: string; status?: str
   }
   const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
   params.push(filter.limit ?? 100);
-  return (db().query(`SELECT * FROM automation_runs ${where} ORDER BY created_at DESC LIMIT ?`).all(...params) as any[])
-    .map(rowToAutomationRun);
+  return { sql: `SELECT * FROM automation_runs ${where} ORDER BY created_at DESC LIMIT ?`, params };
+}
+
+export function listAutomationRuns(filter: { automationId?: string; status?: string; limit?: number } = {}): AutomationRun[] {
+  ensureAutomationTables();
+  const { sql, params } = buildListAutomationRunsQuery(filter);
+  return (db().query(sql).all(...params) as any[]).map(rowToAutomationRun);
 }
 
 export function getAutomationRun(id: string): AutomationRun | null {
@@ -176,25 +181,43 @@ export function cancelActiveRuns(automationId: string, now: number, reason: stri
     .run(now, reason, now, automationId, ...OPEN_RUN_STATUSES);
 }
 
+/** Enabled automations whose next fire time has passed; indexed on (enabled, next_run_at). */
+export const DUE_AUTOMATIONS_SQL = "SELECT * FROM automations WHERE enabled = 1 AND next_run_at IS NOT NULL AND next_run_at <= ? ORDER BY next_run_at ASC LIMIT 25";
+export function listDueAutomations(now: number): Automation[] {
+  return (db().query(DUE_AUTOMATIONS_SQL).all(now) as any[]).map(rowToAutomation);
+}
+
 export function rescheduleAutomation(automation: Automation, nextRunAt: number | undefined, now: number): void {
   db().query("UPDATE automations SET next_run_at = ?, updated_at = ? WHERE id = ?").run(nextRunAt ?? null, now, automation.id);
 }
 
 /** #3175 — runs whose precheck command has been dispatched but not yet settled. */
-export function listPendingPrecheckRuns(): AutomationRun[] {
-  return (db().query(`
+export const PENDING_PRECHECK_RUNS_SQL = `
     SELECT * FROM automation_runs
     WHERE status = 'running' AND task_id IS NULL AND json_extract(meta, '$.precheck.status') = 'running'
     ORDER BY created_at ASC LIMIT 100
-  `).all() as any[]).map(rowToAutomationRun);
+  `;
+export function listPendingPrecheckRuns(): AutomationRun[] {
+  return (db().query(PENDING_PRECHECK_RUNS_SQL).all() as any[]).map(rowToAutomationRun);
+}
+
+/** Open runs bound to a task: the reconcile pass walks these against the task's live state. */
+export const RECONCILABLE_RUNS_SQL = `
+    SELECT * FROM automation_runs
+    WHERE status IN ('scheduled', 'dispatching', 'waiting_agent', 'running') AND task_id IS NOT NULL
+    ORDER BY created_at ASC
+  `;
+export function listReconcilableRuns(): AutomationRun[] {
+  return (db().query(RECONCILABLE_RUNS_SQL).all() as any[]).map(rowToAutomationRun);
 }
 
 /** Queued runs ready to dispatch. A run whose precheck already reported hits was accepted while the
  * automation was runnable (Run now works on disabled automations), so it continues regardless. */
-export function listDispatchableQueuedRuns(): AutomationRun[] {
-  return (db().query(`
+export const DISPATCHABLE_QUEUED_RUNS_SQL = `
     SELECT r.* FROM automation_runs r JOIN automations a ON a.id = r.automation_id
     WHERE r.status = 'scheduled' AND (a.enabled = 1 OR json_extract(r.meta, '$.precheck.status') = 'hits')
     ORDER BY r.scheduled_for ASC LIMIT 25
-  `).all() as any[]).map(rowToAutomationRun);
+  `;
+export function listDispatchableQueuedRuns(): AutomationRun[] {
+  return (db().query(DISPATCHABLE_QUEUED_RUNS_SQL).all() as any[]).map(rowToAutomationRun);
 }

package/src/automations/write-async.ts

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { getGateway } from "../db/gateway";
+import type { insertAutomation, updateAutomationNormalized } from "./persistence";
+import type { Automation, AutomationRun } from "../types";
+import type { insertRun, enqueueAutomationRun, updateRun, cancelActiveRuns, rescheduleAutomation } from "./storage";
+
+export function insertAutomationAsync(normalized: Parameters<typeof insertAutomation>[0], now: number): Promise<Automation> {
+  return getGateway().write("automations.create", { normalized, now }, { idempotencyKey: randomUUID() }) as unknown as Promise<Automation>;
+}
+export function updateAutomationNormalizedAsync(id: string, normalized: Parameters<typeof updateAutomationNormalized>[1], expected: Automation, now: number): Promise<Automation> {
+  return getGateway().write("automations.update", { id, normalized, expected, now }, { idempotencyKey: randomUUID() }) as unknown as Promise<Automation>;
+}
+export function deleteAutomationAsync(id: string): Promise<boolean> {
+  return getGateway().write("automations.delete", { id }) as unknown as Promise<boolean>;
+}
+export function admitAutomationRunAsync(input: { automationId: string; now: number; manual?: boolean; queuedRunId?: string }): Promise<{ automation: Automation; run: AutomationRun } | null> {
+  return getGateway().write("automations.admitRun", input, { idempotencyKey: randomUUID() }) as unknown as Promise<{ automation: Automation; run: AutomationRun } | null>;
+}
+export function insertRunAsync(...args: Parameters<typeof insertRun>): Promise<ReturnType<typeof insertRun>> {
+  return getGateway().write("automations.insertRun", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof insertRun>>;
+}
+export function enqueueAutomationRunAsync(...args: Parameters<typeof enqueueAutomationRun>): Promise<ReturnType<typeof enqueueAutomationRun>> {
+  return getGateway().write("automations.enqueueRun", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof enqueueAutomationRun>>;
+}
+export function updateRunAsync(...args: Parameters<typeof updateRun>): Promise<void> {
+  return getGateway().write("automations.updateRun", args, { idempotencyKey: randomUUID() }) as unknown as Promise<void>;
+}
+export function cancelActiveRunsAsync(...args: Parameters<typeof cancelActiveRuns>): Promise<void> {
+  return getGateway().write("automations.cancelRuns", args, { idempotencyKey: randomUUID() }) as unknown as Promise<void>;
+}
+export function rescheduleAutomationAsync(...args: Parameters<typeof rescheduleAutomation>): Promise<void> {
+  return getGateway().write("automations.reschedule", args, { idempotencyKey: randomUUID() }) as unknown as Promise<void>;
+}

package/src/branch-land-notice.ts

@@ -15,7 +15,7 @@ export async function announceVerifiedLand(input: BranchLandedInput, landedTask:
   const verification = input.mergedSha && input.landVerifiedSha === input.mergedSha
     ? "confirmed" : await verifyPublishedLand(workspace.repoRoot, input.mergedSha, workspace.baseRef);
   if (verification !== "confirmed") {
-    notifyLandUnconfirmed({ workspace, sha: input.mergedSha, targetRef: base.startsWith("origin/") ? base : `origin/${base}`, kind: verification });
+    await notifyLandUnconfirmed({ workspace, sha: input.mergedSha, targetRef: base.startsWith("origin/") ? base : `origin/${base}`, kind: verification });
     return;
   }
   const landedBranch = workspace.branch;
@@ -47,7 +47,7 @@ export async function announceVerifiedLand(input: BranchLandedInput, landedTask:
       : " Worktree reclaimed.";
     // Durable (ttl null): the author's own branch landing must reach them even after they go
     // offline (store-ahead #234) — not a bystander notice that goes stale.
-    const notices = routeNotification({
+    const notices = await routeNotification({
       type: "branch.landed",
       scope: { author, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
       recipients: [author],
@@ -75,7 +75,7 @@ export async function announceVerifiedLand(input: BranchLandedInput, landedTask:
   const mainScope = { author, repoRoot: workspace.repoRoot, workspaceId: workspace.id, teamId: landedTask?.teamId ?? (author ? getAgent(author)?.teamId : undefined), coordinatorAgentIds: [...new Set([resolveCoordinatorAgentId(author), landedTask && resolveTaskOwnerAgentId(getTaskDetail(landedTask.taskId))].filter((id): id is string => !!id && !isHumanAgentId(id)))] };
   const branchLabel = landedBranch ? `\`${landedBranch}\`` : "A branch";
   const authorLabel = author ? ` by \`${author}\`` : "";
-  const notices = routeNotification({
+  const notices = await routeNotification({
     type: "branch.landed",
     scope: mainScope, ...audienceWithTaskOwnerRole("branch.landed", mainScope, landedTask?.taskId), // #2862
     ttlMs: INFORMATIONAL_TTL_MS,

package/src/branch-landed.ts

@@ -1,10 +1,12 @@
+import { insertLandingReceiptAsync } from "./db/runtime-tail-async";
+import { createActivityEventAsync } from "./db/activity-async";
 import { announceVerifiedLand } from "./branch-land-notice";
 import { errMessage, isHumanAgentId, type BaseWorktreeSyncResult } from "@humwick/sdk";
 import { emitRelayEvent } from "./events";
 import { routeNotification, INFORMATIONAL_TTL_MS } from "./notification-router";
 import { stampLifecycleSignal, taskSignalKey } from "./lifecycle-signal-registry";
 import { registerDefaultAudienceRules, audiencePredicates } from "./notification-rules";
-import { createActivityEvent, getAgent, getOrchestrator, getProject, getTaskDetail, insertLandingReceipt, markWorkspaceLanded, patchWorkspaceMetadataAsync, resolveProjectForCwd, updateWorkspaceStatusAsync, markWorkspaceLandedAsync} from "./db";
+import { getAgent, getOrchestrator, getProject, getTaskDetail, markWorkspaceLanded, patchWorkspaceMetadataAsync, resolveProjectForCwd, updateWorkspaceStatusAsync, markWorkspaceLandedAsync } from "./db";
 import { renderTemplate } from "./prompt-resolver";
 import { resolveCoordinatorAgentId } from "./steward-identity";
 import { stewardFallbackTarget } from "./config";
@@ -209,9 +211,9 @@ function landedNotificationIdempotencyKey(input: BranchLandedInput, landedTask:
  * the announcement; this combined entry preserves the original all-synchronous behavior for the
  * maintenance reconcile path (reconcileLandedWorkspace) and direct callers/tests.
  */
-export function notifyBranchLanded(input: BranchLandedInput): void {
-  recordLandingReceipt(input);
-  announceBranchLanded(input);
+export async function notifyBranchLanded(input: BranchLandedInput): Promise<void> {
+  (await recordLandingReceipt(input));
+  await announceBranchLanded(input);
 }
 
 /**
@@ -222,7 +224,7 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
  * row with no receipt. The branch is already landed, so a receipt failure is loud (CRITICAL log) but
  * can never unwind or mask it.
  */
-export function recordLandingReceipt(input: BranchLandedInput): void {
+export async function recordLandingReceipt(input: BranchLandedInput): Promise<void> {
   const { workspace } = input;
   // #1620 — a land that introduced ZERO commits is not a land: no receipt (see announceBranchLanded).
   if (input.landedCommitCount === 0) return;
@@ -237,7 +239,7 @@ export function recordLandingReceipt(input: BranchLandedInput): void {
     const mergedSha = cleanRef(input.mergedSha);
     const commitShas = [...new Set((input.commitShas ?? []).map(cleanRef).filter((sha): sha is string => Boolean(sha)))];
     if (commitShas.length === 0 && mergedSha) commitShas.push(mergedSha);
-    insertLandingReceipt({
+    (await insertLandingReceiptAsync({
       ...(landedTask?.projectId ?? project?.id ? { projectId: landedTask?.projectId ?? project!.id } : {}),
       repo: landedTask?.repo ?? project?.issueRepo ?? repoFromGitRemote(workspace.repoRoot) ?? workspace.repoRoot,
       ref: workspace.baseRef ?? "base",
@@ -253,7 +255,7 @@ export function recordLandingReceipt(input: BranchLandedInput): void {
       ...(landedTask?.teamId ?? worker?.teamId ? { teamId: landedTask?.teamId ?? worker!.teamId } : {}),
       ...(workspace.orchestratorId ? { orchestratorId: workspace.orchestratorId } : {}),
       ...(orchestrator?.hostname ?? worker?.machine ?? worker?.rig ? { host: orchestrator?.hostname ?? worker?.machine ?? worker!.rig } : {}),
-    });
+    }));
   } catch (error) {
     console.error(`[landing-receipt] CRITICAL: failed to persist landed branch ${workspace.id}: ${errMessage(error)}`);
   }
@@ -265,7 +267,7 @@ export function recordLandingReceipt(input: BranchLandedInput): void {
  * the issue/Task lifecycle drives. #1790 — the settle path DEFERS this off its synchronous critical
  * path; the durable receipt is recorded separately + synchronously by {@link recordLandingReceipt}.
  */
-export function announceBranchLanded(input: BranchLandedInput): void {
+export async function announceBranchLanded(input: BranchLandedInput): Promise<void> {
   const { workspace } = input;
   const base = workspace.baseRef ?? "base";
   // #1620 — a land that introduced ZERO commits is not a land. It happens when a reconciliation
@@ -365,10 +367,10 @@ export function announceBranchLanded(input: BranchLandedInput): void {
  * the checkout. Human WIP is never auto-clobbered; `preservedWipPaths` flags paths to merge by
  * hand rather than blind-restore.
  */
-export function notifyBaseWorktreeStrand(input: {
+export async function notifyBaseWorktreeStrand(input: {
   workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
   sync: BaseWorktreeSyncResult;
-}): void {
+}): Promise<void> {
   const { workspace, sync } = input;
   if (sync.reconciled) return;
   const base = workspace.baseRef ?? "base";
@@ -397,7 +399,7 @@ export function notifyBaseWorktreeStrand(input: {
 
   emitRelayEvent({ type: "workspace.base_checkout_strand", source: "server", subject: workspace.id, data: payload });
 
-  createActivityEvent({
+  (await createActivityEventAsync({
     clientId: `workspace-base-strand-${workspace.id}-${Date.now()}`,
     kind: "state",
     title: "Base checkout stranded after land (mixed state)",
@@ -406,13 +408,13 @@ export function notifyBaseWorktreeStrand(input: {
     icon: "ti-alert-octagon",
     view: "orchestrators",
     metadata: { source: "server", maintenanceJobId: "workspace-base-strand", workspaceId: workspace.id, repoRoot: workspace.repoRoot, unsyncedPaths: unsynced, preservedWipPaths: preservedWip },
-  });
+  }));
 
   // Durable (ttl null) push to the owner and its coordinator — whoever works in the shared
   // checkout must learn it's stale before acting on it. Fallback steward covers a teamless land.
   const recipients = [...new Set([owner, coordinator, fallback].filter((r): r is string => Boolean(r)))];
   if (recipients.length) {
-    routeNotification({
+    await routeNotification({
       type: "workspace.base_checkout_strand",
       scope: { author: owner, parent: coordinator ?? undefined, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
       recipients,
@@ -432,12 +434,12 @@ export function notifyBaseWorktreeStrand(input: {
  * steward-task/conflict pings: it tells the worker that its post-ready idle wait ended without
  * a completed land, so it can inspect/report instead of silently staying parked forever.
  */
-export function notifyBranchLandFailed(input: {
+export async function notifyBranchLandFailed(input: {
   workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
   commandId?: string;
   recipients?: string[];
   reason?: string;
-}): void {
+}): Promise<void> {
   const { workspace } = input;
   const base = workspace.baseRef ?? "base";
   const author = workspace.ownerAgentId;
@@ -464,7 +466,7 @@ export function notifyBranchLandFailed(input: {
   const recipients = withWorkspaceTaskOwnerRoles(input.recipients ?? [author, coordinator], workspace); // #2862
   if (!recipients.length) return;
   const branchLabel = workspace.branch ? `\`${workspace.branch}\`` : "Your branch";
-  routeNotification({
+  await routeNotification({
     type: "landed-failure",
     scope: { author, parent: coordinator ?? undefined, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
     recipients,
@@ -494,7 +496,7 @@ export { notifyLandGateFailed, notifyLandGateWarnings, notifyLandGateSkipped } f
  * The steward id is the managed steward's policy name (reachable via `policy:<name>`) or an
  * elected steward's agent id, whichever the caller has in scope.
  */
-export function notifyStewardHandoff(input: {
+export async function notifyStewardHandoff(input: {
   workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
   /** The steward now holding the merge — managed steward policy name or elected agent id. */
   stewardId: string;
@@ -502,7 +504,7 @@ export function notifyStewardHandoff(input: {
   coordinatorAgentId?: string | null;
   /** Why it was handed over ("conflict", "merge state unknown", auto-merge back-off, …). */
   reason?: string;
-}): void {
+}): Promise<void> {
   const { workspace } = input;
   const base = workspace.baseRef ?? "base";
   const owner = workspace.ownerAgentId;
@@ -527,7 +529,7 @@ export function notifyStewardHandoff(input: {
   // thinking the branch silently failed. Durable (ttl null): the owner must learn this
   // even if it went idle. Mirror the "don't touch main" guardrail of the landed-failure wake.
   if (owner) {
-    routeNotification({
+    await routeNotification({
       type: "workspace.steward_handoff",
       scope: { author: owner, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
       recipients: [owner],
@@ -550,7 +552,7 @@ export function notifyStewardHandoff(input: {
   // (it spawned the branch agent and owns the merge landing). Skip when the coordinator IS
   // the owner (no real lineage) to avoid a duplicate ping.
   if (coordinator && coordinator !== owner) {
-    routeNotification({
+    await routeNotification({
       type: "workspace.steward_handoff",
       scope: { author: owner, parent: coordinator, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
       recipients: [coordinator],
@@ -671,7 +673,7 @@ export async function reconcileLandedWorkspace(ws: WorkspaceRecord, preview: Wor
   const closure = ownerAlive
     ? `owner \`${ws.ownerAgentId}\` is still running, so the workspace stays non-terminal and usable at ${nextStatus}${nextStatus === ws.status ? "" : ` (was ${ws.status} — out of the land queue, #1662)`} (#1631); steward/strand and no-progress bookkeeping cleared`
     : `marking merged${landedCommitCount === 0 ? "; nothing was landed" : ""}`;
-  createActivityEvent({
+  (await createActivityEventAsync({
     clientId: "server-workspace-" + ws.id + "-merged-" + Date.now(),
     kind: "state",
     title: ownerAlive
@@ -682,9 +684,9 @@ export async function reconcileLandedWorkspace(ws: WorkspaceRecord, preview: Wor
     icon: "ti-git-merge",
     view: "orchestrators",
     metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, fromStatus: ws.status, toStatus: nextStatus, ...(ownerAlive ? { ownerAlive: true, keptLive: true } : {}), ...(sha ? { landedSha: sha } : {}), ...(landedCommitCount === 0 ? { landedCommitCount: 0 } : {}) },
-  });
+  }));
   try {
-    notifyBranchLanded({ workspace: ws, mergedSha: sha, landVerifiedSha, landedTipSha: sha, commitShas: sha ? [sha] : [], pushed: true, prLand: preview.prMerged === true, ...(landedCommitCount === 0 ? { landedCommitCount } : {}) });
+    await notifyBranchLanded({ workspace: ws, mergedSha: sha, landVerifiedSha, landedTipSha: sha, commitShas: sha ? [sha] : [], pushed: true, prLand: preview.prMerged === true, ...(landedCommitCount === 0 ? { landedCommitCount } : {}) });
   } catch {
     // Notification is best-effort; the status change + activity event still stand.
   }

package/src/bus.ts

@@ -11,7 +11,7 @@ import { announceSpawnedAgentReady, registerAgent } from "./services/register-ag
 import { authContextFromBus } from "./services/auth-context";
 import { commandAuthorizationResource, dispatchCommandAsync } from "./services/dispatch-command";
 import { withRelayEventDrain } from "./relay-event-drain";
-import { runAsCaller } from "./hub-metrics";
+import { framed, runAsCaller } from "./hub-metrics";
 import { auditProviderStateTransition } from "./services/provider-state-audit";
 import { agentProviderTimelineEvent, auditRunnerTimelineEvent } from "./provider-timeline-event";
 import { auditProviderTurnEmpty, auditProviderTurnWatchdog, auditReconciledProviderTurn } from "./services/turn-reconcile-audit";
@@ -19,6 +19,7 @@ import { ServiceAuthError } from "./services/errors";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent, shutdownInputFromBusFrame } from "./services/shutdown-agent";
 import { flushQueuedDirectMessages } from "./services/managed-running";
 import { updateCommandFromBus } from "./services/bus-command-update";
+import { heartbeatFromBus } from "./services/agent-heartbeat";
 import { isAgentUnavailable, reservedAgentIdSql } from "./db/agent-predicates";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
 import { probeWorkspaceOnTurnEnd } from "./workspace-probe";
@@ -76,7 +77,7 @@ const liveBusSocketIds = new Set<string>();
 // stalls unrelated agents.
 const busFrameQueues = new Map<string, Promise<void>>();
 
-subscribeRelayEvents((event) => broadcastRelayEvent(event));
+subscribeRelayEvents(broadcastRelayEvent);
 
 export function handleBusUpgrade(req: Request, server: Server<BusSocketData>): Response | undefined {
   if (!isOriginAllowed(req)) {
@@ -95,11 +96,11 @@ export function handleBusUpgrade(req: Request, server: Server<BusSocketData>): R
   return undefined;
 }
 
-export function busHandleOpen(ws: BusWebSocket): void {
+export const busHandleOpen = framed("WS open", (ws: BusWebSocket): void => {
   liveBusSocketIds.add(ws.data.id);
   // Registration is explicit. The socket is not visible to projections until
   // a valid register frame establishes identity and subscriptions.
-}
+});
 
 export function busHandleMessage(ws: BusWebSocket, data: string | Buffer): void {
   if (!liveBusSocketIds.has(ws.data.id)) return;
@@ -127,7 +128,7 @@ export function busHandleMessage(ws: BusWebSocket, data: string | Buffer): void
   busFrameQueues.set(ws.data.id, queued);
 }
 
-export function busHandleClose(ws: BusWebSocket): void {
+export const busHandleClose = framed("WS close", (ws: BusWebSocket): void => {
   liveBusSocketIds.delete(ws.data.id);
   busFrameQueues.delete(ws.data.id);
   const conn = busConnections.get(ws.data.id);
@@ -145,7 +146,7 @@ export function busHandleClose(ws: BusWebSocket): void {
       });
     }
   }
-}
+});
 
 export function getBusConnectionCount(): number {
   return busConnections.size;
@@ -210,7 +211,7 @@ async function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateCl
             // #416 — flush queued messages if the agent transitioned from unavailable to available.
             if (wasUnavailable) {
               const after = getAgent(conn.agentId);
-              if (after && !isAgentUnavailable(after)) flushQueuedDirectMessages(conn.agentId);
+              if (after && !isAgentUnavailable(after)) (await flushQueuedDirectMessages(conn.agentId));
             }
           }
         }
@@ -249,27 +250,27 @@ async function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateCl
         const after = applied.after;
         await auditProviderStateTransition(conn.agentId, before, after);
         const timelineEvent = agentProviderTimelineEvent(after);
-        auditRunnerTimelineEvent(conn.agentId, timelineEvent);
+        (await auditRunnerTimelineEvent(conn.agentId, timelineEvent));
         // #1621 — a turn the runner proved was cancelled out of band is a real state change the
         // waiting coordinator has to hear about, not just an activity-feed row.
-        auditReconciledProviderTurn(conn.agentId, after, timelineEvent);
+        await auditReconciledProviderTurn(conn.agentId, after, timelineEvent);
         // #1980 — the busy backstop is HOLDING a long turn it can't prove idle (not cancelling);
         // tell the waiting coordinator the turn is still live rather than leaving it to guess.
         // #2010 — but only when there's no positive busy evidence already saying so (see the
         // busy-health gate inside auditProviderTurnWatchdog); a demonstrably working agent needs
         // no wake.
-        auditProviderTurnWatchdog(conn.agentId, after, timelineEvent);
+        await auditProviderTurnWatchdog(conn.agentId, after, timelineEvent);
         // #2389 — a turn that ended clean and produced nothing is the least visible failure of the
         // three: the card reads healthy and idle. Tell the parent once the runner's own nudge has
         // failed to recover it.
-        auditProviderTurnEmpty(conn.agentId, after, timelineEvent);
+        await auditProviderTurnEmpty(conn.agentId, after, timelineEvent);
         // #2432 — a first ready that arrives over a status frame (children whose register kept the
         // row not-ready, e.g. ox/opencode builders) must stamp readiness exactly like the HTTP and
         // registration seams, or the child later reaps as a false `agent.spawn_failed`.
-        if (readyTransition) announceSpawnedAgentReady(conn.agentId, "bus-ready");
+        if (readyTransition) await announceSpawnedAgentReady(conn.agentId, "bus-ready");
         // A parked continuation consumes one retry on a genuine ready/idle transition only.
         const replayEpoch = continuationReplayEpoch(conn, before, after);
-        if (replayEpoch) replayParkedContinuationInjections(conn.agentId, replayEpoch);
+        if (replayEpoch) (await replayParkedContinuationInjections(conn.agentId, replayEpoch));
         // A real PreCompact/SessionStart hook arrives as a timelineEvent in the
         // merged meta — clears any pending stall watch (stale events ignored).
         noteAgentTimelineEvent(conn.agentId, timelineEvent);
@@ -279,7 +280,7 @@ async function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateCl
         // #633 — silent clean-exit: a runner that stays alive after its provider terminally exited
         // marks the offline edge with `terminalProviderExit`; the owning service turns that into a
         // terminal event + #636 diagnosis (and clears the hold on a genuine resume).
-        reconcileTerminalProviderExit(conn.agentId, before, after);
+        await reconcileTerminalProviderExit(conn.agentId, before, after);
       });
       return;
     case "ack":
@@ -305,8 +306,9 @@ async function handleCommandFrame(
   target: string,
   params: Record<string, unknown>,
 ): Promise<void> {
+  if (commandType === "agent.heartbeat") return withRelayEventDrain(() => heartbeatFromBus(conn, target, params)).then((o) => sendCommandResult(ws, frameId, o.status, o.result, o.error));
   if (commandType === "command.update") {
-    return withRelayEventDrain(() => updateCommandFromBus({ target, params, componentAuth: conn.componentAuth }))
+    return withRelayEventDrain(async () => (await updateCommandFromBus({ target, params, componentAuth: conn.componentAuth })))
       .then((result) => sendCommandResult(ws, frameId, result.status, result.result, result.error))
       .catch((error) => sendError(ws, frameId, "FRAME_FAILED", errMessage(error)));
   }
@@ -333,10 +335,10 @@ async function handleCommandFrame(
   // busCommandAuthorized gate), createCommand, and the "command.requested" emit. The bus
   // adapter only translates the typed ServiceAuthError into a rejected result frame.
   try {
-    const command = await withRelayEventDrain(() => dispatchCommandAsync(
+    const command = await withRelayEventDrain(async () => (await dispatchCommandAsync(
       { type: commandType, source: conn.agentId ?? conn.componentId, target, params },
       authContextFromBus(conn.componentAuth),
-    ));
+    )));
     sendCommandResult(ws, frameId, "succeeded", { command });
   } catch (e) {
     if (e instanceof ServiceAuthError) {
@@ -385,7 +387,7 @@ async function handleRegister(ws: BusWebSocket, frame: RegisterFrame): Promise<v
       ...(lifecycle === "transient" || lifecycle === "persistent" ? { lifecycle } : {}),
       meta: payload.meta,
     };
-    const agent = registerAgent(input, authContextFromBus(ws.data.componentAuth), { emitStatus: false });
+    const agent = await registerAgent(input, authContextFromBus(ws.data.componentAuth), { emitStatus: false });
     epoch = agent.epoch;
   }
 
@@ -429,7 +431,7 @@ async function handleRegister(ws: BusWebSocket, frame: RegisterFrame): Promise<v
       epoch,
       cursor: getOutboxCursor(),
       sessionId: ws.data.id,
-      features: { heartbeatAck: true },
+      features: { heartbeatAck: true, liveness: true },
     },
   });
 }