@celilo/cli 5.0.0 → 5.1.0

package/CELILO_SUBSYSTEMS.md

@@ -201,6 +201,7 @@ runner seam (`execRunner` real / `createMockRunner` for tests) lives in
 
 - **Hook executor / ABI** — `apps/celilo/src/hooks/executor.ts` (`invokeHook`, `executeHookScript`, `checkRequiredCapabilities`), types in `apps/celilo/src/hooks/types.ts` (`HookContext`, `HookDefinition`, `HookName`). Named-hook runner: `apps/celilo/src/hooks/run-named-hook.ts`. Manifest hook config: `apps/celilo/src/hooks/load-hook-config.ts`.
 - **Hook process boundary (a hook is a program celilo RUNS)** — `apps/celilo/src/hooks/hook-protocol.ts` (the NDJSON frame union, `HOOK_PROTOCOL_VERSION`, `serializeError`/`deserializeError`), `apps/celilo/src/hooks/broker.ts` (`startBroker`, `capabilityShape`), `apps/celilo/src/hooks/hook-runner-entry.ts` + `apps/celilo/src/hooks/hook-runner.ts` (the spawned shim — the ONLY thing that `import()`s module code; the entry exists to install the advisory lint before the shim's import graph can ESM-load `node:fs`, see `unjailed-lint.ts`). `executeHookScript` spawns `bun hook-runner-entry.ts` over a Unix socket instead of importing; the nine `invokeHook` call sites and `defineHook` are unchanged. **The broker does not know what a capability is**: it sends a shape descriptor built by the same own-string-key walk `wrapWithLogging` does (functions → `methods`, everything else → `data`, which is where `stampProvider`'s `providerModuleId` lives), and the shim rebuilds forwarding proxies from it — so an optional method a provider did not implement is absent rather than present-and-throwing, and `if (cap.registerTrustedSource)` keeps answering correctly. A socket rather than stdout because module scripts spawn subprocesses and a grandchild writing to fd 1 would corrupt the frame stream. Two consequences worth knowing: the child's environment is an **allow-list** (`hookChildEnv` — how to run: `PATH`, `HOME`, `LANG`, `TZ`, `TMPDIR`; whom to trust: `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `SSL_CERT_DIR`; the proxy variables; the `CELILO_HOOK_*` channels; `CELILO_DEBUG` — `FORWARDED_ENV` in executor.ts is the source of truth), so a hook reading any other operator variable now gets `undefined`; and a timeout is a real SIGTERM-then-SIGKILL with the broker refusing further capability calls, replacing a `Promise.race` that cancelled nothing and let a "timed out" hook go on writing DNS and firewall state (celilo#1003). Capability PROVIDER factories still load in-process — they ARE the broker's implementation. Stages 1 and 2 of `openspec/changes/hook-process-boundary`; the filesystem is claimed by the jail below, and SSH reachability by the remote-ops broker next.
