copilot-operator 0.1.17 → 0.1.18

package/dist/src/session/model.js

@@ -21,6 +21,26 @@ export function tidyVcsPlan(plan) {
 export function isContinuable(t) {
     return t.status === 'limit-reached' || t.status === 'aborted' || (!!t.limit && (t.status === 'failed' || t.status === 'blocked'));
 }
+/**
+ * How many times the runner ran the task again in a fresh conversation, on its own, in the run that
+ * produced its latest attempt (`limits.retryBlockedInFreshChat`): the attempts at the end of its
+ * history that it marked `freshRetry`, counted back to the one the operator started. A row that says
+ * "retried in a fresh chat, then done" means the chat was the cause; "still blocked after 2" means
+ * it was not.
+ *
+ * Derived, never stored. It was a counter on the task that the runner added to and nothing reset,
+ * so every Run again or Continue of a task that blocked added the run's retries to the last run's:
+ * the register said 2, then 4, then 6, while each run had retried twice.
+ */
+export function freshRetriesOfLatestRun(task) {
+    if (!task.freshRetry)
+        return 0;
+    let n = 1;
+    const before = task.attempts ?? [];
+    for (let i = before.length - 1; i >= 0 && before[i]?.freshRetry; i -= 1)
+        n += 1;
+    return n;
+}
 export function newId(prefix = '') {
     const now = new Date();
     const p = (n) => String(n).padStart(2, '0');

package/dist/src/session/store.js

@@ -50,6 +50,66 @@ export function bySessionList(a, b) {
         return byTime;
     return b.id.localeCompare(a.id);
 }
+/**
+ * What `rerunTask` does with every field of a task when a new attempt begins — Run again, Continue,
+ * a new prompt, the runner's own fresh-chat retry.
+ *
+ *   archived  belongs to the attempt that ended: copied onto its `TaskAttempt`, cleared on the task
+ *   cleared   belongs to that attempt and is not kept on the record: cleared
+ *   reset     given the new attempt's starting value (status queued, iterations 0, attempt + 1, …)
+ *   kept      the task's own, across attempts: its definition, or something every attempt inherits
+ *
+ * A record over every key of `Task`, so a field added to the task without a decision here does not
+ * compile. Fields that were left out of `rerunTask` by default were counted on by the next attempt:
+ * the fresh-chat retry count said 2, then 4, then 6 while each run had retried twice, and what an
+ * attempt left running was listed under every attempt after it. `npm run check:attempts` holds
+ * `rerunTask` to this table.
+ */
+export const TASK_FIELD_ON_RERUN = {
+    id: 'kept',
+    title: 'kept',
+    level2: 'kept',
+    prompt: 'kept',
+    createdAt: 'kept',
+    checks: 'kept',
+    vcsPlan: 'kept',
+    reviewEnabled: 'kept',
+    readOnly: 'kept',
+    scope: 'kept',
+    // What one review noticed is arithmetic for every attempt after it.
+    reviewChecks: 'kept',
+    attempts: 'kept',
+    status: 'reset',
+    iterations: 'reset',
+    attempt: 'reset',
+    continuing: 'reset',
+    buildsOn: 'reset',
+    runId: 'archived',
+    runGroup: 'archived',
+    startedAt: 'archived',
+    finishedAt: 'archived',
+    summary: 'archived',
+    reason: 'archived',
+    deviations: 'archived',
+    disputes: 'archived',
+    checkResults: 'archived',
+    review: 'archived',
+    stats: 'archived',
+    freshRetry: 'archived',
+    stopCode: 'archived',
+    limit: 'archived',
+    scopeReverted: 'archived',
+    inputsRestored: 'archived',
+    artifactsKept: 'archived',
+    vcs: 'archived',
+    leftovers: 'archived',
+    environment: 'archived',
+    handoff: 'archived',
+    interruption: 'cleared',
+    finalReply: 'cleared',
+    firstMessage: 'cleared',
+    logFile: 'cleared',
+};
 export const DEFAULT_VCS = {
     enabled: true,
     repoDir: '',
@@ -476,6 +536,9 @@ export class SessionStore {
             ...(current.interruption ? { interruption: current.interruption } : {}),
         });
     }
+    /**
+     * What a new attempt does with each field of a task — see `TASK_FIELD_ON_RERUN`.
+     */
     async rerunTask(sessionId, taskId, patch = {}, 
     /** Present when the new attempt carries on from the last one (see `continueTask`). */
     continuing, 
@@ -495,6 +558,8 @@ export class SessionStore {
                 {
                     runId: t.runId,
                     runGroup: t.runGroup,
+                    leftovers: t.leftovers,
+                    environment: t.environment,
                     status: t.status,
                     startedAt: t.startedAt,
                     finishedAt: t.finishedAt,
@@ -518,7 +583,11 @@ export class SessionStore {
                     stopCode: t.stopCode,
                     limit: t.limit,
                     scope: t.scope,
+                    readOnly: t.readOnly,
                     scopeReverted: t.scopeReverted,
+                    handoff: t.handoff,
+                    inputsRestored: t.inputsRestored,
+                    artifactsKept: t.artifactsKept,
                     vcs: t.vcs,
                 },
             ];
@@ -553,9 +622,15 @@ export class SessionStore {
             t.stats = undefined;
             t.handoff = undefined;
             t.scopeReverted = undefined;
+            t.inputsRestored = undefined;
+            t.artifactsKept = undefined;
             t.freshRetry = undefined;
             t.stopCode = undefined;
             t.limit = undefined;
+            // What this attempt left running and the machine it ran on are this attempt's, as the rest:
+            // left in place, the next attempt's list was added to this one's and read as its own.
+            t.leftovers = undefined;
+            t.environment = undefined;
             // The branch of the finished attempt stays in the repository and stays on the record
             // above; the next attempt gets its own, cut from the same commit this one started at.
             t.vcs = undefined;
@@ -618,6 +693,9 @@ export class SessionStore {
             // Sessions written before the queue could be told what to do on a failure behave the
             // way they always did: the chain stops.
             s.onFailure ??= 'stop';
+            // A counter that added up across runs, written before it was derived (`freshRetriesOfLatestRun`).
+            for (const t of s.tasks ?? [])
+                delete t.autoRetries;
             return s;
         }
         catch {

package/dist/src/vcs/artifacts.js

@@ -0,0 +1,138 @@
+/**
+ * Evidence the work produces — reports, ZIP archives, test results — kept with the run, not in git.
+ *
+ * Found in a real run: evidence a task wrote was either committed with the work or, to stop that,
+ * `.gitignore` had to be changed for it, and a later session that needed an earlier one's discovery
+ * report had nothing reliable to read. `vcs.artifacts.paths` names those files, and:
+ *
+ *   - they are never committed: the patterns go into the repository's own `.git/info/exclude`
+ *     (local, never committed, `.gitignore` untouched) when the session's first task starts, so the
+ *     runner's commit and a task's scope both leave them alone. A file git already tracks is not
+ *     affected by an exclude, and is said so;
+ *   - when each task ends, whatever its outcome, the files are copied into the attempt's record,
+ *     `artifacts/project/<path>`, with their sizes and SHA-256 sums on the task — so the evidence of
+ *     each attempt is kept even after a later one overwrites it in the project.
+ *
+ * Works with version control off too: then nothing is excluded, only kept.
+ */
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { looksGenerated } from './commitHygiene.js';
+import { git } from './git.js';
+import { normalisePatterns } from './inputs.js';
+import { inScope } from './scope.js';
+/** The session's artifact patterns, without ones that name the whole project. */
+export function artifactPatterns(vcs) {
+    return normalisePatterns(vcs?.artifacts?.paths ?? []);
+}
+/** A pattern for `.git/info/exclude`: anchored at the repository's top, as a scope pattern is. */
+function excludeLine(pattern) {
+    return `/${pattern.replace(/^\/+/, '')}`;
+}
+/**
+ * Writes the session's artifact patterns into `.git/info/exclude`, once each. Returns the files
+ * matching them that git already tracks, which an exclude does not stop from being committed.
+ */
+export async function excludeArtifacts(dir, session) {
+    const patterns = artifactPatterns(session.vcs);
+    if (patterns.length === 0)
+        return { tracked: [] };
+    const where = await git(dir, ['rev-parse', '--git-path', 'info/exclude']);
+    if (!where.ok || !where.stdout)
+        return { problem: "the repository's exclude file could not be found", tracked: [] };
+    const top = (await git(dir, ['rev-parse', '--show-toplevel'])).stdout || dir;
+    const file = resolve(dir, where.stdout);
+    const before = await readFile(file, 'utf8').catch(() => '');
+    const have = new Set(before.split(/\r?\n/).map((l) => l.trim()));
+    const add = patterns.map(excludeLine).filter((l) => !have.has(l));
+    if (add.length > 0) {
+        try {
+            await mkdir(dirname(file), { recursive: true });
+            const block = [`# copilot-operator: artifacts of session "${session.name.replace(/[\r\n]+/g, ' ')}" (${session.id}) — kept with the run, never committed`, ...add, ''].join('\n');
+            await writeFile(file, `${before}${before && !before.endsWith('\n') ? '\n' : ''}${block}`, 'utf8');
+        }
+        catch (e) {
+            return { problem: `the exclude file could not be written: ${e.message}`, tracked: [] };
+        }
+    }
+    const tracked = (await git(resolve(top), ['ls-files'])).stdout.split('\n').filter((p) => p && inScope(p, patterns));
+    return { tracked };
+}
+const LIMITS = { files: 1000, fileBytes: 100 * 1024 * 1024, totalBytes: 500 * 1024 * 1024 };
+/** Files under `root` matching the patterns, found on disk: git's view does not matter for evidence. */
+async function matching(root, patterns) {
+    const out = [];
+    const starts = new Set(patterns.map((p) => {
+        const fixed = [];
+        for (const part of p.replace(/\/+$/, '').split('/')) {
+            if (/[*?[]/.test(part))
+                break;
+            fixed.push(part);
+        }
+        return fixed.join('/');
+    }));
+    const walk = async (rel) => {
+        if (out.length > LIMITS.files * 2)
+            return;
+        const abs = join(root, rel);
+        const info = await stat(abs).catch(() => null);
+        if (!info)
+            return;
+        if (info.isFile()) {
+            if (inScope(rel, patterns))
+                out.push(rel);
+            return;
+        }
+        if (!info.isDirectory())
+            return;
+        const name = rel.split('/').pop() ?? '';
+        if (name === '.git' || name === 'node_modules' || name === '.copilot-operator')
+            return;
+        for (const child of await readdir(abs).catch(() => []))
+            await walk(rel ? `${rel}/${child}` : child);
+    };
+    for (const start of starts)
+        await walk(start);
+    return [...new Set(out)].sort();
+}
+/**
+ * Copies the artifact files into the attempt's record, `<dest>/<path>`. Secrets are never copied;
+ * past the limits the rest is skipped and said.
+ */
+export async function keepArtifacts(root, patterns, dest) {
+    const kept = [];
+    const skipped = [];
+    if (patterns.length === 0 || !root)
+        return { kept, skipped };
+    let total = 0;
+    const base = resolve(root);
+    for (const rel of await matching(root, patterns)) {
+        const from = resolve(join(root, rel));
+        if (!from.startsWith(base + sep))
+            continue;
+        if (looksGenerated(rel)?.reason === 'a secrets file') {
+            skipped.push(`${rel} (a secrets file)`);
+            continue;
+        }
+        const info = await stat(from).catch(() => null);
+        if (!info)
+            continue;
+        if (kept.length >= LIMITS.files || info.size > LIMITS.fileBytes || total + info.size > LIMITS.totalBytes) {
+            skipped.push(`${rel} (past the limit of ${LIMITS.files} files, ${LIMITS.fileBytes / 1048576} MB a file, ${LIMITS.totalBytes / 1048576} MB in all)`);
+            continue;
+        }
+        const to = join(dest, rel);
+        try {
+            await mkdir(dirname(to), { recursive: true });
+            await copyFile(from, to);
+            const bytes = await readFile(to);
+            kept.push({ path: rel, size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') });
+            total += info.size;
+        }
+        catch (e) {
+            skipped.push(`${rel} (${e.message})`);
+        }
+    }
+    return { kept, skipped };
+}

package/dist/src/vcs/inputs.js

@@ -0,0 +1,332 @@
+/**
+ * The operator's input files: in every session's starting commit, and not the bot's to change.
+ *
+ * Found in a real run: YAML schemas the work was built from were put into the project by hand and
+ * left untracked. Branches did not carry them predictably, a task could not tell "input from the
+ * operator" from "change made by the bot", and a session started from `main` began without them
+ * although they were in other commits. `vcs.userInputs` names them, and three things follow:
+ *
+ *   - Before a session's first task they are in the commit it starts from. New, changed or ignored
+ *     ones go into the starting snapshot (`snapshot.ts`), with the operator's approval. A session
+ *     whose start lacks them — `startFrom: "branch"` after a session that captured them — has them
+ *     committed on top of that start, "Capture user-provided inputs" on `<prefix>input/<session id>`,
+ *     from where they were last committed: the repository's HEAD, else the latest session in the same
+ *     repository that recorded them. Every session of a run sees the same inputs.
+ *   - Their SHA-256 sums are recorded on the session's start, for the record and the exports.
+ *   - Read-only, unless switched off: after every round of steps a changed, removed or added input
+ *     file is put back from the task's starting commit and the chat is told; a task that ends with
+ *     one that could not be put back fails.
+ *
+ * The commit on top of a start is made without touching the working tree or the index (a temporary
+ * index, `commit-tree`), so the operator's checkout is never disturbed to make it.
+ */
+import { createHash } from 'node:crypto';
+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 { inScope } from './scope.js';
+/** The session's input settings with defaults filled in, or null when it names no inputs. */
+export function inputSettings(vcs) {
+    const patterns = normalisePatterns(vcs?.userInputs?.paths ?? []);
+    if (patterns.length === 0)
+        return null;
+    return { paths: patterns, patterns, readOnly: vcs?.userInputs?.readOnly !== false, requireApproval: vcs?.userInputs?.requireApproval !== false };
+}
+/**
+ * Patterns as the matching expects them, without the ones that name everything: an input is a file
+ * the operator can point at, and "the whole repository" would make every change the bot makes a
+ * change to an input.
+ */
+export function normalisePatterns(paths) {
+    const out = new Set();
+    for (const raw of paths) {
+        const p = raw.trim().replace(/\\/g, '/').replace(/^\.?\/+/, '');
+        if (!p || p === '.' || /^[*/]+$/.test(p))
+            continue;
+        out.add(p);
+    }
+    return [...out];
+}
+/** Whether a pattern names everything, which an input pattern may not. */
+export function namesEverything(pattern) {
+    const p = pattern.trim().replace(/\\/g, '/').replace(/^\.?\/+/, '');
+    return !p || p === '.' || /^[*/]+$/.test(p);
+}
+/** The folder part of a pattern before its first wildcard, for narrowing what git lists. */
+function literalPrefix(pattern) {
+    const parts = pattern.replace(/\/+$/, '').split('/');
+    const fixed = [];
+    for (const part of parts) {
+        if (/[*?[]/.test(part))
+            break;
+        fixed.push(part);
+    }
+    return fixed.join('/');
+}
+function pathspecs(patterns) {
+    const prefixes = [...new Set(patterns.map(literalPrefix))];
+    return prefixes.includes('') ? [] : prefixes.map((p) => `:(icase)${p}`);
+}
+const list = async (top, args) => {
+    const r = await gitBytes(top, args, 60_000, 64 * 1024 * 1024);
+    return r.ok ? r.stdout.toString('utf8').split('\0').filter(Boolean) : [];
+};
+/** The input files in the working tree, each with what git thinks of it. */
+export async function inputFilesInTree(top, patterns) {
+    const specs = pathspecs(patterns);
+    const tail = specs.length > 0 ? ['--', ...specs] : [];
+    const seen = new Map();
+    for (const path of await list(top, ['ls-files', '-z', '--cached', ...tail]))
+        seen.set(path, 'tracked');
+    for (const path of await list(top, ['ls-files', '-z', '--others', '--exclude-standard', ...tail]))
+        if (!seen.has(path))
+            seen.set(path, 'untracked');
+    for (const path of await list(top, ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', ...tail])) {
+        // Installed or built folders are never inputs, however wide the pattern.
+        if (!seen.has(path) && !looksGenerated(path)?.key.endsWith('/'))
+            seen.set(path, 'ignored');
+    }
+    const out = [];
+    for (const [path, kind] of seen) {
+        if (!inScope(path, patterns))
+            continue;
+        // A tracked file deleted from the tree is still listed by --cached; it is not there to read.
+        if (kind === 'tracked' && !(await stat(join(top, path)).catch(() => null))?.isFile())
+            continue;
+        out.push({ path, kind });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+/** The input files in one commit: path, mode and blob. */
+async function inputsAt(top, commit, patterns) {
+    const specs = pathspecs(patterns);
+    const out = [];
+    for (const rec of await list(top, ['ls-tree', '-r', '-z', '--full-tree', commit, ...(specs.length > 0 ? ['--', ...specs.map((s) => s.replace(':(icase)', ''))] : [])])) {
+        const tab = rec.indexOf('\t');
+        const [mode = '', type = '', blob = ''] = rec.slice(0, tab).split(' ');
+        const path = rec.slice(tab + 1);
+        if (type === 'blob' && inScope(path, patterns))
+            out.push({ path, mode, blob });
+    }
+    // `ls-tree` pathspecs are case-sensitive; a pattern written in another case is matched in full.
+    if (out.length === 0 && specs.length > 0) {
+        for (const rec of await list(top, ['ls-tree', '-r', '-z', '--full-tree', commit])) {
+            const tab = rec.indexOf('\t');
+            const [mode = '', type = '', blob = ''] = rec.slice(0, tab).split(' ');
+            const path = rec.slice(tab + 1);
+            if (type === 'blob' && inScope(path, patterns))
+                out.push({ path, mode, blob });
+        }
+    }
+    return out;
+}
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** The sums of the input files as one commit has them. */
+export async function inputSumsAt(top, commit, patterns) {
+    const out = [];
+    for (const f of await inputsAt(top, commit, patterns)) {
+        const r = await gitBytes(top, ['cat-file', 'blob', f.blob], 120_000, 512 * 1024 * 1024);
+        if (r.ok)
+            out.push({ path: f.path, sha256: sha(r.stdout), size: r.stdout.length, blob: f.blob });
+    }
+    return out;
+}
+/**
+ * The blob id the working-tree file would be committed as, or null when it is not there.
+ *
+ * Compared by git's own hashing, with its line-ending conversion, rather than by the bytes: with
+ * `core.autocrlf` — usual on Windows — a checked-out file has CRLF where the commit has LF, and a
+ * byte comparison called every untouched input changed, every round.
+ */
+export async function blobOfFile(top, path) {
+    if (!(await stat(join(top, path)).catch(() => null))?.isFile())
+        return null;
+    const r = await git(top, ['hash-object', `--path=${path}`, '--', join(top, path)]);
+    return r.ok && r.stdout ? r.stdout : null;
+}
+const norm = (dir) => dir.trim().replace(/[\\/]+$/, '').replace(/\//g, '\\').toLowerCase();
+/**
+ * Makes `parent` plus the given files one commit, on a new branch, without touching the working
+ * 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) {
+    const index = join(tmpdir(), `cop-inputs-index-${process.pid}-${Date.now()}`);
+    const env = { ...process.env, GIT_INDEX_FILE: index };
+    try {
+        const read = await git(top, ['read-tree', parent], 60_000, env);
+        if (!read.ok)
+            return { problem: read.stderr || 'git read-tree failed' };
+        for (const f of files) {
+            const set = await git(top, ['update-index', '--add', '--cacheinfo', `${f.mode},${f.blob},${f.path}`], 60_000, env);
+            if (!set.ok)
+                return { problem: `${f.path}: ${set.stderr || 'git update-index failed'}` };
+        }
+        const tree = await git(top, ['write-tree'], 60_000, env);
+        if (!tree.ok || !tree.stdout)
+            return { problem: tree.stderr || 'git write-tree failed' };
+        const commit = await git(top, ['-c', 'user.name=copilot-operator', '-c', `user.email=${RUNNER_EMAIL}`, 'commit-tree', tree.stdout, '-p', parent, '-m', message]);
+        if (!commit.ok || !commit.stdout)
+            return { problem: commit.stderr || 'git commit-tree failed' };
+        const made = await git(top, ['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 });
+    }
+}
+/**
+ * Makes sure the commit a session starts from has the operator's input files, and records their
+ * sums on the start. Returns the start to use — the same one, or one whose commit has the inputs
+ * committed on top — or why the session cannot start.
+ *
+ * Called once the start is known and the working tree holds nothing uncommitted of the inputs (new
+ * or changed ones went into the snapshot before this). Where the inputs are taken from: the
+ * repository's HEAD for every pattern it has files for, else the latest session in this same
+ * repository whose start recorded files for that pattern.
+ */
+export async function settleInputs(session, dir, start, allSessions) {
+    const settings = inputSettings(session.vcs);
+    if (!settings)
+        return { start };
+    const topR = await git(dir, ['rev-parse', '--show-toplevel']);
+    if (!topR.ok || !topR.stdout)
+        return { problem: `${dir} is not a git repository.` };
+    const top = resolve(topR.stdout);
+    const head = (await git(top, ['rev-parse', '--verify', '--quiet', 'HEAD'])).stdout;
+    // Where each pattern's files are: HEAD first, then the latest earlier capture in this repository.
+    const wanted = [];
+    const sources = new Set();
+    const missing = [];
+    const atHead = head ? await inputsAt(top, head, settings.patterns) : [];
+    const earlier = (await allSessions())
+        .filter((s) => s.id !== session.id && s.vcsStart?.inputs && norm(s.vcs?.repoDir || s.projectDir || '') === norm(dir))
+        // The newest first: a later capture is the operator's later word on the inputs.
+        .sort((a, b) => (b.createdAt ?? '').localeCompare(a.createdAt ?? ''))
+        .map((s) => s.vcsStart);
+    for (const pattern of settings.patterns) {
+        let found = atHead.filter((f) => inScope(f.path, [pattern]));
+        let from = head;
+        // The start itself next: a snapshot approved on the page has them, wherever HEAD has moved since.
+        if (found.length === 0) {
+            found = (await inputsAt(top, start.commit, [pattern])).filter((f) => inScope(f.path, [pattern]));
+            from = start.commit;
+        }
+        for (const s of earlier) {
+            if (found.length > 0)
+                break;
+            found = (await inputsAt(top, s.commit, [pattern])).filter((f) => inScope(f.path, [pattern]));
+            from = s.commit;
+        }
+        if (found.length === 0)
+            missing.push(pattern);
+        else
+            sources.add(from);
+        for (const f of found)
+            if (!wanted.some((w) => w.path === f.path))
+                wanted.push(f);
+    }
+    if (missing.length > 0) {
+        return {
+            problem: `the input file pattern(s) ${missing.map((m) => `"${m}"`).join(', ')} match no file: not in the working tree, not in the repository's HEAD, ` +
+                'and no earlier session in this repository captured them. Put the files in the project (they will be listed for your approval), or correct "Input files".',
+        };
+    }
+    // What the start has already, file by file; only what differs is committed on top.
+    const inStart = new Map((await inputsAt(top, start.commit, settings.patterns)).map((f) => [f.path, f]));
+    const differ = wanted.filter((w) => inStart.get(w.path)?.blob !== w.blob);
+    let commit = start.commit;
+    let carried;
+    if (differ.length > 0) {
+        const branch = await freeBranchName(top, `${branchNameFrom(['input'], session.vcs?.branchPrefix || 'cop/')}/${session.id}`);
+        if (!(await isValidBranchName(top, branch)))
+            return { problem: `"${branch}" is not a name git accepts.` };
+        const from = [...sources].map((s) => s.slice(0, 8)).join(', ');
+        const message = [
+            'Capture user-provided inputs',
+            '',
+            `The operator's input files for session "${session.name}", which the commit it starts from (${start.commit.slice(0, 8)}) did not have,`,
+            `taken from ${from}, where they were last committed. They are inputs: the work reads them and does not change them.`,
+            '',
+            ...differ.slice(0, 200).map((f) => `- ${f.path}`),
+            '',
+            'Committed by copilot-operator. Not pushed.',
+            '',
+        ].join('\n');
+        const made = await commitOnto(top, start.commit, differ, message, branch);
+        if ('problem' in made)
+            return { problem: `the input files could not be committed on top of the session's start: ${made.problem}` };
+        commit = made.commit;
+        carried = { onto: start.commit, from, branch };
+    }
+    const files = await inputSumsAt(top, commit, settings.patterns);
+    return { start: { ...start, commit, inputs: { patterns: settings.patterns, files, readOnly: settings.readOnly, ...(carried ? { carried } : {}) } } };
+}
+/**
+ * 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
+ * starting commit has the inputs (see `settleInputs`).
+ */
+export async function protectInputs(dir, base, inputs) {
+    const out = { changed: [], restored: [], failed: [] };
+    const topR = await git(dir, ['rev-parse', '--show-toplevel']);
+    if (!topR.ok || !topR.stdout)
+        return out;
+    const top = resolve(topR.stdout);
+    const known = new Map(inputs.files.map((f) => [f.path, f.blob]));
+    for (const f of inputs.files) {
+        if ((await blobOfFile(top, f.path)) === f.blob)
+            continue;
+        out.changed.push(f.path);
+        const back = await git(top, ['checkout', base, '--', f.path]);
+        if (back.ok && (await blobOfFile(top, f.path)) === f.blob)
+            out.restored.push(f.path);
+        else
+            out.failed.push({ path: f.path, why: back.stderr || 'it is not as the starting commit has it' });
+    }
+    // A file the task added under an input pattern: inputs are the operator's, so it goes.
+    for (const { path, kind } of await inputFilesInTree(top, inputs.patterns)) {
+        if (known.has(path) || kind === 'tracked')
+            continue;
+        out.changed.push(path);
+        const abs = resolve(join(top, path));
+        if (!abs.startsWith(resolve(top) + sep)) {
+            out.failed.push({ path, why: 'not inside the repository' });
+            continue;
+        }
+        try {
+            await rm(abs, { force: true });
+            out.restored.push(path);
+        }
+        catch (e) {
+            out.failed.push({ path, why: e.message });
+        }
+    }
+    return out;
+}
+/** What the chat is told when input files were put back. */
+export function inputsMessage(check) {
+    const names = (paths) => paths.slice(0, 15).join(', ') + (paths.length > 15 ? `, and ${paths.length - 15} more` : '');
+    return [
+        `The operator's input files are read-only, so the runner put back: ${names(check.restored)}.`,
+        check.failed.length > 0 ? `Could not be put back: ${check.failed.map((f) => `${f.path} (${f.why})`).join('; ')}.` : '',
+        'Read them as they are; do not change, move, delete or add to them. If the work truly needs a different input, end with status "blocked" and say which and why.',
+    ]
+        .filter(Boolean)
+        .join(' ');
+}
+/** The lines the version-control note carries about the inputs. */
+export function inputsNote(inputs) {
+    if (!inputs || inputs.files.length === 0)
+        return '';
+    const shown = inputs.files.slice(0, 20).map((f) => `\`${f.path}\``).join(', ');
+    return (`The operator's input files are in your working tree, committed in the starting commit: ${shown}` +
+        `${inputs.files.length > 20 ? `, and ${inputs.files.length - 20} more` : ''}. ` +
+        (inputs.readOnly
+            ? 'They are read-only: read them, never change, move or delete them, and add nothing under their paths. The runner puts them back after every round of steps.'
+            : 'They are the work\'s input; change them only if the task says so.'));
+}