freeharness 0.4.1 → 0.4.2

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

@@ -0,0 +1,970 @@
+// SDD context hook: the free-mem worker briefs every subagent at SubagentStart; at SubagentStop an
+// implementer's checkpoint becomes its task state and the worker keeps the task-tagged report.
+// Payload, transcript, report and worker answer are untrusted: in-flight workspace regular files
+// only, bounded loopback calls to a responder whose health answer carries the free-mem marker,
+// never blocks, exit 0.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** A missing or broken tracker silences the hook instead of failing at load. */
+let tracker = null;
+try {
+  tracker = await import("./freeharness-cost-tracker.mjs");
+} catch {
+  tracker = null;
+}
+
+const MAX_STDIN_BYTES = 1024 * 1024;
+/** No legitimate report reaches this size. */
+const MAX_FILE_BYTES = 64 * 1024;
+
+/** Retired implementer-high stays so a stale emitted agent still saves its state. */
+const STATE_TYPES = new Set(["implementer", "implementer-high"]);
+
+/** Anything else could steer the state file name. */
+const TASK_RE = /^(?:\d+(?:\.\d+)*|final)$/;
+
+/** A reply names its report early; the bound keeps a flood from spending the hook's timeout. */
+const MESSAGE_SCAN_CHARS = 64 * 1024;
+const REPORT_MARK = ".freeharness/sdd/";
+const REPORT_SUFFIX = ".review.md";
+/** `<` ends a token so a `<change>` placeholder never matches. */
+const TOKEN_STOPS = new Set(['"', "'", "`", "(", ")", "<", ">", "[", "]"]);
+/** Trimmed so a path closing a sentence still names its report. */
+const TOKEN_TRAIL = new Set([".", ",", ";", ":", "!", "?"]);
+
+/** Copied from validate-handoff.mjs, emitted elsewhere; a parity test pins the copies. */
+const CHECKPOINT_SECTIONS = ["Intent", "Files and code", "Decisions", "Errors and fixes", "Open work", "Next step"];
+const CHECKPOINT_BOUND = 8000;
+
+const MISSING = Symbol("missing");
+const REFUSED = Symbol("refused");
+
+/** The rest is never read, so a flood cannot hold the hook past its timeout. */
+function readStdin(max) {
+  const buf = Buffer.alloc(max);
+  let total = 0;
+  try {
+    while (total < max) {
+      const n = fs.readSync(0, buf, total, max - total, null);
+      if (n === 0) break;
+      total += n;
+    }
+  } catch {
+    // A closed or non-blocking stdin ends the read with what arrived.
+  }
+  return buf.toString("utf8", 0, total);
+}
+
+/** A plugin-scoped type matches by its last segment. */
+function agentName(type) {
+  if (typeof type !== "string") return null;
+  const scoped = /^plugin:[^:]+:([^:]+)$/.exec(type);
+  const name = scoped ? scoped[1] : type;
+  return STATE_TYPES.has(name) ? name : null;
+}
+
+/** The lead shell may sit anywhere in the project, so the workspace hangs off the root above the cwd. */
+function projectRoot(cwd) {
+  try {
+    return typeof tracker.projectRootFor === "function" ? tracker.projectRootFor(cwd) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Null unless reached through no symlink, so every read stays inside the project. */
+function workspaceFor(projectDir, change) {
+  try {
+    const root = fs.realpathSync(projectDir);
+    const dir = path.join(root, ".freeharness", "sdd", change);
+    if (fs.realpathSync(dir) !== dir || !fs.statSync(dir).isDirectory()) return null;
+    return { root, dir };
+  } catch {
+    return null;
+  }
+}
+
+/** Narrows a directory swap during the reads. */
+function stillContained(ws) {
+  try {
+    return fs.realpathSync(ws.dir) === ws.dir;
+  } catch {
+    return false;
+  }
+}
+
+/** REFUSED for a symlink leaf, a non-regular file (O_NONBLOCK keeps a FIFO from blocking), an oversize file or an entry swapped after the open. */
+function readWorkspaceFile(dir, name) {
+  const file = path.join(dir, name);
+  if (path.dirname(file) !== dir) return REFUSED;
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0));
+  } catch (e) {
+    return e && e.code === "ENOENT" ? MISSING : REFUSED;
+  }
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return REFUSED;
+    const buf = Buffer.allocUnsafe(MAX_FILE_BYTES + 1);
+    let total = 0;
+    while (total < buf.length) {
+      const n = fs.readSync(fd, buf, total, buf.length - total, total);
+      if (n === 0) break;
+      total += n;
+    }
+    if (total > MAX_FILE_BYTES) return REFUSED;
+    // Without O_NOFOLLOW a symlink leaf shows here as a different inode.
+    const entry = fs.lstatSync(file);
+    if (entry.dev !== stat.dev || entry.ino !== stat.ino) return REFUSED;
+    return { text: buf.toString("utf8", 0, total) };
+  } catch {
+    return REFUSED;
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      // Nothing to recover: the descriptor is gone either way.
+    }
+  }
+}
+
+/** Code points: the unit the checkpoint validator bounds by. */
+function chars(text) {
+  let n = 0;
+  for (const _ of text) n += 1;
+  return n;
+}
+
+const BRIEF_SUFFIX = ".brief.md";
+/** The emitted script cannot import the engine, so TAG_RE, AGENT_ID_RE, the brief caps and BRIEF_UNSAFE_RANGES are copies a test pins. */
+export const TAG_RE = /^(change|task):[A-Za-z0-9._/-]{1,120}$/;
+
+/** Only an entry that exists yet fails the containment check is a refusal; an absent workspace is not. */
+function entryPresent(file) {
+  try {
+    fs.lstatSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Tags name the brief's change and file, never its Task header, which a stored brief could not verify. */
+function briefTags(named) {
+  const task = named.file.slice(0, -BRIEF_SUFFIX.length);
+  return [`change:${named.change}`, `task:${named.change}/${task}`].filter((t) => TAG_RE.test(t));
+}
+
+/** Start has no prompt or transcript yet; tags need one under the projects directory naming a regular brief of an in-flight change. */
+function stopTags(payload) {
+  try {
+    if (!tracker || typeof tracker.briefPathFromText !== "function" || typeof tracker.underProjectsDir !== "function" || typeof payload.agent_transcript_path !== "string") return [];
+    const { cwd } = payload;
+    const root = projectRoot(cwd);
+    if (!root) return [];
+    const file = promptTranscript(payload);
+    const head = file === null ? null : readHead(file, TRANSCRIPT_HEAD_BYTES, (stat) => tracker.underProjectsDir(file, stat));
+    const text = head === null ? null : firstPromptOf(head);
+    const named = typeof text === "string" ? tracker.briefPathFromText(text, root, cwd) : null;
+    if (!named) return [];
+    const ws = workspaceFor(root, named.change);
+    if (!ws || !tracker.inFlight(ws.root, named.change)) return [];
+    const brief = path.join(ws.dir, named.file);
+    return path.dirname(brief) === ws.dir && regularFile(brief) && stillContained(ws) ? briefTags(named) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** The tracker's change-segment rule, checked without a nested quantifier. */
+function kebabSegment(s) {
+  return /^[a-z0-9-]+$/.test(s) && !s.startsWith("-") && !s.endsWith("-") && !s.includes("--");
+}
+
+function realOr(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    // Lexical match only; the workspace check refuses it later.
+    return p;
+  }
+}
+
+/** The tracker's root rule: the shell may reach the root through a symlinked cwd ancestor, so a lexical ancestor resolving to it counts. */
+function rootAccepted(prefix, root, cwd) {
+  if (prefix === "" || prefix === "./") return true;
+  if (!path.isAbsolute(prefix) || !prefix.endsWith("/")) return false;
+  const withSep = (p) => (p.endsWith("/") ? p : `${p}/`);
+  const base = path.resolve(root);
+  if (prefix === withSep(base) || prefix === withSep(realOr(base))) return true;
+  if (typeof cwd !== "string" || !path.isAbsolute(cwd) || !withSep(path.resolve(cwd)).startsWith(prefix)) return false;
+  return realOr(prefix) === realOr(base);
+}
+
+/** REFUSED, unlike null: the text names a refused report path, so no other source may supply one. */
+function reportPathFromText(text, root, cwd = root) {
+  const found = acceptedReportPath(text, root, cwd);
+  if (found !== null) return found;
+  return text.includes(REPORT_MARK) || text.includes(REPORT_SUFFIX) ? REFUSED : null;
+}
+
+/** The tracker's prompt-path rule on `.review.md`: only the first match counts, so a message cannot steer past a refused path; the scan stays linear on untrusted text. */
+function acceptedReportPath(text, root, cwd) {
+  const truncated = text.length > MESSAGE_SCAN_CHARS;
+  const scan = truncated ? text.slice(0, MESSAGE_SCAN_CHARS) : text;
+  const isStop = (ch) => TOKEN_STOPS.has(ch) || ch.trim() === "";
+  let from = 0;
+  for (;;) {
+    const at = scan.indexOf(REPORT_MARK, from);
+    if (at < 0) return null;
+    let start = at;
+    while (start > from && !isStop(scan[start - 1])) start -= 1;
+    const restStart = at + REPORT_MARK.length;
+    let end = restStart;
+    while (end < scan.length && !isStop(scan[end])) end += 1;
+    // A token cut by the bound has an unknown end.
+    if (truncated && end === scan.length) return null;
+    let last = end;
+    while (last > restStart && TOKEN_TRAIL.has(scan[last - 1])) last -= 1;
+    if (last - REPORT_SUFFIX.length >= restStart && scan.endsWith(REPORT_SUFFIX, last)) {
+      const token = scan.slice(start, last);
+      if (token.includes("..") || token.includes("\\")) return null;
+      const parts = scan.slice(restStart, last - REPORT_SUFFIX.length).split("/");
+      if (parts.length !== 2 || !kebabSegment(parts[0]) || parts[1].length > 64 || !TASK_RE.test(parts[1])) return null;
+      if (!rootAccepted(scan.slice(start, at), root, cwd)) return null;
+      return { change: parts[0], task: parts[1] };
+    }
+    from = end;
+  }
+}
+
+/** Code points, so the source holds no raw separator. */
+const LINE_TERMINATOR_RE = new RegExp(`[${[0x0a, 0x0d, 0x2028, 0x2029].map((c) => String.fromCharCode(c)).join("")}]`);
+
+/** `/^### (.+?)\s*$/` without backtracking: the lazy group is quadratic on a long run of spaces. */
+function headingName(line) {
+  if (!line.startsWith("### ") || line.length === 4) return null;
+  const rest = line.slice(4);
+  const name = rest.trimEnd();
+  if (name === "") return LINE_TERMINATOR_RE.test(rest[0]) ? null : rest[0];
+  return LINE_TERMINATOR_RE.test(name) ? null : name;
+}
+
+/**
+ * Mirrors validate-handoff.mjs `checkpointOf`, which a parity test holds it to.
+ * @returns {{ text: string | null, errors: string[], size: number }} The section, its problems and its size in code points.
+ */
+export function checkpointOf(text) {
+  const lines = String(text).split("\n");
+  let start = -1;
+  lines.forEach((l, i) => {
+    if (/^## Checkpoint\s*$/.test(l)) start = i;
+  });
+  if (start === -1) return { text: null, errors: ["checkpoint-missing section"], size: 0 };
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) {
+      end = i;
+      break;
+    }
+  }
+  const body = lines.slice(start, end).join("\n").trimEnd();
+  const size = chars(body);
+  const headings = [];
+  for (const line of body.split("\n").slice(1)) {
+    const name = headingName(line);
+    if (name !== null) headings.push({ name, filled: false });
+    else if (headings.length > 0 && line.trim() !== "") headings[headings.length - 1].filled = true;
+  }
+  const accepted = new Map();
+  let lastRank = -1;
+  for (const h of headings) {
+    const rank = CHECKPOINT_SECTIONS.indexOf(h.name);
+    if (rank === -1) continue;
+    if (rank <= lastRank) break;
+    accepted.set(h.name, h.filled);
+    lastRank = rank;
+  }
+  const errors = CHECKPOINT_SECTIONS.filter((n) => accepted.get(n) !== true).map((n) => `checkpoint-missing ${n}`);
+  if (size > CHECKPOINT_BOUND) errors.push(`checkpoint-oversized ${size}`);
+  return { text: body, errors, size };
+}
+
+/** Absent or a single-link regular file, so the write never lands on a symlink, a directory or a shared inode. */
+function stateTargetOk(file) {
+  let st;
+  try {
+    st = fs.lstatSync(file);
+  } catch (e) {
+    return Boolean(e && e.code === "ENOENT");
+  }
+  return st.isFile() && st.nlink === 1;
+}
+
+/**
+ * Through a fsynced exclusive temporary file and a rename, so a reader sees the old state or the new one whole.
+ * @returns {string | null} Null once saved, else a reason for the parent: a Node error code or `refused`, never a path.
+ */
+function writeState(ws, name, text) {
+  const target = path.join(ws.dir, name);
+  const tmp = path.join(ws.dir, `.${name}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`);
+  const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0);
+  let fd = null;
+  let created = false;
+  try {
+    fd = fs.openSync(tmp, flags, 0o666);
+    created = true;
+    const buf = Buffer.from(text, "utf8");
+    let off = 0;
+    while (off < buf.length) off += fs.writeSync(fd, buf, off, buf.length - off);
+    fs.fsyncSync(fd);
+    const own = fs.fstatSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    // Narrows a swap of the directory or the target since the first checks.
+    const entry = fs.lstatSync(tmp);
+    if (entry.dev !== own.dev || entry.ino !== own.ino || !stillContained(ws) || !stateTargetOk(target)) return "refused";
+    fs.renameSync(tmp, target);
+    created = false;
+    return null;
+  } catch (e) {
+    const code = e && typeof e.code === "string" ? e.code : "";
+    return /^E[A-Z0-9]{1,15}$/.test(code) ? code : "refused";
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // Nothing to recover: the descriptor is gone either way.
+      }
+    }
+    if (created) {
+      try {
+        fs.unlinkSync(tmp);
+      } catch {
+        // Already gone; nothing else to clean.
+      }
+    }
+  }
+}
+
+/**
+ * A refused path or state target writes nothing, so a planted link cannot redirect the write; an invalid checkpoint leaves the state untouched.
+ * A valid checkpoint that fails to save answers `sdd-context: state <task> not saved (<code>)`, so the lead never takes a lost state for a kept one.
+ * @returns {string | null} One `sdd-context:` line, or null for silence.
+ */
+export function subagentStopState(payload) {
+  return stopOutcome(payload).context;
+}
+
+/**
+ * The state write and the handoff record keep their order and finish before any worker call, which a refusal here forbids.
+ * @returns {{ context: string | null, refused: boolean }} The workerless context and whether a path or target was refused.
+ */
+function stopOutcome(payload) {
+  const quiet = { context: null, refused: false };
+  const refused = { context: null, refused: true };
+  if (!tracker || !payload || typeof payload !== "object" || Array.isArray(payload)) return quiet;
+  if (payload.hook_event_name !== "SubagentStop") return quiet;
+  const agent = agentName(payload.agent_type);
+  const { cwd } = payload;
+  if (!agent || typeof cwd !== "string" || !path.isAbsolute(cwd)) return quiet;
+  const root = projectRoot(cwd);
+  if (!root) return quiet;
+  const named = reportNaming(payload, root);
+  if (named === REFUSED) return refused;
+  if (!named) return quiet;
+  const ws = workspaceFor(root, named.change);
+  if (!ws) return entryPresent(path.join(root, ".freeharness", "sdd", named.change)) ? refused : quiet;
+  if (!tracker.inFlight(ws.root, named.change)) return quiet;
+  const report = readWorkspaceFile(ws.dir, `${named.task}${REPORT_SUFFIX}`);
+  const readable = report !== MISSING && report !== REFUSED;
+  recordHandoff(ws, payload, readable ? report.text : null);
+  if (!readable) return report === REFUSED ? refused : quiet;
+  const stateName = `${named.task}.state.md`;
+  if (!stateTargetOk(path.join(ws.dir, stateName))) return refused;
+  const cp = checkpointOf(report.text);
+  if (cp.errors.length > 0) {
+    if (!stillContained(ws)) return refused;
+    // Error words are fixed or numeric, so no report text reaches the parent.
+    const first = cp.errors[0];
+    const space = first.indexOf(" ");
+    return { context: `sdd-context: ${first.slice(0, space)} ${named.task} ${first.slice(space + 1)}`, refused: false };
+  }
+  const failure = writeState(ws, stateName, cp.text);
+  const context = failure === null ? `sdd-context: state ${named.task} saved (${cp.size} chars)` : `sdd-context: state ${named.task} not saved (${failure})`;
+  return { context, refused: failure === "refused" };
+}
+
+const HANDOFFS_FILE = "handoffs.jsonl";
+const HANDOFF_STATUSES = new Set(["completed", "partial", "blocked"]);
+const STOP_TOKENS = new Set(["too-big", "needs-confirm", "ambiguous", "regressed", "scope"]);
+/** Stricter than the tracker's id shape: the record's readers expect no dot. */
+const RECORD_AGENT_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const MAX_HANDOFF_LINE_BYTES = 1024;
+/** The dispatch prompt opens the transcript, so its head is enough. */
+const TRANSCRIPT_HEAD_BYTES = 64 * 1024;
+const DISPATCH_LINE_RE = /^Dispatch: (\S+)$/;
+
+/** Body of the first fenced json block, or null when none closes. */
+function firstJsonBlock(text) {
+  const lines = text.split("\n");
+  let open = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (open < 0) {
+      if (line === "```json") open = i;
+    } else if (line === "```") {
+      return lines.slice(open + 1, i).join("\n");
+    }
+  }
+  return null;
+}
+
+/** A free-text reason counts only through a known token, so a stop tally never grows new categories. */
+function stopToken(reason) {
+  if (typeof reason !== "string") return null;
+  const colon = reason.indexOf(":");
+  const token = (colon < 0 ? reason : reason.slice(0, colon)).trim();
+  return STOP_TOKENS.has(token) ? token : null;
+}
+
+function handoffOutcome(reportText) {
+  const unreadable = { status: "unreadable", stop: null };
+  if (typeof reportText !== "string") return unreadable;
+  const block = firstJsonBlock(reportText);
+  if (block === null) return unreadable;
+  let handoff;
+  try {
+    handoff = JSON.parse(block);
+  } catch {
+    return unreadable;
+  }
+  if (!handoff || typeof handoff !== "object" || Array.isArray(handoff) || !HANDOFF_STATUSES.has(handoff.status)) return unreadable;
+  return { status: handoff.status, stop: handoff.status === "blocked" ? stopToken(handoff.blocked_reason) : null };
+}
+
+/**
+ * Never follows a symlink leaf or blocks on a FIFO; a larger file yields only its head.
+ * @param {((stat: fs.Stats) => boolean) | null} [accept] Must pass on the opened file before any byte is read.
+ */
+function readHead(file, max, accept = null) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0));
+  } catch {
+    return null;
+  }
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || (accept !== null && !accept(stat))) return null;
+    const buf = Buffer.allocUnsafe(max);
+    let total = 0;
+    while (total < max) {
+      const n = fs.readSync(fd, buf, total, max - total, total);
+      if (n === 0) break;
+      total += n;
+    }
+    return buf.toString("utf8", 0, total);
+  } catch {
+    return null;
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      // Nothing to recover: the descriptor is gone either way.
+    }
+  }
+}
+
+/** The tracker's reading of a prompt's text content, so both sides name the same dispatch. */
+function messageText(msg) {
+  const content = msg && typeof msg === "object" ? msg.content : null;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((c) => c && c.type === "text" && typeof c.text === "string")
+    .map((c) => c.text)
+    .join("\n");
+}
+
+/** The tracker's resolution, so both hooks read the same dispatch. */
+function promptTranscript(payload) {
+  if (typeof tracker.subagentTranscriptFor !== "function") return null;
+  const { transcript_path: transcriptPath, agent_id: agentId } = payload;
+  if (typeof transcriptPath !== "string" || typeof agentId !== "string") return null;
+  const file = tracker.subagentTranscriptFor(transcriptPath, agentId, payload);
+  return typeof file === "string" ? file : null;
+}
+
+function firstPromptText(file) {
+  const head = readHead(file, TRANSCRIPT_HEAD_BYTES);
+  return head === null ? null : firstPromptOf(head);
+}
+
+/** Only the first prompt counts: a later user turn could claim any round, report or brief. */
+function firstPromptOf(head) {
+  for (const raw of head.split("\n")) {
+    let rec;
+    try {
+      rec = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!rec || typeof rec !== "object" || Array.isArray(rec) || rec.type !== "user") continue;
+    return messageText(rec.message);
+  }
+  return null;
+}
+
+function dispatchRound(payload) {
+  if (typeof tracker.parseDispatchName !== "function") return null;
+  const file = promptTranscript(payload);
+  const text = file === null ? null : firstPromptText(file);
+  if (text === null) return null;
+  const m = DISPATCH_LINE_RE.exec(text.split(/\r?\n/, 1)[0]);
+  const round = m ? tracker.parseDispatchName(m[1]).round : null;
+  return Number.isSafeInteger(round) && round >= 1 ? round : null;
+}
+
+const REPORT_LINE = "Report: ";
+
+/**
+ * A dispatch handing back through a background tool names no report in its reply; the lead's prompt does.
+ * The prompt is trusted no more than the reply: only its first `Report: ` line counts, under the reply's path and containment rules.
+ * @param {string} root Project root the report must sit under.
+ * @param {string} [cwd] Payload cwd, whose lexical ancestors may spell the root.
+ * @returns {{ change: string, task: string } | null} The report's change and task, or null for silence.
+ */
+export function reportFromPrompt(transcriptPath, root, cwd = root) {
+  const named = promptReport(transcriptPath, root, cwd);
+  return named === REFUSED ? null : named;
+}
+
+/** REFUSED keeps a refused `Report: ` line apart from a missing one, so the worker call can be withheld. */
+function promptReport(transcriptPath, root, cwd) {
+  try {
+    if (typeof transcriptPath !== "string" || !path.isAbsolute(transcriptPath) || typeof root !== "string" || !path.isAbsolute(root)) return null;
+    const text = firstPromptText(transcriptPath);
+    if (text === null) return null;
+    const line = text.split(/\r?\n/).find((l) => l.startsWith(REPORT_LINE));
+    return line === undefined ? null : reportPathFromText(line.slice(REPORT_LINE.length), root, cwd);
+  } catch {
+    return null;
+  }
+}
+
+/** The state and the record follow one report: the reply's, else the prompt's; the prompt never overrides a refused reply path. */
+function reportNaming(payload, root) {
+  const { last_assistant_message: message, cwd } = payload;
+  const fromReply = typeof message === "string" ? reportPathFromText(message, root, cwd) : null;
+  if (fromReply !== null) return fromReply;
+  const file = promptTranscript(payload);
+  return file === null ? null : promptReport(file, root, cwd);
+}
+
+function namedReport(payload, root) {
+  const named = reportNaming(payload, root);
+  return named === REFUSED ? null : named;
+}
+
+/** A symlinked brief must not make a task countable. */
+function regularFile(file) {
+  try {
+    return fs.lstatSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Review packages are overwritten on re-dispatch, so only an append-only line per stop keeps the handoff count.
+ * The task comes from the report path the reply or else the dispatch prompt names, never the untrusted handoff, and every failure is silence.
+ * @param {{ root: string, dir: string }} ws The in-flight workspace that report path names.
+ * @param {string | null} reportText Report text, null when missing or refused.
+ */
+export function recordHandoff(ws, payload, reportText) {
+  try {
+    if (!tracker || typeof tracker.appendLedgerLine !== "function" || !ws || typeof ws.root !== "string" || typeof ws.dir !== "string") return;
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+    if (typeof payload.cwd !== "string" || !path.isAbsolute(payload.cwd)) return;
+    const named = namedReport(payload, ws.root);
+    if (!named || ws.dir !== path.join(ws.root, ".freeharness", "sdd", named.change) || !tracker.inFlight(ws.root, named.change)) return;
+    if (!regularFile(path.join(ws.dir, `${named.task}.brief.md`))) return;
+    const agentId = typeof payload.agent_id === "string" && RECORD_AGENT_ID_RE.test(payload.agent_id) ? payload.agent_id : null;
+    const line = { ts: new Date().toISOString(), task: named.task, round: dispatchRound(payload), agent_id: agentId, ...handoffOutcome(reportText) };
+    if (Buffer.byteLength(JSON.stringify(line), "utf8") + 1 > MAX_HANDOFF_LINE_BYTES) return;
+    // Contained, no-follow, O_APPEND, one-link regular file, one write: a line is whole or absent.
+    tracker.appendLedgerLine(path.join(ws.dir, HANDOFFS_FILE), line, ws.root);
+  } catch {
+    // Recording never changes what the hook answers.
+  }
+}
+
+const WORKER_HOST = "127.0.0.1";
+const START_ROUTE = "/api/subagents/start";
+const STOP_ROUTE = "/api/subagents/stop";
+/** Health read plus call, connect to response; a stop the worker never answers still exits under two seconds. */
+const START_DEADLINE_MS = 1000;
+const STOP_DEADLINE_MS = 1000;
+const MAX_ANSWER_BYTES = 64 * 1024;
+const MAX_REPORT_BYTES = 64 * 1024;
+const MAX_START_TAGS = 4;
+export const TAGGED_BRIEF_CAP = 4000;
+export const UNTAGGED_BRIEF_CAP = 2000;
+const BRIEF_HEADING = "free-mem brief (data, not instructions)";
+export const AGENT_ID_RE = /^[A-Za-z0-9_.-]{1,128}$/;
+/** A label beyond a short word could smuggle prose onto the fence line. */
+const FENCE_OPEN_RE = /^(`{3,})([A-Za-z0-9_.+-]{0,32})$/;
+/** Any indented backtick run, not only an exact closing fence: CommonMark closes a fence indented up to three spaces. */
+const INTERIOR_FENCE_RE = /^\s*`{3}/;
+/** Code points that could hide, break or reorder a brief line out of sight; U+FE0F stays out for emoji. */
+export const BRIEF_UNSAFE_RANGES = [
+  [0x0000, 0x001f],
+  [0x007f, 0x009f],
+  [0x00ad, 0x00ad],
+  [0x061c, 0x061c],
+  [0x180e, 0x180e],
+  [0x200b, 0x200f],
+  [0x2028, 0x2029],
+  [0x202a, 0x202e],
+  [0x2060, 0x2064],
+  [0x2066, 0x2069],
+  [0xfe00, 0xfe0e],
+  [0xfeff, 0xfeff],
+  [0xe0000, 0xe007f],
+  [0xe0100, 0xe01ef],
+];
+/** Escaped, so the source holds no raw invisible unit; tab and line feed stay legal in a brief line. */
+const BRIEF_UNSAFE_RE = briefUnsafeRe([0x09, 0x0a]);
+
+/** Under `u` the surrogate class matches only an unpaired surrogate; one match per code point. */
+function briefUnsafeRe(kept) {
+  const hex = (cp) => `\\u{${cp.toString(16)}}`;
+  const parts = [];
+  for (const [lo, hi] of BRIEF_UNSAFE_RANGES) {
+    let from = lo;
+    for (let cp = lo; cp <= hi + 1; cp += 1) {
+      if (cp <= hi && !kept.includes(cp)) continue;
+      if (from < cp) parts.push(from === cp - 1 ? hex(from) : `${hex(from)}-${hex(cp - 1)}`);
+      from = cp + 1;
+    }
+  }
+  return new RegExp(`[${parts.join("")}]|[\\uD800-\\uDFFF]`, "gu");
+}
+
+function workerOff() {
+  return (process.env.FREEHARNESS_SDD_CONTEXT_WORKER || "").toLowerCase() === "off";
+}
+
+// The engine's data-dir and port rule, as in freeharness-precompact.mjs, a separate emitted script.
+const MEM_DATA_DIR_KEYS = ["FREE_MEM_DATA_DIR", "CLAUDE_MEM_DATA_DIR"];
+const BOM = 0xfeff;
+
+function expandMemHome(p, home) {
+  if (p === "~") return home;
+  return p.startsWith("~/") ? path.join(home, p.slice(2)) : p;
+}
+
+function isMemDirectory(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Keys as the engine reads them: BOM dropped, `env` first. */
+function readMemSettings(file) {
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    const raw = JSON.parse(text.charCodeAt(0) === BOM ? text.slice(1) : text);
+    const s = raw && (raw.env ?? raw);
+    return s && typeof s === "object" ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+function memPort(value) {
+  const p = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(p) && p > 0 ? p : null;
+}
+
+/** The memory data directory from `env` and `home` alone, so a test can pass fake values. */
+export function resolveMemoryDataDir(env, home) {
+  for (const key of MEM_DATA_DIR_KEYS) {
+    if (typeof env[key] === "string" && env[key]) return expandMemHome(env[key], home);
+  }
+  const freeDir = path.join(home, ".free-mem");
+  const legacyDir = path.join(home, ".claude-mem");
+  const defaults = [path.resolve(freeDir), path.resolve(legacyDir)];
+  for (const dir of [freeDir, legacyDir]) {
+    const s = readMemSettings(path.join(dir, "settings.json"));
+    for (const key of MEM_DATA_DIR_KEYS) {
+      const value = s ? s[key] : undefined;
+      if (typeof value !== "string" || !value) continue;
+      const target = expandMemHome(value, home);
+      // A seeded default is not a redirect; honoring it would pin the directory choice.
+      if (!defaults.includes(path.resolve(target))) return target;
+    }
+  }
+  return isMemDirectory(freeDir) || !isMemDirectory(legacyDir) ? freeDir : legacyDir;
+}
+
+/** The worker port: env (empty is unset), then the data dir's settings, else the default; pure over (env, home). */
+export function resolveWorkerPort(env, home) {
+  const fromEnv = memPort(env.FREE_MEM_WORKER_PORT || env.CLAUDE_MEM_WORKER_PORT);
+  if (fromEnv !== null) return fromEnv;
+  const s = readMemSettings(path.join(resolveMemoryDataDir(env, home), "settings.json"));
+  const fromSettings = s ? memPort(s.FREE_MEM_WORKER_PORT ?? s.CLAUDE_MEM_WORKER_PORT) : null;
+  return fromSettings ?? defaultWorkerPort();
+}
+
+function defaultWorkerPort() {
+  return 37700 + (((typeof process.getuid === "function" ? process.getuid() : 77) || 0) % 100);
+}
+
+/** A resolver error falls back to the default port, as an unreadable settings file does. */
+function workerPort() {
+  try {
+    return resolveWorkerPort(process.env, os.homedir());
+  } catch {
+    return defaultWorkerPort();
+  }
+}
+
+/** Another program may hold the port; the engine's FREE_MEM_PRODUCT, copied because this script cannot import it (a test pins both). */
+export const FREE_MEM_PRODUCT = "free-mem";
+
+/** Nothing from the answer leaves this function: the port may belong to an unknown program. */
+export async function workerIsFreeMem(port, deadlineMs) {
+  try {
+    if (!Number.isInteger(port) || port < 1 || port > 65535 || !(deadlineMs > 0)) return false;
+    const res = await fetch(`http://${WORKER_HOST}:${port}/api/health`, { signal: AbortSignal.timeout(deadlineMs) });
+    if (res.status !== 200 || !res.body) {
+      res.body?.cancel().catch(() => {});
+      return false;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > MAX_ANSWER_BYTES) {
+        reader.cancel().catch(() => {});
+        return false;
+      }
+      chunks.push(value);
+    }
+    const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && parsed.product === FREE_MEM_PRODUCT;
+  } catch {
+    return false;
+  }
+}
+
+/** What a health read left of a deadline, so the read and the call together keep it. */
+function leftOf(budgetMs, startedMs) {
+  return budgetMs - (Date.now() - startedMs);
+}
+
+/** The route schema's identity fields; a payload the route would reject is never sent. */
+function callIdentity(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const { session_id: sessionId, agent_id: agentId, agent_type: agentType, cwd } = payload;
+  if (typeof agentId !== "string" || !AGENT_ID_RE.test(agentId)) return null;
+  if (typeof sessionId !== "string" || sessionId.length < 1 || sessionId.length > 256) return null;
+  if (typeof agentType !== "string" || agentType.length < 1 || agentType.length > 128) return null;
+  if (typeof cwd !== "string" || cwd.length < 1 || cwd.length > 4096 || !path.isAbsolute(cwd)) return null;
+  return { contentSessionId: sessionId, agentId, agentType, cwd };
+}
+
+/** One bounded loopback POST: null on any error, deadline or an answer over its byte bound. */
+function postJson(port, route, body, deadlineMs) {
+  return new Promise((resolve) => {
+    let req = null;
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (req) req.destroy();
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(null), deadlineMs);
+    try {
+      if (!Number.isInteger(port) || port < 1 || port > 65535) return finish(null);
+      const data = Buffer.from(JSON.stringify(body), "utf8");
+      const headers = { "content-type": "application/json", "content-length": data.length, connection: "close" };
+      req = http.request({ host: WORKER_HOST, port, path: route, method: "POST", agent: false, headers }, (res) => {
+        const chunks = [];
+        let total = 0;
+        res.on("data", (chunk) => {
+          total += chunk.length;
+          if (total > MAX_ANSWER_BYTES) finish(null);
+          else chunks.push(chunk);
+        });
+        res.on("end", () => finish({ status: res.statusCode || 0, text: Buffer.concat(chunks).toString("utf8") }));
+        res.on("error", () => finish(null));
+        res.on("close", () => finish(null));
+      });
+      req.on("error", () => finish(null));
+      req.end(data);
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+/**
+ * The answer is data from another process: only a balanced fence passes, cut at a whole line so the closing fence survives the cap.
+ * An unsafe unit is replaced, never a reason to drop.
+ * @param {boolean} taskTagged Whether a `task:` tag was sent (the start route's larger cap).
+ * @returns {string | null} The fenced brief within its cap, or null to drop it.
+ */
+function acceptBrief(raw, taskTagged) {
+  if (typeof raw !== "string" || raw === "") return null;
+  const text = raw.replace(/\r\n/g, "\n").replace(BRIEF_UNSAFE_RE, "�");
+  const lines = (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n");
+  const m = lines.length >= 3 ? FENCE_OPEN_RE.exec(lines[0]) : null;
+  if (!m || lines[lines.length - 1] !== m[1]) return null;
+  const fence = m[1];
+  const interior = lines.slice(1, -1);
+  if (interior.some((l) => INTERIOR_FENCE_RE.test(l))) return null;
+  const cap = taskTagged ? TAGGED_BRIEF_CAP : UNTAGGED_BRIEF_CAP;
+  let size = chars(lines[0]) + 1 + chars(fence);
+  const kept = [];
+  for (const line of interior) {
+    const next = size + chars(line) + 1;
+    if (next > cap) break;
+    kept.push(line);
+    size = next;
+  }
+  return kept.length > 0 ? [lines[0], ...kept, fence].join("\n") : null;
+}
+
+/**
+ * Asks the worker for the subagent's brief; any failure is no brief, leaving the context as without the call.
+ * @param {string[]} tags Change and task tags; a tag off the route's pattern is not sent.
+ * @param {number} [deadlineMs] What the hook's start budget has left for the call.
+ */
+export async function startCall(port, payload, tags, deadlineMs = START_DEADLINE_MS) {
+  try {
+    if (workerOff() || !(deadlineMs > 0)) return null;
+    const identity = callIdentity(payload);
+    if (!identity || !Array.isArray(tags)) return null;
+    const sent = tags.filter((t) => typeof t === "string" && TAG_RE.test(t)).slice(0, MAX_START_TAGS);
+    const answer = await postJson(port, START_ROUTE, { ...identity, tags: sent }, deadlineMs);
+    if (!answer || answer.status < 200 || answer.status > 299) return null;
+    const parsed = JSON.parse(answer.text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return acceptBrief(parsed.brief, sent.some((t) => t.startsWith("task:")));
+  } catch {
+    return null;
+  }
+}
+
+/** The route's byte bound, cut back to a lead byte so the sent text stays valid UTF-8. */
+function utf8Prefix(text, max) {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.length <= max) return buf.toString("utf8");
+  let end = max;
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end -= 1;
+  return buf.toString("utf8", 0, end);
+}
+
+/**
+ * Leaves the agent's final message with the worker; its answer is ignored, so none of it reaches the parent.
+ * @param {number} [deadlineMs] What the hook's stop budget has left for the call.
+ * @returns {Promise<void>} Settles within the stop deadline.
+ */
+export async function stopCall(port, payload, deadlineMs = STOP_DEADLINE_MS) {
+  try {
+    if (workerOff() || !(deadlineMs > 0)) return;
+    const identity = callIdentity(payload);
+    const message = identity ? payload.last_assistant_message : null;
+    if (typeof message !== "string" || message === "") return;
+    const body = { ...identity, report: utf8Prefix(message, MAX_REPORT_BYTES) };
+    const tags = stopTags(payload);
+    await postJson(port, STOP_ROUTE, tags.length > 0 ? { ...body, tags } : body, deadlineMs);
+  } catch {
+    // The report is best effort: a lost one never changes the hook's answer.
+  }
+}
+
+/** Synchronous, so nothing is left queued at exit. */
+function writeOut(text) {
+  const buf = Buffer.from(text, "utf8");
+  let off = 0;
+  while (off < buf.length) off += fs.writeSync(1, buf, off, buf.length - off);
+}
+
+/** At stop the workerless output alone decides a refusal, never the worker call. */
+async function respond(payload) {
+  const event = payload !== null && typeof payload === "object" ? payload.hook_event_name : null;
+  if (event === "SubagentStart") {
+    if (workerOff()) return null;
+    let brief = null;
+    try {
+      const started = Date.now();
+      const port = workerPort();
+      if (await workerIsFreeMem(port, START_DEADLINE_MS)) brief = await startCall(port, payload, [], leftOf(START_DEADLINE_MS, started));
+    } catch {
+      brief = null;
+    }
+    return brief === null ? null : `${BRIEF_HEADING}\n${brief}`;
+  }
+  if (event === "SubagentStop") {
+    const outcome = stopOutcome(payload);
+    try {
+      if (!outcome.refused && !workerOff()) {
+        const started = Date.now();
+        const port = workerPort();
+        if (await workerIsFreeMem(port, STOP_DEADLINE_MS)) await stopCall(port, payload, leftOf(STOP_DEADLINE_MS, started));
+      }
+    } catch {
+      // The parent's answer never depends on the report reaching the worker.
+    }
+    return outcome.context;
+  }
+  return null;
+}
+
+async function main() {
+  try {
+    let payload;
+    try {
+      payload = JSON.parse(readStdin(MAX_STDIN_BYTES));
+    } catch {
+      return;
+    }
+    const context = await respond(payload);
+    if (context === null) return;
+    writeOut(JSON.stringify({ hookSpecificOutput: { hookEventName: payload.hook_event_name, additionalContext: context } }));
+  } catch {
+    // Never block and never speak on stderr: a failure is silence.
+  }
+}
+
+/** Lets tests import the file without side effects. */
+function isMain() {
+  try {
+    return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  await main();
+  process.exit(0);
+}