ultimate-pi 0.23.0 → 0.25.0

package/.pi/lib/harness-plan-fsm.ts

@@ -0,0 +1,162 @@
+/**
+ * Plan-phase finite state machine — deterministic next action for parent orchestrator.
+ */
+
+import { join } from "node:path";
+import { canAutoApprovePlan } from "./harness-auto-approve.js";
+import { derivePlanRouteSpawns } from "./harness-plan-route.js";
+import { validatePlanApprovalReadiness } from "./plan-approval-readiness.js";
+import { loadPlanDebateEligibilitySnapshot } from "./plan-debate-eligibility-snapshot.js";
+import { validatePlanDebateGate } from "./plan-debate-gate.js";
+import { getPlanDebateRoundStatus } from "./plan-debate-round-status.js";
+import { resolvePlanHumanGateStatus } from "./plan-human-gates.js";
+import { loadMessengerState } from "./plan-messenger.js";
+import { readTaskClarificationDoc } from "./plan-task-clarification.js";
+
+export type PlanFsmActionKind = "spawn" | "tool" | "gate" | "wait_user";
+
+export interface PlanFsmNextAction {
+	phase: string;
+	action: PlanFsmActionKind;
+	agents?: string[];
+	tool?: string;
+	rationale: string[];
+	review_gate_mode?: string;
+	synthesis_route?: string;
+}
+
+export interface PlanFsmInput {
+	projectRoot: string;
+	runId: string;
+	entries: unknown[];
+	quick?: boolean;
+	taskSummary?: string;
+	lastOutcome?: string | null;
+}
+
+export async function derivePlanNextAction(
+	input: PlanFsmInput,
+): Promise<PlanFsmNextAction> {
+	const { projectRoot, runId, entries } = input;
+	const runDir = join(projectRoot, ".pi", "harness", "runs", runId);
+	const gateStatus = await resolvePlanHumanGateStatus(
+		projectRoot,
+		runId,
+		entries,
+		{
+			quick: input.quick,
+			taskSummary: input.taskSummary,
+			lastOutcome: input.lastOutcome,
+		},
+	);
+
+	if (!gateStatus.phase0Ready) {
+		return {
+			phase: "0",
+			action: gateStatus.phase0NeedsAskUser ? "wait_user" : "tool",
+			tool: gateStatus.phase0NeedsAskUser
+				? "ask_user"
+				: "write_harness_yaml + harness_artifact_ready (task-clarification)",
+			rationale: [
+				gateStatus.nextRequiredAction ?? "Complete Phase 0 task clarification",
+			],
+		};
+	}
+
+	const clarDoc = await readTaskClarificationDoc(runDir);
+	const resolvedRisk = String(clarDoc?.risk_level ?? "med");
+
+	const route = await derivePlanRouteSpawns(runDir, {
+		risk_level: resolvedRisk,
+	});
+	if (route.agents.length > 0) {
+		return {
+			phase: "2-4",
+			action: "spawn",
+			agents: route.agents,
+			synthesis_route: route.route,
+			rationale: route.rationale,
+		};
+	}
+
+	const eligibility = await loadPlanDebateEligibilitySnapshot(runDir);
+	const messenger = await loadMessengerState(runDir);
+	if (!messenger) {
+		return {
+			phase: "5",
+			action: "tool",
+			tool: "harness_plan_debate_eligibility then harness_debate_open",
+			rationale: ["Review Gate not opened — run eligibility then debate_open"],
+			review_gate_mode: eligibility?.review_gate_strategy.mode,
+		};
+	}
+
+	const roundStatus = await getPlanDebateRoundStatus(runDir, 1, runId);
+	if (!roundStatus.ready_for_integrator && roundStatus.next_tool) {
+		return {
+			phase: "5",
+			action: roundStatus.next_tool.startsWith("subagent") ? "spawn" : "tool",
+			tool: roundStatus.next_tool.startsWith("subagent")
+				? undefined
+				: roundStatus.next_tool,
+			agents: roundStatus.next_tool.includes("parallel batch")
+				? ["harness/planning/plan-evaluator", "harness/planning/plan-adversary"]
+				: roundStatus.next_tool.startsWith("subagent")
+					? [
+							roundStatus.next_tool.replace(/^subagent\s+/, "").split(" ")[0] ??
+								"",
+						]
+					: undefined,
+			review_gate_mode: messenger.review_gate_mode,
+			rationale: [
+				`Review Gate in progress (missing: ${roundStatus.missing.slice(0, 3).join(", ")})`,
+			],
+		};
+	}
+
+	if (gateStatus.debateRequired) {
+		return {
+			phase: "5",
+			action: "tool",
+			tool: "harness_debate_consensus",
+			rationale: [
+				gateStatus.debateRecoveryHint ??
+					"Complete debate consensus before approval",
+			],
+			review_gate_mode: messenger.review_gate_mode,
+		};
+	}
+
+	if (gateStatus.approvalRequired && !gateStatus.approvalRecorded) {
+		const readiness = await validatePlanApprovalReadiness(projectRoot, runId, {
+			risk_level: resolvedRisk,
+		});
+		const debateGate = await validatePlanDebateGate(
+			projectRoot,
+			runId,
+			eligibility ?? undefined,
+		);
+		const auto = await canAutoApprovePlan({
+			projectRoot,
+			runId,
+			riskLevel: resolvedRisk,
+			readiness,
+			debateGate,
+		});
+		return {
+			phase: "6",
+			action: auto.allowed ? "tool" : "gate",
+			tool: auto.allowed ? "approve_plan (auto)" : "approve_plan",
+			rationale: auto.allowed
+				? ["deterministic gates pass — auto-approve eligible"]
+				: ["plan ready — user approval required", ...auto.reasons],
+		};
+	}
+
+	return {
+		phase: "6",
+		action: "tool",
+		tool: "create_plan",
+		rationale: ["plan approved — write plan-packet.yaml via create_plan"],
+	};
+}

