@fusengine/harness 0.1.89 → 0.1.91

package/src/runtime/lifecycle/aipilot/analytics.ts

@@ -0,0 +1,99 @@
+/**
+ * Cache analytics for the ai-pilot scope: append hit/miss events to
+ * `sessions.jsonl` and aggregate them into `summary.json` on SessionEnd.
+ * Ports `cache-analytics-save.ts` + the `logCacheEvent` helper.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { readJsonFile, writeJsonFile } from "../../../util/json-io";
+import { readText, writeText, pathExists } from "../../../util/runtime-io";
+import { cacheBaseDir } from "./cache-base";
+
+const TOKEN_WEIGHTS: Record<string, number> = { explore: 15000, doc: 10000, lessons: 3000, tests: 5000 };
+const CATEGORIES = ["explore", "doc", "lessons", "tests"] as const;
+
+/** A raw analytics event line in `sessions.jsonl`. */
+export interface SessionEntry { ts: string; type: string; action: string; session?: string }
+
+/** Aggregated cache analytics persisted to `summary.json`. */
+export interface Summary {
+  updated: string;
+  total_sessions: number;
+  cache_hits: Record<string, number>;
+  cache_misses: Record<string, number>;
+  hit_rates: Record<string, string>;
+  estimated_tokens_saved: number;
+}
+
+/** Append a single cache event to `analytics/sessions.jsonl` (best effort). */
+export function logCacheEvent(type: string, action: string, projHash: string, extra: Record<string, unknown> = {}, home: string = homedir()): void {
+  try {
+    const dir = join(cacheBaseDir(home), "analytics");
+    mkdirSync(dir, { recursive: true });
+    const entry = { ts: new Date().toISOString(), session: String(Math.floor(Date.now() / 1000)), type, action, project_hash: projHash, ...extra };
+    appendFileSync(join(dir, "sessions.jsonl"), JSON.stringify(entry) + "\n");
+  } catch { /* best effort */ }
+}
+
+/** Count entries matching a `type`+`action`. */
+function countBy(entries: SessionEntry[], type: string, action: string): number {
+  return entries.filter((e) => e.type === type && e.action === action).length;
+}
+
+/** Format a hit-rate percentage string. */
+function hitRate(hits: number, misses: number): string {
+  const total = hits + misses;
+  return total === 0 ? "0%" : `${Math.floor((hits * 100) / total)}%`;
+}
+
+/** Parse the JSONL session log into typed entries. */
+function parseEntries(raw: string): SessionEntry[] {
+  return raw.split("\n").filter(Boolean)
+    .map((line) => { try { return JSON.parse(line) as SessionEntry; } catch { return null; } })
+    .filter((e): e is SessionEntry => e !== null);
+}
+
+/**
+ * Aggregate `sessions.jsonl` into `summary.json` and prune entries > 30 days.
+ * Ports `cache-analytics-save.ts`. SessionEnd hook output is ignored by Claude,
+ * so this returns nothing — it is a pure side-effect.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ */
+export async function cacheAnalyticsSave(home: string = homedir(), now: number = Date.now()): Promise<void> {
+  const dir = join(cacheBaseDir(home), "analytics");
+  const sessionsFile = join(dir, "sessions.jsonl");
+  if (!pathExists(sessionsFile)) return;
+  const raw = readText(sessionsFile);
+  if (!raw.trim()) return;
+  const entries = parseEntries(raw);
+  if (entries.length === 0) return;
+
+  const hits: Record<string, number> = {};
+  const misses: Record<string, number> = {};
+  for (const cat of CATEGORIES) {
+    hits[cat] = countBy(entries, cat, "hit") + (cat === "doc" ? countBy(entries, cat, "blocked") : 0);
+    misses[cat] = countBy(entries, cat, "miss");
+  }
+  const tokensSaved = CATEGORIES.reduce((sum, c) => sum + (hits[c] ?? 0) * (TOKEN_WEIGHTS[c] ?? 0), 0);
+  const sessionCount = new Set(entries.map((e) => e.session).filter(Boolean)).size;
+
+  const old = await readJsonFile<Summary>(join(dir, "summary.json"));
+  const merged: Summary = {
+    updated: new Date(now).toISOString(),
+    total_sessions: (old?.total_sessions ?? 0) + sessionCount,
+    cache_hits: {}, cache_misses: {}, hit_rates: {},
+    estimated_tokens_saved: (old?.estimated_tokens_saved ?? 0) + tokensSaved,
+  };
+  for (const cat of CATEGORIES) {
+    merged.cache_hits[cat] = (old?.cache_hits?.[cat] ?? 0) + (hits[cat] ?? 0);
+    merged.cache_misses[cat] = (old?.cache_misses?.[cat] ?? 0) + (misses[cat] ?? 0);
+    merged.hit_rates[cat] = hitRate(merged.cache_hits[cat] ?? 0, merged.cache_misses[cat] ?? 0);
+  }
+  await writeJsonFile(join(dir, "summary.json"), merged, true);
+
+  const cutoff = new Date(now - 30 * 86_400_000).toISOString();
+  const kept = entries.filter((e) => e.ts >= cutoff);
+  writeText(sessionsFile, kept.map((e) => JSON.stringify(e)).join("\n") + "\n");
+}

