copilot-operator 0.1.7 → 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 знака. Кратко, латиница, с тирета.'],
@@ -726,7 +728,7 @@ in those words, every time:
   1. On \`/history\`, in the **"Flow"** view, press **"Fix the prompt and queue it again"** on that row.
   2. Replace the text with the one above and press **"Save and queue again"**.
   3. Under **"What is next"**, press **"Continue: run the {n} queued task(s) in {s} session(s)"**
-     (it reads **"Continue: run {f} failed and {n} queued task(s) in {s} session(s)"** when a chain
+     (it reads **"Continue: run {f} unfinished and {n} queued task(s) in {s} session(s)"** when a chain
      has a failed task).
   4. In **"Before it continues"** every task is ticked. To run only the fixed one, press
      **"only this one"** beside it.
@@ -736,7 +738,7 @@ in those words, every time:
   A check that is wrong rather than a prompt that is wrong is edited instead: **"Edit"** on the
   task card, then **"What it checks"**, **"Must be"** and **"Command"** under **"Checks"**, then
   **"Save and queue it again"** — which, like every "queue" button, starts nothing by itself.
-  A task that ended **limit-reached** is carried on in its own chat instead: **"Continue in the
+  A task that ended **limit-reached**, or **aborted** because the bot stopped under it, is carried on in its own chat instead: **"Continue in the
   same chat"** on its card on the session page, then **"Run {n} task(s)"** at the top of that page.
   When a failure shows up while the run is still going, **"Pause after this task"** holds the rest
   while you work it out.
@@ -887,7 +889,7 @@ const PHASE3_BG = `
   1. В \`/history\`, в изгледа **„Поток“**, натисни **„Поправи prompt-а и върни в опашката“** на този ред.
   2. Замени текста с горния и натисни **„Запази и върни в опашката“**.
   3. Под **„Какво следва“** натисни **„Продължи: пусни {n} чакащи задачи в {s} сесии“** (пише
-     **„Продължи: пусни {f} провалили се и {n} чакащи задачи в {s} сесии“**, когато във верига има
+     **„Продължи: пусни {f} недовършени и {n} чакащи задачи в {s} сесии“**, когато във верига има
      провалена задача).
   4. В **„Преди да продължи“** всички задачи са отметнати. За да пуснеш само поправената, натисни
      **„само тази“** до нея.
@@ -897,7 +899,7 @@ const PHASE3_BG = `
   Когато е сгрешена проверката, а не prompt-ът, се редактира друго: **„Редактирай“** на картата
   на задачата, после **„Какво проверява“**, **„Трябва“** и **„Команда“** под **„Проверки“**, после
   **„Запази и върни в опашката“** — който, като всеки бутон за връщане в опашката, сам не пуска нищо.
