@celilo/cli 1.14.0 → 2.1.0

package/src/services/alerting/hook-jail.test.ts

@@ -0,0 +1,66 @@
+/**
+ * D8's three states, asserted one branch at a time: only "used to jail and has
+ * stopped" raises. Steady-state unjailed — a Mac that never jailed — is a
+ * configuration fact the doctor reports, never an alert.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { JailModeRecord } from '../../hooks/jail';
+import { hookJailFailingKeys } from './hook-jail';
+
+const HOST = 'celilo-mgr';
+
+const regressed: JailModeRecord = {
+  mode: 'unjailed',
+  backend: 'none',
+  reason: 'bubblewrap is installed but could not build a namespace, so hooks run unjailed.',
+  host: HOST,
+  recordedAt: '2026-08-28T09:00:00.000Z',
+  lastJailed: { backend: 'bubblewrap', recordedAt: '2026-08-27T09:00:00.000Z' },
+};
+
+describe('hookJailFailingKeys', () => {
+  test('a host that used to jail and has stopped raises, naming the host and the reason', () => {
+    const failing = hookJailFailingKeys({ record: regressed, host: HOST }, 'critical');
+    expect(failing).toHaveLength(1);
+    expect(failing[0]?.key).toBe(`builtin:hook_jail/host:${HOST}`);
+    expect(failing[0]?.severity).toBe('critical');
+    expect(failing[0]?.message).toContain(HOST);
+    expect(failing[0]?.message).toContain('until 2026-08-27T09:00:00.000Z');
+    expect(failing[0]?.message).toContain('could not build a namespace');
+  });
+
+  test('steady-state unjailed is not an event', () => {
+    const neverJailed: JailModeRecord = {
+      mode: 'unjailed',
+      backend: 'none',
+      reason: 'macOS has no hook jail yet',
+      host: HOST,
+      recordedAt: '2026-08-28T09:00:00.000Z',
+    };
+    expect(hookJailFailingKeys({ record: neverJailed, host: HOST }, 'critical')).toEqual([]);
+  });
+
+  test('a jailed host raises nothing, which is also how the alert resolves', () => {
+    const healthy: JailModeRecord = {
+      mode: 'jailed',
+      backend: 'bubblewrap',
+      host: HOST,
+      recordedAt: '2026-08-28T09:00:00.000Z',
+    };
+    expect(hookJailFailingKeys({ record: healthy, host: HOST }, 'critical')).toEqual([]);
+  });
+
+  test('no record yet raises nothing', () => {
+    expect(hookJailFailingKeys({ record: undefined, host: HOST }, 'critical')).toEqual([]);
+  });
+
+  test("a record written by another host is a move, not this host's regression", () => {
+    expect(hookJailFailingKeys({ record: regressed, host: 'a-new-box' }, 'critical')).toEqual([]);
+  });
+
+  test("the monitor's severity is the alert's severity", () => {
+    const failing = hookJailFailingKeys({ record: regressed, host: HOST }, 'warning');
+    expect(failing[0]?.severity).toBe('warning');
+  });
+});

package/src/services/alerting/hook-jail.ts

@@ -0,0 +1,70 @@
+/**
+ * Hook-jail regression — a host that used to jail its hooks and has stopped.
+ *
+ * Design D8's three states want three different things (see
+ * openspec/changes/hook-process-boundary/design.md): jailed is normal and
+ * raises nothing; a host that never jailed (a Mac) is a configuration fact
+ * that `celilo system doctor` reports and is NOT an event; a host that ran
+ * hooks jailed yesterday and runs them unjailed today is a kernel upgrade, an
+ * AppArmor policy change, or a changed container profile, and is exactly the
+ * failure that looks like nothing. Only the third state raises here.
+ *
+ * The state this reads is `hook-jail-mode.json`, written by `recordJailMode`
+ * on every real module-hook run. The transition survives the record being
+ * overwritten because an unjailed record carries `lastJailed` — the jailed
+ * record it replaced on the same host.
+ *
+ * The monitor scheduling this check is a SELF-monitor: `celilo monitor add
+ * hook_jail` creates it `suppressible: false`, so per
+ * openspec/specs/alerting/spec.md no ancestor alert and no deploy window can
+ * silence it. Losing confinement during a broad outage is precisely when it
+ * must still page.
+ *
+ * Deliberately cheap: one local file read, no remote contact, safe on every
+ * sweep.
+ */
+
+import type { AlertSeverity } from '../../db/schema';
+import type { JailModeRecord } from '../../hooks/jail';
+import { type FailingKey, builtinAlertKey } from './keys';
+
+export const HOOK_JAIL_CHECK = 'hook_jail';
+
+export interface HookJailState {
+  /** The recorded mode, or undefined when no hook has recorded one yet. */
+  record: JailModeRecord | undefined;
+  /** The host this check runs on, compared against the record's own. */
+  host: string;
+}
+
+/**
+ * One failing key when this host used to jail and has stopped; empty
+ * otherwise. The message names the host and the reason, which is what the
+ * security-model spec requires the alert to carry.
+ *
+ * A record written by another host is ignored rather than compared: a database
+ * or data directory restored onto a new box is a move, not a regression, and
+ * the new box has its own history to make.
+ */
+export function hookJailFailingKeys(state: HookJailState, severity: AlertSeverity): FailingKey[] {
+  const { record, host } = state;
+  if (!record || record.host !== host) return [];
+  if (record.mode !== 'unjailed' || !record.lastJailed) return [];
+
+  return [
+    {
+      key: builtinAlertKey(HOOK_JAIL_CHECK, 'host', host),
+      severity,
+      message:
+        `Hooks on ${host} ran jailed (${record.lastJailed.backend}) until ` +
+        `${record.lastJailed.recordedAt} and now run unjailed: ` +
+        `${record.reason ?? 'no reason was recorded'}`,
+      details:
+        'A host that quietly stops confining hooks is a failure that otherwise\n' +
+        'looks like nothing — the usual causes are a kernel upgrade, an AppArmor\n' +
+        'policy change, or a changed container profile. `celilo system doctor`\n' +
+        'reports what the host can do right now. The alert resolves when a hook\n' +
+        'runs jailed on this host again.',
+    },
+  ];
+}

