@fusengine/harness 0.1.90 → 0.1.91

package/src/tracking/one-shot.ts

@@ -0,0 +1,93 @@
+/**
+ * @module one-shot
+ * Sidecar store + gate wiring for the per-gate one-shot metric.
+ *
+ * STATE — a standalone sidecar (`one-shot.json`) in the same per-project state dir
+ * as the session track, mirroring {@link module:deny-loop-store} (atomicWrite,
+ * prune-by-window, fail-safe). A write error NEVER changes a gate decision nor its
+ * prompt — metrics are pure observation.
+ *
+ * KEY — the operation identity is content-FREE (`tool + filePath/command`): a fix
+ * changes the content, so a content hash would make every retry a new op and hide
+ * the deny→allow transition this metric exists to see. The pure model lives in
+ * {@link module:one-shot-store}; this file is the only IO surface.
+ * @packageDocumentation
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { denyHash } from "../policy/deny-loop";
+import { defaultStateDir } from "../runtime/paths";
+import { applyAllow, applyDeny, EMPTY, formatSummary, pruneState, type OneShotState } from "./one-shot-store";
+import { burstFirst } from "./one-shot-dedup";
+import type { Prompt } from "../prompt/types";
+
+/** Sidecar basename under the per-project state dir. */
+export const SIDECAR = "one-shot.json";
+
+/** Retention window: 7 days. Aggregates and pending denies older than this are pruned. */
+export const WINDOW_MS: number = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Injected clock + state dir (no env var; the gate supplies both). `sessionId` —
+ * when present — arms the burst dedup ({@link module:one-shot-dedup}) so the ~11
+ * sibling plugin hooks of ONE event count once, not once each. Omitted by
+ * mono-process callers/tests → un-deduped historical behaviour.
+ */
+export interface OneShotOpts { now: number; dir: string; sessionId?: string; }
+
+/** Identifying tool input (content-free); `content` only decides gateability. */
+export interface OneShotInput { filePath?: string; content?: string; command?: string; }
+
+/** Load the state, or a fresh copy when missing/corrupt. */
+export function loadState(path: string): OneShotState {
+  try {
+    if (!existsSync(path)) return { ...EMPTY };
+    const d: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return d && typeof d === "object" && !Array.isArray(d) ? { ...EMPTY, ...(d as OneShotState) } : { ...EMPTY };
+  } catch {
+    return { ...EMPTY };
+  }
+}
+
+/**
+ * Record a gate outcome: a `block` is a deny for its gate title; a `null` allow is
+ * a fix (if the op was pending) or a one-shot (if gateable). `ask`/`inform` are
+ * neither and are skipped. Fails silently — a metric write NEVER affects a decision.
+ *
+ * The op key is tool-INDEPENDENT (`filePath`/`command` only, constant `"op"` tool):
+ * a deny (a `Write`) and its fix (an `Edit`) on the same file must link.
+ * @param prompt - The gate's outcome (block, allow=null, or ask/inform).
+ * @param input - Identifying tool input (content decides gateability only).
+ * @param opts - Clock + state dir.
+ */
+export function recordOneShot(prompt: Prompt | null, input: OneShotInput, opts: OneShotOpts): void {
+  try {
+    if (prompt && prompt.kind !== "block") return;
+    const op = denyHash("op", { filePath: input.filePath, command: input.command });
+    if (!burstFirst(op, prompt ? `deny:${prompt.title}` : "allow", opts)) return;
+    const path = join(opts.dir, SIDECAR);
+    let s = pruneState(loadState(path), opts.now, WINDOW_MS);
+    s = prompt
+      ? applyDeny(s, prompt.title, op, opts.now)
+      : applyAllow(s, op, opts.now, input.content != null || input.command != null);
+    atomicWrite(path, JSON.stringify(s));
+  } catch { /* fail-safe: metrics never change a gate decision */ }
+}
+
+/**
+ * Compact, injection-ready one-shot summary for the project rooted at `cwd`. The
+ * state dir is derived EXACTLY like the runtime writer ({@link defaultStateDir},
+ * mirroring `handle.ts` `trackFile(sid, defaultStateDir(cwd))`), so the file read
+ * here is the same one {@link recordOneShot} wrote. "" when no data or read error.
+ * @param cwd - The project working directory (Claude `cwd`), NOT the state dir.
+ * @returns One line, e.g. `gates 7d: 88% one-shot (44/50 clean); ...`, or "".
+ */
+export function oneShotSummary(cwd: string): string {
+  try {
+    const s = pruneState(loadState(join(defaultStateDir(cwd), SIDECAR)), Date.now(), WINDOW_MS);
+    return formatSummary(s);
+  } catch {
+    return "";
+  }
+}

