copilot-operator 0.1.0

package/dist/src/exec/dangerous.js

@@ -0,0 +1,161 @@
+/**
+ * The techniques this runner refuses outright, whatever the configuration says.
+ *
+ * `execution.denyPatterns` is the operator's list: editable, sensible, and about damage — a
+ * wiped folder, a formatted drive, a reset repository. This is a different list and it exists
+ * for a different reader. A security team watching the workstation does not see intent; it sees
+ * `certutil.exe` decoding a base64 blob into a `.js` file in `%TEMP%` and something executing
+ * it, and it is right to treat that as a compromise, because that is precisely what a malware
+ * loader looks like. That the parent process happened to be an automation tool driven by a
+ * language model is not exculpatory. It is the whole problem.
+ *
+ * So these patterns are not defaults. They are not in the config schema, they cannot be edited
+ * away, and a `settings.json` written before they existed still gets them. The operator's list
+ * is applied on top; it can add, never subtract. A tool that executes commands written by a
+ * model has no business leaving its guard rails where the model's own output could one day
+ * suggest widening them.
+ *
+ * What is here, and why each one:
+ *
+ *   living-off-the-land binaries   `certutil`, `bitsadmin`, `mshta`, `regsvr32`, `rundll32`,
+ *                                  `wscript`, `cscript`, `forfiles`, `installutil`. All are
+ *                                  signed Microsoft tools with a legitimate purpose and an
+ *                                  overwhelmingly illegitimate reputation; every one of them
+ *                                  is on every EDR's watch list. None is needed to build, test
+ *                                  or inspect a software project, which is all this runner is
+ *                                  for, so refusing them costs nothing real.
+ *   decode and run                 `-EncodedCommand`, `FromBase64String`, `Invoke-Expression`.
+ *                                  The point of encoding a command is that a person reading the
+ *                                  log cannot see what it does, and the point of this runner's
+ *                                  log is that they can.
+ *   fetch and run                  `DownloadString`/`DownloadFile` into execution, `iwr | iex`.
+ *                                  Code that arrives at run time was never approved by anybody.
+ *   execution out of Temp          Nothing this runner legitimately does lives there: it downloads
+ *                                  nothing, and the code a task runs is written into the project
+ *                                  by a command step, where it can be read.
+ *   tampering and persistence      Defender exclusions, scheduled tasks, Run keys, new services.
+ *                                  A build step does not need to outlive the build.
+ *
+ * Deliberately **not** here: `node`, `npm`, `npx`, `git`, `tsc`, `dotnet`, `python`. They are
+ * the job. A guard that stops the work is a guard that gets switched off.
+ *
+ * And the honest limit, the same one `policy.ts` states about the deny list: this is not a
+ * security boundary. It raises the cost of the ordinary accident and the ordinary injected
+ * instruction. A determined attacker with a language model to write for them will find a
+ * phrasing no regular expression here anticipated. The boundary is a separate Windows account
+ * or a sandbox, which the README recommends and which this does not replace.
+ */
+export const DANGEROUS_TECHNIQUES = [
+    {
+        name: 'certutil',
+        pattern: /\bcertutil(\.exe)?\b/i,
+        why: 'certutil is a certificate tool routinely used to decode base64 payloads and fetch files; every EDR treats it as an indicator of compromise. Use PowerShell to read or convert files.',
+    },
+    {
+        name: 'bitsadmin',
+        pattern: /\bbitsadmin(\.exe)?\b/i,
+        why: 'bitsadmin transfers files in the background out of sight of the run log. This runner downloads nothing; write what is needed in the step itself.',
+    },
+    {
+        name: 'script-host',
+        pattern: /\b(wscript|cscript|mshta)(\.exe)?\b/i,
+        why: 'the Windows Script Host and mshta run .js, .vbs, .hta and remote pages as code. Nothing about building or testing a project needs them.',
+    },
+    {
+        name: 'proxy-execution',
+        pattern: /\b(regsvr32|rundll32|installutil|msbuild\s+[^|]*\/p:|wmic[^|]*process[^|]*call[^|]*create)\b/i,
+        why: 'these run code through a signed Microsoft binary so that it is not the process an observer expects. Run the tool itself instead.',
+    },
+    {
+        name: 'forfiles',
+        pattern: /\bforfiles(\.exe)?\b/i,
+        why: 'forfiles executes a command per matched file and is a common way to launch something under an innocuous parent. Use Get-ChildItem with a loop.',
+    },
+    {
+        name: 'encoded-command',
+        // PowerShell takes any unambiguous prefix, so `-e`, `-en` and `-enc` are the same switch as
+        // `-EncodedCommand`; anchoring on the whole word let `powershell -e <blob>` straight past. The
+        // short form is tied to a PowerShell invocation and a base64-shaped argument, so that `grep -e`
+        // and `node -e` are left alone.
+        pattern: /(-|\/)(EncodedCommand|enc)\b|\b(powershell|pwsh)(\.exe)?\b[^|\n]*\s(-|\/)e[a-z]*\s+["']?[A-Za-z0-9+\/=]{16,}/i,
+        why: 'an encoded command is a command nobody reading the log can see. Write it out in full.',
+    },
+    {
+        name: 'decode-and-run',
+        pattern: /FromBase64String|\bcertutil[^|\n]*-decode\b|\[System\.Text\.Encoding\][^|\n]*GetString\s*\(/i,
+        why: 'decoding a blob into code and running it hides what ran. If the content matters, write it to a file in the project and run that.',
+    },
+    {
+        name: 'invoke-expression',
+        pattern: /\b(Invoke-Expression|iex)\b/i,
+        why: 'Invoke-Expression runs a string as code, so what actually ran is decided at run time and never appears in the step. Call the command directly.',
+    },
+    {
+        name: 'fetch-and-run',
+        pattern: /(DownloadString|DownloadFile)\s*\(|\b(Invoke-WebRequest|iwr|curl|wget)\b[^|\n]*\|\s*(iex|Invoke-Expression|bash|sh|pwsh|powershell)\b/i,
+        why: 'code fetched at run time was approved by nobody. Write the code out in the step itself — a here-string with Set-Content into a file in the project — and run that file in the next step.',
+    },
+    {
+        name: 'run-from-temp',
+        // Any path with a Temp component, however it is spelled — `%TEMP%`, `$env:TEMP`,
+        // `$env:LOCALAPPDATA\\Temp`, `C:\\Windows\\Temp`, `/tmp/`. Matching the one literal spelling
+        // `\\AppData\\Local\\Temp` was matching one of several.
+        pattern: /(%TEMP%|\$env:TEMP|[\\\/]Temp[\\\/]|\/tmp\/)[^\s"';|]*\.(exe|js|jse|vbs|vbe|ps1|bat|cmd|hta|wsf|scr|dll|msi)\b/i,
+        why: 'this runner never executes anything out of Temp, and it downloads nothing: the code a task runs is written into the project by a command step. A binary or script run from Temp is the shape of a dropper.',
+    },
+    {
+        name: 'defender-tampering',
+        pattern: /\b(Add-MpPreference|Set-MpPreference|Remove-MpPreference)\b|\bDefender\b[^|\n]*\b(Disable|Exclusion)\b/i,
+        why: 'nothing this runner does requires changing the machine\'s antivirus settings, and doing so is what an attacker does first.',
+    },
+    {
+        name: 'persistence',
+        pattern: /\b(schtasks\s+[^|\n]*\/create|New-ScheduledTask|Register-ScheduledTask|New-Service|sc\s+create)\b|\\CurrentVersion\\Run\b/i,
+        why: 'a build or test step has no reason to outlive the run. Anything that survives a reboot is persistence and is for a person to set up deliberately.',
+    },
+    {
+        name: 'handler-launch',
+        /*
+         * Opening a file with whatever program Windows has registered for it — `Invoke-Item`, its alias
+         * `ii`, or `Start-Process` given a document rather than a program — and opening a URL, which
+         * starts the operator's browser. A build or a test starts the tool it needs by name; it never
+         * asks the shell to "open" something. Asking is how a `.hta`, a `.js` or a `.lnk` ends up run by
+         * `mshta`, the script host or whatever a shortcut points at, under this runner as the parent,
+         * and how a page ends up in the signed-in browser with the bot's process behind it.
+         */
+        pattern: /\b(Invoke-Item|ii)\s+\S|\b(Start-Process|saps|start)\s+(?:-\w+\s+)*(?:-FilePath\s+)?["']?(?:[^\s"']+\.(hta|vbs|vbe|js|jse|wsf|wsh|lnk|url|scr|cpl|msc|reg|inf|msi|msp|chm|pif)\b|https?:\/\/|ms-\w+:|file:\/\/)/i,
+        why: 'a file opened through its registered handler, or a URL opened in the browser, runs whatever Windows has registered for it under this runner. Start the program itself, by name, with the file as its argument.',
+    },
+    {
+        name: 'obfuscated-name',
+        /*
+         * Not a technique but the shape of hiding one, and worth more than chasing names.
+         *
+         * Attacking the list above found four ways past it that never touched a banned word:
+         * `cert^util` (cmd eats the caret), `cert""util` (the shell eats the empty quotes),
+         * `$a='cert'+'util'; & $a`, and `& (Get-Command cert*til)`. Every one runs
+         * `certutil` and none of them spells it. Chasing spellings is a race the writer wins, so
+         * this matches the hiding instead: a caret or an empty quote pair inside a word, a command
+         * name assembled from pieces, a name resolved by wildcard. None of the four has an honest
+         * use in a step that builds or tests a project — an honest step writes the name out.
+         */
+        pattern: /\w\^\w|\w(\"\"|'')\w|&\s*\(?\s*\$\w|\bGet-Command\s+[^\s|]*\*|\$\w+\s*=\s*['"][^'"]*['"]\s*\+/i,
+        why: 'the command name is hidden rather than written — a caret or empty quotes inside a word, a name built from pieces, or one resolved by wildcard. Write the command out in full; if it is one of the refused tools, it stays refused however it is spelled.',
+    },
+];
+/**
+ * Why this text must not be run, or null.
+ *
+ * It was written to answer for a command line and for the body of a downloaded script alike, since
+ * `pwsh -File payload.ps1` and the `certutil` line inside `payload.ps1` produce the same process
+ * tree. There are no downloaded scripts any more; a script a task runs is written by a command
+ * step whose text passes through here first.
+ */
+export function dangerousRefusal(text) {
+    for (const technique of DANGEROUS_TECHNIQUES) {
+        if (technique.pattern.test(text)) {
+            return `refused: ${technique.name}. ${technique.why}`;
+        }
+    }
+    return null;
+}

package/dist/src/exec/environment.js

@@ -0,0 +1,80 @@
+/**
+ * The tools a run actually ran with, written down once per task.
+ *
+ * Between two runs of the same plan, a day apart, `npm install` fetched TypeScript 6 and then
+ * 7, Next 15 and then 16, and the two runs behaved differently for reasons that took an
+ * afternoon to explain. "Latest" is a moving target and a plan that pins nothing gets a new
+ * world every time; the least the runner can do is say which world a run got. The project's
+ * own dependencies are in its lockfile, which the runner commits; this is the layer under
+ * that — the machine's Node, npm, git, both PowerShells, Edge, and the OS.
+ *
+ * Collected once per process and reused: versions do not change mid-run, and each probe is a
+ * child process.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { release, type as osType } from 'node:os';
+import { availableShells, detectShells } from './shells.js';
+let cached = null;
+/** One probe: its trimmed stdout, or null when the tool is missing or says nothing. */
+function probe(file, args, shell = false) {
+    try {
+        // With a shell the command is one string; Node warns about args it would only concatenate.
+        const r = shell
+            ? spawnSync([file, ...args].join(' '), { encoding: 'utf8', windowsHide: true, timeout: 15_000, shell: true })
+            : spawnSync(file, args, { encoding: 'utf8', windowsHide: true, timeout: 15_000 });
+        return r.status === 0 && typeof r.stdout === 'string' && r.stdout.trim() ? r.stdout.trim().split('\n')[0].trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+const EDGE_PATHS = ['C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe', 'C:/Program Files/Microsoft/Edge/Application/msedge.exe'];
+export function collectEnvironment(fresh = false) {
+    if (cached && !fresh)
+        return cached;
+    const edgePath = EDGE_PATHS.find((p) => existsSync(p)) ?? null;
+    const psVersion = '$PSVersionTable.PSVersion.ToString()';
+    cached = {
+        collectedAt: new Date().toISOString(),
+        os: `${osType()} ${release()}`,
+        node: process.versions.node,
+        // npm is a .cmd on Windows, which spawn cannot start without a shell.
+        npm: probe('npm', ['-v'], true),
+        git: probe('git', ['--version'])?.replace(/^git version\s*/i, '') ?? null,
+        pwsh: probe('pwsh', ['-NoProfile', '-NonInteractive', '-Command', psVersion]),
+        powershell: probe('powershell', ['-NoProfile', '-NonInteractive', '-Command', psVersion]),
+        shells: detectShells({ fresh }),
+        edge: edgePath
+            ? { path: edgePath, version: probe('powershell', ['-NoProfile', '-NonInteractive', '-Command', `(Get-Item '${edgePath}').VersionInfo.ProductVersion`]) }
+            : null,
+    };
+    return cached;
+}
+/** The manifest as a block of `name : version` lines, for the task log. */
+export function describeEnvironment(e, defaultShell) {
+    const at = (shell) => (e.shells.found[shell] ? ` at ${e.shells.found[shell]}` : '');
+    /*
+     * What a command that named no shell was actually handed to.
+     *
+     * `execution.defaultShell` decides it whenever the machine has that shell, and only when it has
+     * not does the order take over. Reporting the order's answer regardless was wrong in the one
+     * case somebody would be reading this line to understand: a default of `cmd` on a machine that
+     * also has PowerShell 7 would be written down here as `pwsh`, which is the opposite of what ran.
+     */
+    const fallback = (defaultShell && e.shells.found[defaultShell] ? defaultShell : availableShells(e.shells)[0]) ?? null;
+    return [
+        `os         : ${e.os}`,
+        `node       : ${e.node}`,
+        `npm        : ${e.npm ?? '(not found)'}`,
+        `git        : ${e.git ?? '(not found)'}`,
+        `pwsh       : ${e.pwsh ?? '(not found)'}${at('pwsh')}`,
+        `powershell : ${e.powershell ?? '(not found)'}${at('powershell')}`,
+        `cmd        : ${e.shells.found.cmd ?? '(not found)'}`,
+        // The one line somebody reads when a step ran and behaved unlike the machine it was written
+        // on: which interpreter a command that named no shell was handed to.
+        `shell used : ${fallback ?? '(none — nothing can be run on this machine)'} when a step or a check names none`,
+        `edge       : ${e.edge ? `${e.edge.version ?? '(version unknown)'} at ${e.edge.path}` : '(not found)'}`,
+        `collected  : ${e.collectedAt}`,
+    ].join('\n');
+}

package/dist/src/exec/isolation.js

@@ -0,0 +1,166 @@
+/**
+ * Where this runner is running, and whether that is anywhere safe.
+ *
+ * Every other gate in this round is a rule about what a command may say. This one is about the
+ * only thing that actually contains a command once it runs: the account it runs as. A deny list
+ * refuses a phrasing; a separate low-privilege Windows account refuses a capability, and no
+ * phrasing gets round it. The README has recommended one since before any of this, and the
+ * recommendation has had no mechanism behind it at all — a machine that ignored it looked exactly
+ * like a machine that had followed it, in the log and in the UI alike.
+ *
+ * What software can honestly do here is narrow, and pretending otherwise would be the worst
+ * outcome, because somebody would rely on it. A process cannot certify its own isolation: it
+ * cannot see the boundary it is inside, only the account it holds, and an attacker inside that
+ * account sees the same thing it does. So this module does three separate things and keeps them
+ * separate:
+ *
+ *   the claim      `execution.isolation` — what the operator says they have arranged. An
+ *                  assertion, recorded as an assertion, never as a finding.
+ *   the signals    the few facts that can be read cheaply and without being lied to by locale:
+ *                  the account name, whether the process holds High or System integrity, and
+ *                  whether the account is Windows Sandbox's own.
+ *   the assessment where the two disagree, or where the combination is one nobody should be in.
+ *
+ * The one rule with teeth: an unattended run on a machine claiming no isolation is refused. That
+ * combination — nobody watching, nothing containing — is the shape that put a security team on the
+ * phone, and it is the one case where refusing costs a little and allowing costs everything.
+ */
+import { spawnSync } from 'node:child_process';
+import { winPsEnv } from './winps.js';
+/** Windows Sandbox signs every process in it into this account. */
+const SANDBOX_USER = 'wdagutilityaccount';
+/*
+ * Integrity level is carried as a well-known SID, and a SID is the same on every Windows in every
+ * language. The text beside it is not: "High Mandatory Level" is translated, and a check written
+ * against the English would answer "not elevated" on a Bulgarian machine — the wrong answer in the
+ * unsafe direction, which is the one kind of wrong this must not be.
+ */
+const INTEGRITY_HIGH = 'S-1-16-12288';
+const INTEGRITY_SYSTEM = 'S-1-16-16384';
+const INTEGRITY_MEDIUM = 'S-1-16-8192';
+const INTEGRITY_LOW = 'S-1-16-4096';
+let cached = null;
+/**
+ * Whether the process holds an elevated (administrator) token, told in the integrity-level SID the
+ * rest of this file reads, or null when it cannot be asked. Separated so a test can supply its own.
+ *
+ * It used to run `whoami /groups`. `whoami.exe` started by another program is on nearly every
+ * endpoint product's list of account-discovery indicators, and this runs on company laptops, so it
+ * asks .NET instead, inside the one Windows PowerShell call: a principal is in the Administrators
+ * role only when its token is elevated — a UAC-filtered token answers no. The answer is `True` or
+ * `False` whatever the language of Windows, and is mapped onto the high and medium integrity SIDs
+ * so that `elevationFrom` stays the single reading of it.
+ */
+function elevationProbe() {
+    try {
+        const r = spawnSync('powershell', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            '([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)',
+        ], { encoding: 'utf8', windowsHide: true, timeout: 15_000, env: winPsEnv() });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        const answer = r.stdout.trim();
+        if (answer === 'True')
+            return INTEGRITY_HIGH;
+        if (answer === 'False')
+            return INTEGRITY_MEDIUM;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Reads the integrity level out of text by SID. Exported for the check. */
+export function elevationFrom(groups) {
+    if (!groups)
+        return null;
+    if (groups.includes(INTEGRITY_SYSTEM) || groups.includes(INTEGRITY_HIGH))
+        return true;
+    if (groups.includes(INTEGRITY_MEDIUM) || groups.includes(INTEGRITY_LOW))
+        return false;
+    return null;
+}
+export function readIsolationSignals(env = process.env, groups = elevationProbe, fresh = false) {
+    if (cached && !fresh)
+        return cached;
+    const user = env.USERNAME ?? '(unknown)';
+    cached = {
+        user,
+        computer: env.COMPUTERNAME ?? '(unknown)',
+        elevated: elevationFrom(groups()),
+        windowsSandbox: user.toLowerCase() === SANDBOX_USER,
+    };
+    return cached;
+}
+/** For tests, which supply their own environment and must not read a cached answer. */
+export function forgetIsolationSignals() {
+    cached = null;
+}
+/**
+ * The posture: the claim, the signals, and every way the two of them are worth remarking on.
+ *
+ * A contradiction is reported rather than resolved. If the operator says "sandbox" and the account
+ * is not the sandbox's, this does not decide which is true — it says they disagree, because one of
+ * them is wrong and only a person can say which.
+ */
+export function assessIsolation(claim, signals) {
+    const warnings = [];
+    if (claim === 'none' || claim === 'none-accepted') {
+        warnings.push('this run is not isolated: commands written by the model run as the ordinary user, with that ' +
+            "user's files, tokens and network access. Set execution.isolation once you have arranged a " +
+            'separate low-privilege account, Windows Sandbox or a VM.');
+    }
+    if (claim === 'none-accepted') {
+        warnings.push('the operator has accepted unattended runs without isolation: a run with nobody watching may go ahead ' +
+            'here, and nothing but the allowlist and the refusal rules limits what its steps reach.');
+    }
+    if (signals.elevated === true) {
+        warnings.push('this process is running elevated (High or System integrity), so every command it runs is ' +
+            'elevated too. Nothing this runner does needs administrator rights; start it as an ordinary user.');
+    }
+    if (signals.elevated === null) {
+        warnings.push('whether this process is elevated could not be determined, so treat it as possibly elevated.');
+    }
+    if (claim === 'sandbox' && !signals.windowsSandbox) {
+        warnings.push(`execution.isolation says "sandbox", but this process is running as ${signals.user}, which is not ` +
+            "Windows Sandbox's own account. One of the two is wrong.");
+    }
+    if (claim === 'separate-account' && signals.windowsSandbox) {
+        warnings.push('execution.isolation says "separate-account", but this is Windows Sandbox. Say "sandbox" instead.');
+    }
+    return { claim, signals, warnings };
+}
+/**
+ * Why an unattended run may not start here, or null.
+ *
+ * Nobody watching and nothing containing is the one combination this refuses outright. Either
+ * side of it alone is a decision somebody can defend; together they are the arrangement that had
+ * a security team asking whether an automation tool had been compromised, and the honest answer
+ * at the time was that nothing would have looked any different if it had.
+ */
+export function unattendedIsolationRefusal(mode, claim) {
+    if (mode !== 'unattended')
+        return null;
+    if (claim !== 'none')
+        return null;
+    return ('refused: an unattended run needs somewhere to run. With execution.isolation set to "none" there is ' +
+        'nobody watching the steps and nothing limiting what they reach, which is the one combination this ' +
+        'runner will not start. Run this task in confirm mode, or set execution.isolation once the bot has a ' +
+        'separate low-privilege account, Windows Sandbox or a VM of its own — or, if you accept the risk, to ' +
+        '"none-accepted" ("This account — I accept unattended runs without isolation" in Settings).');
+}
+/** The posture as lines for the task log and `cop doctor`. */
+export function describeIsolation(p) {
+    return [
+        `claimed     : ${p.claim}${p.claim === 'none'
+            ? ' (the operator has not arranged any)'
+            : p.claim === 'none-accepted'
+                ? ' (none arranged; the operator accepts unattended runs anyway)'
+                : ''}`,
+        `account     : ${p.signals.user} on ${p.signals.computer}${p.signals.windowsSandbox ? ' (Windows Sandbox)' : ''}`,
+        `elevated    : ${p.signals.elevated === null ? 'could not be determined' : p.signals.elevated ? 'YES — every command runs elevated' : 'no'}`,
+        ...(p.warnings.length ? ['concerns    :', ...p.warnings.map((w) => `  - ${w}`)] : ['concerns    : none']),
+    ].join('\n');
+}

package/dist/src/exec/network.js

@@ -0,0 +1,242 @@
+/**
+ * Commands that fetch something from the network, and why they never run on their own.
+ *
+ * The operator's rule, stated on 2026-09-27: the bot does not download files. Not because a
+ * download is dangerous in itself, but because of what comes after it. A step that saves
+ * `https://somewhere/tool.zip` into the project is harmless on the line where it happens; the
+ * *next* step, written by the same chat a minute later, can unpack and run it, and by then the
+ * thing that runs arrived from outside the conversation, was read by nobody, and is exactly the
+ * shape a security team calls a loader. `dangerous.ts` already refuses the one-line form
+ * (`iwr … | iex`); this is about the two-step form, which no single line gives away.
+ *
+ * So a step that fetches is not refused and not run: it is **held for the operator**. It goes to
+ * the approval screen ("A step is waiting for your decision") in every mode, *including* an
+ * unattended run and a run switched to "run the rest without asking", because those are exactly
+ * the runs in which nobody would otherwise see it. Where there is no one to ask — the CLI's
+ * unattended mode has no screen — it is refused instead, with the reason. See `authorizer.ts`.
+ *
+ * What is on the list, and what is deliberately not:
+ *
+ *   on it    `Invoke-WebRequest`/`iwr`, `Invoke-RestMethod`/`irm`, `curl`, `wget`,
+ *            `Start-BitsTransfer` (and the `BitsTransfer` module), .NET's `WebClient`,
+ *            `HttpClient` and `WebRequest`, and the file-transfer programs `ftp`, `tftp`, `sftp`,
+ *            `scp` and `aria2c`. `bitsadmin` and `certutil -urlcache` are here too in spirit, but
+ *            `dangerous.ts` refuses them outright first, which is stronger.
+ *   not      `npm`, `pnpm`, `yarn`, `dotnet restore`, `pip` into a `.venv`, `mvn`, `gradle`,
+ *            `cargo`, `go`, `git fetch`/`pull`. They fetch too, but they fetch *packages*, the
+ *            project's declared dependencies, by the project's own mechanism, from registries the
+ *            project already trusts, and refusing them would stop every build. The operator decided
+ *            that line (2026-09-27); moving it is their call, not this file's.
+ *
+ * One exception, and why: a request whose every target is **this machine** — `localhost`,
+ * `127.0.0.1`, `[::1]` — is not a download. `curl http://localhost:3000/health` is how a task
+ * proves the server it started actually answers, and nothing comes back that the project did not
+ * itself produce. Holding every health check for approval would turn an unattended run into one
+ * that waits all night on its first test. The exception is narrow on purpose: every `http(s)://`
+ * address in the command must be loopback, there must be at least one, and nothing else in the
+ * command may look like a host — a bare `example.com` or `10.0.0.5` beside a localhost URL still
+ * holds the step, because `iwr` accepts an address without a scheme.
+ *
+ * The same text is screened whole, not command by command. That is deliberate and it is what
+ * closes the obvious way round: writing `Invoke-WebRequest …` into a `.ps1` with `Set-Content` and
+ * running the file in the next step. The `Set-Content` step carries the words, so it is the one
+ * held, and the operator sees the script before it exists.
+ *
+ * The honest limit, the same one every rule in this folder states: this is not a boundary. A
+ * program the project itself contains can open a socket — a Node script that calls `fetch()` is
+ * ordinary application code and nothing here can tell it from a download. What this does is keep
+ * the *ordinary* way of downloading, the one a chat reaches for first, in front of a person.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { botRootDir } from './workDir.js';
+const FETCHERS = [
+    { name: 'Invoke-WebRequest', pattern: /\b(Invoke-WebRequest|iwr)\b/i },
+    { name: 'Invoke-RestMethod', pattern: /\b(Invoke-RestMethod|irm)\b/i },
+    { name: 'curl', pattern: /\bcurl(\.exe)?\b/i },
+    { name: 'wget', pattern: /\bwget2?(\.exe)?\b/i },
+    { name: 'Start-BitsTransfer', pattern: /\b(Start-BitsTransfer|BitsTransfer)\b/i },
+    // .NET's own clients, however they are spelled: `New-Object Net.WebClient`,
+    // `[System.Net.Http.HttpClient]::new()`, `[Net.WebRequest]::Create(...)`.
+    { name: '.NET web client', pattern: /\b(WebClient|HttpClient|HttpWebRequest|WebRequest)\b/i },
+    // Requires something after the name, so that the word in prose or a path segment is not a hit.
+    { name: 'file transfer', pattern: /\b(s?ftp|tftp|scp|aria2c)(\.exe)?\s+\S/i },
+    /*
+     * Package managers fetching something that is not a package from the project's registry: a
+     * package named by URL or by a git address, a runner (`npx`, `pnpm dlx`, `bunx`) given a package
+     * that is not installed in the project, a Go module run by address, a container image. Each
+     * downloads code and runs it in the same breath, which is the two-step form in one step.
+     * `npx <installed tool>` is the ordinary way to run a project's own tools and is not held: whether
+     * the tool is installed is checked on disk (`installedInProject`).
+     */
+    {
+        name: 'a package from a URL or a repository',
+        pattern: /\b(npm|pnpm|yarn|bun|pip3?|uv|poetry)(\.cmd|\.exe)?\s+(install|add|i)\b[^|;\n]*?(https?:\/\/|git\+|github:|gitlab:|bitbucket:|git:\/\/|ssh:\/\/|git@)/i,
+        instead: "name the package as the registry knows it, or say in `notes` what is needed and end `blocked`",
+    },
+    {
+        name: 'a package runner fetching a package',
+        // Any argument at all, flags included: whether the tool is installed decides, not the spelling.
+        pattern: /\b(npx|pnpx|bunx)(\.cmd|\.exe)?\s+\S|\b(pnpm|yarn)(\.cmd)?\s+dlx\s+|\bnpm(\.cmd)?\s+exec\s+/i,
+        instead: 'install the tool into the project first (`npm install -D <tool>`); a tool that is installed is run without asking',
+    },
+    { name: 'go run of a module by address', pattern: /\bgo(\.exe)?\s+run\s+\S+@/i, instead: 'add the module to go.mod and run it from there' },
+    {
+        name: 'a container image',
+        pattern: /\bdocker(\.exe)?\s+(pull|run|create|build)\b|\bdocker(\.exe)?\s+compose\s+(up|run|build|pull)\b/i,
+        instead: 'say in `notes` which image is needed; the operator pulls it',
+    },
+];
+/**
+ * Whether the tool `npx` (or its kin) is asked to run is already installed in the project, found by
+ * walking up from `cwd` the way npx itself does. Absent, npx downloads it — and that is the case
+ * that waits for the operator.
+ */
+function installedInProject(command, cwd) {
+    if (!cwd)
+        return false;
+    const m = /\b(?:npx|pnpx|bunx)(?:\.cmd|\.exe)?\s+(?:(?:--yes|-y|--no|--quiet|-q)\s+)*(?:(?:-p|--package)\s+\S+\s+)*(?:"([^"]+)"|'([^']+)'|(\S+))/i.exec(command)
+        ?? /\b(?:pnpm|yarn)(?:\.cmd)?\s+dlx\s+(?:"([^"]+)"|'([^']+)'|(\S+))/i.exec(command)
+        ?? /\bnpm(?:\.cmd)?\s+exec\s+(?:--\s+)?(?:"([^"]+)"|'([^']+)'|(\S+))/i.exec(command);
+    if (!m)
+        return false;
+    if (/\s(-p|--package)\s/i.test(command))
+        return false;
+    const spec = (m[1] ?? m[2] ?? m[3] ?? '').trim();
+    if (!spec || spec.startsWith('-'))
+        return false;
+    // `tsx@4.19` names a version; `@scope/name` starts with `@`. Strip a trailing version only.
+    const name = spec.startsWith('@') ? spec.replace(/(.)@[^@]*$/, '$1') : spec.replace(/@.*$/, '');
+    if (/[\\/:]/.test(name.replace(/^@[^/]+\//, '')))
+        return false;
+    const bin = name.startsWith('@') ? name.split('/')[1] ?? '' : name;
+    let dir = resolve(cwd);
+    for (let i = 0; i < 12; i += 1) {
+        const modules = join(dir, 'node_modules');
+        if (existsSync(join(modules, name, 'package.json')) || existsSync(join(modules, '.bin', `${bin}.cmd`)) || existsSync(join(modules, '.bin', bin)))
+            return true;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return false;
+}
+/** Hosts that are this machine. Anything else is somewhere else. */
+function isLoopback(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, '');
+    return h === 'localhost' || h.endsWith('.localhost') || /^127(\.\d{1,3}){3}$/.test(h) || h === '::1';
+}
+/**
+ * Extensions a bare `name.ext` token carries when it is a file rather than a host. Only used to
+ * decide whether a token beside a loopback URL looks like a *second* address; a file named here is
+ * an argument (`-OutFile health.json`), a token not named here is treated as a host, which is the
+ * safe direction to be wrong in: the step is held, not run.
+ */
+const FILE_EXTENSIONS = new Set([
+    'json', 'txt', 'log', 'md', 'html', 'htm', 'xml', 'csv', 'yml', 'yaml', 'toml', 'ini', 'cfg', 'conf',
+    'js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx', 'css', 'map', 'ps1', 'psm1', 'cs', 'py', 'java', 'go', 'rs',
+    'png', 'jpg', 'jpeg', 'gif', 'svg', 'ico', 'webp', 'pdf', 'out', 'tmp', 'bak', 'lock',
+    'exe', 'cmd', 'bat', 'dll', 'tar', 'gz', 'tgz',
+]);
+/**
+ * Whether every place this command could reach is this machine. True only when it names at least
+ * one `http(s)://` address, all of them loopback, and no other token that reads as a host or an IP.
+ */
+export function onlyLoopbackTargets(command) {
+    const urls = [...command.matchAll(/\b[a-z][a-z0-9+.-]*:\/\/(\[[^\]]+\]|[^\/\s:'"`;|)]+)/gi)];
+    if (urls.length === 0)
+        return false;
+    if (!urls.every((m) => isLoopback(m[1])))
+        return false;
+    const rest = command.replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, ' ');
+    for (const token of rest.split(/[\s'"`=,;|(){}]+/)) {
+        const bare = token.replace(/^-+/, '').replace(/[:\/].*$/, '');
+        if (!bare)
+            continue;
+        if (/^\d{1,3}(\.\d{1,3}){3}$/.test(bare) && !isLoopback(bare))
+            return false;
+        const labels = bare.split('.');
+        if (labels.length < 2 || labels.some((l) => l === ''))
+            continue;
+        const last = labels[labels.length - 1].toLowerCase();
+        if (!/^[a-z]{2,}$/.test(last))
+            continue;
+        if (FILE_EXTENSIONS.has(last))
+            continue;
+        // PowerShell member access on a variable or a type (`$r.StatusCode`, `System.Net`) is not a host.
+        if (token.startsWith('$') || token.startsWith('['))
+            continue;
+        if (/^(system|microsoft|net)$/i.test(labels[0]))
+            continue;
+        if (isLoopback(bare))
+            continue;
+        return false;
+    }
+    return true;
+}
+/**
+ * Why this command must be shown to the operator before it runs, or null.
+ *
+ * The sentence is the one the approval screen and the log print, and — when there is nobody to
+ * ask — the one the chat receives, so it says what was recognised and what to do instead.
+ */
+export function networkFetchReason(command, cwd) {
+    const hit = FETCHERS.find((f) => f.pattern.test(command));
+    if (!hit)
+        return null;
+    if (hit.name === 'a package runner fetching a package' && installedInProject(command, cwd))
+        return null;
+    if (onlyLoopbackTargets(command))
+        return null;
+    return (`fetches from the network (${hit.name}). The bot does not download files on its own, because a later ` +
+        'step could run what arrived; this step waits for the operator to allow it. Requests to this machine ' +
+        '(localhost, 127.0.0.1) are not held. Packages come in through the project\'s own tools (npm, dotnet, ' +
+        'pip into a .venv), which are not held either.' +
+        (hit.instead ? ` Instead: ${hit.instead}.` : ''));
+}
+/**
+ * The bot's own API and UI, and the file that holds their key. The loopback exemption above exists
+ * so a task can check a server *it* started; it must not become the way a step reaches the process
+ * that approves its steps. Found on 2026-09-27: with the token in its environment, a step could call
+ * `127.0.0.1:4000` and answer its own held download. The token is no longer passed (`stepEnv.ts`);
+ * this refuses the attempt as well, so a step that goes looking gets a reason instead of a 401.
+ */
+export function botSelfRefusal(command, ports = botPorts(), root = botRootDir()) {
+    const port = `(?:${ports.map((p) => String(Math.trunc(p))).join('|')})`;
+    const host = String.raw `(?:localhost|127(?:\.\d{1,3}){3}|\[::1\]|0\.0\.0\.0|::1)`;
+    // The folders the bot keeps its records in, by path: its data, its runs, its update backups.
+    const folded = command.replace(/\//g, '\\').toLowerCase();
+    const own = root.replace(/\//g, '\\').toLowerCase().replace(/\\+$/, '');
+    const reachesRecords = ['data', 'runs', 'data-backups'].some((d) => folded.includes(`${own}\\${d}`));
+    /*
+     * Installed from npm, the bot is a dependency of the very project it works on: its code sits in
+     * the project's `node_modules`, its records in the project's `.copilot-operator`, and both are
+     * inside the folders a step may write. A step that edited the bot's code or contract, or swapped
+     * its version, would be changing what runs the next task. So the bot's folders are refused by any
+     * spelling of the path, and so is installing, updating or removing the bot as a package.
+     */
+    const reachesPackage = /node_modules[\\/]+(?:@[^\\/\s]+[\\/]+)?copilot-operator(?![\w-])/i.test(command) ||
+        /(?:^|[\s'"`=(\\/,;])\.copilot-operator(?:[\\/\s'"`;|)]|$)/i.test(command) ||
+        /\b(?:npm|pnpm|yarn|bun)(?:\.cmd|\.exe)?\b[^|;\n]*\b(?:i|install|add|ci|un|uninstall|remove|rm|r|update|up|upgrade|link|ln)\b[^|;\n]*(?:^|\s|@[^\s/]+\/)copilot-operator(?![\w-])/i.test(command);
+    if (reachesPackage) {
+        return ("refused: this reaches the bot's own package — its code in node_modules, its records in .copilot-operator, or " +
+            'its installation. The bot that runs the task is not part of the work; leave both folders and the dependency alone.');
+    }
+    if (reachesRecords || new RegExp(String.raw `${host}\s*:\s*${port}(?!\d)`, 'i').test(command) || /\bapi-token\b|\bdev-pids\.json\b/i.test(command)) {
+        return ('refused: this reaches the bot itself — its API, its web page or its key. A task works on its own project; ' +
+            'the bot that runs it is not part of the work. Use a different port for a server the task starts.');
+    }
+    return null;
+}
+/** The ports the bot's API and web page listen on. */
+export function botPorts(env = process.env) {
+    const api = Number(env.COP_API_PORT ?? 4000);
+    return [...new Set([Number.isFinite(api) ? api : 4000, 4000, 3210])];
+}
+/** What the chat is told when a fetch was held and nobody was there to allow it. */
+export function networkFetchRefusal(reason) {
+    return (`refused: ${reason} This run has nobody to approve it, so it was not run. Do the work without ` +
+        'downloading — write what is needed into the project with a command step, or install it with the ' +
+        "project's package manager — or say in `notes` what must be fetched and end `blocked`.");
+}