package/.pi/lib/harness-plan-route.ts

@@ -0,0 +1,134 @@
+/**
+ * Plan synthesis routing — sequential vs plan-synthesizer path.
+ */
+
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+export type PlanSynthesisRoute = "sequential" | "synthesizer";
+
+export const PLAN_SYNTHESIS_ROUTE_ARTIFACT =
+	"artifacts/plan-synthesis-route.yaml";
+
+const SYNTHESIZER_ARTIFACTS = [
+	"artifacts/decomposition.yaml",
+	"artifacts/hypothesis.yaml",
+	"artifacts/execution-plan-draft.yaml",
+] as const;
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function synthesizerArtifactsComplete(
+	runDir: string,
+): Promise<boolean> {
+	for (const rel of SYNTHESIZER_ARTIFACTS) {
+		if (!(await fileExists(join(runDir, rel)))) return false;
+	}
+	return true;
+}
+
+export async function synthesizerAllowsRespawn(
+	runDir: string,
+): Promise<boolean> {
+	if (!(await synthesizerArtifactsComplete(runDir))) return true;
+	for (const rel of SYNTHESIZER_ARTIFACTS) {
+		try {
+			const raw = await readFile(join(runDir, rel), "utf-8");
+			const doc = parseYaml(raw) as Record<string, unknown>;
+			const status = String(doc?.status ?? "ok").toLowerCase();
+			if (status === "partial" || status === "failed" || status === "error") {
+				return true;
+			}
+		} catch {
+			return true;
+		}
+	}
+	return false;
+}
+
+export interface PlanRouteInput {
+	risk_level?: string;
+	material_fork?: boolean;
+}
+
+export function defaultSynthesisRoute(
+	input: PlanRouteInput,
+): PlanSynthesisRoute {
+	const risk = String(input.risk_level ?? "med").toLowerCase();
+	if (input.material_fork || risk === "high") return "sequential";
+	if (risk === "low" || risk === "med") return "synthesizer";
+	return "sequential";
+}
+
+export async function planSynthesisPath(
+	runDir: string,
+	input?: PlanRouteInput,
+): Promise<PlanSynthesisRoute> {
+	const routePath = join(runDir, PLAN_SYNTHESIS_ROUTE_ARTIFACT);
+	if (await fileExists(routePath)) {
+		try {
+			const raw = await readFile(routePath, "utf-8");
+			const doc = parseYaml(raw) as Record<string, unknown>;
+			const route = String(doc.route ?? "").toLowerCase();
+			if (route === "synthesizer" || route === "sequential") return route;
+		} catch {
+			// fall through
+		}
+	}
+	if (await synthesizerArtifactsComplete(runDir)) return "synthesizer";
+	return defaultSynthesisRoute(input ?? {});
+}
+
+export interface PlanRouteNextSpawn {
+	agents: string[];
+	route: PlanSynthesisRoute;
+	rationale: string[];
+}
+
+export async function derivePlanRouteSpawns(
+	runDir: string,
+	input?: PlanRouteInput,
+): Promise<PlanRouteNextSpawn> {
+	const route = await planSynthesisPath(runDir, input);
+	const rationale: string[] = [`synthesis route: ${route}`];
+	if (route === "synthesizer") {
+		if (await synthesizerArtifactsComplete(runDir)) {
+			return {
+				route,
+				agents: ["harness/planning/execution-plan-author"],
+				rationale: [
+					...rationale,
+					"synthesizer artifacts complete — advance to execution-plan-author",
+				],
+			};
+		}
+		return {
+			route,
+			agents: ["harness/planning/plan-synthesizer"],
+			rationale: [
+				...rationale,
+				"single spawn for decomposition + hypothesis + draft",
+			],
+		};
+	}
+	const agents: string[] = [];
+	if (!(await fileExists(join(runDir, "artifacts/decomposition.yaml")))) {
+		agents.push("harness/planning/decompose");
+	} else if (!(await fileExists(join(runDir, "artifacts/hypothesis.yaml")))) {
+		agents.push("harness/planning/hypothesis");
+	} else if (
+		!(await fileExists(join(runDir, "artifacts/execution-plan-draft.yaml")))
+	) {
+		agents.push("harness/planning/execution-plan-author");
+	}
+	return { route, agents, rationale };
+}

