toolroll 0.9.75 → 0.9.77

package/dist/dispose.js

@@ -455,7 +455,10 @@ export function regateTask(store, taskId, now, approval) {
     if (scope === null)
         return { ok: false, reason: "no-attempt", message: `${taskId} has no scope` };
     const head = last.headRevision;
-    const actor = approval.kind === "operator" ? approval.name : `mode ${approval.name}`;
+    const actor = approval.kind === "operator" ? approval.name : approval.kind === "release" ? approval.name : `mode ${approval.name}`;
+    if (approval.kind === "release" && ((scope.candidate ?? null) === null || (scope.releaseTerms ?? null) === null)) {
+        return { ok: false, reason: "not-approved", message: `${taskId} isn't a release candidate; only a release reruns under its own approval` };
+    }
     // A prepared candidate (a release gate, the nightly check) already names the approved commit, and the builder loads
     // exactly its tree on every attempt. The rerun keeps that scope and its approval as they are: nothing is proposed or
     // sealed again, so a regate can never swap the approved commit, its release terms or the person's yes for others
@@ -481,7 +484,7 @@ export function regateTask(store, taskId, now, approval) {
                     return { ok: false, reason: why[queued.reason] ?? "not-rejected", message: `${taskId} could not be queued again: ${queued.reason}` };
                 }
             }
-            store.addRunNote(last.id, "Toolroll", `The check will run again on the approved commit ${candidate.slice(0, 7)}, under the same approval, as a new attempt, ${approval.kind === "operator" ? `on ${approval.name}'s say-so` : "automatically once, because the failure was outside this change"}.`, now);
+            store.addRunNote(last.id, "Toolroll", `The check will run again on the approved commit ${candidate.slice(0, 7)}, under the same approval, as a new attempt, ${approval.kind === "operator" ? `on ${approval.name}'s say-so` : approval.kind === "release" ? "because Toolroll confirmed the failure was its own infrastructure, not the code" : "automatically once, because the failure was outside this change"}.`, now);
             return { ok: true, run: last.id, head: candidate };
         });
     }
