freeharness 0.4.1 → 0.4.2

package/canonical/hooks/freeharness-memory-guard.mjs

@@ -1,14 +1,9 @@
-// FreeHarness PreToolUse memory guard.
-// Denies hand-written memory .md files: the free-mem plugin owns persistence, and writing
-// duplicate memory files wastes output tokens. Allows free-mem data, openspec,
-// docs, and the .claude/agent-memory/ and .claude/agent-memory-local/ subtrees (Claude
-// Code's own per-agent memory files); a memory-named basename (MEMORY.md, memory.md,
-// memories.md) is denied everywhere else, a path under .claude/ is never treated as
-// source, and otherwise a .md file under packages/memory/ or vendor/ is allowed as a
-// repository source tree.
-// Reads the hook payload from stdin; emits a deny decision or nothing.
-// The path is normalized (`.`/`..` segments collapsed) before any exemption or deny
-// regex runs, so a traversal segment cannot smuggle a denied path through an exempt one.
+// FreeHarness PreToolUse memory guard: free-mem is the only memory owner, so hand-written
+// memory .md files are denied (duplicates also waste output tokens). Exempt: free-mem data,
+// openspec, docs, node_modules. A name that only contains the word (ai-memory.md) is an
+// ordinary document; packages/memory/ and vendor/ are source, but never under .claude/.
+// The deny reason is constant: an echoed path could carry bidi characters.
+// The path is normalized first, so a `..` segment is judged where it lands.
 import { posix } from "node:path";
 
 let data = "";
