@phi-code-admin/phi-code 0.80.0 → 0.82.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.82.0] - 2026-06-14
+
+### Added
+
+- **Opt-in parallel EXPLORE fan-out** (`/plan --fanout <description>`). Before
+  phase 1, the orchestrator runs up to **2 concurrent read-only** sub-explorers,
+  each with a narrow mandate (architecture & reusable patterns, impacted files,
+  risks & constraints), and merges their findings into the EXPLORE context. This
+  applies the perspective-diverse pattern to the front of the pipeline so the
+  downstream phases start from a fuller, more accurate map.
+
+  Guardrails (the fan-out is best-effort and never breaks a run): default OFF
+  (single-agent EXPLORE unchanged); read-only tool set only (no write/edit/bash);
+  hard concurrency cap of 2 against the single rate-limited key; **adaptive
+  fallback to sequential** the moment a sub-explorer reports a 429 / rate limit;
+  a per-explorer timeout that kills the process; and full graceful degradation to
+  the normal EXPLORE on any error, empty result, or rate limit. Experimental: not
+  yet validated against a live proxy at scale, hence opt-in.
+
+## [0.81.0] - 2026-06-14
+
+Marathon increment 4 (prompt-only, low risk).
+
+### Changed
+
+- **Memory discipline.** The per-turn reminder now tells the model to (1) save only
+  non-obvious, cross-session facts (not what git already records) and (2)
+  verify-before-trust: a recalled note describes a PAST state, so confirm it against
+  the live code before acting, and the current observation wins on conflict.
+- **REVIEW final sweep.** On large diffs, the reviewer re-reads the diff once more
+  as if fresh and adds only genuinely new bugs (no padding).
+- **Run Recipe.** EXPLORE records a `## Run Recipe` (build/run command, port, ready
+  signal) in the brief; TEST uses it to actually run the code and to tell a real
+  failure (FAIL) from a stale launch recipe (BLOCKED).
+
 ## [0.80.0] - 2026-06-14
 
 Marathon increment 3: context protection, productivity commands, and the

package/extensions/phi/memory.ts

@@ -665,9 +665,15 @@ REMINDER (project rule, applies every turn):
    project context, prior decisions, and saved learnings are accessible
    ONLY via this tool.
 2. AFTER completing significant work, call \`memory_write\` to save what
-   you did and learned.
-
-These two tool calls are not optional. Skipping them violates project rules.
+   you did and learned. Save only NON-OBVIOUS, cross-session facts and user
+   preferences; do NOT save what the repo or git history already records.
+3. Saved notes describe a PAST state. Before you act on a recalled fact,
+   verify it against the CURRENT code (read/grep that the path or symbol still
+   exists). If it conflicts, the live observation wins. Do not delete a stale
+   note; note the divergence.
+
+The memory_search and memory_write calls are not optional. Skipping them
+violates project rules.
 </system-reminder>
 
 `;

package/extensions/phi/orchestrator.ts

@@ -28,6 +28,7 @@ import {
 	isTransientError,
 	parsePhaseVerdict,
 } from "./providers/orchestrator-helpers.js";
+import { defaultExplorerSpecs, READONLY_EXPLORER_TOOLS, runExploreFanout } from "./providers/explore-fanout.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -414,6 +415,7 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
    - Requirements: specific features needed
    - Tech decisions: frameworks, patterns to use
    - Constraints: what to NOT break
