@fusengine/harness 0.1.49 → 0.1.50

package/dist/cli/bin.mjs

@@ -4,7 +4,7 @@ import { t as detectHarness } from "../harness-Cb9xR8dC.mjs";
 import { t as claudeHome } from "../home-state-D0RLWP8J.mjs";
 import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-DZvP_9xB.mjs";
 import { n as writeInitFile, t as initFor } from "../run-Do2JltgU.mjs";
-import { Mt as todayUtc, t as handleHook } from "../handle-D1hHqHvh.mjs";
+import { Nt as todayUtc, t as handleHook } from "../handle-DzPjaPS-.mjs";
 import { delimiter, dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";

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

@@ -327,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
@@ -867,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) {
@@ -903,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)` });
 }
@@ -1555,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
@@ -1579,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 {
@@ -1590,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) {
@@ -1638,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);
@@ -5159,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
@@ -5223,18 +5679,7 @@ async function handlePre(ctx) {
 		stdout: respond(id, prompt),
 		exit: 0
 	};
-	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);
-	return {
-		stdout: notice ? respond(id, notice) : "",
-		exit: 0
-	};
+	return allowOutcome(id, event, payload, mcpDir, opts.cwd);
 }
 //#endregion
 //#region src/freshness/query-framework.ts
@@ -5564,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 };

package/dist/runtime/index.d.mts

@@ -240,8 +240,24 @@ declare function mcpPostStore(tool: string, input: Record<string, unknown>, resp
 //#endregion
 //#region src/runtime/inject-context.d.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.
+*/
+declare function claudeMdKey(prompt: string, ctx: string): string;
+/**
 * 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).
@@ -811,4 +827,4 @@ interface PreContext {
 */
 declare function handlePre(ctx: PreContext): Promise<HandleOutcome>;
 //#endregion
-export { Activity, DEFAULT_WINDOW_MS, DuplicationVerdict, type GateInput, HandleOptions, HandleOutcome, LifecycleInput, MCP_TTL_MS, McpIntercept, NormalizedEvent, PluginScope, PreContext, REQUIRED_AGENTS, SolidProfile, TRIVIAL_BUDGET, ToolEvent, WEBFETCH_TTL_MS, activityFor, aipilotPostToolUse, cacheQueryOf, cartoSessionStart, checkFileSize, claudeHome, cleanupSession, countFiles, countLoc, defaultStateDir, detectDuplication, detectSolidProfile, devContext, dispatchAipilot, dispatchLessons, dispatchLifecycle, dispatchMemory, dryGate, extractSymbols, fuseHarnessHome, fusengineCache, gate, generateEcosystemMap, generateProjectMap, getFileDesc, gitContext, handleHook, handlePre, harnessStateDir, injectRules, isMcpTool, isProject, isoUtc, lessonsFileFor, lessonsStateFileFor, lifecycleStdout, listChildren, loadEnriched, loadSecurityState, loadSessionState, logToolFailure, mcpPostStore, mcpPreIntercept, mergeLines, normalizeEvent, postEditContext, postEditTypescript, postTrackingSideEffects, preCommitGate, projectContext, projectHash, promptSubmitContext, pruneEmptyDirs, purgeTtlTree, queryOf, readRules, recordActivity, removeOldFiles, respond, runSessionStartCleanups, sanitizeSessionId, saveApexState, saveSecurityState, saveSessionState, securityAdvisory, securityStateDir, securityStatePath, seoPostToolUse, seoPostToolUseResponse, sessionStartCore, sessionStatePath, sessionsDir, solidDetectStart, subagentCacheContext, taskContext, todayUtc, trackAgentMemory, trackEnrichment, trackFile, trackMcpResearch, trackSessionChanges, trackSkillRead, trackWatchResearch, trimLogFile, validateRulesLoaded, validateSolidGate, validateTailwind, validateTeammateOutput, writePluginMap, writeTree };
+export { Activity, DEFAULT_WINDOW_MS, DuplicationVerdict, type GateInput, HandleOptions, HandleOutcome, LifecycleInput, MCP_TTL_MS, McpIntercept, NormalizedEvent, PluginScope, PreContext, REQUIRED_AGENTS, SolidProfile, TRIVIAL_BUDGET, ToolEvent, WEBFETCH_TTL_MS, activityFor, aipilotPostToolUse, cacheQueryOf, cartoSessionStart, checkFileSize, claudeHome, claudeMdKey, cleanupSession, countFiles, countLoc, defaultStateDir, detectDuplication, detectSolidProfile, devContext, dispatchAipilot, dispatchLessons, dispatchLifecycle, dispatchMemory, dryGate, extractSymbols, fuseHarnessHome, fusengineCache, gate, generateEcosystemMap, generateProjectMap, getFileDesc, gitContext, handleHook, handlePre, harnessStateDir, injectRules, isMcpTool, isProject, isoUtc, lessonsFileFor, lessonsStateFileFor, lifecycleStdout, listChildren, loadEnriched, loadSecurityState, loadSessionState, logToolFailure, mcpPostStore, mcpPreIntercept, mergeLines, normalizeEvent, postEditContext, postEditTypescript, postTrackingSideEffects, preCommitGate, projectContext, projectHash, promptSubmitContext, pruneEmptyDirs, purgeTtlTree, queryOf, readRules, recordActivity, removeOldFiles, respond, runSessionStartCleanups, sanitizeSessionId, saveApexState, saveSecurityState, saveSessionState, securityAdvisory, securityStateDir, securityStatePath, seoPostToolUse, seoPostToolUseResponse, sessionStartCore, sessionStatePath, sessionsDir, solidDetectStart, subagentCacheContext, taskContext, todayUtc, trackAgentMemory, trackEnrichment, trackFile, trackMcpResearch, trackSessionChanges, trackSkillRead, trackWatchResearch, trimLogFile, validateRulesLoaded, validateSolidGate, validateTailwind, validateTeammateOutput, writePluginMap, writeTree };

package/dist/runtime/index.mjs

@@ -1,6 +1,6 @@
 import { r as projectLayout } from "../layout-C0jaaCQC.mjs";
 import { a as sanitizeSessionId, c as sessionsDir, i as loadSessionState, n as fuseHarnessHome, o as saveSessionState, r as fusengineCache, s as sessionStatePath, t as claudeHome } from "../home-state-D0RLWP8J.mjs";
-import { $ as saveApexState, A as trackSkillRead, At as securityStateDir, B as writePluginMap, C as seoPostToolUse, Ct as defaultStateDir, D as postTrackingSideEffects, Dt as isoUtc, E as securityAdvisory, Et as normalizeEvent, F as dispatchLessons, G as mergeLines, H as isProject, I as lessonsFileFor, J as listChildren, K as countFiles, L as lessonsStateFileFor, M as dispatchLifecycle, Mt as todayUtc, N as aipilotPostToolUse, O as trackWatchResearch, Ot as loadSecurityState, P as dispatchAipilot, Q as cleanupSession, R as cartoSessionStart, S as postEditContext, St as taskContext, T as dispatchMemory, Tt as trackFile, U as writeTree, V as generateProjectMap, W as loadEnriched, X as trackSessionChanges, Y as postEditTypescript, Z as validateRulesLoaded, _ as preCommitGate, _t as trimLogFile, a as recordActivity, at as validateSolidGate, b as extractSymbols, bt as projectContext, c as MCP_TTL_MS, ct as detectSolidProfile, d as isMcpTool, dt as readRules, et as logToolFailure, f as queryOf, ft as runSessionStartCleanups, g as gate, gt as removeOldFiles, h as TRIVIAL_BUDGET, ht as purgeTtlTree, i as respond, it as validateTailwind, j as trackEnrichment, jt as securityStatePath, k as trackMcpResearch, kt as saveSecurityState, l as WEBFETCH_TTL_MS, lt as solidDetectStart, m as REQUIRED_AGENTS, mt as pruneEmptyDirs, n as activityFor, nt as trackAgentMemory, o as mcpPostStore, ot as checkFileSize, p as DEFAULT_WINDOW_MS, pt as sessionStartCore, q as getFileDesc, r as handlePre, rt as subagentCacheContext, s as mcpPreIntercept, st as countLoc, t as handleHook, tt as validateTeammateOutput, u as cacheQueryOf, ut as injectRules, v as detectDuplication, vt as devContext, w as seoPostToolUseResponse, wt as projectHash, x as lifecycleStdout, xt as promptSubmitContext, y as dryGate, yt as gitContext, z as generateEcosystemMap } from "../handle-D1hHqHvh.mjs";
+import { $ as saveApexState, A as trackSkillRead, At as saveSecurityState, B as writePluginMap, C as seoPostToolUse, Ct as taskContext, D as postTrackingSideEffects, Dt as normalizeEvent, E as securityAdvisory, Et as trackFile, F as dispatchLessons, G as mergeLines, H as isProject, I as lessonsFileFor, J as listChildren, K as countFiles, L as lessonsStateFileFor, M as dispatchLifecycle, Mt as securityStatePath, N as aipilotPostToolUse, Nt as todayUtc, O as trackWatchResearch, Ot as isoUtc, P as dispatchAipilot, Q as cleanupSession, R as cartoSessionStart, S as postEditContext, St as promptSubmitContext, T as dispatchMemory, Tt as projectHash, U as writeTree, V as generateProjectMap, W as loadEnriched, X as trackSessionChanges, Y as postEditTypescript, Z as validateRulesLoaded, _ as preCommitGate, _t as trimLogFile, a as recordActivity, at as validateSolidGate, b as extractSymbols, bt as projectContext, c as MCP_TTL_MS, ct as detectSolidProfile, d as isMcpTool, dt as readRules, et as logToolFailure, f as queryOf, ft as runSessionStartCleanups, g as gate, gt as removeOldFiles, h as TRIVIAL_BUDGET, ht as purgeTtlTree, i as respond, it as validateTailwind, j as trackEnrichment, jt as securityStateDir, k as trackMcpResearch, kt as loadSecurityState, l as WEBFETCH_TTL_MS, lt as solidDetectStart, m as REQUIRED_AGENTS, mt as pruneEmptyDirs, n as activityFor, nt as trackAgentMemory, o as mcpPostStore, ot as checkFileSize, p as DEFAULT_WINDOW_MS, pt as sessionStartCore, q as getFileDesc, r as handlePre, rt as subagentCacheContext, s as mcpPreIntercept, st as countLoc, t as handleHook, tt as validateTeammateOutput, u as cacheQueryOf, ut as injectRules, v as detectDuplication, vt as devContext, w as seoPostToolUseResponse, wt as defaultStateDir, x as lifecycleStdout, xt as claudeMdKey, y as dryGate, yt as gitContext, z as generateEcosystemMap } from "../handle-DzPjaPS-.mjs";
 //#region src/runtime/storage.ts
 /**
 * The project's single state dir (`<root>/.harness`) — neutral + harness-agnostic,
@@ -10,4 +10,4 @@ function harnessStateDir(root) {
 	return projectLayout(root).stateDir;
 }
 //#endregion
-export { DEFAULT_WINDOW_MS, MCP_TTL_MS, REQUIRED_AGENTS, TRIVIAL_BUDGET, WEBFETCH_TTL_MS, activityFor, aipilotPostToolUse, cacheQueryOf, cartoSessionStart, checkFileSize, claudeHome, cleanupSession, countFiles, countLoc, defaultStateDir, detectDuplication, detectSolidProfile, devContext, dispatchAipilot, dispatchLessons, dispatchLifecycle, dispatchMemory, dryGate, extractSymbols, fuseHarnessHome, fusengineCache, gate, generateEcosystemMap, generateProjectMap, getFileDesc, gitContext, handleHook, handlePre, harnessStateDir, injectRules, isMcpTool, isProject, isoUtc, lessonsFileFor, lessonsStateFileFor, lifecycleStdout, listChildren, loadEnriched, loadSecurityState, loadSessionState, logToolFailure, mcpPostStore, mcpPreIntercept, mergeLines, normalizeEvent, postEditContext, postEditTypescript, postTrackingSideEffects, preCommitGate, projectContext, projectHash, promptSubmitContext, pruneEmptyDirs, purgeTtlTree, queryOf, readRules, recordActivity, removeOldFiles, respond, runSessionStartCleanups, sanitizeSessionId, saveApexState, saveSecurityState, saveSessionState, securityAdvisory, securityStateDir, securityStatePath, seoPostToolUse, seoPostToolUseResponse, sessionStartCore, sessionStatePath, sessionsDir, solidDetectStart, subagentCacheContext, taskContext, todayUtc, trackAgentMemory, trackEnrichment, trackFile, trackMcpResearch, trackSessionChanges, trackSkillRead, trackWatchResearch, trimLogFile, validateRulesLoaded, validateSolidGate, validateTailwind, validateTeammateOutput, writePluginMap, writeTree };
+export { DEFAULT_WINDOW_MS, MCP_TTL_MS, REQUIRED_AGENTS, TRIVIAL_BUDGET, WEBFETCH_TTL_MS, activityFor, aipilotPostToolUse, cacheQueryOf, cartoSessionStart, checkFileSize, claudeHome, claudeMdKey, cleanupSession, countFiles, countLoc, defaultStateDir, detectDuplication, detectSolidProfile, devContext, dispatchAipilot, dispatchLessons, dispatchLifecycle, dispatchMemory, dryGate, extractSymbols, fuseHarnessHome, fusengineCache, gate, generateEcosystemMap, generateProjectMap, getFileDesc, gitContext, handleHook, handlePre, harnessStateDir, injectRules, isMcpTool, isProject, isoUtc, lessonsFileFor, lessonsStateFileFor, lifecycleStdout, listChildren, loadEnriched, loadSecurityState, loadSessionState, logToolFailure, mcpPostStore, mcpPreIntercept, mergeLines, normalizeEvent, postEditContext, postEditTypescript, postTrackingSideEffects, preCommitGate, projectContext, projectHash, promptSubmitContext, pruneEmptyDirs, purgeTtlTree, queryOf, readRules, recordActivity, removeOldFiles, respond, runSessionStartCleanups, sanitizeSessionId, saveApexState, saveSecurityState, saveSessionState, securityAdvisory, securityStateDir, securityStatePath, seoPostToolUse, seoPostToolUseResponse, sessionStartCore, sessionStatePath, sessionsDir, solidDetectStart, subagentCacheContext, taskContext, todayUtc, trackAgentMemory, trackEnrichment, trackFile, trackMcpResearch, trackSessionChanges, trackSkillRead, trackWatchResearch, trimLogFile, validateRulesLoaded, validateSolidGate, validateTailwind, validateTeammateOutput, writePluginMap, writeTree };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusengine/harness",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "Harness-agnostic toolkit for AI coding agents: runtime harness detection (Claude Code, Codex, Cursor, Cline, Gemini, Aider...), pure policy core (env config, project/framework detection, SOLID/file-size limits, APEX freshness, guard patterns, portable prompts), cache, project memory, ref routing, state/locks, statusline, per-harness adapters (Claude/Cursor/Cline/Gemini) and a cli-mode harness-check binary. Bun-native, with a built dist for Node + bundlers.",
   "type": "module",
   "module": "src/index.ts",