freeharness 0.4.1

package/canonical/hooks/freeharness-precompact.mjs

@@ -0,0 +1,323 @@
+// FreeHarness PreCompact hook (Claude Code). Runs right before the context is compacted
+// (`/compact` or auto-compaction) and leaves two artifacts for the SessionStart
+// re-orientation (freeharness-session-start, source=compact):
+//   ~/.claude/freeharness/state/<session>.precompact.md  — the eight-section checkpoint
+//     skeleton (Primary Request, Files and Code, Errors and Fixes, Pending Jobs, Current Work,
+//     Next Step, Critical Context, Corrections), one `## <Section>` heading each, built
+//     locally from the transcript; identifiers, paths and error strings copied verbatim.
+//   ~/.claude/freeharness/state/<session>.fileops.json    — [{path, tool, count}] from the
+//     Read/Edit/Write/MultiEdit/NotebookEdit tool_use blocks of the transcript.
+// It also asks the running memory worker to store a session summary
+// (POST /api/sessions/summarize, the same route the Stop hook uses; it queues, it does not
+// return text) so the compaction point lands in memory. The worker being down is normal:
+// the request is skipped, the local skeleton is still written. Never blocks, never prints,
+// exit 0 on every path (a PreCompact hook cannot inject context anyway).
+// Disable: FREEHARNESS_HOOK_PRECOMPACT=off. Worker call off: FREEHARNESS_PRECOMPACT_WORKER=off.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The eight checkpoint sections, in contract order (freeharness-session-start reads them). */
+export const SECTIONS = ["Primary Request", "Files and Code", "Errors and Fixes", "Pending Jobs", "Current Work", "Next Step", "Critical Context", "Corrections"];
+
+/** Tools whose calls are file operations (Read included: it is context worth re-reading). */
+const FILE_TOOLS = new Set(["Read", "Edit", "Write", "MultiEdit", "NotebookEdit"]);
+
+/** Transcript scan cap (bytes). */
+const MAX_TRANSCRIPT_BYTES = 64 * 1024 * 1024;
+
+/** Per-line and per-section caps so the skeleton stays a checkpoint, not a transcript copy. */
+const MAX_LINE_CHARS = 400;
+const MAX_ITEMS = 12;
+const MAX_BODY_CHARS = 1500;
+
+/** Worker request timeout (ms): a PreCompact hook must never hold the compaction. */
+const WORKER_TIMEOUT_MS = 2000;
+
+/** Error markers (case-insensitive) that make a tool result an "Errors and Fixes" line. */
+const ERROR_RE = /\b(error|ENOENT|EACCES|EEXIST|failed|failure|Traceback|exception|not found|permission denied|cannot|exit code [1-9])\b/i;
+
+/** User turns that read as a correction of the assistant. */
+const CORRECTION_RE = /^(no[,.! ]|not (that|this|what)|wrong|don'?t |do not |stop |instead[, ]|that'?s (not|wrong)|actually[, ]|undo|revert|never )/i;
+
+/**
+ * State directory (FREEHARNESS_STATE_DIR overrides).
+ * @returns {string} Absolute path.
+ */
+export 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.
+ * @param {string} id Session id.
+ * @returns {string} Safe name.
+ */
+function safeId(id) {
+  return String(id || "").replace(/[^\w.-]/g, "_") || "unknown";
+}
+
+/**
+ * Trims a string to one line of at most MAX_LINE_CHARS, marking the cut.
+ * @param {string} s Text.
+ * @param {number} [max] Cap.
+ * @returns {string} One line.
+ */
+function oneLine(s, max = MAX_LINE_CHARS) {
+  const t = String(s).replace(/\s+/g, " ").trim();
+  return t.length > max ? `${t.slice(0, max)} …[+${t.length - max} chars]` : t;
+}
+
+/**
+ * Caps a multi-line body, keeping the head.
+ * @param {string} s Text.
+ * @returns {string} Body.
+ */
+function capBody(s) {
+  const t = String(s).trim();
+  return t.length > MAX_BODY_CHARS ? `${t.slice(0, MAX_BODY_CHARS)}\n…[+${t.length - MAX_BODY_CHARS} chars]` : t;
+}
+
+/**
+ * Text of a message content (string or text blocks), tool results excluded.
+ * @param {unknown} content Message content.
+ * @returns {string} Joined text.
+ */
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((b) => b && b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text)
+    .join("\n");
+}
+
+/**
+ * True for user turns that are not real prompts (system reminders, slash-command echoes,
+ * tool results, interruption notices).
+ * @param {string} text User text.
+ * @returns {boolean} Skip it.
+ */
+function isMetaUserText(text) {
+  const t = text.trim();
+  return !t || t.startsWith("<") || t.startsWith("[Request interrupted") || /^Caveat: The messages below/.test(t);
+}
+
+/**
+ * Text of a tool_result block (string or nested text blocks).
+ * @param {any} block tool_result block.
+ * @returns {string} Text.
+ */
+function toolResultText(block) {
+  if (typeof block.content === "string") return block.content;
+  if (Array.isArray(block.content)) return textOf(block.content);
+  return "";
+}
+
+/**
+ * Parses the transcript into the facts the skeleton needs.
+ * @param {string} transcript Transcript path (JSONL).
+ * @returns {{users:string[], assistants:string[], fileOps:{path:string,tool:string,count:number}[], errors:string[], cwds:Set<string>, branches:Set<string>} | null}
+ *   Facts, or null when the transcript is unreadable or oversized.
+ */
+export function parseTranscript(transcript) {
+  let text;
+  try {
+    if (!transcript || fs.statSync(transcript).size > MAX_TRANSCRIPT_BYTES) return null;
+    text = fs.readFileSync(transcript, "utf8");
+  } catch {
+    return null;
+  }
+  const users = [];
+  const assistants = [];
+  const errors = [];
+  const cwds = new Set();
+  const branches = new Set();
+  const ops = new Map(); // path -> Map(tool -> count)
+  const toolNames = new Map(); // tool_use id -> name
+  for (const raw of text.split("\n")) {
+    if (!raw.trim()) continue;
+    let rec;
+    try {
+      rec = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!rec || typeof rec !== "object") continue;
+    if (typeof rec.cwd === "string" && rec.cwd) cwds.add(rec.cwd);
+    if (typeof rec.gitBranch === "string" && rec.gitBranch) branches.add(rec.gitBranch);
+    const msg = rec.message;
+    if (!msg || typeof msg !== "object") continue;
+    const role = rec.type === "user" || rec.type === "assistant" ? rec.type : msg.role;
+    const content = Array.isArray(msg.content) ? msg.content : [];
+    if (role === "assistant") {
+      const t = textOf(msg.content);
+      if (t.trim()) assistants.push(t);
+      for (const block of content) {
+        if (!block || block.type !== "tool_use") continue;
+        if (typeof block.id === "string") toolNames.set(block.id, block.name);
+        if (!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 = ops.get(file) || new Map();
+        per.set(block.name, (per.get(block.name) || 0) + 1);
+        ops.set(file, per);
+      }
+    } else if (role === "user") {
+      const t = textOf(msg.content);
+      if (!isMetaUserText(t)) users.push(t);
+      for (const block of content) {
+        if (!block || block.type !== "tool_result") continue;
+        const body = toolResultText(block);
+        if (!(block.is_error === true || ERROR_RE.test(body))) continue;
+        const line = body.split("\n").map((l) => l.trim()).find((l) => l && (block.is_error === true || ERROR_RE.test(l))) || body;
+        const tool = toolNames.get(block.tool_use_id);
+        errors.push(`${tool ? `${tool}: ` : ""}${oneLine(line)}`);
+      }
+    }
+  }
+  const fileOps = [];
+  for (const [p, per] of ops) for (const [tool, count] of per) fileOps.push({ path: p, tool, count });
+  return { users, assistants, fileOps, errors, cwds, branches };
+}
+
+/**
+ * Renders the eight-section skeleton from transcript facts.
+ * @param {ReturnType<typeof parseTranscript>} facts Facts (null = unreadable transcript).
+ * @param {Record<string, any>} payload Hook payload.
+ * @returns {string} Markdown with one `## <Section>` heading per section.
+ */
+export function renderSkeleton(facts, payload) {
+  const body = {};
+  const f = facts || { users: [], assistants: [], fileOps: [], errors: [], cwds: new Set(), branches: new Set() };
+  const dedupe = (arr) => [...new Set(arr)];
+
+  body["Primary Request"] = f.users.length ? capBody(f.users[0]) : "";
+  body["Files and Code"] = f.fileOps.length
+    ? f.fileOps.slice(0, MAX_ITEMS * 3).map((o) => `- ${o.path} (${o.tool} x${o.count})`).join("\n")
+    : "";
+  body["Errors and Fixes"] = f.errors.length ? dedupe(f.errors).slice(-MAX_ITEMS).map((e) => `- ${e}`).join("\n") : "";
+  // Unchecked task lines the assistant listed most recently, if any.
+  const pending = [];
+  for (const a of f.assistants.slice(-3)) for (const l of a.split("\n")) if (/^\s*- \[ \]/.test(l)) pending.push(oneLine(l));
+  body["Pending Jobs"] = pending.length ? dedupe(pending).slice(0, MAX_ITEMS).join("\n") : "";
+  body["Current Work"] = f.assistants.length ? capBody(f.assistants[f.assistants.length - 1]) : "";
+  body["Next Step"] = f.users.length > 1 ? `Latest instruction from the user (verbatim):\n${capBody(f.users[f.users.length - 1])}` : "";
+  const critical = [];
+  if (typeof payload.cwd === "string" && payload.cwd) critical.push(`cwd: ${payload.cwd}`);
+  for (const b of f.branches) critical.push(`git branch: ${b}`);
+  if (typeof payload.trigger === "string") critical.push(`compaction trigger: ${payload.trigger}`);
+  if (typeof payload.custom_instructions === "string" && payload.custom_instructions.trim()) critical.push(`compact instructions: ${oneLine(payload.custom_instructions)}`);
+  body["Critical Context"] = critical.join("\n");
+  body["Corrections"] = dedupe(f.users.filter((u) => CORRECTION_RE.test(u.trim())).map((u) => `- ${oneLine(u)}`)).slice(-MAX_ITEMS).join("\n");
+
+  const lines = [`<!-- freeharness-precompact ${new Date().toISOString()} session=${safeId(payload.session_id)} -->`];
+  for (const s of SECTIONS) {
+    lines.push(`## ${s}`);
+    lines.push(body[s] && body[s].trim() ? body[s] : "(none)");
+    lines.push("");
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+/**
+ * Mirrors the engine's data-dir resolution: CLAUDE_MEM_DATA_DIR, settings.json, ~/.claude-mem.
+ * @returns {string} Absolute path.
+ */
+export function memDataDir() {
+  const expand = (p) => (p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
+  if (process.env.CLAUDE_MEM_DATA_DIR) return expand(process.env.CLAUDE_MEM_DATA_DIR);
+  const def = path.join(os.homedir(), ".claude-mem");
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(def, "settings.json"), "utf8"));
+    const s = (raw && raw.env) || raw || {};
+    if (typeof s.CLAUDE_MEM_DATA_DIR === "string") return expand(s.CLAUDE_MEM_DATA_DIR);
+  } catch {
+    // default
+  }
+  return def;
+}
+
+/**
+ * Mirrors the engine's worker port: CLAUDE_MEM_WORKER_PORT (env, then settings.json), else 37700 + uid % 100.
+ * @returns {number} Port.
+ */
+export function workerPort() {
+  const fromEnv = Number.parseInt(process.env.CLAUDE_MEM_WORKER_PORT || "", 10);
+  if (Number.isFinite(fromEnv) && fromEnv > 0) return fromEnv;
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(memDataDir(), "settings.json"), "utf8"));
+    const s = (raw && raw.env) || raw || {};
+    const p = Number.parseInt(String(s.CLAUDE_MEM_WORKER_PORT || ""), 10);
+    if (Number.isFinite(p) && p > 0) return p;
+  } catch {
+    // default
+  }
+  return 37700 + (((typeof process.getuid === "function" ? process.getuid() : 77) || 0) % 100);
+}
+
+/**
+ * Asks the worker to queue a session summary (the Stop hook's route). Best effort.
+ * @param {string} sessionId Content session id.
+ * @param {string} lastAssistant Last assistant text (may be empty).
+ * @returns {Promise<"queued"|"skipped"|"down">} Outcome.
+ */
+export async function requestSummary(sessionId, lastAssistant) {
+  if ((process.env.FREEHARNESS_PRECOMPACT_WORKER || "").toLowerCase() === "off") return "skipped";
+  const url = `http://127.0.0.1:${workerPort()}/api/sessions/summarize`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ contentSessionId: sessionId, last_assistant_message: lastAssistant, platformSource: "claude-code" }),
+      signal: AbortSignal.timeout(WORKER_TIMEOUT_MS),
+    });
+    return res.ok ? "queued" : "down";
+  } catch {
+    return "down";
+  }
+}
+
+/**
+ * Runs the hook for one payload: writes the skeleton + file-op list, pings the worker.
+ * @param {Record<string, any>} payload Hook payload.
+ * @returns {Promise<{summary:string, fileops:string, worker:string}>} Paths written and the worker outcome.
+ */
+export async function respond(payload) {
+  const sessionId = typeof payload.session_id === "string" && payload.session_id ? payload.session_id : "unknown";
+  const facts = parseTranscript(typeof payload.transcript_path === "string" ? payload.transcript_path : "");
+  const dir = stateDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const summary = path.join(dir, `${safeId(sessionId)}.precompact.md`);
+  const fileops = path.join(dir, `${safeId(sessionId)}.fileops.json`);
+  fs.writeFileSync(summary, renderSkeleton(facts, payload), "utf8");
+  fs.writeFileSync(fileops, `${JSON.stringify(facts ? facts.fileOps : [])}\n`, "utf8");
+  const lastAssistant = facts && facts.assistants.length ? facts.assistants[facts.assistants.length - 1] : "";
+  const worker = await requestSummary(sessionId, lastAssistant);
+  return { summary, fileops, worker };
+}
+
+/** Entry point: read stdin, write the artifacts, stay silent, exit 0. */
+async function main() {
+  if ((process.env.FREEHARNESS_HOOK_PRECOMPACT || "").toLowerCase() === "off") return;
+  let payload = {};
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    if (raw.trim()) payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (!payload || typeof payload !== "object") return;
+  try {
+    const r = await respond(payload);
+    if (process.env.FREEHARNESS_PRECOMPACT_VERBOSE === "1") process.stderr.write(`freeharness-precompact: ${r.summary} worker=${r.worker}\n`);
+  } catch (e) {
+    process.stderr.write(`freeharness-precompact: ${e instanceof Error ? e.message : String(e)}\n`);
+  }
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  main().finally(() => process.exit(0));
+}

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

