harnery 0.3.1 → 0.4.0

package/README.md

@@ -27,23 +27,36 @@
 ## Install
 
 ```bash
-npm install -g harnery
+curl -fsSL https://harnery.com/install.sh | bash
 ```
 
-Or as a per-project dep:
+One line, no clone: it installs the `harn` CLI globally (npm preferred, Bun fallback), puts it on your `PATH`, and verifies it. Or drive your package manager directly — `npm install -g harnery` / `bun add -g harnery` (or `npm install harnery` for a project dep). Then wire a project:
 
 ```bash
-npm install harnery
+harn init     # creates .harnery/ + registers the harness hooks
+harn doctor   # optional: one-time runtime + dependency check
 ```
 
-Then:
+> **From a git clone?** Cloning for the `web/` dashboard or to contribute? `./scripts/setup.sh` does the clone setup in one shot: installs deps, builds `dist/` on a Bun-free host, runs `harn init`, and links the bins onto your `PATH`.
+
+> **npm gives you the engine + CLI.** The `web/` dashboard and the `docs/` site live in the git repo, not the npm package (which is the CLI + coord engine: `bin`, `dist`, `src`, `schemas`). To run the dashboard, `git clone` the repo, `bun install`, and `harn web up` from there, pointing it at your project with `--coord-root <dir>` (or just run it from inside the project). `harn web up` prints these exact steps if you invoke it without the clone present.
+
+## Uninstall
+
+Two layers. **Unwire a project** (keeps `.harnery/` history by default; on a terminal it asks before deleting it):
 
 ```bash
-harn --help
-harn doctor   # one-time runtime + dep check
+harn deinit                 # unwire the harness hooks
+harn deinit --purge-state   # also delete .harnery/ (destructive)
 ```
 
-> **npm gives you the engine + CLI.** The `web/` dashboard and the `docs/` site live in the git repo, not the npm package (which is the CLI + coord engine: `bin`, `dist`, `src`, `schemas`). To run the dashboard, `git clone` the repo, `bun install`, and `harn web up` from there, pointing it at your project with `--coord-root <dir>` (or just run it from inside the project). `harn web up` prints these exact steps if you invoke it without the clone present.
+**Remove the CLI** with the hosted one-liner (`npm rm -g harnery` / `bun remove -g harnery` work too):
+
+```bash
+curl -fsSL https://harnery.com/uninstall.sh | bash
+```
+
+From a git clone, `./scripts/teardown.sh` is the mirror of `./scripts/setup.sh`: it runs `harn deinit`, removes the `PATH` symlinks, and — on a terminal — asks whether to also delete this project's `.harnery/` history and the clone itself. Both default to no; pre-answer with `--purge-state` and `--remove-clone` for unattended runs.
 
 ## Use as a CLI library
 

package/dist/commander.js

@@ -26,6 +26,7 @@ import { registerCompletionCommand } from "./commands/completion.js";
 import { registerConfigGetCommand } from "./commands/config-get.js";
 import { registerContextCommand } from "./commands/context.js";
 import { registerCookiesCommand } from "./commands/cookies.js";
+import { registerDeinitCommand } from "./commands/deinit.js";
 import { registerDocsCommand } from "./commands/docs.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
 import { registerEditBatchCommand } from "./commands/edit-batch.js";
@@ -44,7 +45,6 @@ import { registerSyncCommand } from "./commands/sync.js";
 import { registerSectionCommand, registerTocCommand } from "./commands/toc.js";
 import { registerTokensCommand } from "./commands/tokens.js";
 import { registerTunnelCommand } from "./commands/tunnel.js";
