toolroll 0.9.103 → 0.9.105

package/dist/teardown-git.js

@@ -1,15 +1,3 @@
-/**
- * Git for teardown (landed-cleanup.ts and the checkout removal it drives in worktree.ts), run by Toolroll's own
- * process inside the shared repository a build can write to. A build can plant hooks in .git/hooks and settings in
- * .git/config (or a worktree's config.worktree), so every teardown command runs hardened: an allowlisted environment
- * with no system or global config (remote-main.ts's), no hooks, no fsmonitor, no ext transport, no prompts and no
- * automatic maintenance.
- *
- * Settings that name a command, and includes (which could bring them in from a file nobody looked at), are not
- * overridden but refused: before each command the repository's own config is read with includes off, and if it sets
- * any of them the command never runs. The refusal is a failed git result, so every caller's existing doubt applies and
- * nothing is removed.
- */
 import { spawnSync } from "node:child_process";
 import { accessSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync, writeSync } from "node:fs";
 import { randomBytes } from "node:crypto";
@@ -21,12 +9,10 @@ import { run } from "./exec.js";
 import { ENV, ENV_ALLOWLIST } from "./remote-main.js";
 import { WORKTREE_TIMEOUT_MS } from "./worktree.js";
 import { FOLDER_DIDNT_ANSWER, folderAnswers } from "./folder-gate.js";
-/** Fixed on every teardown command, ahead of its own arguments. */
 export const TEARDOWN_FLAGS = [
     "--no-optional-locks", "-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "-c", "protocol.ext.allow=never",
     "-c", "credential.helper=", "-c", "gc.auto=0", "-c", "maintenance.auto=false", "-c", "submodule.recurse=false",
 ];