@@ -18,26 +13,29 @@ process.stdin.on("end", () => {
   try {
     j = JSON.parse(data);
   } catch {
-    process.exit(0);
+    return;
   }
-  const tool = j.tool_name || "";
-  if (!/^(Write|Edit|MultiEdit)$/.test(tool)) process.exit(0);
+  if (j === null || typeof j !== "object" || Array.isArray(j)) return;
+  const tool = typeof j.tool_name === "string" ? j.tool_name : "";
+  if (!/^(Write|Edit|MultiEdit)$/.test(tool)) return;
 
   const ti = j.tool_input || {};
-  const raw = ti.file_path || ti.path || "";
-  if (!raw) process.exit(0);
+  const field = ti.file_path || ti.path || "";
+  let raw = "";
+  if (typeof field === "string") raw = field;
+  else if (Array.isArray(field) && field.every((e) => typeof e === "string")) raw = field.join(",");
+  if (!raw) return;
 
-  const p = posix.normalize(String(raw).replace(/\\/g, "/"));
+  const p = posix.normalize(raw.replace(/\\/g, "/"));
   const base = p.split("/").pop() || "";
 
-  if (/\/\.claude-mem(\/|$)/.test(p)) process.exit(0);
-  if (/\/(openspec|docs|node_modules)\//.test(p)) process.exit(0);
-  if (/\/\.claude\/agent-memory(-local)?\//.test(p)) process.exit(0);
+  if (/\/\.(free|claude)-mem(\/|$)/.test(p)) return;
+  if (/\/(openspec|docs|node_modules)\//.test(p)) return;
 
   const md = /\.md$/i.test(base);
   const noext = base.replace(/\.md$/i, "");
-  const memName = md && /(^|[._-])(memory|memoria|memories|memorias)([._-]|$)/i.test(noext);
-  const memDir = md && /\/memor(y|ies|ia|ias)\//i.test(p);
+  const memName = md && /^(memory|memoria|memories|memorias)$/i.test(noext);
+  const memDir = md && /\/(memory|memories|memoria|memorias|agent-memory|agent-memory-local)\//i.test(p);
   const claudeDataTree = /\/\.claude\//.test(p);
   const sourceTree = !claudeDataTree && /\/(packages\/memory|vendor)\//.test(p);
 
@@ -53,5 +51,4 @@ process.stdin.on("end", () => {
       }),
     );
   }
-  process.exit(0);
 });

package/canonical/hooks/freeharness-precompact.mjs

@@ -1,18 +1,10 @@
-// FreeHarness PreCompact hook (Claude Code). Runs right before the context is compacted
-// (`/compact` or auto-compaction) and leaves two artifacts for the SessionStart
-// re-orientation (freeharness-session-start, source=compact):
-//   ~/.claude/freeharness/state/<session>.precompact.md  — the eight-section checkpoint
-//     skeleton (Primary Request, Files and Code, Errors and Fixes, Pending Jobs, Current Work,
-//     Next Step, Critical Context, Corrections), one `## <Section>` heading each, built
-//     locally from the transcript; identifiers, paths and error strings copied verbatim.
-//   ~/.claude/freeharness/state/<session>.fileops.json    — [{path, tool, count}] from the
-//     Read/Edit/Write/MultiEdit/NotebookEdit tool_use blocks of the transcript.
-// It also asks the running memory worker to store a session summary
-// (POST /api/sessions/summarize, the same route the Stop hook uses; it queues, it does not
-// return text) so the compaction point lands in memory. The worker being down is normal:
-// the request is skipped, the local skeleton is still written. Never blocks, never prints,
-// exit 0 on every path (a PreCompact hook cannot inject context anyway).
-// Disable: FREEHARNESS_HOOK_PRECOMPACT=off. Worker call off: FREEHARNESS_PRECOMPACT_WORKER=off.
+// FreeHarness PreCompact hook (Claude Code). Before compaction it writes, for the SessionStart
+// re-orientation, `<state>/<session>.precompact.md` (the eight-section skeleton built from the
+// transcript, paths and errors verbatim) and `<session>.fileops.json`, then asks a running
+// free-mem worker for a session summary so the compaction point lands in memory; a down worker
+// is normal, and another program on the port gets a health read only. The context monitor imports the same builder for its handoff. Never blocks,
+// never prints, exit 0 on every path. Disable: FREEHARNESS_HOOK_PRECOMPACT=off; worker call
+// off: FREEHARNESS_PRECOMPACT_WORKER=off.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -35,55 +27,37 @@ const MAX_BODY_CHARS = 1500;
 /** Worker request timeout (ms): a PreCompact hook must never hold the compaction. */
 const WORKER_TIMEOUT_MS = 2000;
 
+/** Bounds on the file operations sent to the worker, so a long session cannot inflate the request. */
+const MAX_SENT_FILE_OPS = 50;
+const MAX_SENT_PATH_CHARS = 1024;
+const MAX_SENT_TOOL_CHARS = 64;
+
 /** Error markers (case-insensitive) that make a tool result an "Errors and Fixes" line. */
 const ERROR_RE = /\b(error|ENOENT|EACCES|EEXIST|failed|failure|Traceback|exception|not found|permission denied|cannot|exit code [1-9])\b/i;
 
 /** User turns that read as a correction of the assistant. */
 const CORRECTION_RE = /^(no[,.! ]|not (that|this|what)|wrong|don'?t |do not |stop |instead[, ]|that'?s (not|wrong)|actually[, ]|undo|revert|never )/i;
 
-/**
- * State directory (FREEHARNESS_STATE_DIR overrides).
- * @returns {string} Absolute path.
- */
+/** @returns {string} The state dir (FREEHARNESS_STATE_DIR overrides). */
 export function stateDir() {
   return process.env.FREEHARNESS_STATE_DIR || path.join(os.homedir(), ".claude", "freeharness", "state");
 }
 
-/**
- * Sanitizes a session id for use as a file name.
- * @param {string} id Session id.
- * @returns {string} Safe name.
- */
 function safeId(id) {
   return String(id || "").replace(/[^\w.-]/g, "_") || "unknown";
 }
 
-/**
- * Trims a string to one line of at most MAX_LINE_CHARS, marking the cut.
- * @param {string} s Text.
- * @param {number} [max] Cap.
- * @returns {string} One line.
- */
 function oneLine(s, max = MAX_LINE_CHARS) {
   const t = String(s).replace(/\s+/g, " ").trim();
   return t.length > max ? `${t.slice(0, max)} …[+${t.length - max} chars]` : t;
 }
 
-/**
- * Caps a multi-line body, keeping the head.
- * @param {string} s Text.
- * @returns {string} Body.
- */
 function capBody(s) {
   const t = String(s).trim();
   return t.length > MAX_BODY_CHARS ? `${t.slice(0, MAX_BODY_CHARS)}\n…[+${t.length - MAX_BODY_CHARS} chars]` : t;
 }
 
-/**
- * Text of a message content (string or text blocks), tool results excluded.
- * @param {unknown} content Message content.
- * @returns {string} Joined text.
- */
+/** Text blocks of a message content only: tool results are not prose. */
 function textOf(content) {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return "";
@@ -93,22 +67,12 @@ function textOf(content) {
     .join("\n");
 }
 
-/**
- * True for user turns that are not real prompts (system reminders, slash-command echoes,
- * tool results, interruption notices).
- * @param {string} text User text.
- * @returns {boolean} Skip it.
- */
+/** User turns that are not prompts: system reminders, command echoes, interruption notices. */
 function isMetaUserText(text) {
   const t = text.trim();
   return !t || t.startsWith("<") || t.startsWith("[Request interrupted") || /^Caveat: The messages below/.test(t);
 }
 
-/**
- * Text of a tool_result block (string or nested text blocks).
- * @param {any} block tool_result block.
- * @returns {string} Text.
- */
 function toolResultText(block) {
   if (typeof block.content === "string") return block.content;
   if (Array.isArray(block.content)) return textOf(block.content);
@@ -149,7 +113,8 @@ export function parseTranscript(transcript) {
     if (typeof rec.gitBranch === "string" && rec.gitBranch) branches.add(rec.gitBranch);
     const msg = rec.message;
     if (!msg || typeof msg !== "object") continue;
-    const role = rec.type === "user" || rec.type === "assistant" ? rec.type : msg.role;
+    if (rec.type !== "user" && rec.type !== "assistant") continue;
+    const role = rec.type;
     const content = Array.isArray(msg.content) ? msg.content : [];
     if (role === "assistant") {
       const t = textOf(msg.content);
@@ -183,13 +148,8 @@ export function parseTranscript(transcript) {
   return { users, assistants, fileOps, errors, cwds, branches };
 }
 
-/**
- * Renders the eight-section skeleton from transcript facts.
- * @param {ReturnType<typeof parseTranscript>} facts Facts (null = unreadable transcript).
- * @param {Record<string, any>} payload Hook payload.
- * @returns {string} Markdown with one `## <Section>` heading per section.
- */
-export function renderSkeleton(facts, payload) {
+/** Body per section name, "" when empty; null facts (unreadable transcript) leave all empty. */
+function sectionBodies(facts, payload) {
   const body = {};
   const f = facts || { users: [], assistants: [], fileOps: [], errors: [], cwds: new Set(), branches: new Set() };
   const dedupe = (arr) => [...new Set(arr)];
@@ -212,8 +172,11 @@ export function renderSkeleton(facts, payload) {
   if (typeof payload.custom_instructions === "string" && payload.custom_instructions.trim()) critical.push(`compact instructions: ${oneLine(payload.custom_instructions)}`);
   body["Critical Context"] = critical.join("\n");
   body["Corrections"] = dedupe(f.users.filter((u) => CORRECTION_RE.test(u.trim())).map((u) => `- ${oneLine(u)}`)).slice(-MAX_ITEMS).join("\n");
+  return body;
+}
 
-  const lines = [`<!-- freeharness-precompact ${new Date().toISOString()} session=${safeId(payload.session_id)} -->`];
+function renderSections(body) {
+  const lines = [];
   for (const s of SECTIONS) {
     lines.push(`## ${s}`);
     lines.push(body[s] && body[s].trim() ? body[s] : "(none)");
@@ -222,56 +185,223 @@ export function renderSkeleton(facts, payload) {
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
+/** The PreCompact file: a stamp line, then the eight sections. */
+export function renderSkeleton(facts, payload) {
+  return `<!-- freeharness-precompact ${new Date().toISOString()} session=${safeId(payload.session_id)} -->\n${renderSections(sectionBodies(facts, payload))}`;
+}
+
+/** Transcript text must not reach a session as an envelope or system tag: `<a` and `</` become `<\a` and `<\/`. */
+export function neutralize(text) {
+  return String(text).replace(/<(?=[\p{L}/])/gu, "<\\");
+}
+
+/** L2 is cut first; L0 holds what the re-read rule names, so it goes last. */
+const CUT_LEVELS = [
+  ["Files and Code", "Pending Jobs"],
+  ["Primary Request", "Critical Context", "Corrections"],
+  ["Current Work", "Errors and Fixes", "Next Step"],
+];
+const LIST_SECTIONS = new Set(["Files and Code", "Pending Jobs", "Errors and Fixes", "Corrections"]);
+
+/** Lists keep whole lines behind `(+N more)`; prose, or a list too long in its first line, keeps its head behind `(cut)`. */
+function cutBody(body, room, list) {
+  const lines = body.split("\n");
+  if (list && lines.length > 1) {
+    for (let keep = lines.length - 1; keep >= 1; keep--) {
+      const out = `${lines.slice(0, keep).join("\n")}\n(+${lines.length - keep} more)`;
+      if (Buffer.byteLength(out) <= room) return out;
+    }
+  }
+  const marker = "(cut)";
+  let head = "";
+  let used = Buffer.byteLength(` ${marker}`);
+  for (const ch of body) {
+    const n = Buffer.byteLength(ch);
+    if (used + n > room) break;
+    head += ch;
+    used += n;
+  }
+  return head.trim() ? `${head.trimEnd()} ${marker}` : marker;
+}
+
 /**
- * Mirrors the engine's data-dir resolution: CLAUDE_MEM_DATA_DIR, settings.json, ~/.claude-mem.
- * @returns {string} Absolute path.
+ * The eight sections of a transcript without the stamp line; null when it is unreadable.
+ * @param {{mapBody?: (s: string) => string, maxBytes?: number}} [opts] `mapBody` rewrites each
+ *   body; `maxBytes` caps the result in the L2, L1, L0 cut order.
  */
-export function memDataDir() {
-  const expand = (p) => (p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
-  if (process.env.CLAUDE_MEM_DATA_DIR) return expand(process.env.CLAUDE_MEM_DATA_DIR);
-  const def = path.join(os.homedir(), ".claude-mem");
+export function buildSkeleton(transcriptPath, payload = {}, opts = {}) {
+  const facts = parseTranscript(transcriptPath);
+  return facts ? skeletonFromFacts(facts, payload, opts) : null;
+}
+
+/** buildSkeleton over parsed facts, for a caller that needs the facts too and parses once. */
+export function skeletonFromFacts(facts, payload, opts = {}) {
+  const body = sectionBodies(facts, payload);
+  if (typeof opts.mapBody === "function") for (const s of SECTIONS) body[s] = opts.mapBody(body[s]);
+  const max = opts.maxBytes;
+  if (!Number.isFinite(max)) return renderSections(body);
+  for (const level of CUT_LEVELS) {
+    for (const s of level) {
+      const over = Buffer.byteLength(renderSections(body)) - max;
+      if (over <= 0) return renderSections(body);
+      if (!body[s] || !body[s].trim()) continue;
+      body[s] = cutBody(body[s], Math.max(0, Buffer.byteLength(body[s]) - over), LIST_SECTIONS.has(s));
+    }
+  }
+  return renderSections(body);
+}
+
+// The engine's data-dir and port rule; an emitted hook cannot import the engine.
+const MEM_DATA_DIR_KEYS = ["FREE_MEM_DATA_DIR", "CLAUDE_MEM_DATA_DIR"];
+const BOM = 0xfeff;
+
+function expandMemHome(p, home) {
+  if (p === "~") return home;
+  return p.startsWith("~/") ? path.join(home, p.slice(2)) : p;
+}
+
+function isMemDirectory(p) {
   try {
-    const raw = JSON.parse(fs.readFileSync(path.join(def, "settings.json"), "utf8"));
-    const s = (raw && raw.env) || raw || {};
-    if (typeof s.CLAUDE_MEM_DATA_DIR === "string") return expand(s.CLAUDE_MEM_DATA_DIR);
+    return fs.statSync(p).isDirectory();
   } catch {
-    // default
+    return false;
   }
-  return def;
 }
 
-/**
- * Mirrors the engine's worker port: CLAUDE_MEM_WORKER_PORT (env, then settings.json), else 37700 + uid % 100.
- * @returns {number} Port.
- */
-export function workerPort() {
-  const fromEnv = Number.parseInt(process.env.CLAUDE_MEM_WORKER_PORT || "", 10);
-  if (Number.isFinite(fromEnv) && fromEnv > 0) return fromEnv;
+/** Keys as the engine reads them: BOM dropped, `env` first. */
+function readMemSettings(file) {
   try {
-    const raw = JSON.parse(fs.readFileSync(path.join(memDataDir(), "settings.json"), "utf8"));
-    const s = (raw && raw.env) || raw || {};
-    const p = Number.parseInt(String(s.CLAUDE_MEM_WORKER_PORT || ""), 10);
-    if (Number.isFinite(p) && p > 0) return p;
+    const text = fs.readFileSync(file, "utf8");
+    const raw = JSON.parse(text.charCodeAt(0) === BOM ? text.slice(1) : text);
+    const s = raw && (raw.env ?? raw);
+    return s && typeof s === "object" ? s : null;
   } catch {
-    // default
+    return null;
+  }
+}
+
+function memPort(value) {
+  const p = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(p) && p > 0 ? p : null;
+}
+
+/** The memory data directory from `env` and `home` alone, so a test can pass fake values. */
+export function resolveMemoryDataDir(env, home) {
+  for (const key of MEM_DATA_DIR_KEYS) {
+    if (typeof env[key] === "string" && env[key]) return expandMemHome(env[key], home);
   }
+  const freeDir = path.join(home, ".free-mem");
+  const legacyDir = path.join(home, ".claude-mem");
+  const defaults = [path.resolve(freeDir), path.resolve(legacyDir)];
+  for (const dir of [freeDir, legacyDir]) {
+    const s = readMemSettings(path.join(dir, "settings.json"));
+    for (const key of MEM_DATA_DIR_KEYS) {
+      const value = s ? s[key] : undefined;
+      if (typeof value !== "string" || !value) continue;
+      const target = expandMemHome(value, home);
+      // A seeded default is not a redirect; honoring it would pin the directory choice.
+      if (!defaults.includes(path.resolve(target))) return target;
+    }
+  }
+  return isMemDirectory(freeDir) || !isMemDirectory(legacyDir) ? freeDir : legacyDir;
+}
+
+/** The worker port: env (empty is unset), then the data dir's settings, else the default; pure over (env, home). */
+export function resolveWorkerPort(env, home) {
+  const fromEnv = memPort(env.FREE_MEM_WORKER_PORT || env.CLAUDE_MEM_WORKER_PORT);
+  if (fromEnv !== null) return fromEnv;
+  const s = readMemSettings(path.join(resolveMemoryDataDir(env, home), "settings.json"));
+  const fromSettings = s ? memPort(s.FREE_MEM_WORKER_PORT ?? s.CLAUDE_MEM_WORKER_PORT) : null;
+  return fromSettings ?? defaultWorkerPort();
+}
+
+function defaultWorkerPort() {
   return 37700 + (((typeof process.getuid === "function" ? process.getuid() : 77) || 0) % 100);
 }
 
+/** A resolver error falls back to the default port, as an unreadable settings file does. */
+export function workerPort() {
+  try {
+    return resolveWorkerPort(process.env, os.homedir());
+  } catch {
+    return defaultWorkerPort();
+  }
+}
+
+/** Another program may hold the port; the engine's FREE_MEM_PRODUCT, copied because this script cannot import it (a test pins both). */
+export const FREE_MEM_PRODUCT = "free-mem";
+const MAX_HEALTH_BYTES = 64 * 1024;
+
+/** Nothing from the answer leaves this function: the port may belong to an unknown program. */
+export async function workerIsFreeMem(port, deadlineMs) {
+  try {
+    if (!Number.isInteger(port) || port < 1 || port > 65535 || !(deadlineMs > 0)) return false;
+    const res = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(deadlineMs) });
+    if (res.status !== 200 || !res.body) {
+      res.body?.cancel().catch(() => {});
+      return false;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > MAX_HEALTH_BYTES) {
+        reader.cancel().catch(() => {});
+        return false;
+      }
+      chunks.push(value);
+    }
+    const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && parsed.product === FREE_MEM_PRODUCT;
+  } catch {
+    return false;
+  }
+}
+
+const TAG_OPENER_RE = /<[A-Za-z/]/;
+
+function sendable(s, max) {
+  return typeof s === "string" && s.length > 0 && s.length <= max && !TAG_OPENER_RE.test(s);
+}
+
+/**
+ * The first file operations, bounded for the request. An over-long or tagged entry is
+ * dropped whole: a cut could split a <private> span and leave an opener the worker keeps.
+ * @param {unknown[]} fileOps The parsed list.
+ * @returns {{path:string,tool:string,count:number}[]} At most MAX_SENT_FILE_OPS entries.
+ */
+function boundedFileOps(fileOps) {
+  const sent = [];
+  for (const op of fileOps) {
+    if (sent.length === MAX_SENT_FILE_OPS) break;
+    if (!op || !sendable(op.path, MAX_SENT_PATH_CHARS) || !sendable(op.tool, MAX_SENT_TOOL_CHARS) || !Number.isSafeInteger(op.count)) continue;
+    sent.push({ path: op.path, tool: op.tool, count: op.count });
+  }
+  return sent;
+}
+
 /**
  * Asks the worker to queue a session summary (the Stop hook's route). Best effort.
  * @param {string} sessionId Content session id.
  * @param {string} lastAssistant Last assistant text (may be empty).
+ * @param {unknown[]} [fileOps] The session file operations; without a list the body has no file_ops.
  * @returns {Promise<"queued"|"skipped"|"down">} Outcome.
  */
-export async function requestSummary(sessionId, lastAssistant) {
+export async function requestSummary(sessionId, lastAssistant, fileOps) {
   if ((process.env.FREEHARNESS_PRECOMPACT_WORKER || "").toLowerCase() === "off") return "skipped";
-  const url = `http://127.0.0.1:${workerPort()}/api/sessions/summarize`;
+  const port = workerPort();
+  if (!(await workerIsFreeMem(port, WORKER_TIMEOUT_MS))) return "down";
+  const url = `http://127.0.0.1:${port}/api/sessions/summarize`;
+  const body = { contentSessionId: sessionId, last_assistant_message: lastAssistant, platformSource: "claude-code" };
+  if (Array.isArray(fileOps)) body.file_ops = boundedFileOps(fileOps);
   try {
     const res = await fetch(url, {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ contentSessionId: sessionId, last_assistant_message: lastAssistant, platformSource: "claude-code" }),
+      body: JSON.stringify(body),
       signal: AbortSignal.timeout(WORKER_TIMEOUT_MS),
     });
     return res.ok ? "queued" : "down";
@@ -295,7 +425,7 @@ export async function respond(payload) {
   fs.writeFileSync(summary, renderSkeleton(facts, payload), "utf8");
   fs.writeFileSync(fileops, `${JSON.stringify(facts ? facts.fileOps : [])}\n`, "utf8");
   const lastAssistant = facts && facts.assistants.length ? facts.assistants[facts.assistants.length - 1] : "";
-  const worker = await requestSummary(sessionId, lastAssistant);
+  const worker = await requestSummary(sessionId, lastAssistant, facts ? facts.fileOps : []);
   return { summary, fileops, worker };
 }
 

package/canonical/hooks/freeharness-quota-tap.mjs

@@ -0,0 +1,173 @@
+// FreeHarness quota tap, fed by the owner's status line command (the only documented source of
+// the subscription window percentages; FreeHarness never writes `statusLine`). Untrusted input:
+// only validated numbers and a sanitized model id reach the file. Silent, exit 0 on every path.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const READINGS_FILE = "quota-readings.jsonl";
+export const MAX_INPUT_BYTES = 64 * 1024;
+export const MAX_MODEL_CHARS = 128;
+export const MAX_LINE_BYTES = 4096;
+export const TAIL_BYTES = 8 * 1024;
+export const ROTATE_BYTES = 2 * 1024 * 1024;
+/** Counted from process start: Node start-up alone spends tens of the status line's 200 ms. */
+const DEADLINE_MS = 150;
+/** Lets one poll pass read input already in the pipe when start-up overran the deadline. */
+const MIN_WAIT_MS = 5;
+/** A consumer printing the model id must never meet controls, bidi or line separators. */
+const UNSAFE_CHARS = /[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/u;
+
+function own(obj, key) {
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) return undefined;
+  return Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
+}
+
+/** resets_at must be a safe integer so the comparison with the last line stays exact. */
+export function windowOf(value) {
+  const pct = own(value, "used_percentage");
+  const resets = own(value, "resets_at");
+  if (typeof pct !== "number" || !Number.isFinite(pct) || pct < 0 || pct > 100) return null;
+  if (typeof resets !== "number" || !Number.isSafeInteger(resets) || resets <= 0) return null;
+  return { used_percentage: pct === 0 ? 0 : pct, resets_at: resets };
+}
+
+export function readingOf(payload) {
+  const limits = own(payload, "rate_limits");
+  const fiveHour = windowOf(own(limits, "five_hour"));
+  const sevenDay = windowOf(own(limits, "seven_day"));
+  if (fiveHour === null && sevenDay === null) return null;
+  const id = own(own(payload, "model"), "id");
+  const model = typeof id === "string" && id.length > 0 && id.length <= MAX_MODEL_CHARS && !UNSAFE_CHARS.test(id) ? id : null;
+  return { model, five_hour: fiveHour, seven_day: sevenDay };
+}
+
+function sameWindow(current, previous) {
+  if (current === null) return previous === null;
+  return own(previous, "used_percentage") === current.used_percentage && own(previous, "resets_at") === current.resets_at;
+}
+
+/** Reads through the open descriptor, so the file checked by fstat is the one compared. */
+function tailOf(fd, size) {
+  if (size === 0) return { last: null, endsWithNewline: true };
+  const want = Math.min(size, TAIL_BYTES);
+  const buf = Buffer.alloc(want);
+  let got = 0;
+  while (got < want) {
+    const n = fs.readSync(fd, buf, got, want - got, size - want + got);
+    if (n === 0) break;
+    got += n;
+  }
+  const text = buf.toString("utf8", 0, got);
+  const endsWithNewline = text.endsWith("\n");
+  // A trailing fragment is a torn write; the line before it is the last complete one.
+  const complete = endsWithNewline ? text.slice(0, -1) : text.slice(0, Math.max(text.lastIndexOf("\n"), 0));
+  const start = complete.lastIndexOf("\n");
+  // Without a newline before it, the line may begin before the tail window.
+  if (start === -1 && size > want) return { last: null, endsWithNewline };
+  const last = complete.slice(start + 1);
+  return { last: last === "" ? null : last, endsWithNewline };
+}
+
+function unchanged(reading, last) {
+  if (last === null) return false;
+  let prev;
+  try {
+    prev = JSON.parse(last);
+  } catch {
+    return false;
+  }
+  return sameWindow(reading.five_hour, own(prev, "five_hour")) && sameWindow(reading.seven_day, own(prev, "seven_day"));
+}
+
+function lstatOrNull(p, io) {
+  try {
+    return io.lstatSync(p);
+  } catch (e) {
+    if (e && e.code === "ENOENT") return null;
+    throw e;
+  }
+}
+
+/**
+ * Refusals keep the append out of any file the tap did not create. `io` supplies the lstat and
+ * rename calls, so a test can place another tap's rotation between this tap's two lstats.
+ */
+export function record(text, home = os.homedir(), now = new Date(), io = fs) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return "invalid";
+  }
+  const reading = readingOf(payload);
+  if (reading === null) return "invalid";
+  const dir = path.join(home, ".claude", "freeharness");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, READINGS_FILE);
+  const before = lstatOrNull(file, io);
+  if (before !== null && (!before.isFile() || before.nlink > 1)) return "refused";
+  if (before !== null && before.size > ROTATE_BYTES) {
+    const rotated = lstatOrNull(`${file}.1`, io);
+    if (rotated !== null && !rotated.isFile()) return "refused";
+    // Only the file the first lstat judged over the bound is renamed: a file another tap rotated,
+    // removed or grew since then is left for the append, so .1 always holds a full history. The
+    // rename itself never writes through a link.
+    const again = lstatOrNull(file, io);
+    const same = again !== null && again.dev === before.dev && again.ino === before.ino && again.size === before.size;
+    if (same && again.size > ROTATE_BYTES) io.renameSync(file, `${file}.1`);
+  }
+  const flags = fs.constants.O_RDWR | fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW | (fs.constants.O_NONBLOCK || 0);
+  const fd = fs.openSync(file, flags, 0o600);
+  try {
+    // The lstat above can race a swap; the fstat on the open descriptor decides.
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.nlink > 1) return "refused";
+    const tail = tailOf(fd, st.size);
+    if (unchanged(reading, tail.last)) return "unchanged";
+    const line = `${tail.endsWithNewline ? "" : "\n"}${JSON.stringify({ ts: now.toISOString(), ...reading })}\n`;
+    const bytes = Buffer.from(line, "utf8");
+    if (bytes.length >= MAX_LINE_BYTES) return "invalid";
+    // One write under 4 KiB on an O_APPEND descriptor stays whole against concurrent taps.
+    fs.writeSync(fd, bytes, 0, bytes.length);
+    return "written";
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function main() {
+  process.on("uncaughtException", () => process.exit(0));
+  const chunks = [];
+  let got = 0;
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    try {
+      record(Buffer.concat(chunks, got).toString("utf8"));
+    } catch {
+      // Silent by contract: a status line must never show tap errors.
+    }
+    process.exit(0);
+  };
+  // A writer that never closes stdin must not hold the status line: what arrived is all there is.
+  setTimeout(finish, Math.max(MIN_WAIT_MS, DEADLINE_MS - performance.now()));
+  process.stdin.on("data", (chunk) => {
+    const part = chunk.subarray(0, MAX_INPUT_BYTES - got);
+    chunks.push(part);
+    got += part.length;
+    if (got >= MAX_INPUT_BYTES) finish();
+  });
+  process.stdin.on("end", finish);
+  process.stdin.on("error", finish);
+}
+
+let direct = false;
+try {
+  direct = Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+} catch {
+  direct = false;
+}
+if (direct) main();