@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/inject-context.ts

@@ -0,0 +1,85 @@
+import { attachSystemMessage, contextResponse } from "../adapters/claude";
+import { renderInform } from "./inform";
+import { buildClaudeMdContext } from "../policy/claude-md-context";
+import { buildApexTaskInjection } from "../policy/apex-task-context";
+import { apexDocName } from "../policy/apex-target";
+import { hashText } from "../util/json-io";
+import { oncePerWindow, DEDUP_WINDOW_MS } from "./inject-dedup";
+import { capFragment } from "./inject-budget";
+
+/**
+ * Build the {@link oncePerWindow} key for the CLAUDE.md preamble gate. The
+ * prompt hash keeps two distinct legitimate turns from colliding — even non-dev
+ * prompts, whose block is prompt-independent (just CLAUDE.md) and would
+ * otherwise hash-collide within the window — while the content hash still lets a
+ * same-turn double-fire of an identical block be suppressed. Single source of
+ * truth so the owner invariant test guards the real production key.
+ * @param prompt - The raw user prompt.
+ * @param ctx - The rendered CLAUDE.md (+ optional APEX) block.
+ * @returns The namespaced dedup key.
+ */
+export function claudeMdKey(prompt: string, ctx: string): string {
+  return `claude-md:${hashText(prompt)}:${hashText(ctx)}`;
+}
+
+/**
+ * Extract the APEX preamble portion of a `buildClaudeMdContext` result, i.e.
+ * everything BEFORE the `# <docName>\n` root-doc block it prepends on dev
+ * prompts. Returns "" when `ctx` has no preamble (plain prompt: `ctx` starts
+ * directly with the root-doc heading).
+ * @param ctx - The full `buildClaudeMdContext` return value.
+ * @param docName - Root doc file name (e.g. "AGENTS.md").
+ * @returns The preamble text, or "" when absent.
+ */
+function extractApexPreamble(ctx: string, docName: string): string {
+  const heading = `# ${docName}\n`;
+  if (ctx.startsWith(heading)) return "";
+  const sep = `\n\n${heading}`;
+  const idx = ctx.indexOf(sep);
+  return idx === -1 ? "" : ctx.slice(0, idx);
+}
+
+/**
+ * UserPromptSubmit context injection: render the CLAUDE.md (+ optional APEX)
+ * preamble as a Claude `additionalContext` response, or "" when nothing to emit.
+ * Guarded by {@link oncePerWindow} via {@link claudeMdKey}: only a
+ * near-simultaneous double-fire of the SAME turn (identical prompt AND identical
+ * block, within {@link DEDUP_WINDOW_MS}) is suppressed. The invariant "CLAUDE.md
+ * is emitted on EVERY message" is thus preserved.
+ *
+ * On kimi specifically, the root doc body is dropped from the emitted text:
+ * Kimi loads `<kimiHome>/AGENTS.md` natively at session start (`apex-target.ts`),
+ * so re-injecting its full body on every prompt is redundant terminal noise
+ * (kimi has no model-only hook channel — `runtime/inform.ts`). The APEX
+ * preamble, which is NOT part of `AGENTS.md`, is still emitted in full when the
+ * prompt is dev-shaped; a plain prompt leaves only the notice.
+ * @param prompt - The raw user prompt.
+ * @param cwd - Project root (for project-type detection).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export function promptSubmitContext(prompt: string, cwd: string, id: string = "claude-code"): string {
+  const ctx = buildClaudeMdContext(prompt, cwd, id);
+  if (!ctx) return "";
+  if (!oncePerWindow(claudeMdKey(prompt, ctx), DEDUP_WINDOW_MS)) return "";
+  const notice = `${apexDocName(id)} injected`;
+  if (id === "kimi") {
+    const preamble = extractApexPreamble(ctx, apexDocName(id));
+    return preamble ? renderInform(id, "UserPromptSubmit", preamble, notice) : notice;
+  }
+  return renderInform(id, "UserPromptSubmit", ctx, notice);
+}
+
+/**
+ * PreToolUse Task context injection: render the APEX sub-agent context as a
+ * Claude `additionalContext` response when `.claude/apex/` exists, else "".
+ * Harness-produced (not owner CLAUDE.md content), so it is subject to the
+ * per-fragment {@link capFragment} budget — unlike {@link promptSubmitContext}.
+ * @param cwd - Fallback project root when `CLAUDE_PROJECT_DIR` is unset.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export function taskContext(cwd: string, id: string = "claude-code"): string {
+  const ctx = buildApexTaskInjection(process.env.CLAUDE_PROJECT_DIR ?? cwd, id);
+  return ctx ? contextResponse("PreToolUse", capFragment("apex-task", ctx)) : "";
+}

package/src/runtime/inject-dedup-exclusive.ts

@@ -0,0 +1,98 @@
+/**
+ * @module inject-dedup-exclusive
+ * Cross-process-exact-once cooldown gate, via EXCLUSIVE file creation.
+ *
+ * {@link module:inject-dedup.oncePerWindow}'s shared-JSON read-modify-write is
+ * best-effort under true concurrency: the ~11-process plugin hook fan-out for
+ * one Claude event can lose an update and let 2-3 siblings all observe "not
+ * seen yet" (lesson 2026-07-05 16:00 — the `saveTrack` lost-update race, same
+ * shape). `writeFileSync(path, data, { flag: "wx" })` sidesteps this: the OS
+ * guarantees exclusive creation is atomic, so of N concurrent siblings calling
+ * this for the SAME key, exactly one observes success and the rest get
+ * `EEXIST` — never a double-win, with no lock file or retry loop needed.
+ *
+ * One marker file per key (not a shared map) is the tradeoff for that
+ * guarantee. A bounded sweep on every call deletes markers older than
+ * `windowMs` so the directory never grows unbounded under many distinct keys.
+ *
+ * Reserve this for HIGH-CONCURRENCY callers on a short burst window (same
+ * tool-use/lifecycle event fanned out to every installed plugin) — e.g. the
+ * sniper reminder ({@link module:lifecycle/track-changes}) and compliance
+ * notices ({@link module:notices}). Low-frequency, long-window callers (e.g.
+ * the 30-min lessons Stop-reminder cooldown) are fine on the JSON mode: a
+ * single real Stop event per session is not concurrent with itself the way
+ * one PostToolUse's ~11 sibling hooks are within the same 2s burst.
+ * @packageDocumentation
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { defaultStateDir } from "./paths";
+import type { OnceOpts } from "./inject-dedup";
+
+/** Subdirectory (under the state dir) holding one marker file per dedup key. */
+const EXCLUSIVE_SUBDIR = "inject-dedup-locks";
+
+/**
+ * Filesystem-safe, collision-resistant basename for `key`. Full MD5 hex
+ * (unlike {@link module:util/json-io.hashText}'s 8-char truncation) — a
+ * collision here would silently merge two unrelated keys' exclusivity.
+ */
+function lockFileName(key: string): string {
+  return `${createHash("md5").update(key).digest("hex")}.lock`;
+}
+
+/**
+ * Delete marker files older than `windowMs` in `dir` — O(n) per call, bounds
+ * directory growth. Compares against the creation timestamp STORED IN the
+ * marker's content (written by {@link onceExclusive} below), not the file's
+ * fs `mtime`: callers may pass a fake logical `now` (tests), which would never
+ * agree with the real OS clock backing `mtime`.
+ */
+function sweepExclusiveDir(dir: string, now: number, windowMs: number): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry);
+    try {
+      const createdAt = Number(readFileSync(path, "utf8"));
+      if (!Number.isFinite(createdAt) || now - createdAt >= windowMs) unlinkSync(path);
+    } catch {
+      /* a sibling process already swept/removed it, or a transient read race — ignore */
+    }
+  }
+}
+
+/**
+ * Cooldown gate via exclusive marker-file creation. Returns `true` exactly
+ * once per `key` within `windowMs` across ALL concurrent processes sharing
+ * `opts.dir` (the caller MAY emit), `false` for every other concurrent or
+ * subsequent call inside the same window (the caller SHOULD suppress).
+ *
+ * Fails open on any unwritable state dir or unexpected fs error: the emission
+ * is allowed rather than silently dropped.
+ * @param key - Stable identity of the block (same semantics as {@link module:inject-dedup.oncePerWindow}).
+ * @param windowMs - Suppression window in ms (also the sweep threshold).
+ * @param opts - Optional clock + state-dir overrides (for tests).
+ * @returns `true` to proceed/emit, `false` to suppress.
+ */
+export function onceExclusive(key: string, windowMs: number, opts: OnceOpts = {}): boolean {
+  const now = opts.now ?? Date.now();
+  const dir = join(opts.dir ?? defaultStateDir(), EXCLUSIVE_SUBDIR);
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return true;
+  }
+  sweepExclusiveDir(dir, now, windowMs);
+  try {
+    writeFileSync(join(dir, lockFileName(key)), String(now), { flag: "wx" });
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code !== "EEXIST";
+  }
+}

