@fusengine/harness 0.1.89 → 0.1.91

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";

package/src/freshness/query-framework.ts

@@ -0,0 +1,73 @@
+/**
+ * Framework classification for doc consultations, keyed on the QUERY text
+ * (parity ai-pilot/scripts/track_doc_helpers.py::detect_framework): an MCP
+ * doc call (context7/exa/web) has no filePath, so the file-based
+ * `detectFramework()` always yields "generic" — the query keywords are the
+ * only framework signal a doc consultation carries.
+ */
+
+/**
+ * Ordered patterns, EXACT parity with the Python list (same order, same
+ * case-sensitive alternations, substring search — only `go` is word-bounded).
+ * Quirks are inherited deliberately: "javascript" hits `java` (but only after
+ * nextjs/react/laravel/swift/tailwind all missed) and all-caps "NEXT" misses.
+ * The output domain matches `detectFramework()` exactly, so every credit
+ * lands on a key the apex authorization gate actually reads.
+ */
+const QUERY_FRAMEWORKS: ReadonlyArray<readonly [RegExp, string]> = [
+  [/(next|nextjs|Next)/, "nextjs"],
+  [/(react|React)/, "react"],
+  [/(laravel|Laravel|php|PHP)/, "laravel"],
+  [/(swift|Swift|swiftui|SwiftUI)/, "swift"],
+  [/(tailwind|Tailwind)/, "tailwind"],
+  [/(java|Java|spring|Spring)/, "java"],
+  [/\b(go|Go|golang)\b/, "go"],
+  [/(ruby|Ruby|rails|Rails)/, "ruby"],
+  [/(rust|Rust|cargo|Cargo)/, "rust"],
+];
+
+/**
+ * The framework a doc query targets, or null when no keyword matches (the
+ * Python returns "generic"; null here lets the caller fall back to the
+ * event's file-detected framework instead of hardcoding generic).
+ * @param query - The query/url/prompt text of the doc tool call.
+ */
+export function frameworkFromQuery(query: string): string | null {
+  for (const [re, fw] of QUERY_FRAMEWORKS) if (re.test(query)) return fw;
+  return null;
+}
+
+/**
+ * tool_input fields carrying query text across doc tools: context7
+ * (`libraryId`/`libraryName`, parity extract_tool_info), exa/WebSearch
+ * (`query`), fuse-browser serp (`queries[]`), WebFetch (`url` + `prompt`).
+ */
+const QUERY_FIELDS = ["query", "queries", "libraryId", "libraryName", "prompt", "url"] as const;
+
+/**
+ * Fold every query-ish tool_input field into one searchable string. Distinct
+ * from mcp-key.ts `queryOf`, which picks a SINGLE field to key the response
+ * cache — classification wants ALL the text (e.g. WebFetch url + prompt).
+ * @param input - The normalized tool_input (absent on some harnesses).
+ */
+export function docQueryOf(input: Record<string, unknown> | undefined): string {
+  if (!input) return "";
+  const parts: string[] = [];
+  for (const key of QUERY_FIELDS) {
+    const v = input[key];
+    if (typeof v === "string") parts.push(v);
+    else if (Array.isArray(v)) for (const s of v) if (typeof s === "string") parts.push(s);
+  }
+  return parts.join(" ");
+}
+
+/**
+ * The framework to credit for a doc consultation: the query's framework when
+ * a keyword matches (query wins over file-based detection), else `fallback`
+ * (the event's framework — "generic" for pathless MCP calls).
+ * @param input - The doc tool's tool_input.
+ * @param fallback - The event's file-detected framework.
+ */
+export function docFramework(input: Record<string, unknown> | undefined, fallback: string): string {
+  return frameworkFromQuery(docQueryOf(input)) ?? fallback;
+}

package/src/freshness/ref-evidence.ts

