@celilo/cli 2.2.0 → 2.3.0

package/CELILO_CORE_MODULES.md

@@ -71,6 +71,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 
 ## Applications
 
+- **burner** — fleet-only ISO library and on-demand optical-disc writer. An unprivileged controller LXC owns a deliberately disposable content-addressed image store, SQLite job queue, HTTP Basic-protected dashboard, and the only inbound surface; small host workers poll it over private HTTPS and alone receive `cdrom` access to each configured `/dev/sr0`. Jobs accept only blank media with sufficient capacity, stage by SHA-256, burn through argv-only `xorriso`, read exactly the source image length back for SHA-256 verification, and never automatically retry after the laser may have started. Images are uploaded/deleted in the UI and are not covered by a Celilo backup hook; a future NAS can replace the controller store without changing the digest-addressed worker protocol. **requires:** `private_web`.
 - **homebridge** — HomeKit bridge for smart-home devices (VeSync, Leviton, Lutron, TP-Link, Tuya). No capabilities (leaf app).
 
 ## E2E fixtures & probes (not production apps)

package/CELILO_SUBSYSTEMS.md

@@ -203,7 +203,7 @@ runner seam (`execRunner` real / `createMockRunner` for tests) lives in
 - **Hook process boundary (a hook is a program celilo RUNS)** — `apps/celilo/src/hooks/hook-protocol.ts` (the NDJSON frame union, `HOOK_PROTOCOL_VERSION`, `serializeError`/`deserializeError`), `apps/celilo/src/hooks/broker.ts` (`startBroker`, `capabilityShape`), `apps/celilo/src/hooks/hook-runner-entry.ts` + `apps/celilo/src/hooks/hook-runner.ts` (the spawned shim — the ONLY thing that `import()`s module code; the entry exists to install the advisory lint before the shim's import graph can ESM-load `node:fs`, see `unjailed-lint.ts`). `executeHookScript` spawns `bun hook-runner-entry.ts` over a Unix socket instead of importing; the nine `invokeHook` call sites and `defineHook` are unchanged. **The broker does not know what a capability is**: it sends a shape descriptor built by the same own-string-key walk `wrapWithLogging` does (functions → `methods`, everything else → `data`, which is where `stampProvider`'s `providerModuleId` lives), and the shim rebuilds forwarding proxies from it — so an optional method a provider did not implement is absent rather than present-and-throwing, and `if (cap.registerTrustedSource)` keeps answering correctly. A socket rather than stdout because module scripts spawn subprocesses and a grandchild writing to fd 1 would corrupt the frame stream. Two consequences worth knowing: the child's environment is an **allow-list** (`hookChildEnv` — how to run: `PATH`, `HOME`, `LANG`, `TZ`, `TMPDIR`; whom to trust: `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `SSL_CERT_DIR`; the proxy variables; the `CELILO_HOOK_*` channels; `CELILO_DEBUG` — `FORWARDED_ENV` in executor.ts is the source of truth), so a hook reading any other operator variable now gets `undefined`; and a timeout is a real SIGTERM-then-SIGKILL with the broker refusing further capability calls, replacing a `Promise.race` that cancelled nothing and let a "timed out" hook go on writing DNS and firewall state (celilo#1003). Capability PROVIDER factories still load in-process — they ARE the broker's implementation. Stages 1 and 2 of `openspec/changes/hook-process-boundary`; the filesystem is claimed by the jail below, and SSH reachability by the remote-ops broker next.
 - **Unjailed advisory lint (task 4.7, NOT a security boundary)** — `apps/celilo/src/hooks/unjailed-lint.ts`. Where there is no jail backend the executor passes the run's derived mount set to the shim in the environment (`CELILO_HOOK_MOUNT_SET`), and the shim wraps the path-taking `node:fs` / `node:fs/promises` functions so an access outside the set (or a write to a read-only row) warns through the hook's own logger: "on a jailed host this would fail", and that it is advisory. It is the mount-set derivation's SECOND consumer, so it cannot drift from what the jail enforces. It observes JS-level `node:fs` calls only — module code bypasses it trivially — and it must never be described as a boundary, in code or output.
 - **Remote-ops broker (reachability scoped by the credential, stage 3 / D12)** — `apps/celilo/src/hooks/remote-broker.ts` (`startRemoteBroker`, `RemoteAccessPolicy`) answering a SECOND socket beside the capability one, with the policy in `apps/celilo/src/services/remote-access.ts` (`remoteAccessPolicy`) and the asking half inside `@celilo/capabilities`' own remote primitives (`packages/capabilities/src/remote.ts`, "The hook remote-ops bridge"). The jail binds no `~/.ssh`, so a hand-built `ssh` cannot authenticate; the primitives detect `CELILO_HOOK_REMOTE_SOCKET`, send each operation as a STRUCTURED request (never a shell string — the broker rebuilds the ssh line itself), and the broker checks the target against `ownedSystemModuleIds` + `getModuleSystems` before running anything, refusing with the module, the target, and the capability route named. Requests carrying the module's OWN credential (an `identityFile` crossing as content and materialised per call, or `installAuthorizedKey`'s password — the cPanel case) are scoped by that credential instead; an explicit non-root user likewise, because the fleet key's authority is root on fleet systems. Stream primitives' LOCAL paths are confined to the run's granted roots (stateDir, screenshots, generated/, declared path inputs), or `streamBackup` would be a write-as-celilo oracle. Attribution is by the module that PERFORMS the operation: a hook's request to the hook's module (the nine `invokeHook` sites build the policy), a provider's transport to the provider's module — providers run in-process and do not cross this socket, and `public_web`'s hand-built upload was replaced by the Ansible static-content converge (capability-owned-tables stage 4, celilo#1014). Residual, recorded rather than papered over: a hook can still `fetch()` any HTTP endpoint directly; only `probeHttp` consults the target check.
-- **Hook jail (a hook sees the paths it was given, and nothing else)** — `apps/celilo/src/hooks/mount-set.ts` (`deriveMountSet`, `toBwrapArgs`, `forbiddenPaths` — PURE, computes a filesystem view and touches nothing) and `apps/celilo/src/hooks/jail.ts` (`detectJailBackend`, `planJailedSpawn`, `realpathRequest`, `runtimeModulePathsFor`, `recordJailMode` — the half that touches the machine). `executeHookScript` spawns the shim under `bwrap` with the module's tree read-only, `state/` + `generated/` + this run's `screenshots/<run>` read-write on top of it, each contract-declared path input at its declared access, the broker's socket directory, the runtime and the `node_modules` the shim resolves through, and `/tmp` a fresh tmpfs FIRST so it cannot erase the socket or a staged input. `~/.ssh` is deliberately NOT bound (stage 3, D12): withholding the credential is what makes the remote-ops broker's target check a boundary. **The acceptance criterion is absence, not a check**: the module store and the data directory are simply not bound, so `master.key` and a sibling module give `ENOENT`. The set is DERIVED — a module cannot ask for more — and `bwrap` itself is never in it, because the AppArmor profile grants `userns` to `/usr/bin/bwrap` for anyone on the box (design D9). Backend detection RUNS bubblewrap rather than looking for it (four different denials all leave the binary in place), and the resulting mode is written to `hook-jail-mode.json` beside celilo's other per-machine state rather than logged, so a host that stops jailing is readable. `CELILO_HOOK_JAIL` = `auto` (default) / `required` / `off`. macOS has a `sandbox-exec` backend in the union, but `auto` defers on it (ce-29z: sandbox-exec DENIES undeclared writes where bubblewrap masks them, and D14's declared-path mechanism is not built), so the hook runs unjailed with the mode recorded; `required` bypasses the deferral for an operator who opts in. An `unjailed` record carries `lastJailed` (the jailed record it replaced on the same host), which is what the `hook_jail` self-monitor reads (`services/alerting/hook-jail.ts`, created unsuppressible by `celilo monitor add hook_jail`) to alert on a host that used to jail and has stopped. `celilo system doctor`'s "Hook execution" section (`renderHookExecutionSection`) reports the live mode and, when unjailed, why.
+- **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. The policy is `auto` / `required` / `off`, resolved in a fixed precedence: the `CELILO_HOOK_JAIL` environment variable, then the stored `hooks.jail_policy` system config key (`celilo system config set hooks.jail_policy <value>`, which asks an interview question before writing `off` unless `--force`), then the default, which is **`off`** (ce-rez7). Jailing begins because an operator set a policy, never because an upgrade installed a backend — celilo-mgr's 2026-09-07 move to 1:2.2.1 installed bubblewrap and loaded the AppArmor profile and hooks kept running unjailed, which is the ruling working. `resolveJailPolicy` returns the source alongside the policy and `system doctor` renders it, so an effective value is always locatable. 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`.

