@fusengine/harness 0.1.89 → 0.1.91

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

@@ -0,0 +1,72 @@
+/**
+ * Lesson aggregation, dedup, merge, and edit categorization for the ai-pilot
+ * scope. Ported from the ai-pilot plugin's `cache/lesson-aggregator.ts` +
+ * `cache/lesson-helpers.ts` (now removed).
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { readJsonFile } from "../../../util/json-io";
+import { cacheBaseDir } from "./cache-base";
+import type { EditEntry, LessonEntry } from "./types";
+
+/** Deduplicate lessons by `error_type:pattern`, summing counts. */
+export function dedupLessons(lessons: LessonEntry[]): LessonEntry[] {
+  const groups = new Map<string, LessonEntry[]>();
+  for (const l of lessons) {
+    const key = `${l.error_type}:${l.pattern}`;
+    const group = groups.get(key);
+    if (group) group.push(l); else groups.set(key, [l]);
+  }
+  return [...groups.values()].map((entries) => {
+    const first = entries[0] as LessonEntry;
+    return {
+      error_type: first.error_type,
+      pattern: first.pattern,
+      fix: first.fix,
+      last_seen: first.last_seen,
+      count: entries.reduce((s, e) => s + e.count, 0),
+      files: [...new Set(entries.flatMap((e) => e.files))],
+      code: { line: [...new Set(entries.flatMap((e) => e.code?.line ?? []))].slice(0, 5) },
+    };
+  }).sort((a, b) => b.count - a.count);
+}
+
+/** Aggregate all local lesson JSON files into a flat deduplicated list. */
+export async function aggregateLocalLessons(cacheDir: string): Promise<LessonEntry[]> {
+  if (!existsSync(cacheDir)) return [];
+  const files = readdirSync(cacheDir).filter((f) => f.endsWith(".json"));
+  const all: LessonEntry[] = [];
+  for (const f of files) {
+    const data = await readJsonFile<{ errors?: LessonEntry[] }>(join(cacheDir, f));
+    if (data?.errors) all.push(...data.errors);
+  }
+  return dedupLessons(all);
+}
+
+/** Load global lessons for a stack (stack-specific + universal). */
+export async function loadGlobalLessons(stack: string, home: string = homedir()): Promise<LessonEntry[]> {
+  const globalDir = join(cacheBaseDir(home), "lessons", "_global");
+  const result: LessonEntry[] = [];
+  for (const name of [`${stack}.json`, "universal.json"]) {
+    const data = await readJsonFile<LessonEntry[]>(join(globalDir, name));
+    if (data) result.push(...data);
+  }
+  return result;
+}
+
+/** Merge local + global lessons, dedup by type+pattern, sort by count desc. */
+export function mergeLessons(local: LessonEntry[], global: LessonEntry[]): LessonEntry[] {
+  return dedupLessons([...local, ...global]);
+}
+
+/** Categorize an edit entry by analyzing the new code content. */
+export function categorizeEdit(edit: EditEntry): string {
+  const n = edit.newStr.toLowerCase();
+  if (n.includes("use client")) return "missing_directive";
+  if (n.includes("displayname")) return "missing_display_name";
+  if (/onkeydown|tabindex|role=/.test(n)) return "missing_a11y";
+  if (/try|catch/.test(n)) return "missing_error_handling";
+  if (/\?\?|if.*null/.test(n)) return "null_safety";
+  return "code_fix";
+}

package/src/runtime/lifecycle/aipilot/promote-global-lessons.ts

