@humwick/server 0.130.2 → 0.130.3

package/src/server.ts

@@ -1,3 +1,5 @@
+import { framed } from "./hub-metrics";
+import { setConfigAsync } from "./config-store-write";
 import { drainWriterOnShutdown } from "./db/writer-gateway";
 import { relayHeaderConflict, errMessage, reapEphemeralSelf, startArtifactCheckoutLease, startEphemeralWatchdogFromEnv } from "@humwick/sdk";
 import { authorityDenied } from "./authority-audit";
@@ -12,7 +14,7 @@ import { beginMainWriteBootPhase, endMainWriteBootPhase } from "./db/main-connec
 import { markServerBound, timePostBindPhase } from "./post-bind-startup";
 import type { ServerWebSocket } from "bun";
 import { beginStartupPhase, enableStartupTiming, timeStartupPhase } from "./startup-timing";
-import { initDb, getOrchestrator, startPresenceFlushLoop, primeHostAliasMemoFromDb } from "./db";
+import { initDb, getOrchestrator, startPresenceFlushLoop, primeHostAliasMemoFromDb, onWorkspaceCreate } from "./db";
 import { initGateway, shutdownGatewayReader } from "./db/gateway";
 import { flushRelayEvents } from "./relay-event-drain";
 import { startWalCheckpointer } from "./db/wal-checkpointer";
@@ -25,7 +27,7 @@ import { emitRelayEvent } from "./events";
 import { reconcileAutomationRuns, runDueAutomationsAsync, type AutomationDispatchResult, type AutomationReconcileResult } from "./automations";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { reconcileStewardPolicyModels } from "./steward-policy-model-reconcile";
-import { getConfig, setConfig } from "./config-store";
+import { getConfig } from "./config-store";
 export { reconcileProviderModelSeed } from "./provider-model-seed";
 import { ensureEscalationChannelRegistered } from "./connectors";
 import { installNotificationSubscriptionRule } from "./notification-subscription-rules";
@@ -33,7 +35,6 @@ import { startPlanLiveBindings } from "./services/plan-live-bindings";
 import { startEventLoopLagSampler } from "./event-loop-lag";
 import { installLoopBlockRegressionAlarm } from "./loop-block-regression-alarm";
 import { recordWorkspaceIssueActivity } from "./services/spawn-issue-activity";
-import { onWorkspaceCreate } from "./db";
 import { warnIfNoHumanReachableEscalationTarget } from "./workspace-human-escalation";
 import { isTerminalSessionRequestAuthorized } from "./terminal-authz";
 import { resolveBrowserStream } from "./routes/browser";
@@ -84,16 +85,16 @@ import type { Command } from "./types";
 //
 // `relay-version` is still tracked for observability/telemetry, but it no longer
 // triggers restarts.
-export function reconcileRelayVersion(): void {
+export async function reconcileRelayVersion(): Promise<void> {
   const storedVersion = getConfig<string>("system", "relay-version")?.value;
-  if (storedVersion !== VERSION) setConfig("system", "relay-version", VERSION, "server-startup");
+  if (storedVersion !== VERSION) (await setConfigAsync("system", "relay-version", VERSION, "server-startup"));
 
   const storedProtocol = getConfig<string>("system", "runner-protocol-version")?.value;
   const currentProtocol = String(CONTRACT_VERSIONS.runnerProtocol);
   if (storedProtocol === currentProtocol) return;
   // Skip the very first run (no stored protocol yet) — that's initial bootstrap, not an upgrade.
   if (storedProtocol) getLifecycleManager().onRelayUpdated(VERSION);
-  setConfig("system", "runner-protocol-version", currentProtocol, "server-startup");
+  (await setConfigAsync("system", "runner-protocol-version", currentProtocol, "server-startup"));
 }
 
 export function runServerStartupRecoveries(): ReturnType<typeof sweepDeferredLineageReportsOnStartup> {
@@ -116,9 +117,7 @@ export async function startServer(): Promise<void> {
   timeStartupPhase("server.database", () => initDb(DB_PATH));
   // #1960 T2 — stand the gateway up EXPLICITLY here rather than leaving it to the lazy self-init
   // (`getGateway()` on first call, gateway.ts), which would race the rest of this boot sequence.
-  // Reader backend is env-gated (AGENT_RELAY_GATEWAY_READER_BACKEND, default "in-process" — Phase R,
-  // ADR 0001 §7 Phase 1); the writer is deliberately left at its in-process default — Phase W (a
-  // worker writer surrendering the sole RW connection) remains the #1870 migration.
+  // File-backed reads and writes default off-loop; memory fixtures retain local connections (#3339).
   timeStartupPhase("server.gateway", () => initGateway({ readerBackend: gatewayReaderBackendFromEnv() }));
   onShutdown("gateway-reader", shutdownGatewayReader);
   onShutdown("gateway-writer", drainWriterOnShutdown, "drain");
@@ -137,11 +136,11 @@ export async function startServer(): Promise<void> {
   const finishServices = beginStartupPhase("server.services");
   installNotificationSubscriptionRule();
   startPlanLiveBindings();
-  reconcileRelayVersion();
+  (await reconcileRelayVersion());
   // Register the ntfy escalation channel row from persisted connector config BEFORE the
   // warning check, so a correctly-configured relay doesn't spuriously warn while the async
   // channels-host connect is still in flight (#1510).
-  ensureEscalationChannelRegistered();
+  (await ensureEscalationChannelRegistered());
   warnIfNoHumanReachableEscalationTarget();
   startEventLoopLagSampler();
   // #1882 (S5, ADR 0001 §5) — per-callsite on-loop-block attribution + the >50ms regression alarm.
@@ -167,12 +166,12 @@ export async function startServer(): Promise<void> {
       },
     });
   } else {
-    setInterval(() => {
+    setInterval(framed("timer automations", () => {
       void timePostBindPhase("automations.reconcile", reconcileAutomationRuns)
         .then(emitAutomationReconciliations)
         .catch((e) => console.error(`[automations] reconcile failed: ${errMessage(e)}`));
       void timePostBindPhase("automations.dispatch", runDueAutomationsAsync).then(emitAutomationDispatches).catch((e) => console.error(`[automations] dispatch failed: ${errMessage(e)}`));
-    }, AUTOMATION_INTERVAL_MS);
+    }), AUTOMATION_INTERVAL_MS);
   }
 
   installTimerIngressSchema();
@@ -186,7 +185,7 @@ export async function startServer(): Promise<void> {
     websocket: createWebSocketHandlers(),
   }));
   markServerBound();
