freeharness 0.4.1

package/canonical/hooks/cost-prices.json

@@ -0,0 +1,14 @@
+{
+  "$comment": "FreeHarness cost-tracker price table. USD per million tokens (MTok) per model, columns: input, output, cache_read, cache_write, window (the model's standard token window; the tracker resolves 1,000,000 for a `[1m]` model-id suffix regardless of this field). PLACEHOLDERS: the numbers below are public list prices as of the file date and are NOT authoritative for your account — EDIT TO YOUR CONTRACT. The hook resolves a model by exact name, then by the longest key the model name starts with (claude-sonnet-4-5-20250929 -> claude-sonnet-4-5 -> claude-sonnet-4), then `default`. Re-running `freeharness init` never overwrites this file once it exists.",
+  "currency": "USD",
+  "unit": "per_million_tokens",
+  "prices": {
+    "claude-opus-4-1": { "input": 15, "output": 75, "cache_read": 1.5, "cache_write": 18.75, "window": 200000 },
+    "claude-opus-4": { "input": 15, "output": 75, "cache_read": 1.5, "cache_write": 18.75, "window": 200000 },
+    "claude-sonnet-4-5": { "input": 3, "output": 15, "cache_read": 0.3, "cache_write": 3.75, "window": 200000 },
+    "claude-sonnet-4": { "input": 3, "output": 15, "cache_read": 0.3, "cache_write": 3.75, "window": 200000 },
+    "claude-haiku-4-5": { "input": 1, "output": 5, "cache_read": 0.1, "cache_write": 1.25, "window": 200000 },
+    "claude-3-5-haiku": { "input": 0.8, "output": 4, "cache_read": 0.08, "cache_write": 1, "window": 200000 },
+    "default": { "input": 3, "output": 15, "cache_read": 0.3, "cache_write": 3.75, "window": 200000 }
+  }
+}

package/canonical/hooks/freeharness-auto-memory.mjs