+- **Hook-owned state (a hook WRITES what it discovers; it never returns it)** — `apps/celilo/src/hooks/hook-store.ts` (broker side, over `(db, moduleId, manifest, masterKey)`) and `apps/celilo/src/hooks/hook-store-proxy.ts` (the child-side buffering proxy). Two `HookStore` instances reach every hook as `context.config` and `context.secrets`, each with async `get`/`set`/`delete`/`transaction` — async because a hook is a subprocess and every call is a broker round trip over the `store` RPC family (hook protocol version 2). `config` validates against the `variables.owns` entries declared `source: hook` and writes plaintext via `upsertModuleConfig`; `secrets` validates against `secrets.declares` and encrypts. **An undeclared name THROWS, naming the module and the declared set** (design D2) — a silent drop is the failure this whole subsystem exists to delete. `transaction(fn)` buffers CHILD-side, so a throwing `fn` sends no frame at all and the broker applies a finished op list inside one `db.transaction`. The executor injects both lazily through a `hookStores` provider at all nine `invokeHook` sites; a provider-less run REFUSES store writes loudly rather than dropping them. **The counterpart fact is an absence**: contract 1.0 swept a hook's RETURNED record into secrets and config from three capture sites in the deploy path, and all three are gone — nothing anywhere persists a hook return value, `'1.0'` is refused by name as a RETIRED contract, and the recurrence gate is `apps/celilo/test-integration/module/hook-returns-are-never-persisted.test.ts` (behavioural for `validate_config`/`on_install`, reach-measured static over every `invokeHook` caller for `container_created`). A framework-owned provider secret goes through the named `recordProviderSecret` in `secrets/storage.ts`, which no hook can reach. See `openspec/changes/hook-owned-state/`.
 - **Unjailed advisory lint (task 4.7, NOT a security boundary)** — `apps/celilo/src/hooks/unjailed-lint.ts`. Where there is no jail backend the executor passes the run's derived mount set to the shim in the environment (`CELILO_HOOK_MOUNT_SET`), and the shim wraps the path-taking `node:fs` / `node:fs/promises` functions so an access outside the set (or a write to a read-only row) warns through the hook's own logger: "on a jailed host this would fail", and that it is advisory. It is the mount-set derivation's SECOND consumer, so it cannot drift from what the jail enforces. It observes JS-level `node:fs` calls only — module code bypasses it trivially — and it must never be described as a boundary, in code or output.
 - **Remote-ops broker (reachability scoped by the credential, stage 3 / D12)** — `apps/celilo/src/hooks/remote-broker.ts` (`startRemoteBroker`, `RemoteAccessPolicy`) answering a SECOND socket beside the capability one, with the policy in `apps/celilo/src/services/remote-access.ts` (`remoteAccessPolicy`) and the asking half inside `@celilo/capabilities`' own remote primitives (`packages/capabilities/src/remote.ts`, "The hook remote-ops bridge"). The jail binds no `~/.ssh`, so a hand-built `ssh` cannot authenticate; the primitives detect `CELILO_HOOK_REMOTE_SOCKET`, send each operation as a STRUCTURED request (never a shell string — the broker rebuilds the ssh line itself), and the broker checks the target against `ownedSystemModuleIds` + `getModuleSystems` before running anything, refusing with the module, the target, and the capability route named. Requests carrying the module's OWN credential (an `identityFile` crossing as content and materialised per call, or `installAuthorizedKey`'s password — the cPanel case) are scoped by that credential instead; an explicit non-root user likewise, because the fleet key's authority is root on fleet systems. Stream primitives' LOCAL paths are confined to the run's granted roots (stateDir, screenshots, generated/, declared path inputs), or `streamBackup` would be a write-as-celilo oracle. Attribution is by the module that PERFORMS the operation: a hook's request to the hook's module (the nine `invokeHook` sites build the policy), a provider's transport to the provider's module — providers run in-process and do not cross this socket, and `public_web`'s hand-built upload was replaced by the Ansible static-content converge (capability-owned-tables stage 4, celilo#1014). Residual, recorded rather than papered over: a hook can still `fetch()` any HTTP endpoint directly; only `probeHttp` consults the target check.
 - **Hook jail (a hook sees the paths it was given, and nothing else)** — `apps/celilo/src/hooks/mount-set.ts` (`deriveMountSet`, `toBwrapArgs`, `forbiddenPaths` — PURE, computes a filesystem view and touches nothing) and `apps/celilo/src/hooks/jail.ts` (`detectJailBackend`, `planJailedSpawn`, `realpathRequest`, `runtimeModulePathsFor`, `recordJailMode` — the half that touches the machine). `executeHookScript` spawns the shim under `bwrap` with the module's tree read-only, `state/` + `generated/` + this run's `screenshots/<run>` read-write on top of it, each contract-declared path input at its declared access, the broker's socket directory, the runtime and the `node_modules` the shim resolves through, and `/tmp` a fresh tmpfs FIRST so it cannot erase the socket or a staged input. `~/.ssh` is deliberately NOT bound (stage 3, D12): withholding the credential is what makes the remote-ops broker's target check a boundary. **The acceptance criterion is absence, not a check**: the module store and the data directory are simply not bound, so `master.key` and a sibling module give `ENOENT`. The set is DERIVED — a module cannot ask for more — and `bwrap` itself is never in it, because the AppArmor profile grants `userns` to `/usr/bin/bwrap` for anyone on the box (design D9). Backend detection RUNS bubblewrap rather than looking for it (four different denials all leave the binary in place), and the resulting mode is written to `hook-jail-mode.json` beside celilo's other per-machine state rather than logged, so a host that stops jailing is readable. The policy is `auto` / `required` / `off`, resolved in a fixed precedence: the `CELILO_HOOK_JAIL` environment variable, then the stored `hooks.jail_policy` system config key (`celilo system config set hooks.jail_policy <value>`, which asks an interview question before writing `off` unless `--force`), then the default, which is **`off`** (ce-rez7). Jailing begins because an operator set a policy, never because an upgrade installed a backend — celilo-mgr's 2026-09-07 move to 1:2.2.1 installed bubblewrap and loaded the AppArmor profile and hooks kept running unjailed, which is the ruling working. `resolveJailPolicy` returns the source alongside the policy and `system doctor` renders it, so an effective value is always locatable. macOS has a `sandbox-exec` backend in the union, but `auto` defers on it (ce-29z: sandbox-exec DENIES undeclared writes where bubblewrap masks them, and D14's declared-path mechanism is not built), so the hook runs unjailed with the mode recorded; `required` bypasses the deferral for an operator who opts in. An `unjailed` record carries `lastJailed` (the jailed record it replaced on the same host), which is what the `hook_jail` self-monitor reads (`services/alerting/hook-jail.ts`, created unsuppressible by `celilo monitor add hook_jail`) to alert on a host that used to jail and has stopped. `celilo system doctor`'s "Hook execution" section (`renderHookExecutionSection`) reports the live mode and, when unjailed, why.
@@ -252,6 +253,7 @@ to look, which is how a forgotten pause actually gets found.
 
 - **Generator** — `apps/celilo/src/templates/generator.ts` — `generateTemplates` (orchestration), plus Terraform/Ansible file handling.
 - **Variable resolution** — `apps/celilo/src/variables/resolver.ts` (parser: `apps/celilo/src/variables/parser.ts`). Supported prefixes: `$self`, `$system`, `$secret`, `$system_secret`, `$capability`, `$infra`.
+- **Where a config value came from (`module_configs.source`)** — the `source` column (migration `0031_module_config_source.sql`, nullable, no backfill — nothing in an existing row proves who wrote it). The variable `source:` enum in `apps/celilo/src/manifest/schema.ts` and `schemas/module-manifest.schema.json` carries **`hook`** alongside `user`/`system`/`capability`/`infrastructure`/`terraform`: the value is written by the owning module's own hook through `context.config.set`, so the configuration interview never prompts for it (`deploy-validation.ts`, `deploy-preflight.ts`, `templates/generator.ts` all skip it the way they skip `infrastructure`) and `celilo module config set` refuses it — `isDerivedVariable` refuses every non-`user` source, and `describeDerivedSource`/`explainNotSettable` name the accessor. An operator and a hook writing the same key would otherwise overwrite each other, which is what `source: user` on four wireguard keys actually did.
 
 ## Secrets
 

package/MODULE_PRIMITIVES.md

@@ -51,6 +51,7 @@ expect(probe(sys, { kind: 'systemd', unit: 'caddy' }, run).healthy).toBe(true);
 | Read a unit's journal | `tailLog` / `grepLog` | `ssh … journalctl` |
 | Run a secret on a command line | `runAppCommandWithSecret` | secret on argv |
 | Anything else with no capability/HTTP/converge path | `runAppCommand` (+ `// escape-hatch:`) | a raw ssh string |
+| Persist state the hook discovered | `context.config.set` / `context.secrets.set` | returning it; `execFileSync('celilo', …)` |
 
 **Reach for a capability method first.** If another module already provides the
 thing (open a port → `firewall.exposeService`; register a route →
@@ -177,6 +178,14 @@ directly — prefer the specific primitive. `opts` is `{ input?, timeoutMs? }`.
 - **No `sleep`** — `waitFor` on the real condition.
 - **Computed config → `applyRenderedConfig`**, not `ssh cat >`. It validates and
   rolls back; a broken config never goes live.
+- **State a hook discovered is WRITTEN, never returned.** `context.config.set`
+  if it is not sensitive, `context.secrets.set` if it is — sensitivity decides
+  the store, and nothing else does. Declare the name first (`source: hook` in
+  `variables.owns`, or `secrets.declares`) or the write throws. A returned
+  record is persisted nowhere, and the hook jail has no `celilo` binary, so
+  shelling out to `celilo module config set` reports success and writes
+  nothing. Details: MODULE_DEVELOPMENT_GUIDE.md, "Persisting state a hook
+  discovers".
 
 See also: `CELILO_SUBSYSTEMS.md` (the primitive impls + the firewall converge),
 `openspec/changes/unified-management-no-ssh/proposal.md` (the design), `reference/MODULE_DEVELOPMENT_GUIDE.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -59,7 +59,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^6.0.0",
+    "@celilo/capabilities": "^6.1.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.14.0",
     "@celilo/event-bus": "^0.7.0",

package/src/hooks/capability-loader-orchestrator-state.test.ts

@@ -0,0 +1,158 @@
+/**
+ * `orchestrator_state` reaches a module through the loader, and only when the
+ * manifest declares it.
+ *
+ * INV-2 (module-orchestrator-primitives design.md): the declaration is the
+ * authorization. Like `control_plane_api`, this capability is framework-granted
+ * — no provider module exists — so the ordinary "inject everything buildable"
+ * loop does not apply and the loader must gate the injection on the `requires`
+ * line. Modeled on `capability-loader-control-plane-api.test.ts`, which proves
+ * the same property for `control_plane_api` through the loader rather than on
+ * the builder, because the loader is where a wrong argument would be passed.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import type { HookLogger } from '@celilo/capabilities';
+import type { DbClient } from '../db/client';
+import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
+import { loadCapabilityFunctions } from './capability-loader';
+
+const noopLogger: HookLogger = {
+  info() {},
+  warn() {},
+  error() {},
+  success() {},
+};
+
+function installModule(db: DbClient, moduleId: string, manifest: Record<string, unknown>): void {
+  db.$client.run(
+    `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES (?, ?, '1.0.0', '/tmp/${moduleId}', ?)`,
+    [moduleId, moduleId, JSON.stringify(manifest)],
+  );
+}
+
+const DECLARES = {
+  requires: { capabilities: [{ name: 'orchestrator_state', version: '1.0.0' }] },
+};
+
+describe('orchestrator_state injection', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  test('a module that declares it gets it, with no provider module deployed', async () => {
+    installModule(db, 'wireguard', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('wireguard', db, noopLogger);
+
+    expect(capabilities.orchestrator_state).toBeTruthy();
+    const state = capabilities.orchestrator_state as Record<string, unknown>;
+    expect(typeof state.get_system_config).toBe('function');
+  });
+
+  test('a module that declares it as optional gets it too', async () => {
+    installModule(db, 'someday-consumer', {
+      optional: { capabilities: [{ name: 'orchestrator_state', version: '1.0.0' }] },
+    });
+
+    const capabilities = await loadCapabilityFunctions('someday-consumer', db, noopLogger);
+
+    expect(capabilities.orchestrator_state).toBeTruthy();
+  });
+
+  test('a module that declares nothing does NOT get it', async () => {
+    installModule(db, 'hello-foo', { requires: { capabilities: [] } });
+
+    const capabilities = await loadCapabilityFunctions('hello-foo', db, noopLogger);
+
+    expect(capabilities.orchestrator_state).toBeUndefined();
+  });
+
+  test('a module that requires something ELSE does NOT get it', async () => {
+    installModule(db, 'hello-bar', {
+      requires: { capabilities: [{ name: 'firewall', version: '1.0.0' }] },
+    });
+
+    const capabilities = await loadCapabilityFunctions('hello-bar', db, noopLogger);
+
+    expect(capabilities.orchestrator_state).toBeUndefined();
+  });
+
+  test('the injected read works end to end through the loader', async () => {
+    // Through the loader, not only on the builder: the loader is where a
+    // wrong db handle or a wrong module id would be passed.
+    installModule(db, 'wireguard', DECLARES);
+    db.$client.run(
+      `INSERT INTO system_config (key, value) VALUES ('network.control-plane-vpn.subnet', '10.255.255.0/24')`,
+    );
+
+    const capabilities = await loadCapabilityFunctions('wireguard', db, noopLogger);
+    const state = capabilities.orchestrator_state as {
+      get_system_config(request: { key: string }): Promise<{ value: string | null }>;
+    };
+
+    await expect(
+      state.get_system_config({ key: 'network.control-plane-vpn.subnet' }),
+    ).resolves.toEqual({ value: '10.255.255.0/24' });
+  });
+
+  test('the injected table refuses a request naming a module (INV-1 through the loader)', async () => {
+    installModule(db, 'wireguard', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('wireguard', db, noopLogger);
+    const state = capabilities.orchestrator_state as {
+      get_system_config(request: object): Promise<unknown>;
+    };
+    const smuggled = { key: 'k', module: 'celilo-mgmt' } as never;
+
+    await expect(state.get_system_config(smuggled)).rejects.toThrow(/'wireguard'/);
+  });
+
+  test('an allow-listed module gets the privileged list_machines verb', async () => {
+    // list_machines is a per-module trust decision (design INV-2): the pool
+    // goes only to the modules the allow-list names, even though both modules
+    // here declare the same capability for their config reads.
+    installModule(db, 'celilo-mgmt', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('celilo-mgmt', db, noopLogger);
+    const state = capabilities.orchestrator_state as Record<string, unknown>;
+
+    expect(typeof state.get_system_config).toBe('function');
+    expect(typeof state.list_machines).toBe('function');
+  });
+
+  test('a module declaring the capability but not allow-listed does NOT get list_machines', async () => {
+    installModule(db, 'wireguard', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('wireguard', db, noopLogger);
+    const state = capabilities.orchestrator_state as Record<string, unknown>;
+
+    expect(typeof state.get_system_config).toBe('function');
+    expect(state.list_machines).toBeUndefined();
+  });
+
+  test('the privileged list reads end to end through the loader', async () => {
+    // Through the loader, not only on the builder: the loader is where a
+    // wrong allow-list lookup or a wrong db handle would be passed.
+    installModule(db, 'celilo-mgmt', DECLARES);
+    db.$client.run(
+      `INSERT INTO machines (id, hostname, zone, ip_address, ssh_user, ssh_key_encrypted, hardware, role, interfaces)
+       VALUES ('m-1', 'pibox-1', 'dmz', '10.0.20.11', 'peba', 'enc:x', '{"cpu_cores":4,"memory_mb":8192,"disk_gb":64}', 'host', '[]')`,
+    );
+
+    const capabilities = await loadCapabilityFunctions('celilo-mgmt', db, noopLogger);
+    const state = capabilities.orchestrator_state as {
+      list_machines(request: object): Promise<{ machines: Array<Record<string, unknown>> }>;
+    };
+
+    const { machines } = await state.list_machines({});
+    expect(machines).toHaveLength(1);
+    expect(machines[0]).toMatchObject({ hostname: 'pibox-1', zone: 'dmz', role: 'host' });
+  });
+});

package/src/hooks/capability-loader.ts

@@ -41,6 +41,7 @@ import {
   systemConfig,
   webRoutes,
 } from '../db/schema';
+import { allowedPrivilegedVerbs } from '../manifest/validate';
 import { resolveModuleStateWebRoot, resolveModuleWebRoot } from '../module/web-root';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
@@ -53,6 +54,7 @@ import {
 import { CONTROL_PLANE_MODULE_ID, getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
+import { buildOrchestratorState } from '../services/orchestrator-state';
 import { buildPortForwardStore } from '../services/port-forwards';
 import {
   TRUSTED_SUBNETS_CONFIG_KEY,
@@ -940,6 +942,28 @@ export async function loadCapabilityFunctions(
     debugLog(`control_plane_api: framework-granted, injected for ${consumingModuleId}`);
   }
 
+  // orchestrator_state: framework-granted like control_plane_api, and gated on
+  // the DECLARATION for the same reason (INV-2). The verbs read celilo's own
+  // tables — system_config, and for allow-listed modules the machine pool — so
+  // the requires line is the authorization, and a module that never declared
+  // the capability holds no table at all. Built for the calling module (INV-1):
+  // the db this function already holds is the store the verbs read, passed
+  // explicitly so the service tests can pin the closure against an isolated
+  // database. The privileged verbs come from the allow-list map, not the
+  // declaration: declaring the capability buys the config reads, not the pool.
+  if (consumerDeclares(db, consumingModuleId, 'orchestrator_state')) {
+    result.orchestrator_state = wrapWithLogging(
+      buildOrchestratorState(
+        consumingModuleId,
+        db,
+        allowedPrivilegedVerbs('orchestrator_state', consumingModuleId),
+      ),
+      logger,
+      'orchestrator_state',
+    );
+    debugLog(`orchestrator_state: framework-granted, injected for ${consumingModuleId}`);
+  }
+
   // celilo#1072: the CALL is the binding, not the resolution. Everything above
   // is injected whether or not the consumer declared it — the loop's own
   // comment says "not just required ones" — so recording what was resolved

package/src/hooks/mount-set.test.ts

@@ -177,6 +177,34 @@ describe('~/.ssh is never in the mount set (stage 3, D12)', () => {
   });
 });
 
+describe('a bound browser without fonts is a browser that cannot render', () => {
+  // celilo#1422. Binding BROWSER_ROOT makes the browser START; it does not make
+  // it RENDER. With no font configuration in the jail, Blink's remote font face
+  // path hits a fatal NOTREACHED on any page that loads a web font and the
+  // renderer dies mid navigation — surfacing as a Playwright selector timeout
+  // that names neither fonts nor the jail. Measured on the management host,
+  // same bwrap invocation, only these rows differing: 12 NOTREACHED without,
+  // 0 with.
+  //
+  // Tied to BROWSER_ROOT deliberately. Fonts are only interesting BECAUSE a
+  // browser is bound, so if the browser bind is ever dropped this test should
+  // be reconsidered with it rather than left asserting an unrelated directory.
+  test('every font directory the renderer needs is bound alongside the browser', () => {
+    const paths = pathsOf(BASE);
+    expect(paths).toContain(BROWSER_ROOT);
+    for (const dir of ['/usr/share/fonts', '/usr/share/fontconfig', '/etc/fonts']) {
+      expect(paths).toContain(dir);
+    }
+  });
+
+  test('fonts are read-only — a hook has no business writing to them', () => {
+    for (const dir of ['/usr/share/fonts', '/usr/share/fontconfig', '/etc/fonts']) {
+      const row = deriveMountSet(BASE).entries.find((e) => e.path === dir);
+      expect(row?.mode).toBe('ro');
+    }
+  });
+});
+
 describe('the fleet browser is reachable, and only read-only (task 4.10)', () => {
   test('BROWSER_ROOT is bound', () => {
     // Task 4.10 names `~/.cache/ms-playwright`. That path is stale:

package/src/hooks/mount-set.ts

@@ -112,6 +112,34 @@ export interface MountSetRequest {
 /** Directories whose contents the runtime needs in order to start at all. */
 const RUNTIME_SUPPORT_DIRS = ['/usr/lib', '/lib', '/lib64', '/etc/ssl'] as const;
 
+/**
+ * What RENDERING needs, as distinct from what running needs.
+ *
+ * Omitting these does not stop the browser starting, which is why it survived
+ * the bind added for `BROWSER_ROOT` below. It kills the RENDERER, and only on a
+ * page that loads a web font. Blink's remote font face path hits a fatal
+ * `NOTREACHED` with no font configuration present, the renderer dies mid
+ * navigation, and Playwright reports `Target page, context or browser has been
+ * closed` while awaiting a selector — which reads as a slow page or a flaky
+ * selector and names neither fonts nor the jail.
+ *
+ * Measured 2026-09-25 on the management host, same bwrap invocation, only these
+ * three rows differing (celilo#1422):
+ *
+ *   without: 12x ERROR ... remote_font_face_source.cc:365] NOTREACHED hit.
+ *   with:     0
+ *
+ * celilo PROVISIONS these deliberately — `celilo-mgmt`'s browser block installs
+ * `fontconfig` and `fonts-dejavu-core` because "a screenshot with no glyphs is
+ * not worth retaining" (D7). So the fleet already pays for fonts and the jail
+ * was hiding them from the one process that needs them: the provisioning and
+ * the mount set disagreed, and the browser lost.
+ *
+ * Read-only, and absent rows are dropped like any other, so a host with no
+ * fonts installed is exactly as it was rather than newly fatal.
+ */
+const FONT_DIRS = ['/usr/share/fonts', '/usr/share/fontconfig', '/etc/fonts'] as const;
+
 /**
  * What resolving a hostname needs. Read-only, and absent ones are dropped.
  *
@@ -220,6 +248,11 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   for (const dir of RUNTIME_SUPPORT_DIRS) {
     entries.push(entry(dir, 'ro', 'shared libraries and trust store', 'runtime'));
   }
+  for (const dir of FONT_DIRS) {
+    entries.push(
+      entry(dir, 'ro', 'fonts — the renderer dies without them, see FONT_DIRS', 'runtime'),
+    );
+  }
   for (const file of RESOLVER_FILES) {
     entries.push(entry(file, 'ro', 'name resolution — see RESOLVER_FILES', 'runtime'));
   }

package/src/manifest/schema.ts

@@ -860,6 +860,20 @@ export const ModuleManifestSchema = z
         command: z.string().min(1).optional(),
         /** Path to a build script (relative to module directory). Mutually exclusive with command. */
         script: z.string().min(1).optional(),
+        /**
+         * Wall-clock budget for the build, in seconds (celilo#1252).
+         *
+         * The packager used to kill every build at a hardcoded 300s. A module
+         * whose build command declares its own retry budget — forgejo fetches
+         * two release archives from codeberg with `curl --retry` — could
+         * express far more wall clock than that cap allowed, and the retries
+         * written for a flaky upstream never ran. The cap is a property of the
+         * fetch the module performs, so the module names it.
+         *
+         * `packages/e2e/tests/module-build-budget-fits-timeout.test.ts` fails
+         * when a build command's worst-case curl budget exceeds this value.
+         */
+        timeout_seconds: z.number().int().positive().max(7200).default(300),
         artifacts: z
           .array(
             z

package/src/manifest/validate-privileged.test.ts

@@ -6,7 +6,7 @@
 
 import { describe, expect, it } from 'bun:test';
 import type { ModuleManifest } from './schema';
-import { validatePrivilegedCapabilities } from './validate';
+import { isPrivilegedCapability, validatePrivilegedCapabilities } from './validate';
 
 function buildManifest(overrides: Partial<ModuleManifest>): ModuleManifest {
   return {
@@ -81,4 +81,43 @@ describe('validatePrivilegedCapabilities', () => {
     );
     expect(result?.errors).toHaveLength(2);
   });
+
+  describe('framework-granted capabilities that any module may declare', () => {
+    // `control_plane_api` and `orchestrator_state` are framework-granted but NOT
+    // allow-listed: the `requires` line is the authorization (web-ui-console
+    // D7b, module-orchestrator-primitives D3). The registration that matters is
+    // `isPrivilegedCapability` — when it returns false for one of these, three
+    // call sites (`capabilities/validation.ts:50`, `services/deploy-
+    // validation.ts:182`, `hooks/executor.ts:720`) go looking for a provider
+    // module that can never exist and refuse the module with "no module
+    // provides this capability". `validatePrivilegedCapabilities` alone cannot
+    // see that failure, which is why the predicate is asserted directly.
+    it('treats orchestrator_state as framework-granted', () => {
+      expect(isPrivilegedCapability('orchestrator_state')).toBe(true);
+    });
+
+    it('treats control_plane_api as framework-granted', () => {
+      expect(isPrivilegedCapability('control_plane_api')).toBe(true);
+    });
+
+    it('accepts any module requiring orchestrator_state', () => {
+      const result = validatePrivilegedCapabilities(
+        buildManifest({
+          id: 'wireguard',
+          requires: { capabilities: [{ name: 'orchestrator_state', version: '1.0.0' }] },
+        }),
+      );
+      expect(result).toBeNull();
+    });
+
+    it('still refuses a privilege that IS allow-listed, so the two categories stay distinct', () => {
+      const result = validatePrivilegedCapabilities(
+        buildManifest({
+          id: 'wireguard',
+          requires: { capabilities: [{ name: 'cross_module_read', version: '1.0.0' }] },
+        }),
+      );
+      expect(result).not.toBeNull();
+    });
+  });
 });