package/README.md

@@ -1536,7 +1536,7 @@ When debugging issues, check:
 ### Getting Help
 
 **Documentation**:
-- [CLAUDE.md](../../CLAUDE.md) - Engineering standards
+- [AGENTS.md](../../AGENTS.md) - Engineering standards
 - [TESTING_STRATEGY.md](../../reference/TESTING_STRATEGY.md) - Testing approach
 - [IDENTIFIER_NAMING_CONVENTIONS.md](../../reference/IDENTIFIER_NAMING_CONVENTIONS.md) - Naming rules
 - [TEMPLATE_VARIABLE_SYNTAX.md](../../reference/TEMPLATE_VARIABLE_SYNTAX.md) - Variable syntax

package/drizzle/0032_module_jail_policies.sql

@@ -0,0 +1,28 @@
+-- Per-module hook jail policy (openspec/changes/per-module-jail-policy, task 1.1).
+--
+-- The operator's row in the four-step precedence, ranked between the
+-- `CELILO_HOOK_JAIL` environment variable and the system-wide
+-- `hooks.jail_policy` key. One row per module; an ABSENT row means "follow
+-- the system", so there is no default column to get wrong and no way to
+-- distinguish "not set" from "set to the same value as the system".
+--
+-- `module_id` is both the primary key and the FK (same shape as
+-- `module_instances`): a policy cannot exist without the module row it
+-- names, and dropping the module row drops this. The row must never
+-- outlive the module it governs — an exemption for a module that no longer
+-- exists is a finding that names a ghost.
+--
+-- No CHECK constraint on `policy` on purpose. The set-time validation lives
+-- in the `module jail` verb, and the read-time validation lives in
+-- `resolveJailPolicy`, which throws rather than coercing (peba's ruling on
+-- ce-8832, applied to the system key). A restored or hand-edited junk value
+-- fails loudly on the next hook invocation or doctor run; a CHECK would
+-- trade that loud failure at two sites for a silent one at insert time.
+-- The drizzle type keeps the union honest inside the codebase.
+
+CREATE TABLE `module_jail_policies` (
+	`module_id` text PRIMARY KEY NOT NULL,
+	`policy` text NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade
+);

