@humwick/server 0.130.2 → 0.130.3

package/src/cd-deploy-notify.ts

@@ -41,7 +41,7 @@ export async function notifyCdDeployLive(input: CdDeployLiveInput = {}): Promise
   const version = input.version ?? VERSION;
   const gitSha = input.gitSha ?? reportedGitSha();
   if (!gitSha) {
-    routeNotification({ type: "cd.deploy_live", scope: {}, recipients: [], message: {
+    await routeNotification({ type: "cd.deploy_live", scope: {}, recipients: [], message: {
       body: `Humwick v${version} is now running.`, payload: { kind: "cd.deploy-live", version },
       idempotencyKey: `release-deploy-live:${version}`, replyExpected: false,
     } });
@@ -50,7 +50,7 @@ export async function notifyCdDeployLive(input: CdDeployLiveInput = {}): Promise
   const shortSha = gitSha.slice(0, 12);
   const contents = await deployNoticeContents(gitSha, input.repoRoot ?? resolve(import.meta.dir, ".."));
 
-  routeNotification({
+  await routeNotification({
     type: "cd.deploy_live",
     scope: {},
     ttlMs: null,

package/src/ci/notifications.ts

@@ -120,13 +120,13 @@ export interface RouteCiIncidentNotificationResult {
  * through routeNotification so its TTL, idempotency, routing explanation, and
  * Activity audit behavior stay identical to every other Relay notification.
  */
-export function routeCiIncidentNotification(input: RouteCiIncidentNotificationInput): RouteCiIncidentNotificationResult {
+export async function routeCiIncidentNotification(input: RouteCiIncidentNotificationInput): Promise<RouteCiIncidentNotificationResult> {
   const { payload } = input;
   const subject = input.subject ?? defaultSubject(input.type, payload.repository, payload.branch);
   const body = input.body ?? defaultBody(input);
   const recipients = input.recipients ?? [payload.coordinatorAgentId];
   const idempotencyKey = input.idempotencyKey ?? defaultIdempotencyKey(input);
-  const messages = routeNotification({
+  const messages = await routeNotification({
     type: input.type,
     scope: {
       repoRoot: payload.repoRoot ?? payload.repository,
@@ -148,14 +148,14 @@ export function routeCiIncidentNotification(input: RouteCiIncidentNotificationIn
   });
 
   if (!input.alertHuman) return { messages };
-  const humanFallback = notifyWorkspaceHumanEscalation({
+  const humanFallback = (await notifyWorkspaceHumanEscalation({
     subject,
     body,
     payload: { kind: input.type, ...payload },
     priority: humanAlertPriority(input.type),
     tags: ["agent-relay", "ci", humanAlertTag(input.type)],
     source: "ci-incident",
-  });
+  }));
   return { messages, humanFallback };
 }
 

package/src/ci/root-missing.ts

@@ -11,11 +11,11 @@ export interface CiRootMissing {
 
 type Deps = Pick<CiTransitionNotifyDeps, "resolveCoordinator" | "route" | "now">;
 
-function notify(input: CiRootMissing, deps: Deps, fired: boolean): boolean {
+async function notify(input: CiRootMissing, deps: Deps, fired: boolean): Promise<boolean> {
   if (!fired) return false;
   const route = deps.route ?? routeCiIncidentNotification;
   const observedAt = deps.now ?? Date.now();
-  route({
+  await route({
     type: "ci.root_missing",
     payload: { provider: "github-actions", repository: input.repository, repoRoot: input.rootPath, branch: "*", coordinatorAgentId: resolveCoordinator(deps), observedAt },
     alertHuman: true,
@@ -26,5 +26,5 @@ function notify(input: CiRootMissing, deps: Deps, fired: boolean): boolean {
 }
 
 export async function notifyCiRootMissing(input: CiRootMissing, deps: Deps = {}): Promise<boolean> {
-  return notify(input, deps, await markCiRootMissingNotifiedAsync(input.repository, deps.now));
+  return await notify(input, deps, await markCiRootMissingNotifiedAsync(input.repository, deps.now));
 }

package/src/ci/transition-notify.ts

@@ -42,7 +42,7 @@ export const CI_MAIN_WATCH_COORDINATOR = "cd-watcher";
 
 export interface CiTransitionNotifyDeps {
   ingest?: (observation: CiObservation, now?: number) => CiIncidentIngestResult | Promise<CiIncidentIngestResult>;
-  route?: (input: Parameters<typeof routeCiIncidentNotification>[0]) => RouteCiIncidentNotificationResult;
+  route?: (input: Parameters<typeof routeCiIncidentNotification>[0]) => RouteCiIncidentNotificationResult | Promise<RouteCiIncidentNotificationResult>;
   /** Resolve the coordinator/owner agent the relay message addresses. Defaults to the configured
    * steward fallback, then the system watch actor. */
   resolveCoordinator?: () => string | undefined;
@@ -93,7 +93,7 @@ export async function notifyCiTransition(
       failingRunIds: observation.failingRuns.map((run) => run.id),
       failingJobNames: failingJobNames(observation),
     };
-    const routed = route({
+    const routed = await route({
       type: "ci.failed",
       payload,
       alertHuman: true,
@@ -117,7 +117,7 @@ export async function notifyCiTransition(
       greenHeadSha: observation.headSha,
       ...(result.incident.resolution ? { resolution: result.incident.resolution } : {}),
     };
-    const routed = route({
+    const routed = await route({
       type: "ci.recovered",
       payload,
       alertHuman: true,
@@ -138,7 +138,7 @@ export async function notifyCiTransition(
       firstSeenAt: result.firstSeenAt,
       observedAt: observation.observedAt,
     };
-    const routed = route({
+    const routed = await route({
       type: "ci.never_matched",
       payload,
       alertHuman: true,
@@ -149,7 +149,7 @@ export async function notifyCiTransition(
   }
 
   if (result.kind === "config_mismatch") {
-    const routed = route(configMismatchRoute(observation, resolveCoordinator(deps), result.unmatchedJobs));
+    const routed = await route(configMismatchRoute(observation, resolveCoordinator(deps), result.unmatchedJobs));
     return { transition: "config_mismatch", notified: true, messages: routed.messages.length, ...(routed.humanFallback ? { humanFallback: routed.humanFallback } : {}) };
   }
 

package/src/claude-app/oauth-http.ts

@@ -68,12 +68,12 @@ async function getRuntime(): Promise<Runtime> {
       removeShutdownHook = onShutdown("claude-app-oauth", stopClaudeAppOAuth);
       outcome = { status: "ok", detail: "OAuth available" };
       return { provider, server, base: `http://127.0.0.1:${address.port}` };
-    })().catch(error => withRelayEventDrain(() => {
+    })().catch(error => withRelayEventDrain(async () => {
       runtime = undefined;
       const detail = `OAuth unavailable: ${errMessage(error)}`;
       outcome = { status: "error", detail };
-      raiseOperatorAlarm({ clientId: `claude-app-oauth:${detail}`, source: "claude-app-oauth",
-        subject: "Claude app OAuth unavailable", detail, view: "overview", dedupeEvent: true });
+      (await raiseOperatorAlarm({ clientId: `claude-app-oauth:${detail}`, source: "claude-app-oauth",
+        subject: "Claude app OAuth unavailable", detail, view: "overview", dedupeEvent: true }));
       throw error;
     }));
   }

package/src/cli/workflow.ts

@@ -1,7 +1,7 @@
 import { apiRequest } from "./_shared";
 import { probeWorkflowDeployment } from "../../scripts/wait-for-deploy";
 
-export const WORKFLOW_USAGE = "Usage: humwick workflow start <workflow> <taskId> [--json] | workflow get <runId> [--verbose] [--include-held] [--results-ref <id>] [--results-cursor <cursor>] [--json] | workflow resume <runId> [--activation <id>] | workflow pause <runId> --reason <text> | workflow unpause <runId>";
+export const WORKFLOW_USAGE = "Usage: humwick workflow start <workflow> <taskId> [--json] | workflow get <runId> [--verbose] [--include-held] [--results-ref <id>] [--results-cursor <cursor>] [--json] | workflow resume <runId> [--activation <id>] [--step <step>] [--pins <json>] [--note <text>] | workflow pause <runId> --reason <text> | workflow unpause <runId>";
 
 export async function handleWorkflowCommand(args: string[]): Promise<void> {
   const [command, runId, ...flags] = args;
@@ -33,8 +33,17 @@ export async function handleWorkflowCommand(args: string[]): Promise<void> {
     return;
   }
   if (command === "resume") {
-    if (flags.length && (flags[0] !== "--activation" || flags.length !== 2 || !flags[1])) throw new Error(WORKFLOW_USAGE);
-    console.log(JSON.stringify(await apiRequest("POST", `/api/workflows/runs/${encodeURIComponent(runId)}/resume`, { ...(flags[1] ? { activationId: flags[1] } : {}) }), null, 2));
+    const body: Record<string, unknown> = {};
+    const fields: Record<string, string> = { "--activation": "activationId", "--step": "step", "--pins": "pins", "--note": "note" };
+    for (let index = 0; index < flags.length; index++) {
+      const flag = flags[index]!;
+      if (flag === "--json") continue;
+      const field = fields[flag];
+      const value = flags[++index];
+      if (!field || !value || value.startsWith("--")) throw new Error(WORKFLOW_USAGE);
+      body[field] = field === "pins" ? JSON.parse(value) : value;
+    }
+    console.log(JSON.stringify(await apiRequest("POST", `/api/workflows/runs/${encodeURIComponent(runId)}/resume`, body), null, 2));
     return;
   }
   const query = new URLSearchParams();

package/src/commands-db.ts

@@ -834,13 +834,13 @@ export function deleteCommand(id: string): boolean {
 
 // Race the host claim on the same pending row; only the winning cancellation records stop intent.
 // Legacy landing cancellation stays confined to its unfenced rows.
-export function cancelPendingCommand(id: string, expectedType: string, reason = "canceled before dispatch"): boolean {
+export function cancelPendingCommand(id: string, expectedType: string, reason = "canceled before dispatch", submittedAt: number = Date.now()): boolean {
   if (expectedType === "workspace.merge") {
     const existing = getCommand(id);
     if (!existing || !isLegacyUnfencedWorkspaceMerge(existing)) return false;
   }
   return inWriteTransaction(() => {
-    const now = Date.now();
+    const now = submittedAt;
     const changes = getDb()
       .query(`UPDATE commands SET status = 'canceled', result = ${canceledSpawnResultSql()}, error = ?, updated_at = ? WHERE id = ? AND status = 'pending' AND type = ?`)
       .run(reason, now, id, expectedType).changes;
@@ -978,7 +978,7 @@ export const EXPIRED_PENDING_COMMANDS_SQL = `SELECT * FROM commands WHERE (type
 
 export function expireCommands(
   now: number = Date.now(),
-  opts: { isTargetGone?: (command: Command) => boolean } = {},
+  opts: { isTargetGone?: (command: Command) => boolean; update?: typeof updateCommand } = {},
 ): Command[] {
   const activeRows = getDb().query(EXPIRED_CLAIMED_COMMANDS_SQL).all(now, ...CLAIMED_ACTIVE_STATUSES) as CommandRow[];
   const pendingCandidates = getDb().query(EXPIRED_PENDING_COMMANDS_SQL).all(now) as CommandRow[];
@@ -998,7 +998,7 @@ export function expireCommands(
     // #1452 round-13 — the TTL sweep is an AUTHORIZED terminalizer of a claimed publish (executor:true):
     // it is the fail-closed path that lets the reconciler clean a host-death-after-claim, and timed_out is
     // ambiguous (ref retained), never a ref-drop. External surfaces get no such flag (see updateCommand).
-    updateCommand(row.id, {
+    (opts.update ?? updateCommand)(row.id, {
       status: "timed_out",
       error: row.status === "pending"
         ? ((row.type === "agent.spawn" || row.type === "agent.restart") && hostSpawnsDrained(row.target) ? "host draining: spawns disabled; expired before dispatch" : "command target gone; expired before dispatch")

package/src/commands-write.ts

@@ -49,6 +49,10 @@ export async function createCommandAsync(
   vaultProjectId?: string,
 ): Promise<Command> {
   const args = await prepareCommandWriteAsync(input, options, vaultActor, vaultProjectId);
+  return submitPreparedCommandAsync(args);
+}
+
+export function submitPreparedCommandAsync(args: CreateCommandWriteArgs): Promise<Command> {
   return getGateway().coalesce(
     "commands.create",
     args,
@@ -82,6 +86,10 @@ export function getCommandAsync(id: string): Promise<Command | null> {
   return getGateway().read("commands.get", { id }) as unknown as Promise<Command | null>;
 }
 
+export function findLatestCommandByCorrelationAsync(type: string, correlationId: string): Promise<Command | null> {
+  return getGateway().read("commands.latestByCorrelation", { type, correlationId }) as unknown as Promise<Command | null>;
+}
+
 /** #2969 — an agent's confirmed effort changes within a chat window's time range, read off-loop. */
 export function listEffortChangesAsync(agentId: string, from: number, to: number, after?: EffortChangeCursor): Promise<{ changes: EffortChange[]; next?: EffortChangeCursor }> {
   return getGateway().read("commands.effortChanges", { agentId, from, to, ...(after ? { after } : {}) }) as unknown as Promise<{ changes: EffortChange[]; next?: EffortChangeCursor }>;

package/src/compaction-watch.ts

@@ -1,6 +1,8 @@
+import { framed } from "./hub-metrics";
+import { createActivityEventAsync } from "./db/activity-async";
 import { timePostBindPhase } from "./post-bind-startup";
 import { guardedInterval, isRecord } from "@humwick/sdk";
-import { getAgent, createActivityEvent } from "./db";
+import { getAgent } from "./db";
 import { emitRelayEvent } from "./events";
 import { isContinuationSelfResumeCommand } from "./self-resume-command";
 import type { AgentCard, Command } from "./types";
@@ -74,7 +76,7 @@ export class CompactionWatch {
   start(): void {
     if (this.timer) return;
     // #3643 — the tick writes an activity event; a BUSY from a bare timer would exit the hub.
-    this.timer = guardedInterval("[compaction-watch] tick", this.tickMs, () => timePostBindPhase("compaction-watch.tick", () => this.tick()));
+    this.timer = guardedInterval("[compaction-watch] tick", this.tickMs, framed("timer compaction-watch", () => timePostBindPhase("compaction-watch.tick", async () => (await this.tick()))));
   }
 
   stop(): void {
@@ -116,7 +118,7 @@ export class CompactionWatch {
     this.pending.delete(agentId);
   }
 
-  tick(): void {
+  async tick(): Promise<void> {
     const now = this.now();
     for (const [agentId, watch] of this.pending) {
       if (watch.deadline > now) continue;
@@ -138,15 +140,15 @@ export class CompactionWatch {
           continue;
         }
         this.pending.delete(agentId);
-        this.emitStalled(watch, true);
+        (await this.emitStalled(watch, true));
         continue;
       }
       this.pending.delete(agentId);
-      this.emitStalled(watch);
+      (await this.emitStalled(watch));
     }
   }
 
-  private emitStalled(watch: PendingWatch, busyCapped = false): void {
+  private async emitStalled(watch: PendingWatch, busyCapped = false): Promise<void> {
     const verb = watch.kind === "compact" ? "Compaction" : "Context clear";
     // #2043 F3 — the busy-capped variant means the agent is STILL taking turns (not stuck at a menu)
     // yet the compaction never started after a bounded wait — the runaway shape from #2043.
@@ -159,7 +161,7 @@ export class CompactionWatch {
       subject: watch.agentId,
       data: { agentId: watch.agentId, commandId: watch.commandId, kind: watch.kind, detail, busyCapped },
     });
-    createActivityEvent({
+    (await createActivityEventAsync({
       clientId: `command-stalled-${watch.commandId}-${this.now()}-${++this.seq}`,
       kind: "state",
       title: `${verb} stalled: ${watch.agentId}`,
@@ -168,7 +170,7 @@ export class CompactionWatch {
       view: "agents",
       agentId: watch.agentId,
       metadata: { source: "compaction-watch", commandId: watch.commandId, kind: watch.kind, stalled: true, detail, busyCapped },
-    });
+    }));
   }
 }
 

package/src/config-store-write.ts

@@ -45,7 +45,7 @@ export async function setAgentProfileAsync(profile: AgentProfile, updatedBy?: st
 }
 
 /** `deleteAgentProfile` on the writer thread (#1870 S7). */
-export function deleteAgentProfileAsync(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): Promise<boolean> {
+export async function deleteAgentProfileAsync(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): Promise<boolean> {
   const target = agentProfileDeleteTarget(name, opts);
-  return deleteConfigAsync(target.namespace, target.key, updatedBy);
+  return (await deleteConfigAsync(target.namespace, target.key, updatedBy));
 }

package/src/config.ts

@@ -637,21 +637,14 @@ export const DB_READER_JOB_TIMEOUT_MS = envPositiveInt("AGENT_RELAY_DB_READER_JO
 export const DB_READER_MARSHAL_IN_PROCESS =
   process.env.NODE_ENV === "test" || relayEnv(process.env, "AGENT_RELAY_DB_MARSHAL") === "1";
 
-/**
- * Phase-R rollout gate (#1960 T2 — ADR 0001 §7 Phase 1) for the gateway's READER half only. The
- * writer stays in-process unconditionally: Phase W (a worker writer taking the sole RW connection) is
- * a separate, much larger burn-down (#1870) and is deliberately NOT wired here. Any value other than
- * the literal `"worker"` — unset included — resolves to `"in-process"`, so this is behavior-preserving
- * by default; an operator opts in explicitly per the same string-literal convention as
- * `parseKernelTimersMode`.
- */
+/** Explicit reader placement override. Otherwise file databases use workers (#3339). */
 export type GatewayReaderBackendMode = "in-process" | "worker";
 
-export function parseGatewayReaderBackend(value: string | undefined): GatewayReaderBackendMode {
-  return value === "worker" ? "worker" : "in-process";
+export function parseGatewayReaderBackend(value: string | undefined): GatewayReaderBackendMode | undefined {
+  return value === "worker" || value === "in-process" ? value : undefined;
 }
 
-export function gatewayReaderBackendFromEnv(): GatewayReaderBackendMode {
+export function gatewayReaderBackendFromEnv(): GatewayReaderBackendMode | undefined {
   return parseGatewayReaderBackend(relayEnv(process.env, "AGENT_RELAY_GATEWAY_READER_BACKEND"));
 }
 

package/src/connectors.ts

@@ -1,10 +1,12 @@
+import { framed } from "./hub-metrics";
+import { upsertAgentAsync } from "./db/agents-async";
 import { writeChildEnv } from "@humwick/sdk/env";
 import { timePostBindPhase } from "./post-bind-startup";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import type { ConnectorAction, ConnectorActionResult, ConnectorManifest, ConnectorSummary } from "./types";
-import { upsertAgent, ValidationError } from "./db";
+import { ValidationError } from "./db";
 import { CHANNELS_HOST_SECRETS } from "@humwick/sdk/channels-host-service";
 import { fireAndForget, guardedInterval, isRecord } from "@humwick/sdk";
 import { registerConnectorConfigSetting, validateConnectorConfig } from "./settings/modules";
@@ -274,11 +276,11 @@ export function startConnectorStatusPoller(): void {
   //    deploy that took down the relay/orchestrator tree) BEFORE the first status
   //    poll overwrites their persisted "running" flag with the now-dead reality.
   void fireAndForget("[connectors] boot reconcile", async () => {
-    await fireAndForget("[connectors] ensure channels host", () => timePostBindPhase("connectors.ensureChannelsHostConnector", () => ensureChannelsHostOnBoot()));
+    await fireAndForget("[connectors] ensure channels host", () => timePostBindPhase("connectors.ensureChannelsHostConnector", async () => (await ensureChannelsHostOnBoot())));
     await fireAndForget("[connectors] reconcile on boot", () => timePostBindPhase("connectors.reconcileConnectorsOnBoot", reconcileConnectorsOnBoot));
     await timePostBindPhase("connectors.refreshAllConnectorStatuses", refreshAllConnectorStatuses);
   });
-  guardedInterval("[connectors] status poll", STATUS_POLL_INTERVAL_MS, () => timePostBindPhase("connectors.refreshAllConnectorStatuses", refreshAllConnectorStatuses));
+  guardedInterval("[connectors] status poll", STATUS_POLL_INTERVAL_MS, framed("timer connector-status", () => timePostBindPhase("connectors.refreshAllConnectorStatuses", refreshAllConnectorStatuses)));
 }
 
 const CHANNELS_HOST_ID = "channels-host";
@@ -386,14 +388,14 @@ function configuredNtfyTopic(): string | null {
  * adapter's own gate — an unconfigured relay genuinely has no escalation target and must
  * still warn. Returns true when the row was (re)registered.
  */
-export function ensureEscalationChannelRegistered(): boolean {
+export async function ensureEscalationChannelRegistered(): Promise<boolean> {
   if (isEphemeralMode()) return false;
   const topic = configuredNtfyTopic();
   if (!topic) return false;
   // Shape matches the channels-host adapter's registration (channels-host/src/relay.ts
   // registerChannel + adapters/ntfy.ts channels()), so its later re-registration updates
   // the same row in place rather than churning it.
-  upsertAgent({
+  (await upsertAgentAsync({
     id: ESCALATION_NTFY_CHANNEL_ID,
     name: "ntfy",
     kind: "channel",
@@ -411,7 +413,7 @@ export function ensureEscalationChannelRegistered(): boolean {
       displayName: "ntfy",
       topicChannels: [topic],
     },
-  });
+  }));
   return true;
 }
 
@@ -429,7 +431,7 @@ export async function ensureChannelsHostConnector(entry = resolveChannelsHostEnt
   // Register the escalation channel row now that config (incl. any legacy-migrated topic)
   // is persisted, so the escalation-target check passes without waiting for the async
   // channels-host SSE connect (#1510).
-  ensureEscalationChannelRegistered();
+  (await ensureEscalationChannelRegistered());
 
 
 }
@@ -437,7 +439,7 @@ export async function ensureChannelsHostConnector(entry = resolveChannelsHostEnt
 /** Boot wrapper: a failed bring-up is logged with its stack and raised to /api/health, never swallowed (#3393). */
 export async function ensureChannelsHostOnBoot(entry?: string | null): Promise<void> {
   try {
-    await (entry === undefined ? ensureChannelsHostConnector() : ensureChannelsHostConnector(entry));
+    await (entry === undefined ? (await ensureChannelsHostConnector()) : (await ensureChannelsHostConnector(entry)));
     clearChannelsHostEnsureFailure();
   } catch (error) {
     console.error("[connectors] ensureChannelsHostConnector failed:", error instanceof Error ? (error.stack ?? error.message) : error);

package/src/context-advisory.ts

@@ -1,5 +1,6 @@
+import { getGateway } from "./db/gateway";
 import { deriveContextThresholdFromWindowTokens, findProviderCatalogModel, resolveProviderContextThreshold, type ProviderModelCatalogEntry, type ResolvedProviderContextThreshold } from "@humwick/sdk/provider-catalog";
-import { isRecord, isSpawnProvider } from "@humwick/sdk";
+import { fireAndForget, isRecord, isSpawnProvider } from "@humwick/sdk";
 import { HARD_BACKSTOP_BUSY_GRACE_MS } from "./config";
 import { getConfig } from "./config-store";
 import { getToken } from "./token-db";
@@ -39,7 +40,7 @@ interface EffectiveContextThreshold extends ResolvedProviderContextThreshold {
  * #315 — context pressure is a relay-native signal: durable event for observers,
  * plus an agent-facing system push when lifecycle notifications are enabled.
  */
-function notifyContextAdvisory(input: ContextAdvisoryInput): void {
+async function notifyContextAdvisory(input: ContextAdvisoryInput): Promise<void> {
   const payload = {
     kind: "agent.context_threshold",
     agentId: input.agentId,
@@ -63,20 +64,20 @@ function notifyContextAdvisory(input: ContextAdvisoryInput): void {
 
   // Short default TTL (per-type): a stale context advisory is misleading — the band may have moved
   // by the time the agent next polls, so old advice shouldn't wake it.
-  routeNotification({
+  await routeNotification({
     type: "agent.context_threshold",
     scope: { agentId: input.agentId },
     recipients: [input.agentId],
     message: {
       subject: input.stage === "warn" ? "Context threshold warning" : "Context self-compact threshold reached",
-      body: contextAdvisoryBody(input),
+      body: (await contextAdvisoryBody(input)),
       payload,
       replyExpected: false,
     },
   });
 }
 
-function contextAdvisoryBody(input: ContextAdvisoryInput): string {
+async function contextAdvisoryBody(input: ContextAdvisoryInput): Promise<string> {
   const tokens = `${formatTokens(input.tokens)} / ${formatTokens(input.windowTokens)} tokens used`;
   const percent = `${input.percent}% of window, ${input.band}% band`;
   const threshold = `resolved self-compact threshold ${input.selfCompactPercent}% (${input.thresholdSource})`;
@@ -96,7 +97,7 @@ function contextAdvisoryBody(input: ContextAdvisoryInput): string {
       threshold,
       hardBackstop: `${input.hardBackstopPercent}%`,
     });
-  return withPreBoundaryCapture(advisory, input.agentId);
+  return (await withPreBoundaryCapture(advisory, input.agentId));
 }
 
 /**
@@ -110,8 +111,8 @@ function contextAdvisoryBody(input: ContextAdvisoryInput): string {
  * Appended rather than woven into the advisory templates so a blank slug leaves the advisory body
  * BYTE-IDENTICAL to the pre-P5 one.
  */
-function withPreBoundaryCapture(advisory: string, agentId: string): string {
-  const capture = boundaryCaptureClause({ seam: "pre", agentId });
+async function withPreBoundaryCapture(advisory: string, agentId: string): Promise<string> {
+  const capture = (await boundaryCaptureClause({ seam: "pre", agentId }));
   return capture ? `${advisory}\n\n${capture}` : advisory;
 }
 
@@ -123,12 +124,12 @@ function contextAdvisoryBand(utilization: number, threshold: EffectiveContextThr
   return { band: utilizationPercent(threshold.warnUtilization), stage: "warn" };
 }
 
-export function handleContextPressure(input: {
+export async function handleContextPressure(input: {
   agent: AgentCard;
   now: () => number;
   hasActiveCommand: (target: string, type: string) => boolean;
-  compact: (reason: string) => Command | null;
-}): boolean {
+  compact: (reason: string) => Command | null | Promise<Command | null>;
+}): Promise<boolean> {
   const { agent, now } = input;
   const context = agent.context;
   if (!context) return false;
@@ -138,7 +139,7 @@ export function handleContextPressure(input: {
   const advisory = contextAdvisoryBand(context.utilization, threshold);
   if (advisory === null) {
     if (context.lastContextAdvisoryBand !== undefined || context.lastContextAdvisoryAt !== undefined || context.hardBackstopDeferredAt !== undefined) {
-      persistContextState(agent.id, clearContextAdvisory(context));
+      (await persistContextState(agent.id, clearContextAdvisory(context)));
     }
     return false;
   }
@@ -160,8 +161,8 @@ export function handleContextPressure(input: {
     // mid-turn (the runner waits for the live turn to clear before submitting the keystrokes).
     const graceElapsed = deferredAt !== undefined && now() - deferredAt >= HARD_BACKSTOP_BUSY_GRACE_MS;
     if (!busy || graceElapsed) {
-      input.compact(busy ? "context-hard-backstop-busy" : "context-hard-backstop");
-      if (deferredAt !== undefined) persistContextState(agent.id, clearHardBackstopDefer(context));
+      await input.compact(busy ? "context-hard-backstop-busy" : "context-hard-backstop");
+      if (deferredAt !== undefined) (await persistContextState(agent.id, clearHardBackstopDefer(context)));
       return true;
     }
     // Busy and within grace: start the bounded defer clock (once), then fall through so the
@@ -169,19 +170,19 @@ export function handleContextPressure(input: {
     // the forced backstop.
     if (deferredAt === undefined) {
       state = { ...context, hardBackstopDeferredAt: now() };
-      persistContextState(agent.id, state);
+      (await persistContextState(agent.id, state));
     }
   } else if (context.hardBackstopDeferredAt !== undefined) {
     // Dropped below the hard backstop (or a forced compaction is already in flight): reset the clock
     // so a later re-crossing starts a fresh grace window rather than firing immediately.
     state = clearHardBackstopDefer(context);
-    persistContextState(agent.id, state);
+    (await persistContextState(agent.id, state));
   }
   if (state.lastContextAdvisoryBand === advisory.band) return false;
   const tokens = finiteNumber(context.tokensUsed);
   const windowTokens = finiteNumber(context.tokensMax);
   if (tokens === undefined || windowTokens === undefined) return false;
-  notifyContextAdvisory({
+  await fireAndForget(`[context] advisory ${input.agent.id}`, async () => (await notifyContextAdvisory({
     agentId: agent.id,
     agent,
     tokens,
@@ -193,8 +194,8 @@ export function handleContextPressure(input: {
     selfCompactPercent: utilizationPercent(threshold.selfCompactUtilization),
     hardBackstopPercent: utilizationPercent(threshold.hardBackstopUtilization),
     thresholdSource: threshold.source,
-  });
-  persistContextState(agent.id, { ...state, lastContextAdvisoryBand: advisory.band, lastContextAdvisoryAt: now() });
+  })));
+  (await persistContextState(agent.id, { ...state, lastContextAdvisoryBand: advisory.band, lastContextAdvisoryAt: now() }));
   return true;
 }
 
@@ -258,8 +259,8 @@ function clearHardBackstopDefer(context: ContextState): ContextState {
   return rest;
 }
 
-function persistContextState(agentId: string, context: ContextState): void {
-  getDb().query("UPDATE agents SET context_state = ? WHERE id = ?").run(JSON.stringify(context), agentId);
+async function persistContextState(agentId: string, context: ContextState): Promise<void> {
+  await getGateway().write("agents.persistAdvisoryContext", [agentId, context]);
 }
 
 function finiteNumber(value: unknown): number | undefined {

package/src/db/agent-action-write.ts

@@ -0,0 +1,36 @@
+import { ValidationError } from "@humwick/sdk";
+import { createCommandInternal, getCommand } from "../commands-db";
+import { assertSelfEffortAllowed } from "../services/self-effort";
+import { admitDesiredEffortInternal, getAgentEffortState } from "./agent-effort-state";
+import { getAgent } from "./agents";
+import { sendMessageWithResultInternal } from "./messages";
+import type { AgentCard, CreateCommandInput, SendMessageInput } from "../types";
+import type { EffortChangeActorRole } from "@humwick/sdk";
+
+export interface AgentActionWrite {
+  agent: AgentCard;
+  commandId: string;
+  commandInput: Omit<CreateCommandInput, "params"> & { params: Record<string, unknown> };
+  requestId?: string;
+  effort?: string;
+  role: EffortChangeActorRole;
+  selfEffort?: { level: string; efforts?: readonly string[] };
+  message?: SendMessageInput;
+}
+
+export function admitAgentActionBody(input: AgentActionWrite, now: number) {
+  const prior = input.requestId ? getCommand(input.requestId) : null;
+  if (prior) {
+    if (prior.type !== "agent.setEffort" || prior.target !== input.agent.id) throw new ValidationError("requestId belongs to another request");
+    return { command: prior, raced: true, effortState: getAgentEffortState(input.agent.id) };
+  }
+  const current = getAgent(input.agent.id);
+  if (!current || current.instanceId !== input.agent.instanceId || current.epoch !== input.agent.epoch) throw new ValidationError("agent instance changed while the action audit was committing");
+  if (input.selfEffort) assertSelfEffortAllowed(current, input.selfEffort.level, input.selfEffort.efforts);
+  const sent = input.message ? sendMessageWithResultInternal(input.message, false, {}, now) : undefined;
+  if (sent) Object.assign(input.commandInput.params, { messageId: sent.message.id, from: sent.message.from });
+  const admitted = input.effort ? admitDesiredEffortInternal({ agentId: current.id, effort: input.effort, role: input.role, commandId: input.commandId, now }) : undefined;
+  if (admitted) input.commandInput.params.effortVersion = admitted.state.desiredVersion;
+  const command = createCommandInternal({ input: input.commandInput, id: input.commandId }, now);
+  return { command, raced: false, admitted, sessionMessage: sent?.message };
+}

package/src/db/agent-control-async.ts

@@ -0,0 +1,9 @@
+import { getGateway } from "./gateway";
+import type { AgentControlWrite, SelfEffortGrantWrite, createAgentControlBody, grantSelfEffortBody } from "./agent-control-write";
+
+export function createAgentControlAsync(input: AgentControlWrite): Promise<ReturnType<typeof createAgentControlBody>> {
+  return getGateway().write("agents.createControl", input, { idempotencyKey: input.commandId, critical: true }) as unknown as Promise<ReturnType<typeof createAgentControlBody>>;
+}
+export function grantSelfEffortAsync(input: SelfEffortGrantWrite): Promise<ReturnType<typeof grantSelfEffortBody>> {
+  return getGateway().write("agents.grantSelfEffort", input, { idempotencyKey: input.commandId }) as unknown as Promise<ReturnType<typeof grantSelfEffortBody>>;
+}

package/src/db/agent-control-write.ts

@@ -0,0 +1,49 @@
+import { ValidationError } from "@humwick/sdk";
+import { createCommandInternal, updateCommandInternal } from "../commands-db";
+import { agentProviderState } from "../provider-state";
+import { stopRefusal, type SafeCandidate } from "../services/idle-agent-digest";
+import { selfEffortIdentity, type SelfEffortGrant, type SelfEffortPolicy } from "../services/self-effort";
+import { getAgent } from "./agents";
+import { SELF_EFFORT_BAND, setSelfEffortCeilingInternal } from "./self-effort-permissions";
+import type { AgentCard, Command, CreateCommandInput } from "../types";
+
+export interface AgentControlWrite {
+  agent?: AgentCard | null;
+  commandId: string;
+  commandInput: CreateCommandInput;
+  approvalId?: string;
+  idleCandidate?: SafeCandidate;
+}
+export function createAgentControlBody(input: AgentControlWrite, now: number): { command?: Command; refused?: string } {
+  if (input.agent) {
+    const current = getAgent(input.agent.id);
+    if (!current || current.instanceId !== input.agent.instanceId || current.epoch !== input.agent.epoch) throw new ValidationError("agent instance changed while the action audit was committing");
+    if (input.approvalId) {
+      const state = agentProviderState(current);
+      if (state?.state !== "blocked" || state.pendingApproval?.id !== input.approvalId) throw new ValidationError("approval request is no longer current");
+    }
+    if (input.idleCandidate) {
+      const refusal = stopRefusal(input.idleCandidate, current, now);
+      if (refusal) return { refused: refusal.reason };
+    }
+  }
+  return { command: createCommandInternal({ input: input.commandInput, id: input.commandId }, now) };
+}
+
+export const SELF_EFFORT_GRANT_COMMAND = "agent.grantSelfEffort";
+export interface SelfEffortGrantWrite {
+  agent: AgentCard; grant?: SelfEffortGrant; requestedBy: string; commandId: string; spawnRequestId?: string;
+  input: { requestedVia: "mcp" | "http"; requestedByUser?: string };
+  selfEffort: SelfEffortPolicy | null; previous: SelfEffortPolicy | null;
+}
+export function grantSelfEffortBody({ agent, grant, requestedBy, commandId, spawnRequestId, input, selfEffort, previous }: SelfEffortGrantWrite, now: number): Command {
+  const current = getAgent(agent.id);
+  if (!current || current.instanceId !== agent.instanceId || current.epoch !== agent.epoch) throw new ValidationError("agent instance changed while the action audit was committing");
+  const identity = selfEffortIdentity(current);
+  setSelfEffortCeilingInternal(identity, !grant ? null : "band" in grant ? SELF_EFFORT_BAND : grant.ceiling, requestedBy, now);
+  createCommandInternal({ id: commandId, input: { type: SELF_EFFORT_GRANT_COMMAND, source: "system", target: agent.id,
+    ...(spawnRequestId ? { correlationId: spawnRequestId } : {}), params: { agentId: agent.id,
+      ...(spawnRequestId ? { spawnRequestId } : {}), permission: identity, selfEffort, previousSelfEffort: previous, requestedBy,
+      ...(input.requestedByUser ? { requestedByUser: input.requestedByUser } : {}), requestedVia: input.requestedVia, requestedAt: now } } }, now);
+  return updateCommandInternal(commandId, { status: "succeeded", result: { selfEffort } }, {}, now).command!;
+}