@fusengine/harness 0.1.89 → 0.1.91

package/src/tracking/codex-post-failure.ts

@@ -0,0 +1,73 @@
+/**
+ * @module codex-post-failure
+ * Codex has no native `PostToolUseFailure` event (Claude Code's own failure
+ * signal, ported in `src/runtime/lifecycle/tool-failure.ts`'s `logToolFailure`)
+ * — every Codex tool outcome, success or failure, arrives on the SAME
+ * `PostToolUse` event. This infers a failure from the regular payload's
+ * `tool_result`/`tool_response` and journals it into the EXISTING one-shot
+ * failure tally ({@link recordFailure}) — no new store, no new gate.
+ *
+ * Design choice (fail-open): a payload this module cannot positively prove
+ * failed — `null`/`undefined`, a non-object shape, or any parse exception —
+ * classifies as `"success"` (ignored), NEVER `"failure"`. Many legitimate
+ * successful tool calls return no structured result at all (see
+ * `handle-post.ts`'s `spawn_agent` `tool_response: { nickname: "scout" }`),
+ * so treating "can't tell" as a failure would flood the tally with false
+ * positives. Only an EXPLICIT signal (non-zero exit, an error field) counts.
+ * @packageDocumentation
+ */
+import { recordFailure } from "./one-shot-failure";
+import type { OneShotOpts } from "./one-shot";
+
+/** Truthy interruption markers across harness result shapes (parity `tool-failure.ts`'s `is_interrupt`). */
+const INTERRUPT_KEYS = ["is_interrupt", "isInterrupted", "interrupted", "aborted", "cancelled", "canceled"];
+
+/** True when `result` carries any known interruption marker — an interruption is never a failure. */
+function isInterruption(result: Record<string, unknown>): boolean {
+  return INTERRUPT_KEYS.some((k) => result[k] === true);
+}
+
+/** True when `result` reports a non-zero exit code (Bash-shaped tool result). */
+function hasNonZeroExit(result: Record<string, unknown>): boolean {
+  const exit = result.exit_code ?? result.exitCode;
+  return typeof exit === "number" && exit !== 0;
+}
+
+/** True when `result` carries an explicit error signal (`error`, `is_error`/`isError`, or `success: false`). */
+function hasErrorField(result: Record<string, unknown>): boolean {
+  if (result.success === false) return true;
+  if (result.is_error === true || result.isError === true) return true;
+  const err = result.error;
+  return typeof err === "string" ? err.length > 0 : err !== undefined && err !== null;
+}
+
+/**
+ * Classify a Codex PostToolUse `tool_response`/`tool_result` payload.
+ * Fail-open (see module doc): unprovable shapes resolve to `"success"`,
+ * never `"failure"`, and this NEVER throws.
+ * @param result - The raw result value off the payload (any shape).
+ * @returns `"success"` | `"failure"` | `"interrupted"`.
+ */
+export function classifyCodexOutcome(result: unknown): "success" | "failure" | "interrupted" {
+  try {
+    if (result === null || typeof result !== "object" || Array.isArray(result)) return "success";
+    const r = result as Record<string, unknown>;
+    if (isInterruption(r)) return "interrupted";
+    if (hasNonZeroExit(r) || hasErrorField(r)) return "failure";
+    return "success";
+  } catch {
+    return "success";
+  }
+}
+
+/**
+ * Journal a Codex tool failure into the existing one-shot failure tally.
+ * No-op for `"success"`/`"interrupted"` — only a genuine failure is recorded.
+ * @param tool - The tool name.
+ * @param result - The raw PostToolUse result payload.
+ * @param opts - Clock + state dir (+ optional session id), forwarded as-is to {@link recordFailure}.
+ */
+export function recordCodexPostFailure(tool: string, result: unknown, opts: OneShotOpts): void {
+  if (classifyCodexOutcome(result) !== "failure") return;
+  recordFailure(tool, opts);
+}

package/src/tracking/index.ts

@@ -0,0 +1,2 @@
+export * from "./session-state";
+export * from "./store";

package/src/tracking/integrity.ts