package/drizzle/0033_build_bus_hook_runs.sql

@@ -0,0 +1,37 @@
+-- Durable outcome record for build-bus `on_upstream_publish` hook runs.
+--
+-- The hook dispatcher (services/build-bus/hook-dispatcher.ts) is the only
+-- component that runs a module's self-update script, and until now its
+-- outcomes lived nowhere but the daemon's console output: a failed
+-- self-update left no row any surface could read, so `system doctor`
+-- reported the event dispatcher healthy while the CLI on the box aged in
+-- place (celilo#1304). Every `on_upstream_publish` result lands here, one
+-- row per (event, module, hook) execution.
+--
+-- Not event-bus `deliveries`: those record the SQLite bus dispatcher's own
+-- subscriber handlers. The build-bus receiver emits `build-bus.publish`
+-- onto that bus for the record, but hooks run from the receiver's
+-- in-process dispatcher, which no delivery row was ever written for.
+--
+-- `exit_code` is NULLABLE on purpose: a spawn failure (bash missing, EACCES)
+-- never produces an exit code, and recording 0/1 there would conflate "the
+-- script ran and said no" with "the script never ran".
+
+CREATE TABLE `build_bus_hook_runs` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`event_id` text NOT NULL,
+	`package_name` text NOT NULL,
+	`package_version` text NOT NULL,
+	`tag` text NOT NULL,
+	`module_id` text NOT NULL,
+	`hook_name` text NOT NULL,
+	`script_path` text NOT NULL,
+	`exit_code` integer,
+	`timed_out` integer DEFAULT 0 NOT NULL,
+	`duration_ms` integer NOT NULL,
+	`stdout_tail` text,
+	`stderr_tail` text,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `build_bus_hook_runs_created_at_idx` ON `build_bus_hook_runs` (`created_at`);

package/drizzle/meta/_journal.json

@@ -225,6 +225,20 @@
       "when": 1788768000000,
       "tag": "0031_module_config_source",
       "breakpoints": true
+    },
+    {
+      "idx": 32,
+      "version": "6",
+      "when": 1788982143000,
+      "tag": "0032_module_jail_policies",
+      "breakpoints": true
+    },
+    {
+      "idx": 33,
+      "version": "6",
+      "when": 1789082481000,
+      "tag": "0033_build_bus_hook_runs",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

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

package/schemas/system_config.json

@@ -118,6 +118,11 @@
       "type": "string",
       "description": "SSH public key for container access"
     },