package/src/runtime/lifecycle/aipilot/apex-task-store.ts

@@ -0,0 +1,61 @@
+/**
+ * APEX `task.json` mutation helpers + a directory-based lock for the ai-pilot
+ * scope. Ported from the ai-pilot plugin's `apex/state.ts` + `apex/task-helpers.ts`
+ * (now removed).
+ */
+import { mkdir, rmdir } from "node:fs/promises";
+import { readJsonFile, writeJsonFile } from "../../../util/json-io";
+import { sleep } from "../../../util/runtime-io";
+import type { ApexTaskFile } from "./types";
+
+/**
+ * Acquire a directory-based lock with a timeout.
+ * @param lockDir - Path to the lock directory.
+ * @param timeoutMs - Max wait in ms (default 5000).
+ * @returns A release function, or null if acquisition timed out.
+ */
+export async function acquireLock(lockDir: string, timeoutMs = 5000): Promise<(() => Promise<void>) | null> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      await mkdir(lockDir, { recursive: false });
+      return async () => { try { await rmdir(lockDir); } catch { /* noop */ } };
+    } catch { await sleep(100); }
+  }
+  return null;
+}
+
+/** Add a new task to `task.json`. */
+export async function taskCreate(file: string, id: string, subject: string, desc: string): Promise<void> {
+  const data = await readJsonFile<ApexTaskFile>(file);
+  if (!data) return;
+  data.tasks[id] = {
+    subject, description: desc, status: "pending", phase: "pending",
+    created_at: new Date().toISOString(), doc_consulted: {}, files_modified: [], blockedBy: [],
+  };
+  await writeJsonFile(file, data);
+}
+
+/** Mark a task as in_progress in `task.json`. */
+export async function taskStart(file: string, id: string, subject?: string, desc?: string, blocked?: string): Promise<void> {
+  const data = await readJsonFile<ApexTaskFile>(file);
+  if (!data) return;
+  if (!data.tasks[id]) {
+    data.tasks[id] = { subject: "", description: "", status: "in_progress", phase: "analyze", doc_consulted: {}, files_modified: [] };
+  }
+  data.current_task = id;
+  const task = data.tasks[id];
+  Object.assign(task, { status: "in_progress", phase: "analyze", started_at: new Date().toISOString() });
+  if (subject) task.subject = subject;
+  if (desc) task.description = desc;
+  if (blocked) task.blockedBy = blocked.split(",");
+  await writeJsonFile(file, data);
+}
+
+/** Mark a task as completed in `task.json`. */
+export async function taskComplete(file: string, id: string): Promise<void> {
+  const data = await readJsonFile<ApexTaskFile>(file);
+  if (!data?.tasks[id]) return;
+  Object.assign(data.tasks[id], { status: "completed", phase: "completed", completed_at: new Date().toISOString() });
+  await writeJsonFile(file, data);
+}

