copilot-operator 0.1.8 → 0.1.10

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,11 @@ 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 { contractConflicts } from './contract.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 +167,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 +324,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 +359,20 @@ 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;
+    /**
+     * Why the attempt stopped, when the status alone does not say: a format the chat could not keep,
+     * a task contract that contradicts itself, a loop, a check that could never run, a machine that
+     * lacks a shell. Written by `finish`. See `Task.stopCode`.
+     */
+    let stopCode;
     /**
      * 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 +473,13 @@ export async function runTask(transport, session, task, deps) {
             if (reviewChecks.length > 0)
                 t.reviewChecks = reviewChecks;
             t.logFile = 'task-log.txt';
+            t.stats = stats;
+            if (stopCode)
+                t.stopCode = stopCode;
+        });
+        // 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 +609,37 @@ 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 onOwnBranch = !!prepared.vcs.branch && !prepared.vcs.problem && !!prepared.vcs.baseCommit;
+        /*
+         * A read-only task is a scope of nothing, and is enforced the same way: whatever a round changed
+         * is put back before the chat reads the results. It used to be judged only at the end, so an
+         * audit that edited a file "to check something" kept the edit through every later round and its
+         * findings described a tree that was not the one it had been asked to audit.
+         */
+        const scopeEnforced = (scope.length > 0 || !!task.readOnly) && onOwnBranch;
+        /** 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;
+        /*
+         * The task's contract, checked before a single message is sent.
+         *
+         * A task can be written so that no answer satisfies it: read-only and still given paths to
+         * change, or a check that needs a file to change while the task may not change it. Sent as it
+         * is, the chat works for rounds, the check fails at the end, and the task goes blocked on a
+         * finding the chat could never have fixed. The contradiction is named instead, now, and nothing
+         * is run. See `orchestrator/contract.ts`.
+         */
+        const conflicts = await contractConflicts(task, work.cwd, repoDirOf(session) || work.cwd);
+        if (conflicts.length > 0) {
+            stopCode = 'contract-conflict';
+            sink.event('contract-conflict', { conflicts }, `the task contradicts itself: ${conflicts.join(' | ')}`, 'error');
+            return await finish('blocked', `the task contradicts itself, so it was not started: ${conflicts.join(' ')} Change the prompt, the checks, the scope or read-only, and queue it again.`);
+        }
         // --- project mirror, attached to the first message of the task ---------------------
         let mirrorFiles = [];
         if (session.mirror.enabled && session.mirror.rootDir) {
@@ -630,6 +694,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 +759,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 +771,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 +792,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 +842,18 @@ 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';
+                stopCode = '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 +1024,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,10 +1185,22 @@ 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');
+                /*
+                 * Out of format retries: stopped at a limit, not failed.
+                 *
+                 * Nothing about the work went wrong here — the steps that ran are recorded, their output is
+                 * in the run folder, and the rejected replies ran nothing. So the task ends `limit-reached`,
+                 * marked `format-repair-exhausted`, which is what lets "Continue in the same chat" carry it
+                 * on from exactly here instead of the operator having to run it again from the start. It
+                 * used to end `failed`, which read as a verdict on the work and offered only a fresh start.
+                 */
                 if (formatRetries > cfg.limits.maxFormatRetries) {
                     await transport.dumpFailure(log.path('failures'), 'format-error');
-                    return await finish('failed', `Copilot did not keep the output contract: ${parsed.detail}`, undefined, lastMarkdown);
+                    stopCode = 'format-repair-exhausted';
+                    return await finish('limit-reached', `format repair exhausted: ${formatRetries} replies in a row did not match the format (maxFormatRetries ${cfg.limits.maxFormatRetries}), ` +
+                        `the last because ${parsed.detail}. Nothing from those replies was run; the work so far is kept.`, undefined, lastMarkdown);
                 }
                 await pacer.throttleSend();
                 const before = await transport.sendAndConfirm(formatErrorMessage(parsed, formatRetries, cfg.limits.maxFormatRetries));
@@ -1113,6 +1210,9 @@ export async function runTask(transport, session, task, deps) {
                 continue;
             }
             formatRetries = 0;