package/src/manifest/validate.ts

@@ -213,8 +213,32 @@ export function validateCapabilityNames(manifest: ModuleManifest): ValidationErr
  */
 const PRIVILEGED_CAPABILITY_ALLOW_LIST: Record<string, readonly string[]> = {
   cross_module_read: ['celilo-mgmt'],
+  // A PRIVILEGED VERB, not a capability: `orchestrator_state` itself stays in
+  // FRAMEWORK_GRANTED_CAPABILITIES (any module may read system_config), and
+  // this verb-scoped key names the only module trusted with the machine pool
+  // (design INV-2). The key never matches a declared capability name, so
+  // import-time validation is untouched; the capability loader consults it
+  // through allowedPrivilegedVerbs when it builds the table.
+  'orchestrator_state.list_machines': ['celilo-mgmt'],
 };
 
+/**
+ * The privileged verbs of one capability a module may hold, from the
+ * allow-list above. Verb-scoped keys are `<capability>.<verb>`; a module not
+ * named for a verb gets no entry, and the builder omits the method.
+ */
+export function allowedPrivilegedVerbs(capability: string, moduleId: string): string[] {
+  const verbs: string[] = [];
+  for (const key of Object.keys(PRIVILEGED_CAPABILITY_ALLOW_LIST)) {
+    const [keyCapability, keyVerb] = key.split('.');
+    if (keyCapability === capability && keyVerb) {
+      const allowed = PRIVILEGED_CAPABILITY_ALLOW_LIST[key];
+      if (allowed.includes(moduleId)) verbs.push(keyVerb);
+    }
+  }
+  return verbs;
+}
+
 /**
  * Framework-granted capabilities that any module may declare.
  *
@@ -235,7 +259,17 @@ const PRIVILEGED_CAPABILITY_ALLOW_LIST: Record<string, readonly string[]> = {
  * ids in core, so every new console-shaped consumer would need a core change
  * and a `.deb` release before it could be imported at all.
  */
