@event4u/agent-config 9.8.0 → 9.9.0

package/src/config/hook-latency-budget.json

@@ -0,0 +1,20 @@
+{
+    "_comment": "Pre-registered hook-latency budget (road-to-credible-install Phase 1). Committed BEFORE the first optimization landed, per the roadmap's pre-registration discipline: the numbers below are the acceptance bar the precompile + single-process work is measured against, not a post-hoc fit. Consumed by the bench harness (scripts/bench_hook_latency) and its CI gate. Every budget carries an owner and a review date per the Phase-6 budget-ownership lint.",
+    "schema_version": 1,
+    "registered_at": "2026-07-27",
+    "owner": "maintainer",
+    "review_by": "2027-07-27",
+    "hardware_reference": {
+        "ci": "GitHub-hosted ubuntu-latest runner (the numbers the gate enforces)",
+        "floor": "1 vCPU reference container (documented ceiling, not CI-enforced)"
+    },
+    "budgets_ms": {
+        "pre_tool_use": { "p95_ci": 150, "p95_1vcpu": 400 },
+        "any_hook_event": { "p95_ci": 250 }
+    },
+    "regression_gate": {
+        "max_regression_pct": 200,
+        "_comment": "Pathology net only — the ABSOLUTE budgets above are the binding gate for wall-clock. The original 20% window was falsified by measured GitHub-runner variance: two CI runs of IDENTICAL code measured p95 77-89 ms and 92-103 ms (+23% run-to-run, 2026-07-27, runs 30303438480 / round-2 tests.yml). Same rationale as the regression_pct 200 override on the evaluator timing budgets: a tight creep rule on shared-runner wall-clock flaps; sizes/counts keep tight windows, timings get absolute caps."
+    },
+    "honest_null_consequence": "If the budget is missed after precompile + single-process + lazy I/O, hooks ship default-off with an explicit opt-in flag and the measured numbers published under a 'known cost' heading. A resident-dispatcher daemon is NOT improvised as a rescue (council 2026-07-26)."
+}

package/src/install/agentSwitchDetection.ts