@@ -0,0 +1,92 @@
+/**
+ * Promote high-frequency project lessons (occurrence count >= 3) to the global,
+ * stack-scoped cache (`cache/lessons/_global/<stack>.json`, cap 25).
+ * Ports the ai-pilot `promote-global-lessons.ts` (a spawned subprocess) as an
+ * in-process call from `cacheSniperLessons`. Pure side-effect.
+ */
+import { homedir } from "node:os";
+import { mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonFile, writeJsonFile } from "../../../util/json-io";
+import { cacheBaseDir } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import type { LessonEntry } from "./types";
+
+/** A promoted global lesson tagged with the project hashes that produced it. */
+export interface GlobalLesson extends LessonEntry {
+  source_projects: string[];
+}
+
+const MIN_COUNT = 3;
+const MAX_GLOBAL = 25;
+
+/** Group lessons by `error_type:pattern`. */
+function groupByKey<T extends LessonEntry>(lessons: T[]): T[][] {
+  const groups = new Map<string, T[]>();
+  for (const l of lessons) {
+    const key = `${l.error_type}:${l.pattern}`;
+    (groups.get(key) ?? groups.set(key, []).get(key)!).push(l);
+  }
+  return [...groups.values()];
+}
+
+/** Read every project lesson file's `errors` into one flat (un-deduped) list. */
+async function aggregateErrors(cacheDir: string): Promise<LessonEntry[]> {
+  let files: string[];
+  try { files = readdirSync(cacheDir).filter((f) => f.endsWith(".json")); } catch { return []; }
+  const all: LessonEntry[] = [];
+  for (const f of files) {
+    const data = await readJsonFile<{ errors?: LessonEntry[] }>(join(cacheDir, f));
+    if (data?.errors) all.push(...data.errors);
+  }
+  return all;
+}
+
+/** Keep groups seen >= MIN_COUNT times, collapsed to a single lesson each. */
+function filterFrequent(lessons: LessonEntry[]): LessonEntry[] {
+  return groupByKey(lessons).filter((e) => e.length >= MIN_COUNT).map((entries) => {
+    const first = entries[0] as LessonEntry;
+    return {
+      error_type: first.error_type, pattern: first.pattern, fix: first.fix, last_seen: first.last_seen,
+      count: entries.length,
+      files: [...new Set(entries.flatMap((e) => e.files))],
+      code: { line: [...new Set(entries.flatMap((e) => e.code?.line ?? []))].slice(0, 5) },
+    };
+  });
+}
+
+/** Merge tagged candidates into existing global lessons; dedup, sum, sort, cap. */
+function mergeGlobal(existing: GlobalLesson[], candidates: LessonEntry[], projHash: string): GlobalLesson[] {
+  const tagged: GlobalLesson[] = candidates.map((c) => ({ ...c, source_projects: [projHash] }));
+  return groupByKey([...existing, ...tagged]).map((entries) => {
+    const first = entries[0] as GlobalLesson;
+    return {
+      error_type: first.error_type, pattern: first.pattern, fix: first.fix, last_seen: first.last_seen,
+      count: entries.reduce((sum, e) => sum + e.count, 0),
+      files: [...new Set(entries.flatMap((e) => e.files))],
+      code: { line: [...new Set(entries.flatMap((e) => e.code?.line ?? []))].slice(0, 5) },
+      source_projects: [...new Set(entries.flatMap((e) => e.source_projects ?? []))],
+    };
+  }).sort((a, b) => b.count - a.count).slice(0, MAX_GLOBAL);
+}
+
+/**
+ * Promote high-frequency lessons from `cacheDir` to the global stack file.
+ * @param cacheDir - Per-project lessons cache dir to scan.
+ * @param stack - Detected project stack (`nextjs`, `laravel`, …, `universal`).
+ * @param projHash - Source project hash (tags promoted entries).
+ * @param home - Home dir (defaults to `~`).
+ */
+export async function promoteGlobalLessons(cacheDir: string, stack: string, projHash: string, home: string = homedir()): Promise<void> {
+  const candidates = filterFrequent(await aggregateErrors(cacheDir));
+  if (candidates.length === 0) return;
+
+  const globalDir = join(cacheBaseDir(home), "lessons", "_global");
+  mkdirSync(globalDir, { recursive: true });
+  const globalFile = join(globalDir, `${stack}.json`);
+  const existing = (await readJsonFile<GlobalLesson[]>(globalFile)) ?? [];
+  const merged = mergeGlobal(existing, candidates, projHash);
+
+  await writeJsonFile(globalFile, merged, true);
+  logCacheEvent("lessons", "promoted", projHash, { count: merged.length, stack }, home);
+}

package/src/runtime/lifecycle/aipilot/solid-compliance.ts