+            if (parsed.coerced) {
+                sink.event('format-coerced', { fields: parsed.coerced }, `read as text: ${parsed.coerced.join(', ')} arrived in another shape; nothing in them is run, so the reply was taken as it was`);
+            }
             iterations += 1;
             await setTask((t) => {
                 t.iterations = iterations;
@@ -1184,9 +1284,15 @@ export async function runTask(transport, session, task, deps) {
             if (done && reply.steps.length === 0) {
                 const verdict = await gateOnChecks();
                 if (verdict === 'environment') {
+                    stopCode = 'environment';
                     return await finish('failed', shellProblemReason(environmentProblem), reply.summary, lastMarkdown);
                 }
                 if (verdict === 'give-up') {
+                    if (noProgressReason)
+                        return await finish('blocked', noProgressReason, reply.summary, lastMarkdown);
+                    // Every failing check was refused before it ran: a verdict on the checks, not on the work.
+                    if (lastOutcomes.some((o) => !o.passed) && lastOutcomes.every((o) => o.passed || o.refusedBeforeRunning))
+                        stopCode = 'invalid-check';
                     return await finish('failed', checksFailedReason(lastOutcomes), reply.summary, lastMarkdown);
                 }
                 if (verdict === 'accept') {
@@ -1246,6 +1352,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 +1419,43 @@ 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) {
+                stopCode = 'environment';
                 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, !!task.readOnly).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, !!task.readOnly));
+                    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 +1475,15 @@ 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';
+                stopCode = '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.
              *
@@ -1433,9 +1581,15 @@ export async function runTask(transport, session, task, deps) {
             if (done) {
                 const verdict = await gateOnChecks();
                 if (verdict === 'environment') {
+                    stopCode = 'environment';
                     return await finish('failed', shellProblemReason(environmentProblem), reply.summary, lastMarkdown);
                 }
                 if (verdict === 'give-up') {
+                    if (noProgressReason)
+                        return await finish('blocked', noProgressReason, reply.summary, lastMarkdown);
+                    // Every failing check was refused before it ran: a verdict on the checks, not on the work.
+                    if (lastOutcomes.some((o) => !o.passed) && lastOutcomes.every((o) => o.passed || o.refusedBeforeRunning))
+                        stopCode = 'invalid-check';
                     return await finish('failed', checksFailedReason(lastOutcomes), reply.summary, lastMarkdown);
                 }
                 if (verdict === 'accept') {
@@ -1562,8 +1716,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:
@@ -425,7 +432,7 @@ export function checkPlan(text) {
     if (!parsed.success) {
         return { ok: false, warnings, issues: parsed.error.issues.map((i) => ({ path: pathOf(i.path), message: i.message })) };
     }
-    const weak = weakCheckIssues(parsed.data);
+    const weak = [...weakCheckIssues(parsed.data), ...contradictionIssues(parsed.data)];
     if (weak.length)
         return { ok: false, warnings, issues: weak };
     return {
@@ -496,6 +503,26 @@ function weakCheckIssues(plan) {
     });
     return out;
 }
+/**
+ * A task whose own flags contradict each other: read-only (change nothing) and scoped (change
+ * these). Refused at import, where the chat that wrote it can still be asked which it meant; the
+ * runner refuses it again before starting (orchestrator/contract.ts) for a task edited since.
+ */
+function contradictionIssues(plan) {
+    const out = [];
+    plan.sessions.forEach((s, i) => {
+        s.tasks.forEach((t, j) => {
+            if (!t.readOnly || t.scope.length === 0)
+                return;
+            out.push({
+                path: `sessions[${i}].tasks[${j}]`,
+                message: `"${t.title}" is "readOnly": true, which allows no change, and has a "scope" (${t.scope.join(', ')}), which allows changes there. ` +
+                    'An audit that writes a report is not read-only: drop "readOnly" and scope it to the report. One that writes nothing: drop "scope".',
+            });
+        });
+    });
+    return out;
+}
 /** The issues as a block the user can hand back to the chat model without editing it. */
 export function describeIssues(issues) {
     return issues.map((i) => (i.path ? `- ${i.path}: ${i.message}` : `- ${i.message}`)).join('\n');

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',
@@ -1421,6 +1437,22 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'On a task that has already run: stores the edit and queues it again; the earlier attempt is kept. On a done task the new attempt builds on its work. It does not start it.',
                         doesBg: 'При вече изпълнена задача: записва промяната и я връща в опашката; предишният опит се пази. При готова задача новият опит стъпва върху свършеното. Не я пуска.',
                     },
+                    {
+                        key: 'task.readOnlyEdit',
+                        kind: 'checkbox',
+                        en: 'Read-only: this task must not change any file',
+                        bg: 'Само за четене: задачата не бива да променя нито един файл',
+                        doesEn: 'Also in the new-prompt dialog of the register. For an audit: every change a round makes is put back.',
+                        doesBg: 'Има го и в диалога за нов prompt в регистъра. За одит: всяка промяна от кръг се връща.',
+                    },
+                    {
+                        key: 'task.scopeEdit',
+                        kind: 'field',
+                        en: 'Files this task may change',
+                        bg: 'Файлове, които задачата може да променя',
+                        doesEn: 'One path or pattern per line; changes elsewhere are put back. Also in the new-prompt dialog, which lists the old checks to keep or drop.',
+                        doesBg: 'По един път или шаблон на ред; промени другаде се връщат. Има го и в диалога за нов prompt, който изброява старите проверки за запазване или махане.',
+                    },
                     {
                         key: 'task.branch',
                         kind: 'field',
@@ -2571,6 +2603,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 +3114,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: 'Три степени над нормалния.',
                     },
                 ],
             },