freeharness 0.4.1 → 0.4.2

package/canonical/hooks/freeharness-session-start

@@ -4,8 +4,10 @@
 # the free-mem plugin's hooks.
 # Events: SessionStart. Sources: startup, clear, compact, resume, fork.
 # Output: {"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"<text>"}}:
-#   the pointer, an SDD status line and WIP advisory when applicable, the routing block from
-#   FH_ROUTING_FILE, then (compact/resume/fork) the re-orientation block; see buildContext.
+#   the fixed pointer, the routing block from FH_ROUTING_FILE, then the volatile tail: the SDD
+#   status line and WIP advisory when applicable, then (startup/clear) the project's handoff
+#   claimed once from <state>/handoff/, or (compact/resume/fork) the re-orientation block; see
+#   buildContext.
 # Disable: FREEHARNESS_HOOK_SESSION_START=off. Never blocks: exit 0 on every path.
 set -u
 if [ "$(printf '%s' "${FREEHARNESS_HOOK_SESSION_START:-}" | tr '[:upper:]' '[:lower:]')" = "off" ]; then exit 0; fi
@@ -18,16 +20,19 @@ elif [ -r "$FH_HOOK_DIR/../rules/routing.md" ]; then
 else
   FH_ROUTING_FILE=""
 fi
-export FH_ROUTING_FILE
+export FH_ROUTING_FILE FH_HOOK_DIR
 FH_PAYLOAD="$(cat 2>/dev/null || true)"
 export FH_PAYLOAD
 
 if node --input-type=module - <<'JS'
+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";
+import { pathToFileURL } from "node:url";
 