@@ -0,0 +1,90 @@
+/**
+ * agent-switch detection — passive wizard recommendation (S0.1 honest-null
+ * council verdict, 2026-07-28: PASSIVE ROW ONLY, never a proactive card).
+ *
+ * agent-switch (https://github.com/event4u-app/agent-switch,
+ * `@event4u/agent-switch` on npm) isolates multiple agent accounts into
+ * per-account profiles (`CLAUDE_CONFIG_DIR`) so switching accounts never
+ * requires a re-login. Unlike rtk, the install command is npm-global and
+ * identical on every OS — no per-OS command map, no name collision to
+ * disambiguate.
+ *
+ * Two independent installed-signals, either is sufficient:
+ *   - the `agent-switch` binary is resolvable on PATH (the documented
+ *     npm-global install), OR
+ *   - `~/.agent-switch/` exists — a user who installed it another way must
+ *     never be told to install it again.
+ *
+ * Version is only probed when the binary is on PATH (the directory-only
+ * signal carries no version information — reported as `null`). There is
+ * deliberately NO version-currency check and NO network call here — the
+ * wizard only ever answers "installed or not", never "up to date" (roadmap
+ * acceptance criterion: this module does not report on agent-switch's
+ * version currency).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveBinaryOnPath } from './rtkDetection.js';
+
+export const AGENT_SWITCH_REPO = 'event4u-app/agent-switch';
+export const AGENT_SWITCH_NPM = '@event4u/agent-switch';
+export const AGENT_SWITCH_INSTALL_COMMAND = 'npm install -g @event4u/agent-switch';
+
+export interface AgentSwitchDetection {
+    installed: boolean;
+    version: string | null;
+}
+
+export interface DetectAgentSwitchOptions {
+    /** Override the home directory (tests). */
+    home?: string;
+    /** Override PATH (tests). */
+    pathEnv?: string;
+    /** Override the version probe (tests). Receives the resolved binary path. */
+    probeVersion?: (bin: string) => string | null;
+}
+
+const PROBE_TIMEOUT_MS = 2000;
+
+/** First dotted-number token in `output`, or `null` when none is present. */
+export function parseVersionOutput(output: string): string | null {
+    const m = /(\d+\.\d+(?:\.\d+)?)/.exec(output);
+    return m?.[1] ?? null;
+}
+
+function defaultProbeVersion(bin: string): string | null {
+    try {
+        const res = spawnSync(bin, ['--version'], {
+            timeout: PROBE_TIMEOUT_MS,
+            encoding: 'utf-8',
+            windowsHide: true,
+        });
+        if (res.error !== undefined || res.signal !== null) return null;
+        return parseVersionOutput(`${res.stdout ?? ''}\n${res.stderr ?? ''}`);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Detect agent-switch installation. Never throws — every failure mode
+ * (spawn error, timeout, unparsable output) collapses to `version: null`.
+ */
+export function detectAgentSwitch(options: DetectAgentSwitchOptions = {}): AgentSwitchDetection {
+    const binPath = resolveBinaryOnPath('agent-switch', options.pathEnv);
+    if (binPath !== null) {
+        const probe = options.probeVersion ?? defaultProbeVersion;
+        let version: string | null;
+        try {
+            version = probe(binPath);
+        } catch {
+            version = null;
+        }
+        return { installed: true, version };
+    }
+    const home = options.home ?? homedir();
+    const dirInstalled = existsSync(join(home, '.agent-switch'));
+    return { installed: dirInstalled, version: null };
+}

package/src/install/agentSwitchProfile.ts

@@ -0,0 +1,131 @@
+/**
+ * Detect whether AC is currently running under an agent-switch (AS)
+ * profile (`road-to-reciprocal-ecosystem.md` Phase 2 — correctness
+ * work, not the Phase 1 promotion card).
+ *
+ * Pure and injectable: reads only the supplied environment map, no
+ * filesystem I/O. Detection is deliberately topology-free — it never
+ * needs to understand AS's on-disk share model (that lives in
+ * `sharedWriteCheck.ts`, which DOES touch disk via `lstat`).
+ *
+ * AS root resolution mirrors `agent-switch/src/profiles.ts:11`:
+ * `AGENT_SWITCH_HOME` env override, else `~/.agent-switch`. Profile
+ * config dirs live at `<ROOT>/<provider>/<name>/config` (profiles.ts
+ * :143-145). Provider env vars mirror `agent-switch/src/providers.ts`:
+ * claude → `CLAUDE_CONFIG_DIR`, codex → `CODEX_HOME`. `HOME`
+ * (antigravity's provider var) is deliberately NOT checked here — it
+ * is set on every process, so treating it as an AS signal would
+ * false-positive constantly; antigravity profile detection is left to
+ * a future, more specific probe.
+ */
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+
+export interface AgentSwitchProfile {
+    active: boolean;
+    provider: string | null;
+    profile: string | null;
+}
+
+const INACTIVE: AgentSwitchProfile = { active: false, provider: null, profile: null };
+
+/** Provider env vars checked, in priority order (claude wins on a tie). */
+const PROVIDER_ENV_VARS: readonly string[] = ['CLAUDE_CONFIG_DIR', 'CODEX_HOME'];
+
+interface AgentSwitchMatch {
+    /** The resolved AS root implied by the matching env var. */
+    root: string;
+    /** Path segments below `root` (e.g. `[provider, profile, 'config']`). */
+    afterRoot: string[];
+}
+
+/** Expand a leading `~` the way a shell would, for env values set programmatically. */
+function expandTilde(p: string): string {
+    if (p === '~') return homedir();
+    if (p.startsWith('~/') || (process.platform === 'win32' && p.startsWith('~\\'))) {
+        return path.join(homedir(), p.slice(2));
+    }
+    return p;
+}
+
+function normalize(p: string): string {
+    return path.resolve(expandTilde(p));
+}
+
+function nonEmpty(v: string | undefined): v is string {
+    return typeof v === 'string' && v.trim() !== '';
+}
+
+/**
+ * Find the first provider env var whose (normalized) value lies
+ * inside the AS root, and return the root + the path segments below
+ * it. Shared by `detectAgentSwitchProfile` and `resolveAgentSwitchRoot`
+ * so both stay in lockstep with a single matching rule.
+ */
+function resolveMatch(env: NodeJS.ProcessEnv): AgentSwitchMatch | null {
+    const overrideRaw = env['AGENT_SWITCH_HOME'];
+    const overrideRoot = nonEmpty(overrideRaw) ? normalize(overrideRaw) : null;
+
+    for (const varName of PROVIDER_ENV_VARS) {
+        const raw = env[varName];
+        if (!nonEmpty(raw)) continue;
+        const candidate = normalize(raw);
+
+        let root: string | null = null;
+        if (overrideRoot !== null) {
+            if (candidate === overrideRoot || candidate.startsWith(overrideRoot + path.sep)) {
+                root = overrideRoot;
+            }
+        } else {
+            const bareMarker = `${path.sep}.agent-switch`;
+            const nestedMarker = `${bareMarker}${path.sep}`;
+            if (candidate.endsWith(bareMarker)) {
+                root = candidate;
+            } else {
+                const idx = candidate.indexOf(nestedMarker);
+                if (idx !== -1) root = candidate.slice(0, idx + bareMarker.length);
+            }
+        }
+        if (root === null) continue;
+
+        const rest = candidate === root ? '' : candidate.slice(root.length + 1);
+        const afterRoot = rest === '' ? [] : rest.split(path.sep).filter((s) => s.length > 0);
+        return { root, afterRoot };
+    }
+    return null;
+}
+
+/**
+ * Detect the active AS profile (if any) from the current environment.
+ *
+ * - Not inside `.agent-switch` at all → `{ active: false, ... }`.
+ * - Inside the AS root, but the env var points AT the root itself
+ *   (no `<provider>/<profile>` segments below it) → treated as
+ *   inactive; an env var pointing at the bare root is not a profile
+ *   directory.
+ * - Inside the AS root with only one segment below it (a provider dir
+ *   with no profile name) → active, but unparseable (`provider`/
+ *   `profile` both `null`).
+ * - Inside the AS root with `<provider>/<profile>/...` below it →
+ *   active, with `provider`/`profile` parsed from the first two
+ *   segments.
+ */
+export function detectAgentSwitchProfile(env: NodeJS.ProcessEnv = process.env): AgentSwitchProfile {
+    const match = resolveMatch(env);
+    if (match === null) return INACTIVE;
+    if (match.afterRoot.length === 0) return INACTIVE;
+    if (match.afterRoot.length < 2) return { active: true, provider: null, profile: null };
+    // `length >= 2` guaranteed above — `??` only satisfies noUncheckedIndexedAccess.
+    return { active: true, provider: match.afterRoot[0] ?? null, profile: match.afterRoot[1] ?? null };
+}
+
+/**
+ * Resolve the AS root directory implied by the environment (the same
+ * matching rule `detectAgentSwitchProfile` uses), for callers that
+ * need a boundary to stop an upward filesystem walk at — see
+ * `sharedWriteCheck.ts`. Returns `null` when no provider env var
+ * resolves inside an AS tree.
+ */
+export function resolveAgentSwitchRoot(env: NodeJS.ProcessEnv = process.env): string | null {
+    return resolveMatch(env)?.root ?? null;
+}

package/src/install/atomic.ts

@@ -2,7 +2,7 @@
  * Atomic file writer — Phase A4 primitive.
  *
  * 1:1 port of the `tempfile.mkstemp` + `os.replace` pattern used across
- * `scripts/install.py` (see `_write_consumer_bridge_marker` ~line 3036).
+ * the retired Python installer's `_write_consumer_bridge_marker` (ADR-200).
  *
  * Contract:
  *   1. Open a sibling `.tmp.<rand>` file in the destination directory

package/src/install/detect.ts

@@ -26,7 +26,7 @@ import type { InstallTarget } from './types.js';
 /**
  * Settings-file name used as the strongest project-scope signal.
  *
- * Matches `SETTINGS_FILE` in `scripts/install.py`. Presence in `cwd`
+ * Matches `SETTINGS_FILE` in the retired Python installer (ADR-200). Presence in `cwd`
  * short-circuits scope detection to `'project'` without consulting
  * the manifest / AI-tool lists.
  */

package/src/install/rtkDetection.ts

@@ -0,0 +1,274 @@
+/**
+ * rtk (Rust Token Killer) detection — two-stage identity probe.
+ *
+ * rtk is a THIRD-PARTY Apache-2.0 tool (upstream: https://github.com/rtk-ai/rtk,
+ * not an event4u project). Its binary name collides with an unrelated crate —
+ * `reachingforthejack/rtk` (Rust Type Kit), which is also what the bare
+ * crates.io `rtk` crate resolves to. Upstream's INSTALL.md documents the
+ * collision and the discriminator: `rtk gain` renders the token-savings
+ * dashboard only on Rust Token Killer.
+ *
+ * Stage 1 — presence: an executable named `rtk` resolvable on PATH.
+ * Stage 2 — identity: run `rtk gain` (short timeout) and judge the OUTPUT
+ * SIGNATURE, not the exit code (upstream documents no exit-code contract for
+ * `rtk gain`, and `rtk --version` does not distinguish the two tools — both
+ * print `rtk <ver>`). The signature is the dashboard header "RTK Token
+ * Savings" (captured live from rtk 0.43.0, 2026-07-28).
+ *
+ * Four states, never a boolean — a broken RIGHT tool is not the WRONG tool:
+ *   { present: false }
+ *   { present: true, identity: 'token-killer', version }  — signature matched
+ *   { present: true, identity: 'unknown-rtk' }            — probe ran, output
+ *       clearly not Token Killer (e.g. unknown-subcommand / usage error)
+ *   { present: true, identity: 'unverified' }             — timeout, spawn
+ *       failure, crash, or ambiguous (empty) output
+ *
+ * Consumers: the wizard `detect-rtk` endpoint, the `rtk:detect` CLI readout,
+ * and the `rtk_wrap` PreToolUse hook (which gates on
+ * `identity === 'token-killer'` — never on bare presence). Contract:
+ * docs/contracts/rtk-detection.md.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join, dirname } from 'node:path';
+
+export const RTK_UPSTREAM_REPO = 'https://github.com/rtk-ai/rtk';
+
+export type RtkIdentity = 'token-killer' | 'unknown-rtk' | 'unverified';
+
+export interface RtkDetection {
+    /** An executable named `rtk` is resolvable on PATH. */
+    present: boolean;
+    /** Only set when present. */
+    identity?: RtkIdentity;
+    /** Only set when identity === 'token-killer' (from `rtk --version`). */
+    version?: string;
+    /** Resolved binary path (diagnostic; only set when present). */
+    binPath?: string;
+}
+
+/**
+ * Output signature of Rust Token Killer's `rtk gain` savings dashboard.
+ * Rust Type Kit has no `gain` subcommand and errors with a usage message
+ * that never contains this header.
+ */
+const TOKEN_KILLER_GAIN_SIGNATURE = /RTK Token Savings/;
+
+/** Probe timeout — `rtk gain` renders from a local DB (sub-second upstream). */
+const PROBE_TIMEOUT_MS = 3000;
+
+/** Resolve the first executable named `name` on the given PATH string. */
+export function resolveBinaryOnPath(name: string, pathEnv?: string): string | null {
+    const pathVar = pathEnv ?? process.env['PATH'] ?? '';
+    if (pathVar.length === 0) return null;
+    const suffixes = process.platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : [''];
+    for (const dir of pathVar.split(delimiter)) {
+        if (dir.length === 0) continue;
+        for (const suffix of suffixes) {
+            const candidate = join(dir, `${name}${suffix}`);
+            if (existsSync(candidate)) return candidate;
+        }
+    }
+    return null;
+}
+
+export interface ProbeResult {
+    /** Process completed (spawned and exited, regardless of exit code). */
+    completed: boolean;
+    stdout: string;
+    stderr: string;
+}
+
+type ProbeFn = (binPath: string) => ProbeResult;
+
+function runGainProbe(binPath: string): ProbeResult {
+    try {
+        const res = spawnSync(binPath, ['gain'], {
+            timeout: PROBE_TIMEOUT_MS,
+            encoding: 'utf-8',
+            windowsHide: true,
+        });
+        // spawn error or timeout/signal kill → not a completed probe.
+        if (res.error !== undefined || res.signal !== null) {
+            return { completed: false, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
+        }
+        return { completed: true, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
+    } catch {
+        return { completed: false, stdout: '', stderr: '' };
+    }
+}
+
+function readVersion(binPath: string): string | undefined {
+    try {
+        const res = spawnSync(binPath, ['--version'], {
+            timeout: PROBE_TIMEOUT_MS,
+            encoding: 'utf-8',
+            windowsHide: true,
+        });
+        const m = /^rtk\s+(\S+)/m.exec(res.stdout ?? '');
+        return m?.[1];
+    } catch {
+        return undefined;
+    }
+}
+
+/** Judge identity from a finished probe — output signature, never exit code. */
+export function classifyGainOutput(probe: ProbeResult): RtkIdentity {
+    if (!probe.completed) return 'unverified';
+    const combined = `${probe.stdout}\n${probe.stderr}`;
+    if (TOKEN_KILLER_GAIN_SIGNATURE.test(probe.stdout)) return 'token-killer';
+    // Probe ran and produced output that is clearly not the savings dashboard
+    // (Rust Type Kit answers `gain` with a usage/unknown-subcommand error).
+    if (combined.trim().length > 0) return 'unknown-rtk';
+    // Completed silently with no output — ambiguous, don't accuse the tool.
+    return 'unverified';
+}
+
+export interface DetectRtkOptions {
+    /** Override PATH (tests / isolated probes). */
+    pathEnv?: string;
+    /** Override the gain probe (tests). */
+    probe?: ProbeFn;
+    /** Override the version read (tests). */
+    versionReader?: (binPath: string) => string | undefined;
+}
+
+/**
+ * Two-stage rtk detection. Never throws; failure modes collapse into
+ * `unverified` (fail-open for diagnostics, fail-CLOSED for consumers that
+ * gate behavior — `rtk_wrap` activates only on `token-killer`).
+ */
+export function detectRtk(options: DetectRtkOptions = {}): RtkDetection {
+    const binPath = resolveBinaryOnPath('rtk', options.pathEnv);
+    if (binPath === null) return { present: false };
+    const probe = options.probe ?? runGainProbe;
+    const identity = classifyGainOutput(probe(binPath));
+    if (identity !== 'token-killer') return { present: true, identity, binPath };
+    const version = (options.versionReader ?? readVersion)(binPath);
+    return version === undefined
+        ? { present: true, identity, binPath }
+        : { present: true, identity, version, binPath };
+}
+
+/* ------------------------------------------------------------------ */
+/* Cached variant — for high-frequency callers (PreToolUse hook).      */
+/* ------------------------------------------------------------------ */
+
+interface IdentityCacheEntry {
+    binPath: string;
+    mtimeMs: number;
+    size: number;
+    identity: RtkIdentity;
+    version?: string;
+    checkedAt: string;
+}
+
+function cacheFile(): string {
+    return join(homedir(), '.event4u', 'agent-config', 'state', 'rtk-identity.json');
+}
+
+/**
+ * `detectRtk` with a user-global identity cache keyed on the resolved binary's
+ * path + mtime + size — the probe re-runs only when the binary changes. An
+ * `unverified` verdict is never cached (transient by definition). Any cache
+ * I/O error falls through to a live probe (fail-open).
+ */
+export function detectRtkCached(options: DetectRtkOptions = {}): RtkDetection {
+    const binPath = resolveBinaryOnPath('rtk', options.pathEnv);
+    if (binPath === null) return { present: false };
+
+    let stat: { mtimeMs: number; size: number } | null = null;
+    try {
+        const st = statSync(binPath);
+        stat = { mtimeMs: st.mtimeMs, size: st.size };
+    } catch {
+        stat = null;
+    }
+
+    const file = cacheFile();
+    if (stat !== null) {
+        try {
+            const cached = JSON.parse(readFileSync(file, 'utf-8')) as IdentityCacheEntry;
+            if (
+                cached.binPath === binPath &&
+                cached.mtimeMs === stat.mtimeMs &&
+                cached.size === stat.size
+            ) {
+                return cached.version === undefined
+                    ? { present: true, identity: cached.identity, binPath }
+                    : { present: true, identity: cached.identity, version: cached.version, binPath };
+            }
+        } catch {
+            /* no / stale / unreadable cache — fall through to a live probe */
+        }
+    }
+
+    const detection = detectRtk(options);
+    if (stat !== null && detection.identity !== undefined && detection.identity !== 'unverified') {
+        const entry: IdentityCacheEntry = {
+            binPath,
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+            identity: detection.identity,
+            checkedAt: new Date().toISOString(),
+        };
+        if (detection.version !== undefined) entry.version = detection.version;
+        try {
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, `${JSON.stringify(entry, null, 2)}\n`, 'utf-8');
+        } catch {
+            /* cache write is best-effort */
+        }
+    }
+    return detection;
+}
+
+/* ------------------------------------------------------------------ */
+/* Per-OS install commands — verified upstream paths only.             */
+/* ------------------------------------------------------------------ */
+
+export interface RtkInstallCommands {
+    /** The primary copy-and-run command for this platform. */
+    recommended: string;
+    /** Human-readable label for the recommended path. */
+    recommendedLabel: string;
+    /** Secondary/manual path (only where a packaged one may be unavailable). */
+    manual?: string;
+    manualLabel?: string;
+    /** Caveat the UI must surface next to the command. */
+    note?: string;
+}
+
+/**
+ * Per-OS install commands from verified upstream paths. NEVER emit a bare
+ * `cargo install rtk` — the crates.io `rtk` crate is the colliding Rust Type
+ * Kit, not Rust Token Killer.
+ */
+export function rtkInstallCommands(platform: NodeJS.Platform = process.platform): RtkInstallCommands {
+    switch (platform) {
+        case 'darwin':
+            return {
+                recommended: 'brew install rtk',
+                recommendedLabel: 'Homebrew (official homebrew-core formula)',
+            };
+        case 'win32':
+            return {
+                recommended: 'winget install rtk-ai.rtk',
+                recommendedLabel: 'Recommended (automated, winget)',
+                manual: `Download rtk-x86_64-pc-windows-msvc.zip from ${RTK_UPSTREAM_REPO}/releases and place rtk.exe on PATH`,
+                manualLabel: 'Manual (all Windows versions, incl. winget-less images)',
+                note:
+                    'ripgrep is a documented Windows runtime dependency: `winget install BurntSushi.ripgrep.MSVC`. ' +
+                    'The winget path is documented upstream (microsoft/winget-pkgs manifests) but has not been live-verified by agent-config — verify with `rtk gain` after install.',
+            };
+        default:
+            // linux + everything POSIX-ish: upstream's install.sh (errors out
+            // on unsupported platforms itself; installs to ~/.local/bin).
+            return {
+                recommended: `curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh`,
+                recommendedLabel: "Upstream install.sh (installs to ~/.local/bin)",
+                note: 'Ensure ~/.local/bin is on PATH.',
+            };
+    }
+}

package/src/install/rule_scope.ts

@@ -36,10 +36,16 @@ import { rule_in_scope } from '../scripts/condense.js';
  */
 export const COMPAT_ALWAYS_EXCLUDED: readonly string[] = ['source-of-truth.md'];
 
-/** Workspace/pack scope read from consumer settings. `null` axis = unset. */
+/**
+ * Workspace/pack/role scope read from consumer settings. `null` axis =
+ * unset. `roles` is optional (additive — road-to-lean-agent-init Phase 4,
+ * the subagent role-scoping axis) so pre-existing `RuleScope` literals
+ * without the field keep compiling unchanged.
+ */
 export interface RuleScope {
     readonly workspaces: readonly string[] | null;
     readonly packs: readonly string[] | null;
+    readonly roles?: readonly string[] | null;
 }
 
 export const LEGACY_ALL: RuleScope = { workspaces: null, packs: null };
@@ -66,6 +72,7 @@ export function ruleScopeFromSettings(settings: Record<string, unknown>): RuleSc
     return {
         workspaces: _list(p['rule_workspaces']),
         packs: _list(p['rule_packs']),
+        roles: _list(p['rule_roles']),
     };
 }
 
@@ -85,7 +92,7 @@ export function ruleFileArrives(sourcePath: string, scope: RuleScope): boolean {
     if (COMPAT_ALWAYS_EXCLUDED.includes(basename)) {
         return false;
     }
-    return rule_in_scope(sourcePath, scope.workspaces, scope.packs);
+    return rule_in_scope(sourcePath, scope.workspaces, scope.packs, scope.roles ?? null);
 }
 
 /**

package/src/install/types.ts

@@ -2,7 +2,7 @@
  * Core types for the unified TypeScript install engine (v4.0.0).
  *
  * Mirrors the on-disk schema used by the legacy Python installer
- * (`scripts/install.py`) so the v4 engine reads/writes the same
+ * (the retired Python installer, ADR-200) so the v4 engine reads/writes the same
  * `~/.event4u/agent-config/` tree and v2 manifest entries without a
  * migration step.
  *
@@ -10,7 +10,7 @@
  * apply, and conflict-resolution modules. Pure types, no runtime
  * dependencies.
  *
- * Reference: `scripts/install.py`
+ * Reference: the retired Python installer (ADR-200)
  *   - `_file_entry()` → {@link FileEntry}
  *   - `class ConflictPolicy` → {@link ConflictPolicy}
  *   - v2 manifest `files_by_tool` → {@link InstallPlan.filesByTool}

package/src/install/wizard-plan.ts

@@ -63,7 +63,7 @@ export const USER_SCOPE_PATHS: Readonly<Record<string, string>> = {
 
 /**
  * Universal Anthropic-shaped skill bundle deployed to markdown-skills
- * tools. Mirrors `_CLAUDE_SKILL_BUNDLE` in `scripts/install.py`.
+ * tools. Mirrors `_CLAUDE_SKILL_BUNDLE` in the retired Python installer (ADR-200).
  */
 const CLAUDE_SKILL_BUNDLE: ReadonlyArray<readonly [string, string]> = [
     ['dist/agent-src/rules',    'rules'],

package/src/install/wizardDismissals.ts

@@ -0,0 +1,60 @@
+/**
+ * Permanent wizard-recommendation dismissals, persisted at
+ * `~/.event4u/agent-config/wizard-dismissals.json`.
+ *
+ * A dismissed recommendation (e.g. `"agent-switch"`) never returns — there
+ * is deliberately NO un-dismiss function (S0.1 council verdict, 2026-07-28:
+ * a passive row the user closed once stays closed). The file lives in the
+ * user-global config root, not inside the installed package, so a
+ * dismissal survives package updates.
+ *
+ * `AGENT_CONFIG_WIZARD_DISMISSALS` overrides the path (tests only).
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve, dirname } from 'node:path';
+
+function wizardDismissalsPath(): string {
+    const override = process.env['AGENT_CONFIG_WIZARD_DISMISSALS'];
+    if (override !== undefined && override.length > 0) return override;
+    return resolve(homedir(), '.event4u', 'agent-config', 'wizard-dismissals.json');
+}
+
+interface DismissalsFile {
+    dismissed?: unknown;
+}
+
+/**
+ * Return the recorded dismissal ids, or `[]` when absent / unreadable.
+ * Best-effort: a missing or corrupted file behaves as "nothing dismissed
+ * yet" rather than throwing.
+ */
+export function readDismissedRecommendations(): readonly string[] {
+    try {
+        const raw = readFileSync(wizardDismissalsPath(), 'utf8');
+        const parsed = JSON.parse(raw) as DismissalsFile;
+        return Array.isArray(parsed.dismissed)
+            ? parsed.dismissed.filter((d): d is string => typeof d === 'string')
+            : [];
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Record `id` as permanently dismissed. Idempotent — a repeat call for an
+ * already-dismissed id is a no-op.
+ */
+export function dismissRecommendation(id: string): void {
+    try {
+        const existing = readDismissedRecommendations();
+        if (existing.includes(id)) return;
+        const path = wizardDismissalsPath();
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const record = { dismissed: [...existing, id] };
+        writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    } catch {
+        // Best-effort: a failed write just means the recommendation may
+        // resurface on the next load — never throw out of a dismiss action.
+    }
+}