copilot-operator 0.1.9 → 0.1.11

package/dist/src/api/operator.controller.js

@@ -466,6 +466,10 @@ let OperatorController = class OperatorController {
      * Separate from the session's own preflight because that one only speaks when version
      * control is already on, and the question here is whether it may be turned on.
      */
+    /** The command that brings a project's branch back to its remote's main — shown, never run. */
+    repoSync(dir) {
+        return this.ops.syncPlan(dir ?? '').catch(fail);
+    }
     repo(dir) {
         const problem = this.ops.repoProblem(dir ?? '');
         return problem ? { ok: false, problem } : { ok: true };
@@ -994,6 +998,13 @@ __decorate([
     __metadata("design:paramtypes", [Object]),
     __metadata("design:returntype", Promise)
 ], OperatorController.prototype, "setProject", null);
+__decorate([
+    Get('repo/sync'),
+    __param(0, Query('dir')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], OperatorController.prototype, "repoSync", null);
 __decorate([
     Get('repo'),
     __param(0, Query('dir')),

package/dist/src/api/operator.service.js

@@ -15,11 +15,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { Injectable } from '@nestjs/common';
 import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { installLayout } from '../config/layout.js';
-import { SessionStore, DEFAULT_VCS, DEFAULT_REVIEW } from '../session/store.js';
+import { SessionStore, DEFAULT_VCS, DEFAULT_REVIEW, applyTaskPatch } from '../session/store.js';
 import { EventBus } from '../session/events.js';
-import { newId, tidyVcsPlan } from '../session/model.js';
+import { newId } from '../session/model.js';
 import { runSession, openBrowser, queuedToRun } from '../orchestrator/taskRunner.js';
 import { buildExport } from '../session/exportRecord.js';
 import { buildDebugExport } from '../session/debugExport.js';
@@ -47,10 +47,17 @@ import { assessIsolation, readIsolationSignals, unattendedIsolationRefusal } fro
 import { unattendedPrecondition } from '../exec/policy.js';
 import { createTransport } from '../transport/chatTransport.js';
 import { composeHandoff } from '../session/handoff.js';
+import { planSync } from '../vcs/syncCommand.js';
 import { computeMetrics } from '../session/metrics.js';
 import { resolveDesktopDir, desktopIsSynced } from '../context/contextFiles.js';
 import { saveAndReveal } from './saveToDesktop.js';
 import { Settings } from './settings.js';
+/** A folder as compared: absolute, forward slashes, no trailing slash, and case folded as Windows does. */
+function normaliseDir(dir) {
+    if (!dir.trim())
+        return '';
+    return resolve(dir.trim()).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+}
 let OperatorService = class OperatorService {
     /** Where this install keeps its prompts and its records. See `config/layout.ts`. */
     layout = installLayout();
@@ -303,16 +310,7 @@ let OperatorService = class OperatorService {
         return await this.store.updateTask(sessionId, taskId, (t) => {
             if (t.status !== 'queued')
                 throw new Error('Only a queued task can be edited.');
-            if (patch.title !== undefined)
-                t.title = patch.title;
-            if (patch.level2 !== undefined)
-                t.level2 = patch.level2;
-            if (patch.prompt !== undefined)
-                t.prompt = patch.prompt;
-            if (patch.vcsPlan !== undefined)
-                t.vcsPlan = tidyVcsPlan(patch.vcsPlan);
-            if (patch.checks !== undefined)
-                t.checks = patch.checks.filter((c) => c.name.trim() !== '');
+            applyTaskPatch(t, patch);
         });
     }
     async deleteTask(sessionId, taskId) {
@@ -1783,6 +1781,26 @@ let OperatorService = class OperatorService {
     repoProblem(dir) {
         return repoUnusableReason(dir);
     }
+    /**
+     * What bringing a project back to its remote's main branch would lose, and the command that does
+     * it — for the operator to run. See `vcs/syncCommand.ts`; nothing here writes.
+     *
+     * Only for a folder this bot already works in: a project in Settings or the repository of a
+     * session. The answer lists file names and commit subjects, and a local page asking about any
+     * folder on the disk is not a question this API should answer.
+     */
+    async syncPlan(dir) {
+        await this.init();
+        const wanted = normaliseDir(dir);
+        const cfg = await this.settings.load();
+        const known = new Set([cfg.project?.rootDir ?? '', ...(cfg.project?.others ?? []).map((o) => o.rootDir), ...(await this.store.listSessions()).flatMap((s) => [s.vcs?.repoDir ?? '', s.mirror?.rootDir ?? ''])]
+            .filter((d) => d.trim())
+            .map(normaliseDir));
+        if (!wanted || !known.has(wanted)) {
+            throw new Error('That folder is not one of the projects in Settings or the repository of a session, so no command is offered for it.');
+        }
+        return await planSync(resolve(dir.trim()));
+    }
     // --- the project being worked on ---------------------------------------------------------
     /**
      * The folder new sessions start pointed at, and whether it can carry version control.
@@ -2035,6 +2053,7 @@ let OperatorService = class OperatorService {
                     disputes: t.disputes?.length || undefined,
                     readOnly: t.readOnly || undefined,
                     scope: t.scope?.length ? t.scope : undefined,
+                    stopCode: t.stopCode,
                     autoRetries: t.autoRetries || undefined,
                     attempt: t.attempt,
                     changedFiles: t.vcs?.commit && t.vcs.baseCommit ? (t.vcs.files?.length ?? 0) : undefined,

package/dist/src/config/schema.js

@@ -399,6 +399,12 @@ export const RunConfigSchema = z.object({
          * its record. Zero turns it off.
          */
         retryBlockedInFreshChat: z.number().int().nonnegative().default(2),
+        /*
+         * How many genuinely different approaches the chat must have tried before it may end a task
+         * "blocked". The reply format's own floor is 2 (replySchema.ts); this raises it. A "blocked"
+         * with fewer is sent back asking for another approach (see taskRunner.ts). Settings → Execution.
+         */
+        minApproachesBeforeBlocked: z.number().int().min(2).max(50).default(2),
     })
         .prefault({}),
     runsDir: z.string().default('./runs'),

package/dist/src/orchestrator/contract.js

@@ -0,0 +1,58 @@
+/**
+ * Whether a task can be satisfied at all, decided before anything is sent to the chat.
+ *
+ * A task is a contract: a prompt, the checks that say when it is done, and what it may change
+ * (`readOnly`, `scope`). The three are written at different times — a plan, an edit, a new prompt on
+ * a finished task — and they can end up contradicting each other: an audit made read-only that
+ * still carries the old "the file now says X" check; a task scoped to its tests that must change
+ * the config to pass. Run as it is, such a task spends its rounds and ends blocked on a check the
+ * chat could never have met. This names the contradiction instead, before the first message.
+ *
+ * Only what can be known without running anything is judged: the flags against each other, and
+ * the file checks against the tree as it is now. A file check that already passes needs no change;
+ * one that fails needs its file changed, which a read-only task, or a scope that leaves the file
+ * out, forbids. Command checks are not judged: whether a command will pass depends on work the
+ * task is allowed to do elsewhere.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { inScope } from '../vcs/scope.js';
+async function fileCheckPassesNow(check, cwd) {
+    const path = resolve(cwd, (check.cwd ?? '').trim() || '.', (check.file ?? '').trim());
+    const info = await stat(path).catch(() => null);
+    const exists = !!info?.isFile();
+    if (check.expect === 'file-exists')
+        return { passes: exists, path };
+    if (check.expect === 'file-missing')
+        return { passes: !exists, path };
+    const text = exists ? await readFile(path, 'utf8').catch(() => '') : '';
+    return { passes: exists && text.includes(check.value ?? ''), path };
+}
+/** Each contradiction in the task, as a sentence; empty when it can be satisfied. */
+export async function contractConflicts(task, cwd, repoDir) {
+    const out = [];
+    const scope = task.scope ?? [];
+    if (task.readOnly && scope.length > 0) {
+        out.push(`It is read-only, which allows no change, and also scoped to ${scope.join(', ')}, which allows changes there.`);
+    }
+    if (!task.readOnly && scope.length === 0)
+        return out;
+    const checks = [
+        ...(task.checks ?? []),
+        ...(task.reviewChecks ?? []).filter((rc) => rc.state === 'active').map((rc) => rc.check),
+    ].filter((c) => c.expect === 'file-exists' || c.expect === 'file-missing' || c.expect === 'file-contains');
+    for (const check of checks) {
+        const { passes, path } = await fileCheckPassesNow(check, cwd);
+        if (passes)
+            continue;
+        const rel = relative(resolve(repoDir), path).replace(/\\/g, '/');
+        const inside = rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+        if (task.readOnly) {
+            out.push(`The check "${check.name}" fails now and can only pass if ${rel || path} changes, but the task is read-only.`);
+        }
+        else if (inside && !inScope(rel, scope)) {
+            out.push(`The check "${check.name}" fails now and can only pass if ${rel} changes, but the task's scope (${scope.join(', ')}) leaves that file out.`);
+        }
+    }
+    return out;
+}

package/dist/src/orchestrator/taskRunner.js

@@ -38,9 +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 { MIN_TRIED_APPROACHES } from '../protocol/replySchema.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';
@@ -184,11 +186,12 @@ export async function openBrowser(cfg, bus, transportDir, sessionId) {
                 'verification-cleared': 'Verification cleared, continuing.',
                 'error-banner': 'The chat reported a transient error; reloading the page.',
                 'reply-files-ignored': 'The reply came with a file attached. It was not downloaded and will not be run: the runner takes only the text of a reply.',
+                'model-menu-stuck': 'The model menu would not close — Escape, the menu button and a click outside all left it open. Close it in the Edge window; the run goes on.',
             };
             bus.publish({
                 sessionId,
                 type: `browser:${event}`,
-                level: event === 'verification-required' || event === 'reply-files-ignored' ? 'warn' : 'info',
+                level: event === 'verification-required' || event === 'reply-files-ignored' || event === 'model-menu-stuck' ? 'warn' : 'info',
                 message: spoken[event],
                 data: detail,
             });
@@ -360,12 +363,27 @@ export async function runTask(transport, session, task, deps) {
     let runnerNotes = [];
     /** Steps the chat sent that were not run, for the handoff at the end. */
     const notRun = [];
+    /**
+     * How many different approaches "blocked" needs, from Settings, never below the format's own two.
+     * A "blocked" with fewer is sent back; after `MAX_EARLY_BLOCKS` of them in a row with nothing tried
+     * in between the verdict is accepted, so a chat that cannot think of anything else does not spend
+     * the rest of the iterations saying so.
+     */
+    const minApproaches = Math.max(MIN_TRIED_APPROACHES, cfg.limits.minApproachesBeforeBlocked ?? MIN_TRIED_APPROACHES);
+    const MAX_EARLY_BLOCKS = 3;
+    let earlyBlocks = 0;
     /** 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.
@@ -467,6 +485,8 @@ export async function runTask(transport, session, task, deps) {
                 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) => {
@@ -606,9 +626,31 @@ export async function runTask(transport, session, task, deps) {
          * 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;
+        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) {
@@ -664,6 +706,10 @@ export async function runTask(transport, session, task, deps) {
             vcsNote: prepared.note,
             readOnlyNote: task.readOnly ? READ_ONLY_NOTE : undefined,
             scopeNote: scopeNote(scope, scopeEnforced),
+            approachesNote: minApproaches > MIN_TRIED_APPROACHES
+                ? `## Giving up\n\nThis task may end with status "blocked" only after at least ${minApproaches} genuinely different approaches, ` +
+                    `each listed in "tried". With fewer, the runner asks you for another approach instead of accepting it.`
+                : undefined,
             shellNote: shellNote(shells, defaultShell),
         });
         await setTask((t) => {
@@ -819,6 +865,7 @@ export async function runTask(transport, session, task, deps) {
             if (stuck) {
                 noProgressReason = stuck;
                 stats.stoppedFor = 'no-progress';
+                stopCode = 'no-progress';
                 sink.event('no-progress', { kind: 'checks' }, stuck, 'warn');
                 return 'give-up';
             }
@@ -1155,9 +1202,20 @@ export async function runTask(transport, session, task, deps) {
                 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));
@@ -1167,6 +1225,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;
@@ -1231,18 +1292,49 @@ export async function runTask(transport, session, task, deps) {
              * what the reply said, at greater length and one message later. The reason carries the
              * approaches that were tried, and that is what the register shows.
              */
+            if (!blocked && reply.steps.length > 0)
+                earlyBlocks = 0;
+            if (blocked && reply.tried.length < minApproaches && earlyBlocks < MAX_EARLY_BLOCKS) {
+                /*
+                 * Too early to give up, by the operator's own measure (Settings → Execution). Sent back as a
+                 * request for another approach rather than accepted: the format only knows that two is the
+                 * floor, the operator decided this work deserves more tries than that.
+                 */
+                earlyBlocks += 1;
+                stats.blockedTooEarly = (stats.blockedTooEarly ?? 0) + 1;
+                sink.event('blocked-too-early', { tried: reply.tried.length, needed: minApproaches, time: earlyBlocks }, `"blocked" after ${reply.tried.length} approach(es); Settings ask for ${minApproaches}, so the chat is asked for another`, 'warn');
+                const message = `Not yet. This task is given up only after at least ${minApproaches} genuinely different approaches, and your reply lists ` +
+                    `${reply.tried.length}: ${reply.tried.map((x, i) => `(${i + 1}) ${x}`).join(' ')}. Try a different approach now — not one of ` +
+                    'these again, and not the same command reworded — and send its steps with status "continue". If it fails too, add it to ' +
+                    '"tried" and try another. Nothing you listed is lost: the runner keeps what has been tried.';
+                await record('BLOCKED TOO EARLY — MESSAGE SENT', message);
+                await pacer.throttleSend();
+                const before = await transport.sendAndConfirm(message);
+                const next = await transport.waitForReply(before);
+                await saveReply(`blocked-too-early-${earlyBlocks}`, next);
+                lastMarkdown = next.markdown;
+                await pacer.settle();
+                continue;
+            }
             if (blocked) {
                 sink.event('task-blocked', { tried: reply.tried, needed: reply.needed }, `the task was given up as blocked after ${reply.tried.length} approach(es)`, 'warn');
-                return await finish('blocked', blockedReason(reply.tried, reply.needed), reply.summary, lastMarkdown);
+                const early = reply.tried.length < minApproaches
+                    ? ` It gave up after ${reply.tried.length} of the ${minApproaches} approaches Settings ask for, having been asked ${earlyBlocks} time(s) for another.`
+                    : '';
+                return await finish('blocked', blockedReason(reply.tried, reply.needed) + early, reply.summary, lastMarkdown);
             }
             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') {
@@ -1382,6 +1474,7 @@ export async function runTask(transport, session, task, deps) {
             // 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);
             }
             /*
@@ -1390,7 +1483,7 @@ export async function runTask(transport, session, task, deps) {
              * and the chat is told in the same message.
              */
             if (scopeEnforced) {
-                const check = await enforceScope(repoDirOf(session), scope).catch((e) => ({
+                const check = await enforceScope(repoDirOf(session), scope, !!task.readOnly).catch((e) => ({
                     outside: [],
                     reverted: [],
                     failed: [{ path: '(the working tree)', why: e.message }],
@@ -1398,7 +1491,7 @@ export async function runTask(transport, session, task, deps) {
                 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));
+                    runnerNotes.push(scopeMessage(check, scope, !!task.readOnly));
                     stats.scopeReverts += check.reverted.length;
                     await setTask((t) => {
                         t.scopeReverted = [...new Set([...(t.scopeReverted ?? []), ...check.reverted])];
@@ -1429,6 +1522,7 @@ export async function runTask(transport, session, task, deps) {
             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);
             }
@@ -1529,11 +1623,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') {

package/dist/src/plan/schema.js

@@ -432,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 {
@@ -503,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

@@ -1437,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',
@@ -2828,6 +2844,38 @@ export const SYSTEM_GUIDE = [
                         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: 'sync.show',
+                        kind: 'button',
+                        en: 'Command to bring this project back to the remote main branch',
+                        bg: 'Команда за връщане на проекта към основния клон на отдалеченото хранилище',
+                        doesEn: 'Under each project in Settings and on a session\u2019s version control: lists what would be lost and gives a PowerShell command to paste; the bot never runs it.',
+                        doesBg: 'Под всеки проект в Настройки и в контрола на версиите на сесия: изброява какво ще се загуби и дава команда за PowerShell; ботът никога не я пуска.',
+                    },
+                    {
+                        key: 'sync.copyPreview',
+                        kind: 'button',
+                        en: 'Copy the preview (changes nothing)',
+                        bg: 'Копирай прегледа (не променя нищо)',
+                        doesEn: 'Fetches and lists the commits, changes and new files the command would remove.',
+                        doesBg: 'Изтегля и изброява commit-ите, промените и новите файлове, които командата би махнала.',
+                    },
+                    {
+                        key: 'sync.copyCommand',
+                        kind: 'button',
+                        en: 'Copy the command',
+                        bg: 'Копирай командата',
+                        doesEn: 'fetch, reset --hard to the remote main, clean -fd — each only if the step before worked.',
+                        doesBg: 'fetch, reset --hard към основния клон, clean -fd — всяка само ако предишната е успяла.',
+                    },
+                    {
+                        key: 'exec.minApproaches',
+                        kind: 'field',
+                        en: 'Approaches the chat must try before it may give up',
+                        bg: 'Подходи, които чатът трябва да опита, преди да се откаже',
+                        doesEn: 'How many different approaches a "blocked" must list (2–20); with fewer the chat is asked for another.',
+                        doesBg: 'Колко различни подхода трябва да изброи „blocked“ (2–20); с по-малко чатът е помолен за още един.',
+                    },
                     {
                         key: 'exec.retryBlocked',
                         kind: 'field',