copilot-operator 0.1.20 → 0.1.22

package/dist/src/session/exports.js

@@ -21,6 +21,7 @@
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { browserAfterPreflight, readRunLog } from './runLog.js';
 import { TASK_FIELD_ON_RERUN } from './store.js';
 import { botVersion } from '../config/version.js';
 import { withoutPersona } from '../plan/importPlan.js';
@@ -329,7 +330,12 @@ export function exportMachine(cfg) {
         node: process.versions.node,
         platform: process.platform,
         cwd: cfg.resolved.cwd,
-        limits: { ...cfg.limits, execution: { commandTimeoutSec: cfg.execution.commandTimeoutSec, idleTimeoutSec: cfg.execution.idleTimeoutSec, mode: cfg.execution.mode } },
+        /*
+         * The mode in Settings is only what a run is offered first; each run chooses its own, recorded per
+         * task as `policy.mode`. Named `defaultModeInSettings` because a report of 2026-10-03 read this field
+         * as the run's mode — "unattended" for a run started step by step.
+         */
+        limits: { ...cfg.limits, execution: { commandTimeoutSec: cfg.execution.commandTimeoutSec, idleTimeoutSec: cfg.execution.idleTimeoutSec, defaultModeInSettings: cfg.execution.mode } },
     };
 }
 /** The three files an attempt that did not end done leaves in its own run folder. */
