ultimate-pi 0.23.0 → 0.25.0

package/.pi/lib/harness-spawn-budget.ts

@@ -1,8 +1,23 @@
 /**
  * Harness subagent spawn accounting (subprocess model).
- * No session caps — parallel batches are limited only by host resources.
+ * When HARNESS_BUDGET_ENFORCE=1, per-phase spawn caps apply.
  */
 
+import { isHarnessBudgetEnforceOn } from "./harness-budget-enforce.js";
+import type { HarnessPhase } from "./harness-run-context.js";
+
+const PHASE_SPAWN_CAPS: Record<HarnessPhase, number> = {
+	plan: 12,
+	execute: 3,
+	evaluate: 6,
+	adversary: 4,
+	merge: 2,
+};
+
+export function phaseSpawnCap(phase: HarnessPhase): number {
+	return PHASE_SPAWN_CAPS[phase];
+}
+
 export function isHarnessAgentType(type: string): boolean {
 	return type.startsWith("harness/");
 }
@@ -31,11 +46,24 @@ export function countHarnessAgentsInRequest(params: {
 	return { harnessCount: harness.length, agents: harness };
 }
 
-/** Always allows spawn; state is tracked for telemetry only. */
 export function checkHarnessSpawnBudget(
-	_state: SpawnBudgetState,
-	_incomingHarnessTasks: number,
+	state: SpawnBudgetState,
+	incomingHarnessTasks: number,
+	phase?: HarnessPhase,
 ): { ok: boolean; message?: string } {
+	if (!isHarnessBudgetEnforceOn() || !phase) {
+		return { ok: true };
+	}
+	const cap = PHASE_SPAWN_CAPS[phase];
+	const projected = state.totalHarnessSpawns + incomingHarnessTasks;
+	if (projected > cap) {
+		return {
+			ok: false,
+			message:
+				`Spawn budget exceeded for ${phase} phase (${projected}/${cap}). ` +
+				`Use harness_plan_next_action or reduce spawns; set HARNESS_BUDGET_ENFORCE=0 to disable.`,
+		};
+	}
 	return { ok: true };
 }
 

package/.pi/lib/harness-spawn-stall-detector.ts

@@ -0,0 +1,106 @@
+/**
+ * Detect repeated duplicate-spawn blocks (stall loops).
+ */
+
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { captureHarnessEvent } from "./harness-posthog.js";
+import type { HarnessPhase } from "./harness-run-context.js";
+
+const STALL_THRESHOLD = 3;
+
+type StallKey = string;
+
+const counters = new Map<StallKey, number>();
+
+function stallKey(agent: string, artifactHash: string): StallKey {
+	return `${agent}::${artifactHash}`;
+}
+
+async function artifactMtimeFingerprint(
+	projectRoot: string,
+	runId: string,
+	artifactRel: string,
+): Promise<string> {
+	const path = join(projectRoot, ".pi", "harness", "runs", runId, artifactRel);
+	try {
+		const st = await stat(path);
+		return `${artifactRel}:${st.mtimeMs}`;
+	} catch {
+		return `${artifactRel}:missing`;
+	}
+}
+
+export function resetHarnessSpawnStallCounters(): void {
+	counters.clear();
+}
+
+export function resetStallCounterForAgent(agent: string): void {
+	for (const key of [...counters.keys()]) {
+		if (key.startsWith(`${agent}::`)) counters.delete(key);
+	}
+}
+
+/** Parse agent name from duplicate-spawn topology message. */
+export function parseAgentFromDuplicateSpawnMessage(
+	message: string,
+): string | null {
+	const m = /^Duplicate spawn blocked: ([^\s]+) already produced/.exec(message);
+	return m?.[1] ?? null;
+}
+
+/** Parse artifact rel from duplicate-spawn topology message. */
+export function parseArtifactFromDuplicateSpawnMessage(
+	message: string,
+): string | null {
+	const m = /valid (artifacts\/[^\s.]+\.yaml)/.exec(message);
+	return m?.[1] ?? null;
+}
+
+/**
+ * Record a duplicate-spawn block; emit harness_observation stall when threshold hit.
+ */
+export async function recordDuplicateSpawnBlock(args: {
+	message: string;
+	projectRoot: string;
+	runId: string | null;
+	phase: HarnessPhase;
+	sessionId: string;
+}): Promise<{ stall: boolean; count: number }> {
+	if (process.env.HARNESS_FORCE_RESPAWN === "1") {
+		return { stall: false, count: 0 };
+	}
+
+	const agent = parseAgentFromDuplicateSpawnMessage(args.message);
+	const artifactRel = parseArtifactFromDuplicateSpawnMessage(args.message);
+	if (!agent || !artifactRel || !args.runId) {
+		return { stall: false, count: 0 };
+	}
+
+	const hash = await artifactMtimeFingerprint(
+		args.projectRoot,
+		args.runId,
+		artifactRel,
+	);
+	const key = stallKey(agent, hash);
+	const next = (counters.get(key) ?? 0) + 1;
+	counters.set(key, next);
+
+	if (next < STALL_THRESHOLD) {
+		return { stall: false, count: next };
+	}
+
+	captureHarnessEvent(args.sessionId, "harness_observation", {
+		harness_run_id: args.runId,
+		run_id: args.runId,
+		harness_phase: args.phase,
+		kind: "stall",
+		agent_id: agent,
+		artifact_path: artifactRel,
+		artifact_hash: hash,
+		duplicate_block_count: next,
+		reason: "duplicate_spawn_loop",
+	});
+
+	return { stall: true, count: next };
+}

package/.pi/lib/harness-spawn-topology.ts

@@ -7,6 +7,11 @@ import { access, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { validateHarnessArtifactFile } from "./harness-artifact-gate.js";
+import {
+	synthesizerAllowsRespawn,
+	synthesizerArtifactsComplete,
+} from "./harness-plan-route.js";
+import { isHarnessReviewParallelEnabled } from "./harness-review-parallel.js";
 import type { HarnessPhase } from "./harness-run-context.js";
 import { validateTaskClarificationReadyWithHumanGate } from "./plan-human-gates.js";
 
@@ -17,6 +22,7 @@ export interface SpawnTopologyResult {
 
 const DECOMPOSE_AGENT = "harness/planning/decompose";
 const HYPOTHESIS_AGENT = "harness/planning/hypothesis";
+const SYNTHESIZER_AGENT = "harness/planning/plan-synthesizer";
 
 const DEBATE_LANE_AGENTS = new Set([
 	"harness/planning/hypothesis-validator",
@@ -121,6 +127,16 @@ function validateParallelBatch(
 		return "At most one planning-context subagent per parallel batch.";
 	}
 
+	const reviewEvaluator = "harness/reviewing/evaluator";
+	const reviewAdversary = "harness/reviewing/adversary";
+	const reviewParallelPair =
+		isHarnessReviewParallelEnabled() &&
+		names.includes(reviewEvaluator) &&
+		names.includes(reviewAdversary) &&
+		names.filter((n) => n === reviewEvaluator || n === reviewAdversary)
+			.length === 2 &&
+		names.length === 2;
+
 	const otherHarness = names.filter(
 		(n) =>
 			n.startsWith("harness/") &&
@@ -128,7 +144,8 @@ function validateParallelBatch(
 			!PARALLEL_RESEARCH_AGENTS.has(n) &&
 			!DEBATE_LANE_AGENTS.has(n) &&
 			n !== DECOMPOSE_AGENT &&
-			n !== HYPOTHESIS_AGENT,
+			n !== HYPOTHESIS_AGENT &&
+			!(reviewParallelPair && (n === reviewEvaluator || n === reviewAdversary)),
 	);
 	if (
 		(recon > 0 && (research > 0 || otherHarness.length > 0)) ||
@@ -143,6 +160,9 @@ function validateParallelBatch(
 	if (research > 2) {
 		return "At most 2 research lanes (implementation-researcher, stack-researcher) per parallel batch.";
 	}
+	if (reviewParallelPair) {
+		return null;
+	}
 	return null;
 }
 
@@ -185,6 +205,10 @@ async function validateHypothesisDependency(
 	if (!(names.includes(HYPOTHESIS_AGENT) && opts?.projectRoot && opts?.runId)) {
 		return null;
 	}
+	const runRoot = join(opts.projectRoot, ".pi", "harness", "runs", opts.runId);
+	if (await synthesizerArtifactsComplete(runRoot)) {
+		return "Synthesizer path complete — spawn execution-plan-author instead of hypothesis.";
+	}
 	const ready = await decompositionReady(opts.projectRoot, opts.runId);
 	if (ready) return null;
 	return (
@@ -193,6 +217,21 @@ async function validateHypothesisDependency(
 	);
 }
 
+async function validateSequentialPathBlocks(
+	names: string[],
+	opts?: { projectRoot?: string; runId?: string | null },
+): Promise<string | null> {
+	if (!(opts?.projectRoot && opts?.runId)) return null;
+	const runRoot = join(opts.projectRoot, ".pi", "harness", "runs", opts.runId);
+	if (
+		(names.includes(DECOMPOSE_AGENT) || names.includes(HYPOTHESIS_AGENT)) &&
+		(await synthesizerArtifactsComplete(runRoot))
+	) {
+		return "Synthesizer path artifacts present — use execution-plan-author, not decompose/hypothesis.";
+	}
+	return null;
+}
+
 function validatePlanPhaseMutations(
 	names: string[],
 	phase: HarnessPhase,
@@ -244,6 +283,13 @@ async function validateArtifactCompletionDedup(
 	const specsDir = join(opts.projectRoot, ".pi", "harness", "specs");
 
 	for (const name of names) {
+		if (name === SYNTHESIZER_AGENT) {
+			if (await synthesizerAllowsRespawn(runRoot)) continue;
+			return (
+				`Duplicate spawn blocked: ${name} already produced synthesizer artifacts. ` +
+				`Advance to execution-plan-author or set HARNESS_FORCE_RESPAWN=1.`
+			);
+		}
 		const artifactRel = PLANNING_AGENT_ARTIFACT[name];
 		if (!artifactRel) continue;
 		if (await artifactAllowsRespawn(runRoot, artifactRel)) continue;
@@ -285,6 +331,9 @@ export async function validateHarnessSpawnTopology(
 	const parallelError = validateParallelBatch(names, taskCount);
 	if (parallelError) return { ok: false, message: parallelError };
 
+	const sequentialBlock = await validateSequentialPathBlocks(names, opts);
+	if (sequentialBlock) return { ok: false, message: sequentialBlock };
+
 	const hypothesisError = await validateHypothesisDependency(names, opts);
 	if (hypothesisError) return { ok: false, message: hypothesisError };
 

package/.pi/lib/harness-subagent-precheck.ts

@@ -8,12 +8,14 @@ import {
 } from "../../vendor/pi-subagents/src/agents.js";
 import { getAgentKind } from "./agents-policy.mjs";
 import { getHarnessPackageRoot } from "./harness-paths.js";
+import { isHarnessReviewParallelEnabled } from "./harness-review-parallel.js";
 import { type HarnessPhase, inferHarnessPhase } from "./harness-run-context.js";
 import { validateHarnessSpawnTopology } from "./harness-spawn-topology.js";
 import { shouldBlockSubagentForMissingPlanApproval } from "./plan-human-gates.js";
 
 export interface SubagentTaskRef {
 	agent: string;
+	task?: string;
 }
 
 export interface PrecheckResult {
@@ -30,6 +32,29 @@ export interface PrecheckOptions {
 	lastOutcome?: string | null;
 }
 
+function parseSteerAttemptFromTasks(params: {
+	agent?: string;
+	task?: string;
+	tasks?: SubagentTaskRef[];
+	chain?: SubagentTaskRef[];
+}): number {
+	const allTaskText = [
+		...(params.tasks?.map((t) => t.task ?? "") ?? []),
+		...(params.chain?.map((c) => c.task ?? "") ?? []),
+		params.task ?? "",
+	].join("\n");
+	const m = /"steer_attempt"\s*:\s*(\d+)/.exec(allTaskText);
+	if (m) return Number.parseInt(m[1] ?? "0", 10) || 0;
+	const m2 = /steer_attempt[=:](\d+)/i.exec(allTaskText);
+	if (m2) return Number.parseInt(m2[1] ?? "0", 10) || 0;
+	return 0;
+}
+
+function priorBlockMergeInContext(opts?: PrecheckOptions): boolean {
+	const outcome = String(opts?.lastOutcome ?? "").toLowerCase();
+	return outcome.includes("block_merge") || outcome.includes("block");
+}
+
 function collectAgents(params: {
 	agent?: string;
 	tasks?: SubagentTaskRef[];
@@ -79,12 +104,28 @@ export async function precheckHarnessSubagentSpawn(
 		};
 	}
 
+	const steerAttempt = parseSteerAttemptFromTasks(params);
 	const parallelEvalAdversary =
+		isHarnessReviewParallelEnabled({ quick: opts?.quick, steerAttempt }) &&
 		(params.tasks?.length ?? 0) === 2 &&
 		params.tasks?.some((t) => t.agent === "harness/reviewing/evaluator") &&
 		params.tasks?.some((t) => t.agent === "harness/reviewing/adversary") &&
+		names.length === 2 &&
 		phase === "evaluate";
 
+	if (
+		steerAttempt >= 2 &&
+		names.includes("harness/reviewing/adversary") &&
+		!priorBlockMergeInContext(opts)
+	) {
+		return {
+			ok: false,
+			message:
+				`Lite review (steer attempt ${steerAttempt}): skip adversary unless prior block_merge. ` +
+				`Run benchmark + verdict evaluator only.`,
+		};
+	}
+
 	if (
 		(params.tasks?.length ?? 0) > 1 &&
 		mutating.length > 1 &&

package/.pi/lib/harness-subagent-progress.ts

@@ -0,0 +1,119 @@
+/**
+ * In-process progress state for the harness live widget (no stderr output).
+ */
+
+export type HarnessWaitGate = "ask_user" | "approve_plan" | null;
+
+export interface HarnessProgressSnapshot {
+	activeSubagentAgents: string[];
+	harnessPhase: string | null;
+	subagentStartedAtMs: number | null;
+	waitingGate: HarnessWaitGate;
+	waitingStartedAtMs: number | null;
+	lastHeartbeatLine: string | null;
+}
+
+let snapshot: HarnessProgressSnapshot = {
+	activeSubagentAgents: [],
+	harnessPhase: null,
+	subagentStartedAtMs: null,
+	waitingGate: null,
+	waitingStartedAtMs: null,
+	lastHeartbeatLine: null,
+};
+
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+function formatElapsed(ms: number): string {
+	const totalSec = Math.max(0, Math.floor(ms / 1000));
+	const min = Math.floor(totalSec / 60);
+	const sec = totalSec % 60;
+	return min > 0 ? `${min}m ${sec}s` : `${sec}s`;
+}
+
+export function getHarnessProgressSnapshot(): HarnessProgressSnapshot {
+	return { ...snapshot };
+}
+
+export function setHarnessSubagentProgress(args: {
+	agentIds: string[];
+	phase: string | null;
+}): void {
+	snapshot = {
+		...snapshot,
+		activeSubagentAgents: [...args.agentIds],
+		harnessPhase: args.phase,
+		subagentStartedAtMs: Date.now(),
+		waitingGate: null,
+		waitingStartedAtMs: null,
+	};
+}
+
+export function clearHarnessSubagentProgress(): void {
+	snapshot = {
+		...snapshot,
+		activeSubagentAgents: [],
+		subagentStartedAtMs: null,
+		lastHeartbeatLine: null,
+	};
+	stopHarnessSubagentHeartbeat();
+}
+
+export function setHarnessWaitingForUser(gate: HarnessWaitGate): void {
+	snapshot = {
+		...snapshot,
+		waitingGate: gate,
+		waitingStartedAtMs: gate ? Date.now() : null,
+	};
+	if (!gate) {
+		snapshot.waitingStartedAtMs = null;
+	}
+}
+
+export function buildHarnessProgressStatusLine(): string | null {
+	const now = Date.now();
+	if (snapshot.waitingGate && snapshot.waitingStartedAtMs != null) {
+		const elapsed = formatElapsed(now - snapshot.waitingStartedAtMs);
+		const label =
+			snapshot.waitingGate === "approve_plan" ? "plan approval" : "your input";
+		return `Waiting for ${label} (${elapsed})`;
+	}
+	if (
+		snapshot.activeSubagentAgents.length > 0 &&
+		snapshot.subagentStartedAtMs != null
+	) {
+		const elapsed = formatElapsed(now - snapshot.subagentStartedAtMs);
+		const agents = snapshot.activeSubagentAgents
+			.map((a) => a.replace(/^harness\//, ""))
+			.join(", ");
+		const agentsLabel = agents.length > 36 ? `${agents.slice(0, 33)}…` : agents;
+		const phase = snapshot.harnessPhase ?? "harness";
+		return `${phase} · ${agentsLabel} · ${elapsed}`;
+	}
+	return null;
+}
+
+export function startHarnessSubagentHeartbeat(
+	onTick: (line: string) => void,
+	intervalMs = 10_000,
+): void {
+	stopHarnessSubagentHeartbeat();
+	const tick = (): void => {
+		const line = buildHarnessProgressStatusLine();
+		if (!line) return;
+		snapshot = { ...snapshot, lastHeartbeatLine: line };
+		onTick(line);
+	};
+	tick();
+	heartbeatTimer = setInterval(tick, intervalMs);
+	if (typeof heartbeatTimer.unref === "function") {
+		heartbeatTimer.unref();
+	}
+}
+
+export function stopHarnessSubagentHeartbeat(): void {
+	if (heartbeatTimer) {
+		clearInterval(heartbeatTimer);
+		heartbeatTimer = null;
+	}
+}

package/.pi/lib/harness-subagent-timeout.ts

@@ -0,0 +1,81 @@
+/**
+ * Phase-aware default timeouts for harness subagent subprocesses.
+ */
+
+import type { HarnessPhase } from "./harness-run-context.js";
+
+function parsePositiveMs(value: string | undefined): number | undefined {
+	if (!value?.trim()) return undefined;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function isHarnessSubagentTimeoutDisabled(): boolean {
+	return process.env.HARNESS_SUBAGENT_TIMEOUT_DISABLE === "1";
+}
+
+function inferPhaseFromAgent(agentId: string | undefined): HarnessPhase | null {
+	if (!agentId) return null;
+	if (agentId.startsWith("harness/running/")) return "execute";
+	if (agentId.startsWith("harness/reviewing/")) return "evaluate";
+	if (agentId.startsWith("harness/planning/")) return "plan";
+	return null;
+}
+
+/**
+ * Resolve subprocess timeout (ms). Phase-specific env wins over PI_SUBAGENT_TIMEOUT_MS.
+ * Returns undefined when timeouts are disabled or no cap is configured.
+ */
+export function resolveHarnessSubagentTimeoutMs(
+	phase: HarnessPhase,
+	agentId?: string,
+): number | undefined {
+	if (isHarnessSubagentTimeoutDisabled()) return undefined;
+
+	const global = parsePositiveMs(process.env.PI_SUBAGENT_TIMEOUT_MS);
+	const effectivePhase = inferPhaseFromAgent(agentId) ?? phase;
+
+	let phaseDefault: number | undefined;
+	switch (effectivePhase) {
+		case "execute":
+			phaseDefault =
+				parsePositiveMs(process.env.HARNESS_SUBAGENT_TIMEOUT_EXECUTE_MS) ??
+				2_700_000;
+			break;
+		case "evaluate":
+		case "adversary":
+			phaseDefault =
+				parsePositiveMs(process.env.HARNESS_SUBAGENT_TIMEOUT_REVIEW_MS) ??
+				1_200_000;
+			break;
+		default:
+			phaseDefault =
+				parsePositiveMs(process.env.HARNESS_SUBAGENT_TIMEOUT_PLAN_MS) ??
+				1_800_000;
+			break;
+	}
+
+	const phaseEnv =
+		effectivePhase === "execute"
+			? parsePositiveMs(process.env.HARNESS_SUBAGENT_TIMEOUT_EXECUTE_MS)
+			: effectivePhase === "evaluate" || effectivePhase === "adversary"
+				? parsePositiveMs(process.env.HARNESS_SUBAGENT_TIMEOUT_REVIEW_MS)
+				: parsePositiveMs(process.env.HARNESS_SUBAGENT_TIMEOUT_PLAN_MS);
+
+	return phaseEnv ?? global ?? phaseDefault;
+}
+
+/** Pick the strictest (lowest) timeout when spawning multiple harness agents. */
+export function resolveHarnessSubagentTimeoutForAgents(
+	phase: HarnessPhase,
+	agentIds: string[],
+): number | undefined {
+	if (agentIds.length === 0) {
+		return resolveHarnessSubagentTimeoutMs(phase);
+	}
+	const caps = agentIds
+		.map((id) => resolveHarnessSubagentTimeoutMs(phase, id))
+		.filter((v): v is number => v != null);
+	if (caps.length === 0) return undefined;
+	return Math.min(...caps);
+}