copilot-operator 0.1.0

package/dist/src/exec/checks.js

@@ -0,0 +1,285 @@
+/**
+ * The gate a task has to pass before "done" is accepted.
+ *
+ * Until now a task ended when Copilot said it had ended. The `expected` line of a plan was
+ * text: it travelled to the chat, it was read, and nothing ever compared it to the machine.
+ * A check is that same expectation written so this runner can decide it for itself — run a
+ * command and look at the exit code, look for a string in the output, look for a file — and
+ * every kind here was chosen for one reason: a computer can answer it without judgement.
+ *
+ * That constraint is the whole design. This project drives a language model; it does not have
+ * one of its own, and a check whose answer needs an opinion could only be faked. So the
+ * judgement stays where it belongs, with whoever wrote the check, and what happens afterwards
+ * is mechanical: all pass and the task is done, one fails and the failures go back to the chat
+ * as a report, exactly like the output of a step, for Copilot to fix and try again.
+ */
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isWithin } from './confinement.js';
+import { runStep } from './runner.js';
+import { resolveShell } from './shells.js';
+import { repoState, workingTreePaths } from '../vcs/git.js';
+import { findSuspicious, suspiciousDetail } from '../vcs/commitHygiene.js';
+/**
+ * The check the runner adds on its own whenever it is about to commit.
+ *
+ * It is a constant rather than something a plan writes because it is not a claim about the
+ * work: it is what a commit should never carry, whatever the task was.
+ */
+export const COMMIT_CLEAN_CHECK = { name: 'nothing installed, built, logged or secret is committed', expect: 'commit-clean' };
+const DEFAULT_CHECK_TIMEOUT_MS = 10 * 60 * 1000;
+/** How much of a command's output travels back to the chat with a failure. */
+const OUTPUT_KEPT = 4000;
+function shorten(text, max = OUTPUT_KEPT) {
+    const trimmed = text.trim();
+    return trimmed.length > max ? `${trimmed.slice(0, max)}\n… (${trimmed.length - max} more characters)` : trimmed;
+}
+/** Whether a check needs a command run, which decides what it can be asked about. */
+function needsCommand(check) {
+    return check.expect === 'exit-zero' || check.expect === 'exit-nonzero' || check.expect.startsWith('output-');
+}
+/**
+ * One check, decided.
+ *
+ * A check that cannot be evaluated — no command where one is needed, a command the policy
+ * refuses, a file it cannot read — counts as failed rather than as passed. The alternative is
+ * a gate that opens when it breaks, which is the one behaviour a gate must never have.
+ */
+export async function runCheck(check, index, opts) {
+    const fail = (detail, extra = {}) => ({ check, passed: false, detail, ...extra });
+    const pass = (detail, extra = {}) => ({ check, passed: true, detail, ...extra });
+    if (check.expect === 'commit-clean') {
+        const dir = (opts.repoDir ?? '').trim();
+        if (!dir)
+            return pass('no repository is set for this session, so nothing is committed');
+        const state = await repoState(dir).catch(() => null);
+        if (!state?.isRepo)
+            return pass(`${dir} is not a git repository, so nothing is committed`);
+        // File by file, not folder by folder: a new `api/` with node_modules inside is one line to
+        // `git status` and thousands of files to a commit.
+        const found = findSuspicious(await workingTreePaths(dir));
+        return found.length === 0
+            ? pass('nothing in the working tree looks like tool output or secrets')
+            : fail(suspiciousDetail(found), { output: found.map((s) => `${s.path}\t${s.reason}`).join('\n') });
+    }
+    /*
+     * Where this check really runs, decided once. The command runs here and a file check's relative
+     * path is resolved against it — the same folder for both, so the path confined is the path read.
+     * A relative `file` used to be read relative to wherever the runner itself was started, which is
+     * this bot's own checkout: it pointed nowhere useful, and it would have made the path checked and
+     * the path read two different paths.
+     */
+    const cwd = resolve(opts.cwd, (check.cwd ?? '').trim() || '.');
+    if (opts.roots && opts.roots.length > 0 && !isWithin(cwd, opts.roots)) {
+        return fail(`the check was refused before it ran: its working folder ${cwd} is outside the project folders (${opts.roots.join(', ')})`, { refusedBeforeRunning: true });
+    }
+    if (needsCommand(check)) {
+        const command = (check.run ?? '').trim();
+        if (!command)
+            return fail('this check asks about a command but names none');
+        /*
+         * Which shell this check runs in, asked of the same place a task step asks.
+         *
+         * A check used to fall back to `pwsh` here on its own, which is how a machine without
+         * PowerShell 7 came to fail every check with a spawn error while the same commands ran
+         * happily in `cmd`. It is resolved before the deny list rather than inside `runStep`
+         * because the gate below is told which shell it is screening for, and because a check that
+         * cannot run at all should say so without a process being started.
+         */
+        const chosen = resolveShell(check.shell ?? opts.defaultShell);
+        if (!chosen.ok)
+            return fail(chosen.problem.message, { environmentProblem: chosen.problem });
+        const { shell, path: shellPath } = chosen.resolved;
+        const refused = opts.deny?.(command, shell, cwd);
+        if (refused)
+            return fail(`the command was refused before it ran: ${refused}`, { refusedBeforeRunning: true });
+        let result;
+        try {
+            result = await runStep({
+                id: 900 + index,
+                // What the check asked for, or the standing default when it asked for nothing: the
+                // runner resolves it again from the same inventory, so the two cannot disagree, and
+                // the result then records what was wanted as well as what ran.
+                shell: check.shell ?? opts.defaultShell,
+                command,
+                cwd,
+                hardTimeoutMs: opts.timeoutMs ?? DEFAULT_CHECK_TIMEOUT_MS,
+                logPath: join(opts.logDir, `check-${index + 1}.txt`),
+                passEnv: opts.passEnv,
+            }, { signal: opts.signal, tracker: opts.tracker });
+        }
+        catch (e) {
+            return fail(`the check could not be run: ${e.message}`);
+        }
+        const output = shorten(`${result.stdout}${result.stderr ? `\n${result.stderr}` : ''}`);
+        const seen = { exitCode: result.exitCode, output, shell: result.shell, shellPath: result.shellPath };
+        // The shell was there when the run began and would not start when it was wanted. Nothing
+        // about the work has been learned, so this is reported as what it is rather than as a
+        // command that failed.
+        if (result.shellProblem) {
+            return fail(result.shellProblem.message, { ...seen, environmentProblem: result.shellProblem });
+        }
+        if (result.outcome !== 'completed') {
+            return fail(`the command ended ${result.outcome} rather than finishing`, seen);
+        }
+        switch (check.expect) {
+            case 'exit-zero':
+                return result.exitCode === 0
+                    ? pass('the command succeeded', seen)
+                    : fail(`expected the command to succeed, but it exited ${result.exitCode}`, seen);
+            case 'exit-nonzero':
+                return result.exitCode !== 0
+                    ? pass(`the command failed, as expected (exit ${result.exitCode})`, seen)
+                    : fail('expected the command to fail, but it succeeded', seen);
+            case 'output-contains':
+                return output.includes(check.value ?? '')
+                    ? pass(`the output contains "${check.value}"`, seen)
+                    : fail(`expected the output to contain "${check.value}", and it does not`, seen);
+            case 'output-omits':
+                return output.includes(check.value ?? '')
+                    ? fail(`expected the output not to contain "${check.value}", but it does`, seen)
+                    : pass(`the output does not contain "${check.value}"`, seen);
+            case 'output-matches': {
+                let re;
+                try {
+                    re = new RegExp(check.value ?? '', 'm');
+                }
+                catch (e) {
+                    return fail(`the pattern is not a valid regular expression: ${e.message}`, seen);
+                }
+                return re.test(output)
+                    ? pass(`the output matches /${check.value}/`, seen)
+                    : fail(`expected the output to match /${check.value}/, and it does not`, seen);
+            }
+            default:
+                return fail(`unknown check kind "${check.expect}"`, seen);
+        }
+    }
+    const named = (check.file ?? '').trim();
+    if (!named)
+        return fail('this check asks about a file but names none');
+    const file = resolve(cwd, named);
+    if (opts.roots && opts.roots.length > 0 && !isWithin(file, opts.roots)) {
+        return fail(`the check was refused before it ran: ${file} is outside the project folders (${opts.roots.join(', ')})`, { refusedBeforeRunning: true });
+    }
+    switch (check.expect) {
+        case 'file-exists':
+            return existsSync(file) ? pass(`${file} exists`) : fail(`expected ${file} to exist, and it does not`);
+        case 'file-missing':
+            return existsSync(file) ? fail(`expected ${file} not to exist, but it does`) : pass(`${file} does not exist`);
+        case 'file-contains': {
+            if (!existsSync(file))
+                return fail(`expected ${file} to contain "${check.value}", but the file does not exist`);
+            let body;
+            try {
+                body = await readFile(file, 'utf8');
+            }
+            catch (e) {
+                return fail(`${file} could not be read: ${e.message}`);
+            }
+            return body.includes(check.value ?? '')
+                ? pass(`${file} contains "${check.value}"`)
+                : fail(`expected ${file} to contain "${check.value}", and it does not`, { output: shorten(body, 1500) });
+        }
+        default:
+            return fail(`unknown check kind "${check.expect}"`);
+    }
+}
+/** Every check of a task, in order. They all run: a report of one failure at a time is slow. */
+export async function runChecks(checks, opts) {
+    const out = [];
+    for (const [i, check] of checks.entries()) {
+        if (opts.signal?.aborted) {
+            out.push({ check, passed: false, detail: 'the operator stopped the run before this check ran' });
+            continue;
+        }
+        out.push(await runCheck(check, i, opts));
+    }
+    return out;
+}
+/**
+ * Whether a round of checks was decided by the machine rather than by the work.
+ *
+ * The first such problem is the answer: several checks on a machine with no PowerShell 7 all
+ * hit the same missing interpreter, and repeating one sentence per check helps nobody. A
+ * caller that gets something back here is being told that this round was not an attempt at the
+ * task, that it should not cost the task one of its rounds, and that there is nothing worth
+ * sending to a language model — an interpreter it cannot install is not a thing it can fix.
+ */
+export function environmentProblemIn(outcomes) {
+    return outcomes.find((o) => o.environmentProblem)?.environmentProblem ?? null;
+}
+/** A short line per check, for the live log and the task record. */
+export function describeCheck(check) {
+    const what = check.expect === 'commit-clean' ? "the repository's uncommitted files" : needsCommand(check) ? (check.run ?? '') : (check.file ?? '');
+    return `${check.name}: ${check.expect}${check.value ? ` "${check.value}"` : ''} — ${what}`;
+}
+/**
+ * What Copilot is told when checks fail.
+ *
+ * Written as an instruction rather than as a complaint: it says what was asked, what happened,
+ * and that the task is not over. The full output is attached as a file by the caller, the same
+ * way step output is, because a chat message is the wrong place for a compiler's opinion.
+ */
+export function failureMessage(outcomes, round, maxRounds) {
+    const failed = outcomes.filter((o) => !o.passed);
+    const lines = [
+        '## The task is not finished yet',
+        '',
+        `You reported the task as done, but ${failed.length} of the ${outcomes.length} checks set for it did not pass.`,
+        'These checks are run by the runner, not by you, and they are what decides whether this task is over.',
+        '',
+    ];
+    for (const [i, o] of failed.entries()) {
+        lines.push(`### ${i + 1}. ${o.check.name}`);
+        lines.push('');
+        lines.push(o.check.expect === 'commit-clean'
+            ? '- What was required: nothing in the commit that is installed, built, logged or secret'
+            : `- What was required: \`${o.check.expect}\`${o.check.value ? ` of "${o.check.value}"` : ''}`);
+        if (o.check.run)
+            lines.push(`- Command: \`${o.check.run}\``);
+        if (o.check.file)
+            lines.push(`- File: \`${o.check.file}\``);
+        lines.push(`- What happened: ${o.detail}`);
+        if (o.exitCode !== undefined)
+            lines.push(`- Exit code: ${o.exitCode}`);
+        lines.push('');
+    }
+    const passed = outcomes.filter((o) => o.passed);
+    if (passed.length > 0) {
+        lines.push(`The other ${passed.length} check(s) passed: ${passed.map((o) => o.check.name).join(', ')}.`);
+        lines.push('');
+    }
+    lines.push(`Fix what is failing and continue. Send steps as usual; do not report the task as done again until you ` +
+        `have reason to believe these checks will pass. This is attempt ${round} of ${maxRounds}: after that the ` +
+        'task is closed as failed and the operator reads it.');
+    return lines.join('\n');
+}
+/** The same, as the plain text file that travels with the message. */
+export function failureReport(outcomes) {
+    const parts = ['CHECKS THAT DID NOT PASS', '='.repeat(60), ''];
+    for (const o of outcomes.filter((x) => !x.passed)) {
+        parts.push(`CHECK : ${o.check.name}`);
+        parts.push(`EXPECT: ${o.check.expect}${o.check.value ? ` "${o.check.value}"` : ''}`);
+        if (o.check.run)
+            parts.push(`RUN   : ${o.check.run}`);
+        if (o.check.file)
+            parts.push(`FILE  : ${o.check.file}`);
+        parts.push(`RESULT: ${o.detail}`);
+        if (o.exitCode !== undefined)
+            parts.push(`EXIT  : ${o.exitCode}`);
+        if (o.output) {
+            parts.push('OUTPUT:');
+            parts.push(o.output);
+        }
+        parts.push('', '-'.repeat(60), '');
+    }
+    const passed = outcomes.filter((x) => x.passed);
+    if (passed.length > 0) {
+        parts.push('CHECKS THAT PASSED', '-'.repeat(60));
+        for (const o of passed)
+            parts.push(`- ${o.check.name}: ${o.detail}`);
+    }
+    return parts.join('\n');
+}

