copilot-operator 0.1.11 → 0.1.13

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';
@@ -42,10 +42,10 @@ 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 { projectNameFor, projectTargetDir, removeLegacyFlatMirror } from '../context/desktopMirror.js';
+import { mirrorProject, describeMirror, MirrorSelectionError } from '../context/projectMirror.js';
+import { keptOnDesktop, mirrorSourceRoot, projectNameFor, projectTargetDir, removeLegacyFlatMirror } from '../context/desktopMirror.js';
 import { prepareForTask, commitTaskResult, repoDirOf } from '../vcs/taskVcs.js';
 import { exportMachine, writeAttemptRecord } from '../session/exports.js';
 /** Why a task that was reported as done is being closed as failed. */
@@ -384,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.
@@ -456,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}`,
@@ -487,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();
         /*
@@ -612,6 +670,12 @@ export async function runTask(transport, session, task, deps) {
         const prepared = await prepareForTask(session, task, bus, async (mutate) => {
             await store.updateSession(session.id, mutate);
         }, () => store.listSessions());
+        if (prepared.refuse) {
+            await setTask((t) => {
+                t.vcs = prepared.vcs;
+            });
+            return await finish('failed', prepared.refuse);
+        }
         if (prepared.vcs.branch || prepared.vcs.problem) {
             await setTask((t) => {
                 t.vcs = prepared.vcs;
@@ -645,7 +709,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');
@@ -656,11 +722,30 @@ export async function runTask(transport, session, task, deps) {
         if (session.mirror.enabled && session.mirror.rootDir) {
             // One folder per project, and the project's name in front of every file name, so three
             // repositories mirrored in turn do not delete each other's copies or collide in the chat.
-            const projectName = projectNameFor(session.mirror.rootDir, cfg);
-            const targetDir = projectTargetDir(cfg, projectName);
+            // The bot's own Desktop copy named as the root means the project it is a copy of. See `mirrorSourceRoot`.
+            const source = mirrorSourceRoot(cfg, session.mirror.rootDir);
+            if ('problem' in source) {
+                sink.event('mirror-refused', { error: source.problem }, source.problem, 'error');
+                return await finish('failed', `${source.problem} Nothing was sent to the chat.`);
+            }
+            if (source.fromCopy) {
+                sink.event('mirror-source', { asked: source.fromCopy, used: source.rootDir }, `the root of the files to attach is the bot's Desktop copy ${source.fromCopy}; they are copied from the project itself, ${source.rootDir}`, 'warn');
+            }
+            const sourceRoot = source.rootDir;
+            const projectName = projectNameFor(sourceRoot, cfg);
+            // A project kept on the Desktop has its folder there looked after by the Desktop mirror; the
+            // attachments are copied into this attempt's own folder instead. See `keptOnDesktop`.
+            const onDesktop = keptOnDesktop(cfg, sourceRoot);
+            const targetDir = onDesktop ? log.path('attachments') : 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,
+                rootDir: sourceRoot,
+                // `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,
@@ -673,8 +758,12 @@ export async function runTask(transport, session, task, deps) {
                 ignoreDirs: cfg.projectMirror.ignoreDirs,
                 includeEnvFiles: session.mirror.includeEnvFiles ?? cfg.projectMirror.includeEnvFiles,
                 maxFileBytes: cfg.projectMirror.maxFileBytes,
-            });
-            sink.event('mirror', { targetDir, ...result }, `project mirror: ${describeMirror(result)}`);
+            }).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, onDesktop, ...result }, `project mirror${onDesktop ? ' (attachments, in the run folder: the Desktop copy is kept by the Desktop mirror)' : ''}: ${describeMirror(result)}`);
             if (session.mirror.includeEnvFiles) {
                 const envCount = Object.keys(result.mapping).filter((p) => /(^|\/)\.env(\.|$)/i.test(p)).length;
                 if (envCount > 0) {
@@ -786,14 +875,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,
@@ -811,7 +907,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
@@ -885,6 +983,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';
             }
@@ -944,7 +1043,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;
@@ -1129,6 +1228,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';
             }
@@ -1190,10 +1290,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,
@@ -1214,6 +1318,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);
                 }
@@ -1517,6 +1622,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);
@@ -1604,6 +1712,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');
@@ -1648,6 +1763,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:
 
