harnery 0.3.2 → 0.5.0

package/src/commands/{uninstall.ts → deinit.ts}

@@ -1,5 +1,5 @@
 /**
- * `harn uninstall`: reverse what `harn init` wired into a project.
+ * `harn deinit`: reverse what `harn init` wired into a project.
  *
  * `init` makes two kinds of change outside the harnery package:
  *   1. Merges `agent-hook` entries into the harness settings file
@@ -9,42 +9,60 @@
  *      identities, scratch) and stamps the host bin name into
  *      `.harnery/config.jsonc`.
  *
- * `uninstall` undoes (1) by default: it removes only harnery's hook entries from
+ * `deinit` undoes (1) by default: it removes only harnery's hook entries from
  * the settings file, preserving any other hooks the consumer added, and deletes
  * the settings file outright when it's left harnery-only. It does NOT touch the
  * `.harnery/` coord root unless `--purge-state` is passed, because that directory
  * holds session history a consumer may want to keep. Idempotent + `--dry-run`,
  * mirroring `init`.
+ *
+ * For standalone `harn` on a terminal it also handles the destructive extra
+ * conversationally: when `--purge-state` wasn't passed and `.harnery/` exists, it
+ * asks before deleting it, and afterward it prints how to remove the harnery CLI
+ * itself (which a running process can't do to its own package). Both are gated to
+ * standalone harn — an embedding host routes output through its own emit and owns
+ * its install lifecycle — and the prompt never fires off a TTY, so scripted / CI
+ * runs keep the flag-driven behavior untouched. The shell wrapper `scripts/teardown.sh`
+ * is the fuller mirror (it also unlinks the PATH bins and can delete the clone).
  */
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
+import { createInterface } from "node:readline";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { DEFAULT_BIN_NAME } from "../core/config.ts";
 import { HARNESS_SPECS, type HarnessId } from "../core/hooks/harness/events.ts";
 import { type SettingsFile, unwireHooks } from "./init.ts";
 
