@fusengine/harness 0.1.90 → 0.1.92

package/src/freshness/query-framework.ts

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

package/src/freshness/ref-evidence.ts

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

package/src/freshness/ref-journal.ts

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

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

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

package/src/index.ts

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

package/src/init/index.ts

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

package/src/init/run.ts

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

package/src/init/templates.ts

@@ -0,0 +1,75 @@
+/**
+ * Wiring file templates per harness, registering `harness hook <id>` for BOTH
+ * phases: PRE (gate the edit) and POST (catch-all → `activityFor` filters what
+ * to record). Formats verified against each harness's 2026 hook docs.
+ */
+
+/** A file to write during `harness init`. */
+export interface InitFile {
+  path: string;
+  content: string;
+  executable?: boolean;
+}
+
+function json(obj: unknown): string {
+  return `${JSON.stringify(obj, null, 2)}\n`;
+}
+
+/** Claude Code: `.claude/settings.json` — PreToolUse(Write|Edit) + PostToolUse(all). */
+export function claudeInit(command: string): InitFile[] {
+  return [{
+    path: ".claude/settings.json",
+    content: json({ hooks: {
+      PreToolUse: [{ matcher: "Write|Edit|Bash", hooks: [{ type: "command", command }] }],
+      PostToolUse: [{ matcher: "", hooks: [{ type: "command", command }] }],
+    } }),
+  }];
+}
+
+/** Codex CLI: `.codex/hooks.json` (Claude-compatible shape). */
+export function codexInit(command: string): InitFile[] {
+  return [{
+    path: ".codex/hooks.json",
+    content: json({ hooks: {
+      PreToolUse: [{ matcher: "Bash|apply_patch", hooks: [{ type: "command", command }] }],
+      PostToolUse: [{ matcher: "", hooks: [{ type: "command", command }] }],
+      UserPromptSubmit: [{ matcher: "", hooks: [{ type: "command", command }] }],
+    } }),
+  }];
+}
+
+/** Cursor: `.cursor/hooks.json` (version 1) — supported pre gates and post observers. */
+export function cursorInit(command: string): InitFile[] {
+  return [{
+    path: ".cursor/hooks.json",
+    content: json({ version: 1, hooks: {
+      beforeShellExecution: [{ command, failClosed: true }],
+      preToolUse: [{ command, failClosed: true }],
+      beforeMCPExecution: [{ command, failClosed: true }],
+      beforeReadFile: [{ command, failClosed: true }],
+      afterShellExecution: [{ command }],
+      postToolUse: [{ command }],
+      afterFileEdit: [{ command }],
+    } }),
+  }];
+}
+
+/** Gemini CLI: `.gemini/settings.json` — BeforeTool(edits) + AfterTool(all, regex). */
+export function geminiInit(command: string): InitFile[] {
+  return [{
+    path: ".gemini/settings.json",
+    content: json({ hooks: {
+      BeforeTool: [{ matcher: "write_file|edit_file|replace", hooks: [{ type: "command", command, timeout: 30000 }] }],
+      AfterTool: [{ matcher: ".*", hooks: [{ type: "command", command, timeout: 30000 }] }],
+    } }),
+  }];
+}
+
+/** Cline: executable `.clinerules/hooks/PreToolUse` + `PostToolUse` piping stdin. */
+export function clineInit(command: string): InitFile[] {
+  const script = (phase: string): string => `#!/usr/bin/env bash\n# fuse-harness Cline ${phase} hook\ncat | ${command}\n`;
+  return [
+    { path: ".clinerules/hooks/PreToolUse", content: script("pre"), executable: true },
+    { path: ".clinerules/hooks/PostToolUse", content: script("post"), executable: true },
+  ];
+}

package/src/memory/gitignore.ts

