@salaros/ai-harness 0.4.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salaros/ai-harness",
-  "version": "0.4.1",
+  "version": "0.5.2",
   "description": "Installs and updates the agent harness from its upstream repository: hooks, skills, agents and the documentation chain, merged into an existing repository without touching its own work.",
   "bin": {
     "ai-harness": "scripts/update-harness.js"
@@ -11,6 +11,7 @@
     "scripts/lib.js",
     "scripts/project-facts.js",
     "scripts/repo-view.js",
+    "scripts/repo-edit.js",
     "README.md",
     "LICENSE"
   ],

package/scripts/lib.js

@@ -11,6 +11,7 @@
 //   lib.node(["scripts/skills.js", "missing"]) // run a script with this node; { status, output }
 //   lib.shell("npm install")                 // run a command through the OS shell
 //   lib.readTsv("scripts/stacks.tsv")        // rows as arrays of cells; blank and # lines skipped
+//   lib.parseTsv(text)                       // the same, for a caller that already has the text
 //   lib.toLf(text), lib.asFound(text, crlf)  // compare in LF, write back in the endings a file had
 //   lib.sameContent(a, b)                    // equal text, or equal bytes; never text against bytes
 const fs = require("fs");
@@ -80,11 +81,13 @@ function run(cmd, args, opts = {}) {
 const node = (args, opts) => run(process.execPath, args, opts);
 const shell = (cmd, opts) => run(cmd, [], { shell: true, ...opts });
 
-function readTsv(file) {
-    return fs.readFileSync(file, "utf8").split(/\r?\n/)
-        .filter(l => l.trim() && !l.startsWith("#"))
-        .map(l => l.split("\t"));
-}
+// The rows of a tab-separated table, blank and # lines skipped. parseTsv takes the text, for a
+// caller that already has it -- one reading through a repo-view, which hands out text rather than
+// paths -- and readTsv is the same thing for a caller holding a filename.
+const parseTsv = text => text.split(/\r?\n/)
+    .filter(l => l.trim() && !l.startsWith("#"))
+    .map(l => l.split("\t"));
+const readTsv = file => parseTsv(fs.readFileSync(file, "utf8"));
 
 // 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
@@ -103,4 +106,4 @@ const sameContent = (a, b) => Buffer.isBuffer(a) || Buffer.isBuffer(b)
     ? Buffer.isBuffer(a) && Buffer.isBuffer(b) && a.equals(b)
     : a === b;
 
-module.exports = { root, args, ROOT_FLAG, ROOT_ENV_VARS, CHECKOUT, chdirRoot, fix, warn, stdin, run, node, shell, readTsv, isCrlf, toLf, asFound, sameContent };
+module.exports = { root, args, ROOT_FLAG, ROOT_ENV_VARS, CHECKOUT, chdirRoot, fix, warn, stdin, run, node, shell, readTsv, parseTsv, isCrlf, toLf, asFound, sameContent };

package/scripts/repo-edit.js

@@ -0,0 +1,140 @@
+// scripts/repo-edit.js
+// A repo as a run changes it: the mirror of repo-view.js. An install is files in and files out, and
+// this is the "out" -- every write the installer makes to somebody else's repository, in one
+// implementation behind one substitutable adapter.
+//   apply(entries)  carry out a finished plan, and return what became of it
+// Each entry that asks for work gets one result:
+//   { file, kind, done, why }
+// `kind` is write, link, mkdir or mark; `done` is whether the tree now holds what the entry asked
+// for; `why` is the mechanical reason it does not, or null. No outcome word and no summary bucket
+// appears here: those are the install policy's, and the run translates these results into them.
+// Nothing here prints or exits, so a refusal is a value the caller reads rather than a message a
+// user has to be watching for.
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const repoView = require("./repo-view");
+
+// core.longpaths, because a vendored skill tree nests deeper than Windows' default limit.
+const git = (root, args) => spawnSync("git", ["-c", "core.longpaths=true", "-C", root, ...args], { encoding: "utf8" });
+
+const result = (file, kind, why) => ({ file, kind, done: !why, why: why || null });
+
+// What an entry asks to have done, or null when it asks for nothing: a phase heading, or a path the
+// plan decided to leave exactly as it found it.
+function work(e) {
+    if (e.link !== undefined) return "link";
+    if (e.write !== undefined) return "write";
+    if (e.mkdir) return "mkdir";
+    if (e.exec) return "mark";
+    return null;
+}
+
+// The common body: the ordering and the reporting, over whatever actually touches the repo.
+// An entry may ask for two things at once -- the harness's hooks are written and then marked
+// executable -- so the mark is part of whatever the entry chiefly asked for rather than a result of
+// its own, and a caller still gets one line per entry to print. A write that failed is not then
+// marked: there is nothing there to mark.
+function editing(act) {
+    return {
+        apply(entries) {
+            const out = [];
+            for (const e of entries) {
+                const kind = work(e);
+                if (!kind) continue;
+                let why = kind === "mark" ? null : act[kind](e);
+                if (!why && e.exec) why = act.mark(e);
+                out.push(result(e.file, kind, why));
+            }
+            return out;
+        },
+    };
+}
+
+// The same entry, as a map holds it once it is executable.
+const asExec = held => {
+    const spec = held && typeof held === "object" && !Buffer.isBuffer(held) ? held : { bytes: held };
+    return { ...spec, exec: true };
+};
+
+// The entries applied to a map, with the resulting tree readable as a view. A check says what the
+// repo held before and asserts on what it holds after, with no directory in between.
+// `links: false` stands for a target the platform will not let anyone make a symlink in, which is
+// every Windows checkout without Developer Mode. It is a shape a target really has, not a lever for
+// a test: the case it makes reachable is the one the suite could otherwise only run on a machine
+// that happens to refuse.
+function mapEdit(files = {}, { links = true } = {}) {
+    const held = { ...files };
+    const marked = [];
+    const view = () => repoView.fromMap(held);
+    return {
+        ...editing({
+            write: e => { held[e.file] = e.write; return null; },
+            link: e => {
+                if (!links) return `could not create the symlink ${e.file} -> ${e.link}: EPERM`;
+                held[e.file] = { link: e.link };
+                return null;
+            },
+            // A map holds files, and a folder in it is whatever a path implies, so there is nothing
+            // to make: the entry is satisfied the moment anything is written under it.
+            mkdir: () => null,
+            mark: e => {
+                const row = view().modes().find(r => r.file === e.file);
+                if (!row) return `nothing at ${e.file} to mark executable`;
+                if (row.exec) return null;
+                held[e.file] = asExec(held[e.file]);
+                marked.push(e.file);
+                return null;
+            },
+        }),
+        view,
+        marked: () => [...marked],
+    };
+}
+
+// The files on disk under `root`. W-2 is this adapter's whole reason for existing: a parent folder
+// is made before anything is written into it and whatever is in a link's way is removed before the
+// link is made, so a caller orders its entries for a reader rather than for the filesystem.
+function worktreeEdit(root) {
+    const at = rel => path.resolve(root, String(rel));
+    const parent = rel => fs.mkdirSync(path.dirname(at(rel)), { recursive: true });
+    const clear = rel => { try { fs.unlinkSync(at(rel)); } catch { /* nothing was in the way */ } };
+    const marked = [];
+    // Git runs a hook only if it is executable and says nothing when it is not, so an installed
+    // harness whose hooks are 644 looks installed and gates nothing. The upstream records them
+    // 100755 and only Git can carry that: `chmod` alone is not enough, because on Windows
+    // core.fileMode is false and the call does nothing, leaving the file to be staged 100644 later
+    // and the hooks to run for whoever installed them and silently never for anyone else.
+    // Which makes the index, not the disk, where "already marked" is true or false. Asking the disk
+    // on Windows -- where the filesystem has no executable bit at all -- would mark every hook on
+    // every run. A root with no index to read answers no, which marks: the safe way round.
+    const alreadyExec = file => (repoView.indexModes(root, [file]) || []).some(r => r.file === file && r.exec);
+    return {
+        ...editing({
+            write: e => { parent(e.file); fs.writeFileSync(at(e.file), e.write); return null; },
+            mkdir: e => { fs.mkdirSync(at(e.file), { recursive: true }); return null; },
+            link: e => {
+                parent(e.file);
+                clear(e.file);
+                // Windows needs Developer Mode and core.symlinks=true for this to work at all, so a
+                // refusal is a result rather than a throw: the harness still functions with the link
+                // missing, it is just invisible to the agent harnesses that read it.
+                try { fs.symlinkSync(e.link.split("/").join(path.sep), at(e.file), "dir"); }
+                catch (err) { return `could not create the symlink ${e.file} -> ${e.link}: ${err.code || err.message}`; }
+                return null;
+            },
+            mark: e => {
+                if (alreadyExec(e.file)) return null;
+                try { fs.chmodSync(at(e.file), 0o755); } catch { /* the filesystem does not do modes */ }
+                const r = git(root, ["add", "--chmod=+x", "--", e.file]);
+                if (r.status !== 0) return `could not mark ${e.file} executable: ${(r.stderr || "").trim()}`;
+                marked.push(e.file);
+                return null;
+            },
+        }),
+        view: () => repoView.worktree(root),
+        marked: () => [...marked],
+    };
+}
+
+module.exports = { worktreeEdit, mapEdit };

package/scripts/repo-view.js

@@ -1,12 +1,24 @@
 // scripts/repo-view.js
-// A repo as a check reads it: four questions about repo-relative paths, answered from the working
+// A repo as a check reads it: a handful of questions about repo-relative paths, answered from the working
 // tree, from Git's index, or from a map a test builds. A check that takes a view reads what a
 // commit will record as easily as what is on disk, and a test hands it the files it is about
 // instead of building a tree or pointing it at a file that does not exist.
 //   exists(rel)   a file, or a folder holding one
 //   isFile(rel)   a file
 //   read(rel)     its text, or null when there is none
+//   bytes(rel)    its bytes, or null when there is none
 //   list(rel)     the names directly inside a folder, sorted; [] when there is none
+//   lstat(rel)    { link } for whatever is at the path, or null when nothing is: `link` is where a
+//                 symlink points, with forward slashes, and null for anything that is not one
+//   modes()       every path the view holds, sorted, as { file, mode, object, link, exec }
+//   recorded(paths) the same rows, for what a commit would record under `paths`, or null when
+//                 nothing records them. The disk asks Git's index, because Windows has no executable
+//                 bit and a hook's mode is only ever a fact about the index; a view that is already
+//                 a record -- a map, an index, a commit -- answers with its own rows.
+// bytes() is a question of its own rather than a flag on read(), so that a view holding text answers
+// read() honestly and has to be handed real bytes to answer bytes(). A flag is what the installer's
+// own stand-in had, and it satisfied the flag by re-encoding its text: every branch production takes
+// for a blob with a zero byte in it was unreachable from the suite for as long as that lasted.
 // Paths are repo-relative with forward slashes. Nothing here writes, prints or exits.
 // indexModes() is the one reader of `git ls-files -s`: the mode Git records is how the harness
 // tells a symlink (120000) and an executable (100755) from a plain file.
@@ -14,8 +26,16 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
+// quotepath, so a path outside ASCII comes back as itself rather than as escapes. longpaths, because
+// Windows stops at 260 characters and a vendored skill tree in a repo a few folders down the drive
+// crosses it: `git show <commit>:<path>` stats the working copy on the way past, and without this it
+// answers that a file the tree plainly holds is not there.
+const CONFIG = ["-c", "core.quotepath=off", "-c", "core.longpaths=true"];
 // stdout alone and untrimmed, since a blob's trailing newline is part of its text.
-const git = (dir, args) => spawnSync("git", ["-c", "core.quotepath=off", ...args], { cwd: dir, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+const git = (dir, args) => spawnSync("git", [...CONFIG, ...args], { cwd: dir, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+// The same, with stdout left as bytes: a blob is read this way and decoded only if someone asks for
+// its text, since a decode a file never had is not recoverable afterwards.
+const gitBytes = (dir, args) => spawnSync("git", [...CONFIG, ...args], { cwd: dir, maxBuffer: 256 * 1024 * 1024 });
 
 const norm = rel => path.posix.normalize(String(rel).split(path.sep).join("/")).replace(/^\.\/?$|\/+$/g, "");
 
@@ -31,26 +51,50 @@ function indexModes(dir, paths = []) {
     });
 }
 
-// A view over a set of files known up front, each read on first use. Folders are whatever the
-// paths imply, which is all an index or a map has of them.
-function filesView(loaders) {
+// One entry of such a set: the mode Git records, the blob it recorded when there is one, and a
+// loader for the content, called on first use. Written this way round because modes() has to answer
+// for every path without reading a single blob: an index knows a file's mode from `ls-files -s`
+// long before anyone asks what is in it, and a listing that read them all would make the cheapest
+// question in the module the most expensive.
+const entry = (mode, object, load) => ({ mode, object, load });
+
+// A view over a set of entries known up front. Folders are whatever the paths imply, which is all
+// an index or a map has of them. A loader gives text or bytes, whichever its source holds; read()
+// and bytes() convert what they were given rather than what they wish for. A 120000 entry loads the
+// path it points at, which is what Git keeps in its blob, so a source with no filesystem still
+// answers the question the installer asks of a link.
+function filesView(entries) {
     const cache = new Map();
     const under = rel => rel ? rel + "/" : "";
-    return {
-        exists: rel => { rel = norm(rel); return loaders.has(rel) || [...loaders.keys()].some(f => f.startsWith(under(rel))); },
-        isFile: rel => loaders.has(norm(rel)),
-        read: rel => {
-            rel = norm(rel);
-            if (!loaders.has(rel)) return null;
-            if (!cache.has(rel)) cache.set(rel, loaders.get(rel)());
-            return cache.get(rel);
+    const held = rel => {
+        rel = norm(rel);
+        if (!entries.has(rel)) return null;
+        if (!cache.has(rel)) cache.set(rel, entries.get(rel).load());
+        return cache.get(rel);
+    };
+    const view = {
+        exists: rel => { rel = norm(rel); return entries.has(rel) || [...entries.keys()].some(f => f.startsWith(under(rel))); },
+        isFile: rel => entries.has(norm(rel)),
+        read: rel => { const v = held(rel); return v === null ? null : Buffer.isBuffer(v) ? v.toString("utf8") : v; },
+        bytes: rel => { const v = held(rel); return v === null ? null : Buffer.isBuffer(v) ? v : Buffer.from(v, "utf8"); },
+        lstat: rel => {
+            if (!view.exists(rel)) return null;
+            const e = entries.get(norm(rel));
+            return { link: e && e.mode === "120000" ? view.read(rel) : null };
         },
         list: rel => {
             const prefix = under(norm(rel));
-            const names = new Set([...loaders.keys()].filter(f => f.startsWith(prefix)).map(f => f.slice(prefix.length).split("/")[0]));
+            const names = new Set([...entries.keys()].filter(f => f.startsWith(prefix)).map(f => f.slice(prefix.length).split("/")[0]));
             return [...names].sort();
         },
+        modes: () => [...entries.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+            .map(([file, e]) => ({ file, mode: e.mode, object: e.object, link: e.mode === "120000", exec: e.mode === "100755" })),
+        // A set of entries is already a record of itself -- a map, an index, a commit -- so there is
+        // nothing to go and ask. Scoped to `paths`, which is all the caller wanted the index for.
+        recorded: (paths = []) => view.modes().filter(r => !paths.length
+            || paths.map(norm).some(p => r.file === p || r.file.startsWith(p + "/"))),
     };
+    return view;
 }
 
 // The files on disk under `root`. A path outside it resolves as it stands, which is what a cited
@@ -62,7 +106,33 @@ function worktree(root) {
         exists: rel => !!stat(rel),
         isFile: rel => !!(stat(rel) || { isFile: () => false }).isFile(),
         read: rel => { const s = stat(rel); return s && s.isFile() ? fs.readFileSync(at(rel), "utf8") : null; },
+        bytes: rel => { const s = stat(rel); return s && s.isFile() ? fs.readFileSync(at(rel)) : null; },
         list: rel => { const s = stat(rel); return s && s.isDirectory() ? fs.readdirSync(at(rel)).sort() : []; },
+        // lstatSync, not statSync: a link pointing nowhere is still something in the way, and a link
+        // pointing somewhere must not be mistaken for what it points at.
+        lstat(rel) {
+            let s;
+            try { s = fs.lstatSync(at(rel)); } catch { return null; }
+            return { link: s.isSymbolicLink() ? fs.readlinkSync(at(rel)).split(path.sep).join("/") : null };
+        },
+        // The tree walked from the root, .git excepted. There is no blob to name, because nothing
+        // here has been recorded yet; on Windows there is no executable bit either, which is why
+        // the harness asks the index and not the disk what mode a hook was committed with.
+        modes() {
+            const walk = (rel) => fs.readdirSync(at(rel) || root, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)
+                .flatMap(d => {
+                    const file = rel ? `${rel}/${d.name}` : d.name;
+                    if (d.isDirectory()) return d.name === ".git" ? [] : walk(file);
+                    const mode = d.isSymbolicLink() ? "120000"
+                        : ((fs.lstatSync(at(file)).mode & 0o111) ? "100755" : "100644");
+                    return [{ file, mode, object: null, link: mode === "120000", exec: mode === "100755" }];
+                });
+            return fs.existsSync(root) ? walk("") : [];
+        },
+        // The disk records nothing itself, so this is Git's index and not the walk above: the two
+        // differ exactly where it matters, since Windows has no executable bit and stages one all
+        // the same. null when there is no index to ask, which is not an empty one.
+        recorded: (paths = []) => indexModes(root, paths),
     };
 }
 
@@ -73,11 +143,55 @@ function index(root, paths = []) {
     const rows = indexModes(root, paths);
     if (!rows) throw new Error(`could not read the git index in ${root}`);
     const blob = object => {
-        const r = git(root, ["cat-file", "blob", object]);
-        if (r.status !== 0) throw new Error(`could not read blob ${object}: ${r.stderr}`);
+        const r = gitBytes(root, ["cat-file", "blob", object]);
+        if (r.status !== 0) throw new Error(`could not read blob ${object}: ${r.stderr.toString("utf8")}`);
+        return r.stdout;
+    };
+    return filesView(new Map(rows.map(row =>
+        [row.file, entry(row.mode, row.object, () => row.link ? blob(row.object).toString("utf8") : blob(row.object))])));
+}
+
+// Every blob of one tree, read in two calls rather than a `git show` per path. An install reads
+// every file of the upstream's head, and a process per file made a first install take most of a
+// minute on Windows. null when the batch could not be read, which leaves each path to the fallback.
+function treeBlobs(root, rows) {
+    const r = spawnSync("git", ["-c", "core.quotepath=off", "cat-file", "--batch"],
+        { cwd: root, input: rows.map(e => e.object).join("\n") + "\n", maxBuffer: 1024 * 1024 * 1024 });
+    if (r.status !== 0) return null;
+    const blobs = new Map();
+    let at = 0;
+    for (const { file } of rows) {
+        const eol = r.stdout.indexOf(10, at);
+        const size = Number(r.stdout.toString("utf8", at, eol).split(" ")[2]);
+        blobs.set(file, Buffer.from(r.stdout.subarray(eol + 1, eol + 1 + size)));
+        at = eol + 1 + size + 1;
+    }
+    return blobs;
+}
+
+// One commit of the checkout at `root`: what it recorded, whatever the working tree has done since.
+// This is how the upstream is read during an install -- the commit the receipt names, not the
+// checkout that happens to be on disk. Throws when the commit cannot be read, for the same reason
+// index() does: a commit nobody could read is not an empty one.
+// A submodule is not a blob, and is left out, as `git show` would fail on it too.
+function commit(root, sha) {
+    const listing = gitBytes(root, ["ls-tree", "-r", "-z", sha]);
+    if (listing.status !== 0) throw new Error(`could not read the commit ${sha} in ${root}`);
+    const rows = listing.stdout.toString("utf8").split("\0").filter(Boolean).map(line => {
+        const tab = line.indexOf("\t");
+        const [mode, type, object] = line.slice(0, tab).split(" ");
+        return { mode, type, object, file: line.slice(tab + 1) };
+    }).filter(e => e.type === "blob");
+
+    let batch;                                    // read whole on first use, and only if anyone asks
+    const content = row => {
+        if (batch === undefined) batch = treeBlobs(root, rows);
+        if (batch && batch.has(row.file)) return batch.get(row.file);
+        const r = gitBytes(root, ["show", `${sha}:${row.file}`]);
+        if (r.status !== 0) throw new Error(`could not read ${row.file} at ${sha}: ${r.stderr.toString("utf8")}`);
         return r.stdout;
     };
-    return filesView(new Map(rows.map(row => [row.file, () => blob(row.object)])));
+    return filesView(new Map(rows.map(row => [row.file, entry(row.mode, row.object, () => content(row))])));
 }
 
 // What a commit will record for `paths`, and the working tree for everything else. Each of `paths`
@@ -91,11 +205,27 @@ function staged(root, paths) {
         exists: rel => pick(rel).exists(rel),
         isFile: rel => pick(rel).isFile(rel),
         read: rel => pick(rel).read(rel),
+        bytes: rel => pick(rel).bytes(rel),
         list: rel => pick(rel).list(rel),
+        lstat: rel => pick(rel).lstat(rel),
+        // The index's, not a mix of the two: a mode is a question about what a commit will record,
+        // and the disk has no answer to it that this view would rather give.
+        modes: () => idx.modes(),
+        recorded: (within = []) => idx.recorded(within),
     };
 }
 
-// The files a test names, path -> text, and nothing else.
-const fromMap = files => filesView(new Map(Object.entries(files).map(([f, text]) => [norm(f), () => text])));
+// The files a test names, and nothing else. An entry is the content -- text or bytes -- or, when the
+// case is about a mode rather than a content, `{ link }` for a symlink and `{ text|bytes, exec }`
+// for an executable. That is the whole of what a map has to say, so a case about a link in the way
+// or a mode already correct needs no checkout and no platform that has an executable bit.
+function fromMap(files) {
+    return filesView(new Map(Object.entries(files).map(([f, held]) => {
+        const spec = held && typeof held === "object" && !Buffer.isBuffer(held) ? held : { bytes: held };
+        const content = "link" in spec ? spec.link : "text" in spec ? spec.text : spec.bytes;
+        const mode = "link" in spec ? "120000" : spec.exec ? "100755" : "100644";
+        return [norm(f), entry(mode, null, () => content)];
+    })));
+}
 
-module.exports = { worktree, index, staged, fromMap, indexModes };
+module.exports = { worktree, index, commit, staged, fromMap, indexModes };

package/scripts/update-harness.js

@@ -34,8 +34,8 @@ const path = require("path");
 const lib = require("./lib");
 const projectFacts = require("./project-facts");
 const repoView = require("./repo-view");
+const repoEdit = require("./repo-edit");
 const installPolicy = require("./install-policy");
-const { spawnSync } = require("child_process");
 
 const TEMPLATE = "https://github.com/salaros/ai-harness.git";
 const LOCK = "harness-lock.json";
@@ -121,11 +121,16 @@ const say = m => console.log(m);
 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();
+    return repoView.worktree(beside).exists(".git") ? beside : process.cwd();
 }
 
 // ---------------------------------------------------------------- the upstream
 
+// The command line that clone runs on, which is how every install begins that did not bring its own
+// checkout. Separate from the running of it because nothing in the suite clones: a check can read
+// arguments, and cannot watch a network call it must not make.
+const cloneArgs = (ref, dir) => ["-c", "core.longpaths=true", "clone", "--quiet", "--branch", ref, TEMPLATE, dir];
+
 // 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, options) {
@@ -141,7 +146,7 @@ function templateCheckout(ref, options) {
     }
     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]);
+    const r = lib.run("git", cloneArgs(ref, dir));
     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 });
