@phi-code-admin/phi-code 0.94.0 → 0.96.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [0.96.0] - 2026-07-12
+
+### Added — the six efficiency upgrades, each tied to a measured failure
+
+1. **Targeted-test oracle** (flask-4992: the agent's repro passed while the
+   module's real tests failed): when no suite command is known, the /fix
+   oracle and the candidate arbitration auto-discover the EXISTING test files
+   of the touched modules (python/pytest, JS/vitest-jest) and run them as the
+   suite leg. New pure provider test-discovery.ts.
+2. **REPRO-AUDIT adversary phase** (requests-2148, twice-measured): when the
+   reproduction was CONSTRUCTED from prose, an adversary from the review
+   family answers one question — which case stated in the issue is NOT
+   covered? — extends the repro, re-runs it, and re-declares REPRO-CMD (which
+   overrides the earlier one for arbitration). Skipped when a failing test was
+   supplied (ground truth).
+3. **Tiered shot budgets** (sympy/sphinx: the shot burned the whole run):
+   triage decides the single-shot budget (12/8/6 min by difficulty) so a hard
+   instance fails FAST and the escalation inherits real budget.
+4. **/runs command + telemetry upgrades**: aggregates .phi/runs.jsonl —
+   green-at-shot rate, escalation rate, per-mode outcomes, slowest phases,
+   timeout counts. PhaseRecord gains durationMs; timed-out attempts are now
+   recorded (fixes the observed phases:[] gap).
+5. **Parallel candidates in git worktrees (experimental)**: /debug
+   --candidates N --parallel fans the FIX out to isolated worktrees (phi
+   sub-processes, concurrency-capped), collects the diffs, and the existing
+   deterministic arbitration picks the winner in the main tree. Worktrees are
+   always cleaned up; falls back to the sequential pipeline outside git.
+6. **/fix suggestion**: a message that reads like a bug report gets a one-line
+   tip pointing at /fix (once per session, never intercepting input).
+
+17 new tests (discovery heuristics, audit instruction, budgets, telemetry
+aggregation, real-git worktree isolation incl. cleanup, bug-shape detector,
+audit-phase integration); full suite green (1496).
+
+## [0.95.0] - 2026-07-12
+
+### Fixed — the 6h-drift class of failures (measured on seaborn-2848)
+
+sandbox_run executed commands with spawnSync, which blocks Node's event loop:
+no JS timer (session timeouts, phase timeouts, harness watchdogs) can fire while
+a command runs. Back-to-back long executions drifted a 25-minute cap to 6h18.
+Four layered defences, per the post-mortem:
+
+- **Root fix:** execution.ts gains runCommandAsync/runArgvAsync (spawn-based,
+  event loop stays alive, the timeout kills the whole process TREE via
+  taskkill /T on Windows). Sandbox gains execAsync (all three backends);
+  sandbox_run now awaits execAsync. Regression test proves a timer fires DURING
+  a child run.
+- **Cumulative execution budget per orchestration** (default 20 min, env
+  PHI_SANDBOX_BUDGET_MS): beyond it, sandbox_run refuses with BUDGET_EXHAUSTED
+  and instructs the agent to conclude honestly with the evidence it has.
+- **Per-call cap tightenable for batch harnesses** (env PHI_SANDBOX_MAX_TIMEOUT_S,
+  default 1800s; the SWE-bench harness now sets 180s).
+- **External watchdog in the harness driver** (timeout -k 30 4500): an internal
+  guard can never protect against itself; a hard kill from another process can.
+
++8 tests (async twins incl. event-loop-liveness regression, budget refusal).
+
 ## [0.94.0] - 2026-07-12
 
 ### Fixed — three defects the run telemetry caught live

package/extensions/phi/orchestrator.ts

@@ -23,10 +23,12 @@ import { join } from "node:path";
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "phi-code";
 import { type AgentDef, loadAgentDef } from "./providers/agent-def.js";
+import { runCandidateFanout } from "./providers/candidate-fanout.js";
 import { diffChangedLines } from "./providers/candidate-select.js";
 import {
 	buildVerifyInstruction,
 	debugPhaseInstructions,
+	reproAuditInstruction,
 	singleShotInstruction,
 } from "./providers/debug-build-commands.js";
 import {
@@ -35,7 +37,13 @@ import {
 	parseFailingState,
 	type VerifiedCandidate,
 } from "./providers/debug-contract.js";
-import { decideEscalation, parseReproCmd, pickCandidateModels, type RoutingLike } from "./providers/escalation.js";
+import {
+	decideEscalation,
+	parseReproCmd,
+	pickCandidateModels,
+	type RoutingLike,
+	shotBudgetMs,
+} from "./providers/escalation.js";
 import { passed, runCommand, tail } from "./providers/execution.js";
 import { defaultExplorerSpecs, READONLY_EXPLORER_TOOLS, runExploreFanout } from "./providers/explore-fanout.js";
 import {
@@ -46,8 +54,15 @@ import {
 	type StructuredPhaseResult,
 } from "./providers/phase-machine.js";
 import { resolveSandbox, type Sandbox } from "./providers/sandbox.js";
-import { appendRunRecord, buildRunRecord, type PhaseRecord } from "./providers/telemetry.js";
-import { triage } from "./providers/triage.js";
+import {
+	appendRunRecord,
+	buildRunRecord,
+	type PhaseRecord,
+	parseRunsJsonl,
+	summarizeRuns,
+} from "./providers/telemetry.js";
+import { discoverTargetedTests, fsSeamsFor } from "./providers/test-discovery.js";
+import { looksLikeBugReport, triage } from "./providers/triage.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -333,11 +348,22 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		reproCmd?: string;
 		list: { source: string; patch: string }[];
 		arbitrated: boolean;
+		// Experimental --parallel: FIX specs fanned out to worktrees after LOCALIZE.
+		parallelSpecs?: { model: string; instruction: string }[];
 	} | null = null;
 	// Telemetry: per-phase records for the current generic run + sandbox_run
 	// invocation count (reset at orchestration start, flushed at finish).
 	let runPhaseRecords: PhaseRecord[] = [];
 	let sandboxExecCount = 0;
+	// Cumulative sandbox execution time this orchestration (drift guard #2) and
+	// its budget; per-call cap (#4) is tightenable for batch harnesses via env.
+	let sandboxExecMs = 0;
+	let currentPhaseStartedAt = 0;
+	const SANDBOX_BUDGET_MS = Math.max(
+		1_000,
+		Number(process.env.PHI_SANDBOX_BUDGET_MS ?? 20 * 60 * 1000) || 20 * 60 * 1000,
+	);
+	const SANDBOX_MAX_TIMEOUT_S = Math.max(30, Number(process.env.PHI_SANDBOX_MAX_TIMEOUT_S ?? 1800) || 1800);
 
 	/** Run a git command in cwd; returns stdout ("" on any failure). */
 	function gitIn(cwd: string, args: string): string {
@@ -471,11 +497,29 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const p = params as { command: string; timeoutSeconds?: number };
 			const cwd = ctx?.cwd || process.cwd();
+			// Guard #2 against runtime drift: a cumulative execution budget per
+			// orchestration. Even with async runs, an agent chaining long commands
+			// can eat a whole session — beyond the budget it must conclude with
+			// what it has. (Measured: back-to-back long runs drifted a 25-min cap
+			// to 6h18 before the async fix.)
+			if (orchestrationActive && sandboxExecMs >= SANDBOX_BUDGET_MS) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `SANDBOX BUDGET EXHAUSTED — ${Math.round(sandboxExecMs / 60000)} min of cumulative execution used this run (budget ${Math.round(SANDBOX_BUDGET_MS / 60000)} min). No further runs this orchestration: conclude with the evidence you already have, honestly (BLOCKED/PARTIAL if unverified).`,
+						},
+					],
+					details: { verdict: "BUDGET_EXHAUSTED", budgetMs: SANDBOX_BUDGET_MS, usedMs: sandboxExecMs },
+				};
+			}
 			if (orchestrationActive) sandboxExecCount++;
 			const sandbox = getSessionSandbox(cwd);
