ultimate-pi 0.17.0 → 0.18.1

package/.pi/extensions/lib/plan-approval-readiness.ts

@@ -0,0 +1,192 @@
+/**
+ * Pre-approve_plan readiness checks (planning context, research, phase status).
+ */
+
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+export interface PlanApprovalReadiness {
+	ok: boolean;
+	errors: string[];
+	warnings: string[];
+}
+
+const PLANNING_CONTEXT_ARTIFACT = "artifacts/planning-context.yaml";
+
+const PHASE35_ARTIFACTS = [
+	"artifacts/implementation-research.yaml",
+	"artifacts/stack.yaml",
+] as const;
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function readYamlObject(
+	path: string,
+): Promise<Record<string, unknown> | null> {
+	try {
+		const raw = await readFile(path, "utf-8");
+		const doc = parseYaml(raw) as unknown;
+		return doc && typeof doc === "object" && !Array.isArray(doc)
+			? (doc as Record<string, unknown>)
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+async function hasPhaseWaiver(
+	runDir: string,
+	reason: string,
+): Promise<boolean> {
+	const path = join(runDir, "artifacts", "plan-phase-waiver.yaml");
+	const doc = await readYamlObject(path);
+	if (!doc) return false;
+	const waived = doc.waived as unknown;
+	if (!Array.isArray(waived)) return false;
+	return waived.some((w) => {
+		if (!w || typeof w !== "object") return false;
+		const entry = w as Record<string, unknown>;
+		return String(entry.reason ?? "") === reason;
+	});
+}
+
+function artifactStatusBad(
+	doc: Record<string, unknown> | null,
+	label: string,
+): string | null {
+	const status = String(doc?.status ?? "ok").toLowerCase();
+	if (status === "partial" || status === "failed" || status === "error") {
+		return `${label}: status "${status}" without waiver`;
+	}
+	return null;
+}
+
+function coverageLaneStatus(
+	doc: Record<string, unknown> | null,
+	lane: string,
+): string {
+	const coverage = doc?.coverage as Record<string, unknown> | undefined;
+	if (!coverage || typeof coverage !== "object") return "";
+	const laneDoc = coverage[lane] as Record<string, unknown> | undefined;
+	return String(laneDoc?.status ?? "").toLowerCase();
+}
+
+async function validatePlanningContext(
+	runDir: string,
+	quick: boolean,
+	errors: string[],
+): Promise<boolean> {
+	const rel = PLANNING_CONTEXT_ARTIFACT;
+	const abs = join(runDir, rel);
+	if (!(await fileExists(abs))) {
+		return false;
+	}
+	const doc = await readYamlObject(abs);
+	const bad = artifactStatusBad(doc, rel);
+	if (bad) {
+		const waived = await hasPhaseWaiver(
+			runDir,
+			`planning-context:${String(doc?.status ?? "")}`,
+		);
+		if (!waived) {
+			errors.push(bad);
+		}
+	}
+	const arch = coverageLaneStatus(doc, "architecture");
+	const structure = coverageLaneStatus(doc, "structure");
+	if (arch !== "ok" && arch !== "partial") {
+		errors.push(
+			`${rel}: coverage.architecture.status must be ok or partial (got "${arch || "missing"}")`,
+		);
+	}
+	if (structure !== "ok" && structure !== "partial") {
+		errors.push(
+			`${rel}: coverage.structure.status must be ok or partial (got "${structure || "missing"}")`,
+		);
+	}
+	if (!quick) {
+		const semantic = coverageLaneStatus(doc, "semantic");
+		if (
+			semantic &&
+			semantic !== "ok" &&
+			semantic !== "partial" &&
+			semantic !== "skipped"
+		) {
+			errors.push(
+				`${rel}: coverage.semantic.status must be ok, partial, or skipped (got "${semantic}")`,
+			);
+		}
+	}
+	return true;
+}
+
+export async function validatePlanApprovalReadiness(
+	projectRoot: string,
+	runId: string,
+	opts?: { risk_level?: string; quick?: boolean },
+): Promise<PlanApprovalReadiness> {
+	const runDir = join(projectRoot, ".pi", "harness", "runs", runId);
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const risk = String(opts?.risk_level ?? "med").toLowerCase();
+	const quick = opts?.quick === true;
+
+	const statusPath = join(runDir, "artifacts", "plan-phase-status.yaml");
+	const statusDoc = await readYamlObject(statusPath);
+	if (statusDoc) {
+		const planStatus = String(statusDoc.plan_status ?? "").toLowerCase();
+		if (planStatus === "partial" || planStatus === "needs_clarification") {
+			const waived = await hasPhaseWaiver(runDir, `plan_status:${planStatus}`);
+			if (!waived) {
+				errors.push(
+					`plan phase status is "${planStatus}" — resolve gaps, set plan_status ready, or write artifacts/plan-phase-waiver.yaml`,
+				);
+			}
+		}
+	}
+
+	const hasPlanningContext = await validatePlanningContext(
+		runDir,
+		quick,
+		errors,
+	);
+
+	if (!hasPlanningContext) {
+		const waived = await hasPhaseWaiver(
+			runDir,
+			"missing:planning-reconnaissance",
+		);
+		if (!waived) {
+			errors.push(`missing ${PLANNING_CONTEXT_ARTIFACT}`);
+		}
+	}
+
+	for (const rel of PHASE35_ARTIFACTS) {
+		const abs = join(runDir, rel);
+		if (!(await fileExists(abs))) {
+			if (risk === "high" || risk === "med") {
+				errors.push(`missing ${rel} (Phase 3.5 required for risk ${risk})`);
+			} else {
+				warnings.push(`missing ${rel} (recommended for risk ${risk})`);
+			}
+		}
+	}
+
+	if (!(await fileExists(join(runDir, "artifacts/decomposition.yaml")))) {
+		errors.push("missing artifacts/decomposition.yaml");
+	}
+	if (!(await fileExists(join(runDir, "artifacts/hypothesis.yaml")))) {
+		errors.push("missing artifacts/hypothesis.yaml");
+	}
+
+	return { ok: errors.length === 0, errors, warnings };
+}

package/.pi/extensions/lib/plan-debate-eligibility.ts

@@ -126,7 +126,7 @@ export const PLAN_BUDGET_FAST = {
 } as const;
 
 export interface PlanReviewGateStrategy {
-	mode: "consolidated" | "threaded";
+	mode: "consolidated" | "threaded" | "parallel_probes";
 	profile: DebateProfile;
 	required_focuses: PlanDebateFocus[];
 	min_focus_rounds: number;
@@ -232,9 +232,9 @@ export function harnessPlanDebateEligibility(
 		confidenceAllowsLight(impl) &&
 		stackHasClearPrimary(stack)
 	) {
-		profile = "fast";
+		profile = "light";
 		rationale.push(
-			"fast: low risk, clear stack, high-confidence implementation approach",
+			"light: low risk, clear stack, high-confidence implementation (threaded spec+quality)",
 		);
 	} else if (risk === "med") {
 		profile = "standard";
@@ -242,7 +242,9 @@ export function harnessPlanDebateEligibility(
 	}
 
 	const required_focuses: PlanDebateFocus[] =
-		profile === "fast" ? [...LIGHT_FOCUS] : [...PLAN_FOCUS_AREAS];
+		profile === "fast" || profile === "light"
+			? [...LIGHT_FOCUS]
+			: [...PLAN_FOCUS_AREAS];
 
 	const caps = capsForProfile(profile);
 
@@ -253,7 +255,12 @@ export function harnessPlanDebateEligibility(
 		human_required,
 		rationale,
 		review_gate_strategy: {
-			mode: profile === "fast" ? "consolidated" : "threaded",
+			mode:
+				profile === "fast"
+					? "consolidated"
+					: profile === "standard"
+						? "parallel_probes"
+						: "threaded",
 			profile,
 			required_focuses: [...required_focuses],
 			min_focus_rounds: caps.min_focus_rounds,

package/.pi/extensions/lib/plan-debate-gate.ts

@@ -16,6 +16,7 @@ import {
 import { planDebateIdForRun } from "./plan-debate-id.js";
 import {
 	laneArtifactPathsForConsolidatedRound,
+	laneArtifactPathsForParallelProbesRound,
 	laneArtifactPathsForRound,
 } from "./plan-debate-lanes.js";
 import {
@@ -26,6 +27,7 @@ import {
 import {
 	CONSOLIDATED_REVIEW_ARTIFACT,
 	isConsolidatedReviewStrategy,
+	isParallelProbesReviewStrategy,
 	planReviewGateStrategyFromEligibility,
 } from "./plan-review-gate.js";
 
@@ -114,6 +116,7 @@ export async function validatePlanDebateGate(
 						rationale: [],
 					};
 	const consolidated = isConsolidatedReviewStrategy(reviewStrategy);
+	const parallelProbes = isParallelProbesReviewStrategy(reviewStrategy);
 	const coverage = await getPlanFocusCoverage(runDir, { requiredFocuses });
 	const dialogueOpts = {
 		max_exchanges_per_round: caps.max_exchanges_per_round,
@@ -126,7 +129,25 @@ export async function validatePlanDebateGate(
 		errors.push("last submitted review round has review_gate_ready !== true");
 	}
 
-	if (consolidated) {
+	if (parallelProbes) {
+		for (const rel of laneArtifactPathsForParallelProbesRound()) {
+			const abs = join(runDir, rel);
+			if (!(await fileExists(abs))) {
+				errors.push(`missing ${rel}`);
+			}
+		}
+		const roundState = await getMessengerRoundState(runDir, 1);
+		const messengerCheck = messengerRoundDebateReady(
+			roundState,
+			false,
+			dialogueOpts,
+		);
+		if (!messengerCheck.ok) {
+			for (const e of messengerCheck.errors) {
+				errors.push(`parallel_probes round messenger: ${e}`);
+			}
+		}
+	} else if (consolidated) {
 		const absConsolidated = join(runDir, CONSOLIDATED_REVIEW_ARTIFACT);
 		if (!(await fileExists(absConsolidated))) {
 			errors.push(`missing ${CONSOLIDATED_REVIEW_ARTIFACT}`);

package/.pi/extensions/lib/plan-debate-lanes.ts

@@ -43,9 +43,39 @@ export function laneArtifactPathsForRound(
 	return paths;
 }
 
-/** Lanes for consolidated Review Gate (single round, parallel-friendly). */
+/** Lanes for consolidated Review Gate (single round; blind verifier first). */
 export function lanesForConsolidatedRound(): DebateLaneKind[] {
-	return ["validation-turn", "adversary-brief", "sprint-audit"];
+	return [
+		"hypothesis-validation",
+		"validation-turn",
+		"adversary-brief",
+		"sprint-audit",
+	];
+}
+
+export const PARALLEL_PROBES_REVIEW_ARTIFACT =
+	"artifacts/review-round-parallel-probes.yaml";
+
+/** Parallel plan-verify: inspector ∥ adversary (round 1), then integrator. */
+export function lanesForParallelProbesRound(): DebateLaneKind[] {
+	return ["hypothesis-validation", "validation-turn", "adversary-brief"];
+}
+
+export function laneArtifactPathsForParallelProbesRound(): string[] {
+	const roundIndex = 1;
+	return [
+		...lanesForParallelProbesRound().map((lane) => {
+			switch (lane) {
+				case "validation-turn":
+					return `artifacts/validation-turn-r${roundIndex}.yaml`;
+				case "adversary-brief":
+					return `artifacts/adversary-brief-r${roundIndex}.yaml`;
+				default:
+					return `artifacts/${lane}-r${roundIndex}.yaml`;
+			}
+		}),
+		PARALLEL_PROBES_REVIEW_ARTIFACT,
+	];
 }
 
 export function laneArtifactPathsForConsolidatedRound(): string[] {

package/.pi/extensions/lib/plan-review-gate.ts

@@ -38,6 +38,14 @@ export function isConsolidatedReviewStrategy(
 	return strategy.mode === "consolidated";
 }
 
+export { PARALLEL_PROBES_REVIEW_ARTIFACT } from "./plan-debate-lanes.js";
+
+export function isParallelProbesReviewStrategy(
+	strategy: PlanReviewGateStrategy,
+): boolean {
+	return strategy.mode === "parallel_probes";
+}
+
 /** Focus areas covered in a single consolidated review round (spec + quality gate). */
 export const CONSOLIDATED_REVIEW_FOCUS_AREAS: readonly PlanDebateFocus[] = [
 	"spec",

package/.pi/extensions/lib/posthog-client.ts

@@ -0,0 +1,76 @@
+/**
+ * PostHog client helpers — IPv4-first fetch for WSL2 / broken dual-stack DNS.
+ *
+ * Node's default fetch can ETIMEDOUT against *.posthog.com while curl succeeds.
+ * Use createPostHogFetch() (undici, family 4) for all posthog-node clients.
+ */
+
+import { Agent, fetch as undiciFetch } from "undici";
+
+const POSTHOG_HOST_RE = /(^https?:\/\/)?([^.]+\.)*posthog\.com(\/|$)/i;
+
+const ipv4Agent = new Agent({ connect: { family: 4 } });
+
+let fetchPatchInstalled = false;
+
+export function isPostHogHostUrl(url: string): boolean {
+	return POSTHOG_HOST_RE.test(url);
+}
+
+export function resolvePostHogHost(): string {
+	return process.env.POSTHOG_HOST?.trim() || "https://us.i.posthog.com";
+}
+
+/** Fetch that prefers IPv4 — fixes WSL2 ETIMEDOUT on us.i.posthog.com. */
+export function createPostHogFetch(): typeof fetch {
+	return ((input: Parameters<typeof fetch>[0], init?: RequestInit) =>
+		undiciFetch(
+			input as Parameters<typeof undiciFetch>[0],
+			{
+				...init,
+				dispatcher: ipv4Agent,
+			} as Parameters<typeof undiciFetch>[1],
+		)) as typeof fetch;
+}
+
+export function getPostHogClientOptions(): {
+	host: string;
+	fetch: typeof fetch;
+	requestTimeout: number;
+} {
+	return {
+		host: resolvePostHogHost(),
+		fetch: createPostHogFetch(),
+		requestTimeout: 30_000,
+	};
+}
+
+/**
+ * Patch global fetch so @posthog/pi (which uses default fetch) reaches PostHog on WSL2.
+ * Only PostHog hostnames are routed through the IPv4 agent.
+ */
+export function installPostHogFetchPatch(): void {
+	if (fetchPatchInstalled) return;
+	fetchPatchInstalled = true;
+
+	const nativeFetch = globalThis.fetch.bind(globalThis);
+	const posthogFetch = createPostHogFetch();
+
+	globalThis.fetch = ((
+		input: Parameters<typeof fetch>[0],
+		init?: RequestInit,
+	) => {
+		const url =
+			typeof input === "string"
+				? input
+				: input instanceof URL
+					? input.href
+					: typeof input === "object" && input !== null && "url" in input
+						? String((input as { url: string }).url)
+						: "";
+		if (url && isPostHogHostUrl(url)) {
+			return posthogFetch(input, init);
+		}
+		return nativeFetch(input, init);
+	}) as typeof fetch;
+}

package/.pi/extensions/lib/spawn-policy.ts

@@ -11,9 +11,9 @@ export const SUBAGENT_BLOCKED_TOOLS = new Set([
 ]);
 
 const ASK_USER_ALLOWED_AGENT_TYPES = new Set([
-	"harness/evaluator",
-	"harness/adversary",
-	"harness/tie-breaker",
+	"harness/reviewing/evaluator",
+	"harness/reviewing/adversary",
+	"harness/reviewing/tie-breaker",
 ]);
 
 export interface ToolCallDecision {

package/.pi/extensions/observation-bus.ts

@@ -7,6 +7,7 @@
 
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isHarnessProjectEnabled } from "../lib/harness-project-config.js";
 import { getRunIdFromSession } from "../lib/harness-run-context.js";
 
 type HarnessPhase = "plan" | "execute" | "evaluate" | "adversary" | "merge";
@@ -87,6 +88,7 @@ function getRunId(ctx: {
 }
 
 export default function observationBus(pi: ExtensionAPI) {
+	if (!isHarnessProjectEnabled()) return;
 	const seen = new Set<string>();
 
 	pi.on("agent_end", async (_event, ctx) => {

package/.pi/extensions/policy-gate.ts

@@ -9,6 +9,11 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	evaluateContextModeMutation,
+	isMutatingBash,
+} from "../lib/harness-context-mode-policy.js";
+import { isHarnessProjectEnabled } from "../lib/harness-project-config.js";
 import {
 	extractWritePathFromToolInput,
 	getLatestRunContext,
@@ -27,6 +32,7 @@ import {
 	userVisiblePromptSlice,
 	validatePlanPacket,
 } from "../lib/harness-run-context.js";
+import { bootstrapHarnessSubprocessFromEnv } from "./lib/harness-subprocess-bootstrap.js";
 
 type HarnessPhase = "plan" | "execute" | "evaluate" | "adversary" | "merge";
 
@@ -56,20 +62,6 @@ const PHASE_ORDER: HarnessPhase[] = [
 ];
 
 const MUTATING_TOOLS = new Set(["write", "edit"]);
-const BASH_MUTATION_PATTERNS = [
-	/\bgit\s+commit\b/i,
-	/\bgit\s+push\b/i,
-	/\bgit\s+merge\b/i,
-	/\bgit\s+rebase\b/i,
-	/\brm\s+(-rf?|--recursive)\b/i,
-	/\bmv\b/i,
-	/\bcp\b/i,
-	/\bmkdir\b/i,
-	/\bchmod\b/i,
-	/\bchown\b/i,
-	/\bsed\s+-i\b/i,
-	/\bperl\s+-i\b/i,
-];
 
 function nowIso(): string {
 	return new Date().toISOString();
@@ -94,10 +86,6 @@ function hasApprovedPlanSignal(prompt: string, entries: unknown[]): boolean {
 	return hasApprovedPlanSignalFromUserPrompt(prompt);
 }
 
-function isMutatingBash(command: string): boolean {
-	return BASH_MUTATION_PATTERNS.some((pattern) => pattern.test(command));
-}
-
 function getLatestPolicyStateFull(ctx: {
 	sessionManager: { getEntries(): unknown[] };
 }): PolicyState {
@@ -139,6 +127,7 @@ function getLatestPolicyStateFull(ctx: {
 }
 
 export default function policyGate(pi: ExtensionAPI) {
+	if (!isHarnessProjectEnabled()) return;
 	let state = defaultState();
 
 	const appendPolicyState = (next: PolicyState): void => {
@@ -148,10 +137,15 @@ export default function policyGate(pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		state = getLatestPolicyStateFull(ctx);
+		const booted = await bootstrapHarnessSubprocessFromEnv(pi, ctx);
+		if (booted) {
+			state = getLatestPolicyStateFull(ctx);
+		}
 	});
 
 	pi.on("before_agent_start", async (event, ctx) => {
 		const userPrompt = userVisiblePromptSlice(event.prompt);
+		await bootstrapHarnessSubprocessFromEnv(pi, ctx);
 		const entries = ctx.sessionManager.getEntries();
 		state = getLatestPolicyStateFull(ctx);
 		const bootstrapPrompt = isHarnessBootstrapPrompt(userPrompt);
@@ -243,7 +237,7 @@ export default function policyGate(pi: ExtensionAPI) {
 
 		const planPhaseHint =
 			state.phase === "plan"
-				? "\nPlan phase: scouts → decompose → hypothesis → implementation-researcher + stack-researcher → execution-plan-author → validate-plan-dag → debate eligibility + Review Gate → approve_plan → create_plan (YAML plan-packet.yaml). Post-execute: /harness-critic."
+				? "\nPlan phase: scouts (parallel) → decompose → hypothesis (sequential) → implementation-researcher + stack-researcher (parallel) → execution-plan-author → validate-plan-dag → debate eligibility + Review Gate → approve_plan → create_plan (YAML plan-packet.yaml). Post-execute: /harness-review."
 				: "";
 
 		return {
@@ -296,6 +290,19 @@ export default function policyGate(pi: ExtensionAPI) {
 			}
 		}
 
+		const ctxDecision = evaluateContextModeMutation(
+			event.toolName,
+			event.input as Record<string, unknown>,
+			state.phase,
+			{
+				aborted: state.aborted,
+				budgetBypass: state.budgetBypass,
+			},
+		);
+		if (ctxDecision.blocked) {
+			return { block: true, reason: ctxDecision.reason };
+		}
+
 		return undefined;
 	});