freeharness 0.4.1 → 0.4.2

package/canonical/hooks/freeharness-reload-context.mjs

@@ -0,0 +1,197 @@
+// FreeHarness reload-context recap (Claude Code UserPromptSubmit hook). Only the prompt whose
+// trimmed, lower-cased text is exactly `reload context` gets output: the newest (by mtime) of the
+// project's unclaimed handoff and the session's PreCompact skeleton, rendered as the SessionStart
+// re-orientation and cut under 10,000 characters, or one line saying no saved context exists.
+// Reading never claims or renames the handoff: the next session in the project still gets it.
+// Every other prompt is a fast silent exit. Never blocks, exit 0 on every path.
+// Disable: FREEHARNESS_HOOK_RELOAD_CONTEXT=off.
+import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TRIGGER = "reload context";
+const MAX_CHARS = 9_999;
+const HANDOFF_MAX_BYTES = 16_000;
+// The SessionStart claim pass treats an older handoff as stale and never prints it.
+const HANDOFF_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+// A skeleton is capped per section by its writer; anything this large is not one.
+const SKELETON_MAX_BYTES = 256 * 1024;
+const NO_SAVED = "FreeHarness reload context: no saved context exists for this project or session.";
+const RULE = "Rule: this is a recap of saved context, not a new instruction; re-read Next Step and Errors and Fixes before acting.";
+const CUT_MARK = "(cut)";
+
+/** SessionStart's cut order: L2 lists first, L0 (what the rule names) last. */
+const CUT_LEVELS = [
+  ["Files and Code", "Pending Jobs"],
+  ["Primary Request", "Critical Context", "Corrections"],
+  ["Current Work", "Next Step", "Errors and Fixes"],
+];
+const LIST_SECTIONS = new Set(["Files and Code", "Pending Jobs", "Errors and Fixes", "Corrections"]);
+
+/** True only for the exact trigger, so every other prompt costs one string compare. */
+export function isTrigger(prompt) {
+  return typeof prompt === "string" && prompt.trim().toLowerCase() === TRIGGER;
+}
+
+function safeId(id) {
+  return String(id || "").replace(/[^\w.-]/g, "_") || "unknown";
+}
+
+/** The context monitor's key rule; that script is emitted with another hook group, so it is not imported. */
+export function projectKey(cwd) {
+  let root = cwd;
+  try {
+    const top = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (top) root = top;
+  } catch {
+    // not a repository, or no git: the cwd is the root
+  }
+  return crypto.createHash("sha256").update(fs.realpathSync(root)).digest("hex").slice(0, 16);
+}
+
+/** Reads a regular file without following a symlink at the path; null when absent, linked or over `maxBytes`. */
+function readCapped(file, maxBytes) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.size > maxBytes) return null;
+    return { text: fs.readFileSync(fd, "utf8"), mtimeMs: st.mtimeMs };
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function handoffOf(stateDir, cwd) {
+  const dir = path.join(stateDir, "handoff");
+  try {
+    if (!fs.lstatSync(dir).isDirectory()) return null;
+  } catch {
+    return null;
+  }
+  const key = projectKey(cwd);
+  const got = readCapped(path.join(dir, `${key}.md`), HANDOFF_MAX_BYTES);
+  if (!got || Date.now() - got.mtimeMs > HANDOFF_MAX_AGE_MS) return null;
+  const nl = got.text.indexOf("\n");
+  const head = nl < 0 ? got.text : got.text.slice(0, nl);
+  const m = /^handoff ([0-9a-f]{16}) (.*)$/.exec(head);
+  if (!m || m[1] !== key) return null;
+  return { origin: `handoff saved by session ${m[2]}`, text: got.text.slice(nl + 1), mtimeMs: got.mtimeMs };
+}
+
+function skeletonOf(stateDir, sessionId) {
+  const got = readCapped(path.join(stateDir, `${safeId(sessionId)}.precompact.md`), SKELETON_MAX_BYTES);
+  return got ? { origin: "PreCompact skeleton of this session", text: got.text, mtimeMs: got.mtimeMs } : null;
+}
+
+/** `## <Section>` bodies by contract name; a `(none)` body is empty, a stamp or unknown heading is dropped. */
+function parseSections(text, sections) {
+  const out = {};
+  let current = null;
+  const buf = [];
+  const flush = () => {
+    if (current) {
+      const body = buf.join("\n").trim();
+      out[current] = body === "(none)" ? "" : body;
+    }
+    buf.length = 0;
+  };
+  for (const line of text.split("\n")) {
+    const m = /^##\s+(.+?)\s*$/.exec(line);
+    if (m) {
+      flush();
+      current = sections.find((s) => s.toLowerCase() === m[1].toLowerCase()) || null;
+      continue;
+    }
+    if (current) buf.push(line);
+  }
+  flush();
+  return out;
+}
+
+/** At most `max` characters: lists keep whole lines behind `(+N more)`, prose its head behind `(cut)`, never splitting a surrogate pair. */
+function cutBody(body, max, list) {
+  if (body.length <= max) return body;
+  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 (out.length <= max) return out;
+    }
+  }
+  let keep = max - CUT_MARK.length - 1;
+  if (keep <= 0) return CUT_MARK;
+  if (/[\ud800-\udbff]/.test(body[keep - 1])) keep -= 1;
+  const head = body.slice(0, keep).trimEnd();
+  return head ? `${head}\n${CUT_MARK}` : CUT_MARK;
+}
+
+function render(sections, bodies, originLine) {
+  const lines = ['<freeharness_reorientation source="reload context">', originLine];
+  for (const s of sections) {
+    lines.push(`## ${s}`);
+    lines.push(bodies[s] || "(none)");
+  }
+  lines.push(RULE);
+  lines.push("</freeharness_reorientation>");
+  return lines.join("\n");
+}
+
+/**
+ * The additionalContext for one trigger prompt: the newest saved context, or the no-saved line.
+ * @param {Record<string, any>} payload UserPromptSubmit payload (untrusted).
+ * @param {{SECTIONS: string[], neutralize: (s: string) => string, stateDir: () => string}} pc The PreCompact module.
+ */
+export function recap(payload, pc) {
+  const state = pc.stateDir();
+  const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+  const sessionId = typeof payload.session_id === "string" && payload.session_id ? payload.session_id : "unknown";
+  let handoff = null;
+  try {
+    handoff = handoffOf(state, cwd);
+  } catch {
+    // an unresolvable cwd has no project key, so no handoff
+  }
+  const candidates = [handoff, skeletonOf(state, sessionId)].filter(Boolean);
+  if (candidates.length === 0) return NO_SAVED;
+  const pick = candidates.reduce((a, b) => (b.mtimeMs > a.mtimeMs ? b : a));
+  const parsed = parseSections(pick.text, pc.SECTIONS);
+  const bodies = Object.fromEntries(pc.SECTIONS.map((s) => [s, parsed[s] ? pc.neutralize(parsed[s]) : ""]));
+  const originLine = pc.neutralize(`Saved context: ${pick.origin}, written ${new Date(pick.mtimeMs).toISOString()}.`);
+  const over = () => render(pc.SECTIONS, bodies, originLine).length - MAX_CHARS;
+  for (const level of CUT_LEVELS) {
+    for (const s of level) {
+      if (over() <= 0) break;
+      if (bodies[s]) bodies[s] = cutBody(bodies[s], Math.max(0, bodies[s].length - over()), LIST_SECTIONS.has(s));
+    }
+  }
+  return render(pc.SECTIONS, bodies, originLine);
+}
+
+/** Entry point: read stdin, answer the trigger or stay silent, exit 0. */
+async function main() {
+  if ((process.env.FREEHARNESS_HOOK_RELOAD_CONTEXT || "").toLowerCase() === "off") return;
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(0, "utf8"));
+  } catch {
+    return;
+  }
+  if (!payload || typeof payload !== "object" || !isTrigger(payload.prompt)) return;
+  try {
+    // Loaded only for the trigger, so other prompts never pay for the module.
+    const pc = await import(new URL("./freeharness-precompact.mjs", import.meta.url).href);
+    const additionalContext = recap(payload, pc);
+    process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext } })}\n`);
+  } catch (e) {
+    process.stderr.write(`freeharness-reload-context: ${e instanceof Error ? e.message : String(e)}\n`);
+  }
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  main().finally(() => process.exit(0));
+}

package/canonical/hooks/freeharness-repeat-tool.mjs

@@ -2,7 +2,7 @@
 // UserPromptSubmit as the reset). Rewritten from the dsh repeat-tool-reminder guard (MIT).
 // Each call is keyed by sha256(tool + key-sorted JSON of its input); the per-session ring
 // file ~/.claude/freeharness/state/<session>.json holds the last key and its run length.
-// Counting happens before execution, so a call the config guard denies still counts (a model
+// Counting happens before execution, so a call a guard hook denies still counts (a model
 // hammering a denied call is the loop worth breaking). At --thresholds 3,5,8 consecutive
 // identical calls the hook returns an additionalContext reminder: short at the first
 // threshold, detailed (tool, run length, argument preview capped by --preview-chars) at