harnery 0.31.6 → 0.33.0

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

package/dist/core/agents/git-hook.js

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+import { spawnSync } from "node:child_process";
+function git(args, cwd) {
+    const r = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 5000 });
+    return r.status === 0 ? (r.stdout ?? "") : "";
+}
+/**
+ * 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 function discoverCoordRoot(cwd) {
+    const superproject = git(["rev-parse", "--show-superproject-working-tree"], cwd).trim();
+    if (superproject)
+        return superproject;
+    const toplevel = git(["rev-parse", "--show-toplevel"], cwd).trim();
+    return toplevel || null;
+}
+/** Monorepo-relative prefix when `cwd` is inside a submodule ("" in the parent). */
+export function submodulePrefix(cwd) {
+    const superproject = git(["rev-parse", "--show-superproject-working-tree"], cwd).trim();
+    if (!superproject)
+        return "";
+    const toplevel = git(["rev-parse", "--show-toplevel"], cwd).trim();
+    if (!toplevel.startsWith(`${superproject}/`))
+        return "";
+    return toplevel.slice(superproject.length + 1);
+}
+/**
+ * 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 function parseNameStatus(output) {
+    const paths = [];
+    for (const line of output.split("\n")) {
+        if (!line.trim())
+            continue;
+        const parts = line.split("\t");
+        const status = parts[0] ?? "";
+        if (/^[RC]/.test(status)) {
+            if (parts[1])
+                paths.push(parts[1]);
+            if (parts[2])
+                paths.push(parts[2]);
+        }
+        else if (parts[1]) {
+            paths.push(parts[1]);
+        }
+    }
+    return paths;
+}
+function canonicalize(paths, prefix) {
+    return prefix ? paths.map((p) => `${prefix}/${p}`) : [...paths];
+}
+/** Is this repo-local path a submodule gitlink (mode 160000) in the index? */
+function isGitlink(path, cwd) {
+    return git(["ls-files", "--stage", "--", path], cwd).startsWith("160000 ");
+}
+/** Is this repo-local path clean in the worktree (no unstaged residue)? */
+function isCleanInWorktree(path, cwd) {
+    return git(["status", "--porcelain", "--", path], cwd).trim() === "";
+}
+/**
+ * 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 function collectStaged(cwd) {
+    const out = git(["diff", "--cached", "--name-status", "-M"], cwd);
+    const local = parseNameStatus(out);
+    const prefix = submodulePrefix(cwd);
+    const staged = canonicalize(local, prefix);
+    const gitlinks = [];
+    for (let i = 0; i < local.length; i++) {
+        const l = local[i];
+        if (isGitlink(l, cwd))
+            gitlinks.push(staged[i]);
+    }
+    return { staged, gitlinks };
+}
+/**
+ * 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 function collectCommitted(cwd) {
+    // --root: a repo's first commit has no parent; without it diff-tree emits
+    // nothing and the root commit's claims never prune (a bash-era blind spot).
+    const out = git(["diff-tree", "--no-commit-id", "--name-status", "-M", "-r", "--root", "HEAD"], cwd);
+    const local = parseNameStatus(out).filter((p) => isCleanInWorktree(p, cwd));
+    return canonicalize(local, submodulePrefix(cwd));
+}
+/**
+ * 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 function collectCheckoutRemoved(cwd, oldRef, newRef) {
+    const from = oldRef || "0000000000000000000000000000000000000000";
+    const to = newRef || "HEAD";
+    const out = git(["diff", "--name-status", "-M", from, to], cwd);
+    const local = parseNameStatus(out).filter((p) => isCleanInWorktree(p, cwd));
+    return canonicalize(local, submodulePrefix(cwd));
+}

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

@@ -11,4 +11,5 @@
 export * from "./canonical-emit.js";
 export * from "./coord-client.js";
 export * from "./session-events.js";
+export * from "./state/session-state.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}

package/dist/core/agents/index.js

@@ -11,3 +11,4 @@
 export * from "./canonical-emit.js";
 export * from "./coord-client.js";
 export * from "./session-events.js";
+export * from "./state/session-state.js";

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

@@ -12,11 +12,12 @@
  *      + sorted(files_touched) + platform, sorted by instance_id).
  *   2. Council pending: pending open-council IDs hashed; re-emits when the
  *      ID set changes.
- *   3. Focus nudge. Before the first set-task in a human-facing session, tells
- *      every adapter to reproduce set-task's suggested session name in a fenced
- *      code block. Cursor/Codex additionally get the existing unset/stale-task
- *      reminder because their Stop hooks do not enforce task declarations as
- *      reliably as Claude Code's.
+ *   3. Focus nudge. Until the session has produced its suggested name (first
+ *      non-empty set-task), tells every adapter — on every prompt, undeduped —
+ *      to reproduce set-task's suggested session name in a fenced code block.
+ *      Cursor/Codex additionally get the existing unset/stale-task reminder
+ *      because their Stop hooks do not enforce task declarations as reliably
+ *      as Claude Code's.
  *   4. Codex status footer: a non-deduplicated reminder to put the live status
  *      box after the substantive answer. Stop stays observe-only, so missing the
  *      footer can never trigger a replacement response.
@@ -42,6 +43,12 @@ export interface PromptContextOpts {
     /** When true, append the non-deduplicated Codex status-footer reminder.
      * The caller enables this only for human-facing Codex sessions. */
     statusFooterNudge?: boolean;
+    /** Adapter id whose Stop hook ENFORCES the end-of-turn ritual (task_set +
+     * status check). When set, append a fresh per-prompt reminder of that
+     * contract so the model satisfies it before ending the turn instead of
+     * being bounced into a retry. Not hash-deduped, same rationale as the
+     * status footer. */
+    turnRitualNudge?: string;
 }
 /**
  * Build the combined UserPromptSubmit additionalContext string. Returns "" when

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

@@ -1 +1 @@
-{"version":3,"file":"prompt-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/prompt-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAoCH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;8EAC0E;IAC1E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;kFAC8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;uEACmE;IACnE,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CA0CnE"}
+{"version":3,"file":"prompt-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/prompt-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA0CH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;8EAC0E;IAC1E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;kFAC8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;uEACmE;IACnE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;wBAIoB;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAqDnE"}