copilot-operator 0.1.10 → 0.1.12

package/dist/src/session/handoff.js

@@ -1,3 +1,15 @@
+/**
+ * The end of a task in one fixed shape, put together by the runner from what it recorded.
+ *
+ * The chat's summary is the model's account, in its words and in whatever order it chose. The
+ * operator reading a finished run needs the same eight answers every time — what came of it, which
+ * files, what was checked, what is still wrong, where the evidence is, where the code is, what is
+ * left for a person to do, and what was never run — and until now had to piece them together from
+ * the summary, the check list, the review panel, the branch line and the iteration reports. This
+ * reads them off the task record instead, so every entry is a fact the runner saw rather than a
+ * claim, and nothing here is written by the model.
+ */
+import { isContinuable } from './model.js';
 export function composeHandoff(task, notRun = []) {
     const failedChecks = (task.checkResults ?? []).filter((c) => !c.passed);
     const openFindings = task.review?.verdict === 'fail' ? (task.review.findings ?? []).filter((f) => f.about !== 'task') : [];
@@ -18,10 +30,10 @@ export function composeHandoff(task, notRun = []) {
         manual.push(`version control: ${vcs.problem}`);
     if (vcs.commit && vcs.branch)
         manual.push(`push ${vcs.branch} when you are ready — the runner never pushes`);
+    if (isContinuable(task))
+        manual.push('continue it in the same chat from the register, or run it again');
     if (task.status === 'blocked')
         manual.push(`unblock it: ${task.reason ?? 'see the reason'}`);
-    if (task.status === 'limit-reached' || task.status === 'aborted')
-        manual.push('continue it in the same chat from the register, or run it again');
     if (task.status === 'failed')
         manual.push('read why it failed, fix the prompt or the checks, and queue it again');
     if (openFindings.length > 0)
@@ -32,7 +44,33 @@ export function composeHandoff(task, notRun = []) {
         outcome: { status: task.status, ...(task.reason ? { reason: task.reason } : {}), ...(task.stopCode ? { stopCode: task.stopCode } : {}) },
         changedFiles: (vcs.files ?? []).map((f) => ({ path: f.path, added: f.added, removed: f.removed })),
         validation: (task.checkResults ?? []).map((c) => ({ name: c.name, passed: c.passed })),
-        ...(task.review ? { review: { verdict: task.review.verdict, open: openFindings.length } } : {}),
+        ...(task.review
+            ? { review: { verdict: task.review.verdict, open: openFindings.length, ...(task.review.skippedBecause ? { skippedBecause: task.review.skippedBecause } : {}) } }
+            : {}),
+        ...(vcs.branch || vcs.problem
+            ? {
+                lifecycle: {
+                    ...(vcs.beforeCommit ? { preCommitState: { changed: vcs.beforeCommit.changed } } : {}),
+                    checksResult: (task.checkResults ?? []).map((c) => ({ name: c.name, passed: c.passed })),
+                    commitResult: {
+                        ...(vcs.branch ? { branch: vcs.branch } : {}),
+                        ...(vcs.commit ? { commit: vcs.commit } : {}),
+                        files: vcs.files?.length ?? 0,
+                        ...(vcs.problem ? { problem: vcs.problem } : {}),
+                    },
+                    ...(vcs.afterCommit
+                        ? {
+                            postCommitState: {
+                                ...(vcs.afterCommit.branch ? { branch: vcs.afterCommit.branch } : {}),
+                                ...(vcs.afterCommit.head ? { head: vcs.afterCommit.head } : {}),
+                                clean: vcs.afterCommit.clean,
+                                uncommitted: vcs.afterCommit.changed,
+                            },
+                        }
+                        : {}),
+                },
+            }
+            : {}),
         knownIssues,
         evidence: { ...(task.runId ? { runId: task.runId } : {}), checks: task.checkResults?.length ?? 0, reviewRounds: task.review?.rounds ?? 0 },
         vcs: { ...(vcs.branch ? { branch: vcs.branch } : {}), ...(vcs.commit ? { commit: vcs.commit } : {}), pushed: false, ...(vcs.problem ? { problem: vcs.problem } : {}) },

package/dist/src/session/model.js

@@ -12,6 +12,15 @@ export function tidyVcsPlan(plan) {
         return undefined;
     return { ...(branch ? { branch } : {}), ...(commitMessage ? { commitMessage } : {}) };
 }
+/**
+ * Whether "Continue" may carry a task on where it stopped, in its chat and on its branch.
+ *
+ * A task that stopped before it finished qualifies (`limit-reached`, `aborted`), and so does one
+ * whose ending came from a limit in the settings whatever its status says. See `TaskLimit`.
+ */
+export function isContinuable(t) {
+    return t.status === 'limit-reached' || t.status === 'aborted' || (!!t.limit && (t.status === 'failed' || t.status === 'blocked'));
+}
 export function newId(prefix = '') {
     const now = new Date();
     const p = (n) => String(n).padStart(2, '0');

package/dist/src/session/store.js

@@ -9,7 +9,7 @@
 import { mkdir, readFile, writeFile, readdir, rename, rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { newId, tidyVcsPlan } from './model.js';
+import { isContinuable, newId, tidyVcsPlan } from './model.js';
 /** A task the runner is inside of. It cannot be edited, deleted, or left behind at startup. */
 const ACTIVE_STATUSES = ['running', 'waiting-approval'];
 /**
@@ -341,22 +341,24 @@ export class SessionStore {
      *
      * Two kinds of stop qualify. The runner's limit (`limit-reached`), and a stop that was not the
      * task's doing (`aborted`): the bot itself stopping under it — power, a shutdown, Ctrl+C, a crash,
-     * recorded in `interruption` at the next start — or the operator stopping it. A task that failed,
-     * blocked or was not done has a verdict on its work, and carrying that work on would carry the
-     * verdict's cause on with it; those are run again.
+     * recorded in `interruption` at the next start — or the operator stopping it. A task that failed
+     * or blocked has a verdict on its work, and carrying that work on would carry the verdict's cause
+     * on with it; those are run again — unless what ended them was a limit from the settings (out of
+     * rounds of fixing checks or review findings), which is a counter, not the verdict. See `TaskLimit`.
      */
     async continueTask(sessionId, taskId) {
         const current = (await this.getSession(sessionId))?.tasks.find((x) => x.id === taskId);
         if (!current)
             throw new Error(`Task ${taskId} does not exist in session ${sessionId}.`);
-        if (current.status !== 'limit-reached' && current.status !== 'aborted') {
-            throw new Error('Only a task that stopped before it finished can be continued; run this one again instead.');
+        if (!isContinuable(current)) {
+            throw new Error('Only a task that stopped before it finished, or at a limit from the settings, can be continued; run this one again instead.');
         }
-        const how = current.status === 'limit-reached' ? 'limit' : current.interruption ? 'interrupted' : 'stopped';
+        const how = current.status === 'limit-reached' || current.limit ? 'limit' : current.interruption ? 'interrupted' : 'stopped';
         return await this.rerunTask(sessionId, taskId, {}, {
             fromAttempt: current.attempt ?? 1,
             stoppedBecause: current.reason,
             how,
+            ...(current.limit ? { limit: current.limit } : {}),
             ...(current.interruption ? { interruption: current.interruption } : {}),
         });
     }
@@ -400,6 +402,7 @@ export class SessionStore {
                     buildsOn: t.buildsOn,
                     freshRetry: t.freshRetry,
                     stopCode: t.stopCode,
+                    limit: t.limit,
                     scope: t.scope,
                     scopeReverted: t.scopeReverted,
                     vcs: t.vcs,
@@ -438,6 +441,7 @@ export class SessionStore {
             t.scopeReverted = undefined;
             t.freshRetry = undefined;
             t.stopCode = undefined;
+            t.limit = undefined;
             // The branch of the finished attempt stays in the repository and stays on the record
             // above; the next attempt gets its own, cut from the same commit this one started at.
             t.vcs = undefined;

package/dist/src/session/story.js

@@ -12,9 +12,42 @@
  * Nothing here is inferred. An entry is a file, or a section of the task log, or a field of
  * the task record; the reader decides what it means.
  */
-import { readdir, readFile } from 'node:fs/promises';
+import { readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 const MAX_TEXT = 60_000;
+/*
+ * When each thing happened.
+ *
+ * Every entry of the story is a file the runner wrote at the moment it happened: a reply is saved
+ * as it arrives, a step's log is opened as the step starts, a results file is written just before
+ * it is sent. So a file's creation time is the entry's time, for runs recorded long before anyone
+ * asked for times as much as for new ones — nothing had to be recorded differently. The modification
+ * time is the fallback on a file system that keeps no creation time. The opening message has no file
+ * of its own and takes its time from the transcript's first "message-sent".
+ */
+async function createdAt(path) {
+    const info = await stat(path).catch(() => null);
+    if (!info)
+        return undefined;
+    const ms = info.birthtimeMs > 0 ? info.birthtimeMs : info.mtimeMs;
+    return new Date(ms).toISOString();
+}
+async function firstSentAt(dir) {
+    const text = await readFile(join(dir, 'transcript.jsonl'), 'utf8').catch(() => '');
+    for (const line of text.split('\n')) {
+        if (!line.includes('"message-sent"'))
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (e.type === 'message-sent' && e.at)
+                return e.at;
+        }
+        catch {
+            /* a line cut off by a crash */
+        }
+    }
+    return undefined;
+}
 function clip(text) {
     return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}\n… (${text.length - MAX_TEXT} more characters in the run folder)` : text;
 }
@@ -73,6 +106,7 @@ async function stepsIn(dir) {
         const iteration = Number(m[1]);
         const parsed = parseStepLog(await readFile(join(dir, name), 'utf8').catch(() => ''));
         const entry = {
+            at: await createdAt(join(dir, name)),
             kind: 'step',
             iteration,
             id: Number(m[2]),
@@ -103,21 +137,41 @@ async function reviewRound(dir, round) {
     const read = async (name) => clip(await readFile(join(dir, name), 'utf8').catch(() => ''));
     const names = (await readdir(dir).catch(() => [])).sort();
     if (names.includes('00-brief.md'))
-        entries.push({ kind: 'sent', iteration: 0, label: 'brief', text: await read('00-brief.md') });
+        entries.push({ kind: 'sent', iteration: 0, label: 'brief', text: await read('00-brief.md'), at: await createdAt(join(dir, '00-brief.md')) });
     const steps = await stepsIn(join(dir, 'steps'));
-    const replies = names.filter((n) => /^\d+-review\.md$/.test(n)).sort();
-    for (const [i, name] of replies.entries()) {
-        const text = await read(name);
-        const parsed = parseReply(text);
-        entries.push({ kind: 'reply', iteration: i + 1, label: `review ${round}, reply ${i + 1}`, text, ...parsed });
-        for (const step of steps.get(i + 1) ?? [])
+    /*
+     * The replies, by what they answer. `00-opening.md` is the answer to the brief — the one that
+     * proposes the first steps — and `NN-review.md` the answer to the results of iteration NN (the
+     * review saves it after sending them). So after reply k come the steps of iteration k + 1 and
+     * their results, then reply k + 1. The story used to read only the `NN-review` files and put each
+     * before the steps it came after; the times on the entries are what showed it.
+     */
+    const replyFor = new Map();
+    if (names.includes('00-opening.md'))
+        replyFor.set(0, '00-opening.md');
+    for (const n of names) {
+        const m = n.match(/^(\d+)-review\.md$/);
+        if (m)
+            replyFor.set(Number(m[1]), n);
+    }
+    const last = Math.max(0, ...replyFor.keys(), ...steps.keys());
+    for (let k = 0; k <= last; k += 1) {
+        const name = replyFor.get(k);
+        if (name) {
+            const text = await read(name);
+            entries.push({ kind: 'reply', iteration: k, label: `review ${round}, reply ${k + 1}`, text, ...parseReply(text), at: await createdAt(join(dir, name)) });
+        }
+        for (const step of steps.get(k + 1) ?? [])
             entries.push(step);
-        if (names.includes(`iteration-${i + 1}.txt`))
-            entries.push({ kind: 'sent', iteration: i + 1, label: `results ${i + 1}`, text: await read(`iteration-${i + 1}.txt`) });
+        if (names.includes(`iteration-${k + 1}.txt`)) {
+            entries.push({ kind: 'sent', iteration: k + 1, label: `results ${k + 1}`, text: await read(`iteration-${k + 1}.txt`), at: await createdAt(join(dir, `iteration-${k + 1}.txt`)) });
+        }
+    }
+    const replies = [...replyFor.values()];
+    if (names.includes('findings-sent.md')) {
+        entries.push({ kind: 'sent', iteration: replies.length, label: 'findings sent to the implementer', text: await read('findings-sent.md'), at: await createdAt(join(dir, 'findings-sent.md')) });
     }
-    if (names.includes('findings-sent.md'))
-        entries.push({ kind: 'sent', iteration: replies.length, label: 'findings sent to the implementer', text: await read('findings-sent.md') });
-    return { kind: 'review', round, entries };
+    return { kind: 'review', round, entries, at: entries.find((e) => e.at)?.at };
 }
 export async function buildStory(runsDir, runId, task, live) {
     const dir = join(runsDir, runId);
@@ -126,7 +180,9 @@ export async function buildStory(runsDir, runId, task, live) {
     const entries = [];
     const opening = sections.find((s) => s.name === 'OPENING MESSAGE');
     if (opening)
-        entries.push({ kind: 'sent', iteration: 0, label: 'opening message', text: clip(opening.text) });
+        entries.push({ kind: 'sent', iteration: 0, label: 'opening message', text: clip(opening.text), at: (await firstSentAt(dir)) ?? task.startedAt });
+    /** The results file of iteration k, as the report writer names it by default; its creation is when it was sent. */
+    const resultsAt = async (k) => await createdAt(join(dir, 'reports', `iteration-${k}.txt`));
     const steps = await stepsIn(join(dir, 'steps'));
     const reports = new Map();
     for (const s of sections) {
@@ -161,7 +217,7 @@ export async function buildStory(runsDir, runId, task, live) {
             for (const step of steps.get(k) ?? [])
                 entries.push(step);
             if (reports.has(k))
-                entries.push({ kind: 'sent', iteration: k, label: `results ${k}`, text: clip(reports.get(k)) });
+                entries.push({ kind: 'sent', iteration: k, label: `results ${k}`, text: clip(reports.get(k)), at: await resultsAt(k) });
             lastIteration = k;
         }
         else if (rv) {
@@ -170,14 +226,14 @@ export async function buildStory(runsDir, runId, task, live) {
             for (const step of steps.get(lastIteration + 1) ?? [])
                 entries.push(step);
             if (reports.has(lastIteration + 1))
-                entries.push({ kind: 'sent', iteration: lastIteration + 1, label: `results ${lastIteration + 1}`, text: clip(reports.get(lastIteration + 1)) });
+                entries.push({ kind: 'sent', iteration: lastIteration + 1, label: `results ${lastIteration + 1}`, text: clip(reports.get(lastIteration + 1)), at: await resultsAt(lastIteration + 1) });
             lastIteration += reports.has(lastIteration + 1) ? 1 : 0;
             if (!placedReviews.has(round)) {
                 entries.push(await reviewRound(join(dir, 'review', String(round)), round));
                 placedReviews.add(round);
             }
         }
-        entries.push({ kind: 'reply', iteration: it ? Number(it[1]) : 0, label, text, ...parsed });
+        entries.push({ kind: 'reply', iteration: it ? Number(it[1]) : 0, label, text, ...parsed, at: await createdAt(join(dir, 'replies', name)) });
     }
     // Steps and results after the last reply (a task that ended without another reply), and
     // review rounds nobody replied to yet (one still going, or the last one that passed).
@@ -186,7 +242,7 @@ export async function buildStory(runsDir, runId, task, live) {
             for (const step of list)
                 entries.push(step);
             if (reports.has(k))
-                entries.push({ kind: 'sent', iteration: k, label: `results ${k}`, text: clip(reports.get(k)) });
+                entries.push({ kind: 'sent', iteration: k, label: `results ${k}`, text: clip(reports.get(k)), at: await resultsAt(k) });
         }
     }
     for (const round of reviewDirs) {

package/dist/src/transport/chatTransport.js

@@ -20,6 +20,7 @@
  * running in this process — a check script — can call `setTransportFactory`.
  */
 import { CopilotTransport } from './copilotTransport.js';
+export { ReplyTimeoutError, isReplyTimeout } from './copilotTransport.js';
 const realChat = (opts) => new CopilotTransport(opts);
 let factory = realChat;
 /** A chat for these options: the real Copilot window, unless a check has put a scripted one in. */

package/dist/src/transport/copilotTransport.js

@@ -18,6 +18,25 @@ import { landed } from './acceptance.js';
 import { Blocker, Css, Label, Model, Rename, Sidebar, Signal, Surface, TestId, Upload, Url } from './locators.js';
 import { acquireProfileLock } from './profileLock.js';
 import { parseChatId } from './chatSession.js';
+/**
+ * The chat did not finish a reply within `copilot.replyTimeoutSec`.
+ *
+ * Its own class because it is a limit from the settings, not a fault: the runner ends the task
+ * `limit-reached` on it, so "Continue" carries the task on in the same chat, where the reply may
+ * well have finished by then. Any other error from the transport still fails the task.
+ */
+export class ReplyTimeoutError extends Error {
+    seconds;
+    constructor(seconds, message) {
+        super(message);
+        this.seconds = seconds;
+        this.name = 'ReplyTimeoutError';
+    }
+}
+/** Recognised by name as well: a copy of this module loaded twice makes `instanceof` miss its own class. */
+export function isReplyTimeout(e) {
+    return e instanceof ReplyTimeoutError || (e instanceof Error && e.name === 'ReplyTimeoutError' && typeof e.seconds === 'number');
+}
 const ORIGIN = 'https://m365.cloud.microsoft';
 /** Escapes a model name so it can be matched literally inside a regular expression. */
 function escapeForRegExp(text) {
@@ -680,14 +699,77 @@ Current URL: ${url}`);
         }
         await row.click({ timeout: 8_000 }).catch(() => undefined);
     }
-    /** Closes the picker, submenu included. */
+    /**
+     * Whether the model picker is open: its button says so (`aria-expanded`), or its rows are on screen.
+     * Both, because either alone has been wrong: rows can be mid-animation after the menu closed, and a
+     * button re-rendered by the page can lose the attribute while the menu is still up.
+     */
+    async modelMenuOpen() {
+        const button = await this.resolveModelButton(1_000);
+        const expanded = button ? await button.getAttribute('aria-expanded').catch(() => null) : null;
+        if (expanded === 'true')
+            return true;
+        return (await this.readMenuRows()).length > 0;
+    }
+    /**
+     * Closes the picker, submenu included, and makes sure it is closed.
+     *
+     * Escape pressed on the page was all this did, three times, and then it gave up without a word.
+     * Live, that left the model list open over the chat after a check of the model: Escape goes to
+     * whatever has focus, and after a click dispatched on a row, or no click at all because the model
+     * was already chosen, focus was not in the menu, so nothing heard it. Each way a person would close
+     * it is tried in turn, and the menu is looked at after each: Escape; Escape sent to the menu itself;
+     * the picker button again (it toggles); a click outside the menu, in the composer, which a Fluent
+     * popup takes as "close". A menu still open after all of them is reported, not passed over.
+     */
     async closeMenu() {
-        for (let i = 0; i < 3; i += 1) {
-            await this.p.keyboard.press('Escape').catch(() => undefined);
-            await this.p.waitForTimeout(200);
-            if ((await this.readMenuRows()).length === 0)
+        const ways = [
+            ['escape', async () => await this.p.keyboard.press('Escape')],
+            [
+                'escape in the menu',
+                async () => {
+                    for (const selector of Model.popupSelectors.slice(0, 2)) {
+                        const menu = this.p.locator(`${selector}:visible`).last();
+                        if ((await menu.count()) > 0) {
+                            await menu.press('Escape', { timeout: 2_000 });
+                            return;
+                        }
+                    }
+                },
+            ],
+            [
+                'the picker button',
+                async () => {
+                    const button = await this.resolveModelButton(1_000);
+                    // Only while the button itself says the menu is open: clicking it otherwise would open it.
+                    if (button && (await button.getAttribute('aria-expanded').catch(() => null)) === 'true')
+                        await button.click({ timeout: 3_000 });
+                },
+            ],
+            [
+                'a click outside',
+                async () => {
+                    const composer = this.composer();
+                    if ((await composer.count().catch(() => 0)) > 0 && (await composer.isVisible().catch(() => false)))
+                        await composer.click({ timeout: 3_000 });
+                    else
+                        await this.p.mouse.click(4, 4);
+                },
+            ],
+        ];
+        for (const [how, act] of ways) {
+            if (!(await this.modelMenuOpen()))
                 return;
+            await act().catch(() => undefined);
+            await this.p.waitForTimeout(250);
+            if (!(await this.modelMenuOpen())) {
+                if (how !== 'escape')
+                    this.emit('model-menu-closed', { how });
+                return;
+            }
         }
+        if (await this.modelMenuOpen())
+            this.emit('model-menu-stuck', { tried: ways.map(([how]) => how) });
     }
     /** The first popup container that becomes visible after the picker is clicked. */
     async waitForPopup(timeoutMs = 8_000) {
@@ -772,8 +854,7 @@ Current URL: ${url}`);
         await this.p.waitForTimeout(1_000);
         // Whatever the click did, the menu is not left open over the chat: a build that keeps it open
         // after a choice, or a click that did not land, would otherwise leave it for the next message.
-        if ((await this.readMenuRows()).length > 0)
-            await this.closeMenu();
+        await this.closeMenu();
         const after = await this.currentModel();
         // The button shows the choice, so it is the check. It also **shortens** it: picking
         // "GPT 5.6 Quick response" leaves the button reading "GPT 5.6 Quick". So a shown value
@@ -1057,7 +1138,7 @@ Current URL: ${url}`);
         }
         if (!sawNewTurn || !last.finished) {
             await this.dumpFailure(join(this.opts.transportDir, '..', 'failures'), 'reply-timeout').catch(() => undefined);
-            throw new Error(`Copilot did not finish a reply within ${Math.round(this.opts.replyTimeoutMs / 1000)}s ` +
+            throw new ReplyTimeoutError(Math.round(this.opts.replyTimeoutMs / 1000), `Copilot did not finish a reply within ${Math.round(this.opts.replyTimeoutMs / 1000)}s ` +
                 `(new turn seen: ${sawNewTurn}, still streaming: ${last.streaming}). ` +
                 'A screenshot and an HTML dump are in the run folder.');
         }

package/dist/src/vcs/git.js

@@ -155,6 +155,21 @@ export function branchNameFrom(parts, prefix = 'cop/') {
  */
 export function plannedBranchName(raw, prefix = 'cop/', attempt = 1) {
     const trimmed = raw.trim();
+    /*
+     * A name with its own namespace — `recovery/apz-migration`, `feature/JIRA-123-schemas` — is the
+     * team's convention, and it is used as written: the prefix is only for names that have none.
+     * Flattening it to `cop/recovery-apz-migration` made a different branch from the one asked for,
+     * so a plan continuing a recovery branch worked beside it instead of on it (2026-09-30). Each
+     * segment is still made safe, keeping its case; git itself has the last word in `switchTo`.
+     */
+    if (trimmed.includes('/')) {
+        const segments = trimmed
+            .split('/')
+            .map((seg) => seg.replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^[-.]+|[-.]+$/g, ''))
+            .filter(Boolean);
+        if (segments.length > 1)
+            return `${segments.join('/')}${attempt > 1 ? `-a${attempt}` : ''}`.replace(/\.\.+/g, '.').slice(0, 200);
+    }
     const p = prefix.trim();
     const body = p && trimmed.toLowerCase().startsWith(p.toLowerCase()) ? trimmed.slice(p.length) : trimmed;
     return branchNameFrom([body, attempt > 1 ? `a${attempt}` : undefined], prefix);

package/dist/src/vcs/syncCommand.js

@@ -0,0 +1,105 @@
+/**
+ * The command that brings a project's current branch back to the remote's main branch, handed to
+ * the operator rather than run.
+ *
+ * Asked for after a day of runs: a project left on a task branch, with files a step created and
+ * nobody committed, wants to go back to where the team's code is. That is `fetch`, `reset --hard`
+ * to the remote's main, and `clean -fd` for the new files git does not ignore — three commands that
+ * destroy work if pointed at the wrong folder or run a minute too early. So the bot never runs them.
+ * It reads the repository, says exactly what would be lost — commits on this branch that the
+ * remote's main does not have, changed tracked files, new files — and gives the command, ready to
+ * paste into PowerShell, with a read-only preview beside it. Ignored files (`node_modules`, `.env`,
+ * build output) are left alone: `clean` without `-x` does not touch them.
+ *
+ * Nothing here writes to the repository or the network. `git fetch` is in the command, not here:
+ * what "would be lost" is computed against the remote branch as last fetched, and the page says so.
+ */
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { git, porcelainPaths } from './git.js';
+/** A string as a single-quoted PowerShell literal: nothing inside it is expanded. */
+export function psQuote(text) {
+    return `'${text.replace(/'/g, "''")}'`;
+}
+/**
+ * The two commands, for Windows PowerShell 5.1 and PowerShell 7 alike: `;` and `$LASTEXITCODE`
+ * rather than `&&`, which 5.1 does not have, so a failed fetch stops everything after it instead
+ * of resetting to a remote branch that is out of date.
+ */
+export function syncCommands(dir, remote, target) {
+    const g = `git -C ${psQuote(dir)}`;
+    return {
+        preview: [
+            `${g} fetch ${psQuote(remote)}`,
+            `${g} log --oneline ${psQuote(`${target}..HEAD`)}`,
+            `${g} status --short`,
+            `${g} clean -nd`,
+        ].join('; '),
+        command: `${g} fetch ${psQuote(remote)}; if ($LASTEXITCODE -eq 0) { ${g} reset --hard ${psQuote(target)}; ` +
+            `if ($LASTEXITCODE -eq 0) { ${g} clean -fd } }`,
+    };
+}
+const empty = (repoDir, problem) => ({
+    ok: false,
+    problem,
+    repoDir,
+    willLose: { commits: [], changed: [], untracked: [] },
+    preview: '',
+    command: '',
+});
+export async function planSync(repoDir) {
+    const inside = await git(repoDir, ['rev-parse', '--is-inside-work-tree']);
+    if (!inside.ok || inside.stdout !== 'true')
+        return empty(repoDir, `${repoDir} is not a git repository.`);
+    const branch = await git(repoDir, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    if (!branch.ok || !branch.stdout) {
+        return empty(repoDir, 'The repository is not on a branch (a detached HEAD), so there is no "current branch" to bring up to date. Check out a branch first.');
+    }
+    const remotes = (await git(repoDir, ['remote'])).stdout.split('\n').map((r) => r.trim()).filter(Boolean);
+    if (remotes.length === 0)
+        return empty(repoDir, 'The repository has no remote, so there is no remote main branch to go back to.');
+    const remote = remotes.includes('origin') ? 'origin' : remotes[0];
+    // The remote's own idea of its main branch first, then the two usual names.
+    let target = '';
+    const head = await git(repoDir, ['symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`]);
+    if (head.ok && head.stdout)
+        target = head.stdout;
+    for (const name of ['main', 'master']) {
+        if (target)
+            break;
+        const found = await git(repoDir, ['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/${name}`]);
+        if (found.ok)
+            target = `${remote}/${name}`;
+    }
+    if (!target) {
+        return empty(repoDir, `No main branch of ${remote} is known here yet. Run ${syncCommands(repoDir, remote, `${remote}/main`).preview.split('; ')[0]} once, then look again.`);
+    }
+    const commits = await git(repoDir, ['log', '--format=%h %s', `${target}..HEAD`]);
+    const status = await git(repoDir, ['status', '--porcelain', '--untracked-files=no']);
+    const clean = await git(repoDir, ['clean', '-nd']);
+    let lastFetched;
+    try {
+        const gitDir = (await git(repoDir, ['rev-parse', '--absolute-git-dir'])).stdout;
+        lastFetched = statSync(join(gitDir, 'FETCH_HEAD')).mtime.toISOString();
+    }
+    catch {
+        /* never fetched: the page says so */
+    }
+    return {
+        ok: true,
+        repoDir,
+        branch: branch.stdout,
+        remote,
+        target,
+        ...(lastFetched ? { lastFetched } : {}),
+        willLose: {
+            commits: commits.ok && commits.stdout ? commits.stdout.split('\n') : [],
+            changed: porcelainPaths(status.stdout),
+            untracked: clean.stdout
+                .split('\n')
+                .map((l) => l.replace(/^Would remove\s+/, '').trim())
+                .filter(Boolean),
+        },
+        ...syncCommands(repoDir, remote, target),
+    };
+}

package/dist/src/vcs/taskVcs.js

@@ -282,6 +282,15 @@ export function noteFor(repoDir, vcs, ctx = { mode: 'per-task', earlier: [] }) {
         `The runner has already put ${repoDir} on the branch \`${vcs.branch}\`, created for this task from ${base},`,
         'and it will commit whatever you change when the task finishes.',
         '',
+        /*
+         * Said outright because a plan's text may still name the branch the work came from: a task that
+         * was told to continue a recovery branch went on asking for it, on a branch the runner had made
+         * (2026-09-30). The branch above is where the work goes; what it must contain is a commit.
+         */
+        `\`${vcs.branch}\` is where this work goes, whatever branch the task or the project instructions name: do not ask for`,
+        'another branch, switch to it or check that you are on it. When earlier work must be included, check its',
+        'commit instead: `git merge-base --is-ancestor <commit> HEAD` exits 0 when it is.',
+        '',
         ...(began ? [began, ''] : []),
         standing,
         '',
@@ -320,19 +329,33 @@ export async function commitTaskResult(session, task, outcome, bus) {
      * (they are already there; refusing would not remove them) and named on the task.
      */
     const state = await repoState(dir);
+    /*
+     * The repository before the commit and after it, kept apart on the record. A task's own claims
+     * ("nothing committed, the tree is dirty") were written before this runs; without both states
+     * the export read as contradicting itself. See `TaskVcs.beforeCommit`.
+     */
+    const beforeCommit = { changed: state.changed.slice(0, 200) };
+    const withStates = async (v) => {
+        const after = await repoState(dir).catch(() => null);
+        return {
+            ...v,
+            beforeCommit,
+            ...(after ? { afterCommit: { branch: after.branch ?? undefined, head: after.head ?? undefined, clean: !after.dirty, changed: after.changed.slice(0, 200) } } : {}),
+        };
+    };
     if (state.branch !== current.branch) {
         const problem = `the repository is on ${state.branch ?? 'a detached HEAD'}, not on the task's branch ${current.branch}: it was moved while the task ran. ` +
             'Nothing was committed; the changes are left in the working tree for you to look at.';
         bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-provenance', level: 'error', message: problem,
             data: { expected: current.branch, actual: state.branch } });
-        return { ...current, problem };
+        return await withStates({ ...current, problem });
     }
     if (current.baseCommit && state.head && !(await isAncestor(dir, current.baseCommit))) {
         const problem = `the task's branch ${current.branch} no longer contains the commit it started from (${current.baseCommit.slice(0, 8)}): ` +
             'it was reset or rewritten while the task ran. Nothing was committed; the changes are left in the working tree.';
         bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-provenance', level: 'error', message: problem,
             data: { base: current.baseCommit, head: state.head } });
-        return { ...current, problem };
+        return await withStates({ ...current, problem });
     }
     const foreign = current.baseCommit ? await foreignCommits(dir, current.baseCommit) : [];
     if (foreign.length > 0) {
@@ -345,12 +368,12 @@ export async function commitTaskResult(session, task, outcome, bus) {
     if (result.problem) {
         bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-problem', level: 'warn',
             message: `nothing was committed: ${result.problem}` });
-        return { ...current, problem: result.problem };
+        return await withStates({ ...current, problem: result.problem });
     }
     if (!result.committed) {
         bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-nothing', level: 'info',
             message: `nothing to commit on ${current.branch}: the task changed no files` });
-        return current;
+        return await withStates(current);
     }
     const commits = current.baseCommit ? await commitsBetween(dir, current.baseCommit) : [];
     const files = result.commit ? await commitFiles(dir, result.commit) : [];
@@ -367,14 +390,14 @@ export async function commitTaskResult(session, task, outcome, bus) {
                 suspicious.map((s) => `${s.path} (${s.reason})`).join('; '),
             data: { commit: result.commit, suspicious } });
     }
-    return {
+    return await withStates({
         ...current,
         commit: result.commit,
         commits,
         files,
         ...(suspicious.length > 0 ? { suspicious } : {}),
         ...(foreign.length > 0 ? { foreignCommits: foreign } : {}),
-    };
+    });
 }
 /**
  * Commits what a task left behind when the process running it ended before it could.