@fusengine/harness 0.1.90 → 0.1.92

package/src/freshness/agent-evidence-record.ts

@@ -0,0 +1,95 @@
+/**
+ * Session-track agent evidence — writer (parity track-subagent-research.py) +
+ * reader scan (parity apex_agent_helpers._scan_agents). Sub-agent hooks fire
+ * with the LEAD's `session_id`, so evidence recorded here lands in the ONE
+ * session track the freshness gate scans FIRST — sidechain research and
+ * Workflow-spawned agents count, unlike the lead-transcript scan.
+ */
+import { classifyExplore } from "./explore-tools";
+import { withTrack } from "../tracking/store";
+import { recordAgent, type AgentQuality, type SessionTrack } from "../tracking/session-state";
+import { isAgentTool } from "../runtime/is-agent-tool";
+
+/** One classified PostToolUse call, ready to persist as freshness evidence. */
+export interface AgentEvidence {
+  /** Track entry name — `subagent-` + APEX phase (the reader substring-matches). */
+  name: "subagent-explore-codebase" | "subagent-research-expert";
+  /** `sufficient` when the call hit an MCP cache OR its response JSON is >50 chars. */
+  quality: AgentQuality;
+}
+
+/**
+ * `JSON.stringify` length of the raw `tool_response` OBJECT (parity Python
+ * `len(str(tool_response))`); 0 when absent or unserializable (circular).
+ */
+function responseJsonLength(toolResponse: unknown): number {
+  if (toolResponse === undefined || toolResponse === null) return 0;
+  try { return (JSON.stringify(toolResponse) ?? "").length; } catch { return 0; }
+}
+
+/**
+ * Classify one PostToolUse call into session evidence, or null when it is
+ * neither exploration nor research (parity track-subagent-research._classify,
+ * reusing the shared {@link classifyExplore} tables — research/explore/Bash/
+ * cache-read). ANTI-DOUBLE-COUNT: calls classified as agent launches
+ * (`Task`/`Agent`) are skipped — the existing Task tracking credits those; the
+ * criterion is the CALL's classification, never its provenance (lead vs sub).
+ * @param tool - Harness tool name (e.g. "Glob", "Bash", "Read").
+ * @param input - Raw tool input payload.
+ * @param toolResponse - Raw `tool_response` OBJECT from the hook payload.
+ * @returns The evidence to record, or null to skip.
+ */
+export function classifyAgentEvidence(tool: string, input: Record<string, unknown> | undefined, toolResponse: unknown): AgentEvidence | null {
+  if (isAgentTool(tool)) return null;
+  const hit = classifyExplore(tool, input);
+  if (!hit) return null;
+  const name = hit.phase === "explore-codebase" ? "subagent-explore-codebase" : "subagent-research-expert";
+  return { name, quality: hit.cacheHit || responseJsonLength(toolResponse) > 50 ? "sufficient" : "insufficient" };
+}
+
+/**
+ * Persist evidence into the SESSION track via {@link recordAgent} — keyed by
+ * `session_id` alone (sub-agent hooks carry the lead's `session_id`); the TTL
+ * anchors on `ts`, the tool call's own timestamp. `agentId` is tagged as
+ * metadata when present, NEVER used as a condition (unreliable field —
+ * anthropics/claude-code#22348).
+ * @param file - Session track file path.
+ * @param evidence - Classified evidence from {@link classifyAgentEvidence}.
+ * @param ts - Epoch-ms timestamp of the tool call (the hook event's `now`).
+ * @param agentId - Optional Claude `agent_id` — metadata tag only.
+ */
+export async function recordAgentEvidence(file: string, evidence: AgentEvidence, ts: number, agentId?: string): Promise<void> {
+  await withTrack(file, (track) => {
+    const next = recordAgent(track, evidence.name, ts, evidence.quality);
+    const last = next.agents[next.agents.length - 1];
+    if (agentId && last) {
+      const tagged: SessionTrack["agents"][number] & { agentId?: string } = { ...last, agentId };
+      next.agents[next.agents.length - 1] = tagged;
+    }
+    return next;
+  });
+}
+
+/**
+ * Parity `_scan_agents` (apex_agent_helpers.py): reverse-scan `track.agents`,
+ * STOPPING at the first entry older than `windowMs` (entries append in time
+ * order), matching each required name by SUBSTRING (`research-expert` matches
+ * `subagent-research-expert`) and counting ONLY `quality === "sufficient"`.
+ * @param track - The loaded session track.
+ * @param names - Required agent names — ALL must match to return true.
+ * @param windowMs - Freshness window (ms), anchored on each entry's `ts`.
+ * @param now - Current epoch ms.
+ * @returns True when every required name has fresh, sufficient evidence.
+ */
+export function agentsFreshInTrack(track: SessionTrack, names: readonly string[], windowMs: number, now: number): boolean {
+  const found = new Set<string>();
+  for (let i = track.agents.length - 1; i >= 0; i--) {
+    const entry = track.agents[i];
+    if (!entry) continue;
+    if (now - entry.ts > windowMs) break;
+    if (entry.quality !== "sufficient") continue;
+    for (const req of names) if (entry.name.includes(req)) found.add(req);
+    if (found.size === names.length) return true;
+  }
+  return names.every((n) => found.has(n));
+}