-/** The v3 pointer lines (without the closing tag; the SDD status line goes before it). */
+/** The v3 pointer lines; byte-stable across sessions, so nothing project-specific goes inside. */
 const POINTER_LINES = [
   "<freeharness>",
   "FreeHarness active. Plan non-trivial work with OpenSpec (/opsx: proposal, specs, design, tasks).",
@@ -36,7 +41,6 @@ const POINTER_LINES = [
   "Memory is the free-mem plugin. The user's CLAUDE.md/AGENTS.md always takes precedence over this pointer.",
 ];
 
-/** The v3 pointer, unchanged (no openspec/changes in the project). */
 const POINTER = [...POINTER_LINES, "</freeharness>"].join("\n");
 
 /** Complete-but-not-archived ids listed in the status line, at most. */
@@ -63,9 +67,26 @@ const ROUTING_CAP = 6000;
 /** Reserve for the `(+N rows truncated)` marker, so a truncated body still fits ROUTING_CAP. */
 const ROUTING_MARKER_RESERVE = 48;
 
-/** additionalContext length that starts the shortening cascade (stays under 10,000). */
+/** additionalContext length that starts the shortening cascade: Claude Code shows only a 2,000-character preview past 10,000. */
 const SHORTEN_AT = 9800;
 
+/** Shortening levels, cut L2 first; L0 is what the closing rule tells the model to re-read. */
+const L2_SECTIONS = ["Files and Code", "Pending Jobs"];
+const L1_SECTIONS = ["Primary Request", "Critical Context", "Corrections"];
+const L0_SECTIONS = ["Current Work", "Next Step", "Errors and Fixes"];
+
+const CUT_MARK = "(cut)";
+
+/** Sources that claim the project's handoff; compact, resume and fork continue a session that keeps its own state. */
+const CLAIM = new Set(["clear", "startup"]);
+
+/** Handoff limits from the data contract: the writer's size cap, the print window and the claimed-file lifetime. */
+const HANDOFF_MAX_BYTES = 16_000;
+const HANDOFF_FRESH_MS = 24 * 3_600_000;
+const CLAIMED_KEEP_MS = 7 * 24 * 3_600_000;
+const HANDOFF_HEAD = /^handoff [0-9a-f]{16} /;
+const CLAIMED_NAME = /^[0-9a-f]{16}\.claimed-\d+\.md$/;
+
 /** State dir (FREEHARNESS_STATE_DIR overrides). */
 function stateDir() {
   return process.env.FREEHARNESS_STATE_DIR || path.join(os.homedir(), ".claude", "freeharness", "state");
@@ -76,8 +97,11 @@ function safeId(id) {
   return String(id || "").replace(/[^\w.-]/g, "_") || "unknown";
 }
 
-/** A `-`/`*` bullet carrying a `[ ]`/`[x]` checkbox; matches the engine's task-line pattern. */
-const TASK_LINE_PATTERN = /^\s*[-*]\s*\[([\sxX])\]\s*(.*)/;
+/** A task line under any list marker (`-`/`*`/`+`/ordered); matches the engine's task-line pattern. */
+const TASK_LINE_PATTERN = /^\s*(?:[-*+]|\d{1,9}[.)])\s*\[(?:\s*([^\]\s])\s*\](?![([])|\](?![([])|\s+\])\s*(.*)/;
+
+/** Lines longer than this are skipped unmatched so a hostile tasks.md cannot stall the hook. */
+const MAX_TASK_LINE_LENGTH = 10_000;
 
 /** A per-task annotation line, never a task; the trailing `\s*` absorbs a CRLF `\r`. */
 const TASK_ANNOTATION_PATTERN = /^\s*(?:Verify|Interfaces|Boundary|Depends|Disposition):\s*(.*)\s*$/;
@@ -91,6 +115,12 @@ const DISPOSITION_KINDS = new Set(["superseded", "moved", "external"]);
 /** An unclaimed follow-up item line, matching `openspec follow-up list`'s shape. */
 const FOLLOW_UP_ITEM_PATTERN = /^\s*[-*]\s*\[ \]\s*/;
 
+/** Follow-up types in display order; a copy of FOLLOW_UP_TYPES in packages/sdd (session-start.test.ts pins the two equal). */
+const FOLLOW_UP_TYPES = ["defect", "hardening", "refactor", "test-gap", "docs", "design", "owner-step", "upstream"];
+
+/** A leading `[<type>]` tag on an item body; a tag outside FOLLOW_UP_TYPES reads as untyped. */
+const FOLLOW_UP_TYPE_TAG = /^\[([a-z-]+)\]/;
+
 /** `.freeharness/sdd.json`, relative to the project root. */
 const WIP_CAP_FILE = ".freeharness/sdd.json";
 
@@ -102,9 +132,13 @@ function parseTasksWithDisposition(content) {
   const tasks = [];
   let current = null;
   for (const line of content.split("\n")) {
+    if (line.length > MAX_TASK_LINE_LENGTH) {
+      current = null;
+      continue;
+    }
     const task = TASK_LINE_PATTERN.exec(line);
     if (task) {
-      current = { done: task[1].toLowerCase() === "x", dispositioned: false };
+      current = { done: (task[1] ?? "").toLowerCase() === "x", dispositioned: false };
       tasks.push(current);
       continue;
     }
@@ -183,9 +217,10 @@ function wipAdvisoryLines(project) {
   return lines;
 }
 
-/** Counts unclaimed follow-up items; item text is data, never read here. */
+/** Counts unclaimed follow-up items, in total and per type; beyond the type tag, item text is never read. */
 function followUpCount(project) {
   const changesDir = path.join(project, "openspec", "changes");
+  const byType = new Map();
   let total = 0;
   const countFile = (dir) => {
     let text;
@@ -195,14 +230,18 @@ function followUpCount(project) {
       return;
     }
     for (const line of text.split("\n")) {
-      if (FOLLOW_UP_ITEM_PATTERN.test(line)) total += 1;
+      if (!FOLLOW_UP_ITEM_PATTERN.test(line)) continue;
+      total += 1;
+      const tag = line.replace(FOLLOW_UP_ITEM_PATTERN, "").match(FOLLOW_UP_TYPE_TAG);
+      const type = tag && FOLLOW_UP_TYPES.includes(tag[1]) ? tag[1] : "untyped";
+      byType.set(type, (byType.get(type) ?? 0) + 1);
     }
   };
   let entries;
   try {
     entries = fs.readdirSync(changesDir, { withFileTypes: true });
   } catch {
-    return 0;
+    return { total: 0, byType };
   }
   for (const e of entries) {
     if (!e.isDirectory() || e.name.startsWith(".")) continue;
@@ -221,7 +260,7 @@ function followUpCount(project) {
     }
     countFile(path.join(changesDir, e.name));
   }
-  return total;
+  return { total, byType };
 }
 
 /** Active changes with an unchecked task; path id uses stripControl, not sanitizeTag's 64-char cap, so a long id still points at its real tasks.md (sdd-flow-2#7). */
@@ -296,14 +335,16 @@ function openspecLine(status) {
   const ids = status.complete.length > 0 ? ` (${shown.join(", ")}${status.complete.length > shown.length ? ", ..." : ""})` : "";
   const blocked = status.blocked === null ? "" : `, ${status.blocked} blocked by unresolved headers`;
   const dispositioned = status.dispositioned ? `, ${status.dispositioned} dispositioned` : "";
-  const followUps = status.followUps ? `, ${status.followUps} open follow-up(s)` : "";
+  const { total, byType } = status.followUps;
+  const perType = [...FOLLOW_UP_TYPES, "untyped"].filter((type) => byType.get(type)).map((type) => `${byType.get(type)} ${type}`);
+  const followUps = total ? `, ${total} open follow-up(s) (${perType.join(", ")})` : "";
   return `openspec: ${status.inFlight} change(s) in flight, ${status.complete.length} complete but not archived${ids}${blocked}${dispositioned}${followUps}; rule: finish or archive before opening a new change (/opsx:archive)`;
 }
 
-/** The pointer block: v3 lines, SDD status line when present, WIP advisory when the cap is exceeded. */
-function pointerFor(project) {
+/** Volatile status lines: SDD status when present, WIP advisory when the cap is exceeded. */
+function statusLines(project) {
   const line = openspecLine(openspecStatus(project));
-  return [...POINTER_LINES, ...(line ? [line] : []), ...wipAdvisoryLines(project), "</freeharness>"].join("\n");
+  return [...(line ? [line] : []), ...wipAdvisoryLines(project)];
 }
 
 /** `<N>k`, non-finite treated as 0. */
@@ -349,9 +390,9 @@ function routingBlock(file) {
   return { block: `<routing>\n${body}\n</routing>`, path: filePath };
 }
 
-/** One telemetry line: `<change> <task> <tier>: main Nk, subagents Nk, observer Nk|n/a`. */
+/** One telemetry line: `<change|session_class> <task> <tier>: main Nk, subagents Nk, observer Nk|n/a`. */
 function telemetryLine(rec) {
-  const change = sanitizeTag(rec.change) || "untagged";
+  const change = sanitizeTag(rec.change) || sanitizeTag(rec.session_class) || "untagged";
   const task = sanitizeTag(rec.task) || "-";
   const tier = sanitizeTag(rec.tier) || "-";
   const sinks = rec && typeof rec.sinks === "object" && rec.sinks ? rec.sinks : {};
@@ -459,14 +500,17 @@ function fileOps(sessionId, transcript) {
   return [...counts.entries()].map(([file, per]) => `${file} (${[...per.entries()].map(([t, n]) => `${t} x${n}`).join(", ")})`);
 }
 
-/** Parses PreCompact summary: `## <Section>` headings, body verbatim. */
+/** The PreCompact summary's sections; {} when there is none. */
 function precompactSummary(sessionId) {
-  let text;
   try {
-    text = fs.readFileSync(path.join(stateDir(), `${safeId(sessionId)}.precompact.md`), "utf8");
+    return parseSections(fs.readFileSync(path.join(stateDir(), `${safeId(sessionId)}.precompact.md`), "utf8"));
   } catch {
     return {};
   }
+}
+
+/** Splits text at the eight `## <Section>` headings, body verbatim; text before the first heading is dropped. */
+function parseSections(text) {
   const out = {};
   let current = null;
   const buf = [];
@@ -488,73 +532,267 @@ function precompactSummary(sessionId) {
   return out;
 }
 
-/** Renders the re-orientation block from pre-sliced pieces; the eight headings always print in full. */
-function renderReorientation(source, activeLine, ctxLine, telemetryLines, telemetryDropped, opsLines, opsDropped, summary) {
-  const lines = [`<freeharness_reorientation source="${source}">`, activeLine];
-  if (ctxLine) lines.push(ctxLine);
+/**
+ * The neutralizer the handoff writer uses, from the PreCompact hook beside this script, so writer
+ * and reader share one rule. `shared` is false when that file cannot load; the fallback then
+ * escapes every `<`, stricter than the shared rule and never looser.
+ */
+async function loadNeutralize() {
+  const dir = process.env.FH_HOOK_DIR || "";
+  // A program read from stdin has "-" in argv[1]; the imported hook's entry check would realpath it and throw.
+  process.argv[1] = "";
+  try {
+    if (path.isAbsolute(dir)) {
+      const mod = await import(pathToFileURL(path.join(dir, "freeharness-precompact.mjs")).href);
+      if (typeof mod.neutralize === "function") return { neutralize: mod.neutralize, shared: true };
+    }
+  } catch {
+    // falls through to the strict fallback
+  }
+  return { neutralize: (text) => String(text).replace(/</g, "<\\"), shared: false };
+}
+
+/** The tracker's project root, so the tail reads the file the tracker writes; `fallback` when that module cannot load or finds no root. */
+async function telemetryRoot(cwd, fallback) {
+  const dir = process.env.FH_HOOK_DIR || "";
+  process.argv[1] = "";
+  try {
+    if (path.isAbsolute(dir)) {
+      const mod = await import(pathToFileURL(path.join(dir, "freeharness-cost-tracker.mjs")).href);
+      const root = typeof mod.projectRootFor === "function" ? mod.projectRootFor(cwd) : null;
+      if (typeof root === "string" && root) return root;
+    }
+  } catch {
+    // falls through to the fallback
+  }
+  return fallback;
+}
+
+/** The context monitor's project key: SHA-256 of the real git toplevel, else of the cwd, cut to 16 hex. */
+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);
+}
+
+/** A handoff's text and mtime when the path is a regular file within the size cap that starts with the handoff line; null otherwise. */
+function readHandoff(file) {
+  let fd;
+  try {
+    if (!fs.lstatSync(file).isFile()) return null;
+    // The lstat above and O_NOFOLLOW both refuse a link; O_NONBLOCK keeps a swapped-in FIFO from hanging the hook.
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.size > HANDOFF_MAX_BYTES) return null;
+    const buf = Buffer.alloc(st.size);
+    let n = 0;
+    for (let r; n < st.size && (r = fs.readSync(fd, buf, n, st.size - n, n)) > 0; ) n += r;
+    const text = buf.subarray(0, n).toString("utf8");
+    return HANDOFF_HEAD.test(text) ? { text, mtimeMs: st.mtimeMs } : null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+/** Removes claimed files past their lifetime; only names of the claimed shape are ever touched. */
+function sweepClaimed(dir, now) {
+  for (const name of fs.readdirSync(dir)) {
+    if (!CLAIMED_NAME.test(name)) continue;
+    try {
+      const st = fs.lstatSync(path.join(dir, name));
+      if (st.isFile() && now - st.mtimeMs > CLAIMED_KEEP_MS) fs.unlinkSync(path.join(dir, name));
+    } catch {
+      // gone already, or not ours to remove
+    }
+  }
+}
+
+/**
+ * Claims the project's live handoff by rename and returns its text when under a day old. The
+ * rename is the lock: a session whose rename fails lost the race and prints nothing, and a file
+ * outside the contract is left in place.
+ */
+function claimHandoff(dir, cwd) {
+  const now = Date.now();
+  sweepClaimed(dir, now);
+  const key = projectKey(cwd);
+  const live = path.join(dir, `${key}.md`);
+  if (!readHandoff(live)) return null;
+  const claimed = path.join(dir, `${key}.claimed-${now}.md`);
+  fs.renameSync(live, claimed);
+  // Read again after the rename: a newer handoff may have replaced the one checked above.
+  const got = readHandoff(claimed);
+  return got && now - got.mtimeMs <= HANDOFF_FRESH_MS ? got.text : null;
+}
+
+/** The claimed handoff's sections, neutralized; null when there is nothing to print or any step fails. */
+async function claimedHandoff(payload) {
+  try {
+    const dir = path.join(stateDir(), "handoff");
+    // A symlinked handoff dir would claim and delete wherever the link points.
+    if (!fs.lstatSync(dir).isDirectory()) return null;
+    const { neutralize, shared } = await loadNeutralize();
+    if (!shared) return null;
+    const cwd = typeof payload.cwd === "string" && path.isAbsolute(payload.cwd) ? payload.cwd : process.cwd();
+    const text = claimHandoff(dir, cwd);
+    if (text === null) return null;
+    const sections = parseSections(text.slice(text.indexOf("\n") + 1));
+    return Object.fromEntries(SECTIONS.map((s) => [s, sections[s] && sections[s] !== "(none)" ? neutralize(sections[s]) : ""]));
+  } catch {
+    return null;
+  }
+}
+
+/** The first `kept` of `lines`, then `(+N more)` for the rest. */
+function keepLines(lines, kept) {
+  return kept >= lines.length ? lines.join("\n") : [...lines.slice(0, kept), `(+${lines.length - kept} more)`].join("\n");
+}
+
+/** Cuts a body to at most `max` characters ending in a `(cut)` line, never splitting a surrogate pair. */
+function cutBody(body, max) {
+  if (body.length <= max) return body;
+  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;
+}
+
+/** Largest count in [0, total] that `fits`; a binary search is sound because each dropped line outweighs the marker's growth. */
+function largestFitting(total, fits) {
+  if (fits(total)) return total;
+  if (!fits(0)) return 0;
+  let lo = 0;
+  let hi = total;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if (fits(mid)) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/** Renders the re-orientation block from the shortened view; the eight headings always print. */
+function renderReorientation(view) {
+  const lines = [`<freeharness_reorientation source="${view.source}">`, view.activeLine];
+  if (view.ctxLine) lines.push(view.ctxLine);
   lines.push("Telemetry (.freeharness/telemetry.jsonl, last 3):");
-  if (telemetryLines.length > 0) lines.push(...telemetryLines.map((l) => `  ${l}`));
+  const telemetryDropped = view.telemetry.length - view.telemetryKept;
+  if (view.telemetryKept > 0) lines.push(...view.telemetry.slice(0, view.telemetryKept).map((l) => `  ${l}`));
   else if (telemetryDropped === 0) lines.push("  (none)");
   if (telemetryDropped > 0) lines.push(`  (+${telemetryDropped} more)`);
   lines.push("Session file operations:");
-  if (opsLines === null) {
+  if (view.ops === null) {
     lines.push("  (unavailable)");
   } else {
-    if (opsLines.length > 0) lines.push(...opsLines.map((l) => `  - ${l}`));
+    const opsDropped = view.ops.length - view.opsKept;
+    if (view.opsKept > 0) lines.push(...view.ops.slice(0, view.opsKept).map((l) => `  - ${l}`));
     else if (opsDropped === 0) lines.push("  (none)");
     if (opsDropped > 0) lines.push(`  - (+${opsDropped} more)`);
   }
   for (const s of SECTIONS) {
     lines.push(`## ${s}`);
-    lines.push(summary[s] ? summary[s] : "(none)");
+    lines.push(view.bodies[s] || "(none)");
   }
   lines.push(RULE);
   lines.push("</freeharness_reorientation>");
   return lines.join("\n");
 }
 
-/** Builds additionalContext: pointer, routing, re-orientation for compact/resume/fork. Past SHORTEN_AT, drops file-ops then telemetry then collapses routing to a path line; the skeleton is never shortened. */
-function buildContext(payload) {
+/** Renders a claimed handoff; the eight headings always print. */
+function renderHandoff(bodies) {
+  const lines = ["<freeharness_handoff>"];
+  for (const s of SECTIONS) lines.push(`## ${s}`, bodies[s] || "(none)");
+  lines.push("</freeharness_handoff>");
+  return lines.join("\n");
+}
+
+/** The single assembly point: the stable prefix, then the volatile tail in its fixed order (status lines, a claimed handoff once one exists, the re-orientation). */
+function assembleContext(routingText, volatile) {
+  return [POINTER, routingText, ...volatile.filter(Boolean)].join("\n");
+}
+
+/** Shortens `bodies` in place until `assemble()` fits: L2 by whole lines, then the routing collapse and L1, then L0 by equal share. */
+function fitSections(bodies, assemble, collapseRouting) {
+  const over = () => assemble().length - SHORTEN_AT;
+  const fits = () => over() <= 0;
+  for (const s of L2_SECTIONS) {
+    const lines = bodies[s] ? bodies[s].split("\n") : [];
+    bodies[s] = keepLines(lines, largestFitting(lines.length, (k) => ((bodies[s] = keepLines(lines, k)), fits())));
+  }
+
+  if (!fits()) collapseRouting();
+  for (const s of L1_SECTIONS) {
+    if (fits()) break;
+    if (bodies[s]) bodies[s] = cutBody(bodies[s], bodies[s].length - over());
+  }
+
+  if (!fits()) {
+    // Water-filling: a section under its share keeps all of it, and what it leaves goes to the longer ones.
+    const cut = L0_SECTIONS.filter((s) => bodies[s]).sort((a, b) => bodies[a].length - bodies[b].length);
+    let room = SHORTEN_AT - (assemble().length - cut.reduce((n, s) => n + bodies[s].length, 0));
+    cut.forEach((s, i) => {
+      bodies[s] = cutBody(bodies[s], Math.floor(room / (cut.length - i)));
+      room -= bodies[s].length;
+    });
+  }
+}
+
+/** Builds additionalContext; past SHORTEN_AT the tail shortens by level (see fitSections), never a heading or a pointer line. */
+async function buildContext(payload) {
   const source = typeof payload.source === "string" ? payload.source : "startup";
   const project = process.env.CLAUDE_PROJECT_DIR || (typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd());
-  const pointer = pointerFor(project);
+  const status = statusLines(project).join("\n");
   const routing = routingBlock(process.env.FH_ROUTING_FILE || "");
   let routingText = routing.block !== null ? routing.block : "Routing table unavailable: run freeharness update --scope user.";
-  if (!REORIENT.has(source)) return `${pointer}\n${routingText}`;
+  const collapseRouting = () => {
+    if (routing.block !== null && routing.path) routingText = `Routing table: ${routing.path} (Read it before routing).`;
+  };
+  if (!REORIENT.has(source)) {
+    const handoff = CLAIM.has(source) ? await claimedHandoff(payload) : null;
+    if (!handoff) return assembleContext(routingText, [status]);
+    const assemble = () => assembleContext(routingText, [status, renderHandoff(handoff)]);
+    fitSections(handoff, assemble, collapseRouting);
+    return assemble();
+  }
 
+  const { neutralize } = await loadNeutralize();
   const sessionId = typeof payload.session_id === "string" ? payload.session_id : "";
   const transcript = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
   const changes = activeChanges(project);
-  const activeLine = `Active change: ${changes.length > 0 ? changes.join("; ") : "(none)"}`;
-  const ctxLine = contextLine(sessionId);
   const summary = precompactSummary(sessionId);
-  let telemetryLines = telemetryTail(project, 3);
-  let telemetryDropped = 0;
-  let opsLines = fileOps(sessionId, transcript);
-  let opsDropped = 0;
+  const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+  const telemetry = telemetryTail(await telemetryRoot(cwd, project), 3);
+  const ops = fileOps(sessionId, transcript);
+  const view = {
+    source,
+    activeLine: `Active change: ${changes.length > 0 ? changes.join("; ") : "(none)"}`,
+    ctxLine: contextLine(sessionId),
+    telemetry,
+    telemetryKept: telemetry.length,
+    ops: ops === null ? null : ops.map(neutralize),
+    opsKept: ops === null ? 0 : ops.length,
+    bodies: Object.fromEntries(SECTIONS.map((s) => [s, summary[s] ? neutralize(summary[s]) : ""])),
+  };
 
-  const assemble = () => `${pointer}\n${routingText}\n${renderReorientation(source, activeLine, ctxLine, telemetryLines, telemetryDropped, opsLines, opsDropped, summary)}`;
+  const assemble = () => assembleContext(routingText, [status, renderReorientation(view)]);
+  const fits = () => assemble().length <= SHORTEN_AT;
 
-  if (assemble().length > SHORTEN_AT && Array.isArray(opsLines)) {
-    while (opsLines.length > 0 && assemble().length > SHORTEN_AT) {
-      opsLines = opsLines.slice(0, -1);
-      opsDropped += 1;
-    }
-  }
-  if (assemble().length > SHORTEN_AT) {
-    while (telemetryLines.length > 0 && assemble().length > SHORTEN_AT) {
-      telemetryLines = telemetryLines.slice(0, -1);
-      telemetryDropped += 1;
-    }
-  }
-  if (assemble().length > SHORTEN_AT && routing.block !== null && routing.path) {
-    routingText = `Routing table: ${routing.path} (Read it before routing).`;
-  }
+  view.telemetryKept = largestFitting(telemetry.length, (k) => ((view.telemetryKept = k), fits()));
+  if (view.ops !== null) view.opsKept = largestFitting(view.ops.length, (k) => ((view.opsKept = k), fits()));
+  fitSections(view.bodies, assemble, collapseRouting);
   return assemble();
 }
 
 /** Entry point: always print the pointer (at least). */
-function main() {
+async function main() {
   if ((process.env.FREEHARNESS_HOOK_SESSION_START || "").toLowerCase() === "off") return;
   let payload = {};
   try {
@@ -566,14 +804,14 @@ function main() {
   if (!payload || typeof payload !== "object") payload = {};
   let context = POINTER;
   try {
-    context = buildContext(payload);
+    context = await buildContext(payload);
   } catch (e) {
     process.stderr.write(`freeharness-session-start: ${e instanceof Error ? e.message : String(e)}\n`);
   }
   process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } }));
 }
 
-main();
+await main();
 JS
 then exit 0; fi
 

package/canonical/hooks/hooks.claude-code.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "FreeHarness SessionStart hook fragment for Claude Code (rules capability). The installer merges this into <project>/.claude/settings.json additively (never removing existing entries, e.g. the upstream claude-mem plugin at user level is untouched). startup|clear: the short pointer. compact|resume|fork: the pointer plus the re-orientation block (active change id, dogfood tail, session file operations, the eight-section checkpoint pre-filled from ~/.claude/freeharness/state/<session>.precompact.md, the re-read rule). Disable: FREEHARNESS_HOOK_SESSION_START=off or remove this entry.",
+  "$comment": "FreeHarness SessionStart hook fragment for Claude Code (rules capability). The installer merges this into <project>/.claude/settings.json additively (never removing existing entries, e.g. the upstream claude-mem plugin at user level is untouched). The output puts the stable part first (the pointer, the routing block) and the volatile part last, under 10,000 characters, shortened in levels. startup|clear: the short pointer, then the project's saved handoff, claimed once by renaming it (a second session finds nothing; a handoff over 24 hours old is renamed unprinted). compact|resume|fork: the pointer plus the re-orientation block (active change id, dogfood tail, session file operations, the eight-section checkpoint pre-filled from ~/.claude/freeharness/state/<session>.precompact.md, the re-read rule). Disable: FREEHARNESS_HOOK_SESSION_START=off or remove this entry.",
   "hooks": {
     "SessionStart": [
       {

package/canonical/hooks/hooks.config-guard.claude-code.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "FreeHarness config guard for Claude Code (rules capability). Merged additively into settings.json. PreToolUse on Edit|Write|MultiEdit|Bash: denies writes to settings.json, settings.local.json, .mcp.json, CLAUDE.md, hook scripts and the plugin hooks.json unless <project>/.freeharness/allow-config-edit (or ~/.claude/freeharness/allow-config-edit) exists and is younger than --ttl minutes (30; a numeric epoch-ms or ISO body sets an explicit expiry). Bash is denied only when the command writes to such a path (redirect, sed -i, rm, mv, cp, tee, truncate, touch); reads pass. The deny reason names the marker and the `touch` one-liner for the user. `freeharness init`/`update` set and remove their own marker. Disable: FREEHARNESS_HOOK_CONFIG_GUARD=off or remove this entry.",
+  "$comment": "FreeHarness config guard for Claude Code (rules capability). Merged additively into settings.json. PreToolUse on Edit|Write|MultiEdit|Bash: denies writes to live harness configuration, which runs code or loads instructions in every session, unless <project>/.freeharness/allow-config-edit (or ~/.claude/freeharness/allow-config-edit) exists and is younger than --ttl minutes (240 minutes; a numeric epoch-ms or ISO body sets an explicit expiry). The live set is judged by location at the written and the real path: settings.json and settings.local.json inside a .claude dir, any .mcp.json, ~/.claude.json, ~/.claude/CLAUDE.md, everything under ~/.claude/plugins and under the hooks dir of a .claude, .freeharness, ~/.claude/freeharness or freeharness-plugin dir, a plugin's hooks/hooks.json, the marker, and the dirs whose removal takes one of them (CLAUDE_CONFIG_DIR gets every ~/.claude rule); a project CLAUDE.md, a settings.json, hooks.json or hook source elsewhere and a copy in the temp root outside the home and project pass. Bash is judged per simple command (split on ;, &&, ||, |, & and newlines) from the payload cwd moved by each literal cd, pushd or popd: a simple command naming a live path is a write, denied by default, unless its command word is on a closed read-only list (cat, grep, jq, ls, ...) and no redirect targets the path; reads and quoted mentions pass, and a command longer than 16,384 characters or one that cannot be split is a write when its raw text names a protected path. The deny reason names at most 10 targets followed by \"and N more\", the marker and the `touch` one-liners for the user; a deny output of 16,384 bytes or more is replaced by a short reason naming no payload text. `freeharness init`/`update` set and remove their own marker. The entry carries onFailure \"block\", so a guard hook that cannot start, crashes or times out blocks the tool call on Claude Code 2.1.295 and later; a missing node then blocks every Edit, Write and Bash call until node is installed or the entry is removed by hand, and the switches below are read inside node, so they cannot help when node is missing. The same hook runs a git guard independent of the marker: history-destroying git commands (reset --hard, --keep or --merge; push with --force, -f or a + refspec that no --force-with-lease covers, and push --mirror, --delete/-d, --prune or a :refspec, which a lease never excuses; branch -D, -M, -C, -f or --force; clean -f; checkout -- <path>, checkout ., checkout <tree> <path>, checkout -f or -B; switch --discard-changes, -f or -C; restore without --staged alone; stash drop/clear; reflog expire; filter-branch; worktree remove --force) and git config that can add an alias or run code (set through -c, --config-env, GIT_CONFIG_* variables or git config: alias.*, include.*, help.autocorrect, clean.requireForce, core.pager, core.fsmonitor and every key outside a safe list) are denied from the model whatever the marker says, and the user runs an intended one with the `!` prefix; nesting deeper than 8 levels or an internal error denies with a reason naming no payload text; a value bound earlier on the line substitutes into git verb, option and operand slots before the check, interpreter code counts as git only with a process-spawning call and a git word, sed, grep and awk scripts are data, and an unknown expansion in the command-word slot or an xargs {} placeholder in one fails closed; every other git command, a git command inside a quoted argument, push --force-with-lease, object-writing plumbing (commit-tree, mktree, hash-object) and worktree remove --force under the temp root pass; FREEHARNESS_HOOK_GIT_GUARD=off disables only the git guard. Deny reasons render invisible and control characters as \\u{XXXX} escapes and cap each echoed fragment at 200 characters with an ellipsis. Disable the whole hook: FREEHARNESS_HOOK_CONFIG_GUARD=off or remove this entry.",
   "hooks": {
     "PreToolUse": [
       {
@@ -7,7 +7,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-config-guard.mjs\" --ttl 30"
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-config-guard.mjs\" --ttl 240",
+            "onFailure": "block"
           }
         ]
       }

package/canonical/hooks/hooks.context-monitor.claude-code.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "FreeHarness context monitor for Claude Code (cost capability). Merged additively into settings.json. Stop: reads the session's latest cost snapshot (context_tokens) and prints one systemMessage line to the user when the context crosses 60% and then 85% of --budget tokens (200k), naming the `# Compact instructions` block of CLAUDE.md for /compact. Each threshold once per session (~/.claude/freeharness/state/<session>.context.json). Never a Stop additionalContext (that would force another turn), never blocks. Disable: FREEHARNESS_HOOK_CONTEXT_MONITOR=off or remove this entry.",
+  "$comment": "FreeHarness context monitor for Claude Code (cost capability). Merged additively into settings.json. Stop: reads the session's latest cost snapshot (context_tokens) and prints one systemMessage line to the user when the context crosses 60% and then 85% of --budget tokens (200k), naming the `# Compact instructions` block of CLAUDE.md for /compact. At the highest threshold it first writes the project handoff (the eight-section skeleton, atomically, under ~/.claude/freeharness/state/handoff/) that the next startup or clear session claims once, and suggests /clear. Each threshold once per session (~/.claude/freeharness/state/<session>.context.json). Never a Stop additionalContext (that would force another turn), never blocks. Disable: FREEHARNESS_HOOK_CONTEXT_MONITOR=off or remove this entry.",
   "hooks": {
     "Stop": [
       {

package/canonical/hooks/hooks.converge.claude-code.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "FreeHarness converge loop for Claude Code (sdd capability; shape from the anthropics/claude-code ralph-loop plugin, Apache-2.0, fitted to tasks.md). Merged additively into settings.json. Stop: a no-op unless <project>/.freeharness/converge.json exists ({\"change\": \"<id>\", \"max_rounds\": 5, \"promise\": \"<exit condition>\"}). While openspec/changes/<change>/tasks.md has unchecked tasks and rounds < max_rounds it returns {\"decision\":\"block\",\"reason\":\"<next task + its Verify line>\"} so the agent keeps working; every round is appended to .freeharness/converge.log; at the limit or when every task is checked the session ends with a systemMessage. A tasks.md that is missing or has no checkbox lines disables the loop (converge.json gets \"disabled\": true + reason). Disable: FREEHARNESS_HOOK_CONVERGE=off, delete converge.json, or remove this entry.",
+  "$comment": "FreeHarness converge loop for Claude Code (sdd capability; shape from the anthropics/claude-code ralph-loop plugin, Apache-2.0, fitted to tasks.md). Merged additively into settings.json. Stop: a no-op unless <project>/.freeharness/converge.json exists ({\"change\": \"<id>\", \"max_rounds\": 5, \"promise\": \"<exit condition>\"}). While openspec/changes/<change>/tasks.md has unchecked tasks and rounds < max_rounds it returns {\"decision\":\"block\",\"reason\":\"<next task + its Verify line>\"} so the agent keeps working; every round is appended to .freeharness/converge.log; a linked or special .freeharness, converge.json or converge.log turns the loop off silently (a symlink, a hard-linked file, a FIFO or any other non-regular file: no block, no round, no log line); at the limit or when every task is checked the session ends with a systemMessage. A tasks.md that is missing or has no checkbox lines disables the loop (converge.json gets \"disabled\": true + reason). Disable: FREEHARNESS_HOOK_CONVERGE=off, delete converge.json, or remove this entry.",
   "hooks": {
     "Stop": [
       {

package/canonical/hooks/hooks.memory-guard.claude-code.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "FreeHarness PreToolUse memory guard for Claude Code. Merged additively into <project>/.claude/settings.json. Denies hand-written memory .md writes (the free-mem plugin owns memory; saves output tokens).",
+  "$comment": "FreeHarness PreToolUse memory guard for Claude Code. Merged additively into <project>/.claude/settings.json. Denies hand-written memory .md writes (the free-mem plugin owns memory; saves output tokens). The entry carries onFailure \"block\", so a guard hook that cannot start, crashes or times out blocks the tool call on Claude Code 2.1.295 and later; a missing node then blocks every Write, Edit and MultiEdit call until node is installed or the entry is removed by hand.",
   "hooks": {
     "PreToolUse": [
       {
@@ -7,7 +7,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-memory-guard.mjs\""
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-memory-guard.mjs\"",
+            "onFailure": "block"
           }
         ]
       }

package/canonical/hooks/hooks.reload-context.claude-code.json

@@ -0,0 +1,15 @@
+{
+  "$comment": "FreeHarness reload-context recap for Claude Code (rules capability). Merged additively into settings.json. UserPromptSubmit: only the prompt whose trimmed, lower-cased text is exactly `reload context` gets an additionalContext, the newest of the project's unclaimed handoff and the session's PreCompact skeleton rendered as the SessionStart re-orientation under 10,000 characters, or one no-saved-context line; every other prompt exits silently. Reading never claims the handoff. Never blocks. Disable: FREEHARNESS_HOOK_RELOAD_CONTEXT=off or remove the entry.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-reload-context.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}