harnery 0.0.1 → 0.2.1

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

@@ -0,0 +1,35 @@
+/**
+ * File-claim verdict.
+ *
+ * Phase 5 cutover: PreToolUse routes Edit/Write/NotebookEdit through here.
+ *
+ * Two checks:
+ *   1. Conflict: is the path already claimed by a fresh peer? Block with
+ *      the peer's name in the reason.
+ *   2. Ordering: if we already hold a claim on path A and want path
+ *      B, B must sort > A lexicographically. Otherwise emit
+ *      claim.conflict (ordering_violation) and block.
+ *
+ * Reads from `.harnery/active/<id>.json`, the single canonical heartbeat
+ * location after Phase 8 collapsed the v1/v2 dual-write.
+ */
+export type VerdictResult = {
+    allow: boolean;
+    exit_code: 0 | 2;
+    rule: string;
+    reason?: string;
+};
+export interface ClaimRequest {
+    rule: "claim";
+    instance_id: string;
+    session_id?: string;
+    path: string;
+    mode?: "read" | "write";
+}
+/**
+ * Evaluate a file-claim. Returns deny when another fresh peer claims the
+ * path, OR when this owner already holds a lower-sorted claim and the new
+ * one would create a circular wait.
+ */
+export declare function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResult;
+//# sourceMappingURL=claim-conflict.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,244 @@
+/**
+ * File-claim verdict.
+ *
+ * Phase 5 cutover: PreToolUse routes Edit/Write/NotebookEdit through here.
+ *
+ * Two checks:
+ *   1. Conflict: is the path already claimed by a fresh peer? Block with
+ *      the peer's name in the reason.
+ *   2. Ordering: if we already hold a claim on path A and want path
+ *      B, B must sort > A lexicographically. Otherwise emit
+ *      claim.conflict (ordering_violation) and block.
+ *
+ * Reads from `.harnery/active/<id>.json`, the single canonical heartbeat
+ * location after Phase 8 collapsed the v1/v2 dual-write.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const FRESHNESS_SECS = 600;
+/**
+ * Evaluate a file-claim. Returns deny when another fresh peer claims the
+ * path, OR when this owner already holds a lower-sorted claim and the new
+ * one would create a circular wait.
+ */
+export function evaluateClaim(coordRoot, req) {
+    const peers = readPeers(coordRoot);
+    const myPeer = peers.find((p) => p.instance_id === req.instance_id);
+    // Group-ownership exclusion ("Option B" semantics): the parent
+    // session and all subagents under it share a group; claims within the
+    // group don't block each other. Compute the group root for the calling
+    // instance_id, then exclude any peer in the same group from the conflict
+    // scan. session_id from the payload is the parent_owner for subagents.
+    const groupRoot = computeGroupRoot(peers, req.instance_id, req.session_id);
+    const inMyGroup = (p) => p.instance_id === req.instance_id ||
+        p.instance_id === groupRoot ||
+        p.parent_instance_id === groupRoot ||
+        (p.parent_instance_id !== undefined && p.parent_instance_id === req.instance_id);
+    const otherPeers = peers.filter((p) => !inMyGroup(p));
+    // Conflict scan: any other fresh peer claiming this exact path?
+    const conflict = otherPeers.find((p) => isFresh(p.last_heartbeat) && p.files_touched.includes(req.path));
+    if (conflict) {
+        // Self-heal probe: if the file is committed-clean (exists in the repo AND has no uncommitted
+        // changes), the peer's claim is stale (worker crashed without releasing) →
+        // prune the claim from their heartbeat and allow the edit. Skips when the
+        // file doesn't exist (intent-to-create claim); that surface IS load-bearing.
+        if (isFileCommittedClean(coordRoot, req.path)) {
+            pruneClaimFromPeer(coordRoot, conflict.instance_id, req.path);
+            // Fall through to ordering check + allow.
+        }
+        else {
+            return {
+                allow: false,
+                exit_code: 2,
+                rule: "claim.conflict",
+                reason: `File ${req.path} is currently being edited by agent-${conflict.name ?? conflict.instance_id.slice(0, 8)}. Wait for them to finish or pick a different file. Set HARNERY_AGENT_COORD_OFF=1 to bypass (not recommended).`,
+            };
+        }
+    }
+    // Ordering check: if we hold any claim with path < req.path, fine.
+    // Otherwise the new claim would create a backward-edge in the dependency
+    // graph and risk deadlock. Only applies when there are OTHER fresh peers:
+    // single-agent flow can't deadlock with itself, and the rule otherwise
+    // forces release-and-reacquire cycles on every reverse-order edit pair.
+    const hasFreshPeers = otherPeers.some((p) => isFresh(p.last_heartbeat) && p.files_touched.length > 0);
+    if (hasFreshPeers && myPeer && myPeer.files_touched.length > 0) {
+        const highest = [...myPeer.files_touched].sort().at(-1);
+        if (req.path < highest) {
+            return {
+                allow: false,
+                exit_code: 2,
+                rule: "claim.ordering_violation",
+                reason: `Cannot acquire ${req.path} while holding ${highest} (claim ordering rule: paths must be acquired in sorted order). Release the higher claim first.`,
+            };
+        }
+    }
+    // Acquire the claim: atomic check-and-set. Adds req.path to my
+    // files_touched if not already present.
+    if (req.mode !== "read") {
+        addClaimToOwner(coordRoot, req.instance_id, req.path);
+    }
+    return { allow: true, exit_code: 0, rule: "claim.pass" };
+}
+/**
+ * Add `relPath` to the owner's heartbeat `files_touched` array (idempotent;
+ * no-op if already present). Atomic temp + rename. If the owner has no
+ * heartbeat yet (subagent that hasn't been initialized), creates a minimal one.
+ */
+function addClaimToOwner(coordRoot, instanceId, relPath) {
+    const activeDir = join(coordRoot, ".harnery", "active");
+    if (!existsSync(activeDir))
+        return;
+    const path = join(activeDir, `${instanceId}.json`);
+    if (!existsSync(path)) {
+        const now = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+        const minimal = {
+            schema_version: 1,
+            instance_id: instanceId,
+            session_id: instanceId,
+            files_touched: [relPath],
+            started_at: now,
+            last_heartbeat: now,
+        };
+        try {
+            const tmp = `${path}.tmp.${process.pid}`;
+            writeFileSync(tmp, JSON.stringify(minimal, null, 2), "utf8");
+            renameSync(tmp, path);
+        }
+        catch {
+            /* silent */
+        }
+        return;
+    }
+    try {
+        const body = JSON.parse(readFileSync(path, "utf8"));
+        const files = body.files_touched ?? [];
+        if (files.includes(relPath))
+            return;
+        body.files_touched = [...files, relPath];
+        const tmp = `${path}.tmp.${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(body, null, 2), "utf8");
+        renameSync(tmp, path);
+    }
+    catch {
+        /* silent */
+    }
+}
+function readPeers(coordRoot) {
+    const out = [];
+    const path = join(coordRoot, ".harnery", "active");
+    if (!existsSync(path))
+        return out;
+    for (const f of readdirSync(path)) {
+        if (!f.endsWith(".json"))
+            continue;
+        try {
+            const hb = JSON.parse(readFileSync(join(path, f), "utf8"));
+            if (!hb.instance_id)
+                continue;
+            // Derive parent_instance_id: explicit field first, then infer from
+            // session_id-differs-from-instance_id (the subagent shape:
+            // instance_id is the agent_id, session_id is the parent session).
+            const inferredParent = hb.parent_instance_id ??
+                hb.parent_session_id ??
+                (hb.session_id && hb.session_id !== hb.instance_id ? hb.session_id : undefined);
+            out.push({
+                instance_id: hb.instance_id,
+                name: hb.name,
+                session_id: hb.session_id ?? hb.instance_id,
+                files_touched: hb.files_touched ?? [],
+                last_heartbeat: hb.last_heartbeat ?? "",
+                parent_instance_id: inferredParent,
+            });
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return out;
+}
+/**
+ * Compute the group root for `instanceId`. For a parent session it's instanceId
+ * itself. For a subagent it's the parent_instance_id from the heartbeat
+ * (stamped on subagent heartbeats). When session_id is
+ * supplied and differs from instanceId (Claude Code's `session_id != agent_id`
+ * shape for subagents), that's the group root too.
+ */
+function computeGroupRoot(peers, instanceId, sessionId) {
+    // If we have a peer entry, its parent_instance_id is authoritative.
+    const myPeer = peers.find((p) => p.instance_id === instanceId);
+    if (myPeer?.parent_instance_id)
+        return myPeer.parent_instance_id;
+    // Fallback to session_id (parent's instance_id for subagents).
+    if (sessionId && sessionId !== instanceId)
+        return sessionId;
+    // I am the group root.
+    return instanceId;
+}
+function isFresh(lastHeartbeat) {
+    if (!lastHeartbeat)
+        return false;
+    const ts = Date.parse(lastHeartbeat);
+    if (!Number.isFinite(ts))
+        return false;
+    return (Date.now() - ts) / 1000 <= FRESHNESS_SECS;
+}
+/**
+ * Check if a monorepo-relative path is committed-clean: file exists in the
+ * repo, is tracked, AND `git diff HEAD -- path` shows no uncommitted
+ * modifications. Untracked files are NOT committed-clean: `git diff HEAD`
+ * exits 0 on an untracked path (because git ignores it), so we have to
+ * positively confirm tracking via `git ls-files` before trusting the diff.
+ *
+ * Returns false when:
+ *  - file doesn't exist (intent-to-create, preserve the claim)
+ *  - file is untracked (peer wrote it, hasn't staged yet, preserve the claim)
+ *  - any git op fails (treat as dirty, fail-safe)
+ *  - diff shows non-empty output (genuinely dirty)
+ */
+function isFileCommittedClean(coordRoot, relPath) {
+    const abs = join(coordRoot, relPath);
+    if (!existsSync(abs))
+        return false;
+    try {
+        const tracked = spawnSync("git", ["ls-files", "--error-unmatch", "--", relPath], {
+            cwd: coordRoot,
+            encoding: "utf8",
+            timeout: 2000,
+        });
+        if (tracked.status !== 0)
+            return false;
+        const result = spawnSync("git", ["diff", "--quiet", "HEAD", "--", relPath], {
+            cwd: coordRoot,
+            encoding: "utf8",
+            timeout: 2000,
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove a stale claim from a peer's heartbeat. Atomic temp + rename. Silent
+ * on failure.
+ */
+function pruneClaimFromPeer(coordRoot, instanceId, relPath) {
+    const path = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+    if (!existsSync(path))
+        return;
+    try {
+        const body = JSON.parse(readFileSync(path, "utf8"));
+        const files = body.files_touched ?? [];
+        const next = files.filter((p) => p !== relPath);
+        if (next.length === files.length)
+            return;
+        body.files_touched = next;
+        const tmp = `${path}.tmp.${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(body, null, 2), "utf8");
+        renameSync(tmp, path);
+    }
+    catch {
+        /* silent */
+    }
+}

