@fusengine/harness 0.1.48 → 0.1.50

package/dist/{handle-CCV0ycdr.mjs → handle-DzPjaPS-.mjs}

@@ -1,17 +1,19 @@
 import { a as parseEnvInt, i as splitTarget, r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
 import { r as projectLayout } from "./layout-C0jaaCQC.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
-import { B as detectFramework, C as resolveSkillPath, D as frameworkSolidGate, G as requiredArchSkill, H as detectModularArchitecture, I as docConsultedGate, L as evaluateApex, M as capVerbosity, N as detectCreationIntent, O as isExcludedJsPath, S as usesTailwindUtilities, T as readPluginMeta, U as detectProjectType$1, _ as scanPlugin, c as EXCLUDE_DIRS$1, d as buildApexTaskInjection, h as buildClaudeMdContext, k as isExcludedSwiftPath, l as PROJECT_INDICATORS, n as missingSeoElements, o as parseEnrichment, r as descFromText, s as parseEntry, t as isHtmlLike, w as findMarketplacePlugins, x as skillTriggerGate, y as parseField } from "./validate-ebDjIyOa.mjs";
-import { F as PLUGINS_DIR, L as countFrameworkCodeLines, R as countLines, n as FAIL_CLOSED, t as evaluate } from "./evaluate-qYC5xClb.mjs";
+import { A as detectCreationIntent, E as isExcludedSwiftPath, F as docConsultedGate, H as detectProjectType$1, I as evaluateApex, M as POST_AUTH_GATES, N as PRE_AUTH_GATES, S as usesTailwindUtilities, T as isExcludedJsPath, V as detectModularArchitecture, W as requiredArchSkill, _ as scanPlugin, c as EXCLUDE_DIRS$1, d as buildApexTaskInjection, h as buildClaudeMdContext, k as capVerbosity, l as PROJECT_INDICATORS, n as missingSeoElements, o as parseEnrichment, r as descFromText, s as parseEntry, t as isHtmlLike, w as frameworkSolidGate, x as skillTriggerGate, y as parseField, z as detectFramework } from "./validate-DCQ8dkdL.mjs";
+import { a as sanitizeSessionId, c as sessionsDir, d as countFrameworkCodeLines, f as countLines, i as loadSessionState, l as PLUGINS_DIR, n as fuseHarnessHome, o as saveSessionState, r as fusengineCache, t as claudeHome } from "./home-state-D0RLWP8J.mjs";
+import { n as FAIL_CLOSED, t as evaluate } from "./evaluate-CNAzgxnN.mjs";
 import { a as writeJsonFile, i as readJsonFile, r as hashText, t as atomicWrite } from "./json-io-DisYd2fb.mjs";
-import { a as sanitizeSessionId, c as sessionsDir, i as loadSessionState, n as fuseHarnessHome, o as saveSessionState, r as fusengineCache, t as claudeHome } from "./home-state-mKZxP4oZ.mjs";
 import { r as isDocConsulted } from "./doc-helpers-CWZegVdR.mjs";
+import { n as findMarketplacePlugins, r as readPluginMeta, t as resolveSkillPath } from "./skill-path-DhItkBzk.mjs";
 import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
 import { a as nowStamp, l as throttleMs, n as readRoots, o as readState, s as setStateField, t as addRoot } from "./registry-CymilZiZ.mjs";
 import { d as loadIndex, i as cacheLookupMeta, n as webfetchCacheWrite, o as cacheLookupSubstringMeta, t as mcpCacheWrite, u as extractText } from "./mcp-store-BkBDmuxN.mjs";
 import { t as loadRefs } from "./loader-AGz4nK7d.mjs";
-import { c as recordDoc, d as trivialCount, i as agentsFresh, l as recordRefRead, n as saveTrack, o as recordAgent, r as verifyTrack, s as recordBrainstormRequired, t as loadTrack, u as recordTrivialEdit } from "./store-ARx-GQSQ.mjs";
-import { d as readText, f as sleep, l as collectFiles, m as writeText, n as contextResponse, p as spawnCapture, r as denyResponse, s as systemMessage, t as blockResponse, u as pathExists } from "./claude-U1KTaRG4.mjs";
+import { c as recordDoc, d as recordTrivialEdit, f as trivialCount, i as agentsFresh, l as recordRefRead, n as saveTrack, o as recordAgent, p as apexAuthorizationGate, r as verifyTrack, s as recordBrainstormRequired, t as loadTrack, u as recordTarget } from "./store-QSSTO3lY.mjs";
+import { d as collectFiles, f as pathExists, g as writeText, h as spawnCapture, i as denyResponse, l as systemMessage, m as sleep, n as blockResponse, p as readText, r as contextResponse, s as informResponse, t as attachSystemMessage } from "./claude-BxC9semG.mjs";
+import { r as toHermesResponse } from "./hermes-DWXCRFZU.mjs";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -325,18 +327,81 @@ function designLifecycle(payload, cacheDir, cwd, stamp, now) {
 	}
 	return false;
 }
