@humwick/server 0.0.0-stage → 0.130.1

package/src/commands-db.ts

@@ -0,0 +1,1200 @@
+import { buildListCommandsQuery, type CommandFilters } from "./db/commands-list-query";
+import { assertDelegatedSpawnAdmission } from "./db/spawn-delegation";
+import { recordBudgetLineage } from "./db/budget-lineage";
+import { participatesInSpawnDelegation, recordCanceledSpawnTreeStop, recordSpawnTreeStop } from "./db/spawn-delegation-state";
+import { mergeTerminalSpawnEvidence, preserveSpawnProcessEvidence, recordStoppedLaunch, canceledSpawnResultSql } from "./db/spawn-process-evidence";
+import type { WorkflowSpawnQuota } from "./db/spawn-in-flight";
+import { countInFlightSpawnCommands } from "./db/spawn-in-flight-count";
+import { assertWorkflowSpawnQuota, spawnTreeOccupancy } from "./db/workflow-spawn-quota";
+import { revokeVaultTokens } from "./db/vault-tokens";
+import { rowToCommand, type CommandRow } from "./db/command-row";
+import { storeCommandAgentProfile } from "./db/command-agent-profiles";
+import { findSpawnCommandByRequestId } from "./db/commands-spawn-read";
+import { resolveSpawnRequestReuse } from "./db/spawn-request-reuse";
+import { createHash, randomUUID } from "node:crypto";
+import { assembleAgentExitReport } from "./agent-exit-report";
+
+import { getAgent, mergeAgentMeta } from "./db/agents.ts";
+import { stampApiBudgetSpawn } from "./db/claude-api-budget.ts";
+import { stampSelfEffortSpawn } from "./db/self-effort-permissions.ts";
+import { getDb, inWriteTransaction, writeTransaction } from "./db/connection.ts";
+import { landClaimExclusion, refreshPendingLandQueueLease, UPGRADE_CLAIM_EXCLUSION_SQL } from "./db/commands-claim-admission.ts";
+import { recordLandStackCandidate } from "./db/land-stack.ts";
+import { withRestartEpochAdmission } from "./db/restart-epoch-admission.ts";
+
+import { type SpawnHostCapOption } from "./db/spawn-in-flight.ts";
+import { assertSpawnHostCapAdmitted, hostSpawnsDrained } from "./db/spawn-host-cap.ts";
+import { kernelLandingCommandActuationAllowed } from "./db/kernel-landing-command-authority.ts";
+import { getTerminalEvent, recordTerminalEvent } from "./db/terminal-events.ts";
+import { compactExecutionBudgetMs, ValidationError, isRecord, stringValue } from "@humwick/sdk";
+import { maskCommandReport, sealCommandParams } from "./command-secrets";
+import { commandTtlMs, WORKSPACE_COMMAND_TTL_MS } from "./command-ttl";
+import { KERNEL_CORRELATION_PREFIX, isReservedKernelCorrelationId } from "./kernel-correlation";
+import { relayRunReportedLeaseMs } from "./relay-run-lease";
+import { leaselessClaimedCommandIds } from "./db/commands-leaseless-sweep.ts";
+import { HOST_CONFLICT_PENDING_TAG, hostIdentityStatus } from "./host/state";
+import { VALID_WORKSPACE_STATUSES, optionalEnum } from "./validation";
+import type { Command, CommandStatus, CreateCommandInput, UpdateCommandInput } from "./types";
+
+// `Database` is derived from the already-imported `getDb`'s return type rather than imported from
+// "bun:sqlite" directly — the raw-handle ratchet (#1879) bans that import outside the allowlisted
+// dispatch/bootstrap layer. Needed only for createCommandInternal's optional `db` param (#1870/#1991).
+type Database = ReturnType<typeof getDb>;
+
+/**
+ * The command table is the one launch choke point shared by ordinary spawns, recipes,
+ * automations, managed-policy reconciliation, and successor-producing restarts. Keeping this
+ * check here is deliberate: a host whose hardware identity changed must remain fail-closed even
+ * when a new command producer is added without remembering the presentation/selection helpers.
+ *
+ * A missing host link is the established pre-registration compatibility case. Once an
+ * orchestrator is linked to a Host, however, `conflict:pending` is authoritative and only human
+ * hardware acceptance may clear it.
+ */
+function assertLaunchTargetIdentityMatched(input: CreateCommandInput, db: Database): void {
+  if (input.type !== "agent.spawn" && !(input.type === "agent.restart" && input.params?.restartSpawn)) return;
+  const row = db.query(`
+    SELECT o.id AS orchestrator_id, h.system_tags AS system_tags
+    FROM orchestrators o
+    LEFT JOIN hosts h ON h.id = o.host_id
+    WHERE o.agent_id = ? OR o.id = ? LIMIT 1
+  `).get(input.target, stringValue(input.params?.orchestratorId) ?? null) as
+    | { orchestrator_id: string; system_tags: string | null }
+    | undefined;
+  if (!row?.system_tags) return;
+  let tags: unknown;
+  try {
+    tags = JSON.parse(row.system_tags);
+  } catch {
+    // A malformed legacy tag payload is not evidence of an identity mismatch; host projection
+    // owns its repair/validation. Do not reinterpret it here.
+    return;
+  }
+  if (!Array.isArray(tags) || !tags.includes(HOST_CONFLICT_PENDING_TAG)) return;
+  const identity = hostIdentityStatus(tags);
+  if (identity.matched) return;
+  throw new ValidationError(
+    `orchestrator ${row.orchestrator_id} is blocked: ${identity.cause} ${identity.remedy}`,
+  );
+}
+
+/** Per-write option surface for {@link createCommand}. */
+export interface CreateCommandOptions {
+  readonly allowWorkspaceRekey?: boolean;
+  readonly allowWorkspaceDeliveryTip?: boolean;
+  /** R2 (#1409): permit a `kcmd:`-reserved `correlation_id`. ONLY the kernel command bridge (via
+   *  `dispatchCommand`) sets this — every external/client-influenced ingress leaves it false, so the
+   *  reservation is enforced at this single write choke point by construction. */
+  readonly allowReservedCorrelation?: boolean;
+  /** Stage 8 (#1411): only the authenticated server operator service may create this reserved
+   * command type. Generic HTTP/WS command writers must not pre-seed its request-id dedup key. */
+  readonly allowTimerMessageOperator?: boolean;
+  readonly hostCap?: SpawnHostCapOption; // #2702 — absent: capped, no caller discount
+}
+
+/** Plain data supplied by the async writer facade. UUID/time are captured on submission (H6), never
+ * generated on the writer worker. Keeping this body in the domain module lets the writer registry
+ * execute the exact same command-insert choke point off the main thread. */
+export interface CreateCommandWriteArgs {
+  readonly input: CreateCommandInput;
+  readonly options?: CreateCommandOptions;
+  readonly id: string;
+}
+
+/** Structured result returned by the command patch writer op. */
+export interface UpdateCommandWriteResult {
+  readonly command: Command | null;
+  readonly previousStatus?: CommandStatus;
+}
+
+
+
+export const CLAIMED_ACTIVE_STATUSES: CommandStatus[] = ["accepted", "running"]; // #1213 — for the shutdown-agent pre-registration reap path
+const TERMINAL_STATUSES: CommandStatus[] = ["succeeded", "failed", "canceled", "timed_out"];
+
+const DISPATCH_STATUSES: CommandStatus[] = ["accepted", "running"];
+
+// #1803 round-4 (#4) — a FLOOR execution lease for any command CLAIMED via the CAS (claimPendingCommand /
+// fencePublishForPush) whose type has no lease of its own (commandTtlMs → undefined: e.g.
+// orchestrator.migrate-provider-config, or any future/unknown type the orchestrator routes through the
+// generic off-tick claim) AND that carried no creation-time ttl. Without this such a row is stamped
+// `accepted`/`running` with expires_at=NULL and, if its claim-success response is lost (the claim commits
+// on the hub but the ack never reaches the host), it is NEVER re-driven and NEVER swept — accepted
+// forever (a real DB repro: still accepted a year later). Applying a default lease at claim time makes
+// expireCommands eventually sweep it to `timed_out`, which also bounds the #1811 no-owner-token window.
+// 40min matches the most generous real lease (WORKSPACE_COMMAND_TTL_MS), so no live handler is
+// false-expired; a command that DID carry a creation ttl is honored as-is (it does not "lack one").
+const DEFAULT_CLAIMED_COMMAND_TTL_MS = WORKSPACE_COMMAND_TTL_MS;
+
+// #1452 round-12 — the review push/unpublish commands whose ORIGIN mutation is gated on a claim. Once
+// CLAIMED (accepted/running) they must be terminalized ONLY by the executor's own settlement or the TTL
+// sweep — NEVER a public cancel (HIGH#1) — because the host checks its claim exactly once and then pushes.
+function isClaimGatedReviewCommand(type: string): boolean {
+  return type === "workspace.publish-review" || type === "workspace.unpublish-review";
+}
+
+export function isTerminalStatus(status: CommandStatus): boolean {
+  return TERMINAL_STATUSES.includes(status);
+}
+
+function isLegacyUnfencedWorkspaceMerge(command: Pick<Command, "type" | "landingContainmentMode">): boolean {
+  return command.type === "workspace.merge" && command.landingContainmentMode === "legacy-unfenced-v0";
+}
+
+// #930 — the terminal→different transitions that ARE legitimate (verified by
+// checking every updateCommand caller). Everything else out of a terminal state is
+// state churn to be refused. The `timed_out`→terminal corrections below are the
+// exceptions: the executor learned the REAL outcome after the hub's lease swept the
+// row, and its answer beats the sweep's guess.
+//   1. The upgrade reconcile flips a timed-out upgrade back to `succeeded` when the
+//      orchestrator eventually reports the desired version (src/routes/orchestrator.ts).
+function isLegitimateTerminalCorrection(type: string, from: CommandStatus, to: CommandStatus): boolean {
+  if (type === "orchestrator.upgrade" && from === "failed" && to === "succeeded") return true;
+  // #1025 A7 / #1693 — a lost merge RESULT: the orchestrator may land the branch OR
+  // complete a red gate after the TTL sweep marks it `timed_out`. Apply either late
+  // terminal outcome so expiry never overwrites a result we subsequently learned.
+  if (type === "workspace.merge" && from === "timed_out" && (to === "succeeded" || to === "failed")) return true;
+  // #2275 — a lost SPAWN outcome, same shape as the merge case above. Once the watchdog stopped
+  // terminal-failing a spawn whose claim is still live (tier 2's liveness gate), the executor became
+  // the ONLY party that knows how a past-lease launch actually ended — and its late report was being
+  // refused as state churn, leaving the parent on "do NOT retry" forever. Launches longer than the
+  // lease are demonstrated, not hypothetical (the #2275 land-gate contention). Applying the late
+  // outcome is safe from re-introducing the double-fire precisely because nothing tells the parent
+  // "safe to retry" any more, and notifyAgentSpawnFailed carries #648's per-request dedup plus the
+  // `agent.spawn_recovered` retraction if the child registers after all.
+  if (type === "agent.spawn" && from === "timed_out" && (to === "succeeded" || to === "failed")) return true;
+  return false;
+}
+
+/**
+ * The synchronous command-create body. The writer op owns this whole unit, rather than wrapping the
+ * INSERT alone, so reservation validation and the durable insert share one transaction boundary.
+ * `db` defaults to the calling thread's shared connection so every existing in-process caller is
+ * unchanged; a caller that already holds a connection (a registered op, or another #1870 leaf's op
+ * body composing this write into its own transaction, e.g. recipe-db.ts's startRecipeInstance)
+ * passes it explicitly so both writes land in the SAME transaction instead of a second thread hop.
+ */
+export function createCommandInternal(args: CreateCommandWriteArgs, now = Date.now(), db: Database = getDb()): Command {
+  // #2189 P7 — THE restart-epoch admission choke point. Every create that reaches the `commands` table
+  // through this function (commands.create, the kernel bridge's createKernelIfAbsent, and the
+  // quota-gated spawn insert) consults the open epoch HERE, inside the caller's already-open writer
+  // transaction — not before it. The only create that does not pass through here is the legacy landing
+  // insert, which owns its own INSERT and therefore carries the same call explicitly.
+  const input = withRestartEpochAdmission(args.input);
+  const contextBoundary = input.type === "agent.compact" || input.type === "agent.clearContext";
+  const params = contextBoundary ? { ...input.params, compactAgentEpoch: getAgent(input.target)?.epoch, ...(input.type === "agent.compact" ? { compactBudgetMs: compactExecutionBudgetMs() } : {}) } : input.params ?? {};
+  if (input.type === "agent.shutdown") {
+    const stoppedId = stringValue(input.params?.agentId) ?? input.target;
+    recordSpawnTreeStop(stoppedId, stringValue(input.params?.reason) ?? "shutdown", now);
+  }
+  assertDelegatedSpawnAdmission(input, now);
+  assertLaunchTargetIdentityMatched(input, db);
+  assertSpawnHostCapAdmitted(input, args.options?.hostCap, now);
+  recordBudgetLineage(input, now);
+  const { id } = args;
+  const options = args.options ?? {};
+  if (input.type === "workspace.rekey" && !options.allowWorkspaceRekey) throw new ValidationError("workspace.rekey is reserved for the steward handoff");
+  if (input.type === "workspace.pin-delivery-tip" && !options.allowWorkspaceDeliveryTip) throw new ValidationError("workspace.pin-delivery-tip is reserved for complete delivery admission");
+  if (input.type === "workspace.merge") throw new ValidationError("workspace.merge is reserved for commands.createLegacyLanding");
+  if (input.type.startsWith("landing.") && !(options.allowReservedCorrelation === true && isReservedKernelCorrelationId(input.correlationId))) throw new ValidationError("landing.* commands are reserved for the Kernel command bridge");
+  if (input.type === "timer.message-cutover.operator" && options.allowTimerMessageOperator !== true) {
+    throw new ValidationError("timer.message-cutover.operator is reserved for the authenticated server operator service");
+  }
+  // R2 (#1409) — THE single command-write choke point for the reserved kernel correlation namespace.
+  // `correlation_id` is written to the DB in exactly ONE place: the INSERT below. Rejecting a reserved
+  // `kcmd:` correlation here (unless the trusted kernel-bridge path explicitly opts in) covers EVERY
+  // ingress by construction — `POST /api/commands`, spawn `spawnRequestId`, the WS bus, audit
+  // branch/approval/request ids, orchestrator restart — so no client-influenced value can pre-seed a
+  // row that cross-maps a kernel command. Fail-closed.
+  if (!options.allowReservedCorrelation && isReservedKernelCorrelationId(input.correlationId)) {
+    throw new ValidationError(`correlationId must not start with the reserved '${KERNEL_CORRELATION_PREFIX}' prefix`);
+  }
+  const command: Command = {
+    id,
+    type: input.type,
+    source: input.source,
+    target: input.target,
+    params,
+    status: "pending",
+    correlationId: input.correlationId,
+    ...(input.controller ? { controller: input.controller } : {}),
+    ...(input.controllerVersion !== undefined ? { controllerVersion: input.controllerVersion } : {}),
+    ...(input.controllerToken ? { controllerToken: input.controllerToken } : {}),
+    ...(input.laneKey ? { laneKey: input.laneKey } : {}),
+    ...(input.actuator ? { actuator: input.actuator } : {}),
+    ...(input.commandGeneration !== undefined ? { commandGeneration: input.commandGeneration } : {}),
+    ...(input.restartSensitive !== undefined ? { restartSensitive: input.restartSensitive } : {}),
+    ...(input.admission ? { admission: input.admission } : {}),
+    ...(input.blockedByEpochId ? { blockedByEpochId: input.blockedByEpochId } : {}),
+    ...(input.executionId ? { executionId: input.executionId } : {}),
+    ...(input.executionGeneration !== undefined ? { executionGeneration: input.executionGeneration } : {}),
+    ...(input.executionOwnerToken ? { executionOwnerToken: input.executionOwnerToken } : {}),
+    ...(input.processGroupId !== undefined ? { processGroupId: input.processGroupId } : {}),
+    ...(input.transientUnit ? { transientUnit: input.transientUnit } : {}),
+    ...(input.terminalProcessProof ? { terminalProcessProof: input.terminalProcessProof } : {}),
+    ...(input.landingBlockerCode ? { landingBlockerCode: input.landingBlockerCode } : {}),
+    ...(input.landingBlockerDetail ? { landingBlockerDetail: input.landingBlockerDetail } : {}),
+    ...(input.landingContainmentMode ? { landingContainmentMode: input.landingContainmentMode } : {}),
+    createdAt: now,
+    updatedAt: now,
+    expiresAt: input.type === "agent.compact" ? defaultExpiresAt(input.type, now, params) : input.ttlMs ? now + input.ttlMs : defaultExpiresAt(input.type, now, params),
+  };
+  // #1300 — seal secret-shaped env values (the minted runner bearer token) so the commands table
+  // never holds a live credential in plaintext; the in-memory command keeps the real values for the
+  // creator and the target orchestrator. #3606 — the agentProfile goes to its content-hash store.
+  const stored = storeCommandAgentProfile(sealCommandParams(command.params), now, db);
+  db.query(`
+    INSERT INTO commands (
+      id, type, source, target, params, status, correlation_id,
+      controller, controller_version, controller_token, lane_key, actuator, command_generation, restart_sensitive, admission, blocked_by_epoch_id,
+      execution_id, execution_generation, execution_owner_token, process_group_id, transient_unit, terminal_process_proof,
+      landing_blocker_code, landing_blocker_detail, landing_containment_mode,
+      created_at, updated_at, expires_at, agent_profile_hash
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    command.id,
+    command.type,
+    command.source,
+    command.target,
+    JSON.stringify(stored.params),
+    command.status,
+    command.correlationId ?? null,
+    command.controller ?? null,
+    command.controllerVersion ?? null,
+    command.controllerToken ?? null,
+    command.laneKey ?? null,
+    command.actuator ?? null,
+    command.commandGeneration ?? null,
+    command.restartSensitive ? 1 : 0,
+    command.admission ?? "admitted",
+    command.blockedByEpochId ?? null,
+    command.executionId ?? null,
+    command.executionGeneration ?? 0,
+    command.executionOwnerToken ?? null,
+    command.processGroupId ?? null,
+    command.transientUnit ?? null,
+    command.terminalProcessProof ?? null,
+    command.landingBlockerCode ?? null,
+    command.landingBlockerDetail ?? null,
+    command.landingContainmentMode ?? null,
+    command.createdAt,
+    command.updatedAt,
+    command.expiresAt ?? null,
+    stored.agentProfileHash,
+  );
+  if (["agent.shutdown", "agent.restart"].includes(command.type)) {
+    const agentId = stringValue(params.agentId) ?? command.target;
+    const agent = getAgent(agentId);
+    if (agent) revokeVaultTokens(agentId, now, command.type, agent.instanceId, stringValue(params.spawnRequestId));
+  }
+  stampApiBudgetSpawn(command, db);
+  stampSelfEffortSpawn(command, db);
+  return command;
+}
+
+export function createCommand(input: CreateCommandInput, options: CreateCommandOptions = {}, id: string = randomUUID()): Command {
+  return inWriteTransaction(() => createCommandInternal({ input, options, id }));
+}
+
+export function getCommand(id: string): Command | null {
+  const row = getDb().query("SELECT * FROM commands WHERE id = ?").get(id) as CommandRow | undefined;
+  return row ? rowToCommand(row) : null;
+}
+
+export { buildListCommandsQuery } from "./db/commands-list-query";
+
+export function listCommands(filters: CommandFilters = {}): Command[] {
+  const { sql, params } = buildListCommandsQuery(filters);
+  return (getDb().query(sql).all(...params as any[]) as CommandRow[]).map(rowToCommand);
+}
+
+
+export { findSpawnCommandByRequestId, listInFlightSpawnCommands } from "./db/commands-spawn-read";
+
+export function readSpawnSystemTags(spawnRequestId: string | undefined, agentId: string): unknown | undefined { const command = spawnRequestId ? findSpawnCommandByRequestId(spawnRequestId) : null; return command?.params.agentId === agentId ? command.params.systemTags : undefined; }
+
+/**
+ * #2432 — the most recent SUCCEEDED `agent.shutdown` command for this agent's CURRENT generation,
+ * newest settled first, or null. The shutdown command's `target` is always the control
+ * orchestrator; the child identity rides in `params.agentId` (canonical payload,
+ * services/shutdown-agent.ts) and is echoed in `result.agentId`, and the GENERATION rides in
+ * params/result `spawnRequestId` (a fresh registration mints a fresh one, so an agent id reused
+ * across restarts cannot match a predecessor's teardown). Both must equal what the caller read off
+ * the dead agent's card — matching on agentId alone would let a previous generation's graceful
+ * stop mask a genuine crash of the successor. Death classification
+ * (services/bus-expiration-death.ts) consults this as POSITIVE evidence of deliberate teardown.
+ */
+export function latestSucceededShutdownForAgent(agentId: string, spawnRequestId: string): Command | null {
+  if (!agentId || !spawnRequestId) return null;
+  const row = getDb()
+    .query(`
+      SELECT * FROM commands
+      WHERE type = 'agent.shutdown'
+        AND status = 'succeeded'
+        AND (json_extract(params, '$.agentId') = ? OR json_extract(result, '$.agentId') = ?)
+        AND (json_extract(params, '$.spawnRequestId') = ? OR json_extract(result, '$.spawnRequestId') = ?)
+      ORDER BY updated_at DESC
+      LIMIT 1
+    `)
+    .get(agentId, agentId, spawnRequestId, spawnRequestId) as CommandRow | undefined;
+  return row ? rowToCommand(row) : null;
+}
+
+/** #2918 — a same-generation agent.shutdown that settled after reaching the LIVE process, incl. a
+ * kill-failed whose target died moments later. `wasRunning` excludes a stop that only reaped a corpse. */
+export function liveShutdownForAgent(agentId: string, spawnRequestId: string, since: number): Command | null {
+  if (!agentId || !spawnRequestId) return null;
+  const row = getDb().query(`
+    SELECT * FROM commands
+    WHERE type = 'agent.shutdown' AND status IN ('succeeded', 'failed') AND updated_at >= ?
+      AND json_extract(params, '$.agentId') = ? AND json_extract(params, '$.spawnRequestId') = ?
+      AND json_extract(result, '$.wasRunning') = 1
+    ORDER BY updated_at DESC
+    LIMIT 1
+  `).get(since, agentId, spawnRequestId) as CommandRow | undefined;
+  return row ? rowToCommand(row) : null;
+}
+
+/** A recent shutdown requested by the child's parent, scoped to this spawn generation. */
+export function parentRequestedShutdown(agentId: string, spawnRequestId: string, parentId: string, since: number): boolean {
+  if (!spawnRequestId) return false;
+  const rows = getDb().query(PARENT_REQUESTED_SHUTDOWN_SQL).all(since, agentId, spawnRequestId) as Array<{ params: string }>;
+  for (const row of rows) {
+    let params: unknown;
+    try {
+      params = JSON.parse(row.params);
+    } catch {
+      continue;
+    }
+    if (!isRecord(params)) continue;
+    // T4458 — transports record the CREDENTIAL (`runner:spawn:sp_…`, `dashboard`) in
+    // `requestedBy`, never the agent id, so a parent-id equality alone never matches live rows.
+    if (params.requestedBy === parentId) return true;
+    if (params.requestedCallerAgentId === parentId) return true;
+    if (typeof params.requestedBy === "string" && tokenSubIdentifiesAgent(params.requestedBy, parentId)) return true;
+  }
+  return false;
+}
+
+// T4458 — the token sub behind a live `requestedBy` maps to its agent through the signed
+// `agents` constraint minted with the token. Fallback for rows predating `requestedCallerAgentId`.
+function tokenSubIdentifiesAgent(sub: string, agentId: string): boolean {
+  const rows = getDb().query(`SELECT constraints FROM tokens WHERE sub = ? LIMIT 5`).all(sub) as Array<{ constraints: string | null }>;
+  for (const row of rows) {
+    if (!row.constraints) continue;
+    try {
+      const constraints: unknown = JSON.parse(row.constraints);
+      if (isRecord(constraints) && Array.isArray(constraints.agents) && constraints.agents.includes(agentId)) return true;
+    } catch {
+      // A malformed token row is not evidence of parentage; keep checking the rest.
+    }
+  }
+  return false;
+}
+
+/** Mark every command for a spawn request as registered, including a prior unconfirmed advisory. */
+export function markSpawnRegistrationConfirmed(spawnRequestId: string, at = Date.now()): string[] {
+  const cleaned = spawnRequestId.trim();
+  if (!cleaned) return [];
+  const rows = getDb().query(`
+    SELECT id, params FROM commands WHERE json_valid(params) AND id IN (
+      SELECT id FROM commands INDEXED BY idx_commands_correlation WHERE type = 'agent.spawn' AND correlation_id = ?1
+      UNION SELECT id FROM commands INDEXED BY idx_commands_spawn_request WHERE type = 'agent.spawn' AND json_valid(params) AND json_extract(params, '$.spawnRequestId') = ?1
+    )
+  `).all(cleaned) as Array<{ id: string; params: string }>;
+  const changed: string[] = [];
+  const stmt = getDb().query("UPDATE commands SET params = ? WHERE id = ?");
+  for (const row of rows) {
+    try {
+      const parsed = JSON.parse(row.params);
+      if (!isRecord(parsed) || parsed.registrationConfirmed === true) continue;
+      parsed.registrationConfirmed = true;
+      parsed.registrationConfirmedAt = at;
+      if (stmt.run(JSON.stringify(parsed), row.id).changes > 0) changed.push(row.id);
+    } catch {}
+  }
+  return changed;
+}
+
+export { listInjectionAttempts, listPendingInjectionAttemptIds } from "./db/injection-attempts";
+
+/** #2712 — an agent's CURRENT launch via three identity indexes, never a scan of launch history: a
+ *  spawn by `correlation_id` or `params.spawnRequestId`, or a restart/resume by `params.agentId`.
+ *  Only those rows are JSON-read for `presence`; the newest wins. Shared by both launch finders. */
+function launchCommandSql(columns: string, presence: string): string {
+  return `
+    SELECT ${columns} FROM commands WHERE id IN (
+      SELECT id FROM commands INDEXED BY idx_commands_correlation WHERE type = 'agent.spawn' AND correlation_id = ?1
+      UNION SELECT id FROM commands INDEXED BY idx_commands_spawn_request WHERE type = 'agent.spawn' AND json_valid(params) AND json_extract(params, '$.spawnRequestId') = ?1
+      UNION SELECT id FROM commands INDEXED BY idx_commands_relaunch_agent WHERE type IN ('agent.restart', 'agent.resume') AND json_valid(params) AND json_extract(params, '$.agentId') = ?2
+    ) AND coalesce(json_extract(params, '$.${presence}'), json_extract(params, '$.restartSpawn.${presence}')) IS NOT NULL
+    ORDER BY created_at DESC
+    LIMIT 1
+  `;
+}
+
+/**
+ * The command that composed the system prompt an agent is CURRENTLY running under (#1565 F5) — its
+ * `agent.spawn`, or a later `agent.restart`/`agent.resume` that recomposed `systemPromptAppend`.
+ *
+ * A relaunch replaces the prompt, and #1065 rotates the spawnRequestId without writing an
+ * `agent.spawn` row for the successor, so the spawn lookup alone cannot see the newest prompt. The
+ * memory delta-gate needs both the prompt and WHEN it was composed, to tell a hash recorded for a
+ * context that still exists from one recorded for a context a relaunch has since replaced.
+ */
+export function findLaunchPromptCommandForAgent(agentId: string, spawnRequestId?: string): Command | null {
+  const row = getDb()
+    .query(launchCommandSql("*", "systemPromptAppend"))
+    .get(spawnRequestId?.trim() ?? "", agentId) as CommandRow | undefined;
+  return row ? rowToCommand(row) : null;
+}
+
+/**
+ * The command carrying the MEMORY SEAM the agent's current launch resolved (#1625) — the identity
+ * the spawn seam composed its block from, stamped into the immutable
+ * launch params so every later seam replays it instead of re-deriving one that can differ.
+ *
+ * The launch predicate is deliberately the same as {@link findLaunchPromptCommandForAgent}'s (its
+ * sibling; they answer about the same launch) but the PRESENCE test is on `memorySeam`, not on
+ * `systemPromptAppend`: a launch can resolve an identity and still compose an empty append, and a
+ * pre-#1625 launch carries a prompt with no seam. Conflating them would either miss a stamped seam
+ * or claim one that was never recorded.
+ */
+export function findLaunchMemorySeamCommandForAgent(agentId: string, spawnRequestId?: string): Command | null {
+  const row = getDb()
+    .query(launchCommandSql("*", "memorySeam"))
+    .get(spawnRequestId?.trim() ?? "", agentId) as CommandRow | undefined;
+  return row ? rowToCommand(row) : null;
+}
+
+/** What {@link findLaunchMemorySeamCommandsForAgents} returns per matched agent — exactly the
+ *  fields a launch-seam reader (`seamFromLaunchCommand` in `memory-seam.ts`) touches. NOT a full
+ *  `Command`: launch params average ~130 KB, and a fleet read must not materialize them (#1958). */
+export type LaunchSeamCommand = Pick<Command, "type" | "correlationId" | "createdAt" | "params">;
+
+interface LaunchSeamRow {
+  type: string;
+  correlation_id: string | null;
+  created_at: number;
+  memory_seam: unknown;
+  restart_seam: unknown;
+  spawn_request_id: unknown;
+  agent_id: unknown;
+}
+
+const LAUNCH_SEAM_COLUMNS = `type, created_at, correlation_id,
+  json_extract(params, '$.memorySeam') AS memory_seam,
+  json_extract(params, '$.restartSpawn.memorySeam') AS restart_seam,
+  json_extract(params, '$.spawnRequestId') AS spawn_request_id,
+  json_extract(params, '$.agentId') AS agent_id`;
+
+/** `json_extract` returns an object/array path as JSON TEXT but a scalar as the bare SQLite value;
+ *  this normalizes either to the JS value a full `JSON.parse(params)` would have produced. */
+function launchSeamColumnValue(raw: unknown): unknown {
+  if (raw === null || raw === undefined) return undefined;
+  if (typeof raw !== "string") return raw;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function paramsFromLaunchSeamRow(row: LaunchSeamRow): Record<string, unknown> {
+  const params: Record<string, unknown> = {};
+  const memorySeam = launchSeamColumnValue(row.memory_seam);
+  if (memorySeam !== undefined) params.memorySeam = memorySeam;
+  const restartSeam = launchSeamColumnValue(row.restart_seam);
+  if (restartSeam !== undefined) params.restartSpawn = { memorySeam: restartSeam };
+  const spawnRequestId = launchSeamColumnValue(row.spawn_request_id);
+  if (spawnRequestId !== undefined) params.spawnRequestId = spawnRequestId;
+  const agentId = launchSeamColumnValue(row.agent_id);
+  if (agentId !== undefined) params.agentId = agentId;
+  return params;
+}
+
+/** The fleet form of {@link findLaunchMemorySeamCommandForAgent}: the same indexed lookup per agent,
+ *  projected to the seam fields. #2712 — it used to scan and sort every historical launch (~490 MB
+ *  of params on prod). Only agents with a match appear in the returned map. */
+export function findLaunchMemorySeamCommandsForAgents(
+  agents: ReadonlyArray<{ id: string; spawnRequestId?: string }>,
+): Map<string, LaunchSeamCommand> {
+  const resolved = new Map<string, LaunchSeamCommand>();
+  if (!agents.length) return resolved;
+  const query = getDb().query(launchCommandSql(LAUNCH_SEAM_COLUMNS, "memorySeam"));
+  for (const agent of agents) {
+    const row = query.get(agent.spawnRequestId?.trim() ?? "", agent.id) as LaunchSeamRow | null;
+    if (!row) continue;
+    resolved.set(agent.id, {
+      type: row.type,
+      correlationId: row.correlation_id ?? undefined,
+      createdAt: row.created_at,
+      params: paramsFromLaunchSeamRow(row),
+    });
+  }
+  return resolved;
+}
+
+/** The latest command carrying `correlationId`, across any type. The kernel command bridge
+ * (#1409 P2-1) stamps a namespaced idempotency key onto `correlation_id` and looks it up here to
+ * dedupe a re-driven `ctx.commands.issue` onto the SAME orchestrator command instead of
+ * double-dispatching (the #1408 exactly-once boundary). Type-agnostic because the key is already
+ * module-namespaced, so one key maps to at most one logical command. */
+export function findCommandByCorrelationId(correlationId: string): Command | null {
+  const row = getDb()
+    .query("SELECT * FROM commands WHERE correlation_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1")
+    .get(correlationId) as CommandRow | undefined;
+  return row ? rowToCommand(row) : null;
+}
+
+/** The newest attempt of `type` for `correlationId`. A keep-place land retry reuses its first
+ *  attempt's created_at (#2965), so ties break on rowid, the insertion order (#3064). */
+export function findLatestCommandByCorrelation(type: string, correlationId: string): Command | null {
+  const row = getDb()
+    .query(`
+      SELECT * FROM commands INDEXED BY idx_commands_type_correlation_created
+      WHERE type = ? AND correlation_id = ?
+      ORDER BY created_at DESC, rowid DESC
+      LIMIT 1
+    `)
+    .get(type, correlationId) as CommandRow | undefined;
+  return row ? rowToCommand(row) : null;
+}
+
+export { countInFlightSpawnCommands } from "./db/spawn-in-flight-count";
+
+// The quota-gated spawn-command body (#1432/#1467): read the live + in-flight child counts (agents +
+// commands SELECTs), then INSERT the `agent.spawn` command on a win — a read→write UPGRADE inside one
+// transaction, exactly the deferred-upgrade instant-BUSY pattern #1428 fixed for message sends. It hit
+// SQLITE_BUSY when a coordinator fanned out several spawns at once (a dual/quad reviewer batch) or when
+// a spawn landed concurrently with the message-journal / task-update / land writers. MUST run under
+// BEGIN IMMEDIATE (writeTransaction) so busy_timeout governs contention instead of an instant BUSY.
+// Pure synchronous body; the two public wrappers below choose the transaction discipline.
+function runCreateSpawnCommandWithinQuota(
+  input: CreateCommandInput,
+  quota: { parentId: string; maxSpawnedAgents: number; liveChildren: () => number },
+): { command: Command | null; occupiedSlots: number } {
+  const live = quota.liveChildren();
+  const inFlight = countInFlightSpawnCommands(quota.parentId);
+  const occupied = live + inFlight;
+  if (occupied >= quota.maxSpawnedAgents) return { command: null, occupiedSlots: occupied };
+  return { command: createCommand(input), occupiedSlots: occupied + 1 };
+}
+
+/** A quota-gated spawn admission; `replayed` marks an already admitted command for the same request id. */
+export type SpawnAdmission = { command: Command; occupiedSlots: number; replayed: true; registeredAgentId?: string } | { command: Command | null; occupiedSlots: number; replayed?: undefined };
+
+/** Plain arguments for the quota writer op. `bufferedLiveIds` is captured at submission so the
+ * writer retains the presence-buffer semantics without closing over main-thread state. */
+export interface CreateSpawnCommandWithinQuotaWriteArgs {
+  readonly input: CreateCommandInput;
+  readonly parentId?: string; // absent: no spawn quota (admin/dashboard); the #2694 host cap still applies
+  readonly maxSpawnedAgents?: number;
+  readonly workflow?: WorkflowSpawnQuota;
+  readonly hostCap?: SpawnHostCapOption;
+  readonly bufferedLiveIds: readonly string[];
+  /** Generated at submission so the writer body never reaches for wall-clock/UUID state (H6). */
+  readonly id: string;
+}
+
+/**
+ * The async quota body's complete read-modify-write unit. Both the live-child count and the
+ * in-flight command count run on the writer connection, immediately before the INSERT, under the
+ * executor's BEGIN IMMEDIATE. That closes the old "count on the loop, insert later" TOCTOU window.
+ */
+export function createSpawnCommandWithinQuotaInternal(
+  args: CreateSpawnCommandWithinQuotaWriteArgs,
+  now = Date.now(),
+): SpawnAdmission {
+  const parent = stringValue(args.input.params?.spawnedBy);
+  const delegated = parent && participatesInSpawnDelegation(parent);
+  const requestId = args.input.correlationId;
+  const reuse = requestId ? resolveSpawnRequestReuse(requestId) : { kind: "admit" as const };
+  // #3327 — every existing launch replays here, under the writer lock: the caller gets the admitted command
+  // (its provider and decision) and must not emit or record anything of its own.
+  if (reuse.kind === "canceled" || (reuse.kind === "replay" && delegated && reuse.command.params.spawnedBy !== parent)) {
+    throw new ValidationError(delegated ? "SPAWN_SUBTREE_STOPPING: launch was canceled or belongs to another parent" : `spawnRequestId ${requestId} was canceled; use a new spawnRequestId`);
+  }
+  if (reuse.kind === "registered") throw new ValidationError(`spawnRequestId ${requestId} is already registered to agent ${reuse.registeredAgentId}`);
+  if (reuse.kind === "replay") {
+    if (parent && stringValue(reuse.command.params.spawnedBy) !== parent) throw new ValidationError(`spawnRequestId ${requestId} is already in use`);
+    return { command: reuse.command, occupiedSlots: 0, replayed: true, ...(reuse.registeredAgentId ? { registeredAgentId: reuse.registeredAgentId } : {}) };
+  }
+  assertWorkflowSpawnQuota(args, now, Boolean(delegated));
+  const parentId = args.parentId ?? ""; const quota = args.parentId === undefined ? undefined : args.maxSpawnedAgents; // #2694: host-cap-only
+  const occupied = !delegated && args.parentId ? spawnTreeOccupancy(parentId, now, args.bufferedLiveIds) : 0;
+  if (!delegated && quota !== undefined && occupied >= quota) return { command: null, occupiedSlots: occupied };
+  return {
+    command: createCommandInternal({ input: args.input, id: args.id, ...(args.hostCap ? { options: { hostCap: args.hostCap } } : {}) }, now),
+    occupiedSlots: occupied + 1,
+  };
+}
+
+/**
+ * Synchronous quota-gated spawn-command insert in one `BEGIN IMMEDIATE` transaction (#1432/#1467).
+ * Single attempt: a BUSY that survives busy_timeout throws. Prefer {@link createSpawnCommandWithinQuotaAsync}
+ * on the live spawn path, which yields the loop between BUSY retries. Kept for callers that are not async
+ * and for the regression test that isolates the primary BEGIN IMMEDIATE fix.
+ */
+export function createSpawnCommandWithinQuota(
+  input: CreateCommandInput,
+  quota: { parentId: string; maxSpawnedAgents: number; liveChildren: () => number },
+): { command: Command | null; occupiedSlots: number } {
+  return writeTransaction(() => runCreateSpawnCommandWithinQuota(input, quota));
+}
+
+/** Per-write options for {@link updateCommand}. */
+export interface UpdateCommandOptions {
+  /** #1452 round-13 HIGH#2 — the caller is an AUTHORIZED executor of a claim-gated review publish (the
+   *  token-verified settle route) OR the internal TTL sweep. Only such a caller may terminalize a CLAIMED
+   *  (accepted/running) `workspace.publish-review`. Every EXTERNAL write surface (generic PATCH, WS bus,
+   *  public DELETE) funnels through here WITHOUT this flag, so they are refused — closing the spoofed-
+   *  settlement orphan/phantom-published without touching the shared command path. */
+  readonly executor?: boolean;
+  readonly schedulerOwnerToken?: string;
+  readonly cleanupReportValidated?: boolean;
+}
+
+/** Hot command-patch write. Exported for the query-plan gate so it tests the live statement. */
+export const UPDATE_COMMAND_SQL = `
+    UPDATE commands
+    SET status = ?1, result = CASE WHEN ?1 = 'canceled' THEN ${canceledSpawnResultSql("commands", "?2")} ELSE ?2 END,
+        error = ?, updated_at = ?, expires_at = ?,
+        execution_id = ?, execution_generation = ?, execution_owner_token = ?, process_group_id = ?,
+        transient_unit = ?, terminal_process_proof = ?
+    WHERE id = ?
+  `;
+
+/**
+ * Entire read/validate/patch command lifecycle unit. The async writer op invokes this with the
+ * submission timestamp supplied by its context, so no read-modify-write decision crosses a thread
+ * hop (§3.4/H6). Post-commit notifications deliberately remain in the facade below.
+ */
+export function updateCommandInternal(
+  id: string,
+  input: UpdateCommandInput,
+  opts: UpdateCommandOptions = {},
+  now = Date.now(),
+): UpdateCommandWriteResult {
+  const existing = getCommand(id);
+  if (!existing) return { command: null };
+  if (existing.type === "scheduler.command" && opts.schedulerOwnerToken !== undefined
+      && getCommandClaimOwnerToken(id) !== opts.schedulerOwnerToken) {
+    throw new ValidationError("scheduler command claim owner changed");
+  }
+  if (existing.type === "workspace.merge" && !isLegacyUnfencedWorkspaceMerge(existing)) {
+    throw new ValidationError("workspace.merge updates are reserved for landing fence operations");
+  }
+  if (existing.type === "workspace.merge" && input.result) optionalEnum(input.result.status, "result.status", VALID_WORKSPACE_STATUSES);
+  // A repeated shutdown can reach the host after the first command removed its session record.
+  // Resolve that narrow idempotent case from Relay's durable, same-generation kill certificate.
+  // A genuinely missing target still fails, preserving the kill-switch's fail-closed behavior.
+  let alreadyStopped = false;
+  if (existing.type === "agent.shutdown" && input.status === "failed" && input.result?.targetNotFound === true) {
+    const agentId = stringValue(existing.params.agentId);
+    const spawnRequestId = stringValue(existing.params.spawnRequestId);
+    const prior = agentId && spawnRequestId ? latestSucceededShutdownForAgent(agentId, spawnRequestId) : null;
+    if (prior?.result?.stopped === true && getAgent(agentId!)?.status === "offline") {
+      const { targetNotFound: _targetNotFound, ...result } = input.result;
+      alreadyStopped = true;
+      input = { ...input, status: "succeeded", result: { ...result, stopped: true, alreadyStopped: true } };
+    }
+  }
+  const nextStatus = input.status ?? existing.status;
+  // #930 — terminal-state guard. A command already in a terminal state must not be
+  // silently transitioned to a DIFFERENT status. The concrete hazard: the backgrounded
+  // spawn dispatch (#880 cap) can call updateCommand("succeeded") AFTER expireCommands
+  // has already swept the row to `timed_out`, silently flipping timed_out→succeeded —
+  // state churn plus double-spawn risk if the requestor already reacted to the timeout.
+  // Idempotent terminal→same-terminal is fine; the only terminal→different transitions
+  // allowed are the checked-caller corrections in isLegitimateTerminalCorrection. Any
+  // other is an observable no-op (returns the row unchanged, logs) rather than a write.
+  if (
+    input.status &&
+    input.status !== existing.status &&
+    isTerminalStatus(existing.status) &&
+    !isLegitimateTerminalCorrection(existing.type, existing.status, input.status)
+  ) {
+    console.error(`[commands-db] refused terminal transition ${existing.status}→${input.status} for ${existing.type} command ${id}`);
+    mergeTerminalSpawnEvidence(existing, input.result, now);
+    return { command: getCommand(id), previousStatus: existing.status };
+  }
+  // #1452 round-12/13 HIGH#1+#2 — CONFINE terminalization of a CLAIMED (accepted/running) review PUBLISH.
+  // The host gates its origin force-push on winning the claim + an adjacent re-fence; the reconciler reads
+  // this command's terminal STATE/RESULT to decide the pinned ref's fate. So an EXTERNAL party that moves
+  // the row to ANY terminal status mid-execution corrupts that decision: a spoofed `succeeded {pushed:
+  // false}`/`canceled` makes the reconciler drop the ref + delete the ledger row while the host still
+  // pushes → orphan; a spoofed `succeeded {pushed:true}` announces a ref that was never pushed → phantom.
+  // Round-12 blocked only `canceled`; round-13 broadens to EVERY terminal status. This is the SINGLE choke
+  // point for all writers (generic PATCH, WS bus, public DELETE all funnel here), so refusing unless the
+  // caller is an authorized executor (opts.executor: the token-verified settle route, or the TTL sweep for
+  // its timed_out) confines terminalization to exactly the executor + sweep. `pending` is untouched — the
+  // reconciler's pending-only cancelPendingCommand CAS still retires a never-claimed publish.
+  if (
+    !opts.executor &&
+    existing.type === "workspace.publish-review" &&
+    (existing.status === "accepted" || existing.status === "running") &&
+    input.status &&
+    input.status !== existing.status &&
+    isTerminalStatus(input.status)
+  ) {
+    console.error(`[commands-db] refused external terminalization ${existing.status}→${input.status} of claimed publish ${id} (no executor authorization)`);
+    return { command: existing, previousStatus: existing.status };
+  }
+  // #1452 round-12 — an in-flight (accepted/running) review UNPUBLISH must not be publicly CANCELED: it
+  // is idempotent and reconciler-owned, so a public DELETE/PATCH cancel would just strand a cleanup the
+  // reconciler must re-drive. Unpublish is not fenced, so its own succeeded/failed settlement (generic
+  // updateCommand) stays allowed — only the canceled transition is refused.
+  if (
+    input.status === "canceled" &&
+    existing.type === "workspace.unpublish-review" &&
+    (existing.status === "accepted" || existing.status === "running")
+  ) {
+    console.error(`[commands-db] refused post-claim cancel ${existing.status}→canceled for ${existing.type} command ${id}`);
+    return { command: existing, previousStatus: existing.status };
+  }
+  // #3361 — a running spawn is past the host's last pre-launch check, so a late cancel would mark the row
+  // canceled while the process still starts. Refuse it; stop the launched agent with a shutdown instead.
+  if (input.status === "canceled" && existing.type === "agent.spawn" && existing.status === "running") {
+    console.error(`[commands-db] refused running→canceled for agent.spawn command ${id}: launch already started`);
+    return { command: existing, previousStatus: existing.status };
+  }
+  // #930/#953 — refresh the lease from dispatch-intent when an expiring command is
+  // claimed or starts running. Pending commands are not swept before delivery, so a
+  // busy orchestrator must not inherit an already-expired lease when it finally gets
+  // back to the command loop.
+  const ttlMs = relayRunReportedLeaseMs(existing, input, now) ?? (input.status && DISPATCH_STATUSES.includes(input.status) ? commandTtlMs(existing.type, existing.params) : undefined);
+  const nextExpiresAt =
+    ttlMs !== undefined
+      ? now + ttlMs
+      : existing.expiresAt ?? null;
+  if (input.result?.cleanupReport) input = { ...input, result: assembleAgentExitReport(existing, input, opts.cleanupReportValidated) };
+  input = { ...input, result: preserveSpawnProcessEvidence(existing, input.result) };
+  // #3403 — the one persistence seam for reported results: the row, its bus events and retry-ledger copy.
+  input = maskCommandReport(existing, input);
+  getDb().query(UPDATE_COMMAND_SQL).run(
+    nextStatus,
+    input.result !== undefined ? JSON.stringify(input.result) : existing.result ? JSON.stringify(existing.result) : null,
+    alreadyStopped ? null : input.error ?? existing.error ?? null,
+    now,
+    nextExpiresAt,
+    input.executionId ?? existing.executionId ?? null,
+    input.executionGeneration ?? existing.executionGeneration ?? 0,
+    input.executionOwnerToken ?? existing.executionOwnerToken ?? null,
+    input.processGroupId ?? existing.processGroupId ?? null,
+    input.transientUnit ?? existing.transientUnit ?? null,
+    input.terminalProcessProof ?? existing.terminalProcessProof ?? null,
+    id,
+  );
+  if (nextStatus === "canceled") recordCanceledSpawnTreeStop(getCommand(id), now);
+  recordStoppedLaunch(existing, input, now);
+  if (existing.type === "workspace.merge" && nextStatus === "running") recordLandStackCandidate(id, input.result, now);
+  return { command: getCommand(id), previousStatus: existing.status };
+}
+
+/**
+ * True when `applyCommandUpdatePostCommit` could do anything at all. #1869 W0.2 — a PURE check on the
+ * settled command, so the async facade can skip the post-commit writer op entirely for the (vast)
+ * majority of patches instead of paying a thread hop to discover both effects immediately return.
+ * It is exactly the first condition BOTH effects test, kept beside them so it cannot drift.
+ */
+export const commandUpdateHasPostCommitEffects = (updated: Command | null): boolean => updated?.type === "agent.shutdown";
+
+/** Run command-settlement effects only after the command writer transaction committed. */
+export function applyCommandUpdatePostCommit(previousStatus: CommandStatus | undefined, updated: Command | null): Command | null {
+  if (updated) {
+    recordShutdownTerminalEventOnSuccess(previousStatus ?? updated.status, updated);
+    reconcileAgentLifecycleOnShutdownFailure(previousStatus ?? updated.status, updated);
+  }
+  return updated;
+}
+
+export function updateCommand(id: string, input: UpdateCommandInput, opts: UpdateCommandOptions = {}): Command | null {
+  const result = input.status === "canceled" || input.result?.cleanupReport ? inWriteTransaction(() => updateCommandInternal(id, input, opts)) : updateCommandInternal(id, input, opts);
+  return applyCommandUpdatePostCommit(result.previousStatus, result.command);
+}
+
+/** Whether the public DELETE may cancel this command. Shared by the sync and async delete paths. */
+export function commandDeletable(existing: Command | null): existing is Command {
+  if (!existing) return false;
+  if (existing.type === "workspace.merge" && !isLegacyUnfencedWorkspaceMerge(existing)) return false;
+  if (!["pending", "accepted"].includes(existing.status)) return false;
+  // #1452 round-12 HIGH#1 — a CLAIMED (accepted) review publish/unpublish command is NOT publicly
+  // cancelable (see updateCommand's post-claim-cancel guard). Report "cannot cancel" honestly rather
+  // than a false success: without this the updateCommand guard would no-op the cancel yet we'd still
+  // return true, telling the caller a claimed push was canceled when it was not.
+  return !(existing.status === "accepted" && isClaimGatedReviewCommand(existing.type));
+}
+
+export function deleteCommand(id: string): boolean {
+  if (!commandDeletable(getCommand(id))) return false;
+  updateCommand(id, { status: "canceled", error: "canceled" });
+  return true;
+}
+
+// Race the host claim on the same pending row; only the winning cancellation records stop intent.
+// Legacy landing cancellation stays confined to its unfenced rows.
+export function cancelPendingCommand(id: string, expectedType: string, reason = "canceled before dispatch"): boolean {
+  if (expectedType === "workspace.merge") {
+    const existing = getCommand(id);
+    if (!existing || !isLegacyUnfencedWorkspaceMerge(existing)) return false;
+  }
+  return inWriteTransaction(() => {
+    const now = Date.now();
+    const changes = getDb()
+      .query(`UPDATE commands SET status = 'canceled', result = ${canceledSpawnResultSql()}, error = ?, updated_at = ? WHERE id = ? AND status = 'pending' AND type = ?`)
+      .run(reason, now, id, expectedType).changes;
+    if (changes > 0) recordCanceledSpawnTreeStop(getCommand(id), now);
+    return changes > 0;
+  });
+}
+
+// #1747 — workspace abandonment cancels only still-pending rows, with each winning launch's stop.
+export function cancelPendingCommandsForCorrelation(correlationId: string, type: string, reason = "canceled: workspace abandoned"): number {
+  return inWriteTransaction(() => {
+    const now = Date.now();
+    const canceled = getDb()
+      .query(`UPDATE commands SET status = 'canceled', result = ${canceledSpawnResultSql()}, error = ?, updated_at = ?
+        WHERE correlation_id = ? AND type = ? AND status = 'pending'
+          AND (? != 'workspace.merge' OR landing_containment_mode = 'legacy-unfenced-v0') RETURNING id`)
+      .all(reason, now, correlationId, type, type) as Array<{ id: string }>;
+    for (const row of canceled) recordCanceledSpawnTreeStop(getCommand(row.id), now);
+    return canceled.length;
+  });
+}
+
+// #1452 round-11 HIGH#1 — atomically CLAIM a command for execution: `UPDATE ... SET status='accepted'
+// WHERE id=? AND status='pending' [AND type=?]`. A real compare-and-swap — the host MUST call this and
+// PUSH ONLY IF it returns the claimed command (claim won); a null means the row was no longer pending
+// (canceled by the reconciler when the round closed, or already claimed), so the host must NOT push.
+// This is what makes "cancel ⟹ no publish push" a PROVABLE invariant: cancelPendingCommand and this
+// claim are two CAS on the same row+status, so the loser's UPDATE affects 0 rows and is a no-op. The
+// lease (expires_at) is (re)set from dispatch-intent so a host that dies after claiming is sweepable.
+export function claimPendingCommand(id: string, expectedType?: string, ownerToken?: string, now = Date.now()): Command | null {
+  const existing = getCommand(id); if (!existing) return null;
+  if (!kernelLandingCommandActuationAllowed(existing) || (existing.type === "workspace.merge" && !isLegacyUnfencedWorkspaceMerge(existing))
+    || (expectedType && existing.type !== expectedType)) return null;
+  const ttlMs = commandTtlMs(existing.type, existing.params);
+  // #1803 round-4 (#4) — a claimed row must NEVER be leaseless: a typed lease refreshes from dispatch-intent
+  // as before; a type with no lease honors any creation-time ttl, else falls back to the default floor so an
+  // unknown/leaseless command can't sit `accepted` forever on a lost claim-ack.
+  const expiresAt = ttlMs !== undefined ? now + ttlMs : existing.expiresAt ?? now + DEFAULT_CLAIMED_COMMAND_TTL_MS;
+  const typeClause = expectedType ? " AND type = ?" : "";
+  // #2189 P7 — the GENERIC pending→accepted claim is a restart-sensitive admission too. `agent.spawn`
+  // reaches execution through THIS CAS, not through claimLandingBody, so without the predicate below a
+  // parked spawn still ran and a deploy restart killed it mid-registration — the #2148 failure the
+  // restart epoch exists to close. `admission != 'parked'` is part of the CAS itself rather than a
+  // pre-check, so it cannot be raced by a concurrent park: the park and the claim contend for the same
+  // row in the same serialized writer, and exactly one wins.
+  const land = existing.type === "workspace.merge" ? landClaimExclusion(existing.target, now) : undefined;
+  const claimExclusion = (existing.type === "agent.spawn" || existing.type === "agent.restart") && hostSpawnsDrained(existing.target) ? " AND 0"
+    : land ? land.sql
+    : existing.type === "orchestrator.upgrade" ? UPGRADE_CLAIM_EXCLUSION_SQL : "";
+  const query = getDb().query(
+    `UPDATE commands SET status = 'accepted', updated_at = ?, expires_at = ?, claim_owner_token = ?${land?.set ?? ""}
+     WHERE id = ? AND status = 'pending' AND admission != 'parked'${typeClause}${claimExclusion}`,
+  );
+  const changes = query.run(now, expiresAt, ownerToken ?? null, id, ...(expectedType ? [expectedType] : []), ...(land?.args ?? [])).changes;
+  if (changes > 0) return getCommand(id);
+  if (existing.type === "workspace.merge" && existing.status === "pending") refreshPendingLandQueueLease(id, now, true);
+  // A response can be lost after the CAS commits. Replaying the exact claim owner token is safe:
+  // it never transfers ownership and returns the already-accepted row to the same executor only.
+  if (!ownerToken) return null;
+  const reclaimed = getDb().query(
+    `SELECT * FROM commands WHERE id = ? AND (status = 'accepted' OR (status = 'running' AND type = 'scheduler.command' AND json_extract(result, '$.restartRecovery') = 'worker-v1')) AND claim_owner_token = ?${typeClause}`,
+  );
+  const row = expectedType
+    ? reclaimed.get(id, ownerToken, expectedType) as CommandRow | undefined
+    : reclaimed.get(id, ownerToken) as CommandRow | undefined;
+  return row ? rowToCommand(row) : null;
+}
+
+// #3083 — pinned: sampled planner stats rate `target = ?` as ~6 rows, so the unpinned query walked
+// every row of the host target (seconds on the prod hub). The pin seeks target + status + owner.
+export const ACCEPTED_BY_OWNER_SQL = `SELECT * FROM commands INDEXED BY idx_commands_claim_recovery
+  WHERE target = ? AND status IN ('accepted', 'running') AND claim_owner_token = ?
+    AND (status = 'accepted' OR (type = 'scheduler.command' AND json_extract(result, '$.restartRecovery') = 'worker-v1'))
+    AND expires_at > ? ORDER BY created_at ASC LIMIT 500`;
+
+/** Owned accepted work and durable scheduler runs still owing an acknowledged result. */
+export function listAcceptedCommandsByOwner(target: string, ownerToken: string): Command[] {
+  if (!target || !ownerToken) return [];
+  const rows = getDb().query(ACCEPTED_BY_OWNER_SQL).all(target, ownerToken, Date.now()) as CommandRow[];
+  return rows.map(rowToCommand);
+}
+
+// #1452 round-12 HIGH#2 — RE-FENCE a claimed review-publish command IMMEDIATELY before the host's
+// origin push. A CAS `UPDATE ... SET status='running', expires_at=<fresh lease> WHERE id=? [AND type=?]
+// AND status IN ('accepted','running')`, returning the row iff it won. Distinct from claimPendingCommand
+// (pending→accepted, which fences ENTRY): this re-validates an EXISTING live claim right before the
+// irreversible push. A command swept to `timed_out` (this host stalled past its lease) — or otherwise
+// terminalized — matches 0 rows, so the host SKIPS the push. That closes the split-brain resume where a
+// stalled-then-resumed claimant would push AFTER the TTL sweep let a replacement orchestrator retire the
+// ledger row (a permanent orphan): a "re-read then push" alone still races the sweep, but this CAS also
+// REFRESHES the lease, so — with the review-ref git timeout clamped structurally below the lease — the
+// git-timeout-bounded push provably completes within the fresh lease and the sweep cannot fire between
+// the fence and the push. On any transport failure the host fails closed (skips the push).
+export function fencePublishForPush(id: string, expectedType?: string): Command | null {
+  const existing = getCommand(id);
+  if (!existing) return null;
+  if (existing.type === "workspace.merge" && !isLegacyUnfencedWorkspaceMerge(existing)) return null;
+  if (expectedType && existing.type !== expectedType) return null;
+  const now = Date.now();
+  const ttlMs = commandTtlMs(existing.type, existing.params);
+  // #1803 round-4 (#4) — same leaseless-floor invariant as claimPendingCommand: a re-fenced running command
+  // is never left with expires_at=NULL (belt-and-suspenders; every fenced type today already has a lease).
+  const expiresAt = ttlMs !== undefined ? now + ttlMs : existing.expiresAt ?? now + DEFAULT_CLAIMED_COMMAND_TTL_MS;
+  const typeClause = expectedType ? " AND type = ?" : "";
+  const query = getDb().query(
+    `UPDATE commands SET status = 'running', updated_at = ?, expires_at = ? WHERE id = ? AND status IN ('accepted', 'running')${typeClause}`,
+  );
+  const changes = expectedType
+    ? query.run(now, expiresAt, id, expectedType).changes
+    : query.run(now, expiresAt, id).changes;
+  return changes > 0 ? getCommand(id) : null;
+}
+
+// #1025 A6 — sweep both claimed/active leases past their deadline AND pending commands
+// whose target orchestrator is permanently gone. Pending commands are normally left for a
+// busy host to poll (#930/#953), but a `workspace.merge` (or `agent.spawn`) whose target
+// host was decommissioned / re-registered under a new agent id will NEVER poll again — the
+// command lingers forever, `recoverAgedInFlightWorkspaces` files the workspace under
+// `stillActive` indefinitely, and the parked worker waits on a `landed-success` that can't
+// fire. The `isTargetGone` predicate (supplied by the caller, which knows agent liveness)
+// gates the pending sweep so a merely-busy host is untouched; a gone target's expired
+// pending command is timed out, then settled → the workspace returns to review_requested
+// and re-schedules, and the spawn parent is told. Opt-in: callers without the predicate
+// keep the historical claimed/active-only behavior.
+/** Bound on the leaseless backlog one sweep terminalizes. The live database carries fifteen such
+ *  rows; a small page keeps the settle fan-out that follows bounded too. */
+const LEASELESS_CLAIMED_SWEEP_LIMIT = 20;
+
+// The command-expiration sweep's two reads, every reaper tick (gated in src/query-plan-gate.test.ts).
+export const EXPIRED_CLAIMED_COMMANDS_SQL = `SELECT * FROM commands WHERE (type != 'workspace.merge' OR landing_containment_mode = 'legacy-unfenced-v0')
+  AND expires_at IS NOT NULL AND expires_at <= ? AND status IN (${CLAIMED_ACTIVE_STATUSES.map(() => "?").join(",")})`;
+// #2672 — a parked row is held by a restart epoch, not undispatchable: its window restarts at unpark.
+export const EXPIRED_PENDING_COMMANDS_SQL = `SELECT * FROM commands WHERE (type != 'workspace.merge' OR landing_containment_mode = 'legacy-unfenced-v0')
+  AND expires_at IS NOT NULL AND expires_at <= ? AND status = 'pending' AND admission != 'parked'`;
+
+export function expireCommands(
+  now: number = Date.now(),
+  opts: { isTargetGone?: (command: Command) => boolean } = {},
+): Command[] {
+  const activeRows = getDb().query(EXPIRED_CLAIMED_COMMANDS_SQL).all(now, ...CLAIMED_ACTIVE_STATUSES) as CommandRow[];
+  const pendingCandidates = getDb().query(EXPIRED_PENDING_COMMANDS_SQL).all(now) as CommandRow[];
+  // A spawn's create-time lease is a dispatch deadline: once it passes with no
+  // claim, no host can still be running its body. An online orchestrator record
+  // may be stale or unable to poll, and must not keep that row pending forever.
+  const pendingRows = pendingCandidates.filter((row) => row.type === "agent.spawn" || (row.type === "agent.restart" && hostSpawnsDrained(row.target)) || Boolean(opts.isTargetGone?.(rowToCommand(row))));
+  // #2369 — plus the rows no lease-keyed sweep can ever see: claimed commands with NO execution
+  // lease at all, which no live claim path can produce (see commands-leaseless-sweep.ts). Folded in
+  // here rather than given their own job so they reach the SAME settle/emit fan-out this sweep's
+  // caller already drives; a parallel terminal path is how a merge gets marked done while its
+  // workspace stays stranded.
+  const leaselessRows = leaselessClaimedCommandIds(now, LEASELESS_CLAIMED_SWEEP_LIMIT)
+    .map((id) => getDb().query("SELECT * FROM commands WHERE id = ?").get(id) as CommandRow);
+  const rows = [...activeRows, ...pendingRows, ...leaselessRows];
+  for (const row of rows) {
+    // #1452 round-13 — the TTL sweep is an AUTHORIZED terminalizer of a claimed publish (executor:true):
+    // it is the fail-closed path that lets the reconciler clean a host-death-after-claim, and timed_out is
+    // ambiguous (ref retained), never a ref-drop. External surfaces get no such flag (see updateCommand).
+    updateCommand(row.id, {
+      status: "timed_out",
+      error: row.status === "pending"
+        ? ((row.type === "agent.spawn" || row.type === "agent.restart") && hostSpawnsDrained(row.target) ? "host draining: spawns disabled; expired before dispatch" : "command target gone; expired before dispatch")
+        : row.expires_at === null
+          ? "command was claimed without an execution lease and no executor ever held it (pre-cutover legacy row)"
+          : "command timed out",
+    }, { executor: true });
+  }
+  return rows.map((row) => getCommand(row.id)).filter((command): command is Command => Boolean(command));
+}
+
+function defaultExpiresAt(type: string, now: number, params?: Record<string, unknown>): number | undefined {
+  // #2275 — the CREATE-time window. A spawn gets the short dispatch deadline here and the derived
+  // execution lease only once a host commits to running it (claim → accepted, slot → running).
+  const ttlMs = commandTtlMs(type, params, "create");
+  return ttlMs === undefined ? undefined : now + ttlMs;
+}
+
+// #2094 Fix A — a small safety grace since the command was claimed, before an executor-confirmed-gone
+// merge is reclaimed. The instance-id discriminator below is DEFINITIVE (a restarted process can never
+// re-match), so this grace is only belt-and-suspenders against a claim/register interleaving within one
+// tick; it is negligible next to the 40-min lease the fix replaces. Consumed by src/workspace-auto-merge.ts.
+export const EXECUTOR_ORPHAN_GRACE_MS = 90_000;
+
+/** SHA-256 hex of an orchestrator's process-frozen `claimOwnerToken` — the RECONNECT-STABLE per-process
+ *  instance identity {@link commandExecutorConfirmedGone} compares. The orchestrator reports this exact
+ *  fingerprint of its current token in registration (orchestrator/src/relay.ts), and the command's
+ *  `claim_owner_token` (captured AT CLAIM via claimPendingCommand, the raw process-frozen token) is
+ *  hashed the same way here — so equal ⟹ same live process, different ⟹ the claimant restarted. Hashing
+ *  keeps the raw claim secret off the (readable) orchestrator record. */
+export function claimOwnerTokenFingerprint(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+/** The claim owner token captured on a command when the executor CLAIMED it (claimPendingCommand's CAS,
+ *  `claim_owner_token`). Server-internal — deliberately NOT surfaced on the {@link Command} object (it is
+ *  never API-exposed), so the reclaim reads it through this narrow accessor. */
+export function getCommandClaimOwnerToken(id: string): string | null {
+  const row = getDb().query("SELECT claim_owner_token FROM commands WHERE id = ?").get(id) as { claim_owner_token: string | null } | undefined;
+  return row?.claim_owner_token ?? null;
+}
+
+/** The owning-orchestrator facts {@link commandExecutorConfirmedGone} needs, resolved by the CALLER
+ *  (commands-db must not import the orchestrator DB). `claimInstanceId` is `orchestrator.meta.claimInstanceId`:
+ *  the fingerprint of the CURRENT live process's claimOwnerToken (see {@link claimOwnerTokenFingerprint}) —
+ *  reconnect-stable, so it changes ONLY on a real process restart, never on a mere reconnect/re-register.
+ *  `lastSeen` is `orchestrator.lastSeen` (the owner's last recorded heartbeat) — optional because only the
+ *  #2104 spawn-loss escalation (src/services/spawn-loss-escalation.ts) needs it, to gate its `offline`-status
+ *  check on elapsed time since the LAST heartbeat rather than the point-in-time status sample; the #2094
+ *  merge reclaim this interface was built for never reads it. */
+export interface CommandExecutorOwner {
+  readonly status: string;
+  readonly claimInstanceId?: string;
+  readonly lastSeen?: number;
+}
+
+/**
+ * Is the executor session that CLAIMED a still-non-terminal command CONFIRMED GONE — i.e. its owning
+ * orchestrator PROCESS restarted after claiming it? Executor-liveness, not age/TTL, is what tells a
+ * restart-orphaned merge (reclaim in seconds) apart from a genuinely-running gate (leave it alone). It
+ * is deliberately CONSERVATIVE / fail-safe: every unresolvable input returns `false`, so the caller
+ * degrades to its existing 40-min lease-TTL backstop and NEVER to a more aggressive reclaim.
+ *
+ *  - Only a CLAIMED (accepted/running) command has an owning session that can be gone; a `pending`
+ *    command a restarted host simply re-polls is never "orphaned".
+ *  - The discriminator is the RECONNECT-STABLE per-process instance identity, NOT wall-clock. The
+ *    command carries the claiming process's `claim_owner_token` (frozen once per process, captured at
+ *    the claim CAS); the owner reports the fingerprint of its CURRENT token. Different fingerprint ⟹ a
+ *    strictly-different process now runs under that orchestrator id ⟹ the claimant restarted mid-merge.
+ *    SAME fingerprint ⟹ the SAME live process still owns it (even across reconnects / re-registrations,
+ *    which do NOT mint a new token) ⟹ NOT gone — this is what stops a mere reconnect mid-gate from ever
+ *    ripping a live ci:land and double-dispatching a concurrent merge.
+ *  - Plus a small grace since the claim, purely to avoid a claim/register interleaving edge within a tick.
+ *  - An absent owner record, a not-`online` owner, a command with no captured claim token (never claimed
+ *    via the CAS), or an owner that reports no instance id (a pre-#2094 runner) is UNRESOLVABLE → not-gone
+ *    → the TTL backstop decides, never a more aggressive reclaim.
+ */
+export function commandExecutorConfirmedGone(
+  command: Command,
+  claimOwnerToken: string | null,
+  owner: CommandExecutorOwner | null,
+  now: number,
+  graceMs: number = EXECUTOR_ORPHAN_GRACE_MS,
+): boolean {
+  if (!CLAIMED_ACTIVE_STATUSES.includes(command.status)) return false;
+  if (now - command.updatedAt < graceMs) return false;
+  return commandClaimantRestarted(claimOwnerToken, owner);
+}
+
+/**
+ * #2104 — the bare RECONNECT-STABLE discriminator {@link commandExecutorConfirmedGone} is built on,
+ * lifted out so a second consumer reuses the SAME rule instead of re-deriving it (the spawn-loss
+ * escalation in src/services/spawn-loss-escalation.ts, which must apply it to command statuses the
+ * merge reclaim deliberately excludes). It answers exactly one question — "is a strictly-different
+ * process now running under the orchestrator that CLAIMED this command?" — and nothing about the
+ * command's own status or age, which each caller gates on itself.
+ *
+ * Fail-safe in the same direction as its caller: an absent/offline owner, a command that was never
+ * claimed via the CAS (no captured token), or a pre-#2094 runner that reports no instance id is
+ * UNRESOLVABLE → `false` → the caller falls back to its own slower backstop, never to a more
+ * aggressive action.
+ */
+export function commandClaimantRestarted(claimOwnerToken: string | null, owner: CommandExecutorOwner | null): boolean {
+  if (!owner || owner.status !== "online") return false;
+  if (!claimOwnerToken || !owner.claimInstanceId) return false;
+  return claimOwnerTokenFingerprint(claimOwnerToken) !== owner.claimInstanceId;
+}
+
+/**
+ * #2102/#2148 — raw candidates behind the deploy-restart drain: claimed `workspace.merge` commands
+ * plus claimed `agent.spawn` commands whose runner has not registered, all within their lease. The
+ * liveness filter and the public status shape live in src/merge-drain.ts (which can reach the
+ * orchestrator DB this file deliberately must not import); this owns only the command-lifecycle half.
+ *
+ * The scope is CLAIMED-ACTIVE and WITHIN-LEASE, deliberately on both counts:
+ *  - `pending` is EXCLUDED. Pending work has no owning executor session to kill; a restarted host
+ *    simply re-polls it (the same premise {@link commandExecutorConfirmedGone} rests on). Counting it
+ *    would make a non-empty merge QUEUE — the steady state on a busy repo — read as permanently
+ *    draining, so every deploy would burn the whole ceiling and the interlock would decay into a
+ *    fixed delay that never actually protects anything.
+ *  - A cgroup-fenced `workspace.merge` PAST its `expires_at` remains INCLUDED. Expiry is only
+ *    reconciliation input; until positive execution proof atomically terminalizes the command, a live
+ *    Git child may still resume. Exact `legacy-unfenced-v0` rows and `agent.spawn` retain current-main's
+ *    ordinary within-lease filter.
+ *
+ * Bounded by construction: this is only concurrently-executing merges/spawns, so materializing rows
+ * is what lets the caller apply the per-row executor-liveness test a `count(*)` could not.
+ */
+export function activeRestartSensitiveCommands(now: number = Date.now()): Command[] {
+  // The type+status prefix is served by idx_commands_spawn_watchdog(type, status, updated_at); the
+  // lease predicate filters the few rows that survive it.
+  return (getDb()
+    .query(
+      `SELECT * FROM commands
+       WHERE type IN ('workspace.merge', 'agent.spawn')
+         AND status IN (${CLAIMED_ACTIVE_STATUSES.map(() => "?").join(",")})
+         AND ((type = 'workspace.merge'
+               AND (coalesce(landing_containment_mode, '') != 'legacy-unfenced-v0'
+                    OR expires_at IS NULL OR expires_at > ?))
+              OR (type = 'agent.spawn' AND (expires_at IS NULL OR expires_at > ?)))
+         AND (type != 'agent.spawn' OR coalesce(json_extract(params, '$.registrationConfirmed'), 0) != 1)
+       ORDER BY updated_at ASC`,
+    )
+    .all(...CLAIMED_ACTIVE_STATUSES, now, now) as CommandRow[]).map(rowToCommand);
+}
+
+// #1746 RC-2 / issue ask 4 — when a shutdown command settles WITHOUT a confirmed kill (the
+// orchestrator failed the command: `target-not-found`, or the process survived graceful+forceful
+// stop), surface a terminal `kill-failed` pill on the target agent instead of leaving the
+// `shutting-down` pill in-flight forever. The dashboard already renders `kill-failed` (display.ts) and
+// relay_my_agents reports it via childLifecycleStatus. A subsequent process-confirmed exit clears the
+// pill (recordAgentExitDiagnostics); the RC-3 watchdog can re-escalate a still-alive target.
+//
+// A SUCCESSFUL shutdown is intentionally NOT reconciled here: success means the process was confirmed
+// stopped, and the agent's own exit path clears the pill without disturbing its last-heartbeat clock —
+// doing it here would bump last_seen and could delay the stale reaper.
+function reconcileAgentLifecycleOnShutdownFailure(previousStatus: CommandStatus, command: Command): void {
+  if (command.type !== "agent.shutdown") return;
+  // Only a FRESH transition into a terminal FAILURE status; ignore succeeded and no-op re-settles.
+  if (!isTerminalStatus(command.status) || isTerminalStatus(previousStatus)) return;
+  if (command.status === "succeeded") return;
+  const agentId = stringValue(command.result?.agentId) ?? stringValue(command.params?.agentId);
+  if (!agentId) return;
+  const agent = getAgent(agentId);
+  if (!agent) return;
+  // Reconcile ONLY the pill THIS command set (shutdownAgent stamps lifecycleCommandId). A failure on
+  // the command channel for an unrelated/superseded command must never stamp kill-failed onto a
+  // healthy agent, and a confirmed exit that already cleared the pill must not be re-marked.
+  if (stringValue(agent.meta?.lifecycleCommandId) !== command.id) return;
+  mergeAgentMeta(agentId, { lifecycleAction: "kill-failed", lifecycleActionAt: Date.now() });
+}
+
+function recordShutdownTerminalEventOnSuccess(previousStatus: CommandStatus, command: Command): void {
+  if (command.type !== "agent.shutdown" || command.status !== "succeeded" || previousStatus === "succeeded") return;
+  const agentId = stringValue(command.result?.agentId) ?? stringValue(command.params?.agentId);
+  if (!agentId) return;
+  const agent = getAgent(agentId);
+  const epoch = agent?.epoch ?? 0;
+  if (getTerminalEvent(agentId, epoch)) return;
+  const hadReadySignal = !agent || agent.ready || typeof agent.meta?.readyNotifiedAt === "number";
+  recordTerminalEvent({
+    agentId,
+    reason: stringValue(command.result?.reason) ?? stringValue(command.params?.reason) ?? "shutdown",
+    kind: hadReadySignal ? "agent.exited" : "agent.spawn_failed",
+    epoch,
+    createdAt: Date.now(),
+  });
+}
+
+export const PARENT_REQUESTED_SHUTDOWN_SQL = `
+    SELECT params FROM commands INDEXED BY idx_commands_parent_shutdown
+    WHERE type = 'agent.shutdown'
+      AND status IN ('pending', 'accepted', 'running', 'succeeded')
+      AND created_at >= ?
+      AND json_extract(params, '$.agentId') = ?
+      AND json_extract(params, '$.spawnRequestId') = ?
+    ORDER BY created_at DESC
+    LIMIT 5
+  `;