@forwardimpact/libharness 0.1.20 → 1.0.0

package/src/agent-runner.js

@@ -0,0 +1,256 @@
+/**
+ * AgentRunner — runs a single Claude Agent SDK session and emits raw
+ * NDJSON events to an output stream. Building block for `fit-harness run`,
+ * `fit-harness supervise`, `fit-harness facilitate`, and `fit-harness discuss`.
+ *
+ * Follows OO+DI: constructor injection, factory function, tests bypass factory.
+ */
+
+import { AGENT_MODEL } from "@forwardimpact/libutil/models";
+
+const DEFAULT_ALLOWED_TOOLS = ["Bash", "Read", "Glob", "Grep", "Write", "Edit"];
+
+/**
+ * Did the session actually invoke the model? A genuine run always bills
+ * tokens (the system prompt alone is thousands of input tokens) and costs
+ * more than zero. A `result` message with `subtype: "success"` but zero
+ * token usage and zero cost means the model was never reached — the
+ * canonical signature of a Claude Code init/auth failure (e.g. an invalid
+ * `ANTHROPIC_API_KEY`), which the SDK otherwise reports as a clean success.
+ *
+ * If the SDK gave us neither a `usage` object nor `total_cost_usd`, don't
+ * second-guess the subtype — trust the reported success.
+ * @param {object|null} result - The SDK `result` message, or null.
+ * @returns {boolean}
+ */
+function modelDidWork(result) {
+  if (!result) return false;
+  const { usage, total_cost_usd: cost } = result;
+  if (usage == null && cost == null) return true;
+  const tokens = usage
+    ? (usage.input_tokens ?? 0) +
+      (usage.output_tokens ?? 0) +
+      (usage.cache_creation_input_tokens ?? 0) +
+      (usage.cache_read_input_tokens ?? 0)
+    : 0;
+  return tokens > 0 || (cost ?? 0) > 0;
+}
+
+// fit-harness and kata-action run headless in CI/CD with no human to answer
+// permission prompts. The SDK is always launched in bypass mode — not
+// overridable — so a future caller can't accidentally reduce permissions.
+const PERMISSION_MODE = "bypassPermissions";
+
+/** Run a single Claude Agent SDK session and emit raw NDJSON events to an output stream. */
+export class AgentRunner {
+  /**
+   * @param {object} deps
+   * @param {string} deps.cwd - Agent working directory
+   * @param {function} deps.query - SDK query function (injected for testing)
+   * @param {import("stream").Writable} deps.output - Stream to emit NDJSON to
+   * @param {string} [deps.model] - Claude model identifier
+   * @param {number} [deps.maxTurns] - Maximum agentic turns; 0 means unlimited
+   * @param {string[]} [deps.allowedTools] - Tools the agent may use
+   * @param {function} [deps.onLine] - Callback invoked with each NDJSON line as it's produced
+   * @param {string[]} [deps.settingSources] - SDK setting sources (e.g. ['project'] to load CLAUDE.md)
+   * @param {string|object} [deps.systemPrompt] - SDK system prompt (string replaces default; {type:'preset', preset:'claude_code', append} appends)
+   * @param {string[]} [deps.disallowedTools] - Tools to explicitly remove from the model's context
+   * @param {Record<string, object>} [deps.mcpServers] - MCP server configs to pass to the SDK query
+   * @param {object} deps.redactor
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} [deps.runtime] -
+   *   Ambient collaborators. Only `proc.env` is read (to record Skill
+   *   invocations into `LIBHARNESS_SKILL`); when absent the write is skipped.
+   */
+  constructor(deps) {
+    if (!deps.cwd) throw new Error("cwd is required");
+    if (!deps.query) throw new Error("query is required");
+    if (!deps.output) throw new Error("output is required");
+    if (!deps.redactor) throw new Error("redactor is required");
+    this.runtime = deps.runtime ?? null;
+    this.cwd = deps.cwd;
+    this.query = deps.query;
+    this.output = deps.output;
+    this.redactor = deps.redactor;
+    this.model = deps.model ?? AGENT_MODEL;
+    this.maxTurns = deps.maxTurns ?? 50;
+    this.allowedTools = deps.allowedTools ?? DEFAULT_ALLOWED_TOOLS;
+    this.onLine = deps.onLine ?? null;
+    this.settingSources = deps.settingSources ?? [];
+    this.systemPrompt = deps.systemPrompt ?? null;
+    this.disallowedTools = deps.disallowedTools ?? [];
+    this.mcpServers = deps.mcpServers ?? null;
+    this.taskAmend = deps.taskAmend ?? null;
+    this.sessionId = null;
+    /** @type {AbortController|null} */
+    this.currentAbortController = null;
+  }
+
+  /**
+   * Run a new agent session with the given task.
+   * @param {string} task
+   * @returns {Promise<{success: boolean, text: string, sessionId: string|null, error: Error|null, aborted: boolean}>}
+   */
+  async run(task) {
+    const abortController = new AbortController();
+    this.currentAbortController = abortController;
+    const effectiveTask = this.taskAmend
+      ? task
+        ? `${task}\n\n${this.taskAmend}`
+        : this.taskAmend
+      : task;
+    try {
+      const iterator = this.query({
+        prompt: effectiveTask,
+        options: this.#callOptions(abortController),
+      });
+      return await this.#consumeQuery(iterator);
+    } finally {
+      this.currentAbortController = null;
+    }
+  }
+
+  /**
+   * Resume an existing session with a follow-up prompt.
+   * @param {string} prompt
+   * @returns {Promise<{success: boolean, text: string, sessionId: string|null, error: Error|null, aborted: boolean}>}
+   */
+  async resume(prompt) {
+    const abortController = new AbortController();
+    this.currentAbortController = abortController;
+    try {
+      const iterator = this.query({
+        prompt,
+        options: {
+          ...this.#callOptions(abortController),
+          resume: this.sessionId,
+        },
+      });
+      return await this.#consumeQuery(iterator);
+    } finally {
+      this.currentAbortController = null;
+    }
+  }
+
+  /**
+   * Build the options passed to every SDK query() call. Shared by run()
+   * and resume() so the agent's configuration — cwd, tools, prompt,
+   * setting sources, turn budget — is identical across the session's
+   * lifetime. Only resume() layers `resume: this.sessionId` on top.
+   *
+   * SDK options are call-attached, not session-attached: the resumed
+   * call loads the prior conversation but otherwise uses whatever
+   * options this call passes. Omitting tool/prompt/setting options on
+   * resume causes the agent to silently lose its restrictions and
+   * persona between turns.
+   */
+  #callOptions(abortController) {
+    return {
+      cwd: this.cwd,
+      allowedTools: this.allowedTools,
+      maxTurns: this.maxTurns === 0 ? Number.MAX_SAFE_INTEGER : this.maxTurns,
+      model: this.model,
+      permissionMode: PERMISSION_MODE,
+      allowDangerouslySkipPermissions: true,
+      settingSources: this.settingSources,
+      abortController,
+      ...(this.disallowedTools.length > 0 && {
+        disallowedTools: this.disallowedTools,
+      }),
+      ...(this.systemPrompt && { systemPrompt: this.systemPrompt }),
+      ...(this.mcpServers && { mcpServers: this.mcpServers }),
+    };
+  }
+
+  /**
+   * Iterate the SDK query iterator, mirroring every message to the
+   * output stream and the `onLine` callback. Captures `sessionId` from
+   * the SDK's `system/init` message and tracks Skill invocations into
+   * `LIBHARNESS_SKILL` for downstream metrics.
+   *
+   * If the iterator throws and we triggered the abort ourselves
+   * (`currentAbortController.signal.aborted`), we report `aborted:
+   * true`; otherwise the error propagates as `error`.
+   */
+  async #consumeQuery(iterator) {
+    let text = "";
+    let stopReason = null;
+    let resultMessage = null;
+    let error = null;
+    let aborted = false;
+
+    try {
+      for await (const message of iterator) {
+        this.#recordLine(message);
+        if (message.type === "result") {
+          text = message.result ?? "";
+          stopReason = message.subtype;
+          resultMessage = message;
+        }
+      }
+    } catch (err) {
+      if (this.currentAbortController?.signal.aborted) {
+        aborted = true;
+      } else {
+        error = err;
+      }
+    }
+
+    // A "success" subtype is necessary but not sufficient: the SDK reports a
+    // failed init (e.g. an invalid API key) as success with zero model work.
+    // Require evidence the model actually ran, and surface a clear error when
+    // it didn't, so the masked failure can't be reported as a green run.
+    const reportedSuccess = stopReason === "success";
+    const success =
+      reportedSuccess &&
+      resultMessage?.is_error !== true &&
+      modelDidWork(resultMessage);
+    if (reportedSuccess && !success && !error) {
+      error = new Error(
+        "agent reported success but performed no model work (zero token usage) — likely a Claude Code init or authentication failure",
+      );
+    }
+
+    return {
+      success,
+      text,
+      sessionId: this.sessionId,
+      error,
+      aborted,
+    };
+  }
+
+  #recordLine(message) {
+    const redacted = this.redactor.redactValue(message);
+    const line = JSON.stringify(redacted);
+    this.output.write(line + "\n");
+    if (this.onLine) this.onLine(line);
+
+    if (message.type === "system" && message.subtype === "init") {
+      this.sessionId = message.session_id;
+    }
+    if (message.type === "assistant") this.#trackSkillInvocation(message);
+  }
+
+  #trackSkillInvocation(message) {
+    const content = message.message?.content ?? message.content;
+    if (!Array.isArray(content)) return;
+    // Skill metric is recorded into the env map; without a runtime there is
+    // no env surface to write to, so the side-effect is simply skipped.
+    const env = this.runtime?.proc?.env ?? null;
+    if (!env) return;
+    for (const block of content) {
+      if (
+        block.type === "tool_use" &&
+        block.name === "Skill" &&
+        block.input?.skill
+      ) {
+        env.LIBHARNESS_SKILL = block.input.skill;
+      }
+    }
+  }
+}
+
+/** Factory function — wires real dependencies. */
+export function createAgentRunner(deps) {
+  return new AgentRunner(deps);
+}

