harnery 0.31.0 → 0.31.2

package/dist/core/hooks/resolve/coord-root.js

@@ -1,49 +1,24 @@
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { coordEnv } from "../../../lib/env.js";
+import { resolveCoordRoot } from "../../agents/coord-client.js";
 /**
- * Walk up from `start` looking for a directory containing `.harnery/`. The
- * single coord-root resolution so every adapter agrees on the same root.
+ * The hooks-side name for THE coordination-root resolution.
  *
- * Resolution precedence:
+ * Delegates to `resolveCoordRoot()` so the hooks and the CLI cannot resolve
+ * different roots. They used to: this walked up from `CLAUDE_PROJECT_DIR` or
+ * cwd while the CLI's `monorepoRoot()` asked git for the superproject first, so
+ * with a shell inside a submodule that carries its own `.harnery/`, the CLI's
+ * `state.status_checked` landed in a stream this side never read and rule 1/3
+ * blocked every turn.
+ *
+ * Resolution precedence (see `resolveCoordRoot` for the full rationale):
  *   1. HARNERY_COORD_ROOT_OVERRIDE — explicit pin (tests, git hooks).
- *   2. The adapter's project dir (CLAUDE_PROJECT_DIR) — hook processes
- *      inherit the session's *shell* cwd, which follows `cd` into
- *      subdirectories/submodules that may carry a `.harnery/` of their own
- *      (or none at all, e.g. a journal dir under /tmp). The session's
- *      coordination home is the project the adapter opened, not wherever the
- *      shell happens to sit, so a project dir that resolves to a coord root
- *      wins over the cwd walk.
- *   3. Walk up from `start` (default cwd).
+ *   2. The adapter's project dir (CLAUDE_PROJECT_DIR) — hook processes inherit
+ *      the session's *shell* cwd, which follows `cd` into subdirectories or
+ *      submodules that may carry a `.harnery/` of their own (or none at all,
+ *      e.g. a journal dir under /tmp). The session's coordination home is the
+ *      project the adapter opened, not wherever the shell happens to sit.
+ *   3. The root that already holds this session's heartbeat.
+ *   4. The nearest enclosing `.harnery/`, then a git-derived root.
  */
 export function findCoordRoot(start = process.cwd()) {
-    // HARNERY_COORD_ROOT_OVERRIDE: explicit pin matched by agent-coord and the
-    // bash side. Lets the sandboxed coord-test suite run against a temp
-    // directory rather than the real monorepo root. agent-hook's session.start
-    // handler may be the FIRST thing to create .harnery/ in a fresh sandbox,
-    // so the override is honored unconditionally (we don't require .harnery/
-    // to pre-exist).
-    const override = coordEnv("COORD_ROOT_OVERRIDE");
-    if (override)
-        return override;
-    // Claude Code exports CLAUDE_PROJECT_DIR to every hook process; other
-    // adapters don't set it, so this is inert outside claude-code hooks.
-    const projectDir = process.env.CLAUDE_PROJECT_DIR;
-    if (projectDir) {
-        const fromProject = walkUp(projectDir);
-        if (fromProject)
-            return fromProject;
-    }
-    return walkUp(start);
-}
-function walkUp(start) {
-    let dir = resolve(start);
-    while (true) {
-        if (existsSync(join(dir, ".harnery")))
-            return dir;
-        const parent = dirname(dir);
-        if (parent === dir)
-            return null;
-        dir = parent;
-    }
+    return resolveCoordRoot(start);
 }

package/dist/lib/context/index.js

