toolroll 0.9.103 → 0.9.105

package/dist/public-access.js

@@ -1,17 +1,5 @@
-/**
- * Serving on a real domain (remote team, phase 3): which requests arrived safely enough to carry an API token,
- * and when the console sends Strict-Transport-Security. Pure rules over what the socket and the one trusted proxy
- * say; serve.ts applies them right after its Host check, and `toolroll serve check-public` probes for them.
- *
- * Trust comes from the socket first. Only a LOOPBACK peer is the documented same-host TLS proxy (Caddy, Cloudflare
- * Tunnel), and only then are X-Forwarded-For (its last hop, via serve.ts's joinSourceOf) and X-Forwarded-Proto
- * believed. Any other peer's forwarded headers are ignored: it reached us over plain HTTP from where it stands.
- */
-/** One year, this exact host only: no includeSubDomains, no preload, so sibling names are never pinned. */
 export const HSTS_VALUE = "max-age=31536000";
-/** What a token-bearing request over plain HTTP from elsewhere is told. */
 export const USE_HTTPS = "Use HTTPS. API tokens are accepted over plain HTTP only from this computer or your tailnet; connect with the server's https:// address.";
-/** IPv4 dotted quad from an IPv4 or IPv4-mapped IPv6 address, else null. */
 function ipv4Of(address) {
     const bare = address.replace(/^::ffff:/i, "");
     const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(bare);
@@ -20,18 +8,11 @@ function ipv4Of(address) {
     const parts = match.slice(1).map(Number);
     return parts.every(part => part <= 255) ? parts : null;
 }
-/** Strips brackets and an IPv6 zone so `[::1]` and `fe80::1%en0` compare as addresses. */
 const bareAddress = (address) => address.trim().replace(/^\[(.*)\]$/, "$1").replace(/%.*$/, "").toLowerCase();
-/**
- * The exact loopback peers serve.ts trusts as the same-host proxy (joinSourceOf, fromThisComputer). Not all of
- * 127/8: a proxy listening on 127.0.0.2 must not make public callers look like this computer.
- */
 export const LOOPBACK_PEERS = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
-/** One of LOOPBACK_PEERS (brackets, an IPv6 zone and case ignored). The only loopback test that grants trust. */
 export function isLoopbackPeer(address) {
     return LOOPBACK_PEERS.has(bareAddress(address));
 }
-/** 127.0.0.0/8, ::1 and their IPv4-mapped forms. For naming hosts only (public-check.ts); trust uses isLoopbackPeer. */
 export function isLoopbackAddress(address) {
     const bare = bareAddress(address);
     const v4 = ipv4Of(bare);
@@ -39,7 +20,6 @@ export function isLoopbackAddress(address) {
         return v4[0] === 127;
     return bare === "::1" || bare === "0:0:0:0:0:0:0:1";
 }
-/** Tailscale's ranges: 100.64.0.0/10 (and its IPv4-mapped form) and fd7a:115c:a1e0::/48. */
 export function isTailnetAddress(address) {
     const bare = bareAddress(address);
     const v4 = ipv4Of(bare);
@@ -47,16 +27,10 @@ export function isTailnetAddress(address) {
         return v4[0] === 100 && v4[1] >= 64 && v4[1] <= 127;
     return /^fd7a:115c:a1e0(:|$)/.test(bare);
 }
-/** The last value of a possibly repeated, comma-separated header (the one the trusted proxy itself set). */
 const lastValue = (header) => {
     const joined = Array.isArray(header) ? header.join(",") : header ?? "";
     return joined.split(",").pop()?.trim().toLowerCase() ?? "";
 };
-/**
- * The request's transport from its socket peer, the source serve.ts's joinSourceOf derived (`fwd:<hop>` only for a
- * loopback peer) and the proxy headers. A loopback peer that forwards with `Forwarded` but no X-Forwarded-For names
- * no caller we can read, so it is not treated as this computer.
- */
 export function transportOf(request) {
     const peer = request.peer ?? "";
     if (!isLoopbackPeer(peer)) {
@@ -69,9 +43,7 @@ export function transportOf(request) {
         return { source: "unknown", https, privatePath: false };
     return { source, https, privatePath: isLoopbackPeer(source) || isTailnetAddress(source) };
 }
-/** The OAuth endpoints that hand out, consent to or take back a token (mcp-oauth.ts; revoke is reserved). Discovery stays public. */
 export const OAUTH_TOKEN_PATHS = new Set(["/oauth/authorize", "/oauth/token", "/oauth/register", "/oauth/revoke"]);
-/** Requests that carry, or exist to carry, an API token: the remote CLI, the MCP gateway, MCP sign-in, and any bearer credential. */
 export function carriesToken(pathname, authorization) {
     if (pathname === "/api/cli" || pathname.startsWith("/api/cli/") || pathname === "/mcp" || pathname.startsWith("/mcp/"))
         return true;
@@ -79,13 +51,22 @@ export function carriesToken(pathname, authorization) {
         return true;
     return authorization !== undefined && /^bearer\s/i.test(authorization);
 }
-/** The refusal for a token sent over plain HTTP from outside this computer and the tailnet, else null. */
 export function plainHttpRefusal(transport, pathname, authorization) {
     if (transport.https || transport.privatePath)
         return null;
     return carriesToken(pathname, authorization) ? USE_HTTPS : null;
 }
-/** The Strict-Transport-Security value for a request to the configured public https host that arrived over HTTPS. */
 export function hstsFor(publicHost, host, transport) {
     return publicHost !== null && host === publicHost && transport.https ? HSTS_VALUE : null;
 }
+const PROXY_HEADER = /^(forwarded|via|x-forwarded-.+|x-real-ip|x-client-ip|x-original-.+|x-cluster-client-ip|true-client-ip|cf-connecting-ip|fastly-client-ip|x-proxyuser-ip)$/i;
+export function requestFromThisComputer(request) {
+    const peer = request.socket.remoteAddress ?? "";
+    if (!LOOPBACK_PEERS.has(peer))
+        return false;
+    for (const name of Object.keys(request.headers))
+        if (PROXY_HEADER.test(name))
+            return false;
+    const host = request.headers["host"];
+    return /^(localhost|127\.0\.0\.1|\[::1\]):[0-9]{1,5}$/.test(typeof host === "string" ? host : "");
+}

package/dist/public-check.js

@@ -1,18 +1,9 @@
-/**
- * `toolroll serve check-public` (remote team, phase 3): is this server ready to be reached on its real domain?
- * Read-only: it sends no credentials, follows no redirects and changes nothing. It checks the --public-url and
- * --allow-host values, asks the console on this computer what it does with relayed requests, then fetches the public
- * address with the platform's own certificate checks and reads what comes back. Each problem is one line saying
- * what to change.
- */
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { HSTS_VALUE, isLoopbackAddress, isTailnetAddress, USE_HTTPS } from "./public-access.js";
 const TIMEOUT_MS = 10_000;
-/** A documentation address (RFC 5737): the remote caller the local probe pretends to relay for. */
 const SAMPLE_CALLER = "203.0.113.10";
 const HOST_GRAMMAR = /^[A-Za-z0-9.-]{1,253}(:[0-9]{1,5})?$|^\[[0-9A-Fa-f:.]{2,45}\](:[0-9]{1,5})?$/;
-/** The default probe: node's http/https with the platform trust store, a timeout and a 4 KB body cap. */
 export const networkProbe = ({ url, headers }) => new Promise(resolve => {
     const target = new URL(url);
     const send = target.protocol === "https:" ? httpsRequest : httpRequest;
@@ -29,7 +20,6 @@ export const networkProbe = ({ url, headers }) => new Promise(resolve => {
     outgoing.end();
 });
 const codeOf = (error) => typeof error === "object" && error !== null && typeof error.code === "string" ? error.code : "EUNKNOWN";
-/** The exact https origin --public-url must be, as serve.ts requires it; else what is wrong with it. */
 export function publicOriginOf(value) {
     if (value === undefined)
         return "--public-url is missing. Pass the address engineers will use, like --public-url https://toolroll.example.com.";
@@ -47,7 +37,6 @@ export function publicOriginOf(value) {
     }
     return parsed;
 }
-/** Names a plain-HTTP browser can reasonably use: this computer, the tailnet, a LAN or a single-label name. */
 function privateName(host) {
     const name = host.replace(/:[0-9]{1,5}$/, "").replace(/^\[(.*)\]$/, "$1").toLowerCase();
     if (name === "localhost" || name.endsWith(".ts.net") || name.endsWith(".local") || !name.includes(".") && !name.includes(":"))
@@ -65,7 +54,6 @@ const header = (answer, name) => {
     const value = answer.headers[name];
     return Array.isArray(value) ? value.join(", ") : value;
 };
-/** The HSTS max-age a response sets, or null when it sets none. */
 const hstsAge = (value) => {
     const match = value === undefined ? null : /(?:^|;)\s*max-age\s*=\s*"?(\d+)"?/i.exec(value);
     return match === null ? null : Number(match[1]);
@@ -86,7 +74,6 @@ function certificateProblem(host, code) {
         return `The certificate for ${host} is not trusted (${code}). Use a publicly trusted certificate, such as Caddy's automatic one.`;
     return `Could not reach https://${host} (${code}).`;
 }
-/** Every problem with serving on --public-url, in a fixed order; an empty list means ready. */
 export async function checkPublic(options, probe = networkProbe) {
     const origin = publicOriginOf(options.publicUrl);
     if (typeof origin === "string")
@@ -100,7 +87,6 @@ export async function checkPublic(options, probe = networkProbe) {
             findings.push({ check: "allow-host", message: `--allow-host ${allowed} is a public name served over plain HTTP, so passwords would cross the internet unencrypted. Remove it: --public-url already admits ${host}.` });
         }
     }
-    // The console on this computer, asked as the same-host proxy would ask it.
     const local = `http://127.0.0.1:${options.port}`;
     const relayed = { host, "x-forwarded-for": SAMPLE_CALLER };
     const page = await probe({ url: `${local}/login`, headers: { ...relayed, "x-forwarded-proto": "https" } });
@@ -119,7 +105,6 @@ export async function checkPublic(options, probe = networkProbe) {
             findings.push({ check: "forwarding", message: "The server does not refuse API tokens relayed over plain HTTP from another computer. Update Toolroll." });
         }
     }
-    // The public address, with the platform's certificate checks.
     const outside = await probe({ url: `${origin.origin}/login`, headers: {} });
     if ("error" in outside) {
         findings.push({ check: "certificate", message: certificateProblem(host, outside.error) });
@@ -142,7 +127,6 @@ export async function checkPublic(options, probe = networkProbe) {
     }
     return findings;
 }
-/** The command: findings as lines (or one envelope), exit 0 when ready, 1 when not, 2 for a malformed --port. */
 export async function checkPublicCommand(flags, context) {
     const command = "serve check-public";
     const value = (name) => { const one = flags.get(name); return typeof one === "string" ? one : undefined; };

package/dist/publish.js

@@ -1,24 +1,3 @@
-/**
- * Publication (§M4): built work becomes a pushed branch and a pull request,
- * under a grant whose every term was shown before the yes, through a durable
- * intent that survives any crash between "done" and "opened".
- *
- * Two external writes, two named capabilities. Pushing a branch and opening
- * a PR hurt differently, so `push-branch` and `open-pr` are granted
- * separately, with the exact GitHub repository, remote, allowed head
- * prefix, and base branch fixed at grant time — the worker re-proves all of
- * them at publish time, because a grant revoked overnight must stop the
- * morning's pushes.
- *
- * The push names the exact SHA the fenced completion accepted —
- * `git push <remote> <sha>:refs/heads/<head>` — never "whatever the branch
- * points at now". The PR is adopt-or-create: the worker first asks GitHub
- * for an open PR on that head and adopts it, so a crash after `pr create`
- * and before the record lands cannot mint a twin. The body is generated
- * only from durable state (task, scope, run record, answered decisions),
- * with the agent's prose fenced in a quote block so `Fixes #…` or an
- * @-mention in its conclusion cannot acquire GitHub semantics.
- */
 import { createHash } from "node:crypto";
 import { protectedPublicationHold } from "./result-completion.js";
 import { fastPublishProblem } from "./fast-start.js";
@@ -30,19 +9,12 @@ import { summarizeChecks } from "./pulls.js";
 import { parseCiRollup, recordCiChecks, releasePublication } from "./store.js";
 import { headWithin } from "./names.js";
 export const BODY_TEMPLATE_VERSION = 2;
-/** After this many failed attempts a publication stops retrying and pages instead. */
 export const MAX_PUBLISH_ATTEMPTS = 5;
 const EXEC_TIMEOUT_MS = 60_000;
-/**
- * The one grant lookup for a task's publication: its project is the task's repo, and that project's live grant
- * governs it. The publisher, Complete → pull request and a flow's Pull request zone all ask here, so none of them
- * can judge a publication by another project's grant. `fallback`: the repo to assume for a task with none recorded.
- */
 export function publicationGrantOf(store, taskRef, fallback = null) {
     const repo = store.refById(taskRef)?.repo ?? fallback;
     return { repo, grant: repo === null ? null : store.publicationGrantFor(repo) };
 }
-/** The grant's terms, in the words the approver must be shown before agreeing. */
 export function describePublicationGrant(grant) {
     return [
         `  repo         ${grant.repo}`,
@@ -55,18 +27,9 @@ export function describePublicationGrant(grant) {
         `  mode         ${grant.draft ? "draft PRs" : "ready-for-review PRs"}`,
     ];
 }
-/**
- * The PR body, from durable state only — the same rows produce the same
- * bytes after any crash, which is what lets the intent carry a hash of it.
- */
-/** One line of untrusted prose, kept inline: newlines flatten so no agent
- * text can START a Markdown line and gain semantics (audit IV-9) —
- * `Closes #123` at line start closes; mid-sentence it is words. */
 function mdInline(text) {
     return text.replace(/[\r\n\u2028\u2029]+/g, " ").trim();
 }
-/** Untrusted multi-line prose as an INDENTED code block: backticks cannot
- * terminate indentation, so no conclusion escapes its quoting (audit IV-9). */
 function mdIndented(text) {
     return text.replace(/\r\n?/g, "\n").split("\n").map(line => `    ${line}`);
 }
@@ -89,8 +52,6 @@ export function publicationBody(store, publication) {
             lines.push(`- ${mdInline(answer.decision.question)} → **${mdInline(answer.choice)}** (${mdInline(answer.decision.answeredBy ?? "?")})`);
         }
     }
-    // The agent's own words ride INDENTED: an indented code block has no
-    // terminator an agent's text could supply, so prose stays prose.
     if (run?.handoff !== null && run?.handoff !== undefined) {
         lines.push("", "**The agent's conclusion, quoted:**", "", ...mdIndented(run.handoff));
     }
@@ -100,30 +61,15 @@ export function publicationBody(store, publication) {
 export function bodyHashOf(body) {
     return createHash("sha256").update(`v${BODY_TEMPLATE_VERSION}\n${body}`, "utf8").digest("hex");
 }
-/**
- * One pass over everything owed. Each phase re-proves the grant and moves
- * exactly one durable state — a crash at any point leaves a row the next
- * pass picks up where this one stopped.
- */
 export async function publishPass(store, options) {
     const clock = options.clock ?? (() => new Date());
     const exec = options.exec ?? execRun;
     const report = { pushed: 0, opened: 0, adopted: 0, failed: 0, problems: [] };
     for (const publication of store.pendingPublications()) {
-        // The secret gate (audit IV-7): a run whose accepted diff carried a
-        // high-confidence secret shape publishes NOTHING — pushing the branch
-        // would hand the credential to the remote. Fail closed, say why once,
-        // and leave the person to rewrite the branch and requeue.
         if (store.hasRedactedTerminalDiff(publication.run)) {
             concede(store, publication, "the accepted diff carries a detected secret — rewrite the branch before anything publishes", report, clock);
             continue;
         }
-        // Each project's watch publishes its own project's work: the push runs in
-        // that checkout, under that project's grant. Another project's pass must
-        // not touch it — judging it by the wrong grant once recorded "no live
-        // grant" errors until it gave up, while its own pass opened the PR.
-        // The grant is re-read per publication, live: revocation is immediate,
-        // and an intent created under a grant that has since died goes nowhere.
         const { repo, grant } = publicationGrantOf(store, publication.taskRef, options.repo);
         if (repo !== options.repo)
             continue;
@@ -135,15 +81,12 @@ export async function publishPass(store, options) {
                 concede(store, publication, verdict.message, report, clock);
             continue;
         }
-        // v102: separation of duties holds the push itself (so no PR and no merge follow) until a second person
-        // has seen a result that changed protected files on a one-person approval.
         if (publication.state === "intended") {
             const held = protectedPublicationHold(store, publication.run, options.evidenceRoot);
             if (held !== null) {
                 report.problems.push(`publication ${publication.id}: ${held}`);
                 continue;
             }
-            // A fast start waits for a person's Accept, and for a change that stayed small (fast-start.ts).
             const fastTask = store.externalIdFor(publication.taskRef);
             const fast = fastTask === null ? null : fastPublishProblem(store, fastTask, publication.run);
             if (fast !== null) {
@@ -152,8 +95,6 @@ export async function publishPass(store, options) {
             }
         }
         if (publication.state === "intended") {
-            // The exact SHA to the exact ref. A branch that moved since completion
-            // is not what was accepted, and this push cannot be talked into it.
             const push = await exec("git", ["push", publication.remote, `${publication.headSha}:refs/heads/${publication.head}`], { cwd: options.repo, timeoutMs: EXEC_TIMEOUT_MS });
             if (push.code !== 0) {
                 const why = push.notFound ? "git is not on PATH" : firstLine(push.stderr) || `git push exited ${push.code}`;
@@ -184,7 +125,6 @@ export async function publishPass(store, options) {
     }
     return report;
 }
-/** Why a publication may not proceed — checked against the whole grant, per phase. */
 export function permitsPublication(grant, publication) {
     if (grant === null)
         return { ok: false, message: "no live publication grant — nothing may be pushed" };
@@ -201,16 +141,10 @@ export function permitsPublication(grant, publication) {
     return { ok: true };
 }
 async function openOrAdopt(store, publication, grant, exec, clock) {
-    // Adopt first: a PR this head already has — whoever opened it, including
-    // a crashed earlier attempt — is the PR. Creating a second would be the
-    // duplicate the durable intent exists to prevent.
     const listed = await exec("gh", [
         "pr", "list",
         "--repo", publication.githubRepo,
         "--head", publication.head,
-        // The base filter (merge-grant finding 21): a same-head PR aimed at
-        // a DIFFERENT base is not this publication's PR and must never be
-        // adopted under authority granted for another branch.
         "--base", publication.base,
         "--state", "open",
         "--json", "number,url",
@@ -237,8 +171,6 @@ async function openOrAdopt(store, publication, grant, exec, clock) {
     const body = publicationBody(store, publication);
     const taskId = store.externalIdFor(publication.taskRef) ?? publication.head;
     const title = store.getTask(taskId)?.title ?? taskId;
-    // --body-file, not --body: the body quotes an agent and a shell must not
-    // meet it. The file lives in a private temp dir for exactly one call.
     const dir = mkdtempSync(join(tmpdir(), "standing-orders-pr-"));
     try {
         const bodyFile = join(dir, "body.md");
@@ -267,11 +199,6 @@ async function openOrAdopt(store, publication, grant, exec, clock) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
-/**
- * A publication given up on whose pull request exists anyway — a pass that gave up while another opened it, or a
- * person who opened it by hand: the PR on its exact head and base, carrying its exact commit, is adopted as opened
- * (merged or closed ones too; the next observation records which). Whether one was found.
- */
 export async function adoptPublishedPullRequest(store, publication, exec, clock) {
     if (publication.state !== "failed")
         return false;
@@ -292,14 +219,6 @@ export async function adoptPublishedPullRequest(store, publication, exec, clock)
     enqueueOpened(store, publication, pr.url, clock);
     return true;
 }
-/**
- * Read CI for every PR this control plane opened — structured rollup and the
- * exact head OID, never a command's exit status (finding 18). Episodes are
- * keyed `ci:<pr>:<headOid>`: a red head pages once; the episode resolves
- * when that exact head turns green or a newer commit supersedes it. `none`,
- * `running`, and not-read are never called green — an unread rollup neither
- * pages nor resolves anything.
- */
 export async function observeChecks(store, options) {
     const clock = options.clock ?? (() => new Date());
     const exec = options.exec ?? execRun;
@@ -307,10 +226,6 @@ export async function observeChecks(store, options) {
     for (const publication of options.publications ?? store.openedPublications()) {
         if (publication.prNumber === null)
             continue;
-        // The observation generation is RESERVED before the network call
-        // (merge grant, findings 20/24): a stalled older response loses its
-        // conditional settle, and a loser has NO effects — not the mirror
-        // row, not remote_state, not check state, not an episode.
         const generation = store.reserveObservation(publication.githubRepo, publication.prNumber);
         const viewed = await exec("gh", [
             "pr", "view", String(publication.prNumber),
@@ -335,9 +250,6 @@ export async function observeChecks(store, options) {
             continue;
         }
         report.observed++;
-        // A merged or closed PR leaves the watch (Codex M5-M8 audit, C-6): its
-        // remote state is recorded, its episodes resolve, and neither the
-        // review queue nor the next observation pass carries it forever.
         const remoteState = typeof payload.state === "string" ? payload.state.toUpperCase() : null;
         const mergeCommit = typeof payload.mergeCommit === "object" && payload.mergeCommit !== null && typeof payload.mergeCommit.oid === "string"
             ? payload.mergeCommit.oid : null;
@@ -348,19 +260,13 @@ export async function observeChecks(store, options) {
                 if (!settled.won)
                     return;
                 won = true;
-                // The checks' own timing (v146), only with the observation that won.
                 recordCiChecks(store, publication.githubRepo, publication.prNumber, headOid, parseCiRollup(payload.statusCheckRollup), clock());
                 store.recordPublicationRemoteState(publication.id, remoteState, clock());
                 report.resolved += store.resolveCiEpisodes(publication.githubRepo, publication.prNumber, null, clock());
-                // A closed PR moots its merge blocker and supersedes its intent —
-                // and its person-needed episode (arc 3 finding 23).
                 store.liftMergeBlocker(publication.id, "the-remote", clock());
                 store.resolveEpisodes(`merge-attn:${publication.id}`, clock());
                 const intent = store.mergeIntentFor(publication.id);
                 if (intent !== null && ["pending", "claimed", "waiting-human", "firing"].includes(intent.state)) {
-                    // The observer settles ANY nonterminal on an observed remote
-                    // terminal (E1/F1) - generation bumped so a live claim or
-                    // firing owner's later write loses to the observed truth.
                     store.settleMergeIntent(intent.id, intent.generation, remoteState === "MERGED" ? "merged" : "superseded", clock(), {
                         receipt: `observed ${remoteState.toLowerCase()} remotely`, bumpGeneration: true,
                     });
@@ -371,25 +277,18 @@ export async function observeChecks(store, options) {
             continue;
         }
         const state = summarizeChecks(payload.statusCheckRollup);
-        // Settled and, when it won, the checks' own timing recorded (v146) in one transaction: a losing generation writes nothing.
         const settled = settleWithChecks(store, { githubRepo: publication.githubRepo, prNumber: publication.prNumber, headSha: headOid, state, generation }, payload.statusCheckRollup, clock());
         if (!settled.won) {
-            // An out-of-order response: a newer observation already spoke.
-            // Nothing persists from this one (round-4 findings 24/25).
             report.problems.push(`PR #${publication.prNumber}: superseded observation discarded`);
             continue;
         }
         store.recordPublicationCheckState(publication.id, state, clock());
         report.seen.push({ publication, headOid, state, remoteState: null, rollup: payload.statusCheckRollup, mergeCommit });
-        // The episode identity carries the REPOSITORY (audit C-2): PR #55 in
-        // repo A and PR #55 in repo B are different worlds, and one's failure
-        // must never light the other's repair button.
         const key = `ci:${publication.githubRepo}:${publication.prNumber}:${headOid}`;
         const taskId = store.externalIdFor(publication.taskRef) ?? publication.head;
         if (state === "failing") {
             report.failing++;
             store.transact(() => {
-                // Older heads' episodes die with their commits; this head's opens once.
                 store.resolveCiEpisodes(publication.githubRepo, publication.prNumber, key, clock());
                 store.enqueueNotification({
                     source: { run: publication.run },
@@ -404,15 +303,11 @@ export async function observeChecks(store, options) {
             report.resolved += store.resolveCiEpisodes(publication.githubRepo, publication.prNumber, null, clock());
         }
         else {
-            // running / none: not good news, not bad news — old episodes for
-            // *other* heads still resolve (their commit is gone), this head's
-            // verdict stays open.
             store.resolveCiEpisodes(publication.githubRepo, publication.prNumber, key, clock());
         }
     }
     return report;
 }
-/** Retries are over; say so durably and page a person — silence is the one failure mode ruled out. */
 function concede(store, publication, why, report, clock) {
     store.transact(() => {
         store.failPublication(publication.id, clock());
@@ -420,7 +315,6 @@ function concede(store, publication, why, report, clock) {
             source: { run: publication.run },
             dedupeKey: `publication:${publication.id}:failed`,
             kind: "publication-failed",
-            // A person is needed now (v4 review, finding 6): never a digest.
             pushClass: "attention",
             link: `/r/${publication.run}`,
             subject: `publication of run #${publication.run} gave up`,
@@ -441,19 +335,14 @@ function enqueueOpened(store, publication, url, clock) {
 function firstLine(text) {
     return text.split("\n")[0]?.trim() ?? "";
 }
-// ---- the merge sweep (v21; four review rounds are the spec) ---------------
 export const MERGE_LEASE_MS = 5 * 60_000;
-// F1: a firing row is STALE only when this deadline passes - one sweep
-// interval plus grace, stamped at the CAS, never a guess.
 export const FIRING_GRACE_MS = 10 * 60_000;
 export const MERGE_MAX_ATTEMPTS = 3;
-/** The exact terms a merge intent binds - drift supersedes, never surprises. */
 export function mergeTermsHash(grant) {
     return createHash("sha256")
         .update("merge-terms/v1 " + grant.githubRepo + " " + grant.base + " " + grant.headPrefix + " " + (grant.mergeMethod ?? "") + " " + (grant.mergeDeleteBranch === true ? 1 : 0))
         .digest("hex");
 }
-/** One fresh, WINNING observation - the only tuple that may authorize. */
 async function observeOne(store, exec, clock, githubRepo, prNumber) {
     const generation = store.reserveObservation(githubRepo, prNumber);
     const viewed = await exec("gh", ["pr", "view", String(prNumber), "--repo", githubRepo, "--json", "statusCheckRollup,headRefOid,state,isDraft,baseRefName"], { timeoutMs: EXEC_TIMEOUT_MS });
@@ -477,15 +366,10 @@ async function observeOne(store, exec, clock, githubRepo, prNumber) {
         return { ok: false, why: "pr-" + String(payload.state ?? "gone").toLowerCase() };
     const state = summarizeChecks(payload.statusCheckRollup);
     const settled = settleWithChecks(store, { githubRepo, prNumber, headSha, state, generation }, payload.statusCheckRollup, clock());
-    // A losing settle is NO observation (round-4 finding 24).
     if (!settled.won)
         return { ok: false, why: "stale-observation" };
     return { ok: true, state, headSha };
 }
-/** A COMPLETE negative proof that no merge queue governs the base - or no
- * merge (round-4 finding 22): every rules page, plus the classic-protection
- * probe with a STRUCTURED status; any classic protection at all, or any
- * unreadable answer, refuses merge-queue-unknown, fail closed. */
 async function proveNoMergeQueue(exec, githubRepo, base) {
     const rules = await exec("gh", ["api", "--paginate", "--slurp", "repos/" + githubRepo + "/rules/branches/" + encodeURIComponent(base)], { timeoutMs: EXEC_TIMEOUT_MS });
     if (rules.code !== 0)
@@ -504,8 +388,6 @@ async function proveNoMergeQueue(exec, githubRepo, base) {
     catch {
         return { ok: false, why: "merge-queue-unknown" };
     }
-    // Classic protection: the endpoint cannot PROVE queue absence, so any
-    // 200 refuses conservatively; only a structured 404 is a readable "no".
     const classic = await exec("gh", ["api", "--include", "repos/" + githubRepo + "/branches/" + encodeURIComponent(base) + "/protection"], { timeoutMs: EXEC_TIMEOUT_MS });
     const statusLine = classic.stdout.split("\n")[0] ?? "";
     if (classic.code === 0 && /^HTTP\/[\d.]+ 200/.test(statusLine))
@@ -514,21 +396,11 @@ async function proveNoMergeQueue(exec, githubRepo, base) {
         return { ok: true };
     return { ok: false, why: "merge-queue-unknown" };
 }
-/**
- * Merge what the grant allows and the evidence proves: this plane's own
- * publications, on this repo, whose PR was OBSERVED green on the exact
- * head - through a claim lease, a live-grant re-read, the queue proof,
- * and GitHub's own head CAS. Every refusal is typed and durable.
- */
 export async function sweepMerges(store, options) {
     const clock = options.clock ?? (() => new Date());
     const exec = options.exec ?? execRun;
     const who = options.runner ?? "publish";
     const report = { merged: 0, refused: 0, skipped: 0, problems: [] };
-    // Person-needed merge episodes are STAMPED and episodic (arc 3 findings
-    // 14/22/23): one open episode per publication nags, resolution closes it,
-    // and a recurrence after repair pages again. Success and plain status
-    // pages stay classless — a merged PR needs nobody.
     const page = (publication, key, subject, body) => {
         store.enqueueNotification({ source: { run: publication.run }, dedupeKey: key, kind: "merge", subject, body }, clock());
     };
@@ -541,19 +413,15 @@ export async function sweepMerges(store, options) {
     const method = grant.mergeMethod;
     const termsHash = mergeTermsHash(grant);
     for (const publication of store.openedPublications()) {
-        // A release's result merges only through `toolroll release` (release-once.md): the sweep never takes it up.
         if (releasePublication(store, publication.id)) {
             report.skipped++;
             continue;
         }
-        // One bad row never stops the rest of the sweep: every other publication, in every project, still merges.
         try {
             if (publication.prNumber === null || publication.headSha === null)
                 continue;
             const prNumber = publication.prNumber;
             const headSha = publication.headSha;
-            // The local-repo fence (finding 6): repo B's publication never rides
-            // repo A's sweep, whatever the remote terms coincide on.
             const ref = store.refForId(publication.taskRef);
             if (ref === null || ref.repo !== options.repo)
                 continue;
@@ -569,17 +437,11 @@ export async function sweepMerges(store, options) {
             const intent = store.mergeIntentFor(publication.id);
             if (intent === null || intent.state === "merged" || intent.state === "refused" || intent.state === "superseded")
                 continue;
-            // WAITING-HUMAN never fires itself (E1): the person is paged once,
-            // episodically, with the exact ceremony that releases it.
             if (intent.state === "waiting-human") {
                 report.skipped++;
                 pagePerson(publication, "waiting-human", "PR #" + prNumber + " waits for your go-ahead", "Merges wait for you while this posture holds. When you want it merged: toolroll publish merge " + prNumber + " --as <you> --token <t>. It still merges only when CI is seen green on the exact head.");
                 continue;
             }
-            // FIRING is one-shot (E1): a live firing row belongs to its owner.
-            // A STALE one (deadline passed) recovers by STRUCTURED REMOTE REREAD
-            // (F1): an observed terminal settles it; an OPEN same-head PR is
-            // NEVER auto-retried - the person gets the recovery ceremony.
             if (intent.state === "firing") {
                 if (intent.firingDeadline !== null && intent.firingDeadline <= clock().toISOString()) {
                     const reread = await observeOne(store, exec, clock, grant.githubRepo, prNumber);
@@ -611,10 +473,8 @@ export async function sweepMerges(store, options) {
             }
             const claim = store.claimMergeIntent(intent.id, who, MERGE_LEASE_MS, clock());
             if (claim === null)
-                continue; // someone else's live claim
+                continue;
             const settle = (state, detail = {}) => store.settleMergeIntent(intent.id, claim.generation, state, clock(), { from: "claimed", ...detail });
-            // The live grant, re-read AFTER the claim (finding 7): revocation,
-            // narrowing, or any term drift supersedes rather than merges.
             const live = store.publicationGrantFor(options.repo);
             if (live === null || live.merge !== true || mergeTermsHash(live) !== termsHash || intent.headSha !== headSha) {
                 settle("superseded", { error: "the grant or the head moved since this intent was written" });
@@ -629,7 +489,6 @@ export async function sweepMerges(store, options) {
                     : "The branch's protection could not be READ well enough to prove no merge queue governs it - auto-merge stays paused. Check access, then run: toolroll publish rearm " + prNumber + ".");
                 continue;
             }
-            // One fresh, winning observation - green on the EXACT publication head.
             const seen = await observeOne(store, exec, clock, grant.githubRepo, prNumber);
             if (!seen.ok) {
                 if (seen.why === "draft") {
@@ -652,10 +511,6 @@ export async function sweepMerges(store, options) {
                 });
                 continue;
             }
-            // The linearization point (E1): claimed -> firing as a DURABLE CAS
-            // re-proving grant terms, head, and basis-specific authority in one
-            // transaction. Before it commits, a revocation wins; after, the
-            // issued call is one-shot and no revocation demotes it.
             const fired = store.fireMergeIntent(intent.id, claim.generation, { repo: options.repo, headSha, liveGrantTermsHash: mergeTermsHash(live), graceMs: FIRING_GRACE_MS }, clock());
             if (!fired.ok) {
                 if (fired.outcome === "waiting-human") {
@@ -682,8 +537,6 @@ export async function sweepMerges(store, options) {
                 page(publication, "merge:" + publication.id + ":merged", "merged: PR #" + prNumber, (publication.prUrl ?? grant.githubRepo) + " - " + method + " of " + headSha.slice(0, 12) + ", under the merge terms you approved.");
                 continue;
             }
-            // NEVER classify from the exit code alone (only auth=4 is distinct):
-            // re-read structured state and let the PR say what happened.
             if (merged.code === 4) {
                 settle("refused", { error: "credential", countAttempt: true, from: "firing" });
                 report.refused++;
@@ -718,8 +571,6 @@ export async function sweepMerges(store, options) {
     }
     return report;
 }
-/** A conditional settle (store.settleObservation) and, only when it won, that head's checks' own timing (v146 ci_check),
- * in one transaction: a stale, losing answer neither settles nor records a check. */
 export function settleWithChecks(store, observation, rollup, now) {
     return store.transact(() => {
         const settled = store.settleObservation(observation, now);