@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/lifecycle/codex-resync/lock.ts

@@ -0,0 +1,46 @@
+import { mkdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Stale-after window (ms) — survives a session crashing before its `finally`. */
+const STALE_MS = 30_000;
+
+function lockPath(codexHome: string): string {
+  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.
+ */
+export function acquireResyncLock(codexHome: string): boolean {
+  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. */
+export function releaseResyncLock(codexHome: string): void {
+  try {
+    unlinkSync(lockPath(codexHome));
+  } catch { /* best-effort */ }
+}

package/src/runtime/lifecycle/codex-resync/managed-destination.ts

@@ -0,0 +1,39 @@
+import { lstatSync, readFileSync, readlinkSync, unlinkSync } from "node:fs";
+
+/** Marker line stamped at the top of a materialized (non-symlinked) agent TOML. */
+export 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: string): boolean {
+  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).
+ */
+export function clearManagedDestination(path: string): "missing" | "removed" | "skip" {
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      if (!isManagedPluginTarget(readlinkSync(path))) return "skip";
+      unlinkSync(path);
+      return "removed";
+    }
+    if (readFileSync(path, "utf8").startsWith(MANAGED_AGENT_MARKER)) {
+      unlinkSync(path);
+      return "removed";
+    }
+    return "skip";
+  } catch {
+    return "missing";
+  }
+}

package/src/runtime/lifecycle/codex-resync/materialize-agents.ts

@@ -0,0 +1,57 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { clearManagedDestination, MANAGED_AGENT_MARKER } from "./managed-destination";
+import type { PluginFile } from "./plugin-files";
+
+const PORTABLE_SKILL_PATH_RE = /^plugins\/([^/]+)\/skills\/(.+)$/;
+const CACHE_SKILL_PATH_RE = /\/\.codex\/plugins\/cache\/fusengine-codex\/([^/]+)\/[^/]+\/skills\/(.+)$/;
+
+function tomlString(value: string): string {
+  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: string, item: PluginFile, pluginRoots: Map<string, string>): string {
+  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. */
+export function materializeAgentToml(raw: string, item: PluginFile, pluginRoots: Map<string, string>): string {
+  const rewritten = raw.replace(/^(\s*path\s*=\s*)"([^"]+)"/gm, (_m, prefix: string, value: string) =>
+    `${prefix}${tomlString(rewriteAgentSkillPath(value, item, pluginRoots))}`);
+  return rewritten.startsWith(MANAGED_AGENT_MARKER) ? 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.
+ */
+export function materializeAgentFiles(files: PluginFile[], destDir: string, pluginRoots: Map<string, string>): void {
+  mkdirSync(destDir, { recursive: true });
+  const seen = new Set<string>();
+  for (const item of files) {
+    if (seen.has(item.file)) continue;
+    seen.add(item.file);
+    clearManagedDestination(join(destDir, `${item.plugin}-${item.file}`)); // legacy naming cleanup
+    const destPath = join(destDir, item.file);
+    if (clearManagedDestination(destPath) === "skip") continue;
+    const raw = readFileSync(item.src, "utf8");
+    writeFileSync(destPath, materializeAgentToml(raw, item, pluginRoots));
+  }
+}

package/src/runtime/lifecycle/codex-resync/plugin-files.ts