@@ -171,117 +176,68 @@ function installer() {
     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"]);
+    const described = git(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
-// that a project a few folders down the drive crosses it. Git then fails to stat the working copy
-// while resolving <commit>:<path>, so `git show` says the file is not there and the installer skips
-// it -- a skill missing seven of its reference files, and not a word said about it. Setting
-// core.longpaths on every call is what makes those paths reachable, and it costs nothing anywhere
-// else.
-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.
-// 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
-// run re-merged files nobody had touched.
-// Text comes back as a string and anything holding a NUL byte as the Buffer it arrived in, which is
-// how Git itself tells the two apart. Decoded as UTF-8 and written back, every byte a PNG holds
-// outside ASCII becomes U+FFFD: the skill's logo installs as a broken image, and no later run ever
-// agrees with the upstream about it. Nothing merges a Buffer; it is written whole or kept whole.
-function blob(dir, commit, file) {
-    const r = spawnSync("git", [...GIT, "-C", dir, "show", `${commit}:${file}`], { maxBuffer: 256 * 1024 * 1024 });
-    if (r.status !== 0) return null;
-    return r.stdout.includes(0) ? r.stdout : r.stdout.toString("utf8");
-}
+// The commit graph, which is all the installer runs git for itself now that repo-view reads the
+// files. core.longpaths for the same reason repo-view sets it: Windows stops at 260 characters, and
+// the harness ships skill files nested deep enough that a project a few folders down the drive
+// crosses it.
+const git = (dir, args) => lib.run("git", ["-c", "core.longpaths=true", "-C", dir, ...args]);
 
 // ---------------------------------------------------------------- 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;
+// What plan() reads: the upstream at any commit, and the target as it stands. Both are repo-view
+// adapters -- scripts/repo-view.js -- so a real run reads a checkout and a commit while the suite
+// reads a map, through one implementation rather than two. That is the whole point of the seam: the
+// stand-ins this file used to carry drifted, and the branch taken for a file with a NUL byte in it
+// was unreachable from the suite for as long as a stand-in answered a bytes question with a string.
+//
+// What repo-view will not do is guess which of the two a caller wants, so the guess is made here.
+
+// The upstream's version of a path, as the installer needs it: text as a string, and anything
+// holding a NUL byte as the Buffer it arrived in, which is how Git itself tells the two apart.
+// Decoded as UTF-8 and written back, every byte a PNG holds outside ASCII becomes U+FFFD: the
+// skill's logo installs as a broken image, and no later run ever agrees with the upstream about it.
+// Nothing merges a Buffer; it is written whole or kept whole.
+// null when the commit has no such path, and equally when the checkout will not give it up: Git
+// listed it a moment ago, so a read that fails is the checkout being unhappy rather than the file
+// being absent, and plan() reports that as UNREADABLE rather than letting it end the run.
+function contentOf(view, file) {
+    let bytes;
+    try { bytes = view.bytes(file); } catch { return null; }
+    if (bytes === null) return null;
+    return bytes.includes(0) ? bytes : bytes.toString("utf8");
 }
 
-function gitUpstream(dir, head) {
-    let atHead;
+// The upstream checkout: a view per commit, and the two questions only the commit graph can answer.
+// Views are kept, because plan() asks the head for every path and a base for every file it merges;
+// each one reads its tree once and its blobs in a single batch on first use.
+function gitUpstream(dir) {
+    const views = new Map();
     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;
+        at(sha) {
+            if (!views.has(sha)) views.set(sha, repoView.commit(dir, sha));
+            return views.get(sha);
         },
         // 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,
+        has: sha => git(dir, ["cat-file", "-e", `${sha}^{commit}`]).status === 0,
         // The commits that touched a path, newest first.
         history(file) {
-            const r = at(dir, ["log", "--format=%H", "--", file]);
+            const r = git(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
 // exactly, so the nearest version by shared lines stands in as the base. That turns a first install
 // into a real three-way merge for the files that need one, rather than one whole-file conflict.
-// Only reconcile-policy files pay for the search: one git log, then a blob read per commit that
-// touched the path.
+// Only reconcile-policy files pay for the search: one git log, then a view per commit that touched
+// the path.
 // 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;
@@ -293,7 +249,7 @@ function recoverBase(upstream, file, ours) {
     // 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 upstream.history(file).reverse()) {
-        const text = upstream.blob(commit, file);
+        const text = contentOf(upstream.at(commit), file);
         if (typeof text !== "string") continue;
         if (text === ours) return text;
         const shared = overlap(want, lineCounts(text));
@@ -424,7 +380,6 @@ function settleDropped(text) {
 //   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
@@ -438,7 +393,8 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
     // 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)) {
+    const atHead = upstream.at(head);
+    if (base && !upstream.has(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;
     }
@@ -464,14 +420,16 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
             : `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();
+    // The mode Git recorded, rather than one worked out from the entry: a view answers for every path
+    // it holds without reading a blob, and 120000 against 100755 against 100644 is the whole of what
+    // the mode column says.
+    const files = atHead.modes();
     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 { file, link: isLink, exec, mode: m } = entry;
         const { policy, asked } = installPolicy.policyFor(rows, file, options.wants);
-        const m = mode(entry);
-        const theirs = upstream.blob(head, file);
+        const theirs = contentOf(atHead, 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.
@@ -504,10 +462,11 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
         if (policy === "skills") { skills.push(entry); continue; }
         const { outcome, bucket, notice, ...act } = installPolicy.decide(policy,
             { exists, theirs, hasBase: base !== null, adopt: options.adopt, asked }, {
-                held: () => target.read(file, Buffer.isBuffer(theirs)),
-                base: () => upstream.blob(base, file),
-                // A seed file the recorded commit already shipped was laid down then.
-                shippedBefore: () => base !== null && upstream.blob(base, file) !== null,
+                held: () => Buffer.isBuffer(theirs) ? target.bytes(file) : target.read(file),
+                base: () => contentOf(upstream.at(base), file),
+                // A seed file the recorded commit already shipped was laid down then. isFile, not a
+                // read: whether a commit holds a path is a question its listing already answers.
+                shippedBefore: () => base !== null && upstream.at(base).isFile(file),
                 recoverBase: ours => recoverBase(upstream, file, ours),
                 merge: threeWay,
             });
@@ -528,7 +487,7 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
     }
 
     add({ phase: "skills, merged by name" });
-    entries.push(...planSkills(upstream, target, head, skills));
+    entries.push(...planSkills(atHead, target, skills));
 
     // A list of strings on one line, as Prettier writes it: a project formatting its JSON with it
     // would otherwise reject the receipt at every push, and the next update would undo the fix.
@@ -541,10 +500,10 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
 // 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 planSkills(upstream, target, head, files) {
+function planSkills(atHead, target, 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: {} };
+    const theirLock = JSON.parse(atHead.read(LOCKFILE) || '{"skills":{}}');
+    const ourLock = target.isFile(LOCKFILE) ? JSON.parse(target.read(LOCKFILE)) : { skills: {} };
     ourLock.skills = ourLock.skills || {};
     const mine = new Set(Object.keys(ourLock.skills));
 
@@ -563,11 +522,11 @@ function planSkills(upstream, target, head, files) {
         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 = upstream.blob(head, file);
+        const text = contentOf(atHead, file);
         if (text === null) continue;
         // 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 ? target.read(file, true) : null;
+        const held = exists ? target.bytes(file) : null;
         let write;
         if (Buffer.isBuffer(text)) {
             if (lib.sameContent(held, text)) continue;
@@ -593,53 +552,32 @@ function planSkills(upstream, target, head, files) {
 
 // ---------------------------------------------------------------- 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.
+//
+// The writing is scripts/repo-edit.js, an entry at a time: the line for a path is printed as the
+// path is written, and an edit handed the whole plan at once would leave a long install silent and
+// then print all of it at the end. What order the work inside an entry goes in -- the parent folder
+// before the file, the link's way cleared before the link, the mode after the content -- is the
+// edit's, so this loop takes the plan's order as given and adds nothing to it.
 // Returns the entries as they turned out, which the summary is built from.
 function apply(entries, root, options) {
     const done = [];
+    const edit = repoEdit.worktreeEdit(root);
     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 };
+            const [result] = edit.apply([e]);
+            // The edit reports; the policy decides. A symlink this platform will not make means the
+            // target keeps whatever it already had, which is an outcome word and therefore this
+            // run's to choose -- the edit says only that the link is not there and why.
+            if (result && !result.done) {
+                say(result.why);
+                if (result.kind === "link") shown = { ...e, outcome: "yours", bucket: "kept" };
+            }
         }
         if (!shown.silent && !options.quiet) say(`  ${shown.policy.padEnd(9)}${shown.mode}  ${shown.outcome.padEnd(12)}${shown.file}`);
         done.push(shown);
@@ -673,7 +611,7 @@ function finish(target, options) {
 // 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.
+// harness invariants, and scripts/check-harness.js holds them as functions of a repo-view.
 //
 // 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
@@ -684,6 +622,8 @@ function selfCheck(target, templateDir, options) {
     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);
+    // The root rather than a view of it: this is the upstream's copy of check-harness, at whichever
+    // ref the run is installing, and a ref old enough to predate the view still expects a path.
     const r = harness.check(target);
     return { failed: r.failed.length > 0, summary: r.summary, output: harness.format(r) };
 }
@@ -750,10 +690,13 @@ function main(args) {
     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`);
+    // One view of the target, read from here on: whether it is a checkout at all, what its receipt
+    // says, and everything plan() asks of it. worktree() holds nothing between calls, so it still
+    // answers for the tree as the run leaves it rather than as the run found it.
+    const here = repoView.worktree(target);
+    if (!here.exists(".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 previous = here.isFile(LOCK) ? JSON.parse(here.read(LOCK)) : null;
     const ref = options.ref || (previous ? previous.ref : DEFAULT_REF);
     const { dir: templateDir, temporary } = templateCheckout(ref, options);
 
@@ -763,14 +706,14 @@ function main(args) {
         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();
+        const head = git(templateDir, ["rev-parse", "HEAD"]).output.trim();
         if (upToDate(previous, head, options, optional)) {
             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,
+            upstream: gitUpstream(templateDir), target: here, rows, head, ref, previous, options,
             stamp: { ...installer(), updated: new Date().toISOString().slice(0, 10) },
         });
         for (const notice of planned.notices) say(notice);
@@ -792,7 +735,7 @@ function main(args) {
 // 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, upToDate, settleDropped, unknownArgs, mistypedArgs, usage, parseOptions, plan, apply, lineCounts, overlap, NEAREST, skeletonLines };
+module.exports = { cloneArgs, installerStamp, upToDate, settleDropped, unknownArgs, mistypedArgs, usage, parseOptions, plan, apply, lineCounts, overlap, NEAREST, skeletonLines };
 
 if (require.main === module) {
     try { process.exitCode = main(process.argv.slice(2)); }