@fusengine/harness 0.1.41 → 0.1.42

package/dist/{handle-VhWQxvyN.mjs → handle-BTHcKWQ5.mjs}

@@ -1,67 +1,24 @@
-import { r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
+import { a as parseEnvInt, r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
 import { r as projectLayout } from "./layout-C0jaaCQC.mjs";
 import { t as HOME_DIR } from "./dotenv-DGyLln7U.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
 import { t as detectHarness } from "./harness-C8Nxxyn_.mjs";
-import { A as evaluateApex, E as detectCreationIntent, L as requiredArchSkill, P as detectModularArchitecture, S as frameworkSolidGate, T as capVerbosity, _ as buildClaudeMdContext, b as skillTriggerGate, c as parseBodyDesc, d as PROJECT_INDICATORS, l as parseField, n as missingSeoElements, o as parseEnrichment, p as buildApexTaskInjection, r as descFromText, s as parseEntry, t as isHtmlLike, u as EXCLUDE_DIRS$1 } from "./validate-B3wkqEoN.mjs";
-import { N as detectFramework, j as countLines, n as FAIL_CLOSED, t as evaluate } from "./evaluate-B1n1ti0N.mjs";
+import { A as evaluateApex, E as detectCreationIntent, L as requiredArchSkill, P as detectModularArchitecture, S as frameworkSolidGate, T as capVerbosity, _ as buildClaudeMdContext, b as skillTriggerGate, c as parseBodyDesc, d as PROJECT_INDICATORS, l as parseField, n as missingSeoElements, o as parseEnrichment, p as buildApexTaskInjection, r as descFromText, s as parseEntry, t as isHtmlLike, u as EXCLUDE_DIRS$1 } from "./validate-xi-zc-22.mjs";
+import { N as detectFramework, j as countLines, n as FAIL_CLOSED, t as evaluate } from "./evaluate-CeivW6G0.mjs";
 import { r as isDocConsulted } from "./doc-helpers-BhzDmJ18.mjs";
 import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
-import { a as nowStamp, l as throttleMs, n as readRoots, o as readState, s as setStateField, t as addRoot } from "./registry-BkoEbdec.mjs";
-import { c as extractText, i as cacheLookupSubstring, l as loadIndex, n as webfetchCacheWrite, r as cacheLookup, t as mcpCacheWrite } from "./mcp-store-CDUVqtJ0.mjs";
-import { a as writeJsonFile, i as readJsonFile, r as hashText, t as atomicWrite } from "./json-io-CvSumjtz.mjs";
+import { a as writeJsonFile, i as readJsonFile, r as hashText, t as atomicWrite } from "./json-io-DisYd2fb.mjs";
+import { a as nowStamp, l as throttleMs, n as readRoots, o as readState, s as setStateField, t as addRoot } from "./registry-CymilZiZ.mjs";
+import { c as extractText, i as cacheLookupSubstring, l as loadIndex, n as webfetchCacheWrite, r as cacheLookup, t as mcpCacheWrite } from "./mcp-store-CnsW9oFj.mjs";
 import { t as loadRefs } from "./loader-Bn-DbZmt.mjs";
-import { c as recordDoc, d as trivialCount, i as agentsFresh, l as recordRefRead, n as saveTrack, o as recordAgent, r as verifyTrack, s as recordBrainstormRequired, t as loadTrack, u as recordTrivialEdit } from "./store-3WBr37Xz.mjs";
-import { c as collectFiles, d as sleep, f as spawnCapture, l as pathExists, n as contextResponse, p as writeText, t as blockResponse, u as readText } from "./claude-BnFrSfMo.mjs";
+import { _ as saveSessionState, c as recordDoc, d as trivialCount, f as claudeHome, g as sanitizeSessionId, h as loadSessionState, i as agentsFresh, l as recordRefRead, m as fusengineCache, n as saveTrack, o as recordAgent, p as fuseHarnessHome, r as verifyTrack, s as recordBrainstormRequired, t as loadTrack, u as recordTrivialEdit, y as sessionsDir } from "./store-CdWOQ9zD.mjs";
+import { c as collectFiles, d as sleep, f as spawnCapture, l as pathExists, n as contextResponse, p as writeText, t as blockResponse, u as readText } from "./claude-CeRYMOaG.mjs";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { createHash } from "node:crypto";
 import { mkdir, rmdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
-//#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/lifecycle/security/skill-state.ts
 /**
 * Shared security-tracker state: per-UTC-day JSON under
@@ -97,390 +54,162 @@ function loadSecurityState(now = Date.now(), home = homedir()) {
 }
 /** 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");
+	atomicWrite(securityStatePath(now, home), JSON.stringify(state, null, 2));
 }
 //#endregion
-//#region src/freshness/explore-tools.ts
-/** Native exploration tools (parity `apex_constants.EXPLORE_TOOLS`). */
-const EXPLORE_TOOLS = /* @__PURE__ */ new Set(["Glob", "Grep"]);
-/** Research tools — MCP docs + web (parity `apex_constants.RESEARCH_TOOLS`). */
-const RESEARCH_TOOLS = /* @__PURE__ */ new Set([
-	"mcp__context7__query-docs",
-	"mcp__context7__resolve-library-id",
-	"mcp__exa__web_search_exa",
-	"mcp__exa__get_code_context_exa",
-	"mcp__exa__deep_researcher_start",
-	"WebSearch",
-	"WebFetch"
-]);
-/** Bash executables that count as exploration (parity `EXPLORE_BASH_CMDS`). */
-const EXPLORE_BASH_CMDS = /* @__PURE__ */ new Set([
-	"grep",
-	"rg",
-	"find",
-	"ls",
-	"fd",
-	"ast-grep",
-	"tree",
-	"cat",
-	"head",
-	"tail"
-]);
-/** Cached MCP result reads count as research (parity `CACHE_READ_RE` + doc-helpers). */
-const CACHE_READ_RE = /\/context\/mcp\/(exa-search|exa-code-context|context7)-/;
-/**
-* First non-assignment shell token's basename, or "" — mirrors Python
-* `_bash_executable` (skips leading `VAR=value` env prefixes, e.g. `FOO=1 grep`).
-* @param cmd - Raw Bash `command` string.
-* @returns The executable basename, or "" when none.
-*/
-function bashExecutable(cmd) {
-	for (const token of cmd.trim().split(/\s+/)) {
-		if (!token) continue;
-		const last = token.split("/").pop() ?? token;
-		if (!last.includes("=")) return last;
-	}
-	return "";
+//#region src/runtime/normalize.ts
+function str(v) {
+	return typeof v === "string" ? v : void 0;
 }
 /**
-* Classify a direct tool use into an APEX phase, or `null` when it is neither
-* exploration nor research. Mirrors Python `track-subagent-research._classify`.
-* @param tool - Harness tool name (e.g. "Glob", "Bash", "WebSearch").
-* @param input - Tool input payload.
-* @returns The credited phase + cache flag, or `null`.
+* 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 classifyExplore(tool, input) {
-	if (RESEARCH_TOOLS.has(tool)) return {
-		phase: "research-expert",
-		cacheHit: false
-	};
-	if (EXPLORE_TOOLS.has(tool)) return {
-		phase: "explore-codebase",
-		cacheHit: false
-	};
-	if (tool === "Read") {
-		const path = String(input?.file_path ?? input?.path ?? "");
-		if (path && CACHE_READ_RE.test(path)) return {
-			phase: "research-expert",
-			cacheHit: true
-		};
-		return null;
-	}
-	if (tool === "Bash") {
-		const cmd = String(input?.command ?? "").trim();
-		if (EXPLORE_BASH_CMDS.has(bashExecutable(cmd))) return {
-			phase: "explore-codebase",
-			cacheHit: false
+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)
 		};
 	}
-	return null;
-}
-//#endregion
-//#region src/runtime/activity.ts
-/** Min response length (chars) for a lead agent call to count as `sufficient`. */
-const AGENT_QUALITY_MIN = 500;
-/** Min response length (chars) for direct exploration/research (parity Python `> 50`). */
-const EXPLORE_QUALITY_MIN = 50;
-/** Read tools across harnesses (Claude `Read`, Gemini/Cline `read_file`, …). */
-const READ_TOOLS = /* @__PURE__ */ new Set([
-	"Read",
-	"read_file",
-	"read_many_files"
-]);
-/** Grade a response length against a threshold; `undefined` when length is unknown. */
-function qualityFor(len, min) {
-	return len === void 0 ? void 0 : len > min ? "sufficient" : "insufficient";
-}
-/** Build an `agent` activity, attaching `quality` only when graded. */
-function agentActivity(name, ts, quality) {
-	return quality ? {
-		kind: "agent",
-		name,
-		ts,
-		quality
-	} : {
-		kind: "agent",
-		name,
-		ts
+	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
 /**
-* The documentation source a tool satisfies for the doc-consultation gate, or
-* undefined. Context7/Exa are the primary sources; fuse-browser is the fallback
-* when Exa is down (`browser_fetch`/`browser_crawl`/`browser_serp_batch`); the
-* built-in WebSearch/WebFetch also count.
-* @param tool - The harness tool name.
+* @module paths
+* Runtime path helpers — per-project, out-of-tree harness state.
+*
+* Default base: ~/.fuse-harness/state/<projectHash>/
+* where projectHash = 8-char MD5 of CLAUDE_PROJECT_DIR (or cwd).
+* Persistent and not world-writable (unlike /tmp), and OUTSIDE the repo so the
+* agent has no "legitimate" reason to write it (the protected-path guard denies
+* it, and the gate verifies freshness from the transcript, not this file).
+*
+* @packageDocumentation
 */
-function docSourceOf$1(tool) {
-	if (/context7/i.test(tool)) return "context7";
-	if (/exa/i.test(tool)) return "exa";
-	if (/browser_(fetch|crawl|serp)/i.test(tool)) return "fuse-browser";
-	if (tool === "WebSearch") return "websearch";
-	if (tool === "WebFetch") return "webfetch";
+/** Resolve the project root from the environment or fall back to cwd. */
+function resolveProjectDir() {
+	return process.env["CLAUDE_PROJECT_DIR"] ?? process.cwd();
 }
 /**
-* 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`/`Agent` + `subagent_type` (Claude/Cursor) → `agent` (bare agent name)
-* - direct exploration/research (Glob/Grep, explore Bash, web, MCP cache reads)
-*   → `agent` credited to the matching REQUIRED_AGENTS phase
-* - a read tool opening a `.md` reference → `ref`
+* Compute a stable 8-char hex hash for a project directory path.
+* Delegates to `hashText` (MD5, non-cryptographic — used as a stable dir key only).
+*
+* @param projectDir - Absolute path to the project root; defaults to CLAUDE_PROJECT_DIR/cwd.
+* @returns 8-char lowercase hex string.
 */
-function activityFor(event) {
-	const out = [];
-	const docSource = docSourceOf$1(event.tool);
-	if (docSource) out.push({
-		kind: "doc",
-		framework: event.framework,
-		sessionId: event.sessionId,
-		source: docSource
-	});
-	if (event.tool === "Task" || event.tool === "Agent") {
-		const name = String(event.input?.subagent_type ?? event.input?.name ?? "").split(":").pop() ?? "";
-		if (name) out.push(agentActivity(name, event.now, qualityFor(event.responseLength, AGENT_QUALITY_MIN)));
-		return out;
-	}
-	const hit = classifyExplore(event.tool, event.input);
-	if (hit) {
-		const quality = hit.cacheHit ? "sufficient" : qualityFor(event.responseLength, EXPLORE_QUALITY_MIN);
-		out.push(agentActivity(hit.phase, event.now, quality));
-	} else if (READ_TOOLS.has(event.tool)) {
-		const path = String(event.input?.file_path ?? event.input?.path ?? "");
-		if (path.endsWith(".md")) out.push({
-			kind: "ref",
-			path
-		});
-	}
-	return out;
-}
-//#endregion
-//#region src/runtime/mcp-key.ts
-/** Cache-key + tool-class helpers for the MCP/WebFetch interception pipeline. */
-/** Default freshness for cached MCP doc results (48h). */
-const MCP_TTL_MS = 1728e5;
-/** WebFetch freshness — pages go stale faster than docs (24h, parity with Python). */
-const WEBFETCH_TTL_MS = 864e5;
-/** WebFetch prompt slice folded into its cache key (parity with Python prompt[:500]). */
-const PROMPT_TRUNC = 500;
-/** True for the WebFetch tool (exact name). */
-function isWebFetch(tool) {
-	return tool === "WebFetch";
-}
-/** MCP doc tools + WebFetch whose calls are cached / verbosity-capped. */
-function isMcpTool(tool) {
-	return /context7|exa|webfetch|web_fetch/i.test(tool) || tool === "WebFetch";
+function projectHash$1(projectDir) {
+	return hashText(projectDir ?? resolveProjectDir());
 }
-/** 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);
+/**
+* Canonical base directory for per-project harness state.
+* Resolves to: ~/.fuse-harness/state/<projectHash>/
+*
+* @param projectDir - Optional override for hashing; defaults to CLAUDE_PROJECT_DIR/cwd.
+* @returns Absolute directory path (not yet created on disk).
+*/
+function defaultStateDir(projectDir) {
+	return join(fuseHarnessHome(), "state", projectHash$1(projectDir));
 }
 /**
-* The string that keys the cache for `tool`. WebFetch folds `url + "\n" +
-* prompt[:500]` (parity with Python) so distinct prompts on the same URL never
-* collide; every other tool keys on {@link queryOf}.
+* Absolute path to a session's track JSON file.
+*
+* The session identifier is sanitised to `[A-Za-z0-9_-]` before use in the filename.
+*
+* @param sessionId - Claude session identifier (raw value accepted; sanitised internally).
+* @param baseDir   - Override the base directory. Omit in production; pass an explicit
+*                    temp path in unit tests to avoid touching $HOME.
+* @returns Absolute path, e.g. ~/.fuse-harness/state/a1b2c3d4/track-abc123.json
 */
-function cacheQueryOf(tool, input) {
-	if (!isWebFetch(tool)) return queryOf(input);
-	return `${typeof input.url === "string" ? input.url.trim() : ""}\n${(typeof input.prompt === "string" ? input.prompt : "").slice(0, PROMPT_TRUNC)}`;
+function trackFile(sessionId, baseDir) {
+	return join(baseDir ?? defaultStateDir(), `track-${sessionId.replace(/[^A-Za-z0-9_-]/g, "_") || "default"}.json`);
 }
 //#endregion
-//#region src/runtime/mcp.ts
-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";
+//#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";
 }
-/**
-* 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 web = isWebFetch(tool);
-	const ttl = web ? WEBFETCH_TTL_MS : ttlMs;
-	const key = cacheQueryOf(tool, input);
-	const cached = cacheLookup(dir, tool, key, ttl, now) ?? (web ? null : cacheLookupSubstring(dir, key, ttl, 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 };
+/** 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 null;
-}
-/**
-* Post-event: persist the MCP/WebFetch response (extracted to markdown). MCP docs
-* go through {@link mcpCacheWrite} (compact + Jaccard-dedup + `index.json`);
-* WebFetch uses {@link webfetchCacheWrite} (compact, exact key, no index).
-* @param now - Current epoch ms (timestamp source; defaults to `Date.now()`).
-*/
-function mcpPostStore(tool, input, response, dir, now = Date.now()) {
-	if (!isMcpTool(tool)) return;
-	const text = extractText(response);
-	const key = cacheQueryOf(tool, input);
-	if (isWebFetch(tool)) webfetchCacheWrite(dir, tool, key, text, now);
-	else mcpCacheWrite(dir, tool, key, text, now);
-}
-//#endregion
-//#region src/runtime/normalize.ts
-function str(v) {
-	return typeof v === "string" ? v : void 0;
+	return next;
 }
-/**
-* 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;
+/** Record a fuse-browser navigate (resets the scroll-before-screenshot guard). */
+function recordNavigate(state) {
 	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)
+		...state,
+		scrolledSinceNav: false
 	};
 }
-//#endregion
-//#region src/runtime/paths.ts
-/**
-* @module paths
-* Runtime path helpers — per-project, out-of-tree harness state.
-*
-* Default base: ~/.claude/fuse-harness/state/<projectHash>/
-* where projectHash = 8-char MD5 of CLAUDE_PROJECT_DIR (or cwd).
-* Persistent and not world-writable (unlike /tmp), and OUTSIDE the repo so the
-* agent has no "legitimate" reason to write it (the protected-path guard denies
-* it, and the gate verifies freshness from the transcript, not this file).
-*
-* @packageDocumentation
-*/
-/** Resolve the project root from the environment or fall back to cwd. */
-function resolveProjectDir() {
-	return process.env["CLAUDE_PROJECT_DIR"] ?? process.cwd();
-}
-/**
-* Compute a stable 8-char hex hash for a project directory path.
-* Delegates to `hashText` (MD5, non-cryptographic — used as a stable dir key only).
-*
-* @param projectDir - Absolute path to the project root; defaults to CLAUDE_PROJECT_DIR/cwd.
-* @returns 8-char lowercase hex string.
-*/
-function projectHash$1(projectDir) {
-	return hashText(projectDir ?? resolveProjectDir());
-}
-/**
-* Canonical base directory for per-project harness state.
-* Resolves to: ~/.claude/fuse-harness/state/<projectHash>/
-*
-* @param projectDir - Optional override for hashing; defaults to CLAUDE_PROJECT_DIR/cwd.
-* @returns Absolute directory path (not yet created on disk).
-*/
-function defaultStateDir(projectDir) {
-	return join(homedir(), ".claude", "fuse-harness", "state", projectHash$1(projectDir));
-}
-/**
-* Absolute path to a session's track JSON file.
-*
-* The session identifier is sanitised to `[A-Za-z0-9_-]` before use in the filename.
-*
-* @param sessionId - Claude session identifier (raw value accepted; sanitised internally).
-* @param baseDir   - Override the base directory. Omit in production; pass an explicit
-*                    temp path in unit tests to avoid touching $HOME.
-* @returns Absolute path, e.g. ~/.claude/fuse-harness/state/a1b2c3d4/track-abc123.json
-*/
-function trackFile(sessionId, baseDir) {
-	return join(baseDir ?? defaultStateDir(), `track-${sessionId.replace(/[^A-Za-z0-9_-]/g, "_") || "default"}.json`);
+/** Record a fuse-browser scroll (satisfies the scroll-before-screenshot guard). */
+function recordScroll(state) {
+	return {
+		...state,
+		scrolledSinceNav: true
+	};
 }
-//#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));
+/** 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"])]
+	};
 }
-//#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.)
+* Record a skill-file Read: reading the identity templates enters phase 1 (browsing
+* allowed); reading the inspiration catalog satisfies the browse prerequisite.
 */
-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 "";
+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/state.ts
@@ -503,8 +232,7 @@ function loadDesignState(cacheDir, agentId) {
 }
 /** 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));
+	atomicWrite(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) {
@@ -543,82 +271,16 @@ function cleanupDesignStates(cacheDir, agentId, stamp, now) {
 	}
 }
 //#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 "";
+//#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). */
@@ -633,402 +295,98 @@ function clearActiveDesignAgent(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/skill-gate.ts
-/** UI source files the gate polices (.html/.css are handled by the pipeline gate, not here). */
-const UI_FILE_RE = /\.(tsx|jsx|scss|vue|svelte)$/;
-/** Generated/vendored paths that never need a design skill (match at start or mid-path). */
-const EXEMPT_RE = /(^|\/)(node_modules|dist|build)\/|\.claude\//;
-/** UI-intent path fragments (ports the Python `UI_PATH_PATTERNS`). */
-const UI_PATH_RE = /(components|ui|styles|page|layout|content|view|feature|section|hero|footer|header|sidebar|nav|modal|dialog)/;
-/** Tailwind utility usage in JSX `className` (ports the Python `has_jsx_tailwind`). */
-const TAILWIND_RE = /className\s*=.*(?:flex|grid|p-|m-|bg-|text-|rounded|shadow|border|gap-|w-|h-)/;
-/** A read reference path that counts as "a design skill was consulted". */
-const DESIGN_SKILL_RE = /skills\/([0-9]-)?(designing-systems|generating-components|solid-react|solid-nextjs|design|impeccable|frontend-design)/i;
-/** True when this Write/Edit targets a UI file in a UI-ish path or with Tailwind classes. */
-function isUiWrite(tool, filePath, content) {
-	if (tool !== "Write" && tool !== "Edit") return false;
-	if (!UI_FILE_RE.test(filePath) || EXEMPT_RE.test(filePath)) return false;
-	return UI_PATH_RE.test(filePath) || TAILWIND_RE.test(content);
-}
-/** True when a design skill reference was read this session (scans the `refsRead` track). */
-function designSkillRead(refsRead) {
-	return refsRead.some((p) => DESIGN_SKILL_RE.test(p));
-}
-const block$1 = (reason, action) => ({
-	kind: "block",
-	title: "Design skill",
-	reason,
-	actions: [action]
-});
+//#region src/runtime/design-lifecycle.ts
 /**
-* Gate a UI write: require a design-skill read AND any doc source. Returns a
-* blocking {@link Prompt}, or `null` to allow. NEVER requires Gemini.
-* @param tool - the tool name ("Write" | "Edit" | ...).
-* @param filePath - the written file path.
-* @param content - the written content (snippet on Edit, full file on Write).
-* @param ev - the session evidence (refsRead + docConsulted).
+* 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 uiDesignSkillGate(tool, filePath, content, ev) {
-	if (!isUiWrite(tool, filePath, content)) return null;
-	if (!designSkillRead(ev.refsRead)) return block$1("BLOCKED: design skill not consulted before writing UI. Read a design SKILL.md (solid-react, generating-components, or designing-systems), then retry.", "Read a design skill reference, then retry");
-	if (!ev.docConsulted) return block$1("BLOCKED: no documentation consulted. Use ANY ONE of mcp__context7__query-docs, mcp__exa__web_search_exa, WebSearch, or WebFetch. Gemini is NOT required.", "Consult Context7, Exa, or web docs (Gemini not required), then retry");
-	return null;
+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/policy/design/skill-evidence.ts
+//#region src/runtime/inject-context.ts
 /**
-* @module design/skill-evidence
-* IO side of the UI design-skill gate: read the verified session track and
-* derive {@link DesignEvidence} (read references + doc-consulted) for
-* {@link uiDesignSkillGate}. Kept separate from the pure gate logic (SRP).
-* @packageDocumentation
+* 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) : "";
+}
 /**
-* Read the verified session track and derive {@link DesignEvidence}. Fail-closed
-* on a missing/corrupt/tampered track (no evidence → the gate blocks).
-* @param sessionId - the Claude session id.
-* @param cwd - the project root (selects the per-project state dir).
-* @param baseDir - override the track base dir (tests); defaults to the project state dir.
+* 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 collectDesignEvidence(sessionId, cwd, baseDir = defaultStateDir(cwd)) {
-	let track = null;
+function taskContext(cwd) {
+	const ctx = buildApexTaskInjection(process.env.CLAUDE_PROJECT_DIR ?? cwd);
+	return ctx ? contextResponse("PreToolUse", ctx) : "";
+}
+//#endregion
+//#region src/runtime/dev-context.ts
+/** Run a git subcommand in `cwd`, returning trimmed stdout or "" on error. */
+function git(cwd, args) {
 	try {
-		track = verifyTrack(JSON.parse(readFileSync(trackFile(sessionId, baseDir), "utf8")));
+		return execFileSync("git", args, {
+			cwd,
+			encoding: "utf-8",
+			stdio: "pipe",
+			timeout: 5e3
+		}).trim();
 	} catch {
-		track = null;
+		return "";
 	}
-	return {
-		refsRead: track?.refsRead ?? [],
-		docConsulted: track ? isDocConsulted(track.authorizations, sessionId) : false
-	};
 }
-//#endregion
-//#region src/runtime/design-helpers.ts
+/** 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;
+}
 /**
-* @module design-helpers
-* Effectful helpers for the design pipeline gate: locate design-system.md and
-* apply PostToolUse fuse-browser transitions to the design state. Split out of
-* `design.ts` to keep that file within the SOLID size budget (SRP).
-* @packageDocumentation
+* 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).
 */
-const NAV$1 = "mcp__fuse-browser__browser_navigate";
-const SHOT$1 = "mcp__fuse-browser__browser_screenshot";
-const SCROLL = "mcp__fuse-browser__browser_scroll";
-const GEMINI$1 = "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$1) saveDesignState(cacheDir, recordScreenshot(state, MIN_SCREENSHOTS[state.mode]));
-	else if (event.tool === NAV$1) saveDesignState(cacheDir, recordNavigate(state));
-	else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
-	else if (event.tool === GEMINI$1) 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));
-}
-//#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 GEMINI = "mcp__gemini-design__create_frontend";
-/**
-* 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) {
-	if (event.phase !== "post" && (event.tool === "Write" || event.tool === "Edit")) {
-		const skillBlock = uiDesignSkillGate(event.tool, event.filePath ?? "", event.content ?? "", collectDesignEvidence(event.sessionId, cwd));
-		if (skillBlock) return skillBlock;
-	}
-	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;
-	let state = loadDesignState(cacheDir, id);
-	if (!state) {
-		if (!active) return null;
-		const dsExists = findDesignSystem(cwd) !== "";
-		state = initDesignState(id, dsExists ? "page" : "full", dsExists);
-		saveDesignState(cacheDir, state);
-	}
-	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/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");
+function devContext(cwd) {
+	return [...gitContext(cwd), ...projectContext(cwd)].join("\n");
 }
 //#endregion
 //#region src/runtime/fs-cleanup.ts
@@ -1102,7 +460,7 @@ function pruneEmpty(dir, stopAt) {
 }
 //#endregion
 //#region src/runtime/lifecycle/session-start.ts
-/** TTLs (seconds) for purgeable fusengine-cache subtrees (cleanup-old-caches.py). */
+/** TTLs (seconds) for purgeable cache subtrees (cleanup-old-caches.py). */
 const PURGEABLE = {
 	sessions: 48 * 3600,
 	webfetch: 24 * 3600,
@@ -1456,7 +814,7 @@ function saveApexState(cwd, now = Date.now()) {
 /**
 * 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.
+* `cache`. Ports `session-end/cleanup-session.py`. No stdout.
 * @param home - Home dir (defaults to `~`).
 * @param now - Clock (defaults to `Date.now()`).
 */
@@ -2348,7 +1706,7 @@ ${agents}
 /**
 * 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
+* under the same `~/.fuse-harness/cache` tree as the core MCP cache — no
 * second cache layer.
 */
 /** 16-char hex SHA-256 of `text` (project hash / doc topic key). */
@@ -2359,11 +1717,11 @@ function hashText16(text) {
 function projectHash(projectPath) {
 	return hashText16(projectPath);
 }
-/** `~/.claude/fusengine-cache` base dir (shared with the core MCP cache). */
+/** `~/.fuse-harness/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>`. */
+/** Per-type, per-project cache dir: `cache/<type>/<projectHash>`. */
 function cacheDirFor(type, projectPath, home = homedir()) {
 	return join(cacheBaseDir(home), type, projectHash(projectPath));
 }
@@ -2985,7 +2343,7 @@ async function cacheDocFromTranscript(transcript, cwd, home = homedir()) {
 //#region src/runtime/lifecycle/aipilot/promote-global-lessons.ts
 /**
 * Promote high-frequency project lessons (occurrence count >= 3) to the global,
-* stack-scoped cache (`fusengine-cache/lessons/_global/<stack>.json`, cap 25).
+* stack-scoped cache (`cache/lessons/_global/<stack>.json`, cap 25).
 * Ports the ai-pilot `promote-global-lessons.ts` (a spawned subprocess) as an
 * in-process call from `cacheSniperLessons`. Pure side-effect.
 */
@@ -3726,7 +3084,7 @@ function appendMemoryLog(name, line, rotateAt = 0, keep = 0, home = homedir()) {
 		appendFileSync(file, `${line}\n`, "utf-8");
 		if (rotateAt > 0) {
 			const lines = readFileSync(file, "utf-8").split("\n").filter((l) => l.length > 0);
-			if (lines.length > rotateAt) writeFileSync(file, `${lines.slice(-keep).join("\n")}\n`, "utf-8");
+			if (lines.length > rotateAt) atomicWrite(file, `${lines.slice(-keep).join("\n")}\n`);
 		}
 	} catch {}
 }
@@ -3968,7 +3326,8 @@ const EXEMPT_PATTERNS = [
 	/\.claude-plugin\//,
 	/CHANGELOG\.md$/,
 	/marketplace\.json$/,
-	/\/\.claude\/(apex|memory|logs|fusengine-cache)\//
+	/\/\.claude\/(apex|memory|logs)\//,
+	/\/\.fuse-harness\//
 ];
 /**
 * True when `filePath` is a code file the APEX freshness/doc/SOLID gates should
@@ -3999,72 +3358,6 @@ function existingLineCount(path) {
 	}
 }
 //#endregion
-//#region src/freshness/agent-evidence.ts
-/**
-* Platform-authored transcript evidence for APEX agent freshness.
-* Parses the Claude Code session JSONL transcript to find genuine `Task`/`Agent`
-* tool_use entries — forging this requires writing into the transcript file
-* which the Claude Code platform controls, unlike the self-recorded track.
-*/
-/** Parse a raw `timestamp` field to epoch ms; `undefined` when absent or invalid. */
-function parseTs(raw) {
-	if (raw === void 0) return void 0;
-	if (typeof raw === "number") return raw;
-	const ms = Date.parse(raw);
-	return Number.isFinite(ms) ? ms : void 0;
-}
-/**
-* Return `true` ONLY when, for EVERY name in `names`, the Claude Code
-* transcript at `transcriptPath` contains a genuine `tool_use` of the `Task` or
-* `Agent` tool whose `subagent_type` (or `name`) input field matches — after
-* stripping any plugin prefix — with the entry timestamp within `windowMs` of `now`.
-*
-* **Timestamp note:** when a transcript entry carries no `timestamp` field it
-* is counted as within-window (we cannot prove staleness). This is
-* intentionally lenient to stay robust across transcript-format evolution; the
-* tamper-resistance guarantee derives from the platform authoring the file —
-* not from the timestamp alone.
-*
-* @param transcriptPath - Absolute path to the session `.jsonl` transcript
-*   (hook payload field: `transcript_path`). Returns `false` when `undefined`.
-* @param names - Required agent `subagent_type` values — ALL must appear.
-* @param windowMs - Freshness window in milliseconds.
-* @param now - Current epoch ms (pass `Date.now()` at the call-site).
-* @returns `true` when ALL agents have real, within-window transcript evidence.
-*/
-function agentsRanFromTranscript(transcriptPath, names, windowMs, now) {
-	if (!transcriptPath || names.length === 0) return false;
-	let text;
-	try {
-		text = readText(transcriptPath);
-	} catch {
-		return false;
-	}
-	const cutoff = now - windowMs;
-	const found = /* @__PURE__ */ new Set();
-	for (const line of text.split("\n")) {
-		if (!line.trim()) continue;
-		let entry;
-		try {
-			entry = JSON.parse(line);
-		} catch {
-			continue;
-		}
-		const ts = parseTs(entry.timestamp);
-		if (ts !== void 0 && ts <= cutoff) continue;
-		const content = entry.message?.content;
-		if (!Array.isArray(content)) continue;
-		for (const block of content) {
-			if (block?.type !== "tool_use" || block.name !== "Task" && block.name !== "Agent") continue;
-			const raw = block.input?.subagent_type ?? block.input?.name;
-			const agent = typeof raw === "string" ? raw.split(":").pop() ?? raw : void 0;
-			if (agent !== void 0 && names.includes(agent)) found.add(agent);
-		}
-		if (found.size === names.length) return true;
-	}
-	return names.every((n) => found.has(n));
-}
-//#endregion
 //#region src/runtime/dry-patterns.ts
 /** Short identifiers never worth a duplication check (control flow, tiny names). */
 const DRY_KEYWORDS = /* @__PURE__ */ new Set([
@@ -4306,7 +3599,7 @@ const PHP_BLOCKED_IN_APP = [
 	"/app/Notifications/",
 	"/app/Policies/"
 ];
-const block = (reason) => ({
+const block$1 = (reason) => ({
 	kind: "block",
 	title: "Modular architecture",
 	reason,
@@ -4316,30 +3609,30 @@ const block = (reason) => ({
 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]/.`);
+	if ((rel.startsWith("app/") || rel.startsWith("src/app/")) && !NEXT_CONVENTION.test(bn) && !NEXT_STATIC.test(bn)) return block$1(`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.`);
+			if (imported !== "cores" && imported !== "core") return block$1(`BLOCKED: modules/cores/ must not import from modules/${imported}/.`);
+		} else if (imported !== current && imported !== "cores" && imported !== "core") return block$1(`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/.`);
+	for (const b of PHP_BLOCKED_IN_APP) if (filePath.includes(b)) return block$1(`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.`);
+	if (!existsSync(join(cwd, "FuseCore", name, "module.json"))) return block$1(`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.`);
+			if (imported !== "Core") return block$1(`BLOCKED: FuseCore\\Core\\ must not use FuseCore\\${imported}\\.`);
+		} else if (imported !== name && imported !== "Core") return block$1(`BLOCKED: cross-module use — '${name}' uses '${imported}'. Only FuseCore\\Core\\ is shared.`);
 	}
 	return null;
 }
@@ -4392,6 +3685,110 @@ function frameworkSkillGate(input, refsRead, existingLines) {
 	return skillTriggerGate(input.framework, content, refsRead, forced, input.cwd);
 }
 //#endregion
+//#region src/freshness/agent-evidence.ts
+/**
+* Platform-authored transcript evidence for APEX agent freshness.
+* Parses the Claude Code session JSONL transcript to find genuine `Task`/`Agent`
+* tool_use entries — forging this requires writing into the transcript file
+* which the Claude Code platform controls, unlike the self-recorded track.
+*/
+/** Parse a raw `timestamp` field to epoch ms; `undefined` when absent or invalid. */
+function parseTs(raw) {
+	if (raw === void 0) return void 0;
+	if (typeof raw === "number") return raw;
+	const ms = Date.parse(raw);
+	return Number.isFinite(ms) ? ms : void 0;
+}
+/**
+* Return `true` ONLY when, for EVERY name in `names`, the Claude Code
+* transcript at `transcriptPath` contains a genuine `tool_use` of the `Task` or
+* `Agent` tool whose `subagent_type` (or `name`) input field matches — after
+* stripping any plugin prefix — with the entry timestamp within `windowMs` of `now`.
+*
+* **Timestamp note:** when a transcript entry carries no `timestamp` field it
+* is counted as within-window (we cannot prove staleness). This is
+* intentionally lenient to stay robust across transcript-format evolution; the
+* tamper-resistance guarantee derives from the platform authoring the file —
+* not from the timestamp alone.
+*
+* @param transcriptPath - Absolute path to the session `.jsonl` transcript
+*   (hook payload field: `transcript_path`). Returns `false` when `undefined`.
+* @param names - Required agent `subagent_type` values — ALL must appear.
+* @param windowMs - Freshness window in milliseconds.
+* @param now - Current epoch ms (pass `Date.now()` at the call-site).
+* @returns `true` when ALL agents have real, within-window transcript evidence.
+*/
+function agentsRanFromTranscript(transcriptPath, names, windowMs, now) {
+	if (!transcriptPath || names.length === 0) return false;
+	let text;
+	try {
+		text = readText(transcriptPath);
+	} catch {
+		return false;
+	}
+	const cutoff = now - windowMs;
+	const found = /* @__PURE__ */ new Set();
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		let entry;
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		const ts = parseTs(entry.timestamp);
+		if (ts !== void 0 && ts <= cutoff) continue;
+		const content = entry.message?.content;
+		if (!Array.isArray(content)) continue;
+		for (const block of content) {
+			if (block?.type !== "tool_use" || block.name !== "Task" && block.name !== "Agent") continue;
+			const raw = block.input?.subagent_type ?? block.input?.name;
+			const agent = typeof raw === "string" ? raw.split(":").pop() ?? raw : void 0;
+			if (agent !== void 0 && names.includes(agent)) found.add(agent);
+		}
+		if (found.size === names.length) return true;
+	}
+	return names.every((n) => found.has(n));
+}
+//#endregion
+//#region src/runtime/gate-apex.ts
+/**
+* The APEX-scoped portion of {@link gate}: a trivial-edit fast path, then the
+* freshness/doc/SOLID gates fed from the session track. Freshness prefers
+* platform-authored transcript evidence (an agent cannot forge a `Task` in the
+* runtime-owned transcript); the self-recorded track is only a fallback when no
+* transcript path is available (tests / other harnesses).
+* @param input - The tool-use to gate.
+* @param track - The loaded session track.
+* @param window - Freshness window in ms.
+* @returns The first blocking prompt, or null to fall through to the DRY check.
+*/
+async function apexScopedGate(input, track, window) {
+	const lineCount = input.content === void 0 ? Number.POSITIVE_INFINITY : input.content.split("\n").length;
+	if (!input.isReplaceAll && lineCount < 5 && trivialCount(track, window, input.now) < 4) {
+		await saveTrack(input.trackFile, recordTrivialEdit(track, input.now, window, input.now));
+		return null;
+	}
+	const freshnessFor = (names, windowMs = window) => input.transcriptPath ? agentsRanFromTranscript(input.transcriptPath, names, windowMs, input.now) : agentsFresh(track, names, windowMs, input.now);
+	const ctx = {
+		sessionId: input.sessionId,
+		framework: input.framework,
+		filePath: input.filePath ?? "",
+		content: input.content ?? "",
+		authorizations: track.authorizations,
+		refs: input.refs,
+		refsRead: track.refsRead,
+		agentsFresh: freshnessFor([...REQUIRED_AGENTS]),
+		brainstormRequired: track.brainstormRequired,
+		brainstormFresh: freshnessFor(["brainstorming"], Number.MAX_SAFE_INTEGER)
+	};
+	try {
+		return evaluateApex(ctx);
+	} catch {
+		return FAIL_CLOSED;
+	}
+}
+//#endregion
 //#region src/runtime/gate.ts
 /** Prior agents the freshness gate requires before a code edit. */
 const REQUIRED_AGENTS = ["explore-codebase", "research-expert"];
@@ -4421,41 +3818,465 @@ async function gate(input) {
 	} catch {
 		return FAIL_CLOSED;
 	}
-	if (quick.decision !== "allow" && quick.prompt) return quick.prompt;
-	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;
-	if (isApexScoped(input.filePath)) {
-		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;
+	if (quick.decision !== "allow" && quick.prompt) return quick.prompt;
+	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;
+	if (isApexScoped(input.filePath)) {
+		const apex = await apexScopedGate(input, track, window);
+		if (apex) return apex;
+	}
+	return dryGate(input.tool, input.filePath, input.content, input.cwd);
+}
+//#endregion
+//#region src/runtime/mcp-key.ts
+/** Cache-key + tool-class helpers for the MCP/WebFetch interception pipeline. */
+/** Default cached-MCP freshness in seconds (48h). */
+const MCP_TTL_DEFAULT_SEC = 172800;
+/** Default WebFetch freshness in seconds (24h, parity with Python). */
+const WEBFETCH_TTL_DEFAULT_SEC = 86400;
+/** Cached-MCP freshness (ms) from `FUSE_MCP_TTL_SEC` (default 48h). */
+const MCP_TTL_MS = parseEnvInt(process.env.FUSE_MCP_TTL_SEC, MCP_TTL_DEFAULT_SEC) * 1e3;
+/** WebFetch freshness (ms) from `FUSE_WEBFETCH_TTL_SEC` (default 24h; pages stale faster than docs). */
+const WEBFETCH_TTL_MS = parseEnvInt(process.env.FUSE_WEBFETCH_TTL_SEC, WEBFETCH_TTL_DEFAULT_SEC) * 1e3;
+/** WebFetch prompt slice folded into its cache key (parity with Python prompt[:500]). */
+const PROMPT_TRUNC = 500;
+/** True for the WebFetch tool (exact name). */
+function isWebFetch(tool) {
+	return tool === "WebFetch";
+}
+/** 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);
+}
+/**
+* The string that keys the cache for `tool`. WebFetch folds `url + "\n" +
+* prompt[:500]` (parity with Python) so distinct prompts on the same URL never
+* collide; every other tool keys on {@link queryOf}.
+*/
+function cacheQueryOf(tool, input) {
+	if (!isWebFetch(tool)) return queryOf(input);
+	return `${typeof input.url === "string" ? input.url.trim() : ""}\n${(typeof input.prompt === "string" ? input.prompt : "").slice(0, PROMPT_TRUNC)}`;
+}
+//#endregion
+//#region src/runtime/mcp.ts
+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$1(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 web = isWebFetch(tool);
+	const ttl = web ? WEBFETCH_TTL_MS : ttlMs;
+	const key = cacheQueryOf(tool, input);
+	const cached = cacheLookup(dir, tool, key, ttl, now) ?? (web ? null : cacheLookupSubstring(dir, key, ttl, now));
+	if (cached) {
+		const served = denyWith(id, cached);
+		if (served) return {
+			stdout: served,
+			docSource: docSourceOf$1(tool)
+		};
+	}
+	const capped = capVerbosity(tool, input);
+	if (capped) {
+		const mutated = mutateWith(id, capped);
+		if (mutated) return { stdout: mutated };
+	}
+	return null;
+}
+/**
+* Post-event: persist the MCP/WebFetch response (extracted to markdown). MCP docs
+* go through {@link mcpCacheWrite} (compact + Jaccard-dedup + `index.json`);
+* WebFetch uses {@link webfetchCacheWrite} (compact, exact key, no index).
+* @param now - Current epoch ms (timestamp source; defaults to `Date.now()`).
+*/
+function mcpPostStore(tool, input, response, dir, now = Date.now()) {
+	if (!isMcpTool(tool)) return;
+	const text = extractText(response);
+	const key = cacheQueryOf(tool, input);
+	if (isWebFetch(tool)) webfetchCacheWrite(dir, tool, key, text, now);
+	else mcpCacheWrite(dir, tool, key, text, now);
+}
+//#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/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/skill-gate.ts
+/** UI source files the gate polices (.html/.css are handled by the pipeline gate, not here). */
+const UI_FILE_RE = /\.(tsx|jsx|scss|vue|svelte)$/;
+/** Generated/vendored paths that never need a design skill (match at start or mid-path). */
+const EXEMPT_RE = /(^|\/)(node_modules|dist|build)\/|\.claude\//;
+/** UI-intent path fragments (ports the Python `UI_PATH_PATTERNS`). */
+const UI_PATH_RE = /(components|ui|styles|page|layout|content|view|feature|section|hero|footer|header|sidebar|nav|modal|dialog)/;
+/** Tailwind utility usage in JSX `className` (ports the Python `has_jsx_tailwind`). */
+const TAILWIND_RE = /className\s*=.*(?:flex|grid|p-|m-|bg-|text-|rounded|shadow|border|gap-|w-|h-)/;
+/** A read reference path that counts as "a design skill was consulted". */
+const DESIGN_SKILL_RE = /skills\/([0-9]-)?(designing-systems|generating-components|solid-react|solid-nextjs|design|impeccable|frontend-design)/i;
+/** True when this Write/Edit targets a UI file in a UI-ish path or with Tailwind classes. */
+function isUiWrite(tool, filePath, content) {
+	if (tool !== "Write" && tool !== "Edit") return false;
+	if (!UI_FILE_RE.test(filePath) || EXEMPT_RE.test(filePath)) return false;
+	return UI_PATH_RE.test(filePath) || TAILWIND_RE.test(content);
+}
+/** True when a design skill reference was read this session (scans the `refsRead` track). */
+function designSkillRead(refsRead) {
+	return refsRead.some((p) => DESIGN_SKILL_RE.test(p));
+}
+const block = (reason, action) => ({
+	kind: "block",
+	title: "Design skill",
+	reason,
+	actions: [action]
+});
+/**
+* Gate a UI write: require a design-skill read AND any doc source. Returns a
+* blocking {@link Prompt}, or `null` to allow. NEVER requires Gemini.
+* @param tool - the tool name ("Write" | "Edit" | ...).
+* @param filePath - the written file path.
+* @param content - the written content (snippet on Edit, full file on Write).
+* @param ev - the session evidence (refsRead + docConsulted).
+*/
+function uiDesignSkillGate(tool, filePath, content, ev) {
+	if (!isUiWrite(tool, filePath, content)) return null;
+	if (!designSkillRead(ev.refsRead)) return block("BLOCKED: design skill not consulted before writing UI. Read a design SKILL.md (solid-react, generating-components, or designing-systems), then retry.", "Read a design skill reference, then retry");
+	if (!ev.docConsulted) return block("BLOCKED: no documentation consulted. Use ANY ONE of mcp__context7__query-docs, mcp__exa__web_search_exa, WebSearch, or WebFetch. Gemini is NOT required.", "Consult Context7, Exa, or web docs (Gemini not required), then retry");
+	return null;
+}
+//#endregion
+//#region src/policy/design/skill-evidence.ts
+/**
+* @module design/skill-evidence
+* IO side of the UI design-skill gate: read the verified session track and
+* derive {@link DesignEvidence} (read references + doc-consulted) for
+* {@link uiDesignSkillGate}. Kept separate from the pure gate logic (SRP).
+* @packageDocumentation
+*/
+/**
+* Read the verified session track and derive {@link DesignEvidence}. Fail-closed
+* on a missing/corrupt/tampered track (no evidence → the gate blocks).
+* @param sessionId - the Claude session id.
+* @param cwd - the project root (selects the per-project state dir).
+* @param baseDir - override the track base dir (tests); defaults to the project state dir.
+*/
+function collectDesignEvidence(sessionId, cwd, baseDir = defaultStateDir(cwd)) {
+	let track = null;
+	try {
+		track = verifyTrack(JSON.parse(readFileSync(trackFile(sessionId, baseDir), "utf8")));
+	} catch {
+		track = null;
+	}
+	return {
+		refsRead: track?.refsRead ?? [],
+		docConsulted: track ? isDocConsulted(track.authorizations, sessionId) : false
+	};
+}
+//#endregion
+//#region src/runtime/design-helpers.ts
+/**
+* @module design-helpers
+* Effectful helpers for the design pipeline gate: locate design-system.md and
+* apply PostToolUse fuse-browser transitions to the design state. Split out of
+* `design.ts` to keep that file within the SOLID size budget (SRP).
+* @packageDocumentation
+*/
+const NAV$1 = "mcp__fuse-browser__browser_navigate";
+const SHOT$1 = "mcp__fuse-browser__browser_screenshot";
+const SCROLL = "mcp__fuse-browser__browser_scroll";
+const GEMINI$1 = "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$1) saveDesignState(cacheDir, recordScreenshot(state, MIN_SCREENSHOTS[state.mode]));
+	else if (event.tool === NAV$1) saveDesignState(cacheDir, recordNavigate(state));
+	else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
+	else if (event.tool === GEMINI$1) 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));
+}
+//#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 GEMINI = "mcp__gemini-design__create_frontend";
+/**
+* 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) {
+	if (event.phase !== "post" && (event.tool === "Write" || event.tool === "Edit")) {
+		const skillBlock = uiDesignSkillGate(event.tool, event.filePath ?? "", event.content ?? "", collectDesignEvidence(event.sessionId, cwd));
+		if (skillBlock) return skillBlock;
+	}
+	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;
+	let state = loadDesignState(cacheDir, id);
+	if (!state) {
+		if (!active) return null;
+		const dsExists = findDesignSystem(cwd) !== "";
+		state = initDesignState(id, dsExists ? "page" : "full", dsExists);
+		saveDesignState(cacheDir, state);
+	}
+	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: []
+			};
 		}
-		const freshnessFor = (names, windowMs = window) => input.transcriptPath ? agentsRanFromTranscript(input.transcriptPath, names, windowMs, input.now) : agentsFresh(track, names, windowMs, input.now);
-		const ctx = {
-			sessionId: input.sessionId,
-			framework: input.framework,
-			filePath: input.filePath,
-			content: input.content ?? "",
-			authorizations: track.authorizations,
-			refs: input.refs,
-			refsRead: track.refsRead,
-			agentsFresh: freshnessFor([...REQUIRED_AGENTS]),
-			brainstormRequired: track.brainstormRequired,
-			brainstormFresh: freshnessFor(["brainstorming"], Number.MAX_SAFE_INTEGER)
+		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"]
 		};
-		try {
-			const apex = evaluateApex(ctx);
-			if (apex) return apex;
-		} catch {
-			return FAIL_CLOSED;
-		}
+		return null;
 	}
-	return dryGate(input.tool, input.filePath, input.content, input.cwd);
+	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/handle-pre.ts
@@ -4522,6 +4343,203 @@ async function handlePre(ctx) {
 	};
 }
 //#endregion
+//#region src/freshness/explore-tools.ts
+/** Native exploration tools (parity `apex_constants.EXPLORE_TOOLS`). */
+const EXPLORE_TOOLS = /* @__PURE__ */ new Set(["Glob", "Grep"]);
+/** Research tools — MCP docs + web (parity `apex_constants.RESEARCH_TOOLS`). */
+const RESEARCH_TOOLS = /* @__PURE__ */ new Set([
+	"mcp__context7__query-docs",
+	"mcp__context7__resolve-library-id",
+	"mcp__exa__web_search_exa",
+	"mcp__exa__get_code_context_exa",
+	"mcp__exa__deep_researcher_start",
+	"WebSearch",
+	"WebFetch"
+]);
+/** Bash executables that count as exploration (parity `EXPLORE_BASH_CMDS`). */
+const EXPLORE_BASH_CMDS = /* @__PURE__ */ new Set([
+	"grep",
+	"rg",
+	"find",
+	"ls",
+	"fd",
+	"ast-grep",
+	"tree",
+	"cat",
+	"head",
+	"tail"
+]);
+/** Cached MCP result reads count as research (parity `CACHE_READ_RE` + doc-helpers). */
+const CACHE_READ_RE = /\/context\/mcp\/(exa-search|exa-code-context|context7)-/;
+/**
+* First non-assignment shell token's basename, or "" — mirrors Python
+* `_bash_executable` (skips leading `VAR=value` env prefixes, e.g. `FOO=1 grep`).
+* @param cmd - Raw Bash `command` string.
+* @returns The executable basename, or "" when none.
+*/
+function bashExecutable(cmd) {
+	for (const token of cmd.trim().split(/\s+/)) {
+		if (!token) continue;
+		const last = token.split("/").pop() ?? token;
+		if (!last.includes("=")) return last;
+	}
+	return "";
+}
+/**
+* Classify a direct tool use into an APEX phase, or `null` when it is neither
+* exploration nor research. Mirrors Python `track-subagent-research._classify`.
+* @param tool - Harness tool name (e.g. "Glob", "Bash", "WebSearch").
+* @param input - Tool input payload.
+* @returns The credited phase + cache flag, or `null`.
+*/
+function classifyExplore(tool, input) {
+	if (RESEARCH_TOOLS.has(tool)) return {
+		phase: "research-expert",
+		cacheHit: false
+	};
+	if (EXPLORE_TOOLS.has(tool)) return {
+		phase: "explore-codebase",
+		cacheHit: false
+	};
+	if (tool === "Read") {
+		const path = String(input?.file_path ?? input?.path ?? "");
+		if (path && CACHE_READ_RE.test(path)) return {
+			phase: "research-expert",
+			cacheHit: true
+		};
+		return null;
+	}
+	if (tool === "Bash") {
+		const cmd = String(input?.command ?? "").trim();
+		if (EXPLORE_BASH_CMDS.has(bashExecutable(cmd))) return {
+			phase: "explore-codebase",
+			cacheHit: false
+		};
+	}
+	return null;
+}
+//#endregion
+//#region src/runtime/activity.ts
+/** Min response length (chars) for a lead agent call to count as `sufficient`. */
+const AGENT_QUALITY_MIN = 500;
+/** Min response length (chars) for direct exploration/research (parity Python `> 50`). */
+const EXPLORE_QUALITY_MIN = 50;
+/** Read tools across harnesses (Claude `Read`, Gemini/Cline `read_file`, …). */
+const READ_TOOLS = /* @__PURE__ */ new Set([
+	"Read",
+	"read_file",
+	"read_many_files"
+]);
+/** Grade a response length against a threshold; `undefined` when length is unknown. */
+function qualityFor(len, min) {
+	return len === void 0 ? void 0 : len > min ? "sufficient" : "insufficient";
+}
+/** Build an `agent` activity, attaching `quality` only when graded. */
+function agentActivity(name, ts, quality) {
+	return quality ? {
+		kind: "agent",
+		name,
+		ts,
+		quality
+	} : {
+		kind: "agent",
+		name,
+		ts
+	};
+}
+/**
+* The documentation source a tool satisfies for the doc-consultation gate, or
+* undefined. Context7/Exa are the primary sources; fuse-browser is the fallback
+* when Exa is down (`browser_fetch`/`browser_crawl`/`browser_serp_batch`); the
+* built-in WebSearch/WebFetch also count.
+* @param tool - The harness tool name.
+*/
+function docSourceOf(tool) {
+	if (/context7/i.test(tool)) return "context7";
+	if (/exa/i.test(tool)) return "exa";
+	if (/browser_(fetch|crawl|serp)/i.test(tool)) return "fuse-browser";
+	if (tool === "WebSearch") return "websearch";
+	if (tool === "WebFetch") return "webfetch";
+}
+/**
+* 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`/`Agent` + `subagent_type` (Claude/Cursor) → `agent` (bare agent name)
+* - direct exploration/research (Glob/Grep, explore Bash, web, MCP cache reads)
+*   → `agent` credited to the matching REQUIRED_AGENTS phase
+* - a read tool opening a `.md` reference → `ref`
+*/
+function activityFor(event) {
+	const out = [];
+	const docSource = docSourceOf(event.tool);
+	if (docSource) out.push({
+		kind: "doc",
+		framework: event.framework,
+		sessionId: event.sessionId,
+		source: docSource
+	});
+	if (event.tool === "Task" || event.tool === "Agent") {
+		const name = String(event.input?.subagent_type ?? event.input?.name ?? "").split(":").pop() ?? "";
+		if (name) out.push(agentActivity(name, event.now, qualityFor(event.responseLength, AGENT_QUALITY_MIN)));
+		return out;
+	}
+	const hit = classifyExplore(event.tool, event.input);
+	if (hit) {
+		const quality = hit.cacheHit ? "sufficient" : qualityFor(event.responseLength, EXPLORE_QUALITY_MIN);
+		out.push(agentActivity(hit.phase, event.now, quality));
+	} else if (READ_TOOLS.has(event.tool)) {
+		const path = String(event.input?.file_path ?? event.input?.path ?? "");
+		if (path.endsWith(".md")) out.push({
+			kind: "ref",
+			path
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/runtime/handle-post.ts
+/**
+* Run the PostToolUse pipeline: store the MCP response, emit a design warning,
+* record the activity into the session track, apply per-scope side-effects (SEO
+* deny, aipilot task cache), then inject the post-edit context.
+* @param ctx - The resolved context (same shape as the pre pipeline).
+* @returns The native hook outcome.
+*/
+async function handlePost(ctx) {
+	const { id, payload, event, framework, mcpDir, file, opts } = ctx;
+	const response = payload.tool_response ?? payload.tool_output;
+	mcpPostStore(event.tool, event.input, response, mcpDir);
+	const designWarn = designGate(payload, event, mcpDir, opts.cwd);
+	const activities = activityFor({
+		tool: event.tool,
+		input: event.input,
+		sessionId: event.sessionId,
+		framework,
+		now: opts.now,
+		responseLength: extractText(response).length
+	});
+	for (const activity of activities) await recordActivity(file, activity);
+	postTrackingSideEffects(opts.scope ?? "core", event, event.input, opts.now, payload, opts.cwd);
+	const seoDeny = opts.scope === "seo" ? seoPostToolUseResponse(payload) : null;
+	if (seoDeny) return {
+		stdout: seoDeny,
+		exit: 0
+	};
+	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
+	};
+}
+//#endregion
 //#region src/runtime/handle-scope-async.ts
 /**
 * Pre-pipeline async scope interception for {@link handleHook}. The aipilot and
@@ -4582,38 +4600,15 @@ async function handleHook(id, payload, opts) {
 			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 activities = activityFor({
-			tool: event.tool,
-			input: event.input,
-			sessionId: event.sessionId,
-			framework,
-			now: opts.now,
-			responseLength: extractText(response).length
-		});
-		for (const activity of activities) await recordActivity(file, activity);
-		postTrackingSideEffects(opts.scope ?? "core", event, event.input, opts.now, payload, opts.cwd);
-		const seoDeny = opts.scope === "seo" ? seoPostToolUseResponse(payload) : null;
-		if (seoDeny) return {
-			stdout: seoDeny,
-			exit: 0
-		};
-		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
-		};
-	}
+	if (event.phase === "post") return handlePost({
+		id,
+		payload,
+		event,
+		framework,
+		mcpDir,
+		file,
+		opts
+	});
 	return handlePre({
 		id,
 		payload,
@@ -4625,4 +4620,4 @@ async function handleHook(id, payload, opts) {
 	});
 }
 //#endregion
-export { sessionStartCore as $, writePluginMap as A, fusengineCache as At, trackSessionChanges as B, aipilotPostToolUse as C, isoUtc as Ct, lessonsStateFileFor as D, securityStatePath as Dt, lessonsFileFor as E, securityStateDir as Et, mergeLines as F, sessionsDir as Ft, validateTeammateOutput as G, cleanupSession as H, countFiles as I, detectSolidProfile as J, trackAgentMemory as K, getFileDesc as L, isProject as M, sanitizeSessionId as Mt, writeTree as N, saveSessionState as Nt, cartoSessionStart as O, todayUtc as Ot, loadEnriched as P, sessionStatePath as Pt, runSessionStartCleanups as Q, listChildren as R, dispatchLifecycle as S, activityFor as St, dispatchLessons as T, saveSecurityState as Tt, saveApexState as U, validateRulesLoaded as V, logToolFailure as W, injectRules as X, solidDetectStart as Y, readRules as Z, postTrackingSideEffects as _, MCP_TTL_MS as _t, TRIVIAL_BUDGET as a, gitContext as at, trackSkillRead as b, isMcpTool as bt, detectDuplication as c, taskContext as ct, lifecycleStdout as d, defaultStateDir as dt, pruneEmptyDirs as et, postEditContext as f, projectHash$1 as ft, securityAdvisory as g, mcpPreIntercept as gt, dispatchMemory as h, mcpPostStore as ht, REQUIRED_AGENTS as i, devContext as it, generateProjectMap as j, loadSessionState as jt, generateEcosystemMap as k, claudeHome as kt, dryGate as l, respond as lt, seoPostToolUseResponse as m, normalizeEvent as mt, handlePre as n, removeOldFiles as nt, gate as o, projectContext as ot, seoPostToolUse as p, trackFile as pt, subagentCacheContext as q, DEFAULT_WINDOW_MS as r, trimLogFile as rt, preCommitGate as s, promptSubmitContext as st, handleHook as t, purgeTtlTree as tt, extractSymbols as u, recordActivity as ut, trackWatchResearch as v, WEBFETCH_TTL_MS as vt, dispatchAipilot as w, loadSecurityState as wt, trackEnrichment as x, queryOf as xt, trackMcpResearch as y, cacheQueryOf as yt, postEditTypescript as z };
+export { saveApexState as $, trackSkillRead as A, writePluginMap as B, seoPostToolUse as C, isoUtc as Ct, postTrackingSideEffects as D, securityStatePath as Dt, securityAdvisory as E, securityStateDir as Et, dispatchLessons as F, mergeLines as G, isProject as H, lessonsFileFor as I, listChildren as J, countFiles as K, lessonsStateFileFor as L, dispatchLifecycle as M, aipilotPostToolUse as N, trackWatchResearch as O, todayUtc as Ot, dispatchAipilot as P, cleanupSession as Q, cartoSessionStart as R, postEditContext as S, normalizeEvent as St, dispatchMemory as T, saveSecurityState as Tt, writeTree as U, generateProjectMap as V, loadEnriched as W, trackSessionChanges as X, postEditTypescript as Y, validateRulesLoaded as Z, preCommitGate as _, promptSubmitContext as _t, recordActivity as a, solidDetectStart as at, extractSymbols as b, projectHash$1 as bt, MCP_TTL_MS as c, runSessionStartCleanups as ct, isMcpTool as d, purgeTtlTree as dt, logToolFailure as et, queryOf as f, removeOldFiles as ft, gate as g, projectContext as gt, TRIVIAL_BUDGET as h, gitContext as ht, respond as i, detectSolidProfile as it, trackEnrichment as j, trackMcpResearch as k, WEBFETCH_TTL_MS as l, sessionStartCore as lt, REQUIRED_AGENTS as m, devContext as mt, activityFor as n, trackAgentMemory as nt, mcpPostStore as o, injectRules as ot, DEFAULT_WINDOW_MS as p, trimLogFile as pt, getFileDesc as q, handlePre as r, subagentCacheContext as rt, mcpPreIntercept as s, readRules as st, handleHook as t, validateTeammateOutput as tt, cacheQueryOf as u, pruneEmptyDirs as ut, detectDuplication as v, taskContext as vt, seoPostToolUseResponse as w, loadSecurityState as wt, lifecycleStdout as x, trackFile as xt, dryGate as y, defaultStateDir as yt, generateEcosystemMap as z };