harnery 0.31.5 → 0.32.0

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

@@ -224,10 +224,10 @@ export function parsePidmapRowOwner(row) {
     const tab = trimmed.indexOf("\t");
     return tab >= 0 ? trimmed.slice(0, tab) : trimmed;
 }
-/** Parse platform from a pid-map row; legacy rows default to `claude_code`. */
+/** Parse platform from a pid-map row; legacy rows default to `claude-code`. */
 export function parsePidmapRowPlatform(row) {
     const platform = row.trim().split("\t")[1]?.trim();
-    return platform || "claude_code";
+    return platform || "claude-code";
 }
 /** Parse the start token from a pid-map row; rows written before it carry none. */
 export function parsePidmapRowStartToken(row) {
@@ -336,7 +336,7 @@ function readPidmapRow(pidmapDir, pid) {
  *
  * Pid-map files are `instance_id` or `instance_id\tplatform` (Cursor Phase 1).
  * Prefer a row whose platform matches `HARNERY_AGENT_COORD_PLATFORM` (default
- * `claude_code`); otherwise return the first owner seen on the walk.
+ * `claude-code`); otherwise return the first owner seen on the walk.
  *
  * Subagents intentionally do not write pid-map entries; a Bash-tool ppid-walk
  * from inside a subagent therefore resolves to the *parent's* pid-map entry.
@@ -400,7 +400,7 @@ export function resolveOwnerByPidmap(root) {
     const pidmapDir = resolve(root, ".harnery", "pid-map");
     if (!existsSync(pidmapDir))
         return { owner: null, source: "none" };
-    const prefer = process.env.HARNERY_AGENT_COORD_PLATFORM?.trim() || "claude_code";
+    const prefer = process.env.HARNERY_AGENT_COORD_PLATFORM?.trim() || "claude-code";
     let fallbackOwner = null;
     let pid = process.pid;
     for (let hop = 0; hop < 20; hop++) {
@@ -439,6 +439,7 @@ const SESSION_ID_ENV_VARS = [
     "CURSOR_SESSION_ID",
     "CURSOR_CONVERSATION_ID",
     "CODEX_SESSION_ID",
+    "CODEX_THREAD_ID",
 ];
 /** Read normalized candidates from the first non-empty adapter session-id env var. */
 function sessionIdsFromEnv() {
@@ -482,7 +483,10 @@ function shouldPreferSessionEnv() {
  * `instance_id`, or null if there's no session-id env var or no live heartbeat
  * carries it. "Live" reuses the same 10-minute freshness window the singleton
  * fallback applies, so a stale heartbeat from a prior session of the same id
- * doesn't resolve.
+ * doesn't resolve. When legacy Cursor Glass state contains both the canonical
+ * bare id and its raw `bc-` alias, candidate order wins first; ties prefer a
+ * named heartbeat, then the newest heartbeat, with instance id as a stable
+ * final tie-breaker. Filesystem enumeration order never decides identity.
  *
  * Exported for unit testing with an injectable root.
  */
@@ -502,24 +506,38 @@ export function resolveOwnerBySessionEnv(root) {
     catch {
         return null;
     }
+    const matches = [];
     for (const file of files) {
         if (!file.endsWith(".json"))
             continue;
         try {
             const parsed = JSON.parse(readFileSync(resolve(activeDir, file), "utf8"));
-            if (!parsed || !sessionIds.includes(parsed.session_id))
+            if (!parsed)
+                continue;
+            const sessionPreference = sessionIds.indexOf(parsed.session_id);
+            if (sessionPreference === -1)
                 continue;
             if (typeof parsed.instance_id !== "string")
                 continue;
             const ts = Date.parse(parsed.last_heartbeat);
-            if (Number.isFinite(ts) && ts >= cutoffMs)
-                return parsed.instance_id;
+            if (!Number.isFinite(ts) || ts < cutoffMs)
+                continue;
+            matches.push({
+                instanceId: parsed.instance_id,
+                sessionPreference,
+                hasName: typeof parsed.name === "string" && parsed.name.trim().length > 0,
+                lastHeartbeatMs: ts,
+            });
         }
         catch {
             // skip malformed
         }
     }
-    return null;
+    matches.sort((a, b) => a.sessionPreference - b.sessionPreference ||
+        Number(b.hasName) - Number(a.hasName) ||
+        b.lastHeartbeatMs - a.lastHeartbeatMs ||
+        a.instanceId.localeCompare(b.instanceId));
+    return matches[0]?.instanceId ?? null;
 }
 /**
  * Return the instance_id of the sole live agent in this coord root, or null

package/dist/core/agents/finalization.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Ownership-aware Git completion checks for the end-of-turn status ritual.
+ *
+ * The heartbeat's durable `files_touched` ledger is the ownership boundary. We
+ * inspect only those paths, plus any enclosing submodule gitlinks, so a peer's
+ * active edits elsewhere in a shared checkout do not block this session.
+ */
+import { type AgentFinalizationDisposition } from "../config.js";
+export interface GitFinalizationResult {
+    ok: boolean;
+    claim_history_complete: boolean;
+    dirty_paths: string[];
+    unpushed_repos: string[];
+    host_output_paths: string[];
+    unsupported_paths: UnsupportedFinalizationPath[];
+    unverifiable_paths: string[];
+    unverifiable_repos: string[];
+    repos_checked: string[];
+}
+export type UnsupportedFinalizationReason = "outside_finalization_roots" | "invalid_finalization_root" | "ambiguous_finalization_roots" | "path_escapes_finalization_root" | "git_repository_unavailable" | "output_path_is_git";
+export interface UnsupportedFinalizationPath {
+    path: string;
+    reason: UnsupportedFinalizationReason;
+}
+export interface ClaimFinalizationDescriptor {
+    disposition: AgentFinalizationDisposition;
+    root: string;
+}
+export type ClaimFinalizationDecision = {
+    allow: true;
+    path: string;
+    descriptor: ClaimFinalizationDescriptor;
+    authorityRoot: string;
+    repo?: {
+        root: string;
+        path: string;
+    };
+} | {
+    allow: false;
+    path: string;
+    reason: UnsupportedFinalizationReason;
+};
+export interface SessionWriteClaims {
+    paths: string[];
+    complete: boolean;
+}
+/**
+ * Read every write claim made by this session, including claims released after
+ * a commit. Current heartbeat claims describe dirty ownership; this history is
+ * what keeps the touched repository in scope until its commits are pushed.
+ */
+export declare function readSessionWriteClaims(coordRoot: string, instanceId: string, sessionId: string): SessionWriteClaims;
+/**
+ * Resolve one guarded write to the host's single supported end-turn
+ * disposition. Claim event data never grants authority: every call starts from
+ * the project-owned finalization roots and only then inspects the selected
+ * repository or output tree.
+ */
+export declare function classifyWriteClaimFinalization(coordRoot: string, heldPath: string): ClaimFinalizationDecision;
+/** Check that this session's held paths are committed and their repositories are pushed. */
+export declare function checkGitFinalization(coordRoot: string, heldPaths: readonly string[], options?: {
+    claimHistoryComplete?: boolean;
+}): GitFinalizationResult;
+export declare function formatGitFinalizationFailure(result: GitFinalizationResult, bin: string): string;
+export declare function formatWriteClaimFinalizationDenial(decision: Extract<ClaimFinalizationDecision, {
+    allow: false;
+}>, bin: string): string;
+//# sourceMappingURL=finalization.d.ts.map

package/dist/core/agents/finalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalization.d.ts","sourceRoot":"","sources":["../../../src/core/agents/finalization.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAE,KAAK,4BAA4B,EAA2B,MAAM,cAAc,CAAC;AA4B1F,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,OAAO,CAAC;IACZ,sBAAsB,EAAE,OAAO,CAAC;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,iBAAiB,EAAE,2BAA2B,EAAE,CAAC;IACjD,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,MAAM,6BAA6B,GACrC,4BAA4B,GAC5B,2BAA2B,GAC3B,8BAA8B,GAC9B,gCAAgC,GAChC,4BAA4B,GAC5B,oBAAoB,CAAC;AAEzB,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,6BAA6B,CAAC;CACvC;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,yBAAyB,GACjC;IACE,KAAK,EAAE,IAAI,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,2BAA2B,CAAC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC,GACD;IACE,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,6BAA6B,CAAC;CACvC,CAAC;AAEN,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,kBAAkB,CA+BpB;AA+JD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,yBAAyB,CA2D3B;AA2ED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,OAAO,GAAE;IAAE,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/C,qBAAqB,CA6EvB;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAkD/F;AAmBD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,OAAO,CAAC,yBAAyB,EAAE;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC,EAC9D,GAAG,EAAE,MAAM,GACV,MAAM,CAQR"}

package/dist/core/agents/finalization.js

@@ -0,0 +1,443 @@
+/**
+ * Ownership-aware Git completion checks for the end-of-turn status ritual.
+ *
+ * The heartbeat's durable `files_touched` ledger is the ownership boundary. We
+ * inspect only those paths, plus any enclosing submodule gitlinks, so a peer's
+ * active edits elsewhere in a shared checkout do not block this session.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { agentsFinalizationRoots } from "../config.js";
+import { readStreamTailBounded } from "./events/consume.js";
+const CLAIM_HISTORY_CAP_BYTES = 128 * 1024 * 1024;
+const GIT_DISCOVERY_VARS = [
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_COMMON_DIR",
+    "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "GIT_PREFIX",
+    "GIT_NAMESPACE",
+];
+/**
+ * Read every write claim made by this session, including claims released after
+ * a commit. Current heartbeat claims describe dirty ownership; this history is
+ * what keeps the touched repository in scope until its commits are pushed.
+ */
+export function readSessionWriteClaims(coordRoot, instanceId, sessionId) {
+    const streamPath = join(coordRoot, ".harnery", "events.ndjson");
+    const { text, truncated } = readStreamTailBounded(streamPath, CLAIM_HISTORY_CAP_BYTES);
+    const paths = new Set();
+    let sawSessionStart = false;
+    for (const line of text.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event.instance_id !== instanceId || event.session_id !== sessionId)
+                continue;
+            if (event.event_type === "session.start")
+                sawSessionStart = true;
+            if (event.event_type === "claim.acquire" &&
+                event.data?.mode === "write" &&
+                typeof event.data.path === "string") {
+                paths.add(event.data.path);
+            }
+        }
+        catch {
+            // Ignore malformed and crash-truncated event lines, matching the
+            // canonical stream consumer's recovery behavior.
+        }
+    }
+    return { paths: [...paths], complete: !truncated || sawSessionStart };
+}
+function git(args, cwd) {
+    const env = { ...process.env };
+    for (const name of GIT_DISCOVERY_VARS)
+        delete env[name];
+    const result = spawnSync("git", args, { cwd, env, encoding: "utf8", timeout: 5_000 });
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? result.error?.message ?? "",
+    };
+}
+function repoLabel(coordRoot, repoRoot) {
+    const rel = relative(coordRoot, repoRoot).replaceAll("\\", "/");
+    return rel.length === 0 ? "." : rel;
+}
+function pathInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function existingProbeDir(authorityRoot, absolutePath) {
+    let current = absolutePath;
+    if (existsSync(current) && !statSync(current).isDirectory())
+        current = dirname(current);
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current || !pathInside(authorityRoot, parent))
+            return null;
+        current = parent;
+    }
+    return pathInside(authorityRoot, current) ? current : null;
+}
+/** Resolve existing ancestors through symlinks while preserving a missing tail. */
+function physicalPath(absolutePath) {
+    let existing = absolutePath;
+    while (!existsSync(existing)) {
+        const parent = dirname(existing);
+        if (parent === existing)
+            return null;
+        existing = parent;
+    }
+    try {
+        const physical = realpathSync.native(existing);
+        const tail = relative(existing, absolutePath);
+        return resolve(physical, tail);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Translate a Windows-native WSL UNC claim back to the Linux path seen by the
+ * coordination process. Codex can report `\\\\wsl.localhost\\<distro>\\...`
+ * while Harnery runs inside that distro with a `/...` coord root.
+ */
+function resolveHeldPath(coordRoot, heldPath) {
+    const wslUnc = /^\\\\(?:wsl\.localhost|wsl\$)\\[^\\]+\\(.+)$/i.exec(heldPath);
+    if (wslUnc) {
+        const linuxPath = `/${wslUnc[1].replaceAll("\\", "/")}`;
+        const slashRoot = coordRoot.replaceAll("\\", "/");
+        if (slashRoot.startsWith("/") || pathInside(coordRoot, linuxPath))
+            return linuxPath;
+    }
+    return resolve(coordRoot, heldPath);
+}
+function discoverRepo(authorityRoot, absolutePath) {
+    const probeDir = existingProbeDir(authorityRoot, absolutePath);
+    if (!probeDir)
+        return null;
+    const rootResult = git(["rev-parse", "--show-toplevel"], probeDir);
+    if (rootResult.status !== 0)
+        return null;
+    const repoRoot = physicalPath(resolve(rootResult.stdout.trim()));
+    if (!repoRoot || !pathInside(authorityRoot, repoRoot) || !pathInside(repoRoot, absolutePath)) {
+        return null;
+    }
+    const repoPath = relative(repoRoot, absolutePath).replaceAll("\\", "/") || ".";
+    return { root: repoRoot, path: repoPath };
+}
+function rootIsGitRepository(root) {
+    if (!existsSync(root) || !statSync(root).isDirectory())
+        return false;
+    const result = git(["rev-parse", "--show-toplevel"], root);
+    if (result.status !== 0)
+        return false;
+    const discovered = physicalPath(resolve(result.stdout.trim()));
+    const physicalRoot = physicalPath(root);
+    return discovered !== null && physicalRoot !== null && discovered === physicalRoot;
+}
+function outputRootIsInsideGit(root) {
+    let probe = root;
+    while (!existsSync(probe)) {
+        const parent = dirname(probe);
+        if (parent === probe)
+            return false;
+        probe = parent;
+    }
+    if (!statSync(probe).isDirectory())
+        probe = dirname(probe);
+    return git(["rev-parse", "--show-toplevel"], probe).status === 0;
+}
+function finalizationRoots(coordRoot) {
+    const root = resolve(coordRoot);
+    const configured = agentsFinalizationRoots(root).map((entry) => {
+        const lexicalRoot = resolveHeldPath(root, entry.path);
+        const physicalRoot = physicalPath(lexicalRoot);
+        const invalid = physicalRoot === null ||
+            (entry.disposition === "git"
+                ? !rootIsGitRepository(physicalRoot)
+                : outputRootIsInsideGit(physicalRoot));
+        return {
+            configuredPath: entry.path,
+            disposition: entry.disposition,
+            lexicalRoot,
+            physicalRoot,
+            invalid,
+        };
+    });
+    const rootPhysical = physicalPath(root);
+    if (rootPhysical && rootIsGitRepository(rootPhysical)) {
+        configured.push({
+            configuredPath: ".",
+            disposition: "git",
+            lexicalRoot: root,
+            physicalRoot: rootPhysical,
+            invalid: false,
+        });
+    }
+    for (const current of configured) {
+        if (!current.physicalRoot)
+            continue;
+        for (const peer of configured) {
+            if (current === peer || !peer.physicalRoot || current.disposition === peer.disposition) {
+                continue;
+            }
+            if (pathInside(current.physicalRoot, peer.physicalRoot) ||
+                pathInside(peer.physicalRoot, current.physicalRoot)) {
+                current.invalid = true;
+                peer.invalid = true;
+            }
+        }
+    }
+    return configured;
+}
+/**
+ * Resolve one guarded write to the host's single supported end-turn
+ * disposition. Claim event data never grants authority: every call starts from
+ * the project-owned finalization roots and only then inspects the selected
+ * repository or output tree.
+ */
+export function classifyWriteClaimFinalization(coordRoot, heldPath) {
+    const root = resolve(coordRoot);
+    const absolutePath = resolveHeldPath(root, heldPath);
+    const roots = finalizationRoots(root);
+    const lexicalMatches = roots.filter((entry) => pathInside(entry.lexicalRoot, absolutePath));
+    if (lexicalMatches.length === 0) {
+        return { allow: false, path: heldPath, reason: "outside_finalization_roots" };
+    }
+    if (lexicalMatches.some((entry) => entry.invalid)) {
+        return { allow: false, path: heldPath, reason: "invalid_finalization_root" };
+    }
+    const physical = physicalPath(absolutePath);
+    if (!physical) {
+        return { allow: false, path: heldPath, reason: "path_escapes_finalization_root" };
+    }
+    const matches = lexicalMatches.filter((entry) => entry.physicalRoot && pathInside(entry.physicalRoot, physical));
+    if (matches.length === 0) {
+        return { allow: false, path: heldPath, reason: "path_escapes_finalization_root" };
+    }
+    const dispositions = new Set(matches.map((entry) => entry.disposition));
+    if (dispositions.size !== 1) {
+        return { allow: false, path: heldPath, reason: "ambiguous_finalization_roots" };
+    }
+    const selected = [...matches].sort((a, b) => (b.physicalRoot?.length ?? 0) - (a.physicalRoot?.length ?? 0))[0];
+    const normalizedPath = relative(root, absolutePath).replaceAll("\\", "/") || ".";
+    const descriptor = {
+        disposition: selected.disposition,
+        root: selected.configuredPath,
+    };
+    if (selected.disposition === "output") {
+        const probe = existingProbeDir(selected.physicalRoot, physical);
+        if (probe && git(["rev-parse", "--show-toplevel"], probe).status === 0) {
+            return { allow: false, path: heldPath, reason: "output_path_is_git" };
+        }
+        return {
+            allow: true,
+            path: normalizedPath,
+            descriptor,
+            authorityRoot: selected.physicalRoot,
+        };
+    }
+    const repo = discoverRepo(selected.physicalRoot, physical);
+    if (!repo) {
+        return { allow: false, path: heldPath, reason: "git_repository_unavailable" };
+    }
+    return {
+        allow: true,
+        path: normalizedPath,
+        descriptor,
+        authorityRoot: selected.physicalRoot,
+        repo,
+    };
+}
+function addRepoPath(repos, root, path, gitlink = false) {
+    const work = repos.get(root) ?? {
+        root,
+        paths: new Set(),
+        gitlinks: new Set(),
+    };
+    work.paths.add(path);
+    if (gitlink)
+        work.gitlinks.add(path);
+    repos.set(root, work);
+}
+function addSuperprojects(authorityRoot, repos, leafRoot) {
+    let childRoot = leafRoot;
+    for (;;) {
+        const result = git(["rev-parse", "--show-superproject-working-tree"], childRoot);
+        if (result.status !== 0 || result.stdout.trim().length === 0)
+            return;
+        const parentRoot = physicalPath(resolve(result.stdout.trim()));
+        if (!parentRoot || !pathInside(authorityRoot, parentRoot) || parentRoot === childRoot)
+            return;
+        const gitlink = relative(parentRoot, childRoot).replaceAll("\\", "/");
+        addRepoPath(repos, parentRoot, gitlink, true);
+        childRoot = parentRoot;
+    }
+}
+function repoHasRemote(repoRoot) {
+    const result = git(["remote"], repoRoot);
+    return result.status === 0 && result.stdout.trim().length > 0;
+}
+function repoSyncState(repoRoot) {
+    if (!repoHasRemote(repoRoot))
+        return "synced";
+    if (git(["rev-parse", "--verify", "HEAD"], repoRoot).status !== 0)
+        return "unverifiable";
+    const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], repoRoot);
+    if (upstream.status === 0) {
+        const ahead = git(["rev-list", "--count", "@{upstream}..HEAD"], repoRoot);
+        if (ahead.status !== 0)
+            return "unverifiable";
+        return Number.parseInt(ahead.stdout.trim(), 10) > 0 ? "unpushed" : "synced";
+    }
+    // Detached submodules commonly have no upstream. A remote ref containing
+    // HEAD proves that commit is available elsewhere without requiring a branch.
+    const containing = git(["branch", "--remotes", "--contains", "HEAD", "--format=%(refname:short)"], repoRoot);
+    if (containing.status !== 0)
+        return "unverifiable";
+    return containing.stdout.trim().length > 0 ? "synced" : "unpushed";
+}
+/** Compare gitlink commits without treating dirty contents inside the child as a pointer change. */
+function gitlinkIsDirty(parentRoot, gitlink) {
+    const head = git(["rev-parse", `HEAD:${gitlink}`], parentRoot);
+    const index = git(["ls-files", "--stage", "--", gitlink], parentRoot);
+    const child = git(["rev-parse", "HEAD"], join(parentRoot, gitlink));
+    if (head.status !== 0 || index.status !== 0 || child.status !== 0)
+        return true;
+    const indexMatch = /^160000 ([0-9a-f]{40}) 0\t/.exec(index.stdout.trim());
+    if (!indexMatch)
+        return true;
+    return head.stdout.trim() !== indexMatch[1] || child.stdout.trim() !== indexMatch[1];
+}
+/** Check that this session's held paths are committed and their repositories are pushed. */
+export function checkGitFinalization(coordRoot, heldPaths, options = {}) {
+    const root = resolve(coordRoot);
+    const repos = new Map();
+    const hostOutputPaths = new Set();
+    const unsupportedPaths = [];
+    const unverifiablePaths = [];
+    for (const heldPath of heldPaths) {
+        const decision = classifyWriteClaimFinalization(root, heldPath);
+        if (!decision.allow) {
+            unsupportedPaths.push({ path: heldPath, reason: decision.reason });
+            continue;
+        }
+        if (decision.descriptor.disposition === "output") {
+            hostOutputPaths.add(decision.path);
+            continue;
+        }
+        if (!decision.repo) {
+            unsupportedPaths.push({ path: heldPath, reason: "git_repository_unavailable" });
+            continue;
+        }
+        addRepoPath(repos, decision.repo.root, decision.repo.path);
+        addSuperprojects(decision.authorityRoot, repos, decision.repo.root);
+    }
+    const dirtyPaths = new Set();
+    const unpushedRepos = [];
+    const unverifiableRepos = [];
+    for (const work of repos.values()) {
+        for (const repoPath of work.paths) {
+            if (work.gitlinks.has(repoPath)) {
+                if (gitlinkIsDirty(work.root, repoPath)) {
+                    const label = repoLabel(root, work.root);
+                    dirtyPaths.add(label === "." ? repoPath : `${label}/${repoPath}`);
+                }
+                continue;
+            }
+            const status = git(["status", "--porcelain=v1", "--untracked-files=all", "--", repoPath], work.root);
+            if (status.status !== 0) {
+                unverifiablePaths.push(join(repoLabel(root, work.root), repoPath).replaceAll("\\", "/"));
+            }
+            else if (status.stdout.length > 0) {
+                const label = repoLabel(root, work.root);
+                dirtyPaths.add(label === "." ? repoPath : `${label}/${repoPath}`);
+            }
+        }
+        const syncState = repoSyncState(work.root);
+        const label = repoLabel(root, work.root);
+        if (syncState === "unpushed")
+            unpushedRepos.push(label);
+        if (syncState === "unverifiable")
+            unverifiableRepos.push(label);
+    }
+    const result = {
+        ok: false,
+        claim_history_complete: options.claimHistoryComplete ?? true,
+        dirty_paths: [...dirtyPaths].sort(),
+        unpushed_repos: [...new Set(unpushedRepos)].sort(),
+        host_output_paths: [...hostOutputPaths].sort(),
+        unsupported_paths: unsupportedPaths.sort((a, b) => a.path.localeCompare(b.path) || a.reason.localeCompare(b.reason)),
+        unverifiable_paths: [...new Set(unverifiablePaths)].sort(),
+        unverifiable_repos: [...new Set(unverifiableRepos)].sort(),
+        repos_checked: [...repos.keys()].map((repo) => repoLabel(root, repo)).sort(),
+    };
+    result.ok =
+        result.claim_history_complete &&
+            result.dirty_paths.length === 0 &&
+            result.unpushed_repos.length === 0 &&
+            result.unsupported_paths.length === 0 &&
+            result.unverifiable_paths.length === 0 &&
+            result.unverifiable_repos.length === 0;
+    return result;
+}
+export function formatGitFinalizationFailure(result, bin) {
+    const lines = ["Owned work is not finalized; the status box was not issued."];
+    if (!result.claim_history_complete) {
+        lines.push("This session's write-claim history is older than the bounded event window.");
+    }
+    if (result.dirty_paths.length > 0) {
+        lines.push("Dirty owned paths:", ...result.dirty_paths.map((path) => `  - ${path}`));
+    }
+    if (result.unpushed_repos.length > 0) {
+        lines.push("Repositories with commits not on their remote:", ...result.unpushed_repos.map((repo) => `  - ${repo}`));
+    }
+    if (result.unsupported_paths.length > 0) {
+        lines.push("Paths without an authorized end-turn disposition:", ...result.unsupported_paths.map(({ path, reason }) => `  - ${path}: ${unsupportedReasonMessage(reason)}`));
+    }
+    if (result.unverifiable_paths.length > 0) {
+        lines.push("Paths whose Git state could not be verified:", ...result.unverifiable_paths.map((path) => `  - ${path}`));
+    }
+    if (result.unverifiable_repos.length > 0) {
+        lines.push("Repositories whose remote state could not be verified:", ...result.unverifiable_repos.map((repo) => `  - ${repo}`));
+    }
+    if (result.dirty_paths.length > 0 ||
+        result.unpushed_repos.length > 0 ||
+        result.unverifiable_paths.length > 0 ||
+        result.unverifiable_repos.length > 0) {
+        lines.push(`Commit and push the owned Git work, then rerun \`${bin} agents status --end-turn\`.`);
+    }
+    if (result.unsupported_paths.length > 0) {
+        lines.push("For a legacy claim, add the containing Git repository or intentional non-Git output root to the project's `agents.finalizationRoots`, then rerun the guarded status. For new work, start the task from the target Git project or configure that root before editing.");
+    }
+    return lines.join("\n");
+}
+function unsupportedReasonMessage(reason) {
+    switch (reason) {
+        case "outside_finalization_roots":
+            return "outside the coordination repository and project-configured finalization roots";
+        case "invalid_finalization_root":
+            return "the matching project-configured root is invalid or overlaps another disposition";
+        case "ambiguous_finalization_roots":
+            return "more than one finalization disposition matches this path";
+        case "path_escapes_finalization_root":
+            return "the resolved path escapes its configured root";
+        case "git_repository_unavailable":
+            return "the configured Git root does not contain a verifiable repository for this path";
+        case "output_path_is_git":
+            return "the configured non-Git output path is inside a Git repository";
+    }
+}
+export function formatWriteClaimFinalizationDenial(decision, bin) {
+    return (`Harnery denied the write to ${decision.path} before mutation: ` +
+        `${unsupportedReasonMessage(decision.reason)}. ` +
+        "Start the task from the target Git project, or add its Git repository root " +
+        "(or an intentional non-Git output root) to the project's `agents.finalizationRoots` " +
+        `before editing. Then retry the tool and finish with \`${bin} agents status --end-turn\`.`);
+}

