@event4u/agent-config 8.2.0 → 8.4.0

package/src/scripts/_cli/cmd_uninstall.ts

@@ -55,6 +55,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -62,6 +63,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as fs_atomic from '../_lib/fs_atomic.js';
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as installed_tools from '../_lib/installed_tools.js';
+import { remove_managed_hooks } from '../_lib/claude_settings_hooks.js';
 import { resolve_project_root } from '../_lib/agent_settings.js';
 import { subtract_pointers } from '../_lib/json_pointers.js';
 import { PROJECT_BRIDGE_MARKERS, USER_SCOPE_PATHS } from '../install.js';
@@ -771,6 +773,26 @@ function _uninstall_global(opts: Options): number {
             removed_names.push(tool);
         }
     }
+    // Managed Claude hooks live in ~/.claude/settings.json (single-surface
+    // model) — remove exactly our entries, never user-owned ones.
+    if (tools.includes('claude-code')) {
+        const settings_path = path.join(os.homedir(), '.claude', 'settings.json');
+        if (opts.dry_run) {
+            _print(_stdout, `  · claude-code: would remove managed hooks from ${settings_path}`);
+        } else {
+            try {
+                const res = remove_managed_hooks(settings_path);
+                if (res.changed) {
+                    _print(
+                        _stdout,
+                        `  · claude-code: removed managed hooks (${res.events.join(', ')})`,
+                    );
+                }
+            } catch (e) {
+                _print(_stderr, `⚠️  claude-code: managed-hook removal skipped — ${String(e)}`);
+            }
+        }
+    }
     if (lock !== null && !opts.dry_run) {
         const remaining = (lock.tools ?? []).filter((t) => !tools.includes(t));
         const version = String((lock as unknown as AnyDict)['agent_config_version'] ?? '');

package/src/scripts/_cli/cmd_upgrade.ts

@@ -90,7 +90,7 @@ import * as installed_lock from '../_lib/installed_lock.js';
 import * as update_check from '../_lib/update_check.js';
 import * as cli_wrapper from '../_lib/cli_wrapper.js';
 import * as claude_plugin from '../_lib/claude_plugin.js';
-import { event4u_root } from '../_lib/user_global_paths.js';
+import { event4u_root, write_target } from '../_lib/user_global_paths.js';
 import { project_settings_path } from '../_lib/agent_settings.js';
 import { _is_source_repo } from './cmd_refresh.js';
 
@@ -407,10 +407,11 @@ function _refresh_claude_plugin(
 interface Args {
     check: boolean;
     dry_run: boolean;
+    converge: boolean;
 }
 
 const PROG = 'agent-config upgrade';
-const USAGE = `usage: ${PROG} [-h] [--check] [--dry-run]\n`;
+const USAGE = `usage: ${PROG} [-h] [--check] [--dry-run] [--converge]\n`;
 
 function _argError(msg: string): never {
     _stderr.write(USAGE);
@@ -419,7 +420,7 @@ function _argError(msg: string): never {
 }
 
 function _parse(argv: string[]): Args {
-    const args: Args = { check: false, dry_run: false };
+    const args: Args = { check: false, dry_run: false, converge: false };
     const positionals: string[] = [];
     let i = 0;
     while (i < argv.length) {
@@ -447,6 +448,14 @@ function _parse(argv: string[]): Args {
             i += 1;
             continue;
         }
+        if (flag === '--converge') {
+            if (inlineVal !== null) {
+                _argError(`argument --converge: ignored explicit argument '${inlineVal}'`);
+            }
+            args.converge = true;
+            i += 1;
+            continue;
+        }
         if (a.startsWith('-') && a !== '-') {
             _argError(`unrecognized arguments: ${a}`);
         }
@@ -504,12 +513,11 @@ export async function main(argv: string[] | null = null, options: MainOptions =
     }
 
     const target = `${PACKAGE_NAME}@latest`;
-    const steps: string[][] = [
-        ['npm', 'install', '-g', target],
-        // --no-ui: the setup wizard is an onboarding surface, not an upgrade
-        // step — its foreground server used to block the upgrade until Ctrl-C.
-        [_agent_config_bin(), 'global', '--no-ui'],
-    ];
+    const npm_cmd: string[] = ['npm', 'install', '-g', target];
+    // --no-ui: the setup wizard is an onboarding surface, not an upgrade
+    // step — its foreground server used to block the upgrade until Ctrl-C.
+    const global_cmd: string[] = [_agent_config_bin(), 'global', '--no-ui'];
+    const steps: string[][] = [npm_cmd, global_cmd];
 
     const project_root = options.project_root ?? process.cwd();
     const sync_targets = _settings_sync_targets(project_root);
@@ -529,23 +537,73 @@ export async function main(argv: string[] | null = null, options: MainOptions =
         return 0;
     }
 
-    for (const cmd of steps) {
+    // Step 1 — the new package version. Nothing after makes sense without
+    // it, so this is the only hard-abort step.
+    _print(out, '→ ' + npm_cmd.join(' '));
+    const npm_rc = runner(npm_cmd);
+    if (npm_rc !== 0) {
+        _print(
+            err,
+            `❌  agent-config upgrade: step failed (exit ${npm_rc}): ` + `${npm_cmd.join(' ')}`,
+        );
+        return 1;
+    }
+
+    // Steps 2..N — independent. A failing step no longer skips the rest:
+    // the 8.2.0 failure class (aborted `global` step silently skipping the
+    // plugin refresh + settings sync) is closed by running every remaining
+    // step and reporting per-step outcomes in the summary. A failed
+    // essential step (global deploy) still exits 1 — after the others ran.
+    const failed_essential: string[] = [];
+    for (const cmd of steps.slice(1)) {
         _print(out, '→ ' + cmd.join(' '));
         const rc = runner(cmd);
         if (rc !== 0) {
+            failed_essential.push(cmd.join(' '));
             _print(
                 err,
-                `❌  agent-config upgrade: step failed (exit ${rc}): ` + `${cmd.join(' ')}`,
+                `❌  agent-config upgrade: step failed (exit ${rc}): ${cmd.join(' ')} — ` +
+                    'continuing with the remaining steps.',
             );
-            return 1;
         }
     }
 
     // Refresh the OPTIONAL Claude Code plugin so its command surface tracks
-    // the upgrade (no-op when the plugin is not installed — the file
-    // projection is a full install on its own).
+    // the upgrade — gated on the plugin actually being installed (empty step
+    // list otherwise). Deprecation window of the single-surface model: once
+    // the plugin is retired this block disappears with it.
     _refresh_claude_plugin(plugin_steps, runner, out, err);
 
+    // Duplicate-surface convergence (road-to-install-path-convergence
+    // Phase 3). Consent model (council Q2, 2026-07-07):
+    //   --converge          → explicit consent for this run; persists
+    //                         install.auto_converge: true as standing consent.
+    //   standing key true   → auto-converge (the user opted in earlier).
+    //   no key + TTY        → converge asks ONE y/N when duplicates exist.
+    //   no key + non-TTY    → today's print-only prompt; NEVER a silent
+    //                         mutation of a user-owned surface.
+    {
+        const converge_mod = await import('./cmd_converge.js');
+        const consent = converge_mod.read_consent(write_target('agent-settings.yml'));
+        const tty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        if (args.converge || consent || tty) {
+            const rc = converge_mod.main(args.converge ? ['--yes'] : [], { out, err });
+            if (rc !== 0 && (args.converge || consent)) {
+                failed_essential.push('agent-config converge');
+            }
+        } else if (plugin_steps.length > 0) {
+            _print(
+                out,
+                'ℹ️  Claude Code marketplace plugin detected — deprecated surface. Hooks now ' +
+                    'live in ~/.claude/settings.json (wired by the global step above), so the ' +
+                    'plugin only duplicates skills/commands. Remove it with:\n' +
+                    '    claude plugin uninstall ' +
+                    `${claude_plugin.CLAUDE_PLUGIN_ID}@${claude_plugin.CLAUDE_MARKETPLACE_NAME}\n` +
+                    '    (or: agent-config converge)',
+            );
+        }
+    }
+
     // Bring existing settings files up to the NEW template (additive; the
     // subprocess resolves the freshly installed binary + template).
     _sync_settings_files(sync_targets, runner, out, err);
@@ -556,10 +614,37 @@ export async function main(argv: string[] | null = null, options: MainOptions =
     // (marker-guarded; foreign hooks are never touched).
     _maybe_refresh_git_hook(project_root, runner, out, err);
 
+    // Doctor runs LAST, every time, non-fatal: its duplicate-surface and
+    // hook-wiring findings ARE the upgrade summary's health section — a
+    // mixed state (stale plugin, missing hooks) is named in the same run
+    // instead of waiting for the user to think of running doctor.
+    const doctor_cmd = [_agent_config_bin(), 'doctor'];
+    _print(out, '→ ' + doctor_cmd.join(' '));
+    const doctor_rc = runner(doctor_cmd);
+    if (doctor_rc !== 0) {
+        _print(
+            err,
+            `⚠️  agent-config doctor reported findings (exit ${doctor_rc}) — ` +
+                'see the check output above for per-item fixes.',
+        );
+    }
+
+    if (failed_essential.length > 0) {
+        _print(
+            err,
+            `❌  agent-config upgrade finished with ${failed_essential.length} failed ` +
+                `step(s):\n` +
+                failed_essential.map((c) => `    · ${c}`).join('\n') +
+                '\n   Re-run `agent-config upgrade`, or run the failed step directly. ' +
+                '`agent-config doctor` names anything left in a mixed state.',
+        );
+        return 1;
+    }
+
     _print(
         out,
-        '✅  agent-config upgraded. Run `agent-config doctor` to verify ' +
-            'PATH + plugin parity.',
+        '✅  agent-config upgraded' +
+            (doctor_rc === 0 ? ' — doctor green.' : ' — review the doctor findings above.'),
     );
     return 0;
 }

package/src/scripts/_dispatch.bash

@@ -105,6 +105,11 @@ Tier 1 — power-user (release shape, audit, migration):
                              Lists missing, modified, and foreign files.
                              Exits 1 on drift, 2 on missing lockfile.
                              Flags: --json | --project=<path>
+  converge                   Consented cleanup of duplicate install surfaces
+                             (surface-matrix driven). Never touches
+                             user-authored files; persists standing consent
+                             (install.auto_converge) on first use.
+                             Flags: --dry-run | --yes
   explain                    Read-only decision-chain trace.
                              Usage: explain config | explain rule <name>
                                   | explain route "<text>"
@@ -959,6 +964,13 @@ cmd_doctor() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_doctor.ts" "$@"
 }
 
+# `agent-config converge` — consented duplicate-surface cleanup.
+# Exit codes: 0 converged/nothing-to-do/dry-run · 1 refused/failed · 2 usage.
+# See scripts/_cli/cmd_converge.ts.
+cmd_converge() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_converge.ts" "$@"
+}
+
 # `agent-config conformance` — consumer conformance contract
 # (road-to-flow-learnings Phase 0). Doctor --ci semantics plus the five
 # consumer checks (txlog tail, router pointers, dispatcher smoke,
@@ -1048,6 +1060,7 @@ main() {
     uninstall)               cmd_uninstall "$@" ;;
     prune)                   cmd_prune "$@" ;;
     doctor)                  cmd_doctor "$@" ;;
+    converge)                cmd_converge "$@" ;;
     conformance)             cmd_conformance "$@" ;;
     versions)                cmd_versions "$@" ;;
     explain)                 cmd_explain "$@" ;;