+/** Sidecar basename under the per-project state dir. */
+const SIDECAR = "inject-dedup.json";
+/** Load the `{ key -> epochMs }` map, or `{}` when missing/corrupt. */
+function loadMap(path) {
+	try {
+		if (!existsSync(path)) return {};
+		const data = JSON.parse(readFileSync(path, "utf8"));
+		return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+	} catch {
+		return {};
+	}
+}
+/** Keep only entries newer than `windowMs` before `now` (bounds sidecar size). */
+function prune(map, now, windowMs) {
+	const out = {};
+	for (const [k, t] of Object.entries(map)) if (typeof t === "number" && now - t < windowMs) out[k] = t;
+	return out;
+}
+/**
+* Cooldown gate. Returns `true` when `key` has NOT been recorded within the last
+* `windowMs` (the caller MAY emit — and the emission is recorded now), or `false`
+* when it was (the caller SHOULD suppress). The first call in a window wins;
+* subsequent identical keys are throttled until the window elapses.
+*
+* Fails open: if the sidecar is unwritable, the emission is allowed rather than
+* silently dropping context.
+* @param key - Stable identity of the block (e.g. a content hash, or `lesson:<id>`).
+* @param windowMs - Suppression window in ms.
+* @param opts - Optional clock + state-dir overrides (for tests).
+* @returns `true` to proceed/emit, `false` to suppress.
+*/
+function oncePerWindow(key, windowMs, opts = {}) {
+	const now = opts.now ?? Date.now();
+	const path = join(opts.dir ?? defaultStateDir(), SIDECAR);
+	const map = prune(loadMap(path), now, windowMs);
+	const last = map[key];
+	if (typeof last === "number" && now - last < windowMs) return false;
+	map[key] = now;
+	try {
+		atomicWrite(path, JSON.stringify(map));
+	} catch {}
+	return true;
+}
 //#endregion
 //#region src/runtime/inject-context.ts
 /**
+* Build the {@link oncePerWindow} key for the CLAUDE.md preamble gate. The
+* prompt hash keeps two distinct legitimate turns from colliding — even non-dev
+* prompts, whose block is prompt-independent (just CLAUDE.md) and would
+* otherwise hash-collide within the window — while the content hash still lets a
+* same-turn double-fire of an identical block be suppressed. Single source of
+* truth so the owner invariant test guards the real production key.
+* @param prompt - The raw user prompt.
+* @param ctx - The rendered CLAUDE.md (+ optional APEX) block.
+* @returns The namespaced dedup key.
+*/
+function claudeMdKey(prompt, ctx) {
+	return `claude-md:${hashText(prompt)}:${hashText(ctx)}`;
+}
+/**
 * UserPromptSubmit context injection: render the CLAUDE.md (+ optional APEX)
 * preamble as a Claude `additionalContext` response, or "" when nothing to emit.
+* Guarded by {@link oncePerWindow} via {@link claudeMdKey}: only a
+* near-simultaneous double-fire of the SAME turn (identical prompt AND identical
+* block, within {@link DEDUP_WINDOW_MS}) is suppressed. The invariant "CLAUDE.md
+* is emitted on EVERY message" is thus preserved.
 * @param prompt - The raw user prompt.
 * @param cwd - Project root (for project-type detection).
 * @returns The native hook stdout (possibly empty).
 */
 function promptSubmitContext(prompt, cwd) {
 	const ctx = buildClaudeMdContext(prompt, cwd);
-	return ctx ? contextResponse("UserPromptSubmit", ctx) : "";
+	if (!ctx) return "";
+	if (!oncePerWindow(claudeMdKey(prompt, ctx), 3e3)) return "";
+	return contextResponse("UserPromptSubmit", ctx);
 }
 /**
 * PreToolUse Task context injection: render the APEX sub-agent context as a
@@ -865,6 +930,87 @@ function subagentCacheContext(sessionIdRaw, home = homedir(), env = process.env,
 	return fresh.length ? contextResponse("SubagentStart", render(fresh)) : "";
 }
 //#endregion
+//#region src/runtime/lifecycle/agent-files.ts
+/**
+* Per-agent file attribution for SubagentStop. Parses a sub-agent's OWN
+* transcript (`agent_transcript_path` — the clean JSONL the Claude Code platform
+* writes for that specific sub-agent, added in CLI v2.0.42) to recover the exact
+* set of files it wrote via Write/Edit/MultiEdit/NotebookEdit. This lets the
+* sniper reminder attribute only the files THIS agent touched, instead of every
+* file changed in the whole session (which cross-attributes other teammates'
+* work — the bug this fixes). Per LESSON.md, the SubagentStop transcript is the
+* reliable anchor; sidechain PostToolUse hooks are not (issues #43612/#34692).
+*/
+/** Tools whose `input.file_path`/`notebook_path` names a file the agent authored. */
+const WRITE_TOOLS = /* @__PURE__ */ new Set([
+	"Write",
+	"Edit",
+	"MultiEdit",
+	"NotebookEdit"
+]);
+/**
+* Return the distinct list of file paths written by the sub-agent whose own
+* transcript is at `transcriptPath`, by scanning its Write/Edit/MultiEdit/
+* NotebookEdit `tool_use` blocks. Distinguishes "no writes" from "cannot read":
+*
+* - `null` — the path is absent, or the transcript is unreadable. The caller
+*   MUST fall back to the session-wide list (fail-open: never drop the sniper
+*   reminder just because a transcript could not be parsed — no regression vs.
+*   the pre-fix behavior).
+* - `string[]` (possibly empty) — the transcript was read; every write was
+*   collected. An empty array means this agent authored no files, so it should
+*   NOT be told to validate files other agents changed.
+*
+* @param transcriptPath - Absolute path to the sub-agent's own `.jsonl`
+*   transcript (SubagentStop payload field `agent_transcript_path`).
+* @returns Distinct written paths (order-preserving), or `null` when unreadable.
+*/
+function filesWrittenByAgent(transcriptPath) {
+	if (!transcriptPath) return null;
+	let text;
+	try {
+		text = readText(transcriptPath);
+	} catch {
+		return null;
+	}
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		let entry;
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		const content = entry.message?.content;
+		if (!Array.isArray(content)) continue;
+		for (const block of content) {
+			if (block?.type !== "tool_use" || !block.name || !WRITE_TOOLS.has(block.name)) continue;
+			const fp = block.input?.file_path ?? block.input?.notebook_path;
+			if (typeof fp === "string" && fp && !seen.has(fp)) {
+				seen.add(fp);
+				out.push(fp);
+			}
+		}
+	}
+	return out;
+}
+/**
+* Filter `sessionFiles` (from unified state `.changes.modifiedFiles`) down to the
+* ones this agent actually wrote. Matches on the exact recorded string first,
+* then tolerantly on `basename` so a relative-vs-absolute path drift between the
+* PostToolUse record and the transcript input never loses an owned file.
+* @param sessionFiles - Session-wide modified files.
+* @param written - Paths the agent wrote (from {@link filesWrittenByAgent}).
+* @returns The subset of `sessionFiles` attributable to this agent.
+*/
+function attributeFiles(sessionFiles, written) {
+	const exact = new Set(written);
+	const bases = new Set(written.map((f) => basename(f)));
+	return sessionFiles.filter((f) => exact.has(f) || bases.has(basename(f)));
+}
+//#endregion
 //#region src/runtime/lifecycle/agent-memory.ts
 /** `~/.claude/memory/agents` — agent completion history dir. */
 function memoryDir(home) {
@@ -901,17 +1047,19 @@ function trackAgentMemory(data, home = homedir(), now = Date.now()) {
 	if (SKIP_AGENTS.test(agentType)) return JSON.stringify({ message: `Agent ${agentType} completed` });
 	const state = loadSessionState(sessionId, home);
 	const changes = state.changes;
-	const count = changes?.cumulativeCodeFiles ?? 0;
-	if (count > 0) {
-		const files = (changes?.modifiedFiles ?? []).join(", ");
-		saveSessionState(sessionId, {
-			...state,
-			changes: {
-				...changes,
-				cumulativeCodeFiles: 0
-			}
-		}, home);
-		return contextResponse("SubagentStop", `SNIPER VALIDATION REQUIRED: Agent '${agentType}' modified ${count} code file(s): ${files}. Run sniper agent now.`);
+	if ((changes?.cumulativeCodeFiles ?? 0) > 0) {
+		const written = filesWrittenByAgent(typeof data.agent_transcript_path === "string" ? data.agent_transcript_path : void 0);
+		const owned = written === null ? changes?.modifiedFiles ?? [] : attributeFiles(changes?.modifiedFiles ?? [], written);
+		if (owned.length > 0) {
+			saveSessionState(sessionId, {
+				...state,
+				changes: {
+					...changes,
+					cumulativeCodeFiles: 0
+				}
+			}, home);
+			return contextResponse("SubagentStop", `SNIPER VALIDATION REQUIRED: Agent '${agentType}' modified ${owned.length} code file(s): ${owned.join(", ")}. Run sniper agent now.`);
+		}
 	}
 	return JSON.stringify({ message: `Agent ${agentType} completed (no code changes)` });
 }
@@ -1553,6 +1701,109 @@ function cartoSessionStart(cwd, now = Date.now()) {
 	return ctx ? contextResponse("SessionStart", ctx) : "";
 }
 //#endregion
+//#region src/runtime/lifecycle/aipilot/curate-lessons.ts
+/**
+* Mechanical, LLM-free curation of `MEMORY/LESSON.md` bullets (anti-obesity):
+* strict-dedup near-identical bullets (keep newest, `[TRIGGERS …]` preserved),
+* flag over-cap + stale (>90d, cited path gone) in a report. Only dedup writes.
+*/
+const CAP = 50;
+const STALE_DAYS = 90;
+const SIM_THRESHOLD = .8;
+const MIN_TOKENS = 4;
+const TRIG = /^\[TRIGGERS\s+.+\]$/;
+/** Epoch ms for a `[YYYY-MM-DD HH:MM]` stamp; `NaN` if absent or out of range. */
+function parseTs$1(line) {
+	const m = line.match(/\[(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2}))?/);
+	if (!m) return NaN;
+	const mo = +(m[2] ?? 0), d = +(m[3] ?? 0);
+	if (mo < 1 || mo > 12 || d < 1 || d > 31) return NaN;
+	return Date.UTC(+(m[1] ?? 0), mo - 1, d, +(m[4] ?? 0), +(m[5] ?? 0));
+}
+/** Content words (>=4 chars), timestamp & TRIGGERS marker stripped. */
+function tokenize(text) {
+	return new Set(text.toLowerCase().replace(/\[triggers[^\]]*\]/g, " ").replace(/\[\d{4}-\d{2}-\d{2}[^\]]*\]/g, " ").replace(/[^a-z0-9àâäéèêëîïôöùûüç/._-]+/gi, " ").split(/\s+/).filter((t) => t.length >= 4));
+}
+/** Jaccard overlap of two token sets (0 when both empty). */
+function jaccard(a, b) {
+	if (a.size === 0 && b.size === 0) return 0;
+	const inter = [...a].filter((t) => b.has(t)).length;
+	return inter / (a.size + b.size - inter);
+}
+/** Repo-relative cited paths (slash + extension) referenced in a block. */
+function citedPaths(text) {
+	const out = /* @__PURE__ */ new Set();
+	for (const m of text.matchAll(/`([^`]+)`/g)) if (m[1]) out.add(m[1]);
+	for (const m of text.matchAll(/[\w./@-]+\.\w{1,5}/g)) if (m[0]) out.add(m[0]);
+	return [...out].filter((p) => p.includes("/") && /\.\w{1,5}$/.test(p));
+}
+/** Split into a verbatim preamble and one Block per `- ` bullet. */
+function parse(content) {
+	const lines = content.split("\n");
+	const blocks = [];
+	let i = 0;
+	while (i < lines.length && !/^-\s/.test(lines[i] ?? "")) i++;
+	const preamble = lines.slice(0, i).join("\n");
+	for (; i < lines.length; i++) {
+		const l = lines[i] ?? "", last = blocks[blocks.length - 1];
+		if (/^-\s/.test(l)) blocks.push({
+			raw: [l],
+			ts: parseTs$1(l),
+			tokens: tokenize(l)
+		});
+		else if (l.trim() && last) last.raw.push(l);
+	}
+	return {
+		preamble,
+		blocks
+	};
+}
+/** Report lines for bullets older than STALE_DAYS whose only cited path is gone. */
+function staleReport(blocks, now, root) {
+	const cutoff = now - STALE_DAYS * 864e5;
+	return blocks.flatMap((b) => {
+		if (!(b.ts <= cutoff)) return [];
+		const paths = citedPaths(b.raw.join(" "));
+		if (paths.length === 0 || paths.some((p) => existsSync(join(root, p)))) return [];
+		return [`[STALE?] ${(b.raw[0] ?? "").slice(0, 90)} — chemin(s) disparu(s): ${paths.join(", ")}`];
+	});
+}
+/**
+* Strict-dedup LESSON.md bullets (keep newest, its `[TRIGGERS …]` line preserved —
+* or carried over from the dropped twin if the kept one lacks it) and report
+* cap/stale. `content` unchanged unless a dedup occurred. Returns content + report.
+*/
+function curateLessons(content, now, root = process.cwd()) {
+	const { preamble, blocks } = parse(content);
+	const kept = [];
+	const fused = [];
+	for (const b of blocks) {
+		const hit = b.tokens.size >= MIN_TOKENS ? kept.find((k) => k.tokens.size >= MIN_TOKENS && jaccard(k.tokens, b.tokens) >= SIM_THRESHOLD) : void 0;
+		if (!hit) {
+			kept.push(b);
+			continue;
+		}
+		const [win, drop] = b.ts > hit.ts || Number.isNaN(hit.ts) ? [b, hit] : [hit, b];
+		if (win !== hit) kept[kept.indexOf(hit)] = win;
+		if (!win.raw.some((l) => TRIG.test(l.trim()))) {
+			const t = drop.raw.find((l) => TRIG.test(l.trim()));
+			if (t) win.raw.push(t);
+		}
+		fused.push(`fusion: gardé ${(win.raw[0] ?? "").slice(0, 60)} · retiré ${(drop.raw[0] ?? "").slice(0, 60)}`);
+	}
+	const old = [...kept].sort((a, b) => a.ts - b.ts).slice(0, Math.max(0, kept.length - CAP));
+	const cap = old.length ? [`${kept.length} bullets (> ${CAP}) — plus anciens candidats à l'archivage:`, ...old.map((b) => `  ${(b.raw[0] ?? "").slice(0, 80)}`)] : [];
+	const report = [
+		...fused,
+		...cap,
+		...staleReport(blocks, now, root)
+	].join("\n");
+	return {
+		content: fused.length ? `${preamble}\n${kept.map((b) => b.raw.join("\n")).join("\n\n")}\n` : content,
+		report
+	};
+}
+//#endregion
 //#region src/runtime/lifecycle/lessons/state.ts
 /**
 * Per-project lessons paths. The `fuse-lessons` plugin stores its lessons under
@@ -1577,9 +1828,10 @@ function lessonsStateFileFor(root) {
 * across every project with unsaved code edits; PostToolUse marks the write to
 * arm/silence the per-project throttle. Non-fatal by design.
 */
