copilot-operator 0.1.0

package/dist/src/exec/policy.js

@@ -0,0 +1,201 @@
+import { effectiveShell } from './shells.js';
+import { dangerousRefusal } from './dangerous.js';
+import { findShellExecuteTrap } from './shellExecuteTrap.js';
+import { inlineCodeRefusal, programRefusal } from './programs.js';
+import { unattendedIsolationRefusal } from './isolation.js';
+import { confinementRefusal } from './confinement.js';
+import { botSelfRefusal, networkFetchReason, networkFetchRefusal } from './network.js';
+import { scriptFileRefusal } from './scriptFiles.js';
+export function describeStep(step) {
+    // The shell it will really be read by, not the one this file used to assume: a line in the
+    // log that names an interpreter the machine has not got explains the wrong failure.
+    return `[${effectiveShell(step.shell)}] ${step.cmd}`;
+}
+/** Returns the first deny pattern that matches, or null. */
+export function matchDenyPattern(text, patterns) {
+    for (const p of patterns) {
+        try {
+            if (new RegExp(p, 'i').test(text))
+                return p;
+        }
+        catch {
+            // An invalid pattern in the config must not silently disable the whole deny list.
+            if (text.toLowerCase().includes(p.toLowerCase()))
+                return p;
+        }
+    }
+    return null;
+}
+/**
+ * A step that reaches into the repository's own machinery: a path inside `.git`, or a git setting
+ * written to stay. Built in, like `dangerous.ts`, because the operator's deny list is editable and
+ * this is not a matter of taste.
+ *
+ * Found on 2026-09-27: the runner's own git — the branch before a task, `add` and `commit` after
+ * it, `status` for the commit-clean check — runs whatever hooks, filters and fsmonitor the
+ * repository's config names. A step could write `.git\hooks\post-checkout`, or `git config
+ * core.fsmonitor <program>`, and the *runner* would then execute it: no approval, no allowlist, no
+ * step log. The runner now starts git with those switched off (`src/vcs/git.ts`); this stops the
+ * step from setting them up in the first place. Reading history through git is unaffected — the
+ * contract already tells the chat to use git commands, never the folder.
+ */
+export function repositoryInternalsRefusal(command) {
+    const intoGitDir = /(^|[\s'"=(\\/,;])\.git[\\/]/i.test(command);
+    const setting = /\bgit\s+(?:-C\s+\S+\s+)?config\s+(?:(?:--(?:local|global|system|worktree)|--file\s+\S+)\s+)?(?:(?:set|unset)\s+)?[A-Za-z][\w.-]*\s+[^\s|;-]/i.test(command);
+    // `git -c key=value <command>` sets the key for that one command — and some keys name a program
+    // git then starts (hooks, fsmonitor, the pager, the editor, credential helpers, filters, diff and
+    // merge drivers, aliases), which the allowlist never sees. Those keys are refused inline as well.
+    const inline = /\bgit\b[^|;\n]*?\s-c\s*["']?(?:core\.(?:hooksPath|fsmonitor|sshCommand|gitProxy|editor|pager|askPass|alternateRefsCommand|attributesFile)|credential\.|gpg\.|diff\.[^\s=]*\.(?:command|textconv)|difftool\.|mergetool\.|merge\.[^\s=]*\.driver|filter\.|alias\.|sequence\.editor|uploadpack\.|receive\.|http\.proxy|url\.)/i.test(command);
+    if (!intoGitDir && !setting && !inline)
+        return null;
+    return ("refused: this reaches into the repository's own machinery (the .git folder, or a git setting written to stay). " +
+        'The runner owns the repository and runs git itself; hooks and settings placed there would run as the runner. ' +
+        'Read history with git commands (git log, git show, git diff) and leave .git alone.');
+}
+/**
+ * Why a command line must not run, or null. The one gate for a step's command and for a
+ * check's command alike: the deny list, then the forms that are not dangerous but cannot work
+ * (see `shellExecuteTrap.ts`) — refused for the same reason a check that would hang is refused,
+ * because the alternative is an iteration spent on a symptom.
+ */
+export function commandRefusal(command, shell, denyPatterns, allowedPrograms = [], env = process.env, 
+/**
+ * The project folders and where this command runs. Absent only where there is no project to
+ * speak of — a check run by hand, a test of some other rule. Every path that runs a command for a
+ * task passes it: the implementer's steps and checks, and the reviewer's steps and derived checks.
+ */
+confinement) {
+    // The built-in refusals first, because the operator's list can add to them and must not be
+    // able to stand in for them: a config written before they existed, or edited since, still gets
+    // them. See `dangerous.ts` for what is on the list and why each one is.
+    const technique = dangerousRefusal(command);
+    if (technique)
+        return technique;
+    // Before the operator's list: no configuration makes it right for a step to drive the bot.
+    const self = botSelfRefusal(command);
+    if (self)
+        return self;
+    const internals = repositoryInternalsRefusal(command);
+    if (internals)
+        return internals;
+    const hit = matchDenyPattern(command, denyPatterns);
+    if (hit)
+        return `matches deny pattern /${hit}/`;
+    // Where it reaches, before which program it is: a binary named by a path outside the project is
+    // better refused for being outside than for not being on a list, and a cmdlet — which the
+    // allowlist never sees — is only caught here. See `confinement.ts`.
+    if (confinement) {
+        const reach = confinementRefusal(command, confinement);
+        if (reach)
+            return reach;
+    }
+    // The allowlist after the known-bad floor and the operator's deny list, so their precise
+    // messages win, and this catches the long tail neither of them was ever going to enumerate: a
+    // program that is simply not part of this project's toolchain. See `programs.ts`.
+    const offlist = programRefusal(command, allowedPrograms);
+    if (offlist)
+        return offlist;
+    const trap = findShellExecuteTrap(command, shell, env);
+    if (trap)
+        return trap;
+    /*
+     * The scripts this line runs, read from disk and put through the same gate as the line. Only
+     * where the command's folder is known: that is every path that runs a command for a task.
+     */
+    if (confinement) {
+        return scriptFileRefusal(command, confinement.cwd, (text) => dangerousRefusal(text) ??
+            botSelfRefusal(text) ??
+            repositoryInternalsRefusal(text) ??
+            (matchDenyPattern(text, denyPatterns) ? `matches deny pattern /${matchDenyPattern(text, denyPatterns)}/` : null) ??
+            confinementRefusal(text, confinement) ??
+            programRefusal(text, allowedPrograms));
+    }
+    return null;
+}
+/**
+ * The gate for a check's command — the task's own checks and the reviewer's — which runs with
+ * nobody asked. A download in one is therefore refused rather than held, and the scripts it runs
+ * are read like a step's. One function, so the two callers cannot drift apart again (they had: the
+ * reviewer's checks refused downloads, the plan's did not).
+ */
+export function checkCommandRefusal(command, shell, cfg, confinement, env = process.env) {
+    const refusal = commandRefusal(command, shell, cfg.denyPatterns, cfg.allowedPrograms, env, confinement);
+    if (refusal)
+        return refusal;
+    const network = networkFetchReason(command, confinement.cwd) ?? scriptNetworkReason(command, confinement.cwd);
+    return network ? networkFetchRefusal(network) : null;
+}
+/** A fetch inside a script the line runs — held or refused exactly as one on the line would be. */
+export function scriptNetworkReason(command, cwd) {
+    let found = null;
+    scriptFileRefusal(command, cwd, (text) => {
+        found = networkFetchReason(text, cwd);
+        return null;
+    });
+    return found;
+}
+/**
+ * Why an unattended run may not begin at all, or null.
+ *
+ * Both conditions are about the same thing: an unattended run has given up the person who made
+ * every other rule survivable, so the two things that stand in for them have to be there. Nowhere
+ * to run and nobody watching is refused outright; an empty allowlist and nobody watching means
+ * nothing at all limits a step.
+ *
+ * Asked in two places on purpose. At the entrance — `start`, `startBatch`, the CLI, and the button
+ * that turns a running session unattended — so the operator is told once, before anything begins,
+ * what to set and where. And again in `staticCheck`, because the entrance is a courtesy and the
+ * step gate is the rule: a path that reached execution another way still finds it there.
+ *
+ * It is deliberately *not* a warning. The first version of this refused each step as it arrived,
+ * which technically held the line and in practice turned the ordinary "Run sessions" button into a
+ * run where every step came back refused — a gate that breaks the working bot is a gate that gets
+ * switched off, and the fix was to make the condition reachable rather than to soften it.
+ */
+export function unattendedPrecondition(cfg) {
+    if (cfg.mode !== 'unattended')
+        return null;
+    if (cfg.lockedToConfirm) {
+        return 'refused: this machine\'s policy.lock.json forbids unattended runs. Run this task step by step.';
+    }
+    const unisolated = unattendedIsolationRefusal(cfg.mode, cfg.isolation ?? 'none');
+    if (unisolated)
+        return unisolated;
+    if (!cfg.allowedPrograms || cfg.allowedPrograms.length === 0) {
+        return ('refused: an unattended run requires execution.allowedPrograms to name the programs this project ' +
+            'may start. With the allowlist empty and nobody watching, nothing limits what a step can run. ' +
+            'Fill in the allowlist, or run this task step by step.');
+    }
+    return null;
+}
+/**
+ * Applies the automatic rules. Returns null when the step is acceptable so far, or a
+ * decision when it is refused without asking anyone.
+ */
+export function staticCheck(step, cfg, env = process.env, confinement) {
+    // Screened against the shell that will actually read it: the traps in `shellExecuteTrap.ts`
+    // are shell-specific, so screening for one interpreter and running in another finds nothing.
+    const reason = commandRefusal(step.cmd, effectiveShell(step.shell), cfg.denyPatterns, cfg.allowedPrograms, env, confinement);
+    if (reason)
+        return { action: 'skip', reason };
+    /*
+     * Autonomy is graded: an unattended run carries strictly more restrictions than a watched one,
+     * because the thing that makes a watched run safe — a person reading each line — is exactly what
+     * an unattended run has removed.
+     *
+     * The precondition is the same one the entrances ask before anything starts; it is asked again
+     * here because the entrance is a courtesy and this is the path nothing goes round. The second
+     * rule is about an allowlisted interpreter used to evaluate a string, or a shell wrapped in a
+     * shell, which escapes the allowlist by construction: watched, a person can judge it; unwatched,
+     * it makes the list meaningless.
+     */
+    if (cfg.mode === 'unattended') {
+        const precondition = unattendedPrecondition(cfg);
+        if (precondition)
+            return { action: 'skip', reason: precondition };
+        const inline = inlineCodeRefusal(step.cmd);
+        if (inline)
+            return { action: 'skip', reason: inline };
+    }
+    return null;
+}

package/dist/src/exec/policyManifest.js

@@ -0,0 +1,84 @@
+/**
+ * What was allowed, written down once per task, next to what was run.
+ *
+ * This exists because of a question nobody could answer quickly. A security team saw
+ * `certutil.exe` decoding a blob on an operator's workstation with this runner in the process
+ * tree, and asked the two reasonable things: what is this tool permitted to do, and was this
+ * deliberate. The run folder held every command and every exit code — excellent evidence of what
+ * happened — and nothing at all about what the rules had been at the time. So the answer had to be
+ * reconstructed from a config file that had been edited since, which is not an answer.
+ *
+ * A manifest fixes that by recording the policy beside the run it governed: the mode, the
+ * allowlist, whether downloaded files could execute, how many deny patterns and built-in refusals
+ * were in force, and who the process was running as. Lists are recorded by count and digest as
+ * well as in full, so "was this the same policy as last Tuesday" is one comparison rather than a
+ * reading exercise, and a quietly edited `dangerous.ts` shows up as a changed digest.
+ *
+ * What it deliberately does not claim: that the run was isolated. Whether this process sits in a
+ * sandbox or a separate low-privilege account is the operator's assertion to make, not something
+ * software can honestly detect from the inside, so the manifest records the account it sees and
+ * says plainly that isolation is not determined here. A manifest that overstated its own evidence
+ * would be worse than none, because somebody would rely on it.
+ */
+import { createHash } from 'node:crypto';
+import { DANGEROUS_TECHNIQUES } from './dangerous.js';
+import { describeIsolation } from './isolation.js';
+/** A short, stable digest of a list, order-independent so a reordered config is not a changed one. */
+export function digestOf(values) {
+    // JSON rather than a separator character: unambiguous for any entry, and free of the control
+    // byte an earlier version joined on, which made this file read as binary to grep and every
+    // other tool that decides by looking for one.
+    const canonical = JSON.stringify([...values].map((v) => v.trim()).filter(Boolean).sort());
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 12);
+}
+export const NETWORK_FETCH = "a command that fetches from the network (Invoke-WebRequest, Invoke-RestMethod, curl, wget, Start-BitsTransfer, .NET web clients, ftp/scp) is held for the operator in every mode; with nobody to ask it is refused. Requests to localhost and the project's package managers are not held";
+export function collectPolicyManifest(input, env = process.env) {
+    const names = DANGEROUS_TECHNIQUES.map((t) => t.name);
+    return {
+        collectedAt: new Date().toISOString(),
+        mode: input.mode,
+        allowlist: {
+            // An empty list is the gate turned off, and that is the fact worth recording plainly: it is
+            // the difference between "only these programs" and "any program at all".
+            enforced: input.allowedPrograms.length > 0,
+            count: input.allowedPrograms.length,
+            digest: digestOf(input.allowedPrograms),
+            programs: [...input.allowedPrograms],
+        },
+        chatFiles: 'the chat cannot supply a file: this runner has no file step and executes nothing it did not receive as a command',
+        networkFetch: NETWORK_FETCH,
+        denyPatterns: { count: input.denyPatterns.length, digest: digestOf(input.denyPatterns) },
+        builtIn: { count: names.length, digest: digestOf(names), names },
+        lock: input.lock ?? { applied: false, changes: [] },
+        account: {
+            user: env.USERNAME ?? '(unknown)',
+            domain: env.USERDOMAIN ?? '(unknown)',
+            computer: env.COMPUTERNAME ?? '(unknown)',
+        },
+        isolation: input.isolation,
+        cwd: input.cwd,
+        confinedTo: [...(input.confinedTo ?? [])],
+    };
+}
+/** The manifest as a block of `name : value` lines, for the task log, beside the environment. */
+export function describePolicyManifest(m) {
+    return [
+        `mode        : ${m.mode}${m.mode === 'unattended' ? ' (no person saw the steps as they ran)' : ' (a person approved each step)'}`,
+        `allowlist   : ${m.allowlist.enforced ? `${m.allowlist.count} programs, digest ${m.allowlist.digest}` : 'NOT ENFORCED — any program could be started'}`,
+        `chat files : ${m.chatFiles}`,
+        `downloads   : ${m.networkFetch}`,
+        `deny list   : ${m.denyPatterns.count} patterns, digest ${m.denyPatterns.digest}`,
+        `built-in    : ${m.builtIn.count} refused techniques, digest ${m.builtIn.digest} (cannot be switched off)`,
+        `lock        : ${m.lock.applied
+            ? m.lock.changes.length
+                ? `policy.lock.json in force — ${m.lock.changes.join('; ')}`
+                : 'policy.lock.json in force — nothing to tighten'
+            : 'none — this machine has no administrator policy file'}`,
+        `account     : ${m.account.domain}\\${m.account.user} on ${m.account.computer}`,
+        'isolation   :',
+        describeIsolation(m.isolation).split('\n').map((l) => `  ${l}`).join('\n'),
+        `cwd         : ${m.cwd}`,
+        `confined to : ${m.confinedTo.length ? m.confinedTo.join(', ') : 'NOTHING — commands were not held to a project'}`,
+        `collected   : ${m.collectedAt}`,
+    ].join('\n');
+}

package/dist/src/exec/processes.js

@@ -0,0 +1,329 @@
+/**
+ * What a task or a review leaves running, found and stopped by the runner — and how anything the
+ * runner stops is stopped.
+ *
+ * "Anything you start, you stop" is in both contracts, and it is advice: in one run the reviewer
+ * left its own `next start` listening on 4310 and then failed the work for it, and every plan
+ * written so far has carried its own checks for ports and node processes because nothing else
+ * would. The runner can own this. It notes when a task and each review began; afterwards, what was
+ * created since *and was started by the bot* is stopped and written on the task with where it came
+ * from. The plan's own checks still run first — a server the implementer forgot goes back to the
+ * chat as a failed check — and this is the net under them.
+ *
+ * **Whose processes** (2026-09-27, at the operator's request). The first version stopped every new
+ * process whose command line named the project folder. That is a description of a place, not of an
+ * owner: a server the operator started by hand in the same folder while a run was going matched it
+ * exactly, and was killed. Now a process is the bot's only if it descends from a step the bot itself
+ * started — every shell `runStep` spawns is recorded in a `ProcessTracker`, with when it started and
+ * ended, and a process belongs to the run if its chain of parents reaches one of them. Windows does
+ * not re-parent an orphan, so a server left behind by `Start-Process` still names the step's shell
+ * as its parent after that shell has exited; the times are what stop a *reused* process id from
+ * passing for it. What is new in the folder but not provably the bot's is **reported and left
+ * running**. The honest limit: a program started through a wrapper that exits at once (`cmd /c
+ * start …`) leaves a process whose parent is gone and was never recorded; it is reported, not
+ * stopped.
+ *
+ * **How it looks from the outside.** This runs on company laptops whose security tooling watches
+ * every process the bot starts, so what the bot itself does here is kept to the plainest forms:
+ *
+ *   - The process table is read only for processes *created since* the task or step began (a WMI
+ *     filter on `CreationDate`), not the whole machine with every command line, and the listening
+ *     ports only for the processes found. Reading everyone's command lines several times a task is
+ *     what discovery tooling does, and the bot has no need to know about anything older than its
+ *     own work.
+ *   - Stopping is `taskkill /T` first — the polite form, which asks a windowed program to close — a
+ *     grace period, and `taskkill /T /F` only for what is still there. A day's version of this file
+ *     sent a real Ctrl+C by compiling kernel32 calls through `Add-Type`; it worked, and it was
+ *     removed the same day at the operator's decision, because runtime-compiled C# calling
+ *     `AttachConsole` in another process's console is exactly what endpoint protection is built to
+ *     flag. The cost is honest: a console server (node, dotnet) is still ended by `/F`. It is only
+ *     ever one the bot started, which is what matters more.
+ *   - The PowerShell that reads the table is given its script on the command line, where anyone
+ *     reading the process list can see all of it — never on stdin, and never encoded.
+ */
+import { spawn } from 'node:child_process';
+import { winPsEnv } from './winps.js';
+/** How long a process is given to close after the polite `taskkill`, before `/F`. */
+export const CLOSE_GRACE_MS = 5_000;
+/**
+ * The shells the bot has started, with when each started and ended.
+ *
+ * One per task, handed to every `runStep` the task makes — its steps, its checks, its reviews — so
+ * that "the bot's processes" means this task's, and a second session running at the same time in
+ * another project is somebody else. A list rather than a map because Windows reuses process ids,
+ * and two steps of one task can be given the same one.
+ */
+export class ProcessTracker {
+    roots = [];
+    started(pid, at = Date.now()) {
+        this.roots.push({ pid, from: at });
+    }
+    ended(pid, at = Date.now()) {
+        for (let i = this.roots.length - 1; i >= 0; i -= 1) {
+            const r = this.roots[i];
+            if (r.pid === pid && r.to === undefined) {
+                r.to = at;
+                return;
+            }
+        }
+    }
+}
+/** Runs one PowerShell expression, visible on the command line, and returns its stdout or null. */
+function powershell(script, timeoutMs = 20_000) {
+    return new Promise((resolve) => {
+        const child = spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], { windowsHide: true, env: winPsEnv() });
+        let out = '';
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        const timer = setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch {
+                /* already gone */
+            }
+            finish(null);
+        }, timeoutMs);
+        child.stdout.on('data', (d) => (out += d.toString('utf8')));
+        child.on('error', () => {
+            clearTimeout(timer);
+            finish(null);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            finish(code === 0 ? out : null);
+        });
+    });
+}
+function parseJsonList(text) {
+    if (!text?.trim())
+        return [];
+    try {
+        const parsed = JSON.parse(text);
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    catch {
+        return [];
+    }
+}
+/** Windows FILETIME (100 ns since 1601) to milliseconds since 1970. */
+const fromFileTime = (ft) => (ft > 0 ? Math.round(ft / 10_000 - 11_644_473_600_000) : 0);
+/**
+ * A moment as WMI's own datetime literal, `yyyymmddHHMMSS.mmmmmm+000`, in UTC. Built here rather
+ * than by PowerShell's ManagementDateTimeConverter, which Constrained Language Mode does not allow
+ * and which corporate machines commonly enforce (verified 2026-09-27). Exported for the check.
+ */
+export function dmtfOf(ms) {
+    const d = new Date(Math.max(0, ms));
+    const p = (n, w = 2) => String(n).padStart(w, '0');
+    return (`${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}` +
+        `${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}.${p(d.getUTCMilliseconds(), 3)}000+000`);
+}
+/** Slack either side of a recorded start or end: the table's clock and ours are read separately. */
+const SLACK_MS = 2_000;
+/**
+ * The processes created at or after `since`, with their parents. Filtered in WMI itself, so rows
+ * older than the bot's work are never read at all.
+ */
+export async function processTable(since) {
+    const from = dmtfOf(since - SLACK_MS);
+    const text = await powershell(`Get-CimInstance Win32_Process -Filter "CreationDate >= '${from}'" | Select-Object ProcessId, ParentProcessId, Name, CommandLine, ` +
+        "@{n='Created';e={ if ($_.CreationDate) { $_.CreationDate.ToFileTimeUtc() } else { 0 } }} | ConvertTo-Json -Compress");
+    return parseJsonList(text)
+        .map((p) => ({
+        pid: p.ProcessId,
+        parent: p.ParentProcessId,
+        name: p.Name ?? '',
+        command: p.CommandLine ?? '',
+        created: fromFileTime(p.Created),
+    }))
+        .filter((p) => p.pid !== process.pid);
+}
+/** The ports these processes are listening on — asked about them only, not the whole machine. */
+async function listenersOf(pids) {
+    if (pids.length === 0)
+        return [];
+    const text = await powershell(`Get-NetTCPConnection -State Listen -OwningProcess ${pids.map((p) => Math.trunc(p)).join(',')} -ErrorAction SilentlyContinue | ` +
+        'Select-Object LocalPort, OwningProcess | ConvertTo-Json -Compress');
+    return parseJsonList(text).map((l) => ({ port: l.LocalPort, pid: l.OwningProcess }));
+}
+/**
+ * The rows that descend from one of `roots` — including a root itself while it is alive.
+ *
+ * A parent that is still alive is followed only when it is older than the child; if it is younger,
+ * its id was reused after the child's real parent died, and the recorded windows are consulted
+ * instead. A dead parent counts only when it is a recorded root and the child was created while
+ * that root was running — a process cannot be created by one that has already exited.
+ */
+export function descendantsOf(table, roots) {
+    const byPid = new Map(table.map((r) => [r.pid, r]));
+    const memo = new Map();
+    const within = (pid, created) => roots.some((r) => r.pid === pid && created >= r.from - SLACK_MS && (r.to === undefined || created <= r.to + SLACK_MS));
+    const isRoot = (row) => roots.some((r) => r.pid === row.pid && Math.abs(row.created - r.from) <= SLACK_MS);
+    const ours = (row, depth) => {
+        const known = memo.get(row.pid);
+        if (known !== undefined)
+            return known;
+        if (depth > 64)
+            return false;
+        memo.set(row.pid, false); // a cycle in reused ids is not ownership
+        let result = isRoot(row);
+        if (!result && row.parent !== row.pid) {
+            const parent = byPid.get(row.parent);
+            // An older parent that is still alive *is* the parent, ours or not; only when it is gone, or
+            // its id now belongs to a younger process, do the recorded windows decide.
+            if (parent && parent.created <= row.created + SLACK_MS)
+                result = parent.pid !== 0 && ours(parent, depth + 1);
+            else
+                result = within(row.parent, row.created);
+        }
+        memo.set(row.pid, result);
+        return result;
+    };
+    return table.filter((row) => ours(row, 0));
+}
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM means it exists and belongs to someone else, which is still "there".
+        return e.code === 'EPERM';
+    }
+}
+async function waitGone(pids, ms) {
+    const until = Date.now() + ms;
+    while (Date.now() < until && pids.some(isAlive))
+        await new Promise((r) => setTimeout(r, 200));
+}
+function taskkill(pid, force) {
+    return new Promise((resolve) => {
+        try {
+            const args = ['/pid', String(pid), '/T', ...(force ? ['/F'] : [])];
+            const child = spawn('taskkill', args, { stdio: 'ignore', windowsHide: true });
+            child.on('close', () => resolve());
+            child.on('error', () => resolve());
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+/**
+ * Stops exactly these processes: `taskkill /T`, a grace period, then `taskkill /T /F`.
+ *
+ * The list is the whole set, worked out by the caller before anything is stopped — not a root to be
+ * expanded with `/T` — because a tree whose root has already exited is invisible to `/T`, and that
+ * is precisely the shape of a server left behind by `Start-Process`. `/T` is still passed, for
+ * whatever a process managed to start while it was being stopped.
+ *
+ * This process and its parent are never on the list, whatever a caller passes.
+ */
+export async function stopProcesses(pids, opts = {}) {
+    const how = new Map();
+    const protect = new Set([process.pid, process.ppid]);
+    const wanted = [...new Set(pids)].filter((p) => !protect.has(p));
+    for (const p of wanted)
+        if (!isAlive(p))
+            how.set(p, 'already-gone');
+    let live = wanted.filter(isAlive);
+    if (live.length > 0) {
+        for (const p of live)
+            await taskkill(p, false);
+        await waitGone(live, opts.graceMs ?? CLOSE_GRACE_MS);
+        for (const p of live)
+            if (!isAlive(p))
+                how.set(p, 'closed');
+        live = live.filter(isAlive);
+    }
+    for (const p of live)
+        await taskkill(p, true);
+    await waitGone(live, 2_000);
+    for (const p of live)
+        how.set(p, isAlive(p) ? 'failed' : 'forced');
+    return how;
+}
+/**
+ * Stops a process the runner started and everything under it that is still running — the form the
+ * runner uses for a step that timed out, went silent or was aborted. `since` is when it was started,
+ * so only processes from then on are read. When the table cannot be read, it falls back to
+ * `taskkill /T /F` on the root, which is what it always did.
+ */
+export async function stopTree(rootPid, since, opts = {}) {
+    const table = await processTable(since);
+    const root = table.find((r) => r.pid === rootPid);
+    if (!root) {
+        await taskkill(rootPid, true);
+        return new Map([[rootPid, isAlive(rootPid) ? 'failed' : 'forced']]);
+    }
+    const tree = descendantsOf(table, [{ pid: rootPid, from: root.created }]).map((r) => r.pid);
+    return await stopProcesses(tree, opts);
+}
+/** Folded for comparison: Windows paths are case-insensitive and can use either slash. */
+const fold = (s) => s.replace(/\//g, '\\').toLowerCase();
+/**
+ * The moment watching begins. Taken at the start of a task it reads nothing — nothing the task
+ * started exists yet. Taken before a review it reads what the task's own work started since `from`,
+ * so the review is answerable only for what it adds.
+ */
+export async function snapshotProcesses(_projectDir, from) {
+    const since = Date.now();
+    if (from === undefined)
+        return { since, processes: [], listeners: [] };
+    return { since: from, processes: await processTable(from), listeners: [] };
+}
+/**
+ * What was created since the snapshot: the part of it the bot started (`ours`), and the part that
+ * names the project folder but cannot be tied to a step (`notOurs`), each with its ports. Without a
+ * tracker nothing is the bot's, and everything new in the folder is `notOurs`.
+ */
+export async function findLeftovers(projectDir, before, tracker) {
+    const now = await processTable(before.since);
+    // A process is "the same" only if its id *and* its creation time match: an id alone is reused.
+    const known = new Set(before.processes.map((p) => `${p.pid}@${p.created}`));
+    // The console host of a server's own window is its child in the table, and goes when the last
+    // process on that console does; listing it would only be noise beside the server it belongs to.
+    const fresh = now.filter((p) => !known.has(`${p.pid}@${p.created}`) && p.name.toLowerCase() !== 'conhost.exe');
+    const mine = new Set(tracker ? descendantsOf(now, tracker.roots).map((r) => r.pid) : []);
+    const folder = fold(projectDir);
+    const ours = fresh.filter((p) => mine.has(p.pid));
+    const notOurs = fresh
+        .filter((p) => !mine.has(p.pid) && folder !== '' && fold(p.command).includes(folder))
+        // The runner's own table query names nothing of the project, but keep it out regardless.
+        .filter((p) => !p.command.includes('Get-CimInstance Win32_Process'));
+    const listeners = await listenersOf([...ours, ...notOurs].map((p) => p.pid));
+    const withPorts = (p) => ({
+        pid: p.pid,
+        parent: p.parent,
+        name: p.name,
+        command: p.command,
+        ports: listeners.filter((l) => l.pid === p.pid).map((l) => l.port),
+    });
+    return { ours: ours.map(withPorts), notOurs: notOurs.map(withPorts) };
+}
+/** Stops what the bot left running since the snapshot, and says what it stopped and what it did not. */
+export async function reapLeftovers(projectDir, before, tracker) {
+    const { ours, notOurs } = await findLeftovers(projectDir, before, tracker);
+    const result = { killed: [], failed: [], notOurs };
+    if (ours.length === 0)
+        return result;
+    const how = await stopProcesses(ours.map((l) => l.pid));
+    for (const l of ours) {
+        const h = how.get(l.pid) ?? 'failed';
+        (h === 'failed' ? result.failed : result.killed).push({ ...l, how: h });
+    }
+    return result;
+}
+/** One line per leftover, for the event and the record. */
+export function describeLeftovers(leftovers) {
+    return leftovers
+        .map((l) => `${l.name} (pid ${l.pid}${l.ports.length > 0 ? `, listening on ${l.ports.join(', ')}` : ''}${l.how ? `, ${l.how}` : ''}): ` +
+        l.command.slice(0, 160))
+        .join('\n');
+}