@event4u/agent-config 14.10.0 → 14.12.0

package/src/scripts/hot_context_hook.ts

@@ -36,6 +36,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
 import { hardenedSpawnEnv } from './_lib/spawn_env.js';
+import { computeRereads } from './_lib/transcript_reads.js';
 import { redact_low_impact_entry } from './ai_council/redact_low_impact_entry.js';
 import { readHookStdin } from './hooks/hook_stdin.js';
 
@@ -57,6 +58,7 @@ const MAX_OPEN_VERIFICATIONS = 3;
 const THREAD_SNIPPET_CHARS = 200;
 const CHANGE_SNIPPET_CHARS = 120;
 const KEY_FACTS_CHARS = 600;
+const MAX_REREAD_LINES = 3; // advisory, not an inventory — see _reread_lines
 
 const VERIFICATION_RE = /\b(fail(ing|ed|ure)?|error|exit[= ][1-9]|red\b|broken)\b/i;
 
@@ -161,11 +163,55 @@ function _word_count(text: string): number {
     return text.split(/\s+/).filter((w) => w.length > 0).length;
 }
 
+// ---------------------------------------------------------------------
+// re-read advisory (road-to-role-scoped-spawn-profiles Phase 3 Steps 4-5)
+// ---------------------------------------------------------------------
+
+/**
+ * Files this leg read more than once, as advisory lines for the cache.
+ *
+ * Phase 3 Step 4 of `road-to-role-scoped-spawn-profiles` requires the
+ * suppression to ride THIS surface rather than arrive as a second artefact,
+ * and Step 5 requires it to stay advice: there is no refuse branch anywhere
+ * below, and there is no code path that returns a deny on a re-read condition.
+ * The output is three lines in a markdown cache; the next leg may ignore it.
+ *
+ * **Why the path is relativised, and why an outside path is dropped rather
+ * than shortened.** The privacy floor
+ * ({@link _redact_lines} → `redact_low_impact_entry`) drops any line carrying
+ * a project-rooted absolute path, so emitting `/Users/...` would produce a
+ * silently empty section — the feature would look implemented and do nothing.
+ * Relativising to the workspace root keeps the line inside the floor. A path
+ * OUTSIDE the root cannot be relativised without `../` escapes that re-reveal
+ * the layout, and it is another project's business in any case, so it is
+ * dropped entirely.
+ *
+ * Fail-silent: no transcript path, an unreadable one, or a malformed leg all
+ * yield `[]`. This is a cache, and a cache that throws is worse than a cache
+ * that is short.
+ */
+export function _reread_lines(transcriptPath: string | null, root: string): string[] {
+    if (!transcriptPath) return [];
+    const result = computeRereads([transcriptPath]);
+    const lines: string[] = [];
+    for (const f of result.files) {
+        if (lines.length >= MAX_REREAD_LINES) break;
+        const rel = path.relative(root, f.file_path);
+        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+        lines.push(`${rel} — read ${f.total_reads}x this leg (${f.duplicate_reads} re-read)`);
+    }
+    return lines;
+}
+
 // ---------------------------------------------------------------------
 // stop — deterministic write
 // ---------------------------------------------------------------------
 