package/dist/core/agents/git-hook.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Git-plumbing collection for `agent-coord git-hook <event>` — the in-process
+ * replacement for the bash that host pre-commit / post-commit / post-checkout
+ * hooks used to carry.
+ *
+ * Everything here is a port of hook logic that lived in host repos as shell:
+ * staged-path collection with rename handling, submodule canonicalization,
+ * the gitlink probe, and the clean-in-worktree checks that gate claim pruning.
+ * Owning it here means a harnery upgrade upgrades the behavior; the host hook
+ * file keeps only a stable managed region that invokes `git-hook <event>`.
+ *
+ * All functions take an explicit cwd and return data — no printing, no
+ * process.exit — so they unit-test against a temp repo.
+ */
+export type GitHookEvent = "pre-commit" | "post-commit" | "post-checkout";
+/**
+ * The coordination root for a hook firing in `cwd`: the superproject when the
+ * repo is a submodule, else the repo's own toplevel. Pinning to the
+ * superproject matters because some submodules carry a config-only `.harnery/`
+ * that a cwd walk would land on, running the check against an empty claims dir.
+ */
+export declare function discoverCoordRoot(cwd: string): string | null;
+/** Monorepo-relative prefix when `cwd` is inside a submodule ("" in the parent). */
+export declare function submodulePrefix(cwd: string): string;
+/**
+ * Parse `--name-status -M` output into repo-local paths. Renames/copies emit
+ * BOTH sides so the source's claim releases too; plain statuses emit one.
+ */
+export declare function parseNameStatus(output: string): string[];
+/**
+ * pre-commit: staged paths (canonical, monorepo-relative) plus which of them
+ * are submodule gitlinks — a parent-repo pointer bump is not a claim on the
+ * submodule's contents, and the conflict rule's prefix matcher needs to know.
+ */
+export declare function collectStaged(cwd: string): {
+    staged: string[];
+    gitlinks: string[];
+};
+/**
+ * post-commit: paths the just-landed HEAD commit touched that are now clean in
+ * the worktree. A path with unstaged residue keeps its claim — the agent is
+ * still mid-work on it.
+ */
+export declare function collectCommitted(cwd: string): string[];
+/**
+ * post-checkout: paths the ref move rewrote that are now clean — a checkout
+ * that discarded an agent's edits should release its claims so a peer's later
+ * Edit isn't falsely blocked. `oldRef`/`newRef` are the hook's $1/$2.
+ */
+export declare function collectCheckoutRemoved(cwd: string, oldRef: string, newRef: string): string[];
+//# sourceMappingURL=git-hook.d.ts.map

package/dist/core/agents/git-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-hook.d.ts","sourceRoot":"","sources":["../../../src/core/agents/git-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,aAAa,GAAG,eAAe,CAAC;AAO1E;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK5D;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAcxD;AAgBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAWnF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAStD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM5F"}