package/src/tracking/receipts.ts

@@ -0,0 +1,95 @@
+/**
+ * @module receipts
+ * Verification receipts: capture `tsc`/test runs at PostToolUse and query the
+ * freshest PASSING one for the TaskCompleted (hard) and SubagentStop (advisory)
+ * gates. A "done" over modified code files is refused unless such a receipt
+ * exists — mechanising "no proof, no done".
+ * @packageDocumentation
+ */
+import { withTrack, trackJournalEnabled } from "./store";
+import { readTrackSync } from "./track-compact";
+import type { SessionTrack } from "./session-state";
+
+/**
+ * A verification receipt captured at PostToolUse from a Bash verification
+ * command. Feeds the TaskCompleted receipt gate: a "done" over modified code
+ * files is refused unless a fresh, passing receipt (`exitCode === 0`, `fail === 0`)
+ * exists. `pass`/`fail` are parsed only for test runs; `tsc` carries the code alone.
+ */
+export interface Receipt {
+  kind: "tsc" | "test";
+  exitCode: number;
+  pass?: number;
+  fail?: number;
+  ts: number;
+}
+
+/** `tsc` / `bunx tsc` / `npx tsc -p .` — a type-check invocation. */
+const TSC_RE = /(?:^|\s|\/)(?:bunx\s+|npx\s+|pnpm\s+|yarn\s+)?tsc\b/;
+/** `bun test`, `vitest`, `jest`, `npm test`, `npm run test`, … — a test run. */
+const TEST_RE = /\b(?:bun\s+test|vitest|jest|(?:npm|pnpm|yarn)\s+(?:run\s+)?test)\b/;
+
+/** Append a verification receipt to the track. Immutable. */
+export function recordReceipt(track: SessionTrack, receipt: Receipt): SessionTrack {
+  return { ...track, receipts: [...(track.receipts ?? []), receipt] };
+}
+
+/** Parse `N pass` / `M fail` counts from bun/vitest/jest output (undefined when absent). */
+function parseCounts(output: string): { pass?: number; fail?: number } {
+  const pass = output.match(/(\d+)\s+pass/i);
+  const fail = output.match(/(\d+)\s+fail/i);
+  return { pass: pass ? Number(pass[1]) : undefined, fail: fail ? Number(fail[1]) : undefined };
+}
+
+/**
+ * Classify a Bash command as a verification receipt, or `null` when it is not a
+ * recognised `tsc`/test invocation. Test runs additionally carry parsed
+ * pass/fail counts.
+ * @param command - The Bash command line.
+ * @param output - Combined stdout+stderr (bun writes its summary to stderr).
+ * @param exitCode - The command's exit code.
+ * @param now - Capture timestamp (epoch ms).
+ */
+export function classifyReceipt(command: string, output: string, exitCode: number, now: number): Receipt | null {
+  if (TEST_RE.test(command)) {
+    const { pass, fail } = parseCounts(output);
+    return { kind: "test", exitCode, pass, fail, ts: now };
+  }
+  if (TSC_RE.test(command)) return { kind: "tsc", exitCode, ts: now };
+  return null;
+}
+
+/** A receipt PROVES success: exit 0 and (for tests) zero reported failures. */
+function isPassing(r: Receipt): boolean {
+  return r.exitCode === 0 && (r.fail ?? 0) === 0;
+}
+
+/** The newest passing receipt within `windowMs`, or `null`. */
+export function freshPassingReceipt(track: SessionTrack, windowMs: number, now: number): Receipt | null {
+  const cutoff = now - windowMs;
+  const hits = (track.receipts ?? []).filter((r) => r.ts > cutoff && isPassing(r));
+  return hits.length ? hits.reduce((a, b) => (b.ts > a.ts ? b : a)) : null;
+}
+
+/**
+ * Sync variant reading the track directly (snapshot ⊕ journal) — for the sync
+ * gates (TaskCompleted / SubagentStop). Returns the newest passing receipt, or
+ * `null` on any read/verify failure (fail-closed: no proof ⇒ unverified).
+ */
+export function freshReceiptFromFile(file: string, windowMs: number, now: number): Receipt | null {
+  try {
+    return freshPassingReceipt(readTrackSync(file, trackJournalEnabled()), windowMs, now);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Capture a verification receipt from a PostToolUse Bash command into the signed
+ * track (best effort — a non-verification command is a no-op).
+ */
+export async function captureReceipt(file: string, command: string, output: string, exitCode: number, now: number): Promise<void> {
+  const receipt = classifyReceipt(command, output, exitCode, now);
+  if (!receipt) return;
+  await withTrack(file, (track) => recordReceipt(track, receipt));
+}

package/src/tracking/session-state.ts

@@ -0,0 +1,94 @@
+import type { AuthEntry } from "../freshness/doc-helpers";
+import { creditDocConsultation, type SessionTarget } from "../policy/apex-authorization";
+import type { Receipt } from "./receipts";
+
+/** Quality of a recorded agent call (the freshness gate ignores insufficient ones). */
+export type AgentQuality = "sufficient" | "insufficient";
+
+/** Recorded session activity that feeds the APEX gates. */
+export interface SessionTrack {
+  authorizations: Record<string, AuthEntry>;
+  refsRead: string[];
+  /**
+   * Epoch-ms timestamp of each reference read, keyed by `refsRead` path (parity
+   * track-solid-reads.py `solid_reads[].timestamp`). Optional: tracks persisted
+   * before this field existed only carry `refsRead`, and such paths count as
+   * read (backward compat). PARITY: only the SOLID-read gate TTL-checks these —
+   * Python TTL-izes SOLID reads exclusively (require-solid-read.py); the other
+   * refsRead consumers (skill-trigger/shadcn/tailwind/design) stay session-scoped.
+   */
+  refsReadAt?: Record<string, number>;
+  /** Framework awaiting doc credit after a Check-1 deny. PERSISTS — {@link recordDoc} cross-credits it on EVERY consultation, never clears it; only the next deny replaces it via {@link recordTarget} (parity track-doc-consultation.py:62). */
+  target?: SessionTarget;
+  agents: { name: string; ts: number; quality?: AgentQuality }[];
+  trivialEdits: number[];
+  brainstormRequired?: boolean;
+  /** Verification receipts (tsc/test) at PostToolUse; absent/empty reads as unverified in the TaskCompleted gate (backward compat, fail-closed). See {@link Receipt}. */
+  receipts?: Receipt[];
+}
+/** A fresh, empty track. */
+export function emptyTrack(): SessionTrack {
+  return { authorizations: {}, refsRead: [], agents: [], trivialEdits: [] };
+}
+
+/**
+ * Record a doc consultation (Context7/Exa/web) for a framework in this session:
+ * the Check-2 credit (`doc_sessions` + `sources`) plus the Check-1 stamp
+ * (`sessions` + `doc_consulted` = ISO of `now`). PARITY track-doc-consultation.py
+ * :62-70 — a `target` left by a Check-1 deny (enforce-apex-phases.ts:80) is
+ * cross-credited on EVERY consultation, with NO TTL on `target.set_at`, and the
+ * target PERSISTS (only the next deny replaces it via {@link recordTarget});
+ * single-shot clearing or TTL-gating the target re-opened the deny loop when a
+ * consultation landed > TTL after the deny. Immutable.
+ */
+export function recordDoc(track: SessionTrack, framework: string, sessionId: string, source: string, now: number = Date.now()): SessionTrack {
+  const nowIso = new Date(now).toISOString();
+  const authorizations = { ...track.authorizations, [framework]: creditDocConsultation(track.authorizations[framework], sessionId, source, nowIso) };
+  const t = track.target;
+  if (t && t.framework !== framework) {
+    authorizations[t.framework] = creditDocConsultation(track.authorizations[t.framework], sessionId, source, nowIso);
+  }
+  return { ...track, authorizations };
+}
+/** Set the pending doc-credit target (written by the runtime on a Check-1 deny). Immutable. */
+export function recordTarget(track: SessionTrack, target: SessionTarget): SessionTrack {
+  return { ...track, target };
+}
+
+/**
+ * Record that a SOLID reference file was read (deduped). Immutable. When `now`
+ * (epoch ms — the tool event's own timestamp, never a fresh `Date.now()`) is
+ * supplied, the read is stamped in `refsReadAt`, refreshed on re-reads so the
+ * LATEST read drives the SOLID TTL (parity track-solid-reads.py, which appends
+ * a timestamped entry per read; require-solid-read.py checks the most recent).
+ * Callers that omit `now` keep the legacy untimestamped behavior.
+ */
+export function recordRefRead(track: SessionTrack, path: string, now?: number): SessionTrack {
+  const refsRead = track.refsRead.includes(path) ? track.refsRead : [...track.refsRead, path];
+  if (now === undefined) return refsRead === track.refsRead ? track : { ...track, refsRead };
+  return { ...track, refsRead, refsReadAt: { ...track.refsReadAt, [path]: now } };
+}
+/** Record an agent/tool call with a timestamp + optional quality. Immutable. */
+export function recordAgent(track: SessionTrack, name: string, ts: number, quality?: AgentQuality): SessionTrack {
+  const entry = quality ? { name, ts, quality } : { name, ts };
+  return { ...track, agents: [...track.agents, entry] };
+}
+/** True when ALL of `names` ran within `windowMs` with non-insufficient quality. */
+export function agentsFresh(track: SessionTrack, names: string[], windowMs: number, now: number): boolean {
+  const cutoff = now - windowMs;
+  return names.every((n) => track.agents.some((a) => a.name === n && a.ts > cutoff && a.quality !== "insufficient"));
+}
+/** Record a trivial edit timestamp (sliding window; old evicted). Immutable. */
+export function recordTrivialEdit(track: SessionTrack, ts: number, windowMs: number, now: number): SessionTrack {
+  const cutoff = now - windowMs;
+  return { ...track, trivialEdits: [...(track.trivialEdits ?? []).filter((t) => t > cutoff), ts] };
+}
+/** Count trivial edits within the sliding window. */
+export function trivialCount(track: SessionTrack, windowMs: number, now: number): number {
+  const cutoff = now - windowMs;
+  return (track.trivialEdits ?? []).filter((t) => t > cutoff).length;
+}
+/** Set the brainstorm-required flag (from creation-intent detection). Immutable. */
+export function recordBrainstormRequired(track: SessionTrack, required: boolean): SessionTrack {
+  return { ...track, brainstormRequired: required };
+}

package/src/tracking/store.ts

@@ -0,0 +1,96 @@
+/**
+ * @module store
+ * Session-track persistence — TWO modes behind an env kill-switch:
+ * - JOURNAL (default): writes append signed event lines to `track-<sid>.log`
+ *   (O_APPEND, lock-free — see track-journal.ts), reads fold the log over the
+ *   legacy `track-<sid>.json` snapshot. No lock on the hot path ⇒ the fan-out
+ *   can no longer lose a write to "track lock busy, write skipped" — compaction
+ *   included (it is rename-atomic, see track-compact.ts).
+ * - LEGACY (`FUSE_TRACK_JOURNAL=0`): the original locked read-modify-write,
+ *   kept fully intact below as the instant rollback (G1) — no redeploy needed.
+ *   NOTE: =0 does NOT honour the uncompacted journal (the track reads as its
+ *   last snapshot, possibly EMPTY); the events are recoverable by switching
+ *   back to journal mode — never delete a `.log` during a =0 rollback.
+ * The flag is read at CALL time so the switch is live.
+ * @packageDocumentation
+ */
+import { readJsonFile, writeJsonFile } from "../util/json-io";
+import { emptyTrack, type SessionTrack } from "./session-state";
+import { signTrack, verifyTrack, writeLastNonce, type TrackEnvelope } from "./integrity";
+import { LOCK_FAILED, withTrackLock } from "./track-lock";
+import { dirname } from "node:path";
+import { appendEvent, foldEvents } from "./track-journal";
+import { diffTrackEvents } from "./track-diff";
+import { journalLogPath, maybeCompactJournal, readEvents } from "./track-compact";
+
+/** Journal mode is the default; `FUSE_TRACK_JOURNAL=0` reverts to the legacy locked RMW (see the module NOTE: =0 ignores the uncompacted journal — recoverable, keep the `.log`). */
+export function trackJournalEnabled(): boolean {
+  return process.env.FUSE_TRACK_JOURNAL !== "0";
+}
+
+/** Verified legacy snapshot (fail closed: absent/corrupt/tampered → emptyTrack). */
+async function loadSnapshot(file: string): Promise<SessionTrack> {
+  const envelope = await readJsonFile<TrackEnvelope>(file);
+  if (!envelope) return emptyTrack();
+  return verifyTrack(envelope) ?? emptyTrack();
+}
+
+/**
+ * Load a session track: the verified legacy snapshot (the migration base — an
+ * old `track-<sid>.json` with no log reads exactly as before) with the journal
+ * folded on top. Fail closed on tampering (envelope MAC, per-line MAC).
+ */
+export async function loadTrack(file: string): Promise<SessionTrack> {
+  const base = await loadSnapshot(file);
+  if (!trackJournalEnabled()) return base;
+  return foldEvents(readEvents(journalLogPath(file)), base);
+}
+
+/** Journal-mode write: append the mutation's events, then maybe compact. */
+async function appendDiff(file: string, prev: SessionTrack, next: SessionTrack): Promise<boolean> {
+  const log = journalLogPath(file);
+  let ok = true;
+  for (const ev of diffTrackEvents(prev, next, Date.now())) ok = appendEvent(log, ev.field, ev.op, ev.value, ev.ts) && ok;
+  await maybeCompactJournal(file);
+  return ok;
+}
+
+/**
+ * Persist a session track. Journal mode appends the diff as signed events;
+ * legacy mode signs and persists the tamper-evident envelope, then writes the
+ * advisory nonce watermark.
+ */
+export async function saveTrack(file: string, track: SessionTrack): Promise<void> {
+  if (trackJournalEnabled()) {
+    await appendDiff(file, await loadTrack(file), track);
+    return;
+  }
+  const envelope = signTrack(track);
+  await writeJsonFile(file, envelope);
+  writeLastNonce(envelope.nonce);
+}
+
+/**
+ * Mutate a session track. Journal mode: load (snapshot ⊕ log), run `mutate`,
+ * append the resulting events — lock-free, so a write is only ever lost to a
+ * genuine I/O error (reported as `false`). Legacy mode: locked RMW; on lock
+ * contention the write is SKIPPED (fail-open, stderr logged) and `false` is
+ * returned — a named lost write, never a crash.
+ * @param file - The session track file.
+ * @param mutate - Pure mutation over the freshly loaded track.
+ * @returns True when the write landed.
+ */
+export async function withTrack(
+  file: string,
+  mutate: (track: SessionTrack) => SessionTrack | Promise<SessionTrack>,
+): Promise<boolean> {
+  if (trackJournalEnabled()) {
+    const track = await loadTrack(file);
+    return appendDiff(file, track, await mutate(track));
+  }
+  const ran = await withTrackLock(dirname(file), async () => {
+    const track = await loadTrack(file);
+    await saveTrack(file, await mutate(track));
+  });
+  return ran !== LOCK_FAILED;
+}

package/src/tracking/track-compact.ts

@@ -0,0 +1,100 @@
+/**
+ * @module track-compact
+ * Read side + compaction for the track journal (see track-journal.ts):
+ * - {@link parseEvents}/{@link readEvents}: MAC-verified replay — a tampered
+ *   line is dropped, never the whole file (fail-closed PER LINE);
+ * - {@link readTrackSync}: the sync snapshot ⊕ journal read for the sync gates;
+ * - {@link maybeCompactJournal}: past {@link COMPACT_BYTES}, fold the log into
+ *   the signed snapshot — RENAME-ATOMIC (logrotate pattern) under the EXISTING
+ *   track lock (rare, skipped on contention). Lock-free appends stay SAFE in
+ *   both race windows: before the rename → captured by the fold; after → a
+ *   fresh log at the original path (appendFileSync keeps no fd across calls).
+ * @packageDocumentation
+ */
+import { existsSync, readFileSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { emptyTrack, type SessionTrack } from "./session-state";
+import { computeMac, loadOrCreateKey, signTrack, verifyTrack, writeLastNonce, type TrackEnvelope } from "./integrity";
+import { foldEvents, type TrackEvent } from "./track-journal";
+import { withTrackLock } from "./track-lock";
+
+/** Compact when the log exceeds this size (bytes). */
+export const COMPACT_BYTES: number = 128 * 1024;
+
+/** The journal log path twin of a track snapshot path. */
+export function journalLogPath(trackPath: string): string {
+  return trackPath.replace(/\.json$/, ".log");
+}
+
+/** Parse & MAC-verify journal text; malformed or tampered lines are skipped. */
+export function parseEvents(text: string): TrackEvent[] {
+  const key = loadOrCreateKey(), out: TrackEvent[] = [];
+  for (const line of text.split("\n")) {
+    if (!line) continue;
+    try {
+      const ev = JSON.parse(line) as TrackEvent;
+      if (ev?.v !== 1 || typeof ev.nonce !== "string" || typeof ev.ts !== "number") continue;
+      if (ev.mac !== computeMac(key, JSON.stringify({ field: ev.field, op: ev.op, value: ev.value, ts: ev.ts }), ev.nonce)) continue; // fail-closed per line
+      out.push(ev);
+    } catch { /* skip the bad line, keep the rest */ }
+  }
+  return out;
+}
+
+/** Read & verify every event of a log; absent/unreadable → [] (fail-open read). */
+export function readEvents(logPath: string): TrackEvent[] {
+  try { return parseEvents(readFileSync(logPath, "utf8")); } catch { return []; }
+}
+
+/** Verified legacy snapshot only (fail-closed → emptyTrack), sync. */
+function readSnapshotSync(file: string): SessionTrack {
+  try {
+    return verifyTrack(JSON.parse(readFileSync(file, "utf8")) as TrackEnvelope) ?? emptyTrack();
+  } catch {
+    return emptyTrack();
+  }
+}
+
+/** Sync snapshot ⊕ journal read for the sync gates; `journal=false` = legacy kill-switch path. */
+export function readTrackSync(file: string, journal: boolean): SessionTrack {
+  const base = readSnapshotSync(file);
+  return journal ? foldEvents(readEvents(journalLogPath(file)), base) : base;
+}
+
+/** Fold a whole log file into the signed snapshot (signTrack + nonce, unchanged). */
+function foldIntoSnapshot(file: string, logPath: string): void {
+  const envelope = signTrack(foldEvents(readEvents(logPath), readSnapshotSync(file)));
+  atomicWrite(file, JSON.stringify(envelope, null, 2));
+  writeLastNonce(envelope.nonce);
+}
+
+/** Rename-atomic compaction: rename captures the WHOLE log, fold, unlink. A crash leaves `.folding` (recovered first next run); on fold failure BEFORE commit the log is renamed back — never a lost event, and never an event in BOTH snapshot and log (no double-count). */
+function compactSync(file: string): void {
+  const log = journalLogPath(file), folding = `${log}.folding`;
+  if (existsSync(folding)) { foldIntoSnapshot(file, folding); unlinkSync(folding); } // crashed compaction recovery
+  renameSync(log, folding); // atomic capture; the next append recreates a fresh log
+  let committed = false;
+  try {
+    foldIntoSnapshot(file, folding);
+    committed = true; // the snapshot now HOLDS the events: never return them to the log
+    unlinkSync(folding);
+  } catch (err) {
+    if (!committed) { try { renameSync(folding, log); } catch { /* keep .folding for recovery */ } }
+    else { try { unlinkSync(folding); } catch { /* residue iff unlink itself failed */ } }
+    throw err;
+  }
+}
+
+/** Trigger compaction past the cap (`FUSE_TRACK_COMPACT_BYTES` overrides {@link COMPACT_BYTES}), under the existing lock (skipped on contention). */
+export async function maybeCompactJournal(file: string): Promise<void> {
+  try {
+    const cap = Number(process.env.FUSE_TRACK_COMPACT_BYTES) || COMPACT_BYTES;
+    if (statSync(journalLogPath(file)).size < cap) return;
+  } catch {
+    return; // no log yet
+  }
+  await withTrackLock(dirname(file), async () => {
+    try { compactSync(file); } catch { /* rare path: the next trigger retries */ }
+  });
+}

package/src/tracking/track-diff.ts

@@ -0,0 +1,50 @@
+/**
+ * @module track-diff
+ * Derive journal events from a track mutation (prev → next), so journal-mode
+ * writers keep the existing immutable-mutator API unchanged: run the pure
+ * mutator in memory, then append ONLY what changed. The per-field mapping
+ * mirrors the fold table in track-journal.ts (adds/maxes/appends/merges/sets;
+ * evictions are NOT events — the fold's sliding-window re-filter owns those).
+ * @packageDocumentation
+ */
+import type { SessionTrack } from "./session-state";
+
+/** An unsigned event ready for {@link appendEvent}. */
+export type RawEvent = { field: string; op: "add" | "max" | "append" | "merge" | "set"; value: unknown; ts: number };
+
+/** Elements of `next` beyond the longest prefix shared with `prev` (append-only arrays). */
+function tail<T>(prev: T[], next: T[]): T[] {
+  let i = 0;
+  while (i < prev.length && i < next.length && JSON.stringify(prev[i]) === JSON.stringify(next[i])) i++;
+  return next.slice(i);
+}
+
+/** Multiset of added numbers (next counts minus prev counts). */
+function added(xs: number[], ys: number[]): number[] {
+  const left = new Map<number, number>();
+  for (const x of xs) left.set(x, (left.get(x) ?? 0) + 1);
+  const out: number[] = [];
+  for (const y of ys) {
+    const n = left.get(y) ?? 0;
+    if (n > 0) left.set(y, n - 1);
+    else out.push(y);
+  }
+  return out;
+}
+
+/** Events replaying `next` over `prev` (empty when the mutation was a no-op). */
+export function diffTrackEvents(prev: SessionTrack, next: SessionTrack, now: number): RawEvent[] {
+  if (prev === next) return [];
+  const out: RawEvent[] = [];
+  for (const p of next.refsRead) if (!prev.refsRead.includes(p)) out.push({ field: "refsRead", op: "add", value: p, ts: next.refsReadAt?.[p] ?? now });
+  for (const [p, ts] of Object.entries(next.refsReadAt ?? {})) if (ts !== prev.refsReadAt?.[p]) out.push({ field: "refsReadAt", op: "max", value: [p, ts], ts });
+  for (const a of tail(prev.agents, next.agents)) out.push({ field: "agents", op: "append", value: a, ts: a.ts ?? now });
+  for (const r of tail(prev.receipts ?? [], next.receipts ?? [])) out.push({ field: "receipts", op: "append", value: r, ts: r.ts ?? now });
+  for (const [key, entry] of Object.entries(next.authorizations)) {
+    if (JSON.stringify(entry) !== JSON.stringify(prev.authorizations[key])) out.push({ field: "authorizations", op: "merge", value: { key, entry }, ts: Date.parse(entry.doc_consulted ?? "") || now });
+  }
+  for (const ts of added(prev.trivialEdits ?? [], next.trivialEdits ?? [])) out.push({ field: "trivialEdits", op: "add", value: ts, ts });
+  if (next.target && JSON.stringify(next.target) !== JSON.stringify(prev.target)) out.push({ field: "target", op: "set", value: next.target, ts: Date.parse(next.target.set_at) || now });
+  if (next.brainstormRequired !== prev.brainstormRequired) out.push({ field: "brainstormRequired", op: "set", value: next.brainstormRequired, ts: now });
+  return out;
+}

package/src/tracking/track-journal.ts

@@ -0,0 +1,97 @@
+/**
+ * @module track-journal
+ * Append-only, per-line-signed event journal for {@link SessionTrack} — the
+ * fan-out-immune replacement for the locked RMW (generalises the freshness/
+ * ref-journal.ts pattern to every field). Appends serialise on a SHORT
+ * BLOCKING track lock (never skipped, sub-ms wait — see appendEvent) so they
+ * can never race the rename-atomic compaction: zero lost write. Per-line HMAC
+ * (same key/scheme as integrity.ts): a tampered line is dropped, never the
+ * whole file (fail-closed PER LINE).
+ * @packageDocumentation
+ */
+import { appendFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { computeMac, loadOrCreateKey } from "./integrity";
+import { withTrackLockSyncBlocking } from "./track-lock-sync";
+import { emptyTrack, type SessionTrack } from "./session-state";
+import type { AuthEntry } from "../freshness/doc-helpers";
+import type { SessionTarget } from "../policy/apex-authorization";
+import type { Receipt } from "./receipts";
+
+/** One signed journal line: `mac` = HMAC over `"<nonce>:<JSON{field,op,value,ts}>"`. */
+export type TrackEvent = { v: 1; field: string; op: "add" | "max" | "append" | "merge" | "set"; value: unknown; ts: number; nonce: string; mac: string };
+
+/** Hard cap per line — short lines stay non-interleaved under O_APPEND. */
+const MAX_LINE = 32 * 1024;
+/** Trivial-edit sliding window for the fold (mirrors gate.ts DEFAULT_WINDOW_MS). */
+const TRIVIAL_WINDOW_MS = 120_000;
+
+/** Sign one event: an oversized STRING value is truncated then re-signed (never an unsigned partial line); an oversized non-string is dropped (null). */
+export function signEvent(field: string, op: TrackEvent["op"], value: unknown, ts: number): TrackEvent | null {
+  let data = JSON.stringify({ field, op, value, ts });
+  if (data.length > MAX_LINE - 256) {
+    if (typeof value !== "string") return null;
+    value = value.slice(0, Math.max(0, value.length - (data.length - (MAX_LINE - 256))));
+    data = JSON.stringify({ field, op, value, ts });
+  }
+  const nonce = randomBytes(8).toString("hex");
+  return { v: 1, field, op, value, ts, nonce, mac: computeMac(loadOrCreateKey(), data, nonce) };
+}
+
+/** Append one signed event line under the BLOCKING track lock (same `track.lock` as the compaction — an append can never straddle rename/fold/unlink; never skipped). Fail-open on I/O error. */
+export function appendEvent(logPath: string, field: string, op: TrackEvent["op"], value: unknown, ts: number): boolean {
+  try {
+    const ev = signEvent(field, op, value, ts);
+    if (!ev) return false;
+    withTrackLockSyncBlocking(dirname(logPath), () => appendFileSync(logPath, JSON.stringify(ev) + "\n", "utf8"));
+    return true;
+  } catch { return false; }
+}
+
+const union = (a?: string[], b?: string[]): string[] => [...new Set([...(a ?? []), ...(b ?? [])])];
+
+/** Merge one auth entry: non-empty list fields union, scalars of the later-folded (newer) event win. */
+function mergeAuth(p: AuthEntry | undefined, e: AuthEntry): AuthEntry {
+  const b = p ?? {}, out: AuthEntry = { ...b, ...e };
+  const sessions = union(b.sessions, e.sessions);
+  if (sessions.length) out.sessions = sessions;
+  const docSessions = union(b.doc_sessions, e.doc_sessions);
+  if (docSessions.length) out.doc_sessions = docSessions;
+  const sources = union(b.sources ?? (b.source ? [b.source] : []), e.sources ?? (e.source ? [e.source] : []));
+  if (sources.length) out.sources = sources;
+  const readPaths = union(b.read_paths, e.read_paths);
+  if (readPaths.length) out.read_paths = readPaths;
+  return out;
+}
+
+/**
+ * Replay events over `base` (the legacy snapshot — emptyTrack when absent).
+ * Deterministic CRDT fold with a STABLE sort on ts (log order breaks ties):
+ * refsRead = dedup union; refsReadAt = per-key max; agents/receipts =
+ * ts-ordered append, never deduped; authorizations = per-key merge (list
+ * unions); trivialEdits = union re-filtered by the sliding window;
+ * target/brainstormRequired = last-writer-wins on ts.
+ */
+export function foldEvents(events: TrackEvent[], base: SessionTrack = emptyTrack()): SessionTrack {
+  const t: SessionTrack = { ...base, refsRead: [...base.refsRead], agents: [...base.agents], authorizations: { ...base.authorizations }, trivialEdits: [] };
+  const at: Record<string, number> = { ...base.refsReadAt };
+  const receipts: Receipt[] = [...(base.receipts ?? [])];
+  const trivial = new Set(base.trivialEdits ?? []);
+  let targetTs = base.target ? Date.parse(base.target.set_at) || 0 : 0, brainstormTs = 0; // a base flag is unstamped: any event overrides it
+  for (const ev of [...events].sort((a, b) => a.ts - b.ts)) { // stable: log order breaks ts ties
+    if (ev.field === "refsRead") { const p = String(ev.value); if (!t.refsRead.includes(p)) t.refsRead.push(p); }
+    else if (ev.field === "refsReadAt") { const [p, ts] = ev.value as [string, number]; if ((at[p] ?? -1) < ts) at[p] = ts; }
+    else if (ev.field === "agents") t.agents.push(ev.value as SessionTrack["agents"][number]);
+    else if (ev.field === "receipts") receipts.push(ev.value as Receipt);
+    else if (ev.field === "authorizations") { const m = ev.value as { key: string; entry: AuthEntry }; t.authorizations[m.key] = mergeAuth(t.authorizations[m.key], m.entry); }
+    else if (ev.field === "trivialEdits") trivial.add(Number(ev.value));
+    else if (ev.field === "target" && ev.ts >= targetTs) { t.target = ev.value as SessionTarget; targetTs = ev.ts; }
+    else if (ev.field === "brainstormRequired" && ev.ts >= brainstormTs) { t.brainstormRequired = Boolean(ev.value); brainstormTs = ev.ts; }
+  }
+  if (Object.keys(at).length) t.refsReadAt = at;
+  if (receipts.length) t.receipts = receipts;
+  const maxT = Math.max(0, ...trivial);
+  t.trivialEdits = [...trivial].filter((x) => x > maxT - TRIVIAL_WINDOW_MS).sort((a, b) => a - b);
+  return t;
+}