@humwick/server 0.130.2 → 0.130.4

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

package/src/db/agent-effort-observe.ts

@@ -0,0 +1,22 @@
+import { validateAgentSession } from "./agents";
+import { recordEffortObservedInternal } from "./agent-effort-state";
+import { findMessageByIdempotencyKey, sendMessageWithResultInternal } from "./messages";
+export class EffortReportFenced extends Error {}
+/** #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.`;
+}
+
+
+export function observeEffortBody(input: Parameters<typeof recordEffortObservedInternal>[0]) {
+  const session = validateAgentSession(input.agentId, { instanceId: input.instanceId });
+  if (!session.ok) throw new EffortReportFenced(session.error ?? "stale agent instance");
+  const observed = recordEffortObservedInternal(input);
+  const version = observed.outcome !== "stale" ? observed.resumeVersion : undefined;
+  const key = `effort-continuation:${input.agentId}:${version}`;
+  const continuation = version !== undefined && !findMessageByIdempotencyKey("system", key)
+    ? sendMessageWithResultInternal({ from: "system", to: input.agentId, kind: "system", subject: "Effort changed",
+      body: selfEffortContinuation(input.effort), replyExpected: false, idempotencyKey: key,
+      payload: { kind: "agent.effort_continuation", agentId: input.agentId, effortVersion: version, effort: input.effort } }, false, {}, input.now).message : null;
+  return { observed, continuation };
+}

package/src/db/agent-meta.ts

@@ -5,6 +5,8 @@
 import { isRecord } from "@humwick/sdk";
 
 export const AGENT_META_WARN_BYTES = 64 * 1024;
+export const PROFILE_PROJECTION_WARN_BYTES = 192 * 1024;
+export const COMMAND_PROFILE_WARN_BYTES = 1024 * 1024;
 
 // Log dedupe only, so a per-thread copy is correct: the writer thread warns once itself (#1870 S6c).
 const warnedOversizeMeta = new Set<string>();
@@ -62,13 +64,22 @@ export function jsonBytes(value: string): number {
 
 /** Runtime tripwire: one warning per agent/source until the payload returns below the ceiling. */
 export function warnIfAgentMetaOversized(agentId: string, json: string, source: string): void {
-  const key = `${agentId}:${source}`;
+  warnIfOversized(`${agentId}:${source}`, json, AGENT_META_WARN_BYTES, `[agent-meta] ${agentId} ${source}`);
+}
+
+export function warnIfOversized(key: string, json: string, threshold: number, label: string): void {
   const bytes = jsonBytes(json);
-  if (bytes <= AGENT_META_WARN_BYTES) {
+  if (bytes <= threshold) {
     warnedOversizeMeta.delete(key);
     return;
   }
   if (warnedOversizeMeta.has(key)) return;
   warnedOversizeMeta.add(key);
-  console.warn(`[agent-meta] ${agentId} ${source} is ${bytes} bytes (alarm threshold ${AGENT_META_WARN_BYTES})`);
+  console.warn(`${label} is ${bytes} bytes (alarm threshold ${threshold})`);
+}
+
+export function serializeProfileProjection(agentId: string, projection: unknown): string | null {
+  const json = projection == null ? null : JSON.stringify(projection);
+  warnIfOversized(`projection:${agentId}`, json ?? "", PROFILE_PROJECTION_WARN_BYTES, `[agent-profile] ${agentId} profile_projection`);
+  return json;
 }

package/src/db/agents-async.ts

@@ -131,7 +131,7 @@ export async function setStatusAsync(id: string, status: AgentCard["status"], gu
   const before = await getAgentAsync(id);
   if (!agentSessionGuardResult(before, guard).ok) return false;
   if (!before) return false;
-  if (before.status !== status) runBeforeAgentStatusTransitionHandlers(before, status);
+  if (before.status !== status) await runBeforeAgentStatusTransitionHandlers(before, status);
   if (status === "offline" || status === "stale") evictPendingPresence(id);
   const now = Date.now();
   // #2111 — buffered into the short lifecycle window and submitted with its peers as ONE batch job.
@@ -228,8 +228,9 @@ export async function applyAgentLifecycleUpdateAsync(
 ): Promise<AgentLifecycleUpdateResult> {
   // Allocated first, per the ordinal-timing rule at the top of setStatusAsync.
   const seq = nextLifecycleSeq();
-  const before = prepareAgentLifecycleUpdate(id, update, guard);
+  const before = prepareAgentLifecycleUpdate(id, update, guard, false);
   if (!before) return { ok: false, changed: false, metaWriteBytes: 0, before: null, after: null };
+  if (update.status !== undefined && update.status !== before.status) await runBeforeAgentStatusTransitionHandlers(before, update.status);
   const result = (await getGateway().write("agents.applyLifecycleUpdate", agentLifecycleWriteArgs(before, update, seq, now))) as unknown as Omit<AgentLifecycleUpdateResult, "ok" | "before">;
   return { ok: true, before, ...result };
 }
@@ -296,7 +297,7 @@ export async function reapStaleAgentsAsync(ttlMs: number = STALE_TTL_MS, lagGrac
  */
 export async function pruneOfflineAgentsAsync(
   maxOfflineMs: number = DAY_MS,
-  options: { onFinality?: (result: WorkFinalFlushResult) => void } = {},
+  options: { onFinality?: (result: WorkFinalFlushResult) => void; onArchivePurgeFailure?: () => void } = {},
 ): Promise<string[]> {
   const cutoff = Date.now() - maxOfflineMs;
   const candidates = (await getGateway().read("agents.offlinePruneCandidates", {
@@ -304,7 +305,7 @@ export async function pruneOfflineAgentsAsync(
   })) as unknown as AgentCard[];
   const candidateIds = candidates.map((candidate) => candidate.id);
   if (candidateIds.length === 0) return [];
-  await purgeArchivesBeforeDelete(candidateIds, cutoff);
+  if (!await purgeArchivesBeforeDelete(candidateIds, cutoff)) options.onArchivePurgeFailure?.();
 
   const finalityQueues = takeDeferredLineageReports(candidateIds);
   const refreshFinalityCandidates = candidates
@@ -334,11 +335,13 @@ export async function pruneOfflineAgentsAsync(
 }
 
 /** #3012 — best effort: whatever the off-loop purge leaves, the delete's own FK cascade still removes. */
-async function purgeArchivesBeforeDelete(agentIds: string[], offlineBefore?: number): Promise<void> {
+async function purgeArchivesBeforeDelete(agentIds: string[], offlineBefore?: number): Promise<boolean> {
   try {
     await purgeContinuationArchivesAsync({ agentIds, offlineBefore });
+    return true;
   } catch (error) {
     console.warn("[agents] continuation archive purge before delete failed; the cascade will remove them:", error);
+    return false;
   }
 }
 

package/src/db/agents.ts

@@ -1,3 +1,4 @@
+import { trackRelayEvent } from "../relay-event-drain";
 import { mainThreadRegistry } from "./main-thread-state";
 import { spawnTreeParentIds } from "./spawn-tree";
 import { recordSpawnProcessExit } from "./spawn-process-evidence";
@@ -8,6 +9,7 @@ import { STALE_TTL_MS, DAY_MS } from "../config";
 import { withoutAuthzMetaKeys } from "../authz-meta-keys";
 import {
   jsonBytes,
+  serializeProfileProjection,
   splitAgentMetaForStorage,
   splitAgentMetaPatchForStorage,
   topLevelJsonPath,
@@ -48,10 +50,10 @@ import type {
   QuotaState,
 } from "../types";
 
-type BeforeAgentStatusTransition = (agent: AgentCard, nextStatus: AgentCard["status"]) => void;
+type BeforeAgentStatusTransition = (agent: AgentCard, nextStatus: AgentCard["status"]) => unknown;
 const beforeAgentStatusTransitionHandlers = mainThreadRegistry("agents.ts:beforeAgentStatusTransitionHandlers", new Set<BeforeAgentStatusTransition>());
 
-/** Register synchronous work that must finish before a status transition is persisted. */
+/** Register work that must finish before a status transition is persisted. */
 export function onBeforeAgentStatusTransition(handler: BeforeAgentStatusTransition): () => void {
   beforeAgentStatusTransitionHandlers.add(handler);
   return () => beforeAgentStatusTransitionHandlers.delete(handler);
@@ -62,8 +64,9 @@ export function onBeforeAgentStatusTransition(handler: BeforeAgentStatusTransiti
  *  a writer-worker's own instance), so this must only ever be invoked main-thread-side: from
  *  `setStatus` directly, or from `setStatusAsync`'s pre-write orchestration. Never from the
  *  `agents.setStatus` op body. */
-export function runBeforeAgentStatusTransitionHandlers(before: AgentCard, next: AgentCard["status"]): void {
-  for (const handler of beforeAgentStatusTransitionHandlers) handler(before, next);
+export function runBeforeAgentStatusTransitionHandlers(before: AgentCard, next: AgentCard["status"]): Promise<void> {
+  const pending = [...beforeAgentStatusTransitionHandlers].map(handler => handler(before, next));
+  return trackRelayEvent(Promise.all(pending).then(() => {}), "agent.before-status");
 }
 
 const CONTEXT_SNAPSHOT_DEBOUNCE_MS = 60_000;
@@ -161,7 +164,7 @@ export function upsertAgentInternal(
   const contextState = mergeRelayContextMarkers(input.id, input.context);
   const storedMeta = splitAgentMetaForStorage(withCanonicalSpawnRequestId(input.meta));
   const metaJson = JSON.stringify(storedMeta.meta);
-  const profileProjectionJson = storedMeta.profileProjection == null ? null : JSON.stringify(storedMeta.profileProjection);
+  const profileProjectionJson = storedMeta.profileProjectionProvided ? serializeProfileProjection(input.id, storedMeta.profileProjection) : null;
   warnIfAgentMetaOversized(input.id, metaJson, "stored meta");
   const stmt = getDb().query(`
     INSERT INTO agents (id, name, kind, label, tags, system_tags, machine, rig, capabilities, ready, status, instance_id, epoch, provider_capabilities, context_state, quota_state, profile_projection, meta, lifecycle, spawned_by, team_id, status_seq, ready_seq, last_seen, created_at)
@@ -502,12 +505,12 @@ export function agentLifecycleWriteArgs(before: AgentCard, update: AgentLifecycl
 
 /** The main-thread half of a lifecycle delta: guard, `before` snapshot, transition handlers and presence
  *  eviction (main-thread state), all before the write is submitted. Null when the guard rejects. */
-export function prepareAgentLifecycleUpdate(id: string, update: AgentLifecycleUpdate, guard?: AgentSessionGuard): AgentCard | null {
+export function prepareAgentLifecycleUpdate(id: string, update: AgentLifecycleUpdate, guard?: AgentSessionGuard, runHandlers = true): AgentCard | null {
   const before = getPersistedAgentRuntimeCard(id);
   if (!before || !agentSessionGuardResult(before, guard).ok) return null;
   const nextStatus = update.status;
   // Pre-transition handlers must run BEFORE the write lands, exactly as `setStatus` does.
-  if (nextStatus !== undefined && nextStatus !== before.status) runBeforeAgentStatusTransitionHandlers(before, nextStatus);
+  if (runHandlers && nextStatus !== undefined && nextStatus !== before.status) runBeforeAgentStatusTransitionHandlers(before, nextStatus);
   // #1468 — a terminal transition evicts any buffered beat so a coalesced advance cannot later
   // resurrect a gone agent at flush.
   if (nextStatus === "offline" || nextStatus === "stale") evictPendingPresence(id);
@@ -566,7 +569,7 @@ export function applyAgentLifecycleUpdateInternal(args: AgentLifecycleWriteArgs)
     }
     if (patch.profileProjectionProvided) {
       sets.push("profile_projection = $profileProjection");
-      params.$profileProjection = patch.profileProjection == null ? null : JSON.stringify(patch.profileProjection);
+      params.$profileProjection = serializeProfileProjection(id, patch.profileProjection);
     }
   }
   const runtime = update.runtime;
@@ -615,7 +618,7 @@ export function mergeAgentMeta(id: string, meta: Record<string, unknown>, guard?
   warnIfAgentMetaOversized(id, metaJson, "stored meta");
   const result = getDb()
     .query("UPDATE agents SET meta = ?, profile_projection = ?, last_seen = ? WHERE id = ?")
-    .run(metaJson, stored.profileProjection == null ? null : JSON.stringify(stored.profileProjection), now, id);
+    .run(metaJson, serializeProfileProjection(id, stored.profileProjection), now, id);
   return result.changes > 0;
 }
 
@@ -631,7 +634,7 @@ export function markAgentReadyNotified(id: string, at: number = Date.now()): boo
   const merged = { ...(agent.meta ?? {}), readyNotifiedAt: at };
   const stored = splitAgentMetaForStorage(merged);
   return getDb().query("UPDATE agents SET meta = ?, profile_projection = ? WHERE id = ?")
-    .run(JSON.stringify(stored.meta), stored.profileProjection == null ? null : JSON.stringify(stored.profileProjection), id).changes > 0;
+    .run(JSON.stringify(stored.meta), serializeProfileProjection(id, stored.profileProjection), id).changes > 0;
 }
 
 /** Delete specific keys from an agent's meta blob. Returns true if anything changed. Used to clear
@@ -650,7 +653,7 @@ export function clearAgentMetaKeys(id: string, keys: string[]): boolean {
   if (!changed) return false;
   const stored = splitAgentMetaForStorage(meta);
   return getDb().query("UPDATE agents SET meta = ?, profile_projection = ? WHERE id = ?")
-    .run(JSON.stringify(stored.meta), stored.profileProjection == null ? null : JSON.stringify(stored.profileProjection), id).changes > 0;
+    .run(JSON.stringify(stored.meta), serializeProfileProjection(id, stored.profileProjection), id).changes > 0;
 }
 
 /**
@@ -741,7 +744,7 @@ export function recordAgentExitDiagnosticsInternal(
     .run({
       $seq: lifecycleSeq,
       $meta: JSON.stringify(stored.meta),
-      $profileProjection: stored.profileProjection == null ? null : JSON.stringify(stored.profileProjection),
+      $profileProjection: serializeProfileProjection(id, stored.profileProjection),
       $id: id,
     } as never);
   return result.changes > 0 ? agent.epoch : null;

package/src/db/auth-identities.ts

@@ -93,9 +93,9 @@ export function createAuthIdentity(input: {
   providerSubject: string;
   secretHash?: string | null;
   metadata?: Record<string, unknown>;
-}): AuthIdentity {
+}, submittedAt: number = Date.now()): AuthIdentity {
   const id = randomUUID();
-  const now = Date.now();
+  const now = submittedAt;
   getDb()
     .query(
       `INSERT INTO auth_identities (id, user_id, provider, provider_subject, secret_hash, metadata, created_at)

package/src/db/automation-read-ops.ts

@@ -0,0 +1,11 @@
+// #3799 — automation scans (run listing, reconcile/precheck/dispatch ticks) on the reader pool.
+// A cold scan of automation_runs once blocked the hub loop for seconds on swap-bound I/O.
+import { listAutomationRuns, listDispatchableQueuedRuns, listDueAutomations, listPendingPrecheckRuns, listReconcilableRuns } from "../automations/storage.ts";
+
+export const AUTOMATION_READ_OPS = {
+  "automations.listRuns": (args: { automationId?: string; status?: string; limit?: number }) => listAutomationRuns(args),
+  "automations.pendingPrecheckRuns": () => listPendingPrecheckRuns(),
+  "automations.reconcilableRuns": () => listReconcilableRuns(),
+  "automations.dispatchableQueuedRuns": () => listDispatchableQueuedRuns(),
+  "automations.dueAutomations": (args: { now: number }) => listDueAutomations(args.now),
+};

package/src/db/automation-write-ops.ts

@@ -0,0 +1,46 @@
+import { ValidationError } from "@humwick/sdk";
+import { insertAutomation, updateAutomationNormalized, deleteAutomation } from "../automations/persistence";
+import { nextScheduledAt } from "../automations/cron";
+import { getAutomation, getAutomationRun, hasActiveRun, insertRun, enqueueAutomationRun, updateRun, cancelActiveRuns, rescheduleAutomation } from "../automations/storage";
+import type { Automation } from "../types";
+import type { WriterOpSpec } from "./write-ops";
+
+function admitRun(input: { automationId: string; now: number; manual?: boolean; queuedRunId?: string }) {
+  const automation = getAutomation(input.automationId);
+  if (!automation) return null;
+  const active = hasActiveRun(automation.id);
+  if (input.queuedRunId) {
+    const run = getAutomationRun(input.queuedRunId);
+    if (!run || run.automationId !== automation.id || run.status !== "scheduled" || active) return null;
+    updateRun(run.id, { status: "dispatching" }, input.now);
+    return { automation, run: getAutomationRun(run.id)! };
+  }
+  if (input.manual) {
+    if (active) throw new ValidationError("automation already has an active run");
+  } else {
+    if (!automation.enabled || automation.nextRunAt === undefined || automation.nextRunAt > input.now) return null;
+    if (active && automation.concurrencyPolicy === "replace") cancelActiveRuns(automation.id, input.now, "Replaced by newer scheduled run");
+    else if (active && automation.concurrencyPolicy === "queue") enqueueAutomationRun(automation, automation.nextRunAt, input.now);
+    const next = automation.enabled ? nextScheduledAt(automation.schedule, automation.timezone, input.now) : undefined;
+    rescheduleAutomation(automation, next, input.now);
+    if (active && automation.concurrencyPolicy !== "replace") return null;
+  }
+  const run = insertRun(automation, input.manual ? input.now : automation.nextRunAt ?? input.now, input.now);
+  return { automation: getAutomation(automation.id)!, run };
+}
+
+export const AUTOMATION_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
+  "automations.create": { offLoop: true, idempotent: false, fn: (a: { normalized: Parameters<typeof insertAutomation>[0]; now: number }) => insertAutomation(a.normalized, a.now) },
+  "automations.update": { offLoop: true, idempotent: false, fn: (a: { id: string; normalized: Parameters<typeof updateAutomationNormalized>[1]; expected: Automation; now: number }) => {
+    const current = getAutomation(a.id);
+    if (!current || JSON.stringify(current) !== JSON.stringify(a.expected)) throw new ValidationError("automation changed or was deleted during catalog validation");
+    return updateAutomationNormalized(a.id, a.normalized, a.now);
+  } },
+  "automations.delete": { offLoop: true, idempotent: true, fn: (a: { id: string }) => deleteAutomation(a.id) },
+  "automations.admitRun": { offLoop: true, idempotent: false, fn: admitRun },
+  "automations.insertRun": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof insertRun>) => insertRun(...a) },
+  "automations.enqueueRun": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof enqueueAutomationRun>) => enqueueAutomationRun(...a) },
+  "automations.updateRun": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof updateRun>) => updateRun(...a) ?? null },
+  "automations.cancelRuns": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof cancelActiveRuns>) => cancelActiveRuns(...a) ?? null },
+  "automations.reschedule": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof rescheduleAutomation>) => rescheduleAutomation(...a) ?? null },
+});

