@humwick/server 0.130.1 → 0.130.3

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;
 }
 

package/src/services/bus-command-update.ts

@@ -51,23 +51,23 @@ export async function updateCommandFromBus(input: {
       await settleScheduledCommandTimer(updated);
     }
     emitCommandEvent(updated, `command.${updated.status}`);
-    settleSelfResumeContinuationIngestion(updated);
+    (await settleSelfResumeContinuationIngestion(updated));
     noteCompactionCommandCompleted(updated);
     // #2095 — durable "clear committed vs no-op" signal, fired on terminal compact/clear commands.
     noteCompactionResult(updated);
-    enqueueContinuationInjectionAfterSelfResume(updated);
-    enqueueLifecycleIdentityInjectionAfterContextCommand(updated);
-    notifySelfResumeNoOp(updated);
-    settleContextResetCarry(updated);
-    settleSelfRestartManagedState(updated);
-    settleInterruptRedirectMessage(updated);
+    (await enqueueContinuationInjectionAfterSelfResume(updated));
+    (await enqueueLifecycleIdentityInjectionAfterContextCommand(updated));
+    await notifySelfResumeNoOp(updated);
+    (await settleContextResetCarry(updated));
+    (await settleSelfRestartManagedState(updated));
+    (await settleInterruptRedirectMessage(updated));
     // #1565 P4b — memory rides BESIDE the continuation as its own payload (§7), delta-gated on
     // compact. Ordered LAST and contained (#1565 F8) — see the same call in routes/commands.ts.
-    settleMemoryInjectionAfterContextCommand(updated);
+    (await settleMemoryInjectionAfterContextCommand(updated));
     // #1951 — the startup context (validation commands, report-up, profile charter, caller context)
     // rides beside them too, recomposed from the DB and delta-gated on compact. Contained the same
     // way: a compose throw here must not abort the settle chain.
-    settleStartupContextInjectionAfterContextCommand(updated);
+    (await settleStartupContextInjectionAfterContextCommand(updated));
   }
   return { status: "succeeded", result: updated ? { command: updated } : undefined };
 }

package/src/services/checkout-refresh-state.ts

@@ -6,6 +6,7 @@ export function checkoutRefreshHealth(row: CheckoutRefreshStatus, now = Date.now
   if (!row.result?.enabled) return undefined;
   if (["pending", "accepted", "running"].includes(row.status) && row.result.status === "waiting") return "waiting";
   if (row.result.reason) return "blocked";
+  if (row.status === "succeeded" && ["current", "refreshed"].includes(row.result.status)) return "healthy";
   return !row.result.successAt || now - row.result.successAt > 180_000 ? "stale" : "healthy";
 }
 

package/src/services/checkout-refresh.test-fixture.ts

@@ -1,12 +1,13 @@
 import { createCommand, updateCommand } from "../commands-db";
 
 /** Record a host checkout's latest refresh receipt, as the executor reports a finished attempt. */
