copilot-operator 0.1.10 → 0.1.12

package/dist/src/orchestrator/taskRunner.js

@@ -13,7 +13,7 @@
 import { createHash } from 'node:crypto';
 import { readFile, mkdir, writeFile, appendFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { createTransport } from '../transport/chatTransport.js';
+import { createTransport, isReplyTimeout } 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';
@@ -38,12 +38,13 @@ 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 { contractConflicts, readsTreeClean } from './contract.js';
 import { treeFingerprint } from '../vcs/git.js';
-import { mirrorProject, describeMirror } from '../context/projectMirror.js';
+import { mirrorProject, describeMirror, MirrorSelectionError } from '../context/projectMirror.js';
 import { projectNameFor, projectTargetDir, removeLegacyFlatMirror } from '../context/desktopMirror.js';
 import { prepareForTask, commitTaskResult, repoDirOf } from '../vcs/taskVcs.js';
 import { exportMachine, writeAttemptRecord } from '../session/exports.js';
@@ -185,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,
             });
@@ -361,6 +363,15 @@ 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`. */
@@ -373,6 +384,15 @@ export async function runTask(transport, session, task, deps) {
      * lacks a shell. Written by `finish`. See `Task.stopCode`.
      */
     let stopCode;
+    /** The setting whose limit ended the attempt, when one did. Written by `finish`. See `TaskLimit`. */
+    let limitHit;
+    /**
+     * Checks that the working tree is clean, decided after the runner's commit rather than at the gate.
+     * The chat may not commit, so before that commit such a check could only fail (2026-09-30: failed,
+     * and then the commit left the tree clean). Set by the gate, run by `finish`. See `readsTreeClean`.
+     */
+    let afterCommitChecks = [];
+    let runAfterCommit = 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.
@@ -445,6 +465,40 @@ export async function runTask(transport, session, task, deps) {
             sink.event('vcs-error', { error: String(e) }, `version control failed after the task: ${e.message}`, 'warn');
             return undefined;
         });
+        /*
+         * The checks about a clean tree, now that the runner has committed. A done task whose tree is
+         * still not clean after the commit has failed; any other ending keeps its own reason, and the
+         * results are recorded all the same.
+         */
+        let afterCommitResults = [];
+        if (afterCommitChecks.length > 0 && runAfterCommit) {
+            const outcomes = await runAfterCommit(afterCommitChecks).catch((e) => {
+                sink.event('checks-after-commit-error', { error: String(e) }, `the checks after the commit could not run: ${e.message}`, 'warn');
+                return [];
+            });
+            afterCommitResults = outcomes.map((o) => ({ name: `${o.check.name} (after the commit)`, passed: o.passed, detail: o.detail }));
+            for (const o of outcomes) {
+                sink.event(o.passed ? 'check-passed' : 'check-failed', { name: o.check.name, detail: o.detail, afterCommit: true }, `${o.passed ? 'passed' : 'FAILED'} after the commit: ${o.check.name} — ${o.detail}`, o.passed ? 'info' : 'warn');
+            }
+            const failedAfter = outcomes.filter((o) => !o.passed);
+            if (status === 'done' && failedAfter.length > 0) {
+                status = 'failed';
+                reason =
+                    `after the runner's commit${vcsAfter?.commit ? ` (${vcsAfter.commit.slice(0, 8)})` : ''}${vcsAfter?.problem ? `, which did not happen: ${vcsAfter.problem}` : ''}, ` +
+                        `${failedAfter.length} check(s) about the working tree still failed: ${failedAfter.map((o) => `${o.check.name} (${o.detail})`).join('; ')}`;
+            }
+        }
+        /*
+         * What the task said about the repository was written before the commit. When it did not end
+         * done and the runner then committed its changes, the reason says so, so "not committed, the
+         * tree is dirty" is not left standing beside a commit on the record.
+         */
+        if (status !== 'done' && vcsAfter?.commit && vcsAfter.commit !== task.vcs?.commit) {
+            reason =
+                `${reason ?? ''} After that, the runner committed the task's changes as ${vcsAfter.commit.slice(0, 8)} on ${vcsAfter.branch}` +
+                    `${vcsAfter.afterCommit ? (vcsAfter.afterCommit.clean ? '; the working tree is clean' : `; still uncommitted: ${vcsAfter.afterCommit.changed.slice(0, 8).join(', ')}`) : ''}.`;
+            reason = reason.trim();
+        }
         if (vcsAfter?.branch) {
             await record('VERSION CONTROL', [
                 `branch : ${vcsAfter.branch}`,
@@ -476,11 +530,26 @@ export async function runTask(transport, session, task, deps) {
             t.stats = stats;
             if (stopCode)
                 t.stopCode = stopCode;
+            if (limitHit)
+                t.limit = limitHit;
+            if (afterCommitResults.length > 0)
+                t.checkResults = [...(t.checkResults ?? []), ...afterCommitResults];
+            // A review that was asked for and never ran says why, instead of reading as zero rounds.
+            if (!t.review && (task.reviewEnabled ?? session.review?.enabled ?? true) && status !== 'done') {
+                t.review = {
+                    verdict: 'skipped',
+                    rounds: 0,
+                    stepsRun: 0,
+                    skippedBecause: `the task ended ${status} before its work reached the review; the review runs only on work reported done whose checks pass`,
+                };
+            }
         });
         // The end in one fixed shape, read off the record just written. See `session/handoff.ts`.
         await setTask((t) => {
             t.handoff = composeHandoff(t, notRun);
         });
+        // Its last changes, checks and commit included, go to the Desktop copies too.
+        deps.onWorkChanged?.();
         sink.event('task-finished', { status, reason, iterations }, `task "${task.title}" ${status}${reason ? `: ${reason}` : ''}`);
         await log.close();
         /*
@@ -634,7 +703,9 @@ export async function runTask(transport, session, task, deps) {
          * 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);
+        const conflicts = await contractConflicts(task, work.cwd, repoDirOf(session) || work.cwd, {
+            branch: prepared.vcs.problem ? undefined : prepared.vcs.branch,
+        });
         if (conflicts.length > 0) {
             stopCode = 'contract-conflict';
             sink.event('contract-conflict', { conflicts }, `the task contradicts itself: ${conflicts.join(' | ')}`, 'error');
@@ -648,8 +719,14 @@ export async function runTask(transport, session, task, deps) {
             const projectName = projectNameFor(session.mirror.rootDir, cfg);
             const targetDir = projectTargetDir(cfg, projectName);
             await removeLegacyFlatMirror(cfg).catch(() => undefined);
+            /*
+             * A selection that cannot be copied stops the task before anything is sent: the chat would
+             * otherwise work without the files it was promised. The copies already there are kept.
+             */
             const result = await mirrorProject({
                 rootDir: session.mirror.rootDir,
+                // `rules-engine` in a plan usually means the repository's folder, wherever the root is.
+                alsoUnder: [repoDirOf(session)],
                 includeDirs: session.mirror.includeDirs.length ? session.mirror.includeDirs : ['.'],
                 excludeDirs: session.mirror.excludeDirs,
                 targetDir,
@@ -662,7 +739,11 @@ export async function runTask(transport, session, task, deps) {
                 ignoreDirs: cfg.projectMirror.ignoreDirs,
                 includeEnvFiles: session.mirror.includeEnvFiles ?? cfg.projectMirror.includeEnvFiles,
                 maxFileBytes: cfg.projectMirror.maxFileBytes,
-            });
+            }).catch((e) => (e instanceof MirrorSelectionError ? e : Promise.reject(e)));
+            if (result instanceof MirrorSelectionError) {
+                sink.event('mirror-refused', { error: result.message }, result.message, 'error');
+                return await finish('failed', `${result.message} Nothing was sent to the chat. Fix the files to attach and queue the task again.`);
+            }
             sink.event('mirror', { targetDir, ...result }, `project mirror: ${describeMirror(result)}`);
             if (session.mirror.includeEnvFiles) {
                 const envCount = Object.keys(result.mapping).filter((p) => /(^|\/)\.env(\.|$)/i.test(p)).length;
@@ -695,6 +776,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) => {
@@ -771,14 +856,21 @@ 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, CONTENT_CLEAN_CHECK] : [])];
+            const every = [...(task.checks ?? []), ...activeChecks(reviewChecks)];
+            // Whether the tree is clean is decided after the runner's commit; see `afterCommitChecks`.
+            const deferred = willCommit ? every.filter(readsTreeClean) : [];
+            if (deferred.length > 0 && afterCommitChecks.length === 0) {
+                sink.event('checks-after-commit', { checks: deferred.map((c) => c.name) }, `${deferred.length} check(s) about a clean working tree are decided after the runner commits the work: ${deferred.map((c) => c.name).join(', ')}`);
+            }
+            afterCommitChecks = deferred;
+            const checks = [...every.filter((c) => !deferred.includes(c)), ...(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
             // a missing interpreter asked nothing of the work and must not cost the task one.
             const round = checkRounds + 1;
             sink.event('checks-started', { round, count: checks.length }, `checking the task against ${checks.length} condition(s)`);
-            const outcomes = (lastOutcomes = await runChecks(checks, {
+            const checkOptions = {
                 cwd: work.cwd,
                 tracker,
                 passEnv: cfg.execution.passEnv,
@@ -796,7 +888,9 @@ export async function runTask(transport, session, task, deps) {
                 // 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,
-            }));
+            };
+            runAfterCommit = (cs) => runChecks(cs, checkOptions);
+            const outcomes = (lastOutcomes = await runChecks(checks, checkOptions));
             /*
              * 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
@@ -870,6 +964,7 @@ export async function runTask(transport, session, task, deps) {
                     sink.event('checks-derived-deferred', { rounds: checkRounds - 1, checks: failed.map((o) => o.check.name) }, `${failed.length} check(s) from earlier reviews still fail after ${maxCheckRounds} attempt(s); the work goes to the reviewer with them named`, 'warn');
                     return 'accept';
                 }
+                limitHit = { setting: 'maxCheckRounds', value: maxCheckRounds };
                 sink.event('checks-exhausted', { rounds: checkRounds - 1 }, `${failed.length} check(s) still failing after ${maxCheckRounds} attempt(s); the task is closed as failed`, 'warn');
                 return 'give-up';
             }
@@ -929,7 +1024,7 @@ export async function runTask(transport, session, task, deps) {
          */
         const gateOnReview = async (closing) => {
             if (!reviewWanted) {
-                await saveReview({ verdict: 'skipped', rounds: 0, stepsRun: 0 });
+                await saveReview({ verdict: 'skipped', rounds: 0, stepsRun: 0, skippedBecause: `the review is switched off for this ${task.reviewEnabled === false ? 'task' : 'session'}` });
                 return 'accept';
             }
             reviewRounds += 1;
@@ -1114,6 +1209,7 @@ export async function runTask(transport, session, task, deps) {
              * at the fix. It had been fixed.
              */
             if (reviewRounds > maxReviewRounds) {
+                limitHit = { setting: 'maxReviewRounds', value: maxReviewRounds };
                 sink.event('review-exhausted', { rounds: maxReviewRounds, findings: outcome.findings.length }, `the review still has findings after ${maxReviewRounds} round(s) of fixing; the task is closed as blocked`, 'warn');
                 return 'give-up';
             }
@@ -1175,10 +1271,14 @@ export async function runTask(transport, session, task, deps) {
         for (;;) {
             if (signal?.aborted)
                 return await finish('aborted', 'stopped by the operator');
-            if (Date.now() > deadline)
+            if (Date.now() > deadline) {
+                limitHit = { setting: 'maxRunMinutes', value: cfg.limits.maxRunMinutes };
                 return await finish('limit-reached', `maxRunMinutes (${cfg.limits.maxRunMinutes}) reached`);
-            if (iterations >= cfg.limits.maxIterations)
+            }
+            if (iterations >= cfg.limits.maxIterations) {
+                limitHit = { setting: 'maxIterations', value: cfg.limits.maxIterations };
                 return await finish('limit-reached', `maxIterations (${cfg.limits.maxIterations}) reached`);
+            }
             const parsed = parseReply(lastMarkdown, {
                 stopMarker: cfg.copilot.stopMarker,
                 defaultShell,
@@ -1199,6 +1299,7 @@ export async function runTask(transport, session, task, deps) {
                 if (formatRetries > cfg.limits.maxFormatRetries) {
                     await transport.dumpFailure(log.path('failures'), 'format-error');
                     stopCode = 'format-repair-exhausted';
+                    limitHit = { setting: 'maxFormatRetries', value: cfg.limits.maxFormatRetries };
                     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);
                 }
@@ -1277,9 +1378,36 @@ 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();
@@ -1475,6 +1603,9 @@ export async function runTask(transport, session, task, deps) {
             }
             if (aborted)
                 return await finish('aborted', 'the operator aborted the task', undefined, lastMarkdown);
+            // The files may have changed: the Desktop copies catch up, in the background (see RunDeps).
+            if (results.some((r) => r.outcome !== 'refused' && r.outcome !== 'aborted'))
+                deps.onWorkChanged?.();
             // 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);
@@ -1562,6 +1693,13 @@ export async function runTask(transport, session, task, deps) {
                     sent = true;
                 }
                 catch (e) {
+                    /*
+                     * The report went out and the chat is still answering it. Sending it again would stack a
+                     * second copy under a reply in progress; this is the reply wait from the settings running
+                     * out, which ends the task at that limit (see the catch at the end), not an upload to retry.
+                     */
+                    if (isReplyTimeout(e))
+                        throw e;
                     sink.event('report-send-failed', { attempt, error: String(e) }, `sending the report failed (attempt ${attempt + 1}): ${e.message}`, 'warn');
                     if (attempt === cfg.report.uploadRetries) {
                         const body = await readFile(report.paths[0], 'utf8');
@@ -1606,6 +1744,15 @@ export async function runTask(transport, session, task, deps) {
     }
     catch (e) {
         const message = e.message;
+        /*
+         * The chat took longer than Settings allow for a reply. A limit, not a fault: the conversation
+         * and the work are where they were, and "Continue" carries the task on in that chat.
+         */
+        if (isReplyTimeout(e)) {
+            sink.event('reply-timeout', { seconds: e.seconds }, message, 'warn');
+            limitHit = { setting: 'replyTimeoutSec', value: e.seconds };
+            return await finish('limit-reached', `replyTimeoutSec (${e.seconds}) reached: ${message}`);
+        }
         sink.event('task-error', { error: message, stack: e.stack }, message, 'error');
         await transport.dumpFailure(log.path('failures'), 'crash').catch(() => undefined);
         /*

package/dist/src/plan/brief.js

@@ -402,12 +402,12 @@ const FIELD_ROWS_BG = [
 ];
 const VCS_ROWS_EN = [
     ['vcs', 'session', 'yes, always', 'Whether the runner does version control for this session, and where. See below. A session without it is refused.'],
-    ['vcs.branch', 'task', 'yes in per-task mode', 'The branch this task works on, without the prefix.'],
+    ['vcs.branch', 'task', 'yes in per-task mode', 'The branch this task works on. A name with a "/" (feature/x, recovery/y) is used as written; one without gets the prefix.'],
     ['vcs.commitMessage', 'task', 'yes', 'The commit this task ends with. Imperative, first line under 72 characters.'],
 ];
 const VCS_ROWS_BG = [
     ['vcs', 'сесия', 'да, винаги', 'Дали runner-ът прави контрол на версиите за тази сесия и къде. Виж по-долу. Сесия без него се отказва.'],
-    ['vcs.branch', 'задача', 'да, в режим per-task', 'Клонът, по който работи задачата, без представката.'],
+    ['vcs.branch', 'задача', 'да, в режим per-task', 'Клонът, по който работи задачата. Име с „/“ (feature/x, recovery/y) се ползва както е; без „/“ получава представката.'],
     ['vcs.commitMessage', 'задача', 'да', 'Комитът, с който задачата завършва. В повелително наклонение, първият ред под 72 знака.'],
 ];
 function table(header, rows) {
@@ -417,7 +417,12 @@ const VCS_DETAIL_EN = `
 **vcs on a session**: \`enabled\` (true here), \`repoDir\` (absolute path to the git repository),
 \`branchMode\`, \`commitOnFinish\` (true unless the user says otherwise), \`branchPrefix\` (leave it
 "cop/"), \`branchName\` — used **only** in per-session mode, for the one branch the whole
-session works on, without the prefix — and \`startFrom\` with \`baseBranch\`.
+session works on — and \`startFrom\` with \`baseBranch\`. A branch name with a "/" follows the
+team's own convention and is used exactly as written (in per-session mode an existing branch of that
+name is carried on, not copied); a name without one gets the prefix. With version control on, a check never tests which
+branch is checked out — the runner chooses it; to check that earlier work is included, check the
+commit: \`git merge-base --is-ancestor <commit> HEAD\`. Nor does a check test that the working tree
+is clean: the runner commits after the checks, and its own commit is what leaves it clean.
 
 **startFrom** decides where each session's work begins, and it is the user's choice — ask:
 
@@ -460,7 +465,12 @@ const VCS_DETAIL_BG = `
 **vcs на сесия**: \`enabled\` (тук true), \`repoDir\` (абсолютен път до git хранилището),
 \`branchMode\`, \`commitOnFinish\` (true, освен ако потребителят не каже друго), \`branchPrefix\`
 (остави "cop/"), \`branchName\` — използва се **само** в режим per-session, за единствения клон,
-по който работи цялата сесия, без представката — и \`startFrom\` с \`baseBranch\`.
+по който работи цялата сесия — и \`startFrom\` с \`baseBranch\`. Име на клон с „/“ следва
+конвенцията на екипа и се ползва точно както е написано (в режим per-session съществуващ клон с това
+име се продължава, не се копира); име без „/“ получава представката. При включен контрол на версиите проверка никога не
+проверява кой клон е активен — него го избира runner-ът; за да провериш, че по-ранна работа е
+включена, провери commit-а: \`git merge-base --is-ancestor <commit> HEAD\`. Проверка не проверява и
+че работното дърво е чисто: runner-ът комитва след проверките и неговият commit го оставя чисто.
 
 **startFrom** решава откъде започва работата на всяка сесия, и изборът е на потребителя — питай:
 
@@ -738,8 +748,9 @@ 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**, 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.
+  A task stopped by a limit from the settings, or **aborted** because the bot stopped under it, is carried on in its own chat instead:
+  **"Continue where it stopped"** on its row in the register, which starts it, or **"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.
   Putting the repository back to before the task is **"Restore"**; putting it back and re-running
@@ -899,8 +910,9 @@ const PHASE3_BG = `
   Когато е сгрешена проверката, а не prompt-ът, се редактира друго: **„Редактирай“** на картата
   на задачата, после **„Какво проверява“**, **„Трябва“** и **„Команда“** под **„Проверки“**, после
   **„Запази и върни в опашката“** — който, като всеки бутон за връщане в опашката, сам не пуска нищо.
-  Задача, завършила с **limit-reached** или **aborted**, защото ботът е спрял под нея, продължава в собствения си чат: **„Продължи в същия чат“**
-  на картата ѝ на страницата на сесията, после **„Пусни {n} задача(и)“** горе на същата страница.
+  Задача, спряна от лимит в настройките, или **aborted**, защото ботът е спрял под нея, продължава в собствения си чат:
+  **„Продължи откъдето спря“** на реда ѝ в регистъра, който я пуска, или **„Продължи в същия чат“** на картата ѝ на страницата на сесията,
+  после **„Пусни {n} задача(и)“** горе на същата страница.
   Когато провал се покаже, докато пускането още върви, **„Пауза след тази задача“** задържа
   останалото, докато го разбереш.
   Връщането на хранилището отпреди задачата е **„Върни“**; връщането му плюс ново изпълнение на

package/dist/src/plan/systemGuide.js

@@ -798,18 +798,34 @@ export const SYSTEM_GUIDE = [
                     {
                         key: 'home.tickForBoth',
                         kind: 'note',
-                        en: 'The ticks choose what to run and what to delete. Only sessions with something queued can be run.',
-                        bg: 'Отметките избират какво да се пусне и какво да се изтрие. Пускат се само сесии с нещо в опашката.',
-                        doesEn: 'One set of tick boxes serves both the run panel above and the delete button here.',
-                        doesBg: 'Един набор отметки обслужва и панела за пускане горе, и бутона за изтриване тук.',
+                        en: 'The first column of ticks manages the list — status and delete — and works while a run is going, except on the session running now. The second chooses what to run; only active sessions with something queued can be run.',
+                        bg: 'Първата колона отметки управлява списъка — статус и изтриване — и работи и докато тече пускане, освен за сесията, която работи в момента. Втората избира какво да се пусне; пускат се само активни сесии с нещо в опашката.',
+                        doesEn: 'Two sets of tick boxes: the first for status and delete, the second for the run panel above.',
+                        doesBg: 'Два набора отметки: първият за статус и изтриване, вторият за панела за пускане горе.',
+                    },
+                    {
+                        key: 'home.makeActive',
+                        kind: 'button',
+                        en: 'Make active',
+                        bg: 'Направи активни',
+                        doesEn: 'Every session ticked in the first column can be run again. New and imported sessions are active.',
+                        doesBg: 'Всички отметнати в първата колона сесии отново могат да се пускат. Новите и импортираните са активни.',
+                    },
+                    {
+                        key: 'home.makeInactive',
+                        kind: 'button',
+                        en: 'Make inactive',
+                        bg: 'Направи неактивни',
+                        doesEn: 'Sets them aside: nothing starts them — not a run of several, not "Continue" — until made active. Not for a running session.',
+                        doesBg: 'Оставя ги настрана: нищо не ги пуска — нито пускане на няколко, нито „Продължи“ — докато не станат активни. Не и за работеща сесия.',
                     },
                     {
                         key: 'home.deleteSelected',
                         kind: 'button',
                         en: 'Delete the {n} selected',
                         bg: 'Изтрий избраните {n}',
-                        doesEn: 'Deletes every ticked session after one question; the run folders and the chats survive.',
-                        doesBg: 'Изтрива всички отметнати сесии след един въпрос; папките под runs/ и разговорите остават.',
+                        doesEn: 'Deletes every session ticked in the first column after one question, also during a run; never the one running. Run folders and chats survive.',
+                        doesBg: 'Изтрива всички отметнати в първата колона сесии след един въпрос, и по време на пускане; никога работещата. Папките и разговорите остават.',
                     },
                     {
                         key: 'home.delete',
@@ -1474,8 +1490,8 @@ export const SYSTEM_GUIDE = [
                         kind: 'button',
                         en: 'Continue in the same chat',
                         bg: 'Продължи в същия чат',
-                        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} задача(и)“.',
+                        doesEn: 'On a task that stopped before it finished (a limit from the settings, 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',
@@ -2174,6 +2190,14 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'The same button once the story is open: folds it away again.',
                         doesBg: 'Същият бутон, когато историята е отворена: сгъва я обратно.',
                     },
+                    {
+                        key: 'reg.continueHere',
+                        kind: 'button',
+                        en: 'Continue where it stopped',
+                        bg: 'Продължи откъдето спря',
+                        doesEn: 'On a row stopped by a limit from the settings (minutes, messages, reply wait, rounds of fixing), by the bot stopping or by the operator: says what happens to the chat, branch and files, then starts that task alone in its chat.',
+                        doesBg: 'На ред, спрян от лимит в настройките (минути, съобщения, чакане на отговор, кръгове поправки), от спрял бот или от оператора: казва какво става с чата, клона и файловете, после пуска само тази задача в чата ѝ.',
+                    },
                     {
                         key: 'reg.fixPrompt',
                         kind: 'button',
@@ -2685,8 +2709,16 @@ export const SYSTEM_GUIDE = [
                         kind: 'checkbox',
                         en: 'Keep the projects on the Desktop',
                         bg: 'Дръж проектите на Desktop-а',
-                        doesEn: 'Copies every project on this page to its own Desktop folder before each run, which is how the files reach the chat.',
-                        doesBg: 'Копира всеки проект от тази страница в собствена папка на Desktop-а преди всяко пускане — така файловете стигат до чата.',
+                        doesEn: 'The master switch: copies the projects on this page to their own Desktop folders before a run and after every round of steps, which is how the files reach the chat.',
+                        doesBg: 'Главният ключ: копира проектите от тази страница в собствени папки на Desktop-а преди пускане и след всеки кръг стъпки — така файловете стигат до чата.',
+                    },
+                    {
+                        key: 'proj.desktopThis',
+                        kind: 'checkbox',
+                        en: 'Keep a copy of this project on the Desktop',
+                        bg: 'Дръж копие на този проект на Desktop-а',
+                        doesEn: 'Under each project, on by default: untick to keep that one off the Desktop while the switch is on. Greyed out while the switch is off.',
+                        doesBg: 'Под всеки проект, включено по подразбиране: махнете отметката, за да не се копира точно той, докато ключът е включен. Неактивно, докато ключът е изключен.',
                     },
                     {
                         key: 'proj.folders',
@@ -2844,6 +2876,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',

package/dist/src/session/compose.js

@@ -11,7 +11,7 @@ const TASK_HEADER = '## Task';
  * and a note that is empty simply leaves nothing behind.
  */
 function runnerBlock(input) {
-    const notes = [input.workDirNote, input.readOnlyNote, input.scopeNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
+    const notes = [input.workDirNote, input.readOnlyNote, input.scopeNote, input.approachesNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
     return notes.length > 0 ? `${notes.join('\n\n')}\n\n` : '';
 }
 /**
@@ -54,8 +54,23 @@ function whyItStopped(c) {
         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.`;
+    // Out of rounds of fixing: something did say no, and the chat needs to hear it was not waved through.
+    if (c.limit?.setting === 'maxCheckRounds' || c.limit?.setting === 'maxReviewRounds') {
+        return (`It stopped because the runner's limit of ${LIMIT_WORDS[c.limit.setting](c.limit.value)} was reached${why}. ` +
+            'What was still failing then is still open: deal with it first. The count starts again now. The files are as you left them.');
+    }
+    const which = c.limit ? ` of ${LIMIT_WORDS[c.limit.setting](c.limit.value)}` : '';
+    return `It stopped because the runner's limit${which} was reached${why} — not because anything failed. The files are as you left them.`;
 }
+/** Each limit from the settings, as the chat is told about it. See `TaskLimit`. */
+const LIMIT_WORDS = {
+    maxRunMinutes: (n) => `${n} minutes per task`,
+    maxIterations: (n) => `${n} messages per task`,
+    replyTimeoutSec: (n) => `${n} seconds to wait for one reply`,
+    maxFormatRetries: (n) => `${n} replies in the wrong format in a row`,
+    maxCheckRounds: (n) => `${n} rounds of fixing failed checks`,
+    maxReviewRounds: (n) => `${n} rounds of fixing review findings`,
+};
 export function composeOpening(input) {
     const taskBlock = `${TASK_HEADER} ${input.taskNumber}: ${input.taskTitle.trim() || 'untitled'}\n\n${input.prompt.trim()}`;
     /*

package/dist/src/session/exportRecord.js

@@ -87,10 +87,17 @@ function versionControlLines(task, session) {
     if (!vcs.branch)
         return [`version control : did not run — ${vcs.problem}`];
     const commits = vcs.commits ?? [];
+    // In the order it happened: the tree before the runner's commit, the commit, the tree after it.
+    const before = vcs.beforeCommit;
+    const after = vcs.afterCommit;
     const lines = [
         `branch     : ${vcs.branch}`,
         `started at : ${vcs.baseCommit ? vcs.baseCommit.slice(0, 8) : '—'} (the commit this task branched from)`,
-        `commit     : ${vcs.commit ? vcs.commit.slice(0, 8) : 'none — the task changed no files'}`,
+        ...(before ? [`before commit: ${before.changed.length} path(s) changed or new in the working tree${before.changed.length ? ` — ${before.changed.slice(0, 10).join(', ')}` : ''}`] : []),
+        `commit     : ${vcs.commit ? vcs.commit.slice(0, 8) : vcs.problem ? 'none — see the note below' : 'none — the task changed no files'}`,
+        ...(after
+            ? [`after commit: on ${after.branch ?? '?'} at ${after.head ? after.head.slice(0, 8) : '?'}, ${after.clean ? 'working tree clean' : `still uncommitted: ${after.changed.slice(0, 10).join(', ')}`}`]
+            : []),
         `commits    : ${commits.length} on this branch since it was cut`,
     ];
     for (const line of commits)