package/.pi/lib/harness-posthog.ts

@@ -29,9 +29,14 @@ export type HarnessPostHogEventName =
 	| "harness_lens_turn_findings"
 	| "harness_subagent_spawned"
 	| "harness_subagent_completed"
+	| "harness_subagent_timeout"
 	| "harness_subagent_result_wait"
 	| "harness_subagent_setup"
-	| "harness_blackboard_op";
+	| "harness_phase_completed"
+	| "harness_blackboard_op"
+	| "harness_auto_compact"
+	| "harness_plan_fsm"
+	| "harness_plan_route";
 
 const SCHEMA_VERSION = "1.0.0";
 

package/.pi/lib/harness-remediation.ts

@@ -0,0 +1,79 @@
+/**
+ * Review remediation classification — shared by run-context and repair-brief.
+ */
+
+export type RemediationClass =
+	| "pass"
+	| "implementation_gap"
+	| "plan_gap"
+	| "rollback"
+	| "inconclusive";
+
+export interface ReviewOutcomeLike {
+	schema_version?: string;
+	status?: string;
+	remediation_class?: RemediationClass | string;
+	recommended_next?: string;
+}
+
+export interface EvalVerdictLike {
+	status?: string;
+	recommended_action?: string;
+	failed_checks?: string[];
+}
+
+/** Infer remediation when parent skipped Phase 6 but eval-verdict exists on disk. */
+export function remediationClassFromEvalVerdict(
+	verdict: EvalVerdictLike | null,
+): RemediationClass | null {
+	if (!verdict) return null;
+	const status = (verdict.status ?? "").toLowerCase();
+	if (status === "pass") return "pass";
+	const action = (verdict.recommended_action ?? "").toLowerCase();
+	if (
+		action === "replan" ||
+		action.includes("revise") ||
+		action.includes("plan")
+	) {
+		return "plan_gap";
+	}
+	if (action === "rollback" || action.includes("rollback")) {
+		return "rollback";
+	}
+	if (
+		action === "steer" ||
+		action === "repair" ||
+		action.includes("implement")
+	) {
+		return "implementation_gap";
+	}
+	const joined = Array.isArray(verdict.failed_checks)
+		? verdict.failed_checks.join(" ").toLowerCase()
+		: "";
+	if (
+		joined.includes("scope_minimization") ||
+		joined.includes("scope_drift") ||
+		joined.includes("replan")
+	) {
+		return "plan_gap";
+	}
+	if (status === "fail") return "inconclusive";
+	return null;
+}
+
+export function recommendedNextForRemediation(
+	remediation: RemediationClass,
+): string {
+	switch (remediation) {
+		case "pass":
+			return "/harness-policy-status";
+		case "implementation_gap":
+			return "/harness-steer";
+		case "plan_gap":
+			return "/harness-plan (mode: revise)";
+		case "rollback":
+			return "/harness-incident";
+		default:
+			return "/harness-review";
+	}
+}

package/.pi/lib/harness-repair-brief.ts

@@ -4,10 +4,10 @@
 
 import { join } from "node:path";
 import {
-	harnessRunsRoot,
 	type RemediationClass,
 	remediationClassFromEvalVerdict,
-} from "./harness-run-context.js";
+} from "./harness-remediation.js";
+import { harnessRunsRoot } from "./harness-subagent-submit-path.js";
 import { readYamlFile, writeYamlFile } from "./harness-yaml.js";
 
 const REPAIR_BRIEF_SCHEMA = "1.0.0";

