@celilo/cli 1.13.0 → 1.14.0

package/CELILO_CORE_MODULES.md

@@ -59,7 +59,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 - **celilo-apt-repo** — Debian apt repository (reprepro + Bun HTTP server) serving the celilo `.deb` at apt.celilo.computer. **provides:** `apt_publish`. **requires:** `public_web`, `dns_registrar`.
 - **signal** — bidirectional Signal transport for alerts and deploy-interview questions; runs signal-cli in daemon mode with its JSON-RPC socket bound to the host's own address (never public) and **`--receive-mode=manual`**, which is load-bearing: signal-cli's default (`on-start`) leaves the daemon permanently receiving, so it drains every reply into an SSE stream nothing is attached to and REFUSES celilo's `receive` call — replies arrive and are unreadable, while `send` and every health check keep passing. Enrolled as a SECONDARY DEVICE of an existing Signal account rather than registering its own number — Signal blocks most VOIP ranges and bans bot-ish registrations. Recipient addresses live on celilo routes, not in module config, so adding a person never requires a redeploy. Runs on x86_64 and aarch64. `libsignal-client` ships no linux-aarch64 native, so celilo builds one (`modules/signal/build/`) and installs it as a `libsignal-jni` .deb on ARM hosts; x86_64 uses the JAR's bundled native. **provides:** `notification` (`send`, `receive`). **requires:** no capabilities — a transport that depended on the proxy, registrar or firewall could not tell you those were broken — and a system in the **`secure-mgmt`** zone: it holds a linked Signal account (the operator's own messaging identity and keys), and its job is to observe every tier while depending on none, which is what the control-plane zone is for. See `openspec/changes/add-alerting/`.
 - **celilo-website** — public docs site (static Astro) served via Caddy on celilo.computer. **requires:** `public_web`, `dns_registrar`.
-- **celilo-web-console** — the read-mostly operator console: the fleet drawn by zone, a live module roster, and the alert and backup state that says what needs attention. **Not yet deployed** — the manifest, the SPA, the console server and the read verbs exist; the `control_plane_api` enrolment and the e2e suite do not. It holds **no database handle**: every fact it displays arrives over the SSH remote API as a principal whose grants derive from the `COMMANDS` registry's read-only classifier, because an in-process console would hold the whole database including the encrypted secret store and be constrained only by its own code. **⚠️ `secure-mgmt`, and the placement is a security boundary rather than a preference:** celilo reaches into every data-plane zone by trust and no data-plane zone reaches back, so the ONLY client path in is the control-plane VPN. It registers no web route, requests no port forward, takes no `natIp` or ingress address, and gets no DNS record resolvable from a data-plane zone. `apps/celilo/src/console/control-plane-boundary.test.ts` asserts that on every pull request rather than only in e2e, because the way it erodes is a one-line manifest edit adding `private_web` so someone can reach it without bringing up the VPN. It offers no deploy, uninstall, pause, restore or config control: those can raise an interview question, a browser has no responder, and they are ABSENT rather than disabled. **provides:** nothing. **requires:** `idp`, `control_plane_api`. See `openspec/changes/web-ui-console/`.
+- **celilo-web-console** — the read-mostly operator console: the fleet drawn by zone, a live module roster, and the alert and backup state that says what needs attention. **Not yet deployed** — the manifest, the SPA, the console server, the read verbs and the `control_plane_api` capability exist; the `on_install` that enrols the principal, and the e2e suite, do not. It holds **no database handle**: every fact it displays arrives over the SSH remote API as a principal whose grants derive from the `COMMANDS` registry's read-only classifier, because an in-process console would hold the whole database including the encrypted secret store and be constrained only by its own code. **⚠️ `secure-mgmt`, and the placement is a security boundary rather than a preference:** celilo reaches into every data-plane zone by trust and no data-plane zone reaches back, so the ONLY client path in is the control-plane VPN. It registers no web route, requests no port forward, takes no `natIp` or ingress address, and gets no DNS record resolvable from a data-plane zone. `apps/celilo/src/console/control-plane-boundary.test.ts` asserts that on every pull request rather than only in e2e, because the way it erodes is a one-line manifest edit adding `private_web` so someone can reach it without bringing up the VPN. It offers no deploy, uninstall, pause, restore or config control: those can raise an interview question, a browser has no responder, and they are ABSENT rather than disabled. **provides:** nothing. **requires:** `idp`, `control_plane_api`. See `openspec/changes/web-ui-console/`.
 - **celilo-canary** — a deliberately minimal nginx serving one static page in **`dmz`**, permanently deployed, whose health check IS the assertion that the deploy path still works. Nothing about it is interesting except that it is *always there*: modules already deployed keep running when the pipeline breaks, so without a canary a regression in IPAM allocation, Terraform provisioning, Ansible convergence or capability wiring stays invisible until the next real deploy — which is exactly when nobody wants to discover it. One deploy exercises all four, plus a live cross-module capability call. **Fleet-only, and the absence is the design**: it registers one route through `private_web` and requires nothing that reaches the perimeter, so there is no public record, no ACME certificate and no port forward. Its `health_check` probes nginx over systemd and its `/healthz` endpoint with **`probeHttp`, from the management server** rather than by SSHing in and running `curl` — the production `ubuntu-22.04-standard` LXC ships no curl, so the old form could not tell a missing binary from a dead service, and reaching the canary at its own address additionally catches a service bound only to loopback. **requires:** `private_web`.
 
 ## Git forge & CI pipeline

package/CELILO_SUBSYSTEMS.md

@@ -290,6 +290,8 @@ SUGGESTS a `backup.schedule`; the operator's override decides; celilo runs it on
 the resolved cadence and alerts when it stops.
 
 - **Creation** — `apps/celilo/src/services/backup-create.ts` — `createModuleBackup` (invokes the module's `on_backup` hook into an encrypted envelope), `createSystemStateBackup` (celilo.db), `findBackupEligibleModules` (returns each module's operator config alongside its manifest, because every caller has to resolve a policy out of the two together), `isBackupDue`. Storage destinations: `backup-storage.ts`. Restore: `backup-restore.ts`.
+- **Staging celilo's own state** — `apps/celilo/src/services/system-state-stage.ts` — `stageSystemState(rootDir)` and `snapshotDatabase(src, dest)`. Before invoking `on_backup` on a `cross_module_read` module, celilo COPIES its own state (`celilo.db` snapshot, `master.key`, the fleet `ssh/`, and `module_src/<id>/` for every module's lean source) into a directory it creates, and passes the path as the contract input `system_state_root`. ⚠️ **This is what lets celilo back ITSELF up without exempting celilo-mgmt from the hook jail** (`openspec/changes/hook-process-boundary`, design D9b): the hook never READ those bytes, it copied them into `backup_dir`, so the framework does the copying and celilo's data directory is in no hook's mount set. Same allow-list as `cross_module_root` — one privilege, one list to audit. ⚠️ **`snapshotDatabase` uses a readonly connection + `serialize()`, never `copyFileSync`**: celilo runs the DB in WAL mode, so the main file is routinely one near-empty page while all the real data sits in `celilo.db-wal` (measured: 4 KB main against 832 KB WAL), and a plain copy produces a snapshot that opens cleanly, contains NOTHING, and is installed by restore. Gate: `services/system-state-stage.test.ts` writes 200 uncheckpointed rows and asserts they survive.
+- **The fleet SSH key (one accessor)** — `apps/celilo/src/services/fleet-key.ts` — `ensureFleetKey()` (idempotent mint, returns the public half) and `getFleetSshDir()`. Surfaced as `celilo system ensure-fleet-key`, which also records `ssh.public_key`. celilo-mgmt's `on_install` used to mint the keypair itself inside celilo's data directory — a WRITE into the one directory the jail exists to keep out of the mount set (design D9b), which staging does not cover because staging covers copies OUT. ⚠️ **Never re-key**: an existing key is reused, because regenerating strands every machine whose `authorized_keys` holds the old public half, and a redeploy calls this every time. `getFleetSshDir()` follows the DB (`dirname(getDbPath())/.ssh`), not `getDataDir()` — the same directory on a deb install and different when `CELILO_DB_PATH` is overridden; both the mint and `restore-from-file.ts`'s laydown read that one helper so they cannot drift apart.
 - **Cadence (one accessor)** — `apps/celilo/src/services/backup-schedule.ts` — `effectiveBackupSchedule(manifest, override)`. The manifest SUGGESTS; the operator's `backup_schedule` row in `module_configs` decides; absent from both means `daily`, NOT `manual` (opting out takes an explicit `manual`). Resolution happens at READ time — nothing is materialised at install or deploy — so a corrected manifest reaches every install that has not overridden. The one-argument form was DELETED rather than kept as an overload (Rule 3.9): it would let an un-updated reader compile clean while silently ignoring overrides. Both the freshness audit and the backup sweep must read cadence through this one function, or a module can be alerted-on but never backed up.
 - **The cadence type** — `apps/celilo/src/services/cadence.ts` — `Cadence` (`{minutes}` | `'manual'`), `parseCadence` / `formatCadence` / `cadenceMs`, and `cadenceSchema({floorMinutes})`. One spelling set for every cadence in celilo: a named period (`hourly`/`daily`/`weekly`/`monthly`), a duration (`6h`, `90m`, `3d`), or `manual`. ⚠️ **The floors are DERIVED from the sweep ticks, never written down**: this file owns `BACKUP_SWEEP_PATTERN` / `ALERTING_SWEEP_PATTERN` and computes `BACKUP_CADENCE_FLOOR_MINUTES` / `MONITOR_INTERVAL_FLOOR_MINUTES` from them (the sweeps import their pattern from here), so changing a tick moves what it can serve in the same edit. A cadence finer than its sweep's tick is REFUSED, not coerced — accepting it leaves the operator believing they configured something that can silently never happen.
 - **Retention (one accessor)** — `apps/celilo/src/services/backup-retention.ts` — `effectiveBackupRetention(manifest, configs)`, `prunesNothing`, `identifyExpiredBackups`, `pruneBackupsForModule`. Two INDEPENDENT dimensions (copies, age), each resolved override → manifest → **unbounded**. ⚠️ **An unset dimension is unbounded, never a default bound.** `backup.retention` is an optional block, so a manifest omitting it prunes nothing at all and its inner `count: 7` / `max_age_days: 30` defaults never apply; if setting one dimension let the other fall back to those, an operator asking to keep 3 copies would silently arm a 30-day deletion on a module that had been keeping everything. Unbounded is `Infinity`, which `identifyExpiredBackups` needs no special case for. Gate: `services/backup-retention.test.ts`. The four sites that used to read `manifest.backup.retention` directly (`cli/commands/backup-sweep.ts`, `backup-create.ts`, `backup-prune.ts` twice) all go through the accessor — that duplication is what let the schedule readers drift.
