/** * Command classification (IMP-950): decides how intrusive a shell command * is before anyone runs it. One table feeds BOTH arbitration layers: * - bridge-owned spawns (orchestrator runner) arbitrate in-process; * - PATH shims consult this via the arbiter's acquire endpoint. * * Philosophy: known-mutating commands are exclusive; known-read-only are * shared; long-lived dev servers take a shared hold for their lifetime so * an exclusive seeker can SEE them (and ping) without being blocked forever; * everything else passes through untouched - fail-open beats bricking. */ export type CommandClass = /** Excludes all other holders for its duration. */ 'exclusive' /** Coexists with other shared holders; blocked only by exclusive. */ | 'shared' /** Shared hold kept alive while the command runs (dev servers). */ | 'long-shared' /** No arbitration at all. */ | 'passthrough'; export interface Classification { cls: CommandClass; /** Human label used in lock files + pings ("npm install"). */ label: string; /** Machine-global resources also required (engine DLLs, package stores). */ global?: string[]; } /** * Classify a full command line. Never throws - unknown input is * passthrough. */ export declare function classifyCommand(commandLine: string): Classification; /** * Why a command must not run in a READ-ONLY session, or null if it may (2026-10). * * ── WHY `cls.cls === 'exclusive'` IS NOT THE TEST ──────────────────────────── * * The instinct is "exclusive means mutating, so refuse exclusive". That misses * half of what actually writes: `git add`, `git commit`, `git push`, `git tag` * and `git stash` are all classified **shared** (index.lock serializes them * against other git writers, which is all that classification is about) and all * of them mutate the working tree or the branch. A planning pass runs in the * human's own linked folder, so "it got a shared classification" is not * permission to commit on their branch. * * The rule this implements is the user's, stated as an invariant: **a plan must * not have intrusive work.** Planning persists its deliverable over MCP * (description, acceptance criteria, subtasks, checklist, a `plan.md` note) and * reads the tree; it never needs to write to it. Because the bridge no longer * serializes planning passes against each other (`NON_BLOCKING_PRESENCE_KINDS`), * this is what makes that safe — the pass cannot touch the tree it shares. * * Deliberately a REFUSAL, not a queue. A shim that waited would hand an agent a * command that succeeds minutes later, long after it reasoned about the tree; a * refusal with a reason is something a planning agent can immediately adapt to * ("use update_task instead"). * * Shared commands that only read stay allowed, so a plan can still `git * status`/`git log`/`git diff` and run read-only checks. */ export declare function readOnlyRefusal(commandLine: string, cls: Classification): string | null;