package/src/services/alerting/run-monitor.test.ts

@@ -7,6 +7,7 @@ import type { DbClient } from '../../db/client';
 import { type Monitor, alerts, monitorRuns, monitors } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
 import type { HealthCheckResult } from '../health-runner';
+import { HOOK_JAIL_CHECK, type HookJailState } from './hook-jail';
 import { moduleAlertKey, moduleCheckAlertKey } from './keys';
 import { type MonitorRunDeps, runOneMonitor } from './run-monitor';
 import { loadLiveAlerts, markUnsuppressed } from './store';
@@ -40,6 +41,7 @@ describe('runOneMonitor', () => {
       runModuleCheck: async () => result,
       runBuiltinCheck: async () => [],
       loadModuleCoverage: () => [],
+      loadJailState: () => ({ record: undefined, host: 'test-host' }),
       now: () => now,
       graceMs: 60_000,
     };
@@ -182,4 +184,64 @@ describe('runOneMonitor', () => {
     expect(summary.outcome).toBe('success');
     expect(liveKeys()).toEqual([]);
   });
+
+  describe('the hook-jail self-monitor (hook-process-boundary task 4.4)', () => {
+    const HOST = 'celilo-mgr';
+    const regressed: HookJailState = {
+      host: HOST,
+      record: {
+        mode: 'unjailed',
+        backend: 'none',
+        reason: 'bubblewrap is installed but could not build a namespace',
+        host: HOST,
+        recordedAt: NOW.toISOString(),
+        lastJailed: { backend: 'bubblewrap', recordedAt: '2026-07-27T03:00:00.000Z' },
+      },
+    };
+    const healed: HookJailState = {
+      host: HOST,
+      record: {
+        mode: 'jailed',
+        backend: 'bubblewrap',
+        host: HOST,
+        recordedAt: LATER.toISOString(),
+      },
+    };
+
+    let jailMonitor: Monitor;
+
+    beforeEach(() => {
+      db.insert(monitors)
+        .values({
+          id: 'mon-jail',
+          kind: 'builtin_check',
+          target: HOOK_JAIL_CHECK,
+          intervalMinutes: 15,
+          severity: 'critical',
+          suppressible: false,
+        })
+        .run();
+      jailMonitor = db.select().from(monitors).where(eq(monitors.id, 'mon-jail')).get() as Monitor;
+    });
+
+    const jailDeps = (state: HookJailState, now: Date = NOW): MonitorRunDeps => ({
+      ...deps(healthy, now),
+      loadJailState: () => state,
+    });
+
+    test('a jailed-to-unjailed transition fires an alert naming the host', async () => {
+      const summary = await runOneMonitor(db, jailMonitor, jailDeps(regressed));
+      expect(summary.outcome).toBe('success');
+      const live = loadLiveAlerts(db, jailMonitor.id);
+      expect(live.map((a) => a.key)).toEqual([`builtin:hook_jail/host:${HOST}`]);
+      const row = db.select().from(alerts).where(eq(alerts.monitorId, jailMonitor.id)).get();
+      expect(row?.message).toContain(HOST);
+    });
+
+    test('re-jailing resolves it by set difference', async () => {
+      await runOneMonitor(db, jailMonitor, jailDeps(regressed));
+      await runOneMonitor(db, jailMonitor, jailDeps(healed, LATER));
+      expect(loadLiveAlerts(db, jailMonitor.id)).toEqual([]);
+    });
+  });
 });

