copilot-operator 0.1.38 → 0.1.40

package/dist/src/vcs/runPreflight.js

@@ -27,7 +27,7 @@ import { join, resolve } from 'node:path';
 import { branchNameFrom, describeUpdate, freeBranchName, git, updateFromRemote } from './git.js';
 import { commitOnto, dirtyBesidesInputs, inputSettings, inputSumsAt, missingInputPatterns } from './inputs.js';
 import { approvalMismatch, dirtyPolicy, takeSnapshot } from './snapshot.js';
-import { repoDirOf, sessionBranchName, vcsPreflight } from './taskVcs.js';
+import { baseRefOf, repoDirOf, sessionBranchName, vcsPreflight } from './taskVcs.js';
 import { artifactPatterns } from './artifacts.js';
 import { inScope } from './scope.js';
 import { findSuspicious } from './commitHygiene.js';
@@ -58,8 +58,15 @@ async function groupFor(list, allSessions) {
     const branch = branchR.ok && branchR.stdout !== 'HEAD' ? branchR.stdout : null;
     const head = headR.ok && headR.stdout ? headR.stdout : null;
     const startFrom = first.vcs?.startFrom ?? 'head';
-    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;
+    /*
+     * The branch the sessions start from, by its name on screen (`origin/x` for a remote branch chosen in
+     * the start window) and the ref git reads for it: a remote-tracking branch is never the local one of
+     * the same name, and is not brought up to anything here — the start window fetched it.
+     */
+    const base = startFrom === 'branch' || startFrom === 'previous-session' ? baseRefOf(first.vcs) : undefined;
+    const baseBranch = base?.name;
+    const baseHead = base ? (await git(repoDir, ['rev-parse', '--verify', '--quiet', `${base.ref}^{commit}`])).stdout || null : undefined;
+    const updates = first.vcs?.updateFromRemote !== false && !base?.remote;
     const settings = inputSettings(first.vcs);
     const workName = first.vcs?.startFrom === 'existing-branch'
         ? first.vcs.existingBranch?.trim()
@@ -69,7 +76,7 @@ async function groupFor(list, allSessions) {
     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';
+        const role = i === 0 ? 'first' : sf === 'previous-session' ? 'inherits' : sf === 'branch' && baseRefOf(s.vcs).name === baseBranch && !s.vcsBaseCommit ? 'shares' : 'own';
         // 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 };
@@ -111,16 +118,21 @@ async function groupFor(list, allSessions) {
      * The branches the sessions name, before the browser opens rather than at their first task: a
      * branch to carry on that is not there, a base branch that is not there.
      */
+    const otherThanStart = (!!problem && !pre.startProblem) || blocking;
+    let branchMissing = false;
     for (const s of list) {
         if (s.vcsBaseCommit)
             continue;
-        const named = s.vcs?.startFrom === 'existing-branch' ? s.vcs.existingBranch?.trim() : s.vcs?.startFrom === 'branch' ? s.vcs.baseBranch?.trim() || 'main' : '';
-        if (!named)
+        const named = s.vcs?.startFrom === 'existing-branch' ? { ref: `refs/heads/${s.vcs.existingBranch?.trim() ?? ''}`, name: s.vcs.existingBranch?.trim() ?? '', remote: undefined } : s.vcs?.startFrom === 'branch' ? baseRefOf(s.vcs) : null;
+        if (!named?.name)
             continue;
-        const there = (await git(repoDir, ['rev-parse', '--verify', '--quiet', `refs/heads/${named}^{commit}`])).stdout;
+        const there = (await git(repoDir, ['rev-parse', '--verify', '--quiet', `${named.ref}^{commit}`])).stdout;
         if (!there) {
             blocking = true;
-            problem = `${problem ? `${problem} ` : ''}"${s.name}" is set to ${s.vcs?.startFrom === 'existing-branch' ? 'carry on' : 'start from'} the local branch "${named}", and there is no such branch: create it, or change "Start from" on the session's page.`;
+            branchMissing = true;
+            problem =
+                `${problem ? `${problem} ` : ''}"${s.name}" is set to ${s.vcs?.startFrom === 'existing-branch' ? 'carry on' : 'start from'} the ${named.remote ? 'remote' : 'local'} branch "${named.name}", and there is no such branch` +
+                    (named.remote ? ' here: start the run again and choose it in the start window, which fetches it.' : ': create it, or choose another branch when you start the run.');
         }
     }
     const noCommits = first.vcs?.commitOnFinish === false;
@@ -136,7 +148,7 @@ async function groupFor(list, allSessions) {
     }
     if (baseBranch && !first.vcsBaseCommit && inputs.length > 0) {
         const why = !baseHead
-            ? `there is no local branch "${baseBranch}"`
+            ? `there is no ${base?.remote ? 'fetched copy of the remote' : '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${branch !== baseBranch ? ', or use the current branch instead' : ', or take them as a starting snapshot'}`
                 : blockedInputs.length > 0
@@ -151,11 +163,11 @@ async function groupFor(list, allSessions) {
             recommended: !why,
             ...(why ? { why } : {}),
             // 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
+            result: (updates
                 ? `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' : ''}. ` +
+                ` the ${inputs.length} input file(s) on top of "${baseBranch}" (${short(baseHead)}${updates ? ' 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${updates && 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` : ''}.`,
         });
     }
@@ -218,6 +230,7 @@ async function groupFor(list, allSessions) {
         head,
         ...(baseBranch ? { baseBranch, baseHead } : {}),
         ...(workBranch && workBranch.name !== branch ? { workBranch } : {}),
+        ...(!ready && !otherThanStart && (branchMissing || pre.startProblem) ? { startChoiceCanFix: true } : {}),
         ...(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` }
             : {}),
@@ -257,6 +270,8 @@ export async function runVcsPrepare(sessions, repoDir, action, choices, bus, sav
                 if (x.vcs) {
                     x.vcs.startFrom = 'branch';
                     x.vcs.baseBranch = group.branch ?? undefined;
+                    // The branch the repository is on is a local one.
+                    delete x.vcs.baseRemote;
                 }
                 x.vcsBaseCommit = undefined;
                 x.vcsStart = undefined;
@@ -289,8 +304,10 @@ export async function runVcsPrepare(sessions, repoDir, action, choices, bus, sav
      * 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;
+    // Not a remote branch chosen in the start window: that was fetched there, and has no local branch to move.
+    const baseRef = baseRefOf(first.vcs);
+    const update = first.vcs?.updateFromRemote !== false && !baseRef.remote ? await updateFromRemote(top, group.baseBranch) : undefined;
+    const baseHead = (await git(top, ['rev-parse', '--verify', '--quiet', `${baseRef.ref}^{commit}`])).stdout || group.baseHead;
     const files = [];
     for (const path of paths) {
         const blob = await git(top, ['hash-object', '-w', `--path=${path}`, '--', join(top, path)]);

package/dist/src/vcs/snapshot.js

@@ -119,7 +119,9 @@ async function startProblem(session, dir, branch, head, allSessions) {
     const commit = resolved.start?.commit;
     if (!commit || commit === head)
         return undefined;
-    const wanted = resolved.start?.kind === 'previous-session' ? `the end of "${resolved.start.fromSession?.name ?? ''}"'s branch ${resolved.start.branch}` : `the local branch ${resolved.start?.branch ?? ''}`;
+    const wanted = resolved.start?.kind === 'previous-session'
+        ? `the end of "${resolved.start.fromSession?.name ?? ''}"'s branch ${resolved.start.branch}`
+        : `the ${resolved.start?.remote ? 'remote' : 'local'} branch ${resolved.start?.branch ?? ''}`;
     return (`the changes are on ${where}, and this session is set to start from ${wanted} (${commit.slice(0, 8)}). ` +
         'A snapshot is taken where the changes are, so the session would not start where it was told to. ' +
         `Put the repository on ${resolved.start?.branch ?? 'that branch'} first, or choose "From wherever the repository is (as until now)".`);

package/dist/src/vcs/startChoice.js

@@ -0,0 +1,295 @@
+import { git, isAncestor, isValidBranchName, lastFetchedAt } from './git.js';
+import { fetchAsOperator, fetchCommandFor } from './remoteAuth.js';
+import { describeStart, remoteTip, repoDirOf } from './taskVcs.js';
+const lines = (s) => s.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+const norm = (dir) => dir.trim().replace(/[\\/]+$/, '').replace(/\//g, '\\').toLowerCase();
+/** A task of the session has run: a start recorded since then is the one its work stands on. */
+export function startIsFixed(session) {
+    const ran = session.tasks.some((t) => !!t.startedAt || (t.attempts ?? []).some((a) => !!a.startedAt));
+    return !!session.vcsBaseCommit && ran;
+}
+/** The branches of the repository at `dir`, read without touching the network. */
+export async function repoBranches(dir) {
+    const empty = (problem) => ({ repoDir: dir, problem, current: null, head: null, local: [], remotes: [] });
+    const inside = await git(dir, ['rev-parse', '--is-inside-work-tree']);
+    if (!inside.ok || inside.stdout !== 'true')
+        return empty(`${dir} is not a git repository.`);
+    const current = await git(dir, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    const head = await git(dir, ['rev-parse', '--verify', '--quiet', 'HEAD']);
+    const refs = await git(dir, ['for-each-ref', '--format=%(objectname) %(refname)', 'refs/heads', 'refs/remotes']);
+    const remoteNames = lines((await git(dir, ['remote'])).stdout);
+    const local = [];
+    const byRemote = new Map(remoteNames.map((r) => [r, []]));
+    for (const line of refs.ok ? lines(refs.stdout) : []) {
+        const [commit, ref] = [line.slice(0, line.indexOf(' ')), line.slice(line.indexOf(' ') + 1)];
+        if (ref.startsWith('refs/heads/'))
+            local.push({ name: ref.slice('refs/heads/'.length), commit });
+        else if (ref.startsWith('refs/remotes/')) {
+            const rest = ref.slice('refs/remotes/'.length);
+            const remote = remoteNames.find((r) => rest.startsWith(`${r}/`));
+            const name = remote ? rest.slice(remote.length + 1) : '';
+            // `origin/HEAD` points at a branch; it is not one.
+            if (!remote || !name || name === 'HEAD')
+                continue;
+            byRemote.get(remote)?.push({ name, commit });
+        }
+    }
+    const gitDir = (await git(dir, ['rev-parse', '--absolute-git-dir'])).stdout;
+    const fetched = gitDir ? lastFetchedAt(gitDir) : undefined;
+    return {
+        repoDir: dir,
+        current: current.ok && current.stdout ? current.stdout : null,
+        head: head.ok && head.stdout ? head.stdout : null,
+        local,
+        remotes: [...byRemote.entries()].map(([name, branches]) => ({ name, branches })),
+        ...(fetched ? { lastFetched: fetched } : {}),
+    };
+}
+/** The remote a branch is most likely wanted from: `origin`, else the first one. */
+export function defaultRemote(repo) {
+    return repo.remotes.find((r) => r.name === 'origin')?.name ?? repo.remotes[0]?.name;
+}
+/**
+ * What the start window offers first for a session: its own setting, as one of the choices. A local
+ * branch that is not here is offered from the remote when the remote has it, else the branch the
+ * repository is on — a start from wherever it happens to be (`head`) is offered as that branch, which
+ * is what it would have been.
+ */
+export function defaultChoice(session, repo) {
+    const vcs = session.vcs;
+    const how = vcs?.startFrom ?? 'head';
+    if (how === 'previous-session')
+        return { from: 'previous-session' };
+    const onBranch = how === 'existing-branch';
+    // A branch the session names, as against one assumed (`main`, or wherever the repository is).
+    const named = (how === 'head' ? '' : (onBranch ? vcs?.existingBranch : vcs?.baseBranch)?.trim()) ?? '';
+    const wanted = named || (how === 'head' ? repo.current ?? '' : 'main');
+    const remote = vcs?.baseRemote?.trim();
+    const hasRemote = (r, b) => !!repo.remotes.find((x) => x.name === r)?.branches.some((x) => x.name === b);
+    if (remote && hasRemote(remote, wanted))
+        return { from: 'remote', remote, branch: wanted, ...(onBranch ? { onBranch } : {}) };
+    if (wanted && repo.local.some((b) => b.name === wanted))
+        return { from: 'local', branch: wanted, ...(onBranch ? { onBranch } : {}) };
+    const other = remote && repo.remotes.some((x) => x.name === remote) ? remote : defaultRemote(repo);
+    if (other && wanted && hasRemote(other, wanted))
+        return { from: 'remote', remote: other, branch: wanted, ...(onBranch ? { onBranch } : {}) };
+    /*
+     * Named, and neither here nor fetched yet — a branch a colleague pushed after the last fetch: offered from
+     * the remote all the same, which the window fetches by name. Offered as the branch the repository is on,
+     * it was started from that instead with one press, and the session's own branch was written over.
+     */
+    if (named && other)
+        return { from: 'remote', remote: other, branch: named, ...(onBranch ? { onBranch } : {}) };
+    return { from: 'local', branch: repo.current ?? repo.local[0]?.name ?? wanted };
+}
+/**
+ * The sessions of a run as the start window shows them, in run order, with the branches of each
+ * repository they work in.
+ */
+export async function startOptions(sessions) {
+    const repos = new Map();
+    const out = [];
+    const seenRepos = new Set();
+    for (const s of sessions) {
+        const dir = s.vcs?.enabled ? repoDirOf(s) : '';
+        if (!dir) {
+            out.push({ id: s.id, name: s.name, vcs: false, previousOffered: false });
+            continue;
+        }
+        const key = norm(dir);
+        if (!repos.has(key))
+            repos.set(key, await repoBranches(dir));
+        const repo = repos.get(key);
+        const earlierHere = seenRepos.has(key);
+        seenRepos.add(key);
+        const entry = {
+            id: s.id,
+            name: s.name,
+            vcs: true,
+            repoDir: repo.repoDir,
+            previousOffered: s.vcs?.startFrom === 'previous-session' || earlierHere,
+        };
+        if (startIsFixed(s) && s.vcsStart)
+            entry.fixed = describeStart(s.vcsStart);
+        else if (startIsFixed(s))
+            entry.fixed = `it started from ${s.vcsBaseCommit?.slice(0, 8)}`;
+        else {
+            if (s.vcsStart)
+                entry.prepared = describeStart(s.vcsStart);
+            if (!repo.problem)
+                entry.choice = defaultChoice(s, repo);
+        }
+        out.push(entry);
+    }
+    return { repos: [...repos.values()], sessions: out };
+}
+/**
+ * Checks a choice against the repository and works out what it sets. Nothing is written to the session
+ * here; for `remote` with `onBranch` the local branch is made, or moved forward, since that is the
+ * choice — and only then, after everything else about it has been checked, and never with `dry`, which
+ * only says whether it could be done (every session of a run is checked so before any branch moves).
+ */
+export async function applyStartChoice(session, choice, opts = {}) {
+    // Nothing to choose without version control, or once the start is fixed: see `startIsFixed`.
+    if (!session.vcs?.enabled || startIsFixed(session))
+        return { ok: true };
+    const dir = repoDirOf(session);
+    const before = pointOf(session.vcs);
+    if (choice.from === 'previous-session') {
+        const vcs = { startFrom: 'previous-session' };
+        return { ok: true, applied: { vcs, clearStart: changed(before, { ...session.vcs, ...vcs }) && !!session.vcsBaseCommit, said: `"${session.name}" carries on the session before it in this repository` } };
+    }
+    const name = choice.branch.trim();
+    if (!name || !(await isValidBranchName(dir, name)))
+        return { ok: false, problem: `"${choice.branch}" is not a branch name git accepts.` };
+    if (choice.from === 'local') {
+        const tip = (await git(dir, ['rev-parse', '--verify', '--quiet', `refs/heads/${name}^{commit}`])).stdout;
+        if (!tip)
+            return { ok: false, problem: `${dir} has no local branch "${name}". Choose one it has, or the remote branch of that name.` };
+        const vcs = choice.onBranch
+            ? { startFrom: 'existing-branch', existingBranch: name, baseRemote: undefined, updateFromRemote: false }
+            : { startFrom: 'branch', baseBranch: name, baseRemote: undefined, existingBranch: undefined, updateFromRemote: false };
+        return {
+            ok: true,
+            applied: {
+                vcs,
+                clearStart: changed(before, { ...session.vcs, ...vcs }) && !!session.vcsBaseCommit,
+                said: choice.onBranch
+                    ? `"${session.name}" works on the local branch ${name} itself (${tip.slice(0, 8)}), as it is here`
+                    : `"${session.name}" starts from the local branch ${name} (${tip.slice(0, 8)}), as it is here`,
+            },
+        };
+    }
+    const remote = choice.remote.trim();
+    const remotes = lines((await git(dir, ['remote'])).stdout);
+    if (!remotes.includes(remote))
+        return { ok: false, problem: `${dir} has no remote called "${remote}"${remotes.length > 0 ? ` (it has: ${remotes.join(', ')})` : ''}.` };
+    const theirs = await remoteTip(dir, remote, name);
+    if (!theirs)
+        return { ok: false, problem: `${remote}/${name} is not known here: it was not fetched. Start again, and it is fetched first.` };
+    if (!choice.onBranch) {
+        const vcs = { startFrom: 'branch', baseBranch: name, baseRemote: remote, existingBranch: undefined, updateFromRemote: false };
+        return {
+            ok: true,
+            applied: {
+                vcs,
+                clearStart: changed(before, { ...session.vcs, ...vcs }) && !!session.vcsBaseCommit,
+                said: `"${session.name}" starts from the remote branch ${remote}/${name} (${theirs.slice(0, 8)}), as fetched now; the local branch ${name} is not touched`,
+            },
+        };
+    }
+    // Work on the branch itself: the local branch made from the remote one, or brought up to it.
+    const ours = (await git(dir, ['rev-parse', '--verify', '--quiet', `refs/heads/${name}^{commit}`])).stdout;
+    let note;
+    if (!ours) {
+        // By its full name: `origin/x` alone is looked up among tags and local branches first.
+        const made = opts.dry ? { ok: true, stdout: '', stderr: '' } : await git(dir, ['branch', '--track', name, `refs/remotes/${remote}/${name}`]);
+        if (!made.ok)
+            return { ok: false, problem: `the local branch ${name} could not be made from ${remote}/${name}: ${(made.stderr || made.stdout).split(/\r?\n/)[0]}` };
+        note = `made the local branch ${name} from ${remote}/${name} (${theirs.slice(0, 8)})`;
+    }
+    else if (ours === theirs) {
+        note = `the local branch ${name} is already where ${remote}/${name} is (${theirs.slice(0, 8)})`;
+    }
+    else if (await isAncestor(dir, ours, theirs)) {
+        const current = (await git(dir, ['symbolic-ref', '--quiet', '--short', 'HEAD'])).stdout;
+        if (current === name) {
+            const dirty = (await git(dir, ['status', '--porcelain', '--untracked-files=no'])).stdout.trim();
+            if (dirty)
+                return { ok: false, problem: `${name} is checked out with uncommitted changes, so it cannot be brought up to ${remote}/${name}. Commit or stash them first; nothing was changed.` };
+        }
+        const moved = opts.dry
+            ? { ok: true, stdout: '', stderr: '' }
+            : current === name
+                ? await git(dir, ['merge', '--ff-only', '--quiet', theirs])
+                : await git(dir, ['update-ref', '-m', `copilot-operator: brought up to ${remote}/${name} in the start window`, `refs/heads/${name}`, theirs, ours]);
+        if (!moved.ok)
+            return { ok: false, problem: `${name} could not be brought up to ${remote}/${name}: ${(moved.stderr || moved.stdout).split(/\r?\n/)[0]}. Nothing else was changed.` };
+        note = `brought the local branch ${name} up to ${remote}/${name}: ${ours.slice(0, 8)} → ${theirs.slice(0, 8)}, fast-forward`;
+    }
+    else if (await isAncestor(dir, theirs, ours)) {
+        note = `the local branch ${name} has commits ${remote}/${name} does not; it was left as it is (${ours.slice(0, 8)}) and the work goes on top of them`;
+    }
+    else {
+        return {
+            ok: false,
+            problem: `the local branch ${name} (${ours.slice(0, 8)}) and ${remote}/${name} (${theirs.slice(0, 8)}) have each gone their own way, so working on it would mean choosing one of them. ` +
+                `Nothing was changed. Start from ${remote}/${name} on a new branch instead, or bring the two together yourself first.`,
+        };
+    }
+    const vcs = { startFrom: 'existing-branch', existingBranch: name, baseRemote: remote, updateFromRemote: false };
+    return {
+        ok: true,
+        applied: {
+            vcs,
+            clearStart: changed(before, { ...session.vcs, ...vcs }) && !!session.vcsBaseCommit,
+            note,
+            said: `"${session.name}" works on the branch ${name} itself, from ${remote}/${name} as fetched now`,
+        },
+    };
+}
+/** Where a session's settings say it starts: the fields that decide the commit, nothing else. */
+function pointOf(vcs) {
+    return JSON.stringify([vcs?.startFrom ?? 'head', vcs?.baseBranch?.trim() || 'main', vcs?.baseRemote?.trim() ?? '', vcs?.existingBranch?.trim() ?? '']);
+}
+function changed(before, after) {
+    return before !== pointOf(after);
+}
+/** The fields of an `AppliedChoice` written onto a session's version control: `undefined` removes one. */
+export function withChoice(vcs, patch) {
+    const out = { ...vcs };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === undefined)
+            delete out[k];
+        else
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * The refspecs that fetch exactly these branches of `remote` into their remote-tracking branches, or
+ * why one of the names cannot be fetched.
+ */
+export async function refspecsFor(dir, remote, branches) {
+    const refspecs = [];
+    for (const b of [...new Set(branches.map((x) => x.trim()).filter(Boolean))]) {
+        if (!(await isValidBranchName(dir, b)))
+            return { problem: `"${b}" is not a branch name git accepts.` };
+        refspecs.push(`+refs/heads/${b}:refs/remotes/${remote}/${b}`);
+    }
+    return { refspecs };
+}
+/** The branch names a failed fetch said the remote does not have. */
+export function missingOnRemote(detail) {
+    return [...detail.matchAll(/couldn't find remote ref (?:refs\/heads\/)?(\S+)/gi)].map((m) => m[1].replace(/[.,;:]+$/, ''));
+}
+/** Where git keeps the repository's records, for `lastFetchedAt`. */
+export async function gitDirOf(dir) {
+    const r = await git(dir, ['rev-parse', '--absolute-git-dir']);
+    return r.ok && r.stdout ? r.stdout : null;
+}
+/**
+ * Fetches `branches` of `remote` — or the whole remote, pruned, when none are named — for the start
+ * window, where the operator is looking: through Git's password window when there is one (`askpass`).
+ * Only remote-tracking branches move; no local branch, no checkout.
+ */
+export async function fetchForStart(dir, remote, branches, askpass) {
+    const remotes = lines((await git(dir, ['remote'])).stdout);
+    if (!remotes.includes(remote))
+        return { ok: false, problem: `${dir} has no remote called "${remote}"${remotes.length > 0 ? ` (it has: ${remotes.join(', ')})` : ''}.`, missing: [] };
+    const specs = branches && branches.length > 0 ? await refspecsFor(dir, remote, branches) : { refspecs: [] };
+    if ('problem' in specs)
+        return { ok: false, problem: specs.problem, missing: [] };
+    const gitDir = await gitDirOf(dir);
+    // Read before fetching: a fetch that fails empties FETCH_HEAD, and with it the time of the last one that worked.
+    const lastBefore = gitDir ? lastFetchedAt(gitDir) : undefined;
+    const fetched = await fetchAsOperator(dir, remote, { askpass, refspecs: specs.refspecs });
+    const missing = fetched.ok ? [] : missingOnRemote(fetched.detail ?? '');
+    return {
+        ok: fetched.ok,
+        fetched,
+        missing,
+        ...(fetched.ok ? {} : { fetchCommand: fetchCommandFor(dir, remote), ...(lastBefore ? { lastFetched: lastBefore } : {}) }),
+        repo: await repoBranches(dir),
+    };
+}

package/dist/src/vcs/taskVcs.js

@@ -375,9 +375,25 @@ export async function sessionStart(session, dir, head, allSessions,
 opts = {}) {
     const how = session.vcs?.startFrom ?? 'head';
     const baseBranch = session.vcs?.baseBranch?.trim() || 'main';
+    const baseRemote = session.vcs?.baseRemote?.trim() || '';
     if (how === 'head')
         return head ? { start: { kind: 'head', commit: head } } : {};
     const fromBranch = async (note) => {
+        /*
+         * A remote branch chosen in the start window: the remote-tracking branch as that window fetched it,
+         * with the operator there to type a key's passphrase. Not fetched again here — a run's fetch may not
+         * ask anybody anything — and the local branch of that name is neither read nor moved.
+         */
+        if (baseRemote) {
+            const tip = await remoteTip(dir, baseRemote, baseBranch);
+            if (!tip) {
+                return {
+                    problem: `this session is set to start from the remote branch "${baseRemote}/${baseBranch}", and ${dir} has no copy of it. ` +
+                        'Start the run again and choose it in the start window, which fetches it.',
+                };
+            }
+            return { start: { kind: 'branch', commit: tip, branch: `${baseRemote}/${baseBranch}`, remote: baseRemote, ...(note ? { note } : {}) } };
+        }
         // The code as it is on the server, not as this checkout last pulled it: see `updateFromRemote`.
         const update = !opts.dry && session.vcs?.updateFromRemote !== false && (await branchTip(dir, baseBranch)) ? await updateFromRemote(dir, baseBranch) : undefined;
         const tip = await branchTip(dir, baseBranch);
@@ -520,6 +536,22 @@ async function branchTip(dir, branch) {
     const r = await git(dir, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}^{commit}`]);
     return r.ok && r.stdout.trim() ? r.stdout.trim() : null;
 }
+/** Where `<remote>/<branch>` was when it was last fetched here, or null when it never was. */
+export async function remoteTip(dir, remote, branch) {
+    if (!/^[\w.-]+$/.test(remote) || !(await isValidBranchName(dir, branch)))
+        return null;
+    const r = await git(dir, ['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/${branch}^{commit}`]);
+    return r.ok && r.stdout.trim() ? r.stdout.trim() : null;
+}
+/**
+ * The ref a session's `startFrom: branch` reads, and the name it is shown by: `refs/remotes/origin/x`
+ * as `origin/x` for a remote branch chosen in the start window, else `refs/heads/<baseBranch>`.
+ */
+export function baseRefOf(vcs) {
+    const branch = vcs?.baseBranch?.trim() || 'main';
+    const remote = vcs?.baseRemote?.trim();
+    return remote ? { ref: `refs/remotes/${remote}/${branch}`, name: `${remote}/${branch}`, remote, branch } : { ref: `refs/heads/${branch}`, name: branch, branch };
+}
 function normalise(dir) {
     return dir.trim().replace(/[\\/]+$/, '').replace(/\//g, '\\').toLowerCase();
 }
@@ -535,7 +567,9 @@ export function describeStart(start) {
             : start.kind === 'existing-branch'
                 ? `this session carries on the existing branch ${start.branch}, from its tip ${at}`
                 : start.kind === 'branch'
-                    ? `this session starts from the local branch ${start.branch} (${at})`
+                    ? start.remote
+                        ? `this session starts from the remote branch ${start.branch} (${at}), as fetched when the run was started`
+                        : `this session starts from the local branch ${start.branch} (${at})`
                     : `this session starts from where the repository was (${at})`;
     const updated = start.update ? ` (${describeUpdate(start.update)})` : '';
     const plus = carried ? `, plus the operator's input files carried from ${carried.from} as ${start.commit.slice(0, 8)} on ${carried.branch}` : '';
@@ -552,11 +586,11 @@ export async function whereLeft(session) {
     const dir = repoDirOf(session);
     if (!session.vcs?.enabled || files.length === 0 || !dir)
         return null;
-    const base = session.vcs.baseBranch?.trim() || 'main';
+    const { ref, name: base } = baseRefOf(session.vcs);
     const state = await repoState(dir).catch(() => null);
     if (!state?.isRepo || !state.branch || state.branch === base)
         return null;
-    const onBase = await git(dir, ['cat-file', '-e', `refs/heads/${base}:${files[0].path}`]);
+    const onBase = await git(dir, ['cat-file', '-e', `${ref}:${files[0].path}`]);
     if (onBase.ok)
         return null;
     const paths = files.map((f) => f.path);
@@ -598,6 +632,27 @@ export function sessionBranches(session) {
 function firstAttemptBase(task) {
     return earliestBase(task);
 }
+/**
+ * The branch a per-task session's task will be put on when its next attempt starts, worked out before the
+ * run by the rules `prepareForTask` applies at the start: a continuation, or a new prompt on finished work,
+ * goes on the previous attempt's branch; an attempt after one that committed nothing goes on that empty
+ * branch again; otherwise the planned or derived name, "-aN" from the second attempt on. A task that has
+ * run is judged as the attempt it would be queued as, by a plain re-run (no continuation). The one thing
+ * not asked here is whether that empty branch still sits where it was cut, which only the start can see.
+ */
+export function nextAttemptBranch(session, task) {
+    const prefix = session.vcs?.branchPrefix || 'cop/';
+    const ran = task.status !== 'queued';
+    const attempt = (task.attempt ?? 1) + (ran ? 1 : 0);
+    const prev = ran ? { vcs: task.vcs } : task.attempts?.at(-1);
+    const carried = !ran && (task.continuing || task.buildsOn) ? task.attempts?.at(-1)?.vcs?.branch : undefined;
+    if (carried)
+        return carried;
+    if (prev?.vcs?.branch && prev.vcs.baseCommit && !prev.vcs.commit && prev.vcs.baseCommit === firstAttemptBase(task))
+        return prev.vcs.branch;
+    const planned = task.vcsPlan?.branch?.trim();
+    return planned ? plannedBranchName(planned, prefix, attempt) : branchNameFrom([session.name, task.title, attempt > 1 ? `a${attempt}` : undefined], prefix);
+}
 async function switchTo(session, task, dir, wantedName, from, bus, 
 /** `mustExist`: carry on this branch or nothing; never create it. */
 opts) {
@@ -718,7 +773,7 @@ export function noteFor(repoDir, vcs, ctx = { mode: 'per-task', earlier: [] }) {
             : ctx.start?.kind === 'existing-branch'
                 ? `This session carries on the existing branch \`${ctx.start.branch}\`: the work already on it is in your working tree. Build on it; do not redo it.`
                 : ctx.start?.kind === 'branch'
-                    ? `This session started from the local branch \`${ctx.start.branch}\`, not from any earlier session's work${ctx.start.note ? ` (${ctx.start.note})` : ''}.`
+                    ? `This session started from the ${ctx.start.remote ? 'remote branch' : 'local branch'} \`${ctx.start.branch}\`${ctx.start.remote ? ' (the code on the server, fetched when the run was started)' : ''}, not from any earlier session's work${ctx.start.note ? ` (${ctx.start.note})` : ''}.`
                     : '';
     return [
         '## Version control',
@@ -1143,8 +1198,9 @@ export async function vcsPreflight(session, allSessions = async () => []) {
      */
     if (!session.vcsBaseCommit && settings.startFrom === 'previous-session') {
         const planned = await sessionStart(session, repoDir, state.head, allSessions, { dry: true });
+        // About where it starts only: another choice in the start window gets past it (see `RunVcsGroup.startChoiceCanFix`).
         if ('problem' in planned)
-            return { ok: false, repoDir, branch: state.branch ?? undefined, problem: planned.problem };
+            return { ok: false, repoDir, branch: state.branch ?? undefined, problem: planned.problem, startProblem: true };
     }
     return { ok: true, repoDir, branch: state.branch ?? undefined };
 }