freeharness 0.4.1 → 0.4.3

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

@@ -1,9 +1,10 @@
-// FreeHarness context monitor (Claude Code Stop hook).
-// Reads the latest cost snapshot of the session (usage.jsonl, written by the cost tracker) and,
-// when the context crosses 60% and then 85% of its token window, prints one advisory line as a
-// `systemMessage` (shown to the user, never to the model: a Stop `additionalContext` would force
-// another turn). Re-arm and window fallback: see `crossed` and `respond` below.
-// Never blocks; exit 0 on every path. Disable: FREEHARNESS_HOOK_CONTEXT_MONITOR=off.
+// FreeHarness context monitor (Claude Code Stop hook). When the session's latest cost snapshot
+// crosses 60% and then 85% of its token window, it prints one advisory `systemMessage` (a Stop
+// `additionalContext` would force another turn). A hook cannot run /clear, so at the highest
+// threshold it first saves a handoff the project's next session claims. Never blocks; exit 0
+// on every path. Disable: FREEHARNESS_HOOK_CONTEXT_MONITOR=off.
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -12,11 +13,7 @@ import { fileURLToPath } from "node:url";
 /** Defaults; the fragment overrides them with --budget / --thresholds. */
 export const DEFAULTS = Object.freeze({ budget: 200_000, thresholds: [60, 85] });
 
