harnery 0.31.6 → 0.32.0

package/dist/lib/identities/assume.d.ts

@@ -12,7 +12,7 @@
  * Refuse only when another process is still alive, or when cached remote
  * presence reports the name.
  */
-export type IdentityAssumeErrorCode = "identity_busy" | "identity_in_use" | "identity_not_found" | "invalid_identity" | "no_heartbeat" | "not_session" | "projection_failed";
+export type IdentityAssumeErrorCode = "identity_busy" | "identity_in_use" | "identity_is_ancestor" | "identity_not_found" | "invalid_identity" | "no_heartbeat" | "not_session" | "projection_failed";
 export declare class IdentityAssumeError extends Error {
     readonly code: IdentityAssumeErrorCode;
     constructor(code: IdentityAssumeErrorCode, message: string);
@@ -47,5 +47,7 @@ export declare function findIdentityConflict(coordRoot: string, instanceId: stri
  */
 export declare function reclaimAbandonedLocalConflict(coordRoot: string, conflict: IdentityConflict): boolean;
 /** Assume `target` for one live main session. Safe to retry. */
-export declare function assumeIdentity(coordRoot: string, instanceId: string, target: string): IdentityAssumeResult;
+export declare function assumeIdentity(coordRoot: string, instanceId: string, target: string, opts?: {
+    forceAncestor?: boolean;
+}): IdentityAssumeResult;
 //# sourceMappingURL=assume.d.ts.map

package/dist/lib/identities/assume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assume.d.ts","sourceRoot":"","sources":["../../../src/lib/identities/assume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2BH,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,cAAc,GACd,aAAa,GACb,mBAAmB,CAAC;AAExB,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAAE,uBAAuB;gBAA7B,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAOD;+EAC+E;AAC/E,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,SAAa,GACjB,gBAAgB,GAAG,IAAI,CAiCzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CA2CT;AAyED,gEAAgE;AAChE,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,oBAAoB,CAyGtB"}
+{"version":3,"file":"assume.d.ts","sourceRoot":"","sources":["../../../src/lib/identities/assume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2BH,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,iBAAiB,GACjB,sBAAsB,GACtB,oBAAoB,GACpB,kBAAkB,GAClB,cAAc,GACd,aAAa,GACb,mBAAmB,CAAC;AAExB,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAAE,uBAAuB;gBAA7B,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAOD;+EAC+E;AAC/E,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,SAAa,GACjB,gBAAgB,GAAG,IAAI,CAiCzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CA2CT;AAyED,gEAAgE;AAChE,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,oBAAoB,CA4HtB"}

package/dist/lib/identities/assume.js

@@ -18,7 +18,7 @@ import { join } from "node:path";
 import { emitAndProject } from "../../core/agents/cli-emit.js";
 import { emit } from "../../core/agents/events/emit.js";
 import { readHeartbeat } from "../../core/agents/state/heartbeat-writer.js";
-import { recordNameAssumption } from "../../core/agents/state/names.js";
+import { recordNameAssumption, resolveForkAncestry } from "../../core/agents/state/names.js";
 import { instanceHasLivePid, removePidmapRowsForInstance } from "../../core/agents/state/pidmap.js";
 import { coordFreshnessSeconds } from "../../core/config.js";
 import { readRemoteMachines } from "../../core/presence/index.js";
@@ -194,7 +194,7 @@ function adapterOf(platform) {
     return "claude-code";
 }
 /** Assume `target` for one live main session. Safe to retry. */
-export function assumeIdentity(coordRoot, instanceId, target) {
+export function assumeIdentity(coordRoot, instanceId, target, opts) {
     const release = acquireLock(coordRoot);
     try {
         const hb = readHeartbeat(coordRoot, instanceId);
@@ -205,6 +205,19 @@ export function assumeIdentity(coordRoot, instanceId, target) {
             throw new IdentityAssumeError("not_session", `identity assumption is limited to main sessions (current kind: ${hb.kind})`);
         }
         const targetIdentity = resolveTarget(coordRoot, target);
+        // Recorded-fork-lineage guard: a branched session inherits a transcript
+        // full of its ancestor's name, so "assume <ancestor>" is far more likely
+        // a confused fork trusting its scrollback than a legitimate role handoff.
+        // The liveness check below cannot catch this once the ancestor exits;
+        // lineage can. --force-ancestor is the deliberate-successor escape hatch.
+        if (!opts?.forceAncestor) {
+            const ancestor = resolveForkAncestry(coordRoot, instanceId).find((a) => (a.name ?? "").toLowerCase() === targetIdentity.name.toLowerCase());
+            if (ancestor) {
+                throw new IdentityAssumeError("identity_is_ancestor", `agent-${targetIdentity.name} is this session's fork ancestor (${ancestor.instance_id}): ` +
+                    `this conversation was branched from that session, so its name in your context is ` +
+                    `inherited history, not your role. If you are deliberately succeeding it, rerun with --force-ancestor.`);
+            }
+        }
         let reclaimedInstanceId = null;
         let conflict = findIdentityConflict(coordRoot, instanceId, targetIdentity.name);
         if (conflict && reclaimAbandonedLocalConflict(coordRoot, conflict)) {

package/dist/lib/instructions/git-hooks.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Git-hook side of ADR 0008's lifecycle contract: the coordination content of
+ * a consumer's git hooks is machine-owned, exactly like the AGENTS.md block.
+ * `init` installs/refreshes it, `deinit` removes it, `init --check` flags
+ * drift.
+ *
+ * What lives in the hook file is deliberately tiny: a hash-versioned managed
+ * region (# harnery:begin/end markers) that locates `agent-coord` and invokes
+ * `git-hook <event>`. Every piece of actual behavior — staged collection,
+ * submodule canonicalization, gitlink discrimination, verdict, claim pruning —
+ * lives in harnery and upgrades with the package. The region only changes when
+ * the invocation contract does, and then `init` re-splices it and `--check`
+ * catches a stale copy. History's lesson (the first host carried ~200 lines of
+ * coordination bash that decayed for months): logic in a host hook file is
+ * logic outside the upgrade path.
+ *
+ * A hook file harnery created whole is deletable by `deinit` (nothing but the
+ * shebang remains after the region is removed); a host-authored hook keeps all
+ * host content and only loses the managed region.
+ */
+import type { GitHookEvent } from "../../core/agents/git-hook.js";
+import { type ManagedStatus } from "./splice.js";
+export declare const GIT_HOOK_EVENTS: readonly ["pre-commit", "post-commit", "post-checkout"];
+export type { GitHookEvent };
+/**
+ * The managed region body for one hook event. POSIX sh, `harnery_`-prefixed
+ * variables (the region runs inside arbitrary host hook scripts), and a bin
+ * lookup that covers both consumer layouts: git-submodule
+ * (`<root>/harnery/bin/`) and npm (`<root>/node_modules/harnery/bin/`).
+ *
+ * pre-commit propagates a blocking exit code; post-commit / post-checkout are
+ * best-effort and never fail the git operation.
+ */
+export declare function renderGitHookBody(event: GitHookEvent): string;
+/**
+ * The effective hooks dir for the repo at `projectRoot`: honors
+ * `core.hooksPath` (relative values resolve against the repo root) and
+ * worktree layouts, because that's what `git rev-parse --git-path hooks`
+ * reports. Null when `projectRoot` isn't a git repo.
+ */
+export declare function resolveHooksDir(projectRoot: string): string | null;
+export interface GitHooksResult {
+    actions: string[];
+    warnings: string[];
+}
+/** Install or refresh the managed region in each of the three hook files. */
+export declare function applyGitHooks(projectRoot: string, opts: {
+    dryRun?: boolean;
+}): GitHooksResult;
+/**
+ * Has this project adopted harnery-managed git hooks at all? True when any of
+ * the three hook files carries a managed region. Adoption is the gate between
+ * "never installed" (a consumer that upgraded but hasn't opted in — not drift,
+ * `--check` stays green, `doctor` nudges) and "decayed" (a region existed and
+ * is now stale or partially deleted — drift, `--check` goes red).
+ */
+export declare function gitHooksInstalled(projectRoot: string): boolean;
+/**
+ * Drift report for `init --check`: per-hook managed-region freshness. A
+ * project that never adopted git hooks reports fresh — an upgrade must not
+ * turn a consumer's CI red for a feature they haven't installed.
+ */
+export declare function checkGitHooks(projectRoot: string): {
+    status: ManagedStatus;
+    issues: string[];
+};
+/**
+ * Remove the managed region from each hook. A file that was harnery-created
+ * whole (nothing but a shebang left) is deleted; host-authored hooks keep
+ * every host line.
+ */
+export declare function removeGitHooks(projectRoot: string, opts: {
+    dryRun?: boolean;
+}): GitHooksResult;
+//# sourceMappingURL=git-hooks.d.ts.map

package/dist/lib/instructions/git-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-hooks.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/git-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAEL,KAAK,aAAa,EAInB,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,eAAe,yDAIgB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,CAAC;AAM7B;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAkB7D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUlE;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,cAAc,CAoE7F;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAa9D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA2B9F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,cAAc,CA8B9F"}

package/dist/lib/instructions/git-hooks.js

@@ -0,0 +1,238 @@
+/**
+ * Git-hook side of ADR 0008's lifecycle contract: the coordination content of
+ * a consumer's git hooks is machine-owned, exactly like the AGENTS.md block.
+ * `init` installs/refreshes it, `deinit` removes it, `init --check` flags
+ * drift.
+ *
+ * What lives in the hook file is deliberately tiny: a hash-versioned managed
+ * region (# harnery:begin/end markers) that locates `agent-coord` and invokes
+ * `git-hook <event>`. Every piece of actual behavior — staged collection,
+ * submodule canonicalization, gitlink discrimination, verdict, claim pruning —
+ * lives in harnery and upgrades with the package. The region only changes when
+ * the invocation contract does, and then `init` re-splices it and `--check`
+ * catches a stale copy. History's lesson (the first host carried ~200 lines of
+ * coordination bash that decayed for months): logic in a host hook file is
+ * logic outside the upgrade path.
+ *
+ * A hook file harnery created whole is deletable by `deinit` (nothing but the
+ * shebang remains after the region is removed); a host-authored hook keeps all
+ * host content and only loses the managed region.
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { checkRegion, regionBlock, removeRegion, spliceRegion, } from "./splice.js";
+export const GIT_HOOK_EVENTS = [
+    "pre-commit",
+    "post-commit",
+    "post-checkout",
+];
+function regionName(event) {
+    return `git-hook-${event}`;
+}
+/**
+ * The managed region body for one hook event. POSIX sh, `harnery_`-prefixed
+ * variables (the region runs inside arbitrary host hook scripts), and a bin
+ * lookup that covers both consumer layouts: git-submodule
+ * (`<root>/harnery/bin/`) and npm (`<root>/node_modules/harnery/bin/`).
+ *
+ * pre-commit propagates a blocking exit code; post-commit / post-checkout are
+ * best-effort and never fail the git operation.
+ */
+export function renderGitHookBody(event) {
+    const blocking = event === "pre-commit";
+    const invoke = blocking
+        ? `  "$harnery_hook_bin" git-hook ${event} "$@"\n` +
+            `  harnery_hook_rc=$?\n` +
+            `  [ "$harnery_hook_rc" -ne 0 ] && exit "$harnery_hook_rc"\n`
+        : `  "$harnery_hook_bin" git-hook ${event} "$@" >/dev/null 2>&1 || true\n`;
+    return (`# Coordination for this hook lives in harnery (agent-coord git-hook ${event});\n` +
+        `# upgrading harnery upgrades the behavior. Managed region: do not edit by hand.\n` +
+        `harnery_hook_root=$(git rev-parse --show-superproject-working-tree 2>/dev/null)\n` +
+        `[ -n "$harnery_hook_root" ] || harnery_hook_root=$(git rev-parse --show-toplevel 2>/dev/null)\n` +
+        `for harnery_hook_bin in "$harnery_hook_root/harnery/bin/agent-coord" "$harnery_hook_root/node_modules/harnery/bin/agent-coord"; do\n` +
+        `  [ -x "$harnery_hook_bin" ] || continue\n` +
+        invoke +
+        `  break\n` +
+        `done`);
+}
+/**
+ * The effective hooks dir for the repo at `projectRoot`: honors
+ * `core.hooksPath` (relative values resolve against the repo root) and
+ * worktree layouts, because that's what `git rev-parse --git-path hooks`
+ * reports. Null when `projectRoot` isn't a git repo.
+ */
+export function resolveHooksDir(projectRoot) {
+    const r = spawnSync("git", ["rev-parse", "--git-path", "hooks"], {
+        cwd: projectRoot,
+        encoding: "utf8",
+        timeout: 5000,
+    });
+    if (r.status !== 0)
+        return null;
+    const p = (r.stdout ?? "").trim();
+    if (!p)
+        return null;
+    return isAbsolute(p) ? p : resolve(projectRoot, p);
+}
+/** Install or refresh the managed region in each of the three hook files. */
+export function applyGitHooks(projectRoot, opts) {
+    const dryRun = opts.dryRun === true;
+    const actions = [];
+    const warnings = [];
+    const hooksDir = resolveHooksDir(projectRoot);
+    if (!hooksDir) {
+        warnings.push("not a git repository; skipped git-hook regions");
+        return { actions, warnings };
+    }
+    if (!existsSync(hooksDir) && !dryRun)
+        mkdirSync(hooksDir, { recursive: true });
+    for (const event of GIT_HOOK_EVENTS) {
+        const file = join(hooksDir, event);
+        const body = renderGitHookBody(event);
+        const region = regionName(event);
+        const display = relative(projectRoot, file);
+        if (!existsSync(file)) {
+            if (dryRun) {
+                actions.push(`+ would create ${display} (harnery-owned git hook)`);
+                continue;
+            }
+            writeFileSync(file, `#!/bin/sh\n${regionBlock(region, body, "hash")}\n`);
+            chmodSync(file, 0o755);
+            actions.push(`+ created ${display} (harnery-owned git hook)`);
+            continue;
+        }
+        const content = readFileSync(file, "utf8");
+        const status = checkRegion(content, region, body, "hash");
+        if (status === "fresh") {
+            actions.push(`· ${display} git-hook region current`);
+            continue;
+        }
+        if (status === "stale") {
+            const spliced = spliceRegion(content, region, body, "hash");
+            if (dryRun)
+                actions.push(`+ would refresh stale git-hook region in ${display}`);
+            else {
+                writeFileSync(file, spliced.text);
+                actions.push(`+ refreshed stale git-hook region in ${display}`);
+            }
+            continue;
+        }
+        // Missing from an existing, host-authored hook: insert right after the
+        // shebang. Coordination runs first on purpose — an agent should hear
+        // "this commit is blocked by a peer's claim" before paying for the host's
+        // typecheck/lint checks, and post-checkout's claim release must beat any
+        // host short-circuit below it.
+        if (dryRun) {
+            actions.push(`+ would insert git-hook region into ${display} (after shebang)`);
+            continue;
+        }
+        const block = regionBlock(region, body, "hash");
+        let text;
+        if (content.startsWith("#!")) {
+            const nl = content.indexOf("\n");
+            text = `${content.slice(0, nl + 1)}\n${block}\n${content.slice(nl + 1)}`;
+        }
+        else {
+            text = `${block}\n\n${content}`;
+        }
+        writeFileSync(file, text);
+        actions.push(`+ inserted git-hook region into ${display} (after shebang)`);
+    }
+    return { actions, warnings };
+}
+/**
+ * Has this project adopted harnery-managed git hooks at all? True when any of
+ * the three hook files carries a managed region. Adoption is the gate between
+ * "never installed" (a consumer that upgraded but hasn't opted in — not drift,
+ * `--check` stays green, `doctor` nudges) and "decayed" (a region existed and
+ * is now stale or partially deleted — drift, `--check` goes red).
+ */
+export function gitHooksInstalled(projectRoot) {
+    const hooksDir = resolveHooksDir(projectRoot);
+    if (!hooksDir)
+        return false;
+    for (const event of GIT_HOOK_EVENTS) {
+        const file = join(hooksDir, event);
+        if (!existsSync(file))
+            continue;
+        try {
+            if (readFileSync(file, "utf8").includes(`harnery:begin ${regionName(event)}`))
+                return true;
+        }
+        catch {
+            /* unreadable file counts as absent */
+        }
+    }
+    return false;
+}
+/**
+ * Drift report for `init --check`: per-hook managed-region freshness. A
+ * project that never adopted git hooks reports fresh — an upgrade must not
+ * turn a consumer's CI red for a feature they haven't installed.
+ */
+export function checkGitHooks(projectRoot) {
+    const issues = [];
+    let worst = "fresh";
+    const hooksDir = resolveHooksDir(projectRoot);
+    if (!hooksDir)
+        return { status: "fresh", issues };
+    if (!gitHooksInstalled(projectRoot))
+        return { status: "fresh", issues };
+    for (const event of GIT_HOOK_EVENTS) {
+        const file = join(hooksDir, event);
+        const display = relative(projectRoot, file);
+        if (!existsSync(file)) {
+            issues.push(`${display}: missing (run init to create the harnery git hook)`);
+            worst = "missing";
+            continue;
+        }
+        const status = checkRegion(readFileSync(file, "utf8"), regionName(event), renderGitHookBody(event), "hash");
+        if (status !== "fresh") {
+            issues.push(`${display}: git-hook region ${status} (re-run init to refresh)`);
+            if (worst === "fresh")
+                worst = status;
+        }
+    }
+    return { status: worst, issues };
+}
+/**
+ * Remove the managed region from each hook. A file that was harnery-created
+ * whole (nothing but a shebang left) is deleted; host-authored hooks keep
+ * every host line.
+ */
+export function removeGitHooks(projectRoot, opts) {
+    const dryRun = opts.dryRun === true;
+    const actions = [];
+    const warnings = [];
+    const hooksDir = resolveHooksDir(projectRoot);
+    if (!hooksDir)
+        return { actions, warnings };
+    for (const event of GIT_HOOK_EVENTS) {
+        const file = join(hooksDir, event);
+        if (!existsSync(file))
+            continue;
+        const display = relative(projectRoot, file);
+        const content = readFileSync(file, "utf8");
+        const { text, removed } = removeRegion(content, regionName(event), "hash");
+        if (!removed)
+            continue;
+        const residue = text.replace(/^#![^\n]*\n?/, "").trim();
+        if (residue === "") {
+            if (dryRun)
+                actions.push(`+ would remove ${display} (was harnery-owned)`);
+            else {
+                rmSync(file);
+                actions.push(`+ removed ${display} (was harnery-owned)`);
+            }
+        }
+        else if (dryRun) {
+            actions.push(`+ would remove git-hook region from ${display} (host content kept)`);
+        }
+        else {
+            writeFileSync(file, text);
+            actions.push(`+ removed git-hook region from ${display} (host content kept)`);
+        }
+    }
+    return { actions, warnings };
+}

package/dist/lib/instructions/splice.d.ts

@@ -22,8 +22,14 @@
  */
 /** 8-hex-char content hash stamped into every managed marker. */
 export declare function shortHash(s: string): string;
+/**
+ * Marker comment style. Markdown/HTML files wrap markers in HTML comments;
+ * shell files (git hooks) use `#` line comments. The style only changes the
+ * marker syntax — hashing, splice, remove, and check semantics are identical.
+ */
+export type CommentStyle = "html" | "hash";
 /** Canonical region block: begin-marker, body flanked by newlines, end-marker. */
-export declare function regionBlock(region: string, body: string): string;
+export declare function regionBlock(region: string, body: string, style?: CommentStyle): string;
 export type ManagedStatus = "fresh" | "stale" | "missing";
 export interface SpliceResult {
     text: string;
@@ -40,19 +46,19 @@ export interface SpliceResult {
  * absent, the block is appended after existing content (blank-line separated);
  * an empty/whitespace-only `content` becomes just the block.
  */
-export declare function spliceRegion(content: string, region: string, body: string): SpliceResult;
+export declare function spliceRegion(content: string, region: string, body: string, style?: CommentStyle): SpliceResult;
 /**
  * Remove a managed region, collapsing the blank lines it leaves behind. Returns
  * `removed: false` (content unchanged) when the region is absent. When the region
  * was the file's only content, the result is the empty string — the caller
  * decides whether to delete the file.
  */
-export declare function removeRegion(content: string, region: string): {
+export declare function removeRegion(content: string, region: string, style?: CommentStyle): {
     text: string;
     removed: boolean;
 };
 /** Region freshness: missing, stale (hash or body drifted), or fresh. */
-export declare function checkRegion(content: string, region: string, body: string): ManagedStatus;
+export declare function checkRegion(content: string, region: string, body: string, style?: CommentStyle): ManagedStatus;
 /** True when a file carries harnery's ownership header (deinit may delete it). */
 export declare function isOwnedFile(content: string): boolean;
 /**

package/dist/lib/instructions/splice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"splice.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/splice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAcD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,GAAG,EAAE,OAAO,CAAC;IACb,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAaxF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAShG;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAIxF;AAMD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAcT;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAKjF"}
+{"version":3,"file":"splice.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/splice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAMD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAiB3C,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,YAAqB,GAAG,MAAM,CAI9F;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,GAAG,EAAE,OAAO,CAAC;IACb,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,YAAqB,GAC3B,YAAY,CAad;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,YAAqB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CASpC;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,YAAqB,GAC3B,aAAa,CAIf;AAMD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAcT;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAKjF"}

package/dist/lib/instructions/splice.js

@@ -28,14 +28,22 @@ export function shortHash(s) {
 function escapeRe(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function markerPair(style) {
+    return style === "hash" ? { open: "#", close: "" } : { open: "<!--", close: "-->" };
+}
 /** Capture regex for a named managed region: begin-marker, body, end-marker. */
-function regionRe(region) {
+function regionRe(region, style = "html") {
     const r = escapeRe(region);
-    return new RegExp(`(<!--\\s*harnery:begin ${r}(?:\\s+v=([0-9a-f]*))?\\s*-->)([\\s\\S]*?)(<!--\\s*harnery:end ${r}\\s*-->)`);
+    const { open, close } = markerPair(style);
+    const o = escapeRe(open);
+    const c = close ? `\\s*${escapeRe(close)}` : "";
+    return new RegExp(`(${o}\\s*harnery:begin ${r}(?:\\s+v=([0-9a-f]*))?${c ? c : "[ \\t]*"})([\\s\\S]*?)(${o}\\s*harnery:end ${r}${c ? c : "[ \\t]*"})`);
 }
 /** Canonical region block: begin-marker, body flanked by newlines, end-marker. */
-export function regionBlock(region, body) {
-    return `<!-- harnery:begin ${region} v=${shortHash(body)} -->\n${body}\n<!-- harnery:end ${region} -->`;
+export function regionBlock(region, body, style = "html") {
+    const { open, close } = markerPair(style);
+    const tail = close ? ` ${close}` : "";
+    return `${open} harnery:begin ${region} v=${shortHash(body)}${tail}\n${body}\n${open} harnery:end ${region}${tail}`;
 }
 /**
  * Re-splice (or first-time append) a managed region into `content`. Idempotent:
@@ -44,10 +52,10 @@ export function regionBlock(region, body) {
  * absent, the block is appended after existing content (blank-line separated);
  * an empty/whitespace-only `content` becomes just the block.
  */
-export function spliceRegion(content, region, body) {
-    const re = regionRe(region);
+export function spliceRegion(content, region, body, style = "html") {
+    const re = regionRe(region, style);
     const m = content.match(re);
-    const fresh = regionBlock(region, body);
+    const fresh = regionBlock(region, body, style);
     if (m) {
         const stale = m[2] !== shortHash(body) || m[3] !== `\n${body}\n`;
         // Replacer fn avoids `$`-in-body being read as a capture reference.
@@ -64,8 +72,8 @@ export function spliceRegion(content, region, body) {
  * was the file's only content, the result is the empty string — the caller
  * decides whether to delete the file.
  */
-export function removeRegion(content, region) {
-    const re = regionRe(region);
+export function removeRegion(content, region, style = "html") {
+    const re = regionRe(region, style);
     if (!re.test(content))
         return { text: content, removed: false };
     const stripped = content
@@ -76,8 +84,8 @@ export function removeRegion(content, region) {
     return { text: stripped ? `${stripped}\n` : "", removed: true };
 }
 /** Region freshness: missing, stale (hash or body drifted), or fresh. */
-export function checkRegion(content, region, body) {
-    const m = content.match(regionRe(region));
+export function checkRegion(content, region, body, style = "html") {
+    const m = content.match(regionRe(region, style));
     if (!m)
         return "missing";
     return m[2] === shortHash(body) && m[3] === `\n${body}\n` ? "fresh" : "stale";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.31.6",
+  "version": "0.32.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/schemas/config.schema.json

@@ -23,6 +23,38 @@
       "type": "string",
       "description": "Host-specific command that (re)installs the project's git hooks (e.g. 'scripts/setup-hooks.sh'). Surfaced verbatim in the SessionStart 'commit guard not wired' nudge. harnery doesn't own git-hook installation (each host wires its own pre-commit to invoke `agent-coord verdict`) and the path/command is host-specific, so the host declares it here. Unset -> a generic, host-agnostic hint."
     },
+    "agents": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Host-owned agent ritual policy. Harnery capabilities stay available when a policy is disabled; automatic prompts and Stop remediation follow these switches.",
+      "properties": {
+        "requireGitFinalization": {
+          "type": "boolean",
+          "default": false,
+          "description": "Require `agents status --end-turn` instead of plain `agents status` at the end of tool-using turns. The guarded call verifies that session-owned paths are committed and their repositories are pushed. Env override: HARNERY_AGENTS_REQUIRE_GIT_FINALIZATION=1|0."
+        },
+        "finalizationRoots": {
+          "type": "array",
+          "default": [],
+          "description": "Project-owned authority for guarded writes outside the coordination root. Each exact root declares one end-turn disposition: `git` requires the path to be a Git repository root and applies dirty/remote checks; `output` explicitly accepts intentional non-Git output. Paths may be absolute or relative to the coordination root. The coordination root is implicitly `git` when it is a Git repository. User-global config cannot grant these roots.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "disposition"],
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1
+              },
+              "disposition": {
+                "type": "string",
+                "enum": ["git", "output"]
+              }
+            }
+          }
+        }
+      }
+    },
     "coord": {
       "type": "object",
       "additionalProperties": false,

package/src/commander.ts

@@ -24,6 +24,7 @@ import { registerArtifactsCommand } from "./commands/artifacts.ts";
 import { registerBackupCommand } from "./commands/backup.ts";
 import { registerBrowseCommand } from "./commands/browse.ts";
 import { registerBrowseAiCommand } from "./commands/browse-ai.ts";
+import { registerBrowseSessionCommand } from "./commands/browse-session.ts";
 import { registerCallersCommand } from "./commands/callers.ts";
 import { registerCheckpointCommand } from "./commands/checkpoint.ts";
 import { registerClaudeDesktopCommand } from "./commands/claude-desktop.ts";
@@ -280,6 +281,7 @@ export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
   registerFetchCommand(program, emit, opts.context);
   registerReadCommand(program, emit);
   registerBrowseCommand(program, emit, opts.context);
+  registerBrowseSessionCommand(program, emit);
   registerBrowseAiCommand(program, emit);
   registerCompletionCommand(program, emit, opts.context);
   registerCheckpointCommand(program, emit, opts.context);