copilot-operator 0.1.23 → 0.1.25

package/dist/src/vcs/runPreflight.js

@@ -24,15 +24,18 @@
  * The run is refused before the browser opens while any group is not ready (see the service).
  */
 import { join, resolve } from 'node:path';
-import { branchNameFrom, freeBranchName, git } from './git.js';
+import { branchNameFrom, describeUpdate, freeBranchName, git, updateFromRemote } from './git.js';
 import { commitOnto, dirtyBesidesInputs, inputSettings, inputSumsAt, missingInputPatterns } from './inputs.js';
-import { dirtyPolicy, takeSnapshot } from './snapshot.js';
-import { repoDirOf, vcsPreflight } from './taskVcs.js';
+import { approvalMismatch, dirtyPolicy, takeSnapshot } from './snapshot.js';
+import { repoDirOf, sessionBranchName, vcsPreflight } from './taskVcs.js';
 import { artifactPatterns } from './artifacts.js';
 import { inScope } from './scope.js';
+import { findSuspicious } from './commitHygiene.js';
 const norm = (dir) => dir.trim().replace(/[\\/]+$/, '').replace(/\//g, '\\').toLowerCase();
 const short = (c) => (c ?? '').slice(0, 8);
 const names = (list) => list.map((s) => `"${s.name}"`).join(', ');
+/** "starts" for one session, "start" for several (live run 2026-10-03: '"x" start from it', in a commit message too). */
+const verb = (list, one, many) => (list.length === 1 ? one : many);
 /** The groups, one per repository, for the sessions of a run in run order. */
 export async function runVcsPreflight(sessions, allSessions) {
     const byRepo = new Map();
@@ -58,10 +61,18 @@ async function groupFor(list, allSessions) {
     const baseBranch = startFrom === 'branch' || startFrom === 'previous-session' ? first.vcs?.baseBranch?.trim() || 'main' : undefined;
     const baseHead = baseBranch ? (await git(repoDir, ['rev-parse', '--verify', '--quiet', `refs/heads/${baseBranch}^{commit}`])).stdout || null : undefined;
     const settings = inputSettings(first.vcs);
+    const workName = first.vcs?.startFrom === 'existing-branch'
+        ? first.vcs.existingBranch?.trim()
+        : first.vcs?.branchMode === 'per-session' && first.vcsBaseCommit
+            ? sessionBranchName(first)
+            : undefined;
+    const workBranch = workName ? { name: workName, head: (await git(repoDir, ['rev-parse', '--verify', '--quiet', `refs/heads/${workName}^{commit}`])).stdout || null } : undefined;
     const sessions = list.map((s, i) => {
         const sf = s.vcs?.startFrom ?? 'head';
         const role = i === 0 ? 'first' : sf === 'previous-session' ? 'inherits' : sf === 'branch' && (s.vcs?.baseBranch?.trim() || 'main') === baseBranch && !s.vcsBaseCommit ? 'shares' : 'own';
-        return { id: s.id, name: s.name, startFrom: sf, started: !!s.vcsBaseCommit, role };
+        // Started means a task of it ran; a start recorded by the panel (a snapshot) is not that (live run 2026-10-03).
+        const started = s.tasks.some((t) => !!t.startedAt || (t.attempts ?? []).some((a) => !!a.startedAt));
+        return { id: s.id, name: s.name, startFrom: sf, started, hasStart: !!s.vcsBaseCommit, role };
     });
     const pre = await vcsPreflight(first, allSessions);
     const plan = pre.snapshot;
@@ -77,7 +88,11 @@ async function groupFor(list, allSessions) {
         ? []
         : (await dirtyBesidesInputs(repoDir, first.vcsStart)).other
             .filter((path) => !inputPaths.has(path) && !(artifacts.length > 0 && inScope(path, artifacts)))
-            .map((path) => ({ path, ...(reasons.has(path) ? { reason: reasons.get(path) } : {}) }));
+            .map((path) => {
+            // Said under every policy, not only once a snapshot is asked for (live run 2026-10-03: ".env" with no reason).
+            const reason = reasons.get(path) ?? findSuspicious([path])[0]?.reason;
+            return { path, ...(reason ? { reason } : {}) };
+        });
     // Before anything is approved: a pattern that matches nothing is said here, not after the browser opens.
     let problem = pre.ok ? undefined : pre.problem;
     // Problems no approval or setting of version control's own can get past: they need the operator.
@@ -87,7 +102,9 @@ async function groupFor(list, allSessions) {
         const missing = topR.ok ? await missingInputPatterns(first, repoDir, resolve(topR.stdout), allSessions) : [];
         if (missing.length > 0) {
             blocking = true;
-            problem = `the input file pattern(s) ${missing.map((m) => `"${m}"`).join(', ')} match no file in the project: put the files in, or correct "Input files" on the session's page.`;
+            // Added to what was already in the way, not instead of it: the dirty tree was hidden (live run 2026-10-03).
+            const absent = `the input file pattern(s) ${missing.map((m) => `"${m}"`).join(', ')} match no file in the project: put the files in yourself (nothing here can make them), or correct "Input files" on the session's page.`;
+            problem = problem ? `${absent} And besides that: ${problem.charAt(0).toLowerCase()}${problem.slice(1)}` : absent;
         }
     }
     /*
@@ -121,7 +138,7 @@ async function groupFor(list, allSessions) {
         const why = !baseHead
             ? `there is no local branch "${baseBranch}"`
             : unrelated.length > 0
-                ? `besides the input files there are other uncommitted changes (${unrelated.slice(0, 5).map((u) => u.path).join(', ')}${unrelated.length > 5 ? '…' : ''}): commit or stash them first, or use the current branch instead`
+                ? `besides the input files there are other uncommitted changes (${unrelated.slice(0, 5).map((u) => u.path).join(', ')}${unrelated.length > 5 ? '…' : ''}): commit or stash them first${branch !== baseBranch ? ', or use the current branch instead' : ', or take them as a starting snapshot'}`
                 : blockedInputs.length > 0
                     ? `${blockedInputs.map((b) => b.path).join(', ')} cannot be taken as input files`
                     : problem && /match no file/.test(problem)
@@ -130,14 +147,25 @@ async function groupFor(list, allSessions) {
         actions.push({
             id: 'snapshot-on-base',
             available: !why,
-            recommended: !why && branch !== baseBranch,
+            // The fix that leaves the checkout alone: recommended whenever it can be pressed (live run 2026-10-03: not marked on the base branch).
+            recommended: !why,
             ...(why ? { why } : {}),
-            result: `Commits the ${inputs.length} input file(s) on top of "${baseBranch}" (${short(baseHead)}) as "Capture user-provided inputs", on the new branch ${baselineName}, ` +
-                `without switching branches: your checkout${branch ? ` of "${branch}"` : ''} and the files stay exactly as they are. ` +
-                `${names(sharing)} start from it${inheriting.length > 0 ? `; ${names(inheriting)} carry it on through the chain` : ''}.`,
+            // The update from the remote said first: it moves the base branch, and the checkout with it when that is the branch checked out (live run 2026-10-04).
+            result: (first.vcs?.updateFromRemote !== false
+                ? `First brings "${baseBranch}" up to its remote, fast-forward only${branch === baseBranch ? ', which moves your checkout with it' : ''}; then commits`
+                : 'Commits') +
+                ` the ${inputs.length} input file(s) on top of "${baseBranch}" (${short(baseHead)}${first.vcs?.updateFromRemote !== false ? ' now, or where the update takes it' : ''}) as "Capture user-provided inputs", on the new branch ${baselineName}, ` +
+                `without switching branches: your checkout${branch ? ` of "${branch}"` : ''} and the files stay as they are${first.vcs?.updateFromRemote !== false && branch === baseBranch ? ', apart from that update' : ''}. ` +
+                `${names(sharing)} ${verb(sharing, 'starts', 'start')} from it${inheriting.length > 0 ? `; ${names(inheriting)} ${verb(inheriting, 'carries', 'carry')} it on through the chain` : ''}.`,
         });
     }
-    if (plan?.needed && plan.ok && plan.requireApproval) {
+    /*
+     * On the base branch already, with only the inputs uncommitted, the snapshot "where the repository is"
+     * is the snapshot on the base branch under a second button with the same label (seen live on
+     * 2026-10-03: two "Create starting snapshot on main"). The one that leaves the checkout alone stays.
+     */
+    const onBaseOffered = actions.some((a) => a.id === 'snapshot-on-base' && a.available);
+    if (plan?.needed && plan.ok && plan.requireApproval && !(onBaseOffered && branch === baseBranch)) {
         actions.push({
             id: 'snapshot-here',
             available: true,
@@ -151,17 +179,37 @@ async function groupFor(list, allSessions) {
         actions.push({
             id: 'use-current-branch',
             available: true,
-            result: `${names(sharing)} start from "${branch}" (${short(head)}) instead of "${baseBranch}": their "Start from" becomes "From wherever the repository is". ` +
+            result: `${names(sharing)} ${verb(sharing, 'starts', 'start')} from the local branch "${branch}" (${short(head)} now) instead of "${baseBranch}": ${verb(sharing, 'its', 'their')} base branch becomes "${branch}". ` +
                 'Nothing is committed yet; a snapshot on that branch is offered next if one is needed.',
         });
     }
-    if (!plan?.needed && unrelated.length > 0 && dirtyPolicy(first.vcs).policy === 'reject' && !first.vcsBaseCommit && !noCommits) {
+    /*
+     * Offered whenever other uncommitted files are in the way under "refuse", inputs or not. It used to need
+     * `!plan.needed`, and input files make a snapshot needed — so exactly when inputs sat next to other
+     * changes it never appeared, "use the current branch" left only "review", and the panel could not become
+     * ready (live run 2026-10-03).
+     */
+    if (unrelated.length > 0 && dirtyPolicy(first.vcs).policy === 'reject' && !first.vcsBaseCommit && !noCommits) {
         actions.push({
             id: 'allow-snapshot',
             available: true,
             result: `"Uncommitted changes" for "${first.name}" becomes "Take them as a starting snapshot": the files are listed here for you to approve. Nothing is committed yet.`,
         });
     }
+    /*
+     * While something only the operator can fix is in the way — an input that is not there, a branch that
+     * does not exist — no fix here can make the run ready: each says so instead of being offered as one
+     * (live run 2026-10-03: "fixes" offered that could never clear the refusal).
+     */
+    if (blocking) {
+        for (const a of actions) {
+            if (a.id === 'review-inputs' || !a.available)
+                continue;
+            a.available = false;
+            a.recommended = false;
+            a.why = 'first the problem above has to be fixed outside the bot; this cannot make the run ready until then.';
+        }
+    }
     return {
         repoDir,
         ready,
@@ -169,6 +217,10 @@ async function groupFor(list, allSessions) {
         branch,
         head,
         ...(baseBranch ? { baseBranch, baseHead } : {}),
+        ...(workBranch && workBranch.name !== branch ? { workBranch } : {}),
+        ...(settings && inputs.length === 0 && !first.vcsBaseCommit && !blocking
+            ? { carry: `the input files (${settings.patterns.join(', ')}) are not in the working tree: when the first task starts they are committed on top of its start as ${prefix}input/${first.id}, from the latest earlier capture of them` }
+            : {}),
         sessions,
         inputPatterns: settings?.patterns ?? [],
         inputs,
@@ -194,16 +246,23 @@ export async function runVcsPrepare(sessions, repoDir, action, choices, bus, sav
     if (action === 'review-inputs')
         return { ok: true, result: offered.result };
     if (action === 'use-current-branch') {
-        const moved = group.sessions.filter((s) => (s.role === 'first' || s.role === 'shares') && !s.started);
+        const moved = group.sessions.filter((s) => (s.role === 'first' || s.role === 'shares') && !s.hasStart);
         for (const s of moved) {
             await saveSession(s.id, (x) => {
-                if (x.vcs)
-                    x.vcs.startFrom = 'head';
+                /*
+                 * The branch the operator was shown, pinned as the base branch. "From wherever the repository is"
+                 * read HEAD when each session's first task began, and HEAD moves between sessions — the next one
+                 * would have started from the branch of the one before (live run 2026-10-03).
+                 */
+                if (x.vcs) {
+                    x.vcs.startFrom = 'branch';
+                    x.vcs.baseBranch = group.branch ?? undefined;
+                }
                 x.vcsBaseCommit = undefined;
                 x.vcsStart = undefined;
             });
         }
-        return { ok: true, result: `${names(moved)} now start from "${group.branch}".` };
+        return { ok: true, result: `${names(moved)} now ${verb(moved, 'starts', 'start')} from "${group.branch}".` };
     }
     if (action === 'allow-snapshot') {
         await saveSession(first.id, (x) => {
@@ -218,36 +277,42 @@ export async function runVcsPrepare(sessions, repoDir, action, choices, bus, sav
     }
     // snapshot-on-base: the base branch's tree plus the approved inputs only, with a temporary index.
     const paths = group.inputs.map((e) => e.path);
-    const shown = Object.keys(choices).sort();
-    if (JSON.stringify(shown) !== JSON.stringify([...paths].sort()) || paths.some((p) => choices[p] !== 'include')) {
-        return { ok: false, problem: 'the input files changed since the list was shown. Look at the list again; nothing was done.' };
-    }
+    const wrong = approvalMismatch(paths, choices, { allMustBeIncluded: true });
+    if (wrong)
+        return { ok: false, problem: wrong };
     const topR = await git(repoDir, ['rev-parse', '--show-toplevel']);
     if (!topR.ok || !topR.stdout || !group.baseHead || !group.baseBranch)
         return { ok: false, problem: 'the base branch could not be read.' };
     const top = resolve(topR.stdout);
+    /*
+     * The base branch brought up to its remote first, when the session asks for that, as a start from the
+     * branch does: the snapshot is the commit every session here starts from, and it skipped the update
+     * without a word, so a run cut its work from a main the team had already moved past (live run 2026-10-03).
+     */
+    const update = first.vcs?.updateFromRemote !== false ? await updateFromRemote(top, group.baseBranch) : undefined;
+    const baseHead = (await git(top, ['rev-parse', '--verify', '--quiet', `refs/heads/${group.baseBranch}^{commit}`])).stdout || group.baseHead;
     const files = [];
     for (const path of paths) {
         const blob = await git(top, ['hash-object', '-w', `--path=${path}`, '--', join(top, path)]);
         if (!blob.ok || !blob.stdout)
             return { ok: false, problem: `${path} could not be read into git: ${blob.stderr}` };
-        const mode = (await git(top, ['ls-tree', group.baseHead, '--', path])).stdout.split(' ')[0] || '100644';
+        const mode = (await git(top, ['ls-tree', baseHead, '--', path])).stdout.split(' ')[0] || '100644';
         files.push({ path, mode, blob: blob.stdout });
     }
     const branch = await freeBranchName(top, `${branchNameFrom(['baseline'], first.vcs?.branchPrefix || 'cop/')}/${first.id}`);
-    const sharing = group.sessions.filter((s) => (s.role === 'first' || s.role === 'shares') && !s.started);
+    const sharing = group.sessions.filter((s) => (s.role === 'first' || s.role === 'shares') && !s.hasStart);
     const message = [
         'Capture user-provided inputs',
         '',
-        `The operator's input files, approved on the run screen, on top of "${group.baseBranch}" (${short(group.baseHead)}).`,
-        `Made without switching branches; the sessions ${names(sharing)} start from it. The work reads them and does not change them.`,
+        `The operator's input files, approved on the run screen, on top of "${group.baseBranch}" (${short(baseHead)}).`,
+        `Made without switching branches; ${verb(sharing, 'the session', 'the sessions')} ${names(sharing)} ${verb(sharing, 'starts', 'start')} from it. The work reads them and does not change them.`,
         '',
         ...paths.slice(0, 200).map((p) => `- ${p}`),
         '',
         'Committed by copilot-operator. Not pushed.',
         '',
     ].join('\n');
-    const made = await commitOnto(top, group.baseHead, files, message, branch);
+    const made = await commitOnto(top, baseHead, files, message, branch);
     if ('problem' in made)
         return { ok: false, problem: made.problem };
     const settings = inputSettings(first.vcs);
@@ -258,9 +323,10 @@ export async function runVcsPrepare(sessions, repoDir, action, choices, bus, sav
             kind: 'snapshot',
             commit: made.commit,
             branch,
+            ...(update ? { update } : {}),
             snapshot: {
                 fromBranch: group.baseBranch,
-                fromCommit: group.baseHead,
+                fromCommit: baseHead,
                 included: paths.slice(0, 500),
                 leftOut: [],
                 approved: true,
@@ -278,9 +344,12 @@ export async function runVcsPrepare(sessions, repoDir, action, choices, bus, sav
             sessionId: s.id,
             type: 'vcs-snapshot',
             level: 'info',
-            message: `starting snapshot approved on the run screen: ${paths.length} input file(s) on top of ${group.baseBranch} (${short(group.baseHead)}) as ${short(made.commit)} on ${branch}; the checkout was not touched`,
-            data: { commit: made.commit, branch, base: group.baseHead, baseBranch: group.baseBranch, inputs: paths, approvedAt, sessions: sharing.map((x) => x.id) },
+            message: `starting snapshot approved on the run screen: ${paths.length} input file(s) on top of ${group.baseBranch} (${short(baseHead)}) as ${short(made.commit)} on ${branch}; ` +
+                (update?.outcome === 'updated' && group.branch === group.baseBranch
+                    ? `the checked-out ${group.baseBranch} was fast-forwarded to ${update.remote ?? 'its remote'} first, and nothing else in the checkout was touched`
+                    : 'the checkout was not touched'),
+            data: { commit: made.commit, branch, base: baseHead, baseBranch: group.baseBranch, inputs: paths, approvedAt, sessions: sharing.map((x) => x.id) },
         });
     }
-    return { ok: true, result: `taken: ${short(made.commit)} on ${branch}, on top of "${group.baseBranch}"; ${names(sharing)} start from it.` };
+    return { ok: true, result: `${update ? `${describeUpdate(update)}. ` : ''}taken: ${short(made.commit)} on ${branch}, on top of "${group.baseBranch}" (${short(baseHead)}); ${names(sharing)} ${verb(sharing, 'starts', 'start')} from it.` };
 }

package/dist/src/vcs/scope.js

@@ -144,12 +144,28 @@ export function scopeMessage(check, scope, readOnly = false) {
     return parts.filter(Boolean).join(' ');
 }
 /** The line the opening message carries, so the chat knows the rule before its first step. */
-export function scopeNote(scope, enforced) {
+export function scopeNote(scope, enforced, 
+/** The session's artifact patterns and the task's declared outputs: not put back, and kept only as said here. */
+evidence = {}) {
     if (scope.length === 0)
         return '';
+    const artifacts = evidence.artifacts ?? [];
+    const outputs = evidence.outputs ?? [];
+    /*
+     * One account of what is put back and what is kept. The message said "anything outside is put back",
+     * then "this task is to produce" a file outside, then "evidence goes under reports/**" — and a report
+     * there outside the scope was neither put back nor kept (live run 2026-10-03).
+     */
+    const exempt = [
+        ...(outputs.length > 0 ? [`the files this task is to produce (${outputs.join(', ')}) are not put back and are kept with the run`] : []),
+        ...(artifacts.length > 0
+            ? [`files under ${artifacts.join(', ')} are never committed and are not put back; of those, only the ones inside the paths above${outputs.length > 0 ? ' or among the files to produce' : ''} are kept with the run`]
+            : []),
+    ];
     return (`## Scope\n\nThis task may change only these paths (repository-relative): ${scope.join(', ')}. ` +
         (enforced
             ? 'After every round of steps the runner puts back any change outside them and tells you which.'
-            : 'Version control is off for this session, so this is not enforced: keep to it.') +
+            : `${evidence.why ?? 'Version control is off for this session'}, so this is not enforced: keep to it.`) +
+        (exempt.length > 0 ? ` Except: ${exempt.join('; ')}.` : '') +
         ' Reading any file in the project is fine.');
 }

package/dist/src/vcs/snapshot.js

@@ -199,6 +199,15 @@ export async function planSnapshot(session, allSessions = async () => []) {
             continue;
         }
         const artifact = artifactPatterns(session.vcs).length > 0 && inScope(s.path, artifactPatterns(session.vcs));
+        /*
+         * A name that looks temporary (scratch.txt, tmp-x, a .bak) is the operator's to decide: left out unless
+         * ticked, not forced out. The rule was written for the chat's own scratch copies, and it took the choice
+         * away from an operator's own note (live run 2026-10-04).
+         */
+        if (!artifact && !outside && /^a (temporary copy|scratch folder)/.test(generated?.reason ?? '')) {
+            plan.entries.push({ path: s.path, kind: 'untracked', size: await size(s.path), allowed: ['include', 'leave-out'], choice: 'leave-out', reason: 'looks like a temporary or scratch file: left out unless you include it' });
+            continue;
+        }
         const why = artifact
             ? 'an artifact: kept with the run, never committed'
             : generated ? generated.reason : outside ? `outside the project folder ${project}` : policy === 'tracked-only-snapshot' ? 'a new file, and this session takes tracked changes only' : undefined;
@@ -296,15 +305,46 @@ function excludePattern(path) {
     return `/${path.replace(/[\\*?[]/g, (c) => `\\${c}`).replace(/ $/, '\\ ')}`;
 }
 /** Adds the files to the repository's own exclude list, under a line that says who and why. */
+/**
+ * Why an approval does not match the list it answers, said as what is wrong, or null when it matches.
+ * Every mismatch used to read "the files changed since the list was shown", also when the approval only
+ * left a file without a choice and nothing had changed (live run 2026-10-03).
+ */
+export function approvalMismatch(listed, choices, opts = {}) {
+    const given = Object.keys(choices);
+    const missing = listed.filter((p) => !(p in choices));
+    const unknown = given.filter((p) => !listed.includes(p));
+    const leftOut = opts.allMustBeIncluded ? listed.filter((p) => p in choices && choices[p] !== 'include') : [];
+    const some = (paths) => paths.slice(0, 5).join(', ') + (paths.length > 5 ? ` and ${paths.length - 5} more` : '');
+    const parts = [
+        ...(unknown.length > 0 ? [`${some(unknown)} ${unknown.length === 1 ? 'is' : 'are'} not on the list any more — the files changed since it was shown`] : []),
+        ...(missing.length > 0 ? [`the approval has no choice for ${some(missing)}`] : []),
+        ...(leftOut.length > 0 ? [`every input file is taken into this snapshot, and ${some(leftOut)} ${leftOut.length === 1 ? 'was' : 'were'} left out`] : []),
+    ];
+    return parts.length === 0 ? null : `${parts.join('; ')}. Look at the list again; nothing was done.`;
+}
+/**
+ * Writes the left-out files into `.git/info/exclude`. `undo` puts the file back as it was, for every way
+ * the snapshot can still fail afterwards: the failure says the repository is back as it was, and a
+ * left-out file silently gone from `git status` would make that untrue.
+ */
 async function leaveOut(top, session, paths) {
+    const nothing = { undo: async () => undefined };
     if (paths.length === 0)
-        return undefined;
+        return nothing;
     const where = await git(top, ['rev-parse', '--git-path', 'info/exclude']);
     if (!where.ok || !where.stdout)
-        return 'the repository\'s exclude file could not be found';
+        return { ...nothing, problem: 'the repository\'s exclude file could not be found' };
     const file = resolve(top, where.stdout);
     await mkdir(dirname(file), { recursive: true });
+    const existed = await readFile(file, 'utf8').then(() => true, () => false);
     const before = await readFile(file, 'utf8').catch(() => '');
+    const undo = async () => {
+        if (existed)
+            await writeFile(file, before, 'utf8').catch(() => undefined);
+        else
+            await rm(file, { force: true }).catch(() => undefined);
+    };
     const block = [
         `# copilot-operator: left out of the starting snapshot of session "${session.name.replace(/[\r\n]+/g, ' ')}" (${session.id}), ${new Date().toISOString()}`,
         ...paths.map(excludePattern),
@@ -314,9 +354,10 @@ async function leaveOut(top, session, paths) {
         await writeFile(file, `${before}${before && !before.endsWith('\n') ? '\n' : ''}${block}`, 'utf8');
     }
     catch (err) {
-        return `the exclude file could not be written: ${err.message}`;
+        await undo();
+        return { ...nothing, problem: `the exclude file could not be written: ${err.message}` };
     }
-    return undefined;
+    return { undo };
 }
 /** The commit message: what was taken, what was left out, from where, and on whose word. */
 function snapshotMessage(session, plan, taken, leftOut, approved) {
@@ -327,7 +368,7 @@ function snapshotMessage(session, plan, taken, leftOut, approved) {
     return [
         onlyInputs ? 'Capture user-provided inputs' : 'Capture operator baseline before run',
         '',
-        `The ${onlyInputs ? "operator's input files" : 'uncommitted changes in the repository'} when session "${session.name}" was first run, committed so that`,
+        `The ${onlyInputs ? "operator's input files" : 'uncommitted changes in the repository'} of session "${session.name}", ${approved ? 'approved by the operator and ' : ''}committed before its first task so that`,
         "the session starts from them and every task's commit shows only that task's work.",
         ...(inputs.length > 0
             ? ['', `Input files, read by the work and not changed by it (${inputs.length}):`, list(inputs.map((e) => `${e.path}${e.size !== undefined ? ` (${e.size} bytes, ${e.kind})` : ''}`))]
@@ -361,9 +402,9 @@ export async function takeSnapshot(session, opts, bus, saveSession, allSessions
             return { ok: false, problem: plan.problem ?? 'the input files cannot be taken.' };
         const paths = plan.entries.map((e) => e.path);
         if (opts.approved) {
-            const shown = Object.keys(opts.choices ?? {}).sort();
-            if (JSON.stringify(shown) !== JSON.stringify([...paths].sort()) || paths.some((p) => opts.choices?.[p] !== 'include')) {
-                return { ok: false, problem: 'the input files changed since the list was shown. Look at the list again; nothing was done.' };
+            const wrong = approvalMismatch(paths, opts.choices ?? {}, { allMustBeIncluded: true });
+            if (wrong) {
+                return { ok: false, problem: wrong };
             }
         }
         const made = await recaptureInputs(session, plan.repoDir, paths, plan.recapture);
@@ -405,11 +446,9 @@ export async function takeSnapshot(session, opts, bus, saveSession, allSessions
     const chosen = new Map();
     if (opts.approved) {
         const choices = opts.choices ?? {};
-        const shown = Object.keys(choices).sort();
-        const now = plan.entries.map((e) => e.path).sort();
-        if (JSON.stringify(shown) !== JSON.stringify(now)) {
-            return { ok: false, problem: 'the uncommitted files changed since the list was shown. Look at the list again; nothing was done.' };
-        }
+        const wrong = approvalMismatch(plan.entries.map((e) => e.path), choices);
+        if (wrong)
+            return { ok: false, problem: wrong };
         for (const e of plan.entries) {
             const c = choices[e.path];
             if (!c || !e.allowed.includes(c))
@@ -436,22 +475,26 @@ export async function takeSnapshot(session, opts, bus, saveSession, allSessions
     if (take.length === 0)
         return { ok: false, problem: 'nothing would be taken: every file is left out. Leave them out yourself, or take at least one.' };
     const excluded = await leaveOut(top, session, leaveOutPaths);
-    if (excluded)
-        return { ok: false, problem: excluded };
+    if (excluded.problem)
+        return { ok: false, problem: excluded.problem };
     // With the left-out files gone from git's view, what is uncommitted must be exactly what is taken.
     const after = await statusEntries(top);
     const wanted = new Set(take.filter((e) => e.kind !== 'ignored').map((e) => e.path));
     const stray = (after ?? []).filter((s) => !wanted.has(s.path)).map((s) => s.path);
     if (!after || stray.length > 0) {
+        await excluded.undo();
         return { ok: false, problem: `the repository changed while the snapshot was being taken (${someOf(stray)}). Nothing was committed; look at the list again.` };
     }
     const branch = plan.baselineBranch;
     const cut = await git(top, ['checkout', '-b', branch]);
-    if (!cut.ok)
+    if (!cut.ok) {
+        await excluded.undo();
         return { ok: false, problem: `the branch ${branch} could not be made: ${cut.stderr || cut.stdout}` };
+    }
     const back = async (why) => {
         if (plan.branch)
             await git(top, ['checkout', plan.branch]);
+        await excluded.undo();
         return { ok: false, problem: `${why} Nothing was committed; the repository is back on ${plan.branch ?? 'where it was'} with your changes as they were.` };
     };
     // Literal paths from a file: no glob in a name is read as a pattern, and no command line gets too long.
@@ -487,6 +530,8 @@ export async function takeSnapshot(session, opts, bus, saveSession, allSessions
             included: take.map((e) => e.path).slice(0, 500),
             leftOut: leftOutAll.slice(0, 500),
             approved: opts.approved,
+            // When, so the record and the run log say it (live run 2026-10-03: never timestamped).
+            ...(opts.approved ? { approvedAt: new Date().toISOString() } : {}),
         },
     };
     await saveSession((s) => {

package/dist/src/vcs/syncCommand.js

@@ -14,9 +14,7 @@
  * Nothing here writes to the repository or the network. `git fetch` is in the command, not here:
  * what "would be lost" is computed against the remote branch as last fetched, and the page says so.
  */
-import { statSync } from 'node:fs';
-import { join } from 'node:path';
-import { git, porcelainPaths } from './git.js';
+import { git, lastFetchedAt, porcelainPaths } from './git.js';
 /** A string as a single-quoted PowerShell literal: nothing inside it is expanded. */
 export function psQuote(text) {
     return `'${text.replace(/'/g, "''")}'`;
@@ -77,14 +75,8 @@ export async function planSync(repoDir) {
     const commits = await git(repoDir, ['log', '--format=%h %s', `${target}..HEAD`]);
     const status = await git(repoDir, ['status', '--porcelain', '--untracked-files=no']);
     const clean = await git(repoDir, ['clean', '-nd']);
-    let lastFetched;
-    try {
-        const gitDir = (await git(repoDir, ['rev-parse', '--absolute-git-dir'])).stdout;
-        lastFetched = statSync(join(gitDir, 'FETCH_HEAD')).mtime.toISOString();
-    }
-    catch {
-        /* never fetched: the page says so */
-    }
+    const gitDir = (await git(repoDir, ['rev-parse', '--absolute-git-dir'])).stdout;
+    const lastFetched = gitDir ? lastFetchedAt(gitDir) : undefined;
     return {
         ok: true,
         repoDir,