@@ -346,6 +348,7 @@ Run any celilo command on celilo-mgr over SSH instead of screen-scraping `ssh <h
 - **Server** — `apps/celilo/src/api/serve.ts` (`apiServeMode`); the `celilo api-serve --principal=<id>` sshd forced-command entry point (dispatched in `apps/celilo/src/cli/index.ts`). Authorizes per principal, runs the command as a protocol-mode child, streams output, audits to stderr.
 - **Client** — `packages/core/src/remote-client.ts` (`@celilo/core`) — `resolveRemote` (`--remote <dest>` / `CELILO_REMOTE`), `runRemoteClient` (`ssh -T`, renders progress via the local ProgressDisplay, answers interviews via the `@celilo/cli-display` prompts). Refuses to prompt on a non-TTY stdin, replying `unanswerable` rather than submitting a default as if a human had chosen it.
 - **Access control** — `apps/celilo/src/services/api-access.ts` — `grantPrincipal`, `isAuthorized` (deny-by-default, `command:subcommand` grants), `renderAuthorizedKeys`. Table: `api_principals` (`apps/celilo/src/db/schema.ts`). CLI: `apps/celilo/src/cli/commands/api.ts` (`api grant|list|revoke|authorized-keys|key new`).
+- **Principal enrolment for a module (`control_plane_api`)** — `apps/celilo/src/services/api-principal-enrolment.ts` — `enrolControlPlanePrincipal`, `revokeControlPlanePrincipal`, and `buildControlPlaneApi`, the method table a consuming module's hooks receive. The consumer generates an ed25519 pair on its own system and presents the public half; nothing here accepts a private key. Grants are DERIVED from `readOnlyGrants(COMMANDS)` and are not a parameter, so a caller cannot ask for more, and a write verb is never granted however it is named. **Framework-granted, so no module provides it** — enrolment writes celilo's own `api_principals` row and a module script may import nothing but `@celilo/capabilities`, which rules out celilo-mgmt as much as anyone else (`web-ui-console` D7b). Injected by `capability-loader.ts` ONLY for a module whose stored manifest declares it under `requires`/`optional`, unlike every other capability the loader hands out, and scoped to that module: a caller may not name a neighbour's principal. Contract: `packages/capabilities/src/control-plane-api.ts`.
 - **Mid-run interview bridge (`kind:daemon` responder)** — `apps/celilo/src/services/remote-responder.ts` — `startRemoteResponder` bridges bus `interview.required.*` ↔ wire.
 - **Server provisioning** — the `celilo-bootstrap` deb (`packaging/celilo-bootstrap/scripts/postinst`) creates the non-root `celilo-api` landing account + sshd; membership in the `celilo` group + `/etc/sudoers.d/celilo` (`!use_pty`) gives api-serve DB access via the wrapper's sudo-drop.
 - **Self-upgrade (apt)** — `celilo apt-upgrade` (`apps/celilo/src/cli/commands/apt-upgrade.ts`) upgrades the deb-installed `celilo`/`celilo-bootstrap` packages (`apt-get update` → `--only-upgrade install`) then spawns a fresh `celilo system migrate` (ISS-0100), then `celilo events restart-daemon` so the dispatcher actually runs the code just installed — a failure there fails the whole command and names which steps DID complete, because "upgraded" while the dispatcher serves stale code is the silent state celilo#604 documents. It's the RW target behind the MCP's registry-derived `celilo_apt_upgrade` tool; the celilo user's two apt invocations are scoped-sudo'd by `/etc/sudoers.d/celilo-apt-upgrade`, shipped by `celilo-bootstrap`. **This upgrades celilo ITSELF — not the modules it manages. For those, see Module auto-upgrade below; the two are routinely confused.**
@@ -354,14 +357,15 @@ Run any celilo command on celilo-mgr over SSH instead of screen-scraping `ssh <h
 
 ## Web console (read-mostly operator UI)
 