-			const result = sandbox.exec(p.command, {
-				timeoutMs: Math.max(1, Math.min(1800, p.timeoutSeconds ?? 300)) * 1000,
+			// Guard #4: per-call cap, tightenable for batch harnesses via env.
+			const result = await sandbox.execAsync(p.command, {
+				timeoutMs: Math.max(1, Math.min(SANDBOX_MAX_TIMEOUT_S, p.timeoutSeconds ?? 300)) * 1000,
 			});
+			if (orchestrationActive) sandboxExecMs += result.durationMs;
 			const verdict = !sandbox.available()
 				? "UNAVAILABLE"
 				: result.timedOut
@@ -1164,6 +1208,7 @@ Tag the note with relevant keywords for vector search.
 		const phase = phaseQueue.shift()!;
 		phasePending = true;
 		currentPhase = phase;
+		currentPhaseStartedAt = Date.now();
 		// New phase starts with no structured result; it is set only if this
 		// phase's agent calls phase_result.
 		currentPhaseResult = null;
@@ -1251,13 +1296,30 @@ Tag the note with relevant keywords for vector search.
 		};
 	}
 
-	// /debug: REPRODUCE → LOCALIZE → FIX → VERIFY. Each phase routes to a model
-	// that does NOT share the coder's blind spot (verify on the test family).
-	function buildDebugPhases(state: FailingState, candidates = 1): OrchestratorPhase[] {
+	// /debug: REPRODUCE → [REPRO-AUDIT] → LOCALIZE → FIX → VERIFY. Each phase
+	// routes to a model that does NOT share the coder's blind spot. The audit
+	// phase (adversary from the review family) runs ONLY when the reproduction
+	// was CONSTRUCTED from prose — a user-supplied failing test is ground truth
+	// (twice-measured failure: a prose-derived repro validated the agent's
+	// interpretation while the real tests failed).
+	function buildDebugPhases(state: FailingState, candidates = 1, parallel = false): OrchestratorPhase[] {
 		const ins = debugPhaseInstructions(state);
+		const constructed = !state.failingTest?.trim() && !state.reproCommand?.trim();
+		const audit = constructed
+			? [
+					genericPhase(
+						"repro-audit",
+						"🕵️ Phase 1b — REPRO-AUDIT (adversary)",
+						"review",
+						"review",
+						reproAuditInstruction(state),
+					),
+				]
+			: [];
 		if (candidates <= 1) {
 			return [
 				genericPhase("reproduce", "🔴 Phase 1 — REPRODUCE", "test", "test", ins.reproduce),
+				...audit,
 				genericPhase("localize", "🔎 Phase 2 — LOCALIZE", "explore", "explore", ins.localize),
 				genericPhase("fix", "🔧 Phase 3 — FIX", "code", "code", ins.fix),
 				genericPhase("verify", "✅ Phase 4 — VERIFY", "test", "test", ins.verify),
@@ -1281,8 +1343,18 @@ Tag the note with relevant keywords for vector search.
 			phase.fallback = codeRoute.fallback;
 			return phase;
 		});
+		if (parallel) {
+			// Parallel candidates: the queue stops at LOCALIZE; the driver then
+			// fans the FIX out to worktrees and arbitration takes over.
+			return [
+				genericPhase("reproduce", "🔴 Phase 1 — REPRODUCE", "test", "test", ins.reproduce),
+				...audit,
+				genericPhase("localize", "🔎 Phase 2 — LOCALIZE", "explore", "explore", ins.localize),
+			];
+		}
 		return [
 			genericPhase("reproduce", "🔴 Phase 1 — REPRODUCE", "test", "test", ins.reproduce),
+			...audit,
 			genericPhase("localize", "🔎 Phase 2 — LOCALIZE", "explore", "explore", ins.localize),
 			...fixPhases,
 		];
@@ -1377,13 +1449,31 @@ Tag the note with relevant keywords for vector search.
 				"info",
 			);
 		}
-		const suiteCmd = sandbox.recipe.test?.trim();
+		// Oracle upgrade (measured on flask-4992: the agent's own repro passed
+		// while the module's REAL tests failed): when no suite command is known,
+		// auto-discover the EXISTING test files of the modules the change touched
+		// and use them as the suite leg of the oracle.
+		let suiteCmd = sandbox.recipe.test?.trim();
+		const inGitRepo = passed(runCommand("git rev-parse --is-inside-work-tree", { cwd, timeoutMs: 15_000 }));
+		if (!suiteCmd && inGitRepo) {
+			const changed = gitIn(cwd, "diff --name-only")
+				.split("\n")
+				.map((s) => s.trim())
+				.filter(Boolean);
+			const targeted = discoverTargetedTests(changed, fsSeamsFor(cwd));
+			if (targeted.command) {
+				suiteCmd = targeted.command;
+				ctx.ui.notify(
+					`\n🎯 Targeted tests discovered for the touched modules: ${targeted.files.join(", ")}`,
+					"info",
+				);
+			}
+		}
 
 		// A shot that changed NOTHING has nothing to verify — "UNVERIFIED" would be
 		// a lie of omission (measured: a text-only 91s shot ended UNVERIFIED with
 		// zero edits). In a git repo with a clean diff, escalate to the full
 		// pipeline instead: the work simply was not done.
