@hcflabs/pi-subagent 0.0.0-stage → 27.10.8

package/dist/prune.js

@@ -0,0 +1,205 @@
+import { existsSync, realpathSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+import { createHerdrClient } from "@hcflabs/pi-herdr";
+import { runGit } from "./git-process.js";
+import { runProcess } from "./process.js";
+import { inspectWorktreeDirty, OWNED_BRANCH_PATTERN, WORKTREES_DIRNAME } from "./worktree.js";
+const HERDR_TIMEOUT_MS = 30_000;
+const IN_PROGRESS_MARKERS = ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "REBASE_HEAD", "BISECT_LOG", "rebase-merge", "rebase-apply", "sequencer"];
+/** Blockers that a separately confirmed force removal of an unowned item may override; every other kind is hard. */
+export const FORCEABLE_PRUNE_BLOCKERS = ["unmerged", "changes", "operation", "submodules"];
+const forceable = (kind) => FORCEABLE_PRUNE_BLOCKERS.includes(kind);
+export async function requireGit(run, args, cwd) {
+    const result = await run(args, cwd);
+    if (result.code !== 0)
+        throw new Error(`git ${args[0]} failed (exit ${result.code}): ${result.stderr.trim().slice(0, 200)}`);
+    return result.stdout.trimEnd();
+}
+export const within = (directory, path) => path === directory || path.startsWith(`${directory}${sep}`);
+/** Every pane in every Herdr workspace with its shell and foreground working directories. */
+export async function listHerdrPanes(cwd) {
+    const response = await createHerdrClient(runProcess).json(["pane", "list"], { cwd, timeoutMs: HERDR_TIMEOUT_MS });
+    const result = response.result;
+    if (result?.type !== "pane_list" || !Array.isArray(result.panes))
+        throw new Error("Herdr pane list response is malformed.");
+    return result.panes.map((pane) => {
+        const cwds = [pane.cwd, pane.foreground_cwd].filter((cwd) => typeof cwd === "string");
+        if (typeof pane.pane_id !== "string" || !cwds.length)
+            throw new Error("Herdr listed a pane without an ID or working directory.");
+        return { paneId: pane.pane_id, cwds };
+    });
+}
+async function snapshot(root, mainCwd, run) {
+    const checkouts = [];
+    let current;
+    for (const field of (await requireGit(run, ["worktree", "list", "--porcelain", "-z"], root)).split("\0")) {
+        if (field.startsWith("worktree "))
+            checkouts.push(current = { path: field.slice("worktree ".length), locked: false, missing: false });
+        else if (current && field.startsWith("branch refs/heads/"))
+            current.branch = field.slice("branch refs/heads/".length);
+        else if (current && (field === "locked" || field.startsWith("locked ")))
+            current.locked = true;
+        else if (current && (field === "prunable" || field.startsWith("prunable ")))
+            current.missing = true;
+    }
+    if (!checkouts[0])
+        throw new Error("Primary Git worktree is unavailable.");
+    const branches = new Map();
+    for (const line of (await requireGit(run, ["for-each-ref", "--format=%(refname:lstrip=2) %(objectname)", "refs/heads/"], root)).split("\n")) {
+        const [branch, tip] = line.split(" ");
+        if (branch && tip && OWNED_BRANCH_PATTERN.test(branch))
+            branches.set(branch, tip);
+    }
+    const targets = [{ label: "Main HEAD", head: await requireGit(run, ["rev-parse", "--verify", "HEAD^{commit}"], mainCwd) }];
+    const origin = await run(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], root);
+    if (origin.code === 0) {
+        const ref = origin.stdout.trim();
+        targets.push({ label: ref.replace(/^refs\/remotes\//, ""), head: await requireGit(run, ["rev-parse", "--verify", `${ref}^{commit}`], root) });
+    }
+    return { primary: checkouts[0].path, checkouts, branches, targets };
+}
+async function classify(snap, branch, mainCwd, ownership, panes, run, root) {
+    const tip = snap.branches.get(branch);
+    const name = basename(branch);
+    const ownedPath = join(snap.primary, WORKTREES_DIRNAME, name);
+    // A detached or switched owned checkout no longer names the branch; find it by its owned path too.
+    const checkout = snap.checkouts.find((item) => item.branch === branch) ?? snap.checkouts.find((item) => item.path === ownedPath);
+    const blockers = [];
+    const block = (kind, text) => blockers.push({ kind, text });
+    if (checkout && checkout.branch !== branch)
+        block("hard", `owned checkout is ${checkout.branch ? `on branch ${checkout.branch}` : "detached"}; inspect it manually`);
+    let ignored = [];
+    const owners = ownership.owners(name);
+    for (const { label } of owners)
+        block("owner", label);
+    if (ownership.lease)
+        block("lease", ownership.lease);
+    let merged;
+    for (const target of snap.targets) {
+        const result = await run(["merge-base", "--is-ancestor", tip, target.head], root);
+        if (result.code === 0) {
+            merged = target.label;
+            break;
+        }
+        if (result.code !== 1)
+            throw new Error(`git merge-base failed (exit ${result.code}): ${result.stderr.trim().slice(0, 200)}`);
+    }
+    if (!merged)
+        block("unmerged", `branch has commits not in ${snap.targets.map(({ label }) => label).join(" or ")}`);
+    if (checkout) {
+        const path = checkout.path;
+        if (path !== ownedPath)
+            block("hard", "checkout is not at its owned .worktrees path");
+        if (checkout.locked)
+            block("hard", "checkout is locked");
+        if (checkout.missing || !existsSync(path))
+            block("hard", "checkout directory is missing; inspect it, then run git worktree prune");
+        else {
+            const real = realpathSync.native(path);
+            if (within(real, realpathSync.native(mainCwd)))
+                block("hard", "Main runs inside the checkout");
+            const gitDir = await requireGit(run, ["rev-parse", "--absolute-git-dir"], path);
+            const markers = IN_PROGRESS_MARKERS.filter((marker) => existsSync(join(gitDir, marker)));
+            if (markers.length)
+                block("operation", `Git operation in progress (${markers.join(", ")})`);
+            const dirty = await inspectWorktreeDirty(path, run, false);
+            if (dirty.failure)
+                block("hard", `checkout could not be inspected: ${dirty.failure}`);
+            else if (dirty.dirty)
+                block("changes", "checkout has tracked or untracked changes");
+            else if (dirty.initializedSubmodules)
+                block("submodules", "checkout has initialized submodules; Git cannot remove it without force");
+            if (typeof panes === "string")
+                block("hard", `Herdr unavailable (${panes}); cannot prove no pane uses the checkout`);
+            else {
+                const used = panes.filter((pane) => pane.cwds.some((cwd) => within(path, cwd) || within(real, cwd)));
+                if (used.length)
+                    block("hard", `Herdr pane ${used.map(({ paneId }) => paneId).join(", ")} works inside the checkout`);
+            }
+            ignored = (await requireGit(run, ["status", "--porcelain=v1", "-z", "--ignored=matching", "--untracked-files=normal"], path))
+                .split("\0").filter((entry) => entry.startsWith("!! ")).map((entry) => entry.slice(3));
+        }
+    }
+    // The owning request's discard review owns its other blockers; a lease or any second owner keeps the item.
+    const owner = owners.length === 1 ? owners[0].request : undefined;
+    const override = !blockers.length ? undefined : owner && !blockers.some(({ kind }) => kind === "lease") ? "discard"
+        : blockers.every(({ kind }) => forceable(kind)) ? "force" : undefined;
+    return {
+        branch, tip, ...(checkout ? { path: checkout.path } : {}), prunable: !blockers.length, ignored, blockers,
+        ...(owner ? { owner } : {}), ...(override ? { override } : {}),
+        reason: blockers.length ? blockers.map(({ text }) => text).join("; ") : `merged into ${merged}; ${checkout ? "clean checkout" : "no checkout"}`,
+    };
+}
+const existing = (snap) => snap.checkouts.filter((item) => !item.missing && existsSync(item.path)).map(({ path }) => path);
+async function evidence(root, mainCwd, guards, run) {
+    const snap = await snapshot(root, mainCwd, run);
+    const ownership = await guards.ownership(existing(snap));
+    let panes;
+    try {
+        panes = await guards.panes();
+    }
+    catch (error) {
+        panes = (error instanceof Error ? error.message : String(error)).slice(0, 200);
+    }
+    return { snap, ownership, panes };
+}
+/** Read-only review of every pi-subagent worker or integration branch and its checkout. */
+export async function inspectPruneCandidates(root, mainCwd, guards, run = runGit) {
+    const { snap, ownership, panes } = await evidence(root, mainCwd, guards, run);
+    const items = [];
+    for (const branch of [...snap.branches.keys()].sort())
+        items.push(await classify(snap, branch, mainCwd, ownership, panes, run, root));
+    return items;
+}
+async function removeOne(root, mainCwd, reviewed, allowIgnored, force, guards, run) {
+    const skip = (reason) => ({ outcome: "skipped", item: reviewed, reason });
+    const fail = (reason) => ({ outcome: "failed", item: reviewed, reason });
+    const { snap, ownership, panes } = await evidence(root, mainCwd, guards, run);
+    if (snap.branches.get(reviewed.branch) !== reviewed.tip)
+        return skip("branch was deleted or moved since review");
+    const fresh = await classify(snap, reviewed.branch, mainCwd, ownership, panes, run, root);
+    // Force applies only to an item reviewed as forceable, and only while no blocker of a new or hard kind appears.
+    const forced = force && reviewed.override === "force";
+    if (forced ? !fresh.blockers.every(({ kind }) => forceable(kind) && reviewed.blockers.some((item) => item.kind === kind))
+        : !fresh.prunable)
+        return skip(fresh.reason);
+    if (fresh.path !== reviewed.path)
+        return skip("checkout registration changed since review");
+    if (fresh.ignored.some((entry) => !allowIgnored || !reviewed.ignored.includes(entry)))
+        return skip("ignored content was not approved or changed since review");
+    const stale = () => guards.current !== undefined && !guards.current();
+    if (fresh.path) {
+        if (stale())
+            return skip("session or branch changed before removal; reopen /subagent prune");
+        // Git removes ignored content without --force; the checks above approved it. Force also deletes reviewed changes.
+        const removed = await run(["worktree", "remove", ...(forced ? ["--force"] : []), fresh.path], root);
+        if (removed.code !== 0)
+            return fail(`git worktree remove failed: ${removed.stderr.trim().slice(0, 200)}`);
+        if (existsSync(fresh.path))
+            return fail("git worktree remove succeeded but the checkout remains");
+    }
+    if (stale())
+        return skip(`${fresh.path ? "checkout removed; " : ""}session or branch changed before branch deletion; branch kept`);
+    const deleted = await run(["update-ref", "-d", `refs/heads/${reviewed.branch}`, reviewed.tip], root);
+    if (deleted.code !== 0)
+        return fail(`${fresh.path ? "checkout removed; " : ""}branch kept: ${deleted.stderr.trim().slice(0, 200)}`);
+    return { outcome: "removed", item: reviewed, reason: fresh.reason };
+}
+/**
+ * Re-verify each reviewed prunable item immediately before removing its checkout, then delete its
+ * branch only at the reviewed tip. Ignored entries are deleted only when `allowIgnored` and all of
+ * them were in the review. With `force`, a reviewed forceable item is removed with `--force` while
+ * every fresh blocker is forceable and of a reviewed kind. Returns the repository checkouts that still exist.
+ */
+export async function removePruneCandidates(root, mainCwd, reviewed, allowIgnored, force, guards, run = runGit) {
+    const removals = [];
+    for (const item of reviewed) {
+        try {
+            removals.push(await removeOne(root, mainCwd, item, allowIgnored, force, guards, run));
+        }
+        catch (error) {
+            removals.push({ outcome: "failed", item, reason: (error instanceof Error ? error.message : String(error)).slice(0, 300) });
+        }
+    }
+    return { removals, checkouts: existing(await snapshot(root, mainCwd, run)) };
+}

package/dist/review-evidence.d.ts

@@ -0,0 +1,17 @@
+export declare const REVIEW_MAX_PATHS = 1000;
+export declare const REVIEW_MAX_PATCH_BYTES: number;
+export interface PrepareExactReviewEvidenceInput {
+    base: string;
+    tip: string;
+    worktree: string;
+}
+export interface PreparedReviewEvidence {
+    base: string;
+    tip: string;
+    worktree: string;
+    changedPaths: string[];
+    patchPath: string;
+    cleanup: () => Promise<void>;
+}
+/** Prepare one exact private patch for caller-owned review. */
+export declare function prepareExactReviewEvidence(request: PrepareExactReviewEvidenceInput, signal?: AbortSignal): Promise<PreparedReviewEvidence>;

package/dist/review-evidence.js

@@ -0,0 +1,221 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { inspectIndexFlags } from "./worktree.js";
+import { runGit as runCapturedGit } from "./git-process.js";
+const GIT_TIMEOUT_MS = 30_000;
+export const REVIEW_MAX_PATHS = 1_000;
+export const REVIEW_MAX_PATCH_BYTES = 512 * 1024;
+const STDERR_LIMIT = 200;
+function failure(args, result) {
+    const detail = result.stderr.slice(0, STDERR_LIMIT).trim();
+    return new Error(`git ${args.join(" ")} failed with exit ${result.code}${detail ? `: ${detail}` : ""}`);
+}
+async function runGit(args, cwd, signal) {
+    signal?.throwIfAborted();
+    const result = await runCapturedGit(args, cwd, signal);
+    signal?.throwIfAborted();
+    if (result.code !== 0)
+        throw failure(args, result);
+    return result.stdout;
+}
+function line(value, field) {
+    const result = value.replace(/\r?\n$/, "");
+    if (!result || /[\r\n\0]/.test(result))
+        throw new Error(`Git returned malformed ${field}.`);
+    return result;
+}
+function oid(value, field) {
+    const result = line(value, field);
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(result))
+        throw new Error(`Git returned invalid ${field}.`);
+    return result;
+}
+function requestText(value, field) {
+    if (typeof value !== "string" || !value || value.includes("\0"))
+        throw new TypeError(`${field} must be non-empty text without NUL bytes.`);
+    return value;
+}
+async function resolveCommit(reference, cwd, signal) {
+    requestText(reference, "review ref");
+    return oid(await runGit(["rev-parse", "--verify", "--end-of-options", `${reference}^{commit}`], cwd, signal), `commit for ${reference}`);
+}
+function validatePath(path) {
+    if (!path || path.includes("\0") || path.includes("�") || isAbsolute(path) || path.split(/[\\/]/).some((part) => !part || part === "." || part === "..")) {
+        throw new Error(`Git returned malformed or unsupported path: ${JSON.stringify(path)}`);
+    }
+    return path;
+}
+function parsePaths(value) {
+    if (!value)
+        return [];
+    if (!value.endsWith("\0") || value.includes("�"))
+        throw new Error("Git returned malformed changed paths.");
+    const paths = value.slice(0, -1).split("\0");
+    if (paths.length > REVIEW_MAX_PATHS)
+        throw new Error(`Review evidence exceeds ${REVIEW_MAX_PATHS} paths; split the review.`);
+    return paths.map(validatePath);
+}
+function assertSupportedChanges(value) {
+    if (!value)
+        return;
+    if (!value.endsWith("\0") || value.includes("�"))
+        throw new Error("Git returned malformed raw diff.");
+    const fields = value.slice(0, -1).split("\0");
+    for (let index = 0; index < fields.length;) {
+        const header = fields[index++];
+        const match = /^:(\d{6}) (\d{6}) [0-9a-f]+ [0-9a-f]+ ([A-Z][0-9]*)$/.exec(header);
+        if (!match)
+            throw new Error("Git returned malformed raw diff.");
+        for (const mode of [match[1], match[2]]) {
+            if (mode === "160000")
+                throw new Error("Review evidence rejects changed gitlinks.");
+            if (!new Set(["000000", "100644", "100755", "120000"]).has(mode)) {
+                throw new Error(`Review evidence rejects unsupported file mode: ${mode}.`);
+            }
+        }
+        const paths = /^[RC]/.test(match[3]) ? 2 : 1;
+        for (let count = 0; count < paths; count++) {
+            if (fields[index] === undefined)
+                throw new Error("Git returned malformed raw diff paths.");
+            validatePath(fields[index++]);
+        }
+    }
+}
+function registeredWorktrees(value) {
+    if (!value.endsWith("\0") || value.includes("�"))
+        throw new Error("Git returned malformed worktree list.");
+    const result = [];
+    let record = {};
+    for (const field of [...value.slice(0, -1).split("\0"), ""]) {
+        if (!field) {
+            if (Object.keys(record).length)
+                result.push(record);
+            record = {};
+        }
+        else if (field.startsWith("worktree "))
+            record.path = field.slice("worktree ".length);
+        else if (field.startsWith("HEAD "))
+            record.head = oid(`${field.slice("HEAD ".length)}\n`, "worktree HEAD");
+    }
+    return result;
+}
+async function assertCleanRegisteredWorktree(worktree, tip, signal) {
+    const root = await fs.realpath(line(await runGit(["rev-parse", "--show-toplevel"], worktree, signal), "worktree root"));
+    if (root !== worktree)
+        throw new Error("Review evidence requires a registered worktree root.");
+    const registrations = registeredWorktrees(await runGit(["worktree", "list", "--porcelain", "-z"], worktree, signal));
+    const registered = await Promise.all(registrations
+        .filter((entry) => entry.path === worktree)
+        .map(async (entry) => ({ ...entry, path: await fs.realpath(entry.path) })));
+    if (!registered.some((entry) => entry.head === tip)) {
+        throw new Error("Review evidence worktree is not registered at the requested tip.");
+    }
+    if (oid(await runGit(["rev-parse", "HEAD"], worktree, signal), "worktree HEAD") !== tip) {
+        throw new Error("Review evidence worktree moved from the requested tip.");
+    }
+    if (await runGit(["status", "--porcelain=v1", "--untracked-files=all", "--ignore-submodules=none"], worktree, signal)) {
+        throw new Error("Review evidence worktree is not clean.");
+    }
+    const flags = await inspectIndexFlags(worktree, runCapturedGit, signal);
+    if (flags.failure)
+        throw new Error(`Review evidence index inspection failed: ${flags.failure}`);
+    if (flags.hidden)
+        throw new Error("Review evidence rejects assume-unchanged or skip-worktree index entries.");
+}
+async function streamPatch(base, tip, worktree, path, signal) {
+    const file = await fs.open(path, "wx", 0o600);
+    try {
+        await fs.chmod(path, 0o600);
+        signal?.throwIfAborted();
+        const args = ["--no-pager", "diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--binary", base, tip];
+        const child = spawn("git", args, { cwd: worktree, signal, timeout: GIT_TIMEOUT_MS, stdio: ["ignore", "pipe", "pipe"] });
+        let stderr = Buffer.alloc(0);
+        let childError;
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < STDERR_LIMIT)
+                stderr = Buffer.concat([stderr, chunk.subarray(0, STDERR_LIMIT - stderr.length)]);
+        });
+        child.once("error", (error) => { childError = error; });
+        const closed = new Promise((resolve) => child.once("close", resolve));
+        let bytes = 0;
+        let overflow = false;
+        let outputError;
+        try {
+            for await (const chunk of child.stdout) {
+                const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                const available = REVIEW_MAX_PATCH_BYTES - bytes;
+                if (data.length > available) {
+                    if (available > 0)
+                        await file.writeFile(data.subarray(0, available));
+                    bytes += Math.max(available, 0);
+                    overflow = true;
+                    child.kill();
+                    break;
+                }
+                await file.writeFile(data);
+                bytes += data.length;
+            }
+        }
+        catch (error) {
+            outputError = error;
+            child.kill();
+        }
+        const code = await closed;
+        signal?.throwIfAborted();
+        if (overflow)
+            throw new Error(`Review evidence exceeds ${REVIEW_MAX_PATCH_BYTES} bytes; split the review.`);
+        if (outputError)
+            throw outputError;
+        if (childError)
+            throw childError;
+        if (code !== 0)
+            throw failure(args, { code: code ?? -1, stdout: "", stderr: stderr.toString() });
+    }
+    finally {
+        await file.close();
+    }
+}
+async function makeEvidenceDirectory() {
+    const directory = await fs.mkdtemp(join(tmpdir(), "pi-subagent-review-"));
+    try {
+        await fs.chmod(directory, 0o700);
+    }
+    catch (error) {
+        await fs.rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+    let cleanup;
+    return {
+        directory,
+        cleanup: () => cleanup ??= fs.rm(directory, { recursive: true, force: true }),
+    };
+}
+/** Prepare one exact private patch for caller-owned review. */
+export async function prepareExactReviewEvidence(request, signal) {
+    const requestedWorktree = requestText(request.worktree, "review worktree");
+    const worktree = await fs.realpath(requestedWorktree);
+    const [base, tip] = await Promise.all([
+        resolveCommit(request.base, worktree, signal),
+        resolveCommit(request.tip, worktree, signal),
+    ]);
+    await assertCleanRegisteredWorktree(worktree, tip, signal);
+    const changedPaths = parsePaths(await runGit([
+        "diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--name-only", "-z", base, tip,
+    ], worktree, signal));
+    assertSupportedChanges(await runGit([
+        "diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--raw", "-z", base, tip,
+    ], worktree, signal));
+    const owned = await makeEvidenceDirectory();
+    const patchPath = join(owned.directory, "review.patch");
+    try {
+        await streamPatch(base, tip, worktree, patchPath, signal);
+        await assertCleanRegisteredWorktree(worktree, tip, signal);
+        return { base, tip, worktree, changedPaths, patchPath, cleanup: owned.cleanup };
+    }
+    catch (error) {
+        await owned.cleanup();
+        throw error;
+    }
+}