@sleepy_panda_srl/portulan 0.3.0 → 0.4.1

package/cli/telemetry.mjs

@@ -22,6 +22,10 @@ import { isInside } from "./inside.mjs";
 
 /** Every network mode in cli/ or a pack (named from `<category>/<name>/`); a new one is unrailed until it has a row here. */
 export const NETWORK_MODES = Object.freeze([
+    { module: "cli/fixtures/on-path-host/capture.mjs", flag: "--run-host", what: "runs the manual real-host on-path demonstration" },
+    { module: "cli/fixtures/nested-on-path-host/capture.mjs", flag: "--run-host", what: "runs the manual real-host nested instruction demonstration" },
+    { module: "cli/context.mjs", flag: "--count-tokens", what: "sends measured project source to Anthropic's token counter" },
+    { module: "cli/doctor.mjs", flag: "--count-tokens", aliases: [{ module: "cli/portulan.mjs", subcommand: "doctor" }, { module: "portulan", subcommand: "doctor" }, { module: "@sleepy_panda_srl/portulan", subcommand: "doctor" }], what: "requests a provider token estimate" },
     { module: "cli/review-meter.mjs", flag: "--fetch", what: "fetches review data from GitHub" },
     { module: "cli/telemetry.mjs", flag: "--export", what: "posts an OTLP payload to a collector" },
     { module: "cli/feedback.mjs", flag: "--approve", what: "files a GitHub issue with `gh issue create`" },
@@ -40,7 +44,7 @@ export const LOCAL_RECORD_MODES = Object.freeze([
     { module: "portulan", subcommand: "doctor", requiresStatic: "--static", what: "dispatches to the local usage-record reader" },
 ]);
 
-export const modeSpelling = (m) => m.requiresStatic ? `${m.module}${m.subcommand ? ` ${m.subcommand}` : ""} without an immediate ${m.requiresStatic}` : (m.flag ? `${m.module} ${m.flag}` : `${m.module} with anything but ${m.unless} alone${m.alsoUnless ? ` or ${m.alsoUnless.join(" ")} alone` : ""}`);
+export const modeSpelling = (m) => m.requiresStatic ? `${m.module}${m.subcommand ? ` ${m.subcommand}` : ""} without an immediate ${m.requiresStatic}` : (m.flag ? [m, ...(m.aliases ?? [])].map((s) => `${s.module}${s.subcommand ? ` ${s.subcommand}` : ""} ${m.flag}`).join(", ") : `${m.module} with anything but ${m.unless} alone${m.alsoUnless ? ` or ${m.alsoUnless.join(" ")} alone` : ""}`);
 
 /** Whole-line comments only: a trailing `#` may sit inside a quote. */
 export const stripShellComments = (source) =>
@@ -51,14 +55,14 @@ export const stripShellComments = (source) =>
 
 const shellTokens = (body) => body.split(/\s+/).map((t) => t.replace(/^[("'`]+/, "").replace(/[)"'`;]+$/, "")).filter(Boolean);
 
-const tokenNamesModule = (token, module) => token === module || token.endsWith(`/${module}`);
+const tokenNamesModule = (token, module) => token === module || token.endsWith(`/${module}`) || (module.startsWith("@") && token.startsWith(`${module}@`));
 
 const tokenIsFlag = (token, flag) => token === flag || token.startsWith(`${flag}=`);
+const shellSource = (source) => stripShellComments(source).replace(/\\\r?\n/g, "");
 
 /** An `unless` row passes only where every invocation is the module and its one safe flag, alone on its command. */
 const onlySafeInvocations = (source, m) =>
-    stripShellComments(source)
-        .replace(/\\\n/g, " ")
+    shellSource(source)
         .split(/\n|;|&&?|\|\|?|\$\(|<\(|>\(|`/)
         .every((segment) => {
             const tokens = shellTokens(segment);
@@ -66,8 +70,7 @@ const onlySafeInvocations = (source, m) =>
             return tokens.every((t, i) => !tokenNamesModule(t, m.module) || ((tokens.length === i + 2 && tokens[i + 1] === m.unless) || (m.alsoUnless && JSON.stringify(tokens.slice(i + 1)) === JSON.stringify(m.alsoUnless))));
         });
 
-const onlyStaticInvocations = (source, mode) => stripShellComments(source)
-    .replace(/\\\n/g, " ")
+const onlyStaticInvocations = (source, mode) => shellSource(source)
     .split(/\n|;|&&?|\|\|?|\$\(|<\(|>\(|`/)
     .every((segment) => {
         const words = shellTokens(segment);
@@ -78,9 +81,9 @@ const onlyStaticInvocations = (source, mode) => stripShellComments(source)
     });
 
 export function auditRecipeSource(source) {
-    const tokens = shellTokens(stripShellComments(source));
+    const tokens = shellTokens(shellSource(source));
     const network = NETWORK_MODES.filter((m) =>
-        m.flag ? tokens.some((t) => tokenNamesModule(t, m.module)) && tokens.some((t) => tokenIsFlag(t, m.flag)) : !onlySafeInvocations(source, m),
+        m.flag ? [m, ...(m.aliases ?? [])].some((s) => tokens.some((t, i) => tokenNamesModule(t, s.module) && (!s.subcommand || tokens[i + 1] === s.subcommand))) && tokens.some((t) => tokenIsFlag(t, m.flag)) : !onlySafeInvocations(source, m),
     );
     const local = LOCAL_RECORD_MODES.filter((m) => !onlyStaticInvocations(source, m));
     return [...network, ...local];
@@ -114,9 +117,10 @@ export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
     const read = [];
     for (const r of recipes) {
         const words = String(r.run ?? "").split(/\s+/).filter(Boolean);
-        // A run line that is itself a `node` invocation is the whole shell text the recipe runs, so it is graded as read.
-        const direct = words[0] === "node" && !words.some((t) => t.endsWith(".sh"));
-        const script = direct ? words.find((t) => /\.[cm]?js$/.test(t)) : words.find((t) => t.endsWith(".sh"));
+        // Direct CLI commands are graded as shell text; referenced shell scripts are read too.
+        const bare = words[0] === "portulan";
+        const direct = bare || (words[0] === "node" && !words.some((t) => t.endsWith(".sh")));
+        const script = bare ? "cli/portulan.mjs" : direct ? words.find((t) => /\.[cm]?js$/.test(t)) : words.find((t) => t.endsWith(".sh"));
         if (!script) {
             return { ok: false, why: `recipe ${JSON.stringify(r.id)} has no readable script in its run line (${JSON.stringify(r.run ?? null)}); this audit cannot grade what it cannot read` };
         }
@@ -131,7 +135,10 @@ export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
             return { ok: false, why: `recipe ${JSON.stringify(r.id)} names ${script}, which could not be read — ${cause.message}` };
         }
         read.push(r.id);
-        for (const hit of auditRecipeSource(direct ? r.run : source)) findings.push({ recipe: r.id, script, ...hit });
+        const hits = [...auditRecipeSource(r.run), ...(direct ? [] : auditRecipeSource(source))];
+        for (const [i, hit] of hits.entries()) {
+            if (!hits.slice(0, i).some((previous) => previous.module === hit.module && previous.flag === hit.flag && previous.requiresStatic === hit.requiresStatic)) findings.push({ recipe: r.id, script, ...hit });
+        }
     }
     return { ok: true, examined: read, findings };
 }

package/cli/upgrade.mjs

@@ -4,6 +4,7 @@
 // Exit 0 succeeded · 1 a step owed under `--check` or left by hand, a red workspace, an unresolved pointer · 2 could not run.
 
 import fs from "node:fs";
+import { assertNoSourceJournal } from "./instructions-journal.mjs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -12,6 +13,7 @@ import { resolveGovernor } from "./discover.mjs";
 import { gitIn } from "./form.mjs";
 import { offerLines } from "./sessions.mjs";
 import { walk } from "./vendor.mjs";
+import { atomicWrite,guardedRemove,readOutput,sameContent } from "./guidance-files.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLE = path.resolve(HERE, "..");
@@ -19,10 +21,10 @@ const MIGRATIONS = path.join(BUNDLE, "spec", "migrations");
 
 let stagingSeq = 0;
 
-/** Everything that means `upgrade` could not run. Carries no verdict about a workspace. */
+/** Unavailable, without a verdict about the workspace. */
 export class UpgradeError extends Error {}
 
-/** The Workspace Definition version this bundle implements, read from its schema's `$id`. */
+/** This bundle's Workspace Definition version from the schema `$id`. */
 export function bundleSpec({ schemaPath } = {}) {
     const file = schemaPath ?? path.join(BUNDLE, "spec", "workspace.schema.json");
     let text;
@@ -68,7 +70,7 @@ export async function loadSteps({ dir = MIGRATIONS } = {}) {
     return steps;
 }
 
-/** Read a workspace into the view a step is given, as `spec/migrations/README.md` defines it. */
+/** The step's workspace view; contract: `spec/migrations/README.md`. */
 export function readWorkspace(dir) {
     const root = path.resolve(dir);
     const file = path.join(root, "workspace.json");
@@ -120,7 +122,7 @@ export function readWorkspace(dir) {
     };
 }
 
-/** The repository the manifest's `tree` names, as a step reads it; `null` where it names no directory. */
+/** The step's declared repository view, or null without a tree. */
 export function repositoryView(root, manifest) {
     if (typeof manifest?.tree !== "string") return null;
     const dir = path.resolve(root, manifest.tree);
@@ -223,7 +225,7 @@ export async function planFor(ws, ctx, steps) {
         } catch (error) {
             answer = { owed: null, because: `${step.id} threw while deciding whether it is owed — ${error.message}` };
         }
-        // `hand`: owed, and placed by a person rather than by the step, so `--write` reports it and runs on.
+        // `hand` requires a person; report it and continue.
         entries.push({ step, owed: answer.owed, because: answer.because, hand: answer.owed === true && answer.hand === true });
         if (answer.owed === null) unknown += 1;
         else if (answer.owed === true) owed += 1;
@@ -231,14 +233,14 @@ export async function planFor(ws, ctx, steps) {
     return { entries, owed, unknown };
 }
 
-/** `rel` resolved inside `root`, or `null` if it escapes: `path.join` would pass an absolute `rel` as inside. */
+/** Resolve inside root, rejecting escapes. */
 export function inside(root, rel) {
     const resolved = path.resolve(root, rel);
     if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) return null;
     return resolved;
 }
 
-/** A reason to refuse, or `null`; `root` itself is not checked, since macOS's `os.tmpdir()` runs through `/var`. */
+/** Refusal or null; root may itself follow macOS's `/var` alias. */
 function linkOnPath(root, resolved) {
     const rel = path.relative(root, resolved);
     if (rel === "") return null;
@@ -257,7 +259,7 @@ function linkOnPath(root, resolved) {
     return null;
 }
 
-/** `dirs` as created, shallowest first; one that will not go is not empty, and neither are its parents. */
+/** Remove created directories deepest first, stopping at a nonempty one. */
 function unwindDirs(dirs) {
     for (const made of [...dirs].reverse()) {
         try {
@@ -275,6 +277,7 @@ export function applyEdits(dir, edits, options = {}) {
     const treeRoot = typeof options.treeDir === "string" ? path.resolve(options.treeDir) : null;
     const snapshots = [];
     for (const edit of edits) {
+        try{options.beforeMutation?.(edit);}catch(error){return {ok:false,snapshots,reason:error.message};}
         if (edit.root !== undefined && edit.root !== "workspace" && edit.root !== "tree") {
             return { ok: false, snapshots, reason: `an edit names root \`${edit.root}\`, which is neither the workspace nor the tree` };
         }
@@ -294,29 +297,35 @@ export function applyEdits(dir, edits, options = {}) {
         if (linked !== null) return { ok: false, snapshots, reason: linked };
 
         let previous = null;
-        let mode = null;
+        let mode = null, observedIdentity = null;
         try {
-            previous = fs.readFileSync(file, "utf8");
-            mode = fs.lstatSync(file).mode;
+            const at=fs.lstatSync(file);
+            if(!at.isFile()) return {ok:false,snapshots,reason:`${file} is not a regular file`};
+            if(edit.nested && edit.next!==null && at.nlink!==1) return {ok:false,snapshots,reason:`${file} is a multiply linked guidance output`};
+            previous = readOutput(file,root);
+            const after=fs.lstatSync(file);
+            if(after.dev!==at.dev||after.ino!==at.ino||after.mode!==at.mode)return {ok:false,snapshots,reason:`${file} changed while its original was read`};
+            mode=at.mode;observedIdentity={dev:at.dev,ino:at.ino,mode:at.mode};
         } catch (error) {
             if (error.code !== "ENOENT") {
                 return { ok: false, snapshots, reason: `${file} could not be read before writing — ${error.code ?? error.message}` };
             }
         }
 
+        if (Object.hasOwn(edit,"before") && !sameContent(previous,edit.before)) return {ok:false,snapshots,reason:`${file} changed after guidance planning`};
+        if(edit.beforeIdentity){const at=fs.lstatSync(file,{throwIfNoEntry:false});if(!at||at.dev!==edit.beforeIdentity.dev||at.ino!==edit.beforeIdentity.ino||at.mode!==edit.beforeIdentity.mode)return {ok:false,snapshots,reason:`${file} changed identity after source planning`};}
         if (edit.next === null) {
             if (previous === null) continue;
             if (!fs.lstatSync(file).isFile()) return { ok: false, snapshots, reason: `${file} is not a regular file — refusing to delete it` };
             try {
-                fs.rmSync(file);
+                guardedRemove(file,{before:previous,identity:edit.beforeIdentity??observedIdentity,allowLinks:Boolean(edit.claimBase),claimBase:edit.claimBase,onClaim:data=>options.journal?.(edit,"claim",data),onRemove:claim=>{snapshots.push({file:edit.file,root:edit.root,previous,mode,created:[],deleted:true,after:null,identity:null,cleanup:[claim]});options.journal?.(edit,"retired",claim);}});
             } catch (error) {
                 return { ok: false, snapshots, reason: `${file} could not be deleted — ${error.code ?? error.message}` };
             }
-            snapshots.push({ file: edit.file, root: edit.root, previous, mode, created: [], deleted: true });
             continue;
         }
 
-        // `lstat`, not `existsSync`, which follows links and answers `false` for a path it could not read.
+        // lstat distinguishes links and unreadable paths from absence.
         const wanted = [];
         for (let at = path.dirname(file); at.startsWith(root) && at !== root; at = path.dirname(at)) {
             try {
@@ -330,7 +339,7 @@ export function applyEdits(dir, edits, options = {}) {
             }
         }
 
-        // No snapshot owns these until the rename lands, so every failure before it unwinds them.
+        // Unwind this edit's created directories if publication fails.
         const created = [];
         try {
             for (const dir of wanted) {
@@ -338,7 +347,7 @@ export function applyEdits(dir, edits, options = {}) {
                     fs.mkdirSync(dir);
                     created.push(dir);
                 } catch (error) {
-                    // Made by another since the probe: fine if a directory, and not this run's to remove.
+                    // A concurrently created directory is not ours to remove.
                     if (error.code !== "EEXIST" || !fs.lstatSync(dir).isDirectory()) throw error;
                 }
             }
@@ -347,24 +356,17 @@ export function applyEdits(dir, edits, options = {}) {
             return { ok: false, snapshots, reason: `${path.dirname(file)} could not be created — ${error.code ?? error.message}` };
         }
 
-        // Unique per process and edit, and beside its file so the rename stays atomic.
+        // Stage each edit beside its target for exclusive publication.
         const staging = `${file}.portulan-upgrade.${process.pid}.${stagingSeq++}`;
+        let published;
         try {
-            // `wx`: anything already at the staging path, a planted symlink included, fails rather than being followed.
-            write(staging, edit.next, { flag: "wx" });
+            // Exclusive creation refuses existing files and symlinks.
             const keep = mode ?? edit.mode ?? null;
-            if (keep !== null) fs.chmodSync(staging, keep);
-            fs.renameSync(staging, file);
+            published=atomicWrite(file,edit.next,{exclusive:edit.exclusive??previous===null,before:previous,identity:edit.beforeIdentity??observedIdentity??undefined,mode:keep,write,stagingPath:edit.nested?undefined:staging,onPrepare:data=>options.journal?.(edit,"stage",data),onClaim:data=>options.journal?.(edit,"claim",data),onCleanupClaim:data=>options.journal?.(edit,"undo-claim",data),onPublish:(id,cleanup)=>snapshots.push({file:edit.file,root:edit.root,previous,mode,created,after:edit.next,identity:{dev:id.dev,ino:id.ino,mode:id.mode},cleanup})});
         } catch (error) {
-            try {
-                fs.rmSync(staging, { force: true });
-            } catch {
-                /* the staging file is the lesser problem; the write failure is what gets reported */
-            }
             unwindDirs(created);
             return { ok: false, snapshots, reason: `${file} could not be written — ${error.code ?? error.message}` };
         }
-        snapshots.push({ file: edit.file, root: edit.root, previous, mode, created });
     }
     return { ok: true, snapshots };
 }
@@ -374,9 +376,12 @@ export function restore(dir, snapshots, options = {}) {
     const treeRoot = typeof options.treeDir === "string" ? path.resolve(options.treeDir) : null;
     const restored = [];
     const failed = [];
-    // Last edit first: a directory two edits share is recorded on the first, and empties only after the second.
+    const restoredIdentities=new Map();
+    // Reverse order empties shared directories before their owner removes them.
     for (const snapshot of [...snapshots].reverse()) {
-        // Contained again, as `restore` is exported and a snapshot may come from any caller.
+        if(options.stopOnFailure&&failed.length){failed.push(snapshot.file);continue;}
+        try{options.beforeMutation?.(snapshot);}catch{failed.push(snapshot.file);continue;}
+        // Exported restore must recheck containment of caller-supplied snapshots.
         const root = snapshot.root === "tree" ? treeRoot : workspaceRoot;
         const file = root === null ? null : inside(root, snapshot.file);
         if (file === null || linkOnPath(root, file) !== null) {
@@ -384,15 +389,27 @@ export function restore(dir, snapshots, options = {}) {
             continue;
         }
         try {
+            for(const item of snapshot.cleanup??[])if(typeof item.file!=="string"||inside(root,path.relative(root,item.file))!==item.file||linkOnPath(root,item.file)!==null)throw new UpgradeError("cleanup journal is outside its transaction root or aliases another path");
+            const at=fs.lstatSync(file,{throwIfNoEntry:false});
+            const aliases=(snapshot.cleanup??[]).filter(item=>{try{const linked=fs.lstatSync(item.file);return linked.isFile()&&linked.dev===at?.dev&&linked.ino===at?.ino&&sameContent(readOutput(item.file,root),item.before);}catch{return false;}});
+            const allowLinks=Boolean(at&&at.nlink>1&&at.nlink===aliases.length+1);
+            if(at && (!at.isFile() || at.isSymbolicLink() || (at.nlink!==1&&!allowLinks))) throw new UpgradeError(`${file} is not an ordinary singly linked restore target`);
+            const current=at ? readOutput(file,root) : null;
+            if(Object.hasOwn(snapshot,"after")) {
+                const expected=restoredIdentities.has(file) ? restoredIdentities.get(file) : snapshot.identity;
+                if(!sameContent(current,snapshot.after) || (expected && (!at || at.dev!==expected.dev || at.ino!==expected.ino || (expected.mode!==undefined&&at.mode!==expected.mode)))) throw new UpgradeError(`${file} changed since this transaction wrote it`);
+            }
+            let replacedIdentity=null;
             if (snapshot.previous === null) {
-                fs.rmSync(file, { force: true });
-                unwindDirs(snapshot.created ?? []);
+                if(at)guardedRemove(file,{before:current,identity:{dev:at.dev,ino:at.ino,mode:at.mode},allowLinks,onClaim:data=>options.journal?.(snapshot,"undo-claim",data),onRemove:claim=>options.journal?.(snapshot,"retired",claim)});
             } else {
-                const at = fs.lstatSync(file, { throwIfNoEntry: false });
-                if (at?.isSymbolicLink()) throw new UpgradeError(`${file} is a symlink — refusing to restore through it`);
-                fs.writeFileSync(file, snapshot.previous);
-                if (snapshot.mode !== null && snapshot.mode !== undefined) fs.chmodSync(file, snapshot.mode);
+                replacedIdentity=atomicWrite(file,snapshot.previous,{exclusive:!at,before:current,identity:at ? {dev:at.dev,ino:at.ino,mode:at.mode} : undefined,allowLinks,mode:snapshot.mode,onPrepare:data=>options.journal?.(snapshot,"undo-stage",data),onClaim:data=>options.journal?.(snapshot,"undo-claim",data),onCleanupClaim:data=>options.journal?.(snapshot,"claim",data)});
             }
+            for(const item of snapshot.cleanup??[])if(fs.lstatSync(item.file,{throwIfNoEntry:false}))guardedRemove(item.file,{before:item.before,identity:item.identity,allowLinks:true,claimBase:path.basename(file)});
+            if(snapshot.previous===null)unwindDirs(snapshot.created??[]);
+            const replaced=fs.lstatSync(file,{throwIfNoEntry:false});
+            if(replacedIdentity?(!replaced||replaced.dev!==replacedIdentity.dev||replaced.ino!==replacedIdentity.ino||replaced.mode!==replacedIdentity.mode):Boolean(replaced))throw new UpgradeError(`${file} changed during rollback publication`);
+            restoredIdentities.set(file,replacedIdentity);
             restored.push(snapshot.file);
         } catch {
             failed.push(snapshot.file);
@@ -497,7 +514,7 @@ export async function run(argv = [], options = {}) {
         return 2;
     }
 
-    // ---- which workspace, and in which residence
+    // Resolve target and residence.
     const target = await resolveTarget(positional[0], { env });
     if (target.state === "could-not-look") {
         warn(`upgrade: ${target.sentence}`);
@@ -524,6 +541,7 @@ export async function run(argv = [], options = {}) {
         return read.code;
     }
     const ws = read.ws;
+    try{assertNoSourceJournal(ws.dir);if(ws.repository)assertNoSourceJournal(ws.repository.dir);}catch(error){warn(`upgrade: ${error.message}`);return 2;}
     const relative = path.relative(process.cwd(), ws.dir);
     const shown = relative && relative.length < ws.dir.length ? relative : ws.dir;
 
@@ -533,7 +551,7 @@ export async function run(argv = [], options = {}) {
         for (const line of offerLines()) say(`upgrade: ${line}`);
     };
 
-    // ---- which direction is this workspace off in
+    // Classify version drift.
     const declared = /^([0-9]+)\.([0-9]+)$/.exec(ws.manifest?.portulan?.spec ?? "");
     if (!declared) {
         warn(`upgrade: ${shown} declares no readable \`portulan.spec\` — refusing to guess which contract it was written against`);
@@ -551,7 +569,7 @@ export async function run(argv = [], options = {}) {
         return 2;
     }
 
-    // ---- the pre-state gate, which can only ever apply to a gradeable workspace
+    // Pre-state gate requires a gradeable workspace.
     if (!behindByMajor) {
         let pre;
         try {
@@ -572,7 +590,7 @@ export async function run(argv = [], options = {}) {
         }
     }
 
-    // ---- the plan
+    // Plan.
     const ctx = { bundle: BUNDLE, spec, tree, today: options.today ?? new Date().toISOString().slice(0, 10) };
     const plan = await planFor(ws, ctx, steps);
 
@@ -622,10 +640,10 @@ export async function run(argv = [], options = {}) {
         return 0;
     }
 
-    // ---- apply, one step at a time, re-reading between them
+    // Apply and reread after each step.
     let snapshots = [];
     let current = ws;
-    // A step may declare the tree but none moves it, so every snapshot was made in the latest one.
+    // Steps can declare a tree, but never move it.
     let treeDir = ws.repository?.dir ?? null;
     const undo = () => {
         const result = restore(current.dir, snapshots, { treeDir });
@@ -640,7 +658,7 @@ export async function run(argv = [], options = {}) {
     const byHand = new Map();
     const apply = async (entry) => {
         applied.add(entry.step.id);
-        // A step's `plan` is foreign code: a throw becomes a refusal, so the rollback still runs.
+        // Foreign plan failures must reach rollback.
         let planned;
         try {
             planned = await entry.step.plan(current, ctx);
@@ -677,7 +695,7 @@ export async function run(argv = [], options = {}) {
         treeDir = current.repository?.dir ?? treeDir;
         return null;
     };
-    // A step can make an earlier one owed, so the chain is asked again until a pass applies nothing.
+    // Revisit earlier steps until a pass applies nothing.
     for (let pass = 0; ; pass++) {
         let appliedNow = 0;
         for (const entry of plan.entries) {
@@ -712,7 +730,7 @@ export async function run(argv = [], options = {}) {
         }
     }
 
-    // ---- and grade what it produced, with the real validator
+    // Grade with the real validator.
     let post;
     try {
         post = await inspect(current.dir);