@celilo/cli 2.1.0 → 2.2.0

package/src/services/fleet-key.ts

@@ -73,3 +73,57 @@ export function ensureFleetKey(): FleetKey {
 
   return { publicKey: readFileSync(publicKeyPath, 'utf-8').trim(), created: true };
 }
+
+/**
+ * Every directory a fleet private key may sit in, in priority order.
+ *
+ * Exported so an error message names exactly what was searched. The message
+ * used to say "~/.ssh/" while the search had already been widened, which is a
+ * smaller version of the bug this whole helper exists to prevent.
+ */
+export function fleetKeySearchDirs(): string[] {
+  return [getFleetSshDir(), join(process.env.HOME ?? '~', '.ssh')];
+}
+
+/**
+ * The private key whose public half is `publicKey`, or null.
+ *
+ * Searches celilo's own key directory FIRST and `$HOME/.ssh` second, and the
+ * order is the point. Two different keys are normally present: the one
+ * `ensureFleetKey` minted, which is what celilo authorizes on managed
+ * machines, and whatever keypair the operator or the base image left in the
+ * home directory. Only the first can open a machine celilo provisioned.
+ *
+ * This lives beside `getFleetSshDir` for the reason that helper exists. The
+ * caller that searched for the key hand-derived its own `join(HOME, '.ssh')`
+ * and therefore could not see a minted key at all (celilo#1240).
+ *
+ * Matching ignores the trailing comment, because ssh-keygen writes
+ * `user@host` there and the recorded public half carries `celilo-fleet`.
+ */
+export function findFleetPrivateKey(publicKey: string): string | null {
+  const [type, material] = publicKey.trim().split(/\s+/);
+  if (!type || !material) return null;
+
+  const byType: Record<string, string[]> = {
+    'ssh-ed25519': ['id_ed25519'],
+    'ssh-rsa': ['id_rsa'],
+    'ecdsa-sha2-nistp256': ['id_ecdsa'],
+    'ecdsa-sha2-nistp384': ['id_ecdsa'],
+    'ecdsa-sha2-nistp521': ['id_ecdsa'],
+  };
+  const candidates = byType[type] ?? ['id_ed25519', 'id_rsa', 'id_ecdsa'];
+
+  for (const dir of fleetKeySearchDirs()) {
+    if (!existsSync(dir)) continue;
+    for (const name of candidates) {
+      const keyPath = join(dir, name);
+      const pubPath = `${keyPath}.pub`;
+      if (!existsSync(keyPath) || !existsSync(pubPath)) continue;
+      const [fileType, fileMaterial] = readFileSync(pubPath, 'utf-8').trim().split(/\s+/);
+      if (fileType === type && fileMaterial === material) return keyPath;
+    }
+  }
+
+  return null;
+}

package/src/services/health-runner.ts

@@ -11,6 +11,7 @@ import type { DbClient } from '../db/client';
 import { type ModuleState, modules } from '../db/schema';
 import { loadCapabilityFunctions } from '../hooks/capability-loader';
 import { invokeHook } from '../hooks/executor';
+import { createHookStores } from '../hooks/hook-store';
 import { loadHookConfigMap } from '../hooks/load-hook-config';
 import { createCapturingLogger, createConsoleLogger, createGaugeLogger } from '../hooks/logger';
 import type { HookLogger, HookResult } from '../hooks/types';
@@ -212,6 +213,7 @@ export async function runModuleHealthCheck(
       requiredCapabilities,
       systems: getModuleSystems(moduleId, db),
       remoteAccess: remoteAccessPolicy(moduleId, db),
+      hookStores: () => createHookStores(db, moduleId),
     },
   );
   presentation.finish(hookResult.success);

package/src/services/module-config.ts

