@event4u/agent-config 8.2.0 → 8.3.0

package/src/scripts/_cli/cmd_upgrade.ts

@@ -504,12 +504,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 +528,58 @@ 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);
 
+    // Migration prompt (single-surface model): hooks were wired into
+    // ~/.claude/settings.json by the `global` step above, so an installed
+    // plugin is now a duplicate surface. Surface the one-line removal —
+    // NEVER uninstall autonomously (the plugin is a user-owned surface).
+    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}`,
+        );
+    }
+
     // 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 +590,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/_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 };
+    });
+}

package/src/scripts/condense.ts

@@ -39,6 +39,7 @@ import {
     resolve_logical as _agent_src_resolve_logical,
     strip_source_prefix,
 } from './_lib/agent_src.js';
+import { build_claude_hook_matrix } from './_lib/claude_settings_hooks.js';
 import { project_settings_path, load_agent_settings } from './_lib/agent_settings.js';
 import { info, success, flush_summary, resolve_level } from './_lib/script_output.js';
 import {
@@ -1963,36 +1964,13 @@ export function generate_plugin_hooks(): number {
         return 0;
     }
 
-    // Python: `manifest = yaml.safe_load(...) or {}`.
-    let manifest = _yamlParse(_readText(manifest_path)) as Record<string, unknown> | null;
-    if (manifest === null || manifest === undefined) {
-        manifest = {};
-    }
-    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 nativeAliasesAll = (manifest['native_event_aliases'] ?? {}) as Record<string, unknown>;
-    const aliases = ((nativeAliasesAll['claude'] ?? {}) as Record<string, unknown>) || {};
-    // Reverse the native→agent-config map.
-    const ac_to_native: Record<string, string> = {};
-    for (const [native, ac] of Object.entries(aliases)) {
-        ac_to_native[String(ac)] = native;
-    }
-
+    // Single source of truth: the SAME matrix derivation the installer uses
+    // for the managed settings.json block (road-to-claude-code-single-surface
+    // Phase 4) — plugin hooks.json and settings hooks cannot drift by
+    // construction. Backstop: tests/install/claude_hook_matrix_parity.test.ts.
+    const matrix = build_claude_hook_matrix(manifest_path);
     const hooks: Record<string, unknown[]> = {};
-    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;
-        }
-        const command =
-            '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)}`;
+    for (const [native, command] of Object.entries(matrix)) {
         hooks[native] = [{ hooks: [{ type: 'command', command }] }];
     }
 

package/src/scripts/install

@@ -27,6 +27,9 @@
 #                     the comma-separated values are unioned.
 #   --list-tools      Print supported tool IDs with descriptions, then exit
 #   --yes, -y         Non-interactive mode: do not prompt (default for non-TTY)
+#   --no-ui           Unattended install: never launch the browser setup
+#                     wizard and skip the terminal tool picker (tools default
+#                     to all). Used by `agent-config upgrade`.
 #   --force           Overwrite existing bridge files
 #   --dry-run         Show what payload sync would do (does not run bridges)
 #   --verbose         Detailed payload sync output
@@ -95,12 +98,13 @@ MINIMAL=false
 VALIDATE_ONLY=false
 FLEET_CONFIG=""
 USER_TYPE=""
+NO_UI=false
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro all"
 
 show_help() {
-    sed -n '3,58p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,61p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -167,6 +171,7 @@ while [[ $# -gt 0 ]]; do
         --ai=*)          TOOLS="${TOOLS:+$TOOLS,}${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
         --list-tools)    LIST_TOOLS=true; shift ;;
         --yes|-y)        YES=true; shift ;;
+        --no-ui)         NO_UI=true; shift ;;
         --force)         FORCE=true; shift ;;
         --dry-run)       DRY_RUN=true; shift ;;
         --verbose)       VERBOSE=true; shift ;;
@@ -194,6 +199,15 @@ if $LIST_TOOLS; then
     exit 0
 fi
 
+# --no-ui = unattended install (the `agent-config upgrade` path). Export the
+# suppression env so every downstream stage (install.ts honors both the flag
+# and AGENT_CONFIG_NO_UI) skips the browser setup wizard — the wizard is an
+# onboarding surface whose foreground server used to block `upgrade` until
+# Ctrl-C.
+if $NO_UI; then
+    export AGENT_CONFIG_NO_UI=1
+fi
+
 # road-to-global-only-install § Phase 3.3 — consumer-floor gate.
 #
 # Consumer installs are global-only (ADR-020). Explicit --scope=project
