copilot-operator 0.1.38 → 0.1.40

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

@@ -29,6 +29,17 @@ import { suggestRunName } from '../session/runName.js';
 import { buildStory } from '../session/story.js';
 import { checkPlan } from '../plan/schema.js';
 import { planBrief } from '../plan/brief.js';
+/**
+ * A settings file or a policy lock that cannot be used: answered 409 with its own message on every route
+ * (see `server.ts`), so a start passes it on rather than answering it as a start that did not happen.
+ */
+function unusableConfig(e) {
+    return e instanceof SettingsUnusableError || e instanceof PolicyLockUnusableError;
+}
+/** `20261013-102231` from an ISO time, in this machine's time as the file's contents are, for a file name. */
+function fileStamp(iso) {
+    return localTime(iso).replace(/[-:]/g, '').replace(/\..*$/, '').replace(' ', '-');
+}
 /** Windows paths: case and the slash direction do not make two folders. */
 function sameFolder(a, b) {
     const norm = (p) => p.trim().replace(/[\\/]+$/, '').replace(/\//g, '\\').toLowerCase();
@@ -36,8 +47,8 @@ function sameFolder(a, b) {
 }
 import { importPlan, plannedSessionSignature, taskSignature } from '../plan/importPlan.js';
 import { readInterruption } from '../session/interruption.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 { baseRefOf, branchAt, commitInterrupted, nextAttemptBranch, repoDirOf, trackedRepoOf, vcsPreflight, restorePoint, restorePreview, restoreToBase, sessionBranches, sessionBranchName } from '../vcs/taskVcs.js';
+import { branchExists, changedFilesBetween, commitsBetween, 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';
@@ -48,9 +59,13 @@ import { composeHandoff } from '../session/handoff.js';
 import { planSync } from '../vcs/syncCommand.js';
 import { planPrepare, prepareFromRemote } from '../vcs/prepareFromRemote.js';
 import { askpassProgram } from '../vcs/remoteAuth.js';
-import { appendRunLog, appendSessionLog } from '../session/runLog.js';
+import { appendRunLog, appendSessionLog, readRunLog } from '../session/runLog.js';
+import { applyStartChoice, fetchForStart, startOptions, withChoice } from '../vcs/startChoice.js';
+import { StartFailures, failureReport, refOf } from '../session/startFailure.js';
+import { formatTerminal, localTime, terminalLines, terminalLogFile } from '../log/terminal.js';
+import { redactSecrets } from '../exec/redaction.js';
 import { workingDirFor, isWorkingDirProblem } from '../exec/workDir.js';
-import { contractConflicts } from '../orchestrator/contract.js';
+import { contractConflictsWithFixes, contractFixPatch, describeContractChange } from '../orchestrator/contract.js';
 import { checkRefusalForOperator, lineRefusal } from '../orchestrator/taskRunner.js';
 import { preferredShell } from '../exec/shells.js';
 import { sessionRoots } from '../exec/confinement.js';
@@ -62,7 +77,10 @@ import { botVersion } from '../config/version.js';
 import { computeMetrics } from '../session/metrics.js';
 import { resolveDesktopDir, desktopIsSynced } from '../context/desktopDir.js';
 import { saveAndReveal } from './saveToDesktop.js';
-import { settingsOf } from './settings.js';
+import { settingsOf, SettingsUnusableError } from './settings.js';
+import { PolicyLockUnusableError } from '../config/lockedPolicy.js';
+/** Why a session set aside on the Sessions page does not run: one sentence for every start that refuses it. */
+const INACTIVE_REASON = 'the session is inactive; make it active on the Sessions page to run it';
 /**
  * Why the browser cannot be had now, said in terms of what was pressed. The sentences a start, a
  * batch and the model picker gave before there was one rule for all three are kept where they still
@@ -193,6 +211,8 @@ let OperatorService = class OperatorService {
     settings = settingsOf(this.layout);
     store = new SessionStore(this.dataDir, join(this.layout.promptsDir, 'level1.md'));
     bus = new EventBus();
+    /** Starts that did not get as far as a first task, for the page to show and offer as a file. */
+    startFailures = new StartFailures();
     running = new Map();
     waiting = new Map();
     /** The batch in progress, or the last one that finished. At most one ever exists. */
@@ -431,6 +451,17 @@ let OperatorService = class OperatorService {
                     merged.baseBranch = merged.baseBranch.trim();
                 if (merged.existingBranch !== undefined)
                     merged.existingBranch = merged.existingBranch.trim();
+                /*
+                 * The session page names local branches: a start or a branch changed there is a local one, and
+                 * the remote the start window chose it from last time no longer applies (see `baseRemote`).
+                 */
+                const pointMoved = (patch.vcs.startFrom !== undefined && patch.vcs.startFrom !== s.vcs?.startFrom) ||
+                    (patch.vcs.baseBranch !== undefined && patch.vcs.baseBranch.trim() !== (s.vcs?.baseBranch ?? '').trim()) ||
+                    (patch.vcs.existingBranch !== undefined && patch.vcs.existingBranch.trim() !== (s.vcs?.existingBranch ?? '').trim());
+                if (pointMoved && patch.vcs.baseRemote === undefined)
+                    delete merged.baseRemote;
+                if (merged.baseRemote !== undefined && !merged.baseRemote.trim())
+                    delete merged.baseRemote;
                 // Only the two known fields, and absent when it says what absent says: reject, asking first.
                 const dirty = dirtyPolicy(merged);
                 if (dirty.policy === 'reject')
@@ -477,6 +508,7 @@ let OperatorService = class OperatorService {
                 const startChanged = (merged.startFrom ?? 'head') !== (s.vcs?.startFrom ?? 'head') ||
                     (merged.baseBranch || 'main') !== (s.vcs?.baseBranch || 'main') ||
                     (merged.existingBranch ?? '') !== (s.vcs?.existingBranch ?? '') ||
+                    (merged.baseRemote ?? '') !== (s.vcs?.baseRemote ?? '') ||
                     (merged.updateFromRemote !== false) !== (s.vcs?.updateFromRemote !== false) ||
                     merged.repoDir.toLowerCase() !== (s.vcs?.repoDir ?? '').trim().toLowerCase();
                 if (startChanged) {
@@ -955,19 +987,47 @@ let OperatorService = class OperatorService {
      * Starts the session's queued tasks in the background. Returns immediately; progress
      * arrives on the event stream. One run at a time, of this session or any other.
      */
-    async start(sessionId, mode = 'confirm', name) {
+    async start(sessionId, mode = 'confirm', name, 
+    /** Where the session starts, as chosen in the start window: see `vcs/startChoice.ts`. Absent keeps its settings. */
+    starts) {
+        const pressedAt = new Date().toISOString();
         // One conversation at a time is not a policy, it is the browser profile: a second run
         // does not get a second browser, it gets an error about a closed one. Whatever has the
         // browser now — a batch, another session, a read of the models — the start is refused where
         // the reason can still be read, rather than three minutes later in a stack trace.
         const claim = this.claimBrowser({ kind: 'run', sessionId });
         if ('refused' in claim)
-            return { started: false, reason: claim.refused };
+            return await this.notStarted({ stage: 'refused', message: claim.refused, sessionIds: [sessionId], pressedAt });
+        let runId;
         try {
             // A run nobody named is named after what it is a run of, rather than left to show up in the
             // register as "Unnamed run" beside five others of the same description.
+            // Set aside on the Sessions page: said first, before the preflight judges a session that will not run.
+            if ((await this.store.getSession(sessionId))?.active === false) {
+                this.releaseBrowser(claim.holder);
+                return await this.notStarted({ stage: 'refused', message: INACTIVE_REASON, sessionIds: [sessionId], pressedAt });
+            }
             const chosenName = name?.trim() || (await this.suggestRunName([sessionId]));
             const runGroup = { id: newId('r-'), startedAt: new Date().toISOString(), sessions: 1, name: chosenName };
+            runId = runGroup.id;
+            /*
+             * What refuses this start whatever branch is chosen, asked before the choice moves anything: a local
+             * branch made or brought up to its remote, and the session's settings, stayed changed after a start
+             * refused for an unattended run this machine does not allow (review of 2026-10-13).
+             */
+            const before = await this.store.getSession(sessionId);
+            const earlyRefusal = !before ? 'no such session' : queuedToRun(before).length === 0 ? 'no queued tasks' : await this.unattendedRefusal(mode);
+            if (earlyRefusal) {
+                this.releaseBrowser(claim.holder);
+                // No run log for a session that does not exist: the id is the caller's, and may be anything.
+                return await this.notStarted({ stage: 'refused', message: earlyRefusal, sessionIds: [sessionId], pressedAt, ...(before ? { runId } : {}) });
+            }
+            // The branch the session starts from, as the start window chose it, before the preflight judges it.
+            const unusable = await this.applyStartChoices(runGroup.id, [sessionId], starts);
+            if (unusable) {
+                this.releaseBrowser(claim.holder);
+                return await this.notStarted({ stage: 'branch', message: unusable, sessionIds: [sessionId], pressedAt, runId });
+            }
             // A run of one is still a run, and it records the same thing a batch does, so that going
             // back and starting again from a task works the same whether one session was started or six.
             // Recorded by `beginRun` once the start is accepted, not here: see `recordOnSession`.
@@ -975,12 +1035,12 @@ let OperatorService = class OperatorService {
             const notReady = await this.runPreflight(runGroup.id, [sessionId]);
             if (notReady) {
                 this.releaseBrowser(claim.holder);
-                return { started: false, reason: notReady };
+                return await this.notStarted({ stage: 'preflight', message: notReady, sessionIds: [sessionId], pressedAt, runId });
             }
-            const begun = await this.beginRun(sessionId, mode, undefined, runGroup, undefined, { recordOnSession: true });
+            const begun = await this.beginRun(sessionId, mode, undefined, runGroup, undefined, { recordOnSession: true, pressedAt });
             if (!begun.started) {
                 this.releaseBrowser(claim.holder);
-                return { started: false, reason: begun.reason };
+                return await this.notStarted({ stage: 'refused', message: begun.reason ?? 'not started', sessionIds: [sessionId], pressedAt, runId });
             }
             // The window closes before the run's promise settles (see `runSession`), so the browser is
             // free again exactly when it is.
@@ -989,9 +1049,157 @@ let OperatorService = class OperatorService {
         }
         catch (e) {
             this.releaseBrowser(claim.holder);
-            throw e;
+            if (unusableConfig(e))
+                throw e;
+            // Said with the error itself, and on record with the console of those moments, rather than as a bare 500.
+            console.error('[start] the session could not be started:', e.stack ?? e.message);
+            return await this.notStarted({ stage: 'error', message: e.message, sessionIds: [sessionId], pressedAt, runId });
         }
     }
+    /**
+     * A start that did not happen, put on record (`session/startFailure.ts`) and in the run's log when it
+     * had a run, and said on the console, so the terminal shows it as well. `answered`: the reply to the
+     * press carries it; false for one found after the start was accepted, which every page then shows.
+     */
+    async notStarted(f) {
+        const sessions = [];
+        for (const id of f.sessionIds) {
+            const s = await this.store.getSession(id).catch(() => null);
+            sessions.push({ id, name: s?.name ?? id });
+        }
+        const recorded = this.startFailures.record({
+            pressedAt: f.pressedAt,
+            stage: f.stage,
+            message: f.message,
+            ...(f.runId ? { runId: f.runId } : {}),
+            sessions,
+            answered: f.answered !== false,
+        });
+        console.warn(`[start] the work did not start (${f.stage}${f.runId ? `, run ${f.runId}` : ''}): ${f.message}`);
+        if (f.runId) {
+            const cfg = await this.settings.load().catch(() => null);
+            if (cfg) {
+                await appendRunLog(cfg.resolved.runsDir, f.runId, [
+                    { at: recorded.at, type: 'start-failed', message: f.message, data: { stage: f.stage, failure: recorded.id, sessions: f.sessionIds } },
+                ]).catch(() => undefined);
+            }
+        }
+        return { started: false, reason: f.message, failure: refOf(recorded) };
+    }
+    /**
+     * Writes the start window's choices onto the sessions of a run, or says why one cannot be used.
+     *
+     * Every choice is checked first, with nothing moved (`dry`), so a choice that cannot be used for one
+     * session leaves every other session and every branch as it was; then each is written, and a local
+     * branch made from, or brought up to, its remote one where the choice was to work on it. A session
+     * whose start is fixed keeps it. Recorded in the run's log and the session's.
+     */
+    async applyStartChoices(runId, sessionIds, starts) {
+        if (!starts || typeof starts !== 'object')
+            return null;
+        const wanted = sessionIds.filter((id) => starts[id]);
+        if (wanted.length === 0)
+            return null;
+        for (const id of wanted) {
+            const s = await this.store.getSession(id);
+            if (!s)
+                continue;
+            if (this.running.has(id))
+                return `"${s.name}" is running; its start cannot be changed now.`;
+            const checked = await applyStartChoice(s, starts[id], { dry: true });
+            if (!checked.ok)
+                return `"${s.name}": ${checked.problem}`;
+        }
+        const cfg = await this.settings.load();
+        const entries = [];
+        for (const id of wanted) {
+            const s = await this.store.getSession(id);
+            if (!s)
+                continue;
+            const done = await applyStartChoice(s, starts[id]);
+            if (!done.ok)
+                return `"${s.name}": ${done.problem}`;
+            if (!done.applied)
+                continue;
+            const applied = done.applied;
+            await this.store.updateSession(id, (x) => {
+                if (!x.vcs)
+                    return;
+                x.vcs = withChoice(x.vcs, applied.vcs);
+                if (applied.clearStart) {
+                    x.vcsBaseCommit = undefined;
+                    x.vcsStart = undefined;
+                }
+            });
+            const message = `${applied.said}${applied.note ? `; ${applied.note}` : ''}${applied.clearStart ? '; the start prepared before (a starting snapshot) no longer applies' : ''}`;
+            entries.push({ at: new Date().toISOString(), type: 'start-chosen', message, data: { session: id, choice: starts[id], ...(applied.note ? { note: applied.note } : {}) } });
+            this.bus.publish({ sessionId: id, type: 'start-chosen', level: 'info', message, data: { runId, choice: starts[id] } });
+            await appendSessionLog(cfg.resolved.runsDir, id, { type: 'start-chosen', message, data: { runId, choice: starts[id] } }).catch(() => undefined);
+        }
+        await appendRunLog(cfg.resolved.runsDir, runId, entries).catch(() => undefined);
+        return null;
+    }
+    /** The start window's question for these sessions: their starts and the branches of their repositories. */
+    async startChoices(sessionIds) {
+        await this.init();
+        const sessions = [];
+        for (const id of [...new Set(sessionIds.map((x) => x.trim()).filter(Boolean))]) {
+            const s = await this.store.getSession(id);
+            if (s)
+                sessions.push(s);
+        }
+        return await startOptions(sessions);
+    }
+    /**
+     * Fetches branches of a remote for the start window, where the operator is looking — so through Git's
+     * own password window when the remote asks (see `vcs/remoteAuth.ts`). Only for a folder this bot works
+     * in; only remote-tracking branches move.
+     */
+    async startFetch(dir, remote, branches) {
+        await this.init();
+        await this.knownProjectFolder(dir, 'it is not fetched from here');
+        return await fetchForStart(resolve(dir.trim()), remote.trim(), branches, await askpassProgram());
+    }
+    /** The starts that did not get as far as a first task, newest first: see `session/startFailure.ts`. */
+    recentStartFailures(unansweredOnly) {
+        return this.startFailures.recent({ unansweredOnly }).slice(0, 10).map(refOf);
+    }
+    /**
+     * One of them as a file: what failed and where, the run's record, the sessions' events from the press,
+     * and the console lines from the press to a few seconds after — secret-shaped text taken out.
+     */
+    async startFailureReport(id) {
+        await this.init();
+        const f = this.startFailures.get(id);
+        if (!f)
+            throw new Error('That failed start is not known to this process (was the bot restarted since?). Its console is still in the terminal log: System → "Download what the terminal showed".');
+        const cfg = await this.settings.load();
+        const from = new Date(new Date(f.pressedAt).getTime() - 2_000).toISOString();
+        const to = new Date(new Date(f.at).getTime() + 5_000).toISOString();
+        const events = f.sessions.flatMap((s) => this.bus.recent(s.id)).filter((e) => e.at >= from).sort((a, b) => a.at.localeCompare(b.at));
+        const text = failureReport(f, {
+            runLog: await readRunLog(cfg.resolved.runsDir, f.runId),
+            events,
+            terminal: terminalLines({ from, to, max: 2_000 }),
+            terminalFile: terminalLogFile(),
+            version: botVersion(),
+        });
+        return { fileName: `copilot-operator-not-started-${fileStamp(f.at)}.txt`, content: redactSecrets(text, cfg.report.redactPatterns) };
+    }
+    /** What the bot's console showed: the latest lines kept in memory, as a file. See `log/terminal.ts`. */
+    async terminalReport() {
+        const cfg = await this.settings.load();
+        const lines = terminalLines({ max: 5_000 });
+        const file = terminalLogFile();
+        const head = [
+            "copilot-operator — what the terminal showed (the bot's console)",
+            `Version: ${botVersion()}`,
+            `${lines.length} line(s), the latest kept in memory${file ? `; everything since the bot started is in ${file}` : ''}.`,
+            '',
+            '',
+        ].join('\n');
+        return { fileName: `copilot-operator-terminal-${fileStamp(new Date().toISOString())}.txt`, content: redactSecrets(`${head}${formatTerminal(lines)}\n`, cfg.report.redactPatterns) };
+    }
     /**
      * The same thing `start` does, but it also hands back a promise that settles when the run
      * is over and says how it went.
@@ -1017,7 +1225,7 @@ let OperatorService = class OperatorService {
             return { started: false, reason: 'no such session', done: Promise.resolve(idle) };
         // Set aside by the operator on the Sessions page: not started by anything until made active.
         if (session.active === false) {
-            return { started: false, reason: 'the session is inactive; make it active on the Sessions page to run it', done: Promise.resolve(idle) };
+            return { started: false, reason: INACTIVE_REASON, done: Promise.resolve(idle) };
         }
         const queuedIds = queuedToRun(session, onlyTasks).map((t) => t.id);
         if (queuedIds.length === 0)
@@ -1056,7 +1264,8 @@ let OperatorService = class OperatorService {
          * nothing else.
          */
         const authorizer = this.webAuthorizer(policy, controller.signal);
-        this.running.set(sessionId, { controller, startedAt: new Date().toISOString(), mode, policy });
+        const startedAt = new Date().toISOString();
+        this.running.set(sessionId, { controller, startedAt, mode, policy });
         this.bus.publish({ sessionId, type: 'run-requested', level: 'info', message: `starting in ${mode} mode` });
         // Said at the start of every run, in both modes, because it is the one fact about this tool a
         // data-protection team needs and the one an operator forgets: the reports leave the machine.
@@ -1115,10 +1324,27 @@ let OperatorService = class OperatorService {
                 },
             },
         })
-            .then(async (outcome) => ({ ...(await this.tally(sessionId, queuedIds)), paused: outcome.paused, ...(outcome.refused ? { refused: outcome.refused } : {}) }))
+            .then(async (outcome) => {
+            const tally = { ...(await this.tally(sessionId, queuedIds)), paused: outcome.paused, ...(outcome.refused ? { refused: outcome.refused } : {}) };
+            // Refused at its turn in a run that was going: nothing of it began, and nobody was answered with it.
+            if (outcome.refused && tally.ran === 0) {
+                await this.notStarted({ stage: 'at-turn', message: outcome.refused, sessionIds: [sessionId], pressedAt: how.pressedAt ?? startedAt, ...(runGroup ? { runId: runGroup.id } : {}), answered: false });
+            }
+            return tally;
+        })
             .catch(async (e) => {
             this.bus.publish({ sessionId, type: 'run-failed', level: 'error', message: e.message });
-            return { ...(await this.tally(sessionId, queuedIds)), error: e.message };
+            const tally = { ...(await this.tally(sessionId, queuedIds)), error: e.message };
+            /*
+             * Failed before any task of it began — the browser, the profile, the sign-in, the model: the start
+             * was answered "started" already, so the failure is shown on every page, with the console (2026-10-13).
+             */
+            // Not when the operator stopped it: that is an answer, not a failure to show.
+            if (tally.ran === 0 && !controller.signal.aborted) {
+                console.error('[start] the run ended before its first task:', e.stack ?? e.message);
+                await this.notStarted({ stage: how.laterInRun ? 'at-turn' : 'run', message: e.message, sessionIds: [sessionId], pressedAt: how.pressedAt ?? startedAt, ...(runGroup ? { runId: runGroup.id } : {}), answered: false });
+            }
+            return tally;
         })
             .finally(() => {
             this.running.delete(sessionId);
@@ -1232,14 +1458,17 @@ let OperatorService = class OperatorService {
      * ticked in the register. A session none of whose chosen tasks is queued is skipped; the
      * tasks nobody chose stay queued exactly as they were. Absent means every queued task.
      */
-    taskIds) {
+    taskIds, 
+    /** Where each session starts, as chosen in the start window: see `vcs/startChoice.ts`. Absent keeps their settings. */
+    starts) {
+        const pressedAt = new Date().toISOString();
         const wanted = [...new Set(sessionIds.map((s) => s.trim()).filter(Boolean))];
         // Before anything is waited for (see `browser`): a second batch, a session running on its own
         // — one of these or any other — and a read of the models all have the browser already.
         const claim = this.claimBrowser({ kind: 'batch', sessionIds: wanted });
         if ('refused' in claim)
-            return { started: false, reason: claim.refused };
-        return await this.startBatchHolding(claim.holder, wanted, mode, onFailure, model, reviewModel, name, taskIds);
+            return await this.notStarted({ stage: 'refused', message: claim.refused, sessionIds: wanted, pressedAt });
+        return await this.startBatchHolding(claim.holder, wanted, mode, onFailure, model, reviewModel, name, taskIds, { starts, pressedAt });
     }
     /**
      * `startBatch` for a caller that has claimed the browser already, and the claim with it: handed on
@@ -1247,27 +1476,73 @@ let OperatorService = class OperatorService {
      * refusal. "Run again from here" claims it before it moves anything and starts through this, so
      * one claim covers the restore, the requeue and the run.
      */
-    async startBatchHolding(holder, wanted, mode, onFailure, model, reviewModel, name, taskIds) {
+    async startBatchHolding(holder, wanted, mode, onFailure, model, reviewModel, name, taskIds, how = {}) {
         const onlyTasks = taskIds && taskIds.length > 0 ? new Set(taskIds.map((t) => t.trim()).filter(Boolean)) : undefined;
+        const pressedAt = how.pressedAt ?? new Date().toISOString();
         let handedOn = false;
+        // The batch's id first, so the preflight is recorded under the run it decides about.
+        const batchId = newId('b-');
+        const refuse = (stage, message, runId) => this.notStarted({ stage, message, sessionIds: wanted, pressedAt, ...(runId ? { runId } : {}) });
         try {
             await this.init();
             if (wanted.length === 0)
-                return { started: false, reason: 'no sessions were selected' };
+                return await refuse('refused', 'no sessions were selected');
             // Version control first, before anything opens the browser: see `vcs/runPreflight.ts`.
-            // The batch's id first, so the preflight is recorded under the run it decides about.
-            const batchId = newId('b-');
-            const notReady = await this.runPreflight(batchId, wanted, onlyTasks);
+            /*
+             * Sessions set aside on the Sessions page are left out before the preflight: judged there, an inactive
+             * session's contradiction or version-control problem was the answer to the press — and could refuse
+             * the whole batch — although it would never have run (review of 2026-10-09). `prepareBatch` records
+             * them as skipped, with the reason.
+             */
+            const active = [];
+            const inactive = [];
+            for (const id of wanted) {
+                const s = await this.store.getSession(id);
+                if (s?.active === false)
+                    inactive.push(s.name);
+                else
+                    active.push(id);
+            }
+            if (active.length === 0)
+                return await refuse('refused', `${inactive.map((n) => `"${n}"`).join(', ')}: ${INACTIVE_REASON}`);
+            /*
+             * What refuses the batch whatever branch is chosen, asked before the choices move anything (review of
+             * 2026-10-13): nothing queued among the chosen tasks, an unattended run this machine does not allow.
+             */
+            let anyQueued = false;
+            for (const id of active) {
+                const s = await this.store.getSession(id);
+                if (s && queuedToRun(s, onlyTasks).length > 0)
+                    anyQueued = true;
+            }
+            if (!anyQueued)
+                return await refuse('refused', 'none of the selected sessions has a queued task', batchId);
+            const blockedEarly = await this.unattendedRefusal(mode);
+            if (blockedEarly)
+                return await refuse('refused', blockedEarly, batchId);
+            // The branch each session starts from, as the start window chose it, before the preflight judges it.
+            const unusable = await this.applyStartChoices(batchId, active, how.starts);
+            if (unusable)
+                return await refuse('branch', unusable, batchId);
+            const notReady = await this.runPreflight(batchId, active, onlyTasks);
             if (notReady)
-                return { started: false, reason: notReady };
+                return await refuse('preflight', notReady, batchId);
             const begun = await this.prepareBatch(wanted, onlyTasks, mode, onFailure, model, reviewModel, name, batchId);
             if (!begun.batch)
-                return { started: false, reason: begun.reason };
+                return await refuse('refused', begun.reason, batchId);
+            begun.batch.pressedAt = pressedAt;
             this.batch = begun.batch;
             handedOn = true;
             void this.runBatch(begun.batch, holder);
             return { started: true, batch: this.batchState() };
         }
+        catch (e) {
+            if (unusableConfig(e))
+                throw e;
+            // Said with the error itself, and on record with the console of those moments, rather than as a bare 400.
+            console.error('[start] the run could not be started:', e.stack ?? e.message);
+            return await refuse('error', e.message, batchId);
+        }
         finally {
             if (!handedOn)
                 this.releaseBrowser(holder);
@@ -1306,13 +1581,25 @@ let OperatorService = class OperatorService {
                 sessions.push({ sessionId: id, name: id, state: 'skipped', ran: 0, failed: 0, reason: 'no such session' });
                 continue;
             }
+            /*
+             * Set aside on the Sessions page: left out here, before the browser opens, with the reason `start`
+             * gives. Let through, the batch said "started", opened the browser, and only then skipped it — a
+             * "Run" that reported success and ran nothing.
+             */
+            if (s.active === false) {
+                sessions.push({ sessionId: id, name: s.name, state: 'skipped', ran: 0, failed: 0, reason: INACTIVE_REASON });
+                continue;
+            }
             const queued = queuedToRun(s, onlyTasks).length;
             sessions.push(queued === 0
                 ? { sessionId: id, name: s.name, state: 'skipped', ran: 0, failed: 0, reason: onlyTasks ? 'none of its chosen tasks is queued' : 'nothing queued' }
                 : { sessionId: id, name: s.name, state: 'waiting', ran: 0, failed: 0 });
         }
         if (!sessions.some((s) => s.state === 'waiting')) {
-            return { reason: 'none of the selected sessions has a queued task' };
+            const inactive = sessions.filter((s) => s.reason === INACTIVE_REASON);
+            return {
+                reason: inactive.length > 0 ? `${inactive.map((s) => `"${s.name}"`).join(', ')}: ${INACTIVE_REASON}` : 'none of the selected sessions has a queued task',
+            };
         }
         /*
          * The same entrance rule `start` has, asked here too and for the same reason: before a browser
@@ -1491,6 +1778,19 @@ let OperatorService = class OperatorService {
                 level: 'error',
                 message: `the browser could not be opened: ${e.message}`,
             });
+            /*
+             * The run had been accepted, so the press was answered "started": this is shown on every page
+             * until it is closed, with what the console printed (2026-10-13). The stack is printed for it.
+             */
+            console.error('[start] the browser could not be opened:', e.stack ?? e.message);
+            await this.notStarted({
+                stage: 'browser',
+                message: `the browser could not be opened: ${e.message}`,
+                sessionIds: batch.sessions.map((x) => x.sessionId),
+                pressedAt: batch.pressedAt ?? batch.startedAt,
+                runId: batch.id,
+                answered: false,
+            });
             return;
         }
         try {
@@ -1561,6 +1861,7 @@ let OperatorService = class OperatorService {
                 // switched the batch with it (see `setRunMode`). The hold is this batch's own.
                 const begun = await this.beginRun(entry.sessionId, batch.mode, browser, runGroup, batch.onlyTasks ? new Set(batch.onlyTasks) : undefined, {
                     shouldPause: () => batch.pausing,
+                    laterInRun: batch.sessions.some((x) => x.ran > 0),
                 });
                 if (!begun.started) {
                     entry.state = 'skipped';
@@ -2152,29 +2453,38 @@ let OperatorService = class OperatorService {
         const next = queuedToRun(session, onlyTasks)[0];
         if (!next)
             return null;
+        const conflicts = await this.contractFor(session, next, afterOthers);
+        return conflicts.length === 0
+            ? null
+            : `The task "${next.title}" of "${session.name}" contradicts itself, so it was not started and stays queued: ${conflicts.map((c) => c.text).join(' ')} Press "Run this task" on it, in the register or on the session's page, and the smallest change that removes it is offered there; or change the prompt, the checks, the scope or read-only on the session's page, and start again.`;
+    }
+    /**
+     * Each way the task contradicts itself, judged as its next attempt would start, with the ways out
+     * (see `ContractFix`). The one judgement behind the refusal at a run's start and behind the fixes
+     * the pages offer, so a fix offered is a fix for the refusal the operator was shown.
+     */
+    async contractFor(session, next, afterOthers = false) {
         const cfg = await this.settings.load();
         const work = workingDirFor(session, cfg.resolved.cwd);
         if (isWorkingDirProblem(work))
-            return null;
+            return [];
         /*
          * 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;
+        // By the runner's own rules for the attempt's branch; a task that has run is judged as the attempt it would be queued as.
         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);
+                    : nextAttemptBranch({ ...session, vcs: { ...session.vcs, branchPrefix: prefix } }, next);
         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(() => []);
+        const conflicts = await contractConflictsWithFixes(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);
@@ -2183,12 +2493,95 @@ let OperatorService = class OperatorService {
             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)}.`);
+            if (why) {
+                conflicts.push({
+                    text: `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)}.`,
+                    fixes: [{ kind: 'drop-check', check: c.name }],
+                });
+            }
         }
-        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.`;
+        return conflicts;
+    }
+    /**
+     * How a task contradicts itself, asked by a page: a task that ended `contract-conflict`, or a queued
+     * one a run refused to start for it. Changes nothing.
+     */
+    async contractCheck(sessionId, taskId) {
+        await this.init();
+        const session = await this.store.getSession(sessionId);
+        if (!session)
+            throw new Error('No such session.');
+        const task = session.tasks.find((t) => t.id === taskId);
+        if (!task)
+            throw new Error('No such task.');
+        return { conflicts: await this.contractFor(session, task) };
+    }
+    /**
+     * Applies the chosen way out of each contradiction and puts the task back in the queue.
+     *
+     * `choices` holds one entry per contradiction `contractCheck` names, in its order: the index of the
+     * fix taken, or -1 to leave that one as it is. Judged again here rather than trusted from the page,
+     * and refused when the contradictions are no longer the ones the operator chose from — an edit in
+     * another tab, a check that passes now. A queued task is edited in place; one that has run is queued
+     * again with the change, its attempt kept on the record as any re-run keeps it. Nothing starts.
+     */
+    async applyContractFix(sessionId, taskId, choices, 
+    /** The contradictions the choices were made from, as the page was shown them. */
+    expect) {
+        await this.init();
+        const session = await this.store.getSession(sessionId);
+        if (!session)
+            throw new Error('No such session.');
+        const task = session.tasks.find((t) => t.id === taskId);
+        if (!task)
+            throw new Error('No such task.');
+        if (task.status === 'running' || task.status === 'waiting-approval')
+            throw new Error('This task is running. Stop the session first.');
+        const conflicts = await this.contractFor(session, task);
+        // The same ones, not only as many: a fix chosen for one contradiction must not be applied to another.
+        const same = Array.isArray(expect) ? expect.length === conflicts.length && expect.every((x, i) => x === conflicts[i].text) : true;
+        if (!Array.isArray(choices) || choices.length !== conflicts.length || !same) {
+            throw new Error(`The task's contradictions are not the ones shown (${conflicts.length} now). Look again before applying a fix.`);
+        }
+        const chosen = conflicts.flatMap((c, i) => {
+            const at = choices[i] ?? -1;
+            if (at === -1)
+                return [];
+            const fix = Number.isInteger(at) ? c.fixes[at] : undefined;
+            if (!fix)
+                throw new Error(`There is no fix number ${at} for "${c.text}".`);
+            return [fix];
+        });
+        if (chosen.length === 0)
+            throw new Error('No fix was chosen.');
+        const patch = contractFixPatch(task, chosen);
+        const applied = describeContractChange(task, patch);
+        // Judged on the task as it was read: one edited meanwhile, in another tab, is not overwritten with a patch made from the old one.
+        const contract = (t) => JSON.stringify([t?.status, !!t?.readOnly, t?.scope ?? [], t?.checks ?? []]);
+        const meanwhile = (await this.store.getSession(sessionId))?.tasks.find((t) => t.id === taskId);
+        if (contract(meanwhile) !== contract(task))
+            throw new Error('The task was changed while its contradictions were being judged. Look again before applying a fix.');
+        const updated = task.status === 'queued' ? await this.updateTask(sessionId, taskId, patch) : await this.rerunTask(sessionId, taskId, patch);
+        const after = await this.store.getSession(sessionId);
+        const now = after?.tasks.find((t) => t.id === taskId) ?? updated;
+        const remaining = after ? await this.contractFor(after, now) : [];
+        const cfg = await this.settings.load();
+        await appendSessionLog(cfg.resolved.runsDir, sessionId, {
+            type: 'contract-fixed',
+            message: `"${now.title}": ${applied.join('; ')}${remaining.length > 0 ? `; ${remaining.length} contradiction(s) left` : ''}`,
+            data: { taskId, applied: chosen, remaining: remaining.map((c) => c.text) },
+        }).catch(() => undefined);
+        this.bus.publish({
+            sessionId,
+            taskId,
+            type: 'contract-fixed',
+            level: 'info',
+            message: remaining.length === 0
+                ? `"${now.title}" changed so it no longer contradicts itself: ${applied.join('; ')}`
+                : `"${now.title}" changed (${applied.join('; ')}), and it still contradicts itself in ${remaining.length} way(s)`,
+            data: { applied: chosen, remaining: remaining.length },
+        });
+        return { task: now, applied, remaining };
     }
     /**
      * Where the next task's file checks can be judged before the run: see `ContractTree`. The folder holds
@@ -2218,13 +2611,15 @@ let OperatorService = class OperatorService {
         const branch = how === 'existing-branch' ? session.vcs?.existingBranch?.trim() : session.vcs?.baseBranch?.trim() || 'main';
         if (!branch)
             return 'unknown';
+        // A remote branch chosen in the start window: its remote-tracking branch, as that window fetched it.
+        const ref = how === 'branch' ? baseRefOf(session.vcs).ref : `refs/heads/${branch}`;
         // Brought up to its remote first: what that brings is known only then.
-        if (session.vcs?.updateFromRemote !== false) {
+        if (session.vcs?.updateFromRemote !== false && !(how === 'branch' && session.vcs?.baseRemote)) {
             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}`]);
+        const tip = await git(repo, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
         return tip.ok && tip.stdout ? { ref: tip.stdout } : 'unknown';
     }
     /**
@@ -2508,11 +2903,35 @@ let OperatorService = class OperatorService {
         // Asked of the machine as it is now, as `restartFrom` will ask it; see `unattendedRefused`.
         if (plan.mode === 'unattended')
             plan.unattendedRefused = (await this.unattendedRefusal('unattended')) ?? undefined;
+        // The sessions in the order the run had them: the order `rerunFromRestore` moves them in.
+        const inOrder = [...new Map(tasks.map(({ session: s }) => [s.id, s])).values()];
         for (const target of restoreTargets(tasks)) {
             const preview = await restorePreview(target.session, target.task);
             // What would stop the restore itself, asked here as well, so the dialog says it before the
             // operator agrees rather than after.
             const refused = target.problem ?? (await this.restoreRefusal(target.session));
+            /*
+             * What the restart moves besides the first session's line: each later per-session session in this
+             * repository that ran goes onto a new branch, and its own commits stay on the branch it leaves. By
+             * the conditions `rerunFromRestore` applies when it does it, so the list is what will happen.
+             */
+            const listed = new Set(preview.leftBehind);
+            const here = normaliseDir(target.dir);
+            const laterSessions = [];
+            for (const s of inOrder.slice(inOrder.findIndex((x) => x.id === target.session.id) + 1)) {
+                if (!s.vcs?.enabled || s.vcs.branchMode !== 'per-session' || s.vcs.startFrom === 'existing-branch')
+                    continue;
+                if (!s.vcsBaseCommit || normaliseDir(repoDirOf(s)) !== here)
+                    continue;
+                const first = tasks.find((x) => x.session.id === s.id && x.task.startedAt)?.task;
+                if (!first)
+                    continue;
+                const branch = sessionBranchName(s);
+                const from = (s.vcsStart?.kind === 'branch' ? restorePoint(s, first) : undefined) ?? s.vcsBaseCommit;
+                const commits = (await commitsBetween(target.dir, from, branch).catch(() => [])).filter((c) => !listed.has(c));
+                commits.forEach((c) => listed.add(c));
+                laterSessions.push({ sessionName: s.name, branch, commits });
+            }
             plan.restores.push({
                 repoDir: preview.repoDir || target.dir,
                 ok: preview.ok && !refused,
@@ -2522,6 +2941,7 @@ let OperatorService = class OperatorService {
                 branchName: preview.branchName,
                 leftBehind: preview.leftBehind,
                 keptOn: preview.keptOn,
+                ...(laterSessions.length > 0 ? { laterSessions } : {}),
             });
         }
         /*
@@ -2534,6 +2954,17 @@ let OperatorService = class OperatorService {
             plan.ok = false;
             plan.problem = refusedRestores.map((r) => `${r.repoDir}: ${r.problem ?? 'the restore cannot be made'}`).join(' ');
         }
+        /*
+         * A session set aside on the Sessions page would not run, and the run is refused at its start for it:
+         * said here, before anything moves, as the other entrance rules are (review of 2026-10-09: the
+         * repositories were taken back and the tasks queued, and only then was the run refused).
+         */
+        const inactive = sessions.filter((s) => s.active === false);
+        if (inactive.length > 0) {
+            plan.ok = false;
+            plan.inactive = true;
+            plan.problem = `${inactive.map((s) => `"${s.name}"`).join(', ')}: ${INACTIVE_REASON}`;
+        }
         return plan;
     }
     /**
@@ -2554,6 +2985,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);
+        // A session set aside stops it whatever is asked: its run would be refused after everything moved.
+        if (plan.inactive)
+            return { ...idle, reason: plan.problem };
         // 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))