@fusengine/harness 0.1.29 → 0.1.31

package/dist/handle-DW9cWdVt.mjs

@@ -0,0 +1,3356 @@
+import { r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
+import { r as projectLayout } from "./layout-C0jaaCQC.mjs";
+import { C as capVerbosity, F as requiredArchSkill, M as detectModularArchitecture, O as evaluateApex, a as parseEntry, b as frameworkSolidGate, c as EXCLUDE_DIRS$1, d as buildApexTaskInjection, h as buildClaudeMdContext, i as parseEnrichment, l as PROJECT_INDICATORS, s as parseField, t as descFromText, v as skillTriggerGate, w as detectCreationIntent } from "./describe-BYqhoV4c.mjs";
+import { j as detectFramework, k as countLines, n as FAIL_CLOSED, t as evaluate } from "./evaluate-j3gRJ_ng.mjs";
+import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
+import { a as extractText, o as loadIndex, r as cacheStore, t as cacheLookup } from "./store-PrNPm6So.mjs";
+import { i as writeJsonFile, r as readJsonFile, t as atomicWrite } from "./json-io-CAn72gI4.mjs";
+import { t as loadRefs } from "./loader-CyAoJv2W.mjs";
+import { a as recordAgent, c as recordRefRead, l as recordTrivialEdit, n as saveTrack, o as recordBrainstormRequired, r as agentsFresh, s as recordDoc, t as loadTrack, u as trivialCount } from "./store-D-ge2ZPI.mjs";
+import { t as contextResponse } from "./claude-B9FYp0Yw.mjs";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { mkdir, rmdir } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { Glob } from "bun";
+//#region src/runtime/activity.ts
+/** Min response length (chars) for a lead agent call to count as `sufficient`. */
+const AGENT_QUALITY_MIN = 500;
+/** Read tools across harnesses (Claude `Read`, Gemini/Cline `read_file`, …). */
+const READ_TOOLS = /* @__PURE__ */ new Set([
+	"Read",
+	"read_file",
+	"read_many_files"
+]);
+/**
+* Map a live tool-use to the activity to record, or null when nothing is
+* tracked. Works across harnesses — tool names are globally distinct:
+* - MCP doc calls (`context7` / `exa`, any separator) → `doc`
+* - `Task` + `subagent_type` (Claude/Cursor) → `agent` (bare agent name)
+* - a read tool opening a `.md` reference → `ref`
+*/
+function activityFor(event) {
+	if (/context7|exa/i.test(event.tool)) return {
+		kind: "doc",
+		framework: event.framework,
+		sessionId: event.sessionId,
+		source: /exa/i.test(event.tool) ? "exa" : "context7"
+	};
+	if (event.tool === "Task") {
+		const name = String(event.input?.subagent_type ?? "").split(":").pop() ?? "";
+		if (!name) return null;
+		const quality = event.responseLength === void 0 ? void 0 : event.responseLength > AGENT_QUALITY_MIN ? "sufficient" : "insufficient";
+		return quality ? {
+			kind: "agent",
+			name,
+			ts: event.now,
+			quality
+		} : {
+			kind: "agent",
+			name,
+			ts: event.now
+		};
+	}
+	if (READ_TOOLS.has(event.tool)) {
+		const path = String(event.input?.file_path ?? event.input?.path ?? "");
+		if (path.endsWith(".md")) return {
+			kind: "ref",
+			path
+		};
+	}
+	return null;
+}
+//#endregion
+//#region src/runtime/mcp.ts
+/** Default freshness for cached MCP/WebFetch results (48h). */
+const MCP_TTL_MS = 1728e5;
+/** MCP doc tools + WebFetch whose calls are cached / verbosity-capped. */
+function isMcpTool(tool) {
+	return /context7|exa|webfetch|web_fetch/i.test(tool) || tool === "WebFetch";
+}
+/** The query/url that keys the cache. */
+function queryOf(input) {
+	const q = input.query ?? input.url ?? input.libraryId ?? "";
+	return typeof q === "string" ? q : JSON.stringify(q);
+}
+function denyWith(id, content) {
+	if (id === "claude-code" || id === "codex") return JSON.stringify({ hookSpecificOutput: {
+		hookEventName: "PreToolUse",
+		permissionDecision: "deny",
+		permissionDecisionReason: content
+	} });
+	if (id === "gemini-cli") return JSON.stringify({
+		decision: "deny",
+		reason: content
+	});
+	return "";
+}
+function mutateWith(id, input) {
+	if (id === "claude-code" || id === "codex") return JSON.stringify({ hookSpecificOutput: {
+		hookEventName: "PreToolUse",
+		permissionDecision: "allow",
+		updatedInput: input
+	} });
+	if (id === "gemini-cli") return JSON.stringify({ hookSpecificOutput: { tool_input: input } });
+	return "";
+}
+/** The doc provider a served cache-hit satisfies (`exa`/`context7`), else undefined. */
+function docSourceOf(tool) {
+	if (/exa/i.test(tool)) return "exa";
+	if (/context7/i.test(tool)) return "context7";
+}
+/**
+* Pre-event MCP interception: serve a fresh cache hit (deny + cached content),
+* else cap exa verbosity (allow + mutated input), else null to allow normally.
+* Harnesses without input-mutation/cache support fall through to null.
+*/
+function mcpPreIntercept(id, tool, input, dir, ttlMs, now) {
+	if (!isMcpTool(tool)) return null;
+	const cached = cacheLookup(dir, tool, queryOf(input), ttlMs, now);
+	if (cached) {
+		const served = denyWith(id, cached);
+		if (served) return {
+			stdout: served,
+			docSource: docSourceOf(tool)
+		};
+	}
+	const capped = capVerbosity(tool, input);
+	if (capped) {
+		const mutated = mutateWith(id, capped);
+		if (mutated) return { stdout: mutated };
+	}
+	return null;
+}
+/** Post-event: store the MCP/WebFetch response (extracted to markdown) in the cache. */
+function mcpPostStore(tool, input, response, dir) {
+	if (!isMcpTool(tool)) return;
+	cacheStore(dir, tool, queryOf(input), extractText(response));
+}
+//#endregion
+//#region src/runtime/normalize.ts
+function str(v) {
+	return typeof v === "string" ? v : void 0;
+}
+/**
+* Normalize a harness hook payload into a uniform event. Handles Cline's nested
+* `preToolUse`/`postToolUse` shape and the top-level `tool_name`/`tool_input`
+* shape used by Claude, Codex, Gemini, and Cursor.
+*/
+function normalizeEvent(id, payload) {
+	if (id === "cline") {
+		const post = payload.postToolUse;
+		const node = post ?? payload.preToolUse ?? {};
+		const params = node.parameters ?? {};
+		return {
+			phase: post ? "post" : "pre",
+			tool: str(node.toolName) ?? "",
+			input: params,
+			sessionId: str(payload.taskId) ?? "",
+			filePath: str(params.path),
+			content: str(params.content),
+			command: str(params.command)
+		};
+	}
+	const event = str(payload.hook_event_name) ?? "";
+	const input = payload.tool_input ?? payload;
+	return {
+		phase: /post|after/i.test(event) ? "post" : "pre",
+		tool: str(payload.tool_name) ?? "",
+		input,
+		sessionId: str(payload.session_id) ?? str(payload.conversation_id) ?? "",
+		filePath: str(input.file_path) ?? str(input.path) ?? str(payload.file_path),
+		content: str(input.content) ?? str(input.new_string),
+		command: str(input.command) ?? str(payload.command),
+		agentType: str(payload.agent_type) ?? str(input.subagent_type)
+	};
+}
+//#endregion
+//#region src/runtime/paths.ts
+/** Path to a session's track file (under a per-tool base dir). */
+function trackFile(sessionId, baseDir = join(tmpdir(), "fuse-harness")) {
+	return join(baseDir, `track-${sessionId.replace(/[^A-Za-z0-9_-]/g, "_") || "default"}.json`);
+}
+//#endregion
+//#region src/runtime/record.ts
+/** Apply an activity to a session's track and persist it (PostToolUse path). */
+async function recordActivity(file, activity) {
+	const track = await loadTrack(file);
+	await saveTrack(file, activity.kind === "agent" ? recordAgent(track, activity.name, activity.ts, activity.quality) : activity.kind === "doc" ? recordDoc(track, activity.framework, activity.sessionId, activity.source) : recordRefRead(track, activity.path));
+}
+//#endregion
+//#region src/runtime/respond.ts
+/**
+* Map a portable {@link Prompt} to a harness's native hook response. `block`
+* denies; anything else asks/injects context. (Codex/Cursor parse but ignore
+* `ask` — they only honor deny.)
+*/
+function respond(id, prompt) {
+	const message = formatPrompt(prompt);
+	const deny = prompt.kind === "block";
+	switch (id) {
+		case "claude-code":
+		case "codex": return JSON.stringify({ hookSpecificOutput: {
+			hookEventName: "PreToolUse",
+			permissionDecision: deny ? "deny" : "ask",
+			permissionDecisionReason: message
+		} });
+		case "gemini-cli": return JSON.stringify(deny ? {
+			decision: "deny",
+			reason: message
+		} : { hookSpecificOutput: { additionalContext: message } });
+		case "cursor": return JSON.stringify({
+			permission: deny ? "deny" : "ask",
+			continue: false,
+			userMessage: message,
+			agentMessage: message
+		});
+		case "cline": return JSON.stringify(deny ? {
+			cancel: true,
+			errorMessage: message
+		} : { contextModification: message });
+		default: return "";
+	}
+}
+//#endregion
+//#region src/policy/design/state.ts
+/** Minimum fuse-browser screenshots required before writing design-system.md, per mode. */
+const MIN_SCREENSHOTS = {
+	full: 4,
+	page: 2,
+	component: 0
+};
+const stateFile = (cacheDir, agentId) => join(cacheDir, `.design-state-${agentId}.json`);
+/** Load the design state for `agentId`, or null when absent/corrupt (fail-open). */
+function loadDesignState(cacheDir, agentId) {
+	const path = stateFile(cacheDir, agentId);
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+}
+/** Persist the design state under its agent id. */
+function saveDesignState(cacheDir, state) {
+	mkdirSync(cacheDir, { recursive: true });
+	writeFileSync(stateFile(cacheDir, state.agentId), JSON.stringify(state, null, 2));
+}
+/** Build the initial state for a design agent starting a run. */
+function initDesignState(agentId, mode, designSystemExists) {
+	return {
+		agentId,
+		mode,
+		currentPhase: 0,
+		phasesCompleted: [],
+		inspirationRead: false,
+		scrolledSinceNav: false,
+		screenshotsCount: 0,
+		designSystemExists,
+		designSystemValid: false,
+		geminiCalls: 0
+	};
+}
+/** Archive the active state file (timestamp suffix) and drop archives older than 7 days. */
+function cleanupDesignStates(cacheDir, agentId, stamp, now) {
+	if (agentId) {
+		const src = stateFile(cacheDir, agentId);
+		if (existsSync(src)) renameSync(src, join(cacheDir, `.design-state-${agentId}-${stamp}.json`));
+	}
+	let entries;
+	try {
+		entries = readdirSync(cacheDir);
+	} catch {
+		return;
+	}
+	const cutoff = now - 7 * 864e5;
+	for (const name of entries) {
+		if (!name.startsWith(".design-state-")) continue;
+		const path = join(cacheDir, name);
+		try {
+			if (statSync(path).mtimeMs < cutoff) rmSync(path);
+		} catch {}
+	}
+}
+//#endregion
+//#region src/policy/design/transitions.ts
+/** Infer the pipeline mode from the launch prompt + whether a design-system.md already exists. */
+function detectMode(prompt, designSystemExists) {
+	const p = prompt.toLowerCase();
+	if ([
+		"component",
+		"composant",
+		"snippet"
+	].some((k) => p.includes(k))) return "component";
+	return designSystemExists ? "page" : "full";
+}
+/** Record a screenshot: bump the count and advance to phase 2 once the quota is met. */
+function recordScreenshot(state, needed) {
+	const screenshotsCount = state.screenshotsCount + 1;
+	const next = {
+		...state,
+		screenshotsCount
+	};
+	if (screenshotsCount >= needed && state.currentPhase < 2) {
+		next.currentPhase = 2;
+		next.phasesCompleted = [.../* @__PURE__ */ new Set([
+			...state.phasesCompleted,
+			"identity",
+			"research"
+		])];
+	}
+	return next;
+}
+/** Record a fuse-browser navigate (resets the scroll-before-screenshot guard). */
+function recordNavigate(state) {
+	return {
+		...state,
+		scrolledSinceNav: false
+	};
+}
+/** Record a fuse-browser scroll (satisfies the scroll-before-screenshot guard). */
+function recordScroll(state) {
+	return {
+		...state,
+		scrolledSinceNav: true
+	};
+}
+/** Mark the design system validated and advance to phase 3 (after a passing create_frontend check). */
+function recordValidDesignSystem(state) {
+	return {
+		...state,
+		designSystemExists: true,
+		designSystemValid: true,
+		currentPhase: Math.max(state.currentPhase, 3),
+		phasesCompleted: [.../* @__PURE__ */ new Set([...state.phasesCompleted, "design-system"])]
+	};
+}
+/**
+* Record a skill-file Read: reading the identity templates enters phase 1 (browsing
+* allowed); reading the inspiration catalog satisfies the browse prerequisite.
+*/
+function recordRead(state, filePath) {
+	const next = { ...state };
+	if (filePath.includes("identity-system")) {
+		next.currentPhase = Math.max(state.currentPhase, 1);
+		next.phasesCompleted = [.../* @__PURE__ */ new Set([...state.phasesCompleted, "identity"])];
+	}
+	if (filePath.includes("design-inspiration")) next.inspirationRead = true;
+	return next;
+}
+//#endregion
+//#region src/policy/design/flag.ts
+const flagPath = (cacheDir) => join(cacheDir, "design-agent-active");
+/** The active design agent id (the flag), or "" when no design agent is running. */
+function activeDesignAgent(cacheDir) {
+	const path = flagPath(cacheDir);
+	if (!existsSync(path)) return "";
+	try {
+		return readFileSync(path, "utf8").trim();
+	} catch {
+		return "";
+	}
+}
+/** Mark a design agent active (writes its id to the flag file). */
+function setActiveDesignAgent(cacheDir, agentId) {
+	mkdirSync(cacheDir, { recursive: true });
+	writeFileSync(flagPath(cacheDir), agentId);
+}
+/** Clear the active-design-agent flag. */
+function clearActiveDesignAgent(cacheDir) {
+	try {
+		rmSync(flagPath(cacheDir));
+	} catch {}
+}
+//#endregion
+//#region src/policy/design/content-checks.ts
+/** Accessibility warnings: icon buttons need aria-label, images need alt. */
+function checkAccessibility(content) {
+	const w = [];
+	if (!/<(button|a|input|img)/.test(content)) return w;
+	if (/<button[^>]*>/.test(content) && !/aria-label|aria-labelledby/.test(content) && /<button[^>]*>[^<]*<[^>]*Icon/.test(content)) w.push("Accessibility: icon buttons need an aria-label.");
+	for (const m of content.matchAll(/<img[^>]*?>/g)) if (!m[0].includes("alt=")) {
+		w.push("Accessibility: images need an alt attribute.");
+		break;
+	}
+	return w;
+}
+/** Anti-pattern warnings: colored left borders, AI-slop gradients, emoji-as-icons. */
+function checkPatterns(content) {
+	const w = [];
+	if (/border-l-[0-9]+ border-l-(blue|green|red|purple)/.test(content)) w.push("Design: avoid colored left borders — use shadow/gradient.");
+	if (/from-purple|to-purple|via-purple|from-pink.*to-purple/.test(content)) w.push("Design: avoid purple/pink gradients (AI slop) — use brand colors.");
+	if (/>[^\x00-\x7F]+</.test(content)) w.push("Design: avoid emojis as icons — use a real icon set.");
+	return w;
+}
+/** Forbidden-font warnings (CSS font-family + Google Fonts import). */
+function checkFonts(content) {
+	const w = [];
+	if (/font-family:\s*['"]?(Roboto|Inter|Arial|Open Sans|Lato)\b/i.test(content)) w.push("Font: forbidden family (Roboto/Inter/Arial/Open Sans/Lato) — use identity fonts.");
+	if (/@import.*fonts\.googleapis.*family=(Roboto|Inter)\b/.test(content)) w.push("Font: Google Fonts import for a forbidden family.");
+	return w;
+}
+/** Hard-coded-color warnings (hex in className or inline style). */
+function checkColors(content) {
+	const w = [];
+	if (/className="[^"]*#[0-9a-fA-F]{3,8}[^"]*"/.test(content)) w.push("Color: hard-coded hex in className — use CSS variables.");
+	if (/(?:color|background(?:-color)?|fill|stroke):\s*['"]?#[0-9a-fA-F]{3,8}/.test(content)) w.push("Color: hard-coded hex in style — use var(--color-*).");
+	return w;
+}
+/** Run all design content checks → non-blocking warnings (empty = clean). */
+function runDesignChecks(content) {
+	return [
+		...checkAccessibility(content),
+		...checkPatterns(content),
+		...checkFonts(content),
+		...checkColors(content)
+	];
+}
+//#endregion
+//#region src/policy/design/gates.ts
+const ALLOWED_WRITE = /\.(html|css|md|json)$/;
+const EXEMPT_DIRS = [
+	"node_modules/",
+	"dist/",
+	"build/",
+	".claude/"
+];
+const FORBIDDEN_FONTS = [
+	"Inter",
+	"Roboto",
+	"Arial",
+	"Open Sans"
+];
+const OKLCH_RE = /oklch\(\s*[\d.]+%?\s+0\.0*[1-9]/;
+const KNOWN_DOMAINS = [
+	"framer.website",
+	"webflow.io",
+	"awwwards.com",
+	"godly.website",
+	"lapa.ninja",
+	"onepagelove.com",
+	"saasframe.io",
+	"bestwebsite.gallery",
+	"landingfolio.com"
+];
+const deny = (reason) => ({
+	kind: "block",
+	title: "Design pipeline",
+	reason,
+	actions: ["Follow the design pipeline phases (0→identity, 1→inspiration, 2→screenshots, 3→design-system, 4→generate) in order"]
+});
+/** Block the design agent from writing anything but .html/.css/.md/.json. */
+function htmlCssOnlyGate(filePath) {
+	if (EXEMPT_DIRS.some((d) => filePath.includes(d)) || ALLOWED_WRITE.test(filePath)) return null;
+	return deny("BLOCKED: design-expert can only write .html, .css, .md, and .json files.");
+}
+/** Block edits to the harness-managed `.design-state-*` files (read-only to the agent). */
+function stateFileGate(filePath) {
+	return filePath.includes(".design-state-") ? deny("BLOCKED: .design-state files are read-only; the hooks update them as you progress.") : null;
+}
+/** Gate writing design-system.md: requires phase ≥ 2 and the per-mode screenshot quota. */
+function designSystemWriteGate(filePath, state) {
+	if (!filePath.endsWith("design-system.md")) return null;
+	if (state.currentPhase < 2) return deny(`BLOCKED: cannot write design-system.md at phase ${state.currentPhase}. Read identity + inspiration, then browse & screenshot first.`);
+	const needed = MIN_SCREENSHOTS[state.mode];
+	if (state.screenshotsCount < needed) return deny(`BLOCKED: ${state.screenshotsCount}/${needed} fuse-browser screenshots for mode '${state.mode}'. Take ${needed - state.screenshotsCount} more (fullPage).`);
+	return null;
+}
+/** Return the requirements missing from a design-system.md (empty = valid). */
+function validateDesignSystem(content) {
+	const missing = [];
+	if (!content.includes("## Design Reference")) missing.push("## Design Reference section");
+	if (!/https?:\/\//.test(content)) missing.push("reference URL (https://…)");
+	if (!OKLCH_RE.test(content)) missing.push("oklch() color with chroma > 0");
+	if (FORBIDDEN_FONTS.some((f) => content.includes(f))) missing.push("forbidden font (Inter/Roboto/Arial/Open Sans)");
+	return missing;
+}
+/** Gate Gemini create_frontend: requires phase ≥ 3 and a validated design system. */
+function geminiCreateGate(state) {
+	if (state.currentPhase < 3) return deny("BLOCKED: cannot call create_frontend before phase 3. Finish screenshots and write a valid design-system.md.");
+	if (!state.designSystemValid) return deny("BLOCKED: design-system.md not validated (needs ## Design Reference, OKLCH, typography, reference URL).");
+	return null;
+}
+/** Gate fuse-browser navigate: phase ≥ 1, inspiration read, URL in the catalog. */
+function browserNavigateGate(state, url) {
+	if (state.currentPhase < 1) return deny("BLOCKED: read identity templates + design-inspiration.md before browsing.");
+	if (!state.inspirationRead) return deny("BLOCKED: design-inspiration.md not read yet — read it then pick catalog URLs.");
+	if (url && !KNOWN_DOMAINS.some((d) => url.includes(d))) return deny(`BLOCKED: '${url}' is not in the catalog. Use design-inspiration-urls.md domains.`);
+	return null;
+}
+/** Gate a screenshot: require a scroll since the last navigate (lazy-load content). */
+function screenshotScrollGate(state) {
+	return state.scrolledSinceNav ? null : deny("BLOCKED: scroll the page before a screenshot — browser_scroll to:'end', wait, scroll back, then fullPage screenshot.");
+}
+/** The Gemini design gates are OPT-IN: off unless `FUSE_DESIGN_GEMINI` is `1`/`true`. */
+function geminiEnabled() {
+	const v = process.env.FUSE_DESIGN_GEMINI;
+	return v === "1" || v === "true";
+}
+//#endregion
+//#region src/runtime/design.ts
+const NAV = "mcp__fuse-browser__browser_navigate";
+const SHOT = "mcp__fuse-browser__browser_screenshot";
+const SCROLL = "mcp__fuse-browser__browser_scroll";
+const GEMINI = "mcp__gemini-design__create_frontend";
+/** Read design-system.md walking up to 6 parents from `cwd` ("" if absent/unreadable). */
+function findDesignSystem(cwd) {
+	let dir = cwd;
+	for (let i = 0; i < 6; i++) {
+		const p = join(dir, "design-system.md");
+		if (existsSync(p)) try {
+			return readFileSync(p, "utf8");
+		} catch {
+			return "";
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return "";
+}
+/** Apply a PostToolUse fuse-browser transition to the design state. */
+function recordPost(event, cacheDir, state) {
+	if (event.tool === SHOT) saveDesignState(cacheDir, recordScreenshot(state, MIN_SCREENSHOTS[state.mode]));
+	else if (event.tool === NAV) saveDesignState(cacheDir, recordNavigate(state));
+	else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
+	else if (event.tool === GEMINI) saveDesignState(cacheDir, {
+		...state,
+		geminiCalls: state.geminiCalls + 1
+	});
+	else if (event.tool === "Read") saveDesignState(cacheDir, recordRead(state, event.filePath ?? ""));
+	else if ((event.tool === "Write" || event.tool === "Edit") && (event.filePath ?? "").endsWith("design-system.md")) saveDesignState(cacheDir, recordValidDesignSystem(state));
+}
+/**
+* Design-pipeline gate (effectful: reads/writes the design state + design-system.md).
+* Returns a Prompt to block, or null when this isn't a design-agent context / nothing fires.
+*/
+function designGate(payload, event, cacheDir, cwd) {
+	const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+	const active = activeDesignAgent(cacheDir);
+	if (active && agentId && agentId !== active) return null;
+	const id = active || agentId;
+	if (!id) return null;
+	const state = loadDesignState(cacheDir, id);
+	if (!state) return null;
+	if (event.phase === "post") {
+		recordPost(event, cacheDir, state);
+		if ((event.tool === "Write" || event.tool === "Edit") && /\.(tsx|jsx|css)$/.test(event.filePath ?? "")) {
+			const warnings = runDesignChecks(event.content ?? "");
+			if (warnings.length) return {
+				kind: "inform",
+				title: "Design review",
+				reason: warnings.join(" "),
+				actions: []
+			};
+		}
+		return null;
+	}
+	if (event.tool === "Write" || event.tool === "Edit") {
+		const fp = event.filePath ?? "";
+		const base = stateFileGate(fp) ?? htmlCssOnlyGate(fp) ?? designSystemWriteGate(fp, state);
+		if (base) return base;
+		if (geminiEnabled() && state.geminiCalls === 0 && /\.(html|css)$/.test(fp)) return {
+			kind: "block",
+			title: "Design pipeline",
+			reason: "BLOCKED: generate the frontend via create_frontend before hand-writing HTML/CSS.",
+			actions: ["Call mcp__gemini-design__create_frontend first"]
+		};
+		return null;
+	}
+	if (event.tool === NAV) return browserNavigateGate(state, typeof event.input.url === "string" ? event.input.url : "");
+	if (event.tool === SHOT) return screenshotScrollGate(state);
+	if (event.tool === GEMINI) {
+		if (!geminiEnabled()) return null;
+		const block = geminiCreateGate(state);
+		if (block) return block;
+		const missing = validateDesignSystem(findDesignSystem(cwd));
+		if (missing.length) return {
+			kind: "block",
+			title: "Design pipeline",
+			reason: `BLOCKED: design-system.md too generic. Missing: ${missing.join(", ")}.`,
+			actions: ["Fix design-system.md, then retry create_frontend"]
+		};
+		saveDesignState(cacheDir, recordValidDesignSystem(state));
+	}
+	return null;
+}
+//#endregion
+//#region src/runtime/design-lifecycle.ts
+/**
+* Handle the design-agent SubagentStart/Stop lifecycle: init the pipeline state +
+* raise the active flag on start, archive/cleanup + clear the flag on stop.
+* Returns true when it handled the event (caller should respond and stop).
+*/
+function designLifecycle(payload, cacheDir, cwd, stamp, now) {
+	const event = typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+	if (!(typeof payload.agent_type === "string" ? payload.agent_type : "").includes("design")) return false;
+	const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+	if (event === "SubagentStart") {
+		if (!agentId) return false;
+		const dsExists = existsSync(join(cwd, "design-system.md"));
+		saveDesignState(cacheDir, initDesignState(agentId, detectMode(typeof payload.prompt === "string" ? payload.prompt : "", dsExists), dsExists));
+		setActiveDesignAgent(cacheDir, agentId);
+		return true;
+	}
+	if (event === "SubagentStop") {
+		cleanupDesignStates(cacheDir, agentId, stamp, now);
+		clearActiveDesignAgent(cacheDir);
+		return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/runtime/inject-context.ts
+/**
+* UserPromptSubmit context injection: render the CLAUDE.md (+ optional APEX)
+* preamble as a Claude `additionalContext` response, or "" when nothing to emit.
+* @param prompt - The raw user prompt.
+* @param cwd - Project root (for project-type detection).
+* @returns The native hook stdout (possibly empty).
+*/
+function promptSubmitContext(prompt, cwd) {
+	const ctx = buildClaudeMdContext(prompt, cwd);
+	return ctx ? contextResponse("UserPromptSubmit", ctx) : "";
+}
+/**
+* PreToolUse Task context injection: render the APEX sub-agent context as a
+* Claude `additionalContext` response when `.claude/apex/` exists, else "".
+* @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) : "";
+}
+//#endregion
+//#region src/runtime/home-state.ts
+/** Home `~/.claude` dir (single source for every home-based hook path). */
+function claudeHome(home = homedir()) {
+	return join(home, ".claude");
+}
+/** `~/.claude/fusengine-cache` base dir for legacy session/cache state. */
+function fusengineCache(home = homedir()) {
+	return join(claudeHome(home), "fusengine-cache");
+}
+/** `~/.claude/fusengine-cache/sessions` — per-session JSON state dir. */
+function sessionsDir(home = homedir()) {
+	return join(fusengineCache(home), "sessions");
+}
+const SID_RE = /^[a-zA-Z0-9_-]{1,128}$/;
+/** Validate a session id (1-128 url-safe chars); null when invalid. */
+function sanitizeSessionId(sid) {
+	const s = String(sid ?? "").trim();
+	return SID_RE.test(s) ? s : null;
+}
+/** Unified per-session state file path: `sessions/session-<sid>.json`. */
+function sessionStatePath(sid, home = homedir()) {
+	return join(sessionsDir(home), `session-${sid}.json`);
+}
+/** Load a session-state dict, or `{}` when missing/corrupt (mirrors Python). */
+function loadSessionState(sid, home = homedir()) {
+	const path = sessionStatePath(sid, home);
+	try {
+		if (!existsSync(path)) return {};
+		const data = JSON.parse(readFileSync(path, "utf-8"));
+		return typeof data === "object" && data !== null && !Array.isArray(data) ? data : {};
+	} catch {
+		return {};
+	}
+}
+/** Atomically persist a session-state dict (0o600 via atomicWrite, indent 2). */
+function saveSessionState(sid, state, home = homedir()) {
+	mkdirSync(sessionsDir(home), {
+		recursive: true,
+		mode: 448
+	});
+	atomicWrite(sessionStatePath(sid, home), JSON.stringify(state, null, 2));
+}
+//#endregion
+//#region src/runtime/dev-context.ts
+/** Run a git subcommand in `cwd`, returning trimmed stdout or "" on error. */
+function git(cwd, args) {
+	try {
+		return execFileSync("git", args, {
+			cwd,
+			encoding: "utf-8",
+			stdio: "pipe",
+			timeout: 5e3
+		}).trim();
+	} catch {
+		return "";
+	}
+}
+/** Build the git portion of the dev context (branch + up to 5 changed files). */
+function gitContext(cwd) {
+	if (!existsSync(join(cwd, ".git"))) return [];
+	const parts = [`Git branch: ${git(cwd, ["branch", "--show-current"]) || "unknown"}`];
+	const status = git(cwd, ["status", "--porcelain"]);
+	if (status) parts.push("Modified files:\n" + status.split("\n").slice(0, 5).join("\n"));
+	return parts;
+}
+/** Build the project-type portion (mirrors load-dev-context.py exactly). */
+function projectContext(cwd) {
+	const parts = [];
+	const has = (f) => existsSync(join(cwd, f));
+	if ([
+		"next.config.js",
+		"next.config.ts",
+		"next.config.mjs"
+	].some(has)) parts.push("Project: Next.js");
+	else if (has("package.json")) parts.push("Project: Node.js");
+	if (has("composer.json") && has("artisan")) parts.push("Project: Laravel");
+	if (has("Package.swift")) parts.push("Project: Swift");
+	return parts;
+}
+/**
+* Build the SessionStart dev-context block (git + project type), or "" when
+* nothing applies. Ports `core-guards/scripts/session-start/load-dev-context.py`.
+* @param cwd - Project root to inspect.
+* @returns The joined additionalContext text (possibly empty).
+*/
+function devContext(cwd) {
+	return [...gitContext(cwd), ...projectContext(cwd)].join("\n");
+}
+//#endregion
+//#region src/runtime/fs-cleanup.ts
+/** Age of a file in seconds (now - mtime). Infinity when unstat-able. */
+function ageSec(path, now) {
+	try {
+		return (now - statSync(path).mtimeMs) / 1e3;
+	} catch {
+		return Infinity;
+	}
+}
+/** Remove files directly under `dir` matching `test` older than `maxAgeSec`. */
+function removeOldFiles(dir, test, maxAgeSec, now = Date.now()) {
+	if (!existsSync(dir)) return;
+	for (const name of readdirSync(dir)) {
+		const path = join(dir, name);
+		if (test(name) && ageSec(path, now) > maxAgeSec) try {
+			rmSync(path, { force: true });
+		} catch {}
+	}
+}
+/** Trim `file` to its last `keepLines` lines when it exceeds `maxBytes`. */
+function trimLogFile(file, maxBytes, keepLines) {
+	try {
+		if (!existsSync(file) || statSync(file).size <= maxBytes) return;
+		writeFileSync(file, readFileSync(file, "utf-8").split("\n").slice(-keepLines).join("\n"), "utf-8");
+	} catch {}
+}
+/** Recursively purge files under `root/<top>` older than `ttls[top]` seconds. */
+function purgeTtlTree(root, ttls, now = Date.now()) {
+	if (!existsSync(root)) return;
+	for (const [top, ttlSec] of Object.entries(ttls)) walkPurge(join(root, top), ttlSec, now);
+}
+function walkPurge(dir, ttlSec, now) {
+	if (!existsSync(dir)) return;
+	for (const name of readdirSync(dir)) {
+		const path = join(dir, name);
+		let isDir = false;
+		try {
+			isDir = statSync(path).isDirectory();
+		} catch {
+			continue;
+		}
+		if (isDir) {
+			walkPurge(path, ttlSec, now);
+			continue;
+		}
+		if (ageSec(path, now) > ttlSec) try {
+			rmSync(path, { force: true });
+		} catch {}
+	}
+}
+/** Bottom-up removal of empty subdirs under each `root/<top>` (best effort). */
+function pruneEmptyDirs(root, tops) {
+	for (const top of tops) {
+		const sub = join(root, top);
+		if (!existsSync(sub)) continue;
+		pruneEmpty(sub, sub);
+	}
+}
+function pruneEmpty(dir, stopAt) {
+	for (const name of existsSync(dir) ? readdirSync(dir) : []) {
+		const path = join(dir, name);
+		try {
+			if (statSync(path).isDirectory()) pruneEmpty(path, stopAt);
+		} catch {}
+	}
+	if (dir !== stopAt && relative(stopAt, dir).split(sep)[0] !== "..") try {
+		rmdirSync(dir);
+	} catch {}
+}
+//#endregion
+//#region src/runtime/lifecycle/session-start.ts
+/** TTLs (seconds) for purgeable fusengine-cache subtrees (cleanup-old-caches.py). */
+const PURGEABLE = {
+	sessions: 48 * 3600,
+	webfetch: 24 * 3600,
+	doc: 48 * 3600,
+	explore: 48 * 3600
+};
+/** Read `~/.claude/CLAUDE.md`, or "" when missing/unreadable. */
+function claudeMd(home) {
+	const path = join(claudeHome(home), "CLAUDE.md");
+	try {
+		return existsSync(path) ? readFileSync(path, "utf-8") : "";
+	} catch {
+		return "";
+	}
+}
+/** Run the legacy SessionStart cleanups (stale states, caches, log trim). */
+function runSessionStartCleanups(home = homedir(), now = Date.now()) {
+	const base = fusengineCache(home);
+	removeOldFiles(sessionsDir(home), (n) => n.startsWith("session-") && n.endsWith(".json"), 86400, now);
+	const user = process.env.USER ?? "unknown";
+	removeOldFiles(base, (n) => n === `changes-${user}.json`, 21600, now);
+	trimLogFile(join(claudeHome(home), "logs", "hooks.log"), 10485760, 5e3);
+	removeOldFiles(join(claudeHome(home), "logs", "00-apex"), (n) => n.startsWith("ref-cache-") && n.endsWith(".json"), 86400, now);
+	purgeTtlTree(base, PURGEABLE, now);
+	pruneEmptyDirs(base, Object.keys(PURGEABLE));
+}
+/**
+* Handle core-guards SessionStart: inject CLAUDE.md + dev context as
+* `additionalContext`, then run the cache/state cleanups. Ports the four
+* `session-start/*.py` scripts into one harness call.
+* @param cwd - Project root for dev-context detection.
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock for TTL cleanup (defaults to `Date.now()`).
+* @returns The native hook stdout (possibly empty).
+*/
+function sessionStartCore(cwd, home = homedir(), now = Date.now()) {
+	const md = claudeMd(home);
+	const dev = devContext(cwd);
+	runSessionStartCleanups(home, now);
+	const ctx = [md, dev].filter(Boolean).join("\n");
+	return ctx ? contextResponse("SessionStart", ctx) : "";
+}
+//#endregion
+//#region src/runtime/lifecycle/inject-rules.ts
+/** Read & concatenate all `*.md` files (sorted) under `rulesDir`. */
+function readRules(rulesDir) {
+	if (!existsSync(rulesDir)) return "";
+	let names;
+	try {
+		names = readdirSync(rulesDir).filter((n) => n.endsWith(".md")).sort();
+	} catch {
+		return "";
+	}
+	const parts = [];
+	for (const name of names) try {
+		parts.push(readFileSync(join(rulesDir, name), "utf-8"));
+	} catch {}
+	return parts.join("\n\n");
+}
+/**
+* Build the rules injection for claude-rules (SessionStart + UserPromptSubmit):
+* read `<pluginRoot>/rules/*.md` and emit as `additionalContext`, or "" when no
+* rules. Ports `claude-rules/scripts/inject-rules.py` (which always tags the
+* output `hookEventName: "SessionStart"`, even on UserPromptSubmit).
+* @param pluginRoot - `CLAUDE_PLUGIN_ROOT` of the claude-rules plugin.
+* @returns The native hook stdout (possibly empty).
+*/
+function injectRules(pluginRoot) {
+	const content = readRules(join(pluginRoot, "rules"));
+	return content ? contextResponse("SessionStart", content) : "";
+}
+//#endregion
+//#region src/runtime/lifecycle/solid-detect.ts
+/** Ordered detection table (mirrors solid/scripts/detect-project.py). */
+const CHECKS = [
+	{
+		file: "package.json",
+		grep: "next",
+		profile: {
+			type: "nextjs",
+			limit: 150,
+			ifaceDir: "modules/cores/interfaces"
+		}
+	},
+	{
+		file: "composer.json",
+		grep: "laravel",
+		profile: {
+			type: "laravel",
+			limit: 100,
+			ifaceDir: "app/Contracts"
+		}
+	},
+	{
+		file: "go.mod",
+		grep: null,
+		profile: {
+			type: "go",
+			limit: 100,
+			ifaceDir: "internal/interfaces"
+		}
+	},
+	{
+		file: "Cargo.toml",
+		grep: null,
+		profile: {
+			type: "rust",
+			limit: 100,
+			ifaceDir: "src/traits"
+		}
+	},
+	{
+		file: "pyproject.toml",
+		grep: null,
+		profile: {
+			type: "python",
+			limit: 100,
+			ifaceDir: "src/interfaces"
+		}
+	},
+	{
+		file: "requirements.txt",
+		grep: null,
+		profile: {
+			type: "python",
+			limit: 100,
+			ifaceDir: "src/interfaces"
+		}
+	}
+];
+/** Detect the SOLID profile for `projectDir`, defaulting to `unknown`. */
+function detectSolidProfile(projectDir) {
+	for (const { file, grep, profile } of CHECKS) {
+		const path = join(projectDir, file);
+		if (!existsSync(path)) continue;
+		if (grep !== null) try {
+			if (!readFileSync(path, "utf-8").includes(grep)) continue;
+		} catch {
+			continue;
+		}
+		return profile;
+	}
+	if (existsSync(join(projectDir, "Package.swift"))) return {
+		type: "swift",
+		limit: 150,
+		ifaceDir: "Protocols"
+	};
+	try {
+		if (readdirSync(projectDir).some((e) => e.endsWith(".xcodeproj") || e.endsWith(".xcworkspace"))) return {
+			type: "swift",
+			limit: 150,
+			ifaceDir: "Protocols"
+		};
+	} catch {}
+	return {
+		type: "unknown",
+		limit: 100,
+		ifaceDir: ""
+	};
+}
+/**
+* Handle solid SessionStart: detect the profile, append SOLID_* exports to
+* `CLAUDE_ENV_FILE`, and return the `SOLID: …` stdout line (or "" for unknown).
+* Ports `solid/scripts/detect-project.py`.
+* @param env - Environment (defaults to `process.env`).
+* @returns The plain-text stdout line (possibly empty).
+*/
+function solidDetectStart(env = process.env) {
+	const profile = detectSolidProfile(env.CLAUDE_PROJECT_DIR ?? ".");
+	const envFile = env.CLAUDE_ENV_FILE ?? "";
+	if (envFile) try {
+		appendFileSync(envFile, `export SOLID_PROJECT_TYPE=${profile.type}\nexport SOLID_FILE_LIMIT=${profile.limit}\nexport SOLID_INTERFACE_DIR=${profile.ifaceDir}\n`, "utf-8");
+	} catch {}
+	return profile.type !== "unknown" ? `SOLID: ${profile.type} project (max ${profile.limit} lines)` : "";
+}
+//#endregion
+//#region src/runtime/lifecycle/subagent-cache.ts
+const DEFAULT_TTL_MIN = 30;
+/** Resolve cache TTL (minutes) from `FUSENGINE_CACHE_TTL_MIN` or default. */
+function ttlMinutes(env) {
+	const raw = (env.FUSENGINE_CACHE_TTL_MIN ?? "").trim();
+	const val = Number.parseInt(raw, 10);
+	return Number.isFinite(val) && val > 0 ? val : DEFAULT_TTL_MIN;
+}
+/** True when ISO ts `YYYY-MM-DDTHH:MM:SSZ` is within `ttlMin` minutes of now. */
+function isFresh(ts, ttlMin, now) {
+	const parsed = Date.parse(ts);
+	if (Number.isNaN(parsed)) return false;
+	const ageSec = (now - parsed) / 1e3;
+	return ageSec >= 0 && ageSec <= ttlMin * 60;
+}
+/** Sanitize + truncate a cell value (replace `|`/newline, ellipsize). */
+function trunc(text, limit) {
+	const t = String(text ?? "").replace(/\|/g, "/").replace(/\n/g, " ");
+	return t.length <= limit ? t : t.slice(0, limit - 3) + "...";
+}
+/** Render fresh cache entries as the markdown injection block. */
+function render(entries) {
+	const lines = [
+		"# MCP Cache disponible cette session",
+		"Avant de lancer mcp__context7/exa, verifie si deja cached.",
+		"Lis le fichier .md via Read pour recuperer le resultat.",
+		"APEX: Read sur cache MCP compte comme research-expert satisfait.",
+		"",
+		"| Tool | Query | File |",
+		"| --- | --- | --- |"
+	];
+	for (const e of entries) lines.push(`| ${trunc(e.tool, 40)} | ${trunc(e.query, 60)} | ${trunc(e.file, 50)} |`);
+	return lines.join("\n");
+}
+/**
+* Handle SubagentStart: surface fresh MCP cache entries for the session as
+* `additionalContext`. Ports `subagent-start/inject-context-cache.py`.
+* @param sessionIdRaw - Raw session id from the payload.
+* @param home - Home dir (defaults to `~`).
+* @param env - Environment (defaults to `process.env`).
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native hook stdout (possibly empty).
+*/
+function subagentCacheContext(sessionIdRaw, home = homedir(), env = process.env, now = Date.now()) {
+	const sid = sanitizeSessionId(sessionIdRaw === "" || sessionIdRaw == null ? "unknown" : sessionIdRaw);
+	if (!sid) return "";
+	const index = loadIndex(join(sessionsDir(home), sid, "context", "index.json"));
+	if (index.length === 0) return "";
+	const fresh = index.filter((e) => isFresh(String(e.ts ?? ""), ttlMinutes(env), now));
+	return fresh.length ? contextResponse("SubagentStart", render(fresh)) : "";
+}
+//#endregion
+//#region src/runtime/lifecycle/agent-memory.ts
+/** `~/.claude/memory/agents` — agent completion history dir. */
+function memoryDir(home) {
+	return join(home, ".claude", "memory", "agents");
+}
+const SKIP_AGENTS = /(sniper|sniper-faster|explore-codebase|research-expert|claude-code-guide|Explore|Plan)/;
+/** Append the agent completion record to `agent-history.jsonl` (best effort). */
+function recordHistory(home, agentId, agentType, ts) {
+	const dir = memoryDir(home);
+	try {
+		mkdirSync(dir, { recursive: true });
+		appendFileSync(join(dir, "agent-history.jsonl"), JSON.stringify({
+			agentId,
+			agentType,
+			completedAt: ts
+		}) + "\n", "utf-8");
+	} catch {}
+}
+/**
+* Handle SubagentStop: append the completion to agent-history.jsonl and, for a
+* non-skipped agent that touched code, emit the sniper reminder + reset the
+* counter. Ports `subagent-stop/track-agent-memory.py`.
+* @param data - The raw hook payload.
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native hook stdout (always a JSON message).
+*/
+function trackAgentMemory(data, home = homedir(), now = Date.now()) {
+	mkdirSync(sessionsDir(home), { recursive: true });
+	const agentType = String(data.agent_type ?? data.subagent_type ?? "unknown");
+	const sessionId = String(data.session_id ?? "unknown");
+	const ts = new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+	recordHistory(home, String(data.agent_id ?? "unknown"), agentType, ts);
+	if (SKIP_AGENTS.test(agentType)) return JSON.stringify({ message: `Agent ${agentType} completed` });
+	const stateFile = join(sessionsDir(home), `session-${sessionId}-changes.json`);
+	if (existsSync(stateFile)) try {
+		const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+		const count = state.cumulativeCodeFiles ?? 0;
+		if (count > 0) {
+			const files = (state.modifiedFiles ?? []).join(", ");
+			writeFileSync(stateFile, JSON.stringify({
+				...state,
+				cumulativeCodeFiles: 0
+			}), "utf-8");
+			return contextResponse("SubagentStop", `SNIPER VALIDATION REQUIRED: Agent '${agentType}' modified ${count} code file(s): ${files}. Run sniper agent now.`);
+		}
+	} catch {}
+	return JSON.stringify({ message: `Agent ${agentType} completed (no code changes)` });
+}
+//#endregion
+//#region src/runtime/lifecycle/teammate-idle.ts
+/**
+* Handle TeammateIdle: when the teammate's session-changes file shows code was
+* modified, suggest sniper validation as `additionalContext`. Ports
+* `teammate-idle/validate-teammate-output.py`.
+* @param data - The raw hook payload.
+* @param home - Home dir (defaults to `~`).
+* @returns The native hook stdout (possibly empty).
+*/
+function validateTeammateOutput(data, home = homedir()) {
+	const teammate = String(data.teammate_name ?? "unknown");
+	const sessionId = String(data.session_id ?? "unknown");
+	const stateFile = join(sessionsDir(home), `session-${sessionId}-changes.json`);
+	if (!existsSync(stateFile)) return "";
+	try {
+		const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+		const count = state.cumulativeCodeFiles ?? 0;
+		if (count > 0) return contextResponse("TeammateIdle", `Teammate '${teammate}' going idle after modifying ${count} code file(s): ${(state.modifiedFiles ?? []).slice(0, 5).join(", ")}. Consider running sniper validation.`);
+	} catch {}
+	return "";
+}
+//#endregion
+//#region src/runtime/lifecycle/tool-failure.ts
+/**
+* Handle PostToolUseFailure: append a `TOOL_FAILURE` line to
+* `~/.claude/logs/tool-failures.log`, skipping user interrupts. Ports
+* `post-tool-use/log-tool-failure.py`. No stdout (logging only).
+* @param data - The raw hook payload.
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+*/
+function logToolFailure(data, home = homedir(), now = Date.now()) {
+	if (data.is_interrupt === true) return;
+	const tool = String(data.tool_name ?? "unknown");
+	const error = String(data.error ?? "unknown error");
+	const sessionId = String(data.session_id ?? "unknown");
+	const ts = new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+	const dir = join(home, ".claude", "logs");
+	try {
+		mkdirSync(dir, { recursive: true });
+		appendFileSync(join(dir, "tool-failures.log"), `[${ts}] TOOL_FAILURE session=${sessionId} tool=${tool} error=${error}\n`, "utf-8");
+	} catch {}
+}
+//#endregion
+//#region src/runtime/lifecycle/pre-compact.ts
+/** Two-digit zero-pad. */
+function pad(n) {
+	return String(n).padStart(2, "0");
+}
+/** Compact local timestamp `YYYYMMDD-HHMMSS` (mirrors Python strftime). */
+function stamp(now) {
+	const d = new Date(now);
+	return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+/**
+* Handle PreCompact: back up `.claude/apex/task.json` to `backups/`, keep only
+* the 5 newest, and emit a confirmation. Ports `pre-compact/save-apex-state.py`.
+* @param cwd - Project root.
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native hook stdout (possibly empty when no task.json).
+*/
+function saveApexState(cwd, now = Date.now()) {
+	const apexDir = join(cwd, ".claude", "apex");
+	const stateFile = join(apexDir, "task.json");
+	if (!existsSync(stateFile)) return "";
+	const backupDir = join(apexDir, "backups");
+	mkdirSync(backupDir, { recursive: true });
+	copyFileSync(stateFile, join(backupDir, `task-${stamp(now)}.json`));
+	const backups = readdirSync(backupDir).filter((n) => n.startsWith("task-") && n.endsWith(".json")).sort().reverse();
+	for (const old of backups.slice(5)) try {
+		rmSync(join(backupDir, old), { force: true });
+	} catch {}
+	return JSON.stringify({ additionalContext: "APEX state saved before compaction. Previous task state preserved in .claude/apex/backups/" });
+}
+//#endregion
+//#region src/runtime/lifecycle/session-end.ts
+/**
+* Handle SessionEnd: remove stale `*.tmp` (>1h) under `session-tmp/` and stale
+* legacy `claude_solid_reads_*` / `claude_session_changes_*` files (>2h) under
+* `fusengine-cache`. Ports `session-end/cleanup-session.py`. No stdout.
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+*/
+function cleanupSession(home = homedir(), now = Date.now()) {
+	const base = fusengineCache(home);
+	removeOldFiles(join(base, "session-tmp"), (n) => n.endsWith(".tmp"), 3600, now);
+	removeOldFiles(base, (n) => n.startsWith("claude_solid_reads_") || n.startsWith("claude_session_changes_"), 7200, now);
+}
+//#endregion
+//#region src/runtime/lifecycle/instructions-loaded.ts
+/**
+* Handle InstructionsLoaded: append `load_reason | memory_type | file_path` to
+* the per-session debug log. Ports `instructions-loaded/validate-rules-loaded.py`.
+* No stdout (logging only; InstructionsLoaded has no decision control).
+* @param data - The raw hook payload.
+* @param home - Home dir (defaults to `~`).
+*/
+function validateRulesLoaded(data, home = homedir()) {
+	const filePath = String(data.file_path ?? "");
+	const loadReason = String(data.load_reason ?? "");
+	const memoryType = String(data.memory_type ?? "");
+	const sessionId = String(data.session_id ?? "unknown");
+	const dir = join(home, ".claude", "logs", "instructions-loaded");
+	try {
+		mkdirSync(dir, { recursive: true });
+		appendFileSync(join(dir, `${sessionId}.log`), `${loadReason} | ${memoryType} | ${filePath}\n`, "utf-8");
+	} catch {}
+}
+//#endregion
+//#region src/runtime/lifecycle/track-changes.ts
+/** Code-file extensions tracked for sniper (mirrors track-session-changes.py). */
+const CODE_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|vue|svelte|astro)$/;
+/**
+* Handle PostToolUse Write/Edit: track the cumulative set of modified code
+* files per session and emit the mandatory "SNIPER VALIDATION REQUIRED"
+* additionalContext. Ports `post-tool-use/track-session-changes.py`.
+* @param sessionIdRaw - Raw session id from the payload.
+* @param filePath - The edited file path.
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native hook stdout (possibly empty when not a code file).
+*/
+function trackSessionChanges(sessionIdRaw, filePath, home = homedir(), now = Date.now()) {
+	if (!filePath || !CODE_EXT.test(filePath)) return "";
+	const sid = sanitizeSessionId(sessionIdRaw) ?? "unknown";
+	const state = loadSessionState(sid, home);
+	const prev = state.changes ?? {
+		cumulativeCodeFiles: 0,
+		modifiedFiles: []
+	};
+	const files = [...prev.modifiedFiles];
+	let count = prev.cumulativeCodeFiles;
+	if (!files.includes(filePath)) {
+		count += 1;
+		files.push(filePath);
+	}
+	state.changes = {
+		cumulativeCodeFiles: count,
+		modifiedFiles: files,
+		lastModifiedFile: filePath,
+		lastCheck: new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z")
+	};
+	saveSessionState(sid, state, home);
+	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.`);
+}
+//#endregion
+//#region src/runtime/lifecycle/post-edit-ts.ts
+const TS_EXT$1 = /\.(ts|tsx)$/;
+const TIMEOUT_MS$1 = 1e4;
+/** True when `bin` is resolvable on PATH (mirrors shutil.which). */
+function hasBin(bin) {
+	try {
+		execFileSync(process.platform === "win32" ? "where" : "which", [bin], {
+			stdio: "pipe",
+			timeout: 2e3
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Run `bin args`, returning `{ code, out }` (code 1 on spawn error). */
+function run(bin, args) {
+	try {
+		return {
+			code: 0,
+			out: execFileSync(bin, args, {
+				encoding: "utf-8",
+				stdio: "pipe",
+				timeout: TIMEOUT_MS$1
+			})
+		};
+	} catch (err) {
+		const e = err;
+		return {
+			code: e.status ?? 1,
+			out: typeof e.stdout === "string" ? e.stdout : e.stdout?.toString() ?? ""
+		};
+	}
+}
+/**
+* Handle PostToolUse for TS/TSX: report eslint/prettier issues (never fixes) as
+* additionalContext. Ports `post-tool-use/post-edit-typescript.py`.
+* @param filePath - The edited file path.
+* @returns The native hook stdout (possibly empty).
+*/
+function postEditTypescript(filePath) {
+	if (!filePath || !TS_EXT$1.test(filePath) || !existsSync(filePath)) return "";
+	const issues = [];
+	if (hasBin("eslint")) {
+		const r = run("eslint", [
+			"--no-fix",
+			"--format",
+			"compact",
+			filePath
+		]);
+		if (r.code !== 0 && r.out.trim()) issues.push(`ESLint:\n${r.out.trim()}`);
+	}
+	if (hasBin("prettier")) {
+		if (run("prettier", ["--check", filePath]).code !== 0) issues.push(`Prettier: ${basename(filePath)} needs formatting`);
+	}
+	if (issues.length === 0) return "";
+	return contextResponse("PostToolUse", `Lint issues in ${basename(filePath)}: ${issues.join(" | ")}`);
+}
+//#endregion
+//#region src/runtime/lifecycle/cartographer/fs-util.ts
+/**
+* Filesystem helpers for the cartographer tree walk. Ports the fs parts of
+* `describe.py` (file desc) and `write_recursive.py` (children + counts).
+*/
+/**
+* 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 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/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.
+*/
+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 {
+		return statSync(dir).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/**
+* 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;
+}
+/**
+* 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/runtime/lifecycle/cartographer/session-start.ts
+/**
+* Cartographer SessionStart handler. Ports the project-map half of
+* `generate_project_map.py`: regenerates `.cartographer/project` and emits no
+* additionalContext (the plugin ecosystem map from `generate_map.py` is not
+* ported and stays as Python).
+*/
+/**
+* Regenerate the project map for `cwd` on SessionStart. Returns "" (side-effect
+* only — no additionalContext).
+* @param cwd - The working directory.
+* @returns "" always.
+*/
+function cartoSessionStart(cwd) {
+	generateProjectMap(cwd);
+	return "";
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/inject-apex.ts
+/**
+* SubagentStart (matcher "") for the ai-pilot scope: inject APEX AGENTS.md +
+* task context + cartographer paths into every sub-agent. Ports
+* `inject-subagent-context.ts`. The core-scope SubagentStart already surfaces
+* the MCP cache table (`subagent-cache.ts`) in a separate hook entry — this
+* handler only emits the APEX/cartographer block, so there is no double-emit.
+*/
+/** Last 3 completed task subjects (newest first), or "none". */
+function completedTasks(tasks) {
+	const done = Object.entries(tasks).filter(([, t]) => t.status === "completed").sort((a, b) => (b[1].completed_at ?? "").localeCompare(a[1].completed_at ?? "")).slice(0, 3).map(([id, t]) => `#${id}: ${t.subject}`);
+	return done.length > 0 ? done.join(", ") : "none";
+}
+/** Pending task subjects, or "none". */
+function pendingTasks(tasks) {
+	const pending = Object.entries(tasks).filter(([, t]) => t.status === "pending").map(([id, t]) => `#${id}: ${t.subject}`);
+	return pending.length > 0 ? pending.join(", ") : "none";
+}
+/** Cartographer navigation block, or "" when no plugin map is present. */
+function cartographerContext() {
+	const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+	if (!pluginRoot) return "";
+	const pluginsMap = resolve(pluginRoot, "..", ".cartographer", "index.md");
+	if (!existsSync(pluginsMap)) return "";
+	return `\n### 7. Cartographer Maps\nNavigate branches (index.md) -> leaves link to real files:\n- Plugin skills: ${pluginsMap}\n- Project files: .cartographer/project/index.md`;
+}
+/**
+* Build the APEX sub-agent injection for SubagentStart, or "" when the project
+* has no `.claude/apex/` dir. Reads AGENTS.md (first 4KB) + task.json.
+* @param cwd - Fallback project root when `CLAUDE_PROJECT_DIR` is unset.
+* @param home - Home dir (unused placeholder; kept for symmetry/testing).
+* @returns The native hook stdout (possibly empty).
+*/
+async function injectApexSubagentContext(cwd, home = homedir()) {
+	const apexDir = join(process.env.CLAUDE_PROJECT_DIR ?? cwd, ".claude", "apex");
+	if (!existsSync(apexDir)) return "";
+	const agentsFile = Bun.file(join(apexDir, "AGENTS.md"));
+	const agents = await agentsFile.exists() ? (await agentsFile.text()).slice(0, 4e3) : "";
+	const taskData = await readJsonFile(join(apexDir, "task.json"));
+	return contextResponse("SubagentStart", `## APEX Sub-Agent Instructions
+
+You are a sub-agent in APEX workflow. Follow these rules:
+
+### 1. AGENTS.md Rules
+${agents}
+
+### 2. Task Context
+- Last completed: ${taskData ? completedTasks(taskData.tasks) : "none"}
+- Pending: ${taskData ? pendingTasks(taskData.tasks) : "none"}
+
+### 3. Before Starting Work
+- Use TaskUpdate(taskId, status: in_progress) before starting
+
+### 4. SOLID Rules
+- Files < ${resolveMaxLines()} lines | Interfaces in src/interfaces/ | JSDoc/PHPDoc required
+
+### 5. Research Before Code
+- Use Context7/Exa for docs | Write notes to .claude/apex/docs/
+
+### 6. When Done
+- TaskUpdate(taskId, status: completed) triggers auto-commit${cartographerContext()}`);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/cache-base.ts
+/**
+* Shared cache-path + age helpers for the ai-pilot scope.
+* Reuses the harness home-state (`fusengineCache`) so the ai-pilot caches live
+* under the same `~/.claude/fusengine-cache` tree as the core MCP cache — no
+* second cache layer.
+*/
+/** 16-char hex SHA-256 of `text` (project hash / doc topic key). */
+function hashText16(text) {
+	return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+/** 16-char project hash from its absolute path. */
+function projectHash(projectPath) {
+	return hashText16(projectPath);
+}
+/** `~/.claude/fusengine-cache` base dir (shared with the core MCP cache). */
+function cacheBaseDir(home = homedir()) {
+	return fusengineCache(home);
+}
+/** Per-type, per-project cache dir: `fusengine-cache/<type>/<projectHash>`. */
+function cacheDirFor(type, projectPath, home = homedir()) {
+	return join(cacheBaseDir(home), type, projectHash(projectPath));
+}
+/** Age in seconds from an ISO timestamp (now - ts). */
+function cacheAge(ts, now = Date.now()) {
+	return Math.floor((now - new Date(ts).getTime()) / 1e3);
+}
+/** Full SHA-256 hex checksum of a file's text; "" when unreadable. */
+async function fileChecksum(path) {
+	try {
+		return createHash("sha256").update(await Bun.file(path).text()).digest("hex");
+	} catch {
+		return "";
+	}
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/analytics.ts
+/**
+* Cache analytics for the ai-pilot scope: append hit/miss events to
+* `sessions.jsonl` and aggregate them into `summary.json` on SessionEnd.
+* Ports `cache-analytics-save.ts` + the `logCacheEvent` helper.
+*/
+const TOKEN_WEIGHTS = {
+	explore: 15e3,
+	doc: 1e4,
+	lessons: 3e3,
+	tests: 5e3
+};
+const CATEGORIES = [
+	"explore",
+	"doc",
+	"lessons",
+	"tests"
+];
+/** Append a single cache event to `analytics/sessions.jsonl` (best effort). */
+function logCacheEvent(type, action, projHash, extra = {}, home = homedir()) {
+	try {
+		const dir = join(cacheBaseDir(home), "analytics");
+		mkdirSync(dir, { recursive: true });
+		const entry = {
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			session: String(Math.floor(Date.now() / 1e3)),
+			type,
+			action,
+			project_hash: projHash,
+			...extra
+		};
+		appendFileSync(join(dir, "sessions.jsonl"), JSON.stringify(entry) + "\n");
+	} catch {}
+}
+/** Count entries matching a `type`+`action`. */
+function countBy(entries, type, action) {
+	return entries.filter((e) => e.type === type && e.action === action).length;
+}
+/** Format a hit-rate percentage string. */
+function hitRate(hits, misses) {
+	const total = hits + misses;
+	return total === 0 ? "0%" : `${Math.floor(hits * 100 / total)}%`;
+}
+/** Parse the JSONL session log into typed entries. */
+function parseEntries(raw) {
+	return raw.split("\n").filter(Boolean).map((line) => {
+		try {
+			return JSON.parse(line);
+		} catch {
+			return null;
+		}
+	}).filter((e) => e !== null);
+}
+/**
+* Aggregate `sessions.jsonl` into `summary.json` and prune entries > 30 days.
+* Ports `cache-analytics-save.ts`. SessionEnd hook output is ignored by Claude,
+* so this returns nothing — it is a pure side-effect.
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+*/
+async function cacheAnalyticsSave(home = homedir(), now = Date.now()) {
+	const dir = join(cacheBaseDir(home), "analytics");
+	const sessionsFile = join(dir, "sessions.jsonl");
+	const file = Bun.file(sessionsFile);
+	if (!await file.exists()) return;
+	const raw = await file.text();
+	if (!raw.trim()) return;
+	const entries = parseEntries(raw);
+	if (entries.length === 0) return;
+	const hits = {};
+	const misses = {};
+	for (const cat of CATEGORIES) {
+		hits[cat] = countBy(entries, cat, "hit") + (cat === "doc" ? countBy(entries, cat, "blocked") : 0);
+		misses[cat] = countBy(entries, cat, "miss");
+	}
+	const tokensSaved = CATEGORIES.reduce((sum, c) => sum + (hits[c] ?? 0) * (TOKEN_WEIGHTS[c] ?? 0), 0);
+	const sessionCount = new Set(entries.map((e) => e.session).filter(Boolean)).size;
+	const old = await readJsonFile(join(dir, "summary.json"));
+	const merged = {
+		updated: new Date(now).toISOString(),
+		total_sessions: (old?.total_sessions ?? 0) + sessionCount,
+		cache_hits: {},
+		cache_misses: {},
+		hit_rates: {},
+		estimated_tokens_saved: (old?.estimated_tokens_saved ?? 0) + tokensSaved
+	};
+	for (const cat of CATEGORIES) {
+		merged.cache_hits[cat] = (old?.cache_hits?.[cat] ?? 0) + (hits[cat] ?? 0);
+		merged.cache_misses[cat] = (old?.cache_misses?.[cat] ?? 0) + (misses[cat] ?? 0);
+		merged.hit_rates[cat] = hitRate(merged.cache_hits[cat] ?? 0, merged.cache_misses[cat] ?? 0);
+	}
+	await writeJsonFile(join(dir, "summary.json"), merged, true);
+	const cutoff = (/* @__PURE__ */ new Date(now - 30 * 864e5)).toISOString();
+	const kept = entries.filter((e) => e.ts >= cutoff);
+	await Bun.write(sessionsFile, kept.map((e) => JSON.stringify(e)).join("\n") + "\n");
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/inject-explore.ts
+/**
+* SubagentStart (matcher "explore-codebase") for the ai-pilot scope: serve a
+* cached architecture report when fresh + config-matching, else inject save
+* instructions. Ports `explore-cache-check.ts`.
+*/
+const TTL_SECONDS$2 = 86400;
+const CONFIG_FILES = [
+	"package.json",
+	"tsconfig.json",
+	"composer.json",
+	"go.mod",
+	"Cargo.toml",
+	"Package.swift",
+	"biome.json",
+	".eslintrc.js",
+	".eslintrc.json"
+];
+/** Compute a config hash from git-tracked config files; "noconfig" on failure. */
+async function configHash(cwd) {
+	try {
+		const proc = Bun.spawn([
+			"git",
+			"ls-tree",
+			"HEAD",
+			...CONFIG_FILES
+		], {
+			cwd,
+			stdout: "pipe",
+			stderr: "ignore"
+		});
+		const output = await new Response(proc.stdout).text();
+		return output.trim() ? hashText16(output) : "noconfig";
+	} catch {
+		return "noconfig";
+	}
+}
+/** Build the cache-miss save-instructions block. */
+function missBlock(cacheDir, metaFile, snapFile, ts, cfgHash, projPath) {
+	return `## EXPLORATION CACHE INSTRUCTIONS\nAfter completing your exploration, save the report for future runs:\n\`\`\`bash\nmkdir -p ${cacheDir}\ncat > ${metaFile} << 'METAEOF'\n{"timestamp":"${ts}","config_hash":"${cfgHash}","project":"${projPath}"}\nMETAEOF\n\`\`\`\nThen write your full exploration report (markdown) to: ${snapFile}`;
+}
+/**
+* SubagentStart for explore-codebase: inject cached architecture or save block.
+* @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native hook stdout.
+*/
+async function injectExploreCache(cwd, home = homedir(), now = Date.now()) {
+	const projPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+	const pHash = projectHash(projPath);
+	const cacheDir = cacheDirFor("explore", projPath, home);
+	const metaFile = join(cacheDir, "metadata.json");
+	const snapFile = join(cacheDir, "snapshot.md");
+	const cfgHash = await configHash(projPath);
+	let context = "";
+	const meta = await readJsonFile(metaFile);
+	const snapBunFile = Bun.file(snapFile);
+	const snapshot = await snapBunFile.exists() ? await snapBunFile.text() : "";
+	if (meta?.timestamp && snapshot) {
+		const age = cacheAge(meta.timestamp, now);
+		if (age < TTL_SECONDS$2 && meta.config_hash === cfgHash) {
+			context = `## CACHED ARCHITECTURE AVAILABLE (age: ${Math.floor(age / 60)}min)\nUSE this cached report. Do NOT run full exploration. Return it immediately.\n\n${snapshot}`;
+			logCacheEvent("explore", "hit", pHash, {}, home);
+		}
+	}
+	if (!context) {
+		logCacheEvent("explore", "miss", pHash, {}, home);
+		context = missBlock(cacheDir, metaFile, snapFile, new Date(now).toISOString().replace(/\.\d+Z$/, ""), cfgHash, projPath);
+	}
+	return contextResponse("SubagentStart", context);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/inject-doc.ts
+/**
+* SubagentStart (matcher "research-expert") for the ai-pilot scope: inject
+* cached documentation summaries. Ports `doc-cache-inject.ts`. Doc *saving*
+* happens on SubagentStop (`cache-doc.ts`).
+*/
+const TTL_SECONDS$1 = 604800;
+const MAX_SIZE = 8192;
+/** Concatenate fresh, dedup-by-hash cached doc bodies. */
+async function buildDocsContext(entries, docsDir, now) {
+	let ctx = "";
+	let count = 0;
+	let maxAge = 0;
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		if (!entry.timestamp) continue;
+		const age = cacheAge(entry.timestamp, now);
+		if (age >= TTL_SECONDS$1) continue;
+		if (age > maxAge) maxAge = age;
+		if (!entry.hash || seen.has(entry.hash)) continue;
+		seen.add(entry.hash);
+		const file = Bun.file(join(docsDir, `${entry.hash}.md`));
+		if (!await file.exists()) continue;
+		const content = await file.text();
+		if (!content) continue;
+		ctx += `\n${content}\n`;
+		count++;
+	}
+	return {
+		ctx,
+		count,
+		maxAge
+	};
+}
+/**
+* SubagentStart for research-expert: inject cached doc summaries, or "".
+* @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native hook stdout (possibly empty).
+*/
+async function injectDocCache(cwd, home = homedir(), now = Date.now()) {
+	const projPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+	const pHash = projectHash(projPath);
+	const cacheDir = cacheDirFor("doc", projPath, home);
+	const index = await readJsonFile(join(cacheDir, "index.json"));
+	if (!index?.docs?.length) return "";
+	const { ctx, count, maxAge } = await buildDocsContext(index.docs, join(cacheDir, "docs"), now);
+	if (count === 0) return "";
+	logCacheEvent("doc", "hit", pHash, { docs_injected: count }, home);
+	return contextResponse("SubagentStart", `${`## CACHED DOCUMENTATION (${count} docs, ${Math.ceil(maxAge / 3600)}h ago)\nUse this knowledge. Only query Context7 for topics NOT covered below.\n`}${ctx}Full docs: ${join(cacheDir, "docs")}/`.slice(0, MAX_SIZE));
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/source-scan.ts
+/**
+* Source-file scanning + project-stack detection for the ai-pilot scope.
+* Ported from the ai-pilot plugin's `cache/source-collector.ts` +
+* the stack detection in `cache/lesson-helpers.ts` (now removed).
+*/
+/** Source file glob patterns (monorepo-aware; separate to avoid brace-wildcards). */
+const SRC_PATTERNS = [
+	"src/**/*.{ts,tsx,js,jsx}",
+	"app/**/*.{ts,tsx,js,jsx}",
+	"apps/*/src/**/*.{ts,tsx,js,jsx}",
+	"packages/*/src/**/*.{ts,tsx,js,jsx}"
+];
+/**
+* Scan source files in `projectPath` (monorepo-aware), capped at `maxFiles`.
+* @param projectPath - Absolute project root.
+* @param maxFiles - Max files to collect (default 200).
+* @returns Absolute paths matching the source patterns.
+*/
+async function scanSourceFiles(projectPath, maxFiles = 200) {
+	const files = [];
+	for (const pattern of SRC_PATTERNS) {
+		try {
+			for await (const p of new Glob(pattern).scan({
+				cwd: projectPath,
+				absolute: true
+			})) {
+				if (p.includes("node_modules")) continue;
+				files.push(p);
+				if (files.length >= maxFiles) break;
+			}
+		} catch {}
+		if (files.length >= maxFiles) break;
+	}
+	return files;
+}
+/** Detect the project stack from config files in the project root. */
+function detectStack(projectPath) {
+	try {
+		const entries = readdirSync(projectPath);
+		if (entries.some((f) => f.startsWith("next.config"))) return "nextjs";
+		if (entries.includes("composer.json")) return "laravel";
+		if (entries.some((f) => f.endsWith(".xcodeproj")) || entries.includes("Package.swift")) return "swift";
+		if (entries.some((f) => f.startsWith("tailwind.config"))) return "tailwindcss";
+	} catch {}
+	return "universal";
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/lessons.ts
+/**
+* Lesson aggregation, dedup, merge, and edit categorization for the ai-pilot
+* scope. Ported from the ai-pilot plugin's `cache/lesson-aggregator.ts` +
+* `cache/lesson-helpers.ts` (now removed).
+*/
+/** Deduplicate lessons by `error_type:pattern`, summing counts. */
+function dedupLessons(lessons) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const l of lessons) {
+		const key = `${l.error_type}:${l.pattern}`;
+		const group = groups.get(key);
+		if (group) group.push(l);
+		else groups.set(key, [l]);
+	}
+	return [...groups.values()].map((entries) => {
+		const first = entries[0];
+		return {
+			error_type: first.error_type,
+			pattern: first.pattern,
+			fix: first.fix,
+			last_seen: first.last_seen,
+			count: entries.reduce((s, e) => s + e.count, 0),
+			files: [...new Set(entries.flatMap((e) => e.files))],
+			code: { line: [...new Set(entries.flatMap((e) => e.code?.line ?? []))].slice(0, 5) }
+		};
+	}).sort((a, b) => b.count - a.count);
+}
+/** Aggregate all local lesson JSON files into a flat deduplicated list. */
+async function aggregateLocalLessons(cacheDir) {
+	if (!existsSync(cacheDir)) return [];
+	const files = readdirSync(cacheDir).filter((f) => f.endsWith(".json"));
+	const all = [];
+	for (const f of files) {
+		const data = await readJsonFile(join(cacheDir, f));
+		if (data?.errors) all.push(...data.errors);
+	}
+	return dedupLessons(all);
+}
+/** Load global lessons for a stack (stack-specific + universal). */
+async function loadGlobalLessons(stack, home = homedir()) {
+	const globalDir = join(cacheBaseDir(home), "lessons", "_global");
+	const result = [];
+	for (const name of [`${stack}.json`, "universal.json"]) {
+		const data = await readJsonFile(join(globalDir, name));
+		if (data) result.push(...data);
+	}
+	return result;
+}
+/** Merge local + global lessons, dedup by type+pattern, sort by count desc. */
+function mergeLessons(local, global) {
+	return dedupLessons([...local, ...global]);
+}
+/** Categorize an edit entry by analyzing the new code content. */
+function categorizeEdit(edit) {
+	const n = edit.newStr.toLowerCase();
+	if (n.includes("use client")) return "missing_directive";
+	if (n.includes("displayname")) return "missing_display_name";
+	if (/onkeydown|tabindex|role=/.test(n)) return "missing_a11y";
+	if (/try|catch/.test(n)) return "missing_error_handling";
+	if (/\?\?|if.*null/.test(n)) return "null_safety";
+	return "code_fix";
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/inject-lessons.ts
+/**
+* SubagentStart (matcher "") for the ai-pilot scope: inject cached lessons
+* (known project issues) into every agent. Ports `lessons-cache-inject.ts`.
+*/
+const MAX_AGE_MS = 30 * 864e5;
+const MAX_LESSONS = 10;
+/** Remove JSON files older than 30 days from `dir` (best effort). */
+function pruneOldFiles(dir, now) {
+	try {
+		const cutoff = now - MAX_AGE_MS;
+		for (const f of readdirSync(dir).filter((n) => n.endsWith(".json"))) {
+			const path = `${dir}/${f}`;
+			try {
+				if (statSync(path).mtimeMs < cutoff) unlinkSync(path);
+			} catch {}
+		}
+	} catch {}
+}
+/** Render lessons as a numbered known-issues list. */
+function formatLessonList(lessons) {
+	return lessons.map((l, i) => {
+		const code = l.code?.line?.length ? `\n     Code: ${l.code.line.join(" | ").slice(0, 200)}` : "";
+		return `${i + 1}. [${l.count}x] | ${l.pattern ?? "unknown"} -> ${l.fix ?? "see docs"}${code}`;
+	}).join("\n");
+}
+/**
+* SubagentStart lessons injection: aggregate local + global lessons, or "".
+* @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native hook stdout (possibly empty).
+*/
+async function injectLessonsCache(cwd, home = homedir(), now = Date.now()) {
+	const projectPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+	const pHash = projectHash(projectPath);
+	const cacheDir = cacheDirFor("lessons", projectPath, home);
+	const stack = detectStack(projectPath);
+	pruneOldFiles(cacheDir, now);
+	let localLessons = [];
+	try {
+		localLessons = await aggregateLocalLessons(cacheDir);
+	} catch {}
+	const globalLessons = await loadGlobalLessons(stack, home);
+	if (localLessons.length === 0 && globalLessons.length === 0) return "";
+	const merged = mergeLessons(localLessons, globalLessons).slice(0, MAX_LESSONS);
+	if (merged.length === 0) return "";
+	logCacheEvent("lessons", "hit", pHash, {
+		count: merged.length,
+		stack
+	}, home);
+	return contextResponse("SubagentStart", `## KNOWN PROJECT ISSUES (from previous sniper validations)\nThese errors have been found and fixed before. AVOID them:\n${formatLessonList(merged)}\n\nINSTRUCTION: Check your code against these known issues BEFORE submitting.`);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/inject-test.ts
+/**
+* SubagentStart (matcher "sniper") for the ai-pilot scope: tell sniper which
+* source files changed vs. already-validated. Ports `test-cache-inject.ts`.
+*/
+const TTL_SECONDS = 172800;
+/**
+* SubagentStart for sniper: inject the changed-file list, or "" when nothing
+* useful to say (no cache / no unchanged files).
+* @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+* @param home - Home dir (defaults to `~`).
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native hook stdout (possibly empty).
+*/
+async function injectTestCache(cwd, home = homedir(), now = Date.now()) {
+	const projectPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+	const cache = await readJsonFile(join(cacheDirFor("tests", projectPath, home), "results.json"));
+	if (!cache?.files || Object.keys(cache.files).length === 0) return "";
+	const srcFiles = await scanSourceFiles(projectPath);
+	if (srcFiles.length === 0) return "";
+	const changed = [];
+	let unchanged = 0;
+	for (const filepath of srcFiles) {
+		const relPath = filepath.replace(`${projectPath}/`, "");
+		const cached = cache.files[relPath];
+		if (!cached) {
+			changed.push(relPath);
+			continue;
+		}
+		if ((await fileChecksum(filepath)).slice(0, 16) !== cached.checksum) {
+			changed.push(relPath);
+			continue;
+		}
+		if (cached.last_tested && cacheAge(cached.last_tested, now) > TTL_SECONDS) {
+			changed.push(relPath);
+			continue;
+		}
+		unchanged++;
+	}
+	if (unchanged === 0) return "";
+	const changedList = changed.map((f) => `- ${f}`).join("\n");
+	return contextResponse("SubagentStart", `## TEST CACHE (${unchanged}/${srcFiles.length} files already validated)\nOnly run linters on these CHANGED files:\n${changedList}\nSKIP linting on ${unchanged} unchanged files - already PASS.`);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/transcript.ts
+/**
+* JSONL transcript parsing helpers for the ai-pilot scope: project-root
+* detection from file paths, file-path extraction, Edit extraction, and the
+* assistant report extraction. Ported into the harness from the ai-pilot
+* plugin's `cache/project-detect.ts` + `cache/lesson-helpers.ts` (now removed).
+*/
+const ROOT_MARKERS = [
+	".git",
+	".hg",
+	"turbo.json",
+	"nx.json",
+	"lerna.json",
+	"pnpm-workspace.yaml"
+];
+const PKG_MARKERS = [
+	"package.json",
+	"composer.json",
+	"Package.swift",
+	"Cargo.toml",
+	"go.mod",
+	"pyproject.toml",
+	"Gemfile",
+	"pom.xml"
+];
+/** Detect the project root by walking up from the first file path to a marker. */
+function projectRootFromPaths(filePaths) {
+	const firstPath = filePaths[0];
+	if (!firstPath) return null;
+	const lastSlash = firstPath.lastIndexOf("/");
+	if (lastSlash <= 0) return null;
+	let dir = firstPath.substring(0, lastSlash);
+	let bestRoot = null;
+	while (dir && dir !== "/" && dir.length > 1) {
+		try {
+			const entries = readdirSync(dir);
+			if (ROOT_MARKERS.some((m) => entries.includes(m))) return dir;
+			if (PKG_MARKERS.some((m) => entries.includes(m))) bestRoot = dir;
+		} catch {
+			break;
+		}
+		const parentSlash = dir.lastIndexOf("/");
+		if (parentSlash <= 0) break;
+		dir = dir.substring(0, parentSlash);
+	}
+	return bestRoot;
+}
+/** Extract all absolute file paths from tool_use entries in a JSONL transcript. */
+async function transcriptFilePaths(transcriptPath) {
+	const text = await Bun.file(transcriptPath).text();
+	const paths = /* @__PURE__ */ new Set();
+	for (const line of text.split("\n").filter(Boolean)) try {
+		const content = JSON.parse(line)?.message?.content;
+		if (!Array.isArray(content)) continue;
+		for (const block of content) {
+			if (block?.type !== "tool_use") continue;
+			const fp = block.input?.file_path ?? block.input?.path ?? "";
+			if (typeof fp === "string" && fp.startsWith("/")) paths.add(fp);
+		}
+	} catch {}
+	return [...paths];
+}
+/** Extract deduplicated Edit tool_use entries (keyed by basename) from a transcript. */
+async function transcriptEdits(transcriptPath) {
+	const text = await Bun.file(transcriptPath).text();
+	const edits = [];
+	for (const line of text.split("\n").filter(Boolean)) try {
+		const content = JSON.parse(line)?.message?.content;
+		if (!Array.isArray(content)) continue;
+		for (const block of content) if (block?.type === "tool_use" && block.name === "Edit" && block.input?.file_path) edits.push({
+			file: block.input.file_path,
+			oldStr: block.input.old_string ?? "",
+			newStr: block.input.new_string ?? ""
+		});
+	} catch {}
+	const seen = /* @__PURE__ */ new Map();
+	for (const e of edits) seen.set(e.file.split("/").pop() ?? e.file, e);
+	return [...seen.values()];
+}
+/** Extract the last assistant text report (first 500 lines) from a transcript. */
+async function transcriptReport(transcriptPath) {
+	const text = await Bun.file(transcriptPath).text();
+	let lastReport = "";
+	for (const line of text.split("\n").filter(Boolean)) try {
+		const entry = JSON.parse(line);
+		if (entry?.message?.role !== "assistant") continue;
+		for (const block of entry.message.content ?? []) if (block.type === "text" && block.text) lastReport = block.text;
+	} catch {}
+	return lastReport.split("\n").slice(0, 500).join("\n");
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/cache-doc.ts
+/**
+* SubagentStop (matcher "research-expert") for the ai-pilot scope: extract the
+* agent's synthesis text from the transcript and cache it as documentation.
+* Ports `cache-doc-from-transcript.ts`. SubagentStop output here is a pure
+* side-effect (no stdout needed).
+*/
+const TOOL_PATTERN = /context7__query-docs|exa__get_code_context|exa__web_search/;
+const MAX_DOC_SIZE = 20480;
+const MIN_TEXT_SIZE = 200;
+const MAX_DOCS = 15;
+const RETRY_DELAYS = [
+	500,
+	1e3,
+	2e3
+];
+/** Extract the longest assistant synthesis + queried library ids from a transcript. */
+async function extractSynthesis(path) {
+	const lines = (await Bun.file(path).text()).split("\n").filter(Boolean);
+	const libraries = [];
+	let synthesis = "";
+	for (const line of lines) try {
+		const entry = JSON.parse(line);
+		const role = entry?.type ?? entry?.role;
+		const contents = entry?.message?.content;
+		if (!Array.isArray(contents)) continue;
+		for (const block of contents) {
+			if (block.type === "tool_use" && TOOL_PATTERN.test(block.name ?? "")) {
+				const lib = block.input?.libraryId ?? block.input?.query ?? "";
+				if (lib && !libraries.includes(lib)) libraries.push(lib);
+			}
+			if (role === "assistant" && block.type === "text" && typeof block.text === "string" && block.text.length > synthesis.length) synthesis = block.text;
+		}
+	} catch {}
+	return {
+		text: synthesis,
+		libraries
+	};
+}
+/**
+* SubagentStop research-expert: cache the synthesis text from the transcript.
+* @param transcript - Path to the agent JSONL transcript.
+* @param cwd - Fallback project root.
+* @param home - Home dir (defaults to `~`).
+*/
+async function cacheDocFromTranscript(transcript, cwd, home = homedir()) {
+	if (!transcript || !await Bun.file(transcript).exists()) return;
+	const projPath = projectRootFromPaths(await transcriptFilePaths(transcript)) ?? process.env.CLAUDE_PROJECT_DIR ?? cwd;
+	const cacheDir = cacheDirFor("doc", projPath, home);
+	const docsDir = join(cacheDir, "docs");
+	let result = await extractSynthesis(transcript);
+	for (const delay of RETRY_DELAYS) {
+		if (result.text.length >= MIN_TEXT_SIZE && result.libraries.length > 0) break;
+		await Bun.sleep(delay);
+		result = await extractSynthesis(transcript);
+	}
+	const { text, libraries } = result;
+	if (text.length < MIN_TEXT_SIZE || libraries.length === 0) return;
+	const indexFile = join(cacheDir, "index.json");
+	const index = await readJsonFile(indexFile) ?? {
+		project: projPath,
+		docs: []
+	};
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	const content = text.slice(0, MAX_DOC_SIZE);
+	const topic = libraries.join(", ");
+	const docHash = hashText16(topic);
+	await Bun.write(join(docsDir, `${docHash}.md`), content);
+	const sizeKb = Math.floor(content.length / 1024);
+	for (const lib of libraries) {
+		index.docs = index.docs.filter((d) => d.library !== lib);
+		index.docs.push({
+			hash: docHash,
+			library: lib,
+			topic,
+			timestamp,
+			size_kb: sizeKb
+		});
+	}
+	if (index.docs.length > MAX_DOCS) index.docs = index.docs.slice(-15);
+	await writeJsonFile(indexFile, index, true);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/cache-lessons.ts
+/**
+* SubagentStop (matcher "sniper") for the ai-pilot scope: capture error
+* patterns + corrected code from the sniper transcript as lessons. Ports
+* `cache-sniper-lessons.ts` (the dead `promote-global-lessons.ts` spawn is
+* dropped — that helper no longer exists). Pure side-effect.
+*/
+/**
+* SubagentStop sniper: extract lessons from the transcript and persist them.
+* @param transcript - Path to the agent JSONL transcript.
+* @param cwd - Fallback project root.
+* @param home - Home dir (defaults to `~`).
+*/
+async function cacheSniperLessons(transcript, cwd, home = homedir()) {
+	if (!transcript || !await Bun.file(transcript).exists()) return;
+	const edits = await transcriptEdits(transcript);
+	if (edits.length === 0) return;
+	const projectPath = projectRootFromPaths(edits.map((e) => e.file)) ?? process.env.CLAUDE_PROJECT_DIR ?? cwd;
+	const pHash = projectHash(projectPath);
+	const cacheDir = cacheDirFor("lessons", projectPath, home);
+	mkdirSync(cacheDir, { recursive: true });
+	const report = await transcriptReport(transcript);
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	const errors = edits.map((edit) => {
+		const basename = edit.file.split("/").pop() ?? edit.file;
+		const descLine = report.split("\n").find((l) => l.toLowerCase().includes(basename.toLowerCase()));
+		const errorType = categorizeEdit(edit);
+		return {
+			error_type: errorType,
+			pattern: descLine ?? `Code correction in ${basename}`,
+			fix: `Fix ${errorType} in ${basename}`,
+			count: 1,
+			last_seen: timestamp,
+			files: [edit.file],
+			code: { line: (edit.newStr ?? "").split("\n").filter(Boolean).slice(0, 10) }
+		};
+	});
+	await writeJsonFile(join(cacheDir, `${timestamp.replace(/:/g, "-")}.json`), {
+		project: projectPath,
+		timestamp,
+		errors
+	}, true);
+	logCacheEvent("lessons", "hit", pHash, { count: edits.length }, home);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/cache-test.ts
+/**
+* SubagentStop (matcher "sniper") for the ai-pilot scope: extract linter
+* results from the transcript and cache per-file checksums. Ports
+* `cache-test-results.ts`. Pure side-effect.
+*/
+/** Extract linter-related command/output text from a JSONL transcript. */
+async function extractLinterOutput(path) {
+	const text = await Bun.file(path).text();
+	const outputs = [];
+	for (const line of text.split("\n").filter(Boolean)) try {
+		const content = JSON.parse(line)?.message?.content;
+		if (!Array.isArray(content)) continue;
+		for (const block of content) {
+			if (block.type === "tool_use" && block.name === "Bash") {
+				const cmd = block.input?.command ?? "";
+				if (/eslint|tsc|biome|npx.*lint/i.test(cmd)) outputs.push(cmd);
+			}
+			if (block.type === "tool_result" || block.type === "text") outputs.push(block.text ?? block.content ?? "");
+		}
+	} catch {}
+	return outputs.join("\n");
+}
+/**
+* SubagentStop sniper: cache linter results per-file with checksums.
+* @param transcript - Path to the agent JSONL transcript.
+* @param cwd - Fallback project root.
+* @param home - Home dir (defaults to `~`).
+*/
+async function cacheTestResults(transcript, cwd, home = homedir()) {
+	if (!transcript || !await Bun.file(transcript).exists()) return;
+	const projectPath = projectRootFromPaths(await transcriptFilePaths(transcript)) ?? process.env.CLAUDE_PROJECT_DIR ?? cwd;
+	const pHash = projectHash(projectPath);
+	const cacheDir = cacheDirFor("tests", projectPath, home);
+	mkdirSync(cacheDir, { recursive: true });
+	const resultsPath = join(cacheDir, "results.json");
+	const linterOutput = await extractLinterOutput(transcript);
+	if (!linterOutput) return;
+	const srcFiles = await scanSourceFiles(projectPath);
+	if (srcFiles.length === 0) return;
+	const existing = await readJsonFile(resultsPath) ?? {
+		timestamp: "",
+		files: {}
+	};
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	const newFiles = {};
+	for (const filepath of srcFiles) {
+		const relPath = filepath.replace(`${projectPath}/`, "");
+		const checksum = (await fileChecksum(filepath)).slice(0, 16);
+		if (!checksum) continue;
+		const basename = filepath.split("/").pop() ?? "";
+		newFiles[relPath] = {
+			checksum,
+			eslint: linterOutput.includes(basename) && linterOutput.includes("error") ? "fail" : "pass",
+			tsc: "pass",
+			last_tested: timestamp
+		};
+	}
+	await writeJsonFile(resultsPath, {
+		timestamp,
+		files: {
+			...existing.files,
+			...newFiles
+		}
+	}, true);
+	logCacheEvent("tests", "hit", pHash, { count: Object.keys(newFiles).length }, home);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/apex-task-store.ts
+/**
+* APEX `task.json` mutation helpers + a directory-based lock for the ai-pilot
+* scope. Ported from the ai-pilot plugin's `apex/state.ts` + `apex/task-helpers.ts`
+* (now removed).
+*/
+/**
+* Acquire a directory-based lock with a timeout.
+* @param lockDir - Path to the lock directory.
+* @param timeoutMs - Max wait in ms (default 5000).
+* @returns A release function, or null if acquisition timed out.
+*/
+async function acquireLock(lockDir, timeoutMs = 5e3) {
+	const start = Date.now();
+	while (Date.now() - start < timeoutMs) try {
+		await mkdir(lockDir, { recursive: false });
+		return async () => {
+			try {
+				await rmdir(lockDir);
+			} catch {}
+		};
+	} catch {
+		await Bun.sleep(100);
+	}
+	return null;
+}
+/** Add a new task to `task.json`. */
+async function taskCreate(file, id, subject, desc) {
+	const data = await readJsonFile(file);
+	if (!data) return;
+	data.tasks[id] = {
+		subject,
+		description: desc,
+		status: "pending",
+		phase: "pending",
+		created_at: (/* @__PURE__ */ new Date()).toISOString(),
+		doc_consulted: {},
+		files_modified: [],
+		blockedBy: []
+	};
+	await writeJsonFile(file, data);
+}
+/** Mark a task as in_progress in `task.json`. */
+async function taskStart(file, id, subject, desc, blocked) {
+	const data = await readJsonFile(file);
+	if (!data) return;
+	if (!data.tasks[id]) data.tasks[id] = {
+		subject: "",
+		description: "",
+		status: "in_progress",
+		phase: "analyze",
+		doc_consulted: {},
+		files_modified: []
+	};
+	data.current_task = id;
+	const task = data.tasks[id];
+	Object.assign(task, {
+		status: "in_progress",
+		phase: "analyze",
+		started_at: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	if (subject) task.subject = subject;
+	if (desc) task.description = desc;
+	if (blocked) task.blockedBy = blocked.split(",");
+	await writeJsonFile(file, data);
+}
+/** Mark a task as completed in `task.json`. */
+async function taskComplete(file, id) {
+	const data = await readJsonFile(file);
+	if (!data?.tasks[id]) return;
+	Object.assign(data.tasks[id], {
+		status: "completed",
+		phase: "completed",
+		completed_at: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	await writeJsonFile(file, data);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/sync-task.ts
+/**
+* PostToolUse (matcher "TaskCreate|TaskUpdate") for the ai-pilot scope:
+* synchronize Claude task tools with `.claude/apex/task.json` and prompt an
+* auto-commit on completion when git changes are detected. Ports
+* `sync-task-tracking.ts`.
+*/
+/** True when the project has uncommitted git changes. */
+async function hasGitChanges(cwd) {
+	try {
+		const proc = Bun.spawn([
+			"git",
+			"status",
+			"--porcelain"
+		], {
+			cwd,
+			stdout: "pipe",
+			stderr: "ignore"
+		});
+		return (await new Response(proc.stdout).text()).trim().length > 0;
+	} catch {
+		return false;
+	}
+}
+/** Handle a completed task: emit the commit reminder (or the no-change note). */
+async function onComplete(taskFile, taskId, projectRoot) {
+	await taskComplete(taskFile, taskId);
+	if (!await hasGitChanges(projectRoot)) return contextResponse("PostToolUse", "Task completed. No changes to commit.");
+	return contextResponse("PostToolUse", `Task #${taskId} completed: ${(await readJsonFile(taskFile))?.tasks[taskId]?.subject ?? "Task"}\n\nChanges detected. MANDATORY: Run /fuse-commit-pro:commit to commit with smart detection.`);
+}
+/**
+* PostToolUse TaskCreate/TaskUpdate handler.
+* @param payload - The raw hook payload (`tool_name`, `tool_input`, `tool_response`).
+* @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+* @returns The native hook stdout (possibly empty).
+*/
+async function syncTaskTracking(payload, cwd) {
+	const toolName = String(payload.tool_name ?? "");
+	if (toolName !== "TaskCreate" && toolName !== "TaskUpdate") return "";
+	const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+	const taskFile = join(projectRoot, ".claude", "apex", "task.json");
+	if (!existsSync(taskFile)) return "";
+	const unlock = await acquireLock(join(projectRoot, ".claude", "apex", ".task.lock"), 1e4);
+	if (!unlock) return "";
+	try {
+		const ti = payload.tool_input ?? {};
+		if (toolName === "TaskCreate") {
+			const existing = (await readJsonFile(taskFile))?.tasks ?? {};
+			await taskCreate(taskFile, payload.tool_response?.id ?? String(Math.max(0, ...Object.keys(existing).map(Number)) + 1), ti.subject ?? "", ti.description ?? "");
+			return "";
+		}
+		const taskId = ti.taskId ?? "";
+		if (!taskId) return "";
+		const newStatus = ti.status ?? "";
+		if (newStatus === "in_progress") {
+			const blocked = ti.addBlockedBy?.join(",") ?? "";
+			await taskStart(taskFile, taskId, ti.subject || void 0, ti.description || void 0, blocked || void 0);
+		}
+		if (newStatus === "completed") return onComplete(taskFile, taskId, projectRoot);
+		return "";
+	} finally {
+		await unlock();
+	}
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/dispatch-aipilot.ts
+/**
+* ai-pilot scope dispatcher: routes Claude lifecycle events to the ported
+* cache/injection handlers by (event, agent_type matcher).
+*/
+/** The agent_type a SubagentStart/Stop payload reports. */
+function agentTypeOf(payload) {
+	return String(payload.agent_type ?? payload.subagent_type ?? "");
+}
+/** Extract the `additionalContext` text from a SubagentStart response, or "". */
+function contextTextOf(response) {
+	if (!response) return "";
+	try {
+		return JSON.parse(response).hookSpecificOutput?.additionalContext ?? "";
+	} catch {
+		return "";
+	}
+}
+/**
+* Combine two SubagentStart responses into one (Claude concatenates multiple
+* hooks' additionalContext; collapsing two matcher-"" scripts into one dispatch
+* call must do that join itself). Returns "" when both are empty.
+*/
+function combineContext(a, b) {
+	const parts = [contextTextOf(a), contextTextOf(b)].filter(Boolean);
+	return parts.length ? contextResponse("SubagentStart", parts.join("\n\n")) : "";
+}
+/** The transcript path a SubagentStop payload reports (Stop-only field). */
+function transcriptOf(payload) {
+	const t = payload.agent_transcript_path;
+	return typeof t === "string" ? t : void 0;
+}
+/** SubagentStart routing: cache injectors keyed on agent_type. */
+async function onSubagentStart(payload, cwd, now) {
+	const agent = agentTypeOf(payload);
+	if (agent.includes("explore-codebase")) return injectExploreCache(cwd, void 0, now);
+	if (agent.includes("research-expert")) return injectDocCache(cwd, void 0, now);
+	if (agent.includes("sniper")) return injectTestCache(cwd, void 0, now);
+	return combineContext(await injectApexSubagentContext(cwd), await injectLessonsCache(cwd, void 0, now));
+}
+/** SubagentStop routing: transcript-driven cache writers (side-effects). */
+async function onSubagentStop(payload, cwd) {
+	const agent = agentTypeOf(payload);
+	const transcript = transcriptOf(payload);
+	if (agent.includes("research-expert")) {
+		await cacheDocFromTranscript(transcript, cwd);
+		return "";
+	}
+	if (agent.includes("sniper")) {
+		await cacheSniperLessons(transcript, cwd);
+		await cacheTestResults(transcript, cwd);
+	}
+	return "";
+}
+/**
+* Dispatch an ai-pilot-scope lifecycle event. Returns the native stdout, or
+* `null` when unhandled (caller falls through to the default pipeline).
+*/
+async function dispatchAipilot(event, payload, cwd, now) {
+	if (event === "SubagentStart") return onSubagentStart(payload, cwd, now);
+	if (event === "SubagentStop") return onSubagentStop(payload, cwd);
+	if (event === "SessionEnd") {
+		await cacheAnalyticsSave(void 0, now);
+		return "";
+	}
+	return null;
+}
+/** PostToolUse (TaskCreate/TaskUpdate) sync for the ai-pilot scope. */
+async function aipilotPostToolUse(payload, cwd) {
+	return syncTaskTracking(payload, cwd);
+}
+//#endregion
+//#region src/runtime/lifecycle/dispatch.ts
+/** SessionStart handler keyed on plugin scope. */
+function sessionStart(input) {
+	if (input.scope === "solid") return solidDetectStart();
+	if (input.scope === "rules") return injectRules(process.env.CLAUDE_PLUGIN_ROOT ?? input.cwd);
+	if (input.scope === "carto") return cartoSessionStart(input.cwd);
+	return sessionStartCore(input.cwd, void 0, input.now);
+}
+/**
+* Route a lifecycle/session/context hook event to its ported handler. Returns
+* the native stdout when handled, or `null` when the event is not a lifecycle
+* event (so the caller falls through to the PreToolUse/PostToolUse pipeline).
+* @param input - The dispatch input.
+* @returns The native hook stdout, or `null` when unhandled.
+*/
+function dispatchLifecycle(input) {
+	switch (input.event) {
+		case "SessionStart": return sessionStart(input);
+		case "UserPromptSubmit": return input.scope === "rules" ? injectRules(process.env.CLAUDE_PLUGIN_ROOT ?? input.cwd) : null;
+		case "SubagentStart": return input.scope === "aipilot" ? "" : subagentCacheContext(input.payload.session_id);
+		case "SubagentStop": return input.scope === "aipilot" ? "" : trackAgentMemory(input.payload, void 0, input.now);
+		case "TeammateIdle": return validateTeammateOutput(input.payload);
+		case "PostToolUseFailure":
+			logToolFailure(input.payload, void 0, input.now);
+			return "";
+		case "PreCompact": return saveApexState(input.cwd, input.now);
+		case "SessionEnd":
+			if (input.scope !== "aipilot") cleanupSession(void 0, input.now);
+			return "";
+		case "InstructionsLoaded":
+			validateRulesLoaded(input.payload);
+			return "";
+		default: return null;
+	}
+}
+//#endregion
+//#region src/runtime/lifecycle/cartographer/track-enrichment.ts
+/**
+* Enrichment tracker (PostToolUse Edit/Write on `.cartographer/**\/index.md`).
+* Ports `track-enrichment.py`: persists manual descriptions to a sidecar so the
+* next regeneration can preserve them.
+*/
+/**
+* Record manually-edited descriptions from a cartographer `index.md` into the
+* adjacent `.enriched.json` sidecar. No-op for unrelated paths. No stdout.
+* @param filePath - The edited file path.
+*/
+function trackEnrichment(filePath) {
+	if (!filePath || !filePath.includes(".cartographer") || !filePath.endsWith("index.md")) return;
+	if (!existsSync(filePath)) return;
+	const sidecar = join(dirname(filePath), ".enriched.json");
+	let existing = {
+		version: 1,
+		entries: {}
+	};
+	if (existsSync(sidecar)) try {
+		existing = JSON.parse(readFileSync(sidecar, "utf-8"));
+	} catch {}
+	const entries = existing.entries ??= {};
+	let text = "";
+	try {
+		text = readFileSync(filePath, "utf-8");
+	} catch {
+		return;
+	}
+	for (const line of text.split("\n")) {
+		const e = parseEnrichment(line);
+		if (e) entries[e[0]] = e[1];
+	}
+	try {
+		writeFileSync(sidecar, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+	} catch {}
+}
+//#endregion
+//#region src/runtime/lifecycle/security/skill-state.ts
+/**
+* Shared security-tracker state: per-UTC-day JSON under
+* `~/.claude/logs/00-security`. Ports the state helpers of
+* `check-security-skill.py` / `track-skill-read.py` / `track-mcp-research.py`.
+*/
+/** `~/.claude/logs/00-security` state directory. */
+function securityStateDir(home = homedir()) {
+	return join(claudeHome(home), "logs", "00-security");
+}
+/** Current UTC date as `YYYY-MM-DD`. */
+function todayUtc(now = Date.now()) {
+	return new Date(now).toISOString().slice(0, 10);
+}
+/** Current UTC instant as `YYYY-MM-DDTHH:MM:SSZ` (seconds, no millis). */
+function isoUtc(now = Date.now()) {
+	return new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** Today's security-state file path. */
+function securityStatePath(now = Date.now(), home = homedir()) {
+	return join(securityStateDir(home), `${todayUtc(now)}-state.json`);
+}
+/** Load today's security state, or `{}` when missing/corrupt. */
+function loadSecurityState(now = Date.now(), home = homedir()) {
+	const path = securityStatePath(now, home);
+	try {
+		if (!existsSync(path)) return {};
+		const data = JSON.parse(readFileSync(path, "utf-8"));
+		return typeof data === "object" && data !== null && !Array.isArray(data) ? data : {};
+	} catch {
+		return {};
+	}
+}
+/** Persist today's security state (indent 2, no trailing newline). */
+function saveSecurityState(state, now = Date.now(), home = homedir()) {
+	mkdirSync(securityStateDir(home), { recursive: true });
+	writeFileSync(securityStatePath(now, home), JSON.stringify(state, null, 2), "utf-8");
+}
+//#endregion
+//#region src/runtime/lifecycle/security/track-skill-read.ts
+/**
+* Security skill-read tracker (PostToolUse Read). Ports `track-skill-read.py`:
+* flips `skill_read` once a security skill reference is read.
+*/
+const SKILL_RE = /skills\/(security-scan|cve-research|dependency-audit|security-headers|auth-audit)\//;
+/**
+* Mark the security skill as read when a Read hits a security skill reference.
+* No-op for other tools/paths. No stdout.
+* @param tool - The tool name.
+* @param filePath - The read file path.
+* @param now - Clock.
+* @param home - Home dir.
+*/
+function trackSkillRead(tool, filePath, now = Date.now(), home = homedir()) {
+	if (tool !== "Read") return;
+	if (!SKILL_RE.test(filePath)) return;
+	const state = loadSecurityState(now, home);
+	state.skill_read = true;
+	(state.reads ??= []).push({
+		timestamp: isoUtc(now),
+		file: filePath
+	});
+	saveSecurityState(state, now, home);
+}
+//#endregion
+//#region src/runtime/lifecycle/security/track-mcp.ts
+/**
+* Security MCP-research tracker (PostToolUse context7/exa). Ports
+* `track-mcp-research.py`: logs documentation queries to today's state.
+*/
+/**
+* Append a context7/exa research call to today's security state. No-op for other
+* tools. No stdout.
+* @param tool - The tool name.
+* @param input - The tool input (query/libraryId/libraryName).
+* @param now - Clock.
+* @param home - Home dir.
+*/
+function trackMcpResearch(tool, input, now = Date.now(), home = homedir()) {
+	if (!tool.includes("context7") && !tool.includes("exa")) return;
+	const query = String(input.query ?? input.libraryId ?? input.libraryName ?? "");
+	const state = loadSecurityState(now, home);
+	(state.research ??= []).push({
+		timestamp: isoUtc(now),
+		tool,
+		query
+	});
+	saveSecurityState(state, now, home);
+}
+//#endregion
+//#region src/runtime/lifecycle/changelog-research.ts
+/**
+* Changelog research tracker (PostToolUse exa/WebFetch/WebSearch). Ports
+* `track-watch-research.py`: logs research queries to
+* `~/.claude/logs/00-changelog/<utc-date>-research.json`.
+*/
+/**
+* Append an exa/WebFetch/WebSearch query to today's changelog research log.
+* No-op for other tools. No stdout (errors swallowed).
+* @param tool - The tool name.
+* @param input - The tool input (query/url/prompt).
+* @param now - Clock.
+* @param home - Home dir.
+*/
+function trackWatchResearch(tool, input, now = Date.now(), home = homedir()) {
+	if (!tool.includes("exa") && !tool.includes("WebFetch") && !tool.includes("WebSearch")) return;
+	const query = String(input.query ?? input.url ?? input.prompt ?? "");
+	const dir = join(claudeHome(home), "logs", "00-changelog");
+	try {
+		mkdirSync(dir, { recursive: true });
+		const path = join(dir, `${todayUtc(now)}-research.json`);
+		let state = { queries: [] };
+		if (existsSync(path)) try {
+			state = JSON.parse(readFileSync(path, "utf-8"));
+		} catch {
+			state = { queries: [] };
+		}
+		state.queries.push({
+			timestamp: isoUtc(now),
+			tool,
+			query
+		});
+		writeFileSync(path, JSON.stringify(state, null, 2), "utf-8");
+	} catch {}
+}
+//#endregion
+//#region src/runtime/lifecycle/post-tracking.ts
+/**
+* Dispatch the appropriate PostToolUse tracker for the invoking scope. Carto
+* persists manual enrichments; security records skill reads + MCP research;
+* changelog records watch research. Side-effect only.
+* @param scope - The invoking plugin scope.
+* @param event - The normalized event.
+* @param input - The raw tool input.
+* @param now - Clock.
+*/
+function postTrackingSideEffects(scope, event, input, now) {
+	if (scope === "carto" && (event.tool === "Edit" || event.tool === "Write") && event.filePath) {
+		trackEnrichment(event.filePath);
+		return;
+	}
+	if (scope === "security") {
+		trackSkillRead(event.tool, event.filePath ?? "", now);
+		trackMcpResearch(event.tool, input, now);
+		return;
+	}
+	if (scope === "changelog") trackWatchResearch(event.tool, input, now);
+}
+//#endregion
+//#region src/runtime/lifecycle/security/check-skill.ts
+/**
+* Security advisory (PreToolUse Write/Edit on code files) — NON-BLOCKING.
+* Ports `check-security-skill.py`: nudge the agent to read the security skill,
+* but always allow the edit.
+*/
+const CODE_RE = /\.(ts|tsx|js|jsx|py|php|swift|go|rs|rb|java)$/;
+const ADVISORY = "SECURITY: Read security skill references before modifying code. Use: Read skills/security-scan/references/scan-patterns.md";
+/**
+* Build a non-blocking PreToolUse `allow` response with a security advisory when
+* editing a code file before the security skill has been read. "" otherwise.
+* @param tool - The tool name (`Write`/`Edit`).
+* @param filePath - The target file path.
+* @param now - Clock.
+* @param home - Home dir.
+* @returns The advisory response JSON, or "".
+*/
+function securityAdvisory(tool, filePath, now = Date.now(), home = homedir()) {
+	if (tool !== "Write" && tool !== "Edit") return "";
+	if (!CODE_RE.test(filePath)) return "";
+	const path = securityStatePath(now, home);
+	if (existsSync(path)) try {
+		if (JSON.parse(readFileSync(path, "utf-8")).skill_read === true) return "";
+	} catch {}
+	return JSON.stringify({ hookSpecificOutput: {
+		hookEventName: "PreToolUse",
+		permissionDecision: "allow",
+		additionalContext: ADVISORY
+	} });
+}
+//#endregion
+//#region src/runtime/lifecycle-bridge.ts
+/** Raw event name from a payload (Cline lacks one; lifecycle is Claude-only). */
+function rawEvent(payload) {
+	return typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+}
+/**
+* Run the ported lifecycle/session/context hooks (SessionStart, SubagentStart/
+* Stop, TeammateIdle, PostToolUseFailure, PreCompact, SessionEnd,
+* InstructionsLoaded, rules-scope UserPromptSubmit). Returns the native stdout
+* when handled, or `null` to fall through to the tool-use pipeline.
+* @param payload - The raw hook payload.
+* @param cwd - Project root.
+* @param scope - The invoking plugin scope (defaults to `core`).
+* @param now - Clock.
+* @returns The native stdout, or `null` when unhandled.
+*/
+function lifecycleStdout(payload, cwd, scope, now) {
+	return dispatchLifecycle({
+		event: rawEvent(payload),
+		payload,
+		cwd,
+		scope,
+		now
+	});
+}
+/**
+* Post-edit additions for core-scope PostToolUse Write/Edit: track cumulative
+* session changes (sniper reminder) + report eslint/prettier issues. Returns the
+* combined extra stdout (track-changes wins; lint appended only when no track
+* output), or "" when nothing to emit.
+* @param scope - The invoking plugin scope.
+* @param event - The normalized event.
+* @param now - Clock.
+* @returns The extra stdout (possibly empty).
+*/
+function postEditContext(scope, event, now) {
+	if (scope !== "core" || event.tool !== "Write" && event.tool !== "Edit" || !event.filePath) return "";
+	return trackSessionChanges(event.sessionId, event.filePath, void 0, now) || postEditTypescript(event.filePath);
+}
+//#endregion
+//#region src/runtime/dry-patterns.ts
+/** Short identifiers never worth a duplication check (control flow, tiny names). */
+const DRY_KEYWORDS = /* @__PURE__ */ new Set([
+	"if",
+	"for",
+	"while",
+	"switch",
+	"catch",
+	"return",
+	"async",
+	"new",
+	"get",
+	"set",
+	"map",
+	"run",
+	"use",
+	"test",
+	"main"
+]);
+/** Extensions treated as TS/JS-family for symbol extraction. */
+const TS_EXT = /* @__PURE__ */ new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".astro"
+]);
+/** Declaration patterns whose capture group 1 is the declared symbol name (TS/JS). */
+const TS_PATTERNS = [
+	/(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*[(<]/g,
+	/(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*(?:async\s*)?\(/g,
+	/class\s+(\w+)\b/g
+];
+/**
+* Declaration patterns for PHP (capture group 1 = symbol name). The modifier run
+* is bounded (`{0,6}`) on purpose: an unbounded `(?:…\s+)*` is quadratic (O(n²))
+* on a long whitespace/keyword run with no trailing `function`, which would block
+* the hook for seconds on a crafted file. A real PHP signature has at most a few
+* leading keywords, so the bound is behavior-equivalent and keeps matching linear.
+*/
+const PHP_PATTERNS = [/(?:(?:public|protected|private|static|final|abstract|readonly)\s+){0,6}function\s+(\w+)\s*\(/g, /(?:class|interface|trait)\s+(\w+)\b/g];
+/** Directories grep skips when scanning for existing declarations. */
+const EXCLUDE_DIRS = [
+	"vendor",
+	"node_modules",
+	".next",
+	".git",
+	"dist",
+	"build",
+	"coverage",
+	".turbo"
+];
+//#endregion
+//#region src/runtime/dry.ts
+/** Extract long (>12 char) declared symbol names from new file content. */
+function extractSymbols(content, ext) {
+	const pats = TS_EXT.has(ext) ? TS_PATTERNS : ext === ".php" ? PHP_PATTERNS : [];
+	const names = /* @__PURE__ */ new Set();
+	for (const re of pats) for (const m of content.matchAll(re)) {
+		const n = m[1];
+		if (n && !DRY_KEYWORDS.has(n) && n.length > 12) names.add(n);
+	}
+	return [...names];
+}
+/** `modules/X/...` -> `"X"`, else `""` (module-boundary key). */
+function moduleOf(path) {
+	const parts = path.split(sep);
+	const i = parts.indexOf("modules");
+	return i >= 0 && i + 1 < parts.length ? parts[i + 1] ?? "" : "";
+}
+/**
+* Grep the codebase for existing declarations of the symbols a write introduces,
+* honoring module boundaries (cross-`modules/` matches are ignored). Effectful:
+* shells out to `grep`. Fails open (returns no duplicates) on any grep error,
+* timeout, or no-match — matching the original Python hook.
+*/
+function detectDuplication(filePath, content, cwd) {
+	const ext = extname(filePath).toLowerCase();
+	if (!TS_EXT.has(ext) && ext !== ".php") return {
+		names: [],
+		duplicates: []
+	};
+	const names = extractSymbols(content, ext);
+	if (!names.length) return {
+		names,
+		duplicates: []
+	};
+	const include = TS_EXT.has(ext) ? [
+		"--include=*.ts",
+		"--include=*.tsx",
+		"--include=*.js",
+		"--include=*.jsx"
+	] : ["--include=*.php"];
+	const pattern = `${TS_EXT.has(ext) ? "(function|const|let|class|interface)\\s+" : "(function|class|interface|trait)\\s+"}(${names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`;
+	let out = "";
+	try {
+		out = execFileSync("grep", [
+			"-rEl",
+			...EXCLUDE_DIRS.map((d) => `--exclude-dir=${d}`),
+			...include,
+			"--",
+			pattern,
+			cwd
+		], {
+			encoding: "utf8",
+			timeout: 1500
+		});
+	} catch {
+		return {
+			names,
+			duplicates: []
+		};
+	}
+	const self = resolve(filePath);
+	const targetMod = moduleOf(filePath);
+	const duplicates = [];
+	for (const line of out.split("\n")) {
+		const f = line.trim();
+		if (!f || resolve(f) === self) continue;
+		const dupMod = moduleOf(f);
+		if (targetMod && dupMod && dupMod !== targetMod) continue;
+		duplicates.push(f);
+	}
+	return {
+		names,
+		duplicates
+	};
+}
+/** Blocking prompt when a Write/Edit re-declares 2+ existing symbols, else null. */
+function dryGate(tool, filePath, content, cwd) {
+	if (!cwd || tool !== "Write" && tool !== "Edit" || !content) return null;
+	const dup = detectDuplication(filePath, content, cwd);
+	if (dup.duplicates.length < 2) return null;
+	return {
+		kind: "block",
+		title: "Duplicate code (DRY)",
+		reason: `[${dup.names.slice(0, 5).join(", ")}] already declared in: ${dup.duplicates.slice(0, 3).join(", ")}. Import and reuse instead of re-declaring.`,
+		actions: ["Import the existing symbol instead of re-declaring it", "Extend the existing module"]
+	};
+}
+//#endregion
+//#region src/runtime/precommit.ts
+const TIMEOUT_MS = 3e4;
+const ESLINT_CONFIGS = [
+	".eslintrc.json",
+	".eslintrc.js",
+	"eslint.config.js",
+	"eslint.config.mjs",
+	"eslint.config.ts"
+];
+const PRETTIER_CONFIGS = [
+	".prettierrc",
+	".prettierrc.json",
+	"prettier.config.js"
+];
+/** Run a linter; returns its error output, or "" if it passed / spawn-failed / timed out (fail-open). */
+function runLinter(file, args, label, cwd) {
+	try {
+		execFileSync(file, args, {
+			cwd,
+			timeout: TIMEOUT_MS,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		return "";
+	} catch (e) {
+		const err = e;
+		if (err.status === void 0 || err.status === null) return "";
+		const out = (err.stdout?.toString() ?? err.stderr?.toString() ?? "").trim();
+		return out ? `[${label}]\n${out}` : "";
+	}
+}
+/** Run the applicable linters in `cwd`, returning a block of errors per failing tool. */
+function collectErrors(cwd) {
+	const has = (f) => existsSync(join(cwd, f));
+	const errors = [];
+	if (has("package.json")) {
+		if (ESLINT_CONFIGS.some(has)) {
+			const m = runLinter("bunx", [
+				"eslint",
+				".",
+				"--max-warnings",
+				"0"
+			], "ESLint", cwd);
+			if (m) errors.push(m);
+		}
+		if (has("tsconfig.json")) {
+			const m = runLinter("bunx", ["tsc", "--noEmit"], "TypeScript", cwd);
+			if (m) errors.push(m);
+		}
+		if (PRETTIER_CONFIGS.some(has)) {
+			const m = runLinter("bunx", [
+				"prettier",
+				"--check",
+				"."
+			], "Prettier", cwd);
+			if (m) errors.push(m);
+		}
+	}
+	if (has("requirements.txt") || has("pyproject.toml")) {
+		const m = runLinter("ruff", ["check", "."], "Ruff", cwd);
+		if (m) errors.push(m);
+	}
+	return errors;
+}
+/** Block a `git commit` when linters fail (effectful: runs eslint/tsc/prettier/ruff, never auto-fixes). */
+function preCommitGate(tool, command, cwd) {
+	if (tool !== "Bash" || !command || !cwd) return null;
+	if (!command.startsWith("git") || !command.includes("commit")) return null;
+	const errors = collectErrors(cwd);
+	if (!errors.length) return null;
+	return {
+		kind: "block",
+		title: "Pre-commit checks failed",
+		reason: `COMMIT BLOCKED — fix then retry:\n\n${errors.join("\n\n")}`,
+		actions: ["Fix the linter/type errors above", "Re-run the commit"]
+	};
+}
+//#endregion
+//#region src/runtime/modular.ts
+const NEXT_CONVENTION = /^(page|layout|loading|error|not-found|route|template|default|global-error|opengraph-image|twitter-image|icon|apple-icon|sitemap|robots|manifest|middleware)\.(tsx|ts|js|jsx)$/;
+const NEXT_STATIC = /\.(css|ico|png|jpg|svg|json)$/;
+const PHP_BLOCKED_IN_APP = [
+	"/app/Models/",
+	"/app/Services/",
+	"/app/Actions/",
+	"/app/Http/Controllers/",
+	"/app/Http/Requests/",
+	"/app/Http/Resources/",
+	"/app/Contracts/",
+	"/app/DTOs/",
+	"/app/Repositories/",
+	"/app/Events/",
+	"/app/Listeners/",
+	"/app/Jobs/",
+	"/app/Notifications/",
+	"/app/Policies/"
+];
+const block = (reason) => ({
+	kind: "block",
+	title: "Modular architecture",
+	reason,
+	actions: ["Move the code into the correct feature module", "Import only from the shared core module"]
+});
+/** Next.js `modules/` architecture: `app/` convention + cross-module import rules. */
+function nextModular(filePath, content, cwd) {
+	const rel = relative(cwd, filePath);
+	const bn = basename(filePath);
+	if ((rel.startsWith("app/") || rel.startsWith("src/app/")) && !NEXT_CONVENTION.test(bn) && !NEXT_STATIC.test(bn)) return block(`BLOCKED: modular Next.js — '${bn}' is not an app/ convention file. Move business logic to modules/[feature]/.`);
+	const mod = filePath.match(/\/modules\/([^/]+)\//);
+	if (!mod) return null;
+	const current = mod[1] ?? "";
+	for (const m of content.matchAll(/from\s+['"][@.][^'"]*?\/modules\/([^/]+)\//g)) {
+		const imported = m[1] ?? "";
+		if (current === "cores") {
+			if (imported !== "cores" && imported !== "core") return block(`BLOCKED: modules/cores/ must not import from modules/${imported}/.`);
+		} else if (imported !== current && imported !== "cores" && imported !== "core") return block(`BLOCKED: cross-module import — '${current}' imports '${imported}'. Only modules/cores/ is shared.`);
+	}
+	return null;
+}
+/** Laravel FuseCore architecture: `app/` domain ban + module.json + cross-module `use` rules. */
+function fusecore(filePath, content, cwd) {
+	for (const b of PHP_BLOCKED_IN_APP) if (filePath.includes(b)) return block(`BLOCKED: FuseCore — domain code in '${b}' must move to FuseCore/{Module}/App/.`);
+	const mod = filePath.match(/\/FuseCore\/([A-Za-z]+)\//);
+	if (!mod) return null;
+	const name = mod[1] ?? "";
+	if (!existsSync(join(cwd, "FuseCore", name, "module.json"))) return block(`BLOCKED: FuseCore module '${name}' is missing module.json — create it first.`);
+	for (const m of content.matchAll(/use\s+FuseCore\\(\w+)\\/g)) {
+		const imported = m[1] ?? "";
+		if (name === "Core") {
+			if (imported !== "Core") return block(`BLOCKED: FuseCore\\Core\\ must not use FuseCore\\${imported}\\.`);
+		} else if (imported !== name && imported !== "Core") return block(`BLOCKED: cross-module use — '${name}' uses '${imported}'. Only FuseCore\\Core\\ is shared.`);
+	}
+	return null;
+}
+/** Enforce the project's modular architecture (Next.js `modules/` or Laravel FuseCore) on a Write/Edit. */
+function modularGate(tool, filePath, content, cwd) {
+	if (tool !== "Write" && tool !== "Edit" || !filePath || !cwd) return null;
+	if (/\/(node_modules|dist|build|\.next|vendor|storage)\//.test(filePath)) return null;
+	const arch = detectModularArchitecture(cwd);
+	if (arch === "nextjs-modular" && /\.(tsx|ts|jsx|js)$/.test(filePath)) return nextModular(filePath, content ?? "", cwd);
+	if (arch === "fusecore" && filePath.endsWith(".php")) return fusecore(filePath, content ?? "", cwd);
+	return null;
+}
+//#endregion
+//#region src/runtime/framework-skill-gate.ts
+/**
+* Effective line count for the SOLID size check. On an Edit, `content` is only
+* the `new_string` snippet, so judge the larger of the snippet and the full
+* on-disk file (`existingLines`) — mirroring the base file-size guard and the
+* Python `get_full_file_content`. On Write, `content` IS the full file, so the
+* snippet count stands (undefined → the gate falls back to `countLines`).
+* @param tool - the tool name ("Edit" | "Write" | ...).
+* @param content - the written content (snippet on Edit, full file on Write).
+* @param existingLines - full on-disk line count, when known.
+*/
+function effectiveLines(tool, content, existingLines) {
+	if (tool !== "Edit" || existingLines === void 0) return void 0;
+	return Math.max(countLines(content), existingLines);
+}
+/**
+* Framework-aware SOLID + sub-skill gate, run on the Write/Edit path once a
+* `filePath` is present. Combines:
+*  - {@link frameworkSolidGate}: framework-specific SOLID rules (line limits,
+*    interface/protocol separation, `'use client'`, @MainActor...).
+*  - {@link skillTriggerGate}: blocks when written APIs need a sub-skill that
+*    was not read this session, also forcing the modular-architecture skill
+*    resolved from disk via {@link requiredArchSkill}.
+*
+* @param input - the gated tool-use (filePath + content + framework + cwd).
+* @param refsRead - in-session read reference paths (from the loaded track).
+* @param existingLines - full on-disk line count (so an Edit on an oversized
+*   file still fires the framework SOLID size rule). Omit on Write.
+* @returns the first blocking {@link Prompt}, or `null` to allow.
+*/
+function frameworkSkillGate(input, refsRead, existingLines) {
+	if (!input.filePath) return null;
+	const content = input.content ?? "";
+	const solid = frameworkSolidGate(input.filePath, content, effectiveLines(input.tool, content, existingLines));
+	if (solid) return solid;
+	const forced = input.cwd ? requiredArchSkill(input.cwd) : null;
+	return skillTriggerGate(input.framework, content, refsRead, forced, input.cwd);
+}
+//#endregion
+//#region src/runtime/gate.ts
+/** Prior agents the freshness gate requires before a code edit. */
+const REQUIRED_AGENTS = ["explore-codebase", "research-expert"];
+/** Default freshness window for {@link REQUIRED_AGENTS} (2 min — matches the plugin's `FUSE_ENFORCE_TTL_SEC` default). */
+const DEFAULT_WINDOW_MS = 12e4;
+/** Trivial edits allowed within the window before the full APEX gates apply. */
+const TRIVIAL_BUDGET = 4;
+/**
+* Code-only line count of the existing on-disk file (undefined if
+* absent/unreadable). Uses {@link countLines} (skips blank/comment lines) to
+* mirror the Python `count_code_lines(get_full_file_content(...))`, so a partial
+* Edit judges the full file by the SAME metric as the incoming snippet — a raw
+* `split("\n").length` would over-count JSDoc/blank lines (and add a
+* trailing-newline off-by-one), falsely blocking well-documented files.
+*/
+function existingLineCount(path) {
+	if (!path) return void 0;
+	try {
+		return existsSync(path) ? countLines(readFileSync(path, "utf8")) : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Full gate: the stateless guards (file-size, git, security...) first, then a
+* trivial-edit fast path, then the stateful APEX gates fed from the session
+* track. Returns the first blocking prompt, or null to allow.
+*/
+async function gate(input) {
+	const existingLines = existingLineCount(input.filePath);
+	let quick;
+	try {
+		quick = evaluate({
+			tool: input.tool,
+			filePath: input.filePath,
+			content: input.content,
+			command: input.command,
+			agentType: input.agentType,
+			existingLines
+		});
+	} catch {
+		return FAIL_CLOSED;
+	}
+	if (quick.decision !== "allow" && quick.prompt) return quick.prompt;
+	const precommit = preCommitGate(input.tool, input.command, input.cwd);
+	if (precommit) return precommit;
+	const modular = modularGate(input.tool, input.filePath, input.content, input.cwd);
+	if (modular) return modular;
+	if (!input.filePath) return null;
+	const window = input.windowMs ?? 12e4;
+	const track = await loadTrack(input.trackFile);
+	const solidOrSkill = frameworkSkillGate(input, track.refsRead, existingLines);
+	if (solidOrSkill) return solidOrSkill;
+	const lineCount = input.content === void 0 ? Number.POSITIVE_INFINITY : input.content.split("\n").length;
+	if (!input.isReplaceAll && lineCount < 5 && trivialCount(track, window, input.now) < 4) {
+		await saveTrack(input.trackFile, recordTrivialEdit(track, input.now, window, input.now));
+		return null;
+	}
+	const ctx = {
+		sessionId: input.sessionId,
+		framework: input.framework,
+		filePath: input.filePath,
+		content: input.content ?? "",
+		authorizations: track.authorizations,
+		refs: input.refs,
+		refsRead: track.refsRead,
+		agentsFresh: agentsFresh(track, [...REQUIRED_AGENTS], window, input.now),
+		brainstormRequired: track.brainstormRequired,
+		brainstormFresh: agentsFresh(track, ["brainstorming"], window, input.now)
+	};
+	try {
+		const apex = evaluateApex(ctx);
+		if (apex) return apex;
+	} catch {
+		return FAIL_CLOSED;
+	}
+	return dryGate(input.tool, input.filePath, input.content, input.cwd);
+}
+//#endregion
+//#region src/runtime/handle-pre.ts
+/**
+* Run the PreToolUse pipeline: MCP/WebFetch cache intercept, design gate, APEX
+* Task context injection, then the stateless+APEX gate chain. Returns the native
+* hook outcome (deny/ask/inject or allow).
+* @param ctx - The resolved pre-context.
+* @returns The hook outcome.
+*/
+async function handlePre(ctx) {
+	const { id, payload, event, framework, mcpDir, file, opts } = ctx;
+	const intercept = mcpPreIntercept(id, event.tool, event.input, mcpDir, MCP_TTL_MS, opts.now);
+	if (intercept !== null) {
+		if (intercept.docSource) await recordActivity(file, {
+			kind: "doc",
+			framework,
+			sessionId: event.sessionId,
+			source: intercept.docSource
+		});
+		return {
+			stdout: intercept.stdout,
+			exit: 0
+		};
+	}
+	const designBlock = designGate(payload, event, mcpDir, opts.cwd);
+	if (designBlock) return {
+		stdout: respond(id, designBlock),
+		exit: 0
+	};
+	if (opts.scope === "security") return {
+		stdout: securityAdvisory(event.tool, event.filePath ?? "", opts.now),
+		exit: 0
+	};
+	if (event.tool === "Task") {
+		const taskCtx = taskContext(opts.cwd);
+		if (taskCtx) return {
+			stdout: taskCtx,
+			exit: 0
+		};
+	}
+	const prompt = await gate({
+		sessionId: event.sessionId,
+		framework,
+		tool: event.tool,
+		filePath: event.filePath,
+		content: event.content,
+		command: event.command,
+		cwd: opts.cwd,
+		refs: opts.refsDir ? await loadRefs(opts.refsDir) : void 0,
+		isReplaceAll: event.input.replace_all === true,
+		agentType: event.agentType,
+		windowMs: opts.windowMs,
+		now: opts.now,
+		trackFile: file
+	});
+	return prompt ? {
+		stdout: respond(id, prompt),
+		exit: 0
+	} : {
+		stdout: "",
+		exit: 0
+	};
+}
+//#endregion
+//#region src/runtime/handle.ts
+/** Raw Claude hook event name from a payload (empty when absent). */
+function rawEventName(payload) {
+	return typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+}
+/**
+* The full hook handler: on a PRE event it gates the tool-use (stateless guards
+* then APEX gates from the session track) and returns the native response; on a
+* POST event it records the activity into the track. The loop that makes the
+* package behave like the Claude plugin, on any harness.
+*/
+async function handleHook(id, payload, opts) {
+	const event = normalizeEvent(id, payload);
+	const layout = projectLayout(opts.cwd);
+	const file = trackFile(event.sessionId, layout.trackDir);
+	const mcpDir = layout.cacheDir;
+	const framework = detectFramework(event.filePath ?? "", event.content ?? "");
+	if (designLifecycle(payload, mcpDir, opts.cwd, String(opts.now), opts.now)) return {
+		stdout: "",
+		exit: 0
+	};
+	if (opts.scope === "aipilot") {
+		const ai = await dispatchAipilot(rawEventName(payload), payload, opts.cwd, opts.now);
+		if (ai !== null) return {
+			stdout: ai,
+			exit: 0
+		};
+	}
+	const life = lifecycleStdout(payload, opts.cwd, opts.scope ?? "core", opts.now);
+	if (life !== null) return {
+		stdout: life,
+		exit: 0
+	};
+	const userPrompt = typeof payload.prompt === "string" ? payload.prompt : void 0;
+	if (userPrompt !== void 0) {
+		await saveTrack(file, recordBrainstormRequired(await loadTrack(file), detectCreationIntent(userPrompt)));
+		return {
+			stdout: promptSubmitContext(userPrompt, opts.cwd),
+			exit: 0
+		};
+	}
+	if (event.phase === "post") {
+		const response = payload.tool_response ?? payload.tool_output;
+		mcpPostStore(event.tool, event.input, response, mcpDir);
+		const designWarn = designGate(payload, event, mcpDir, opts.cwd);
+		const activity = activityFor({
+			tool: event.tool,
+			input: event.input,
+			sessionId: event.sessionId,
+			framework,
+			now: opts.now,
+			responseLength: extractText(response).length
+		});
+		if (activity) await recordActivity(file, activity);
+		postTrackingSideEffects(opts.scope ?? "core", event, event.input, opts.now);
+		if (opts.scope === "aipilot" && (event.tool === "TaskCreate" || event.tool === "TaskUpdate")) {
+			const out = await aipilotPostToolUse(payload, opts.cwd);
+			if (out) return {
+				stdout: out,
+				exit: 0
+			};
+		}
+		const extra = postEditContext(opts.scope ?? "core", event, opts.now);
+		return {
+			stdout: designWarn ? respond(id, designWarn) : extra,
+			exit: 0
+		};
+	}
+	return handlePre({
+		id,
+		payload,
+		event,
+		framework,
+		mcpDir,
+		file,
+		opts
+	});
+}
+//#endregion
+export { purgeTtlTree as $, isProject as A, cleanupSession as B, todayUtc as C, activityFor as Ct, dispatchAipilot as D, aipilotPostToolUse as E, getFileDesc as F, subagentCacheContext as G, logToolFailure as H, listChildren as I, injectRules as J, detectSolidProfile as K, postEditTypescript as L, loadEnriched as M, mergeLines as N, cartoSessionStart as O, countFiles as P, pruneEmptyDirs as Q, trackSessionChanges as R, securityStatePath as S, queryOf as St, dispatchLifecycle as T, validateTeammateOutput as U, saveApexState as V, trackAgentMemory as W, runSessionStartCleanups as X, readRules as Y, sessionStartCore as Z, trackSkillRead as _, normalizeEvent as _t, TRIVIAL_BUDGET as a, claudeHome as at, saveSecurityState as b, mcpPostStore as bt, detectDuplication as c, sanitizeSessionId as ct, lifecycleStdout as d, sessionsDir as dt, removeOldFiles as et, postEditContext as f, promptSubmitContext as ft, trackMcpResearch as g, trackFile as gt, trackWatchResearch as h, recordActivity as ht, REQUIRED_AGENTS as i, projectContext as it, writeTree as j, generateProjectMap as k, dryGate as l, saveSessionState as lt, postTrackingSideEffects as m, respond as mt, handlePre as n, devContext as nt, gate as o, fusengineCache as ot, securityAdvisory as p, taskContext as pt, solidDetectStart as q, DEFAULT_WINDOW_MS as r, gitContext as rt, preCommitGate as s, loadSessionState as st, handleHook as t, trimLogFile as tt, extractSymbols as u, sessionStatePath as ut, isoUtc as v, MCP_TTL_MS as vt, trackEnrichment as w, securityStateDir as x, mcpPreIntercept as xt, loadSecurityState as y, isMcpTool as yt, validateRulesLoaded as z };