@fusengine/harness 0.1.68 → 0.1.69

package/dist/{handle-D8rvbAfw.mjs → handle-CVk0NlTg.mjs}

@@ -4,7 +4,7 @@ import { r as projectLayout } from "./layout-C0jaaCQC.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
 import { A as detectCreationIntent, E as isExcludedSwiftPath, F as docConsultedGate, H as detectProjectType$1, I as evaluateApex, M as POST_AUTH_GATES, N as PRE_AUTH_GATES, S as usesTailwindUtilities, T as isExcludedJsPath, V as detectModularArchitecture, W as requiredArchSkill, _ as scanPlugin, c as EXCLUDE_DIRS$1, d as buildApexTaskInjection, h as buildClaudeMdContext, k as capVerbosity, l as PROJECT_INDICATORS, n as missingSeoElements, o as parseEnrichment, r as descFromText, s as parseEntry, t as isHtmlLike, w as frameworkSolidGate, x as skillTriggerGate, y as parseField, z as detectFramework } from "./validate-DnOqIZD_.mjs";
 import { a as sanitizeSessionId, c as sessionsDir, d as countFrameworkCodeLines, f as countLines, i as loadSessionState, l as PLUGINS_DIR, n as fuseHarnessHome, o as saveSessionState, r as fusengineCache, t as claudeHome } from "./home-state-D0RLWP8J.mjs";
-import { n as FAIL_CLOSED, t as evaluate } from "./evaluate-CRZ_Hq33.mjs";
+import { n as FAIL_CLOSED, t as evaluate } from "./evaluate-Dx6q1kmQ.mjs";
 import { a as writeJsonFile, i as readJsonFile, r as hashText, t as atomicWrite } from "./json-io-DisYd2fb.mjs";
 import { r as isDocConsulted } from "./doc-helpers-CWZegVdR.mjs";
 import { n as findMarketplacePlugins, r as readPluginMeta, t as resolveSkillPath } from "./skill-path-DhItkBzk.mjs";
@@ -14,14 +14,14 @@ import { d as loadIndex, i as cacheLookupMeta, n as webfetchCacheWrite, o as cac
 import { t as loadRefs } from "./loader-AGz4nK7d.mjs";
 import { a as writeLastNonce, c as recordAgent, d as recordRefRead, f as recordTarget, h as apexAuthorizationGate, i as verifyTrack, l as recordBrainstormRequired, m as trivialCount, n as saveTrack, o as agentsFresh, p as recordTrivialEdit, r as signTrack, s as emptyTrack, t as loadTrack, u as recordDoc } from "./store-CQ4roWrU.mjs";
 import { n as parseApplyPatch, t as isBypassPermissions } from "./permission-mode-BN3MNgbm.mjs";
-import { _ as writeText, d as collectFiles, f as pathExists, g as spawnCapture, h as sleep, i as denyResponse, l as systemMessage, m as readText, n as blockResponse, r as contextResponse, s as informResponse, t as attachSystemMessage, v as commandToString } from "./claude-BmchLlp7.mjs";
-import { r as toHermesResponse } from "./hermes-dbvFJRuY.mjs";
+import { _ as writeText, d as collectFiles, f as pathExists, g as spawnCapture, h as sleep, i as denyResponse, l as systemMessage, m as readText, n as blockResponse, r as contextResponse, s as informResponse, t as attachSystemMessage, v as commandToString } from "./claude-CHpb1U0A.mjs";
+import { r as toHermesResponse } from "./hermes-CddsFoPN.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 { appendFileSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { mkdir, rmdir } from "node:fs/promises";
 import { createHash } from "node:crypto";
-import { execFileSync, execSync } from "node:child_process";
+import { execFileSync, execSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import figures from "figures";
 //#region src/runtime/lifecycle/security/skill-state.ts
@@ -105,7 +105,7 @@ function normalizeEvent(id, payload) {
 		}));
 		return {
 			...base,
-			phase: "pre",
+			phase: base.phase,
 			files: files.length > 0 ? files : void 0
 		};
 	}
@@ -1980,6 +1980,215 @@ function harvestSubagentTrack(payload, cwd, now, baseDir = defaultStateDir(cwd))
 	} catch {}
 }
 //#endregion
