copilot-operator 0.1.0

package/dist/src/transport/edgeCrash.js

@@ -0,0 +1,59 @@
+/**
+ * Naming an Edge crash, so a run that dies says why.
+ *
+ * When the browser process goes away, every Playwright call afterwards fails with "Target
+ * page, context or browser has been closed", which explains nothing: a closed window, a
+ * second Edge on the same profile and a crash all read the same. But Edge writes a minidump
+ * into the profile's `Crashpad/reports` the instant it crashes, with the process type and the
+ * version in `watson_metadata` next to it. A run that ended that way can point at the report
+ * — which is what made the attachment crash diagnosable at all: three reports, one per
+ * attempt, `ProcessType=browser`, the same `SubCode`, and the click was the cause.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The last values of the fields that matter, out of the binary metadata file. */
+export function parseWatsonMetadata(text) {
+    const last = (re) => {
+        let value;
+        for (const m of text.matchAll(re))
+            value = m[1];
+        return value;
+    };
+    return {
+        processType: last(/ProcessType=([A-Za-z-]+)/g),
+        version: last(/ApplicationVersion=([0-9.]+)/g),
+        subCode: last(/SubCode=(0x[0-9A-Fa-f]+)/g),
+    };
+}
+/** The newest minidump written within `sinceMs`, with what the metadata says about it. */
+export async function findRecentCrash(profileDir, sinceMs = 5 * 60_000, now = Date.now()) {
+    const dir = join(profileDir, 'Crashpad', 'reports');
+    let names;
+    try {
+        names = (await readdir(dir)).filter((n) => n.toLowerCase().endsWith('.dmp'));
+    }
+    catch {
+        return null;
+    }
+    let newest = null;
+    for (const name of names) {
+        const path = join(dir, name);
+        const s = await stat(path).catch(() => null);
+        if (!s)
+            continue;
+        if (s.mtimeMs < now - sinceMs)
+            continue;
+        if (!newest || s.mtimeMs > newest.mtime)
+            newest = { path, mtime: s.mtimeMs };
+    }
+    if (!newest)
+        return null;
+    const meta = await readFile(join(profileDir, 'Crashpad', 'watson_metadata'), 'latin1').catch(() => '');
+    return { report: newest.path, at: new Date(newest.mtime).toISOString(), ...parseWatsonMetadata(meta) };
+}
+/** One sentence for a task's reason and the log. */
+export function describeCrash(c) {
+    const what = c.processType ? `Edge's ${c.processType} process crashed` : 'Edge crashed';
+    const details = [c.version ? `Edge ${c.version}` : '', c.subCode ? `code ${c.subCode}` : ''].filter(Boolean).join(', ');
+    return `${what}${details ? ` (${details})` : ''} at ${c.at}; report: ${c.report}`;
+}

package/dist/src/transport/locators.js

