@salaros/ai-harness 0.2.10 → 0.3.1

package/scripts/update-harness.js

@@ -32,6 +32,8 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const lib = require("./lib");
+const projectFacts = require("./project-facts");
+const repoView = require("./repo-view");
 const { spawnSync } = require("child_process");
 
 const TEMPLATE = "https://github.com/salaros/ai-harness.git";
@@ -39,9 +41,6 @@ const LOCK = "harness-lock.json";
 const MANIFEST = "scripts/harness-files.tsv";
 const DEFAULT_REF = "master";
 
-const argv = process.argv.slice(2);
-const flag = name => argv.includes(name);
-const value = (name, fallback) => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1] : fallback; };
 // Every argument the installer knows. An optional part of the harness adds its own flag through the
 // manifest (optional:<flag>), so those are checked once the upstream checkout is read. Anything else
 // stops the run before a file is written: this script installs when it is run, so a mistyped
@@ -86,8 +85,31 @@ function usage() {
     for (let i = start + 1; i < lines.length && lines[i].startsWith("//   "); i++) out.push(lines[i].slice(3).replace("node scripts/update-harness.js", "npx @salaros/ai-harness"));
     return ["Installs or updates the agent harness in the current git repository.", "", "Usage:", ...out].join("\n");
 }
-const dryRun = flag("--dry-run");
-const adopt = flag("--adopt");
+
+// The arguments, read once. Everything below takes this object rather than the process's argv, so a
+// test can ask what an --adopt run would plan without being one. `wants` answers whether the run
+// asked for an optional part of the harness by its flag.
+function parseOptions(args) {
+    const flag = name => args.includes(name);
+    const value = name => { const i = args.indexOf(name); return i >= 0 && args[i + 1] ? args[i + 1] : null; };
+    return {
+        help: flag("--help") || flag("-h"),
+        dryRun: flag("--dry-run"),
+        adopt: flag("--adopt"),
+        quiet: flag("--quiet"),
+        check: !flag("--no-check"),
+        wants: name => flag(`--${name}`),
+        ref: value("--ref"),
+        target: value("--target"),
+        from: value("--from"),
+    };
+}
+
+// A reason to stop. Thrown rather than exiting, so main() is the one place the process ends, and a
+// temporary clone is still removed on the way out.
+class Stop extends Error {}
+const fail = m => { throw new Stop(m); };
+const say = m => console.log(m);
 
 // ---------------------------------------------------------------- the target
 
@@ -95,9 +117,8 @@ const adopt = flag("--adopt");
 // its scripts/ folder. Run through npx, the package is an extracted tarball with no .git of its own,
 // so the answer is the directory the user is standing in. One rule covers both, and --target covers
 // installing into a checkout from somewhere else entirely.