-The fleet drawn by zone, a live module roster, and the alert and backup state that says what needs attention. Design: `openspec/changes/web-ui-console/`. **Not yet deployed** — the SPA, its server and the console read verbs exist; the module, its `control_plane_api` enrolment and the e2e suite do not.
+The fleet drawn by zone, a live module roster, and the alert and backup state that says what needs attention. Design: `openspec/changes/web-ui-console/`. **Not yet deployed** — the SPA, its server, the console read verbs, the acknowledgement path and the `control_plane_api` capability exist; the module's `on_install` that CALLS that capability, and the e2e suite, do not. The capability issues only the derived read-only grants and has no parameter that could widen them (task 6.3b settled that deliberately), so acknowledgement renders a denial until an operator grants `alerts:ack` by hand.
 
 - **Console read verbs** — `apps/celilo/src/cli/commands/console.ts` — `celilo console status` (the dashboard's single poll: zone order, per-module systems, observed health, backup freshness) and `celilo console get <module-id> [--depth N]` (one module's bounded capability closure). Both classify **read-only** under `readOnlyGrants()`, so the console's principal covers them with no hand-maintained list. The verbs are named from the read-verb vocabulary (`status`, `get`) rather than for prose, because the API authorises at two levels and classifies a leaf by its SUBCOMMAND token — `console roster` would read better and classify as a WRITE.
 - **Console projection** — `apps/celilo/src/console/projection.ts` — the narrow payload, deliberately WITHOUT `manifestData`: `module list --json` returns 156 KB for 23 modules because it embeds every manifest blob, which is the wrong payload for a poll loop. Distinguishes *not deployed* from *not observed*; a module with no system is carried, not omitted.
 - **Bounded capability closure** — `apps/celilo/src/console/closure.ts` — `computeClosure()` wraps `planConsumerCleanup()`'s edge rather than forking it, adding distance, optionality and cycle termination. Takes a bindings map (`capability_bindings`, celilo#1072) so the walk follows what a module has ACTUALLY called into; without one it follows declarations, which answers "what could this reach" rather than "what does this stand on".
 - **Read-only classifier** — `packages/core/src/read-only-classifier.ts` — `READ_VERBS`, `isReadOnlyPath`, `opOf`, `flattenLeaves`, `readOnlyGrants()`. Lives beside `COMMANDS` because it is a property of the registry, and both the MCP server's `RO_GRANTS` and the console's principal derive from it. A new read verb is covered automatically; a new write verb is not.
 - **SSH transport** — `packages/core/src/ssh-transport.ts` — `childProcessTransport`, `sshArgs`, `sshTransportWith`, and the exit reaper. Shared rather than copied because the reaper exists after 656 orphaned ssh clients threw celilo-mgr into MaxStartups throttling (celilo#921), and the console server has the same restart-freely lifecycle.
-- **Console server** — `apps/console-server/src/upstream.ts` — holds **no database handle**; every fact arrives over the remote API as a read-only principal. An interview is a FAILURE (a browser has no responder), and an unavailable read is reported with a reason (`denied` / `unknown-verb` / `unreachable` / `interview` / `malformed`) rather than returned as an empty result. Failures are not cached, so fixing a grant recovers on the next poll.
+- **Console server** — `apps/console-server/src/upstream.ts` — holds **no database handle**; every fact arrives over the remote API as a principal granted the derived read ops plus `alerts:ack`. An interview is a FAILURE (a browser has no responder), and an unavailable read is reported with a reason (`denied` / `unknown-verb` / `unreachable` / `interview` / `malformed`) rather than returned as an empty result. Failures are not cached, so fixing a grant recovers on the next poll. `Upstream.run` is the one non-read: uncached, unparsed (the ack answers with a sentence), and it drops every cached read afterwards.
+- **Console acknowledgement** — `apps/console-server/src/verbs.ts` (`readSession`, `ackAlert`), `apps/celilo/src/cli/commands/notify-config.ts` (`celilo person list --json`) — the console's ONLY write. `celilo alerts ack` falls back to `people[0]` when `--as` is absent, which in a browser would credit every acknowledgement to whoever sorts first, so `ackAlert` takes a required `person` and there is no path through it that omits the flag. The person comes from `readSession`, which resolves the identity provider's subject against `person list --json` (display name, then the `sub` claim, case-insensitive); a subject matching nobody resolves to null and the console draws no control. `ackedAt` is re-read from celilo's row rather than stamped by the console server, which is a different machine. Gates: `apps/console-server/tests/ack.test.ts` records the argv, so "refused but written anyway" is visible.
 - **Protocol** — `packages/console-protocol/` — tsrpc definitions plus the generated `serviceProto`, shared by server and SPA. The repo's single documented exception to ESM-everywhere: no `type` field, because `tsrpc-cli proto` `require()`s the protocol sources. Gated by a test in an ESM directory that round-trips a call.
 - **SPA** — `apps/console/src/` — Vite + React 19 + atom.io + tsrpc-browser. Three routes (`dashboard`, `alerts`, `backups`); a module's detail is a panel, not a fourth route. Visual constraints live in `shell.css` and four are asserted against the source by `tests/constraints.test.ts`, including "no control for any operation that can raise an interview". Every read goes through one `Panel` that separates *unavailable* from *empty*.
 - **Zone topology renderer** — `packages/visualizer/src/gen/zone-topology.ts`, `topology-theme.ts`, `column-assignment.ts`, `render/topology-svg.ts` — bands by zone in trust order, columns assigned so a dependency edge falls as a vertical drop, orthogonal routing checked against every module rather than assumed clear, and a report naming anything it could not place. Tuning playground at `bun run dev` in `packages/visualizer`, route `/topology`; it exports a `TopologyTheme` JSON the console commits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^3.3.0",
+    "@celilo/capabilities": "^3.4.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.10.0",
     "@celilo/event-bus": "^0.6.0",

package/src/capabilities/public-web-helpers.test.ts

@@ -89,7 +89,6 @@ function basePublishRequest(
 ): PublishStaticSiteRequest {
   return {
     path: '/lunacycle',
-    sourceDir: '/tmp/build/dist',
     ...overrides,
   };
 }
@@ -134,17 +133,24 @@ describe('validatePublishStaticSiteRequest', () => {
     expect(result.valid).toBe(true);
   });
 
-  test('rejects empty sourceDir', () => {
-    const result = validatePublishStaticSiteRequest(basePublishRequest({ sourceDir: '' }));
+  test('rejects a stale sourceDir, and says what to do instead', () => {
+    // Replaces 'rejects empty sourceDir'. The field is gone (D10 amendment), so
+    // the failure mode inverted: supplying one is now the error, and the
+    // message has to carry the directory move because that is not guessable
+    // from "unknown key".
+    const result = validatePublishStaticSiteRequest({
+      path: '/lunacycle',
+      sourceDir: '/tmp/site',
+    } as unknown as PublishStaticSiteRequest);
     expect(result.valid).toBe(false);
-    expect(result.errors).toContain('sourceDir is required');
+    expect(result.errors.join(' ')).toContain('site/dist');
   });
 
   test('reports multiple errors at once', () => {
     const result = validatePublishStaticSiteRequest({
       path: '',
-      sourceDir: '',
-    });
+      sourceDir: '/tmp/site',
+    } as unknown as PublishStaticSiteRequest);
     expect(result.valid).toBe(false);
     expect(result.errors.length).toBeGreaterThanOrEqual(2);
   });

package/src/capabilities/public-web-publish.test.ts

@@ -106,6 +106,7 @@ describe('publishStaticSite — clientConfig injection', () => {
   test('writes config.js into sourceDir before upload when clientConfig is provided', async () => {
     const { ops } = makeRouteOps();
     const cap = createPublicWeb({
+      webRoot: sourceDir,
       moduleId: 'lunacycle',
       logger: noopLogger,
       config: {
@@ -123,7 +124,6 @@ describe('publishStaticSite — clientConfig injection', () => {
 
     const result = await cap.publishStaticSite({
       path: '/lunacycle',
-      sourceDir,
       clientConfig: {
         AUTHENTIK_URL: 'https://auth.example.com/application/o',
         CLIENT_ID: 'lunacycle-web',
@@ -150,6 +150,7 @@ describe('publishStaticSite — clientConfig injection', () => {
   test('does not write config.js when clientConfig is omitted', async () => {
     const { ops } = makeRouteOps();
     const cap = createPublicWeb({
+      webRoot: sourceDir,
       moduleId: 'lunacycle',
       logger: noopLogger,
       config: {
@@ -167,7 +168,6 @@ describe('publishStaticSite — clientConfig injection', () => {
 
     await cap.publishStaticSite({
       path: '/lunacycle',
-      sourceDir,
       // no clientConfig
     });
 
@@ -177,6 +177,7 @@ describe('publishStaticSite — clientConfig injection', () => {
   test('registers the route as static and records moduleId/path', async () => {
     const { ops, routes } = makeRouteOps();
     const cap = createPublicWeb({
+      webRoot: sourceDir,
       moduleId: 'lunacycle',
       logger: noopLogger,
       config: {
@@ -194,7 +195,6 @@ describe('publishStaticSite — clientConfig injection', () => {
 
     await cap.publishStaticSite({
       path: '/lunacycle',
-      sourceDir,
     });
 
     const stored = routes.find((r) => r.path === '/lunacycle');
@@ -204,9 +204,16 @@ describe('publishStaticSite — clientConfig injection', () => {
     expect(stored?.slug).toBe('lunacycle');
   });
 
-  test('fails fast when sourceDir does not exist', async () => {
+  test('fails fast, and names the path to ship, when the module has no web root', async () => {
+    // The publish path's one unrecoverable input. It used to arrive on the
+    // request as `sourceDir`; core now resolves it (D10 amendment), so the
+    // missing-directory case moves onto the capability's construction.
+    //
+    // It must throw rather than upload nothing: a zero-file upload succeeds,
+    // writes a content hash over an empty release, and serves a blank page.
     const { ops } = makeRouteOps();
     const cap = createPublicWeb({
+      webRoot: '/nonexistent/path/that/should/not/exist',
       moduleId: 'lunacycle',
       logger: noopLogger,
       config: {
@@ -222,18 +229,19 @@ describe('publishStaticSite — clientConfig injection', () => {
       dnsManagedDomains: ['www.example.com'],
     });
 
-    await expect(
-      cap.publishStaticSite({
-        path: '/lunacycle',
-        sourceDir: '/nonexistent/path/that/should/not/exist',
-        clientConfig: { FOO: 'bar' },
-      }),
-    ).rejects.toThrow('sourceDir does not exist');
+    const attempt = cap.publishStaticSite({
+      path: '/lunacycle',
+      clientConfig: { FOO: 'bar' },
+    });
+    await expect(attempt).rejects.toThrow('no built site at');
+    // The operator's next move is a directory move, so the error has to name it.
+    await expect(attempt).rejects.toThrow('site/dist');
   });
 
   test('fails validation before touching the filesystem', async () => {
     const { ops } = makeRouteOps();
     const cap = createPublicWeb({
+      webRoot: sourceDir,
       moduleId: 'lunacycle',
       logger: noopLogger,
       config: {
@@ -252,7 +260,6 @@ describe('publishStaticSite — clientConfig injection', () => {
     await expect(
       cap.publishStaticSite({
         path: '', // bad — caught by validator before any side effects
-        sourceDir,
       }),
     ).rejects.toThrow('Invalid publishStaticSite request');
 
@@ -355,6 +362,7 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
     const { ops } = makeRouteOps();
 
     const cap = createPublicWeb({
+      webRoot: sourceDir,
       moduleId: 'lunacycle',
       logger,
       config: {
@@ -389,6 +397,7 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
     const { ops } = makeRouteOps();
 
     const cap = createPublicWeb({
+      webRoot: sourceDir,
       moduleId: 'lunacycle',
       logger,
       config: {
@@ -424,6 +433,7 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
     const { ops } = makeRouteOps();
 
     const cap = createPublicWeb({
+      webRoot: sourceDir,
       moduleId: 'lunacycle',
       logger,
       config: {
@@ -439,7 +449,7 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
       dnsManagedDomains: ['www.example.com'],
     });
 
-    await cap.publishStaticSite({ path: '/lunacycle', sourceDir });
+    await cap.publishStaticSite({ path: '/lunacycle' });
 
     const messageTexts = messages.map((m) => m.message);
     // The high-level call itself logs.
@@ -459,6 +469,7 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
     const { ops } = makeRouteOps();
 
     const cap = createPublicWeb({
+      webRoot: sourceDir,
       moduleId: 'lunacycle',
       logger,
       config: {

package/src/capabilities/validation.test.ts

@@ -228,6 +228,37 @@ describe('Capability Access Validation', () => {
       expect(result.success).toBe(true);
     });
 
+    test('a framework-granted capability needs no providing module', async () => {
+      // This is the breakage, not a hypothetical. `control_plane_api` has no
+      // provider module and never will — celilo grants it (web-ui-console D7b) —
+      // so the console's manifest, already merged, hit the refusal below and
+      // could not be imported at all. Note the db here is the SAME one that
+      // fails the test after this one: the difference is entirely which
+      // capability is asked for.
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'celilo-web-console',
+        name: 'Celilo Web Console',
+        version: '1.0.0',
+        description: 'Console',
+        requires: {
+          capabilities: [{ name: 'control_plane_api', version: '1.0.0' }],
+        },
+        provides: { capabilities: [] },
+        variables: { owns: [], imports: [] },
+      };
+
+      const noProviderDb = {
+        prepare: () => ({
+          get: () => undefined,
+        }),
+      } as unknown as Database;
+
+      const result = await validateCapabilityAccess(manifest, noProviderDb);
+
+      expect(result.success).toBe(true);
+    });
+
     test('should return error when required capability not found', async () => {
       const manifest: ModuleManifest = {
         celilo_contract: '1.0',

package/src/cli/commands/console-get-chain.test.ts

@@ -0,0 +1,96 @@
+/**
+ * The wiring, end to end: does `celilo console get` actually carry the chain?
+ *
+ * `orderFirewallChain` is unit-tested, `computeClosure` is unit-tested, and
+ * `loadClosureInputs` is unit-tested against real rows. None of that says the
+ * command joins them up. A dropped argument at this one call site returns a
+ * perfectly well-formed answer with an empty `chains` — which reads as a fleet
+ * with no delegation, and is the failure mode CLAUDE.md names.
+ *
+ * So this drives the REAL command against a REAL database and asserts on what
+ * it emits.
+ */
+
+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';
+
+let testDir: string;
+
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), 'celilo-console-chain-'));
+  process.env.CELILO_DB_PATH = join(testDir, 'test.db');
+  process.env.CELILO_DATA_DIR = testDir;
+});
+
+afterEach(() => {
+  rmSync(testDir, { recursive: true, force: true });
+  process.env.CELILO_DB_PATH = undefined;
+});
+
+/** The live fleet's firewall shape: caddy on iptables, iptables on the router. */
+async function seedFleet() {
+  const { getDb } = await import('../../db/client');
+  const db = getDb();
+  const consumer = JSON.stringify({ requires: { capabilities: [{ name: 'firewall' }] } });
+
+  db.$client.run(
+    `INSERT INTO modules (id, name, version, source_path, manifest_data, state)
+     VALUES ('caddy', 'Caddy', '1.0.0', '/p', '${consumer}', 'VERIFIED')`,
+  );
+  for (const id of ['iptables', 'axon']) {
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data, state)
+       VALUES ('${id}', '${id}', '1.0.0', '/p', '{}', 'VERIFIED')`,
+    );
+  }
+  db.$client.run(
+    `INSERT INTO capabilities (module_id, capability_name, version, data)
+     VALUES ('iptables', 'firewall', '1.0.0', '{"nat_ip":"192.168.0.253"}')`,
+  );
+  db.$client.run(
+    `INSERT INTO capabilities (module_id, capability_name, version, data)
+     VALUES ('axon', 'firewall', '1.0.0', '{"has_external":true}')`,
+  );
+}
+
+describe('celilo console get, and the delegation chain', () => {
+  test('--json carries the chain, in order', async () => {
+    await seedFleet();
+    const { handleConsoleGet } = await import('./console');
+    const result = handleConsoleGet(['caddy'], { json: true });
+
+    expect(result.success).toBe(true);
+    const payload = JSON.parse(result.success ? result.message : '{}');
+    expect(payload.chains).toEqual([{ capability: 'firewall', moduleIds: ['iptables', 'axon'] }]);
+  });
+
+  test('the router is in the closure, though no manifest mentions it', async () => {
+    // caddy requires `firewall` and nothing else. Walking manifests alone stops
+    // at the two registered providers and has no way to know one stands on the
+    // other — which is the whole reason the chain is derived.
+    await seedFleet();
+    const { handleConsoleGet } = await import('./console');
+    const payload = JSON.parse(
+      (() => {
+        const r = handleConsoleGet(['caddy'], { json: true });
+        return r.success ? r.message : '{}';
+      })(),
+    );
+
+    const axon = payload.nodes.find((n: { moduleId: string }) => n.moduleId === 'axon');
+    expect(axon).toBeDefined();
+  });
+
+  test('the human output prints it as a path, not as more rows', async () => {
+    // A list of two firewalls is exactly the claim being corrected. The arrow is
+    // the information.
+    await seedFleet();
+    const { handleConsoleGet } = await import('./console');
+    const result = handleConsoleGet(['caddy'], {});
+
+    expect(result.success).toBe(true);
+    expect(result.success ? result.message : '').toContain('iptables -> axon');
+  });
+});

package/src/cli/commands/console.ts

@@ -73,7 +73,7 @@ export function handleConsoleGet(
   const depth = parseDepth(flags.depth);
   if (depth instanceof Error) return { success: false, error: depth.message };
 
-  const { manifests, providerStates } = loadClosureInputs(db);
+  const { manifests, providerStates, chains } = loadClosureInputs(db);
 
   // Real bindings, for every module the walk might reach. The console draws what
   // the fleet IS doing, not what its manifests permit.
@@ -86,6 +86,7 @@ export function handleConsoleGet(
     providerStates,
     depth,
     bindings,
+    chains,
   });
 
   if (hasFlag(flags, 'json')) {
@@ -98,14 +99,21 @@ export function handleConsoleGet(
     return { success: true, message: `${moduleId} depends on nothing.` };
   }
 
+  // The chain is printed as a path rather than as more rows, because that is the
+  // whole claim: these providers are ordered, and a list of them is not.
+  const chainLines = result.chains.map(
+    (chain) => `${chain.capability}: ${chain.moduleIds.join(' -> ')}`,
+  );
+
   return {
     success: true,
-    message: result.nodes
-      .map(
+    message: [
+      ...result.nodes.map(
         (n) =>
           `hop ${n.hop}  ${n.moduleId.padEnd(24)} ${n.optional ? '(optional)' : '          '} via ${n.via.join(', ')}`,
-      )
-      .join('\n'),
+      ),
+      ...(chainLines.length > 0 ? ['', 'delegates upstream:', ...chainLines] : []),
+    ].join('\n'),
   };
 }
 

package/src/cli/commands/notify-config.test.ts

@@ -0,0 +1,79 @@
+/**
+ * `celilo person list --json` — the shape the web console maps an identity
+ * against.
+ *
+ * Worth its own test for a reason that is not obvious from the three lines it
+ * covers. The console server decides whether an authenticated browser subject
+ * corresponds to a real person, and it decides it by reading THIS. Its own
+ * tests answer that question against a fake celilo, so they prove the console
+ * parses what it was told to expect and say nothing about what celilo emits.
+ * This is the end that closes.
+ *
+ * If the payload ever stops being `[{ name, timezone }]`, the console does not
+ * error: it maps nobody, draws no acknowledge control, and reports every
+ * operator as unknown to the fleet. That reads as a configuration problem for
+ * as long as anyone is willing to believe 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 { closeDb, getDb } from '../../db/client';
+import { createPerson } from '../../services/alerting/people';
+import { setupTestDatabaseAt } from '../../test-utils/database';
+import { handlePerson } from './notify-config';
+
+let dir: string;
+const previousDbPath = process.env.CELILO_DB_PATH;
+
+beforeEach(async () => {
+  dir = mkdtempSync(join(tmpdir(), 'celilo-person-'));
+  const dbPath = join(dir, 'test.db');
+  const db = await setupTestDatabaseAt(dbPath);
+  createPerson(db, { name: 'peter', timezone: 'America/Los_Angeles' });
+  createPerson(db, { name: 'ada', timezone: 'Europe/London' });
+  db.$client.close();
+  process.env.CELILO_DB_PATH = dbPath;
+});
+
+afterEach(() => {
+  closeDb();
+  if (previousDbPath === undefined) delete process.env.CELILO_DB_PATH;
+  else process.env.CELILO_DB_PATH = previousDbPath;
+  rmSync(dir, { recursive: true, force: true });
+});
+
+/** Run `person list`, insisting it succeeded before reading what it said. */
+async function personList(flags: Record<string, boolean | string>): Promise<string> {
+  const result = await handlePerson('list', [], flags);
+  if (!result.success) throw new Error(`person list failed: ${result.error}`);
+  return result.message;
+}
+
+async function listJson(): Promise<{ name: string; timezone: string }[]> {
+  return JSON.parse(await personList({ json: true }));
+}
+
+describe('celilo person list --json', () => {
+  test('names every person, sorted the way listPeople sorts them', async () => {
+    expect((await listJson()).map((p) => p.name)).toEqual(['ada', 'peter']);
+  });
+
+  test('carries the timezone, which is the only other thing a person IS', async () => {
+    const ada = (await listJson()).find((p) => p.name === 'ada');
+    expect(ada?.timezone).toBe('Europe/London');
+  });
+
+  test('an empty fleet is an empty array, not a sentence about it', async () => {
+    // The human listing prints "Nobody configured." and a hint. A caller that
+    // parsed that would throw, which is a better failure than the one this
+    // avoids — but the console polls this, so it gets JSON either way.
+    getDb().$client.run('DELETE FROM people');
+    expect(await listJson()).toEqual([]);
+  });
+
+  test('without --json it stays the human table, and says how many', async () => {
+    expect(await personList({})).toContain('2 person');
+  });
+});

package/src/cli/commands/notify-config.ts

@@ -33,6 +33,7 @@ import {
   listRoutes,
 } from '../../services/alerting/people';
 import { parseClockTime } from '../../services/alerting/quiet-hours';
+import { hasFlag } from '../parser';
 import type { CommandResult } from '../types';
 
 const NO_SCHEMAS = defineEvents({});
@@ -109,8 +110,18 @@ function personAdd(args: string[], flags: Record<string, boolean | string>): Com
   return { success: true, message: `Added ${name} (${timezone}${quietNote})` };
 }
 
-function personList(): CommandResult {
+function personList(flags: Record<string, boolean | string> = {}): CommandResult {
   const people = listPeople(getDb());
+
+  // The web console's subject-to-person mapping reads this. It never invents a
+  // person and never lets celilo fall back to `people[0]`, so it has to be able
+  // to ASK who exists. `person:list` is already in the read-only grant set, so
+  // the flag adds a shape rather than an authority.
+  if (hasFlag(flags, 'json')) {
+    const payload = people.map((p) => ({ name: p.name, timezone: p.timezone }));
+    return { success: true, message: JSON.stringify(payload), rawOutput: true, data: payload };
+  }
+
   if (people.length === 0) {
     console.log('\nNobody configured.\n');
     console.log(
@@ -158,7 +169,7 @@ export async function handlePerson(
   switch (subcommand) {
     case undefined:
     case 'list':
-      return personList();
+      return personList(flags);
     case 'add':
       return personAdd(args, flags);
     case 'remove':

package/src/cli/commands/system-ensure-fleet-key.ts

@@ -0,0 +1,52 @@
+/**
+ * `celilo system ensure-fleet-key` — mint celilo's fleet SSH keypair if it
+ * is absent, record its public half, and print it.
+ *
+ * The celilo-side half of "minting the fleet key is not the module's job"
+ * (openspec/changes/hook-process-boundary, design D9b). celilo-mgmt's
+ * `on_install` used to generate the keypair itself, writing into celilo's
+ * data directory from inside a hook — the one directory the hook jail
+ * exists to keep out of the mount set. The hook now asks for the key
+ * through this command and receives the public half, rather than producing
+ * it.
+ *
+ * Idempotent: an existing key is reused. Re-keying would strand every
+ * machine whose authorized_keys holds the old public half.
+ */
+
+import { getDb } from '../../db/client';
+import { ensureFleetKey, getFleetSshDir } from '../../services/fleet-key';
+import { initializeSystem } from '../../services/system-init';
+import type { CommandResult } from '../types';
+
+export async function handleSystemEnsureFleetKey(): Promise<CommandResult> {
+  let key: ReturnType<typeof ensureFleetKey>;
+  try {
+    key = ensureFleetKey();
+  } catch (err) {
+    return {
+      success: false,
+      error: `Could not create the fleet SSH key in ${getFleetSshDir()}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+
+  try {
+    initializeSystem(getDb(), { 'ssh.public_key': key.publicKey });
+  } catch (err) {
+    return {
+      success: false,
+      error: `Fleet key is on disk but recording ssh.public_key failed: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+
+  // The public key alone, and `rawOutput` to say so on the record: this
+  // command exists to be read by celilo-mgmt's on_install as much as by an
+  // operator, and the key IS the answer either way (an operator pastes it into
+  // a machine's authorized_keys). Wrapping it in prose would make the caller
+  // parse for it, which is how a hook ends up depending on a sentence.
+  return { success: true, message: key.publicKey, rawOutput: true };
+}

package/src/cli/completion.ts

@@ -674,6 +674,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'init',
       'apply-config',
       'discover-network',
+      'ensure-fleet-key',
       'config',
       'secret',
       'vault-password',