-const FRAMEWORK_GRANTED_CAPABILITIES: ReadonlySet<string> = new Set(['control_plane_api']);
+const FRAMEWORK_GRANTED_CAPABILITIES: ReadonlySet<string> = new Set([
+  'control_plane_api',
+  // module-orchestrator-primitives slice 2: reads of celilo's own state
+  // (`system_config`, and the privileged `list_machines` verb for
+  // allow-listed modules). The table is built for the calling module and the
+  // declaration is the authorization, like `control_plane_api` — no
+  // capability-level allow-list, because the config reads are not a per-module
+  // trust decision. The pool snapshot verb is, and its allow-list lives in
+  // PRIVILEGED_CAPABILITY_ALLOW_LIST as a verb-scoped key.
+  'orchestrator_state',
+]);
 
 /**
  * Whether `name` is a framework-granted privilege rather than a normal

package/src/module/packaging/build.ts

@@ -348,12 +348,19 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
       // variable expansion would strip shell-only bash variables like
       // $STAGE before bash ever sees them.
       const buildEnv = { ...process.env, CELILO_MODULE_SOURCE_DIR: sourceDir };
+      // celilo#1252: the budget is the MODULE's, not a constant three layers
+      // away. forgejo's fetch declares `curl --retry 10 --max-time 900` and was
+      // killed at 300s having emitted five of its ten retries, reporting only
+      // "spawnSync bash ETIMEDOUT" — which names neither the cap, the elapsed
+      // time, nor the module.
+      const timeoutMs = (manifest.build.timeout_seconds ?? 300) * 1000;
+      const startedAt = Date.now();
       try {
         if (manifest.build.command) {
           execFileSync('bash', ['-c', manifest.build.command], {
             cwd: buildDir,
             stdio: 'inherit',
-            timeout: 300_000,
+            timeout: timeoutMs,
             env: buildEnv,
           });
         } else {
@@ -362,12 +369,19 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
           execFileSync(cmd, [script], {
             cwd: buildDir,
             stdio: 'inherit',
-            timeout: 300_000,
+            timeout: timeoutMs,
             env: buildEnv,
           });
         }
       } catch (buildError) {
         const msg = buildError instanceof Error ? buildError.message : String(buildError);
+        if (msg.includes('ETIMEDOUT')) {
+          const elapsed = Math.round((Date.now() - startedAt) / 1000);
+          return {
+            success: false,
+            error: `Auto-build failed: ${moduleId}'s build exceeded its ${timeoutMs / 1000}s timeout (killed after ${elapsed}s). Raise build.timeout_seconds in manifest.yml if the build legitimately needs longer, or shrink what it fetches.`,
+          };
+        }
         return { success: false, error: `Auto-build failed: Build exited with code ${msg}` };
       }
 

package/src/policy/capability-shape-baseline.ts

@@ -155,4 +155,10 @@ export const CAPABILITY_SHAPE_BASELINE: Readonly<Record<string, CapabilityShape>
     requests:
       '[{kind:"interface",members:[{name:"all",optional:false,type:"Promise<PrivateWebRoute[]>"},{name:"replaceAll",optional:false,type:"Promise<void>"}],name:"PrivateRouteView"},{kind:"interface",members:[{name:"hostname",optional:false,type:"string"},{name:"module_id",optional:false,type:"string"},{name:"path",optional:false,type:"string"},{name:"slug",optional:false,type:"string"},{name:"target_host",optional:true,type:"string"},{name:"target_port",optional:true,type:"number"},{name:"type",optional:false,type:"\'static\' | \'reverse_proxy\'"},{name:"websocket",optional:true,type:"boolean"}],name:"PrivateWebRoute"}]',
   },
+  orchestrator_state: {
+    version: '1.0.0',
+    hash: '5127c0aa524cdd03bbcfa080a220307dfe6742143d76f3a50d7fa4870519b0c4',
+    requests:
+      '[{kind:"interface",members:[{name:"key",optional:false,type:"string"}],name:"GetSystemConfigRequest"},{kind:"interface",members:[{name:"value",optional:false,type:"string | null"}],name:"GetSystemConfigResult"},{kind:"alias",members:[{name:"_self",optional:false,type:"Record<string, never>"}],name:"ListMachinesRequest"},{kind:"interface",members:[{name:"machines",optional:false,type:"MachineSnapshot[]"}],name:"ListMachinesResult"},{kind:"interface",members:[{name:"arch",optional:true,type:"string"},{name:"cpu_cores",optional:false,type:"number"},{name:"disk_gb",optional:false,type:"number"},{name:"memory_mb",optional:false,type:"number"}],name:"MachineHardwareSnapshot"},{kind:"interface",members:[{name:"ip_address",optional:false,type:"string"},{name:"name",optional:false,type:"string"},{name:"zone",optional:false,type:"string"}],name:"MachineInterfaceSnapshot"},{kind:"interface",members:[{name:"earmarked_module",optional:false,type:"string | null"},{name:"hardware",optional:false,type:"MachineHardwareSnapshot"},{name:"hostname",optional:false,type:"string"},{name:"id",optional:false,type:"string"},{name:"interfaces",optional:false,type:"MachineInterfaceSnapshot[]"},{name:"ip_address",optional:false,type:"string"},{name:"role",optional:false,type:"\'host\' | \'router\'"},{name:"ssh_user",optional:false,type:"string"},{name:"zone",optional:false,type:"string"}],name:"MachineSnapshot"},{kind:"interface",members:[{name:"get_system_config",optional:false,type:"Promise<GetSystemConfigResult>"},{name:"list_machines",optional:true,type:"Promise<ListMachinesResult>"}],name:"OrchestratorStateCapability"}]',
+  },
 };

package/src/policy/module-business-baseline.ts

@@ -261,6 +261,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
+  {
+    file: 'apps/celilo/src/manifest/validate.ts',
+    capability: 'orchestrator_state',
+    count: 1,
+    why: "PERMANENT — orchestrator_state is framework-granted, not module-provided: its verbs read celilo's own tables, so celilo builds the method table and no module can (module-orchestrator-primitives)",
+  },
   {
     file: 'apps/celilo/src/manifest/validate.ts',
     capability: 'cross_module_read',
@@ -273,6 +279,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'PERMANENT — framework-granted, so celilo satisfies it and no module provides it; the resolver has to be told that by name (web-ui-console D7b)',
   },
+  {
+    file: 'apps/celilo/src/hooks/capability-loader.ts',
+    capability: 'orchestrator_state',
+    count: 5,
+    why: "PERMANENT — orchestrator_state is framework-granted, not module-provided: its verbs read celilo's own tables, so celilo builds the method table and no module can (module-orchestrator-primitives)",
+  },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'control_plane_api',
@@ -375,6 +387,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'PERMANENT — X10, a contract declaration with no implementation; this is the package doing its job',
   },
+  {
+    file: 'packages/capabilities/src/capability-contract.ts',
+    capability: 'orchestrator_state',
+    count: 1,
+    why: 'PERMANENT — X10, a contract declaration with no implementation; this is the package doing its job',
+  },
   {
     file: 'packages/capabilities/src/capability-contract.ts',
     capability: 'cross_module_read',
@@ -507,6 +525,11 @@ export const SERVICE_FILENAME_BASELINE: readonly ServiceFilenameRow[] = [
     capability: 'cross_module_read',
     why: 'PERMANENT — cross_module_read is a framework privilege, not a module capability',
   },
+  {
+    file: 'apps/celilo/src/services/orchestrator-state.ts',
+    capability: 'orchestrator_state',
+    why: "PERMANENT — orchestrator_state is framework-granted, not module-provided: its verbs read celilo's own tables, so celilo builds the method table and no module can (module-orchestrator-primitives)",
+  },
   {
     file: 'apps/celilo/src/services/provider-converge.ts',
     capability: 'provider_converge',

package/src/registry/client.test.ts

@@ -513,10 +513,11 @@ describe('RegistryClient.download integrity', () => {
   });
 
   test('a non-digest cksum sentinel skips verification instead of failing', async () => {
-    // The registry's bootstrap path publishes `cksum: 'bootstrap'`
-    // (packages/registry-server/src/bootstrap.ts:114) because those modules are
-    // packaged on demand and have no stable digest. Treating a sentinel as a
-    // digest rejects a perfectly good 2.7MB package on every import.
+    // `bootstrap` is the sentinel an index entry carries when it has no
+    // integrity data at all. The registry's bootstrap path no longer emits it
+    // — it hashes the .netapp it packages (celilo#1262) — but the sentinel
+    // branch stays, because treating one as a digest would reject a perfectly
+    // good 2.7MB package on every import.
     fetchSpy.mockImplementation(() => new Response(body, { status: 200 }));
 
     const client = new RegistryClient('https://reg.example.com');

package/src/services/infrastructure-selector.test.ts

@@ -272,6 +272,52 @@ describe('infrastructure-selector', () => {
     });
   });
 
+  describe('the no-infrastructure error names what IS configured', () => {
+    it("names the service and the zones it covers when none covers the module's zone", async () => {
+      const db = createDbClient({ path: testDbPath });
+      await db.insert(modules).values({
+        id: 'needs-dmz',
+        name: 'Needs DMZ',
+        version: '1.0.0',
+        manifestData: {
+          requires: { system: { cpu: 1, memory: 512, disk: 5, zone: 'dmz' } },
+        },
+        sourcePath: '/test',
+        state: 'CONFIGURED',
+      });
+      const module = (await db.select().from(modules).limit(1))[0] as Module;
+
+      // A service exists — it just does not list 'dmz'. This is the case the
+      // old message described as having no service at all.
+      const service = await addContainerService({
+        name: 'Proxmox E2E',
+        providerName: 'proxmox',
+        zones: ['app', 'secure-mgmt'],
+        providerConfig: {},
+        apiCredentials: { api_url: 'https://test' },
+      });
+      const { updateVerificationStatus } = await import('./container-service');
+      await updateVerificationStatus(service.id, { success: true, message: 'ok' });
+
+      let message = '';
+      try {
+        await selectInfrastructure(module);
+        throw new Error('expected selectInfrastructure to throw');
+      } catch (err) {
+        expect(err).toBeInstanceOf(InfrastructureError);
+        message = (err as Error).message;
+      }
+
+      expect(message).toContain("zone 'dmz'");
+      expect(message).toContain('Proxmox E2E');
+      expect(message).toContain("'app'");
+      expect(message).toContain("'secure-mgmt'");
+      // The misleading half: do not tell the operator to configure a service
+      // they already have.
+      expect(message).not.toContain('celilo service add');
+    });
+  });
+
   describe('hardware validation', () => {
     it('rejects machine with insufficient CPU', async () => {
       const db = createDbClient({ path: testDbPath });

package/src/services/infrastructure-selector.ts

@@ -1,6 +1,7 @@
 import type { Module } from '../db/schema';
 import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import type {
+  ContainerService,
   InfrastructureSelection,
   Machine,
   MachineRole,
@@ -79,9 +80,30 @@ interface RejectionReason {
 /**
  * Build a detailed error message explaining why no infrastructure was selected
  */