package/src/services/alerting/run-monitor.ts

@@ -19,6 +19,7 @@ import type { HealthCheckResult } from '../health-runner';
 import { failingKeysFromFindings } from './builtin-monitors';
 import { HEALTH_COVERAGE_CHECK, healthCoverageFailingKeys } from './health-coverage';
 import type { ModuleCoverageInput } from './health-coverage';
+import { HOOK_JAIL_CHECK, type HookJailState, hookJailFailingKeys } from './hook-jail';
 import {
   type FailingKey,
   builtinMonitorKey,
@@ -35,6 +36,8 @@ export interface MonitorRunDeps {
   runBuiltinCheck(category: DriftCategory): Promise<DriftFinding[]>;
   /** Module roster for the health-coverage check. */
   loadModuleCoverage(): ModuleCoverageInput[];
+  /** Recorded jail mode and current host, for the hook-jail self-monitor. */
+  loadJailState(): HookJailState;
   now(): Date;
   /** Grace window before a new alert may notify. */
   graceMs: number;
@@ -95,6 +98,15 @@ async function runCheck(
     };
   }
 
+  // Same shape: one local file read. This is the self-monitor for D8's third
+  // state — a host that used to jail its hooks and has stopped.
+  if (monitor.target === HOOK_JAIL_CHECK) {
+    return {
+      outcome: 'success',
+      failingKeys: hookJailFailingKeys(deps.loadJailState(), severity),
+    };
+  }
+
   const category = monitor.target as DriftCategory;
   try {
     const findings = await deps.runBuiltinCheck(category);

package/src/services/alerting/sweep-runner.test.ts

@@ -42,6 +42,7 @@ describe('runSweep', () => {
       runModuleCheck: async () => result,
       runBuiltinCheck: async () => [],
       loadModuleCoverage: () => [],
+      loadJailState: () => ({ record: undefined, host: 'test-host' }),
       now: () => now,
       graceMs: 60_000,
     };

package/src/services/backup-create.ts

@@ -41,6 +41,7 @@ import {
   refuseIfInFlight,
   startOperation,
 } from './module-operations';
+import { remoteAccessPolicy } from './remote-access';
 import { stageSystemState } from './system-state-stage';
 
 export interface BackupCreateOptions {
@@ -399,6 +400,7 @@ export async function createModuleBackup(
       {
         debug: false,
         systems: getModuleSystems(moduleId, db),
+        remoteAccess: remoteAccessPolicy(moduleId, db),
       },
     );
 
@@ -563,6 +565,7 @@ export async function importModuleBackup(
         {
           debug: false,
           systems: getModuleSystems(moduleId, db),
+          remoteAccess: remoteAccessPolicy(moduleId, db),
         },
       );
 

package/src/services/backup-restore.ts

@@ -30,6 +30,7 @@ import {
   refuseIfInFlight,
   startOperation,
 } from './module-operations';
+import { remoteAccessPolicy } from './remote-access';
 
 export interface RestoreResult {
   success: boolean;
@@ -288,6 +289,7 @@ export async function restoreModuleBackup(
       {
         debug: false,
         systems: getModuleSystems(backup.moduleId, db),
+        remoteAccess: remoteAccessPolicy(backup.moduleId, db),
       },
     );
 

package/src/services/control-plane-bootstrap.test.ts

@@ -0,0 +1,177 @@
+/**
+ * The control-plane bootstrap, which replaced celilo-mgmt's `on_install`
+ * (celilo#1225).
+ *
+ * Every dependency is injected, so these run against a real database and no
+ * host: no resolver file is read, no ssh-keygen runs, no bus is opened. That is
+ * the property the hook could not have. Its equivalents shelled out to the CLI,
+ * so the only way to exercise them was to have a celilo on PATH — which is also
+ * why the jail broke them and no unit test noticed.
+ */
+
+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 type { DbClient } from '../db/client';
+import { systemConfig } from '../db/schema';
+import { setupTestDatabaseAt } from '../test-utils/database';
+import {
+  type ControlPlaneBootstrapOptions,
+  bootstrapControlPlane,
+} from './control-plane-bootstrap';
+import type { FleetFinding } from './fleet-checks';
+
+const DNS = { primary: '9.9.9.9', fallback: '8.8.4.4' };
+const PUBLIC_KEY = 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI test celilo-fleet';
+
+function dispatcher(status: FleetFinding['status']): FleetFinding {
+  return {
+    id: 'dispatcher',
+    title: 'Event dispatcher',
+    status,
+    summary: `dispatcher ${status}`,
+    detail: [],
+    remediation: status === 'ok' ? null : 'start the dispatcher',
+    autoFixable: false,
+  };
+}
+
+function configValue(db: DbClient, key: string): string | undefined {
+  return db.select().from(systemConfig).where(eq(systemConfig.key, key)).get()?.value ?? undefined;
+}
+
+describe('bootstrapControlPlane', () => {
+  let dir: string;
+  let db: DbClient;
+  /** Every sleep the poll performed, so waiting is asserted rather than timed. */
+  let sleeps: number[];
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'cpb-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabaseAt(dbPath);
+    sleeps = [];
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function run(overrides: Partial<ControlPlaneBootstrapOptions> = {}) {
+    return bootstrapControlPlane({
+      db,
+      discoverDnsImpl: () => DNS,
+      ensureFleetKeyImpl: () => ({ publicKey: PUBLIC_KEY, created: true }),
+      discoverNetworkImpl: () => ({ applied: ['network.internal.subnet = 10.0.0.0/24'] }),
+      probeDispatcher: () => dispatcher('ok'),
+      sleep: async (ms) => {
+        sleeps.push(ms);
+      },
+      ...overrides,
+    });
+  }
+
+  test('records the discovered DNS and the fleet public key in system config', async () => {
+    await run();
+
+    expect(configValue(db, 'dns.primary')).toBe('9.9.9.9');
+    expect(configValue(db, 'dns.fallback')).toBe('8.8.4.4');
+    expect(configValue(db, 'ssh.public_key')).toBe(PUBLIC_KEY);
+  });
+
+  test('returns what each step found, so the caller renders and this does not', async () => {
+    const result = await run();
+
+    expect(result.dns).toEqual(DNS);
+    expect(result.fleetKey).toEqual({ publicKey: PUBLIC_KEY, created: true });
+    expect(result.network.applied).toEqual(['network.internal.subnet = 10.0.0.0/24']);
+    expect(result.dispatcher.status).toBe('ok');
+  });
+
+  test('a dispatcher already up is probed once and never waited for', async () => {
+    let probes = 0;
+    await run({
+      probeDispatcher: () => {
+        probes++;
+        return dispatcher('ok');
+      },
+    });
+
+    expect(probes).toBe(1);
+    expect(sleeps).toEqual([]);
+  });
+
+  test('a dispatcher still starting is polled until it answers', async () => {
+    // The role enables the supervisor unit moments before this runs, so the
+    // first probe legitimately finds nothing. Two failures then success.
+    const readings: FleetFinding['status'][] = ['fail', 'fail', 'ok'];
+    let probes = 0;
+    const result = await run({
+      probeDispatcher: () => dispatcher(readings[probes++] ?? 'ok'),
+    });
+
+    expect(probes).toBe(3);
+    expect(sleeps).toEqual([1000, 1000]);
+    expect(result.dispatcher.status).toBe('ok');
+  });
+
+  test('a dispatcher that never answers gives up after the attempt budget', async () => {
+    let probes = 0;
+    const result = await run({
+      probeDispatcher: () => {
+        probes++;
+        return dispatcher('fail');
+      },
+      dispatcherAttempts: 5,
+    });
+
+    expect(probes).toBe(5);
+    expect(sleeps).toHaveLength(4);
+    // Reported, not thrown. The caller decides how loud to be, which is what
+    // lets `module deploy` fail the install and a later caller merely warn.
+    expect(result.dispatcher.status).toBe('fail');
+  });
+
+  test('a warn reading is accepted rather than polled against', async () => {
+    let probes = 0;
+    await run({
+      probeDispatcher: () => {
+        probes++;
+        return dispatcher('warn');
+      },
+    });
+
+    expect(probes).toBe(1);
+    expect(sleeps).toEqual([]);
+  });
+
+  test('a box with no default route still gets its DNS and key recorded', async () => {
+    // `discoverAndRecordNetwork` reports a skip rather than throwing, and a
+    // box celilo cannot read a network from must not fail the whole deploy.
+    const result = await run({
+      discoverNetworkImpl: () => ({ applied: [], skipped: 'no default route' }),
+    });
+
+    expect(result.network.skipped).toBe('no default route');
+    expect(configValue(db, 'dns.primary')).toBe('9.9.9.9');
+    expect(configValue(db, 'ssh.public_key')).toBe(PUBLIC_KEY);
+  });
+
+  test('an existing fleet key is recorded without being reminted', async () => {
+    const result = await run({
+      ensureFleetKeyImpl: () => ({ publicKey: PUBLIC_KEY, created: false }),
+    });
+
+    expect(result.fleetKey.created).toBe(false);
+    expect(configValue(db, 'ssh.public_key')).toBe(PUBLIC_KEY);
+  });
+});

package/src/services/control-plane-bootstrap.ts

@@ -0,0 +1,176 @@
+/**
+ * Initialise the management box's own celilo state, during the celilo-mgmt
+ * deploy.
+ *
+ * ## Why this is here and not in a hook
+ *
+ * It was a hook until celilo#1225. `modules/celilo-mgmt/scripts/on_install.ts`
+ * reached every one of these operations by spawning the `celilo` CLI, which a
+ * jailed hook cannot do: the jail's mount set binds no `/usr/bin`, no
+ * `/usr/local/bin` and no shell, so `execFileSync` dies on the missing binary
+ * and `execSync` dies one step earlier on the missing `/bin/sh`. The deploy ran
+ * Ansible to completion and then failed in its own install hook, on every host
+ * where a jail backend exists.
+ *
+ * The fix is not to let the hook reach the CLI. It is that none of this wanted
+ * to be in a hook. celilo-mgmt is never deployed to a remote box (ruled
+ * 2026-09-02), so the host being configured is always the host celilo runs on,
+ * and every step below is celilo acting on itself: read this box's resolvers,
+ * mint celilo's own fleet key, record celilo's own network, check celilo's own
+ * event bus. A hook was a process boundary with celilo on both sides of it.
+ *
+ * ## What it does NOT do
+ *
+ * It does not decide whether to run. The deploy path does that, from the
+ * control-plane module id, which celilo already keys on in three other places
+ * (`manifest/validate.ts`'s privileged allow-list, `capability-loader.ts`'s
+ * `CONTROL_PLANE_MODULE_ID`, `fleet-checks.ts`'s `CONTROL_PLANE_MODULE`).
+ *
+ * It also does not print. It returns what happened and the caller renders it,
+ * so the same function serves a deploy, a test and any later caller without
+ * carrying a logger's opinions (Rule 10.1).
+ */
+
+import { type Bus, defineEvents, openBus } from '@celilo/event-bus';
+import { getEventBusPath } from '../config/paths';
+import type { DbClient } from '../db/client';
+import { type DnsServers, discoverDns } from './dns-discovery';
+import { type FleetFinding, checkDispatcher } from './fleet-checks';
+import { type FleetKey, ensureFleetKey } from './fleet-key';
+import { type NetworkDiscoveryResult, discoverAndRecordNetwork } from './network-discovery';
+import { initializeSystem } from './system-init';
+
+/**
+ * How long to give a dispatcher that is still coming up.
+ *
+ * The Ansible role enables its supervisor unit moments before this runs, so a
+ * first probe legitimately finds nothing. Five one-second attempts is what the
+ * hook this replaced used, and no case has argued for more.
+ */
+const DISPATCHER_ATTEMPTS = 5;
+const DISPATCHER_INTERVAL_MS = 1_000;
+
+export interface ControlPlaneBootstrapOptions {
+  db: DbClient;
+  /** Injectable so tests drive the whole sequence without a host or a bus. */
+  discoverDnsImpl?: () => DnsServers;
+  ensureFleetKeyImpl?: () => FleetKey;
+  discoverNetworkImpl?: (db: DbClient) => NetworkDiscoveryResult;
+  /**
+   * One dispatcher reading. Injectable so a test needs no bus at all; the
+   * default opens celilo's own and runs the four-part check against it.
+   */
+  probeDispatcher?: () => FleetFinding;
+  sleep?: (ms: number) => Promise<void>;
+  dispatcherAttempts?: number;
+}
+
+export interface ControlPlaneBootstrapResult {
+  dns: DnsServers;
+  fleetKey: FleetKey;
+  network: NetworkDiscoveryResult;
+  /** The last dispatcher reading. `fail` means no dispatcher ever answered. */
+  dispatcher: FleetFinding;
+}
+
+/**
+ * The control plane reads the bus's own health tables and emits nothing, so it
+ * registers no event schemas — the same empty registry `celilo events` opens
+ * with.
+ */
+const NO_SCHEMAS = defineEvents({});
+
+/**
+ * Read the dispatcher's state from celilo's own bus.
+ *
+ * `checkDispatcher` is deliberately used in place of the "is the process up?"
+ * read the hook did. Its docblock records why: a naive liveness check reports
+ * green on a dispatcher that is running, unsupervised, on stale code, and
+ * delivering nothing.
+ */
+/**
+ * Open celilo's own bus, do one thing with it, close it.
+ *
+ * There is an async twin below and the two are NOT interchangeable: handing an
+ * async function to this one closes the bus when the promise is CREATED, not
+ * when it settles, so the work runs against a closed handle.
+ */
+export function withCeliloBus<T>(fn: (bus: Bus) => T): T {
+  const bus: Bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+  try {
+    return fn(bus);
+  } finally {
+    bus.close();
+  }
+}
+
+/** The async twin. See the warning on `withCeliloBus`. */
+export async function withCeliloBusAsync<T>(fn: (bus: Bus) => Promise<T>): Promise<T> {
+  const bus: Bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+  try {
+    return await fn(bus);
+  } finally {
+    bus.close();
+  }
+}
+
+function probeOwnDispatcher(): FleetFinding {
+  return withCeliloBus((bus) => checkDispatcher(bus));
+}
+
+/** Poll until a dispatcher answers, or the attempts run out. */
+async function waitForDispatcher(
+  probe: () => FleetFinding,
+  attempts: number,
+  sleep: (ms: number) => Promise<void>,
+): Promise<FleetFinding> {
+  let finding = probe();
+  for (let attempt = 1; attempt < attempts && finding.status === 'fail'; attempt++) {
+    await sleep(DISPATCHER_INTERVAL_MS);
+    finding = probe();
+  }
+  return finding;
+}
+
+/**
+ * Record what celilo needs to know about the box it runs on.
+ *
+ * Ordering is not cosmetic. The fleet key and the DNS servers are written in
+ * ONE `initializeSystem` call, because that function applies defaults and the
+ * init sentinel alongside the keys it is given, and calling it twice makes the
+ * second call re-derive everything the first already settled. The hook this
+ * replaced made two round trips through the CLI for exactly that reason and
+ * had no way not to.
+ *
+ * The network is recorded after, not in the same call: `system apply-config`
+ * REFUSES `network.*` keys outright, so a network is not something you write
+ * through the config surface at all. `discoverAndRecordNetwork` is the only
+ * path, it is idempotent, and it never overwrites an operator's value.
+ */
+export async function bootstrapControlPlane(
+  options: ControlPlaneBootstrapOptions,
+): Promise<ControlPlaneBootstrapResult> {
+  const {
+    db,
+    discoverDnsImpl = discoverDns,
+    ensureFleetKeyImpl = ensureFleetKey,
+    discoverNetworkImpl = discoverAndRecordNetwork,
+    probeDispatcher = probeOwnDispatcher,
+    sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms)),
+    dispatcherAttempts = DISPATCHER_ATTEMPTS,
+  } = options;
+
+  const dns = discoverDnsImpl();
+  const fleetKey = ensureFleetKeyImpl();
+
+  initializeSystem(db, {
+    'dns.primary': dns.primary,
+    'dns.fallback': dns.fallback,
+    'ssh.public_key': fleetKey.publicKey,
+  });
+
+  const network = discoverNetworkImpl(db);
+  const dispatcher = await waitForDispatcher(probeDispatcher, dispatcherAttempts, sleep);
+
+  return { dns, fleetKey, network, dispatcher };
+}