@@ -90,6 +90,7 @@ export function upsertModuleConfig(
   moduleId: string,
   key: string,
   value: string | number | boolean | unknown[] | Record<string, unknown> | null,
+  source?: 'hook',
 ): void {
   if (value === null || value === undefined) {
     throw new Error(`upsertModuleConfig(${moduleId}, ${key}): value must not be null/undefined`);
@@ -97,11 +98,28 @@ export function upsertModuleConfig(
   const valueJson = JSON.stringify(value);
   const displayValue = isComplexValue(value) ? valueJson : String(value);
 
+  // `source` records who owns the row (hook-owned-state design D7 — the same
+  // column `derived-value-recomputation` reads). Absent keeps the legacy
+  // pre-column shape for every existing caller: operator and interview writes
+  // stay sourceless until that change gives them their own value to write.
+  // Only the hook config store passes 'hook', and only a hook may: the
+  // manifest refuses `module config set` on any source: hook variable.
   db.insert(moduleConfigs)
-    .values({ moduleId, key, value: displayValue, valueJson })
+    .values({
+      moduleId,
+      key,
+      value: displayValue,
+      valueJson,
+      ...(source !== undefined ? { source } : {}),
+    })
     .onConflictDoUpdate({
       target: [moduleConfigs.moduleId, moduleConfigs.key],
-      set: { value: displayValue, valueJson, updatedAt: new Date() },
+      set: {
+        value: displayValue,
+        valueJson,
+        updatedAt: new Date(),
+        ...(source !== undefined ? { source } : {}),
+      },
     })
     .run();
 }

package/src/services/module-deploy.dns-repoint.test.ts

@@ -0,0 +1,187 @@
+// Slice 3 of openspec/changes/module-orchestrator-primitives: celilo performs
+// the dns.primary repoint when a dns_internal provider deploys (D5), gated on
+// an askConfirm interview. knot's on_install no longer touches these keys.
+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 { eq } from 'drizzle-orm';
+import { type DbClient, closeDb, getDb } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { capabilities, moduleSystems, modules, systemConfig } from '../db/schema';
+import { InterviewUnansweredError } from './interview-errors';
+import { planDnsRepoint, repointDnsPrimaryForProvider } from './module-deploy';
+
+const MODULE_ID = 'knot-unbound-internal';
+const SERVER_IP = '10.226.10.53';
+
+type AskOpts = { scope: string; key: string; message: string };
+
+function makeAsk(answer: boolean): ((opts: AskOpts) => Promise<boolean>) & { calls: AskOpts[] } {
+  const calls: AskOpts[] = [];
+  const ask = async (opts: AskOpts) => {
+    calls.push(opts);
+    return answer;
+  };
+  return Object.assign(ask, { calls });
+}
+
+function makeAskThrowing(err: Error): ((opts: AskOpts) => Promise<boolean>) & { calls: AskOpts[] } {
+  const calls: AskOpts[] = [];
+  const ask = async (opts: AskOpts) => {
+    calls.push(opts);
+    throw err;
+  };
+  return Object.assign(ask, { calls });
+}
+
+describe('repointDnsPrimaryForProvider (module-orchestrator-primitives slice 3)', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-dns-repoint-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    await runMigrations(process.env.CELILO_DB_PATH);
+    db = getDb();
+    seedProvider();
+  });
+
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* temp dir cleanup is best-effort */
+    }
+  });
+
+  function seedProvider() {
+    db.insert(modules)
+      .values({
+        id: MODULE_ID,
+        name: MODULE_ID,
+        version: '1.3.4',
+        manifestData: { id: MODULE_ID, name: MODULE_ID, version: '1.3.4', celilo_contract: '1.0' },
+        sourcePath: `/tmp/${MODULE_ID}`,
+      })
+      .run();
+    db.insert(capabilities)
+      .values({ moduleId: MODULE_ID, capabilityName: 'dns_internal', version: '1.0.0', data: {} })
+      .run();
+    db.insert(moduleSystems)
+      .values({
+        moduleId: MODULE_ID,
+        name: 'main',
+        hostname: 'dns',
+        ipv4Address: SERVER_IP,
+        zone: 'dmz',
+        infraType: 'container_service',
+      })
+      .run();
+  }
+
+  function setConfig(key: string, value: string) {
+    db.insert(systemConfig)
+      .values({ key, value })
+      .onConflictDoUpdate({ target: systemConfig.key, set: { value } })
+      .run();
+  }
+
+  function configValue(key: string): string | undefined {
+    return db.select().from(systemConfig).where(eq(systemConfig.key, key)).get()?.value;
+  }
+
+  test('3.1: repoints dns.primary at the resolver and demotes the prior primary WITHOUT losing the existing fallback', async () => {
+    setConfig('dns.primary', '1.1.1.1');
+    setConfig('dns.fallback', '8.8.8.8');
+    const ask = makeAsk(true);
+
+    await repointDnsPrimaryForProvider(MODULE_ID, db, ask);
+
+    expect(configValue('dns.primary')).toBe(SERVER_IP);
+    // The WHOLE resulting value: the existing fallback must survive beside the
+    // demoted prior primary (D5's secondary observation — knot's hook lost it).
+    expect(configValue('dns.fallback')).toBe('1.1.1.1,8.8.8.8');
+    expect(ask.calls).toHaveLength(1);
+    expect(ask.calls[0].message).toContain(SERVER_IP);
+    expect(ask.calls[0].message).toContain('1.1.1.1');
+  });
+
+  test('3.1: demotes the prior primary to dns.fallback when no fallback existed', async () => {
+    setConfig('dns.primary', '1.1.1.1');
+    const ask = makeAsk(true);
+
+    await repointDnsPrimaryForProvider(MODULE_ID, db, ask);
+
+    expect(configValue('dns.primary')).toBe(SERVER_IP);
+    expect(configValue('dns.fallback')).toBe('1.1.1.1');
+  });
+
+  test('3.1: sets dns.primary without touching dns.fallback when no primary was set', async () => {
+    const ask = makeAsk(true);
+
+    await repointDnsPrimaryForProvider(MODULE_ID, db, ask);
+
+    expect(configValue('dns.primary')).toBe(SERVER_IP);
+    expect(configValue('dns.fallback')).toBeUndefined();
+  });
+
+  test('does not ask when dns.primary already names this resolver (re-deploy)', async () => {
+    setConfig('dns.primary', SERVER_IP);
+    setConfig('dns.fallback', '8.8.8.8');
+    const ask = makeAsk(true);
+
+    await repointDnsPrimaryForProvider(MODULE_ID, db, ask);
+
+    expect(ask.calls).toHaveLength(0);
+    expect(configValue('dns.primary')).toBe(SERVER_IP);
+    expect(configValue('dns.fallback')).toBe('8.8.8.8');
+  });
+
+  test('3.2: a negative answer leaves both keys unchanged and does not fail the deploy', async () => {
+    setConfig('dns.primary', '1.1.1.1');
+    setConfig('dns.fallback', '8.8.8.8');
+    const ask = makeAsk(false);
+
+    await expect(repointDnsPrimaryForProvider(MODULE_ID, db, ask)).resolves.toBeUndefined();
+
+    expect(configValue('dns.primary')).toBe('1.1.1.1');
+    expect(configValue('dns.fallback')).toBe('8.8.8.8');
+    expect(ask.calls).toHaveLength(1);
+  });
+
+  test('no responder able to answer (headless) is a defined skip, never a hang', async () => {
+    setConfig('dns.primary', '1.1.1.1');
+    const ask = makeAskThrowing(
+      new InterviewUnansweredError('interview.required.deploy:knot.repoint_dns_primary', 'nobody'),
+    );
+
+    await expect(repointDnsPrimaryForProvider(MODULE_ID, db, ask)).resolves.toBeUndefined();
+
+    expect(configValue('dns.primary')).toBe('1.1.1.1');
+  });
+});
+
+describe('planDnsRepoint', () => {
+  test('merges the existing fallback without duplicating the demoted primary', () => {
+    const plan = planDnsRepoint({
+      serverIp: SERVER_IP,
+      priorPrimary: '1.1.1.1',
+      existingFallback: '1.1.1.1,9.9.9.9',
+    });
+    expect(plan.needsRepoint).toBe(true);
+    expect(plan.newFallback).toBe('1.1.1.1,9.9.9.9');
+  });
+
+  test('already-primary is a no-op plan', () => {
+    const plan = planDnsRepoint({
+      serverIp: SERVER_IP,
+      priorPrimary: SERVER_IP,
+      existingFallback: '8.8.8.8',
+    });
+    expect(plan.needsRepoint).toBe(false);
+    expect(plan.newFallback).toBeUndefined();
+  });
+});