+   - Run Recipe: from package.json scripts / Makefile / Dockerfile / README, a \`## Run Recipe\` with the build command, run command, port/URL, and ready signal (the TEST phase uses this to actually run the code)
 5. **MANDATORY:** Write your findings to \`.phi/plans/explore-${ts}.md\` using the \`write\` tool. This file is READ by Phase 2 PLAN — if you skip it, the plan agent has no context. Do NOT skip this step.
 
 **LAST ACTION (MANDATORY):** Call \`memory_write\` to save your exploration findings for downstream agents.
@@ -580,6 +582,8 @@ $ <command actually executed>
 - Error: ... -> Fix: ...
 \`\`\`
 
+**Launch:** if the brief contains a "## Run Recipe" (build command, run command, port/URL, ready signal), use it. Distinguish a real failure (FAIL) from a stale launch recipe (BLOCKED) and report the recipe that actually works.
+
 **Verdict rules:** PASS only if you OBSERVED every feature working at runtime. When in doubt, FAIL. No partial pass (3/4 working = FAIL). Use BLOCKED only when you could not run anything (broken launch recipe, missing env, provider down) and say what is needed.
 
 **CRITICAL RULES:**
@@ -640,6 +644,8 @@ After testing, use \`memory_write\` to save test results, bugs found, and lesson
 - path/file.ts:123 - <what must change and why>
 \`\`\`
 
+**Final sweep (large diffs only):** before writing the verdict, re-read the diff once more as if you had never seen it; add ONLY bugs not already in your list. If there are none, do not pad.
+
 **Verdict rules:** VERDICT: FAIL if there is ANY CONFIRMED correctness/security finding (it goes under BLOCKING). VERDICT: PASS only if BLOCKING is empty. Do NOT pad: if the code is clean, return PASS with no findings.
 
 After your review, use \`memory_write\` ONCE to save:
@@ -1132,10 +1138,13 @@ Tag the note with relevant keywords for vector search.
 				return;
 			}
 
-			const description = rawArgs;
+			// Opt-in: `--fanout` runs a small read-only parallel exploration before
+			// phase 1 (default OFF — single-agent EXPLORE, the safe behaviour).
+			const wantFanout = /(^|\s)--fanout\b/.test(rawArgs);
+			const description = rawArgs.replace(/(^|\s)--fanout\b/g, " ").trim();
 
 			if (!description) {
-				ctx.ui.notify(`**Usage:** \`/plan <project description>\` (or \`/plan --resume\` to continue a checkpointed run)
+				ctx.ui.notify(`**Usage:** \`/plan <project description>\` (or \`/plan --resume\` to continue a checkpointed run, \`/plan --fanout <desc>\` for parallel exploration)
 
 **Examples:**
   /plan Build a REST API for user authentication with JWT
@@ -1183,6 +1192,35 @@ Tag the note with relevant keywords for vector search.
 
 			// Record orchestration start time for final summary
 			phaseStartTime = Date.now();
+
+			// Opt-in parallel EXPLORE fan-out (read-only, <=2 concurrent, sequential
+			// fallback on rate limit). Best-effort: any failure degrades to the normal
+			// single-agent EXPLORE below by simply not enriching the instruction.
+			if (wantFanout) {
+				try {
+					const available = ctx.modelRegistry?.getAvailable?.() || [];
+					const exploreModelId = resolveModelRef(available, firstPhase.model)?.id || firstPhase.model;
+					ctx.ui.notify(`\n🔭 **Parallel exploration** (read-only, up to 2 concurrent) — building a fuller map before phase 1...`, "info");
+					const fan = await runExploreFanout(defaultExplorerSpecs(description), {
+						model: exploreModelId,
+						tools: READONLY_EXPLORER_TOOLS,
+						cwd: ctx.cwd || process.cwd(),
+						concurrency: 2,
+						timeoutMs: 4 * 60 * 1000,
+					});
+					const okCount = fan.results.filter((r) => r.ok).length;
+					if (fan.merged.trim()) {
+						firstPhase.instruction =
+							`## Parallel exploration findings (${okCount} read-only sub-explorer(s))\nUse these as a starting map; verify and synthesize them into your brief, do not trust them blindly.\n\n${fan.merged}\n\n---\n${firstPhase.instruction}`;
+						ctx.ui.notify(`\n🔭 ${okCount} sub-exploration(s) merged into EXPLORE${fan.rateLimited ? " (rate limit hit — ran the rest sequentially)" : ""}.`, "info");
+					} else {
+						ctx.ui.notify(`\n🔭 Parallel exploration returned nothing usable${fan.rateLimited ? " (rate-limited)" : ""} — running the normal single-agent EXPLORE.`, "warning");
+					}
+				} catch {
+					ctx.ui.notify(`\n🔭 Parallel exploration skipped (error) — running the normal single-agent EXPLORE.`, "warning");
+				}
+			}
+
 			// Switch model and activate agent for first phase
 			const { modelId, warning } = await switchModelForPhase(firstPhase, ctx);
 			activateAgent(firstPhase, ctx);

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

