toolroll 0.9.93 → 0.9.94

package/dist/release-next.js

@@ -0,0 +1,161 @@
+/**
+ * What `toolroll release <branch>` does before its journal's next step (docs/plans/plain-toolroll.md P2.6): one command,
+ * so a person never chooses between --recover-deploy, --release-gate and rerunning.
+ *
+ * - **Another run**: a run lock per branch, by host and pid. A live one is waited for, named; two coordinators never act
+ *   on one release at once. A lock whose process is proved gone on this host is taken over.
+ * - **A deployment left open**: the journal decides. Before the swap: its pause is lifted, once proved. Past the new
+ *   service's start: forward, by the release. Between: rolled back through its own recovery. Each of those re-proves
+ *   itself, so a crash at any phase ends the same on the next run.
+ */
+import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, writeSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { FORWARD_ONLY, rescueDeployment } from "./deploy-rescue.js";
+import { BEFORE_SWAP, releaseGate } from "./release-gate.js";
+import { journalFile, readJournal } from "./release.js";
+import { autoPublishHeld, PUBLISH_ALLOWED_ACTION } from "./release-auto.js";
+import { sameMachineHost } from "./machine-identity.js";
+const lockFile = (stateDir, branch) => journalFile(stateDir, branch).replace(/\.json$/, ".running");
+/** How long a run waits for another before it says so and stops. */
+export const RELEASE_WAIT_MS = 30 * 60_000;
+const processAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+function readHolder(file) {
+    try {
+        const read = JSON.parse(readFileSync(file, "utf8"));
+        return typeof read.host === "string" && Number.isSafeInteger(read.pid) ? { host: read.host, pid: read.pid } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Take this branch's run lock, waiting for a live holder. Answers how to give it back, or who kept it. */
+export async function takeReleaseRun(stateDir, branch, say, seams = {}) {
+    const file = lockFile(stateDir, branch);
+    const host = seams.host ?? hostname(), pid = seams.pid ?? process.pid;
+    const alive = seams.alive ?? processAlive, sleep = seams.sleep ?? (ms => new Promise(done => setTimeout(done, ms)));
+    const now = seams.now ?? Date.now;
+    const deadline = now() + (seams.waitMs ?? RELEASE_WAIT_MS);
+    mkdirSync(dirname(file), { recursive: true });
+    let said = false;
+    for (;;) {
+        try {
+            const fd = openSync(file, "wx", 0o600);
+            try {
+                writeSync(fd, JSON.stringify({ host, pid }));
+            }
+            finally {
+                closeSync(fd);
+            }
+            return { ok: true, release: () => { const mine = readHolder(file); if (mine?.pid === pid && mine.host === host)
+                    rmSync(file, { force: true }); } };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const holder = readHolder(file);
+        // A lock with no readable holder, or a process proved gone on this computer, holds nothing. Another computer's can't
+        // be proved gone from here, so it is waited for.
+        if (holder === null || (sameMachineHost(holder.host, host) && !alive(holder.pid))) {
+            rmSync(file, { force: true });
+            continue;
+        }
+        if (!said) {
+            say(`Waiting: another release of ${branch} is running on ${holder.host} (process ${holder.pid}).`);
+            said = true;
+        }
+        if (now() >= deadline)
+            return { ok: false, holder };
+        await sleep(seams.pollMs ?? 5_000);
+    }
+}
+/** The one action a deployment's journal calls for. */
+export function deployActionOf(phase) {
+    if (typeof phase !== "string")
+        return "refuse";
+    if (phase === "released" || phase === "deployed")
+        return "none";
+    if (BEFORE_SWAP.includes(phase))
+        return "lift-pause";
+    if (FORWARD_ONLY.includes(phase))
+        return "forward";
+    return "roll-back";
+}
+/** Settle what a stopped deployment left, saying what was done. A refusal stops the release before it does anything. */
+export async function settleDeployment(world, say) {
+    const open = world.rescue.journals().filter(one => deployActionOf(one.journal?.["phase"]) !== "none");
+    if (open.length === 0)
+        return { ok: true };
+    if (open.length > 1)
+        return { ok: false, message: `${open.length} deployments are unfinished: ${open.map(one => one.stage).join(", ")}. Nothing was changed.` };
+    const { stage, journal } = open[0];
+    const action = deployActionOf(journal?.["phase"]);
+    if (action === "refuse")
+        return { ok: false, message: `The deployment journal in ${stage} can't be read. Nothing was changed.` };
+    if (action === "forward") {
+        say("Finishing the deployment that was under way.");
+        return { ok: true };
+    }
+    if (action === "lift-pause") {
+        const lifted = releaseGate(String(journal?.["id"] ?? ""), world.gate, true);
+        if (!lifted.ok)
+            return { ok: false, message: lifted.message };
+        say("Lifted the pause an unfinished deployment left before its swap.");
+        return { ok: true };
+    }
+    const back = await rescueDeployment(stage, true, world.rescue);
+    if (!back.ok)
+        return { ok: false, message: back.message };
+    say("Put back the deployment that stopped half way.");
+    return { ok: true };
+}
+// ---- a held release resumes itself -----------------------------------------------------------------------------------
+export const RELEASE_RESUMED_ACTION = "release resumed";
+/**
+ * A person let a held release go on (release-auto.ts allowAutoPublish; the Release sheet's button or `publish-ok`): each
+ * sweep, its journal goes on from where it stopped, once per that person's act, under the same run lock. It was merged
+ * already, so only the tag, publication and Homebrew are left, and each re-proves itself.
+ */
+export async function resumeAllowedReleases(store, stateDir, run, now) {
+    let folder;
+    try {
+        folder = readdirSync(join(stateDir, "releases")).filter(name => name.endsWith(".json") && !name.includes(".superseded-"));
+    }
+    catch {
+        return 0;
+    }
+    let resumed = 0;
+    for (const name of folder) {
+        const journal = readJournal(join(stateDir, "releases", name));
+        if (journal === null || !["tag", "publish", "homebrew"].includes(journal.step) || autoPublishHeld(store, journal.task.id) !== null)
+            continue;
+        const allowed = store.handle.prepare("SELECT id FROM action_ledger WHERE task_id = ? AND action = ? ORDER BY id DESC LIMIT 1").get(journal.task.id, PUBLISH_ALLOWED_ACTION);
+        if (allowed === undefined)
+            continue;
+        // Once per act: a resume that stops again waits for a person, never for the next sweep.
+        const done = store.handle.prepare("SELECT 1 AS hit FROM action_ledger WHERE task_id = ? AND action = ? AND outcome = ?").get(journal.task.id, RELEASE_RESUMED_ACTION, String(allowed["id"]));
+        if (done !== undefined)
+            continue;
+        const taken = await takeReleaseRun(stateDir, journal.branch, () => { }, { waitMs: 0 });
+        if (!taken.ok)
+            continue;
+        try {
+            store.recordAction({ at: now.toISOString(), actor: "system", repo: store.lookupRef(journal.task.id)?.repo ?? null, taskId: journal.task.id, runId: null, action: RELEASE_RESUMED_ACTION, outcome: String(allowed["id"]), source: "work", detail: journal.tag });
+            await run(journal);
+            resumed++;
+        }
+        finally {
+            taken.release();
+        }
+    }
+    return resumed;
+}

package/dist/release.d.ts

@@ -77,7 +77,9 @@ export declare const RELEASE_TAG_WORKFLOW = ".github/workflows/publish.yml";
 export declare const RELEASE_STEPS: readonly ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
 export type ReleaseStep = typeof RELEASE_STEPS[number];
 type WaitingStep = "gate" | "approval" | "check" | "quiet" | "deploy" | "ci" | "publish" | "homebrew";
-/** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
+/** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). The
+ * check's covers the first attempt and the two same-commit reruns the plane may give it, each of which a busy machine
+ * may stretch to two hours (check-load.ts). */
 export declare const RELEASE_LIMITS: Readonly<Record<WaitingStep, number>>;
 /** One check attempt; `app` is the GitHub App that made it (github-actions for a workflow), when known; `id` its check
  * run id, `suite` its check suite (one workflow run: its re-runs stay in it) and `head` the commit GitHub filed it
@@ -332,6 +334,15 @@ export type ReleaseAuthorityAdapter = {
         why: string;
         warning: string | null;
     }>;
+    /** Whether a sandboxed Full check's skipped cases are covered (fenced-check-coverage.ts, H3). Run `run`'s stamped level
+     * decides: an unsandboxed check answers at once. Absent: a plane that can't say, as for every older one. */
+    fencedCoverage?(taskId: string, run: number, candidate: string): Promise<{
+        ok: true;
+        covered: number;
+    } | {
+        ok: false;
+        why: string;
+    }>;
     /** One-tap release approval (docs/plans/trusted-release-reports.md, slice A): what the plane tells a person and
      * keeps for the approval sheet. Best effort: a failure here never changes the release. Absent on an older plane. */
     ready?: ReleaseReadyAdapter;
@@ -536,6 +547,14 @@ export type ReleaseAdapters = {
         mainHead(repo: string): Promise<string>;
         /** Whether `sha` already holds `ancestor`, by GitHub's own comparison. */
         contains(repo: string, sha: string, ancestor: string): Promise<boolean>;
+        /** Bring a pull request's branch up to main, only while its head is `expectedHead` (GitHub's own compare-and-swap: a
+         * push that got there first refuses). Absent: a behind branch stops, for a person to update. */
+        updateBranch?(repo: string, pr: number, expectedHead: string): Promise<{
+            ok: true;
+        } | {
+            ok: false;
+            why: string;
+        }>;
         /** Whether GitHub refuses to merge a branch that is behind main ("Require branches to be up to date before
          * merging"); null when it can't be read. Read only. */
         upToDateRequired(repo: string): Promise<MainProtection | null>;

package/dist/release.js

@@ -101,8 +101,10 @@ export const ADVISORY_PR_CHECKS = {
 export const RELEASE_TAG_CHECKS = ["release proof", "publish"];
 export const RELEASE_TAG_WORKFLOW = ".github/workflows/publish.yml";
 export const RELEASE_STEPS = ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
-/** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
-export const RELEASE_LIMITS = { gate: 60, approval: 24 * 60, check: 120, quiet: 60, deploy: 30, ci: 60, publish: 45, homebrew: 45 };
+/** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). The
+ * check's covers the first attempt and the two same-commit reruns the plane may give it, each of which a busy machine
+ * may stretch to two hours (check-load.ts). */
+export const RELEASE_LIMITS = { gate: 60, approval: 24 * 60, check: 360, quiet: 60, deploy: 30, ci: 60, publish: 45, homebrew: 45 };
 const POLL_MS = 15_000;
 /**
  * Failure classes replace a flat flake allowance (docs/plans/eval-harness.md; check-failure.ts says the classes): only a
@@ -129,9 +131,12 @@ class HomebrewFailed extends Error {
 /** The branch moved before the deploy reservation: carry the approval to the new head, or file it for a person. */
 class Restart extends Error {
     head;
-    constructor(head) {
+    updated;
+    /** `updated`: Toolroll itself brought the branch up to main; the new commit is a new candidate and nothing carries. */
+    constructor(head, updated = false) {
         super(`restart at ${head}`);
         this.head = head;
+        this.updated = updated;
     }
 }
 /** Every commit that landed after the approval, in words: the summary and the merge message list them all. */
@@ -626,11 +631,41 @@ export async function runRelease(options, adapters) {
         /** identity(), on a plane that keeps release authority; a legacy plane keeps the old rules. */
         const watch = async (action) => { if (rel !== undefined)
             await identity(action, true); };
-        const restart = async (head) => {
+        /**
+         * Behind main (plain-toolroll.md P2.6): update the branch under this release's lease and the head it was gated on.
+         * A concurrent push aborts it. The approval stops first, so nothing can ride it across the update; the updated head
+         * is a new candidate with a new approval, fresh CI and a fresh check, and there is no carry.
+         */
+        const updateFromMain = async () => {
+            const update = adapters.github.updateBranch;
+            if (update === undefined)
+                return null;
+            if (rel !== undefined && j.authority) {
+                if (epoch === null || !await rel.renew(j.authority.id, owner, epoch))
+                    throw new Stop("lease", "Another release coordinator took over this release.");
+            }
+            const pr = await adapters.github.pullRequest(j.github, j.branch);
+            if (pr === null || pr.number !== j.pr || pr.state !== "open" || pr.head !== j.candidate.sha)
+                throw new Stop("drift", `${j.branch} moved while it was being brought up to main. Nothing was changed; rerun \`${resume}\`.`);
+            if (rel !== undefined && j.authority && !await rel.needsApproval(j.authority.id, "the branch was brought up to main, so its new commit needs a fresh approval", epoch)) {
+                throw new Stop("lease", "The release's approval couldn't be stopped before the update, so the branch wasn't updated.");
+            }
+            say(`  ${j.branch} is behind main: bringing it up to date`);
+            const moved = await update(j.github, j.pr, j.candidate.sha);
+            if (!moved.ok)
+                throw new Stop("drift", `${j.branch} couldn't be brought up to main: ${moved.why}. Rerun \`${resume}\`.`);
+            return waitFor("ci", `${j.branch} to move past ${j.candidate.sha.slice(0, 7)}`, async () => {
+                const head = await adapters.repo.remoteHead(j.branch);
+                return head !== null && head !== j.candidate.sha ? head : null;
+            });
+        };
+        const restart = async (head, updated = false) => {
             // The step this commit was at ends here: the release goes on with the new commit (and, filed again, a new task).
             mark(j.step, "failed", `${j.branch} moved to ${head.slice(0, 7)}`);
             const tree = await adapters.repo.tree(head);
-            if (rel !== undefined && j.authority && epoch !== null) {
+            if (updated)
+                say(`  ${j.branch} is at ${head.slice(0, 7)}: a new commit, so it needs its own approval, CI and check`);
+            else if (rel !== undefined && j.authority && epoch !== null) {
                 say(`  ${j.branch} moved to ${head.slice(0, 7)}: checking whether the approval carries`);
                 const carried = await rel.carry(j.authority.id, head, randomUUID(), epoch);
                 if (carried.ok) {
@@ -808,7 +843,17 @@ export async function runRelease(options, adapters) {
                         }
                         // The tree CI tested (the pull request's head, not GitHub's merge commit) is the tree that merges only when the
                         // branch already contains main's head: refused here, before anything is filed, and again right before merging.
-                        await containsMain(adapters, j, "Nothing was filed or sent for approval");
+                        try {
+                            await containsMain(adapters, j, "Nothing was filed or sent for approval");
+                        }
+                        catch (error) {
+                            if (!(error instanceof Stop) || error.reason !== "base-moved")
+                                throw error;
+                            const head = await updateFromMain();
+                            if (head === null)
+                                throw error;
+                            throw new Restart(head, true);
+                        }
                         if (j.intents.gate === undefined)
                             await mainProtection(adapters, j, false, "Nothing was filed or sent for approval");
                         const existing = await adapters.toolroll.gate(j.task.id);
@@ -963,6 +1008,15 @@ export async function runRelease(options, adapters) {
                                 else if (standing.retried.length > 0)
                                     say(`  run ${gate.result.run} passed, but only on a retry: ${standing.retried.join(", ")}`);
                             }
+                            // A sandboxed Full check must show that what it skipped passed elsewhere (trusted-release-reports.md H3). The plane
+                            // answers at once for a check that ran unsandboxed, as Toolroll's own do: nothing there skips for this reason.
+                            if (rel?.fencedCoverage !== undefined) {
+                                const covered = await rel.fencedCoverage(j.task.id, gate.result.run, j.candidate.sha);
+                                if (!covered.ok)
+                                    throw new Stop("check-failed", `Run ${gate.result.run} passed on ${j.candidate.sha.slice(0, 7)}, but ${covered.why}.`);
+                                if (covered.covered > 0)
+                                    say(`  ${covered.covered} cases skipped inside the sandbox passed in this commit's macOS CI`);
+                            }
                             return { run: gate.result.run, receipt: gate.result.receipt, worktree: gate.result.worktree, head };
                         };
                         const result = await waitFor("check", `the release check of ${j.candidate.sha.slice(0, 7)}`, async () => {
@@ -1175,7 +1229,21 @@ export async function runRelease(options, adapters) {
                                 await identity("merge", false);
                             await pinned();
                             // A squash merge only reproduces the gated (and CI-tested) tree when main hasn't moved past the branch's base.
-                            const main = await containsMain(adapters, j, "Nothing was merged");
+                            let main;
+                            try {
+                                main = await containsMain(adapters, j, "Nothing was merged");
+                            }
+                            catch (error) {
+                                if (!(error instanceof Stop) || error.reason !== "base-moved")
+                                    throw error;
+                                // Past the deploy: the updated commit isn't what's running, so it starts over, with a person.
+                                const head = await updateFromMain();
+                                if (head === null)
+                                    throw error;
+                                j.needsApproval = true;
+                                save();
+                                throw new Stop("approval", `${j.branch} was behind main, so it's now at ${head.slice(0, 7)}. Nothing was merged. The new commit needs a person's approval: run \`toolroll release ${j.branch} --repo ${j.checkout} --new\`.`);
+                            }
                             // Every release merges only where GitHub itself refuses a branch behind main.
                             await mainProtection(adapters, j, j.auto?.state === "approved", "Nothing was merged");
                             // The checks again, at the moment of merging: a rerun that failed since must not merge.
@@ -1290,7 +1358,7 @@ export async function runRelease(options, adapters) {
             catch (error) {
                 if (!(error instanceof Restart))
                     throw error;
-                await restart(error.head);
+                await restart(error.head, error.updated);
             }
         }
         const left = homebrewLeft;

package/dist/remote-destination.d.ts

@@ -0,0 +1,36 @@
+export type Lookup = (host: string) => Promise<readonly string[]>;
+export declare const lookupAll: Lookup;
+export type Destination = {
+    scheme: "https" | "ssh";
+    host: string;
+    port: number;
+    literal: boolean;
+};
+export type Pin = {
+    /** `-c` settings for git, or nothing for ssh. */
+    gitArgs: string[];
+    /** Environment on top of remote-main.ts's ENV. */
+    env: Record<string, string>;
+    /** The proxy's host name when the read goes through the operator's proxy. */
+    proxy: string | null;
+};
+export type PinResult = {
+    ok: true;
+    pin: Pin;
+} | {
+    ok: false;
+    why: string;
+};
+/** Whether an address is loopback, unspecified, link-local, or an IPv4-mapped or NAT64 form of these. */
+export declare function addressRefused(address: string): boolean;
+/** The host, effective port and scheme a recorded URL connects to; null when it can't be read. The caller has already
+ * passed remoteUrlProblem. Node's URL parser normalizes every spelling of a literal host. */
+export declare function destinationOf(url: string): Destination | null;
+/** Whether curl would skip the proxy for this host; "unknown" when an entry can't be decided. */
+export declare function noProxyApplies(noProxy: string, host: string): boolean | "unknown";
+/**
+ * Decide the route and pin it. `env` is what git will see (the names remote-main.ts's ENV_ALLOWLIST passes). ssh never
+ * uses a proxy. Through a proxy, the proxy's own address is checked and pinned; the operator's proxy then chooses the
+ * final destination, and the caller says so.
+ */
+export declare function pinDestination(url: string, env: Readonly<Record<string, string | undefined>>, lookup?: Lookup): Promise<PinResult>;

package/dist/remote-destination.js

@@ -0,0 +1,217 @@
+/**
+ * Where a read of a recorded remote really connects, worked out and pinned before git runs (docs/plans/code-map.md §1).
+ * remote-main.ts's URL rules look at a host's spelling; a name can still resolve to this machine. Here the name is
+ * resolved once, every address is checked, and git is told to use exactly the checked address. Routing is decided from
+ * the same environment git gets. Anything that can't be decided or pinned refuses with a reason: there is no fallback to
+ * an unpinned read.
+ */
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+export const lookupAll = async (host) => (await dnsLookup(host, { all: true, verbatim: true })).map(one => one.address);
+const UNDECIDED = "Toolroll can't tell how this connection would be routed";
+const NOT_ALLOWED = "its address isn't one Toolroll connects to";
+/** The eight 16-bit groups of an IPv6 address; null when it isn't one. */
+function hextets(address) {
+    let text = address.toLowerCase().replace(/%.*$/, "");
+    const dotted = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+    if (dotted !== null) {
+        const parts = dotted[1].split(".").map(Number);
+        if (parts.some(part => part > 255))
+            return null;
+        text = `${text.slice(0, dotted.index)}${((parts[0] << 8) | parts[1]).toString(16)}:${((parts[2] << 8) | parts[3]).toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const left = halves[0] === "" ? [] : halves[0].split(":");
+    const right = halves.length === 1 || halves[1] === "" ? [] : halves[1].split(":");
+    const gap = 8 - left.length - right.length;
+    if (halves.length === 1 ? gap !== 0 : gap < 1)
+        return null;
+    const groups = [...left, ...Array(halves.length === 1 ? 0 : gap).fill("0"), ...right].map(one => parseInt(one, 16));
+    return groups.length === 8 && groups.every(one => Number.isInteger(one) && one >= 0 && one <= 0xffff) ? groups : null;
+}
+const refusedV4 = (address) => {
+    const [a, b] = address.split(".").map(Number);
+    return a === 127 || a === 0 || (a === 169 && b === 254);
+};
+const v4Of = (high, low) => `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+/** Whether an address is loopback, unspecified, link-local, or an IPv4-mapped or NAT64 form of these. */
+export function addressRefused(address) {
+    const family = isIP(address);
+    if (family === 4)
+        return refusedV4(address);
+    if (family !== 6)
+        return true;
+    const g = hextets(address);
+    if (g === null)
+        return true;
+    const top = g.slice(0, 5).every(one => one === 0);
+    if (top && g[5] === 0 && g[6] === 0 && (g[7] === 0 || g[7] === 1))
+        return true; // :: and ::1
+    if ((g[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10
+    if (top && g[5] === 0xffff)
+        return refusedV4(v4Of(g[6], g[7])); // ::ffff:a.b.c.d
+    if (top && g[5] === 0)
+        return refusedV4(v4Of(g[6], g[7])); // ::a.b.c.d (deprecated compatible form)
+    if (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every(one => one === 0))
+        return refusedV4(v4Of(g[6], g[7])); // 64:ff9b::/96
+    return false;
+}
+/** The host, effective port and scheme a recorded URL connects to; null when it can't be read. The caller has already
+ * passed remoteUrlProblem. Node's URL parser normalizes every spelling of a literal host. */
+export function destinationOf(url) {
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(url)?.[1]?.toLowerCase();
+    let host, port;
+    if (scheme === "https" || scheme === "ssh") {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return null;
+        }
+        host = parsed.hostname.replace(/^\[(.*)\]$/, "$1");
+        port = parsed.port === "" ? (scheme === "https" ? 443 : 22) : Number(parsed.port);
+        return validDestination(scheme, host, port);
+    }
+    if (scheme !== undefined)
+        return null;
+    const colon = url.indexOf(":");
+    if (colon <= 0)
+        return null;
+    host = url.slice(0, colon).replace(/^.*@/, "");
+    return validDestination("ssh", host, 22);
+}
+function validDestination(scheme, host, port) {
+    const literal = isIP(host) !== 0;
+    if (!literal && !/^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?\.?$/.test(host))
+        return null;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    return { scheme, host, port, literal };
+}
+async function checkedAddress(host, literal, lookup) {
+    if (literal)
+        return addressRefused(host) ? { ok: false, why: NOT_ALLOWED } : { ok: true, address: host };
+    let found;
+    try {
+        found = await lookup(host);
+    }
+    catch {
+        return { ok: false, why: "its host name couldn't be resolved" };
+    }
+    if (found.length === 0)
+        return { ok: false, why: "its host name couldn't be resolved" };
+    // Every address, not just the first: a name that also answers with this machine isn't connected to.
+    if (found.some(addressRefused))
+        return { ok: false, why: NOT_ALLOWED };
+    return { ok: true, address: found[0] };
+}
+const curlPin = (host, port, address) => ["-c", `http.curloptResolve=${host}:${port}:${isIP(address) === 6 ? `[${address}]` : address}`];
+/** One NO_PROXY entry against a host, as curl compares them; "unknown" for anything Toolroll won't second-guess. */
+function noProxyMatch(entry, host) {
+    const raw = entry.replace(/^\[(.*)\]$/, "$1");
+    if (raw === "*")
+        return true;
+    const hostIp = isIP(host);
+    const cidr = /^(.+)\/(\d+)$/.exec(raw);
+    if (cidr !== null) {
+        if (isIP(cidr[1]) === 0)
+            return "unknown";
+        if (hostIp === 0)
+            return false;
+        if (hostIp !== isIP(cidr[1]))
+            return false;
+        const bits = Number(cidr[2]);
+        if (hostIp === 4) {
+            if (bits > 32)
+                return "unknown";
+            const value = (ip) => ip.split(".").reduce((n, part) => n * 256 + Number(part), 0);
+            const size = 2 ** (32 - bits);
+            return Math.floor(value(host) / size) === Math.floor(value(cidr[1]) / size);
+        }
+        return "unknown";
+    }
+    if (isIP(raw) !== 0)
+        return hostIp !== 0 && (hextets(raw)?.join() ?? raw) === (hextets(host)?.join() ?? host);
+    if (/[^A-Za-z0-9.-]/.test(raw))
+        return "unknown";
+    if (hostIp !== 0)
+        return false;
+    const name = raw.replace(/^\.+/, "").replace(/\.+$/, "").toLowerCase();
+    const wanted = host.replace(/\.+$/, "").toLowerCase();
+    return name !== "" && (wanted === name || wanted.endsWith(`.${name}`));
+}
+/** Whether curl would skip the proxy for this host; "unknown" when an entry can't be decided. */
+export function noProxyApplies(noProxy, host) {
+    let unknown = false;
+    for (const entry of noProxy.split(/[,\s]+/).filter(Boolean)) {
+        const hit = noProxyMatch(entry, host);
+        if (hit === true)
+            return true;
+        if (hit === "unknown")
+            unknown = true;
+    }
+    return unknown ? "unknown" : false;
+}
+const envOf = (env, lower, upper) => {
+    const low = env[lower];
+    return low !== undefined && low !== "" ? low : env[upper] ?? "";
+};
+/** The proxy curl would use from `https_proxy`/`HTTPS_PROXY`: http or https schemes only (a SOCKS proxy resolves names
+ * on its side, in ways this can't see). */
+function proxyOf(value) {
+    const text = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(value) ? value : `http://${value}`;
+    let parsed;
+    try {
+        parsed = new URL(text);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return null;
+    const host = parsed.hostname.replace(/^\[(.*)\]$/, "$1");
+    const port = parsed.port === "" ? (parsed.protocol === "https:" ? 443 : 1080) : Number(parsed.port);
+    const literal = isIP(host) !== 0;
+    if (host === "" || (!literal && !/^[A-Za-z0-9.-]+$/.test(host)))
+        return null;
+    return { host, port, literal };
+}
+/**
+ * Decide the route and pin it. `env` is what git will see (the names remote-main.ts's ENV_ALLOWLIST passes). ssh never
+ * uses a proxy. Through a proxy, the proxy's own address is checked and pinned; the operator's proxy then chooses the
+ * final destination, and the caller says so.
+ */
+export async function pinDestination(url, env, lookup = lookupAll) {
+    const target = destinationOf(url);
+    if (target === null)
+        return { ok: false, why: UNDECIDED };
+    if (target.scheme === "ssh") {
+        const checked = await checkedAddress(target.host, target.literal, lookup);
+        if (!checked.ok)
+            return checked;
+        return { ok: true, pin: { gitArgs: [], proxy: null, env: { GIT_SSH_COMMAND: `ssh -o BatchMode=yes -o ProxyCommand=none -o ProxyJump=none -o HostName=${checked.address} -o Port=${target.port} -o HostKeyAlias=${target.host} -o CheckHostIP=no` } } };
+    }
+    const proxyValue = envOf(env, "https_proxy", "HTTPS_PROXY");
+    if (proxyValue !== "") {
+        const skip = noProxyApplies(envOf(env, "no_proxy", "NO_PROXY"), target.host);
+        if (skip === "unknown")
+            return { ok: false, why: UNDECIDED };
+        if (!skip) {
+            const proxy = proxyOf(proxyValue);
+            if (proxy === null)
+                return { ok: false, why: UNDECIDED };
+            const checked = await checkedAddress(proxy.host, proxy.literal, lookup);
+            if (!checked.ok)
+                return { ok: false, why: `your proxy's ${checked.why.replace(/^its /, "")}` };
+            return { ok: true, pin: { gitArgs: curlPin(proxy.host, proxy.port, checked.address), env: {}, proxy: proxy.host } };
+        }
+    }
+    const checked = await checkedAddress(target.host, target.literal, lookup);
+    if (!checked.ok)
+        return checked;
+    return { ok: true, pin: { gitArgs: curlPin(target.host, target.port, checked.address), env: {}, proxy: null } };
+}

package/dist/remote-main.d.ts

@@ -1,4 +1,6 @@
 import { type ExecResult } from "./exec.js";
+import type { BoundedOptions, BoundedResult, BoundedRunner } from "./bounded-spawn.js";
+import type { Pin } from "./remote-destination.js";
 import type { Store } from "./store.js";
 import type { Runner } from "./worktree.js";
 /** What the private directory's git may see of this process's environment: nothing that names a repository, an
@@ -40,7 +42,13 @@ export type RemoteMainRead = {
 } | {
     ok: false;
     why: string;
+    reason?: "moved";
 };
+/** What every reader of a remote main shows when its address redirects. The target is remote-supplied text: it is never
+ * shown, stored or followed, and the new remote is never adopted automatically. */
+export declare const REMOTE_MOVED = "The repository moved: its address now redirects. Update the project's remote in Toolroll (Settings \u2192 Projects), then try again.";
+/** git's words for a refused redirect (http.followRedirects=false), read for the status code alone. */
+export declare function redirected(stderr: string): boolean;
 /**
  * One pass's reads of recorded remotes. Every `read` fetches again (the pre-teardown re-check is never older than
  * the teardown); a project's private directory lasts until `close`, so a fetch after the first only brings what
@@ -61,3 +69,43 @@ export declare class RemoteMains {
     read(repo: string): Promise<RemoteMainRead>;
     close(): void;
 }
+export declare const MAP_FETCH_LIMITS: {
+    readonly timeoutMs: 120000;
+    readonly memoryBytes: number;
+    readonly diskBytes: number;
+    readonly fileBytes: number;
+    readonly maxStderr: number;
+};
+export type MapGitOptions = {
+    helper?: string;
+    extra?: readonly string[];
+};
+/** Git in a private directory under the map's rules: the same hardening as `RemoteMains`, plus the pin. */
+export declare function mapGitArgs(dir: string, pin: Pin, args: readonly string[], options?: MapGitOptions): string[];
+/** The environment for it: exactly the allowed names, the fixed settings, and the pin's. */
+export declare function mapGitEnv(pin: Pin, from?: Readonly<Record<string, string | undefined>>): Record<string, string>;
+export declare function initPrivateDir(dir: string, bounded: BoundedRunner): Promise<BoundedResult>;
+export type MapPeek = {
+    ok: true;
+    commit: string | null;
+} | {
+    ok: false;
+    why: string;
+    reason?: "moved";
+};
+/** The commit the recorded remote's main is at, without fetching: null when the remote has no `main`. */
+export declare function peekMain(url: string, dir: string, pin: Pin, bounded: BoundedRunner, helper?: string): Promise<MapPeek>;
+/** A depth-1 private folder is clean when it holds only what the fetch made: a `shallow` file naming exactly the fetched
+ * commit, and no grafts or alternates. */
+export declare function shallowClean(dir: string, commit: string): boolean;
+export type MapFetch = {
+    ok: true;
+    commit: string;
+    enforced: "system" | "checked";
+} | {
+    ok: false;
+    why: string;
+    reason?: "moved";
+};
+/** Fetch main at depth 1 into `dir`, under the map's limits. `onStart` records the spawn for crash cleanup. */
+export declare function readShallowMain(url: string, dir: string, pin: Pin, bounded: BoundedRunner, onStart?: BoundedOptions["onStart"], helper?: string): Promise<MapFetch>;