@@ -0,0 +1,14 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+/** Ensure `<memoryDir>/.gitignore` ignores the machine-local `state.json`. */
+export function ensureMemoryGitignore(memoryDir: string): void {
+  const file = `${memoryDir}/.gitignore`;
+  try {
+    const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+    if (/^state\.json$/m.test(existing)) return;
+    const next = existing.trim() ? `${existing.trimEnd()}\nstate.json\n` : "state.json\n";
+    writeFileSync(file, next);
+  } catch {
+    /* non-fatal: memory must never block a session */
+  }
+}

package/src/memory/index.ts

@@ -0,0 +1,3 @@
+export * from "./state";
+export * from "./registry";
+export * from "./gitignore";

package/src/memory/registry.ts

@@ -0,0 +1,39 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Registry path relative to the home dir. */
+const SUBPATH = ".fuse-harness/cache/lessons/roots.json";
+
+/** Absolute path of the global roots registry, or null when home is unusable. */
+export function registryFile(home: string | undefined = process.env.HOME): string | null {
+  const h = home?.trim();
+  if (!h || !h.startsWith("/")) return null;
+  return `${h}/${SUBPATH}`;
+}
+
+/** Read the registered project roots (deduplicated string entries only). */
+export function readRoots(home?: string): string[] {
+  const file = registryFile(home);
+  if (!file) return [];
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+    return Array.isArray(parsed) ? parsed.filter((e): e is string => typeof e === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Register a project root once (deduplicated, read-modify-write, non-throwing). */
+export function addRoot(root: string, home?: string): void {
+  const file = registryFile(home);
+  if (!file) return;
+  try {
+    const roots = new Set(readRoots(home));
+    if (roots.has(root)) return;
+    roots.add(root);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify([...roots]));
+  } catch {
+    /* non-fatal: a missed root never blocks the session */
+  }
+}

package/src/memory/session-roots.ts

@@ -0,0 +1,99 @@
+/**
+ * Session-scoped lessons roots registry. The flat {@link module:memory/registry}
+ * keeps ONE global list of pending roots — correct mono-session, but wrong with
+ * several concurrent Claude Code sessions: at Stop, one session lists (and, by
+ * bumping the throttle, STEALS) another session's pending lesson on a project it
+ * never touched. This registry keys "which project got code edits, and was its
+ * Stop reminder already fired" by `session_id`, so each Stop sees and consumes
+ * ONLY its own roots. Stored at `$HOME/.fuse-harness/cache/lessons/session-roots.json`;
+ * non-fatal on any I/O failure (a missed reminder never blocks a session).
+ */
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWrite } from "../util/json-io";
+
+/** Per-(session, root) throttle: last code edit vs. last reminder emitted. */
+export interface RootMark {
+  editedAt: number;
+  remindedAt: number;
+}
+/** One session's edited roots plus an `updatedAt` purge cursor. */
+interface SessionEntry {
+  updatedAt: number;
+  roots: Record<string, RootMark>;
+}
+/** Whole registry keyed by sanitized `session_id`. */
+type Registry = Record<string, SessionEntry>;
+
+/** Registry path (rel. home) + stale-bucket purge horizon (bounds growth). */
+const SUBPATH = ".fuse-harness/cache/lessons/session-roots.json";
+const PURGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Absolute registry path, or null when home is unusable. */
+function file(home: string | undefined): string | null {
+  const h = home?.trim();
+  return h && h.startsWith("/") ? `${h}/${SUBPATH}` : null;
+}
+
+/** Read the registry; missing/corrupt/legacy (array) shapes collapse to `{}`. */
+function read(home: string | undefined): Registry {
+  const f = file(home);
+  if (!f) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(f, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Registry) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Purge stale buckets, then atomically persist (unique tmp + rename). Non-throwing. */
+function write(home: string | undefined, reg: Registry, now: number): void {
+  const f = file(home);
+  if (!f) return;
+  for (const [sid, entry] of Object.entries(reg)) {
+    if (!entry || now - (entry.updatedAt ?? 0) > PURGE_MS) delete reg[sid];
+  }
+  try {
+    mkdirSync(dirname(f), { recursive: true });
+    atomicWrite(f, JSON.stringify(reg));
+  } catch {
+    /* non-fatal: a missed root never blocks the session */
+  }
+}
+
+/** Record `field` for `(sid, root)`, refreshing the purge cursor. `home` defaults to `$HOME`. */
+export function markSessionRoot(
+  sid: string, root: string, field: keyof RootMark, value: number, home: string | undefined = process.env.HOME,
+): void {
+  const reg = read(home);
+  const prev = reg[sid];
+  const entry: SessionEntry = prev && typeof prev.roots === "object" && prev.roots !== null ? prev : { updatedAt: value, roots: {} };
+  const mark = entry.roots[root] ?? { editedAt: 0, remindedAt: 0 };
+  entry.roots[root] = { ...mark, [field]: value };
+  entry.updatedAt = value;
+  reg[sid] = entry;
+  write(home, reg, value);
+}
+
+/**
+ * Roots of `sid` with an unsaved code edit past the `window`; each returned
+ * root's `remindedAt` is bumped to `now` so the reminder fires at most once per
+ * window and is consumed ONLY by this session. `home` defaults to `$HOME`.
+ */
+export function collectSessionPending(
+  sid: string, now: number, window: number, home: string | undefined = process.env.HOME,
+): string[] {
+  const reg = read(home);
+  const entry = reg[sid];
+  if (!entry || typeof entry.roots !== "object" || entry.roots === null) return [];
+  const pending: string[] = [];
+  for (const [root, mark] of Object.entries(entry.roots)) {
+    if (mark.editedAt <= mark.remindedAt) continue;
+    if (now - mark.remindedAt < window) continue;
+    pending.push(root);
+    entry.roots[root] = { ...mark, remindedAt: now };
+  }
+  if (pending.length > 0) write(home, reg, now);
+  return pending;
+}

package/src/memory/state.ts

@@ -0,0 +1,58 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { projectLayout } from "../config/layout";
+import { ensureMemoryGitignore } from "./gitignore";
+
+/** Per-project reminder throttle state, stored at `<root>/MEMORY/state.json`. */
+export interface ReminderState {
+  lastRemindedAt: number;
+  lastCodeEditAt: number;
+}
+
+/** Absolute path of the per-project throttle state file. */
+export function stateFileFor(root: string): string {
+  return projectLayout(root).memoryStateFile;
+}
+
+/** Absolute path of the per-project curated lessons file (committable). */
+export function lessonsFileFor(root: string): string {
+  return projectLayout(root).lessonsFile;
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+/** Read both throttle timestamps; missing/corrupt fields default to 0. */
+export function readState(file: string): ReminderState {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as Partial<ReminderState>;
+    return { lastRemindedAt: num(parsed?.lastRemindedAt), lastCodeEditAt: num(parsed?.lastCodeEditAt) };
+  } catch {
+    return { lastRemindedAt: 0, lastCodeEditAt: 0 };
+  }
+}
+
+/** Persist one field without clobbering the other (read-modify-write). */
+export function setStateField(file: string, key: keyof ReminderState, value: number): void {
+  const next: ReminderState = { ...readState(file), [key]: value };
+  const dir = dirname(file);
+  mkdirSync(dir, { recursive: true });
+  ensureMemoryGitignore(dir);
+  atomicWrite(file, JSON.stringify(next));
+}
+
+/** Local wall-clock timestamp for a lesson bullet: `YYYY-MM-DD HH:MM`. */
+export function nowStamp(): string {
+  const d = new Date();
+  const p = (n: number): string => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/** Throttle window (ms) from `FUSE_LESSONS_THROTTLE_MIN` (default 5 min). */
+export function throttleMs(env: Record<string, string | undefined> = process.env): number {
+  const raw = env.FUSE_LESSONS_THROTTLE_MIN?.trim();
+  const min = raw ? Number(raw) : 5;
+  return (Number.isFinite(min) ? Math.max(0, min) : 5) * 60_000;
+}