bunqueue-dashboard 0.0.39 → 0.0.41

package/README.md

@@ -96,7 +96,7 @@ 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 installable Bunqueue 2.9.0 npm client
+agent is pinned to the server it manages and uses the exact installable Bunqueue 2.9.2 npm client
 contracts; it never patches Bunqueue internals.
 
 ## Features
@@ -104,6 +104,7 @@ contracts; it never patches Bunqueue internals.
 | Area | Where | What you can do |
 | --- | --- | --- |
 | **Home** | Overview | Live health banner, throughput, queue health, recent activity |
+| **Fleet** | Fleet | Probe and operate multiple Bunqueue APIs + paired agents; verify shared PostgreSQL target/namespace topology |
 | **Server** | Control ▸ Server | **Start / stop / restart** the server process, edit its config, tail process logs |
 | **Enqueue** | Control ▸ Add Job | Add jobs (single or bulk) with every option |
 | **Inspect** | Control ▸ Job Inspector | Look up any job; promote / re-prioritize / delay; view data & result |
@@ -117,7 +118,7 @@ contracts; it never patches Bunqueue internals.
 | **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.9.0 flow contract. Every DLQ retry and completed-job requeue is
+> Job actions are gated by the v2.9.2 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
@@ -128,7 +129,7 @@ contracts; it never patches Bunqueue internals.
 
 ## Quick start
 
-**Prerequisites:** [Bun](https://bun.sh) ≥ 1.4.0 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)
@@ -147,7 +148,7 @@ standalone binaries: `PORT` · `BIND_ADDR` · `BUNQUEUE_URL` · `AGENT_PORT` ·
 Install it permanently instead of running via `bunx`:
 
 ```bash
-bun add -g bunqueue-dashboard   # or: npm i -g bunqueue-dashboard (still runs on Bun)
+bun add -g bunqueue-dashboard
 bunqueue-dashboard
 ```
 
@@ -192,14 +193,22 @@ flowchart LR
 - **Writes** through the same HTTP API, with every mutation shape-verified against the live server.
 - **Process lifecycle**, the one thing HTTP can't do, is delegated to the local control agent.
 
+For multiple brokers, create one named Dashboard profile and one paired control
+agent per broker. The Fleet page probes all profiles without retargeting the
+active UI, groups brokers that share an exact PostgreSQL target + namespace,
+and drives each node's Start/Stop/Restart controls. Queue state is shared by
+PostgreSQL; lifecycle, process logs/config, in-memory webhooks, and each agent's
+Workflow Engine store remain node-local. See the
+[Fleet guide](https://egeominotti.github.io/bunqueue-dashboard/docs/guide/fleet).
+
 Two HTTP clients coexist on purpose: `src/lib/api.ts` (first-generation view pages) and
 `src/lib/bq.ts` (the complete, shape-verified client used by every `Control ▸ *` page). See
 [`docs/`](docs/README.md) for the full, source-verified reference.
 
 ## Configuration
 
-The `VITE_*` dashboard defaults are build-time values and can **also** be changed at runtime from
-the in-app **Settings** page. The all-in-one server reads the non-`VITE_*` runtime variables below.
+The `VITE_*` dashboard defaults are build-time values and can **also** seed the first named profile
+in **Settings**. Add up to 32 broker/agent profiles at runtime. The all-in-one server reads the non-`VITE_*` runtime variables below.
 Copy [`.env.example`](.env.example) to `.env` to set defaults.
 
 | Variable | Purpose | Default |
@@ -253,6 +262,8 @@ target-pinned Flow, Workflow, Queue and Backup agent operations.
 | `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 |
+| `bun run test:e2e` | Real Flow, Workflow, Queue SDK, and three-broker PostgreSQL runtime tests |
+| `bun run test:e2e:postgres-fleet` | Three authenticated Bunqueue 2.9.2 brokers + three agents sharing disposable PostgreSQL 18.6 |
 
 ## Docker
 
@@ -299,8 +310,11 @@ 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.9.0 processes and exercises the complete FlowProducer,
-Workflow Engine, and Queue SDK operator bridges. Run it alone with `bun run test:e2e`.
+The E2E stage starts disposable Bunqueue 2.9.2 processes and exercises the complete FlowProducer,
+Workflow Engine, and Queue SDK operator bridges. It also starts PostgreSQL 18.6 in Docker with
+three authenticated brokers and paired agents, proving cross-broker enqueue/inspect/leased
+pull+ack, pause/resume, cron, and rate-limit behavior. Run it alone with `bun run test:e2e` (Docker
+is required for the PostgreSQL stage).
 
 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,

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.9.0 contract`);
+  throw new Error(`Bunqueue ${label} has an invalid 2.9.2 contract`);
 }