package/src/freshness/agent-evidence.ts

@@ -0,0 +1,95 @@
+/**
+ * Platform-authored transcript evidence for APEX agent freshness. Parses the
+ * Claude Code session JSONL transcript for genuine dispatch tool_use entries
+ * — forging requires writing into the platform-controlled transcript file.
+ */
+import { readText } from "../util/runtime-io";
+import { classifyExplore } from "./explore-tools";
+import { isAgentTool } from "../runtime/is-agent-tool";
+
+/** Raw shape of one JSONL line in a Claude Code transcript. */
+interface TranscriptLine {
+  /** ISO-8601 or epoch-ms timestamp written by the platform. */
+  timestamp?: string | number;
+  message?: { content?: unknown[] };
+}
+
+/** A tool_use content block inside a transcript message. */
+interface ToolUseBlock {
+  type: string;
+  name?: string;
+  input?: Record<string, unknown>;
+}
+
+/** 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;
+}
+
+/**
+ * Return `true` ONLY when, for EVERY name in `names`, the transcript at
+ * `transcriptPath` shows a within-window genuine `tool_use`: a dispatch tool
+ * ({@link isAgentTool}) whose `subagent_type`/`name` (plugin prefix stripped)
+ * matches, OR a direct exploration/research call classified into that name by
+ * {@link classifyExplore} — issued by any sub-agent or the lead (the transcript
+ * carries no author field). Entries without `timestamp` count as within-window
+ * (format-evolution leniency; tamper-resistance comes from platform authoring).
+ * @param transcriptPath - Session `.jsonl` transcript (`transcript_path`); false when undefined.
+ * @param names - Required agent `subagent_type` values — ALL must appear.
+ * @param windowMs - Freshness window in milliseconds.
+ * @param now - Current epoch ms (pass `Date.now()` at the call-site).
+ * @returns `true` when ALL agents have real, within-window transcript evidence.
+ */
+export function agentsRanFromTranscript(
+  transcriptPath: string | undefined,
+  names: readonly string[],
+  windowMs: number,
+  now: number,
+): boolean {
+  if (!transcriptPath || names.length === 0) return false;
+  let text: string;
+  try {
+    text = readText(transcriptPath);
+  } catch {
+    return false;
+  }
+  const cutoff = now - windowMs;
+  const found = new Set<string>();
+  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 ts = parseTs(entry.timestamp);
+    if (ts !== undefined && ts <= cutoff) continue;
+    const content = entry.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content as ToolUseBlock[]) {
+      if (block?.type !== "tool_use") continue;
+      if (block.name !== undefined && isAgentTool(block.name)) {
+        const raw = block.input?.subagent_type ?? block.input?.name;
+        // Strip any plugin prefix (`fuse-ai-pilot:research-expert` → `research-expert`)
+        // before matching the bare REQUIRED_AGENTS names.
+        const agent = typeof raw === "string" ? raw.split(":").pop() ?? raw : undefined;
+        if (agent !== undefined && (names as string[]).includes(agent)) found.add(agent);
+        continue;
+      }
+      // Direct exploration/research tool_use — credited to the matching phase
+      // regardless of which sub-agent (or the lead) issued it: the transcript
+      // carries no author field distinguishing sidechains, so — mirroring the
+      // pre-existing self-recorded-track behavior in `runtime/activity.ts` —
+      // ANY Glob/Grep/mcp__context7/mcp__exa/WebSearch/WebFetch/explore-Bash
+      // tool_use in this session's transcript counts as freshness evidence.
+      const hit = classifyExplore(block.name ?? "", block.input);
+      if (hit && (names as string[]).includes(hit.phase)) found.add(hit.phase);
+    }
+    if (found.size === names.length) return true;
+  }
+  return names.every((n) => found.has(n));
+}

