@fusengine/harness 0.1.89 → 0.1.91

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

package/src/tracking/track-lock-sync.ts

@@ -0,0 +1,83 @@
+/**
+ * Synchronous twin of {@link withTrackLock} for lifecycle paths that CANNOT
+ * float async work (the SubagentStop dispatch runs synchronously in a
+ * short-lived hook process — an async write could be dropped before exit,
+ * see `evidence-harvest-io.ts`). Same semantics: `wx` lockfile, bounded total
+ * retry, named skipped write on contention, stale reclamation. The wait uses
+ * `Atomics.wait` (allowed on the main thread in both Node and Bun).
+ */
+import { closeSync, mkdirSync, openSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { LOCK_FAILED, LOCK_RETRY_TOTAL_MS, LOCK_TTL_MS } from "./track-lock";
+
+export { LOCK_FAILED } from "./track-lock";
+
+/** Block the thread for `ms` (bounded by the caller's total budget). */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** True when the lockfile is older than the TTL (orphaned by a dead process). */
+function isStale(lock: string): boolean {
+  try { return Date.now() - statSync(lock).mtimeMs > LOCK_TTL_MS; } catch { return false; }
+}
+
+/**
+ * Run `fn` under the track lock of `dir`, synchronously.
+ * @param dir - The track state directory (lockfile lives inside).
+ * @param fn - The protected read-modify-write.
+ * @returns `fn`'s result, or {@link LOCK_FAILED} when the lock stayed busy.
+ */
+export function withTrackLockSync<T>(dir: string, fn: () => T): T | typeof LOCK_FAILED {
+  mkdirSync(dir, { recursive: true });
+  const lock = join(dir, "track.lock");
+  const deadline = Date.now() + LOCK_RETRY_TOTAL_MS;
+  for (;;) {
+    try {
+      const fd = openSync(lock, "wx");
+      closeSync(fd);
+      break;
+    } catch {
+      if (isStale(lock)) { try { unlinkSync(lock); } catch { /* raced */ } continue; }
+      if (Date.now() >= deadline) {
+        process.stderr.write(`harness: track lock busy, write skipped (${lock})\n`);
+        return LOCK_FAILED;
+      }
+      sleepSync(8);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try { unlinkSync(lock); } catch { /* best-effort release */ }
+  }
+}
+
+/**
+ * Blocking twin of {@link withTrackLockSync}: NEVER skips — spins (1 ms step)
+ * until the lock is acquired. Used by the journal append path (track-journal
+ * `appendEvent`): an append must wait out an in-flight compaction (same
+ * `track.lock`), never race its rename/fold/unlink, never be skipped — a lost
+ * write is not an option. The stale-lock TTL (dead-process reclamation) is the
+ * only anti-deadlock guard. Do NOT use on paths that may already hold the lock.
+ */
+export function withTrackLockSyncBlocking<T>(dir: string, fn: () => T): T {
+  mkdirSync(dir, { recursive: true });
+  const lock = join(dir, "track.lock");
+  for (;;) {
+    try {
+      const fd = openSync(lock, "wx");
+      closeSync(fd);
+      break;
+    } catch {
+      if (isStale(lock)) { try { unlinkSync(lock); } catch { /* raced */ } }
+      sleepSync(1);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try { unlinkSync(lock); } catch { /* best-effort release */ }
+  }
+}
+

package/src/tracking/track-lock.ts

@@ -0,0 +1,67 @@
+/**
+ * Cross-process lock for session-track read-modify-write. The ~11-hook
+ * fan-out races plain `loadTrack → mutate → saveTrack` (writes silently
+ * lost — `refsRead` was the only mitigated channel, via its journal). This
+ * lockfile (`wx`, atomic create) serializes the whole RMW:
+ * - retry is bounded in TOTAL time (400 ms, far under any hook timeout);
+ * - after the budget, NEVER crash: stderr is logged and the caller skips the
+ *   write — a named lost write beats a fail-open crash (hook fail-open
+ *   semantics preserved);
+ * - an orphaned lockfile (dead process) is reclaimed after a 10 s TTL, so a
+ *   crash mid-write never blocks a project forever.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+/** Orphaned lockfile lifetime before reclamation. */
+export const LOCK_TTL_MS = 10_000;
+/** Total bounded retry budget before the write is skipped (fail-open). */
+export const LOCK_RETRY_TOTAL_MS = 400;
+/** Delay between two lock acquisition attempts. */
+const RETRY_STEP_MS = 8;
+
+/** Sentinel returned by {@link withTrackLock} when the lock could not be taken. */
+export const LOCK_FAILED: unique symbol = Symbol("track-lock-failed");
+
+/** True when the lockfile is older than the TTL (orphaned by a dead process). */
+function isStale(lock: string): boolean {
+  try { return Date.now() - statSync(lock).mtimeMs > LOCK_TTL_MS; } catch { return false; }
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Run `fn` under the track lock of `dir`, or skip with a stderr note.
+ * @param dir - The track state directory (lockfile lives inside).
+ * @param fn - The protected read-modify-write.
+ * @returns `fn`'s result, or {@link LOCK_FAILED} when the lock stayed busy.
+ */
+export async function withTrackLock<T>(dir: string, fn: () => Promise<T>): Promise<T | typeof LOCK_FAILED> {
+  mkdirSync(dir, { recursive: true });
+  const lock = join(dir, "track.lock");
+  const deadline = Date.now() + LOCK_RETRY_TOTAL_MS;
+  for (;;) {
+    try {
+      const fd = openSync(lock, "wx");
+      closeSync(fd);
+      break;
+    } catch {
+      if (isStale(lock)) { try { unlinkSync(lock); } catch { /* raced */ } continue; }
+      if (Date.now() >= deadline) {
+        process.stderr.write(`harness: track lock busy, write skipped (${lock})\n`);
+        return LOCK_FAILED;
+      }
+      await sleep(RETRY_STEP_MS);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    try { unlinkSync(lock); } catch { /* best-effort release */ }
+  }
+}
+
+/** Test helper: true when a lockfile currently exists in `dir`. */
+export function trackLockExists(dir: string): boolean {
+  return existsSync(join(dir, "track.lock"));
+}

package/src/util/compact-json.ts

@@ -0,0 +1,23 @@
+/**
+ * Compact JSON serializer for cache/state files.
+ * Top-level keys are indented one per line; nested objects/arrays render inline.
+ * Behaviour preserved from the fusengine hooks.
+ */
+export function compactJson(data: unknown): string {
+  if (typeof data !== "object" || data === null) return `${JSON.stringify(data)}\n`;
+  if (Array.isArray(data)) {
+    if (data.length === 0) return "[]\n";
+    const items = data.map((item) => `  ${JSON.stringify(item)}`);
+    return `[\n${items.join(",\n")}\n]\n`;
+  }
+  const lines: string[] = [];
+  for (const [key, val] of Object.entries(data as Record<string, unknown>)) {
+    if (Array.isArray(val) && val.length > 0) {
+      const items = val.map((item) => `    ${JSON.stringify(item)}`);
+      lines.push(`  "${key}": [\n${items.join(",\n")}\n  ]`);
+    } else {
+      lines.push(`  "${key}": ${JSON.stringify(val)}`);
+    }
+  }
+  return `{\n${lines.join(",\n")}\n}\n`;
+}

package/src/util/index.ts

@@ -0,0 +1,2 @@
+export * from "./compact-json";
+export * from "./project-root";

package/src/util/json-io.ts

@@ -0,0 +1,47 @@
+import { mkdir } from "node:fs/promises";
+import {
+  chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { compactJson } from "./compact-json";
+
+/** Atomically write `data` to `path` (temp + rename, 0o600). Cross-FS safe on macOS/Linux. */
+export function atomicWrite(path: string, data: string): void {
+  const parent = dirname(path);
+  mkdirSync(parent, { recursive: true });
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(tmp, data, { encoding: "utf8" });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* noop */ }
+    throw err;
+  }
+}
+
+/** Ensure a directory exists. */
+export async function ensureDir(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+}
+
+/** Read & JSON-parse a file; null on missing/corrupt. */
+export async function readJsonFile<T>(path: string): Promise<T | null> {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Atomically write JSON (compact form when `compact`). */
+export async function writeJsonFile(path: string, data: unknown, compact = false): Promise<void> {
+  atomicWrite(path, compact ? compactJson(data) : JSON.stringify(data, null, 2));
+}
+
+/** 8-char MD5 of text (cache key; non-cryptographic). Portable Node+Bun. */
+export function hashText(text: string): string {
+  return createHash("md5").update(text).digest("hex").slice(0, 8);
+}

package/src/util/project-root.ts

@@ -0,0 +1,41 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/** Source-code file extensions worth tracking as "code was written". */
+const CODE_EXT =
+  /\.(ts|tsx|js|jsx|py|php|swift|go|rs|rb|java|vue|svelte|astro|css|kt|dart|cpp|c)$/;
+/** Generated/vendored directories that never count as code. */
+const SKIP_DIRS = /(node_modules|vendor|dist|build|\.next|DerivedData|\.git)/;
+
+/** True for a source-code file outside generated/vendored directories. */
+export function isCodeFile(p: string): boolean {
+  return CODE_EXT.test(p) && !SKIP_DIRS.test(p);
+}
+
+/**
+ * Walk up from `dir` to the nearest ancestor directory containing `marker`.
+ * @param dir - Starting directory.
+ * @param marker - Sibling file/dir name to look for at each level.
+ * @returns The ancestor holding `marker`, or `null` at filesystem root.
+ */
+export function walkUpFor(dir: string, marker: string): string | null {
+  let current = resolve(dir);
+  while (current !== "/") {
+    if (existsSync(`${current}/${marker}`)) return current;
+    current = dirname(current);
+  }
+  return null;
+}
+
+/**
+ * Resolve the project root, preferring the repo boundary (`.git`) over a
+ * nested `package.json` — avoids false roots in monorepos. Null if none found.
+ */
+export function projectRootOrNull(dir: string): string | null {
+  return walkUpFor(dir, ".git") ?? walkUpFor(dir, "package.json");
+}
+
+/** Like {@link projectRootOrNull} but falls back to `process.cwd()`. */
+export function projectRoot(dir: string): string {
+  return projectRootOrNull(dir) ?? process.cwd();
+}