@impeccable/reviews 0.1.23 → 0.1.25

package/dist/fence.js

@@ -412,7 +412,7 @@ function namesTrackedFiles(paths, cwd) {
     const named = new Set(paths.map((a) => resolve(cwd, a)));
     return tracked !== null && tracked.split('\0').filter(Boolean).every((a) => named.has(resolve(cwd, a)));
 }
-function git(args, where, protectedBranches, held = false) {
+function git(args, where, protectedBranches, held = false, ended = new Set()) {
     const words = gitArgs(args);
     if (!words)
         return deny('a git option before the command: run git with the command first');
@@ -500,6 +500,9 @@ function git(args, where, protectedBranches, held = false) {
         const branch = rest[2];
         if (branch.includes(':') || ['HEAD', '@'].includes(pushedBranch(branch)) || protectedBranches.includes(pushedBranch(branch)))
             return deny('a push to the default branch');
+        // The person's no ended the setup (#413): of a repository of one app, nothing is pushed; of an app of several, not its own test drive.
+        if (ended.has('') || [...ended].some((key) => pushedBranch(branch) === `impeccable/test-drive-${key}`))
+            return deny("a push after the person's no ended the setup: there is no preview to review it on");
         // A connected Vercel project builds every push, and calls a new project's first deployment Production, public at the project's own address.
         return held ? deny("a push before impeccable_vercel_connect settled the linked Vercel project's first deployment: run it first") : allow();
     }
@@ -899,7 +902,7 @@ function simpleCommand(seg, where, opts) {
                 return deny('a cd that runs only sometimes: put it first, or after ;');
             return isFolder(realPath(resolve(where.cwd, args[0]))) ? allow() : deny('a cd into a folder that is not there');
         case 'git':
-            return git(args, where, opts.protectedBranches, opts.hosts.has('vercel') && !(opts.vercelSettled && opts.vercelSettled.projectId === (linkedVercelProject(where.root)?.projectId ?? null)));
+            return git(args, where, opts.protectedBranches, opts.hosts.has('vercel') && !(opts.vercelSettled && opts.vercelSettled.projectId === (linkedVercelProject(where.root)?.projectId ?? null)), opts.ended);
         case 'gh':
             // gh reads the file outside the sandbox, after the fence read it: a command still running in the sandbox can swap it in between.
             if (args[0] === 'pr' && args[1] === 'create')
@@ -1202,7 +1205,7 @@ function unsyncedWorkflows(where, named, carried, synced) {
 }
 /** The fence's answer for one shell command run from the checkout's top folder. */
 export function classifyCommand(command, root, options = {}) {
-    const opts = { protectedBranches: options.protectedBranches ?? ['main', 'master'], scriptsChanged: options.scriptsChanged ?? false, hosts: options.hosts ?? new Set(), installs: options.installs ?? new Set(), teams: options.teams ?? new Map(), vercelSettled: options.vercelSettled ?? null, repository: options.repository };
+    const opts = { protectedBranches: options.protectedBranches ?? ['main', 'master'], scriptsChanged: options.scriptsChanged ?? false, hosts: options.hosts ?? new Set(), installs: options.installs ?? new Set(), teams: options.teams ?? new Map(), vercelSettled: options.vercelSettled ?? null, ended: options.ended ?? new Set(), repository: options.repository };
     const segments = parseCommand(command);
     if (!segments) {
         // A here-document is how a file or a message gets written in one command: the write tool, -m and --body do that.
@@ -1532,7 +1535,7 @@ function classifyOpened(tool, opened, where) {
  * it searches and the files it reads context lines from; the matches themselves ripgrep reads, and guardedGrepTool takes those out.
  * ls's are the folder and each entry in it, so an entry that is a symlink out of the checkout is skipped, not listed.
  */
-export function guardedFileOperations(root, scratch) {
+export function guardedFileOperations(root, scratch, journal) {
     const where = { root: realPath(root), cwd: root, scratch: scratch && realPath(scratch) };
     // Every operation judges its own path: the order pi calls them in is not relied on.
     const judged = (tool, path) => {
@@ -1541,6 +1544,13 @@ export function guardedFileOperations(root, scratch) {
             throw new Error(`Refused: ${decision.reason}`);
         return path;
     };
+    /** A write the journal sees on both sides, what the file held taken before anything is awaited, so the run's end can take back what no commit carried (#421). */
+    const written = async (tool, path, content) => {
+        const real = realPath(judged(tool, path));
+        journal?.writing(real);
+        await writeFile(path, content, 'utf-8');
+        journal?.wrote(real, content);
+    };
     return {
         read: {
             readFile: async (path) => readFile(judged('read', path)),
@@ -1548,12 +1558,16 @@ export function guardedFileOperations(root, scratch) {
             detectImageMimeType: async (path) => detectSupportedImageMimeTypeFromFile(judged('read', path)),
         },
         write: {
-            writeFile: async (path, content) => writeFile(judged('write', path), content, 'utf-8'),
-            mkdir: async (dir) => void (await mkdir(judged('write', dir), { recursive: true })),
+            writeFile: (path, content) => written('write', path, content),
+            mkdir: async (dir) => {
+                const real = realPath(judged('write', dir));
+                journal?.making(real);
+                await mkdir(dir, { recursive: true });
+            },
         },
         edit: {
             readFile: async (path) => readFile(judged('edit', path)),
-            writeFile: async (path, content) => writeFile(judged('edit', path), content, 'utf-8'),
+            writeFile: (path, content) => written('edit', path, content),
             access: async (path) => access(judged('edit', path), constants.R_OK | constants.W_OK),
         },
         grep: {
@@ -1628,6 +1642,22 @@ export function previewRetryState(log) {
 const setupBranch = (branch) => /^impeccable\/setup(?:-(?:[2-9]|[1-9][0-9]+))?$/.test(branch);
 /** The test drive's branch: impeccable/test-drive, an app's impeccable/test-drive-<app key> on a repository with several, each with -2, -3 where an earlier run took it. */
 const driveBranch = (branch) => /^impeccable\/test-drive(?:-[A-Za-z0-9][A-Za-z0-9._-]*)?$/.test(branch) && !branch.includes('..') && !branch.endsWith('.') && !branch.endsWith('.lock');
+/** Under --signed-in-test-drive, why a test drive's branch may not be pushed or opened yet: its app has no test account saved (#410). An app's branch is impeccable/test-drive-<app key>, with -2, -3 where an earlier run took it; a run that sets up one app of several uses impeccable/test-drive. */
+function signedInRefusal(state, branch) {
+    const signedIn = state.signedIn;
+    if (!signedIn)
+        return;
+    const rest = branch.slice('impeccable/test-drive'.length);
+    const picked = signedIn.picked ?? [];
+    const named = (key) => rest === `-${key}` || (rest.startsWith(`-${key}-`) && /^\d+$/.test(rest.slice(key.length + 2)));
+    // An app's own branch, a numeric key's too, else the unnamed branch of a run that picked one app.
+    const saved = !signedIn.apps ? signedIn.saved.has('')
+        : picked.some((key) => named(key)) ? picked.some((key) => named(key) && signedIn.saved.has(key))
+            : /^(?:-\d+)?$/.test(rest) && picked.length === 1 && signedIn.saved.has(picked[0]);
+    if (saved)
+        return;
+    return deny(`the run was started with --signed-in-test-drive, and no test account is saved${signedIn.apps ? ' for this app' : ''}, so its test drive cannot change a page behind the sign-in. Save the accounts first, as the sign-in case says. Where the app has no sign-in of its own, or every account was skipped, push and open no test drive: say in the report that --signed-in-test-drive could not be honoured, and why`);
+}
 /** A GitHub repository as `<owner>/<name>`. */
 const REPOSITORY = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\/[A-Za-z0-9_.-]{1,100}$/;
 /** `gh pr ready <the test drive's branch> [--repo <owner>/<name>]`, and nothing else (never `--undo`, a number or another branch): the branch and the repository named, or null. */
@@ -1725,9 +1755,16 @@ export function reservePreviewCommand(state, command, root, scratch) {
         const gitWords = words[0] === 'git' ? gitArgs(words.slice(1)) : [];
         if (!gitWords)
             return deny('a git option before the command');
+        // A push or a pull request would go by on "Understanding your app" while the list shows only the reading (#416).
+        if (state.reading?.() && (gitWords[0] === 'push' || (words[0] === 'gh' && words[1] === 'pr' && words[2] === 'create'))) {
+            return deny('the task list shows no work past reading the repository yet, so the screen still says "Understanding your app". Call impeccable_progress first with Read the repository completed and the task this is for in progress (Test drive for the test drive), then run it again');
+        }
         // The test drive is the run's other pull request (one an app on a repository with several): one branch, one pull request, a few pushes, none of the setup pull request's attempts.
         const drivePush = pushBranch(gitWords, driveBranch);
         if (drivePush) {
+            const unsigned = signedInRefusal(state, drivePush);
+            if (unsigned)
+                return unsigned;
             const drive = driveOf(drivePush);
             if (!drive)
                 return deny(state.drivesAllowed > 1 ? `one test drive for each of the ${state.drivesAllowed} apps this run sets up, each on one branch` : 'keep the test drive on one branch');
@@ -1761,6 +1798,9 @@ export function reservePreviewCommand(state, command, root, scratch) {
                 || (!parsed.repository && realPath(where.cwd) !== where.root))
                 return deny('name this repository explicitly when creating a pull request');
             if (parsed.head && driveBranch(parsed.head)) {
+                const unsigned = signedInRefusal(state, parsed.head);
+                if (unsigned)
+                    return unsigned;
                 const drive = driveOf(parsed.head);
                 if (!drive)
                     return deny(state.drivesAllowed > 1 ? `one test drive for each of the ${state.drivesAllowed} apps this run sets up, each opened from the branch that was pushed` : 'open the test drive from the branch that was pushed');
@@ -2000,6 +2040,17 @@ export function settleVercelFirstDeployment(log, settlement) {
 export function vercelFirstDeploymentSettled(log) {
     return settledVercel.get(log) ?? null;
 }
+/** The apps whose setup the person's no ended (#413), by the run's log: '' for a repository of one app, which then pushes nothing; an app's key, whose own test drive is not pushed. */
+const endedSetups = new WeakMap();
+function setupsEnded(log) {
+    let keys = endedSetups.get(log);
+    if (!keys)
+        endedSetups.set(log, (keys = new Set()));
+    return keys;
+}
+export function endAppSetup(log, key) {
+    setupsEnded(log).add(key);
+}
 /** Tool calls a run makes before the fence refuses more: a setup takes far fewer, and a run steered elsewhere stops there. */
 export const MAX_TOOL_CALLS = 400;
 /** What still runs past the cap, so the run can say where it got to and end. */
@@ -2098,14 +2149,29 @@ const SECRET_RULE = 'A secret never goes into a file, a setting, a commit, a pul
 export function fenceExtension(root, log, protectedBranches, scratch, scans = scanRecorder(log)) {
     const retry = previewRetryState(log);
     return (pi) => {
-        /** The first file the agent changed that the scripts and tools load, and the first of those but vite.config, which also stops the local preview check. */
-        let changed;
-        let previewChanged;
-        /** The scripts and tools stop once `path`, which they load, changed, and the local preview check too unless every name of the file is a vite.config. */
-        const stop = (path, names) => {
-            changed ??= path;
-            if (!names.every((p) => VITE_CONFIG.test(p)))
-                previewChanged ??= path;
+        /**
+         * Each file the agent changed that the scripts and tools load, in the order it first did, with the hash it held before
+         * (#421): the scripts and tools stop while one differs from that, so a file the agent put back as it was is the
+         * repository's own again. `preview` when a name of the file is not a vite.config, which stops the local preview check too.
+         */
+        const stops = new Map();
+        /** The loaded files a write or edit allowed is still writing, by its call: changed until its result. */
+        const writing = new Map();
+        /** By the file itself, whichever spelling named it: the first spelling is the one the refusal names, and the first hash stands. */
+        const stop = (path, names, before) => {
+            const file = realPath(resolve(root, path));
+            const stopped = stops.get(file) ?? { path, before: before ?? hashOf(file), preview: false };
+            stopped.preview ||= !names.every((p) => VITE_CONFIG.test(p));
+            stops.set(file, stopped);
+            return file;
+        };
+        /** The first file the agent changed that the scripts and tools load and that differs from what it held, of those that stop the local preview check when `preview`. */
+        const changedNow = (preview = false) => {
+            for (const [file, { path, before, preview: stopsPreview }] of stops) {
+                if ((!preview || stopsPreview) && ([...writing.values()].includes(file) || hashOf(file) !== before))
+                    return path;
+            }
+            return undefined;
         };
         /** The paths this run wrote or named, as git names them: what a commit may carry. */
         const touched = new Set();
@@ -2120,12 +2186,12 @@ export function fenceExtension(root, log, protectedBranches, scratch, scans = sc
                 return { block: true, reason: `Refused: this run has made ${MAX_TOOL_CALLS} tool calls, its limit. Call impeccable_progress with every task's final status, then impeccable_report with what was done and what was left.` };
             }
             const input = event.input;
-            const scriptsChanged = changed ?? false;
+            const scriptsChanged = changedNow() ?? false;
             let decision;
             let shown;
             if (event.toolName === 'bash') {
                 shown = String(input.command ?? '');
-                decision = classifyCommand(shown, root, { protectedBranches, scriptsChanged, scratch, hosts: hostsAgreed(log), installs: installsAgreed(log), teams: teamsChosen(log), vercelSettled: vercelFirstDeploymentSettled(log), touched, synced, repository: retry.repository });
+                decision = classifyCommand(shown, root, { protectedBranches, scriptsChanged, scratch, hosts: hostsAgreed(log), installs: installsAgreed(log), teams: teamsChosen(log), vercelSettled: vercelFirstDeploymentSettled(log), ended: setupsEnded(log), touched, synced, repository: retry.repository });
                 if (decision.verdict === 'allow')
                     decision = reservePreviewCommand(retry, shown, root, scratch);
                 if (decision.verdict === 'allow') {
@@ -2135,7 +2201,8 @@ export function fenceExtension(root, log, protectedBranches, scratch, scans = sc
                         watched.set(event.toolCallId, trustedFiles(root));
                 }
             }
-            else if (event.toolName === 'impeccable_verify_preview' && previewChanged) {
+            else if (event.toolName === 'impeccable_verify_preview' && changedNow(true)) {
+                const previewChanged = changedNow(true);
                 shown = `local preview after an edit of ${previewChanged}`;
                 decision = deny(changedReason(previewChanged));
             }
@@ -2150,7 +2217,7 @@ export function fenceExtension(root, log, protectedBranches, scratch, scans = sc
                     // The name written to and the file it resolves to: through a symlink, a vite.config may be another config.
                     const loaded = [String(input.path), realPath(resolve(root, String(input.path)))].filter((p) => LOADED.test(p));
                     if (loaded.length)
-                        stop(String(input.path), loaded);
+                        writing.set(event.toolCallId, stop(String(input.path), loaded));
                 }
             }
             else if (OUTPUT_TOOLS.has(event.toolName)) {
@@ -2204,6 +2271,7 @@ export function fenceExtension(root, log, protectedBranches, scratch, scans = sc
                 }
                 return undefined;
             }
+            writing.delete(event.toolCallId);
             if (!['read', 'grep', 'bash'].includes(event.toolName))
                 return undefined;
             const input = event.input;
@@ -2220,7 +2288,7 @@ export function fenceExtension(root, log, protectedBranches, scratch, scans = sc
                 if (rewritten.length)
                     log.write('a command changed files the scripts and tools load', rewritten.join(', '));
                 for (const path of rewritten)
-                    stop(path, [path]);
+                    stop(path, [path], before.get(path) ?? '');
             }
             const sources = event.toolName === 'bash' ? (parseCommand(String(input.command ?? ''))?.flatMap((seg) => seg.words) ?? []) : [input.path, input.glob].filter((s) => typeof s === 'string');
             const hits = scan('input', text(), sources);

package/dist/focus.js

@@ -32,6 +32,23 @@ const hasApps = (repo) => Boolean(record(repo.items)?.[APPS.item]) || records(re
 export function severalApps(answer) {
     return reposOf(answer).some(hasApps);
 }
+/** The state's sign-in item of `repo`, which it has only when the scan read a sign-in of the app's own. */
+export const signInItem = (state, repo) => record(record(reposOf(state).find((r) => String(r.name).toLowerCase() === repo.toLowerCase())?.items)?.signin);
+/**
+ * The apps of `repo` with a test account saved, as the sign-in item says (#410): '' on a repository of one app. On one
+ * with several, the item speaks for its first picked app with that app's roles, and the others ride along in `perApp`
+ * with their status alone, `done` once an account is saved.
+ */
+export function accountsSaved(state, repo) {
+    const item = signInItem(state, repo);
+    if (!item)
+        return [];
+    const saved = Array.isArray(item.rolesSaved) && item.rolesSaved.length > 0;
+    if (!severalApps(state))
+        return saved ? [''] : [];
+    const keys = records(item.perApp).filter((app) => app.status === 'done').map((app) => app.app);
+    return [...new Set([...(saved ? [item.app] : []), ...keys])].filter((key) => typeof key === 'string' && key !== '');
+}
 /**
  * Whether the state or the checkup shows a card of this setup `not-selected` on `repo`, a repository with several apps.
  * The command's token covers the apps there were when the person signed in, so this is an app the scan proposed later.

package/dist/leftovers.js

@@ -0,0 +1,271 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, sep } from 'node:path';
+import { gitEnvironment } from './sandbox.js';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** Up to three paths, then how many more. */
+export const listPaths = (paths) => `${paths.slice(0, 3).join(', ')}${paths.length > 3 ? ` and ${paths.length - 3} more` : ''}`;
+/** A pathspec git reads as the path itself, never a pattern. */
+const literal = (path) => `:(literal)${path}`;
+const them = (paths, one, more) => (paths.length === 1 ? one : more);
+export function checkoutJournal(checkoutRoot) {
+    const root = realpathSync(checkoutRoot);
+    // As the person, outside the sandbox, as backToStartBranch runs it: no hooks, no fsmonitor.
+    const git = (args, input) => execFileSync('git', args, { cwd: root, encoding: 'utf8', input, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'ignore'], timeout: 10_000, maxBuffer: 64 * 1024 * 1024, env: gitEnvironment() });
+    const untracked = () => {
+        try {
+            return new Set(git(['ls-files', '-z', '--others', '--exclude-standard']).split('\0').filter(Boolean));
+        }
+        catch {
+            return null;
+        }
+    };
+    /** A blob's bytes as git keeps them: cat-file runs no filter without --filters. */
+    const blob = (id) => execFileSync('git', ['cat-file', 'blob', id], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000, maxBuffer: 64 * 1024 * 1024, env: gitEnvironment() });
+    let autocrlf;
+    /**
+     * What git converts in `rel` as it stages it, read from its attributes and settings (check-attr and config run no filter):
+     * CRLF to LF (`lf`), unless the attributes say it is not text; and whether it has a working-tree-encoding.
+     */
+    const convert = (rel) => {
+        const listed = git(['check-attr', '-z', 'text', 'eol', 'crlf', 'working-tree-encoding', '--', rel]).split('\0');
+        const attr = new Map();
+        for (let i = 0; i + 2 < listed.length; i += 3)
+            attr.set(listed[i + 1], listed[i + 2]);
+        if (autocrlf === undefined) {
+            try {
+                autocrlf = git(['config', '--get', 'core.autocrlf']).trim().toLowerCase();
+            }
+            catch {
+                autocrlf = '';
+            }
+        }
+        const text = attr.get('text') ?? 'unspecified', crlf = attr.get('crlf') ?? 'unspecified';
+        const notText = text === 'unset' || (text === 'unspecified' && crlf === 'unset');
+        const isText = text === 'set' || text === 'auto' || crlf === 'set' || (attr.get('eol') ?? 'unspecified') !== 'unspecified';
+        return { lf: !notText && (isText || ['true', 'input'].includes(autocrlf)), encoding: !['unspecified', 'unset'].includes(attr.get('working-tree-encoding') ?? 'unspecified') };
+    };
+    /** HEAD's blob of `rel`; '' with none. */
+    const headBlob = (rel) => {
+        try {
+            return git(['rev-parse', '-q', '--verify', `HEAD:${rel}`]).trim();
+        }
+        catch {
+            return '';
+        }
+    };
+    /** The path as git names it from the checkout's top; null outside the checkout. */
+    const named = (path) => {
+        const rel = relative(root, path);
+        return !rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) ? null : rel.split(sep).join('/');
+    };
+    const atStart = untracked();
+    const files = new Map();
+    const dirs = new Set();
+    const current = (path) => {
+        try {
+            const stat = lstatSync(path);
+            return stat.isFile() ? readFileSync(path) : undefined;
+        }
+        catch (error) {
+            return error.code === 'ENOENT' ? null : undefined;
+        }
+    };
+    const removeEmptyDirs = () => {
+        // Deepest first, so a folder emptied by the one below it goes too; one that is not empty stays.
+        for (const dir of [...dirs].sort((a, b) => b.length - a.length)) {
+            try {
+                rmdirSync(dir);
+            }
+            catch {
+                // Not empty, or already gone.
+            }
+        }
+    };
+    return {
+        writing(path) {
+            const rel = named(path);
+            if (files.has(path) || rel === null)
+                return;
+            const held = current(path);
+            try {
+                const entry = git(['ls-files', '-s', '-z', '--', literal(rel)]).split('\0').filter(Boolean);
+                // `<mode> <id> <stage>\t<path>`: a conflict's stages are left to the person.
+                const [mode, id, stage] = (entry[0] ?? '').split(/[ \t]/);
+                if (held === undefined || entry.length > 1 || (entry.length && stage !== '0'))
+                    throw new Error('not a plain file');
+                files.set(path, { original: held, index: entry.length ? `${mode} ${id}` : '', head: headBlob(rel), all: new Set(), lf: new Set() });
+            }
+            catch {
+                files.set(path, { original: null, index: '', head: '', all: new Set(), lf: new Set(), other: true });
+            }
+        },
+        wrote(path, content) {
+            const entry = files.get(path);
+            if (!entry)
+                return;
+            entry.all.add((entry.last = digest(Buffer.from(content, 'utf8'))));
+            entry.lf.add(digest(Buffer.from(content.replace(/\r\n/g, '\n'), 'utf8')));
+        },
+        making(dir) {
+            for (let at = dir; named(at) !== null && !existsSync(at); at = dirname(at))
+                dirs.add(at);
+        },
+        undo() {
+            const all = [...files].filter(([, entry]) => !entry.other).map(([path, entry]) => ({ path, rel: named(path), entry, now: current(path) }));
+            // A write still going when the run was stopped: what it left is not known, so it is named.
+            const unfinished = all.filter(({ entry, now }) => entry.last === undefined && now !== undefined && !(now === null ? entry.original === null : entry.original?.equals(now))).map(({ rel }) => rel);
+            const mine = all.filter(({ entry }) => entry.last !== undefined);
+            const lines = (kept, failed) => [
+                ...(kept.length ? [`${listPaths(kept)} changed after the setup wrote ${them(kept, 'it, so it stays', 'them, so they stay')} in your checkout as ${them(kept, 'it is', 'they are')}.`] : []),
+                ...(unfinished.length ? [`The setup stopped while writing ${listPaths(unfinished)}, so ${them(unfinished, 'it stays', 'they stay')} in your checkout as ${them(unfinished, 'it is', 'they are')}.`] : []),
+                ...(failed.length ? [`The setup could not take back what it wrote to ${listPaths(failed)}: ${them(failed, 'it stays', 'they stay')} in your checkout.`] : []),
+            ];
+            if (!mine.length) {
+                removeEmptyDirs();
+                return lines([], []);
+            }
+            let tracked;
+            try {
+                tracked = new Set(git(['ls-files', '-z', '--cached', '--', ...mine.map(({ rel }) => literal(rel))]).split('\0').filter(Boolean));
+            }
+            catch {
+                return [`The setup could not check ${listPaths(mine.map(({ rel }) => rel))}, which it wrote, so ${them(mine, 'it is', 'they are')} as it left ${them(mine, 'it', 'them')}.`];
+            }
+            // git status may run a content filter outside the sandbox on a tracked file: those are left to the person, as backToStartBranch leaves the checkout.
+            const ownTracked = mine.filter(({ rel }) => tracked.has(rel));
+            let changedTracked = new Set();
+            let filtered = false;
+            if (ownTracked.length) {
+                try {
+                    const listed = git(['check-attr', '--stdin', '-z', 'filter'], ownTracked.map(({ rel }) => `${rel}\0`).join('')).split('\0');
+                    for (let i = 2; i < listed.length; i += 3)
+                        if (!['unspecified', 'unset'].includes(listed[i]))
+                            filtered = true;
+                    if (!filtered) {
+                        changedTracked = new Set(git(['status', '--porcelain=v1', '-z', '--untracked-files=no', '--no-renames', '--', ...ownTracked.map(({ rel }) => literal(rel))]).split('\0').filter(Boolean).map((line) => line.slice(3)));
+                    }
+                }
+                catch {
+                    filtered = true;
+                }
+            }
+            const kept = [];
+            const failed = [];
+            /** The index entries to set, `<mode> <id>\t<path>`, and the paths to take out of the index. */
+            const entries = [];
+            const removed = [];
+            const committed = [];
+            // Read before anything is taken back, which may put an attributes file back and change them.
+            const rules = new Map(mine.map(({ rel }) => {
+                try {
+                    return [rel, convert(rel)];
+                }
+                catch {
+                    return [rel, { lf: false, encoding: true }];
+                }
+            }));
+            /**
+             * `rel`'s index entry goes to `to` (`<mode> <id>`, '' for none: by default the one before the run's first write) where
+             * what is staged now is something the run wrote; what anyone else staged stays.
+             */
+            const stageBack = (rel, entry, to = entry.index) => {
+                try {
+                    const [mode, id] = (git(['ls-files', '-s', '-z', '--', literal(rel)]).split('\0')[0] ?? '').split(/[ \t]/);
+                    if (!id || `${mode} ${id}` === to)
+                        return;
+                    const staged = digest(blob(id));
+                    // As git stages it where its line-ending rules turn CRLF into LF.
+                    if (!entry.all.has(staged) && !(rules.get(rel).lf && entry.lf.has(staged)))
+                        return;
+                    if (to)
+                        entries.push(`${to}\t${rel}`);
+                    else
+                        removed.push(rel);
+                }
+                catch {
+                    // Left staged: a file still changed keeps the checkout on its branch, and backToStartBranch names it.
+                }
+            };
+            for (const { path, rel, entry, now } of mine) {
+                // A file a commit carries, as it is, is the branch's, and goes with it.
+                if (tracked.has(rel) && (filtered || !changedTracked.has(rel)))
+                    continue;
+                // Gone, or no longer a plain file: nothing of the run's is left there to take back, but in the index where it was never there.
+                if (!now) {
+                    if (now === null && entry.original === null)
+                        stageBack(rel, entry);
+                    continue;
+                }
+                // Changed since the run last wrote it, by a command or by the person: theirs now, unless it is back as it was.
+                if (digest(now) !== entry.last) {
+                    if (entry.original?.equals(now))
+                        stageBack(rel, entry);
+                    else
+                        kept.push(rel);
+                    continue;
+                }
+                const head = tracked.has(rel) ? headBlob(rel) : entry.head;
+                // The run committed the file after its first write, so it is the branch's: back to HEAD's version, once every other file is back.
+                if (head !== entry.head) {
+                    committed.push({ path, rel, entry, head });
+                    continue;
+                }
+                try {
+                    if (entry.original === null)
+                        unlinkSync(path);
+                    else
+                        writeFileSync(path, entry.original);
+                    stageBack(rel, entry);
+                }
+                catch (error) {
+                    failed.push(`${rel} (${error.code ?? 'an error'})`);
+                }
+            }
+            for (const { path, rel, entry, head } of committed) {
+                try {
+                    const [mode] = git(['ls-tree', '-z', 'HEAD', '--', rel]).split('\0').find((line) => line.endsWith(`\t${rel}`))?.split(' ') ?? [];
+                    if (!mode || !head)
+                        throw Object.assign(new Error('no entry in HEAD'), { code: 'ENOENT' });
+                    // Kept in another encoding in the working tree than git keeps it, which only git's checkout converts: by the rules before the run's files were put back, or after.
+                    let encoded = rules.get(rel).encoding;
+                    try {
+                        encoded ||= convert(rel).encoding;
+                    }
+                    catch {
+                        encoded = true;
+                    }
+                    if (encoded)
+                        throw Object.assign(new Error('working-tree-encoding'), { code: 'working-tree-encoding' });
+                    // HEAD's bytes as git keeps them, which no filter runs on.
+                    writeFileSync(path, blob(head));
+                    stageBack(rel, entry, `${mode} ${head}`);
+                }
+                catch (error) {
+                    failed.push(`${rel} (${error.code ?? 'an error'})`);
+                }
+            }
+            try {
+                // No filter runs: these set index entries alone.
+                if (entries.length)
+                    git(['update-index', '-z', '--index-info'], entries.map((line) => `${line}\0`).join(''));
+                if (removed.length)
+                    git(['update-index', '-z', '--force-remove', '--stdin'], removed.map((rel) => `${rel}\0`).join(''));
+            }
+            catch {
+                // A file still changed keeps the checkout on its branch, and backToStartBranch names it.
+            }
+            removeEmptyDirs();
+            return lines(kept, failed);
+        },
+        appeared() {
+            const now = untracked();
+            if (!atStart || !now)
+                return [];
+            const mine = new Set([...files.keys()].map(named));
+            const fresh = [...now].filter((path) => !atStart.has(path) && !mine.has(path));
+            return fresh.length ? [`${listPaths(fresh)} appeared in your checkout during the setup, from a command it ran or from you, so ${them(fresh, 'it stays', 'they stay')}.`] : [];
+        },
+    };
+}