copilot-operator 0.1.8 → 0.1.10

package/dist/src/protocol/parser.js

@@ -60,8 +60,83 @@ export function stripCitations(text) {
         return undefined;
     return text.replace(/\s*【[^】]*】/g, '').replace(/[ 	]+$/gm, '').trim();
 }
+/*
+ * Prose that arrived in another shape.
+ *
+ * `tried`, `needed`, `notes` and `summary` are sentences for a person to read; nothing in them is
+ * run. A chat that writes `tried` as a list of objects — `{"approach": "…", "result": "…"}` — has
+ * said exactly what was asked, in a shape the schema did not expect, and refusing the whole reply
+ * for it cost a format round each time and, three in a row, the task: it ended "failed" with the
+ * work done and its results already recorded. So these fields are read as text whatever shape they
+ * come in, and the reading is reported. The fields that are acted on — `status`, `steps` and
+ * everything in them — are never coerced: a step the runner would have to guess at is not run.
+ */
+const PROSE_KEYS = ['approach', 'what', 'tried', 'attempt', 'action', 'description', 'text', 'summary', 'detail', 'result', 'outcome', 'why', 'reason', 'needed'];
+function proseOf(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return value.map(proseOf).filter((x) => x.trim()).join('\n');
+    if (typeof value === 'object') {
+        const record = value;
+        const named = PROSE_KEYS.filter((k) => typeof record[k] === 'string' && record[k].trim()).map((k) => record[k]);
+        if (named.length > 0)
+            return named.join(' — ');
+        const strings = Object.values(record).filter((v) => typeof v === 'string' && v.trim() !== '');
+        return strings.length > 0 ? strings.join(' — ') : JSON.stringify(value);
+    }
+    return String(value);
+}
+export function normaliseProse(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return { value, coerced: [] };
+    const out = { ...value };
+    const coerced = [];
+    for (const key of ['notes', 'summary', 'needed']) {
+        if (key in out && out[key] !== undefined && typeof out[key] !== 'string') {
+            out[key] = proseOf(out[key]);
+            coerced.push(key);
+        }
+    }
+    if ('tried' in out && out.tried !== undefined) {
+        const tried = out.tried;
+        if (typeof tried === 'string') {
+            out.tried = tried.trim() ? [tried] : [];
+            coerced.push('tried');
+        }
+        else if (Array.isArray(tried) && tried.some((t) => typeof t !== 'string')) {
+            out.tried = tried.map(proseOf).filter((t) => t.trim() !== '');
+            tried.forEach((t, i) => {
+                if (typeof t !== 'string')
+                    coerced.push(`tried.${i}`);
+            });
+        }
+    }
+    return { value: out, coerced };
+}
+/** What each field must look like, said in the message that asks for a reformatted reply. */
+const FIELD_SHAPES = [
+    [/^status$/, '"status" is one of "continue", "done", "blocked"'],
+    [/^steps(\.|$)/, '"steps" is a list of {"id": 1, "type": "command", "cmd": "the command"} ("shell", "expect", "timeoutSec" optional)'],
+    [/^tried(\.|$)/, '"tried" is a list of plain strings, one sentence per approach'],
+    [/^deviations(\.|$)/, '"deviations" is a list of {"instruction": "…", "did": "…", "why": "…"} with plain strings'],
+    [/^disputed(\.|$)/, '"disputed" is a list of {"finding": "…", "why": "…", "evidence": "…"} with plain strings'],
+    [/^(summary|notes|needed)$/, '"summary", "notes" and "needed" are plain strings'],
+];
+const FORMAT_EXAMPLE = [
+    '```json',
+    '{"status": "continue", "notes": "what this round does", "steps": [{"id": 1, "type": "command", "cmd": "npm test"}]}',
+    '```',
+    'or, to end: {"status": "done", "summary": "several sentences on what was done and what it shows"}',
+    'or {"status": "blocked", "summary": "…", "tried": ["first approach", "second approach"], "needed": "what would unblock it"}',
+].join('\n');
 export function parseReply(markdown, opts) {
     const candidates = findJsonCandidates(markdown);
+    const paths = new Set();
     if (candidates.length === 0) {
         return {
             ok: false,
@@ -80,9 +155,12 @@ export function parseReply(markdown, opts) {
                 errors.push(`JSON.parse failed: ${e.message}`);
                 continue;
             }
-            const result = ReplySchema.safeParse(value);
+            const prose = normaliseProse(value);
+            const result = ReplySchema.safeParse(prose.value);
             if (!result.success) {
                 errors.push(result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; '));
+                for (const i of result.error.issues)
+                    paths.add(i.path.join('.') || '(root)');
                 continue;
             }
             const reply = result.data;
@@ -106,6 +184,7 @@ export function parseReply(markdown, opts) {
                 done: reply.status === 'done' || (markerHit && hasSummary && !blocked),
                 blocked,
                 json: text.trim(),
+                ...(prose.coerced.length > 0 ? { coerced: prose.coerced } : {}),
             };
         }
     }
@@ -113,6 +192,7 @@ export function parseReply(markdown, opts) {
         ok: false,
         reason: 'invalid-json',
         detail: errors.slice(0, 4).join(' | '),
+        ...(paths.size > 0 ? { paths: [...paths] } : {}),
     };
 }
 /**
@@ -162,15 +242,28 @@ export function parseReview(markdown, opts) {
     return { ok: false, reason: 'invalid-json', detail: errors.slice(0, 4).join(' | ') };
 }
 /** The message sent back when a reply did not validate. Names the problem, nothing else. */
+/**
+ * The message that asks for the same answer again, in the format.
+ *
+ * It names each rejected field with the shape it must have, gives a valid example, and says what
+ * did not happen: nothing from the rejected reply was run, so the results of the steps before it
+ * stand and the answer only needs reformatting. Without that last part a chat told "invalid" tends
+ * to start the round again, or to keep the same shape and change the wording, and the rounds run out.
+ */
 export function formatErrorMessage(fail, attempt, maxAttempts) {
+    const shapes = [...new Set((fail.paths ?? []).flatMap((p) => FIELD_SHAPES.filter(([re]) => re.test(p)).map(([, s]) => s)))];
     return [
-        `Your last reply did not match the required format (attempt ${attempt} of ${maxAttempts}).`,
+        `Your last reply did not match the required format (format retry ${attempt} of ${maxAttempts}).`,
         fail.reason === 'no-json-block'
             ? 'There was no fenced json code block in it.'
             : `The json block did not validate: ${fail.detail}`,
-        'Resend the same answer as exactly one fenced code block tagged json, with the fields',
-        'status, steps and notes, and nothing else tagged json in the reply.',
-    ].join(' ');
+        shapes.length > 0 ? `What those fields must be: ${shapes.join('; ')}.` : '',
+        'Only the format is wrong. Nothing from that reply was run, and the results of the steps before it stand.',
+        'Send the same answer again, reformatted, as exactly one fenced code block tagged json — do not start over and do not change what it asks for. For example:',
+        FORMAT_EXAMPLE,
+    ]
+        .filter(Boolean)
+        .join('\n');
 }
 /**
  * Spots a command that arrived damaged rather than badly written.

package/dist/src/session/compose.js

@@ -11,7 +11,7 @@ const TASK_HEADER = '## Task';
  * and a note that is empty simply leaves nothing behind.
  */
 function runnerBlock(input) {
-    const notes = [input.workDirNote, input.readOnlyNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
+    const notes = [input.workDirNote, input.readOnlyNote, input.scopeNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
     return notes.length > 0 ? `${notes.join('\n\n')}\n\n` : '';
 }
 /**

package/dist/src/session/exports.js

@@ -168,6 +168,8 @@ export function buildPlanExport(scope) {
                         task.review = false;
                     if (t.readOnly)
                         task.readOnly = true;
+                    if (t.scope && t.scope.length > 0)
+                        task.scope = [...t.scope];
                     const earlier = earlierPlans(t, level2);
                     if (earlier.length > 0)
                         task.earlierAttempts = earlier;
@@ -394,6 +396,10 @@ async function domainTask(session, task, runsDir) {
             title: task.title,
             attempt: task.attempt ?? 1,
             readOnly: task.readOnly ?? false,
+            scope: task.scope ?? [],
+            scopeReverted: task.scopeReverted ?? [],
+            handoff: task.handoff ?? null,
+            stopCode: task.stopCode ?? null,
             prompt: p.prompt,
             expected: p.expected,
             level2: task.level2,

package/dist/src/session/handoff.js

@@ -0,0 +1,42 @@
+export function composeHandoff(task, notRun = []) {
+    const failedChecks = (task.checkResults ?? []).filter((c) => !c.passed);
+    const openFindings = task.review?.verdict === 'fail' ? (task.review.findings ?? []).filter((f) => f.about !== 'task') : [];
+    const vcs = task.vcs ?? {};
+    const knownIssues = [
+        ...failedChecks.map((c) => `check failed: ${c.name} — ${c.detail}`),
+        ...openFindings.map((f) => `review finding${f.id ? ` ${f.id}` : ''}: ${f.what}${f.where ? ` (${f.where})` : ''}`),
+        ...(task.checkResults ?? [])
+            .filter((c) => c.passed && /still there after being pointed out once/.test(c.detail))
+            .map((c) => `committed with a finding left in place: ${c.name}`),
+        ...(vcs.suspicious ?? []).map((s) => `committed although it looks like ${s.reason}: ${s.path}`),
+        ...(vcs.foreignCommits ?? []).map((c) => `a commit on the branch the runner did not make: ${c}`),
+        ...(task.scopeReverted?.length ? [`put back because outside the task's scope: ${task.scopeReverted.join(', ')}`] : []),
+        ...(task.deviations ?? []).map((d) => `did not follow "${d.instruction}" as written: ${d.did}`),
+    ];
+    const manual = [];
+    if (vcs.problem)
+        manual.push(`version control: ${vcs.problem}`);
+    if (vcs.commit && vcs.branch)
+        manual.push(`push ${vcs.branch} when you are ready — the runner never pushes`);
+    if (task.status === 'blocked')
+        manual.push(`unblock it: ${task.reason ?? 'see the reason'}`);
+    if (task.status === 'limit-reached' || task.status === 'aborted')
+        manual.push('continue it in the same chat from the register, or run it again');
+    if (task.status === 'failed')
+        manual.push('read why it failed, fix the prompt or the checks, and queue it again');
+    if (openFindings.length > 0)
+        manual.push(`${openFindings.length} review finding(s) are open`);
+    if ((vcs.suspicious?.length ?? 0) > 0 || (vcs.foreignCommits?.length ?? 0) > 0)
+        manual.push('look at the committed files and commits listed above');
+    return {
+        outcome: { status: task.status, ...(task.reason ? { reason: task.reason } : {}), ...(task.stopCode ? { stopCode: task.stopCode } : {}) },
+        changedFiles: (vcs.files ?? []).map((f) => ({ path: f.path, added: f.added, removed: f.removed })),
+        validation: (task.checkResults ?? []).map((c) => ({ name: c.name, passed: c.passed })),
+        ...(task.review ? { review: { verdict: task.review.verdict, open: openFindings.length } } : {}),
+        knownIssues,
+        evidence: { ...(task.runId ? { runId: task.runId } : {}), checks: task.checkResults?.length ?? 0, reviewRounds: task.review?.rounds ?? 0 },
+        vcs: { ...(vcs.branch ? { branch: vcs.branch } : {}), ...(vcs.commit ? { commit: vcs.commit } : {}), pushed: false, ...(vcs.problem ? { problem: vcs.problem } : {}) },
+        manual,
+        notExecuted: notRun.slice(0, 30).map((n) => `${n.command} — ${n.why}`),
+    };
+}

package/dist/src/session/metrics.js

@@ -0,0 +1,95 @@
+const ENDED = ['done', 'failed', 'blocked', 'aborted', 'limit-reached'];
+function attemptsOf(task) {
+    const all = [...(task.attempts ?? [])];
+    if (ENDED.includes(task.status))
+        all.push(task);
+    return all.filter((a) => ENDED.includes(a.status));
+}
+function modelOf(session) {
+    return (session.modelInUse ?? '').trim() || (session.model ?? '').trim() || '(the chat default)';
+}
+function row(group, tasks) {
+    const r = {
+        group,
+        tasks: 0,
+        attempts: 0,
+        firstPass: { n: 0, of: 0 },
+        doneInTheEnd: { n: 0, of: 0 },
+        ended: {},
+        freshRetries: 0,
+        manualInterventions: 0,
+        falseCompletion: { n: 0, of: 0 },
+        reviewRejection: { n: 0, of: 0 },
+        repeatedCommands: { n: 0, of: 0 },
+        scopeViolation: { n: 0, of: 0 },
+        noProgress: { n: 0, of: 0 },
+        unrelatedDiff: { n: 0, of: 0 },
+        resumed: { n: 0, of: 0 },
+        withStats: 0,
+    };
+    for (const task of tasks) {
+        const list = attemptsOf(task);
+        if (list.length === 0)
+            continue;
+        r.tasks += 1;
+        r.attempts += list.length;
+        r.firstPass.of += 1;
+        if (list[0].status === 'done')
+            r.firstPass.n += 1;
+        const last = list[list.length - 1];
+        r.doneInTheEnd.of += 1;
+        if (last.status === 'done')
+            r.doneInTheEnd.n += 1;
+        r.ended[last.status] = (r.ended[last.status] ?? 0) + 1;
+        list.forEach((a, i) => {
+            if (a.freshRetry)
+                r.freshRetries += 1;
+            else if (i > 0)
+                r.manualInterventions += 1;
+            r.unrelatedDiff.of += 1;
+            if ((a.vcs?.suspicious?.length ?? 0) > 0 || (a.vcs?.foreignCommits?.length ?? 0) > 0)
+                r.unrelatedDiff.n += 1;
+            if ((a.scope?.length ?? 0) > 0) {
+                r.scopeViolation.of += 1;
+                if ((a.scopeReverted?.length ?? 0) > 0)
+                    r.scopeViolation.n += 1;
+            }
+            if (a.continuing) {
+                r.resumed.of += 1;
+                if (a.status === 'done')
+                    r.resumed.n += 1;
+            }
+            if (a.review && a.review.verdict !== 'skipped') {
+                r.reviewRejection.of += 1;
+                if ((a.stats?.reviewRejections ?? 0) > 0 || a.review.verdict === 'fail' || (a.review.rounds ?? 0) > 1)
+                    r.reviewRejection.n += 1;
+            }
+            if (!a.stats)
+                return;
+            r.withStats += 1;
+            r.manualInterventions += a.stats.operatorStops;
+            r.falseCompletion.of += 1;
+            if (a.stats.doneRejected > 0)
+                r.falseCompletion.n += 1;
+            r.repeatedCommands.of += 1;
+            if (a.stats.repeatsRefused > 0)
+                r.repeatedCommands.n += 1;
+            r.noProgress.of += 1;
+            if (a.stats.stoppedFor === 'no-progress')
+                r.noProgress.n += 1;
+        });
+    }
+    return r;
+}
+/** All tasks, then one row per model the sessions ran on, busiest first. */
+export function computeMetrics(sessions, now = new Date()) {
+    const all = sessions.flatMap((s) => s.tasks);
+    const byModel = new Map();
+    for (const s of sessions)
+        byModel.set(modelOf(s), [...(byModel.get(modelOf(s)) ?? []), ...s.tasks]);
+    const models = [...byModel.entries()]
+        .map(([group, tasks]) => row(group, tasks))
+        .filter((r) => r.tasks > 0)
+        .sort((a, b) => b.tasks - a.tasks);
+    return { rows: [row('all', all), ...(models.length > 1 ? models : [])], computedAt: now.toISOString() };
+}

package/dist/src/session/store.js

@@ -42,6 +42,47 @@ export const DEFAULT_MIRROR = {
     respectGitignore: true,
     includeEnvFiles: false,
 };
+/**
+ * Applies an edit to a task: the one place the rule about a new intent lives.
+ *
+ * A task given a new prompt is a new question. The checks the reviews of its earlier attempts
+ * added were findings about the old question, and inheriting them gated the new one on work it
+ * no longer asks for: a maintenance task rewritten as an audit still had to pass "the build uses
+ * the new config", and went blocked on an artificial finding. So a changed prompt drops them, with
+ * the reason kept beside each, and they stay on the record. The plan's own checks are not guessed
+ * at: whoever writes the new prompt says which still apply (the edit form and the new-prompt
+ * dialog both show them), and `checks` in the patch is that answer. A re-run with the same prompt
+ * keeps everything, because it is the same question asked again.
+ */
+export function applyTaskPatch(t, patch) {
+    const newPrompt = patch.prompt !== undefined && patch.prompt.trim() !== '' && patch.prompt.trim() !== t.prompt.trim();
+    if (patch.title !== undefined)
+        t.title = patch.title.trim() || t.title;
+    if (patch.prompt !== undefined && patch.prompt.trim())
+        t.prompt = patch.prompt;
+    if (patch.level2 !== undefined)
+        t.level2 = patch.level2;
+    if (patch.vcsPlan !== undefined)
+        t.vcsPlan = tidyVcsPlan(patch.vcsPlan);
+    if (patch.checks !== undefined)
+        t.checks = patch.checks.filter((c) => c.name.trim() !== '');
+    if (patch.readOnly !== undefined) {
+        if (patch.readOnly)
+            t.readOnly = true;
+        else
+            delete t.readOnly;
+    }
+    if (patch.scope !== undefined) {
+        const scope = patch.scope.map((p) => p.trim()).filter(Boolean);
+        if (scope.length > 0)
+            t.scope = scope;
+        else
+            delete t.scope;
+    }
+    if (newPrompt && t.reviewChecks?.length) {
+        t.reviewChecks = t.reviewChecks.map((rc) => rc.state === 'dropped' ? rc : { ...rc, state: 'dropped', droppedBecause: 'the task was given a new prompt; this was a finding about the old one' });
+    }
+}
 export class SessionStore {
     defaultLevel1Path;
     dir;
@@ -251,6 +292,8 @@ export class SessionStore {
             ...(input.reviewEnabled === false ? { reviewEnabled: false } : {}),
             // Only `true` is worth storing: a task may change files unless a plan said otherwise.
             ...(input.readOnly === true ? { readOnly: true } : {}),
+            // Stored only when it limits something: absent means anywhere, as before scopes existed.
+            ...((input.scope ?? []).filter((p) => p.trim()).length > 0 ? { scope: (input.scope ?? []).map((p) => p.trim()).filter(Boolean) } : {}),
         };
         await this.updateSession(sessionId, (s) => {
             s.tasks.push(task);
@@ -352,20 +395,18 @@ export class SessionStore {
                     checks: t.checks,
                     vcsPlan: t.vcsPlan,
                     review: t.review,
+                    stats: t.stats,
+                    continuing: t.continuing,
+                    buildsOn: t.buildsOn,
+                    freshRetry: t.freshRetry,
+                    stopCode: t.stopCode,
+                    scope: t.scope,
+                    scopeReverted: t.scopeReverted,
                     vcs: t.vcs,
                 },
             ];
             // An edit is applied only after the old attempt has been put beyond its reach.
-            if (patch.title !== undefined)
-                t.title = patch.title.trim() || t.title;
-            if (patch.prompt !== undefined && patch.prompt.trim())
-                t.prompt = patch.prompt;
-            if (patch.level2 !== undefined)
-                t.level2 = patch.level2;
-            if (patch.vcsPlan !== undefined)
-                t.vcsPlan = tidyVcsPlan(patch.vcsPlan);
-            if (patch.checks !== undefined)
-                t.checks = patch.checks.filter((c) => c.name.trim() !== '');
+            applyTaskPatch(t, patch);
             t.attempt = (t.attempt ?? 1) + 1;
             t.status = 'queued';
             t.iterations = 0;
@@ -390,6 +431,13 @@ export class SessionStore {
             // the one thing a new attempt should inherit.
             t.deviations = undefined;
             t.disputes = undefined;
+            // Counts, the ending and what was put back belong to the attempt above too. A fresh-chat retry
+            // marks itself again after this, in the runner.
+            t.stats = undefined;
+            t.handoff = undefined;
+            t.scopeReverted = undefined;
+            t.freshRetry = undefined;
+            t.stopCode = 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;

package/dist/src/transport/chatTransport.js

@@ -0,0 +1,32 @@
+/**
+ * What the runner, the reviewer and the API need from a chat, and where that chat comes from.
+ *
+ * Everything that talks to Copilot goes through `CopilotTransport`, which drives a real Edge window
+ * signed in to Microsoft 365. That is the product, and it is also why nothing above the transport
+ * could be tested end to end: every run opened a browser, signed in and spent the operator's hourly
+ * message allowance. The loop itself — send, read the reply, run the steps, report back, stop at the
+ * limit, carry on after an interruption, commit on the right branch — never touches the page, only
+ * these few methods. So the rest of the code asks for a `ChatTransport` and gets one from
+ * `createTransport`, and the automated checks put a scripted chat in its place (test/support/fakeChat.ts)
+ * that answers from a script and never opens a window.
+ *
+ * The type is a `Pick` of the real class rather than an interface written out by hand, so the two
+ * cannot drift apart: a method that changes its signature in `CopilotTransport` changes it here, and
+ * the scripted chat stops compiling instead of passing checks against a shape the product no longer has.
+ *
+ * Deliberately, nothing outside the code can swap the chat: no environment variable, no setting, no
+ * command-line flag. A scripted chat hands the runner steps to execute, and a switch that a file or
+ * an environment could flip would be a way to make the bot run commands nobody reviewed. Only code
+ * running in this process — a check script — can call `setTransportFactory`.
+ */
+import { CopilotTransport } from './copilotTransport.js';
+const realChat = (opts) => new CopilotTransport(opts);
+let factory = realChat;
+/** A chat for these options: the real Copilot window, unless a check has put a scripted one in. */
+export function createTransport(opts) {
+    return factory(opts);
+}
+/** For checks only: every chat opened from now on comes from `f`. `null` puts the real one back. */
+export function setTransportFactory(f) {
+    factory = f ?? realChat;
+}

package/dist/src/transport/copilotTransport.js

@@ -750,12 +750,30 @@ Current URL: ${url}`);
             await this.closeMenu();
             return { ok: false, current: before, reason: `The picker does not offer "${name}" any more.` };
         }
+        /*
+         * Already the one in force: close the menu and say so, without clicking.
+         *
+         * The button cannot answer this on its own, because it shortens names — "GPT 5.6 Think deeper"
+         * reads "GPT 5.6 Think" — so the exact comparison above lets a chat that is already on the
+         * model through to here. The row's own mark (`aria-checked` and its kin) is the answer. The
+         * click it used to get did nothing in Copilot: the row already in force ignores it, the menu
+         * stayed open over the composer, and the run went on with the model list hanging on screen.
+         */
+        if (target.selected) {
+            await this.closeMenu();
+            this.emit('model-already-selected', { model: target.name, buttonShows: before });
+            return { ok: true, current: target.name };
+        }
         if (target.disabled) {
             await this.closeMenu();
             return { ok: false, current: before, reason: `"${name}" is shown but not available right now.` };
         }
         await this.clickMenuRow(target.name, inSubmenu);
         await this.p.waitForTimeout(1_000);
+        // Whatever the click did, the menu is not left open over the chat: a build that keeps it open
+        // after a choice, or a click that did not land, would otherwise leave it for the next message.
+        if ((await this.readMenuRows()).length > 0)
+            await this.closeMenu();
         const after = await this.currentModel();
         // The button shows the choice, so it is the check. It also **shortens** it: picking
         // "GPT 5.6 Quick response" leaves the button reading "GPT 5.6 Quick". So a shown value

package/dist/src/vcs/contentIntegrity.js

@@ -0,0 +1,174 @@
+/**
+ * What the text a task wrote should not contain, checked before it is committed.
+ *
+ * `commitHygiene.ts` looks at which files would be committed. This looks inside them, because the
+ * damage a Windows shell does to text is invisible to a formatter and to a reviewer reading a diff
+ * in a browser: PowerShell 5.1's `Set-Content -Encoding utf8` puts a byte-order mark in front of a
+ * JSON file and `JSON.parse` then refuses it; text read in one code page and written in another
+ * comes out as `é` or, for Cyrillic, `а` and `Р°`; a decoder that gave up leaves `�`; a terminal's
+ * colour codes pasted into a file leave ESC characters; one file ends up half CRLF and half LF.
+ * Also a private key or an access token written into a file, which a path check cannot see.
+ *
+ * Every finding is about what THIS task did. A file is compared with the same file at the commit the
+ * task started from, and a kind of problem already there is not reported: a repository that has
+ * always had CRLF and LF mixed in one file is not this task's fault, and blaming it would send the
+ * chat to "fix" a file it was never asked to touch.
+ *
+ * Used as a check the runner adds by itself when it is going to commit (`content-clean`, see
+ * `checks.ts`), with the same rule as the path check: pointed out to the chat once; a second "done"
+ * with the problem still there is committed and the finding stays on the task where a person sees it.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { gitBytes } from './git.js';
+import { looksGenerated } from './commitHygiene.js';
+/** Written files larger than this are almost always generated output. */
+export const OVERSIZED_BYTES = 1024 * 1024;
+/** Files that are binary by nature: their bytes are not text and are not looked into. */
+const BINARY_EXTENSIONS = new Set([
+    'png', 'jpg', 'jpeg', 'gif', 'bmp', 'ico', 'webp', 'tif', 'tiff', 'avif', 'psd',
+    'pdf', 'zip', '7z', 'gz', 'tgz', 'bz2', 'xz', 'rar', 'jar', 'war', 'nupkg',
+    'woff', 'woff2', 'ttf', 'otf', 'eot',
+    'exe', 'dll', 'so', 'dylib', 'bin', 'obj', 'o', 'a', 'lib', 'pdb', 'class', 'wasm',
+    'mp3', 'mp4', 'wav', 'ogg', 'webm', 'mov', 'avi',
+    'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'odt', 'ods',
+    'sqlite', 'db', 'mdb', 'pfx', 'p12', 'der',
+]);
+/**
+ * Text formats where a byte-order mark breaks the reader: JSON.parse, a shell's shebang line, YAML
+ * and TOML parsers, Node's module loader for the first line. A BOM in these is reported even in a
+ * new file; in any other text file only when the file had none before.
+ */
+const BOM_BREAKS = new Set(['json', 'jsonc', 'js', 'mjs', 'cjs', 'ts', 'mts', 'cts', 'tsx', 'jsx', 'sh', 'bash', 'yml', 'yaml', 'toml', 'py', 'env', 'html', 'css', 'scss', 'md']);
+function extensionOf(path) {
+    const name = path.replace(/\\/g, '/').split('/').pop() ?? '';
+    const dot = name.lastIndexOf('.');
+    return dot > 0 ? name.slice(dot + 1).toLowerCase() : '';
+}
+/*
+ * Mojibake: UTF-8 bytes decoded in a single-byte code page and written back as UTF-8.
+ *
+ * Latin text through Windows-1252 turns "é" into "é" and "’" into "’". Cyrillic through
+ * Windows-1252 turns "а" into "а"; through Windows-1251, into "Р°". The second character is what
+ * gives it away: it is one of the characters the code page puts at bytes 0x80–0xBF, which real text
+ * almost never places right after "Ã", "Ð", "Ñ", "Р" or "С". Plain "Ра" (Cyrillic Р then а) is
+ * ordinary Bulgarian and does not match, because "а" is not in that range.
+ */
+const CP1252_HIGH = '€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ -¿';
+const CP1251_HIGH = 'ЂЃ‚ѓ„…†‡€‰Љ‹ЊЌЋЏђ‘’“”•–—™љ›њќћџ ЎўЈ¤Ґ¦§Ё©Є«¬­®Ї°±Ііґµ¶·ё№є»јЅѕї';
+const MOJIBAKE = new RegExp(`[ÃÂÐÑâ][${CP1252_HIGH}]|[РС][${CP1251_HIGH}]`, 'g');
+/** Control characters other than tab, line feed and carriage return; NUL is counted as binary. */
+const CONTROL = /[\u0001-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+/*
+ * Credentials by their shape. Only formats that are unambiguous — a private key block, and tokens
+ * whose prefix is the issuer's own — so a test fixture that says `password = "secret"` is not one.
+ */
+const SECRETS = [
+    [/-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED |PGP )?PRIVATE KEY(?: BLOCK)?-----/, 'a private key'],
+    [/\bAKIA[0-9A-Z]{16}\b/, 'an AWS access key id'],
+    [/\bgh[pousr]_[A-Za-z0-9]{36,}\b/, 'a GitHub token'],
+    [/\bgithub_pat_[A-Za-z0-9_]{50,}\b/, 'a GitHub token'],
+    [/\bxox[abposr]-[A-Za-z0-9-]{10,}\b/, 'a Slack token'],
+    [/\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{32,}\b/, 'an API secret key'],
+    [/AccountKey=[A-Za-z0-9+/=]{40,}/, 'an Azure storage account key'],
+    [/\bAIza[0-9A-Za-z_-]{35}\b/, 'a Google API key'],
+];
+/** Every kind of problem a file's bytes show, with a short description of each. */
+export function traitsOf(path, bytes) {
+    const t = {};
+    if (bytes.length > OVERSIZED_BYTES)
+        t.oversized = `${(bytes.length / 1024 / 1024).toFixed(1)} MB, far more than anyone writes by hand`;
+    // A NUL in the first 8 KB is how git itself decides a file is binary.
+    if (bytes.subarray(0, 8192).includes(0)) {
+        t['binary-in-text'] = 'NUL bytes in what should be a text file';
+        return t;
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
+        t.bom = 'starts with a UTF-8 byte-order mark';
+    const text = bytes.toString('utf8');
+    const replacement = (text.match(/�/g) ?? []).length;
+    if (replacement > 0)
+        t['replacement-char'] = `${replacement} "�" (text that was decoded with the wrong encoding, or invalid UTF-8)`;
+    const mojibake = text.match(MOJIBAKE) ?? [];
+    // Two or more, so one stray pair in a legitimate string does not count.
+    if (mojibake.length >= 2)
+        t.mojibake = `${mojibake.length} sequences such as "${mojibake.slice(0, 3).join('", "')}" (UTF-8 read in another code page)`;
+    const control = (text.match(CONTROL) ?? []).length;
+    if (control > 0)
+        t['control-chars'] = `${control} control character(s)${text.includes('\u001B[') ? ', including terminal colour codes' : ''}`;
+    const crlf = (text.match(/\r\n/g) ?? []).length;
+    const lf = (text.match(/(?<!\r)\n/g) ?? []).length;
+    if (crlf > 0 && lf > 0)
+        t['mixed-line-endings'] = `${crlf} CRLF and ${lf} LF line ending(s) in one file`;
+    for (const [re, what] of SECRETS) {
+        if (re.test(text)) {
+            t.secret = `what looks like ${what}`;
+            break;
+        }
+    }
+    return t;
+}
+/**
+ * The problems `now` has that `before` did not. `before` is null for a file the task created.
+ *
+ * A BOM in a new file counts only for formats it breaks; in a changed file, whenever the file had
+ * none. Size counts only when the file crossed the line in this task.
+ */
+export function newProblems(path, now, before) {
+    const ext = extensionOf(path);
+    if (BINARY_EXTENSIONS.has(ext))
+        return [];
+    const had = before ? traitsOf(path, before) : {};
+    const has = traitsOf(path, now);
+    const out = [];
+    for (const [kind, detail] of Object.entries(has)) {
+        if (had[kind])
+            continue;
+        if (kind === 'bom' && !before && !BOM_BREAKS.has(ext))
+            continue;
+        out.push({ path, kind, detail });
+    }
+    return out;
+}
+/** The problems the task added to these working-tree paths, compared with `baseCommit`. */
+export async function scanChanges(dir, paths, baseCommit, limit = 400) {
+    const found = [];
+    for (const rel of paths.slice(0, limit)) {
+        if (rel.endsWith('/') || looksGenerated(rel))
+            continue;
+        const abs = join(dir, rel);
+        const info = await stat(abs).catch(() => null);
+        if (!info?.isFile())
+            continue;
+        if (BINARY_EXTENSIONS.has(extensionOf(rel)))
+            continue;
+        // A very large file is not read: its size is the finding, compared with the size it had before.
+        if (info.size > OVERSIZED_BYTES * 4) {
+            const was = baseCommit ? await gitBytes(dir, ['cat-file', '-s', `${baseCommit}:${rel.replace(/\\/g, '/')}`]) : null;
+            const wasSize = was?.ok ? Number(was.stdout.toString('utf8').trim()) : 0;
+            if (wasSize <= OVERSIZED_BYTES) {
+                found.push({ path: rel, kind: 'oversized', detail: `${(info.size / 1024 / 1024).toFixed(1)} MB, far more than anyone writes by hand` });
+            }
+            continue;
+        }
+        const now = await readFile(abs).catch(() => null);
+        if (!now)
+            continue;
+        let before = null;
+        if (baseCommit) {
+            const shown = await gitBytes(dir, ['show', `${baseCommit}:${rel.replace(/\\/g, '/')}`]);
+            before = shown.ok ? shown.stdout : null;
+        }
+        found.push(...newProblems(rel, now, before));
+    }
+    return found;
+}
+/** What the chat is told, once, before the commit. */
+export function integrityDetail(found) {
+    const list = found.slice(0, 20).map((f) => `${f.path}: ${f.detail}`).join('; ');
+    return (`${found.length} problem(s) in the text of files this task changed, none of them there before it: ${list}` +
+        `${found.length > 20 ? `; and ${found.length - 20} more` : ''}. Write the files again as UTF-8 without a byte-order mark ` +
+        '(in PowerShell 5.1 use [IO.File]::WriteAllText with New-Object Text.UTF8Encoding($false), not Set-Content -Encoding utf8), ' +
+        'one kind of line ending per file, no terminal colour codes, and no credentials — load those from the environment. ' +
+        'If one of these is intended, leave it and say why in your summary: it will be committed and the finding kept on the task.');
+}