package/dist/src/exec/confinement.js

@@ -0,0 +1,224 @@
+/**
+ * The project and nothing else.
+ *
+ * Every other gate in this runner is about *what* a command is: a technique on the refused list, a
+ * program not on the allowlist. None of them knew *where* a command reached. A step could read the
+ * operator's SSH key, write into their AppData, delete from `C:\Windows`, change a service or open
+ * the firewall, and every one of those passed — cmdlets are not programs, so the allowlist never
+ * saw them, and nothing anywhere knew what "the project" was. Probed before this was written:
+ * of eighteen operations reaching outside the project, four were stopped, and those four only
+ * because `netsh`, `setx` and `winget` happen not to be on the program list.
+ *
+ * The rule the operator set is short: this runner works in the project folders, and nowhere else.
+ * The project folders are the session's own and every folder registered in Settings — a test
+ * suite legitimately starts the application from the repository next to it, and a plan across a
+ * front end, a back end and its tests is one piece of work. Everything outside them belongs to the
+ * machine and the person who owns it, and none of it is the task's business.
+ *
+ * Four things are refused, all by reading the command line:
+ *
+ *   paths outside      an absolute path, a UNC share, `..` that climbs out, a location built from
+ *                      the operator's profile or the system (`~`, `$env:APPDATA`, `%TEMP%`…).
+ *                      Reads as well as writes: what a step prints goes to the chat, so reading
+ *                      a key outside the project is sending it there.
+ *   the registry       and the other providers that are not the file system. The project has no
+ *                      business in any of them, reading or writing.
+ *   the machine        services, the network and the firewall, local users, the clock, Windows
+ *                      features, disks, machine-wide modules. Management of the computer.
+ *   global installs    `npm -g`, `dotnet tool -g`, `cargo install`, `go install`, `pip install`
+ *                      into the machine's own Python. The same tool installed into the project
+ *                      (`npm install -D`, a `.venv`) is the ordinary way and stays open.
+ *
+ * What this is not, and it has to be said where somebody will read it: a boundary. It reads what a
+ * step *says*, which is exactly what the operator asked for — whatever the chat proposes that
+ * reaches outside the project is not run. It cannot see what a program does once it is running:
+ * `node build.js`, `npm run x` and a test suite can each read and write anywhere the account can,
+ * and a path assembled from variables at run time is invisible here. Confinement that holds against
+ * that is the operating system's to give — a separate Windows account whose file permissions reach
+ * the project folders and nothing of the operator's — and the README says how.
+ */
+import { win32 } from 'node:path';
+function normalise(p) {
+    return win32.resolve(p).replace(/[\\/]+$/, '').toLowerCase();
+}
+/**
+ * Whether a path lies within one of the roots. By path segments, not by string prefix: a root of
+ * `C:\Projects\calc` must not admit `C:\Projects\calculator-evil`, which starts with the same
+ * characters and is somewhere else entirely.
+ */
+export function isWithin(path, roots) {
+    const target = normalise(path);
+    return roots.some((r) => {
+        if (!r.trim())
+            return false;
+        const root = normalise(r);
+        return target === root || target.startsWith(`${root}\\`);
+    });
+}
+/** Roots as a set: resolved, de-duplicated, empty ones dropped. */
+export function projectRoots(folders) {
+    const seen = new Map();
+    for (const f of folders) {
+        const t = (f ?? '').trim();
+        if (!t)
+            continue;
+        const abs = win32.resolve(t);
+        seen.set(normalise(abs), abs);
+    }
+    return [...seen.values()];
+}
+// --- what gets read out of a command line -------------------------------------------------
+/** Quoted strings, with their content. The content of either kind is searched for paths. */
+const QUOTED = /(["'])((?:(?!\1)[^\r\n])*)\1/g;
+/** A drive-absolute path, `C:\x` or `C:/x`, not glued to a word, a slash or a dot. */
+const DRIVE_BARE = /(?<![\w/\\.])([A-Za-z]:[\\/][^\s"'`;|&<>,(){}]*)/g;
+/** Where a drive-absolute path starts, inside quoted text that may hold several. */
+const DRIVE_START = /(?<![\w/\\.])[A-Za-z]:[\\/]/g;
+/** A share: `\\host\share`, and the device forms `\\?\` and `\\.\`. */
+const UNC = /(?:^|[^\\])(\\\\(?:[?.]\\|[A-Za-z0-9._$-]+\\[A-Za-z0-9._$ -]))/;
+/** A path written as a file URI, which reads a local file through a web cmdlet. */
+const FILE_URI = /\bfile:\/{2,3}([A-Za-z]:[\\/][^\s"'`;|&<>]*)/gi;
+/**
+ * Locations that belong to the operator or to the system, however they are spelled. Kept to the
+ * location-bearing names: `$env:PATH`, `$env:NODE_ENV` and the rest are not places and stay open.
+ */
+const LOCATION_VARS = 'USERPROFILE|HOMEDRIVE|HOMEPATH|HOMESHARE|HOME|APPDATA|LOCALAPPDATA|TEMP|TMP|WINDIR|SystemRoot|SystemDrive|' +
+    'ProgramFiles(?:\\(x86\\))?|ProgramW6432|ProgramData|ALLUSERSPROFILE|PUBLIC|OneDrive\\w*|CommonProgramFiles\\w*';
+const ENV_LOCATION = new RegExp(`\\$\\{?env:(${LOCATION_VARS})\\}?|%(${LOCATION_VARS})%`, 'i');
+const HOME_VAR = /\$HOME\b/i;
+/** `~` as the start of a path, and not the `~` of `HEAD~1` or `@~1.2`. */
+const TILDE = /(?:^|[\s"'=(,])~(?=[\\/]|$|[\s"'`;|&)])/;
+/** Changing to the root of the current drive, which needs no drive letter to leave the project. */
+const CD_TO_ROOT = /(?:^|[\s;|&({])(?:Set-Location|Push-Location|cd|chdir|sl|pushd)\s+["']?[\\/]["']?(?=$|[\s;|&)}])/i;
+/** A path segment that climbs: `..` on its own, or between separators. */
+const CLIMBS = /(?:^|[\\/])\.\.(?:$|[\\/])/;
+/** Every whitespace- or separator-delimited token, quoted content split the same way. */
+function tokens(command) {
+    const out = [];
+    const rest = command.replace(QUOTED, (_whole, _q, inner) => {
+        out.push(...inner.split(/\s+/));
+        return ' ';
+    });
+    out.push(...rest.split(/[\s;|&<>(){},]+/));
+    // An argument written `name=value` or `-Name:value` carries its path after the separator.
+    return out
+        .filter(Boolean)
+        .flatMap((t) => {
+        const m = /^-{1,2}[\w-]+[:=](.+)$/.exec(t) ?? /^[\w.-]+=(.+)$/.exec(t);
+        return m ? [t, m[1]] : [t];
+    });
+}
+/** Every drive-absolute path in a command, quoted ones whole even when they hold spaces. */
+function drivePaths(command) {
+    const found = [];
+    const rest = command.replace(QUOTED, (whole, _q, inner) => {
+        // A quoted string may carry several paths — `cmd /c "copy C:\a C:\b"` — so each one runs from
+        // where it starts to where the next begins, rather than the first swallowing the rest.
+        const starts = [...inner.matchAll(DRIVE_START)].map((m) => m.index ?? 0);
+        starts.forEach((start, i) => found.push(inner.slice(start, starts[i + 1] ?? inner.length).trim()));
+        return ' '.repeat(whole.length);
+    });
+    for (const m of rest.matchAll(DRIVE_BARE))
+        found.push(m[1]);
+    for (const m of command.matchAll(FILE_URI))
+        found.push(m[1]);
+    return found;
+}
+// --- the machine, as opposed to the project -----------------------------------------------
+const PROVIDERS = /\b(?:HKLM|HKCU|HKCR|HKU|HKCC):|\bRegistry::|\bCert:\\|\bWSMan:\\/i;
+/** Cmdlet families that manage the computer. Each entry is a reason a person would recognise. */
+const MACHINE = [
+    { what: 'services', pattern: /\b(?:Get|Set|New|Remove|Start|Stop|Restart|Suspend|Resume)-Service\b/i },
+    { what: 'the network and the firewall', pattern: /\b\w+-Net(?:Firewall\w*|IPAddress|IPConfiguration|IPInterface|Adapter\w*|Route|NeighborCache|ConnectionProfile|Nat\w*|Qos\w*)\b|\b\w+-DnsClient\w*\b/i },
+    { what: 'local users and groups', pattern: /\b\w+-Local(?:User|Group|GroupMember)\b/i },
+    { what: 'the clock, the locale and the time zone', pattern: /\bSet-(?:Date|TimeZone|Culture|WinSystemLocale|WinUserLanguageList|WinHomeLocation)\b/i },
+    { what: 'Windows features and packages', pattern: /\b\w+-(?:WindowsOptionalFeature|WindowsFeature|WindowsCapability|WindowsPackage|AppxPackage|AppxProvisionedPackage)\b/i },
+    { what: 'machine-wide PowerShell modules', pattern: /\b(?:Install|Uninstall|Update)-(?:Module|Package|Script|PackageProvider|PSResource)\b|\b(?:Register|Set|Unregister)-PSRepository\b/i },
+    { what: 'disks and volumes', pattern: /\b\w+-(?:Disk|PhysicalDisk|VirtualDisk|Partition|Volume|StoragePool)\b/i },
+    { what: 'the execution policy', pattern: /\bSet-ExecutionPolicy\b/i },
+    { what: 'printers', pattern: /\b\w+-Printer\w*\b/i },
+    { what: 'the computer itself', pattern: /\b(?:Rename|Add|Remove|Checkpoint|Restore|Stop|Restart)-Computer\b|\b(?:Enable|Disable)-(?:PSRemoting|WSManCredSSP|ComputerRestore)\b/i },
+    { what: 'BitLocker and the TPM', pattern: /\b\w+-(?:BitLocker\w*|Tpm\w*)\b/i },
+    { what: 'network shares', pattern: /\b\w+-(?:SmbShare|SmbMapping|SmbServerConfiguration)\b/i },
+];
+/** Installs that land outside the project, and the ordinary way to do the same inside it. */
+const GLOBAL_INSTALL = [
+    { what: 'a global npm or pnpm install', pattern: /\b(?:npm|pnpm)(?:\.cmd)?\b[^|;&\n]*\s(?:-g|--global|--location[= ]global)(?=\s|$)/i, instead: 'install it into the project (`npm install -D <pkg>`) and run it with `npx`' },
+    { what: 'a global yarn install', pattern: /\byarn(?:\.cmd)?\s+global\s+add\b/i, instead: 'add it to the project (`yarn add -D <pkg>`)' },
+    { what: 'a global bun install', pattern: /\bbun(?:\.exe)?\b[^|;&\n]*\s(?:-g|--global)(?=\s|$)/i, instead: 'add it to the project (`bun add -d <pkg>`)' },
+    { what: 'a global .NET tool', pattern: /\bdotnet(?:\.exe)?\s+tool\s+(?:install|update)\b[^|;&\n]*\s(?:-g|--global)(?=\s|$)/i, instead: 'use a local tool manifest (`dotnet new tool-manifest`, then `dotnet tool install <tool>`)' },
+    { what: '`cargo install`, which installs into the user profile', pattern: /\bcargo(?:\.exe)?\s+install\b/i, instead: 'add it as a dependency of the project' },
+    { what: '`go install`, which installs outside the module', pattern: /\bgo(?:\.exe)?\s+install\b/i, instead: 'run it with `go run <pkg>@<version>` from the project' },
+];
+/**
+ * `pip install` into whatever Python is first on the PATH — the machine's, not the project's.
+ * Allowed when the interpreter or pip is itself a path inside the project (a `.venv`), which the
+ * path check then confirms, or when the install is aimed at a folder with `--target`/`--prefix`.
+ */
+function pipRefusal(command) {
+    const m = /(?:^|[\s;|&(])(["']?)([^\s"';|&()]*?)(pip3?|python3?|py)(?:\.exe)?\1\b[^|;&\n]*?\binstall\b[^|;&\n]*/i.exec(command);
+    if (!m)
+        return null;
+    const clause = m[0];
+    if (!/\b(?:pip3?)\b[^|;&\n]*\binstall\b|-m\s+pip\s+install\b/i.test(clause))
+        return null;
+    if (/\s--user\b/i.test(clause))
+        return 'refused: `pip install --user` installs into the operator\'s profile, outside the project. Create a virtual environment in the project (`python -m venv .venv`) and install into that (`.venv\\Scripts\\python -m pip install <pkg>`).';
+    const qualified = /[\\/]/.test(m[2] ?? '');
+    const aimed = /\s(?:--target|-t|--prefix|--root)(?:[\s=])/i.test(clause);
+    if (qualified || aimed)
+        return null;
+    return 'refused: `pip install` with the Python on the PATH installs into the machine\'s own Python, outside the project. Create a virtual environment in the project (`python -m venv .venv`) and install into that: `.venv\\Scripts\\python -m pip install <pkg>`.';
+}
+// --- the verdict ---------------------------------------------------------------------------
+function outside(what, c) {
+    return (`refused: ${what} — this runner works only inside the project folders (${c.roots.join(', ')}), and ` +
+        'nothing outside them is the task\'s business. Use a path inside the project. If the task genuinely ' +
+        'needs something from elsewhere on the machine, say so in `notes` and end `blocked`: that is for the ' +
+        'operator to arrange, not for a step to reach for.');
+}
+/**
+ * Why a command reaches outside the project, or null.
+ *
+ * Checked in order of how plainly the command says it, so the reason given is the most specific one:
+ * the machine's own settings first, then an install that lands outside, then any path at all.
+ */
+export function confinementRefusal(command, c) {
+    if (PROVIDERS.test(command)) {
+        return outside('the registry and the other non-file providers belong to the machine, not the project', c);
+    }
+    for (const { what, pattern } of MACHINE) {
+        if (pattern.test(command))
+            return outside(`this manages ${what}, which is the computer's, not the project's`, c);
+    }
+    for (const { what, pattern, instead } of GLOBAL_INSTALL) {
+        if (pattern.test(command)) {
+            return `refused: ${what} lands outside the project folders. ${instead[0].toUpperCase()}${instead.slice(1)}.`;
+        }
+    }
+    const pip = pipRefusal(command);
+    if (pip)
+        return pip;
+    const env = ENV_LOCATION.exec(command);
+    if (env)
+        return outside(`\`${env[0]}\` is a location on the machine — the operator's profile or the system — not in the project`, c);
+    if (HOME_VAR.test(command) || TILDE.test(command)) {
+        return outside('`~` and `$HOME` are the operator\'s profile, not the project', c);
+    }
+    if (UNC.test(command))
+        return outside('a network share is not the project', c);
+    if (CD_TO_ROOT.test(command))
+        return outside('this changes to the root of the drive', c);
+    for (const p of drivePaths(command)) {
+        if (!isWithin(p, c.roots))
+            return outside(`\`${p}\` is outside the project`, c);
+    }
+    for (const t of tokens(command)) {
+        if (!CLIMBS.test(t))
+            continue;
+        const resolved = win32.resolve(c.cwd, t);
+        if (!isWithin(resolved, c.roots))
+            return outside(`\`${t}\` climbs out of the project to ${resolved}`, c);
+    }
+    return null;
+}