package/src/benchmark/apm-installer.js

@@ -0,0 +1,207 @@
+/**
+ * ApmInstaller — runs `apm install --target claude` in the family root to
+ * materialise skills and agents, copies the resulting `.claude/` into a
+ * staging directory, and computes the manifest fingerprint from the lockfile.
+ * Per-task copy happens later in WorkdirManager.
+ *
+ * Subprocess and filesystem access route through the injected `runtime` bag
+ * (`runtime.subprocess.spawn` for the streaming `apm` child, `runtime.fs` for
+ * the async staging copies). See `createApmInstaller` for the real-dependency
+ * wiring; `installApm` is a thin free-function wrapper.
+ */
+
+import { createHash } from "node:crypto";
+import { join, resolve } from "node:path";
+
+/** Installs apm and stages `.claude/` for a task family. */
+export class ApmInstaller {
+  /**
+   * @param {object} deps
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime -
+   *   Ambient collaborators; uses `subprocess.spawn` and `fs`.
+   */
+  constructor({ runtime }) {
+    if (!runtime) throw new Error("runtime is required");
+    this.runtime = runtime;
+  }
+
+  /**
+   * @param {import("./task-family.js").TaskFamily} family
+   * @param {string} outputDir - The benchmark run's output directory.
+   * @param {object} [options]
+   * @param {string|null} [options.skillsFrom] - Stage `.claude/` from this
+   *   directory instead of running apm install. The path is a root containing
+   *   a `.claude/` tree (e.g. a working tree), letting a run exercise local,
+   *   unpublished skills.
+   * @returns {Promise<{stagingDir: string, skillSetHash: string, judgeProfilesDir: string}>}
+   */
+  async install(family, outputDir, { skillsFrom } = {}) {
+    const fs = this.runtime.fs;
+    const stagingDir = join(outputDir, ".apm-staging");
+    const stagedClaude = join(stagingDir, ".claude");
+    const sourceClaude = skillsFrom
+      ? join(resolve(skillsFrom), ".claude")
+      : join(family.rootPath, ".claude");
+    const apmYml = join(family.rootPath, "apm.yml");
+
+    // --skills-from takes precedence over apm install: the caller is supplying
+    // the skill tree explicitly, so no remote fetch runs.
+    const hasApm =
+      !skillsFrom &&
+      (await fs
+        .access(apmYml)
+        .then(() => true)
+        .catch(() => false));
+
+    if (hasApm) {
+      await this.#runApmInstall(family.rootPath);
+      try {
+        await fs.access(sourceClaude);
+      } catch {
+        throw new Error(
+          `apm install did not produce .claude/ at ${sourceClaude}; check the family's apm.yml`,
+        );
+      }
+    }
+
+    await fs.rm(stagingDir, { recursive: true, force: true });
+    const hasClaudeDir = await fs
+      .access(sourceClaude)
+      .then(() => true)
+      .catch(() => false);
+    if (skillsFrom && !hasClaudeDir) {
+      throw new Error(`--skills-from has no .claude/ tree at ${sourceClaude}`);
+    }
+    if (hasClaudeDir) {
+      await fs.cp(sourceClaude, stagedClaude, { recursive: true });
+    } else {
+      await fs.mkdir(stagedClaude, { recursive: true });
+    }
+
+    // apm's claude target deploys a pack's skills/ into .claude/skills/ but
+    // never its agents/ subtree (agent profiles + references). Stage that from
+    // the installed apm_modules into .claude/agents/ so a skill that cites an
+    // agent reference (e.g. the work-item tracker matrix) resolves in the
+    // agent CWD. No-op when --skills-from supplied a tree or no apm_modules
+    // exist.
+    if (!skillsFrom) {
+      await this.#stageApmAgents(family.rootPath, stagedClaude);
+    }
+
+    // Stage the family-local judge profile outside .claude/ so it is available
+    // to the judge but never copied into the agent-under-test's CWD.
+    const judgeSource = join(family.rootPath, "judge.md");
+    const judgeProfilesDir = join(stagingDir, "judge-profiles");
+    try {
+      await fs.access(judgeSource);
+      await fs.mkdir(judgeProfilesDir, { recursive: true });
+      await fs.cp(judgeSource, join(judgeProfilesDir, "judge.md"));
+    } catch {}
+
+    const lockPath = join(family.rootPath, "apm.lock.yaml");
+    let skillSetHash = "";
+    try {
+      const lockBytes = await fs.readFile(lockPath);
+      skillSetHash =
+        "sha256:" +
+        createHash("sha256").update(normalizeLf(lockBytes)).digest("hex");
+    } catch {
+      // No lockfile — family doesn't use skill packs.
+    }
+
+    return { stagingDir, skillSetHash, judgeProfilesDir };
+  }
+
+  /**
+   * Merge each installed pack's `agents/` subtree (profiles + references) from
+   * `apm_modules/<owner>/<pack>/agents/` into the staged `.claude/agents/`.
+   * apm's claude target deploys `skills/` only, so without this an agent
+   * reference a skill cites is absent from the agent CWD.
+   * @param {string} familyRoot
+   * @param {string} stagedClaude
+   */
+  async #stageApmAgents(familyRoot, stagedClaude) {
+    const fs = this.runtime.fs;
+    const modulesRoot = join(familyRoot, "apm_modules");
+    let owners;
+    try {
+      owners = await fs.readdir(modulesRoot, { withFileTypes: true });
+    } catch {
+      return; // no apm_modules — nothing to stage
+    }
+    const stagedAgents = join(stagedClaude, "agents");
+    for (const owner of owners) {
+      if (!owner.isDirectory()) continue;
+      const ownerDir = join(modulesRoot, owner.name);
+      let packs;
+      try {
+        packs = await fs.readdir(ownerDir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const pack of packs) {
+        if (!pack.isDirectory()) continue;
+        const agentsDir = join(ownerDir, pack.name, "agents");
+        const hasAgents = await fs
+          .access(agentsDir)
+          .then(() => true)
+          .catch(() => false);
+        if (hasAgents) {
+          await fs.cp(agentsDir, stagedAgents, { recursive: true });
+        }
+      }
+    }
+  }
+
+  async #runApmInstall(cwd) {
+    const child = this.runtime.subprocess.spawn(
+      "apm",
+      ["install", "--target", "claude"],
+      { cwd, stdio: ["ignore", "pipe", "pipe"] },
+    );
+    // Drain stdout concurrently so the child never blocks on backpressure;
+    // capture stderr for the failure message.
+    let stderr = "";
+    const drainStdout = (async () => {
+      for await (const _chunk of child.stdout) {
+        // discard
+      }
+    })();
+    for await (const chunk of child.stderr) stderr += chunk.toString();
+    await drainStdout;
+    const code = await child.exitCode;
+    if (code !== 0) {
+      throw new Error(`apm install exited ${code}: ${stderr}`);
+    }
+  }
+}
+
+function normalizeLf(buf) {
+  const out = [];
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === 0x0d && i + 1 < buf.length && buf[i + 1] === 0x0a) continue;
+    out.push(buf[i]);
+  }
+  return Buffer.from(out);
+}
+
+/**
+ * Factory function — wires real dependencies.
+ * @param {ConstructorParameters<typeof ApmInstaller>[0]} deps
+ * @returns {ApmInstaller}
+ */
+export function createApmInstaller(deps) {
+  return new ApmInstaller(deps);
+}
+
+/**
+ * Free-function shorthand for callers that thread a runtime bag.
+ * @param {import("./task-family.js").TaskFamily} family
+ * @param {string} outputDir
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @param {object} [options] - Forwarded to `ApmInstaller.install` (e.g.
+ *   `{ skillsFrom }`).
+ */
+export function installApm(family, outputDir, runtime, options = {}) {
+  return new ApmInstaller({ runtime }).install(family, outputDir, options);
+}

