@celilo/cli 1.12.0 → 1.13.0

package/CELILO_CORE_MODULES.md

@@ -55,10 +55,11 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 ## Celilo's own infrastructure (self-hosted)
 
 - **celilo-mgmt** — the celilo management server itself, deployed as a module (replaces install.sh + `system init`; ships daemon, runs migrations, self-registers). **provides:** `celilo_event_bus`, `celilo_module_deploy_worker`. **requires:** `cross_module_read`. See `openspec/specs/management-as-module/spec.md`.
-- **celilo-registry** — module registry server (Cargo sparse protocol); stores `.netapp` files, serves index + search/download API. On install it provisions a confidential introspection OIDC client via `idp.create_oidc_client` (SECURE_MODULE_PUBLISH.md §5[D-A]) and converges its issuer + introspection endpoint + creds onto the box for RFC 7662 token verification. **provides:** `registry_publish`. **requires:** `public_web`, `dns_registrar`, `idp`.
+- **celilo-registry** — module registry server (Cargo sparse protocol); stores `.netapp` files, serves index + search/download API. On install it provisions a confidential introspection OIDC client via `idp.create_oidc_client` (SECURE_MODULE_PUBLISH.md §5[D-A]) and converges its issuer + introspection endpoint + creds onto the box for RFC 7662 token verification. Its `sweep_revisions` hook is the store's ONLY delete path — `yank` flips a boolean in the index entry and frees nothing, so before it existed every build revision ever published was retained forever and a `+N` revision is auto-assigned on every publish. The production store reached 18 GB of which ~93% was superseded history, filled a 20 GB disk and took the release pipeline down. The sweep keeps the newest `sweep_keep_build_revisions` (default 1) of EVERY release, so no release can disappear and a manual rollback still works — that is what makes the hourly `timer.tick.1h` subscription defensible. It removes the index line BEFORE the payload, because the download route reads the payload file directly and never consults the index: that order leaves an interrupted sweep with an unlisted-but-served version rather than a listed one that 404s, and the orphan it leaves is reclaimed by the next run. On demand with `celilo module run-hook celilo-registry sweep_revisions` (add `dry_run=true` to see the plan). **provides:** `registry_publish`. **requires:** `public_web`, `dns_registrar`, `idp`.
 - **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-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

@@ -45,7 +45,7 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 ## Capability system (cross-module data & functions)
 
 - **Define a capability function** — `packages/capabilities/src/define-capability-function.ts` — `defineCapabilityFunction`.