@@ -0,0 +1,261 @@
+/**
+ * The ONLY file in the project that knows about the Copilot web UI's DOM.
+ *
+ * Captured live from https://m365.cloud.microsoft/chat on 2026-09-17.
+ *
+ * Rule of thumb for maintenance: `data-testid` values and `aria-label` values are
+ * stable across deployments; Fluent UI class hashes (f1c21dwh, ___7qar2c0, OGl5QnhL)
+ * are NOT — never select on them. The `scriptor-*` class names are semantic and
+ * are the one exception, because the code-block widget exposes no test id.
+ */
+/** Stable `data-testid` values in the chat surface. */
+export const TestId = {
+    /** Scroll container holding every turn. */
+    messageList: 'MessageListContainer',
+    /** One conversation turn: contains both the user question and the Copilot answer. */
+    turn: 'm365-chat-llm-web-ui-chat-message',
+    /** The user's own message inside a turn. */
+    userMessage: 'chatQuestion',
+    /** The Copilot answer inside a turn. */
+    assistantOutput: 'chatOutput',
+    /** Wrapper of one Copilot answer; its DOM id is `chatMessageResponse-<hash>`. */
+    assistantMessage: 'copilot-message-div',
+    /** Body of the Copilot answer (no toolbar). */
+    assistantReplyBody: 'copilot-message-reply-div',
+    /** Rendered markdown of the answer. Download links and code blocks live here. */
+    markdownReply: 'markdown-reply',
+    /** Present on the newest answer only. */
+    lastMessage: 'lastChatMessage',
+    /** Message-level copy button (aria-label "Copy Response"). */
+    copyResponse: 'CopyButtonTestId',
+    /** Composer add-sources ("+") button. Opens the menu; not needed for uploads. */
+    plusMenu: 'PlusMenuButton',
+};
+/**
+ * File upload.
+ *
+ * The page keeps a hidden, always-present multi-file input in the DOM. Playwright can
+ * call `setInputFiles` on it directly, so the bot never opens the "+" menu and never
+ * touches a native Windows file dialog.
+ *
+ * Its `accept` list includes `.txt` and `text/plain`, which is what the runner reports use.
+ * Also accepted, should we ever need them: .log, .json, .csv, .md, .xml, .yml. .ps1 is NOT
+ * in the list. Uploads are the runner's own reports; nothing is ever downloaded.
+ */
+export const Upload = {
+    /** Hidden `<input type="file" multiple>`. */
+    input: '#upload-file-button',
+    /** Extensions the input accepts that are useful to us. */
+    safeReportExtension: '.txt',
+    /** Container of the pending attachments in the composer. */
+    list: 'div.fx-AttachmentList',
+    /** One pending attachment. Its `aria-label` is the file name. */
+    chip: 'div.fx-Attachment',
+    /** `aria-label` of the chip's remove button, with the file name appended. */
+    removeLabelPrefix: 'Remove attachment ',
+    /**
+     * Wait for this before clicking Send: the chip's DOM id starts with `SPO_` only once
+     * the file has finished uploading to SharePoint/OneDrive.
+     */
+    uploadedIdPrefix: 'SPO_',
+};
+/**
+ * Accessible names used with getByRole / getByLabel.
+ * The UI is English-only in this tenant; if a localized tenant is targeted these
+ * must be moved into a locale map.
+ */
+export const Label = {
+    /** The composer. It is a contenteditable SPAN, not a textarea. */
+    composer: 'Message Copilot',
+    send: 'Send',
+    /** Visible only while the answer is streaming. Its absence = generation finished. */
+    stopGenerating: 'Stop generating',
+    copyResponse: 'Copy Response',
+    /** Copy button inside a code block; yields the full code, ignoring virtualization. */
+    copyCode: 'Copy code',
+    /** Expands a long code block. */
+    showMoreLines: 'Show more lines',
+    newChat: 'New chat',
+    modelSelector: 'Model Selector',
+};
+/**
+ * The model picker.
+ *
+ * The button was captured live: `button#gptModeSwitcher[aria-label="Model Selector"]`, showing
+ * `Auto`. What its popup contains was **not** captured, and it is the one thing here that
+ * Microsoft changes without warning: models come and go, and a tenant sees a different list
+ * from the next tenant. So nothing in this project hard-codes a list of models. The names are
+ * read from the open popup at the moment the user asks for them, and what is offered in the UI
+ * is whatever the chat itself offered.
+ *
+ * Because the popup's markup is unknown, the reader is deliberately role-based and tries
+ * several shapes rather than one selector. Anything matched inside the popup counts; the
+ * button's own text is the current selection.
+ */
+export const Model = {
+    /** The picker button. The id has been stable; the aria-label is the fallback. */
+    button: 'button#gptModeSwitcher',
+    buttonLabel: 'Model Selector',
+    /** Containers a Fluent popup can use. The first visible one after the click wins. */
+    popupSelectors: ['[role="menu"]', '[role="listbox"]', '[role="dialog"]', '[role="group"]'],
+    /**
+     * Roles an option can carry. All of them are read, not just the first that matches:
+     * the menu mixes `menuitemradio` for the choices with plain `menuitem` for the groups
+     * that open a submenu, so stopping at the first role hides every grouped model.
+     */
+    optionRoles: ['menuitemradio', 'menuitemcheckbox', 'option', 'radio', 'menuitem'],
+    /** Attributes that mark the option currently in force. */
+    selectedAttributes: ['aria-checked', 'aria-selected', 'aria-pressed'],
+    /**
+     * A row that opens a submenu instead of choosing anything. Seen live as `GPT / OpenAI`
+     * with a chevron, holding `GPT 5.6 Think deeper` and `GPT 5.6 Quick response`. A tenant
+     * with other vendors enabled gets one such group per vendor, which is where the models
+     * this project is asked to pick actually live.
+     */
+    submenuAttributes: ['aria-haspopup', 'aria-expanded'],
+};
+/** CSS selectors for things that have neither a test id nor an accessible name. */
+export const Css = {
+    /** The composer element. Its DOM id has been stable so far. */
+    composer: '#m365-chat-editor-target-element',
+    /**
+     * The composer's own wrapper, and the reason every Send lookup goes through it.
+     *
+     * "The button called Send" is not unique on this page. The Office feedback panel
+     * (`data-testid="obf-…"`) has one too, and when it opens over the chat a page-wide lookup
+     * matches two elements and Playwright refuses to guess — which is a run ending on a strict
+     * mode violation because Microsoft asked the operator what they thought of Copilot.
+     *
+     * Note the spelling: this one is `data-test-id`, with hyphens, unlike the `data-testid`
+     * values above. Both spellings exist in this UI.
+     */
+    composerWrapper: '[data-test-id="chat-input-wrapper"]',
+    /**
+     * The shape of the real Send button, used when the wrapper cannot be found.
+     *
+     * The composer's Send is its form's submit control; the feedback panel's is an ordinary
+     * button. So this tells them apart without knowing either one's container.
+     */
+    composerSendSubmit: 'button[type="submit"][aria-label="Send"]',
+    /**
+     * Anything belonging to the Office feedback panel. Never clicked, only detected: its
+     * buttons submit an opinion on the operator's own account, and this program has none.
+     */
+    feedbackPanel: '[data-testid^="obf-"]',
+    /**
+     * A rendered code block. Beware: it carries `scriptor-codeblock-virtualized`
+     * and renders line numbers as separate text nodes, so `innerText` is
+     * "PowerShell\n1\nline one\n2\nline two". Never parse it directly - use the
+     * "Copy code" button or the message-level "Copy Response" button instead.
+     */
+    codeBlock: '.scriptor-component-code-block',
+    codeBlockVirtualized: '.scriptor-codeblock-virtualized',
+    /**
+     * A file Copilot generated for download. It is a plain anchor with a blob href,
+     * a `download` attribute and `target="_blank"`, which is why nothing useful shows
+     * on hover. `aria-label` and `download` both carry the file name.
+     *
+     * Read only to name what was ignored: the runner never clicks it, and the browser is
+     * opened with downloads refused.
+     */
+    downloadLink: 'a[download]',
+    downloadLinkBlob: 'a[href^="blob:"]',
+};
+/** Signals the transport uses to decide what state the page is in. */
+export const Signal = {
+    /** Sign-in redirect target. */
+    loginHost: 'login.microsoftonline.com',
+    /** Generation is running while a button with this label exists anywhere. */
+    streamingButtonLabel: Label.stopGenerating,
+    /**
+     * Generation has finished when the newest answer exposes its copy button.
+     *
+     * Two traps here, both found by checking against the live DOM rather than assuming:
+     *
+     * 1. `[data-testid="loading-message"]` is NOT a busy flag. It stays in the DOM after
+     *    streaming ends.
+     * 2. The copy button is **not** inside `lastChatMessage`. `lastChatMessage` is the answer
+     *    body (its DOM id is `response-id_...`); the copy button lives in a toolbar that is a
+     *    sibling of it. Both sit inside `copilot-message-div`, which is therefore the anchor
+     *    for anything that has to see the whole answer.
+     *
+     * There is no CSS for "the last element with this test id" across separate containers, so
+     * the check is done in JS: take the last `copilot-message-div` and look inside it.
+     */
+    answerWrapper: `[data-testid="${TestId.assistantMessage}"]`,
+    copyButtonInAnswer: `[data-testid="${TestId.copyResponse}"]`,
+};
+/**
+ * Things that stop the chat from working and that only a human can clear.
+ *
+ * The bot **detects** these and waits. It never clicks the verification checkbox and never
+ * tries to get past a challenge: that is the human's job, by design and on purpose. The
+ * value here is that the run pauses with a clear message instead of timing out with a
+ * confusing one.
+ */
+export const Blocker = {
+    /** Text seen on the human-verification dialog. */
+    verificationText: ['Verification required', 'Verify you are human'],
+    /** Transient failure banner; a reload usually clears it. */
+    errorBannerText: ["Your request couldn't be completed", 'Refresh to try again'],
+    refreshLabel: 'Refresh',
+    /** Challenge widgets are iframed from these hosts. */
+    challengeFrameHosts: ['challenges.cloudflare.com', 'hcaptcha.com', 'recaptcha.net', 'google.com/recaptcha'],
+};
+/**
+ * Telling the work Copilot apart from the consumer one.
+ *
+ * `m365.cloud.microsoft` redirects to the consumer Copilot when the profile is not signed in
+ * with a work or school account. Both surfaces have a message box, so "a textbox is visible"
+ * is not proof of being in the right place. The consumer surface also runs bot protection,
+ * which the work surface does not, so landing there looks exactly like being detected as a
+ * bot when it is really a sign-in problem.
+ */
+export const Surface = {
+    workHost: 'm365.cloud.microsoft',
+    /** Only the work surface has this composer id and these test ids. */
+    workMarkers: ['#m365-chat-editor-target-element'],
+    consumerHosts: ['copilot.microsoft.com', 'www.bing.com', 'bing.com'],
+    /** Chips that only the consumer surface shows. */
+    consumerMarkers: ['Shop', 'Play'],
+};
+/** Chat URL. Microsoft is consolidating this to copilot.cloud.microsoft. */
+export const Url = {
+    chat: 'https://m365.cloud.microsoft/chat',
+    /** "New chat" is an anchor, so a plain navigation is equivalent to clicking it. */
+    newChat: 'https://m365.cloud.microsoft/chat?es=SSR',
+    /** Every conversation has a stable address: /chat/conversation/<uuid>. */
+    conversation: (id) => `https://m365.cloud.microsoft/chat/conversation/${id}?es=SSR`,
+    /** Full chat list, used as the last resort when looking a chat up by name. */
+    allChats: 'https://m365.cloud.microsoft/chat/all?es=SSR',
+};
+/**
+ * Naming a chat, so the bot can find its own conversation again after a re-login.
+ *
+ * Path: the sidebar entry's "More" menu -> "Rename" -> a dialog with a text input and a
+ * Save button. Enter does **not** submit the dialog; Save must be clicked.
+ *
+ * The name is capped at 50 characters by the UI, which shows the inline error
+ * "Your Copilot chat name can't be longer than 50 characters".
+ */
+export const Rename = {
+    /** Per-chat overflow button in the sidebar. There is one per chat, so scope it to the row. */
+    moreButtonLabel: 'More',
+    menuItem: 'Rename',
+    /** The dialog's text input. */
+    input: '#new-session-name',
+    inputLabel: 'Chat name',
+    /** The dialog's confirm button. Text, not an aria-label. */
+    saveText: 'Save',
+    cancelText: 'Cancel',
+    maxLength: 50,
+};
+/**
+ * Sidebar chat rows. `aria-label` carries the chat's current name, `href` carries its id,
+ * so a row identifies a conversation both ways.
+ *
+ * `document.title` is NOT reliable here: after a rename it still showed the old title.
+ */
+export const Sidebar = {
+    conversationLink: 'a[href*="/chat/conversation/"]',
+};

