@humwick/server 0.130.2 → 0.130.3

package/src/events.ts

@@ -19,7 +19,7 @@ export interface RelayEvent {
 
 type Listener = (event: RelayEvent) => void;
 
-const listeners = new Set<Listener>();
+const listeners = new Map<Listener, string>();
 const fanoutQueue: Array<{ event: RelayEvent; lastSeq: number }> = [];
 let notifying = false;
 
@@ -33,12 +33,13 @@ export function emitRelayEvent(input: Omit<RelayEvent, "seq" | "timestamp">): Pr
       const appended = appendRelayEventInternal(input.type, input.source, input.data, input.subject, timestamp)!;
       return Promise.resolve(fanOutAppendedEvent(input, appended, timestamp));
     }
-    return emitRelayEventAsync(structuredClone(input), { idempotencyKey: crypto.randomUUID() });
+    // #3614 — keyless: nothing resubmits this append, so a ledger row would only cost writes.
+    return trackRelayEvent(appendAndFanOut(structuredClone(input), {}), input.type);
   });
 }
 
 /** #3606 — fan out to the current listeners only: no bus_outbox row, no idempotency-ledger row, no
- * replay. For state the next tick supersedes anyway (dashboard viewer presence). */
+ * replay. For state the next tick supersedes anyway (dashboard viewer presence, agent liveness ticks). */
 export function emitEphemeralRelayEvent(input: Omit<RelayEvent, "seq" | "timestamp" | "ephemeral">): RelayEvent {
   return fanOutAppendedEvent({ ...input, ephemeral: true }, { seq: 0, lastSeq: 0 }, Date.now());
 }
@@ -71,7 +72,8 @@ async function appendAndFanOut(
   } catch (error) {
     // H5: a lost acknowledgement says nothing about commit. Re-submit the exact logical append
     // with the same durable key; the writer returns the first result without a second insert.
-    if (!(error instanceof WriteIndeterminateError)) throw error;
+    // A keyless emit is at-most-once: it surfaces the error, and a committed row stays replayable.
+    if (!(error instanceof WriteIndeterminateError) || !options.idempotencyKey) throw error;
     appended = await getGateway().write("bus.append", args, { critical: true, idempotencyKey: options.idempotencyKey }) as unknown as typeof appended;
   }
   // A retry ledger result proves durable storage, not that this process owns a fresh live edge.