package/src/services/module-deploy.ts

@@ -11,9 +11,10 @@ import { generateInventory } from '../ansible/inventory';
 import { FuelGauge } from '../cli/fuel-gauge';
 import { log, setActiveDisplay } from '../cli/prompts';
 import type { DbClient } from '../db/client';
-import { capabilities, machines, modules } from '../db/schema';
+import { capabilities, machines, modules, systemConfig } from '../db/schema';
 import { loadCapabilityFunctions } from '../hooks/capability-loader';
 import { invokeHook } from '../hooks/executor';
+import { createHookStores } from '../hooks/hook-store';
 import { createGaugeLogger } from '../hooks/logger';
 import { describeArtifacts } from '../hooks/types';
 import type { HookDefinition, HookLogger, HookResult } from '../hooks/types';
@@ -22,6 +23,7 @@ import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { buildResolutionContext } from '../variables/context';
 import { maybeRunAspectForTrigger } from './aspect-runner';
+import { askConfirm } from './bus-interview';
 import {
   autoDeriveMachineConfig,
   findEnsureOnProvider,
@@ -40,6 +42,7 @@ import { CONTROL_PLANE_MODULE_ID } from './deployed-systems';
 import { getModuleSystems } from './deployed-systems';
 import { E2E_CONFLICT_MESSAGE, runningE2eContainers } from './e2e-guard';
 import { resolveInfrastructureVariables } from './infrastructure-variable-resolver';
+import { InterviewAbandonedError, InterviewUnansweredError } from './interview-errors';
 import { findMachineForModule } from './machine-pool';
 import { ensureRequiredNetworks } from './network-ensure';
 import {
@@ -388,6 +391,154 @@ export async function deployModule(
   return result;
 }
 
+/**
+ * Headless bound for the repoint confirm. A staged responder replies in
+ * milliseconds; this exists so an attached-but-unstaged responder produces a
+ * defined skip instead of hanging until the suite budget kills the deploy
+ * (module-orchestrator-primitives design.md D5, "never a hang"). On a TTY
+ * there is no bound: the operator IS the responder and may take minutes.
+ */
+const DNS_REPOINT_HEADLESS_TIMEOUT_MS = 60_000;
+
+/**
+ * The deploy-time DNS repoint for a `dns_internal` provider
+ * (module-orchestrator-primitives slice 3, design D5). celilo owns the whole
+ * operation because every input is already celilo's: the resolver address is
+ * the system celilo just placed, and the prior primary/fallback are celilo's
+ * own rows. knot's on_install used to do this through the CLI, one key at a
+ * time, under a catch that reported success over a repoint that never
+ * happened.
+ *
+ * D5 is a recorded DELIBERATE EXCEPTION to the framework-does-not-infer-intent
+ * rule. What makes it acceptable is the interview: the deploy ASKS before it
+ * touches the fleet resolver, and a declined repoint is an operator decision,
+ * not an error. Do not cite this as precedent (design.md D5, "So do not cite
+ * this as precedent").
+ */
+export interface DnsRepointPlan {
+  serverIp: string;
+  priorPrimary: string | undefined;
+  existingFallback: string | undefined;
+  /** Merged dns.fallback when the repoint demotes the prior primary; undefined leaves the key untouched. */
+  newFallback: string | undefined;
+  /** False when dns.primary already names this resolver: the deploy asks nothing. */
+  needsRepoint: boolean;
+}
+
+/**
+ * Pure half of the repoint. The demote keeps an existing fallback (D5's
+ * secondary observation: knot's one-key-at-a-time hook overwrote it, dropping
+ * e.g. 8.8.8.8 from the fleet's resolver list).
+ */
+export function planDnsRepoint(args: {
+  serverIp: string;
+  priorPrimary: string | undefined;
+  existingFallback: string | undefined;
+}): DnsRepointPlan {
+  const { serverIp, priorPrimary, existingFallback } = args;
+  if (priorPrimary === serverIp) {
+    return {
+      serverIp,
+      priorPrimary,
+      existingFallback,
+      newFallback: undefined,
+      needsRepoint: false,
+    };
+  }
+  const newFallback = priorPrimary ? mergeFallback(existingFallback, priorPrimary) : undefined;
+  return { serverIp, priorPrimary, existingFallback, newFallback, needsRepoint: true };
+}
+
+/** Comma-separated, demoted primary first, deduped (public-dns-probe.ts parses commas). */
+function mergeFallback(existing: string | undefined, demoted: string): string {
+  const entries = [demoted];
+  for (const part of (existing ?? '').split(',')) {
+    const ip = part.trim();
+    if (ip && !entries.includes(ip)) entries.push(ip);
+  }
+  return entries.join(',');
+}
+
+function readSystemConfigValue(db: DbClient, key: string): string | undefined {
+  const row = db.select().from(systemConfig).where(eq(systemConfig.key, key)).get();
+  return row?.value && row.value.length > 0 ? row.value : undefined;
+}
+
+function writeSystemConfigValue(db: DbClient, key: string, value: string): void {
+  db.insert(systemConfig)
+    .values({ key, value })
+    .onConflictDoUpdate({ target: systemConfig.key, set: { value } })
+    .run();
+}
+
+/**
+ * Ask, then perform (or skip) the repoint for a just-deployed `dns_internal`
+ * provider. Exported for tests; `deployModuleImpl` calls this after the DNS
+ * backfill when the deployed module provides `dns_internal`.
+ */
+export async function repointDnsPrimaryForProvider(
+  moduleId: string,
+  db: DbClient,
+  ask: typeof askConfirm = askConfirm,
+): Promise<void> {
+  const serverIp = getModuleSystems(moduleId, db)[0]?.ipv4_address;
+  if (!serverIp) {
+    log.warn(
+      `dns_internal provider '${moduleId}' has no deployed system — skipping dns.primary repoint`,
+    );
+    return;
+  }
+  const plan = planDnsRepoint({
+    serverIp,
+    priorPrimary: readSystemConfigValue(db, 'dns.primary'),
+    existingFallback: readSystemConfigValue(db, 'dns.fallback'),
+  });
+  if (!plan.needsRepoint) {
+    log.info(`dns.primary already points at ${serverIp} — no repoint needed`);
+    return;
+  }
+
+  const demoteNote = plan.newFallback
+    ? ` The old primary ${plan.priorPrimary} moves to dns.fallback (${plan.newFallback}).`
+    : '';
+  const opts = {
+    scope: `deploy:${moduleId}`,
+    key: 'repoint_dns_primary',
+    message: `Deploying '${moduleId}' made it the fleet's internal DNS resolver. Point dns.primary at ${serverIp}?${demoteNote}`,
+    defaultValue: false,
+  };
+  // Called DIRECTLY, not inside withInterviewSession: deployModuleImpl already
+  // opened the terminal responder above and closes it in its finally. A second
+  // responder instance would race the first on stdin (design.md D5).
+  let confirmed: boolean;
+  try {
+    confirmed = await ask(
+      process.stdin.isTTY ? opts : { ...opts, timeoutMs: DNS_REPOINT_HEADLESS_TIMEOUT_MS },
+    );
+  } catch (error) {
+    if (error instanceof InterviewUnansweredError || error instanceof InterviewAbandonedError) {
+      log.warn(
+        `dns.primary repoint skipped — nobody answered the confirm (${opts.scope}:${opts.key}). Stage the answer (celilo events respond --values) or set dns.primary manually later.`,
+      );
+      return;
+    }
+    throw error;
+  }
+
+  if (!confirmed) {
+    log.info('dns.primary repoint declined — fleet resolver left unchanged');
+    return;
+  }
+
+  writeSystemConfigValue(db, 'dns.primary', serverIp);
+  if (plan.newFallback !== undefined) {
+    writeSystemConfigValue(db, 'dns.fallback', plan.newFallback);
+  }
+  log.success(
+    `dns.primary repointed at internal resolver ${serverIp}${plan.newFallback ? ` (dns.fallback: ${plan.newFallback})` : ''}`,
+  );
+}
+
 async function deployModuleImpl(
   moduleId: string,
   db: DbClient,
@@ -724,6 +875,7 @@ async function deployModuleImpl(
             requiredCapabilities: manifest.requires.capabilities.map((c) => c.name),
             systems: getModuleSystems(moduleId, db),
             remoteAccess: remoteAccessPolicy(moduleId, db),
+            hookStores: () => createHookStores(db, moduleId),
           },
         );
 
@@ -863,6 +1015,7 @@ async function deployModuleImpl(
                 requiredCapabilities: (manifest.requires?.capabilities ?? []).map((c) => c.name),
                 systems: getModuleSystems(moduleId, db),
                 remoteAccess: remoteAccessPolicy(moduleId, db),
+                hookStores: () => createHookStores(db, moduleId),
               },
             };
           },