package/src/runtime/lifecycle/aipilot/cache-base.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared cache-path + age helpers for the ai-pilot scope.
+ * Reuses the harness home-state (`fusengineCache`) so the ai-pilot caches live
+ * under the same `~/.fuse-harness/cache` tree as the core MCP cache — no
+ * second cache layer.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { fusengineCache } from "../../home-state";
+import { readText } from "../../../util/runtime-io";
+
+/** Doc cache freshness window, in seconds (7 days) — shared by inject-doc.ts (serves the cache) and doc-cache-gate.ts (denies a redundant re-query). */
+export const DOC_CACHE_TTL_SECONDS = 604_800;
+
+/** 16-char hex SHA-256 of `text` (project hash / doc topic key). */
+export function hashText16(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+/** 16-char project hash from its absolute path. */
+export function projectHash(projectPath: string): string {
+  return hashText16(projectPath);
+}
+
+/** `~/.fuse-harness/cache` base dir (shared with the core MCP cache). */
+export function cacheBaseDir(home: string = homedir()): string {
+  return fusengineCache(home);
+}
+
+/** Per-type, per-project cache dir: `cache/<type>/<projectHash>`. */
+export function cacheDirFor(type: string, projectPath: string, home: string = homedir()): string {
+  return join(cacheBaseDir(home), type, projectHash(projectPath));
+}
+
+/** Age in seconds from an ISO timestamp (now - ts). */
+export function cacheAge(ts: string, now: number = Date.now()): number {
+  return Math.floor((now - new Date(ts).getTime()) / 1000);
+}
+
+/** Full SHA-256 hex checksum of a file's text; "" when unreadable. */
+export async function fileChecksum(path: string): Promise<string> {
+  try {
+    return createHash("sha256").update(readText(path)).digest("hex");
+  } catch {
+    return "";
+  }
+}

package/src/runtime/lifecycle/aipilot/cache-doc.ts

@@ -0,0 +1,100 @@
+/**
+ * SubagentStop (matcher "research-expert") for the ai-pilot scope: extract the
+ * agent's synthesis text from the transcript and cache it as documentation.
+ * Ports `cache-doc-from-transcript.ts`. SubagentStop output here is a pure
+ * side-effect (no stdout needed).
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readJsonFile, writeJsonFile } from "../../../util/json-io";
+import { readText, writeText, pathExists, sleep } from "../../../util/runtime-io";
+import { hashText16, cacheDirFor } from "./cache-base";
+import { transcriptFilePaths, projectRootFromPaths } from "./transcript";
+import { canonicalizeMcpToolName } from "../../mcp-tool-name";
+import type { CacheEntry, CacheIndex } from "./types";
+
+const TOOL_PATTERN = /context7__query-docs|exa__get_code_context|exa__web_search/;
+const MAX_DOC_SIZE = 20480;
+const MIN_TEXT_SIZE = 200;
+const MAX_DOCS = 15;
+const RETRY_DELAYS = [500, 1000, 2000];
+
+/**
+ * Extract the longest assistant synthesis + queried library ids from a transcript.
+ * @param id - Harness adapter id, used to canonicalize `block.name` (Codex-mangled
+ *   underscore tool names) before the {@link TOOL_PATTERN} match — see
+ *   {@link cacheDocFromTranscript} for why this is a defensive, unconfirmed-case cover.
+ */
+async function extractSynthesis(path: string, id: string): Promise<{ text: string; libraries: string[] }> {
+  const lines = readText(path).split("\n").filter(Boolean);
+  const libraries: string[] = [];
+  let synthesis = "";
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line) as { type?: string; role?: string; message?: { content?: unknown } };
+      const role = entry?.type ?? entry?.role;
+      const contents = entry?.message?.content;
+      if (!Array.isArray(contents)) continue;
+      for (const block of contents) {
+        if (block.type === "tool_use" && TOOL_PATTERN.test(canonicalizeMcpToolName(id, block.name ?? ""))) {
+          const lib = block.input?.libraryId ?? block.input?.query ?? "";
+          if (lib && !libraries.includes(lib)) libraries.push(lib);
+        }
+        if (role === "assistant" && block.type === "text" && typeof block.text === "string" && block.text.length > synthesis.length) {
+          synthesis = block.text;
+        }
+      }
+    } catch { /* skip malformed */ }
+  }
+  return { text: synthesis, libraries };
+}
+
+/**
+ * SubagentStop research-expert: cache the synthesis text from the transcript.
+ * @param transcript - Path to the agent JSONL transcript.
+ * @param cwd - Fallback project root.
+ * @param home - Home dir (defaults to `~`).
+ * @param id - Harness adapter id (defaults to "claude-code"). On `"codex"`,
+ *   every `tool_use.name` read from the transcript is canonicalized before the
+ *   {@link TOOL_PATTERN} match, defensively covering the SAME Codex-mangled
+ *   underscore form as `doc-cache-gate.ts`'s `docCacheGate`. UNLIKE that gate,
+ *   this is NOT a confirmed-reproduced bug: the proof that Codex emits the
+ *   underscore form (`sanitize_responses_api_tool_name()`, openai/codex#14605,
+ *   `SCENARIO_DASH_TOOL` in #18385) is about the live PreToolUse HOOK payload,
+ *   never observed here against transcript `tool_use.name` content. The
+ *   canonicalization is a no-op when the transcript already carries the dash
+ *   form (idempotence proven in `test/mcp-tool-name.test.ts`, test 2), so this
+ *   costs nothing if the hypothesis turns out false.
+ */
+export async function cacheDocFromTranscript(transcript: string | undefined, cwd: string, home: string = homedir(), id: string = "claude-code"): Promise<void> {
+  if (!transcript || !pathExists(transcript)) return;
+  const allPaths = await transcriptFilePaths(transcript);
+  const projPath = projectRootFromPaths(allPaths) ?? process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const cacheDir = cacheDirFor("doc", projPath, home);
+  const docsDir = join(cacheDir, "docs");
+
+  let result = await extractSynthesis(transcript, id);
+  for (const delay of RETRY_DELAYS) {
+    if (result.text.length >= MIN_TEXT_SIZE && result.libraries.length > 0) break;
+    await sleep(delay);
+    result = await extractSynthesis(transcript, id);
+  }
+  const { text, libraries } = result;
+  if (text.length < MIN_TEXT_SIZE || libraries.length === 0) return;
+
+  const indexFile = join(cacheDir, "index.json");
+  const index = (await readJsonFile<CacheIndex>(indexFile)) ?? { project: projPath, docs: [] };
+  const timestamp = new Date().toISOString();
+  const content = text.slice(0, MAX_DOC_SIZE);
+  const topic = libraries.join(", ");
+  const docHash = hashText16(topic);
+  writeText(join(docsDir, `${docHash}.md`), content);
+
+  const sizeKb = Math.floor(content.length / 1024);
+  for (const lib of libraries) {
+    index.docs = index.docs.filter((d: CacheEntry) => d.library !== lib);
+    index.docs.push({ hash: docHash, library: lib, topic, timestamp, size_kb: sizeKb });
+  }
+  if (index.docs.length > MAX_DOCS) index.docs = index.docs.slice(-MAX_DOCS);
+  await writeJsonFile(indexFile, index, true);
+}

