@fusengine/harness 0.1.90 → 0.1.91

package/src/config/layout.ts

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+
+/** Top-level project state dir — neutral + harness-agnostic (not `.claude/…`). */
+export const STATE_ROOT = ".harness";
+
+/**
+ * The selective `.gitignore` for `.harness/`: ignore the machine-local session
+ * state (track, cache, throttle) but keep the curated `memory/LESSON.md`.
+ */
+export const STATE_GITIGNORE = "track/\ncache/\nmemory/state.json\n";
+
+/** Every project-state path the package uses, derived from one project root. */
+export interface ProjectLayout {
+  root: string;
+  /** `<root>/.harness` — the single state dir. */
+  stateDir: string;
+  /** `<root>/.harness/track` — session track files. */
+  trackDir: string;
+  /** `<root>/.harness/cache` — MCP/WebFetch cache. */
+  cacheDir: string;
+  /** `<root>/.harness/memory` — lessons + throttle. */
+  memoryDir: string;
+  /** `<root>/.harness/memory/LESSON.md` — curated, committable. */
+  lessonsFile: string;
+  /** `<root>/.harness/memory/state.json` — machine-local throttle. */
+  memoryStateFile: string;
+  /** `<root>/.harness/track/solid-notice.json` — SubagentStop dedup sidecar. */
+  solidNoticeFile: string;
+  /** `<root>/.harness/.gitignore`. */
+  gitignoreFile: string;
+}
+
+/**
+ * The single source of truth for where every package file lives under a project
+ * root. All modules (runtime storage, memory, init) derive their paths here —
+ * nothing hardcodes a directory name elsewhere.
+ */
+export function projectLayout(root: string): ProjectLayout {
+  const stateDir = join(root, STATE_ROOT);
+  const memoryDir = join(stateDir, "memory");
+  return {
+    root,
+    stateDir,
+    trackDir: join(stateDir, "track"),
+    solidNoticeFile: join(stateDir, "track", "solid-notice.json"),
+    cacheDir: join(stateDir, "cache"),
+    memoryDir,
+    lessonsFile: join(memoryDir, "LESSON.md"),
+    memoryStateFile: join(memoryDir, "state.json"),
+    gitignoreFile: join(stateDir, ".gitignore"),
+  };
+}

package/src/config/limits.ts

@@ -0,0 +1,56 @@
+import { parseEnvInt } from "./env";
+
+/** Default SOLID max lines per file. */
+export const DEFAULT_MAX_LINES = 100;
+
+/** Default env var name carrying the max-lines override. */
+export const MAX_LINES_ENV_KEY = "FUSE_SOLID_MAX_LINES";
+
+/**
+ * Resolve the SOLID max-lines limit from an env map.
+ * @param env - environment map (defaults to `process.env`)
+ * @param key - env var name (defaults to `FUSE_SOLID_MAX_LINES`)
+ */
+export function resolveMaxLines(
+  env: Record<string, string | undefined> = process.env,
+  key: string = MAX_LINES_ENV_KEY,
+): number {
+  return parseEnvInt(env[key], DEFAULT_MAX_LINES);
+}
+
+/** Advisory module-split headroom = `maxLines - 10` (never below 1). */
+export function splitTarget(maxLines: number): number {
+  return Math.max(maxLines - 10, 1);
+}
+
+/**
+ * Custom-hook line budget, derived from the global limit (ratio 0.3 — with
+ * the default 100 this yields the owner template's 30; one variable,
+ * `FUSE_SOLID_MAX_LINES`, drives every budget proportionally).
+ * @param maxLines - The global limit (from {@link resolveMaxLines}).
+ */
+export function hookBudget(maxLines: number): number {
+  return Math.max(Math.round(maxLines * 0.3), 1);
+}
+
+/**
+ * Store line budget, derived from the global limit (ratio 0.4 — 40 at the
+ * default 100, per owner rules/07-state-management).
+ * @param maxLines - The global limit (from {@link resolveMaxLines}).
+ */
+export function storeBudget(maxLines: number): number {
+  return Math.max(Math.round(maxLines * 0.4), 1);
+}
+
+/** Default stdin cap for hook payloads: 16 MiB. */
+export const DEFAULT_STDIN_MAX_BYTES: number = 16 * 1024 * 1024;
+
+/**
+ * Resolve the hook stdin cap (`FUSE_HOOK_STDIN_MAX_BYTES`, default 16 MiB;
+ * absent/invalid falls back to the default). The only new env var of the
+ * mission — owner-approved exception.
+ * @param env - environment map (defaults to `process.env`)
+ */
+export function resolveStdinMaxBytes(env: Record<string, string | undefined> = process.env): number {
+  return parseEnvInt(env.FUSE_HOOK_STDIN_MAX_BYTES, DEFAULT_STDIN_MAX_BYTES);
+}