@@ -427,6 +432,16 @@ session works on, without the prefix — and \`startFrom\` with \`baseBranch\`.
 - \`"previous-session"\` — the session carries on from the end of the branch of the session that
   ran before it **in the same repository**, so the sessions form a chain. The first session of
   such a chain starts from \`baseBranch\`. Sessions in other repositories do not count.
+- \`"existing-branch"\` with \`existingBranch\` — no new branch at all: every task of the session
+  works on that existing local branch, exactly as named (\`"existingBranch": "recovery/apz-migration"\`),
+  one after another, building on what is already on it. For new work that continues a branch the
+  user already has. The branch must exist when the plan is imported; \`branchMode\`, \`branchName\`
+  and the prefix do not apply.
+
+Before a session's first branch the runner fetches and fast-forwards the branch it starts from
+(\`baseBranch\`, or \`existingBranch\`), so the work begins from the server's code; it never resets or
+merges. \`"updateFromRemote": false\` turns that off — only when the user asks to work offline or from
+local commits on purpose.
 
 Put the same \`startFrom\` on every session that works in one repository unless the user wants it
 mixed. Leaving it out keeps the old behaviour — whatever branch the repository is on — which is
@@ -460,7 +475,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** решава откъде започва работата на всяка сесия, и изборът е на потребителя — питай:
 
@@ -469,6 +489,15 @@ const VCS_DETAIL_BG = `
 - \`"previous-session"\` — сесията продължава от края на клона на сесията, пусната преди нея **в
   същото хранилище**, така че сесиите образуват верига. Първата сесия от веригата тръгва от
   \`baseBranch\`. Сесии в други хранилища не се броят.
+- \`"existing-branch"\` с \`existingBranch\` — без нов клон: всяка задача от сесията работи на този
+  съществуващ локален клон, точно с това име (\`"existingBranch": "recovery/apz-migration"\`), една след
+  друга, върху това, което вече е там. За нова работа, която продължава клон, който потребителят вече
+  има. Клонът трябва да съществува при импорта; \`branchMode\`, \`branchName\` и представката не се прилагат.
+
+Преди първия клон на сесията runner-ът прави fetch и fast-forward на клона, от който тя тръгва
+(\`baseBranch\` или \`existingBranch\`), така че работата започва от кода на сървъра; никога не прави
+reset или merge. \`"updateFromRemote": false\` го изключва — само ако потребителят поиска да работи
+офлайн или нарочно от локални commit-и.
 
 Сложи един и същ \`startFrom\` на всички сесии в едно хранилище, освен ако потребителят не иска
 различни. Ако го пропуснеш, остава старото поведение — от който клон е хранилището в момента —
@@ -738,8 +767,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 +929,9 @@ const PHASE3_BG = `
   Когато е сгрешена проверката, а не prompt-ът, се редактира друго: **„Редактирай“** на картата
   на задачата, после **„Какво проверява“**, **„Трябва“** и **„Команда“** под **„Проверки“**, после
   **„Запази и върни в опашката“** — който, като всеки бутон за връщане в опашката, сам не пуска нищо.
-  Задача, завършила с **limit-reached** или **aborted**, защото ботът е спрял под нея, продължава в собствения си чат: **„Продължи в същия чат“**
-  на картата ѝ на страницата на сесията, после **„Пусни {n} задача(и)“** горе на същата страница.
+  Задача, спряна от лимит в настройките, или **aborted**, защото ботът е спрял под нея, продължава в собствения си чат:
+  **„Продължи откъдето спря“** на реда ѝ в регистъра, който я пуска, или **„Продължи в същия чат“** на картата ѝ на страницата на сесията,
+  после **„Пусни {n} задача(и)“** горе на същата страница.
   Когато провал се покаже, докато пускането още върви, **„Пауза след тази задача“** задържа
   останалото, докато го разбереш.
   Връщането на хранилището отпреди задачата е **„Върни“**; връщането му плюс ново изпълнение на

package/dist/src/plan/importPlan.js

@@ -169,6 +169,9 @@ persona = '') {
         const vcs = { ...DEFAULT_VCS, ...(planned.vcs ?? {}) };
         vcs.branchPrefix = vcs.branchPrefix.trim() || DEFAULT_VCS.branchPrefix;
         vcs.repoDir = vcs.repoDir.trim();
+        // A branch to carry on, given alone, is that choice: see `VersionControl.startFrom`.
+        if (vcs.existingBranch?.trim())
+            vcs.startFrom = 'existing-branch';
         const group = planned.conversationGroup.trim() || sharedGroup;
         await store.updateSession(created.id, (s) => {
             s.onFailure = planned.onFailure;

package/dist/src/plan/schema.js

@@ -44,16 +44,40 @@ const VcsInput = z
      * Absent keeps the old behaviour, wherever the repository is. See `VersionControl.startFrom`.
      */
     startFrom: z
-        .enum(['branch', 'previous-session', 'head'], {
-        error: 'startFrom must be "branch" (every session starts from the local branch in baseBranch, "main" unless said otherwise) or "previous-session" (each session carries on from the branch of the session before it in the same repository).',
+        .enum(['branch', 'previous-session', 'head', 'existing-branch'], {
+        error: 'startFrom must be "branch" (every session starts from the local branch in baseBranch, "main" unless said otherwise), "previous-session" (each session carries on from the branch of the session before it in the same repository) or "existing-branch" (the session works on the existing branch named in existingBranch).',
     })
         .optional(),
     /** The local branch `startFrom: "branch"` starts from, and `previous-session`'s fallback. */
     baseBranch: z.string().trim().optional(),
+    /**
+     * The existing local branch the whole session works on, exactly as named: no new branch, no
+     * prefix. Given alone it means `startFrom: "existing-branch"`. See `VersionControl.startFrom`.
+     */
+    existingBranch: z.string().trim().optional(),
+    /**
+     * Fetch and fast-forward the branch the session starts from before its first branch is cut.
+     * Absent means true. See `VersionControl.updateFromRemote`.
+     */
+    updateFromRemote: z.boolean().optional(),
 }, {
     error: 'Every session needs a "vcs" object saying whether the runner does version control for it and, when it does, which git repository to work in. Ask the user both questions and write the answers here.',
 })
     .superRefine((vcs, ctx) => {
+    if (vcs.startFrom === 'existing-branch' && !vcs.existingBranch) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['existingBranch'],
+            message: 'startFrom is "existing-branch", so "existingBranch" must name the local branch to carry on, exactly as it is in git (for example "recovery/apz-migration").',
+        });
+    }
+    if (vcs.existingBranch && vcs.startFrom && vcs.startFrom !== 'existing-branch') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['existingBranch'],
+            message: `"existingBranch" carries on a branch that exists, and startFrom "${vcs.startFrom}" cuts a new one. Keep one: startFrom "existing-branch" with existingBranch, or leave existingBranch out.`,
+        });
+    }
     if (vcs.enabled && !vcs.repoDir.trim()) {
         ctx.addIssue({
             code: 'custom',