-function buildInfrastructureErrorMessage(zone: string, rejections: RejectionReason[]): string {
+function buildInfrastructureErrorMessage(
+  zone: string,
+  rejections: RejectionReason[],
+  allServices: ContainerService[],
+): string {
   if (rejections.length === 0) {
-    return `No infrastructure available for zone '${zone}'. Configure a container service with 'celilo service add' or add a machine with 'celilo machine add'.`;
+    // Naming the services that DO exist is the whole value of this branch.
+    // "Configure a container service" is actively misleading when one is
+    // already configured and simply does not list this zone — it sends the
+    // reader to `machine add`, which is the wrong fix and, in an e2e fixture,
+    // a forbidden one (a machine-pool deploy never renders `main.tf.tpl`,
+    // celilo#879). Measured 2026-09-25: a suite whose Proxmox service covered
+    // `app` and `secure-mgmt` failed to place caddy in `dmz`, and this
+    // sentence described the situation as having no service at all.
+    const covering = allServices
+      .map(
+        (svc) =>
+          `'${svc.name}' covers ${svc.zones.length > 0 ? svc.zones.map((z) => `'${z}'`).join(', ') : 'no zones'}`,
+      )
+      .join('; ');
+    const have = covering
+      ? ` Configured container services do not cover it: ${covering}. Add '${zone}' to one with 'celilo service reconfigure', or add a machine with 'celilo machine add'.`
+      : ` Configure a container service with 'celilo service add' or add a machine with 'celilo machine add'.`;
+    return `No infrastructure available for zone '${zone}'.${have}`;
   }
 
   const details = rejections
@@ -246,5 +268,7 @@ export async function selectInfrastructure(module: Module): Promise<Infrastructu
   }
 
   // 3. No infrastructure available
-  throw new InfrastructureError(buildInfrastructureErrorMessage(zone, rejections));
+  throw new InfrastructureError(
+    buildInfrastructureErrorMessage(zone, rejections, await listContainerServices()),
+  );
 }

