@celilo/cli 4.0.0 → 5.0.0

package/src/cli/commands/system-reboot.ts

@@ -0,0 +1,126 @@
+/**
+ * `celilo system reboot` — reboot the management server (celilo#1378).
+ *
+ * Thin adapter (Rule 10.5): parse flags, obtain consent, compose the real
+ * host's dependencies, call the service, format the result. Every judgement —
+ * the in-flight refusal, the boot-id bookkeeping, what counts as "came back" —
+ * lives in `services/system-reboot.ts` and is tested against a fake host.
+ *
+ * Consent follows the repo's flag-or-interview rule: `--allow-reboot` (or
+ * `--yes`) wins, otherwise the question goes on the event bus so a headless
+ * responder can answer it. No stdin prompt.
+ *
+ * `--verify` is the other half, and it exists because the process asking for a
+ * reboot dies in it: no single call can both reboot this host and report that
+ * it came back. See the service's header.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { defineEvents, openBus } from '@celilo/event-bus';
+import { getEventBusPath } from '../../config/paths';
+import { askConfirm, withInterviewSession } from '../../services/bus-interview';
+import {
+  BOOT_ID_PATH,
+  collectRebootPendingDeps,
+  requestReboot,
+  verifyReturn,
+} from '../../services/system-reboot';
+import { hasFlag } from '../parser';
+import type { CommandResult } from '../types';
+
+/** The deb's wrapper — the same binary `apt-upgrade` re-execs for migrations. */
+const CELILO_BIN = '/usr/local/bin/celilo';
+
+/** This command publishes nothing; it only reads the bus's health. */
+const NO_SCHEMAS = defineEvents({});
+
+function readBootId(): string | null {
+  try {
+    const id = readFileSync(BOOT_ID_PATH, 'utf-8').trim();
+    return id.length > 0 ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Does the installed CLI answer? Its version, or null. */
+function installedCliVersion(): string | null {
+  try {
+    const { status, stdout } = spawnSync(CELILO_BIN, ['--version'], { encoding: 'utf-8' });
+    if (status !== 0) return null;
+    const version = (stdout ?? '').trim();
+    return version.length > 0 ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is the dispatcher alive? Confirmed rather than sampled — a dispatcher
+ * starved on a box that just booted looks exactly like a dead one for one
+ * sample (celilo#1399).
+ */
+async function dispatcherHeartbeatLive(): Promise<boolean> {
+  let bus: ReturnType<typeof openBus> | undefined;
+  try {
+    bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+    const health = await bus.healthConfirmed();
+    return health.status !== 'no_dispatcher' && health.status !== 'wedged';
+  } catch {
+    return false;
+  } finally {
+    bus?.close?.();
+  }
+}
+
+export async function handleSystemReboot(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  if (hasFlag(flags, 'verify')) {
+    const result = await verifyReturn({
+      bootId: readBootId,
+      heartbeatLive: dispatcherHeartbeatLive,
+      cliVersion: installedCliVersion,
+    });
+    return result.success
+      ? { success: true, message: result.message ?? 'Reboot verified.' }
+      : { success: false, error: result.error ?? 'Reboot could not be verified.' };
+  }
+
+  // Report the condition before asking, so the operator is answering about
+  // the host in front of them rather than about the word "reboot".
+  const { verdict } = collectRebootPendingDeps();
+  const why = verdict.pending
+    ? verdict.reasons.join('; ')
+    : 'no pending kernel or deferred restart was detected';
+
+  const consented =
+    flags['allow-reboot'] === true ||
+    hasFlag(flags, 'yes') ||
+    (await withInterviewSession(() =>
+      askConfirm({
+        scope: 'system-reboot',
+        key: 'reboot',
+        message: `Reboot the management server? This takes down the dispatcher, the MCP server and the remote API. Condition: ${why}.`,
+        defaultValue: false,
+      }),
+    ));
+
+  if (!consented) {
+    return { success: false, error: 'Reboot not approved — re-run with --allow-reboot.' };
+  }
+
+  const result = requestReboot(
+    {
+      bootId: readBootId,
+      issueReboot: () => spawnSync('sudo', ['systemctl', 'reboot'], { stdio: 'inherit' }),
+    },
+    why,
+  );
+
+  return result.success
+    ? { success: true, message: result.message ?? 'Reboot issued.' }
+    : { success: false, error: result.error ?? 'Reboot refused.' };
+}

package/src/cli/commands/system-update.ts

@@ -31,12 +31,14 @@ import { collectBrowserPinDeps } from '../../services/audit/browser-pin';
 import { fetchLatestCliVersion } from '../../services/audit/cli-version';
 import { unusedPublicDnsProbe } from '../../services/audit/public-dns';
 import { makeJournalReader, readAppliedMigrations } from '../../services/audit/schema';
+import { collectServerBunPinDeps } from '../../services/audit/server-bun-pin';
 import { createModuleBackup, createSystemStateBackup } from '../../services/backup-create';
 import { BACKUP_SCHEDULE_CONFIG_KEY } from '../../services/backup-schedule';
 import { runAllHealthChecks, runModuleHealthCheck } from '../../services/health-runner';
 import { collectJailExemptions } from '../../services/jail-exemptions';
 import { configOverride, parseStoredConfigValue } from '../../services/module-config';
 import { deployModule } from '../../services/module-deploy';
+import { collectRebootPendingDeps } from '../../services/system-reboot';
 import { buildModuleGraph } from '../../services/update/dep-graph';
 import {
   type ModuleSnapshot,
@@ -549,6 +551,8 @@ export async function handleSystemUpdate(
       })),
     },
     browserPin: collectBrowserPinDeps(upgradableModules),
+    serverBunPin: collectServerBunPinDeps(),
+    rebootPending: collectRebootPendingDeps(),
     terraformPlan: {
       modules: upgradableModules.map((m) => ({
         id: m.id,
@@ -616,6 +620,7 @@ export async function handleSystemUpdate(
     secretsDecryptable: { results: [] },
     servicesReachable: { results: [] },
     machinesReachable: { results: [] },
+    machineInterfaceZones: { machines: [] },
     // Public reachability needs a network round trip per name; the update
     // flow's partial audit does no probing. `system audit` and the scheduled
     // monitor own this check.

package/src/cli/completion.ts

@@ -439,14 +439,14 @@ export async function getCompletions(words: string[], current: number): Promise<
   }
 
   if (command === 'machine' && currentIndex === 1) {
-    const subcommands = ['add', 'list', 'status', 'remove', 'earmark', 'detect'];
+    const subcommands = ['add', 'list', 'status', 'remove', 'earmark', 'reclassify', 'detect'];
     return filterSuggestions(subcommands, args[1] || '');
   }
 
   // Machine remove/earmark - complete with machine hostnames and IPs
   if (
     command === 'machine' &&
-    (args[1] === 'remove' || args[1] === 'earmark') &&
+    (args[1] === 'remove' || args[1] === 'earmark' || args[1] === 'reclassify') &&
     currentIndex === 2
   ) {
     const machineList = await listMachines();
@@ -704,6 +704,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'update',
       'doctor',
       'migrate',
+      'reboot',
     ];
     return filterSuggestions(subcommands, args[1] || '');
   }

package/src/cli/index.ts

@@ -65,6 +65,7 @@ import {
 import { handleMachineAdd } from './commands/machine-add';
 import { handleMachineEarmark } from './commands/machine-earmark';
 import { handleMachineList } from './commands/machine-list';
+import { handleMachineReclassify } from './commands/machine-reclassify';
 import { handleMachineRemove } from './commands/machine-remove';
 import { handleMachineStatus } from './commands/machine-status';
 import { moduleAudit } from './commands/module-audit';
@@ -132,6 +133,7 @@ import { handleSystemDoctor } from './commands/system-doctor';
 import { handleSystemEnsureFleetKey } from './commands/system-ensure-fleet-key';
 import { handleSystemInit } from './commands/system-init';
 import { handleSystemMigrate } from './commands/system-migrate';
+import { handleSystemReboot } from './commands/system-reboot';
 import { handleSystemSecretGet } from './commands/system-secret-get';
 import { handleSystemSecretSet } from './commands/system-secret-set';
 import { handleSystemUpdate } from './commands/system-update';
@@ -1097,6 +1099,10 @@ Examples:
   celilo machine earmark 10.0.10.10 caddy
   celilo machine earmark pi-01 --clear
 
+  # Re-classify stored interface zone labels after a zone-model change
+  celilo machine reclassify celilo-mgr
+  celilo machine reclassify celilo-mgr --apply
+
   # Remove machine (by hostname or IP)
   celilo machine remove pi-01
   celilo machine remove 10.0.10.10 --force
@@ -1214,6 +1220,11 @@ Subcommands:
 
   doctor [--fix]                       Diagnose system prerequisites and @celilo/* version drift
 
+  reboot [--allow-reboot] [--verify]   Reboot the management server. Refuses while a module
+                                       operation is in flight and names it. The process asking
+                                       dies in the reboot, so --verify is what confirms the host
+                                       came back: boot id changed, dispatcher live, CLI answering.
+
 Runbook:
   https://celilo.computer/docs/system-update
   (offline summary in apps/celilo/docs/INDEX.md)
@@ -2269,6 +2280,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       return handleMachineEarmark(parsed.args, parsed.flags);
     }
 
+    if (parsed.subcommand === 'reclassify') {
+      return handleMachineReclassify(parsed.args, parsed.flags);
+    }
+
     return {
       success: false,
       error: `Unknown machine subcommand: ${parsed.subcommand}\n\nRun "celilo machine --help" for usage`,
@@ -2369,6 +2384,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       return handleSystemMigrate(parsed.args, parsed.flags);
     }
 
+    if (parsed.subcommand === 'reboot') {
+      return handleSystemReboot(parsed.args, parsed.flags);
+    }
+
     return {
       success: false,
       error: `Unknown system subcommand: ${parsed.subcommand}\n\nRun "celilo system --help" for usage`,
@@ -2559,6 +2578,26 @@ function parseCommand(command: string): string[] {
   return args;
 }
 
+/**
+ * Write to stdout and WAIT for it to reach the far end before returning.
+ *
+ * `process.stdout.write()` followed by `process.exit()` silently drops
+ * everything past the pipe buffer (64 KiB on macOS) whenever stdout is a pipe
+ * rather than a TTY — so `celilo completion zsh > file` was whole while
+ * `GENERATED=$(celilo completion zsh)` lost its tail mid-line, with exit 0 and
+ * no diagnostic anywhere. install-zsh-completion.sh captured exactly that way
+ * and installed a truncated, unparseable `_celilo`.
+ *
+ * Awaiting the stream's own write callback is the whole fix: it fires once the
+ * bytes have been accepted downstream, so the following `process.exit()` can no
+ * longer race the flush.
+ */
+async function writeStdout(text: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    process.stdout.write(text, (err) => (err ? reject(err) : resolve()));
+  });
+}
+
 async function serverMode(): Promise<void> {
   const readline = await import('node:readline');
 
@@ -2680,7 +2719,7 @@ export async function main(): Promise<void> {
     if (result.success) {
       // For completion mode, output raw text without formatting
       if (process.argv.includes('--get-completions') || process.argv.includes('completion')) {
-        console.log(result.message);
+        await writeStdout(`${result.message}\n`);
         process.exit(0);
       }
 
@@ -2703,7 +2742,7 @@ export async function main(): Promise<void> {
       // `line.startsWith('<module-id> ')` over `celilo module list` match
       // nothing — read in celilo#695 as a missing module rather than as a
       // parse failure, at the cost of a full e2e run.
-      process.stdout.write(`${result.message}\n`);
+      await writeStdout(`${result.message}\n`);
       process.exit(0);
     }
 

package/src/cli/restore-migration-failure.test.ts

@@ -37,7 +37,7 @@ const MODULE_ID = 'restore-migration-test';
 
 /** The manifest the module row carries: one on_restore hook, the fixture. */
 const MODULE_MANIFEST = {
-  celilo_contract: '1.0',
+  celilo_contract: '2.0',
   id: MODULE_ID,
   name: 'Restore Migration Test',
   version: '0.0.1',

package/src/cli/stdout-pipe-flush.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test';
+
+// `process.stdout.write()` followed by `process.exit()` drops everything past
+// the 64 KiB OS pipe buffer when stdout is a pipe. The zsh completion script is
+// the CLI's largest stdout payload (~70 KB), so it is the cheapest witness.
+//
+// The capture has to go through a real shell: a Bun.spawn pipe is not an OS
+// pipe and never truncates, so a test written that way passes with the defect
+// present. `$(...)` is how install-zsh-completion.sh reads the generator, and
+// it read 65536 bytes of a 70092-byte script — exit 0, no diagnostic, and a
+// `_celilo` cut off mid-line installed into the operator's fpath.
+//
+// The invariant is that a capture and a redirect of the same command agree to
+// within the trailing newlines `$(...)` strips. Both are measured in the same
+// shell, so nothing here depends on the generator's exact size.
+describe('CLI stdout survives an OS pipe', () => {
+  test('completion zsh is captured whole, not truncated at 64 KiB', async () => {
+    const cli = `bun run ${import.meta.dir}/index.ts completion zsh`;
+    const proc = Bun.spawn(
+      [
+        'bash',
+        '-c',
+        `f=$(mktemp); ${cli} > "$f"; out=$(${cli}); printf %s "$out" | wc -c; wc -c < "$f"; rm -f "$f"`,
+      ],
+      { stdout: 'pipe', stderr: 'ignore' },
+    );
+    const [captured, redirected] = (await new Response(proc.stdout).text())
+      .trim()
+      .split('\n')
+      .map((n) => Number(n.trim()));
+
+    expect(redirected).toBeGreaterThan(65536); // below the buffer this proves nothing
+    expect(redirected - captured).toBeLessThanOrEqual(2); // only stripped newlines
+  }, 60_000);
+});

package/src/cli/tui/audit-state.ts

@@ -73,6 +73,8 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
   'schema',
   'capability_abi',
   'browser_pin',
+  'server_bun_pin',
+  'reboot_pending',
   'terraform_plan',
   'module_versions',
   'module_configs',
@@ -96,6 +98,8 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
 ];
 
 export const CATEGORY_LABELS: Record<DriftCategory, string> = {
+  server_bun_pin: 'Server bun pin',
+  reboot_pending: 'Pending reboot',
   module_integrity: 'Module integrity',
   detect_without_converge: 'Drift without converge',
   jail_exemptions: 'Hook jail exemptions',

package/src/db/private-routes.test.ts

@@ -0,0 +1,159 @@
+/**
+ * `private_routes` — the internal ingress's own declared rows (slice 2 of
+ * providers-converge-declared-state, task 2.1).
+ *
+ * Same shape as `web_routes`, separate table on purpose. caddy derives the
+ * hostnames it SERVES from every row of `web_routes`, so a private route stored
+ * there would be picked up and served by the PUBLIC ingress — the exact leak
+ * caddy-internal exists to prevent (celilo#846). The isolation is therefore a
+ * property worth asserting rather than assuming: a table boundary is only as
+ * good as the queries that respect it.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { setupTestDatabaseAt } from '../test-utils/database';
+import { resetTestDbPath } from '../test-utils/db-path';
+import type { DbClient } from './client';
+import { modules, privateRoutes, webRoutes } from './schema';
+
+describe('private_routes', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'private-routes-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabaseAt(dbPath);
+
+    for (const id of ['wireguard-manager', 'hello-foo']) {
+      db.insert(modules)
+        .values({
+          id,
+          name: id,
+          version: '1.0.0',
+          manifestData: {},
+          sourcePath: join(dir, 'modules', id),
+          state: 'VERIFIED',
+        })
+        .onConflictDoNothing()
+        .run();
+    }
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    resetTestDbPath();
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function insertPrivate(overrides: Record<string, unknown> = {}) {
+    db.insert(privateRoutes)
+      .values({
+        slug: 'vpn-manager',
+        moduleId: 'wireguard-manager',
+        type: 'reverse_proxy',
+        path: '/',
+        hostname: 'vpn-manager.celilo.computer',
+        targetHost: '10.0.20.15',
+        targetPort: 3000,
+        websocket: false,
+        ...overrides,
+      })
+      .run();
+  }
+
+  test('carries web_routes columns, so one renderer shape serves both', () => {
+    insertPrivate();
+    const row = db.select().from(privateRoutes).get();
+
+    // Named individually rather than compared as a set: the point is that a
+    // renderer written against WebRoute reads this row unchanged.
+    expect(row?.slug).toBe('vpn-manager');
+    expect(row?.moduleId).toBe('wireguard-manager');
+    expect(row?.type).toBe('reverse_proxy');
+    expect(row?.path).toBe('/');
+    expect(row?.hostname).toBe('vpn-manager.celilo.computer');
+    expect(row?.targetHost).toBe('10.0.20.15');
+    expect(row?.targetPort).toBe(3000);
+    expect(row?.websocket).toBe(false);
+    expect(row?.contentHash ?? null).toBeNull();
+    expect(row?.createdAt).toBeInstanceOf(Date);
+    expect(row?.updatedAt).toBeInstanceOf(Date);
+  });
+
+  test('a private route is unreachable from the public provider query (celilo#846)', () => {
+    insertPrivate();
+
+    // This is the query the public provider runs — buildRouteOps.getAllRoutes,
+    // which caddy's renderer turns into served hostnames. It must not see a
+    // private row, or the private hostname gets a public site block and a
+    // public certificate.
+    const publicRows = db.select().from(webRoutes).all();
+    expect(publicRows).toEqual([]);
+
+    // And the converse, so the assertion cannot pass merely because nothing
+    // was written anywhere.
+    expect(db.select().from(privateRoutes).all()).toHaveLength(1);
+  });
+
+  test('a public and a private route may share a hostname and path without colliding', () => {
+    // Separate tables means separate unique indexes. Same name served by both
+    // ingresses is a legitimate split-horizon arrangement, and a shared table
+    // would have rejected the second row.
+    insertPrivate({ hostname: 'shared.celilo.computer' });
+    db.insert(webRoutes)
+      .values({
+        slug: 'shared',
+        moduleId: 'hello-foo',
+        type: 'reverse_proxy',
+        path: '/',
+        hostname: 'shared.celilo.computer',
+        targetHost: '10.0.10.9',
+        targetPort: 8080,
+        websocket: false,
+      })
+      .run();
+
+    expect(db.select().from(privateRoutes).all()).toHaveLength(1);
+    expect(db.select().from(webRoutes).all()).toHaveLength(1);
+  });
+
+  test('uniqueness is scoped to (hostname, path), as web_routes is', () => {
+    insertPrivate();
+    expect(() => insertPrivate({ moduleId: 'hello-foo', slug: 'other' })).toThrow();
+  });
+
+  test('removing the consumer removes its routes (consumer cascade)', () => {
+    insertPrivate();
+    db.insert(privateRoutes)
+      .values({
+        slug: 'other',
+        moduleId: 'hello-foo',
+        type: 'reverse_proxy',
+        path: '/other',
+        hostname: 'vpn-manager.celilo.computer',
+        targetHost: '10.0.20.16',
+        targetPort: 3000,
+        websocket: false,
+      })
+      .run();
+
+    db.delete(modules).where(eq(modules.id, 'wireguard-manager')).run();
+
+    // The departing consumer's row goes; the other consumer's stays. A private
+    // route outliving its module would render a site block pointing at a
+    // backend nothing owns.
+    const left = db.select().from(privateRoutes).all();
+    expect(left).toHaveLength(1);
+    expect(left[0]?.moduleId).toBe('hello-foo');
+  });
+});

package/src/db/schema.ts

@@ -816,6 +816,55 @@ export const webRoutes = sqliteTable(
   }),
 );
 
+/**
+ * Private-route registry — the desired-state store for the `private_web`
+ * capability (openspec/changes/providers-converge-declared-state, slice 2).
+ *
+ * `web_routes`' columns, its own table. The shape is shared so ONE renderer
+ * shape serves both ingresses and the plumbing around them is the same
+ * (design D1); the table is separate because the PUBLIC provider derives the
+ * hostnames it serves from every row of `web_routes`, so a private route
+ * stored there would be picked up and served publicly — the exact leak
+ * caddy-internal exists to prevent (celilo#846). Two tables is what makes that
+ * impossible rather than merely intended.
+ *
+ * This replaces caddy-internal's `routes` module-config key, which held the
+ * same rows as module business inside one module's config. No data migration
+ * (design D9): the table starts empty, and when caddy-internal deploys,
+ * provider arrival re-registers its consumers, whose hooks write their routes
+ * into it inside that same deploy.
+ * @owner capability:private_web — one row is one route on the internal ingress
+ */
+export const privateRoutes = sqliteTable(
+  'private_routes',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    slug: text('slug').notNull(),
+    moduleId: text('module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    type: text('type').$type<'static' | 'reverse_proxy'>().notNull(),
+    path: text('path').notNull(),
+    /** FQDN this route serves under, in the INTERNAL DNS view only. */
+    hostname: text('hostname').notNull(),
+    targetHost: text('target_host'),
+    targetPort: integer('target_port'),
+    websocket: integer('websocket', { mode: 'boolean' }).notNull().default(false),
+    contentHash: text('content_hash'),
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    // Scoped to hostname exactly as web_routes is, and scoped to THIS table:
+    // the same hostname and path may exist on both ingresses, which is a
+    // legitimate split-horizon arrangement.
+    hostnamePathUnique: uniqueIndex('private_routes_hostname_path_idx').on(
+      table.hostname,
+      table.path,
+    ),
+  }),
+);
+
 /**
  * Port-forward registry — the desired-state store for the `firewall` capability
  * (openspec/changes/unified-management-no-ssh/proposal.md). One row per exposed forward. `exposeService`

package/src/hooks/broker.ts

@@ -105,6 +105,18 @@ export interface Broker {
   outcome(): HookOutcome | undefined;
   /** Every protocol-level complaint, for the error message when one matters. */
   faults(): string[];
+  /**
+   * The capability calls that are still in flight, newest last, each rendered
+   * as `provider_module:capability.method (Ns)`.
+   *
+   * A hook that dies at its total timeout has usually died WAITING on one of
+   * these, and the bare "Hook total timeout exceeded" names only the hook —
+   * never what it was waiting for. Measured 2026-09-21 (celilo#1403):
+   * bna-yard-sale's on_install died at 120s blocked on caddy's 75s route
+   * reconcile, and the log's only tell was a `publishStaticSite` push line
+   * with no matching completion. The operator had to infer the provider.
+   */
+  pendingCalls(): string[];
   /** Refuse further calls. Idempotent. Called on kill and again on cleanup. */
   stop(): void;
   /** Close the socket and remove its directory. */
@@ -184,6 +196,8 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
   let outcome: HookOutcome | undefined;
   let stopped = false;
   const faults: string[] = [];
+  /** In-flight capability calls by frame id, so a timeout can name them. */
+  const pending = new Map<string, { capability: string; method: string; startedAt: number }>();
   let connection: Socket | undefined;
   // Already resolved: no connection means nothing left to deliver.
   let connectionClosed: Promise<void> = Promise.resolve();
@@ -300,6 +314,7 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       return;
     }
 
+    pending.set(id, { capability: capabilityName, method, startedAt: Date.now() });
     try {
       const value = await (fn as (...a: unknown[]) => unknown).apply(capability, args);
       options.onActivity();
@@ -307,6 +322,8 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     } catch (error) {
       options.onActivity();
       send({ type: 'throw', id, error: serializeError(error) });
+    } finally {
+      pending.delete(id);
     }
   }
 
@@ -384,6 +401,20 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       ]),
     outcome: () => outcome,
     faults: () => [...faults],
+    pendingCalls: () => {
+      const now = Date.now();
+      return [...pending.values()]
+        .sort((a, b) => a.startedAt - b.startedAt)
+        .map((call) => {
+          // `providerModuleId` is stamped onto the capability's data half by
+          // the loader, so the message can name the MODULE the hook is waiting
+          // on and not only the capability it asked through.
+          const view = options.capabilities[call.capability] as Record<string, unknown> | undefined;
+          const provider = typeof view?.providerModuleId === 'string' ? view.providerModuleId : '';
+          const waited = Math.round((now - call.startedAt) / 1000);
+          return `${provider ? `${provider}:` : ''}${call.capability}.${call.method} (${waited}s)`;
+        });
+    },
     stop: () => {
       stopped = true;
     },