+//#region src/cli/doctor.ts
+/**
+* `harness doctor` — diagnose which `@fusengine/harness` is actually running.
+*
+* A confirmed, still-open bun bug (oven-sh/bun #5791; scoped-pkg behaviour
+* reinforced by #32019/#32150) makes `bunx <pkg>` (unpinned) prefer a stale
+* GLOBAL install over npm-latest, so a consumer can silently run an old harness
+* after a publish. This command surfaces the truth: the resolved version +
+* package path of the code executing right now, the runtime binary, and the
+* latest version published on npm. It queries the registry over HTTP (not
+* `npm view`, whose exit code is 0 even on an empty result — npm/cli#6408) and
+* never throws: an offline environment yields `latest: null`, never a crash.
+*/
+const PKG = "@fusengine/harness";
+/** Walk up from `startDir` for the `@fusengine/harness` `package.json`. */
+function findPackage(startDir) {
+	let dir = startDir;
+	for (let depth = 0; depth < 6; depth++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (pkg.name === PKG) return {
+				version: pkg.version ?? "unknown",
+				path: dir
+			};
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/** Resolve the running version + package path (no network), from a module URL. */
+function runningVersion(moduleUrl) {
+	const found = findPackage(dirname(fileURLToPath(moduleUrl)));
+	return {
+		version: found?.version ?? "unknown",
+		path: found?.path ?? "unknown"
+	};
+}
+/** One-line `pkg vX.Y.Z` banner (stderr, only on explicit `--version`/`doctor` commands — never on `hook`, to avoid spamming automated invocations). */
+function versionBanner(moduleUrl) {
+	return `${PKG} v${runningVersion(moduleUrl).version}`;
+}
+/** Latest published version via the npm registry HTTP API. `null` on any failure. */
+async function npmLatest() {
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: AbortSignal.timeout(8e3) });
+		if (!res.ok) return null;
+		return (await res.json()).version ?? null;
+	} catch {
+		return null;
+	}
+}
+/** Build the full diagnostic report for the module at `moduleUrl`. */
+async function buildDoctorReport(moduleUrl) {
+	const { version, path } = runningVersion(moduleUrl);
+	const latest = await npmLatest();
+	return {
+		running: version,
+		packagePath: path,
+		runtime: process.execPath,
+		latest,
+		stale: latest !== null && latest !== version
+	};
+}
+/** Render a {@link DoctorReport} as human-readable stdout text. */
+function formatDoctor(r) {
+	const lines = [
+		`${PKG} doctor`,
+		`  running:    ${r.running}`,
+		`  package:    ${r.packagePath}`,
+		`  runtime:    ${r.runtime}`,
+		`  npm latest: ${r.latest ?? "(unavailable — offline or unreachable)"}`
+	];
+	if (r.stale) lines.push(`  ! stale — npm serves ${r.latest}. Pin "@fusengine/harness@${r.latest}" in hooks.json (see README).`);
+	else if (r.latest !== null) lines.push(`  ok — running the latest published version.`);
+	return lines.join("\n");
+}
+/** Run `harness doctor`: print the diagnostic to stdout. Always resolves 0 (pure info). */
+async function runDoctor(moduleUrl) {
+	process.stdout.write(formatDoctor(await buildDoctorReport(moduleUrl)) + "\n");
+	return 0;
+}
+//#endregion
+//#region src/runtime/notification-sound.ts
+/**
+* @module notification-sound
+* Resolve the on-disk sound file for a hook notification kind: a per-kind env
+* override, else the package's own `assets/song/` bundle, else a plugin-root
+* fallback. Returns an absolute path or `null` ("stay silent"). NEVER throws.
+* @packageDocumentation
+*/
+/** Kind → asset filename (under `assets/song/` and the plugin-root fallback). */
+const FILES = {
+	stop: "finish.mp3",
+	permission: "permission-need.mp3",
+	human: "need-human.mp3"
+};
+/** Kind → env var holding an explicit override path. */
+const ENV_VARS = {
+	stop: "FUSE_HARNESS_SOUND_STOP",
+	permission: "FUSE_HARNESS_SOUND_PERMISSION",
+	human: "FUSE_HARNESS_SOUND_HUMAN"
+};
+/**
+* Resolve the sound file for `kind`, or `null` when none is available. Cascade:
+* (1) the per-kind env override when present on disk; (2) the package's own
+* `assets/song/<f>.mp3`, located by walking up to the running `package.json`
+* ({@link runningVersion} — survives the flat/hashed `dist/` bundle a hardcoded
+* `../../` of non-deterministic depth would escape); (3) `$CLAUDE_PLUGIN_ROOT/song/<f>.mp3`. Never throws.
+* @param kind - Which event to voice.
+* @param env - Injectable environment (defaults to `process.env`).
+* @param moduleUrl - Injectable module URL (defaults to this module's; locates the package).
+*/
+function resolveSound(kind, env = process.env, moduleUrl = import.meta.url) {
+	try {
+		const override = env[ENV_VARS[kind]];
+		if (override && existsSync(override)) return override;
+		const pkgRoot = runningVersion(moduleUrl).path;
+		if (pkgRoot !== "unknown") {
+			const asset = join(pkgRoot, "assets", "song", FILES[kind]);
+			if (existsSync(asset)) return asset;
+		}
+		const pluginRoot = env.CLAUDE_PLUGIN_ROOT;
+		if (pluginRoot) {
+			const fallback = join(pluginRoot, "song", FILES[kind]);
+			if (existsSync(fallback)) return fallback;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/runtime/notifications.ts
+/**
+* @module notifications
+* Native OS notification sound for lifecycle hook events (turn Stop, permission
+* needed, human needed). ON by default; opt OUT with `FUSE_HARNESS_SOUND=0`.
+*
+* Only two events invoke {@link notify}: the core-scope `Stop` (Codex-only —
+* Claude voices Stop via its own native `afplay` hook, so this never double-
+* sounds) and `TeammateIdle` (Claude-only, which has no native sound). That
+* structural split IS the anti-double-sound guarantee — do NOT add a harness-id
+* gate here: it would silence `TeammateIdle`'s "human" sound, whose only home is
+* claude-code. PermissionRequest/Notification stay native-only and are
+* intentionally not wired here (no dead code).
+*
+* ABSOLUTE fail-open, `command || true` semantics: an opt-out, an unsupported
+* platform, a missing player binary, a missing/undecodable sound file, or a
+* non-zero exit is swallowed — this module NEVER throws and NEVER blocks the
+* caller, so a broken/absent player can never break a hook.
+* @packageDocumentation
+*/
+/**
+* The player command for `platform` playing `file`, or undefined for an
+* unsupported platform. Pure — no filesystem/process access, so it is cheaply
+* unit-testable without spawning anything. mp3 decoding is native on darwin
+* (`afplay`); on linux (`paplay`/libsndfile) and win32 (`SoundPlayer`, wav-only)
+* a bare mp3 may not decode — harmless under the fail-open contract.
+* @param platform - `process.platform`-shaped value.
+* @param file - Absolute path to the sound file to play.
+*/
+function resolvePlayer(platform, file) {
+	if (platform === "darwin") return {
+		bin: "afplay",
+		args: [file]
+	};
+	if (platform === "linux") return {
+		bin: "paplay",
+		args: [file]
+	};
+	if (platform === "win32") return {
+		bin: "powershell",
+		args: [
+			"-NoProfile",
+			"-c",
+			`(New-Object Media.SoundPlayer '${file}').PlaySync()`
+		]
+	};
+}
+/** True unless the user opted OUT (`FUSE_HARNESS_SOUND=0`). ON by default. */
+function soundEnabled(env = process.env) {
+	return env.FUSE_HARNESS_SOUND !== "0";
+}
+/**
+* Fire-and-forget a native notification sound for `kind`. See module doc for
+* the absolute fail-open contract. A `null` resolved sound (nothing on disk) is
+* a silent no-op.
+* @param kind - Which event to voice.
+* @param opts - Injectable platform/env/spawn for tests; production defaults to the real ones.
+*/
+function notify(kind, opts = {}) {
+	try {
+		const env = opts.env ?? process.env;
+		if (!soundEnabled(env)) return;
+		const file = resolveSound(kind, env);
+		if (!file) return;
+		const player = resolvePlayer(opts.platform ?? process.platform, file);
+		if (!player) return;
+		const child = (opts.spawnFn ?? spawn)(player.bin, player.args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+//#endregion
 //#region src/runtime/lifecycle/teammate-idle-check.ts
 /**
 * @module teammate-idle-check
@@ -2031,7 +2240,9 @@ function teammateIdleContext(data, cwd, home = homedir(), now = Date.now()) {
 		})) notice = `Teammate '${teammate}' idle but expected deliverable(s) not found on disk: ${missing.slice(0, 5).join(", ")} — verify before treating as done.`;
 	}
 	const merged = [sniper, notice].filter(Boolean).join("\n\n");
-	return merged ? contextResponse("TeammateIdle", merged) : "";
+	if (!merged) return "";
+	notify("human");
+	return contextResponse("TeammateIdle", merged);
 }
 //#endregion
 //#region src/policy/lessons/trigger-index.ts
@@ -2675,90 +2886,6 @@ function collectGit(root) {
 	return lines.join("\n");
 }
 //#endregion
-//#region src/cli/doctor.ts
-/**
-* `harness doctor` — diagnose which `@fusengine/harness` is actually running.
-*
-* A confirmed, still-open bun bug (oven-sh/bun #5791; scoped-pkg behaviour
-* reinforced by #32019/#32150) makes `bunx <pkg>` (unpinned) prefer a stale
-* GLOBAL install over npm-latest, so a consumer can silently run an old harness
-* after a publish. This command surfaces the truth: the resolved version +
-* package path of the code executing right now, the runtime binary, and the
-* latest version published on npm. It queries the registry over HTTP (not
-* `npm view`, whose exit code is 0 even on an empty result — npm/cli#6408) and
-* never throws: an offline environment yields `latest: null`, never a crash.
-*/
-const PKG = "@fusengine/harness";
-/** Walk up from `startDir` for the `@fusengine/harness` `package.json`. */
-function findPackage(startDir) {
-	let dir = startDir;
-	for (let depth = 0; depth < 6; depth++) {
-		try {
-			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
-			if (pkg.name === PKG) return {
-				version: pkg.version ?? "unknown",
-				path: dir
-			};
-		} catch {}
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	return null;
-}
-/** Resolve the running version + package path (no network), from a module URL. */
-function runningVersion(moduleUrl) {
-	const found = findPackage(dirname(fileURLToPath(moduleUrl)));
-	return {
-		version: found?.version ?? "unknown",
-		path: found?.path ?? "unknown"
-	};
-}
-/** One-line `pkg vX.Y.Z` banner (stderr, only on explicit `--version`/`doctor` commands — never on `hook`, to avoid spamming automated invocations). */
-function versionBanner(moduleUrl) {
-	return `${PKG} v${runningVersion(moduleUrl).version}`;
-}
-/** Latest published version via the npm registry HTTP API. `null` on any failure. */
-async function npmLatest() {
-	try {
-		const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: AbortSignal.timeout(8e3) });
-		if (!res.ok) return null;
-		return (await res.json()).version ?? null;
-	} catch {
-		return null;
-	}
-}
-/** Build the full diagnostic report for the module at `moduleUrl`. */
-async function buildDoctorReport(moduleUrl) {
-	const { version, path } = runningVersion(moduleUrl);
-	const latest = await npmLatest();
-	return {
-		running: version,
-		packagePath: path,
-		runtime: process.execPath,
-		latest,
-		stale: latest !== null && latest !== version
-	};
-}
-/** Render a {@link DoctorReport} as human-readable stdout text. */
-function formatDoctor(r) {
-	const lines = [
-		`${PKG} doctor`,
-		`  running:    ${r.running}`,
-		`  package:    ${r.packagePath}`,
-		`  runtime:    ${r.runtime}`,
-		`  npm latest: ${r.latest ?? "(unavailable — offline or unreachable)"}`
-	];
-	if (r.stale) lines.push(`  ! stale — npm serves ${r.latest}. Pin "@fusengine/harness@${r.latest}" in hooks.json (see README).`);
-	else if (r.latest !== null) lines.push(`  ok — running the latest published version.`);
-	return lines.join("\n");
-}
-/** Run `harness doctor`: print the diagnostic to stdout. Always resolves 0 (pure info). */
-async function runDoctor(moduleUrl) {
-	process.stdout.write(formatDoctor(await buildDoctorReport(moduleUrl)) + "\n");
-	return 0;
-}
-//#endregion
 //#region src/runtime/lifecycle/snapshot/version.ts
 /** Read the `version` field of `<root>/package.json`, or `""` if absent/unreadable. */
 function pkgVersion(root) {
@@ -3022,14 +3149,18 @@ function collectViolations(files, max) {
 * Handle TaskCompleted (ports `task-completed/validate-task-solid.py`, plus the
 * receipt gate). SOLID violations surface first as `SOLID VIOLATION`
 * additionalContext; once the files comply, {@link receiptGate} refuses a "done"
-* that has no fresh passing tsc/test receipt.
-* @param payload - The TaskCompleted payload (`task_id`, `task_subject`, `session_id`).
+* that has no fresh passing tsc/test receipt. Also reused verbatim from `Stop`
+* for Codex's core scope ({@link stopCore}): Codex never emits `TaskCompleted`
+* (codex-plugins/docs/reference/hooks.md) so this is its only completion check;
+* `event` lets that caller stamp the real hook name instead of a false one.
+* @param payload - The TaskCompleted/Stop payload (`task_id`, `task_subject`, `session_id`).
 * @param home - Home dir (defaults to `~`).
 * @param now - Clock (defaults to `Date.now()`).
 * @param stateDir - Track base dir (defaults to the cwd-derived state dir; matches `handleHook`).
+* @param event - The hook event name to stamp on the SOLID-violation response (default `TaskCompleted`).
 * @returns The native hook stdout, or `""` when the session is clean.
 */
-function validateTaskSolid(payload, home = homedir(), now = Date.now(), stateDir = defaultStateDir(process.cwd())) {
+function validateTaskSolid(payload, home = homedir(), now = Date.now(), stateDir = defaultStateDir(process.cwd()), event = "TaskCompleted") {
 	const sid = sanitizeSessionId(payload.session_id ?? "unknown");
 	if (!sid) return "";
 	const files = loadSessionState(sid, home).changes?.modifiedFiles ?? [];
@@ -3038,7 +3169,7 @@ function validateTaskSolid(payload, home = homedir(), now = Date.now(), stateDir
 	const violations = collectViolations(files, max);
 	if (violations.length === 0) return receiptGate(sid, files, now, stateDir) ?? "";
 	const taskId = String(payload.task_id ?? "");
-	return contextResponse("TaskCompleted", `SOLID VIOLATION in task '${String(payload.task_subject ?? "")}' (${taskId}): ${violations.length} file(s) exceed ${max} lines: ` + violations.slice(0, 5).join("; "));
+	return contextResponse(event, `SOLID VIOLATION in task '${String(payload.task_subject ?? "")}' (${taskId}): ${violations.length} file(s) exceed ${max} lines: ` + violations.slice(0, 5).join("; "));
 }
 //#endregion
 //#region src/runtime/lifecycle/cartographer/fs-util.ts
@@ -3432,7 +3563,7 @@ function parseTs$1(line) {
 	return Date.UTC(+(m[1] ?? 0), mo - 1, d, +(m[4] ?? 0), +(m[5] ?? 0));
 }
 /** Content words (>=4 chars), timestamp & TRIGGERS marker stripped. */
-function tokenize(text) {
+function tokenize$1(text) {
 	return new Set(text.toLowerCase().replace(/\[triggers[^\]]*\]/g, " ").replace(/\[\d{4}-\d{2}-\d{2}[^\]]*\]/g, " ").replace(/[^a-z0-9àâäéèêëîïôöùûüç/._-]+/gi, " ").split(/\s+/).filter((t) => t.length >= 4));
 }
 /** Jaccard overlap of two token sets (0 when both empty). */
@@ -3464,7 +3595,7 @@ function parse(content) {
 		if (/^-\s/.test(l)) blocks.push({
 			raw: [l],
 			ts: parseTs$1(l),
-			tokens: tokenize(l)
+			tokens: tokenize$1(l)
 		});
 		else if (l.trim() && last) last.raw.push(l);
 	}
@@ -3895,6 +4026,35 @@ function dispatchLessons(event, payload, cwd, now) {
 	}
 }
 //#endregion
+//#region src/runtime/lifecycle/stop-core.ts
+/**
+* Handle the core scope's `Stop` event — Codex parity. Codex never emits
+* `SessionEnd`/`TaskCompleted` (codex-plugins/docs/reference/hooks.md,
+* "Harness Runtime Limits": "lifecycle dispatch includes Claude-only names
+* such as TaskCompleted, PostToolUseFailure, and SessionEnd; Codex does not
+* emit those events") but its own hooks.json wires `Stop` to `hook codex
+* core`, and its own docs table defines `Stop` as "turn finishes — cleanup
+* and completion notification". Both ported behaviors collapse onto it here
+* rather than being invented anew: {@link cleanupSession} (normally
+* SessionEnd-only) for cleanup, {@link validateTaskSolid} (normally
+* TaskCompleted-only) for the SOLID/receipt completion check.
+*
+* Claude-side, this branch is unreachable: core-guards' Claude `Stop` hooks
+* are a native `afplay` sound + an LLM `type:"prompt"` check, neither of
+* which invokes the harness binary (see `hooks/hooks.json` in claude-plugins
+* vs codex-plugins) — `dispatchLifecycle`'s `case "Stop"` for scope `"core"`
+* only ever receives a real payload from Codex.
+* @param payload - The raw Stop hook payload.
+* @param cwd - Project root (drives the state dir).
+* @param now - Clock.
+* @returns The native hook stdout ("" when the session is clean).
+*/
+function stopCore(payload, cwd, now) {
+	cleanupSession(void 0, now);
+	notify("stop");
+	return validateTaskSolid(payload, homedir(), now, defaultStateDir(cwd), "Stop");
+}
+//#endregion
 //#region src/runtime/lifecycle/aipilot/inject-apex.ts
 /**
 * SubagentStart (matcher "") for the ai-pilot scope: inject APEX AGENTS.md +
@@ -5092,8 +5252,7 @@ function contextTextOf(response) {
 }
 /**
 * Combine N SubagentStart responses into one (Claude concatenates every hook's
-* additionalContext; collapsing the matcher-"" + type-specific scripts into one
-* dispatch call must do that join itself). Returns "" when all are empty.
+* additionalContext; this single dispatch call must do that join itself). "" when all empty.
 */
 function combineContext(...responses) {
 	const parts = responses.map(contextTextOf).filter(Boolean);
@@ -5112,10 +5271,9 @@ async function typeSpecificCache(agent, cwd, now) {
 	return "";
 }
 /**
-* SubagentStart routing. Parity with the Python ai-pilot hooks: the two
-* matcher-"" entries (APEX context + lessons "known issues") fire for EVERY
-* sub-agent, then the type-specific cache (explore/doc/test) is concatenated on
-* top. Sniper must still receive the lessons block — hence no early return.
+* SubagentStart routing (parity with the Python ai-pilot hooks): the two matcher-""
+* entries (APEX context + lessons) fire for EVERY sub-agent, then the type-specific
+* cache is concatenated on top — sniper too, hence no early return.
 */
 async function onSubagentStart(payload, cwd, now) {
 	const agent = agentTypeOf(payload);
@@ -5139,7 +5297,7 @@ async function onSubagentStop(payload, cwd) {
 async function dispatchAipilot(event, payload, cwd, now) {
 	if (event === "SubagentStart") return onSubagentStart(payload, cwd, now);
 	if (event === "SubagentStop") return onSubagentStop(payload, cwd);
-	if (event === "SessionEnd") {
+	if (event === "SessionEnd" || event === "Stop") {
 		await cacheAnalyticsSave(void 0, now);
 		return "";
 	}
@@ -5177,7 +5335,9 @@ function dispatchLifecycle(input) {
 			if (input.scope === "aipilot") return "";
 			if (input.scope === "lessons") return dispatchLessons("SubagentStart", input.payload, input.cwd, input.now);
 			return subagentCacheContext(input.payload.session_id);
-		case "Stop": return input.scope === "lessons" ? dispatchLessons("Stop", input.payload, input.cwd, input.now) : null;
+		case "Stop":
+			if (input.scope === "lessons") return dispatchLessons("Stop", input.payload, input.cwd, input.now);
+			return input.scope === "core" ? stopCore(input.payload, input.cwd, input.now) : null;
 		case "SubagentStop":
 			if (input.scope === "aipilot") return "";
 			harvestSubagentTrack(input.payload, input.cwd, input.now);
@@ -5360,9 +5520,22 @@ function postTrackingSideEffects(scope, event, input, now, payload = {}, cwd = p
 */
 const CODE_RE = /\.(ts|tsx|js|jsx|py|php|swift|go|rs|rb|java)$/;
 const ADVISORY = "SECURITY: Read security skill references before modifying code. Use: Read skills/security-scan/references/scan-patterns.md";
+/** True once today's security skill is marked read. Fail-open: missing/corrupt state reads as unread. */
+function skillAlreadyRead(now, home) {
+	const path = securityStatePath(now, home);
+	if (!existsSync(path)) return false;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")).skill_read === true;
+	} catch {
+		return false;
+	}
+}
 /**
-* Build a non-blocking PreToolUse `allow` response with a security advisory when
-* editing a code file before the security skill has been read. "" otherwise.
+* Build a non-blocking PreToolUse advisory when editing a code file before the
+* security skill has been read, "" otherwise. Renders through the shared
+* {@link contextResponse} builder (`additionalContext` only) — NEVER a naked
+* `permissionDecision: "allow"`, which the Codex adapter's own hook shape
+* (`src/adapters/claude/index.ts`) never emits and which Codex rejects.
 * @param tool - The tool name (`Write`/`Edit`).
 * @param filePath - The target file path.
 * @param now - Clock.
@@ -5372,15 +5545,26 @@ const ADVISORY = "SECURITY: Read security skill references before modifying code
 function securityAdvisory(tool, filePath, now = Date.now(), home = homedir()) {
 	if (tool !== "Write" && tool !== "Edit") return "";
 	if (!CODE_RE.test(filePath)) return "";
-	const path = securityStatePath(now, home);
-	if (existsSync(path)) try {
-		if (JSON.parse(readFileSync(path, "utf-8")).skill_read === true) return "";
-	} catch {}
-	return JSON.stringify({ hookSpecificOutput: {
-		hookEventName: "PreToolUse",
-		permissionDecision: "allow",
-		additionalContext: ADVISORY
-	} });
+	if (skillAlreadyRead(now, home)) return "";
+	return contextResponse("PreToolUse", ADVISORY);
+}
+/**
+* Multi-file counterpart for a Codex `apply_patch` envelope: evaluate EACH
+* add/update file (delete ignored outright; non-code filtered by the same
+* `CODE_RE` inside {@link securityAdvisory}) and return the advisory
+* triggered by the FIRST qualifying file, or "" once the skill has been read
+* or no file qualifies.
+* @param files - The patch's per-file changes ({@link NormalizedFile}).
+* @param now - Clock.
+* @param home - Home dir.
+*/
+function securityAdvisoryForPatch(files, now = Date.now(), home = homedir()) {
+	for (const f of files) {
+		if (f.op === "delete") continue;
+		const advisory = securityAdvisory(f.op === "add" ? "Write" : "Edit", f.filePath, now, home);
+		if (advisory) return advisory;
+	}
+	return "";
 }
 //#endregion
 //#region src/runtime/lifecycle/memory/client.ts
@@ -5621,7 +5805,7 @@ function isMemoryTool(tool) {
 */
 async function dispatchMemory(event, payload, cwd, now) {
 	if (event === "SessionStart") return recallOnSession(cwd, now);
-	if (event === "SubagentStop") {
+	if (event === "SubagentStop" || event === "Stop") {
 		await captureAgentLesson(payload, now);
 		return "";
 	}
@@ -7678,7 +7862,7 @@ async function handlePre(ctx) {
 		exit: 0
 	};
 	if (opts.scope === "security") return {
-		stdout: securityAdvisory(event.tool, event.filePath ?? "", opts.now),
+		stdout: event.files?.length ? securityAdvisoryForPatch(event.files, opts.now) : securityAdvisory(event.tool, event.filePath ?? "", opts.now),
 		exit: 0
 	};
 	if (opts.scope === "solid") return {
@@ -7808,6 +7992,104 @@ function docFramework(input, fallback) {
 	return frameworkFromQuery(docQueryOf(input)) ?? fallback;
 }
 //#endregion
+//#region src/policy/shell-read-refs.ts
+/**
+* @module shell-read-refs
+* Codex teammates frequently read skill/SOLID reference `.md` files through a
+* shell Bash call (`cat`, `head`, …) instead of a native `Read` — the
+* refsRead/ref-journal freshness gates only ever credited a native `Read`
+* (`src/runtime/activity.ts`'s `READ_TOOLS` branch), so a shell-read skill
+* consultation was invisible to every SOLID/skill gate. This detects the
+* `.md` paths a KNOWN read-only command targets in a Bash `command`, for a
+* caller to fold into the SAME `{kind:"ref", path, ts}` activity
+* `src/runtime/record.ts` already persists (no new store, no new gate).
+*
+* Fail-open by construction: only a whitelisted read-only command name
+* credits its `.md` arguments — a non-read command (`echo`, `mv`, `tee`, …)
+* sharing a chained/piped segment is never credited, and `sed -i`/
+* `--in-place` (a MUTATION despite the `sed` name) is explicitly excluded.
+* @packageDocumentation
+*/
+/** Read-only shell commands that can target a `.md` reference by path. */
+const READ_COMMANDS = /* @__PURE__ */ new Set([
+	"cat",
+	"head",
+	"tail",
+	"sed",
+	"rg",
+	"ripgrep",
+	"less",
+	"more",
+	"bat"
+]);
+/** POSIX shells whose `-c`-style argv (or inline string) wraps a real script. */
+const SHELL_BINS = /* @__PURE__ */ new Set([
+	"bash",
+	"sh",
+	"zsh",
+	"dash"
+]);
+/** `sed -i` / `sed --in-place` mutates the file in place — never a read. */
+const SED_INPLACE = /(^|\s)(-i\b|--in-place\b)/;
+/** Split a command string on `&&`, `||`, `;`, `|`, and newlines — each side scanned independently. */
+function segments(command) {
+	return command.split(/&&|\|\||[;|\n]/);
+}
+/** Strip a redirection (`>`, `>>`, `<`, `2>`, `&>`, …) and everything after — its target is WRITTEN, not read. */
+function beforeRedirect(segment) {
+	const m = segment.match(/\s(?:\d*>{1,2}|<|&>)\s*\S/);
+	return m ? segment.slice(0, m.index) : segment;
+}
+/** Naive shell tokenizer: whitespace-split, stripping one matching layer of quotes per token. */
+function tokenize(segment) {
+	return (segment.match(/(?:"[^"]*"|'[^']*'|\S+)/g) ?? []).map((t) => /^(['"]).*\1$/.test(t) ? t.slice(1, -1) : t);
+}
+/** Index of the first token that isn't an env-assignment prefix (`KEY=VAL cmd …`). */
+function firstCommandIndex(tokens) {
+	let i = 0;
+	while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i] ?? "")) i++;
+	return i;
+}
+/** The inner script of a `sh|bash|zsh|dash -c <script>` wrapper (as ONE token, since {@link tokenize} keeps a quoted phrase whole), or undefined when `tokens` isn't that shape. */
+function unwrapShellC(tokens) {
+	const i = firstCommandIndex(tokens);
+	const bin = tokens[i]?.slice(tokens[i].lastIndexOf("/") + 1);
+	if (!bin || !SHELL_BINS.has(bin)) return void 0;
+	const flag = tokens[i + 1];
+	if (!flag || !/^-[a-z]*c$/.test(flag)) return void 0;
+	return tokens[i + 2];
+}
+/** Credit the `.md` arguments of one segment if its command is a whitelisted read; recurses once into a `sh -c` wrapper. */
+function scanSegment(raw, out) {
+	const segment = beforeRedirect(raw);
+	const tokens = tokenize(segment);
+	const inner = unwrapShellC(tokens);
+	if (inner !== void 0) {
+		for (const s of segments(inner)) scanSegment(s, out);
+		return;
+	}
+	const i = firstCommandIndex(tokens);
+	const name = tokens[i]?.slice(tokens[i].lastIndexOf("/") + 1);
+	if (!name || !READ_COMMANDS.has(name)) return;
+	if (name === "sed" && SED_INPLACE.test(segment)) return;
+	for (const t of tokens.slice(i + 1)) if (t.endsWith(".md") && !t.startsWith("-")) out.push(t);
+}
+/**
+* The `.md` paths a read-only shell command reads in `command` (a Bash
+* `tool_input.command` — plain string or Codex's argv-array form, both
+* normalized via {@link commandToString}). Empty for a non-read command,
+* `sed -i` in-place, or an unparseable/absent command — fail-open, never a
+* false credit.
+* @param command - Raw `tool_input.command` value (string | string[] | unknown).
+*/
+function shellReadRefPaths(command) {
+	const str = commandToString(command);
+	if (!str) return [];
+	const out = [];
+	for (const seg of segments(str)) scanSegment(seg, out);
+	return out;
+}
+//#endregion
 //#region src/runtime/activity.ts
 /** Min response length (chars) for a lead agent call to count as `sufficient`. */
 const AGENT_QUALITY_MIN = 500;
@@ -7888,6 +8170,11 @@ function activityFor(event) {
 			ts: event.now
 		});
 	}
+	if (event.tool === "Bash") for (const path of shellReadRefPaths(event.input?.command)) out.push({
+		kind: "ref",
+		path,
+		ts: event.now
+	});
 	return out;
 }
 //#endregion
@@ -7977,11 +8264,126 @@ async function recordCodexSpawnEvidence(file, id, tool, input, ts) {
 	if (next !== track) await saveTrack(file, next);
 }
 //#endregion
+//#region src/tracking/codex-post-failure.ts
+/**
+* @module codex-post-failure
+* Codex has no native `PostToolUseFailure` event (Claude Code's own failure
+* signal, ported in `src/runtime/lifecycle/tool-failure.ts`'s `logToolFailure`)
+* — every Codex tool outcome, success or failure, arrives on the SAME
+* `PostToolUse` event. This infers a failure from the regular payload's
+* `tool_result`/`tool_response` and journals it into the EXISTING one-shot
+* failure tally ({@link recordFailure}) — no new store, no new gate.
+*
+* Design choice (fail-open): a payload this module cannot positively prove
+* failed — `null`/`undefined`, a non-object shape, or any parse exception —
+* classifies as `"success"` (ignored), NEVER `"failure"`. Many legitimate
+* successful tool calls return no structured result at all (see
+* `handle-post.ts`'s `spawn_agent` `tool_response: { nickname: "scout" }`),
+* so treating "can't tell" as a failure would flood the tally with false
+* positives. Only an EXPLICIT signal (non-zero exit, an error field) counts.
+* @packageDocumentation
+*/
+/** Truthy interruption markers across harness result shapes (parity `tool-failure.ts`'s `is_interrupt`). */
+const INTERRUPT_KEYS = [
+	"is_interrupt",
+	"isInterrupted",
+	"interrupted",
+	"aborted",
+	"cancelled",
+	"canceled"
+];
+/** True when `result` carries any known interruption marker — an interruption is never a failure. */
+function isInterruption(result) {
+	return INTERRUPT_KEYS.some((k) => result[k] === true);
+}
+/** True when `result` reports a non-zero exit code (Bash-shaped tool result). */
+function hasNonZeroExit(result) {
+	const exit = result.exit_code ?? result.exitCode;
+	return typeof exit === "number" && exit !== 0;
+}
+/** True when `result` carries an explicit error signal (`error`, `is_error`/`isError`, or `success: false`). */
+function hasErrorField(result) {
+	if (result.success === false) return true;
+	if (result.is_error === true || result.isError === true) return true;
+	const err = result.error;
+	return typeof err === "string" ? err.length > 0 : err !== void 0 && err !== null;
+}
+/**
+* Classify a Codex PostToolUse `tool_response`/`tool_result` payload.
+* Fail-open (see module doc): unprovable shapes resolve to `"success"`,
+* never `"failure"`, and this NEVER throws.
+* @param result - The raw result value off the payload (any shape).
+* @returns `"success"` | `"failure"` | `"interrupted"`.
+*/
+function classifyCodexOutcome(result) {
+	try {
+		if (result === null || typeof result !== "object" || Array.isArray(result)) return "success";
+		const r = result;
+		if (isInterruption(r)) return "interrupted";
+		if (hasNonZeroExit(r) || hasErrorField(r)) return "failure";
+		return "success";
+	} catch {
+		return "success";
+	}
+}
+/**
+* Journal a Codex tool failure into the existing one-shot failure tally.
+* No-op for `"success"`/`"interrupted"` — only a genuine failure is recorded.
+* @param tool - The tool name.
+* @param result - The raw PostToolUse result payload.
+* @param opts - Clock + state dir (+ optional session id), forwarded as-is to {@link recordFailure}.
+*/
+function recordCodexPostFailure(tool, result, opts) {
+	if (classifyCodexOutcome(result) !== "failure") return;
+	recordFailure(tool, opts);
+}
+//#endregion
+//#region src/runtime/post-fanout.ts
+/**
+* Fan a Codex `apply_patch` envelope's `event.files` into one synthetic
+* per-file event per touched file, so the per-file PostToolUse gates (SOLID
+* size, Tailwind, tracking, post-edit context) see EACH file instead of the
+* whole patch (whose own `filePath`/`content` are always undefined). `add`
+* maps to `Write`, `update` to `Edit` (mirrors the Pre-phase `applyPatchGate`'s
+* tool mapping); `delete`/`move` map to a tool none of those Write|Edit-gated
+* checks recognize, so they no-op on it without special-casing each gate.
+* Returns `[event]` unchanged for every non-`apply_patch` tool/harness.
+* @param event - The normalized PostToolUse event.
+* @returns One event per touched file, or the original event.
+*/
+function fanOutFiles(event) {
+	if (!event.files || event.files.length === 0) return [event];
+	return event.files.map((f) => ({
+		...event,
+		tool: f.op === "add" ? "Write" : f.op === "update" ? "Edit" : "apply_patch:delete",
+		filePath: f.filePath,
+		content: f.op === "delete" ? void 0 : f.content
+	}));
+}
+/**
+* Run `check(tool, filePath)` over each fanned-out file, OR-ing the verdict —
+* the first non-empty result wins (parity with `applyPatchGate`'s "one
+* violating hunk blocks the whole envelope").
+* @param files - Per-file events from {@link fanOutFiles}.
+* @param check - A PostToolUse gate keyed on `(tool, filePath)`.
+* @returns The first non-empty result, or `""` when every file is clean.
+*/
+function firstFileMatch(files, check) {
+	for (const f of files) {
+		if (!f.filePath) continue;
+		const result = check(f.tool, f.filePath);
+		if (result) return result;
+	}
+	return "";
+}
+//#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.
+* deny, aipilot task cache), then inject the post-edit context. Codex
+* `apply_patch` is fanned into per-file events ({@link fanOutFiles}) before the
+* per-file gates (tracking, SOLID size, Tailwind, post-edit context) run.
 * @param ctx - The resolved context (same shape as the pre pipeline).
 * @returns The native hook outcome.
 */
@@ -8008,21 +8410,27 @@ async function handlePost(ctx) {
 		const exit = Number(r?.exit_code ?? 0);
 		await captureReceipt(file, event.command, out, Number.isFinite(exit) ? exit : 0, opts.now);
 	}
-	postTrackingSideEffects(opts.scope ?? "core", event, event.input, opts.now, payload, opts.cwd);
+	if (id === "codex") recordCodexPostFailure(event.tool, payload.tool_result ?? response, {
+		now: opts.now,
+		dir: defaultStateDir(opts.cwd),
+		sessionId: event.sessionId
+	});
+	const files = fanOutFiles(event);
+	for (const f of files) postTrackingSideEffects(opts.scope ?? "core", f, f.input, opts.now, payload, opts.cwd);
 	const seoDeny = opts.scope === "seo" ? seoPostToolUseResponse(payload) : null;
 	if (seoDeny) return {
 		stdout: seoDeny,
 		exit: 0
 	};
-	if (opts.scope === "solid" && event.filePath) {
-		const solidWarn = checkFileSize(event.tool, event.filePath);
+	if (opts.scope === "solid") {
+		const solidWarn = firstFileMatch(files, checkFileSize);
 		if (solidWarn) return {
 			stdout: solidWarn,
 			exit: 0
 		};
 	}
-	if (opts.scope === "tailwindcss" && event.filePath) {
-		const tailwindWarn = validateTailwind(event.tool, event.filePath);
+	if (opts.scope === "tailwindcss") {
+		const tailwindWarn = firstFileMatch(files, validateTailwind);
 		if (tailwindWarn) return {
 			stdout: tailwindWarn,
 			exit: 0
@@ -8035,7 +8443,11 @@ async function handlePost(ctx) {
 			exit: 0
 		};
 	}
-	const extra = await postEditContext(opts.scope ?? "core", event, opts.now);
+	let extra = "";
+	for (const f of files) {
+		extra = await postEditContext(opts.scope ?? "core", f, opts.now);
+		if (extra) break;
+	}
 	const notice = designPassNotice({
 		agentId: typeof payload.agent_id === "string" ? payload.agent_id : "",
 		tool: event.tool,
@@ -8101,6 +8513,347 @@ async function asyncScopeStdout(scope, event, payload, cwd, now) {
 	return null;
 }
 //#endregion
+//#region src/runtime/lifecycle/codex-resync/lock.ts
+/** Stale-after window (ms) — survives a session crashing before its `finally`. */
+const STALE_MS = 3e4;
+function lockPath(codexHome) {
+	return join(codexHome, "fusengine", "state", "agents-resync.lock");
+}
+/**
+* Best-effort inter-process lock for the agents resync. `writeFileSync(path,
+* pid, { flag: "wx" })` uses `O_EXCL`: it fails with `EEXIST` when the lock
+* file already exists, so two Codex sessions starting at once cannot both
+* resolve then write DIFFERENT versions of the agents cache in interleave (a
+* torn TOML). Stale after {@link STALE_MS} to survive a crash that never
+* reached its `finally`. No live-PID check (a permanent, accepted limit of any
+* mtime-based lock — same tradeoff `proper-lockfile` makes).
+* @param codexHome - The Codex home directory.
+* @returns `true` when the lock was acquired; `false` when another live
+* holder has it.
+*/
+function acquireResyncLock(codexHome) {
+	const path = lockPath(codexHome);
+	mkdirSync(dirname(path), { recursive: true });
+	try {
+		writeFileSync(path, String(process.pid), { flag: "wx" });
+		return true;
+	} catch {
+		try {
+			if (Date.now() - statSync(path).mtimeMs <= STALE_MS) return false;
+			unlinkSync(path);
+			writeFileSync(path, String(process.pid), { flag: "wx" });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+}
+/** Release the lock. Best-effort — never throws. */
+function releaseResyncLock(codexHome) {
+	try {
+		unlinkSync(lockPath(codexHome));
+	} catch {}
+}
+//#endregion
+//#region src/runtime/lifecycle/codex-resync/plugin-roots.ts
+/** Frozen marketplace name (matches codex-plugins' own `scripts/install-codex.ts`). */
+const MARKETPLACE = "fusengine-codex";
+/** The plugin cache root under a Codex home. */
+function pluginsCacheRoot(codexHome) {
+	return join(codexHome, "plugins", "cache", MARKETPLACE);
+}
+/** Descending semver-ish compare (`"2.1" > "10.0"` stays false — numeric per segment). */
+function compareVersionsDesc(a, b) {
+	const left = a.split(/[.-]/).map((part) => Number.parseInt(part, 10));
+	const right = b.split(/[.-]/).map((part) => Number.parseInt(part, 10));
+	const max = Math.max(left.length, right.length);
+	for (let i = 0; i < max; i++) {
+		const av = Number.isNaN(left[i]) ? 0 : left[i] ?? 0;
+		const bv = Number.isNaN(right[i]) ? 0 : right[i] ?? 0;
+		if (av !== bv) return bv - av;
+	}
+	return b.localeCompare(a);
+}
+/** Resolve one plugin's active root: unversioned dir first, else the newest version dir. */
+function resolvePluginRoot(pluginsRoot, plugin) {
+	const root = join(pluginsRoot, plugin);
+	if (existsSync(join(root, ".codex-plugin")) || existsSync(join(root, "skills"))) return root;
+	let entries;
+	try {
+		entries = readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+	} catch {
+		return;
+	}
+	const versions = entries.sort(compareVersionsDesc);
+	return versions[0] ? join(root, versions[0]) : void 0;
+}
+/**
+* Resolve the active root directory of every installed plugin under a plugins
+* cache root, keyed by plugin name. Ports `plugin-root-resolver.ts::buildPluginRoots`.
+* @param pluginsRoot - The plugin cache root (see {@link pluginsCacheRoot}).
+* @returns Plugin name -> resolved root dir (missing entries are silently skipped).
+*/
+function buildPluginRoots(pluginsRoot) {
+	const roots = /* @__PURE__ */ new Map();
+	let entries;
+	try {
+		entries = readdirSync(pluginsRoot, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "_shared").map((e) => e.name);
+	} catch {
+		return roots;
+	}
+	for (const plugin of entries) {
+		const root = resolvePluginRoot(pluginsRoot, plugin);
+		if (root) roots.set(plugin, root);
+	}
+	return roots;
+}
+//#endregion
+//#region src/runtime/lifecycle/codex-resync/fingerprint.ts
+/** Where the last-applied plugin-cache fingerprint is persisted. */
+function manifestPath(codexHome) {
+	return join(codexHome, "fusengine", "state", "agents-cache-fingerprint.json");
+}
+/** sha256 over sorted "plugin=root" pairs — stable while cache resolution is unchanged. */
+function fingerprint(roots) {
+	const sorted = [...roots.entries()].sort(([a], [b]) => a.localeCompare(b));
+	const hash = createHash("sha256");
+	for (const [plugin, root] of sorted) hash.update(`${plugin}=${root}\n`);
+	return hash.digest("hex");
+}
+/** The last-persisted fingerprint, or `undefined` (missing/corrupt — treated as "never resynced"). */
+function readFingerprint(codexHome) {
+	try {
+		return JSON.parse(readFileSync(manifestPath(codexHome), "utf8")).fingerprint;
+	} catch {
+		return;
+	}
+}
+/** Persist the applied fingerprint atomically (tmp+rename via {@link atomicWrite}). */
+function writeFingerprint(codexHome, value) {
+	atomicWrite(manifestPath(codexHome), JSON.stringify({ fingerprint: value }));
+}
+/** True when a direct symlink child of `dir` points at a now-missing target. */
+function hasDanglingSymlink(dir) {
+	if (!existsSync(dir)) return false;
+	try {
+		for (const name of readdirSync(dir)) {
+			const full = join(dir, name);
+			if (lstatSync(full).isSymbolicLink() && !existsSync(full)) return true;
+		}
+	} catch {}
+	return false;
+}
+/**
+* Resolve the current plugin roots + fingerprint. `undefined` = nothing cached
+* (fail-open — the initial installer, not this hook, owns that case).
+* @param pluginsRoot - The plugin cache root.
+*/
+function resolveCurrentFingerprint(pluginsRoot) {
+	if (!pathExists(pluginsRoot)) return void 0;
+	const roots = buildPluginRoots(pluginsRoot);
+	if (roots.size === 0) return void 0;
+	return {
+		roots,
+		value: fingerprint(roots)
+	};
+}
+/** True when a resync is due: fingerprint changed/never recorded, or a command symlink is dangling. */
+function needsResync(codexHome, currentValue, promptsDir) {
+	return currentValue !== readFingerprint(codexHome) || hasDanglingSymlink(promptsDir);
+}
+//#endregion
+//#region src/runtime/lifecycle/codex-resync/plugin-files.ts
+/** Files matching `extension` directly under `dir`, tagged with `plugin`. */
+function filesIn(dir, plugin, extension) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir).filter((file) => file.endsWith(extension)).map((file) => ({
+		plugin,
+		file,
+		src: join(dir, file)
+	}));
+}
+/** Versioned plugin layout: newest version subdir wins, first match returned. */
+function listVersionedFiles(pluginRoot, plugin, subdir, extension) {
+	let versions;
+	try {
+		versions = readdirSync(pluginRoot, { withFileTypes: true }).filter((v) => v.isDirectory() && !v.name.startsWith(".")).map((v) => v.name).sort(compareVersionsDesc);
+	} catch {
+		return [];
+	}
+	for (const version of versions) {
+		const found = filesIn(join(pluginRoot, version, subdir), plugin, extension);
+		if (found.length > 0) return found;
+	}
+	return [];
+}
+/**
+* Discover every plugin's files of a given kind (agents `.toml`, commands
+* `.md`) across a plugins cache root — unversioned layout first, else the
+* newest version subdir. Ports `plugin-file-discovery.ts::listPluginFiles`.
+* @param pluginsRoot - The plugin cache root.
+* @param subdir - `"agents"` or `"commands"`.
+* @param extension - File extension to match, including the dot.
+*/
+function listPluginFiles(pluginsRoot, subdir, extension) {
+	const out = [];
+	let entries;
+	try {
+		entries = readdirSync(pluginsRoot, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "_shared").map((e) => e.name);
+	} catch {
+		return out;
+	}
+	for (const plugin of entries) {
+		const direct = filesIn(join(pluginsRoot, plugin, subdir), plugin, extension);
+		if (direct.length > 0) {
+			out.push(...direct);
+			continue;
+		}
+		out.push(...listVersionedFiles(join(pluginsRoot, plugin), plugin, subdir, extension));
+	}
+	return out;
+}
+//#endregion
+//#region src/runtime/lifecycle/codex-resync/managed-destination.ts
+/** Marker line stamped at the top of a materialized (non-symlinked) agent TOML. */
+const MANAGED_AGENT_MARKER = "# Managed by fusengine-codex; source:";
+/** True when a symlink target lives under a plugin cache dir (ours to manage). */
+function isManagedPluginTarget(target) {
+	return target.includes("/plugins/") || target.includes("\\plugins\\");
+}
+/**
+* Clear a previously-installed destination before reinstalling it, but ONLY
+* when it is clearly ours: a symlink into a plugin cache dir, or a text file
+* stamped with {@link MANAGED_AGENT_MARKER}. Anything else (a user's own file,
+* a foreign symlink) is left untouched. Ports the merged behavior of
+* `plugin-managed-destination.ts` + the local helper in
+* `plugin-file-symlinks.ts` (this harness always runs hook-silent, so the
+* `@clack/prompts` warnings those ports had are dropped, not translated).
+* @param path - The destination path to check/clear.
+* @returns `"missing"` (nothing there), `"removed"` (ours, cleared), or
+* `"skip"` (foreign — left alone).
+*/
+function clearManagedDestination(path) {
+	try {
+		if (lstatSync(path).isSymbolicLink()) {
+			if (!isManagedPluginTarget(readlinkSync(path))) return "skip";
+			unlinkSync(path);
+			return "removed";
+		}
+		if (readFileSync(path, "utf8").startsWith("# Managed by fusengine-codex; source:")) {
+			unlinkSync(path);
+			return "removed";
+		}
+		return "skip";
+	} catch {
+		return "missing";
+	}
+}
+//#endregion
+//#region src/runtime/lifecycle/codex-resync/materialize-agents.ts
+const PORTABLE_SKILL_PATH_RE = /^plugins\/([^/]+)\/skills\/(.+)$/;
+const CACHE_SKILL_PATH_RE = /\/\.codex\/plugins\/cache\/fusengine-codex\/([^/]+)\/[^/]+\/skills\/(.+)$/;
+function tomlString(value) {
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+/** Rewrite one `path = "..."` value to an absolute path (portable/cache skill refs, or relative-to-source). */
+function rewriteAgentSkillPath(value, item, pluginRoots) {
+	const portable = PORTABLE_SKILL_PATH_RE.exec(value);
+	if (portable) {
+		const root = pluginRoots.get(portable[1] ?? "");
+		return root ? join(root, "skills", portable[2] ?? "") : value;
+	}
+	const cached = CACHE_SKILL_PATH_RE.exec(value);
+	if (cached) {
+		const root = pluginRoots.get(cached[1] ?? "");
+		return root ? join(root, "skills", cached[2] ?? "") : value;
+	}
+	if (value.startsWith("./") || value.startsWith("../")) return resolve(dirname(item.src), value);
+	return value;
+}
+/** Rewrite every `path = "..."` line in an agent TOML + stamp the managed-source marker. */
+function materializeAgentToml(raw, item, pluginRoots) {
+	const rewritten = raw.replace(/^(\s*path\s*=\s*)"([^"]+)"/gm, (_m, prefix, value) => `${prefix}${tomlString(rewriteAgentSkillPath(value, item, pluginRoots))}`);
+	return rewritten.startsWith("# Managed by fusengine-codex; source:") ? rewritten : `${MANAGED_AGENT_MARKER} ${item.src}\n${rewritten}`;
+}
+/**
+* Materialize agent TOMLs into `destDir` (Codex ignores symlinked agent
+* TOMLs — openai/codex#15345, never fixed — so these are COPIED, not linked).
+* Silent: no `@clack/prompts` (this always runs inside a hook, which must
+* stay stdout-clean). Ports `agent-materializer.ts::materializeAgentFiles`.
+* @param files - Discovered agent files (see {@link import("./plugin-files").listPluginFiles}).
+* @param destDir - Destination dir (`<codexHome>/agents`).
+* @param pluginRoots - Resolved plugin roots, for `path=` rewriting.
+*/
+function materializeAgentFiles(files, destDir, pluginRoots) {
+	mkdirSync(destDir, { recursive: true });
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of files) {
+		if (seen.has(item.file)) continue;
+		seen.add(item.file);
+		clearManagedDestination(join(destDir, `${item.plugin}-${item.file}`));
+		const destPath = join(destDir, item.file);
+		if (clearManagedDestination(destPath) === "skip") continue;
+		writeFileSync(destPath, materializeAgentToml(readFileSync(item.src, "utf8"), item, pluginRoots));
+	}
+}
+//#endregion
+//#region src/runtime/lifecycle/codex-resync/symlink-commands.ts
+/**
+* Symlink command files (`.md`) into `destDir` — unlike agents, Codex has no
+* known symlink-loading issue for prompts, so these stay linked rather than
+* copied. Silent, no `@clack/prompts` (see {@link materializeAgentFiles} for
+* why). Ports `plugin-file-symlinks.ts::symlinkPluginFiles`.
+* @param files - Discovered command files (see {@link import("./plugin-files").listPluginFiles}).
+* @param destDir - Destination dir (`<codexHome>/prompts`).
+*/
+function symlinkPluginFiles(files, destDir) {
+	mkdirSync(destDir, { recursive: true });
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of files) {
+		if (seen.has(item.file)) continue;
+		seen.add(item.file);
+		clearManagedDestination(join(destDir, `${item.plugin}-${item.file}`));
+		const linkPath = join(destDir, item.file);
+		if (clearManagedDestination(linkPath) === "skip") continue;
+		symlinkSync(item.src, linkPath);
+	}
+}
+//#endregion
+//#region src/runtime/lifecycle/codex-resync/resync.ts
+/** The Codex home dir: `$CODEX_HOME`, else `~/.codex`. */
+function defaultCodexHome() {
+	return process.env.CODEX_HOME ?? join(homedir(), ".codex");
+}
+/**
+* Re-materialize the Codex plugin agents/commands cache on SessionStart, but
+* only when the plugin-cache fingerprint changed (or a command symlink dangles)
+* since the last apply — otherwise a cheap no-op. Agents are COPIED into
+* `<codexHome>/agents` (Codex won't load symlinked agent TOMLs), commands are
+* SYMLINKED into `<codexHome>/prompts`. Guarded by a best-effort inter-process
+* lock so two sessions starting at once can't write a torn cache; the sha256
+* fingerprint is the real correctness backstop (idempotent skip), the lock only
+* reduces redundant concurrent rebuilds. ABSOLUTELY fail-open: any error is
+* swallowed so a resync can never break SessionStart.
+* @param codexHome - The Codex home directory (defaults to {@link defaultCodexHome}).
+*/
+function resyncCodexAgents(codexHome = defaultCodexHome()) {
+	try {
+		const pluginsRoot = pluginsCacheRoot(codexHome);
+		const current = resolveCurrentFingerprint(pluginsRoot);
+		if (!current) return;
+		const promptsDir = join(codexHome, "prompts");
+		if (!needsResync(codexHome, current.value, promptsDir)) return;
+		if (!acquireResyncLock(codexHome)) return;
+		try {
+			materializeAgentFiles(listPluginFiles(pluginsRoot, "agents", ".toml"), join(codexHome, "agents"), current.roots);
+			symlinkPluginFiles(listPluginFiles(pluginsRoot, "commands", ".md"), promptsDir);
+			writeFingerprint(codexHome, current.value);
+		} finally {
+			releaseResyncLock(codexHome);
+		}
+	} catch {}
+}
+//#endregion
 //#region src/runtime/inject-budget-recap.ts
 /**
 * @module inject-budget-recap
@@ -8164,10 +8917,11 @@ async function handleHook(id, payload, opts) {
 	const file = trackFile(event.sessionId, defaultStateDir(opts.cwd));
 	const mcpDir = layout.cacheDir;
 	const framework = detectFramework(event.filePath ?? "", event.content ?? "");
-	if (id === "claude-code" && designLifecycle(payload, mcpDir, opts.cwd, String(opts.now), opts.now)) return {
+	if ((id === "claude-code" || id === "codex") && designLifecycle(payload, mcpDir, opts.cwd, String(opts.now), opts.now)) return {
 		stdout: "",
 		exit: 0
 	};
+	if (id === "codex" && rawEventName(payload) === "SessionStart") resyncCodexAgents();
 	const asyncOut = await asyncScopeStdout(opts.scope, rawEventName(payload), payload, opts.cwd, opts.now);
 	if (asyncOut !== null) return {
 		stdout: asyncOut,
@@ -8206,4 +8960,4 @@ async function handleHook(id, payload, opts) {
 	});
 }
 //#endregion
-export { postEditTypescript as $, trackSkillRead as A, trackFile as At, isProject as B, seoPostToolUse as C, gitContext as Ct, postTrackingSideEffects as D, taskContext as Dt, securityAdvisory as E, promptSubmitContext as Et, dispatchLessons as F, securityStateDir as Ft, getFileDesc as G, loadEnriched as H, cartoSessionStart as I, securityStatePath as It, runningVersion as J, listChildren as K, generateEcosystemMap as L, todayUtc as Lt, dispatchLifecycle as M, isoUtc as Mt, aipilotPostToolUse as N, loadSecurityState as Nt, trackWatchResearch as O, defaultStateDir as Ot, dispatchAipilot as P, saveSecurityState as Pt, lessonsStateFileFor as Q, writePluginMap as R, postEditContext as S, devContext as St, dispatchMemory as T, claudeMdKey as Tt, mergeLines as U, writeTree as V, countFiles as W, lessonsArchiveFileFor as X, versionBanner as Y, lessonsFileFor as Z, preCommitGate as _, sessionStartCore as _t, recordActivity as a, validateTeammateOutput as at, extractSymbols as b, removeOldFiles as bt, MCP_TTL_MS as c, validateTailwind as ct, isMcpTool as d, countLoc as dt, trackSessionChanges as et, queryOf as f, detectSolidProfile as ft, gate as g, runSessionStartCleanups as gt, TRIVIAL_BUDGET as h, readRules as ht, respond as i, logToolFailure as it, trackEnrichment as j, normalizeEvent as jt, trackMcpResearch as k, projectHash$1 as kt, WEBFETCH_TTL_MS as l, validateSolidGate as lt, REQUIRED_AGENTS as m, injectRules as mt, activityFor as n, cleanupSession as nt, mcpPostStore as o, trackAgentMemory as ot, DEFAULT_WINDOW_MS as p, solidDetectStart as pt, runDoctor as q, handlePre as r, saveApexState as rt, mcpPreIntercept as s, subagentCacheContext as st, handleHook as t, validateRulesLoaded as tt, cacheQueryOf as u, checkFileSize as ut, detectDuplication as v, pruneEmptyDirs as vt, seoPostToolUseResponse as w, projectContext as wt, lifecycleStdout as x, trimLogFile as xt, dryGate as y, purgeTtlTree as yt, generateProjectMap as z };
+export { versionBanner as $, trackMcpResearch as A, projectHash$1 as At, generateProjectMap as B, seoPostToolUse as C, devContext as Ct, securityAdvisoryForPatch as D, promptSubmitContext as Dt, securityAdvisory as E, claudeMdKey as Et, dispatchAipilot as F, saveSecurityState as Ft, countFiles as G, writeTree as H, dispatchLessons as I, securityStateDir as It, lessonsArchiveFileFor as J, getFileDesc as K, cartoSessionStart as L, securityStatePath as Lt, trackEnrichment as M, normalizeEvent as Mt, dispatchLifecycle as N, isoUtc as Nt, postTrackingSideEffects as O, taskContext as Ot, aipilotPostToolUse as P, loadSecurityState as Pt, runningVersion as Q, generateEcosystemMap as R, todayUtc as Rt, postEditContext as S, trimLogFile as St, dispatchMemory as T, projectContext as Tt, loadEnriched as U, isProject as V, mergeLines as W, lessonsStateFileFor as X, lessonsFileFor as Y, runDoctor as Z, preCommitGate as _, runSessionStartCleanups as _t, recordActivity as a, logToolFailure as at, extractSymbols as b, purgeTtlTree as bt, MCP_TTL_MS as c, subagentCacheContext as ct, isMcpTool as d, checkFileSize as dt, postEditTypescript as et, queryOf as f, countLoc as ft, gate as g, readRules as gt, TRIVIAL_BUDGET as h, injectRules as ht, respond as i, saveApexState as it, trackSkillRead as j, trackFile as jt, trackWatchResearch as k, defaultStateDir as kt, WEBFETCH_TTL_MS as l, validateTailwind as lt, REQUIRED_AGENTS as m, solidDetectStart as mt, activityFor as n, validateRulesLoaded as nt, mcpPostStore as o, validateTeammateOutput as ot, DEFAULT_WINDOW_MS as p, detectSolidProfile as pt, listChildren as q, handlePre as r, cleanupSession as rt, mcpPreIntercept as s, trackAgentMemory as st, handleHook as t, trackSessionChanges as tt, cacheQueryOf as u, validateSolidGate as ut, detectDuplication as v, sessionStartCore as vt, seoPostToolUseResponse as w, gitContext as wt, lifecycleStdout as x, removeOldFiles as xt, dryGate as y, pruneEmptyDirs as yt, writePluginMap as z };