@@ -0,0 +1,65 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { compareVersionsDesc } from "./plugin-roots";
+
+/** One discovered plugin file: which plugin owns it, its filename, and its source path. */
+export interface PluginFile {
+  plugin: string;
+  file: string;
+  src: string;
+}
+
+/** Files matching `extension` directly under `dir`, tagged with `plugin`. */
+function filesIn(dir: string, plugin: string, extension: string): PluginFile[] {
+  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: string, plugin: string, subdir: string, extension: string): PluginFile[] {
+  let versions: string[];
+  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.
+ */
+export function listPluginFiles(pluginsRoot: string, subdir: string, extension: string): PluginFile[] {
+  const out: PluginFile[] = [];
+  let entries: string[];
+  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;
+}

package/src/runtime/lifecycle/codex-resync/plugin-roots.ts

@@ -0,0 +1,62 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/** Frozen marketplace name (matches codex-plugins' own `scripts/install-codex.ts`). */
+export const MARKETPLACE = "fusengine-codex";
+
+/** The plugin cache root under a Codex home. */
+export function pluginsCacheRoot(codexHome: string): string {
+  return join(codexHome, "plugins", "cache", MARKETPLACE);
+}
+
+/** Descending semver-ish compare (`"2.1" > "10.0"` stays false — numeric per segment). */
+export function compareVersionsDesc(a: string, b: string): number {
+  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: string, plugin: string): string | undefined {
+  const root = join(pluginsRoot, plugin);
+  if (existsSync(join(root, ".codex-plugin")) || existsSync(join(root, "skills"))) return root;
+  let entries: string[];
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+      .map((e) => e.name);
+  } catch {
+    return undefined;
+  }
+  const versions = entries.sort(compareVersionsDesc);
+  return versions[0] ? join(root, versions[0]) : undefined;
+}
+
+/**
+ * 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).
+ */
+export function buildPluginRoots(pluginsRoot: string): Map<string, string> {
+  const roots = new Map<string, string>();
+  let entries: string[];
+  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;
+}

package/src/runtime/lifecycle/codex-resync/resync.ts

@@ -0,0 +1,45 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { acquireResyncLock, releaseResyncLock } from "./lock";
+import { needsResync, resolveCurrentFingerprint, writeFingerprint } from "./fingerprint";
+import { pluginsCacheRoot } from "./plugin-roots";
+import { listPluginFiles } from "./plugin-files";
+import { materializeAgentFiles } from "./materialize-agents";
+import { symlinkPluginFiles } from "./symlink-commands";
+
+/** The Codex home dir: `$CODEX_HOME`, else `~/.codex`. */
+export function defaultCodexHome(): string {
+  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}).
+ */
+export function resyncCodexAgents(codexHome: string = defaultCodexHome()): void {
+  try {
+    const pluginsRoot = pluginsCacheRoot(codexHome);
+    const current = resolveCurrentFingerprint(pluginsRoot);
+    if (!current) return; // nothing cached — the installer, not this hook, owns first-time setup
+    const promptsDir = join(codexHome, "prompts");
+    if (!needsResync(codexHome, current.value, promptsDir)) return; // unchanged since last apply — no-op
+    if (!acquireResyncLock(codexHome)) return; // another session already holds the resync lock
+    try {
+      materializeAgentFiles(listPluginFiles(pluginsRoot, "agents", ".toml"), join(codexHome, "agents"), current.roots);
+      symlinkPluginFiles(listPluginFiles(pluginsRoot, "commands", ".md"), promptsDir);
+      writeFingerprint(codexHome, current.value);
+    } finally {
+      releaseResyncLock(codexHome); // best-effort, never throws (see lock.ts)
+    }
+  } catch {
+    /* absolute fail-open: a resync must never break SessionStart */
+  }
+}

package/src/runtime/lifecycle/codex-resync/symlink-commands.ts