@@ -0,0 +1,99 @@
+/**
+ * @module integrity
+ * HMAC-SHA256 tamper-evident wrapping for {@link SessionTrack}.
+ *
+ * Failure policy: ONLY a MAC mismatch causes fail-closed (returns null).
+ * The nonce is included in the signed payload and written to disk for advisory
+ * diagnostics, but is NOT checked during verification — concurrent hook
+ * invocations (PostToolUse, SubagentStop, …) legitimately load the same
+ * envelope after the nonce watermark advances; a monotonic check would trigger
+ * spurious fail-closed behaviour mid-session.
+ *
+ * The machine key is readable by the same agent process, so this deters naive
+ * out-of-band tampering — not a determined re-sign. Item B (transcript-grounded
+ * freshness) is the primary guarantee.
+ * @packageDocumentation
+ */
+import { createHmac, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fuseHarnessHome } from "../runtime/home-state";
+import type { SessionTrack } from "./session-state";
+
+const HARNESS_DIR = fuseHarnessHome();
+const KEY_PATH = join(HARNESS_DIR, ".key");
+const NONCE_PATH = join(HARNESS_DIR, ".nonce");
+
+/** Signed envelope wrapping a JSON-serialised {@link SessionTrack}. */
+export interface TrackEnvelope {
+  /** JSON-serialised SessionTrack. */
+  data: string;
+  /** Advisory timestamp (Date.now() at sign time); embedded in the MAC. */
+  nonce: number;
+  /** HMAC-SHA256 hex digest over `"${nonce}:${data}"`. */
+  mac: string;
+}
+
+/** Load (or create on first use) the per-machine HMAC key stored at mode 0600. */
+export function loadOrCreateKey(): string {
+  mkdirSync(HARNESS_DIR, { recursive: true });
+  if (existsSync(KEY_PATH)) return readFileSync(KEY_PATH, "utf8").trim();
+  // Race-tolerant creation ("wx" crowns ONE creator): before, N concurrent
+  // first-time processes (virgin home — CI) each signed with their OWN key.
+  const candidate = randomBytes(32).toString("hex");
+  try {
+    writeFileSync(KEY_PATH, candidate, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    return candidate;
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+  }
+  // The winner's 64-byte write is one write(2); bounded re-reads cover the gap.
+  for (let i = 0; i < 5; i++) {
+    const existing = readFileSync(KEY_PATH, "utf8").trim();
+    if (existing) return existing;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+  }
+  const key = readFileSync(KEY_PATH, "utf8").trim();
+  if (!key) throw new Error("fuse: empty .key after write contention");
+  return key;
+}
+
+/**
+ * Persist the last-seen nonce for advisory diagnostics (mode 0600).
+ * Never read during {@link verifyTrack} — see module JSDoc for rationale.
+ */
+export function writeLastNonce(nonce: number): void {
+  mkdirSync(HARNESS_DIR, { recursive: true });
+  writeFileSync(NONCE_PATH, String(nonce), { encoding: "utf8", mode: 0o600 });
+}
+
+/** Compute HMAC-SHA256 over `"${nonce}:${data}"` (nonce: envelope number or journal per-line string). */
+export function computeMac(key: string, data: string, nonce: number | string): string {
+  return createHmac("sha256", key).update(`${nonce}:${data}`).digest("hex");
+}
+
+/**
+ * Sign a {@link SessionTrack} into a tamper-evident envelope. The nonce
+ * (`Date.now()`) is embedded in the MAC to bind the timestamp to the payload.
+ */
+export function signTrack(track: SessionTrack): TrackEnvelope {
+  const key = loadOrCreateKey();
+  const data = JSON.stringify(track);
+  const nonce = Date.now();
+  return { data, nonce, mac: computeMac(key, data, nonce) };
+}
+
+/**
+ * Verify a {@link TrackEnvelope}. Returns the parsed {@link SessionTrack} on
+ * success, or `null` ONLY on MAC mismatch / parse failure (fail-closed on
+ * tampering). The nonce is NOT checked — see module JSDoc.
+ */
+export function verifyTrack(envelope: TrackEnvelope): SessionTrack | null {
+  try {
+    const key = loadOrCreateKey();
+    if (envelope.mac !== computeMac(key, envelope.data, envelope.nonce)) return null;
+    return JSON.parse(envelope.data) as SessionTrack;
+  } catch {
+    return null;
+  }
+}

package/src/tracking/one-shot-dedup.ts

@@ -0,0 +1,34 @@
+/**
+ * @module one-shot-dedup
+ * Burst-dedup guard for the one-shot metric ({@link module:one-shot}).
+ *
+ * ONE Claude tool event fans out to ~11 sibling plugin-hook processes, each
+ * calling {@link recordOneShot}; without this the metric would count a single
+ * deny/allow ~11×. Reuses the proven {@link oncePerWindow} cooldown sidecar:
+ * the FIRST process in the {@link module:burst-window} window mutates the
+ * metric, the rest skip. The dedup key includes the outcome KIND (deny-title vs
+ * allow) so a deny and its later fix — different kinds — are never folded into
+ * each other. No `sessionId` → always the first (mono-process + unit-test
+ * parity; a burst can only exist when a real session drives the fan-out).
+ * @packageDocumentation
+ */
+import { oncePerWindow } from "../runtime/inject-dedup";
+import { BURST_DEDUP_MS } from "../runtime/burst-window";
+
+/** Opts needed to decide + persist a burst claim (a structural subset of `OneShotOpts`). */
+export interface BurstOpts { now: number; dir: string; sessionId?: string; }
+
+/**
+ * True when this `(op, kind)` is the FIRST of its burst for the session — the
+ * process that should actually mutate the metric. Sibling processes firing the
+ * SAME event within {@link BURST_DEDUP_MS} return false and skip the write.
+ * @param op - Content-free operation key ({@link denyHash}("op", …)).
+ * @param kind - Outcome discriminator (`deny:<title>` or `allow`).
+ * @param opts - Clock + state dir + optional session id.
+ * @returns `true` to apply the record, `false` to skip (already counted).
+ */
+export function burstFirst(op: string, kind: string, opts: BurstOpts): boolean {
+  const sid = opts.sessionId?.trim();
+  if (!sid) return true;
+  return oncePerWindow(`oneshot:${sid}:${op}:${kind}`, BURST_DEDUP_MS, { now: opts.now, dir: opts.dir });
+}

package/src/tracking/one-shot-failure.ts

@@ -0,0 +1,42 @@
+/**
+ * @module one-shot-failure
+ * PostToolUseFailure tally for the one-shot sidecar. A pure per-tool counter
+ * ({@link applyFailure}) plus its burst-deduped IO writer ({@link recordFailure}),
+ * kept out of {@link module:one-shot-store} so that file stays under the SOLID
+ * size limit. Reuses the SAME sidecar, prune window, and burst-dedup as
+ * {@link module:one-shot} — failures never touch the deny/allow gate rate.
+ * @packageDocumentation
+ */
+import { join } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { pruneState, type OneShotState } from "./one-shot-store";
+import { SIDECAR, WINDOW_MS, loadState, type OneShotOpts } from "./one-shot";
+import { burstFirst } from "./one-shot-dedup";
+
+/**
+ * Bump the per-tool failure count. Orthogonal to gates/pending, so it can never
+ * distort the one-shot rate.
+ * @param s - Current state.
+ * @param tool - The failing tool name (`unknown` when absent).
+ * @param now - Clock.
+ * @returns The next state with `failures[tool]` incremented.
+ */
+export function applyFailure(s: OneShotState, tool: string, now: number): OneShotState {
+  return { ...s, failures: { ...(s.failures ?? {}), [tool]: (s.failures?.[tool] ?? 0) + 1 }, updatedAt: now };
+}
+
+/**
+ * Persist a PostToolUseFailure into the one-shot sidecar, burst-deduped across the
+ * ~11-process fan-out (same window/store as {@link recordOneShot}). Fail-safe: a
+ * write error never propagates out of the hook.
+ * @param tool - The failing tool name.
+ * @param opts - Clock + state dir + optional session id (arms the burst dedup).
+ */
+export function recordFailure(tool: string, opts: OneShotOpts): void {
+  try {
+    if (!burstFirst(`fail:${tool}`, "failure", opts)) return;
+    const path = join(opts.dir, SIDECAR);
+    const next = applyFailure(pruneState(loadState(path), opts.now, WINDOW_MS), tool, opts.now);
+    atomicWrite(path, JSON.stringify(next));
+  } catch { /* fail-safe: metrics never break the hook */ }
+}

package/src/tracking/one-shot-store.ts

@@ -0,0 +1,95 @@
+/**
+ * @module one-shot-store
+ * Pure, IO-free state model for the per-gate one-shot metric ({@link module:one-shot}).
+ *
+ * Measures the owner's "precision / one-shot" criterion: per gate (keyed by the
+ * block prompt's title) how many times it DENIED and how many were later cleared
+ * by an allow of the same operation (a fix). Globally: `firstTry` (a gateable op
+ * that passed with NO prior deny = one-shot) vs `corrected` (passed after a deny).
+ * The store ({@link module:one-shot}) loads, persists, and wires this into the gate.
+ * @packageDocumentation
+ */
+
+/** Per-gate tally: total denies, denies later fixed by an allow, last-seen clock. */
+export interface GateStat { denies: number; corrected: number; lastTs: number; }
+
+/** One open deny awaiting its fix: the blocking gate title and when it landed. */
+export interface Pending { title: string; ts: number; }
+
+/** Aggregate one-shot state (a sidecar JSON). `pending` links a deny to its later allow. */
+export interface OneShotState {
+  gates: Record<string, GateStat>;
+  firstTry: number;
+  corrected: number;
+  pending: Record<string, Pending>;
+  updatedAt: number;
+  /** Per-tool PostToolUseFailure tally. Optional — absent in pre-0.1.57 sidecars (additive, back-compatible). */
+  failures?: Record<string, number>;
+}
+
+/** A fresh, empty state — always spread (`{ ...EMPTY }`) so the const is never shared. */
+export const EMPTY: OneShotState = { gates: {}, firstTry: 0, corrected: 0, pending: {}, updatedAt: 0 };
+
+/**
+ * Drop stale data: whole-state idle reset past the window, else per-entry prune of
+ * gates/pending older than `windowMs`. Keeps the "7d" window honest, bounds size.
+ */
+export function pruneState(s: OneShotState, now: number, windowMs: number): OneShotState {
+  if (now - s.updatedAt >= windowMs) return { ...EMPTY };
+  const gates: Record<string, GateStat> = {};
+  for (const [k, g] of Object.entries(s.gates)) if (now - g.lastTs < windowMs) gates[k] = g;
+  const pending: Record<string, Pending> = {};
+  for (const [k, p] of Object.entries(s.pending)) if (now - p.ts < windowMs) pending[k] = p;
+  return { ...s, gates, pending };
+}
+
+/**
+ * Record a deny for gate `title` on operation `op` (content-free tool identity):
+ * bump the gate's deny count and mark `op` pending for a later fix.
+ */
+export function applyDeny(s: OneShotState, title: string, op: string, now: number): OneShotState {
+  const g = s.gates[title] ?? { denies: 0, corrected: 0, lastTs: 0 };
+  return {
+    ...s,
+    gates: { ...s.gates, [title]: { denies: g.denies + 1, corrected: g.corrected, lastTs: now } },
+    pending: { ...s.pending, [op]: { title, ts: now } },
+    updatedAt: now,
+  };
+}
+
+/**
+ * Record an allow for a gateable `op`. A non-gateable allow (Read/Task/MCP) leaves
+ * state untouched — it never counts and never clears a pending deny. Otherwise: a
+ * pending deny → `corrected` (a fix, credited to the blocking gate); no pending →
+ * `firstTry` (one-shot).
+ */
+export function applyAllow(s: OneShotState, op: string, now: number, gateable: boolean): OneShotState {
+  if (!gateable) return s;
+  const pend = s.pending[op];
+  if (pend) {
+    const g = s.gates[pend.title] ?? { denies: 0, corrected: 0, lastTs: 0 };
+    const { [op]: _drop, ...pending } = s.pending;
+    return {
+      ...s,
+      gates: { ...s.gates, [pend.title]: { ...g, corrected: g.corrected + 1, lastTs: now } },
+      corrected: s.corrected + 1, pending, updatedAt: now,
+    };
+  }
+  return gateable ? { ...s, firstTry: s.firstTry + 1, updatedAt: now } : s;
+}
+
+/**
+ * Compact injectable summary (one line); "" when there is nothing to report.
+ * @returns e.g. `gates 7d: 88% one-shot (44/50 clean); SOLID file-size limit 4den/3fix`.
+ */
+export function formatSummary(s: OneShotState): string {
+  const keys = Object.keys(s.gates);
+  const total = s.firstTry + s.corrected;
+  if (keys.length === 0 && total === 0) return "";
+  const head = total > 0 ? `${Math.round((s.firstTry / total) * 100)}% one-shot (${s.firstTry}/${total} clean)` : "no clean pass yet";
+  const parts = keys
+    .map((k) => ({ k, g: s.gates[k]! }))
+    .sort((a, b) => b.g.denies - a.g.denies)
+    .map(({ k, g }) => `${k} ${g.denies}den/${g.corrected}fix`);
+  return `gates 7d: ${head}${parts.length ? `; ${parts.join("; ")}` : ""}`;
+}

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