@celilo/cli 2.0.0 → 2.2.0

package/CELILO_CORE_MODULES.md

@@ -54,7 +54,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 
 ## Celilo's own infrastructure (self-hosted)
 
-- **celilo-mgmt** — the celilo management server itself, deployed as a module (replaces install.sh + `system init`; ships daemon, runs migrations, self-registers). **provides:** `celilo_event_bus`, `celilo_module_deploy_worker`. **requires:** `cross_module_read`. See `openspec/specs/management-as-module/spec.md`.
+- **celilo-mgmt** — the celilo management server itself, deployed as a module (replaces install.sh + `system init`; ships daemon, runs migrations). Has **no `on_install`** — celilo initialises the box itself during the deploy (`bootstrapControlPlane`), because a jailed hook cannot spawn the CLI it used to reach (celilo#1225). **provides:** `celilo_event_bus`, `celilo_module_deploy_worker`. **requires:** `cross_module_read`. See `openspec/specs/management-as-module/spec.md`.
 - **celilo-registry** — module registry server (Cargo sparse protocol); stores `.netapp` files, serves index + search/download API. On install it provisions a confidential introspection OIDC client via `idp.create_oidc_client` (SECURE_MODULE_PUBLISH.md §5[D-A]) and converges its issuer + introspection endpoint + creds onto the box for RFC 7662 token verification. Its `sweep_revisions` hook is the store's ONLY delete path — `yank` flips a boolean in the index entry and frees nothing, so before it existed every build revision ever published was retained forever and a `+N` revision is auto-assigned on every publish. The production store reached 18 GB of which ~93% was superseded history, filled a 20 GB disk and took the release pipeline down. The sweep keeps the newest `sweep_keep_build_revisions` (default 1) of EVERY release, so no release can disappear and a manual rollback still works — that is what makes the hourly `timer.tick.1h` subscription defensible. It removes the index line BEFORE the payload, because the download route reads the payload file directly and never consults the index: that order leaves an interrupted sweep with an unlisted-but-served version rather than a listed one that 404s, and the orphan it leaves is reclaimed by the next run. On demand with `celilo module run-hook celilo-registry sweep_revisions` (add `dry_run=true` to see the plan). **provides:** `registry_publish`. **requires:** `public_web`, `dns_registrar`, `idp`.
 - **celilo-apt-repo** — Debian apt repository (reprepro + Bun HTTP server) serving the celilo `.deb` at apt.celilo.computer. **provides:** `apt_publish`. **requires:** `public_web`, `dns_registrar`.
 - **signal** — bidirectional Signal transport for alerts and deploy-interview questions; runs signal-cli in daemon mode with its JSON-RPC socket bound to the host's own address (never public) and **`--receive-mode=manual`**, which is load-bearing: signal-cli's default (`on-start`) leaves the daemon permanently receiving, so it drains every reply into an SSE stream nothing is attached to and REFUSES celilo's `receive` call — replies arrive and are unreadable, while `send` and every health check keep passing. Enrolled as a SECONDARY DEVICE of an existing Signal account rather than registering its own number — Signal blocks most VOIP ranges and bans bot-ish registrations. Recipient addresses live on celilo routes, not in module config, so adding a person never requires a redeploy. Runs on x86_64 and aarch64. `libsignal-client` ships no linux-aarch64 native, so celilo builds one (`modules/signal/build/`) and installs it as a `libsignal-jni` .deb on ARM hosts; x86_64 uses the JAR's bundled native. **provides:** `notification` (`send`, `receive`). **requires:** no capabilities — a transport that depended on the proxy, registrar or firewall could not tell you those were broken — and a system in the **`secure-mgmt`** zone: it holds a linked Signal account (the operator's own messaging identity and keys), and its job is to observe every tier while depending on none, which is what the control-plane zone is for. See `openspec/changes/add-alerting/`.

package/CELILO_SUBSYSTEMS.md

@@ -205,6 +205,7 @@ runner seam (`execRunner` real / `createMockRunner` for tests) lives in
 - **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`.
+- **Control-plane bootstrap (celilo initialises its own box)** — `apps/celilo/src/services/control-plane-bootstrap.ts` (`bootstrapControlPlane`) with `apps/celilo/src/services/dns-discovery.ts` (`discoverDns`) beside `network-discovery.ts`. Called from `module-deploy.ts` at the point `on_install` runs, for `CONTROL_PLANE_MODULE_ID` (exported from `services/deployed-systems.ts`, replacing three private copies of the string). Reads the box's upstream resolvers, mints the fleet key via `ensureFleetKey`, writes `dns.*` + `ssh.public_key` in ONE `initializeSystem` call, records the network via `discoverAndRecordNetwork`, then polls `checkDispatcher` and FAILS the deploy if no dispatcher answers. **It is not a hook, and that is the point** (celilo#1225): it was `modules/celilo-mgmt/scripts/on_install.ts`, which reached all of this by spawning the `celilo` CLI — impossible inside the jail, whose mount set binds no `/usr/bin`, no `/usr/local/bin` and no shell, so the deploy ran Ansible clean and then died in its own install hook on every host with a jail backend. celilo-mgmt is never deployed to a remote box, so the host being configured is always the host celilo runs on and the hook was a process boundary with celilo on both sides. Self-registering the management host into its own pool did NOT move: celilo places a module only on a machine already in the pool. The dispatcher read is celilo's four-part `checkDispatcher`, not the "is a process up?" probe the hook used.
 - **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:
   - **Outbound** (`maybeRunAspectForTrigger`, `on_install`): one provider's aspect across the whole fleet, enumerated at that instant. A failure never fails the provider's own deploy — aspects are forward-progress and a partial fleet converges on the next fan-out.

package/drizzle/0031_module_config_source.sql

@@ -0,0 +1,20 @@
+-- Who owns a `module_configs` row (hook-owned-state design D7).
+--
+-- One column, two changes: hook-owned-state needs it to enforce "only a hook
+-- writes source: hook", and `derived-value-recomputation` needs it to tell an
+-- operator row from a derived-seeded one. Whichever change landed first owns
+-- the migration; this is it.
+--
+-- Purely additive and NULLABLE on purpose. NULL means "written before the
+-- column existed" — operator intent, interview writes, legacy derived seeds,
+-- framework keys alike — and stays the value for operator writes until
+-- derived-value-recomputation lands its own classification. There is no
+-- backfill: nothing in an existing row can prove who wrote it, and a guess
+-- backfilled as fact is worse than an honest NULL.
+--
+-- The first writer of a non-NULL value is the hook config store
+-- (`hooks/hook-store.ts`), whose `set` writes 'hook' through
+-- `upsertModuleConfig`. The manifest refuses `module config set` on any
+-- `source: hook` variable, so only a hook can produce the value.
+
+ALTER TABLE `module_configs` ADD `source` text;

package/drizzle/meta/_journal.json

@@ -218,6 +218,13 @@
       "when": 1784400000000,
       "tag": "0030_drop_module_builds_environment",
       "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "6",
+      "when": 1788768000000,
+      "tag": "0031_module_config_source",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "2.0.0",
+  "version": "2.2.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": "^4.0.0",
+    "@celilo/capabilities": "^4.2.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.11.0",
     "@celilo/event-bus": "^0.6.0",

package/schemas/system_config.json

@@ -102,7 +102,8 @@
     },
     "firewall.trusted_subnets": {
       "type": "string",
-      "description": "Operator-declared trusted source subnets (comma-separated CIDRs) permitted to reach every managed zone. ADDITIVE to the control-plane subnet celilo derives and to the sources modules register \u2014 it cannot drop control-plane trust, which would block the SSH every hook and converge runs over."
+      "format": "cidr-list",
+      "description": "Operator-declared trusted source subnets permitted to reach every managed zone, as a comma-separated CIDR list (10.0.0.0/24,10.1.0.0/24) or a JSON array ([\"10.0.0.0/24\"]). ADDITIVE to the control-plane subnet celilo derives and to the sources modules register \u2014 it cannot drop control-plane trust, which would block the SSH every hook and converge runs over."
     },
     "dns.primary": {
       "type": "string",

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

@@ -273,6 +273,67 @@ describe('publishStaticSite — clientConfig injection', () => {
   });
 });
 
+describe('the state web overlay (celilo#1265)', () => {
+  beforeEach(() => {
+    execSyncSpy = spyOn(childProcess, 'execSync').mockReturnValue(Buffer.from(''));
+  });
+
+  afterEach(() => {
+    execSyncSpy.mockRestore();
+  });
+
+  // A jailed hook cannot write into its own module tree, so generated site
+  // files land in `<module>/state/site`. The upload's content hash must see
+  // them, or the release directory never refreshes when the overlay changes.
+  test('the upload hash and file count include the state overlay', async () => {
+    const sourceDir = mkdtempSync(join(tmpdir(), 'publish-overlay-'));
+    const overlayDir = join(mkdtempSync(join(tmpdir(), 'publish-overlay-state-')));
+    writeFileSync(join(sourceDir, 'index.html'), '<html></html>', 'utf-8');
+
+    try {
+      const { ops, routes } = makeRouteOps();
+      const cap = createPublicWeb({
+        webRoot: sourceDir,
+        stateWebRoot: overlayDir,
+        moduleId: 'lunacycle',
+        logger: noopLogger,
+        config: {
+          target_ip: '10.0.10.20/24',
+          hostname: 'www',
+          primary_domain: 'example.com',
+          email: 'admin@example.com',
+        },
+        secrets: {},
+        convergeStaticContent: async () => {},
+        routeOps: ops,
+        hostnames: ['www.example.com'],
+        caddyModuleId: 'caddy',
+        dnsManagedDomains: ['www.example.com'],
+      });
+
+      const hashOf = () =>
+        routes.find((r) => r.moduleId === 'lunacycle' && r.path === '/lunacycle')?.contentHash;
+
+      // No overlay yet: one file, and the hash covers only the web root.
+      const before = await cap.publishStaticSite({ path: '/lunacycle' });
+      const hashBefore = hashOf();
+      expect(before.filesUploaded).toBe(1);
+      expect(hashBefore).toBeTruthy();
+
+      // A generated file in state must move the hash, or a rebuilt host's
+      // converge would re-serve the old release and the file would never land.
+      writeFileSync(join(overlayDir, 'ca.crt'), '---CERT---', 'utf-8');
+      const after = await cap.publishStaticSite({ path: '/lunacycle' });
+      expect(after.filesUploaded).toBe(2);
+      expect(hashOf()).toBeTruthy();
+      expect(hashOf()).not.toBe(hashBefore);
+    } finally {
+      rmSync(sourceDir, { recursive: true, force: true });
+      rmSync(overlayDir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('registerReverseProxy', () => {
   beforeEach(() => {
     execSyncSpy = spyOn(childProcess, 'execSync').mockReturnValue(Buffer.from(''));

package/src/cli/commands/firewall-interface-list.test.ts

@@ -8,11 +8,39 @@
  * was never a lack of information but a lack of celilo saying it.
  */
 
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
+// The command reaches boxes ONLY through these two modules, and both are
+// mocked below so the tests can drive the live-read and fallback paths without
+// a real machine. Spreading the actual module keeps every other export intact
+// for anything else that loads them.
+const actualDetector = await import('../../services/machine-detector');
+const actualKeyManager = await import('../../services/ssh-key-manager');
+
+type Detected = {
+  interfaces: Array<{ name: string; ipAddress: string; zone?: string }>;
+  role: string;
+};
+
+let liveRead: (ip: string, user: string, keyPath: string) => Promise<Detected>;
+let localRead: () => Promise<Detected>;
+let tempKeyWriter: (machineId: string) => Promise<string>;
+
+mock.module('../../services/machine-detector', () => ({
+  ...actualDetector,
+  detectNetworkInterfaces: (ip: string, user: string, keyPath: string) =>
+    liveRead(ip, user, keyPath),
+  detectNetworkInterfacesLocal: () => localRead(),
+}));
+mock.module('../../services/ssh-key-manager', () => ({
+  ...actualKeyManager,
+  writeTemporarySshKey: (machineId: string) => tempKeyWriter(machineId),
+  deleteTemporarySshKey: () => {},
+}));
+
 let testDir: string;
 let logs: string[];
 const originalLog = console.log;
@@ -29,6 +57,10 @@ beforeEach(() => {
   testDir = mkdtempSync(join(tmpdir(), 'celilo-fw-iface-'));
   process.env.CELILO_DB_PATH = join(testDir, 'test.db');
   process.env.CELILO_DATA_DIR = testDir;
+  // Key decryption (getMachineSshKey) needs a master key.
+  const masterKeyPath = join(testDir, 'master.key');
+  writeFileSync(masterKeyPath, 'a'.repeat(64));
+  process.env.CELILO_MASTER_KEY_PATH = masterKeyPath;
   captureLogs();
 });
 
@@ -36,6 +68,8 @@ afterEach(() => {
   console.log = originalLog;
   rmSync(testDir, { recursive: true, force: true });
   process.env.CELILO_DB_PATH = undefined;
+  process.env.CELILO_DATA_DIR = undefined;
+  process.env.CELILO_MASTER_KEY_PATH = undefined;
 });
 
 describe('celilo firewall interface list', () => {
@@ -71,15 +105,130 @@ describe('celilo firewall interface list', () => {
  * me — it would pass no matter what they said. The property below is different:
  * it is a claim about what the command may DO, and it can genuinely fail.
  */
-describe('read-only by construction', () => {
-  test('never touches the box', async () => {
-    // Safe to run against a firewall whose converge is currently refusing —
-    // which is exactly when an operator reaches for it. If this ever grows an
-    // SSH call it is a different command and should be named like one.
+describe('no side effects on the box', () => {
+  test('reaches a box only through the read-only detectors', async () => {
+    // #1287's CLI half came from the stored-read-only version of this command:
+    // a snapshot taken at machine add kept reading ALIEN after the interface
+    // was gone, so the command contradicted the converge it claims to preview.
+    // The fix reads the box live through the same detectors machine add uses —
+    // read-only by construction. What is still forbidden is any MUTATING
+    // remote primitive, and any hand-built ssh that could grow one silently.
     const src = await Bun.file(join(import.meta.dir, 'firewall-interface-list.ts')).text();
 
     expect(src).not.toContain('runAppCommand');
     expect(src).not.toContain('execFileSync');
     expect(src).not.toContain('ssh ');
+    // The live read must come from the shared detector, not a private path.
+    expect(src).toContain('detectNetworkInterfaces');
+  });
+});
+
+/**
+ * The live-read contract, against a machine whose STORED snapshot is stale —
+ * the #1287 shape: the alien cable was attached when `machine add` recorded
+ * the interfaces, and nothing refreshes that snapshot afterwards.
+ */
+describe('reads the box live', () => {
+  beforeEach(async () => {
+    liveRead = async () => {
+      throw new Error('liveRead not configured for this test');
+    };
+    localRead = async () => {
+      throw new Error('localRead not configured for this test');
+    };
+    tempKeyWriter = async () => {
+      throw new Error('tempKeyWriter not configured for this test');
+    };
+
+    const { getDb } = await import('../../db/client');
+    const { systemConfig } = await import('../../db/schema');
+    const { addMachine } = await import('../../services/machine-pool');
+
+    await getDb()
+      .insert(systemConfig)
+      .values([
+        { key: 'network.internal.subnet', value: '10.226.1.0/24' },
+        { key: 'network.app.subnet', value: '10.226.20.0/24' },
+        { key: 'network.dmz.subnet', value: '10.226.10.0/24' },
+        { key: 'network.secure.subnet', value: '10.226.30.0/24' },
+      ]);
+
+    await addMachine({
+      hostname: 'fw-main',
+      zone: 'internal',
+      ipAddress: '10.226.1.254',
+      sshUser: 'root',
+      sshKey: 'test-key-material',
+      hardware: { cpu_cores: 2, memory_mb: 2048, disk_gb: 64 },
+      role: 'host',
+      interfaces: [
+        { name: 'eth0', ipAddress: '10.226.20.1', zone: 'app' },
+        { name: 'eth1', ipAddress: '10.226.10.1', zone: 'dmz' },
+        { name: 'eth2', ipAddress: '10.226.1.254', zone: 'internal' },
+        { name: 'eth3', ipAddress: '10.226.30.1', zone: 'secure' },
+        // The cable nobody documented, recorded because it was attached when
+        // the machine was added. It left the box afterwards; the snapshot
+        // never heard about it.
+        { name: 'eth4', ipAddress: '172.31.99.2', zone: 'unknown' },
+      ],
+    });
+  });
+
+  test('an interface removed after machine add no longer reads ALIEN', async () => {
+    let keyWritten = false;
+    tempKeyWriter = async () => {
+      keyWritten = true;
+      return '/tmp/celilo-fw-iface-test.key';
+    };
+    liveRead = async (ip, user) => {
+      // The read went to the box named in the machine record, with its stored
+      // credentials — the same targeting the converge uses.
+      expect(ip).toBe('10.226.1.254');
+      expect(user).toBe('root');
+      return {
+        interfaces: [
+          { name: 'eth0', ipAddress: '10.226.20.1' },
+          { name: 'eth1', ipAddress: '10.226.10.1' },
+          { name: 'eth2', ipAddress: '10.226.1.254' },
+          { name: 'eth3', ipAddress: '10.226.30.1' },
+        ],
+        role: 'router',
+      };
+    };
+
+    const { handleFirewallInterfaceList } = await import('./firewall-interface-list');
+    const result = await handleFirewallInterfaceList(['fw-main'], {});
+
+    expect(result.success).toBe(true);
+    expect(keyWritten).toBe(true);
+    const out = logs.join('\n');
+    // eth4 is gone from the box, so the answer says so — even though the
+    // stored snapshot still carries it.
+    expect(out).not.toContain('172.31.99.2');
+    expect(out).not.toContain('ALIEN');
+    for (const zone of ['app', 'dmz', 'internal', 'secure']) {
+      expect(out).toContain(`zone:${zone}`);
+    }
+    expect(out).not.toContain('could not read the box live');
+  });
+
+  test('a box that cannot be reached says so, and labels the snapshot as stale', async () => {
+    tempKeyWriter = async () => '/tmp/celilo-fw-iface-test.key';
+    liveRead = async () => {
+      throw new Error('SSH command failed after 3 attempts: connection refused');
+    };
+
+    const { handleFirewallInterfaceList } = await import('./firewall-interface-list');
+    const result = await handleFirewallInterfaceList(['fw-main'], {});
+
+    // Unreachable is not a classification result, but the stored snapshot is
+    // still the best available answer — as long as it says what it is.
+    expect(result.success).toBe(true);
+    const out = logs.join('\n');
+    expect(out).toContain('could not read the box live');
+    expect(out).toContain('may be stale');
+    // The stale eth4 is reported, under the label that keeps it from being
+    // mistaken for a current finding.
+    expect(out).toContain('ALIEN');
   });
 });

package/src/cli/commands/firewall-interface-list.ts

@@ -9,15 +9,34 @@
  * The condition that produced `fw-keeper.sh` was not that celilo lacked the
  * information; it was that celilo never said it.
  *
- * Read-only by construction: it reads the stored interface table and the
- * declarations, and classifies in memory. It never touches the box, so it is
- * safe to run against a firewall that is currently refusing.
+ * No side effects: it reads the LIVE interface table the same way the next
+ * converge will — classification is recomputed, never read from a stored copy
+ * (design D4: a stored classification goes stale) — plus the declarations, and
+ * classifies in memory. The only remote operations are the read-only interface
+ * detectors `machine add` uses. When the box cannot be reached it says so, and
+ * falls back to the interface snapshot recorded at machine add, labelled as
+ * what it is.
+ *
+ * The stored-read-only version of this command was the whole of the CLI half
+ * of #1287: the snapshot is taken at machine add, so an interface removed after
+ * it was recorded kept reading ALIEN forever, and an operator who did exactly
+ * what the converge refusal told them to do was told their fix had not worked.
  */
 
 import { classifyInterfaces, isPubliclyRoutable } from '@celilo/capabilities';
 import { getDb } from '../../db/client';
 import { listFirewallIps, readDeclaredNetworks } from '../../hooks/capability-loader';
+import {
+  detectNetworkInterfaces,
+  detectNetworkInterfacesLocal,
+} from '../../services/machine-detector';
 import { listMachines } from '../../services/machine-pool';
+import {
+  LOCAL_MACHINE_IP,
+  deleteTemporarySshKey,
+  writeTemporarySshKey,
+} from '../../services/ssh-key-manager';
+import type { Machine } from '../../types/infrastructure';
 import { celiloIntro } from '../prompts';
 import type { CommandResult } from '../types';
 
@@ -36,6 +55,41 @@ async function declaredZones(): Promise<Array<{ zone: string; subnet: string }>>
   return readDeclaredNetworks(getDb());
 }
 
+/** What the classifier consumes, whatever the source. */
+interface NamedInterface {
+  name: string;
+  ip: string;
+}
+
+/**
+ * The interface table as the box holds it RIGHT NOW, via the same read-only
+ * detectors `machine add` runs. The converge reads the box live too, so this
+ * is the input its classification will see.
+ */
+async function readLiveInterfaces(machine: Machine): Promise<NamedInterface[]> {
+  const toNamed = (list: Array<{ name: string; ipAddress: string }>): NamedInterface[] =>
+    list.map(({ name, ipAddress }) => ({ name, ip: ipAddress }));
+
+  // The management box registers itself as 127.0.0.1 with no stored SSH key
+  // and is reached locally, the same way machine add reaches it.
+  if (machine.ipAddress === LOCAL_MACHINE_IP) {
+    const { interfaces } = await detectNetworkInterfacesLocal();
+    return toNamed(interfaces);
+  }
+
+  const keyPath = await writeTemporarySshKey(machine.id);
+  try {
+    const { interfaces } = await detectNetworkInterfaces(
+      machine.ipAddress,
+      machine.sshUser,
+      keyPath,
+    );
+    return toNamed(interfaces);
+  } finally {
+    deleteTemporarySshKey(machine.id);
+  }
+}
+
 /** One line per interface, explaining the role rather than just naming it. */
 function describe(role: string, zone: string | undefined, ip: string): string {
   if (role === 'zone') return `zone:${zone}`;
@@ -88,10 +142,22 @@ export async function handleFirewallInterfaceList(
   for (const machine of targets) {
     console.log(`\n${machine.hostname} (${machine.ipAddress})`);
 
-    const interfaces = (machine.interfaces ?? []).map((i) => ({
-      name: i.name,
-      ip: i.ipAddress,
-    }));
+    let interfaces: NamedInterface[];
+    try {
+      interfaces = await readLiveInterfaces(machine);
+    } catch (error) {
+      // An unreachable box is not a classification result. Name the fallback
+      // for what it is, so a stale ALIEN is never mistaken for a current one.
+      const reason = error instanceof Error ? error.message : String(error);
+      console.log(
+        '  could not read the box live — classifying the interface snapshot recorded at machine add, which may be stale:',
+      );
+      console.log(`  ${reason}`);
+      interfaces = (machine.interfaces ?? []).map((i) => ({
+        name: i.name,
+        ip: i.ipAddress,
+      }));
+    }
     if (interfaces.length === 0) {
       console.log('  no interfaces recorded — re-run `celilo machine add` to detect them');
       continue;

package/src/cli/commands/machine-add.ts

@@ -5,11 +5,11 @@
 
 import { existsSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
 import { isPubliclyRoutable } from '@celilo/capabilities';
 import { getDb } from '../../db/client';
 import type { NetworkZone } from '../../db/schema';
 import { askText, withInterviewSession } from '../../services/bus-interview';
+import { findFleetPrivateKey, fleetKeySearchDirs } from '../../services/fleet-key';
 import {
   detectMachineInfo,
   detectMachineInfoLocal,
@@ -30,60 +30,18 @@ import { celiloIntro, celiloOutro } from '../prompts';
 import type { CommandResult } from '../types';
 
 /**
- * Auto-detect SSH private key from system configuration
+ * The private key matching `ssh.public_key`, or null.
  *
- * Reads ssh.public_key from system config and finds matching private key in ~/.ssh/
- *
- * @returns Path to SSH private key, or null if not found
+ * Delegates the search to `findFleetPrivateKey`, which lives beside the mint
+ * so the two cannot name different directories. This function used to derive
+ * its own `join(HOME, '.ssh')`, which meant it could not see the key
+ * `ensureFleetKey` writes into celilo's data directory, so a fleet whose key
+ * celilo minted refused every `machine add` (celilo#1240).
  */
 function findSshPrivateKey(): string | null {
   try {
-    const db = getDb();
-    const config = loadExistingConfiguration(db);
-    const publicKey = config['ssh.public_key'];
-
-    if (!publicKey) {
-      return null;
-    }
-
-    // Extract key type from public key (e.g., "ssh-ed25519", "ssh-rsa")
-    const keyType = publicKey.split(' ')[0];
-
-    const sshDir = join(process.env.HOME || '~', '.ssh');
-    if (!existsSync(sshDir)) {
-      return null;
-    }
-
-    // Common private key filenames based on type
-    const keyFileMap: Record<string, string[]> = {
-      'ssh-ed25519': ['id_ed25519'],
-      'ssh-rsa': ['id_rsa'],
-      'ecdsa-sha2-nistp256': ['id_ecdsa'],
-      'ecdsa-sha2-nistp384': ['id_ecdsa'],
-      'ecdsa-sha2-nistp521': ['id_ecdsa'],
-    };
-
-    const candidateFiles = keyFileMap[keyType] || ['id_rsa', 'id_ed25519', 'id_ecdsa'];
-
-    // Try common key files
-    for (const keyFile of candidateFiles) {
-      const keyPath = join(sshDir, keyFile);
-      if (existsSync(keyPath)) {
-        // Verify this is the matching private key by checking if public key exists
-        const pubKeyPath = `${keyPath}.pub`;
-        if (existsSync(pubKeyPath)) {
-          const pubKeyContent = readFileSync(pubKeyPath, 'utf8').trim();
-          // Check if public keys match (compare key type and key data, ignore comment)
-          const [sysType, sysKey] = publicKey.split(' ');
-          const [fileType, fileKey] = pubKeyContent.split(' ');
-          if (sysType === fileType && sysKey === fileKey) {
-            return keyPath;
-          }
-        }
-      }
-    }
-
-    return null;
+    const publicKey = loadExistingConfiguration(getDb())['ssh.public_key'];
+    return publicKey ? findFleetPrivateKey(publicKey) : null;
   } catch {
     return null;
   }
@@ -200,10 +158,9 @@ export async function handleMachineAdd(
           if (!detectedKeyPath) {
             return {
               success: false,
-              error:
-                'Cannot find SSH private key.\n\n' +
-                'The ssh.public_key system config is set, but no matching private key was found in ~/.ssh/\n\n' +
-                'Specify manually with: --ssh-key-file ~/.ssh/id_ed25519',
+              error: `Cannot find SSH private key.\n\nThe ssh.public_key system config is set, but no private key matching it was found in:\n${fleetKeySearchDirs()
+                .map((dir) => `  ${dir}`)
+                .join('\n')}\n\nSpecify manually with: --ssh-key-file <path>`,
             };
           }
           sshKeyPath = detectedKeyPath;

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

@@ -10,7 +10,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { type DbClient, getDb } from '../../db/client';
-import { modules } from '../../db/schema';
+import { moduleConfigs, modules } from '../../db/schema';
 import { resolveDeployPosture } from '../../services/deploy-posture';
 import {
   FRAMEWORK_CONFIG_KEYS,
@@ -41,6 +41,7 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
               { name: 'vmid', type: 'integer', source: 'infrastructure' },
               { name: 'target_node', type: 'string', source: 'infrastructure' },
               { name: 'app_port', type: 'integer' },
+              { name: 'public_ip', type: 'string', source: 'hook' },
             ],
           },
         },
@@ -79,6 +80,24 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
     expect(result.success).toBe(true);
   });
 
+  // Hook-owned-state task 2.4 (design D2/D6): a `source: hook` variable is
+  // written ONLY by the module's own hook via `context.config.set`. A hand set
+  // value would be meaningless — the next hook run overwrites it — so the
+  // command refuses rather than reporting success over nothing.
+  test('rejects a hook-owned key and points at the accessor', async () => {
+    const result = await handleModuleConfigSet(['testmod', 'public_ip', '203.0.113.7']);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain('source: hook');
+      expect(result.error).toContain('not operator-settable');
+      expect(result.error).toContain('context.config.set');
+    }
+    // And no row may exist — a refusal that leaves the row behind is the
+    // accept-then-override bug in a different coat.
+    const rows = db.select().from(moduleConfigs).all();
+    expect(rows).toEqual([]);
+  });
+
   test('still rejects an undeclared key, and omits infra keys from the valid-keys hint', async () => {
     const result = await handleModuleConfigSet(['testmod', 'nope', 'x']);
     expect(result.success).toBe(false);

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

@@ -339,7 +339,7 @@ async function handlePublicRegistryImport(
   // Download the .netapp
   const tmpPath = join(tmpdir(), `${name}-${latest.vers}-${Date.now()}.netapp`);
   try {
-    const pkgData = await client.download(name, latest.vers);
+    const pkgData = await client.download(name, latest.vers, latest.cksum);
     await Bun.write(tmpPath, pkgData);
   } catch (err) {
     return {