harnery 0.31.0 → 0.31.2

package/dist/core/agents/coord-client.d.ts

@@ -50,14 +50,55 @@ 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 declare function monorepoRoot(): string | null;
+/**
+ * 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 declare function resolveCoordRoot(start?: string): string | null;
+/** Nearest enclosing directory carrying `.harnery/`, or null. */
+export declare function nearestCoordRoot(start: string): string | 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 declare function rootKnowsSession(root: string): boolean;
 /** Parse owner from a pid-map row (`owner` or `owner\tplatform`). */
 export declare function parsePidmapRowOwner(row: string): string;
 /** Parse platform from a pid-map row; legacy rows default to `claude_code`. */
@@ -105,6 +146,16 @@ export declare function resolveOwnerWithSource(): {
     owner: string | null;
     source: "env" | "pidmap" | "pidmap_fallback" | "session_env" | "active_singleton" | "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 declare function resolveOwnerByPidmap(root: string): {
+    owner: string | null;
+    source: "pidmap" | "pidmap_fallback" | "none";
+};
 /**
  * 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

package/dist/core/agents/coord-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coord-client.d.ts","sourceRoot":"","sources":["../../../src/core/agents/coord-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAWhE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAI5E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOhF;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yIAAyI;IACzI,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mEAAmE;IACnE,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CA0C5C;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA2CxD;AAgCD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,iBAAiB,GAAG,aAAa,GAAG,kBAAkB,GAAG,MAAM,CAAC;CAC5F,CA2DA;AA0DD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA2BpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyBpE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMlE;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC"}
+{"version":3,"file":"coord-client.d.ts","sourceRoot":"","sources":["../../../src/core/agents/coord-client.ts"],"names":[],"mappings":"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"}

package/dist/core/agents/coord-client.js

@@ -8,7 +8,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.
 const MAX_INSTANCE_ID_LENGTH = 128;
@@ -53,52 +53,171 @@ export function resolveContainedFile(directory, fileName) {
 /**
  * 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() {
-    // 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 = process.cwd()) {
     const rootOverride = process.env.HARNERY_COORD_ROOT_OVERRIDE;
-    if (rootOverride) {
+    if (rootOverride)
         return rootOverride;
+    const projectDir = process.env.CLAUDE_PROJECT_DIR;
+    if (projectDir) {
+        const fromProject = nearestCoordRoot(projectDir);
+        if (fromProject)
+            return fromProject;
+    }
+    // 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;
+    }
+    // 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];
+    if (gitRoots.length > 0)
+        return gitRoots[0];
+    // 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) {
+    return ancestorCoordRoots(start)[0] ?? null;
+}
+/** Every enclosing directory carrying `.harnery/`, nearest first. */
+function ancestorCoordRoots(start) {
+    const found = [];
+    let dir = resolve(start);
+    while (true) {
+        if (existsSync(join(dir, ".harnery")))
+            found.push(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
     }
-    // 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();
-    }
-    // 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);
-        }
+    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) {
+    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) {
+    const roots = [];
+    const push = (value) => {
+        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) {
+    return gitRevParse(start, "--show-toplevel");
+}
+function gitRevParse(cwd, flag) {
+    const key = `${cwd}${flag}`;
+    const cached = gitRevParseCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    let value = 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;
     }
-    // 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();
+    catch {
+        value = null;
     }
-    return 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();
 /** Parse owner from a pid-map row (`owner` or `owner\tplatform`). */
 export function parsePidmapRowOwner(row) {
     const trimmed = row.trim();
@@ -255,6 +374,29 @@ export function resolveOwnerWithSource() {
             return { owner: bySession, source: "session_env" };
         }
     }
+    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) {
     const pidmapDir = resolve(root, ".harnery", "pid-map");
     if (!existsSync(pidmapDir))
         return { owner: null, source: "none" };
@@ -279,15 +421,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/dist/core/agents/paths.d.ts

@@ -1,6 +1,9 @@
 /**
- * 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 declare function findCoordRoot(start?: string): string | null;
 //# sourceMappingURL=paths.d.ts.map

package/dist/core/agents/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/core/agents/paths.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAQ1E"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/core/agents/paths.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAE1E"}

package/dist/core/agents/paths.js

@@ -1,17 +1,11 @@
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { resolveCoordRoot } from "./coord-client.js";
 /**
- * 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 = process.cwd()) {
-    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/core/hooks/adapter/detect.d.ts

@@ -1,8 +1,10 @@
 import type { Adapter } from "../events/schema.js";
 /**
  * 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 declare function detectAdapter(argv: readonly string[]): Adapter | null;

package/dist/core/hooks/adapter/detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/adapter/detect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,GAAG,IAAI,CAWrE"}
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/adapter/detect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,GAAG,IAAI,CAcrE"}

package/dist/core/hooks/adapter/detect.js

@@ -1,21 +1,26 @@
 import { coordEnv } from "../../../lib/env.js";
 /**
  * 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) {
     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) {
     if (v === "claude-code" || v === "cursor" || v === "codex")

package/dist/core/hooks/cli.js

@@ -22,6 +22,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { coordEnv } from "../../lib/env.js";
 import { replayCodexJsonl } from "../agents/codex-replay.js";
+import { coordBinPath } from "../agents/coord-bin.js";
 import { consumeSince, writeCursor } from "../agents/events/consume.js";
 import { evaluateStopHook } from "../agents/rules/stop-hook.js";
 import { projectHeartbeats } from "../agents/state/heartbeat-projector.js";
@@ -43,11 +44,11 @@ function parseArgv(argv) {
     const out = { 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="))
+        if (arg.startsWith("--adapter=") || arg.startsWith("--harness="))
             continue;
         if (!out.eventName && !arg.startsWith("--")) {
             out.eventName = arg;
@@ -118,7 +119,7 @@ function logError(coordRoot, err, context) {
  * separation: we spawn rather than import.
  */
 function assignNameViaAgentCoord(coordRoot, instanceId, kind) {
-    const binary = join(coordRoot, "harnery", "bin", "agent-coord");
+    const binary = coordBinPath("agent-coord", coordRoot) ?? "";
     if (!existsSync(binary))
         return null;
     try {
@@ -620,7 +621,7 @@ async function main() {
     // 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",
@@ -644,7 +645,7 @@ async function main() {
     if (norm.event_type === "subagent.stop") {
         try {
             cleanupSessionEnd(coordRoot, owner.instance_id, data.reason ?? "unknown");
-            const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+            const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
             if (existsSync(agentCoordBin)) {
                 spawnSync(agentCoordBin, [
                     "log",
@@ -907,7 +908,7 @@ async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, adapte
         .filter((p) => 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
@@ -1008,7 +1009,7 @@ function parseApplyPatchPaths(data) {
     return out;
 }
 function healHeartbeatViaCli(coordRoot, instanceId, sessionId, adapter) {
-    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
@@ -1118,7 +1119,7 @@ function refreshPidmap(coordRoot, instanceId, adapter, payloadPid) {
     writePidmapViaAgentCoord(coordRoot, pid, instanceId, adapterPlatform(adapter));
 }
 function stampToolActivity(coordRoot, instanceId, data) {
-    const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+    const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
     if (!existsSync(agentCoordBin))
         return;
     const toolName = data.tool_name ?? "";
@@ -1188,7 +1189,7 @@ function releaseClaimOnFailure(coordRoot, instanceId, data, rawPayload) {
             ? filePath.slice(coordRoot.length + 1)
             : 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], {
@@ -1232,13 +1233,13 @@ function cleanupSessionEnd(coordRoot, instanceId, reason) {
         }
     }
     // Activity log
-    const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+    const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
     if (existsSync(agentCoordBin)) {
         spawnSync(agentCoordBin, ["log", `SESSION_END     reason=${reason}`, "--instance", instanceId], { encoding: "utf8", timeout: 2000 });
     }
 }
 async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionId, adapter, recoveryBriefing = "") {
-    const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+    const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
     let additionalContext = "";
     if (existsSync(agentCoordBin)) {
         // Look up the agent's name from its heartbeat (for council pending rendering).
@@ -1293,7 +1294,7 @@ function emitSubagentStartContext(coordRoot, instanceId, sessionId, data, adapte
     // 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(agentCoordBin, ["prompt-context", "--instance", instanceId, "--session", sessionId, "--name", subagentName], { encoding: "utf8", timeout: 3000 });
@@ -1313,7 +1314,7 @@ function adapterPlatform(adapter) {
     return adapter;
 }
 async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, emittedData, adapter, recoveryBriefing = "") {
-    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/dist/core/hooks/effects/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/effects/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,SAAI,GACX,IAAI,CAYN;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW3F;AAOD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa3D;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAYpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAqB9E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,IAAI,CAqBN;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAa1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOnD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/effects/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,SAAI,GACX,IAAI,CAYN;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW3F;AAMD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa3D;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAYpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAqB9E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,IAAI,CAqBN;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAa1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOnD"}

package/dist/core/hooks/effects/index.js

@@ -16,6 +16,7 @@ import { existsSync, readdirSync, rmSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
 import { applyDetection } from "../../../lib/presence.js";
+import { coordBinPath } from "../../agents/coord-bin.js";
 export { captureImages, imageJanitor } from "./image-capture.js";
 /**
  * Play a notification sound via the cross-platform utility
@@ -53,8 +54,7 @@ export function soundForEvent(eventName) {
     }
 }
 function harnBin(repoRoot) {
-    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. */
 export function journalJanitor(repoRoot) {

package/dist/core/hooks/resolve/coord-root.d.ts

@@ -1,17 +1,22 @@
 /**
- * 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 declare function findCoordRoot(start?: string): string | null;
 //# sourceMappingURL=coord-root.d.ts.map

package/dist/core/hooks/resolve/coord-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coord-root.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/coord-root.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAiB1E"}
+{"version":3,"file":"coord-root.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/coord-root.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAE1E"}