@event4u/agent-config 8.4.0 → 8.5.0

package/src/install/txlog.ts

@@ -0,0 +1,161 @@
+/**
+ * Transaction log — Phase A4 (council Finding #18).
+ *
+ * Append-only JSONL at `getLogPath()` (`~/.event4u/agent-config/install-log.jsonl`).
+ * Each successful atomic write appends one entry; recovery on crash is
+ * `tail -n` + reverse-apply. No PID lockfile (per Phase-A4 decision 8).
+ *
+ * Rotation: 10 MB OR 30 days, whichever first. Rotated copies move to
+ * `install-log.<ISO>.jsonl.gz` siblings; recovery never scans them.
+ *
+ * Recovery cap: at most the **last 500 entries** of the active log are
+ * scanned. Older incomplete tails are treated as abandoned and surfaced
+ * to the wizard as "previous run aborted; ignoring".
+ */
+
+import { createGzip } from 'node:zlib';
+import { createReadStream, createWriteStream, existsSync, readFileSync, renameSync, statSync, unlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+
+import { atomicAppendLine } from './atomic.js';
+
+/** Rotate the active log when it reaches this size (council Finding #18). */
+export const ROTATION_MAX_BYTES = 10 * 1024 * 1024;
+
+/** Rotate the active log when its first entry is older than this (ms). */
+export const ROTATION_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Recovery scans at most the last N entries of the active log. */
+export const RECOVERY_DEPTH_CAP = 500;
+
+/** Per-event shape written as one JSONL line. */
+export interface TxLogEntry {
+    /** ISO-8601 UTC timestamp of the event. */
+    readonly ts: string;
+    /** Event kind \u2014 `write` is the only success path; `abort` flags client disconnect. */
+    readonly kind: 'write' | 'skip' | 'abort' | 'rollback';
+    /** Absolute target path the entry refers to. */
+    readonly path: string;
+    /** SHA-256 of the bytes written (null for skip/abort/rollback). */
+    readonly sha256: string | null;
+    /** Optional free-form note (e.g. abort reason). */
+    readonly note?: string;
+}
+
+/** Append one entry to the active log, rotating first if thresholds tripped. */
+export function appendTxLog(logPath: string, entry: TxLogEntry): void {
+    if (shouldRotate(logPath)) {
+        rotateLogSync(logPath);
+    }
+    atomicAppendLine(logPath, JSON.stringify(entry));
+}
+
+/**
+ * Read at most the last {@link RECOVERY_DEPTH_CAP} entries from the active log.
+ *
+ * Returns entries in chronological order (oldest of the tail first).
+ * Malformed lines are dropped silently \u2014 partial-write tails should not
+ * crash recovery.
+ */
+export function readRecentEntries(logPath: string): readonly TxLogEntry[] {
+    if (!existsSync(logPath)) {
+        return [];
+    }
+    const raw = readFileSync(logPath, 'utf8');
+    const lines = raw.split('\n').filter((l) => l.length > 0);
+    const tail = lines.slice(-RECOVERY_DEPTH_CAP);
+    const out: TxLogEntry[] = [];
+    for (const line of tail) {
+        const parsed = tryParseEntry(line);
+        if (parsed !== null) {
+            out.push(parsed);
+        }
+    }
+    return out;
+}
+
+/**
+ * True when the active log breaches one of the rotation thresholds.
+ *
+ * Size threshold trips on byte-count alone; age threshold reads the
+ * first line and compares its `ts` against `now`.
+ */
+export function shouldRotate(logPath: string, now: Date = new Date()): boolean {
+    if (!existsSync(logPath)) {
+        return false;
+    }
+    let size = 0;
+    try {
+        size = statSync(logPath).size;
+    } catch {
+        return false;
+    }
+    if (size >= ROTATION_MAX_BYTES) {
+        return true;
+    }
+    const firstTs = readFirstTimestamp(logPath);
+    if (firstTs === null) {
+        return false;
+    }
+    return now.getTime() - firstTs >= ROTATION_MAX_AGE_MS;
+}
+
+/**
+ * Rotate the active log to `install-log.<ISO>.jsonl.gz` and remove the original.
+ *
+ * Sync wrapper around the async gzip pipeline so callers stay sequential.
+ * `appendTxLog` blocks on this \u2014 acceptable: rotations are rare (10 MB
+ * or 30 days) and the gzip is fire-and-forget afterwards.
+ */
+export function rotateLogSync(logPath: string): void {
+    if (!existsSync(logPath)) {
+        return;
+    }
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const rotated = logPath.replace(/\.jsonl$/, `.${stamp}.jsonl`);
+    renameSync(logPath, rotated);
+    // Best-effort gzip in the background; failure is non-fatal because
+    // the rotated `.jsonl` is already a valid recovery artefact.
+    void gzipInPlace(rotated).catch(() => {});
+}
+
+async function gzipInPlace(source: string): Promise<void> {
+    const target = `${source}.gz`;
+    await pipeline(createReadStream(source), createGzip(), createWriteStream(target));
+    try {
+        unlinkSync(source);
+    } catch {
+        /* swallow \u2014 gzip succeeded, leak is acceptable */
+    }
+}
+
+function readFirstTimestamp(logPath: string): number | null {
+    try {
+        const raw = readFileSync(logPath, 'utf8');
+        const firstLine = raw.split('\n', 1)[0] ?? '';
+        const parsed = tryParseEntry(firstLine);
+        if (parsed === null) return null;
+        const t = Date.parse(parsed.ts);
+        return Number.isFinite(t) ? t : null;
+    } catch {
+        return null;
+    }
+}
+
+function tryParseEntry(line: string): TxLogEntry | null {
+    try {
+        const obj = JSON.parse(line) as Partial<TxLogEntry>;
+        if (typeof obj.ts !== 'string' || typeof obj.kind !== 'string' || typeof obj.path !== 'string') {
+            return null;
+        }
+        return obj as TxLogEntry;
+    } catch {
+        return null;
+    }
+}
+
+/** Resolve the directory holding `logPath` \u2014 helper for callers (apply.ts). */
+export function txLogDir(logPath: string): string {
+    return dirname(logPath);
+}

package/src/install/types.ts

@@ -0,0 +1,175 @@
+/**
+ * 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
+ * `~/.event4u/agent-config/` tree and v2 manifest entries without a
+ * migration step.
+ *
+ * Phase A1 — foundation. Sub-types referenced by `detect`, `plan`,
+ * apply, and conflict-resolution modules. Pure types, no runtime
+ * dependencies.
+ *
+ * Reference: `scripts/install.py`
+ *   - `_file_entry()` → {@link FileEntry}
+ *   - `class ConflictPolicy` → {@link ConflictPolicy}
+ *   - v2 manifest `files_by_tool` → {@link InstallPlan.filesByTool}
+ */
+
+/**
+ * Where the install lands.
+ *
+ * - `global`  — `~/.event4u/agent-config/` (user-scope, shared across projects).
+ * - `project` — the current project root (`.augment/`, `.claude/`, bridges).
+ *
+ * The Python script uses the `scope` string ("global" | "project") for the
+ * same distinction; this enum is the TS-side equivalent.
+ */
+export type InstallTarget = 'global' | 'project';
+
+/**
+ * Kind of file recorded in a v2 `files[]` manifest entry.
+ *
+ * Matches the literal string values produced by `_file_entry()` in the
+ * Python installer so a v3 manifest round-trips through the v4 engine
+ * without rewriting on-disk records.
+ *
+ * - `deployed` — content we own bytes-for-bytes (hash recorded).
+ * - `marker`   — content we own at a known marker path (hash recorded).
+ * - `bridge`   — pointer to a foreign tool's config (no hash; we do not own bytes).
+ */
+export type FileKind = 'deployed' | 'marker' | 'bridge';
+
+/**
+ * One file the install plan will touch.
+ *
+ * Mirrors the dict produced by `_file_entry(path, kind, hash_content=...)`
+ * in `scripts/install.py:2744`. `sha256` is `null` for bridges (we do
+ * not own the bytes) and a hex digest for deployed/marker files.
+ *
+ * `path` is the absolute target path on disk — the v2 manifest is
+ * path-only at the wire level because user-scope files are not under
+ * `project_root`.
+ */
+export interface FileEntry {
+    /** Absolute target path on disk. */
+    readonly path: string;
+    /** What kind of file this is — drives hash and conflict policy. */
+    readonly kind: FileKind;
+    /** SHA-256 hex digest, or `null` for bridges. */
+    readonly sha256: string | null;
+}
+
+/**
+ * How to resolve a file collision.
+ *
+ * Per Phase A5 of the unified-setup roadmap: three modes only.
+ *
+ * - `skip`           — leave the existing file untouched (default safe behaviour).
+ * - `overwrite`      — replace the existing file with the planned content.
+ * - `surface-to-ui`  — defer to the wizard's conflict screen (Phase B3).
+ *
+ * The CLI `--force-overwrite` flag is the headless mapping for `overwrite`.
+ */
+export type ConflictStrategy = 'skip' | 'overwrite' | 'surface-to-ui';
+
+/**
+ * Per-install conflict resolution policy.
+ *
+ * 1:1 mirror of `class ConflictPolicy` in `scripts/install.py:169`.
+ *
+ * - `force`         — true when `--force-overwrite` was passed OR the
+ *                     `AGENT_CONFIG_ALLOW_OVERWRITE=1` env var is set.
+ * - `interactive`   — true when both stdin and stdout are TTYs.
+ * - `knownPaths`    — absolute paths the manifest already records as ours.
+ *                     A target at a known path is not a foreign collision.
+ * - `knownPointers` — `(fileLabel, jsonPointer)` pairs we previously
+ *                     merged into shared JSON files; anything else found
+ *                     in a shared JSON is a foreign merge collision.
+ * - `defaultStrategy` — fallback when no UI is available.
+ */
+export interface ConflictPolicy {
+    readonly force: boolean;
+    readonly interactive: boolean;
+    readonly knownPaths: ReadonlySet<string>;
+    readonly knownPointers: ReadonlySet<string>;
+    readonly defaultStrategy: ConflictStrategy;
+}
+
+/**
+ * The declarative install plan.
+ *
+ * Built once by the planner; the applier never recomputes paths from
+ * the plan. Empty plans render the wizard's "nothing to do" screen.
+ *
+ * `filesByTool` matches the v2 manifest's `{tool_id: [files[]]}` shape
+ * produced by `_files_by_tool_from_deploy` / `_files_by_tool_from_bridges`
+ * in the Python installer.
+ *
+ * `mergedKeysByTool` records JSON deep-merge pointers (Phase A5) so the
+ * conflict policy can distinguish ours-vs-foreign on later runs.
+ */
+export interface InstallPlan {
+    /** Plan schema version — bump on breaking shape change. */
+    readonly version: 2;
+    /** Where this plan lands (global vs project scope). */
+    readonly target: InstallTarget;
+    /** Absolute root for all relative paths in this plan. */
+    readonly root: string;
+    /** Per-tool file inventory; empty list means "nothing to write for this tool". */
+    readonly filesByTool: Readonly<Record<string, ReadonlyArray<FileEntry>>>;
+    /** Per-tool JSON-pointer inventory for deep-merged files (Phase A5). */
+    readonly mergedKeysByTool: Readonly<Record<string, ReadonlyArray<{ file: string; pointer: string }>>>;
+    /** Conflict policy active for this plan. */
+    readonly policy: ConflictPolicy;
+}
+
+/**
+ * One foreign collision discovered at plan time.
+ *
+ * Phase B3 — surfaced by the `/api/v1/install/plan` route so the wizard's
+ * conflict screen can render single-pick / batch-resolution UI **before**
+ * the apply phase opens the transaction log. A `ConflictEntry` means the
+ * target exists, its bytes do not match the planned SHA, it is not in
+ * `policy.knownPaths`, and `policy.force` is false — i.e. the policy
+ * would surface this file to the UI during apply.
+ *
+ * `mergeable` is `true` only for `.json` deployed files; the wizard
+ * shows the per-row `merge` button only on those. `existingSha256` is
+ * the on-disk hash so the UI can render byte-equality hints when the
+ * user toggles overwrite-vs-merge.
+ */
+export interface ConflictEntry {
+    readonly path: string;
+    readonly kind: FileKind;
+    readonly plannedSha256: string | null;
+    readonly existingSha256: string | null;
+    readonly mergeable: boolean;
+}
+
+/**
+ * Per-file resolution chosen by the wizard's conflict screen.
+ *
+ * - `skip`      — leave the existing file untouched.
+ * - `overwrite` — replace the existing file with planned bytes verbatim.
+ * - `merge`     — JSON deep-merge planned bytes into the existing file.
+ *
+ * `merge` is only valid for entries with `mergeable: true`; the apply
+ * layer falls back to `overwrite` if the caller picks `merge` on a
+ * non-JSON target rather than failing the entire plan.
+ */
+export type ConflictResolution = 'skip' | 'overwrite' | 'merge';
+
+/**
+ * Result of applying an {@link InstallPlan}.
+ *
+ * Surfaced to the wizard's progress bar (Phase B1) and recorded in the
+ * transaction log (Phase A4) so recovery can reverse-apply on crash.
+ */
+export interface ApplyResult {
+    readonly target: InstallTarget;
+    readonly written: ReadonlyArray<FileEntry>;
+    readonly skipped: ReadonlyArray<FileEntry>;
+    readonly conflicts: ReadonlyArray<FileEntry>;
+    readonly errors: ReadonlyArray<{ path: string; code: string; message: string }>;
+}

package/src/install/wizard-plan.ts

@@ -0,0 +1,216 @@
+/**
+ * Wizard-state → {@link PlanSource}[] translator — Phase B2.
+ *
+ * The Preact wizard collects high-level identifiers (tool IDs like
+ * `cursor` / `augment`, capability-pack IDs like `founder-mvp`) and is
+ * deliberately ignorant of filesystem layout. This module is the
+ * server-side bridge that expands those IDs into the low-level
+ * `(srcDir, destDir, toolId, kind)` tuples consumed by
+ * {@link buildInstallPlan}.
+ *
+ * Mirrors the canonical mapping tables in
+ * `scripts/install.py:2029-2222`:
+ *   - {@link USER_SCOPE_PATHS}     ← `USER_SCOPE_PATHS`
+ *   - {@link GLOBAL_DEPLOY_SOURCES} ← `_CLAUDE_SKILL_BUNDLE` + `GLOBAL_DEPLOY_SOURCES`
+ *
+ * Packs are intentionally NOT in this table: they are settings overlays
+ * (`packs/*.yml`), not file deployments. The 2PC settings write owns
+ * pack activation; the install plan only carries tool content.
+ */
+
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import type { ConflictPolicy, InstallPlan, InstallTarget } from './types.js';
+import { buildInstallPlan, type PlanSource } from './plan.js';
+
+/**
+ * Per-tool user-scope anchor directory, mirrored 1:1 from
+ * `scripts/install.py:USER_SCOPE_PATHS`. Values may use `~` for the
+ * user's home directory; {@link expandAnchor} resolves it server-side.
+ *
+ * Tools without a user-scope directory convention (e.g. `claude-desktop`
+ * which writes a single marker file, or `aider` which writes a single
+ * YAML file) are still listed so the wizard's bridge logic in Phase A6
+ * can resolve them via {@link expandAnchor} when needed.
+ */
+export const USER_SCOPE_PATHS: Readonly<Record<string, string>> = {
+    'claude-code':    '~/.claude/',
+    'claude-desktop': '~/Library/Application Support/Claude/',
+    cursor:           '~/.cursor/',
+    windsurf:         '~/.codeium/windsurf/',
+    cline:            '~/Documents/Cline/Rules/',
+    'gemini-cli':     '~/.gemini/',
+    copilot:          '~/.copilot/',
+    augment:          '~/.augment/',
+    aider:            '~/.aider.conf.yml',
+    codex:            '~/.codex/',
+    roocode:          '~/.roo/',
+    continue:         '~/.continue/',
+    kilocode:         '~/.kilocode/',
+    zed:              '~/.config/zed/',
+    jetbrains:        '~/.config/JetBrains/',
+    kiro:             '~/.kiro/',
+    qoder:            '~/.qoder/',
+    opencode:         '~/.opencode/',
+    trae:             '~/.trae/',
+    antigravity:      '~/.agents/',
+    codebuddy:        '~/.codebuddy/',
+    droid:            '~/.factory/',
+    warp:             '~/.warp/',
+};
+
+/**
+ * Universal Anthropic-shaped skill bundle deployed to markdown-skills
+ * tools. Mirrors `_CLAUDE_SKILL_BUNDLE` in `scripts/install.py`.
+ */
+const CLAUDE_SKILL_BUNDLE: ReadonlyArray<readonly [string, string]> = [
+    ['dist/agent-src/rules',    'rules'],
+    ['dist/agent-src/skills',   'skills'],
+    // Commands ship to ~/.claude/commands/ — native Claude Code slash-
+    // command surface. Verified empirically 2026-05-28: rich frontmatter
+    // (disable-model-invocation, custom fields) tolerated; nested
+    // subdirs route as `/<cluster>:<sub>`. Council session 2026-05-28
+    // converged on Option B (native slash-only) — see
+    // agents/runtime/council/responses/claude-code-distribution.json
+    // and scripts/install.py:_CLAUDE_SKILL_BUNDLE for the Python mirror.
+    ['dist/agent-src/commands', 'commands'],
+    ['dist/agent-src/personas', 'personas'],
+];
+
+/**
+ * Per-tool content deployment plan for `--global` installs. Each entry
+ * is a list of `(packageSrcRelative, destSubpath)` pairs.
+ *
+ * `packageSrcRelative` resolves against the agent-config package root;
+ * `destSubpath` is appended to `USER_SCOPE_PATHS[toolId]` (expanded).
+ *
+ * Mirrors `GLOBAL_DEPLOY_SOURCES` in `scripts/install.py:2178-2222`.
+ * Tools absent from this map have no deployable content in global scope
+ * — they either follow a marker-only convention (handled by bridges in
+ * Phase A6) or have no markdown convention at all.
+ */
+export const GLOBAL_DEPLOY_SOURCES: Readonly<Record<string, ReadonlyArray<readonly [string, string]>>> = {
+    'claude-code': CLAUDE_SKILL_BUNDLE,
+    augment: [
+        ['dist/agent-src/rules',     'rules'],
+        ['dist/agent-src/skills',    'skills'],
+        ['dist/agent-src/commands',  'commands'],
+        ['dist/agent-src/contexts',  'contexts'],
+        ['dist/agent-src/personas',  'personas'],
+        ['dist/agent-src/templates', 'templates'],
+    ],
+    cursor: [
+        ['dist/agent-src/rules',    'rules'],
+        ['dist/agent-src/commands', 'commands'],
+        ['dist/agent-src/personas', 'personas'],
+    ],
+    windsurf: [
+        ['dist/agent-src/rules', 'rules'],
+    ],
+    cline: [
+        ['dist/agent-src/rules', ''],
+    ],
+    'gemini-cli': CLAUDE_SKILL_BUNDLE,
+    codex:        CLAUDE_SKILL_BUNDLE,
+    continue:     CLAUDE_SKILL_BUNDLE,
+    roocode:      CLAUDE_SKILL_BUNDLE,
+    kilocode:     CLAUDE_SKILL_BUNDLE,
+    qoder:        CLAUDE_SKILL_BUNDLE,
+    opencode:     CLAUDE_SKILL_BUNDLE,
+    trae:         CLAUDE_SKILL_BUNDLE,
+    antigravity:  CLAUDE_SKILL_BUNDLE,
+    codebuddy:    CLAUDE_SKILL_BUNDLE,
+    droid:        CLAUDE_SKILL_BUNDLE,
+    warp:         CLAUDE_SKILL_BUNDLE,
+    kiro: [
+        ['dist/agent-src/rules',    'rules'],
+        ['dist/agent-src/skills',   'steering'],
+        ['dist/agent-src/personas', 'personas'],
+    ],
+};
+
+/**
+ * Resolve a `~/...` anchor against the user's home directory.
+ *
+ * Absolute paths (no `~` prefix) pass through unchanged. Empty string
+ * returns the home directory itself. Mirrors Python's `os.path.expanduser`.
+ */
+export function expandAnchor(anchor: string, home?: string): string {
+    const h = home ?? homedir();
+    if (anchor === '~') return h;
+    if (anchor.startsWith('~/')) return join(h, anchor.slice(2));
+    if (isAbsolute(anchor)) return anchor;
+    return resolve(anchor);
+}
+
+/** Inputs to {@link expandWizardSources}. */
+export interface WizardExpandInputs {
+    /** Stable tool IDs selected by the user in the wizard. */
+    readonly toolIds: ReadonlyArray<string>;
+    /** Absolute path to the agent-config package root (source of `dist/agent-src/`). */
+    readonly packageRoot: string;
+    /** Override for the user's home directory (tests only). */
+    readonly home?: string;
+}
+
+/**
+ * Expand the wizard's `toolIds` selection into a flat list of
+ * {@link PlanSource} tuples for the global install target.
+ *
+ * For each tool ID present in {@link GLOBAL_DEPLOY_SOURCES}, emit one
+ * `PlanSource` per `(packageSrcRelative, destSubpath)` pair, with:
+ *   - `srcDir`  = `packageRoot/packageSrcRelative`
+ *   - `destDir` = `expandAnchor(USER_SCOPE_PATHS[toolId])/destSubpath`
+ *   - `kind`    = `'deployed'` (we own these bytes)
+ *
+ * Tool IDs absent from {@link GLOBAL_DEPLOY_SOURCES} contribute zero
+ * sources — they are either marker-only (Phase A6 bridges handle them)
+ * or have no markdown convention. Unknown tool IDs (not in any map) are
+ * silently ignored — the detect/plan layer is the gatekeeper for
+ * enable/disable, not this expander.
+ */
+export function expandWizardSources(inputs: WizardExpandInputs): PlanSource[] {
+    const { toolIds, packageRoot, home } = inputs;
+    const out: PlanSource[] = [];
+    for (const toolId of toolIds) {
+        const deploy = GLOBAL_DEPLOY_SOURCES[toolId];
+        const anchor = USER_SCOPE_PATHS[toolId];
+        if (!deploy || !anchor) continue;
+        const destRoot = expandAnchor(anchor, home);
+        for (const [srcRel, destSub] of deploy) {
+            const srcDir = join(packageRoot, srcRel);
+            const destDir = destSub.length === 0 ? destRoot : join(destRoot, destSub);
+            out.push({ toolId, srcDir, destDir, kind: 'deployed' });
+        }
+    }
+    return out;
+}
+
+/** Inputs to {@link buildPlanFromWizard}. */
+export interface WizardPlanInputs extends WizardExpandInputs {
+    /** Install target. Wizard always emits `global` today; reserved for future project-scope. */
+    readonly target: InstallTarget;
+    /** Absolute install root anchor passed through to {@link InstallPlan.root}. */
+    readonly root: string;
+    /** Conflict policy active for this run. */
+    readonly policy: ConflictPolicy;
+}
+
+/**
+ * Build an {@link InstallPlan} directly from a wizard selection.
+ *
+ * Thin convenience over {@link expandWizardSources} +
+ * {@link buildInstallPlan}. Returns an empty-`filesByTool` plan when
+ * the selection contains zero deployable tool IDs — the wizard renders
+ * the "nothing to do" screen on that shape.
+ */
+export function buildPlanFromWizard(inputs: WizardPlanInputs): InstallPlan {
+    const sources = expandWizardSources(inputs);
+    return buildInstallPlan({
+        target: inputs.target,
+        root: inputs.root,
+        sources,
+        policy: inputs.policy,
+    });
+}

package/src/scripts/_cli/cmd_converge.ts

@@ -250,6 +250,37 @@ export interface MainOptions {
     err?: OutSink;
 }
 
+/**
+ * Live-session notice for reaped Claude Code plugin caches — or null when no
+ * reap touched `~/.claude/plugins/`.
+ *
+ * Removing an installed plugin's cache does NOT reach into Claude Code
+ * sessions that are already running: they registered the plugin's hooks at
+ * session start and keep firing them, so every subsequent event logs
+ * `Failed to run: Plugin directory does not exist: …/plugins/cache/… — run
+ * /plugin to reinstall` until the session restarts. Claude Code's own
+ * `/plugin to reinstall` hint would recreate exactly the duplicate surface
+ * converge just removed — the correct remedy is a restart, so converge says
+ * so explicitly (road-to-truth-and-reference-hygiene follow-up, 2026-07-08).
+ */
+export function live_session_notice(executed_reaps: readonly string[]): string | null {
+    const hit = executed_reaps.some((r) => r.startsWith('~/.claude/plugins/'));
+    if (!hit) {
+        return null;
+    }
+    return (
+        '⚠️  Live-session note: Claude Code sessions that were ALREADY RUNNING still\n' +
+        '    hold the removed plugin\'s hook registrations. Until you restart them,\n' +
+        '    every event logs a non-blocking\n' +
+        '      "Failed to run: Plugin directory does not exist: …/plugins/cache/…"\n' +
+        '    error. This is cosmetic for new sessions but means the affected LIVE\n' +
+        '    session\'s plugin-sourced hooks no longer run — restart Claude Code\n' +
+        '    sessions to clear it. Do NOT follow the error\'s "/plugin to reinstall"\n' +
+        '    hint: reinstalling recreates the duplicate surface converge just removed\n' +
+        '    (the ~/.claude/ file projection already carries content AND hooks).'
+    );
+}
+
 export function main(argv: string[] | null = null, opts: MainOptions = {}): number {
     let args: Args;
     try {
@@ -329,6 +360,7 @@ export function main(argv: string[] | null = null, opts: MainOptions = {}): numb
     // Perform the cleanup — matrix-declared actions ONLY.
     let failures = 0;
     const report: string[] = [];
+    const executed_reaps: string[] = [];
     for (const f of findings) {
         if (f.command) {
             _print(out, `→ ${f.command}`);
@@ -351,6 +383,7 @@ export function main(argv: string[] | null = null, opts: MainOptions = {}): numb
             try {
                 fs.rmSync(abs, { recursive: true, force: true });
                 report.push(`${f.tool}: reaped package-tagged orphan \`${reap}\``);
+                executed_reaps.push(reap);
                 _print(out, `→ reaped ${reap}`);
             } catch (e) {
                 failures += 1;
@@ -367,6 +400,11 @@ export function main(argv: string[] | null = null, opts: MainOptions = {}): numb
     if (report.length === 0) {
         _print(out, '  (no actions completed)');
     }
+    const notice = live_session_notice(executed_reaps);
+    if (notice !== null) {
+        _print(out);
+        _print(out, notice);
+    }
     _print(
         out,
         'Rollback hint: a removed Claude Code plugin can be reinstalled with\n' +