package/dist/src/transport/profileLock.js

@@ -0,0 +1,102 @@
+/**
+ * Guards the browser profile directory.
+ *
+ * Chromium profiles are single-writer. If any Edge process already has this profile open,
+ * a second launch does not get its own browser: it hands the request to the running one and
+ * exits, which Playwright then reports as
+ *
+ *   Target page, context or browser has been closed
+ *
+ * a message that says nothing about the actual cause. That failure has already been seen in
+ * practice, with leftover `msedge.exe` processes still holding the profile from an earlier
+ * run. So the profile is checked and locked before the browser is launched, and the error
+ * says what to do.
+ */
+import { writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { winPsEnv } from '../exec/winps.js';
+/**
+ * Edge processes that currently have this profile open.
+ *
+ * Windows only, via CIM. A failure to query is reported as "unknown" rather than "none", so
+ * a broken check never silently claims the profile is free.
+ */
+export function findEdgeUsingProfile(profileDir) {
+    const script = `Get-CimInstance Win32_Process -Filter "Name='msedge.exe'" | ` +
+        `Where-Object { $_.CommandLine -like '*${profileDir.replace(/\\/g, '\\').replace(/'/g, "''")}*' } | ` +
+        `Select-Object ProcessId, CommandLine | ConvertTo-Json -Compress`;
+    const res = spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+        env: winPsEnv(),
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 15_000,
+    });
+    if (res.status !== 0 || typeof res.stdout !== 'string')
+        return 'unknown';
+    const text = res.stdout.trim();
+    if (text.length === 0)
+        return [];
+    try {
+        const parsed = JSON.parse(text);
+        const list = Array.isArray(parsed) ? parsed : [parsed];
+        return list.map((p) => ({ pid: p.ProcessId, commandLine: p.CommandLine ?? '' }));
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Takes the lock, or explains why it cannot.
+ *
+ * A stale lock file (its process is gone) is taken over rather than treated as fatal,
+ * because a crashed run would otherwise leave the profile unusable until someone deleted a
+ * file they have never heard of.
+ */
+export function acquireProfileLock(profileDir) {
+    mkdirSync(profileDir, { recursive: true });
+    const lockPath = join(profileDir, '.cop-lock.json');
+    if (existsSync(lockPath)) {
+        try {
+            const held = JSON.parse(readFileSync(lockPath, 'utf8'));
+            let alive = false;
+            try {
+                process.kill(held.pid, 0);
+                alive = true;
+            }
+            catch {
+                alive = false;
+            }
+            if (alive && held.pid !== process.pid) {
+                throw new Error(`The browser profile at ${profileDir} is already in use by copilot-operator ` +
+                    `(process ${held.pid}, started ${held.startedAt}). Wait for that run to finish, or stop it.`);
+            }
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.startsWith('The browser profile'))
+                throw e;
+            // An unreadable lock file is stale by definition; take it over.
+        }
+    }
+    const users = findEdgeUsingProfile(profileDir);
+    if (Array.isArray(users) && users.length > 0) {
+        const pids = users.map((u) => u.pid).join(', ');
+        throw new Error(`Microsoft Edge is already running with this profile (process ${pids}), so a new ` +
+            `browser cannot be launched and Playwright would fail with "Target page, context or ` +
+            `browser has been closed".\n` +
+            `Close that Edge window, or end those processes:\n` +
+            `  Stop-Process -Id ${users.map((u) => u.pid).join(',')} -Force\n` +
+            `Profile: ${profileDir}`);
+    }
+    writeFileSync(lockPath, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }), 'utf8');
+    return {
+        release: () => {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                /* already gone */
+            }
+        },
+    };
+}