package/src/runtime/inject-dedup.ts

@@ -0,0 +1,89 @@
+/**
+ * @module inject-dedup
+ * Generic "once per window" guard for hook context injection.
+ *
+ * Persists a tiny sidecar map `{ key -> lastEmittedEpochMs }` in the existing
+ * per-project state dir (`~/.fuse-harness/state/<projectHash>/inject-dedup.json`,
+ * the same dir as the session track — see {@link defaultStateDir}). Lets a caller
+ * suppress a block it has already emitted within a short window, defending
+ * against the "same content emitted by two near-simultaneous hooks" family
+ * (cf. the 0.1.48 SubagentStart double-inject). Also reused as a cooldown gate.
+ *
+ * Best-effort under true process-level concurrency (the read-modify-write is not
+ * locked); reliable for the sequential single-process callers that use it.
+ * @packageDocumentation
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { defaultStateDir } from "./paths";
+
+/** Default suppression window (ms): catches same-turn double-fire, not next-turn re-emits. */
+export const DEDUP_WINDOW_MS = 3000;
+
+/** Sidecar basename under the per-project state dir. */
+const SIDECAR = "inject-dedup.json";
+
+/** Optional overrides — tests inject a clock + a scratch dir; production omits both. */
+export interface OnceOpts {
+  /** Clock in epoch-ms (default `Date.now()`). */
+  now?: number;
+  /** State-dir override (default {@link defaultStateDir}). */
+  dir?: string;
+}
+
+/** Load the `{ key -> epochMs }` map, or `{}` when missing/corrupt. */
+function loadMap(path: string): Record<string, number> {
+  try {
+    if (!existsSync(path)) return {};
+    const data: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, number>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Keep only entries newer than `windowMs` before `now` (bounds sidecar size). */
+function prune(map: Record<string, number>, now: number, windowMs: number): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const [k, t] of Object.entries(map)) {
+    if (typeof t === "number" && now - t < windowMs) out[k] = t;
+  }
+  return out;
+}
+
+/**
+ * Cooldown gate. Returns `true` when `key` has NOT been recorded within the last
+ * `windowMs` (the caller MAY emit — and the emission is recorded now), or `false`
+ * when it was (the caller SHOULD suppress). The first call in a window wins;
+ * subsequent identical keys are throttled until the window elapses.
+ *
+ * Fails open: if the sidecar is unwritable, the emission is allowed rather than
+ * silently dropping context.
+ * @param key - Stable identity of the block (e.g. a content hash, or `lesson:<id>`).
+ * @param windowMs - Suppression window in ms.
+ * @param opts - Optional clock + state-dir overrides (for tests).
+ * @returns `true` to proceed/emit, `false` to suppress.
+ */
+export function oncePerWindow(key: string, windowMs: number, opts: OnceOpts = {}): boolean {
+  const now = opts.now ?? Date.now();
+  const path = join(opts.dir ?? defaultStateDir(), SIDECAR);
+  const map = prune(loadMap(path), now, windowMs);
+  const last = map[key];
+  if (typeof last === "number" && now - last < windowMs) return false;
+  map[key] = now;
+  try {
+    atomicWrite(path, JSON.stringify(map));
+  } catch {
+    /* sidecar unwritable → fail-open: allow the emission rather than lose context */
+  }
+  return true;
+}
+
+/**
+ * Cross-process-exact-once variant (exclusive file creation, not the shared
+ * JSON above) for high-concurrency callers — split out to
+ * {@link module:inject-dedup-exclusive} to keep this file under the SOLID
+ * line budget; re-exported here so both modes share one import surface.
+ */
+export { onceExclusive } from "./inject-dedup-exclusive";