package/.pi/lib/harness-review-parallel.ts

@@ -0,0 +1,18 @@
+/**
+ * Risk-based default for parallel review evaluator ∥ adversary.
+ */
+
+export interface ReviewParallelOpts {
+	quick?: boolean;
+	steerAttempt?: number;
+}
+
+export function isHarnessReviewParallelEnabled(
+	opts?: ReviewParallelOpts,
+): boolean {
+	if (process.env.HARNESS_REVIEW_PARALLEL === "0") return false;
+	if (process.env.HARNESS_REVIEW_PARALLEL === "1") return true;
+	if (opts?.quick) return false;
+	if ((opts?.steerAttempt ?? 0) >= 2) return false;
+	return true;
+}

package/.pi/lib/harness-run-context.ts

@@ -12,6 +12,7 @@ import {
 	readFile,
 	realpath,
 	stat,
+	unlink,
 	writeFile,
 } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
@@ -20,7 +21,23 @@ import {
 	PLAN_APPROVE_OPTION,
 	PLAN_CANCEL_OPTION,
 } from "./ask-user/policy.js";
+import {
+	type RemediationClass,
+	type ReviewOutcomeLike,
+	recommendedNextForRemediation,
+	remediationClassFromEvalVerdict,
+} from "./harness-remediation.js";
 import { readYamlFile, writeYamlFile } from "./harness-yaml.js";
+
+export type {
+	RemediationClass,
+	ReviewOutcomeLike,
+} from "./harness-remediation.js";
+export {
+	recommendedNextForRemediation,
+	remediationClassFromEvalVerdict,
+} from "./harness-remediation.js";
+
 import { readTaskClarificationDoc } from "./plan-task-clarification.js";
 
 export { isPlanApprovalAskUser } from "./ask-user/policy.js";
