copilot-operator 0.1.0

package/dist/src/exec/shells.js

@@ -0,0 +1,298 @@
+/**
+ * Which Windows shell a command is handed to, decided in one place for everything that runs.
+ *
+ * This module exists because the runner had four opinions about shells and no way to reconcile
+ * them. A step carried whatever the parser had filled in, a check fell back to `pwsh` in
+ * `checks.ts`, the policy gate assumed `pwsh` while it screened a command for traps, and the
+ * runner itself turned all of that into a bare `pwsh.exe` for `spawn`. On the machine the bot
+ * was written on those four opinions happened to agree, so nothing ever disagreed loudly enough
+ * to be noticed. On a second Windows machine, which has Windows PowerShell and `cmd` but no
+ * PowerShell 7, every one of them resolved to an executable that is not there: the tasks and
+ * the post-task checks died of `spawn ENOENT` while the very same commands ran perfectly
+ * through `cmd`, and the task spent its retry rounds asking a language model to fix an
+ * interpreter it cannot install.
+ *
+ * So the knowledge of what a shell is called, where it lives and how it is invoked is gathered
+ * here, and two questions are kept deliberately apart. `resolveShell` answers the executable
+ * question — may this run, and with what — and it is allowed to refuse; a shell that was asked
+ * for by name and is not installed is a configuration fault, reported as one, and never quietly
+ * swapped for a different interpreter that would read the same command differently.
+ * `effectiveShell` answers the cheaper question of which shell a command will be read by, which
+ * is what a label in the log and the syntax-trap screen need, and it never refuses.
+ *
+ * Nothing is substituted behind anybody's back, but a machine that has a usable shell does get
+ * to use it: when nothing named a shell, the fallback order is PowerShell 7, then Windows
+ * PowerShell, then `cmd`, because that is the order of how much of what this bot sends will
+ * actually be understood.
+ *
+ * Detection is a set of file-system lookups rather than a set of child processes, so it costs
+ * nothing to do at the start of a run, and it is cached like the rest of the environment probes
+ * for the same reason they are: a shell does not appear halfway through a task.
+ */
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+/**
+ * The order a command that named no shell is offered to them in.
+ *
+ * Most of what reaches this runner is PowerShell, written by a model that was asked for
+ * PowerShell, so the two PowerShells come first and the more capable one comes before the
+ * older one. `cmd` is last and is a genuine last resort: it is on every Windows machine ever
+ * made, which is the only reason it is in the list at all.
+ */
+export const SHELL_ORDER = ['pwsh', 'powershell', 'cmd'];
+/** What each shell is called on disk. */
+const EXECUTABLE = {
+    pwsh: 'pwsh.exe',
+    powershell: 'powershell.exe',
+    cmd: 'cmd.exe',
+};
+/** What to tell somebody whose machine does not have one, as the second half of a sentence. */
+const REMEDY = {
+    pwsh: 'install PowerShell 7 (winget install Microsoft.PowerShell)',
+    powershell: 'repair the Windows PowerShell that ships with Windows',
+    cmd: 'repair the Windows installation; cmd.exe is part of it',
+};
+let cached = null;
+/** The usual places a shell sits when PATH has been trimmed or has not been inherited. */
+function wellKnownPaths(shell, env) {
+    const programFiles = env.ProgramFiles ?? 'C:\\Program Files';
+    const systemRoot = env.SystemRoot ?? env.windir ?? 'C:\\Windows';
+    switch (shell) {
+        case 'pwsh':
+            // 7 first: a machine with both is a machine that installed 7 on purpose.
+            return [join(programFiles, 'PowerShell', '7', 'pwsh.exe'), join(programFiles, 'PowerShell', '6', 'pwsh.exe')];
+        case 'powershell':
+            return [join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')];
+        case 'cmd':
+            return [join(systemRoot, 'System32', 'cmd.exe')];
+    }
+}
+/**
+ * Looks one shell up the way the operating system would, and then in the places it lives.
+ *
+ * PATH is walked by hand rather than asked of `where.exe`, because this runs at the start of
+ * every run and a file-system lookup costs nothing next to a child process — and because a
+ * machine whose PATH is broken is exactly the machine this is trying to help.
+ */
+function findOnDisk(shell, env = process.env) {
+    const exe = EXECUTABLE[shell];
+    const path = env.PATH ?? env.Path ?? '';
+    for (const dir of path.split(delimiter)) {
+        // A PATH entry may be quoted, and a quoted directory joined as-is finds nothing.
+        const clean = dir.trim().replace(/^"|"$/g, '');
+        if (!clean)
+            continue;
+        const candidate = join(clean, exe);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    for (const candidate of wellKnownPaths(shell, env)) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * What this machine has, collected once and reused.
+ *
+ * `fresh` re-probes, the way the environment manifest does. `probe` replaces the lookup
+ * altogether and also replaces what is cached, which is how a test describes a machine that is
+ * not this one — a machine without PowerShell 7 cannot otherwise be reasoned about from a
+ * machine that has it, and installing and uninstalling an interpreter to make a point is not a
+ * test, it is an afternoon.
+ */
+export function detectShells(opts = {}) {
+    if (cached && !opts.fresh && !opts.probe)
+        return cached;
+    const probe = opts.probe ?? ((shell) => findOnDisk(shell));
+    cached = {
+        detectedAt: new Date().toISOString(),
+        found: {
+            pwsh: probe('pwsh'),
+            powershell: probe('powershell'),
+            cmd: probe('cmd'),
+        },
+    };
+    return cached;
+}
+/** An inventory of exactly the shells named, for a caller that already knows what is there. */
+export function inventoryOf(found) {
+    return detectShells({ probe: (shell) => found[shell] ?? null });
+}
+/** The shells this machine has, in the order a command that named none is offered to them. */
+export function availableShells(inventory = detectShells()) {
+    return SHELL_ORDER.filter((shell) => inventory.found[shell]);
+}
+function problemFor(requested, inventory) {
+    const available = availableShells(inventory);
+    const here = available.length > 0 ? `what this machine has is ${available.join(', ')}` : 'this machine appears to have no shell at all';
+    const message = requested === null
+        ? `no Windows shell was found on this machine: none of ${SHELL_ORDER.map((s) => EXECUTABLE[s]).join(', ')} is on PATH or in its usual place. ` +
+            'Nothing can be run until one of them is.'
+        : `${EXECUTABLE[requested]} is not on this machine, and it was asked for by name, so nothing was substituted for it. ` +
+            `To run this, ${REMEDY[requested]}, or ask for one of the shells that are here instead — ${here}. ` +
+            'A step or a check names its shell in "shell"; the standing default is execution.defaultShell in the config.';
+    return { requested, available, message };
+}
+/**
+ * Which shell something runs in, and whether it may run at all.
+ *
+ * A named shell is honoured or refused, never exchanged: a command written for PowerShell and
+ * quietly handed to `cmd` does not fail, it does something else, and finding that out from a
+ * task's output costs more than the refusal ever would. A command that named no shell takes
+ * the first shell this machine has, in `SHELL_ORDER`.
+ */
+export function resolveShell(requested, inventory = detectShells()) {
+    if (requested) {
+        const path = inventory.found[requested];
+        return path
+            ? { ok: true, resolved: { requested, shell: requested, path } }
+            : { ok: false, problem: problemFor(requested, inventory) };
+    }
+    const shell = availableShells(inventory)[0];
+    return shell
+        ? { ok: true, resolved: { requested: null, shell, path: inventory.found[shell] } }
+        : { ok: false, problem: problemFor(null, inventory) };
+}
+/**
+ * The same refusal, addressed to the chat instead of to the operator.
+ *
+ * `problemFor` writes for a person: install PowerShell 7, or set `execution.defaultShell`. Both
+ * are true and neither is anything a language model can do, and this runner already knows what
+ * happens when a model is handed an instruction it cannot carry out — it tries something else,
+ * fails the same way, and spends the round. So a step refused for its shell gets the half of the
+ * fact it can act on: what is here, and what to write instead.
+ *
+ * `fallback` is the shell a step that names none actually gets, which is not always the first one
+ * the machine has: `execution.defaultShell` decides it whenever the machine has that shell. The
+ * two have to be named by the same value or the message offers a choice between two things it
+ * calls equivalent and are not.
+ */
+export function refusalForChat(problem, fallback) {
+    if (problem.available.length === 0) {
+        return ('this machine has no Windows shell the runner can find, so nothing can be run on it at all. ' +
+            'Do not send more steps: end the task with status "blocked" and say that the machine has no shell.');
+    }
+    const use = fallback && problem.available.includes(fallback) ? fallback : problem.available[0];
+    const named = problem.requested ? `\`${problem.requested}\` is not installed on this machine` : 'the shell this step asked for is not installed on this machine';
+    return (`${named}, and nothing was substituted for it, because a command written for one shell and read by ` +
+        `another does not fail — it does something else. This machine has ${problem.available.map((s) => `\`${s}\``).join(' and ')}. ` +
+        `Send this step again with \`"shell": "${use}"\`, or leave \`shell\` out and the runner uses \`${use}\`, and write the ` +
+        `command for that shell. Do not ask for anything to be installed: nothing in this conversation can install it.`);
+}
+/**
+ * Which shell a command will be read by, for a label or for a screen of its syntax.
+ *
+ * Never refuses, because neither of those callers is about to start a process: describing a
+ * step in the log and deciding whether a command contains a trap both need a name, and a name
+ * they can always be given. Whether the thing may actually run is `resolveShell`'s question.
+ *
+ * A shell that was named and is not installed keeps its name here rather than falling through
+ * the order. It is not going to run in anything, so the honest label is the one that says what
+ * was asked for — which is also what the refusal, when it comes, will be about.
+ */
+export function effectiveShell(requested, inventory = detectShells()) {
+    const choice = resolveShell(requested, inventory);
+    return choice.ok ? choice.resolved.shell : (requested ?? SHELL_ORDER[0]);
+}
+/**
+ * The standing default, checked against what is here.
+ *
+ * `execution.defaultShell` is a preference and not an instruction: nothing wrote it for this
+ * task, it is what a step or a check gets when it says nothing at all, and a machine that has
+ * not got it should fall through the order rather than fail every command with a spawn error.
+ * A shell a reply or a plan named for itself goes through `resolveShell` and is never treated
+ * this way.
+ */
+export function preferredShell(configured, inventory = detectShells()) {
+    return inventory.found[configured] ? configured : (availableShells(inventory)[0] ?? configured);
+}
+/**
+ * What the chat is told about this machine's shells, or nothing when there is nothing to say.
+ *
+ * The contract in `prompts/level1.md` shows `"shell": "pwsh"` in its one worked example, and a
+ * model writing to an example copies the example. On the machine the bot was written on that is
+ * harmless, because `pwsh` is there. On a machine with only Windows PowerShell it is the whole
+ * problem: every first reply names an interpreter that does not exist, every step is refused, and
+ * a round is spent discovering something the runner knew before the conversation opened.
+ *
+ * So it is said up front — but only when it is not already true. A machine with PowerShell 7 gets
+ * no note at all, which is deliberate: the contract is already right there, and a paragraph
+ * repeating it is a paragraph of context spent saying nothing.
+ */
+export function shellNote(inventory = detectShells(), fallback) {
+    if (inventory.found.pwsh)
+        return undefined;
+    const available = availableShells(inventory);
+    const lines = available.length === 0
+        ? [
+            '## Shells on this machine',
+            '',
+            'This machine has none of pwsh.exe, powershell.exe or cmd.exe where the runner can find them.',
+            'No command can be run until that is fixed. End the task with status "blocked", and fill',
+            '"tried" — the format wants two entries there — with what you attempted and this refusal.',
+        ]
+        : (() => {
+            const chosen = fallback && inventory.found[fallback] ? fallback : available[0];
+            return [
+                '## Shells on this machine',
+                '',
+                `**PowerShell 7 (\`pwsh\`) is not installed here.** This machine has ${available.map((s) => `\`${s}\``).join(' and ')}.`,
+                `A step that names \`"shell": "pwsh"\` is refused and has to be written again, so do not name it:`,
+                `write \`"shell": "${chosen}"\`, or leave \`shell\` out, and the runner uses \`${chosen}\`.`,
+                '',
+                chosen === 'cmd'
+                    ? 'Write the commands for `cmd` rather than for PowerShell: no cmdlets, no pipelines of objects, no `$PSVersionTable`.'
+                    : 'Windows PowerShell 5.1 is not PowerShell 7: no `??`, no `?.`, no ternary operator, and `Invoke-RestMethod` behaves differently.',
+            ];
+        })();
+    return lines.join('\n');
+}
+/**
+ * How one shell is asked to run one command.
+ *
+ * The flags are not incidental: no profile so that a machine's own startup script cannot change
+ * what a step does, and non-interactive so that a prompt is an error rather than a hang.
+ *
+ * No `-ExecutionPolicy` at all, since 2026-09-27. It was `Bypass` for the file steps that no longer
+ * exist, then `RemoteSigned` for a day. The operator's decision: the machine's own policy applies,
+ * whatever it is. On a company laptop that policy is set by the administrators, and a process that
+ * overrides it on every command line — even to a value they would agree with — is exactly the
+ * process their tooling is told to look at; and a policy the runner cannot change is one more thing
+ * a security review can take at face value. The cost is on a machine set to `Restricted` or
+ * `AllSigned`: the `.ps1` shims that npm and its kin install are then refused, and the chat is told
+ * (in the contract) to call the `.cmd` form of the tool instead.
+ */
+export function invocationFor(resolved, command, scriptArgs) {
+    const isScript = Array.isArray(scriptArgs);
+    switch (resolved.shell) {
+        case 'pwsh':
+        case 'powershell': {
+            const base = ['-NoProfile', '-NonInteractive'];
+            return isScript
+                ? { file: resolved.path, args: [...base, '-File', command, ...(scriptArgs ?? [])] }
+                : { file: resolved.path, args: [...base, '-Command', command] };
+        }
+        case 'cmd':
+            return isScript
+                ? { file: resolved.path, args: ['/d', '/c', command, ...(scriptArgs ?? [])] }
+                : { file: resolved.path, args: ['/d', '/s', '/c', command] };
+    }
+}
+/**
+ * A shell that was found at detection time and would not start when it was wanted.
+ *
+ * Rare and worth saying plainly: an interpreter that was uninstalled during the run, a PATH
+ * entry pointing at a folder that has gone, an antivirus holding the file. It is the same class
+ * of fault as a missing shell — the machine, not the work — so it is reported the same way.
+ */
+export function missingShellProblem(resolved, inventory = detectShells()) {
+    const others = availableShells(inventory).filter((s) => s !== resolved.shell);
+    return {
+        requested: resolved.requested,
+        available: availableShells(inventory),
+        message: `${resolved.path} would not start, although ${EXECUTABLE[resolved.shell]} was found there when this run began. ` +
+            `Check that it is still installed and still on PATH${others.length > 0 ? `, or run this in ${others.join(' or ')} instead` : ''}. ` +
+            `If it has gone, ${REMEDY[resolved.shell]}.`,
+    };
+}

