copilot-operator 0.1.20 → 0.1.23

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

@@ -496,6 +496,14 @@ let OperatorController = class OperatorController {
     repoSync(dir) {
         return this.ops.syncPlan(dir ?? '').catch(fail);
     }
+    /** "Prepare the folder from the remote main branch": what it would do (fetches, changes nothing else). */
+    repoPreparePreview(body) {
+        return this.ops.preparePreview(body?.dir ?? '', body?.fetch !== false).catch(fail);
+    }
+    /** …and doing it, if the folder is still what the preview showed. */
+    repoPrepare(body) {
+        return this.ops.prepareProject(body?.dir ?? '', body?.fingerprint ?? '').catch(fail);
+    }
     repo(dir) {
         const problem = this.ops.repoProblem(dir ?? '');
         return problem ? { ok: false, problem } : { ok: true };
@@ -504,6 +512,18 @@ let OperatorController = class OperatorController {
     vcsStatus(id) {
         return this.ops.vcsStatus(id).catch(fail);
     }
+    /** "Prepare version control for this run": one group per repository of the sessions given. */
+    runVcs(ids, tasks) {
+        const only = (tasks ?? '').split(',').map((t) => t.trim()).filter(Boolean);
+        return this.ops.runVcs((ids ?? '').split(',').map((s) => s.trim()).filter(Boolean), only.length > 0 ? new Set(only) : undefined).catch(fail);
+    }
+    /** One action of that panel, for one repository. */
+    runVcsPrepare(body) {
+        const actions = ['review-inputs', 'snapshot-on-base', 'snapshot-here', 'use-current-branch', 'allow-snapshot'];
+        if (!actions.includes(body?.action ?? ''))
+            return Promise.resolve({ ok: false, problem: 'unknown action' });
+        return this.ops.runVcsPrepare(body?.sessionIds ?? [], body?.repoDir ?? '', body.action, body?.choices ?? {}).catch(fail);
+    }
     /** The operator's approval of the starting snapshot: one choice per file of the list they saw. */
     vcsSnapshot(id, body) {
         return this.ops.vcsSnapshot(id, body?.choices ?? {}).catch(fail);
@@ -1028,6 +1048,20 @@ __decorate([
     __metadata("design:paramtypes", [String]),
     __metadata("design:returntype", Promise)
 ], OperatorController.prototype, "repoSync", null);
+__decorate([
+    Post('repo/prepare/preview'),
+    __param(0, Body()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], OperatorController.prototype, "repoPreparePreview", null);
+__decorate([
+    Post('repo/prepare'),
+    __param(0, Body()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], OperatorController.prototype, "repoPrepare", null);
 __decorate([
     Get('repo'),
     __param(0, Query('dir')),
@@ -1042,6 +1076,21 @@ __decorate([
     __metadata("design:paramtypes", [String]),
     __metadata("design:returntype", Promise)
 ], OperatorController.prototype, "vcsStatus", null);
+__decorate([
+    Get('batch/vcs'),
+    __param(0, Query('ids')),
+    __param(1, Query('tasks')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], OperatorController.prototype, "runVcs", null);
+__decorate([
+    Post('batch/vcs/prepare'),
+    __param(0, Body()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], OperatorController.prototype, "runVcsPrepare", null);
 __decorate([
     Post('sessions/:id/vcs/snapshot'),
     __param(0, Param('id')),

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

@@ -45,7 +45,11 @@ 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 { planPrepare, prepareFromRemote } from '../vcs/prepareFromRemote.js';
+import { askpassProgram } from '../vcs/remoteAuth.js';
+import { appendRunLog } from '../session/runLog.js';
 import { dirtyPolicy, takeSnapshot } from '../vcs/snapshot.js';
+import { runVcsPreflight, runVcsPrepare } from '../vcs/runPreflight.js';
 import { normalisePatterns } from '../vcs/inputs.js';
 import { coveredByArtifacts } from '../vcs/artifacts.js';
 import { botVersion } from '../config/version.js';
@@ -917,6 +921,12 @@ let OperatorService = class OperatorService {
             // A run of one is still a run, and it records the same thing a batch does, so that going
             // back and starting again from a task works the same whether one session was started or six.
             // Recorded by `beginRun` once the start is accepted, not here: see `recordOnSession`.
+            // Version control first, before anything opens the browser: see `vcs/runPreflight.ts`.
+            const notReady = await this.runPreflight(runGroup.id, [sessionId]);
+            if (notReady) {
+                this.releaseBrowser(claim.holder);
+                return { started: false, reason: notReady };
+            }
             const begun = await this.beginRun(sessionId, mode, undefined, runGroup, undefined, { recordOnSession: true });
             if (!begun.started) {
                 this.releaseBrowser(claim.holder);
@@ -1026,8 +1036,10 @@ let OperatorService = class OperatorService {
             transport,
             runGroup,
             onlyTasks,
+            vcsGate: (s) => this.sessionVcsGate(s, onlyTasks),
+            ...(transport || !runGroup ? {} : { beforeBrowser: () => this.browserRequested(runGroup.id, [sessionId]) }),
         })
-            .then(async (outcome) => ({ ...(await this.tally(sessionId, queuedIds)), paused: outcome.paused }))
+            .then(async (outcome) => ({ ...(await this.tally(sessionId, queuedIds)), paused: outcome.paused, ...(outcome.refused ? { error: outcome.refused } : {}) }))
             .catch(async (e) => {
             this.bus.publish({ sessionId, type: 'run-failed', level: 'error', message: e.message });
             return { ...(await this.tally(sessionId, queuedIds)), error: e.message };
@@ -1097,7 +1109,12 @@ let OperatorService = class OperatorService {
      * directory walk every few seconds, on every page, to light up a dot would be a bad trade.
      */
     activity() {
-        return { running: this.running.size > 0, sessions: this.running.size, batch: this.batch?.running === true };
+        /*
+         * A run being started — its version control checked before the browser opens — is not running yet
+         * and not idle either: `starting` says so, so "nothing is happening" is not read in that moment.
+         */
+        const starting = this.running.size === 0 && !this.batch?.running && (this.browser?.kind === 'run' || this.browser?.kind === 'batch');
+        return { running: this.running.size > 0, sessions: this.running.size, batch: this.batch?.running === true, starting };
     }
     /** The batch in progress, or the last one that ran, or null if none ever has. */
     batchState() {
@@ -1156,7 +1173,13 @@ let OperatorService = class OperatorService {
             await this.init();
             if (wanted.length === 0)
                 return { started: false, reason: 'no sessions were selected' };
-            const begun = await this.prepareBatch(wanted, onlyTasks, mode, onFailure, model, reviewModel, name);
+            // Version control first, before anything opens the browser: see `vcs/runPreflight.ts`.
+            // The batch's id first, so the preflight is recorded under the run it decides about.
+            const batchId = newId('b-');
+            const notReady = await this.runPreflight(batchId, wanted, onlyTasks);
+            if (notReady)
+                return { started: false, reason: notReady };
+            const begun = await this.prepareBatch(wanted, onlyTasks, mode, onFailure, model, reviewModel, name, batchId);
             if (!begun.batch)
                 return { started: false, reason: begun.reason };
             this.batch = begun.batch;
@@ -1188,7 +1211,9 @@ let OperatorService = class OperatorService {
      * an unattended run may begin, and the models the run panel chose. A refusal comes back as the
      * reason; nothing is started here.
      */
-    async prepareBatch(wanted, onlyTasks, mode, onFailure, model, reviewModel, name) {
+    async prepareBatch(wanted, onlyTasks, mode, onFailure, model, reviewModel, name, 
+    /** The id its preflight was recorded under; a new one when there was none. */
+    id = newId('b-')) {
         // Worked out here rather than asked of the operator again: every way into this — the run
         // panel, continuing after a failure, "Run again from here" — either has a field they may
         // have left empty or has no field at all.
@@ -1252,7 +1277,7 @@ let OperatorService = class OperatorService {
         }
         return {
             batch: {
-                id: newId('b-'),
+                id,
                 startedAt: new Date().toISOString(),
                 name: chosenName,
                 ...(onlyTasks ? { onlyTasks: [...onlyTasks] } : {}),
@@ -1355,6 +1380,7 @@ let OperatorService = class OperatorService {
         let browser = null;
         try {
             const cfg = await this.settings.load();
+            await this.browserRequested(batch.id, batch.sessions.filter((x) => x.state === 'waiting').map((x) => x.sessionId));
             browser = await openBrowser(cfg, this.bus, join(cfg.resolved.runsDir, '_browser'), batch.id);
             this.bus.publish({
                 sessionId: batch.sessions[0]?.sessionId ?? batch.id,
@@ -1855,6 +1881,124 @@ let OperatorService = class OperatorService {
         return this.bus.subscribe(sessionId, handler);
     }
     // --- version control ----------------------------------------------------------------------
+    /**
+     * Version control for the sessions of a run, one group per repository, with what can be done about
+     * it from the run screen. See `vcs/runPreflight.ts`. Only sessions that have something queued count.
+     */
+    async runVcs(sessionIds, onlyTasks) {
+        await this.init();
+        const sessions = [];
+        for (const id of sessionIds) {
+            const s = await this.store.getSession(id);
+            if (s && queuedToRun(s, onlyTasks).length > 0)
+                sessions.push(s);
+        }
+        return await runVcsPreflight(sessions, () => this.store.listSessions());
+    }
+    /**
+     * The run's version control preflight: why the run may not start, said before anything opens the
+     * browser, creates a task attempt or emits `task-started`; null when it may.
+     *
+     * Recorded as it happens, in the run's own log (`session/runLog.ts`) and on each session's event
+     * stream: `run-preflight-started`, one `repository-preflight` per repository, `baseline-created` for
+     * a starting snapshot taken on the run screen, `snapshot-approval-required` where the operator has a
+     * fix to press, then `run-preflight-passed` or `run-preflight-refused`. The browser is asked for
+     * only after a pass (`browser-launch-requested`), so the export can show the order.
+     */
+    async runPreflight(runId, sessionIds, onlyTasks) {
+        const cfg = await this.settings.load();
+        const log = [];
+        const note = (type, message, data, ids, level = 'info') => {
+            log.push({ at: new Date().toISOString(), type, message, data });
+            for (const id of ids)
+                this.bus.publish({ sessionId: id, type, level, message, data: { runId, ...data } });
+        };
+        note('run-preflight-started', `version control preflight for ${sessionIds.length} session(s), before the browser opens`, { sessions: sessionIds }, sessionIds);
+        const groups = await this.runVcs(sessionIds, onlyTasks);
+        for (const g of groups) {
+            const ids = g.sessions.map((x) => x.id);
+            const first = ids[0] ? await this.store.getSession(ids[0]) : null;
+            const start = first?.vcsStart;
+            const untouched = !!first && !first.tasks.some((t) => t.startedAt);
+            if (start?.kind === 'snapshot' && start.snapshot?.approved && untouched) {
+                note('baseline-created', `starting snapshot ${start.commit.slice(0, 8)} on ${start.branch ?? '?'}, approved ${start.snapshot.approvedAt ?? ''}${start.snapshot.onBase ? ` on top of "${start.snapshot.fromBranch}"` : ''}`, {
+                    repoDir: g.repoDir,
+                    commit: start.commit,
+                    branch: start.branch,
+                    approvedAt: start.snapshot.approvedAt,
+                    onBase: !!start.snapshot.onBase,
+                    included: start.snapshot.included.length,
+                }, ids);
+            }
+            note('repository-preflight', `${g.repoDir}: ${g.ready ? 'ready' : g.problem ?? 'needs your approval'}`, {
+                repoDir: g.repoDir,
+                ready: g.ready,
+                branch: g.branch,
+                head: g.head,
+                ...(g.baseBranch ? { baseBranch: g.baseBranch, baseHead: g.baseHead } : {}),
+                sessions: g.sessions.map((x) => ({ id: x.id, name: x.name, startFrom: x.startFrom, role: x.role })),
+                inputPatterns: g.inputPatterns,
+                inputs: g.inputs.map((e) => e.path),
+                unrelated: g.unrelated.map((u) => u.path),
+                ...(g.problem ? { problem: g.problem } : {}),
+            }, ids, g.ready ? 'info' : 'warn');
+            const fixes = g.actions.filter((a) => a.available && a.id !== 'review-inputs').map((a) => a.id);
+            if (!g.ready && fixes.length > 0) {
+                note('snapshot-approval-required', `${g.repoDir}: nothing runs until one of these is pressed on the run screen: ${fixes.join(', ')}`, { repoDir: g.repoDir, actions: fixes }, ids, 'warn');
+            }
+        }
+        const open = groups.filter((g) => !g.ready);
+        const reason = open.length === 0
+            ? null
+            : 'Version control is not ready for this run, so nothing was opened or sent. ' +
+                open.map((g) => `${g.repoDir}: ${g.problem ?? 'it needs your approval'}`).join(' ') +
+                ' Fix it under "Prepare version control for this run" on the Sessions page.';
+        if (reason)
+            note('run-preflight-refused', reason, { repositories: open.map((g) => g.repoDir) }, sessionIds, 'warn');
+        else
+            note('run-preflight-passed', `version control is ready in ${groups.length} repositor${groups.length === 1 ? 'y' : 'ies'}; the browser may open`, { repositories: groups.map((g) => g.repoDir) }, sessionIds);
+        await appendRunLog(cfg.resolved.runsDir, runId, log).catch(() => undefined);
+        return reason;
+    }
+    /**
+     * The same rule for one session that has not started, when its turn comes: see `RunDeps.vcsGate`.
+     * A session that has started is past its first preparation; its tasks are prepared as they come.
+     */
+    async sessionVcsGate(session, onlyTasks) {
+        if (!session.vcs?.enabled || session.vcsBaseCommit)
+            return null;
+        if (queuedToRun(session, onlyTasks).length === 0)
+            return null;
+        const [group] = await runVcsPreflight([session], () => this.store.listSessions());
+        if (!group || group.ready)
+            return null;
+        return `Version control is not ready for "${session.name}", so it did not start and its tasks stay queued: ${group.problem ?? 'it needs your approval'} Fix it under "Prepare version control for this run" on the Sessions page.`;
+    }
+    /** Recorded in the run's log just before the browser is opened for it: see `runPreflight`. */
+    async browserRequested(runId, sessionIds) {
+        const cfg = await this.settings.load();
+        const entry = { at: new Date().toISOString(), type: 'browser-launch-requested', message: 'the version control preflight passed; opening the browser', data: { sessions: sessionIds } };
+        for (const id of sessionIds)
+            this.bus.publish({ sessionId: id, type: entry.type, level: 'info', message: entry.message, data: { runId, ...entry.data } });
+        await appendRunLog(cfg.resolved.runsDir, runId, [entry]).catch(() => undefined);
+    }
+    /** One action of "Prepare version control for this run". Refused while anything runs in that repository. */
+    async runVcsPrepare(sessionIds, repoDir, action, choices) {
+        await this.init();
+        if (this.batch?.running)
+            return { ok: false, problem: 'A run is going. Stop it before preparing version control.' };
+        const other = await this.runningIn(repoDir);
+        if (other)
+            return { ok: false, problem: `Session "${other.name}" is running in this repository. Stop it first.` };
+        const sessions = [];
+        for (const id of sessionIds) {
+            const s = await this.store.getSession(id);
+            if (s && queuedToRun(s).length > 0)
+                sessions.push(s);
+        }
+        const done = await runVcsPrepare(sessions, repoDir, action, choices && typeof choices === 'object' ? choices : {}, this.bus, async (id, mutate) => void (await this.store.updateSession(id, mutate)), () => this.store.listSessions());
+        return done.ok ? { ok: true, result: done.result } : { ok: false, problem: done.problem };
+    }
     /** Whether version control can do its job in this session, asked before a run. */
     async vcsStatus(sessionId) {
         await this.init();
@@ -2328,15 +2472,45 @@ let OperatorService = class OperatorService {
      */
     async syncPlan(dir) {
         await this.init();
+        await this.knownProjectFolder(dir, 'no command is offered for it');
+        return await planSync(resolve(dir.trim()));
+    }
+    /** Throws unless the folder is a project in Settings or the repository of a session. */
+    async knownProjectFolder(dir, otherwise) {
         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.projectDir ?? ''])]
             .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.');
+            throw new Error(`That folder is not one of the projects in Settings or the repository of a session, so ${otherwise}.`);
         }
-        return await planSync(resolve(dir.trim()));
+    }
+    /**
+     * "Prepare the folder from the remote main branch", first half: fetches and says what would be
+     * kept where and what the folder would be. See `vcs/prepareFromRemote.ts`.
+     */
+    async preparePreview(dir, fetch = true) {
+        await this.init();
+        await this.knownProjectFolder(dir, 'it is not prepared from here');
+        // The operator pressed the button and is looking: the remote may ask for a password through Git's own window.
+        return await planPrepare(resolve(dir.trim()), { fetch, askpass: fetch ? await askpassProgram() : null });
+    }
+    /**
+     * The second half: does it, if the folder is still what the preview showed. Refused while anything
+     * runs, or is being started, in that folder or one around it: it moves the checkout.
+     */
+    async prepareProject(dir, fingerprint) {
+        await this.init();
+        await this.knownProjectFolder(dir, 'it is not prepared from here');
+        if (this.batch?.running)
+            return { ok: false, problem: 'A run is going. Stop it before preparing the folder; nothing was changed.' };
+        if (this.browser?.kind === 'run' || this.browser?.kind === 'batch')
+            return { ok: false, problem: 'A run is being started. Wait for it, or stop it, before preparing the folder; nothing was changed.' };
+        const other = await this.runningIn(dir);
+        if (other)
+            return { ok: false, problem: `Session "${other.name}" is running in this folder. Stop it before preparing the folder; nothing was changed.` };
+        return await prepareFromRemote(resolve(dir.trim()), String(fingerprint ?? ''));
     }
     // --- the project being worked on ---------------------------------------------------------
     /**

package/dist/src/orchestrator/taskRunner.js

@@ -630,11 +630,16 @@ export async function runTask(transport, session, task, deps) {
          */
         const patterns = artifactPatterns(session.vcs);
         const projectRoot = repoDirOf(session) || session.projectDir?.trim() || '';
-        if ((patterns.length > 0 || (task.outputs?.length ?? 0) > 0) && projectRoot) {
+        // Only after the task started: one refused before it ran made nothing, and what is there is not its own.
+        if ((patterns.length > 0 || (task.outputs?.length ?? 0) > 0) && projectRoot && artifactsBefore) {
             // Only what this task made or changed, inside its scope, or declared as its outputs.
             const kept = await keepArtifacts(projectRoot, patterns, join(artifactsDir, 'project'), { before: artifactsBefore, scope: task.scope, outputs: task.outputs })
                 .catch((e) => ({ kept: [], skipped: [`(all: ${e.message})`], unchanged: 0, outsideScope: [] }));
-            sink.event('artifacts-kept', { kept: kept.kept.length, skipped: kept.skipped, unchanged: kept.unchanged, outsideScope: kept.outsideScope.slice(0, 20) }, `artifacts kept with the run: ${kept.kept.length} file(s) this task made or changed` +
+            /*
+             * `artifacts-kept` only when something was: files that were there before and untouched are not this
+             * task's evidence, and an event of that name with nothing in it read as if they had been collected.
+             */
+            sink.event(kept.kept.length > 0 || kept.skipped.length > 0 ? 'artifacts-kept' : 'artifacts-none', { kept: kept.kept.length, skipped: kept.skipped, unchanged: kept.unchanged, outsideScope: kept.outsideScope.slice(0, 20) }, `artifacts kept with the run: ${kept.kept.length} file(s) this task made or changed` +
                 `${kept.unchanged > 0 ? `; ${kept.unchanged} already there and untouched, not kept` : ''}` +
                 `${kept.outsideScope.length > 0 ? `; ${kept.outsideScope.length} outside the task's scope, not kept` : ''}` +
                 `${kept.skipped.length > 0 ? `; not kept: ${kept.skipped.slice(0, 5).join('; ')}` : ''}`, kept.skipped.length > 0 ? 'warn' : 'info');
@@ -2226,6 +2231,12 @@ export async function runSession(sessionId, deps) {
         bus.publish({ sessionId, type: 'session-idle', level: 'info', message: 'no queued tasks' });
         return { ran: 0, paused: false };
     }
+    // Version control before anything else: a session that may not start is refused with its tasks queued.
+    const refused = deps.vcsGate ? await deps.vcsGate(session) : null;
+    if (refused) {
+        bus.publish({ sessionId, type: 'run-preflight-refused', level: 'warn', message: refused, data: { queued: queued.length } });
+        return { ran: 0, paused: false, refused };
+    }
     await store.updateSession(sessionId, (s) => {
         s.status = 'running';
     });
@@ -2245,6 +2256,7 @@ export async function runSession(sessionId, deps) {
             await enterSessionConversation(borrowed, session, { closeOnFailure: false });
         }
         else {
+            await deps.beforeBrowser?.();
             transport = await openSessionTransport(cfg, session, bus, sessionRunsDir);
         }
         const chat = transport;

package/dist/src/plan/systemGuide.js

@@ -685,6 +685,110 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'The model that reviews each task afterwards, chosen separately from the one doing the work.',
                         doesBg: 'Моделът, който проверява всяка задача после, избран отделно от този, който върши работата.',
                     },
+                    {
+                        key: 'runvcs.title',
+                        kind: 'note',
+                        en: 'Prepare version control for this run',
+                        bg: 'Подготви контрола на версиите за това пускане',
+                        doesEn: 'Shown under the run settings when a repository of the ticked sessions is not ready: one box per repository, with the fixes. The run buttons stay off until every box is ready, and a start is refused before the browser opens.',
+                        doesBg: 'Показва се под настройките на пускането, когато хранилище на отметнатите сесии не е готово: по една кутия на хранилище, с решенията. Бутоните за пускане остават изключени, докато всяка кутия не е готова, а старт се отказва преди да се отвори браузърът.',
+                    },
+                    {
+                        key: 'runvcs.repo',
+                        kind: 'note',
+                        en: 'Repository',
+                        bg: 'Хранилище',
+                        doesEn: 'The repository the box is about.',
+                        doesBg: 'Хранилището, за което е кутията.',
+                    },
+                    {
+                        key: 'runvcs.current',
+                        kind: 'note',
+                        en: 'Current branch and HEAD',
+                        bg: 'Текущ клон и HEAD',
+                        doesEn: 'Where the repository is now.',
+                        doesBg: 'Къде е хранилището сега.',
+                    },
+                    {
+                        key: 'runvcs.base',
+                        kind: 'note',
+                        en: 'Requested base branch and HEAD',
+                        bg: 'Поискан базов клон и HEAD',
+                        doesEn: 'The branch the plan asked the sessions to start from, and its tip.',
+                        doesBg: 'Клонът, от който планът иска сесиите да тръгнат, и върхът му.',
+                    },
+                    {
+                        key: 'runvcs.sessions',
+                        kind: 'note',
+                        en: 'Sessions',
+                        bg: 'Сесии',
+                        doesEn: 'The ticked sessions in this repository and how each starts: first, from the same base, or carrying on the one before.',
+                        doesBg: 'Отметнатите сесии в това хранилище и как тръгва всяка: първа, от същата база или продължава предната.',
+                    },
+                    {
+                        key: 'runvcs.patterns',
+                        kind: 'note',
+                        en: 'Input file patterns',
+                        bg: 'Шаблони за входни файлове',
+                        doesEn: 'The "Input files" of the first session.',
+                        doesBg: '„Входни файлове“ на първата сесия.',
+                    },
+                    {
+                        key: 'runvcs.review',
+                        kind: 'button',
+                        en: 'Review input files',
+                        bg: 'Прегледай входните файлове',
+                        doesEn: 'Lists the matched input files with git status and size. Changes nothing.',
+                        doesBg: 'Показва съвпадналите входни файлове с git статус и размер. Нищо не променя.',
+                    },
+                    {
+                        key: 'runvcs.snapshotOnBase',
+                        kind: 'button',
+                        en: 'Create starting snapshot on {branch}',
+                        bg: 'Създай начална снимка върху {branch}',
+                        doesEn: 'Commits the approved input files on top of the base branch, on a new cop/baseline/ branch, without switching branches or touching the checkout; every session of the run starting from that branch starts from it, chained ones carry it on. Recommended when the plan names that branch. Not offered while other files are uncommitted.',
+                        doesBg: 'Комитва одобрените входни файлове върху базовия клон, на нов клон cop/baseline/, без да сменя клона и без да пипа работното копие; всяка сесия от пускането, тръгваща от този клон, тръгва от снимката, а свързаните във верига я продължават. Препоръчано, когато планът посочва този клон. Не се предлага, докато има други некомитнати файлове.',
+                    },
+                    {
+                        key: 'runvcs.snapshotHere',
+                        kind: 'button',
+                        en: 'Create starting snapshot on {current}',
+                        bg: 'Създай начална снимка върху {current}',
+                        doesEn: 'Takes the listed files as the starting snapshot where the repository is, as the session page does: one commit on a new branch, the current branch not moved.',
+                        doesBg: 'Взема изброените файлове като начална снимка там, където е хранилището, както страницата на сесията: един комит на нов клон, текущият клон не се мести.',
+                    },
+                    {
+                        key: 'runvcs.useCurrent',
+                        kind: 'button',
+                        en: 'Use the current branch instead of {branch}',
+                        bg: 'Използвай текущия branch вместо {branch}',
+                        doesEn: 'The sessions start from the branch the repository is on instead of the base branch: their "Start from" becomes "From wherever the repository is". Nothing is committed.',
+                        doesBg: 'Сесиите тръгват от клона, на който е хранилището, вместо от базовия: „Откъде тръгва“ им става „Откъдето е хранилището“. Нищо не се комитва.',
+                    },
+                    {
+                        key: 'runvcs.allowSnapshot',
+                        kind: 'button',
+                        en: 'Take uncommitted changes as a starting snapshot',
+                        bg: 'Вземи некомитнатите промени като начална снимка',
+                        doesEn: 'Sets "Uncommitted changes" of the first session to "Take them as a starting snapshot", so the files are listed to approve. Nothing is committed.',
+                        doesBg: 'Задава „Некомитнати промени“ на първата сесия на „Запази ги като начална снимка“, за да се изброят файловете за одобрение. Нищо не се комитва.',
+                    },
+                    {
+                        key: 'runvcs.cancel',
+                        kind: 'button',
+                        en: 'Cancel',
+                        bg: 'Отказ',
+                        doesEn: 'Hides the fixes; nothing is changed and the run stays off.',
+                        doesBg: 'Скрива решенията; нищо не се променя и пускането остава изключено.',
+                    },
+                    {
+                        key: 'runvcs.showAgain',
+                        kind: 'button',
+                        en: 'Show the fixes again',
+                        bg: 'Покажи решенията отново',
+                        doesEn: 'Brings the fixes back after Cancel.',
+                        doesBg: 'Връща решенията след „Отказ“.',
+                    },
                     {
                         key: 'batch.run',
                         kind: 'button',
@@ -2837,28 +2941,52 @@ export const SYSTEM_GUIDE = [
                         doesBg: 'Секунди чакане на отговор от чата (по подразбиране 900); незавършен дотогава отговор проваля задачата с „Copilot did not finish a reply within …“.',
                     },
                     {
-                        key: 'sync.show',
+                        key: 'prep.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; ботът никога не я пуска.',
+                        en: 'Prepare the folder from the remote main branch',
+                        bg: 'Подготви папката от remote main',
+                        doesEn: 'Under each project in Settings and on a session’s version control: fetches, then shows what would be kept where — uncommitted changes and new files on a saved branch of their own, commits of the local main the remote lacks on another — and where the folder ends up (the remote main, nothing uncommitted). Changes nothing until "Confirm".',
+                        doesBg: 'Под всеки проект в Настройки и в контрола на версиите на сесия: изтегля и показва какво къде ще се запази — некомитнатите промени и новите файлове в отделен запазен клон, комитите на локалния main, които ги няма в remote, в друг — и къде ще е папката (основният клон на remote, без некомитнати промени). Нищо не се променя до „Потвърди“.',
                     },
                     {
-                        key: 'sync.copyPreview',
+                        key: 'prep.confirm',
                         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-ите, промените и новите файлове, които командата би махнала.',
+                        en: 'Confirm',
+                        bg: 'Потвърди',
+                        doesEn: 'Keeps everything as shown, then checks out the remote main branch as the local one and removes the new files from the folder (they are on the saved branch); ignored files stay. Refused if the folder changed since the preview, or while a run works in it. Afterwards the operator adds the files a task needs and the run screen offers a starting snapshot of them.',
+                        doesBg: 'Запазва всичко, както е показано, после избира основния клон на remote като локален и маха новите файлове от папката (те са в запазения клон); игнорираните остават. Отказва се, ако папката се е променила след прегледа или докато пускане работи в нея. След това операторът добавя файловете за задачата и екранът за пускане предлага начална снимка от тях.',
                     },
                     {
-                        key: 'sync.copyCommand',
+                        key: 'prep.retry',
                         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 — всяка само ако предишната е успяла.',
+                        en: 'Try again',
+                        bg: 'Опитай пак',
+                        doesEn: 'Shown when the fetch did not get through: fetches again; a remote that wants a password or an SSH key passphrase asks through Git\u2019s own window, which the bot never reads.',
+                        doesBg: 'Показва се, когато изтеглянето не е минало: изтегля отново; remote, който иска парола или passphrase за SSH ключ, пита през собствения прозорец на Git, който ботът не чете.',
+                    },
+                    {
+                        key: 'prep.copyFetch',
+                        kind: 'button',
+                        en: 'Copy the fetch command',
+                        bg: 'Копирай командата за изтегляне',
+                        doesEn: 'Copies git fetch for this repository, to run in the operator\u2019s own PowerShell, where ssh asks for the passphrase directly.',
+                        doesBg: 'Копира git fetch за това хранилище, за собствения PowerShell на оператора, където ssh пита за passphrase директно.',
+                    },
+                    {
+                        key: 'prep.useFetched',
+                        kind: 'button',
+                        en: 'Continue with what was last fetched',
+                        bg: 'Продължи с последно изтегленото',
+                        doesEn: 'The preview again without fetching, against the remote as it was last fetched (say, by the command above); it says when that was.',
+                        doesBg: 'Прегледът отново без изтегляне, спрямо remote, както е изтеглен последно (например с командата по-горе); казва кога е било.',
+                    },
+                    {
+                        key: 'prep.cancel',
+                        kind: 'button',
+                        en: 'Cancel',
+                        bg: 'Отказ',
+                        doesEn: 'Closes the preview; nothing is changed.',
+                        doesBg: 'Затваря прегледа; нищо не се променя.',
                     },
                     {
                         key: 'exec.minApproaches',