@@ -1165,6 +1318,7 @@ async function deployModuleImpl(
             requiredCapabilities: providerManifest.requires.capabilities.map((c) => c.name),
             systems: getModuleSystems(capRecord.moduleId, db),
             remoteAccess: remoteAccessPolicy(capRecord.moduleId, db),
+            hookStores: () => createHookStores(db, capRecord.moduleId),
           },
         );
 
@@ -1483,6 +1637,7 @@ async function deployModuleImpl(
                 requiredCapabilities: manifest.requires.capabilities.map((c) => c.name),
                 systems: getModuleSystems(moduleId, db),
                 remoteAccess: remoteAccessPolicy(moduleId, db),
+                hookStores: () => createHookStores(db, moduleId),
               },
             };
           },
@@ -1608,6 +1763,13 @@ async function deployModuleImpl(
             `DNS backfill failed for '${moduleId}': ${msg}. Some internal DNS records may need manual setup.`,
           );
         }
+
+        // The dns_internal handoff (module-orchestrator-primitives slice 3,
+        // design D5): celilo repoints dns.primary at the resolver it just
+        // deployed, gated on an interview. knot's on_install no longer does
+        // this. Runs after the backfill so a failed deploy never repoints the
+        // fleet at a resolver that never came up.
+        await repointDnsPrimaryForProvider(moduleId, db);
       }
 
       // Announce each deployed system on the bus (D5/D6) — one