@@ -122,19 +124,19 @@ export function fanOutAppendedEvent(
 
 function notify(event: RelayEvent): void {
   measureEmit(event.type, true, () => {
-    for (const listener of listeners) {
+    for (const [listener, name] of listeners) {
       try {
         listener(event);
       } catch (error) {
         // Event projections are isolated so one transport cannot block another; a failed one (e.g. a
         // BUSY write in a projection, #3643) is logged, not swallowed.
-        console.warn(`[events] ${event.type} listener failed: ${errMessage(error)}`);
+        console.warn(`[events] ${event.type} listener ${name} failed: ${errMessage(error)}`, error instanceof Error ? error.stack : error);
       }
     }
   });
 }
 
-export function subscribeRelayEvents(listener: Listener): () => void {
-  listeners.add(listener);
+export function subscribeRelayEvents(listener: Listener, name = listener.name || "<anonymous>"): () => void {
+  listeners.set(listener, name);
   return () => listeners.delete(listener);
 }

package/src/host-provider-store.ts

@@ -1,8 +1,9 @@
+import { setConfigAsync } from "./config-store-write";
 // #2855 — DB-backed readers for per-host provider enablement. Separate from
 // host-provider-enablement.ts (a config-store-imported leaf) so this module can
 // import getConfig/listConfig without closing a cycle.
 import { errMessage, type SpawnProvider } from "@humwick/sdk";
-import { getConfig, listConfig, setConfig } from "./config-store";
+import { getConfig, listConfig } from "./config-store";
 import { listOrchestratorIds } from "./db";
 import {
   HOST_PROVIDER_ENABLEMENT_NAMESPACE,
@@ -75,11 +76,11 @@ export function hostProviderRefusal(hostId: string, provider: SpawnProvider): st
 /** One-time env migration: missing/unmarked rows merge omitted disables
  * without touching operator entries. In-env opt-ins store explicit true;
  * everything else outside env seeds as disabled. */
-export function seedHostProvidersFromEnv(
+export async function seedHostProvidersFromEnv(
   hostId: string,
   envProviders: readonly string[],
   switchableCatalog: readonly SpawnProvider[],
-): HostProviderEnablementSetting | null {
+): Promise<HostProviderEnablementSetting | null> {
   const existing = getHostProviderSetting(hostId);
   if (existing?.seeded) return null;
   const env = new Set(envProviders);
@@ -98,5 +99,5 @@ export function seedHostProvidersFromEnv(
       providers[provider] = { enabled: false, reason: "migrated from host env list" };
     }
   }
-  return setConfig(HOST_PROVIDER_ENABLEMENT_NAMESPACE, hostId, { providers, seeded: true }, "migration-seed").value;
+  return (await setConfigAsync(HOST_PROVIDER_ENABLEMENT_NAMESPACE, hostId, { providers, seeded: true }, "migration-seed")).value;
 }

package/src/hub-metrics-report.ts

@@ -20,6 +20,7 @@ export function hubMetricsReport(now = Date.now()) {
   const emits = emitTable.snapshot(now);
   const readerOps = readerOpTable.snapshot(now);
   const cpuMs = callers.reduce((total, row) => total + row.cpuMs, 0);
+  const backgroundCpuMs = callers.find((row) => row.key === BACKGROUND_KEY)?.cpuMs ?? 0;
   const calls = callers.reduce((total, row) => total + row.count, 0);
   return {
     generatedAt: now,
@@ -28,7 +29,9 @@ export function hubMetricsReport(now = Date.now()) {
     mainThread: {
       cpuMs: Math.round(cpuMs),
       cpuPct: Math.round((cpuMs / windowMs) * 10_000) / 100,
-      backgroundCpuMs: Math.round(callers.find((row) => row.key === BACKGROUND_KEY)?.cpuMs ?? 0),
+      backgroundCpuMs: Math.round(backgroundCpuMs),
+      // #3798 — the share of main-thread CPU a named frame (route, bus frame, timer, job) accounts for.
+      namedCpuPct: cpuMs > 0 ? Math.round(((cpuMs - backgroundCpuMs) / cpuMs) * 10_000) / 100 : 100,
     },
     callers: {
       count: calls,
@@ -62,6 +65,7 @@ export function hubLoadCheck(now = Date.now()): HealthCheck {
       busConnections: report.connections.bus,
       callsPerSec: report.callers.perSec,
       mainThreadCpuPct: report.mainThread.cpuPct,
+      mainThreadNamedCpuPct: report.mainThread.namedCpuPct,
     },
   };
 }

package/src/hub-metrics.ts

@@ -4,7 +4,7 @@
 // so caller CPU is split at marks (caller start/end, reader resumes): the CPU between two marks goes
 // to the caller that ran. docs/operations.md "Hub load metrics" describes the model and its limits.
 
-import { runWithLoopCallsite } from "./loop-block-attribution";
+import { resolveLoopCallsite, runWithLoopCallsite, type LoopCallsiteContext } from "./loop-block-attribution";
 
 const BUCKET_MS = 10_000;
 const BUCKETS = 6;
@@ -109,25 +109,45 @@ export function markCallerResume(owner: string | undefined): void {
   ledgerOwner = owner;
 }
 
-/** Run `run` as caller `key`: one request or frame, its wall time and its main-thread CPU segments. */
-export async function trackCaller<T>(key: string, run: () => T | Promise<T>): Promise<T> {
-  const startedAt = performance.now();
-  markCallerResume(key);
-  try {
-    return await run();
-  } finally {
-    // The code finishing the caller is the caller itself, so the segment since the last mark is its own.
-    const now = Date.now();
-    settleCpu(key, now);
-    ledgerOwner = undefined;
-    callerTable.add(key, now, 1, performance.now() - startedAt);
-  }
+/** #3798 — run `run` as named frame `ctx.callsite` (request, bus frame, timer tick, job): its count, wall
+ *  time and main-thread CPU. Opens the loop callsite scope, so reader and writer results inside it are
+ *  charged back to it. Returns what `run` returns (a sync body stays sync); on exit the ledger goes back
+ *  to the enclosing frame (a job inside the scheduler tick). */
+export function runInFrame<T>(ctx: LoopCallsiteContext & { callsite: string }, run: () => T): T {
+  const outer = resolveLoopCallsite();
+  return runWithLoopCallsite(ctx, () => {
+    const key = ctx.callsite;
+    const startedAt = performance.now();
+    markCallerResume(key);
+    const end = () => {
+      // The code finishing the frame is the frame itself, so the segment since the last mark is its own.
+      const now = Date.now();
+      settleCpu(key, now);
+      ledgerOwner = outer;
+      callerTable.add(key, now, 1, performance.now() - startedAt);
+    };
+    let result: T;
+    try {
+      result = run();
+    } catch (error) {
+      end();
+      throw error;
+    }
+    if (result instanceof Promise) return result.finally(end) as T;
+    end();
+    return result;
+  });
+}
+
+/** `runInFrame` as a callback, for a timer or interval body: `setInterval(framed("timer x", tick), ms)`. */
+export function framed<A extends unknown[], T>(key: string, fn: (...args: A) => T): (...args: A) => T {
+  const ctx = { callsite: key };
+  return (...args: A) => runInFrame(ctx, () => fn(...args));
 }
 
-/** `trackCaller` for a caller with no request scope of its own (a bus frame): also opens the loop
- *  callsite scope, so reader resumes and on-loop frames inside it are attributed to it. */
-export function runAsCaller<T>(callsite: string, run: () => T | Promise<T>): Promise<T> {
-  return runWithLoopCallsite({ callsite }, () => trackCaller(callsite, run));
+/** A bus frame: always a promise, so a sync throw reaches the frame queue's `catch`. */
+export async function runAsCaller<T>(callsite: string, run: () => T | Promise<T>): Promise<T> {
+  return runInFrame({ callsite }, run);
 }
 
 // ── Emits ─────────────────────────────────────────────────────────────────────────────────────────

package/src/injection-sweep-pacing.ts

@@ -2,23 +2,21 @@
 // one boundary per macrotask (`forEachPaced`); a backlog (a long pause, a crash that lost many settles)
 // is drained in runs of this budget, well inside the 30s job deadline, re-run this soon while a run
 // reports `moreWork`.
-import { isSqliteBusyError, withFastFailConnection, writerLockAvailable } from "./db/connection";
+import { isSqliteBusyError } from "./db/connection";
 import { forEachPaced } from "./event-loop-yield";
 
 export const INJECTION_SWEEP_RUN_BUDGET_MS = 10_000;
 export const INJECTION_SWEEP_BACKLOG_INTERVAL_MS = 5_000;
-const SWEEP_BUSY_TIMEOUT_MS = 40;
 
-/** Each unit runs on the fast-fail connection, so a write under another writer's lock fails in 40ms
- *  instead of the shared connection's ~1s; the run then stops with `moreWork` and retries soon. */
-export async function pacedInjectionSweep<T>(items: () => Iterable<T>, unit: (item: T) => void, signal?: AbortSignal): Promise<{ moreWork: boolean }> {
+/** The gateway owns write contention; wait for each unit before continuing the bounded sweep. */
+export async function pacedInjectionSweep<T>(items: () => Iterable<T>, unit: (item: T) => unknown, signal?: AbortSignal): Promise<{ moreWork: boolean }> {
   let contended = false;
-  return forEachPaced(items, (item) => {
+  return forEachPaced(items, async (item) => {
     try {
-      withFastFailConnection(SWEEP_BUSY_TIMEOUT_MS, () => unit(item));
+      await unit(item);
     } catch (error) {
       if (!isSqliteBusyError(error)) throw error;
       contended = true;
     }
-  }, { signal, budgetMs: INJECTION_SWEEP_RUN_BUDGET_MS, ready: () => !contended && writerLockAvailable(SWEEP_BUSY_TIMEOUT_MS) });
+  }, { signal, budgetMs: INJECTION_SWEEP_RUN_BUDGET_MS, ready: () => !contended });
 }

package/src/land-gate-notifications.ts

@@ -1,7 +1,8 @@
+import { createActivityEventAsync } from "./db/activity-async";
 import type { LandGateRunResult, WorkspaceRecord } from "@humwick/sdk";
 import { emitRelayEvent } from "./events";
 import { routeNotification, INFORMATIONAL_TTL_MS } from "./notification-router";
-import { createActivityEvent } from "./db";
+
 import { resolveCoordinatorAgentId } from "./steward-identity";
 import { stewardFallbackTarget } from "./config";
 import { routeLandGateFailure } from "./land-gate-failure-routing";
@@ -51,7 +52,7 @@ export async function notifyLandGateFailed(input: {
 
   emitRelayEvent({ type: "workspace.land_gate_failed", source: "server", subject: workspace.id, data: payload });
 
-  createActivityEvent({
+  (await createActivityEventAsync({
     clientId: `workspace-land-gate-failed-${workspace.id}-${Date.now()}`,
     kind: "state",
     title: "Land blocked by gate failure",
@@ -60,11 +61,11 @@ export async function notifyLandGateFailed(input: {
     icon: "ti-alert-octagon",
     view: "orchestrators",
     metadata: { source: "server", maintenanceJobId: "workspace-land-gate", workspaceId: workspace.id, repoRoot: workspace.repoRoot, gateName: gate.name, ...(input.artifactId ? { artifactId: input.artifactId } : {}) },
-  });
+  }));
 
   const routing = await routeLandGateFailure({ workspaceId: workspace.id, branch: workspace.branch, failedAt: input.failedAt, owner, coordinator, fallback, gateName: gate.name });
   if (routing.stale) return;
-  routeNotification({
+  await routeNotification({
     type: "workspace.land_gate_failed",
     scope: { author: owner, parent: routing.parent, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
     recipients: routing.recipients,
@@ -80,14 +81,14 @@ export async function notifyLandGateFailed(input: {
 }
 
 /** #902 — gate failures wake both owner and coordinator durably; full logs stay in artifacts. */
-export function notifyLandGateWarnings(input: {
+export async function notifyLandGateWarnings(input: {
   workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
   warnings: LandGateRunResult[];
   /** #2474 R3 — false when any warning's wire output is a folded tail: the combined artifact is
    *  then an index (tails + per-gate full-log refs), not full output, and the label must not
    *  claim otherwise. Defaults to true (nothing folded). */
   artifactId?: string; fullOutput?: boolean;
-}): void {
+}): Promise<void> {
   const { workspace, warnings } = input;
   if (warnings.length === 0) return;
   const base = workspace.baseRef ?? "base";
@@ -110,7 +111,7 @@ export function notifyLandGateWarnings(input: {
   emitRelayEvent({ type: "workspace.land_gate_warning", source: "server", subject: workspace.id, data: payload });
 
   if (!owner) return;
-  routeNotification({
+  await routeNotification({
     type: "workspace.land_gate_warning",
     scope: { author: owner, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
     recipients: [owner],
@@ -124,13 +125,13 @@ export function notifyLandGateWarnings(input: {
   });
 }
 
-export function notifyLandGateSkipped(input: {
+export async function notifyLandGateSkipped(input: {
   workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
   level: "subset" | "none";
   reason: string;
   by: string;
   commit?: string;
-}): void {
+}): Promise<void> {
   const { workspace } = input;
   const base = workspace.baseRef ?? "base";
   const owner = workspace.ownerAgentId;
@@ -157,7 +158,7 @@ export function notifyLandGateSkipped(input: {
 
   const recipients = [...new Set([owner, coordinator ?? fallback].filter((r): r is string => Boolean(r)))];
   if (!recipients.length) return;
-  routeNotification({
+  await routeNotification({
     type: "workspace.land_gate_skipped",
     scope: { author: owner, parent: coordinator ?? undefined, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
     recipients,

package/src/land-gate-queue-progress.ts

@@ -6,14 +6,14 @@ import { stewardFallbackTarget } from "./config";
 import type { Command, WorkspaceRecord } from "./types";
 
 /** An offline host is uncertain, never positive evidence to release its lane (#2777). */
-export function alertUnprovenLandLaneHolder(command: Command): void {
+export async function alertUnprovenLandLaneHolder(command: Command): Promise<void> {
   const workspaceId = command.correlationId ?? command.params.workspaceId;
   const workspace = typeof workspaceId === "string" ? getWorkspace(workspaceId) : null;
   if (!workspace) return;
   const coordinator = resolveCoordinatorAgentId(workspace.ownerAgentId);
   const target = coordinator ?? stewardFallbackTarget() ?? workspace.ownerAgentId;
   if (!target) return;
-  routeNotification({
+  await routeNotification({
     type: "workspace.land_gate_queue_stalled",
     scope: { author: workspace.ownerAgentId, parent: coordinator ?? undefined, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
     recipients: [target], forceDelivery: true, ttlMs: null,
@@ -39,7 +39,7 @@ export async function recordLandGateQueueProgress(workspace: WorkspaceRecord, co
   const coordinator = resolveCoordinatorAgentId(workspace.ownerAgentId);
   const target = coordinator ?? stewardFallbackTarget() ?? workspace.ownerAgentId;
   if (!target) return;
-  routeNotification({
+  await routeNotification({
     type: "workspace.land_gate_queue_stalled",
     scope: { author: workspace.ownerAgentId, parent: coordinator ?? undefined, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
     recipients: [target], forceDelivery: true, ttlMs: null,

package/src/land-settle-dispatch.ts

@@ -1,56 +1,7 @@
 import { errMessage } from "@humwick/sdk";
+import { trackRelayEvent } from "./relay-event-drain";
 
-/**
- * #1790 — the land settle path (`settleWorkspaceMergeCommand`) fires 6–12 serialized SYNCHRONOUS
- * DB writes per land: the `branch.landed` + `landed-success` events, the per-recipient notification
- * fan-out (each a `sendMessage` + an activity-event audit, over an all-agents audience scan), the
- * issue/Task lifecycle drives, and — on the reviewer path — an eager policy spawn dispatch. NONE use
- * the async busy-retry wrapper, so each raw write can block the event-loop thread up to `busy_timeout`
- * (1s, `db/connection.ts`) under lock contention. A land BURST piles this onto the contended loop and
- * amplifies the ~2.4s event-loop lag that made the relay HTTP server miss a concurrent `spawn` (the
- * "socket connection closed" failures in #1790).
- *
- * None of that work belongs on the synchronous settle critical path. The AUTHORITATIVE land STATE —
- * the workspace status transition (ancestry-gated, #1713) and the landed-sha stamp — plus the durable
- * landing RECEIPT (`recordLandingReceipt`, one indexed INSERT) are written synchronously and ARE the
- * source of truth; the events, notifications, lifecycle drives and reviewer spawn are ANNOUNCEMENTS
- * derived from that state.
- *
- * ## Serialized, one-item-per-tick drain (#1790 review F2)
- * Deferring N announcements as N `setImmediate` callbacks does NOT relieve a burst: Node/Bun drain a
- * whole `setImmediate` batch as one contiguous group within a single check phase, BEFORE the poll
- * phase accepts the next connection — so an N×fan-out block still refuses a `spawn` arriving during
- * it. Instead this runs a SERIALIZED queue: each drain executes exactly ONE item and, only if the
- * queue is still non-empty, re-schedules itself. That guarantees a full event-loop iteration — poll
- * phase included, so incoming connections are accepted — between every two fan-outs.
- *
- * ## Shutdown drain (#1790 review F1)
- * A graceful stop is a SIGTERM/SIGINT (CD deploys are graceful SIGTERMs, often triggered BY a land —
- * a bad correlation). {@link drainPendingLandSettleSideEffects} runs every still-queued callback
- * synchronously; the process shutdown handler (a SINGLE `once` per signal in `db/agents.ts`) calls it
- * before re-raising, so an announcement already QUEUED by the time the signal is handled is never
- * dropped. Accepted residual: a HARD crash (SIGKILL / power loss) still loses any un-flushed deferred
- * announcement, but the durable landing RECEIPT is written synchronously right after the settle's own
- * `await` resolves (`recordLandingReceipt`, before `markWorkspaceLanded`), so a land whose settle has
- * fully RUN is never left unrecorded on a clean stop — only its wake/lifecycle drive would need a
- * re-poll to recover.
- *
- * #1830 (async land-settle git probes) narrowed this guarantee: `settleWorkspaceMergeCommand` now
- * awaits a bounded (up to ~12s worst case) async git ancestry check BEFORE it writes the land state,
- * the receipt, or queues any announcement here. A graceful stop that lands mid-await — the event loop
- * is genuinely free during that await, unlike the old fully-synchronous settle a signal handler could
- * never interrupt mid-function — sees NOTHING queued for this land yet, so `drainPendingLandSettleSideEffects`
- * flushes nothing for it and the settle can be lost in its entirety (state + receipt + announcement),
- * not just its announcement. The land is not silently mis-recorded (no state was written either), but
- * it is a real durability gap this module cannot close on its own — a full fix needs the settle path
- * itself to survive/resume across a restart (a fast re-settle on startup, or a bounded shutdown drain
- * that waits out in-flight settles). Tracked as #1831; out of scope here.
- *
- * Errors are isolated: a deferred announcement runs AFTER the land it announces has already settled,
- * so a throw here can never unwind or mask the land. This is a deliberate swallow-and-log (the inline
- * callers propagated most of these throws to the settle caller; moving them off-thread means there is
- * no caller left to catch them, so isolation is a behavior improvement, not parity).
- */
+// #1790/#1870 — serialize post-commit announcements, yielding between items and awaiting them at shutdown.
 type LandSettleScheduler = (run: () => void) => void;
 
 const defaultScheduler: LandSettleScheduler = (run) => {
@@ -61,7 +12,8 @@ let scheduler: LandSettleScheduler = defaultScheduler;
 
 interface PendingSideEffect {
   label: string;
-  fn: () => void;
+  fn: () => unknown;
+  complete: () => void;
 }
 
 // One global FIFO queue drained one item per scheduler tick (F2). `scheduled` guards against
@@ -69,25 +21,36 @@ interface PendingSideEffect {
 const queue: PendingSideEffect[] = [];
 let scheduled = false;
 
-function runOne(item: PendingSideEffect): void {
-  try {
-    item.fn();
-  } catch (error) {
-    console.warn(`[land-settle] deferred ${item.label} threw (land already settled; announcement only): ${errMessage(error)}`);
-  }
+let active: Promise<void> | undefined;
+let shutdownDrain: Promise<void> | undefined;
+let executing = false;
+let draining = false;
+
+async function runOne(item: PendingSideEffect): Promise<void> {
+  try { await item.fn(); }
+  catch (error) { console.warn(`[land-settle] deferred ${item.label} threw (land already settled; announcement only): ${errMessage(error)}`); }
+  finally { item.complete(); }
+}
+
+function scheduleNext(): void {
+  if (!queue.length || scheduled || executing || draining) return;
+  scheduled = true;
+  scheduler(drainOne);
 }
 
 function drainOne(): void {
   scheduled = false;
+  if (executing || draining) return;
   const item = queue.shift();
-  if (item) runOne(item);
-  // Re-schedule for the NEXT item only — one item per loop iteration, so the poll phase runs (and a
-  // pending spawn connection is accepted) between fan-outs. A continuously-fed queue still terminates
-  // each drain in O(1); it just keeps re-arming while work remains.
-  if (queue.length > 0 && !scheduled) {
-    scheduled = true;
-    scheduler(drainOne);
-  }
+  if (!item) return;
+  executing = true;
+  const running = runOne(item);
+  active = running;
+  void running.finally(() => {
+    if (active === running) active = undefined;
+    executing = false;
+    scheduleNext();
+  }).catch(error => console.warn(`[land-settle] drain failed: ${errMessage(error)}`));
 }
 
 /**
@@ -96,39 +59,36 @@ function drainOne(): void {
  * path and DOES run once flushed. Pass `undefined` to restore the `setImmediate` default. Also drains
  * any queued work so state never leaks across tests.
  */
-export function __setLandSettleSchedulerForTests(fn: LandSettleScheduler | undefined): void {
-  drainPendingLandSettleSideEffects();
+export async function __setLandSettleSchedulerForTests(fn: LandSettleScheduler | undefined): Promise<void> {
+  await drainPendingLandSettleSideEffects();
   scheduler = fn ?? defaultScheduler;
 }
 
 /** Schedule a land-settle announcement/side-effect off the synchronous settle critical path (#1790). */
-export function deferLandSettleSideEffect(label: string, fn: () => void): void {
-  queue.push({ label, fn });
-  if (!scheduled) {
-    scheduled = true;
-    scheduler(drainOne);
-  }
+export function deferLandSettleSideEffect(label: string, fn: () => unknown): void {
+  let complete!: () => void;
+  const pending = new Promise<void>(resolve => { complete = resolve; });
+  trackRelayEvent(pending, `land-settle.${label}`);
+  queue.push({ label, fn, complete });
+  scheduleNext();
 }
 
-/**
- * #1790 review F1 — run every still-queued side-effect synchronously, for the graceful-shutdown
- * (SIGTERM/SIGINT) drain so a deferred landing announcement is never dropped on a clean stop.
- * Re-entrant-safe: an announcement that itself defers more work is picked up by the same loop (the
- * loop re-reads `queue.length`), and each item's throw is swallowed so one bad announcement can never
- * block shutdown. A pathologically self-feeding queue is bounded by MAX_SHUTDOWN_DRAIN so shutdown
- * always terminates.
- */
 const MAX_SHUTDOWN_DRAIN = 100_000;
-export function drainPendingLandSettleSideEffects(): void {
+export function drainPendingLandSettleSideEffects(): Promise<void> {
+  if (shutdownDrain) return shutdownDrain;
   scheduled = false;
-  let drained = 0;
-  while (queue.length > 0) {
-    const item = queue.shift()!;
-    runOne(item);
-    if (++drained >= MAX_SHUTDOWN_DRAIN) {
-      console.warn(`[land-settle] shutdown drain hit ${MAX_SHUTDOWN_DRAIN} items; abandoning ${queue.length} still-queued side-effect(s)`);
-      queue.length = 0;
-      break;
+  draining = true;
+  shutdownDrain = (async () => {
+    if (active) await active;
+    let drained = 0;
+    while (queue.length) {
+      await runOne(queue.shift()!);
+      if (++drained >= MAX_SHUTDOWN_DRAIN) {
+        console.warn(`[land-settle] shutdown drain hit ${MAX_SHUTDOWN_DRAIN} items; abandoning ${queue.length} still-queued side-effect(s)`);
+        for (const item of queue.splice(0)) item.complete();
+        break;
+      }
     }
-  }
+  })().finally(() => { shutdownDrain = undefined; draining = false; scheduleNext(); });
+  return shutdownDrain;
 }

package/src/lifecycle-context-pressure.ts

@@ -1,5 +1,6 @@
+import { createCommandAsync } from "./commands-write";
 import { errMessage } from "@humwick/sdk";
-import { createCommand, listCommands } from "./commands-db";
+import { listCommands } from "./commands-db";
 import { getAgent, listAgents } from "./db";
 import { getManagedAgentState } from "./config-store";
 import { emitCommandEvent } from "./command-events";
@@ -22,7 +23,7 @@ interface CompactAgentInput {
   hasActiveCommand: (target: string, type: string) => boolean;
 }
 
-export function reconcileLifecycleContextPressure(input: LifecycleContextPressureInput): Set<string> {
+export async function reconcileLifecycleContextPressure(input: LifecycleContextPressureInput): Promise<Set<string>> {
   const byPolicy = new Map(input.policies.map((policy) => [policy.name, policy]));
   const candidates = new Map<string, { agent: AgentCard; policy?: SpawnPolicy }>();
 
@@ -42,26 +43,26 @@ export function reconcileLifecycleContextPressure(input: LifecycleContextPressur
 
   const handled = new Set<string>();
   for (const { agent, policy } of candidates.values()) {
-    if (handleContextPressure({
+    if ((await handleContextPressure({
       agent,
       now: input.now,
       hasActiveCommand: input.hasActiveCommand,
-      compact: (reason) => requestAgentCompact({
+      compact: async (reason) => (await requestAgentCompact({
         agent,
         reason,
         policyName: policy?.name,
         alwaysReload: alwaysReloadTags(agent.tags),
         now: input.now,
         hasActiveCommand: input.hasActiveCommand,
-      }),
-    })) {
+      })),
+    }))) {
       handled.add(agent.id);
     }
   }
   return handled;
 }
 
-export function requestAgentCompact(input: CompactAgentInput): Command | null {
+export async function requestAgentCompact(input: CompactAgentInput): Promise<Command | null> {
   // #2004 — dedup BEFORE building the resume plan (which persists a recovery message): a compaction
   // may already be in flight as EITHER an agent.compact (native providers) or an agent.clearContext
   // (clear-inject providers), so guard against both shapes rather than only the legacy agent.compact.
@@ -81,7 +82,7 @@ export function requestAgentCompact(input: CompactAgentInput): Command | null {
   // whose identity/startup hooks still reinject the charter — never a clear, never nothing.
   let resume: ForcedResumePlan | null = null;
   try {
-    resume = buildForcedResumePlan(input.agent.id, now);
+    resume = (await buildForcedResumePlan(input.agent.id, now));
   } catch (error) {
     console.warn(`[lifecycle] forced resume plan for '${input.agent.id}' failed; degrading to a bare compact: ${errMessage(error)}`);
     resume = null;
@@ -90,7 +91,7 @@ export function requestAgentCompact(input: CompactAgentInput): Command | null {
   const spawnRequestId = typeof input.agent.meta?.spawnRequestId === "string" ? input.agent.meta.spawnRequestId : undefined;
   const sessionName = typeof input.agent.meta?.sessionName === "string" ? input.agent.meta.sessionName : undefined;
   const tmuxSession = typeof input.agent.meta?.tmuxSession === "string" ? input.agent.meta.tmuxSession : undefined;
-  const command = createCommand({
+  const command = (await createCommandAsync({
     type: commandType,
     source: "system",
     target: input.agent.id,
@@ -108,7 +109,7 @@ export function requestAgentCompact(input: CompactAgentInput): Command | null {
       requestedAt: now,
       ...(resume?.params ?? {}),
     },
-  });
+  }));
   emitCommandEvent(command, "command.requested");
   return command;
 }