@celilo/cli 2.2.0 → 2.3.0

package/src/hooks/hook-trespass.test.ts

@@ -31,9 +31,9 @@ import {
   listUnpublishedWorkspacePackages,
   planFallbacks,
 } from '../../../../scripts/workspace-fallback';
-import { childPath, executeHookScript, hookChildEnv } from './executor';
+import { CLI_BIN_DIR, childPath, executeHookScript, hookChildEnv } from './executor';
 import { HOOK_PROTOCOL_VERSION } from './hook-protocol';
-import { detectJailBackend, jailPolicy } from './jail';
+import { detectJailBackend } from './jail';
 import { createCapturingLogger } from './logger';
 import { configStore, secretStore } from './test-fixtures/store-backed';
 import type { HookContext } from './types';
@@ -246,19 +246,29 @@ describe('the child environment is an allow-list', () => {
   // celilo#1300: a hook that spawns `celilo` by name must find the same CLI
   // the parent runs, whatever the inherited PATH looks like.
   describe('childPath', () => {
-    test('prepends the runtime directory so the child reaches the parent CLI', () => {
+    test('prepends the CLI bin and runtime directories so the child reaches the parent CLI', () => {
       const child = childPath('/usr/local/bin:/usr/bin');
-      expect(child.startsWith(`${dirname(process.execPath)}:`)).toBe(true);
+      expect(child.startsWith(`${CLI_BIN_DIR}:${dirname(process.execPath)}:`)).toBe(true);
       expect(child.endsWith('/usr/local/bin:/usr/bin')).toBe(true);
     });
 
-    test('leaves an inherited PATH that already carries the directory unchanged', () => {
-      const already = `${dirname(process.execPath)}:/usr/bin`;
+    test('leaves an inherited PATH that already carries the directories unchanged', () => {
+      const already = `${CLI_BIN_DIR}:${dirname(process.execPath)}:/usr/bin`;
       expect(childPath(already)).toBe(already);
     });
 
-    test('substitutes the directory when the parent has no PATH at all', () => {
-      expect(childPath(undefined)).toBe(dirname(process.execPath));
+    test('substitutes both directories when the parent has no PATH at all', () => {
+      expect(childPath(undefined)).toBe(`${CLI_BIN_DIR}:${dirname(process.execPath)}`);
+    });
+
+    // The fleet gate (ce-y0fd): the .deb layout runs the CLI through
+    // $CELILO_HOME/node_modules/@celilo/cli/bin/celilo, so the directory beside
+    // process.execPath holds only bun and holds no celilo. A PATH that resolves
+    // `celilo` must therefore come from the CLI package's own bin directory —
+    // and that directory must really contain the bin, or every prepended PATH
+    // entry is decoration over the same accident celilo#1300 recorded.
+    test('prepends a CLI bin directory that actually contains the celilo bin', () => {
+      expect(existsSync(join(CLI_BIN_DIR, 'celilo'))).toBe(true);
     });
   });
 });
@@ -292,7 +302,14 @@ describe('hook process boundary — hello-trespass gate', () => {
 });
 
 const availability = detectJailBackend();
-const jailed = availability.backend !== 'none' && jailPolicy() !== 'off';
+// Gated on the BACKEND alone, not on `jailPolicy()`. The ambient policy is an
+// operator switch (`CELILO_HOOK_JAIL=off` is the default), and reading it here
+// made stage 2 skip on every host with the default — measuring nothing. The
+// jailed run pins the policy to `required` inside `runTrespass(true)` and
+// restores it after, so the jail under test is this suite's own act wherever a
+// backend exists. (celilo#1359: since the default became `off`, all three
+// jailed suites skipped everywhere.)
+const jailed = availability.backend !== 'none';
 
 describe.skipIf(!jailed)(
   `stage 2: the same hook, jailed (backend: ${availability.backend})`,

package/src/hooks/jail.test.ts

@@ -27,6 +27,7 @@ import {
   readJailMode,
   realpathRequest,
   recordJailMode,
+  resolveJailPolicy,
   runtimeModulePathsFor,
 } from './jail';
 import { deriveMountSet } from './mount-set';
@@ -208,9 +209,13 @@ describe('the three policies', () => {
   });
 
   test("'required' turns an unavailable jail into a hard failure (task 4.5)", () => {
-    expect(() =>
-      planJailedSpawn(CMD, deriveMountSet(REQUEST), UNAVAILABLE, 'required', allPresent),
-    ).toThrow(/CELILO_HOOK_JAIL=required/);
+    expect(
+      () => planJailedSpawn(CMD, deriveMountSet(REQUEST), UNAVAILABLE, 'required', allPresent),
+      // Not /CELILO_HOOK_JAIL=required/. Since hook-jail-config-surface the
+      // policy can come from the stored `hooks.jail_policy` row or the
+      // default, so a message naming the variable names a source that may be
+      // unset.
+    ).toThrow(/hook jail policy is 'required'/);
   });
 
   test("'required' names the reason, so the operator can act on it", () => {
@@ -272,8 +277,12 @@ describe('jailPolicy reads the operator’s switch', () => {
     }
   };
 
-  test('unset is auto', () => {
-    expect(withEnv(undefined, jailPolicy)).toBe('auto');
+  test('unset is off (peba, ce-rez7)', () => {
+    expect(withEnv(undefined, jailPolicy)).toBe('off');
+  });
+
+  test('an explicit auto still means auto', () => {
+    expect(withEnv('auto', jailPolicy)).toBe('auto');
   });
 
   test('a typo is refused rather than silently meaning auto', () => {
@@ -284,6 +293,144 @@ describe('jailPolicy reads the operator’s switch', () => {
   });
 });
 
+describe('resolveJailPolicy applies D2 precedence (hook-jail-config-surface)', () => {
+  test('an env value set and non-empty wins over stored config', () => {
+    expect(resolveJailPolicy('required', undefined, 'off')).toEqual({
+      policy: 'required',
+      source: 'env',
+    });
+  });
+
+  test('an EMPTY STRING env value counts as unset and falls through to config', () => {
+    // jailPolicy() already treats '' as unset, so the resolver agrees rather
+    // than inventing a second rule for what counts as set.
+    expect(resolveJailPolicy('', undefined, 'off')).toEqual({ policy: 'off', source: 'config' });
+  });
+
+  test('stored config wins when the env var is absent', () => {
+    expect(resolveJailPolicy(undefined, undefined, 'off')).toEqual({
+      policy: 'off',
+      source: 'config',
+    });
+    expect(resolveJailPolicy(undefined, undefined, 'required')).toEqual({
+      policy: 'required',
+      source: 'config',
+    });
+  });
+
+  test('all absent resolves to off from the default (peba, ce-rez7)', () => {
+    expect(resolveJailPolicy(undefined, undefined, undefined)).toEqual({
+      policy: 'off',
+      source: 'default',
+    });
+    expect(resolveJailPolicy('', undefined, undefined)).toEqual({
+      policy: 'off',
+      source: 'default',
+    });
+  });
+
+  test('an explicit env auto still wins (peba, ce-rez7)', () => {
+    expect(resolveJailPolicy('auto', undefined, 'off')).toEqual({ policy: 'auto', source: 'env' });
+  });
+
+  test('a stored empty jail_policy THROWS, it does not resolve to auto (peba, ce-8832)', () => {
+    // The set-time pattern ^(auto|off|required)$ rejects '', so a stored one
+    // can only arrive via a restore from file or a hand edit to the DB — the
+    // untrusted paths D3 exists to catch. It is outside the enum and fails
+    // closed like any other bad stored value.
+    expect(() => resolveJailPolicy(undefined, undefined, '')).toThrow(/is not a hook jail policy/);
+    expect(() => resolveJailPolicy(undefined, undefined, '')).toThrow(/hooks\.jail_policy=''/);
+  });
+
+  test('a typo in the STORED row is refused, not silently treated as auto (D3)', () => {
+    // The DB row is a trust boundary like any other (Rule 3.7): restores carry
+    // foreign state, and a typo that silently meant `auto` reads as an armed
+    // jail when nothing is armed. The config path is no laxer than the env
+    // path.
+    expect(() => resolveJailPolicy(undefined, undefined, 'alwayssafe')).toThrow(
+      /is not a hook jail policy/,
+    );
+    expect(() => resolveJailPolicy(undefined, undefined, 'alwayssafe')).toThrow(
+      /hooks\.jail_policy='alwayssafe'/,
+    );
+  });
+
+  test('a typo in the env value is still refused (unchanged jailPolicy behaviour)', () => {
+    expect(() => resolveJailPolicy('requried', undefined, undefined)).toThrow(
+      /is not a hook jail policy/,
+    );
+    expect(() => resolveJailPolicy('requried', undefined, 'off')).toThrow(
+      /CELILO_HOOK_JAIL='requried'/,
+    );
+  });
+});
+
+describe('resolveJailPolicy applies the four-step precedence (per-module-jail-policy task 1.3)', () => {
+  // Each boundary gets its own assertion, not just the ends: the chain is
+  // fixed and rendered, and a test that only pins (env, default) cannot tell
+  // a reordering of module and config apart from a correct one.
+
+  test('env beats the module row', () => {
+    expect(resolveJailPolicy('required', 'off', 'auto')).toEqual({
+      policy: 'required',
+      source: 'env',
+    });
+    expect(resolveJailPolicy('off', 'auto', 'auto')).toEqual({ policy: 'off', source: 'env' });
+  });
+
+  test('the module row beats system config', () => {
+    expect(resolveJailPolicy(undefined, 'off', 'auto')).toEqual({
+      policy: 'off',
+      source: 'module',
+    });
+    expect(resolveJailPolicy(undefined, 'required', 'off')).toEqual({
+      policy: 'required',
+      source: 'module',
+    });
+  });
+
+  test('system config beats the default', () => {
+    expect(resolveJailPolicy(undefined, undefined, 'auto')).toEqual({
+      policy: 'auto',
+      source: 'config',
+    });
+    expect(resolveJailPolicy(undefined, undefined, 'required')).toEqual({
+      policy: 'required',
+      source: 'config',
+    });
+  });
+
+  test('the default is off (peba, ce-rez7)', () => {
+    expect(resolveJailPolicy(undefined, undefined, undefined)).toEqual({
+      policy: 'off',
+      source: 'default',
+    });
+  });
+
+  test('an absent module row falls through to system config — absent means follow the system', () => {
+    // The everyday case: a fleet with no per-module rows behaves exactly as
+    // it does today, which is the spec's own operator guarantee.
+    expect(resolveJailPolicy(undefined, undefined, 'auto')).toEqual({
+      policy: 'auto',
+      source: 'config',
+    });
+  });
+
+  test('a bad stored per-module value THROWS rather than coercing (task 1.3)', () => {
+    // The same rule as the system key (peba, ce-8832): a restore or a hand
+    // edit is a trust boundary, and a typo that silently meant `off` would
+    // jail a module the operator exempted — or the reverse. The error names
+    // its source so a reader can tell which stored row is junk.
+    expect(() => resolveJailPolicy(undefined, 'alwayssafe', 'off')).toThrow(
+      /is not a hook jail policy/,
+    );
+    expect(() => resolveJailPolicy(undefined, 'alwayssafe', 'off')).toThrow(
+      /module's jail policy='alwayssafe'/,
+    );
+    expect(() => resolveJailPolicy(undefined, '', 'off')).toThrow(/is not a hook jail policy/);
+  });
+});
+
 describe('realpath at the caller (task 4.2k)', () => {
   test('a symlinked module root is resolved before it becomes a bind', () => {
     // `mod.sourcePath` comes out of the database, and a database restored from

package/src/hooks/jail.ts

@@ -100,7 +100,9 @@ export function autoJailDefers(availability: JailAvailability): boolean {
 }
 
 /**
- * What the operator asked for. `CELILO_HOOK_JAIL`, and the default is `auto`.
+ * What the operator asked for. `CELILO_HOOK_JAIL`, and the default is `off`
+ * (peba's ruling on ce-rez7; `resolveJailPolicy`'s doc comment below has the
+ * reversal trigger).
  *
  * `required` is D8's end state, reached as an explicit act once stage 2 has
  * been proven on a host: an unavailable jail becomes a hard failure rather
@@ -418,16 +420,98 @@ function unavailableReason(error: unknown): string {
  * `CELILO_HOOK_JAIL=requried` that silently meant `auto` would read as the
  * jail being enforced when it is not, which is the one mistake this variable
  * exists to prevent.
+ *
+ * The unset/empty default is `off` (peba's ruling on ce-rez7): jailing must
+ * begin because someone set a switch, not because a package upgrade installed
+ * a backend. Turning the jail ON is a deliberate act.
  */
 export function jailPolicy(): JailPolicy {
   const raw = process.env.CELILO_HOOK_JAIL;
-  if (raw === undefined || raw === '') return 'auto';
+  if (raw === undefined || raw === '') return 'off';
   if (raw === 'auto' || raw === 'off' || raw === 'required') return raw;
   throw new Error(
     `CELILO_HOOK_JAIL='${raw}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
   );
 }
 
+/** Where the effective jail policy came from. Rendered by `system doctor` (D4). */
+export type JailPolicySource = 'env' | 'module' | 'config' | 'default';
+
+/** How much jailing a policy does. Lower is weaker (per-module-jail-policy). */
+export const POLICY_STRENGTH: Record<JailPolicy, number> = { off: 0, auto: 1, required: 2 };
+
+/**
+ * Whether the module's own policy jails LESS than the system's would — the
+ * definition of an exemption (per-module-jail-policy task 3.1-3.3).
+ *
+ * Shared by `module jail`'s weakening interview, `module list`'s marker,
+ * `system doctor`'s count and `system audit`'s category, so the four
+ * surfaces cannot disagree about what an exemption is.
+ */
+export function isWeakerJailPolicy(modulePolicy: JailPolicy, systemPolicy: JailPolicy): boolean {
+  return POLICY_STRENGTH[modulePolicy] < POLICY_STRENGTH[systemPolicy];
+}
+
+/**
+ * Apply the precedence to the four sources (per-module-jail-policy task 1.2):
+ * env wins, then the module's own recorded policy, then stored system
+ * config, then the default, which is `off` (peba's rulings on ce-rez7 and
+ * ce-8832; see openspec/changes/hook-jail-config-surface/design.md and
+ * openspec/changes/per-module-jail-policy/ for the fixed chain).
+ *
+ * Pure, so both consumers (executor.ts and system-doctor.ts) can fetch the
+ * stored rows themselves and stay testable without a database.
+ *
+ * The empty-string env value is treated as unset, matching `jailPolicy()`'s
+ * own handling — one rule for "what counts as set", not a second one here.
+ *
+ * The stored paths are deliberately stricter than the env path: a stored
+ * empty string THROWS (peba's ruling on ce-8832). The set-time pattern
+ * `^(auto|off|required)$` rejects `''`, so a stored one can only arrive via
+ * a restore from file or a hand edit to the DB — exactly the untrusted
+ * paths D3 exists to catch. Resolving it to a silent `auto` would let
+ * foreign state pick the jailing default with nobody told, and failing
+ * closed is the whole point. An empty CELILO_HOOK_JAIL stays "not set",
+ * because `jailPolicy()` relies on that and slice 1's safety rests on the
+ * two resolvers agreeing.
+ *
+ * The module row follows the same throw rule as the system key (task 1.3).
+ * `undefined` is the everyday case — no row, follow the system — and a row
+ * keyed to a module that was removed is impossible by schema: the FK
+ * cascades the delete.
+ */
+export function resolveJailPolicy(
+  envValue: string | undefined,
+  moduleValue: string | undefined,
+  configValue: string | undefined,
+): { policy: JailPolicy; source: JailPolicySource } {
+  if (envValue !== undefined && envValue !== '') {
+    if (envValue === 'auto' || envValue === 'off' || envValue === 'required') {
+      return { policy: envValue, source: 'env' };
+    }
+    throw new Error(
+      `CELILO_HOOK_JAIL='${envValue}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
+    );
+  }
+  if (moduleValue !== undefined) {
+    if (moduleValue === 'auto' || moduleValue === 'off' || moduleValue === 'required') {
+      return { policy: moduleValue, source: 'module' };
+    }
+    throw new Error(
+      `the module's jail policy='${moduleValue}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
+    );
+  }
+  if (configValue !== undefined) {
+    if (configValue === 'auto' || configValue === 'off' || configValue === 'required') {
+      return { policy: configValue, source: 'config' };
+    }
+    throw new Error(
+      `hooks.jail_policy='${configValue}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
+    );
+  }
+  return { policy: 'off', source: 'default' };
+}
+
 /**
  * Resolve every path in a mount-set request through the filesystem (task 4.2k).
  *
@@ -568,9 +652,14 @@ function realpathOrSelf(path: string): string {
  * Why an `off` policy runs unjailed, shared with `celilo system doctor` (task
  * 4.6) so the sentence the operator reads there is the sentence the record
  * carries.
+ *
+ * It names no source. Since hook-jail-config-surface there are three (the
+ * environment variable, the stored `hooks.jail_policy` row, and the `off`
+ * default), and this sentence is rendered for all of them. The doctor prints
+ * the source on its own line above this one; the record carries it as state.
  */
 export const JAIL_OFF_REASON =
-  'CELILO_HOOK_JAIL=off: the operator switched the hook jail off on this host.';
+  "The hook jail policy is 'off', so hooks run unjailed on this host. Set hooks.jail_policy to 'auto' or 'required' to jail them.";
 
 export function planJailedSpawn(
   cmd: readonly string[],
@@ -595,7 +684,7 @@ export function planJailedSpawn(
       : 'This invocation has no module tree to jail, so there is no mount set to enforce.';
     if (policy === 'required') {
       throw new Error(
-        `CELILO_HOOK_JAIL=required and no hook jail is available. ${reason ?? ''}`.trim(),
+        `The hook jail policy is 'required' and no hook jail is available. ${reason ?? ''}`.trim(),
       );
     }
     return { cmd, mode: 'unjailed', backend: availability.backend, reason, skipped: [] };

package/src/manifest/contracts/v1.ts

@@ -173,6 +173,19 @@ export const V1_HOOKS: ContractHooks = {
        * mount-set derivation walking the declared inputs could not see it.
        */
       system_state_root: { required: false, path: { access: 'read' } },
+      /**
+       * The management-host inventory as a JSON array, staged by
+       * `backup-create.ts` from `listMachines()` under the same
+       * cross_module_read privilege as `system_state_root`. Not a path: the
+       * hook reads the value, not a file, so it carries no mount-set entry.
+       *
+       * It replaces on_backup's `celilo machine list --json` spawn, which the
+       * hook jail kills (no celilo binary, celilo#1225) and which never
+       * actually produced JSON before that — the CLI printed its human report,
+       * the hook's JSON.parse failed, and the catch wrote [] into every
+       * envelope (ce-y0we).
+       */
+      machine_pool: { required: false },
     },
     outputs: {
       artifact_count: { required: true },

package/src/module/packaging/audit.ts

@@ -13,7 +13,6 @@ import {
 } from '../../services/module-instances';
 import { computeFileChecksum } from './checksum';
 import type { IntegrityViolation } from './extract';
-import { compareVerbatimRoleAssets, readVerbatimRoleAssets } from './generated-plane';
 import { type HostPlaneResult, verifyModuleOnHosts } from './host-plane';
 import { classifyModulePath } from './package-rules';
 
@@ -204,30 +203,11 @@ export async function auditModule(
       }
     }
 
-    // Plane two: is what we would deploy built from what we installed? Only
-    // verbatim role assets have a meaningful expected digest — Ansible
-    // templates the rest, and a `.j2` in `generated/` is SUPPOSED to differ.
-    // A module that has never been generated has nothing to compare and is not
-    // a finding; it is simply pre-deploy.
-    const generatedDir = join(moduleDir, 'generated');
-    if (existsSync(generatedDir)) {
-      const differences = compareVerbatimRoleAssets(
-        await readVerbatimRoleAssets(moduleDir),
-        await readVerbatimRoleAssets(generatedDir),
-      );
-      for (const difference of differences) {
-        violations.push({
-          type: 'stale-generated',
-          path: difference.relPath,
-          expectedDigest: difference.installedDigest,
-          actualDigest: difference.generatedDigest,
-          message:
-            difference.reason === 'missing'
-              ? `Generated project is missing ${difference.relPath} — the next deploy would ship nothing for it. Run 'celilo module generate ${moduleId}'.`
-              : `Generated project holds different bytes for ${difference.relPath} (generated ${difference.generatedDigest}, installed ${difference.installedDigest}) — the next deploy would ship the wrong ones. Run 'celilo module generate ${moduleId}'.`,
-        });
-      }
-    }
+    // The second plane (is what we would deploy built from what we installed?)
+    // retired here: the generated tree is ephemeral now (D4 of
+    // control-plane-stops-building-modules) — rendered for a deploy and
+    // deleted on success — so a persistent generated copy that verbatim role
+    // assets could be compared against no longer exists to compare.
 
     // Check for extra files (not in checksums)
     const actualFiles = await scanDirectory(moduleDir, moduleDir);
@@ -244,7 +224,10 @@ export async function auditModule(
     }
 
     // Plane three: is what is running what we generated? One SSH per system,
-    // so it is asked only when the caller says so.
+    // so it is asked only when the caller says so. With the generated tree
+    // ephemeral (D4), a deep audit after a successful deploy finds no playbook
+    // and says so — the remedy is generate, which is cheap and never builds.
+    const generatedDir = join(moduleDir, 'generated');
     let hostPlane: HostPlaneResult | undefined;
     if (options.deep) {
       hostPlane = await verifyModuleOnHosts({

package/src/module/packaging/build-paths.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from 'bun:test';
+import { cpSync, existsSync, mkdtempSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { resolveBuildCommandPaths } from './build-paths';
+
+/** Repo root: this file sits at apps/celilo/src/module/packaging/. */
+const REPO_ROOT = join(import.meta.dir, '..', '..', '..', '..', '..');
+
+/** Every module in the repo that declares a `build:` block (design, Context). */
+const BUILD_MODULES = [
+  'celilo-registry',
+  'celilo-web-console',
+  'celilo-website',
+  'forgejo',
+  'npm-cache-node',
+  'wireguard-manager',
+] as const;
+
+function buildCommand(moduleId: string): string {
+  const manifestPath = join(REPO_ROOT, 'modules', moduleId, 'manifest.yml');
+  if (!existsSync(manifestPath)) throw new Error(`fixture missing: ${manifestPath}`);
+  const manifest = parseYaml(readFileSync(manifestPath, 'utf8')) as {
+    build?: { command?: string };
+  };
+  const command = manifest.build?.command;
+  if (!command) throw new Error(`${moduleId} declares no build command`);
+  return command;
+}
+
+describe('publish-time build path gate', () => {
+  test('flags celilo-registry when packaged outside the monorepo (the control-plane shape)', () => {
+    // The known-bad form, per celilo#1307: the script reaches a sibling of the
+    // module source (`../../packages/registry-server`). Inside the monorepo
+    // that resolves; from a tree where the module stands alone — a control
+    // plane, or any packaging that is not the source checkout — it does not.
+    // The spec scenario pins this: "packaged from a tree where that directory
+    // does not exist".
+    const scratch = mkdtempSync(join(tmpdir(), 'celilo-build-paths-'));
+    const moduleSourceDir = join(scratch, 'celilo-registry');
+    cpSync(join(REPO_ROOT, 'modules', 'celilo-registry'), moduleSourceDir, {
+      recursive: true,
+    });
+    const violations = resolveBuildCommandPaths(buildCommand('celilo-registry'), {
+      moduleSourceDir,
+      buildDir: moduleSourceDir,
+    });
+    expect(violations).toHaveLength(1);
+    expect(violations[0].rawPath).toContain('../../packages/registry-server');
+    expect(violations[0].resolvedPath).not.toContain(REPO_ROOT);
+  });
+
+  test('flags a plain relative escape that does not resolve (spec scenario)', () => {
+    const scratch = mkdtempSync(join(tmpdir(), 'celilo-build-paths-'));
+    const violations = resolveBuildCommandPaths(
+      'cd ../../packages/registry-server && bun install',
+      { moduleSourceDir: scratch, buildDir: scratch },
+    );
+    expect(violations).toHaveLength(1);
+    expect(violations[0].rawPath).toBe('../../packages/registry-server');
+  });
+
+  test('accepts $CELILO_MODULE_SOURCE_DIR/server when it exists (npm-cache-node shape)', () => {
+    const scratch = mkdtempSync(join(tmpdir(), 'celilo-build-paths-'));
+    const moduleSourceDir = join(scratch, 'npm-cache-node');
+    cpSync(
+      join(REPO_ROOT, 'modules', 'npm-cache-node', 'server'),
+      join(moduleSourceDir, 'server'),
+      {
+        recursive: true,
+      },
+    );
+    const violations = resolveBuildCommandPaths(buildCommand('npm-cache-node'), {
+      moduleSourceDir,
+      buildDir: moduleSourceDir,
+    });
+    expect(violations).toEqual([]);
+  });
+
+  test('accepts every module build command at publish time in the monorepo', () => {
+    // The regression surface for the five healthy modules. celilo-registry
+    // passes here too, and that is correct: at publish, inside the monorepo,
+    // its `cd` target exists (the binaries shipped on 2026-08-20 prove the
+    // build ran). The gate refuses the script only where it genuinely cannot
+    // resolve — the first test above.
+    for (const moduleId of BUILD_MODULES) {
+      const moduleSourceDir = join(REPO_ROOT, 'modules', moduleId);
+      const violations = resolveBuildCommandPaths(buildCommand(moduleId), {
+        moduleSourceDir,
+        buildDir: moduleSourceDir,
+      });
+      expect(violations, moduleId).toEqual([]);
+    }
+  });
+
+  test('skips a cd target it cannot resolve rather than guessing (forgejo shape)', () => {
+    // `cd "$D"` where D was assigned earlier in the same command: the gate
+    // does not interpret shell, so an unresolvable target is skipped, not
+    // failed. A guard that rejects working modules is worse than none.
+    const scratch = mkdtempSync(join(tmpdir(), 'celilo-build-paths-'));
+    const violations = resolveBuildCommandPaths('D=files && mkdir -p "$D" && cd "$D" && ls', {
+      moduleSourceDir: scratch,
+      buildDir: scratch,
+    });
+    expect(violations).toEqual([]);
+  });
+
+  test('tracks the working directory across chained cds (celilo-web-console shape)', () => {
+    // `cd $SOURCE/../../apps/console` then `cd ../console-server`: the second
+    // target resolves against the FIRST cd's destination, not the build dir.
+    const scratch = mkdtempSync(join(tmpdir(), 'celilo-build-paths-'));
+    const moduleSourceDir = join(scratch, 'web');
+    const monorepo = join(scratch, 'mono');
+    cpSync(join(REPO_ROOT, 'modules', 'celilo-web-console'), moduleSourceDir, { recursive: true });
+    // A monorepo-shaped sibling tree, minimal but real.
+    const { mkdirSync } = require('node:fs') as typeof import('node:fs');
+    mkdirSync(join(monorepo, 'apps', 'console'), { recursive: true });
+    mkdirSync(join(monorepo, 'apps', 'console-server'), { recursive: true });
+    cpSync(moduleSourceDir, join(monorepo, 'modules', 'celilo-web-console'), { recursive: true });
+    const violations = resolveBuildCommandPaths(buildCommand('celilo-web-console'), {
+      moduleSourceDir: join(monorepo, 'modules', 'celilo-web-console'),
+      buildDir: join(monorepo, 'modules', 'celilo-web-console'),
+    });
+    expect(violations).toEqual([]);
+  });
+});