package/src/runtime/lifecycle/aipilot/cache-lessons.ts

@@ -0,0 +1,58 @@
+/**
+ * SubagentStop (matcher "sniper") for the ai-pilot scope: capture error
+ * patterns + corrected code from the sniper transcript as lessons. Ports
+ * `cache-sniper-lessons.ts`, including the high-frequency promotion to the
+ * global stack cache (`promoteGlobalLessons`). Pure side-effect.
+ */
+import { homedir } from "node:os";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonFile } from "../../../util/json-io";
+import { pathExists } from "../../../util/runtime-io";
+import { cacheDirFor, projectHash } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import { transcriptEdits, transcriptReport, projectRootFromPaths } from "./transcript";
+import { categorizeEdit } from "./lessons";
+import { detectStack } from "./source-scan";
+import { promoteGlobalLessons } from "./promote-global-lessons";
+import type { LessonEntry } from "./types";
+
+/**
+ * SubagentStop sniper: extract lessons from the transcript and persist them.
+ * @param transcript - Path to the agent JSONL transcript.
+ * @param cwd - Fallback project root.
+ * @param home - Home dir (defaults to `~`).
+ */
+export async function cacheSniperLessons(transcript: string | undefined, cwd: string, home: string = homedir()): Promise<void> {
+  if (!transcript || !pathExists(transcript)) return;
+  const edits = await transcriptEdits(transcript);
+  if (edits.length === 0) return;
+
+  const editPaths = edits.map((e) => e.file);
+  const projectPath = projectRootFromPaths(editPaths) ?? process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const pHash = projectHash(projectPath);
+  const cacheDir = cacheDirFor("lessons", projectPath, home);
+  mkdirSync(cacheDir, { recursive: true });
+
+  const report = await transcriptReport(transcript);
+  const timestamp = new Date().toISOString();
+  const errors: LessonEntry[] = edits.map((edit) => {
+    const basename = edit.file.split("/").pop() ?? edit.file;
+    const descLine = report.split("\n").find((l) => l.toLowerCase().includes(basename.toLowerCase()));
+    const errorType = categorizeEdit(edit);
+    return {
+      error_type: errorType,
+      pattern: descLine ?? `Code correction in ${basename}`,
+      fix: `Fix ${errorType} in ${basename}`,
+      count: 1,
+      last_seen: timestamp,
+      files: [edit.file],
+      code: { line: (edit.newStr ?? "").split("\n").filter(Boolean).slice(0, 10) },
+    };
+  });
+
+  const safeName = timestamp.replace(/:/g, "-");
+  await writeJsonFile(join(cacheDir, `${safeName}.json`), { project: projectPath, timestamp, errors }, true);
+  await promoteGlobalLessons(cacheDir, detectStack(projectPath), pHash, home);
+  logCacheEvent("lessons", "hit", pHash, { count: edits.length }, home);
+}

