@humwick/server 0.130.1 → 0.130.2

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 }));
 }
 
 
@@ -920,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
@@ -1142,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/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,6 +29,16 @@ 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,

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-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,
@@ -209,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,
@@ -319,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(

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

@@ -19,6 +19,8 @@ import { applyIdleSelfCare } from "./idle-self-care";
 // write (none of these are) would need `idempotent: false` plus a caller-supplied key.
 
 import {
+  applyAgentLifecycleUpdateInternal,
+  type AgentLifecycleWriteArgs,
   clearAgentMetaKeys,
   deleteAgentInternal,
   heartbeat,
@@ -41,6 +43,7 @@ import {
 import { pruneOfflineAgentsWithFinality, type AgentsPruneOfflineOpArgs } from "./agents-prune-write-op.ts";
 import { setAgentKeepState } from "./agent-keep.ts";
 import type { AgentCard, AgentKeep, AgentSessionGuard, ContextState, ManagedSessionExitDiagnostics, ProviderCapabilities, QuotaState, RegisterAgentInput } from "../types";
+import type { OrphanedTokenPage } from "./agents.ts";
 import type { LineageRevokeReason } from "./token-standing.ts";
 import type { LifecycleWriteOutcome } from "./lifecycle-seq.ts";
 import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
@@ -69,7 +72,7 @@ export interface AgentsHeartbeatOpArgs {
 export interface AgentsRecordContextSnapshotOpArgs { agentId: string; context: ContextState }
 export interface AgentsReapStaleOpArgs { ttlMs: number; lagGraceMs: number; protectedIds?: string[]; seq: number }
 export interface AgentsDeleteOpArgs { id: string }
-export interface AgentsRevokeOrphanedTokensOpArgs { graceMs: number; lagGraceMs: number }
+export interface AgentsRevokeOrphanedTokensOpArgs { graceMs: number; lagGraceMs: number; afterId?: string; limit?: number }
 export interface AgentsRevokeTokensForAgentOpArgs { agentId: string; reason?: LineageRevokeReason }
 
 export const AGENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
@@ -107,6 +110,12 @@ export const AGENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.f
   // coalescing window buffered them) and return a tri-state: `superseded` means a later-submitted
   // lifecycle write already landed, which is a SUCCESS for the caller and must not be mistaken for a
   // missing agent. See lifecycle-seq.ts.
+  "agents.applyLifecycleUpdate": {
+    // #1870 S7: bus status frame and heartbeat bypass; a replay of the same `seq` is a no-op on the fenced columns.
+    offLoop: true,
+    idempotent: true,
+    fn: (args: AgentLifecycleWriteArgs) => applyAgentLifecycleUpdateInternal(args),
+  },
   "agents.setStatus": {
     offLoop: true,
     idempotent: true,
@@ -176,8 +185,8 @@ export const AGENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.f
   "agents.revokeOrphanedTokens": {
     offLoop: true,
     idempotent: true,
-    fn: (args: AgentsRevokeOrphanedTokensOpArgs, ctx: WriterOpContext): Array<{ agentId: string; jtis: string[] }> =>
-      revokeOrphanedRuntimeTokens(args.graceMs, args.lagGraceMs, ctx.now),
+    fn: (args: AgentsRevokeOrphanedTokensOpArgs, ctx: WriterOpContext): OrphanedTokenPage =>
+      revokeOrphanedRuntimeTokens(args.graceMs, args.lagGraceMs, ctx.now, { afterId: args.afterId, limit: args.limit }),
   },
   "agents.revokeTokensForAgent": {
     offLoop: true,