@@ -0,0 +1,25 @@
+import { mkdirSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { clearManagedDestination } from "./managed-destination";
+import type { PluginFile } from "./plugin-files";
+
+/**
+ * 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`).
+ */
+export function symlinkPluginFiles(files: PluginFile[], destDir: string): void {
+  mkdirSync(destDir, { recursive: true });
+  const seen = new Set<string>();
+  for (const item of files) {
+    if (seen.has(item.file)) continue;
+    seen.add(item.file);
+    clearManagedDestination(join(destDir, `${item.plugin}-${item.file}`)); // legacy naming cleanup
+    const linkPath = join(destDir, item.file);
+    if (clearManagedDestination(linkPath) === "skip") continue;
+    symlinkSync(item.src, linkPath);
+  }
+}

package/src/runtime/lifecycle/dispatch.ts

@@ -0,0 +1,109 @@
+import { sessionStartCore } from "./session-start";
+import { injectRules } from "./inject-rules";
+import { resolveRulesRoot } from "./rules-root";
+import { solidDetectStart } from "./solid-detect";
+import { subagentCacheContext } from "./subagent-cache";
+import { trackAgentMemory } from "./agent-memory";
+import { harvestSubagentTrack } from "../../freshness/evidence-harvest-io";
+import { markSubagentSeen } from "../confirm/confirm-subagent";
+import { teammateIdleContext } from "./teammate-idle-check";
+import { failureLessonContext } from "./failure-lesson";
+import { postCompactContext } from "./post-compact";
+import { saveApexState } from "./pre-compact";
+import { cleanupSession } from "./session-end";
+import { validateRulesLoaded } from "./instructions-loaded";
+import { validateTaskSolid } from "./task-completed";
+import { cartoSessionStart } from "./cartographer/session-start";
+import { dispatchLessons } from "./lessons/dispatch";
+import { withSnapshot } from "./snapshot";
+import { stopCore } from "./stop-core";
+
+/** Which plugin's hooks.json invoked the harness (selects SessionStart behavior). */
+export type PluginScope = "core" | "solid" | "rules" | "carto" | "security" | "changelog" | "aipilot" | "lessons" | "seo" | "memory" | "tailwindcss";
+
+/** Inputs the lifecycle dispatcher needs (clock + roots injected). */
+export interface LifecycleInput {
+  event: string;
+  payload: Record<string, unknown>;
+  cwd: string;
+  scope: PluginScope;
+  now: number;
+  /** Harness target id (defaults to "claude-code" — zero-regression default). */
+  id?: string;
+}
+
+/** SessionStart handler keyed on plugin scope. */
+function sessionStart(input: LifecycleInput): string {
+  if (input.scope === "solid") return solidDetectStart();
+  if (input.scope === "rules") return injectRules(resolveRulesRoot(input.id ?? "claude-code", input.cwd), input.event, input.id ?? "claude-code");
+  if (input.scope === "carto") return cartoSessionStart(input.cwd, input.now);
+  if (input.scope === "lessons") return dispatchLessons("SessionStart", input.payload, input.cwd, input.now, input.id ?? "claude-code");
+  const core = sessionStartCore(input.cwd, undefined, input.now, input.id ?? "claude-code");
+  // core scope only: concatenate the reconciliation snapshot onto the existing
+  // additionalContext (CLAUDE.md + dev-context) — never replaces it, fail-safe.
+  return input.scope === "core" ? withSnapshot(core, input.cwd, import.meta.url) : core;
+}
+
+/**
+ * Route a lifecycle/session/context hook event to its ported handler. Returns
+ * the native stdout when handled, or `null` when the event is not a lifecycle
+ * event (so the caller falls through to the PreToolUse/PostToolUse pipeline).
+ * @param input - The dispatch input.
+ * @returns The native hook stdout, or `null` when unhandled.
+ */
+export function dispatchLifecycle(input: LifecycleInput): string | null {
+  switch (input.event) {
+    case "SessionStart":
+      return sessionStart(input);
+    case "UserPromptSubmit":
+      if (input.scope === "rules") return injectRules(resolveRulesRoot(input.id ?? "claude-code", input.cwd), input.event, input.id ?? "claude-code");
+      if (input.scope === "lessons") return dispatchLessons("UserPromptSubmit", input.payload, input.cwd, input.now, input.id ?? "claude-code");
+      return null;
+    case "SubagentStart":
+      // G0 (CONFIRM-token mechanism, confirm-subagent.ts): mark this session
+      // as having recent sub-agent activity BEFORE the scope branching below,
+      // so it fires regardless of which plugin scope dispatched it. A
+      // monotone max-write timestamp, NOT a counter — see confirm-subagent.ts's
+      // subagentWindowMs doc for why a start/stop counter desyncs unsafely
+      // under this same multi-plugin fan-out.
+      markSubagentSeen(input.payload.session_id, input.now);
+      if (input.scope === "rules") return injectRules(resolveRulesRoot(input.id ?? "claude-code", input.cwd), input.event, input.id ?? "claude-code");
+      if (input.scope === "aipilot") return "";
+      if (input.scope === "lessons") return dispatchLessons("SubagentStart", input.payload, input.cwd, input.now, input.id ?? "claude-code");
+      return subagentCacheContext(input.payload.session_id);
+    case "Stop":
+      if (input.scope === "lessons") return dispatchLessons("Stop", input.payload, input.cwd, input.now, input.id ?? "claude-code");
+      return input.scope === "core" ? stopCore(input.payload, input.cwd, input.now) : null;
+    case "SubagentStop":
+      // G0 counterpart of the SubagentStart branch above — the SAME
+      // monotone max-write, never a decrement (see confirm-subagent.ts).
+      markSubagentSeen(input.payload.session_id, input.now);
+      if (input.scope === "aipilot") return "";
+      // Retroactively harvest the finishing sub-agent's transcript into the session
+      // track BEFORE the reminder — so next turn's freshness gate sees research/
+      // explore evidence even when sidechain PostToolUse hooks never fired
+      // (#43612/#27655/#34692). SubagentStop is main-session-dispatched (reliable).
+      harvestSubagentTrack(input.payload, input.cwd, input.now);
+      return trackAgentMemory(input.payload, undefined, input.now);
+    case "TeammateIdle":
+      return teammateIdleContext(input.payload, input.cwd, undefined, input.now);
+    case "PostToolUseFailure":
+      return failureLessonContext(input.payload, input.cwd, undefined, input.now);
+    case "PostCompact":
+      return input.scope === "core" ? postCompactContext(input.payload, input.cwd, import.meta.url, input.now) : "";
+    case "PreCompact":
+      return saveApexState(input.cwd, input.now, input.id ?? "claude-code");
+    case "SessionEnd":
+      if (input.scope !== "aipilot") cleanupSession(undefined, input.now);
+      return "";
+    case "InstructionsLoaded":
+      validateRulesLoaded(input.payload);
+      return "";
+    case "TaskCompleted":
+      return validateTaskSolid(input.payload);
+    default:
+      return null;
+  }
+}
+
+export { dispatchAipilot, aipilotPostToolUse } from "./aipilot/dispatch-aipilot";

package/src/runtime/lifecycle/failure-lesson.ts

@@ -0,0 +1,51 @@
+/**
+ * @module failure-lesson
+ * PostToolUseFailure handler: keep the failure log, record the failure in the
+ * one-shot metric, and inject the ONE most-specific lesson whose `error:` trigger
+ * matches the failure message — reusing the PreToolUse {@link lessonFor} index and
+ * its cooldown (idempotent under the ~11-process fan-out). Fail-open throughout.
+ *
+ * Claude-Code-only: no equivalent `PostToolUseFailure` hook exists on Codex or
+ * Hermes, so this handler is never reached through those adapters.
+ * @packageDocumentation
+ */
+import { homedir } from "node:os";
+import { contextResponse } from "../../adapters/claude";
+import { lessonFor } from "../../policy/lessons/lesson-gate";
+import { lessonsFileFor } from "./lessons/state";
+import { projectRoot } from "../../util/project-root";
+import { oncePerWindow } from "../inject-dedup";
+import { defaultStateDir } from "../paths";
+import { recordFailure } from "../../tracking/one-shot-failure";
+import { logToolFailure } from "./tool-failure";
+import type { OncePerWindow } from "../../policy/lessons/types";
+
+/** The failure message across the documented `error` field and defensive fallbacks; "" when none. */
+function failureError(data: Record<string, unknown>): string {
+  const raw = data.error ?? data.tool_error ?? data.tool_output;
+  if (typeof raw === "string") return raw;
+  return raw != null ? JSON.stringify(raw) : "";
+}
+
+/**
+ * Handle PostToolUseFailure: log the failure, tally it per tool, and inject the
+ * matching `error:`-triggered lesson as `additionalContext` ("" when none).
+ * @param data - The raw PostToolUseFailure payload (`tool_name`, `error`, `session_id`).
+ * @param cwd - Project root.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @param once - Cooldown gate (injected for tests; defaults to {@link oncePerWindow}).
+ * @returns The native hook stdout, or "" when nothing to inject.
+ */
+export function failureLessonContext(data: Record<string, unknown>, cwd: string, home: string = homedir(), now: number = Date.now(), once: OncePerWindow = oncePerWindow): string {
+  logToolFailure(data, home, now);
+  const tool = typeof data.tool_name === "string" ? data.tool_name : "unknown";
+  const sessionId = typeof data.session_id === "string" ? data.session_id : undefined;
+  try { recordFailure(tool, { now, dir: defaultStateDir(cwd), sessionId }); } catch { /* metric never breaks the hook */ }
+  const errorMsg = failureError(data);
+  if (!errorMsg) return "";
+  // tool="" + empty input isolates matching to the `error:` regex (rank 1),
+  // reusing the PreToolUse gate's index + cooldown — no second lesson engine.
+  const lesson = lessonFor("", {}, { file: lessonsFileFor(projectRoot(cwd)), once, prevError: errorMsg });
+  return lesson?.reason ? contextResponse("PostToolUseFailure", lesson.reason) : "";
+}

package/src/runtime/lifecycle/index.ts

@@ -0,0 +1,34 @@
+export * from "./session-start";
+export * from "./inject-rules";
+export * from "./solid-detect";
+export * from "./check-file-size";
+export * from "./validate-solid";
+export * from "./validate-tailwind";
+export * from "./subagent-cache";
+export * from "./agent-memory";
+export * from "./teammate-idle";
+export * from "./tool-failure";
+export * from "./pre-compact";
+export * from "./session-end";
+export * from "./instructions-loaded";
+export * from "./track-changes";
+export * from "./post-edit-ts";
+export * from "./dispatch";
+export * from "./post-tracking";
+export * from "./changelog-research";
+export * from "./cartographer/session-start";
+export * from "./cartographer/project-map";
+export * from "./cartographer/track-enrichment";
+export * from "./cartographer/write-tree";
+export * from "./cartographer/merge";
+export * from "./cartographer/fs-util";
+export * from "./security/check-skill";
+export * from "./security/track-skill-read";
+export * from "./security/track-mcp";
+export * from "./security/skill-state";
+export * from "./lessons/dispatch";
+export * from "./lessons/state";
+export * from "./memory/dispatch";
+export * from "./seo/post-tool-use";
+export * from "./cartographer/ecosystem-map";
+export * from "./cartographer/write-plugin-map";

package/src/runtime/lifecycle/inject-rules.ts

@@ -0,0 +1,50 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { renderInform } from "../inform";
+import { rulesInAgentsMd } from "./kimi-rules-native";
+
+/** Read & concatenate all `*.md` files (sorted) under `rulesDir`. */
+export function readRules(rulesDir: string): string {
+  if (!existsSync(rulesDir)) return "";
+  let names: string[];
+  try {
+    names = readdirSync(rulesDir).filter((n) => n.endsWith(".md")).sort();
+  } catch {
+    return "";
+  }
+  const parts: string[] = [];
+  for (const name of names) {
+    try {
+      parts.push(readFileSync(join(rulesDir, name), "utf-8"));
+    } catch {
+      /* skip unreadable rule file */
+    }
+  }
+  return parts.join("\n\n");
+}
+
+/**
+ * Build the rules injection for claude-rules (SessionStart, UserPromptSubmit,
+ * SubagentStart): read `<pluginRoot>/rules/*.md` and emit via {@link renderInform}
+ * (Claude-shaped `additionalContext`, or raw text for kimi). Tags the output
+ * with the *actual* `hookEventName` — the spec requires it to match the firing
+ * event (a hardcoded "SessionStart" is non-conforming and may be dropped on
+ * UserPromptSubmit/SubagentStart).
+ *
+ * On kimi's `UserPromptSubmit` specifically, when the corpus is already fenced
+ * inside `<kimiHome>/AGENTS.md` (native load, {@link rulesInAgentsMd}), only the
+ * notice is emitted — the re-injected corpus would otherwise dump into the
+ * user's terminal on every single prompt for no model-context benefit.
+ * `SessionStart`/`SubagentStart` always keep the full corpus (session bootstrap
+ * / sub-agent contexts need it regardless of the native AGENTS.md load).
+ * @param pluginRoot - `CLAUDE_PLUGIN_ROOT` of the claude-rules plugin.
+ * @param event - The firing hook event name (e.g. "SessionStart").
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export function injectRules(pluginRoot: string, event: string, id: string = "claude-code"): string {
+  const content = readRules(join(pluginRoot, "rules"));
+  if (!content) return "";
+  if (id === "kimi" && event === "UserPromptSubmit" && rulesInAgentsMd()) return "rules 00-08 injected";
+  return renderInform(id, event, content, "rules 00-08 injected");
+}

package/src/runtime/lifecycle/instructions-loaded.ts

@@ -0,0 +1,22 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Handle InstructionsLoaded: append `load_reason | memory_type | file_path` to
+ * the per-session debug log. Ports `instructions-loaded/validate-rules-loaded.py`.
+ * No stdout (logging only; InstructionsLoaded has no decision control).
+ * @param data - The raw hook payload.
+ * @param home - Home dir (defaults to `~`).
+ */
+export function validateRulesLoaded(data: Record<string, unknown>, home: string = homedir()): void {
+  const filePath = String(data.file_path ?? "");
+  const loadReason = String(data.load_reason ?? "");
+  const memoryType = String(data.memory_type ?? "");
+  const sessionId = String(data.session_id ?? "unknown");
+  const dir = join(home, ".claude", "logs", "instructions-loaded");
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, `${sessionId}.log`), `${loadReason} | ${memoryType} | ${filePath}\n`, "utf-8");
+  } catch { /* best effort */ }
+}