package/src/runtime/lifecycle/aipilot/cache-test.ts

@@ -0,0 +1,70 @@
+/**
+ * SubagentStop (matcher "sniper") for the ai-pilot scope: extract linter
+ * results from the transcript and cache per-file checksums. Ports
+ * `cache-test-results.ts`. Pure side-effect.
+ */
+import { homedir } from "node:os";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonFile, writeJsonFile } from "../../../util/json-io";
+import { readText, pathExists } from "../../../util/runtime-io";
+import { cacheDirFor, projectHash, fileChecksum } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import { transcriptFilePaths, projectRootFromPaths } from "./transcript";
+import { scanSourceFiles } from "./source-scan";
+import type { TestCache, TestResult } from "./types";
+
+/** Extract linter-related command/output text from a JSONL transcript. */
+async function extractLinterOutput(path: string): Promise<string> {
+  const text = readText(path);
+  const outputs: string[] = [];
+  for (const line of text.split("\n").filter(Boolean)) {
+    try {
+      const content = (JSON.parse(line) as { message?: { content?: unknown } })?.message?.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (block.type === "tool_use" && block.name === "Bash") {
+          const cmd = block.input?.command ?? "";
+          if (/eslint|tsc|biome|npx.*lint/i.test(cmd)) outputs.push(cmd);
+        }
+        if (block.type === "tool_result" || block.type === "text") outputs.push(block.text ?? block.content ?? "");
+      }
+    } catch { /* skip malformed */ }
+  }
+  return outputs.join("\n");
+}
+
+/**
+ * SubagentStop sniper: cache linter results per-file with checksums.
+ * @param transcript - Path to the agent JSONL transcript.
+ * @param cwd - Fallback project root.
+ * @param home - Home dir (defaults to `~`).
+ */
+export async function cacheTestResults(transcript: string | undefined, cwd: string, home: string = homedir()): Promise<void> {
+  if (!transcript || !pathExists(transcript)) return;
+  const allPaths = await transcriptFilePaths(transcript);
+  const projectPath = projectRootFromPaths(allPaths) ?? process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const pHash = projectHash(projectPath);
+  const cacheDir = cacheDirFor("tests", projectPath, home);
+  mkdirSync(cacheDir, { recursive: true });
+  const resultsPath = join(cacheDir, "results.json");
+
+  const linterOutput = await extractLinterOutput(transcript);
+  if (!linterOutput) return;
+  const srcFiles = await scanSourceFiles(projectPath);
+  if (srcFiles.length === 0) return;
+
+  const existing = (await readJsonFile<TestCache>(resultsPath)) ?? { timestamp: "", files: {} };
+  const timestamp = new Date().toISOString();
+  const newFiles: Record<string, TestResult> = {};
+  for (const filepath of srcFiles) {
+    const relPath = filepath.replace(`${projectPath}/`, "");
+    const checksum = (await fileChecksum(filepath)).slice(0, 16);
+    if (!checksum) continue;
+    const basename = filepath.split("/").pop() ?? "";
+    const hasError = linterOutput.includes(basename) && linterOutput.includes("error");
+    newFiles[relPath] = { checksum, eslint: hasError ? "fail" : "pass", tsc: "pass", last_tested: timestamp };
+  }
+  await writeJsonFile(resultsPath, { timestamp, files: { ...existing.files, ...newFiles } }, true);
+  logCacheEvent("tests", "hit", pHash, { count: Object.keys(newFiles).length }, home);
+}