-/** Inject `<root>/MEMORY/LESSON.md` as additionalContext for `event`. */
-function injectMemory(cwd, event) {
-	const file = lessonsFileFor(projectRoot(cwd));
+/** Inject `MEMORY/LESSON.md` for `event`, after mechanical curation (a strict dedup rewrites the file in place; any report surfaces to the user via systemMessage). */
+function injectMemory(cwd, event, now) {
+	const root = projectRoot(cwd);
+	const file = lessonsFileFor(root);
 	if (!existsSync(file)) return "";
 	let content = "";
 	try {
@@ -1588,7 +1840,13 @@ function injectMemory(cwd, event) {
 		return "";
 	}
 	if (!content) return "";
-	return contextResponse(event, `Project lessons — never reproduce these:\n${content}\nYou may append OR refine/merge/dedupe bullets in MEMORY/LESSON.md — keep it terse.`);
+	const { content: curated, report } = curateLessons(content, now, root);
+	if (curated !== content) try {
+		atomicWrite(file, curated);
+		content = curated;
+	} catch {}
+	const ctx = `Project lessons — never reproduce these:\n${content}\nYou may append OR refine/merge/dedupe bullets in MEMORY/LESSON.md — keep it terse.`;
+	return report ? attachSystemMessage(contextResponse(event, ctx), `LESSON.md curation:\n${report}`) : contextResponse(event, ctx);
 }
 /** Select roots with unsaved code edits past the throttle, bumping their state. */
 function collectPending(now, window) {
@@ -1636,7 +1894,7 @@ function markWrite(payload, now) {
 function dispatchLessons(event, payload, cwd, now) {
 	switch (event) {
 		case "SessionStart":
-		case "SubagentStart": return injectMemory(cwd, event);
+		case "SubagentStart": return injectMemory(cwd, event, now);
 		case "Stop": return remindWrite(now);
 		case "PostToolUse":
 			markWrite(payload, now);
@@ -3529,6 +3787,50 @@ async function postEditContext(scope, event, now) {
 	return contextResponse("PostToolUse", `${additionalContextOf(sniper)}\n\n${additionalContextOf(lint)}`);
 }
 //#endregion
+//#region src/policy/trivial-edits.ts
+/**
+* Pre-filters of the ported enforce-apex-phases.ts hook, in Python order
+* (lines 48-65): protected-path guard first, then the dependency/build-dir
+* skip, then the trivial-edit fast path. The trivial COUNTER itself lives in
+* the SessionTrack (`trivialEdits`, see recordTrivialEdit/trivialCount) — no
+* separate state file.
+*/
+/** Hook-managed state paths — Write/Edit always denied (parity enforce-apex-phases.ts PROTECTED_PATHS). */
+const PROTECTED_PATHS = /\.claude\/(plugins\/(marketplaces|cache)|logs\/00-apex|fusengine-cache\/skill-tracking)/;
+/** Dependency/build dirs the APEX gates skip entirely (parity enforce-apex-phases.ts SKIP_DIRS). */
+const SKIP_DIRS = /(node_modules|vendor|dist|build|\.next|DerivedData)/;
+/**
+* Absolute deny on Write/Edit of hook-managed state paths, with the Python
+* wording byte-for-byte. Runs BEFORE the code-ext/skip-dirs filters (parity
+* enforce-apex-phases.ts:48-54), so non-code files under the protected roots
+* are covered too.
+* @param tool - The harness tool name (only Write/Edit are policed).
+* @param filePath - Target path of the edit (or undefined).
+* @returns A blocking prompt, or null to fall through.
+*/
+function protectedPathGate(tool, filePath) {
+	if (tool !== "Write" && tool !== "Edit" || !filePath || !PROTECTED_PATHS.test(filePath)) return null;
+	return {
+		kind: "block",
+		title: "APEX Hook Guard: protected path",
+		reason: "[APEX Hook Guard] Write blocked — this path is managed automatically by APEX hooks. Manual edits are forbidden and would corrupt tracked state."
+	};
+}
+/**
+* True when this tool-use qualifies for the trivial fast path (parity
+* enforce-apex-phases.ts:58-65): only an Edit (a Write always creates or
+* replaces a file wholesale), NEVER `replace_all`, and a new_string under
+* {@link TRIVIAL_MAX_LINES} lines. Absent content is NOT trivial (fail closed
+* — the full gates run).
+* @param tool - The harness tool name.
+* @param content - The Edit's new_string (adapter-normalized).
+* @param isReplaceAll - The Edit's replace_all flag.
+*/
+function isTrivialEdit(tool, content, isReplaceAll) {
+	if (tool !== "Edit" || isReplaceAll === true || content === void 0) return false;
+	return content.split("\n").length < 5;
+}
+//#endregion
 //#region src/runtime/gate-helpers.ts
 /** Source extensions the APEX gates apply to (parity: require-apex-agents.py CODE_EXT). */
 const CODE_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|dart|vue|svelte|astro)$/;
@@ -4113,7 +4415,14 @@ function geminiMcpGate(tool, filePath, content, ev) {
 //#region src/freshness/explore-tools.ts
 /** Native exploration tools (parity `apex_constants.EXPLORE_TOOLS`). */
 const EXPLORE_TOOLS = /* @__PURE__ */ new Set(["Glob", "Grep"]);
-/** Research tools — MCP docs + web (parity `apex_constants.RESEARCH_TOOLS`). */
+/**
+* Research tools — MCP docs + web (parity `apex_constants.RESEARCH_TOOLS`).
+* The fuse-browser fast-path entries are a deliberate TS addition: CLAUDE.md
+* mandates fuse-browser FIRST for web research, and `docSourceOf` (activity.ts)
+* already credits it for doc consultation — without them here, an agent
+* following the rules would never satisfy the freshness gate (same
+* cross-consumer inconsistency class as the solidReadGate lesson).
+*/
 const RESEARCH_TOOLS = /* @__PURE__ */ new Set([
 	"mcp__context7__query-docs",
 	"mcp__context7__resolve-library-id",
@@ -4121,7 +4430,11 @@ const RESEARCH_TOOLS = /* @__PURE__ */ new Set([
 	"mcp__exa__get_code_context_exa",
 	"mcp__exa__deep_researcher_start",
 	"WebSearch",
-	"WebFetch"
+	"WebFetch",
+	"mcp__fuse-browser__browser_fetch",
+	"mcp__fuse-browser__browser_fetch_batch",
+	"mcp__fuse-browser__browser_crawl",
+	"mcp__fuse-browser__browser_serp_batch"
 ]);
 /** Bash executables that count as exploration (parity `EXPLORE_BASH_CMDS`). */
 const EXPLORE_BASH_CMDS = /* @__PURE__ */ new Set([
@@ -4269,25 +4582,120 @@ function agentsRanFromTranscript(transcriptPath, names, windowMs, now) {
 	return names.every((n) => found.has(n));
 }
 //#endregion
+//#region src/freshness/agent-evidence-record.ts
+/**
+* Session-track agent evidence — writer (parity track-subagent-research.py) +
+* reader scan (parity apex_agent_helpers._scan_agents). Sub-agent hooks fire
+* with the LEAD's `session_id`, so evidence recorded here lands in the ONE
+* session track the freshness gate scans FIRST — sidechain research and
+* Workflow-spawned agents count, unlike the lead-transcript scan.
+*/
+/** Tools the existing Task tracking already credits as agent LAUNCHES. */
+const AGENT_LAUNCH_TOOLS = /* @__PURE__ */ new Set(["Task", "Agent"]);
+/**
+* `JSON.stringify` length of the raw `tool_response` OBJECT (parity Python
+* `len(str(tool_response))`); 0 when absent or unserializable (circular).
+*/
+function responseJsonLength(toolResponse) {
+	if (toolResponse === void 0 || toolResponse === null) return 0;
+	try {
+		return (JSON.stringify(toolResponse) ?? "").length;
+	} catch {
+		return 0;
+	}
+}
+/**
+* Classify one PostToolUse call into session evidence, or null when it is
+* neither exploration nor research (parity track-subagent-research._classify,
+* reusing the shared {@link classifyExplore} tables — research/explore/Bash/
+* cache-read). ANTI-DOUBLE-COUNT: calls classified as agent launches
+* (`Task`/`Agent`) are skipped — the existing Task tracking credits those; the
+* criterion is the CALL's classification, never its provenance (lead vs sub).
+* @param tool - Harness tool name (e.g. "Glob", "Bash", "Read").
+* @param input - Raw tool input payload.
+* @param toolResponse - Raw `tool_response` OBJECT from the hook payload.
+* @returns The evidence to record, or null to skip.
+*/
+function classifyAgentEvidence(tool, input, toolResponse) {
+	if (AGENT_LAUNCH_TOOLS.has(tool)) return null;
+	const hit = classifyExplore(tool, input);
+	if (!hit) return null;
+	return {
+		name: hit.phase === "explore-codebase" ? "subagent-explore-codebase" : "subagent-research-expert",
+		quality: hit.cacheHit || responseJsonLength(toolResponse) > 50 ? "sufficient" : "insufficient"
+	};
+}
+/**
+* Persist evidence into the SESSION track via {@link recordAgent} — keyed by
+* `session_id` alone (sub-agent hooks carry the lead's `session_id`); the TTL
+* anchors on `ts`, the tool call's own timestamp. `agentId` is tagged as
+* metadata when present, NEVER used as a condition (unreliable field —
+* anthropics/claude-code#22348).
+* @param file - Session track file path.
+* @param evidence - Classified evidence from {@link classifyAgentEvidence}.
+* @param ts - Epoch-ms timestamp of the tool call (the hook event's `now`).
+* @param agentId - Optional Claude `agent_id` — metadata tag only.
+*/
+async function recordAgentEvidence(file, evidence, ts, agentId) {
+	const next = recordAgent(await loadTrack(file), evidence.name, ts, evidence.quality);
+	const last = next.agents[next.agents.length - 1];
+	if (agentId && last) {
+		const tagged = {
+			...last,
+			agentId
+		};
+		next.agents[next.agents.length - 1] = tagged;
+	}
+	await saveTrack(file, next);
+}
+/**
+* Parity `_scan_agents` (apex_agent_helpers.py): reverse-scan `track.agents`,
+* STOPPING at the first entry older than `windowMs` (entries append in time
+* order), matching each required name by SUBSTRING (`research-expert` matches
+* `subagent-research-expert`) and counting ONLY `quality === "sufficient"`.
+* @param track - The loaded session track.
+* @param names - Required agent names — ALL must match to return true.
+* @param windowMs - Freshness window (ms), anchored on each entry's `ts`.
+* @param now - Current epoch ms.
+* @returns True when every required name has fresh, sufficient evidence.
+*/
+function agentsFreshInTrack(track, names, windowMs, now) {
+	const found = /* @__PURE__ */ new Set();
+	for (let i = track.agents.length - 1; i >= 0; i--) {
+		const entry = track.agents[i];
+		if (!entry) continue;
+		if (now - entry.ts > windowMs) break;
+		if (entry.quality !== "sufficient") continue;
+		for (const req of names) if (entry.name.includes(req)) found.add(req);
+		if (found.size === names.length) return true;
+	}
+	return names.every((n) => found.has(n));
+}
+//#endregion
 //#region src/runtime/gate-apex.ts
 /**
-* The APEX-scoped portion of {@link gate}: a trivial-edit fast path, then the
-* freshness/doc/SOLID gates fed from the session track. Freshness prefers
-* platform-authored transcript evidence (an agent cannot forge a `Task` in the
-* runtime-owned transcript); the self-recorded track is only a fallback when no
-* transcript path is available (tests / other harnesses).
+* The APEX-scoped portion of {@link gate}, in the Python enforce-apex-phases.ts
+* order: protected-paths guard, skip-dirs allow, trivial-edit fast path, then
+* brainstorm/freshness, Check 1 (per-framework doc authorization — a deny
+* persists `track.target` so recordDoc can cross-credit the framework) and
+* Check 2 + SOLID refs. Freshness scans the SESSION track first (parity
+* _scan_agents: sub-agent hooks share the lead's session_id, so sidechain/
+* Workflow research is visible); the platform-authored transcript scan and the
+* legacy exact-name track check are fallbacks.
 * @param input - The tool-use to gate.
 * @param track - The loaded session track.
 * @param window - Freshness window in ms.
 * @returns The first blocking prompt, or null to fall through to the DRY check.
 */
 async function apexScopedGate(input, track, window) {
-	const lineCount = input.content === void 0 ? Number.POSITIVE_INFINITY : input.content.split("\n").length;
-	if (input.tool === "Edit" && !input.isReplaceAll && lineCount < 5 && trivialCount(track, window, input.now) < 4) {
+	const protectedDeny = protectedPathGate(input.tool, input.filePath);
+	if (protectedDeny) return protectedDeny;
+	if (SKIP_DIRS.test(input.filePath ?? "")) return null;
+	if (isTrivialEdit(input.tool, input.content, input.isReplaceAll) && trivialCount(track, window, input.now) < 4) {
 		await saveTrack(input.trackFile, recordTrivialEdit(track, input.now, window, input.now));
 		return null;
 	}
-	const freshnessFor = (names, windowMs = window) => input.transcriptPath ? agentsRanFromTranscript(input.transcriptPath, names, windowMs, input.now) : agentsFresh(track, names, windowMs, input.now);
+	const freshnessFor = (names, windowMs = window) => agentsFreshInTrack(track, names, windowMs, input.now) || (input.transcriptPath ? agentsRanFromTranscript(input.transcriptPath, names, windowMs, input.now) : agentsFresh(track, names, windowMs, input.now));
 	const ctx = {
 		sessionId: input.sessionId,
 		framework: input.framework,
@@ -4305,7 +4713,20 @@ async function apexScopedGate(input, track, window) {
 		brainstormFresh: freshnessFor(["brainstorming"], Number.MAX_SAFE_INTEGER)
 	};
 	try {
-		return evaluateApex(ctx);
+		const pre = evaluateApex(ctx, PRE_AUTH_GATES);
+		if (pre) return pre;
+		const authDeny = apexAuthorizationGate(ctx);
+		if (authDeny) {
+			const set_at = new Date(input.now).toISOString();
+			await saveTrack(input.trackFile, recordTarget(track, {
+				project: input.cwd ?? "",
+				framework: input.framework,
+				set_by: "apex-authorization",
+				set_at
+			}));
+			return authDeny;
+		}
+		return evaluateApex(ctx, POST_AUTH_GATES);
 	} catch {
 		return FAIL_CLOSED;
 	}
@@ -4331,6 +4752,8 @@ const TRIVIAL_BUDGET = 4;
 async function gate(input) {
 	const precommit = preCommitGate(input.tool, input.command, input.cwd);
 	if (precommit) return precommit;
+	const protectedDeny = protectedPathGate(input.tool, input.filePath);
+	if (protectedDeny) return protectedDeny;
 	const { raw: existingLines, code: existingCodeLines } = existingLineCounts(input.filePath);
 	let quick;
 	try {
@@ -4493,7 +4916,7 @@ function mcpPostStore(tool, input, response, dir, now = Date.now()) {
 /** Apply an activity to a session's track and persist it (PostToolUse path). */
 async function recordActivity(file, activity) {
 	const track = await loadTrack(file);
-	await saveTrack(file, activity.kind === "agent" ? recordAgent(track, activity.name, activity.ts, activity.quality) : activity.kind === "doc" ? recordDoc(track, activity.framework, activity.sessionId, activity.source) : recordRefRead(track, activity.path, activity.ts));
+	await saveTrack(file, activity.kind === "agent" ? recordAgent(track, activity.name, activity.ts, activity.quality) : activity.kind === "doc" ? recordDoc(track, activity.framework, activity.sessionId, activity.source, activity.ts) : recordRefRead(track, activity.path, activity.ts));
 }
 //#endregion
 //#region src/runtime/respond.ts
@@ -4501,51 +4924,81 @@ async function recordActivity(file, activity) {
 * Map a portable {@link Prompt} to a harness's native hook response, honoring
 * all 3 prompt kinds (`block`/`ask`/`inform`) instead of collapsing `ask` and
 * `inform` together. Reuses the Claude adapter's `denyResponse`/
-* `contextResponse` builders for claude-code/codex (same hook shape) to avoid
-* duplicating the JSON.
+* `contextResponse`/`informResponse` builders for claude-code/codex (same hook
+* shape) to avoid duplicating the JSON.
 * - claude-code/codex: `block` -> deny, `ask` -> interactive
 *   `permissionDecision:"ask"`, `inform` -> non-blocking `additionalContext`.
 * - gemini-cli/cline: their real hook schemas have no interactive "ask"
 *   state (deny is the only blocking outcome), so `ask` and `inform` already
 *   both resolve to non-blocking context injection — unchanged.
-* - cursor: `ask` keeps its current best-effort `permission:"ask"` shape
-*   (unverified against Cursor's exact hook docs); only `inform` is fixed to
-*   a non-blocking `permission:"allow"` note, since it was wrongly conflated
-*   with `ask` before.
+* - cursor: `ask` keeps its current best-effort `permission:"ask"` shape;
+*   only `inform` is fixed to a non-blocking `permission:"allow"` note.
+* - hermes: delegated to the adapter's `toHermesResponse` — `block` ->
+*   `{decision:"block",reason}`; `ask`/`inform` degrade to non-blocking
+*   `{context}` (Hermes has no interactive "ask" state).
+*
+* User-visible pass notices (`prompt.userMessage`, Python `hook_output.allow_pass`
+* / `post_pass` parity), by harness:
+* - claude-code/codex: top-level `systemMessage` ("warning message shown to the
+*   user"); a pure notice (empty `reason`) emits `{systemMessage}` alone. Codex
+*   consumes the Claude hook schema, so it rides the same field.
+* - gemini-cli: common `systemMessage` output field ("displayed immediately to
+*   the user in the terminal") — the notice rides there.
+* - cursor: `user_message` is its user-visible channel (see case comment).
+* - cline: NO user-visible channel (`cancel`/`contextModification`/
+*   `errorMessage`-on-cancel only) — the notice is dropped silently (a pure
+*   notice returns "" = plain allow).
 */
 function respond(id, prompt) {
 	const message = formatPrompt(prompt);
-	const { kind } = prompt;
+	const { kind, userMessage, reason } = prompt;
 	switch (id) {
 		case "claude-code":
 		case "codex":
 			if (kind === "block") return denyResponse("PreToolUse", message);
-			if (kind === "inform") return contextResponse("PreToolUse", message);
+			if (kind === "inform") return userMessage ? informResponse("PreToolUse", userMessage, reason ? message : "") : contextResponse("PreToolUse", message);
 			return JSON.stringify({ hookSpecificOutput: {
 				hookEventName: "PreToolUse",
 				permissionDecision: "ask",
 				permissionDecisionReason: message
 			} });
-		case "gemini-cli": return JSON.stringify(kind === "block" ? {
-			decision: "deny",
-			reason: message
-		} : { hookSpecificOutput: { additionalContext: message } });
-		case "cursor":
-			if (kind === "inform") return JSON.stringify({
-				permission: "allow",
-				userMessage: message,
-				agentMessage: message
+		case "gemini-cli":
+			if (kind === "block") return JSON.stringify({
+				decision: "deny",
+				reason: message
+			});
+			if (userMessage) return JSON.stringify({
+				...reason ? { hookSpecificOutput: { additionalContext: message } } : {},
+				systemMessage: userMessage
 			});
+			return JSON.stringify({ hookSpecificOutput: { additionalContext: message } });
+		case "cursor":
+			if (kind === "inform") {
+				if (userMessage) return JSON.stringify({
+					permission: "allow",
+					user_message: userMessage,
+					...reason ? { agent_message: message } : {}
+				});
+				return JSON.stringify({
+					permission: "allow",
+					user_message: message,
+					agent_message: message
+				});
+			}
 			return JSON.stringify({
 				permission: kind === "block" ? "deny" : "ask",
 				continue: false,
-				userMessage: message,
-				agentMessage: message
+				user_message: message,
+				agent_message: message
+			});
+		case "hermes": return toHermesResponse(prompt);
+		case "cline":
+			if (kind === "block") return JSON.stringify({
+				cancel: true,
+				errorMessage: message
 			});
-		case "cline": return JSON.stringify(kind === "block" ? {
-			cancel: true,
-			errorMessage: message
-		} : { contextModification: message });
+			if (userMessage && !reason) return "";
+			return JSON.stringify({ contextModification: message });
 		default: return "";
 	}
 }
@@ -4733,10 +5186,10 @@ function collectDesignEvidence(sessionId, cwd, baseDir = defaultStateDir(cwd)) {
 * `design.ts` to keep that file within the SOLID size budget (SRP).
 * @packageDocumentation
 */
-const NAV$1 = "mcp__fuse-browser__browser_navigate";
-const SHOT$1 = "mcp__fuse-browser__browser_screenshot";
+const NAV$2 = "mcp__fuse-browser__browser_navigate";
+const SHOT$2 = "mcp__fuse-browser__browser_screenshot";
 const SCROLL = "mcp__fuse-browser__browser_scroll";
-const GEMINI$1 = "mcp__gemini-design__create_frontend";
+const GEMINI$2 = "mcp__gemini-design__create_frontend";
 /** Read design-system.md walking up to 6 parents from `cwd` ("" if absent/unreadable). */
 function findDesignSystem(cwd) {
 	let dir = cwd;
@@ -4755,10 +5208,10 @@ function findDesignSystem(cwd) {
 }
 /** Apply a PostToolUse fuse-browser transition to the design state. */
 function recordPost(event, cacheDir, state) {
-	if (event.tool === SHOT$1) saveDesignState(cacheDir, recordScreenshot(state, MIN_SCREENSHOTS[state.mode]));
-	else if (event.tool === NAV$1) saveDesignState(cacheDir, recordNavigate(state));
+	if (event.tool === SHOT$2) saveDesignState(cacheDir, recordScreenshot(state, MIN_SCREENSHOTS[state.mode]));
+	else if (event.tool === NAV$2) saveDesignState(cacheDir, recordNavigate(state));
 	else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
-	else if (event.tool === GEMINI$1) saveDesignState(cacheDir, {
+	else if (event.tool === GEMINI$2) saveDesignState(cacheDir, {
 		...state,
 		geminiCalls: state.geminiCalls + 1
 	});
@@ -4781,6 +5234,9 @@ const FORBIDDEN_FONTS = [
 	"Open Sans"
 ];
 const OKLCH_RE = /oklch\(\s*[\d.]+%?\s+0\.0*[1-9]/;
+const NAV$1 = "mcp__fuse-browser__browser_navigate";
+const SHOT$1 = "mcp__fuse-browser__browser_screenshot";
+const GEMINI$1 = "mcp__gemini-design__create_frontend";
 const deny = (reason) => ({
 	kind: "block",
 	title: "Design pipeline",
@@ -4814,6 +5270,40 @@ function geminiEnabled() {
 	const v = process.env.FUSE_DESIGN_GEMINI;
 	return v === "1" || v === "true";
 }
+/**
+* Python-parity pass notices (`hook_output.allow_pass`/`post_pass`): the
+* user-visible `script: detail` lines the old plugins printed on EVERY passing
+* design hook. Call AFTER the gates allowed the event; returns an `inform`
+* Prompt carrying only `userMessage` (for the human, never agent context), or
+* null when nothing applies. The check-design-skill line fires for ANY agent
+* on a UI write; the rest only inside the active design-agent context.
+*/
+function designPassNotice(i, cacheDir) {
+	const isWrite = i.tool === "Write" || i.tool === "Edit";
+	const fp = i.filePath;
+	const lines = [];
+	if (i.phase === "pre" && isUiWrite(i.tool, fp, i.content)) {
+		const domains = SKILL_TRIGGERS.filter((t) => t.patterns.some((re) => re.test(i.content))).map((t) => t.skill).join(", ");
+		lines.push(`check-design-skill: pass (domain: ${domains || "base"})`);
+	}
+	const state = i.agentId && activeDesignAgent(cacheDir) === i.agentId ? loadDesignState(cacheDir, i.agentId) : null;
+	if (state && i.phase === "pre") {
+		if (isWrite && fp && !EXEMPT_DIRS.some((d) => fp.includes(d)) && ALLOWED_WRITE.test(fp)) lines.push(`enforce-html-css-only: allowed: ${basename(fp)}`);
+		if (i.tool === NAV$1) lines.push(`check-inspiration-read: pass (${i.url})`);
+		if (i.tool === GEMINI$1 && geminiEnabled()) lines.push("validate-design-system: design-system.md ok");
+		if (isWrite || i.tool === NAV$1 || i.tool === SHOT$1 || i.tool === GEMINI$1) lines.push(`pipeline-gate: phase ${state.currentPhase} ok`);
+	}
+	if (state && i.phase === "post" && isWrite) {
+		if (basename(fp) === "design-system.md") lines.push("validate-design: design-system.md → phase 3");
+		else if (/\.(tsx|jsx|css)$/.test(fp)) lines.push("validate-design: design ok");
+	}
+	return lines.length ? {
+		kind: "inform",
+		title: "Design pipeline",
+		reason: "",
+		userMessage: lines.join("\n")
+	} : null;
+}
 //#endregion
 //#region src/policy/design/gates-pipeline.ts
 const SKILLS = `${PLUGINS_DIR}/design-expert/skills`;
@@ -4925,6 +5415,206 @@ function designGate(payload, event, cacheDir, cwd) {
 	return null;
 }
 //#endregion
+//#region src/policy/lessons/trigger-index.ts
+/**
+* Compile the triggered-lesson index from `MEMORY/LESSON.md`. A lesson is a
+* bullet (`- [YYYY-MM-DD HH:MM] ...`); it opts into decision-time injection by
+* ending with a `[TRIGGERS tool:.. path:.. error:.. keyword:..]` line. Lessons
+* WITHOUT that tag are skipped here (they keep the SessionStart block behavior —
+* zero regression). Parsed once per file version (mtime-memoized).
+*/
+/** Matches a trailing `[TRIGGERS ...]` line (its body captured). */
+const TRIGGER_RE = /^\[TRIGGERS\s+(.+?)\]$/;
+/** Comma list for `key:` in a trigger body (values are space-delimited). */
+function list(body, key) {
+	const val = body.match(new RegExp(`\\b${key}:([^\\s\\]]+)`))?.[1];
+	return val ? val.split(",").filter(Boolean) : [];
+}
+/** Parse a `[TRIGGERS ...]` body into predicates (error is a single regex). */
+function parseTriggers(body) {
+	const err = body.match(/\berror:([^\s\]]+)/);
+	return {
+		tools: list(body, "tool"),
+		paths: list(body, "path"),
+		error: err?.[1],
+		keywords: list(body, "keyword")
+	};
+}
+/** Collapse to a single ≤3-line compact string (cap length). */
+function compact(text) {
+	const one = text.replace(/\s+/g, " ").trim();
+	return one.length > 280 ? `${one.slice(0, 277)}…` : one;
+}
+/**
+* Parse LESSON.md content into triggered entries. A bullet's text spans its
+* `- ` line plus any following non-blank continuation lines up to the next
+* bullet; a `[TRIGGERS ...]` continuation line arms it.
+* @param content - Raw LESSON.md text.
+* @returns Entries that declared triggers (others skipped).
+*/
+function parseLessons(content) {
+	const lines = content.split("\n");
+	const out = [];
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (line === void 0 || !line.startsWith("- ")) continue;
+		let text = line.slice(2);
+		let triggers = null;
+		for (let j = i + 1; j < lines.length; j++) {
+			const cont = lines[j];
+			if (cont === void 0 || cont.trim() === "" || cont.startsWith("- ")) break;
+			const body = cont.trim().match(TRIGGER_RE)?.[1];
+			if (body !== void 0) triggers = parseTriggers(body);
+			else text += ` ${cont.trim()}`;
+		}
+		if (triggers) out.push({
+			text: compact(text),
+			triggers
+		});
+	}
+	return out;
+}
+let memo = null;
+/**
+* Compile (once per file version) the triggered-lesson index from `file`.
+* Memoized by path+mtime: re-parses only when LESSON.md changes.
+* @param file - Absolute path to MEMORY/LESSON.md.
+* @returns The compiled entries (missing/unreadable file → empty).
+*/
+function lessonIndex(file) {
+	let key;
+	try {
+		key = `${file}:${statSync(file).mtimeMs}`;
+	} catch {
+		return [];
+	}
+	if (memo?.key === key) return memo.entries;
+	let entries = [];
+	try {
+		entries = parseLessons(readFileSync(file, "utf-8"));
+	} catch {
+		entries = [];
+	}
+	memo = {
+		key,
+		entries
+	};
+	return entries;
+}
+/** Glob (`*`/`**`) → RegExp, matching a path segment/tail. */
+function globToRe(glob) {
+	const esc = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(//g, ".*");
+	return new RegExp(`(^|/)${esc}$`);
+}
+/** Safe case-insensitive regex test (absent source or invalid → false). */
+function safeTest(src, s) {
+	if (!src) return false;
+	try {
+		return new RegExp(src, "i").test(s);
+	} catch {
+		return false;
+	}
+}
+/** Score one entry against the call; null = no predicate matched. */
+function scoreEntry(e, tool, filePath, inputJson, prevError) {
+	const tr = e.triggers;
+	if (tr.tools.includes(tool)) return {
+		entry: e,
+		rank: 3
+	};
+	if (filePath && tr.paths.some((g) => globToRe(g).test(filePath))) return {
+		entry: e,
+		rank: 2
+	};
+	if (prevError && safeTest(tr.error, prevError)) return {
+		entry: e,
+		rank: 1
+	};
+	if (tr.keywords.some((k) => inputJson.includes(k))) return {
+		entry: e,
+		rank: 0
+	};
+	return null;
+}
+/** Stable, filesystem-safe cooldown key from a lesson's compact text (djb2). */
+function cooldownKey(text) {
+	let h = 5381;
+	for (let i = 0; i < text.length; i++) h = (h << 5) + h + text.charCodeAt(i) | 0;
+	return `lesson:${(h >>> 0).toString(36)}`;
+}
+/**
+* The single most-specific lesson for this PreToolUse call, or null. Matching
+* priority: exact tool > path glob > error regex > input-JSON keyword. Cooldown
+* suppresses a lesson already injected within the window.
+* @param tool - The tool being called (e.g. `Write`).
+* @param toolInput - The raw `tool_input`.
+* @param opts - Index file, cooldown gate, and optional prior error.
+* @returns An `inform` prompt, or null when nothing matches / in cooldown.
+*/
+function lessonFor(tool, toolInput, opts) {
+	const entries = lessonIndex(opts.file);
+	if (entries.length === 0) return null;
+	const filePath = typeof toolInput?.file_path === "string" ? toolInput.file_path : "";
+	const inputJson = JSON.stringify(toolInput ?? {});
+	let best = null;
+	for (const e of entries) {
+		const m = scoreEntry(e, tool, filePath, inputJson, opts.prevError);
+		if (m && (!best || m.rank > best.rank)) best = m;
+	}
+	if (!best) return null;
+	if (!opts.once(cooldownKey(best.entry.text), opts.cooldownMs ?? 18e5)) return null;
+	return {
+		kind: "inform",
+		title: `Project lesson${filePath ? ` (${basename(filePath)})` : ""}`,
+		reason: best.entry.text
+	};
+}
+//#endregion
+//#region src/runtime/pre-allow.ts
+/**
+* PreToolUse ALLOW-path response assembly. Reached only after every gate
+* allowed (a deny/ask already returned upstream), so nothing here can block nor
+* override a decision. Combines the Python-parity pass notice (systemMessage)
+* with the single most-specific decision-time lesson (additionalContext).
+*/
+/**
+* Build the native outcome for a PreToolUse call that passed every gate: emit a
+* user-visible pass notice (once per allowed call) and, when its TRIGGERS match
+* this call, the one cooldown-guarded decision-time lesson. Both channels ride a
+* single response (lesson → additionalContext, notice → systemMessage).
+* @param id - Harness id for {@link respond}.
+* @param event - The normalized PreToolUse event.
+* @param payload - The raw hook payload (for `agent_id`).
+* @param mcpDir - MCP state dir backing the pass-notice throttle.
+* @param cwd - Project root (lesson file + notice scope).
+* @returns The native hook outcome (empty stdout when nothing to emit).
+*/
+function allowOutcome(id, event, payload, mcpDir, cwd) {
+	const notice = designPassNotice({
+		agentId: typeof payload.agent_id === "string" ? payload.agent_id : "",
+		tool: event.tool,
+		filePath: event.filePath ?? "",
+		content: event.content ?? "",
+		url: typeof event.input.url === "string" ? event.input.url : "",
+		phase: "pre"
+	}, mcpDir);
+	const lesson = lessonFor(event.tool, event.input, {
+		file: lessonsFileFor(projectRoot(cwd)),
+		once: oncePerWindow
+	});
+	if (lesson) return {
+		stdout: respond(id, notice?.userMessage ? {
+			...lesson,
+			userMessage: notice.userMessage
+		} : lesson),
+		exit: 0
+	};
+	return {
+		stdout: notice ? respond(id, notice) : "",
+		exit: 0
+	};
+}
+//#endregion
 //#region src/runtime/handle-pre.ts
 /**
 * Run the PreToolUse pipeline: MCP/WebFetch cache intercept, design gate, APEX
@@ -4985,13 +5675,90 @@ async function handlePre(ctx) {
 		trackFile: file,
 		transcriptPath: typeof payload.transcript_path === "string" ? payload.transcript_path : void 0
 	});
-	return prompt ? {
+	if (prompt) return {
 		stdout: respond(id, prompt),
 		exit: 0
-	} : {
-		stdout: "",
-		exit: 0
 	};
+	return allowOutcome(id, event, payload, mcpDir, opts.cwd);
+}
+//#endregion
+//#region src/freshness/query-framework.ts
+/**
+* Framework classification for doc consultations, keyed on the QUERY text
+* (parity ai-pilot/scripts/track_doc_helpers.py::detect_framework): an MCP
+* doc call (context7/exa/web) has no filePath, so the file-based
+* `detectFramework()` always yields "generic" — the query keywords are the
+* only framework signal a doc consultation carries.
+*/
+/**
+* Ordered patterns, EXACT parity with the Python list (same order, same
+* case-sensitive alternations, substring search — only `go` is word-bounded).
+* Quirks are inherited deliberately: "javascript" hits `java` (but only after
+* nextjs/react/laravel/swift/tailwind all missed) and all-caps "NEXT" misses.
+* The output domain matches `detectFramework()` exactly, so every credit
+* lands on a key the apex authorization gate actually reads.
+*/
+const QUERY_FRAMEWORKS = [
+	[/(next|nextjs|Next)/, "nextjs"],
+	[/(react|React)/, "react"],
+	[/(laravel|Laravel|php|PHP)/, "laravel"],
+	[/(swift|Swift|swiftui|SwiftUI)/, "swift"],
+	[/(tailwind|Tailwind)/, "tailwind"],
+	[/(java|Java|spring|Spring)/, "java"],
+	[/\b(go|Go|golang)\b/, "go"],
+	[/(ruby|Ruby|rails|Rails)/, "ruby"],
+	[/(rust|Rust|cargo|Cargo)/, "rust"]
+];
+/**
+* The framework a doc query targets, or null when no keyword matches (the
+* Python returns "generic"; null here lets the caller fall back to the
+* event's file-detected framework instead of hardcoding generic).
+* @param query - The query/url/prompt text of the doc tool call.
+*/
+function frameworkFromQuery(query) {
+	for (const [re, fw] of QUERY_FRAMEWORKS) if (re.test(query)) return fw;
+	return null;
+}
+/**
+* tool_input fields carrying query text across doc tools: context7
+* (`libraryId`/`libraryName`, parity extract_tool_info), exa/WebSearch
+* (`query`), fuse-browser serp (`queries[]`), WebFetch (`url` + `prompt`).
+*/
+const QUERY_FIELDS = [
+	"query",
+	"queries",
+	"libraryId",
+	"libraryName",
+	"prompt",
+	"url"
+];
+/**
+* Fold every query-ish tool_input field into one searchable string. Distinct
+* from mcp-key.ts `queryOf`, which picks a SINGLE field to key the response
+* cache — classification wants ALL the text (e.g. WebFetch url + prompt).
+* @param input - The normalized tool_input (absent on some harnesses).
+*/
+function docQueryOf(input) {
+	if (!input) return "";
+	const parts = [];
+	for (const key of QUERY_FIELDS) {
+		const v = input[key];
+		if (typeof v === "string") parts.push(v);
+		else if (Array.isArray(v)) {
+			for (const s of v) if (typeof s === "string") parts.push(s);
+		}
+	}
+	return parts.join(" ");
+}
+/**
+* The framework to credit for a doc consultation: the query's framework when
+* a keyword matches (query wins over file-based detection), else `fallback`
+* (the event's framework — "generic" for pathless MCP calls).
+* @param input - The doc tool's tool_input.
+* @param fallback - The event's file-detected framework.
+*/
+function docFramework(input, fallback) {
+	return frameworkFromQuery(docQueryOf(input)) ?? fallback;
 }
 //#endregion
 //#region src/runtime/activity.ts
@@ -5052,9 +5819,10 @@ function activityFor(event) {
 	const docSource = docSourceOf(event.tool);
 	if (docSource) out.push({
 		kind: "doc",
-		framework: event.framework,
+		framework: docFramework(event.input, event.framework),
 		sessionId: event.sessionId,
-		source: docSource
+		source: docSource,
+		ts: event.now
 	});
 	if (event.tool === "Task" || event.tool === "Agent") {
 		const name = String(event.input?.subagent_type ?? event.input?.name ?? "").split(":").pop() ?? "";
@@ -5098,6 +5866,8 @@ async function handlePost(ctx) {
 		responseLength: extractText(response).length
 	});
 	for (const activity of activities) await recordActivity(file, activity);
+	const evidence = classifyAgentEvidence(event.tool, event.input, response);
+	if (evidence) await recordAgentEvidence(file, evidence, opts.now, typeof payload.agent_id === "string" ? payload.agent_id : void 0);
 	postTrackingSideEffects(opts.scope ?? "core", event, event.input, opts.now, payload, opts.cwd);
 	const seoDeny = opts.scope === "seo" ? seoPostToolUseResponse(payload) : null;
 	if (seoDeny) return {
@@ -5126,8 +5896,35 @@ async function handlePost(ctx) {
 		};
 	}
 	const extra = await postEditContext(opts.scope ?? "core", event, opts.now);
+	const notice = designPassNotice({
+		agentId: typeof payload.agent_id === "string" ? payload.agent_id : "",
+		tool: event.tool,
+		filePath: event.filePath ?? "",
+		content: event.content ?? "",
+		url: "",
+		phase: "post"
+	}, mcpDir);
+	if (designWarn) return {
+		stdout: respond(id, notice?.userMessage ? {
+			...designWarn,
+			userMessage: notice.userMessage
+		} : designWarn),
+		exit: 0
+	};
+	if (!notice?.userMessage) return {
+		stdout: extra,
+		exit: 0
+	};
+	if (!extra) return {
+		stdout: respond(id, notice),
+		exit: 0
+	};
+	if (id === "claude-code" || id === "codex") return {
+		stdout: attachSystemMessage(extra, notice.userMessage),
+		exit: 0
+	};
 	return {
-		stdout: designWarn ? respond(id, designWarn) : extra,
+		stdout: respond(id, notice) || extra,
 		exit: 0
 	};
 }
@@ -5212,4 +6009,4 @@ async function handleHook(id, payload, opts) {
 	});
 }
 //#endregion
-export { saveApexState as $, trackSkillRead as A, securityStateDir as At, writePluginMap as B, seoPostToolUse as C, defaultStateDir as Ct, postTrackingSideEffects as D, isoUtc as Dt, securityAdvisory as E, normalizeEvent as Et, dispatchLessons as F, mergeLines as G, isProject as H, lessonsFileFor as I, listChildren as J, countFiles as K, lessonsStateFileFor as L, dispatchLifecycle as M, todayUtc as Mt, aipilotPostToolUse as N, trackWatchResearch as O, loadSecurityState as Ot, dispatchAipilot as P, cleanupSession as Q, cartoSessionStart as R, postEditContext as S, taskContext as St, dispatchMemory as T, trackFile as Tt, writeTree as U, generateProjectMap as V, loadEnriched as W, trackSessionChanges as X, postEditTypescript as Y, validateRulesLoaded as Z, preCommitGate as _, trimLogFile as _t, recordActivity as a, validateSolidGate as at, extractSymbols as b, projectContext as bt, MCP_TTL_MS as c, detectSolidProfile as ct, isMcpTool as d, readRules as dt, logToolFailure as et, queryOf as f, runSessionStartCleanups as ft, gate as g, removeOldFiles as gt, TRIVIAL_BUDGET as h, purgeTtlTree as ht, respond as i, validateTailwind as it, trackEnrichment as j, securityStatePath as jt, trackMcpResearch as k, saveSecurityState as kt, WEBFETCH_TTL_MS as l, solidDetectStart as lt, REQUIRED_AGENTS as m, pruneEmptyDirs as mt, activityFor as n, trackAgentMemory as nt, mcpPostStore as o, checkFileSize as ot, DEFAULT_WINDOW_MS as p, sessionStartCore as pt, getFileDesc as q, handlePre as r, subagentCacheContext as rt, mcpPreIntercept as s, countLoc as st, handleHook as t, validateTeammateOutput as tt, cacheQueryOf as u, injectRules as ut, detectDuplication as v, devContext as vt, seoPostToolUseResponse as w, projectHash$1 as wt, lifecycleStdout as x, promptSubmitContext as xt, dryGate as y, gitContext as yt, generateEcosystemMap as z };
+export { saveApexState as $, trackSkillRead as A, saveSecurityState as At, writePluginMap as B, seoPostToolUse as C, taskContext as Ct, postTrackingSideEffects as D, normalizeEvent as Dt, securityAdvisory as E, trackFile as Et, dispatchLessons as F, mergeLines as G, isProject as H, lessonsFileFor as I, listChildren as J, countFiles as K, lessonsStateFileFor as L, dispatchLifecycle as M, securityStatePath as Mt, aipilotPostToolUse as N, todayUtc as Nt, trackWatchResearch as O, isoUtc as Ot, dispatchAipilot as P, cleanupSession as Q, cartoSessionStart as R, postEditContext as S, promptSubmitContext as St, dispatchMemory as T, projectHash$1 as Tt, writeTree as U, generateProjectMap as V, loadEnriched as W, trackSessionChanges as X, postEditTypescript as Y, validateRulesLoaded as Z, preCommitGate as _, trimLogFile as _t, recordActivity as a, validateSolidGate as at, extractSymbols as b, projectContext as bt, MCP_TTL_MS as c, detectSolidProfile as ct, isMcpTool as d, readRules as dt, logToolFailure as et, queryOf as f, runSessionStartCleanups as ft, gate as g, removeOldFiles as gt, TRIVIAL_BUDGET as h, purgeTtlTree as ht, respond as i, validateTailwind as it, trackEnrichment as j, securityStateDir as jt, trackMcpResearch as k, loadSecurityState as kt, WEBFETCH_TTL_MS as l, solidDetectStart as lt, REQUIRED_AGENTS as m, pruneEmptyDirs as mt, activityFor as n, trackAgentMemory as nt, mcpPostStore as o, checkFileSize as ot, DEFAULT_WINDOW_MS as p, sessionStartCore as pt, getFileDesc as q, handlePre as r, subagentCacheContext as rt, mcpPreIntercept as s, countLoc as st, handleHook as t, validateTeammateOutput as tt, cacheQueryOf as u, injectRules as ut, detectDuplication as v, devContext as vt, seoPostToolUseResponse as w, defaultStateDir as wt, lifecycleStdout as x, claudeMdKey as xt, dryGate as y, gitContext as yt, generateEcosystemMap as z };