package/dist/src/exec/stepEnv.js

@@ -0,0 +1,72 @@
+/**
+ * The environment a command step is started with — named, not inherited.
+ *
+ * Steps used to be given the bot's whole environment. Found on 2026-09-27: that included the API
+ * token (put there by `npm start` for the web build), so a model-written step could read it and
+ * call the API that approves its own held steps, switches a run to unattended and edits the deny
+ * list. It also carried whatever else the operator's shell happened to hold — cloud keys, CI tokens
+ * — to be printed into a results file that goes to the chat.
+ *
+ * So a step gets the variables Windows and the toolchains need to work, by name, and nothing else:
+ * the system folders and the user's profile folders (npm, dotnet and pip keep their caches there),
+ * `PATH`, the processor facts some builds read, the toolchain homes, and the proxy and certificate
+ * settings a company network needs for `npm install` to reach its registry. `PSModulePath` is left
+ * out on purpose — see `winps.ts` for what it breaks in Windows PowerShell. Anything a project truly
+ * needs beyond this is named by the operator in `execution.passEnv`.
+ *
+ * And three are set, not passed:
+ *
+ *   npm_config_ignore_scripts=true   `npm install` no longer runs the install scripts of what it
+ *   YARN_ENABLE_SCRIPTS=0            downloads. A package's `postinstall` is code fetched from a
+ *                                    registry and executed with nobody reading it — exactly the
+ *                                    download-then-run the operator ruled out (2026-09-27). The
+ *                                    honest cost: packages that build something when installed
+ *                                    (esbuild, sharp, Playwright's browsers) may not work until the
+ *                                    operator installs them by hand.
+ *   NEXT_TELEMETRY_DISABLED=1        a Next.js project's build would otherwise report to a third
+ *                                    party from this machine.
+ */
+/** Passed through when present, compared without regard to case as Windows does. */
+const PASSED = [
+    // Windows itself
+    'SystemRoot', 'SystemDrive', 'windir', 'ComSpec', 'PATH', 'PATHEXT', 'OS',
+    'PROCESSOR_ARCHITECTURE', 'PROCESSOR_IDENTIFIER', 'PROCESSOR_LEVEL', 'PROCESSOR_REVISION', 'NUMBER_OF_PROCESSORS',
+    'ProgramData', 'ProgramFiles', 'ProgramFiles(x86)', 'ProgramW6432',
+    'CommonProgramFiles', 'CommonProgramFiles(x86)', 'CommonProgramW6432', 'ALLUSERSPROFILE', 'PUBLIC',
+    // the user's folders, where toolchains keep caches and settings
+    'USERPROFILE', 'USERNAME', 'USERDOMAIN', 'COMPUTERNAME', 'HOMEDRIVE', 'HOMEPATH', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP',
+    // toolchain homes
+    'JAVA_HOME', 'DOTNET_ROOT', 'GOROOT', 'GOPATH', 'CARGO_HOME', 'RUSTUP_HOME', 'NVM_HOME', 'NVM_SYMLINK', 'PNPM_HOME',
+    // a company network: the proxy and the company's own certificate authority
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'REQUESTS_CA_BUNDLE', 'PIP_INDEX_URL',
+    // language and time, so output reads the same as at the operator's own prompt
+    'LANG', 'LC_ALL', 'TZ',
+];
+/** Names that pass whatever they are called: a toolchain's telemetry switch is always the operator's to set. */
+const PASSED_BY_SHAPE = /telemetry|_optout$|^do_not_track$|_nologo$/i;
+const FORCED = {
+    NO_COLOR: '1',
+    TERM: 'dumb',
+    npm_config_ignore_scripts: 'true',
+    YARN_ENABLE_SCRIPTS: '0',
+    // No toolchain reports home from a step: a company's opt-outs, set for every build tool that
+    // honours them, so that the step's own traffic is the project's and nothing else.
+    NEXT_TELEMETRY_DISABLED: '1',
+    DOTNET_CLI_TELEMETRY_OPTOUT: '1',
+    DOTNET_NOLOGO: '1',
+    POWERSHELL_TELEMETRY_OPTOUT: '1',
+    DO_NOT_TRACK: '1',
+};
+/** Names a step must never be given, even if the operator lists them: the bot's own keys. */
+const NEVER = /^(NEXT_PUBLIC_COP_|COP_)/i;
+export function stepEnvironment(from = process.env, extra = []) {
+    const wanted = new Set([...PASSED, ...extra].map((n) => n.toLowerCase()));
+    const out = {};
+    for (const [k, v] of Object.entries(from)) {
+        if (v === undefined || NEVER.test(k))
+            continue;
+        if (wanted.has(k.toLowerCase()) || PASSED_BY_SHAPE.test(k))
+            out[k] = v;
+    }
+    return { ...out, ...FORCED };
+}

