@humwick/server 0.130.2 → 0.130.3

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`);
+  })();
+}

package/src/db/checkout-refresh.ts

@@ -4,12 +4,12 @@ import { getOrchestrator } from "./orchestrators";
 import { stringValue } from "@humwick/sdk";
 import { getDb } from "./connection";
 
+export const CHECKOUT_REFRESH_COMMANDS_SQL = `SELECT c.id, c.status, c.params, c.result, c.error, c.updated_at
+  FROM checkout_refresh_heads h CROSS JOIN commands c ON c.id = h.command_id
+  WHERE h.project_id = ?`;
+
 export function checkoutRefreshCommands(projectId: string): CheckoutRefreshStatus[] {
-  const rows = getDb().query(`SELECT * FROM (
-    SELECT id, status, params, result, error, updated_at,
-      row_number() OVER (PARTITION BY 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_extract(params, '$.projectId') = ?
-  ) WHERE ordinal = 1`).all(projectId) as Array<{ id: string; status: Command["status"]; params: string; result: string | null; error: string | null; updated_at: number }>;
+  const rows = getDb().query(CHECKOUT_REFRESH_COMMANDS_SQL).all(projectId) as Array<{ id: string; status: Command["status"]; params: string; result: string | null; error: string | null; updated_at: number }>;
   return rows.map((row) => {
     const params = JSON.parse(row.params);
     return { orchestratorId: params.orchestratorId, rootPath: params.rootPath, commandId: row.id, status: row.status, updatedAt: row.updated_at,

package/src/db/command-agent-profile-backfill.ts

@@ -0,0 +1,39 @@
+// #3606/#3610 — spawn commands written before the content-hash store (command-agent-profiles.ts)
+// still carry `params.agentProfile` inline (~0.4 MB each). Retention keeps some of them past the
+// terminal window (managed agents, unconfirmed spawns), so move those profiles into the store in
+// bounded chunks from the retention pass. `updated_at` is untouched: retention windows key off it.
+
+import { storeCommandAgentProfile } from "./command-agent-profiles";
+import { TERMINAL_COMMAND_STATUS_SQL_LIST } from "./command-terminal-status";
+import type { getDb } from "./connection";
+
+type Database = ReturnType<typeof getDb>;
+const WRITE_TRANSACTION_BUDGET_MS = 25;
+
+/** One bounded chunk: returns the same shape as a retention prune chunk (`pruned` = rows slimmed). */
+export function slimSpawnProfileChunk(db: Database, limit: number): { candidates: number; attempted: number; pruned: number } {
+  // Only terminal rows: a live spawn is still being claimed. A profile carrying vault ciphertext stays
+  // inline (the #3488 settlement trigger prunes it there), so those rows are not candidates.
+  const ids = db.query(`
+    SELECT id FROM commands
+    WHERE type = 'agent.spawn' AND status IN (${TERMINAL_COMMAND_STATUS_SQL_LIST}) AND agent_profile_hash IS NULL
+      AND instr(params, '"agentProfile"') > 0 AND json_valid(params) AND json_type(params, '$.agentProfile') = 'object'
+      AND instr(params, 'sealed:v2:') = 0
+    LIMIT ?
+  `).all(limit) as Array<{ id: string }>;
+  if (ids.length === 0) return { candidates: 0, attempted: 0, pruned: 0 };
+  const read = db.query("SELECT params FROM commands WHERE id = ?");
+  const write = db.query("UPDATE commands SET params = ?, agent_profile_hash = ? WHERE id = ? AND agent_profile_hash IS NULL");
+  return db.transaction(() => {
+    const startedAt = performance.now(); let attempted = 0; let pruned = 0;
+    for (const { id } of ids) {
+      if (attempted > 0 && performance.now() - startedAt >= WRITE_TRANSACTION_BUDGET_MS) break;
+      attempted += 1;
+      const row = read.get(id) as { params: string } | null;
+      if (!row) continue;
+      const stored = storeCommandAgentProfile(JSON.parse(row.params) as Record<string, unknown>, Date.now(), db);
+      if (stored.agentProfileHash) pruned += write.run(JSON.stringify(stored.params), stored.agentProfileHash, id).changes;
+    }
+    return { candidates: ids.length, attempted, pruned };
+  })();
+}

package/src/db/command-agent-profiles.ts

@@ -7,6 +7,7 @@
 import { createHash } from "node:crypto";
 import { isRecord } from "@humwick/sdk";
 import { getDb } from "./connection";
+import { COMMAND_PROFILE_WARN_BYTES, warnIfOversized } from "./agent-meta";
 
 type Database = ReturnType<typeof getDb>;
 
@@ -41,7 +42,10 @@ export function storeCommandAgentProfile(sealed: Record<string, unknown>, now: n
   const body = JSON.stringify(profile);
   if (body.includes("sealed:v2:")) return { params: sealed, agentProfileHash: null };
   const hash = createHash("sha256").update(body).digest("hex");
-  db.query("INSERT OR IGNORE INTO command_agent_profiles (hash, profile, created_at) VALUES (?, ?, ?)").run(hash, body, now);
+  const inserted = db.query("INSERT OR IGNORE INTO command_agent_profiles (hash, profile, created_at) VALUES (?, ?, ?)").run(hash, body, now);
+  if (inserted.changes && Buffer.byteLength(body) > COMMAND_PROFILE_WARN_BYTES) {
+    warnIfOversized("command-profile", body, COMMAND_PROFILE_WARN_BYTES, "[commands] stored agentProfile");
+  }
   const { agentProfile: _stored, ...params } = sealed;
   return { params, agentProfileHash: hash };
 }

package/src/db/command-retention.ts

@@ -0,0 +1,126 @@
+import { quoteIdentifier } from "@humwick/kernel/persistence-schema";
+import { getDb } from "./connection";
+import { TERMINAL_COMMAND_STATUS_SQL_LIST } from "./command-terminal-status";
+
+type Database = ReturnType<typeof getDb>;
+
+const ELIGIBLE = `type != 'agent.spawn' AND status IN (${TERMINAL_COMMAND_STATUS_SQL_LIST})`;
+export const COMMAND_RETENTION_SCHEMA = `
+  CREATE INDEX IF NOT EXISTS idx_commands_terminal_retention ON commands(updated_at, id) WHERE ${ELIGIBLE};
+  CREATE INDEX IF NOT EXISTS idx_commands_refresh_retention ON commands(updated_at, id)
+    WHERE type = 'project.checkout.refresh' AND status IN (${TERMINAL_COMMAND_STATUS_SQL_LIST});
+  CREATE TABLE IF NOT EXISTS command_retention_cursor (
+    id INTEGER PRIMARY KEY CHECK (id = 1), updated_at INTEGER NOT NULL, command_id TEXT NOT NULL);
+`;
+
+// Sampled status stats favor a broad status scan plus sort; retain the bounded age seek (#3619).
+export const TERMINAL_COMMAND_CANDIDATES_SQL = `SELECT id, updated_at FROM commands INDEXED BY idx_commands_terminal_retention
+  WHERE ${ELIGIBLE} AND updated_at < ? AND (updated_at, id) > (?, ?)
+  ORDER BY updated_at, id LIMIT ?`;
+
+export const REFRESH_COMMAND_CANDIDATES_SQL = `SELECT id, updated_at FROM commands INDEXED BY idx_commands_refresh_retention
+  WHERE type = 'project.checkout.refresh' AND status IN (${TERMINAL_COMMAND_STATUS_SQL_LIST})
+    AND updated_at >= ? AND updated_at < ? AND (updated_at, id) > (?, ?)
+  ORDER BY updated_at, id LIMIT ?`;
+
+const JSON_REFERENCES = [
+  ["activity_events", "metadata", ["$.commandId", "$.mergeCommandId"]],
+  ["task_events", "metadata", ["$.commandId", "$.mergeCommandId"]],
+  ["workspaces", "metadata", ["$.mergeCommandId", "$.rekeyCommandId", "$.lastStewardRekey.commandId"]],
+  ["scheduled_timers", "command", ["$.commandId"]],
+  ["workflow_instances", "wait_for", ["$.commandId"]],
+  ["workflow_instances", "initial_state", ["$.commandId"]],
+  ["workflow_step_journal", "wait_for", ["$.commandId"]],
+  ["workflow_step_journal", "state_snapshot", ["$.commandId"]],
+] as const;
+
+function jsonReference(column: string, path: string): string {
+  return `json_extract(CASE WHEN json_valid(${column}) THEN ${column} ELSE '{}' END, '${path}')`;
+}
+
+function commandReferences(db: Database): { tbl: string; col: string }[] {
+  return db.query(`SELECT s.name AS tbl, c.name AS col FROM sqlite_schema s, pragma_table_info(s.name) c
+    WHERE s.type = 'table' AND s.name NOT LIKE 'sqlite_%' AND s.name != 'command_retention_cursor'
+      AND (lower(replace(c.name, '_', '')) LIKE '%commandid' OR lower(replace(c.name, '_', '')) LIKE '%commandids')
+    UNION SELECT s.name, f."from" FROM sqlite_schema s, pragma_foreign_key_list(s.name) f
+      WHERE s.type = 'table' AND f."table" = 'commands'`).all() as { tbl: string; col: string }[];
+}
+
+/** Equality checks in a DELETE must seek references, never repeatedly scan their history (#3619). */
+export function ensureCommandRetentionReferenceIndexes(db: Database): void {
+  for (const { tbl, col } of commandReferences(db)) {
+    if (col.replaceAll("_", "").toLowerCase().endsWith("commandids")) continue;
+    const indexes = db.query(`PRAGMA index_list(${quoteIdentifier(tbl)})`).all() as { name: string; partial: number }[];
+    const covered = indexes.some(index => !index.partial &&
+      (db.query(`PRAGMA index_info(${quoteIdentifier(index.name)})`).get() as { name: string } | null)?.name === col);
+    if (!covered) db.run(`CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`idx_retention_${tbl}_${col}`)} ON ${quoteIdentifier(tbl)}(${quoteIdentifier(col)})`);
+  }
+  for (const [table, column, paths] of JSON_REFERENCES) {
+    if (table === "scheduled_timers") continue; // idx_scheduled_timers_command_created already owns this expression.
+    for (const [i, path] of paths.entries()) db.run(`CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`idx_retention_${table}_${column}_${i}`)}
+      ON ${table}(${jsonReference(column, path)})`);
+  }
+}
+
+const predicates = new WeakMap<Database, { version: number; sql: string }>();
+
+/** Resolve each reference index for the whole candidate set, including CASCADE/SET NULL FKs. */
+function referencedCommandIds(db: Database): string {
+  const version = (db.query("PRAGMA schema_version").get() as { schema_version: number }).schema_version;
+  const cached = predicates.get(db);
+  if (cached?.version === version) return cached.sql;
+  const refs = commandReferences(db);
+  const selections = refs.map(({ tbl, col }) => {
+    const table = quoteIdentifier(tbl), column = quoteIdentifier(col);
+    return col.replaceAll("_", "").toLowerCase().endsWith("commandids")
+      ? `SELECT candidate.id FROM ${table} ref, json_each(CASE WHEN json_valid(ref.${column}) THEN ref.${column} ELSE '[]' END) item
+          JOIN candidates candidate ON CAST(item.value AS TEXT) = candidate.id`
+      : `SELECT candidate.id FROM candidates candidate CROSS JOIN ${table} ref ON ref.${column} = candidate.id`;
+  });
+  // Strip candidate TEXT affinity so JSON expression indexes can seek (#3619).
+  for (const [table, column, paths] of JSON_REFERENCES) {
+    for (const path of paths) {
+      const expression = table === "scheduled_timers" ? `json_extract(ref.${column}, '${path}')` : jsonReference(`ref.${column}`, path);
+      selections.push(`SELECT candidate.id FROM candidates candidate CROSS JOIN ${table} ref ON ${expression} = +candidate.id`);
+    }
+  }
+  const sql = selections.join(" UNION ");
+  predicates.set(db, { version, sql });
+  return sql;
+}
+
+/** #3619 — advance past referenced rows so they cannot starve unrelated expired commands. */
+export function pruneTerminalCommands(cutoff: number, limit: number, refreshCutoff = cutoff): { pruned: number; scanned: number; moreWork: boolean } {
+  const db = getDb();
+  const start = performance.now();
+  const cursor = db.query("SELECT updated_at, command_id FROM command_retention_cursor WHERE id = 1").get() as
+    { updated_at: number; command_id: string } | null;
+  const candidates = db.query(TERMINAL_COMMAND_CANDIDATES_SQL)
+    .all(cutoff, cursor?.updated_at ?? -1, cursor?.command_id ?? "", limit) as { id: string; updated_at: number }[];
+  // Merge two bounded age seeks; one shared cursor also advances past referenced refresh receipts (#3797).
+  if (refreshCutoff > cutoff) candidates.push(...db.query(REFRESH_COMMAND_CANDIDATES_SQL)
+    .all(cutoff, refreshCutoff, cursor?.updated_at ?? -1, cursor?.command_id ?? "", limit) as typeof candidates);
+  const rows = candidates.sort((a, b) => a.updated_at - b.updated_at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).slice(0, limit);
+  if (!rows.length) {
+    db.run("DELETE FROM command_retention_cursor WHERE id = 1");
+    return { pruned: 0, scanned: 0, moreWork: false };
+  }
+  const references = referencedCommandIds(db);
+  let pruned = 0, scanned = 0;
+  // Visit each reference index once per chunk, rather than switch indexes per command (#3807).
+  for (let offset = 0; offset < rows.length; offset += 25) {
+    if (scanned > 0 && performance.now() - start >= 25) break;
+    const chunk = rows.slice(offset, offset + 25);
+    pruned += db.query(`WITH candidates AS MATERIALIZED (
+        SELECT id FROM commands WHERE id IN (${chunk.map(() => "?").join(",")}) AND ${ELIGIBLE}
+          AND (updated_at < ? OR (type = 'project.checkout.refresh' AND updated_at < ?))),
+      referenced(id) AS MATERIALIZED (${references})
+      DELETE FROM commands WHERE id IN (SELECT id FROM candidates EXCEPT SELECT id FROM referenced)`)
+      .run(...chunk.map(row => row.id), cutoff, refreshCutoff).changes;
+    scanned += chunk.length;
+  }
+  const last = rows[scanned - 1]!;
+  db.query(`INSERT INTO command_retention_cursor VALUES (1, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET updated_at = excluded.updated_at, command_id = excluded.command_id`).run(last.updated_at, last.id);
+  return { pruned, scanned, moreWork: true };
+}

package/src/db/commands-planner-stats.test-fixture.ts

@@ -39,6 +39,10 @@ export const PROD_SAMPLED_COMMANDS_STATS: CommandsStatsProfile = {
     idx_commands_target_updated: "499038 6 1 1",
     idx_commands_correlation: "499038 5",
     idx_commands_type_status_created: "499038 18063 6168 1 1",
+    // Undeployed (#3619): conservative full-history upper bound for terminal non-spawn rows.
+    idx_commands_terminal_retention: "499038 2 1",
+    // Undeployed (#3797): conservative refresh-history census, before the one-hour pruning drains it.
+    idx_commands_refresh_retention: "65773 2 1",
     idx_commands_created: "499038 1",
     idx_commands_status: "499038 134",
     idx_commands_target: "499038 6",
@@ -78,6 +82,10 @@ export const PROD_EXACT_COMMANDS_STATS: CommandsStatsProfile = {
     idx_commands_target_updated: "505748 157 1 1",
     idx_commands_correlation: "505748 12",
     idx_commands_type_status_created: "505748 18063 6168 1 1",
+    // Undeployed (#3619): conservative full-history upper bound for terminal non-spawn rows.
+    idx_commands_terminal_retention: "505748 2 1",
+    // Undeployed (#3797): conservative refresh-history census, before the one-hour pruning drains it.
+    idx_commands_refresh_retention: "65773 2 1",
     idx_commands_created: "505748 2",
     idx_commands_status: "505748 72250",
     idx_commands_target: "505748 157",