package/src/runtime/is-agent-tool.ts

@@ -0,0 +1,19 @@
+/**
+ * Sub-agent dispatch tool detection — the single source of truth for "this
+ * tool call spawns a sub-agent". Claude Code and Codex dispatch via `Task`;
+ * Kimi Code CLI dispatches via `Agent` (and `AgentSwarm` for parallel fan-out).
+ * Centralized so the APEX task-context injection, the activity tracking and
+ * the PostToolUse evidence credit stop drifting on inline `"Task" | "Agent"`
+ * unions: every consumer imports from HERE, never re-declares the list.
+ */
+
+/** Canonical set of sub-agent dispatch tool names (the ONLY definition). */
+export const AGENT_TOOLS: ReadonlySet<string> = new Set(["Task", "Agent", "AgentSwarm"]);
+
+/**
+ * True when the tool is a sub-agent dispatch primitive on any harness.
+ * @param tool - The normalized tool name from the hook payload.
+ */
+export function isAgentTool(tool: string): boolean {
+  return AGENT_TOOLS.has(tool);
+}

package/src/runtime/lifecycle/agent-files.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-agent file attribution for SubagentStop. Uses the shared transcript parser
+ * ({@link readAgentToolUses}) to recover the exact set of files a sub-agent wrote
+ * via Write/Edit/MultiEdit/NotebookEdit, so the sniper reminder attributes only
+ * the files THIS agent touched instead of every file changed in the whole session
+ * (which cross-attributes other teammates' work — the bug this fixes).
+ */
+import { basename } from "node:path";
+import { readAgentToolUses } from "./agent-transcript";
+
+/** Tools whose `input.file_path`/`notebook_path` names a file the agent authored. */
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+/**
+ * Return the distinct file paths written by the sub-agent whose own transcript is
+ * at `transcriptPath` (Write/Edit/MultiEdit/NotebookEdit). `null` when unreadable
+ * (caller MUST fall back to the session-wide list — no regression); a possibly-
+ * empty array when parsed (empty = authored nothing, so it should NOT be told to
+ * validate files other agents changed).
+ * @param transcriptPath - Absolute path to the sub-agent's own `.jsonl` transcript.
+ * @returns Distinct written paths (order-preserving), or `null` when unreadable.
+ */
+export function filesWrittenByAgent(transcriptPath: string | undefined): string[] | null {
+  const uses = readAgentToolUses(transcriptPath);
+  if (uses === null) return null;
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const u of uses) {
+    if (!WRITE_TOOLS.has(u.name)) continue;
+    const fp = u.input?.file_path ?? u.input?.notebook_path;
+    if (typeof fp === "string" && fp && !seen.has(fp)) { seen.add(fp); out.push(fp); }
+  }
+  return out;
+}
+
+/**
+ * Filter `sessionFiles` down to the ones this agent actually wrote. Matches the
+ * exact recorded string first, then tolerantly on `basename` so a relative-vs-
+ * absolute drift between the PostToolUse record and the transcript input never
+ * loses an owned file.
+ * @param sessionFiles - Session-wide modified files.
+ * @param written - Paths the agent wrote (from {@link filesWrittenByAgent}).
+ * @returns The subset of `sessionFiles` attributable to this agent.
+ */
+export function attributeFiles(sessionFiles: readonly string[], written: readonly string[]): string[] {
+  const exact = new Set(written);
+  const bases = new Set(written.map((f) => basename(f)));
+  return sessionFiles.filter((f) => exact.has(f) || bases.has(basename(f)));
+}