-		const inGitRepo = passed(runCommand("git rev-parse --is-inside-work-tree", { cwd, timeoutMs: 15_000 }));
 		if (inGitRepo && !gitIn(cwd, "diff").trim() && !gitIn(cwd, "status --porcelain").trim()) {
 			ctx.ui.notify(
 				`\n🔺 **/fix escalating: the single shot made NO changes** — nothing to verify, the full /debug pipeline takes over.`,
@@ -1482,9 +1572,19 @@ Tag the note with relevant keywords for vector search.
 				verified.push({ source: cand.source, patch: cand.patch, reproAfter: null, suite: null });
 				continue;
 			}
+			// Per-candidate suite: the recipe's, else the targeted tests of the
+			// modules THIS candidate touched (flask-4992 oracle upgrade).
+			let candSuite = suiteCmd;
+			if (!candSuite) {
+				const changed = gitIn(cwd, "diff --name-only")
+					.split("\n")
+					.map((s) => s.trim())
+					.filter(Boolean);
+				candSuite = discoverTargetedTests(changed, fsSeamsFor(cwd)).command;
+			}
 			const reproAfter =
 				cc.reproCmd && sandbox.available() ? sandbox.exec(cc.reproCmd, { timeoutMs: 10 * 60 * 1000 }) : null;
-			const suite = suiteCmd && sandbox.available() ? sandbox.exec(suiteCmd, { timeoutMs: 20 * 60 * 1000 }) : null;
+			const suite = candSuite && sandbox.available() ? sandbox.exec(candSuite, { timeoutMs: 20 * 60 * 1000 }) : null;
 			verified.push({ source: cand.source, patch: cand.patch, reproAfter, suite });
 			gitIn(cwd, "checkout -- .");
 			const rp = reproAfter
@@ -1494,7 +1594,7 @@ Tag the note with relevant keywords for vector search.
 			ctx.ui.notify(`  ${cand.source}: ${rp}, ${st}`, "info");
 		}
 
-		const outcome = decideVerify(verified, Boolean(suiteCmd));
+		const outcome = decideVerify(verified, Boolean(suiteCmd) || verified.some((v) => v.suite !== null));
 		if (outcome.verdict === "FIXED" && outcome.patch) {
 			applyPatch(outcome.patch);
 			finishGenericOrchestration(
@@ -1530,6 +1630,7 @@ Tag the note with relevant keywords for vector search.
 		const phase = phaseQueue.shift()!;
 		phasePending = true;
 		currentPhase = phase;
+		currentPhaseStartedAt = Date.now();
 		currentPhaseResult = null;
 		currentPhaseResultKey = null;
 
@@ -1550,6 +1651,17 @@ Tag the note with relevant keywords for vector search.
 					} catch {
 						/* best effort */
 					}
+					// Telemetry: a timed-out attempt is a row too (the observed
+					// phases:[] bug — the swallowed agent_end never pushed one).
+					runPhaseRecords.push({
+						key: phase.key,
+						label: phase.label,
+						model: phase.useFallback ? phase.fallback : phase.model,
+						verdict: "TIMEOUT",
+						retried: Boolean(phase.retried),
+						blockedRetried: Boolean(phase.blockedRetried),
+						durationMs: currentPhaseStartedAt ? Date.now() - currentPhaseStartedAt : undefined,
+					});
 					if (!phase.retried) {
 						phase.retried = true;
 						phase.useFallback = true;
@@ -1612,6 +1724,7 @@ Tag the note with relevant keywords for vector search.
 				verdict: outcome.verdict,
 				retried: Boolean(currentPhase.retried),
 				blockedRetried: Boolean(currentPhase.blockedRetried),
+				durationMs: currentPhaseStartedAt ? Date.now() - currentPhaseStartedAt : undefined,
 			});
 		}
 
