@event4u/agent-config 8.11.0 → 8.13.0

package/src/scripts/consumer_matrix.ts

@@ -4,15 +4,25 @@
  *
  * Exercises the PUBLISHED TARBALL the way a consumer does: pack → fresh
  * global install (isolated prefix) → `init` into a fresh project → doctor →
- * conformance → MCP stdio handshake → hook health → projection presence →
- * uninstall. Optional upgrade leg: install the last published minor from the
- * registry, then upgrade to the packed tarball and assert doctor stays green.
+ * conformance → MCP stdio handshake → hook health → hook lifecycle →
+ * projection presence → uninstall. Optional upgrade leg: install the last
+ * published minor from the registry, then upgrade to the packed tarball and
+ * assert doctor stays green.
  *
  * Why this exists: the release-PR gate skips source-level matrices (soundly —
  * a version-bump diff cannot regress source behaviour), but nothing between
  * merge and tag exercised the tarball shape. Two published minors shipped
  * without `src/install/` while published code imported from it; `tsx` was
  * missing from the published package; each manifested only at publish time.
+ * A third bug (missing `dist/install/rule_scope.js`) shipped past every leg
+ * because none of them fired a REAL installed hook command — `conformance`'s
+ * dispatcher smoke calls `dispatch_hook.ts` directly via `tsx`, bypassing the
+ * `agent-config` binary (and its ESM import graph) entirely. The `hooks`
+ * (static doctor) and `hook-lifecycle` (this file's live leg, below) legs
+ * close that gap: the latter runs the EXACT shell command Claude installed in
+ * `~/.claude/settings.json`, so a crash anywhere in the binary's load path —
+ * including a missing compiled sibling module — fails the leg with the
+ * culprit's stderr, not silently at publish time.
  * Every leg here asserts exit code + an expected artifact, no LLM calls.
  *
  * Usage:
@@ -30,7 +40,9 @@ import { spawnSync, spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { MANAGED_SIGNATURE } from './_lib/claude_settings_hooks.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -63,7 +75,7 @@ function log(msg: string): void {
 function run(
     cmd: string,
     args: string[],
-    opts: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number } = {},
+    opts: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number; input?: string } = {},
 ): { status: number; stdout: string; stderr: string } {
     const r = spawnSync(cmd, args, {
         cwd: opts.cwd ?? REPO_ROOT,
@@ -71,6 +83,7 @@ function run(
         encoding: 'utf8',
         timeout: opts.timeoutMs ?? 600_000,
         maxBuffer: 32 * 1024 * 1024,
+        input: opts.input,
     });
     return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
 }
@@ -216,6 +229,210 @@ function legHooks(ctx: Ctx): string {
     return 'hooks:doctor green';
 }
 
+// ── hook-lifecycle leg ─────────────────────────────────────────────
+//
+// `hooks:doctor` (above) is a read-only static report — it never runs
+// anything. `conformance`'s dispatcher smoke calls `dispatch_hook.ts`
+// directly via `tsx`, bypassing the installed `agent-config` binary (and
+// its ESM import graph) entirely. Neither exercises what a real Claude
+// Code SessionStart/PreToolUse/PostToolUse/Stop event actually invokes:
+// the exact shell command the installer registered in
+// `~/.claude/settings.json`. This leg does — plus a deterministic
+// completeness check on the compiled entrypoint's module graph, so a
+// missing sibling `.js` (the historical `dist/install/rule_scope.js` bug)
+// fails with the exact culprit instead of a live crash.
+
+interface HookCommandEntry {
+    /** Native platform event name, e.g. `SessionStart`, `PreToolUse`. */
+    nativeEvent: string;
+    /** The exact managed shell command string installed for this event. */
+    command: string;
+}
+
+/**
+ * Read every agent-config-managed hook command out of an installed Claude
+ * settings file, keyed by native event. Mirrors the shape
+ * `ensure_managed_hooks` (src/scripts/_lib/claude_settings_hooks.ts) writes;
+ * a group is "managed" iff one of its commands contains `MANAGED_SIGNATURE`
+ * — the same identity check the installer itself uses, so this can never
+ * drift from what actually got registered.
+ */
+export function readInstalledClaudeHookCommands(settingsPath: string): HookCommandEntry[] {
+    if (!fs.existsSync(settingsPath)) return [];
+    const raw = JSON.parse(fs.readFileSync(settingsPath, 'utf8')) as {
+        hooks?: Record<string, Array<{ hooks?: Array<{ command?: unknown }> }>>;
+    };
+    const hooks = raw.hooks ?? {};
+    const out: HookCommandEntry[] = [];
+    for (const [nativeEvent, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+            for (const h of group.hooks ?? []) {
+                if (typeof h.command === 'string' && h.command.includes(MANAGED_SIGNATURE)) {
+                    out.push({ nativeEvent, command: h.command });
+                }
+            }
+        }
+    }
+    return out;
+}
+
+/** A representative Claude Code event envelope, shaped per native event. */
+export function buildHookEnvelope(nativeEvent: string, projectDir: string): string {
+    const base = {
+        session_id: 'consumer-matrix-fixture',
+        transcript_path: '',
+        cwd: projectDir,
+        hook_event_name: nativeEvent,
+    };
+    switch (nativeEvent) {
+        case 'PreToolUse':
+            return JSON.stringify({
+                ...base,
+                tool_name: 'Read',
+                tool_input: { file_path: path.join(projectDir, 'README.md') },
+            });
+        case 'PostToolUse':
+            return JSON.stringify({
+                ...base,
+                tool_name: 'Read',
+                tool_input: { file_path: path.join(projectDir, 'README.md') },
+                tool_response: { success: true },
+            });
+        case 'Stop':
+            return JSON.stringify({ ...base, stop_hook_active: false });
+        case 'UserPromptSubmit':
+            return JSON.stringify({ ...base, prompt: 'consumer-matrix smoke prompt' });
+        case 'SessionEnd':
+            return JSON.stringify({ ...base, reason: 'exit' });
+        case 'SessionStart':
+        default:
+            return JSON.stringify({ ...base, source: 'startup' });
+    }
+}
+
+/**
+ * Run one installed hook command exactly as the platform would — a shell
+ * invocation with the event envelope piped to stdin — and report whether it
+ * exited clean.
+ */
+export function invokeHookCommand(
+    entry: HookCommandEntry,
+    opts: { cwd: string; env: NodeJS.ProcessEnv; projectDir: string; timeoutMs?: number },
+): { ok: boolean; status: number; stderrTail: string } {
+    const payload = buildHookEnvelope(entry.nativeEvent, opts.projectDir);
+    const r = run('bash', ['-c', entry.command], {
+        cwd: opts.cwd,
+        env: opts.env,
+        timeoutMs: opts.timeoutMs ?? 30_000,
+        input: payload,
+    });
+    const stderrTail = r.stderr.trim().split('\n').slice(-5).join(' | ');
+    return { ok: r.status === 0, status: r.status, stderrTail };
+}
+
+interface MissingModule {
+    from: string;
+    spec: string;
+    resolved: string;
+}
+
+/**
+ * Extract relative (`./`, `../`) ESM specifiers from a compiled `.js` file —
+ * static `from "..."`, bare `import "...";`, and dynamic `import("...")`.
+ * Regex, not a full parser: good enough for tsc's fixed output shape, and
+ * deliberately ignores bare package specifiers (`from 'commander'`) so the
+ * walk never leaves the package's own `dist/` tree.
+ */
+export function parseRelativeSpecifiers(source: string): string[] {
+    const out = new Set<string>();
+    const patterns = [
+        /\bfrom\s*["']([^"']+)["']/g,
+        /^\s*import\s*["']([^"']+)["']\s*;/gm,
+        /\bimport\(\s*["']([^"']+)["']\s*\)/g,
+    ];
+    for (const re of patterns) {
+        let m: RegExpExecArray | null;
+        while ((m = re.exec(source)) !== null) {
+            const spec = m[1];
+            if (spec && (spec.startsWith('./') || spec.startsWith('../'))) out.add(spec);
+        }
+    }
+    return [...out];
+}
+
+/**
+ * Walk the compiled ESM module graph reachable from `entryFile`, following
+ * every relative import/export/dynamic-import specifier, and report any
+ * resolved target that does not exist on disk — the deterministic twin of
+ * "does this crash at require time", without spawning a process.
+ */
+export function walkEsmModuleGraph(entryFile: string): { visited: string[]; missing: MissingModule[] } {
+    const visited = new Set<string>();
+    const missing: MissingModule[] = [];
+    const stack: string[] = [entryFile];
+    while (stack.length > 0) {
+        const file = stack.pop() as string;
+        if (visited.has(file)) continue;
+        visited.add(file);
+        let source: string;
+        try {
+            source = fs.readFileSync(file, 'utf8');
+        } catch {
+            missing.push({ from: '(entry)', spec: file, resolved: file });
+            continue;
+        }
+        for (const spec of parseRelativeSpecifiers(source)) {
+            const resolved = path.resolve(path.dirname(file), spec);
+            if (!fs.existsSync(resolved)) {
+                missing.push({ from: file, spec, resolved });
+                continue;
+            }
+            if (!visited.has(resolved)) stack.push(resolved);
+        }
+    }
+    return { visited: [...visited], missing };
+}
+
+/** Dist-manifest completeness gate — every module the entrypoint can reach exists. */
+export function checkDistManifestCompleteness(entryFile: string): { ok: boolean; message: string } {
+    const { visited, missing } = walkEsmModuleGraph(entryFile);
+    if (missing.length > 0) {
+        const detail = missing
+            .slice(0, 5)
+            .map((m) => `${path.relative(path.dirname(entryFile), m.from)} → missing ${m.spec}`)
+            .join('; ');
+        return { ok: false, message: `dist-manifest incomplete: ${missing.length} missing module(s): ${detail}` };
+    }
+    return {
+        ok: true,
+        message: `dist-manifest complete — ${visited.length} module(s) reachable from ${path.basename(entryFile)}`,
+    };
+}
+
+function legHookLifecycle(ctx: Ctx): string {
+    const settingsPath = path.join(ctx.tmpRoot, 'home', '.claude', 'settings.json');
+    const entries = readInstalledClaudeHookCommands(settingsPath);
+    if (entries.length === 0) {
+        throw new Error(`no managed Claude hook commands found in ${settingsPath} (did init register hooks?)`);
+    }
+
+    const entryScript = fs.realpathSync(ctx.bin);
+    const manifestCheck = checkDistManifestCompleteness(entryScript);
+    if (!manifestCheck.ok) throw new Error(manifestCheck.message);
+
+    const env = { ...binEnv(ctx), CLAUDE_PROJECT_DIR: ctx.projectDir };
+    const fired: string[] = [];
+    for (const entry of entries) {
+        const result = invokeHookCommand(entry, { cwd: ctx.projectDir, env, projectDir: ctx.projectDir });
+        if (!result.ok) {
+            throw new Error(`hook '${entry.nativeEvent}' exited ${result.status}: ${result.stderrTail}`);
+        }
+        fired.push(`${entry.nativeEvent}=${result.status}`);
+    }
+    return `${manifestCheck.message}; fired ${fired.length} live event(s): ${fired.join(', ')}`;
+}
+
 function legProjections(ctx: Ctx): string {
     const home = path.join(ctx.tmpRoot, 'home');
     const missing = ['.cursor/rules', '.codeium/windsurf', '.claude/skills']
@@ -278,6 +495,7 @@ const LEGS: Array<{ name: string; fn: (ctx: Ctx) => string | Promise<string> }>
     { name: 'conformance', fn: legConformance },
     { name: 'mcp-handshake', fn: legMcpHandshake },
     { name: 'hooks', fn: legHooks },
+    { name: 'hook-lifecycle', fn: legHookLifecycle },
     { name: 'projections', fn: legProjections },
     { name: 'uninstall', fn: legUninstall },
     { name: 'upgrade', fn: legUpgrade },
@@ -383,10 +601,31 @@ async function main(): Promise<number> {
     return failed ? 1 : 0;
 }
 
-main().then(
-    (code) => process.exit(code),
-    (err) => {
-        log(`❌  consumer-matrix crashed: ${(err as Error).stack ?? err}`);
-        process.exit(2);
-    },
-);
+// Entry guard (mirrors src/scripts/hooks/dispatch_hook.ts): a test file
+// imports the pure helpers above (readInstalledClaudeHookCommands,
+// checkDistManifestCompleteness, invokeHookCommand, …) without wanting a
+// full `npm pack` + global-install run to fire as a side effect of the
+// import. `main()` only runs when this file is the process's actual entry
+// point (`npx tsx src/scripts/consumer_matrix.ts …`).
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    main().then(
+        (code) => process.exit(code),
+        (err) => {
+            log(`❌  consumer-matrix crashed: ${(err as Error).stack ?? err}`);
+            process.exit(2);
+        },
+    );
+}

package/src/scripts/council_cli.ts

@@ -25,6 +25,7 @@ import {
     bundle_roadmap,
 } from './ai_council/bundler.js';
 import { select_chairman } from './ai_council/chairman.js';
+import { jaccardSimilarity } from './_lib/text_similarity.js';
 import type { ChairmanCandidate } from './ai_council/chairman.js';
 import { synthesis_template } from './ai_council/prompts.js';
 import type {
@@ -1906,6 +1907,7 @@ function cmd_run(
         _isDict(ai_cfg) &&
         _isDict(ai_cfg['stance_tally']) &&
         (ai_cfg['stance_tally'] as Dict)['enabled'] === true;
+    const stance_repairs: CouncilResponse[] = [];
     const responses = consult(members, question, budget, {
         table,
         project,
@@ -1913,6 +1915,14 @@ function cmd_run(
         rounds,
         advisor_plans,
         stance_tally: stance_tally_on,
+        // Interactive one-line confirm (cmd_run has no --auto-continue); the
+        // repaired-call cost is collected so cost_usd_actual stays honest.
+        on_stance_repair: stance_tally_on
+            ? (member: string): boolean => _make_repair_confirm(false)(member, 'missing stance line')
+            : null,
+        on_stance_repair_result: (r: CouncilResponse): void => {
+            stance_repairs.push(r);
+        },
     });
     const persona_labels = build_persona_labels(advisor_plans, billable);
     const peer_review = _maybe_run_peer_review(
@@ -1941,6 +1951,7 @@ function cmd_run(
     if (chairman !== null && chairman.response !== null) {
         all_responses.push(chairman.response);
     }
+    all_responses.push(...stance_repairs);
     for (const r of all_responses) {
         if (r.error) {
             continue;
@@ -2068,6 +2079,20 @@ function _listEq(a: string[], b: string[]): boolean {
     return a.every((v, i) => v === b[i]);
 }
 
+
+/** Phase 3 repair transport (council 2026-07-12): auto-fire under
+ *  --auto-continue; one-line confirm otherwise (blank/EOF stdin = N). */
+function _make_repair_confirm(auto_continue: boolean): (member: string, reason: string) => boolean {
+    if (auto_continue) {
+        return () => true;
+    }
+    return (member: string, reason: string): boolean => {
+        _stdout(`\ndebate:repair ${member} — ${reason} — send one bounded repair re-prompt? [y/N]: `);
+        const answer = _readStdinLine();
+        return answer === 'y' || answer === 'yes';
+    };
+}
+
 function _make_debate_continue_prompt(opts: {
     auto_continue: boolean;
     stream?: ((s: string) => void) | null;
@@ -2263,6 +2288,31 @@ function cmd_debate(
         auto_continue: Boolean(_getattr(args, 'auto_continue', false)),
     });
 
+    // Phase 3: restate pass — CLI flag OR config key; default off.
+    const restate_on =
+        Boolean(_getattr(args, 'restate', false)) ||
+        (_isDict(ai_cfg) && _isDict(ai_cfg['restate']) && (ai_cfg['restate'] as Dict)['enabled'] === true);
+    const restate_responses: CouncilResponse[] = [];
+    const ask_for_divergence = (args.original_ask as string) || '';
+    const on_restate = (rs: CouncilResponse[]): void => {
+        restate_responses.push(...rs);
+        const blocks = rs
+            .filter((r) => !r.error && r.text.trim() !== '')
+            .map((r) => `### ${r.provider} - ${r.model}\n\n${r.text.trim()}`);
+        if (blocks.length > 0) {
+            _stdout(`\n## Restatements (pre-round-1)\n\n${blocks.join('\n\n')}\n`);
+        }
+        // Divergence flag BEFORE further spend: a restatement far from the
+        // stated ask is surfaced to the user (Jaccard over token sets).
+        if (ask_for_divergence.trim() !== '') {
+            for (const r of rs) {
+                if (!r.error && r.text.trim() !== '' && jaccardSimilarity(ask_for_divergence, r.text) < 0.1) {
+                    _stderr(`⚠️  restate divergence: ${r.provider} restated the ask with little overlap — verify framing before continuing.\n`);
+                }
+            }
+        }
+    };
+
     // Phase 3: debate gates (anti-conformity directive on round 2+). Read
     // defensively from the raw ai_council block — a malformed/absent
     // `debate_gates` reads as off, keeping the debate prompt byte-identical.
@@ -2282,6 +2332,9 @@ function cmd_debate(
             on_round_complete: _on_round_complete,
             on_continue,
             debate_gates: debate_gates_on,
+            on_repair: debate_gates_on ? _make_repair_confirm(Boolean(_getattr(args, 'auto_continue', false))) : null,
+            restate: restate_on,
+            on_restate: restate_on ? on_restate : null,
             advisor_plans,
             seed_round_1: seed,
         });
@@ -2299,7 +2352,7 @@ function cmd_debate(
     }
 
     let actual_total = 0.0;
-    for (const rnd of all_rounds) {
+    for (const rnd of [...all_rounds, restate_responses]) {
         for (const r of rnd) {
             if (r.error) {
                 continue;
@@ -2546,6 +2599,7 @@ interface Args {
     single: boolean;
     prose_synthesis: boolean | null;
     auto_continue: boolean;
+    restate?: boolean;
     continue_as_debate: string | null;
     // render / replay
     responses?: string | null;
@@ -2675,6 +2729,7 @@ function _specsFor(cmd: string): { positionals: string[]; opts: OptSpec[]; requi
                     { flag: '--confirm', takesValue: false, apply: (o) => (o.confirm = true) },
                     { flag: '--rounds', takesValue: true, isInt: true, apply: (o, v) => (o.rounds = v === null ? null : parseInt(v, 10)) },
                     { flag: '--auto-continue', takesValue: false, apply: (o) => (o.auto_continue = true) },
+                    { flag: '--restate', takesValue: false, apply: (o) => (o.restate = true) },
                     { flag: '--continue-as-debate', takesValue: true, apply: (o, v) => (o.continue_as_debate = v) },
                     { flag: '--invocation', takesValue: true, choices: ['agent', 'user_explicit'], apply: (o, v) => (o.invocation = v as string) },
                     { flag: '--proceed-anyway', takesValue: false, apply: (o) => (o.proceed_anyway = true) },