-/** Exit code of a refused command (git's own fatal code, so no caller reads it as "not found" or "no"). */
 export const REFUSED_CODE = 128;
 const REFUSED_PREFIX = "Toolroll won't run git here: ";
 const KNOWN_SECTIONS = new Map(Object.entries({
@@ -36,7 +22,6 @@ const KNOWN_SECTIONS = new Map(Object.entries({
             "packedgitlimit", "packedgitwindowsize", "deltabasecachelimit", "multipackindex", "commitgraph", "splitindex", "warnambiguousrefs", "notesref",
             "sparsecheckout", "sparsecheckoutcone", "filesreflocktimeout", "packedrefstimeout", "usereplacerefs", "fsync", "fsyncmethod", "fsyncobjectfiles",
             "checkroundtripencoding", "protecthfs", "protectntfs", "logallrefupdates", "restrictinheritedhandles", "maxtreedepth", "createobject"] },
-    // A remote: never its helper programs; its URLs are checked apart (helperUrl).
     remote: { allow: ["url", "pushurl", "fetch", "push", "mirror", "tagopt", "prune", "prunetags", "promisor", "partialclonefilter", "skipdefaultupdate",
             "skipfetchall", "followremotehead", "serveroption", "proxy", "proxyauthmethod"] },
     branch: "any", user: "any", init: "any", pull: "any", push: "any", fetch: "any", status: "any", color: "any", advice: "any", extensions: "any",
@@ -52,12 +37,9 @@ const KNOWN_SECTIONS = new Map(Object.entries({
     submodule: { deny: ["update"] },
     gc: { deny: ["recentobjectshook"] },
     uploadpack: { deny: ["packobjectshook"] },
-    // git-lfs's own: lfsCommand decides (inert keys only); filter: git-lfs's exact values only (runsCommand).
     lfs: "any",
     ssh: { allow: ["variant"] },
 }));
-/** A remote URL git hands to a remote helper: `<helper>::…`, or a scheme git has no transport of its own for (it runs
- * git-remote-<scheme>). scp-like `host:path`, `user@host:path` and plain paths are git's own. */
 const OWN_SCHEMES = new Set(["https", "http", "ssh", "git", "file", "git+ssh", "ssh+git"]);
 function helperUrl(value) {
     const url = value.trim();
@@ -66,7 +48,6 @@ function helperUrl(value) {
     const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(url);
     return scheme !== null && !OWN_SCHEMES.has(scheme[1].toLowerCase());
 }
-/** A config key's parts as git names them: section and variable lowercased, the subsection as it is (or null). */
 function keyParts(key) {
     const first = key.indexOf(".");
     const last = key.lastIndexOf(".");
@@ -74,8 +55,6 @@ function keyParts(key) {
         return { section: key.toLowerCase(), subsection: null, variable: "" };
     return { section: key.slice(0, first).toLowerCase(), subsection: first === last ? null : key.slice(first + 1, last), variable: key.slice(last + 1).toLowerCase() };
 }
-/** git-lfs settings that name no program (where it fetches, what, whether it checks locks, how it signs in); any other
- * `lfs.*` key in a checkout's own config could (extensions, custom and standalone transfer agents), so it's refused. */
 const INERT_LFS_PLAIN = new Set(["url", "pushurl", "fetchinclude", "fetchexclude", "locksverify", "repositoryformatversion", "setlockablereadonly", "skipdownloaderrors", "concurrenttransfers"]);
 const INERT_LFS_SUBSECTION = new Set(["access", "locksverify"]);
 const lfsCommand = (key) => {
@@ -84,17 +63,11 @@ const lfsCommand = (key) => {
         return false;
     return subsection === null ? !INERT_LFS_PLAIN.has(variable) : !INERT_LFS_SUBSECTION.has(variable);
 };
-/** core.fsmonitor as a boolean is git's own daemon; anything else is a command to run. */
 const BOOLEAN = /^(|true|false|yes|no|on|off|-?\d+)$/i;
-/** Whether one setting can run a command (or bring in config nobody read), whatever scope it came from. git-lfs's own
- * filters, exactly as `git lfs install` writes them (LFS_FILTER), are the one filter allowed, and only where the caller
- * has also refused a `.lfsconfig` naming a git-lfs extension (`lfsChecked`): git-lfs reads that file as it runs. */
 function runsCommand(key, value, lfsChecked) {
     const { section, subsection, variable } = keyParts(key);
     if (section === "core" && variable === "fsmonitor")
         return !BOOLEAN.test(value.trim());
-    // A filter: whether it is required names no program; its commands only git-lfs's own, exactly, beside a checked
-    // .lfsconfig.
     if (section === "filter")
         return !((variable === "required" && BOOLEAN.test(value.trim())) || (lfsChecked && subsection === "lfs" && LFS_FILTER.get(`filter.lfs.${variable}`) === value));
     if (section === "lfs")
@@ -110,10 +83,6 @@ function runsCommand(key, value, lfsChecked) {
         return rule.deny.includes(variable);
     return !rule.allow.includes(variable);
 }
-/** The command-running setting a `git config --list --show-scope -z` listing sets, or null. Only local and worktree
- * scope count: teardown commands never read system or global config. `lfsChecked`: the caller refuses a checkout whose
- * `.lfsconfig` names a git-lfs extension (lfsExtensionIn), so git-lfs's own exact filters may stand (runsCommand).
- * Fails closed: a listing that can't be classified names a setting. */
 export function commandSetting(listing, options = {}) {
     try {
         const fields = listing.split("\0");
@@ -134,18 +103,11 @@ export function commandSetting(listing, options = {}) {
         return "a setting that couldn't be read";
     }
 }
-/**
- * What the plane's git on a build's checkout keeps of the operator's own (global and system) configuration: values,
- * never commands — identity, line endings, ignore and case settings — and git-lfs's filters only as git-lfs itself
- * installs them, exactly. Everything else there (filters, diff drivers, fsmonitor, signing and its key commands,
- * whatever an include brings in) is left out, so nothing in it can run a file of the checkout's.
- */
 const CARRIED_VALUES = new Set(["user.name", "user.email", "core.autocrlf", "core.eol", "core.safecrlf", "core.excludesfile", "core.ignorecase",
     "core.precomposeunicode", "core.quotepath", "core.filemode", "core.symlinks", "core.longpaths"]);
 const LFS_FILTER = new Map(Object.entries({
     "filter.lfs.clean": "git-lfs clean -- %f", "filter.lfs.smudge": "git-lfs smudge -- %f", "filter.lfs.process": "git-lfs filter-process", "filter.lfs.required": "true",
 }));
-/** The `-c` settings that carry the operator's own values (CARRIED_VALUES, LFS_FILTER) from a global/system listing. */
 export function carriedSettings(listing) {
     const fields = listing.split("\0");
     const carried = new Map();
@@ -163,13 +125,10 @@ export function carriedSettings(listing) {
     }
     return [...carried].flatMap(([key, value]) => ["-c", `${key}=${value}`]);
 }
-/** Why a teardown command was refused, or null when `result` isn't a refusal. */
 export function refusal(result) {
     return result.code === REFUSED_CODE && result.stderr.startsWith(REFUSED_PREFIX) ? result.stderr.slice(REFUSED_PREFIX.length).trim() : null;
 }
 const refused = (why) => ({ code: REFUSED_CODE, stdout: "", stderr: `${REFUSED_PREFIX}${why}\n`, timedOut: false, notFound: false });
-/** Refuse nested repositories without asking Git to enter them or evaluate their config.
- * Includes ignored/untracked repositories and bare repositories; never follows symlinks. */
 function nestedRepository(path) {
     const pending = [path];
     while (pending.length > 0) {
@@ -184,18 +143,10 @@ function nestedRepository(path) {
     }
     return false;
 }
-/**
- * Runs `work` with a write view of `cwd`'s repository (gitView): the view, and how to restore git's output. From a
- * folder inside a checkout, the view is of the checkout git would find (checkoutRootOf); with none, git's own "not a
- * git repository", nothing run. One whose `.git` or config can't be read as git reads it, or isn't bound to one
- * repository (boundDirs; `binding.repo` when the caller has the project's), is refused; so is a command whose
- * repository changed under it while git ran.
- */
 async function inView(cwd, binding, work, after = true, lockTimeoutMs, doing, gitFile = "git") {
     const root = checkoutRootOf(cwd);
     if (root === null)
         return NOT_A_REPOSITORY;
-    // One plane git command at a time on a checkout (git-views.ts withCheckoutLock: re-entrant along one call chain).
     let key;
     try {
         key = realpathSync(root);
@@ -228,17 +179,9 @@ async function inView(cwd, binding, work, after = true, lockTimeoutMs, doing, gi
         return refused(error instanceof Error ? error.message : "the checkout is busy");
     }
 }
-/** The one way teardown runs git, including the target checkout immediately before removal. Every command runs
- * against a write view of its repository (gitView), whose config is the one inspected and whose info is a copy, so a
- * setting or attributes file an agent adds after the inspection is never read (a build's process can outlive its turn:
- * on macOS containment is observational, src/containment.ts, and a sibling build shares the repository). A removal's
- * target is bound to the same repository as the folder it is removed from. A removal without --force runs under the
- * target's own view (its own config.worktree folded in), so git's last check of whether it is clean reads it as the
- * target itself would. `binding.repo`: the project's main checkout, from the plane's records, when the caller has it. */
 export function teardownGit(runner = run, binding = {}, lockTimeoutMs, gitFile = "git") {
     const options = (cwd, env) => ({ cwd, envAllowlist: ENV_ALLOWLIST, env: { ...ENV, ...env }, timeoutMs: WORKTREE_TIMEOUT_MS, maxBuffer: 512 * 1024 * 1024 });
     const configProblem = async (cwd, env) => {
-        // git-lfs's own filters may stand only beside a .lfsconfig that names no extension (commandSetting's lfsChecked).
         if (lfsExtensionIn(env["GIT_WORK_TREE"] ?? cwd, gitFile))
             return refused("the checkout's .lfsconfig sets a git-lfs key that can run a command");
         const config = await runner("git", ["--no-optional-locks", "config", "--list", "--no-includes", "--show-scope", "-z"], options(cwd, env));
@@ -264,7 +207,6 @@ export function teardownGit(runner = run, binding = {}, lockTimeoutMs, gitFile =
         const ran = async (env) => restore(await runner("git", [...TEARDOWN_FLAGS, ...WRITE_VIEW_FLAGS, ...safeArgs], options(cwd, env)), args);
         if (!(removal || inspection || args.includes("checkout") || args.includes("clean")))
             return ran(view.env);
-        // The checkout the command acts on, in its own view (bound to the same repository), checked first.
         return inView(target, { repo: binding.repo ?? dirname(view.dirs.common) }, async (targetView) => {
             if (removal) {
                 const targetProblem = await configProblem(target, targetView.env);
@@ -278,25 +220,18 @@ export function teardownGit(runner = run, binding = {}, lockTimeoutMs, gitFile =
             catch {
                 return refused("the checkout couldn't be inspected for nested repositories");
             }
-            // ls-files reads index entries only; it cannot run submodule filters. Even an uninitialized
-            // gitlink is kept, so worktree remove's internal status can never traverse it.
             const index = await runner("git", [...TEARDOWN_FLAGS, ...WRITE_VIEW_FLAGS, "ls-files", "--stage", "-z"], options(target, targetView.env));
             if (index.code !== 0)
                 return refused("the checkout's index couldn't be read");
             if (index.stdout.split("\0").some(entry => entry.startsWith("160000 ")))
                 return refused("the checkout contains a gitlink");
-            // git's own clean check in a removal (a `status` it runs in the target) reads the config GIT_COMMON_DIR names:
-            // the target's view, inspected above, so it judges the target by the target's own settings.
             return ran(removal && !forced ? { ...view.env, GIT_COMMON_DIR: targetView.env["GIT_COMMON_DIR"] } : view.env);
-            // A removed target has no git directory left to prove: the folder it was removed from is proven instead.
         }, !removal, lockTimeoutMs, doing, gitFile);
     }, true, lockTimeoutMs, teardownDoing(args), gitFile);
 }
-/** What teardown git is doing, for an incident's notice: removing a checkout, or looking one over to tidy it. */
 function teardownDoing(args) {
     return args.includes("worktree") && args.includes("remove") ? "removing an old checkout" : "tidying an old checkout";
 }
-/** What a build's git is doing, for an incident's notice. */
 function checkoutDoing(args) {
     if (args.includes("worktree"))
         return args.includes("remove") ? "removing a checkout" : args.includes("add") ? "making a checkout" : "listing checkouts";
@@ -306,8 +241,6 @@ function checkoutDoing(args) {
         return "updating a repository";
     return "reading a build's checkout";
 }
-/** A setup call's time limit: its own five seconds, or less when a caller's deadline leaves less (never below 1 ms;
- * a caller checks the deadline itself before calling). */
 const setupTimeout = (limit) => limit === undefined ? 5_000 : Math.max(1, Math.min(5_000, limit()));
 export function checkoutIncludes(checkout, gitFile = "git", limit) {
     const dirs = gitDirsOf(checkout);
@@ -323,10 +256,7 @@ export function checkoutIncludes(checkout, gitFile = "git", limit) {
     }
     return false;
 }
-/** One config file, read only as the regular file it is (bounded), or null. */
 function regularFile(path) {
-    // Opened without following a link and without blocking, then judged by what was opened: a FIFO swapped in after a
-    // look never hangs the read (eval-harness review 1, finding 7).
     let fd = null;
     try {
         fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
@@ -343,13 +273,10 @@ function regularFile(path) {
             closeSync(fd);
     }
 }
-/** A checkout's git directory and common directory, as git finds them from its `.git` (a folder, or a one-line
- * `gitdir: ` file); null when the pointer isn't one git would read the same way. */
 function gitDirsOf(checkout, vouched = NO_VOUCHED) {
     let gitdir = join(checkout, ".git");
     try {
         if (!lstatSync(gitdir).isDirectory()) {
-            // As git reads a .git file: "gitdir: " then the path, one line; anything else (more lines, stray space) refused.
             const text = (regularFile(gitdir) ?? "").replace(/\r?\n$/, "");
             if (!text.startsWith("gitdir: ") || /[\r\n]/.test(text))
                 return null;
@@ -362,12 +289,6 @@ function gitDirsOf(checkout, vouched = NO_VOUCHED) {
     catch {
         return null;
     }
-    // Where the checkout's own files point (a build can write both): read, in the console, only while that folder
-    // answered a look lately, and never vouched for by the checkout pool's spelling (folder-gate.ts). Held back: not one
-    // git would read the same way, so every caller refuses.
-    // `vouched`: the very folders this view was made from, read again after git ran (settle). They answered moments ago
-    // and git just ran in them; the gate's staleness is no evidence about them. Anything they now point elsewhere is
-    // gated as ever, so a re-pointed `.git` or `commondir` is never read on the console's thread on its say.
     if (gitdir !== join(checkout, ".git") && !vouched.has(gitdir) && !folderAnswers(gitdir, true))
         return null;
     const named = regularFile(join(gitdir, "commondir"))?.trim();
@@ -376,14 +297,8 @@ function gitDirsOf(checkout, vouched = NO_VOUCHED) {
         return null;
     return { gitdir, common };
 }
-/** What includeIn answers when Git didn't finish parsing the file in time: still a refusal, named as what it is. */
 export const INCLUDE_PARSE_TIMED_OUT = "Git didn't finish reading it in time";
-/** The include parse's own limit: a loaded machine (a CI runner's parallel test files) can take seconds to start git, and
- * a refusal that names a slow machine an "unreadable file" sent two releases chasing a config that was fine. */
 const INCLUDE_PARSE_MS = 15_000;
-/** The include key one config file sets (lowercased, as git names it), "include" when only a plain reading finds one,
- * "an unreadable file" when it can't be read as a plain file or parsed, or INCLUDE_PARSE_TIMED_OUT when the caller's
- * deadline or the parse's own limit ran out first; null when it includes nothing. Every non-null answer refuses. */
 function includeIn(path, gitFile = "git", limit) {
     const text = regularFile(path);
     if (text === null)
@@ -465,7 +380,6 @@ function boundDirs(checkout, binding = {}, vouched = NO_VOUCHED) {
             fail("belongs to a git directory that names another checkout");
         dirs = { checkout: top, gitdir, common, linked: true, spelled: [named.gitdir, named.common, gitdir, common] };
     }
-    // The common folder is a main checkout's own `.git` folder, a real one.
     if (basename(dirs.common) !== ".git")
         fail("belongs to a repository that isn't a checkout's");
     try {
@@ -476,10 +390,6 @@ function boundDirs(checkout, binding = {}, vouched = NO_VOUCHED) {
         fail("belongs to a repository that isn't there");
     }
     if (binding.repo != null) {
-        // The anchor is the plane's own record, never a pointer file: the recorded project's main checkout, whose `.git`
-        // must be a real folder (not a link, holding no `commondir`); its real path is the only common folder accepted. A
-        // record that isn't such a checkout (a linked worktree, as agent-fence.ts trustedWorktreeBinding also refuses) or
-        // can't be read is refused, never taken as unbound.
         let recorded = null;
         try {
             const dotgit = join(realpathSync(binding.repo), ".git");
@@ -496,24 +406,14 @@ function boundDirs(checkout, binding = {}, vouched = NO_VOUCHED) {
     }
     return dirs;
 }
-/** The shared git folder of a recorded project, read from disk and proven as boundDirs proves it: the project's own
- * real `.git` folder, holding no `commondir`. No pointer file or `commondir` an agent can write decides it, and no git
- * runs (a page visit reads this). Throws with the reason otherwise. */
 export function recordedCommonDir(repo) {
     return boundDirs(repo, { repo }).common;
 }
-/** What git keeps only per worktree and the plane never links: HEAD (git won't take it as a link) and the pointers. */
-/** What the plane links of a worktree's own git folder (git writes them in place through the link: the index and its
- * logs by lockfile, per-worktree refs and logs inside the folders), whether or not they exist yet; a rebase's,
- * cherry-pick's or sequencer's state folder only when one is already there. */
 const ADMIN_LINKED = ["index", "logs", "refs", "reftable"];
-/** What git keeps in a common directory (its path.c common_list, and reftable), linked whether or not it exists yet. */
 const COMMON_NAMES = ["branches", "gc.pid", "logs", "lost-found", "modules", "objects", "packed-refs", "reftable", "refs", "remotes", "rr-cache", "shallow", "svn", "worktrees"];
-/** Where git incidents are recorded: beside the fenced views folder (git-incident.ts). */
 export function gitIncidentRecord() {
     return join(dirname(ensureGitViewsRoot(realpathSync(homedir()))), "git-incidents.jsonl");
 }
-/** `doing`: what the plane was doing, in a person's words ("tidying an old checkout"), for an incident's notice. */
 function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
     const dirs = boundDirs(checkout, binding);
     const root = ensureGitViewsRoot(realpathSync(homedir()));
@@ -529,7 +429,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
         const configPath = join(view, "config");
         writeFileSync(configPath, config, { mode: 0o600 });
         const base = { cwd: "/", encoding: "utf8", killSignal: "SIGKILL", env: { PATH: process.env["PATH"] ?? "", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", HOME: "/nonexistent" } };
-        // Each call's limit is worked out as it starts, from what is left of a caller's deadline.
         const plainNow = () => {
             if (limit !== undefined && limit() <= 0)
                 throw new Error("the read's deadline passed");
@@ -540,7 +439,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
             if (flag.status !== 0 && flag.status !== 1)
                 throw new Error("the checkout's git config couldn't be read");
             if (flag.stdout.trim() === "true") {
-                // Git would also read the worktree's config.worktree, which the agent can still change: folded in as it is now.
                 const worktree = join(dirs.gitdir, "config.worktree");
                 const own = existsSync(worktree) ? regularFile(worktree) : "";
                 if (own === null)
@@ -558,7 +456,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
         if (include !== null)
             throw new Error(`the checkout's git config includes another file (${include})`);
         mkdirSync(join(view, "info"));
-        // A main checkout's sparse-checkout patterns are in its own (common) info folder; a linked one's in its admin's.
         for (const name of kind === "write" ? ["exclude", "attributes", "sparse-checkout"] : ["exclude", "sparse-checkout"]) {
             if (name === "sparse-checkout" && dirs.linked)
                 continue;
@@ -566,7 +463,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
             if (!existsSync(path))
                 continue;
             const text = regularFile(path);
-            // A write that dropped the operator's exclude or attributes could stage what they keep out: refused instead.
             if (text === null && kind === "write")
                 throw new Error(`the checkout's info/${name} couldn't be read as a plain file`);
             if (text !== null)
@@ -578,32 +474,25 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
                 try {
                     mkdirSync(folder);
                 }
-                catch { /* git reports it if it needs the folder */ }
+                catch { }
             }
             try {
                 for (const id of readdirSync(folder))
                     priorWorktrees.add(id);
             }
-            catch { /* none yet */ }
+            catch { }
         }
         for (const name of new Set([...readdirSync(dirs.common), ...COMMON_NAMES])) {
             if (name === "config" || name === "info" || name === "hooks" || name === "commondir")
                 continue;
             symlinkSync(join(dirs.common, name), join(view, name));
         }
-        // GIT_DIR is the plane's too (git's ref store reads `commondir` from GIT_DIR as it goes, empirically on 2.50.1):
-        // its `commondir` names the view and its `gitdir` this checkout, both the plane's; HEAD is a copy (git won't take
-        // it as a link) carried back after the run; the worktree's other files are linked (the index and logs even before
-        // they exist), so git's lockfiles write them in place.
-        // (A folder under a dangling link can't be made by git: the worktree's `logs` is made first, as git would.)
         if (kind === "write" && !existsSync(join(dirs.gitdir, "logs"))) {
             try {
                 mkdirSync(join(dirs.gitdir, "logs"));
             }
-            catch { /* git reports it */ }
+            catch { }
         }
-        // Only what git needs of the worktree's own folder is linked (ADMIN_LINKED, and a split index's shared files), each
-        // checked to be a real entry directly in it, never a link (Codex review of a0fa135d).
         const linked = [...ADMIN_LINKED, ...readdirSync(dirs.gitdir).filter(name => name.startsWith("sharedindex."))];
         for (const name of new Set(linked)) {
             const path = join(dirs.gitdir, name);
@@ -622,9 +511,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
         const head = regularFile(join(dirs.gitdir, "HEAD"));
         if (head === null)
             throw new Error("the checkout's HEAD couldn't be read as a plain file");
-        // The worktree's own state files (WORKTREE_STATE: HEAD, a merge's, cherry-pick's, rebase's or bisect's pseudo-refs
-        // and messages) are copies (git won't take them as links), carried back after the run; its state folders, when
-        // there, are linked.
         for (const name of WORKTREE_STATE) {
             const path = join(dirs.gitdir, name);
             if (!existsSync(path) && name !== "HEAD")
@@ -651,7 +537,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
         }
         writeFileSync(join(admin, "commondir"), `${view}\n`, { mode: 0o600 });
         writeFileSync(join(admin, "gitdir"), `${join(dirs.checkout, ".git")}\n`, { mode: 0o600 });
-        // A main checkout's own info (its sparse-checkout) is the view's frozen one; a linked one's is its own.
         symlinkSync(dirs.linked ? join(dirs.gitdir, "info") : join(view, "info"), join(admin, "info"));
         if (!pinned(dirs).ok)
             throw new Error("the checkout's repository has a folder that is a link");
@@ -660,7 +545,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
         dispose();
         throw error;
     }
-    // The folders down to the worktree's own, as they are now: carry-back writes only while each is still the same one.
     let anchor;
     try {
         anchor = anchorOf(dirs.gitdir);
@@ -669,9 +553,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
         dispose();
         throw new Error("the checkout's repository has a folder that is a link");
     }
-    // Where git names a view (rev-parse --git-dir, --git-common-dir), the caller is told the repository's own folder;
-    // where `worktree list` names the common view as the main worktree, that worktree (git's rule: the common dir less
-    // `/.git`).
     const mainWorktree = dirname(dirs.common);
     const restore = (output, args) => {
         if (!output.includes(view) && !output.includes(admin))
@@ -682,8 +563,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
     const settle = () => {
         const now = pinned(dirs);
         let bound = false;
-        // The same proof as before git ran, of the same folders: re-read past the console's folder gate only where they are
-        // the very ones this view was made from (vouched), so a gate whose answer went stale mid-run is never read as a swap.
         try {
             const again = boundDirs(checkout, binding, new Set(dirs.spelled));
             bound = again.gitdir === dirs.gitdir && again.common === dirs.common;
@@ -692,7 +571,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
             bound = false;
         }
         if (!now.ok || !bound) {
-            // Too late to prevent: recorded and told (git-incident.ts), never rolled back where the swap leads.
             if (kind === "write") {
                 gitIncident({ checkout: dirs.checkout, repository: dirs.common, swapped: now.swapped.length > 0 ? now.swapped.map(({ path, leadsTo }) => ({ path, leadsTo })) : [{ path: join(dirs.checkout, ".git"), leadsTo: null }],
                     cause: now.swapped.length > 0 ? "swapped" : "rebound", ...(doing === undefined ? {} : { doing }), record: gitIncidentRecord() });
@@ -700,8 +578,6 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
             return "the checkout's repository changed while git ran";
         }
         if (kind === "write") {
-            // The worktree's own state git rewrote in the plane's GIT_DIR goes back to it, and what it removed is removed
-            // there; anything else git left there the plane can't keep, and says so.
             const left = readdirSync(admin).filter(name => !initial.has(name) && !WORKTREE_STATE.includes(name) && !["commondir", "gitdir", "info"].includes(name));
             try {
                 carryBack(admin, dirs.gitdir, initial, anchor);
@@ -722,37 +598,16 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
     };
     return { env: { GIT_DIR: admin, GIT_COMMON_DIR: view, GIT_WORK_TREE: dirs.checkout }, restore, dispose, dirs, settle };
 }
-/** A worktree's own state files git may write (git's per-worktree names: HEAD and the pseudo-refs and messages of a
- * merge, cherry-pick, revert, rebase or bisect), and its state folders. */
 const WORKTREE_STATE = ["HEAD", "ORIG_HEAD", "MERGE_HEAD", "MERGE_MSG", "MERGE_MODE", "MERGE_RR", "AUTO_MERGE", "FETCH_HEAD", "COMMIT_EDITMSG",
     "CHERRY_PICK_HEAD", "REVERT_HEAD", "REBASE_HEAD", "SQUASH_MSG", "TAG_EDITMSG", "BISECT_LOG", "BISECT_START", "BISECT_TERMS", "BISECT_EXPECTED_REV",
     "BISECT_ANCESTORS_OK", "BISECT_NAMES", "BISECT_RUN", "BISECT_HEAD"];
 const WORKTREE_STATE_DIRS = ["sequencer", "rebase-merge", "rebase-apply"];
-/**
- * Whether every path git may write through a view is still the repository's own (Codex review of a0fa135d: git
- * writes deeper than the top-level folders, through a link at `refs/heads/x`, `logs/…` or `objects/xx` as well). The
- * walk, by lstat, never following a link: every name of the common folder git may write (COMMON_NAMES: refs, logs,
- * reftable, packed-refs, worktrees with each worktree's own folder, rr-cache, modules, …) all the way down, HEAD and
- * the index; the worktree's own state (WORKTREE_STATE: its HEAD, index, refs, logs, a merge's, rebase's or bisect's
- * state, a split index's shared files); and the object store (the common `objects`, and a submodule git directory's
- * own under modules/): its fan-out folders' entries for links, `info` and `pack` all the way down, but not each loose
- * object (a big repository has very many, and hard-linked objects are legitimate). Any link is refused, so is a folder
- * that can't be listed, and so is any file walked deep with a second hard link (git appends to a log in place), but for
- * another checkout's index (siblingIndexes: still never a link). The exemptions are by place only: an `objects` anywhere else (under refs/, logs/, worktrees/) is walked like the rest. For each one found, where it leads (for an incident's record).
- *
- * Checked when the view is made and again after git ran; between the two, a process that outlived the agent's turn
- * can still swap one of these for a link and have git write through it mid-command. That window is an accepted
- * residual: git takes paths, not handles. Seen after the run, it is an incident (git-incident.ts).
- */
 function pinned(dirs) {
     const swapped = [];
     const seen = new Set();
     let budget = 400_000;
     const stores = objectStores(dirs.common);
     const siblings = siblingIndexes(dirs);
-    /** `deep`: every entry all the way down, each file held to one hard link. `shallow`: the folder's own entries
-     * checked for links only. `store`: an object store (objects/: its fan-out folders shallow, `info` and `pack` deep
-     * without the hard-link test). A link, or a folder that can't be listed, is swapped. */
     const check = (path, mode) => {
         if (seen.has(path))
             return;
@@ -777,9 +632,6 @@ function pinned(dirs) {
             swapped.push({ path, leadsTo: real });
             return;
         }
-        // Another checkout's own index, by exact place (siblingIndexes): held to being no link, but a second name is not
-        // counted. A tool in that checkout may hard-link it for a moment (Claude Code's security-guidance plugin does, to
-        // diff against a copy), and git never writes another checkout's index, nor any index in place.
         if (held.isFile() && mode === "deep" && held.nlink > 1 && !siblings.has(path)) {
             swapped.push({ path, leadsTo: null });
             return;
@@ -787,7 +639,6 @@ function pinned(dirs) {
         if (!held.isDirectory())
             return;
         let entries;
-        // A folder that can't be listed hides what's in it: it counts as swapped (fail closed).
         try {
             entries = readdirSync(path);
         }
@@ -802,19 +653,16 @@ function pinned(dirs) {
                     if (lstatSync(child).isSymbolicLink())
                         check(child, "shallow");
                 }
-                catch { /* gone */ }
+                catch { }
                 continue;
             }
             if (mode === "store") {
                 check(child, name === "info" || name === "pack" ? "deep-unlinked" : "shallow");
                 continue;
             }
-            // The object store exemption by exact place, never by name (stores, enumerated before the walk).
             check(child, stores.has(child) ? "store" : mode);
         }
     };
-    // The common folder's every name git may write, all the way down (refs, logs, reftable, packed-refs, worktrees with
-    // each worktree's own folder, rr-cache, modules, the rest of COMMON_NAMES), and the worktree's own state.
     for (const name of COMMON_NAMES)
         if (name !== "objects")
             check(join(dirs.common, name), "deep");
@@ -830,14 +678,10 @@ function pinned(dirs) {
     catch {
         swapped.push({ path: dirs.gitdir, leadsTo: null });
     }
-    // The object store: the folder and its fan-out folders for links (not each loose object: a big repository has very
-    // many, and `clone --local` hard-links them legitimately; git writes a new object to a fresh temporary file linked
-    // into place, never through an existing one), `info` and `pack` all the way down.
     for (const store of stores)
         check(store, "store");
     if (budget <= 0)
         swapped.push({ path: dirs.common, leadsTo: null });
-    // A path that is no longer its own real path (a folder on the way swapped) counts too.
     for (const path of [dirs.common, dirs.gitdir]) {
         try {
             if (realpathSync(path) !== path)
@@ -849,12 +693,6 @@ function pinned(dirs) {
     }
     return { ok: swapped.length === 0, swapped };
 }
-/**
- * The object stores the walk exempts from its full check, enumerated before it, never decided by a name met on the
- * way: the common `objects`, and `<gitdir>/objects` for each submodule git directory under modules/ — a folder with
- * its own config, HEAD, refs/ and objects/, reached through no component named refs, logs, reftable, objects, info,
- * worktrees or hooks (so `modules/x/refs/objects` with a planted HEAD is no store).
- */
 function objectStores(common) {
     const stores = new Set([join(common, "objects")]);
     const NOT_A_PATH = new Set(["refs", "logs", "reftable", "objects", "info", "worktrees", "hooks"]);
@@ -890,16 +728,6 @@ function objectStores(common) {
     visit(join(common, "modules"), 0);
     return stores;
 }
-/**
- * The index files of the repository's other checkouts, by exact place, enumerated before the walk: `index` directly in
- * each worktree folder of the common `worktrees` that isn't this checkout's own git directory, and, for a linked
- * checkout, the main checkout's `index` in the common folder. The walk still refuses any of them that is a link; it
- * only doesn't count a second hard link to one (pinned). The view links only this checkout's own index, and git writes
- * an index only by renaming a new file over it, so a hard link at another checkout's can't take a write of the plane's
- * anywhere. Measured (Nov 2026): Claude Code's security-guidance plugin hard-links the index of the checkout a session
- * runs in to a temporary copy for up to seconds at a time, and a release gate that ran meanwhile in another checkout of
- * the repository was stopped as an incident naming that checkout's index.
- */
 function siblingIndexes(dirs) {
     const indexes = new Set();
     if (dirs.linked)
@@ -908,7 +736,7 @@ function siblingIndexes(dirs) {
     try {
         ids = readdirSync(join(dirs.common, "worktrees"));
     }
-    catch { /* none (an unlistable folder is the walk's to refuse) */ }
+    catch { }
     for (const id of ids) {
         const folder = join(dirs.common, "worktrees", id);
         if (folder !== dirs.gitdir)
@@ -929,8 +757,6 @@ function anchorOf(path) {
 }
 class AnchorMoved extends Error {
 }
-/** Throws AnchorMoved unless every folder of `anchor` is still the one it was (Node has no openat, so each component
- * is looked at again right before each rename or unlink). */
 function holdAnchor(anchor) {
     for (const one of anchor) {
         let held;
@@ -944,9 +770,6 @@ function holdAnchor(anchor) {
             throw new AnchorMoved(one.path);
     }
 }
-/** Carry the WORKTREE_STATE files git rewrote or removed in the plane's GIT_DIR back to the worktree's own folder: a
- * new file of a random name, created exclusively (never through a link), then renamed into place; before each rename
- * or unlink, every folder down to the worktree's own is proven the same one it was when the view was made. */
 function carryBack(admin, gitdir, initial, anchor) {
     for (const name of WORKTREE_STATE) {
         const here = join(admin, name);
@@ -959,7 +782,6 @@ function carryBack(admin, gitdir, initial, anchor) {
         }
         const was = initial.get(name);
         if (held === null) {
-            // Removed by git: removed in the worktree's own folder too (a merge's state once it concluded).
             if (initial.get(name) != null) {
                 holdAnchor(anchor);
                 rmSync(join(gitdir, name), { force: true });
@@ -990,19 +812,6 @@ function carryBack(admin, gitdir, initial, anchor) {
         }
     }
 }
-/**
- * A worktree `worktree add` made through a view, pointed at its repository instead of the view. Before git 2.48 the new
- * checkout's `.git` file names the common directory as given (the view, removed right after the run: every later
- * command in that checkout would find no repository); later versions name its real path, and this finds nothing to do.
- * Only a worktree folder this run made (not there when the view was made) whose checkout's `.git` is a plain file
- * reading exactly `gitdir: <view>/worktrees/<id>` (a name private to this run, in a folder every fence denies) is
- * rewritten: a new file created exclusively (never through a link) and renamed into place, then bound to the repository
- * (boundDirs) as any checkout is. Before it writes, the repository's own record of the worktree must name this very
- * checkout and repository, and every folder down to the checkout is anchored (anchorOf) and proven the same one before
- * the open, the re-read and the rename, as carryBack does. A failure after the rename isn't undone (the old content
- * names a view that no longer exists, so the checkout is unusable either way); it refuses. Null when every such
- * checkout is bound, or why one isn't.
- */
 function relinkAdded(view, common, prior) {
     let ids;
     try {
@@ -1032,7 +841,6 @@ function relinkAdded(view, common, prior) {
         } };
         if (read()?.trim() !== stale)
             continue;
-        // The repository's record of this worktree names this checkout and this repository, before anything is written.
         const admin = join(common, "worktrees", id);
         let recorded;
         try {
@@ -1062,7 +870,6 @@ function relinkAdded(view, common, prior) {
             finally {
                 closeSync(fd);
             }
-            // Checked again at the moment of use: the same folders, and still the plain file git wrote.
             holdAnchor(anchor);
             if (read()?.trim() !== stale) {
                 rmSync(temporary, { force: true });
@@ -1084,8 +891,6 @@ function relinkAdded(view, common, prior) {
     }
     return null;
 }
-/** The checkout git would find from `cwd`: the nearest folder, `cwd` or above, with a `.git`; null when there is
- * none (git's own "not a git repository"). A `.git` that can't even be looked at counts as found (the view refuses it). */
 function checkoutRootOf(cwd) {
     for (let dir = resolve(cwd);; dir = dirname(dir)) {
         try {
@@ -1101,14 +906,7 @@ function checkoutRootOf(cwd) {
     }
 }
 const NOT_A_REPOSITORY = { code: 128, stdout: "", stderr: "fatal: not a git repository (or any of the parent directories): .git\n", timedOut: false, notFound: false };
-/** Settings fixed on every write through a view: `worktree add` records absolute paths (relative ones would need a
- * config write, which a view keeps); no transport at all (a caller that fetches allows its one protocol by name, as the
- * nightly check's local fetch does with protocol.file.allow); and no split index (its shared index files would be
- * written in the plane's GIT_DIR). */
 export const WRITE_VIEW_FLAGS = ["-c", "worktree.useRelativePaths=false", "-c", "protocol.allow=never", "-c", "core.splitIndex=false"];
-/** Whether the checkout's .lfsconfig (read as git parses it, that file only) sets any git-lfs key that could name a
- * program (anything but INERT_LFS). A file that
- * isn't a plain one, or doesn't parse, counts as naming one. */
 export function lfsExtensionIn(checkout, gitFile = "git", limit) {
     const path = join(checkout, ".lfsconfig");
     try {
@@ -1123,14 +921,8 @@ export function lfsExtensionIn(checkout, gitFile = "git", limit) {
     const parsed = spawnSync(gitFile, ["config", "--file", path, "--no-includes", "--name-only", "--list", "-z"], { cwd: "/", encoding: "utf8", timeout: setupTimeout(limit), killSignal: "SIGKILL", env: { PATH: process.env["PATH"] ?? "", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", HOME: "/nonexistent" } });
     return parsed.status !== 0 || parsed.stdout.split("\0").filter(Boolean).some(name => lfsCommand(name) || ["include", "includeif"].includes(keyParts(name).section));
 }
-/** The hardened runners' own reads before the caller's command (the checkout's config listing): their own bounds, never
- * the caller's. A caller's small `maxBuffer` is for its own command's output (builder.ts reads one ls-tree line with
- * 2 KiB): inherited, it failed the config listing once a project's .git/config grew past 2 KiB (one [branch] section per
- * work branch), and every prepared release check then failed as "its config couldn't be read" (runs 3316–3324). */
 export const CONFIG_READ_BYTES = 16 * 1024 * 1024;
 export const CONFIG_READ_MS = 30_000;
-/** What of a caller's options an internal read keeps: where it runs and with what environment and containment —
- * never its time limit, output limit, stdin or output callbacks. */
 function internalOptions(options, env) {
     const { cwd, envAllowlist, omitEnv, fence, fenceGrants, confinement, processGroup, owner, signal } = options ?? {};
     return { ...(cwd === undefined ? {} : { cwd }), ...(envAllowlist === undefined ? {} : { envAllowlist }), ...(omitEnv === undefined ? {} : { omitEnv }),
@@ -1138,29 +930,21 @@ function internalOptions(options, env) {
         ...(processGroup === undefined ? {} : { processGroup }), ...(owner === undefined ? {} : { owner }), ...(signal === undefined ? {} : { signal }),
         env, timeoutMs: CONFIG_READ_MS, maxBuffer: CONFIG_READ_BYTES };
 }
-/** Why the checkout's config listing failed, in words, for the refusal: git's own first line, or what stopped it. */
 function listingFailure(result) {
     if (result.timedOut)
         return `its config couldn't be read (the read ran past ${CONFIG_READ_MS / 1000} s)`;
     const said = `${result.stderr}`.split("\n").map(line => line.trim()).find(line => line !== "");
     return `its config couldn't be read${said === undefined ? ` (git exited ${result.code})` : ` (${said.slice(0, 300)})`}`;
 }
-/** Every command runs against a view of the checkout's repository (gitView) whose config and info are copies the
- * plane made, inspected there, so neither can change between the inspection and the run. `mode` "read" is for reading
- * a checkout an agent may still be writing (the code page): every command also takes readFlags(), and the view holds
- * no info/attributes. "build" is the plane's staging and committing of a build's work, which writes the repository
- * through the view (gitView). */
 export function checkoutGit(inner = run, mode = "build", binding = {}) {
     return async (file, args, options) => {
         if (file !== "git")
             return inner(file, args, options);
         const cwd = options?.cwd;
-        // In the console, a checkout whose folder hasn't answered a look lately is not read on its thread (folder-gate.ts).
         if (cwd !== undefined && !folderAnswers(cwd))
             return refused(FOLDER_DIDNT_ANSWER);
         if (cwd === undefined || checkoutIncludes(cwd))
             return refused("the checkout's git config includes another file, or couldn't be read as a plain file");
-        // git-lfs also reads .lfsconfig from the checkout: one that names an extension (a command it would run) is refused.
         if (lfsExtensionIn(cwd))
             return refused("the checkout's .lfsconfig sets a git-lfs key that can run a command");
         const once = async () => {
@@ -1173,21 +957,16 @@ export function checkoutGit(inner = run, mode = "build", binding = {}) {
             }
             try {
                 const viewed = { ...options, env: { ...(options?.env ?? {}), ...view.env } };
-                // The checkout's own config may name no command. Read with this runner's own bounds (internalOptions).
                 const own = await inner("git", ["--no-optional-locks", "config", "--list", "--show-scope", "-z"], internalOptions(options, viewed.env));
                 if (own.code !== 0)
                     return refused(listingFailure(own));
                 const key = commandSetting(own.stdout, { lfsChecked: true });
                 if (key !== null)
                     return refused(`the checkout's git config sets ${key}, which can run a command`);
-                // A git without --no-lazy-fetch: a repository that could fetch lazily is refused, from the view's frozen config.
                 if (!lazyFetchSupported() && lazyFetchSetting(own.stdout) !== null)
                     return refused(PARTIAL_CLONE_REFUSAL);
-                // The operator's own config contributes values only (carriedSettings); git then reads no global or system config.
-                // A read carries no filter: it reads attributes from the empty tree anyway.
                 const carried = mode === "read" ? withoutFilters(carriedSettings(own.stdout)) : carriedSettings(own.stdout);
                 const env = { ...viewed.env, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null" };
-                // Never into a submodule or nested repository, whose own config this never read: status and diff skip them.
                 const safeArgs = withoutUnsupportedFlags(args);
                 const command = safeArgs.findIndex(arg => arg === "status" || arg === "diff");
                 if (command >= 0 && !safeArgs.includes("--ignore-submodules=all"))
@@ -1205,7 +984,6 @@ export function checkoutGit(inner = run, mode = "build", binding = {}) {
         };
         if (mode !== "build")
             return once();
-        // A write, one at a time on a checkout (git-views.ts withCheckoutLock: re-entrant along one call chain).
         try {
             return await withCheckoutLock(realpathSync(homedir()), realpathSync(cwd), once);
         }
@@ -1215,30 +993,13 @@ export function checkoutGit(inner = run, mode = "build", binding = {}) {
     };
 }
 const withoutFilters = (carried) => carried.filter((one, at, all) => !(one.startsWith("filter.") || (one === "-c" && all[at + 1]?.startsWith("filter."))));
-/**
- * Flags for reading a checkout an agent writes while a page waits (docs/plans/get-side-effects.md). Command-line
- * settings win over anything the checkout's config says, even one changed after it was inspected: no fsmonitor, hooks,
- * pager or credential helper; no network (lazy fetch off, every protocol refused); and attributes read from the empty
- * tree, so no filter or textconv a .gitattributes names can run. A diff also takes --no-ext-diff --no-textconv.
- */
 export const PAGE_READ_FLAGS = [
     "--no-lazy-fetch", "--attr-source=4b825dc642cb6eb9a060e54bf8d69288fbee4904",
     "-c", "protocol.allow=never", "-c", "core.pager=cat", "-c", "core.alternateRefsCommand=", "-c", "core.attributesFile=/dev/null",
 ];
-/** The read flags, for every read of an agent-written checkout, whatever the HTTP method (security review of
- * 01bf3114): the worktree's attributes come from the empty tree. Git still reads the repository's info/attributes and
- * its config as it starts, so the flags alone don't stop a filter planted in both after the inspection: every read
- * also runs against a view of the checkout's repository (gitView; checkoutGitSync, checkoutGit "read"), whose config and info are the plane's. The cost is cosmetic: a checkout's line-ending or encoding rules are not applied, so
- * a file they would normalize can read as changed (fail closed: shipping then asks for a clean commit). */
 export function readFlags(gitFile = "git") {
     return lazyFetchSupported(gitFile) ? PAGE_READ_FLAGS : PAGE_READ_FLAGS.filter(flag => flag !== "--no-lazy-fetch");
 }
-/**
- * checkoutGit, synchronously, for reads a page shows from a checkout an agent writes (docs/plans/get-side-effects.md):
- * the same refusals (an include, an .lfsconfig extension, a config key that can run a command), no system or global
- * config, the operator's own values carried, PAGE_READ_FLAGS and a view of the checkout's repository (gitView: they hold even if its config
- * or info/attributes change after they were read), submodules skipped, bounded. A refusal throws.
- */
 export function checkoutGitSync(cwd, args, options = {}) {
     const ran = viewedGitSync(cwd, args, options);
     if (ran.status !== 0)
@@ -1247,14 +1008,11 @@ export function checkoutGitSync(cwd, args, options = {}) {
 }
 export function viewedGitSync(cwd, args, options = {}) {
     const gitFile = options.git ?? "git";
-    // `deadline` (absolute, wall-clock ms): every subprocess here, setup included, gets only what is left of it, and an
-    // expired deadline throws before the next one starts or after the last one ran.
     const deadline = options.deadline;
     const limit = deadline === undefined ? undefined : () => deadline - Date.now();
     const expire = () => { if (limit !== undefined && limit() <= 0)
         throw new Error("the read's deadline passed"); };
     expire();
-    // In the console, a checkout whose folder hasn't answered a look lately is not read on its thread (folder-gate.ts).
     if (!folderAnswers(cwd))
         throw new Error(FOLDER_DIDNT_ANSWER);
     if (checkoutIncludes(cwd, gitFile, limit))
@@ -1263,13 +1021,11 @@ export function viewedGitSync(cwd, args, options = {}) {
     if (lfsExtensionIn(cwd, gitFile, limit))
         throw new Error("the checkout's .lfsconfig sets a git-lfs key that can run a command");
     expire();
-    // Its config and info/attributes as read once, in a folder of the plane's own: neither can change before git runs.
     const view = gitView(cwd, "read", options.binding, gitFile, limit);
     try {
         const env = { PATH: process.env["PATH"] ?? "", HOME: process.env["HOME"] ?? "", LANG: "C", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_TERMINAL_PROMPT: "0", ...view.env };
         const timeoutNow = () => { expire(); return limit === undefined ? options.timeoutMs ?? 60_000 : Math.max(1, Math.min(options.timeoutMs ?? 60_000, limit())); };
         const fixed = { cwd, env, encoding: "utf8", killSignal: "SIGKILL", maxBuffer: options.maxBuffer ?? 1_048_576, stdio: ["ignore", "pipe", "pipe"] };
-        // Its own bounds, never the caller's output limit (CONFIG_READ_BYTES); a caller's deadline still holds.
         const own = spawnSync(gitFile, ["--no-optional-locks", "config", "--list", "--show-scope", "-z"], { ...fixed, maxBuffer: CONFIG_READ_BYTES,
             timeout: limit === undefined ? CONFIG_READ_MS : Math.max(1, Math.min(CONFIG_READ_MS, limit())) });
         if (own.status !== 0)
@@ -1277,21 +1033,17 @@ export function viewedGitSync(cwd, args, options = {}) {
         const key = commandSetting(own.stdout, { lfsChecked: true });
         if (key !== null)
             throw new Error(`the checkout's git config sets ${key}, which can run a command`);
-        // A git without --no-lazy-fetch: a repository that could fetch lazily is refused, from the view's frozen config.
         if (!lazyFetchSupported(gitFile) && lazyFetchSetting(own.stdout) !== null)
             throw new Error(PARTIAL_CLONE_REFUSAL);
         const safeArgs = withoutUnsupportedFlags(args, gitFile);
         const command = safeArgs.findIndex(arg => arg === "status" || arg === "diff");
         if (command >= 0 && !safeArgs.includes("--ignore-submodules=all"))
             safeArgs.splice(command + 1, 0, "--ignore-submodules=all");
-        // An external diff program is named by config, which may change after it was read: never used here.
         if (command >= 0 && safeArgs[command] === "diff")
             safeArgs.splice(command + 1, 0, "--no-ext-diff", "--no-textconv");
-        // The operator's own values, but no filter: PAGE_READ_FLAGS reads attributes from the empty tree anyway.
         const carried = withoutFilters(carriedSettings(own.stdout));
         const argv = [...TEARDOWN_FLAGS, ...readFlags(gitFile), "-c", "diff.ignoreSubmodules=all", ...carried, ...safeArgs];
         if (options.buffer === true) {
-            // stdin is the caller's own bytes when given (cat-file --batch), else closed.
             const ran = spawnSync(gitFile, argv, { ...fixed, timeout: timeoutNow(), encoding: "buffer", ...(options.input === undefined ? {} : { input: options.input, stdio: ["pipe", "pipe", "pipe"] }) });
             const why = view.settle();
             if (why !== null)
@@ -1310,12 +1062,6 @@ export function viewedGitSync(cwd, args, options = {}) {
         view.dispose();
     }
 }
-/**
- * checkoutGit ("build": the repository written through its view) for callers that name the repository with a leading
- * `git -C <dir>` instead of a cwd: worktree add and remove in a project's repository, a merge in a checkout of it.
- * The project's repository is shared with every build, which can write its config, info and hooks; nothing here runs
- * what they name. Anything but git goes to `inner` as given.
- */
 export function hardenedGit(inner = run, mode = "build", binding = {}) {
     const hardened = checkoutGit(inner, mode, binding);
     return (file, args, options) => {
@@ -1330,15 +1076,8 @@ export function hardenedGit(inner = run, mode = "build", binding = {}) {
         return hardened("git", rest, { ...options, ...(cwd === undefined ? {} : { cwd }) });
     };
 }
-/**
- * Git older than 2.45 has no `--no-lazy-fetch` (and no GIT_NO_LAZY_FETCH): there, every hardened read leaves the flag
- * out and instead refuses a repository whose config makes lazy fetching possible (lazyFetchSetting), while
- * `protocol.allow=never` stays on every read and write, so a lazy fetch that slipped past would still find no
- * transport. Asked once per process, as the plane's other plain git probes run: no system or global config.
- */
 const lazyFetchByGit = new Map();
 let lazyFetchOverride;
-/** The git executable `file` names, as the real path it runs (a bare name looked up on PATH), or `file` itself. */
 function gitExecutablePath(file) {
     const candidates = file.includes("/") ? [file] : (process.env["PATH"] ?? "").split(delimiter).filter(dir => isAbsolute(dir)).map(dir => join(dir, file));
     for (const candidate of candidates) {
@@ -1346,12 +1085,10 @@ function gitExecutablePath(file) {
             accessSync(candidate, fsConstants.X_OK);
             return realpathSync(candidate);
         }
-        catch { /* next */ }
+        catch { }
     }
     return file;
 }
-/** Asked once per git executable (eval-harness review 2, follow-up): a fixed git given to viewedGitSync is probed
- * itself, never answered for by the one PATH names. */
 export function lazyFetchSupported(gitFile = "git") {
     if (lazyFetchOverride !== undefined)
         return lazyFetchOverride;
@@ -1365,23 +1102,12 @@ export function lazyFetchSupported(gitFile = "git") {
     }
     return known;
 }
-/** For tests: forget the probes' answers, or set one for every executable (null forgets). */
 export function setLazyFetchSupportedForTest(value) { lazyFetchOverride = value ?? undefined; lazyFetchByGit.clear(); }
-/** The words for a partial clone refused on a git without `--no-lazy-fetch`. */
 export const PARTIAL_CLONE_REFUSAL = "this project is a partial clone; protected reads need git 2.45 or newer";
-/** `--no-lazy-fetch` where the installed git has it, else nothing (and lazyFetchSetting refuses partial clones). */
 export function noLazyFetch() { return lazyFetchSupported() ? ["--no-lazy-fetch"] : []; }
-/** A caller's own arguments with `--no-lazy-fetch` taken out when the installed git doesn't know it. */
 function withoutUnsupportedFlags(args, gitFile = "git") {
     return lazyFetchSupported(gitFile) ? [...args] : args.filter(arg => arg !== "--no-lazy-fetch");
 }
-/**
- * The repository setting (local or worktree scope of a `git config --list --show-scope -z` listing) that makes lazy
- * fetching possible, or null: `extensions.partialClone` set at all, any `remote.<name>.promisor` not plainly false, or
- * any `remote.<name>.partialCloneFilter` set (git makes that remote a promisor). Fails closed: a listing that can't be
- * read names a setting. `remote.<name>.vcs` (a foreign-VCS helper) is named too, though the classifier already refuses
- * it (commandSetting: not in the remote allowlist), as it does every `protocol.*` key and every include.
- */
 export function lazyFetchSetting(listing) {
     try {
         const fields = listing.split("\0");
@@ -1407,23 +1133,9 @@ export function lazyFetchSetting(listing) {
         return "a setting that couldn't be read";
     }
 }
-/**
- * For the reads that run git directly on a repository rather than through a view: with `--no-lazy-fetch` they run as
- * they always have (the flag stops any fetch). Without it, they must not check a repository's config and then run git
- * on it (the config could change in between, or an include could set what the check never saw): `inner`, wrapped so
- * every git command runs through a frozen read view (checkoutGit "read"), whose own config listing (includes refused,
- * command and protocol settings refused, a partial clone refused) is the config git then runs with.
- */
 export function lazyFetchSafeGit(inner = run) {
-    // On every git version (eval-harness review 1, finding 7): with --no-lazy-fetch the direct read still took the
-    // repository's config and its includes as git found them, and an include naming a FIFO could hang the plane.
     return checkoutGit(inner, "read");
 }
-/**
- * The checkout a folder sits in, for choosing a folder (easy-start): the nearest parent holding a `.git`, then read
- * through checkoutGitSync, so a config that includes another file (a FIFO), or sets a command, is refused and the read
- * is bounded. Null when there is no checkout or it can't be read that way.
- */
 export function checkoutTop(dir, timeoutMs = 10_000) {
     let at;
     try {