harnery 0.3.1 → 0.4.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,CAiFjF"}

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

@@ -63,14 +63,29 @@ export function evaluateClaim(coordRoot, req) {
     // 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.`,
-            };
+        // 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} while holding ${highest} (claim ordering rule: paths must be acquired in sorted order). Release the higher claim first.`,
+                };
+            }
+            // 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 +212,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

@@ -30,7 +30,7 @@ import { captureImages, detectPresence, imageJanitor, playSound, resetSoundCount
 import { emit } from "./events/emit.js";
 import { detectHarness } from "./harness/detect.js";
 import { extractBashCommand, extractToolDescription, normalizeEventName, parsePayload, } from "./harness/parse.js";
-import { selectAnchorPid } from "./resolve/anchor.js";
+import { parsePsChainLine, selectAnchorPid } from "./resolve/anchor.js";
 import { findCoordRoot } from "./resolve/coord-root.js";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.js";
 import { resolveOwner } from "./resolve/owner.js";
@@ -820,10 +820,10 @@ function healHeartbeatViaCli(coordRoot, instanceId, sessionId, harness) {
  * the next tool call rather than going invisible until SessionStart fires
  * again, which it may never do.
  *
- * Returns undefined on macOS (no /proc) or when no anchor is found; callers
- * fall back to `process.ppid` (the bash wrapper's parent, which is usually
- * the harness binary itself). `HARNERY_AGENT_COORD_TEST_ANCHOR_PID` overrides
- * everything so the test sandbox can pin a deterministic PID.
+ * Returns undefined only when no anchor is found; callers fall back to
+ * `process.ppid` (the bash wrapper's parent, which is usually the harness binary
+ * itself). `HARNERY_AGENT_COORD_TEST_ANCHOR_PID` overrides everything so the
+ * test sandbox can pin a deterministic PID.
  */
 function findHarnessAnchorPid(harness) {
     const override = coordEnv("AGENT_COORD_TEST_ANCHOR_PID");
@@ -832,30 +832,35 @@ function findHarnessAnchorPid(harness) {
         if (Number.isFinite(n) && n > 0)
             return n;
     }
-    // Build the ppid chain (nearest → root, up to 20 hops) from /proc, then hand
-    // it to the pure selector. Splitting the /proc walk (untestable off a live
-    // box) from the comm-matching (unit-tested against the real Phase 0 chains in
-    // resolve/anchor.ts) keeps the cursor `node`-fallback logic verifiable.
+    // Build the ppid chain (nearest → root, up to 20 hops), then hand it to the
+    // pure selector. Linux/WSL reads /proc; macOS/BSD (no /proc) falls back to
+    // `ps -o ppid=,comm=` parsed by the unit-tested `parsePsChainLine`. Splitting
+    // the walk (untestable off a live box) from the comm-matching keeps the
+    // cursor `node`-fallback logic verifiable.
     const chain = [];
     let pid = process.pid;
     for (let hops = 0; hops < 20; hops++) {
-        let comm;
-        let status;
+        let hop = null;
         try {
-            comm = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
-            status = readFileSync(`/proc/${pid}/status`, "utf8");
+            const comm = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
+            const status = readFileSync(`/proc/${pid}/status`, "utf8");
+            const m = status.match(/^PPid:\s+(\d+)/m);
+            hop = { comm, ppid: m ? Number(m[1]) : 0 };
         }
         catch {
-            break;
+            // no /proc (macOS/BSD) — fall through to ps
+        }
+        if (!hop) {
+            const out = spawnSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], { encoding: "utf8" });
+            if (out.status === 0)
+                hop = parsePsChainLine(out.stdout);
         }
-        chain.push({ pid, comm });
-        const m = status.match(/^PPid:\s+(\d+)/m);
-        if (!m)
+        if (!hop)
             break;
-        const ppid = Number(m[1]);
-        if (!Number.isFinite(ppid) || ppid === 0 || ppid === 1)
+        chain.push({ pid, comm: hop.comm });
+        if (!Number.isFinite(hop.ppid) || hop.ppid === 0 || hop.ppid === 1)
             break;
-        pid = ppid;
+        pid = hop.ppid;
     }
     return selectAnchorPid(chain, harness);
 }

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 "";
+}

package/dist/core/hooks/resolve/anchor.d.ts

@@ -34,4 +34,19 @@ export declare function selectAnchorPid(chain: ReadonlyArray<{
     pid: number;
     comm: string;
 }>, harness?: string): number | undefined;
+/**
+ * Parse one `ps -o ppid=,comm= -p <pid>` line into the same `{ ppid, comm }`
+ * shape the `/proc` fast path produces, for the macOS/BSD branch of the anchor
+ * walk. `ps` prints `comm` as a full executable path (and some Apple helper
+ * names contain spaces, e.g. `Code Helper (Plugin)`), so the comm is reduced to
+ * its basename to match the harness comm tokens the way Linux's `/proc/<pid>/comm`
+ * basename does. Returns null when the line has no leading numeric ppid.
+ *
+ * Pure (no I/O) so the parsing — the error-prone part — is unit-testable
+ * without a live process tree; the caller owns the `ps` spawn.
+ */
+export declare function parsePsChainLine(line: string): {
+    ppid: number;
+    comm: string;
+} | null;
 //# sourceMappingURL=anchor.d.ts.map

package/dist/core/hooks/resolve/anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACnD,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAUpB"}
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACnD,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAUpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQpF"}

package/dist/core/hooks/resolve/anchor.js

@@ -46,3 +46,25 @@ export function selectAnchorPid(chain, harness) {
     }
     return undefined;
 }
+/**
+ * Parse one `ps -o ppid=,comm= -p <pid>` line into the same `{ ppid, comm }`
+ * shape the `/proc` fast path produces, for the macOS/BSD branch of the anchor
+ * walk. `ps` prints `comm` as a full executable path (and some Apple helper
+ * names contain spaces, e.g. `Code Helper (Plugin)`), so the comm is reduced to
+ * its basename to match the harness comm tokens the way Linux's `/proc/<pid>/comm`
+ * basename does. Returns null when the line has no leading numeric ppid.
+ *
+ * Pure (no I/O) so the parsing — the error-prone part — is unit-testable
+ * without a live process tree; the caller owns the `ps` spawn.
+ */
+export function parsePsChainLine(line) {
+    const m = line.trim().match(/^(\d+)\s+(.*)$/);
+    if (!m)
+        return null;
+    const ppid = Number.parseInt(m[1], 10);
+    if (!Number.isFinite(ppid))
+        return null;
+    const commPath = m[2].trim();
+    const comm = commPath.split("/").pop() || commPath;
+    return { ppid, comm };
+}