package/src/db/blackboard.ts

@@ -161,11 +161,11 @@ export function searchEntries(
   return rows.map(rowToEntry);
 }
 
-export function retractEntry(id: string): BlackboardEntry | null {
+export function retractEntry(id: string, submittedAt: number = Date.now()): BlackboardEntry | null {
   const existing = getEntry(id);
   if (!existing) return null;
   assertStatus("retracted");
   getDb().query("UPDATE blackboard_entries SET status = 'retracted', updated_at = ? WHERE id = ?")
-    .run(Date.now(), id);
+    .run(submittedAt, id);
   return getEntry(id);
 }

package/src/db/browser-session-write.ts

@@ -0,0 +1,32 @@
+import { getAgent } from "./agents";
+import { createCommandInternal } from "../commands-db";
+import { countActiveBrowserSessions, getBrowserSessionRow, insertBrowserSession, transitionBrowserSession } from "./browser-sessions";
+import { getOrchestrator } from "./orchestrators";
+import type { BrowserLimits } from "@humwick/sdk";
+
+export interface StartBrowserWrite {
+  id: string; commandId: string; agentId: string; instanceId?: string; epoch?: number;
+  orchestratorId: string; limits: BrowserLimits;
+}
+export function startBrowserBody(input: StartBrowserWrite, now: number) {
+  const agent = getAgent(input.agentId);
+  if (!agent || agent.status === "offline" || agent.instanceId !== input.instanceId || agent.epoch !== input.epoch) return { conflict: "agent" as const };
+  const host = getOrchestrator(input.orchestratorId);
+  if (!host || host.status !== "online") return { conflict: "host" as const };
+  if (countActiveBrowserSessions({ agentId: input.agentId }) >= input.limits.perAgent) return { conflict: "agentLimit" as const };
+  if (countActiveBrowserSessions({ orchestratorId: host.id }) >= input.limits.perHost) return { conflict: "hostLimit" as const };
+  const command = createCommandInternal({ id: input.commandId, input: { type: "browser.start", source: input.agentId, target: host.agentId, correlationId: input.id,
+    params: { sessionId: input.id, agentId: input.agentId, orchestratorId: host.id, idleTimeoutMs: input.limits.idleTimeoutMinutes * 60_000, hostSessionLimit: input.limits.perHost } } }, now);
+  const row = insertBrowserSession({ id: input.id, agentId: input.agentId, orchestratorId: host.id, startCommandId: command.id, now });
+  return { row, command };
+}
+
+export function stopBrowserBody(input: { id: string; reason: string; commandId: string }, now: number) {
+  const row = getBrowserSessionRow(input.id);
+  if (!row || (row.status !== "starting" && row.status !== "running")) return { row };
+  const host = getOrchestrator(row.orchestratorId);
+  if (!host) return { row: transitionBrowserSession(row.id, ["starting", "running"], { status: "stopped", stoppedAt: now, error: "orchestrator no longer registered" }, now) };
+  const command = createCommandInternal({ id: input.commandId, input: { type: "browser.stop", source: "system", target: host.agentId, correlationId: row.id,
+    params: { sessionId: row.id, agentId: row.agentId, orchestratorId: host.id, reason: input.reason } } }, now);
+  return { row: transitionBrowserSession(row.id, ["starting", "running"], { status: "stopping", stopCommandId: command.id }, now), command };
+}

package/src/db/bus-outbox-write-ops.ts

@@ -31,8 +31,10 @@ export const BUS_OUTBOX_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Obje
   "bus.append": {
     offLoop: true,
     // Appending assigns a new sequence row; retries reconcile by idempotency key rather than
-    // inserting a second durable event after a phantom acknowledgement.
+    // inserting a second durable event after a phantom acknowledgement. A plain emit never retries,
+    // so it goes keyless and writes no ledger row (#3614).
     idempotent: false,
+    atMostOnce: true,
     fn: (args: BusAppendOpArgs, ctx: WriterOpContext) => ({
       ...appendRelayEventInternal(args.type, args.source, args.data, args.subject, ctx.now)!, replayed: false,
     }),

package/src/db/checkout-refresh-schema.ts

@@ -0,0 +1,47 @@
+import type { getDb } from "./connection";
+
+type Database = ReturnType<typeof getDb>;
+
+// Keep one referenced command per checkout; generic command retention can expire its history (#3797).
+export const CHECKOUT_REFRESH_SCHEMA = `
+  CREATE TABLE IF NOT EXISTS checkout_refresh_heads (
+    project_id TEXT NOT NULL,
+    orchestrator_id TEXT NOT NULL,
+    root_path TEXT NOT NULL,
+    command_id TEXT NOT NULL REFERENCES commands(id) ON DELETE CASCADE,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (project_id, orchestrator_id, root_path)
+  );
+  CREATE INDEX IF NOT EXISTS idx_checkout_refresh_heads_command ON checkout_refresh_heads(command_id);
+  CREATE TRIGGER IF NOT EXISTS checkout_refresh_head_insert AFTER INSERT ON commands
+  WHEN NEW.type = 'project.checkout.refresh' AND json_valid(NEW.params)
+    AND json_type(NEW.params, '$.projectId') = 'text'
+    AND json_type(NEW.params, '$.orchestratorId') = 'text'
+    AND json_type(NEW.params, '$.rootPath') = 'text'
+  BEGIN
+    INSERT INTO checkout_refresh_heads VALUES (
+      json_extract(NEW.params, '$.projectId'), json_extract(NEW.params, '$.orchestratorId'),
+      json_extract(NEW.params, '$.rootPath'), NEW.id, NEW.created_at)
+    ON CONFLICT(project_id, orchestrator_id, root_path) DO UPDATE SET
+      command_id = excluded.command_id, created_at = excluded.created_at
+    WHERE excluded.created_at >= checkout_refresh_heads.created_at;
+  END;
+`;
+
+export function migrateCheckoutRefreshHeads(db: Database): void {
+  db.transaction(() => {
+    const installed = db.query("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'checkout_refresh_heads'").get();
+    db.run(CHECKOUT_REFRESH_SCHEMA);
+    if (installed) return;
+    db.run(`INSERT INTO checkout_refresh_heads
+      SELECT project_id, orchestrator_id, root_path, id, created_at FROM (
+        SELECT id, created_at, json_extract(params, '$.projectId') AS project_id,
+          json_extract(params, '$.orchestratorId') AS orchestrator_id, json_extract(params, '$.rootPath') AS root_path,
+          row_number() OVER (PARTITION BY json_extract(params, '$.projectId'), json_extract(params, '$.orchestratorId'),
+            json_extract(params, '$.rootPath') ORDER BY created_at DESC, rowid DESC) AS ordinal
+        FROM commands WHERE type = 'project.checkout.refresh' AND json_valid(params)
+          AND json_type(params, '$.projectId') = 'text' AND json_type(params, '$.orchestratorId') = 'text'
+          AND json_type(params, '$.rootPath') = 'text'
+      ) WHERE ordinal = 1`);
+  })();
+}