-  Задача, завършила с **limit-reached**, продължава в собствения си чат: **„Продължи в същия чат“**
+  Задача, завършила с **limit-reached** или **aborted**, защото ботът е спрял под нея, продължава в собствения си чат: **„Продължи в същия чат“**
   на картата ѝ на страницата на сесията, после **„Пусни {n} задача(и)“** горе на същата страница.
   Когато провал се покаже, докато пускането още върви, **„Пауза след тази задача“** задържа
   останалото, докато го разбереш.

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',
@@ -1442,8 +1458,8 @@ export const SYSTEM_GUIDE = [
                         kind: 'button',
                         en: 'Continue in the same chat',
                         bg: 'Продължи в същия чат',
-                        doesEn: 'Only on a task stopped at its limit: queues it to carry on in the same chat and branch with a fresh count. Then press "Run {n} task(s)".',
-                        doesBg: 'Само на задача, спряла на лимита: нарежда я да продължи в същия чат и клон с нов брояч. После натиснете „Пусни {n} задача(и)“.',
+                        doesEn: 'On a task that stopped before it finished (its limit, the bot stopping, the operator): queues it to carry on in the same chat and branch. Then "Run {n} task(s)".',
+                        doesBg: 'На задача, спряла преди да приключи (лимит, спрял бот, оператор): нарежда я да продължи в същия чат и клон. После „Пусни {n} задача(и)“.',
                     },
                     {
                         key: 'task.rerun',
@@ -2316,6 +2332,14 @@ export const SYSTEM_GUIDE = [
                 en: 'What is next',
                 bg: 'Какво следва',
                 controls: [
+                    {
+                        key: 'reg.interruptedTitle',
+                        kind: 'note',
+                        en: 'The bot stopped in the middle of the work.',
+                        bg: 'Ботът спря посред работата.',
+                        doesEn: 'After the bot stopped under a run (power, Ctrl+C, a crash): the stopped tasks\' work is kept, and "Continue" carries them on where they stopped.',
+                        doesBg: 'След като ботът е спрял посред пускане (ток, Ctrl+C, срив): свършеното е запазено, а „Продължи“ продължава спрелите задачи оттам, където са спрели.',
+                    },
                     {
                         key: 'batch.pause',
                         kind: 'button',
@@ -2351,8 +2375,8 @@ export const SYSTEM_GUIDE = [
                     {
                         key: 'reg.continueWithFailed',
                         kind: 'button',
-                        en: 'Continue: run {f} failed and {n} queued task(s) in {s} session(s)',
-                        bg: 'Продължи: пусни {f} провалили се и {n} чакащи задачи в {s} сесии',
+                        en: 'Continue: run {f} unfinished and {n} queued task(s) in {s} session(s)',
+                        bg: 'Продължи: пусни {f} недовършени и {n} чакащи задачи в {s} сесии',
                         doesEn: 'The same button when a failed task of a chained session would go back into the queue with the queued ones.',
                         doesBg: 'Същият бутон, когато провалена задача от сесия-верига би се върнала в опашката заедно с чакащите.',
                     },
@@ -2417,8 +2441,8 @@ export const SYSTEM_GUIDE = [
                         kind: 'button',
                         en: 'Continue without asking',
                         bg: 'Продължи без да пита',
-                        doesEn: 'Starts exactly the ticked tasks and runs every command without asking (asks "are you sure" first unless Settings say otherwise). Ticked failed tasks start afresh.',
-                        doesBg: 'Пуска точно отметнатите задачи и изпълнява всяка команда без питане (първо пита „сигурен ли си“, освен ако Настройките казват друго). Отметнатите провалени задачи тръгват отначало.',
+                        doesEn: 'Starts exactly the ticked tasks without asking (after "are you sure" unless Settings say otherwise). Stopped ones (aborted, limit reached) continue where they stopped; failed or blocked ones start afresh.',
+                        doesBg: 'Пуска точно отметнатите задачи без питане (след „сигурен ли си“, освен ако Настройките казват друго). Спрелите (прекратени, с лимит) продължават откъдето спряха; провалените и блокираните тръгват отначало.',
                     },
                     {
                         key: 'reg.continueGo',
@@ -2563,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: [],
+            },
         ],
     },
     {
@@ -2789,6 +2820,14 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'How many minutes one task may run (default 240) before it stops as limit reached; saved as you type.',
                         doesBg: 'Колко минути може да върви една задача (по подразбиране 240), преди да спре като достигнат лимит; запазва се, докато пишете.',
                     },
+                    {
+                        key: 'exec.replyTimeout',
+                        kind: 'field',
+                        en: 'How long to wait for a reply from the chat',
+                        bg: 'Колко да се чака отговор от чата',
+                        doesEn: 'Seconds to wait for a chat reply (default 900); a reply not finished by then fails the task with "Copilot did not finish a reply within …".',
+                        doesBg: 'Секунди чакане на отговор от чата (по подразбиране 900); незавършен дотогава отговор проваля задачата с „Copilot did not finish a reply within …“.',
+                    },
                     {
                         key: 'exec.retryBlocked',
                         kind: 'field',
@@ -3059,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

@@ -1,17 +1,4 @@
-/**
- * Builds the messages that open a task in the chat.
- *
- * Two shapes, because a conversation is opened once and then reused:
- *
- *   first task in a session   level 1 (the contract, sent on its own and acknowledged),
- *                             then level 2 plus the task in one message
- *   later tasks               a short reminder that the contract still applies,
- *                             then level 2 plus the task
- *
- * Level 2 is always sent with the task, even when it did not change, because it is cheap
- * and it keeps each task self-contained in the transcript. The priority of level 1 over
- * level 2 is stated inside level 1 itself; the composition only makes the boundary visible.
- */
+import { describeInterruption } from './interruption.js';
 const LEVEL2_HEADER = '## Project instructions (level 2)';
 const TASK_HEADER = '## Task';
 /**
@@ -24,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` : '';
 }
 /**
@@ -50,6 +37,25 @@ function level2Block(level2) {
  * The messages to send, in order. The last one is the one whose reply starts the loop.
  * `firstMessage` is what the UI shows as "the prompt that opened this task".
  */
+/**
+ * Why the attempt being continued stopped, and where it was, in the words the chat is sent. The
+ * chat was mid-conversation when it stopped, so what it most needs is to know that nothing it did
+ * failed, that the files are as its work left them, and — after the bot stopped under it — which of
+ * the steps it had just asked for actually ran.
+ */
+function whyItStopped(c) {
+    if (c.how === 'interrupted') {
+        const where = c.interruption ? `\n\n${describeInterruption(c.interruption)}\n\n` : ' ';
+        return ('The runner stopped unexpectedly while this task was in progress — the program was closed, the machine went off or it ' +
+            'crashed; nothing you did failed — and it has now started again. The files are as your work left them, and what had ' +
+            `changed is committed on this branch.${where}`.trimEnd());
+    }
+    if (c.how === 'stopped') {
+        return 'It was stopped by the operator before it finished — not because anything failed. The files are as you left them.';
+    }
+    const why = c.stoppedBecause ? ` (${c.stoppedBecause})` : '';
+    return `It stopped because the runner's limit was reached${why} — not because anything failed. The files are as you left them.`;
+}
 export function composeOpening(input) {
     const taskBlock = `${TASK_HEADER} ${input.taskNumber}: ${input.taskTitle.trim() || 'untitled'}\n\n${input.prompt.trim()}`;
     /*
@@ -58,18 +64,17 @@ export function composeOpening(input) {
      * conversation was lost does the task go out in full, with a line saying it is a continuation.
      */
     if (input.continuing && input.contractAlreadySent) {
-        const why = input.continuing.stoppedBecause ? ` (${input.continuing.stoppedBecause})` : '';
         const message = `Continue task ${input.taskNumber}: ${input.taskTitle.trim() || 'untitled'}, in this same conversation. ` +
-            `It stopped because the runner's limit was reached${why} — not because anything failed. ` +
-            `The files are as you left them. Do not start over and do not repeat work that is done: start from ` +
+            `${whyItStopped(input.continuing)} ` +
+            `Do not start over and do not repeat work that is done: start from ` +
             `your plan, say in \`notes\` which stages are done and which one you are on, and carry on. ` +
             `The assignment is the one you were given above; it has not changed. Step numbering restarts at 1.\n\n` +
             `${runnerBlock(input)}`.trimEnd();
         return { messages: [message], firstMessage: message };
     }
     const continuationLine = input.continuing
-        ? `\n\nThis continues an earlier attempt at this task that stopped at the runner's limit. The files are as ` +
-            `that attempt left them: look at what is already done before changing anything, and carry on from there.`
+        ? `\n\nThis continues an earlier attempt at this task. ${whyItStopped(input.continuing)} ` +
+            `Look at what is already done before changing anything, and carry on from there.`
         : input.buildsOn
             ? `\n\nThis task was done once already (attempt ${input.buildsOn.fromAttempt}), and that work is in your ` +
                 `working tree. The text above is a new instruction for it: look at what is there first, build on it, and ` +

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,