bunqueue-dashboard 0.0.37 → 0.0.39

package/README.md

@@ -26,9 +26,9 @@ The full dashboard running on sample data, no server needed.
 
 ![React 19](https://img.shields.io/badge/React-19-149ECA?logo=react&logoColor=white)
 ![Vite 8](https://img.shields.io/badge/Vite-8-646CFF?logo=vite&logoColor=white)
-![Bun](https://img.shields.io/badge/Bun-1.3-000?logo=bun&logoColor=white)
+![Bun](https://img.shields.io/badge/Bun-1.4-000?logo=bun&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
-![Biome](https://img.shields.io/badge/Biome-lint%20%2B%20format-60A5FA?logo=biome&logoColor=white)
+![Oxlint + Oxfmt](https://img.shields.io/badge/Oxc-Oxlint%20%2B%20Oxfmt-7C3AED)
 
 <br />
 
@@ -90,13 +90,13 @@ The full dashboard running on sample data, no server needed.
 bunqueue exposes a rich HTTP API, but operating it by hand (curl, ad-hoc scripts) is slow and
 error-prone. This dashboard is a production-oriented operator console: it exposes the verified,
 safe subset of the API, fails closed where
-[v2.8.59](https://github.com/egeominotti/bunqueue/releases/tag/v2.8.59) lacks atomic
+[Bunqueue 2.9.x](https://github.com/egeominotti/bunqueue/releases/tag/v2.9.2) lacks atomic
 flow-safety guarantees, and also manages the
 server *process* through a separate guarded agent.
 
 It uses Bunqueue's public HTTP API (`:6790`) for ordinary remote observability and a small local
 **control agent** for process, FlowProducer, Workflow Engine, database, and backup operations. The
-agent is pinned to the server it manages and uses the exact installed Bunqueue 2.8.59 client
+agent is pinned to the server it manages and uses the exact installable Bunqueue 2.9.0 npm client
 contracts; it never patches Bunqueue internals.
 
 ## Features
@@ -111,22 +111,24 @@ contracts; it never patches Bunqueue internals.
 | **Cron** | Control ▸ Cron Manager | Submit acknowledged cron/interval upserts and delete schedules |
 | **Workflow Engine** | Workflow ▸ Overview / Executions / Waiting / Compensation / Archive | Start, recover, signal, inspect, compensate, archive and clean durable executions |
 | **Job Flows** | Workflow ▸ Job Flows | Explore DAGs, run all FlowProducer create modes and operate safe Flow Job methods |
-| **DLQ** | Control ▸ DLQ | Inspect entries, failure history and CSV exports; retry and purge stay unavailable |
+| **DLQ** | Control ▸ DLQ | Inspect/export failures; removal, retry and purge stay unavailable without atomic generation/topology preconditions |
 | **Webhooks** | Control ▸ Webhooks | Create / enable / delete job-event webhooks |
 | **Ops** | Control ▸ Diagnostics | Health, ping, storage, memory, connections, totals |
 | **S3 backup** | Management ▸ S3 Backup | Configure, inspect, list, create and guarded-restore official snapshots |
 | **Browse** | Queues / Jobs / DLQ / Cron / Metrics / Workers / Logs | Read-only browsing with basic actions |
 
-> Job actions are gated by the v2.8.59 flow contract. Every DLQ retry and completed-job requeue is
+> Job actions are gated by the v2.9.0 flow contract. Every DLQ retry and completed-job requeue is
 > unavailable: the DLQ GET + POST sequence has no atomic generation/state/topology precondition and
 > can target a job recreated under the same ID, while `retryCompleted` does not rebuild dependency
 > registration or flow order. Cancel, Discard, Drain, Clean, Obliterate and DLQ Purge also fail
-> closed. DLQ `maxAge`/`maxEntries` are read-only, auto-retry can only be disabled, and Copilot's only
+> closed. Bunqueue 2.9's `Queue.removeDlqJob()` also accepts only queue + job ID, so custom-ID reuse
+> prevents the dashboard from proving that a later deletion still targets the observed generation.
+> DLQ `maxAge`/`maxEntries` are read-only, auto-retry can only be disabled, and Copilot's only
 > mutations are Promote, Pause and Resume.
 
 ## Quick start
 
-**Prerequisites:** [Bun](https://bun.sh) ≥ 1.3 and a reachable bunqueue server (or let the control
+**Prerequisites:** [Bun](https://bun.sh) ≥ 1.4.0 and a reachable bunqueue server (or let the control
 agent start one for you from the **Server** page).
 
 ### Run from npm (no clone)
@@ -246,8 +248,10 @@ target-pinned Flow, Workflow, Queue and Backup agent operations.
 | `bun run agent` | Control agent only |
 | `bun run build` | Typecheck (`tsc --noEmit`) + production build → `dist/` |
 | `bun run preview` | Preview the production build |
-| `bun run check` | Biome lint + format (the CI gate) |
-| `bun run check:fix` | Biome lint + format with safe fixes applied |
+| `bun run lint` | Lint with Oxlint, including type-aware rules and the implicit-`any` parity guard |
+| `bun run format:check` | Check formatting with Oxfmt |
+| `bun run check` | Oxlint + Oxfmt validation (the CI gate) |
+| `bun run check:fix` | Apply safe Oxlint fixes, then format with Oxfmt |
 | `bun test` | Unit + agent-lifecycle tests |
 
 ## Docker
@@ -295,9 +299,15 @@ The canonical gate must be green before a change is considered done; CI runs the
 bun run quality   # architecture, lint/build, size, docs, coverage, real E2E, packed-bin smoke, audit
 ```
 
-The E2E stage starts disposable Bunqueue 2.8.59 processes and exercises the complete FlowProducer,
+The E2E stage starts disposable Bunqueue 2.9.0 processes and exercises the complete FlowProducer,
 Workflow Engine, and Queue SDK operator bridges. Run it alone with `bun run test:e2e`.
 
+The blocking browser job builds the production bundle under `/e2e/dashboard`, starts an
+authenticated disposable Bunqueue server, and drives the UI with Playwright on Chromium, Firefox,
+and WebKit. It covers the token gate, every sidebar route, SSE recovery across a real server
+restart, confirmed Cron creation/deletion, and automated WCAG A/AA checks. Install the browser
+binaries once with `bun run test:e2e:browser:install`, then run `bun run test:e2e:browser`.
+
 CI enforces this on every push and pull request. See [Contributing](#contributing).
 
 ## Project structure

package/agent/backup/resultValidation.ts

@@ -81,5 +81,5 @@ function validIsoDate(value: string): boolean {
 }
 
 function invalid(label: string): never {
-  throw new Error(`Bunqueue ${label} has an invalid 2.8.59 contract`);
+  throw new Error(`Bunqueue ${label} has an invalid 2.9.0 contract`);
 }

package/agent/backup/routes.ts

@@ -10,36 +10,82 @@ export interface BackupRouteResponse {
   body: Record<string, unknown>;
 }
 
-export async function routeBackupRequest(
+export type PreparedBackupRequest =
+  | { operation: 'status' | 'list' | 'now'; query: URLSearchParams }
+  | { operation: 'configure'; query: URLSearchParams; environment: unknown }
+  | { operation: 'restore'; query: URLSearchParams; key: string; database: unknown };
+
+/** Read and validate the bounded HTTP payload before acquiring a lifecycle lease. */
+export async function prepareBackupRequest(
   request: Request,
   pathname: string,
   method: string,
-  config: ServerConfig,
-  serverRunning: boolean,
-  database: DbStats,
-  runner: BackupRunnerPort,
-  configure?: (extraEnv: Record<string, string>) => void,
+  config?: ServerConfig,
   targetPolicy?: ManagedTargetPolicy
-): Promise<BackupRouteResponse | null> {
+): Promise<PreparedBackupRequest | null> {
   const operation = routeOperation(pathname, method);
   if (!operation) return null;
   const query = exactTargetQuery(request.url);
-  assertManagedTarget(query, config, targetPolicy);
+  if (config) assertManagedTarget(query, config, targetPolicy);
   if (operation === 'configure') {
-    if (!configure) throw new Error('Backup configuration is unavailable');
     const body = await boundedRecord(request, ['environment']);
-    const next = mergeBackupEnvironment(config.extraEnv, body.environment);
-    configure(next);
-    return success({ configured: true, enabled: next.S3_BACKUP_ENABLED === 'true' });
+    return { operation, query, environment: body.environment };
   }
   if (operation === 'restore') {
-    if (serverRunning) throw new Error('Stop the managed Bunqueue server before restoring a backup');
     const body = await boundedRecord(request, ['key', 'database']);
-    const key = backupKey(body.key);
-    assertDatabaseSnapshot(body.database, database);
-    return success(await runner.execute(config, operation, key));
+    return { operation, query, key: backupKey(body.key), database: body.database };
+  }
+  return { operation, query };
+}
+
+/** Execute a prepared operation against one lifecycle-pinned config/database snapshot. */
+export async function executePreparedBackupRequest(
+  prepared: PreparedBackupRequest,
+  config: ServerConfig,
+  serverRunning: boolean,
+  database: DbStats,
+  runner: BackupRunnerPort,
+  configure?: (extraEnv: Record<string, string>) => void | Promise<void>,
+  targetPolicy?: ManagedTargetPolicy
+): Promise<BackupRouteResponse> {
+  assertManagedTarget(prepared.query, config, targetPolicy);
+  if (prepared.operation === 'configure') {
+    if (!configure) throw new Error('Backup configuration is unavailable');
+    const next = mergeBackupEnvironment(config.extraEnv, prepared.environment);
+    await configure(next);
+    return success({ configured: true, enabled: next.S3_BACKUP_ENABLED === 'true' });
+  }
+  if (prepared.operation === 'restore') {
+    if (serverRunning) throw new Error('Stop the managed Bunqueue server before restoring a backup');
+    assertDatabaseSnapshot(prepared.database, database);
+    return success(await runner.execute(config, prepared.operation, prepared.key));
   }
-  return success(await runner.execute(config, operation));
+  return success(await runner.execute(config, prepared.operation));
+}
+
+export async function routeBackupRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  config: ServerConfig,
+  serverRunning: boolean,
+  database: DbStats,
+  runner: BackupRunnerPort,
+  configure?: (extraEnv: Record<string, string>) => void,
+  targetPolicy?: ManagedTargetPolicy
+): Promise<BackupRouteResponse | null> {
+  const prepared = await prepareBackupRequest(request, pathname, method, config, targetPolicy);
+  return prepared
+    ? executePreparedBackupRequest(
+        prepared,
+        config,
+        serverRunning,
+        database,
+        runner,
+        configure,
+        targetPolicy
+      )
+    : null;
 }
 
 function routeOperation(pathname: string, method: string) {

package/agent/db/query.ts

@@ -47,7 +47,8 @@ export function dbQuery(path: string, sql: string): DbQueryResult {
       throw translateDbError(error);
     }
     let columns = statement.columnNames;
-    if (statement.columnTypes.length > columns.length) {
+    const hasDuplicateNames = new Set(columns).size !== columns.length;
+    if (statement.columnTypes.length > columns.length || hasDuplicateNames) {
       const disambiguated = disambiguateColumns(db, trimmed);
       if (disambiguated) {
         statement = disambiguated.stmt;

package/agent/manager/config.ts

@@ -10,7 +10,7 @@ const CONFIG_KEYS = new Set<keyof ServerConfig>([
 
 export function defaultConfig(): ServerConfig {
   return {
-    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.8.59 start',
+    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.9.0 start',
     httpPort: Number(process.env.HTTP_PORT) || 6790,
     tcpPort: Number(process.env.TCP_PORT) || 6789,
     dataPath: process.env.BUNQUEUE_DATA_PATH || './data/bunq.db',
@@ -76,6 +76,7 @@ export function validateServerConfig(value: unknown): ServerConfig {
   for (const key of CONFIG_KEYS) {
     if (!Object.hasOwn(value, key)) throw new Error(`Missing config key: ${key}`);
   }
+  if (config.httpPort === config.tcpPort) throw new Error('httpPort and tcpPort must differ');
   return config as ServerConfig;
 }
 

package/agent/manager/process.ts

@@ -1,6 +1,7 @@
 import { copyConfig, defaultConfig, validateConfigPatch, validateServerConfig } from './config';
 import { ProcessLogs } from './logs';
 import { databaseStats } from './storage';
+import { managedStorageMode, removeSqlitePaths } from './storageMode';
 import type {
   DbStats,
   LogLine,
@@ -29,6 +30,9 @@ export class ProcessManager {
   private startedAt: number | null = null;
   private exitCode: number | null = null;
   private config: ServerConfig = defaultConfig();
+  // A per-agent random seed prevents stale compare-and-set tokens from a
+  // previous control-agent process matching again after a restart (ABA).
+  private configRevision = configRevisionSeed();
   private runningConfig: ServerConfig | null = null;
   private procToken = 0;
   private stopping: Promise<StatusSnapshot> | null = null;
@@ -42,13 +46,26 @@ export class ProcessManager {
     return copyConfig(this.config);
   }
 
-  setConfig(patch: Partial<ServerConfig>): ServerConfig {
+  getConfigRevision(): number {
+    return this.configRevision;
+  }
+
+  setConfig(patch: Partial<ServerConfig>, expectedRevision?: number): ServerConfig {
+    if (expectedRevision !== undefined && expectedRevision !== this.configRevision) {
+      throw new Error(
+        `Configuration changed since revision ${expectedRevision}; current revision is ${this.configRevision}`
+      );
+    }
     const valid = validateConfigPatch(patch);
-    this.config = {
+    const next = validateServerConfig({
       ...this.config,
       ...valid,
       extraEnv: valid.extraEnv ?? this.config.extraEnv,
-    };
+    });
+    if (!sameConfig(this.config, next)) {
+      this.config = next;
+      this.configRevision = nextConfigRevision(this.configRevision);
+    }
     return copyConfig(this.config);
   }
 
@@ -56,6 +73,7 @@ export class ProcessManager {
     return {
       status: this.status,
       generation: this.procToken,
+      configRevision: this.configRevision,
       pid: this.proc?.pid ?? null,
       startedAt: this.startedAt,
       exitCode: this.exitCode,
@@ -64,8 +82,10 @@ export class ProcessManager {
     };
   }
 
-  dbStats(): Promise<DbStats> {
-    return databaseStats(this.config.dataPath);
+  dbStats(dataPath?: string): Promise<DbStats> {
+    const effectivePath =
+      dataPath ?? (this.runningConfig ?? this.config).dataPath;
+    return databaseStats(effectivePath);
   }
 
   getLogs(): LogLine[] {
@@ -90,6 +110,7 @@ export class ProcessManager {
     }
 
     const launchConfig = validateServerConfig(this.config);
+    const storageMode = managedStorageMode(launchConfig);
     const [command, ...args] = launchConfig.command.trim().split(/\s+/);
     this.status = 'starting';
     this.exitCode = null;
@@ -101,6 +122,7 @@ export class ProcessManager {
       TCP_PORT: String(launchConfig.tcpPort),
       BUNQUEUE_DATA_PATH: launchConfig.dataPath,
     };
+    if (storageMode !== 'sqlite') removeSqlitePaths(env);
 
     try {
       this.proc = Bun.spawn([command, ...args], {
@@ -231,3 +253,27 @@ export class ProcessManager {
     }
   }
 }
+
+function sameConfig(left: ServerConfig, right: ServerConfig): boolean {
+  const leftEnv = Object.entries(left.extraEnv).sort(([a], [b]) => a.localeCompare(b));
+  const rightEnv = Object.entries(right.extraEnv).sort(([a], [b]) => a.localeCompare(b));
+  return (
+    left.command === right.command &&
+    left.httpPort === right.httpPort &&
+    left.tcpPort === right.tcpPort &&
+    left.dataPath === right.dataPath &&
+    JSON.stringify(leftEnv) === JSON.stringify(rightEnv)
+  );
+}
+
+function configRevisionSeed(): number {
+  const words = crypto.getRandomValues(new Uint32Array(2));
+  return ((words[0] ?? 0) & 0x1f_ffff) * 0x1_0000_0000 + (words[1] ?? 0);
+}
+
+function nextConfigRevision(current: number): number {
+  if (current < Number.MAX_SAFE_INTEGER) return current + 1;
+  let next = configRevisionSeed();
+  while (next === current) next = configRevisionSeed();
+  return next;
+}

package/agent/manager/storageMode.ts

@@ -0,0 +1,21 @@
+import type { ServerConfig } from './types';
+
+export type ManagedStorageMode = 'memory' | 'sqlite' | 'postgres';
+
+/** Mirrors Bunqueue 2.9's explicit-driver, PostgreSQL-URL, then data-path precedence. */
+export function managedStorageMode(config: ServerConfig): ManagedStorageMode {
+  const explicit = config.extraEnv.BUNQUEUE_STORAGE_DRIVER ?? process.env.BUNQUEUE_STORAGE_DRIVER;
+  if (explicit === 'postgres' || explicit === 'memory' || explicit === 'sqlite') return explicit;
+  if (explicit) throw new Error(`Unsupported storage driver: ${explicit}`);
+  const postgresUrl = config.extraEnv.BUNQUEUE_POSTGRES_URL ?? process.env.BUNQUEUE_POSTGRES_URL;
+  if (postgresUrl) return 'postgres';
+  return config.dataPath ? 'sqlite' : 'memory';
+}
+
+/** Non-SQLite drivers cannot be combined with Bunqueue's legacy SQLite path aliases. */
+export function removeSqlitePaths(env: Record<string, string>): void {
+  delete env.BUNQUEUE_DATA_PATH;
+  delete env.BQ_DATA_PATH;
+  delete env.DATA_PATH;
+  delete env.SQLITE_PATH;
+}

package/agent/manager/types.ts

@@ -30,6 +30,8 @@ export interface StatusSnapshot {
   status: Status;
   /** Monotonic identity of the managed process generation. */
   generation: number;
+  /** Monotonic desired-config revision used for optimistic updates. */
+  configRevision?: number;
   pid: number | null;
   startedAt: number | null;
   exitCode: number | null;

package/agent/manager.ts

@@ -1,6 +1,7 @@
 /** Public compatibility entrypoint for managed bunqueue process supervision. */
 export { validateConfigPatch } from './manager/config';
 export { ProcessManager } from './manager/process';
+export { managedStorageMode } from './manager/storageMode';
 export type {
   DbStats,
   LogLine,

package/agent/queue/routes.ts

@@ -19,8 +19,7 @@ import {
 } from './validation';
 
 const READ_ROUTE = /^\/queue-operations\/([^/]+)\/(limits|deduplication|metrics)$/;
-const MUTATION_ROUTE =
-  /^\/queue-operations\/([^/]+)\/(deduplication\/remove|events\/trim)$/;
+const MUTATION_ROUTE = /^\/queue-operations\/([^/]+)\/(deduplication\/remove|events\/trim)$/;
 
 export async function routeQueueOperationsRequest(
   request: Request,

package/agent/queue/runtime.ts

@@ -13,6 +13,7 @@ export type QueueOperationsClient = Pick<
   | 'isMaxed'
   | 'getDeduplicationJobId'
   | 'removeDeduplicationKey'
+  | 'removeDlqJob'
   | 'getMetrics'
   | 'trimEvents'
   | 'close'
@@ -59,6 +60,10 @@ export class QueueOperationsRuntime implements QueueOperationsPort {
     return this.withQueue(config, queue, (client) => client.removeDeduplicationKey(deduplicationId));
   }
 
+  removeDlqJob(config: ServerConfig, queue: string, jobId: string): Promise<boolean> {
+    return this.withQueue(config, queue, (client) => client.removeDlqJob(jobId));
+  }
+
   metrics(
     config: ServerConfig,
     queue: string,

package/agent/queue/types.ts

@@ -20,6 +20,7 @@ export interface QueueOperationsPort {
     queue: string,
     deduplicationId: string
   ): Promise<number>;
+  removeDlqJob(config: ServerConfig, queue: string, jobId: string): Promise<boolean>;
   metrics(
     config: ServerConfig,
     queue: string,

package/agent/server/controlRoutes.ts

@@ -1,4 +1,4 @@
-import { type ProcessManager, validateConfigPatch } from '../manager';
+import { managedStorageMode, type ProcessManager, validateConfigPatch } from '../manager';
 import { safeErrorMessage } from '../errorMessage';
 import {
   WorkflowRuntimeUnavailableError,
@@ -15,12 +15,18 @@ import type { RouteResponse } from './types';
 
 const MAX_CONFIG_BODY_BYTES = 64 * 1024;
 
-async function statusWithHealth(manager: ProcessManager, controlTarget: ServerControlTarget) {
+async function statusWithHealth(
+  manager: ProcessManager,
+  controlTarget: ServerControlTarget,
+  retryOnProcessChange = true
+) {
   const snapshot = manager.getStatus();
+  const configRevision = snapshot.configRevision ?? manager.getConfigRevision?.() ?? 0;
   if (controlTarget.mode === 'external') {
     const health = await probeExternalHealth(controlTarget);
     return {
       ...snapshot,
+      configRevision,
       managementMode: 'external' as const,
       healthy: health.healthy,
       version: health.version,
@@ -51,8 +57,41 @@ async function statusWithHealth(manager: ProcessManager, controlTarget: ServerCo
       // The managed process is not healthy yet.
     }
   }
-  const database = await manager.dbStats().catch(() => null);
-  return { ...snapshot, managementMode: 'managed' as const, healthy, version, db: database };
+  const effectiveConfig = snapshot.runningConfig ?? snapshot.config;
+  const database = await statusDatabase(manager, effectiveConfig);
+  const current = manager.getStatus();
+  if (!sameProcessSnapshot(snapshot, current)) {
+    if (retryOnProcessChange) return statusWithHealth(manager, controlTarget, false);
+    const currentConfig = current.runningConfig ?? current.config;
+    return {
+      ...current,
+      configRevision: current.configRevision ?? manager.getConfigRevision?.() ?? 0,
+      managementMode: 'managed' as const,
+      healthy: false,
+      version: undefined,
+      db: await statusDatabase(manager, currentConfig),
+    };
+  }
+  return {
+    ...snapshot,
+    configRevision,
+    managementMode: 'managed' as const,
+    healthy,
+    version,
+    db: database,
+  };
+}
+
+async function statusDatabase(
+  manager: ProcessManager,
+  config: ReturnType<ProcessManager['getConfig']>
+) {
+  try {
+    return managedStorageMode(config) === 'sqlite' ? await manager.dbStats(config.dataPath) : null;
+  } catch {
+    // Status must remain reachable so an invalid desired storage driver can be corrected.
+    return null;
+  }
 }
 
 export async function routeControlRequest(
@@ -65,7 +104,10 @@ export async function routeControlRequest(
   controlTarget: ServerControlTarget = MANAGED_CONTROL_TARGET
 ): Promise<RouteResponse | null> {
   if (pathname === '/control/status') {
-    return { status: 200, body: await statusWithHealth(manager, controlTarget) };
+    return coordinatedLease(lifecycle, async () => ({
+      status: 200,
+      body: await statusWithHealth(manager, controlTarget),
+    }));
   }
   if (pathname === '/control/logs') {
     return { status: 200, body: { lines: manager.getLogs() } };
@@ -96,22 +138,62 @@ export async function routeControlRequest(
     });
   }
   if (pathname === '/control/config' && method === 'GET') {
-    return { status: 200, body: manager.getConfig() };
+    return { status: 200, body: configSnapshot(manager) };
   }
   if (pathname === '/control/config' && method === 'PUT') {
     assertManagedControl(controlTarget);
-    const patch = validateConfigPatch(
+    const update = configUpdate(
       await readLimitedJsonBody(request, {
         scope: 'Agent configuration',
         maxBytes: MAX_CONFIG_BODY_BYTES,
         limitLabel: '64 KiB',
       })
     );
-    return { status: 200, body: manager.setConfig(patch) };
+    return coordinated(lifecycle, async () => {
+      manager.setConfig(update.patch, update.expectedRevision);
+      return { status: 200, body: configSnapshot(manager) };
+    });
   }
   return null;
 }
 
+function configSnapshot(manager: ProcessManager) {
+  return { ...manager.getConfig(), configRevision: manager.getConfigRevision?.() ?? 0 };
+}
+
+function configUpdate(value: unknown): {
+  patch: ReturnType<typeof validateConfigPatch>;
+  expectedRevision?: number;
+} {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return { patch: validateConfigPatch(value) };
+  }
+  const input = { ...(value as Record<string, unknown>) };
+  const hasExpectedRevision = Object.hasOwn(input, 'expectedRevision');
+  const hasConfigRevision = Object.hasOwn(input, 'configRevision');
+  const expected = hasExpectedRevision
+    ? input.expectedRevision
+    : hasConfigRevision
+      ? input.configRevision
+      : undefined;
+  if (
+    hasExpectedRevision &&
+    hasConfigRevision &&
+    input.expectedRevision !== input.configRevision
+  ) {
+    throw new Error('expectedRevision and configRevision must match');
+  }
+  delete input.expectedRevision;
+  delete input.configRevision;
+  if (expected !== undefined && (!Number.isSafeInteger(expected) || (expected as number) < 0)) {
+    throw new Error('expectedRevision must be a non-negative safe integer');
+  }
+  return {
+    patch: validateConfigPatch(input),
+    ...(expected === undefined ? {} : { expectedRevision: expected as number }),
+  };
+}
+
 export function assertManagedControl(controlTarget: ServerControlTarget): void {
   if (controlTarget.mode === 'external') {
     throw new Error(
@@ -173,6 +255,25 @@ function coordinated<T>(
   return lifecycle ? lifecycle.run(operation) : operation();
 }
 
+function coordinatedLease<T>(
+  lifecycle: AgentLifecyclePort | undefined,
+  operation: () => Promise<T>
+): Promise<T> {
+  return lifecycle ? lifecycle.lease(operation) : operation();
+}
+
+function sameProcessSnapshot(
+  initial: ReturnType<ProcessManager['getStatus']>,
+  current: ReturnType<ProcessManager['getStatus']>
+): boolean {
+  return (
+    initial.status === current.status &&
+    initial.generation === current.generation &&
+    initial.pid === current.pid &&
+    initial.configRevision === current.configRevision
+  );
+}
+
 type SettledOperation = { ok: true } | { ok: false; error: unknown };
 
 async function settle(operation: () => Promise<unknown>): Promise<SettledOperation> {