@celilo/cli 1.5.0 → 1.6.0

package/CELILO_SUBSYSTEMS.md

@@ -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.
@@ -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.5.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'),
   };
 }

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

@@ -211,6 +211,13 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
 
   const healthResults = await runAllHealthChecks(db, { onProgress });
 
+  // Module integrity. Shallow by default: the installed tree against its
+  // baseline, and the generated project against the installed tree. Both are
+  // local and take milliseconds. The host plane is one SSH per system and is
+  // reached through `module verify --deep`, not from here.
+  const { auditModule } = await import('../../module/packaging/audit');
+  const integrityResults = await Promise.all(installed.map((m) => auditModule(m.id, db)));
+
   // Services-credentials: try decrypting each container service's
   // credential envelope. Failures (missing master key, wrong
   // provider shape, corrupt envelope) become BLOCKED audit findings.
@@ -369,6 +376,14 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
       fetcher: makeRegistryFetcher(registryClient),
     },
     moduleConfigs: { modules: installedConfigs },
+    moduleIntegrity: { results: integrityResults },
+    detectWithoutConverge: {
+      modules: deployedModules.map((m) => ({
+        id: m.id,
+        state: m.state,
+        manifest: m.manifestData as ModuleManifest,
+      })),
+    },
     health: { results: healthResults },
     backups: { modules: installedBackupInfo },
     abandonedOperations: { records: loadAbandonedOperations(db) },
@@ -419,11 +434,13 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
 
 const VERDICT_ICON: Record<string, string> = {
   READY: '●',
+  UNKNOWN: '?',
   DRIFT: '⚠',
   BLOCKED: '✗',
 };
 
 const SEVERITY_ICON: Record<string, string> = {
+  unmeasured: '?',
   drift: '⚠',
   blocked: '✗',
 };