bunqueue-dashboard 0.0.36 → 0.0.37

package/README.md

@@ -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.57](https://github.com/egeominotti/bunqueue/releases/tag/v2.8.57) lacks atomic
+[v2.8.59](https://github.com/egeominotti/bunqueue/releases/tag/v2.8.59) 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.57 client
+agent is pinned to the server it manages and uses the exact installed Bunqueue 2.8.59 client
 contracts; it never patches Bunqueue internals.
 
 ## Features
@@ -117,7 +117,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.8.57 flow contract. Every DLQ retry and completed-job requeue is
+> Job actions are gated by the v2.8.59 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
@@ -140,7 +140,7 @@ http://127.0.0.1:8080, proxies `/api/*` to your bunqueue server (`BUNQUEUE_URL`,
 `http://localhost:6790`), and runs the control agent on `127.0.0.1:6800`. Same env knobs as the
 standalone binaries: `PORT` · `BIND_ADDR` · `BUNQUEUE_URL` · `AGENT_PORT` ·
 `AGENT_ALLOWED_ORIGINS` · `AGENT_ALLOWED_HOSTS` · `AGENT_TOKEN` · `BUNQUEUE_TOKEN` ·
-`TRUST_PROXY` · `BUNQUEUE_START_CMD`.
+`TRUST_PROXY` · `BASE_PATH` · `BUNQUEUE_MANAGED` · `BUNQUEUE_START_CMD`.
 
 Install it permanently instead of running via `bunx`:
 
@@ -196,14 +196,17 @@ Two HTTP clients coexist on purpose: `src/lib/api.ts` (first-generation view pag
 
 ## Configuration
 
-All dashboard variables are build-time (`VITE_*`) and can **also** be changed at runtime from the
-in-app **Settings** page. Copy [`.env.example`](.env.example) to `.env` to set defaults.
+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.
+Copy [`.env.example`](.env.example) to `.env` to set defaults.
 
 | Variable | Purpose | Default |
 | --- | --- | --- |
 | `VITE_BUNQUEUE_URL` | bunqueue server origin | `/api` (dev proxy → `:6790`) |
 | `VITE_BUNQUEUE_AGENT_URL` | Control-agent origin | `http://localhost:6800` |
 | `BIND_ADDR` | All-in-one dashboard bind address | `127.0.0.1` |
+| `BASE_PATH` | Runtime mount for the all-in-one server (for example `/internal/queue`) | `/` |
+| `BUNQUEUE_MANAGED` | `0` attaches to the externally supervised `BUNQUEUE_URL`; `1` enables local lifecycle controls | `1` |
 | `AGENT_PORT` | Control-agent port | `6800` |
 | `AGENT_ALLOWED_ORIGINS` | Extra browser origins allowed to drive the agent (comma-separated) | dev defaults |
 | `AGENT_ALLOWED_HOSTS` | Extra Host names/IPs accepted by the all-in-one server and agent | loopback names |
@@ -224,6 +227,16 @@ proxy, allowlist the public origin; if it rewrites `Host`, also allowlist the
 rewritten Host and use `TRUST_PROXY=1` only when the proxy overwrites
 `X-Forwarded-Host`.
 
+For a broker already owned by systemd, Docker or Kubernetes, run the all-in-one
+dashboard with `BUNQUEUE_MANAGED=0`. **Control ▸ Server** then reports health
+from `BUNQUEUE_URL` and cannot spawn, stop, restart or reconfigure a child.
+Stopped-only backup restore is also rejected because the dashboard cannot prove
+that an externally supervised broker is inactive.
+To mount the same process below a reverse-proxy prefix, set for example
+`BASE_PATH=/internal/queue` and preserve that prefix when proxying; the SPA,
+assets, `/api` proxy and `/agent` bridge all move below it, including the
+target-pinned Flow, Workflow, Queue and Backup agent operations.
+
 ## Scripts
 
 | Command | Does |
@@ -282,7 +295,7 @@ 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.57 processes and exercises the complete FlowProducer,
+The E2E stage starts disposable Bunqueue 2.8.59 processes and exercises the complete FlowProducer,
 Workflow Engine, and Queue SDK operator bridges. Run it alone with `bun run test:e2e`.
 
 CI enforces this on every push and pull request. See [Contributing](#contributing).

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

package/agent/backup/routes.ts

@@ -1,4 +1,4 @@
-import { assertManagedTarget } from '../managedTarget';
+import { assertManagedTarget, type ManagedTargetPolicy } from '../managedTarget';
 import type { DbStats, ServerConfig } from '../manager';
 import { readLimitedJsonBody } from '../server/jsonBody';
 import type { BackupRunnerPort } from './runner';
@@ -18,12 +18,13 @@ export async function routeBackupRequest(
   serverRunning: boolean,
   database: DbStats,
   runner: BackupRunnerPort,
-  configure?: (extraEnv: Record<string, string>) => void
+  configure?: (extraEnv: Record<string, string>) => void,
+  targetPolicy?: ManagedTargetPolicy
 ): Promise<BackupRouteResponse | null> {
   const operation = routeOperation(pathname, method);
   if (!operation) return null;
   const query = exactTargetQuery(request.url);
-  assertManagedTarget(query, config);
+  assertManagedTarget(query, config, targetPolicy);
   if (operation === 'configure') {
     if (!configure) throw new Error('Backup configuration is unavailable');
     const body = await boundedRecord(request, ['environment']);

package/agent/flow/routes.ts

@@ -1,5 +1,5 @@
 import type { ServerConfig } from '../manager';
-import { assertManagedTarget } from '../managedTarget';
+import { assertManagedTarget, type ManagedTargetPolicy } from '../managedTarget';
 import type {
   ManagedRuntimeAdmission,
   ManagedRuntimeSnapshot,
@@ -27,6 +27,7 @@ export interface FlowOperationsPort {
 export interface FlowRouteDependencies {
   admission?: ManagedRuntimeAdmission;
   operations?: FlowOperationsPort;
+  targetPolicy?: ManagedTargetPolicy;
 }
 
 const DEFAULT_OPERATIONS: FlowOperationsPort = {
@@ -95,7 +96,7 @@ export async function routeFlowRequest(
   }
   if (pathname === '/flows/create' && method === 'POST') {
     const query = exactQuery(request.url, ['target']);
-    assertManagedTarget(query, config);
+    assertManagedTarget(query, config, dependencies.targetPolicy);
     const body = await readFlowJsonBody(request);
     return success(
       await admitted(query, config, serverRunning, dependencies, ({ config: current }) =>
@@ -105,7 +106,7 @@ export async function routeFlowRequest(
   }
   if (pathname === '/flows/tree' && method === 'GET') {
     const query = exactQuery(request.url, ['id', 'queueName', 'depth', 'maxChildren', 'target']);
-    assertManagedTarget(query, config);
+    assertManagedTarget(query, config, dependencies.targetPolicy);
     const target = {
       id: required(query, 'id'),
       queueName: required(query, 'queueName'),
@@ -120,7 +121,7 @@ export async function routeFlowRequest(
   }
   if (pathname === '/flows/results' && method === 'POST') {
     const query = exactQuery(request.url, ['target']);
-    assertManagedTarget(query, config);
+    assertManagedTarget(query, config, dependencies.targetPolicy);
     const body = await readFlowJsonBody(request);
     return success(
       await admitted(query, config, serverRunning, dependencies, ({ config: current }) =>
@@ -136,7 +137,7 @@ export async function routeFlowRequest(
       ? ['queueName', 'target', 'ttl']
       : ['queueName', 'target']
   );
-  assertManagedTarget(query, config);
+  assertManagedTarget(query, config, dependencies.targetPolicy);
   const target = { id: decodeURIComponent(match[1]), queueName: required(query, 'queueName') };
   const operation = match[2];
   if (method === 'GET' && operation === 'waitUntilFinished') {
@@ -176,7 +177,7 @@ function admitted<T>(
   operation: (snapshot: ManagedRuntimeSnapshot) => Promise<T>
 ): Promise<T> {
   const execute = async (snapshot: ManagedRuntimeSnapshot) => {
-    assertManagedTarget(query, snapshot.config);
+    assertManagedTarget(query, snapshot.config, dependencies.targetPolicy);
     assertRunning(snapshot.running);
     return operation(snapshot);
   };

package/agent/index.ts

@@ -9,11 +9,17 @@
  *
  * Run:  bun run agent/index.ts        (default port 6800)
  * Env:  AGENT_PORT, AGENT_ALLOWED_ORIGINS, AGENT_TOKEN,
- *       BUNQUEUE_START_CMD, HTTP_PORT, TCP_PORT, BUNQUEUE_DATA_PATH
+ *       BUNQUEUE_START_CMD, BUNQUEUE_MANAGED, BUNQUEUE_URL, BUNQUEUE_TOKEN,
+ *       HTTP_PORT, TCP_PORT, BUNQUEUE_DATA_PATH
  */
 import { logger } from './logger';
 import { ProcessManager } from './manager';
-import { createFetchHandler, resolveAllowedHosts, resolveAllowedOrigins } from './server';
+import {
+  createFetchHandler,
+  resolveAllowedHosts,
+  resolveAllowedOrigins,
+  resolveServerControlTarget,
+} from './server';
 import { installAgentShutdown } from './shutdown';
 
 const mgr = new ProcessManager();
@@ -25,8 +31,9 @@ const allowedOrigins = resolveAllowedOrigins();
 // GETs. Extend via AGENT_ALLOWED_HOSTS when fronted by a proxy on another host.
 const allowedHosts = resolveAllowedHosts();
 const token = process.env.AGENT_TOKEN || undefined;
+const controlTarget = resolveServerControlTarget(process.env);
 
-const handle = createFetchHandler(mgr, { allowedOrigins, allowedHosts, token });
+const handle = createFetchHandler(mgr, { allowedOrigins, allowedHosts, token, controlTarget });
 const stopAccepting: Array<() => unknown | Promise<unknown>> = [];
 installAgentShutdown(handle, { stopAccepting });
 
@@ -38,6 +45,12 @@ const server = Bun.serve({
 stopAccepting.push(() => server.stop());
 
 logger.info(
-  { url: `http://127.0.0.1:${PORT}/control`, allowedOrigins, allowedHosts, tokenAuth: Boolean(token) },
+  {
+    url: `http://127.0.0.1:${PORT}/control`,
+    allowedOrigins,
+    allowedHosts,
+    tokenAuth: Boolean(token),
+    serverManagement: controlTarget.mode,
+  },
   'bunqueue dashboard control agent ready'
 );

package/agent/managedTarget.ts

@@ -1,14 +1,53 @@
 import type { ServerConfig } from './manager';
 
+const MANAGED_PROXY_PATH_PATTERN = /^\/(?:[A-Za-z0-9._~-]+\/)*api$/;
+
+export interface ManagedTargetPolicy {
+  /** Exact browser-visible proxy alias accepted in addition to legacy `/api`. */
+  proxyPath: string;
+  /** Local upstream represented by the alias; it still passes the anti-SSRF gate. */
+  proxyUrl?: string;
+}
+
+/** Validate the one browser-visible proxy path that aliases the local managed server. */
+export function resolveManagedProxyPath(value: string | undefined): string {
+  const path = value?.trim() || '/api';
+  if (
+    !MANAGED_PROXY_PATH_PATTERN.test(path) ||
+    path.split('/').some((segment) => segment === '.' || segment === '..')
+  ) {
+    throw new Error('Managed proxy path must be /api or a safe root-relative path ending in /api');
+  }
+  return path;
+}
+
+/** Resolve the alias once without cloning a request or touching its body stream. */
+export function resolveManagedTargetPolicy(
+  proxyPath: string | undefined,
+  proxyUrl?: string
+): ManagedTargetPolicy {
+  return {
+    proxyPath: resolveManagedProxyPath(proxyPath),
+    proxyUrl: proxyUrl?.trim() || undefined,
+  };
+}
+
 /** Refuse agent-side SDK operations for a server the agent does not manage. */
 export function assertManagedTarget(
   query: URLSearchParams,
   config: ServerConfig,
-  proxyTarget = process.env.BUNQUEUE_URL?.trim() || 'http://localhost:6790'
+  policy: ManagedTargetPolicy | string =
+    process.env.BUNQUEUE_URL?.trim() || 'http://localhost:6790'
 ): void {
   const target = query.get('target');
   if (!target) throw new Error('Managed Bunqueue target is required');
-  if (target === '/api') {
+  const proxyPath =
+    typeof policy === 'string' ? '/api' : resolveManagedProxyPath(policy.proxyPath);
+  const proxyTarget =
+    (typeof policy === 'string' ? policy : policy.proxyUrl?.trim()) ||
+    process.env.BUNQUEUE_URL?.trim() ||
+    'http://localhost:6790';
+  if (target === '/api' || target === proxyPath) {
     assertLocalTarget(proxyTarget, config, 'Dashboard /api proxy');
     return;
   }

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.57 start',
+    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.8.59 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/queue/routes.ts

@@ -1,6 +1,6 @@
 import type { QueueMetricType } from 'bunqueue/client';
 import type { ServerConfig } from '../manager';
-import { assertManagedTarget } from '../managedTarget';
+import { assertManagedTarget, type ManagedTargetPolicy } from '../managedTarget';
 import type {
   ManagedRuntimeAdmission,
   ManagedRuntimeSnapshot,
@@ -29,32 +29,33 @@ export async function routeQueueOperationsRequest(
   config: ServerConfig,
   runtime: QueueOperationsPort,
   running: boolean,
-  admission?: ManagedRuntimeAdmission
+  admission?: ManagedRuntimeAdmission,
+  targetPolicy?: ManagedTargetPolicy
 ): Promise<RouteResponse | null> {
   const read = pathname.match(READ_ROUTE);
   if (read && method === 'GET') {
     const queue = decodedQueue(read[1]);
     if (read[2] === 'limits') {
-      const query = pinnedQuery(request, config, ['target', 'maxJobs']);
+      const query = pinnedQuery(request, config, ['target', 'maxJobs'], targetPolicy);
       assertRunning(running);
       const maxJobs = optionalMaxJobs(query);
-      return admitted(query, config, running, admission, async ({ config: current }) =>
+      return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>
         ok({ limits: await runtime.limits(current, queue, maxJobs) })
       );
     }
     if (read[2] === 'deduplication') {
-      const query = pinnedQuery(request, config, ['target', 'deduplicationId']);
+      const query = pinnedQuery(request, config, ['target', 'deduplicationId'], targetPolicy);
       const id = requiredDeduplicationId(query.get('deduplicationId'));
       assertRunning(running);
-      return admitted(query, config, running, admission, async ({ config: current }) =>
+      return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>
         ok({ jobId: await runtime.deduplicationJobId(current, queue, id) })
       );
     }
-    const query = pinnedQuery(request, config, ['target', 'type', 'start', 'end']);
+    const query = pinnedQuery(request, config, ['target', 'type', 'start', 'end'], targetPolicy);
     const type = metricType(query.get('type'));
     const range = metricsRange(query);
     assertRunning(running);
-    return admitted(query, config, running, admission, async ({ config: current }) =>
+    return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>
       ok({ metrics: await runtime.metrics(current, queue, type, range.start, range.end) })
     );
   }
@@ -62,20 +63,20 @@ export async function routeQueueOperationsRequest(
   const mutation = pathname.match(MUTATION_ROUTE);
   if (mutation && method === 'POST') {
     const queue = decodedQueue(mutation[1]);
-    const query = pinnedQuery(request, config, ['target']);
+    const query = pinnedQuery(request, config, ['target'], targetPolicy);
     assertRunning(running);
     if (mutation[2] === 'deduplication/remove') {
       const body = await exactJsonBody(request, ['deduplicationId']);
       const id = requiredDeduplicationId(
         typeof body.deduplicationId === 'string' ? body.deduplicationId : null
       );
-      return admitted(query, config, running, admission, async ({ config: current }) =>
+      return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>
         ok({ removed: await runtime.removeDeduplicationKey(current, queue, id) })
       );
     }
     const body = await exactJsonBody(request, ['maxLength']);
     const retention = eventRetention(body.maxLength);
-    return admitted(query, config, running, admission, async ({ config: current }) =>
+    return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>
       ok({ removed: await runtime.trimEvents(current, queue, retention) })
     );
   }
@@ -90,19 +91,25 @@ function admitted<T>(
   config: ServerConfig,
   running: boolean,
   admission: ManagedRuntimeAdmission | undefined,
+  targetPolicy: ManagedTargetPolicy | undefined,
   operation: (snapshot: ManagedRuntimeSnapshot) => Promise<T>
 ): Promise<T> {
   const execute = async (snapshot: ManagedRuntimeSnapshot) => {
-    assertManagedTarget(query, snapshot.config);
+    assertManagedTarget(query, snapshot.config, targetPolicy);
     assertRunning(snapshot.running);
     return operation(snapshot);
   };
   return admission ? admission(execute) : execute({ config, running });
 }
 
-function pinnedQuery(request: Request, config: ServerConfig, allowed: string[]) {
+function pinnedQuery(
+  request: Request,
+  config: ServerConfig,
+  allowed: string[],
+  targetPolicy?: ManagedTargetPolicy
+) {
   const query = exactQuery(request.url, allowed);
-  assertManagedTarget(query, config);
+  assertManagedTarget(query, config, targetPolicy);
   return query;
 }
 

package/agent/server/controlRoutes.ts

@@ -5,13 +5,32 @@ import {
   type WorkflowRuntimePort,
 } from '../workflow/runtime';
 import { readLimitedJsonBody } from './jsonBody';
+import {
+  MANAGED_CONTROL_TARGET,
+  probeExternalHealth,
+  type ServerControlTarget,
+} from './controlTarget';
 import type { AgentLifecyclePort } from './lifecycle';
 import type { RouteResponse } from './types';
 
 const MAX_CONFIG_BODY_BYTES = 64 * 1024;
 
-async function statusWithHealth(manager: ProcessManager) {
+async function statusWithHealth(manager: ProcessManager, controlTarget: ServerControlTarget) {
   const snapshot = manager.getStatus();
+  if (controlTarget.mode === 'external') {
+    const health = await probeExternalHealth(controlTarget);
+    return {
+      ...snapshot,
+      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') {
@@ -33,7 +52,7 @@ async function statusWithHealth(manager: ProcessManager) {
     }
   }
   const database = await manager.dbStats().catch(() => null);
-  return { ...snapshot, healthy, version, db: database };
+  return { ...snapshot, managementMode: 'managed' as const, healthy, version, db: database };
 }
 
 export async function routeControlRequest(
@@ -42,40 +61,45 @@ export async function routeControlRequest(
   method: string,
   manager: ProcessManager,
   runtime: WorkflowRuntimePort,
-  lifecycle?: AgentLifecyclePort
+  lifecycle?: AgentLifecyclePort,
+  controlTarget: ServerControlTarget = MANAGED_CONTROL_TARGET
 ): Promise<RouteResponse | null> {
   if (pathname === '/control/status') {
-    return { status: 200, body: await statusWithHealth(manager) };
+    return { status: 200, body: await statusWithHealth(manager, controlTarget) };
   }
   if (pathname === '/control/logs') {
     return { status: 200, body: { lines: manager.getLogs() } };
   }
   if (pathname === '/control/start' && method === 'POST') {
+    assertManagedControl(controlTarget);
     return coordinated(lifecycle, async () => {
       await manager.start();
-      return { status: 200, body: await statusWithHealth(manager) };
+      return { status: 200, body: await statusWithHealth(manager, controlTarget) };
     });
   }
   if (pathname === '/control/stop' && method === 'POST') {
+    assertManagedControl(controlTarget);
     return coordinated(lifecycle, async () => {
       await stopWithRuntimeCleanup(manager, runtime);
-      return { status: 200, body: await statusWithHealth(manager) };
+      return { status: 200, body: await statusWithHealth(manager, controlTarget) };
     });
   }
   if (pathname === '/control/restart' && method === 'POST') {
+    assertManagedControl(controlTarget);
     return coordinated(lifecycle, async () => {
       const closeResult = await settle(() => runtime.close());
       if (!closeResult.ok) {
         await stopAfterCloseFailure(manager, workflowCloseError(closeResult.error));
       }
       await manager.restart();
-      return { status: 200, body: await statusWithHealth(manager) };
+      return { status: 200, body: await statusWithHealth(manager, controlTarget) };
     });
   }
   if (pathname === '/control/config' && method === 'GET') {
     return { status: 200, body: manager.getConfig() };
   }
   if (pathname === '/control/config' && method === 'PUT') {
+    assertManagedControl(controlTarget);
     const patch = validateConfigPatch(
       await readLimitedJsonBody(request, {
         scope: 'Agent configuration',
@@ -88,6 +112,14 @@ export async function routeControlRequest(
   return null;
 }
 
+export function assertManagedControl(controlTarget: ServerControlTarget): void {
+  if (controlTarget.mode === 'external') {
+    throw new Error(
+      'Server lifecycle is disabled in external mode (BUNQUEUE_MANAGED=0); manage this broker with its external supervisor'
+    );
+  }
+}
+
 async function stopWithRuntimeCleanup(
   manager: ProcessManager,
   runtime: WorkflowRuntimePort

package/agent/server/controlTarget.ts

@@ -0,0 +1,116 @@
+import { safeErrorMessage } from '../errorMessage';
+
+export type ServerManagementMode = 'managed' | 'external';
+
+export interface ServerControlTarget {
+  mode: ServerManagementMode;
+  /** Canonical external HTTP base; present only in attach-only mode. */
+  url?: string;
+  /** Server bearer used only by the agent-side health probe. */
+  token?: string;
+}
+
+export interface ExternalHealthProbe {
+  reachable: boolean;
+  healthy: boolean;
+  statusCode: number | null;
+  version?: string;
+  error?: string;
+}
+
+export const MANAGED_CONTROL_TARGET: ServerControlTarget = Object.freeze({ mode: 'managed' });
+
+/** Resolve the immutable lifecycle mode once, before the agent starts listening. */
+export function resolveServerControlTarget(
+  env: Record<string, string | undefined> = process.env
+): ServerControlTarget {
+  const configured = env.BUNQUEUE_MANAGED?.trim().toLowerCase();
+  if (!configured || ['1', 'true', 'yes', 'on'].includes(configured)) {
+    return MANAGED_CONTROL_TARGET;
+  }
+  if (!['0', 'false', 'no', 'off'].includes(configured)) {
+    throw new Error('BUNQUEUE_MANAGED must be 1/0, true/false, yes/no, or on/off');
+  }
+  return Object.freeze({
+    mode: 'external',
+    url: normalizeExternalUrl(env.BUNQUEUE_URL),
+    token: env.BUNQUEUE_TOKEN?.trim() || undefined,
+  });
+}
+
+function normalizeExternalUrl(value: string | undefined): string {
+  const candidate = value?.trim() || 'http://localhost:6790';
+  let parsed: URL;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    throw new Error('BUNQUEUE_URL must be an absolute HTTP(S) URL in external mode');
+  }
+  if (
+    (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') ||
+    !parsed.hostname ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new Error(
+      'BUNQUEUE_URL must be a credential-free HTTP(S) URL without query or fragment in external mode'
+    );
+  }
+  const path = parsed.pathname.replace(/\/+$/, '');
+  return `${parsed.origin}${path}`;
+}
+
+/** Probe an externally supervised broker without following credential-bearing redirects. */
+export async function probeExternalHealth(target: ServerControlTarget): Promise<ExternalHealthProbe> {
+  if (target.mode !== 'external' || !target.url) {
+    throw new Error('External health probe requires an external server target');
+  }
+  let response: Response;
+  try {
+    response = await fetch(`${target.url}/health`, {
+      headers: target.token ? { Authorization: `Bearer ${target.token}` } : undefined,
+      redirect: 'error',
+      signal: AbortSignal.timeout(1500),
+    });
+  } catch (error) {
+    return {
+      reachable: false,
+      healthy: false,
+      statusCode: null,
+      error: safeErrorMessage(error),
+    };
+  }
+
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    return {
+      reachable: true,
+      healthy: false,
+      statusCode: response.status,
+      error: `Health endpoint returned non-JSON HTTP ${response.status}`,
+    };
+  }
+  const health = isRecord(body) ? body : {};
+  const healthy = response.ok && health.ok === true;
+  const version = typeof health.version === 'string' ? health.version : undefined;
+  const reportedStatus = typeof health.status === 'string' ? health.status : undefined;
+  return {
+    reachable: true,
+    healthy,
+    statusCode: response.status,
+    version,
+    error: healthy
+      ? undefined
+      : reportedStatus
+        ? `Health reported ${reportedStatus} (HTTP ${response.status})`
+        : `Health endpoint returned HTTP ${response.status}`,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/agent/server/errors.ts

@@ -18,6 +18,7 @@ const CONFLICT_MESSAGES = [
   'BUNQUEUE_WORKFLOW_QUEUE_NAME must',
   'BUNQUEUE_WORKFLOW_CONCURRENCY must',
   'Managed Bunqueue server restarted',
+  'Server lifecycle is disabled in external mode',
 ];
 
 export function errorStatus(error: unknown): number {

package/agent/server/handler.ts

@@ -3,7 +3,9 @@ import type { ProcessManager } from '../manager';
 import { QueueOperationsRuntime } from '../queue/runtime';
 import type { QueueOperationsPort } from '../queue/types';
 import { WorkflowRuntime, type WorkflowRuntimePort } from '../workflow/runtime';
+import { resolveManagedTargetPolicy } from '../managedTarget';
 import { errorMessage, errorStatus } from './errors';
+import { MANAGED_CONTROL_TARGET } from './controlTarget';
 import { AgentLifecycleGate, type AgentLifecyclePort } from './lifecycle';
 import { corsHeaders, isHostAllowed, isOriginAllowed, tokenOk } from './policy';
 import { routeAgentRequest } from './router';
@@ -39,7 +41,12 @@ export function createFetchHandler(
     allowedHosts,
     token,
     requireTokenForAll = false,
+    controlTarget = MANAGED_CONTROL_TARGET,
   } = options;
+  const managedTargetPolicy = resolveManagedTargetPolicy(
+    options.managedProxyPath,
+    options.managedProxyUrl
+  );
   const json = (body: unknown, status: number, origin: string | null) =>
     responseOf({ body, status }, origin, allowedOrigins);
 
@@ -74,7 +81,9 @@ export function createFetchHandler(
         queueRuntime,
         lifecycle,
         origin,
-        allowedOrigins
+        allowedOrigins,
+        controlTarget,
+        managedTargetPolicy
       );
       return responseOf(result, origin, allowedOrigins);
     } catch (error) {