package/src/freshness/codex-spawn-evidence.ts

@@ -0,0 +1,91 @@
+/**
+ * Codex multi_agent_v2 `spawn_agent` -> session evidence bridge. Codex's custom
+ * agents (fusengine multi_agent_v2, e.g. sniper/explore-codebase) are launched
+ * via a `spawn_agent` TOOL CALL inside the SAME session -- Codex has no
+ * SubagentStart/SubagentStop lifecycle for them, so the existing Claude-side
+ * evidence paths (agent-evidence-record.ts `classifyAgentEvidence`, the
+ * SubagentStop harvest) never observe them; the harness only ever saw a
+ * generic tool call. This module credits the SAME session track
+ * ({@link recordAgent}, read back by `agent-evidence-record.ts`
+ * `agentsFreshInTrack`) straight from that PostToolUse `spawn_agent` call.
+ *
+ * SOURCE (openai/codex@44918ea1, tag rust-v0.144.1 -- verified upstream,
+ * not re-checked here): the hook `tool_name` is `"spawn_agent"` normally, or
+ * the SEPARATOR-LESS namespace-prefixed `{namespace}spawn_agent` when the
+ * `namespace_tools` capability provider is active (e.g.
+ * `"fusengine_agentsspawn_agent"`, `"collaborationspawn_agent"`). Detection is
+ * `tool_name === "spawn_agent" || tool_name.endsWith("spawn_agent")` -- a tool
+ * that merely CONTAINS the substring without being an exact/suffix match
+ * (`"spawn_agentX"`, `"myspawn_agent_tool"`) is correctly rejected.
+ * `tool_input.agent_type` carries the spawned agent's type only when Codex's
+ * `hide_spawn_agent_metadata=false`; treat it as always-optional.
+ *
+ * INVARIANT (multi-harness parity): every entry point here is gated on
+ * `id === "codex"` FIRST -- claude-code/cursor/cline/gemini-cli/hermes always
+ * take the early return, touching neither the track nor disk. Byte-identical
+ * elsewhere by construction.
+ */
+import { recordAgent, type SessionTrack } from "../tracking/session-state";
+import { withTrack } from "../tracking/store";
+
+/**
+ * True when `tool` is Codex's `spawn_agent` primitive, bare or
+ * namespace-prefixed (no separator). Rejects any tool that merely contains
+ * the substring elsewhere in its name.
+ * @param tool - Raw/normalized `tool_name` from the hook payload.
+ */
+export function isCodexSpawnAgentTool(tool: string): boolean {
+  return tool === "spawn_agent" || tool.endsWith("spawn_agent");
+}
+
+/**
+ * Extract the spawned agent's type from a `spawn_agent` `tool_input`, or
+ * `undefined` when absent/blank (`hide_spawn_agent_metadata=true`, or a
+ * future Codex build omitting it) -- never throws.
+ * @param input - Raw `tool_input` payload (harness `event.input`).
+ */
+export function codexSpawnAgentType(input: Record<string, unknown> | undefined): string | undefined {
+  const v = input?.agent_type;
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+}
+
+/**
+ * Pure classifier + folder: credit a Codex `spawn_agent` call into
+ * `track.agents` under the SAME `subagent-<name>` convention the Claude-side
+ * explore/research evidence uses -- so an `agent_type` that happens to match
+ * a `REQUIRED_AGENTS` name (e.g. `"explore-codebase"`) is picked up by
+ * `agentsFreshInTrack`'s substring match exactly like genuine Claude
+ * Task/Agent evidence. Immutable: returns `track` UNCHANGED (same reference)
+ * for any other harness `id`, any non-spawn tool, or a missing `agent_type`.
+ * @param id - Harness id (only `"codex"` ever credits).
+ * @param tool - Normalized event tool name (raw `tool_name`).
+ * @param input - Raw `tool_input` payload.
+ * @param track - The current session track.
+ * @param ts - Epoch-ms timestamp of the tool call.
+ * @returns The credited track, or `track` itself when nothing was credited.
+ */
+export function creditCodexSpawnAgent(id: string, tool: string, input: Record<string, unknown> | undefined, track: SessionTrack, ts: number): SessionTrack {
+  if (id !== "codex" || !isCodexSpawnAgentTool(tool)) return track;
+  const agentType = codexSpawnAgentType(input);
+  if (!agentType) return track;
+  return recordAgent(track, `subagent-${agentType}`, ts, "sufficient");
+}
+
+/**
+ * I/O wiring for {@link creditCodexSpawnAgent}: load the session track, fold
+ * in the credit, and persist only when something actually changed (skips a
+ * write for the strict no-op cases). Mirrors `agent-evidence-record.ts`
+ * `recordAgentEvidence`'s async load/save shape.
+ * @param file - Session track file path (same one the freshness gate reads).
+ * @param id - Harness id (only `"codex"` ever credits).
+ * @param tool - Normalized event tool name (raw `tool_name`).
+ * @param input - Raw `tool_input` payload.
+ * @param ts - Epoch-ms timestamp of the tool call.
+ */
+export async function recordCodexSpawnEvidence(file: string, id: string, tool: string, input: Record<string, unknown> | undefined, ts: number): Promise<void> {
+  if (id !== "codex" || !isCodexSpawnAgentTool(tool)) return;
+  await withTrack(file, (track) => {
+    const next = creditCodexSpawnAgent(id, tool, input, track, ts);
+    return next !== track ? next : track;
+  });
+}