package/dist/src/exec/winps.js

@@ -0,0 +1,17 @@
+/**
+ * The environment the bot's own Windows PowerShell calls are started with.
+ *
+ * Found on 2026-09-27: when the bot is started from a PowerShell 7 terminal, its environment carries
+ * PowerShell 7's `PSModulePath`, and a Windows PowerShell 5.1 started from it looks for its own
+ * built-in modules in PowerShell 7's folders first — `Get-Acl` then fails with "the module could not
+ * be loaded", and so can any cmdlet that lives in a module. Without the variable, Windows PowerShell
+ * builds its default path, which is the one it was written for. Every call the bot makes to
+ * `powershell` goes through this, so the answer does not depend on which terminal started it.
+ */
+export function winPsEnv(env = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env))
+        if (k.toLowerCase() !== 'psmodulepath')
+            out[k] = v;
+    return out;
+}

package/dist/src/exec/workDir.js

@@ -0,0 +1,94 @@
+/**
+ * Where a session's commands run.
+ *
+ * Until now every step, every check and every review command ran in `execution.cwd`, whose
+ * default is `.` — the directory the runner was started from, which for the API is this
+ * project's own checkout. The first step of a nine-task plan ran with
+ * `cwd=C:\Projects\automate-365` while writing files into `C:\Projects\calculator-test`, and
+ * it went right only because the model used absolute paths, as the plan's instructions told it
+ * to. That is a plan author compensating for a runner default: one relative path in one step
+ * and the model is editing the bot. The reviewer was told the same directory in as many words,
+ * "Working directory for your commands: C:\Projects\automate-365", and the implementer was told
+ * nothing at all.
+ *
+ * A session already knows its project — `vcs.repoDir` says where the branches go and
+ * `mirror.rootDir` where the files are — so that is where its commands run. The configured
+ * `execution.cwd` is the fallback for a session with no project, and this project's own
+ * checkout is never a fallback: a session that would land here by default does not run, and
+ * says why. Landing here on purpose — the operator pointed the session at the bot itself — is
+ * allowed and said out loud, because that is a decision somebody made.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+let cachedBotRoot;
+/**
+ * This project's own root: the nearest ancestor of this file with a package.json named
+ * `copilot-operator`. Walks rather than counting `..`, because the file sits at one depth under
+ * `src/` and another under `dist/src/`.
+ */
+export function botRootDir() {
+    if (cachedBotRoot)
+        return cachedBotRoot;
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        try {
+            const pkg = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8'));
+            if (pkg.name === 'copilot-operator')
+                return (cachedBotRoot = dir);
+        }
+        catch {
+            // No package.json here, or not ours. Keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return (cachedBotRoot = process.cwd());
+        dir = parent;
+    }
+}
+function isInside(dir, root) {
+    const a = resolve(dir).toLowerCase();
+    const b = resolve(root).toLowerCase();
+    return a === b || a.startsWith(b.endsWith(sep) ? b : b + sep);
+}
+/** Whether a directory is, or is inside, this runner's own checkout. */
+export function isOwnCheckout(dir, own = botRootDir()) {
+    return isInside(dir, own);
+}
+/**
+ * Decides the directory a session's commands run in, or refuses.
+ *
+ * `configCwd` is `execution.cwd` already resolved; `own` is this runner's root, a parameter so
+ * the rule can be exercised against a made-up one.
+ */
+export function workingDirFor(session, configCwd, own = botRootDir()) {
+    const repo = (session.vcs?.repoDir ?? '').trim();
+    const mirror = (session.mirror?.rootDir ?? '').trim();
+    if (repo)
+        return { cwd: resolve(repo), source: 'repository', ownCheckout: isInside(repo, own) };
+    if (mirror)
+        return { cwd: resolve(mirror), source: 'mirror', ownCheckout: isInside(mirror, own) };
+    if (isInside(configCwd, own)) {
+        return {
+            cwd: resolve(configCwd),
+            problem: "no working directory for this session's commands: it names no project folder, and the configured " +
+                `default (${resolve(configCwd)}) is this runner's own checkout, where nothing the model writes belongs. ` +
+                'Give the session a project folder, or set execution.cwd to a folder of its own.',
+        };
+    }
+    return { cwd: resolve(configCwd), source: 'config', ownCheckout: false };
+}
+export function isWorkingDirProblem(w) {
+    return 'problem' in w;
+}
+/** What the model is told, so a relative path is a fact rather than a guess. */
+export function workingDirNote(w) {
+    return [
+        '## Working directory',
+        '',
+        `Commands run in \`${w.cwd}\` unless a step changes directory. Relative paths resolve there.`,
+        ...(w.ownCheckout
+            ? ['', "That folder is this runner's own checkout. The operator pointed the session at it deliberately."]
+            : []),
+    ].join('\n');
+}

