copilot-operator 0.1.22 → 0.1.25

package/dist/src/api/operator.controller.js

@@ -498,11 +498,11 @@ let OperatorController = class OperatorController {
     }
     /** "Prepare the folder from the remote main branch": what it would do (fetches, changes nothing else). */
     repoPreparePreview(body) {
-        return this.ops.preparePreview(body?.dir ?? '').catch(fail);
+        return this.ops.preparePreview(body?.dir ?? '', body?.fetch !== false).catch(fail);
     }
     /** …and doing it, if the folder is still what the preview showed. */
     repoPrepare(body) {
-        return this.ops.prepareProject(body?.dir ?? '', body?.fingerprint ?? '').catch(fail);
+        return this.ops.prepareProject(body?.dir ?? '', body?.fingerprint ?? '', { savedBranch: body?.savedBranch, savedMainBranch: body?.savedMainBranch }).catch(fail);
     }
     repo(dir) {
         const problem = this.ops.repoProblem(dir ?? '');

package/dist/src/api/operator.service.js

@@ -35,8 +35,8 @@ function sameFolder(a, b) {
 }
 import { importPlan, plannedSessionSignature, taskSignature } from '../plan/importPlan.js';
 import { readInterruption } from '../session/interruption.js';
-import { branchAt, commitInterrupted, repoDirOf, vcsPreflight, restorePoint, restorePreview, restoreToBase, sessionBranches, sessionBranchName } from '../vcs/taskVcs.js';
-import { branchExists, changedFilesBetween, fileAt, freeBranchName, gitAvailable, localBranches, plannedBranchName, repoUnusableReason } from '../vcs/git.js';
+import { branchAt, commitInterrupted, repoDirOf, trackedRepoOf, vcsPreflight, restorePoint, restorePreview, restoreToBase, sessionBranches, sessionBranchName } from '../vcs/taskVcs.js';
+import { branchExists, branchNameFrom, changedFilesBetween, fileAt, freeBranchName, git, gitAvailable, localBranches, plannedBranchName, repoUnusableReason } from '../vcs/git.js';
 import { makeAuthorizer } from '../exec/authorizer.js';
 import { pickFolder } from './folderPicker.js';
 import { findEdgeUsingProfile } from '../transport/profileLock.js';
@@ -46,10 +46,16 @@ import { createTransport } from '../transport/chatTransport.js';
 import { composeHandoff } from '../session/handoff.js';
 import { planSync } from '../vcs/syncCommand.js';
 import { planPrepare, prepareFromRemote } from '../vcs/prepareFromRemote.js';
-import { appendRunLog } from '../session/runLog.js';
+import { askpassProgram } from '../vcs/remoteAuth.js';
+import { appendRunLog, appendSessionLog } from '../session/runLog.js';
+import { workingDirFor, isWorkingDirProblem } from '../exec/workDir.js';
+import { contractConflicts } from '../orchestrator/contract.js';
+import { checkRefusalForOperator, lineRefusal } from '../orchestrator/taskRunner.js';
+import { preferredShell } from '../exec/shells.js';
+import { sessionRoots } from '../exec/confinement.js';
 import { dirtyPolicy, takeSnapshot } from '../vcs/snapshot.js';
 import { runVcsPreflight, runVcsPrepare } from '../vcs/runPreflight.js';
-import { normalisePatterns } from '../vcs/inputs.js';
+import { inputSettings, normalisePatterns } from '../vcs/inputs.js';
 import { coveredByArtifacts } from '../vcs/artifacts.js';
 import { botVersion } from '../config/version.js';
 import { computeMetrics } from '../session/metrics.js';
@@ -496,11 +502,27 @@ let OperatorService = class OperatorService {
      */
     async updateTask(sessionId, taskId, patch) {
         await this.init();
-        return await this.store.updateTask(sessionId, taskId, (t) => {
+        let before;
+        const task = await this.store.updateTask(sessionId, taskId, (t) => {
             if (t.status !== 'queued')
                 throw new Error('Only a queued task can be edited.');
+            before = structuredClone(t);
             applyTaskPatch(t, patch);
         });
+        /*
+         * On record with the operator's other actions: a check or the prompt changed after the import is a
+         * different contract from the plan's, and the export showed only the new one (live run 2026-10-04).
+         */
+        const changed = Object.keys(patch).filter((k) => JSON.stringify(before?.[k]) !== JSON.stringify(task[k]));
+        if (changed.length > 0) {
+            const cfg = await this.settings.load();
+            await appendSessionLog(cfg.resolved.runsDir, sessionId, {
+                type: 'task-edited',
+                message: `"${task.title}" edited while queued: ${changed.join(', ')} changed`,
+                data: { taskId, changed, before: Object.fromEntries(changed.map((k) => [k, before?.[k] ?? null])) },
+            }).catch(() => undefined);
+        }
+        return task;
     }
     async deleteTask(sessionId, taskId) {
         await this.init();
@@ -516,7 +538,16 @@ let OperatorService = class OperatorService {
     /** "Continue" on a task that stopped before it finished — a limit from the settings, the bot stopping, the operator: same chat, same branch, fresh count. */
     async continueTask(sessionId, taskId) {
         await this.init();
-        const task = await this.store.continueTask(sessionId, taskId);
+        /*
+         * An attempt the operator stopped: which of its last steps ran, and what they printed, read from its
+         * run folder, so "Continue" can tell the chat. Without it the chat was told only that it had been
+         * stopped, and ran its inspection steps again (live run 2026-10-03).
+         */
+        const before = (await this.store.getSession(sessionId))?.tasks.find((t) => t.id === taskId);
+        const cfg = await this.settings.load();
+        const stoppedAt = before?.status === 'aborted' && !before.interruption && before.runId ? await readInterruption(join(cfg.resolved.runsDir, before.runId)).catch(() => null) : null;
+        const task = await this.store.continueTask(sessionId, taskId, stoppedAt);
+        await appendSessionLog(cfg.resolved.runsDir, sessionId, { type: 'continue', message: `"${task.title}" queued to continue as attempt ${task.attempt ?? 1}`, data: { taskId, attempt: task.attempt } }).catch(() => undefined);
         this.bus.publish({
             sessionId,
             taskId,
@@ -537,7 +568,21 @@ let OperatorService = class OperatorService {
         await this.init();
         const before = (await this.store.getSession(sessionId))?.tasks.find((t) => t.id === taskId);
         const buildsOn = opts.buildOnFinished && before?.status === 'done' ? { fromAttempt: before.attempt ?? 1 } : undefined;
+        /*
+         * A new prompt is a new change: the plan's commit subject was written for the old one, and two
+         * different commits went out under it (live run 2026-10-03). Dropped unless the edit names one.
+         */
+        // A correction added to the old prompt is not a new change, and keeps the subject (live run 2026-10-04).
+        const appended = !!before && !!patch.prompt && patch.prompt.trim().startsWith(before.prompt.trim().split('\n### Expected result')[0].trim());
+        if (patch.prompt?.trim() && before && patch.prompt.trim() !== before.prompt.trim() && !appended && before.vcsPlan?.commitMessage && !patch.vcsPlan?.commitMessage) {
+            patch = { ...patch, vcsPlan: { ...before.vcsPlan, ...(patch.vcsPlan ?? {}), commitMessage: undefined } };
+        }
         const task = await this.store.rerunTask(sessionId, taskId, patch, undefined, buildsOn);
+        {
+            const cfg = await this.settings.load();
+            const changed = Object.keys(patch).filter((k) => patch[k] !== undefined);
+            await appendSessionLog(cfg.resolved.runsDir, sessionId, { type: 'rerun', message: `"${task.title}" queued again as attempt ${task.attempt ?? 1}${buildsOn ? `, building on attempt ${buildsOn.fromAttempt}` : ''}${changed.length > 0 ? `, with ${changed.join(', ')} changed` : ''}`, data: { taskId, attempt: task.attempt, changed, ...(buildsOn ? { buildsOn } : {}) } }).catch(() => undefined);
+        }
         this.bus.publish({
             sessionId,
             taskId,
@@ -1013,9 +1058,11 @@ let OperatorService = class OperatorService {
             sessionId,
             type: 'upload-notice',
             level: 'info',
-            message: "every report of this run — each step's terminal output, the check results, the reviewer's transcripts — and any " +
-                "mirrored project files are uploaded into the Copilot chat and stored in the signed-in account's OneDrive and " +
-                'Copilot history, inside the tenant; secret-shaped strings are redacted first',
+            message: 
+            // Project files are no longer mirrored to the chat (removed in 0.1.14): only the reports go (live run 2026-10-03).
+            "every report of this run — each step's terminal output, the check results, the reviewer's transcripts — is " +
+                "uploaded into the Copilot chat and stored in the signed-in account's OneDrive and Copilot history, inside the " +
+                'tenant; secret-shaped strings are redacted first',
         });
         const done = runSession(sessionId, {
             cfg: { ...cfg, execution: { ...cfg.execution, mode } },
@@ -1035,10 +1082,32 @@ let OperatorService = class OperatorService {
             transport,
             runGroup,
             onlyTasks,
-            vcsGate: (s) => this.sessionVcsGate(s, onlyTasks),
+            vcsGate: async (s) => {
+                const refused = await this.sessionVcsGate(s, onlyTasks);
+                // In the run's own log, where the export finds it: it was only in the live events (live run 2026-10-04).
+                if (refused && runGroup) {
+                    await appendRunLog(cfg.resolved.runsDir, runGroup.id, [
+                        { at: new Date().toISOString(), type: 'run-preflight-refused', message: `refused at its turn: ${refused}`, data: { sessions: [s.id], atTurn: true } },
+                    ]).catch(() => undefined);
+                }
+                return refused;
+            },
             ...(transport || !runGroup ? {} : { beforeBrowser: () => this.browserRequested(runGroup.id, [sessionId]) }),
+            // The page is the source of the model names: Settings and the saved list follow it (see `ModelHooks`).
+            models: {
+                renamedDefault: async (which, from, to) => {
+                    const now = (await this.settings.load()).copilot;
+                    if (which === 'model' && (now.defaultModel ?? '').trim() === from)
+                        await this.setDefaultModel(to);
+                    if (which === 'review' && (now.defaultReviewModel ?? '').trim() === from)
+                        await this.setDefaultReviewModel(to);
+                },
+                seen: async (options, current) => {
+                    await this.store.saveModels({ options, current: current ?? undefined, readAt: new Date().toISOString() });
+                },
+            },
         })
-            .then(async (outcome) => ({ ...(await this.tally(sessionId, queuedIds)), paused: outcome.paused, ...(outcome.refused ? { error: outcome.refused } : {}) }))
+            .then(async (outcome) => ({ ...(await this.tally(sessionId, queuedIds)), paused: outcome.paused, ...(outcome.refused ? { refused: outcome.refused } : {}) }))
             .catch(async (e) => {
             this.bus.publish({ sessionId, type: 'run-failed', level: 'error', message: e.message });
             return { ...(await this.tally(sessionId, queuedIds)), error: e.message };
@@ -1073,6 +1142,10 @@ let OperatorService = class OperatorService {
                 continue;
             }
             tally.ran += 1;
+            if (task.status === 'aborted') {
+                tally.stopped = (tally.stopped ?? 0) + 1;
+                continue;
+            }
             if (task.status !== 'done') {
                 tally.failed += 1;
                 tally.failedTitles.push(task.title);
@@ -1095,7 +1168,8 @@ let OperatorService = class OperatorService {
         await this.store.updateSession(sessionId, (s) => {
             s.status = 'stopping';
         });
-        this.bus.publish({ sessionId, type: 'stop-requested', level: 'warn', message: 'stopping after the current step' });
+        // The running step is cut off, not waited for: said as it is (live run 2026-10-03).
+        this.bus.publish({ sessionId, type: 'stop-requested', level: 'warn', message: 'stopping now: nothing more is sent, and a step still running is cut off' });
         return { stopping: true };
     }
     // --- running several sessions in turn -------------------------------------------------
@@ -1485,7 +1559,12 @@ let OperatorService = class OperatorService {
                 const tally = await begun.done;
                 entry.ran = tally.ran;
                 entry.failed = tally.failed;
-                if (tally.error) {
+                if (tally.refused) {
+                    // Refused at its turn, before anything of it ran: not a failure of its tasks, which stay queued.
+                    entry.state = 'skipped';
+                    entry.reason = tally.refused;
+                }
+                else if (tally.error) {
                     entry.state = 'failed';
                     entry.reason = tally.error;
                 }
@@ -1493,6 +1572,12 @@ let OperatorService = class OperatorService {
                     entry.state = 'failed';
                     entry.reason = `${tally.failed} task(s) did not finish: ${tally.failedTitles.join(', ')}`;
                 }
+                else if ((tally.stopped ?? 0) > 0) {
+                    entry.state = 'stopped';
+                    // The task cut short is counted as what it is: "after 0 task(s)" beside ran 1 read as if nothing ran (live run 2026-10-04).
+                    const finished = tally.ran - (tally.stopped ?? 0);
+                    entry.reason = `stopped by the operator: ${tally.stopped} task(s) cut short${finished > 0 ? `, after ${finished} that finished` : ''}; ${tally.leftQueued} still queued`;
+                }
                 else if (tally.paused) {
                     entry.state = 'stopped';
                     entry.reason = `paused after ${tally.ran} task(s); ${tally.leftQueued} still queued`;
@@ -1507,11 +1592,12 @@ let OperatorService = class OperatorService {
                 this.bus.publish({
                     sessionId: entry.sessionId,
                     type: 'batch-session-finished',
-                    level: entry.state === 'failed' ? 'warn' : 'info',
-                    message: `this session ended ${entry.state} inside the batch`,
+                    level: entry.state === 'failed' || tally.refused ? 'warn' : 'info',
+                    message: tally.refused ? 'this session was refused at its turn inside the batch; its tasks stay queued' : `this session ended ${entry.state} inside the batch`,
                     data: { batchId: batch.id, ran: entry.ran, failed: entry.failed },
                 });
-                if (entry.state === 'failed' && batch.onFailure === 'stop') {
+                // A session refused at its turn breaks a chain as a failed one does.
+                if ((entry.state === 'failed' || tally.refused) && batch.onFailure === 'stop') {
                     batch.stopping = true;
                     this.bus.publish({
                         sessionId: entry.sessionId,
@@ -1638,8 +1724,13 @@ let OperatorService = class OperatorService {
          */
         const repoIssues = [];
         check.plan.sessions.forEach((session, i) => {
-            if (session.vcs?.enabled === false)
+            if (session.vcs?.enabled === false) {
+                // Without version control the project folder must still be there (live run 2026-10-03: not looked at).
+                const folder = (session.projectDir ?? '').trim();
+                if (folder && !existsSync(folder))
+                    repoIssues.push({ path: `sessions[${i}].projectDir`, message: `${folder} does not exist. Name the session's project folder, or create it.` });
                 return;
+            }
             const dir = plannedRepoDir(session);
             const reason = repoUnusableReason(dir);
             if (reason)
@@ -1685,7 +1776,30 @@ let OperatorService = class OperatorService {
         }
         if (repoIssues.length > 0)
             return { ok: false, issues: repoIssues, warnings: check.warnings, duplicates: [] };
-        return { ...check, duplicates: await this.findDuplicates(check.plan) };
+        /*
+         * A check the runner refuses for its own command line under these Settings: every start of its task
+         * is refused for it, so it is said here, at the check, and not only at the start (live run 2026-10-04:
+         * "check" said ok and the first start was refused). A warning, since the Settings may be changed.
+         */
+        const cfg = await this.settings.load();
+        const shell = preferredShell(cfg.execution.defaultShell);
+        const others = [cfg.project.rootDir, ...cfg.project.others.map((o) => o.rootDir)];
+        const lineWarnings = [];
+        check.plan.sessions.forEach((session, i) => {
+            const cwd = (session.vcs?.enabled === false ? '' : plannedRepoDir(session)) || (session.projectDir ?? '').trim() || cfg.resolved.cwd;
+            const roots = sessionRoots(cwd, others);
+            session.tasks.forEach((task, j) => {
+                for (const c of task.checks ?? []) {
+                    const run = c.run?.trim();
+                    if (!run)
+                        continue;
+                    const why = lineRefusal(run, c.shell ?? shell, c.cwd ? resolve(cwd, c.cwd) : cwd, cfg.execution, roots);
+                    if (why)
+                        lineWarnings.push(`sessions[${i}].tasks[${j}] ("${task.title}"): the check "${c.name}" is refused by the runner for its own command line, so the task cannot start until it is changed: ${checkRefusalForOperator(why)}.`);
+                }
+            });
+        });
+        return { ...check, warnings: [...check.warnings, ...lineWarnings], duplicates: await this.findDuplicates(check.plan) };
     }
     /**
      * Sessions the store already holds that this plan would create again, task for task.
@@ -1918,7 +2032,8 @@ let OperatorService = class OperatorService {
             const ids = g.sessions.map((x) => x.id);
             const first = ids[0] ? await this.store.getSession(ids[0]) : null;
             const start = first?.vcsStart;
-            const untouched = !!first && !first.tasks.some((t) => t.startedAt);
+            // Said once, in the first run after the snapshot: a re-run clears `startedAt`, so earlier attempts count too.
+            const untouched = !!first && !first.tasks.some((t) => t.startedAt || (t.attempts ?? []).some((a) => a.startedAt));
             if (start?.kind === 'snapshot' && start.snapshot?.approved && untouched) {
                 note('baseline-created', `starting snapshot ${start.commit.slice(0, 8)} on ${start.branch ?? '?'}, approved ${start.snapshot.approvedAt ?? ''}${start.snapshot.onBase ? ` on top of "${start.snapshot.fromBranch}"` : ''}`, {
                     repoDir: g.repoDir,
@@ -1935,7 +2050,9 @@ let OperatorService = class OperatorService {
                 branch: g.branch,
                 head: g.head,
                 ...(g.baseBranch ? { baseBranch: g.baseBranch, baseHead: g.baseHead } : {}),
-                sessions: g.sessions.map((x) => ({ id: x.id, name: x.name, startFrom: x.startFrom, role: x.role })),
+                ...(g.workBranch ? { workBranch: g.workBranch } : {}),
+                ...(g.carry ? { carry: g.carry } : {}),
+                sessions: g.sessions.map((x) => ({ id: x.id, name: x.name, startFrom: x.startFrom, role: x.role, started: x.started })),
                 inputPatterns: g.inputPatterns,
                 inputs: g.inputs.map((e) => e.path),
                 unrelated: g.unrelated.map((u) => u.path),
@@ -1943,15 +2060,43 @@ let OperatorService = class OperatorService {
             }, ids, g.ready ? 'info' : 'warn');
             const fixes = g.actions.filter((a) => a.available && a.id !== 'review-inputs').map((a) => a.id);
             if (!g.ready && fixes.length > 0) {
-                note('snapshot-approval-required', `${g.repoDir}: nothing runs until one of these is pressed on the run screen: ${fixes.join(', ')}`, { repoDir: g.repoDir, actions: fixes }, ids, 'warn');
+                const label = {
+                    'snapshot-on-base': `Create starting snapshot on ${g.baseBranch ?? 'the base branch'}`,
+                    'snapshot-here': `Create starting snapshot on ${g.branch ?? 'HEAD'}`,
+                    'use-current-branch': `Use the current branch instead of ${g.baseBranch ?? 'the base branch'}`,
+                    'allow-snapshot': 'Take uncommitted changes as a starting snapshot',
+                };
+                note('snapshot-approval-required', `${g.repoDir}: nothing runs until one of these is pressed under "Prepare version control for this run" on the Sessions page: ${fixes.map((f) => `"${label[f] ?? f}"`).join(', ')}`, { repoDir: g.repoDir, actions: fixes }, ids, 'warn');
             }
         }
         const open = groups.filter((g) => !g.ready);
-        const reason = open.length === 0
-            ? null
-            : 'Version control is not ready for this run, so nothing was opened or sent. ' +
-                open.map((g) => `${g.repoDir}: ${g.problem ?? 'it needs your approval'}`).join(' ') +
-                ' Fix it under "Prepare version control for this run" on the Sessions page.';
+        // A task that contradicts itself, said here too: found at its start, it had already cut a branch and used an attempt.
+        const contradictions = [];
+        const reposBefore = new Set();
+        for (const id of sessionIds) {
+            const s = await this.store.getSession(id);
+            const repo = s ? trackedRepoOf(s) : '';
+            const afterOthers = !!repo && reposBefore.has(resolve(repo).toLowerCase());
+            if (repo)
+                reposBefore.add(resolve(repo).toLowerCase());
+            const said = s ? await this.contractRefusal(s, onlyTasks, afterOthers) : null;
+            if (said) {
+                contradictions.push(said);
+                // Said once here as what it is; the refusal below names it again with everything else in the way.
+                note('task-contract-refused', said, { session: id, contract: true }, [id], 'warn');
+            }
+        }
+        const parts = [
+            ...(open.length > 0
+                ? [
+                    'Version control is not ready for this run, so nothing was opened or sent. ' +
+                        open.map((g) => `${g.repoDir}: ${g.problem ?? 'it needs your approval'}`).join(' ') +
+                        ' Fix it under "Prepare version control for this run" on the Sessions page.',
+                ]
+                : []),
+            ...(contradictions.length > 0 ? [`${open.length > 0 ? '' : 'Nothing was opened or sent. '}${contradictions.join(' ')}`] : []),
+        ];
+        const reason = parts.length === 0 ? null : parts.join(' ');
         if (reason)
             note('run-preflight-refused', reason, { repositories: open.map((g) => g.repoDir) }, sessionIds, 'warn');
         else
@@ -1959,11 +2104,98 @@ let OperatorService = class OperatorService {
         await appendRunLog(cfg.resolved.runsDir, runId, log).catch(() => undefined);
         return reason;
     }
+    /**
+     * Why the session's next task cannot start because it contradicts itself — read-only and scoped, or
+     * a file check that needs a change the task may not make — or null. The part of the contract that
+     * depends on the branch the runner will choose is checked at the task's start, once that is known.
+     */
+    async contractRefusal(session, onlyTasks, afterOthers = false) {
+        const next = queuedToRun(session, onlyTasks)[0];
+        if (!next)
+            return null;
+        const cfg = await this.settings.load();
+        const work = workingDirFor(session, cfg.resolved.cwd);
+        if (isWorkingDirProblem(work))
+            return null;
+        /*
+         * The branch the task will be on, where that is known before the run: so a check that expects another
+         * branch is refused here too, not after the browser opened and a branch was cut (live run 2026-10-04).
+         */
+        const prefix = session.vcs?.branchPrefix || 'cop/';
+        const attempt = next.attempt ?? 1;
+        const branch = !session.vcs?.enabled
+            ? undefined
+            : session.vcs.startFrom === 'existing-branch'
+                ? session.vcs.existingBranch?.trim() || undefined
+                : session.vcs.branchMode === 'per-session'
+                    ? sessionBranchName(session)
+                    : next.vcsPlan?.branch?.trim()
+                        ? plannedBranchName(next.vcsPlan.branch, prefix, attempt)
+                        : branchNameFrom([session.name, next.title, attempt > 1 ? `a${attempt}` : undefined], prefix);
+        const files = await this.contractTree(session, afterOthers).catch(() => 'unknown');
+        // Input files are carried onto a first start from their last capture: not judged before it (see `contract.ts`).
+        const carried = !session.vcsBaseCommit ? inputSettings(session.vcs)?.patterns : undefined;
+        const conflicts = await contractConflicts(next, work.cwd, repoDirOf(session) || work.cwd, { branch, files, carried }).catch(() => []);
+        // A plan check the runner refuses for its own command line can never run: the task could never pass.
+        const roots = sessionRoots(work.cwd, [cfg.project.rootDir, ...cfg.project.others.map((o) => o.rootDir)]);
+        const shell = preferredShell(cfg.execution.defaultShell);
+        for (const c of next.checks ?? []) {
+            const run = c.run?.trim();
+            if (!run)
+                continue;
+            const why = lineRefusal(run, c.shell ?? shell, c.cwd ? resolve(work.cwd, c.cwd) : work.cwd, cfg.execution, roots);
+            if (why)
+                conflicts.push(`The check "${c.name}" is refused by the runner for its own command line, so it can never run and the task could never pass: ${checkRefusalForOperator(why)}.`);
+        }
+        return conflicts.length === 0
+            ? null
+            : `The task "${next.title}" of "${session.name}" contradicts itself, so it was not started and stays queued: ${conflicts.join(' ')} Change the prompt, the checks, the scope or read-only on the session's page, and start again.`;
+    }
+    /**
+     * Where the next task's file checks can be judged before the run: see `ContractTree`. The folder holds
+     * the task's tree only when nothing is still to happen to it first — no update from a remote, no
+     * earlier session of the batch in the same repository (`afterOthers`) — and otherwise the commit the
+     * task starts from is read where it is already known, or the checks wait for the task's start.
+     */
+    async contractTree(session, afterOthers) {
+        const repo = trackedRepoOf(session);
+        if (!repo)
+            return 'tree';
+        if (session.vcsBaseCommit) {
+            if (session.vcs?.branchMode !== 'per-session')
+                return { ref: session.vcsBaseCommit };
+            // A started session goes on from where its last task left its branch: the folder, when still on it.
+            const last = [...session.tasks].reverse().find((t) => t.vcs?.branch)?.vcs?.branch;
+            const now = await git(repo, ['branch', '--show-current']);
+            return last && now.ok && now.stdout === last ? 'tree' : 'unknown';
+        }
+        if (session.vcsStart?.commit)
+            return { ref: session.vcsStart.commit };
+        const how = session.vcs?.startFrom ?? 'head';
+        if (how === 'head')
+            return afterOthers ? 'unknown' : 'tree';
+        if (how === 'previous-session')
+            return 'unknown';
+        const branch = how === 'existing-branch' ? session.vcs?.existingBranch?.trim() : session.vcs?.baseBranch?.trim() || 'main';
+        if (!branch)
+            return 'unknown';
+        // Brought up to its remote first: what that brings is known only then.
+        if (session.vcs?.updateFromRemote !== false) {
+            const remotes = await git(repo, ['remote']);
+            if (!remotes.ok || remotes.stdout.trim() !== '')
+                return 'unknown';
+        }
+        const tip = await git(repo, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}^{commit}`]);
+        return tip.ok && tip.stdout ? { ref: tip.stdout } : 'unknown';
+    }
     /**
      * The same rule for one session that has not started, when its turn comes: see `RunDeps.vcsGate`.
      * A session that has started is past its first preparation; its tasks are prepared as they come.
      */
     async sessionVcsGate(session, onlyTasks) {
+        const contradiction = await this.contractRefusal(session, onlyTasks);
+        if (contradiction)
+            return contradiction;
         if (!session.vcs?.enabled || session.vcsBaseCommit)
             return null;
         if (queuedToRun(session, onlyTasks).length === 0)
@@ -1971,7 +2203,9 @@ let OperatorService = class OperatorService {
         const [group] = await runVcsPreflight([session], () => this.store.listSessions());
         if (!group || group.ready)
             return null;
-        return `Version control is not ready for "${session.name}", so it did not start and its tasks stay queued: ${group.problem ?? 'it needs your approval'} Fix it under "Prepare version control for this run" on the Sessions page.`;
+        // The panel is named only where it has a fix to offer: for a chain waiting on its predecessor the remedy is that one's Continue (live run 2026-10-04).
+        const panel = group.actions.some((a) => a.available && a.id !== 'review-inputs');
+        return `Version control is not ready for "${session.name}", so it did not start and its tasks stay queued: ${group.problem ?? 'it needs your approval'}${panel ? ' Fix it under "Prepare version control for this run" on the Sessions page.' : ''}`;
     }
     /** Recorded in the run's log just before the browser is opened for it: see `runPreflight`. */
     async browserRequested(runId, sessionIds) {
@@ -1996,6 +2230,15 @@ let OperatorService = class OperatorService {
                 sessions.push(s);
         }
         const done = await runVcsPrepare(sessions, repoDir, action, choices && typeof choices === 'object' ? choices : {}, this.bus, async (id, mutate) => void (await this.store.updateSession(id, mutate)), () => this.store.listSessions());
+        // Kept on every session the action was for, with what it did: see `appendSessionLog`.
+        if (done.ok && action !== 'review-inputs') {
+            const cfg = await this.settings.load();
+            for (const s of sessions.filter((x) => normaliseDir(repoDirOf(x)) === normaliseDir(repoDir))) {
+                const message = `run screen: "${action}" in ${repoDir}: ${done.result}`;
+                await appendSessionLog(cfg.resolved.runsDir, s.id, { type: 'run-screen-action', message, data: { action, repoDir, before: { startFrom: s.vcs?.startFrom, baseBranch: s.vcs?.baseBranch } } }).catch(() => undefined);
+                this.bus.publish({ sessionId: s.id, type: 'run-screen-action', level: 'info', message, data: { action, repoDir } });
+            }
+        }
         return done.ok ? { ok: true, result: done.result } : { ok: false, problem: done.problem };
     }
     /** Whether version control can do its job in this session, asked before a run. */
@@ -2061,7 +2304,30 @@ let OperatorService = class OperatorService {
         const refused = await this.restoreRefusal(session);
         if (refused)
             return { ok: false, problem: refused };
-        return await restoreToBase(session, task, this.bus);
+        const done = await restoreToBase(session, task, this.bus);
+        // On record with the operator's other actions: it made a branch and moved the checkout (live run 2026-10-04).
+        if (done.ok) {
+            const cfg = await this.settings.load();
+            await appendSessionLog(cfg.resolved.runsDir, session.id, { type: 'restore', message: `restored the code as it was before "${task.title}" on ${done.branch} at ${(done.commit ?? '').slice(0, 8)}`, data: { taskId, branch: done.branch, commit: done.commit, leftBehind: done.leftBehind, keptOn: done.keptOn } }).catch(() => undefined);
+        }
+        /*
+         * In per-session mode the session's one branch is where its next task goes, so a Restore moves the
+         * session onto the restore branch, as "Run again from here" does. Without that the next run checked
+         * the old session branch out again and the restore did not hold (live run 2026-10-03).
+         */
+        if (done.ok && done.branch && session.vcs?.branchMode === 'per-session' && session.vcs.startFrom !== 'existing-branch') {
+            const left = sessionBranchName(session);
+            await this.store.updateSession(session.id, (s) => {
+                if (s.vcs) {
+                    s.vcs.branchName = done.branch;
+                    s.vcs.branchNameExact = true;
+                }
+            });
+            this.bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-session-branch', level: 'info',
+                message: `the session carries on from ${done.branch}, the code as it was before "${task.title}"; ${left} keeps the work that came after`,
+                data: { branch: done.branch, left } });
+        }
+        return done;
     }
     /**
      * Why the repository of this session cannot be moved to another branch now, or null when it can.
@@ -2219,6 +2485,16 @@ let OperatorService = class OperatorService {
                 keptOn: preview.keptOn,
             });
         }
+        /*
+         * The plan is "ok" only when the restart it describes can happen: a refused restore refuses the
+         * restart, as `restartFrom` does and the dialog says, so a caller reading only `ok` is not told
+         * otherwise (live run 2026-10-04: ok true beside its only restore refused).
+         */
+        const refusedRestores = plan.restores.filter((r) => !r.ok);
+        if (plan.ok && refusedRestores.length > 0) {
+            plan.ok = false;
+            plan.problem = refusedRestores.map((r) => `${r.repoDir}: ${r.problem ?? 'the restore cannot be made'}`).join(' ');
+        }
         return plan;
     }
     /**
@@ -2239,7 +2515,9 @@ let OperatorService = class OperatorService {
         if (this.batch?.running)
             return { ...idle, reason: 'A run is in progress. Stop it first.' };
         const plan = await this.restartPlan(sessionId, taskId);
-        if (!plan.ok)
+        // A refused restore stops the restart only when the restore is asked for: `restore: false` queues without one.
+        const onlyRestoreRefused = plan.tasks.length > 0 && plan.restores.some((r) => !r.ok);
+        if (!plan.ok && !(opts.restore === false && onlyRestoreRefused))
             return { ...idle, reason: plan.problem };
         if (plan.sessions.some((s) => this.running.has(s.id))) {
             return { ...idle, reason: 'One of these sessions is running on its own. Stop it first.' };
@@ -2354,8 +2632,9 @@ let OperatorService = class OperatorService {
             taskId,
             type: 'run-restarted',
             level: 'info',
-            message: `starting again from "${plan.from.title}": ${plan.tasks.length} task(s) in ${plan.sessions.length} session(s)` +
-                (restored.length > 0 ? `, after taking ${restored.length} repository(ies) back` : ''),
+            message: `${opts.start === false ? 'prepared to start again' : 'starting again'} from "${plan.from.title}": ${plan.tasks.length} task(s) in ${plan.sessions.length} session(s)` +
+                (restored.length > 0 ? `, after taking ${restored.length} repository(ies) back` : '') +
+                (opts.start === false ? '; press a run button to start' : ''),
             data: { requeued, restored },
         });
         if (opts.start === false)
@@ -2489,16 +2768,17 @@ let OperatorService = class OperatorService {
      * "Prepare the folder from the remote main branch", first half: fetches and says what would be
      * kept where and what the folder would be. See `vcs/prepareFromRemote.ts`.
      */
-    async preparePreview(dir) {
+    async preparePreview(dir, fetch = true) {
         await this.init();
         await this.knownProjectFolder(dir, 'it is not prepared from here');
-        return await planPrepare(resolve(dir.trim()), { fetch: true });
+        // The operator pressed the button and is looking: the remote may ask for a password through Git's own window.
+        return await planPrepare(resolve(dir.trim()), { fetch, askpass: fetch ? await askpassProgram() : null });
     }
     /**
      * The second half: does it, if the folder is still what the preview showed. Refused while anything
      * runs, or is being started, in that folder or one around it: it moves the checkout.
      */
-    async prepareProject(dir, fingerprint) {
+    async prepareProject(dir, fingerprint, names = {}) {
         await this.init();
         await this.knownProjectFolder(dir, 'it is not prepared from here');
         if (this.batch?.running)
@@ -2508,7 +2788,18 @@ let OperatorService = class OperatorService {
         const other = await this.runningIn(dir);
         if (other)
             return { ok: false, problem: `Session "${other.name}" is running in this folder. Stop it before preparing the folder; nothing was changed.` };
-        return await prepareFromRemote(resolve(dir.trim()), String(fingerprint ?? ''));
+        const done = await prepareFromRemote(resolve(dir.trim()), String(fingerprint ?? ''), { names });
+        // Kept on every session working in that folder: it moved the checkout and made saved branches.
+        if (done.ok) {
+            const cfg = await this.settings.load();
+            const here = normaliseDir(dir);
+            for (const s of (await this.store.listSessions()).filter((x) => normaliseDir(repoDirOf(x)) === here)) {
+                const message = `the folder was prepared from ${done.target}: ${done.result}`;
+                await appendSessionLog(cfg.resolved.runsDir, s.id, { type: 'folder-prepared', message, data: { target: done.target, commit: done.commit, branch: done.branch, saved: done.saved, removedFromFolder: done.removedFromFolder } }).catch(() => undefined);
+                this.bus.publish({ sessionId: s.id, type: 'folder-prepared', level: 'info', message, data: { target: done.target, commit: done.commit, saved: done.saved } });
+            }
+        }
+        return done;
     }
     // --- the project being worked on ---------------------------------------------------------
     /**
@@ -2820,6 +3111,10 @@ let OperatorService = class OperatorService {
                             reason: a.reason,
                             runId: a.runId,
                             branch: a.vcs?.branch,
+                            // Why the runner stopped this attempt, whether it was a fresh-chat retry, and its commit (live run 2026-10-03).
+                            stopCode: a.stopCode,
+                            freshRetry: a.freshRetry,
+                            commit: a.vcs?.commit,
                             changedFiles: a.vcs?.commit && a.vcs.baseCommit ? (a.vcs.files?.length ?? 0) : undefined,
                         };
                     }),