package/agent/index.ts

@@ -12,6 +12,7 @@
  *       BUNQUEUE_START_CMD, BUNQUEUE_MANAGED, BUNQUEUE_URL, BUNQUEUE_TOKEN,
  *       HTTP_PORT, TCP_PORT, BUNQUEUE_DATA_PATH
  */
+import { assertRequiredBunVersion } from '../scripts/bunVersion';
 import { logger } from './logger';
 import { ProcessManager } from './manager';
 import {
@@ -22,6 +23,8 @@ import {
 } from './server';
 import { installAgentShutdown } from './shutdown';
 
+assertRequiredBunVersion();
+
 const mgr = new ProcessManager();
 const PORT = Number(process.env.AGENT_PORT) || 6800;
 const allowedOrigins = resolveAllowedOrigins();

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.9.0 start',
+    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.9.2 start',
     httpPort: Number(process.env.HTTP_PORT) || 6790,
     tcpPort: Number(process.env.TCP_PORT) || 6789,
     dataPath: process.env.BUNQUEUE_DATA_PATH || './data/bunq.db',

package/agent/manager/process.ts

@@ -1,7 +1,7 @@
 import { copyConfig, defaultConfig, validateConfigPatch, validateServerConfig } from './config';
 import { ProcessLogs } from './logs';
 import { databaseStats } from './storage';
-import { managedStorageMode, removeSqlitePaths } from './storageMode';
+import { removeSqlitePaths, validateManagedStorage } from './storageMode';
 import type {
   DbStats,
   LogLine,
@@ -110,7 +110,7 @@ export class ProcessManager {
     }
 
     const launchConfig = validateServerConfig(this.config);
-    const storageMode = managedStorageMode(launchConfig);
+    const storageMode = validateManagedStorage(launchConfig);
     const [command, ...args] = launchConfig.command.trim().split(/\s+/);
     this.status = 'starting';
     this.exitCode = null;

package/agent/manager/storageMode.ts

@@ -12,6 +12,45 @@ export function managedStorageMode(config: ServerConfig): ManagedStorageMode {
   return config.dataPath ? 'sqlite' : 'memory';
 }
 
+export function managedPostgresUrl(config: ServerConfig): string | undefined {
+  return (config.extraEnv.BUNQUEUE_POSTGRES_URL ?? process.env.BUNQUEUE_POSTGRES_URL)?.trim() || undefined;
+}
+
+export function managedPostgresNamespace(config: ServerConfig): string {
+  return (
+    (config.extraEnv.BUNQUEUE_POSTGRES_NAMESPACE ?? process.env.BUNQUEUE_POSTGRES_NAMESPACE)?.trim() ||
+    'default'
+  );
+}
+
+/** Credential-free PostgreSQL cluster label safe to expose to authenticated operators. */
+export function managedPostgresTarget(config: ServerConfig): string | undefined {
+  const configured = managedPostgresUrl(config);
+  if (!configured) return undefined;
+  try {
+    const parsed = new URL(configured);
+    if (
+      (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:') ||
+      !parsed.hostname
+    ) {
+      return undefined;
+    }
+    const database = decodeURIComponent(parsed.pathname.replace(/^\/+/, '')) || 'postgres';
+    return `${parsed.hostname}:${parsed.port || '5432'}/${database}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Fail before spawning when Bunqueue would reject an incomplete PostgreSQL config. */
+export function validateManagedStorage(config: ServerConfig): ManagedStorageMode {
+  const mode = managedStorageMode(config);
+  if (mode === 'postgres' && !managedPostgresUrl(config)) {
+    throw new Error('PostgreSQL storage requires BUNQUEUE_POSTGRES_URL');
+  }
+  return mode;
+}
+
 /** 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;

package/agent/manager.ts

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

package/agent/queue/routes.ts

@@ -13,13 +13,17 @@ import {
   exactJsonBody,
   exactQuery,
   metricsRange,
+  optionalMaxCount,
   optionalMaxJobs,
+  positiveSafeInteger,
   requiredDeduplicationId,
+  requiredGroupId,
   validateQueueName,
 } from './validation';
 
-const READ_ROUTE = /^\/queue-operations\/([^/]+)\/(limits|deduplication|metrics)$/;
-const MUTATION_ROUTE = /^\/queue-operations\/([^/]+)\/(deduplication\/remove|events\/trim)$/;
+const READ_ROUTE = /^\/queue-operations\/([^/]+)\/(limits|groups|deduplication|metrics)$/;
+const MUTATION_ROUTE =
+  /^\/queue-operations\/([^/]+)\/(groups\/(?:rate-limit|concurrency)(?:\/remove)?|deduplication\/remove|events\/trim)$/;
 
 export async function routeQueueOperationsRequest(
   request: Request,
@@ -50,6 +54,21 @@ export async function routeQueueOperationsRequest(
         ok({ jobId: await runtime.deduplicationJobId(current, queue, id) })
       );
     }
+    if (read[2] === 'groups') {
+      const query = pinnedQuery(
+        request,
+        config,
+        ['target', 'groupId', 'maxJobs', 'maxCount'],
+        targetPolicy
+      );
+      const groupId = requiredGroupId(query.get('groupId'));
+      const maxJobs = optionalMaxJobs(query);
+      const maxCount = optionalMaxCount(query);
+      assertRunning(running);
+      return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>
+        ok({ group: await runtime.group(current, queue, groupId, maxJobs, maxCount) })
+      );
+    }
     const query = pinnedQuery(request, config, ['target', 'type', 'start', 'end'], targetPolicy);
     const type = metricType(query.get('type'));
     const range = metricsRange(query);
@@ -73,6 +92,42 @@ export async function routeQueueOperationsRequest(
         ok({ removed: await runtime.removeDeduplicationKey(current, queue, id) })
       );
     }
+    if (mutation[2].startsWith('groups/')) {
+      const remove = mutation[2].endsWith('/remove');
+      const rateLimit = mutation[2].includes('/rate-limit');
+      const allowed = remove
+        ? ['groupId']
+        : rateLimit
+          ? ['groupId', 'max', 'duration']
+          : ['groupId', 'concurrency'];
+      const body = await exactJsonBody(request, allowed);
+      const groupId = requiredGroupId(body.groupId);
+      return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) => {
+        if (remove) {
+          const removed = rateLimit
+            ? await runtime.removeGroupRateLimit(current, queue, groupId)
+            : await runtime.removeGroupConcurrency(current, queue, groupId);
+          return ok({ removed });
+        }
+        if (rateLimit) {
+          await runtime.setGroupRateLimit(
+            current,
+            queue,
+            groupId,
+            positiveSafeInteger(body.max, 'max'),
+            positiveSafeInteger(body.duration, 'duration')
+          );
+        } else {
+          await runtime.setGroupConcurrency(
+            current,
+            queue,
+            groupId,
+            positiveSafeInteger(body.concurrency, 'concurrency')
+          );
+        }
+        return ok({ applied: true });
+      });
+    }
     const body = await exactJsonBody(request, ['maxLength']);
     const retention = eventRetention(body.maxLength);
     return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>

package/agent/queue/runtime.ts

@@ -1,7 +1,7 @@
 import { Queue, type QueueMetricType, type QueueMetrics } from 'bunqueue/client';
 import { managedAuthToken } from '../managedTarget';
 import type { ServerConfig } from '../manager';
-import type { QueueLimitSnapshot, QueueOperationsPort } from './types';
+import type { QueueGroupSnapshot, QueueLimitSnapshot, QueueOperationsPort } from './types';
 import { QueueOperationsUnavailableError } from './types';
 
 export type QueueOperationsClient = Pick<
@@ -11,6 +11,16 @@ export type QueueOperationsClient = Pick<
   | 'getGlobalConcurrency'
   | 'getRateLimitTtl'
   | 'isMaxed'
+  | 'getGroupJobsCount'
+  | 'getGroupsJobsCount'
+  | 'getGroupActiveCount'
+  | 'setGroupRateLimit'
+  | 'getGroupRateLimit'
+  | 'removeGroupRateLimit'
+  | 'getGroupRateLimitTtl'
+  | 'setGroupConcurrency'
+  | 'getGroupConcurrency'
+  | 'removeGroupConcurrency'
   | 'getDeduplicationJobId'
   | 'removeDeduplicationKey'
   | 'removeDlqJob'
@@ -42,6 +52,57 @@ export class QueueOperationsRuntime implements QueueOperationsPort {
     });
   }
 
+  group(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    maxJobs?: number,
+    maxCount?: number
+  ): Promise<QueueGroupSnapshot> {
+    return this.withQueue(config, queue, async (client) => {
+      const [jobs, active, totalGrouped, rateLimit, rateLimitTtl, concurrency] = await Promise.all([
+        client.getGroupJobsCount(groupId),
+        client.getGroupActiveCount(groupId),
+        client.getGroupsJobsCount(maxCount),
+        client.getGroupRateLimit(groupId),
+        client.getGroupRateLimitTtl(groupId, maxJobs),
+        client.getGroupConcurrency(groupId),
+      ]);
+      return { jobs, active, totalGrouped, rateLimit, rateLimitTtl, concurrency };
+    });
+  }
+
+  setGroupRateLimit(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    max: number,
+    duration: number
+  ): Promise<void> {
+    return this.withQueue(config, queue, (client) =>
+      client.setGroupRateLimit(groupId, max, duration)
+    );
+  }
+
+  removeGroupRateLimit(config: ServerConfig, queue: string, groupId: string): Promise<number> {
+    return this.withQueue(config, queue, (client) => client.removeGroupRateLimit(groupId));
+  }
+
+  setGroupConcurrency(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    concurrency: number
+  ): Promise<void> {
+    return this.withQueue(config, queue, (client) =>
+      client.setGroupConcurrency(groupId, concurrency)
+    );
+  }
+
+  removeGroupConcurrency(config: ServerConfig, queue: string, groupId: string): Promise<number> {
+    return this.withQueue(config, queue, (client) => client.removeGroupConcurrency(groupId));
+  }
+
   deduplicationJobId(
     config: ServerConfig,
     queue: string,

package/agent/queue/types.ts

@@ -8,8 +8,39 @@ export interface QueueLimitSnapshot {
   maxed: boolean;
 }
 
+export interface QueueGroupSnapshot {
+  jobs: number;
+  active: number;
+  totalGrouped: number;
+  rateLimit: { max: number; duration: number } | null;
+  rateLimitTtl: number;
+  concurrency: number | null;
+}
+
 export interface QueueOperationsPort {
   limits(config: ServerConfig, queue: string, maxJobs?: number): Promise<QueueLimitSnapshot>;
+  group(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    maxJobs?: number,
+    maxCount?: number
+  ): Promise<QueueGroupSnapshot>;
+  setGroupRateLimit(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    max: number,
+    duration: number
+  ): Promise<void>;
+  removeGroupRateLimit(config: ServerConfig, queue: string, groupId: string): Promise<number>;
+  setGroupConcurrency(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    concurrency: number
+  ): Promise<void>;
+  removeGroupConcurrency(config: ServerConfig, queue: string, groupId: string): Promise<number>;
   deduplicationJobId(
     config: ServerConfig,
     queue: string,

package/agent/queue/validation.ts

@@ -40,6 +40,22 @@ export function optionalMaxJobs(query: URLSearchParams): number | undefined {
   return raw === null ? undefined : boundedInteger(raw, 'maxJobs', 0, 1_000_000);
 }
 
+export function optionalMaxCount(query: URLSearchParams): number | undefined {
+  const raw = query.get('maxCount');
+  return raw === null ? undefined : boundedInteger(raw, 'maxCount', 1, 1_000_000);
+}
+
+export function requiredGroupId(value: unknown): string {
+  if (typeof value !== 'string' || !value || value.length > 256 || value.includes('\0')) {
+    throw new Error('groupId must be a non-empty string of at most 256 characters without NUL');
+  }
+  return value;
+}
+
+export function positiveSafeInteger(value: unknown, label: string): number {
+  return bodyInteger(value, label, 1, Number.MAX_SAFE_INTEGER);
+}
+
 export function metricsRange(query: URLSearchParams): { start: number; end: number } {
   const start = optionalInteger(query.get('start'), 'start', 0, MAX_PAGE_INDEX, 0);
   const rawEnd = query.get('end');

package/agent/server/controlRoutes.ts

@@ -1,4 +1,4 @@
-import { managedStorageMode, type ProcessManager, validateConfigPatch } from '../manager';
+import { type ProcessManager, validateConfigPatch } from '../manager';
 import { safeErrorMessage } from '../errorMessage';
 import {
   WorkflowRuntimeUnavailableError,
@@ -7,93 +7,14 @@ import {
 import { readLimitedJsonBody } from './jsonBody';
 import {
   MANAGED_CONTROL_TARGET,
-  probeExternalHealth,
   type ServerControlTarget,
 } from './controlTarget';
+import { statusWithHealth } from './controlStatus';
 import type { AgentLifecyclePort } from './lifecycle';
 import type { RouteResponse } from './types';
 
 const MAX_CONFIG_BODY_BYTES = 64 * 1024;
 
-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,
-      reachable: health.reachable,
-      externalUrl: controlTarget.url,
-      healthStatus: health.statusCode,
-      healthError: health.error,
-      db: null,
-    };
-  }
-  let healthy = false;
-  let version: string | undefined;
-  if (snapshot.status === 'running') {
-    const port = snapshot.runningConfig?.httpPort ?? snapshot.config.httpPort;
-    try {
-      const response = await fetch(`http://127.0.0.1:${port}/health`, {
-        signal: AbortSignal.timeout(1500),
-      });
-      if (response.ok) {
-        const body: unknown = await response.json();
-        if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
-          const health = body as Record<string, unknown>;
-          healthy = health.ok === true;
-          if (typeof health.version === 'string') version = health.version;
-        }
-      }
-    } catch {
-      // The managed process is not healthy yet.
-    }
-  }
-  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(
   request: Request,
   pathname: string,
@@ -262,18 +183,6 @@ function coordinatedLease<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> {

package/agent/server/controlStatus.ts

@@ -0,0 +1,120 @@
+import {
+  managedPostgresNamespace,
+  managedPostgresTarget,
+  managedStorageMode,
+  type ProcessManager,
+} from '../manager';
+import { probeExternalHealth, type ServerControlTarget } from './controlTarget';
+
+export 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,
+      reachable: health.reachable,
+      externalUrl: controlTarget.url,
+      healthStatus: health.statusCode,
+      healthError: health.error,
+      db: null,
+    };
+  }
+  let healthy = false;
+  let version: string | undefined;
+  if (snapshot.status === 'running') {
+    const port = snapshot.runningConfig?.httpPort ?? snapshot.config.httpPort;
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/health`, {
+        signal: AbortSignal.timeout(1500),
+      });
+      if (response.ok) {
+        const body: unknown = await response.json();
+        if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+          const health = body as Record<string, unknown>;
+          healthy = health.ok === true;
+          if (typeof health.version === 'string') version = health.version;
+        }
+      }
+    } catch {
+      // The managed process is not healthy yet.
+    }
+  }
+  const effectiveConfig = snapshot.runningConfig ?? snapshot.config;
+  const storageMode = statusStorageMode(effectiveConfig);
+  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;
+    const currentStorageMode = statusStorageMode(currentConfig);
+    return {
+      ...current,
+      configRevision: current.configRevision ?? manager.getConfigRevision?.() ?? 0,
+      managementMode: 'managed' as const,
+      healthy: false,
+      version: undefined,
+      storageMode: currentStorageMode,
+      postgresNamespace:
+        currentStorageMode === 'postgres' ? managedPostgresNamespace(currentConfig) : undefined,
+      postgresTarget:
+        currentStorageMode === 'postgres' ? managedPostgresTarget(currentConfig) : undefined,
+      db: await statusDatabase(manager, currentConfig),
+    };
+  }
+  return {
+    ...snapshot,
+    configRevision,
+    managementMode: 'managed' as const,
+    healthy,
+    version,
+    storageMode,
+    postgresNamespace:
+      storageMode === 'postgres' ? managedPostgresNamespace(effectiveConfig) : undefined,
+    postgresTarget:
+      storageMode === 'postgres' ? managedPostgresTarget(effectiveConfig) : undefined,
+    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;
+  }
+}
+
+function statusStorageMode(
+  config: ReturnType<ProcessManager['getConfig']>
+): ReturnType<typeof managedStorageMode> | undefined {
+  try {
+    return managedStorageMode(config);
+  } catch {
+    return undefined;
+  }
+}
+
+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
+  );
+}