package/src/freshness/doc-helpers.ts

@@ -0,0 +1,90 @@
+/**
+ * Documentation-consultation freshness: was ANY documentation source consulted
+ * this session — Context7, Exa, or WebSearch/WebFetch — via a live call or a
+ * Read on a cached MCP result file?
+ */
+
+/** Authorization entry from APEX state (legacy session + new sessions[]). */
+export interface AuthEntry {
+  source?: string;
+  sources?: string[];
+  sessions?: string[];
+  session?: string;
+  doc_sessions?: string[];
+  read_paths?: string[];
+  /** ISO stamp of the latest doc/skill consultation for this framework (Check-1 TTL, parity enforce-apex-phases.ts). */
+  doc_consulted?: string;
+}
+
+/** Resolve the sessions array from an auth entry (legacy fallback). */
+export function resolveSessions(auth: AuthEntry | undefined): string[] {
+  if (!auth) return [];
+  return auth.sessions ?? (auth.session ? [auth.session] : []);
+}
+
+function sessionAuthsFor(
+  authorizations: Record<string, AuthEntry> | undefined,
+  sessionId: string,
+): AuthEntry[] {
+  if (!authorizations) return [];
+  return Object.values(authorizations).filter((a) => a.doc_sessions?.includes(sessionId));
+}
+
+/** Per-source satisfaction status for a session. */
+export interface DocSatisfactionStatus {
+  context7: boolean;
+  exa: boolean;
+  web: boolean;
+  viaCache: boolean;
+}
+
+function evaluateDoc(auths: AuthEntry[]): DocSatisfactionStatus {
+  const sources = auths.flatMap((a) => a.sources ?? [a.source ?? ""]);
+  const readPaths = auths.flatMap((a) => a.read_paths ?? []);
+  const liveC7 = sources.some((s) => /context7/i.test(s));
+  const liveExa = sources.some((s) => /exa/i.test(s));
+  const liveWeb = sources.some((s) => /web(search|fetch)|fuse-browser/i.test(s));
+  const cacheC7 = readPaths.some((p) => /\/context\/mcp\/context7-/.test(p));
+  const cacheExa = readPaths.some((p) => /\/context\/mcp\/(exa-search|exa-code-context)-/.test(p));
+  return {
+    context7: liveC7 || cacheC7,
+    exa: liveExa || cacheExa,
+    web: liveWeb,
+    viaCache: (!liveC7 && cacheC7) || (!liveExa && cacheExa),
+  };
+}
+
+/**
+ * True when documentation research is satisfied for the session. Primary path
+ * is parity with the Python `mcp_research_done`
+ * (`_shared/scripts/check_skill_common.py`): `"context7:" in content and
+ * "exa:" in content`, a strict AND (the Python source has no web-alone path).
+ * `web` (WebSearch/WebFetch/fuse-browser) is a deliberate TS-side addition —
+ * it alone satisfies the gate, since fuse-browser is this harness's preferred
+ * doc-research fast-path (see CLAUDE.md) and Context7/Exa can be unavailable.
+ */
+export function isDocConsulted(
+  authorizations: Record<string, AuthEntry> | undefined,
+  sessionId: string,
+): boolean {
+  const s = evaluateDoc(sessionAuthsFor(authorizations, sessionId));
+  return (s.context7 && s.exa) || s.web;
+}
+
+/** Report how each doc source was satisfied for a session. */
+export function formatDocSatisfactionStatus(
+  authorizations: Record<string, AuthEntry> | undefined,
+  sessionId: string,
+): DocSatisfactionStatus {
+  return evaluateDoc(sessionAuthsFor(authorizations, sessionId));
+}
+
+/** Deny message when online documentation has not been consulted. */
+export function formatDocDeny(framework: string): string {
+  return [
+    `BLOCKED: No MCP research done for ${framework}. Use BOTH:`,
+    "1) mcp__context7__query-docs AND 2) mcp__exa__web_search_exa",
+    "— OR a web fallback alone: mcp__fuse-browser__browser_fetch / browser_crawl / browser_serp_batch, WebSearch, or WebFetch.",
+    "This check is once per session — after consulting the required source(s), Write/Edit will be allowed.",
+  ].join("\n");
+}

