@phi-code-admin/phi-code 0.88.0 → 0.90.0

package/extensions/phi/providers/redteam.ts

@@ -0,0 +1,115 @@
+/**
+ * Executable red-team — the adversary's deliverable is a FAILING RUN, not an
+ * opinion (docs/design/plan-debug-build.md). This is the pure decision core: it
+ * turns the outcome of each adversarial attempt into a loop step, so a "breaking
+ * case" is only ever recorded when a real test went RED. Prose can't lie its way
+ * to a finding here — execution is the oracle.
+ *
+ * Why this exists: in the 3362 measurement an over-clever guard survived a
+ * different model's careful written review because the reviewer shared the
+ * misconception. It would NOT have survived the assertion being *run*. So the
+ * adversary must attack the specific input regime the diff touched, and express
+ * the attack as an executed test.
+ */
+
+import type { FailingState } from "./debug-contract.js";
+import { type CommandResult, passed, tail } from "./execution.js";
+
+/** One adversarial attempt: a runnable test aimed at a specific input regime. */
+export interface RedTeamAttempt {
+	/** Which boundary/regime it targets (e.g. "buffered vs streaming"). */
+	regime: string;
+	/** The runnable breaking test (a command). */
+	test: string;
+	/** The execution of that test (null = it could not be run). */
+	result: CommandResult | null;
+}
+
+/** A confirmed break: an attempt whose test actually ran RED. */
+export interface BreakingCase {
+	regime: string;
+	test: string;
+	symptom: string;
+}
+
+export interface RedTeamState {
+	/** Consecutive rounds that failed to break the code. */
+	dry: number;
+	attemptsUsed: number;
+	breakingCases: BreakingCase[];
+}
+
+export interface RedTeamConfig {
+	/** Stop after this many consecutive rounds that could not break the code. */
+	dryRoundsToStop: number;
+	/** Hard budget on attempts. */
+	maxAttempts: number;
+}
+
+export const DEFAULT_REDTEAM_CONFIG: RedTeamConfig = { dryRoundsToStop: 2, maxAttempts: 8 };
+
+export function initRedTeam(): RedTeamState {
+	return { dry: 0, attemptsUsed: 0, breakingCases: [] };
+}
+
+/** Keep going only while under budget and not yet K dry rounds in a row. */
+export function shouldContinueRedTeam(state: RedTeamState, config: RedTeamConfig): boolean {
+	return state.attemptsUsed < config.maxAttempts && state.dry < config.dryRoundsToStop;
+}
+
+/**
+ * Fold one attempt into the state. A RED run (test failed) is a breaking case
+ * and resets the dry counter; a GREEN run (or one that could not be executed at
+ * all) counts as a dry round — you cannot claim a break you did not run.
+ */
+export function recordAttempt(state: RedTeamState, attempt: RedTeamAttempt, config: RedTeamConfig): RedTeamState {
+	const attemptsUsed = state.attemptsUsed + 1;
+	const ran = attempt.result !== null;
+	const broke = ran && !passed(attempt.result as CommandResult);
+
+	if (broke) {
+		const result = attempt.result as CommandResult;
+		return {
+			dry: 0,
+			attemptsUsed,
+			breakingCases: [
+				...state.breakingCases,
+				{ regime: attempt.regime, test: attempt.test, symptom: tail(result, 20) || `exit ${result.exitCode}` },
+			],
+		};
+	}
+	// Green, or unrunnable: this round produced no finding.
+	void config;
+	return { dry: state.dry + 1, attemptsUsed, breakingCases: state.breakingCases };
+}
+
+/** Turn confirmed breaks into failing states that /debug can consume directly. */
+export function breakingCasesToFailingStates(cases: BreakingCase[], cwd?: string): FailingState[] {
+	return cases.map((c) => ({
+		reproCommand: c.test,
+		trace: c.symptom,
+		expected: `input regime "${c.regime}" must not break the change`,
+		cwd,
+	}));
+}
+
+const STREAMING_HINT = /\b(stream|iter|chunk|read|io|http|response|decode|encode|buffer|socket|pipe)\b/i;
+const PARSE_HINT = /\b(parse|json|yaml|xml|deserialize|decode|token|lexer)\b/i;
+const NUMERIC_HINT = /\b(sum|count|index|offset|length|size|range|price|amount|math|float|int)\b/i;
+const AUTH_HINT = /\b(auth|login|token|session|password|permission|role|jwt)\b/i;
+
+/**
+ * Cheap enumeration of the input regimes worth attacking, given hints from the
+ * change (file names + keywords). Always includes the universal boundaries;
+ * adds domain-specific ones when the hints match. The adversary attacks these,
+ * not the whole app.
+ */
+export function enumerateInputRegimes(hints: { changedFiles?: string[]; keywords?: string } = {}): string[] {
+	const blob = `${(hints.changedFiles ?? []).join(" ")} ${hints.keywords ?? ""}`;
+	const regimes = ["empty input", "null/undefined", "boundary value", "wrong type", "large input"];
+	if (STREAMING_HINT.test(blob)) regimes.push("buffered vs streaming");
+	if (PARSE_HINT.test(blob)) regimes.push("malformed/partial input", "non-ASCII / unicode");
+	if (NUMERIC_HINT.test(blob)) regimes.push("zero / negative", "overflow / very large number");
+	if (AUTH_HINT.test(blob)) regimes.push("missing credentials", "expired / tampered token");
+	return regimes;
+}