@@ -0,0 +1,49 @@
+/**
+ * Platform-transcript reconciliation for `.md` reference reads — the durable
+ * counterpart to {@link agentsRanFromTranscript} for agent freshness.
+ *
+ * WHY: the session track is persisted by a non-atomic load→mutate→save. Under
+ * the multi-plugin hook fan-out (one hook process per installed plugin, ×N) plus
+ * back-to-back tool events, concurrent writers clobber each other (lost update).
+ * `agents`/`authorizations` self-heal — every explore/research/doc call rewrites
+ * them, so a lost update lands again on the next of hundreds of writes — but a
+ * `refsRead` entry is written ONCE (when the `.md` is Read), so a single lost
+ * update erases it permanently, and the lead has no SubagentStop
+ * {@link harvestAgentEvidence} pass to reconcile it (sub-agents do, which is why
+ * only the LEAD's solidReadGate never credited). The Claude-authored transcript
+ * is append-only and race-immune, so folding its `.md` Reads back into the track
+ * restores the lost evidence; each gate still applies its own TTL/session policy.
+ */
+import { readAgentToolUses } from "../runtime/lifecycle/agent-transcript";
+import { recordRefRead, type SessionTrack } from "../tracking/session-state";
+
+/**
+ * Fold every `.md` `Read` in the transcript into `track` as a timestamped ref
+ * read (immutably). PURE reconciliation — the caller owns the track; each read
+ * is stamped with its transcript timestamp (unstamped → `now`, lenient, matching
+ * {@link agentsRanFromTranscript}), and an existing MORE-recent stamp is never
+ * rolled back. Fail-open: an absent/unreadable transcript returns `track`
+ * unchanged (same reference).
+ * @param track - The current (possibly race-damaged) session track.
+ * @param transcriptPath - Claude `transcript_path` for this session.
+ * @param now - Fallback epoch-ms for transcript entries the platform left unstamped.
+ * @returns The track with transcript `.md` reads merged into `refsRead`/`refsReadAt`.
+ */
+export function reconcileRefReadsFromTranscript(
+  track: SessionTrack,
+  transcriptPath: string | undefined,
+  now: number,
+): SessionTrack {
+  const uses = readAgentToolUses(transcriptPath);
+  if (!uses) return track; // unreadable → unchanged (no regression)
+  let next = track;
+  for (const u of uses) {
+    if (u.name !== "Read") continue;
+    const path = String(u.input?.file_path ?? u.input?.path ?? "");
+    if (!path.endsWith(".md")) continue;
+    const ts = u.ts ?? now;
+    const prev = next.refsReadAt?.[path];
+    if (prev === undefined || prev < ts) next = recordRefRead(next, path, ts);
+  }
+  return next;
+}

package/src/freshness/ref-journal.ts

@@ -0,0 +1,98 @@
+/**
+ * Append-only journal of `.md` reference reads — the FRESH, race-immune companion
+ * to {@link reconcileRefReadsFromTranscript}.
+ *
+ * WHY a third source (track + transcript were not enough for teammates): the live
+ * session track write is a non-atomic load→mutate→save, so under the multi-plugin
+ * hook fan-out (one process per plugin, ×N) a lone `refsRead` write is clobbered
+ * (lost update). The transcript reconcile recovers the LEAD's lost reads because,
+ * by the time the lead edits, its Read has flushed to the platform transcript. But
+ * the platform flushes that JSONL to disk with a MULTI-MINUTE lag (measured ~230s,
+ * well past the 120s freshness TTL): a background TEAMMATE reads the exact listed
+ * ref then edits within seconds — far faster than the flush — so the transcript on
+ * disk does NOT yet contain the teammate's read, reconcile misses it, and (its live
+ * track write having been lost to the fan-out) solidReadGate blocks despite a
+ * genuine read. That is the "teammate solidRead" gap.
+ *
+ * This journal closes it: every credited `.md` read is appended (one JSON line) the
+ * instant PostToolUse fires — O_APPEND is per-write atomic, so concurrent fan-out
+ * processes each add their own line and none is lost, and there is no flush lag. The
+ * gate folds it back BEFORE any refsRead consumer, alongside the transcript.
+ *
+ * ANTI-FORGERY: it lives in the out-of-tree state dir the protected-path guard
+ * denies agents from writing (SAME boundary as the signed track); the only writer is
+ * our PostToolUse on a real `.md` Read. COST: the gate reads it once per edit, bounded
+ * by {@link appendRefRead}'s trim cap — cheaper than the multi-MB transcript parse.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { readText } from "../util/runtime-io";
+import { trimLogFile } from "../runtime/fs-cleanup";
+import { recordRefRead, type SessionTrack } from "../tracking/session-state";
+
+/** Journal filename inside the per-session state dir. */
+const JOURNAL = "refs-read.log";
+
+/** One journalled read: `.md` path plus the tool event's epoch-ms timestamp. */
+interface RefReadLine {
+  p: string;
+  t: number;
+}
+
+/**
+ * Append a credited `.md` read to the state-dir journal (O_APPEND, atomic under
+ * the fan-out). No-op for non-`.md` paths (parity with the reconcile filter).
+ * Fully fail-open: a mkdir/append error is swallowed so recording never blocks the
+ * PostToolUse path.
+ * @param dir - Per-session state dir (`dirname(trackFile)`).
+ * @param path - The read file's absolute path.
+ * @param ts - The tool event's epoch-ms timestamp.
+ */
+export function appendRefRead(dir: string, path: string, ts: number): void {
+  if (!path.endsWith(".md")) return;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, JOURNAL);
+    appendFileSync(file, JSON.stringify({ p: path, t: ts } satisfies RefReadLine) + "\n", "utf-8");
+    trimLogFile(file, 128 * 1024, 1_000); // bound the SHARED cross-session log: keep the recent tail (only fresh reads credit a gate)
+  } catch {
+    /* fail-open: a missing dir or write error must never break recording */
+  }
+}
+
+/**
+ * Fold every `.md` read in the state-dir journal into `track` (immutably), each
+ * stamped with its journalled timestamp and never rolling back a MORE-recent
+ * existing stamp — identical merge semantics to
+ * {@link reconcileRefReadsFromTranscript}, but from the fresh append-only journal
+ * instead of the lagged transcript. Fail-open: an absent/unreadable journal returns
+ * `track` unchanged (same reference).
+ * @param track - The current (possibly race-damaged) session track.
+ * @param dir - Per-session state dir (`dirname(trackFile)`).
+ * @param now - Fallback epoch-ms for entries with an invalid timestamp.
+ * @returns The track with journalled `.md` reads merged into `refsRead`/`refsReadAt`.
+ */
+export function reconcileRefReadsFromJournal(track: SessionTrack, dir: string, now: number): SessionTrack {
+  let text: string;
+  try {
+    text = readText(join(dir, JOURNAL));
+  } catch {
+    return track; // unreadable → unchanged (no regression)
+  }
+  let next = track;
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let entry: RefReadLine;
+    try {
+      entry = JSON.parse(line) as RefReadLine;
+    } catch {
+      continue; // tolerate malformed lines
+    }
+    const path = typeof entry.p === "string" ? entry.p : "";
+    if (!path.endsWith(".md")) continue;
+    const ts = typeof entry.t === "number" && Number.isFinite(entry.t) ? entry.t : now;
+    const prev = next.refsReadAt?.[path];
+    if (prev === undefined || prev < ts) next = recordRefRead(next, path, ts);
+  }
+  return next;
+}

