harnery 0.30.0 → 0.31.1

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.
@@ -73,7 +73,7 @@ export interface Heartbeat {
   last_tool_target?: string;
   /** Free-form task/intent string set via `harn agents set-task`. Phase 2. */
   task?: string;
-  /** UTC ISO-8601 timestamp when task was last set/cleared. Used by harnesses without Stop enforcement to compute staleness. 2026-05-24. */
+  /** UTC ISO-8601 timestamp when task was last set/cleared. Used by adapters without Stop enforcement to compute staleness. 2026-05-24. */
   task_updated_at?: string | null;
   /** Auto-generated per-turn summary written by the Stop hook via Haiku. 2026-05-23. */
   turn_summary?: string | null;
@@ -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;
+  }
+
+  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;
+}
+
+/**
+ * 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;
+}
 
-  // 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();
+/**
+ * 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));
   }
 
-  return null;
+  // 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();
@@ -146,9 +262,93 @@ export function parsePidmapRowOwner(row: string): string {
 
 /** Parse platform from a pid-map row; legacy rows default to `claude_code`. */
 export function parsePidmapRowPlatform(row: string): string {
-  const trimmed = row.trim();
-  const tab = trimmed.indexOf("\t");
-  return tab >= 0 ? trimmed.slice(tab + 1).trim() : "claude_code";
+  const platform = row.trim().split("\t")[1]?.trim();
+  return platform || "claude_code";
+}
+
+/** Parse the start token from a pid-map row; rows written before it carry none. */
+export function parsePidmapRowStartToken(row: string): string | undefined {
+  return row.trim().split("\t")[2]?.trim() || undefined;
+}
+
+/**
+ * Is the process now holding `pid` the one this row was written for?
+ *
+ * A pid is a number the OS re-issues, and quickly: a `pid_max` of 99999 against
+ * ~100 new processes a second recycles the whole space about every quarter
+ * hour. Believing a row past that point resolves this session to whichever
+ * agent last held the number — which is what made `whoami` report a stranger's
+ * name and files. The start token settles it, since two processes may share a
+ * pid but never a pid and a start instant.
+ *
+ * Deliberately inlined rather than imported from `state/proc-start.ts`: this
+ * file is vendored verbatim into a downstream consumer and stays on node
+ * builtins only. The token is a wire format shared with that module and with
+ * the host's commit guard, so the copies must agree byte for byte; exported so
+ * a test can hold this one against `processStartToken` and fail on drift.
+ */
+export function pidStartToken(pid: number): string | null {
+  const forced = process.env.HARNERY_PID_PROBE;
+  const useProcfs = forced === "procfs" || (forced !== "ps" && existsSync("/proc/self/stat"));
+  // One machine, one probe. Falling back to the other on a read failure would
+  // answer in the wrong dialect and read as a recycled pid.
+  if (useProcfs) {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+      const afterComm = stat.slice(stat.lastIndexOf(") ") + 2);
+      // Fields after comm, 0-based: 0 is state (field 3), starttime (22) is 19.
+      const ticks = afterComm.split(" ")[19];
+      if (!ticks || !/^\d+$/.test(ticks)) return null;
+      // Ticks count from boot, so they repeat across reboots; the boot id scopes
+      // them. Rows written before it carry ticks alone and still compare.
+      let boot = "";
+      try {
+        const raw = readFileSync("/proc/sys/kernel/random/boot_id", "utf8")
+          .trim()
+          .replace(/-/g, "");
+        if (/^[0-9a-f]{8,}$/.test(raw)) boot = `${raw.slice(0, 8)}.`;
+      } catch {
+        /* unnamed boot: fall back to the tick-only shape */
+      }
+      return `l${boot}${ticks}`;
+    } catch {
+      return null;
+    }
+  }
+  try {
+    // TZ and locale are pinned because `ps` renders the date through them, and
+    // two callers with different environments must not disagree about one
+    // process.
+    const out = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf8",
+      timeout: 2000,
+      env: { ...process.env, TZ: "UTC", LC_ALL: "C" },
+    });
+    if (out.status !== 0) return null;
+    const lstart = (out.stdout ?? "").split("\n")[0]?.trim().replace(/\s+/g, " ");
+    return lstart ? `p${lstart}` : null;
+  } catch {
+    return null;
+  }
+}
+
+function pidWasRecycled(pid: number, row: string): boolean {
+  const recorded = parsePidmapRowStartToken(row);
+  if (!recorded) return false; // pre-token row: unverifiable, behave as before
+  const current = pidStartToken(pid);
+  if (!current) return false;
+  if (current === recorded) return false;
+  // A row predating the boot segment recorded ticks alone; compare it on what
+  // it recorded rather than pruning every live row on the first upgraded run.
+  if (
+    recorded[0] === "l" &&
+    current[0] === "l" &&
+    recorded.includes(".") !== current.includes(".")
+  ) {
+    const ticks = (t: string) => (t.includes(".") ? t.slice(t.indexOf(".") + 1) : t.slice(1));
+    return ticks(recorded) !== ticks(current);
+  }
+  return true;
 }
 
 function readPidmapRow(pidmapDir: string, pid: number): string | null {
@@ -197,9 +397,14 @@ export function resolveOwnerWithSource(): {
   const root = monorepoRoot();
   if (!root) return { owner: null, source: "none" };
 
-  // Cursor's Glass/Agents UI can run several chats under one long-lived node
-  // process, so the pid-map row for that shared ancestor is last-writer-wins.
-  // Prefer the per-chat session id when Cursor exposes one in the tool env.
+  // Every supported adapter exports its session id into the env of the
+  // subprocess it spawns for a tool call, and each heartbeat records the
+  // session id it was minted under. Matching the two names us outright, even
+  // with many live agents, so it goes ahead of the ppid walk rather than
+  // catching what the walk drops. Cursor needed this first because its
+  // Glass/Agents UI runs several chats under one node ancestor, making that row
+  // last-writer-wins; pid recycling generalises the same hazard to every
+  // adapter.
   if (shouldPreferSessionEnv()) {
     const bySession = resolveOwnerBySessionEnv(root);
     if (bySession) {
@@ -207,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" };
 
@@ -217,7 +450,7 @@ export function resolveOwnerWithSource(): {
   for (let hop = 0; hop < 20; hop++) {
     if (pid === null) break;
     const row = readPidmapRow(pidmapDir, pid);
-    if (row) {
+    if (row && !pidWasRecycled(pid, row)) {
       const rowOwner = parsePidmapRowOwner(row);
       const rowPlat = parsePidmapRowPlatform(row);
       if (rowPlat === prefer) {
@@ -230,35 +463,12 @@ export function resolveOwnerWithSource(): {
   if (fallbackOwner) {
     return { owner: fallbackOwner, source: "pidmap_fallback" };
   }
-
-  // The ppid walk found nothing (e.g. a Bash-tool subshell whose process tree
-  // doesn't climb back to the harness anchor). Before guessing, try the
-  // harness-provided session id from the environment: every supported harness
-  // exports its session id into the tool subprocess env, and each heartbeat
-  // records the `session_id` it was minted under. Matching the two resolves us
-  // unambiguously even with multiple live agents, which is the case the
-  // singleton fallback below cannot handle.
-  const bySession = resolveOwnerBySessionEnv(root);
-  if (bySession) {
-    return { owner: bySession, source: "session_env" };
-  }
-
-  // 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" };
 }
 
 /**
- * Harness-exported session-id environment variables, in precedence order. Each
- * supported harness propagates its session id into the env of the subprocess it
+ * Adapter-exported session-id environment variables, in precedence order. Each
+ * supported adapter propagates its session id into the env of the subprocess it
  * spawns for a tool call (Claude Code's Bash tool, Cursor's terminal, Codex's
  * shell). A coord CLI invoked as such a tool can therefore recover its own
  * identity from the env even when the ppid walk misses.
@@ -274,7 +484,7 @@ const SESSION_ID_ENV_VARS = [
   "CODEX_SESSION_ID",
 ] as const;
 
-/** Read normalized candidates from the first non-empty harness session-id env var. */
+/** Read normalized candidates from the first non-empty adapter session-id env var. */
 function sessionIdsFromEnv(): string[] {
   for (const key of SESSION_ID_ENV_VARS) {
     const v = process.env[key]?.trim();
@@ -287,19 +497,33 @@ function sessionIdsFromEnv(): string[] {
   return [];
 }
 
-/** Read the first non-empty harness session-id env var, or null. */
+/** Read the first non-empty adapter session-id env var, or null. */
 function sessionIdFromEnv(): string | null {
   return sessionIdsFromEnv()[0] ?? null;
 }
 
+/**
+ * Should the adapter-exported session id be consulted before the ppid walk?
+ *
+ * Yes, whenever one is exported. The env var is the adapter stating its own
+ * identity; the walk is a guess over a namespace the OS recycles. On a box with
+ * `pid_max` of 99999 and ~100 pids allocated per second the whole pid space
+ * turns over about every quarter hour, so a row written before that can name a
+ * pid some unrelated process now holds. Pruning cannot save the walk here:
+ * it removes rows whose pid is dead, and a recycled pid is alive. Letting a
+ * guess outrank a statement of fact is what made `agents whoami` report another
+ * agent's name and file list.
+ *
+ * This only reorders the two. Session-env resolution still requires a live
+ * heartbeat carrying that session id, so when it does not match, the walk runs
+ * exactly as before.
+ */
 function shouldPreferSessionEnv(): boolean {
-  if (!sessionIdFromEnv()) return false;
-  const platform = process.env.HARNERY_AGENT_COORD_PLATFORM?.trim();
-  return process.env.CURSOR_AGENT === "1" || platform === "cursor";
+  return sessionIdFromEnv() !== null;
 }
 
 /**
- * Resolve the owner by matching the harness session-id env var against the
+ * Resolve the owner by matching the adapter session-id env var against the
  * `session_id` of a live heartbeat in this coord root. Returns the matching
  * `instance_id`, or null if there's no session-id env var or no live heartbeat
  * carries it. "Live" reuses the same 10-minute freshness window the singleton

package/src/core/agents/events/consume.ts

@@ -56,7 +56,7 @@ export interface CanonicalEvent {
   parent_session_id?: string;
   turn_id?: string;
   parent_turn_id?: string;
-  harness: string;
+  adapter: string;
   source: string;
   data: Record<string, unknown>;
 }

package/src/core/agents/events/emit.ts

@@ -5,7 +5,7 @@
  * event/schema types).
  *
  * Phase 4: agent-coord uses this from CLI handlers (state.task_set,
- * state.status_checked, state.scratch_append, council.*, decision.*,
+ * state.status_checked, state.journal_append, council.*, decision.*,
  * presence.*).
  */
 
@@ -19,8 +19,9 @@ const STREAM_FILE = ".harnery/events.ndjson";
 const LOCK_FILE = ".harnery/events.ndjson.lock";
 const MAX_LINE_BYTES = 64 * 1024;
 
-export type Harness = "claude-code" | "cursor" | "codex";
-export type Source = "agent-hooks" | "agent-coord" | "user" | "system";
+export type { Adapter, Source } from "../../hooks/events/schema.ts";
+
+import type { Adapter, Source } from "../../hooks/events/schema.ts";
 
 export interface Envelope {
   schema_version: typeof SCHEMA_VERSION;
@@ -32,7 +33,7 @@ export interface Envelope {
   parent_session_id?: string;
   turn_id?: string;
   parent_turn_id?: string;
-  harness: Harness;
+  adapter: Adapter;
   source: Source;
   data: Record<string, unknown>;
 }
@@ -41,7 +42,7 @@ export interface EmitInput {
   event_type: string;
   instance_id: string;
   session_id: string;
-  harness: Harness;
+  adapter: Adapter;
   source?: Source;
   parent_session_id?: string;
   turn_id?: string;
@@ -61,7 +62,7 @@ export function buildEnvelope(input: EmitInput): Envelope {
     parent_session_id: input.parent_session_id,
     turn_id: input.turn_id,
     parent_turn_id: input.parent_turn_id,
-    harness: input.harness,
+    adapter: input.adapter,
     source: input.source ?? "agent-coord",
     data: input.data,
   };

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);
 }