@@ -0,0 +1,69 @@
+/**
+ * PostToolUse (matcher "Write|Edit") for the ai-pilot scope: validate SOLID
+ * file-size and interface-location compliance right after a code write.
+ * Ports `check-solid-compliance.py`.
+ */
+import { readText, pathExists } from "../../../util/runtime-io";
+import { contextResponse } from "../../../adapters/claude";
+import { resolveMaxLines, splitTarget } from "../../../config/limits";
+import { maskCommentsAndStrings } from "../../../policy/conventions/strip";
+import { isVendorPath } from "../../../policy/conventions/langs";
+
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|py|php|swift|go|rs|rb|java|astro)$/;
+const COMPONENT_DIR = /\/(components|pages|views)\//;
+const BACKEND_DIR = /\/(Controllers|Models|Services)\//;
+const TS_INTERFACE_RE = /^(export )?(interface|type) [A-Z]/m;
+const PHP_INTERFACE_RE = /^interface /m;
+
+/** Count non-empty, non-comment (`//`/`#`/`*`-prefixed) lines. Shared with {@link checkSolidFromTranscript}. */
+export function countCodeLines(content: string): number {
+  let count = 0;
+  for (const raw of content.split("\n")) {
+    const s = raw.trim();
+    if (!s || s.startsWith("//") || s.startsWith("#") || s.startsWith("*")) continue;
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Validate SOLID compliance for a just-written file.
+ * @param payload - The raw PostToolUse hook payload (`tool_name`, `tool_input.file_path`).
+ * @returns The PostToolUse `additionalContext` response, or `""` when clean/not applicable.
+ */
+export function checkSolidCompliance(payload: Record<string, unknown>): string {
+  const tool = String(payload.tool_name ?? "");
+  if (tool !== "Write" && tool !== "Edit") return "";
+  const input = (payload.tool_input as Record<string, unknown> | undefined) ?? {};
+  const filePath = typeof input.file_path === "string" ? input.file_path : "";
+  if (!filePath || !CODE_EXTENSIONS.test(filePath) || !pathExists(filePath)) return "";
+  if (isVendorPath(filePath)) return ""; // dependency/build dirs are never convention-gated
+
+  let content: string;
+  try {
+    content = readText(filePath);
+  } catch {
+    return "";
+  }
+
+  const violations: string[] = [];
+  const max = resolveMaxLines();
+  const split = splitTarget(max);
+  const lc = countCodeLines(content);
+  if (lc > max) violations.push(`FILE SIZE: ${lc} lines (max: ${max})`);
+  else if (lc > split) violations.push(`FILE SIZE WARNING: ${lc} lines (split at ${split})`);
+
+  // Per-extension matching on MASKED content (no cross-language regex bleed,
+  // no comment/string false positives).
+  const masked = maskCommentsAndStrings(content, filePath.endsWith(".php") ? "php" : filePath.endsWith(".py") ? "py" : "c");
+  if (COMPONENT_DIR.test(filePath) && /\.(ts|tsx|js|jsx|astro)$/.test(filePath)) {
+    if (TS_INTERFACE_RE.test(masked)) violations.push("INTERFACE LOCATION: Move to src/interfaces/");
+  } else if (BACKEND_DIR.test(filePath) && filePath.endsWith(".php")) {
+    if (PHP_INTERFACE_RE.test(masked)) violations.push("INTERFACE LOCATION: Move to app/Contracts/");
+  }
+
+  if (violations.length === 0) return "";
+  const name = filePath.split("/").pop() ?? filePath;
+  const message = `SOLID COMPLIANCE CHECK: ${name}\n\n${violations.join("\n")}\nINSTRUCTION: Fix violations before continuing.\nRun sniper agent for full validation.`;
+  return contextResponse("PostToolUse", message);
+}

package/src/runtime/lifecycle/aipilot/solid-notice.ts

@@ -0,0 +1,47 @@
+/**
+ * SubagentStop SOLID-notice dedup (anti-loop): `checkSolidFromTranscript` is
+ * stateless, so an unchanged violation set re-emitted the same
+ * `additionalContext` on EVERY SubagentStop — re-invoking the agent in an
+ * observed ~15-repeat loop. The dedup fingerprint is a SHA-256 hash of the
+ * sorted `file:message` set, persisted per agent key in the canonical
+ * `.harness/track/solid-notice.json` sidecar (`config/layout.ts`), written
+ * under the synchronous track lock (this hook runs in an ephemeral sync
+ * process). Semantics: identical fingerprint within the TTL → silence;
+ * changed/absent/expired fingerprint → emit once and record (the TTL derives
+ * from `FUSE_ENFORCE_TTL_SEC`, no new env var). On lock contention the notice
+ * is emitted anyway (visibility beats a muted violation) but not recorded.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWrite } from "../../../util/json-io";
+import { LOCK_FAILED, withTrackLockSync } from "../../../tracking/track-lock-sync";
+
+/** SHA-256 (truncated) of the sorted violation set — the dedup fingerprint. */
+export function noticeFingerprint(violations: string[]): string {
+  return createHash("sha256").update([...violations].sort().join("\n")).digest("hex").slice(0, 16);
+}
+
+/** Sidecar shape: agent key → last emitted fingerprint + timestamp. */
+type NoticeState = Record<string, { hash: string; at: number }>;
+
+/**
+ * Decide whether the notice for `key` may be emitted, recording it when so.
+ * @param noticeFile - `projectLayout(cwd).solidNoticeFile`.
+ * @param key - Agent/transcript identity (e.g. `agent_transcript_path`).
+ * @param hash - The current set's fingerprint ({@link noticeFingerprint}).
+ * @param now - Clock (epoch ms).
+ * @param ttlMs - Reminder window (derived from `FUSE_ENFORCE_TTL_SEC`).
+ */
+export function shouldEmitNotice(noticeFile: string, key: string, hash: string, now: number, ttlMs: number): boolean {
+  let state: NoticeState = {};
+  try { state = JSON.parse(readFileSync(noticeFile, "utf8")) as NoticeState; } catch { /* absent/corrupt → emit */ }
+  const prev = state[key];
+  if (prev && prev.hash === hash && now - prev.at < ttlMs) return false;
+  const next: NoticeState = { ...state, [key]: { hash, at: now } };
+  const ran = withTrackLockSync(dirname(noticeFile), () => {
+    try { atomicWrite(noticeFile, JSON.stringify(next)); } catch { /* fail-open */ }
+  });
+  void (ran === LOCK_FAILED); // emit regardless (see module doc)
+  return true;
+}

package/src/runtime/lifecycle/aipilot/solid-transcript.ts

@@ -0,0 +1,60 @@
+/**
+ * SubagentStop (matcher "") for the ai-pilot scope: check SOLID file-size and
+ * interface-location compliance for every file a sub-agent wrote/edited, per
+ * the transcript. Ports `check-solid-from-transcript.py`. Fires unconditionally
+ * for every sub-agent, unlike the sniper/research-expert-scoped caches here.
+ */
+import { readText, pathExists } from "../../../util/runtime-io";
+import { contextResponse } from "../../../adapters/claude";
+import { resolveMaxLines } from "../../../config/limits";
+import { resolveTtlSec } from "../../../config/ttl";
+import { projectLayout } from "../../../config/layout";
+import { transcriptFilePaths } from "./transcript";
+import { countCodeLines } from "./solid-compliance";
+import { noticeFingerprint, shouldEmitNotice } from "./solid-notice";
+
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|dart|vue|svelte|astro)$/;
+const INTERFACE_PATTERN = /^(export )?(interface|type) [A-Z]/m;
+/** Segment-anchored dirs (a substring like `app/` matched `livetest-app/`). */
+const INTERFACE_DIRS_RE = /\/(components|pages|views|app)\//;
+/** Canonical homes — never a violation there (owner decision: types/ is
+ * canonical; Contracts/ is the Laravel home taught by solid-php/laravelGate). */
+const INTERFACE_EXEMPT_RE = /\/(interfaces|types|Contracts|contracts)\//;
+
+/**
+ * Check every Write/Edit target in a subagent transcript against the SOLID
+ * line-count ceiling and interface-location convention. Deduped per
+ * transcript (`solid-notice.ts`): an unchanged violation set is emitted once
+ * per TTL window, never in a loop.
+ * @param transcript - Path to the agent JSONL transcript (`agent_transcript_path`).
+ * @param cwd - Project root (locates the `.harness/track` dedup sidecar).
+ * @param now - Clock (tests inject it).
+ * @returns The SubagentStop `additionalContext` response, or `""` when clean/deduped.
+ */
+export async function checkSolidFromTranscript(transcript: string | undefined, cwd: string = process.cwd(), now: number = Date.now()): Promise<string> {
+  if (!transcript || !pathExists(transcript)) return "";
+  const files = await transcriptFilePaths(transcript, ["Write", "Edit"]);
+  const max = resolveMaxLines();
+  const violations: string[] = [];
+
+  for (const fp of files.sort()) {
+    if (!pathExists(fp) || !CODE_EXTENSIONS.test(fp)) continue;
+    const name = fp.split("/").pop() ?? fp;
+    let content: string;
+    try {
+      content = readText(fp);
+    } catch {
+      continue;
+    }
+    const lc = countCodeLines(content);
+    if (lc > max) violations.push(`SOLID: ${name} = ${lc} lines (max ${max})`);
+    if (INTERFACE_DIRS_RE.test(fp) && !INTERFACE_EXEMPT_RE.test(fp) && INTERFACE_PATTERN.test(content)) {
+      const dest = fp.endsWith(".php") ? "app/Contracts/" : "interfaces/";
+      violations.push(`SOLID: ${name}: move interfaces to ${dest}`);
+    }
+  }
+
+  if (violations.length === 0) return "";
+  if (!shouldEmitNotice(projectLayout(cwd).solidNoticeFile, transcript, noticeFingerprint(violations), now, resolveTtlSec(process.env) * 1000)) return "";
+  return contextResponse("SubagentStop", `## SOLID VIOLATIONS DETECTED (subagent output)\n${violations.join("\n")}\nRun sniper to fix these issues.`);
+}

package/src/runtime/lifecycle/aipilot/source-scan.ts

@@ -0,0 +1,56 @@
+/**
+ * Source-file scanning + project-stack detection for the ai-pilot scope.
+ * Ported from the ai-pilot plugin's `cache/source-collector.ts` +
+ * the stack detection in `cache/lesson-helpers.ts` (now removed).
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { collectFiles } from "../../../util/runtime-io";
+
+/** Source extensions to collect (monorepo-aware, dot-prefixed for matching). */
+const SRC_EXTS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+/** Roots walked: `src`, `app`, plus each child `src` under `apps/` and `packages/`. */
+const TOP_DIRS = ["src", "app"] as const;
+const NESTED_PARENTS = ["apps", "packages"] as const;
+
+/** Collect the existing monorepo `src` roots nested under `apps/` and `packages/`. */
+function nestedRoots(projectPath: string): string[] {
+  const roots: string[] = [];
+  for (const parent of NESTED_PARENTS) {
+    try {
+      for (const e of readdirSync(join(projectPath, parent), { withFileTypes: true })) {
+        if (e.isDirectory()) roots.push(join(projectPath, parent, e.name, "src"));
+      }
+    } catch { /* parent dir may not exist */ }
+  }
+  return roots;
+}
+
+/**
+ * Scan source files in `projectPath` (monorepo-aware), capped at `maxFiles`.
+ * Node+Bun portable: walks `node:fs` recursively (replaces the Bun `Glob`).
+ * @param projectPath - Absolute project root.
+ * @param maxFiles - Max files to collect (default 200).
+ * @returns Absolute paths matching the source extensions.
+ */
+export async function scanSourceFiles(projectPath: string, maxFiles = 200): Promise<string[]> {
+  const files: string[] = [];
+  const roots = [...TOP_DIRS.map((d) => join(projectPath, d)), ...nestedRoots(projectPath)];
+  for (const root of roots) {
+    collectFiles(root, SRC_EXTS, files, maxFiles);
+    if (files.length >= maxFiles) break;
+  }
+  return files;
+}
+
+/** Detect the project stack from config files in the project root. */
+export function detectStack(projectPath: string): string {
+  try {
+    const entries = readdirSync(projectPath);
+    if (entries.some((f) => f.startsWith("next.config"))) return "nextjs";
+    if (entries.includes("composer.json")) return "laravel";
+    if (entries.some((f) => f.endsWith(".xcodeproj")) || entries.includes("Package.swift")) return "swift";
+    if (entries.some((f) => f.startsWith("tailwind.config"))) return "tailwindcss";
+  } catch { /* fallback */ }
+  return "universal";
+}

package/src/runtime/lifecycle/aipilot/sync-task.ts

@@ -0,0 +1,75 @@
+/**
+ * PostToolUse (matcher "TaskCreate|TaskUpdate") for the ai-pilot scope:
+ * synchronize Claude task tools with `.claude/apex/task.json` and prompt an
+ * auto-commit on completion when git changes are detected. Ports
+ * `sync-task-tracking.ts`.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonFile } from "../../../util/json-io";
+import { spawnCapture } from "../../../util/runtime-io";
+import { contextResponse } from "../../../adapters/claude";
+import { acquireLock, taskCreate, taskStart, taskComplete } from "./apex-task-store";
+import { harnessHomeSegment } from "../../../policy/apex-target";
+import type { ApexTaskFile } from "./types";
+
+/** True when the project has uncommitted git changes. */
+async function hasGitChanges(cwd: string): Promise<boolean> {
+  try {
+    return spawnCapture("git", ["status", "--porcelain"], cwd).trim().length > 0;
+  } catch { return false; }
+}
+
+/** Handle a completed task: emit the commit reminder (or the no-change note). */
+async function onComplete(taskFile: string, taskId: string, projectRoot: string): Promise<string> {
+  await taskComplete(taskFile, taskId);
+  if (!(await hasGitChanges(projectRoot))) {
+    return contextResponse("PostToolUse", "Task completed. No changes to commit.");
+  }
+  const data = await readJsonFile<ApexTaskFile>(taskFile);
+  const subject = data?.tasks[taskId]?.subject ?? "Task";
+  return contextResponse("PostToolUse", `Task #${taskId} completed: ${subject}\n\nChanges detected. MANDATORY: Run /fuse-commit-pro:commit to commit with smart detection.`);
+}
+
+/**
+ * PostToolUse TaskCreate/TaskUpdate handler. Claude-only by design: Codex never
+ * emits these native task tools, so the `toolName` matcher below intentionally
+ * stays as-is — only the target apex-dir segment is harness-aware.
+ * @param payload - The raw hook payload (`tool_name`, `tool_input`, `tool_response`).
+ * @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export async function syncTaskTracking(payload: Record<string, unknown>, cwd: string, id: string = "claude-code"): Promise<string> {
+  const toolName = String(payload.tool_name ?? "");
+  if (toolName !== "TaskCreate" && toolName !== "TaskUpdate") return "";
+
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const seg = harnessHomeSegment(id);
+  const taskFile = join(projectRoot, seg, "apex", "task.json");
+  if (!existsSync(taskFile)) return "";
+
+  const unlock = await acquireLock(join(projectRoot, seg, "apex", ".task.lock"), 10000);
+  if (!unlock) return "";
+  try {
+    const ti = (payload.tool_input ?? {}) as Record<string, string>;
+    if (toolName === "TaskCreate") {
+      const existing = (await readJsonFile<ApexTaskFile>(taskFile))?.tasks ?? {};
+      const respId = (payload.tool_response as { id?: string } | undefined)?.id;
+      const taskId = respId ?? String(Math.max(0, ...Object.keys(existing).map(Number)) + 1);
+      await taskCreate(taskFile, taskId, ti.subject ?? "", ti.description ?? "");
+      return "";
+    }
+    const taskId = ti.taskId ?? "";
+    if (!taskId) return "";
+    const newStatus = ti.status ?? "";
+    if (newStatus === "in_progress") {
+      const blocked = (ti.addBlockedBy as unknown as string[] | undefined)?.join(",") ?? "";
+      await taskStart(taskFile, taskId, ti.subject || undefined, ti.description || undefined, blocked || undefined);
+    }
+    if (newStatus === "completed") return onComplete(taskFile, taskId, projectRoot);
+    return "";
+  } finally {
+    await unlock();
+  }
+}

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

@@ -0,0 +1,88 @@
+/**
+ * JSONL transcript parsing helpers for the ai-pilot scope: project-root
+ * detection from file paths, file-path extraction, Edit extraction, and the
+ * assistant report extraction. Ported into the harness from the ai-pilot
+ * plugin's `cache/project-detect.ts` + `cache/lesson-helpers.ts` (now removed).
+ */
+import { readdirSync } from "node:fs";
+import { readText } from "../../../util/runtime-io";
+import type { EditEntry } from "./types";
+
+const ROOT_MARKERS = [".git", ".hg", "turbo.json", "nx.json", "lerna.json", "pnpm-workspace.yaml"];
+const PKG_MARKERS = ["package.json", "composer.json", "Package.swift", "Cargo.toml", "go.mod", "pyproject.toml", "Gemfile", "pom.xml"];
+
+/** Detect the project root by walking up from the first file path to a marker. */
+export function projectRootFromPaths(filePaths: string[]): string | null {
+  const firstPath = filePaths[0];
+  if (!firstPath) return null;
+  const lastSlash = firstPath.lastIndexOf("/");
+  if (lastSlash <= 0) return null;
+  let dir = firstPath.substring(0, lastSlash);
+  let bestRoot: string | null = null;
+  while (dir && dir !== "/" && dir.length > 1) {
+    try {
+      const entries = readdirSync(dir);
+      if (ROOT_MARKERS.some((m) => entries.includes(m))) return dir;
+      if (PKG_MARKERS.some((m) => entries.includes(m))) bestRoot = dir;
+    } catch { break; }
+    const parentSlash = dir.lastIndexOf("/");
+    if (parentSlash <= 0) break;
+    dir = dir.substring(0, parentSlash);
+  }
+  return bestRoot;
+}
+
+/** Extract absolute file paths from tool_use entries in a JSONL transcript, optionally restricted to `toolNames` (default: any tool). */
+export async function transcriptFilePaths(transcriptPath: string, toolNames?: readonly string[]): Promise<string[]> {
+  const text = readText(transcriptPath);
+  const paths = new Set<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") continue;
+        if (toolNames && !toolNames.includes(block.name)) continue;
+        const fp = block.input?.file_path ?? block.input?.path ?? "";
+        if (typeof fp === "string" && fp.startsWith("/")) paths.add(fp);
+      }
+    } catch { /* skip malformed */ }
+  }
+  return [...paths];
+}
+
+/** Extract deduplicated Edit tool_use entries (keyed by basename) from a transcript. */
+export async function transcriptEdits(transcriptPath: string): Promise<EditEntry[]> {
+  const text = readText(transcriptPath);
+  const edits: EditEntry[] = [];
+  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 === "Edit" && block.input?.file_path) {
+          edits.push({ file: block.input.file_path, oldStr: block.input.old_string ?? "", newStr: block.input.new_string ?? "" });
+        }
+      }
+    } catch { /* skip malformed */ }
+  }
+  const seen = new Map<string, EditEntry>();
+  for (const e of edits) seen.set(e.file.split("/").pop() ?? e.file, e);
+  return [...seen.values()];
+}
+
+/** Extract the last assistant text report (first 500 lines) from a transcript. */
+export async function transcriptReport(transcriptPath: string): Promise<string> {
+  const text = readText(transcriptPath);
+  let lastReport = "";
+  for (const line of text.split("\n").filter(Boolean)) {
+    try {
+      const entry = JSON.parse(line) as { message?: { role?: string; content?: { type?: string; text?: string }[] } };
+      if (entry?.message?.role !== "assistant") continue;
+      for (const block of entry.message.content ?? []) {
+        if (block.type === "text" && block.text) lastReport = block.text;
+      }
+    } catch { /* skip malformed */ }
+  }
+  return lastReport.split("\n").slice(0, 500).join("\n");
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Cache + APEX interfaces for the ai-pilot scope (separated from implementation
+ * per SOLID interface-segregation).
+ */
+
+/** Index file for the per-project documentation cache. */
+export interface CacheIndex {
+  project: string;
+  docs: CacheEntry[];
+}
+
+/** Single cached document entry in the doc index. */
+export interface CacheEntry {
+  hash: string;
+  library: string;
+  topic: string;
+  timestamp: string;
+  size_kb: number;
+}
+
+/** Lesson entry extracted from a sniper transcript. */
+export interface LessonEntry {
+  error_type: string;
+  pattern: string;
+  fix: string;
+  count: number;
+  last_seen: string;
+  files: string[];
+  code: { line: string[] };
+}
+
+/** An Edit tool_use extracted from a sniper transcript. */
+export interface EditEntry {
+  file: string;
+  oldStr: string;
+  newStr: string;
+}
+
+/** Cached lint/test result for a single source file. */
+export interface TestResult {
+  checksum: string;
+  eslint: "pass" | "fail";
+  tsc: "pass" | "fail";
+  last_tested: string;
+}
+
+/** Test cache structure stored on disk. */
+export interface TestCache {
+  timestamp: string;
+  files: Record<string, TestResult>;
+}
+
+/** A task entry in `.claude/apex/task.json`. */
+export interface ApexTask {
+  subject: string;
+  description: string;
+  status: string;
+  phase: string;
+  started_at?: string;
+  completed_at?: string;
+  created_at?: string;
+  doc_consulted: Record<string, unknown>;
+  files_modified: string[];
+  blockedBy?: string[];
+}
+
+/** Structure of `.claude/apex/task.json`. */
+export interface ApexTaskFile {
+  current_task: string;
+  created_at: string;
+  tasks: Record<string, ApexTask>;
+}