harnery 0.3.2 → 0.5.0

package/dist/core/agents/render/session-context.js

@@ -9,7 +9,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { resolveBinName } from "../../config.js";
+import { resolveBinName, resolveHooksSetupHint } from "../../config.js";
+import { harneryVersion, loadHarnessWiring } from "../../hooks/harness/wiring.js";
 /**
  * Build the combined SessionStart systemMessage. Returns the additionalContext
  * string (or "" if there's nothing to say).
@@ -38,12 +39,37 @@ export function renderSessionContext(opts) {
         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 = [];
+            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");
 }
 /** Read all peer heartbeats from .harnery/active/, excluding self. */
@@ -152,17 +178,23 @@ function fmtAge(secs) {
     return `${Math.floor(secs / 86400)}d ago`;
 }
 /**
- * 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) {
-    const expected = join(coordRoot, "scripts", "hooks");
     const issues = [];
-    // Parent repo
-    const parentHp = gitConfig(coordRoot, "core.hooksPath");
-    const parentResolved = resolveHooksPath(coordRoot, parentHp);
-    if (parentResolved !== expected) {
-        issues.push(`parent core.hooksPath=${parentHp || "<unset>"} (resolves to ${parentResolved}, expected ${expected})`);
+    if (!preCommitInvokesGuard(coordRoot)) {
+        issues.push("parent repo: pre-commit hook is missing or doesn't invoke the harnery commit guard");
     }
     // One representative submodule
     const gitmodules = join(coordRoot, ".gitmodules");
@@ -170,37 +202,44 @@ export function checkWiring(coordRoot) {
         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)`);
             }
         }
     }
     return issues;
 }
-function gitConfig(cwd, key) {
-    const result = spawnSync("git", ["-C", cwd, "config", "--get", key], { encoding: "utf8" });
-    if (result.status !== 0)
-        return "";
-    return result.stdout.trim();
-}
-function resolveHooksPath(root, hp) {
-    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) {
+    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, sub, hp) {
-    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) {
+    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) {
     try {

package/dist/core/agents/rules/claim-conflict.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claim-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/claim-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAeF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,aAAa,CAmEjF"}
+{"version":3,"file":"claim-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/claim-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAeF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,aAAa,CAyFjF"}

package/dist/core/agents/rules/claim-conflict.js

@@ -62,15 +62,38 @@ export function evaluateClaim(coordRoot, req) {
     // single-agent flow can't deadlock with itself, and the rule otherwise
     // forces release-and-reacquire cycles on every reverse-order edit pair.
     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);
         }
     }
     // Acquire the claim: atomic check-and-set. Adds req.path to my
@@ -197,18 +220,21 @@ function isFresh(lastHeartbeat) {
  *  - diff shows non-empty output (genuinely dirty)
  */
 function isFileCommittedClean(coordRoot, relPath) {
-    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/dist/core/agents/state/heartbeat-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heartbeat-writer.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6DH,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAiBD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQrF;AAeD,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAS7F;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKxF;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAMlB;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,SAAS,GAAG,IAAI,CAKlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA4BnF;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAS5E;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAuBnF;AAED,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,GAAG,IAAI,CAqDlB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,SAAS,GAAG,IAAI,CAOlB"}
+{"version":3,"file":"heartbeat-writer.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6DH,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAiBD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQrF;AAeD,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAS7F;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKxF;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAMlB;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,SAAS,GAAG,IAAI,CAYlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA4BnF;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAS5E;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAuBnF;AAED,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,GAAG,IAAI,CAqDlB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,SAAS,GAAG,IAAI,CAOlB"}

package/dist/core/agents/state/heartbeat-writer.js

@@ -114,9 +114,15 @@ export function setTurnSummary(coordRoot, instanceId, summary) {
     }));
 }
 export function releaseClaim(coordRoot, instanceId, path) {
+    // 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) => 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/dist/core/config.d.ts

@@ -26,4 +26,11 @@ export declare function stripJsonComments(input: string): string;
  * `coordRoot` is resolved via `findCoordRoot()` when not passed.
  */
 export declare function resolveBinName(coordRoot?: string | null): string;
+/**
+ * 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 declare function resolveHooksSetupHint(coordRoot?: string | null): string | null;
 //# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAQvC,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqCvD;AAyBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAShE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAgBvC,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqCvD;AAyBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAShE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK9E"}

package/dist/core/config.js

@@ -106,3 +106,16 @@ export function resolveBinName(coordRoot) {
     }
     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) {
+    const root = coordRoot ?? findCoordRoot();
+    if (!root)
+        return null;
+    const hint = readConfig(root).hooksSetupHint;
+    return typeof hint === "string" && hint.trim() ? hint.trim() : null;
+}

package/dist/core/hooks/cli.js

@@ -28,6 +28,7 @@ import { projectHeartbeats } from "../agents/state/heartbeat-projector.js";
 import { shellMutationPaths } from "../agents/state/shell-mutation.js";
 import { captureImages, detectPresence, imageJanitor, playSound, resetSoundCounters, runTurnSummary, scratchArchive, scratchJanitor, scratchRecoveryCue, soundForEvent, syncClaudeSessions, } from "./effects/index.js";
 import { emit } from "./events/emit.js";
+import { canonicalize } from "./guard-path.js";
 import { detectHarness } from "./harness/detect.js";
 import { extractBashCommand, extractToolDescription, normalizeEventName, parsePayload, } from "./harness/parse.js";
 import { parsePsChainLine, selectAnchorPid } from "./resolve/anchor.js";
@@ -688,7 +689,9 @@ async function main() {
 }
 async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, harness) {
     const toolName = data.tool_name ?? "";
-    const targets = collectGuardTargets(toolName, data).map((p) => canonicalize(coordRoot, p));
+    const targets = collectGuardTargets(toolName, data)
+        .map((p) => canonicalize(coordRoot, p))
+        .filter((p) => p !== null);
     if (targets.length === 0)
         return;
     const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
@@ -737,15 +740,6 @@ async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, harnes
 /** Canonicalize a path to monorepo-relative form. Absolute paths under
  * coordRoot get the prefix stripped; relative paths pass through (assumed
  * already canonical). */
-function canonicalize(coordRoot, p) {
-    if (!p)
-        return p;
-    if (p.startsWith(`${coordRoot}/`))
-        return p.slice(coordRoot.length + 1);
-    if (p === coordRoot)
-        return ".";
-    return p;
-}
 /** Pull the candidate path(s) out of a write-tool payload. Empty array when
  * the tool isn't a write or no path could be derived. */
 function collectGuardTargets(toolName, data) {

package/dist/core/hooks/guard-path.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Canonicalize a write-tool target path for the claim guard.
+ *
+ * Returns the monorepo-relative path, or `null` when the target lies OUTSIDE the
+ * repo (an absolute path not under coordRoot, e.g. a `/tmp` scratchpad or other
+ * session-temp file).
+ *
+ * The claim system is intentionally repo-scoped: it coordinates monorepo files,
+ * not arbitrary absolute paths, so the guard skips out-of-repo targets. Skipping
+ * them is right on two counts. First, it keeps non-repo paths out of a
+ * heartbeat's `files_touched`. Second, the ordering rule compares raw path
+ * strings, and an absolute `/tmp/…` sorts before every repo-relative path
+ * (`/` = 0x2F < any letter), so without this a scratchpad write would spuriously
+ * "block" a legitimately-held repo file. Returning null keeps such paths out of
+ * the claim system entirely.
+ *
+ * Accepted tradeoff: this also means shared out-of-repo files (a user-level
+ * memory or plans directory) are not coordinated across agents. The alternative,
+ * normalizing every path to one consistent key so those stay coordinated, was
+ * rejected as gold-plating a rare, merge-disciplined race in a deadlock-critical
+ * path. Coordinate shared state by keeping it in the repo, not out of it.
+ *
+ * Relative inputs are assumed already-repo-relative (Codex `apply_patch` emits
+ * cwd-relative paths). The in-repo check requires the `<root>/` separator, so a
+ * sibling dir that merely shares a prefix (`/repo-other` vs `/repo`) is treated
+ * as out-of-repo, not stripped.
+ */
+export declare function canonicalize(coordRoot: string, p: string): string | null;
+//# sourceMappingURL=guard-path.d.ts.map

package/dist/core/hooks/guard-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-path.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/guard-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxE"}

package/dist/core/hooks/guard-path.js

@@ -0,0 +1,38 @@
+/**
+ * Canonicalize a write-tool target path for the claim guard.
+ *
+ * Returns the monorepo-relative path, or `null` when the target lies OUTSIDE the
+ * repo (an absolute path not under coordRoot, e.g. a `/tmp` scratchpad or other
+ * session-temp file).
+ *
+ * The claim system is intentionally repo-scoped: it coordinates monorepo files,
+ * not arbitrary absolute paths, so the guard skips out-of-repo targets. Skipping
+ * them is right on two counts. First, it keeps non-repo paths out of a
+ * heartbeat's `files_touched`. Second, the ordering rule compares raw path
+ * strings, and an absolute `/tmp/…` sorts before every repo-relative path
+ * (`/` = 0x2F < any letter), so without this a scratchpad write would spuriously
+ * "block" a legitimately-held repo file. Returning null keeps such paths out of
+ * the claim system entirely.
+ *
+ * Accepted tradeoff: this also means shared out-of-repo files (a user-level
+ * memory or plans directory) are not coordinated across agents. The alternative,
+ * normalizing every path to one consistent key so those stay coordinated, was
+ * rejected as gold-plating a rare, merge-disciplined race in a deadlock-critical
+ * path. Coordinate shared state by keeping it in the repo, not out of it.
+ *
+ * Relative inputs are assumed already-repo-relative (Codex `apply_patch` emits
+ * cwd-relative paths). The in-repo check requires the `<root>/` separator, so a
+ * sibling dir that merely shares a prefix (`/repo-other` vs `/repo`) is treated
+ * as out-of-repo, not stripped.
+ */
+export function canonicalize(coordRoot, p) {
+    if (!p)
+        return null;
+    if (p === coordRoot)
+        return ".";
+    if (p.startsWith(`${coordRoot}/`))
+        return p.slice(coordRoot.length + 1);
+    if (p.startsWith("/"))
+        return null; // absolute + not under coordRoot → out-of-repo
+    return p; // relative → treat as repo-relative
+}

package/dist/core/hooks/harness/wiring.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Read-only harness-hook wiring inspection — the inverse of `harn init`'s
+ * writer (commands/init.ts `wireHooks`). Compares what `init` would wire
+ * (HARNESS_SPECS) against what's actually present in a project's harness
+ * settings file, so `harn doctor` and the SessionStart nudge can tell an agent
+ * when a harnery upgrade changed the hook set but the project hasn't been
+ * re-wired yet.
+ *
+ * The shared types + matcher live here (not in init.ts) so the writer, the
+ * doctor check, and the session-start renderer all agree on what "wired" means
+ * — there's exactly one definition of the `agent-hook <subcommand>` match.
+ */
+import { type HarnessId, type HarnessSpec, type HookEntryShape, type HookEvent } from "./events.js";
+/** Claude Code + Codex entry: `{ hooks: [{ type, command }] }`. */
+export interface ClaudeHookGroup {
+    matcher?: string;
+    hooks: {
+        type: string;
+        command: string;
+    }[];
+}
+/** Cursor entry: a flat `{ command }`. */
+export interface CursorHookGroup {
+    command: string;
+    type?: string;
+    matcher?: string;
+}
+export type HookGroup = ClaudeHookGroup | CursorHookGroup;
+export interface SettingsFile {
+    version?: number;
+    hooks?: Record<string, HookGroup[]>;
+    [k: string]: unknown;
+}
+/** Build a hook entry in the harness's shape. */
+export declare function makeEntry(shape: HookEntryShape, command: string): HookGroup;
+/** Pull every command string out of a hook entry, regardless of shape. */
+export declare function groupCommands(group: HookGroup): string[];
+/**
+ * Whether a hook command string wires the given agent-hook subcommand. The
+ * trailing space is load-bearing: it keeps `stop` from matching `stop-failure`.
+ */
+export declare function commandWiresSubcommand(command: string, subcommand: string): boolean;
+export interface WiringDiff {
+    /** Spec events not wired in the settings file. */
+    missing: HookEvent[];
+    /** Spec events already wired. */
+    present: HookEvent[];
+    /**
+     * agent-hook subcommands wired in the file that are NOT in the current spec
+     * (e.g. an event renamed/removed by an upgrade). Additive re-init won't clean
+     * these — they need explicit removal — so they're surfaced separately.
+     */
+    orphans: string[];
+}
+/**
+ * Pure diff of one settings object against one harness spec. Read-only inverse
+ * of `wireHooks`; no fs, so it's unit-testable.
+ */
+export declare function diffWiring(settings: SettingsFile, spec: HarnessSpec): WiringDiff;
+export interface HarnessWiringStatus {
+    harness: HarnessId;
+    /** Settings file path, relative to the project root. */
+    settingsFile: string;
+    missing: HookEvent[];
+    orphans: string[];
+}
+/**
+ * Inspect every harness whose settings file exists under `projectRoot` and
+ * return only those with *drift*. Read-only; never writes.
+ *
+ * Drift is reported only for a harness the project has **already opted into** —
+ * i.e. at least one harnery hook is already wired. A settings file with zero
+ * harnery hooks just means this harness isn't harnery-wired here (a bare
+ * `.claude/settings.json` is a generic Claude Code file); that's `harn init`'s
+ * job to surface on first run, not drift to nag about every session. A harness
+ * with no settings file at all, or an unparseable one, is skipped.
+ */
+export declare function loadHarnessWiring(projectRoot: string): HarnessWiringStatus[];
+/**
+ * Resolve the harnery package version for context in nudges/checks. Walks up
+ * from this module to the package root (works under Bun from `src/` and Node
+ * from `dist/`). Returns "" if unresolved — callers omit it from the message.
+ */
+export declare function harneryVersion(): string;
+//# sourceMappingURL=wiring.d.ts.map

package/dist/core/hooks/harness/wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/harness/wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAErB,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AACD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,eAAe,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAE3E;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAMxD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnF;AAQD,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,iCAAiC;IACjC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CA0BhF;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,CAAC;IACnB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAwB5E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAkBvC"}

package/dist/core/hooks/harness/wiring.js

@@ -0,0 +1,137 @@
+/**
+ * Read-only harness-hook wiring inspection — the inverse of `harn init`'s
+ * writer (commands/init.ts `wireHooks`). Compares what `init` would wire
+ * (HARNESS_SPECS) against what's actually present in a project's harness
+ * settings file, so `harn doctor` and the SessionStart nudge can tell an agent
+ * when a harnery upgrade changed the hook set but the project hasn't been
+ * re-wired yet.
+ *
+ * The shared types + matcher live here (not in init.ts) so the writer, the
+ * doctor check, and the session-start renderer all agree on what "wired" means
+ * — there's exactly one definition of the `agent-hook <subcommand>` match.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HARNESS_SPECS, } from "./events.js";
+/** Build a hook entry in the harness's shape. */
+export function makeEntry(shape, command) {
+    return shape === "cursor" ? { command } : { hooks: [{ type: "command", command }] };
+}
+/** Pull every command string out of a hook entry, regardless of shape. */
+export function groupCommands(group) {
+    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) => typeof c === "string");
+    }
+    return [];
+}
+/**
+ * Whether a hook command string wires the given agent-hook subcommand. The
+ * trailing space is load-bearing: it keeps `stop` from matching `stop-failure`.
+ */
+export function commandWiresSubcommand(command, subcommand) {
+    return command.includes(`agent-hook ${subcommand} `);
+}
+/** Pull the agent-hook subcommand out of a command string, or null if none. */
+function commandSubcommand(command) {
+    const m = command.match(/agent-hook\s+([a-z][a-z-]*)\s/);
+    return m ? m[1] : null;
+}
+/**
+ * Pure diff of one settings object against one harness spec. Read-only inverse
+ * of `wireHooks`; no fs, so it's unit-testable.
+ */
+export function diffWiring(settings, spec) {
+    const missing = [];
+    const present = [];
+    const hooks = settings.hooks ?? {};
+    for (const event of spec.events) {
+        const groups = hooks[event.settingsKey] ?? [];
+        const wired = groups.some((g) => groupCommands(g).some((c) => commandWiresSubcommand(c, event.subcommand)));
+        (wired ? present : missing).push(event);
+    }
+    const specSubcommands = new Set(spec.events.map((e) => e.subcommand));
+    const orphans = new Set();
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const g of groups) {
+            for (const c of groupCommands(g)) {
+                const sub = commandSubcommand(c);
+                if (sub && !specSubcommands.has(sub))
+                    orphans.add(sub);
+            }
+        }
+    }
+    return { missing, present, orphans: [...orphans].sort() };
+}
+/**
+ * Inspect every harness whose settings file exists under `projectRoot` and
+ * return only those with *drift*. Read-only; never writes.
+ *
+ * Drift is reported only for a harness the project has **already opted into** —
+ * i.e. at least one harnery hook is already wired. A settings file with zero
+ * harnery hooks just means this harness isn't harnery-wired here (a bare
+ * `.claude/settings.json` is a generic Claude Code file); that's `harn init`'s
+ * job to surface on first run, not drift to nag about every session. A harness
+ * with no settings file at all, or an unparseable one, is skipped.
+ */
+export function loadHarnessWiring(projectRoot) {
+    const out = [];
+    for (const [id, spec] of Object.entries(HARNESS_SPECS)) {
+        const settingsPath = resolve(projectRoot, spec.settingsFile);
+        if (!existsSync(settingsPath))
+            continue;
+        let settings;
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+        }
+        catch {
+            // Unparseable settings file: can't tell opt-in from noise, and the
+            // harness itself will complain about its own malformed config. Skip.
+            continue;
+        }
+        const diff = diffWiring(settings, spec);
+        if (diff.present.length === 0)
+            continue; // not opted in → not drift
+        if (diff.missing.length === 0 && diff.orphans.length === 0)
+            continue; // current
+        out.push({
+            harness: id,
+            settingsFile: spec.settingsFile,
+            missing: diff.missing,
+            orphans: diff.orphans,
+        });
+    }
+    return out;
+}
+/**
+ * Resolve the harnery package version for context in nudges/checks. Walks up
+ * from this module to the package root (works under Bun from `src/` and Node
+ * from `dist/`). Returns "" if unresolved — callers omit it from the message.
+ */
+export function harneryVersion() {
+    try {
+        let dir = dirname(fileURLToPath(import.meta.url));
+        for (let i = 0; i < 8; i++) {
+            try {
+                const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+                if (pkg.name === "harnery" && typeof pkg.version === "string")
+                    return pkg.version;
+            }
+            catch {
+                /* no package.json here, or not ours; keep walking up */
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        /* import.meta.url unavailable or fs error */
+    }
+    return "";
+}