freeharness 0.4.1

package/canonical/hooks/freeharness-session-start

@@ -0,0 +1,583 @@
+#!/usr/bin/env bash
+# FreeHarness SessionStart pointer (Claude Code): reads the payload from stdin, hands it to the
+# embedded Node program via FH_PAYLOAD (runnable by path or by `bash`). Additive: coexists with
+# 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.
+# 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
+# Routing file: next to this script first, else the canonical source layout.
+FH_HOOK_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+if [ -r "$FH_HOOK_DIR/freeharness-routing.md" ]; then
+  FH_ROUTING_FILE="$FH_HOOK_DIR/freeharness-routing.md"
+elif [ -r "$FH_HOOK_DIR/../rules/routing.md" ]; then
+  FH_ROUTING_FILE="$(cd "$FH_HOOK_DIR/../rules" && pwd -P)/routing.md"
+else
+  FH_ROUTING_FILE=""
+fi
+export FH_ROUTING_FILE
+FH_PAYLOAD="$(cat 2>/dev/null || true)"
+export FH_PAYLOAD
+
+if node --input-type=module - <<'JS'
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** The v3 pointer lines (without the closing tag; the SDD status line goes before it). */
+const POINTER_LINES = [
+  "<freeharness>",
+  "FreeHarness active. Plan non-trivial work with OpenSpec (/opsx: proposal, specs, design, tasks).",
+  "Execute with skills: test-driven-development, subagent-driven-development; review with code-review",
+  "plus the reviewer agents (python/database/security) and pr-reviewer (mle lens); gate with verification-before-completion.",
+  "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. */
+const MAX_COMPLETE_IDS = 5;
+
+/** The eight checkpoint sections, in order. */
+const SECTIONS = ["Primary Request", "Files and Code", "Errors and Fixes", "Pending Jobs", "Current Work", "Next Step", "Critical Context", "Corrections"];
+
+/** Closing rule. */
+const RULE = "Rule: after compaction, re-read Next Step and Errors and Fixes before acting.";
+
+/** Sources that get the re-orientation block. */
+const REORIENT = new Set(["compact", "resume", "fork"]);
+
+/** Tools whose calls count as file operations. */
+const FILE_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+
+/** Transcript scan cap (bytes). */
+const MAX_TRANSCRIPT_BYTES = 64 * 1024 * 1024;
+
+/** Routing table body cap (characters), before the `<routing>`/`</routing>` tags. */
+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). */
+const SHORTEN_AT = 9800;
+
+/** State dir (FREEHARNESS_STATE_DIR overrides). */
+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. */
+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 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*$/;
+
+/** A `Disposition:` line and its leading kind token. */
+const DISPOSITION_LINE_PATTERN = /^\s*Disposition:\s*(\S+)/;
+
+/** Disposition kinds that resolve a task; any other kind leaves it open. */
+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*/;
+
+/** `.freeharness/sdd.json`, relative to the project root. */
+const WIP_CAP_FILE = ".freeharness/sdd.json";
+
+/** `wip_cap` default when the file is absent, unreadable or holds an invalid value. */
+const DEFAULT_WIP_CAP = 1;
+
+/** Parses task lines with disposition awareness, mirroring the engine so the pointer agrees with `openspec status`. */
+function parseTasksWithDisposition(content) {
+  const tasks = [];
+  let current = null;
+  for (const line of content.split("\n")) {
+    const task = TASK_LINE_PATTERN.exec(line);
+    if (task) {
+      current = { done: task[1].toLowerCase() === "x", dispositioned: false };
+      tasks.push(current);
+      continue;
+    }
+    if (current && TASK_ANNOTATION_PATTERN.test(line)) {
+      const disposition = DISPOSITION_LINE_PATTERN.exec(line);
+      if (disposition && DISPOSITION_KINDS.has(disposition[1])) current.dispositioned = true;
+      continue;
+    }
+    current = null;
+  }
+  return tasks;
+}
+
+/** Counts a tasks.md's checkboxes: done, dispositioned (unchecked with a Disposition: line) and open. */
+function countTasksFromContent(content) {
+  const tasks = parseTasksWithDisposition(content);
+  const done = tasks.filter((t) => t.done).length;
+  const dispositioned = tasks.filter((t) => !t.done && t.dispositioned).length;
+  const open = tasks.length - done - dispositioned;
+  return { open, done, dispositioned };
+}
+
+/** Reads `wip_cap`; absent = default, invalid = default + INFO line naming the file. */
+function readWipCap(project) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(project, WIP_CAP_FILE), "utf8");
+  } catch (e) {
+    const absent = e && (e.code === "ENOENT" || e.code === "ENOTDIR");
+    if (absent) return { cap: DEFAULT_WIP_CAP, info: null };
+    return { cap: DEFAULT_WIP_CAP, info: `INFO ${WIP_CAP_FILE}: wip_cap invalid, using ${DEFAULT_WIP_CAP}` };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const cap = parsed && parsed.wip_cap;
+    if (typeof cap === "number" && Number.isInteger(cap) && cap > 0) return { cap, info: null };
+  } catch {
+    // falls through to the default below
+  }
+  return { cap: DEFAULT_WIP_CAP, info: `INFO ${WIP_CAP_FILE}: wip_cap invalid, using ${DEFAULT_WIP_CAP}` };
+}
+
+/** In-flight ids for the WIP cap: open task or no tasks.md, sorted for a deterministic list. */
+function wipInFlightIds(project) {
+  const dir = path.join(project, "openspec", "changes");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const ids = [];
+  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!e.isDirectory() || e.name === "archive" || e.name.startsWith(".")) continue;
+    let hasOpen = true;
+    try {
+      hasOpen = countTasksFromContent(fs.readFileSync(path.join(dir, e.name, "tasks.md"), "utf8")).open > 0;
+    } catch {
+      hasOpen = true;
+    }
+    if (hasOpen) ids.push(e.name);
+  }
+  return ids;
+}
+
+/** WIP advisory lines, printed only once in-flight count exceeds the cap (one change earlier than `openspec new change`'s own warning). */
+function wipAdvisoryLines(project) {
+  const inFlight = wipInFlightIds(project);
+  if (inFlight.length === 0) return [];
+  const { cap, info } = readWipCap(project);
+  if (inFlight.length <= cap) return [];
+  const lines = [];
+  if (info) lines.push(info);
+  const named = inFlight.map((id) => sanitizeTag(id)).join(", ");
+  lines.push(`WIP advisory: ${inFlight.length} change(s) in flight (cap ${cap}): ${named}; finish or archive before opening another`);
+  return lines;
+}
+
+/** Counts unclaimed follow-up items; item text is data, never read here. */
+function followUpCount(project) {
+  const changesDir = path.join(project, "openspec", "changes");
+  let total = 0;
+  const countFile = (dir) => {
+    let text;
+    try {
+      text = fs.readFileSync(path.join(dir, "follow-ups.md"), "utf8");
+    } catch {
+      return;
+    }
+    for (const line of text.split("\n")) {
+      if (FOLLOW_UP_ITEM_PATTERN.test(line)) total += 1;
+    }
+  };
+  let entries;
+  try {
+    entries = fs.readdirSync(changesDir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith(".")) continue;
+    if (e.name === "archive") {
+      let archived;
+      try {
+        archived = fs.readdirSync(path.join(changesDir, "archive"), { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const a of archived) {
+        if (!a.isDirectory() || a.name.startsWith(".")) continue;
+        countFile(path.join(changesDir, "archive", a.name));
+      }
+      continue;
+    }
+    countFile(path.join(changesDir, e.name));
+  }
+  return total;
+}
+
+/** 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). */
+function activeChanges(project) {
+  const dir = path.join(project, "openspec", "changes");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name === "archive") continue;
+    const tasks = path.join(dir, e.name, "tasks.md");
+    let text;
+    try {
+      text = fs.readFileSync(tasks, "utf8");
+    } catch {
+      continue;
+    }
+    const { open } = countTasksFromContent(text);
+    if (open > 0) {
+      const display = sanitizeTag(e.name);
+      const pathId = stripControl(e.name);
+      out.push(`${display} (openspec/changes/${pathId}/tasks.md, ${open} unchecked)`);
+    }
+  }
+  return out;
+}
+
+/** SDD status of the project's changes, from tasks.md checkbox counts; null when openspec/changes is absent. */
+function openspecStatus(project) {
+  const dir = path.join(project, "openspec", "changes");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const ids = [];
+  const complete = [];
+  let dispositioned = 0;
+  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!e.isDirectory() || e.name === "archive" || e.name.startsWith(".")) continue;
+    ids.push(e.name);
+    let text;
+    try {
+      text = fs.readFileSync(path.join(dir, e.name, "tasks.md"), "utf8");
+    } catch {
+      continue;
+    }
+    const counts = countTasksFromContent(text);
+    dispositioned += counts.dispositioned;
+    if (counts.open === 0 && counts.done > 0) complete.push(e.name);
+  }
+  let blocked = null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(project, ".freeharness", "sdd", "blockers.json"), "utf8"));
+    const list = Array.isArray(parsed) ? parsed : parsed && Array.isArray(parsed.blocked) ? parsed.blocked : null;
+    if (list) blocked = list.filter((id) => typeof id === "string" && ids.includes(id)).length;
+  } catch {
+    blocked = null;
+  }
+  return { inFlight: ids.length, complete, blocked, dispositioned, followUps: followUpCount(project) };
+}
+
+/** One-line SDD status; null when there is no status. */
+function openspecLine(status) {
+  if (!status) return null;
+  const shown = status.complete.slice(0, MAX_COMPLETE_IDS).map((id) => sanitizeTag(id));
+  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)` : "";
+  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) {
+  const line = openspecLine(openspecStatus(project));
+  return [...POINTER_LINES, ...(line ? [line] : []), ...wipAdvisoryLines(project), "</freeharness>"].join("\n");
+}
+
+/** `<N>k`, non-finite treated as 0. */
+function kTokens(n) {
+  const v = Number.isFinite(n) ? Number(n) : 0;
+  return `${Math.round(v / 1000)}k`;
+}
+
+/** Caps at 64 characters, keeps only `[\w.\-/ ,()]`: a directory name or telemetry field cannot inject a line of its own. */
+function sanitizeTag(s) {
+  return typeof s === "string" ? s.trim().replace(/[^\w.\-/ ,()]/g, "").slice(0, 64).trim() : "";
+}
+
+/** Strips control characters only, no length cap: see activeChanges (sdd-flow-2#7). */
+function stripControl(s) {
+  return typeof s === "string" ? s.replace(/[\x00-\x1f\x7f]/g, "") : "";
+}
+
+/** FH_ROUTING_FILE for the block after the pointer: strips control bytes (keeps \n/\t), truncates at ROUTING_CAP. block: null when missing, unreadable or empty. */
+function routingBlock(file) {
+  const filePath = typeof file === "string" ? file.trim() : "";
+  if (!filePath) return { block: null, path: "" };
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return { block: null, path: filePath };
+  }
+  const stripped = raw.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "").replace(/\n+$/, "");
+  if (!stripped.trim()) return { block: null, path: filePath };
+  if (stripped.length <= ROUTING_CAP) return { block: `<routing>\n${stripped}\n</routing>`, path: filePath };
+  const lines = stripped.split("\n");
+  let kept = "";
+  let cutAt = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const next = kept ? `${kept}\n${lines[i]}` : lines[i];
+    if (next.length > ROUTING_CAP - ROUTING_MARKER_RESERVE) break;
+    kept = next;
+    cutAt = i + 1;
+  }
+  const truncated = lines.length - cutAt;
+  const body = kept ? `${kept}\n(+${truncated} rows truncated)` : `(+${truncated} rows truncated)`;
+  return { block: `<routing>\n${body}\n</routing>`, path: filePath };
+}
+
+/** One telemetry line: `<change> <task> <tier>: main Nk, subagents Nk, observer Nk|n/a`. */
+function telemetryLine(rec) {
+  const change = sanitizeTag(rec.change) || "untagged";
+  const task = sanitizeTag(rec.task) || "-";
+  const tier = sanitizeTag(rec.tier) || "-";
+  const sinks = rec && typeof rec.sinks === "object" && rec.sinks ? rec.sinks : {};
+  const main = kTokens(sinks.main && sinks.main.total);
+  const subagents = kTokens(sinks.subagents && sinks.subagents.total);
+  const observerTokens = sinks.observer && Number.isFinite(sinks.observer.tokens) ? sinks.observer.tokens : null;
+  const observer = observerTokens === null ? "n/a" : kTokens(observerTokens);
+  return `${change} ${task} ${tier}: main ${main}, subagents ${subagents}, observer ${observer}`;
+}
+
+/** Last N telemetry records, one line each; empty when the file is absent or carries no valid record. */
+function telemetryTail(project, n) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(project, ".freeharness", "telemetry.jsonl"), "utf8");
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const raw of text.split("\n")) {
+    if (!raw.trim()) continue;
+    try {
+      const rec = JSON.parse(raw);
+      if (rec && typeof rec === "object") records.push(rec);
+    } catch {
+      // skip malformed line
+    }
+  }
+  return records.slice(-n).map(telemetryLine);
+}
+
+/** Latest cost-log snapshot context size/window for the session (usage.jsonl); null when absent. */
+function contextFromSnapshot(sessionId) {
+  const file = process.env.FREEHARNESS_COST_LOG || path.join(os.homedir(), ".claude", "freeharness", "cost", "usage.jsonl");
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const raw of text.split("\n")) {
+    if (!raw.includes(sessionId)) continue;
+    try {
+      const rec = JSON.parse(raw);
+      if (rec && rec.session_id === sessionId && rec.usage && Number.isFinite(rec.context_tokens)) {
+        const window = Number.isInteger(rec.context_window) && rec.context_window > 0 ? rec.context_window : 200_000;
+        best = { tokens: rec.context_tokens, window };
+      }
+    } catch {
+      // skip malformed line
+    }
+  }
+  return best;
+}
+
+/** `context: <tokens>k of <window>k`, only at or above 60% of the window. */
+function contextLine(sessionId) {
+  const snap = contextFromSnapshot(sessionId);
+  if (!snap) return null;
+  const pct = (snap.tokens / snap.window) * 100;
+  if (pct < 60) return null;
+  return `context: ${kTokens(snap.tokens)} of ${kTokens(snap.window)}`;
+}
+
+/** File operations: the PreCompact list when present, else a transcript count; null when unavailable. */
+function fileOps(sessionId, transcript) {
+  const listed = path.join(stateDir(), `${safeId(sessionId)}.fileops.json`);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(listed, "utf8"));
+    if (Array.isArray(parsed)) {
+      return parsed.map((x) => (typeof x === "string" ? x : x && typeof x.path === "string" ? `${x.path}${x.tool ? ` (${x.tool}${x.count ? ` x${x.count}` : ""})` : ""}` : "")).filter(Boolean);
+    }
+  } catch {
+    // fall through to the transcript
+  }
+  if (!transcript) return null;
+  let text;
+  try {
+    if (fs.statSync(transcript).size > MAX_TRANSCRIPT_BYTES) return null;
+    text = fs.readFileSync(transcript, "utf8");
+  } catch {
+    return null;
+  }
+  const counts = new Map();
+  for (const raw of text.split("\n")) {
+    if (!raw.includes('"tool_use"')) continue;
+    let rec;
+    try {
+      rec = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    const content = rec && rec.message && Array.isArray(rec.message.content) ? rec.message.content : [];
+    for (const block of content) {
+      if (!block || block.type !== "tool_use" || !FILE_TOOLS.has(block.name)) continue;
+      const input = block.input && typeof block.input === "object" ? block.input : {};
+      const file = input.file_path || input.notebook_path;
+      if (typeof file !== "string" || !file) continue;
+      const per = counts.get(file) || new Map();
+      per.set(block.name, (per.get(block.name) || 0) + 1);
+      counts.set(file, per);
+    }
+  }
+  return [...counts.entries()].map(([file, per]) => `${file} (${[...per.entries()].map(([t, n]) => `${t} x${n}`).join(", ")})`);
+}
+
+/** Parses PreCompact summary: `## <Section>` headings, body verbatim. */
+function precompactSummary(sessionId) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(stateDir(), `${safeId(sessionId)}.precompact.md`), "utf8");
+  } catch {
+    return {};
+  }
+  const out = {};
+  let current = null;
+  const buf = [];
+  const flush = () => {
+    if (current) out[current] = buf.join("\n").trim();
+    buf.length = 0;
+  };
+  for (const line of text.split("\n")) {
+    const m = /^##\s+(.+?)\s*$/.exec(line);
+    if (m) {
+      flush();
+      const name = SECTIONS.find((s) => s.toLowerCase() === m[1].toLowerCase());
+      current = name || null;
+      continue;
+    }
+    if (current) buf.push(line);
+  }
+  flush();
+  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);
+  lines.push("Telemetry (.freeharness/telemetry.jsonl, last 3):");
+  if (telemetryLines.length > 0) lines.push(...telemetryLines.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) {
+    lines.push("  (unavailable)");
+  } else {
+    if (opsLines.length > 0) lines.push(...opsLines.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(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) {
+  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 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 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 assemble = () => `${pointer}\n${routingText}\n${renderReorientation(source, activeLine, ctxLine, telemetryLines, telemetryDropped, opsLines, opsDropped, summary)}`;
+
+  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).`;
+  }
+  return assemble();
+}
+
+/** Entry point: always print the pointer (at least). */
+function main() {
+  if ((process.env.FREEHARNESS_HOOK_SESSION_START || "").toLowerCase() === "off") return;
+  let payload = {};
+  try {
+    const raw = process.env.FH_PAYLOAD || "";
+    if (raw.trim()) payload = JSON.parse(raw);
+  } catch {
+    payload = {};
+  }
+  if (!payload || typeof payload !== "object") payload = {};
+  let context = POINTER;
+  try {
+    context = 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();
+JS
+then exit 0; fi
+
+# Node missing/failed: the plain pointer, JSON-escaped by hand.
+POINTER='<freeharness>\nFreeHarness active. Plan non-trivial work with OpenSpec (/opsx: proposal, specs, design, tasks).\nExecute with skills: test-driven-development, subagent-driven-development; review with code-review\nplus the reviewer agents (python/database/security) and pr-reviewer (mle lens); gate with verification-before-completion.\nMemory is the free-mem plugin. The user'"'"'s CLAUDE.md/AGENTS.md always takes precedence over this pointer.\n</freeharness>'
+printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$POINTER"
+exit 0

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

@@ -0,0 +1,16 @@
+{
+  "$comment": "FreeHarness auto-memory tier-0 spike for Claude Code (memory capability, optional; OFF by default). Merged additively into settings.json. When FREEHARNESS_AUTO_MEMORY=on, SessionEnd curates one line per project into ~/.claude/freeharness/MEMORY.md from the last entry of <cwd>/.freeharness/dogfood.md, idempotently. Without the flag the hook is a no-op. Never blocks, never prints, exit 0. timeout 10 raises the 1.5 s SessionEnd budget Claude Code applies by default.",
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-auto-memory.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "$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.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact|resume|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-session-start\"",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,16 @@
+{
+  "$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.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-config-guard.mjs\" --ttl 30"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,15 @@
+{
+  "$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.",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-context-monitor.mjs\" --budget 200000 --thresholds 60,85"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,15 @@
+{
+  "$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.",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-converge.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}