package/src/config/ttl.ts

@@ -0,0 +1,30 @@
+import { parseEnvInt } from "./env";
+
+/**
+ * Default enforcement-freshness window, in seconds (2 minutes). Matches the
+ * plugin's original `FUSE_ENFORCE_TTL_SEC` default. This is the constant that
+ * actually reaches production (via `resolveTtlSec` -> `bin.ts`); `gate.ts`'s
+ * `DEFAULT_WINDOW_MS` is only a fallback for direct programmatic callers that
+ * omit `windowMs` (e.g. tests) and never applies on the real CLI path.
+ */
+export const DEFAULT_TTL_SEC = 120;
+
+/** Default env var name carrying the TTL override. */
+export const TTL_ENV_KEY = "FUSE_ENFORCE_TTL_SEC";
+
+/**
+ * Resolve the enforcement TTL (seconds) from an env map.
+ * @param env - environment map (defaults to `process.env`)
+ * @param key - env var name (defaults to `FUSE_ENFORCE_TTL_SEC`)
+ */
+export function resolveTtlSec(
+  env: Record<string, string | undefined> = process.env,
+  key: string = TTL_ENV_KEY,
+): number {
+  return parseEnvInt(env[key], DEFAULT_TTL_SEC);
+}
+
+/** Human label for a TTL: 120 -> "2min", 240 -> "4min", 90 -> "90s". */
+export function ttlLabel(sec: number): string {
+  return sec % 60 === 0 ? `${sec / 60}min` : `${sec}s`;
+}

package/src/detect/harness.ts