@@ -49,8 +49,15 @@ function buildSelf() {
     if (!owner)
         throw new Error("not in an agent session (no pid-map entry)");
     const hb = readHeartbeat(owner);
-    if (!hb)
-        throw new Error(`pid-map resolved owner=${owner.slice(0, 8)}… but no heartbeat`);
+    // Full id, never abbreviated: this message exists to hand the reader an id to
+    // pass back (to `agents heal --owner`, say), and an 8-char prefix is not that
+    // id. Healing the truncated form writes `.harnery/active/<prefix>.json`, a
+    // heartbeat no reader ever resolves — so the session still looks unhealable
+    // and now has a junk file shadowing it. Same rule as `noHeartbeatMessage` in
+    // the agents command.
+    if (!hb) {
+        throw new Error(`pid-map resolved owner=${owner} but no heartbeat exists at .harnery/active/${owner}.json`);
+    }
     const startedMs = Date.parse(hb.started_at);
     const ageSecs = Number.isFinite(startedMs)
         ? Math.max(0, Math.floor((Date.now() - startedMs) / 1000))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.31.0",
+  "version": "0.31.2",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/src/commands/agents.ts

@@ -28,6 +28,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { coordBinPath } from "../core/agents/coord-bin.ts";
 import { readStreamTailBounded } from "../core/agents/events/consume.ts";
 import {
   emitCanonical,
@@ -116,6 +117,44 @@ export function coordHelperOpts(root: string): { cwd: string; env: NodeJS.Proces
   return { cwd: root, env: { ...process.env, HARNERY_COORD_ROOT_OVERRIDE: root } };
 }
 
+/**
+ * Resolve the bundled `agent-coord` helper, or exit with an error that names the
+ * problem. Every heartbeat mutation goes through that binary, so a caller who
+ * cannot find it has nothing useful to do — but it has to SAY so, because the
+ * alternative was spawning a path that did not exist and then crashing on the
+ * result (see `spawnFailureMessage`).
+ */
+function agentCoordOrExit(root: string): string {
+  const binary = coordBinPath("agent-coord", root);
+  if (!binary) {
+    emit.error({
+      code: "coord_helper_missing",
+      message: `agent-coord helper not found for coord root ${root}; reinstall or rebuild harnery`,
+    });
+    process.exit(1);
+  }
+  return binary;
+}
+
+/**
+ * Describe a failed `spawnSync` without assuming it ran.
+ *
+ * When the binary cannot be executed at all (ENOENT, EACCES) node reports
+ * `status: null` AND `stderr: null`, so the obvious `result.stderr.trim()`
+ * threw "null is not an object" — replacing a legible "helper not found" with a
+ * crash that pointed at the wrong layer entirely. `error` carries the real
+ * cause on that path, so prefer it.
+ */
+function spawnFailureMessage(
+  result: { status: number | null; stderr: string | null; error?: Error },
+  what: string,
+): string {
+  if (result.error) return `${what}: ${result.error.message}`;
+  const stderr = result.stderr?.trim();
+  if (stderr) return stderr;
+  return result.status === null ? `${what}: did not run` : `${what} exited ${result.status}`;
+}
+
 function formatPlatformLabel(platform?: string | null): string {
   if (platform === "cursor") return "Cursor";
   if (platform === "codex") return "Codex";
@@ -820,7 +859,7 @@ function runWhoami(opts: { json?: boolean }): void {
   if (!hb) {
     emit.error({
       code: "no_heartbeat",
-      message: `pid-map resolved owner=${myOwner.slice(0, 8)} but no heartbeat exists`,
+      message: noHeartbeatMessage(myOwner),
     });
     process.exit(1);
   }
@@ -1020,6 +1059,41 @@ function normalizeKind(kind: string | undefined | null): string {
   return kind;
 }
 
+/**
+ * The `no_heartbeat` diagnostic, quoting the owner id in FULL.
+ *
+ * This id is actionable: the reader's next move is `agents heal --kind
+ * heartbeat --owner <id>`, and heartbeats are keyed by the whole
+ * `instance_id` (`.harnery/active/<instance_id>.json`). An abbreviated id
+ * here reads as complete, so it gets copy-pasted into `--owner` and mints a
+ * heartbeat at a filename no reader resolves — an orphan that leaves the
+ * session looking unhealable. Abbreviate ids for display elsewhere, never in
+ * a message whose whole purpose is to hand the reader an id to pass back.
+ */
+function noHeartbeatMessage(owner: string): string {
+  return `resolved owner=${owner} but no heartbeat exists at .harnery/active/${owner}.json`;
+}
+
+/**
+ * The instance_id of a live heartbeat that `prefix` strictly prefixes, or null.
+ *
+ * Used to recognize an abbreviated id handed back by a reader when the caller
+ * supplied no canonical id of their own. Ambiguity is treated as "no answer":
+ * two live sessions sharing the prefix means we cannot name the one intended,
+ * and refusing with the wrong id in the message would be worse than the orphan.
+ */
+function liveIdWithPrefix(root: string, prefix: string): string | null {
+  const activeDir = resolve(root, ".harnery", "active");
+  if (!existsSync(activeDir)) return null;
+  const matches = new Set<string>();
+  for (const file of readdirSync(activeDir)) {
+    if (!file.endsWith(".json")) continue;
+    const id = file.slice(0, -".json".length);
+    if (id !== prefix && id.startsWith(prefix)) matches.add(id);
+  }
+  return matches.size === 1 ? (matches.values().next().value as string) : null;
+}
+
 async function runWatch(pollMs: number): Promise<void> {
   const root = monorepoRoot();
   if (!root) {
@@ -1333,8 +1407,8 @@ function ensureCursorSession(root: string): void {
 
   const sessionId = cursorEnvSessionId();
   if (!sessionId) return;
-  const agentHook = resolve(root, "harnery", "bin", "agent-hook");
-  if (!existsSync(agentHook)) return;
+  const agentHook = coordBinPath("agent-hook", root);
+  if (!agentHook) return;
 
   const payload = JSON.stringify({
     conversation_id: sessionId,
@@ -1383,7 +1457,7 @@ function runReleaseClaim(path: string): void {
   let canonical = path;
   if (path.startsWith(`${root}/`)) canonical = path.slice(root.length + 1);
 
-  const helper = resolve(root, "harnery", "bin", "agent-coord");
+  const helper = agentCoordOrExit(root);
   const result = spawnSync(helper, ["release-claim", myOwner, canonical], {
     encoding: "utf8",
     ...coordHelperOpts(root),
@@ -1391,7 +1465,7 @@ function runReleaseClaim(path: string): void {
   if (result.status !== 0) {
     emit.error({
       code: "release_claim_failed",
-      message: result.stderr.trim() || `agent-coord exited ${result.status}`,
+      message: spawnFailureMessage(result, "agent-coord"),
     });
     process.exit(1);
   }
@@ -1432,7 +1506,7 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
   const firstOfSession = !priorHb?.task_updated_at;
 
   // Heartbeat mutation goes through agent-coord (atomic temp+rename).
-  const helper = resolve(root, "harnery", "bin", "agent-coord");
+  const helper = agentCoordOrExit(root);
   const result = spawnSync(helper, ["set-task", myOwner, task], {
     encoding: "utf8",
     ...coordHelperOpts(root),
@@ -1440,7 +1514,7 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
   if (result.status !== 0) {
     emit.error({
       code: "set_task_failed",
-      message: result.stderr.trim() || `agent-coord exited ${result.status}`,
+      message: spawnFailureMessage(result, "agent-coord"),
     });
     process.exit(1);
   }
@@ -1577,7 +1651,7 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
   if (!hb) {
     emit.error({
       code: "no_heartbeat",
-      message: `pid-map resolved owner=${myOwner.slice(0, 8)} but no heartbeat exists`,
+      message: noHeartbeatMessage(myOwner),
     });
     process.exit(1);
   }
@@ -1587,7 +1661,7 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
   // populated for back-compat with consumers reading v1 directly. The stamp
   // goes through agent-coord (atomic write).
   try {
-    const helper = resolve(root, "harnery", "bin", "agent-coord");
+    const helper = agentCoordOrExit(root);
     spawnSync(helper, ["stamp-status-call", myOwner], {
       encoding: "utf8",
       timeout: 2000,
@@ -3578,6 +3652,44 @@ function runHeal(opts: {
   const action =
     kind === "pidmap" ? "heal-pidmap" : kind === "heartbeat" ? "heal-heartbeat" : "kill-heartbeat";
 
+  // Refuse to mint a heartbeat at a TRUNCATED owner id.
+  //
+  // Heartbeats are keyed by the whole instance_id, so healing at an
+  // abbreviated id writes `.harnery/active/<prefix>.json` while every reader
+  // (`status`, `set-task`, `whoami`) resolves `<instance_id>.json`. The heal
+  // reports success, the session stays broken, and an orphan file is left
+  // behind that the singleton fallback can then mis-resolve other callers to.
+  //
+  // A distinct instance_id (subagent, workflow child) is never a prefix of its
+  // own session_id, so a strict prefix is unambiguously an abbreviated id
+  // rather than a legitimately different owner. Only guard the create path: an
+  // existing heartbeat at `owner` means the id is real, whatever its shape.
+  //
+  // Two sources for the canonical id, because the reported failure arrives
+  // without `--session-id`: someone copies a truncated id out of a diagnostic
+  // and passes it as `--owner` alone. Comparing against `--session-id` alone
+  // therefore misses the exact path that produced the orphan; a live heartbeat
+  // whose instance_id this id is a prefix of settles it just as well, and is
+  // present in precisely the case that matters (the session the reader was
+  // trying to heal is registered, just not under the abbreviated name).
+  if (kind === "heartbeat" && !readHeartbeat(owner)) {
+    const canonical =
+      opts.sessionId && opts.sessionId.trim() !== owner && opts.sessionId.trim().startsWith(owner)
+        ? opts.sessionId.trim()
+        : liveIdWithPrefix(root, owner);
+    if (canonical) {
+      const source = opts.sessionId?.trim() === canonical ? "--session-id" : "a live heartbeat";
+      emit.error({
+        code: "truncated_owner",
+        message:
+          `--owner ${owner} is a prefix of ${canonical} (${source}), and no heartbeat exists ` +
+          `at .harnery/active/${owner}.json. Healing here would create a heartbeat no reader ` +
+          `resolves. Re-run with --owner ${canonical}.`,
+      });
+      process.exit(1);
+    }
+  }
+
   // Build positional args. agent-coord's arg layout:
   //   heal-pidmap <instance_id> [<pid>]
   //   heal-heartbeat <instance_id> [<session_id>]
@@ -3587,8 +3699,8 @@ function runHeal(opts: {
   if (kind === "heartbeat" && opts.sessionId) helperArgs.push(opts.sessionId);
 
   // heal-pidmap / heal-heartbeat / kill-heartbeat are handled by the
-  // agent-coord binary at harnery/bin/agent-coord.
-  const helper = `${root}/harnery/bin/agent-coord`;
+  // bundled agent-coord binary.
+  const helper = agentCoordOrExit(root);
   const proc = spawnSync(helper, helperArgs, {
     encoding: "utf8",
     ...coordHelperOpts(root),
@@ -3597,7 +3709,7 @@ function runHeal(opts: {
   if (proc.status !== 0) {
     emit.error({
       code: "heal_failed",
-      message: proc.stderr?.trim() || `agent-coord ${action} exited non-zero`,
+      message: spawnFailureMessage(proc, `agent-coord ${action}`),
     });
     process.exit(1);
   }
@@ -3635,7 +3747,10 @@ function runHeal(opts: {
     ],
     meta: {
       kind,
-      helper: "harnery/bin/agent-coord",
+      // The path actually spawned, not a guess at the layout: the helper is
+      // resolved from harnery's own package location, which differs between a
+      // submodule, an installed dependency, and a standalone checkout.
+      helper,
     },
   });
   if (!opts.json) {
@@ -4430,7 +4545,7 @@ function runCouncilContribute(
     if (!myHb?.name) {
       emit.error({
         code: "no_self_name",
-        message: `resolved owner ${myOwner.slice(0, 8)} has no name on heartbeat (pass --as <member> to override)`,
+        message: `resolved owner ${myOwner} has no name on heartbeat (pass --as <member> to override)`,
       });
       process.exit(1);
     }

package/src/commands/grep.ts

@@ -741,7 +741,7 @@ function buildFindArgs(
  * chunk-boundary tests. Record shapes (both engines, pinned by the parity
  * suite):
  *   content:    <path>NUL<line>:<text>LF
- *   count:      <path>NUL<count>LF
+ *   count:      <path>NUL<count>LF   (BSD grep ignores --null here: <path>:<count>LF)
  *   filesOnly:  <path>NUL            (NUL is the record terminator)
  *   plainLines: <path>LF             (files mode: rg --files / find)
  *
@@ -801,7 +801,24 @@ export class NulDecoder {
       return { file: normalizeFile(path), line: 0, text: "" };
     }
     const nul = record.indexOf(0);
-    if (nul < 0) return null; // not a NUL-framed record (stray engine chatter)
+    if (nul < 0) {
+      // BSD grep honours --null for content and -l records but IGNORES it under
+      // -c, emitting `<path>:<count>` where GNU grep emits `<path>NUL<count>`.
+      // Without this fallback every count row is dropped as unframed chatter, so
+      // `grep -c` returns nothing on a host whose only engine is BSD grep. The
+      // count is always a terminal run of digits, so a greedy match on the LAST
+      // colon recovers the path even when the path itself contains colons.
+      if (this.mode === "count") {
+        const bsd = /^(.*):(\d+)$/.exec(record.toString("utf8"));
+        if (!bsd) return null;
+        return {
+          file: normalizeFile(bsd[1] as string),
+          line: Number.parseInt(bsd[2] as string, 10),
+          text: "",
+        };
+      }
+      return null; // not a NUL-framed record (stray engine chatter)
+    }
     const file = normalizeFile(record.subarray(0, nul).toString("utf8"));
     const rest = record.subarray(nul + 1).toString("utf8");
     if (this.mode === "count") {

package/src/commands/tunnel.ts

@@ -209,12 +209,27 @@ function sweepStrays(gatePort: number, alreadyKilled: Set<number>): number {
   );
 }
 
-/** Ports currently bound by a LISTEN socket (best-effort via `ss`). */
+/**
+ * Ports currently bound by a LISTEN socket (best-effort, platform-dependent).
+ *
+ * `ss` (iproute2) is Linux-only. Without the lsof fallback this returns an empty
+ * set on macOS/BSD. That does not fail loudly. It reports every port as free, so
+ * `allocateGatePort` can hand out an occupied port and the reload port-release
+ * check becomes inert.
+ */
 function listeningPorts(): Set<number> {
   const ports = new Set<number>();
-  const r = spawnSync("ss", ["-tlnH"], { encoding: "utf-8" });
-  if (r.status === 0 && typeof r.stdout === "string") {
-    for (const m of r.stdout.matchAll(/:(\d+)\s/g)) ports.add(Number(m[1]));
+  const ss = spawnSync("ss", ["-tlnH"], { encoding: "utf-8" });
+  if (ss.status === 0 && typeof ss.stdout === "string") {
+    for (const m of ss.stdout.matchAll(/:(\d+)\s/g)) ports.add(Number(m[1]));
+    return ports;
+  }
+  // Rows look like: `bun 123 user 4u IPv4 0x… 0t0 TCP 127.0.0.1:58055 (LISTEN)`.
+  // Status can be nonzero while stdout still holds usable rows (lsof reports a
+  // failure when any single process is unreadable), so judge it on the output.
+  const lsof = spawnSync("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN"], { encoding: "utf-8" });
+  if (typeof lsof.stdout === "string") {
+    for (const m of lsof.stdout.matchAll(/:(\d+) \(LISTEN\)$/gm)) ports.add(Number(m[1]));
   }
   return ports;
 }

package/src/core/agents/canonical-emit.ts

@@ -10,9 +10,8 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { monorepoRoot } from "./coord-client.ts";
+import { coordBinPath } from "./coord-bin.ts";
+import { resolveCoordRoot } from "./coord-client.ts";
 
 export interface CanonicalEmitInput {
   type: string;
@@ -28,37 +27,21 @@ export interface CanonicalEmitInput {
 /**
  * Resolve the coord root for a canonical emit.
  *
- * Order: explicit `HARNERY_COORD_ROOT_OVERRIDE` → git-superproject-aware
- * `monorepoRoot()` (must actually carry `.harnery/`) → cwd walk (non-git
- * hosts). The git-aware step is load-bearing: a shell cd'd into a nested
- * directory that carries its own `.harnery/` (e.g. an embedded harnery
- * checkout) made the old cwd-walk resolve the NESTED root, from which
- * `<root>/harnery/bin/agent-coord` doesn't exist — so `agents status` /
- * `set-task` emits silently vanished and the Stop-hook's rule 1/3
- * (`state.status_checked` in-turn) blocked turns that had done the ritual.
- * Same bug class as the coordHelperOpts root-pin fix; this closes the
- * emitCanonical instance of it.
+ * Delegates to `resolveCoordRoot()`, the single resolution the hooks and the
+ * CLI's reads also use. An emit resolved any other way is an emit the Stop hook
+ * cannot see: the hook reads `state.status_checked` from the stream under ITS
+ * root, so a divergent emit root blocks rule 1/3 on a turn that did run
+ * `agents status`, and no sequence of CLI commands can satisfy it.
  */
 export function resolveEmitRoot(start: string = process.cwd()): string | null {
-  const override = process.env.HARNERY_COORD_ROOT_OVERRIDE;
-  if (override) return override;
-  // Memoized per start-dir: the session-tee middleware resolves once per
-  // emitted event, and monorepoRoot() spawns git — cache so a streaming
-  // command doesn't pay 1-3 subprocess spawns per output line.
-  if (cachedRoot && cachedRoot.start === start) return cachedRoot.root;
-  const gitRoot = monorepoRoot();
-  const root = gitRoot && existsSync(join(gitRoot, ".harnery")) ? gitRoot : findRepoRoot(start);
-  cachedRoot = { start, root };
-  return root;
+  return resolveCoordRoot(start);
 }
 
-let cachedRoot: { start: string; root: string | null } | undefined;
-
 export function emitCanonical(input: CanonicalEmitInput): void {
   const root = resolveEmitRoot();
   if (!root) return;
-  const binary = resolve(root, "harnery", "bin", "agent-coord");
-  if (!existsSync(binary)) return;
+  const binary = coordBinPath("agent-coord", root);
+  if (!binary) return;
   try {
     const args = [
       "emit-event",
@@ -103,13 +86,3 @@ export function normalizeAdapter(platform: string | undefined): "claude-code" |
   if (platform === "codex") return "codex";
   return "claude-code";
 }
-
-function findRepoRoot(start: string): string | null {
-  let dir = resolve(start);
-  while (true) {
-    if (existsSync(join(dir, ".harnery"))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}

package/src/core/agents/coord-bin.ts

@@ -0,0 +1,92 @@
+/**
+ * Locate harnery's own bundled coordination binaries (`agent-coord`,
+ * `agent-hook`, `harn`).
+ *
+ * Every coord-helper spawn used to build its path as
+ * `<coordRoot>/harnery/bin/<name>`, which only exists in one host layout: a
+ * superproject carrying harnery as a submodule at `harnery/`. That assumption
+ * was load-bearing in the worst way — because the path missed whenever the
+ * resolved root was anything else, root resolution itself was bent toward the
+ * git superproject to keep the spawns working, which is what split the CLI's
+ * root from the hook's and blocked end-of-turn rule 1/3. The same missing path
+ * also surfaced as a crash rather than an error: `spawnSync` on a nonexistent
+ * binary reports `status: null` and `stderr: null`, so a caller checking
+ * `status !== 0` then reading `stderr.trim()` threw "null is not an object".
+ *
+ * The binaries ship inside the harnery package, so the package is what knows
+ * where they are. Resolution walks up from this module to the package root,
+ * which covers every install shape: `src/` under Bun, `dist/` on Node, and
+ * `node_modules/harnery/`. The layout-specific paths remain as fallbacks so a
+ * host whose harnery copy is not the one executing (a vendored tree, a shim)
+ * still resolves.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { coordEnv } from "../../lib/env.ts";
+
+export type CoordBinName = "agent-coord" | "agent-hook" | "harn";
+
+/**
+ * Absolute path to one of harnery's bundled binaries, or null when no candidate
+ * exists on disk. Callers must handle null — a missing helper is a real state
+ * (a partially installed package) and silently spawning a nonexistent path is
+ * what produced the null-deref crash above.
+ */
+export function coordBinPath(name: CoordBinName, coordRoot?: string | null): string | null {
+  for (const candidate of coordBinCandidates(name, coordRoot)) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** Candidate paths for `name`, in resolution order. Exported for tests. */
+export function coordBinCandidates(name: CoordBinName, coordRoot?: string | null): string[] {
+  const candidates: string[] = [];
+  const push = (value: string | null | undefined) => {
+    if (value && !candidates.includes(value)) candidates.push(value);
+  };
+
+  // Explicit pin, for a host that relocates the binaries.
+  const pinned = coordEnv("BIN_DIR");
+  if (pinned) push(join(pinned, name));
+
+  // The package this code is executing from.
+  const pkgRoot = packageRoot(name);
+  if (pkgRoot) push(join(pkgRoot, "bin", name));
+
+  if (coordRoot) {
+    // Host layouts, in decreasing specificity: harnery as a submodule, as an
+    // installed dependency, or the coord root being harnery's own checkout.
+    push(resolve(coordRoot, "harnery", "bin", name));
+    push(resolve(coordRoot, "node_modules", "harnery", "bin", name));
+    push(resolve(coordRoot, "bin", name));
+  }
+
+  return candidates;
+}
+
+/**
+ * Walk up from this module to the directory holding `bin/<name>`.
+ *
+ * The walk keys on the binary itself rather than on `package.json`, because
+ * both `src/core/agents/` and the built `dist/core/agents/` sit under the same
+ * package root and only the binary's presence proves we found the right level.
+ */
+function packageRoot(name: CoordBinName): string | null {
+  let dir: string;
+  try {
+    dir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    // No import.meta (a CJS transpile); the coordRoot fallbacks still apply.
+    return null;
+  }
+  for (let hop = 0; hop < 8; hop++) {
+    if (existsSync(join(dir, "bin", name))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}