@@ -969,6 +986,25 @@ export function getLatestRunContext(
 	entries: unknown[],
 ): HarnessRunContext | null {
 	for (let i = entries.length - 1; i >= 0; i--) {
+		const clearEntry = entries[i] as SessionEntryLike;
+		if (
+			clearEntry.type === "custom" &&
+			clearEntry.customType === "harness-clear-result"
+		) {
+			const clearData = clearEntry.data as
+				| {
+						approved?: boolean;
+						active_cleared?: boolean;
+						cleared_all?: boolean;
+				  }
+				| undefined;
+			if (
+				clearData?.approved === true &&
+				(clearData.active_cleared === true || clearData.cleared_all === true)
+			) {
+				return null;
+			}
+		}
 		const entry = entries[i] as SessionEntryLike;
 		if (entry.type !== "custom" || entry.customType !== "harness-run-context")
 			continue;
@@ -1067,6 +1103,17 @@ export async function loadProjectActiveRun(
 	}
 }
 
+export async function deleteProjectActiveRun(
+	projectRoot: string,
+): Promise<boolean> {
+	try {
+		await unlink(activeRunPointerPath(projectRoot));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 export async function saveProjectActiveRun(
 	ctx: HarnessRunContext,
 ): Promise<void> {
@@ -1107,6 +1154,52 @@ export function isStaleActiveRunPointer(
 	return ageMs > activeRunTtlHours() * 60 * 60 * 1000;
 }
 
+export interface ActiveRunOwnershipConflict {
+	runId: string;
+	ownerPiSessionId: string;
+}
+
+/** True when another Pi session owns a non-stale active run on disk. */
+export async function findActiveRunOwnershipConflict(
+	projectRoot: string,
+	sessionId: string,
+): Promise<ActiveRunOwnershipConflict | null> {
+	const pointer = await loadProjectActiveRun(projectRoot);
+	if (!pointer || isStaleActiveRunPointer(pointer, projectRoot)) return null;
+	if (pointer.owner_pi_session_id === sessionId) return null;
+	const disk = await loadRunContextFromDisk(pointer.run_id, projectRoot);
+	if (!disk || disk.status !== "active") return null;
+	return {
+		runId: pointer.run_id,
+		ownerPiSessionId: pointer.owner_pi_session_id,
+	};
+}
+
+/** QA smoke: drop stale harness-qa-live ownership left by interrupted live QA runs. */
+export async function releaseForeignQaRunOwnership(
+	projectRoot: string,
+	sessionId: string,
+): Promise<boolean> {
+	if (process.env.HARNESS_QA_SMOKE !== "1") return false;
+	const pointer = await loadProjectActiveRun(projectRoot);
+	if (!pointer || pointer.owner_pi_session_id === sessionId) return false;
+	if (!pointer.owner_pi_session_id.startsWith("harness-qa-live-")) {
+		return false;
+	}
+	const disk = await loadRunContextFromDisk(pointer.run_id, projectRoot);
+	if (disk && disk.status === "active") {
+		await saveRunContextToDisk({
+			...disk,
+			status: "aborted",
+			last_outcome: "abandoned",
+			last_completed_step: "abort",
+			updated_at: nowIso(),
+		});
+	}
+	await deleteProjectActiveRun(projectRoot);
+	return true;
+}
+
 export interface CrossSessionResumeInfo {
 	runId: string;
 	resumeCommand: string;
@@ -1937,8 +2030,32 @@ export function isHarnessBootstrapPrompt(prompt: string): boolean {
 }
 
 export function hasHarnessAbortSignal(prompt: string): boolean {
-	const p = prompt.toLowerCase();
-	return p.includes("/harness-abort") || p.includes("harness-abort");
+	const slice = userVisiblePromptSlice(prompt);
+	for (const line of slice.split("\n")) {
+		const parsed = parseHarnessSlashInput(line.trim());
+		if (parsed?.command === "harness-abort") return true;
+	}
+	return false;
+}
+
+/** Slash command line for AGT prompt defense — not expanded prompt template bodies. */
+export function harnessSlashCommandLineForPolicy(
+	prompt: string,
+	entries?: unknown[],
+): string | null {
+	const slice = userVisiblePromptSlice(prompt);
+	for (const line of slice.split("\n")) {
+		const trimmed = line.trim();
+		const parsed = parseHarnessSlashInput(trimmed);
+		if (parsed) return trimmed;
+	}
+	if (entries?.length) {
+		const turn = getLatestHarnessTurn(entries);
+		if (turn?.command) {
+			return `/${turn.command}${turn.args ? ` ${turn.args}` : ""}`.trim();
+		}
+	}
+	return null;
 }
 
 /** Mirrors policy-gate phase checks so run-context does not inject on blocked turns. */
@@ -2007,20 +2124,6 @@ export function isNewTaskPlanBlocked(
 	return newTask.length > 0 && prior.length > 0;
 }
 
-export type RemediationClass =
-	| "pass"
-	| "implementation_gap"
-	| "plan_gap"
-	| "rollback"
-	| "inconclusive";
-
-export interface ReviewOutcomeLike {
-	schema_version?: string;
-	status?: string;
-	remediation_class?: RemediationClass | string;
-	recommended_next?: string;
-}
-
 export async function readReviewOutcomeFromRun(
 	runId: string,
 	projectRoot: string,
@@ -2038,62 +2141,6 @@ export async function readReviewOutcomeFromRun(
 	}
 }
 
-/** Infer remediation when parent skipped Phase 6 but eval-verdict exists on disk. */
-export function remediationClassFromEvalVerdict(
-	verdict: EvalVerdictDisk | null,
-): RemediationClass | null {
-	if (!verdict) return null;
-	const status = (verdict.status ?? "").toLowerCase();
-	if (status === "pass") return "pass";
-	const action = (verdict.recommended_action ?? "").toLowerCase();
-	if (
-		action === "replan" ||
-		action.includes("revise") ||
-		action.includes("plan")
-	) {
-		return "plan_gap";
-	}
-	if (action === "rollback" || action.includes("rollback")) {
-		return "rollback";
-	}
-	if (
-		action === "steer" ||
-		action === "repair" ||
-		action.includes("implement")
-	) {
-		return "implementation_gap";
-	}
-	const failed = (verdict as EvalVerdictDisk & { failed_checks?: string[] })
-		.failed_checks;
-	const joined = Array.isArray(failed) ? failed.join(" ").toLowerCase() : "";
-	if (
-		joined.includes("scope_minimization") ||
-		joined.includes("scope_drift") ||
-		joined.includes("replan")
-	) {
-		return "plan_gap";
-	}
-	if (status === "fail") return "inconclusive";
-	return null;
-}
-
-export function recommendedNextForRemediation(
-	remediation: RemediationClass,
-): string {
-	switch (remediation) {
-		case "pass":
-			return "/harness-policy-status";
-		case "implementation_gap":
-			return "/harness-steer";
-		case "plan_gap":
-			return "/harness-plan (mode: revise)";
-		case "rollback":
-			return "/harness-incident";
-		default:
-			return "/harness-review";
-	}
-}
-
 export async function resolveRemediationClassForRun(
 	runId: string,
 	projectRoot: string,