-  startServerBackgroundJobs();
+  await startServerBackgroundJobs();
   finishStartup();
   console.log(`humwick ${VERSION} running on http://${HOST}:${PORT}`);
 
@@ -280,12 +279,12 @@ export function createFetchHandler(
     const terminalStreamMatch = url.pathname.match(/^\/api\/orchestrators\/([^/]+)\/terminal\/([^/]+)\/stream$/);
     if (req.method === "GET" && terminalStreamMatch) {
       if (!server) return new Response("WebSocket upgrade unavailable", { status: 400 });
-      if (!isOriginAllowed(req)) return authorityDenied(req, "origin not allowed", 403);
-      if (!isAuthorized(req)) return applyCors(req, authorityDenied(req, "unauthorized", 401));
+      if (!isOriginAllowed(req)) return (await authorityDenied(req, "origin not allowed", 403));
+      if (!isAuthorized(req)) return applyCors(req, (await authorityDenied(req, "unauthorized", 401)));
       const orchestratorId = decodeURIComponent(terminalStreamMatch[1]!);
       const session = decodeURIComponent(terminalStreamMatch[2]!);
       if (!isTerminalSessionRequestAuthorized(req, orchestratorId, session, "read")) {
-        return applyCors(req, authorityDenied(req, "forbidden"));
+        return applyCors(req, (await authorityDenied(req, "forbidden")));
       }
       const writeAuthorized = isTerminalSessionRequestAuthorized(req, orchestratorId, session, "write");
       const orch = getOrchestrator(orchestratorId);
@@ -312,7 +311,7 @@ export function createFetchHandler(
     }
     const matched = matchRoute(req.method, url.pathname);
     if (!isOriginAllowed(req) && !(req.headers.get("origin") === "null" && matched?.handler === postSecretUpload)) {
-      return authorityDenied(req, "origin not allowed", 403);
+      return (await authorityDenied(req, "origin not allowed", 403));
     }
 
     // KAPI-1 §4.2 — the live `/api/kernel` control mount. Handled as a dedicated subtree (not through
@@ -322,7 +321,7 @@ export function createFetchHandler(
     // default-denies. A request that fails the coarse gate 403s here (matching the resolver's own 403 for
     // a missing/invalid/non-component credential), including `GET /api/kernel/openapi.json`.
     if (isKernelControlPath(url.pathname)) {
-      if (!isKernelControlRequestAuthorized(req)) return applyCors(req, authorityDenied(req, "forbidden"));
+      if (!isKernelControlRequestAuthorized(req)) return applyCors(req, (await authorityDenied(req, "forbidden")));
       const response = await handleKernelControlRequest(req);
       applyCors(req, response);
       if (logRequests) console.log(`${req.method} ${url.pathname} → ${response.status}`);
@@ -367,11 +366,11 @@ export function createFetchHandler(
             // full server scope), so it stays the authoritative reject for a revoked/
             // invalid session token — it just answers in the caller's protocol.
             if (url.pathname === "/api/mcp") return unauthorizedMcp(req);
-            return applyCors(req, authorityDenied(req, "unauthorized", 401));
+            return applyCors(req, (await authorityDenied(req, "unauthorized", 401)));
           }
-          if (!handlerOwnsScopedAuth && !isScopedRequestAuthorized(req)) return applyCors(req, authorityDenied(req, "forbidden"));
+          if (!handlerOwnsScopedAuth && !isScopedRequestAuthorized(req)) return applyCors(req, (await authorityDenied(req, "forbidden")));
         }
-        if (componentAuth && !handlerOwnsScopedAuth && !isScopedRequestAuthorized(req)) return applyCors(req, authorityDenied(req, "forbidden"));
+        if (componentAuth && !handlerOwnsScopedAuth && !isScopedRequestAuthorized(req)) return applyCors(req, (await authorityDenied(req, "forbidden")));
       }
       const response = await runMatchedRoute(matched, req, (body) => maybeCompressApiResponse(req, url, body));
       applyCors(req, response);

package/src/services/agent-action.ts

@@ -1,9 +1,11 @@
+import { getGateway } from "../db/gateway";
+import type { admitAgentActionBody } from "../db/agent-action-write";
 import { isHumanAgentId } from "@humwick/sdk";
 import { randomUUID } from "node:crypto";
-import { createCommandInternal, getCommand } from "../commands-db";
-import { admitDesiredEffortInternal, getAgentEffortState } from "../db/agent-effort-state";
+import { getCommand } from "../commands-db";
+import { getAgentEffortState } from "../db/agent-effort-state";
 import { emitEffortState } from "./agent-effort";
-import { ValidationError, createActivityEventAsync, getAgent, sendMessage, writeTransaction } from "../db";
+import { ValidationError, createActivityEventAsync, getAgent } from "../db";
 import { emitCommandEvent } from "../command-events";
 import { emitActivityEvent, emitNewMessage } from "../sse";
 import { effectiveProviderCatalogList } from "../provider-catalog-store";
@@ -112,15 +114,6 @@ function catalogEffort(agent: AgentCard, effort: string | undefined): { level: s
   return { level, efforts: known?.efforts };
 }
 
-function sessionMessageForInject(agentId: string, ctx: AuthContext, body: string) {
-  const from = ctx.callerAgentId && getAgent(ctx.callerAgentId) ? ctx.callerAgentId : "system";
-  return sendMessage({
-    from,
-    to: agentId,
-    kind: "session",
-    body,
-  });
-}
 
 export function revalidateAgentInstance(snapshot: AgentCard): AgentCard {
   const current = getAgent(snapshot.id);
@@ -136,7 +129,7 @@ export async function dispatchAgentAction(input: AgentActionInput, ctx: AuthCont
 
   // #2950 — an agent may change its own effort (only that), gated by its spawn's selfEffort ceiling below.
   const self = input.action === "effort" && Boolean(ctx.callerAgentId) && ctx.callerAgentId === agent.id;
-  if (!self) authorizeShutdown(ctx, { agentId: input.agentId, requestedVia: input.requestedVia }, input.action);
+  if (!self) (await authorizeShutdown(ctx, { agentId: input.agentId, requestedVia: input.requestedVia }, input.action));
   const requestId = input.action === "effort" ? input.requestId?.trim() || undefined : undefined;
   if (requestId && !REQUEST_ID.test(requestId)) throw new ValidationError("requestId must be a UUID");
   const retried = admittedEffortRequest(agent.id, requestId);
@@ -210,24 +203,12 @@ export async function dispatchAgentAction(input: AgentActionInput, ctx: AuthCont
   // a stale command built from the predecessor's capabilities/session data.
   const event = await createActivityEventAsync(activityInput);
   const current = revalidateAgentInstance(agent);
-  const sessionMessage = body ? sessionMessageForInject(current.id, ctx, body) : undefined;
-  // #2664 — the runner keeps the original sender on a prompt it has to park.
-  if (sessionMessage) Object.assign(commandInput.params, { messageId: sessionMessage.id, from: sessionMessage.from });
-  let admitted: ReturnType<typeof admitDesiredEffortInternal> | undefined;
-  let raced: AgentActionResult | undefined;
-  const command = writeTransaction(() => {
-    // A concurrent retry of the same request committed first.
-    if ((raced = admittedEffortRequest(current.id, requestId))) return raced.command;
-    // #2966 — a revoke committed during the audit await wins: recheck where the command is inserted.
-    if (selfPolicy) assertSelfEffortAllowed(current, requested!.level, requested!.efforts);
-    if (effort) {
-      // #2984 — the desired version is the change; the command is its audit row, never executed.
-      admitted = admitDesiredEffortInternal({ agentId: current.id, effort, role: requestedByRole, commandId, now: Date.now() });
-      commandInput.params.effortVersion = admitted.state.desiredVersion;
-    }
-    return createCommandInternal({ input: commandInput, id: commandId });
-  });
-  if (raced) return raced;
+  const from = ctx.callerAgentId && getAgent(ctx.callerAgentId) ? ctx.callerAgentId : "system";
+  const result = await getGateway().write("agents.admitAction", { agent: current, commandId, commandInput, requestId, effort, role: requestedByRole,
+    ...(selfPolicy ? { selfEffort: requested } : {}), ...(body ? { message: { from, to: current.id, kind: "session", body } } : {}) }, { idempotencyKey: commandId }) as unknown as ReturnType<typeof admitAgentActionBody>;
+  const { command } = result;
+  if (result.raced) return { action: input.action, command, effortState: result.effortState };
+  const { admitted, sessionMessage } = result;
   if (sessionMessage) emitNewMessage(sessionMessage);
   for (const id of admitted?.superseded ?? []) { const canceled = getCommand(id); if (canceled) emitCommandEvent(canceled, "command.canceled"); }
   // No `command.requested` for effort: nothing executes the audit row. `command.pending` only tells the target runner to reconcile.

package/src/services/agent-effort.ts

@@ -1,7 +1,10 @@
+import { getGateway } from "../db/gateway";
+import type { observeEffortBody } from "../db/agent-effort-observe";
+import { sendMessageAsync } from "../db/message-send";
 import type { AgentEffortState } from "@humwick/sdk";
 import { getCommand } from "../commands-db";
 import { emitCommandEvent } from "../command-events";
-import { findMessageByIdempotencyKey, sendMessage, validateAgentSession, writeTransaction } from "../db";
+import { findMessageByIdempotencyKey, validateAgentSession, writeTransaction } from "../db";
 import { EffortReportRejected, recordEffortObservedInternal, type EffortObservation } from "../db/agent-effort-state";
 import { emitRelayEvent } from "../events";
 import { emitNewMessage } from "../sse";
@@ -9,47 +12,19 @@ import type { Command, Message } from "../types";
 
 export { EffortReportRejected };
 
-/** #2984 — the prompt that resumes an agent once its own effort change applied. */
-export function selfEffortContinuation(effort: string): string {
-  return `Effort is now ${effort}. Continue your work.`;
-}
-
 /** Dashboard + runner notice: the agent's desired/observed effort changed. */
 export function emitEffortState(state: AgentEffortState): void {
   emitRelayEvent({ type: "agent.effort", source: "server", subject: state.agentId, data: state as unknown as Record<string, unknown> });
 }
 
-/** One continuation per owed resume (keyed by the self request's version): a repeated report finds the first. */
-function enqueueSelfContinuation(agentId: string, version: number, effort: string): Message | undefined {
-  const idempotencyKey = `effort-continuation:${agentId}:${version}`;
-  if (findMessageByIdempotencyKey("system", idempotencyKey)) return undefined;
-  return sendMessage({
-    from: "system",
-    to: agentId,
-    kind: "system",
-    subject: "Effort changed",
-    body: selfEffortContinuation(effort),
-    replyExpected: false,
-    idempotencyKey,
-    payload: { kind: "agent.effort_continuation", agentId, effortVersion: version, effort },
-  });
-}
-
 export interface EffortReport { instanceId: string; version: number; effort: string; previousEffort: string | null }
 
-export class EffortReportFenced extends Error {}
+export { EffortReportFenced, selfEffortContinuation } from "../db/agent-effort-observe";
 
 /** A runner applied (or verified) a desired version. Fenced to the agent's current incarnation; the
  *  observation and the resume it settles are one transaction. */
-export function reportEffortObserved(agentId: string, report: EffortReport, now = Date.now()): EffortObservation {
-  let continuation: Message | undefined;
-  const observed = writeTransaction(() => {
-    const session = validateAgentSession(agentId, { instanceId: report.instanceId });
-    if (!session.ok) throw new EffortReportFenced(session.error ?? "stale agent instance");
-    const result = recordEffortObservedInternal({ agentId, ...report, now });
-    if (result.outcome !== "stale" && result.resumeVersion !== undefined) continuation = enqueueSelfContinuation(agentId, result.resumeVersion, report.effort);
-    return result;
-  });
+export async function reportEffortObserved(agentId: string, report: EffortReport, now = Date.now()): Promise<EffortObservation> {
+  const { observed, continuation } = await getGateway().write("agents.observeEffort", { agentId, ...report, now }) as unknown as ReturnType<typeof observeEffortBody>;
   if (observed.outcome === "applied") {
     const command: Command | null = observed.commandId ? getCommand(observed.commandId) : null;
     if (command) emitCommandEvent(command, "command.succeeded");

package/src/services/agent-hang-watchdog-job.ts

@@ -386,7 +386,7 @@ async function deliverSelfCheck(agent: AgentCard, decision: AgentHangDecision, c
     },
   });
 
-  const messages = routeNotification({
+  const messages = await routeNotification({
     type: "agent.self_check",
     scope: { agentId: agent.id, parent: agent.spawnedBy, teamId: agent.teamId },
     // Explicit, though the registered `subject-agent` rule resolves the same single recipient: the
@@ -457,7 +457,7 @@ async function escalate(
 
   // Reuse the `agent.stuck_busy` notice shape (type, spawn-parent audience, `payload.kind`) so every
   // existing coordinator-side consumer renders it with no new case to handle.
-  const messages = routeNotification({
+  const messages = await routeNotification({
     type: "agent.stuck_busy",
     scope: { agentId: agent.id, parent: agent.spawnedBy, teamId: agent.teamId },
     message: {

package/src/services/agent-heartbeat.ts

@@ -0,0 +1,166 @@
+// The agent liveness exchange (#3606/#3608/#3618): one service behind POST /api/agents/:id/heartbeat
+// and the bus `agent.heartbeat` command frame, so both transports apply status, readiness, the
+// unread inbox and the quota piggyback identically. Transports parse and authorize at their edge.
+import { isRecord, type HeartbeatResult, type ProviderQuotaUpdateInput } from "@humwick/sdk";
+import { ValidationError, getAgent, markReadyAsync, recordHeartbeatAsync, setStatusAsync, validateAgentSession } from "../db";
+import { isAgentUnavailable } from "../db/agent-predicates";
+import type { ViewerScope } from "../db/viewer-scope";
+import { emitAgentStatus } from "../agent-status-events";
+import { VALID_AGENT_STATUSES, agentSessionStatus, auditEvent } from "../routes/_shared";
+import { pollAgentMessages } from "../routes/messages";
+import { cleanProviderQuotaUpdate } from "../routes/provider-quotas";
+import { publishHeartbeatQuota } from "../routes/agent-heartbeat-quota";
+import { announceSpawnedAgentReady } from "./register-agent";
+import { flushQueuedDirectMessages } from "./managed-running";
+import { acquireTeamOnReady } from "./team";
+import { isComponentAuthorizedFor } from "../security";
+import type { AgentCard, AgentSessionGuard, ComponentToken } from "../types";
+
+type AgentStatusValue = (typeof VALID_AGENT_STATUSES)[number];
+
+export interface AgentHeartbeatReport {
+  status?: AgentStatusValue;
+  ready?: boolean;
+  unread?: boolean;
+  providerQuota?: ProviderQuotaUpdateInput;
+  quotaLeaseToken?: string;
+}
+
+export type AgentHeartbeatOutcome = { ok: true; result: HeartbeatResult } | { ok: false; error: string; status: number };
+
+type AgentActivityState = {
+  key: "available" | "busy" | "not-ready" | "offline";
+  title: string;
+  icon: string;
+};
+
+function agentActivityState(agent?: Pick<AgentCard, "ready" | "status"> | null): AgentActivityState | null {
+  if (!agent) return null;
+  if (agent.status === "offline") return { key: "offline", title: "Agent offline", icon: "ti-plug-off" };
+  if (!agent.ready) return { key: "not-ready", title: "Agent not ready", icon: "ti-loader" };
+  if (agent.status === "busy") return { key: "busy", title: "Agent busy", icon: "ti-activity" };
+  return { key: "available", title: "Agent available", icon: "ti-circle-check" };
+}
+
+async function auditAgentStateTransition(agentId: string, before: AgentCard | null | undefined, after: AgentCard | null | undefined): Promise<void> {
+  const previous = agentActivityState(before);
+  const next = agentActivityState(after);
+  if (!next || previous?.key === next.key) return;
+  await auditEvent({
+    clientId: "server-agent-" + agentId + "-state-" + next.key + "-" + Date.now(),
+    kind: "state",
+    title: next.title,
+    meta: agentId,
+    icon: next.icon,
+    view: "agents",
+    agentId,
+  });
+}
+
+export function cleanAgentStatus(value: unknown): AgentStatusValue {
+  if (!VALID_AGENT_STATUSES.includes(value as AgentStatusValue)) throw new ValidationError(`status must be one of: ${VALID_AGENT_STATUSES.join(", ")}`);
+  return value as AgentStatusValue;
+}
+
+/** Validates a wire heartbeat body; throws ValidationError. `sourceAgentId` is always the reporting agent. */
+export function cleanHeartbeatReport(agentId: string, body: unknown): AgentHeartbeatReport {
+  const raw = isRecord(body) ? body : {};
+  if (raw.ready !== undefined && typeof raw.ready !== "boolean") throw new ValidationError("ready must be a boolean");
+  if (raw.unread !== undefined && typeof raw.unread !== "boolean") throw new ValidationError("unread must be a boolean");
+  const quota = raw.providerQuota === undefined ? undefined : cleanProviderQuotaUpdate(raw.providerQuota);
+  if (typeof quota === "string") throw new ValidationError(quota);
+  if (quota) quota.sourceAgentId = agentId;
+  return {
+    ...(raw.status === undefined ? {} : { status: cleanAgentStatus(raw.status) }),
+    ...(raw.ready === undefined ? {} : { ready: raw.ready }),
+    ...(raw.unread ? { unread: true } : {}),
+    ...(quota ? { providerQuota: quota } : {}),
+    ...(typeof raw.quotaLeaseToken === "string" ? { quotaLeaseToken: raw.quotaLeaseToken } : {}),
+  };
+}
+
+// #3606 — a reported status/readiness equal to the live card is a liveness tick, not a transition: no
+// row write, no agent.status event. Presence still advances through the coalescing heartbeat buffer,
+// except for a terminal row, which a beat would resurrect.
+export async function noteUnchangedLifecycle(agentId: string, current: AgentCard, guard: AgentSessionGuard | undefined): Promise<void> {
+  if (current.status !== "offline" && current.status !== "stale") await recordHeartbeatAsync(agentId, { guard });
+}
+
+export async function applyAgentStatus(agentId: string, status: AgentStatusValue, guard: AgentSessionGuard | undefined, before: AgentCard | null): Promise<boolean> {
+  // #1895 (S3.2 L10, review finding 3) — routed through the async gateway facade.
+  if (!(await setStatusAsync(agentId, status, guard))) return false;
+  await auditAgentStateTransition(agentId, before, getAgent(agentId));
+  await emitAgentStatus(agentId);
+  return true;
+}
+
+export async function applyAgentReady(agentId: string, ready: boolean, guard: AgentSessionGuard | undefined, before: AgentCard | null): Promise<boolean> {
+  // #1895 (S3.2 L10, review finding 3) — routed through the async gateway facade.
+  if (!(await markReadyAsync(agentId, ready, guard))) return false;
+  await auditAgentStateTransition(agentId, before, getAgent(agentId));
+  // #308/#2432 — a spawned child's false→true ready wakes its parent (announceSpawnedAgentReady dedups).
+  // #1927 — the awaited audit lets a same-instance PATCH flip ready back first, so re-read the live
+  // card and session guard before firing, never the pre-audit snapshot.
+  if (ready && !before?.ready) {
+    const live = getAgent(agentId);
+    const stillCurrentInstance = validateAgentSession(agentId, guard).ok;
+    if (live?.ready === true && stillCurrentInstance) {
+      await announceSpawnedAgentReady(agentId, "agent-ready");
+      (await acquireTeamOnReady(agentId)); // #3107 — before the flush, so seat mail reaches a new holder
+      // #416 — also flush queued direct messages: a not-ready agent that becomes ready
+      // may have queued messages waiting (e.g. starting up, clearing context).
+      (await flushQueuedDirectMessages(agentId));
+    }
+  }
+  await emitAgentStatus(agentId);
+  return true;
+}
+
+/** One liveness tick. Only a value that differs from the live card takes the transition path; the rest is a coalesced beat. */
+export async function applyAgentHeartbeat(agentId: string, report: AgentHeartbeatReport, guard: AgentSessionGuard | undefined, viewer: ViewerScope | null): Promise<AgentHeartbeatOutcome> {
+  const session = validateAgentSession(agentId, guard);
+  if (!session.ok) return { ok: false, error: session.error!, status: agentSessionStatus(session.error) };
+  // #416 — capture unavailability before heartbeat to detect the transition.
+  const beforeHeartbeat = getAgent(agentId);
+  if (beforeHeartbeat?.kind === "channel" && !beforeHeartbeat.ready) return { ok: false, error: "channel agent not ready; re-register required", status: 409 };
+  const notFound = { ok: false, error: "agent not found", status: 404 } as const;
+  const wasUnavailable = beforeHeartbeat ? isAgentUnavailable(beforeHeartbeat) : false;
+  let current = beforeHeartbeat;
+  const { status, ready } = report;
+  if (status !== undefined && status !== current?.status) {
+    if (!(await applyAgentStatus(agentId, status, guard, current))) return notFound;
+    current = getAgent(agentId);
+  }
+  if (ready !== undefined && ready !== current?.ready) {
+    if (!(await applyAgentReady(agentId, ready, guard, current))) return notFound;
+  }
+  // A reported terminal status must not be undone by the beat's offline/stale resurrection.
+  if (status !== "offline" && status !== "stale") {
+    // #1468 — route the API heartbeat through the same coalescing buffer as the bus path.
+    if (!(await recordHeartbeatAsync(agentId, { guard }))) return notFound;
+  }
+  if (wasUnavailable) {
+    const after = getAgent(agentId);
+    if (after && !isAgentUnavailable(after)) (await flushQueuedDirectMessages(agentId));
+  }
+  const result: HeartbeatResult = { ok: true };
+  if (report.unread) result.messages = await pollAgentMessages(viewer, { for: agentId, unread: true, limit: 100, turnDelivery: true });
+  if (report.providerQuota) {
+    try { result.providerQuota = await publishHeartbeatQuota(report.providerQuota, report.quotaLeaseToken); }
+    catch (error) { console.warn(`heartbeat quota publish failed for ${agentId}:`, error); }
+  }
+  return { ok: true, result };
+}
+
+/** #3618 — the bus `agent.heartbeat` frame. A socket reports only for the agent it registered as,
+ *  under that registration's session guard and the scopes its upgrade credential carries. */
+export async function heartbeatFromBus(conn: { agentId?: string; instanceId: string; epoch: number; componentAuth?: ComponentToken }, target: string, params: Record<string, unknown>): Promise<{ status: "succeeded" | "failed" | "rejected"; result?: Record<string, unknown>; error?: string }> {
+  if (!conn.agentId || target !== conn.agentId) return { status: "rejected", error: "agent.heartbeat reports only for the registered agent" };
+  let report: AgentHeartbeatReport;
+  try { report = cleanHeartbeatReport(conn.agentId, params); }
+  catch (error) { if (error instanceof ValidationError) return { status: "failed", error: error.message }; throw error; }
+  const denied = (scope: string) => conn.componentAuth && !isComponentAuthorizedFor(conn.componentAuth, { scope, resource: { agentId: conn.agentId, target: conn.agentId } });
+  if ((report.unread && denied("message:read")) || (report.providerQuota && denied("quota:write"))) return { status: "rejected", error: "component token lacks heartbeat scope" };
+  const outcome = await applyAgentHeartbeat(conn.agentId, report, { instanceId: conn.instanceId, epoch: conn.epoch }, null);
+  return outcome.ok ? { status: "succeeded", result: outcome.result as unknown as Record<string, unknown> } : { status: "failed", error: outcome.error };
+}

package/src/services/agent-reporting.ts

@@ -10,7 +10,7 @@ export async function setAgentReportVerbosity(input: {
   requestedVia: "http" | "mcp";
   reason?: string;
 }, ctx: AuthContext): Promise<{ action: "reportVerbosity"; reportVerbosity: ReportVerbosity }> {
-  authorizeShutdown(ctx, { agentId: input.agentId, requestedVia: input.requestedVia });
+  (await authorizeShutdown(ctx, { agentId: input.agentId, requestedVia: input.requestedVia }));
   const agent = getAgent(input.agentId);
   if (!agent) throw new ShutdownTargetError("agent not found");
   if (!isReportVerbosity(input.reportVerbosity)) throw new ValidationError("reportVerbosity must be off, quiet, normal or verbose");

package/src/services/browser-inventory.ts

@@ -34,7 +34,7 @@ export async function reconcileBrowserInventory(orchestratorId: string, inventor
   const live = new Set(inventory.liveSessionIds);
   const closed = new Set(inventory.closedSessionIds);
   for (const row of listBrowserSessionRows({ orchestratorId, activeOnly: true, limit: 1000 })) {
-    if (getAgent(row.agentId)?.status === "offline") reapAgentBrowserSessions(row.agentId);
+    if (getAgent(row.agentId)?.status === "offline") (await reapAgentBrowserSessions(row.agentId));
     const idleMs = inventory.idleMs?.[row.id];
     if (idleMs !== undefined) noteBrowserActivity(row, idleMs, Date.now());
     if (live.has(row.id) || (!registration && !closed.has(row.id))) continue;
@@ -44,9 +44,9 @@ export async function reconcileBrowserInventory(orchestratorId: string, inventor
       if (command?.status === "pending") continue;
     }
     const now = Date.now();
-    transitionAndEmit(row.id, [row.status], {
+    (await transitionAndEmit(row.id, [row.status], {
       status: row.status === "stopping" || closed.has(row.id) ? "stopped" : "failed", stoppedAt: now,
       error: registration ? "browser absent from orchestrator registration" : "browser process ended on host",
-    }, now);
+    }, now));
   }
 }

package/src/services/browser-session-state.ts

@@ -1,3 +1,4 @@
+import { getGateway } from "../db/gateway";
 // #3489 H4 — the one write path for browser session rows after insert: every change is pushed as
 // `browser.session.<status>`, so the dashboard follows starts, stops, idle expiry and crashes without polling.
 import type { BrowserSession, BrowserSessionStatus } from "@humwick/sdk";
@@ -26,8 +27,8 @@ export function emitBrowserSession(row: BrowserSessionRow): void {
 }
 
 /** Applies a guarded transition and announces it; undefined when the row already left `from`. */
-export function transitionAndEmit(id: string, from: readonly BrowserSessionStatus[], patch: BrowserSessionPatch, now: number): BrowserSessionRow | undefined {
-  const row = transitionBrowserSession(id, from, patch, now);
+export async function transitionAndEmit(id: string, from: readonly BrowserSessionStatus[], patch: BrowserSessionPatch, now: number): Promise<BrowserSessionRow | undefined> {
+  const row = await getGateway().write("browser.transition", [id, from, patch, now]) as unknown as BrowserSessionRow | undefined;
   if (!row) return undefined;
   if (row.status === "running") lastActivity.set(row.id, lastActivity.get(row.id) ?? now);
   else if (row.status === "stopped" || row.status === "failed") lastActivity.delete(row.id);

package/src/services/browser-session.ts

@@ -1,3 +1,5 @@
+import { getGateway } from "../db/gateway";
+import type { startBrowserBody, stopBrowserBody } from "../db/browser-session-write";
 // #3489 — Relay-managed browser sessions. The server owns identity, limits and lifecycle state; the agent's own
 // orchestrator owns the Chromium process and executes `browser.start` / `browser.stop` from the command bus.
 // Command results are folded into the row as they arrive (and again on read, which also settles a missed event).
@@ -6,14 +8,14 @@ import { isRecord, stringValue, type BrowserLimits, type BrowserSession } from "
 import { getBrowserLimits } from "../browser-config";
 import { canAccessBrowserSession, type BrowserCaller } from "../browser-authz";
 import { emitCommandEvent } from "../command-events";
-import { createCommandInternal } from "../commands-db";
+
 import { subscribeRelayEvents } from "../events";
 import type { Command } from "../types";
 import { getCommandAsync } from "../commands-write";
 import { getAgentProfile } from "../config-store";
 import { getAgent, getOrchestrator } from "../db";
 import {
-  countActiveBrowserSessions, getBrowserSessionRow, insertBrowserSession, listBrowserSessionRows, type BrowserSessionRow,
+  getBrowserSessionRow, listBrowserSessionRows, type BrowserSessionRow,
 } from "../db/browser-sessions";
 import { getLaunchFact } from "../db/launch-facts";
 import { generationLaunchParams } from "../db/generation-launch";
@@ -67,17 +69,13 @@ export async function startBrowserSession(caller: BrowserCaller, input: { agentI
   const limits = getBrowserLimits();
   // Settle finished stops first, so a reaped session stops counting against the limits.
   for (const row of [...listBrowserSessionRows({ agentId, activeOnly: true, limit: 100 }), ...listBrowserSessionRows({ orchestratorId: host.id, activeOnly: true, limit: 100 })]) await reconcile(row);
-  // Count and insert run in one synchronous stretch, so two concurrent starts cannot both pass the cap.
-  if (countActiveBrowserSessions({ agentId }) >= limits.perAgent) {
-    throw new BrowserSessionError(`agent ${agentId} already has ${limits.perAgent} browser session(s) (limit from settings browser/default)`, 409);
-  }
-  if (countActiveBrowserSessions({ orchestratorId: host.id }) >= limits.perHost) {
-    throw new BrowserSessionError(`host ${host.id} already runs ${limits.perHost} browser session(s) (limit from settings browser/default)`, 409);
-  }
   const id = randomUUID();
-  const command = createCommandInternal({ id: randomUUID(), input: { type: "browser.start", source: agentId, target: host.agentId, correlationId: id,
-    params: { sessionId: id, agentId, orchestratorId: host.id, idleTimeoutMs: limits.idleTimeoutMinutes * 60_000, hostSessionLimit: limits.perHost } } });
-  emitBrowserSession(insertBrowserSession({ id, agentId, orchestratorId: host.id, startCommandId: command.id, now: Date.now() }));
+  const result = await getGateway().write("browser.start", { id, commandId: randomUUID(), agentId, instanceId: agent.instanceId, epoch: agent.epoch, orchestratorId: host.id, limits }, { idempotencyKey: id }) as unknown as ReturnType<typeof startBrowserBody>;
+  if (result.conflict === "agentLimit") throw new BrowserSessionError(`agent ${agentId} already has ${limits.perAgent} browser session(s) (limit from settings browser/default)`, 409);
+  if (result.conflict === "hostLimit") throw new BrowserSessionError(`host ${host.id} already runs ${limits.perHost} browser session(s) (limit from settings browser/default)`, 409);
+  if (result.conflict) throw new BrowserSessionError("browser session target changed during admission", 409);
+  const { command, row } = result;
+  emitBrowserSession(row);
   emitCommandEvent(command, "command.requested");
   return { session: publicView(await settle(id, signal)), limits };
 }
@@ -92,16 +90,16 @@ async function reconcile(row: BrowserSessionRow): Promise<BrowserSessionRow> {
     const patch = command.status === "succeeded"
       ? { status: "running" as const, cdpUrl: stringValue(result.cdpUrl), pid: typeof result.pid === "number" ? result.pid : undefined, profileDir: stringValue(result.profileDir) }
       : { status: "failed" as const, error: command.error ?? `browser.start ${command.status}`, stoppedAt: now };
-    return transitionAndEmit(row.id, ["starting"], patch, now) ?? getBrowserSessionRow(row.id)!;
+    return (await transitionAndEmit(row.id, ["starting"], patch, now)) ?? getBrowserSessionRow(row.id)!;
   }
   if (row.status === "stopping" && row.stopCommandId) {
     const command = await getCommandAsync(row.stopCommandId);
     if (!command || !isTerminalCommandStatus(command.status)) {
       if (now - row.updatedAt < SETTLE_TIMEOUT_MS) return row;
-      return transitionAndEmit(row.id, ["stopping"], { status: "failed", stoppedAt: now, error: "browser stop did not settle" }, now) ?? row;
+      return (await transitionAndEmit(row.id, ["stopping"], { status: "failed", stoppedAt: now, error: "browser stop did not settle" }, now)) ?? row;
     }
     const error = command.status === "succeeded" ? undefined : command.error ?? `browser.stop ${command.status}`;
-    return transitionAndEmit(row.id, ["stopping"], { status: "stopped", stoppedAt: now, ...(error ? { error } : {}) }, now) ?? getBrowserSessionRow(row.id)!;
+    return (await transitionAndEmit(row.id, ["stopping"], { status: "stopped", stoppedAt: now, ...(error ? { error } : {}) }, now)) ?? getBrowserSessionRow(row.id)!;
   }
   return row;
 }
@@ -133,27 +131,23 @@ export async function listBrowserSessions(caller: BrowserCaller, filter: { agent
 }
 
 /** Issue `browser.stop`; idempotent for a session that is already stopping or over. */
-function requestStop(row: BrowserSessionRow, reason: string): BrowserSessionRow {
+async function requestStop(row: BrowserSessionRow, reason: string): Promise<BrowserSessionRow> {
   if (row.status !== "starting" && row.status !== "running") return row;
-  const host = getOrchestrator(row.orchestratorId);
-  const now = Date.now();
-  if (!host) return transitionAndEmit(row.id, ["starting", "running"], { status: "stopped", stoppedAt: now, error: "orchestrator no longer registered" }, now) ?? row;
-  const command = createCommandInternal({ id: randomUUID(), input: { type: "browser.stop", source: "system", target: host.agentId, correlationId: row.id,
-    params: { sessionId: row.id, agentId: row.agentId, orchestratorId: host.id, reason } } });
-  const stopping = transitionAndEmit(row.id, ["starting", "running"], { status: "stopping", stopCommandId: command.id }, now);
-  emitCommandEvent(command, "command.requested");
-  return stopping ?? getBrowserSessionRow(row.id)!;
+  const result = await getGateway().write("browser.stop", { id: row.id, reason, commandId: randomUUID() }, { idempotencyKey: row.id }) as unknown as ReturnType<typeof stopBrowserBody>;
+  if (result.row) emitBrowserSession(result.row);
+  if (result.command) emitCommandEvent(result.command, "command.requested");
+  return result.row ?? row;
 }
 
 export async function stopBrowserSession(caller: BrowserCaller, id: string, signal?: AbortSignal): Promise<BrowserSession> {
-  const row = requestStop(await reconcile(accessible(caller, id)), "requested");
+  const row = await requestStop(await reconcile(accessible(caller, id)), "requested");
   return publicView(row.status === "stopping" ? await settle(id, signal) : row);
 }
 
 /** Agent exit: every live session of the agent is stopped with it. Synchronous; the commands settle later. */
-export function reapAgentBrowserSessions(agentId: string): number {
+export async function reapAgentBrowserSessions(agentId: string): Promise<number> {
   const live = listBrowserSessionRows({ agentId, activeOnly: true, limit: 100 }).filter((row) => row.status !== "stopping");
-  for (const row of live) requestStop(row, "agent-exit");
+  for (const row of live) await requestStop(row, "agent-exit");
   return live.length;
 }