looply-cli 0.0.0-stage → 0.3.0

package/dist/git-driver.js

@@ -0,0 +1,900 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitDriver = exports.STATE_DIR = exports.GitError = void 0;
+exports.executionStateDir = executionStateDir;
+exports.projectStateDir = projectStateDir;
+exports.nodeGitExec = nodeGitExec;
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const trusted_git_1 = require("./trusted-git");
+const node_child_process_1 = require("node:child_process");
+const core_1 = require("@looply/core");
+class GitError extends Error {
+}
+exports.GitError = GitError;
+/** The runner's own files; git must never stage them and never clean them. */
+exports.STATE_DIR = '.looply';
+/**
+ * THE EXECUTION'S OWN STATE — one directory per checkout, one writer.
+ *
+ * Everything whose correctness rests on there being a single writer lives here:
+ * the run lease, `queue.json`'s whole-file rewrite, `status.json`'s single-run
+ * shape, `events.jsonl`'s in-memory `seq` counter. Those are correct BECAUSE
+ * one run owns one checkout, and they stay correct when a second run happens in
+ * a different one.
+ */
+function executionStateDir(cwd) {
+    return (0, node_path_1.join)(cwd, exports.STATE_DIR, 'state');
+}
+/**
+ * THE PROJECT'S STATE — one directory per repository, however many worktrees.
+ *
+ * 🔴 A LINKED WORKTREE IS THE SAME PROJECT, and the state whose invariant says
+ * "per project" must not follow the checkout. Otherwise isolating executions
+ * silently un-does safety rather than adding it:
+ *
+ *   loop-safety history      keyed by the state directory and the pursuit it
+ *                            watches, and the path half exists only as where the
+ *                            file sits — so a second worktree is a FRESH
+ *                            history. Both detectors
+ *                            need three observations and each run contributes
+ *                            one, so with a worktree per run they can never
+ *                            fire at all.
+ *   exemption spend ledger   single-use holds only because there is one
+ *                            `exemptions.json` per checkout. N checkouts make
+ *                            one granted row spendable N times — a rails bypass,
+ *                            not a bookkeeping detail.
+ *   control.json             the ONE channel the daemon, the run and the
+ *                            controller share about whether a person said stop.
+ *                            Split it and the stop button reaches one run.
+ *   goals                    the daemon is the sole writer; a run reads.
+ *
+ * ⚠️ IDENTICAL TO `executionStateDir` IN THE ORDINARY CASE. In a normal checkout
+ * the main worktree IS the cwd, so both answer the same path and Simple Mode is
+ * byte-identical. They diverge only inside a linked worktree.
+ *
+ * ⚠️ FALLS BACK TO THE EXECUTION DIR when there is no repository or its metadata
+ * cannot be read — the pre-worktree behaviour, unchanged. `repoConfigTroubleAt`
+ * is the check that refuses on unreadable metadata; this is not that check.
+ *
+ * 🔴 AND THAT FALLBACK USED TO SWALLOW A CASE IT SHOULD NOT HAVE. A repository
+ * can have several worktrees and no main one — `clone --bare` plus two
+ * `worktree add`s — and there `mainWorktreeRoot` is null while the sharing is
+ * still required. The old code read null as "nothing to share" and put the
+ * project's state inside each checkout: a fresh loop-safety history per
+ * checkout, and one single-use exemption spendable once per checkout, with
+ * nothing said about it.
+ *
+ * For those, the shared state goes under `~/.looply/projects/<key>`, keyed by
+ * the common dir — the one identity every worktree of that repository agrees
+ * on. `~/.looply` is where this codebase already puts state that must survive
+ * the repository, and a bare repository has no tree to put it in anyway.
+ *
+ * ⚠️ AN ORDINARY CHECKOUT IS UNAFFECTED, and that is load-bearing for
+ * compatibility: `linkedRepoCommonDir` answers null unless the checkout is
+ * LINKED, so a single-worktree repository — bare or not — keeps the exact path
+ * it has always used and no existing state is orphaned.
+ */
+function projectStateDir(cwd) {
+    /**
+     * ⚠️ A SUBDIRECTORY ANSWERS ITS REPOSITORY'S STATE, and a narrowing that made
+     * it answer its own was reverted — see `repoIdentityPath` for the measurement.
+     *
+     * In short: `looply stop` and `looply runs` are the only commands a person
+     * types from inside a tree, they are not guarded by the repository-root check,
+     * and a subdirectory that answers `<subdir>/.looply/state` makes the brake
+     * write a file no run will ever read while reporting "no run is going".
+     */
+    const root = (0, trusted_git_1.mainWorktreeRoot)(cwd);
+    if (root !== null)
+        return (0, node_path_1.join)(root, exports.STATE_DIR, 'state');
+    const shared = (0, trusted_git_1.linkedRepoCommonDir)(cwd);
+    if (shared !== null) {
+        const key = (0, node_crypto_1.createHash)('sha256').update(shared.toLowerCase(), 'utf8').digest('hex').slice(0, 16);
+        return (0, node_path_1.join)((0, node_os_1.homedir)(), '.looply', 'projects', key, 'state');
+    }
+    return executionStateDir(cwd);
+}
+function isStatePath(path) {
+    return path === exports.STATE_DIR || path.startsWith(`${exports.STATE_DIR}/`);
+}
+/**
+ * The loop's own writes: the ledger, the queue, the projection, the control
+ * file. These churn constantly while a run is going and are nobody's edit.
+ *
+ * Deliberately narrower than {@link isStatePath}. Everything else under
+ * `.looply/` — above all `config.yaml`, which is tracked and holds the rails —
+ * is a real change that the interlock and the dirty-tree check must both see.
+ */
+const RUNTIME_STATE = `${exports.STATE_DIR}/state`;
+function isRuntimeState(path) {
+    return path === RUNTIME_STATE || path.startsWith(`${RUNTIME_STATE}/`);
+}
+class GitDriver {
+    exec;
+    constructor(exec) {
+        this.exec = exec;
+    }
+    async run(args) {
+        const r = await this.exec(args);
+        if (r.code !== 0) {
+            throw new GitError(`git ${args.join(' ')} exited ${r.code}: ${r.stderr.trim()}`);
+        }
+        return r.stdout;
+    }
+    /**
+     * The pathspec that keeps `.looply` out of a stage — WHEN NAMING IT IS LEGAL.
+     *
+     * 🔴 `:(exclude).looply` IS A REFUSAL WHEN `.looply` IS ALREADY IGNORED, and
+     * that broke evidence gathering on every round of any project that gitignores
+     * it. Git rejects a pathspec that EXPLICITLY names an ignored path, and an
+     * exclusion names it:
+     *
+     *     .looply not in .gitignore   git add -N -- . :(exclude).looply   exit 0
+     *     .looply in .gitignore       same command                        exit 1
+     *       "The following paths are ignored by one of your .gitignore files"
+     *
+     * `advice.addIgnoredFile=false` only hides the hint; the exit code stays 1.
+     *
+     * ⚠️ AND IT IS A CATCH-22 WITHOUT THIS. Leave `.looply/` untracked and the run
+     * refuses to start on a dirty tree; gitignore it — the obvious fix, and the
+     * one a person reaches for — and every round's evidence fails instead.
+     * Measured live: a round whose gate was green and whose proof said `proven`
+     * recorded `evidence could not be gathered`.
+     *
+     * When the path is already ignored the exclusion is not merely illegal, it is
+     * REDUNDANT: git skips ignored paths under a `.` pathspec anyway. So the
+     * answer is to ask, and to drop it exactly when git is already doing the job.
+     *
+     * ⚠️ ASKED EVERY TIME, NOT MEMOISED. A round may edit `.gitignore`, and the
+     * direction that goes wrong is the one a cache would get wrong: believing
+     * `.looply` is ignored when it is no longer ignored stages the state
+     * directory into somebody's commit. One `check-ignore` is a few milliseconds.
+     *
+     * `check-ignore` only reads `.gitignore` and prints; it is in the same
+     * READ-ONLY family as `status` and `rev-parse`, and none of the forbidden
+     * verbs.
+     */
+    async keepStateOut() {
+        // exit 0 = ignored (git already excludes it, and naming it would refuse)
+        // exit 1 = not ignored, including absent (the exclusion is needed)
+        const asked = await this.exec(['check-ignore', '-q', '--', exports.STATE_DIR]);
+        return asked.code === 0 ? [] : [`:(exclude)${exports.STATE_DIR}`];
+    }
+    /** Create and switch to `name`. An existing branch of that name is a refusal. */
+    async createBranch(name, from) {
+        const probe = await this.exec(['rev-parse', '--verify', '--quiet', `refs/heads/${name}`]);
+        if (probe.code === 0) {
+            // Reusing a branch would land this round's commits on top of whatever a
+            // previous (possibly aborted) run left there (DESIGN §12 case 2).
+            throw new GitError(`branch already exists: ${name} — refusing to reuse it`);
+        }
+        /**
+         * ⚠️ `from` IS PHASE 5's ANSWER TO STACKING, AND ABSENT KEEPS THE OLD SHAPE.
+         *
+         * Run N+1 used to be cut from wherever HEAD was — which, after run N, is run
+         * N's branch. One ever-deepening chain with no shared base. With integration
+         * on, the caller names the integration head instead. With it off nothing is
+         * passed and this is byte-identical to what it has always done, which is the
+         * whole compatibility guarantee of the phase.
+         */
+        await this.run(from === undefined ? ['switch', '-c', name] : ['switch', '-c', name, from]);
+    }
+    /** The sha of HEAD — recorded as the run's base before any round writes. */
+    async headSha() {
+        return (await this.run(['rev-parse', 'HEAD'])).trim();
+    }
+    /**
+     * THE FIRST CONVERGENCE VERBS THIS DRIVER HAS EVER ISSUED.
+     *
+     * Until Phase 5 the complete list was add, cat-file, clean, commit, ls-tree,
+     * push, reset, rev-list, rev-parse, status, switch, worktree — no fetch, no
+     * merge, no rebase, no cherry-pick, no revert, no stash, no checkout, no tag,
+     * no remote, no branch -d, no notes, no gc, no bisect, no submodule. That was
+     * not an oversight; it was the whole safety argument, and it is why the three
+     * added here are the three that only ever READ or FAST-FORWARD.
+     *
+     * ⚠️ THERE IS STILL NO `merge`, NO `rebase` AND NO `cherry-pick`. Integration
+     * is a fast-forward or it is a refusal. A merge that had to combine two
+     * histories is the thing that can silently drop somebody's line, and
+     * "auto-resolving a merge conflict" is listed under **Never**.
+     */
+    async mergeBase(a, b) {
+        try {
+            return (await this.run(['merge-base', a, b])).trim() || null;
+        }
+        catch {
+            // No common ancestor is a real answer, not an error: two histories that
+            // share nothing cannot be reconciled by any verb this driver may issue.
+            return null;
+        }
+    }
+    /**
+     * How far apart two refs are, counted rather than assumed.
+     *
+     * `--left-right --count` answers both directions in one call, so the two
+     * numbers are read at the SAME moment — asking twice would let a ref move in
+     * between and produce a pair that never simultaneously held.
+     */
+    async divergence(mine, theirs) {
+        const out = (await this.run(['rev-list', '--left-right', '--count', `${theirs}...${mine}`])).trim();
+        const [behind, ahead] = out.split(/\s+/).map((n) => Number.parseInt(n, 10));
+        /**
+         * 🔴 UNPARSEABLE OUTPUT IS NOT ZERO DIVERGENCE.
+         *
+         * `Number.isInteger(x) ? x : 0` reads as a tidy default and is a fail-open:
+         * the consumer is `baseFreshness`, and `{ahead: 0, behind: 0}` is its word
+         * for "the base is current". So a git that answered anything this could not
+         * parse — a warning line, a locale-translated message, an empty string from
+         * a broken invocation — told the run its ground had not moved.
+         *
+         * There is no number here that can mean "I could not tell", so this throws
+         * and lets the caller decide. `baseFreshness` refuses on it, which is the
+         * direction a staleness check has to fail in.
+         */
+        if (!Number.isInteger(ahead) || !Number.isInteger(behind)) {
+            throw new Error(`git could not say how ${mine} and ${theirs} diverge — rev-list answered ${JSON.stringify(out)}`);
+        }
+        return { ahead: ahead, behind: behind };
+    }
+    /**
+     * CREATE OR ADVANCE ONE OF LOOPLY'S OWN REFS — AND ONLY BY COMPARE-AND-SWAP.
+     *
+     * 🔴 THE FOURTH CONVERGENCE VERB, AND THE ONLY ONE THAT WRITES. Phase 5's
+     * integration queue has to move `looply/integration` forward, and until now
+     * this driver could not move a ref at all. What it must NOT become is a
+     * general `update-ref`: that is one typo away from moving `main`.
+     *
+     * Three narrowings, all of them enforced here rather than by convention:
+     *
+     *   1. THE NAME MUST BE LOOPLY'S. Anything not under `refs/heads/looply/` is
+     *      refused before git is asked. A person's branch is theirs, and `main`
+     *      is nobody's to move from here.
+     *   2. IT IS A COMPARE-AND-SWAP, ALWAYS. `git update-ref <ref> <new> <old>`
+     *      fails if the ref is not still `old`, so a base that moved between
+     *      validation and publication cannot be overwritten — git itself refuses,
+     *      atomically, without this code having to re-read and hope. Creating a
+     *      ref passes the all-zero oid as `old`, which is git's own way of saying
+     *      "and it must not exist yet".
+     *   3. FAST-FORWARD ONLY. The caller must have established that `newSha` has
+     *      `oldSha` as an ancestor; there is still no `merge`, `rebase` or
+     *      `cherry-pick` in this file, so nothing here can combine two histories.
+     *
+     * ⚠️ GIT'S REFERENCE API, NOT A FILE WRITE. Writing `.git/refs/...` by hand
+     * would miss packed refs, the reflog and the lock — and would be a second,
+     * worse implementation of the compare-and-swap that is the whole point.
+     *
+     * Answers `false` when the swap was refused (the ref moved, or already
+     * existed); throws only when git could not be asked at all.
+     */
+    async compareAndSetRef(ref, newSha, oldSha) {
+        if (!/^looply\/[A-Za-z0-9._\-\/]+$/.test(ref)) {
+            throw new GitError(`refusing to move ${ref}: this driver may only create or advance looply's own refs`);
+        }
+        if (!/^[0-9a-f]{7,40}$/.test(newSha)) {
+            throw new GitError(`refusing to move ${ref}: ${newSha} is not a commit id`);
+        }
+        if (oldSha !== null && !/^[0-9a-f]{7,40}$/.test(oldSha)) {
+            throw new GitError(`refusing to move ${ref}: ${oldSha} is not a commit id`);
+        }
+        // The all-zero oid is git's own "it must not exist yet".
+        const expected = oldSha ?? '0000000000000000000000000000000000000000';
+        const out = await this.exec(['update-ref', `refs/heads/${ref}`, newSha, expected]);
+        return out.code === 0;
+    }
+    /** Local branches under a prefix, with their tips — the finished runs the lane may be offered (M5-1). */
+    async listBranches(prefix) {
+        const out = await this.run(['for-each-ref', '--format=%(refname:short) %(objectname)', `refs/heads/${prefix}*`]);
+        const found = [];
+        for (const line of out.split(/\r?\n/)) {
+            const [name, sha] = line.trim().split(' ');
+            if (name !== undefined && sha !== undefined && name.startsWith(prefix) && /^[0-9a-f]{40}$/.test(sha))
+                found.push({ name, sha });
+        }
+        return found;
+    }
+    /** Whether a ref exists at all. Integration may not have been cut yet. */
+    async refExists(ref) {
+        try {
+            await this.run(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * WHAT THE REPOSITORY CONTAINS, as distinct from which commit produced it.
+     *
+     * ─────────────────────────────────────────────────────────────────────────
+     * A COMMIT SHA IS THE WRONG IDENTITY FOR "IS THIS THE SAME STATE AGAIN"
+     *
+     * A commit id covers the parent, the author, the message and the timestamp,
+     * so it differs on every commit even when the content is byte-identical.
+     * Loop safety needs to notice a pursuit moving A → B → A → B, and with commit
+     * ids that reads as four distinct states and no cycle is ever detectable.
+     *
+     * A tree id is the content. The same files reached twice by two different
+     * commits are ONE state, which is exactly the equality the detector needs.
+     *
+     * ⚠️ IT DESCRIBES THE COMMITTED TREE, NOT THE WORKING ONE. Uncommitted edits
+     * do not move it — the same limit `headSha` has. That is the honest reading
+     * for a Round that commits its work; a caller comparing dirty trees would
+     * need something else, and inventing one here would mean writing to the index
+     * (see `diff()`, which is not read-only despite its name).
+     *
+     * READ-ONLY. `rev-parse` resolves; it changes nothing.
+     */
+    async headTreeSha() {
+        return (await this.run(['rev-parse', 'HEAD^{tree}'])).trim();
+    }
+    /**
+     * The tree a ref or commit points at — `headTreeSha` for any ref (F25: the lane
+     * judges coverage on the integration tip's tree). READ-ONLY, the same `rev-parse`.
+     */
+    async treeOf(ref) {
+        return (await this.run(['rev-parse', `${ref}^{tree}`])).trim();
+    }
+    /**
+     * Whether `ancestor` is in `of`'s history (a commit is its own ancestor) — F31. READ-ONLY:
+     * `merge-base --is-ancestor` answers by exit code, 0 yes and 1 no; anything else is a fault.
+     */
+    async isAncestor(ancestor, of) {
+        const r = await this.exec(['merge-base', '--is-ancestor', ancestor, of]);
+        if (r.code === 0)
+            return true;
+        if (r.code === 1)
+            return false;
+        throw new GitError(`merge-base --is-ancestor ${ancestor} ${of} failed: ${r.stderr.trim()}`);
+    }
+    /** The commit a ref points at (F27). READ-ONLY, the same `rev-parse`. */
+    async commitOf(ref) {
+        return (await this.run(['rev-parse', '--verify', `${ref}^{commit}`])).trim();
+    }
+    /**
+     * Put HEAD on `sha`, detached — the tree a goal-met Start must judge (F27).
+     *
+     * ⚠️ `switch`, the verb this driver already uses, and never forced: `switch --detach`
+     * refuses when local changes would be lost, and the caller has already found the tree clean.
+     */
+    async switchDetached(sha) {
+        // F33: `--no-overwrite-ignore` — git overwrites IGNORED files by default, and the caller's
+        // clean-tree check cannot see them.
+        await this.run(['switch', '--detach', '--no-overwrite-ignore', sha]);
+    }
+    /**
+     * The branch HEAD is on, or `(detached)` when it is not on one.
+     *
+     * Recorded in the run lease as the branch the run was cut from. Nothing
+     * returns to it — run branches stack — so knowing where a run started is the
+     * only way a later process can tell an ordinary stacked branch from a tree
+     * somebody has since moved somewhere else entirely.
+     */
+    /**
+     * Every tracked file at a revision, with its blob sha and size.
+     *
+     * 🔴 ENUMERATED FROM THE GIT INDEX, NEVER FROM THE FILESYSTEM, AND THAT ONE
+     * DECISION SETTLES FOUR SEPARATE PROBLEMS THE AUDIT FOUND.
+     *
+     *   ignore rules   git has already applied `.gitignore`. Nothing in this
+     *                  repository reads that file, and the one production skip
+     *                  list is three hardcoded basenames that would happily walk
+     *                  `dist/` and `coverage/` — build output that is by
+     *                  construction different on every machine.
+     *   symlink escape the existing physical-path defence is a NAMED-PATH
+     *                  defence: it says nothing about an enumeration, so a
+     *                  directory walk inherits none of it. The git index cannot
+     *                  contain an entry outside the repository, so the escape is
+     *                  impossible here rather than guarded against.
+     *   ordering       `ls-tree` output is deterministic, unlike `readdir`.
+     *   portability    paths are already project-relative.
+     *
+     * `-r` recurses into subtrees; `-z` because a path may contain anything a
+     * newline could, and `-l` adds the size git already knows so nothing has to
+     * stat the working tree.
+     */
+    async listTree(treeIsh) {
+        const out = await this.run(['ls-tree', '-r', '-l', '-z', treeIsh]);
+        const entries = [];
+        for (const record of out.split('\0')) {
+            if (record === '')
+                continue;
+            // `<mode> SP <type> SP <sha> SP* <size> TAB <path>`
+            const tab = record.indexOf('\t');
+            if (tab < 0)
+                continue;
+            const meta = record.slice(0, tab).split(/\s+/);
+            const path = record.slice(tab + 1);
+            if (meta.length < 4)
+                continue;
+            const [, type, blobSha, size] = meta;
+            // Only blobs. A submodule is a `commit` entry and has no content here.
+            if (type !== 'blob' || blobSha === undefined || path === '')
+                continue;
+            const bytes = Number(size);
+            entries.push({ path, blobSha, bytes: Number.isFinite(bytes) ? bytes : 0 });
+        }
+        return entries;
+    }
+    /**
+     * The COMMITTED content of one blob.
+     *
+     * ⚠️ THE COMMITTED CONTENT, NOT THE WORKING TREE'S. An index describes a
+     * revision; reading the file from disk would describe whatever somebody has
+     * half-edited, and two machines would then disagree about a revision they
+     * both have.
+     */
+    async readBlob(blobSha) {
+        return this.run(['cat-file', 'blob', blobSha]);
+    }
+    async currentBranch() {
+        const r = await this.exec(['rev-parse', '--abbrev-ref', 'HEAD']);
+        if (r.code !== 0)
+            return '(unknown)';
+        const name = r.stdout.trim();
+        return name === 'HEAD' || name === '' ? '(detached)' : name;
+    }
+    /**
+     * Working-tree paths that differ from HEAD, with `.looply/**` filtered out —
+     * the runner's own state writes must never read as "the agent changed
+     * something", or the no-op branch becomes unreachable (DESIGN §2.4).
+     */
+    async changedPaths() {
+        return (await this.changedEntries()).map((e) => e.path);
+    }
+    /**
+     * Every changed path WITH what happened to it, as `git status` reports it.
+     *
+     * The manifest a rejected candidate is retained with. `changedPaths` is the
+     * same list with the status dropped, and the two share one parse so they
+     * cannot disagree about which paths a round touched. `status` is the
+     * two-character porcelain code (`??` new, ` M` modified, `R ` renamed…).
+     */
+    async changedEntries() {
+        // -z: NUL separators, no quoting — a path with a space or a non-ASCII byte
+        // arrives literal instead of C-escaped.
+        // -uall lists every untracked file. The default collapses a new directory
+        // to `newdir/`, so a railed file created inside one was invisible to the
+        // interlock — it never saw a path it could match against.
+        const out = await this.run(['status', '--porcelain=v1', '-z', '-uall']);
+        const tokens = out.split('\0').filter((t) => t.length > 0);
+        const entries = [];
+        for (let i = 0; i < tokens.length; i++) {
+            const entry = tokens[i];
+            if (entry === undefined || entry.length < 4)
+                continue;
+            const status = entry.slice(0, 2);
+            entries.push({ path: entry.slice(3), status });
+            if (entry.startsWith('R') || entry.startsWith('C')) {
+                // Rename/copy entries carry the source as the next token. Both ends
+                // changed as far as `when:` filters and rails are concerned.
+                i += 1;
+                const source = tokens[i];
+                if (source !== undefined)
+                    entries.push({ path: source, status });
+            }
+        }
+        // Only the loop's own runtime writes are filtered. This used to drop
+        // everything under `.looply/`, and that list is the interlock's only input
+        // — so a rail naming `.looply/` could never fire, and a round was free to
+        // edit the config that constrains it: weaken forbidden_paths, drop a
+        // `required: true`, commit its legitimate work alongside, and the next run
+        // re-reads the weakened file. Nothing recorded that it happened.
+        return entries.filter((e) => !isRuntimeState(e.path));
+    }
+    /**
+     * Commits in `fromSha..toSha` that touch any of `paths` — the input to the
+     * re-verification trigger (DESIGN §12 case 19). Zero paths short-circuits to
+     * 0 without calling git: `rev-list --count` with an empty pathspec counts
+     * *every* commit, which would read as "everything touched the evidence".
+     */
+    async countCommitsTouching(fromSha, toSha, paths) {
+        if (paths.length === 0)
+            return 0;
+        const out = await this.run(['rev-list', '--count', `${fromSha}..${toSha}`, '--', ...paths]);
+        const n = Number.parseInt(out.trim(), 10);
+        if (Number.isNaN(n)) {
+            throw new GitError(`rev-list --count returned non-numeric output: ${JSON.stringify(out.trim())}`);
+        }
+        return n;
+    }
+    /** `add -A`, with the state directory excluded by pathspec. */
+    /**
+     * The round's changes as a unified diff, for the prover.
+     *
+     * Staged and unstaged both, because the round is inspected before anything is
+     * committed. State and run logs are excluded by the same pathspec the commit
+     * uses — a prover reading its own run's ledger would be grading the story.
+     */
+    /**
+     * Create a linked worktree at `path`, on a NEW branch cut from `baseSha`.
+     *
+     * ⚠️ THROUGH THE SAME `exec` AS EVERY OTHER VERB, deliberately. A worktree
+     * provisioner with its own git runner would be a second "safe enough" path
+     * around the config check, the repository-root check, the rebuilt `GIT_`
+     * namespace and the absolute binary resolution — all four of which exist
+     * because the repository is untrusted input.
+     *
+     * ⚠️ A NEW BRANCH, NEVER AN EXISTING ONE. `-b` fails if the branch is already
+     * there, which is the same refusal `createBranch` makes and for the same
+     * reason: reusing a branch would stack this execution's commits on whatever a
+     * previous one left behind. Linked worktrees SHARE the ref namespace, so this
+     * is the check that makes two simultaneous executions safe to start.
+     */
+    async addWorktree(path, branch, baseSha) {
+        await this.run(['worktree', 'add', '-b', branch, path, baseSha]);
+    }
+    /**
+     * Every worktree of this repository: its path, its HEAD, its branch.
+     *
+     * `--porcelain` because the human-readable form is not parseable — a path may
+     * contain spaces, and the columns are aligned rather than delimited.
+     */
+    async listWorktrees() {
+        const out = await this.run(['worktree', 'list', '--porcelain']);
+        const found = [];
+        let cur = null;
+        for (const line of out.split(/\r?\n/)) {
+            if (line.startsWith('worktree ')) {
+                if (cur !== null)
+                    found.push(cur);
+                cur = { path: line.slice('worktree '.length), head: '', branch: null };
+                continue;
+            }
+            if (cur === null)
+                continue;
+            if (line.startsWith('HEAD '))
+                cur.head = line.slice('HEAD '.length);
+            else if (line.startsWith('branch '))
+                cur.branch = line.slice('branch '.length);
+        }
+        if (cur !== null)
+            found.push(cur);
+        return found;
+    }
+    /**
+     * Remove a linked worktree.
+     *
+     * 🔴 NEVER `--force`, AND THIS IS NOT A STYLE CHOICE. `git worktree remove
+     * --force` deletes IGNORED files — `node_modules`, `.env` — which `discard()`
+     * one method below deliberately preserves by omitting `-x` from `clean`. It
+     * also fires exactly when git has already refused the safe form, which is to
+     * say exactly when something is there that git thought worth refusing over.
+     *
+     * So git's own refusal IS the check. A caller that cannot remove a worktree
+     * should leave it and say so, not insist.
+     */
+    async removeWorktree(path) {
+        await this.run(['worktree', 'remove', path]);
+    }
+    /**
+     * Drop the administrative records of worktrees whose directories are gone.
+     *
+     * Touches no working tree — it only reconciles `.git/worktrees/*` with what is
+     * actually on disk, which is what makes a directory that a person deleted by
+     * hand stop counting against the ref namespace.
+     */
+    async pruneWorktrees() {
+        await this.run(['worktree', 'prune']);
+    }
+    /**
+     * Everything THIS checkout holds that a pristine one would not — INCLUDING
+     * ignored files.
+     *
+     * ⚠️ `--ignored` IS THE WHOLE POINT. Without it this asks exactly the question
+     * `git worktree remove` already answers by refusing, and learns nothing new.
+     * With it, it sees the `node_modules` and the `.env` that `remove` deletes
+     * silently.
+     *
+     * 🔴 AND IT ANSWERS ABOUT *THIS* DRIVER'S CHECKOUT — the first version took a
+     * `workspace` and passed `-C <workspace>`, which does nothing here.
+     * `trustedGitEnv` pins GIT_DIR and GIT_WORK_TREE from the cwd the driver was
+     * built with, and a pinned work tree beats `-C`. Measured: it reported the
+     * MAIN checkout's residue while claiming to describe a workspace — so a dirty
+     * main checkout would have blocked every reap, and a clean one would have
+     * waved through a workspace full of files. To ask about another checkout,
+     * build a driver for it.
+     */
+    async statusWithIgnored() {
+        /**
+         * ⚠️ `-uall` AND `--ignored=matching`, SO EVERY PATH IS NAMED INDIVIDUALLY.
+         *
+         * 🔴 Plain `--porcelain` COLLAPSES an entirely-untracked directory to one
+         * entry: `?? .looply/`, never `?? .looply/state/creating.json`. Any caller
+         * that wants to reason about WHICH files are there — to ignore looply's own
+         * state while still seeing a person's — cannot, because the person's file
+         * and looply's are hidden behind the same single line. Measured: the reaper's
+         * residue filter matched nothing at all because of it.
+         */
+        return this.run(['status', '--porcelain', '-uall', '--ignored=matching']);
+    }
+    async diff(maxBytes = 200_000) {
+        const p = await this.patch(maxBytes);
+        if (!p.truncated)
+            return p.text;
+        // Truncation is announced rather than silent: a prover judging a diff it
+        // only partly received must know that is what happened.
+        return `${p.text}\n\n[diff truncated at ${maxBytes} bytes]\n`;
+    }
+    /**
+     * The working tree's change against HEAD as one applicable patch — the
+     * artifact a rejected candidate is retained as, before `discard()` resets it.
+     *
+     * `diff()` is this with the prover's own truncation notice; the two share the
+     * implementation so the patch a repair restores and the diff a prover judged
+     * are the same text. `truncated` is a FLAG here rather than a notice in the
+     * text, because a truncated patch must never be applied: `git apply` would
+     * either refuse it or, worse, apply the part it could read.
+     */
+    async patch(maxBytes) {
+        // Intent-to-add first, so a file the round CREATED appears in the diff.
+        // `git diff HEAD` is tracked-only, and stageAll does not run until after
+        // the prover has answered — so an additive round handed the prover an
+        // empty string under the instruction "if a required behaviour is not
+        // visible in the diff, it does not count". It rejected work it was never
+        // shown, and since "add a spec"/"add a guard" is the commonest shape a
+        // scan produces, that was the default path for most overnight runs.
+        //
+        // -N records intent only: no content is staged, and both discard (which
+        // resets) and commit (which stages properly) are unaffected.
+        await this.run(['add', '-N', '--', '.', ...(await this.keepStateOut())]);
+        const out = await this.run([
+            'diff',
+            'HEAD',
+            '--',
+            '.',
+            `:!${exports.STATE_DIR}`,
+        ]);
+        if (out.length <= maxBytes)
+            return { text: out, bytes: out.length, truncated: false };
+        return { text: out.slice(0, maxBytes), bytes: out.length, truncated: true };
+    }
+    /**
+     * The change one commit range makes, as one applicable patch — the same
+     * artifact `patch()` produces for a working tree, asked about history
+     * instead.
+     *
+     * 🔴 THIS IS WHAT A REPLAY CARRIES, and it is deliberately a PATCH rather
+     * than a range of commits. Carrying commits would mean replaying their
+     * identities onto a new base, which is the rewrite `integration.spec.ts`
+     * forbids; carrying the change means a NEW commit that must earn its own
+     * proof. The distinction is the whole reason a replay is not a rebase.
+     *
+     * ⚠️ `truncated` is a flag, never a notice in the text: a truncated patch
+     * must never be applied, because `git apply` would either refuse it or,
+     * worse, apply the part it could read.
+     */
+    async patchBetween(fromSha, toSha, maxBytes) {
+        const out = await this.run(['diff', fromSha, toSha, '--', '.', `:!${exports.STATE_DIR}`]);
+        if (out.length <= maxBytes)
+            return { text: out, bytes: out.length, truncated: false };
+        return { text: out.slice(0, maxBytes), bytes: out.length, truncated: true };
+    }
+    /**
+     * The paths a commit range touched — what the replay fold is asked about.
+     *
+     * ⚠️ The state directory is excluded for the same reason it is excluded from
+     * the patch: it is looply's own bookkeeping, not the candidate's work, and a
+     * replay that carried it would carry one run's ledger onto another's base.
+     */
+    async changedPathsBetween(fromSha, toSha) {
+        // F31 (soun-5/corr-8): `--no-renames`, so a rename names BOTH paths. With rename detection a
+        // moved file reported only its new path, and a replay that overlapped the old one read as disjoint.
+        const out = await this.run(['diff', '--name-only', '--no-renames', fromSha, toSha, '--', '.', `:!${exports.STATE_DIR}`]);
+        return out
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l !== '');
+    }
+    /**
+     * Restore a retained candidate into the working tree from its patch file.
+     *
+     * ⚠️ CHECKED FIRST, THEN APPLIED, AND NEVER PARTIALLY. `--check` asks git
+     * whether the whole patch fits the tree as it stands; only then is it applied
+     * — and `git apply` without `--reject` is itself all-or-nothing, so a hunk
+     * that no longer fits leaves the tree exactly as it was. The runner decides
+     * WHETHER to restore (base matches, patch complete, paths permitted); this
+     * only does the restoring, and answers a refusal as a value rather than a
+     * throw because "the patch no longer applies" is a finding, not a fault.
+     *
+     * `patchFile` is a path on this machine, never patch text on a command line.
+     */
+    async applyPatch(patchFile) {
+        const check = await this.exec(['apply', '--check', '--', patchFile]);
+        if (check.code !== 0) {
+            return { ok: false, because: `the patch does not apply to this tree: ${check.stderr.trim()}` };
+        }
+        const applied = await this.exec(['apply', '--', patchFile]);
+        if (applied.code !== 0) {
+            return { ok: false, because: `git apply exited ${applied.code}: ${applied.stderr.trim()}` };
+        }
+        return { ok: true };
+    }
+    async stageAll() {
+        await this.run(['add', '-A', '--', '.', ...(await this.keepStateOut())]);
+    }
+    /**
+     * Is there anything staged to commit?
+     *
+     * 🔴 BECAUSE "ALREADY DONE" WAS ENDING WHOLE RUNS. `git commit` exits 1 on an
+     * empty tree, the driver turns a non-zero exit into a `GitError`, and the
+     * runner's crash path turns that into `run-aborted` — severity critical, the
+     * run over, every remaining item dropped.
+     *
+     * Measured live: a round whose gate was GREEN in 2,148 ms and whose prover
+     * answered `proven` at 0.83 killed its run, because the previous round's
+     * implementer had already written the tests this round's item asked for. The
+     * work was right, the checks agreed it was right, and being right is what
+     * ended the run.
+     *
+     * `--quiet` implies `--exit-code`: 0 means no staged difference against HEAD,
+     * 1 means there is one. Anything else is a real git failure and is raised
+     * rather than read as "nothing staged" — answering "empty" to a broken
+     * repository would silently skip a commit that should have happened.
+     */
+    async hasStagedChanges() {
+        const r = await this.exec(['diff', '--cached', '--quiet']);
+        if (r.code === 0)
+            return false;
+        if (r.code === 1)
+            return true;
+        throw new GitError(`git diff --cached --quiet exited ${r.code}: ${r.stderr.trim()}`);
+    }
+    /**
+     * Commit the staged tree. The trailer is generated here from the executed step
+     * list — the driver takes `TrailerInput`, not a finished string, so no caller
+     * can hand-write a trailer that claims a check it never ran.
+     */
+    async commit(subject, trailer) {
+        await this.run(['commit', '-m', `${subject}\n\n${(0, core_1.buildTrailer)(trailer)}`]);
+        return (await this.run(['rev-parse', 'HEAD'])).trim();
+    }
+    /**
+     * The full message of a commit, or null when the ref does not resolve.
+     *
+     * Read-only, and used by recovery for one narrow question: whether the commit
+     * at HEAD is the one a crashed round was about to record. A round commits
+     * with the item's title as the subject, and only ever after the commit permit
+     * passed — so finding it is evidence the round finished, not a substitute for
+     * the checks that let it.
+     */
+    async messageOf(ref) {
+        const r = await this.exec(['show', '-s', '--format=%B', ref]);
+        return r.code === 0 ? r.stdout.trim() : null;
+    }
+    /**
+     * Drop everything the round did: `reset --hard`, then `clean -fd` with the
+     * state directory explicitly spared. `-fd` (never `-fdx`) plus `-e` means
+     * `.looply/**` survives even in a repo whose `.gitignore` forgot it.
+     */
+    async discard() {
+        await this.run(['reset', '--hard']);
+        await this.run(['clean', '-fd', '-e', exports.STATE_DIR]);
+    }
+    /* ------------------------------------------------ the only outward verbs */
+    /**
+     * WHAT THE REMOTE SAYS THIS REF IS, OR NULL.
+     *
+     * The reconciliation read, and the reason a push is the right first real
+     * action: the question "did it happen" has an exact answer that can be asked
+     * afterwards, from a different process, with nothing carried over but the
+     * approved sha.
+     *
+     * A ref the remote does not have is `null`, which is not an error — a branch
+     * that has never existed is the ordinary case for a first push.
+     */
+    async remoteRef(remoteName, ref) {
+        refuseOption('remote', remoteName);
+        refuseOption('ref', ref);
+        const r = await this.exec(['ls-remote', '--exit-code', remoteName, ref]);
+        // 2 is `--exit-code`'s "no matching ref", which is an answer and not a
+        // failure. Anything else genuinely went wrong and must not read as absence.
+        if (r.code === 2)
+            return null;
+        if (r.code !== 0) {
+            throw new GitError(`git ls-remote exited ${r.code}: ${r.stderr.trim()}`);
+        }
+        const first = r.stdout.split(/\r?\n/).find((l) => l.trim().length > 0);
+        const sha = first?.split(/\s+/)[0]?.trim();
+        return sha !== undefined && /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+    }
+    /**
+     * THE ONE OUTWARD ACT.
+     *
+     * `<sha>:<ref>` rather than a branch name, so what is pushed is the exact
+     * commit a person approved and not whatever a local ref points at by the time
+     * this runs. There is no `--force` and no `+` in the refspec: this method
+     * cannot express a forced push, which is a stronger statement than declining
+     * to pass a flag.
+     *
+     * Everything else about safety it inherits: `nodeGitExec` is the one trusted
+     * construction point, so this call is refused outright if the repository's
+     * config names a program for git to run, and carries the hooks override and
+     * `GIT_TERMINAL_PROMPT=0` like every other verb.
+     */
+    async push(remoteName, sourceSha, destinationRef) {
+        refuseOption('remote', remoteName);
+        refuseOption('ref', destinationRef);
+        if (!/^[0-9a-f]{40}$/.test(sourceSha)) {
+            throw new GitError('a push needs a full commit id, not a ref');
+        }
+        if (!destinationRef.startsWith('refs/')) {
+            throw new GitError('a push needs a full destination ref');
+        }
+        await this.run(['push', remoteName, `${sourceSha}:${destinationRef}`]);
+    }
+}
+exports.GitDriver = GitDriver;
+/**
+ * A leading dash is an OPTION to git, not a name.
+ *
+ * There is no shell here — argv goes straight to the process — so this is not
+ * about quoting. It is that `git push --receive-pack=... origin` is a perfectly
+ * well-formed argv in which the "remote" names a program to run on the far end,
+ * and `--` cannot help because git's push grammar takes the repository
+ * positionally before any separator would apply.
+ *
+ * The action parser refuses these shapes too. This is the second place, because
+ * the driver is reachable from callers the parser never saw.
+ */
+function refuseOption(what, value) {
+    if (value.length === 0)
+        throw new GitError(`a push needs a ${what}`);
+    if (value.startsWith('-'))
+        throw new GitError(`that ${what} is an option, not a name`);
+}
+/**
+ * Real exec: argv straight to git, no shell, so message bytes arrive verbatim.
+ *
+ * THE ONE TRUSTED CONSTRUCTION POINT. Every production git call in the tree —
+ * the daemon's, the run's, the verifier's — is built here, which is why the
+ * repository-config defence can live in one place and cover all of them.
+ */
+function nodeGitExec(cwd) {
+    return (args) => new Promise((resolve, reject) => {
+        // BEFORE GIT RUNS AT ALL. A filter is named by the repository and can be
+        // called anything, so there is no `-c` override that covers the family;
+        // the only sound answer is to decline the operation. Read as a plain
+        // file, deliberately — asking git would already be running git.
+        const trouble = (0, trusted_git_1.repoConfigTroubleAt)(cwd);
+        if (trouble !== null) {
+            reject(new GitError(trouble));
+            return;
+        }
+        // AND THAT THE TREE IS THE ONE THE CALLER NAMED. Every verb below is
+        // scoped to a repository, not to `cwd`: run from a subdirectory and
+        // `reset --hard` still resets everything above. Checked here for the same
+        // reason as the config — this is the one construction point, so a caller
+        // cannot forget it.
+        const misplaced = (0, trusted_git_1.repoRootTroubleAt)(cwd);
+        if (misplaced !== null) {
+            reject(new GitError(misplaced));
+            return;
+        }
+        /**
+         * AN ABSOLUTE PATH, NEVER THE BARE NAME. On Windows the cwd is searched
+         * before PATH, and the cwd here is a directory the contained agent may
+         * write — so `spawn('git', …)` let the repository choose the program.
+         */
+        const bin = (0, trusted_git_1.gitBinary)();
+        if (bin === null) {
+            reject(new GitError('git was not found on PATH, so no repository operation can be performed'));
+            return;
+        }
+        const child = (0, node_child_process_1.spawn)(bin, [...(0, trusted_git_1.trustedGitArgs)(), ...args], {
+            cwd,
+            env: (0, trusted_git_1.trustedGitEnv)(process.env, cwd),
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (d) => out.push(d.toString('utf8')));
+        child.stderr.on('data', (d) => err.push(d.toString('utf8')));
+        child.on('error', reject);
+        child.on('close', (code) => {
+            resolve({ code: code ?? 1, stdout: out.join(''), stderr: err.join('') });
+        });
+    });
+}
+//# sourceMappingURL=git-driver.js.map