@celilo/cli 1.4.0 → 1.5.0

package/CELILO_SUBSYSTEMS.md

@@ -29,7 +29,7 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 - **Zone detection / system config** — `apps/celilo/src/services/zone-detector.ts` — `detectZoneFromIp` reads `network.<zone>.subnet` from the `systemConfig` table and returns `NetworkZone | 'unknown'`. It answers CONTAINMENT ONLY. It used to return `'external'` on no-match, which conflated "no declared subnet contains this" with "the internet can route to this" — on a firewall with five RFC1918 legs that reported four of them as facing the internet. `'unknown'` is the honest answer; the caller resolves it (see `machine add`: publicly routable → `external`, otherwise fail asking for `--zone`). The subnet-backed zone list is derived from `NETWORK_ZONES` minus `external`, which has no subnet and must never be given one.
 - **Interface classification** — `packages/capabilities/src/interface-classification.ts` — THE shared classifier, used by the backend and every firewall provider module so the two cannot drift apart again. `isPubliclyRoutable(ip)` is a property of the address alone (false for RFC 1918, RFC 6598 carrier-grade NAT, loopback, link-local, multicast, reserved). `classifyInterfaces(interfaces, zones)` assigns each interface `zone → external → alien`, first match winning, where `external` is the RESIDUAL — routable and claimed by no declared zone — and is never subnet-matched. `externalEdge()` returns none/single/**ambiguous** rather than silently picking the first public address. `defaultRouteFinding()` enforces the invariant that the default route leaves through `internal` or `external`. **`subnetContains(cidr, ip)` lives here and is the ONLY implementation** — three existed and disagreed (the backend's mishandled `/0`); the other two are deleted, not aliased. Design: `openspec/changes/firewall-interface-classification/design.md`.
 - **Declared networks (classification input)** — `readDeclaredNetworks(db)` in `apps/celilo/src/hooks/capability-loader.ts` — every `network.<name>.subnet` in system config, which is what an interface is attributed against. Read from the CONFIG, not from `NETWORK_ZONES`: celilo holds networks that are not placement zones (`network.control-plane-vpn.subnet`, which `wireguard` requires and reads). Injected into the firewall capability as a LIVE reader (`declaredNetworks`) — that liveness was a mitigation for values written mid-run by a module hook, which `network-declaration` removes; see that spec before assuming a snapshot is still unsafe.
-- **Network requirement + ensure (celilo owns the namespace)** — `apps/celilo/src/services/network-ensure.ts` (`ensureRequiredNetworks`), `NetworkRequirementSchema` / `getRequiredNetworkNames` in `apps/celilo/src/manifest/schema.ts`. A module declares `requires.networks: [{name}]` — a NAME, never a value; the schema is `.strict()` so a `subnet:` on the requirement is rejected with a message saying why. The deploy calls `ensureRequiredNetworks` in its interview phase, BEFORE generation and before any hook, and asks over the generic bus interview (`askText`, so it is answerable headless) for anything undefined. Which attributes a network has is celilo's answer, taken from `apps/celilo/schemas/system_config.json`: that file declares `network.<n>.gateway` for the routed segments and omits it for `control-plane-vpn`, so a gateway is never asked for a network that has none. Well-known names carry a `suggested` range there — deliberately NOT `default`, which `getDefaultConfiguration()` would seed at `system init`. Spec: `openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md`.
+- **Network requirement + ensure (celilo owns the namespace)** — `apps/celilo/src/services/network-ensure.ts` (`ensureRequiredNetworks`), `NetworkRequirementSchema` / `getRequiredNetworkNames` in `apps/celilo/src/manifest/schema.ts`. A module declares `requires.networks: [{name}]` — a NAME, never a value; the schema is `.strict()` so a `subnet:` on the requirement is rejected with a message saying why. The deploy calls `ensureRequiredNetworks` in its interview phase, BEFORE generation and before any hook, and asks over the generic bus interview (`askText`, so it is answerable headless) for anything undefined. Which attributes a network has is celilo's answer, taken from `apps/celilo/schemas/system_config.json`: that file declares `network.<n>.gateway` for the routed segments and omits it for `control-plane-vpn`, so a gateway is never asked for a network that has none. Well-known names carry a `suggested` range there — deliberately NOT `default`, which `getDefaultConfiguration()` would seed at `system init`. Spec: `openspec/specs/network-declaration/spec.md`.
 - **The network write path (closed) + celilo's own discovery** — `celilo system apply-config` (`apps/celilo/src/cli/commands/system-apply-config.ts`) REFUSES the whole `network.` namespace, `network.bridge` excepted (a Proxmox bridge name is not addressing, and it is the one network key with a schema default). That is the automation surface a module hook shells out to, so closing it there is what makes "networks are celilo's" an authority rather than a convention every module has to remember. The refusal names the alternative — declare the network, read it with `$system:` — because a bare rejection sends a module author hunting for a typo. The one write that legitimately needed the surface moved INTO celilo: `celilo system discover-network` (`apps/celilo/src/services/network-discovery.ts`, `cli/commands/system-discover-network.ts`) parses the box's own `ip route` and records `network.internal.*` — or `network.secure-mgmt.*` when the box is off the internal LAN (#300). `celilo-mgmt` calls it and decides nothing; it used to parse and write this itself. Idempotent and never overwrites addressing already set. Recurrence gate: `test-integration/module/no-module-writes-networks.test.ts`.
 - **Firewall interface audit** — `apps/celilo/src/services/audit/interface-classification.ts` — reports per-firewall classification in `celilo audit`: alien interfaces by name and address (drift), and the blocking findings a converge refuses on — a carrier-grade NAT leg, an ambiguous external edge, a default route on the wrong leg.
 - **Zone taxonomy (canonical list)** — `apps/celilo/src/db/schema.ts` — `NETWORK_ZONES` is the single array; `NetworkZone` is DERIVED from it. Never hand-maintain a second copy: a duplicate that dropped a member made zone validation return null and silently fall back to a wrong-but-valid zone.
@@ -181,7 +181,7 @@ runner seam (`execRunner` real / `createMockRunner` for tests) lives in
   - **Inbound** (`reconcileAspectsForSystems`): every approved aspect applied to systems that have just come into existence. Called from `module-deploy.ts` between `waitForSSH` and `executeAnsible` (so a module's playbook and `on_install` see a correctly configured host) and from `machine-add.ts`. Eligibility is `applicable_zones` + approval; the aspect's `triggers` list is deliberately NOT consulted, so convergence is not opt-in per manifest. A failure here IS fatal to the deploy that created the system — the aspect is a prerequisite of that host — while a failure on `machine add` is only a warning. PAUSED providers are skipped, which is the escape hatch for a wedged aspect. Nothing is rolled back: rows, guest and IPAM allocation persist and a re-run converges on the same system. Fixes celilo#902, where a system provisioned after its provider deployed silently never received the aspect. See `openspec/changes/aspect-fanout-new-systems/`.
   - **Coverage verification** — `verifyAspectCoverage` + `celilo system doctor --deep [--fix]`. Answers "is any system missing an aspect its zone entitles it to" WITHOUT stored state: the entitled set is `planAspectFanOut` itself, and coverage is measured by evaluating the role against the host in Ansible check mode (`executeAnsible({check:true})` + `parseAnsibleRecap`). Three outcomes, not two — `changed=0,skipped=0` applied, `changed>0` missing, **`skipped>0` unknown**, because check mode SKIPS a task it cannot evaluate and a `command`/`shell` role would otherwise report clean having never run.
 - **In-flight operation lock** — `apps/celilo/src/services/module-operations.ts` — `startOperation`/`completeOperation`/`failOperation` record deploy/uninstall/backup/restore in `module_operations`; `refuseIfInFlight`/`checkInFlight` are what backup and restore consult. Deploy and uninstall REGISTER but never check: it is a one-way guard protecting backup/restore consistency, not a general mutex (`openspec/specs/management-server-backup/spec.md` "In-flight operation refusal"). A row stops holding the lock once it is GONE, STOPPED/zombie (`isPidRunnable`, `ps -o state=` — `kill(pid,0)` calls a Ctrl-Z'd process alive), or older than `OPERATION_TTL_MS` (2h). The TTL is not redundancy: a pid is a recycled number, and once the pid space wraps an old row names an unrelated healthy process. Operator surface: `celilo module operations [list|clear] [--abandoned] [--all]` (`apps/celilo/src/cli/commands/module-operations.ts`); `list` shows only what holds the lock, abandoned rows are summarised unless `--abandoned`. Abandoned rows are reclaimed hourly by the `celilo-operations-sweep` bus subscriber (`timer.tick.1h` → `celilo module operations clear`, armed by `ensureOperationsSweepSubscriber` from module registration and `celilo system migrate`). `clear` MARKS rows failed rather than deleting them, and that is load-bearing: the `abandoned_operations` audit reads exactly those released rows to notice one module's operation dying over and over.
-- **Module pause / unpause (control-plane quiescence)** — `apps/celilo/src/services/module-pause.ts` — pure `planPause`/`planUnpause` producing an ordered plan, `executePause`/`executeUnpause` performing it, plus `listPausedModules`/`pausedAmong`/`formatPausedDuration`/`describePausedModule` (the ONE place an age is formatted). CLI: `apps/celilo/src/cli/commands/module-pause.ts` (`celilo module pause|unpause <id> [--cascade] [--stop-infra] [--reason] [--dry-run] [--yes]`). Pausing takes a module out of the CONTROL plane — no dispatched events, no timer hooks, no health checks, alerts suppressed — while leaving the DATA plane running, because capability consumption is deploy-time: every consumer calls `firewall`/`dhcp_server` from `on_install` and nothing calls it while serving. Config, secrets, IPAM/VMID and placement are preserved; `on_uninstall` does NOT run. Quiescence is enforced in two places: pausing drops the module's bus subscriptions (`unregisterModuleSubscriptions`), and `run-named-hook.ts` refuses any non-lifecycle hook for a PAUSED module (`skippedPaused`), which catches the paths that skip the bus — `events resync-subscriptions`, a restore that starts events.db empty, aspect fan-out, public-web republish. `on_install`/`on_uninstall` are exempt by hook NAME (not a caller flag): unpause redeploys through `on_install`, and removing a paused provider needs `on_uninstall`. Unpause always REDEPLOYS (`deployModule`) — that is what rebinds a consumer to a replacement provider and recreates provider-local state from the consumers that own it — and re-registers subscriptions, which a plain deploy does not do. A failed unpause restores `PAUSED` rather than leaving the module live and mis-bound. Cascade order reuses `services/update/dep-graph.ts` unchanged (pause = consumers first, unpause = providers first) and is computed from the GRAPH, never from which modules are currently paused, so a cascade walks THROUGH already-done members and is resumable. See `openspec/changes/module-pause-lifecycle/`.
+- **Module pause / unpause (control-plane quiescence)** — `apps/celilo/src/services/module-pause.ts` — pure `planPause`/`planUnpause` producing an ordered plan, `executePause`/`executeUnpause` performing it, plus `listPausedModules`/`pausedAmong`/`formatPausedDuration`/`describePausedModule` (the ONE place an age is formatted). CLI: `apps/celilo/src/cli/commands/module-pause.ts` (`celilo module pause|unpause <id> [--cascade] [--stop-infra] [--reason] [--dry-run] [--yes]`). Pausing takes a module out of the CONTROL plane — no dispatched events, no timer hooks, no health checks, alerts suppressed — while leaving the DATA plane running, because capability consumption is deploy-time: every consumer calls `firewall`/`dhcp_server` from `on_install` and nothing calls it while serving. Config, secrets, IPAM/VMID and placement are preserved; `on_uninstall` does NOT run. Quiescence is enforced in two places: pausing drops the module's bus subscriptions (`unregisterModuleSubscriptions`), and `run-named-hook.ts` refuses any non-lifecycle hook for a PAUSED module (`skippedPaused`), which catches the paths that skip the bus — `events resync-subscriptions`, a restore that starts events.db empty, aspect fan-out, public-web republish. `on_install`/`on_uninstall` are exempt by hook NAME (not a caller flag): unpause redeploys through `on_install`, and removing a paused provider needs `on_uninstall`. Unpause always REDEPLOYS (`deployModule`) — that is what rebinds a consumer to a replacement provider and recreates provider-local state from the consumers that own it — and re-registers subscriptions, which a plain deploy does not do. A failed unpause restores `PAUSED` rather than leaving the module live and mis-bound. Cascade order reuses `services/update/dep-graph.ts` unchanged (pause = consumers first, unpause = providers first) and is computed from the GRAPH, never from which modules are currently paused, so a cascade walks THROUGH already-done members and is resumable. See `openspec/specs/module-pause/spec.md`.
 - **Provider-removal guard** — `apps/celilo/src/services/remove-guard.ts` — `findRemovalBlockers`/`describeRemovalRefusal`, called from `apps/celilo/src/cli/commands/module-remove.ts`. A PAUSED module is not a dependent (unpause cannot return it to service without a redeploy, and a redeploy re-resolves capabilities), which is what makes a provider swap possible at all. A dependent is one declaring the capability under `requires` **or** `optional` — the same relation `dep-graph.ts` uses, so the guard and the cascade agree on the set; the guard previously read `requires` alone, which let a removal silently orphan `technitium`'s `optional` `dhcp_server`. Refusals name each blocker AND which declaration makes it one. It deliberately does NOT exempt a dependent because another provider of the same capability exists (celilo#683).
 - **Consumer-removal cleanup (every provider is told)** — `apps/celilo/src/services/consumer-cleanup.ts` — pure `planConsumerCleanup` + `loadConsumerCleanupPlan` + `runConsumerCleanup`, called from `apps/celilo/src/cli/commands/module-remove.ts` after `on_uninstall` and before `terraform destroy`. A capability is two-sided: the consumer asks, the provider mints something in ITS world (a caddy site block, a DNAT rule, an OIDC client at authentik, a registered CI runner), and removal only ever touched one side — the FK cascade dropped celilo's row, so the provider's next converge had no way to learn the thing existed. This dispatches the `on_consumer_removed` hook to every provider of every capability the departing module declared under `requires` OR `optional` (the same relation `remove-guard.ts` counts as a dependency edge), **once per provider** rather than once per capability, sorted by provider id. The hook receives one input, `consumer`, and NOTHING else: a provider that cannot answer "what do I hold for this module" without being told has a different defect — the consumer's id was never recorded at mint time. It replaces `services/web-route-cleanup.ts`, which did the same job for exactly one capability, by name, from core. Semantics that are easy to get backwards: **a failed withdrawal never blocks the removal** — the consumer goes and the failing PROVIDER is marked `ERROR` with the departing consumer named in `error_message` (surfaced as a `blocked` finding by `services/audit/undeployed-modules.ts`), because the hook is a full converge and after a failure the provider's state is unknown rather than "one thing missed". **Dispatch continues past a failure**, so one broken provider cannot leave the others holding state. A PAUSED provider is skipped with a warning naming what it keeps (`run-named-hook.ts` refuses non-lifecycle hooks on a paused module, and `on_consumer_removed` must NOT join `LIFECYCLE_HOOKS`), and a never-deployed one is skipped silently. Providers implementing it: caddy, caddy-internal, iptables, greenwave, axon, authentik, forgejo, generic-cpanel-hosting-provider. See `openspec/changes/consumer-removal-cleanup/`.
 - **Firewall registry ownership** — `apps/celilo/src/services/port-forwards.ts` + `apps/celilo/src/services/trusted-sources.ts`. Both stores are bound to the CONSUMING module and stamp `registered_by` themselves; a caller cannot supply it, so a registration is never attributed to the wrong module. Both writes are **declarative**: `replace()` states a consumer's COMPLETE set for a target, so a port or subnet it previously registered and now omits is withdrawn (celilo#855 — before this, a module that exposed `:8080` and redeployed exposing `:9090` kept both, forever). The owner is IN both unique indexes, not merely beside them: two consumers wanting the same forward are two ROWS, so one leaving cannot delete a rule the other still needs; `modules/iptables/scripts/ruleset-renderer.ts` dedupes on the rule tuple so the pair renders once. Neither column is a FK, so `runConsumerCleanup` deletes these rows explicitly after every provider has converged without them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/module/packaging/build.ts

@@ -6,6 +6,7 @@ import { basename, join, relative } from 'node:path';
 import { create as tarCreate } from 'tar';
 import { parse as parseYaml } from 'yaml';
 import { log } from '../../cli/prompts';
+import { formatViolations, scanModuleDirectory } from '../../policy/module-script-scan';
 import { validateModuleDirectory } from '../import';
 import { computeFileChecksum } from './checksum';
 import { includeNodeModulesPath } from './package-rules';
@@ -175,6 +176,34 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
     return { success: false, error: dirError };
   }
 
+  // Refuse to package a module whose hook scripts hand-build SSH or take the
+  // raw-exec escape hatch without justifying it
+  // (openspec/changes/unified-management-no-ssh/proposal.md).
+  //
+  // The same rules run as a `bun test` gate over this repo's modules. This is
+  // the enforcement point that catches what that one cannot: a module built
+  // outside CI. `bun run publish` is a documented escape hatch for when the
+  // runners are down and it runs no tests, and a module authored outside this
+  // repo never passes through the suite at all — in both cases packaging is the
+  // last place anything looks at the code before it becomes an artifact the
+  // fleet installs.
+  //
+  // Scans the SOURCE scripts, before staging: it fails in under a second rather
+  // than after a `bun pm pack` and a full module build, and the staged copy
+  // bundles `@celilo/capabilities` — whose `remote.ts` builds the very
+  // `ssh … root@` string these rules exist to keep out of module code — so
+  // scanning the bundle would fail every module in the fleet on the
+  // implementation of the primitives they were told to use.
+  const policyViolations = scanModuleDirectory(sourceDir);
+  if (policyViolations.length > 0) {
+    return {
+      success: false,
+      error: `Refusing to package ${basename(sourceDir)}: module script policy violations.\n${formatViolations(
+        policyViolations,
+      )}\n\nSee apps/celilo/MODULE_PRIMITIVES.md.`,
+    };
+  }
+
   // Copy source to a temp dir for building. Strategy:
   // - If the source has a package.json, use `bun pm pack` to respect the
   //   `files` field (or .npmignore), copying only what the build needs.

package/src/policy/module-script-scan.test.ts

@@ -0,0 +1,164 @@
+/**
+ * The scan rules themselves, and the proof that packaging refuses a module that
+ * breaks them.
+ *
+ * `no-hand-built-ssh.test.ts` asserts the CURRENT tree is clean, which is a
+ * different claim: it passes both when the rules work and when they match
+ * nothing. These tests are the ones that fail if a rule stops catching things.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { buildModule } from '../module/packaging/build';
+import { scanModuleDirectory, scanModuleScriptSource } from './module-script-scan';
+
+const rules = (src: string) => scanModuleScriptSource('f.ts', src).map((v) => v.rule);
+
+describe('module script scan — SSH rules', () => {
+  it('catches a hand-built ssh string', () => {
+    expect(rules("run(`ssh root@${ip} 'systemctl restart x'`);")).toContain(
+      'raw ssh invocation (ssh … root@)',
+    );
+  });
+
+  it('catches StrictHostKeyChecking however it is invoked', () => {
+    expect(rules("const c = 'ssh -o StrictHostKeyChecking=no host';")).toContain(
+      'raw ssh invocation (StrictHostKeyChecking)',
+    );
+  });
+
+  it('catches an ssh2 import', () => {
+    expect(rules("import { Client } from 'ssh2';")).toContain("'ssh2' import");
+  });
+
+  it('does not fire on ordinary module code', () => {
+    expect(rules('const x = probe(system, { kind: "systemd", unit: "caddy" }, run);')).toEqual([]);
+  });
+});
+
+describe('module script scan — raw-exec escape hatch', () => {
+  it('flags a runAppCommand call with no justification', () => {
+    expect(rules('const r = runAppCommand(system, "rm -f /tmp/x", run);')).toContain(
+      'unjustified raw-exec escape hatch',
+    );
+  });
+
+  it('flags runAppCommandWithSecret too', () => {
+    expect(rules('const r = runAppCommandWithSecret(system, cli, secret, run);')).toContain(
+      'unjustified raw-exec escape hatch',
+    );
+  });
+
+  it('accepts a call justified immediately above', () => {
+    const src = [
+      '// escape-hatch: forgejo admin user create is CLI-only, no HTTP API path.',
+      'const r = runAppCommand(system, cmd, run);',
+    ].join('\n');
+    expect(rules(src)).toEqual([]);
+  });
+
+  it('accepts a call wrapped in waitFor, justified above the enclosing statement', () => {
+    // The real shape in modules/caddy-internal — the justification sits above
+    // `const ready = await waitFor(`, a few lines up from the call itself.
+    const src = [
+      '// escape-hatch: the command output IS the payload; no API to ask.',
+      'const ready = await waitFor(',
+      '  () =>',
+      '    runAppCommand(target, CMD, run, {',
+      '      timeoutMs: 10_000,',
+      '    }).ok,',
+      ');',
+    ].join('\n');
+    expect(rules(src)).toEqual([]);
+  });
+
+  it('does not let a distant hatch launder a later call', () => {
+    const src = [
+      '// escape-hatch: justifies the call directly below it, and nothing else.',
+      'const a = runAppCommand(system, one, run);',
+      ...Array(12).fill('doSomethingElse();'),
+      'const b = runAppCommand(system, two, run);',
+    ].join('\n');
+    // Exactly one violation: the second call, which has no hatch in reach.
+    expect(rules(src)).toEqual(['unjustified raw-exec escape hatch']);
+  });
+
+  it('does not flag the import of runAppCommand', () => {
+    expect(rules("import { runAppCommand, probe } from '@celilo/capabilities';")).toEqual([]);
+  });
+});
+
+describe('module script scan — what it deliberately does not scan', () => {
+  let dir: string;
+
+  function write(rel: string, content: string): void {
+    const full = join(dir, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+
+  it('ignores bundled node_modules and test files', () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-scan-test-'));
+    try {
+      write('manifest.yml', 'id: demo\n');
+      // @celilo/capabilities legitimately BUILDS the ssh string these rules ban.
+      // Scanning the bundled closure would fail every module in the fleet.
+      write(
+        'scripts/node_modules/@celilo/capabilities/src/remote.ts',
+        'const c = `ssh -o StrictHostKeyChecking=no root@${ip} ${cmd}`;',
+      );
+      write('scripts/setup.test.ts', "run('ssh root@host uptime');");
+      write('scripts/setup.ts', 'export const fine = 1;\n');
+      expect(scanModuleDirectory(dir)).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('packaging refuses a module that breaks the policy', () => {
+  let dir: string;
+
+  function write(rel: string, content: string): void {
+    const full = join(dir, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+
+  it('fails the build, naming the file, line and rule', async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-package-policy-'));
+    try {
+      write('manifest.yml', 'id: demo\nversion: 0.1.0\n');
+      write(
+        'scripts/setup.ts',
+        ['export function bad(ip: string) {', '  return `ssh root@${ip} uptime`;', '}'].join('\n'),
+      );
+
+      const result = await buildModule({ sourceDir: dir });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('scripts/setup.ts:2');
+      expect(result.error).toContain('raw ssh invocation');
+      expect(result.error).toContain('MODULE_PRIMITIVES.md');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('fails the build for an unjustified escape hatch', async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-package-policy-'));
+    try {
+      write('manifest.yml', 'id: demo\nversion: 0.1.0\n');
+      write('scripts/setup.ts', 'const r = runAppCommand(system, "rm -rf /srv", run);\n');
+
+      const result = await buildModule({ sourceDir: dir });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('unjustified raw-exec escape hatch');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/policy/module-script-scan.ts

@@ -0,0 +1,143 @@
+/**
+ * The recurrence gate for openspec/changes/unified-management-no-ssh/proposal.md:
+ * **modules never hand-build SSH, and the one sanctioned raw-exec path is
+ * always justified in writing.**
+ *
+ * ONE definition of the rules, used by both enforcement points:
+ *
+ *   - `apps/celilo/src/policy/no-hand-built-ssh.test.ts` — every in-repo module,
+ *     on every `bun test`.
+ *   - `apps/celilo/src/module/packaging/build.ts` — every `.netapp` at the
+ *     moment it is packaged, including modules that never pass through this
+ *     repo's CI (`bun run publish` is a documented escape hatch and runs no
+ *     tests).
+ *
+ * Deliberately not two copies. The types this repo keeps re-learning that
+ * lesson on — `HookName` (celilo#821), `HookContext` — were duplicated
+ * declarations that drifted silently because nothing fails when two copies
+ * disagree. A scan rule is worse: the duplicate that drifts is the one that
+ * stops catching things, and a gate that stops catching things looks exactly
+ * like a gate with nothing to catch.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export interface ScanViolation {
+  /** Path as the operator should see it — relative to the scanned root. */
+  file: string;
+  /** 1-based line number of the offending line. */
+  line: number;
+  /** Short rule name, e.g. `raw ssh invocation`. */
+  rule: string;
+  /** What to do instead. */
+  hint: string;
+}
+
+/**
+ * How far above a `runAppCommand*` call the justification may sit.
+ *
+ * Calibrated against the real call sites rather than guessed: the convention is
+ * a comment block directly above the call, but a call wrapped in `waitFor(() =>
+ * …)` puts the justification above the ENCLOSING statement, a few lines up. A
+ * window covers both without needing to parse TypeScript. Eight lines is the
+ * widest real gap plus headroom; wide enough to miss nothing legitimate, narrow
+ * enough that an unrelated hatch elsewhere in the function cannot launder a
+ * fresh call.
+ */
+const ESCAPE_HATCH_LOOKBACK_LINES = 8;
+
+const PATTERN_RULES: Array<{ rule: string; re: RegExp; hint: string }> = [
+  {
+    rule: 'raw ssh invocation (StrictHostKeyChecking)',
+    re: /StrictHostKeyChecking/,
+    hint: 'Use a remote-ops primitive (remoteExec/probe/serviceCtl/…). See MODULE_PRIMITIVES.md.',
+  },
+  {
+    rule: 'raw ssh invocation (ssh … root@)',
+    re: /\bssh\s+(?:-\S+\s+|\S*root@)/,
+    hint: 'Use a remote-ops primitive, not a hand-built ssh string. See MODULE_PRIMITIVES.md.',
+  },
+  {
+    rule: "'ssh2' import",
+    re: /(?:from|require\()\s*['"]ssh2['"]/,
+    hint: 'Modules never open their own SSH connection — use the primitives. See MODULE_PRIMITIVES.md.',
+  },
+];
+
+/** A `runAppCommand(` / `runAppCommandWithSecret(` CALL — not the import. */
+const RAW_EXEC_CALL = /\brunAppCommand(?:WithSecret)?\s*\(/;
+
+const ESCAPE_HATCH_MARKER = /escape-hatch:/;
+
+/**
+ * Scan one file's source. Pure — takes the text, returns the violations, so it
+ * is testable without a filesystem and reusable over a staged package.
+ */
+export function scanModuleScriptSource(file: string, source: string): ScanViolation[] {
+  const violations: ScanViolation[] = [];
+  const lines = source.split('\n');
+
+  lines.forEach((text, i) => {
+    for (const { rule, re, hint } of PATTERN_RULES) {
+      if (re.test(text)) violations.push({ file, line: i + 1, rule, hint });
+    }
+
+    if (!RAW_EXEC_CALL.test(text)) return;
+    const from = Math.max(0, i - ESCAPE_HATCH_LOOKBACK_LINES);
+    const justified = lines.slice(from, i).some((l) => ESCAPE_HATCH_MARKER.test(l));
+    if (!justified) {
+      violations.push({
+        file,
+        line: i + 1,
+        rule: 'unjustified raw-exec escape hatch',
+        hint:
+          'runAppCommand* is the ONLY sanctioned raw-exec path and every call site must say why ' +
+          'no capability, HTTP or converge path exists. Add an `// escape-hatch: …` comment ' +
+          'immediately above the call. See MODULE_PRIMITIVES.md.',
+      });
+    }
+  });
+
+  return violations;
+}
+
+/**
+ * Every production `.ts` under a module's `scripts/` — excluding tests and
+ * `node_modules`.
+ *
+ * The exclusion is load-bearing, not tidiness: the shipped closure bundles
+ * `@celilo/capabilities`, whose `remote.ts` builds the `ssh … root@` string
+ * that every one of these rules exists to keep OUT of module code. Scanning it
+ * would fail every module in the fleet on the implementation of the primitives
+ * they were told to use.
+ */
+export function moduleScriptFiles(scriptsDir: string): string[] {
+  if (!existsSync(scriptsDir) || !statSync(scriptsDir).isDirectory()) return [];
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      if (entry === 'node_modules') continue;
+      const p = join(dir, entry);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (p.endsWith('.ts') && !p.endsWith('.test.ts')) out.push(p);
+    }
+  };
+  walk(scriptsDir);
+  return out;
+}
+
+/**
+ * Scan a module directory (the one holding `manifest.yml`). Returns every
+ * violation in its `scripts/`, with paths relative to `moduleDir`.
+ */
+export function scanModuleDirectory(moduleDir: string): ScanViolation[] {
+  return moduleScriptFiles(join(moduleDir, 'scripts')).flatMap((f) =>
+    scanModuleScriptSource(relative(moduleDir, f), readFileSync(f, 'utf-8')),
+  );
+}
+
+/** Render violations for a test failure message or a refused publish. */
+export function formatViolations(violations: ScanViolation[]): string {
+  return violations.map((v) => `  ${v.file}:${v.line}\n    → ${v.rule}. ${v.hint}`).join('\n');
+}

package/src/policy/no-hand-built-ssh.test.ts

@@ -1,24 +1,20 @@
 /**
- * Recurrence gate for openspec/changes/unified-management-no-ssh/proposal.md: **modules never hand-build SSH.**
+ * Recurrence gate for openspec/changes/unified-management-no-ssh/proposal.md: **modules never hand-build SSH,
+ * and every raw-exec escape hatch is justified in writing.**
  *
- * Module hooks reach a remote box through the typed primitives in
- * `@celilo/capabilities` (probe / serviceCtl / applyRenderedConfig / … — see
- * apps/celilo/MODULE_PRIMITIVES.md), never a raw `ssh root@…` string, `ssh2`, or
- * an ad-hoc `child_process` shell-out. This test scans every production module
- * script and fails if a banned pattern reappears, so the SSH-elimination work
- * can't silently erode.
+ * The rules themselves live in `./module-script-scan`, because this is not the
+ * only place they run — `.netapp` packaging applies the same scan at publish
+ * time, which is the enforcement point that also covers a module built outside
+ * this repo's CI. One definition, two callers.
  *
- * Precise on purpose: `noRestrictedImports` can't see raw ssh *strings* (the real
- * risk). We ban the SSH shapes themselves — an `ssh root@…` string catches
- * hand-built SSH however it's invoked (child_process, execSync, or the Runner),
- * and `ssh2` catches the library route. We do NOT ban `child_process` outright:
- * many modules' on_install legitimately shell LOCAL `celilo`/system commands
- * (`celilo system apply-config`), which isn't remote SSH.
+ * This file is the in-repo half: every production module script, on every
+ * `bun test`.
  */
 
 import { describe, expect, test } from 'bun:test';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { formatViolations, moduleScriptFiles, scanModuleDirectory } from './module-script-scan';
 
 /** Walk up from this test to the repo root (the dir holding both modules/ and apps/). */
 function repoRoot(): string {
@@ -30,61 +26,25 @@ function repoRoot(): string {
   throw new Error('could not locate repo root (no ancestor with modules/ + apps/)');
 }
 
-/** Every production `.ts` under modules/<m>/scripts/ (excludes node_modules + tests). */
-function moduleScripts(): string[] {
+function moduleDirs(): string[] {
   const modulesRoot = join(repoRoot(), 'modules');
-  const out: string[] = [];
-  const walk = (dir: string) => {
-    for (const entry of readdirSync(dir)) {
-      if (entry === 'node_modules') continue;
-      const p = join(dir, entry);
-      if (statSync(p).isDirectory()) walk(p);
-      else if (p.endsWith('.ts') && !p.endsWith('.test.ts')) out.push(p);
-    }
-  };
-  for (const mod of readdirSync(modulesRoot)) {
-    const scripts = join(modulesRoot, mod, 'scripts');
-    if (existsSync(scripts) && statSync(scripts).isDirectory()) walk(scripts);
-  }
-  return out;
+  return readdirSync(modulesRoot)
+    .map((m) => join(modulesRoot, m))
+    .filter((d) => statSync(d).isDirectory() && existsSync(join(d, 'scripts')));
 }
 
-const BANNED = [
-  {
-    name: 'raw ssh invocation (StrictHostKeyChecking)',
-    re: /StrictHostKeyChecking/,
-    hint: 'Use a remote-ops primitive (remoteExec/probe/serviceCtl/…). See MODULE_PRIMITIVES.md.',
-  },
-  {
-    name: 'raw ssh invocation (ssh … root@)',
-    re: /\bssh\s+(?:-\S+\s+|\S*root@)/,
-    hint: 'Use a remote-ops primitive, not a hand-built ssh string. See MODULE_PRIMITIVES.md.',
-  },
-  {
-    name: "'ssh2' import",
-    re: /(?:from|require\()\s*['"]ssh2['"]/,
-    hint: 'Modules never open their own SSH connection — use the primitives. See MODULE_PRIMITIVES.md.',
-  },
-];
-
 describe('recurrence gate: modules never hand-build SSH', () => {
-  const scripts = moduleScripts();
+  const dirs = moduleDirs();
 
   test('scans a non-trivial set of module scripts (sanity — the scan actually ran)', () => {
-    expect(scripts.length).toBeGreaterThan(10);
+    const scanned = dirs.flatMap((d) => moduleScriptFiles(join(d, 'scripts')));
+    expect(scanned.length).toBeGreaterThan(10);
   });
 
-  test('no production module script hand-builds SSH (ssh string / ssh2)', () => {
-    const violations: string[] = [];
-    for (const file of scripts) {
-      const src = readFileSync(file, 'utf-8');
-      for (const b of BANNED) {
-        if (b.re.test(src)) violations.push(`${file}\n    → ${b.name}. ${b.hint}`);
-      }
-    }
-    expect(
-      violations,
-      `Hand-built SSH found in module scripts:\n  ${violations.join('\n  ')}`,
-    ).toEqual([]);
+  test('no production module script hand-builds SSH, and every runAppCommand* is justified', () => {
+    const violations = dirs.flatMap((d) => scanModuleDirectory(d));
+    expect(violations, `Module script policy violations:\n${formatViolations(violations)}`).toEqual(
+      [],
+    );
   });
 });

package/src/templates/copy-role-files.test.ts

@@ -0,0 +1,69 @@
+/**
+ * `copyAnsibleRoleFilesDirs` had no test, and celilo#925 is what that cost.
+ *
+ * A module's Ansible role `files/` directory holds static assets — most often a
+ * compiled binary — that cannot go through the utf-8 template pipeline. They are
+ * copied verbatim on every generate. Except they were not: the copy omitted
+ * `force`, which Node defaults to true and bun does not, so the FIRST generate
+ * populated `generated/` and no later one ever replaced it.
+ *
+ * Nothing surfaced it. `cp` reports no error, so the caller's try/catch caught
+ * nothing; Ansible then installed the first binary forever and reported `ok`,
+ * unchanged, while the module's version field advanced past it. On the live
+ * fleet that read as a successful deploy of code that never shipped.
+ *
+ * The overwrite case is therefore the point of this file. A test that only
+ * copied into an empty directory would have passed throughout.
+ */
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { copyAnsibleRoleFilesDirs } from './generator';
+
+function moduleWithRoleFile(binary: string): string {
+  const root = mkdtempSync(join(tmpdir(), 'celilo-rolefiles-'));
+  const filesDir = join(root, 'ansible', 'roles', 'demo', 'files');
+  mkdirSync(filesDir, { recursive: true });
+  writeFileSync(join(filesDir, 'demo-linux-x86_64'), binary);
+  return root;
+}
+
+const generatedBinary = (out: string): string =>
+  readFileSync(join(out, 'ansible', 'roles', 'demo', 'files', 'demo-linux-x86_64'), 'utf-8');
+
+describe('copyAnsibleRoleFilesDirs', () => {
+  test('populates an empty generated tree', async () => {
+    const modulePath = moduleWithRoleFile('v1');
+    const outputPath = mkdtempSync(join(tmpdir(), 'celilo-out-'));
+
+    await copyAnsibleRoleFilesDirs(modulePath, outputPath);
+
+    expect(generatedBinary(outputPath)).toBe('v1');
+  });
+
+  /**
+   * celilo#925 in one assertion. This is the case that regressed, and the only
+   * one that can catch it: the destination already exists, and a rebuilt
+   * artifact has to replace it.
+   */
+  test('OVERWRITES an artifact a previous generate already placed', async () => {
+    const outputPath = mkdtempSync(join(tmpdir(), 'celilo-out-'));
+
+    await copyAnsibleRoleFilesDirs(moduleWithRoleFile('v1'), outputPath);
+    expect(generatedBinary(outputPath)).toBe('v1');
+
+    // The module is rebuilt at a new version; generate runs again.
+    await copyAnsibleRoleFilesDirs(moduleWithRoleFile('v2'), outputPath);
+
+    expect(generatedBinary(outputPath)).toBe('v2');
+  });
+
+  test('a module with no role files/ directory is not an error', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'celilo-norole-'));
+    mkdirSync(join(root, 'ansible', 'roles', 'demo', 'tasks'), { recursive: true });
+    const outputPath = mkdtempSync(join(tmpdir(), 'celilo-out-'));
+
+    await copyAnsibleRoleFilesDirs(root, outputPath);
+  });
+});

package/src/templates/generator.ts

@@ -500,7 +500,29 @@ export async function copyAnsibleRoleFilesDirs(
     if (!existsSync(srcFilesDir)) continue;
     const destFilesDir = join(outputPath, 'ansible', 'roles', role.name, 'files');
     await mkdir(dirname(destFilesDir), { recursive: true });
-    await cp(srcFilesDir, destFilesDir, { recursive: true, preserveTimestamps: true });
+    // `force: true` is LOAD-BEARING on bun, and its absence was celilo#925.
+    //
+    // Node defaults `force` to true, so this looked correct and is correct
+    // under Node. Bun 1.3.3 does not, on this path specifically — measured,
+    // copying "NEW" over an existing "OLD":
+    //
+    //   recursive only                          -> NEW
+    //   recursive + force                       -> NEW
+    //   recursive + preserveTimestamps          -> OLD   <- what this was
+    //   recursive + force + preserveTimestamps  -> NEW
+    //
+    // celilo runs on bun. So a module's built binary landed in `generated/`
+    // exactly once, at first generate, and no later version ever replaced it —
+    // silently, because `cp` reports no error, so the caller's try/catch has
+    // nothing to catch. Ansible then copies that first binary forever and
+    // reports `ok`, unchanged, while the module's version field advances.
+    //
+    // The sibling call in `storage-set-path.ts:153` already passes `force`.
+    await cp(srcFilesDir, destFilesDir, {
+      recursive: true,
+      force: true,
+      preserveTimestamps: true,
+    });
   }
 }