+    "hooks.jail_policy": {
+      "type": "string",
+      "pattern": "^(auto|off|required)$",
+      "description": "Hook jail policy: 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off' (hooks run unjailed). Precedence: the CELILO_HOOK_JAIL environment variable wins over this stored value. Run 'celilo system doctor' to see the effective policy and which source it came from."
+    },
     "public_dns.resolver": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",

package/src/__integration__/container-services-cli.integration.test.ts

@@ -25,7 +25,7 @@ describe('Container Services and Machine Pool CLI Integration', () => {
   });
 
   afterEach(async () => {
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    delete process.env.CELILO_MASTER_KEY_PATH;
     await ctx.cleanup();
   });
 

package/src/ansible/inventory.test.ts

@@ -4,6 +4,7 @@ import { rm } from 'node:fs/promises';
 import { type DbClient, createDbClient } from '../db/client';
 import { systemConfig } from '../db/schema';
 import { upsertModuleConfig } from '../services/module-config';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   buildHostVars,
   buildSystemVars,
@@ -286,7 +287,7 @@ describe('Database integration', () => {
   afterEach(async () => {
     db.$client.close();
     // Clean up environment variable
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     if (existsSync(TEST_DB_PATH)) {
       await rm(TEST_DB_PATH);
     }

package/src/api/sessions.test.ts

@@ -32,6 +32,7 @@ import { handleModuleUpdate } from '../cli/commands/module-update';
 import { getDb } from '../db/client';
 import { modules } from '../db/schema';
 import { RESPONDER_PROBE_EVENT } from '../services/responder-probe';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { SessionWriter, listSessions, reapExpiredSessions } from './sessions';
 
 const NO_SCHEMAS = defineEvents({});
@@ -99,10 +100,10 @@ beforeEach(() => {
 afterEach(() => {
   server.stop(true);
   rmSync(dir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
-  process.env.CELILO_DATA_DIR = undefined;
-  process.env.CELILO_ORIGINAL_CWD = undefined;
-  process.env.EVENT_BUS_DB = undefined;
+  resetTestDbPath();
+  delete process.env.CELILO_DATA_DIR;
+  delete process.env.CELILO_ORIGINAL_CWD;
+  delete process.env.EVENT_BUS_DB;
 });
 
 test('an expired session is reaped and the command reports abandoned, not declined', async () => {

package/src/api-clients/proxmox.ts

@@ -38,7 +38,8 @@ async function makeProxmoxRequest<T>(
   credentials: ProxmoxCredentials,
   path: string,
 ): Promise<ProxmoxResult<T>> {
-  return new Promise((resolve) => {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  return new Promise<ProxmoxResult<T>>((resolve) => {
     try {
       const { api_url, api_token_id, api_token_secret } = credentials;
       const authHeader = `PVEAPIToken=${api_token_id}=${api_token_secret}`;
@@ -114,17 +115,17 @@ async function makeProxmoxRequest<T>(
         });
       });
 
-      // Fail fast instead of hanging on an unreachable host (no implicit timeout
-      // on https.request). Callers treat a failed result as "couldn't reach
-      // Proxmox" and fall back accordingly.
-      req.setTimeout(15_000, () => {
-        req.destroy();
+      // Bound the entire request, including connection establishment. On Bun
+      // 1.4, req.setTimeout does not bound a connection to an unreachable host.
+      // Callers need a failed result so they can fall back instead of hanging.
+      timeout = setTimeout(() => {
         resolve({
           success: false,
           message: 'Request timed out',
           details: { timeoutMs: 15_000 },
         });
-      });
+        req.destroy();
+      }, 15_000);
 
       req.end();
     } catch (error) {
@@ -134,6 +135,8 @@ async function makeProxmoxRequest<T>(
         details: { error: String(error) },
       });
     }
+  }).finally(() => {
+    if (timeout !== undefined) clearTimeout(timeout);
   });
 }
 

package/src/cli/backup-rename.test.ts

@@ -16,6 +16,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { runCli } from './index';
 
 describe('celilo module backup (renamed surface)', () => {
@@ -27,7 +28,7 @@ describe('celilo module backup (renamed surface)', () => {
     dir = mkdtempSync(join(tmpdir(), 'celilo-rename-test-'));
     process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
     process.env.CELILO_MASTER_KEY_PATH = join(dir, 'master.key');
-    process.env.CELILO_SUPPRESS_DEPRECATION = undefined;
+    delete process.env.CELILO_SUPPRESS_DEPRECATION;
     await runMigrations(process.env.CELILO_DB_PATH);
 
     warnings = [];
@@ -48,9 +49,9 @@ describe('celilo module backup (renamed surface)', () => {
       warnSpy = null;
     }
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
-    process.env.CELILO_SUPPRESS_DEPRECATION = undefined;
+    resetTestDbPath();
+    delete process.env.CELILO_MASTER_KEY_PATH;
+    delete process.env.CELILO_SUPPRESS_DEPRECATION;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/cli/cli.test.ts

@@ -8,6 +8,7 @@ import { moduleConfigs, modules, secrets } from '../db/schema';
 import { encryptSecret } from '../secrets/encryption';
 import { generateMasterKey, writeMasterKey } from '../secrets/master-key';
 import { upsertModuleConfig } from '../services/module-config';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { runCli } from './index';
 
 const TEST_DB_PATH = `./test-cli-${Date.now()}-${Math.random()}.db`;
@@ -146,8 +147,8 @@ description: Test module for CLI
     }
 
     // Clear environment variables
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
-    process.env.CELILO_DB_PATH = undefined;
+    delete process.env.CELILO_MASTER_KEY_PATH;
+    resetTestDbPath();
   });
 
   describe('help', () => {

package/src/cli/commands/console-get-chain.test.ts

@@ -15,6 +15,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { resetTestDbPath } from '../../test-utils/db-path';
 
 let testDir: string;
 
@@ -26,7 +27,7 @@ beforeEach(() => {
 
 afterEach(() => {
   rmSync(testDir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
 });
 
 /** The live fleet's firewall shape: caddy on iptables, iptables on the router. */

package/src/cli/commands/events.test.ts

@@ -28,7 +28,7 @@ describe('celilo events command handlers', () => {
     process.env.EVENT_BUS_DB = dbPath;
   });
   afterEach(() => {
-    process.env.EVENT_BUS_DB = undefined;
+    delete process.env.EVENT_BUS_DB;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {
@@ -284,7 +284,7 @@ describe('celilo events list-failed', () => {
     bus.close();
   });
   afterEach(() => {
-    process.env.EVENT_BUS_DB = undefined;
+    delete process.env.EVENT_BUS_DB;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

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

@@ -12,6 +12,7 @@ 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';
+import { resetTestDbPath } from '../../test-utils/db-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
@@ -67,9 +68,9 @@ beforeEach(() => {
 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;
+  resetTestDbPath();
+  delete process.env.CELILO_DATA_DIR;
+  delete process.env.CELILO_MASTER_KEY_PATH;
 });
 
 describe('celilo firewall interface list', () => {

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

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'bun:test';
+import type { Machine } from '../../types/infrastructure';
+import { machineListJson } from './machine-list';
+
+const AT = Date.UTC(2026, 8, 8, 22, 59, 59);
+
+function machine(partial: Partial<Machine> = {}): Machine {
+  return {
+    id: '3f6c2a44-1f0e-4a5b-9c8d-7e6f5a4b3c2d',
+    hostname: 'forgejo',
+    zone: 'dmz',
+    ipAddress: '10.0.20.5',
+    sshUser: 'peba',
+    // A real row always carries one; the JSON must not.
+    sshKeyEncrypted: '{"v":1,"sealed":"secret"}',
+    hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 128, arch: 'arm64' },
+    role: 'host',
+    interfaces: [{ name: 'eth0', ipAddress: '10.0.20.5', zone: 'dmz' }],
+    earmarkedModule: null,
+    apiOnly: false,
+    createdAt: new Date(AT),
+    updatedAt: new Date(AT),
+    ...partial,
+  };
+}
+
+function parse(machines: Machine[]): unknown[] {
+  const result = machineListJson(machines);
+  if (!result.success) throw new Error(result.error);
+  return JSON.parse(result.message ?? 'null') as unknown[];
+}
+
+describe('machineListJson', () => {
+  test('output parses as a machine-readable JSON array', () => {
+    const rows = parse([machine()]);
+    expect(Array.isArray(rows)).toBe(true);
+  });
+
+  test('the encrypted SSH key envelope is not in the payload', () => {
+    // Machine-readable output gets piped into scripts and stored in
+    // artifacts. A secret envelope in every listing is worse than a
+    // missing field in a terminal table.
+    const [row] = parse([machine()]) as Array<Record<string, unknown>>;
+    expect(row).not.toHaveProperty('sshKeyEncrypted');
+    expect(row.sshUser).toBe('peba');
+  });
+
+  test('timestamps survive as exact instants, not strings', () => {
+    const [row] = parse([machine()]) as Array<Record<string, unknown>>;
+    expect(row.createdAt).toBe(AT);
+    expect(row.updatedAt).toBe(AT);
+  });
+
+  test('an empty pool is a valid answer, not an error', () => {
+    expect(parse([])).toEqual([]);
+  });
+});

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

@@ -9,28 +9,59 @@ import {
   getModulesOnMachine,
   listMachines,
 } from '../../services/machine-pool';
+import type { Machine } from '../../types/infrastructure';
 import { celiloIntro } from '../prompts';
 import type { CommandResult } from '../types';
 
+/**
+ * Machine-readable rows for `machine list --json`. One row per machine,
+ * with the same fields the human table renders. The encrypted SSH key
+ * envelope is deliberately absent: machine-readable output travels into
+ * scripts, logs and artifacts, where a secret is one more copy to leak.
+ */
+export function machineListJson(machines: Machine[]): CommandResult {
+  const payload = machines.map((machine) => ({
+    id: machine.id,
+    hostname: machine.hostname,
+    zone: machine.zone,
+    ipAddress: machine.ipAddress,
+    sshUser: machine.sshUser,
+    role: machine.role,
+    hardware: machine.hardware,
+    interfaces: machine.interfaces,
+    earmarkedModule: machine.earmarkedModule,
+    apiOnly: machine.apiOnly,
+    createdAt: machine.createdAt.getTime(),
+    updatedAt: machine.updatedAt.getTime(),
+  }));
+
+  // `rawOutput` keeps the payload out of the decorating renderer, which
+  // would wrap it and stop it parsing (celilo#698).
+  return { success: true, message: JSON.stringify(payload, null, 2), rawOutput: true };
+}
+
 /**
  * Handle machine list command
  *
  * @param args - Command arguments (unused)
- * @param flags - Command flags (--zone filter)
+ * @param flags - Command flags (--zone filter, --json for machine-readable output)
  */
 export async function handleMachineList(
   _args: string[],
   flags: Record<string, boolean | string> = {},
 ): Promise<CommandResult> {
   try {
-    celiloIntro('Machine Pool');
-
-    // Apply zone filter if provided
     const filters: MachineFilters = {};
     if (flags.zone && typeof flags.zone === 'string') {
       filters.zone = flags.zone as NetworkZone;
     }
 
+    if (flags.json) {
+      return machineListJson(await listMachines(filters));
+    }
+
+    celiloIntro('Machine Pool');
+
     const machines = await listMachines(filters);
 
     if (machines.length === 0) {

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

@@ -12,6 +12,7 @@ import { join } from 'node:path';
 import { type DbClient, getDb } from '../../db/client';
 import { moduleConfigs, modules } from '../../db/schema';
 import { resolveDeployPosture } from '../../services/deploy-posture';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import {
   FRAMEWORK_CONFIG_KEYS,
   handleModuleConfigGet,
@@ -51,7 +52,7 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
   });
 
   test('rejects an infrastructure-managed key (no silent accept-then-override)', async () => {

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

@@ -14,7 +14,7 @@ import type { CommandResult } from '../types';
  * Handle module deploy command
  *
  * Usage:
- *   celilo module deploy <module-id> [--debug] [--preflight] [--verbose]
+ *   celilo module deploy <module-id> [--debug] [--preflight] [--verbose] [--keep]
  *
  * Note: there is no `--no-interactive` flag. The deploy interview
  * runs through the bus event system; automation answers via a
@@ -59,8 +59,14 @@ export async function handleModuleDeploy(
   const debug = hasFlag(flags, 'debug');
   const verbose = hasFlag(flags, 'verbose');
   const stopAfterInterview = hasFlag(flags, 'stop-after-interview');
+  const keepGeneratedProject = hasFlag(flags, 'keep');
 
-  const result = await deployModule(moduleId, db, { debug, verbose, stopAfterInterview });
+  const result = await deployModule(moduleId, db, {
+    debug,
+    verbose,
+    stopAfterInterview,
+    keepGeneratedProject,
+  });
 
   if (!result.success) {
     return {

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

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ModuleManifest } from '../../manifest/schema';
+import { missingBuildOutputs } from './module-generate';
+
+const DECLARED = join('ansible', 'roles', 'fixture', 'files', 'binary');
+
+function manifestWithArtifacts(artifacts: string[]): ModuleManifest {
+  return {
+    celilo_contract: '1.0',
+    id: 'fixture',
+    name: 'Fixture',
+    version: '1.0.0',
+    description: 'fixture',
+    build: { command: 'true', artifacts },
+  } as ModuleManifest;
+}
+
+describe('missingBuildOutputs', () => {
+  let payload: string;
+
+  beforeEach(() => {
+    payload = mkdtempSync(join(tmpdir(), 'celilo-missing-outputs-'));
+  });
+
+  afterEach(() => {
+    rmSync(payload, { recursive: true, force: true });
+  });
+
+  test('names the declared output the payload is missing', () => {
+    expect(missingBuildOutputs(payload, manifestWithArtifacts([DECLARED]))).toEqual([DECLARED]);
+  });
+
+  test('reports nothing when the payload carries its declared outputs', () => {
+    mkdirSync(join(payload, 'ansible', 'roles', 'fixture', 'files'), { recursive: true });
+    writeFileSync(join(payload, DECLARED), 'built-bytes');
+    expect(missingBuildOutputs(payload, manifestWithArtifacts([DECLARED]))).toEqual([]);
+  });
+
+  test('reports nothing for a module with no build block', () => {
+    expect(
+      missingBuildOutputs(payload, {
+        celilo_contract: '1.0',
+        id: 'fixture',
+        name: 'Fixture',
+        version: '1.0.0',
+        description: 'fixture',
+      } as ModuleManifest),
+    ).toEqual([]);
+  });
+});