-- **Canonical capability registry** — `packages/capabilities/src/capability-registry.ts` — `KNOWN_CAPABILITY_NAMES` (the authoritative list), `CapabilityRegistry` type. Public surface: `packages/capabilities/src/index.ts`.
+- **Canonical capability registry** — `packages/capabilities/src/capability-registry.ts` — `KNOWN_CAPABILITY_NAMES` (the authoritative list), `CapabilityRegistry` type. Also `PROVIDER_VIEW_CAPABILITIES` / `isProviderView` / `ProviderViewCapabilities`: the registry entries (`web_routes`, `firewall_registry`) that are framework-injected PROVIDER VIEWS rather than capabilities a module can declare — in the registry so audits and type checks reach them, named separately so author-facing surfaces leave them out. `ProviderViewCapabilities` is what puts them on a hook's `capabilities` object. Public surface: `packages/capabilities/src/index.ts`.
 - **Loader (wires provider factories into hook contexts)** — `apps/celilo/src/hooks/capability-loader.ts` — `loadCapabilityFunctions`, `resolveFirewallNatIp`.
 - **Which provider a consumer actually resolved to (`capability_bindings`)** — `apps/celilo/src/services/capability-bindings.ts` — `recordCapabilityBinding`, `listCapabilityBindings`, `withBindingRecord`, written from the single return of `loadCapabilityFunctions`. The `capabilities` table is provider-side only, so celilo could answer "who COULD provide this" and never "who does this module actually use"; every caller needing the second question rebuilt the same approximation (the consumer's `requires` + `optional` crossed with `capabilities`), which names every provider a module MIGHT have bound to. `tango-nexus` declares four optional capabilities, is deployed against one off-fleet host, and that approximation carries three edges that do not exist. **The CALL is the binding, not the resolution** — the loader injects every registered capability regardless of what the consumer declared (its own comment: "not just required ones"), so recording what it resolves is a SUPERSET of even the permissive set. A consumer's hook invoking a method is the only event that separates the optional it uses from the ones it merely declares, which is why this matters most for the capabilities that mint nothing (`external_web`, `idp`, `source_forge`, `registry_publish`, `control_plane_vpn`, `apt_publish`) and therefore leave no artefact anywhere else. Recorded on ATTEMPT rather than success: a consumer that called a provider and got an error is standing on that provider, and hiding the edge exactly when the call fails hides it when it matters most. Unique on (consumer, capability) so a redeploy re-asserts and a provider swap rewrites in place; `bound_at` is LAST-SEEN, so a binding last exercised forty deploys ago is a queryable fact rather than a silent lie. Cascades on the consumer. It runs BESIDE `planConsumerCleanup`, never narrowing it — cleanup must still reach every provider that might hold minted state, including one whose binding row was never written. See celilo#1072.
 - **Ledger wrappers (stateful capabilities)** — `apps/celilo/src/services/dns-registrations.ts` (`withDnsRegistrationLedger`), `apps/celilo/src/services/dns-internal-records.ts` (`withDnsInternalLedger`).
@@ -180,7 +180,8 @@ runner seam (`execRunner` real / `createMockRunner` for tests) lives in
 ## Hooks & deploy
 
 - **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.ts` (the spawned shim — the ONLY thing that `import()`s module code). `executeHookScript` spawns `bun hook-runner.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` — `PATH`, `HOME`, `LANG`, `TZ`, `TMPDIR`, `CELILO_HOOK_*`, `CELILO_DEBUG`), 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. Stage 1 of `openspec/changes/hook-process-boundary`; it claims the environment and the process, not the filesystem (a hook can still compute the default master-key path) and not the network.
+- **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.ts` (the spawned shim — the ONLY thing that `import()`s module code). `executeHookScript` spawns `bun hook-runner.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` — `PATH`, `HOME`, `LANG`, `TZ`, `TMPDIR`, `CELILO_HOOK_*`, `CELILO_DEBUG`), 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, the network is not claimed at all (stage 3, D12).
+- **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, `~/.ssh` read-only (stage 2 only — stage 3 drops it, D12), and `/tmp` a fresh tmpfs FIRST so it cannot erase the socket or a staged input. **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. `CELILO_HOOK_JAIL` = `auto` (default) / `required` / `off`. No backend on macOS yet (task 4.8), and the hook then runs unjailed with the mode recorded.
 - **Deploy pipeline** — `apps/celilo/src/services/module-deploy.ts`.
 - **DNS provider backfill** (re-emit registrations when a provider deploys) — `apps/celilo/src/services/dns-provider-backfill.ts` — `isDnsInternalProvider`, `backfillProviderDns`.
 - **Base-module aspects (fan-out across the fleet)** — `apps/celilo/src/services/aspect-runner.ts` — `planAspectFanOut`, `runAspectFanOut`, `maybeRunAspectForTrigger`. Aspect content lives in `modules/<m>/base-module-aspect/` (e.g. knot-unbound-internal, technitium). Two directions, with DELIBERATELY OPPOSITE failure semantics:
