harnery 0.31.0 → 0.31.2

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

@@ -9,7 +9,7 @@
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 
 // NOTE: kept dependency-free (node builtins only); this file is vendored verbatim into
 // a downstream consumer, so it cannot import the coordEnv helper.
@@ -86,57 +86,173 @@ export interface Heartbeat {
 /**
  * Resolve the monorepo root for coord-state purposes.
  *
- * Resolves the coordination root,
- * including the `--git-common-dir` fallback that strips
- * `<superproject>/.git/modules/<name>/` to recover the superproject for
- * submodule worktrees. Without that fallback, a TS coord caller running
- * inside a `harn worktree add-submodule` checkout would resolve a different
- * `.harnery/` than the bash hooks and the two layers would silently diverge.
+ * Thin alias for `resolveCoordRoot()`; kept because it is the name the CLI
+ * command modules and the vendored downstream consumer already import.
  */
 export function monorepoRoot(): string | null {
-  // Test-only override (matches bash HARNERY_COORD_ROOT_OVERRIDE). Lets tests
-  // seed `.harnery/pid-map/<pid>` + `.harnery/active/<owner>.json` fixtures
-  // in a tmpdir without needing a real git repo.
+  return resolveCoordRoot();
+}
+
+/**
+ * THE coordination-root resolution. Every surface — the hooks, the CLI's reads,
+ * and the CLI's canonical emits — resolves through this one function, because a
+ * root the two layers disagree about is a root that silently breaks the
+ * end-of-turn rules: the hook evaluates `state.status_checked` from the stream
+ * it reads, so an emit into a different `.harnery/events.ndjson` is invisible
+ * and rule 1/3 blocks a turn that did run `agents status`, with no sequence of
+ * CLI commands able to satisfy it.
+ *
+ * Precedence:
+ *   1. `HARNERY_COORD_ROOT_OVERRIDE` — explicit pin (tests, git hooks, and the
+ *      root every coord-helper spawn pins for its child).
+ *   2. `CLAUDE_PROJECT_DIR` — the adapter stating which project it opened. Hook
+ *      processes inherit the session's *shell* cwd, which follows `cd` into a
+ *      subdirectory or submodule that may carry a `.harnery/` of its own (or
+ *      none at all), so the adapter's own statement outranks the cwd walk.
+ *   3. The candidate root that already holds THIS session's heartbeat.
+ *   4. The nearest enclosing `.harnery/`, then a git-derived root.
+ *
+ * Step 3 is what makes CLI/hook disagreement structurally impossible rather
+ * than a coin flip. Choosing either root unconditionally is wrong in one
+ * direction each: preferring the git superproject strands a session whose
+ * adapter opened the submodule itself (its heartbeat lives in the submodule,
+ * so status/set-task wrote events the hook never read), while walking up from
+ * cwd alone strands the opposite case, a session opened on the superproject
+ * whose shell has cd'd into a submodule that carries its own `.harnery/`
+ * (regression-tested in tests/unit/coord-helper-root-pin.test.ts). The session's
+ * own heartbeat settles it: whichever root the hook registered this session in
+ * is the root the CLI must use, and the adapter-exported session id needed to
+ * recognize it is available to a plain tool-call subprocess even though
+ * `CLAUDE_PROJECT_DIR` is not.
+ */
+export function resolveCoordRoot(start: string = process.cwd()): string | null {
   const rootOverride = process.env.HARNERY_COORD_ROOT_OVERRIDE;
-  if (rootOverride) {
-    return rootOverride;
+  if (rootOverride) return rootOverride;
+
+  const projectDir = process.env.CLAUDE_PROJECT_DIR;
+  if (projectDir) {
+    const fromProject = nearestCoordRoot(projectDir);
+    if (fromProject) return fromProject;
   }
 
-  // 1. Superproject working tree (when running from inside a submodule).
-  const sup = spawnSync("git", ["rev-parse", "--show-superproject-working-tree"], {
-    encoding: "utf8",
-  });
-  if (sup.status === 0 && sup.stdout.trim() !== "") {
-    return sup.stdout.trim();
+  // Nearest-first, so the fallback at the end keeps the historical cwd-walk
+  // behavior for a shell that has no registered session at all.
+  const ancestors = ancestorCoordRoots(start);
+  for (const candidate of ancestors) {
+    if (rootKnowsSession(candidate)) return candidate;
   }
 
-  // 2. --git-common-dir fallback for submodule worktrees. `git worktree add`
-  // inside a submodule produces a worktree whose --show-superproject-working-
-  // tree is empty (the worktree has no submodule relationship of its own),
-  // but --git-common-dir points at <superproject>/.git/modules/<name>/, so
-  // we recover the superproject by stripping that suffix.
-  const common = spawnSync("git", ["rev-parse", "--git-common-dir"], {
-    encoding: "utf8",
-  });
-  if (common.status === 0) {
-    const cd = common.stdout.trim();
-    const idx = cd.indexOf("/.git/modules/");
-    if (idx !== -1) {
-      return cd.substring(0, idx);
-    }
+  // Only reached when no enclosing root knows this session: a submodule
+  // worktree (`harn worktree add-submodule`) has no ancestor relationship with
+  // the superproject that registered the session, so ask git for it.
+  const gitRoots = gitCoordRoots(start).filter((r) => !ancestors.includes(r));
+  for (const candidate of gitRoots) {
+    if (rootKnowsSession(candidate)) return candidate;
   }
 
-  // 3. Top-level fallback (regular checkout).
-  const top = spawnSync("git", ["rev-parse", "--show-toplevel"], {
-    encoding: "utf8",
-  });
-  if (top.status === 0 && top.stdout.trim() !== "") {
-    return top.stdout.trim();
+  if (ancestors.length > 0) return ancestors[0] as string;
+  if (gitRoots.length > 0) return gitRoots[0] as string;
+  // Nothing carries `.harnery/` yet. Hand back the enclosing checkout so a
+  // first run (`harn init`, agent-hook's session.start) has somewhere to
+  // create it.
+  return gitToplevel(start);
+}
+
+/** Nearest enclosing directory carrying `.harnery/`, or null. */
+export function nearestCoordRoot(start: string): string | null {
+  return ancestorCoordRoots(start)[0] ?? null;
+}
+
+/** Every enclosing directory carrying `.harnery/`, nearest first. */
+function ancestorCoordRoots(start: string): string[] {
+  const found: string[] = [];
+  let dir = resolve(start);
+  while (true) {
+    if (existsSync(join(dir, ".harnery"))) found.push(dir);
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
   }
+  return found;
+}
 
-  return null;
+/**
+ * Does this root's `.harnery/` already know the process asking?
+ *
+ * Two discriminators, both genuinely about *this* session: the adapter-exported
+ * session id matching a live heartbeat, and a pid-map row on our own ppid
+ * chain. Deliberately NOT the single-live-agent fallback that owner resolution
+ * ends with — a lone stranger in the wrong root is exactly how `whoami` came to
+ * report another agent's name and task as its own.
+ */
+export function rootKnowsSession(root: string): boolean {
+  if (resolveOwnerBySessionEnv(root)) return true;
+  return resolveOwnerByPidmap(root).owner !== null;
 }
 
+/**
+ * Git-derived candidate roots for `start`, in preference order, filtered to
+ * those that actually carry `.harnery/`.
+ *
+ * Spawns run with `cwd: start` rather than the process cwd so an injected
+ * start dir resolves its own repository — without that, a call about some
+ * unrelated directory inherits this process's repo and can resolve a root that
+ * has nothing to do with the question asked.
+ */
+function gitCoordRoots(start: string): string[] {
+  const roots: string[] = [];
+  const push = (value: string | null) => {
+    if (value && existsSync(join(value, ".harnery")) && !roots.includes(value)) roots.push(value);
+  };
+
+  // Superproject working tree (running from inside a submodule).
+  push(gitRevParse(start, "--show-superproject-working-tree"));
+
+  // `--git-common-dir` fallback for submodule worktrees: `git worktree add`
+  // inside a submodule produces a worktree whose superproject working tree is
+  // empty (the worktree has no submodule relationship of its own), but the
+  // common dir points at `<superproject>/.git/modules/<name>/`, so the
+  // superproject is recoverable by stripping that suffix.
+  const common = gitRevParse(start, "--git-common-dir");
+  if (common) {
+    const idx = common.indexOf("/.git/modules/");
+    if (idx !== -1) push(common.substring(0, idx));
+  }
+
+  // Top-level (regular checkout).
+  push(gitRevParse(start, "--show-toplevel"));
+  return roots;
+}
+
+function gitToplevel(start: string): string | null {
+  return gitRevParse(start, "--show-toplevel");
+}
+
+function gitRevParse(cwd: string, flag: string): string | null {
+  const key = `${cwd}${flag}`;
+  const cached = gitRevParseCache.get(key);
+  if (cached !== undefined) return cached;
+  let value: string | null = null;
+  try {
+    // `cwd` must exist or the spawn itself fails; callers pass paths that may
+    // not (a project dir from a stale env var), so treat any failure as "no
+    // answer" rather than letting it throw.
+    const r = spawnSync("git", ["rev-parse", flag], { encoding: "utf8", cwd });
+    if (r.status === 0) value = r.stdout.trim() || null;
+  } catch {
+    value = null;
+  }
+  gitRevParseCache.set(key, value);
+  return value;
+}
+
+/**
+ * Memoized because git spawns are the expensive part of resolution and every
+ * CLI command resolves the root many times per invocation. Keyed by (cwd, flag);
+ * a repository's identity does not change under a running process.
+ */
+const gitRevParseCache = new Map<string, string | null>();
+
 /** Parse owner from a pid-map row (`owner` or `owner\tplatform`). */
 export function parsePidmapRowOwner(row: string): string {
   const trimmed = row.trim();
@@ -296,6 +412,34 @@ export function resolveOwnerWithSource(): {
     }
   }
 
+  if (!existsSync(resolve(root, ".harnery", "pid-map"))) return { owner: null, source: "none" };
+
+  const byPidmap = resolveOwnerByPidmap(root);
+  if (byPidmap.owner) return byPidmap;
+
+  // Last resort: if exactly one agent is live in this coord root, it's
+  // unambiguously us — resolve to it. This is what lets the bare `agents
+  // status` / `set-task` the stop hook recommends work without a `--session-id`
+  // flag in the common single-agent case. With 0 or 2+ live agents it would be
+  // a guess, so we stay null and require the explicit flag.
+  const singleton = resolveSingleActiveOwner(root);
+  if (singleton) {
+    return { owner: singleton, source: "active_singleton" };
+  }
+
+  return { owner: null, source: "none" };
+}
+
+/**
+ * Walk our own ppid chain for a pid-map row in ONE given root.
+ *
+ * Root-parameterized (rather than resolving the root itself) so root resolution
+ * can use it as a discriminator without recursing back into itself.
+ */
+export function resolveOwnerByPidmap(root: string): {
+  owner: string | null;
+  source: "pidmap" | "pidmap_fallback" | "none";
+} {
   const pidmapDir = resolve(root, ".harnery", "pid-map");
   if (!existsSync(pidmapDir)) return { owner: null, source: "none" };
 
@@ -319,17 +463,6 @@ export function resolveOwnerWithSource(): {
   if (fallbackOwner) {
     return { owner: fallbackOwner, source: "pidmap_fallback" };
   }
-
-  // Last resort: if exactly one agent is live in this coord root, it's
-  // unambiguously us — resolve to it. This is what lets the bare `agents
-  // status` / `set-task` the stop hook recommends work without a `--session-id`
-  // flag in the common single-agent case. With 0 or 2+ live agents it would be
-  // a guess, so we stay null and require the explicit flag.
-  const singleton = resolveSingleActiveOwner(root);
-  if (singleton) {
-    return { owner: singleton, source: "active_singleton" };
-  }
-
   return { owner: null, source: "none" };
 }
 

package/src/core/agents/paths.ts

@@ -1,16 +1,12 @@
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { resolveCoordRoot } from "./coord-client.ts";
 
 /**
- * Walk up from `start` looking for a directory containing `.harnery/`, so
- * adapter + legacy code agree on the same monorepo root.
+ * Resolve the coordination root.
+ *
+ * Delegates to `resolveCoordRoot()`. This was a third, independent copy of the
+ * walk-up — the kind of duplication that let the hooks and the CLI drift onto
+ * different roots in the first place; keep resolution in one place.
  */
 export function findCoordRoot(start: string = process.cwd()): 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;
-  }
+  return resolveCoordRoot(start);
 }

package/src/core/hooks/adapter/detect.ts

@@ -3,21 +3,26 @@ import type { Adapter } from "../events/schema.ts";
 
 /**
  * Resolve the adapter firing the hook. The dispatcher binary is always
- * invoked with `--adapter <name>` per the wiring in each adapter's settings
- * file (Phase 1). Returns null when the flag is missing; caller falls
+ * invoked with `--adapter <name>` per the current wiring in each adapter's
+ * settings file. `--harness` remains an accepted alias because settings files
+ * written by older releases survive a package upgrade until the consumer
+ * re-runs `harn init`. Returns null when neither flag is present; caller falls
  * through to the env-based fallback or skips emission.
  */
 export function detectAdapter(argv: readonly string[]): Adapter | null {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
-    if (a === "--adapter") {
+    if (a === "--adapter" || a === "--harness") {
       return validate(argv[i + 1]);
     }
     if (a.startsWith("--adapter=")) {
       return validate(a.slice("--adapter=".length));
     }
+    if (a.startsWith("--harness=")) {
+      return validate(a.slice("--harness=".length));
+    }
   }
-  return validate(coordEnv("AGENT_COORD_ADAPTER"));
+  return validate(coordEnv("AGENT_COORD_ADAPTER") ?? coordEnv("AGENT_COORD_HARNESS"));
 }
 
 function validate(v: string | undefined): Adapter | null {

package/src/core/hooks/cli.ts

@@ -23,6 +23,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { coordEnv } from "../../lib/env.ts";
 import { replayCodexJsonl } from "../agents/codex-replay.ts";
+import { coordBinPath } from "../agents/coord-bin.ts";
 import { consumeSince, writeCursor } from "../agents/events/consume.ts";
 import { evaluateStopHook } from "../agents/rules/stop-hook.ts";
 import { projectHeartbeats } from "../agents/state/heartbeat-projector.ts";
@@ -79,11 +80,11 @@ function parseArgv(argv: string[]): Argv {
   const out: Argv = { eventName: null, extra: [] };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]!;
-    if (arg === "--adapter") {
+    if (arg === "--adapter" || arg === "--harness") {
       i++; // detectAdapter will re-parse; just consume the value here.
       continue;
     }
-    if (arg.startsWith("--adapter=")) continue;
+    if (arg.startsWith("--adapter=") || arg.startsWith("--harness=")) continue;
     if (!out.eventName && !arg.startsWith("--")) {
       out.eventName = arg;
     } else {
@@ -160,7 +161,7 @@ function assignNameViaAgentCoord(
   instanceId: string,
   kind: "session" | "subagent" | "transient",
 ): { name: string; kind: string } | null {
-  const binary = join(coordRoot, "harnery", "bin", "agent-coord");
+  const binary = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(binary)) return null;
   try {
     const result = spawnSync(binary, ["assign-name", instanceId, kind], {
@@ -719,7 +720,7 @@ async function main(): Promise<number> {
   // subagent (claude-code + cursor; codex doesn't fan out subagents today).
   if (norm.event_type === "subagent.start") {
     try {
-      const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+      const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
       if (existsSync(agentCoordBin)) {
         spawnSync(agentCoordBin, ["project"], {
           encoding: "utf8",
@@ -747,7 +748,7 @@ async function main(): Promise<number> {
   if (norm.event_type === "subagent.stop") {
     try {
       cleanupSessionEnd(coordRoot, owner.instance_id, (data.reason as string) ?? "unknown");
-      const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+      const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
       if (existsSync(agentCoordBin)) {
         spawnSync(
           agentCoordBin,
@@ -1037,7 +1038,7 @@ async function runPreToolUseGuard(
     .filter((p): p is string => p !== null);
   if (targets.length === 0) return;
 
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) return;
 
   // For apply_patch (multi-file), collect siblings so the deny reason names
@@ -1142,7 +1143,7 @@ function healHeartbeatViaCli(
   sessionId: string,
   adapter: string,
 ): void {
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) return;
   // Pass the detected adapter so a pruned Cursor/Codex heartbeat is recreated
   // with the correct platform; without it, healHeartbeat defaults to
@@ -1255,7 +1256,7 @@ function stampToolActivity(
   instanceId: string,
   data: Record<string, unknown>,
 ): void {
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) return;
   const toolName = (data.tool_name as string | undefined) ?? "";
   // Extract a 1-line target from the tool_input blob (file path / command head).
@@ -1327,7 +1328,7 @@ function releaseClaimOnFailure(
       : filePath;
   }
 
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) return;
   spawnSync(agentCoordBin, ["release-claim", instanceId, canonical], {
     encoding: "utf8",
@@ -1368,7 +1369,7 @@ function cleanupSessionEnd(coordRoot: string, instanceId: string, reason: string
     }
   }
   // Activity log
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (existsSync(agentCoordBin)) {
     spawnSync(
       agentCoordBin,
@@ -1385,7 +1386,7 @@ async function emitUserPromptSubmitSystemMessage(
   adapter: Adapter,
   recoveryBriefing = "",
 ): Promise<boolean> {
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   let additionalContext = "";
 
   if (existsSync(agentCoordBin)) {
@@ -1445,7 +1446,7 @@ function emitSubagentStartContext(
   // Render peer table inline since the subagent might want to know who else
   // is around. Reuse prompt-context (which dedups against the per-owner hash);
   // first call will always emit.
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   let combined = message;
   if (existsSync(agentCoordBin)) {
     const result = spawnSync(
@@ -1477,7 +1478,7 @@ async function emitSessionStartSystemMessage(
   adapter: Adapter,
   recoveryBriefing = "",
 ): Promise<boolean> {
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   let additionalContext = "";
   if (existsSync(agentCoordBin)) {
     // Sync-project so the heartbeat exists for downstream readers (peer table,

package/src/core/hooks/effects/index.ts

@@ -17,6 +17,7 @@ import { existsSync, readdirSync, rmSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
 import { applyDetection } from "../../../lib/presence.ts";
+import { coordBinPath } from "../../agents/coord-bin.ts";
 
 export type { CaptureContext } from "./image-capture.ts";
 export { captureImages, imageJanitor } from "./image-capture.ts";
@@ -62,8 +63,7 @@ export function soundForEvent(eventName: string): { sound: string; maxPlays: num
 }
 
 function harnBin(repoRoot: string): string | null {
-  const bin = join(repoRoot, "harnery", "bin", "harn");
-  return existsSync(bin) ? bin : null;
+  return coordBinPath("harn", repoRoot);
 }
 
 /** Prune stale journal archives + sweep orphans (global, fast). Fire-and-forget. */

package/src/core/hooks/resolve/coord-root.ts

@@ -1,47 +1,25 @@
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { coordEnv } from "../../../lib/env.ts";
+import { resolveCoordRoot } from "../../agents/coord-client.ts";
 
 /**
- * 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: string = process.cwd()): string | null {
-  // 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: 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;
-  }
+  return resolveCoordRoot(start);
 }

package/src/lib/context/index.ts

@@ -156,7 +156,17 @@ function buildSelf(): SelfSection {
   const owner = resolveOwner();
   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))