package/src/services/orchestrator-state.test.ts

@@ -0,0 +1,211 @@
+/**
+ * `orchestrator_state` — the framework-built method table.
+ *
+ * INV-1 (module-orchestrator-primitives design.md) is what these tests exist to
+ * pin: the module a verb acts on is a CONSTRUCTION argument, never a field in
+ * the request. The jail cannot be trusted to name itself honestly, so a request
+ * that arrives carrying a module field is refused even though the contract type
+ * has no such field — the broker hands the implementation whatever JSON the
+ * hook process sent, and the runtime check is the only thing standing between a
+ * hook and a neighbour's data once the shape has crossed the process boundary.
+ *
+ * The refusal message names the calling module, which is also how the closure
+ * itself is observable: two instances built for different modules read the same
+ * table but each names its OWN module when it refuses.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import type { DbClient } from '../db/client';
+import { machines, systemConfig } from '../db/schema';
+import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
+import { buildOrchestratorState } from './orchestrator-state';
+
+const VPN_SUBNET_KEY = 'network.control-plane-vpn.subnet';
+
+/**
+ * Pull the privileged verb off the table with a guard that fails clearly.
+ * The method is optional on the contract (the allow-list decides), so a test
+ * that calls it unguarded reads as possibly-undefined rather than as the
+ * assertion it is: these tests granted the verb, and its absence is what the
+ * test should report.
+ */
+function requireListMachines(state: ReturnType<typeof buildOrchestratorState>) {
+  const { list_machines } = state;
+  if (!list_machines) {
+    throw new Error('list_machines was not injected; the verbs argument did not grant it');
+  }
+  return list_machines;
+}
+
+describe('buildOrchestratorState', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  test('reads the value of a set system-config key', async () => {
+    db.insert(systemConfig).values({ key: VPN_SUBNET_KEY, value: '10.255.255.0/24' }).run();
+    const state = buildOrchestratorState('wireguard', db);
+
+    await expect(state.get_system_config({ key: VPN_SUBNET_KEY })).resolves.toEqual({
+      value: '10.255.255.0/24',
+    });
+  });
+
+  test('an unset key is value null, not an error', async () => {
+    // The case the replaced CLI call mangled: `celilo system config get`
+    // exits non-zero for an unset key, so the caller had to catch the spawn
+    // failure AND parse stdout. Here the normal absence is a typed result.
+    const state = buildOrchestratorState('wireguard', db);
+
+    await expect(state.get_system_config({ key: 'no.such.key' })).resolves.toEqual({
+      value: null,
+    });
+  });
+
+  test('a request carrying a module field is refused (INV-1)', async () => {
+    // The contract type has no `module` field, so this only arrives as a
+    // smuggled extra property across the broker. Refused, not ignored: an
+    // ignored field means a hook testing the water learns nothing.
+    const state = buildOrchestratorState('wireguard', db);
+    const smuggled = { key: VPN_SUBNET_KEY, module: 'celilo-mgmt' } as never;
+
+    await expect(state.get_system_config(smuggled)).rejects.toThrow(/module/);
+  });
+
+  test('the refusal names the module the table was built for (the closure, observed)', async () => {
+    // Two instances over the same db, built for different modules. The reads
+    // are identical; the refusals are not, and the difference is the proof
+    // that each instance closed over its own module id.
+    const wireguard = buildOrchestratorState('wireguard', db);
+    const impostor = buildOrchestratorState('celilo-mgmt', db);
+
+    const smuggled = { key: 'k', module: 'someone-else' } as never;
+    await expect(wireguard.get_system_config(smuggled)).rejects.toThrow(/'wireguard'/);
+    await expect(impostor.get_system_config(smuggled)).rejects.toThrow(/'celilo-mgmt'/);
+  });
+
+  test('a request carrying any unexpected field is refused, not just module-named ones', async () => {
+    // The general shape of INV-1: the request is exactly the contract, and
+    // anything extra is a jail trying to widen the surface. Refusing on the
+    // general rule covers the next smuggled field nobody thought to name.
+    const state = buildOrchestratorState('wireguard', db);
+    const widened = { key: 'k', value: '10.0.0.0/8' } as never;
+
+    await expect(state.get_system_config(widened)).rejects.toThrow(/value/);
+  });
+});
+
+describe('buildOrchestratorState list_machines', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  function insertMachine(overrides: Partial<typeof machines.$inferInsert> = {}): void {
+    db.insert(machines)
+      .values({
+        id: 'm-1',
+        hostname: 'pibox-1',
+        zone: 'dmz',
+        ipAddress: '10.0.20.11',
+        sshUser: 'peba',
+        sshKeyEncrypted: 'enc:never-read-back',
+        hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 64 },
+        role: 'host',
+        interfaces: [{ name: 'eth0', ipAddress: '10.0.20.11', zone: 'dmz' }],
+        ...overrides,
+      })
+      .run();
+  }
+
+  test('an allowed module gets the pool, as the snapshot type carries it', async () => {
+    // The list_machines allow-list (design INV-2) is the loader's decision;
+    // the builder takes the allowed verbs as an argument so the service tests
+    // can pin the closure without importing the trust map.
+    insertMachine({ earmarkedModule: null });
+    insertMachine({
+      id: 'm-2',
+      hostname: 'gw-1',
+      role: 'router',
+      earmarkedModule: 'celilo-mgmt',
+    });
+    const state = buildOrchestratorState('celilo-mgmt', db, ['list_machines']);
+
+    const { machines: pool } = await requireListMachines(state)({});
+    expect(pool).toEqual([
+      {
+        id: 'm-1',
+        hostname: 'pibox-1',
+        zone: 'dmz',
+        ip_address: '10.0.20.11',
+        ssh_user: 'peba',
+        role: 'host',
+        interfaces: [{ name: 'eth0', ip_address: '10.0.20.11', zone: 'dmz' }],
+        hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 64 },
+        earmarked_module: null,
+      },
+      {
+        id: 'm-2',
+        hostname: 'gw-1',
+        zone: 'dmz',
+        ip_address: '10.0.20.11',
+        ssh_user: 'peba',
+        role: 'router',
+        interfaces: [{ name: 'eth0', ip_address: '10.0.20.11', zone: 'dmz' }],
+        hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 64 },
+        earmarked_module: 'celilo-mgmt',
+      },
+    ]);
+  });
+
+  test('an empty pool is an empty list, not an error', async () => {
+    // A fresh management box has no machines yet. The backup writes an empty
+    // inventory because the pool IS empty — a real result, not the swallow
+    // the replaced CLI spawn produced.
+    const state = buildOrchestratorState('celilo-mgmt', db, ['list_machines']);
+
+    const { machines: pool } = await requireListMachines(state)({});
+    expect(pool).toEqual([]);
+  });
+
+  test('the encrypted key column never reaches the snapshot', async () => {
+    // The one column the snapshot must not carry. Asserting on the VALUE (not
+    // just the type) because a pass-through of the row would ship the secret
+    // inside a correctly-shaped envelope.
+    insertMachine();
+    const state = buildOrchestratorState('celilo-mgmt', db, ['list_machines']);
+
+    const { machines: pool } = await requireListMachines(state)({});
+    expect(JSON.stringify(pool)).not.toContain('enc:never-read-back');
+  });
+
+  test('a request carrying any field is refused (INV-1)', async () => {
+    // The list_machines contract is empty, so ANY field is a smuggled
+    // widening — including the module id the jail cannot be trusted to name.
+    const state = buildOrchestratorState('celilo-mgmt', db, ['list_machines']);
+    const smuggled = { module: 'wireguard' } as never;
+
+    await expect(requireListMachines(state)(smuggled)).rejects.toThrow(/module/);
+  });
+
+  test('a table built without the verb allowed does not carry it', async () => {
+    // Deny by default (Rule 6.4): the loader passes the allow-list decision,
+    // and a builder that defaulted to generous would hand the pool to any
+    // module declaring orchestrator_state for the config reads.
+    insertMachine();
+    const state = buildOrchestratorState('wireguard', db);
+
+    expect((state as unknown as Record<string, unknown>).list_machines).toBeUndefined();
+  });
+});