@@ -456,6 +462,31 @@ async function domainTask(session, task, runsDir) {
             name: session.name,
             // The commit the session's tasks are cut from, by the name a report looks for.
             ...(session.vcsBaseCommit ? { baselineCommit: session.vcsBaseCommit } : {}),
+            /*
+             * The starting snapshot, in the terms a report asks for: the base it was made on, the approved
+             * inputs with their sums, the approval, the sessions that start from it, and whether this one
+             * made it or inherited it through its chain.
+             */
+            ...(session.vcsStart?.kind === 'snapshot' || session.vcsStart?.baseline
+                ? {
+                    baseline: {
+                        commit: session.vcsStart.kind === 'snapshot' ? session.vcsStart.commit : session.vcsStart.baseline?.commit,
+                        branch: session.vcsStart.kind === 'snapshot' ? session.vcsStart.branch : session.vcsStart.baseline?.branch,
+                        inherited: session.vcsStart.kind !== 'snapshot',
+                        ...(session.vcsStart.baseline?.fromSession ? { inheritedFrom: session.vcsStart.baseline.fromSession } : {}),
+                        ...(session.vcsStart.snapshot
+                            ? {
+                                targetBaseCommit: session.vcsStart.snapshot.fromCommit,
+                                targetBaseBranch: session.vcsStart.snapshot.fromBranch,
+                                onBaseBranch: !!session.vcsStart.snapshot.onBase,
+                                approval: { approved: session.vcsStart.snapshot.approved, at: session.vcsStart.snapshot.approvedAt },
+                                sessions: session.vcsStart.snapshot.sharedWith ?? [{ id: session.id, name: session.name }],
+                            }
+                            : {}),
+                        approvedInputs: (session.vcsStart.inputs?.files ?? []).map((f) => ({ path: f.path, sha256: f.sha256 })),
+                    },
+                }
+                : {}),
             ...(session.vcsStart
                 ? {
                     start: {
@@ -594,6 +625,28 @@ export async function buildDomainExport(scope, runsDir) {
 // bot: what the runner did
 // ------------------------------------------------------------------------------------------
 const TRANSPORT_TYPES = new Set(['message-sent', 'format-error', 'report-written', 'report-redacted', 'report-send-failed', 'attachment-missing', 'chat-registered', 'download']);
+/**
+ * The mode the attempt actually ran in, in the words of the run buttons: from its own policy.json
+ * (written when the task began, from the mode of the run as it was then), else the run's record on the
+ * session. "Run the rest without asking" can turn a step-by-step run unattended mid-way; a later task
+ * says so in its own policy.json.
+ */
+async function policyOf(session, task, runsDir) {
+    const named = (m) => (m === 'confirm' ? 'step-by-step' : m === 'unattended' ? 'unattended' : undefined);
+    if (task.runId) {
+        const raw = await readFile(join(runsDir, task.runId, 'policy.json'), 'utf8').catch(() => null);
+        try {
+            const mode = raw ? named(JSON.parse(raw).mode) : undefined;
+            if (mode)
+                return { mode, from: 'policy.json' };
+        }
+        catch {
+            /* a damaged file: fall back to the run record */
+        }
+    }
+    const mode = session.runGroup && task.runGroup?.id === session.runGroup.id ? named(session.runGroup.mode) : undefined;
+    return mode ? { mode, from: 'run record' } : undefined;
+}
 async function botTask(session, task, runsDir) {
     const events = await readEvents(runsDir, task.runId);
     const steps = stepsOf(events);
@@ -605,6 +658,9 @@ async function botTask(session, task, runsDir) {
     return {
         session: { id: session.id, name: session.name, model: session.model, modelInUse: session.modelInUse, reviewModel: session.review?.model },
         task: { id: task.id, title: task.title, attempt: task.attempt ?? 1, status: task.status, runId: task.runId, runFolder: task.runId ? join(runsDir, task.runId) : undefined, logFile: task.logFile },
+        // Which press of a run button this attempt belongs to: its preflight is under `runs` by this id.
+        run: task.runGroup ? { id: task.runGroup.id, name: task.runGroup.name } : undefined,
+        policy: await policyOf(session, task, runsDir),
         timing: { startedAt: task.startedAt, finishedAt: task.finishedAt, iterations: task.iterations },
         environment: task.environment,
         transport: {
@@ -654,12 +710,25 @@ export async function buildBotExport(scope, runsDir, machine) {
     const tasks = [];
     for (const { session, task } of pairs)
         tasks.push(await botTask(session, task, runsDir));
+    /*
+     * What each run did before its tasks: the version control preflight and the moment the browser was
+     * asked for, in the order they happened (`session/runLog.ts`), with the order checked rather than claimed.
+     */
+    const runs = {};
+    for (const { task } of pairs) {
+        const id = task.runGroup?.id;
+        if (!id || id in runs)
+            continue;
+        const preflight = await readRunLog(runsDir, id);
+        runs[id] = { name: task.runGroup?.name, preflight, order: browserAfterPreflight(preflight) };
+    }
     return {
         exportedAt: new Date().toISOString(),
         // Which copilot-operator made this, so a report from another machine says it without being asked.
         botVersion: botVersion(),
         about: `copilot-operator, the runner: ${scope.label}. The environment, every transcript event, every step with its exit code, the transport's retries, what was reaped, what the review machinery did. Read the domain export for what the task was about.`,
         machine,
+        runs,
         tasks,
     };
 }

package/dist/src/session/runLog.js

@@ -0,0 +1,60 @@
+/**
+ * What a run did before any of its tasks began: the version control preflight, repository by
+ * repository, and the moment the browser was asked for.
+ *
+ * From the bug report of 2026-10-03 (run on 0.1.20): a run refused for uncommitted files had already
+ * emitted `task-started`, set up the shell, opened Edge and collected artifacts, and its export could
+ * not show in which order any of it happened. The preflight now runs before all of that, and this is
+ * its record: one file per run (`<runs>/_runs/<run id>/run.jsonl`), written by the service before the
+ * browser opens and read back by the runner export, which can then show that `browser-launch-requested`
+ * came after `run-preflight-passed` — or that a refused run never asked for a browser at all.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** A run id as a folder name: what the service makes (`r-…`, `b-…`), and nothing that walks out of `_runs`. */
+const safe = (runId) => runId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 80);
+export function runLogPath(runsDir, runId) {
+    return join(runsDir, '_runs', safe(runId), 'run.jsonl');
+}
+export async function appendRunLog(runsDir, runId, entries) {
+    if (!runId || entries.length === 0)
+        return;
+    const path = runLogPath(runsDir, runId);
+    await mkdir(join(path, '..'), { recursive: true });
+    await appendFile(path, entries.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf8');
+}
+export async function readRunLog(runsDir, runId) {
+    if (!runId)
+        return [];
+    try {
+        const text = await readFile(runLogPath(runsDir, runId), 'utf8');
+        return text
+            .split('\n')
+            .filter((l) => l.trim())
+            .flatMap((l) => {
+            try {
+                return [JSON.parse(l)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Whether the browser was asked for only after the preflight passed, read from the record rather
+ * than claimed: the position of each in the file, which is written in the order things happened.
+ */
+export function browserAfterPreflight(entries) {
+    const passed = entries.findIndex((e) => e.type === 'run-preflight-passed');
+    const browser = entries.findIndex((e) => e.type === 'browser-launch-requested');
+    return {
+        ...(passed >= 0 ? { preflightPassedAt: entries[passed].at } : {}),
+        ...(browser >= 0 ? { browserLaunchRequestedAt: entries[browser].at } : {}),
+        // No browser asked for: nothing to prove. A browser with no passed preflight before it: false.
+        browserOnlyAfterPreflight: browser < 0 ? null : passed >= 0 && passed < browser,
+    };
+}

package/dist/src/vcs/git.js

@@ -64,7 +64,17 @@ export async function repoState(dir) {
         return { ...empty, problem: 'No repository folder is set.' };
     if (!existsSync(dir))
         return { ...empty, problem: `The folder ${dir} does not exist.` };
-    const inside = await git(dir, ['rev-parse', '--is-inside-work-tree']);
+    let inside = await git(dir, ['rev-parse', '--is-inside-work-tree']);
+    /*
+     * A folder with a .git that git calls "not a repository" is, on Windows, a moment when another git is
+     * replacing HEAD or the index (a rename there is not atomic while the file is open): asked again, it is
+     * one. Found 2026-10-02 when a run was refused before it started for "not a git repository" while its
+     * branch and HEAD read fine. Asked up to three more times before the answer stands.
+     */
+    for (let i = 0; i < 3 && (!inside.ok || inside.stdout !== 'true') && existsSync(join(dir, '.git')); i += 1) {
+        await new Promise((r) => setTimeout(r, 150 * (i + 1)));
+        inside = await git(dir, ['rev-parse', '--is-inside-work-tree']);
+    }
     if (!inside.ok || inside.stdout !== 'true') {
         return { ...empty, problem: `${dir} is not a git repository. Run "git init" there, or point version control at one.` };
     }

package/dist/src/vcs/inputs.js

@@ -25,7 +25,7 @@ import { rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
 import { looksGenerated } from './commitHygiene.js';
-import { branchNameFrom, freeBranchName, git, gitBytes, isValidBranchName, RUNNER_EMAIL } from './git.js';
+import { branchNameFrom, freeBranchName, git, gitBytes, isValidBranchName, RUNNER_EMAIL, workingTreePaths } from './git.js';
 import { inScope } from './scope.js';
 /** The session's input settings with defaults filled in, or null when it names no inputs. */
 export function inputSettings(vcs) {
@@ -152,7 +152,7 @@ const norm = (dir) => dir.trim().replace(/[\\/]+$/, '').replace(/\//g, '\\').toL
  * tree or the index: a temporary index is read from `parent`, the files are set in it, and the
  * tree is committed with `commit-tree`.
  */
-async function commitOnto(top, parent, files, message, branch) {
+export async function commitOnto(top, parent, files, message, branch) {
     const index = join(tmpdir(), `cop-inputs-index-${process.pid}-${Date.now()}`);
     const env = { ...process.env, GIT_INDEX_FILE: index };
     try {
@@ -377,6 +377,30 @@ export async function untrackedInputs(dir, patterns) {
         return new Set();
     return new Set((await inputFilesInTree(resolve(topR.stdout), patterns)).filter((f) => f.kind !== 'tracked').map((f) => f.path));
 }
+/**
+ * What is uncommitted in the working tree besides the session's recorded input files as they were
+ * approved. An input taken into a starting snapshot on the base branch stays untracked where it is —
+ * the operator's checkout is not touched — and is not "a dirty tree" while its content is the one
+ * recorded: `inputs` lists those, to be staged before the task's branch is checked out, so the switch
+ * keeps them.
+ */
+export async function dirtyBesidesInputs(dir, start) {
+    const topR = await git(dir, ['rev-parse', '--show-toplevel']);
+    if (!topR.ok || !topR.stdout)
+        return { other: [], inputs: [] };
+    const top = resolve(topR.stdout);
+    const recorded = new Map((start?.inputs?.files ?? []).map((f) => [f.path, f.blob]));
+    const other = [];
+    const inputs = [];
+    for (const p of await workingTreePaths(top)) {
+        const want = recorded.get(p);
+        if (want && (await blobOfFile(top, p)) === want)
+            inputs.push(p);
+        else
+            other.push(p);
+    }
+    return { other, inputs };
+}
 /**
  * Puts the input files back as the task's starting commit has them: a changed or removed one from
  * that commit, a new one matching an input pattern removed. Only on the task's own branch, whose

package/dist/src/vcs/prepareFromRemote.js

@@ -0,0 +1,263 @@
+/**
+ * "Prepare the folder from the remote main branch": the project folder put exactly where the team's
+ * code is — the remote's main branch, freshly fetched, checked out as the local branch of the same
+ * name, with no uncommitted changes — so the operator can add the files a task needs on top of it and
+ * hand it to the bot from there.
+ *
+ * Asked for on 2026-10-03, after a run was refused for uncommitted files on a branch the operator had
+ * put them on: a button beside the project in Settings, instead of the command to copy that
+ * `syncCommand.ts` hands out. A command to paste was the answer while the only way back to the remote
+ * was `reset --hard` and `clean -fd`, which throw work away. This does not throw anything away, which
+ * is what makes it a button:
+ *
+ *   1. Everything not on the remote's main is kept first. Uncommitted changes and new files git does
+ *      not ignore become one commit on a branch of their own (`<prefix>saved/<when>`), made with a
+ *      temporary index, so neither the checkout nor the real index moves while it is made — and it is
+ *      checked to hold every one of them before anything else happens. Commits of the local main
+ *      branch that the remote does not have get a branch of their own too. The branch the folder was
+ *      on keeps its commits; no branch is deleted.
+ *   2. Only then is the folder moved: the local main branch is set to the remote's main and checked
+ *      out, and the new files that are now on the saved branch are removed from the folder. Ignored
+ *      files — node_modules, .env, build output, what a snapshot left out — are not touched.
+ *   3. The result is read back: HEAD on the remote's main, nothing uncommitted. Otherwise it says so.
+ *
+ * The preview fetches (so what it shows is against the remote as it is now) and changes nothing else;
+ * the preparation itself refuses when the folder is no longer what the preview showed.
+ */
+import { existsSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { branchNameFrom, freeBranchName, git, porcelainPaths, RUNNER_EMAIL } from './git.js';
+const QUIET = { ...process.env, GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never', GIT_ASKPASS: '', SSH_ASKPASS: '' };
+const short = (c) => (c ?? '').slice(0, 8);
+const lines = (s) => s.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+function stamp(now = new Date()) {
+    const p = (n) => String(n).padStart(2, '0');
+    return `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}-${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+}
+/** A merge, rebase, cherry-pick or revert half done: the folder is the operator's to finish first. */
+function operationInProgress(gitDir) {
+    for (const [file, what] of [
+        ['MERGE_HEAD', 'a merge'],
+        ['rebase-merge', 'a rebase'],
+        ['rebase-apply', 'a rebase'],
+        ['CHERRY_PICK_HEAD', 'a cherry-pick'],
+        ['REVERT_HEAD', 'a revert'],
+    ]) {
+        if (existsSync(join(gitDir, file)))
+            return what;
+    }
+    return null;
+}
+const empty = (repoDir, problem) => ({
+    ok: false,
+    problem,
+    repoDir,
+    changed: [],
+    untracked: [],
+    mainOnlyCommits: [],
+    branchOnlyCommits: [],
+});
+/**
+ * What preparing the folder would do. Fetches the remote when `fetch` is true (the preview); reads
+ * only when it is false (the preparation, which must compare against what the preview fetched).
+ */
+export async function planPrepare(folder, opts) {
+    const inside = await git(folder, ['rev-parse', '--is-inside-work-tree']);
+    if (!inside.ok || inside.stdout !== 'true')
+        return empty(folder, `${folder} is not a git repository.`);
+    // The whole repository, not the folder under it the project may name: a checkout moves all of it.
+    const topR = await git(folder, ['rev-parse', '--show-toplevel']);
+    const repoDir = topR.ok && topR.stdout ? resolve(topR.stdout) : folder;
+    const gitDir = (await git(repoDir, ['rev-parse', '--absolute-git-dir'])).stdout;
+    const busy = gitDir ? operationInProgress(gitDir) : null;
+    if (busy)
+        return empty(repoDir, `The repository is in the middle of ${busy}. Finish or abort it first; nothing was changed.`);
+    const headR = await git(repoDir, ['rev-parse', '--verify', '--quiet', 'HEAD']);
+    if (!headR.ok || !headR.stdout)
+        return empty(repoDir, 'The repository has no commits yet, so there is nothing to keep the changes on top of. Make a first commit, then press it again.');
+    const branchR = await git(repoDir, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    const branch = branchR.ok && branchR.stdout ? branchR.stdout : null;
+    const remotes = lines((await git(repoDir, ['remote'])).stdout);
+    if (remotes.length === 0)
+        return empty(repoDir, 'The repository has no remote, so there is no remote main branch to prepare it from.');
+    const remote = remotes.includes('origin') ? 'origin' : remotes[0];
+    let fetched;
+    if (opts.fetch) {
+        const f = await git(repoDir, ['-c', 'credential.interactive=false', 'fetch', '--quiet', '--no-tags', '--prune', remote], 120_000, QUIET);
+        fetched = f.ok ? { ok: true } : { ok: false, detail: (f.stderr || f.stdout || 'git fetch failed').split(/\r?\n/)[0] };
+        // The remote's own idea of its main branch, asked of it now; a remote that will not say keeps the old answer.
+        if (f.ok)
+            await git(repoDir, ['remote', 'set-head', remote, '--auto'], 60_000, QUIET);
+    }
+    let target = '';
+    const remoteHead = await git(repoDir, ['symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`]);
+    if (remoteHead.ok && remoteHead.stdout)
+        target = remoteHead.stdout;
+    for (const name of ['main', 'master']) {
+        if (target)
+            break;
+        if ((await git(repoDir, ['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/${name}`])).ok)
+            target = `${remote}/${name}`;
+    }
+    if (!target) {
+        return {
+            ...empty(repoDir, fetched && !fetched.ok ? `The remote could not be fetched (${fetched.detail}), and no main branch of ${remote} is known here.` : `No main branch of ${remote} is known here.`),
+            ...(fetched ? { fetched } : {}),
+        };
+    }
+    if (fetched && !fetched.ok) {
+        return { ...empty(repoDir, `The remote could not be fetched, so the folder would be set to an old copy of ${target}: ${fetched.detail}. Nothing was changed.`), fetched };
+    }
+    const targetCommit = (await git(repoDir, ['rev-parse', '--verify', '--quiet', `refs/remotes/${target}^{commit}`])).stdout;
+    if (!targetCommit)
+        return empty(repoDir, `${target} could not be read.`);
+    const localBranch = target.slice(remote.length + 1);
+    const localHead = (await git(repoDir, ['rev-parse', '--verify', '--quiet', `refs/heads/${localBranch}^{commit}`])).stdout || null;
+    const status = await git(repoDir, ['status', '--porcelain', '--untracked-files=no']);
+    const changed = porcelainPaths(status.stdout);
+    const untracked = lines((await git(repoDir, ['ls-files', '--others', '--exclude-standard'])).stdout);
+    const mainOnlyCommits = localHead ? lines((await git(repoDir, ['log', '--format=%h %s', `${targetCommit}..${localHead}`])).stdout) : [];
+    const branchOnlyCommits = branch && branch !== localBranch ? lines((await git(repoDir, ['log', '--format=%h %s', `${targetCommit}..HEAD`])).stdout) : [];
+    const prefix = opts.prefix || 'cop/';
+    const when = stamp();
+    const dirty = changed.length + untracked.length > 0;
+    // The local main's own commits need a branch only when nothing else keeps them: the saved commit sits on top of them when the folder is on main.
+    const mainNeedsKeeping = mainOnlyCommits.length > 0 && !(dirty && branch === localBranch);
+    const savedBranch = dirty ? await freeBranchName(repoDir, `${branchNameFrom(['saved'], prefix)}/${when}`) : undefined;
+    const savedMainBranch = mainNeedsKeeping ? await freeBranchName(repoDir, `${branchNameFrom(['saved'], prefix)}/${when}-${localBranch}`) : undefined;
+    const alreadyThere = !dirty && branch === localBranch && headR.stdout === targetCommit;
+    const fingerprint = createHash('sha256')
+        .update([headR.stdout, branch ?? '', targetCommit, localHead ?? '', status.stdout, untracked.join('\n')].join('\0'))
+        .digest('hex')
+        .slice(0, 16);
+    return {
+        ok: true,
+        repoDir,
+        branch,
+        head: headR.stdout,
+        remote,
+        target,
+        targetCommit,
+        localBranch,
+        localHead,
+        ...(fetched ? { fetched } : {}),
+        changed,
+        untracked,
+        mainOnlyCommits,
+        branchOnlyCommits,
+        ...(savedBranch ? { savedBranch } : {}),
+        ...(savedMainBranch ? { savedMainBranch } : {}),
+        ...(alreadyThere ? { alreadyThere } : {}),
+        fingerprint,
+    };
+}
+/**
+ * Every uncommitted change and new file, as one commit on top of HEAD on a branch of its own, made
+ * with a temporary index — then checked to hold all of them, so nothing is removed from the folder
+ * that is not kept.
+ */
+async function keepUncommitted(dir, head, branch, message) {
+    const index = join(tmpdir(), `cop-saved-index-${process.pid}-${Date.now()}`);
+    const env = { ...process.env, GIT_INDEX_FILE: index };
+    try {
+        const read = await git(dir, ['read-tree', head], 60_000, env);
+        if (!read.ok)
+            return { problem: read.stderr || 'git read-tree failed' };
+        const added = await git(dir, ['add', '-A', '--', '.'], 300_000, env);
+        if (!added.ok)
+            return { problem: `the changes could not be read into git: ${added.stderr || added.stdout}` };
+        // Kept means kept: no tracked file differs from the saved index, and no new file is outside it.
+        const differs = await git(dir, ['diff-files', '--name-only'], 120_000, env);
+        const outside = await git(dir, ['ls-files', '--others', '--exclude-standard'], 120_000, env);
+        if (!differs.ok || differs.stdout || !outside.ok || outside.stdout) {
+            return { problem: `not every change could be kept (${[differs.stdout, outside.stdout].filter(Boolean).join(', ').slice(0, 300) || differs.stderr || outside.stderr}), so nothing was moved.` };
+        }
+        const tree = await git(dir, ['write-tree'], 60_000, env);
+        if (!tree.ok || !tree.stdout)
+            return { problem: tree.stderr || 'git write-tree failed' };
+        const commit = await git(dir, ['-c', 'user.name=copilot-operator', '-c', `user.email=${RUNNER_EMAIL}`, 'commit-tree', tree.stdout, '-p', head, '-m', message]);
+        if (!commit.ok || !commit.stdout)
+            return { problem: commit.stderr || 'git commit-tree failed' };
+        const made = await git(dir, ['branch', branch, commit.stdout]);
+        if (!made.ok)
+            return { problem: made.stderr || `the branch ${branch} could not be made` };
+        return { commit: commit.stdout };
+    }
+    finally {
+        await rm(index, { force: true });
+    }
+}
+/** Does it, after checking the folder is still what the preview showed. */
+export async function prepareFromRemote(folder, fingerprint, opts = {}) {
+    const plan = await planPrepare(folder, { fetch: false, prefix: opts.prefix });
+    if (!plan.ok)
+        return { ok: false, problem: plan.problem ?? 'the folder could not be read.' };
+    const repoDir = plan.repoDir;
+    if (!fingerprint || plan.fingerprint !== fingerprint) {
+        return { ok: false, problem: 'The folder changed since the preview was shown (a commit, a branch, a changed or new file). Look at the preview again; nothing was changed.' };
+    }
+    const target = plan.target;
+    const targetCommit = plan.targetCommit;
+    const localBranch = plan.localBranch;
+    const head = plan.head;
+    if (plan.alreadyThere) {
+        return { ok: true, branch: localBranch, commit: targetCommit, target, saved: [], removedFromFolder: 0, result: `The folder is already on ${localBranch} at ${short(targetCommit)}, the same as ${target}, with nothing uncommitted. Nothing was changed.` };
+    }
+    const saved = [];
+    if (plan.savedBranch) {
+        const what = `${plan.changed.length} changed and ${plan.untracked.length} new file(s) from ${plan.branch ?? `HEAD ${short(head)}`}`;
+        const message = [
+            'Keep uncommitted work before preparing the folder from the remote',
+            '',
+            `Everything that was not committed in the folder on ${plan.branch ?? 'a detached HEAD'} (${short(head)}), kept here before the folder was set to ${target} (${short(targetCommit)}).`,
+            'To take a file back: git restore --source <this branch> -- <path>',
+            '',
+            ...[...plan.changed.map((p) => `- changed: ${p}`), ...plan.untracked.map((p) => `- new: ${p}`)].slice(0, 300),
+            '',
+            'Committed by copilot-operator. Not pushed.',
+            '',
+        ].join('\n');
+        const kept = await keepUncommitted(repoDir, head, plan.savedBranch, message);
+        if ('problem' in kept)
+            return { ok: false, problem: kept.problem };
+        saved.push({ branch: plan.savedBranch, commit: kept.commit, what });
+    }
+    if (plan.savedMainBranch && plan.localHead) {
+        const made = await git(repoDir, ['branch', plan.savedMainBranch, plan.localHead]);
+        if (!made.ok)
+            return { ok: false, problem: `the commits of ${localBranch} the remote does not have could not be kept on ${plan.savedMainBranch}: ${made.stderr}. ${saved.length ? `The uncommitted work is on ${saved[0].branch}; ` : ''}the folder was not moved.` };
+        saved.push({ branch: plan.savedMainBranch, commit: plan.localHead, what: `${plan.mainOnlyCommits.length} commit(s) of ${localBranch} that ${target} does not have` });
+    }
+    // Everything is kept; now the folder. The forced checkout drops tracked changes that are on the saved branch.
+    const moved = await git(repoDir, ['checkout', '--quiet', '--force', '-B', localBranch, targetCommit], 300_000);
+    if (!moved.ok) {
+        return { ok: false, problem: `${localBranch} could not be checked out at ${short(targetCommit)}: ${moved.stderr || moved.stdout}. ${saved.map((s) => `${s.what} are on ${s.branch}.`).join(' ')}` };
+    }
+    await git(repoDir, ['branch', `--set-upstream-to=${target}`, localBranch]);
+    // The new files, kept on the saved branch, out of the folder; ignored files stay (no -x).
+    const removed = plan.untracked.length > 0 ? await git(repoDir, ['clean', '-fd', '--quiet'], 300_000) : { ok: true, stdout: '', stderr: '' };
+    const nowHead = (await git(repoDir, ['rev-parse', 'HEAD'])).stdout;
+    const left = lines((await git(repoDir, ['status', '--porcelain'])).stdout);
+    const keptLine = saved.length > 0 ? ` Kept: ${saved.map((s) => `${s.what} on ${s.branch}`).join('; ')}.` : '';
+    const branchLine = plan.branchOnlyCommits.length > 0 && plan.branch ? ` ${plan.branch} keeps its ${plan.branchOnlyCommits.length} commit(s); nothing was deleted.` : '';
+    if (nowHead !== targetCommit || left.length > 0 || !removed.ok) {
+        return {
+            ok: false,
+            problem: `The folder is on ${localBranch} at ${short(nowHead)}, but not exactly at ${target}: ${left.length > 0 ? `still uncommitted: ${left.slice(0, 10).join(', ')}` : removed.ok ? 'HEAD differs' : removed.stderr}.` +
+                keptLine,
+        };
+    }
+    return {
+        ok: true,
+        branch: localBranch,
+        commit: targetCommit,
+        target,
+        saved,
+        removedFromFolder: plan.untracked.length,
+        result: `The folder is on ${localBranch} at ${short(targetCommit)}, the same as ${target}, with nothing uncommitted.${keptLine}${branchLine} ` +
+            'Ignored files (node_modules, .env, build output) were not touched. Add the files the task needs now; the run screen offers a starting snapshot of them.',
+    };
+}