-/**
- * Parses --budget and --thresholds (percentages, ascending).
- * @param {string[]} argv Arguments after the script path.
- * @returns {{budget:number, thresholds:number[]}} Options.
- */
+/** --budget and --thresholds (percentages, sorted ascending). */
 export function parseOptions(argv) {
   const opts = { budget: DEFAULTS.budget, thresholds: [...DEFAULTS.thresholds] };
   for (let i = 0; i < argv.length; i++) {
@@ -34,22 +31,15 @@ export function parseOptions(argv) {
   return opts;
 }
 
-/**
- * Resolves the state file of a session.
- * @param {string} sessionId Session id.
- * @returns {string} Absolute path.
- */
 function stateFile(sessionId) {
-  const dir = process.env.FREEHARNESS_STATE_DIR || path.join(os.homedir(), ".claude", "freeharness", "state");
-  return path.join(dir, `${sessionId.replace(/[^\w.-]/g, "_") || "unknown"}.context.json`);
+  return path.join(stateDir(), `${sessionId.replace(/[^\w.-]/g, "_") || "unknown"}.context.json`);
 }
 
-/**
- * Latest context size and token window recorded for the session in the cost log.
- * @param {string} sessionId Session id.
- * @returns {{tokens: number, window: number} | null} Tokens and window (default 200,000 when the
- *   snapshot lacks `context_window`), or null when no snapshot carries `context_tokens`.
- */
+function stateDir() {
+  return process.env.FREEHARNESS_STATE_DIR || path.join(os.homedir(), ".claude", "freeharness", "state");
+}
+
+/** Latest `{tokens, window}` of the session in the cost log (window 200,000 when unrecorded), or null. */
 export function contextFromSnapshot(sessionId) {
   const file = process.env.FREEHARNESS_COST_LOG || path.join(os.homedir(), ".claude", "freeharness", "cost", "usage.jsonl");
   let text;
@@ -74,11 +64,7 @@ export function contextFromSnapshot(sessionId) {
   return best;
 }
 
-/**
- * Context size from the transcript: the last assistant message's input + cache tokens.
- * @param {string} transcript Transcript path.
- * @returns {number | null} Tokens, or null when unreadable.
- */
+/** Input plus cache tokens of the transcript's last usage record, or null. */
 export function contextFromTranscript(transcript) {
   let text;
   try {
@@ -101,15 +87,8 @@ export function contextFromTranscript(transcript) {
 }
 
 /**
- * Decides which threshold (if any) to announce against the given window, records it, and
- * re-arms (clears the announced set, bumps the epoch) once the context drops back below the
- * lowest threshold, so a later climb announces both thresholds again.
- * @param {number} tokens Current context tokens.
- * @param {number} window Token window the percentage is computed against.
- * @param {{budget:number, thresholds:number[]}} opts Options (thresholds only; budget is the
- *   caller's fallback window, not used here).
- * @param {string} file State file.
- * @returns {number | null} The percentage to announce, or null.
+ * The threshold to announce, or null; each is announced once per epoch. A drop below the lowest
+ * threshold re-arms (clears the set, bumps the epoch) so a later climb announces again.
  */
 export function crossed(tokens, window, opts, file) {
   let state = { announced: [], epoch: 0 };
@@ -136,21 +115,69 @@ export function crossed(tokens, window, opts, file) {
   }
   if (changed) {
     state.updated = new Date().toISOString();
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(state), "utf8");
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(state), "utf8");
+    } catch {
+      // An unwritable state dir still gets the advisory; it repeats until the state persists.
+    }
   }
   return top;
 }
 
+const HANDOFF_MAX_BYTES = 16_000;
+
+/** SessionStart derives the same key to claim the handoff: SHA-256 of the real git toplevel, else of the cwd. */
+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);
+}
+
+/** The rename makes the write atomic and replaces an older unclaimed handoff; resolves to the path, or null. */
+export async function writeHandoff(payload) {
+  if (typeof payload.transcript_path !== "string" || !payload.transcript_path) return null;
+  // Imported lazily: the PreCompact script is emitted with another hook group and may be absent.
+  const pc = await import(new URL("./freeharness-precompact.mjs", import.meta.url).href);
+  const facts = pc.parseTranscript(payload.transcript_path);
+  if (!facts) return null;
+  const cwd = typeof payload.cwd === "string" && path.isAbsolute(payload.cwd) ? payload.cwd : process.cwd();
+  const key = projectKey(cwd);
+  const session = String(typeof payload.session_id === "string" ? payload.session_id : "").replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 64) || "unknown";
+  const head = `handoff ${key} ${session}\n`;
+  const body = pc.skeletonFromFacts(facts, payload, { mapBody: pc.neutralize, maxBytes: HANDOFF_MAX_BYTES - Buffer.byteLength(head) });
+  const dir = path.join(stateDir(), "handoff");
+  const file = path.join(dir, `${key}.md`);
+  const tmp = path.join(dir, `.${key}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`);
+  let written = null;
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // A symlinked handoff dir would put the file wherever the link points.
+    if (fs.lstatSync(dir).isDirectory()) {
+      fs.writeFileSync(tmp, head + body, { encoding: "utf8", mode: 0o600, flag: "wx" });
+      fs.renameSync(tmp, file);
+      written = file;
+    }
+  } catch {
+    fs.rmSync(tmp, { force: true });
+  } finally {
+    // The engine summary does not depend on the local file, so it is asked for either way.
+    const lastAssistant = facts.assistants.length ? facts.assistants[facts.assistants.length - 1] : "";
+    await pc.requestSummary(typeof payload.session_id === "string" && payload.session_id ? payload.session_id : "unknown", lastAssistant);
+  }
+  return written;
+}
+
 /**
- * Builds the advisory for one Stop payload, or null when nothing is due. The window is the
- * snapshot's own `context_window`; the transcript fallback carries no window of its own, so
- * --budget stands in for it there.
- * @param {Record<string, any>} payload Parsed hook payload.
- * @param {{budget:number, thresholds:number[]}} opts Options.
- * @returns {Record<string, unknown> | null} JSON to print, or null.
+ * The advisory JSON for one Stop payload, or null. The transcript fallback carries no window of
+ * its own, so --budget stands in for it. A failed handoff leaves the plain advisory.
  */