@@ -0,0 +1,158 @@
+// FreeHarness auto-memory tier-0 spike (Claude Code SessionEnd hook). OFF BY DEFAULT.
+// When FREEHARNESS_AUTO_MEMORY=on, the session's last project telemetry record
+// (<cwd>/.freeharness/telemetry.jsonl, last valid JSON line) is curated into
+// ~/.claude/freeharness/MEMORY.md as ONE line per project (`- <project>: <change> <task>
+// <tier>: main <N>k, subagents <N>k, observer <N>k|n/a`): a re-run with the same record
+// changes nothing; a newer record replaces the project's line. Nothing else is written;
+// the free-mem plugin stays the memory of record. Never blocks, never prints, exit 0 on every path.
+// File override: FREEHARNESS_AUTO_MEMORY_FILE.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Header of the curated file. */
+export const HEADER = "# FreeHarness auto-memory (tier-0 spike; one line per project from the telemetry log)";
+
+/**
+ * True when the spike is switched on.
+ * @param {NodeJS.ProcessEnv} env Environment.
+ * @returns {boolean} Enabled.
+ */
+export function enabled(env = process.env) {
+  return String(env.FREEHARNESS_AUTO_MEMORY || "").trim().toLowerCase() === "on";
+}
+
+/**
+ * The curated file path.
+ * @returns {string} Absolute path.
+ */
+export function memoryFile() {
+  return process.env.FREEHARNESS_AUTO_MEMORY_FILE || path.join(os.homedir(), ".claude", "freeharness", "MEMORY.md");
+}
+
+/** `<N>k`, non-finite treated as 0. */
+function kTokens(n) {
+  const v = Number.isFinite(n) ? Number(n) : 0;
+  return `${Math.round(v / 1000)}k`;
+}
+
+/**
+ * Renders a telemetry tag defensively: caps at 64 characters, keeps only `[\w.\-/ ,()]` (no
+ * control characters, no embedded newline that could split the one curated line per project).
+ * The producer already sanitizes at write time; this is a second pass against a tampered or
+ * pre-fix telemetry line.
+ * @param {unknown} s Raw field value.
+ * @returns {string} Sanitized value ("" for a non-string).
+ */
+function sanitizeTag(s) {
+  return typeof s === "string" ? s.trim().replace(/[^\w.\-/ ,()]/g, "").slice(0, 64).trim() : "";
+}
+
+/**
+ * One telemetry record rendered as a curated line: `<change or untagged> <task or -> <tier or
+ * ->: main <N>k, subagents <N>k, observer <N>k|n/a`.
+ * @param {Record<string, any>} rec Parsed telemetry.jsonl record.
+ * @returns {string} Formatted line.
+ */
+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 valid record of a project's telemetry file, rendered as a curated line.
+ * @param {string} project Project root.
+ * @returns {string | null} The line, or null when the file is absent or carries no valid record.
+ */
+export function lastTelemetryLine(project) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(project, ".freeharness", "telemetry.jsonl"), "utf8");
+  } catch {
+    return null;
+  }
+  let last = null;
+  for (const raw of text.split("\n")) {
+    if (!raw.trim()) continue;
+    try {
+      const rec = JSON.parse(raw);
+      if (rec && typeof rec === "object") last = rec;
+    } catch {
+      // skip malformed lines
+    }
+  }
+  return last ? telemetryLine(last) : null;
+}
+
+/**
+ * Upserts one project line into the curated text (idempotent).
+ * @param {string} text Current file text (may be empty).
+ * @param {string} project Project name (basename of cwd).
+ * @param {string} line Formatted telemetry line.
+ * @returns {{text:string, changed:boolean}} New text and whether it differs.
+ */
+export function upsert(text, project, line) {
+  const entry = `- ${project}: ${line}`;
+  // The file is FreeHarness-owned: header + one `- <project>: ...` line per project.
+  const entries = (text || "").split("\n").filter((l) => l.startsWith("- "));
+  const idx = entries.findIndex((l) => l.startsWith(`- ${project}: `));
+  if (idx >= 0) entries[idx] = entry;
+  else entries.push(entry);
+  const next = `${HEADER}\n\n${entries.join("\n")}\n`;
+  return { text: next, changed: next !== text };
+}
+
+/**
+ * Runs the hook for one payload.
+ * @param {Record<string, any>} payload Hook payload.
+ * @returns {{changed:boolean, file:string} | null} What happened, or null when nothing applied.
+ */
+export function respond(payload) {
+  const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+  const line = lastTelemetryLine(cwd);
+  if (!line) return null;
+  const file = memoryFile();
+  let current = "";
+  try {
+    current = fs.readFileSync(file, "utf8");
+  } catch {
+    // first write
+  }
+  const r = upsert(current, path.basename(cwd), line);
+  if (r.changed) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, r.text, "utf8");
+  }
+  return { changed: r.changed, file };
+}
+
+/** Entry point: flag-gated, read stdin, curate, stay silent, exit 0. */
+function main() {
+  if (!enabled()) 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 {
+    respond(payload);
+  } catch (e) {
+    process.stderr.write(`freeharness-auto-memory: ${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);
+}

package/canonical/hooks/freeharness-config-guard.mjs

@@ -0,0 +1,162 @@
+// FreeHarness config guard (Claude Code PreToolUse hook, matcher Edit|Write|MultiEdit|Bash).
+// Denies writes to the files that invalidate the prompt cache or change the harness under
+// the session (settings.json, settings.local.json, .mcp.json, CLAUDE.md, hook scripts and
+// the plugin hooks.json) unless an allow marker exists and is fresh:
+//   <project>/.freeharness/allow-config-edit   (or ~/.claude/freeharness/allow-config-edit)
+// The marker is valid for --ttl minutes (30) after its mtime; a numeric (epoch ms) or ISO
+// date body sets an explicit expiry instead. `touch .freeharness/allow-config-edit` in a
+// terminal sets or refreshes it; `freeharness init`/`update` set and remove their own.
+// Bash is denied only when the command writes to such a path (redirect, sed -i, rm, mv, cp,
+// tee, truncate, touch); reads pass. The marker itself is protected from tool writes, so
+// the user, not the model, opens the window. Never throws; exit 0 on every path.
+// Disable: FREEHARNESS_HOOK_CONFIG_GUARD=off.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Marker file name (project: .freeharness/, user: ~/.claude/freeharness/). */
+export const MARKER = "allow-config-edit";
+/** Default marker lifetime in minutes. */
+export const DEFAULT_TTL_MIN = 30;
+
+/** Protected basenames. */
+const NAMES = /^(settings\.json|settings\.local\.json|\.mcp\.json|CLAUDE\.md|hooks\.json)$/i;
+/** Protected directories (hook scripts) and the marker. */
+const DIRS = /\/(\.freeharness\/hooks|\.claude\/freeharness\/hooks|\.claude\/hooks|freeharness-plugin\/hooks)\/[^/]+$|\/\.freeharness\/allow-config-edit$|\/\.claude\/freeharness\/allow-config-edit$/;
+/** Same set as a token pattern for Bash commands (relative spellings included). */
+const TOKEN = /(?:^|[\s"'=:/])((?:[\w.~-]+\/)*(?:settings\.json|settings\.local\.json|\.mcp\.json|CLAUDE\.md|hooks\.json|allow-config-edit|(?:\.freeharness|\.claude\/freeharness|\.claude)\/hooks\/[\w.-]+|freeharness-[\w-]+\.mjs|freeharness-session-start))(?=$|[\s"';|&)])/g;
+/** Write constructs a Bash command may apply to a protected token. */
+const WRITERS = /(^|[\s;|&(])(sed\s+(-[a-zA-Z]*i|--in-place)|rm|mv|cp|tee|truncate|touch|install|ln|dd|shred|python3?\s+-c|perl\s+-[a-z]*i)\b|>{1,2}\s*["']?(?:[\w.~-]+\/)*(?:settings\.json|settings\.local\.json|\.mcp\.json|CLAUDE\.md|hooks\.json|allow-config-edit|freeharness-[\w-]+\.mjs|freeharness-session-start)/;
+
+/**
+ * Parses --ttl (minutes).
+ * @param {string[]} argv Arguments after the script path.
+ * @returns {{ttlMin:number}} Options.
+ */
+export function parseOptions(argv) {
+  const opts = { ttlMin: DEFAULT_TTL_MIN };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--ttl") {
+      const n = Number.parseInt(argv[++i], 10);
+      if (Number.isInteger(n) && n > 0) opts.ttlMin = n;
+    }
+  }
+  return opts;
+}
+
+/**
+ * Whether an absolute file path is protected.
+ * @param {string} file Path (any separator).
+ * @returns {boolean} True when protected.
+ */
+export function isProtectedPath(file) {
+  const p = String(file).replace(/\\/g, "/");
+  if (/\/node_modules\//.test(p)) return false;
+  const base = p.split("/").pop() || "";
+  return NAMES.test(base) || DIRS.test(p);
+}
+
+/**
+ * Protected paths a Bash command writes to (empty when it only reads them).
+ * @param {string} command The command.
+ * @returns {string[]} Matched tokens.
+ */
+export function bashTargets(command) {
+  const tokens = [...command.matchAll(TOKEN)].map((m) => m[1]).filter((t) => !/\/node_modules\//.test(t));
+  if (tokens.length === 0) return [];
+  return WRITERS.test(command) ? [...new Set(tokens)] : [];
+}
+
+/**
+ * Whether a marker file is present and unexpired.
+ * @param {string} file Marker path.
+ * @param {number} ttlMin Default lifetime from mtime, in minutes.
+ * @param {number} now Reference time (ms).
+ * @returns {"valid" | "expired" | "absent"} State.
+ */
+export function markerState(file, ttlMin, now = Date.now()) {
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    return "absent";
+  }
+  let expires = stat.mtimeMs + ttlMin * 60_000;
+  try {
+    const body = fs.readFileSync(file, "utf8").trim();
+    if (/^\d{10,}$/.test(body)) expires = Number(body);
+    else if (body && !Number.isNaN(Date.parse(body))) expires = Date.parse(body);
+  } catch {
+    // mtime rule
+  }
+  return now < expires ? "valid" : "expired";
+}
+
+/**
+ * Candidate marker paths for a payload: project first, then user.
+ * @param {Record<string, any>} payload Hook payload.
+ * @returns {string[]} Absolute paths.
+ */
+export function markerPaths(payload) {
+  const project = process.env.CLAUDE_PROJECT_DIR || (typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd());
+  return [path.join(project, ".freeharness", MARKER), path.join(os.homedir(), ".claude", "freeharness", MARKER)];
+}
+
+/**
+ * Builds the deny response for a PreToolUse payload, or null to allow.
+ * @param {Record<string, any>} payload Parsed hook payload.
+ * @param {{ttlMin:number}} opts Options.
+ * @returns {Record<string, unknown> | null} JSON to print, or null.
+ */
+export function respond(payload, opts) {
+  const tool = String(payload.tool_name || "");
+  const input = payload.tool_input && typeof payload.tool_input === "object" ? payload.tool_input : {};
+  let targets = [];
+  if (/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(tool)) {
+    const file = input.file_path || input.notebook_path || input.path || "";
+    if (file && isProtectedPath(String(file))) targets = [String(file)];
+  } else if (tool === "Bash") {
+    targets = bashTargets(typeof input.command === "string" ? input.command : "");
+  }
+  if (targets.length === 0) return null;
+  const markers = markerPaths(payload);
+  const states = markers.map((m) => markerState(m, opts.ttlMin));
+  if (states.includes("valid")) return null;
+  const expired = states.findIndex((s) => s === "expired");
+  const why = expired >= 0 ? `marker expired: ${markers[expired]}` : `no marker at ${markers[0]}`;
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason:
+        `FreeHarness config guard: ${targets.join(", ")} is harness configuration (cache invalidator: settings, MCP, hooks, CLAUDE.md); ${why}. ` +
+        `Ask the user to open a ${opts.ttlMin}-minute window from a terminal: \`mkdir -p .freeharness && touch .freeharness/${MARKER}\` (project) or \`touch ~/.claude/freeharness/${MARKER}\` (user), then retry. ` +
+        "Do not create the marker yourself, and do not route the edit through another tool.",
+    },
+  };
+}
+
+/** Entry point: read stdin, deny or stay silent, exit 0. */
+function main() {
+  if ((process.env.FREEHARNESS_HOOK_CONFIG_GUARD || "").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 out = respond(payload, parseOptions(process.argv.slice(2)));
+    if (out) process.stdout.write(JSON.stringify(out));
+  } catch (e) {
+    process.stderr.write(`freeharness-config-guard: ${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);
+}

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

@@ -0,0 +1,198 @@
+// FreeHarness context monitor (Claude Code Stop hook).
+// Reads the latest cost snapshot of the session (usage.jsonl, written by the cost tracker) and,
+// when the context crosses 60% and then 85% of its token window, prints one advisory line as a
+// `systemMessage` (shown to the user, never to the model: a Stop `additionalContext` would force
+// another turn). Re-arm and window fallback: see `crossed` and `respond` below.
+// Never blocks; exit 0 on every path. Disable: FREEHARNESS_HOOK_CONTEXT_MONITOR=off.
+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 --budget / --thresholds. */
+export const DEFAULTS = Object.freeze({ budget: 200_000, thresholds: [60, 85] });
+
+/**
+ * Parses --budget and --thresholds (percentages, ascending).
+ * @param {string[]} argv Arguments after the script path.
+ * @returns {{budget:number, thresholds:number[]}} Options.
+ */
+export function parseOptions(argv) {
+  const opts = { budget: DEFAULTS.budget, thresholds: [...DEFAULTS.thresholds] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--budget") {
+      const n = Number.parseInt(argv[++i], 10);
+      if (Number.isInteger(n) && n > 0) opts.budget = n;
+    } else if (argv[i] === "--thresholds") {
+      const list = String(argv[++i] ?? "")
+        .split(",")
+        .map((s) => Number.parseInt(s.trim(), 10))
+        .filter((n) => Number.isInteger(n) && n > 0 && n <= 100);
+      if (list.length > 0) opts.thresholds = list.sort((a, b) => a - b);
+    }
+  }
+  return opts;
+}
+
+/**
+ * Resolves the state file of a session.
+ * @param {string} sessionId Session id.
+ * @returns {string} Absolute path.
+ */
+function stateFile(sessionId) {
+  const dir = process.env.FREEHARNESS_STATE_DIR || path.join(os.homedir(), ".claude", "freeharness", "state");
+  return path.join(dir, `${sessionId.replace(/[^\w.-]/g, "_") || "unknown"}.context.json`);
+}
+
+/**
+ * Latest context size and token window recorded for the session in the cost log.
+ * @param {string} sessionId Session id.
+ * @returns {{tokens: number, window: number} | null} Tokens and window (default 200,000 when the
+ *   snapshot lacks `context_window`), or null when no snapshot carries `context_tokens`.
+ */
+export 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 lines
+    }
+  }
+  return best;
+}
+
+/**
+ * Context size from the transcript: the last assistant message's input + cache tokens.
+ * @param {string} transcript Transcript path.
+ * @returns {number | null} Tokens, or null when unreadable.
+ */
+export function contextFromTranscript(transcript) {
+  let text;
+  try {
+    text = fs.readFileSync(transcript, "utf8");
+  } catch {
+    return null;
+  }
+  let last = null;
+  for (const raw of text.split("\n")) {
+    if (!raw.includes('"usage"')) continue;
+    try {
+      const rec = JSON.parse(raw);
+      const u = rec && rec.message && rec.message.usage;
+      if (u && typeof u === "object") last = (Number(u.input_tokens) || 0) + (Number(u.cache_read_input_tokens) || 0) + (Number(u.cache_creation_input_tokens) || 0);
+    } catch {
+      // skip
+    }
+  }
+  return last;
+}
+
+/**
+ * Decides which threshold (if any) to announce against the given window, records it, and
+ * re-arms (clears the announced set, bumps the epoch) once the context drops back below the
+ * lowest threshold, so a later climb announces both thresholds again.
+ * @param {number} tokens Current context tokens.
+ * @param {number} window Token window the percentage is computed against.
+ * @param {{budget:number, thresholds:number[]}} opts Options (thresholds only; budget is the
+ *   caller's fallback window, not used here).
+ * @param {string} file State file.
+ * @returns {number | null} The percentage to announce, or null.
+ */
+export function crossed(tokens, window, opts, file) {
+  let state = { announced: [], epoch: 0 };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (parsed && Array.isArray(parsed.announced)) state = { announced: parsed.announced, epoch: Number.isInteger(parsed.epoch) ? parsed.epoch : 0 };
+  } catch {
+    // fresh state
+  }
+  const pct = (tokens / window) * 100;
+  const lowest = opts.thresholds[0];
+  let changed = false;
+  if (pct < lowest && state.announced.length > 0) {
+    state.announced = [];
+    state.epoch += 1;
+    changed = true;
+  }
+  const due = opts.thresholds.filter((t) => pct >= t && !state.announced.includes(t));
+  let top = null;
+  if (due.length > 0) {
+    top = due[due.length - 1];
+    state.announced = [...new Set([...state.announced, ...due])].sort((a, b) => a - b);
+    changed = true;
+  }
+  if (changed) {
+    state.updated = new Date().toISOString();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(state), "utf8");
+  }
+  return top;
+}
+
+/**
+ * Builds the advisory for one Stop payload, or null when nothing is due. The window is the
+ * snapshot's own `context_window`; the transcript fallback carries no window of its own, so
+ * --budget stands in for it there.
+ * @param {Record<string, any>} payload Parsed hook payload.
+ * @param {{budget:number, thresholds:number[]}} opts Options.
+ * @returns {Record<string, unknown> | null} JSON to print, or null.
+ */
+export function respond(payload, opts) {
+  const sessionId = typeof payload.session_id === "string" && payload.session_id ? payload.session_id : "unknown";
+  const snap = contextFromSnapshot(sessionId);
+  let tokens = null;
+  let window = null;
+  if (snap) {
+    tokens = snap.tokens;
+    window = snap.window;
+  } else if (typeof payload.transcript_path === "string") {
+    tokens = contextFromTranscript(payload.transcript_path);
+    if (tokens !== null) window = opts.budget;
+  }
+  if (tokens === null) return null;
+  const threshold = crossed(tokens, window, opts, stateFile(sessionId));
+  if (threshold === null) return null;
+  const usedPct = Math.round((tokens / window) * 100);
+  const tokensK = Math.round(tokens / 1000);
+  const windowK = Math.round(window / 1000);
+  return {
+    systemMessage: `context ${tokensK}k of ${windowK}k (${usedPct}%): compact with the project instructions, or /clear before unrelated work`,
+  };
+}
+
+/** Entry point: read stdin, respond or stay silent, exit 0. */
+function main() {
+  if ((process.env.FREEHARNESS_HOOK_CONTEXT_MONITOR || "").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 out = respond(payload, parseOptions(process.argv.slice(2)));
+    if (out) process.stdout.write(JSON.stringify(out));
+  } catch (e) {
+    process.stderr.write(`freeharness-context-monitor: ${e instanceof Error ? e.message : String(e)}\n`);
+  }
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  main();
+  process.exit(0);
+}