-import { registerUninstallCommand } from "./commands/uninstall.js";
 import { registerWebCommand } from "./commands/web.js";
 export const defaultEmit = {
     config() {
@@ -115,7 +115,7 @@ export function createHarneryProgram(opts = {}) {
     registerAgentsCommand(program, emit);
     registerDoctorCommand(program, emit);
     registerInitCommand(program, emit, opts.binName);
-    registerUninstallCommand(program, emit);
+    registerDeinitCommand(program, emit, opts.binName);
     registerBackupCommand(program, emit);
     registerSyncCommand(program, emit);
     if (include("web"))

package/dist/commands/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA+EnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA6OpF"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAgFnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA6OpF"}

package/dist/commands/agents.js

@@ -18,6 +18,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, resolveOwnerWithSource, } from "../core/agents/index.js";
 import { resolveBinName } from "../core/config.js";
+import { parsePsChainLine } from "../core/hooks/resolve/anchor.js";
 import { buildCouncilId, buildInviteMarkdown, COUNCIL_SCHEMA_VERSION, contributorsInRound, councilBodyDir, councilsArchiveDir, deleteArchivedCouncil, effectiveSteward, findManifestByPartialId, listKnownAgents, listManifests, moveFromArchive, moveToArchive, normalizeAgentName, pendingCouncilsForMember, readArchivedManifest, readManifest, readRoundPrompts, roundDir, setCouncilSteward, writeContribution, writeManifest, writePrompt, } from "../lib/council/index.js";
 import { displayName as displayAgentName, ensureIdentity, listIdentities, lookupById as lookupIdentityById, lookupByName as lookupIdentityByName, } from "../lib/identities/index.js";
 import { appendEntry, resolveOwnerByName } from "../lib/scratch/index.js";
@@ -2251,14 +2252,26 @@ function runHarnessProbe(id, opts) {
     for (let hops = 0; hops < 20; hops++) {
         let comm = "?";
         let ppid = 0;
+        let got = false;
         try {
             comm = readFileSync(`/proc/${walkPid}/comm`, "utf8").trim() || "?";
             const status = readFileSync(`/proc/${walkPid}/status`, "utf8");
             const m = status.match(/^PPid:\s+(\d+)/m);
             ppid = m ? Number(m[1]) : 0;
+            got = true;
         }
         catch {
-            // non-Linux (no /proc) or the pid is gone: stop walking.
+            // non-Linux (no /proc): fall through to the portable ps walk below.
+        }
+        if (!got) {
+            const out = spawnSync("ps", ["-o", "ppid=,comm=", "-p", String(walkPid)], {
+                encoding: "utf8",
+            });
+            const parsed = out.status === 0 ? parsePsChainLine(out.stdout) : null;
+            if (parsed) {
+                comm = parsed.comm || "?";
+                ppid = parsed.ppid;
+            }
         }
         chainParts.push(`${walkPid}:${comm}`);
         if (!anchorPid && anchorTokens.has(comm))

package/dist/commands/deinit.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `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
+ *      (Claude Code `.claude/settings.json`, Cursor `.cursor/hooks.json`, or
+ *      Codex `.codex/hooks.json`).
+ *   2. Creates the `.harnery/` coord root (runtime state: events, councils,
+ *      identities, scratch) and stamps the host bin name into
+ *      `.harnery/config.jsonc`.
+ *
+ * `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 type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerDeinitCommand(program: Command, emit: EmitContext, binName?: string): void;
+/**
+ * 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 declare function shouldPromptForState(o: {
+    standalone: boolean;
+    interactive: boolean;
+    dryRun: boolean;
+    purgeState: boolean;
+    coordExists: boolean;
+}): boolean;
+/**
+ * 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 declare function engineRemovalHint(): string;
+//# sourceMappingURL=deinit.d.ts.map

package/dist/commands/deinit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deinit.d.ts","sourceRoot":"","sources":["../../src/commands/deinit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAYnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CA2GjG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}

package/dist/commands/{uninstall.js → deinit.js}

@@ -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,29 +9,46 @@
  *      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 { DEFAULT_BIN_NAME } from "../core/config.js";
 import { HARNESS_SPECS } from "../core/hooks/harness/events.js";
 import { unwireHooks } from "./init.js";
-export function registerUninstallCommand(program, emit) {
+export function registerDeinitCommand(program, emit, binName) {
+    // 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) => {
+        .action(async (opts) => {
         const harness = opts.harness;
         const spec = HARNESS_SPECS[harness];
         if (!spec) {
@@ -41,7 +58,20 @@ export function registerUninstallCommand(program, emit) {
         }
         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 = [];
+        // ── 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)) {
@@ -84,9 +114,8 @@ export function registerUninstallCommand(program, emit) {
             }
         }
         // ── 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) {
@@ -97,10 +126,49 @@ export function registerUninstallCommand(program, emit) {
                 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) {
+    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() {
+    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) {
+    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) {
+    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`. */
@@ -108,12 +176,13 @@ function harnessOnly(settings) {
     const keys = Object.keys(settings);
     return keys.length === 0 || (keys.length === 1 && keys[0] === "version");
 }
-function render(projectRoot, dryRun, actions) {
-    const head = dryRun ? "harn uninstall (dry run): no changes written" : "harn uninstall";
+function render(projectRoot, dryRun, actions, hint) {
+    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() {
     const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwC/E;AAED,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAWnC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwC/E;AAED,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAYnC"}

package/dist/commands/doctor.js

@@ -14,6 +14,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { resolveBinName } from "../core/config.js";
+import { loadHarnessWiring } from "../core/hooks/harness/wiring.js";
 export function registerDoctorCommand(program, emit) {
     program
         .command("doctor")
@@ -55,6 +57,7 @@ export function runChecks() {
         checkGit(),
         checkBun(),
         checkHarneryDir(),
+        checkHarnessHooks(),
         checkRestic(),
         checkRclone(),
         checkPlaywright(),
@@ -172,22 +175,24 @@ function checkPython() {
     }
     return { name: "python3", severity: "ok", detail: r.out };
 }
-function checkHarneryDir() {
-    // Walk up from cwd looking for .harnery/.
+/** Walk up from cwd to the nearest dir containing `.harnery/`; null if none. */
+function findCoordProjectRoot() {
     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() {
+    const root = findCoordProjectRoot();
+    if (root) {
+        return { name: ".harnery/", severity: "ok", detail: path.join(root, ".harnery") };
+    }
     return {
         name: ".harnery/",
         severity: "warn",
@@ -195,6 +200,39 @@ function checkHarneryDir() {
         hint: "create one with `mkdir -p .harnery/active` from your monorepo root",
     };
 }
+/**
+ * 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() {
+    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 = [];
+        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, linux) {
     return os.platform() === "darwin" ? mac : linux;
 }

package/dist/commands/init.d.ts

@@ -18,26 +18,8 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.js";
 import { type HarnessId, type HarnessSpec } from "../core/hooks/harness/events.js";
-/** 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;
-}
+import { type HookGroup, type SettingsFile } from "../core/hooks/harness/wiring.js";
+export type { HookGroup, SettingsFile };
 export declare function registerInitCommand(program: Command, emit: EmitContext, binName?: string): void;
 /**
  * Merge agent-hook entries into a harness settings object in place, idempotently.
@@ -78,5 +60,4 @@ export declare function unwireHooks(settings: SettingsFile): {
  *   - key absent → splice it in as the first key (comment-safe).
  */
 export declare function stampBinName(configPath: string, binName: string, dryRun: boolean): string | null;
-export {};
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,WAAW,EAEjB,MAAM,iCAAiC,CAAC;AAWzC,mEAAmE;AACnE,UAAU,eAAe;IACvB,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,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,KAAK,SAAS,GAAG,eAAe,GAAG,eAAe,CAAC;AAEnD,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,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAsF/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,SAAS,GACjB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAsBpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAmB1F;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAmDhG"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EAGL,KAAK,SAAS,EAEd,KAAK,YAAY,EAClB,MAAM,iCAAiC,CAAC;AAIzC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AAWxC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAsF/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,SAAS,GACjB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAsBpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAmB1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAmDhG"}

package/dist/commands/init.js

@@ -20,7 +20,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_BIN_NAME, stripJsonComments } from "../core/config.js";
-import { HARNESS_SPECS, } from "../core/hooks/harness/events.js";
+import { HARNESS_SPECS } from "../core/hooks/harness/events.js";
+import { commandWiresSubcommand, groupCommands, makeEntry, } from "../core/hooks/harness/wiring.js";
 // This file is src/commands/init.ts → harnery package root is two levels up.
 const HARNERY_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 export function registerInitCommand(program, emit, binName) {
@@ -122,7 +123,7 @@ export function wireHooks(settings, spec, agentHookPath, harness) {
     for (const { settingsKey, subcommand } of spec.events) {
         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} `)));
+        const present = groups.some((g) => groupCommands(g).some((c) => commandWiresSubcommand(c, subcommand)));
         if (present) {
             already++;
             continue;
@@ -169,19 +170,6 @@ export function unwireHooks(settings) {
         delete settings.hooks;
     return { removed, remaining };
 }
-/** Build a hook entry in the harness's shape. */
-function makeEntry(shape, command) {
-    return shape === "cursor" ? { command } : { hooks: [{ type: "command", command }] };
-}
-/** Pull every command string out of a hook entry, regardless of shape. */
-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 [];
-}
 /**
  * Idempotently record `binName` in `.harnery/config.jsonc`, preserving any
  * existing JSONC comments and the `files` section. Returns an action line, or

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

@@ -330,15 +330,30 @@ export function selfDisplayName() {
     return displayName(owner);
 }
 function readPpid(pid) {
+    // Linux/WSL fast path: /proc/<pid>/status carries `PPid:`.
     try {
         const status = readFileSync(`/proc/${pid}/status`, "utf8");
         const m = status.match(/^PPid:\s+(\d+)/m);
-        if (!m)
-            return null;
-        const parsed = Number.parseInt(m[1], 10);
-        return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+        if (m) {
+            const parsed = Number.parseInt(m[1], 10);
+            if (Number.isFinite(parsed) && parsed > 0)
+                return parsed;
+        }
     }
     catch {
-        return null;
+        // no /proc (macOS/BSD) — fall through to ps
+    }
+    // Portable fallback: `ps -o ppid= -p <pid>` works on macOS/BSD/Linux.
+    try {
+        const out = spawnSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8" });
+        if (out.status === 0) {
+            const parsed = Number.parseInt(out.stdout.trim(), 10);
+            if (Number.isFinite(parsed) && parsed > 0)
+                return parsed;
+        }
+    }
+    catch {
+        // ps unavailable — give up
     }
+    return null;
 }

package/dist/core/agents/render/session-context.d.ts

@@ -22,8 +22,18 @@ export interface RenderOpts {
  */
 export declare function renderSessionContext(opts: RenderOpts): 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 declare function checkWiring(coordRoot: string): string[];
 /**

package/dist/core/agents/render/session-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAyC,QAAQ,EAAE,MAAM,SAAS,CAAC;AAmB1E,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+BAC2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAoC7D;AAwHD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAiCvD;AA6CD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAiDlF;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,iBAAW,CAAC"}
+{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAyC,QAAQ,EAAE,MAAM,SAAS,CAAC;AAoB1E,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+BAC2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CA+D7D;AAwHD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAwBvD;AAwDD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAiDlF;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,iBAAW,CAAC"}