@celilo/cli 1.14.0 → 2.0.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, 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-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. **Deployable, not yet servable.** The manifest, the SPA, the console server, the read verbs, the `control_plane_api` capability, the `on_install` that enrols the principal, and a full deployable body (`terraform/`, `ansible/` with a role, config variables, and a `build:` step compiling a per-architecture bun binary plus the SPA) all exist. What does not exist is an OIDC client: the console refuses to serve without an identity provider, and nothing creates one yet, so a deployed unit starts, fails its start limit and sits in `failed` with the reason in its journal. That is deliberate rather than hidden — leaving the service disabled would make an unfinished module look like a clean converge. The e2e suite does not exist either. 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

@@ -93,6 +93,26 @@ content module targets either with
 `capabilities.external_web ?? capabilities.public_web`. Both are
 **authoritative**: a publish that doesn't reach clients throws (#328).
 
+- **Static-content converge (`/srv/www`, design D10)** —
+  `apps/celilo/src/services/static-content-converge.ts` (pure
+  `planStaticContent`/`buildStaticContentPlan` + `writeStaticContentVars` + the
+  `executeAnsible` caller `convergeStaticContent`). The declared `web_routes`
+  release set (slug, content hash, hostnames, the source dir core derives from
+  `modules.source_path`) is the desired state; the provider's Ansible converge
+  makes `/srv/www` match: content-hashed release dirs `/srv/www/<slug>-<hash>`,
+  an atomic symlink swap of `/srv/www/<slug>`, pruning beyond
+  `static_release_retention` (caddy manifest variable, operator config with
+  default 5 — the role never carries the number). Two callers, one plan: the
+  `public_web` capability's `convergeStaticContent` callback (tag-scoped run
+  through `executeAnsible`, so a publish returns only once the host matches)
+  and the provider's own deploy (vars written pre-Ansible in
+  `module-deploy.ts`, so a rebuilt host recovers with no consumer). The
+  content hash lands on EVERY route row sharing the slug. Replaced the
+  hand-built ssh tar pipe in `upload_static_assets` (celilo#1014); the
+  no-hand-built-SSH gate now scans `@celilo/capabilities` everywhere except
+  its primitive file (`module-script-scan.ts`, `scanCapabilityPackageSource`).
+  e2e: `modules/caddy/e2e/static-content-converge.test.ts`.
+
 ## Remote-ops primitives (the SSH seam — modules never hand-build SSH)
 
 Module hooks reach a remote box ONLY through these typed primitives
@@ -180,8 +200,10 @@ 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. 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.
+- **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.
+- **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. `CELILO_HOOK_JAIL` = `auto` (default) / `required` / `off`. 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.
 - **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:
@@ -263,7 +285,7 @@ is currently wrong, and routes carry the message to a person's phone. Design:
 
 - **Alert identity** — `apps/celilo/src/services/alerting/keys.ts` — the key grammar (`module:<id>[/check:<name>]`, `builtin:<check>[/<kind>:<target>]`) that makes "the same problem" the same alert across runs. `moduleAlertKey`, `moduleCheckAlertKey`, `builtinAlertKey`, `parseAlertKey`.
 - **Reconciliation** — `apps/celilo/src/services/alerting/reconcile.ts` (`reconcile`) — a successful run's failing-key set is authoritative and resolution is by SET DIFFERENCE (absent ⇒ resolved). A run whose outcome is `error` resolves NOTHING and fires a module-level alert instead: the false-all-clear guard.
-- **Monitor execution** — `apps/celilo/src/services/alerting/run-monitor.ts` (`runOneMonitor`) + `sweep.ts` (`selectDueMonitors`) + `builtin-monitors.ts` / `health-coverage.ts` (the built-in checks and the "module with no health check" coverage check).
+- **Monitor execution** — `apps/celilo/src/services/alerting/run-monitor.ts` (`runOneMonitor`) + `sweep.ts` (`selectDueMonitors`) + `builtin-monitors.ts` / `health-coverage.ts` / `hook-jail.ts` (the built-in checks, the "module with no health check" coverage check, and the hook-jail regression self-monitor).
 - **Health-check cadence (one accessor)** — `apps/celilo/src/services/alerting/health-cadence.ts` — `effectiveHealthCheckCadence(manifest, override)`, `isScheduled`, `loadModuleHealthCadences`, `reconcileModuleWatchState`. The manifest's `hooks.health_check.interval` SUGGESTS; the operator's `health_check_interval` decides; both resolve at read time. `null` means nobody named a cadence (a coverage gap); `'manual'` means the operator opted out (a decision — raises no coverage finding, and resolves the module's live alerts on the way down, since nothing will report on them again).
 - **⚠️ `monitors.intervalMinutes` and `monitors.enabled` are `builtin_check`-only.** A `module_hook` row carries severity, escalation policy and `lastRunAt`; its cadence and whether it is watched resolve through the accessor above. The columns' meaning depending on `kind` is a named smell (design.md D8) — the alternatives are a cached resolved value that rots, or splitting the table, which needs a synthetic monitor identity for `alerts.monitorId`. Gates: `sweep-runner.test.ts` asserts a module row's stored values are NOT consulted; `cadence-migration.test.ts` asserts the same through `loadModuleHealthCadences`.
 - **Carrying an existing fleet over** — `apps/celilo/src/services/alerting/cadence-migration.ts` (`migrateMonitorCadences`), run from `celilo system migrate` (the `.deb` postinst runs it on every apt upgrade). A monitor row whose cadence diverges from its manifest gets that cadence written as an override; a disabled one gets `manual`. Not bookkeeping: without it the upgrade that ships read-time resolution silently reverts every hand-set cadence to the author's suggestion and resumes watching modules an operator deliberately disabled. Idempotent — writes only where no override exists.

package/README.md

@@ -286,7 +286,6 @@ bun run test:integration    # All integration tests (run via bun test)
 # - VM resource defaults
 
 # What gets skipped:
-# - Nix builds
 # - Docker builds
 # - Slow module builds (Caddy)
 ```
@@ -296,7 +295,6 @@ bun run test:integration    # All integration tests (run via bun test)
 bun run test:integration-slow  # Full builds + end-to-end
 
 # Includes everything from fast tests PLUS:
-# - Full Nix builds (Caddy with modules)
 # - Docker builds
 # - Complete module packaging
 ```

package/drizzle/0030_drop_module_builds_environment.sql

@@ -0,0 +1,8 @@
+-- The `environment` column recorded whether a build ran inside a `nix develop`
+-- shell ('nix') or with system tools ('system'). That was the only information
+-- it carried, and the Nix build path never shipped: no module has ever carried
+-- a flake.nix, and the detection code (detectNixEnvironment / isNixAvailable /
+-- the `nix develop` wrapper in module-build.ts) is deleted in the same change.
+-- Every row ever written holds 'system' or NULL, so a constant column: deleted
+-- with the path it described rather than kept as dead weight.
+ALTER TABLE `module_builds` DROP COLUMN `environment`;

package/drizzle/meta/_journal.json

@@ -211,6 +211,13 @@
       "when": 1784400000000,
       "tag": "0029_module_instances",
       "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "6",
+      "when": 1784400000000,
+      "tag": "0030_drop_module_builds_environment",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.14.0",
+  "version": "2.0.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.4.0",
+    "@celilo/capabilities": "^4.0.0",
     "@celilo/cli-display": "^0.2.0",
-    "@celilo/core": "^0.10.0",
+    "@celilo/core": "^0.11.0",
     "@celilo/event-bus": "^0.6.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

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

@@ -116,6 +116,7 @@ describe('publishStaticSite — clientConfig injection', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -160,6 +161,7 @@ describe('publishStaticSite — clientConfig injection', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -187,6 +189,7 @@ describe('publishStaticSite — clientConfig injection', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -223,6 +226,7 @@ describe('publishStaticSite — clientConfig injection', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -251,6 +255,7 @@ describe('publishStaticSite — clientConfig injection', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -289,6 +294,7 @@ describe('registerReverseProxy', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -325,6 +331,7 @@ describe('registerReverseProxy', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -372,6 +379,7 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -407,6 +415,7 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -443,6 +452,7 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -479,6 +489,7 @@ describe('auto-logging — end-to-end through createPublicWeb', () => {
         email: 'admin@example.com',
       },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -535,6 +546,7 @@ describe('register_route — public DNS wiring (D1/M1 #328)', () => {
       logger: noopLogger,
       config: { target_ip: '10.0.10.20/24' },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -562,6 +574,7 @@ describe('register_route — public DNS wiring (D1/M1 #328)', () => {
       logger: noopLogger,
       config: { target_ip: '10.0.10.20/24' },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -593,6 +606,7 @@ describe('register_route — public DNS wiring (D1/M1 #328)', () => {
       logger: noopLogger,
       config: { target_ip: '10.0.10.20/24' },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -613,6 +627,7 @@ describe('register_route — public DNS wiring (D1/M1 #328)', () => {
       logger: noopLogger,
       config: { target_ip: '10.0.10.20/24' },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -637,6 +652,7 @@ describe('register_route — public DNS wiring (D1/M1 #328)', () => {
       logger: noopLogger,
       config: { target_ip: '10.0.10.20/24' },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -663,6 +679,7 @@ describe('register_route — public DNS wiring (D1/M1 #328)', () => {
       // No target_ip and no firewallNatIp → internalDnsIp is falsy.
       config: {},
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',
@@ -693,6 +710,7 @@ describe('register_route — public DNS wiring (D1/M1 #328)', () => {
       logger: noopLogger,
       config: { target_ip: '10.0.10.20/24' },
       secrets: {},
+      convergeStaticContent: async () => {},
       routeOps: ops,
       hostnames: ['www.example.com'],
       caddyModuleId: 'caddy',

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

@@ -10,8 +10,10 @@
  * report counts.
  */
 
+import { hostname } from 'node:os';
 import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
+import { readJailMode } from '../../hooks/jail';
 import { runBuiltinCheckForMonitor } from '../../services/alerting/builtin-source';
 import { loadModuleCoverage } from '../../services/alerting/coverage-source';
 import { modulesInDeployWindow } from '../../services/alerting/deploy-hooks';
@@ -61,6 +63,7 @@ export async function handleAlertsSweep(): Promise<CommandResult> {
         runModuleHealthCheck(moduleId, db, { unattended: true, noInteractive: true }),
       runBuiltinCheck: (category) => runBuiltinCheckForMonitor(category, db),
       loadModuleCoverage: () => loadModuleCoverage(db),
+      loadJailState: () => ({ record: readJailMode(), host: hostname() }),
       now: () => new Date(),
       graceMs: DEFAULT_GRACE_MS,
     },

package/src/cli/commands/monitor.ts

@@ -6,10 +6,12 @@
  * and audit checks into the injectable deps `runOneMonitor` expects.
  */
 
+import { hostname } from 'node:os';
 import { defineEvents, openBus } from '@celilo/event-bus';
 import { getEventBusPath } from '../../config/paths';
 import { getDb } from '../../db/client';
 import type { MonitorKind } from '../../db/schema';
+import { readJailMode } from '../../hooks/jail';
 import {
   isSchedulableBuiltin,
   runBuiltinCheckForMonitor,
@@ -17,6 +19,7 @@ import {
 import { loadModuleCoverage } from '../../services/alerting/coverage-source';
 import { loadModuleHealthCadences } from '../../services/alerting/health-cadence';
 import { HEALTH_COVERAGE_CHECK } from '../../services/alerting/health-coverage';
+import { HOOK_JAIL_CHECK } from '../../services/alerting/hook-jail';
 import {
   createMonitor,
   ensureSweepSubscriber,
@@ -50,6 +53,7 @@ function buildDeps() {
       runModuleHealthCheck(moduleId, db, { unattended: true, noInteractive: true }),
     runBuiltinCheck: (category: DriftCategory) => runBuiltinCheckForMonitor(category, db),
     loadModuleCoverage: () => loadModuleCoverage(db),
+    loadJailState: () => ({ record: readJailMode(), host: hostname() }),
     now: () => new Date(),
     graceMs: DEFAULT_GRACE_MS,
   };
@@ -120,7 +124,10 @@ function handleAdd(args: string[], flags: Record<string, boolean | string>): Com
   // underscore heuristic alone would file it as a module hook against a module
   // that does not exist.
   const kind: MonitorKind =
-    target === HEALTH_COVERAGE_CHECK || isSchedulableBuiltin(target) || target.includes('_')
+    target === HEALTH_COVERAGE_CHECK ||
+    target === HOOK_JAIL_CHECK ||
+    isSchedulableBuiltin(target) ||
+    target.includes('_')
       ? 'builtin_check'
       : 'module_hook';
 
@@ -148,7 +155,13 @@ function handleAdd(args: string[], flags: Record<string, boolean | string>): Com
   const cadence = parseCadence(interval);
   const intervalMinutes = cadence !== null && cadence !== 'manual' ? cadence.minutes : 0;
 
-  createMonitor(db, { kind, target, intervalMinutes });
+  // The hook-jail check is a SELF-monitor: it watches celilo's own confinement
+  // of module hooks, and the alerting spec marks monitors watching the system
+  // itself unsuppressible. That is a property of the target, not an operator
+  // choice — losing the jail during a broad outage is exactly when no ancestor
+  // alert may silence it.
+  const suppressible = target === HOOK_JAIL_CHECK ? false : undefined;
+  createMonitor(db, { kind, target, intervalMinutes, suppressible });
 
   // Creating the first monitor is also what switches the sweep on. Registering
   // here rather than at install means a celilo with no monitors carries no

package/src/cli/commands/system-doctor.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, test } from 'bun:test';
-import { compareVersions } from './system-doctor';
+import type { JailModeRecord } from '../../hooks/jail';
+import {
+  type HookExecutionInput,
+  compareVersions,
+  renderHookExecutionSection,
+} from './system-doctor';
 
 describe('compareVersions', () => {
   test('detects ascending major/minor/patch', () => {
@@ -34,3 +39,118 @@ describe('compareVersions', () => {
     expect(compareVersions('v1.2.3', '1.2.3')).toBe(0);
   });
 });
+
+describe('renderHookExecutionSection (hook-process-boundary task 4.6)', () => {
+  const HOST = 'celilo-mgr';
+  const jailedRecord: JailModeRecord = {
+    mode: 'jailed',
+    backend: 'bubblewrap',
+    host: HOST,
+    recordedAt: '2026-08-28T09:00:00.000Z',
+  };
+  const regressedRecord: JailModeRecord = {
+    mode: 'unjailed',
+    backend: 'none',
+    reason: 'bubblewrap is installed but could not build a namespace, so hooks run unjailed.',
+    host: HOST,
+    recordedAt: '2026-08-28T09:00:00.000Z',
+    lastJailed: { backend: 'bubblewrap', recordedAt: '2026-08-27T09:00:00.000Z' },
+  };
+
+  const render = (over: Partial<HookExecutionInput>) =>
+    renderHookExecutionSection({
+      availability: { backend: 'bubblewrap' },
+      policy: 'auto',
+      record: jailedRecord,
+      host: HOST,
+      monitored: true,
+      ...over,
+    });
+
+  const text = (r: { lines: string[] }) => r.lines.join('\n');
+
+  test('a jailing host is a ✔ and nothing more', () => {
+    const r = render({});
+    expect(text(r)).toContain('hooks run jailed (bubblewrap)');
+    expect(r.failCount).toBe(0);
+    expect(r.warnCount).toBe(0);
+  });
+
+  test('unjailed says why in the reason sentence, as a warning and not a failure', () => {
+    const r = render({
+      availability: {
+        backend: 'none',
+        reason:
+          'bubblewrap is not installed, so hooks run unjailed. Install it (`apt install bubblewrap`) and re-run.',
+      },
+      record: undefined,
+      monitored: null,
+    });
+    expect(text(r)).toContain('hooks run unjailed — bubblewrap is not installed');
+    expect(text(r)).toContain('no execution mode recorded yet');
+    expect(r.warnCount).toBe(1);
+    expect(r.failCount).toBe(0);
+  });
+
+  test('CELILO_HOOK_JAIL=off is reported as the operator’s own act', () => {
+    const r = render({ policy: 'off', record: undefined });
+    expect(text(r)).toContain('CELILO_HOOK_JAIL=off');
+    expect(r.warnCount).toBe(1);
+  });
+
+  test('auto deferral on sandbox-exec reads as unjailed, not jailed (ce-29z)', () => {
+    // The doctor and the executor share one predicate (autoJailDefers), so
+    // the doctor cannot report a jail the executor will not build. When D14
+    // lands and the flag flips, this goes back to ✔ with no code change here.
+    const r = render({ availability: { backend: 'sandbox-exec' }, record: undefined });
+    expect(text(r)).toContain('hooks run unjailed — macOS hooks run unjailed');
+    expect(text(r)).not.toContain('hooks run jailed');
+    expect(r.warnCount).toBe(1);
+    expect(r.failCount).toBe(0);
+  });
+
+  test('required with no backend is a failure, because every hook fails', () => {
+    const r = render({
+      policy: 'required',
+      availability: { backend: 'none', reason: 'the profile did not load' },
+      record: undefined,
+    });
+    expect(text(r)).toContain('CELILO_HOOK_JAIL=required and no jail is available');
+    expect(r.failCount).toBe(1);
+  });
+
+  test('a host that used to jail and has stopped is a failure naming when', () => {
+    const r = render({
+      availability: { backend: 'none', reason: 'the profile did not load' },
+      record: regressedRecord,
+    });
+    expect(text(r)).toContain('ran hooks jailed (bubblewrap) until 2026-08-27T09:00:00.000Z');
+    expect(r.failCount).toBe(1);
+  });
+
+  test('an unmonitored regression points at the self-monitor', () => {
+    const r = render({
+      availability: { backend: 'none', reason: 'the profile did not load' },
+      record: regressedRecord,
+      monitored: false,
+    });
+    expect(text(r)).toContain('celilo monitor add hook_jail');
+  });
+
+  test('a jailing but unmonitored host is told the transition alerts only if monitored', () => {
+    const r = render({ monitored: false });
+    expect(text(r)).toContain('celilo monitor add hook_jail');
+    expect(r.failCount).toBe(0);
+  });
+
+  test('a dev box with no DB gets no monitor hint', () => {
+    const r = render({ monitored: null });
+    expect(text(r)).not.toContain('monitor add');
+  });
+
+  test("another host's record reads as a move, not this host's history", () => {
+    const r = render({ record: { ...regressedRecord, host: 'old-box' } });
+    expect(text(r)).toContain('belongs to host "old-box"');
+    expect(r.failCount).toBe(0);
+  });
+});