package/dist/src/log/runLog.js

@@ -0,0 +1,43 @@
+/**
+ * The run log: a JSONL transcript on disk plus a readable line on the console.
+ *
+ * Everything the bot does is appended to `runs/<runId>/transcript.jsonl`, including every
+ * prompt sent, every reply received, every command and its exit code, and every file hash.
+ * A run that goes wrong is then reconstructable without guessing, which matters when the
+ * thing being audited is a machine running model-written commands.
+ */
+import { createWriteStream } from 'node:fs';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export class RunLog {
+    runId;
+    quiet;
+    stream;
+    dir;
+    constructor(runId, runsDir, quiet = false) {
+        this.runId = runId;
+        this.quiet = quiet;
+        this.dir = join(runsDir, runId);
+        mkdirSync(this.dir, { recursive: true });
+        this.stream = createWriteStream(join(this.dir, 'transcript.jsonl'), { flags: 'a' });
+    }
+    /** Structured record for the transcript; nothing is printed unless `human` is given. */
+    event(type, data = {}, human, level = 'info') {
+        this.stream.write(JSON.stringify({ at: new Date().toISOString(), type, ...data }) + '\n');
+        if (human && !this.quiet) {
+            const prefix = level === 'error' ? '  !! ' : level === 'warn' ? '  ! ' : '  ';
+            process.stdout.write(prefix + human + '\n');
+        }
+    }
+    /** Console-only, for things too noisy or too transient for the transcript. */
+    say(text) {
+        if (!this.quiet)
+            process.stdout.write(text + '\n');
+    }
+    path(...parts) {
+        return join(this.dir, ...parts);
+    }
+    async close() {
+        await new Promise((resolve) => this.stream.end(resolve));
+    }
+}