package/src/runtime/lifecycle/aipilot/curate-lessons.ts

@@ -0,0 +1,64 @@
+/**
+ * Stage-0 mechanical, LLM-free dedup of MEMORY/LESSON.md bullets + cap→archive
+ * orchestration. Strict-dedup near-identical bullets (keep newest, `[TRIGGERS …]`
+ * preserved), then hand the deduped set to lesson-archive's cap split. Returns the
+ * rewritten LESSON.md content, the archive block to move out, and a human report.
+ * Pure: all file I/O (archive-first, fail-safe) lives in the dispatch caller.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { CAP, DAY_MS, STALE_DAYS, TRIG, type Block, citedPaths, jaccard, parse } from "./lesson-parse";
+import { formatArchive, splitAtCap } from "./lesson-archive";
+
+const SIM_THRESHOLD = 0.8;
+const MIN_TOKENS = 4;
+
+/** Report lines for bullets older than STALE_DAYS whose only cited path is gone. */
+function staleReport(blocks: Block[], now: number, root: string): string[] {
+  const cutoff = now - STALE_DAYS * DAY_MS;
+  return blocks.flatMap((b) => {
+    if (!(b.ts <= cutoff)) return [];
+    const paths = citedPaths(b.raw.join(" "));
+    if (paths.length === 0 || paths.some((p) => existsSync(join(root, p)))) return [];
+    return [`[STALE?] ${(b.raw[0] ?? "").slice(0, 90)} — missing path(s): ${paths.join(", ")}`];
+  });
+}
+
+/** Strict-dedup: keep the newest of each near-identical pair (TRIGGERS carried over). Returns kept blocks + merge report lines. */
+function dedup(blocks: Block[]): { kept: Block[]; fused: string[] } {
+  const kept: Block[] = [];
+  const fused: string[] = [];
+  for (const b of blocks) {
+    const hit = b.tokens.size >= MIN_TOKENS ? kept.find((k) => k.tokens.size >= MIN_TOKENS && jaccard(k.tokens, b.tokens) >= SIM_THRESHOLD) : undefined;
+    if (!hit) { kept.push(b); continue; }
+    const [win, drop] = (b.ts > hit.ts || Number.isNaN(hit.ts)) ? [b, hit] : [hit, b];
+    if (win !== hit) kept[kept.indexOf(hit)] = win;
+    if (!win.raw.some((l) => TRIG.test(l.trim()))) { const t = drop.raw.find((l) => TRIG.test(l.trim())); if (t) win.raw.push(t); }
+    fused.push(`merged: kept ${(win.raw[0] ?? "").slice(0, 60)} · dropped ${(drop.raw[0] ?? "").slice(0, 60)}`);
+  }
+  return { kept, fused };
+}
+
+/** Result of a curation pass: rewritten LESSON.md, the block to archive out, a report. */
+export interface CurateResult { content: string; archive: string; report: string; }
+
+/**
+ * Dedup LESSON.md bullets, then archive the oldest excess over CAP (via
+ * lesson-archive). `content` is byte-identical to the input when nothing is
+ * deduped or archived. The `archive` block (possibly "") is what the caller must
+ * PREPEND to LESSON-archive.md, archive-first, before writing `content`.
+ * @param content - Raw LESSON.md text.
+ * @param now - Clock (ms) for stale/archival windows.
+ * @param root - Project root, for resolving cited paths in the stale report.
+ * @returns The rewritten content, the archive block, and the report.
+ */
+export function curateLessons(content: string, now: number, root: string = process.cwd()): CurateResult {
+  const { preamble, blocks } = parse(content);
+  const { kept, fused } = dedup(blocks);
+  const { keep, archive } = splitAtCap(kept, now);
+  const changed = fused.length > 0 || archive.length > 0;
+  const rebuilt = changed ? `${preamble}\n${keep.map((b) => b.raw.join("\n")).join("\n\n")}\n` : content;
+  const capReport = archive.length ? [`${kept.length} bullets (> ${CAP}) — ${archive.length} oldest archived → LESSON-archive.md`] : [];
+  const report = [...fused, ...capReport, ...staleReport(blocks, now, root)].join("\n");
+  return { content: rebuilt, archive: formatArchive(archive, now), report };
+}