@@ -351,6 +352,20 @@ Run any celilo command on celilo-mgr over SSH instead of screen-scraping `ssh <h
 - **Module auto-upgrade (registry-poll CD)** — the *pull* half of continuous deployment: celilo-mgr polls the registry and upgrades opted-in modules unattended. Spec: `openspec/specs/module-auto-upgrade/spec.md`. Entry points: `apps/celilo/src/cli/commands/module-upgrade.ts` — `runRegistryPoll` (the `--poll` path), `selectPollTargets` (pure: `autoUpgrade && latest && change ∉ {up-to-date, ahead}`), `upgradeOneModule` (update → backup → deploy → verify), `needsPreUpgradeBackup`, `pickAutoUpgrade`/`pickUpgradePolicy` (both fail closed/safe); `classifyVersionChange` in `module-update.ts` (treats a registry `+N` revision as a patch); `resolveDeployPosture` in `apps/celilo/src/services/deploy-posture.ts`. Trigger: celilo-mgmt's `registry-poll` subscription (`modules/celilo-mgmt/manifest.yml`) on `timer.tick.15m` with handler **`celilo module upgrade --poll`** — the flag is REQUIRED, since the dispatcher appends the event id positionally and a bare handler would consume it as the optional module name (silent: 3108 deliveries, 0 successes). Operator controls are framework config keys settable on ANY module (`FRAMEWORK_CONFIG_KEYS` in `module-config.ts`): `auto_upgrade` (opt-in, default false) and `upgrade_policy` (`by-semver`|`always-safe`|`always-fast`), validated at set time because both readers fail open. ⚠️ `always-safe` guarantees safe *posture*, NOT a backup — `needsPreUpgradeBackup` also requires the TARGET manifest to declare an `on_backup` hook, else it warns and proceeds. Confirm a data-bearing module declares `on_backup` before enabling `auto_upgrade` on it. The *build* half (app CI publishing a `.netapp` on merge) is not yet shipped — `openspec/changes/build-bus-poll-cd`.
 - **MCP service (`@celilo/mcp`)** — `packages/mcp/src/` — an operator-facing stdio MCP server (official `@modelcontextprotocol/sdk`, bin `celilo-mcp`) that drives a remote celilo server over the Remote API for an AI client. Two-item config (`config.ts`: `server` + `defaultUser`, env or `~/.config/celilo-mcp/config.json`). Dual-principal auth (`auth.ts`: `celilo-mcp auth setup` enrolls read-only `celilo-mcp-ro` + full `celilo-mcp-rw` ed25519 keypairs, prints the exact `celilo api grant` lines the operator runs server-side). Transport (`transport.ts`): reuses `@celilo/core` `runRemoteClient`, selecting the principal by `ssh -i <key>` and capturing structured output. Tool surface is generated LIVE from the server's command registry — `registry-fetch.ts` fetches `celilo commands --json` (+ `service list --json` for configured providers) over the RO principal on connect; `tools-from-registry.ts` (pure) projects that into one tool per runnable leaf, grouped by top-level command (`celilo_module_*`, `celilo_proxmox_*`, …), each with a Zod input schema from the leaf's args/flags and a read/write tag → RO/RW routing, plus a generic `celilo_run` escape hatch. Auto-detect hides provider-gated groups (e.g. `celilo_proxmox_*` until a Proxmox service is configured) and re-detects on a timer, emitting `notifications/tools/list_changed` when the surface changes. Coverage gate (`tests/coverage.test.ts`) asserts every registry leaf maps to a tool. Composite RO troubleshooting tools (`troubleshoot.ts` pure correlation + `troubleshoot-tools.ts` thin adapters): `celilo_assess_module <id>` and `celilo_fleet_status` correlate `celilo audit --json` (the drift backbone) with the `module list --json` roster into a per-module / fleet-wide verdict. Design: `openspec/changes/celilo-mcp-service/proposal.md`. (Distinct from the dev/ops `@celilo/mcp-server` below.)
 
+## 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.
+
+- **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.
+- **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.
+
 ## E2E simulation
 
 - **cele2e harness** — `packages/e2e/src/` — `runner.ts`, `container-manager.ts` (`startNetwork`, `reconnectNetwork`), `network-builder.ts` (`NetworkBuilder`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,9 +58,9 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^3.2.0",
+    "@celilo/capabilities": "^3.3.0",
     "@celilo/cli-display": "^0.2.0",
-    "@celilo/core": "^0.9.1",
+    "@celilo/core": "^0.10.0",
     "@celilo/event-bus": "^0.6.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/src/cli/commands/alerts-list.ts

@@ -7,6 +7,7 @@
  */
 
 import { getDb } from '../../db/client';
+import { people } from '../../db/schema';
 import { renderAlertTable, toAlertRow } from '../../services/alerting/format';
 import { listMonitors } from '../../services/alerting/monitors';
 import { policyForAlert } from '../../services/alerting/notify-deps';
@@ -23,10 +24,21 @@ export async function handleAlertsList(
 
   if (flags.json) {
     const monitorsById = new Map(listMonitors(db).map((m) => [m.id, m.target]));
+    const peopleById = new Map(
+      db
+        .select()
+        .from(people)
+        .all()
+        .map((p) => [p.id, p.name]),
+    );
     return {
       success: true,
       message: JSON.stringify(
         live.map((alert) => ({
+          // The row's own identifier, needed by anything that acts on ONE
+          // alert. `key` identifies the condition and is stable across
+          // restarts; `id` identifies this occurrence of it.
+          id: alert.id,
           key: alert.key,
           state: alert.state,
           severity: alert.severity,
@@ -43,7 +55,10 @@ export async function handleAlertsList(
           suppressedByAlertId: alert.suppressedByAlertId,
           suppressedByWindowId: alert.suppressedByWindowId,
           awaitingConfirmation: alert.awaitingConfirmation,
-          ackedBy: alert.ackedBy,
+          // Resolved to a name. The column is a `people` foreign key, and a
+          // bare id tells a reader nothing about who acknowledged their alert.
+          ackedBy: alert.ackedBy ? (peopleById.get(alert.ackedBy) ?? alert.ackedBy) : null,
+          ackedAt: alert.ackedAt,
           silencedUntil: alert.silencedUntil,
           message: alert.message,
         })),

package/src/cli/commands/backup-list.test.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, test } from 'bun:test';
 import type { Backup } from '../../db/schema';
-import { backedUpModuleIds, lastSuccessSummaryLines } from './backup-list';
+import { backedUpModuleIds, backupListJson, lastSuccessSummaryLines } from './backup-list';
 
 const NOW = Date.UTC(2026, 7, 13, 12, 0, 0);
 const ago = (ms: number) => new Date(NOW - ms);
@@ -81,3 +81,84 @@ describe('lastSuccessSummaryLines', () => {
     expect(line).not.toContain('attempts');
   });
 });
+
+/**
+ * `--json`, which exists because the human output cannot be parsed back.
+ *
+ * `formatRelativeDate` buckets everything past six days — "last week", then
+ * "2 weeks ago", then "last month". A person reading a screen wants that. The
+ * web console draws one square per module per day and cannot place a row it
+ * cannot date, and a row it leaves out renders as a day on which no backup ran.
+ * Inventing a gap in somebody's backup coverage is the one thing that page must
+ * never do, so these pin the exactness rather than the formatting.
+ */
+describe('backupListJson', () => {
+  const AT = Date.UTC(2026, 6, 14, 18, 13, 6);
+
+  function row(partial: Partial<Backup>): Backup {
+    return backup({
+      id: 'da8522ea-4319-45fb-ae06-a6d3525f4b9f',
+      storageId: 'st-1',
+      storagePath: '2026-07-14/forgejo.backup',
+      status: 'completed',
+      sizeBytes: 2_900_000_000,
+      startedAt: new Date(AT),
+      completedAt: new Date(AT + 1000),
+      ...partial,
+    });
+  }
+
+  const noDatabase = {
+    storageNameOf: () => 'aws-backups',
+    historyOf: () => ({
+      lastSuccessAt: new Date(AT),
+      lastAttemptAt: new Date(AT),
+      consecutiveFailures: 0,
+    }),
+  };
+
+  function parse(backups: Backup[], windowDays: number | null = null) {
+    const result = backupListJson(backups, windowDays, noDatabase);
+    // Narrowed rather than asserted: `message` lives only on the success arm,
+    // and a failure here should say what went wrong, not read as empty JSON.
+    if (!result.success) throw new Error(result.error);
+    return JSON.parse(result.message ?? '{}');
+  }
+
+  test('a timestamp survives as an exact instant, not a bucket', () => {
+    // The same row the human path renders as "last month".
+    const [only] = parse([row({})].map((b) => b)).backups;
+    expect(only.startedAt).toBe(AT);
+    expect(only.completedAt).toBe(AT + 1000);
+  });
+
+  test('the short id is offered so a caller need not slice a UUID', () => {
+    expect(parse([row({})]).backups[0].shortId).toBe('da8522ea');
+  });
+
+  test('a failed attempt reports no size and no completion', () => {
+    // Not zero and not "now". A failure kept nothing and never finished, and
+    // both of those are facts a caller renders differently from a small backup.
+    const [only] = parse([row({ status: 'failed', sizeBytes: null, completedAt: null })]).backups;
+    expect(only.sizeBytes).toBeNull();
+    expect(only.completedAt).toBeNull();
+  });
+
+  test('the failure cause is carried, because one red square is not one problem', () => {
+    const [only] = parse([row({ status: 'failed', errorMessage: 'ENOSPC' })]).backups;
+    expect(only.error).toBe('ENOSPC');
+  });
+
+  test('windowDays is echoed, so a caller can tell "nothing ran" from "not asked"', () => {
+    // Null means unbounded. A number means the rows are complete only that far
+    // back, and an empty day beyond it asserts nothing.
+    expect(parse([row({})], 30).windowDays).toBe(30);
+    expect(parse([row({})], null).windowDays).toBeNull();
+  });
+
+  test('an empty listing is a valid answer, not an error', () => {
+    const empty = parse([]);
+    expect(empty.backups).toEqual([]);
+    expect(empty.modules).toEqual([]);
+  });
+});

package/src/cli/commands/backup-list.ts

@@ -10,6 +10,7 @@ import {
   listBackups,
   loadBackupHistory,
 } from '../../services/backup-metadata';
+import type { BackupHistory } from '../../services/backup-schedule';
 import { getBackupStorage } from '../../services/backup-storage';
 import { celiloIntro } from '../prompts';
 import type { CommandResult } from '../types';
@@ -136,28 +137,136 @@ export function lastSuccessSummaryLines(
   });
 }
 
+/**
+ * The listing as data, for anything that is not a person reading a terminal.
+ *
+ * This exists because the human output cannot be parsed back into facts. Ages
+ * are rendered relative and BUCKETED — everything past six days collapses to
+ * "last week", then "2 weeks ago", then "last month" — so a caller reading the
+ * text can place a backup on a day for six days and not one day further.
+ *
+ * That is fine for a person, who is asking "is this recent". It is not fine for
+ * the web console, which draws one square per module per day: a row it cannot
+ * place is a row it must leave out, and a missing row renders as a day on which
+ * no backup ran. The one thing a coverage grid must never do is invent a gap.
+ *
+ * So the timestamps go out as epoch ms, exactly as stored, and the caller
+ * decides how to say them. Everything else here is what the human path already
+ * shows — the same rows and the same per-module summary — because a second
+ * source of truth for "what backups exist" is worth less than no second source.
+ */
+/**
+ * The two database reads this needs, injectable so the shape can be tested
+ * without one (Rule 2.3). The defaults are the real thing.
+ */
+export interface BackupListJsonDeps {
+  storageNameOf: (storageId: string) => string;
+  historyOf: (moduleId: string) => BackupHistory;
+}
+
+const LIVE_LOOKUPS: BackupListJsonDeps = {
+  storageNameOf: (storageId) => getBackupStorage(storageId)?.storageId ?? 'unknown',
+  historyOf: loadBackupHistory,
+};
+
+export function backupListJson(
+  backupList: Backup[],
+  windowDays: number | null,
+  deps: BackupListJsonDeps = LIVE_LOOKUPS,
+): CommandResult {
+  // One lookup per distinct destination rather than one per row: a month of a
+  // failing module is hundreds of rows and two or three storages.
+  const storageNames = new Map<string, string>();
+  for (const backup of backupList) {
+    if (storageNames.has(backup.storageId)) continue;
+    storageNames.set(backup.storageId, deps.storageNameOf(backup.storageId));
+  }
+
+  const payload = {
+    asOf: Date.now(),
+    /**
+     * How far back the rows are COMPLETE for, or null when unbounded.
+     *
+     * The caller needs this to tell "nothing ran that day" from "you did not
+     * ask about that day". They look identical in the data and only one of them
+     * is somebody's missing backup.
+     */
+    windowDays,
+    backups: backupList.map((backup) => ({
+      id: backup.id,
+      shortId: backup.id.substring(0, 8),
+      moduleId: backup.moduleId,
+      backupType: backup.backupType,
+      status: backup.status,
+      sizeBytes: backup.sizeBytes,
+      // Epoch ms, both of them. `startedAt` is when the attempt began and
+      // `completedAt` is when it finished; a failed attempt has no second one.
+      startedAt: backup.startedAt.getTime(),
+      completedAt: backup.completedAt ? backup.completedAt.getTime() : null,
+      storage: storageNames.get(backup.storageId) ?? 'unknown',
+      storagePath: backup.storagePath,
+      moduleVersion: backup.moduleVersion,
+      schemaVersion: backup.schemaVersion,
+      name: backup.name,
+      error: backup.errorMessage,
+    })),
+    modules: backedUpModuleIds(backupList).map((moduleId) => {
+      const history = deps.historyOf(moduleId);
+      return {
+        moduleId,
+        lastSuccessAt: history.lastSuccessAt ? history.lastSuccessAt.getTime() : null,
+        lastAttemptAt: history.lastAttemptAt ? history.lastAttemptAt.getTime() : null,
+        consecutiveFailures: history.consecutiveFailures,
+      };
+    }),
+  };
+
+  // `rawOutput` keeps the payload out of the decorating renderer, which would
+  // wrap it and stop it parsing (celilo#698).
+  return { success: true, message: JSON.stringify(payload, null, 2), rawOutput: true };
+}
+
 export async function handleBackupList(
   args: string[],
   flags: Record<string, boolean | string> = {},
 ): Promise<CommandResult> {
   try {
     const moduleIdOrBackupId = args[0];
-    const limit = typeof flags.limit === 'string' ? Number.parseInt(flags.limit, 10) : 20;
+    // A JSON caller is a program with a window in mind, not a person skimming a
+    // screen, so 20 is the wrong ceiling for it. It still takes --limit.
+    const defaultLimit = flags.json ? 5000 : 20;
+    const limit = typeof flags.limit === 'string' ? Number.parseInt(flags.limit, 10) : defaultLimit;
+    const windowDays = typeof flags.since === 'string' ? Number.parseInt(flags.since, 10) : null;
+    if (windowDays !== null && (!Number.isFinite(windowDays) || windowDays <= 0)) {
+      return {
+        success: false,
+        error: `--since takes a positive number of days, got: ${flags.since}`,
+      };
+    }
+    const since = windowDays === null ? undefined : Date.now() - windowDays * 86_400_000;
 
     // If the argument looks like a backup ID (hex chars), show detail view
     if (moduleIdOrBackupId && /^[0-9a-f]{8,}$/i.test(moduleIdOrBackupId)) {
       const backup = getBackup(moduleIdOrBackupId);
       if (backup) {
+        // The same envelope as the listing, holding one row. A caller that can
+        // parse `backup list --json` can parse this without a second shape, and
+        // asking about one backup is the commonest scripted case there is.
+        if (flags.json) return backupListJson([backup], null);
         celiloIntro('Backup Detail');
         return showBackupDetail(moduleIdOrBackupId);
       }
       // Fall through to module filter if not a backup ID
     }
 
-    celiloIntro('Available Backups');
-
     const moduleId = moduleIdOrBackupId;
-    const backupList = listBackups({ moduleId, limit });
+    const backupList = listBackups({ moduleId, limit, since });
+
+    // Before the banner: --json must emit JSON and nothing else, or the first
+    // thing a parser meets is a celilo logo.
+    if (flags.json) return backupListJson(backupList, windowDays);
+
+    celiloIntro('Available Backups');
 
     if (backupList.length === 0) {
       console.log('No backups found.\n');

package/src/cli/commands/console.ts

@@ -0,0 +1,122 @@
+/**
+ * `celilo console …` — the narrow reads the web console polls.
+ *
+ * A NOTE ON THE VERB NAMES, because they read oddly on purpose. celilo's remote
+ * API authorises at two levels (`command:subcommand`), and a leaf is classified
+ * read-only by its subcommand token against `READ_VERBS` in `@celilo/core`. So
+ * these are named from that vocabulary — `status`, `list`, `get` — rather than
+ * for prose. `console roster` would be a nicer name and would classify as a
+ * WRITE, which would either deny the console its own data or require widening
+ * the read-verb set for every principal in the fleet.
+ *
+ * All three are reads. The console's principal is granted read ops only, so a
+ * mutating verb added to this file would be refused at the API boundary rather
+ * than running.
+ */
+
+import {
+  DEFAULT_CLOSURE_DEPTH,
+  UNBOUNDED_CLOSURE_DEPTH,
+  computeClosure,
+} from '../../console/closure';
+import {
+  consoleStatus,
+  loadBindings,
+  loadClosureInputs,
+  moduleExists,
+} from '../../console/projection';
+import { getDb } from '../../db/client';
+import { loadCapabilityProviderRows } from '../../services/consumer-cleanup';
+import { hasFlag } from '../parser';
+import type { CommandResult } from '../types';
+
+/** `celilo console status [--json]` — the dashboard's single poll. */
+export function handleConsoleStatus(flags: Record<string, string | boolean> = {}): CommandResult {
+  const payload = consoleStatus(getDb());
+
+  if (hasFlag(flags, 'json')) {
+    return { success: true, message: JSON.stringify(payload), rawOutput: true, data: payload };
+  }
+
+  const lines = payload.modules.map(
+    (m) =>
+      `${m.id.padEnd(24)} ${m.state.padEnd(12)} ${m.health.cell.padEnd(14)} ${
+        m.systems.map((s) => `${s.hostname}@${s.zone}`).join(', ') || '(no system)'
+      }`,
+  );
+  return {
+    success: true,
+    message: [`zones: ${payload.zones.join(' > ')}`, '', ...lines].join('\n'),
+  };
+}
+
+/**
+ * `celilo console get <module-id> [--depth N] [--json]` — one module's bounded
+ * capability closure.
+ *
+ * `--depth 0` walks the whole graph. The walk terminates on cycles either way.
+ */
+export function handleConsoleGet(
+  args: string[],
+  flags: Record<string, string | boolean> = {},
+): CommandResult {
+  const moduleId = args[0];
+  if (!moduleId) {
+    return { success: false, error: 'Module ID required\n\nUsage: celilo console get <module-id>' };
+  }
+
+  const db = getDb();
+  if (!moduleExists(db, moduleId)) {
+    return { success: false, error: `Module not found: ${moduleId}` };
+  }
+
+  const depth = parseDepth(flags.depth);
+  if (depth instanceof Error) return { success: false, error: depth.message };
+
+  const { manifests, providerStates } = loadClosureInputs(db);
+
+  // Real bindings, for every module the walk might reach. The console draws what
+  // the fleet IS doing, not what its manifests permit.
+  const bindings = new Map([...manifests.keys()].map((id) => [id, loadBindings(db, id)] as const));
+
+  const result = computeClosure({
+    rootModuleId: moduleId,
+    manifests,
+    providerRows: loadCapabilityProviderRows(db),
+    providerStates,
+    depth,
+    bindings,
+  });
+
+  if (hasFlag(flags, 'json')) {
+    return { success: true, message: JSON.stringify(result), rawOutput: true, data: result };
+  }
+
+  if (result.nodes.length === 0) {
+    // An answer, not a failure. The console says the same thing in words rather
+    // than rendering an empty picture that reads as still loading.
+    return { success: true, message: `${moduleId} depends on nothing.` };
+  }
+
+  return {
+    success: true,
+    message: result.nodes
+      .map(
+        (n) =>
+          `hop ${n.hop}  ${n.moduleId.padEnd(24)} ${n.optional ? '(optional)' : '          '} via ${n.via.join(', ')}`,
+      )
+      .join('\n'),
+  };
+}
+
+/** Depth flag, or an Error explaining what was wrong with it. */
+function parseDepth(raw: string | boolean | undefined): number | Error {
+  if (raw === undefined || raw === true) return DEFAULT_CLOSURE_DEPTH;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return new Error(
+      `Invalid --depth: ${raw}\n\nExpected a non-negative integer (${UNBOUNDED_CLOSURE_DEPTH} walks the whole graph).`,
+    );
+  }
+  return parsed;
+}

package/src/cli/commands/module-list.ts

@@ -1,8 +1,6 @@
-import { eq } from 'drizzle-orm';
-import { type DbClient, getDb } from '../../db/client';
-import { modules, modules as modulesTable, monitors } from '../../db/schema';
-import { moduleHealthCell } from '../../services/alerting/format';
-import { loadAllLiveAlerts, summariseByModule } from '../../services/alerting/store';
+import { getDb } from '../../db/client';
+import { modules } from '../../db/schema';
+import { loadObservedHealth } from '../../services/alerting/observed-health';
 import { formatPausedDuration } from '../../services/module-pause';
 import { hasFlag } from '../parser';
 import type { CommandResult } from '../types';
@@ -77,39 +75,3 @@ export async function handleModuleList(
     data: moduleRows,
   };
 }
-
-/**
- * Observed health per module: `ok`, `N firing`, `suppressed`, or
- * `not observed`.
- *
- * Only computed for DEPLOYED modules — a module still being imported has
- * nothing to observe, and reporting it as unwatched would be noise rather
- * than a finding.
- */
-function loadObservedHealth(db: DbClient): Map<string, string> {
-  const monitored = new Set(
-    db
-      .select({ target: monitors.target })
-      .from(monitors)
-      .where(eq(monitors.enabled, true))
-      .all()
-      .map((m) => m.target),
-  );
-  const byModule = summariseByModule(loadAllLiveAlerts(db));
-
-  const result = new Map<string, string>();
-  for (const module of db.select().from(modulesTable).all()) {
-    if (module.state !== 'INSTALLED' && module.state !== 'VERIFIED') continue;
-
-    const summary = byModule.get(module.id) ?? [];
-    result.set(
-      module.id,
-      moduleHealthCell({
-        monitored: monitored.has(module.id),
-        firingCount: summary.filter((s) => !s.suppressed).length,
-        suppressed: summary.length > 0 && summary.every((s) => s.suppressed),
-      }),
-    );
-  }
-  return result;
-}

package/src/cli/completion.ts

@@ -37,6 +37,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'backup',
       'capability',
       'commands',
+      'console',
       'dns',
       'completion',
       'alerts',
@@ -658,6 +659,10 @@ export async function getCompletions(words: string[], current: number): Promise<
   }
 
   // Completion subcommands
+  if (command === 'console' && currentIndex === 1) {
+    return filterSuggestions(['status', 'get'], args[1] || '');
+  }
+
   if (command === 'completion' && currentIndex === 1) {
     const subcommands = ['bash', 'zsh'];
     return filterSuggestions(subcommands, args[1] || '');

package/src/cli/index.ts

@@ -25,6 +25,7 @@ import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
 import { handleCommands } from './commands/commands-json';
 import { handleCompletion } from './commands/completion';
+import { handleConsoleGet, handleConsoleStatus } from './commands/console';
 import { handleDnsRegistrations } from './commands/dns';
 import {
   handleEventsAck,
@@ -225,6 +226,7 @@ Commands:
   api                      Manage remote-API access (principals, grants, authorized_keys)
   completion               Generate shell completion scripts (bash/zsh)
   commands                 Print the CLI command registry as JSON (drives @celilo/mcp)
+  console                  Narrow read-only projections for the web console
 
   help, --help, -h         Show this help message
 
@@ -803,7 +805,11 @@ Subcommands:
 
   list [module-id]         List available backups
     Options:
-      --limit <n>          Number of backups to show (default: 20)
+      --limit <n>          Number of backups to show (default: 20; 5000 with --json)
+      --json               Emit the listing as JSON with EXACT timestamps.
+                           The human output buckets ages past six days into
+                           "last week", so it cannot be parsed back into days.
+      --since <days>       Only attempts from the last N days
 
   restore <backup-id>      Restore from a backup
     Options:
@@ -1275,6 +1281,24 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     return handleCommands(parsed.args, parsed.flags);
   }
 
+  // The web console's narrow reads.
+  if (parsed.command === 'console') {
+    const flagError = checkFlags('console', parsed.subcommand, parsed.flags, parsed.args);
+    if (flagError) return flagError;
+
+    switch (parsed.subcommand) {
+      case 'status':
+        return handleConsoleStatus(parsed.flags);
+      case 'get':
+        return handleConsoleGet(parsed.args, parsed.flags);
+      default:
+        return {
+          success: false,
+          error: 'Console subcommand required: status | get',
+        };
+    }
+  }
+
   // Top-level alias: `celilo audit` → `celilo system audit`
   if (parsed.command === 'audit') {
     return handleSystemAudit(parsed.args, parsed.flags);