package/src/benchmark/env-loader.js

@@ -0,0 +1,158 @@
+/**
+ * Env-loader — auto-discover `.env` / `.env.local` files in a task family
+ * and its tasks, load them into `process.env`, and render the merged result
+ * into each agent CWD.
+ *
+ * Discovery paths (loaded in this order, first value per key wins):
+ *   1. process.env  (CI secrets, shell env — never overwritten)
+ *   2. <family>/.env.local
+ *   3. <family>/.env
+ *   4. tasks/<id>/.env.local
+ *   5. tasks/<id>/.env
+ *
+ * Every discovered env file — family or task — is loaded into process.env
+ * AND rendered (with resolved values) into the agent working directory.
+ */
+
+import { join } from "node:path";
+
+const ENV_FILES = [".env.local", ".env"];
+
+/**
+ * Parse a `.env` file into an array of {key, value} pairs.
+ * Handles KEY=VALUE, # comments, blank lines, and single/double-quoted values.
+ * @param {string} content
+ * @returns {Array<{key: string, value: string}>}
+ */
+export function parseEnvFile(content) {
+  const entries = [];
+  for (const raw of content.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    if (!key) continue;
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    entries.push({ key, value });
+  }
+  return entries;
+}
+
+/**
+ * Read and parse an env file, returning [] if the file does not exist.
+ * @param {object} fs - Async filesystem surface (`runtime.fs`).
+ * @param {string} filePath
+ * @returns {Promise<Array<{key: string, value: string}>>}
+ */
+async function readEnvFile(fs, filePath) {
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    return parseEnvFile(content);
+  } catch (e) {
+    if (e.code === "ENOENT") return [];
+    throw e;
+  }
+}
+
+/**
+ * Load entries into the process env map. Existing keys are never overwritten.
+ * @param {Record<string, string|undefined>} env - The `runtime.proc.env` map.
+ * @param {Array<{key: string, value: string}>} entries
+ * @returns {string[]} var names that were loaded
+ */
+function applyToProcessEnv(env, entries) {
+  const names = [];
+  for (const { key, value } of entries) {
+    names.push(key);
+    if (env[key] === undefined) {
+      env[key] = value;
+    }
+  }
+  return names;
+}
+
+/**
+ * Load one env file: apply to the env map, record keys in the merged map.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @param {string} dir
+ * @param {string} file
+ * @param {Set<string>} names
+ * @param {Map<string, Map<string, true>>} merged
+ */
+async function loadOneEnvFile(runtime, dir, file, names, merged) {
+  const entries = await readEnvFile(runtime.fs, join(dir, file));
+  if (entries.length === 0) return;
+  for (const name of applyToProcessEnv(runtime.proc.env, entries)) {
+    names.add(name);
+  }
+  if (!merged.has(file)) merged.set(file, new Map());
+  const fileMap = merged.get(file);
+  for (const { key } of entries) {
+    if (!fileMap.has(key)) fileMap.set(key, true);
+  }
+}
+
+/**
+ * Scan directories for env files, load into the env map, and collect
+ * a merged key manifest per filename.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @param {string[]} dirs
+ * @returns {Promise<{names: Set<string>, merged: Map<string, Map<string, true>>}>}
+ */
+async function collectEnvEntries(runtime, dirs) {
+  const names = new Set();
+  const merged = new Map();
+  for (const dir of dirs) {
+    for (const file of ENV_FILES) {
+      await loadOneEnvFile(runtime, dir, file, names, merged);
+    }
+  }
+  return { names, merged };
+}
+
+/**
+ * Write resolved env files into the agent CWD and warn about empty values.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @param {Map<string, Map<string, true>>} merged
+ * @param {string} agentCwd
+ */
+async function renderEnvFiles(runtime, merged, agentCwd) {
+  const env = runtime.proc.env;
+  for (const [file, keyMap] of merged) {
+    const keys = [...keyMap.keys()];
+    const resolved = keys.map((key) => `${key}=${env[key] ?? ""}`);
+    await runtime.fs.writeFile(
+      join(agentCwd, file),
+      resolved.join("\n") + "\n",
+    );
+    const empty = keys.filter((key) => !env[key]);
+    if (empty.length > 0) {
+      runtime.proc.stderr.write(
+        `libharness: env warning: ${file} declares vars with no value: ${empty.join(", ")}\n`,
+      );
+    }
+  }
+}
+
+/**
+ * Discover `.env` / `.env.local` in one or more directories, load them
+ * into the process env map, and render the resolved values into the agent CWD.
+ *
+ * @param {string[]} dirs - Directories to scan (family root, task dir, etc.)
+ * @param {string} agentCwd - Agent working directory to render into.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime - Ambient
+ *   collaborators; uses `fs` (async read/write), `proc.env`, `proc.stderr`.
+ * @returns {Promise<string[]>} All var names discovered (for redaction).
+ */
+export async function loadEnv(dirs, agentCwd, runtime) {
+  const { names, merged } = await collectEnvEntries(runtime, dirs);
+  await renderEnvFiles(runtime, merged, agentCwd);
+  return [...names];
+}