-export function respond(payload, opts) {
+export async function respond(payload, opts) {
   const sessionId = typeof payload.session_id === "string" && payload.session_id ? payload.session_id : "unknown";
   const snap = contextFromSnapshot(sessionId);
   let tokens = null;
@@ -168,13 +195,21 @@ export function respond(payload, opts) {
   const usedPct = Math.round((tokens / window) * 100);
   const tokensK = Math.round(tokens / 1000);
   const windowK = Math.round(window / 1000);
-  return {
-    systemMessage: `context ${tokensK}k of ${windowK}k (${usedPct}%): compact with the project instructions, or /clear before unrelated work`,
-  };
+  const usage = `context ${tokensK}k of ${windowK}k (${usedPct}%)`;
+  if (threshold === opts.thresholds[opts.thresholds.length - 1]) {
+    let handoff = null;
+    try {
+      handoff = await writeHandoff(payload);
+    } catch {
+      // a failed handoff leaves the plain advisory
+    }
+    if (handoff) return { systemMessage: `${usage}: handoff saved to ${handoff}; /clear now and the next session in this project picks it up` };
+  }
+  return { systemMessage: `${usage}: compact with the project instructions, or /clear before unrelated work` };
 }
 
 /** Entry point: read stdin, respond or stay silent, exit 0. */
-function main() {
+async function main() {
   if ((process.env.FREEHARNESS_HOOK_CONTEXT_MONITOR || "").toLowerCase() === "off") return;
   let payload = {};
   try {
@@ -185,7 +220,7 @@ function main() {
   }
   if (!payload || typeof payload !== "object") return;
   try {
-    const out = respond(payload, parseOptions(process.argv.slice(2)));
+    const out = await respond(payload, parseOptions(process.argv.slice(2)));
     if (out) process.stdout.write(JSON.stringify(out));
   } catch (e) {
     process.stderr.write(`freeharness-context-monitor: ${e instanceof Error ? e.message : String(e)}\n`);
@@ -193,6 +228,5 @@ function main() {
 }
 
 if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
-  main();
-  process.exit(0);
+  main().finally(() => process.exit(0));
 }

package/canonical/hooks/freeharness-converge.mjs

@@ -7,7 +7,8 @@
 // is below max_rounds it answers {"decision":"block","reason":"<next task + its Verify
 // line>"} (the Claude Code Stop contract: `block` keeps the agent working, `reason` is what
 // it reads next). When every task is checked, the limit is reached, or the loop is disabled,
-// the session ends normally. Each round is appended to .freeharness/converge.log. A tasks.md
+// the session ends normally. Each round is appended to .freeharness/converge.log (task text
+// JSON-encoded); a linked or special .freeharness, config or log turns the loop off. A tasks.md
 // that cannot be read as a task list (missing, empty, or no checkbox lines) disables the loop
 // for good: converge.json is rewritten with "disabled": true and the reason, so a broken
 // plan never traps a session. The promise text is echoed in the block reason so the agent
@@ -21,13 +22,12 @@ import { fileURLToPath } from "node:url";
 /** Defaults applied to a converge.json that omits them. */
 export const DEFAULTS = Object.freeze({ maxRounds: 5, promise: "every task in tasks.md is checked and its Verify line passed" });
 
-const TASK_LINE = /^\s*[-*]\s*\[([\sxX])\]\s*(.*)/;
-// The trailing `\s*` of the annotation patterns absorbs the `\r` of a CRLF file, which `.`
-// never matches; without it every annotation line of such a file reads as prose.
-const VERIFY_LINE = /^\s*Verify:\s*(.*?)\s*$/;
-const DISPOSITION_LINE = /^\s*Disposition:\s*(superseded|moved|external)\b\s*(.*?)\s*$/;
+const TASK_LINE = /^\s*(?:[-*+]|\d{1,9}[.)])\s*\[(?:\s*([^\]\s])\s*\](?![([])|\](?![([])|\s+\])\s*(.*)/;
+// Values run to end of line and are trimmed in code; a group before `\s*$` is quadratic.
+const VERIFY_LINE = /^\s*Verify:(.*)$/s;
+const DISPOSITION_LINE = /^\s*Disposition:\s*(superseded|moved|external)\b(.*)$/s;
 /** The annotation lines a task may carry; any other line ends its block. */
-const ANNOTATION_LINE = /^\s*(?:Verify|Interfaces|Boundary|Depends|Disposition):\s*(.*)\s*$/;
+const ANNOTATION_LINE = /^\s*(?:Verify|Interfaces|Boundary|Depends|Disposition):/;
 
 /**
  * Resolves the project root of a Stop payload.
@@ -47,11 +47,16 @@ export function projectDir(payload) {
 export function readConfig(project) {
   const file = path.join(project, ".freeharness", "converge.json");
   if (!fs.existsSync(file)) return { file, config: null };
+  if (!contained(project)) return { file, config: null };
+  const fd = openRegular(file, fs.constants.O_RDONLY);
+  if (fd === null) return { file, config: null };
   let parsed;
   try {
-    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    parsed = JSON.parse(fs.readFileSync(fd, "utf8"));
   } catch (e) {
     return { file, config: null, error: `converge.json is not valid JSON (${e instanceof Error ? e.message : String(e)}); loop off` };
+  } finally {
+    fs.closeSync(fd);
   }
   if (!parsed || typeof parsed !== "object" || typeof parsed.change !== "string" || !/^[A-Za-z0-9._-]+$/.test(parsed.change)) {
     return { file, config: null, error: "converge.json needs a \"change\" id (letters, digits, . _ -); loop off" };
@@ -79,7 +84,7 @@ export function parseTasks(content) {
   for (const line of content.split("\n")) {
     const t = line.match(TASK_LINE);
     if (t) {
-      current = { done: t[1].toLowerCase() === "x", text: t[2].trim(), verify: null, disposition: null };
+      current = { done: (t[1] ?? "").toLowerCase() === "x", text: t[2].trim(), verify: null, disposition: null };
       tasks.push(current);
       continue;
     }
@@ -110,15 +115,56 @@ export function parseTasks(content) {
   return tasks;
 }
 
+const NO_FOLLOW = (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+
+/** True when `file` is absent or a single-link regular file (never a symlink). */
+function plainOrAbsent(file) {
+  try {
+    const st = fs.lstatSync(file);
+    return st.isFile() && st.nlink === 1;
+  } catch (e) {
+    return e?.code === "ENOENT";
+  }
+}
+
+/** True when .freeharness is a real directory holding a plain config and log: a cloned repo can link either to a shell rc file. */
+function contained(project) {
+  const dir = path.join(project, ".freeharness");
+  try {
+    if (!fs.lstatSync(dir).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return plainOrAbsent(path.join(dir, "converge.json")) && plainOrAbsent(path.join(dir, "converge.log"));
+}
+
+/** Descriptor of `file` unless it is a symlink, special or hard-linked; checked on the fd, so a swap after `contained` fails too. */
+function openRegular(file, flags) {
+  let fd;
+  try {
+    fd = fs.openSync(file, flags | NO_FOLLOW, 0o644);
+    const st = fs.fstatSync(fd);
+    if (st.isFile() && st.nlink === 1) return fd;
+  } catch {
+    // refused below
+  }
+  if (fd !== undefined) fs.closeSync(fd);
+  return null;
+}
+
 /**
  * Appends one line to the round log.
  * @param {string} project Project dir.
  * @param {string} line Text.
  */
 function log(project, line) {
-  const file = path.join(project, ".freeharness", "converge.log");
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.appendFileSync(file, `${new Date().toISOString()} ${line}\n`, "utf8");
+  const fd = openRegular(path.join(project, ".freeharness", "converge.log"), fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT);
+  if (fd === null) return;
+  try {
+    fs.writeSync(fd, `${new Date().toISOString()} ${line}\n`);
+  } finally {
+    fs.closeSync(fd);
+  }
 }
 
 /**
@@ -127,13 +173,20 @@ function log(project, line) {
  * @param {Record<string, unknown>} patch Fields to merge over the current file.
  */
 function writeConfig(file, patch) {
-  let current = {};
+  const fd = openRegular(file, fs.constants.O_RDWR);
+  if (fd === null) return;
   try {
-    current = JSON.parse(fs.readFileSync(file, "utf8"));
-  } catch {
-    // unreadable: the patch alone is written (the reader already validated the shape)
+    let current = {};
+    try {
+      current = JSON.parse(fs.readFileSync(fd, "utf8"));
+    } catch {
+      // unreadable: the patch alone is written (the reader already validated the shape)
+    }
+    fs.ftruncateSync(fd, 0);
+    fs.writeSync(fd, `${JSON.stringify({ ...current, ...patch }, null, 2)}\n`, 0);
+  } finally {
+    fs.closeSync(fd);
   }
-  fs.writeFileSync(file, `${JSON.stringify({ ...current, ...patch }, null, 2)}\n`, "utf8");
 }
 
 /**
@@ -157,13 +210,13 @@ export function respond(payload) {
   } catch (e) {
     const reason = `tasks.md unreadable at ${tasksFile}: ${e instanceof Error ? e.message : String(e)}`;
     writeConfig(file, { disabled: true, reason });
-    log(project, `disabled change=${config.change} reason="${reason}"`);
+    log(project, `disabled change=${config.change} reason=${JSON.stringify(reason)}`);
     return { systemMessage: `freeharness-converge: disabled (${reason}). Fix the change id or the file and remove "disabled" from .freeharness/converge.json to re-arm.` };
   }
   if (tasks.length === 0) {
     const reason = `tasks.md has no checkbox task lines (${tasksFile})`;
     writeConfig(file, { disabled: true, reason });
-    log(project, `disabled change=${config.change} reason="${reason}"`);
+    log(project, `disabled change=${config.change} reason=${JSON.stringify(reason)}`);
     return { systemMessage: `freeharness-converge: disabled (${reason}). Write the tasks as "- [ ] N.M ..." lines and remove "disabled" from .freeharness/converge.json to re-arm.` };
   }
 
@@ -181,10 +234,10 @@ export function respond(payload) {
   }
   if (config.rounds >= config.maxRounds) {
     const remaining = open.map((t) => t.text).join(" | ");
-    log(project, `limit change=${config.change} rounds=${config.rounds}/${config.maxRounds} remaining=${open.length} tasks="${remaining}"`);
+    log(project, `limit change=${config.change} rounds=${config.rounds}/${config.maxRounds} remaining=${open.length} tasks=${JSON.stringify(remaining)}`);
     if (dispositioned.length > 0) {
       const skipped = dispositioned.map((t) => `${t.text} (${t.disposition.kind})`).join(" | ");
-      log(project, `dispositioned change=${config.change} tasks="${skipped}"`);
+      log(project, `dispositioned change=${config.change} tasks=${JSON.stringify(skipped)}`);
     }
     return { systemMessage: `freeharness-converge: round limit ${config.maxRounds} reached for ${config.change} with ${open.length} task(s) open: ${remaining}. Raise max_rounds or reset rounds in .freeharness/converge.json to continue.` };
   }
@@ -192,7 +245,7 @@ export function respond(payload) {
   const next = open[0];
   const round = config.rounds + 1;
   writeConfig(file, { rounds: round });
-  log(project, `round=${round}/${config.maxRounds} change=${config.change} open=${open.length} next="${next.text}"`);
+  log(project, `round=${round}/${config.maxRounds} change=${config.change} open=${open.length} next=${JSON.stringify(next.text)}`);
   const reason = [
     `freeharness-converge round ${round}/${config.maxRounds} for change ${config.change}: ${open.length} task(s) still unchecked.`,
     `Next task: ${next.text}`,
@@ -222,6 +275,8 @@ function main() {
 }
 
 if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  // No exit(): it truncates a reason past the pipe buffer. EPIPE on either stream is ignored.
+  process.stdout.on("error", () => {});
+  process.stderr.on("error", () => {});
   main();
-  process.exit(0);
 }