package/src/services/orchestrator-state.ts

@@ -0,0 +1,122 @@
+/**
+ * The `orchestrator_state` method table celilo builds for one consuming module.
+ *
+ * Framework-granted like `control_plane_api` (`api-principal-enrolment.ts`,
+ * whose shape this copies): the verbs answer questions about celilo's own
+ * tables, so no module script can implement them, and a module script may
+ * import nothing but `@celilo/capabilities`. celilo builds the table for the
+ * calling module and `capability-loader.ts` injects it when the manifest
+ * declares the capability — the `requires` line is the authorization.
+ *
+ * ## INV-1: the module is a construction argument, never a request field
+ *
+ * `buildOrchestratorState(moduleId)` closes over the module id, exactly as
+ * `buildControlPlaneApi` does. A request that arrives carrying any field the
+ * contract does not declare is REFUSED, not ignored: the broker hands this
+ * table whatever JSON the hook process sent, the contract type has no way to
+ * reject extra properties at compile time, and an ignored field would let a
+ * jail probe the surface while learning nothing. The refusal message names the
+ * calling module, so the log shows who tried to widen what.
+ *
+ * ## Reads through the existing store
+ *
+ * Both verbs read the tables the CLI reads, through drizzle, with the same
+ * injectable `db` (defaulting to the process-wide `getDb()`) so the INV-1
+ * tests can pin the closure against an isolated database instead of the
+ * operator's real fleet. `get_system_config` reads `system_config`;
+ * `list_machines` reads `machines` — the same rows `celilo machine list`
+ * renders, minus the encrypted key column, which no snapshot carries (the
+ * fleet keypair is staged into the backup envelope by the framework).
+ *
+ * `list_machines` is a PRIVILEGED verb: handing out the pool is a per-module
+ * trust decision (design INV-2), so the loader passes the verbs the calling
+ * module is allow-listed for and the table omits the rest. Deny by default:
+ * a builder that defaulted to generous would hand the pool to every module
+ * declaring `orchestrator_state` for its config reads.
+ */
+
+import type { OrchestratorStateCapability } from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
+import { type DbClient, getDb } from '../db/client';
+import { machines, systemConfig } from '../db/schema';
+
+/**
+ * The fields `get_system_config`'s contract declares, and therefore the only
+ * fields a request may carry. Anything else is a smuggled widening and is
+ * refused with the offending field named.
+ */
+const GET_SYSTEM_CONFIG_FIELDS = ['key'] as const;
+
+/**
+ * Refuse a request carrying any field the contract does not declare.
+ *
+ * INV-1's runtime half. `as never` call sites are expected: a hook process
+ * sends JSON, and JSON has no compile-time shape once it crosses the broker.
+ */
+function requireExactRequest(
+  moduleId: string,
+  verb: string,
+  request: object,
+  allowedFields: readonly string[],
+): void {
+  const unexpected = Object.keys(request).filter((field) => !allowedFields.includes(field));
+  if (unexpected.length === 0) return;
+  throw new Error(
+    `Module '${moduleId}' called orchestrator_state.${verb} with unexpected field(s): ${unexpected.join(', ')}. The calling module is a construction argument of this capability, never a request field; allowed fields for ${verb}: ${allowedFields.join(', ')}.`,
+  );
+}
+
+/**
+ * Build the `orchestrator_state` table for one module.
+ *
+ * `db` is injectable for tests; production callers (the capability loader)
+ * let it default to the process-wide client, the same way the enrolment
+ * service resolves its store.
+ *
+ * `allowPrivilegedVerbs` names the privileged verbs the calling module may
+ * hold, as computed by the loader from the allow-list in
+ * `manifest/validate.ts`. It defaults to empty (deny by default): a module
+ * declaring `orchestrator_state` gets `get_system_config` and nothing else
+ * unless the trust map names it.
+ */
+export function buildOrchestratorState(
+  moduleId: string,
+  db: DbClient = getDb(),
+  allowPrivilegedVerbs: readonly string[] = [],
+): OrchestratorStateCapability {
+  const table: OrchestratorStateCapability = {
+    async get_system_config(request) {
+      requireExactRequest(moduleId, 'get_system_config', request, GET_SYSTEM_CONFIG_FIELDS);
+      const row = db.select().from(systemConfig).where(eq(systemConfig.key, request.key)).get();
+      return { value: row?.value ?? null };
+    },
+  };
+
+  if (allowPrivilegedVerbs.includes('list_machines')) {
+    table.list_machines = async (request) => {
+      // The contract is empty, so the allowed-field set is empty and any
+      // field at all — including a module id — is a smuggled widening.
+      requireExactRequest(moduleId, 'list_machines', request, []);
+      const rows = db.select().from(machines).all();
+      return {
+        machines: rows.map((row) => ({
+          id: row.id,
+          hostname: row.hostname,
+          zone: row.zone,
+          ip_address: row.ipAddress,
+          ssh_user: row.sshUser,
+          role: row.role,
+          interfaces: row.interfaces.map((iface) => ({
+            name: iface.name,
+            ip_address: iface.ipAddress,
+            zone: iface.zone,
+          })),
+          hardware: row.hardware,
+          earmarked_module: row.earmarkedModule ?? null,
+        })),
+      };
+    };
+  }
+
+  return table;
+}