package/src/scripts/_lib/claude_settings_hooks.ts

@@ -0,0 +1,251 @@
+/**
+ * Managed Claude Code hook registration in settings.json.
+ *
+ * road-to-claude-code-single-surface Phase 1: the marketplace plugin used to
+ * be the only carrier of the deterministic hook matrix (hooks/hooks.json).
+ * This module registers the same matrix directly in a Claude Code settings
+ * file (`~/.claude/settings.json` for the global install) so the plugin is
+ * no longer required for hooks.
+ *
+ * Contract (parity findings: agents/settings/contexts/claude-code-hook-parity.md):
+ *
+ * - The hook schema is identical between plugin hooks.json and settings.json;
+ *   Claude Code fires all sources in parallel and dedupes identical command
+ *   strings — so a still-installed plugin never double-fires during the
+ *   migration window.
+ * - Managed entries are identified by the dispatch signature inside the
+ *   command string (MANAGED_SIGNATURE). No extra marker field is written —
+ *   content-derived identity keeps the entry byte-identical to the plugin's,
+ *   which is what makes the dedup guarantee hold.
+ * - User-owned entries (anything without the signature) are never touched,
+ *   reordered, or removed. Managed entries are replaced in place per event.
+ * - Writes are atomic (temp file + rename via atomicWriteFile) and guarded
+ *   by a sidecar lockfile so two concurrent installers cannot tear the file.
+ * - A settings file that exists but does not parse as JSON is NEVER
+ *   overwritten — the operation throws CorruptSettingsError and leaves the
+ *   file byte-identical (the user's file outranks our convenience).
+ *
+ * The hook matrix itself derives from src/scripts/hook_manifest.yaml via
+ * build_claude_hook_matrix() — the same single source generate_plugin_hooks()
+ * (condense.ts) uses for the plugin's hooks/hooks.json.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import * as YAML from 'yaml';
+
+import { atomicWriteFile } from '../../install/atomic.js';
+
+// Bundle note: a static import of the CJS `yaml` package requires the
+// createRequire banner in `build:install-bundle` (package.json) — without it
+// the esbuild ESM bundle throws `Dynamic require of "process" is not
+// supported` at module init. A bare lazy `require('yaml')` is NOT an
+// alternative: it is a ReferenceError under plain tsx/node ESM (CI).
+function _yaml_parse(text: string): unknown {
+    return YAML.parse(text);
+}
+
+/** Substring that identifies an entry as agent-config-managed. */
+export const MANAGED_SIGNATURE = 'dispatch:hook --platform claude';
+
+export class CorruptSettingsError extends Error {
+    constructor(file: string, cause: string) {
+        super(
+            `${file} exists but is not valid JSON (${cause}). ` +
+                'Refusing to overwrite a user-owned settings file — fix or remove it, then re-run.',
+        );
+        this.name = 'CorruptSettingsError';
+    }
+}
+
+export class SettingsLockError extends Error {
+    constructor(lockPath: string) {
+        super(
+            `settings lock ${lockPath} is held by another process. ` +
+                'Re-run when the concurrent install finishes (stale lock: delete the file).',
+        );
+        this.name = 'SettingsLockError';
+    }
+}
+
+interface HookCommand {
+    type: string;
+    command: string;
+    [k: string]: unknown;
+}
+
+interface HookGroup {
+    matcher?: string;
+    hooks: HookCommand[];
+    [k: string]: unknown;
+}
+
+/** native event name → full shell command, e.g. { SessionStart: "BIN=..." }. */
+export type ClaudeHookMatrix = Record<string, string>;
+
+/**
+ * Derive the Claude hook matrix from hook_manifest.yaml — the SAME source
+ * generate_plugin_hooks() uses, so settings-registered hooks and the plugin's
+ * hooks.json can never drift from each other.
+ */
+export function build_claude_hook_matrix(manifest_path: string): ClaudeHookMatrix {
+    const raw = fs.readFileSync(manifest_path, 'utf8');
+    const manifest = (_yaml_parse(raw) ?? {}) as Record<string, unknown>;
+    const hook_spec = (manifest['schema_version'] as unknown) ?? 1;
+    const platforms = (manifest['platforms'] ?? {}) as Record<string, unknown>;
+    const claude_events = ((platforms['claude'] ?? {}) as Record<string, unknown>) || {};
+    const aliasesAll = (manifest['native_event_aliases'] ?? {}) as Record<string, unknown>;
+    const aliases = ((aliasesAll['claude'] ?? {}) as Record<string, unknown>) || {};
+
+    const ac_to_native: Record<string, string> = {};
+    for (const [native, ac] of Object.entries(aliases)) {
+        ac_to_native[String(ac)] = native;
+    }
+
+    const matrix: ClaudeHookMatrix = {};
+    for (const [ac_event, concerns] of Object.entries(claude_events)) {
+        if (!concerns || (Array.isArray(concerns) && concerns.length === 0)) continue;
+        const native = ac_to_native[ac_event];
+        if (native === undefined) continue;
+        matrix[native] =
+            'BIN="$CLAUDE_PROJECT_DIR/agent-config"; [ -x "$BIN" ] || BIN=agent-config; ' +
+            `"$BIN" dispatch:hook --platform claude --event ${ac_event} ` +
+            `--native-event ${native} --project-dir "$CLAUDE_PROJECT_DIR" ` +
+            `--min-version ${String(hook_spec)}`;
+    }
+    return matrix;
+}
+
+function _is_managed_group(group: unknown): boolean {
+    if (typeof group !== 'object' || group === null || Array.isArray(group)) return false;
+    const hooks = (group as HookGroup).hooks;
+    if (!Array.isArray(hooks)) return false;
+    return hooks.some(
+        (h) =>
+            typeof h === 'object' &&
+            h !== null &&
+            typeof (h as HookCommand).command === 'string' &&
+            (h as HookCommand).command.includes(MANAGED_SIGNATURE),
+    );
+}
+
+function _read_settings(settings_path: string): Record<string, unknown> {
+    if (!fs.existsSync(settings_path)) return {};
+    const raw = fs.readFileSync(settings_path, 'utf8');
+    if (raw.trim() === '') return {};
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (e) {
+        throw new CorruptSettingsError(settings_path, (e as Error).message);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new CorruptSettingsError(settings_path, 'top level is not an object');
+    }
+    return parsed as Record<string, unknown>;
+}
+
+function _with_lock<T>(settings_path: string, fn: () => T): T {
+    const lockPath = settings_path + '.agent-config.lock';
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    let fd: number;
+    try {
+        fd = fs.openSync(lockPath, 'wx');
+    } catch {
+        throw new SettingsLockError(lockPath);
+    }
+    try {
+        return fn();
+    } finally {
+        fs.closeSync(fd);
+        fs.rmSync(lockPath, { force: true });
+    }
+}
+
+export interface EnsureResult {
+    /** true when the file content changed on disk. */
+    changed: boolean;
+    /** native events whose managed entry was added or replaced. */
+    events: string[];
+}
+
+/**
+ * Idempotently register the managed hook matrix in a Claude settings file.
+ * User entries are preserved untouched; managed entries are replaced in
+ * place; a second run with the same matrix produces zero diff.
+ */
+export function ensure_managed_hooks(
+    settings_path: string,
+    matrix: ClaudeHookMatrix,
+): EnsureResult {
+    return _with_lock(settings_path, () => {
+        const settings = _read_settings(settings_path);
+        const before = JSON.stringify(settings);
+
+        const hooks = ((settings['hooks'] ?? {}) as Record<string, unknown>) || {};
+        const touched: string[] = [];
+
+        for (const [native, command] of Object.entries(matrix)) {
+            const existing = Array.isArray(hooks[native]) ? (hooks[native] as unknown[]) : [];
+            const user_groups = existing.filter((g) => !_is_managed_group(g));
+            const managed_group: HookGroup = {
+                hooks: [{ type: 'command', command }],
+            };
+            const next = [...user_groups, managed_group];
+            if (JSON.stringify(next) !== JSON.stringify(existing)) touched.push(native);
+            hooks[native] = next;
+        }
+
+        settings['hooks'] = hooks;
+        const after = JSON.stringify(settings);
+        if (after === before) {
+            return { changed: false, events: [] };
+        }
+        atomicWriteFile(settings_path, JSON.stringify(settings, null, 2) + '\n');
+        return { changed: true, events: touched };
+    });
+}
+
+export interface RemoveResult {
+    changed: boolean;
+    /** native events a managed entry was removed from. */
+    events: string[];
+}
+
+/**
+ * Remove exactly the managed entries (dispatch-signature match) from a
+ * Claude settings file. User entries, other settings keys, and files
+ * without managed entries are left byte-identical. Missing file → no-op.
+ */
+export function remove_managed_hooks(settings_path: string): RemoveResult {
+    if (!fs.existsSync(settings_path)) return { changed: false, events: [] };
+    return _with_lock(settings_path, () => {
+        const settings = _read_settings(settings_path);
+        const hooks = settings['hooks'];
+        if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
+            return { changed: false, events: [] };
+        }
+
+        const hooksRec = hooks as Record<string, unknown>;
+        const touched: string[] = [];
+        for (const [native, groups] of Object.entries(hooksRec)) {
+            if (!Array.isArray(groups)) continue;
+            const kept = groups.filter((g) => !_is_managed_group(g));
+            if (kept.length !== groups.length) {
+                touched.push(native);
+                if (kept.length === 0) {
+                    delete hooksRec[native];
+                } else {
+                    hooksRec[native] = kept;
+                }
+            }
+        }
+        if (touched.length === 0) return { changed: false, events: [] };
+        if (Object.keys(hooksRec).length === 0) {
+            delete settings['hooks'];
+        }
+        atomicWriteFile(settings_path, JSON.stringify(settings, null, 2) + '\n');
+        return { changed: true, events: touched };
+    });
+}