@celilo/cli 2.3.0 → 3.1.0

package/src/services/build-bus/hook-dispatch-executor.test.ts

@@ -0,0 +1,269 @@
+/**
+ * The slice-7 wiring, end to end: build-bus dispatcher → runNamedHook →
+ * invokeHook → a real defineHook child, with the verified PublishEvent
+ * arriving as the hook's `event` input (tasks.md 7.3/7.4).
+ *
+ * The scratch-module pattern is hook-state-dir.test.ts's: a temp module
+ * whose scripts resolve the WORKSPACE @celilo/capabilities through a
+ * symlink, because a real module in the store carries its own bundled copy
+ * (modules run their bundled capabilities, celilo#173) and the jail binds
+ * the module's tree and nothing above it.
+ *
+ * The database is an isolated client at a temp path, never the operator's
+ * live store.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import type { PublishEvent } from '@celilo/event-bus/build-bus';
+import { type DbClient, createDbClient } from '../../db/client';
+import { buildBusHookRuns, modules } from '../../db/schema';
+import { startHookDispatcher } from './hook-dispatcher';
+
+const CAPABILITIES_PACKAGE = resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  '..',
+  'packages',
+  'capabilities',
+);
+
+function buildEvent(overrides: Partial<PublishEvent> = {}): PublishEvent {
+  return {
+    eventId: 'evt-1',
+    timestamp: new Date().toISOString(),
+    registry: 'npm',
+    tag: 'latest',
+    package: { name: '@celilo/cli', version: '0.5.0' },
+    ...overrides,
+  };
+}
+
+/**
+ * A module whose on_upstream_publish hook echoes the event fields it
+ * received back as outputs, so the test can assert exactly what crossed
+ * the executor boundary. When `failing` is true the handler throws
+ * instead, for the ledger test below.
+ */
+function scratchUpstreamModule(failing = false): string {
+  const root = mkdtempSync(join(tmpdir(), 'celilo-upstream-module-'));
+  mkdirSync(join(root, 'scripts'), { recursive: true });
+  const handlerBody = failing
+    ? `    throw new Error('boom from the jailed hook');`
+    : `    const event = ctx.event as { package?: { name?: string; version?: string } };
+    // Two channels on purpose: the outputs come back through the broker,
+    // and the file is an independent read the test can make without
+    // trusting the dispatcher's result shape.
+    writeFileSync(
+      join(ctx.stateDir as string, 'received.json'),
+      JSON.stringify({ name: event?.package?.name ?? null, version: event?.package?.version ?? null }),
+    );
+    return { received_name: event?.package?.name ?? null, received_version: event?.package?.version ?? null };`;
+  writeFileSync(
+    join(root, 'scripts', 'on-upstream-publish.ts'),
+    `
+import { defineHook } from '@celilo/capabilities';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export default defineHook({
+  requires: [] as const,
+  handler: async (ctx) => {
+${handlerBody}
+  },
+});
+`,
+  );
+  // See the file docblock: the fixture must carry its own capabilities link.
+  mkdirSync(join(root, 'node_modules', '@celilo'), { recursive: true });
+  symlinkSync(CAPABILITIES_PACKAGE, join(root, 'node_modules', '@celilo', 'capabilities'));
+  return root;
+}
+
+let db: DbClient;
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'celilo-upstream-dispatch-'));
+  process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+  process.env.CELILO_EVENT_BUS_PATH = join(dir, 'events.db');
+  process.env.CELILO_DATA_DIR = join(dir, 'data');
+  mkdirSync(join(dir, 'data'), { recursive: true });
+  db = createDbClient({ path: process.env.CELILO_DB_PATH });
+});
+
+afterEach(() => {
+  db.$client.close();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('the dispatcher dispatches on_upstream_publish through the ordinary executor', () => {
+  test('the hook receives the verified PublishEvent as its event input', async () => {
+    const moduleRoot = scratchUpstreamModule();
+    const hookEntry = {
+      name: 'echo-publish',
+      match: { registry: 'npm', tag: 'latest', package_pattern: '@celilo/cli' },
+      script: './scripts/on-upstream-publish.ts',
+      timeout: 60_000,
+    };
+    db.insert(modules)
+      .values({
+        id: 'upstream-fixture',
+        name: 'upstream-fixture',
+        version: '1.0.0',
+        state: 'INSTALLED',
+        sourcePath: moduleRoot,
+        manifestData: {
+          id: 'upstream-fixture',
+          name: 'upstream-fixture',
+          version: '1.0.0',
+          celilo_contract: '1.0',
+          provides: { capabilities: [] },
+          requires: { capabilities: [] },
+          hooks: { on_upstream_publish: [hookEntry] },
+        },
+      })
+      .run();
+
+    const dispatcher = await startHookDispatcher({
+      db,
+      // The loader reads manifest.yml from disk; the fixture module keeps its
+      // manifest in the DB row (runNamedHook's source) and the context here.
+      loadModules: () => [
+        { moduleId: 'upstream-fixture', sourcePath: moduleRoot, hooks: [hookEntry] },
+      ],
+      controlPlaneInstalled: () => false,
+    });
+    try {
+      const results = await dispatcher.handleEvent(
+        buildEvent({ package: { name: '@celilo/cli', version: '0.5.0' } }),
+      );
+      expect(results).toHaveLength(1);
+      expect(results[0].module).toBe('upstream-fixture');
+      expect(results[0].hookName).toBe('echo-publish');
+      expect(results[0].success).toBe(true);
+      // The event crossed the executor into the hook's typed context,
+      // proven by the hook's own file (independent of the dispatcher's
+      // result shape, which carries no outputs).
+      const received = JSON.parse(
+        readFileSync(join(moduleRoot, 'state', 'received.json'), 'utf-8'),
+      ) as { name: string | null; version: string | null };
+      expect(received).toEqual({ name: '@celilo/cli', version: '0.5.0' });
+    } finally {
+      await dispatcher.stop();
+      rmSync(moduleRoot, { recursive: true, force: true });
+    }
+  });
+
+  test('a non-matching event does not run the hook', async () => {
+    const moduleRoot = scratchUpstreamModule();
+    const hookEntry = {
+      name: 'echo-publish',
+      match: { registry: 'npm', tag: 'latest', package_pattern: '@celilo/cli' },
+      script: './scripts/on-upstream-publish.ts',
+      timeout: 60_000,
+    };
+    db.insert(modules)
+      .values({
+        id: 'upstream-fixture',
+        name: 'upstream-fixture',
+        version: '1.0.0',
+        state: 'INSTALLED',
+        sourcePath: moduleRoot,
+        manifestData: {
+          id: 'upstream-fixture',
+          name: 'upstream-fixture',
+          version: '1.0.0',
+          celilo_contract: '1.0',
+          provides: { capabilities: [] },
+          requires: { capabilities: [] },
+          hooks: { on_upstream_publish: [hookEntry] },
+        },
+      })
+      .run();
+
+    const dispatcher = await startHookDispatcher({
+      db,
+      loadModules: () => [
+        { moduleId: 'upstream-fixture', sourcePath: moduleRoot, hooks: [hookEntry] },
+      ],
+      controlPlaneInstalled: () => false,
+    });
+    try {
+      const results = await dispatcher.handleEvent(
+        buildEvent({ package: { name: '@celilo/e2e', version: '0.8.0' } }),
+      );
+      expect(results).toEqual([]);
+    } finally {
+      await dispatcher.stop();
+      rmSync(moduleRoot, { recursive: true, force: true });
+    }
+  });
+});
+
+/**
+ * The durable outcome record (celilo#1304): every dispatched run lands in
+ * the `build_bus_hook_runs` ledger via the production default recordRun —
+ * no injectable capture between the dispatcher and the DB. The jailed
+ * executor (slice 7) exposes no exit codes or captured stdio, so the row
+ * carries the script path (the result doesn't), a null exit code, and the
+ * executor's error text in stderr_tail.
+ */
+test('a failing hook run lands in the build_bus_hook_runs ledger', async () => {
+  const moduleRoot = scratchUpstreamModule(true);
+  const hookEntry = {
+    name: 'echo-publish',
+    match: { registry: 'npm', tag: 'latest', package_pattern: '@celilo/cli' },
+    script: './scripts/on-upstream-publish.ts',
+    timeout: 60_000,
+  };
+  db.insert(modules)
+    .values({
+      id: 'upstream-fixture',
+      name: 'upstream-fixture',
+      version: '1.0.0',
+      state: 'INSTALLED',
+      sourcePath: moduleRoot,
+      manifestData: {
+        id: 'upstream-fixture',
+        name: 'upstream-fixture',
+        version: '1.0.0',
+        celilo_contract: '1.0',
+        provides: { capabilities: [] },
+        requires: { capabilities: [] },
+        hooks: { on_upstream_publish: [hookEntry] },
+      },
+    })
+    .run();
+
+  const dispatcher = await startHookDispatcher({
+    db,
+    loadModules: () => [
+      { moduleId: 'upstream-fixture', sourcePath: moduleRoot, hooks: [hookEntry] },
+    ],
+    controlPlaneInstalled: () => false,
+  });
+  try {
+    await dispatcher.handleEvent(
+      buildEvent({ package: { name: '@celilo/cli', version: '0.5.0' } }),
+    );
+
+    const rows = db.select().from(buildBusHookRuns).all();
+    expect(rows).toHaveLength(1);
+    const row = rows[0];
+    expect(row.eventId).toBe('evt-1');
+    expect(row.packageName).toBe('@celilo/cli');
+    expect(row.moduleId).toBe('upstream-fixture');
+    expect(row.hookName).toBe('echo-publish');
+    expect(row.scriptPath).toBe('./scripts/on-upstream-publish.ts');
+    expect(row.exitCode).toBeNull();
+    expect(row.stderrTail).toContain('boom from the jailed hook');
+  } finally {
+    await dispatcher.stop();
+    rmSync(moduleRoot, { recursive: true, force: true });
+  }
+});

package/src/services/build-bus/hook-dispatch-mgmt.test.ts

@@ -1,37 +1,30 @@
 /**
- * End-to-end test: build-bus hook dispatcher → modules/celilo-mgmt's
- * on_upstream_publish rules → self-update script (with the actual
- * `bun add -g` replaced by a noop so the test doesn't mutate the
- * operator's global install).
+ * End-to-end tests for the framework self-update on a build-bus publish
+ * event (module-orchestrator-primitives slice 7, tasks.md 7.2).
  *
- * Confirms the manifest's match rules pick the right hook for a
- * given event AND that the dispatcher passes the expected env vars
- * to the script.
+ * celilo-mgmt's on_upstream_publish bash hook is gone: self-update is
+ * framework work in the dispatcher now (design D6 — class H's answer).
+ * These tests pin the three things that must hold:
+ *
+ *   1. The real celilo-mgmt manifest declares NO on_upstream_publish — the
+ *      work lives in the framework, and a hook creeping back is a second
+ *      self-update racing the framework one.
+ *   2. planSelfUpdate reproduces the old manifest's match rules exactly
+ *      (npm + latest + the two binary packages).
+ *   3. The dispatcher runs the update ONLY when the control-plane module
+ *      is installed, and logs — never throws — when it fails.
  */
 
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
 import { readFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { PublishEvent } from '@celilo/event-bus/build-bus';
 import { parse as parseYaml } from 'yaml';
-import type { ModuleHookContext, UpstreamHookEntry } from './hook-dispatch';
 import { startHookDispatcher } from './hook-dispatcher';
+import { type SelfUpdatePlan, planSelfUpdate } from './self-update';
 
 const REPO_ROOT = join(__dirname, '..', '..', '..', '..', '..');
 
-function loadCeliloMgmtHooks(): UpstreamHookEntry[] {
-  // Parse the real modules/celilo-mgmt/manifest.yml so this test
-  // tracks the actual deployed manifest — drift here is a test
-  // failure rather than silent breakage.
-  const manifestPath = join(REPO_ROOT, 'modules', 'celilo-mgmt', 'manifest.yml');
-  const parsed = parseYaml(readFileSync(manifestPath, 'utf-8')) as {
-    hooks?: { on_upstream_publish?: UpstreamHookEntry[] };
-  };
-  return parsed.hooks?.on_upstream_publish ?? [];
-}
-
 function buildEvent(overrides: Partial<PublishEvent> = {}): PublishEvent {
   return {
     eventId: 'evt-1',
@@ -43,163 +36,122 @@ function buildEvent(overrides: Partial<PublishEvent> = {}): PublishEvent {
   };
 }
 
-describe('hook-dispatcher → modules/celilo-mgmt', () => {
-  let tmpModuleDir: string;
-
-  beforeEach(() => {
-    // Use the real manifest's hooks but point them at a noop script
-    // in a temp dir so we don't actually shell out to `bun add -g`.
-    tmpModuleDir = mkdtempSync(join(tmpdir(), 'celilo-mgmt-hook-test-'));
-    mkdirSync(join(tmpModuleDir, 'scripts'), { recursive: true });
-    const scriptPath = join(tmpModuleDir, 'scripts', 'on_upstream_publish.sh');
-    // Record the env we received so the test can verify the dispatcher
-    // passed the right vars. Sentinel file lives in tmpModuleDir.
-    const logPath = join(tmpModuleDir, 'invocations.log');
-    writeFileSync(
-      scriptPath,
-      `#!/usr/bin/env bash
-echo "name=$CELILO_EVENT_PACKAGE_NAME version=$CELILO_EVENT_PACKAGE_VERSION tag=$CELILO_EVENT_TAG" >> ${logPath}
-exit 0
-`,
-    );
-    chmodSync(scriptPath, 0o755);
+describe('celilo-mgmt declares no on_upstream_publish (self-update is framework work)', () => {
+  test('the real manifest has no on_upstream_publish block', () => {
+    const manifestPath = join(REPO_ROOT, 'modules', 'celilo-mgmt', 'manifest.yml');
+    const parsed = parseYaml(readFileSync(manifestPath, 'utf-8')) as {
+      hooks?: Record<string, unknown>;
+    };
+    expect(parsed.hooks?.on_upstream_publish).toBeUndefined();
+    // The module is still the canonical build-bus subscriber via its
+    // registry-poll subscription — that half did not move.
+    expect(Object.keys(parsed.hooks ?? {})).toContain('on_backup');
   });
+});
 
-  afterEach(() => {
-    rmSync(tmpModuleDir, { recursive: true, force: true });
+describe('planSelfUpdate (the old manifest match rules, now in the framework)', () => {
+  test('a @celilo/cli@latest npm event self-updates the cli binary', () => {
+    const plan = planSelfUpdate(buildEvent({ package: { name: '@celilo/cli', version: '0.5.0' } }));
+    expect(plan).toEqual({ packageName: '@celilo/cli', version: '0.5.0', binary: 'celilo' });
   });
 
-  function buildModuleContext(): ModuleHookContext {
-    const hooks = loadCeliloMgmtHooks();
-    // Rewrite the script path to point at the temp noop. The match
-    // rules from the real manifest are preserved — that's what we're
-    // testing.
-    return {
-      moduleId: 'celilo-mgmt',
-      sourcePath: tmpModuleDir,
-      hooks,
-    };
-  }
+  test('a @celilo/e2e@latest npm event self-updates the e2e binary', () => {
+    const plan = planSelfUpdate(buildEvent({ package: { name: '@celilo/e2e', version: '0.8.0' } }));
+    expect(plan).toEqual({ packageName: '@celilo/e2e', version: '0.8.0', binary: 'cele2e' });
+  });
 
-  test('the real manifest declares two on_upstream_publish hooks (cli + e2e)', () => {
-    const hooks = loadCeliloMgmtHooks();
-    expect(hooks).toHaveLength(2);
-    const names = hooks.map((h) => h.name).sort();
-    expect(names).toEqual(['self-update-celilo-cli', 'self-update-celilo-e2e']);
+  test('an alpha-tag event for @celilo/cli does NOT fire (tag must be "latest")', () => {
+    expect(
+      planSelfUpdate(
+        buildEvent({ tag: 'alpha', package: { name: '@celilo/cli', version: '0.5.0-alpha.0' } }),
+      ),
+    ).toBeNull();
   });
 
-  test('a @celilo/cli@latest event fires the celilo-cli hook only', async () => {
-    const dispatcher = await startHookDispatcher({
-      loadModules: () => [buildModuleContext()],
-    });
-    const results = await dispatcher.handleEvent(
-      buildEvent({ package: { name: '@celilo/cli', version: '0.5.0' } }),
-    );
-    await dispatcher.stop();
+  test('a non-celilo package does NOT fire', () => {
+    expect(
+      planSelfUpdate(buildEvent({ package: { name: 'left-pad', version: '1.3.0' } })),
+    ).toBeNull();
+  });
 
-    expect(results).toHaveLength(1);
-    expect(results[0].hookName).toBe('self-update-celilo-cli');
-    expect(results[0].exitCode).toBe(0);
+  test('a transitive @celilo package (no standalone binary) does NOT fire', () => {
+    expect(
+      planSelfUpdate(buildEvent({ package: { name: '@celilo/event-bus', version: '0.2.0' } })),
+    ).toBeNull();
+  });
 
-    // The log written by the noop script should show the env it received.
-    const log = readFileSync(join(tmpModuleDir, 'invocations.log'), 'utf-8');
-    expect(log).toContain('name=@celilo/cli version=0.5.0 tag=latest');
+  test('a non-npm registry event does NOT fire', () => {
+    expect(
+      planSelfUpdate(
+        buildEvent({
+          registry: 'celilo-registry',
+          package: { name: '@celilo/cli', version: '0.5.0' },
+        }),
+      ),
+    ).toBeNull();
   });
+});
 
-  test('a @celilo/e2e@latest event fires the celilo-e2e hook only', async () => {
-    const dispatcher = await startHookDispatcher({
-      loadModules: () => [buildModuleContext()],
-    });
-    const results = await dispatcher.handleEvent(
-      buildEvent({ package: { name: '@celilo/e2e', version: '0.8.0' } }),
-    );
-    await dispatcher.stop();
+describe('dispatcher runs the framework self-update behind the control-plane gate', () => {
+  let selfUpdateCalls: SelfUpdatePlan[];
 
-    expect(results).toHaveLength(1);
-    expect(results[0].hookName).toBe('self-update-celilo-e2e');
+  beforeEach(() => {
+    selfUpdateCalls = [];
   });
 
-  test('an alpha-tag event for @celilo/cli does NOT fire (tag must be "latest")', async () => {
-    const dispatcher = await startHookDispatcher({
-      loadModules: () => [buildModuleContext()],
-    });
-    const results = await dispatcher.handleEvent(
-      buildEvent({ tag: 'alpha', package: { name: '@celilo/cli', version: '0.5.0-alpha.0' } }),
-    );
-    await dispatcher.stop();
-    expect(results).toEqual([]);
+  afterEach(() => {
+    mock.restore();
   });
 
-  test('a non-celilo package (e.g. @celilo/event-bus) does NOT fire', async () => {
-    const dispatcher = await startHookDispatcher({
-      loadModules: () => [buildModuleContext()],
+  function start(controls: { installed: boolean }) {
+    return startHookDispatcher({
+      loadModules: () => [],
+      controlPlaneInstalled: () => controls.installed,
+      selfUpdate: (plan) => {
+        selfUpdateCalls.push(plan);
+        return {
+          packageName: plan.packageName,
+          version: plan.version,
+          beforeVersion: '0.4.0',
+          updated: true,
+          verified: true,
+        };
+      },
     });
+  }
+
+  test('control-plane installed + matching event → update runs with the right plan', async () => {
+    const dispatcher = await start({ installed: true });
     const results = await dispatcher.handleEvent(
-      buildEvent({ package: { name: '@celilo/event-bus', version: '0.2.0' } }),
+      buildEvent({ package: { name: '@celilo/cli', version: '0.5.0' } }),
     );
     await dispatcher.stop();
     expect(results).toEqual([]);
+    expect(selfUpdateCalls).toEqual([
+      { packageName: '@celilo/cli', version: '0.5.0', binary: 'celilo' },
+    ]);
   });
 
-  test('a non-npm registry event (e.g. celilo-registry module publish) does NOT fire', async () => {
-    const dispatcher = await startHookDispatcher({
-      loadModules: () => [buildModuleContext()],
-    });
-    const results = await dispatcher.handleEvent(
-      buildEvent({
-        registry: 'celilo-registry',
-        package: { name: '@celilo/cli', version: '0.5.0' },
-      }),
+  test('control-plane NOT installed → no self-update even on a matching event', async () => {
+    const dispatcher = await start({ installed: false });
+    await dispatcher.handleEvent(
+      buildEvent({ package: { name: '@celilo/cli', version: '0.5.0' } }),
     );
     await dispatcher.stop();
-    expect(results).toEqual([]);
+    expect(selfUpdateCalls).toEqual([]);
   });
-});
-
-/**
- * The durable outcome record (celilo#1304): every dispatched run lands in
- * the `build_bus_hook_runs` ledger via the injectable recordRun. Without it
- * a failed self-update existed only as daemon console output, which no
- * surface reads.
- */
-describe('hook-dispatcher outcome record', () => {
-  test('a failing script records exit code, stderr tail, and the event identity', async () => {
-    const failDir = mkdtempSync(join(tmpdir(), 'hook-record-test-'));
-    const scriptPath = join(failDir, 'fail.sh');
-    writeFileSync(scriptPath, '#!/usr/bin/env bash\necho "boom" >&2\nexit 7\n');
-    chmodSync(scriptPath, 0o755);
-
-    const recorded: Array<{
-      event: PublishEvent;
-      result: { exitCode: number | null; stderr: string };
-    }> = [];
-    const dispatcher = await startHookDispatcher({
-      loadModules: () => [
-        {
-          moduleId: 'celilo-mgmt',
-          sourcePath: failDir,
-          hooks: [
-            {
-              name: 'self-update-celilo-cli',
-              match: { registry: 'npm', tag: 'latest', package_pattern: '@celilo/cli' },
-              script: 'fail.sh',
-            },
-          ],
-        },
-      ],
-      recordRun: (event, result) => recorded.push({ event, result }),
-    });
 
+  test('a non-binary package (e.g. @celilo/event-bus) never self-updates', async () => {
+    const dispatcher = await start({ installed: true });
     await dispatcher.handleEvent(
-      buildEvent({ package: { name: '@celilo/cli', version: '2.2.1' } }),
+      buildEvent({ package: { name: '@celilo/event-bus', version: '0.2.0' } }),
     );
     await dispatcher.stop();
-    rmSync(failDir, { recursive: true, force: true });
-
-    expect(recorded).toHaveLength(1);
-    expect(recorded[0].event.eventId).toBe('evt-1');
-    expect(recorded[0].event.package.name).toBe('@celilo/cli');
-    expect(recorded[0].result.exitCode).toBe(7);
-    expect(recorded[0].result.stderr).toContain('boom');
+    expect(selfUpdateCalls).toEqual([]);
   });
 });
+
+// The durable outcome record (celilo#1304) is exercised in
+// hook-dispatch-executor.test.ts, against the real ledger and the real
+// jailed executor — the old injectable-capture form here asserted the
+// bash path's exit code and stderr, which slice 7 deleted.

package/src/services/build-bus/hook-dispatch-path.test.ts

@@ -0,0 +1,95 @@
+/**
+ * The recurrence gate for module-orchestrator-primitives slice 7
+ * (tasks.md 7.1): exactly ONE hook dispatch path.
+ *
+ * A module-declared hook is anything a manifest declares under `hooks:`.
+ * Since slice 7, every such hook — including `on_upstream_publish` — is
+ * executed by the ordinary executor (`apps/celilo/src/hooks/executor.ts`
+ * → `hook-runner.ts`, jailed). No other celilo service may spawn a
+ * process to run one. That second path is how `bash <script>` with the
+ * whole of celilo's `process.env` reached a module-supplied script
+ * (design D6).
+ *
+ * The scan asserts on the DISPATCH, not on an interpreter name: it flags
+ * any file that (a) reaches a child process AND (b) consumes what a
+ * module declares under `hooks:`. Asserting on the literal `bash` would
+ * pass the moment someone renamed the interpreter, and would miss a
+ * second path built on `sh`, `bun run` or a direct `Bun.spawn`.
+ *
+ * `apps/celilo/src/hooks/**` is the one sanctioned path and is exempt:
+ * `executor.ts` and `hook-runner.ts` are where module-declared hooks are
+ * supposed to be spawned, jailed. Every other service file that both
+ * spawns and reads hook declarations is a second dispatch path.
+ *
+ * Seen-fail note (Rule 7.6): this scan was written RED against
+ * `hook-dispatch.ts` at the spawn it then contained, and re-proven RED in
+ * task 7.5 by restoring that spawn in a scratch copy of the tree.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC_ROOT = join(__dirname, '..', '..');
+
+/** Directories that ARE the one hook dispatch path. Spawning there is the design. */
+const EXEMPT_DIRS = new Set(['hooks']);
+
+/**
+ * (a) The file reaches a child process. Covers `node:child_process` in
+ * every spelling plus Bun's own spawner.
+ */
+const CHILD_PROCESS_REACH = /node:child_process|Bun\.spawn/;
+
+/**
+ * (b) The file consumes a hook's declared SCRIPT for dispatch — the input
+ * side of a hook execution. Deliberately narrow: a service that merely
+ * PEEKS at the manifest hooks block to gate a framework call (e.g.
+ * `system update` reading `hooks?.on_backup` to skip a backup) reads hook
+ * declarations without dispatching one, and stays out of scope. Comment
+ * mentions are stripped before matching: a docblock naming the hook this
+ * gate replaced is prose, not a dispatch.
+ */
+const HOOK_DISPATCH_MARKERS = ['UpstreamHookEntry', 'planHookDispatch', 'hook.script'];
+
+/**
+ * Strip line and block comments so a prose mention of a marker does not
+ * flag a file. Conservative on purpose: strings containing `//` (URLs) can
+ * lose a tail, which is safe here — it can only REMOVE a match, and a
+ * string carrying a hook-dispatch marker is not itself a dispatch.
+ */
+function stripComments(src: string): string {
+  return src.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/^\s*\/\/.*$/gm, ' ');
+}
+
+function listTsFiles(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      if (EXEMPT_DIRS.has(entry)) continue;
+      listTsFiles(full, out);
+    } else if (entry.endsWith('.ts') && !entry.endsWith('.test.ts')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+describe('exactly one hook dispatch path (module-orchestrator-primitives 7.1)', () => {
+  test('no service outside apps/celilo/src/hooks spawns a process for a module-declared hook', () => {
+    const violations: string[] = [];
+    for (const file of listTsFiles(SRC_ROOT)) {
+      const src = stripComments(readFileSync(file, 'utf-8'));
+      if (!CHILD_PROCESS_REACH.test(src)) continue;
+      if (!HOOK_DISPATCH_MARKERS.some((m) => src.includes(m))) continue;
+      violations.push(file.replace(`${SRC_ROOT}/`, ''));
+    }
+    expect(violations).toEqual([]);
+  });
+
+  test('the one sanctioned path still exists (executor.ts)', () => {
+    const executor = readFileSync(join(SRC_ROOT, 'hooks', 'executor.ts'), 'utf-8');
+    expect(executor).toContain('export async function invokeHook');
+    expect(executor).toContain('export async function executeHookScript');
+  });
+});