@@ -0,0 +1,208 @@
+// FreeHarness repeat-tool reminder (Claude Code PreToolUse hook on every tool, plus
+// UserPromptSubmit as the reset). Rewritten from the dsh repeat-tool-reminder guard (MIT).
+// Each call is keyed by sha256(tool + key-sorted JSON of its input); the per-session ring
+// file ~/.claude/freeharness/state/<session>.json holds the last key and its run length.
+// Counting happens before execution, so a call the config guard denies still counts (a model
+// hammering a denied call is the loop worth breaking). At --thresholds 3,5,8 consecutive
+// identical calls the hook returns an additionalContext reminder: short at the first
+// threshold, detailed (tool, run length, argument preview capped by --preview-chars) at
+// the later ones. Advisory only: no permissionDecision. A new user prompt clears the ring
+// (a repeat across a user message is not a loop); a missing or corrupt ring starts a fresh
+// chain. Thresholds are validated at load (integers >= 2, strictly ascending, no
+// duplicates); an invalid list is reported on stderr and the defaults apply, never a block.
+// Disable: FREEHARNESS_HOOK_REPEAT_TOOL=off.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Defaults; the fragment overrides them with --thresholds / --preview-chars. */
+export const DEFAULTS = Object.freeze({ thresholds: [3, 5, 8], previewChars: 500 });
+
+/**
+ * Validates a threshold list: integers >= 2, strictly ascending, no duplicates.
+ * @param {number[]} values Candidate list.
+ * @returns {string | null} The rule violated, or null when valid.
+ */
+export function validateThresholds(values) {
+  if (!Array.isArray(values) || values.length === 0) return "thresholds must not be empty";
+  for (const v of values) if (!Number.isInteger(v) || v < 2) return `threshold ${v} is not an integer >= 2`;
+  for (let i = 1; i < values.length; i++) if (values[i] <= values[i - 1]) return `thresholds must be strictly ascending (${values[i - 1]} then ${values[i]})`;
+  return null;
+}
+
+/**
+ * Parses --thresholds (comma list) and --preview-chars; invalid values fall back to the
+ * defaults with a stderr line naming the rule.
+ * @param {string[]} argv Arguments after the script path.
+ * @returns {{thresholds:number[], previewChars:number, error?:string}} Options.
+ */
+export function parseOptions(argv) {
+  const opts = { thresholds: [...DEFAULTS.thresholds], previewChars: DEFAULTS.previewChars };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--thresholds") {
+      const raw = String(argv[++i] ?? "");
+      const list = raw.split(",").map((s) => (s.trim() === "" ? NaN : Number(s.trim())));
+      const err = validateThresholds(list);
+      if (err) opts.error = `freeharness-repeat-tool: invalid thresholds "${raw}": ${err}; using ${DEFAULTS.thresholds.join(",")}`;
+      else opts.thresholds = list;
+    } else if (argv[i] === "--preview-chars") {
+      const n = Number.parseInt(argv[++i], 10);
+      if (Number.isInteger(n) && n >= 1) opts.previewChars = n;
+    }
+  }
+  return opts;
+}
+
+/**
+ * Deep key-sort so two inputs that differ only in property order canonicalize identically.
+ * @param {unknown} value Parsed JSON value.
+ * @returns {unknown} Sorted copy.
+ */
+export function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const k of Object.keys(value).sort()) out[k] = sortKeys(value[k]);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Canonical string of a call's input.
+ * @param {unknown} input Tool input.
+ * @returns {string} JSON with sorted keys.
+ */
+export function canonical(input) {
+  return JSON.stringify(sortKeys(input ?? {}));
+}
+
+/**
+ * Call identity: sha256 over the tool name and its canonical input.
+ * @param {string} tool Tool name.
+ * @param {string} canon Canonical input.
+ * @returns {string} Hex digest.
+ */
+export function callKey(tool, canon) {
+  return crypto.createHash("sha256").update(tool).update("\0").update(canon).digest("hex");
+}
+
+/**
+ * Resolves the ring file of a session.
+ * @param {string} sessionId Session id.
+ * @returns {string} Absolute path.
+ */
+export function ringFile(sessionId) {
+  const dir = process.env.FREEHARNESS_STATE_DIR || path.join(os.homedir(), ".claude", "freeharness", "state");
+  return path.join(dir, `${sessionId.replace(/[^\w.-]/g, "_") || "unknown"}.json`);
+}
+
+/**
+ * Reads the ring; a missing or corrupt file is a fresh chain.
+ * @param {string} file Ring path.
+ * @returns {{key:string, count:number}} Chain state.
+ */
+function readRing(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (parsed && typeof parsed.key === "string" && Number.isInteger(parsed.count) && parsed.count >= 0) return { key: parsed.key, count: parsed.count };
+  } catch {
+    // fresh
+  }
+  return { key: "", count: 0 };
+}
+
+/**
+ * Writes the ring.
+ * @param {string} file Ring path.
+ * @param {{key:string, count:number}} ring State.
+ */
+function writeRing(file, ring) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ ...ring, updated: new Date().toISOString() }), "utf8");
+}
+
+/**
+ * Head-truncates the canonical input for the detailed reminder.
+ * @param {string} canon Canonical input.
+ * @param {number} cap Character cap.
+ * @returns {string} Preview.
+ */
+function preview(canon, cap) {
+  return canon.length <= cap ? canon : `${canon.slice(0, cap)}… (+${canon.length - cap} more chars)`;
+}
+
+/**
+ * Reminder text for a run length that hit a threshold.
+ * @param {string} tool Tool name.
+ * @param {number} count Run length.
+ * @param {string} canon Canonical input.
+ * @param {{thresholds:number[], previewChars:number}} opts Options.
+ * @returns {string} Reminder.
+ */
+export function reminder(tool, count, canon, opts) {
+  if (count === opts.thresholds[0]) {
+    return `FreeHarness: same ${tool} call with identical arguments ${count} times in a row. Analyze the previous result before calling again; if the task is not complete, change the approach or the arguments.`;
+  }
+  return [
+    "FreeHarness: repeated tool call detected.",
+    `- tool: ${tool}`,
+    `- consecutive_calls: ${count}`,
+    `- arguments: ${preview(canon, opts.previewChars)}`,
+    "The repeated calls are not making progress. Do not call this tool with these exact arguments again: inspect the latest result, choose a different action or different arguments, or finish the task if enough evidence has been gathered.",
+  ].join("\n");
+}
+
+/**
+ * Advances the chain for one PreToolUse payload and returns the reminder response, or
+ * null; clears the chain for a UserPromptSubmit payload.
+ * @param {Record<string, any>} payload Parsed hook payload.
+ * @param {{thresholds:number[], previewChars:number}} opts Options.
+ * @returns {Record<string, unknown> | null} JSON to print, or null.
+ */
+export function respond(payload, opts) {
+  const sessionId = typeof payload.session_id === "string" && payload.session_id ? payload.session_id : "unknown";
+  const file = ringFile(sessionId);
+  const event = String(payload.hook_event_name || (payload.prompt !== undefined ? "UserPromptSubmit" : "PreToolUse"));
+  if (event === "UserPromptSubmit") {
+    writeRing(file, { key: "", count: 0 });
+    return null;
+  }
+  const tool = String(payload.tool_name || "");
+  if (!tool) return null;
+  const canon = canonical(payload.tool_input);
+  const key = callKey(tool, canon);
+  const ring = readRing(file);
+  const count = ring.key === key ? ring.count + 1 : 1;
+  writeRing(file, { key, count });
+  if (!opts.thresholds.includes(count)) return null;
+  return { hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: reminder(tool, count, canon, opts) } };
+}
+
+/** Entry point: read stdin, respond or stay silent, exit 0. */
+function main() {
+  if ((process.env.FREEHARNESS_HOOK_REPEAT_TOOL || "").toLowerCase() === "off") return;
+  const opts = parseOptions(process.argv.slice(2));
+  if (opts.error) process.stderr.write(`${opts.error}\n`);
+  let payload = {};
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    if (raw.trim()) payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (!payload || typeof payload !== "object") return;
+  try {
+    const out = respond(payload, opts);
+    if (out) process.stdout.write(JSON.stringify(out));
+  } catch (e) {
+    process.stderr.write(`freeharness-repeat-tool: ${e instanceof Error ? e.message : String(e)}\n`);
+  }
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  main();
+  process.exit(0);
+}