package/src/freshness/evidence-harvest-io.ts

@@ -0,0 +1,72 @@
+/**
+ * SubagentStop wiring for {@link harvestAgentEvidence}. The core SubagentStop
+ * dispatch (`runtime/lifecycle/dispatch.ts`) is SYNCHRONOUS and runs in a
+ * short-lived hook process, so this does SYNC track I/O (load → harvest → save)
+ * rather than the async `loadTrack`/`saveTrack`: a floating async write could be
+ * dropped before the process exits. Mirrors the sync read precedent in
+ * `policy/design/skill-evidence.ts` and the exact save body of `tracking/store.ts`
+ * (`signTrack` → atomic write → `writeLastNonce`) — kept sync on purpose here.
+ */
+import { readFileSync } from "node:fs";
+import { harvestAgentEvidence } from "./evidence-harvest";
+import { defaultStateDir, trackFile } from "../runtime/paths";
+import { emptyTrack, type SessionTrack } from "../tracking/session-state";
+import { signTrack, verifyTrack, writeLastNonce, type TrackEnvelope } from "../tracking/integrity";
+import { atomicWrite } from "../util/json-io";
+import { LOCK_FAILED, withTrackLockSync } from "../tracking/track-lock-sync";
+import { trackJournalEnabled } from "../tracking/store";
+import { appendEvent } from "../tracking/track-journal";
+import { diffTrackEvents } from "../tracking/track-diff";
+import { journalLogPath, readTrackSync } from "../tracking/track-compact";
+import { dirname } from "node:path";
+
+/** Load the current track synchronously; `emptyTrack()` when absent/corrupt (fail-closed read). */
+function loadTrackSync(file: string): SessionTrack {
+  try {
+    return verifyTrack(JSON.parse(readFileSync(file, "utf8")) as TrackEnvelope) ?? emptyTrack();
+  } catch {
+    return emptyTrack();
+  }
+}
+
+/**
+ * Harvest the finishing sub-agent's transcript into its session track. Runs for
+ * EVERY agent type (unlike the sniper reminder, which skips research/explore) —
+ * those are exactly the agents whose research/explore evidence we want to credit.
+ * Fully fail-open: a missing `agent_transcript_path`, an unreadable transcript, or
+ * a write error leaves the track untouched and never throws out of the hook.
+ * @param payload - The raw SubagentStop hook payload.
+ * @param cwd - Project root (selects the per-project state dir).
+ * @param now - Fallback epoch-ms for unstamped transcript tool_uses.
+ * @param baseDir - Override the track base dir (tests); defaults to the project state dir.
+ */
+export function harvestSubagentTrack(payload: Record<string, unknown>, cwd: string, now: number, baseDir: string = defaultStateDir(cwd)): void {
+  const transcriptPath = typeof payload.agent_transcript_path === "string" ? payload.agent_transcript_path : undefined;
+  if (!transcriptPath) return;
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+  const file = trackFile(sessionId, baseDir);
+  // Journal mode (default): snapshot ⊕ log read, then lock-free signed event
+  // appends — same fail-open contract, never a "write skipped" under fan-out.
+  if (trackJournalEnabled()) {
+    const track = readTrackSync(file, true);
+    const next = harvestAgentEvidence(transcriptPath, track, now);
+    if (next === track) return; // nothing harvested → no write
+    const log = journalLogPath(file);
+    for (const ev of diffTrackEvents(track, next, now)) appendEvent(log, ev.field, ev.op, ev.value, ev.ts);
+    return;
+  }
+  // Locked RMW (legacy kill-switch path, sync variant — this path cannot float
+  // async work): on contention the harvest is skipped like any other write
+  // error, fail-open.
+  const ran = withTrackLockSync(dirname(file), () => {
+    const track = loadTrackSync(file);
+    const next = harvestAgentEvidence(transcriptPath, track, now);
+    if (next === track) return; // nothing harvested (or unreadable) → no rewrite
+    try {
+      const envelope = signTrack(next);
+      atomicWrite(file, JSON.stringify(envelope, null, 2));
+      writeLastNonce(envelope.nonce);
+    } catch { /* fail-open: a lifecycle hook must never throw */ }
+  });
+  if (ran === LOCK_FAILED) return;
+}