@@ -1689,12 +1802,42 @@ Tag the note with relevant keywords for vector search.
 
 		if (candidateContext && currentPhase) {
 			const cwd = ctx.cwd || process.cwd();
+			if (currentPhase.key === "repro-audit") {
+				// The adversary may have EXTENDED the reproduction — its REPRO-CMD
+				// overrides the one REPRODUCE registered.
+				const updated = parseReproCmd(outcome.handoff);
+				if (updated && updated !== candidateContext.reproCmd) {
+					candidateContext.reproCmd = updated;
+					ctx.ui.notify(`\n🧷 Arbitration reproduction UPDATED by the audit: \`${updated}\``, "info");
+				}
+			}
 			if (currentPhase.key === "reproduce" && !candidateContext.reproCmd) {
 				candidateContext.reproCmd = parseReproCmd(outcome.handoff);
 				if (candidateContext.reproCmd) {
 					ctx.ui.notify(`\n🧷 Arbitration reproduction registered: \`${candidateContext.reproCmd}\``, "info");
 				}
 			}
+			if (
+				currentPhase.key === "localize" &&
+				candidateContext.parallelSpecs?.length &&
+				candidateContext.list.length === 0
+			) {
+				ctx.ui.notify(
+					`
+🧵 **Fanning ${candidateContext.parallelSpecs.length} FIX candidates out to parallel worktrees** (experimental)…`,
+					"info",
+				);
+				const fan = await runCandidateFanout(
+					cwd,
+					candidateContext.parallelSpecs.map((sp) => ({ model: sp.model, instruction: sp.instruction })),
+				);
+				for (const o of fan.outcomes) candidateContext.list.push({ source: o.source, patch: o.patch });
+				if (fan.failures.length) ctx.ui.notify(`⚠️ Candidate failures: ${fan.failures.join("; ")}`, "warning");
+				ctx.ui.notify(
+					`🧵 Fan-out done — ${fan.outcomes.filter((o) => o.ok).length}/${fan.outcomes.length} candidate patch(es) collected; arbitration next.`,
+					"info",
+				);
+			}
 			if (currentPhase.key === "fix-cand") {
 				const patch = gitIn(cwd, "diff").trim();
 				candidateContext.list.push({
@@ -1738,6 +1881,7 @@ Tag the note with relevant keywords for vector search.
 		if (mode !== "debug") candidateContext = null;
 		runPhaseRecords = [];
 		sandboxExecCount = 0;
+		sandboxExecMs = 0;
 		setOrchestrationActive(true);
 		phasePending = true;
 		originalModel = ctx.model || null;
@@ -1750,6 +1894,7 @@ Tag the note with relevant keywords for vector search.
 		phaseStartTime = Date.now();
 		const first = phases[0];
 		currentPhase = first;
+		currentPhaseStartedAt = Date.now();
 
 		ctx.ui.notify(headline, "info");
 		for (const p of phases) {
@@ -1775,6 +1920,15 @@ Tag the note with relevant keywords for vector search.
 					// Same policy as every other phase: one retry on the fallback
 					// model before skipping (the old skip-direct lost the whole run
 					// when the very first phase was slow).
+					runPhaseRecords.push({
+						key: first.key,
+						label: first.label,
+						model: first.useFallback ? first.fallback : first.model,
+						verdict: "TIMEOUT",
+						retried: Boolean(first.retried),
+						blockedRetried: Boolean(first.blockedRetried),
+						durationMs: currentPhaseStartedAt ? Date.now() - currentPhaseStartedAt : undefined,
+					});
 					if (!first.retried) {
 						first.retried = true;
 						first.useFallback = true;
@@ -2251,9 +2405,13 @@ It runs REPRODUCE → LOCALIZE → FIX → VERIFY and only reports FIXED with a
 			// Opt-in multi-candidate FIX: `--candidates N` (2..4). Diversity
 			// proposes (N model families patch independently), the oracle disposes
 			// (a real run arbitrates). Cost-disciplined: default stays 1.
+			const wantParallel = /(^|s)--parallel/.test(raw);
 			const candMatch = raw.match(/(^|\s)--candidates[= ](\d)\b/);
 			let candidates = candMatch ? Math.max(1, Math.min(4, Number(candMatch[2]))) : 1;
-			const cleaned = raw.replace(/(^|\s)--candidates[= ]\d\b/g, " ").trim();
+			const cleaned = raw
+				.replace(/(^|\s)--candidates[= ]\d\b/g, " ")
+				.replace(/(^|s)--parallel/g, " ")
+				.trim();
 			const cwd = ctx.cwd || process.cwd();
 
 			const state: FailingState = parseFailingState(cleaned, { cwd });
@@ -2287,13 +2445,22 @@ It runs REPRODUCE → LOCALIZE → FIX → VERIFY and only reports FIXED with a
 			}
 
 			await ensurePlansDir();
-			const phases = buildDebugPhases(state, candidates);
+			const parallel = wantParallel && candidates > 1;
+			const phases = buildDebugPhases(state, candidates, parallel);
 			if (candidates > 1) {
 				candidateContext = {
 					total: candidates,
 					reproCmd: state.failingTest?.trim() || state.reproCommand?.trim() || undefined,
 					list: [],
 					arbitrated: false,
+					parallelSpecs: parallel
+						? pickCandidateModels(readRoutingConfig(), candidates).map((model, i) => ({
+								model,
+								instruction: `${debugPhaseInstructions(state).fix}
+
+**Candidate protocol:** you are INDEPENDENT candidate ${i + 1} of ${candidates}, working in an isolated worktree. A REAL run arbitrates between candidates afterwards. Make your own best minimal fix.`,
+							}))
+						: undefined,
 				};
 			}
 			startGenericOrchestration(
@@ -2351,7 +2518,16 @@ With no runnable check at all, the result is honestly labelled UNVERIFIED.`,
 
 			await ensurePlansDir();
 			fixContext = { state, oracleRan: false };
+			// Tiered budget (measured: hard instances burned the whole run in the
+			// shot, leaving the escalation nothing): triage decides how long the
+			// single shot deserves before the pipeline takes over.
+			const t = triage({ text: raw, hasFailingState: Boolean(state.failingTest || state.reproCommand) });
 			const shot = genericPhase("shot", "🎯 Phase 1 — SINGLE SHOT", "code", "code", singleShotInstruction(state));
+			shot.timeoutMs = shotBudgetMs(t.route);
+			ctx.ui.notify(
+				`⏱️ Shot budget: ${Math.round(shotBudgetMs(t.route) / 60000)} min (triage: ${t.reason}).`,
+				"info",
+			);
 			// A real single shot legitimately runs 8–18 min (measured on the
 			// baselines); the flat 10 min phase cap was killing it mid-work.
 			shot.timeoutMs = 25 * 60 * 1000;
@@ -2419,6 +2595,43 @@ It reports SUCCESS only when a real run meets the acceptance criteria — otherw
 
 	// ─── /sandbox Command — inspect / prepare the guaranteed environment ──
 
+	// ─── /runs Command — exploit the telemetry (continuous measurement) ──
+
+	pi.registerCommand("runs", {
+		description: "Aggregate .phi/runs.jsonl — green-at-shot rate, escalations, durations, slowest phases",
+		handler: async (_args, ctx) => {
+			const cwd = ctx.cwd || process.cwd();
+			let blob = "";
+			try {
+				blob = readFileSync(join(cwd, ".phi", "runs.jsonl"), "utf-8");
+			} catch {
+				/* no file yet */
+			}
+			ctx.ui.notify(summarizeRuns(parseRunsJsonl(blob)), "info");
+		},
+	});
+
+	// ─── /fix suggestion — the measured-best default, surfaced once ─────
+	// A message that reads like a bug report gets a one-line tip pointing at
+	// /fix (never worse than a single shot, oracle-verified). Suggest once per
+	// session, never during an orchestration, and NEVER intercept the input.
+	let fixHintShown = false;
+	pi.on("input", async (event: any, ctx: any) => {
+		try {
+			const text = typeof event?.text === "string" ? event.text : "";
+			if (!fixHintShown && !orchestrationActive && looksLikeBugReport(text)) {
+				fixHintShown = true;
+				ctx.ui.notify(
+					"💡 This looks like a bug report — `/fix <the same text>` runs one attempt, verifies it in the sandbox oracle, and escalates to the full /debug pipeline only if a real run stays red.",
+					"info",
+				);
+			}
+		} catch {
+			/* a hint must never break input */
+		}
+		return undefined; // pass through untouched
+	});
+
 	pi.registerCommand("sandbox", {
 		description:
 			"Inspect or prepare the project's execution sandbox (Docker when available) — status | prepare | run <cmd>",

package/extensions/phi/providers/candidate-fanout.ts

@@ -0,0 +1,180 @@
+/**
+ * Parallel candidate generation in git WORKTREES (experimental).
+ *
+ * Sequential multi-candidate is safe (one tree, reset between attempts) but
+ * pays N× wall-clock. Worktrees give each candidate an isolated copy of the
+ * repo at HEAD, so N fixes run truly in parallel; the diffs come back to the
+ * main tree where the existing deterministic arbitration (real runs) picks the
+ * winner. Sub-candidates are separate phi processes (same pattern as
+ * explore-fanout), so a crash in one never corrupts another.
+ */
+
+import { spawn } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runCommand } from "./execution.js";
+import { getPiInvocation, isRateLimited } from "./explore-fanout.js";
+
+export interface CandidateSpec {
+	/** Model ref for this candidate (e.g. "alibaba-codingplan/qwen3.7-plus"). */
+	model: string;
+	/** The FIX instruction (already includes the candidate protocol note). */
+	instruction: string;
+}
+
+export interface CandidateOutcome {
+	source: string;
+	patch: string;
+	ok: boolean;
+	error?: string;
+}
+
+const CANDIDATE_TOOLS = ["read", "grep", "glob", "ls", "find", "edit", "write", "bash", "sandbox_run"];
+const HARD_CONCURRENCY = 2;
+const DEFAULT_TIMEOUT_MS = 12 * 60 * 1000;
+
+function git(cwd: string, args: string): { ok: boolean; out: string } {
+	const r = runCommand(`git ${args}`, { cwd, timeoutMs: 120_000 });
+	return { ok: r.exitCode === 0 && !r.timedOut, out: r.stdout };
+}
+
+export interface Worktree {
+	path: string;
+	remove(): void;
+}
+
+/**
+ * Create a detached worktree of HEAD in a temp dir, with the main tree's
+ * .phi/sandbox.json copied in (the sub-candidate must target the SAME
+ * guaranteed environment). Throws on failure — callers fall back to the
+ * sequential pipeline.
+ */
+export function createCandidateWorktree(mainCwd: string, index: number): Worktree {
+	const base = mkdtempSync(join(tmpdir(), `phi-cand-${index}-`));
+	const wt = join(base, "wt");
+	const add = git(mainCwd, `worktree add --detach "${wt}" HEAD`);
+	if (!add.ok) {
+		rmSync(base, { recursive: true, force: true });
+		throw new Error(`git worktree add failed for candidate ${index}`);
+	}
+	const sandboxCfg = join(mainCwd, ".phi", "sandbox.json");
+	if (existsSync(sandboxCfg)) {
+		mkdirSync(join(wt, ".phi"), { recursive: true });
+		copyFileSync(sandboxCfg, join(wt, ".phi", "sandbox.json"));
+	}
+	return {
+		path: wt,
+		remove() {
+			git(mainCwd, `worktree remove --force "${wt}"`);
+			rmSync(base, { recursive: true, force: true });
+			// prune bookkeeping for safety (best effort)
+			git(mainCwd, "worktree prune");
+		},
+	};
+}
+
+/** Diff of a worktree against its HEAD — the candidate's patch. */
+export function worktreePatch(wtPath: string): string {
+	const d = git(wtPath, "diff");
+	return d.ok && d.out.trim() ? `${d.out.trim()}\n` : "";
+}
+
+/** Run one candidate as a phi sub-process inside its worktree. Never throws. */
+export function runOneCandidate(
+	wtPath: string,
+	spec: CandidateSpec,
+	timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<CandidateOutcome> {
+	return new Promise((resolve) => {
+		const args = [
+			"--mode",
+			"json",
+			"-p",
+			"--no-session",
+			"--model",
+			spec.model,
+			"--tools",
+			CANDIDATE_TOOLS.join(","),
+		];
+		args.push(`Task: ${spec.instruction}`);
+		let proc: ReturnType<typeof spawn>;
+		try {
+			const inv = getPiInvocation(args);
+			proc = spawn(inv.command, inv.args, { cwd: wtPath, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+		} catch (e) {
+			resolve({ source: spec.model, patch: "", ok: false, error: String(e) });
+			return;
+		}
+		let blob = "";
+		const timer = setTimeout(() => {
+			try {
+				proc.kill();
+			} catch {
+				/* best effort */
+			}
+		}, timeoutMs);
+		proc.stdout?.on("data", (d) => {
+			blob += d.toString();
+		});
+		proc.stderr?.on("data", (d) => {
+			blob += d.toString();
+		});
+		const finish = () => {
+			clearTimeout(timer);
+			const patch = worktreePatch(wtPath);
+			resolve({
+				source: spec.model,
+				patch,
+				ok: patch.length > 0,
+				error: patch ? undefined : isRateLimited(blob) ? "rate-limited" : "no changes produced",
+			});
+		};
+		proc.on("close", finish);
+		proc.on("error", () => finish());
+	});
+}
+
+export interface FanoutRun {
+	outcomes: CandidateOutcome[];
+	failures: string[];
+}
+
+/**
+ * Run N candidates in parallel worktrees (concurrency-capped), ALWAYS cleaning
+ * the worktrees up. Returns every outcome; the caller feeds non-empty patches
+ * to the deterministic arbitration in the MAIN tree.
+ */
+export async function runCandidateFanout(
+	mainCwd: string,
+	specs: CandidateSpec[],
+	timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<FanoutRun> {
+	const outcomes: CandidateOutcome[] = [];
+	const failures: string[] = [];
+	for (let batch = 0; batch < specs.length; batch += HARD_CONCURRENCY) {
+		const slice = specs.slice(batch, batch + HARD_CONCURRENCY);
+		const settled = await Promise.all(
+			slice.map(async (spec, j) => {
+				let wt: Worktree | null = null;
+				try {
+					wt = createCandidateWorktree(mainCwd, batch + j);
+					return await runOneCandidate(wt.path, spec, timeoutMs);
+				} catch (e) {
+					return { source: spec.model, patch: "", ok: false, error: String(e) } as CandidateOutcome;
+				} finally {
+					try {
+						wt?.remove();
+					} catch {
+						/* best effort */
+					}
+				}
+			}),
+		);
+		for (const o of settled) {
+			outcomes.push(o);
+			if (!o.ok) failures.push(`${o.source}: ${o.error ?? "failed"}`);
+		}
+	}
+	return { outcomes, failures };
+}

package/extensions/phi/providers/debug-build-commands.ts

@@ -111,6 +111,33 @@ Reason: <only when BLOCKED>
 	};
 }
 
+/**
+ * The REPRO-AUDIT phase — red-team the reproduction ITSELF (the twice-measured
+ * failure: requests-2148 and flask-4992 both had a reproduction that validated
+ * the agent's interpretation while the project's real tests failed). A
+ * DIFFERENT model family answers one question — "which case stated in the
+ * issue is NOT covered by this reproduction?" — and extends it. Only used when
+ * the reproduction was CONSTRUCTED from prose; a user-supplied failing test is
+ * already ground truth.
+ */
+export function reproAuditInstruction(state: FailingState): string {
+	const failing = formatFailingState(state);
+	return `You are the REPRO-AUDIT agent (adversary). The previous phase CONSTRUCTED a reproduction from the issue text. Your single question: **which case stated in the issue is NOT covered by that reproduction?**
+
+**The issue / failing state:**
+${failing}
+
+**Do exactly this:**
+1. Read the reproduction script/command the previous phase reported (see its handoff and the repro file in the working tree).
+2. Compare it against the issue LITERALLY: every quoted snippet, input, expected value, and edge case named in the issue text. List what the reproduction does NOT exercise.
+3. If gaps exist: EXTEND the reproduction (edit the repro file — this is the one file you may edit) to cover them, then run it with \`sandbox_run\` — it must still FAIL on the current code for the same root cause.
+4. If the reproduction only passes because it mirrors an interpretation, not the issue: rewrite it from the issue's own examples and re-run.
+5. **Last action:** call \`phase_result\` with \`verdict: PASS\` (audited — gaps closed or none found) or \`verdict: BLOCKED\` (the issue cannot be reproduced as stated), and a handoff that MUST restate the final command on a machine-readable line:
+\`\`\`
+REPRO-CMD: <the exact, possibly updated, command>
+\`\`\`${DEBUG_RULES}`;
+}
+
 /**
  * The /fix single-shot phase — the measured-cheapest first attempt. One agent
  * fixes directly (baseline cost); the DRIVER then oracle-checks the result

package/extensions/phi/providers/escalation.ts

@@ -85,6 +85,22 @@ export function parseReproCmd(handoff: string | null | undefined): string | unde
 	return cmd && cmd.length > 1 ? cmd : undefined;
 }
 
+/**
+ * Tiered shot budget (drift guard, measured on sympy/sphinx): a hard instance
+ * must fail FAST at the shot so the escalation inherits real budget; an easy
+ * one deserves a longer single attempt since escalation is unlikely.
+ */
+export function shotBudgetMs(triageRoute: "single-shot" | "debug" | "build" | "plan"): number {
+	switch (triageRoute) {
+		case "single-shot":
+			return 12 * 60 * 1000; // likely to finish here — give it room
+		case "debug":
+			return 8 * 60 * 1000;
+		default:
+			return 6 * 60 * 1000; // build-scale/hard: fail fast, escalate with budget left
+	}
+}
+
 /** Minimal shape of routing.json this module needs (kept structural). */
 export interface RoutingLike {
 	routes?: Record<string, { preferredModel?: string; fallback?: string } | undefined>;

package/extensions/phi/providers/execution.ts

@@ -8,10 +8,102 @@
  * itself is exercised with trivial real commands.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 
 const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
 
+/**
+ * Kill a spawned process AND its children. On Windows, child.kill() only hits
+ * the direct child (a shell) — the actual workload (docker, pytest…) survives;
+ * taskkill /T fells the whole tree.
+ */
+function killTree(pid: number | undefined): void {
+	if (!pid) return;
+	try {
+		if (process.platform === "win32") {
+			spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true });
+		} else {
+			process.kill(-pid, "SIGKILL");
+		}
+	} catch {
+		/* best effort */
+	}
+}
+
+/**
+ * ASYNC command run — the drift fix. spawnSync blocks Node's event loop, so no
+ * JS timer (session timeouts, phase timeouts, a harness Promise.race) can fire
+ * while a command runs; long back-to-back runs measured a 25-minute cap
+ * drifting to 6h18. spawn keeps the loop alive: every watchdog fires on time,
+ * and the timeout here kills the whole process tree itself. Same contract as
+ * runCommand: never throws, everything comes back as data.
+ */
+export function runCommandAsync(command: string, options: RunOptions = {}): Promise<CommandResult> {
+	return spawnAsync(command, undefined, options, command);
+}
+
+/** ASYNC no-shell argv run — twin of runArgv (used for docker invocations). */
+export function runArgvAsync(
+	file: string,
+	args: string[],
+	options: RunOptions & { label?: string } = {},
+): Promise<CommandResult> {
+	return spawnAsync(file, args, options, options.label ?? `${file} ${args.join(" ")}`.trim());
+}
+
+function spawnAsync(
+	fileOrCommand: string,
+	args: string[] | undefined,
+	options: RunOptions,
+	label: string,
+): Promise<CommandResult> {
+	const start = Date.now();
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	return new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		let settled = false;
+		const child = args
+			? spawn(fileOrCommand, args, {
+					cwd: options.cwd,
+					env: options.env ?? process.env,
+					shell: false,
+					windowsHide: true,
+				})
+			: spawn(fileOrCommand, { cwd: options.cwd, env: options.env ?? process.env, shell: true, windowsHide: true });
+		const timer = setTimeout(() => {
+			timedOut = true;
+			killTree(child.pid);
+		}, timeoutMs);
+		const cap = (s: string, d: unknown) => {
+			const next = s + String(d);
+			return next.length > DEFAULT_MAX_BUFFER ? next.slice(-DEFAULT_MAX_BUFFER) : next;
+		};
+		child.stdout?.on("data", (d) => {
+			stdout = cap(stdout, d);
+		});
+		child.stderr?.on("data", (d) => {
+			stderr = cap(stderr, d);
+		});
+		const finish = (exitCode: number | null, extraErr?: string) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve({
+				command: label,
+				exitCode: timedOut ? null : exitCode,
+				stdout,
+				stderr: extraErr ? `${extraErr}\n${stderr}` : stderr,
+				durationMs: Date.now() - start,
+				timedOut,
+			});
+		};
+		child.on("error", (err) => finish(null, err.message));
+		child.on("close", (code) => finish(code));
+	});
+}
+
 export interface CommandResult {
 	command: string;
 	exitCode: number | null;

package/extensions/phi/providers/explore-fanout.ts

@@ -49,7 +49,7 @@ const HARD_CONCURRENCY_CAP = 2;
 const DEFAULT_TIMEOUT_MS = 4 * 60 * 1000;
 
 /** Re-invoke the current phi binary (so the sub-explorer is the same build). */
-function getPiInvocation(args: string[]): { command: string; args: string[] } {
+export function getPiInvocation(args: string[]): { command: string; args: string[] } {
 	const currentScript = process.argv[1];
 	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
 	if (currentScript && !isBunVirtualScript && existsSync(currentScript)) {

package/extensions/phi/providers/sandbox.ts

@@ -18,7 +18,9 @@ import {
 	passed,
 	type RunOptions,
 	runArgv as realRunArgv,
+	runArgvAsync as realRunArgvAsync,
 	runCommand as realRunCommand,
+	runCommandAsync as realRunCommandAsync,
 } from "./execution.js";
 import {
 	applyConfig,
@@ -45,19 +47,34 @@ export interface Sandbox {
 	readonly reason: string;
 	describe(): string;
 	available(): boolean;
-	/** Run a command in the environment. Never throws (see execution.ts). */
+	/** Run a command in the environment. Never throws (see execution.js). */
 	exec(command: string, options?: RunOptions): CommandResult;
+	/**
+	 * ASYNC twin of exec — non-blocking (the drift fix): the event loop stays
+	 * alive during the run, so session/phase timers fire on time and the run's
+	 * own timeout kills the process tree. Agent-facing paths (sandbox_run) MUST
+	 * use this; sync exec remains for bounded driver-internal steps.
+	 */
+	execAsync(command: string, options?: RunOptions): Promise<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;
+type RunCommandAsyncFn = (command: string, options?: RunOptions) => Promise<CommandResult>;
+type RunArgvAsyncFn = (
+	file: string,
+	args: string[],
+	options?: RunOptions & { label?: string },
+) => Promise<CommandResult>;
 
 /** Injectable seams — real fs/spawn by default, fakes in tests. */
 export interface SandboxDeps {
 	runCommand?: RunCommandFn;
 	runArgv?: RunArgvFn;
+	runCommandAsync?: RunCommandAsyncFn;
+	runArgvAsync?: RunArgvAsyncFn;
 	listFiles?: (cwd: string) => string[];
 	readConfig?: (cwd: string) => SandboxConfig | undefined;
 	/** Force docker availability in tests; otherwise probed via `docker version`. */
@@ -112,6 +129,8 @@ export function resolveSandbox(opts: ResolveOptions): Sandbox {
 	const deps = opts.deps ?? {};
 	const rc = deps.runCommand ?? realRunCommand;
 	const ra = deps.runArgv ?? realRunArgv;
+	const rcAsync = deps.runCommandAsync ?? realRunCommandAsync;
+	const raAsync = deps.runArgvAsync ?? realRunArgvAsync;
 	const files = (deps.listFiles ?? listProjectFiles)(opts.cwd);
 	const config = (deps.readConfig ?? readSandboxConfig)(opts.cwd);
 	const tc = detectToolchain(files);
@@ -128,8 +147,8 @@ export function resolveSandbox(opts: ResolveOptions): Sandbox {
 	// 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({
+	const dockerArgsFor = (command: string) =>
+		buildDockerRunArgs({
 			image: state.image,
 			command,
 			mountSource: opts.cwd,
@@ -139,12 +158,18 @@ export function resolveSandbox(opts: ResolveOptions): Sandbox {
 			memory: recipe.memory,
 			cpus: recipe.cpus,
 		});
-		return ra("docker", args, {
+	const dockerExec = (command: string, options?: RunOptions): CommandResult =>
+		ra("docker", dockerArgsFor(command), {
+			cwd: opts.cwd,
+			timeoutMs: options?.timeoutMs,
+			label: `docker[${state.image}] ${command}`,
+		});
+	const dockerExecAsync = (command: string, options?: RunOptions): Promise<CommandResult> =>
+		raAsync("docker", dockerArgsFor(command), {
 			cwd: opts.cwd,
 			timeoutMs: options?.timeoutMs,
 			label: `docker[${state.image}] ${command}`,
 		});
-	};
 
 	const base = { backend: decision.backend, recipe, reason: decision.reason };
 
@@ -154,6 +179,7 @@ export function resolveSandbox(opts: ResolveOptions): Sandbox {
 			describe: () => `unavailable — ${decision.reason}`,
 			available: () => false,
 			exec: (command) => unavailableResult(command),
+			execAsync: async (command) => unavailableResult(command),
 			prepare: () => ({ ok: false, backend: "unavailable", detail: decision.reason }),
 		};
 	}
@@ -164,6 +190,7 @@ export function resolveSandbox(opts: ResolveOptions): Sandbox {
 			describe: () => `local host (${opts.cwd})`,
 			available: () => true,
 			exec: (command, options) => rc(command, { cwd: opts.cwd, ...options }),
+			execAsync: (command, options) => rcAsync(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" }),
@@ -176,6 +203,7 @@ export function resolveSandbox(opts: ResolveOptions): Sandbox {
 		describe: () => `docker (${state.image})`,
 		available: () => true,
 		exec: dockerExec,
+		execAsync: dockerExecAsync,
 		prepare: () => {
 			if (recipe.source === "dockerfile") {
 				const tag = imageTagFor(recipe);

package/extensions/phi/providers/telemetry.ts

@@ -15,6 +15,72 @@ export interface PhaseRecord {
 	verdict: string | null;
 	retried: boolean;
 	blockedRetried: boolean;
+	/** Wall-clock of this phase attempt (ms); absent on legacy records. */
+	durationMs?: number;
+}
+
+/** Aggregate .phi/runs.jsonl records into a readable markdown summary. */
+export function summarizeRuns(records: RunRecord[]): string {
+	if (records.length === 0) return "No runs recorded yet — run /fix, /debug or /build first.";
+	const byMode = new Map<string, RunRecord[]>();
+	for (const r of records) {
+		const list = byMode.get(r.mode) ?? [];
+		list.push(r);
+		byMode.set(r.mode, list);
+	}
+	const pct = (n: number, d: number) => (d ? `${Math.round((100 * n) / d)}%` : "–");
+	const avg = (xs: number[]) => (xs.length ? Math.round(xs.reduce((a, b) => a + b, 0) / xs.length) : 0);
+	let out = `**Run telemetry** — ${records.length} run(s)\n\n`;
+	out +=
+		"| mode | runs | green/finished | blocked | unverified | avg duration | avg sandbox execs |\n|---|---|---|---|---|---|---|\n";
+	for (const [mode, rs] of byMode) {
+		const green = rs.filter((r) => /GREEN|FIXED|finished/i.test(r.outcome)).length;
+		const blocked = rs.filter((r) => /BLOCKED/i.test(r.outcome)).length;
+		const unv = rs.filter((r) => /UNVERIFIED/i.test(r.outcome)).length;
+		out += `| ${mode} | ${rs.length} | ${pct(green, rs.length)} | ${pct(blocked, rs.length)} | ${pct(unv, rs.length)} | ${Math.round(avg(rs.map((x) => x.durationMs)) / 1000)}s | ${avg(rs.map((x) => x.sandboxExecs))} |\n`;
+	}
+	// /fix specifics: how often the shot alone was enough (the promise metric).
+	const fixes = byMode.get("fix") ?? [];
+	if (fixes.length) {
+		const greenShot = fixes.filter((r) => /GREEN at single-shot cost/i.test(r.outcome)).length;
+		const escalated = fixes.filter((r) => r.phases.some((p) => p.key === "localize" || p.key === "reproduce")).length;
+		out += `\n/fix: green at single-shot cost ${pct(greenShot, fixes.length)}, escalated ${pct(escalated, fixes.length)}.\n`;
+	}
+	// Slowest phase kinds (durationMs is absent on legacy records).
+	const durs = new Map<string, number[]>();
+	for (const r of records)
+		for (const ph of r.phases)
+			if (typeof ph.durationMs === "number") {
+				const l = durs.get(ph.key) ?? [];
+				l.push(ph.durationMs);
+				durs.set(ph.key, l);
+			}
+	if (durs.size) {
+		const rows = [...durs]
+			.map(([k, xs]) => ({ k, avg: avg(xs), n: xs.length }))
+			.sort((a, b) => b.avg - a.avg)
+			.slice(0, 5);
+		out += `\nSlowest phases (avg): ${rows.map((r) => `${r.k} ${Math.round(r.avg / 1000)}s ×${r.n}`).join(", ")}.\n`;
+	}
+	const timeouts = records.flatMap((r) => r.phases).filter((p) => p.verdict === "TIMEOUT").length;
+	if (timeouts) out += `\n⏰ ${timeouts} phase timeout(s) recorded.\n`;
+	return out;
+}
+
+/** Parse a runs.jsonl blob (tolerant: bad lines are skipped). */
+export function parseRunsJsonl(blob: string): RunRecord[] {
+	const out: RunRecord[] = [];
+	for (const line of blob.split("\n")) {
+		const t = line.trim();
+		if (!t) continue;
+		try {
+			const r = JSON.parse(t);
+			if (r && typeof r.mode === "string" && Array.isArray(r.phases)) out.push(r as RunRecord);
+		} catch {
+			/* skip */
+		}
+	}
+	return out;
 }
 
 export interface RunRecord {

package/extensions/phi/providers/test-discovery.ts

@@ -0,0 +1,119 @@
+/**
+ * Targeted-test discovery — the oracle upgrade the flask-4992 measurement
+ * demanded: the driver oracle validated the agent's own reproduction (exit 0)
+ * while the project's REAL tests for the touched module failed. Running the
+ * full suite is usually too slow/foreign (django ≠ pytest); the right-sized
+ * check is the EXISTING test files that belong to the modules the change
+ * touched. Pure logic with fs seams so every heuristic is unit-tested.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface DiscoverySeams {
+	/** Does this repo-relative path exist? */
+	exists(relPath: string): boolean;
+	/** package.json content (for JS runner detection); null when absent. */
+	readPackageJson(): { devDependencies?: Record<string, string>; dependencies?: Record<string, string> } | null;
+}
+
+const PY_EXT = /\.py$/;
+const JS_EXT = /\.(ts|tsx|js|jsx|mjs)$/;
+
+function posix(p: string): string {
+	return p.replace(/\\/g, "/");
+}
+
+/** Candidate test-file locations for one changed source file. */
+export function testCandidatesFor(changedFile: string): string[] {
+	const f = posix(changedFile);
+	const dir = f.includes("/") ? f.slice(0, f.lastIndexOf("/")) : "";
+	const base = f.slice(f.lastIndexOf("/") + 1);
+	const stem = base.replace(/\.[^.]+$/, "");
+	const d = (s: string) => (dir ? `${dir}/${s}` : s);
+
+	if (PY_EXT.test(base)) {
+		if (base.startsWith("test_")) return [f]; // a test itself
+		return [
+			d(`test_${base}`),
+			d(`tests/test_${base}`),
+			`tests/test_${stem}.py`,
+			`test/test_${stem}.py`,
+			// package-level tests dir next to the module's parent (e.g. pkg/mod/x.py → pkg/tests/test_x.py)
+			dir.includes("/") ? `${dir.slice(0, dir.lastIndexOf("/"))}/tests/test_${stem}.py` : "",
+		].filter(Boolean);
+	}
+
+	if (JS_EXT.test(base)) {
+		if (/\.(test|spec)\./.test(base)) return [f];
+		const exts = ["ts", "tsx", "js", "mjs"];
+		const out: string[] = [];
+		for (const e of exts) {
+			out.push(
+				d(`${stem}.test.${e}`),
+				d(`__tests__/${stem}.test.${e}`),
+				`test/${stem}.test.${e}`,
+				`tests/${stem}.test.${e}`,
+			);
+		}
+		return out;
+	}
+
+	return [];
+}
+
+export interface TargetedTests {
+	/** Existing test files that cover the changed modules. */
+	files: string[];
+	/** A runnable command for them, or undefined when none could be built. */
+	command?: string;
+}
+
+/**
+ * Discover the existing targeted tests for a set of changed files and build one
+ * command to run them. Python → pytest; JS → vitest/jest when present in
+ * package.json. Deduped, capped (a huge change should not queue a full suite by
+ * the back door).
+ */
+export function discoverTargetedTests(changedFiles: string[], seams: DiscoverySeams, cap = 5): TargetedTests {
+	const found: string[] = [];
+	for (const cf of changedFiles) {
+		for (const cand of testCandidatesFor(cf)) {
+			if (!found.includes(cand) && seams.exists(cand)) {
+				found.push(cand);
+				break; // first existing candidate per changed file is enough
+			}
+		}
+		if (found.length >= cap) break;
+	}
+	if (found.length === 0) return { files: [] };
+
+	if (found.every((f) => PY_EXT.test(f))) {
+		return { files: found, command: `python -m pytest ${found.join(" ")} -x -q` };
+	}
+	const pkg = seams.readPackageJson();
+	const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+	if (deps.vitest) return { files: found, command: `npx vitest run ${found.join(" ")}` };
+	if (deps.jest) return { files: found, command: `npx jest ${found.join(" ")}` };
+	return { files: found };
+}
+
+/** Real-fs seams for a repo root. */
+export function fsSeamsFor(cwd: string): DiscoverySeams {
+	return {
+		exists: (rel) => {
+			try {
+				return existsSync(join(cwd, rel));
+			} catch {
+				return false;
+			}
+		},
+		readPackageJson: () => {
+			try {
+				return JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8"));
+			} catch {
+				return null;
+			}
+		},
+	};
+}

package/extensions/phi/providers/triage.ts

@@ -54,6 +54,21 @@ export function estimateFiles(text: string): number {
  * decision out. Order matters — a forced mode wins, then a real failing state
  * (cheapest useful oracle), then build-scale, else single shot.
  */
+const BUG_SHAPE =
+	/\b(traceback|exception|stack ?trace|segfault|error:|fails?\b|failing|broken|crash(es|ed)?|bug\b|régression|regression|ne (marche|fonctionne) (pas|plus)|plante)\b/i;
+
+/**
+ * Does a free-form user message look like a bug report? Used to suggest /fix
+ * once (the measured-best default: never worse than a single shot, oracle-
+ * verified). Deliberately conservative — suggestion, never interception.
+ */
+export function looksLikeBugReport(text: string): boolean {
+	const t = text.trim();
+	if (!t || t.startsWith("/")) return false;
+	if (t.length < 15) return false;
+	return BUG_SHAPE.test(t);
+}
+
 export function triage(signals: TriageSignals): TriageDecision {
 	if (signals.forced) {
 		return {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@phi-code-admin/phi-code",
-	"version": "0.94.0",
+	"version": "0.96.0",
 	"description": "Coding agent CLI with persistent memory, sub-agents, intelligent routing, and orchestration",
 	"type": "module",
 	"piConfig": {