copilot-operator 0.1.8 → 0.1.9

package/dist/src/orchestrator/taskRunner.js

@@ -13,14 +13,14 @@
 import { createHash } from 'node:crypto';
 import { readFile, mkdir, writeFile, appendFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { CopilotTransport } from '../transport/copilotTransport.js';
+import { createTransport } from '../transport/chatTransport.js';
 import { buildChatName, chatCode, savePointer } from '../transport/chatSession.js';
 import { parseReply, formatErrorMessage, findLikelyDamage, damageGuidance } from '../protocol/parser.js';
 import { resolveDeviations, describeDeviations, mergeDisputes, describeDisputes } from '../protocol/replySchema.js';
 import { buildCoveringMessage, assertSendable } from '../protocol/reporter.js';
 import { runStep } from '../exec/runner.js';
 import { availableShells, detectShells, effectiveShell, preferredShell, refusalForChat, resolveShell, shellNote } from '../exec/shells.js';
-import { runChecks, failureMessage, failureReport, environmentProblemIn, COMMIT_CLEAN_CHECK } from '../exec/checks.js';
+import { runChecks, failureMessage, failureReport, environmentProblemIn, COMMIT_CLEAN_CHECK, CONTENT_CLEAN_CHECK, RUNNER_CHECK_KINDS } from '../exec/checks.js';
 import { activeChecks, suspendDisputed, settleAfterReview, onlyDerivedFailing } from './derivedChecks.js';
 import { workingDirFor, isWorkingDirProblem, workingDirNote } from '../exec/workDir.js';
 import { redactSecrets } from '../exec/redaction.js';
@@ -38,6 +38,10 @@ import { writeReport } from '../exec/reportFile.js';
 import { Pacer } from '../util/pacing.js';
 import { RunLog } from '../log/runLog.js';
 import { composeOpening, READ_ONLY_NOTE } from '../session/compose.js';
+import { enforceScope, scopeMessage, scopeNote } from '../vcs/scope.js';
+import { composeHandoff } from '../session/handoff.js';
+import { ProgressWatch } from './progress.js';
+import { treeFingerprint } from '../vcs/git.js';
 import { mirrorProject, describeMirror } from '../context/projectMirror.js';
 import { projectNameFor, projectTargetDir, removeLegacyFlatMirror } from '../context/desktopMirror.js';
 import { prepareForTask, commitTaskResult, repoDirOf } from '../vcs/taskVcs.js';
@@ -162,7 +166,7 @@ class Sink {
  * holding the profile.
  */
 export async function openBrowser(cfg, bus, transportDir, sessionId) {
-    const transport = new CopilotTransport({
+    const transport = createTransport({
         profileDir: cfg.resolved.profileDir,
         transportDir,
         chatUrl: cfg.copilot.url,
@@ -319,6 +323,13 @@ export async function runTask(transport, session, task, deps) {
     const taskLogPath = log.path('task-log.txt');
     await mkdir(artifactsDir, { recursive: true });
     await mkdir(repliesDir, { recursive: true });
+    /*
+     * Made here, not left to the first step report. The report writer creates it as a side effect, so
+     * a chat that answered "done" before running a single step reached the failed-checks report with
+     * no folder to write it into, and the task ended "failed" on an ENOENT about checks-1.txt instead
+     * of telling the chat which check failed. Found by the end-to-end checks (test/e2e-run.check.ts).
+     */
+    await mkdir(reportsDir, { recursive: true });
     /** The consolidated, human-readable record of the whole task, appended as it happens. */
     const record = async (heading, body) => {
         await appendFile(taskLogPath, `\n${'='.repeat(78)}\n${heading}\n${'='.repeat(78)}\n${body.trimEnd()}\n`, 'utf8');
@@ -347,6 +358,14 @@ export async function runTask(transport, session, task, deps) {
     let disputes = [];
     /** What the runner tells the model in its next message about the reply just processed. */
     let runnerNotes = [];
+    /** Steps the chat sent that were not run, for the handoff at the end. */
+    const notRun = [];
+    /** What went wrong on the way, counted for the register's figures. See `TaskStats`. */
+    const stats = { formatErrors: 0, doneRejected: 0, repeatsRefused: 0, stepsRefused: 0, operatorStops: 0, reviewRejections: 0, scopeReverts: 0 };
+    /** Loops the older guards do not see; see `progress.ts`. */
+    const progress = new ProgressWatch({ noProgress: Math.max(2, cfg.limits.maxNoProgressRounds ?? 3), oscillations: 2 });
+    /** Set when a check round shows no progress; the give-up then ends the task blocked with it. */
+    let noProgressReason = null;
     /**
      * Checks earlier reviews gave with their findings — carried over from every attempt before
      * this one, and grown by this one. See `derivedChecks.ts` for the three rules.
@@ -447,6 +466,11 @@ export async function runTask(transport, session, task, deps) {
             if (reviewChecks.length > 0)
                 t.reviewChecks = reviewChecks;
             t.logFile = 'task-log.txt';
+            t.stats = stats;
+        });
+        // The end in one fixed shape, read off the record just written. See `session/handoff.ts`.
+        await setTask((t) => {
+            t.handoff = composeHandoff(t, notRun);
         });
         sink.event('task-finished', { status, reason, iterations }, `task "${task.title}" ${status}${reason ? `: ${reason}` : ''}`);
         await log.close();
@@ -576,6 +600,15 @@ export async function runTask(transport, session, task, deps) {
                 ? `not active: ${prepared.vcs.problem}`
                 : `branch ${prepared.vcs.branch}, from ${prepared.vcs.baseCommit ?? '(no commits yet)'}`);
         }
+        /*
+         * The paths this task may change. Enforced only on a branch of the task's own, which is what
+         * makes "put back" safe: the tree was clean when the branch was made, so every change in it
+         * is the task's, and the starting commit is what a change goes back to.
+         */
+        const scope = task.scope ?? [];
+        const scopeEnforced = scope.length > 0 && !!prepared.vcs.branch && !prepared.vcs.problem && !!prepared.vcs.baseCommit;
+        /** The working tree's fingerprint, when the task is on a branch of its own; null otherwise. */
+        const treeNow = async () => prepared.vcs.branch && !prepared.vcs.problem && prepared.vcs.baseCommit ? await treeFingerprint(repoDirOf(session)).catch(() => null) : null;
         // --- project mirror, attached to the first message of the task ---------------------
         let mirrorFiles = [];
         if (session.mirror.enabled && session.mirror.rootDir) {
@@ -630,6 +663,7 @@ export async function runTask(transport, session, task, deps) {
             workDirNote: workingDirNote(work),
             vcsNote: prepared.note,
             readOnlyNote: task.readOnly ? READ_ONLY_NOTE : undefined,
+            scopeNote: scopeNote(scope, scopeEnforced),
             shellNote: shellNote(shells, defaultShell),
         });
         await setTask((t) => {
@@ -694,7 +728,8 @@ export async function runTask(transport, session, task, deps) {
          * task refusing to start over it.
          */
         const willCommit = !!(session.vcs?.enabled && session.vcs.commitOnFinish && repoDirOf(session));
-        let generatedPointedOut = false;
+        /** The runner's own checks that have been pointed out to the chat once already. */
+        const pointedOut = new Set();
         /**
          * Whether "done" is accepted, decided by the operator's checks rather than by the reply.
          *
@@ -705,7 +740,7 @@ export async function runTask(transport, session, task, deps) {
          * happened, and a task cannot be trusted to answer that about itself.
          */
         const gateOnChecks = async () => {
-            const checks = [...(task.checks ?? []), ...activeChecks(reviewChecks), ...(willCommit ? [COMMIT_CLEAN_CHECK] : [])];
+            const checks = [...(task.checks ?? []), ...activeChecks(reviewChecks), ...(willCommit ? [COMMIT_CLEAN_CHECK, CONTENT_CLEAN_CHECK] : [])];
             if (checks.length === 0)
                 return 'accept';
             // Counted only once the round turns out to have been a real attempt. A round that died of
@@ -726,19 +761,26 @@ export async function runTask(transport, session, task, deps) {
                 deny: (command, shell, cwd) => checkCommandRefusal(command, shell, cfg.execution, { roots: confinement.roots, cwd }),
                 roots: confinement.roots,
                 repoDir: willCommit ? repoDirOf(session) : undefined,
+                baseCommit: prepared.vcs.baseCommit,
                 // The same shell a step that named none is given, so the gate and the work it judges
                 // cannot have been read by different interpreters.
                 defaultShell,
             }));
+            /*
+             * The runner's own checks are advice given once, not a gate: a second "done" with the finding
+             * still there is committed and the finding stays on the task. Refusing instead would leave the
+             * tree dirty and the next task unable to start. Each check is pointed out once on its own, so a
+             * content problem found after the paths were settled still gets its one mention.
+             */
             for (const o of outcomes) {
-                if (o.check.expect !== 'commit-clean' || o.passed)
+                if (!RUNNER_CHECK_KINDS.has(o.check.expect) || o.passed)
                     continue;
-                if (generatedPointedOut) {
+                if (pointedOut.has(o.check.expect)) {
                     o.passed = true;
-                    o.detail = `still there after being pointed out once; committed and marked as suspicious on the task — ${o.detail}`;
+                    o.detail = `still there after being pointed out once; committed and kept on the task — ${o.detail}`;
                 }
                 else {
-                    generatedPointedOut = true;
+                    pointedOut.add(o.check.expect);
                 }
             }
             await setTask((t) => {
@@ -769,8 +811,17 @@ export async function runTask(transport, session, task, deps) {
                 sink.event('checks-passed', { count: outcomes.length }, `all ${outcomes.length} check(s) passed`);
                 return 'accept';
             }
+            stats.doneRejected += 1;
             if (deps.signal?.aborted)
                 return 'give-up';
+            // The same failures as last time, and not a file changed since they were reported.
+            const stuck = progress.afterFailedChecks(await treeNow(), failed.map((o) => ({ name: o.check.name, detail: o.detail })));
+            if (stuck) {
+                noProgressReason = stuck;
+                stats.stoppedFor = 'no-progress';
+                sink.event('no-progress', { kind: 'checks' }, stuck, 'warn');
+                return 'give-up';
+            }
             if (checkRounds > maxCheckRounds) {
                 /*
                  * Only checks from earlier reviews are failing. A reviewer's check is outranked by the
@@ -941,6 +992,8 @@ export async function runTask(transport, session, task, deps) {
              * task; the ones suspended by a dispute or by spent rounds come back if the finding was
              * raised again, and go if it was not.
              */
+            if (outcome.verdict === 'fail')
+                stats.reviewRejections += 1;
             if (outcome.verdict === 'pass' || outcome.verdict === 'fail') {
                 for (const d of outcome.derivedChecks ?? []) {
                     reviewChecks = [...reviewChecks, { check: d.check, findingId: d.findingId, what: d.what, where: d.where, round: reviewRounds, attempt, state: 'active' }];
@@ -1100,6 +1153,7 @@ export async function runTask(transport, session, task, deps) {
             });
             if (!parsed.ok) {
                 formatRetries += 1;
+                stats.formatErrors += 1;
                 sink.event('format-error', { reason: parsed.reason, detail: parsed.detail }, `reply did not match the contract (${parsed.reason}), retry ${formatRetries}/${cfg.limits.maxFormatRetries}`, 'warn');
                 if (formatRetries > cfg.limits.maxFormatRetries) {
                     await transport.dumpFailure(log.path('failures'), 'format-error');
@@ -1187,6 +1241,8 @@ export async function runTask(transport, session, task, deps) {
                     return await finish('failed', shellProblemReason(environmentProblem), reply.summary, lastMarkdown);
                 }
                 if (verdict === 'give-up') {
+                    if (noProgressReason)
+                        return await finish('blocked', noProgressReason, reply.summary, lastMarkdown);
                     return await finish('failed', checksFailedReason(lastOutcomes), reply.summary, lastMarkdown);
                 }
                 if (verdict === 'accept') {
@@ -1246,6 +1302,7 @@ export async function runTask(transport, session, task, deps) {
                 const ran = seen.get(key)?.sameInARow ?? 0;
                 if (ran >= maxCommandRepeats) {
                     repeatsRefused += 1;
+                    stats.repeatsRefused += 1;
                     sink.event('step-repeated', { id: step.id, count: ran, limit: maxCommandRepeats }, `step ${step.id} refused: already run ${ran} time(s) in this task with the same result`, 'warn');
                     results.push(refusedResult(step, repeatRefusal(ran, maxCommandRepeats)));
                     continue;
@@ -1312,11 +1369,42 @@ export async function runTask(transport, session, task, deps) {
                 }
                 await pacer.settle();
             }
+            for (const r of results) {
+                if (r.outcome !== 'refused' && r.outcome !== 'aborted')
+                    continue;
+                if (r.outcome === 'refused')
+                    stats.stepsRefused += 1;
+                else
+                    stats.operatorStops += 1;
+                const why = (r.stderr.split('\n')[0] ?? '').replace(/^\[policy\] step not executed: /, '').trim();
+                notRun.push({ command: r.command.slice(0, 200), why: why.slice(0, 300) || r.outcome });
+            }
             // Ended before the report is written and sent: there is nobody to send it to who could
             // do anything with it, and the reason on the task says what to install or set instead.
             if (environmentProblem) {
                 return await finish('failed', shellProblemReason(environmentProblem), reply.summary, lastMarkdown);
             }
+            /*
+             * The task's scope, as a rule rather than a sentence (see `vcs/scope.ts`): whatever this round
+             * changed outside it is put back now, before the chat reads the results and builds on them,
+             * and the chat is told in the same message.
+             */
+            if (scopeEnforced) {
+                const check = await enforceScope(repoDirOf(session), scope).catch((e) => ({
+                    outside: [],
+                    reverted: [],
+                    failed: [{ path: '(the working tree)', why: e.message }],
+                }));
+                if (check.outside.length > 0 || check.failed.length > 0) {
+                    sink.event('scope-reverted', { iteration: iterations, reverted: check.reverted, failed: check.failed }, `outside the task's scope, put back: ${check.reverted.join(', ') || '(none)'}` +
+                        (check.failed.length > 0 ? `; could not be put back: ${check.failed.map((f) => f.path).join(', ')}` : ''), 'warn');
+                    runnerNotes.push(scopeMessage(check, scope));
+                    stats.scopeReverts += check.reverted.length;
+                    await setTask((t) => {
+                        t.scopeReverted = [...new Set([...(t.scopeReverted ?? []), ...check.reverted])];
+                    });
+                }
+            }
             // --- report back ---------------------------------------------------------------
             const report = await writeReport(results, {
                 runId,
@@ -1336,6 +1424,14 @@ export async function runTask(transport, session, task, deps) {
             }
             if (aborted)
                 return await finish('aborted', 'the operator aborted the task', undefined, lastMarkdown);
+            // A loop in which every round looks new: see `progress.ts`. After the report is written, so
+            // the evidence the diagnosis points at is on disk.
+            const stuck = progress.afterRound(await treeNow(), results);
+            if (stuck) {
+                stats.stoppedFor = 'no-progress';
+                sink.event('no-progress', { kind: 'rounds', iteration: iterations }, stuck, 'warn');
+                return await finish('blocked', stuck, reply.summary, lastMarkdown);
+            }
             /*
              * Nothing this iteration did anything.
              *
@@ -1436,6 +1532,8 @@ export async function runTask(transport, session, task, deps) {
                     return await finish('failed', shellProblemReason(environmentProblem), reply.summary, lastMarkdown);
                 }
                 if (verdict === 'give-up') {
+                    if (noProgressReason)
+                        return await finish('blocked', noProgressReason, reply.summary, lastMarkdown);
                     return await finish('failed', checksFailedReason(lastOutcomes), reply.summary, lastMarkdown);
                 }
                 if (verdict === 'accept') {
@@ -1562,8 +1660,10 @@ export async function runSession(sessionId, deps) {
                     s.chat = undefined;
                     s.contractSent = false;
                     const again = s.tasks.find((x) => x.id === task.id);
-                    if (again)
+                    if (again) {
                         again.autoRetries = (again.autoRetries ?? 0) + 1;
+                        again.freshRetry = true;
+                    }
                 });
                 await chat.newChat();
                 /*

package/dist/src/plan/brief.js

@@ -316,6 +316,7 @@ const FIELD_ROWS_EN = [
     ],
     ['review', 'task', 'no', 'Set to `false` to skip the review for one task. Absent means the session decides.'],
     ['readOnly', 'task', 'no', '`true` for a task that must not change files — an audit, a smoke test, a report. The runner fails it if the tree changed, and still commits the change on its branch so nothing is lost.'],
+    ['scope', 'task', 'no', 'The paths the task may change: files, folders (`tests/e2e/`) or `*`/`**` patterns. With version control on, the runner puts back any change outside them. Give it when the task is about one suite or module.'],
     ['mirror', 'session', 'no, but ask', 'Whether project files are copied and attached to the first message as context, and which: root, directories in and out, gitignore, env files. Off when left out.'],
     ['tasks', 'session', 'yes', 'At least one, in the order they must run.'],
     ['title', 'task', 'yes', '3 to 120 characters. Short, latin, hyphenated.'],
@@ -380,6 +381,7 @@ const FIELD_ROWS_BG = [
     ],
     ['review', 'задача', 'не', 'Сложи `false`, за да се пропусне рецензията само за тази задача. Липсата значи каквото казва сесията.'],
     ['readOnly', 'задача', 'не', '`true` за задача, която не бива да променя файлове — одит, smoke тест, доклад. Runner-ът я проваля, ако дървото е променено, и пак комитва промяната на клона ѝ, за да не се губи нищо.'],
+    ['scope', 'задача', 'не', 'Пътищата, които задачата може да променя: файлове, папки (`tests/e2e/`) или шаблони с `*`/`**`. При включен контрол на версиите runner-ът връща всяка промяна извън тях. Давай го, когато задачата е за един suite или модул.'],
     ['mirror', 'сесия', 'не, но питай', 'Дали файлове от проекта се копират и прикачат към първото съобщение като контекст, и кои: корен, директории вътре и вън, gitignore, env файлове. Изключено, когато липсва.'],
     ['tasks', 'сесия', 'да', 'Поне една, в реда, в който трябва да се изпълнят.'],
     ['title', 'задача', 'да', 'От 3 до 120 знака. Кратко, латиница, с тирета.'],

package/dist/src/plan/importPlan.js

@@ -194,6 +194,7 @@ persona = '') {
                 checks: task.checks,
                 reviewEnabled: task.review,
                 readOnly: task.readOnly || undefined,
+                scope: task.scope.length > 0 ? task.scope : undefined,
             });
             titles.push(added.title);
         }

package/dist/src/plan/schema.js

@@ -207,6 +207,13 @@ const TaskInput = z.object({
      * branch so nothing is lost and the next task starts clean.
      */
     readOnly: z.boolean().default(false),
+    /**
+     * The paths this task may change, repository-relative: a file, a folder (`tests/e2e/`), or a
+     * pattern with `*` and `**`. Absent or empty means anywhere in the project. Enforced by the runner
+     * after every round of steps when version control is on — a change outside is put back and the
+     * chat told — which a sentence in the prompt cannot be. See `vcs/scope.ts`.
+     */
+    scope: z.array(z.string().trim().min(1, 'A scope entry needs a path or a pattern.')).default([]),
     /**
      * What earlier attempts of this task were asked, written by the plan export for a task that has
      * been run more than once (`earlierPlans` in `session/exports.ts`). History, not instruction:

package/dist/src/plan/systemGuide.js

@@ -278,6 +278,22 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'Puts the whole brief on the clipboard; paste it into a fresh chat conversation.',
                         doesBg: 'Слага цялото задание в клипборда; поставете го в нов разговор с чат модел.',
                     },
+                    {
+                        key: 'plan.saveBrief',
+                        kind: 'button',
+                        en: 'Save the brief as a file',
+                        bg: 'Запази заданието като файл',
+                        doesEn: 'Saves the brief as a .txt to attach to a fresh chat; the way when it is over about 116 000 characters.',
+                        doesBg: 'Запазва заданието като .txt за прикачване в нов разговор; начинът, когато е над около 116 000 знака.',
+                    },
+                    {
+                        key: 'plan.copyBriefNote',
+                        kind: 'button',
+                        en: 'Copy the message for the file',
+                        bg: 'Копирай съобщението към файла',
+                        doesEn: 'Only when the brief is too long to paste: the one line to send with the attached file.',
+                        doesBg: 'Само когато заданието е твърде дълго за поставяне: едното изречение, което се праща с прикачения файл.',
+                    },
                     {
                         key: 'plan.softwarePart',
                         kind: 'disclosure',
@@ -2571,6 +2587,13 @@ export const SYSTEM_GUIDE = [
                     },
                 ],
             },
+            {
+                headingKey: 'metrics.title',
+                en: 'How the bot is doing',
+                bg: 'Как се справя ботът',
+                // A table of figures at the foot of the register, read-only; the heading says what it is.
+                controls: [],
+            },
         ],
     },
     {
@@ -3075,29 +3098,45 @@ export const SYSTEM_GUIDE = [
                 en: 'Text size',
                 bg: 'Размер на текста',
                 controls: [
+                    {
+                        key: 'ap.sizeSmall',
+                        kind: 'button',
+                        en: 'Small',
+                        bg: 'Малък',
+                        doesEn: 'One step below normal.',
+                        doesBg: 'Една степен под нормалния.',
+                    },
                     {
                         key: 'ap.sizeNormal',
                         kind: 'button',
                         en: 'Normal',
                         bg: 'Нормален',
-                        doesEn: 'Normal text size.',
-                        doesBg: 'Нормален размер на текста.',
+                        doesEn: 'Normal size.',
+                        doesBg: 'Нормален размер.',
                     },
                     {
                         key: 'ap.sizeLarge',
                         kind: 'button',
                         en: 'Large',
                         bg: 'Голям',
-                        doesEn: 'Larger text.',
-                        doesBg: 'По-голям текст.',
+                        doesEn: 'One step above normal.',
+                        doesBg: 'Една степен над нормалния.',
                     },
                     {
                         key: 'ap.sizeHuge',
                         kind: 'button',
+                        en: 'Larger',
+                        bg: 'По-голям',
+                        doesEn: 'Two steps above normal.',
+                        doesBg: 'Две степени над нормалния.',
+                    },
+                    {
+                        key: 'ap.sizeGiant',
+                        kind: 'button',
                         en: 'Largest',
                         bg: 'Най-голям',
-                        doesEn: 'The largest text.',
-                        doesBg: 'Най-големият текст.',
+                        doesEn: 'Three steps above normal.',
+                        doesBg: 'Три степени над нормалния.',
                     },
                 ],
             },

package/dist/src/session/compose.js

@@ -11,7 +11,7 @@ const TASK_HEADER = '## Task';
  * and a note that is empty simply leaves nothing behind.
  */
 function runnerBlock(input) {
-    const notes = [input.workDirNote, input.readOnlyNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
+    const notes = [input.workDirNote, input.readOnlyNote, input.scopeNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
     return notes.length > 0 ? `${notes.join('\n\n')}\n\n` : '';
 }
 /**

package/dist/src/session/exports.js

@@ -168,6 +168,8 @@ export function buildPlanExport(scope) {
                         task.review = false;
                     if (t.readOnly)
                         task.readOnly = true;
+                    if (t.scope && t.scope.length > 0)
+                        task.scope = [...t.scope];
                     const earlier = earlierPlans(t, level2);
                     if (earlier.length > 0)
                         task.earlierAttempts = earlier;
@@ -394,6 +396,9 @@ async function domainTask(session, task, runsDir) {
             title: task.title,
             attempt: task.attempt ?? 1,
             readOnly: task.readOnly ?? false,
+            scope: task.scope ?? [],
+            scopeReverted: task.scopeReverted ?? [],
+            handoff: task.handoff ?? null,
             prompt: p.prompt,
             expected: p.expected,
             level2: task.level2,

package/dist/src/session/handoff.js

@@ -0,0 +1,42 @@
+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') : [];
+    const vcs = task.vcs ?? {};
+    const knownIssues = [
+        ...failedChecks.map((c) => `check failed: ${c.name} — ${c.detail}`),
+        ...openFindings.map((f) => `review finding${f.id ? ` ${f.id}` : ''}: ${f.what}${f.where ? ` (${f.where})` : ''}`),
+        ...(task.checkResults ?? [])
+            .filter((c) => c.passed && /still there after being pointed out once/.test(c.detail))
+            .map((c) => `committed with a finding left in place: ${c.name}`),
+        ...(vcs.suspicious ?? []).map((s) => `committed although it looks like ${s.reason}: ${s.path}`),
+        ...(vcs.foreignCommits ?? []).map((c) => `a commit on the branch the runner did not make: ${c}`),
+        ...(task.scopeReverted?.length ? [`put back because outside the task's scope: ${task.scopeReverted.join(', ')}`] : []),
+        ...(task.deviations ?? []).map((d) => `did not follow "${d.instruction}" as written: ${d.did}`),
+    ];
+    const manual = [];
+    if (vcs.problem)
+        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 (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)
+        manual.push(`${openFindings.length} review finding(s) are open`);
+    if ((vcs.suspicious?.length ?? 0) > 0 || (vcs.foreignCommits?.length ?? 0) > 0)
+        manual.push('look at the committed files and commits listed above');
+    return {
+        outcome: { status: task.status, ...(task.reason ? { reason: task.reason } : {}) },
+        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 } } : {}),
+        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 } : {}) },
+        manual,
+        notExecuted: notRun.slice(0, 30).map((n) => `${n.command} — ${n.why}`),
+    };
+}

package/dist/src/session/metrics.js

@@ -0,0 +1,95 @@
+const ENDED = ['done', 'failed', 'blocked', 'aborted', 'limit-reached'];
+function attemptsOf(task) {
+    const all = [...(task.attempts ?? [])];
+    if (ENDED.includes(task.status))
+        all.push(task);
+    return all.filter((a) => ENDED.includes(a.status));
+}
+function modelOf(session) {
+    return (session.modelInUse ?? '').trim() || (session.model ?? '').trim() || '(the chat default)';
+}
+function row(group, tasks) {
+    const r = {
+        group,
+        tasks: 0,
+        attempts: 0,
+        firstPass: { n: 0, of: 0 },
+        doneInTheEnd: { n: 0, of: 0 },
+        ended: {},
+        freshRetries: 0,
+        manualInterventions: 0,
+        falseCompletion: { n: 0, of: 0 },
+        reviewRejection: { n: 0, of: 0 },
+        repeatedCommands: { n: 0, of: 0 },
+        scopeViolation: { n: 0, of: 0 },
+        noProgress: { n: 0, of: 0 },
+        unrelatedDiff: { n: 0, of: 0 },
+        resumed: { n: 0, of: 0 },
+        withStats: 0,
+    };
+    for (const task of tasks) {
+        const list = attemptsOf(task);
+        if (list.length === 0)
+            continue;
+        r.tasks += 1;
+        r.attempts += list.length;
+        r.firstPass.of += 1;
+        if (list[0].status === 'done')
+            r.firstPass.n += 1;
+        const last = list[list.length - 1];
+        r.doneInTheEnd.of += 1;
+        if (last.status === 'done')
+            r.doneInTheEnd.n += 1;
+        r.ended[last.status] = (r.ended[last.status] ?? 0) + 1;
+        list.forEach((a, i) => {
+            if (a.freshRetry)
+                r.freshRetries += 1;
+            else if (i > 0)
+                r.manualInterventions += 1;
+            r.unrelatedDiff.of += 1;
+            if ((a.vcs?.suspicious?.length ?? 0) > 0 || (a.vcs?.foreignCommits?.length ?? 0) > 0)
+                r.unrelatedDiff.n += 1;
+            if ((a.scope?.length ?? 0) > 0) {
+                r.scopeViolation.of += 1;
+                if ((a.scopeReverted?.length ?? 0) > 0)
+                    r.scopeViolation.n += 1;
+            }
+            if (a.continuing) {
+                r.resumed.of += 1;
+                if (a.status === 'done')
+                    r.resumed.n += 1;
+            }
+            if (a.review && a.review.verdict !== 'skipped') {
+                r.reviewRejection.of += 1;
+                if ((a.stats?.reviewRejections ?? 0) > 0 || a.review.verdict === 'fail' || (a.review.rounds ?? 0) > 1)
+                    r.reviewRejection.n += 1;
+            }
+            if (!a.stats)
+                return;
+            r.withStats += 1;
+            r.manualInterventions += a.stats.operatorStops;
+            r.falseCompletion.of += 1;
+            if (a.stats.doneRejected > 0)
+                r.falseCompletion.n += 1;
+            r.repeatedCommands.of += 1;
+            if (a.stats.repeatsRefused > 0)
+                r.repeatedCommands.n += 1;
+            r.noProgress.of += 1;
+            if (a.stats.stoppedFor === 'no-progress')
+                r.noProgress.n += 1;
+        });
+    }
+    return r;
+}
+/** All tasks, then one row per model the sessions ran on, busiest first. */
+export function computeMetrics(sessions, now = new Date()) {
+    const all = sessions.flatMap((s) => s.tasks);
+    const byModel = new Map();
+    for (const s of sessions)
+        byModel.set(modelOf(s), [...(byModel.get(modelOf(s)) ?? []), ...s.tasks]);
+    const models = [...byModel.entries()]
+        .map(([group, tasks]) => row(group, tasks))
+        .filter((r) => r.tasks > 0)
+        .sort((a, b) => b.tasks - a.tasks);
+    return { rows: [row('all', all), ...(models.length > 1 ? models : [])], computedAt: now.toISOString() };
+}

package/dist/src/session/store.js

@@ -251,6 +251,8 @@ export class SessionStore {
             ...(input.reviewEnabled === false ? { reviewEnabled: false } : {}),
             // Only `true` is worth storing: a task may change files unless a plan said otherwise.
             ...(input.readOnly === true ? { readOnly: true } : {}),
+            // Stored only when it limits something: absent means anywhere, as before scopes existed.
+            ...((input.scope ?? []).filter((p) => p.trim()).length > 0 ? { scope: (input.scope ?? []).map((p) => p.trim()).filter(Boolean) } : {}),
         };
         await this.updateSession(sessionId, (s) => {
             s.tasks.push(task);
@@ -352,6 +354,12 @@ export class SessionStore {
                     checks: t.checks,
                     vcsPlan: t.vcsPlan,
                     review: t.review,
+                    stats: t.stats,
+                    continuing: t.continuing,
+                    buildsOn: t.buildsOn,
+                    freshRetry: t.freshRetry,
+                    scope: t.scope,
+                    scopeReverted: t.scopeReverted,
                     vcs: t.vcs,
                 },
             ];
@@ -390,6 +398,12 @@ export class SessionStore {
             // the one thing a new attempt should inherit.
             t.deviations = undefined;
             t.disputes = undefined;
+            // Counts, the ending and what was put back belong to the attempt above too. A fresh-chat retry
+            // marks itself again after this, in the runner.
+            t.stats = undefined;
+            t.handoff = undefined;
+            t.scopeReverted = undefined;
+            t.freshRetry = 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/transport/chatTransport.js

@@ -0,0 +1,32 @@
+/**
+ * What the runner, the reviewer and the API need from a chat, and where that chat comes from.
+ *
+ * Everything that talks to Copilot goes through `CopilotTransport`, which drives a real Edge window
+ * signed in to Microsoft 365. That is the product, and it is also why nothing above the transport
+ * could be tested end to end: every run opened a browser, signed in and spent the operator's hourly
+ * message allowance. The loop itself — send, read the reply, run the steps, report back, stop at the
+ * limit, carry on after an interruption, commit on the right branch — never touches the page, only
+ * these few methods. So the rest of the code asks for a `ChatTransport` and gets one from
+ * `createTransport`, and the automated checks put a scripted chat in its place (test/support/fakeChat.ts)
+ * that answers from a script and never opens a window.
+ *
+ * The type is a `Pick` of the real class rather than an interface written out by hand, so the two
+ * cannot drift apart: a method that changes its signature in `CopilotTransport` changes it here, and
+ * the scripted chat stops compiling instead of passing checks against a shape the product no longer has.
+ *
+ * Deliberately, nothing outside the code can swap the chat: no environment variable, no setting, no
+ * command-line flag. A scripted chat hands the runner steps to execute, and a switch that a file or
+ * an environment could flip would be a way to make the bot run commands nobody reviewed. Only code
+ * running in this process — a check script — can call `setTransportFactory`.
+ */
+import { CopilotTransport } 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. */
+export function createTransport(opts) {
+    return factory(opts);
+}
+/** For checks only: every chat opened from now on comes from `f`. `null` puts the real one back. */
+export function setTransportFactory(f) {
+    factory = f ?? realChat;
+}