package/src/freshness/evidence-harvest.ts

@@ -0,0 +1,61 @@
+/**
+ * Retroactive evidence harvest at SubagentStop. Parses a completed sub-agent's
+ * OWN transcript (`agent_transcript_path`) and backfills the session track with
+ * the research/explore tool_use it performed (→ `agents`) and the `.md` reference
+ * files it read (→ `refsReadAt`). Per LESSON.md + issues #43612/#27655/#34692,
+ * sidechain PostToolUse hooks are NOT guaranteed to fire, so live in-session
+ * crediting is only opportunistic; SubagentStop is dispatched by the main session
+ * (reliable), and its transcript is the durable anchor this harvest reads.
+ *
+ * QUALITY: harvested agent evidence is credited `sufficient`. The freshness reader
+ * (`agentsFreshInTrack`) ignores `insufficient` entries, so anything less would
+ * make the harvest inert. This is sound: the platform-authored transcript proves
+ * the tool genuinely ran to completion in a finished sub-agent — a STRONGER
+ * guarantee than the live path's response-size heuristic (an anti-gaming measure
+ * for the self-recorded track, which the transcript's provenance supersedes).
+ */
+import { classifyAgentEvidence } from "./agent-evidence-record";
+import { readAgentToolUses, type TranscriptToolUse } from "../runtime/lifecycle/agent-transcript";
+import { recordAgent, recordRefRead, type SessionTrack } from "../tracking/session-state";
+
+/** Dedup tolerance (ms) against evidence a live sidechain hook may already hold. */
+const DEDUP_MS = 2000;
+
+/** True when an `agents` entry with `name` already sits within ±{@link DEDUP_MS} of `ts`. */
+function agentAlreadyRecorded(track: SessionTrack, name: string, ts: number): boolean {
+  return track.agents.some((a) => a.name === name && Math.abs(a.ts - ts) <= DEDUP_MS);
+}
+
+/**
+ * Fold one transcript tool_use into the track (immutably): credit classified
+ * research/explore evidence to `agents` (deduped, forced `sufficient`) and any
+ * `.md` Read to `refsReadAt` (never restamping a MORE-recent existing read).
+ * Returns the same reference when the call contributes nothing.
+ */
+function applyToolUse(track: SessionTrack, u: TranscriptToolUse, fallbackNow: number): SessionTrack {
+  const ts = u.ts ?? fallbackNow;
+  let next = track;
+  const ev = classifyAgentEvidence(u.name, u.input, undefined);
+  if (ev && !agentAlreadyRecorded(next, ev.name, ts)) next = recordAgent(next, ev.name, ts, "sufficient");
+  if (u.name === "Read") {
+    const path = String(u.input?.file_path ?? u.input?.path ?? "");
+    const prev = next.refsReadAt?.[path];
+    if (path.endsWith(".md") && (prev === undefined || prev < ts)) next = recordRefRead(next, path, ts);
+  }
+  return next;
+}
+
+/**
+ * Backfill `track` from the sub-agent transcript at `transcriptPath`. PURE: the
+ * caller owns load/save. Fail-open — an absent or unreadable transcript returns
+ * `track` UNCHANGED (same reference), never throwing.
+ * @param transcriptPath - Sub-agent's own `.jsonl` (SubagentStop `agent_transcript_path`).
+ * @param track - The current session track.
+ * @param now - Fallback epoch-ms for tool_uses the platform left unstamped.
+ * @returns The backfilled track, or `track` itself when nothing was harvested.
+ */
+export function harvestAgentEvidence(transcriptPath: string | undefined, track: SessionTrack, now: number): SessionTrack {
+  const uses = readAgentToolUses(transcriptPath);
+  if (uses === null) return track; // unreadable → unchanged (no regression)
+  return uses.reduce((acc, u) => applyToolUse(acc, u, now), track);
+}

