@fusengine/harness 0.1.55 → 0.1.57

package/dist/{handle-L4ZNmpwN.mjs → handle-DY79I4a8.mjs}

@@ -373,6 +373,68 @@ function oncePerWindow(key, windowMs, opts = {}) {
 	return true;
 }
 //#endregion
+//#region src/runtime/inject-budget.ts
+/**
+* @module inject-budget
+* Hard per-fragment ceiling for harness-PRODUCED context injections (lessons,
+* snapshot sections, APEX task context, cartographer/dev-context blocks) —
+* inspired by Codex's "ContextualUserFragment, no item > 10K tokens" pattern.
+* NEVER apply this to owner-authored content (CLAUDE.md/rules): that path is
+* a locked invariant (see the "owner invariant" tests in
+* test/dedup-inject.test.ts) and must always ship uncapped and in full.
+*
+* A real regression motivated this: MEMORY/LESSON.md's SessionStart injection
+* had grown to ~44k tokens with no per-fragment or total alarm, silently
+* bloating every SessionStart/SubagentStart turn.
+* @packageDocumentation
+*/
+/**
+* Hard cap per fragment, in characters. ~8000 chars ≈ 2000 tokens at the
+* conservative ~4 chars/token ratio for mixed FR/EN prose — the accepted
+* approximation absent a real tokenizer (cf. LangChain's `trim_messages`
+* fallback token_counter). Chosen because a SINGLE SessionStart already
+* stacks several harness fragments (lessons, snapshot, dev-context,
+* cartographer) on top of the uncapped CLAUDE.md block, and the known 11x
+* multi-plugin hook fan-out can multiply whatever ships — 2k tokens/fragment
+* keeps the harness-produced share bounded even under that fan-out, while
+* still leaving room for a few dozen useful lines of content.
+*/
+const FRAGMENT_CHAR_CAP = 8e3;
+/**
+* Cap `text` at {@link FRAGMENT_CHAR_CAP} characters, cutting at the last
+* newline within budget so no line is chopped mid-sentence. Text at or under
+* the cap is returned byte-identical (no-op). Over the cap, a single English
+* truncation line is appended so the reader knows content was dropped and
+* that the SOURCE FILE itself is untouched (only this injected view is cut).
+* @param label - Short identifier of the fragment (e.g. "lessons", "Git").
+* @param text - The candidate fragment body.
+* @returns `text` unchanged, or a truncated copy ending in the cut notice — always ≤ the cap.
+*/
+function capFragment(label, text) {
+	if (text.length <= 8e3) return text;
+	const totalLen = text.length;
+	const safeLabel = label.length <= 80 ? label : `${label.slice(0, 77)}...`;
+	const suffixFor = (keptLen) => `\n[truncated ${safeLabel}: kept ${keptLen} of ${totalLen} chars — source file unchanged]`;
+	const reserve = suffixFor(totalLen).length;
+	const budget = Math.max(0, FRAGMENT_CHAR_CAP - reserve);
+	const slice = text.slice(0, budget);
+	const lastNl = slice.lastIndexOf("\n");
+	const kept = (lastNl > 0 ? slice.slice(0, lastNl) : slice).trimEnd();
+	return kept + suffixFor(kept.length);
+}
+/**
+* One-line numeric recap of what a batch of fragments actually injected —
+* the owner-requested visibility so a silent blowup (like the 44k-token
+* lessons block) shows up as a number instead of going unnoticed.
+* @param fragments - The injected fragments (post-cap sizes).
+* @returns e.g. `"injected 5 fragments, 14.2k chars"`, or `"injected 0 fragments"` when empty.
+*/
+function budgetReport(fragments) {
+	if (fragments.length === 0) return "injected 0 fragments";
+	const total = fragments.reduce((sum, f) => sum + f.chars, 0);
+	return `injected ${fragments.length} fragments, ${(total / 1e3).toFixed(1)}k chars`;
+}
+//#endregion
 //#region src/runtime/inject-context.ts
 /**
 * Build the {@link oncePerWindow} key for the CLAUDE.md preamble gate. The
@@ -408,12 +470,14 @@ function promptSubmitContext(prompt, cwd) {
 /**
 * PreToolUse Task context injection: render the APEX sub-agent context as a
 * Claude `additionalContext` response when `.claude/apex/` exists, else "".
+* Harness-produced (not owner CLAUDE.md content), so it is subject to the
+* per-fragment {@link capFragment} budget — unlike {@link promptSubmitContext}.
 * @param cwd - Fallback project root when `CLAUDE_PROJECT_DIR` is unset.
 * @returns The native hook stdout (possibly empty).
 */
 function taskContext(cwd) {
 	const ctx = buildApexTaskInjection(process.env.CLAUDE_PROJECT_DIR ?? cwd);
-	return ctx ? contextResponse("PreToolUse", ctx) : "";
+	return ctx ? contextResponse("PreToolUse", capFragment("apex-task", ctx)) : "";
 }
 //#endregion
 //#region src/runtime/dev-context.ts
@@ -459,7 +523,7 @@ function projectContext(cwd) {
 * @returns The joined additionalContext text (possibly empty).
 */
 function devContext(cwd) {
-	return [...gitContext(cwd), ...projectContext(cwd)].join("\n");
+	return capFragment("dev-context", [...gitContext(cwd), ...projectContext(cwd)].join("\n"));
 }
 //#endregion
 //#region src/runtime/fs-cleanup.ts
@@ -1314,6 +1378,76 @@ function validateRulesLoaded(data, home = homedir()) {
 /** Fan-out dedup window (ms). The ~11 sibling hooks for one event land in <2s. */
 const BURST_DEDUP_MS = 2e3;
 //#endregion
+//#region src/runtime/notices.ts
+/**
+* @module notices
+* Compact, uniform "compliance" notices for the user-visible `systemMessage`
+* channel — the visual counterpart to the additionalContext-only gate/credit
+* signals, which land in agent-only context and stay invisible to the human in
+* the Claude Code UI (deny reasons show in red; these did not show at all).
+* Owner-reported gap: pass-notices existed in v0.1.49 for design gates, but
+* nothing surfaced skill credits, freshness, or the sniper reminder to the human.
+*
+* The text builders are pure. `refCreditNoticeFor` is the one exception — like
+* `pre-allow.ts`/`track-changes.ts` already do, it calls the existing
+* {@link oncePerWindow} file-backed cooldown gate directly, so a caller can drop
+* it straight into a PostToolUse loop without re-deriving the dedup. Rendering
+* onto a harness's native stdout always goes through the existing adapter
+* helpers (`respond`/`attachSystemMessage`); a harness with no `systemMessage`
+* channel (e.g. cline) silently drops the notice there (documented no-op, never
+* a crash) — nothing in this module renders directly.
+*/
+/** One compliance line: `✓ <gate> — <detail>` (detail omitted when empty). */
+function complianceNotice(gate, detail) {
+	return detail ? `✓ ${gate} — ${detail}` : `✓ ${gate}`;
+}
+/** One non-blocking requirement line: `⚠ <requirement> — <detail>`. */
+function requirementNotice(requirement, detail) {
+	return detail ? `⚠ ${requirement} — ${detail}` : `⚠ ${requirement}`;
+}
+/** Extract the skill name from a `.md` ref path (`.../skills/<name>/...`), or null when it isn't a skill reference (a banal doc Read — no notice). */
+function skillNameFromRefPath(path) {
+	return /skills\/([^/]+)\//.exec(path)?.[1] ?? null;
+}
+/** Notice for a SOLID/skill reference credited via an in-session Read, or null for a non-skill `.md`. */
+function refCreditedNotice(path) {
+	const skill = skillNameFromRefPath(path);
+	return skill ? complianceNotice("SOLID refs read", skill) : null;
+}
+/** Notice for the APEX freshness gate (explore+research) currently satisfied. */
+function evidenceFreshNotice() {
+	return complianceNotice("evidence fresh", "explore+research");
+}
+/** Notice mirroring the existing sniper-required additionalContext reminder. */
+function sniperRequiredNotice(fileName) {
+	return requirementNotice("sniper required", fileName);
+}
+/**
+* The one `✓ SOLID refs read (<skill>)` notice to show for this PostToolUse
+* call, or null. Scans the activities `activityFor` recorded from this event
+* for a skill-ref Read, deduped per (session, path) against the same burst
+* window as the sniper reminder — the ~11 sibling-plugin fan-out for one real
+* Read must never repeat it (lesson 2026-07-05 15:21).
+* @param activities - This event's recorded activities (only `ref` entries matter).
+* @param sessionId - Current session id (dedup scope).
+* @param now - Event clock.
+* @param dir - State-dir override for the dedup sidecar (tests MUST pass an
+*   isolated dir; production passes the per-project state dir).
+*/
+function refCreditNoticeFor(activities, sessionId, now, dir) {
+	for (const a of activities) {
+		if (a.kind !== "ref" || !a.path) continue;
+		const notice = refCreditedNotice(a.path);
+		if (!notice) continue;
+		if (!oncePerWindow(`ref-credited:${sessionId}:${a.path}`, 2e3, {
+			now,
+			dir
+		})) continue;
+		return notice;
+	}
+	return null;
+}
+//#endregion
 //#region src/runtime/lifecycle/track-changes.ts
 /** Code-file extensions tracked for sniper (mirrors track-session-changes.py). */
 const CODE_EXT$1 = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|vue|svelte|astro)$/;
@@ -1352,7 +1486,8 @@ function trackSessionChanges(sessionIdRaw, filePath, home = homedir(), now = Dat
 		now,
 		dir: sessionsDir(home)
 	})) return "";
-	return contextResponse("PostToolUse", `SNIPER VALIDATION REQUIRED: Code file '${basename(filePath)}' was modified. You MUST now run the sniper agent (fuse-ai-pilot:sniper) to validate this modification before continuing. This is mandatory per CLAUDE.md rules.`);
+	const fname = basename(filePath);
+	return attachSystemMessage(contextResponse("PostToolUse", `SNIPER VALIDATION REQUIRED: Code file '${fname}' was modified. You MUST now run the sniper agent (fuse-ai-pilot:sniper) to validate this modification before continuing. This is mandatory per CLAUDE.md rules.`), sniperRequiredNotice(fname));
 }
 //#endregion
 //#region src/runtime/lifecycle/post-edit-ts.ts
@@ -1698,1558 +1833,1918 @@ function harvestSubagentTrack(payload, cwd, now, baseDir = defaultStateDir(cwd))
 	} catch {}
 }
 //#endregion
-//#region src/runtime/lifecycle/task-completed.ts
-/** Code-file extensions audited on task completion (mirrors validate-task-solid.py). */
-const CODE_EXTENSIONS$2 = /* @__PURE__ */ new Set([
-	".ts",
-	".tsx",
-	".js",
-	".jsx",
-	".py",
-	".go",
-	".rs",
-	".java",
-	".php",
-	".cpp",
-	".c",
-	".rb",
-	".swift",
-	".kt",
-	".dart",
-	".vue",
-	".svelte",
-	".astro"
-]);
-/** Freshness multiple on `FUSE_ENFORCE_TTL_SEC` for receipts (no new env var); a tsc+test run precedes the "done" by more than one edit window. */
-const RECEIPT_TTL_MULTIPLIER = 5;
-/** The modified files that are code (by extension) — the receipt gate's trigger set. */
-function codeFiles(files) {
-	return files.filter((fp) => CODE_EXTENSIONS$2.has(extname(fp)));
-}
+//#region src/runtime/lifecycle/teammate-idle-check.ts
 /**
-* Refuse completion when code files changed but no fresh, passing verification
-* receipt (`tsc`/test, exit 0, zero failures, within TTL×{@link RECEIPT_TTL_MULTIPLIER})
-* exists in the signed track. TaskCompleted does NOT honor `decision:"block"`
-* (verified against the official hooks docs — `TeammateIdle/TaskCreated/
-* TaskCompleted` are excluded from that list); the documented stdout refusal is
-* `{"continue":false,"stopReason":…}`, which halts the teammate with the reason
-* shown to the user. Returns that JSON, or `null` when the session is clear.
+* @module teammate-idle-check
+* TeammateIdle anti-"false done": alongside the existing sniper suggestion
+* ({@link validateTeammateOutput}), verify that the files this teammate ANNOUNCED
+* (session-changes `modifiedFiles`) actually exist on disk. A claimed deliverable
+* missing on disk is a mechanically-verifiable false-done signal → warn the lead.
+* Deduped across the fan-out; silent when nothing is verifiable. Fail-open.
+*
+* Claude-Code-only: no equivalent `TeammateIdle` hook exists on Codex or Hermes,
+* so this handler is never reached through those adapters.
+* @packageDocumentation
 */
