@celilo/cli 1.4.0 → 1.6.0

package/CELILO_SUBSYSTEMS.md

@@ -29,7 +29,7 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 - **Zone detection / system config** — `apps/celilo/src/services/zone-detector.ts` — `detectZoneFromIp` reads `network.<zone>.subnet` from the `systemConfig` table and returns `NetworkZone | 'unknown'`. It answers CONTAINMENT ONLY. It used to return `'external'` on no-match, which conflated "no declared subnet contains this" with "the internet can route to this" — on a firewall with five RFC1918 legs that reported four of them as facing the internet. `'unknown'` is the honest answer; the caller resolves it (see `machine add`: publicly routable → `external`, otherwise fail asking for `--zone`). The subnet-backed zone list is derived from `NETWORK_ZONES` minus `external`, which has no subnet and must never be given one.
 - **Interface classification** — `packages/capabilities/src/interface-classification.ts` — THE shared classifier, used by the backend and every firewall provider module so the two cannot drift apart again. `isPubliclyRoutable(ip)` is a property of the address alone (false for RFC 1918, RFC 6598 carrier-grade NAT, loopback, link-local, multicast, reserved). `classifyInterfaces(interfaces, zones)` assigns each interface `zone → external → alien`, first match winning, where `external` is the RESIDUAL — routable and claimed by no declared zone — and is never subnet-matched. `externalEdge()` returns none/single/**ambiguous** rather than silently picking the first public address. `defaultRouteFinding()` enforces the invariant that the default route leaves through `internal` or `external`. **`subnetContains(cidr, ip)` lives here and is the ONLY implementation** — three existed and disagreed (the backend's mishandled `/0`); the other two are deleted, not aliased. Design: `openspec/changes/firewall-interface-classification/design.md`.
 - **Declared networks (classification input)** — `readDeclaredNetworks(db)` in `apps/celilo/src/hooks/capability-loader.ts` — every `network.<name>.subnet` in system config, which is what an interface is attributed against. Read from the CONFIG, not from `NETWORK_ZONES`: celilo holds networks that are not placement zones (`network.control-plane-vpn.subnet`, which `wireguard` requires and reads). Injected into the firewall capability as a LIVE reader (`declaredNetworks`) — that liveness was a mitigation for values written mid-run by a module hook, which `network-declaration` removes; see that spec before assuming a snapshot is still unsafe.
-- **Network requirement + ensure (celilo owns the namespace)** — `apps/celilo/src/services/network-ensure.ts` (`ensureRequiredNetworks`), `NetworkRequirementSchema` / `getRequiredNetworkNames` in `apps/celilo/src/manifest/schema.ts`. A module declares `requires.networks: [{name}]` — a NAME, never a value; the schema is `.strict()` so a `subnet:` on the requirement is rejected with a message saying why. The deploy calls `ensureRequiredNetworks` in its interview phase, BEFORE generation and before any hook, and asks over the generic bus interview (`askText`, so it is answerable headless) for anything undefined. Which attributes a network has is celilo's answer, taken from `apps/celilo/schemas/system_config.json`: that file declares `network.<n>.gateway` for the routed segments and omits it for `control-plane-vpn`, so a gateway is never asked for a network that has none. Well-known names carry a `suggested` range there — deliberately NOT `default`, which `getDefaultConfiguration()` would seed at `system init`. Spec: `openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md`.
+- **Network requirement + ensure (celilo owns the namespace)** — `apps/celilo/src/services/network-ensure.ts` (`ensureRequiredNetworks`), `NetworkRequirementSchema` / `getRequiredNetworkNames` in `apps/celilo/src/manifest/schema.ts`. A module declares `requires.networks: [{name}]` — a NAME, never a value; the schema is `.strict()` so a `subnet:` on the requirement is rejected with a message saying why. The deploy calls `ensureRequiredNetworks` in its interview phase, BEFORE generation and before any hook, and asks over the generic bus interview (`askText`, so it is answerable headless) for anything undefined. Which attributes a network has is celilo's answer, taken from `apps/celilo/schemas/system_config.json`: that file declares `network.<n>.gateway` for the routed segments and omits it for `control-plane-vpn`, so a gateway is never asked for a network that has none. Well-known names carry a `suggested` range there — deliberately NOT `default`, which `getDefaultConfiguration()` would seed at `system init`. Spec: `openspec/specs/network-declaration/spec.md`.
 - **The network write path (closed) + celilo's own discovery** — `celilo system apply-config` (`apps/celilo/src/cli/commands/system-apply-config.ts`) REFUSES the whole `network.` namespace, `network.bridge` excepted (a Proxmox bridge name is not addressing, and it is the one network key with a schema default). That is the automation surface a module hook shells out to, so closing it there is what makes "networks are celilo's" an authority rather than a convention every module has to remember. The refusal names the alternative — declare the network, read it with `$system:` — because a bare rejection sends a module author hunting for a typo. The one write that legitimately needed the surface moved INTO celilo: `celilo system discover-network` (`apps/celilo/src/services/network-discovery.ts`, `cli/commands/system-discover-network.ts`) parses the box's own `ip route` and records `network.internal.*` — or `network.secure-mgmt.*` when the box is off the internal LAN (#300). `celilo-mgmt` calls it and decides nothing; it used to parse and write this itself. Idempotent and never overwrites addressing already set. Recurrence gate: `test-integration/module/no-module-writes-networks.test.ts`.
 - **Firewall interface audit** — `apps/celilo/src/services/audit/interface-classification.ts` — reports per-firewall classification in `celilo audit`: alien interfaces by name and address (drift), and the blocking findings a converge refuses on — a carrier-grade NAT leg, an ambiguous external edge, a default route on the wrong leg.
 - **Zone taxonomy (canonical list)** — `apps/celilo/src/db/schema.ts` — `NETWORK_ZONES` is the single array; `NetworkZone` is DERIVED from it. Never hand-maintain a second copy: a duplicate that dropped a member made zone validation return null and silently fall back to a wrong-but-valid zone.
@@ -96,7 +96,8 @@ Module hooks reach a remote box ONLY through these typed primitives
 (exported from `packages/capabilities/src/index.ts`).
 
 - **`remoteExec`** — the ONE ssh seam (`ssh <user>@<target> <cmd>`); everything else builds on it. `user`/`port`/`identityFile` on the target default to `root`/22/the agent key, so a fleet call is unchanged; an OFF-FLEET account (`external_web`) sets them.
-- **`probe`** — read-only health checks: `systemd` / `http` / `command`.
+- **`probe`** — read-only health checks over SSH: `systemd` / `command`. It carried a third `http` kind that SSHed in and ran `curl`; the production `ubuntu-22.04-standard` LXC ships none, and a missing binary was indistinguishable from a dead service. Deleted — `probeHttp` replaces it (`openspec/changes/probe-http-from-management/`).
+- **`probeHttp`** — HTTP health check run FROM the management server over `fetch`; nothing on the target. Takes `port` + `path`, never a URL, and builds the address from the target's `ipv4_address` — so a check cannot name `localhost` and silently probe celilo-mgr's own port. Redirects observed, not followed (caddy's 308 is a healthy answer). Typed failure: `'unreachable'` vs `'status'`.
 - **`serviceCtl`** — systemctl start/stop/restart/reload/enable/disable.
 - **`runAppCommand` / `runAppCommandWithSecret`** — escape-hatch on-box command; the secret variant feeds the secret on **stdin** (`$SECRET`), never argv.
 - **`streamBackup` / `streamRestore` / `fetchFile` / `pushFile`** — binary-safe streaming via local shell redirect/pipe.
@@ -181,7 +182,7 @@ runner seam (`execRunner` real / `createMockRunner` for tests) lives in
   - **Inbound** (`reconcileAspectsForSystems`): every approved aspect applied to systems that have just come into existence. Called from `module-deploy.ts` between `waitForSSH` and `executeAnsible` (so a module's playbook and `on_install` see a correctly configured host) and from `machine-add.ts`. Eligibility is `applicable_zones` + approval; the aspect's `triggers` list is deliberately NOT consulted, so convergence is not opt-in per manifest. A failure here IS fatal to the deploy that created the system — the aspect is a prerequisite of that host — while a failure on `machine add` is only a warning. PAUSED providers are skipped, which is the escape hatch for a wedged aspect. Nothing is rolled back: rows, guest and IPAM allocation persist and a re-run converges on the same system. Fixes celilo#902, where a system provisioned after its provider deployed silently never received the aspect. See `openspec/changes/aspect-fanout-new-systems/`.
   - **Coverage verification** — `verifyAspectCoverage` + `celilo system doctor --deep [--fix]`. Answers "is any system missing an aspect its zone entitles it to" WITHOUT stored state: the entitled set is `planAspectFanOut` itself, and coverage is measured by evaluating the role against the host in Ansible check mode (`executeAnsible({check:true})` + `parseAnsibleRecap`). Three outcomes, not two — `changed=0,skipped=0` applied, `changed>0` missing, **`skipped>0` unknown**, because check mode SKIPS a task it cannot evaluate and a `command`/`shell` role would otherwise report clean having never run.
 - **In-flight operation lock** — `apps/celilo/src/services/module-operations.ts` — `startOperation`/`completeOperation`/`failOperation` record deploy/uninstall/backup/restore in `module_operations`; `refuseIfInFlight`/`checkInFlight` are what backup and restore consult. Deploy and uninstall REGISTER but never check: it is a one-way guard protecting backup/restore consistency, not a general mutex (`openspec/specs/management-server-backup/spec.md` "In-flight operation refusal"). A row stops holding the lock once it is GONE, STOPPED/zombie (`isPidRunnable`, `ps -o state=` — `kill(pid,0)` calls a Ctrl-Z'd process alive), or older than `OPERATION_TTL_MS` (2h). The TTL is not redundancy: a pid is a recycled number, and once the pid space wraps an old row names an unrelated healthy process. Operator surface: `celilo module operations [list|clear] [--abandoned] [--all]` (`apps/celilo/src/cli/commands/module-operations.ts`); `list` shows only what holds the lock, abandoned rows are summarised unless `--abandoned`. Abandoned rows are reclaimed hourly by the `celilo-operations-sweep` bus subscriber (`timer.tick.1h` → `celilo module operations clear`, armed by `ensureOperationsSweepSubscriber` from module registration and `celilo system migrate`). `clear` MARKS rows failed rather than deleting them, and that is load-bearing: the `abandoned_operations` audit reads exactly those released rows to notice one module's operation dying over and over.
-- **Module pause / unpause (control-plane quiescence)** — `apps/celilo/src/services/module-pause.ts` — pure `planPause`/`planUnpause` producing an ordered plan, `executePause`/`executeUnpause` performing it, plus `listPausedModules`/`pausedAmong`/`formatPausedDuration`/`describePausedModule` (the ONE place an age is formatted). CLI: `apps/celilo/src/cli/commands/module-pause.ts` (`celilo module pause|unpause <id> [--cascade] [--stop-infra] [--reason] [--dry-run] [--yes]`). Pausing takes a module out of the CONTROL plane — no dispatched events, no timer hooks, no health checks, alerts suppressed — while leaving the DATA plane running, because capability consumption is deploy-time: every consumer calls `firewall`/`dhcp_server` from `on_install` and nothing calls it while serving. Config, secrets, IPAM/VMID and placement are preserved; `on_uninstall` does NOT run. Quiescence is enforced in two places: pausing drops the module's bus subscriptions (`unregisterModuleSubscriptions`), and `run-named-hook.ts` refuses any non-lifecycle hook for a PAUSED module (`skippedPaused`), which catches the paths that skip the bus — `events resync-subscriptions`, a restore that starts events.db empty, aspect fan-out, public-web republish. `on_install`/`on_uninstall` are exempt by hook NAME (not a caller flag): unpause redeploys through `on_install`, and removing a paused provider needs `on_uninstall`. Unpause always REDEPLOYS (`deployModule`) — that is what rebinds a consumer to a replacement provider and recreates provider-local state from the consumers that own it — and re-registers subscriptions, which a plain deploy does not do. A failed unpause restores `PAUSED` rather than leaving the module live and mis-bound. Cascade order reuses `services/update/dep-graph.ts` unchanged (pause = consumers first, unpause = providers first) and is computed from the GRAPH, never from which modules are currently paused, so a cascade walks THROUGH already-done members and is resumable. See `openspec/changes/module-pause-lifecycle/`.
+- **Module pause / unpause (control-plane quiescence)** — `apps/celilo/src/services/module-pause.ts` — pure `planPause`/`planUnpause` producing an ordered plan, `executePause`/`executeUnpause` performing it, plus `listPausedModules`/`pausedAmong`/`formatPausedDuration`/`describePausedModule` (the ONE place an age is formatted). CLI: `apps/celilo/src/cli/commands/module-pause.ts` (`celilo module pause|unpause <id> [--cascade] [--stop-infra] [--reason] [--dry-run] [--yes]`). Pausing takes a module out of the CONTROL plane — no dispatched events, no timer hooks, no health checks, alerts suppressed — while leaving the DATA plane running, because capability consumption is deploy-time: every consumer calls `firewall`/`dhcp_server` from `on_install` and nothing calls it while serving. Config, secrets, IPAM/VMID and placement are preserved; `on_uninstall` does NOT run. Quiescence is enforced in two places: pausing drops the module's bus subscriptions (`unregisterModuleSubscriptions`), and `run-named-hook.ts` refuses any non-lifecycle hook for a PAUSED module (`skippedPaused`), which catches the paths that skip the bus — `events resync-subscriptions`, a restore that starts events.db empty, aspect fan-out, public-web republish. `on_install`/`on_uninstall` are exempt by hook NAME (not a caller flag): unpause redeploys through `on_install`, and removing a paused provider needs `on_uninstall`. Unpause always REDEPLOYS (`deployModule`) — that is what rebinds a consumer to a replacement provider and recreates provider-local state from the consumers that own it — and re-registers subscriptions, which a plain deploy does not do. A failed unpause restores `PAUSED` rather than leaving the module live and mis-bound. Cascade order reuses `services/update/dep-graph.ts` unchanged (pause = consumers first, unpause = providers first) and is computed from the GRAPH, never from which modules are currently paused, so a cascade walks THROUGH already-done members and is resumable. See `openspec/specs/module-pause/spec.md`.
 - **Provider-removal guard** — `apps/celilo/src/services/remove-guard.ts` — `findRemovalBlockers`/`describeRemovalRefusal`, called from `apps/celilo/src/cli/commands/module-remove.ts`. A PAUSED module is not a dependent (unpause cannot return it to service without a redeploy, and a redeploy re-resolves capabilities), which is what makes a provider swap possible at all. A dependent is one declaring the capability under `requires` **or** `optional` — the same relation `dep-graph.ts` uses, so the guard and the cascade agree on the set; the guard previously read `requires` alone, which let a removal silently orphan `technitium`'s `optional` `dhcp_server`. Refusals name each blocker AND which declaration makes it one. It deliberately does NOT exempt a dependent because another provider of the same capability exists (celilo#683).
 - **Consumer-removal cleanup (every provider is told)** — `apps/celilo/src/services/consumer-cleanup.ts` — pure `planConsumerCleanup` + `loadConsumerCleanupPlan` + `runConsumerCleanup`, called from `apps/celilo/src/cli/commands/module-remove.ts` after `on_uninstall` and before `terraform destroy`. A capability is two-sided: the consumer asks, the provider mints something in ITS world (a caddy site block, a DNAT rule, an OIDC client at authentik, a registered CI runner), and removal only ever touched one side — the FK cascade dropped celilo's row, so the provider's next converge had no way to learn the thing existed. This dispatches the `on_consumer_removed` hook to every provider of every capability the departing module declared under `requires` OR `optional` (the same relation `remove-guard.ts` counts as a dependency edge), **once per provider** rather than once per capability, sorted by provider id. The hook receives one input, `consumer`, and NOTHING else: a provider that cannot answer "what do I hold for this module" without being told has a different defect — the consumer's id was never recorded at mint time. It replaces `services/web-route-cleanup.ts`, which did the same job for exactly one capability, by name, from core. Semantics that are easy to get backwards: **a failed withdrawal never blocks the removal** — the consumer goes and the failing PROVIDER is marked `ERROR` with the departing consumer named in `error_message` (surfaced as a `blocked` finding by `services/audit/undeployed-modules.ts`), because the hook is a full converge and after a failure the provider's state is unknown rather than "one thing missed". **Dispatch continues past a failure**, so one broken provider cannot leave the others holding state. A PAUSED provider is skipped with a warning naming what it keeps (`run-named-hook.ts` refuses non-lifecycle hooks on a paused module, and `on_consumer_removed` must NOT join `LIFECYCLE_HOOKS`), and a never-deployed one is skipped silently. Providers implementing it: caddy, caddy-internal, iptables, greenwave, axon, authentik, forgejo, generic-cpanel-hosting-provider. See `openspec/changes/consumer-removal-cleanup/`.
 - **Firewall registry ownership** — `apps/celilo/src/services/port-forwards.ts` + `apps/celilo/src/services/trusted-sources.ts`. Both stores are bound to the CONSUMING module and stamp `registered_by` themselves; a caller cannot supply it, so a registration is never attributed to the wrong module. Both writes are **declarative**: `replace()` states a consumer's COMPLETE set for a target, so a port or subnet it previously registered and now omits is withdrawn (celilo#855 — before this, a module that exposed `:8080` and redeployed exposing `:9090` kept both, forever). The owner is IN both unique indexes, not merely beside them: two consumers wanting the same forward are two ROWS, so one leaving cannot delete a rule the other still needs; `modules/iptables/scripts/ruleset-renderer.ts` dedupes on the rule tuple so the pair renders once. Neither column is a FK, so `runConsumerCleanup` deletes these rows explicitly after every provider has converged without them.
@@ -226,13 +227,26 @@ to look, which is how a forgotten pause actually gets found.
 
 ## Packaging, registry & publish
 
-- **Module packaging** — `apps/celilo/src/module/packaging/` — `build.ts` (`buildModule`), `extract.ts`, `checksum.ts`, `signature.ts` (`signChecksums`/`verifySignature`), `release-metadata.ts`, `audit.ts`.
+- **Module packaging** — `apps/celilo/src/module/packaging/` — `build.ts` (`buildModule`), `extract.ts`, `checksum.ts`, `signature.ts` (`signChecksums`/`verifySignature`), `release-metadata.ts`, `audit.ts`, `package-rules.ts`, `generated-plane.ts`, `host-plane.ts` (see **Module integrity** below).
 - **Publish driver** — `scripts/publish.ts` shims to `apps/celilo/src/cli/commands/publish/` (workspace npm packages via `bun publish` + module registry; preflight stale-version/stale-manifest gates).
 - **Registry publish-token admin (append-safe)** — `apps/celilo/src/cli/commands/registry-token.ts` — `celilo registry token add/rm <token>` read-modify-write the celilo-registry `publish_tokens` secret (newline-separated bootstrap/admin list). Avoids the `module secret set` full-overwrite that clobbered other holders. Runs on-mgr where the master key lives; runtime-minted scoped tokens are handled separately by the registry-server.
 - **Contributor identity tokens (idp-issued, per-user)** — `apps/celilo/src/cli/commands/token.ts` — `celilo token obtain|list|revoke` mints/lists/revokes per-user API tokens via the `idp` capability (`create_token`/`list_tokens`/`revoke_token` on authentik). A module contributor authenticates publishes AS THEMSELVES (SECURE_MODULE_PUBLISH.md §6) — no admin/shared token on their machine; the token feeds `celilo author init`. Shown once at mint; the idp stores it hashed, celilo persists nothing. Runs on-mgr where the idp provider lives. Distinct from `registry token add/rm` (raw bootstrap list, different trust model).
 - **Registry token verification (opaque + idp introspection)** — `packages/registry-server/src/auth.ts` (`TokenAuth` — opaque SHA-256 publish tokens, admin/per-package scope) + `packages/registry-server/src/introspection.ts` (`IntrospectionVerifier` — RFC 7662 verify-bridge, SECURE_MODULE_PUBLISH.md §5[D-A]). `authorizePackage()` in `server.ts` tries the opaque set first (unchanged), then, for a token unknown to it, `identify()`s it via the idp introspection endpoint using the registry's confidential OIDC client creds (`OIDC_INTROSPECTION_ENDPOINT`/`OIDC_CLIENT_ID`/`OIDC_CLIENT_SECRET`, provisioned on install — ce-7aa), reading `{active, sub, groups, exp}`. Fails CLOSED on any introspection error; never logs tokens/secrets. Instant revocation: revoke at the idp → next publish sees `active:false` → 401.
 - **Registry module-owner table (hybrid group + owner authz — ce-1ch, D-C)** — `packages/registry-server/src/module-owner-store.ts` (`ModuleOwnerStore` — JSON-persisted `{moduleName, ownerSub, claimedAt, sourceGroup}`, `REGISTRY_OWNERS_FILE`/`dataDir/module-owners.json`). The verified `groups` claim gates *whether* an identity may publish (`REGISTRY_ADMIN_GROUP`→publish/reassign anything; `REGISTRY_PUBLISHER_GROUP`, default `celilo-authors`, configurable→claim+publish owned); the owner table gates *which names*. First-publish-claims: the first verified publisher of an unclaimed name owns it; a *different* publisher is then DENIED (confused-deputy defense — Author-A cannot publish Author-B's module). Admin HTTP endpoints `GET /api/v1/modules/owners`, `GET|POST /api/v1/modules/owners/{name}` (reassign). Operator front door: `celilo registry owner list|show|set` (`apps/celilo/src/cli/commands/registry-owner.ts`), admin token resolved from the local `publish_tokens` bootstrap list.
 
+## Module integrity (the four places a module exists)
+
+A module exists in four places at once, and celilo verifies the correspondence
+between them. Design: `openspec/changes/module-integrity-rigor/design.md`.
+
+- **The one classifier** — `apps/celilo/src/module/packaging/package-rules.ts` — `classifyModulePath(relPath)` returns `package` / `derived` / `unknown` and is the SINGLE answer to what belongs to a module. `build.ts#shouldExclude`, `extract.ts#scanDirectory`, `import.ts#copyModuleFiles`, `module-update.ts` and `audit.ts` all route through it. Composes with, and does not restate, `includeNodeModulesPath` (ISS-0046).
+- **The versioned baseline** — `moduleIntegrity` in `apps/celilo/src/db/schema.ts` — checksums PLUS the `version` they describe. Upserted by `module import` and written by `module-update.ts#updateOne`, so it tracks the installed version instead of freezing at first import. `version` is nullable: NULL means "written before celilo stamped versions", which verify reports rather than papers over.
+- **Plane 1, installed tree vs baseline** — `apps/celilo/src/module/packaging/audit.ts` — `auditModule(moduleId, db, { deep })`. The entry point for `module verify`.
+- **Plane 2, generated project vs installed tree** — `apps/celilo/src/module/packaging/generated-plane.ts` — `compareVerbatimRoleAssets` (pure), `readVerbatimRoleAssets`, `refuseIfGeneratedIsStale`. Only `ansible/roles/<role>/files/**` has a meaningful expected digest; Ansible templates the rest. Wired into `module verify` and into `module-deploy.ts` as a pre-flight that refuses BEFORE contacting any system (celilo#925).
+- **Plane 3, host vs generated project** — `apps/celilo/src/module/packaging/host-plane.ts` — `verifyModuleOnHosts` runs the generated playbook through `executeAnsible(..., { check: true })` and classifies each `PLAY RECAP` line as `converged` / `drift` / `unmeasured`. One SSH per system, so `--deep` only. A module opts out with `verify: { deep: false, reason: … }`; the reason is required and is printed.
+- **Surfaces** — `celilo module verify <id> [--deep] [--json]` (`apps/celilo/src/cli/commands/module-verify.ts`), the `module_integrity` audit category (`apps/celilo/src/services/audit/module-integrity.ts`), and `system doctor`'s fleet section. Same implementation behind all three.
+- **Dead convergence machinery** — `apps/celilo/src/services/audit/detect-without-converge.ts` — the `detect_without_converge` category reports a module declaring a `reconcile_*` / `refresh_registrations` / `reassert_dhcp_dns` hook that no subscription ever fires (celilo#934).
+
 ## Alerting & notifications
 
 Observation and delivery: monitors run checks on a schedule, alerts hold what

package/MODULE_PRIMITIVES.md

@@ -64,12 +64,25 @@ that, not a primitive. The primitives are for the module's *own* box.
 ### `probe(target, check, runner?, opts?) → { healthy, detail }`
 Read-only health check. Never mutates. `check` is one of:
 - `{ kind: 'systemd', unit }` — unit is `active`.
-- `{ kind: 'http', url, expectStatus?, headers? }` — curl runs **on the box**, so
-  it doesn't depend on Caddy/public DNS. `expectStatus` defaults to 200; pass a
-  list (e.g. `[200, 308]`) or `headers: { Host: 'app.example.com' }` for a vhost.
 - `{ kind: 'command', command, expectStdoutIncludes? }`.
+
+For HTTP use `probeHttp`, not `probe` — see below.
+```ts
+probe(sys, { kind: 'systemd', unit: 'caddy' }, run);
+```
+
+### `probeHttp(target, { port, path?, expectStatus?, headers?, timeoutMs? }) → Promise<{ healthy, detail, failure? }>`
+HTTP health check, run **from the management server** over `fetch`. Nothing runs
+on the target — no SSH, no curl (the production LXC image ships none, and a
+missing binary used to be indistinguishable from a dead service). There is
+deliberately **no `url`**: you give a port and a path, and the primitive builds
+the address from the target's `ipv4_address`, so a check cannot name `localhost`
+and end up probing celilo-mgr itself. `expectStatus` defaults to 200; pass a
+list (e.g. `[200, 308]`) or `headers: { Host: 'app.example.com' }` for a vhost.
+Redirects are **observed, not followed**. On failure, `failure` is
+`'unreachable'` (could not connect) or `'status'` (answered with the wrong code).
 ```ts
-probe(sys, { kind: 'http', url: 'http://localhost', headers: { Host: fqdn }, expectStatus: [200, 308] }, run);
+await probeHttp(sys, { port: 80, headers: { Host: fqdn }, expectStatus: [200, 308] });
 ```
 
 ### `serviceCtl(target, unit, action, runner?, opts?) → RunResult`
@@ -97,11 +110,11 @@ applyRenderedConfig({
 
 ### `waitFor(predicate, { attempts?, intervalMs?, onAttempt? }) → Promise<boolean>`
 Poll an async predicate until true or exhausted (default 30 × 5s). A combinator —
-it never touches the remote; wrap a `probe`/`runAppCommand` thunk. Use
+it never touches the remote; wrap a `probe`/`probeHttp`/`runAppCommand` thunk. Use
 `onAttempt` to emit a heartbeat so a long wait doesn't trip the hook idle-timeout.
 Never `sleep`.
 ```ts
-await waitFor(() => probe(sys, { kind: 'http', url }, run).healthy,
+await waitFor(async () => (await probeHttp(sys, { port: 3000 })).healthy,
   { onAttempt: (n) => logger.info(`waiting… ${n * 5}s`) });
 ```
 

package/drizzle/0026_module_integrity_version.sql

@@ -0,0 +1,20 @@
+-- The integrity baseline records WHICH VERSION its checksums describe
+-- (openspec/changes/module-integrity-rigor, D1).
+--
+-- Without it `module verify` cannot distinguish "the files are old" from "the
+-- checksums are old", and it reported the same violations either way. The row
+-- was written once, by a plain INSERT on a UNIQUE column inside a try/catch
+-- that only warned, and `module update` never touched the table at all — so a
+-- module imported once and updated ten times still carried its first import's
+-- checksums, and every file that had legitimately changed since read as
+-- [MODIFIED]. That was the whole of the manifest.yml / README.md / scripts/*
+-- block in the fleet's 47- and 25-violation outputs.
+--
+-- NULLABLE on purpose, and this is the Rule 3.4 exception rather than a missing
+-- default: NULL means "written before celilo stamped versions", which is a
+-- fact verify must be able to state. A default of '' or of the module's current
+-- version would fabricate a correspondence nobody measured — exactly the
+-- failure this change exists to remove. Existing rows keep NULL until the next
+-- `module import` or `module update` rewrites them.
+
+ALTER TABLE `module_integrity` ADD `version` text;

package/drizzle/meta/_journal.json

@@ -183,6 +183,13 @@
       "when": 1784100000000,
       "tag": "0025_port_forward_owner",
       "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "6",
+      "when": 1784200000000,
+      "tag": "0026_module_integrity_version",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.4.0",
+  "version": "1.6.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": "^2.2.0",
+    "@celilo/capabilities": "^2.3.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.9.0",
     "@celilo/event-bus": "^0.6.0",

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

@@ -13,9 +13,12 @@
 import type { CommandResult } from '../types';
 import { moduleVerify } from './module-verify';
 
-export async function moduleAudit(args: string[]): Promise<CommandResult> {
+export async function moduleAudit(
+  args: string[],
+  flags: Record<string, string | boolean> = {},
+): Promise<CommandResult> {
   process.stderr.write(
     'warning: `celilo module audit` is deprecated; use `celilo module verify` instead.\n',
   );
-  return moduleVerify(args);
+  return moduleVerify(args, flags);
 }

package/src/cli/commands/module-update.test.ts

@@ -5,9 +5,9 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { type DbClient, getDb } from '../../db/client';
 import { modules } from '../../db/schema';
@@ -321,3 +321,91 @@ describe('registry sweep — an unanswered breaking update is not a decline', ()
     expect(getDb().select().from(modules).all()[0].version).toBe('1.0.2+9');
   });
 });
+
+/**
+ * Every file under `root`, keyed by relative path, valued by its exact bytes.
+ * Compared whole so a TRUNCATION shows up — an existence check would not.
+ */
+function snapshot(root: string, dir = root): Record<string, string> {
+  const files: Record<string, string> = {};
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) Object.assign(files, snapshot(root, full));
+    else if (entry.isFile()) files[relative(root, full)] = readFileSync(full, 'utf-8');
+  }
+  return files;
+}
+
+describe("updateOne — pointed at the module's own installed path", () => {
+  let tempDir: string;
+  let installedDir: string;
+  let db: DbClient;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-selfpath-'));
+    process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+    process.env.CELILO_ORIGINAL_CWD = tempDir;
+
+    installedDir = join(tempDir, 'installed', 'selfmod');
+    mkdirSync(installedDir, { recursive: true });
+    writeFileSync(
+      join(installedDir, 'manifest.yml'),
+      `celilo_contract: "1.0"
+id: selfmod
+name: Self Module
+version: 1.0.0
+description: fixture
+`,
+    );
+
+    db = getDb();
+    db.insert(modules)
+      .values({
+        id: 'selfmod',
+        name: 'Self Module',
+        sourcePath: installedDir,
+        version: '1.0.0',
+        manifestData: {
+          celilo_contract: '1.0',
+          id: 'selfmod',
+          name: 'Self Module',
+          version: '1.0.0',
+        },
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    process.env.CELILO_DB_PATH = undefined;
+    process.env.CELILO_ORIGINAL_CWD = undefined;
+  });
+
+  test('refuses by name, and writes NOTHING', async () => {
+    // A data-loss guard, not a UX nicety. On celilo-mgr on 2026-08-19,
+    // `celilo module update /var/celilo/modules/wireguard-manager` threw
+    // `EINVAL: copy_file_range` and TRUNCATED
+    // `ansible/roles/wireguard-manager/handlers/main.yml` in the module source
+    // on the way down. The crash was mid-copy, so the tree was left damaged
+    // rather than untouched. It stayed invisible for nine hours because
+    // `generated/` still held a good copy; the next generate propagated the
+    // truncation, and the deploy after that died with "The requested handler
+    // 'Restart wireguard-manager' was not found". App health, ingress and
+    // tunnel peers were all green throughout — none of them can see a
+    // truncated Ansible handler.
+    //
+    // So this compares the whole tree byte for byte rather than checking that
+    // a file still exists. "It threw" was already true of the behaviour that
+    // caused the damage, and an existence check cannot see a truncation.
+    const before = snapshot(installedDir);
+
+    const result = await updateOne(installedDir, db, {}, { quiet: true });
+
+    expect(result.status).toBe('failed');
+    if (result.status !== 'failed') return;
+    expect(result.error).toContain('IS the installed copy of selfmod');
+    expect(result.error).not.toContain('EINVAL');
+
+    expect(snapshot(installedDir)).toEqual(before);
+  });
+});

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

