copilot-operator 0.1.13 → 0.1.16

package/dist/src/protocol/parser.js

@@ -169,7 +169,11 @@ export function parseReply(markdown, opts) {
             reply.notes = stripCitations(reply.notes);
             reply.summary = stripCitations(reply.summary);
             const steps = reply.steps.map((s) => ({ ...s, shell: s.shell ?? opts.defaultShell }));
-            const markerHit = markdown.includes(opts.stopMarker);
+            // A blank stop word is no stop word. The setting is free text, and every reply contains the
+            // empty string and nearly every one a space, so searching for either would read each
+            // `continue` that carries a summary as done and close the task after one round.
+            const marker = opts.stopMarker.trim();
+            const markerHit = marker !== '' && markdown.includes(marker);
             const hasSummary = (reply.summary ?? '').trim().length > 0;
             // The stop word alone is not enough to end a task any more: the summary is the
             // deliverable, and a marker without one would let a task close with nothing to show.

package/dist/src/session/debugExport.js

@@ -145,7 +145,7 @@ export async function buildDebugExport(input) {
             chat: session.chat ? { name: session.chat.name, url: session.chat.url } : undefined,
             vcs: session.vcs,
             vcsBaseCommit: session.vcsBaseCommit,
-            mirror: session.mirror,
+            projectDir: session.projectDir,
             tasks,
         });
     }

package/dist/src/session/exportRecord.js

