copilot-operator 0.1.0

package/dist/src/session/exports.js

@@ -0,0 +1,484 @@
+/**
+ * Three JSON views of the same work, for handing to whoever — or whatever — has to reason
+ * about it next. Each answers one question and nothing else, because a file that answers all
+ * three is the debug export next door, and the person debugging one task does not want to
+ * scroll past the machine's PATH to find the prompt.
+ *
+ *   plan    What was asked. The sessions and tasks in the plan format, as they are *now*: a
+ *           plan written by a chat model and then edited in the UI comes back out with the
+ *           edits, and a queue built by hand comes out as a plan that never existed as a file.
+ *           It re-imports.
+ *   domain  What happened to the work. The task as it was given, what the chat tried, what
+ *           was actually done to the repository, and why it did not end done — in the words
+ *           of the task, not of the runner.
+ *   bot     What the runner did. The environment, every transcript event, every step with its
+ *           exit code and duration, the transport's retries, what was reaped, what the review
+ *           machinery went through. Nothing about the domain that is not needed to read it.
+ *
+ * All three exist for one task and for one run, because those are the two sizes a question
+ * comes in: "why did this one fail" and "what did this whole run do".
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { withoutPersona } from '../plan/importPlan.js';
+const EXPECTED_HEADER = '### Expected result';
+const GOAL_HEADER = '## Goal of this session';
+const MAX_STRING_CHARS = 2000;
+function clip(text, max = MAX_STRING_CHARS) {
+    return text.length > max ? `${text.slice(0, max)}… (${text.length - max} more characters)` : text;
+}
+function tasksOf(scope) {
+    const out = [];
+    for (const session of scope.sessions) {
+        for (const task of session.tasks) {
+            if (!scope.taskFilter || scope.taskFilter(session, task))
+                out.push({ session, task });
+        }
+    }
+    return out;
+}
+function stamp() {
+    return new Date().toISOString().slice(0, 16).replace(/[:T]/g, '').replace(/-/g, '');
+}
+function fileLabel(label) {
+    return label.replace(/[^\p{L}\p{N}._ -]/gu, '').trim().replace(/\s+/g, '-').slice(0, 60) || 'export';
+}
+export function exportFileName(kind, label) {
+    return `copilot-operator-${kind}-${fileLabel(label)}-${stamp()}.json`;
+}
+// ------------------------------------------------------------------------------------------
+// plan: what was asked, in the format that goes back in
+// ------------------------------------------------------------------------------------------
+/** The prompt as stored is the plan's prompt with `expected` appended under a heading. */
+function splitPrompt(prompt) {
+    const i = prompt.indexOf(`\n\n${EXPECTED_HEADER}\n\n`);
+    if (i < 0)
+        return { prompt, expected: '' };
+    return { prompt: prompt.slice(0, i).trim(), expected: prompt.slice(i + EXPECTED_HEADER.length + 4).trim() };
+}
+/** The session's level 2 is the plan's level 2 with the goal on top under a heading. */
+function splitLevel2(level2) {
+    const text = level2.trim();
+    if (!text.startsWith(GOAL_HEADER))
+        return { goal: '', level2: text };
+    const body = text.slice(GOAL_HEADER.length).trim();
+    const gap = body.indexOf('\n\n');
+    if (gap < 0)
+        return { goal: body, level2: '' };
+    return { goal: body.slice(0, gap).trim(), level2: body.slice(gap).trim() };
+}
+/** The level 2 most of a session's tasks carry, which is the one the plan gave the session. */
+/**
+ * A task's level 2 as the plan wrote it: the operator's persona taken off the front.
+ *
+ * The import puts the persona that was in force on every task. The plan export is for importing
+ * again, where the persona in the field *then* is the one that should apply — so it is lifted out
+ * here, exactly, by its closing line. Left in, it would sit in front of the session's goal, the goal
+ * would no longer be found at the head of the text, and a second import would add a second persona
+ * on top of the first. The record exports keep it: they describe what ran, and the approach is part
+ * of what ran.
+ */
+function planLevel2(t) {
+    return withoutPersona(t.level2).trim();
+}
+function commonLevel2(tasks) {
+    const counts = new Map();
+    for (const t of tasks)
+        counts.set(planLevel2(t), (counts.get(planLevel2(t)) ?? 0) + 1);
+    let best = '';
+    let n = 0;
+    for (const [text, count] of counts) {
+        if (count > n) {
+            best = text;
+            n = count;
+        }
+    }
+    return best;
+}
+function planCheck(c) {
+    const out = { name: c.name, expect: c.expect };
+    if (c.run)
+        out.run = c.run;
+    if (c.shell)
+        out.shell = c.shell;
+    if (c.cwd)
+        out.cwd = c.cwd;
+    if (c.file)
+        out.file = c.file;
+    if (c.value !== undefined && c.value !== '')
+        out.value = c.value;
+    return out;
+}
+export function buildPlanExport(scope) {
+    const sessions = scope.sessions.filter((s) => s.tasks.some((t) => !scope.taskFilter || scope.taskFilter(s, t)));
+    const groups = new Set(sessions.map((s) => (s.conversationGroup ?? '').trim()));
+    const shared = sessions.length > 1 && groups.size === 1 && !groups.has('');
+    const runFailure = sessions.find((s) => s.runGroup?.onFailure)?.runGroup?.onFailure ?? 'stop';
+    return {
+        version: 1,
+        plan: scope.label,
+        notes: `Exported from copilot-operator on ${new Date().toISOString()}: the sessions and tasks as they are now, ` +
+            'including anything edited in the UI after the original plan (if there was one) was imported. ' +
+            'Task outcomes are not part of this file; it is the plan, and it can be imported again.',
+        onFailure: runFailure,
+        conversation: shared ? 'shared' : 'per-session',
+        sessions: sessions.map((s) => {
+            const tasks = s.tasks.filter((t) => !scope.taskFilter || scope.taskFilter(s, t));
+            const level2 = commonLevel2(tasks);
+            const split = splitLevel2(level2);
+            const session = {
+                name: s.name,
+                goal: split.goal,
+                model: s.model ?? '',
+                onFailure: s.onFailure ?? 'stop',
+                level2: split.level2,
+                conversationGroup: shared ? '' : (s.conversationGroup ?? ''),
+                vcs: {
+                    enabled: s.vcs?.enabled ?? false,
+                    repoDir: s.vcs?.repoDir ?? '',
+                    branchMode: s.vcs?.branchMode ?? 'per-task',
+                    commitOnFinish: s.vcs?.commitOnFinish ?? true,
+                    branchPrefix: s.vcs?.branchPrefix ?? 'cop/',
+                    branchName: s.vcs?.branchName ?? '',
+                },
+                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,
+                },
+                tasks: tasks.map((t) => {
+                    const p = splitPrompt(t.prompt);
+                    const task = { title: t.title, prompt: p.prompt, expected: p.expected };
+                    if (planLevel2(t) !== level2)
+                        task.level2 = planLevel2(t);
+                    if (t.vcsPlan?.branch || t.vcsPlan?.commitMessage) {
+                        task.vcs = { ...(t.vcsPlan.branch ? { branch: t.vcsPlan.branch } : {}), ...(t.vcsPlan.commitMessage ? { commitMessage: t.vcsPlan.commitMessage } : {}) };
+                    }
+                    if (t.checks && t.checks.length > 0)
+                        task.checks = t.checks.map(planCheck);
+                    if (t.reviewEnabled === false)
+                        task.review = false;
+                    if (t.readOnly)
+                        task.readOnly = true;
+                    return task;
+                }),
+            };
+            return session;
+        }),
+    };
+}
+async function readEvents(runsDir, runId) {
+    if (!runId)
+        return [];
+    const raw = await readFile(join(runsDir, runId, 'transcript.jsonl'), 'utf8').catch(() => null);
+    if (raw === null)
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // A half-written last line when the process died is not a reason to lose the rest.
+        }
+    }
+    return out;
+}
+/** Every string in an event cut to a readable length; the run folder keeps the full text. */
+function trimmed(event) {
+    const out = {};
+    for (const [k, v] of Object.entries(event)) {
+        out[k] = typeof v === 'string' ? clip(v, 600) : v;
+    }
+    return out;
+}
+/** Steps joined from proposed/started/finished/skipped, in the order they were proposed. */
+function stepsOf(events) {
+    const byKey = new Map();
+    let iteration = 0;
+    for (const e of events) {
+        if (e.type === 'reply-parsed')
+            iteration = Number(e.iteration ?? iteration + 1);
+        const id = typeof e.id === 'number' ? e.id : undefined;
+        if (id === undefined)
+            continue;
+        const key = `${iteration}:${id}`;
+        if (e.type === 'step-proposed') {
+            byKey.set(key, { id, iteration, description: typeof e.description === 'string' ? clip(e.description, 600) : undefined });
+        }
+        else if (e.type === 'step-finished') {
+            const s = byKey.get(key) ?? { id, iteration };
+            byKey.set(key, { ...s, outcome: String(e.outcome ?? ''), exitCode: typeof e.exitCode === 'number' ? e.exitCode : undefined, durationMs: typeof e.durationMs === 'number' ? e.durationMs : undefined });
+        }
+        else if (e.type === 'step-skipped' || e.type === 'step-repeated' || e.type === 'step-damaged') {
+            const s = byKey.get(key) ?? { id, iteration };
+            byKey.set(key, { ...s, refused: String(e.reason ?? e.message ?? e.type) });
+        }
+    }
+    return [...byKey.values()];
+}
+// ------------------------------------------------------------------------------------------
+// domain: what happened to the work
+// ------------------------------------------------------------------------------------------
+/** What a closing `blocked` reply said it tried and needed, read back out of the reply. */
+function blockedDetail(finalReply) {
+    if (!finalReply)
+        return undefined;
+    const m = finalReply.match(/```json\s*([\s\S]*?)```/) ?? [null, finalReply];
+    try {
+        const j = JSON.parse((m[1] ?? '').trim());
+        const tried = Array.isArray(j.tried) ? j.tried.map(String) : undefined;
+        const needed = typeof j.needed === 'string' ? j.needed : undefined;
+        return tried || needed ? { tried, needed } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function domainTask(session, task, runsDir) {
+    const events = await readEvents(runsDir, task.runId);
+    const steps = stepsOf(events);
+    const rounds = events
+        .filter((e) => e.type === 'reply-parsed')
+        .map((e) => ({
+        iteration: e.iteration,
+        status: e.status,
+        notes: typeof e.notes === 'string' ? clip(e.notes, 1000) : undefined,
+        steps: steps.filter((s) => s.iteration === e.iteration).map((s) => ({ id: s.id, ran: s.description, outcome: s.refused ? `refused: ${s.refused}` : s.outcome, exitCode: s.exitCode })),
+    }));
+    const p = splitPrompt(task.prompt);
+    const failed = task.status !== 'done' && task.status !== 'queued' && task.status !== 'running' && task.status !== 'waiting-approval';
+    const started = task.startedAt ? Date.parse(task.startedAt) : NaN;
+    const finished = task.finishedAt ? Date.parse(task.finishedAt) : NaN;
+    const out = {
+        session: { id: session.id, name: session.name },
+        task: {
+            id: task.id,
+            title: task.title,
+            attempt: task.attempt ?? 1,
+            readOnly: task.readOnly ?? false,
+            prompt: p.prompt,
+            expected: p.expected,
+            level2: task.level2,
+            checks: (task.checks ?? []).map(planCheck),
+        },
+        outcome: {
+            status: task.status,
+            reason: task.reason,
+            summary: task.summary,
+            startedAt: task.startedAt,
+            finishedAt: task.finishedAt,
+            durationMs: Number.isFinite(started) && Number.isFinite(finished) ? finished - started : undefined,
+            iterations: task.iterations,
+            checks: task.checkResults,
+        },
+        whatTheChatTried: rounds,
+        whatWasActuallyDone: {
+            repository: task.vcs,
+            deviations: task.deviations,
+            disputes: task.disputes,
+            filesAttachedFirst: undefined,
+        },
+        review: task.review
+            ? {
+                verdict: task.review.verdict,
+                rounds: task.review.rounds,
+                stepsRun: task.review.stepsRun,
+                model: task.review.model,
+                summary: task.review.summary,
+                findings: task.review.findings,
+                problem: task.review.problem,
+            }
+            : undefined,
+    };
+    if (failed) {
+        out.whyItFailed = {
+            status: task.status,
+            reason: task.reason,
+            failingChecks: (task.checkResults ?? []).filter((c) => !c.passed),
+            blocked: blockedDetail(task.finalReply),
+            reviewFindings: task.review?.verdict === 'fail' ? task.review.findings : undefined,
+            leftovers: task.leftovers,
+            lastRound: rounds.at(-1),
+        };
+    }
+    /*
+     * The attempts before this one, each with its own transcript.
+     *
+     * After "fix the prompt and queue it again" the task on the record is queued and the failure
+     * that prompted the fix lives only here — so an export taken then, which is exactly when
+     * somebody wants to hand the failure to a model, has to carry what the earlier attempt tried
+     * and why it ended, not just that it did.
+     */
+    if (task.attempts && task.attempts.length > 0) {
+        const earlier = [];
+        for (const [i, a] of task.attempts.entries()) {
+            const aEvents = await readEvents(runsDir, a.runId);
+            const aSteps = stepsOf(aEvents);
+            const aRounds = aEvents
+                .filter((e) => e.type === 'reply-parsed')
+                .map((e) => ({
+                iteration: e.iteration,
+                status: e.status,
+                notes: typeof e.notes === 'string' ? clip(e.notes, 1000) : undefined,
+                steps: aSteps.filter((s) => s.iteration === e.iteration).map((s) => ({ id: s.id, ran: s.description, outcome: s.refused ? `refused: ${s.refused}` : s.outcome, exitCode: s.exitCode })),
+            }));
+            const aFailed = a.status !== 'done';
+            earlier.push({
+                attempt: i + 1,
+                runId: a.runId,
+                status: a.status,
+                reason: a.reason,
+                summary: a.summary,
+                iterations: a.iterations,
+                startedAt: a.startedAt,
+                finishedAt: a.finishedAt,
+                prompt: a.prompt !== task.prompt ? splitPrompt(a.prompt).prompt : undefined,
+                whatTheChatTried: aRounds,
+                whatWasActuallyDone: { repository: a.vcs, deviations: a.deviations, disputes: a.disputes },
+                whyItFailed: aFailed
+                    ? { status: a.status, reason: a.reason, failingChecks: (a.checkResults ?? []).filter((c) => !c.passed), lastRound: aRounds.at(-1) }
+                    : undefined,
+            });
+        }
+        out.earlierAttempts = earlier;
+    }
+    return out;
+}
+export async function buildDomainExport(scope, runsDir) {
+    const pairs = tasksOf(scope);
+    const tasks = [];
+    for (const { session, task } of pairs)
+        tasks.push(await domainTask(session, task, runsDir));
+    const counts = { tasks: pairs.length, done: 0, failed: 0, open: 0 };
+    for (const { task } of pairs) {
+        if (task.status === 'done')
+            counts.done += 1;
+        else if (task.status === 'queued' || task.status === 'running' || task.status === 'waiting-approval')
+            counts.open += 1;
+        else
+            counts.failed += 1;
+    }
+    return {
+        exportedAt: new Date().toISOString(),
+        about: `copilot-operator, the work: ${scope.label}. What each task asked, what the chat tried, what was done to the repository, and why a task did not end done. Nothing about the runner itself; that is the bot export.`,
+        counts,
+        tasks,
+    };
+}
+// ------------------------------------------------------------------------------------------
+// bot: what the runner did
+// ------------------------------------------------------------------------------------------
+const TRANSPORT_TYPES = new Set(['message-sent', 'format-error', 'report-written', 'report-redacted', 'report-send-failed', 'attachment-missing', 'chat-registered', 'download']);
+async function botTask(session, task, runsDir) {
+    const events = await readEvents(runsDir, task.runId);
+    const steps = stepsOf(events);
+    const byType = new Map();
+    for (const e of events)
+        byType.set(String(e.type), (byType.get(String(e.type)) ?? 0) + 1);
+    const problems = events.filter((e) => e.level === 'error' || e.level === 'warn').map(trimmed);
+    const reviewEvents = events.filter((e) => String(e.type).startsWith('review-') || String(e.type).startsWith('finding-'));
+    return {
+        session: { id: session.id, name: session.name, model: session.model, modelInUse: session.modelInUse, reviewModel: session.review?.model },
+        task: { id: task.id, title: task.title, attempt: task.attempt ?? 1, status: task.status, runId: task.runId, runFolder: task.runId ? join(runsDir, task.runId) : undefined, logFile: task.logFile },
+        timing: { startedAt: task.startedAt, finishedAt: task.finishedAt, iterations: task.iterations },
+        environment: task.environment,
+        transport: {
+            counts: Object.fromEntries([...byType.entries()].filter(([t]) => TRANSPORT_TYPES.has(t))),
+            events: events.filter((e) => TRANSPORT_TYPES.has(String(e.type))).map(trimmed),
+        },
+        steps: steps.map((s) => ({ iteration: s.iteration, id: s.id, command: s.description, outcome: s.outcome, exitCode: s.exitCode, durationMs: s.durationMs, refused: s.refused })),
+        checks: {
+            results: task.checkResults,
+            rounds: byType.get('checks-started') ?? 0,
+            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,
+            stepsRun: task.review?.stepsRun,
+            model: task.review?.model,
+            problem: task.review?.problem,
+            formatErrors: byType.get('review-format-error') ?? 0,
+            events: reviewEvents.map(trimmed),
+        },
+        problems,
+        eventCounts: Object.fromEntries(byType.entries()),
+        events: events.map(trimmed),
+        // Earlier attempts with their own run folders: the same technical record, per attempt,
+        // because a task queued again after a failure has no transcript of its own yet.
+        earlierAttempts: await Promise.all((task.attempts ?? []).map(async (a, i) => {
+            const aEvents = await readEvents(runsDir, a.runId);
+            return {
+                attempt: i + 1,
+                runId: a.runId,
+                runFolder: a.runId ? join(runsDir, a.runId) : undefined,
+                status: a.status,
+                steps: stepsOf(aEvents).map((s) => ({ iteration: s.iteration, id: s.id, command: s.description, outcome: s.outcome, exitCode: s.exitCode, durationMs: s.durationMs, refused: s.refused })),
+                problems: aEvents.filter((e) => e.level === 'error' || e.level === 'warn').map(trimmed),
+                events: aEvents.map(trimmed),
+            };
+        })),
+    };
+}
+export async function buildBotExport(scope, runsDir, machine) {
+    const pairs = tasksOf(scope);
+    const tasks = [];
+    for (const { session, task } of pairs)
+        tasks.push(await botTask(session, task, runsDir));
+    return {
+        exportedAt: new Date().toISOString(),
+        about: `copilot-operator, the runner: ${scope.label}. The environment, every transcript event, every step with its exit code, the transport's retries, what was reaped, what the review machinery did. Read the domain export for what the task was about.`,
+        machine,
+        tasks,
+    };
+}
+// ------------------------------------------------------------------------------------------
+// bundle: all three views of the same chosen tasks, in one file
+// ------------------------------------------------------------------------------------------
+/**
+ * The three exports of one chosen set of tasks, in a single document.
+ *
+ * The three are downloaded separately because they answer separate questions, and that is right
+ * when the question is known. It is wrong for the thing the operator actually does most: hand a
+ * failure to a chat model and ask what happened. That needs all three — the plan says what was
+ * asked, the work says what the chat did with it, the runner says what the machine did — and
+ * until now it meant three downloads, three attachments, and remembering which was which.
+ *
+ * **The three stay whole rather than being interleaved per task.** Merging them into one array
+ * of tasks, each carrying its plan, its work and its runner, reads better and is the wrong
+ * trade: the plan export's whole point is that it goes back in through the import page, and a
+ * plan folded inside a fourth format is a plan nothing can read. So this is a wrapper, each
+ * part exactly the document it would have been on its own, and anything that could read one of
+ * them still can.
+ *
+ * `work` and `runner` are what the interface calls them. Inside the code they are `domain` and
+ * `bot`, which is a naming the operator has never been shown and should not meet here.
+ */
+export async function buildBundleExport(scope, runsDir, machine) {
+    const pairs = tasksOf(scope);
+    return {
+        exportedAt: new Date().toISOString(),
+        about: `copilot-operator, all three views of ${pairs.length} chosen task(s): ${scope.label}. ` +
+            '`plan` is what was asked, in the format that imports again; `work` is what happened to it; ' +
+            '`runner` is what the machine did. Read `work` first, then `runner` when the machine is the suspect.',
+        chosen: pairs.map(({ session, task }) => ({
+            session: session.name,
+            sessionId: session.id,
+            task: task.title,
+            taskId: task.id,
+            status: task.status,
+        })),
+        plan: buildPlanExport(scope),
+        work: await buildDomainExport(scope, runsDir),
+        runner: await buildBotExport(scope, runsDir, machine),
+    };
+}

package/dist/src/session/model.js

@@ -0,0 +1,22 @@
+/**
+ * A plan with its blanks removed, or nothing at all when both are blank.
+ *
+ * One function rather than three, because a task made in the form, a task made by an import
+ * and a task edited afterwards all have to end up in the same shape on disk. An empty string
+ * is how the form says "I do not want a name here", and it must leave no trace behind.
+ */
+export function tidyVcsPlan(plan) {
+    const branch = plan?.branch?.trim();
+    const commitMessage = plan?.commitMessage?.trim();
+    if (!branch && !commitMessage)
+        return undefined;
+    return { ...(branch ? { branch } : {}), ...(commitMessage ? { commitMessage } : {}) };
+}
+export function newId(prefix = '') {
+    const now = new Date();
+    const p = (n) => String(n).padStart(2, '0');
+    const stamp = `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}` +
+        `-${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+    const rnd = Math.random().toString(36).slice(2, 6);
+    return `${prefix}${stamp}-${rnd}`;
+}

package/dist/src/session/retention.js

@@ -0,0 +1,34 @@
+/**
+ * How long a session's run folder is kept.
+ *
+ * A run folder holds every step's raw output, the reports that were uploaded, the reviewer's
+ * transcripts and, on a failure, a screenshot of the signed-in page. Nothing used to remove any of
+ * it, which for an operator's own machine is a choice and for a company is a gap: a retention
+ * rule says how long such records may exist, and a tool that keeps them forever cannot follow it.
+ *
+ * `runsRetentionDays` in the config is the rule; 0, the default, keeps everything, because nothing
+ * here should delete an operator's records without their say. When set, the API removes at start
+ * every session folder whose last change is older than that. Folders whose name begins with `_`
+ * are the bot's own working folders (`_browser`, `_models`) and are left alone.
+ */
+import { readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Removes the session run folders older than `keepDays`; returns the names removed. */
+export async function pruneRuns(runsDir, keepDays, now = Date.now()) {
+    if (!Number.isFinite(keepDays) || keepDays <= 0)
+        return [];
+    const cutoff = now - keepDays * 24 * 60 * 60 * 1000;
+    const removed = [];
+    const entries = await readdir(runsDir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('_'))
+            continue;
+        const path = join(runsDir, entry.name);
+        const s = await stat(path).catch(() => null);
+        if (!s || s.mtimeMs >= cutoff)
+            continue;
+        await rm(path, { recursive: true, force: true }).catch(() => undefined);
+        removed.push(entry.name);
+    }
+    return removed;
+}

package/dist/src/session/runName.js

@@ -0,0 +1,36 @@
+/** A trailing ` #12` taken off, so the counter never stacks up into `name #2 #3`. */
+function stripNumber(name) {
+    return name.replace(/\s*#\d+$/, '').trim();
+}
+export function suggestRunName(all, sessionIds, about) {
+    const wanted = new Set(sessionIds);
+    /** Every name any run has ever carried, wherever it was written down. */
+    const used = new Set();
+    /** The names these particular sessions last ran under, newest first. */
+    const theirs = [];
+    for (const session of all) {
+        const groups = [session.runGroup, ...session.tasks.flatMap((t) => [t.runGroup, ...(t.attempts ?? []).map((a) => a.runGroup)])];
+        for (const group of groups) {
+            if (!group?.name)
+                continue;
+            used.add(group.name);
+            if (wanted.has(session.id))
+                theirs.push({ name: group.name, at: group.startedAt });
+        }
+    }
+    theirs.sort((a, b) => b.at.localeCompare(a.at));
+    const chosen = all.filter((s) => wanted.has(s.id));
+    const base = stripNumber(theirs[0]?.name ?? '') ||
+        (chosen.length === 1 ? chosen[0].name.trim() : '') ||
+        (about ?? '').trim() ||
+        // Nothing to go on: say what it is rather than leave it blank again.
+        (chosen.length > 0 ? `${chosen.length} sessions` : 'run');
+    if (!used.has(base))
+        return base;
+    for (let n = 2; n < 1000; n += 1) {
+        const candidate = `${base} #${n}`;
+        if (!used.has(candidate))
+            return candidate;
+    }
+    return base;
+}