package/src/runtime/lifecycle/kimi-rules-native.ts

@@ -0,0 +1,44 @@
+/**
+ * Guard for the kimi notice-only rules injection. Kimi Code CLI has no
+ * model-only hook channel (`src/runtime/inform.ts`) — every `UserPromptSubmit`
+ * stdout is BOTH appended to the model's context AND rendered raw in the
+ * user's terminal. `injectRules` (`inject-rules.ts`) normally re-injects the
+ * full ~18 Ko rules corpus on every prompt; when the installer has already
+ * merged that same corpus into `<kimiHome>/AGENTS.md` — which Kimi loads
+ * natively at session start via its documented `${agents_md}` mechanism,
+ * independent of hooks — the re-injection is pure noise the user has to
+ * scroll past. Confirmed present, fenced, in the local install:
+ * `~/.kimi-code/AGENTS.md:87` / `:335`.
+ *
+ * Fail-safe semantics: fences absent, file absent, or any read error ⟹
+ * `false` — the caller then falls back to the full corpus. A dump is
+ * verbose but never wrong; a false `true` would silently drop the rules.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { harnessHome } from "../../config/home-dir";
+
+/** Opening fence the fusengine installer writes around the merged corpus. */
+const FENCE_START = "<!-- fusengine:kimi-rules:start -->";
+
+/** Closing fence the fusengine installer writes around the merged corpus. */
+const FENCE_END = "<!-- fusengine:kimi-rules:end -->";
+
+/**
+ * Check whether the kimi rules corpus is already present, fenced, inside
+ * `<kimiHome>/AGENTS.md`.
+ * @param home - Kimi home dir override (defaults to `harnessHome("kimi")`,
+ * which honors `KIMI_CODE_HOME`).
+ * @returns `true` only when both fences are found in a readable file.
+ */
+export function rulesInAgentsMd(home?: string): boolean {
+  try {
+    const kimiHome = home ?? harnessHome("kimi");
+    const agentsMd = join(kimiHome, "AGENTS.md");
+    if (!existsSync(agentsMd)) return false;
+    const content = readFileSync(agentsMd, "utf-8");
+    return content.includes(FENCE_START) && content.includes(FENCE_END);
+  } catch {
+    return false;
+  }
+}