@@ -494,7 +497,7 @@ export function regateTask(store, taskId, now, approval) {
         let sealed = false;
         if (approval.kind === "operator")
             sealed = approve(store, taskId, approval.name, now, proposed.digest, approval.token).ok;
-        else
+        else if (approval.kind === "mode")
             sealed = store.sealScopeApproval(taskId, actor, now, {}, { kind: "mode", modeDigest: approval.modeDigest });
         if (!sealed)
             return { ok: false, reason: "not-approved", message: `${taskId}'s rerun scope could not be approved` };

package/dist/doctor.d.ts

@@ -24,6 +24,11 @@ export type DoctorReport = {
         version: string;
         problem: string | null;
     };
+    /** The installed git against Toolroll's floor (git-floor.ts): null when it is new enough (or unreadable). */
+    git?: {
+        floor: string;
+        problem: string | null;
+    };
 };
 export type DoctorDeps = {
     platform?: NodeJS.Platform;
@@ -35,6 +40,8 @@ export type DoctorDeps = {
     procRoot?: string;
     /** The doctor's own environment: the terminal a `toolroll up` would start from. */
     env?: NodeJS.ProcessEnv;
+    /** The installed git's floor problem (a test's stand-in for git-floor.ts installedGitFloorProblem). */
+    gitFloorProblem?: string | null;
 };
 /** The names among `pairs` that hold a credential: a provider key, a credential-looking name, or a key-shaped value.
  * Values are only tested here and never leave. */

package/dist/doctor.js

@@ -21,6 +21,7 @@ import { join } from "node:path";
 import { daemonStatus, installedServiceDefinition, planDaemon } from "./daemon.js";
 import { scanForSecrets } from "./evidence.js";
 import { envelopeJson } from "./envelope.js";
+import { GIT_FLOOR_WORDS, installedGitFloorProblem } from "./git-floor.js";
 import { run as runCommand } from "./exec.js";
 import { OWN_KEY_ENV } from "./keys.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
@@ -123,7 +124,8 @@ function reinstallCommand(args) {
         const flag = equal < 0 ? arg : arg.slice(0, equal);
         const value = equal < 0 ? args[index + 1] : arg.slice(equal + 1);
         const known = freeform.has(flag) || numeric.has(flag) || Object.hasOwn(enums, flag);
-        if (equal < 0 && (known || CREDENTIAL_FLAG.test(flag)) && value !== undefined && !value.startsWith("-"))
+        // A credential's value is the next argument even when it starts with "-" (random base64url can).
+        if (equal < 0 && value !== undefined && (CREDENTIAL_FLAG.test(flag) || (known && !value.startsWith("-"))))
             index += 1;
         if (flag === "--token") {
             kept.push("--token-file", "<set-again>");
@@ -386,7 +388,9 @@ export async function auditServiceEnvironment(deps = {}) {
 /** The report as the owner reads it: one state, then each finding with its steps; detail after. */
 export function doctorLines(report) {
     const lines = [];
-    if (report.ok)
+    if (report.git?.problem != null)
+        lines.push(`Git: ${report.git.problem}`, "");
+    if (report.findings.length === 0 && report.unreadable.length === 0)
         lines.push("No secrets found in Toolroll's service. A build can't read a key from it.");
     else if (report.findings.length > 0)
         lines.push(`Toolroll's service holds ${report.findings.length === 1 ? "a secret" : "secrets"} a build could read. Nothing was changed; follow these steps.`);
@@ -422,6 +426,10 @@ export async function runDoctorCommand(argv, write, deps = {}) {
     }
     const report = await auditServiceEnvironment(deps);
     report.sandbox = { engine: SANDBOX_RUNTIME.name, version: SANDBOX_RUNTIME.version, problem: sandboxRuntimeProblem() };
+    // A git older than the floor: named here too, and the console and worker won't start on it.
+    report.git = { floor: GIT_FLOOR_WORDS, problem: deps.gitFloorProblem === undefined ? installedGitFloorProblem() : deps.gitFloorProblem };
+    if (report.git.problem !== null)
+        report.ok = false;
     if (json)
         write(envelopeJson({ command: "doctor", ...report }));
     else

package/dist/envelope.js

@@ -74,7 +74,8 @@ export const DOCUMENTED_REASONS = [
     "drift", //             the branch, pull request or result moved from the gated commit
     "check-failed", //      the release check failed; it stays visible and nothing reruns it
     "ci-failed", //         a required pull-request check failed or is missing — nothing merged
-    "base-moved", //        main gained a commit the release branch lacks — nothing merged
+    "git-too-old", //       the installed git is older than Toolroll's floor (git-floor.ts) — serve, watch and up don't start
+    "base-moved", //        the release branch lacks main's head — nothing filed (gate) or merged
     "tree-mismatch", //     main's merge commit has a different tree than the gated commit — nothing tagged
     "conflict", //          a task or tag exists for a different commit
     "mixed-runtime", //     the console, worker and CLI names don't run one build

package/dist/evidence.js

@@ -23,6 +23,7 @@ import { parseReport, REPORT_LIMITS } from "./scout-report.js";
 import { parseProof, PROOF_LIMITS } from "./proof.js";
 import { HANDOFF_VERSION, readHandoffArtifact } from "./contracts/handoff.js";
 import { encodeBaseTreeSnapshot, parseBaseTreeSnapshot } from "./peek.js";
+import { noLazyFetch } from "./teardown-git.js";
 /** The park mailbox pattern. Each run's actual name carries a nonce; see `mailboxName`. */
 export const MAILBOX_PREFIX = "STANDING-ORDERS-PARK-";
 /** The terminal handoff: how every non-parking attempt says how it ended. */
@@ -929,7 +930,9 @@ export async function captureBaseTree(store, git, repoRoot, repo, base, root, ru
     }
 }
 async function captureBaseTreeInner(store, git, repoRoot, repo, base, root, runId, now) {
-    const args = ["--no-lazy-fetch", "--no-replace-objects", "--no-optional-locks", "ls-tree", "-r", "-l", "-z", base];
+    const args = [...noLazyFetch(), "-c", "protocol.allow=never", "--no-replace-objects", "--no-optional-locks", "ls-tree", "-r", "-l", "-z", base];
+    // `git` is the builder's hardened checkout git (a frozen view): on a git without --no-lazy-fetch it refuses a partial
+    // clone from the same config it runs with (teardown-git.ts lazyFetchSetting).
     const listed = await git("git", args, { cwd: repoRoot, envAllowlist: ["PATH", "HOME"] });
     const command = `git ls-tree -r -l -z ${base} (exit ${listed.code})`;
     const refuse = () => {

package/dist/exec.d.ts

@@ -28,6 +28,13 @@ export type ExecResult = {
      * returned — a transport exit alone never proves that.
      */
     containment?: ContainmentOutcome;
+    /** The signal that ended the process, when one did (its `code` then reads 1, as it always has): kept apart so a
+     * killed command is never mistaken for one that exited 1 on its own (release check 3261). Only the buffered
+     * process-group transport says. */
+    signal?: NodeJS.Signals | null;
+    /** This process (the plane) ended it with its hard stop (terminateLiveProviders: a worker shutting down), not
+     * anything the command or another process did. */
+    stoppedByPlane?: boolean;
 };
 export type ContainmentOutcome = {
     refused: string;

package/dist/exec.js

@@ -21,6 +21,8 @@ import { primaryResultEvent, topLevelEvent } from "./stream-scope.js";
 export const CONTAINMENT_REFUSED_CODE = 126;
 /** Live provider children, for the deterministic stop. Registered only when `processGroup` was set. */
 const liveProviders = new Set();
+/** Children this process's own hard stop ended: their results say so (`stoppedByPlane`). */
+const hardStopped = new WeakSet();
 /** Live children by owner tag (v52): the exact-attempt stop's handle. A
  * child is registered here beside liveProviders when its options named an
  * owner, and dropped the moment it closes. */
@@ -370,6 +372,7 @@ function killGroup(child) {
 export function terminateLiveProviders() {
     let terminated = 0;
     for (const child of liveProviders) {
+        hardStopped.add(child);
         killGroup(child);
         terminated += 1;
     }
@@ -677,6 +680,7 @@ function runBufferedGroup(file, args, bag) {
         });
         let settled = false;
         let transient = false;
+        let endSignal = null;
         const finish = (code) => {
             if (settled)
                 return;
@@ -697,6 +701,8 @@ function runBufferedGroup(file, args, bag) {
                         timedOut: timedOut && !overflowed,
                         notFound,
                         ...containmentOf(container, empty, attachFailure),
+                        ...(endSignal === null ? {} : { signal: endSignal }),
+                        ...(hardStopped.has(child) ? { stoppedByPlane: true } : {}),
                     },
                     transient,
                 });
@@ -709,7 +715,7 @@ function runBufferedGroup(file, args, bag) {
                 stderr = String(error);
             finish(null);
         });
-        child.on("close", code => finish(code));
+        child.on("close", (code, signal) => { endSignal = code === null ? signal ?? null : null; finish(code); });
         if (bag.stdin !== undefined && child.stdin !== null) {
             child.stdin.on("error", () => {
                 inputFailed = true;

package/dist/first-run.js

@@ -6,6 +6,7 @@
  * the composer: nothing is filed until the person sends it and confirms.
  */
 import { run } from "./exec.js";
+import { hardenedGit } from "./teardown-git.js";
 import { githubIssues } from "./issues.js";
 export const SIGN_IN_COMMAND = "claude auth login";
 export const SANDBOX_COMMAND = "npx toolroll demo";
@@ -95,7 +96,8 @@ export async function findFirstTasks(repo, runner = run) {
     let todos = [];
     if (issues.length < 3) {
         try {
-            const result = await runner("git", [...TODO_GREP_ARGS], { cwd: repo, timeoutMs: 5_000 });
+            // The project's repository is shared with builds that can write its config: the hardened read (teardown-git.ts).
+            const result = await (runner === run ? hardenedGit(run, "read") : runner)("git", [...TODO_GREP_ARGS], { cwd: repo, timeoutMs: 5_000 });
             if (result.code === 0 || result.stdout !== "")
                 todos = parseTodoLines(result.stdout);
         }

package/dist/git-floor.d.ts

@@ -0,0 +1,16 @@
+export declare const GIT_FLOOR: {
+    readonly major: 2;
+    readonly minor: 41;
+};
+export declare const GIT_FLOOR_WORDS: string;
+/** The version `git --version` names ("git version 2.50.1 (Apple Git-155)" → 2.50.1), or null when it names none. */
+export declare function parseGitVersion(text: string): {
+    major: number;
+    minor: number;
+    words: string;
+} | null;
+/** Why `version` (`git --version`'s answer) is below the floor, in one sentence, or null when it isn't (or can't be read). */
+export declare function gitFloorWords(versionText: string): string | null;
+/** The installed git's floor problem, asked once per process with no system or global config; null when git is new
+ * enough, or when no version could be read (a missing git is reported where it is used). */
+export declare function installedGitFloorProblem(): string | null;

package/dist/git-floor.js

@@ -0,0 +1,36 @@
+/**
+ * The oldest git Toolroll runs on (README, Requirements): the global `git --attr-source` option every hardened read
+ * takes arrived in git 2.41 (others in use are older: `worktree list -z` 2.36, GIT_CONFIG_COUNT and `--path-format`
+ * 2.31). On git older than 2.45, which lacks `--no-lazy-fetch`, partial clones are refused for protected reads
+ * (teardown-git.ts lazyFetchSupported), every protected read runs through a frozen view and refuses every transport,
+ * and nothing leans on GIT_NO_LAZY_FETCH, which 2.41.0 ignores. The CI git lanes test this floor's oldest release
+ * exactly, 2.41.0, and 2.47 (.github/workflows/ci.yml, scripts/ci-git.sh).
+ */
+import { spawnSync } from "node:child_process";
+export const GIT_FLOOR = { major: 2, minor: 41 };
+export const GIT_FLOOR_WORDS = `${GIT_FLOOR.major}.${GIT_FLOOR.minor}`;
+/** The version `git --version` names ("git version 2.50.1 (Apple Git-155)" → 2.50.1), or null when it names none. */
+export function parseGitVersion(text) {
+    const found = /^git version (\d+)\.(\d+)(?:\.(\d+))?/.exec(text.trim());
+    return found === null ? null : { major: Number(found[1]), minor: Number(found[2]), words: `${found[1]}.${found[2]}${found[3] === undefined ? "" : `.${found[3]}`}` };
+}
+/** Why `version` (`git --version`'s answer) is below the floor, in one sentence, or null when it isn't (or can't be read). */
+export function gitFloorWords(versionText) {
+    const version = parseGitVersion(versionText);
+    if (version === null)
+        return null;
+    if (version.major > GIT_FLOOR.major || (version.major === GIT_FLOOR.major && version.minor >= GIT_FLOOR.minor))
+        return null;
+    return `Toolroll needs git ${GIT_FLOOR_WORDS} or newer, and this machine's git is ${version.words}. Install a newer git (and put it first on PATH), then start Toolroll again.`;
+}
+let probed;
+/** The installed git's floor problem, asked once per process with no system or global config; null when git is new
+ * enough, or when no version could be read (a missing git is reported where it is used). */
+export function installedGitFloorProblem() {
+    if (probed === undefined) {
+        const answer = spawnSync("git", ["--version"], { cwd: "/", encoding: "utf8", timeout: 5_000, stdio: ["ignore", "pipe", "ignore"],
+            env: { PATH: process.env["PATH"] ?? "", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", HOME: "/nonexistent" } });
+        probed = answer.status === 0 ? gitFloorWords(answer.stdout ?? "") : null;
+    }
+    return probed;
+}

package/dist/git-incident.d.ts

@@ -0,0 +1,49 @@
+export type GitIncident = {
+    at: string;
+    checkout: string;
+    repository: string;
+    /** Folders of the repository found swapped, and where each now leads (null: its pointers changed instead). */
+    swapped: {
+        path: string;
+        leadsTo: string | null;
+    }[];
+};
+type Listener = (incident: GitIncident) => void;
+/** Hear about every git incident (returns the unsubscribe). With none registered, incidents go to stderr. */
+export declare function onGitIncident(listener: Listener): () => void;
+/** Record and tell one incident. */
+export declare function gitIncident(input: {
+    checkout: string;
+    repository: string;
+    swapped: GitIncident["swapped"];
+    record: string;
+}): GitIncident;
+/** What noticeGitIncidents needs of the store: its durable outbox, and its own project records. */
+export type IncidentOutbox = {
+    enqueueNotification(notification: {
+        dedupeKey: string;
+        kind: string;
+        subject: string;
+        body: string;
+        pushClass?: "attention";
+        source?: {
+            project: string;
+        } | {
+            installation: true;
+        };
+    }, now: Date): boolean;
+    listProjects(): {
+        path: string;
+        name: string;
+    }[];
+};
+/**
+ * Every git incident from now on raises an attention notification in `outbox` (the console and the background worker
+ * register their store as they start; once per store): "Git incident in <project>: a folder of its repository changed
+ * while Toolroll's git ran". Nothing the agent chose reaches the text (paths in an agent-written repository can carry
+ * newlines and words of its own): the project is named only by the plane's own record of it (matched by real path,
+ * else "a project"), and the person is pointed to the incident record file, where the paths are. Returns the
+ * unsubscribe.
+ */
+export declare function noticeGitIncidents(outbox: IncidentOutbox, now?: () => Date, record?: string): () => void;
+export {};

package/dist/git-incident.js

@@ -0,0 +1,69 @@
+/**
+ * A git incident: the plane's own git wrote through a view of a repository (teardown-git.ts gitView) while a folder of
+ * that repository the view links to was swapped for a link elsewhere, or its git pointers changed (the residual the
+ * view can't prevent: git takes paths, and a build that outlived its turn can still rename a folder of the shared
+ * `.git` mid-command). Seen after git ran, it is:
+ *
+ * - recorded, one JSON line in `~/.toolroll/git-incidents.jsonl` (beside the fenced views folder, git-views.ts);
+ * - told to every listener (the console's, when it registers one; otherwise the plane's stderr);
+ * - and the command is reported refused, so no caller takes its result as done.
+ *
+ * Nothing is rolled back automatically: where a swapped folder leads is the agent's choice, and the plane never runs
+ * git there on its say (a confused deputy); what git wrote is for a person, named in the record.
+ */
+import { appendFileSync, realpathSync } from "node:fs";
+import { basename, dirname } from "node:path";
+const listeners = new Set();
+/** Hear about every git incident (returns the unsubscribe). With none registered, incidents go to stderr. */
+export function onGitIncident(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+/** Record and tell one incident. */
+export function gitIncident(input) {
+    const incident = { at: new Date().toISOString(), checkout: input.checkout, repository: input.repository, swapped: input.swapped };
+    try {
+        appendFileSync(input.record, `${JSON.stringify(incident)}\n`, { mode: 0o600 });
+    }
+    catch { /* still told */ }
+    if (listeners.size === 0)
+        process.stderr.write(`Toolroll git incident: ${JSON.stringify(incident)}\n`);
+    for (const listener of listeners) {
+        try {
+            listener(incident);
+        }
+        catch { /* every listener hears it */ }
+    }
+    return incident;
+}
+const noticed = new WeakSet();
+/**
+ * Every git incident from now on raises an attention notification in `outbox` (the console and the background worker
+ * register their store as they start; once per store): "Git incident in <project>: a folder of its repository changed
+ * while Toolroll's git ran". Nothing the agent chose reaches the text (paths in an agent-written repository can carry
+ * newlines and words of its own): the project is named only by the plane's own record of it (matched by real path,
+ * else "a project"), and the person is pointed to the incident record file, where the paths are. Returns the
+ * unsubscribe.
+ */
+export function noticeGitIncidents(outbox, now = () => new Date(), record = "~/.toolroll/git-incidents.jsonl") {
+    if (noticed.has(outbox))
+        return () => { };
+    noticed.add(outbox);
+    const stop = onGitIncident(incident => {
+        const main = basename(incident.repository) === ".git" ? dirname(incident.repository) : incident.repository;
+        const real = (path) => { try {
+            return realpathSync(path);
+        }
+        catch {
+            return null;
+        } };
+        const known = outbox.listProjects().find(project => real(project.path) !== null && real(project.path) === real(main)) ?? null;
+        outbox.enqueueNotification({
+            dedupeKey: `git-incident:${incident.at}:${known?.path ?? "unrecorded"}`, kind: "git-incident", pushClass: "attention",
+            source: known === null ? { installation: true } : { project: known.path },
+            subject: `Git incident in ${known === null ? "a project" : known.name}: a folder of its repository changed while Toolroll's git ran`,
+            body: `Toolroll stopped trusting that git command and changed nothing more. Nothing was rolled back: check the repository by hand. The checkout and the folders that changed are in ${record}.`,
+        }, now());
+    });
+    return () => { stop(); noticed.delete(outbox); };
+}

package/dist/git-views.d.ts

@@ -0,0 +1,20 @@
+/** The views folder under `home`. */
+export declare function gitViewsRoot(home: string): string;
+/**
+ * The views folder under `home`, made if it isn't there (owner-only), and proven to be this user's own real folder all
+ * the way from `home`: neither it nor `~/.toolroll` may be a link or anyone else's. Throws otherwise.
+ */
+export declare function ensureGitViewsRoot(home: string): string;
+/**
+ * One plane git command at a time on a checkout (Codex review of a0fa135d): each command's private GIT_DIR has its own
+ * HEAD, so two at once would each take their own HEAD lock and the later carry-back would undo the earlier. The lock
+ * is a file the plane makes exclusively in the fenced views folder, named by the checkout's real path, holding this
+ * process's id; one whose process is gone is taken over. Waits up to `timeoutMs`; returns the release.
+ */
+export declare function lockCheckout(home: string, checkout: string, timeoutMs?: number): Promise<() => void>;
+/**
+ * Run `work` holding the checkout's lock (lockCheckout). Re-entrant along one call chain: a hardened git nested in
+ * another on the same checkout (teardown's git run through the builder's hardened runner, a view within a view) runs
+ * under the lock its caller already holds instead of waiting on itself.
+ */
+export declare function withCheckoutLock<T>(home: string, checkout: string, work: () => Promise<T>): Promise<T>;

package/dist/git-views.js

@@ -0,0 +1,120 @@
+/**
+ * Where the plane makes its private views of a repository for git (teardown-git.ts gitView): a folder of its own under
+ * the home folder's `~/.toolroll`, which every fence denies to builds, read and write (agent-fence.ts agentFence names
+ * this folder by name, made first so no build can be the one to create it). A view in the system temp folder could be
+ * rewritten by a build that writes anywhere and outlived its turn (Codex review of e48e9d8d).
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+import { closeSync, constants as fsConstants, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeSync } from "node:fs";
+import { join } from "node:path";
+/** The views folder under `home`. */
+export function gitViewsRoot(home) {
+    return join(home, ".toolroll", "git-views");
+}
+/**
+ * The views folder under `home`, made if it isn't there (owner-only), and proven to be this user's own real folder all
+ * the way from `home`: neither it nor `~/.toolroll` may be a link or anyone else's. Throws otherwise.
+ */
+export function ensureGitViewsRoot(home) {
+    const uid = process.getuid?.();
+    const base = join(home, ".toolroll");
+    const root = gitViewsRoot(home);
+    for (const dir of [base, root]) {
+        try {
+            mkdirSync(dir, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const held = lstatSync(dir);
+        if (!held.isDirectory() || held.isSymbolicLink() || (uid !== undefined && held.uid !== uid))
+            throw new Error(`${dir} isn't a folder of this user's own`);
+    }
+    return root;
+}
+/**
+ * One plane git command at a time on a checkout (Codex review of a0fa135d): each command's private GIT_DIR has its own
+ * HEAD, so two at once would each take their own HEAD lock and the later carry-back would undo the earlier. The lock
+ * is a file the plane makes exclusively in the fenced views folder, named by the checkout's real path, holding this
+ * process's id; one whose process is gone is taken over. Waits up to `timeoutMs`; returns the release.
+ */
+export async function lockCheckout(home, checkout, timeoutMs = 10 * 60_000) {
+    const folder = join(ensureGitViewsRoot(home), "locks");
+    try {
+        mkdirSync(folder, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const held = lstatSync(folder);
+    if (!held.isDirectory() || held.isSymbolicLink())
+        throw new Error(`${folder} isn't a folder of this user's own`);
+    const path = join(folder, `${createHash("sha256").update(checkout).digest("hex")}.lock`);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 0o600);
+            try {
+                writeSync(fd, `${process.pid}\n`);
+            }
+            finally {
+                closeSync(fd);
+            }
+            let released = false;
+            return () => { if (!released) {
+                released = true;
+                rmSync(path, { force: true });
+            } };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        // Held: by a live process, wait; by one that is gone, take it over.
+        let owner = NaN;
+        try {
+            owner = Number(readFileSync(path, "utf8").trim());
+        }
+        catch {
+            owner = NaN;
+        }
+        if (Number.isSafeInteger(owner) && owner > 0 && owner !== process.pid && !alive(owner)) {
+            rmSync(path, { force: true });
+            continue;
+        }
+        if (Date.now() > deadline)
+            throw new Error("another of Toolroll's git commands on this checkout is still running");
+        await new Promise(done => setTimeout(done, 25));
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** The checkouts the current async call chain already holds (lockCheckout through withCheckoutLock). */
+const heldHere = new AsyncLocalStorage();
+/**
+ * Run `work` holding the checkout's lock (lockCheckout). Re-entrant along one call chain: a hardened git nested in
+ * another on the same checkout (teardown's git run through the builder's hardened runner, a view within a view) runs
+ * under the lock its caller already holds instead of waiting on itself.
+ */
+export async function withCheckoutLock(home, checkout, work) {
+    const held = heldHere.getStore() ?? new Set();
+    if (held.has(checkout))
+        return work();
+    const release = await lockCheckout(home, checkout);
+    try {
+        return await heldHere.run(new Set([...held, checkout]), work);
+    }
+    finally {
+        release();
+    }
+}

package/dist/grant.js

@@ -30,6 +30,7 @@
  * the same reason an unknown lease is: silence is not consent.
  */
 import { run } from "./exec.js";
+import { lazyFetchSafeGit, noLazyFetch } from "./teardown-git.js";
 export const MUTATION_CLASSES = [
     "create",
     "transition",
@@ -175,10 +176,15 @@ async function observedByGit(repo, paths, runner) {
     const local = paths.filter(path => !isRemoteRef(path));
     if (local.length === 0)
         return false;
+    // On a git without --no-lazy-fetch, through a frozen read view (teardown-git.ts lazyFetchSafeGit): a partial clone is
+    // refused there, and a refusal reads as "not ignored", so observed.
+    const git = lazyFetchSafeGit(runner);
     for (const path of local) {
         const asked = [path, `${normalise(path)}/`];
         const ignored = await Promise.all(asked.map(async (candidate) => {
-            const result = await runner("git", ["--no-optional-locks", "check-ignore", "-q", candidate], {
+            // check-ignore reads the index, so a planted fsmonitor would run: off (and hooks, lazy fetch) on the command line,
+            // which wins over any config the repository's builds can write.
+            const result = await git("git", ["--no-optional-locks", ...noLazyFetch(), "-c", "protocol.allow=never", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "check-ignore", "-q", candidate], {
                 cwd: repo,
             });
             return result.code === 0;

package/dist/guides.js

@@ -510,9 +510,10 @@ instead of making them twice.
   rerunning the failed job on GitHub, run the same command again.
 - \`publish-failed\` / \`homebrew-failed\`: fix the failed workflow before
   resuming. A failed tag check cannot finish publication or update Homebrew.
-- \`base-moved\`: main gained a commit the branch doesn't have, so the
-  merge wouldn't be the checked tree. Nothing was merged: update the
-  branch and release it with \`--new\`.
+- \`base-moved\`: the branch is behind main (it doesn't contain main's
+  head), so the merge wouldn't be the tree CI tested. Checked at the gate
+  (nothing filed) and again right before merging (nothing merged): update
+  the branch, push, and release it with \`--new\`.
 - \`tree-mismatch\`: main changed what was checked. Nothing was tagged;
   the deployed build stays.
 - \`timeout\`: rerun to keep waiting; \`--limit <step>=<minutes>\`

package/dist/operate.d.ts

@@ -6,6 +6,7 @@ import type { StepIo } from "./flow-steps.js";
 import type { FetchLike } from "./flow-share.js";
 import { type Store } from "./store.js";
 import { type DispatchAdapter } from "./sync.js";
+import { type RolePort, type UpRoleStart } from "./up-processes.js";
 import { type TelegramTransport } from "./telegram.js";
 import { type LeadCliSeams } from "./lead-cli.js";
 import { type Principal, type RemoteSource } from "./operate-remote.js";
@@ -89,6 +90,8 @@ export type OperateOptions = {
     };
     /** Injected by tests: the classifier that sizes filed tasks (none by default under test). */
     filingSizer?: Sizer;
+    /** Set only by up-role-child.ts: this process is one role of a `toolroll up` (the console or the worker). */
+    upRole?: UpRoleHost;
 };
 export type OnboardSeams = Partial<Pick<OnboardIo, "home" | "env" | "cwd" | "interactive" | "confirm" | "findRepo" | "checkConnection" | "pullRequests">>;
 export declare const OPERATE_HELP: string;
@@ -117,6 +120,8 @@ export declare const KEYS_ACTIONS: readonly ["status", "set", "clear", "verify",
  * tests): every value-taking flag any verb reads, and every boolean.
  * A --flag in neither set is a typo, refused by name.
  */
+/** Flags whose value is a secret someone types or pastes: taken as the next argument even when it starts with "--". */
+export declare const SECRET_VALUE_FLAGS: ReadonlySet<string>;
 export declare const OPERATE_VALUE_FLAGS: ReadonlySet<string>;
 export declare const OPERATE_BOOLEAN_FLAGS: ReadonlySet<string>;
 export declare function parseOperateArgs(argv: readonly string[], ownValues?: ReadonlySet<string>): Args | {
@@ -168,3 +173,11 @@ export declare function readUpConsoleUrl(dir: string): string | null;
 export declare const PROPOSALS_ACTIONS: readonly ["list", "confirm", "dismiss"];
 /** The value flags a verb reads under a global switch's name, for parseOperateArgs. */
 export declare function ownValueFlags(command: string, argv: readonly string[]): ReadonlySet<string> | undefined;
+/** What up-role-child.ts hands runOperate: the role's start, and its channel to the `up` that started it. */
+export type UpRoleHost = {
+    start: UpRoleStart;
+    port: RolePort;
+};
+/** A role child's whole run (up-role-child.ts): the ordinary command prelude (containment, secrets, limits), then the
+ * role itself. Only a process started by `up` gets here; no command line selects a role. */
+export declare function runUpRole(start: UpRoleStart, port: RolePort): Promise<number>;