-export function recordRefreshReceipt(projectId: string, orchestratorId: string, rootPath: string, outcome: "hook-failed" | "current" | "behind" | "refreshing"): void {
+export function recordRefreshReceipt(projectId: string, orchestratorId: string, rootPath: string, outcome: "hook-failed" | "current" | "behind" | "refreshing" | "busy"): void {
   const command = createCommand({ type: "project.checkout.refresh", source: "system", target: `orchestrator-${orchestratorId}`,
     params: { projectId, rootPath, orchestratorId, remoteUrl: "https://example.invalid/repo.git", enabled: true } });
-  const dependency = { fingerprint: "inputs", attemptId: "attempt", status: outcome === "hook-failed" || outcome === "refreshing" ? "pending" : "current" };
+  const dependency = { fingerprint: "inputs", attemptId: "attempt", status: outcome === "hook-failed" || outcome === "refreshing" || outcome === "busy" ? "pending" : "current" };
   updateCommand(command.id, { status: outcome === "refreshing" ? "running" : "succeeded", result: { rootPath, enabled: true, attemptedAt: Date.now(), backups: [], headSha: "head", dependency,
     ...(outcome === "hook-failed" ? { status: "error", reason: "dependency hook failed: npm ci exited 1" }
+      : outcome === "busy" ? { status: "skipped", reason: "host gate admission busy; retry next refresh cycle" }
       : outcome === "behind" ? { status: "skipped", behind: 3, reason: "fetch failed" }
       : outcome === "refreshing" ? { status: "refreshing" } : { status: "current", successAt: Date.now() }) } });
 }

package/src/services/command-host.ts

@@ -2,11 +2,14 @@ import { stringValue } from "@humwick/sdk";
 import type { Orchestrator } from "@humwick/sdk";
 import { getAgent, listOrchestrators, ValidationError } from "../db";
 import type { AuthContext } from "./auth-context";
+import { listManagedOrchestratorsForAgent } from "../orchestrator-lookup";
 import { isPathWithinBase, sameHostIdentity } from "../utils";
 
 /** The orchestrator the caller agent is registered on, online or not: its stamped
- * `meta.orchestratorId`, else its `machine` matched by host identity (the runner's raw os.hostname()
- * differs in case/separators). */
+ * `meta.orchestratorId`, else the one host whose managed-agent roster runs it, else its `machine`
+ * matched by host identity (the runner's raw os.hostname() differs in case/separators). The roster
+ * covers unpinned system launches (stewards, managed policies) on a host whose OS hostname is not
+ * its orchestrator name, e.g. WSL "XPS15" on xps15-wsl (#3822). */
 function callerHost(ctx: AuthContext, hosts: Orchestrator[]): Orchestrator | undefined {
   const agent = ctx.callerAgentId ? getAgent(ctx.callerAgentId) : undefined;
   if (!agent) return undefined;
@@ -15,6 +18,8 @@ function callerHost(ctx: AuthContext, hosts: Orchestrator[]): Orchestrator | und
     const byId = hosts.find((item) => item.id === stamped);
     if (byId) return byId;
   }
+  const rostered = listManagedOrchestratorsForAgent({ agentId: agent.id });
+  if (rostered.length === 1) return rostered[0];
   if (!agent.machine) return undefined;
   return hosts.find((item) => sameHostIdentity(item.hostname, agent.machine) || sameHostIdentity(item.id, agent.machine));
 }

package/src/services/coordinator-digest.ts

@@ -1,3 +1,4 @@
+import { framed } from "../hub-metrics";
 import { errMessage } from "@humwick/sdk";
 import { flushCoordinatorDigestsAsync } from "../db/coordinator-digest-async";
 import { emitNewMessages } from "../sse";
@@ -18,11 +19,11 @@ export function startCoordinatorDigestLoop(): () => Promise<void> {
   let stopped = false;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let pending: Promise<void>;
-  const tick = async () => {
+  const tick = framed("timer coordinator-digest", async () => {
     try { await flushCoordinatorDigests(); }
     catch (error) { console.error(`coordinator digest flush failed: ${errMessage(error)}`); }
     finally { if (!stopped) timer = setTimeout(() => { pending = tick(); }, 1000).unref(); }
-  };
+  });
   pending = tick();
   const stop = () => { stopped = true; clearTimeout(timer); removeShutdownHook(); return pending; };
   const removeShutdownHook = onShutdown("coordinator-digest", stop);

package/src/services/dispatch-command.ts

@@ -1,6 +1,7 @@
+import { createCommandAsync, createKernelCommandIfAbsentAsync } from "../commands-write";
 import { writeChildEnv } from "@humwick/sdk/env";
 import { rejectCallerSealedEnv } from "../spawn-env";
-import { commandSecretMaskValues } from "../command-secrets";
+import { commandSecretMaskValues, omitCommandFenceSecrets, redactCommandSecrets, revealCommandSecrets } from "../command-secrets";
 import { spawnDelegationState } from "../db/spawn-delegation-state";
 import { authorizeShutdown } from "./shutdown-agent";
 import { stewardGenerationCanceled } from "../db/workspace-steward-fence";
@@ -17,11 +18,9 @@ import { stewardGenerationCanceled } from "../db/workspace-steward-fence";
 // owned by the spawn (#349) / shutdown (#347) slices — they are NOT generic dispatch and stay
 // out of this service.
 import { isRecord, stringValue, ValidationError } from "@humwick/sdk";
-import { createCommand } from "../commands-db";
-import { createCommandAsync, createKernelCommandIfAbsentAsync } from "../commands-write";
+
 import { emitCommandEvent } from "../command-events";
 import { componentConstraintsAllow, hasComponentScope, isComponentAuthorizedFor, isOpenApprovalConstraints } from "../security";
-import { omitCommandFenceSecrets, redactCommandSecrets, revealCommandSecrets } from "../command-secrets";
 import { listOrchestrators } from "../db";
 import { ServiceAuthError } from "./errors";
 import type { AuthContext } from "./auth-context";
@@ -211,10 +210,10 @@ function assertPathAxesWithinConstraint(input: CreateCommandInput, component: Co
  * scope gate at the transport edge — HTTP middleware `isScopedRequestAuthorized`, bus
  * `withRegistered`). HTTP `authorizeRoute` and bus `busCommandAuthorized` both reduce to this:
  * "no component token ⇒ allow; else `isComponentAuthorizedFor(command:write, resource)`". */
-function assertCommandAuthorized(ctx: AuthContext, input: CreateCommandInput, schedulerFire = false): void {
+async function assertCommandAuthorized(ctx: AuthContext, input: CreateCommandInput, schedulerFire = false): Promise<void> {
   if (ctx.callerAgentId && spawnDelegationState(ctx.callerAgentId).participating) {
     if (input.type === "agent.spawn") throw new ValidationError("agent.spawn requires the spawn service to preserve delegated lineage");
-    if (input.type === "agent.shutdown") authorizeShutdown(ctx, { agentId: stringValue(input.params?.agentId), spawnRequestId: stringValue(input.params?.spawnRequestId), requestedVia: "bus" });
+    if (input.type === "agent.shutdown") (await authorizeShutdown(ctx, { agentId: stringValue(input.params?.agentId), spawnRequestId: stringValue(input.params?.spawnRequestId), requestedVia: "bus" }));
   }
   if (ctx.callerAgentId && stewardGenerationCanceled(ctx.callerAgentId, ctx.constraints?.spawnRequestIds?.[0])) {
     throw new ServiceAuthError("steward job canceled by land withdrawal; host mutations are fenced");
@@ -304,9 +303,9 @@ export function serializeCommandForRead(command: Command, ctx: AuthContext): Com
 }
 
 /** Dispatch options. `allowReservedCorrelation` threads the R2 (#1409) kernel-correlation opt-in to
- *  `createCommand` — set ONLY by the kernel command bridge, whose `correlation_id` is a legitimately
+ *  `createCommandAsync` — set ONLY by the kernel command bridge, whose `correlation_id` is a legitimately
  *  `kcmd:`-namespaced dedup key. Every other (external) `dispatchCommand` caller omits it, so the
- *  reservation stays enforced at the `createCommand` choke point. */
+ *  reservation stays enforced at the `createCommandAsync` choke point. */
 export interface DispatchCommandOptions {
   readonly allowReservedCorrelation?: boolean;
   /** #2392 — INTERNAL ONLY. Set exclusively by the two scheduler FIRE paths
@@ -340,10 +339,10 @@ function withServerCommandProvenance(input: CreateCommandInput, options: Dispatc
   };
 }
 
-export function dispatchCommand(input: CreateCommandInput, ctx: AuthContext, options: DispatchCommandOptions = {}): Command {
+export async function dispatchCommand(input: CreateCommandInput, ctx: AuthContext, options: DispatchCommandOptions = {}): Promise<Command> {
   const sanitizedInput = withServerCommandProvenance(input, options);
-  assertCommandAuthorized(ctx, sanitizedInput, options.schedulerFire === true);
-  const command = createCommand(sanitizedInput, { allowReservedCorrelation: options.allowReservedCorrelation === true });
+  (await assertCommandAuthorized(ctx, sanitizedInput, options.schedulerFire === true));
+  const command = (await createCommandAsync(sanitizedInput, { allowReservedCorrelation: options.allowReservedCorrelation === true }));
   // A freshly created command is always `pending`; emit the literal "command.requested"
   // (the relay auto-fans-out the follow-up "command.dispatched"). HTTP used the status-derived
   // `emitCommand`, bus used `emitCommandEvent(_, "command.requested")` — identical for pending.
@@ -359,7 +358,7 @@ export async function dispatchCommandAsync(
   options: DispatchCommandOptions = {},
 ): Promise<Command> {
   const sanitizedInput = withServerCommandProvenance(input, options);
-  assertCommandAuthorized(ctx, sanitizedInput, options.schedulerFire === true);
+  (await assertCommandAuthorized(ctx, sanitizedInput, options.schedulerFire === true));
   const command = await createCommandAsync(sanitizedInput, {
     allowReservedCorrelation: options.allowReservedCorrelation === true,
   }, ctx.callerAgentId ?? ctx.actor.id, ctx.constraints?.projectId);
@@ -381,7 +380,7 @@ export async function dispatchKernelCommandAsync(
   options: Pick<DispatchCommandOptions, "schedulerFire" | "schedulerRequestedVia"> = {},
 ): Promise<Command> {
   const sanitizedInput = withServerCommandProvenance(input, options);
-  assertCommandAuthorized(ctx, sanitizedInput, options.schedulerFire === true);
+  (await assertCommandAuthorized(ctx, sanitizedInput, options.schedulerFire === true));
   const { command, created } = await createKernelCommandIfAbsentAsync(sanitizedInput, ctx.callerAgentId ?? ctx.actor.id, ctx.constraints?.projectId);
   if (created) emitCommandEvent(command, "command.requested");
   return command;