package/src/services/module-validator/git-hygiene.test.ts

@@ -1,8 +1,9 @@
 import { describe, expect, test } from 'bun:test';
 import { execSync } from 'node:child_process';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { classifyModulePath } from '../../module/packaging/package-rules';
 import { checkGitHygiene, checkModuleStale } from './git-hygiene';
 
 interface TempRepo {
@@ -18,8 +19,19 @@ interface TempRepo {
  */
 function makeTempRepo(): TempRepo {
   const dir = mkdtempSync(join(tmpdir(), 'celilo-git-hygiene-'));
+  // Bound every git child. A git call that hangs used to run until bun's
+  // per-test timeout killed it, and bun's dangling-process kill left the
+  // WHOLE run parked (reproduced for celilo#1282; the park itself is
+  // celilo#1246). Erroring the test instead keeps the failure visible and
+  // the run exitable. 30s per command stays under the 60s per-test ceiling
+  // this suite runs with.
   const exec = (cmd: string): string =>
-    execSync(cmd, { cwd: dir, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    execSync(cmd, {
+      cwd: dir,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 30_000,
+    });
   exec('git init -q');
   exec('git config user.email "test@example.com"');
   exec('git config user.name "Test"');
@@ -88,6 +100,113 @@ describe('checkModuleStale', () => {
   });
 });
 
+describe('staleness reach vs the packager (celilo#1270)', () => {
+  // Paths planted to span the classifications classifyModulePath produces.
+  // The expected staleness outcome is NOT hand-written per path: each test
+  // asks classifyModulePath what the packager does with the path and holds
+  // the staleness gate to the same answer.
+  const planted = [
+    'e2e/split-horizon-views.test.ts',
+    'e2e/fixtures/cases.json',
+    'scripts/install.sh',
+    'scripts/tsconfig.json',
+    'ansible/playbook.yml',
+    'terraform/main.tf',
+    'schema/tables.sql',
+    'hooks/run.test.ts',
+    'generated/report.json',
+    'state/last-run.json',
+  ];
+
+  /** Repo with only manifest.yml committed; returns `commit(rel)` helper. */
+  function repoWithManifest() {
+    const repo = makeTempRepo();
+    writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.0\n');
+    repo.exec('git add manifest.yml && git commit -q -m manifest');
+    const commit = (rel: string) => {
+      const abs = join(repo.dir, rel);
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, 'planted\n');
+      repo.exec(`git add ${rel} && git commit -q -m ${JSON.stringify(rel)}`);
+    };
+    return { repo, commit };
+  }
+
+  test(
+    'a commit touching only e2e/ does not mark the manifest stale',
+    () => {
+      const { repo, commit } = repoWithManifest();
+      try {
+        commit('e2e/split-horizon-views.test.ts');
+        expect(checkModuleStale(repo.dir)).toBeNull();
+      } finally {
+        repo.cleanup();
+      }
+    },
+    { timeout: 30_000 },
+  );
+
+  test(
+    'a commit touching scripts/, ansible/, terraform/ or schema/ still fires',
+    () => {
+      for (const rel of [
+        'scripts/install.sh',
+        'ansible/playbook.yml',
+        'terraform/main.tf',
+        'schema/tables.sql',
+      ]) {
+        const { repo, commit } = repoWithManifest();
+        try {
+          commit(rel);
+          expect(classifyModulePath(rel)).toBe('package');
+          expect(checkModuleStale(repo.dir)).not.toBeNull();
+        } finally {
+          repo.cleanup();
+        }
+      }
+    },
+    { timeout: 30_000 },
+  );
+
+  test(
+    'reach parity: the gate fires exactly for paths the packager ships',
+    async () => {
+      for (const rel of planted) {
+        const { repo, commit } = repoWithManifest();
+        try {
+          commit(rel);
+          const stale = checkModuleStale(repo.dir);
+          if (classifyModulePath(rel) === 'package') {
+            expect(stale).not.toBeNull();
+          } else {
+            expect(stale).toBeNull();
+          }
+        } finally {
+          repo.cleanup();
+        }
+      }
+    },
+    { timeout: 30_000 },
+  );
+
+  test(
+    'non-shipped commits between manifest and a shipped change stay quiet until shipped bytes move',
+    () => {
+      const { repo, commit } = repoWithManifest();
+      try {
+        commit('e2e/split-horizon-views.test.ts');
+        commit('scripts/tsconfig.json');
+        expect(checkModuleStale(repo.dir)).toBeNull();
+        commit('scripts/install.sh');
+        expect(checkModuleStale(repo.dir)).not.toBeNull();
+      } finally {
+        repo.cleanup();
+      }
+    },
+    { timeout: 30_000 },
+  );
+});
+
 describe('checkGitHygiene', () => {
   test('all ok on a fresh, clean repo with manifest as latest commit', () => {
     const repo = makeTempRepo();