@humwick/server 0.130.0 → 0.130.2

package/src/ci/transition-notify.ts

@@ -1,7 +1,7 @@
 import { stewardFallbackTarget } from "../config.ts";
 import { emitRelayEvent } from "../events.ts";
 import type { WorkspaceHumanEscalationResult } from "../workspace-human-escalation.ts";
-import { ingestCiObservation, ingestCiObservationAsync, type CiIncidentIngestResult } from "./incidents.ts";
+import { ingestCiObservationAsync, type CiIncidentIngestResult } from "./incidents.ts";
 import {
   routeCiIncidentNotification,
   type CiFailedNotificationPayload,
@@ -41,7 +41,7 @@ import type { CiObservation, CiRunRef } from "./provider.ts";
 export const CI_MAIN_WATCH_COORDINATOR = "cd-watcher";
 
 export interface CiTransitionNotifyDeps {
-  ingest?: (observation: CiObservation, now?: number) => CiIncidentIngestResult;
+  ingest?: (observation: CiObservation, now?: number) => CiIncidentIngestResult | Promise<CiIncidentIngestResult>;
   route?: (input: Parameters<typeof routeCiIncidentNotification>[0]) => RouteCiIncidentNotificationResult;
   /** Resolve the coordinator/owner agent the relay message addresses. Defaults to the configured
    * steward fallback, then the system watch actor. */
@@ -65,16 +65,17 @@ export interface CiTransitionNotifyResult {
  * Detect and (if a flip occurred) alert on a CI red/green transition for a single observed watch.
  * Idempotent per transition — safe to call every poll tick.
  */
-export function notifyCiTransition(
+export async function notifyCiTransition(
   observation: CiObservation | null | undefined,
   deps: CiTransitionNotifyDeps = {},
-): CiTransitionNotifyResult {
+): Promise<CiTransitionNotifyResult> {
   if (!observation) return { transition: "none", notified: false, messages: 0 };
-  const ingest = deps.ingest ?? ingestCiObservation;
+  const ingest = deps.ingest ?? ingestCiObservationAsync;
   const route = deps.route ?? routeCiIncidentNotification;
   const now = deps.now ?? Date.now();
 
-  const result = ingest(observation, now);
+  // Notification emission follows the committed transition (one writer op, #1870), never a pre-write observation.
+  const result = await ingest(observation, deps.now);
   emitCiStatus(result);
 
   if (result.kind === "opened") {
@@ -155,39 +156,6 @@ export function notifyCiTransition(
   return { transition: "none", ...(result.kind === "deduped" ? { incidentId: result.incident.id } : {}), notified: false, messages: 0 };
 }
 
-/** Gateway-routed companion for async maintenance polling. Notification emission follows the
- * committed transition, never a pre-write observation. */
-export async function notifyCiTransitionAsync(
-  observation: CiObservation | null | undefined,
-  deps: Omit<CiTransitionNotifyDeps, "ingest"> = {},
-): Promise<CiTransitionNotifyResult> {
-  if (!observation) return { transition: "none", notified: false, messages: 0 };
-  const route = deps.route ?? routeCiIncidentNotification;
-  const now = deps.now ?? Date.now();
-  const result = await ingestCiObservationAsync(observation);
-  emitCiStatus(result);
-  if (result.kind === "opened") {
-    const coordinatorAgentId = resolveCoordinator(deps);
-    const routed = route({ type: "ci.failed", payload: { incidentId: result.incident.id, provider: observation.provider, repository: observation.repository, branch: observation.branch, workflow: observation.workflow, failingHeadSha: observation.headSha, coordinatorAgentId, observedAt: observation.observedAt, ...(observation.conclusion ? { conclusion: observation.conclusion } : {}), failingRunIds: observation.failingRuns.map((run) => run.id), failingJobNames: failingJobNames(observation) }, alertHuman: true, subject: redSubject(observation), body: redBody(observation, result.incident.id) });
-    return { transition: "went_red", incidentId: result.incident.id, notified: true, messages: routed.messages.length, ...(routed.humanFallback ? { humanFallback: routed.humanFallback } : {}) };
-  }
-  if (result.kind === "resolved") {
-    const coordinatorAgentId = resolveCoordinator(deps);
-    const routed = route({ type: "ci.recovered", payload: { incidentId: result.incident.id, provider: observation.provider, repository: observation.repository, branch: observation.branch, workflow: observation.workflow, failingHeadSha: result.incident.openedHeadSha, coordinatorAgentId, recoveredAt: now, greenHeadSha: observation.headSha, ...(result.incident.resolution ? { resolution: result.incident.resolution } : {}) }, alertHuman: true, subject: greenSubject(observation), body: greenBody(observation, result.incident.id, result.incident.openedHeadSha) });
-    return { transition: "back_green", incidentId: result.incident.id, notified: true, messages: routed.messages.length, ...(routed.humanFallback ? { humanFallback: routed.humanFallback } : {}) };
-  }
-  if (result.kind === "never_matched") {
-    const coordinatorAgentId = resolveCoordinator(deps);
-    const routed = route({ type: "ci.never_matched", payload: { provider: observation.provider, repository: observation.repository, branch: observation.branch, workflow: observation.workflow, coordinatorAgentId, firstSeenAt: result.firstSeenAt, observedAt: observation.observedAt }, alertHuman: true, subject: neverMatchedSubject(observation), body: neverMatchedBody(observation) });
-    return { transition: "never_matched", notified: true, messages: routed.messages.length, ...(routed.humanFallback ? { humanFallback: routed.humanFallback } : {}) };
-  }
-  if (result.kind === "config_mismatch") {
-    const routed = route(configMismatchRoute(observation, resolveCoordinator(deps), result.unmatchedJobs));
-    return { transition: "config_mismatch", notified: true, messages: routed.messages.length, ...(routed.humanFallback ? { humanFallback: routed.humanFallback } : {}) };
-  }
-  return { transition: "none", ...(result.kind === "deduped" ? { incidentId: result.incident.id } : {}), notified: false, messages: 0 };
-}
-
 /** Live CI view (#3011): one `ci.status` event per watch status transition, never per poll. */
 function emitCiStatus(result: CiIncidentIngestResult): void {
   if (result.statusChange) emitRelayEvent({ type: "ci.status", source: "server", subject: result.watchKey, data: { ...result.statusChange } });

package/src/cli/cd-pauses.ts

@@ -0,0 +1,19 @@
+import type { CdPause, CdPauseControl } from "../state-adoption/cd-cutover";
+import { apiRequest, ApiRequestError } from "./_shared";
+
+/** The audited maintenance pause API (#1645) shared by local and fleet cutovers (#3470). */
+export const cdWatcherPauses: CdPauseControl = {
+  async pause(holder, reason) {
+    try {
+      return ((await apiRequest("POST", "/api/maintenance/jobs/cd-watcher/pause", { holder, reason, indefinite: true })) as { pause: CdPause }).pause;
+    } catch (error) {
+      if (error instanceof ApiRequestError && error.status === 409) return (error.responseBody as { pause: CdPause }).pause;
+      throw error;
+    }
+  },
+  async current() {
+    const { pauses } = (await apiRequest("GET", "/api/maintenance/pauses")) as { pauses: Array<CdPause & { jobId: string }> };
+    return pauses.find((pause) => pause.jobId === "cd-watcher") ?? null;
+  },
+  async resume() { await apiRequest("POST", "/api/maintenance/jobs/cd-watcher/resume"); },
+};

package/src/cli/orchestrator.ts

@@ -118,7 +118,7 @@ export async function handleOrchestratorCommand(args: string[]): Promise<void> {
   // Install the server package too so a real `humwick` bin lands in the
   // runtime .bin dir (#1421): under bunx there is no global install, so without
   // this the darwin shim below would point at a bin that does not exist.
-  const packageCommand = skipInstall ? [] : ["npm", "install", "--prefix", runtimePrefix, `agent-relay-runner@${version}`, `agent-relay-orchestrator@${version}`, `agent-relay-server@${version}`, OPENCODE_HARNESS_PACKAGE];
+  const packageCommand = skipInstall ? [] : ["npm", "install", "--prefix", runtimePrefix, `@humwick/runner@${version}`, `@humwick/orchestrator@${version}`, `@humwick/server@${version}`, OPENCODE_HARNESS_PACKAGE];
   // W1: on macOS, put `humwick` on the interactive PATH (shim + profile
   // block). Gated to darwin — Linux global-npm installs already get the shim via
   // the postinstall, and we avoid editing Linux user profiles unnecessarily.

package/src/cli/state.ts

@@ -2,8 +2,7 @@ import { readFileSync } from "node:fs";
 import { adoptMacos } from "../state-adoption/macos";
 import { adoptLinux } from "../state-adoption/linux";
 import { adoptState } from "../state-adoption";
-import type { CdPause, CdPauseControl } from "../state-adoption/cd-cutover";
-import { apiRequest, ApiRequestError } from "./_shared";
+import { cdWatcherPauses } from "./cd-pauses";
 
 export const STATE_USAGE = "humwick state adopt|linux-adopt|macos-adopt|cd-cutover|cd-resume --manifest PATH [--interrupt-after STEP] [--rollback] [--systemctl PATH] [--launchctl PATH]";
 const COMMANDS = ["adopt", "linux-adopt", "macos-adopt", "cd-cutover", "cd-resume"];
@@ -43,6 +42,7 @@ export async function handleStateCommand(args: string[]): Promise<void> {
 async function cdCutover(command: string, input: any, options: { rollback: boolean; systemctl?: string; launchctl?: string; interrupt: (step: string) => void }) {
   const { runCutover, resumeCutoverCd } = await import("../state-adoption/cd-cutover");
   if (command === "cd-resume") return resumeCutoverCd(input, cdWatcherPauses);
+  if (input?.fleet) throw new Error("Fleet activation uses bun run release --deploy-only --cutover-manifest PATH under the existing executor");
   const [{ resolveCanonicalRelayDbPath, withDeployLedgerDb }, { resolveReleaseLocalOrchestratorId }] = await Promise.all([
     import("../../scripts/cd-config"), import("../../scripts/release-upgrade")]);
   const dbPath = resolveCanonicalRelayDbPath();
@@ -54,20 +54,3 @@ async function cdCutover(command: string, input: any, options: { rollback: boole
       : adoptLinux(input.handoff, { rollback, systemctl: options.systemctl, interrupt: options.interrupt }),
   });
 }
-
-/** The audited maintenance pause API (#1645) for cd-watcher; an existing pause is returned, ours or not. */
-const cdWatcherPauses: CdPauseControl = {
-  async pause(holder, reason) {
-    try {
-      return ((await apiRequest("POST", "/api/maintenance/jobs/cd-watcher/pause", { holder, reason, indefinite: true })) as { pause: CdPause }).pause;
-    } catch (error) {
-      if (error instanceof ApiRequestError && error.status === 409) return (error.responseBody as { pause: CdPause }).pause;
-      throw error;
-    }
-  },
-  async current() {
-    const { pauses } = (await apiRequest("GET", "/api/maintenance/pauses")) as { pauses: Array<CdPause & { jobId: string }> };
-    return pauses.find((pause) => pause.jobId === "cd-watcher") ?? null;
-  },
-  async resume() { await apiRequest("POST", "/api/maintenance/jobs/cd-watcher/resume"); },
-};

package/src/cli/task-edit.ts

@@ -0,0 +1,22 @@
+import { parseTaskIdValue } from "../validation";
+import { apiRequest } from "./_shared";
+
+const fields: Record<string, string> = { "--title": "title", "--intent": "intent", "--done-when": "doneWhen", "--on-deploy": "onDeploy", "--team": "teamId", "--repo": "repo" };
+
+export async function editTaskCommand(args: string[]): Promise<void> {
+  const create = args[0] === "create";
+  const id = create ? undefined : parseTaskIdValue(args[1] ?? "");
+  if (!create && !id) throw new Error("taskId must be a positive integer (TNNNN accepted)");
+  const body: Record<string, string> = {};
+  for (let i = create ? 1 : 2; i < args.length; i++) {
+    const flag = args[i]!;
+    if (flag === "--json") continue;
+    const field = fields[flag];
+    if (!field || i + 1 >= args.length) throw new Error(`Unknown or missing task ${args[0]} option: ${flag}`);
+    body[field] = args[++i]!;
+  }
+  if (create && (!body.title || !body.intent)) throw new Error("task create requires --title and --intent");
+  if (!Object.keys(body).length) throw new Error("task update requires a field such as --on-deploy");
+  const result = await apiRequest(create ? "POST" : "PATCH", create ? "/api/tasks" : `/api/tasks/${id}`, body);
+  console.log(JSON.stringify(result, null, 2));
+}

package/src/cli/task.ts

@@ -1,3 +1,4 @@
+import { editTaskCommand } from "./task-edit";
 // Task commands — #2518 review-hold control (`humwick task review-hold …`) + #2312
 // withdraw-land (`humwick task withdraw-land …`). Thin HTTP clients (same apiRequest seam
 // as workspace.ts): all policy — coordinator-only authorization, the expected-HEAD CAS,
@@ -11,7 +12,7 @@ function parseTaskId(raw: string | undefined): number | null {
   return raw === undefined ? null : parseTaskIdValue(raw);
 }
 
-export const TASK_USAGE = "Usage: humwick task get <taskId> [--verbose] [--json] | humwick task review-hold <taskId> <status|set|clear> [--expected-head SHA] [--reason TEXT] [--json] | humwick task withdraw-land <workspaceId> [--reason TEXT] [--json]";
+export const TASK_USAGE = "Usage: humwick task create --title TEXT --intent TEXT [--on-deploy TEXT] | humwick task update <taskId> [--on-deploy TEXT] | humwick task get <taskId> [--verbose] [--json] | humwick task review-hold <taskId> <status|set|clear> [--expected-head SHA] [--reason TEXT] [--json] | humwick task withdraw-land <workspaceId> [--reason TEXT] [--json]";
 
 interface ReviewHoldStatusView {
   id: number;
@@ -48,6 +49,7 @@ function renderStatus(task: ReviewHoldStatusView): string {
 
 export async function handleTaskCommand(args: string[]): Promise<void> {
   const sub = args[0];
+  if (sub === "create" || sub === "update") return editTaskCommand(args);
   if (sub === "get") {
     const taskId = parseTaskId(args[1]);
     if (taskId === null) throw new Error(`taskId must be a positive integer (TNNNN accepted). ${TASK_USAGE}`);

package/src/cli/workflow.ts

@@ -1,7 +1,7 @@
 import { apiRequest } from "./_shared";
 import { probeWorkflowDeployment } from "../../scripts/wait-for-deploy";
 
-export const WORKFLOW_USAGE = "Usage: humwick workflow start <workflow> <taskId> [--json] | workflow get <runId> [--verbose] [--include-held] [--results-ref <id>] [--results-cursor <cursor>] [--json] | workflow resume <runId> [--activation <id>]";
+export const WORKFLOW_USAGE = "Usage: humwick workflow start <workflow> <taskId> [--json] | workflow get <runId> [--verbose] [--include-held] [--results-ref <id>] [--results-cursor <cursor>] [--json] | workflow resume <runId> [--activation <id>] | workflow pause <runId> --reason <text> | workflow unpause <runId>";
 
 export async function handleWorkflowCommand(args: string[]): Promise<void> {
   const [command, runId, ...flags] = args;
@@ -25,7 +25,13 @@ export async function handleWorkflowCommand(args: string[]): Promise<void> {
     }
     return;
   }
-  if (!["get", "resume"].includes(command ?? "") || !runId || runId.startsWith("--")) throw new Error(WORKFLOW_USAGE);
+  if (!["get", "resume", "pause", "unpause"].includes(command ?? "") || !runId || runId.startsWith("--")) throw new Error(WORKFLOW_USAGE);
+  if (command === "pause" || command === "unpause") {
+    // #3757 — a pause says why the run waits; the server refuses an empty reason.
+    if (command === "pause" ? flags.length !== 2 || flags[0] !== "--reason" || !flags[1]?.trim() : flags.length) throw new Error(WORKFLOW_USAGE);
+    console.log(JSON.stringify(await apiRequest("POST", `/api/workflows/runs/${encodeURIComponent(runId)}/${command}`, command === "pause" ? { reason: flags[1] } : {}), null, 2));
+    return;
+  }
   if (command === "resume") {
     if (flags.length && (flags[0] !== "--activation" || flags.length !== 2 || !flags[1])) throw new Error(WORKFLOW_USAGE);
     console.log(JSON.stringify(await apiRequest("POST", `/api/workflows/runs/${encodeURIComponent(runId)}/resume`, { ...(flags[1] ? { activationId: flags[1] } : {}) }), null, 2));

package/src/commands-db.ts

@@ -305,7 +305,7 @@ 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);
+  return (getDb().query(sql).all(...params as any[]) as CommandRow[]).map((row) => rowToCommand(row, { slim: filters.slim }));
 }
 
 
@@ -814,8 +814,8 @@ export function updateCommand(id: string, input: UpdateCommandInput, opts: Updat
   return applyCommandUpdatePostCommit(result.previousStatus, result.command);
 }
 
-export function deleteCommand(id: string): boolean {
-  const existing = getCommand(id);
+/** 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;
@@ -823,7 +823,11 @@ export function deleteCommand(id: string): boolean {
   // 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.
-  if (existing.status === "accepted" && isClaimGatedReviewCommand(existing.type)) return false;
+  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;
 }
@@ -916,7 +920,7 @@ export const ACCEPTED_BY_OWNER_SQL = `SELECT * FROM commands INDEXED BY idx_comm
 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);
+  return rows.map((row) => rowToCommand(row));
 }
 
 // #1452 round-12 HIGH#2 — RE-FENCE a claimed review-publish command IMMEDIATELY before the host's
@@ -1138,7 +1142,7 @@ export function activeRestartSensitiveCommands(now: number = Date.now()): Comman
          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);
+    .all(...CLAIMED_ACTIVE_STATUSES, now, now) as CommandRow[]).map((row) => rowToCommand(row));
 }
 
 // #1746 RC-2 / issue ask 4 — when a shutdown command settles WITHOUT a confirmed kill (the

package/src/commands-write.ts

@@ -11,6 +11,7 @@ import { STALE_TTL_MS } from "./config.ts";
 import { bufferedLiveAgentIds } from "./db/presence-buffer.ts";
 import { getGateway } from "./db/gateway.ts";
 import {
+  commandDeletable,
   commandUpdateHasPostCommitEffects,
   type CreateCommandOptions,
   type CreateCommandWriteArgs,
@@ -120,6 +121,13 @@ export async function updateCommandAsync(
   return result.command;
 }
 
+/** Public DELETE (#1870 S6a): the cancel is a normal off-loop patch, so it never writes on the main thread. */
+export async function deleteCommandAsync(id: string): Promise<boolean> {
+  if (!commandDeletable(await getCommandAsync(id))) return false;
+  await updateCommandAsync(id, { status: "canceled", error: "canceled" });
+  return true;
+}
+
 /** Atomically cancel only if the command is still in the caller's expected live statuses. */
 export function cancelCommandIfStatusAsync(
   args: CancelCommandIfStatusWriteArgs,

package/src/config-store-write.ts

@@ -6,7 +6,8 @@
 
 import { randomUUID } from "node:crypto";
 import { getGateway } from "./db/gateway.ts";
-import type { ConfigEntry } from "./types.ts";
+import { agentProfileDeleteTarget, agentProfileWriteNamespace, savedAgentProfileEntry } from "./config-store.ts";
+import type { AgentProfile, ConfigEntry } from "./types.ts";
 
 /**
  * Set a config entry off-loop (landmine #2). Routes through a single serialized `config.set` writer op
@@ -37,3 +38,14 @@ export function setConfigAsync<T = unknown>(
 export function deleteConfigAsync(namespace: string, key: string, updatedBy?: string): Promise<boolean> {
   return getGateway().write("config.delete", { namespace, key, updatedBy }) as unknown as Promise<boolean>;
 }
+
+/** `setAgentProfile` on the writer thread (#1870 S7). */
+export async function setAgentProfileAsync(profile: AgentProfile, updatedBy?: string, opts: { overrideBuiltIn?: boolean } = {}): Promise<ConfigEntry<AgentProfile>> {
+  return savedAgentProfileEntry(await setConfigAsync(agentProfileWriteNamespace(profile, opts), profile.name, profile, updatedBy));
+}
+
+/** `deleteAgentProfile` on the writer thread (#1870 S7). */
+export function deleteAgentProfileAsync(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): Promise<boolean> {
+  const target = agentProfileDeleteTarget(name, opts);
+  return deleteConfigAsync(target.namespace, target.key, updatedBy);
+}

package/src/config-store.ts

@@ -1120,24 +1120,35 @@ export function listAgentProfiles(): ConfigEntry<AgentProfile>[] {
   ].sort((a, b) => Number(Boolean(b.value.builtIn)) - Number(Boolean(a.value.builtIn)) || a.key.localeCompare(b.key));
 }
 
+/** Where a profile write lands: a built-in's override row, else its own row. The rollback snapshot is
+ *  dropped by setConfigInternal on an override write (#1963 N10). */
+export function agentProfileWriteNamespace(profile: AgentProfile, opts: { overrideBuiltIn?: boolean } = {}): string {
+  return BUILT_IN_AGENT_PROFILE_NAMES.has(profile.name) && opts.overrideBuiltIn ? AGENT_PROFILE_OVERRIDE_NAMESPACE : AGENT_PROFILE_NAMESPACE;
+}
+
+/** The stored entry a profile write returns: an override reads back merged over its built-in. */
+export function savedAgentProfileEntry(saved: ConfigEntry<AgentProfile>): ConfigEntry<AgentProfile> {
+  return saved.namespace === AGENT_PROFILE_OVERRIDE_NAMESPACE ? getAgentProfile(saved.key)! : applyProfilePromptEntry(saved)!;
+}
+
+/** Sync twin for tests and boot; runtime callers use `setAgentProfileAsync` (#1870 S7). */
 export function setAgentProfile(profile: AgentProfile, updatedBy?: string, opts: { overrideBuiltIn?: boolean } = {}): ConfigEntry<AgentProfile> {
-  if (BUILT_IN_AGENT_PROFILE_NAMES.has(profile.name) && opts.overrideBuiltIn) {
-    // The rollback snapshot is dropped by setConfigInternal on this override write (#1963 N10).
-    setConfig(AGENT_PROFILE_OVERRIDE_NAMESPACE, profile.name, profile, updatedBy);
-    return getAgentProfile(profile.name)!;
-  }
-  return applyProfilePromptEntry(setConfig(AGENT_PROFILE_NAMESPACE, profile.name, profile, updatedBy))!;
+  return savedAgentProfileEntry(setConfig(agentProfileWriteNamespace(profile, opts), profile.name, profile, updatedBy));
 }
 
-export function deleteAgentProfile(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): boolean {
-  // #2791 — delete resolves case-insensitively to the stored key, so DELETE /qa drops "QA".
+/** The row a profile delete removes. #2791 — resolves case-insensitively, so DELETE /qa drops "QA". The
+ *  rollback snapshot is dropped by deleteConfigInternal on an override delete (#1963 N10). */
+export function agentProfileDeleteTarget(name: string, opts: { resetBuiltInOverride?: boolean } = {}): { namespace: string; key: string } {
   const canonical = resolveAgentProfileKey(name) ?? name;
-  if (BUILT_IN_AGENT_PROFILE_NAMES.has(canonical)) {
-    // The rollback snapshot is dropped by deleteConfigInternal on this override delete (#1963 N10).
-    if (opts.resetBuiltInOverride) return deleteConfig(AGENT_PROFILE_OVERRIDE_NAMESPACE, canonical, updatedBy);
-    throw new ValidationError("built-in agent profiles are managed by Relay");
-  }
-  return deleteConfig(AGENT_PROFILE_NAMESPACE, canonical, updatedBy);
+  if (!BUILT_IN_AGENT_PROFILE_NAMES.has(canonical)) return { namespace: AGENT_PROFILE_NAMESPACE, key: canonical };
+  if (opts.resetBuiltInOverride) return { namespace: AGENT_PROFILE_OVERRIDE_NAMESPACE, key: canonical };
+  throw new ValidationError("built-in agent profiles are managed by Relay");
+}
+
+/** Sync twin for tests; runtime callers use `deleteAgentProfileAsync` (#1870 S7). */
+export function deleteAgentProfile(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): boolean {
+  const target = agentProfileDeleteTarget(name, opts);
+  return deleteConfig(target.namespace, target.key, updatedBy);
 }
 
 export function getManagedAgentState(policyName: string): ManagedAgentState | null {

package/src/db/activity-async.ts

@@ -4,7 +4,7 @@
 import { activityWriteIdempotencyKey } from "./activity-write-ops.ts";
 import { getGateway } from "./gateway.ts";
 import type { ActivityEvent, ActivityEventInput } from "../types";
-import type { AgentIssueActivitySummary, AgentTimelineEntry, IssueActivityAction, IssueActivityAgentSummary, RecordIssueActivityInput } from "./activity.ts";
+import type { AgentIssueActivitySummary, CreateActivityEventResult, AgentTimelineEntry, IssueActivityAction, IssueActivityAgentSummary, RecordIssueActivityInput } from "./activity.ts";
 
 export async function listActivityEventsAsync(input: {
   operatorId?: string;
@@ -43,6 +43,11 @@ export async function createActivityEventAsync(input: ActivityEventInput, idempo
   return (await getGateway().write("activity.create", { input }, { idempotencyKey: key })) as unknown as ActivityEvent;
 }
 
+/** Creates by `clientId` and reports whether this call created the row (false: the id already existed). */
+export async function createActivityEventByClientIdAsync(input: ActivityEventInput & { clientId: string }): Promise<CreateActivityEventResult> {
+  return (await getGateway().write("activity.createByClientId", { input })) as unknown as CreateActivityEventResult;
+}
+
 /** See `createActivityEventAsync` — same `idempotent: false` / key-derivation contract. */
 export async function recordIssueActivityAsync(input: RecordIssueActivityInput, idempotencyKey?: string): Promise<ActivityEvent> {
   const key = activityWriteIdempotencyKey(idempotencyKey, input.clientId);

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

@@ -14,7 +14,8 @@
 // "do not blindly retry").
 
 import { randomUUID } from "node:crypto";
-import { createActivityEvent, recordIssueActivity } from "./activity.ts";
+import { createActivityEvent, createActivityEventWithResult, recordIssueActivity } from "./activity.ts";
+import type { CreateActivityEventResult } from "./activity.ts";
 import type { ActivityEvent, ActivityEventInput } from "../types";
 import type { RecordIssueActivityInput } from "./activity.ts";
 import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
@@ -28,7 +29,18 @@ export const ACTIVITY_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object
     idempotent: false,
     fn: (args: ActivityCreateOpArgs, ctx: WriterOpContext): ActivityEvent => createActivityEvent(args.input, ctx.now),
   },
+  // Dedups on `clientId` inside the body, so a replay reports `created: false` truthfully; the idempotency
+  // ledger would instead replay the first `created: true` (#1870 S7, operator alarms).
+  "activity.createByClientId": {
+    offLoop: true,
+    idempotent: true,
+    fn: (args: ActivityCreateOpArgs, ctx: WriterOpContext): CreateActivityEventResult => {
+      if (!args.input.clientId) throw new Error("activity.createByClientId requires input.clientId");
+      return createActivityEventWithResult(args.input, ctx.now);
+    },
+  },
   "activity.recordIssueActivity": {
+    offLoop: true,
     idempotent: false,
     fn: (args: ActivityRecordIssueOpArgs, ctx: WriterOpContext): ActivityEvent => recordIssueActivity(args.input, ctx.now),
   },

package/src/db/activity.ts

@@ -1,18 +1,5 @@
-import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "@humwick/sdk";
-import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
+import { isRecord, stringValue } from "@humwick/sdk";
 import { parseJson } from "../utils";
-import { isLiveIsolatedWorkspace } from "../workspace-phase";
-import {
-  CONTRACT_REQUIREMENTS,
-  contractCompatibility,
-  parseRuntimeCapabilities,
-  parseRuntimeContracts,
-  parseRuntimePackage,
-  type RuntimeContracts,
-} from "../contracts";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
-import { matchAgents } from "../agent-ref";
 import { getDb, ValidationError } from "./connection.ts";
 import { rowToActivityEvent } from "./mappers.ts";
 import { getIssueRef, resolveIssueRefFromString } from "./issue-refs.ts";

package/src/db/agent-lifecycle-write-ops.ts

@@ -66,6 +66,7 @@ export const AGENT_LIFECYCLE_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> =
       instanceSuperseded(args.agentId, args.expectedEpoch) ? [] : releaseWorkspaceClaimsForAgent(args.agentId, args.now),
   },
   "agents.seedContinuationObjective": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsSeedContinuationOpArgs, ctx: WriterOpContext): null => {
       seedContinuationObjectiveFromSpawnPrompt(args.agentId, args.spawnRequestId, ctx.now);

package/src/db/agent-meta.ts

@@ -1,4 +1,3 @@
-import { mainThreadRegistry } from "./main-thread-state";
 // Agent meta has two storage temperatures: small runtime fields change on status frames, while the
 // launch projection is fixed for the life of a runner instance. Keep the latter out of `agents.meta`
 // so a hot status update never has to carry it through its JSON patch.
@@ -7,7 +6,8 @@ import { isRecord } from "@humwick/sdk";
 
 export const AGENT_META_WARN_BYTES = 64 * 1024;
 
-const warnedOversizeMeta = mainThreadRegistry("agent-meta.ts:warnedOversizeMeta", new Set<string>());
+// Log dedupe only, so a per-thread copy is correct: the writer thread warns once itself (#1870 S6c).
+const warnedOversizeMeta = new Set<string>();
 
 export interface StoredAgentMeta {
   meta: Record<string, unknown>;

package/src/db/agent-ownership-write-ops.ts

@@ -23,10 +23,12 @@ export interface AgentOwnershipReassignOpArgs { fromUserId: string; toUserId: st
 
 export const AGENT_OWNERSHIP_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
   "agent-ownership.set": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentOwnershipSetOpArgs, ctx: WriterOpContext): AgentOwnership => setAgentOwnership(args.input, ctx.now),
   },
   "agent-ownership.delete": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentOwnershipDeleteOpArgs): null => {
       deleteAgentOwnership(args.agentId);
@@ -36,6 +38,7 @@ export const AGENT_OWNERSHIP_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> =
   // Back-compat migration sweep (#392) — re-running converges (`INSERT ... WHERE NOT EXISTS`), so no
   // args and idempotent: true.
   "agent-ownership.seedDefault": {
+    offLoop: true,
     idempotent: true,
     fn: (_args: unknown, ctx: WriterOpContext): null => {
       seedDefaultAgentOwnership(ctx.now);
@@ -44,6 +47,7 @@ export const AGENT_OWNERSHIP_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> =
   },
   // #3567 H4 admin handover — re-applying finds nothing left on the old owner, so it converges.
   "agent-ownership.reassign": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentOwnershipReassignOpArgs, ctx: WriterOpContext): string[] => reassignAgentOwnership(args.fromUserId, args.toUserId, ctx.now),
   },

package/src/db/agent-search.ts

@@ -1,18 +1,4 @@
-import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "@humwick/sdk";
-import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
-import { parseJson } from "../utils";
-import { isLiveIsolatedWorkspace } from "../workspace-phase";
-import {
-  CONTRACT_REQUIREMENTS,
-  contractCompatibility,
-  parseRuntimeCapabilities,
-  parseRuntimeContracts,
-  parseRuntimePackage,
-  type RuntimeContracts,
-} from "../contracts";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
-import { matchAgents } from "../agent-ref";
+import { STALE_TTL_MS } from "../config";
 import { ROSTER_AGENT_COLUMNS } from "./agent-card-read.ts";
 import { getDb } from "./connection.ts";
 import { rowToAgent } from "./mappers.ts";

package/src/db/agents-async.ts

@@ -11,8 +11,16 @@
 
 import { agentSessionGuardResult } from "./agent-predicates.ts";
 import {
+  agentLifecycleWriteArgs,
+  bufferOrBypassHeartbeat,
   getAgent,
+  prepareAgentLifecycleUpdate,
   runBeforeAgentStatusTransitionHandlers,
+  type AgentLifecycleUpdate,
+  type AgentLifecycleUpdateResult,
+  type HeartbeatInput,
+  type OrphanedTokenPage,
+  type OrphanedTokenRevocation,
   validateAgentSession,
   type UpsertAgentTxResult,
   type UpsertAgentOptions,
@@ -52,8 +60,12 @@ export async function upsertAgentAsync(
 ): Promise<AgentCard> {
   // #2111 — allocated before the await, per the ordinal-timing rule at the top of setStatusAsync.
   const seq = nextLifecycleSeq();
-  const { agent, contextState } = (await getGateway().write("agents.upsert", { input, opts, seq })) as unknown as UpsertAgentTxResult;
-  if (contextState) await recordContextSnapshotAsync(input.id, contextState);
+  return finishAgentUpsertAsync(input.id, (await getGateway().write("agents.upsert", { input, opts, seq })) as unknown as UpsertAgentTxResult);
+}
+
+/** The registration's follow-ups after its row committed. Shared with `upsertOrchestratorAsync`. */
+export async function finishAgentUpsertAsync(inputId: string, { agent, contextState }: UpsertAgentTxResult): Promise<AgentCard> {
+  if (contextState) await recordContextSnapshotAsync(inputId, contextState);
   evictPendingPresence(agent.id);
   // Both effects settle on the writer. The `spawnRequestId` guard is `seedContinuationObjectiveFromSpawnPrompt`'s
   // own first condition, hoisted here so a registration without one costs no thread hop at all.
@@ -205,6 +217,31 @@ export async function recordAgentExitDiagnosticsAsync(
   return getAgentAsync(id);
 }
 
+/** `applyAgentLifecycleUpdate` with the write on the writer thread (#1870 S7). The guard, the `before` read
+ *  and the transition handlers stay on the main thread ahead of submission; the op CAS-fences on
+ *  `before.epoch`, so a takeover that lands in the hop turns this into a no-op instead of a clobber. */
+export async function applyAgentLifecycleUpdateAsync(
+  id: string,
+  update: AgentLifecycleUpdate,
+  guard?: AgentSessionGuard,
+  now: number = Date.now(),
+): Promise<AgentLifecycleUpdateResult> {
+  // Allocated first, per the ordinal-timing rule at the top of setStatusAsync.
+  const seq = nextLifecycleSeq();
+  const before = prepareAgentLifecycleUpdate(id, update, guard);
+  if (!before) return { ok: false, changed: false, metaWriteBytes: 0, before: null, after: null };
+  const result = (await getGateway().write("agents.applyLifecycleUpdate", agentLifecycleWriteArgs(before, update, seq, now))) as unknown as Omit<AgentLifecycleUpdateResult, "ok" | "before">;
+  return { ok: true, before, ...result };
+}
+
+/** `recordHeartbeat` for the transports: a steady-state beat is buffered at once; a presence-critical one
+ *  writes on the writer thread (#1870 S7). */
+export async function recordHeartbeatAsync(id: string, opts: HeartbeatInput = {}): Promise<boolean> {
+  const beat = bufferOrBypassHeartbeat(id, opts);
+  if (typeof beat === "boolean") return beat;
+  return (await applyAgentLifecycleUpdateAsync(id, beat, opts.guard, opts.now ?? Date.now())).changed;
+}
+
 export async function heartbeatAsync(
   id: string,
   guard?: AgentSessionGuard,
@@ -315,14 +352,28 @@ export async function deleteAgentAsync(id: string): Promise<{ ok: boolean; error
   return deleted ? { ok: true } : { ok: false, error: "agent not found" };
 }
 
+// #3776 — the sweep is one short writer op per page of agents (each agent's lineage revoke stays atomic), so
+// other writes interleave between pages. It stops when aborted or past its budget; the next run starts over.
+const ORPHAN_SWEEP_PAGE_SIZE = 8;
+const ORPHAN_SWEEP_BUDGET_MS = 30_000;
+
 export async function revokeOrphanedRuntimeTokensAsync(
   graceMs: number = STALE_TTL_MS,
   lagGraceMs = 0,
-): Promise<Array<{ agentId: string; jtis: string[] }>> {
-  return (await getGateway().write("agents.revokeOrphanedTokens", { graceMs, lagGraceMs })) as unknown as Array<{
-    agentId: string;
-    jtis: string[];
-  }>;
+  options: { signal?: AbortSignal; budgetMs?: number; pageSize?: number } = {},
+): Promise<{ revoked: OrphanedTokenRevocation[]; complete: boolean }> {
+  const { signal, budgetMs = ORPHAN_SWEEP_BUDGET_MS, pageSize = ORPHAN_SWEEP_PAGE_SIZE } = options;
+  const deadline = Date.now() + budgetMs;
+  const revoked: OrphanedTokenRevocation[] = [];
+  let afterId: string | undefined;
+  do {
+    if (signal?.aborted) return { revoked, complete: false };
+    const page = (await getGateway().write("agents.revokeOrphanedTokens", { graceMs, lagGraceMs, afterId, limit: pageSize })) as unknown as OrphanedTokenPage;
+    revoked.push(...page.revoked);
+    if (page.nextAfterId === null) return { revoked, complete: true };
+    afterId = page.nextAfterId;
+  } while (Date.now() < deadline);
+  return { revoked, complete: false };
 }
 
 export async function revokeRuntimeTokensForAgentAsync(