@@ -0,0 +1,199 @@
+/**
+ * Opt-in parallel EXPLORE fan-out for the /plan orchestrator.
+ *
+ * Spawns a small number of read-only `pi` sub-explorers, each with a narrow focus
+ * (architecture / impacted files / risks), and merges their findings into the
+ * EXPLORE phase context. This is the perspective-diverse pattern applied to the
+ * front of the pipeline: a more complete map of the codebase means better
+ * downstream plan/code/test phases.
+ *
+ * GUARDRAILS (this whole module is best-effort and NEVER throws):
+ *  - Read-only only: sub-explorers get a read-only tool set, no write/edit/bash.
+ *  - Hard concurrency cap of 2 (a single rate-limited proxy key is the constraint).
+ *  - Adaptive fallback: if any sub-explorer reports a 429 / rate limit, the
+ *    remaining ones run sequentially (concurrency drops to 1).
+ *  - Per-explorer timeout, with the process killed on expiry.
+ *  - Any failure (spawn error, timeout, no output, rate limit) degrades to "no
+ *    findings" so the orchestrator simply runs the normal single-agent EXPLORE.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
+
+export interface ExplorerSpec {
+	focus: string;
+	prompt: string;
+}
+
+export interface ExplorerResult {
+	focus: string;
+	text: string;
+	ok: boolean;
+	rateLimited: boolean;
+	error?: string;
+}
+
+export interface FanoutOptions {
+	model?: string;
+	tools?: string[];
+	cwd?: string;
+	concurrency?: number;
+	timeoutMs?: number;
+}
+
+/** Read-only tools handed to every sub-explorer. */
+export const READONLY_EXPLORER_TOOLS = ["read", "grep", "glob", "ls", "find", "memory_search", "memory_read"];
+
+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[] } {
+	const currentScript = process.argv[1];
+	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+	if (currentScript && !isBunVirtualScript && existsSync(currentScript)) {
+		return { command: process.execPath, args: [currentScript, ...args] };
+	}
+	const execName = basename(process.execPath).toLowerCase();
+	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+	if (!isGenericRuntime) return { command: process.execPath, args };
+	return { command: "pi", args };
+}
+
+export function isRateLimited(text: string): boolean {
+	return /\b429\b|rate.?limit(ed)?|too many requests|overloaded|quota exceeded|resource exhausted/i.test(text);
+}
+
+/** Run one sub-explorer. Never throws; always resolves to an ExplorerResult. */
+function runOneExplorer(spec: ExplorerSpec, opts: FanoutOptions): Promise<ExplorerResult> {
+	return new Promise((resolve) => {
+		const args = ["--mode", "json", "-p", "--no-session"];
+		if (opts.model) args.push("--model", opts.model);
+		const tools = opts.tools && opts.tools.length > 0 ? opts.tools : READONLY_EXPLORER_TOOLS;
+		args.push("--tools", tools.join(","));
+		args.push(`Task: ${spec.prompt}`);
+
+		let proc: ReturnType<typeof spawn>;
+		try {
+			const inv = getPiInvocation(args);
+			proc = spawn(inv.command, inv.args, { cwd: opts.cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+		} catch (e) {
+			resolve({ focus: spec.focus, text: "", ok: false, rateLimited: false, error: String(e) });
+			return;
+		}
+
+		let buffer = "";
+		let finalText = "";
+		let stderr = "";
+		let errorMessage = "";
+		let settled = false;
+
+		const timer = setTimeout(() => {
+			try {
+				proc.kill();
+			} catch {
+				/* best effort */
+			}
+		}, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+
+		const processLine = (line: string) => {
+			if (!line.trim()) return;
+			let event: any;
+			try {
+				event = JSON.parse(line);
+			} catch {
+				return;
+			}
+			if (event?.type === "message_end" && event.message?.role === "assistant") {
+				const parts = event.message.content;
+				if (Array.isArray(parts)) {
+					for (const p of parts) {
+						if (p?.type === "text" && typeof p.text === "string") finalText = p.text;
+					}
+				}
+				if (event.message.errorMessage) errorMessage = String(event.message.errorMessage);
+			}
+		};
+
+		const finish = (timedOut: boolean) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			if (buffer.trim()) processLine(buffer);
+			const blob = `${finalText}\n${errorMessage}\n${stderr}`;
+			const rateLimited = isRateLimited(blob);
+			const ok = !timedOut && finalText.trim().length > 0 && !rateLimited;
+			resolve({
+				focus: spec.focus,
+				text: finalText,
+				ok,
+				rateLimited,
+				error: errorMessage || (ok ? undefined : timedOut ? "timeout" : "no output"),
+			});
+		};
+
+		proc.stdout?.on("data", (data) => {
+			buffer += data.toString();
+			const lines = buffer.split("\n");
+			buffer = lines.pop() || "";
+			for (const line of lines) processLine(line);
+		});
+		proc.stderr?.on("data", (data) => {
+			stderr += data.toString();
+		});
+		proc.on("error", (e) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve({ focus: spec.focus, text: "", ok: false, rateLimited: false, error: String(e) });
+		});
+		proc.on("close", () => finish(false));
+	});
+}
+
+/**
+ * Run the sub-explorers with a hard concurrency cap of 2; if a batch hits a rate
+ * limit, drop to sequential for the rest. Returns the merged findings (markdown)
+ * plus the raw results. Best-effort: callers should fall back to the normal
+ * single-agent EXPLORE when `merged` is empty.
+ */
+export async function runExploreFanout(
+	specs: ExplorerSpec[],
+	opts: FanoutOptions,
+): Promise<{ results: ExplorerResult[]; merged: string; rateLimited: boolean }> {
+	let concurrency = Math.max(1, Math.min(opts.concurrency ?? HARD_CONCURRENCY_CAP, HARD_CONCURRENCY_CAP));
+	const results: ExplorerResult[] = [];
+	let i = 0;
+	while (i < specs.length) {
+		const batch = specs.slice(i, i + concurrency);
+		const batchResults = await Promise.all(batch.map((s) => runOneExplorer(s, opts)));
+		results.push(...batchResults);
+		i += batch.length;
+		// Adaptive backoff: a rate limit means the single key is saturated, so
+		// serialize whatever is left rather than push harder.
+		if (batchResults.some((r) => r.rateLimited)) concurrency = 1;
+	}
+	const ok = results.filter((r) => r.ok && r.text.trim());
+	const merged = ok.map((r) => `### Exploration — ${r.focus}\n${r.text.trim()}`).join("\n\n");
+	return { results, merged, rateLimited: results.some((r) => r.rateLimited) };
+}
+
+/** The default narrow-mandate explorer specs for a /plan request. */
+export function defaultExplorerSpecs(description: string): ExplorerSpec[] {
+	const base = `Read-only exploration. Do NOT modify any file. Be concise and cite file:line.`;
+	return [
+		{
+			focus: "architecture & reusable patterns",
+			prompt: `${base}\nProject request: ${description}\nExplore the codebase architecture: tech stack, key modules/directories, the conventions and existing utilities/functions to REUSE, and how the pieces fit together.`,
+		},
+		{
+			focus: "impacted files",
+			prompt: `${base}\nProject request: ${description}\nIdentify the files and code that will be IMPACTED: grep the relevant symbols, find callers and callees, and list the exact files (file:line) that will likely need changes and why.`,
+		},
+		{
+			focus: "risks & constraints",
+			prompt: `${base}\nProject request: ${description}\nIdentify risks, edge cases, and constraints to NOT break: behaviour that must be preserved, error handling, security, and tests that cover the area.`,
+		},
+	];
+}

package/package.json

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