package/src/freshness/trivial-edit-counter.ts

@@ -0,0 +1,30 @@
+import { dirname } from "node:path";
+import { ensureDir, readJsonFile, writeJsonFile } from "../util/json-io";
+
+interface TrivialEditState {
+  trivial_edits?: number[];
+  [key: string]: unknown;
+}
+
+/**
+ * Increment a session's trivial-edit counter, evicting timestamps older than
+ * `windowMs`. Decoupled + injectable `now` for testability.
+ * @param filePath - session state file path
+ * @param windowMs - sliding window in ms
+ * @param now - current epoch ms (defaults to `Date.now()`)
+ * @returns number of trivial edits within the window (including this one)
+ */
+export async function incrementTrivialEditCounter(
+  filePath: string,
+  windowMs: number,
+  now: number = Date.now(),
+): Promise<number> {
+  await ensureDir(dirname(filePath));
+  const state: TrivialEditState = (await readJsonFile<TrivialEditState>(filePath)) ?? {};
+  const cutoff = now - windowMs;
+  const edits = (state.trivial_edits ?? []).filter((ts) => ts > cutoff);
+  edits.push(now);
+  state.trivial_edits = edits;
+  await writeJsonFile(filePath, state);
+  return edits.length;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/** @fusengine/harness - harness-agnostic toolkit for AI coding agents. */
+export * from "./config";
+export * from "./util";
+export * from "./detect";
+export * from "./policy";
+export * from "./prompt";
+export * from "./memory";
+export * from "./cache";
+export * from "./freshness";
+export * from "./refs";
+export * from "./statusline";

package/src/init/index.ts

@@ -0,0 +1,2 @@
+export * from "./templates";
+export * from "./run";

package/src/init/run.ts

@@ -0,0 +1,32 @@
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { HarnessId } from "../detect/harness";
+import { claudeInit, clineInit, codexInit, cursorInit, geminiInit, type InitFile } from "./templates";
+import { STATE_GITIGNORE, STATE_ROOT } from "../config/layout";
+
+const RUNNERS: Partial<Record<HarnessId, (command: string) => InitFile[]>> = {
+  "claude-code": claudeInit,
+  codex: codexInit,
+  cursor: cursorInit,
+  "gemini-cli": geminiInit,
+  cline: clineInit,
+};
+
+/**
+ * Build the wiring file(s) for a harness, or null when it has no hook
+ * integration (cli-mode harnesses use `harness check` in a pre-commit step).
+ */
+export function initFor(id: HarnessId, command: string = `npx -y @fusengine/harness hook ${id}`): InitFile[] | null {
+  const make = RUNNERS[id];
+  if (!make) return null;
+  return [...make(command), { path: `${STATE_ROOT}/.gitignore`, content: STATE_GITIGNORE }];
+}
+
+/** Write an {@link InitFile} under `root` (creates dirs; `chmod +x` when executable). */
+export function writeInitFile(root: string, file: InitFile): string {
+  const full = join(root, file.path);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, file.content);
+  if (file.executable) chmodSync(full, 0o755);
+  return full;
+}