package/dist/core/agents/rules/commit-conflict.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pre-commit E-guard verdict. The caller (typically a bash pre-commit hook)
+ * sends a JSON request with the staged paths, resolves its own instance_id
+ * via pid-map, and prints the verdict messages + exits with
+ * verdict.exit_code.
+ *
+ * Three outcomes:
+ *   1. allow (no conflicts): exit 0.
+ *   2. allow + suppressed (self-attribution heuristic: holder's files ⊆
+ *      staged set AND no live foreign pid anchors them): exit 0, prints
+ *      "treating as self under transient identity".
+ *   3. block: exit 1, prints "Commit blocked by multi-agent coordination".
+ *
+ * `bypass: true` flips conflict → allow + warning lines (the
+ * `HARNERY_AGENT_COORD_BYPASS=1` escape hatch).
+ *
+ * Gitlink discrimination: a parent-repo staged submodule path is a pointer
+ * bump, NOT a claim on the submodule's contents. The caller supplies
+ * `staged_gitlinks[]` (cheap to compute via `git ls-files --stage`); paths
+ * in that set are matched with the staged-is-gitlink rule.
+ */
+interface Conflict {
+    /** Staged path that triggered the match. */
+    staged_path: string;
+    /** The peer's claimed path (may be a parent/child of staged_path). */
+    claimed_path: string;
+    /** Peer's instance_id. */
+    instance_id: string;
+    /** Peer's display name (or first 8 chars of instance_id). */
+    short_name: string;
+}
+export interface CommitVerdictRequest {
+    instance_id: string;
+    /** Group key. Subagents inherit parent's session_id. */
+    session_id: string;
+    /** Canonical monorepo-relative paths. */
+    staged_paths: string[];
+    /** Paths in `staged_paths` that resolve to submodule gitlinks (mode 160000)
+     * in the index. Used for gitlink-discrimination prefix matching. */
+    staged_gitlinks?: string[];
+    /** `HARNERY_AGENT_COORD_BYPASS=1` was set. Conflicts become warnings, not blocks. */
+    bypass?: boolean;
+}
+export interface CommitVerdictResult {
+    allow: boolean;
+    exit_code: number;
+    rule: string;
+    /** Conflict details (for the caller to print). */
+    conflicts: Conflict[];
+    /** Path-specific gates that fired (for `coord_log` lines). */
+    log_lines: string[];
+    /** Human-readable header for printing. */
+    message: string;
+    /** When true, conflicts were detected but suppressed (self-attribution). */
+    suppressed_self_attribution?: boolean;
+}
+export declare function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): CommitVerdictResult;
+export {};
+//# sourceMappingURL=commit-conflict.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commit-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/commit-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAiBH,UAAU,QAAQ;IAChB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;wEACoE;IACpE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,oBAAoB,GAAG,mBAAmB,CAsGhG"}

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

