@fusengine/harness 0.1.89 → 0.1.91

package/src/runtime/lifecycle/changelog-research.ts

@@ -0,0 +1,43 @@
+/**
+ * Changelog research tracker (PostToolUse exa/WebFetch/WebSearch). Ports
+ * `track-watch-research.py`: logs research queries to
+ * `~/.claude/logs/00-changelog/<utc-date>-research.json`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { claudeHome } from "../home-state";
+import { isoUtc, todayUtc } from "./security/skill-state";
+
+/** A recorded changelog research query. */
+interface ChangelogQuery {
+  timestamp: string;
+  tool: string;
+  query: string;
+}
+
+/**
+ * Append an exa/WebFetch/WebSearch query to today's changelog research log.
+ * No-op for other tools. No stdout (errors swallowed).
+ * @param tool - The tool name.
+ * @param input - The tool input (query/url/prompt).
+ * @param now - Clock.
+ * @param home - Home dir.
+ */
+export function trackWatchResearch(tool: string, input: Record<string, unknown>, now: number = Date.now(), home: string = homedir()): void {
+  if (!tool.includes("exa") && !tool.includes("WebFetch") && !tool.includes("WebSearch")) return;
+  const query = String(input.query ?? input.url ?? input.prompt ?? "");
+  const dir = join(claudeHome(home), "logs", "00-changelog");
+  try {
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${todayUtc(now)}-research.json`);
+    let state: { queries: ChangelogQuery[] } = { queries: [] };
+    if (existsSync(path)) {
+      try {
+        state = JSON.parse(readFileSync(path, "utf-8")) as { queries: ChangelogQuery[] };
+      } catch { state = { queries: [] }; }
+    }
+    state.queries.push({ timestamp: isoUtc(now), tool, query });
+    writeFileSync(path, JSON.stringify(state, null, 2), "utf-8");
+  } catch { /* best effort */ }
+}

package/src/runtime/lifecycle/check-file-size.ts

@@ -0,0 +1,61 @@
+/**
+ * PostToolUse (matcher "Write|Edit") for the solid scope: warn when a file
+ * exceeds the adaptive `SOLID_FILE_LIMIT` (set by `solidDetectStart` at
+ * SessionStart, keyed off the detected project type). Ports `check-file-size.py`.
+ * Non-blocking (`additionalContext`), unlike the fixed-ceiling core-guards gate.
+ */
+import { extname } from "node:path";
+import { readText, pathExists } from "../../util/runtime-io";
+import { contextResponse } from "../../adapters/claude";
+import { parseEnvInt } from "../../config/env";
+
+/** Per-language "blank or comment" line pattern (parity `count_loc`'s `code_comment` map). */
+const COMMENT_RE: Record<string, RegExp> = {
+  ts: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  tsx: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  js: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  jsx: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  go: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  rs: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  java: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  swift: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  php: /^\s*$|^\s*\/\/|^\s*#|^\s*\/\*|^\s*\*/,
+  py: /^\s*$|^\s*#|^\s*"""|^\s*'''/,
+};
+
+/** Count lines of code excluding comments/blanks for `filePath`'s extension (raw length when unmapped). */
+export function countLoc(filePath: string, content: string): number {
+  const pattern = COMMENT_RE[extname(filePath).slice(1)];
+  const lines = content.split("\n");
+  return pattern ? lines.filter((l) => !pattern.test(l)).length : lines.length;
+}
+
+/**
+ * Warn when a written/edited file exceeds `SOLID_FILE_LIMIT` (default 100).
+ * Inert when `SOLID_PROJECT_TYPE` is absent/"unknown" (parity: the Python hook
+ * no-ops outside a detected project).
+ * @param tool - The tool name (only "Write"/"Edit" are checked).
+ * @param filePath - The written file's absolute path.
+ * @param env - Environment (defaults to `process.env`).
+ * @returns The PostToolUse `additionalContext` response, or `""` when clean/inert.
+ */
+export function checkFileSize(tool: string, filePath: string, env: Record<string, string | undefined> = process.env): string {
+  const ptype = env.SOLID_PROJECT_TYPE ?? "";
+  if (!ptype || ptype === "unknown") return "";
+  if (tool !== "Write" && tool !== "Edit") return "";
+  if (!filePath || !pathExists(filePath)) return "";
+
+  let content: string;
+  try {
+    content = readText(filePath);
+  } catch {
+    return "";
+  }
+
+  const limit = parseEnvInt(env.SOLID_FILE_LIMIT, 100);
+  const loc = countLoc(filePath, content);
+  if (loc <= limit) return "";
+
+  const name = filePath.split("/").pop() ?? filePath;
+  return contextResponse("PostToolUse", `SOLID: ${name} has ${loc} lines (limit: ${limit}). Consider splitting into smaller modules.`);
+}

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

@@ -0,0 +1,63 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { atomicWrite } from "../../../util/json-io";
+import { pathExists } from "../../../util/runtime-io";
+import { buildPluginRoots } from "./plugin-roots";
+
+/** Where the last-applied plugin-cache fingerprint is persisted. */
+function manifestPath(codexHome: string): string {
+  return join(codexHome, "fusengine", "state", "agents-cache-fingerprint.json");
+}
+
+/** sha256 over sorted "plugin=root" pairs — stable while cache resolution is unchanged. */
+export function fingerprint(roots: Map<string, string>): string {
+  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"). */
+export function readFingerprint(codexHome: string): string | undefined {
+  try {
+    const raw = JSON.parse(readFileSync(manifestPath(codexHome), "utf8")) as { fingerprint?: string };
+    return raw.fingerprint;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Persist the applied fingerprint atomically (tmp+rename via {@link atomicWrite}). */
+export function writeFingerprint(codexHome: string, value: string): void {
+  atomicWrite(manifestPath(codexHome), JSON.stringify({ fingerprint: value }));
+}
+
+/** True when a direct symlink child of `dir` points at a now-missing target. */
+export function hasDanglingSymlink(dir: string): boolean {
+  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 { /* best-effort */ }
+  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.
+ */
+export function resolveCurrentFingerprint(pluginsRoot: string): { roots: Map<string, string>; value: string } | undefined {
+  if (!pathExists(pluginsRoot)) return undefined;
+  const roots = buildPluginRoots(pluginsRoot);
+  if (roots.size === 0) return undefined;
+  return { roots, value: fingerprint(roots) };
+}
+
+/** True when a resync is due: fingerprint changed/never recorded, or a command symlink is dangling. */
+export function needsResync(codexHome: string, currentValue: string, promptsDir: string): boolean {
+  return currentValue !== readFingerprint(codexHome) || hasDanglingSymlink(promptsDir);
+}

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";