package/src/freshness/explore-tools.ts

@@ -0,0 +1,95 @@
+/**
+ * Classifier crediting DIRECT (lead-agent) exploration/research tool use as the
+ * matching APEX phase, so the freshness gate's self-recorded fallback accepts
+ * genuine direct work — not only `Task`/`Agent` sub-agent spawns. Mirrors the
+ * Python core-guards `_shared/apex_constants.py` + `track-subagent-research.py`.
+ */
+
+/** A REQUIRED_AGENTS name credited for a classified direct tool use. */
+export type ExplorePhase = "explore-codebase" | "research-expert";
+
+/** Outcome of classifying one direct tool use. */
+export interface ExploreHit {
+  /** APEX phase credited (a REQUIRED_AGENTS name). */
+  phase: ExplorePhase;
+  /** Reads of a cached MCP result count as `sufficient` regardless of length. */
+  cacheHit: boolean;
+}
+
+/** Native exploration tools (parity `apex_constants.EXPLORE_TOOLS`). */
+const EXPLORE_TOOLS = new Set(["Glob", "Grep"]);
+
+/**
+ * Research tools — MCP docs + web (parity `apex_constants.RESEARCH_TOOLS`).
+ * The fuse-browser fast-path entries are a deliberate TS addition: CLAUDE.md
+ * mandates fuse-browser FIRST for web research, and `docSourceOf` (activity.ts)
+ * already credits it for doc consultation — without them here, an agent
+ * following the rules would never satisfy the freshness gate (same
+ * cross-consumer inconsistency class as the solidReadGate lesson).
+ */
+const RESEARCH_TOOLS = new Set([
+  "mcp__context7__query-docs",
+  "mcp__context7__resolve-library-id",
+  "mcp__exa__web_search_exa",
+  "mcp__exa__get_code_context_exa",
+  "mcp__exa__deep_researcher_start",
+  "WebSearch",
+  "WebFetch",
+  "FetchURL", // Kimi Code CLI's WebFetch-equivalent tool name (docs/reference/tools.html)
+  "mcp__fuse-browser__browser_fetch",
+  "mcp__fuse-browser__browser_fetch_batch",
+  "mcp__fuse-browser__browser_crawl",
+  "mcp__fuse-browser__browser_serp_batch",
+]);
+
+/** Bash executables that count as exploration (parity `EXPLORE_BASH_CMDS`). */
+const EXPLORE_BASH_CMDS = new Set(["grep", "rg", "find", "ls", "fd", "ast-grep", "tree", "cat", "head", "tail"]);
+
+/** Legacy Python cache names still credited (parity `CACHE_READ_RE` + doc-helpers). */
+const CACHE_READ_RE = /\/context\/mcp\/(exa-search|exa-code-context|context7)-/;
+
+/**
+ * Real TS cache stores: `<root>/.harness/cache/<fnv16>.md` (core MCP store,
+ * `projectLayout().cacheDir`) and `~/.fuse-harness/cache/**` (ai-pilot doc
+ * caches, `cache-base.cacheBaseDir`). Segment-matched — not resolved against
+ * `homedir()` — so tilde-prefixed and absolute paths both hit; the `.md`
+ * suffix keeps session-state JSON reads from counting as research.
+ */
+const TS_CACHE_READ_RE = /\.(?:fuse-)?harness[\\/]cache[\\/].*\.md$/;
+
+/**
+ * First non-assignment shell token's basename, or "" — mirrors Python
+ * `_bash_executable` (skips leading `VAR=value` env prefixes, e.g. `FOO=1 grep`).
+ * @param cmd - Raw Bash `command` string.
+ * @returns The executable basename, or "" when none.
+ */
+function bashExecutable(cmd: string): string {
+  for (const token of cmd.trim().split(/\s+/)) {
+    if (!token) continue;
+    const last = token.split("/").pop() ?? token;
+    if (!last.includes("=")) return last;
+  }
+  return "";
+}
+
+/**
+ * Classify a direct tool use into an APEX phase, or `null` when it is neither
+ * exploration nor research. Mirrors Python `track-subagent-research._classify`.
+ * @param tool - Harness tool name (e.g. "Glob", "Bash", "WebSearch").
+ * @param input - Tool input payload.
+ * @returns The credited phase + cache flag, or `null`.
+ */
+export function classifyExplore(tool: string, input: Record<string, unknown> | undefined): ExploreHit | null {
+  if (RESEARCH_TOOLS.has(tool)) return { phase: "research-expert", cacheHit: false };
+  if (EXPLORE_TOOLS.has(tool)) return { phase: "explore-codebase", cacheHit: false };
+  if (tool === "Read") {
+    const path = String(input?.file_path ?? input?.path ?? "");
+    if (path && (CACHE_READ_RE.test(path) || TS_CACHE_READ_RE.test(path))) return { phase: "research-expert", cacheHit: true };
+    return null;
+  }
+  if (tool === "Bash") {
+    const cmd = String(input?.command ?? "").trim();
+    if (EXPLORE_BASH_CMDS.has(bashExecutable(cmd))) return { phase: "explore-codebase", cacheHit: false };
+  }
+  return null;
+}

package/src/freshness/index.ts

@@ -0,0 +1,2 @@
+export * from "./doc-helpers";
+export * from "./trivial-edit-counter";