copilot-operator 0.1.0

package/dist/src/vcs/git.js

@@ -0,0 +1,286 @@
+/**
+ * The git the runner does for itself.
+ *
+ * Every git command in this project runs from here, not from a step written by Copilot. That
+ * is deliberate. Branching and committing have to be exact, and exactness is the one thing a
+ * language model cannot promise: a step it writes goes through improvisation, through the
+ * approval gate, and through the output pipeline that has already been observed to mangle
+ * text. A task that is asked to "go back to the code as it was" cannot be built on that.
+ *
+ * Two rules hold everywhere in this file:
+ *
+ *   - Nothing is destructive. There is no `reset --hard`, no forced checkout, no branch
+ *     deletion. Going back to an earlier state means branching from the commit that state
+ *     was at, which adds history instead of removing it.
+ *   - Nothing runs through a shell. `execFile` takes an argument list, so a branch name or a
+ *     commit message cannot turn into another command.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Settings every git the runner starts is given, ahead of the command.
+ *
+ * The repository is one the chat's steps have been working in, and a repository can carry code that
+ * git runs by itself: hooks (`post-checkout`, `prepare-commit-msg`, `post-commit` — `--no-verify`
+ * skips only two of them), an fsmonitor program that `status` starts, and clean/smudge filters that
+ * `add` and `checkout` run. Found on 2026-09-27: any of these, placed by a step, would have been
+ * executed by the runner — as the runner, with no approval and no log. So hooks are pointed at a
+ * folder that does not exist, fsmonitor is off, and the repository's own attribute files are not
+ * read for filters (`core.attributesFile` cannot switch off `.gitattributes`, but a filter needs a
+ * driver in the config, which the steps may no longer write — see `repositoryInternalsRefusal`).
+ * `--no-optional-locks` keeps `status` from writing the index behind a step's back.
+ */
+const SAFE_GIT = [
+    '-c', `core.hooksPath=${noHooksDir()}`,
+    '-c', 'core.fsmonitor=false',
+    '-c', 'core.untrackedCache=false',
+    '--no-optional-locks',
+];
+/** A folder that does not exist, so git finds no hooks in it. */
+function noHooksDir() {
+    return process.env.SystemRoot ? join(process.env.SystemRoot, 'System32', 'copilot-operator-no-hooks') : '/nonexistent';
+}
+/** Runs one git command in a directory. Never throws: the caller decides what a failure means. */
+export function git(cwd, args, timeoutMs = 60_000) {
+    return new Promise((resolve) => {
+        execFile('git', [...SAFE_GIT, ...args], { cwd, timeout: timeoutMs, windowsHide: true, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+            const code = error?.code;
+            resolve({
+                ok: !error,
+                stdout: (stdout ?? '').trim(),
+                stderr: (stderr ?? '').trim(),
+                code: typeof code === 'number' ? code : error ? 1 : 0,
+            });
+        });
+    });
+}
+/** Everything the runner needs to know about a repository before it touches it. */
+export async function repoState(dir) {
+    const empty = { isRepo: false, branch: null, head: null, dirty: false, changed: [] };
+    if (!dir?.trim())
+        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']);
+    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.` };
+    }
+    const branch = await git(dir, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const head = await git(dir, ['rev-parse', 'HEAD']);
+    const status = await git(dir, ['status', '--porcelain']);
+    const changed = porcelainPaths(status.stdout);
+    return {
+        isRepo: true,
+        // A repository with no commits yet has no HEAD to resolve, and that is a real state:
+        // a branch can still be made from it, but nothing can be "gone back to".
+        branch: branch.ok && branch.stdout !== 'HEAD' ? branch.stdout : null,
+        head: head.ok ? head.stdout : null,
+        dirty: changed.length > 0,
+        changed: changed.slice(0, 40),
+    };
+}
+/**
+ * Every path that would go into the next commit, file by file.
+ *
+ * `repoState` reads `git status --porcelain`, which folds a new folder into one line: a task
+ * that creates `web/` and installs into it shows as `?? web/`, and nothing under it is named.
+ * That is fine for "is the tree dirty" and useless for "what is in it" — the first task of
+ * every plan creates a folder, and what it contains is exactly what a commit-hygiene check
+ * has to see. `--untracked-files=all` lists each file; renames are reported by their new name.
+ */
+export async function workingTreePaths(dir, limit = 20_000) {
+    const status = await git(dir, ['status', '--porcelain', '--untracked-files=all']);
+    if (!status.ok || !status.stdout)
+        return [];
+    return porcelainPaths(status.stdout)
+        .map((p) => (p.includes(' -> ') ? p.slice(p.indexOf(' -> ') + 4) : p))
+        .slice(0, limit);
+}
+/**
+ * The paths out of `git status --porcelain`, whatever happened to the leading space.
+ *
+ * Porcelain puts two status characters and a space in front of every path, and the first of
+ * those characters is a space for a file modified in the working tree but not staged: ` M
+ * src/x.ts`. This runner trims every git result, which eats that leading space on the first
+ * line only — and cutting a fixed three characters then ate the first letter of the path with
+ * it. The operator saw "There are uncommitted changes (ules-engine/docs…)" and, worse, the
+ * commit-hygiene check was looking for `node_modules` in a list where the first entry could
+ * read `ode_modules`. So the status characters are matched rather than counted.
+ */
+export function porcelainPaths(stdout) {
+    if (!stdout)
+        return [];
+    return stdout
+        .split('\n')
+        .map((l) => l.replace(/^\s*[A-Z?!ADMRTUC ]{1,2}\s+/, '').trim())
+        .filter(Boolean);
+}
+/** Is git usable at all on this machine? */
+export async function gitAvailable() {
+    const r = await git(process.cwd(), ['--version'], 10_000);
+    return r.ok ? r.stdout : null;
+}
+/**
+ * A branch name git will accept, built from whatever the caller has.
+ *
+ * git's own rules are stricter than they look: no spaces, no `..`, no leading or trailing
+ * dots or slashes, no control characters, and a few reserved sequences. Rather than
+ * reimplementing the rule book, this reduces the name to a conservative alphabet and then
+ * asks git itself whether the result is legal.
+ */
+export function branchNameFrom(parts, prefix = 'cop/') {
+    const body = parts
+        .filter((p) => p !== undefined && `${p}`.trim() !== '')
+        .map((p) => `${p}`
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}._-]+/gu, '-')
+        .replace(/^[-.]+|[-.]+$/g, '')
+        .slice(0, 40))
+        .filter(Boolean)
+        .join('-');
+    const name = `${prefix}${body || 'task'}`.replace(/\.\.+/g, '.').replace(/\/+/g, '/');
+    return name.slice(0, 200);
+}
+/**
+ * A branch name somebody chose, made safe without being made unrecognisable.
+ *
+ * The prefix is stripped if the name already carries it, because a plan written by a model
+ * that has been told the prefix is `cop/` will helpfully include it, and `cop/cop-thing` is
+ * the kind of small ugliness nobody ever goes back to fix. Everything else goes through the
+ * same slug as a derived name: this is a suggestion from outside the system, and it reaches
+ * git through exactly one path.
+ */
+export function plannedBranchName(raw, prefix = 'cop/', attempt = 1) {
+    const trimmed = raw.trim();
+    const p = prefix.trim();
+    const body = p && trimmed.toLowerCase().startsWith(p.toLowerCase()) ? trimmed.slice(p.length) : trimmed;
+    return branchNameFrom([body, attempt > 1 ? `a${attempt}` : undefined], prefix);
+}
+export async function isValidBranchName(dir, name) {
+    const r = await git(dir, ['check-ref-format', '--branch', name]);
+    return r.ok;
+}
+export async function branchExists(dir, name) {
+    const r = await git(dir, ['rev-parse', '--verify', '--quiet', `refs/heads/${name}`]);
+    return r.ok && r.stdout.length > 0;
+}
+/** A name nothing is using yet, by adding `-2`, `-3` until one is free. */
+export async function freeBranchName(dir, wanted) {
+    if (!(await branchExists(dir, wanted)))
+        return wanted;
+    for (let i = 2; i < 100; i += 1) {
+        const candidate = `${wanted}-${i}`;
+        if (!(await branchExists(dir, candidate)))
+            return candidate;
+    }
+    return `${wanted}-${Date.now()}`;
+}
+/**
+ * Creates a branch and switches to it.
+ *
+ * `from` is a commit or a branch to start at. Leaving it out starts from where the repository
+ * already is. This is how "go back to the code as it was before that task" is done: the task
+ * recorded the commit it started at, and a new branch is cut from that commit. The branches
+ * that already exist are not touched, so nothing that was done in between is lost.
+ */
+export async function createBranch(dir, name, from) {
+    const args = from ? ['checkout', '-b', name, from] : ['checkout', '-b', name];
+    return await git(dir, args);
+}
+export async function checkoutExisting(dir, name) {
+    return await git(dir, ['checkout', name]);
+}
+/**
+ * Commits everything in the working tree, including files git does not track yet.
+ *
+ * Returns `committed: false` when there was nothing to commit, which is an ordinary outcome:
+ * a task that only read things leaves no changes, and that is not a failure.
+ *
+ * The author is set per command rather than in the repository's configuration, so a machine
+ * with no `user.email` still works and the operator's own identity is never written to.
+ */
+export async function commitAll(dir, message, author = 'copilot-operator <copilot-operator@localhost>') {
+    const add = await git(dir, ['add', '-A']);
+    if (!add.ok)
+        return { committed: false, problem: add.stderr || 'git add failed' };
+    const staged = await git(dir, ['diff', '--cached', '--name-only']);
+    if (staged.stdout.length === 0)
+        return { committed: false };
+    const commit = await git(dir, [
+        '-c',
+        `user.name=${author.split('<')[0].trim()}`,
+        '-c',
+        `user.email=${author.includes('<') ? author.split('<')[1].replace('>', '').trim() : 'copilot-operator@localhost'}`,
+        'commit',
+        '--no-verify',
+        '-m',
+        message,
+    ]);
+    if (!commit.ok)
+        return { committed: false, problem: commit.stderr || commit.stdout || 'git commit failed' };
+    const head = await git(dir, ['rev-parse', 'HEAD']);
+    return { committed: true, commit: head.ok ? head.stdout : undefined };
+}
+/**
+ * What one commit touched: the files, and how many lines went in and out of each.
+ *
+ * Read once, at the moment of committing, and kept on the task. The alternative is asking git
+ * again whenever the UI wants to show it, which fails the day the branch is gone, the folder
+ * has moved or the operator is looking at the record of a machine they no longer have.
+ */
+export async function commitFiles(dir, commit) {
+    const r = await git(dir, ['show', '--numstat', '--format=', commit]);
+    if (!r.ok || !r.stdout)
+        return [];
+    return r.stdout
+        .split('\n')
+        .map((line) => line.split('\t'))
+        .filter((parts) => parts.length === 3 && parts[2].trim() !== '')
+        .map(([added, removed, path]) => ({
+        path: path.trim(),
+        // A binary file reports "-" for both, which is a real answer and not a zero.
+        added: added === '-' ? -1 : Number(added) || 0,
+        removed: removed === '-' ? -1 : Number(removed) || 0,
+    }));
+}
+/** The subject line of one commit, or empty when it cannot be read. */
+export async function commitSubject(dir, commit) {
+    const r = await git(dir, ['log', '-1', '--format=%s', commit]);
+    return r.ok ? r.stdout.trim() : '';
+}
+/** One line per commit, newest first, for showing what a task produced. */
+export async function commitsBetween(dir, fromCommit, toRef = 'HEAD') {
+    const r = await git(dir, ['log', '--oneline', `${fromCommit}..${toRef}`]);
+    return r.ok && r.stdout ? r.stdout.split('\n') : [];
+}
+/** True when the folder looks like a repository worth offering in the UI. */
+export function looksLikeRepo(dir) {
+    return !!dir?.trim() && existsSync(join(dir, '.git'));
+}
+/**
+ * Why version control cannot be turned on for a folder, or null when it can.
+ *
+ * Checked before the choice is saved rather than when a run reaches it. Version control that
+ * is on but inactive is the worst of both: the operator believes there is a way back, the
+ * runner quietly branches nothing, and the first anyone knows of it is a task card an hour
+ * later. Making the repository a precondition of the switch means the switch tells the truth.
+ *
+ * An empty folder is not an error here. It means nothing has been chosen yet, and the panel
+ * says that in its own words.
+ */
+export function repoUnusableReason(dir) {
+    const d = (dir ?? '').trim();
+    if (!d)
+        return null;
+    if (!existsSync(d)) {
+        return (`The folder ${d} does not exist, so there is no repository to work in. ` +
+            'Create the project first, make it a git repository, and then point version control at it.');
+    }
+    if (!existsSync(join(d, '.git'))) {
+        return (`${d} is not a git repository: it has no .git folder. ` +
+            'Version control cannot make a branch or a commit there. Run "git init" in that folder, ' +
+            'or choose a folder that is already a repository.');
+    }
+    return null;
+}

package/dist/src/vcs/taskVcs.js

@@ -0,0 +1,343 @@
+import { findSuspicious } from './commitHygiene.js';
+import { branchNameFrom, commitAll, commitFiles, commitsBetween, commitSubject, createBranch, checkoutExisting, freeBranchName, isValidBranchName, plannedBranchName, repoState } from './git.js';
+/** Which repository a session works in: its own setting, else the project it mirrors. */
+export function repoDirOf(session) {
+    return (session.vcs?.repoDir?.trim() || session.mirror.rootDir?.trim() || '').trim();
+}
+/**
+ * Puts the repository on the right branch for a task and reports where it starts from.
+ *
+ * A problem is never fatal. Version control failing is a reason to tell the operator and carry
+ * on without it, not a reason to throw away a queue of work: the task itself may not even
+ * touch the repository.
+ */
+export async function prepareForTask(session, task, bus, saveSession) {
+    const settings = session.vcs;
+    if (!settings?.enabled)
+        return { vcs: {}, note: '' };
+    const dir = repoDirOf(session);
+    const state = await repoState(dir);
+    if (!state.isRepo) {
+        const problem = state.problem ?? 'The repository could not be read.';
+        bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-unavailable', level: 'warn',
+            message: `version control is on but inactive: ${problem}` });
+        return { vcs: { problem }, note: '' };
+    }
+    // A dirty tree is the operator's own work in progress. Committing it under the bot's name
+    // or moving it to another branch would both be decisions that are not ours to make.
+    if (state.dirty) {
+        const problem = `the repository has uncommitted changes (${state.changed.slice(0, 5).join(', ')}` +
+            `${state.changed.length > 5 ? `, and ${state.changed.length - 5} more` : ''}). ` +
+            'Commit or stash them, so the task starts from a known state.';
+        bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-dirty', level: 'warn',
+            message: `version control is on but inactive: ${problem}` });
+        return { vcs: { problem }, note: '' };
+    }
+    // The session's base is fixed the first time it runs: every per-task branch is cut from it,
+    // which is what makes the tasks independent of each other rather than of the calendar.
+    let base = session.vcsBaseCommit;
+    if (!base && state.head) {
+        base = state.head;
+        await saveSession((s) => {
+            s.vcsBaseCommit = base;
+        });
+    }
+    const attempt = task.attempt ?? 1;
+    const prefix = settings.branchPrefix || 'cop/';
+    if (settings.branchMode === 'per-session') {
+        const planned = settings.branchName?.trim();
+        const wanted = planned
+            ? plannedBranchName(planned, prefix)
+            : branchNameFrom([session.name, session.id.slice(0, 13)], prefix);
+        return await switchTo(session, task, dir, wanted, base, bus, { reuseExisting: true });
+    }
+    // A name the task carries wins over one derived from its title: whoever wrote the plan knew
+    // what the task was for, and a title is only ever a label for the list.
+    const plannedBranch = task.vcsPlan?.branch?.trim();
+    const wanted = plannedBranch
+        ? plannedBranchName(plannedBranch, prefix, attempt)
+        : branchNameFrom([session.name, task.title, attempt > 1 ? `a${attempt}` : undefined], prefix);
+    // A re-run starts from where that task started the first time, not from where the previous
+    // attempt ended. That is the whole point of recording the base commit.
+    const from = firstAttemptBase(task) ?? base;
+    return await switchTo(session, task, dir, wanted, from, bus, { reuseExisting: false });
+}
+/**
+ * Which branch has the complete work of a session, when one does.
+ *
+ * Answered from the session's own record rather than from git, because the question is asked
+ * after the run, from a page, and often about a repository whose HEAD is somewhere else: in
+ * per-task mode HEAD is left on whichever task ran last, which for a nine-task plan was an
+ * audit branch that did not carry the README written one task earlier.
+ */
+export function sessionBranches(session) {
+    const mode = session.vcs?.branchMode ?? 'per-task';
+    const branches = session.tasks
+        .filter((t) => !!t.vcs?.branch)
+        .map((t) => ({ title: t.title, branch: t.vcs?.branch, commit: t.vcs?.commit, status: t.status }));
+    if (mode === 'per-session') {
+        const planned = session.vcs?.branchName?.trim();
+        const complete = branches[branches.length - 1]?.branch ?? (planned ? plannedBranchName(planned, session.vcs?.branchPrefix || 'cop/') : undefined);
+        return { mode, complete, branches };
+    }
+    return { mode, branches };
+}
+/** The commit the task's first attempt started from, if it has one. */
+function firstAttemptBase(task) {
+    return earliestBase(task);
+}
+async function switchTo(session, task, dir, wantedName, from, bus, opts) {
+    if (!(await isValidBranchName(dir, wantedName))) {
+        const problem = `"${wantedName}" is not a name git accepts.`;
+        bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-problem', level: 'warn', message: problem });
+        return { vcs: { problem }, note: '' };
+    }
+    const state = await repoState(dir);
+    let name = wantedName;
+    let result;
+    if (opts.reuseExisting && state.branch === wantedName) {
+        result = { ok: true, stdout: '', stderr: '', code: 0 };
+    }
+    else if (opts.reuseExisting) {
+        const existing = await checkoutExisting(dir, wantedName);
+        result = existing.ok ? existing : await createBranch(dir, wantedName, from);
+    }
+    else {
+        name = await freeBranchName(dir, wantedName);
+        result = await createBranch(dir, name, from);
+    }
+    if (!result.ok) {
+        const problem = result.stderr || result.stdout || 'the branch could not be created';
+        bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-problem', level: 'warn',
+            message: `version control is on but inactive: ${problem}` });
+        return { vcs: { problem }, note: '' };
+    }
+    const after = await repoState(dir);
+    const vcs = { branch: after.branch ?? name, baseCommit: after.head ?? from };
+    bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-branch', level: 'info',
+        message: `working on branch ${vcs.branch}${from ? ` (from ${from.slice(0, 8)})` : ''}`, data: { ...vcs, repoDir: dir } });
+    // What the task stands on, and what it does not: the base commit by name, and the other
+    // tasks of this session that already ran, with the branch each of them worked on.
+    const subject = vcs.baseCommit ? await commitSubject(dir, vcs.baseCommit) : '';
+    const mode = session.vcs?.branchMode ?? 'per-task';
+    // On this branch (per-session: their work is here) or on others (per-task: it is not). A
+    // session whose mode was switched mid-way has both, and each kind is reported by where it is.
+    const earlier = session.tasks
+        .filter((t) => t.id !== task.id && !!t.vcs?.branch && t.status !== 'queued')
+        .filter((t) => (mode === 'per-session' ? t.vcs?.branch === vcs.branch : t.vcs?.branch !== vcs.branch))
+        .map((t) => ({ title: t.title, branch: t.vcs?.branch }));
+    const note = noteFor(dir, vcs, {
+        mode,
+        base: vcs.baseCommit ? { commit: vcs.baseCommit, subject } : undefined,
+        earlier,
+    });
+    return { vcs, note };
+}
+/**
+ * What level 1 tells Copilot when version control is on.
+ *
+ * Copilot has to know the repository is being managed, or it will helpfully create its own
+ * branch, commit half-way through, or switch away in the middle of a task. It is written as a
+ * plain instruction with the reason attached, because a rule without a reason is the kind a
+ * model talks itself out of.
+ */
+export function noteFor(repoDir, vcs, ctx = { mode: 'per-task', earlier: [] }) {
+    if (!vcs.branch)
+        return '';
+    const base = ctx.base
+        ? `\`${ctx.base.commit.slice(0, 8)}\`${ctx.base.subject ? ` ("${ctx.base.subject}")` : ''}`
+        : 'the current commit';
+    const named = ctx.earlier.map((e) => `"${e.title}"`).join(', ');
+    /*
+     * Which earlier work is in the tree and which is not, said outright. In per-task mode every
+     * branch is cut from the same commit, so an audit task that ran after a README task was
+     * looking at a tree without the README — and had no way to know, because until this note
+     * was written it was told only the branch's name.
+     */
+    const standing = ctx.mode === 'per-session'
+        ? ctx.earlier.length > 0
+            ? `This branch already carries the work of ${ctx.earlier.length} earlier task(s) of this session — ${named} — so their files are in your working tree.`
+            : 'This is the first task on this branch.'
+        : ctx.earlier.length > 0
+            ? `Every task of this session gets its own branch from that same commit, so the work of the earlier tasks is NOT in your working tree: ` +
+                `${ctx.earlier.map((e) => `"${e.title}" is on \`${e.branch}\``).join(', ')}. If this task depends on what one of them produced, say so in the summary rather than looking for files that are not here.`
+            : 'Every task of this session gets its own branch from that same commit.';
+    return [
+        '## Version control',
+        '',
+        `The runner has already put ${repoDir} on the branch \`${vcs.branch}\`, created for this task from ${base},`,
+        'and it will commit whatever you change when the task finishes.',
+        '',
+        standing,
+        '',
+        '- Do not create branches, switch branches, commit, stash, reset or revert. That is the',
+        "  runner's job, and two of us doing it would leave the repository in a state neither of us",
+        '  expects.',
+        '- Do not push anything. Pushing is the operator\'s decision, made by hand, afterwards.',
+        '- Read-only git is fine: `git status`, `git diff`, `git log` tell you where you are.',
+        '- Change files as the task requires. You do not need to preserve the old ones by copying',
+        '  them aside: the previous state is already a commit, and it can be returned to.',
+    ].join('\n');
+}
+/**
+ * Commits what the task changed, after it has ended.
+ *
+ * Runs whatever the outcome was. A failed task that left changes behind is exactly the case
+ * where having them on a branch, rather than loose in the tree, is worth the most.
+ */
+export async function commitTaskResult(session, task, outcome, bus) {
+    const settings = session.vcs;
+    const current = task.vcs ?? {};
+    if (!settings?.enabled || !settings.commitOnFinish || !current.branch)
+        return current;
+    const dir = repoDirOf(session);
+    const message = commitMessage(task, outcome);
+    const result = await commitAll(dir, message);
+    if (result.problem) {
+        bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-problem', level: 'warn',
+            message: `nothing was committed: ${result.problem}` });
+        return { ...current, problem: result.problem };
+    }
+    if (!result.committed) {
+        bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-nothing', level: 'info',
+            message: `nothing to commit on ${current.branch}: the task changed no files` });
+        return current;
+    }
+    const commits = current.baseCommit ? await commitsBetween(dir, current.baseCommit) : [];
+    const files = result.commit ? await commitFiles(dir, result.commit) : [];
+    bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-commit', level: 'info',
+        message: `committed on ${current.branch} as ${result.commit?.slice(0, 8)}: ` +
+            `${files.length} file(s) — push it yourself when you are ready`,
+        data: { branch: current.branch, commit: result.commit, files: files.length } });
+    // What went in that should not have. Read from the commit itself rather than from the check
+    // that pointed it out, so the record is what happened and not what was noticed.
+    const suspicious = findSuspicious(files.map((f) => f.path));
+    if (suspicious.length > 0) {
+        bus.publish({ sessionId: session.id, taskId: task.id, type: 'vcs-suspicious', level: 'warn',
+            message: `${suspicious.length} committed file(s) look like tool output or secrets: ` +
+                suspicious.map((s) => `${s.path} (${s.reason})`).join('; '),
+            data: { commit: result.commit, suspicious } });
+    }
+    return { ...current, commit: result.commit, commits, files, ...(suspicious.length > 0 ? { suspicious } : {}) };
+}
+/**
+ * A commit message that says what was asked and how it ended, in git's own shape.
+ *
+ * A task can carry its own message, which is what an imported plan sets: the model that wrote
+ * the plan knew what the change was for before it was made, and that reads better in a log
+ * than a title typed into a form. Its first line is the subject and the rest, if there is any,
+ * becomes the first paragraph of the body. Everything the runner adds afterwards — the
+ * summary, how it ended, the trailer — is added either way, because none of it can be known
+ * in advance.
+ */
+export function commitMessage(task, outcome) {
+    const planned = task.vcsPlan?.commitMessage?.trim();
+    const [plannedSubject = '', ...plannedRest] = (planned ?? '').split('\n');
+    const subject = (planned ? plannedSubject : task.title).replace(/\s+/g, ' ').trim().slice(0, 72) || 'copilot-operator task';
+    const paragraphs = [
+        plannedRest.join('\n').trim() || undefined,
+        outcome.summary?.trim(),
+        // What the model could not do as the task said. In the commit because that is where the
+        // next person looks for why a file is not what the plan describes.
+        outcome.deviations && outcome.deviations.length > 0
+            ? `Not as the task said:\n${outcome.deviations.map((d) => `- ${d.instruction}\n  did: ${d.did}\n  because: ${d.why}`).join('\n')}`
+            : undefined,
+        outcome.reason
+            ? `Ended ${outcome.status}: ${outcome.reason}`
+            : outcome.status !== 'done'
+                ? `Ended ${outcome.status}.`
+                : undefined,
+        [`Task: ${task.title}`, `Attempt: ${task.attempt ?? 1}`, 'Committed by copilot-operator. Not pushed.'].join('\n'),
+    ].filter((p) => !!p && p.trim().length > 0);
+    return `${subject}\n\n${paragraphs.join('\n\n')}\n`;
+}
+/** The earliest starting point recorded for this task, across all of its attempts. */
+function earliestBase(task) {
+    const fromAttempts = (task.attempts ?? []).map((a) => a.vcs?.baseCommit).find(Boolean);
+    return fromAttempts ?? task.vcs?.baseCommit;
+}
+/** What restoring this task would do, asked before anything is done. */
+export async function restorePreview(session, task) {
+    const repoDir = repoDirOf(session);
+    const empty = { ok: false, repoDir, leftBehind: [] };
+    if (!session.vcs?.enabled)
+        return { ...empty, problem: 'Version control is off for this session.' };
+    const base = earliestBase(task);
+    if (!base) {
+        return {
+            ...empty,
+            problem: 'This task never recorded where it started, so there is nothing to go back to. That happens when ' +
+                'version control was off or inactive at the time it ran.',
+        };
+    }
+    const state = await repoState(repoDir);
+    if (!state.isRepo)
+        return { ...empty, problem: state.problem ?? 'The repository could not be read.' };
+    if (state.dirty) {
+        return {
+            ...empty,
+            baseCommit: base,
+            currentBranch: state.branch ?? undefined,
+            problem: `There are uncommitted changes (${state.changed.slice(0, 3).join(', ')}${state.changed.length > 3 ? '…' : ''}). ` +
+                'Switching branches now would carry them along or lose them, and neither is this tool\'s decision to make. ' +
+                'Commit or stash them first.',
+        };
+    }
+    const prefix = session.vcs.branchPrefix || 'cop/';
+    return {
+        ok: true,
+        repoDir,
+        baseCommit: base,
+        currentBranch: state.branch ?? undefined,
+        leftBehind: await commitsBetween(repoDir, base, 'HEAD'),
+        keptOn: state.branch ?? undefined,
+        branchName: await freeBranchName(repoDir, plannedBranchName(`restore-${task.title}`, prefix)),
+    };
+}
+/** Does it: a new branch at that commit, checked out. Nothing else changes. */
+export async function restoreToBase(session, task, bus) {
+    const preview = await restorePreview(session, task);
+    if (!preview.ok || !preview.baseCommit || !preview.branchName) {
+        return { ok: false, problem: preview.problem ?? 'The restore could not be prepared.' };
+    }
+    const result = await createBranch(preview.repoDir, preview.branchName, preview.baseCommit);
+    if (!result.ok) {
+        return { ok: false, problem: result.stderr || result.stdout || 'the branch could not be created' };
+    }
+    bus.publish({
+        sessionId: session.id,
+        taskId: task.id,
+        type: 'vcs-restored',
+        level: 'info',
+        message: `restored the code as it was before "${task.title}": ${preview.repoDir} is on ${preview.branchName} at ` +
+            `${preview.baseCommit.slice(0, 8)}` +
+            (preview.leftBehind.length > 0 ? `; ${preview.leftBehind.length} later commit(s) stay on ${preview.keptOn}` : ''),
+        data: { branch: preview.branchName, commit: preview.baseCommit, leftBehind: preview.leftBehind.length },
+    });
+    return {
+        ok: true,
+        branch: preview.branchName,
+        commit: preview.baseCommit,
+        leftBehind: preview.leftBehind,
+        keptOn: preview.keptOn,
+    };
+}
+/** What the UI shows before a run: is version control going to work here? */
+export async function vcsPreflight(session) {
+    const settings = session.vcs;
+    if (!settings?.enabled)
+        return { ok: false, repoDir: '', problem: 'off' };
+    const repoDir = repoDirOf(session);
+    const state = await repoState(repoDir);
+    if (!state.isRepo)
+        return { ok: false, repoDir, problem: state.problem };
+    if (state.dirty) {
+        return {
+            ok: false,
+            repoDir,
+            branch: state.branch ?? undefined,
+            problem: `There are uncommitted changes (${state.changed.slice(0, 3).join(', ')}${state.changed.length > 3 ? '…' : ''}). Commit or stash them first.`,
+        };
+    }
+    return { ok: true, repoDir, branch: state.branch ?? undefined };
+}