ruvnet-brain 4.2.2-dev → 4.3.1-dev

package/scripts/wired-check.mjs

@@ -98,11 +98,10 @@ const STANDALONE = [
   ['fix-workstream', 'session-supervised coordination CLI run explicitly by the integration owner or an '
     + 'isolated writing agent to start and hand off a fix lane. Scheduling it would violate its safety '
     + 'boundary: it prepares evidence but never merges, pushes, publishes, deletes, or cleans worktrees'],
-  // Run by the launchd nightly, which lives OUTSIDE this repo — so no in-repo caller can exist.
-  // This is the one category the scanner genuinely cannot reach, and saying so is the honest form.
-  ['self-update', 'launchd nightly (out-of-repo scheduler)'],
+  ['self-update', 'author-run candidate rebuild; --apply is guarded by worktree-integrity.mjs and is not scheduled'],
+  ['ingest-new-repos', 'author-run corpus expansion; --apply is guarded by worktree-integrity.mjs and is not scheduled'],
   ['count-chunks', 'human-run CLI — recount + restamp chunk surfaces (--check for drift); no scheduler'],
-  ['brain-stamp', 'invoked by self-update.mjs:249, the nightly launchd driver (com.ruvnet.brain-nightly)'],
+  ['brain-stamp', 'invoked by the author-run self-update.mjs candidate builder'],
   ['lesson-promote', 'human-run CLI — promotion is manual (--apply); no scheduler yet (automation is ADR-029 #4, open)'],
   ['behavioral-l1-l4', 'behavioural harness invoked by its own test file — not a product path'],
   // A measurement harness, not a product path: it answers "would bounding the cross-encoder pool
@@ -129,8 +128,7 @@ const STANDALONE = [
     + 'com.stuartkerr.clear-claude-tmp.plist is loaded and its ProgramArguments invoke this exact file'],
   ['nightly-gists', 'launchd nightly 21:47 (out-of-repo scheduler) — confirmed live: '
     + 'com.ruvnet.brain-gists.plist is loaded and its ProgramArguments invoke this exact file'],
-  ['nightly-wrapper', 'launchd nightly 03:15 (out-of-repo scheduler) — confirmed live: '
-    + 'com.ruvnet.brain-nightly.plist is loaded and its ProgramArguments invoke this exact file'],
+  ['nightly-wrapper', 'author-run maintenance harness, deliberately unscheduled; refuses primary, nested, and dirty worktrees'],
   ['routing-flywheel', 'launchd nightly 04:45 --dry-run (out-of-repo scheduler) — confirmed live: '
     + 'com.ruvnet.routing-flywheel.plist is loaded and its ProgramArguments invoke this exact file'],
   ['install-npx-witness', 'one-shot idempotent installer for the com.ruvnet.npx-witness launchd job, '
@@ -298,8 +296,21 @@ const INVENTORY_ROOTS = [
  * invoker outside the roots proves the ROOTS are incomplete — the fix is to add the root, never to
  * write an exemption. That rule caught its own author within a minute of the gate first running.
  */
-const CALLER_ROOTS = ['scripts', 'plugin', 'console', 'bin', '.github', '.claude', 'package.json'];
+// `dream.config.json` is executable configuration, not documentation: the Dream compiler runs its
+// controlPlaneProbes and evaluatorEntrypoints. Excluding it made two real scheduled callers look
+// dead while the same scanner already trusted workflow YAML and package.json command manifests.
+const CALLER_ROOTS = [
+  'scripts', 'plugin', 'console', 'bin', '.github', '.claude', 'package.json', 'dream.config.json',
+];
 const CALLER_EXTS = new Set(['.mjs', '.js', '.sh', '.json', '.html', '.yml', '.yaml']);
+export const REQUIRED_OPERATIONAL_EXPORTS = [
+  { rel: 'scripts/corpus-reconcile.mjs', symbol: 'syncCorpusInputs' },
+  { rel: 'scripts/corpus-reconcile.mjs', symbol: 'materializeGistReceipts' },
+  { rel: 'scripts/corpus-reconcile.mjs', symbol: 'observeAndMaterializeGistReceipts' },
+  { rel: 'scripts/corpus-aggregates.mjs', symbol: 'rebuildCorpusAggregates' },
+  { rel: 'scripts/corpus-reconcile.mjs', symbol: 'reconcileCorpusUntilStable' },
+  { rel: 'scripts/corpus-reconcile.mjs', symbol: 'reconcileAndPrepareCorpusCandidate' },
+];
 
 const isTestFile = (f) => /\.(test|spec)\.(mjs|js)$/.test(path.basename(f))
   || f.includes(`${path.sep}tests${path.sep}`) || f.startsWith(`tests${path.sep}`);
@@ -505,7 +516,33 @@ export function callersOf(mod, files, repo = REPO) {
   return hits;
 }
 
-export function audit({ repo = REPO, standalone = STANDALONE, held = HELD } = {}) {
+export function operationalExportAudit({ repo = REPO, required = REQUIRED_OPERATIONAL_EXPORTS } = {}) {
+  const files = callerFiles(repo);
+  const rows = required.map(({ rel, symbol }) => {
+    const sourceFile = path.join(repo, rel);
+    let source = '';
+    try { source = fs.readFileSync(sourceFile, 'utf8'); } catch { /* reported as missing below */ }
+    const quoted = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const exported = new RegExp(`\\bexport\\s+(?:async\\s+)?function\\s+${quoted}\\s*\\(`).test(source);
+    if (!exported) return { rel, symbol, state: 'missing', callers: [] };
+    const declaration = new RegExp(`\\bexport\\s+(?:async\\s+)?function\\s+${quoted}\\s*\\(`, 'g');
+    const invocation = new RegExp(`\\b${quoted}\\s*\\(`);
+    const callers = [];
+    for (const file of files) {
+      const callerRel = path.relative(repo, file).split(path.sep).join('/');
+      if (isTestFile(callerRel)) continue;
+      let body = '';
+      try { body = stripComments(fs.readFileSync(file, 'utf8'), path.extname(file)); } catch { continue; }
+      body = body.replace(declaration, 'export function __operational_definition__(');
+      if (invocation.test(body)) callers.push(callerRel);
+    }
+    return { rel, symbol, state: callers.length ? 'wired' : 'unwired', callers };
+  });
+  return { rows };
+}
+
+export function audit({ repo = REPO, standalone = STANDALONE, held = HELD,
+  operationalExports = REQUIRED_OPERATIONAL_EXPORTS } = {}) {
   const dupes = [];
   const seen = new Map();
   for (const [name, why] of standalone) {
@@ -532,13 +569,15 @@ export function audit({ repo = REPO, standalone = STANDALONE, held = HELD } = {}
           state = 'manual';
           const list = names.map((n) => `\`${n}\``).join(', ');
           why = `defined as npm script ${list} and invoked by NOTHING automated — reachable only by a `
-            + `human typing \`npm run ${names[0]}\`. Built and correct; not in any ship path.`;
+            + `human typing \`npm run ${names[0]}\`. This wiring audit does not establish operational `
+            + `correctness.`;
         }
       }
     }
     rows.push({ ...m, state, callers, ...(why ? { why } : {}) });
   }
-  return { rows, dupes, inventory: all.length };
+  const operationalRows = operationalExportAudit({ repo, required: operationalExports }).rows;
+  return { rows, operationalRows, dupes, inventory: all.length };
 }
 
 /**
@@ -567,9 +606,12 @@ export function audit({ repo = REPO, standalone = STANDALONE, held = HELD } = {}
  * exists to prevent), different surface. Two new, narrow predicates, each modelling the REAL
  * mechanism Claude Code / the lesson dispatcher actually uses, not a generic text search:
  *
- *   CHECK B — HOOK WIRING. Walks the real reachability chain: plugin/hooks/hooks.json (what we
- *   ship) → hook-shim.mjs's own TABLE (resolving its id-based indirection explicitly, since a hook
- *   id like "route-dispatch" is not the string "route-dispatch.sh") → this repo's own
+ *   CHECK B — HOOK WIRING. Walks the real reachability chain for both supported hosts:
+ *   plugin/hooks/hooks.json (Claude Code) → hook-shim.mjs's own TABLE (resolving its id-based
+ *   indirection explicitly, since a hook id like "route-dispatch" is not the string
+ *   "route-dispatch.sh"); and plugin/hooks/codex-hooks.json → bin/install.mjs's Stable Spine copy
+ *   (codex-hook-wrapper.mjs installed as codex-hook.mjs) → codex-hook-adapter.mjs. It also reads
+ *   this repo's own
  *   .claude/settings.json → the user's REAL ~/.claude/settings.json (what is actually installed on
  *   THIS machine — never checked before). One further hop is closed by a small fixed-point pass
  *   (the unprompted-speech runtime spawns anticipate.sh/lesson-hooks.sh as candidate producers),
@@ -671,6 +713,28 @@ function hookShimIdIn(cmd) {
   return m ? m[1] : null;
 }
 
+/** The dispatch id after Codex's inline bootstrap and numeric timeout. Same grammar as hook-registry. */
+function codexHookIdIn(cmd) {
+  const m = cmd.match(/"\s+\d+\s+([a-zA-Z][\w-]*)/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Derive the Stable Spine wrapper copy from the installer source. The Codex manifest names the
+ * durable installed target (`codex-hook.mjs`), while the repository inventory contains its source
+ * (`codex-hook-wrapper.mjs`). Both names plus the actual copy operation must be present; otherwise
+ * there is no proven bridge and the hook stays unwired.
+ */
+function installedCodexHookWrapper(repo) {
+  let src = '';
+  try { src = fs.readFileSync(path.join(repo, 'bin/install.mjs'), 'utf8'); } catch { return null; }
+  const stripped = stripComments(src, '.mjs');
+  const source = stripped.match(/hookWrapperSource\s*=\s*path\.join\([^\n]*['"]([\w.-]+\.mjs)['"]\)/)?.[1];
+  const target = stripped.match(/const codexHookWrapperPath[\s\S]{0,260}?['"]([\w.-]+\.mjs)['"]\)/)?.[1];
+  const copiesSource = /fs\.copyFileSync\(hookWrapperSource,\s*tmp\)/.test(stripped);
+  return source && target && copiesSource ? { source, target } : null;
+}
+
 /** hook-shim.mjs's own dispatch TABLE: id -> file. Parsed, not re-implemented — it IS the authority. */
 function hookShimTable(repo) {
   let src = '';
@@ -691,9 +755,9 @@ function hookHeaderDeclares(src) { return HOOK_EVENT_RE.test(src.slice(0, 1600))
 
 /**
  * CHECK B — HOOK WIRING. See the file-level comment above for the full reasoning. Walks the real
- * chain from the real entry points (plugin/hooks/hooks.json, this repo's .claude/settings.json, the
- * user's actual ~/.claude/settings.json) through hook-shim.mjs's id-based indirection, then closes
- * one further hop with a small fixed-point pass restricted to files already proven reachable.
+ * chain from the real entry points (both plugin hook manifests, this repo's .claude/settings.json,
+ * the user's actual ~/.claude/settings.json) through each host's real indirection, then closes one
+ * further hop with a small fixed-point pass restricted to files already proven reachable.
  */
 export function hookWiringAudit({
   repo = REPO,
@@ -701,6 +765,7 @@ export function hookWiringAudit({
   held = HOOK_HELD,
 } = {}) {
   const table = hookShimTable(repo);
+  const codexWrapper = installedCodexHookWrapper(repo);
   const reached = new Map(); // basename -> Set(reason)
   const add = (name, reason) => {
     if (!name) return;
@@ -708,16 +773,21 @@ export function hookWiringAudit({
     reached.get(name).add(reason);
   };
 
-  const scanConfig = (file, label) => {
+  const scanConfig = (file, label, { codex = false } = {}) => {
     const doc = readJsonSafe(file);
     if (!doc || !doc.hooks) return;
     for (const cmd of commandStrings(doc.hooks)) {
-      for (const b of basenamesIn(cmd)) add(b, label);
-      const id = hookShimIdIn(cmd);
-      if (id && table[id]) add(table[id], `${label} (hook-shim id "${id}")`);
+      const basenames = basenamesIn(cmd);
+      for (const b of basenames) add(b, label);
+      const id = codex ? codexHookIdIn(cmd) : hookShimIdIn(cmd);
+      if (id && table[id]) add(table[id], `${label} (${codex ? 'Codex dispatch' : 'hook-shim'} id "${id}")`);
+      if (codex && codexWrapper && basenames.includes(codexWrapper.target)) {
+        add(codexWrapper.source, `${label} via bin/install.mjs Stable Spine copy (${codexWrapper.target})`);
+      }
     }
   };
   scanConfig(path.join(repo, 'plugin/hooks/hooks.json'), 'plugin/hooks/hooks.json');
+  scanConfig(path.join(repo, 'plugin/hooks/codex-hooks.json'), 'plugin/hooks/codex-hooks.json', { codex: true });
   scanConfig(path.join(repo, '.claude/settings.json'), '.claude/settings.json (this repo)');
   scanConfig(homeSettingsFile, '~/.claude/settings.json (this machine)');
 
@@ -753,7 +823,14 @@ export function hookWiringAudit({
   return { rows, plumbing: HOOK_PLUMBING };
 }
 
-/** The trigger tokens requested by lesson-hooks.sh's `case "$EVENT" in` block — the sole authority. */
+/**
+ * The trigger tokens requested by lesson-hooks.sh — the sole authority. A trigger reaches the gate
+ * two ways: a static `case "$EVENT" in ... TRIGGERS="<name>"` label, or a dynamic conditional append
+ * (`ARGS+=(--trigger <name>)`, e.g. `ship`, appended only when a live regex matches the real command
+ * text). Reading only the static form means a trigger whose SOLE live path is dynamic is invisible
+ * to this audit — and Check C would then depend on an unrelated dead case label merely coexisting in
+ * the file to report it correctly, which breaks the moment that dead label is ever cleaned up.
+ */
 function lessonHooksRequestedTriggers(repo) {
   let src = '';
   try { src = fs.readFileSync(path.join(repo, 'plugin/scripts/lesson-hooks.sh'), 'utf8'); } catch { return new Set(); }
@@ -762,6 +839,8 @@ function lessonHooksRequestedTriggers(repo) {
   const re = /TRIGGERS="([^"]*)"/g;
   let m;
   while ((m = re.exec(stripped))) { for (const t of m[1].split(/\s+/)) if (t) requested.add(t); }
+  const dynRe = /ARGS\+=\(--trigger\s+"?([A-Za-z][\w-]*)"?\)/g;
+  while ((m = dynRe.exec(stripped))) { requested.add(m[1]); }
   return requested;
 }
 
@@ -784,9 +863,10 @@ const invokedDirectly = process.argv[1]
   && path.resolve(process.argv[1]).endsWith(`wired-check${path.extname(process.argv[1])}`);
 
 if (invokedDirectly) {
-  const { rows, dupes, inventory } = audit();
+  const { rows, operationalRows, dupes, inventory } = audit();
   const by = (s) => rows.filter((r) => r.state === s);
   const unwired = by('unwired');
+  const operationalUnwired = operationalRows.filter((row) => row.state !== 'wired');
 
   const hookAudit = hookWiringAudit();
   const hookBy = (s) => hookAudit.rows.filter((r) => r.state === s);
@@ -805,6 +885,16 @@ if (invokedDirectly) {
       console.log(`  or add it to STANDALONE in this file WITH A TRUE REASON.\n`);
     }
 
+    console.log(`  ${operationalRows.length} release-critical operational export(s) checked · `
+      + `${operationalUnwired.length} UNWIRED\n`);
+    for (const row of operationalUnwired) {
+      console.log(`    ✗ ${row.rel}#${row.symbol} — exported, but no production invocation reaches it`);
+    }
+    if (operationalUnwired.length) {
+      console.log('\n  Importing or re-exporting a function is not operation. A release-critical export must');
+      console.log('  be invoked through a production path whose module is itself wired.\n');
+    }
+
     // Every exemption, every run. v1 never printed these, so 3 false reasons rotted unseen for a
     // day inside the gate built to stop exactly that.
     if (by('manual').length) {
@@ -821,7 +911,7 @@ if (invokedDirectly) {
     if (dupes.length) console.log(`  ✗ DUPLICATE exemption(s): ${dupes.join(', ')}\n`);
 
     // ── CHECK B: HOOK WIRING ──────────────────────────────────────────────────────────────────
-    console.log(`\n  ── HOOK WIRING — plugin/scripts/*.sh|*.mjs vs plugin/hooks/hooks.json, `
+    console.log(`\n  ── HOOK WIRING — plugin/scripts/*.sh|*.mjs vs plugin/hooks/{hooks,codex-hooks}.json, `
       + `.claude/settings.json, ~/.claude/settings.json ──\n`);
     console.log(`  ${hookAudit.rows.length} hook-intended script(s) in the census`);
     console.log(`    ${hookBy('wired').length} wired · ${hookBy('held').length} held · `
@@ -862,6 +952,6 @@ if (invokedDirectly) {
     }
   }
 
-  const bad = unwired.length || dupes.length || hookUnwired.length;
+  const bad = unwired.length || operationalUnwired.length || dupes.length || hookUnwired.length;
   process.exit(argv.includes('--check') && bad ? 1 : 0);
 }

package/scripts/worktree-integrity.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * One mutation boundary for author-side automation.
+ *
+ * A clean linked worktree is the only place a corpus/update command may write. The primary
+ * checkout is never a writer, even when it is on a feature branch, because scheduled work cannot
+ * distinguish the owner's active edits from its own generated changes. This module only classifies
+ * and refuses; it never resets, cleans, removes, commits, or switches a checkout.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+function git(cwd, args) {
+  const result = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8' });
+  if (result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || result.error?.message || 'unknown git error').trim();
+    throw new Error(`git ${args.join(' ')} failed: ${detail}`);
+  }
+  return String(result.stdout || '').trim();
+}
+
+function samePath(left, right) {
+  try { return fs.realpathSync(left) === fs.realpathSync(right); } catch { return false; }
+}
+
+function within(parent, candidate) {
+  const relative = path.relative(parent, candidate);
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function digest(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+export function inspectMutationWorktree(root) {
+  const requestedRoot = path.resolve(root);
+  const worktreeRoot = fs.realpathSync(git(requestedRoot, ['rev-parse', '--show-toplevel']));
+  const commonDirRaw = git(worktreeRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  const commonDir = fs.realpathSync(commonDirRaw);
+  const primaryRoot = fs.realpathSync(path.dirname(commonDir));
+  const dotGit = fs.lstatSync(path.join(worktreeRoot, '.git'));
+  const linked = dotGit.isFile();
+  const primary = samePath(worktreeRoot, primaryRoot);
+  const nestedInPrimary = !primary && within(primaryRoot, worktreeRoot);
+  const status = git(worktreeRoot, ['status', '--porcelain=v1', '--untracked-files=all']);
+  const clean = status.length === 0;
+  const allowed = linked && !primary && !nestedInPrimary && clean;
+  let reason = 'clean-linked-worktree';
+  if (primary) reason = 'primary-checkout';
+  else if (!linked) reason = 'not-linked-worktree';
+  else if (nestedInPrimary) reason = 'nested-inside-primary';
+  else if (!clean) reason = 'dirty-writer-worktree';
+  return { allowed, reason, worktreeRoot, primaryRoot, commonDir, linked, primary, nestedInPrimary, clean, status };
+}
+
+export function assertIsolatedMutationWorktree(root, operation = 'repository mutation') {
+  const state = inspectMutationWorktree(root);
+  if (!state.allowed) {
+    throw new Error(
+      `[worktree-integrity] DENIED ${operation}: ${state.reason}. `
+      + `Run author-side mutations in a clean linked worktree outside ${state.primaryRoot}; `
+      + 'the primary checkout is immutable to automation.',
+    );
+  }
+  return state;
+}
+
+/**
+ * Seal the primary checkout around an isolated author-side mutation.
+ *
+ * A status-only comparison is insufficient: a checkout that was already dirty can be modified
+ * again while keeping the same porcelain status. Bind HEAD, the staged diff, the full tracked
+ * working diff, and the exact non-ignored untracked-file set instead. Ignored runtime state (logs,
+ * AgentDB, locks) is deliberately outside the source-checkout contract.
+ */
+export function snapshotPrimaryCheckout(root) {
+  const { primaryRoot } = inspectMutationWorktree(root);
+  return {
+    primaryRoot,
+    head: git(primaryRoot, ['rev-parse', 'HEAD']),
+    indexDigest: digest(git(primaryRoot, ['diff', '--binary', '--cached', 'HEAD', '--'])),
+    trackedDigest: digest(git(primaryRoot, ['diff', '--binary', 'HEAD', '--'])),
+    untracked: git(primaryRoot, ['ls-files', '--others', '--exclude-standard', '-z'])
+      .split('\0').filter(Boolean).sort(),
+  };
+}
+
+export function assertPrimaryCheckoutUnchanged(root, before) {
+  const after = snapshotPrimaryCheckout(root);
+  const fields = ['primaryRoot', 'head', 'indexDigest', 'trackedDigest', 'untracked'];
+  const changed = fields.filter((field) => JSON.stringify(after[field]) !== JSON.stringify(before[field]));
+  if (changed.length) {
+    throw new Error(
+      `[worktree-integrity] PRIMARY CHECKOUT CHANGED during isolated mutation: ${changed.join(', ')}. `
+      + 'The candidate is invalid and must not be promoted.',
+    );
+  }
+  return after;
+}
+
+const invokedDirectly = process.argv[1]
+  && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  try {
+    const command = process.argv[2];
+    if (command === 'snapshot') {
+      process.stdout.write(`${JSON.stringify(snapshotPrimaryCheckout(process.argv[3] || process.cwd()))}\n`);
+    } else if (command === 'verify') {
+      const root = process.argv[3] || process.cwd();
+      const receipt = JSON.parse(fs.readFileSync(process.argv[4], 'utf8'));
+      process.stdout.write(`${JSON.stringify(assertPrimaryCheckoutUnchanged(root, receipt))}\n`);
+    } else {
+      const state = assertIsolatedMutationWorktree(command || process.cwd(), process.argv[3] || 'repository mutation');
+      process.stdout.write(`${JSON.stringify(state)}\n`);
+    }
+  } catch (error) {
+    console.error(error?.message || String(error));
+    process.exit(2);
+  }
+}