package/extensions/phi/providers/sandbox-plan.ts

@@ -0,0 +1,273 @@
+/**
+ * Sandbox planning — the pure core that turns "what project is this?" into "how
+ * do I run its code in a guaranteed environment?" (docs/design/plan-debug-build.md,
+ * §Execution grounding).
+ *
+ * The SWE-bench measurement was defeated because the host Python was too new to
+ * run the target library, so the model reconstructed a mock and graded itself.
+ * A per-project container fixes that: run the real reproduction/suite with the
+ * project's real toolchain. Everything here is pure (no fs, no spawn) so the
+ * toolchain detection, the recipe, the backend decision, and — critically — the
+ * `docker run` argv (where the Windows path/quoting bugs live) are all unit-tested.
+ */
+
+export type ToolchainKind = "node" | "python" | "go" | "rust" | "ruby" | "unknown";
+
+export interface Toolchain {
+	kind: ToolchainKind;
+	/** The marker file that determined it (e.g. "package.json"). */
+	marker: string | null;
+	hasDockerfile: boolean;
+	hasCompose: boolean;
+}
+
+/** `.phi/sandbox.json` — explicit project override, always wins over detection. */
+export interface SandboxConfig {
+	backend?: "docker" | "local" | "auto";
+	image?: string;
+	setup?: string;
+	test?: string;
+	workdir?: string;
+	env?: Record<string, string>;
+	/** Allow network inside the container (default true — deps often need it). */
+	network?: boolean;
+	memory?: string;
+	cpus?: string;
+}
+
+export type RecipeSource = "detected" | "dockerfile" | "config";
+
+export interface SandboxRecipe {
+	image: string;
+	/** One-off dependency install, run against the mounted project. */
+	setup?: string;
+	/** Best-guess suite command (a floor; the caller may override). */
+	test?: string;
+	workdir: string;
+	env: Record<string, string>;
+	network: boolean;
+	memory?: string;
+	cpus?: string;
+	source: RecipeSource;
+}
+
+const MOUNT_WORKDIR = "/work";
+
+const BASE_IMAGES: Record<Exclude<ToolchainKind, "unknown">, string> = {
+	node: "node:20-slim",
+	python: "python:3.12-slim",
+	go: "golang:1.22-bookworm",
+	rust: "rust:1-slim",
+	ruby: "ruby:3-slim",
+};
+
+const DEFAULT_ENV: Record<ToolchainKind, Record<string, string>> = {
+	node: { CI: "1" },
+	// PYTHONSAFEPATH stops a stray local module from shadowing the stdlib (the
+	// `select.py`/`resource` class of failures seen in the SWE-bench harness).
+	python: { PYTHONSAFEPATH: "1", PYTHONDONTWRITEBYTECODE: "1" },
+	go: {},
+	rust: {},
+	ruby: {},
+	unknown: {},
+};
+
+/** Detect the toolchain from a project's top-level file names. Order = priority. */
+export function detectToolchain(files: string[]): Toolchain {
+	const set = new Set(files.map((f) => f.trim()).filter(Boolean));
+	const has = (name: string) => set.has(name);
+	const hasDockerfile = has("Dockerfile");
+	const hasCompose = has("docker-compose.yml") || has("compose.yml") || has("docker-compose.yaml");
+
+	let kind: ToolchainKind = "unknown";
+	let marker: string | null = null;
+	if (has("package.json")) {
+		kind = "node";
+		marker = "package.json";
+	} else if (has("pyproject.toml") || has("requirements.txt") || has("setup.py")) {
+		kind = "python";
+		marker = has("pyproject.toml") ? "pyproject.toml" : has("requirements.txt") ? "requirements.txt" : "setup.py";
+	} else if (has("go.mod")) {
+		kind = "go";
+		marker = "go.mod";
+	} else if (has("Cargo.toml")) {
+		kind = "rust";
+		marker = "Cargo.toml";
+	} else if (has("Gemfile")) {
+		kind = "ruby";
+		marker = "Gemfile";
+	}
+	return { kind, marker, hasDockerfile, hasCompose };
+}
+
+function detectedSetup(tc: Toolchain, files: Set<string>): string | undefined {
+	switch (tc.kind) {
+		case "node":
+			return files.has("package-lock.json") ? "npm ci || npm install" : "npm install";
+		case "python":
+			if (files.has("pyproject.toml") || files.has("setup.py")) return "pip install -e . || pip install .";
+			if (files.has("requirements.txt")) return "pip install -r requirements.txt";
+			return undefined;
+		case "go":
+			return "go mod download";
+		case "rust":
+			return "cargo fetch";
+		case "ruby":
+			return "bundle install";
+		default:
+			return undefined;
+	}
+}
+
+function detectedTest(tc: Toolchain): string | undefined {
+	switch (tc.kind) {
+		case "node":
+			return "npm test";
+		case "python":
+			return "pytest";
+		case "go":
+			return "go test ./...";
+		case "rust":
+			return "cargo test";
+		case "ruby":
+			return "bundle exec rake test";
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Build the environment recipe from detected toolchain + files. A project
+ * Dockerfile is honored (source "dockerfile"); otherwise a base image is chosen.
+ */
+export function defaultRecipe(tc: Toolchain, files: string[] = []): SandboxRecipe {
+	const set = new Set(files);
+	const base: SandboxRecipe = {
+		image: tc.kind === "unknown" ? "debian:bookworm-slim" : BASE_IMAGES[tc.kind],
+		setup: detectedSetup(tc, set),
+		test: detectedTest(tc),
+		workdir: MOUNT_WORKDIR,
+		env: { ...DEFAULT_ENV[tc.kind] },
+		network: true,
+		source: tc.hasDockerfile ? "dockerfile" : "detected",
+	};
+	return base;
+}
+
+/** Merge an explicit `.phi/sandbox.json` over a detected recipe (config wins). */
+export function applyConfig(recipe: SandboxRecipe, config?: SandboxConfig): SandboxRecipe {
+	if (!config) return recipe;
+	return {
+		image: config.image ?? recipe.image,
+		setup: config.setup ?? recipe.setup,
+		test: config.test ?? recipe.test,
+		workdir: config.workdir ?? recipe.workdir,
+		env: { ...recipe.env, ...(config.env ?? {}) },
+		network: config.network ?? recipe.network,
+		memory: config.memory ?? recipe.memory,
+		cpus: config.cpus ?? recipe.cpus,
+		source: config.image || config.setup ? "config" : recipe.source,
+	};
+}
+
+export type Backend = "docker" | "local" | "unavailable";
+
+export interface BackendSignals {
+	dockerAvailable: boolean;
+	requested?: "docker" | "local" | "auto";
+	toolchainKnown: boolean;
+	hasDockerfile: boolean;
+}
+
+export interface BackendDecision {
+	backend: Backend;
+	reason: string;
+}
+
+/**
+ * Choose the execution backend, honestly. Docker is the guaranteed oracle but
+ * only helps when we can containerize (a known toolchain or a Dockerfile). When
+ * the caller explicitly demanded docker and it is absent, the answer is
+ * `unavailable` — NOT a silent downgrade to a non-guaranteed local run.
+ */
+export function decideBackend(s: BackendSignals): BackendDecision {
+	const req = s.requested ?? "auto";
+	if (req === "local") return { backend: "local", reason: "backend: local (requested)" };
+	if (req === "docker") {
+		return s.dockerAvailable
+			? { backend: "docker", reason: "backend: docker (requested, available)" }
+			: { backend: "unavailable", reason: "docker requested but the daemon is not available" };
+	}
+	// auto
+	if (s.dockerAvailable && (s.toolchainKnown || s.hasDockerfile)) {
+		return { backend: "docker", reason: "backend: docker (guaranteed environment)" };
+	}
+	if (!s.dockerAvailable)
+		return {
+			backend: "local",
+			reason: "backend: local (docker unavailable — runs are real but not dependency-guaranteed)",
+		};
+	return { backend: "local", reason: "backend: local (unknown toolchain, no Dockerfile — nothing to containerize)" };
+}
+
+/**
+ * Normalize a host path into a Docker bind source. On Windows, forward-slash the
+ * path but keep the drive colon (`C:/Users/…`) — the form Docker Desktop accepts
+ * and, crucially, one that survives argv passing without MSYS mangling.
+ */
+export function toBindSource(hostPath: string, platform: NodeJS.Platform = process.platform): string {
+	if (platform === "win32") return hostPath.replace(/\\/g, "/");
+	return hostPath;
+}
+
+export interface DockerRunSpec {
+	image: string;
+	/** The command run inside the container via `sh -c`. */
+	command: string;
+	/** Host path to bind-mount as the workdir. */
+	mountSource: string;
+	workdir: string;
+	env: Record<string, string>;
+	network: boolean;
+	memory?: string;
+	cpus?: string;
+	platform?: NodeJS.Platform;
+}
+
+/**
+ * Build the argv passed to `docker` (after the program name). Pure and total, so
+ * the exact invocation — mount, workdir, env, network isolation, resource caps —
+ * is asserted in tests instead of discovered in production.
+ */
+export function buildDockerRunArgs(spec: DockerRunSpec): string[] {
+	const bind = `${toBindSource(spec.mountSource, spec.platform)}:${spec.workdir}`;
+	const args: string[] = ["run", "--rm", "-v", bind, "-w", spec.workdir];
+	for (const [k, v] of Object.entries(spec.env)) {
+		args.push("-e", `${k}=${v}`);
+	}
+	if (!spec.network) args.push("--network", "none");
+	if (spec.memory) args.push("--memory", spec.memory);
+	if (spec.cpus) args.push("--cpus", spec.cpus);
+	args.push(spec.image, "sh", "-c", spec.command);
+	return args;
+}
+
+/** A small, dependency-free deterministic hash (djb2) for cache tags. */
+function djb2(input: string): string {
+	let h = 5381;
+	for (let i = 0; i < input.length; i++) {
+		h = ((h << 5) + h + input.charCodeAt(i)) >>> 0;
+	}
+	return h.toString(16).padStart(8, "0");
+}
+
+/** Deterministic image tag for a built recipe (project Dockerfile / config). */
+export function imageTagFor(recipe: SandboxRecipe): string {
+	return `phi-sandbox:${djb2(`${recipe.image}|${recipe.setup ?? ""}|${recipe.workdir}`)}`;
+}
+
+/** Generate a minimal Dockerfile for a detected recipe (utility / persistence). */
+export function generatedDockerfile(recipe: SandboxRecipe): string {
+	const envLines = Object.entries(recipe.env).map(([k, v]) => `ENV ${k}=${v}`);
+	return [`FROM ${recipe.image}`, `WORKDIR ${recipe.workdir}`, ...envLines, ""].join("\n");
+}

package/extensions/phi/providers/sandbox.ts

@@ -0,0 +1,215 @@
+/**
+ * Sandbox — the thin IO shell over the pure planner (sandbox-plan.ts). It turns
+ * a project directory into a runnable environment and executes commands in it,
+ * returning the same CommandResult the oracle cores already consume. Three
+ * backends: `docker` (the guaranteed environment), `local` (real runs, but not
+ * dependency-guaranteed), and `unavailable` (honest — every exec reports it
+ * could not run, so /debug and /build emit BLOCKED instead of a fabricated pass).
+ *
+ * The fs reads and spawns are injectable so the routing/interpretation is
+ * unit-tested without a Docker daemon; a separate docker-gated smoke test does
+ * one real container run.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	type CommandResult,
+	passed,
+	type RunOptions,
+	runArgv as realRunArgv,
+	runCommand as realRunCommand,
+} from "./execution.js";
+import {
+	applyConfig,
+	type Backend,
+	buildDockerRunArgs,
+	decideBackend,
+	defaultRecipe,
+	detectToolchain,
+	imageTagFor,
+	type SandboxConfig,
+	type SandboxRecipe,
+} from "./sandbox-plan.js";
+
+export interface PrepareResult {
+	ok: boolean;
+	backend: Backend;
+	detail: string;
+	result?: CommandResult;
+}
+
+export interface Sandbox {
+	readonly backend: Backend;
+	readonly recipe: SandboxRecipe;
+	readonly reason: string;
+	describe(): string;
+	available(): boolean;
+	/** Run a command in the environment. Never throws (see execution.ts). */
+	exec(command: string, options?: RunOptions): CommandResult;
+	/** Build the image / install deps. Idempotent, best-effort. */
+	prepare(): PrepareResult;
+}
+
+type RunCommandFn = (command: string, options?: RunOptions) => CommandResult;
+type RunArgvFn = (file: string, args: string[], options?: RunOptions & { label?: string }) => CommandResult;
+
+/** Injectable seams — real fs/spawn by default, fakes in tests. */
+export interface SandboxDeps {
+	runCommand?: RunCommandFn;
+	runArgv?: RunArgvFn;
+	listFiles?: (cwd: string) => string[];
+	readConfig?: (cwd: string) => SandboxConfig | undefined;
+	/** Force docker availability in tests; otherwise probed via `docker version`. */
+	dockerAvailable?: boolean;
+}
+
+export interface ResolveOptions {
+	cwd: string;
+	requested?: "docker" | "local" | "auto";
+	deps?: SandboxDeps;
+}
+
+/** List a project's top-level entries (best-effort; empty on error). */
+export function listProjectFiles(cwd: string): string[] {
+	try {
+		return readdirSync(cwd);
+	} catch {
+		return [];
+	}
+}
+
+/** Read and parse `.phi/sandbox.json` if present. */
+export function readSandboxConfig(cwd: string): SandboxConfig | undefined {
+	try {
+		const raw = readFileSync(join(cwd, ".phi", "sandbox.json"), "utf-8");
+		const parsed = JSON.parse(raw);
+		return parsed && typeof parsed === "object" ? (parsed as SandboxConfig) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Probe the Docker daemon (server version reachable). Cheap, capped timeout. */
+export function probeDocker(ra: RunArgvFn): boolean {
+	const r = ra("docker", ["version", "--format", "{{.Server.Version}}"], { timeoutMs: 8000, label: "docker version" });
+	return passed(r) && r.stdout.trim().length > 0;
+}
+
+const UNAVAILABLE_MESSAGE = "SANDBOX UNAVAILABLE — no executable environment; do not fabricate a result, emit BLOCKED.";
+
+function unavailableResult(command: string): CommandResult {
+	return { command, exitCode: null, stdout: "", stderr: UNAVAILABLE_MESSAGE, durationMs: 0, timedOut: false };
+}
+
+/**
+ * Resolve the sandbox for a project directory: detect toolchain, merge config,
+ * decide the backend honestly, and return an executor. Docker exec runs
+ * `docker run --rm -v <cwd>:/work …`; edits land on the host mount, so /debug's
+ * fix-then-rerun works and the container stays ephemeral.
+ */
+export function resolveSandbox(opts: ResolveOptions): Sandbox {
+	const deps = opts.deps ?? {};
+	const rc = deps.runCommand ?? realRunCommand;
+	const ra = deps.runArgv ?? realRunArgv;
+	const files = (deps.listFiles ?? listProjectFiles)(opts.cwd);
+	const config = (deps.readConfig ?? readSandboxConfig)(opts.cwd);
+	const tc = detectToolchain(files);
+	const recipe = applyConfig(defaultRecipe(tc, files), config);
+	const requested = opts.requested ?? config?.backend ?? "auto";
+	const dockerAvailable = deps.dockerAvailable ?? probeDocker(ra);
+	const decision = decideBackend({
+		dockerAvailable,
+		requested,
+		toolchainKnown: tc.kind !== "unknown",
+		hasDockerfile: tc.hasDockerfile,
+	});
+
+	// Effective image can change after prepare() builds a project Dockerfile.
+	const state = { image: recipe.image };
+
+	const dockerExec = (command: string, options?: RunOptions): CommandResult => {
+		const args = buildDockerRunArgs({
+			image: state.image,
+			command,
+			mountSource: opts.cwd,
+			workdir: recipe.workdir,
+			env: recipe.env,
+			network: recipe.network,
+			memory: recipe.memory,
+			cpus: recipe.cpus,
+		});
+		return ra("docker", args, {
+			cwd: opts.cwd,
+			timeoutMs: options?.timeoutMs,
+			label: `docker[${state.image}] ${command}`,
+		});
+	};
+
+	const base = { backend: decision.backend, recipe, reason: decision.reason };
+
+	if (decision.backend === "unavailable") {
+		return {
+			...base,
+			describe: () => `unavailable — ${decision.reason}`,
+			available: () => false,
+			exec: (command) => unavailableResult(command),
+			prepare: () => ({ ok: false, backend: "unavailable", detail: decision.reason }),
+		};
+	}
+
+	if (decision.backend === "local") {
+		return {
+			...base,
+			describe: () => `local host (${opts.cwd})`,
+			available: () => true,
+			exec: (command, options) => rc(command, { cwd: opts.cwd, ...options }),
+			// Deliberately no host-side dependency install — running `npm install`
+			// etc. on the user's host is intrusive; local is best-effort as-is.
+			prepare: () => ({ ok: true, backend: "local", detail: "local host — no preparation performed" }),
+		};
+	}
+
+	// docker
+	return {
+		...base,
+		describe: () => `docker (${state.image})`,
+		available: () => true,
+		exec: dockerExec,
+		prepare: () => {
+			if (recipe.source === "dockerfile") {
+				const tag = imageTagFor(recipe);
+				const built = ra("docker", ["build", "-t", tag, "-f", "Dockerfile", "."], {
+					cwd: opts.cwd,
+					label: `docker build ${tag}`,
+				});
+				if (passed(built)) state.image = tag;
+				return {
+					ok: passed(built),
+					backend: "docker",
+					detail: passed(built) ? `built image ${tag} from Dockerfile` : "docker build failed",
+					result: built,
+				};
+			}
+			// Base image: pull it, then run the dependency setup against the mount.
+			const pulled = ra("docker", ["pull", state.image], { cwd: opts.cwd, label: `docker pull ${state.image}` });
+			if (!recipe.setup) {
+				return {
+					ok: passed(pulled),
+					backend: "docker",
+					detail: `pulled ${state.image} (no setup step)`,
+					result: pulled,
+				};
+			}
+			const setup = dockerExec(recipe.setup);
+			return {
+				ok: passed(setup),
+				backend: "docker",
+				detail: passed(setup)
+					? `pulled ${state.image}; ran setup \`${recipe.setup}\``
+					: `setup failed: \`${recipe.setup}\``,
+				result: setup,
+			};
+		},
+	};
+}

package/extensions/phi/providers/triage.ts

@@ -0,0 +1,96 @@
+/**
+ * Triage / adaptive depth — pick the CHEAPEST mode consistent with the signals.
+ *
+ * The measured lesson (docs/design/plan-debug-build.md): the 6–14× overhead of
+ * the full pipeline is only worth paying when a single shot fails the real
+ * oracle. So this classifier defaults to the least machinery and escalates only
+ * on concrete signals — a supplied failing state routes to /debug, a large or
+ * under-specified build routes to /build, everything else is a single shot.
+ */
+
+export type Route = "debug" | "single-shot" | "build" | "plan";
+
+export interface TriageSignals {
+	/** A concrete failing test / trace / repro command was supplied. */
+	hasFailingState?: boolean;
+	/** Rough number of files the task will touch (undefined = estimate from text). */
+	estimatedFiles?: number;
+	/** The task text, for cheap keyword signals. */
+	text?: string;
+	/** Caller forces a specific mode (an explicit /debug, /build, /plan). */
+	forced?: Route;
+	/** Caller wants only a plan artifact, not the execution loop. */
+	planOnly?: boolean;
+}
+
+export interface TriageDecision {
+	route: Route;
+	/** "minimal" = do the least; "full" = the multi-phase pipeline is justified. */
+	depth: "minimal" | "full";
+	reason: string;
+}
+
+const BUILD_KEYWORDS =
+	/\b(build|scaffold|application|app|feature|end[- ]?to[- ]?end|full[- ]?stack|from scratch|new (project|service|module|api|endpoint|component|page)|several files|multiple files)\b/i;
+
+/** At/above this many touched files, a single shot is unlikely to stay coherent. */
+export const MULTI_FILE_THRESHOLD = 3;
+
+/**
+ * Cheap file-count estimate from a request: count distinct path-like tokens.
+ * Deliberately conservative — defaults to 1 when nothing looks like a path.
+ */
+export function estimateFiles(text: string): number {
+	if (!text.trim()) return 1;
+	const paths = new Set<string>();
+	for (const m of text.matchAll(/\b[\w./-]+\.[a-z]{1,6}\b/gi)) {
+		paths.add(m[0].toLowerCase());
+	}
+	return Math.max(1, paths.size);
+}
+
+/**
+ * Map signals to a route + depth. Pure and deterministic: same signals in, same
+ * decision out. Order matters — a forced mode wins, then a real failing state
+ * (cheapest useful oracle), then build-scale, else single shot.
+ */
+export function triage(signals: TriageSignals): TriageDecision {
+	if (signals.forced) {
+		return {
+			route: signals.forced,
+			depth: signals.forced === "single-shot" ? "minimal" : "full",
+			reason: `explicit /${signals.forced}`,
+		};
+	}
+
+	if (signals.hasFailingState) {
+		return {
+			route: "debug",
+			depth: "minimal",
+			reason: "a reproducible failing state was supplied — fix it directly, skip planning",
+		};
+	}
+
+	const text = signals.text ?? "";
+	const files = signals.estimatedFiles ?? estimateFiles(text);
+	const buildy = BUILD_KEYWORDS.test(text);
+	const large = files >= MULTI_FILE_THRESHOLD;
+
+	if (buildy || large) {
+		const why = large ? `~${files} files touched (≥ ${MULTI_FILE_THRESHOLD})` : "build-scale request";
+		if (signals.planOnly) {
+			return {
+				route: "plan",
+				depth: "full",
+				reason: `${why}; plan-only requested — decompose without the run loop`,
+			};
+		}
+		return { route: "build", depth: "full", reason: `${why} — decompose and run the build→verify→debug loop` };
+	}
+
+	return {
+		route: "single-shot",
+		depth: "minimal",
+		reason: "small, self-contained — try one shot and verify before escalating",
+	};
+}