package/src/runtime/lifecycle/aipilot/dispatch-aipilot.ts

@@ -0,0 +1,100 @@
+/**
+ * ai-pilot scope dispatcher: routes Claude lifecycle events to the ported
+ * cache/injection handlers by (event, agent_type matcher).
+ */
+import { homedir } from "node:os";
+import { injectApexSubagentContext } from "./inject-apex";
+import { injectExploreCache } from "./inject-explore";
+import { injectDocCache } from "./inject-doc";
+import { injectLessonsCache } from "./inject-lessons";
+import { injectTestCache } from "./inject-test";
+import { cacheDocFromTranscript } from "./cache-doc";
+import { cacheSniperLessons } from "./cache-lessons";
+import { cacheTestResults } from "./cache-test";
+import { cacheAnalyticsSave } from "./analytics";
+import { syncTaskTracking } from "./sync-task";
+import { docCacheGate } from "./doc-cache-gate";
+import { checkSolidCompliance } from "./solid-compliance";
+import { checkSolidFromTranscript } from "./solid-transcript";
+import { contextResponse } from "../../../adapters/claude";
+
+/** The agent_type a SubagentStart/Stop payload reports. */
+function agentTypeOf(payload: Record<string, unknown>): string {
+  return String(payload.agent_type ?? payload.subagent_type ?? "");
+}
+
+/** Extract the `additionalContext` text from a SubagentStart response, or "". */
+function contextTextOf(response: string): string {
+  if (!response) return "";
+  try {
+    const parsed = JSON.parse(response) as { hookSpecificOutput?: { additionalContext?: string } };
+    return parsed.hookSpecificOutput?.additionalContext ?? "";
+  } catch { return ""; }
+}
+
+/**
+ * Combine N SubagentStart responses into one (Claude concatenates every hook's
+ * additionalContext; this single dispatch call must do that join itself). "" when all empty.
+ */
+function combineContext(...responses: string[]): string {
+  const parts = responses.map(contextTextOf).filter(Boolean);
+  return parts.length ? contextResponse("SubagentStart", parts.join("\n\n")) : "";
+}
+
+/** The transcript path a SubagentStop payload reports (Stop-only field). */
+function transcriptOf(payload: Record<string, unknown>): string | undefined {
+  const t = payload.agent_transcript_path;
+  return typeof t === "string" ? t : undefined;
+}
+
+/** Type-specific SubagentStart cache for an agent, or "" when none applies. */
+async function typeSpecificCache(agent: string, cwd: string, now: number, home: string): Promise<string> {
+  if (agent.includes("explore-codebase")) return injectExploreCache(cwd, home, now);
+  if (agent.includes("research-expert")) return injectDocCache(cwd, home, now);
+  if (agent.includes("sniper")) return injectTestCache(cwd, home, now);
+  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: Record<string, unknown>, cwd: string, now: number, home: string, id: string): Promise<string> {
+  const agent = agentTypeOf(payload);
+  const apex = await injectApexSubagentContext(cwd, home, id);
+  const lessons = await injectLessonsCache(cwd, home, now);
+  const typeSpecific = await typeSpecificCache(agent, cwd, now, home);
+  return combineContext(apex, lessons, typeSpecific);
+}
+
+/** SubagentStop routing: transcript-driven cache writers, then the universal SOLID check. `id` selects the harness target (defaults to "claude-code"), threaded into `cacheDocFromTranscript`. */
+async function onSubagentStop(payload: Record<string, unknown>, cwd: string, home: string, id: string): Promise<string> {
+  const agent = agentTypeOf(payload);
+  const transcript = transcriptOf(payload);
+  if (agent.includes("research-expert")) await cacheDocFromTranscript(transcript, cwd, home, id);
+  if (agent.includes("sniper")) {
+    await cacheSniperLessons(transcript, cwd, home);
+    await cacheTestResults(transcript, cwd, home);
+  }
+  return checkSolidFromTranscript(transcript, cwd);
+}
+
+/**
+ * Dispatch an ai-pilot-scope lifecycle event. Returns the native stdout, or
+ * `null` when unhandled (caller falls through to the default pipeline).
+ * @param home - Home dir for cache resolution (defaults to `~`; injectable for test isolation); `id` selects the harness target (defaults to "claude-code").
+ */
+export async function dispatchAipilot(event: string, payload: Record<string, unknown>, cwd: string, now: number, home: string = homedir(), id: string = "claude-code"): Promise<string | null> {
+  if (event === "SubagentStart") return onSubagentStart(payload, cwd, now, home, id);
+  if (event === "SubagentStop") return onSubagentStop(payload, cwd, home, id);
+  // Stop too: Codex emits no SessionEnd, so its ai-pilot hooks.json wires Stop here as the sole analytics-flush trigger — reusing the SessionEnd handler verbatim (codex-plugins/docs/reference/hooks.md).
+  if (event === "SessionEnd" || event === "Stop") { await cacheAnalyticsSave(home, now); return ""; }
+  if (event === "PreToolUse") return docCacheGate(payload, cwd, now, home, id);
+  return null;
+}
+
+/** PostToolUse (Write/Edit SOLID check, else TaskCreate/TaskUpdate sync) for the ai-pilot scope; `id` selects the harness target (defaults to "claude-code"). */
+export async function aipilotPostToolUse(payload: Record<string, unknown>, cwd: string, id: string = "claude-code"): Promise<string> {
+  return checkSolidCompliance(payload) || (await syncTaskTracking(payload, cwd, id));
+}