@@ -0,0 +1,73 @@
+/**
+ * Runtime detection of the AI coding harness, and its integration mode.
+ * Env-signal names verified 2026 (agentx, agents.md#136, @vercel/detect-agent,
+ * official Claude Code / Cursor / Gemini / Codex docs). Presence-based: the
+ * value is ignored except for the `AGENT` / `AI_AGENT` standards.
+ */
+import type { HarnessId, HarnessMode, HarnessInfo } from "./interfaces/types";
+
+export type { HarnessId, HarnessMode, HarnessVia, HarnessInfo } from "./interfaces/types";
+
+/** Tool-specific env var (presence) -> harness id. Order = detection priority. */
+const ENV_SIGNALS: ReadonlyArray<readonly [string, HarnessId]> = [
+  ["CLAUDECODE", "claude-code"], ["CODEX_SANDBOX", "codex"],
+  ["CURSOR_AGENT", "cursor"], ["CLINE", "cline"], ["CLINE_AGENT", "cline"],
+  ["GEMINI_CLI", "gemini-cli"], ["OPENCODE", "opencode"],
+  ["WINDSURF_AGENT", "windsurf"], ["CODEIUM_AGENT", "windsurf"],
+  ["COPILOT_AGENT", "copilot"], ["AIDER", "aider"], ["KIRO", "kiro"],
+  ["GOOSE", "goose"], ["AMP", "amp"], ["HERMES_SESSION_ID", "hermes"],
+  // No documented session-marker env var for Kimi Code CLI (unlike CLAUDECODE,
+  // CURSOR_AGENT, ...). `KIMI_CODE_HOME`/`KIMI_PLUGIN_ROOT` are injected only
+  // into PLUGIN-declared hooks (customization/plugins.html: "The hook process
+  // receives two extra environment variables"), never into config.toml hooks —
+  // verified live against kimi-code v0.27.0: a config.toml hook process sees
+  // neither var, and no session marker at all. Detection therefore falls
+  // through to the `AGENT=kimi` / `AI_AGENT=kimi` standard above.
+];
+
+/** `AGENT=<name>` / `AI_AGENT=<name>` standard value -> harness id. */
+const STD_NAMES: Record<string, HarnessId> = {
+  goose: "goose", amp: "amp", claude: "claude-code", "claude-code": "claude-code",
+  cursor: "cursor", codex: "codex", cline: "cline", aider: "aider",
+  opencode: "opencode", gemini: "gemini-cli", copilot: "copilot", kiro: "kiro",
+  hermes: "hermes", kimi: "kimi",
+};
+
+/** Harnesses exposing a native hook system (vs CLI-only integration). */
+const HOOK_CAPABLE: ReadonlySet<HarnessId> = new Set([
+  "claude-code", "codex", "cursor", "cline", "gemini-cli", "opencode", "hermes", "kimi",
+]);
+
+/** Integration mode for a harness id. */
+export function modeFor(id: HarnessId): HarnessMode {
+  return HOOK_CAPABLE.has(id) ? "hook" : "cli";
+}
+
+/**
+ * Detect the current AI coding harness from environment signals.
+ * Priority: `AGENT` standard -> `AI_AGENT` standard -> tool-specific vars -> unknown.
+ * @param env - environment map (defaults to `process.env`)
+ */
+export function detectHarness(
+  env: Record<string, string | undefined> = process.env,
+): HarnessInfo {
+  const agent = env.AGENT?.trim().toLowerCase();
+  const agentId = agent ? STD_NAMES[agent] : undefined;
+  if (agentId) return { id: agentId, mode: modeFor(agentId), via: "agent-std" };
+
+  const ai = env.AI_AGENT?.trim().toLowerCase();
+  const aiId = ai ? STD_NAMES[ai] : undefined;
+  if (aiId) return { id: aiId, mode: modeFor(aiId), via: "ai-agent-std" };
+
+  for (const [key, id] of ENV_SIGNALS) {
+    if (env[key]?.trim()) return { id, mode: modeFor(id), via: "env" };
+  }
+  return { id: "unknown", mode: "cli", via: "fallback" };
+}
+
+/** Convenience: the integration mode of the current harness. */
+export function detectMode(
+  env: Record<string, string | undefined> = process.env,
+): HarnessMode {
+  return detectHarness(env).mode;
+}

package/src/detect/index.ts

@@ -0,0 +1 @@
+export * from "./harness";

package/src/detect/interfaces/types.ts

@@ -0,0 +1,18 @@
+/** Known AI coding harnesses detectable at runtime. */
+export type HarnessId =
+  | "claude-code" | "codex" | "cursor" | "cline" | "gemini-cli"
+  | "opencode" | "windsurf" | "copilot" | "aider" | "kiro"
+  | "goose" | "amp" | "hermes" | "kimi" | "unknown";
+
+/** Integration mode: `hook` = native lifecycle hooks; `cli` = run as an external step. */
+export type HarnessMode = "hook" | "cli";
+
+/** How the harness was identified. */
+export type HarnessVia = "agent-std" | "ai-agent-std" | "env" | "fallback";
+
+/** Result of {@link detectHarness}. */
+export interface HarnessInfo {
+  id: HarnessId;
+  mode: HarnessMode;
+  via: HarnessVia;
+}

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