package/dist/src/util/pacing.js

@@ -0,0 +1,89 @@
+/**
+ * Pacing: the small amount of deliberate waiting the bot actually needs.
+ *
+ * An earlier version drew delays from a log-normal distribution and occasionally took a
+ * long pause, to make the traffic look less mechanical. That was dropped: it changed
+ * nothing measurable. The browser still reports `navigator.webdriver === true`, and with
+ * the default limits the hourly cap never binds, so the randomness only added a few
+ * minutes per run.
+ *
+ * What is left is the part that does work:
+ *
+ * - `settle()`   a short fixed pause after an action, as a belt on top of the real
+ *                condition waits in the transport (Stop-generating gone, SPO_ prefix on the
+ *                attachment chip, Send button present). Those waits are the actual fix for
+ *                flaky clicks; this is only a cushion.
+ * - `throttleSend()` a hard cap on messages per hour, which is the one thing that protects
+ *                against service-side throttling on long runs.
+ * - `backoffFor()`   exponential backoff with jitter, so a failing step cannot turn into a
+ *                tight retry loop.
+ */
+export const DEFAULT_PACING = {
+    enabled: true,
+    settleMs: 1_000,
+    maxMessagesPerHour: 60,
+};
+/** Small, fast, seedable PRNG, used only for backoff jitter. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export class Pacer {
+    rnd;
+    profile;
+    /** Timestamps of sent messages, for the hourly cap. */
+    sentAt = [];
+    seed;
+    constructor(profile = {}) {
+        this.profile = { ...DEFAULT_PACING, ...profile };
+        this.seed = this.profile.seed ?? ((Date.now() ^ (Math.random() * 0xffffffff)) >>> 0);
+        this.rnd = mulberry32(this.seed);
+    }
+    /** Short fixed pause after an action. Zero when pacing is disabled. */
+    async settle(signal) {
+        const ms = this.profile.enabled ? this.profile.settleMs : 0;
+        if (ms > 0)
+            await sleep(ms, signal);
+        return ms;
+    }
+    /**
+     * Wait however long is needed to stay under the hourly message cap, then record that a
+     * message is being sent. Call immediately before clicking Send. Returns how long it
+     * waited, so the caller can log a visible "throttled for N s".
+     */
+    async throttleSend(signal) {
+        const hour = 3_600_000;
+        const now = Date.now();
+        while (this.sentAt.length && now - this.sentAt[0] > hour)
+            this.sentAt.shift();
+        let waited = 0;
+        if (this.sentAt.length >= this.profile.maxMessagesPerHour) {
+            waited = this.sentAt[0] + hour - now;
+            if (waited > 0)
+                await sleep(waited, signal);
+        }
+        this.sentAt.push(Date.now());
+        return Math.max(waited, 0);
+    }
+    /** Exponential backoff with jitter, for retries after a failure. */
+    backoffFor(attempt, baseMs = 2_000, capMs = 60_000) {
+        const exp = Math.min(baseMs * 2 ** attempt, capMs);
+        return Math.round(exp * (0.5 + this.rnd() * 0.5));
+    }
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(new Error('aborted'));
+        const t = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(t);
+            reject(new Error('aborted'));
+        }, { once: true });
+    });
+}