package/src/runtime/lifecycle/agent-memory.ts

@@ -0,0 +1,82 @@
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { contextResponse } from "../../adapters/claude";
+import { resolveTtlSec } from "../../config/ttl";
+import { loadSessionState, sanitizeSessionId, saveSessionState, sessionsDir } from "../home-state";
+import { defaultStateDir, trackFile } from "../paths";
+import { freshReceiptFromFile } from "../../tracking/receipts";
+import { attributeFiles, filesWrittenByAgent } from "./agent-files";
+
+/** The `changes` block written by `track-changes.ts` into unified session state. */
+interface Changes {
+  cumulativeCodeFiles?: number;
+  modifiedFiles?: string[];
+}
+
+/** `~/.claude/memory/agents` — agent completion history dir. */
+function memoryDir(home: string): string {
+  return join(home, ".claude", "memory", "agents");
+}
+
+const SKIP_AGENTS = /(sniper|sniper-faster|explore-codebase|research-expert|claude-code-guide|Explore|Plan)/;
+
+/** Append the agent completion record to `agent-history.jsonl` (best effort). */
+function recordHistory(home: string, agentId: string, agentType: string, ts: string): void {
+  const dir = memoryDir(home);
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "agent-history.jsonl"), JSON.stringify({ agentId, agentType, completedAt: ts }) + "\n", "utf-8");
+  } catch { /* best effort */ }
+}
+
+/**
+ * Handle SubagentStop: append the completion to agent-history.jsonl and, for a
+ * non-skipped agent that touched code, emit the sniper reminder + reset the
+ * counter. Ports `subagent-stop/track-agent-memory.py`.
+ * @param data - The raw hook payload.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout (always a JSON message).
+ */
+export function trackAgentMemory(data: Record<string, unknown>, home: string = homedir(), now: number = Date.now()): string {
+  mkdirSync(sessionsDir(home), { recursive: true });
+  const agentType = String(data.agent_type ?? data.subagent_type ?? "unknown");
+  const sessionId = sanitizeSessionId(data.session_id) ?? "unknown";
+  const ts = new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+  recordHistory(home, String(data.agent_id ?? "unknown"), agentType, ts);
+  if (SKIP_AGENTS.test(agentType)) return JSON.stringify({ message: `Agent ${agentType} completed` });
+  const state = loadSessionState(sessionId, home);
+  const changes = state.changes as Changes | undefined;
+  const count = changes?.cumulativeCodeFiles ?? 0;
+  if (count > 0) {
+    // Attribute only the files THIS agent actually wrote, parsed from its own
+    // transcript (SubagentStop `agent_transcript_path`, CLI v2.0.42+). When the
+    // field is absent or the transcript is unreadable, `filesWrittenByAgent`
+    // returns null → fall back to the session-wide list (no regression).
+    const written = filesWrittenByAgent(typeof data.agent_transcript_path === "string" ? data.agent_transcript_path : undefined);
+    const owned = written === null ? (changes?.modifiedFiles ?? []) : attributeFiles(changes?.modifiedFiles ?? [], written);
+    // Only reset the session counter when this agent owns changes — so an agent
+    // that touched none of the tracked files never clears them for the real
+    // author, and never gets told to validate another teammate's work.
+    if (owned.length > 0) {
+      saveSessionState(sessionId, { ...state, changes: { ...changes, cumulativeCodeFiles: 0 } }, home);
+      // Never demand sniper on a file the agent deleted before stopping (e.g. a
+      // scratch probe rm -rf'd): the tracked list records writes, never removals,
+      // so re-check the disk (a relative path resolves against the hook cwd) and
+      // keep only files still present. All gone → nothing to validate → "no changes".
+      const hookCwd = typeof data.cwd === "string" ? data.cwd : process.cwd();
+      const present = owned.filter((f) => existsSync(resolve(hookCwd, f)));
+      if (present.length > 0) {
+        // Advisory (no hard block here — the TaskCompleted gate enforces): flag the
+        // missing proof when the agent owns code but posted no fresh passing receipt.
+        // Window = TTL×5, matching the TaskCompleted receipt gate.
+        const windowMs = resolveTtlSec(process.env) * 1000 * 5;
+        const noReceipt = freshReceiptFromFile(trackFile(sessionId, defaultStateDir(process.cwd())), windowMs, now) === null;
+        const note = noReceipt ? " NO VERIFICATION RECEIPT — run tsc + tests before reporting done." : "";
+        return contextResponse("SubagentStop", `SNIPER VALIDATION REQUIRED: Agent '${agentType}' modified ${present.length} code file(s): ${present.join(", ")}. Run sniper agent now.${note}`);
+      }
+    }
+  }
+  return JSON.stringify({ message: `Agent ${agentType} completed (no code changes)` });
+}