package/src/benchmark/hook-env.js

@@ -0,0 +1,40 @@
+/**
+ * Shared environment builder for the benchmark hook scripts (`preflight.sh` and
+ * `invariants.sh`). Keeping both spawns on one helper guarantees they expose the
+ * same variable set, so hook authors never have to wonder which vars a given
+ * hook receives.
+ *
+ * Path vars (TASK_DIR, FAMILY_DIR, HOOKS_DIR) let hooks reference real
+ * locations instead of reconstructing them from `$0`. They are paths, not
+ * secrets, so they need no redaction allowlist entry.
+ */
+
+/**
+ * @param {Record<string, string>} baseEnv - Inherited env (`runtime.proc.env`).
+ * @param {object} vars
+ * @param {string} vars.cwd - Agent CWD → `$AGENT_CWD`.
+ * @param {number} vars.port - Allocated TCP port → `$PORT`.
+ * @param {string} vars.taskId - Task id → `$TASK_ID`.
+ * @param {string} vars.taskDir - Task directory on host → `$TASK_DIR`.
+ * @param {string} vars.hooksDir - Task `hooks/` dir on host → `$HOOKS_DIR`.
+ * @param {string|null} vars.familyDir - Family root on host → `$FAMILY_DIR`
+ *   (null when the family root is unknown, e.g. a standalone task).
+ * @returns {Record<string, string>}
+ */
+export function buildHookEnv(
+  baseEnv,
+  { cwd, port, taskId, taskDir, hooksDir, familyDir },
+) {
+  return {
+    ...baseEnv,
+    // The agent CWD itself — hooks reference emitted files as `$AGENT_CWD/<path>`.
+    // Distinct from the `invariants` CLI's `--run-dir` (the parent that
+    // *contains* `cwd/`), so the two are never confused.
+    AGENT_CWD: cwd,
+    PORT: String(port),
+    TASK_ID: taskId,
+    TASK_DIR: taskDir,
+    HOOKS_DIR: hooksDir,
+    FAMILY_DIR: familyDir ?? "",
+  };
+}