-function receiptGate(sid, files, now, stateDir) {
-	if (codeFiles(files).length === 0) return null;
-	const windowMs = resolveTtlSec(process.env) * 1e3 * RECEIPT_TTL_MULTIPLIER;
-	if (freshReceiptFromFile(trackFile(sid, stateDir), windowMs, now)) return null;
-	return JSON.stringify({
-		continue: false,
-		stopReason: "VERIFICATION RECEIPT REQUIRED: code files changed but no fresh passing tsc/test receipt exists. Run `bun test` + `tsc --noEmit` (exit 0, 0 failures) and re-complete."
-	});
+/** Re-warn about the same idle teammate at most once per 30s (fan-out + retries). */
+const IDLE_DEDUP_MS = 3e4;
+/** Announced files (session changes) that are ABSENT on disk (the false-done set). */
+function missingDeliverables(sessionId, home) {
+	return (loadSessionState(sessionId, home).changes?.modifiedFiles ?? []).filter((f) => typeof f === "string" && f !== "" && !existsSync(f));
 }
-/**
-* Re-count physical lines of every modified code file and collect SOLID
-* violations (`<basename>: <n> lines (max <max>)`) for those exceeding `max`.
-* @param files - Candidate modified file paths.
-* @param max - The SOLID line ceiling.
-* @returns The list of violation strings (empty when all files comply).
-*/
-function collectViolations(files, max) {
-	const violations = [];
-	for (const fp of files) {
-		if (!CODE_EXTENSIONS$2.has(extname(fp)) || !existsSync(fp)) continue;
-		try {
-			const lines = countLines(readFileSync(fp, "utf-8"));
-			if (lines > max) violations.push(`${basename(fp)}: ${lines} lines (max ${max})`);
-		} catch {}
+/** Pull the `additionalContext` body out of a `contextResponse` stdout ("" when empty/unparseable). */
+function bodyOf(stdout) {
+	if (!stdout) return "";
+	try {
+		return JSON.parse(stdout).hookSpecificOutput?.additionalContext ?? "";
+	} catch {
+		return "";
 	}
-	return violations;
 }
 /**
-* Handle TaskCompleted (ports `task-completed/validate-task-solid.py`, plus the
-* receipt gate). SOLID violations surface first as `SOLID VIOLATION`
-* additionalContext; once the files comply, {@link receiptGate} refuses a "done"
-* that has no fresh passing tsc/test receipt.
-* @param payload - The TaskCompleted payload (`task_id`, `task_subject`, `session_id`).
+* Handle TeammateIdle: merge the existing sniper suggestion with a missing-
+* deliverable warning (deduped) into one `additionalContext` response, or "" when
+* neither fires.
+* @param data - The raw TeammateIdle payload (`teammate_name`, `session_id`).
+* @param cwd - Project root (state dir for the dedup sidecar).
 * @param home - Home dir (defaults to `~`).
 * @param now - Clock (defaults to `Date.now()`).
-* @param stateDir - Track base dir (defaults to the cwd-derived state dir; matches `handleHook`).
-* @returns The native hook stdout, or `""` when the session is clean.
+* @returns The native hook stdout, or "".
 */
-function validateTaskSolid(payload, home = homedir(), now = Date.now(), stateDir = defaultStateDir(process.cwd())) {
-	const sid = sanitizeSessionId(payload.session_id ?? "unknown");
-	if (!sid) return "";
-	const files = loadSessionState(sid, home).changes?.modifiedFiles ?? [];
-	if (files.length === 0) return "";
-	const max = resolveMaxLines();
-	const violations = collectViolations(files, max);
-	if (violations.length === 0) return receiptGate(sid, files, now, stateDir) ?? "";
-	const taskId = String(payload.task_id ?? "");
-	return contextResponse("TaskCompleted", `SOLID VIOLATION in task '${String(payload.task_subject ?? "")}' (${taskId}): ${violations.length} file(s) exceed ${max} lines: ` + violations.slice(0, 5).join("; "));
+function teammateIdleContext(data, cwd, home = homedir(), now = Date.now()) {
+	const sniper = bodyOf(validateTeammateOutput(data, home));
+	const sessionId = sanitizeSessionId(data.session_id);
+	const teammate = String(data.teammate_name ?? data.team_name ?? "unknown");
+	let notice = "";
+	if (sessionId) {
+		const missing = missingDeliverables(sessionId, home);
+		if (missing.length > 0 && oncePerWindow(`idle:${sessionId}:${teammate}`, IDLE_DEDUP_MS, {
+			now,
+			dir: defaultStateDir(cwd)
+		})) notice = `Teammate '${teammate}' idle but expected deliverable(s) not found on disk: ${missing.slice(0, 5).join(", ")} — verify before treating as done.`;
+	}
+	const merged = [sniper, notice].filter(Boolean).join("\n\n");
+	return merged ? contextResponse("TeammateIdle", merged) : "";
 }
 //#endregion
-//#region src/runtime/lifecycle/cartographer/fs-util.ts
+//#region src/policy/lessons/trigger-index.ts
 /**
-* Filesystem helpers for the cartographer tree walk. Ports the fs parts of
-* `describe.py` (file desc) and `write_recursive.py` (children + counts).
+* 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;
+}
 /**
-* Read a file and derive its one-line description (frontmatter / heading /
-* comment). "" on any error or when nothing is found.
-* @param filePath - Absolute path to the file.
-* @returns The description, or "".
+* 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 getFileDesc(filePath) {
-	let text = "";
-	try {
-		text = readFileSync(filePath, "utf-8");
-	} catch {
-		return "";
+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
+		});
 	}
-	const suffix = extname(filePath);
-	const mdField = suffix === ".md" ? parseField(text, "description") : "";
-	return descFromText(suffix, text, mdField);
+	return out;
 }
+let memo = null;
 /**
-* Recursively count files whose relative path parts are all visible (no leading
-* "." or "_") and none excluded. Best-effort (partial count on errors).
-* @param dir - Directory to count under.
-* @param exclude - Directory/name set to skip.
-* @returns The file count.
+* 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 countFiles(dir, exclude) {
-	let total = 0;
-	try {
-		for (const e of readdirSync(dir, { withFileTypes: true })) {
-			if (e.name.startsWith(".") || e.name.startsWith("_") || exclude.has(e.name)) continue;
-			if (e.isDirectory()) total += countFiles(join(dir, e.name), exclude);
-			else if (e.isFile()) total += 1;
-		}
-	} catch {}
-	return total;
-}
-/** Absolute children of `source`, split into dirs/files, sorted by full path. */
-function listChildren(source, exclude) {
-	const dirs = [];
-	const files = [];
-	let entries;
+function lessonIndex(file) {
+	let key;
 	try {
-		entries = readdirSync(source, { withFileTypes: true });
+		key = `${file}:${statSync(file).mtimeMs}`;
 	} catch {
-		return {
-			dirs,
-			files
-		};
+		return [];
 	}
-	for (const e of entries) {
-		if (e.name.startsWith(".") || e.name.startsWith("_") || exclude.has(e.name)) continue;
-		const abs = join(source, e.name);
-		if (e.isDirectory()) dirs.push(abs);
-		else if (e.isFile()) files.push(abs);
+	if (memo?.key === key) return memo.entries;
+	let entries = [];
+	try {
+		entries = parseLessons(readFileSync(file, "utf-8"));
+	} catch {
+		entries = [];
 	}
-	return {
-		dirs: dirs.sort(),
-		files: files.sort()
+	memo = {
+		key,
+		entries
 	};
+	return entries;
 }
-//#endregion
-//#region src/runtime/lifecycle/cartographer/merge.ts
-/**
-* Index merge — preserves enriched descriptions across regenerations. Ports
-* `merge_index.py` (merge_lines + .enriched.json sidecar).
-*/
-/**
-* Load the `.enriched.json` sidecar's `entries` map for an output index.
-* @param outputIndexPath - Path to the index.md being written.
-* @returns The path→desc enrichment map (possibly empty).
-*/
-function loadEnriched(outputIndexPath) {
-	const sidecar = join(dirname(outputIndexPath), ".enriched.json");
+/** 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 {
-		if (!existsSync(sidecar)) return {};
-		return JSON.parse(readFileSync(sidecar, "utf-8")).entries ?? {};
+		return new RegExp(src, "i").test(s);
 	} catch {
-		return {};
+		return false;
 	}
 }
-/**
-* Merge freshly generated lines with prior descriptions: enriched sidecar wins,
-* else a longer pre-existing description is preserved.
-* @param newLines - The freshly generated index lines.
-* @param outputIndexPath - Path to the existing index.md (if any).
-* @returns The merged lines.
-*/
-function mergeLines(newLines, outputIndexPath) {
-	const enriched = loadEnriched(outputIndexPath);
-	const existingDescs = {};
-	if (existsSync(outputIndexPath)) try {
-		for (const line of readFileSync(outputIndexPath, "utf-8").split("\n")) {
-			const e = parseEntry(line);
-			if (e) existingDescs[e.path] = e.desc;
-		}
-	} catch {}
-	return newLines.map((line) => {
-		const e = parseEntry(line);
-		if (!e) return line;
-		if (e.path in enriched) return `${e.prefix}[${e.name}](${e.path}) — ${enriched[e.path]}`;
-		const old = existingDescs[e.path] ?? "";
-		if (old.length > e.desc.length) return `${e.prefix}[${e.name}](${e.path}) — ${old}`;
-		return line;
-	});
+/** 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)}`;
 }
-//#endregion
-//#region src/runtime/lifecycle/cartographer/write-tree.ts
-/**
-* Recursive index.md tree writer. Ports `write_recursive.py`.
-*/
 /**
-* Write `index.md` files mirroring `source` under `output`, recursing into
-* subdirectories. Directory lines carry a file-count hint; file lines carry a
-* derived description and link to the real absolute source path.
-* @param source - Absolute source directory.
-* @param output - Absolute output directory for the index tree.
-* @param back - Relative `← back` link target ("" at the root).
-* @param exclude - Directory/name set to skip.
+* 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 writeTree(source, output, back = "", exclude) {
-	const ex = exclude ?? /* @__PURE__ */ new Set();
-	mkdirSync(output, { recursive: true });
-	const { dirs, files } = listChildren(source, ex);
-	const lines = [`# ${basename(source)}\n`];
-	if (back) lines.push(`> [← back](${back})\n`);
-	const total = dirs.length + files.length;
-	let idx = 0;
-	for (const d of dirs) {
-		idx += 1;
-		const conn = idx === total ? "└──" : "├──";
-		const count = countFiles(d, ex);
-		const hint = count ? ` — ${count} files` : "";
-		lines.push(`${conn} [${basename(d)}/](./${basename(d)}/index.md)${hint}`);
-		writeTree(d, join(output, basename(d)), "../index.md", exclude);
-	}
-	for (const f of files) {
-		idx += 1;
-		const conn = idx === total ? "└──" : "├──";
-		const desc = getFileDesc(f);
-		const suffix = desc ? ` — ${desc}` : "";
-		lines.push(`${conn} [${basename(f)}](${f})${suffix}`);
+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;
 	}
-	const indexPath = join(output, "index.md");
-	writeFileSync(indexPath, mergeLines(lines, indexPath).join("\n") + "\n", "utf-8");
+	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/lifecycle/cartographer/project-map.ts
+//#region src/runtime/lifecycle/lessons/state.ts
 /**
-* Project map generation. Ports `generate_project_map.py` (project map only).
+* Per-project lessons paths. The `fuse-lessons` plugin stores its lessons under
+* `<root>/MEMORY/` (NOT the harness `.harness/memory/`), so these two path
+* helpers override the layout while ALL state/gitignore/throttle logic is
+* reused from `src/memory` (`setStateField`, `ensureMemoryGitignore`,
+* `readState`, `nowStamp`, `throttleMs`).
 */
-/** True when `dir` is a real directory. */
-function isDirectory(dir) {
-	try {
-		return statSync(dir).isDirectory();
-	} catch {
-		return false;
-	}
+/** Absolute `<root>/MEMORY/LESSON.md` — the curated, committable lessons file. */
+function lessonsFileFor(root) {
+	return join(root, "MEMORY", "LESSON.md");
 }
-/**
-* True when `dir` looks like a project root (has an indicator file) and is not
-* the home directory or filesystem root.
-* @param dir - Directory to test.
-* @returns Whether `dir` is a project root.
-*/
-function isProject(dir) {
-	const resolved = resolve(dir);
-	if (resolved === resolve(homedir()) || resolved === "/") return false;
-	for (const f of PROJECT_INDICATORS) if (existsSync(join(dir, f))) return true;
-	return false;
+/** Absolute `<root>/MEMORY/LESSON-archive.md` — cold storage for capped-out bullets. */
+function lessonsArchiveFileFor(root) {
+	return join(root, "MEMORY", "LESSON-archive.md");
 }
-/**
-* Generate the `.cartographer/project` index tree for `cwd` when it is a real
-* project directory. Always returns "" (no additionalContext emitted).
-* @param cwd - The working directory.
-* @param outputDir - Override for the output tree root.
-* @returns "" (side-effect only).
-*/
-function generateProjectMap(cwd, outputDir) {
-	const projectDir = resolve(cwd);
-	const out = outputDir ?? join(projectDir, ".cartographer", "project");
-	if (!isDirectory(projectDir)) return "";
-	if (!isProject(projectDir)) return "";
-	writeTree(projectDir, out, "", EXCLUDE_DIRS$1);
-	return "";
+/** Absolute `<root>/MEMORY/state.json` — machine-local throttle counter. */
+function lessonsStateFileFor(root) {
+	return join(root, "MEMORY", "state.json");
 }
 //#endregion
-//#region src/policy/cartographer/build-tree.ts
-const SECTION_ORDER = [
-	"agent",
-	"skill",
-	"command"
-];
+//#region src/tracking/one-shot-store.ts
+/** A fresh, empty state — always spread (`{ ...EMPTY }`) so the const is never shared. */
+const EMPTY = {
+	gates: {},
+	firstTry: 0,
+	corrected: 0,
+	pending: {},
+	updatedAt: 0
+};
 /**
-* Format grouped items with tree connectors and optional markdown links.
-* Skill sections link to `./skills/<name>/index.md`; other sections to
-* `./<folder>/<name>.md`; unlinked sections render the bare name.
-* @param prefix - The line prefix (indent + branch glyphs).
-* @param items - The `[name, desc]` pairs to render.
-* @param folder - The link folder ("" disables linking).
-* @param asDirs - Whether items link to a subdirectory `index.md`.
-* @returns The rendered lines.
+* Drop stale data: whole-state idle reset past the window, else per-entry prune of
+* gates/pending older than `windowMs`. Keeps the "7d" window honest, bounds size.
 */
-function printItems(prefix, items, folder, asDirs) {
-	return items.map(([name, desc], i) => {
-		const connector = i === items.length - 1 ? "└──" : "├──";
-		const safe = name.replace(/^\/+/, "");
-		let label = name;
-		if (folder && asDirs) label = `[${name}](./${folder}/${safe}/index.md)`;
-		else if (folder) label = `[${name}](./${folder}/${safe}.md)`;
-		const short = desc && desc !== "(no description)" ? ` — ${desc.slice(0, 80)}` : "";
-		return `${prefix}${connector} ${label}${short}`;
-	});
+function pruneState(s, now, windowMs) {
+	if (now - s.updatedAt >= windowMs) return { ...EMPTY };
+	const gates = {};
+	for (const [k, g] of Object.entries(s.gates)) if (now - g.lastTs < windowMs) gates[k] = g;
+	const pending = {};
+	for (const [k, p] of Object.entries(s.pending)) if (now - p.ts < windowMs) pending[k] = p;
+	return {
+		...s,
+		gates,
+		pending
+	};
 }
 /**
-* Build an indented tree from scanned items. The `hooks` row renders as a single
-* trailing `└── hooks: …` line; agents/skills/commands render as folder sections.
-* @param items - The scanned `[type, name, desc]` rows.
-* @param linked - When true, leaf names become markdown links.
-* @returns The joined tree text.
+* Record a deny for gate `title` on operation `op` (content-free tool identity):
+* bump the gate's deny count and mark `op` pending for a later fix.
 */
-function buildTree(items, linked = false) {
-	const groups = {};
-	let hooksLine = "";
-	for (const [typ, name, desc] of items) if (typ === "hooks") hooksLine = name;
-	else (groups[typ] ??= []).push([name, desc]);
-	const sections = SECTION_ORDER.filter((s) => s in groups);
-	if (hooksLine) sections.push("hooks");
-	const lines = [];
-	const total = sections.length;
-	for (let idx = 0; idx < total; idx++) {
-		const section = sections[idx] ?? "";
-		if (section === "hooks") {
-			lines.push(`└── hooks: ${hooksLine}`);
-			continue;
-		}
-		const isLast = idx === total - 1;
-		const folder = `${section}s`;
-		const prefix = isLast ? "└──" : "├──";
-		const subPrefix = isLast ? "    " : "│   ";
-		lines.push(`${prefix} ${folder}/`);
-		const linkFolder = linked ? folder : "";
-		const isDirSection = section === "skill";
-		lines.push(...printItems(subPrefix, groups[section] ?? [], linkFolder, linked && isDirSection));
-	}
-	return lines.join("\n");
+function applyDeny(s, title, op, now) {
+	const g = s.gates[title] ?? {
+		denies: 0,
+		corrected: 0,
+		lastTs: 0
+	};
+	return {
+		...s,
+		gates: {
+			...s.gates,
+			[title]: {
+				denies: g.denies + 1,
+				corrected: g.corrected,
+				lastTs: now
+			}
+		},
+		pending: {
+			...s.pending,
+			[op]: {
+				title,
+				ts: now
+			}
+		},
+		updatedAt: now
+	};
 }
-//#endregion
-//#region src/runtime/lifecycle/cartographer/write-plugin-map.ts
 /**
-* Per-plugin map writer (fs). Ports `write_plugin_map.py`: writes a level-2
-* `<plugin>/index.md` (indented linked tree) then recurses agents/skills/
-* commands into deeper index trees. Reuses `buildTree`, `mergeLines`, `writeTree`.
-*/
-/** True when `dir` is a real directory. */
-function isDir(dir) {
-	try {
-		return statSync(dir).isDirectory();
-	} catch {
-		return false;
+* Record an allow for a gateable `op`. A non-gateable allow (Read/Task/MCP) leaves
+* state untouched — it never counts and never clears a pending deny. Otherwise: a
+* pending deny → `corrected` (a fix, credited to the blocking gate); no pending →
+* `firstTry` (one-shot).
+*/
+function applyAllow(s, op, now, gateable) {
+	if (!gateable) return s;
+	const pend = s.pending[op];
+	if (pend) {
+		const g = s.gates[pend.title] ?? {
+			denies: 0,
+			corrected: 0,
+			lastTs: 0
+		};
+		const { [op]: _drop, ...pending } = s.pending;
+		return {
+			...s,
+			gates: {
+				...s.gates,
+				[pend.title]: {
+					...g,
+					corrected: g.corrected + 1,
+					lastTs: now
+				}
+			},
+			corrected: s.corrected + 1,
+			pending,
+			updatedAt: now
+		};
 	}
+	return gateable ? {
+		...s,
+		firstTry: s.firstTry + 1,
+		updatedAt: now
+	} : s;
 }
 /**
-* Write `<outputDir>/<pluginName>/index.md` (indented linked tree) and recurse
-* agents/skills/commands into their own index trees rooted there.
-* @param outputDir - The map root directory.
-* @param pluginName - Display name of the plugin (the index subfolder).
-* @param version - Plugin version ("" to omit).
-* @param items - The scanned `[type, name, desc]` rows.
-* @param pluginPath - Absolute source plugin directory (for recursion).
+* Compact injectable summary (one line); "" when there is nothing to report.
+* @returns e.g. `gates 7d: 88% one-shot (44/50 clean); SOLID file-size limit 4den/3fix`.
 */
-function writePluginMap(outputDir, pluginName, version, items, pluginPath) {
-	const pluginDir = join(outputDir, pluginName);
-	mkdirSync(pluginDir, { recursive: true });
-	const newLines = `# ${pluginName}${version ? ` (v${version})` : ""}\n\n${items.length ? buildTree(items, true) : "└── (empty)"}`.split("\n");
-	const indexPath = join(pluginDir, "index.md");
-	writeFileSync(indexPath, mergeLines(newLines, indexPath).join("\n") + "\n", "utf-8");
-	for (const section of [
-		"agents",
-		"skills",
-		"commands"
-	]) {
-		const src = join(pluginPath, section);
-		if (isDir(src)) writeTree(src, join(pluginDir, section), "../index.md");
-	}
+function formatSummary(s) {
+	const keys = Object.keys(s.gates);
+	const total = s.firstTry + s.corrected;
+	if (keys.length === 0 && total === 0) return "";
+	const head = total > 0 ? `${Math.round(s.firstTry / total * 100)}% one-shot (${s.firstTry}/${total} clean)` : "no clean pass yet";
+	const parts = keys.map((k) => ({
+		k,
+		g: s.gates[k]
+	})).sort((a, b) => b.g.denies - a.g.denies).map(({ k, g }) => `${k} ${g.denies}den/${g.corrected}fix`);
+	return `gates 7d: ${head}${parts.length ? `; ${parts.join("; ")}` : ""}`;
 }
 //#endregion
-//#region src/runtime/lifecycle/cartographer/ecosystem-map.ts
+//#region src/policy/deny-loop.ts
 /**
-* Ecosystem (plugin) map generation (fs). Ports `generate_map.py`: scans every
-* installed plugin into a level-1 `.cartographer/index.md` + per-plugin level-2+
-* trees, preserving enriched descriptions. Reuses `findMarketplacePlugins`,
-* `readPluginMeta`, `scanPlugin`, `mergeLines`, `writePluginMap`.
+* @module deny-loop
+* Pure anti-loop logic: hash a tool-call, decide if it repeats a prior deny, and
+* enrich the repeated block's message.
+*
+* The proprietary rule "NEVER propose the same fix twice" is prose a model under
+* pressure ignores. This makes it machine-enforced: when a call whose
+* `(tool + normalized input)` hash was ALREADY denied in-window is retried, the
+* harness keeps the deny but rewrites the message — `[REPEAT]` title, STOP
+* prefix, forced `research-expert` action. State + wiring live in the sidecar
+* store ({@link module:deny-loop-store}); this file is IO-free and pure.
+* @packageDocumentation
 */
-function pluginDirs(dir) {
-	let entries = [];
-	try {
-		entries = readdirSync(dir);
-	} catch {
-		return [];
-	}
-	return entries.filter((n) => !n.startsWith("_") && !n.startsWith(".")).filter((n) => {
-		try {
-			return statSync(join(dir, n)).isDirectory();
-		} catch {
-			return false;
-		}
-	}).sort((a, b) => a.localeCompare(b, "en"));
-}
-function utcStamp(now) {
-	return new Date(now).toISOString().slice(0, 16).replace("T", " ");
+/** Stable JSON: keys sorted at every depth so `{a,b}` and `{b,a}` hash identically. */
+function stableStringify(v) {
+	if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
+	if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+	const o = v;
+	return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(o[k])}`).join(",")}}`;
 }
 /**
-* Generate the plugin ecosystem map under `<pluginsDir>/.cartographer`.
-* @param now - Clock for the banner timestamp.
-* @param pluginsDirOverride - Override for the marketplace plugins directory.
-* @returns The map navigation context, or "".
+* Stable identity hash of a tool-call = tool name + normalized (key-sorted) input,
+* so re-ordered keys never mask a repeat.
+* @param tool - Tool name (e.g. "Write", "Bash").
+* @param input - Identifying tool input (filePath/content/command...).
+* @returns 8-char hex hash.
 */
-function generateEcosystemMap(now, pluginsDirOverride) {
-	const pluginsDir = resolve(pluginsDirOverride ?? findMarketplacePlugins());
-	try {
-		if (!statSync(pluginsDir).isDirectory()) return "";
-	} catch {
-		return "";
-	}
-	const outputDir = join(pluginsDir, ".cartographer");
-	mkdirSync(outputDir, { recursive: true });
-	const dirs = pluginDirs(pluginsDir);
-	const lines = [`# Ecosystem Map (${dirs.length} plugins)\n`, `> Auto-generated by cartographer — ${utcStamp(now)}\n`];
-	for (const name of dirs) {
-		const pluginPath = join(pluginsDir, name);
-		const [version, pkgName] = readPluginMeta(pluginPath);
-		const display = pkgName || name;
-		const items = scanPlugin(pluginPath);
-		const agents = items.filter(([t]) => t === "agent").map(([, n]) => n);
-		const ver = version ? ` (v${version})` : "";
-		lines.push(`- [${display}](./${display}/index.md)${ver} → ${agents.length ? agents.join(", ") : "(no agents)"}`);
-		writePluginMap(outputDir, display, version, items, pluginPath);
-		writePluginMap(pluginPath, ".cartographer", version, items, pluginPath);
-	}
-	const indexPath = join(outputDir, "index.md");
-	writeFileSync(indexPath, mergeLines(lines, indexPath).join("\n") + "\n", "utf-8");
-	return `Project map: .cartographer/project/index.md — navigate project files. Plugin skills map: ${outputDir}/index.md — navigate agent skills. Branches link to deeper index.md, leaves link to real files.`;
+function denyHash(tool, input) {
+	return hashText(`${tool}\n${stableStringify(input)}`);
 }
-//#endregion
-//#region src/runtime/lifecycle/cartographer/session-start.ts
 /**
-* Cartographer SessionStart handler. Ports BOTH halves of the Python maps:
-* `generate_project_map.py` (regenerate `.cartographer/project`) and
-* `generate_map.py` (regenerate the plugin ecosystem map), emitting the
-* navigation context from the latter as additionalContext.
+* Pure loop check: given the already-pruned in-window map, compute the running
+* count for `hash` and whether it repeats (count > 1). No IO — the caller persists.
+*
+* When `dedupMs` is set (>0) and an identical prior deny landed within that
+* window, the current call is a sibling hook echoing the SAME event (see
+* {@link module:burst-window}): it returns the prior verdict VERBATIM with
+* `deduped:true` and does NOT bump the count, so all N fan-out processes agree
+* on one number instead of counting to N. Absent `dedupMs` (mono-process
+* callers / unit tests) the historical increment-every-time behaviour holds.
+* @param hash - {@link denyHash}-derived map key of the current call.
+* @param priorDenies - The `{ hash -> DenyEntry }` map, pruned to `now`/`windowMs`.
+* @param opts - Clock + window, plus an optional burst-dedup window.
+* @returns `{ isRepeat, count, hash, deduped? }`.
 */
+function denyLoopCheck(hash, priorDenies, opts) {
+	const prev = priorDenies[hash];
+	if (!(prev && typeof prev.lastTs === "number" && opts.now - prev.lastTs < opts.windowMs)) return {
+		isRepeat: false,
+		count: 1,
+		hash
+	};
+	if ((opts.dedupMs ?? 0) > 0 && opts.now - prev.lastTs < (opts.dedupMs ?? 0)) return {
+		isRepeat: prev.count > 1,
+		count: prev.count,
+		hash,
+		deduped: true
+	};
+	const count = prev.count + 1;
+	return {
+		isRepeat: count > 1,
+		count,
+		hash
+	};
+}
 /**
-* Resolve the marketplace plugins dir from `CLAUDE_PLUGIN_ROOT`, mirroring the
-* Python hook which passes `${CLAUDE_PLUGIN_ROOT}/..` to `generate_map.py`.
-* @returns The plugins dir (env `/..`), or `undefined` to fall back to auto-detect.
+* Enrich a REPEATED block prompt — a NEW object, never a mutation (the input may
+* be a shared const like FAIL_CLOSED). The decision stays `block`; only the
+* message changes, so every harness renders it through the same adapter.
+* @param prompt - The original block prompt.
+* @param count - The running identical-deny count (n).
+* @returns A block prompt with `[REPEAT]` title, STOP-prefixed reason, forced research action.
 */
-function pluginsDirFromEnv() {
-	const root = process.env.CLAUDE_PLUGIN_ROOT;
-	return root ? resolve(root, "..") : void 0;
+function enrichRepeatDeny(prompt, count) {
+	const stop = `Identical attempt #${count} already denied for the same reason. STOP: do not retry this same call. `;
+	const action = "Launch fuse-ai-pilot:research-expert to find a DIFFERENT approach";
+	return {
+		...prompt,
+		title: prompt.title.startsWith("[REPEAT]") ? prompt.title : `[REPEAT] ${prompt.title}`,
+		reason: stop + prompt.reason,
+		actions: [action, ...prompt.actions ?? []]
+	};
 }
+//#endregion
+//#region src/tracking/one-shot-dedup.ts
 /**
-* Regenerate the project map + plugin ecosystem map for `cwd` on SessionStart.
-* Emits the ecosystem navigation context as additionalContext (or "").
-* @param cwd - The working directory.
-* @param now - Clock for the ecosystem map banner timestamp.
-* @returns The SessionStart additionalContext response, or "".
+* @module one-shot-dedup
+* Burst-dedup guard for the one-shot metric ({@link module:one-shot}).
+*
+* ONE Claude tool event fans out to ~11 sibling plugin-hook processes, each
+* calling {@link recordOneShot}; without this the metric would count a single
+* deny/allow ~11×. Reuses the proven {@link oncePerWindow} cooldown sidecar:
+* the FIRST process in the {@link module:burst-window} window mutates the
+* metric, the rest skip. The dedup key includes the outcome KIND (deny-title vs
+* allow) so a deny and its later fix — different kinds — are never folded into
+* each other. No `sessionId` → always the first (mono-process + unit-test
+* parity; a burst can only exist when a real session drives the fan-out).
+* @packageDocumentation
 */
-function cartoSessionStart(cwd, now = Date.now()) {
-	generateProjectMap(cwd);
-	const ctx = generateEcosystemMap(now, pluginsDirFromEnv());
-	return ctx ? contextResponse("SessionStart", ctx) : "";
+/**
+* True when this `(op, kind)` is the FIRST of its burst for the session — the
+* process that should actually mutate the metric. Sibling processes firing the
+* SAME event within {@link BURST_DEDUP_MS} return false and skip the write.
+* @param op - Content-free operation key ({@link denyHash}("op", …)).
+* @param kind - Outcome discriminator (`deny:<title>` or `allow`).
+* @param opts - Clock + state dir + optional session id.
+* @returns `true` to apply the record, `false` to skip (already counted).
+*/
+function burstFirst(op, kind, opts) {
+	const sid = opts.sessionId?.trim();
+	if (!sid) return true;
+	return oncePerWindow(`oneshot:${sid}:${op}:${kind}`, BURST_DEDUP_MS, {
+		now: opts.now,
+		dir: opts.dir
+	});
 }
 //#endregion
-//#region src/runtime/lifecycle/aipilot/lesson-parse.ts
-/** Milliseconds in a day. */
-const DAY_MS = 864e5;
-/** Case-sensitive decision-time tag line (`[TRIGGERS …]`) — opus-lessons format. */
-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));
-}
-/** True when a block carries a `[TRIGGERS …]` continuation line. */
-function hasTrigger(b) {
-	return b.raw.some((l) => TRIG.test(l.trim()));
-}
-/** Split content 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);
+//#region src/tracking/one-shot.ts
+/**
+* @module one-shot
+* Sidecar store + gate wiring for the per-gate one-shot metric.
+*
+* STATE — a standalone sidecar (`one-shot.json`) in the same per-project state dir
+* as the session track, mirroring {@link module:deny-loop-store} (atomicWrite,
+* prune-by-window, fail-safe). A write error NEVER changes a gate decision nor its
+* prompt — metrics are pure observation.
+*
+* KEY — the operation identity is content-FREE (`tool + filePath/command`): a fix
+* changes the content, so a content hash would make every retry a new op and hide
+* the deny→allow transition this metric exists to see. The pure model lives in
+* {@link module:one-shot-store}; this file is the only IO surface.
+* @packageDocumentation
+*/
+/** Sidecar basename under the per-project state dir. */
+const SIDECAR$1 = "one-shot.json";
+/** Retention window: 7 days. Aggregates and pending denies older than this are pruned. */
+const WINDOW_MS = 10080 * 60 * 1e3;
+/** Load the state, or a fresh copy when missing/corrupt. */
+function loadState(path) {
+	try {
+		if (!existsSync(path)) return { ...EMPTY };
+		const d = JSON.parse(readFileSync(path, "utf8"));
+		return d && typeof d === "object" && !Array.isArray(d) ? {
+			...EMPTY,
+			...d
+		} : { ...EMPTY };
+	} catch {
+		return { ...EMPTY };
 	}
-	return {
-		preamble,
-		blocks
-	};
 }
-//#endregion
-//#region src/runtime/lifecycle/aipilot/lesson-archive.ts
 /**
-* Stage 1 — cap→archive split for LESSON.md. When deduped bullets exceed CAP the
-* OLDEST excess is MOVED (never deleted) to LESSON-archive.md, EXCEPT a
-* `[TRIGGERS …]` bullet younger than STALE_DAYS: archiving it would blind the
-* PreToolUse trigger index (src/policy/lessons/trigger-index reads LESSON.md), so
-* it stays even past the cap. Pure: this module decides the partition and renders
-* the archive block; the fail-safe, archive-first file write is the caller's job.
+* Record a gate outcome: a `block` is a deny for its gate title; a `null` allow is
+* a fix (if the op was pending) or a one-shot (if gateable). `ask`/`inform` are
+* neither and are skipped. Fails silently — a metric write NEVER affects a decision.
+*
+* The op key is tool-INDEPENDENT (`filePath`/`command` only, constant `"op"` tool):
+* a deny (a `Write`) and its fix (an `Edit`) on the same file must link.
+* @param prompt - The gate's outcome (block, allow=null, or ask/inform).
+* @param input - Identifying tool input (content decides gateability only).
+* @param opts - Clock + state dir.
 */
-/** Sort key: undated bullets sort oldest, so malformed entries archive first. */
-function age(b) {
-	return Number.isNaN(b.ts) ? -Infinity : b.ts;
-}
-/** A TRIGGERS bullet is protected from archival until older than STALE_DAYS. */
-function isProtected(b, staleBefore) {
-	return hasTrigger(b) && !(b.ts <= staleBefore);
+function recordOneShot(prompt, input, opts) {
+	try {
+		if (prompt && prompt.kind !== "block") return;
+		const op = denyHash("op", {
+			filePath: input.filePath,
+			command: input.command
+		});
+		if (!burstFirst(op, prompt ? `deny:${prompt.title}` : "allow", opts)) return;
+		const path = join(opts.dir, SIDECAR$1);
+		let s = pruneState(loadState(path), opts.now, WINDOW_MS);
+		s = prompt ? applyDeny(s, prompt.title, op, opts.now) : applyAllow(s, op, opts.now, input.content != null || input.command != null);
+		atomicWrite(path, JSON.stringify(s));
+	} catch {}
 }
 /**
-* Partition deduped `blocks` (newest-first file order) into the bullets that
-* stay in LESSON.md and the oldest excess to archive. Archives only enough to
-* reach CAP, skipping protected TRIGGERS bullets (so the file MAY stay slightly
-* over cap by design). Order is preserved in both halves; `keep ∪ archive` is
-* exactly `blocks` with no loss and no mutation.
-* @param blocks - Deduped bullets, newest first.
-* @param now - Clock (ms) for the STALE_DAYS protection window.
-* @returns `{ keep, archive }` — a lossless partition of `blocks`.
+* Compact, injection-ready one-shot summary for the project rooted at `cwd`. The
+* state dir is derived EXACTLY like the runtime writer ({@link defaultStateDir},
+* mirroring `handle.ts` `trackFile(sid, defaultStateDir(cwd))`), so the file read
+* here is the same one {@link recordOneShot} wrote. "" when no data or read error.
+* @param cwd - The project working directory (Claude `cwd`), NOT the state dir.
+* @returns One line, e.g. `gates 7d: 88% one-shot (44/50 clean); ...`, or "".
 */
-function splitAtCap(blocks, now) {
-	if (blocks.length <= 50) return {
-		keep: blocks,
-		archive: []
-	};
-	const staleBefore = now - 90 * DAY_MS;
-	const oldestFirst = [...blocks].sort((a, b) => age(a) - age(b));
-	const toArchive = /* @__PURE__ */ new Set();
-	let excess = blocks.length - 50;
-	for (const b of oldestFirst) {
-		if (excess <= 0) break;
-		if (isProtected(b, staleBefore)) continue;
-		toArchive.add(b);
-		excess--;
+function oneShotSummary(cwd) {
+	try {
+		return formatSummary(pruneState(loadState(join(defaultStateDir(cwd), SIDECAR$1)), Date.now(), WINDOW_MS));
+	} catch {
+		return "";
 	}
-	return {
-		keep: blocks.filter((b) => !toArchive.has(b)),
-		archive: blocks.filter((b) => toArchive.has(b))
-	};
 }
+//#endregion
+//#region src/tracking/one-shot-failure.ts
 /**
-* Render `archive` bullets as a dated block to PREPEND to LESSON-archive.md
-* (newest archive session on top). Bullets are emitted BYTE-IDENTICAL (raw lines
-* rejoined) — zero mutation, so the move stays reversible/auditable.
-* @param archive - Bullets chosen by {@link splitAtCap}.
-* @param now - Clock (ms) for the archival header date.
-* @returns The block text (trailing newline), or "" when nothing is archived.
+* @module one-shot-failure
+* PostToolUseFailure tally for the one-shot sidecar. A pure per-tool counter
+* ({@link applyFailure}) plus its burst-deduped IO writer ({@link recordFailure}),
+* kept out of {@link module:one-shot-store} so that file stays under the SOLID
+* size limit. Reuses the SAME sidecar, prune window, and burst-dedup as
+* {@link module:one-shot} — failures never touch the deny/allow gate rate.
+* @packageDocumentation
 */
-function formatArchive(archive, now) {
-	if (archive.length === 0) return "";
-	return `${`<!-- archived ${new Date(now).toISOString().slice(0, 10)}: ${archive.length} bullet(s) moved from LESSON.md at cap 50 -->`}\n${archive.map((b) => b.raw.join("\n")).join("\n\n")}\n`;
-}
-//#endregion
-//#region src/runtime/lifecycle/aipilot/curate-lessons.ts
 /**
-* Stage-0 mechanical, LLM-free dedup of MEMORY/LESSON.md bullets + cap→archive
-* orchestration. Strict-dedup near-identical bullets (keep newest, `[TRIGGERS …]`
-* preserved), then hand the deduped set to lesson-archive's cap split. Returns the
-* rewritten LESSON.md content, the archive block to move out, and a human report.
-* Pure: all file I/O (archive-first, fail-safe) lives in the dispatch caller.
+* Bump the per-tool failure count. Orthogonal to gates/pending, so it can never
+* distort the one-shot rate.
+* @param s - Current state.
+* @param tool - The failing tool name (`unknown` when absent).
+* @param now - Clock.
+* @returns The next state with `failures[tool]` incremented.
 */
-const SIM_THRESHOLD = .8;
-const MIN_TOKENS = 4;
-/** Report lines for bullets older than STALE_DAYS whose only cited path is gone. */
-function staleReport(blocks, now, root) {
-	const cutoff = now - 90 * DAY_MS;
-	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)} — missing path(s): ${paths.join(", ")}`];
-	});
-}
-/** Strict-dedup: keep the newest of each near-identical pair (TRIGGERS carried over). Returns kept blocks + merge report lines. */
-function dedup(blocks) {
-	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(`merged: kept ${(win.raw[0] ?? "").slice(0, 60)} · dropped ${(drop.raw[0] ?? "").slice(0, 60)}`);
-	}
+function applyFailure(s, tool, now) {
 	return {
-		kept,
-		fused
+		...s,
+		failures: {
+			...s.failures ?? {},
+			[tool]: (s.failures?.[tool] ?? 0) + 1
+		},
+		updatedAt: now
 	};
 }
 /**
-* Dedup LESSON.md bullets, then archive the oldest excess over CAP (via
-* lesson-archive). `content` is byte-identical to the input when nothing is
-* deduped or archived. The `archive` block (possibly "") is what the caller must
-* PREPEND to LESSON-archive.md, archive-first, before writing `content`.
-* @param content - Raw LESSON.md text.
-* @param now - Clock (ms) for stale/archival windows.
-* @param root - Project root, for resolving cited paths in the stale report.
-* @returns The rewritten content, the archive block, and the report.
+* Persist a PostToolUseFailure into the one-shot sidecar, burst-deduped across the
+* ~11-process fan-out (same window/store as {@link recordOneShot}). Fail-safe: a
+* write error never propagates out of the hook.
+* @param tool - The failing tool name.
+* @param opts - Clock + state dir + optional session id (arms the burst dedup).
 */
-function curateLessons(content, now, root = process.cwd()) {
-	const { preamble, blocks } = parse(content);
-	const { kept, fused } = dedup(blocks);
-	const { keep, archive } = splitAtCap(kept, now);
-	const rebuilt = fused.length > 0 || archive.length > 0 ? `${preamble}\n${keep.map((b) => b.raw.join("\n")).join("\n\n")}\n` : content;
-	const capReport = archive.length ? [`${kept.length} bullets (> 50) — ${archive.length} oldest archived → LESSON-archive.md`] : [];
-	const report = [
-		...fused,
-		...capReport,
-		...staleReport(blocks, now, root)
-	].join("\n");
-	return {
-		content: rebuilt,
-		archive: formatArchive(archive, now),
-		report
-	};
-}
-/** The `[YYYY-MM-DD HH:MM]` (or date-only) stamp of a bullet, "" if absent. */
-function stamp(block) {
-	return (block.raw[0] ?? "").match(/\[(\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2})?)\]/)?.[1] ?? "";
-}
-/** Bullet text: raw lines joined, leading "- ", date stamp & TRIGGERS lines stripped. */
-function bodyText(block) {
-	return block.raw.filter((l) => !/^\s*\[TRIGGERS\s/.test(l)).join(" ").replace(/^-\s*/, "").replace(/\[\d{4}-\d{2}-\d{2}[^\]]*\]\s*/, "").trim();
-}
-/** First sentence of `s` (split on a period + whitespace), whole string if none. */
-function firstSentence(s) {
-	return (s.split(/(?<=\.)\s/)[0] ?? s).trim();
+function recordFailure(tool, opts) {
+	try {
+		if (!burstFirst(`fail:${tool}`, "failure", opts)) return;
+		const path = join(opts.dir, SIDECAR$1);
+		const next = applyFailure(pruneState(loadState(path), opts.now, WINDOW_MS), tool, opts.now);
+		atomicWrite(path, JSON.stringify(next));
+	} catch {}
 }
+//#endregion
+//#region src/runtime/lifecycle/failure-lesson.ts
 /**
-* Distil the actionable rule from a bullet body. With no "→" the whole bullet is
-* the rule → its first sentence. Otherwise the rule is everything after the FIRST
-* "→"; among its arrow-delimited segments (trimmed, empty dropped) take the first
-* sentence of the LONGEST — the information-dense clause, not whichever short
-* aside the author appended last. When that clause is under {@link MIN_RULE}
-* chars, fall back to the first sentence of the WHOLE rule part (never the
-* narrative), so a short trailing segment never yields an illegible stub yet a
-* legitimately terse rule is still shown intact.
+* @module failure-lesson
+* PostToolUseFailure handler: keep the failure log, record the failure in the
+* one-shot metric, and inject the ONE most-specific lesson whose `error:` trigger
+* matches the failure message — reusing the PreToolUse {@link lessonFor} index and
+* its cooldown (idempotent under the ~11-process fan-out). Fail-open throughout.
+*
+* Claude-Code-only: no equivalent `PostToolUseFailure` hook exists on Codex or
+* Hermes, so this handler is never reached through those adapters.
+* @packageDocumentation
 */
-function distillRule(text) {
-	const arrow = text.indexOf("→");
-	if (arrow < 0) return firstSentence(text);
-	const rulePart = text.slice(arrow + 1);
-	const rule = firstSentence(rulePart.split("→").map((s) => s.trim()).filter(Boolean).reduce((a, b) => b.length > a.length ? b : a, ""));
-	return rule.length >= 40 ? rule : firstSentence(rulePart);
-}
-/** Collapse one older bullet to `- [date] <rule>`: {@link distillRule}, capped. */
-function compressBullet(block) {
-	let rule = distillRule(bodyText(block));
-	if (rule.length > 200) rule = `${rule.slice(0, 199).trimEnd()}…`;
-	const date = stamp(block);
-	return `- ${date ? `[${date}] ` : ""}${rule}`;
+/** The failure message across the documented `error` field and defensive fallbacks; "" when none. */
+function failureError(data) {
+	const raw = data.error ?? data.tool_error ?? data.tool_output;
+	if (typeof raw === "string") return raw;
+	return raw != null ? JSON.stringify(raw) : "";
 }
 /**
-* Build the compressed injection body for `content`. The preamble comments are
-* dropped (format docs, noise for the reader); the `recentFull` newest bullets
-* stay whole, every older bullet becomes one distilled rule-line.
-* @param content - Raw LESSON.md text.
-* @param recentFull - Count of newest bullets to keep verbatim.
-* @returns The compressed block (bullets only), or the trimmed content when there are no bullets.
-*/
-function compressInjection(content, recentFull = 10) {
-	const { blocks } = parse(content);
-	if (blocks.length === 0) return content.trim();
-	const full = blocks.slice(0, recentFull).map((b) => b.raw.join("\n"));
-	const rest = blocks.slice(recentFull).map(compressBullet);
-	return [...full, ...rest].join("\n");
-}
-//#endregion
-//#region src/runtime/lifecycle/lessons/state.ts
-/**
-* Per-project lessons paths. The `fuse-lessons` plugin stores its lessons under
-* `<root>/MEMORY/` (NOT the harness `.harness/memory/`), so these two path
-* helpers override the layout while ALL state/gitignore/throttle logic is
-* reused from `src/memory` (`setStateField`, `ensureMemoryGitignore`,
-* `readState`, `nowStamp`, `throttleMs`).
+* Handle PostToolUseFailure: log the failure, tally it per tool, and inject the
+* matching `error:`-triggered lesson as `additionalContext` ("" when none).
+* @param data - The raw PostToolUseFailure payload (`tool_name`, `error`, `session_id`).
+* @param cwd - Project root.
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+* @param once - Cooldown gate (injected for tests; defaults to {@link oncePerWindow}).
+* @returns The native hook stdout, or "" when nothing to inject.
 */
-/** Absolute `<root>/MEMORY/LESSON.md` — the curated, committable lessons file. */
-function lessonsFileFor(root) {
-	return join(root, "MEMORY", "LESSON.md");
-}
-/** Absolute `<root>/MEMORY/LESSON-archive.md` — cold storage for capped-out bullets. */
-function lessonsArchiveFileFor(root) {
-	return join(root, "MEMORY", "LESSON-archive.md");
-}
-/** Absolute `<root>/MEMORY/state.json` — machine-local throttle counter. */
-function lessonsStateFileFor(root) {
-	return join(root, "MEMORY", "state.json");
+function failureLessonContext(data, cwd, home = homedir(), now = Date.now(), once = oncePerWindow) {
+	logToolFailure(data, home, now);
+	const tool = typeof data.tool_name === "string" ? data.tool_name : "unknown";
+	const sessionId = typeof data.session_id === "string" ? data.session_id : void 0;
+	try {
+		recordFailure(tool, {
+			now,
+			dir: defaultStateDir(cwd),
+			sessionId
+		});
+	} catch {}
+	const errorMsg = failureError(data);
+	if (!errorMsg) return "";
+	const lesson = lessonFor("", {}, {
+		file: lessonsFileFor(projectRoot(cwd)),
+		once,
+		prevError: errorMsg
+	});
+	return lesson?.reason ? contextResponse("PostToolUseFailure", lesson.reason) : "";
 }
 //#endregion
-//#region src/memory/session-roots.ts
+//#region src/runtime/lifecycle/snapshot/git.ts
 /**
-* Session-scoped lessons roots registry. The flat {@link module:memory/registry}
-* keeps ONE global list of pending roots — correct mono-session, but wrong with
-* several concurrent Claude Code sessions: at Stop, one session lists (and, by
-* bumping the throttle, STEALS) another session's pending lesson on a project it
-* never touched. This registry keys "which project got code edits, and was its
-* Stop reminder already fired" by `session_id`, so each Stop sees and consumes
-* ONLY its own roots. Stored at `$HOME/.fuse-harness/cache/lessons/session-roots.json`;
-* non-fatal on any I/O failure (a missed reminder never blocks a session).
+* Run a git subcommand at `root` with a short timeout, returning trimmed stdout.
+* Uses `node:child_process` (the Bun shell can hang on some git plumbing) and
+* swallows every failure — a non-repo, missing git, or timeout yields `""` so
+* the caller omits the section instead of throwing inside the hook.
+* @param root - Directory to run git in.
+* @param args - The git args (e.g. `"log --oneline -3"`).
+* @returns Trimmed stdout, or `""` on any error.
 */
-/** Registry path (rel. home) + stale-bucket purge horizon (bounds growth). */
-const SUBPATH = ".fuse-harness/cache/lessons/session-roots.json";
-const PURGE_MS = 10080 * 60 * 1e3;
-/** Absolute registry path, or null when home is unusable. */
-function file(home) {
-	const h = home?.trim();
-	return h && h.startsWith("/") ? `${h}/${SUBPATH}` : null;
-}
-/** Read the registry; missing/corrupt/legacy (array) shapes collapse to `{}`. */
-function read(home) {
-	const f = file(home);
-	if (!f) return {};
+function git(root, args) {
 	try {
-		const parsed = JSON.parse(readFileSync(f, "utf8"));
-		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+		return execSync(`git ${args}`, {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 150,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
 	} catch {
-		return {};
+		return "";
 	}
 }
-/** Purge stale buckets, then atomically persist (unique tmp + rename). Non-throwing. */
-function write(home, reg, now) {
-	const f = file(home);
-	if (!f) return;
-	for (const [sid, entry] of Object.entries(reg)) if (!entry || now - (entry.updatedAt ?? 0) > PURGE_MS) delete reg[sid];
-	try {
-		mkdirSync(dirname(f), { recursive: true });
-		atomicWrite(f, JSON.stringify(reg));
-	} catch {}
-}
-/** Record `field` for `(sid, root)`, refreshing the purge cursor. `home` defaults to `$HOME`. */
-function markSessionRoot(sid, root, field, value, home = process.env.HOME) {
-	const reg = read(home);
-	const prev = reg[sid];
-	const entry = prev && typeof prev.roots === "object" && prev.roots !== null ? prev : {
-		updatedAt: value,
-		roots: {}
-	};
-	const mark = entry.roots[root] ?? {
-		editedAt: 0,
-		remindedAt: 0
-	};
-	entry.roots[root] = {
-		...mark,
-		[field]: value
+/** Count staged/unstaged/untracked files from porcelain v1 output (skips the `##` branch line). */
+function countWip(porcelain) {
+	const w = {
+		staged: 0,
+		unstaged: 0,
+		untracked: 0
 	};
-	entry.updatedAt = value;
-	reg[sid] = entry;
-	write(home, reg, value);
+	for (const line of porcelain.split("\n")) {
+		if (!line || line.startsWith("#")) continue;
+		if (line.startsWith("??")) {
+			w.untracked++;
+			continue;
+		}
+		const x = line[0], y = line[1];
+		if (x && x !== " " && x !== "?") w.staged++;
+		if (y === "M" || y === "D") w.unstaged++;
+	}
+	return w;
+}
+/** Parse the current branch from the leading `## branch...upstream` porcelain line. */
+function parseBranch(porcelain) {
+	const head = porcelain.split("\n")[0] ?? "";
+	if (!head.startsWith("## ")) return "";
+	const rest = head.slice(3);
+	const dots = rest.indexOf("...");
+	return (dots >= 0 ? rest.slice(0, dots) : rest).split(" ")[0] ?? "";
 }
 /**
-* Roots of `sid` with an unsaved code edit past the `window`; each returned
-* root's `remindedAt` is bumped to `now` so the reminder fires at most once per
-* window and is consumed ONLY by this session. `home` defaults to `$HOME`.
+* Collect a compact git reconciliation section for `root`: current branch, the
+* last three commits (oneline), and staged/unstaged/untracked WIP counts. When
+* `root` is not a git repo (status fails) the whole section is omitted (`""`).
+* @param root - The project/repo root.
+* @returns The rendered git section body, or `""` when not a repo.
 */
-function collectSessionPending(sid, now, window, home = process.env.HOME) {
-	const reg = read(home);
-	const entry = reg[sid];
-	if (!entry || typeof entry.roots !== "object" || entry.roots === null) return [];
-	const pending = [];
-	for (const [root, mark] of Object.entries(entry.roots)) {
-		if (mark.editedAt <= mark.remindedAt) continue;
-		if (now - mark.remindedAt < window) continue;
-		pending.push(root);
-		entry.roots[root] = {
-			...mark,
-			remindedAt: now
-		};
-	}
-	if (pending.length > 0) write(home, reg, now);
-	return pending;
+function collectGit(root) {
+	const status = git(root, "status --porcelain=v1 --branch");
+	if (!status) return "";
+	const branch = parseBranch(status) || "(unknown)";
+	const w = countWip(status);
+	const log = git(root, "log --oneline -3");
+	const lines = [`- branch: ${branch}`];
+	if (log) lines.push("- recent:", ...log.split("\n").map((l) => `    ${l}`));
+	lines.push(`- WIP: ${w.staged} staged, ${w.unstaged} unstaged, ${w.untracked} untracked`);
+	return lines.join("\n");
 }
 //#endregion
-//#region src/runtime/lifecycle/lessons/reminder.ts
+//#region src/cli/doctor.ts
 /**
-* fuse-lessons write-mark + Stop-reminder, scoped by `session_id` when present.
+* `harness doctor` — diagnose which `@fusengine/harness` is actually running.
 *
-* WITH a session id (normal Claude Code): each `(session, root)` pair carries
-* its own edit/reminder throttle in {@link module:memory/session-roots}, so a
-* Stop lists and silences ONLY the roots THAT session edited — concurrent
-* sessions on different projects never cross-remind nor steal each other's
-* throttle. WITHOUT a usable session id (a harness that omits it, or the legacy
-* on-disk state) it falls back to the original mono-session behavior: the global
-* flat root registry + the per-project `MEMORY/state.json` throttle.
+* A confirmed, still-open bun bug (oven-sh/bun #5791; scoped-pkg behaviour
+* reinforced by #32019/#32150) makes `bunx <pkg>` (unpinned) prefer a stale
+* GLOBAL install over npm-latest, so a consumer can silently run an old harness
+* after a publish. This command surfaces the truth: the resolved version +
+* package path of the code executing right now, the runtime binary, and the
+* latest version published on npm. It queries the registry over HTTP (not
+* `npm view`, whose exit code is 0 even on an empty result — npm/cli#6408) and
+* never throws: an offline environment yields `latest: null`, never a crash.
 */
-/** Sanitized session id from a raw hook payload, or null (→ legacy fallback). */
-function sessionOf(payload) {
-	return sanitizeSessionId(payload.session_id);
-}
-/** Legacy (no session id): pending roots across the global flat registry. */
-function collectLegacyPending(now, window) {
-	const pending = [];
-	for (const root of readRoots()) {
-		const stateFile = lessonsStateFileFor(root);
-		const { lastRemindedAt, lastCodeEditAt } = readState(stateFile);
-		if (lastCodeEditAt <= lastRemindedAt) continue;
-		if (now - lastRemindedAt < window) continue;
-		pending.push(root);
-		setStateField(stateFile, "lastRemindedAt", now);
+const PKG = "@fusengine/harness";
+/** Walk up from `startDir` for the `@fusengine/harness` `package.json`. */
+function findPackage(startDir) {
+	let dir = startDir;
+	for (let depth = 0; depth < 6; depth++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (pkg.name === PKG) return {
+				version: pkg.version ?? "unknown",
+				path: dir
+			};
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
 	}
-	return pending;
+	return null;
 }
-/** Stop reminder body listing each pending project's lessons file. */
-function reminderText(pending) {
-	return `Before ending: if this session hit a mistake/blocker worth never reproducing, append 1-3 COMPACT bullets OR sharpen/merge existing ones (format \`- [${nowStamp()}] what went wrong → do instead\`, use exactly this timestamp) in each project's lessons file below. Skip if nothing notable.\n${pending.map((r) => `- ${r}/MEMORY/LESSON.md`).join("\n")}`;
+/** Resolve the running version + package path (no network), from a module URL. */
+function runningVersion(moduleUrl) {
+	const found = findPackage(dirname(fileURLToPath(moduleUrl)));
+	return {
+		version: found?.version ?? "unknown",
+		path: found?.path ?? "unknown"
+	};
 }
-/**
-* Stop: emit one reminder covering the stopping session's pending projects.
-* @param payload - Raw hook payload (`session_id` selects the scoped path).
-* @param now - Clock.
-* @returns Native Stop stdout, or "" when nothing is pending.
-*/
-function remindWrite(payload, now) {
-	const window = throttleMs();
-	const sid = sessionOf(payload);
-	const pending = sid ? collectSessionPending(sid, now, window) : collectLegacyPending(now, window);
-	if (pending.length === 0) return "";
-	return contextResponse("Stop", reminderText(pending));
+/** One-line `pkg vX.Y.Z` banner (stderr, only on explicit `--version`/`doctor` commands — never on `hook`, to avoid spamming automated invocations). */
+function versionBanner(moduleUrl) {
+	return `${PKG} v${runningVersion(moduleUrl).version}`;
 }
-/**
-* PostToolUse: record the edit against the throttle. A code file arms the
-* reminder; writing `MEMORY/LESSON.md` silences it (the lesson was just saved).
-* Session-scoped when `session_id` is present, else the legacy global path.
-* @param payload - Raw hook payload (`tool_input.file_path`, `session_id`).
-* @param now - Clock.
-*/
-function markWrite(payload, now) {
-	const input = payload.tool_input;
-	if (!input?.file_path) return;
-	const abs = resolve(input.file_path);
-	const root = projectRootOrNull(dirname(abs));
-	if (!root) return;
-	const isLesson = abs === resolve(root, "MEMORY", "LESSON.md");
-	if (!isLesson && !isCodeFile(abs)) return;
-	const sid = sessionOf(payload);
-	if (sid) markSessionRoot(sid, root, isLesson ? "remindedAt" : "editedAt", now);
-	else if (isLesson) setStateField(lessonsStateFileFor(root), "lastRemindedAt", now);
-	else {
-		setStateField(lessonsStateFileFor(root), "lastCodeEditAt", now);
-		addRoot(root);
+/** Latest published version via the npm registry HTTP API. `null` on any failure. */
+async function npmLatest() {
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: AbortSignal.timeout(8e3) });
+		if (!res.ok) return null;
+		return (await res.json()).version ?? null;
+	} catch {
+		return null;
 	}
 }
+/** Build the full diagnostic report for the module at `moduleUrl`. */
+async function buildDoctorReport(moduleUrl) {
+	const { version, path } = runningVersion(moduleUrl);
+	const latest = await npmLatest();
+	return {
+		running: version,
+		packagePath: path,
+		runtime: process.execPath,
+		latest,
+		stale: latest !== null && latest !== version
+	};
+}
+/** Render a {@link DoctorReport} as human-readable stdout text. */
+function formatDoctor(r) {
+	const lines = [
+		`${PKG} doctor`,
+		`  running:    ${r.running}`,
+		`  package:    ${r.packagePath}`,
+		`  runtime:    ${r.runtime}`,
+		`  npm latest: ${r.latest ?? "(unavailable — offline or unreachable)"}`
+	];
+	if (r.stale) lines.push(`  ! stale — npm serves ${r.latest}. Pin "@fusengine/harness@${r.latest}" in hooks.json (see README).`);
+	else if (r.latest !== null) lines.push(`  ok — running the latest published version.`);
+	return lines.join("\n");
+}
+/** Run `harness doctor`: print the diagnostic to stdout. Always resolves 0 (pure info). */
+async function runDoctor(moduleUrl) {
+	process.stdout.write(formatDoctor(await buildDoctorReport(moduleUrl)) + "\n");
+	return 0;
+}
 //#endregion
-//#region src/runtime/lifecycle/lessons/dispatch.ts
+//#region src/runtime/lifecycle/snapshot/version.ts
+/** Read the `version` field of `<root>/package.json`, or `""` if absent/unreadable. */
+function pkgVersion(root) {
+	try {
+		return JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version ?? "";
+	} catch {
+		return "";
+	}
+}
 /**
-* fuse-lessons scope dispatch (TS port of the 4 handler scripts). Routes by
-* event: SessionStart/SubagentStart inject `MEMORY/LESSON.md`; Stop reminds the
-* stopping session about ITS OWN projects with unsaved code edits; PostToolUse
-* marks the write to arm/silence the throttle. The reminder + mark logic (incl.
-* the per-`session_id` scoping that fixes the multi-session misdirection) lives
-* in {@link module:runtime/lifecycle/lessons/reminder}; this module keeps the
-* event router + lesson-file injection. Non-fatal by design.
+* Collect the version reconciliation section: the harness version actually
+* running (resolved from {@link runningVersion}, no network) and, when `root`
+* carries its own `package.json`, whether that project's version has drifted
+* from the running harness.
+* @param root - The project root (cwd repo).
+* @param moduleUrl - `import.meta.url` of the calling module (locates the running package.json).
+* @returns The rendered version section body (never `""`).
 */
+function collectVersion(root, moduleUrl) {
+	const running = runningVersion(moduleUrl).version;
+	const lines = [`- harness running: v${running}`];
+	const project = pkgVersion(root);
+	if (project && project !== running) lines.push(`- project package.json: v${project} (DRIFT — running harness differs)`);
+	else if (project) lines.push(`- project package.json: v${project} (in sync)`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/runtime/lifecycle/snapshot/board.ts
+/** Max board characters injected — a persistent board should stay small; over-long boards are truncated. */
+const MAX_BOARD = 4e3;
 /**
-* Persist a curation ATOMICALLY and ARCHIVE-FIRST for zero-loss: prepend the
-* moved bullets to LESSON-archive.md, THEN rewrite LESSON.md. On ANY write error
-* the original file is left untouched (returns `original`) so a bullet is never
-* lost — a rare archive-then-trim-fail leaves a duplicate (never a loss), which
-* the next dedup pass reconciles.
+* Collect the persistent task board: the contents of `<root>/.claude/BOARD.md`
+* (truncated to {@link MAX_BOARD}) plus an instruction to keep it current. The
+* board lives on disk so it survives context purges — rehydrated every session.
+* Missing/empty/unreadable board → `""` (section omitted).
+* @param root - The project root.
+* @returns The rendered board section body, or `""` when there is no board.
 */
-function persistCuration(file, root, curated, archive, original) {
+function collectBoard(root) {
+	const path = join(root, ".claude", "BOARD.md");
 	try {
-		if (archive) {
-			const af = lessonsArchiveFileFor(root);
-			const prev = existsSync(af) ? readFileSync(af, "utf-8") : "";
-			atomicWrite(af, prev ? `${archive}\n${prev}` : archive);
-		}
-		atomicWrite(file, curated);
-		return curated;
+		if (!existsSync(path)) return "";
+		let body = readFileSync(path, "utf8").trim();
+		if (!body) return "";
+		if (body.length > MAX_BOARD) body = `${body.slice(0, MAX_BOARD)}\n… (truncated)`;
+		return `- .claude/BOARD.md (keep current — Write to it as tasks start/finish):\n\n${body}`;
 	} catch {
-		return original;
+		return "";
 	}
 }
+//#endregion
+//#region src/runtime/lifecycle/snapshot/format.ts
 /**
-* Inject `MEMORY/LESSON.md` for `event`. Mechanical curation (dedup + cap→archive)
-* rewrites the FILE; the injected BLOCK is then COMPRESSED (newest bullets whole,
-* older ones distilled to their rule) so a growing file never inflates the
-* SessionStart/SubagentStart context. Any curation report surfaces via systemMessage.
+* Render the non-empty `sections` under one reconciliation heading. Empty
+* sections are dropped; when every section is empty the whole snapshot is `""`.
+* Each surviving section is passed through {@link capFragment} (harness-produced
+* content, not owner CLAUDE.md), and a trailing {@link budgetReport} line gives
+* the owner-requested numeric visibility into what was actually injected.
+* @param sections - The collected sections in display order.
+* @returns The assembled markdown block, or `""` when nothing to report.
 */
-function injectMemory(cwd, event, now) {
-	const root = projectRoot(cwd);
-	const file = lessonsFileFor(root);
-	if (!existsSync(file)) return "";
-	let content = "";
+function renderSections(sections) {
+	const kept = sections.filter((s) => s.body.trim()).map((s) => ({
+		title: s.title,
+		body: capFragment(s.title, s.body.trim())
+	}));
+	if (!kept.length) return "";
+	const header = "# Reconciliation snapshot\nReal state of the world at session start — reconcile against this instead of re-discovering it.";
+	const parts = kept.map((s) => `### ${s.title}\n${s.body}`);
+	const report = budgetReport(kept.map((s) => ({
+		label: s.title,
+		chars: s.body.length
+	})));
+	return `${header}\n\n${parts.join("\n\n")}\n\n_${report}_`;
+}
+/**
+* Concatenate `snapshot` onto an existing SessionStart stdout's
+* `additionalContext` — it never replaces prior injected context (CLAUDE.md,
+* dev-context). When `stdout` is empty a fresh {@link contextResponse} is made;
+* a non-empty but unparseable `stdout` is returned UNCHANGED (the snapshot is
+* dropped) — fabricating a fresh response there would discard the very CLAUDE.md
+* injection the invariant protects, so preserving prior context always wins.
+* @param stdout - The core SessionStart JSON stdout (may be `""`).
+* @param snapshot - The snapshot markdown to append (no-op when `""`).
+* @returns The merged hook stdout JSON.
+*/
+function attachSnapshot(stdout, snapshot) {
+	if (!snapshot) return stdout;
+	if (!stdout) return contextResponse("SessionStart", snapshot);
 	try {
-		content = readFileSync(file, "utf-8").trim();
+		const parsed = JSON.parse(stdout);
+		const prev = parsed.hookSpecificOutput?.additionalContext ?? "";
+		const merged = prev ? `${prev}\n\n${snapshot}` : snapshot;
+		return JSON.stringify({
+			...parsed,
+			hookSpecificOutput: {
+				...parsed.hookSpecificOutput,
+				hookEventName: "SessionStart",
+				additionalContext: merged
+			}
+		});
+	} catch {
+		return stdout;
+	}
+}
+//#endregion
+//#region src/runtime/lifecycle/snapshot/index.ts
+/** Run `fn`, swallowing any throw into `""` so no single collector can break the hook. */
+function safe(fn) {
+	try {
+		return fn();
 	} catch {
 		return "";
 	}
-	if (!content) return "";
-	const { content: curated, archive, report } = curateLessons(content, now, root);
-	if (curated !== content) content = persistCuration(file, root, curated, archive, content);
-	const ctx = `Project lessons — never reproduce these:\n${compressInjection(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);
 }
 /**
-* Route a fuse-lessons event to its handler. Returns the native stdout for
-* context-injecting events (SessionStart/SubagentStart/Stop) or "" for the
-* side-effect-only PostToolUse mark.
-* @param event - The raw hook event name.
-* @param payload - The raw hook payload.
-* @param cwd - Project root for memory injection.
-* @param now - Clock.
-* @returns The native stdout (possibly empty).
+* Build the reconciliation snapshot markdown for `cwd`: git state, running
+* harness version + drift, the persistent board, and one-shot gate status. Each
+* collector is isolated by {@link safe}; an all-empty result yields `""`.
+* @param cwd - The session working directory.
+* @param moduleUrl - `import.meta.url` of the caller (locates the running package).
+* @returns The snapshot markdown, or `""` when nothing to report.
 */
-function dispatchLessons(event, payload, cwd, now) {
-	switch (event) {
-		case "SessionStart":
-		case "SubagentStart": return injectMemory(cwd, event, now);
-		case "Stop": return remindWrite(payload, now);
-		case "PostToolUse":
-			markWrite(payload, now);
-			return "";
-		default: return "";
+function renderSnapshot(cwd, moduleUrl) {
+	const root = projectRootOrNull(cwd) ?? cwd;
+	return renderSections([
+		{
+			title: "Git",
+			body: safe(() => collectGit(root))
+		},
+		{
+			title: "Version",
+			body: safe(() => collectVersion(root, moduleUrl))
+		},
+		{
+			title: "Board",
+			body: safe(() => collectBoard(root))
+		},
+		{
+			title: "One-shot gates",
+			body: safe(() => oneShotSummary(cwd))
+		}
+	]);
+}
+/**
+* Concatenate the reconciliation snapshot onto a core SessionStart stdout. Fully
+* fail-safe: any error returns `stdout` unchanged so the hook never breaks.
+* @param stdout - The core SessionStart JSON stdout (may be `""`).
+* @param cwd - The session working directory.
+* @param moduleUrl - `import.meta.url` of the caller.
+* @returns The merged hook stdout.
+*/
+function withSnapshot(stdout, cwd, moduleUrl) {
+	try {
+		return attachSnapshot(stdout, renderSnapshot(cwd, moduleUrl));
+	} catch {
+		return stdout;
 	}
 }
 //#endregion
-//#region src/policy/deny-loop.ts
+//#region src/runtime/lifecycle/post-compact.ts
 /**
-* @module deny-loop
-* Pure anti-loop logic: hash a tool-call, decide if it repeats a prior deny, and
-* enrich the repeated block's message.
-*
-* The proprietary rule "NEVER propose the same fix twice" is prose a model under
-* pressure ignores. This makes it machine-enforced: when a call whose
-* `(tool + normalized input)` hash was ALREADY denied in-window is retried, the
-* harness keeps the deny but rewrites the message — `[REPEAT]` title, STOP
-* prefix, forced `research-expert` action. State + wiring live in the sidecar
-* store ({@link module:deny-loop-store}); this file is IO-free and pure.
+* @module post-compact
+* PostCompact handler (core scope): re-inject the reconciliation snapshot plus a
+* one-line reminder that read-state may have been reset by compaction, so the
+* agent re-reads files before editing. Deduped per session/window (compaction can
+* fan out too). Fully fail-open — any error yields "".
 * @packageDocumentation
 */
-/** Stable JSON: keys sorted at every depth so `{a,b}` and `{b,a}` hash identically. */
-function stableStringify(v) {
-	if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
-	if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
-	const o = v;
-	return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(o[k])}`).join(",")}}`;
-}
+/** Re-inject at most once per 30s per session (compaction fan-out + retries). */
+const COMPACT_DEDUP_MS = 3e4;
+/** One-line reminder prepended to the re-injected snapshot. */
+const REMINDER = "Context was compacted — reread files before editing (read-state may be reset).";
 /**
-* Stable identity hash of a tool-call = tool name + normalized (key-sorted) input,
-* so re-ordered keys never mask a repeat.
-* @param tool - Tool name (e.g. "Write", "Bash").
-* @param input - Identifying tool input (filePath/content/command...).
-* @returns 8-char hex hash.
+* Handle PostCompact: emit the reminder + reconciliation snapshot as
+* `additionalContext`, deduped per session. "" on dedup-suppress or any error.
+* @param data - The raw PostCompact payload (`session_id`, `trigger`).
+* @param cwd - Project root.
+* @param moduleUrl - `import.meta.url` of the caller (locates the running package for the version line).
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native hook stdout, or "".
 */
-function denyHash(tool, input) {
-	return hashText(`${tool}\n${stableStringify(input)}`);
-}
-/**
-* Pure loop check: given the already-pruned in-window map, compute the running
-* count for `hash` and whether it repeats (count > 1). No IO — the caller persists.
-*
-* When `dedupMs` is set (>0) and an identical prior deny landed within that
-* window, the current call is a sibling hook echoing the SAME event (see
-* {@link module:burst-window}): it returns the prior verdict VERBATIM with
-* `deduped:true` and does NOT bump the count, so all N fan-out processes agree
-* on one number instead of counting to N. Absent `dedupMs` (mono-process
-* callers / unit tests) the historical increment-every-time behaviour holds.
-* @param hash - {@link denyHash}-derived map key of the current call.
-* @param priorDenies - The `{ hash -> DenyEntry }` map, pruned to `now`/`windowMs`.
-* @param opts - Clock + window, plus an optional burst-dedup window.
-* @returns `{ isRepeat, count, hash, deduped? }`.
-*/
-function denyLoopCheck(hash, priorDenies, opts) {
-	const prev = priorDenies[hash];
-	if (!(prev && typeof prev.lastTs === "number" && opts.now - prev.lastTs < opts.windowMs)) return {
-		isRepeat: false,
-		count: 1,
-		hash
-	};
-	if ((opts.dedupMs ?? 0) > 0 && opts.now - prev.lastTs < (opts.dedupMs ?? 0)) return {
-		isRepeat: prev.count > 1,
-		count: prev.count,
-		hash,
-		deduped: true
-	};
-	const count = prev.count + 1;
-	return {
-		isRepeat: count > 1,
-		count,
-		hash
-	};
-}
-/**
-* Enrich a REPEATED block prompt — a NEW object, never a mutation (the input may
-* be a shared const like FAIL_CLOSED). The decision stays `block`; only the
-* message changes, so every harness renders it through the same adapter.
-* @param prompt - The original block prompt.
-* @param count - The running identical-deny count (n).
-* @returns A block prompt with `[REPEAT]` title, STOP-prefixed reason, forced research action.
-*/
-function enrichRepeatDeny(prompt, count) {
-	const stop = `Identical attempt #${count} already denied for the same reason. STOP: do not retry this same call. `;
-	const action = "Launch fuse-ai-pilot:research-expert to find a DIFFERENT approach";
-	return {
-		...prompt,
-		title: prompt.title.startsWith("[REPEAT]") ? prompt.title : `[REPEAT] ${prompt.title}`,
-		reason: stop + prompt.reason,
-		actions: [action, ...prompt.actions ?? []]
-	};
+function postCompactContext(data, cwd, moduleUrl, now = Date.now()) {
+	try {
+		if (!oncePerWindow(`postcompact:${typeof data.session_id === "string" ? data.session_id : "unknown"}`, COMPACT_DEDUP_MS, {
+			now,
+			dir: defaultStateDir(cwd)
+		})) return "";
+		const snapshot = renderSnapshot(cwd, moduleUrl);
+		return contextResponse("PostCompact", snapshot ? `${REMINDER}\n\n${snapshot}` : REMINDER);
+	} catch {
+		return "";
+	}
 }
 //#endregion
-//#region src/tracking/one-shot-store.ts
-/** A fresh, empty state — always spread (`{ ...EMPTY }`) so the const is never shared. */
-const EMPTY = {
-	gates: {},
-	firstTry: 0,
-	corrected: 0,
-	pending: {},
-	updatedAt: 0
-};
-/**
-* Drop stale data: whole-state idle reset past the window, else per-entry prune of
-* gates/pending older than `windowMs`. Keeps the "7d" window honest, bounds size.
-*/
-function pruneState(s, now, windowMs) {
-	if (now - s.updatedAt >= windowMs) return { ...EMPTY };
-	const gates = {};
-	for (const [k, g] of Object.entries(s.gates)) if (now - g.lastTs < windowMs) gates[k] = g;
-	const pending = {};
-	for (const [k, p] of Object.entries(s.pending)) if (now - p.ts < windowMs) pending[k] = p;
-	return {
-		...s,
-		gates,
-		pending
-	};
+//#region src/runtime/lifecycle/task-completed.ts
+/** Code-file extensions audited on task completion (mirrors validate-task-solid.py). */
+const CODE_EXTENSIONS$2 = /* @__PURE__ */ new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".py",
+	".go",
+	".rs",
+	".java",
+	".php",
+	".cpp",
+	".c",
+	".rb",
+	".swift",
+	".kt",
+	".dart",
+	".vue",
+	".svelte",
+	".astro"
+]);
+/** Freshness multiple on `FUSE_ENFORCE_TTL_SEC` for receipts (no new env var); a tsc+test run precedes the "done" by more than one edit window. */
+const RECEIPT_TTL_MULTIPLIER = 5;
+/** The modified files that are code (by extension) — the receipt gate's trigger set. */
+function codeFiles(files) {
+	return files.filter((fp) => CODE_EXTENSIONS$2.has(extname(fp)));
 }
 /**
-* Record a deny for gate `title` on operation `op` (content-free tool identity):
-* bump the gate's deny count and mark `op` pending for a later fix.
+* Refuse completion when code files changed but no fresh, passing verification
+* receipt (`tsc`/test, exit 0, zero failures, within TTL×{@link RECEIPT_TTL_MULTIPLIER})
+* exists in the signed track. TaskCompleted does NOT honor `decision:"block"`
+* (verified against the official hooks docs — `TeammateIdle/TaskCreated/
+* TaskCompleted` are excluded from that list); the documented stdout refusal is
+* `{"continue":false,"stopReason":…}`, which halts the teammate with the reason
+* shown to the user. Returns that JSON, or `null` when the session is clear.
 */
-function applyDeny(s, title, op, now) {
-	const g = s.gates[title] ?? {
-		denies: 0,
-		corrected: 0,
-		lastTs: 0
-	};
-	return {
-		...s,
-		gates: {
-			...s.gates,
-			[title]: {
-				denies: g.denies + 1,
-				corrected: g.corrected,
-				lastTs: now
-			}
-		},
-		pending: {
-			...s.pending,
-			[op]: {
-				title,
-				ts: now
-			}
-		},
-		updatedAt: now
-	};
+function receiptGate(sid, files, now, stateDir) {
+	if (codeFiles(files).length === 0) return null;
+	const windowMs = resolveTtlSec(process.env) * 1e3 * RECEIPT_TTL_MULTIPLIER;
+	if (freshReceiptFromFile(trackFile(sid, stateDir), windowMs, now)) return null;
+	return JSON.stringify({
+		continue: false,
+		stopReason: "VERIFICATION RECEIPT REQUIRED: code files changed but no fresh passing tsc/test receipt exists. Run `bun test` + `tsc --noEmit` (exit 0, 0 failures) and re-complete."
+	});
 }
 /**
-* Record an allow for a gateable `op`. A non-gateable allow (Read/Task/MCP) leaves
-* state untouched — it never counts and never clears a pending deny. Otherwise: a
-* pending deny → `corrected` (a fix, credited to the blocking gate); no pending →
-* `firstTry` (one-shot).
+* Re-count physical lines of every modified code file and collect SOLID
+* violations (`<basename>: <n> lines (max <max>)`) for those exceeding `max`.
+* @param files - Candidate modified file paths.
+* @param max - The SOLID line ceiling.
+* @returns The list of violation strings (empty when all files comply).
 */
-function applyAllow(s, op, now, gateable) {
-	if (!gateable) return s;
-	const pend = s.pending[op];
-	if (pend) {
-		const g = s.gates[pend.title] ?? {
-			denies: 0,
-			corrected: 0,
-			lastTs: 0
-		};
-		const { [op]: _drop, ...pending } = s.pending;
-		return {
-			...s,
-			gates: {
-				...s.gates,
-				[pend.title]: {
-					...g,
-					corrected: g.corrected + 1,
-					lastTs: now
-				}
-			},
-			corrected: s.corrected + 1,
-			pending,
-			updatedAt: now
-		};
+function collectViolations(files, max) {
+	const violations = [];
+	for (const fp of files) {
+		if (!CODE_EXTENSIONS$2.has(extname(fp)) || !existsSync(fp)) continue;
+		try {
+			const lines = countLines(readFileSync(fp, "utf-8"));
+			if (lines > max) violations.push(`${basename(fp)}: ${lines} lines (max ${max})`);
+		} catch {}
 	}
-	return gateable ? {
-		...s,
-		firstTry: s.firstTry + 1,
-		updatedAt: now
-	} : s;
+	return violations;
 }
 /**
-* Compact injectable summary (one line); "" when there is nothing to report.
-* @returns e.g. `gates 7d: 88% one-shot (44/50 clean); SOLID file-size limit 4den/3fix`.
+* Handle TaskCompleted (ports `task-completed/validate-task-solid.py`, plus the
+* receipt gate). SOLID violations surface first as `SOLID VIOLATION`
+* additionalContext; once the files comply, {@link receiptGate} refuses a "done"
+* that has no fresh passing tsc/test receipt.
+* @param payload - The TaskCompleted payload (`task_id`, `task_subject`, `session_id`).
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+* @param stateDir - Track base dir (defaults to the cwd-derived state dir; matches `handleHook`).
+* @returns The native hook stdout, or `""` when the session is clean.
 */
-function formatSummary(s) {
-	const keys = Object.keys(s.gates);
-	const total = s.firstTry + s.corrected;
-	if (keys.length === 0 && total === 0) return "";
-	const head = total > 0 ? `${Math.round(s.firstTry / total * 100)}% one-shot (${s.firstTry}/${total} clean)` : "no clean pass yet";
-	const parts = keys.map((k) => ({
-		k,
-		g: s.gates[k]
-	})).sort((a, b) => b.g.denies - a.g.denies).map(({ k, g }) => `${k} ${g.denies}den/${g.corrected}fix`);
-	return `gates 7d: ${head}${parts.length ? `; ${parts.join("; ")}` : ""}`;
+function validateTaskSolid(payload, home = homedir(), now = Date.now(), stateDir = defaultStateDir(process.cwd())) {
+	const sid = sanitizeSessionId(payload.session_id ?? "unknown");
+	if (!sid) return "";
+	const files = loadSessionState(sid, home).changes?.modifiedFiles ?? [];
+	if (files.length === 0) return "";
+	const max = resolveMaxLines();
+	const violations = collectViolations(files, max);
+	if (violations.length === 0) return receiptGate(sid, files, now, stateDir) ?? "";
+	const taskId = String(payload.task_id ?? "");
+	return contextResponse("TaskCompleted", `SOLID VIOLATION in task '${String(payload.task_subject ?? "")}' (${taskId}): ${violations.length} file(s) exceed ${max} lines: ` + violations.slice(0, 5).join("; "));
 }
 //#endregion
-//#region src/tracking/one-shot-dedup.ts
+//#region src/runtime/lifecycle/cartographer/fs-util.ts
 /**
-* @module one-shot-dedup
-* Burst-dedup guard for the one-shot metric ({@link module:one-shot}).
-*
-* ONE Claude tool event fans out to ~11 sibling plugin-hook processes, each
-* calling {@link recordOneShot}; without this the metric would count a single
-* deny/allow ~11×. Reuses the proven {@link oncePerWindow} cooldown sidecar:
-* the FIRST process in the {@link module:burst-window} window mutates the
-* metric, the rest skip. The dedup key includes the outcome KIND (deny-title vs
-* allow) so a deny and its later fix — different kinds — are never folded into
-* each other. No `sessionId` → always the first (mono-process + unit-test
-* parity; a burst can only exist when a real session drives the fan-out).
-* @packageDocumentation
+* Filesystem helpers for the cartographer tree walk. Ports the fs parts of
+* `describe.py` (file desc) and `write_recursive.py` (children + counts).
 */
 /**
-* True when this `(op, kind)` is the FIRST of its burst for the session — the
-* process that should actually mutate the metric. Sibling processes firing the
-* SAME event within {@link BURST_DEDUP_MS} return false and skip the write.
-* @param op - Content-free operation key ({@link denyHash}("op", …)).
-* @param kind - Outcome discriminator (`deny:<title>` or `allow`).
-* @param opts - Clock + state dir + optional session id.
-* @returns `true` to apply the record, `false` to skip (already counted).
+* Read a file and derive its one-line description (frontmatter / heading /
+* comment). "" on any error or when nothing is found.
+* @param filePath - Absolute path to the file.
+* @returns The description, or "".
 */
-function burstFirst(op, kind, opts) {
-	const sid = opts.sessionId?.trim();
-	if (!sid) return true;
-	return oncePerWindow(`oneshot:${sid}:${op}:${kind}`, BURST_DEDUP_MS, {
-		now: opts.now,
-		dir: opts.dir
+function getFileDesc(filePath) {
+	let text = "";
+	try {
+		text = readFileSync(filePath, "utf-8");
+	} catch {
+		return "";
+	}
+	const suffix = extname(filePath);
+	const mdField = suffix === ".md" ? parseField(text, "description") : "";
+	return descFromText(suffix, text, mdField);
+}
+/**
+* Recursively count files whose relative path parts are all visible (no leading
+* "." or "_") and none excluded. Best-effort (partial count on errors).
+* @param dir - Directory to count under.
+* @param exclude - Directory/name set to skip.
+* @returns The file count.
+*/
+function countFiles(dir, exclude) {
+	let total = 0;
+	try {
+		for (const e of readdirSync(dir, { withFileTypes: true })) {
+			if (e.name.startsWith(".") || e.name.startsWith("_") || exclude.has(e.name)) continue;
+			if (e.isDirectory()) total += countFiles(join(dir, e.name), exclude);
+			else if (e.isFile()) total += 1;
+		}
+	} catch {}
+	return total;
+}
+/** Absolute children of `source`, split into dirs/files, sorted by full path. */
+function listChildren(source, exclude) {
+	const dirs = [];
+	const files = [];
+	let entries;
+	try {
+		entries = readdirSync(source, { withFileTypes: true });
+	} catch {
+		return {
+			dirs,
+			files
+		};
+	}
+	for (const e of entries) {
+		if (e.name.startsWith(".") || e.name.startsWith("_") || exclude.has(e.name)) continue;
+		const abs = join(source, e.name);
+		if (e.isDirectory()) dirs.push(abs);
+		else if (e.isFile()) files.push(abs);
+	}
+	return {
+		dirs: dirs.sort(),
+		files: files.sort()
+	};
+}
+//#endregion
+//#region src/runtime/lifecycle/cartographer/merge.ts
+/**
+* Index merge — preserves enriched descriptions across regenerations. Ports
+* `merge_index.py` (merge_lines + .enriched.json sidecar).
+*/
+/**
+* Load the `.enriched.json` sidecar's `entries` map for an output index.
+* @param outputIndexPath - Path to the index.md being written.
+* @returns The path→desc enrichment map (possibly empty).
+*/
+function loadEnriched(outputIndexPath) {
+	const sidecar = join(dirname(outputIndexPath), ".enriched.json");
+	try {
+		if (!existsSync(sidecar)) return {};
+		return JSON.parse(readFileSync(sidecar, "utf-8")).entries ?? {};
+	} catch {
+		return {};
+	}
+}
+/**
+* Merge freshly generated lines with prior descriptions: enriched sidecar wins,
+* else a longer pre-existing description is preserved.
+* @param newLines - The freshly generated index lines.
+* @param outputIndexPath - Path to the existing index.md (if any).
+* @returns The merged lines.
+*/
+function mergeLines(newLines, outputIndexPath) {
+	const enriched = loadEnriched(outputIndexPath);
+	const existingDescs = {};
+	if (existsSync(outputIndexPath)) try {
+		for (const line of readFileSync(outputIndexPath, "utf-8").split("\n")) {
+			const e = parseEntry(line);
+			if (e) existingDescs[e.path] = e.desc;
+		}
+	} catch {}
+	return newLines.map((line) => {
+		const e = parseEntry(line);
+		if (!e) return line;
+		if (e.path in enriched) return `${e.prefix}[${e.name}](${e.path}) — ${enriched[e.path]}`;
+		const old = existingDescs[e.path] ?? "";
+		if (old.length > e.desc.length) return `${e.prefix}[${e.name}](${e.path}) — ${old}`;
+		return line;
 	});
 }
 //#endregion
-//#region src/tracking/one-shot.ts
+//#region src/runtime/lifecycle/cartographer/write-tree.ts
 /**
-* @module one-shot
-* Sidecar store + gate wiring for the per-gate one-shot metric.
-*
-* STATE — a standalone sidecar (`one-shot.json`) in the same per-project state dir
-* as the session track, mirroring {@link module:deny-loop-store} (atomicWrite,
-* prune-by-window, fail-safe). A write error NEVER changes a gate decision nor its
-* prompt — metrics are pure observation.
-*
-* KEY — the operation identity is content-FREE (`tool + filePath/command`): a fix
-* changes the content, so a content hash would make every retry a new op and hide
-* the deny→allow transition this metric exists to see. The pure model lives in
-* {@link module:one-shot-store}; this file is the only IO surface.
-* @packageDocumentation
+* Recursive index.md tree writer. Ports `write_recursive.py`.
 */
-/** Sidecar basename under the per-project state dir. */
-const SIDECAR$1 = "one-shot.json";
-/** Retention window: 7 days. Aggregates and pending denies older than this are pruned. */
-const WINDOW_MS = 10080 * 60 * 1e3;
-/** Load the state, or a fresh copy when missing/corrupt. */
-function loadState(path) {
+/**
+* Write `index.md` files mirroring `source` under `output`, recursing into
+* subdirectories. Directory lines carry a file-count hint; file lines carry a
+* derived description and link to the real absolute source path.
+* @param source - Absolute source directory.
+* @param output - Absolute output directory for the index tree.
+* @param back - Relative `← back` link target ("" at the root).
+* @param exclude - Directory/name set to skip.
+*/
+function writeTree(source, output, back = "", exclude) {
+	const ex = exclude ?? /* @__PURE__ */ new Set();
+	mkdirSync(output, { recursive: true });
+	const { dirs, files } = listChildren(source, ex);
+	const lines = [`# ${basename(source)}\n`];
+	if (back) lines.push(`> [← back](${back})\n`);
+	const total = dirs.length + files.length;
+	let idx = 0;
+	for (const d of dirs) {
+		idx += 1;
+		const conn = idx === total ? "└──" : "├──";
+		const count = countFiles(d, ex);
+		const hint = count ? ` — ${count} files` : "";
+		lines.push(`${conn} [${basename(d)}/](./${basename(d)}/index.md)${hint}`);
+		writeTree(d, join(output, basename(d)), "../index.md", exclude);
+	}
+	for (const f of files) {
+		idx += 1;
+		const conn = idx === total ? "└──" : "├──";
+		const desc = getFileDesc(f);
+		const suffix = desc ? ` — ${desc}` : "";
+		lines.push(`${conn} [${basename(f)}](${f})${suffix}`);
+	}
+	const indexPath = join(output, "index.md");
+	writeFileSync(indexPath, mergeLines(lines, indexPath).join("\n") + "\n", "utf-8");
+}
+//#endregion
+//#region src/runtime/lifecycle/cartographer/project-map.ts
+/**
+* Project map generation. Ports `generate_project_map.py` (project map only).
+*/
+/** True when `dir` is a real directory. */
+function isDirectory(dir) {
 	try {
-		if (!existsSync(path)) return { ...EMPTY };
-		const d = JSON.parse(readFileSync(path, "utf8"));
-		return d && typeof d === "object" && !Array.isArray(d) ? {
-			...EMPTY,
-			...d
-		} : { ...EMPTY };
+		return statSync(dir).isDirectory();
 	} catch {
-		return { ...EMPTY };
+		return false;
 	}
 }
 /**
-* Record a gate outcome: a `block` is a deny for its gate title; a `null` allow is
-* a fix (if the op was pending) or a one-shot (if gateable). `ask`/`inform` are
-* neither and are skipped. Fails silently — a metric write NEVER affects a decision.
-*
-* The op key is tool-INDEPENDENT (`filePath`/`command` only, constant `"op"` tool):
-* a deny (a `Write`) and its fix (an `Edit`) on the same file must link.
-* @param prompt - The gate's outcome (block, allow=null, or ask/inform).
-* @param input - Identifying tool input (content decides gateability only).
-* @param opts - Clock + state dir.
+* True when `dir` looks like a project root (has an indicator file) and is not
+* the home directory or filesystem root.
+* @param dir - Directory to test.
+* @returns Whether `dir` is a project root.
 */
-function recordOneShot(prompt, input, opts) {
+function isProject(dir) {
+	const resolved = resolve(dir);
+	if (resolved === resolve(homedir()) || resolved === "/") return false;
+	for (const f of PROJECT_INDICATORS) if (existsSync(join(dir, f))) return true;
+	return false;
+}
+/**
+* Generate the `.cartographer/project` index tree for `cwd` when it is a real
+* project directory. Always returns "" (no additionalContext emitted).
+* @param cwd - The working directory.
+* @param outputDir - Override for the output tree root.
+* @returns "" (side-effect only).
+*/
+function generateProjectMap(cwd, outputDir) {
+	const projectDir = resolve(cwd);
+	const out = outputDir ?? join(projectDir, ".cartographer", "project");
+	if (!isDirectory(projectDir)) return "";
+	if (!isProject(projectDir)) return "";
+	writeTree(projectDir, out, "", EXCLUDE_DIRS$1);
+	return "";
+}
+//#endregion
+//#region src/policy/cartographer/build-tree.ts
+const SECTION_ORDER = [
+	"agent",
+	"skill",
+	"command"
+];
+/**
+* Format grouped items with tree connectors and optional markdown links.
+* Skill sections link to `./skills/<name>/index.md`; other sections to
+* `./<folder>/<name>.md`; unlinked sections render the bare name.
+* @param prefix - The line prefix (indent + branch glyphs).
+* @param items - The `[name, desc]` pairs to render.
+* @param folder - The link folder ("" disables linking).
+* @param asDirs - Whether items link to a subdirectory `index.md`.
+* @returns The rendered lines.
+*/
+function printItems(prefix, items, folder, asDirs) {
+	return items.map(([name, desc], i) => {
+		const connector = i === items.length - 1 ? "└──" : "├──";
+		const safe = name.replace(/^\/+/, "");
+		let label = name;
+		if (folder && asDirs) label = `[${name}](./${folder}/${safe}/index.md)`;
+		else if (folder) label = `[${name}](./${folder}/${safe}.md)`;
+		const short = desc && desc !== "(no description)" ? ` — ${desc.slice(0, 80)}` : "";
+		return `${prefix}${connector} ${label}${short}`;
+	});
+}
+/**
+* Build an indented tree from scanned items. The `hooks` row renders as a single
+* trailing `└── hooks: …` line; agents/skills/commands render as folder sections.
+* @param items - The scanned `[type, name, desc]` rows.
+* @param linked - When true, leaf names become markdown links.
+* @returns The joined tree text.
+*/
+function buildTree(items, linked = false) {
+	const groups = {};
+	let hooksLine = "";
+	for (const [typ, name, desc] of items) if (typ === "hooks") hooksLine = name;
+	else (groups[typ] ??= []).push([name, desc]);
+	const sections = SECTION_ORDER.filter((s) => s in groups);
+	if (hooksLine) sections.push("hooks");
+	const lines = [];
+	const total = sections.length;
+	for (let idx = 0; idx < total; idx++) {
+		const section = sections[idx] ?? "";
+		if (section === "hooks") {
+			lines.push(`└── hooks: ${hooksLine}`);
+			continue;
+		}
+		const isLast = idx === total - 1;
+		const folder = `${section}s`;
+		const prefix = isLast ? "└──" : "├──";
+		const subPrefix = isLast ? "    " : "│   ";
+		lines.push(`${prefix} ${folder}/`);
+		const linkFolder = linked ? folder : "";
+		const isDirSection = section === "skill";
+		lines.push(...printItems(subPrefix, groups[section] ?? [], linkFolder, linked && isDirSection));
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/runtime/lifecycle/cartographer/write-plugin-map.ts
+/**
+* Per-plugin map writer (fs). Ports `write_plugin_map.py`: writes a level-2
+* `<plugin>/index.md` (indented linked tree) then recurses agents/skills/
+* commands into deeper index trees. Reuses `buildTree`, `mergeLines`, `writeTree`.
+*/
+/** True when `dir` is a real directory. */
+function isDir(dir) {
 	try {
-		if (prompt && prompt.kind !== "block") return;
-		const op = denyHash("op", {
-			filePath: input.filePath,
-			command: input.command
+		return statSync(dir).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/**
+* Write `<outputDir>/<pluginName>/index.md` (indented linked tree) and recurse
+* agents/skills/commands into their own index trees rooted there.
+* @param outputDir - The map root directory.
+* @param pluginName - Display name of the plugin (the index subfolder).
+* @param version - Plugin version ("" to omit).
+* @param items - The scanned `[type, name, desc]` rows.
+* @param pluginPath - Absolute source plugin directory (for recursion).
+*/
+function writePluginMap(outputDir, pluginName, version, items, pluginPath) {
+	const pluginDir = join(outputDir, pluginName);
+	mkdirSync(pluginDir, { recursive: true });
+	const newLines = `# ${pluginName}${version ? ` (v${version})` : ""}\n\n${items.length ? buildTree(items, true) : "└── (empty)"}`.split("\n");
+	const indexPath = join(pluginDir, "index.md");
+	writeFileSync(indexPath, mergeLines(newLines, indexPath).join("\n") + "\n", "utf-8");
+	for (const section of [
+		"agents",
+		"skills",
+		"commands"
+	]) {
+		const src = join(pluginPath, section);
+		if (isDir(src)) writeTree(src, join(pluginDir, section), "../index.md");
+	}
+}
+//#endregion
+//#region src/runtime/lifecycle/cartographer/ecosystem-map.ts
+/**
+* Ecosystem (plugin) map generation (fs). Ports `generate_map.py`: scans every
+* installed plugin into a level-1 `.cartographer/index.md` + per-plugin level-2+
+* trees, preserving enriched descriptions. Reuses `findMarketplacePlugins`,
+* `readPluginMeta`, `scanPlugin`, `mergeLines`, `writePluginMap`.
+*/
+function pluginDirs(dir) {
+	let entries = [];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return [];
+	}
+	return entries.filter((n) => !n.startsWith("_") && !n.startsWith(".")).filter((n) => {
+		try {
+			return statSync(join(dir, n)).isDirectory();
+		} catch {
+			return false;
+		}
+	}).sort((a, b) => a.localeCompare(b, "en"));
+}
+function utcStamp(now) {
+	return new Date(now).toISOString().slice(0, 16).replace("T", " ");
+}
+/**
+* Generate the plugin ecosystem map under `<pluginsDir>/.cartographer`.
+* @param now - Clock for the banner timestamp.
+* @param pluginsDirOverride - Override for the marketplace plugins directory.
+* @returns The map navigation context, or "".
+*/
+function generateEcosystemMap(now, pluginsDirOverride) {
+	const pluginsDir = resolve(pluginsDirOverride ?? findMarketplacePlugins());
+	try {
+		if (!statSync(pluginsDir).isDirectory()) return "";
+	} catch {
+		return "";
+	}
+	const outputDir = join(pluginsDir, ".cartographer");
+	mkdirSync(outputDir, { recursive: true });
+	const dirs = pluginDirs(pluginsDir);
+	const lines = [`# Ecosystem Map (${dirs.length} plugins)\n`, `> Auto-generated by cartographer — ${utcStamp(now)}\n`];
+	for (const name of dirs) {
+		const pluginPath = join(pluginsDir, name);
+		const [version, pkgName] = readPluginMeta(pluginPath);
+		const display = pkgName || name;
+		const items = scanPlugin(pluginPath);
+		const agents = items.filter(([t]) => t === "agent").map(([, n]) => n);
+		const ver = version ? ` (v${version})` : "";
+		lines.push(`- [${display}](./${display}/index.md)${ver} → ${agents.length ? agents.join(", ") : "(no agents)"}`);
+		writePluginMap(outputDir, display, version, items, pluginPath);
+		writePluginMap(pluginPath, ".cartographer", version, items, pluginPath);
+	}
+	const indexPath = join(outputDir, "index.md");
+	writeFileSync(indexPath, mergeLines(lines, indexPath).join("\n") + "\n", "utf-8");
+	return `Project map: .cartographer/project/index.md — navigate project files. Plugin skills map: ${outputDir}/index.md — navigate agent skills. Branches link to deeper index.md, leaves link to real files.`;
+}
+//#endregion
+//#region src/runtime/lifecycle/cartographer/session-start.ts
+/**
+* Cartographer SessionStart handler. Ports BOTH halves of the Python maps:
+* `generate_project_map.py` (regenerate `.cartographer/project`) and
+* `generate_map.py` (regenerate the plugin ecosystem map), emitting the
+* navigation context from the latter as additionalContext.
+*/
+/**
+* Resolve the marketplace plugins dir from `CLAUDE_PLUGIN_ROOT`, mirroring the
+* Python hook which passes `${CLAUDE_PLUGIN_ROOT}/..` to `generate_map.py`.
+* @returns The plugins dir (env `/..`), or `undefined` to fall back to auto-detect.
+*/
+function pluginsDirFromEnv() {
+	const root = process.env.CLAUDE_PLUGIN_ROOT;
+	return root ? resolve(root, "..") : void 0;
+}
+/**
+* Regenerate the project map + plugin ecosystem map for `cwd` on SessionStart.
+* Emits the ecosystem navigation context as additionalContext (or "").
+* @param cwd - The working directory.
+* @param now - Clock for the ecosystem map banner timestamp.
+* @returns The SessionStart additionalContext response, or "".
+*/
+function cartoSessionStart(cwd, now = Date.now()) {
+	generateProjectMap(cwd);
+	const ctx = generateEcosystemMap(now, pluginsDirFromEnv());
+	return ctx ? contextResponse("SessionStart", ctx) : "";
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/lesson-parse.ts
+/** Milliseconds in a day. */
+const DAY_MS = 864e5;
+/** Case-sensitive decision-time tag line (`[TRIGGERS …]`) — opus-lessons format. */
+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));
+}
+/** True when a block carries a `[TRIGGERS …]` continuation line. */
+function hasTrigger(b) {
+	return b.raw.some((l) => TRIG.test(l.trim()));
+}
+/** Split content 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)
 		});
-		if (!burstFirst(op, prompt ? `deny:${prompt.title}` : "allow", opts)) return;
-		const path = join(opts.dir, SIDECAR$1);
-		let s = pruneState(loadState(path), opts.now, WINDOW_MS);
-		s = prompt ? applyDeny(s, prompt.title, op, opts.now) : applyAllow(s, op, opts.now, input.content != null || input.command != null);
-		atomicWrite(path, JSON.stringify(s));
-	} catch {}
+		else if (l.trim() && last) last.raw.push(l);
+	}
+	return {
+		preamble,
+		blocks
+	};
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/lesson-archive.ts
+/**
+* Stage 1 — cap→archive split for LESSON.md. When deduped bullets exceed CAP the
+* OLDEST excess is MOVED (never deleted) to LESSON-archive.md, EXCEPT a
+* `[TRIGGERS …]` bullet younger than STALE_DAYS: archiving it would blind the
+* PreToolUse trigger index (src/policy/lessons/trigger-index reads LESSON.md), so
+* it stays even past the cap. Pure: this module decides the partition and renders
+* the archive block; the fail-safe, archive-first file write is the caller's job.
+*/
+/** Sort key: undated bullets sort oldest, so malformed entries archive first. */
+function age(b) {
+	return Number.isNaN(b.ts) ? -Infinity : b.ts;
+}
+/** A TRIGGERS bullet is protected from archival until older than STALE_DAYS. */
+function isProtected(b, staleBefore) {
+	return hasTrigger(b) && !(b.ts <= staleBefore);
+}
+/**
+* Partition deduped `blocks` (newest-first file order) into the bullets that
+* stay in LESSON.md and the oldest excess to archive. Archives only enough to
+* reach CAP, skipping protected TRIGGERS bullets (so the file MAY stay slightly
+* over cap by design). Order is preserved in both halves; `keep ∪ archive` is
+* exactly `blocks` with no loss and no mutation.
+* @param blocks - Deduped bullets, newest first.
+* @param now - Clock (ms) for the STALE_DAYS protection window.
+* @returns `{ keep, archive }` — a lossless partition of `blocks`.
+*/
+function splitAtCap(blocks, now) {
+	if (blocks.length <= 50) return {
+		keep: blocks,
+		archive: []
+	};
+	const staleBefore = now - 90 * DAY_MS;
+	const oldestFirst = [...blocks].sort((a, b) => age(a) - age(b));
+	const toArchive = /* @__PURE__ */ new Set();
+	let excess = blocks.length - 50;
+	for (const b of oldestFirst) {
+		if (excess <= 0) break;
+		if (isProtected(b, staleBefore)) continue;
+		toArchive.add(b);
+		excess--;
+	}
+	return {
+		keep: blocks.filter((b) => !toArchive.has(b)),
+		archive: blocks.filter((b) => toArchive.has(b))
+	};
 }
 /**
-* Compact, injection-ready one-shot summary for the project rooted at `cwd`. The
-* state dir is derived EXACTLY like the runtime writer ({@link defaultStateDir},
-* mirroring `handle.ts` `trackFile(sid, defaultStateDir(cwd))`), so the file read
-* here is the same one {@link recordOneShot} wrote. "" when no data or read error.
-* @param cwd - The project working directory (Claude `cwd`), NOT the state dir.
-* @returns One line, e.g. `gates 7d: 88% one-shot (44/50 clean); ...`, or "".
+* Render `archive` bullets as a dated block to PREPEND to LESSON-archive.md
+* (newest archive session on top). Bullets are emitted BYTE-IDENTICAL (raw lines
+* rejoined) — zero mutation, so the move stays reversible/auditable.
+* @param archive - Bullets chosen by {@link splitAtCap}.
+* @param now - Clock (ms) for the archival header date.
+* @returns The block text (trailing newline), or "" when nothing is archived.
 */
-function oneShotSummary(cwd) {
-	try {
-		return formatSummary(pruneState(loadState(join(defaultStateDir(cwd), SIDECAR$1)), Date.now(), WINDOW_MS));
-	} catch {
-		return "";
-	}
+function formatArchive(archive, now) {
+	if (archive.length === 0) return "";
+	return `${`<!-- archived ${new Date(now).toISOString().slice(0, 10)}: ${archive.length} bullet(s) moved from LESSON.md at cap 50 -->`}\n${archive.map((b) => b.raw.join("\n")).join("\n\n")}\n`;
 }
 //#endregion
-//#region src/runtime/lifecycle/snapshot/git.ts
+//#region src/runtime/lifecycle/aipilot/curate-lessons.ts
 /**
-* Run a git subcommand at `root` with a short timeout, returning trimmed stdout.
-* Uses `node:child_process` (the Bun shell can hang on some git plumbing) and
-* swallows every failure — a non-repo, missing git, or timeout yields `""` so
-* the caller omits the section instead of throwing inside the hook.
-* @param root - Directory to run git in.
-* @param args - The git args (e.g. `"log --oneline -3"`).
-* @returns Trimmed stdout, or `""` on any error.
+* Stage-0 mechanical, LLM-free dedup of MEMORY/LESSON.md bullets + cap→archive
+* orchestration. Strict-dedup near-identical bullets (keep newest, `[TRIGGERS …]`
+* preserved), then hand the deduped set to lesson-archive's cap split. Returns the
+* rewritten LESSON.md content, the archive block to move out, and a human report.
+* Pure: all file I/O (archive-first, fail-safe) lives in the dispatch caller.
 */
-function git(root, args) {
-	try {
-		return execSync(`git ${args}`, {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 150,
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			]
-		}).trim();
-	} catch {
-		return "";
-	}
+const SIM_THRESHOLD = .8;
+const MIN_TOKENS = 4;
+/** Report lines for bullets older than STALE_DAYS whose only cited path is gone. */
+function staleReport(blocks, now, root) {
+	const cutoff = now - 90 * DAY_MS;
+	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)} — missing path(s): ${paths.join(", ")}`];
+	});
 }
-/** Count staged/unstaged/untracked files from porcelain v1 output (skips the `##` branch line). */
-function countWip(porcelain) {
-	const w = {
-		staged: 0,
-		unstaged: 0,
-		untracked: 0
-	};
-	for (const line of porcelain.split("\n")) {
-		if (!line || line.startsWith("#")) continue;
-		if (line.startsWith("??")) {
-			w.untracked++;
+/** Strict-dedup: keep the newest of each near-identical pair (TRIGGERS carried over). Returns kept blocks + merge report lines. */
+function dedup(blocks) {
+	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 x = line[0], y = line[1];
-		if (x && x !== " " && x !== "?") w.staged++;
-		if (y === "M" || y === "D") w.unstaged++;
+		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(`merged: kept ${(win.raw[0] ?? "").slice(0, 60)} · dropped ${(drop.raw[0] ?? "").slice(0, 60)}`);
 	}
-	return w;
-}
-/** Parse the current branch from the leading `## branch...upstream` porcelain line. */
-function parseBranch(porcelain) {
-	const head = porcelain.split("\n")[0] ?? "";
-	if (!head.startsWith("## ")) return "";
-	const rest = head.slice(3);
-	const dots = rest.indexOf("...");
-	return (dots >= 0 ? rest.slice(0, dots) : rest).split(" ")[0] ?? "";
+	return {
+		kept,
+		fused
+	};
 }
 /**
-* Collect a compact git reconciliation section for `root`: current branch, the
-* last three commits (oneline), and staged/unstaged/untracked WIP counts. When
-* `root` is not a git repo (status fails) the whole section is omitted (`""`).
-* @param root - The project/repo root.
-* @returns The rendered git section body, or `""` when not a repo.
+* Dedup LESSON.md bullets, then archive the oldest excess over CAP (via
+* lesson-archive). `content` is byte-identical to the input when nothing is
+* deduped or archived. The `archive` block (possibly "") is what the caller must
+* PREPEND to LESSON-archive.md, archive-first, before writing `content`.
+* @param content - Raw LESSON.md text.
+* @param now - Clock (ms) for stale/archival windows.
+* @param root - Project root, for resolving cited paths in the stale report.
+* @returns The rewritten content, the archive block, and the report.
 */
-function collectGit(root) {
-	const status = git(root, "status --porcelain=v1 --branch");
-	if (!status) return "";
-	const branch = parseBranch(status) || "(unknown)";
-	const w = countWip(status);
-	const log = git(root, "log --oneline -3");
-	const lines = [`- branch: ${branch}`];
-	if (log) lines.push("- recent:", ...log.split("\n").map((l) => `    ${l}`));
-	lines.push(`- WIP: ${w.staged} staged, ${w.unstaged} unstaged, ${w.untracked} untracked`);
-	return lines.join("\n");
+function curateLessons(content, now, root = process.cwd()) {
+	const { preamble, blocks } = parse(content);
+	const { kept, fused } = dedup(blocks);
+	const { keep, archive } = splitAtCap(kept, now);
+	const rebuilt = fused.length > 0 || archive.length > 0 ? `${preamble}\n${keep.map((b) => b.raw.join("\n")).join("\n\n")}\n` : content;
+	const capReport = archive.length ? [`${kept.length} bullets (> 50) — ${archive.length} oldest archived → LESSON-archive.md`] : [];
+	const report = [
+		...fused,
+		...capReport,
+		...staleReport(blocks, now, root)
+	].join("\n");
+	return {
+		content: rebuilt,
+		archive: formatArchive(archive, now),
+		report
+	};
+}
+/** The `[YYYY-MM-DD HH:MM]` (or date-only) stamp of a bullet, "" if absent. */
+function stamp(block) {
+	return (block.raw[0] ?? "").match(/\[(\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2})?)\]/)?.[1] ?? "";
+}
+/** Bullet text: raw lines joined, leading "- ", date stamp & TRIGGERS lines stripped. */
+function bodyText(block) {
+	return block.raw.filter((l) => !/^\s*\[TRIGGERS\s/.test(l)).join(" ").replace(/^-\s*/, "").replace(/\[\d{4}-\d{2}-\d{2}[^\]]*\]\s*/, "").trim();
+}
+/** First sentence of `s` (split on a period + whitespace), whole string if none. */
+function firstSentence(s) {
+	return (s.split(/(?<=\.)\s/)[0] ?? s).trim();
 }
-//#endregion
-//#region src/cli/doctor.ts
 /**
-* `harness doctor` — diagnose which `@fusengine/harness` is actually running.
-*
-* A confirmed, still-open bun bug (oven-sh/bun #5791; scoped-pkg behaviour
-* reinforced by #32019/#32150) makes `bunx <pkg>` (unpinned) prefer a stale
-* GLOBAL install over npm-latest, so a consumer can silently run an old harness
-* after a publish. This command surfaces the truth: the resolved version +
-* package path of the code executing right now, the runtime binary, and the
-* latest version published on npm. It queries the registry over HTTP (not
-* `npm view`, whose exit code is 0 even on an empty result — npm/cli#6408) and
-* never throws: an offline environment yields `latest: null`, never a crash.
+* The bullet's `narrative → rule` delimiter: a SPACED arrow only. A GLUED arrow
+* between tokens (e.g. `120s→300s`, `s→3`) is prose the author wrote, never a
+* delimiter — matching on `→` alone chopped rules mid-token (bug: `300s) pensant
+* corriger…`). Also used to split rule-internal clauses.
 */
-const PKG = "@fusengine/harness";
-/** Walk up from `startDir` for the `@fusengine/harness` `package.json`. */
-function findPackage(startDir) {
-	let dir = startDir;
-	for (let depth = 0; depth < 6; depth++) {
-		try {
-			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
-			if (pkg.name === PKG) return {
-				version: pkg.version ?? "unknown",
-				path: dir
-			};
-		} catch {}
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	return null;
+const RULE_ARROW = /\s+→\s+/;
+/**
+* Distil the actionable rule from a bullet body. With no spaced arrow the whole
+* bullet is the rule → its first sentence. Otherwise the rule is everything after
+* the FIRST spaced arrow; its spaced-arrow-delimited segments are kept whole
+* except for TRAILING short asides (< {@link MIN_RULE} chars, e.g. `→ (cf.
+* lecture).`) which are dropped — so an arrow used as PROSE inside a rule (`maps
+* X → Y doit…`) is preserved intact rather than chopped at the arrow. When the
+* kept rule is still under {@link MIN_RULE} chars, fall back to the first sentence
+* of the WHOLE rule part (never the narrative), avoiding an illegible stub.
+*/
+function distillRule(text) {
+	const sep = text.search(RULE_ARROW);
+	if (sep < 0) return firstSentence(text);
+	const rulePart = text.slice(sep).replace(RULE_ARROW, "").trim();
+	const segments = rulePart.split(RULE_ARROW).map((s) => s.trim()).filter(Boolean);
+	while (segments.length > 1 && (segments[segments.length - 1]?.length ?? 0) < 40) segments.pop();
+	const rule = firstSentence(segments.join(" → "));
+	return rule.length >= 40 ? rule : firstSentence(rulePart);
 }
-/** Resolve the running version + package path (no network), from a module URL. */
-function runningVersion(moduleUrl) {
-	const found = findPackage(dirname(fileURLToPath(moduleUrl)));
-	return {
-		version: found?.version ?? "unknown",
-		path: found?.path ?? "unknown"
-	};
+/** Collapse one older bullet to `- [date] <rule>`: {@link distillRule}, capped. */
+function compressBullet(block) {
+	let rule = distillRule(bodyText(block));
+	if (rule.length > 200) rule = `${rule.slice(0, 199).trimEnd()}…`;
+	const date = stamp(block);
+	return `- ${date ? `[${date}] ` : ""}${rule}`;
 }
-/** One-line `pkg vX.Y.Z` banner (stderr, only on explicit `--version`/`doctor` commands — never on `hook`, to avoid spamming automated invocations). */
-function versionBanner(moduleUrl) {
-	return `${PKG} v${runningVersion(moduleUrl).version}`;
+/**
+* Build the compressed injection body for `content`. The preamble comments are
+* dropped (format docs, noise for the reader); the `recentFull` newest bullets
+* stay whole, every older bullet becomes one distilled rule-line.
+* @param content - Raw LESSON.md text.
+* @param recentFull - Count of newest bullets to keep verbatim.
+* @returns The compressed block (bullets only), or the trimmed content when there are no bullets.
+*/
+function compressInjection(content, recentFull = 10) {
+	const { blocks } = parse(content);
+	if (blocks.length === 0) return content.trim();
+	const full = blocks.slice(0, recentFull).map((b) => b.raw.join("\n"));
+	const rest = blocks.slice(recentFull).map(compressBullet);
+	return [...full, ...rest].join("\n");
+}
+//#endregion
+//#region src/memory/session-roots.ts
+/**
+* Session-scoped lessons roots registry. The flat {@link module:memory/registry}
+* keeps ONE global list of pending roots — correct mono-session, but wrong with
+* several concurrent Claude Code sessions: at Stop, one session lists (and, by
+* bumping the throttle, STEALS) another session's pending lesson on a project it
+* never touched. This registry keys "which project got code edits, and was its
+* Stop reminder already fired" by `session_id`, so each Stop sees and consumes
+* ONLY its own roots. Stored at `$HOME/.fuse-harness/cache/lessons/session-roots.json`;
+* non-fatal on any I/O failure (a missed reminder never blocks a session).
+*/
+/** Registry path (rel. home) + stale-bucket purge horizon (bounds growth). */
+const SUBPATH = ".fuse-harness/cache/lessons/session-roots.json";
+const PURGE_MS = 10080 * 60 * 1e3;
+/** Absolute registry path, or null when home is unusable. */
+function file(home) {
+	const h = home?.trim();
+	return h && h.startsWith("/") ? `${h}/${SUBPATH}` : null;
 }
-/** Latest published version via the npm registry HTTP API. `null` on any failure. */
-async function npmLatest() {
+/** Read the registry; missing/corrupt/legacy (array) shapes collapse to `{}`. */
+function read(home) {
+	const f = file(home);
+	if (!f) return {};
 	try {
-		const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: AbortSignal.timeout(8e3) });
-		if (!res.ok) return null;
-		return (await res.json()).version ?? null;
+		const parsed = JSON.parse(readFileSync(f, "utf8"));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
 	} catch {
-		return null;
+		return {};
 	}
 }
-/** Build the full diagnostic report for the module at `moduleUrl`. */
-async function buildDoctorReport(moduleUrl) {
-	const { version, path } = runningVersion(moduleUrl);
-	const latest = await npmLatest();
-	return {
-		running: version,
-		packagePath: path,
-		runtime: process.execPath,
-		latest,
-		stale: latest !== null && latest !== version
-	};
+/** Purge stale buckets, then atomically persist (unique tmp + rename). Non-throwing. */
+function write(home, reg, now) {
+	const f = file(home);
+	if (!f) return;
+	for (const [sid, entry] of Object.entries(reg)) if (!entry || now - (entry.updatedAt ?? 0) > PURGE_MS) delete reg[sid];
+	try {
+		mkdirSync(dirname(f), { recursive: true });
+		atomicWrite(f, JSON.stringify(reg));
+	} catch {}
 }
-/** Render a {@link DoctorReport} as human-readable stdout text. */
-function formatDoctor(r) {
-	const lines = [
-		`${PKG} doctor`,
-		`  running:    ${r.running}`,
-		`  package:    ${r.packagePath}`,
-		`  runtime:    ${r.runtime}`,
-		`  npm latest: ${r.latest ?? "(unavailable — offline or unreachable)"}`
-	];
-	if (r.stale) lines.push(`  ! stale — npm serves ${r.latest}. Pin "@fusengine/harness@${r.latest}" in hooks.json (see README).`);
-	else if (r.latest !== null) lines.push(`  ok — running the latest published version.`);
-	return lines.join("\n");
+/** Record `field` for `(sid, root)`, refreshing the purge cursor. `home` defaults to `$HOME`. */
+function markSessionRoot(sid, root, field, value, home = process.env.HOME) {
+	const reg = read(home);
+	const prev = reg[sid];
+	const entry = prev && typeof prev.roots === "object" && prev.roots !== null ? prev : {
+		updatedAt: value,
+		roots: {}
+	};
+	const mark = entry.roots[root] ?? {
+		editedAt: 0,
+		remindedAt: 0
+	};
+	entry.roots[root] = {
+		...mark,
+		[field]: value
+	};
+	entry.updatedAt = value;
+	reg[sid] = entry;
+	write(home, reg, value);
 }
-/** Run `harness doctor`: print the diagnostic to stdout. Always resolves 0 (pure info). */
-async function runDoctor(moduleUrl) {
-	process.stdout.write(formatDoctor(await buildDoctorReport(moduleUrl)) + "\n");
-	return 0;
+/**
+* Roots of `sid` with an unsaved code edit past the `window`; each returned
+* root's `remindedAt` is bumped to `now` so the reminder fires at most once per
+* window and is consumed ONLY by this session. `home` defaults to `$HOME`.
+*/
+function collectSessionPending(sid, now, window, home = process.env.HOME) {
+	const reg = read(home);
+	const entry = reg[sid];
+	if (!entry || typeof entry.roots !== "object" || entry.roots === null) return [];
+	const pending = [];
+	for (const [root, mark] of Object.entries(entry.roots)) {
+		if (mark.editedAt <= mark.remindedAt) continue;
+		if (now - mark.remindedAt < window) continue;
+		pending.push(root);
+		entry.roots[root] = {
+			...mark,
+			remindedAt: now
+		};
+	}
+	if (pending.length > 0) write(home, reg, now);
+	return pending;
 }
 //#endregion
-//#region src/runtime/lifecycle/snapshot/version.ts
-/** Read the `version` field of `<root>/package.json`, or `""` if absent/unreadable. */
-function pkgVersion(root) {
-	try {
-		return JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version ?? "";
-	} catch {
-		return "";
+//#region src/runtime/lifecycle/lessons/reminder.ts
+/**
+* fuse-lessons write-mark + Stop-reminder, scoped by `session_id` when present.
+*
+* WITH a session id (normal Claude Code): each `(session, root)` pair carries
+* its own edit/reminder throttle in {@link module:memory/session-roots}, so a
+* Stop lists and silences ONLY the roots THAT session edited — concurrent
+* sessions on different projects never cross-remind nor steal each other's
+* throttle. WITHOUT a usable session id (a harness that omits it, or the legacy
+* on-disk state) it falls back to the original mono-session behavior: the global
+* flat root registry + the per-project `MEMORY/state.json` throttle.
+*/
+/** Sanitized session id from a raw hook payload, or null (→ legacy fallback). */
+function sessionOf(payload) {
+	return sanitizeSessionId(payload.session_id);
+}
+/** Legacy (no session id): pending roots across the global flat registry. */
+function collectLegacyPending(now, window) {
+	const pending = [];
+	for (const root of readRoots()) {
+		const stateFile = lessonsStateFileFor(root);
+		const { lastRemindedAt, lastCodeEditAt } = readState(stateFile);
+		if (lastCodeEditAt <= lastRemindedAt) continue;
+		if (now - lastRemindedAt < window) continue;
+		pending.push(root);
+		setStateField(stateFile, "lastRemindedAt", now);
 	}
+	return pending;
+}
+/** Stop reminder body listing each pending project's lessons file. */
+function reminderText(pending) {
+	return `Before ending: if this session hit a mistake/blocker worth never reproducing, append 1-3 COMPACT bullets OR sharpen/merge existing ones (format \`- [${nowStamp()}] what went wrong → do instead\`, use exactly this timestamp) in each project's lessons file below. Skip if nothing notable.\n${pending.map((r) => `- ${r}/MEMORY/LESSON.md`).join("\n")}`;
 }
 /**
-* Collect the version reconciliation section: the harness version actually
-* running (resolved from {@link runningVersion}, no network) and, when `root`
-* carries its own `package.json`, whether that project's version has drifted
-* from the running harness.
-* @param root - The project root (cwd repo).
-* @param moduleUrl - `import.meta.url` of the calling module (locates the running package.json).
-* @returns The rendered version section body (never `""`).
+* Stop: emit one reminder covering the stopping session's pending projects.
+* @param payload - Raw hook payload (`session_id` selects the scoped path).
+* @param now - Clock.
+* @returns Native Stop stdout, or "" when nothing is pending.
 */
-function collectVersion(root, moduleUrl) {
-	const running = runningVersion(moduleUrl).version;
-	const lines = [`- harness running: v${running}`];
-	const project = pkgVersion(root);
-	if (project && project !== running) lines.push(`- project package.json: v${project} (DRIFT — running harness differs)`);
-	else if (project) lines.push(`- project package.json: v${project} (in sync)`);
-	return lines.join("\n");
+function remindWrite(payload, now) {
+	const window = throttleMs();
+	const sid = sessionOf(payload);
+	const pending = sid ? collectSessionPending(sid, now, window) : collectLegacyPending(now, window);
+	if (pending.length === 0) return "";
+	return contextResponse("Stop", reminderText(pending));
 }
-//#endregion
-//#region src/runtime/lifecycle/snapshot/board.ts
-/** Max board characters injected — a persistent board should stay small; over-long boards are truncated. */
-const MAX_BOARD = 4e3;
 /**
-* Collect the persistent task board: the contents of `<root>/.claude/BOARD.md`
-* (truncated to {@link MAX_BOARD}) plus an instruction to keep it current. The
-* board lives on disk so it survives context purges — rehydrated every session.
-* Missing/empty/unreadable board → `""` (section omitted).
-* @param root - The project root.
-* @returns The rendered board section body, or `""` when there is no board.
+* PostToolUse: record the edit against the throttle. A code file arms the
+* reminder; writing `MEMORY/LESSON.md` silences it (the lesson was just saved).
+* Session-scoped when `session_id` is present, else the legacy global path.
+* @param payload - Raw hook payload (`tool_input.file_path`, `session_id`).
+* @param now - Clock.
 */
-function collectBoard(root) {
-	const path = join(root, ".claude", "BOARD.md");
-	try {
-		if (!existsSync(path)) return "";
-		let body = readFileSync(path, "utf8").trim();
-		if (!body) return "";
-		if (body.length > MAX_BOARD) body = `${body.slice(0, MAX_BOARD)}\n… (truncated)`;
-		return `- .claude/BOARD.md (keep current — Write to it as tasks start/finish):\n\n${body}`;
-	} catch {
-		return "";
+function markWrite(payload, now) {
+	const input = payload.tool_input;
+	if (!input?.file_path) return;
+	const abs = resolve(input.file_path);
+	const root = projectRootOrNull(dirname(abs));
+	if (!root) return;
+	const isLesson = abs === resolve(root, "MEMORY", "LESSON.md");
+	if (!isLesson && !isCodeFile(abs)) return;
+	const sid = sessionOf(payload);
+	if (sid) markSessionRoot(sid, root, isLesson ? "remindedAt" : "editedAt", now);
+	else if (isLesson) setStateField(lessonsStateFileFor(root), "lastRemindedAt", now);
+	else {
+		setStateField(lessonsStateFileFor(root), "lastCodeEditAt", now);
+		addRoot(root);
 	}
 }
 //#endregion
-//#region src/runtime/lifecycle/snapshot/format.ts
+//#region src/runtime/lifecycle/lessons/dispatch.ts
 /**
-* Render the non-empty `sections` under one reconciliation heading. Empty
-* sections are dropped; when every section is empty the whole snapshot is `""`.
-* @param sections - The collected sections in display order.
-* @returns The assembled markdown block, or `""` when nothing to report.
+* fuse-lessons scope dispatch (TS port of the 4 handler scripts). Routes by
+* event: SessionStart/SubagentStart inject `MEMORY/LESSON.md`; Stop reminds the
+* stopping session about ITS OWN projects with unsaved code edits; PostToolUse
+* marks the write to arm/silence the throttle. The reminder + mark logic (incl.
+* the per-`session_id` scoping that fixes the multi-session misdirection) lives
+* in {@link module:runtime/lifecycle/lessons/reminder}; this module keeps the
+* event router + lesson-file injection. Non-fatal by design.
 */
-function renderSections(sections) {
-	const parts = sections.filter((s) => s.body.trim()).map((s) => `### ${s.title}\n${s.body.trim()}`);
-	if (!parts.length) return "";
-	return `# Reconciliation snapshot
-Real state of the world at session start — reconcile against this instead of re-discovering it.\n\n${parts.join("\n\n")}`;
-}
 /**
-* Concatenate `snapshot` onto an existing SessionStart stdout's
-* `additionalContext` — it never replaces prior injected context (CLAUDE.md,
-* dev-context). When `stdout` is empty a fresh {@link contextResponse} is made;
-* a non-empty but unparseable `stdout` is returned UNCHANGED (the snapshot is
-* dropped) — fabricating a fresh response there would discard the very CLAUDE.md
-* injection the invariant protects, so preserving prior context always wins.
-* @param stdout - The core SessionStart JSON stdout (may be `""`).
-* @param snapshot - The snapshot markdown to append (no-op when `""`).
-* @returns The merged hook stdout JSON.
+* Persist a curation ATOMICALLY and ARCHIVE-FIRST for zero-loss: prepend the
+* moved bullets to LESSON-archive.md, THEN rewrite LESSON.md. On ANY write error
+* the original file is left untouched (returns `original`) so a bullet is never
+* lost — a rare archive-then-trim-fail leaves a duplicate (never a loss), which
+* the next dedup pass reconciles.
 */
-function attachSnapshot(stdout, snapshot) {
-	if (!snapshot) return stdout;
-	if (!stdout) return contextResponse("SessionStart", snapshot);
+function persistCuration(file, root, curated, archive, original) {
 	try {
-		const parsed = JSON.parse(stdout);
-		const prev = parsed.hookSpecificOutput?.additionalContext ?? "";
-		const merged = prev ? `${prev}\n\n${snapshot}` : snapshot;
-		return JSON.stringify({
-			...parsed,
-			hookSpecificOutput: {
-				...parsed.hookSpecificOutput,
-				hookEventName: "SessionStart",
-				additionalContext: merged
-			}
-		});
+		if (archive) {
+			const af = lessonsArchiveFileFor(root);
+			const prev = existsSync(af) ? readFileSync(af, "utf-8") : "";
+			atomicWrite(af, prev ? `${archive}\n${prev}` : archive);
+		}
+		atomicWrite(file, curated);
+		return curated;
 	} catch {
-		return stdout;
+		return original;
 	}
 }
-//#endregion
-//#region src/runtime/lifecycle/snapshot/index.ts
-/** Run `fn`, swallowing any throw into `""` so no single collector can break the hook. */
-function safe(fn) {
+/**
+* Inject `MEMORY/LESSON.md` for `event`. Mechanical curation (dedup + cap→archive)
+* rewrites the FILE; the injected BLOCK is then COMPRESSED (newest bullets whole,
+* older ones distilled to their rule) so a growing file never inflates the
+* SessionStart/SubagentStart context. A hard {@link capFragment} budget is the
+* last-resort backstop on top of compression — the regression that motivated it
+* was this exact block silently reaching ~44k tokens. Any curation report
+* surfaces via systemMessage.
+*/
+function injectMemory(cwd, event, now) {
+	const root = projectRoot(cwd);
+	const file = lessonsFileFor(root);
+	if (!existsSync(file)) return "";
+	let content = "";
 	try {
-		return fn();
+		content = readFileSync(file, "utf-8").trim();
 	} catch {
 		return "";
 	}
+	if (!content) return "";
+	const { content: curated, archive, report } = curateLessons(content, now, root);
+	if (curated !== content) content = persistCuration(file, root, curated, archive, content);
+	const ctx = `Project lessons — never reproduce these:\n${capFragment("lessons", compressInjection(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);
 }
 /**
-* Build the reconciliation snapshot markdown for `cwd`: git state, running
-* harness version + drift, the persistent board, and one-shot gate status. Each
-* collector is isolated by {@link safe}; an all-empty result yields `""`.
-* @param cwd - The session working directory.
-* @param moduleUrl - `import.meta.url` of the caller (locates the running package).
-* @returns The snapshot markdown, or `""` when nothing to report.
-*/
-function renderSnapshot(cwd, moduleUrl) {
-	const root = projectRootOrNull(cwd) ?? cwd;
-	return renderSections([
-		{
-			title: "Git",
-			body: safe(() => collectGit(root))
-		},
-		{
-			title: "Version",
-			body: safe(() => collectVersion(root, moduleUrl))
-		},
-		{
-			title: "Board",
-			body: safe(() => collectBoard(root))
-		},
-		{
-			title: "One-shot gates",
-			body: safe(() => oneShotSummary(cwd))
-		}
-	]);
-}
-/**
-* Concatenate the reconciliation snapshot onto a core SessionStart stdout. Fully
-* fail-safe: any error returns `stdout` unchanged so the hook never breaks.
-* @param stdout - The core SessionStart JSON stdout (may be `""`).
-* @param cwd - The session working directory.
-* @param moduleUrl - `import.meta.url` of the caller.
-* @returns The merged hook stdout.
+* Route a fuse-lessons event to its handler. Returns the native stdout for
+* context-injecting events (SessionStart/SubagentStart/Stop) or "" for the
+* side-effect-only PostToolUse mark.
+* @param event - The raw hook event name.
+* @param payload - The raw hook payload.
+* @param cwd - Project root for memory injection.
+* @param now - Clock.
+* @returns The native stdout (possibly empty).
 */
-function withSnapshot(stdout, cwd, moduleUrl) {
-	try {
-		return attachSnapshot(stdout, renderSnapshot(cwd, moduleUrl));
-	} catch {
-		return stdout;
+function dispatchLessons(event, payload, cwd, now) {
+	switch (event) {
+		case "SessionStart":
+		case "SubagentStart": return injectMemory(cwd, event, now);
+		case "Stop": return remindWrite(payload, now);
+		case "PostToolUse":
+			markWrite(payload, now);
+			return "";
+		default: return "";
 	}
 }
 //#endregion
@@ -3292,7 +3787,7 @@ async function injectApexSubagentContext(cwd, home = homedir()) {
 	const agentsPath = join(apexDir, "AGENTS.md");
 	const agents = existsSync(agentsPath) ? readText(agentsPath).slice(0, 4e3) : "";
 	const taskData = await readJsonFile(join(apexDir, "task.json"));
-	return contextResponse("SubagentStart", `## APEX Sub-Agent Instructions
+	return contextResponse("SubagentStart", capFragment("apex-subagent", `## APEX Sub-Agent Instructions
 
 You are a sub-agent in APEX workflow. Follow these rules:
 
@@ -3313,7 +3808,7 @@ ${agents}
 - Use Context7/Exa for docs | Write notes to .claude/apex/docs/
 
 ### 6. When Done
-- TaskUpdate(taskId, status: completed) triggers auto-commit${cartographerContext()}`);
+- TaskUpdate(taskId, status: completed) triggers auto-commit${cartographerContext()}`));
 }
 /** 16-char hex SHA-256 of `text` (project hash / doc topic key). */
 function hashText16(text) {
@@ -4535,10 +5030,9 @@ function dispatchLifecycle(input) {
 			if (input.scope === "aipilot") return "";
 			harvestSubagentTrack(input.payload, input.cwd, input.now);
 			return trackAgentMemory(input.payload, void 0, input.now);
-		case "TeammateIdle": return validateTeammateOutput(input.payload);
-		case "PostToolUseFailure":
-			logToolFailure(input.payload, void 0, input.now);
-			return "";
+		case "TeammateIdle": return teammateIdleContext(input.payload, input.cwd, void 0, input.now);
+		case "PostToolUseFailure": return failureLessonContext(input.payload, input.cwd, void 0, input.now);
+		case "PostCompact": return input.scope === "core" ? postCompactContext(input.payload, input.cwd, import.meta.url, input.now) : "";
 		case "PreCompact": return saveApexState(input.cwd, input.now);
 		case "SessionEnd":
 			if (input.scope !== "aipilot") cleanupSession(void 0, input.now);
@@ -5587,6 +6081,50 @@ function frameworkSkillGate(input, refsRead, existingCodeLines) {
 	return skillTriggerGate(input.framework, content, refsRead, forced, input.cwd, input.filePath);
 }
 //#endregion
+//#region src/freshness/ref-evidence.ts
+/**
+* Platform-transcript reconciliation for `.md` reference reads — the durable
+* counterpart to {@link agentsRanFromTranscript} for agent freshness.
+*
+* WHY: the session track is persisted by a non-atomic load→mutate→save. Under
+* the multi-plugin hook fan-out (one hook process per installed plugin, ×N) plus
+* back-to-back tool events, concurrent writers clobber each other (lost update).
+* `agents`/`authorizations` self-heal — every explore/research/doc call rewrites
+* them, so a lost update lands again on the next of hundreds of writes — but a
+* `refsRead` entry is written ONCE (when the `.md` is Read), so a single lost
+* update erases it permanently, and the lead has no SubagentStop
+* {@link harvestAgentEvidence} pass to reconcile it (sub-agents do, which is why
+* only the LEAD's solidReadGate never credited). The Claude-authored transcript
+* is append-only and race-immune, so folding its `.md` Reads back into the track
+* restores the lost evidence; each gate still applies its own TTL/session policy.
+*/
+/**
+* Fold every `.md` `Read` in the transcript into `track` as a timestamped ref
+* read (immutably). PURE reconciliation — the caller owns the track; each read
+* is stamped with its transcript timestamp (unstamped → `now`, lenient, matching
+* {@link agentsRanFromTranscript}), and an existing MORE-recent stamp is never
+* rolled back. Fail-open: an absent/unreadable transcript returns `track`
+* unchanged (same reference).
+* @param track - The current (possibly race-damaged) session track.
+* @param transcriptPath - Claude `transcript_path` for this session.
+* @param now - Fallback epoch-ms for transcript entries the platform left unstamped.
+* @returns The track with transcript `.md` reads merged into `refsRead`/`refsReadAt`.
+*/
+function reconcileRefReadsFromTranscript(track, transcriptPath, now) {
+	const uses = readAgentToolUses(transcriptPath);
+	if (!uses) return track;
+	let next = track;
+	for (const u of uses) {
+		if (u.name !== "Read") continue;
+		const path = String(u.input?.file_path ?? u.input?.path ?? "");
+		if (!path.endsWith(".md")) continue;
+		const ts = u.ts ?? now;
+		const prev = next.refsReadAt?.[path];
+		if (prev === void 0 || prev < ts) next = recordRefRead(next, path, ts);
+	}
+	return next;
+}
+//#endregion
 //#region src/policy/shadcn-skill-gate.ts
 /** File extensions the shadcn gate polices (source: `\.(tsx|jsx|css|scss|json)$`). */
 const SHADCN_FILE_RE = /\.(tsx|jsx|css|scss|json)$/;
@@ -6048,8 +6586,7 @@ async function runGates(input) {
 	if (modular) return modular;
 	if (!input.filePath) return null;
 	const filePath = input.filePath;
-	const window = input.windowMs ?? 12e4;
-	const track = await loadTrack(input.trackFile);
+	const track = reconcileRefReadsFromTranscript(await loadTrack(input.trackFile), input.transcriptPath, input.now);
 	const solidOrSkill = frameworkSkillGate(input, track.refsRead, existingCodeLines);
 	if (solidOrSkill) return solidOrSkill;
 	if (isShadcnWrite(input.tool, filePath)) {
@@ -6070,7 +6607,7 @@ async function runGates(input) {
 	});
 	if (geminiBlock) return geminiBlock;
 	if (isApexScoped(input.filePath)) {
-		const apex = await apexScopedGate(input, track, window);
+		const apex = await apexScopedGate(input, track, input.windowMs ?? 12e4);
 		if (apex) return apex;
 	}
 	return dryGate(input.tool, input.filePath, input.content, input.cwd);
@@ -6690,181 +7227,49 @@ 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).
-*/
+* with the single most-specific decision-time lesson (additionalContext), plus
+* a compact "evidence fresh" compliance notice on the first APEX-scoped code
+* Write/Edit that clears the freshness gate.
+*/
+/**
+* `✓ evidence fresh (explore+research)` for the first APEX-scoped Write/Edit
+* that finds explore-codebase + research-expert evidence still within the
+* freshness window — the user-visible confirmation for a gate that, until now,
+* only ever spoke up when it BLOCKED. Deduped once per freshness window per
+* session (same window the gate itself re-validates on), so it reads as "just
+* confirmed", not a notice on every edit. Returns null for anything but a
+* Write/Edit on an APEX-scoped path, or when evidence isn't fresh.
+*/
+async function freshEvidenceNotice(event, evidence, cwd) {
+	if (event.tool !== "Write" && event.tool !== "Edit" || !isApexScoped(event.filePath)) return null;
+	const windowMs = evidence.windowMs ?? 12e4;
+	if (!agentsFreshInTrack(await loadTrack(evidence.trackFile), REQUIRED_AGENTS, windowMs, evidence.now)) return null;
+	if (!oncePerWindow(`evidence-fresh:${event.sessionId}`, windowMs, {
+		now: evidence.now,
+		dir: defaultStateDir(cwd)
+	})) return null;
+	return evidenceFreshNotice();
+}
 /**
 * 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).
+* user-visible pass notice (once per allowed call), the "evidence fresh"
+* compliance notice when applicable, and, when its TRIGGERS match this call,
+* the one cooldown-guarded decision-time lesson. All 3 channels ride a single
+* response (lesson → additionalContext, notices → 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).
+* @param evidence - Session track + clock for the "evidence fresh" notice (omit to disable it).
 * @returns The native hook outcome (empty stdout when nothing to emit).
 */
-function allowOutcome(id, event, payload, mcpDir, cwd) {
+async function allowOutcome(id, event, payload, mcpDir, cwd, evidence) {
 	const notice = designPassNotice({
 		agentId: typeof payload.agent_id === "string" ? payload.agent_id : "",
 		tool: event.tool,
@@ -6877,13 +7282,32 @@ function allowOutcome(id, event, payload, mcpDir, cwd) {
 		file: lessonsFileFor(projectRoot(cwd)),
 		once: oncePerWindow
 	});
-	if (lesson) return {
-		stdout: respond(id, notice?.userMessage ? {
-			...lesson,
-			userMessage: notice.userMessage
-		} : lesson),
-		exit: 0
-	};
+	const evidenceNotice = evidence ? await freshEvidenceNotice(event, evidence, cwd) : null;
+	if (lesson) {
+		const userMessage = [notice?.userMessage, evidenceNotice].filter(Boolean).join("\n") || void 0;
+		return {
+			stdout: respond(id, userMessage ? {
+				...lesson,
+				userMessage
+			} : lesson),
+			exit: 0
+		};
+	}
+	if (evidenceNotice) {
+		const userMessage = [notice?.userMessage, evidenceNotice].filter(Boolean).join("\n");
+		return {
+			stdout: respond(id, notice ? {
+				...notice,
+				userMessage
+			} : {
+				kind: "inform",
+				title: "APEX freshness",
+				reason: "",
+				userMessage
+			}),
+			exit: 0
+		};
+	}
 	return {
 		stdout: notice ? respond(id, notice) : "",
 		exit: 0
@@ -6954,7 +7378,11 @@ async function handlePre(ctx) {
 		stdout: respond(id, prompt),
 		exit: 0
 	};
-	return allowOutcome(id, event, payload, mcpDir, opts.cwd);
+	return allowOutcome(id, event, payload, mcpDir, opts.cwd, {
+		trackFile: file,
+		windowMs: opts.windowMs,
+		now: opts.now
+	});
 }
 //#endregion
 //#region src/freshness/query-framework.ts
@@ -7185,27 +7613,38 @@ async function handlePost(ctx) {
 		url: "",
 		phase: "post"
 	}, mcpDir);
+	const refNotice = refCreditNoticeFor(activities, event.sessionId, opts.now, defaultStateDir(opts.cwd));
+	const userMessage = [notice?.userMessage, refNotice].filter(Boolean).join("\n") || void 0;
 	if (designWarn) return {
-		stdout: respond(id, notice?.userMessage ? {
+		stdout: respond(id, userMessage ? {
 			...designWarn,
-			userMessage: notice.userMessage
+			userMessage
 		} : designWarn),
 		exit: 0
 	};
-	if (!notice?.userMessage) return {
+	if (!userMessage) return {
 		stdout: extra,
 		exit: 0
 	};
+	const withUserMessage = notice ? {
+		...notice,
+		userMessage
+	} : {
+		kind: "inform",
+		title: "Compliance",
+		reason: "",
+		userMessage
+	};
 	if (!extra) return {
-		stdout: respond(id, notice),
+		stdout: respond(id, withUserMessage),
 		exit: 0
 	};
 	if (id === "claude-code" || id === "codex") return {
-		stdout: attachSystemMessage(extra, notice.userMessage),
+		stdout: attachSystemMessage(extra, userMessage),
 		exit: 0
 	};
 	return {
-		stdout: respond(id, notice) || extra,
+		stdout: respond(id, withUserMessage) || extra,
 		exit: 0
 	};
 }
@@ -7290,4 +7729,4 @@ async function handleHook(id, payload, opts) {
 	});
 }
 //#endregion
-export { postEditTypescript as $, trackSkillRead as A, trackFile as At, lessonsFileFor as B, seoPostToolUse as C, gitContext as Ct, postTrackingSideEffects as D, taskContext as Dt, securityAdvisory as E, promptSubmitContext as Et, runDoctor as F, securityStateDir as Ft, generateProjectMap as G, cartoSessionStart as H, runningVersion as I, securityStatePath as It, loadEnriched as J, isProject as K, versionBanner as L, todayUtc as Lt, dispatchLifecycle as M, isoUtc as Mt, aipilotPostToolUse as N, loadSecurityState as Nt, trackWatchResearch as O, defaultStateDir as Ot, dispatchAipilot as P, saveSecurityState as Pt, listChildren as Q, dispatchLessons as R, postEditContext as S, devContext as St, dispatchMemory as T, claudeMdKey as Tt, generateEcosystemMap as U, lessonsStateFileFor as V, writePluginMap as W, countFiles as X, mergeLines as Y, getFileDesc as Z, preCommitGate as _, sessionStartCore as _t, recordActivity as a, validateTeammateOutput as at, extractSymbols as b, removeOldFiles as bt, MCP_TTL_MS as c, validateTailwind as ct, isMcpTool as d, countLoc as dt, trackSessionChanges as et, queryOf as f, detectSolidProfile as ft, gate as g, runSessionStartCleanups as gt, TRIVIAL_BUDGET as h, readRules as ht, respond as i, logToolFailure as it, trackEnrichment as j, normalizeEvent as jt, trackMcpResearch as k, projectHash$1 as kt, WEBFETCH_TTL_MS as l, validateSolidGate as lt, REQUIRED_AGENTS as m, injectRules as mt, activityFor as n, cleanupSession as nt, mcpPostStore as o, trackAgentMemory as ot, DEFAULT_WINDOW_MS as p, solidDetectStart as pt, writeTree as q, handlePre as r, saveApexState as rt, mcpPreIntercept as s, subagentCacheContext as st, handleHook as t, validateRulesLoaded as tt, cacheQueryOf as u, checkFileSize as ut, detectDuplication as v, pruneEmptyDirs as vt, seoPostToolUseResponse as w, projectContext as wt, lifecycleStdout as x, trimLogFile as xt, dryGate as y, purgeTtlTree as yt, lessonsArchiveFileFor as z };
+export { postEditTypescript as $, trackSkillRead as A, trackFile as At, isProject as B, seoPostToolUse as C, gitContext as Ct, postTrackingSideEffects as D, taskContext as Dt, securityAdvisory as E, promptSubmitContext as Et, dispatchLessons as F, securityStateDir as Ft, getFileDesc as G, loadEnriched as H, cartoSessionStart as I, securityStatePath as It, runningVersion as J, listChildren as K, generateEcosystemMap as L, todayUtc as Lt, dispatchLifecycle as M, isoUtc as Mt, aipilotPostToolUse as N, loadSecurityState as Nt, trackWatchResearch as O, defaultStateDir as Ot, dispatchAipilot as P, saveSecurityState as Pt, lessonsStateFileFor as Q, writePluginMap as R, postEditContext as S, devContext as St, dispatchMemory as T, claudeMdKey as Tt, mergeLines as U, writeTree as V, countFiles as W, lessonsArchiveFileFor as X, versionBanner as Y, lessonsFileFor as Z, preCommitGate as _, sessionStartCore as _t, recordActivity as a, validateTeammateOutput as at, extractSymbols as b, removeOldFiles as bt, MCP_TTL_MS as c, validateTailwind as ct, isMcpTool as d, countLoc as dt, trackSessionChanges as et, queryOf as f, detectSolidProfile as ft, gate as g, runSessionStartCleanups as gt, TRIVIAL_BUDGET as h, readRules as ht, respond as i, logToolFailure as it, trackEnrichment as j, normalizeEvent as jt, trackMcpResearch as k, projectHash$1 as kt, WEBFETCH_TTL_MS as l, validateSolidGate as lt, REQUIRED_AGENTS as m, injectRules as mt, activityFor as n, cleanupSession as nt, mcpPostStore as o, trackAgentMemory as ot, DEFAULT_WINDOW_MS as p, solidDetectStart as pt, runDoctor as q, handlePre as r, saveApexState as rt, mcpPreIntercept as s, subagentCacheContext as st, handleHook as t, validateRulesLoaded as tt, cacheQueryOf as u, checkFileSize as ut, detectDuplication as v, pruneEmptyDirs as vt, seoPostToolUseResponse as w, projectContext as wt, lifecycleStdout as x, trimLogFile as xt, dryGate as y, purgeTtlTree as yt, generateProjectMap as z };