package/src/runtime/lifecycle/agent-transcript.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared low-level parser for a sub-agent's OWN transcript (`agent_transcript_path`
+ * — the clean JSONL the Claude Code platform writes per sub-agent, CLI v2.0.42+).
+ * Per LESSON.md this is the RELIABLE anchor for evidence: sidechain PostToolUse
+ * hooks are not guaranteed (issues #43612/#27655/#34692). One parser, reused by
+ * file-attribution (`agent-files.ts`) and retroactive evidence harvesting
+ * (`src/freshness/evidence-harvest.ts`) — no duplication.
+ */
+import { readText } from "../../util/runtime-io";
+
+/** A tool_use content block inside a transcript message. */
+interface ToolUseBlock {
+  type: string;
+  /** Tool name, e.g. "Write", "Edit", "WebSearch", "Grep". */
+  name?: string;
+  /** Raw tool input — shape varies per tool; narrowed at the call-site. */
+  input?: Record<string, unknown>;
+}
+
+/** One JSONL line of a Claude Code transcript. */
+interface TranscriptLine {
+  /** ISO-8601 or epoch-ms timestamp written by the platform (may be absent). */
+  timestamp?: string | number;
+  message?: { content?: unknown[] };
+}
+
+/** A parsed `tool_use`, carrying its message timestamp when the platform stamped one. */
+export interface TranscriptToolUse {
+  /** Tool name, e.g. "Write", "WebSearch", "Read". */
+  name: string;
+  /** Raw tool input payload (shape varies per tool). */
+  input: Record<string, unknown> | undefined;
+  /** Epoch-ms of the enclosing message, or `undefined` when unstamped. */
+  ts?: number;
+}
+
+/** Parse a raw `timestamp` field to epoch ms; `undefined` when absent or invalid. */
+function parseTs(raw: string | number | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw === "number") return raw;
+  const ms = Date.parse(raw);
+  return Number.isFinite(ms) ? ms : undefined;
+}
+
+/**
+ * Scan a sub-agent transcript into its ordered `tool_use` blocks (each with the
+ * enclosing message timestamp). Distinguishes "no tool use" from "cannot read":
+ * returns `null` when the path is absent or the transcript is unreadable (callers
+ * fail-open), or a possibly-empty array when parsed. Malformed lines/blocks are
+ * tolerated and skipped.
+ * @param transcriptPath - Absolute path to the sub-agent's own `.jsonl` transcript.
+ * @returns Ordered tool uses, or `null` when unreadable.
+ */
+export function readAgentToolUses(transcriptPath: string | undefined): TranscriptToolUse[] | null {
+  if (!transcriptPath) return null;
+  let text: string;
+  try {
+    text = readText(transcriptPath);
+  } catch {
+    return null; // fail-open: caller keeps its pre-harvest state
+  }
+  const out: TranscriptToolUse[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let entry: TranscriptLine;
+    try {
+      entry = JSON.parse(line) as TranscriptLine;
+    } catch {
+      continue; // tolerate malformed lines
+    }
+    const content = entry.message?.content;
+    if (!Array.isArray(content)) continue;
+    const ts = parseTs(entry.timestamp);
+    for (const block of content as ToolUseBlock[]) {
+      if (block?.type !== "tool_use" || !block.name) continue;
+      out.push({ name: block.name, input: block.input, ts });
+    }
+  }
+  return out;
+}

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);
+}