-export function build_hot_context(root: string, now: Date = new Date()): string {
+export function build_hot_context(
+    root: string,
+    now: Date = new Date(),
+    transcriptPath: string | null = null,
+): string {
     const session = _latest_session_entries(_read_history(root));
 
     const userPrompts = session.filter((e) => e.t === 'user_prompt' && e.text);
@@ -188,20 +234,36 @@ export function build_hot_context(root: string, now: Date = new Date()): string
     );
     const lastStop = String(stops[stops.length - 1]?.text ?? '');
     const keyFacts = _redact_lines(lastStop ? [_snippet(lastStop, KEY_FACTS_CHARS)] : []);
+    const rereads = _redact_lines(_reread_lines(transcriptPath, root));
 
     const droppedTotal =
-        activeThreads.dropped + recentChanges.dropped + openVerifications.dropped + keyFacts.dropped;
+        activeThreads.dropped +
+        recentChanges.dropped +
+        openVerifications.dropped +
+        keyFacts.dropped +
+        rereads.dropped;
 
     // Assemble; trim lowest-priority sections first until under the word cap.
     // Priority (highest kept longest): Key Facts > Active Threads >
-    // Open Verifications > Recent Changes.
+    // Open Verifications > Recent Changes > Re-Read Advisory.
+    //
+    // The advisory sits LAST on purpose. It is the only section that is a
+    // suggestion rather than a record of what happened, so when the 400-word
+    // cap bites it is the one whose loss costs nothing.
     const sections: Array<{ title: string; items: string[] }> = [
         { title: 'Key Facts', items: keyFacts.kept },
         { title: 'Active Threads', items: activeThreads.kept },
         { title: 'Open Verifications', items: openVerifications.kept },
         { title: 'Recent Changes', items: recentChanges.kept },
+        { title: 'Re-Read Advisory', items: rereads.kept },
+    ];
+    const trimOrder = [
+        'Re-Read Advisory',
+        'Recent Changes',
+        'Open Verifications',
+        'Active Threads',
+        'Key Facts',
     ];
-    const trimOrder = ['Recent Changes', 'Open Verifications', 'Active Threads', 'Key Facts'];
 
     const render = (): string => {
         const lines: string[] = [
@@ -240,9 +302,9 @@ export function build_hot_context(root: string, now: Date = new Date()): string
     return text;
 }
 
-function _write_hot_context(root: string): void {
+function _write_hot_context(root: string, transcriptPath: string | null = null): void {
     const target = _hot_context_path(root);
-    const text = build_hot_context(root);
+    const text = build_hot_context(root, new Date(), transcriptPath);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     const tmp = `${target}.tmp-${process.pid}`;
     fs.writeFileSync(tmp, text, { encoding: 'utf-8' });
@@ -392,7 +454,12 @@ export function main(): number {
         // one rebuild and can never produce a worse cache than the older one it
         // replaces. It emits nothing — the restore side is unchanged.
         if (event === 'stop' || event === 'session_end' || event === 'pre_compact') {
-            _write_hot_context(root);
+            // Claude Code puts the leg's own transcript on the stop payload;
+            // the camelCase alias is defensive, matching how the subagent
+            // ledger reads `last_assistant_message`. Absent on other hosts,
+            // where the advisory is simply empty.
+            const tp = payload.transcript_path ?? payload.transcriptPath;
+            _write_hot_context(root, typeof tp === 'string' && tp.length > 0 ? tp : null);
         } else if (event === 'session_start') {
             const source = String(payload.source ?? '');
             const decision = restore_hot_context(root, source);

package/src/scripts/install.ts

@@ -74,6 +74,7 @@ import type * as YamlModule from 'yaml';
 import { build_merge_entries } from './_lib/json_pointers.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import * as installed_lock from './_lib/installed_lock.js';
+import * as mcp_bridge from './_lib/mcp_bridge.js';
 import * as scoped_projection from './_lib/scoped_projection.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
@@ -1115,6 +1116,18 @@ function ensure_claude_bridge(project_root: string, force: boolean): Record<stri
     return merge_json_file(target, bridge, force || healed.length > 0, '.claude/settings.json');
 }
 
+// `.mcp.json` registration + the skill-tier projection lever live in
+// `_lib/mcp_bridge.ts`; only the call sites are here (see that module's header
+// for why). Names are forwarded so the export surface is unchanged.
+const ensure_mcp_bridge = mcp_bridge.makeEnsureMcpBridge(merge_json_file);
+const _resolve_tier_b = mcp_bridge.resolveTierB;
+const _tier_b_advisory = mcp_bridge.tierBAdvisory;
+const _prune_tier_b_modules = (
+    dr: Record<string, DeployResult>,
+    tier_b: ReadonlySet<string>,
+): [number, Record<string, DeployResult>] =>
+    _prune_modules_by(dr, mcp_bridge.tierBPrunePredicate(tier_b));
+
 const CURSOR_DISPATCHER_BINDINGS: ReadonlyArray<readonly [string, string]> = [
     ['session_start', 'sessionStart'],
     ['session_end', 'sessionEnd'],
@@ -2472,7 +2485,7 @@ function _file_entry(p: string, kind: string, hash_content: boolean): Record<str
     };
 }
 
-type DeployResult = [number, number, string, string[]];
+type DeployResult = scoped_projection.DeployTuple;
 
 function _files_by_tool_from_deploy(
     deploy_results: Record<string, DeployResult>,
@@ -3397,91 +3410,10 @@ function _verify_deploy_targets(anchor: string, plan: ReadonlyArray<readonly [st
     return missing;
 }
 
-/**
- * Remove skills/commands matching `is_pruned` from a completed deploy.
- *
- * road-to-install-contract-stability Phase 2 Step 2 (generalized in
- * road-to-credible-install Phase 2 to back both the core-only lab prune and
- * the scoped-projection pack prune off the same mechanics). Skills are
- * pruned by whole directory (tier decided by the skill's `SKILL.md`
- * frontmatter); commands by file (own frontmatter). Rules / personas /
- * contexts / templates are core/shared and left intact. Returns
- * `[pruned_count, adjusted_results]` with the pruned paths removed from each
- * tool's `written_paths` so the manifest never records them.
- */
-function _prune_modules_by(
-    deploy_results: Record<string, DeployResult>,
-    is_pruned: (md_path: string) => boolean,
-): [number, Record<string, DeployResult>] {
-    let pruned = 0;
-    const adjusted: Record<string, DeployResult> = {};
-    for (const tool_id of Object.keys(deploy_results)) {
-        const [written, skipped, status, paths] = deploy_results[tool_id] as DeployResult;
-        const pruned_skill_dirs = new Set<string>();
-        for (const p of paths) {
-            const parts = p.split(path.sep);
-            if (parts.includes('skills')) {
-                const i = parts.indexOf('skills');
-                if (i + 1 < parts.length) {
-                    const skill_root = parts.slice(0, i + 2).join(path.sep);
-                    if (!pruned_skill_dirs.has(skill_root)) {
-                        const skillmd = path.join(skill_root, 'SKILL.md');
-                        if (pathExists(skillmd) && is_pruned(skillmd)) {
-                            pruned_skill_dirs.add(skill_root);
-                        }
-                    }
-                }
-            }
-        }
-        const keep: string[] = [];
-        const delete_files: string[] = [];
-        for (const p of paths) {
-            const parts = p.split(path.sep);
-            let is_target = false;
-            if (parts.includes('skills')) {
-                const i = parts.indexOf('skills');
-                if (i + 1 < parts.length && pruned_skill_dirs.has(parts.slice(0, i + 2).join(path.sep))) {
-                    is_target = true;
-                }
-            } else if (
-                parts.includes('commands') &&
-                path.extname(p) === '.md' &&
-                is_pruned(p)
-            ) {
-                is_target = true;
-            }
-            (is_target ? delete_files : keep).push(p);
-        }
-        for (const d of pruned_skill_dirs) {
-            fs.rmSync(d, { recursive: true, force: true });
-        }
-        for (const p of delete_files) {
-            if (p.split(path.sep).includes('commands') && pathExists(p)) {
-                try {
-                    fs.unlinkSync(p);
-                } catch {
-                    // OSError → swallow, mirroring the .py.
-                }
-            }
-        }
-        pruned += delete_files.length;
-        adjusted[tool_id] = [Math.max(0, written - delete_files.length), skipped, status, keep];
-    }
-    return [pruned, adjusted];
-}
-
-/**
- * Remove lab-tier skills/commands from a completed deploy (core-only).
- *
- * road-to-install-contract-stability Phase 2 Step 2. Thin wrapper over
- * `_prune_modules_by` — see that function for the mechanics.
- */
-function _prune_lab_modules(
-    deploy_results: Record<string, DeployResult>,
-    lab_ids: Set<string>,
-): [number, Record<string, DeployResult>] {
-    return _prune_modules_by(deploy_results, (p) => surface_tiers.is_lab_artefact(p, lab_ids));
-}
+// The prune mechanics moved WHOLE into `_lib/scoped_projection.ts` beside the
+// predicate they consume — a pure move, names forwarded, no behaviour change.
+const _prune_modules_by = scoped_projection.prune_modules_by;
+const _prune_lab_modules = scoped_projection.prune_lab_modules;
 
 // --- Scoped-projection prune (road-to-credible-install Phase 2) ----------
 //
@@ -3549,10 +3481,10 @@ function _resolve_global_settings_path(): string | null {
  */
 function _resolve_scoped_projection(
     package_root: string,
-): { mode: 'scoped' | 'legacy-all'; active_packs: string[] } {
+): { mode: mcp_bridge.ProjectionMode; active_packs: string[] } {
     const doc = _resolve_global_settings_doc() ?? _load_default_settings(package_root);
     const projection = _isPlainObject(doc['projection']) ? (doc['projection'] as Record<string, unknown>) : {};
-    const mode: 'scoped' | 'legacy-all' = projection['mode'] === 'scoped' ? 'scoped' : 'legacy-all';
+    const mode = mcp_bridge.projectionModeOf(projection['mode']);
     const runtime = _isPlainObject(doc['runtime']) ? (doc['runtime'] as Record<string, unknown>) : {};
     const active_packs_raw = runtime['active_packs'];
     const active_packs = Array.isArray(active_packs_raw)
@@ -3782,6 +3714,13 @@ function install_global(
     // here and restores the full tree — never a partial or crashed prune.
     try {
         const { mode, active_packs } = _resolve_scoped_projection(package_root);
+        if (mode === 'tiered') {
+            const outcome = mcp_bridge.applyTieredPrune(deploy_results, package_root, _prune_modules_by);
+            deploy_results = outcome.deployResults;
+            if (!state.QUIET && outcome.message !== null) {
+                (outcome.level === 'warn' ? warn : info)(outcome.message);
+            }
+        }
         if (mode === 'scoped') {
             const packs_registry = _load_packs_registry(package_root);
             const active_ids = _compute_active_pack_ids(packs_registry, active_packs);
@@ -5225,7 +5164,10 @@ function _main_project_install(
             ...ensure_augment_bridge(project_root, opts.force),
         ];
         if (_is_tool_enabled(tools, 'claude-code')) {
-            merged_keys_by_tool['claude-code'] = ensure_claude_bridge(project_root, opts.force);
+            merged_keys_by_tool['claude-code'] = [
+                ...ensure_claude_bridge(project_root, opts.force),
+                ...ensure_mcp_bridge(project_root, opts.force),
+            ];
         }
         if (_is_tool_enabled(tools, 'cursor')) {
             merged_keys_by_tool['cursor'] = ensure_cursor_bridge(project_root, opts.force);
@@ -5249,6 +5191,11 @@ function _main_project_install(
         if (_is_tool_enabled(tools, 'kiro')) ensure_kiro_bridge(project_root, opts.force);
     }
 
+    const tier_advisory = _tier_b_advisory(package_root);
+    if (tier_advisory !== null && !state.QUIET) {
+        info(tier_advisory);
+    }
+
     if (opts.augment_user_hooks) {
         (merged_keys_by_tool['augment'] ??= []).push(...ensure_augment_user_hooks(package_root, opts.force));
     }
@@ -5441,6 +5388,10 @@ export {
     GEMINI_DISPATCHER_BINDINGS,
     ensure_cursor_bridge,
     ensure_cline_bridge,
+    ensure_mcp_bridge,
+    _prune_tier_b_modules,
+    _resolve_tier_b,
+    _tier_b_advisory,
     ensure_windsurf_bridge,
     ensure_gemini_bridge,
     // road-to-credible-install Phase 2: exported for the scoped-projection