package/dist/src/orchestrator/derivedChecks.js

@@ -0,0 +1,95 @@
+/**
+ * Checks that come from review findings, and what happens to them over a task's life.
+ *
+ * A review is judgement, and judgement varies between runs: the same missing `@HttpCode(200)`
+ * was found by one reviewer and missed by the next. So a reviewer may give, with a finding,
+ * the mechanical test that would have caught it, in the plan's own check shape — and from
+ * then on the runner repeats it, on this attempt and on every later one. Three rules keep that
+ * from turning a wrong finding into a permanent wall:
+ *
+ *   - A check is kept only if it fails on the work as it stands. One that passes on the
+ *     defective state does not capture the defect; it is refused, and the reviewer is told.
+ *   - A dispute suspends the finding's check until the next review rules: raised again, the
+ *     check comes back; not raised, it is dropped. A counter never overrules a person.
+ *   - A derived check sends the work back like any other, but never ends the task by itself.
+ *     With the rounds spent and only derived checks failing, the work goes to the reviewer
+ *     with those failures named. The next reviewer's judgement outranks the last one's check.
+ */
+import { join } from 'node:path';
+import { runCheck } from '../exec/checks.js';
+import { isRepeat } from '../protocol/reviewSchema.js';
+/** How a derived check is named in the gate, so its result is recognisable and cannot clash. */
+export function derivedCheckName(findingId, name) {
+    return `review ${findingId}: ${name}`;
+}
+export function isDerivedCheck(check) {
+    return /^review r\d+f\d+: /.test(check.name);
+}
+/**
+ * Runs each finding's check on the current state. Kept if it fails now, refused if it passes.
+ */
+export async function validateDerivedChecks(findings, opts) {
+    const out = { kept: [], refused: [], blocked: [] };
+    for (const [i, finding] of findings.entries()) {
+        if (!finding.check)
+            continue;
+        const check = { ...finding.check, name: derivedCheckName(finding.id, finding.check.name) };
+        const outcome = await runCheck(check, 500 + i, {
+            cwd: opts.cwd,
+            logDir: join(opts.logDir, 'derived'),
+            repoDir: opts.repoDir,
+            deny: opts.deny,
+            roots: opts.roots,
+            signal: opts.signal,
+            defaultShell: opts.defaultShell,
+            tracker: opts.tracker,
+            passEnv: opts.passEnv,
+        });
+        if (outcome.refusedBeforeRunning)
+            out.blocked.push({ finding, check, outcome });
+        else
+            (outcome.passed ? out.refused : out.kept).push({ finding, check, outcome });
+    }
+    return out;
+}
+/** The derived checks that run in the gate. */
+export function activeChecks(reviewChecks) {
+    return reviewChecks.filter((rc) => rc.state === 'active').map((rc) => rc.check);
+}
+/** A dispute of a finding suspends its check until the next review rules. */
+export function suspendDisputed(reviewChecks, disputedIds) {
+    const ids = new Set(disputedIds.map((d) => d.trim().toLowerCase()));
+    const suspended = [];
+    const checks = reviewChecks.map((rc) => {
+        if (rc.state !== 'active' || !ids.has(rc.findingId.toLowerCase()))
+            return rc;
+        suspended.push(rc.findingId);
+        return { ...rc, state: 'suspended' };
+    });
+    return { checks, suspended };
+}
+/**
+ * What a review's verdict does to suspended checks: raised again, back to active; not raised,
+ * dropped — the dispute stood. On a pass every suspended one is dropped.
+ */
+export function settleAfterReview(reviewChecks, verdict, newFindings) {
+    const reactivated = [];
+    const dropped = [];
+    const checks = reviewChecks.map((rc) => {
+        if (rc.state !== 'suspended')
+            return rc;
+        const raisedAgain = verdict === 'fail' && newFindings.some((f) => isRepeat([{ what: rc.what, evidence: '', basis: '', where: rc.where ?? '', about: 'work' }], f));
+        if (raisedAgain) {
+            reactivated.push(rc.findingId);
+            return { ...rc, state: 'active' };
+        }
+        dropped.push(rc.findingId);
+        return { ...rc, state: 'dropped' };
+    });
+    return { checks, reactivated, dropped };
+}
+/** Whether the failures left are all derived, which is when the work goes to the reviewer anyway. */
+export function onlyDerivedFailing(outcomes) {
+    const failed = outcomes.filter((o) => !o.passed);
+    return failed.length > 0 && failed.every((o) => isDerivedCheck(o.check));
+}