-interface UninstallOpts {
+interface DeinitOpts {
   harness: string;
   dryRun?: boolean;
   projectRoot?: string;
   purgeState?: boolean;
 }
 
-export function registerUninstallCommand(program: Command, emit: EmitContext): void {
+export function registerDeinitCommand(program: Command, emit: EmitContext, binName?: string): void {
+  // The interactive prompt + engine-removal hint are standalone-harn niceties.
+  // An embedding host routes output through its own emit and owns its install
+  // lifecycle, so for a host (binName set + non-default) deinit stays strictly
+  // flag-driven and says nothing about removing "the package".
+  const standalone = !binName || binName === DEFAULT_BIN_NAME;
+
   program
-    .command("uninstall")
+    .command("deinit")
     .description(
       "Reverse `harn init`: remove harnery's hook entries from the harness " +
         "settings file (keeps any others). Pass --purge-state to also delete the " +
-        ".harnery/ coord root. Idempotent; use --dry-run to preview.",
+        ".harnery/ coord root (on a terminal it asks first). Idempotent; use " +
+        "--dry-run to preview.",
     )
     .option("--harness <id>", "claude-code | cursor | codex", "claude-code")
     .option("--dry-run", "Show what would change without writing")
     .option("--project-root <path>", "Project root (default: git toplevel, else cwd)")
     .option("--purge-state", "Also delete the .harnery/ coord root (runtime state, destructive)")
-    .action((opts: UninstallOpts) => {
+    .action(async (opts: DeinitOpts) => {
       const harness = opts.harness as HarnessId;
       const spec = HARNESS_SPECS[harness];
       if (!spec) {
@@ -55,8 +73,24 @@ export function registerUninstallCommand(program: Command, emit: EmitContext): v
 
       const projectRoot = resolve(opts.projectRoot ?? gitTopLevel() ?? process.cwd());
       const dryRun = opts.dryRun === true;
+      const coordDir = resolve(projectRoot, ".harnery");
+      const coordExists = existsSync(coordDir);
+      let purgeState = opts.purgeState === true;
       const actions: string[] = [];
 
+      // ── 0. interactive: offer to delete .harnery/ (standalone harn, TTY) ───
+      if (
+        shouldPromptForState({
+          standalone,
+          interactive: process.stdin.isTTY === true,
+          dryRun,
+          purgeState,
+          coordExists,
+        })
+      ) {
+        purgeState = await confirmDeleteState(coordDir);
+      }
+
       // ── 1. unwire harness hooks ────────────────────────────────────────────
       const settingsPath = resolve(projectRoot, spec.settingsFile);
       if (!existsSync(settingsPath)) {
@@ -100,9 +134,8 @@ export function registerUninstallCommand(program: Command, emit: EmitContext): v
       }
 
       // ── 2. coord root (opt-in; destructive) ────────────────────────────────
-      const coordDir = resolve(projectRoot, ".harnery");
-      if (opts.purgeState) {
-        if (!existsSync(coordDir)) {
+      if (purgeState) {
+        if (!coordExists) {
           actions.push("· .harnery/ doesn't exist; nothing to purge");
         } else if (dryRun) {
           actions.push("+ would delete .harnery/ and all coord state (events, councils, scratch)");
@@ -110,12 +143,65 @@ export function registerUninstallCommand(program: Command, emit: EmitContext): v
           rmSync(coordDir, { recursive: true, force: true });
           actions.push("+ deleted .harnery/ and all coord state");
         }
-      } else if (existsSync(coordDir)) {
+      } else if (coordExists) {
         actions.push("· left .harnery/ coord root in place (pass --purge-state to delete it)");
       }
 
-      emit.text(render(projectRoot, dryRun, actions));
+      const hint = standalone && !dryRun ? engineRemovalHint() : null;
+      emit.text(render(projectRoot, dryRun, actions, hint));
+    });
+}
+
+/**
+ * Whether to interactively ask before deleting `.harnery/`. True only for
+ * standalone harn on a TTY, when the user didn't already answer with
+ * --purge-state, it isn't a dry run, and there's actually a coord root to
+ * delete. Pure so the gating is unit-testable without a terminal.
+ */
+export function shouldPromptForState(o: {
+  standalone: boolean;
+  interactive: boolean;
+  dryRun: boolean;
+  purgeState: boolean;
+  coordExists: boolean;
+}): boolean {
+  return o.standalone && o.interactive && !o.dryRun && !o.purgeState && o.coordExists;
+}
+
+/**
+ * The "harnery itself is still installed" line shown to standalone-harn users
+ * after a real deinit. `harn deinit` can't remove the package it's running
+ * from, so it points at the two ways to finish the job. Pure + exported for the
+ * test.
+ */
+export function engineRemovalHint(): string {
+  return (
+    "harnery itself is still installed. To remove the CLI too: `npm rm -g harnery` " +
+    "(if you installed it with npm/bun); from a git clone, " +
+    "`scripts/teardown.sh --remove-clone` removes the checkout."
+  );
+}
+
+/** Mirror scripts/teardown.sh's wording: explain what .harnery/ holds, then ask. */
+function confirmDeleteState(coordDir: string): Promise<boolean> {
+  process.stdout.write(
+    "\nharnery saved this project's coordination history in .harnery/\n" +
+      "(its event log, councils, agent identities, and scratchpads):\n" +
+      `    ${coordDir}\n` +
+      "Unwiring leaves that in place. Deleting it can't be undone.\n",
+  );
+  return confirm("Delete this project's harnery history too? [y/N]");
+}
+
+/** Read one y/N answer from the TTY. Yes only on an explicit y / yes. */
+function confirm(question: string): Promise<boolean> {
+  return new Promise((resolveAnswer) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`${question} `, (answer) => {
+      rl.close();
+      resolveAnswer(/^y(es)?$/i.test(answer.trim()));
     });
+  });
 }
 
 /** True when an unwired settings object holds nothing but (optionally) `version`. */
@@ -124,12 +210,18 @@ function harnessOnly(settings: SettingsFile): boolean {
   return keys.length === 0 || (keys.length === 1 && keys[0] === "version");
 }
 
-function render(projectRoot: string, dryRun: boolean, actions: string[]): string {
-  const head = dryRun ? "harn uninstall (dry run): no changes written" : "harn uninstall";
+function render(
+  projectRoot: string,
+  dryRun: boolean,
+  actions: string[],
+  hint: string | null,
+): string {
+  const head = dryRun ? "harn deinit (dry run): no changes written" : "harn deinit";
   const tail = dryRun
     ? "\nRe-run without --dry-run to apply."
     : "\nDone. harnery hooks are unwired; restart your harness session to drop them.";
-  return `${head}\n  root: ${projectRoot}\n${actions.map((a) => `  ${a}`).join("\n")}${tail}`;
+  const hintBlock = hint ? `\n\n${hint}` : "";
+  return `${head}\n  root: ${projectRoot}\n${actions.map((a) => `  ${a}`).join("\n")}${tail}${hintBlock}`;
 }
 
 function gitTopLevel(): string | null {

package/src/commands/doctor.ts

@@ -17,6 +17,8 @@ import os from "node:os";
 import path from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { resolveBinName } from "../core/config.ts";
+import { loadHarnessWiring } from "../core/hooks/harness/wiring.ts";
 
 type Severity = "ok" | "warn" | "fail";
 
@@ -79,6 +81,7 @@ export function runChecks(): Check[] {
     checkGit(),
     checkBun(),
     checkHarneryDir(),
+    checkHarnessHooks(),
     checkRestic(),
     checkRclone(),
     checkPlaywright(),
@@ -203,21 +206,23 @@ function checkPython(): Check {
   return { name: "python3", severity: "ok", detail: r.out };
 }
 
-function checkHarneryDir(): Check {
-  // Walk up from cwd looking for .harnery/.
+/** Walk up from cwd to the nearest dir containing `.harnery/`; null if none. */
+function findCoordProjectRoot(): string | null {
   let dir = process.cwd();
   for (let i = 0; i < 8; i++) {
-    if (existsSync(path.join(dir, ".harnery"))) {
-      return {
-        name: ".harnery/",
-        severity: "ok",
-        detail: path.join(dir, ".harnery"),
-      };
-    }
+    if (existsSync(path.join(dir, ".harnery"))) return dir;
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
+  return null;
+}
+
+function checkHarneryDir(): Check {
+  const root = findCoordProjectRoot();
+  if (root) {
+    return { name: ".harnery/", severity: "ok", detail: path.join(root, ".harnery") };
+  }
   return {
     name: ".harnery/",
     severity: "warn",
@@ -226,6 +231,39 @@ function checkHarneryDir(): Check {
   };
 }
 
+/**
+ * Compare the project's wired harness hooks against HARNESS_SPECS. Catches the
+ * post-upgrade case where a harnery release added (or renamed) a hook event but
+ * the consumer's settings file hasn't been re-wired. Only fires for a harness
+ * the project has opted into (≥1 harnery hook already wired) — see
+ * loadHarnessWiring — so a bare settings file never false-warns. The remedy is
+ * always the same: re-run `<bin> init` (idempotent, additive).
+ */
+function checkHarnessHooks(): Check {
+  const root = findCoordProjectRoot();
+  if (!root) {
+    return { name: "harness hooks", severity: "ok", detail: "n/a (no .harnery/ above cwd)" };
+  }
+  const drift = loadHarnessWiring(root);
+  if (drift.length === 0) {
+    return { name: "harness hooks", severity: "ok", detail: "wired + current" };
+  }
+  const bin = resolveBinName(root);
+  const parts = drift.map((d) => {
+    const bits: string[] = [];
+    if (d.missing.length > 0) {
+      bits.push(`${d.missing.length} missing (${d.missing.map((m) => m.subcommand).join(", ")})`);
+    }
+    if (d.orphans.length > 0) bits.push(`${d.orphans.length} orphaned (${d.orphans.join(", ")})`);
+    return `${d.settingsFile}: ${bits.join("; ")}`;
+  });
+  const hasOrphans = drift.some((d) => d.orphans.length > 0);
+  const hint = hasOrphans
+    ? `run \`${bin} init\` to wire missing hooks; remove orphaned entries (renamed/dropped events) with \`${bin} deinit\` then \`${bin} init\``
+    : `run \`${bin} init\` to wire the new hook(s) (idempotent)`;
+  return { name: "harness hooks", severity: "warn", detail: parts.join("  |  "), hint };
+}
+
 function macOrLinux(mac: string, linux: string): string {
   return os.platform() === "darwin" ? mac : linux;
 }

package/src/commands/init.ts

@@ -23,12 +23,18 @@ import { fileURLToPath } from "node:url";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { DEFAULT_BIN_NAME, stripJsonComments } from "../core/config.ts";
+import { HARNESS_SPECS, type HarnessId, type HarnessSpec } from "../core/hooks/harness/events.ts";
 import {
-  HARNESS_SPECS,
-  type HarnessId,
-  type HarnessSpec,
-  type HookEntryShape,
-} from "../core/hooks/harness/events.ts";
+  commandWiresSubcommand,
+  groupCommands,
+  type HookGroup,
+  makeEntry,
+  type SettingsFile,
+} from "../core/hooks/harness/wiring.ts";
+
+// Re-exported for back-compat: callers (deinit, tests) import these names
+// from init.ts. The definitions now live in core/hooks/harness/wiring.ts.
+export type { HookGroup, SettingsFile };
 
 // This file is src/commands/init.ts → harnery package root is two levels up.
 const HARNERY_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -39,25 +45,6 @@ interface InitOpts {
   projectRoot?: string;
 }
 
-/** Claude Code + Codex entry: `{ hooks: [{ type, command }] }`. */
-interface ClaudeHookGroup {
-  matcher?: string;
-  hooks: { type: string; command: string }[];
-}
-/** Cursor entry: a flat `{ command }`. */
-interface CursorHookGroup {
-  command: string;
-  type?: string;
-  matcher?: string;
-}
-type HookGroup = ClaudeHookGroup | CursorHookGroup;
-
-export interface SettingsFile {
-  version?: number;
-  hooks?: Record<string, HookGroup[]>;
-  [k: string]: unknown;
-}
-
 export function registerInitCommand(program: Command, emit: EmitContext, binName?: string): void {
   program
     .command("init")
@@ -173,7 +160,7 @@ export function wireHooks(
     const command = `bash ${agentHookPath} ${subcommand} --harness ${harness}`;
     const groups = settings.hooks[settingsKey] ?? [];
     const present = groups.some((g) =>
-      groupCommands(g).some((c) => c.includes(`agent-hook ${subcommand} `)),
+      groupCommands(g).some((c) => commandWiresSubcommand(c, subcommand)),
     );
     if (present) {
       already++;
@@ -217,20 +204,6 @@ export function unwireHooks(settings: SettingsFile): { removed: number; remainin
   return { removed, remaining };
 }
 
-/** Build a hook entry in the harness's shape. */
-function makeEntry(shape: HookEntryShape, command: string): HookGroup {
-  return shape === "cursor" ? { command } : { hooks: [{ type: "command", command }] };
-}
-
-/** Pull every command string out of a hook entry, regardless of shape. */
-function groupCommands(group: HookGroup): string[] {
-  if ("command" in group && typeof group.command === "string") return [group.command];
-  if ("hooks" in group && Array.isArray(group.hooks)) {
-    return group.hooks.map((h) => h.command).filter((c): c is string => typeof c === "string");
-  }
-  return [];
-}
-
 /**
  * Idempotently record `binName` in `.harnery/config.jsonc`, preserving any
  * existing JSONC comments and the `files` section. Returns an action line, or

package/src/core/agents/render/session-context.ts

@@ -10,7 +10,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { resolveBinName } from "../../config.ts";
+import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
+import { harneryVersion, loadHarnessWiring } from "../../hooks/harness/wiring.ts";
 
 interface HeartbeatRow {
   instance_id?: string;
@@ -69,13 +70,40 @@ export function renderSessionContext(opts: RenderOpts): string {
     if (councilMsg) messages.push(councilMsg);
   }
 
-  // 4. Wiring check
+  // 4. Commit-guard wiring check
   const wiringIssues = checkWiring(coordRoot);
   if (wiringIssues.length > 0) {
-    const wiringSummary = `Coordination hooks are NOT wired: the E-guard will not block conflicting commits, and post-commit claim pruning will not run. Run \`scripts/setup-hooks.sh\` to fix. Detected:\n${wiringIssues.map((i) => `  - ${i}`).join("\n")}`;
+    const hint = resolveHooksSetupHint(coordRoot);
+    const fix = hint
+      ? `Run \`${hint}\` to install them.`
+      : "Wire each repo's pre-commit hook to invoke `agent-coord verdict --rule=commit` (harnery's commit guard).";
+    const wiringSummary = `Coordination hooks are NOT wired: the E-guard will not block conflicting commits, and post-commit claim pruning will not run. ${fix} Detected:\n${wiringIssues.map((i) => `  - ${i}`).join("\n")}`;
     messages.push(wiringSummary);
   }
 
+  // 5. Harness-hook drift: a harnery upgrade changed the hook set, but this
+  // project's settings file hasn't been re-wired. Only fires for a harness the
+  // project already opted into (≥1 hook wired), so it never nags a project that
+  // simply has a settings file. Remedy is always `<bin> init` (idempotent).
+  const drift = loadHarnessWiring(coordRoot);
+  if (drift.length > 0) {
+    const bin = resolveBinName(coordRoot);
+    const ver = harneryVersion();
+    const verPart = ver ? ` (harnery ${ver})` : "";
+    const lines = drift.map((d) => {
+      const bits: string[] = [];
+      if (d.missing.length > 0)
+        bits.push(`missing: ${d.missing.map((m) => m.subcommand).join(", ")}`);
+      if (d.orphans.length > 0) bits.push(`orphaned: ${d.orphans.join(", ")}`);
+      return `  - ${d.settingsFile} — ${bits.join("; ")}`;
+    });
+    messages.push(
+      `Harnery hook wiring is out of date${verPart}: an upgrade changed the hook set but the harness ` +
+        `settings file hasn't been re-wired, so the new hook(s) won't fire. Run \`${bin} init\` to wire them ` +
+        `(idempotent, additive).\n${lines.join("\n")}`,
+    );
+  }
+
   return messages.join("\n\n");
 }
 
@@ -198,19 +226,25 @@ function fmtAge(secs: number): string {
 }
 
 /**
- * Returns a list of wiring issues (empty when everything's wired). Checks
- * parent core.hooksPath + one representative submodule.
+ * Returns a list of commit-guard wiring issues (empty when wired). Portable
+ * across host projects: it asserts the FUNCTIONAL property ("does this repo's
+ * pre-commit invoke harnery's guard?") rather than any path convention. For
+ * each repo it resolves the EFFECTIVE git-hooks dir via
+ * `git rev-parse --git-path hooks` (which already honors `core.hooksPath`,
+ * linked worktrees, and submodule gitdirs) and checks whether the `pre-commit`
+ * there calls `agent-coord` / `agent-hook`. Checks the parent repo + one
+ * representative submodule (others almost always share the same setup).
+ *
+ * harnery does not install git hooks itself — each host wires its own
+ * pre-commit to invoke the guard — so the remediation command is host-specific
+ * and supplied via `hooksSetupHint` in `.harnery/config.jsonc` (see the caller).
  */
 export function checkWiring(coordRoot: string): string[] {
-  const expected = join(coordRoot, "scripts", "hooks");
   const issues: string[] = [];
 
-  // Parent repo
-  const parentHp = gitConfig(coordRoot, "core.hooksPath");
-  const parentResolved = resolveHooksPath(coordRoot, parentHp);
-  if (parentResolved !== expected) {
+  if (!preCommitInvokesGuard(coordRoot)) {
     issues.push(
-      `parent core.hooksPath=${parentHp || "<unset>"} (resolves to ${parentResolved}, expected ${expected})`,
+      "parent repo: pre-commit hook is missing or doesn't invoke the harnery commit guard",
     );
   }
 
@@ -220,15 +254,10 @@ export function checkWiring(coordRoot: string): string[] {
     const sampleSub = extractFirstSubmodule(gitmodules);
     if (sampleSub) {
       const subPath = join(coordRoot, sampleSub);
-      const subGitDir = join(subPath, ".git");
-      if (existsSync(subGitDir)) {
-        const subHp = gitConfig(subPath, "core.hooksPath");
-        const subResolved = resolveSubmoduleHooksPath(coordRoot, sampleSub, subHp);
-        if (subResolved !== expected) {
-          issues.push(
-            `submodule ${sampleSub} core.hooksPath=${subHp || "<unset>"} (resolves to ${subResolved}; other submodules likely affected too)`,
-          );
-        }
+      if (existsSync(join(subPath, ".git")) && !preCommitInvokesGuard(subPath)) {
+        issues.push(
+          `submodule ${sampleSub}: pre-commit hook doesn't invoke the harnery commit guard (other submodules likely affected too)`,
+        );
       }
     }
   }
@@ -236,22 +265,33 @@ export function checkWiring(coordRoot: string): string[] {
   return issues;
 }
 
-function gitConfig(cwd: string, key: string): string {
-  const result = spawnSync("git", ["-C", cwd, "config", "--get", key], { encoding: "utf8" });
-  if (result.status !== 0) return "";
-  return result.stdout.trim();
-}
-
-function resolveHooksPath(root: string, hp: string): string {
-  if (!hp) return join(root, ".git", "hooks");
-  if (hp.startsWith("/")) return hp.replace(/\/$/, "");
-  return join(root, hp).replace(/\/$/, "");
+/**
+ * Whether the repo at `repoDir` has a pre-commit hook — at its effective,
+ * `core.hooksPath`-aware location — that invokes harnery's commit guard.
+ * Fully portable: no assumption about WHERE the host keeps its hooks.
+ */
+function preCommitInvokesGuard(repoDir: string): boolean {
+  const hooksDir = gitHooksDir(repoDir);
+  if (!hooksDir) return false;
+  const preCommit = join(hooksDir, "pre-commit");
+  if (!existsSync(preCommit)) return false;
+  try {
+    return /agent-(coord|hook)\b/.test(readFileSync(preCommit, "utf8"));
+  } catch {
+    return false;
+  }
 }
 
-function resolveSubmoduleHooksPath(root: string, sub: string, hp: string): string {
-  if (!hp) return join(root, sub, ".git", "hooks");
-  if (hp.startsWith("/")) return hp.replace(/\/$/, "");
-  return join(root, sub, hp).replace(/\/$/, "");
+/** Resolve a repo's effective git-hooks directory (absolute), or null. */
+function gitHooksDir(repoDir: string): string | null {
+  const r = spawnSync("git", ["-C", repoDir, "rev-parse", "--git-path", "hooks"], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return null;
+  const p = r.stdout.trim();
+  if (!p) return null;
+  // `--git-path` prints relative to repoDir (we passed -C); absolutize.
+  return p.startsWith("/") ? p : join(repoDir, p);
 }
 
 function extractFirstSubmodule(gitmodulesPath: string): string | null {

package/src/core/agents/rules/claim-conflict.ts

@@ -101,15 +101,37 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
   const hasFreshPeers = otherPeers.some(
     (p) => isFresh(p.last_heartbeat) && p.files_touched.length > 0,
   );
-  if (hasFreshPeers && myPeer && myPeer.files_touched.length > 0) {
-    const highest = [...myPeer.files_touched].sort().at(-1)!;
-    if (req.path < highest) {
-      return {
-        allow: false,
-        exit_code: 2,
-        rule: "claim.ordering_violation",
-        reason: `Cannot acquire ${req.path} while holding ${highest} (claim ordering rule: paths must be acquired in sorted order). Release the higher claim first.`,
-      };
+  // Re-editing a path already in our own files_touched acquires no new lock
+  // edge, so it can't create a circular wait — the ordering rule must not block
+  // it. Without this exemption, an agent that edits a higher-sorting file and
+  // then makes a second pass over an already-held lower-sorting file gets a
+  // spurious ordering_violation (the dominant friction source under concurrency:
+  // both agent-Gibson holding README.md and agent-Ophelia holding AGENTS.md were
+  // blocked re-editing those held files after touching a higher path, 2026-07-03).
+  const alreadyHeld = myPeer?.files_touched.includes(req.path) ?? false;
+  if (hasFreshPeers && myPeer && myPeer.files_touched.length > 0 && !alreadyHeld) {
+    // Only ACTIVE (uncommitted) edits should constrain lock ordering. A claim on
+    // a committed-clean file is a finished edit, not a held lock, so it must not
+    // wall off a lower-sorted acquisition. Without this, a long session
+    // accumulates committed claims that block every earlier-sorted path — pure
+    // friction, no deadlock risk (the file isn't being touched). Mirrors the
+    // peer stale-claim self-heal above. The git probes run only on the
+    // would-block path (claims sorting after req.path), staying off the hot path.
+    const blockers = myPeer.files_touched.filter((p) => req.path < p);
+    if (blockers.length > 0) {
+      const activeBlockers = blockers.filter((p) => !isFileCommittedClean(coordRoot, p));
+      if (activeBlockers.length > 0) {
+        const highest = [...activeBlockers].sort().at(-1)!;
+        return {
+          allow: false,
+          exit_code: 2,
+          rule: "claim.ordering_violation",
+          reason: `Cannot acquire ${req.path}: you already hold ${highest}, which sorts after it (claim ordering rule: acquire paths in sorted order to prevent deadlock between concurrent agents). Fix by editing in sorted order, or by committing ${highest} first, since a committed-clean file no longer blocks and is auto-pruned.`,
+        };
+      }
+      // Every blocker is a finished (committed-clean) edit: prune them so they
+      // stop constraining future acquisitions, then fall through to allow.
+      for (const p of blockers) pruneClaimFromPeer(coordRoot, req.instance_id, p);
     }
   }
 
@@ -240,16 +262,19 @@ function isFresh(lastHeartbeat: string): boolean {
  *  - diff shows non-empty output (genuinely dirty)
  */
 function isFileCommittedClean(coordRoot: string, relPath: string): boolean {
-  const abs = join(coordRoot, relPath);
+  // Tolerate either path form: files_touched can hold absolute-under-coordRoot
+  // entries (legacy file-tracking) or canonical monorepo-relative ones.
+  const rel = relPath.startsWith(`${coordRoot}/`) ? relPath.slice(coordRoot.length + 1) : relPath;
+  const abs = join(coordRoot, rel);
   if (!existsSync(abs)) return false;
   try {
-    const tracked = spawnSync("git", ["ls-files", "--error-unmatch", "--", relPath], {
+    const tracked = spawnSync("git", ["ls-files", "--error-unmatch", "--", rel], {
       cwd: coordRoot,
       encoding: "utf8",
       timeout: 2000,
     });
     if (tracked.status !== 0) return false;
-    const result = spawnSync("git", ["diff", "--quiet", "HEAD", "--", relPath], {
+    const result = spawnSync("git", ["diff", "--quiet", "HEAD", "--", rel], {
       cwd: coordRoot,
       encoding: "utf8",
       timeout: 2000,

package/src/core/agents/state/heartbeat-writer.ts

@@ -171,9 +171,16 @@ export function releaseClaim(
   instanceId: string,
   path: string,
 ): Heartbeat | null {
+  // files_touched can hold either absolute-under-coordRoot or canonical
+  // monorepo-relative entries; normalize both sides so release matches
+  // regardless of the form the caller passes (the old exact-string filter
+  // silently no-op'd on a form mismatch).
+  const norm = (p: string): string =>
+    p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
+  const target = norm(path);
   return mutate(coordRoot, instanceId, (hb) => ({
     ...hb,
-    files_touched: (hb.files_touched ?? []).filter((p) => p !== path),
+    files_touched: (hb.files_touched ?? []).filter((p) => norm(p) !== target),
   }));
 }
 

package/src/core/config.ts

@@ -25,6 +25,14 @@ export const DEFAULT_BIN_NAME = "harn";
 interface HarneryConfig {
   /** Host CLI bin name, stamped by `harn init` for a consumer (e.g. "bp"). */
   binName?: string;
+  /**
+   * Host-specific command that (re)installs the project's git hooks, surfaced
+   * verbatim in the "commit guard not wired" nudge. Optional: harnery doesn't
+   * own git-hook installation (each host wires its own pre-commit to invoke
+   * `agent-coord verdict`), and the path/command is host-specific, so the host
+   * declares it here (e.g. "scripts/setup-hooks.sh"). Unset → a generic hint.
+   */
+  hooksSetupHint?: string;
   [k: string]: unknown;
 }
 
@@ -109,3 +117,16 @@ export function resolveBinName(coordRoot?: string | null): string {
   }
   return DEFAULT_BIN_NAME;
 }
+
+/**
+ * The host's git-hook (re)install command, for the "commit guard not wired"
+ * nudge. Returns the configured `hooksSetupHint` (e.g. "scripts/setup-hooks.sh")
+ * or null when unset — callers fall back to a generic, host-agnostic message.
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export function resolveHooksSetupHint(coordRoot?: string | null): string | null {
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return null;
+  const hint = readConfig(root).hooksSetupHint;
+  return typeof hint === "string" && hint.trim() ? hint.trim() : null;
+}