@@ -0,0 +1,244 @@
+/**
+ * Pre-commit E-guard verdict. The caller (typically a bash pre-commit hook)
+ * sends a JSON request with the staged paths, resolves its own instance_id
+ * via pid-map, and prints the verdict messages + exits with
+ * verdict.exit_code.
+ *
+ * Three outcomes:
+ *   1. allow (no conflicts): exit 0.
+ *   2. allow + suppressed (self-attribution heuristic: holder's files ⊆
+ *      staged set AND no live foreign pid anchors them): exit 0, prints
+ *      "treating as self under transient identity".
+ *   3. block: exit 1, prints "Commit blocked by multi-agent coordination".
+ *
+ * `bypass: true` flips conflict → allow + warning lines (the
+ * `HARNERY_AGENT_COORD_BYPASS=1` escape hatch).
+ *
+ * Gitlink discrimination: a parent-repo staged submodule path is a pointer
+ * bump, NOT a claim on the submodule's contents. The caller supplies
+ * `staged_gitlinks[]` (cheap to compute via `git ls-files --stage`); paths
+ * in that set are matched with the staged-is-gitlink rule.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { coordEnv } from "../../../lib/env.js";
+const DEFAULT_FRESHNESS_SECS = 600;
+export function evaluateCommit(coordRoot, req) {
+    if (req.staged_paths.length === 0) {
+        return {
+            allow: true,
+            exit_code: 0,
+            rule: "commit.pass",
+            conflicts: [],
+            log_lines: [],
+            message: "",
+        };
+    }
+    const peers = readActivePeers(coordRoot);
+    const cutoffMs = Date.now() - freshnessSecs() * 1000;
+    const stagedSet = new Set(req.staged_paths);
+    const gitlinkSet = new Set(req.staged_gitlinks ?? []);
+    const conflicts = [];
+    for (const peer of peers) {
+        if (peer.instance_id === req.instance_id)
+            continue;
+        const peerSession = peer.session_id ?? peer.instance_id;
+        if (req.session_id && peerSession === req.session_id)
+            continue; // same group
+        const ts = peer.last_heartbeat ? Date.parse(peer.last_heartbeat) : 0;
+        if (!Number.isFinite(ts) || ts < cutoffMs)
+            continue; // stale
+        const files = peer.files_touched ?? [];
+        if (files.length === 0)
+            continue;
+        for (const staged of req.staged_paths) {
+            const stagedIsGitlink = gitlinkSet.has(staged);
+            const hit = findOverlap(staged, files, coordRoot, stagedIsGitlink);
+            if (!hit)
+                continue;
+            conflicts.push({
+                staged_path: staged,
+                claimed_path: hit,
+                instance_id: peer.instance_id,
+                short_name: shortName(peer),
+            });
+            break; // one conflict per peer is enough
+        }
+    }
+    if (conflicts.length === 0) {
+        return {
+            allow: true,
+            exit_code: 0,
+            rule: "commit.pass",
+            conflicts: [],
+            log_lines: [],
+            message: "",
+        };
+    }
+    if (req.bypass) {
+        return {
+            allow: true,
+            exit_code: 0,
+            rule: "commit.bypass",
+            conflicts,
+            log_lines: conflicts.map((c) => `COMMIT_BYPASSED  path=${c.staged_path} owner=${c.short_name}`),
+            message: "⚠ Multi-Agent coordination: bypass active; staged paths claimed by other agents will be committed anyway:",
+        };
+    }
+    // Self-attribution check (Fix #2): if every conflicting holder is plausibly
+    // us under a transient identity (held files_touched ⊆ the staged set AND no
+    // live foreign PID anchors the holder via pid-map), suppress the block.
+    const allSelfAttributed = conflicts.every((c) => isHolderSelfAttributed(coordRoot, c.instance_id, stagedSet, peers));
+    if (allSelfAttributed) {
+        return {
+            allow: true,
+            exit_code: 0,
+            rule: "commit.suppressed",
+            conflicts,
+            log_lines: conflicts.map((c) => `COMMIT_SUPPRESSED  path=${c.staged_path} owner=${c.short_name} reason=self_attribution`),
+            message: "⚠ Multi-Agent coordination: self-attribution detected; staged paths\n" +
+                "  are claimed by an unanchored heartbeat that holds only files in\n" +
+                "  this commit's staged set. Treating as self under a transient\n" +
+                "  identity; commit will proceed.",
+            suppressed_self_attribution: true,
+        };
+    }
+    return {
+        allow: false,
+        exit_code: 1,
+        rule: "commit.conflict",
+        conflicts,
+        log_lines: conflicts.map((c) => `COMMIT_BLOCKED  path=${c.staged_path} owner=${c.short_name}`),
+        message: "✗ Commit blocked by multi-agent coordination (E guard).\n\n" +
+            "  The following staged paths are currently claimed by other\n" +
+            "  active agents:",
+    };
+}
+function findOverlap(staged, files, coordRoot, stagedIsGitlink) {
+    for (const claimed of files) {
+        if (claimed === staged)
+            return claimed;
+        if (claimed.startsWith(`${staged}/`)) {
+            // Staged is a submodule gitlink, claimed is a file inside it. Disjoint.
+            if (stagedIsGitlink)
+                continue;
+            return claimed;
+        }
+        if (staged.startsWith(`${claimed}/`)) {
+            // Claimed is a gitlink, staged is a file inside it. Disjoint.
+            if (isGitlinkInIndex(coordRoot, claimed))
+                continue;
+            return claimed;
+        }
+    }
+    return null;
+}
+function isGitlinkInIndex(coordRoot, path) {
+    const result = spawnSync("git", ["ls-files", "--stage", "--", path], {
+        cwd: coordRoot,
+        encoding: "utf8",
+        timeout: 2000,
+    });
+    if (result.status !== 0)
+        return false;
+    // ls-files --stage emits "<mode> <sha> <stage>\t<path>"; mode 160000 = gitlink.
+    return result.stdout.trim().startsWith("160000 ");
+}
+function isHolderSelfAttributed(coordRoot, holderId, stagedSet, peers) {
+    // Gate B (cheaper): live foreign pid-map entry blocks self-attribution.
+    if (holderHasLiveForeignPid(coordRoot, holderId))
+        return false;
+    // Gate A: every held path is either in the staged set or already clean in HEAD.
+    const holder = peers.find((p) => p.instance_id === holderId);
+    if (!holder)
+        return false;
+    const files = holder.files_touched ?? [];
+    if (files.length === 0)
+        return false;
+    for (const held of files) {
+        if (stagedSet.has(held))
+            continue;
+        if (isPathCleanInHead(coordRoot, held))
+            continue;
+        return false;
+    }
+    return true;
+}
+function holderHasLiveForeignPid(coordRoot, holderId) {
+    const dir = join(coordRoot, ".harnery", "pid-map");
+    if (!existsSync(dir))
+        return false;
+    for (const f of readdirSync(dir)) {
+        let row = "";
+        try {
+            row = readFileSync(join(dir, f), "utf8").trim();
+        }
+        catch {
+            continue;
+        }
+        const owner = row.split("\t")[0]?.trim() ?? "";
+        if (owner !== holderId)
+            continue;
+        // Process still alive?
+        const pid = Number.parseInt(f, 10);
+        if (!Number.isFinite(pid))
+            continue;
+        try {
+            process.kill(pid, 0); // signal 0 = liveness probe
+            return true; // live foreign pid found
+        }
+        catch {
+            // ESRCH (no such process): pid-map entry is stale, skip
+        }
+    }
+    return false;
+}
+function isPathCleanInHead(coordRoot, relPath) {
+    // Path is tracked + diff-clean against HEAD = "already committed, holder
+    // hasn't released the claim yet". Counts as self-attributable.
+    const tracked = spawnSync("git", ["ls-files", "--error-unmatch", "--", relPath], {
+        cwd: coordRoot,
+        encoding: "utf8",
+        timeout: 2000,
+    });
+    if (tracked.status !== 0)
+        return false;
+    const diff = spawnSync("git", ["diff", "--quiet", "HEAD", "--", relPath], {
+        cwd: coordRoot,
+        encoding: "utf8",
+        timeout: 2000,
+    });
+    return diff.status === 0;
+}
+function readActivePeers(coordRoot) {
+    const dir = join(coordRoot, ".harnery", "active");
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        try {
+            const hb = JSON.parse(readFileSync(join(dir, f), "utf8"));
+            if (hb.instance_id)
+                out.push(hb);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return out;
+}
+function freshnessSecs() {
+    const raw = coordEnv("AGENT_FRESHNESS");
+    if (!raw)
+        return DEFAULT_FRESHNESS_SECS;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_FRESHNESS_SECS;
+}
+function shortName(peer) {
+    if (peer.name && peer.name.length > 0)
+        return `agent-${peer.name}`;
+    return `agent-${peer.instance_id.slice(0, 8)}`;
+}

package/dist/core/agents/rules/stop-hook.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Stop-hook verdict: rule 1/3, 2/3, 3/3 enforcement evaluated
+ * from the canonical event stream alone (no transcript scan).
+ *
+ * Rule 1/3: `state.status_checked` event with matching turn boundary exists.
+ * Rule 2/3: latest `turn.stop` event has `status_box_present: true` (or the
+ *            stop currently firing carries that field via the in-flight event
+ *            agent-hook emits before the stop hook runs).
+ * Rule 3/3: `state.task_set` event with matching turn boundary exists.
+ *
+ * Pure-prose-turn exemption: when zero `tool.pre_use` events fire in
+ * the current turn, rules 1/3 and 3/3 do not apply. Rule 2/3 still applies
+ * as a user-visible mobile cue.
+ */
+export type VerdictResult = {
+    allow: boolean;
+    exit_code: 0 | 2;
+    rule: string;
+    reason?: string;
+};
+export interface StopHookRequest {
+    rule: "stop-hook";
+    instance_id: string;
+    session_id?: string;
+    /** Firing harness. Selects the end-of-turn ack signal (see `ackSignalFor`).
+     * Undefined → Claude Code semantics (transcript-scanned status box). */
+    harness?: string;
+    /** Wall-clock cutoff for the current turn; events strictly after this are not yet relevant. */
+    now_ms?: number;
+    /** Override the turn-window discovery (used by tests). */
+    turn_window?: {
+        start_ms: number;
+        end_ms: number;
+    };
+    /** Bypass switch: operator escape hatch identical to HARNERY_AGENT_COORD_BYPASS_STOP. */
+    bypass?: boolean;
+}
+/**
+ * Evaluate the Stop-hook verdict. Returns the first failing rule (or allow
+ * when all three pass). Soft-fails open when the event stream isn't
+ * readable, fail-open posture on a verdict failure.
+ */
+export declare function evaluateStopHook(coordRoot: string, req: StopHookRequest): VerdictResult;
+//# sourceMappingURL=stop-hook.d.ts.map

package/dist/core/agents/rules/stop-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-hook.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/stop-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,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;AAcF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;4EACwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+BD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,aAAa,CA2FvF"}