package/dist/src/vcs/commitHygiene.js

@@ -0,0 +1,102 @@
+/**
+ * What a commit made by the runner should not carry.
+ *
+ * `commitOnFinish` commits everything the task left in the working tree, and that is the right
+ * default: the runner cannot know which of the model's files are the work. But it can know
+ * what tool output looks like. A nine-task plan wrote its `.gitignore` exactly as told, nine
+ * entries, and the second web task still committed `web/tsconfig.tsbuildinfo` — the build had
+ * turned on `incremental` in a file the plan had dictated the contents of, the reviewer saw the
+ * path in its list of changed files and said nothing, and the plan's own audit looked for
+ * `node_modules`, `.next` and `dist` and found none. Nobody was wrong; nobody was looking for
+ * that.
+ *
+ * So the runner looks, once. A file that is installed, built, cached or logged rather than
+ * written, or one that holds secrets, is pointed out to the model before the task can end —
+ * through the same channel as the operator's checks — with the instruction to ignore it or to
+ * say why it belongs. Pointed out once: a second `done` with the file still there commits it
+ * and records it as suspicious on the task, where a person will see it. The alternative,
+ * refusing to commit, leaves the tree dirty and the next task refusing to start over it.
+ */
+/** Directory names that are installed, built or cached rather than written. */
+const GENERATED_DIRS = {
+    node_modules: 'installed by the package manager',
+    dist: 'build output',
+    build: 'build output',
+    out: 'build output',
+    '.next': "Next.js's build output",
+    '.nuxt': "Nuxt's build output",
+    '.svelte-kit': "SvelteKit's build output",
+    coverage: 'test coverage output',
+    '.turbo': 'a build cache',
+    '.cache': 'a cache',
+    '.parcel-cache': 'a build cache',
+    __pycache__: 'compiled Python',
+    '.pytest_cache': 'a test cache',
+    '.mypy_cache': 'a type-checker cache',
+    '.venv': 'a Python virtual environment',
+    venv: 'a Python virtual environment',
+};
+/** File names, or endings, that a tool writes and nobody reads. */
+const GENERATED_FILES = [
+    [(n) => n.endsWith('.tsbuildinfo'), "TypeScript's incremental build state"],
+    [(n) => n.endsWith('.log'), 'a log file'],
+    [(n) => n === '.DS_Store' || n === 'Thumbs.db' || n === 'desktop.ini', "the operating system's folder metadata"],
+    [(n) => n.endsWith('.pyc'), 'compiled Python'],
+];
+/** `.env` and its variants, except the ones that exist to be committed. */
+function isSecretsFile(name) {
+    if (!name.startsWith('.env'))
+        return false;
+    const rest = name.slice('.env'.length);
+    if (rest === '')
+        return true;
+    if (!rest.startsWith('.'))
+        return false;
+    const suffix = rest.slice(1).toLowerCase();
+    return suffix !== 'example' && suffix !== 'sample' && suffix !== 'template';
+}
+/**
+ * Why a path should not be committed, or null when it looks like work.
+ *
+ * `key` is what to report: for a file, the file; for anything under a generated folder, the
+ * folder — `api/node_modules/` once, not fifteen thousand lines under it.
+ */
+export function looksGenerated(path) {
+    const parts = path.replace(/\\/g, '/').split('/').filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    for (const [i, dir] of parts.slice(0, -1).entries()) {
+        const reason = GENERATED_DIRS[dir];
+        if (reason)
+            return { reason: `a \`${dir}/\` folder, ${reason}`, key: `${parts.slice(0, i + 1).join('/')}/` };
+    }
+    const last = parts[parts.length - 1];
+    // A folder `git status` lists as one entry, with a trailing slash.
+    if (/[\\/]$/.test(path) && GENERATED_DIRS[last])
+        return { reason: `a \`${last}/\` folder, ${GENERATED_DIRS[last]}`, key: `${parts.join('/')}/` };
+    const file = parts.join('/');
+    for (const [test, reason] of GENERATED_FILES)
+        if (test(last))
+            return { reason, key: file };
+    if (isSecretsFile(last))
+        return { reason: 'a secrets file', key: file };
+    return null;
+}
+/** The paths, out of a list, that should not be committed — one entry per file or folder. */
+export function findSuspicious(paths) {
+    const seen = new Map();
+    for (const path of paths) {
+        const hit = looksGenerated(path);
+        if (hit && !seen.has(hit.key))
+            seen.set(hit.key, { path: hit.key, reason: hit.reason });
+    }
+    return [...seen.values()];
+}
+/** What the model is told, once, before the commit. */
+export function suspiciousDetail(found) {
+    const list = found.map((s) => `${s.path} (${s.reason})`).join('; ');
+    return (`${found.length} file(s) that look like tool output or secrets are in the working tree and would be committed ` +
+        `with this task: ${list}. Add them to .gitignore — they are installed, built or generated, not written — and ` +
+        'take them out of the index if git already tracks them. If one of them truly belongs in the repository, leave ' +
+        'it and say why in your summary: it will be committed and marked.');
+}