@@ -245,7 +245,7 @@ export async function buildExport(input) {
         `chat       : ${session.chat?.url ?? '(no conversation was opened)'}`,
         `model      : ${session.model || 'whatever the chat was set to'}${session.modelInUse ? ` (ran on ${session.modelInUse})` : ''}`,
         `repository : ${session.vcs?.enabled
-            ? `${session.vcs.repoDir || session.mirror.rootDir || '(none set)'} — ${session.vcs.branchMode === 'per-session' ? 'one branch for the whole session' : 'a branch of its own for every task'}, prefix ${session.vcs.branchPrefix}${session.vcs.commitOnFinish ? '' : ', commits off'}`
+            ? `${session.vcs.repoDir || session.projectDir || '(none set)'} — ${session.vcs.branchMode === 'per-session' ? 'one branch for the whole session' : 'a branch of its own for every task'}, prefix ${session.vcs.branchPrefix}${session.vcs.commitOnFinish ? '' : ', commits off'}`
             : 'version control is off for this session'}`,
         `tasks      : ${tasks.length} of ${session.tasks.length}`,
         `exported   : ${when(new Date().toISOString())}`,

package/dist/src/session/exports.js

@@ -149,14 +149,7 @@ export function buildPlanExport(scope) {
                     ...(s.vcs?.updateFromRemote === false ? { updateFromRemote: false } : {}),
                 },
                 review: { enabled: s.review?.enabled !== false, model: s.review?.model ?? '' },
-                mirror: {
-                    enabled: s.mirror.enabled,
-                    rootDir: s.mirror.rootDir,
-                    includeDirs: s.mirror.includeDirs,
-                    excludeDirs: s.mirror.excludeDirs,
-                    respectGitignore: s.mirror.respectGitignore ?? true,
-                    includeEnvFiles: s.mirror.includeEnvFiles ?? false,
-                },
+                ...(s.projectDir ? { projectDir: s.projectDir } : {}),
                 tasks: tasks.map((t) => {
                     const p = splitPrompt(t.prompt);
                     const task = { title: t.title, prompt: p.prompt, expected: p.expected };
@@ -269,6 +262,54 @@ export function taskAtAttempt(task, attempt) {
 export function withTask(session, task) {
     return { ...session, tasks: session.tasks.map((t) => (t.id === task.id ? task : t)) };
 }
+/**
+ * The task as it ended in one run: the last of its attempts that ran in it, live or archived, or
+ * null when none did. Several attempts can share a run (a retry in a fresh chat is one); the last
+ * is how the run left it, with the ones before it as its history.
+ */
+export function taskInRun(task, runId) {
+    if (task.runGroup?.id === runId)
+        return task;
+    const attempts = task.attempts ?? [];
+    for (let i = attempts.length - 1; i >= 0; i -= 1) {
+        if (attempts[i]?.runGroup?.id === runId)
+            return taskAtAttempt(task, i + 1);
+    }
+    return null;
+}
+/**
+ * One run's sessions, with each task as it ended in that run, and only the tasks that were part of it.
+ *
+ * A run is a record of what happened, and the task on the record moves on after it: "run again"
+ * queues it as a new attempt, and another run may finish it. Taken as it is now, a task that
+ * failed in the run read as queued, its failure only among the earlier attempts, and the run's
+ * counts said nothing failed in it; once a later run had stamped it, the task was not in the
+ * first run's export at all. So each task is taken at its attempt in the run (`taskInRun`), and
+ * the three views describe the run whichever is asked for. A task the run was asked to do and
+ * never reached has no such attempt; it is still the run's, as it stands, through the run's own
+ * record on the session.
+ */
+export function runScope(sessions, runId, label) {
+    const chosen = new Map();
+    const asInRun = sessions.map((s) => {
+        let session = s;
+        const ids = new Set();
+        for (const t of s.tasks) {
+            const ran = taskInRun(t, runId);
+            if (ran) {
+                ids.add(t.id);
+                if (ran !== t)
+                    session = withTask(session, ran);
+            }
+            else if (s.runGroup?.id === runId && s.runGroup.taskIds.includes(t.id)) {
+                ids.add(t.id);
+            }
+        }
+        chosen.set(s.id, ids);
+        return session;
+    });
+    return { sessions: asInRun, taskFilter: (s, t) => !!chosen.get(s.id)?.has(t.id), label };
+}
 /** What the runner export says about the machine, from the configuration in force. */
 export function exportMachine(cfg) {
     return {
@@ -540,7 +581,6 @@ async function botTask(session, task, runsDir) {
             fromReviews: task.reviewChecks,
         },
         processes: { leftovers: task.leftovers, reaped: events.filter((e) => e.type === 'processes-reaped').map(trimmed), notOurs: events.filter((e) => e.type === 'processes-not-ours').map(trimmed) },
-        mirror: events.filter((e) => String(e.type).startsWith('mirror')).map(trimmed),
         review: {
             verdict: task.review?.verdict,
             rounds: task.review?.rounds,

package/dist/src/session/store.js

@@ -4,10 +4,12 @@
  * JSON files, not a database. A single operator on one machine gets nothing from a
  * database except a dependency, and files can be read, diffed and backed up with nothing
  * installed. Writes go through a temp file and a rename, so a crash mid-write cannot leave a
- * half-written session behind.
+ * half-written session behind, and the writes of one file wait their turn (see `inTurn`), so two
+ * at once cannot fail each other or undo each other's change.
  */
 import { mkdir, readFile, writeFile, readdir, rename, rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { join, resolve } from 'node:path';
 import { isContinuable, newId, tidyVcsPlan } from './model.js';
 /** A task the runner is inside of. It cannot be edited, deleted, or left behind at startup. */
@@ -34,14 +36,27 @@ export const DEFAULT_VCS = {
     commitOnFinish: true,
     branchPrefix: 'cop/',
 };
-export const DEFAULT_MIRROR = {
-    enabled: false,
-    rootDir: '',
-    includeDirs: [],
-    excludeDirs: [],
-    respectGitignore: true,
-    includeEnvFiles: false,
-};
+/**
+ * Points a new session that names no folder at the default project, the one on the Project page.
+ *
+ * The one rule for every way a session is made: on the Sessions page and by importing a plan. The
+ * import used to skip it, so a plan's session with version control off and no `projectDir` — the
+ * brief's own example has one — kept an empty folder and ran its commands in `execution.cwd`,
+ * somewhere the operator never chose, while the same session made by hand worked in their project.
+ *
+ * Both fields, because they answer different questions about the same folder: where the work is
+ * and where the branches go. Version control is not switched on by being filled in. A session that
+ * names either keeps what it named and gets nothing here: a plan's repository with the default
+ * project beside it as its folder would say the work is in two places.
+ */
+export function applyDefaultProject(session, defaultDir) {
+    const dir = defaultDir.trim();
+    if (!dir || session.projectDir.trim() || session.vcs?.repoDir.trim())
+        return;
+    session.projectDir = dir;
+    if (session.vcs)
+        session.vcs.repoDir = dir;
+}
 /**
  * Applies an edit to a task: the one place the rule about a new intent lives.
  *
@@ -114,10 +129,10 @@ export class SessionStore {
         return { content: await readFile(this.defaultLevel1Path, 'utf8'), customised: false };
     }
     async setLevel1(content) {
-        await this.atomicWrite(this.level1Path, content);
+        await writeFileAtomically(this.level1Path, content);
     }
     async resetLevel1() {
-        await rm(this.level1Path, { force: true });
+        await removeFile(this.level1Path);
     }
     // --- the organisation's part of the plan persona -------------------------------------
     /**
@@ -136,10 +151,10 @@ export class SessionStore {
         return { content: '', customised: false, example };
     }
     async setContext(kind, content) {
-        await this.atomicWrite(join(this.dir, `context-${kind}.md`), content);
+        await writeFileAtomically(join(this.dir, `context-${kind}.md`), content);
     }
     async resetContext(kind) {
-        await rm(join(this.dir, `context-${kind}.md`), { force: true });
+        await removeFile(join(this.dir, `context-${kind}.md`));
     }
     // --- the model catalogue ----------------------------------------------------------------
     /** What the chat's picker offered when it was last read, or null if it never was. */
@@ -152,7 +167,7 @@ export class SessionStore {
         }
     }
     async saveModels(catalogue) {
-        await this.atomicWrite(this.modelsPath, JSON.stringify(catalogue, null, 2));
+        await writeFileAtomically(this.modelsPath, JSON.stringify(catalogue, null, 2));
     }
     // --- level 2 presets ------------------------------------------------------------------
     async listPresets() {
@@ -168,15 +183,23 @@ export class SessionStore {
         }
         return out;
     }
+    /**
+     * Saves a preset under the name it can later be deleted by.
+     *
+     * Stripping the characters a file name cannot hold is not enough on its own: a leading dot and
+     * ".." survive it, and `safePresetName` refuses both, so ".env" and "a..b" were saved and then
+     * could never be deleted. The name goes through the same rule as the delete, the way a persona's
+     * always has, so a name that could not be removed is refused here instead.
+     */
     async savePreset(name, content) {
         const safe = name.replace(/[^\p{L}\p{N}._ -]/gu, '').trim();
         if (!safe)
             throw new Error('Preset name is empty after removing unsafe characters.');
-        await this.atomicWrite(join(this.presetsDir, `${safe}.md`), content);
+        await writeFileAtomically(join(this.presetsDir, `${safePresetName(safe)}.md`), content);
         return { name: safe, content, updatedAt: new Date().toISOString() };
     }
     async deletePreset(name) {
-        await rm(join(this.presetsDir, `${safePresetName(name)}.md`), { force: true });
+        await removeFile(await namedFile(this.presetsDir, name));
     }
     // --- named personas -------------------------------------------------------------------
     //
@@ -202,11 +225,11 @@ export class SessionStore {
         if (!safe)
             throw new Error('The persona name is empty after removing unsafe characters.');
         await mkdir(this.personasDir, { recursive: true });
-        await this.atomicWrite(join(this.personasDir, `${safePresetName(safe)}.md`), content);
+        await writeFileAtomically(join(this.personasDir, `${safePresetName(safe)}.md`), content);
         return { name: safe, content, updatedAt: new Date().toISOString() };
     }
     async deletePersona(name) {
-        await rm(join(this.personasDir, `${safePresetName(name)}.md`), { force: true });
+        await removeFile(await namedFile(this.personasDir, name));
     }
     // --- sessions -------------------------------------------------------------------------
     /**
@@ -238,10 +261,27 @@ export class SessionStore {
             return b.id.localeCompare(a.id);
         });
     }
+    /**
+     * The session of this id, or null when there is none.
+     *
+     * An id that could not be a session's file name — a path, `..`, anything `safeName` refuses —
+     * names no session, and is answered as one that does not exist. It used to throw here, so every
+     * route that only reads a session (the session itself, a task's log, story or files, a start)
+     * answered a path for an id with a 500 rather than the 404 or "no such session" a missing one
+     * gets. A write or a delete of such an id is still refused outright: those go through
+     * `sessionPath` themselves.
+     */
     async getSession(id) {
-        return await this.readSession(join(this.sessionsDir, `${safeName(id)}.json`));
+        let path;
+        try {
+            path = this.sessionPath(id);
+        }
+        catch {
+            return null;
+        }
+        return await this.readSession(path);
     }
-    async createSession(name, mirror = {}) {
+    async createSession(name, projectDir = '') {
         const session = {
             id: newId(),
             name: name.trim() || 'untitled',
@@ -252,26 +292,38 @@ export class SessionStore {
             // behaved and the safer of the two.
             onFailure: 'stop',
             vcs: { ...DEFAULT_VCS },
-            mirror: { ...DEFAULT_MIRROR, ...mirror },
+            projectDir: projectDir.trim(),
             tasks: [],
         };
         await this.saveSession(session);
         return session;
     }
     async saveSession(session) {
-        await this.atomicWrite(join(this.sessionsDir, `${safeName(session.id)}.json`), JSON.stringify(session, null, 2));
+        await writeFileAtomically(this.sessionPath(session.id), JSON.stringify(session, null, 2));
     }
     async deleteSession(id) {
-        await rm(join(this.sessionsDir, `${safeName(id)}.json`), { force: true });
+        await removeFile(this.sessionPath(id));
     }
-    /** Applies a change under a fresh read, so two writers cannot clobber each other. */
+    /**
+     * Applies a change under a fresh read, so two writers cannot clobber each other.
+     *
+     * The read, the change and the write happen in the file's turn, with nothing else of this
+     * process writing the session in between. A fresh read alone did not keep that promise: Stop
+     * writes "stopping" at the moment it answers an approval, and the runner it has just woken
+     * writes the task at the same moment. Both read the session before either had written, so
+     * whichever wrote second put back what the first had changed, or, when both renamed at once,
+     * one of them failed and took the stop or the task down with it.
+     */
     async updateSession(id, mutate) {
-        const s = await this.getSession(id);
-        if (!s)
-            throw new Error(`Session ${id} does not exist.`);
-        mutate(s);
-        await this.saveSession(s);
-        return s;
+        const path = this.sessionPath(id);
+        return await inTurn(path, async () => {
+            const s = await this.readSession(path);
+            if (!s)
+                throw new Error(`Session ${id} does not exist.`);
+            mutate(s);
+            await replaceFile(path, JSON.stringify(s, null, 2));
+            return s;
+        });
     }
     async addTask(sessionId, input) {
         const vcsPlan = tidyVcsPlan(input.vcsPlan);
@@ -465,33 +517,41 @@ export class SessionStore {
      */
     async recoverInterrupted() {
         const recovered = [];
-        for (const session of await this.listSessions()) {
-            const stuck = session.tasks.filter((t) => ACTIVE_STATUSES.includes(t.status));
-            const busySession = session.status !== 'idle';
-            if (stuck.length === 0 && !busySession)
+        for (const listed of await this.listSessions()) {
+            if (listed.status === 'idle' && !listed.tasks.some((t) => ACTIVE_STATUSES.includes(t.status)))
                 continue;
-            for (const t of stuck) {
-                t.status = 'aborted';
-                t.finishedAt = t.finishedAt ?? new Date().toISOString();
-                t.reason =
-                    'The bot stopped while this task was in progress (the program was closed, the machine went off, or it crashed), so it never finished. ' +
-                        'Its work so far is kept; "Continue in the same chat" carries it on where it stopped.';
-                recovered.push({ sessionId: session.id, taskId: t.id, title: t.title });
-            }
-            session.status = 'idle';
-            await this.saveSession(session);
+            // Read again in the file's turn, like any other change, so a write that landed since the
+            // list was read is kept rather than replaced by the copy in the list.
+            const path = this.sessionPath(listed.id);
+            await inTurn(path, async () => {
+                const session = await this.readSession(path);
+                if (!session)
+                    return;
+                for (const t of session.tasks.filter((x) => ACTIVE_STATUSES.includes(x.status))) {
+                    t.status = 'aborted';
+                    t.finishedAt = t.finishedAt ?? new Date().toISOString();
+                    t.reason =
+                        'The bot stopped while this task was in progress (the program was closed, the machine went off, or it crashed), so it never finished. ' +
+                            'Its work so far is kept; "Continue in the same chat" carries it on where it stopped.';
+                    recovered.push({ sessionId: session.id, taskId: t.id, title: t.title });
+                }
+                session.status = 'idle';
+                await replaceFile(path, JSON.stringify(session, null, 2));
+            });
         }
         return recovered;
     }
     // --- helpers --------------------------------------------------------------------------
     /**
-     * Reads one session file, filling in mirror fields added after it was written. Sessions are
+     * Reads one session file, filling in fields added after it was written. Sessions are
      * long-lived JSON on disk, so a new option must never come back as `undefined`.
      */
     async readSession(path) {
         try {
             const s = JSON.parse(await readFile(path, 'utf8'));
-            s.mirror = { ...DEFAULT_MIRROR, ...(s.mirror ?? {}) };
+            // Written before the project-files feature was removed: its root is the project folder.
+            s.projectDir = (s.projectDir ?? s.mirror?.rootDir ?? '').trim();
+            delete s.mirror;
             s.vcs = { ...DEFAULT_VCS, ...(s.vcs ?? {}) };
             // Sessions written before the queue could be told what to do on a failure behave the
             // way they always did: the chain stops.
@@ -502,44 +562,119 @@ export class SessionStore {
             return null;
         }
     }
-    /**
-     * Write through a temp file and a rename, and keep trying when Windows says no.
-     *
-     * The rename is what makes the write atomic: a crash halfway through leaves the temp file
-     * behind and the real one untouched. On Windows it is also the step that fails, because
-     * renaming onto a destination that any other process has open is refused outright — and this
-     * file is read constantly, by the register polling every few seconds, by the sessions list,
-     * and by whatever virus scanner has decided to look inside a JSON file that just changed.
-     *
-     * The failure is EPERM and it is transient: the handle closes microseconds later. Letting it
-     * through unretried meant a task dying mid-run with a message about a temp file, which is
-     * what happened — a scaffold that had finished three tasks was killed by a file lock on the
-     * fourth. So it is retried, briefly and with a growing pause, and only then given up on.
-     */
-    async atomicWrite(path, content) {
-        const tmp = `${path}.${process.pid}.tmp`;
-        await writeFile(tmp, content, 'utf8');
-        const backoffMs = [10, 25, 60, 120, 250, 500];
-        for (let attempt = 0;; attempt += 1) {
-            try {
-                await rename(tmp, path);
-                return;
-            }
-            catch (e) {
-                const code = e.code ?? '';
-                const transient = code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
-                if (!transient || attempt >= backoffMs.length) {
-                    // The temp file is no use to anyone now, and leaving one per failed write behind
-                    // would slowly fill the folder with them.
-                    await rm(tmp, { force: true }).catch(() => undefined);
-                    throw new Error(`Could not save ${path}: ${code || e.message}. ` +
-                        'Something else is holding the file open — an editor, a sync client or a virus scanner.');
-                }
-                await new Promise((r) => setTimeout(r, backoffMs[attempt]));
+    sessionPath(id) {
+        return join(this.sessionsDir, `${safeName(id)}.json`);
+    }
+}
+// --- writing a file -------------------------------------------------------------------------
+/**
+ * The work queued on each file, by the file's full path: the tail of its chain.
+ *
+ * Kept for the module, not for one store, because every store in a process writes the same
+ * files: the API has one, but a check or the terminal may make another over the same folder,
+ * and a queue each would let their writes meet again.
+ */
+const queued = new Map();
+/**
+ * Runs `work` once everything queued earlier on the same file has finished, failed or not.
+ *
+ * Every write of the store goes through here, and `updateSession` holds the turn across its read
+ * as well, as does a write worked out from the file (see `writeFileAtomically`), so a change is
+ * always made to what the last write left. `work` must not wait for another turn on the same file,
+ * which would wait for itself; nothing here does, and a session's `mutate` is synchronous, so it
+ * cannot.
+ *
+ * In this process only: another process writing the same file at the same time is not waited
+ * for. The one that might, a run from the terminal, makes a session of its own and writes only that.
+ */
+function inTurn(path, work) {
+    const full = resolve(path);
+    // Windows treats `A.json` and `a.json` as one file, so they share one queue there.
+    const key = process.platform === 'win32' ? full.toLowerCase() : full;
+    const run = (queued.get(key) ?? Promise.resolve()).then(work);
+    const tail = run.then(() => undefined, () => undefined);
+    queued.set(key, tail);
+    // Forgotten once nothing is queued behind it, so the map holds only the files being written.
+    void tail.then(() => {
+        if (queued.get(key) === tail)
+            queued.delete(key);
+    });
+    return run;
+}
+/**
+ * Writes a file whole, in its turn: a crash, or another write of the same file, cannot leave it
+ * half written or lose either write. For any file the program keeps, not only the store's.
+ *
+ * `content` may be a function instead, for a write worked out from what the file holds: it is
+ * called in the file's turn, so what it reads is what the last write left, and nothing else of this
+ * process writes the file until its answer has landed. Read first and written here, a change of one
+ * setting put back whatever another had changed in between. If it throws, nothing is written. Like
+ * any work in a turn, it must not wait for another turn on the same file (see `inTurn`).
+ */
+export async function writeFileAtomically(path, content) {
+    await inTurn(path, async () => replaceFile(path, typeof content === 'string' ? content : await content()));
+}
+/** Removes a file in its turn, so a delete and a write of it land in the order they were asked for. */
+async function removeFile(path) {
+    await inTurn(path, () => rm(path, { force: true }));
+}
+/**
+ * Write through a temp file and a rename, and keep trying when Windows says no. Not queued: the
+ * caller holds the file's turn (see `inTurn`).
+ *
+ * The rename is what makes the write atomic: a crash halfway through leaves the temp file
+ * behind and the real one untouched. On Windows it is also the step that fails, because
+ * renaming onto a destination that any other process has open is refused outright — and this
+ * file is read constantly, by the register polling every few seconds, by the sessions list,
+ * and by whatever virus scanner has decided to look inside a JSON file that just changed.
+ *
+ * The failure is EPERM and it is transient: the handle closes microseconds later. Letting it
+ * through unretried meant a task dying mid-run with a message about a temp file, which is
+ * what happened — a scaffold that had finished three tasks was killed by a file lock on the
+ * fourth. So it is retried, briefly and with a growing pause, and only then given up on.
+ *
+ * Each write has a temp file of its own. One name per process was shared by every write of the
+ * same file, so when two overlapped, the first rename took the temp file the second was about to
+ * rename, and the second failed with ENOENT — reported as a lock it was not.
+ */
+async function replaceFile(path, content) {
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(tmp, content, 'utf8');
+    const backoffMs = [10, 25, 60, 120, 250, 500];
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await rename(tmp, path);
+            return;
+        }
+        catch (e) {
+            const code = e.code ?? '';
+            const transient = code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+            if (!transient || attempt >= backoffMs.length) {
+                // The temp file is no use to anyone now, and leaving one per failed write behind
+                // would slowly fill the folder with them.
+                await rm(tmp, { force: true }).catch(() => undefined);
+                throw new Error(transient
+                    ? `Could not save ${path}: ${code}. Something else is holding the file open — an editor, a sync client or a virus scanner.`
+                    : `Could not save ${path}: ${e.message}`);
             }
+            await new Promise((r) => setTimeout(r, backoffMs[attempt]));
         }
     }
 }
+/**
+ * The file a preset or persona of this name is kept in, for removing it.
+ *
+ * A name `safePresetName` accepts, or one that is already a file in the folder. The save did not
+ * always apply that rule, so a preset called ".env" or "a..b" may be on disk from before; without
+ * the second way it is listed and can never be deleted. A name matched against the folder's own
+ * listing is a file name, which cannot hold a separator, so it cannot reach outside the folder.
+ */
+async function namedFile(dir, name) {
+    const onDisk = await readdir(dir).catch(() => []);
+    if (onDisk.includes(`${name}.md`))
+        return join(dir, `${name}.md`);
+    return join(dir, `${safePresetName(name)}.md`);
+}
 /**
  * A session id as it may appear in a file name, or an error.
  *

package/dist/src/transport/copilotTransport.js

@@ -11,7 +11,7 @@
  *   3. A message cannot consist of an attachment alone; Send stays disabled without text.
  */
 import { chromium } from 'playwright';
-import { mkdir } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { findRecentCrash, describeCrash } from './edgeCrash.js';
 import { landed } from './acceptance.js';
@@ -575,6 +575,7 @@ Current URL: ${url}`);
             return { options: [], current, note: 'The model picker opened nothing that could be read.' };
         }
         const top = await this.readMenuRows();
+        await this.captureMenu('top', top);
         await this.closeMenu();
         const options = top.filter((r) => !r.opensSubmenu).map(({ opensSubmenu, ...o }) => o);
         const groups = top.filter((r) => r.opensSubmenu);
@@ -589,8 +590,44 @@ Current URL: ${url}`);
             }
         }
         this.emit('models-read', { count: options.length, groups: groups.length, current });
+        await this.captureMenu('result', top, { current, options }).catch(() => undefined);
         return { options, current };
     }
+    /**
+     * What the picker showed, kept beside the reading: the menu as HTML, a picture of it, and the rows
+     * that were read from it.
+     *
+     * The picker is Microsoft's markup and it changes without notice; when "Read the list from
+     * Copilot" comes back with the wrong models, the only way to see why is the menu as it was at that
+     * moment. Written to this transport's folder (runs/_models for that button), overwritten by the
+     * next reading, and never a reason for the reading to fail. Nothing personal is in a model menu.
+     */
+    async captureMenu(label, rows, extra) {
+        try {
+            await mkdir(this.opts.transportDir, { recursive: true });
+            const base = join(this.opts.transportDir, `models-${label}`);
+            if (label !== 'result') {
+                const html = await this.p
+                    .evaluate((selectors) => {
+                    const parts = [];
+                    for (const sel of selectors) {
+                        for (const el of Array.from(document.querySelectorAll(sel))) {
+                            if (el.getClientRects().length > 0)
+                                parts.push(`<!-- ${sel} -->\n${el.outerHTML}`);
+                        }
+                    }
+                    return parts.join('\n\n');
+                }, [...Model.popupSelectors])
+                    .catch((e) => `<!-- could not read the menu: ${String(e)} -->`);
+                await writeFile(`${base}.html`, html, 'utf8');
+                await this.p.screenshot({ path: `${base}.png` }).catch(() => undefined);
+            }
+            await writeFile(`${base}.json`, JSON.stringify({ at: new Date().toISOString(), rows, ...(extra ?? {}) }, null, 2), 'utf8');
+        }
+        catch {
+            /* a diagnostic, never the reason a reading fails */
+        }
+    }
     /** Every visible menu row right now, across the menu and whatever submenu is open. */
     async readMenuRows() {
         return await this.p.evaluate(({ roles, selectedAttrs, submenuAttrs }) => {
@@ -652,6 +689,7 @@ Current URL: ${url}`);
             await trigger.click().catch(() => undefined);
             children = await this.waitForNewRows(topNames);
         }
+        await this.captureMenu(`group-${groupName.replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 40)}`, children);
         await this.closeMenu();
         return children;
     }