-function targetRoot() {
-    const given = value("--target", null);
-    if (given) return path.resolve(given);
+function targetRoot(options) {
+    if (options.target) return path.resolve(options.target);
     const beside = path.resolve(__dirname, "..");
     return fs.existsSync(path.join(beside, ".git")) ? beside : process.cwd();
 }
@@ -106,22 +127,21 @@ function targetRoot() {
 
 // A clone deep enough to read the recorded commit: an update needs that commit's version of a file
 // as the merge base, and --depth 1 would not have it. Removed again unless the caller supplied one.
-function templateCheckout(ref) {
+function templateCheckout(ref, options) {
     // The manifest is what makes a checkout usable here, so both routes are held to it: a --from
     // that points somewhere else, and a --ref naming a branch or tag from before the table existed,
     // fail the same way. Without this the run reaches readTsv and dies in a stack trace naming a
     // temporary directory the reader has never heard of.
     const usable = dir => fs.existsSync(path.join(dir, MANIFEST));
-    const given = value("--from", null);
-    if (given) {
-        const dir = path.resolve(given);
+    if (options.from) {
+        const dir = path.resolve(options.from);
         if (!usable(dir)) fail(`${dir} does not look like the upstream harness: no ${MANIFEST}`);
         return { dir, temporary: false };
     }
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "harness-"));
     say(`cloning ${TEMPLATE} at ${ref}`);
     const r = lib.run("git", [...GIT, "clone", "--quiet", "--branch", ref, TEMPLATE, dir]);
-    if (r.status !== 0) fail(`could not clone the upstream at ${ref}\n${r.output}`);
+    if (r.status !== 0) { fs.rmSync(dir, { recursive: true, force: true }); fail(`could not clone the upstream at ${ref}\n${r.output}`); }
     if (!usable(dir)) {
         fs.rmSync(dir, { recursive: true, force: true });
         fail(`${TEMPLATE} at ${ref} carries no ${MANIFEST}, so there is nothing to install from; try another --ref`);
@@ -129,17 +149,29 @@ function templateCheckout(ref) {
     return { dir, temporary: true };
 }
 
-// The installer's own name and version, read from the package it ships inside rather than written
-// down here, so a release cannot forget to update it. It answers what the upstream commit cannot:
-// which released tool wrote this tree. Both routes land on the right file, because the script always
-// sits in the scripts/ folder of either the npm package or a checkout of the upstream. Omitted
-// rather than recorded as null when it cannot be read, so the receipt never claims a version it
-// does not know.
+// The installer's own name and version: which released tool wrote this tree, the one thing the
+// upstream commit cannot answer. package.json holds 0.0.0 on every branch and only the release job
+// writes the real version into it, just before the publish, so its number means something only
+// inside the npm package. A checkout of the upstream reads the release tag on its own HEAD instead.
+// A checkout on no tag is not a release, and the receipt names no package rather than a version
+// that was never published. Omitted, never null, whenever it cannot be read, so the receipt never
+// claims a version it does not know.
+const PLACEHOLDER_VERSION = "0.0.0";
+const RELEASE_TAG = /^\d+\.\d+\.\d+$/;
+function installerStamp({ name, version, tag }) {
+    if (!name) return {};
+    if (version && version !== PLACEHOLDER_VERSION) return { installer: `${name}@${version}` };
+    return tag && RELEASE_TAG.test(tag) ? { installer: `${name}@${tag}` } : {};
+}
+// The reads behind installerStamp. The script sits in the scripts/ folder of either the npm package
+// or a checkout of the upstream, so both files are one folder up; the package has no .git, and there
+// git answers nothing.
 function installer() {
-    try {
-        const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf8"));
-        return pkg.name && pkg.version ? { installer: `${pkg.name}@${pkg.version}` } : {};
-    } catch { return {}; }
+    const home = path.resolve(__dirname, "..");
+    let pkg = {};
+    try { pkg = JSON.parse(fs.readFileSync(path.join(home, "package.json"), "utf8")); } catch { return {}; }
+    const described = at(home, ["describe", "--tags", "--exact-match", "HEAD"]);
+    return installerStamp({ name: pkg.name, version: pkg.version, tag: described.status === 0 ? described.output.trim() : null });
 }
 
 // Windows stops at 260 characters for a path, and the harness ships skill files nested deep enough
@@ -151,8 +183,7 @@ function installer() {
 const GIT = ["-c", "core.longpaths=true"];
 const at = (dir, args) => lib.run("git", [...GIT, "-C", dir, ...args]);
 
-// The upstream's version of a path at a commit, or null when the file did not exist there. Also how
-// a missing base is detected: a rewritten history no longer holds the recorded commit.
+// The upstream's version of a path at a commit, or null when the file did not exist there.
 // Read raw rather than through lib.run, which trims trailing whitespace: that is right for the
 // plumbing whose output is a hash or a status line, and wrong for a file. Trimmed, every installed
 // file lost its final newline, no copy was ever byte-identical to the upstream, and so every later
@@ -173,6 +204,82 @@ const same = (a, b) => Buffer.isBuffer(a) || Buffer.isBuffer(b)
     ? Buffer.isBuffer(a) && Buffer.isBuffer(b) && a.equals(b)
     : a === b;
 
+// ---------------------------------------------------------------- the adapters
+//
+// What plan() reads, and nothing more: the upstream at any commit, and the target as it stands. A
+// real run backs them with the upstream's git checkout and the target's directory; the suite backs
+// them with maps, so a whole install is a table row rather than a clone and a temp tree.
+
+// Every blob in one commit, read in two calls rather than one `git show` per path: an install reads
+// every file at the head, and a process per file made a first install take most of a minute on
+// Windows. Keyed by path, holding what blob() would return; a submodule entry is not a blob and is
+// left out, as `git show` would fail on it too.
+function treeBlobs(dir, commit) {
+    const listing = spawnSync("git", [...GIT, "-C", dir, "ls-tree", "-r", "-z", commit], { maxBuffer: 64 * 1024 * 1024 });
+    if (listing.status !== 0) return null;
+    const entries = listing.stdout.toString("utf8").split("\0").filter(Boolean)
+        .map(line => { const tab = line.indexOf("\t"); const [, type, oid] = line.slice(0, tab).split(" "); return { type, oid, file: line.slice(tab + 1) }; })
+        .filter(e => e.type === "blob");
+    const r = spawnSync("git", [...GIT, "-C", dir, "cat-file", "--batch"],
+        { input: entries.map(e => e.oid).join("\n") + "\n", maxBuffer: 1024 * 1024 * 1024 });
+    if (r.status !== 0) return null;
+    const blobs = new Map();
+    let at = 0;
+    for (const { file } of entries) {
+        const eol = r.stdout.indexOf(10, at);
+        const size = Number(r.stdout.toString("utf8", at, eol).split(" ")[2]);
+        const bytes = r.stdout.subarray(eol + 1, eol + 1 + size);
+        blobs.set(file, bytes.includes(0) ? Buffer.from(bytes) : bytes.toString("utf8"));
+        at = eol + 1 + size + 1;
+    }
+    return blobs;
+}
+
+function gitUpstream(dir, head) {
+    let atHead;
+    return {
+        // Every path the upstream tracks, with the mode Git recorded. Mode 120000 is a symlink, and
+        // the harness has two kinds: .claude/agents pointing at .agents/agents, and one per skill
+        // under .claude/skills. Written as ordinary files they become text files holding a path,
+        // which is how a harness ends up looking installed while the agent sees no skills at all.
+        files() {
+            const rows = repoView.indexModes(dir);
+            if (!rows) fail(`could not list the upstream's files in ${dir}`);
+            return rows.map(({ file, link, exec }) => ({ file, link, exec }));
+        },
+        // The head is read whole on first use; any other commit, which only a base or a base search
+        // asks for, one path at a time.
+        blob(commit, file) {
+            if (commit !== head) return blob(dir, commit, file);
+            if (atHead === undefined) atHead = treeBlobs(dir, head);
+            if (atHead === null) return blob(dir, commit, file);
+            return atHead.has(file) ? atHead.get(file) : null;
+        },
+        // A rewritten history no longer holds the recorded commit, which leaves the run without a base.
+        hasCommit: commit => at(dir, ["cat-file", "-e", `${commit}^{commit}`]).status === 0,
+        // The commits that touched a path, newest first.
+        history(file) {
+            const r = at(dir, ["log", "--format=%H", "--", file]);
+            return r.status === 0 ? r.output.split(/\r?\n/).filter(Boolean) : [];
+        },
+    };
+}
+
+function fsTarget(root) {
+    const full = file => path.join(root, file);
+    return {
+        exists: file => fs.existsSync(full(file)),
+        // A Buffer when asked for bytes, text otherwise.
+        read: (file, binary) => binary ? fs.readFileSync(full(file)) : fs.readFileSync(full(file), "utf8"),
+        // null when nothing is there; otherwise whether it is a symlink, and where it points.
+        lstat(file) {
+            let s;
+            try { s = fs.lstatSync(full(file)); } catch { return null; }
+            return s.isSymbolicLink() ? { link: fs.readlinkSync(full(file)).split(path.sep).join("/") } : { link: null };
+        },
+    };
+}
+
 // The receipt is missing, so the base is found instead: the upstream version this copy is closest to
 // is where the project forked from, whatever a receipt would have said. An exact match is the clean
 // case, an older copy nobody touched; a project that has since edited its own file matches nothing
@@ -183,17 +290,15 @@ const same = (a, b) => Buffer.isBuffer(a) || Buffer.isBuffer(b)
 // Under half the lines in common is a different file, not an older one, and merging against it would
 // invent a diff the project never made.
 const NEAREST = 0.5;
-function recoverBase(dir, file, ours) {
-    const r = at(dir, ["log", "--format=%H", "--", file]);
-    if (r.status !== 0) return null;
+function recoverBase(upstream, file, ours) {
     const want = lineCounts(ours);
     let best = null;
     let nearest = NEAREST;
     // Oldest first, and a tie goes to the first seen: two upstream versions one line apart score the
     // same against a copy that has neither, and the older of them is the one whose merge puts that
     // line back. The newer would drop it silently, which is the failure this policy exists to stop.
-    for (const commit of r.output.split(/\r?\n/).filter(Boolean).reverse()) {
-        const text = blob(dir, commit, file);
+    for (const commit of upstream.history(file).reverse()) {
+        const text = upstream.blob(commit, file);
         if (typeof text !== "string") continue;
         if (text === ours) return text;
         const shared = overlap(want, lineCounts(text));
@@ -242,59 +347,6 @@ function policyFor(rows, file, wants) {
     return wants(row.policy.slice("optional:".length)) ? "seed" : "template";
 }
 
-// Every path the upstream tracks, with the mode Git recorded. Mode 120000 is a symlink, and the
-// harness has two kinds: .claude/agents pointing at .agents/agents, and one per skill under
-// .claude/skills. Written as ordinary files they become text files holding a path, which is how a
-// harness ends up looking installed while the agent sees no skills and no agents at all.
-function templateFiles(dir) {
-    const r = at(dir, ["ls-files", "-s"]);
-    if (r.status !== 0) fail(`could not list the upstream's files\n${r.output}`);
-    return r.output.split(/\r?\n/).filter(Boolean).map(line => {
-        const [meta, file] = line.split("\t");
-        return { file, link: meta.startsWith("120000"), exec: meta.startsWith("100755") };
-    });
-}
-
-// Git runs a hook only if it is executable, and says nothing when it is not: an installed harness
-// whose hooks are mode 644 looks installed and gates nothing. The upstream records them 100755, so
-// that mode has to travel, and only Git can carry it. `chmod` alone is not enough -- on Windows
-// core.fileMode is false and the call does nothing, so the file would be staged 100644 later and the
-// hooks would run for whoever installed them and silently never run for anyone else. `git add
-// --chmod=+x` writes the mode into the index whether or not the file was tracked, which is why the
-// install stages these few files rather than leaving them for the project's own `git add`.
-function carryMode(target, file) {
-    try { fs.chmodSync(path.join(target, file), 0o755); } catch { /* the filesystem does not do modes */ }
-    const r = lib.run("git", [...GIT, "-C", target, "add", "--chmod=+x", "--", file]);
-    if (r.status !== 0) say(`could not mark ${file} executable: ${r.output}`);
-}
-
-// A symlink recorded in Git is a blob holding its target. Windows needs Developer Mode and
-// core.symlinks=true for this to work at all, so a refusal is reported rather than thrown: the
-// harness still functions with the links missing, it is just invisible to the harnesses that read
-// them, and README says how to turn them on.
-function link(target, file, to) {
-    const full = path.join(target, file);
-    if (dryRun) return "written";
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    let existing = null;
-    try { existing = fs.lstatSync(full); } catch { /* absent */ }
-    if (existing) {
-        // Something of the project's is in the way -- or, in a repo whose harness predates the lock
-        // file, the link itself checked out as a text file holding a path, which is the failure that
-        // leaves an agent seeing no skills at all. --adopt is the only thing that replaces it.
-        if (!existing.isSymbolicLink()) { if (!adopt) return "kept"; fs.unlinkSync(full); }
-        else if (fs.readlinkSync(full).split(path.sep).join("/") === to) return null;
-        else fs.unlinkSync(full);
-    }
-    try {
-        fs.symlinkSync(to.split("/").join(path.sep), full, "dir");
-        return existing ? "merged" : "written";
-    } catch (e) {
-        say(`could not create the symlink ${file} -> ${to}: ${e.code || e.message}`);
-        return "kept";
-    }
-}
-
 // ---------------------------------------------------------------- skeletons
 
 // Three files the upstream does not ship, because there they would be lies: MEMORY.md
@@ -311,14 +363,6 @@ const SKELETONS = {
         "`pre-commit` and `pre-push` hooks refuse to let work leave a clone while any value is still a",
         "`<placeholder>`.",
         "",
-        "- **Name:** <name>",
-        "- **Purpose:** <purpose>",
-        "- **Prose language:** <prose language>",
-        "- **Requirements:** <requirements>",
-        "- **Unit type:** <unit type>",
-        "- **Language:** <language>",
-        "- **Runtime / package manager:** <runtime>",
-        "",
     ],
     "CONTEXT.md": [
         "# Context",
@@ -338,21 +382,13 @@ const SKELETONS = {
     ],
 };
 
-// A repo that already has an INTENT.md names the product and its purpose there, so the MEMORY.md
-// laid down beside it leaves those two out rather than asking for them a second time.
-function skeletonLines(target, file, lines) {
-    if (file !== "MEMORY.md" || !fs.existsSync(path.join(target, "INTENT.md"))) return lines;
-    const facts = lines.filter(l => !/^- \*\*(?:Name|Purpose):\*\*/.test(l));
-    const first = facts.findIndex(l => l.startsWith("- **"));
-    return [...facts.slice(0, first), "The name and purpose are in `INTENT.md`, under `## Product`.", "", ...facts.slice(first)];
-}
-
-function skeletons(target) {
-    for (const [file, lines] of Object.entries(SKELETONS)) {
-        if (fs.existsSync(path.join(target, file))) { step("seed", "100644", "yours", file); continue; }
-        write(target, file, skeletonLines(target, file, lines).join("\n"));
-        step("seed", "100644", "created", file, "seeded");
-    }
+// MEMORY.md's fact lines come from scripts/project-facts.js, the table the gate checks them against,
+// so a skeleton never asks for a fact the gate does not know or leaves out one it requires. A repo
+// that already has an INTENT.md names the product and its purpose there, so the MEMORY.md laid down
+// beside it leaves those two out rather than asking for them a second time.
+function skeletonLines(file, lines, hasIntent) {
+    if (file !== projectFacts.MEMORY) return lines;
+    return [...lines, ...projectFacts.skeleton(hasIntent), ""];
 }
 
 // ---------------------------------------------------------------- merging
@@ -372,25 +408,6 @@ function threeWay(base, ours, theirs) {
     } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 }
 
-// ---------------------------------------------------------------- reporting
-
-const notes = { written: [], merged: [], conflicted: [], seeded: [], kept: [], skipped: [], template: [], unreadable: [], check: null };
-const say = m => console.log(m);
-function fail(m) { console.error(`update-harness: ${m}`); process.exit(1); }
-
-// An install rewrites someone else's repository, so it says what it did to every path while it does
-// it, and --quiet asks for the summary alone. The mode is worth a column of its own: a hook that
-// lands 100644 gates nothing and a skill link written as a regular file leaves the agent with no
-// skills, and both look installed. One call records the outcome and prints the line, so the running
-// commentary and the summary below cannot drift apart.
-const quiet = flag("--quiet");
-const mode = f => f.link ? "120000" : f.exec ? "100755" : "100644";
-function step(policy, m, outcome, file, bucket) {
-    if (bucket) notes[bucket].push(file);
-    if (!quiet) say(`  ${policy.padEnd(9)}${m}  ${outcome.padEnd(12)}${file}`);
-}
-const phase = m => { if (!quiet) say(`\n${m}`); };
-
 // Git checks a repo out with the platform's line endings, so a Windows working copy holds CRLF where
 // the upstream stores LF. Compared raw, every line of every file reads as changed: a copy nobody
 // touched reports as edited, and a real edit is buried in a whole-file conflict nobody can read. So
@@ -409,14 +426,11 @@ const asFound = (text, crlf) => crlf ? text.replace(LF, "\r\n") : text;
 //
 // What happens to one file the target already has, decided apart from doing it. Everything these two
 // read is an argument, including the three things they cannot compute -- the base's text, the search
-// for a base when the receipt has none, and the three-way merge itself -- so the caller passes them
-// in and the loop below is left reading, writing and reporting.
+// for a base when the receipt has none, and the three-way merge itself -- so plan() passes them in.
 //
 // Both answer the same shape: `outcome` is the word the run prints, `bucket` the summary list it
 // belongs in (null for a file nothing happened to), and `text` what to write, or null to write
-// nothing. Splitting them this way is what makes the table of cases testable: an install rewrites
-// someone else's repository, and every branch below used to need a git checkout and a temp tree to
-// reach even once.
+// nothing.
 
 // A file with no lines to merge: it is the upstream's copy or it is the project's, and the base
 // decides which. A logo the project replaced stays replaced.
@@ -468,246 +482,290 @@ function decideText({ policy, raw, theirs, hasBase, adopt }, { baseText, recover
     return { outcome: "merged", bucket: "merged", text: result };
 }
 
-function write(target, file, text, exec) {
-    const full = path.join(target, file);
-    if (dryRun) return;
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    fs.writeFileSync(full, text);
-    if (exec) carryMode(target, file);
-}
-
-// ---------------------------------------------------------------- the self check
-
-// Merging is not checking. The installer knows it wrote a file; it cannot know whether the result
-// still works -- an AGENTS.md whose chain table no longer parses, routing sections naming an agent
-// this repo does not have, a skill nothing links to, an upstream with no licence row. Those are the
-// harness invariants, and scripts/check-harness.js holds them as functions of a root.
+// ---------------------------------------------------------------- the plan
 //
-// So they run from the upstream checkout against the target, and nothing is written into the target
-// to run them. The upstream's copy rather than the one just installed, so the check is the one that
-// matches the files this run wrote. The suite's fixtures stay upstream: they prove the harness
-// scripts, which the upstream's own CI has already done.
-function selfCheck(target, templateDir) {
-    const script = path.join(templateDir, "scripts", "check-harness.js");
-    if (!fs.existsSync(script)) return { skipped: "this upstream ref has no scripts/check-harness.js" };
-    phase("self check: the harness invariants, run from the upstream against this repo");
-    const harness = require(script);
-    const r = harness.check(target);
-    return { failed: r.failed.length > 0, summary: r.summary, output: harness.format(r) };
-}
-
-// ---------------------------------------------------------------- the run
-
-function main() {
-    if (flag("--help") || flag("-h")) { console.log(usage()); return; }
-    const mistyped = mistypedArgs(argv);
-    if (mistyped.length) fail(`unknown argument(s): ${mistyped.join(" ")}. Nothing was written; run with --help for the options.`);
-    const target = targetRoot();
-    if (!fs.existsSync(path.join(target, ".git"))) fail(`${target} is not a git checkout`);
-
-    const lockPath = path.join(target, LOCK);
-    const previous = fs.existsSync(lockPath) ? JSON.parse(fs.readFileSync(lockPath, "utf8")) : null;
-    const ref = value("--ref", previous ? previous.ref : DEFAULT_REF);
-    const { dir: templateDir, temporary } = templateCheckout(ref);
+// Everything a run will do to the target, decided before anything is written: an install rewrites
+// someone else's repository, and deciding and writing in the same loop left every branch but the
+// per-file decision reachable only through a git checkout and a temp tree. A dry run prints the plan;
+// a real run applies it. Each entry is one line of the run's output and at most one thing done to
+// one path:
+//   file, policy, mode, outcome, bucket   what the run prints, and the summary list the path joins
+//   write                                 the path's new content, text or a Buffer
+//   link, replace                         a symlink to `link`, replacing what is there when `replace`
+//   exec                                  mark the path executable, whether or not it is written
+//   mkdir                                 create the path's folder and nothing else
+//   silent                                counted in the summary, never printed as a line
+// and a { phase } entry heads each section of the output.
+const mode = f => f.link ? "120000" : f.exec ? "100755" : "100644";
+const SKILLS = ".agents/skills/";
+
+// `previous` is the target's harness-lock.json, or null; `stamp` is what the receipt records about
+// this run besides the upstream commit, passed in so a plan is the same whenever it is made.
+function plan({ upstream, target, rows, head, ref, previous, options, stamp = {} }) {
+    const entries = [];
+    const notices = [];
+    const add = e => entries.push(e);
+
+    // A base is what makes this an update rather than an overwrite. Without one -- a first install,
+    // or an upstream whose history was rewritten -- an existing file is left alone instead of being
+    // guessed at, and the run says so.
+    let base = previous ? previous.commit : null;
+    if (base && !upstream.hasCommit(base)) {
+        notices.push(`the recorded upstream commit ${base.slice(0, 8)} is not in ${TEMPLATE} any more, so this run has no merge base: existing files are left alone`);
+        base = null;
+    }
+    // --adopt is how a repo whose harness files are wrong gets them replaced, and the commonest way to
+    // reach that state is an install that wrote the receipt and kept a stale harness. So the run stays
+    // open at the recorded commit, and main() answers "nothing to update" only without --adopt.
+    if (previous && base === head) notices.push(`harness is already at ${head.slice(0, 8)} (${ref}); --adopt takes every harness file again anyway`);
+
+    // A repo carrying a harness from before harness-lock.json existed. Without a base the rule below
+    // keeps every file that is already there, which protects the project's work and also preserves
+    // the old harness: its checks then run against the new skills and agents and fail, naming rules
+    // this version dropped. Worth saying out loud, because the run otherwise looks like a success.
+    const MARKERS = [".agents/hooks/lib.js", "scripts/lib.js", ".githooks/pre-commit"];
+    const stale = previous ? [] : MARKERS.filter(f => target.exists(f));
+    if (stale.length) {
+        notices.push(options.adopt
+            ? `this repo has a harness but no ${LOCK}, and --adopt was given: harness files are replaced with ${ref}'s, and edits to them are lost`
+            : `this repo has a harness (${stale.join(", ")}) but no ${LOCK}, so it predates the receipt and there is no merge base.\nEvery harness file already here is kept, which leaves old checks running against new skills. Re-run with --adopt to replace them, or --dry-run --quiet to list them first.`);
+    }
 
-    try {
-        // Checked before anything is said about the target, so a bad argument is the only message.
-        const rows = policies(templateDir);
-        const optional = rows.filter(r => r.policy.startsWith("optional:")).map(r => r.policy.slice("optional:".length));
-        const unknown = unknownArgs(argv, optional);
-        if (unknown.length) {
-            if (temporary) fs.rmSync(templateDir, { recursive: true, force: true });
-            fail(`unknown argument(s): ${unknown.join(" ")}. Nothing was written; run with --help for the options.`);
-        }
-        const head = at(templateDir, ["rev-parse", "HEAD"]).output.trim();
-        // A base is what makes this an update rather than an overwrite. Without one -- a first
-        // install, or an upstream whose history was rewritten -- an existing file is left alone
-        // instead of being guessed at, and the run says so.
-        let base = previous ? previous.commit : null;
-        if (base && at(templateDir, ["cat-file", "-e", `${base}^{commit}`]).status !== 0) {
-            say(`the recorded upstream commit ${base.slice(0, 8)} is not in ${TEMPLATE} any more, so this run has no merge base: existing files are left alone`);
-            base = null;
-        }
-        // --adopt is how a repo whose harness files are wrong gets them replaced, and the commonest
-        // way to reach that state is an install that wrote the receipt and kept a stale harness. So
-        // the run has to stay open at the recorded commit: short-circuiting here would answer the
-        // one command that fixes it with "nothing to update".
-        if (previous && base === head && !adopt) { say(`harness is already at ${head.slice(0, 8)} (${ref}); nothing to update`); return; }
-        if (previous && base === head) say(`harness is already at ${head.slice(0, 8)} (${ref}); --adopt takes every harness file again anyway`);
-
-        // A repo carrying a harness from before harness-lock.json existed. Without a base the rule
-        // below keeps every file that is already there, which protects the project's work and also
-        // preserves the old harness: its checks then run against the new skills and agents and fail,
-        // naming rules this version dropped. Worth saying out loud, because the run otherwise looks
-        // like a success.
-        const MARKERS = [".agents/hooks/lib.js", "scripts/lib.js", ".githooks/pre-commit"];
-        const stale = !previous && MARKERS.filter(f => fs.existsSync(path.join(target, f)));
-        if (stale && stale.length) {
-            if (adopt) say(`this repo has a harness but no ${LOCK}, and --adopt was given: harness files are replaced with ${ref}'s, and edits to them are lost`);
-            else say(`this repo has a harness (${stale.join(", ")}) but no ${LOCK}, so it predates the receipt and there is no merge base.\nEvery harness file already here is kept, which leaves old checks running against new skills. Re-run with --adopt to replace them, or --dry-run --quiet to list them first.`);
+    const files = upstream.files();
+    const skills = [];
+    add({ phase: `${files.length} path(s) in ${ref} at ${head.slice(0, 8)}` });
+    for (const entry of files) {
+        const { file, link: isLink, exec } = entry;
+        const policy = policyFor(rows, file, options.wants);
+        const m = mode(entry);
+        const theirs = upstream.blob(head, file);
+        // Git listed the path a moment ago, so failing to read it is the checkout being unhappy
+        // rather than the file being absent. Said out loud: skipped quietly, the run reports a clean
+        // install of a harness missing whichever files the reader was never told about.
+        if (theirs === null) { add({ file, policy, mode: m, outcome: "UNREADABLE", bucket: "unreadable" }); continue; }
+        const exists = target.exists(file);
+        // The executable bit is not the project's content, so a file kept for its content still has
+        // its mode corrected. Git runs a hook only if it is executable and says nothing when it is
+        // not, so a hook kept at 100644 by an install that had no merge base looks installed and
+        // gates nothing at all -- the failure the mode column exists to catch.
+        const line = (outcome, bucket, act = {}) =>
+            add({ file, policy, mode: m, outcome, bucket, ...act, exec: exec && (exists || act.write !== undefined) });
+
+        // Not installed anywhere, and named in one line of the summary instead: sixty-five lines
+        // saying nothing happened bury the thirty-eight saying something did.
+        if (policy === "template") { line("template", "template", { silent: true }); continue; }
+        if (isLink) {
+            // A skill link is relink's to make, once the directory it lives in exists: it knows which
+            // skills this project actually has, where the upstream only knows its own.
+            if (policy === "skills") { add({ file, mkdir: true, silent: true }); continue; }
+            const to = theirs.trim();
+            const found = target.lstat(file);
+            // Something of the project's in the way -- or, in a repo whose harness predates the lock
+            // file, the link itself checked out as a text file holding a path, which is the failure
+            // that leaves an agent seeing no skills at all. --adopt is the only thing that replaces it.
+            if (!found) line("written", "written", { link: to });
+            else if (!found.link) line(options.adopt ? "merged" : "yours", options.adopt ? "merged" : "kept", options.adopt ? { link: to, replace: true } : {});
+            else if (found.link === to) line("unchanged", null);
+            else line("merged", "merged", { link: to, replace: true });
+            continue;
         }
-
-        const wants = name => flag(`--${name}`);
-        const files = templateFiles(templateDir);
-        const skills = [];
-
-        phase(`${files.length} path(s) in ${ref} at ${head.slice(0, 8)}`);
-        for (const entry of files) {
-            const { file, link: isLink, exec } = entry;
-            const policy = policyFor(rows, file, wants);
-            const m = mode(entry);
-            const theirs = blob(templateDir, head, file);
-            // Git listed the path a moment ago, so failing to read it is the checkout being unhappy
-            // rather than the file being absent. Said out loud: skipped quietly, the run reports a
-            // clean install of a harness missing whichever files the reader was never told about.
-            if (theirs === null) { step(policy, m, "UNREADABLE", file, "unreadable"); continue; }
-            const full = path.join(target, file);
-            const exists = fs.existsSync(full);
-
-            // The executable bit is not the project's content, so a file kept for its content still
-            // has its mode corrected. Git runs a hook only if it is executable and says nothing when
-            // it is not, so a hook kept at 100644 by an install that had no merge base looks
-            // installed and gates nothing at all -- the failure this whole column exists to catch.
-            if (exec && exists && !dryRun) carryMode(target, file);
-
-            // Not installed anywhere, and named in one line of the summary instead: sixty-five
-            // lines saying nothing happened bury the thirty-eight saying something did.
-            if (policy === "template") { notes.template.push(file); continue; }
-            if (isLink) {
-                // A skill link is relink's to make, once the directory it lives in exists: it knows
-                // which skills this project actually has, where the upstream only knows its own.
-                if (policy === "skills") {
-                    if (!dryRun) fs.mkdirSync(path.dirname(full), { recursive: true });
-                    continue;
-                }
-                const how = link(target, file, theirs.trim());
-                step(policy, m, how === "kept" ? "yours" : how || "unchanged", file, how);
-                continue;
-            }
-            // Reported one line per skill by mergeSkills below, not one per reference file: a skill
-            // is the unit a project installs, and its files run to several hundred.
-            if (policy === "skills") { skills.push(file); continue; }
-            // Reported only when the target actually has it: "left alone, yours" about a file the
-            // repo does not have names something that was never there.
-            if (policy === "skip") { step(policy, m, exists ? "yours" : "absent", file, exists && "skipped"); continue; }
-
-            if (policy === "seed") {
-                if (exists) { step(policy, m, "yours", file, "kept"); continue; }
-                write(target, file, theirs, exec);
-                step(policy, m, "created", file, "seeded");
-                continue;
-            }
-            // merge
-            if (!exists) { write(target, file, theirs, exec); step(policy, m, "written", file, "written"); continue; }
-
-            // Everything the decision needs, read here; what to do with its answer, done here. The
-            // decision itself is decideBinary/decideText, which touch neither git nor the disk.
-            const hasBase = base !== null;
-            const held = Buffer.isBuffer(theirs) ? fs.readFileSync(full) : fs.readFileSync(full, "utf8");
-            const { outcome, bucket, text } = Buffer.isBuffer(theirs)
-                ? decideBinary({ held, theirs, hasBase, adopt }, { baseBytes: () => blob(templateDir, base, file) })
-                : decideText({ policy, raw: held, theirs, hasBase, adopt }, {
-                    baseText: () => blob(templateDir, base, file),
-                    recoverBase: ours => recoverBase(templateDir, file, ours),
-                    merge: threeWay,
-                });
-            if (text !== null) write(target, file, text, exec);
-            step(policy, m, outcome, file, bucket);
+        // Reported one line per skill by planSkills below, not one per reference file: a skill is the
+        // unit a project installs, and its files run to several hundred.
+        if (policy === "skills") { skills.push(entry); continue; }
+        // Reported only when the target actually has it: "left alone, yours" about a file the repo
+        // does not have names something that was never there.
+        if (policy === "skip") { line(exists ? "yours" : "absent", exists ? "skipped" : null); continue; }
+        if (policy === "seed") {
+            if (exists) line("yours", "kept");
+            else line("created", "seeded", { write: theirs });
+            continue;
         }
+        // merge and reconcile
+        if (!exists) { line("written", "written", { write: theirs }); continue; }
+        const hasBase = base !== null;
+        const held = target.read(file, Buffer.isBuffer(theirs));
+        const { outcome, bucket, text } = Buffer.isBuffer(theirs)
+            ? decideBinary({ held, theirs, hasBase, adopt: options.adopt }, { baseBytes: () => upstream.blob(base, file) })
+            : decideText({ policy, raw: held, theirs, hasBase, adopt: options.adopt }, {
+                baseText: () => upstream.blob(base, file),
+                recoverBase: ours => recoverBase(upstream, file, ours),
+                merge: threeWay,
+            });
+        line(outcome, bucket, text === null ? {} : { write: text });
+    }
 
-        phase("skeletons a project starts with");
-        skeletons(target);
-        phase("skills, merged by name");
-        mergeSkills(target, templateDir, head, skills);
-
-        if (!dryRun) {
-            fs.writeFileSync(lockPath, JSON.stringify({
-                template: TEMPLATE, ref, commit: head, ...installer(),
-                updated: new Date().toISOString().slice(0, 10),
-            }, null, 2) + "\n");
-            finish(target);
-            // After finish(), because the invariants check the links relink has just written.
-            if (!flag("--no-check")) notes.check = selfCheck(target, templateDir);
-        }
-        report(target, head, ref, base);
-    } finally {
-        if (temporary) fs.rmSync(templateDir, { recursive: true, force: true });
+    add({ phase: "skeletons a project starts with" });
+    const hasIntent = target.exists(projectFacts.INTENT);
+    for (const [file, lines] of Object.entries(SKELETONS)) {
+        if (target.exists(file)) add({ file, policy: "seed", mode: "100644", outcome: "yours", bucket: null });
+        else add({ file, policy: "seed", mode: "100644", outcome: "created", bucket: "seeded", write: skeletonLines(file, lines, hasIntent).join("\n") });
     }
+
+    add({ phase: "skills, merged by name" });
+    entries.push(...planSkills(upstream, target, head, skills));
+
+    add({ file: LOCK, silent: true, write: JSON.stringify({ template: TEMPLATE, ref, commit: head, ...stamp }, null, 2) + "\n" });
+    return { entries, notices, base };
 }
 
 // Skills merge by name, not by content: the upstream's are added and updated, and a skill the
 // project vendored itself is never removed. skills-lock.json is the union, the project's entry
 // winning where both name the same skill, so a project that pinned a different source keeps it.
-function mergeSkills(target, templateDir, head, files) {
-    const SKILLS = ".agents/skills/";
-    const ours = path.join(target, "skills-lock.json");
-    const theirLock = JSON.parse(blob(templateDir, head, "skills-lock.json") || '{"skills":{}}');
-    const ourLock = fs.existsSync(ours) ? JSON.parse(fs.readFileSync(ours, "utf8")) : { skills: {} };
+function planSkills(upstream, target, head, files) {
+    const LOCKFILE = "skills-lock.json";
+    const theirLock = JSON.parse(upstream.blob(head, LOCKFILE) || '{"skills":{}}');
+    const ourLock = target.exists(LOCKFILE) ? JSON.parse(target.read(LOCKFILE)) : { skills: {} };
     ourLock.skills = ourLock.skills || {};
-
     const mine = new Set(Object.keys(ourLock.skills));
-    // One line per skill, not per file. Outcome is decided across the whole folder: a skill counts
-    // as changed the moment any file in it did, and only an untouched folder reads "unchanged".
+
+    const out = [];
+    // One line per skill, not per file. Outcome is decided across the whole folder: a skill counts as
+    // changed the moment any file in it did, and only an untouched folder reads "unchanged".
     const outcomes = new Map();
     const seen = name => outcomes.get(name) || outcomes.set(name, { added: 0, updated: 0, files: 0 }).get(name);
-    for (const file of files) {
+    for (const { file, exec } of files) {
         if (!file.startsWith(SKILLS)) continue;                 // .claude/skills links are rebuilt, not copied
         const name = file.slice(SKILLS.length).split("/")[0];
         const tally = seen(name);
         tally.files++;
+        const exists = target.exists(file);
+        // A script the skill runs keeps its executable bit whoever owns the content, as a hook does.
+        if (exec && exists) out.push({ file, silent: true, exec: true });
         // A skill the project installed under a name the upstream also uses stays the project's.
         if (mine.has(name) && !theirLock.skills[name]) { tally.yours = true; continue; }
-        const text = blob(templateDir, head, file);
+        const text = upstream.blob(head, file);
         if (text === null) continue;
-        const full = path.join(target, file);
-        const exists = fs.existsSync(full);
         // A vendored file the project has not touched still differs byte-for-byte on Windows, where
         // Git checked it out with CRLF. Compared raw, every skill would report as updated every run.
-        const held = exists ? fs.readFileSync(full) : null;
+        const held = exists ? target.read(file, true) : null;
+        let write;
         if (Buffer.isBuffer(text)) {
             if (same(held, text)) continue;
-            write(target, file, text);
+            write = text;
         } else {
             const ourText = held === null ? null : held.toString("utf8");
             if (ourText !== null && toLf(ourText) === text) continue;
-            write(target, file, asFound(text, ourText !== null && isCrlf(ourText)));
+            write = asFound(text, ourText !== null && isCrlf(ourText));
         }
-        if (exists) { tally.updated++; notes.merged.push(file); }
-        else { tally.added++; notes.written.push(file); }
+        if (exists) tally.updated++; else tally.added++;
+        out.push({ file, silent: true, write, bucket: exists ? "merged" : "written", exec: exec && !exists });
     }
     for (const [name, t] of [...outcomes].sort()) {
         const what = t.yours ? "yours" : t.added ? "added" : t.updated ? "updated" : "unchanged";
-        step("skills", "100644", what, `${SKILLS}${name}  (${t.files} file(s))`);
+        out.push({ file: `${SKILLS}${name}  (${t.files} file(s))`, policy: "skills", mode: "100644", outcome: what, bucket: null });
     }
     for (const [name, entry] of Object.entries(theirLock.skills)) {
         if (!ourLock.skills[name]) ourLock.skills[name] = entry;
     }
-    if (!dryRun) fs.writeFileSync(ours, JSON.stringify(ourLock, null, 2) + "\n");
+    out.push({ file: LOCKFILE, silent: true, write: JSON.stringify(ourLock, null, 2) + "\n" });
+    return out;
 }
 
+// ---------------------------------------------------------------- applying it
+
+// Git runs a hook only if it is executable, and says nothing when it is not: an installed harness
+// whose hooks are mode 644 looks installed and gates nothing. The upstream records them 100755, so
+// that mode has to travel, and only Git can carry it. `chmod` alone is not enough -- on Windows
+// core.fileMode is false and the call does nothing, so the file would be staged 100644 later and the
+// hooks would run for whoever installed them and silently never run for anyone else. `git add
+// --chmod=+x` writes the mode into the index whether or not the file was tracked, which is why the
+// install stages these few files rather than leaving them for the project's own `git add`.
+// Returns why it failed, or null.
+function carryMode(root, file) {
+    try { fs.chmodSync(path.join(root, file), 0o755); } catch { /* the filesystem does not do modes */ }
+    const r = lib.run("git", [...GIT, "-C", root, "add", "--chmod=+x", "--", file]);
+    return r.status === 0 ? null : `could not mark ${file} executable: ${r.output}`;
+}
+
+// Carries out one entry. Returns null when it went as planned, or what happened instead: `why` to
+// print, and the `outcome` and `bucket` the run reports in place of the plan's.
+function perform(root, e) {
+    const full = path.join(root, e.file);
+    if (e.mkdir || e.link !== undefined || e.write !== undefined) fs.mkdirSync(path.dirname(full), { recursive: true });
+    if (e.link !== undefined) {
+        if (e.replace) fs.unlinkSync(full);
+        // Windows needs Developer Mode and core.symlinks=true for this to work at all, so a refusal
+        // is reported rather than thrown: the harness still functions with the link missing, it is
+        // just invisible to the harnesses that read it, and README says how to turn them on.
+        try { fs.symlinkSync(e.link.split("/").join(path.sep), full, "dir"); }
+        catch (err) { return { outcome: "yours", bucket: "kept", why: `could not create the symlink ${e.file} -> ${e.link}: ${err.code || err.message}` }; }
+        return null;
+    }
+    if (e.write !== undefined) fs.writeFileSync(full, e.write);
+    if (e.exec) { const why = carryMode(root, e.file); if (why) return { why }; }
+    return null;
+}
+
+// An install rewrites someone else's repository, so it says what it did to every path while it does
+// it, and --quiet asks for the summary alone. The mode is worth a column of its own: a hook that
+// lands 100644 gates nothing and a skill link written as a regular file leaves the agent with no
+// skills, and both look installed. A dry run prints the same lines straight from the plan.
+// Returns the entries as they turned out, which the summary is built from.
+function apply(entries, root, options) {
+    const done = [];
+    for (const e of entries) {
+        if (e.phase) { if (!options.quiet) say(`\n${e.phase}`); continue; }
+        let shown = e;
+        if (!options.dryRun) {
+            const fix = perform(root, e);
+            if (fix && fix.why) say(fix.why);
+            if (fix && fix.outcome) shown = { ...e, outcome: fix.outcome, bucket: fix.bucket };
+        }
+        if (!shown.silent && !options.quiet) say(`  ${shown.policy.padEnd(9)}${shown.mode}  ${shown.outcome.padEnd(12)}${shown.file}`);
+        done.push(shown);
+    }
+    return done;
+}
+
+// ---------------------------------------------------------------- after it
+
 // Two files nothing copied: the per-harness skill links, which depend on which skills this project
 // has rather than which the upstream ships, and the third-party notice, which must describe this
 // project's lock file. Both are generated, so the install leaves a harness that works rather than a
-// list of commands to remember.
-function finish(target) {
-    phase("links and notices");
+// list of commands to remember. Each run names the target with --root: the shared resolver prefers a
+// harness's project-dir variable to the checkout a script sits in, and an install started from a
+// session open on another repo would otherwise link and describe that repo instead.
+function finish(target, options) {
+    if (!options.quiet) say("\nlinks and notices");
     for (const [label, args] of [["links", ["relink"]], ["notices", ["notices"]]]) {
-        const r = lib.node([path.join(target, "scripts/skills.js"), ...args], { cwd: target });
+        const r = lib.node([path.join(target, "scripts/skills.js"), ...args, `${lib.ROOT_FLAG}${target}`], { cwd: target });
         say(r.status === 0 ? r.output : `${label}: ${r.output}`);
     }
 }
 
-function report(target, head, ref, base) {
+// Merging is not checking. The installer knows it wrote a file; it cannot know whether the result
+// still works -- an AGENTS.md whose chain table no longer parses, routing sections naming an agent
+// this repo does not have, a skill nothing links to, an upstream with no licence row. Those are the
+// harness invariants, and scripts/check-harness.js holds them as functions of a root.
+//
+// So they run from the upstream checkout against the target, and nothing is written into the target
+// to run them. The upstream's copy rather than the one just installed, so the check is the one that
+// matches the files this run wrote. The suite's fixtures stay upstream: they prove the harness
+// scripts, which the upstream's own CI has already done.
+function selfCheck(target, templateDir, options) {
+    const script = path.join(templateDir, "scripts", "check-harness.js");
+    if (!fs.existsSync(script)) return { skipped: "this upstream ref has no scripts/check-harness.js" };
+    if (!options.quiet) say("\nself check: the harness invariants, run from the upstream against this repo");
+    const harness = require(script);
+    const r = harness.check(target);
+    return { failed: r.failed.length > 0, summary: r.summary, output: harness.format(r) };
+}
+
+// The summary, from the entries as they turned out. Returns the exit code: 1 while anything is left
+// for the reader to act on.
+function report({ entries, base, head, ref, target, check, options }) {
+    const notes = { written: [], merged: [], conflicted: [], seeded: [], kept: [], skipped: [], template: [], unreadable: [] };
+    for (const e of entries) if (e.bucket) notes[e.bucket].push(e.file);
     // Every path was named as it happened, so repeating the lists here doubles the output; a quiet
     // run never saw them and gets them in full. Conflicts are listed either way: they are what the
     // reader has to act on, and they belong beside the instructions for acting on them.
     const list = (label, arr, always) => {
         if (!arr.length) return;
-        if (quiet || always) say(`\n${label} (${arr.length}):\n  ${arr.sort().join("\n  ")}`);
+        if (options.quiet || always) say(`\n${label} (${arr.length}):\n  ${arr.sort().join("\n  ")}`);
         else say(`\n${label}: ${arr.length}`);
     };
     say("");
-    say(dryRun ? `dry run against ${ref} at ${head.slice(0, 8)}` : `harness updated to ${ref} at ${head.slice(0, 8)}`);
+    say(options.dryRun ? `dry run against ${ref} at ${head.slice(0, 8)}` : `harness updated to ${ref} at ${head.slice(0, 8)}`);
     if (!base) say("no merge base: this was an install, so nothing that already existed was changed");
     list("added", notes.written);
     list("merged", notes.merged);
@@ -729,21 +787,74 @@ function report(target, head, ref, base) {
         list("CONFLICTED, resolve the markers by hand", notes.conflicted, true);
         say(`\nEach one holds <<<<<<< yours / ======= / >>>>>>> upstream (new). Resolve them, then check the harness:\n  node scripts/check-harness.js`);
     }
-    const check = notes.check;
     if (check && check.skipped) say(`\nself check skipped: ${check.skipped}`);
     else if (check && check.failed) say(`\nSELF CHECK FAILED, so this install does not work yet:\n${check.output}`);
     else if (check) say(`\nself check: ${check.summary}`);
 
-    if (!dryRun) {
+    if (!options.dryRun) {
         say(`\nIn ${target}, point Git at the hooks once per clone, then check the harness:`);
         say(`  node scripts/githooks-init.js && node scripts/check-harness.js`);
     }
-    if (notes.conflicted.length || notes.unreadable.length || (check && check.failed)) process.exit(1);
+    return notes.conflicted.length || notes.unreadable.length || (check && check.failed) ? 1 : 0;
 }
 
-// The decision, and the two pure helpers under it, so the suite can put a case in and read the
-// answer out rather than building a git checkout to reach one branch. Everything else here writes to
-// somebody's repository and stays behind main().
-module.exports = { unknownArgs, mistypedArgs, usage, policyFor, decideText, decideBinary, lineCounts, overlap, NEAREST, skeletonLines };
+// ---------------------------------------------------------------- the run
+
+// Returns the exit code, and throws Stop for a run that could not start.
+function main(args) {
+    const options = parseOptions(args);
+    if (options.help) { console.log(usage()); return 0; }
+    const mistyped = mistypedArgs(args);
+    if (mistyped.length) fail(`unknown argument(s): ${mistyped.join(" ")}. Nothing was written; run with --help for the options.`);
+    const target = targetRoot(options);
+    if (!fs.existsSync(path.join(target, ".git"))) fail(`${target} is not a git checkout`);
+
+    const lockPath = path.join(target, LOCK);
+    const previous = fs.existsSync(lockPath) ? JSON.parse(fs.readFileSync(lockPath, "utf8")) : null;
+    const ref = options.ref || (previous ? previous.ref : DEFAULT_REF);
+    const { dir: templateDir, temporary } = templateCheckout(ref, options);
 
-if (require.main === module) main();
+    try {
+        // Checked before anything is said about the target, so a bad argument is the only message.
+        const rows = policies(templateDir);
+        const optional = rows.filter(r => r.policy.startsWith("optional:")).map(r => r.policy.slice("optional:".length));
+        const unknown = unknownArgs(args, optional);
+        if (unknown.length) fail(`unknown argument(s): ${unknown.join(" ")}. Nothing was written; run with --help for the options.`);
+        const head = at(templateDir, ["rev-parse", "HEAD"]).output.trim();
+        if (previous && previous.commit === head && !options.adopt) {
+            say(`harness is already at ${head.slice(0, 8)} (${ref}); nothing to update`);
+            return 0;
+        }
+
+        const planned = plan({
+            upstream: gitUpstream(templateDir, head), target: fsTarget(target), rows, head, ref, previous, options,
+            stamp: { ...installer(), updated: new Date().toISOString().slice(0, 10) },
+        });
+        for (const notice of planned.notices) say(notice);
+        const entries = apply(planned.entries, target, options);
+        let check = null;
+        if (!options.dryRun) {
+            // After the plan is applied, because relink needs the skills in place and the invariants
+            // check the links relink has just written.
+            finish(target, options);
+            if (options.check) check = selfCheck(target, templateDir, options);
+        }
+        return report({ entries, base: planned.base, head, ref, target, check, options });
+    } finally {
+        if (temporary) fs.rmSync(templateDir, { recursive: true, force: true });
+    }
+}
+
+// The plan and the decisions under it, so the suite can put a case in and read the answer out rather
+// than building a git checkout to reach one branch. apply() is here for its dry run, which prints and
+// writes nothing; main() writes to somebody's repository and is reached through the command line.
+module.exports = { installerStamp, unknownArgs, mistypedArgs, usage, parseOptions, policyFor, plan, apply, decideText, decideBinary, lineCounts, overlap, NEAREST, skeletonLines };
+
+if (require.main === module) {
+    try { process.exitCode = main(process.argv.slice(2)); }
+    catch (e) {
+        if (!(e instanceof Stop)) throw e;
+        console.error(`update-harness: ${e.message}`);
+        process.exitCode = 1;
+    }
+}