@@ -282,8 +296,8 @@ prompt_tools() {
 # When an interactive global install will hand off to the browser wizard,
 # the wizard is the single tool-selection surface — skip the terminal
 # picker so it does not pre-empt (and, via TOOLS_EXPLICIT, suppress) the
-# GUI. Mirrors install.py::_wizard_should_launch minus the --no-ui flag,
-# which the bash orchestrator never receives (it errors on unknown args).
+# GUI. Mirrors install.py::_wizard_should_launch (the --no-ui flag is
+# handled here too — it suppresses both the wizard and the picker).
 # Headless paths (no TTY / CI / AGENT_CONFIG_NO_UI) still get the picker.
 wizard_will_handle_tools=false
 if $GLOBAL && [[ -t 0 && -t 1 && -z "${CI:-}" ]] \
@@ -291,8 +305,12 @@ if $GLOBAL && [[ -t 0 && -t 1 && -z "${CI:-}" ]] \
     wizard_will_handle_tools=true
 fi
 
+# --no-ui also skips the terminal picker: the flag means "fully unattended"
+# (its only caller today is `agent-config upgrade`, where a mid-upgrade
+# prompt reads as a hang). Tools fall through to the "all" default below —
+# the same effective selection the wizard-handoff path used.
 if ! $MINIMAL && ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS \
-   && [[ -t 0 && -t 1 ]] && ! $wizard_will_handle_tools; then
+   && [[ -t 0 && -t 1 ]] && ! $wizard_will_handle_tools && ! $NO_UI; then
     prompt_tools
     TOOLS_EXPLICIT=true
 fi
@@ -416,6 +434,7 @@ run_bridges() {
     [[ -n "$CUSTOM_PATH" ]] && args+=(--custom-path="$CUSTOM_PATH")
     $OFFLINE && args+=(--offline)
     $MINIMAL && args+=(--minimal)
+    $NO_UI && args+=(--no-ui)
     args+=(--tools="$TOOLS")
     "${runner[@]}" "${args[@]}"
 }

package/src/scripts/install.ts

@@ -78,6 +78,7 @@ import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
 import * as installed_tools from './_lib/installed_tools.js';
 import * as user_global_paths from './_lib/user_global_paths.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
+import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
 import { detect_module_roots } from './_lib/module_detection.js';
 import {
@@ -2914,6 +2915,35 @@ function _deploy_global_content(
         }
         _emit_progress({ type: 'reaped', tool: tool_id, count: reaped.length });
         results[tool_id] = [written_total, skipped_total, 'deployed', written_paths];
+
+        // Single-surface model (road-to-claude-code-single-surface): the
+        // deterministic hook matrix registers directly in the user-scope
+        // settings file — the marketplace plugin is no longer required for
+        // hooks. Failure here must not sink the content deploy (hooks can
+        // be re-wired via `agent-config refresh --global` / doctor).
+        if (tool_id === 'claude-code') {
+            try {
+                const manifest = path.join(package_root, 'src', 'scripts', 'hook_manifest.yaml');
+                const matrix = claude_settings_hooks.build_claude_hook_matrix(manifest);
+                const res = claude_settings_hooks.ensure_managed_hooks(
+                    path.join(anchor, 'settings.json'),
+                    matrix,
+                );
+                if (!state.QUIET) {
+                    if (res.changed) {
+                        success(
+                            `claude-code: managed hooks registered in ~/.claude/settings.json ` +
+                                `(${res.events.length} event(s))`,
+                        );
+                    } else {
+                        skip('claude-code: managed hooks already registered');
+                    }
+                }
+            } catch (e) {
+                warn(`claude-code: managed-hook registration failed — ${String(e)}`);
+                _emit_progress({ type: 'hooks_failed', tool: tool_id, error: String(e) });
+            }
+        }
     }
     return results;
 }

package/src/scripts/lint_glama_drift.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env tsx
+/**
+ * Guard against `internal/glama/README.md` drifting from the committed
+ * `internal/glama/build` / `internal/glama/run` scripts it documents.
+ *
+ * Extracts the single canonical command line each script actually runs
+ * (the last non-comment, non-`set -euo pipefail` line — `exec ` stripped)
+ * and asserts that literal string appears verbatim somewhere in the README.
+ * Catches the exact failure mode fixed in road-to-mcp-full-power.md Phase 1:
+ * the README described a Python/uv build long after the scripts moved to
+ * Node/tsx.
+ *
+ * Exit codes: 0 no drift, 1 one or more scripts' canonical command is not
+ * documented verbatim in the README.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const GLAMA_DIR = path.join(REPO, 'internal', 'glama');
+
+interface ScriptSpec {
+    file: string;
+    /** Strip this exact prefix from the extracted command line before comparing. */
+    stripPrefix?: string;
+}
+
+const SCRIPTS: readonly ScriptSpec[] = [
+    { file: 'build' },
+    { file: 'run', stripPrefix: 'exec ' },
+];
+
+function _canonicalCommand(scriptPath: string, stripPrefix?: string): string {
+    const lines = fs.readFileSync(scriptPath, 'utf8').split('\n');
+    const candidates = lines
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith('#') && l !== 'set -euo pipefail');
+    const last = candidates[candidates.length - 1] ?? '';
+    return stripPrefix && last.startsWith(stripPrefix) ? last.slice(stripPrefix.length) : last;
+}
+
+function main(): number {
+    const readmePath = path.join(GLAMA_DIR, 'README.md');
+    const readme = fs.readFileSync(readmePath, 'utf8');
+
+    let failed = false;
+    for (const spec of SCRIPTS) {
+        const scriptPath = path.join(GLAMA_DIR, spec.file);
+        const cmd = _canonicalCommand(scriptPath, spec.stripPrefix);
+        if (!cmd) {
+            console.error(`❌  internal/glama/${spec.file}: could not extract a canonical command line`);
+            failed = true;
+            continue;
+        }
+        if (!readme.includes(cmd)) {
+            console.error(
+                `❌  drift: internal/glama/${spec.file} runs \`${cmd}\` — not found verbatim in internal/glama/README.md`,
+            );
+            failed = true;
+        }
+    }
+
+    if (failed) {
+        console.error('\nUpdate internal/glama/README.md to match the committed build/run scripts.');
+        return 1;
+    }
+
+    process.stdout.write('✅  internal/glama/README.md matches build/run scripts — no drift.\n');
+    return 0;
+}
+
+process.exit(main());