@@ -9,18 +9,20 @@
  * The module ID is read from the manifest at the given path.
  */
 
-import { cpSync, existsSync, readFileSync, readdirSync } from 'node:fs';
+import { cpSync, existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { join, relative, resolve } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { parse as parseYaml } from 'yaml';
 import { registerModuleCapabilities } from '../../capabilities/registration';
 import { getDb } from '../../db/client';
-import { capabilities, modules } from '../../db/schema';
+import { capabilities, moduleIntegrity, modules } from '../../db/schema';
 import { ModuleManifestSchema } from '../../manifest/schema';
 import type { ModuleManifest } from '../../manifest/schema';
+import { computeChecksums } from '../../module/packaging/build';
 import { cleanupTempDir, extractPackage } from '../../module/packaging/extract';
+import { classifyModulePath } from '../../module/packaging/package-rules';
 import { RegistryClient } from '../../registry/client';
 import { askConfirm, withInterviewSession } from '../../services/bus-interview';
 import { InterviewAbandonedError, InterviewUnansweredError } from '../../services/interview-errors';
@@ -152,6 +154,30 @@ export async function fetchAndUpdate(
 /**
  * Upgrade a single module from a source path
  */
+/**
+ * Every file under an installed module that an update is entitled to remove:
+ * `package` (the new version decides whether it survives) and `unknown` (no
+ * version ever shipped it, so it self-heals a tree an older update polluted).
+ *
+ * `derived` is neither walked nor removed. It is celilo's or the operator's —
+ * `generated/`, the hook runtime closure, `screenshots/`, `cookies.json` — and
+ * `generated/` alone carries terraform state and provider binaries.
+ */
+function listPrunableFiles(root: string, dir = root): string[] {
+  const found: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    const rel = relative(root, full);
+    if (classifyModulePath(rel) === 'derived') continue;
+    if (entry.isDirectory()) {
+      found.push(...listPrunableFiles(root, full));
+    } else if (entry.isFile()) {
+      found.push(rel);
+    }
+  }
+  return found;
+}
+
 export async function updateOne(
   sourcePath: string,
   db: ReturnType<typeof getDb>,
@@ -241,6 +267,20 @@ export async function updateOne(
     };
   }
 
+  // Pointed at the module's OWN install, `updateOne` used to copy every file
+  // onto itself and die inside `cpSync` with `EINVAL: copy_file_range` — an
+  // error that names a syscall and not the mistake. Worse since D1: the copy
+  // dies partway, after the prune has already run. Refuse by name instead
+  // (D11).
+  if (resolve(actualPath) === resolve(module.sourcePath)) {
+    if (tempDir) await cleanupTempDir(tempDir);
+    return {
+      status: 'failed',
+      moduleId,
+      error: `'${sourcePath}' IS the installed copy of ${moduleId}. There is nothing to update it from. Point 'module update' at the module's source tree or a .netapp, or run 'celilo module upgrade ${moduleId}' to take the registry's version.`,
+    };
+  }
+
   // Old version comes from the DB so we capture whatever was last
   // recorded (which IS the registry-versioned form, e.g. "1.0.0+5",
   // for registry-driven installs/upgrades).
@@ -257,18 +297,84 @@ export async function updateOne(
   const installedPath = module.sourcePath;
   const preserveDirs = new Set(['generated', 'screenshots', 'cookies.json']);
 
-  const skipDirs = new Set(['.git', 'node_modules', '.next', '.cache']);
+  // Route the copy through the one classifier, the way `module import` does.
+  // `updateOne` used to copy the source tree wholesale, so updating from a
+  // directory planted `e2e/`, `*.test.ts` and `scripts/tsconfig.json` in the
+  // install — files no package ships and no target runs. Import never did,
+  // because a directory import goes through the packager; update is the path
+  // that skipped it.
   const entries = readdirSync(actualPath);
   for (const entry of entries) {
-    if (preserveDirs.has(entry) || skipDirs.has(entry)) continue;
+    if (preserveDirs.has(entry)) continue;
     const src = join(actualPath, entry);
     const dest = join(installedPath, entry);
-    cpSync(src, dest, { recursive: true, force: true });
+    cpSync(src, dest, {
+      recursive: true,
+      force: true,
+      filter: (from) => classifyModulePath(relative(actualPath, from)) !== 'unknown',
+    });
   }
 
+  // The integrity baseline for the version just installed. Prefer the package's
+  // own signed `checksums.json`; a directory update has none, so compute over
+  // the source we just copied. Read before the temp dir goes away.
+  const packagedChecksumsPath = join(actualPath, 'checksums.json');
+  const packagedSignaturePath = join(actualPath, 'signature.sig');
+  let baselineChecksums: Record<string, string>;
+  if (existsSync(packagedChecksumsPath)) {
+    const parsed = JSON.parse(readFileSync(packagedChecksumsPath, 'utf-8')) as {
+      files?: Record<string, string>;
+    };
+    baselineChecksums = parsed.files ?? {};
+  } else {
+    baselineChecksums = (await computeChecksums(actualPath)).files;
+  }
+  const packagedSignature = existsSync(packagedSignaturePath)
+    ? readFileSync(packagedSignaturePath, 'utf-8').trim()
+    : null;
+
   // Clean up temp dir if we extracted a .netapp
   if (tempDir) await cleanupTempDir(tempDir);
 
+  // Remove what the new version dropped. `updateOne` only ever overlaid files,
+  // so a hook script deleted in 1.1.0 stayed on the box and stayed runnable —
+  // code celilo no longer believes it has installed, which is the same class of
+  // lie as celilo#925 pointing the other way. Only `package`-class paths are
+  // pruned: `generated/`, the hook runtime closure, `screenshots/` and
+  // `cookies.json` are celilo's or the operator's, and survive an update by
+  // design.
+  const survivingPaths = new Set(
+    Object.keys(baselineChecksums).filter((p) => classifyModulePath(p) === 'package'),
+  );
+  for (const relPath of listPrunableFiles(installedPath)) {
+    if (!survivingPaths.has(relPath)) {
+      rmSync(join(installedPath, relPath));
+    }
+  }
+
+  // Record it. `updateOne` never touched this table, so the baseline stayed
+  // frozen at the module's FIRST import no matter how many times it was
+  // updated. That is why `module verify` reported the same violations whether
+  // the files were old or the checksums were old, and could not answer the one
+  // question that matters (celilo#925).
+  db.insert(moduleIntegrity)
+    .values({
+      moduleId,
+      checksums: baselineChecksums,
+      version: newVersion,
+      signature: packagedSignature,
+    })
+    .onConflictDoUpdate({
+      target: moduleIntegrity.moduleId,
+      set: {
+        checksums: baselineChecksums,
+        version: newVersion,
+        signature: packagedSignature,
+        updatedAt: new Date(),
+      },
+    })
+    .run();
+
   // Update manifest in database. We persist the display version (with
   // +N when known) so subsequent `module list` / `module update` calls
   // see the same version string the registry reported.

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

@@ -1,53 +1,117 @@
 import { auditModule } from '../../module/packaging/audit';
+import type { IntegrityViolation } from '../../module/packaging/extract';
+import { hasFlag } from '../parser';
 import type { CommandResult } from '../types';
 
 /**
- * Verify module integrity (signature + checksums).
+ * Verify module integrity across the three planes a module lives in.
  *
- * Usage: celilo module verify <module-id>
+ * Usage: celilo module verify <module-id> [--deep] [--json]
+ *
+ *   installed tree vs baseline      did anything change the files since install?
+ *   generated project vs installed  is what we would deploy built from it?
+ *   host vs generated project       is what is running what we generated?  (--deep)
+ *
+ * The first two are local and take milliseconds. `--deep` is one SSH per
+ * system, so it is opt-in (openspec/changes/module-integrity-rigor, D3).
  *
  * Renamed from `module audit` per CELILO_UPDATE D11 — `audit` is now
  * reserved for system-level drift detection (`celilo system audit`).
  * The legacy `module audit` continues to work via a deprecation alias
  * (see `module-audit.ts`).
  *
- * Returns a CommandResult so the dispatcher controls process exit
- * behavior.
+ * Returns a CommandResult so the dispatcher controls process exit behavior.
  */
-export async function moduleVerify(args: string[]): Promise<CommandResult> {
+export async function moduleVerify(
+  args: string[],
+  flags: Record<string, string | boolean> = {},
+): Promise<CommandResult> {
   if (args.length === 0) {
     return {
       success: false,
-      error: 'Module ID is required\n\nUsage: celilo module verify <module-id>',
+      error: 'Module ID is required\n\nUsage: celilo module verify <module-id> [--deep] [--json]',
     };
   }
 
   const moduleId = args[0];
+  const deep = hasFlag(flags, 'deep');
+  const json = hasFlag(flags, 'json');
+
+  const result = await auditModule(moduleId, undefined, { deep });
 
-  const result = await auditModule(moduleId);
+  if (json) {
+    // The whole point of D9: one call answers "is the installed tree the
+    // version celilo thinks it is", with the digests on both sides, so nobody
+    // needs a shell on celilo-mgr to settle a celilo#925-shaped question.
+    const payload = {
+      moduleId,
+      deep,
+      ok: result.success && !result.error,
+      error: result.error ?? null,
+      moduleVersion: result.moduleVersion ?? null,
+      baselineVersion: result.baselineVersion ?? null,
+      violations: result.violations.map((v) => ({
+        type: v.type,
+        path: v.path,
+        message: v.message,
+        expectedDigest: v.expectedDigest ?? null,
+        actualDigest: v.actualDigest ?? null,
+      })),
+      hosts: result.hostPlane?.findings ?? [],
+      deepOptOut: result.hostPlane?.optedOut ?? null,
+    };
+    const text = JSON.stringify(payload, null, 2);
+    return payload.ok ? { success: true, message: text } : { success: false, error: text };
+  }
 
   if (result.error) {
     return { success: false, error: result.error };
   }
 
+  const lines: string[] = [];
+
+  // An opt-out nobody sees is a check that quietly disappeared, so it prints
+  // whether the module is clean or not (task 6.3).
+  if (result.hostPlane?.optedOut) {
+    lines.push(
+      `  ⚠ [DEEP SKIPPED] This module opts out of the host check: ${result.hostPlane.optedOut.reason}`,
+    );
+  }
+  for (const finding of result.hostPlane?.findings ?? []) {
+    if (finding.state === 'converged') {
+      lines.push(`  ✓ [HOST] ${finding.hostname}: running what celilo generated`);
+    } else {
+      const tag = finding.state === 'drift' ? 'HOST-DRIFT' : 'HOST-UNMEASURED';
+      lines.push(
+        `  ${finding.state === 'drift' ? '✗' : '⚠'} [${tag}] ${finding.hostname}: ${finding.detail}`,
+      );
+    }
+  }
+
   if (result.success) {
     return {
       success: true,
-      message: `Module '${moduleId}' passed integrity check\n  No violations found.`,
+      message: [`Module '${moduleId}' passed integrity check`, ...lines, '  No violations found.']
+        .join('\n')
+        .trimEnd(),
     };
   }
 
-  const violationLines = result.violations.map((v) => {
-    const icon = v.type === 'missing' ? '⚠' : v.type === 'modified' ? '✗' : '!';
-    return `  ${icon} [${v.type.toUpperCase()}] ${v.message}`;
-  });
+  const ICONS: Record<IntegrityViolation['type'], string> = {
+    missing: '⚠',
+    modified: '✗',
+    extra: '!',
+    'stale-baseline': '⚠',
+    'stale-generated': '✗',
+  };
 
   return {
     success: false,
     error: [
       `Module '${moduleId}' failed integrity check`,
       `  Found ${result.violations.length} violation(s):`,
-      ...violationLines,
+      ...result.violations.map((v) => `  ${ICONS[v.type]} [${v.type.toUpperCase()}] ${v.message}`),
+      ...lines,
     ].join('\n'),
   };
 }