ultimate-pi 0.23.0 → 0.25.0

package/.pi/extensions/harness-telemetry.ts

@@ -53,6 +53,7 @@ const FLUSH_MAP: Record<string, HarnessPostHogEventName> = {
 	"harness-eval-verdict": "harness_eval_verdict",
 	"harness-sentrux-signal": "harness_sentrux_signal",
 	"harness-observation": "harness_observation",
+	"harness-phase-completed": "harness_phase_completed",
 };
 
 function hashEntry(customType: string, data: unknown): string {

package/.pi/extensions/harness-web-tools.ts

@@ -32,6 +32,7 @@ import {
 	summarizeSearchJson,
 } from "../lib/harness-web/run-cli.js";
 
+// @ts-expect-error pi extensions run as ESM
 const MODULE_URL = import.meta.url;
 
 const WEB_SEARCH_GUIDELINES = [

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

@@ -60,6 +60,7 @@ const PHASE_ORDER: HarnessPhase[] = [
 	"merge",
 ];
 
+// @ts-expect-error pi extensions run as ESM
 const MODULE_URL = import.meta.url;
 
 const MUTATING_TOOLS = new Set(["write", "edit"]);
@@ -183,6 +184,10 @@ async function handlePolicyBeforeAgentStart(args: {
 		stateRef.current.updatedAt = stateRef.current.abortedAt;
 		stateRef.current = state;
 		pi.appendEntry("harness-policy-state", stateRef.current);
+		pi.events.emit("harness-run-aborted", {
+			reason: state.abortReason,
+			abortedAt: stateRef.current.abortedAt,
+		});
 		return {
 			message: {
 				customType: "harness-policy-aborted",
@@ -435,6 +440,10 @@ export default function policyGate(pi: ExtensionAPI) {
 			stateRef.current.abortedAt = nowIso();
 			stateRef.current.updatedAt = stateRef.current.abortedAt;
 			pi.appendEntry("harness-policy-state", stateRef.current);
+			pi.events.emit("harness-run-aborted", {
+				reason: stateRef.current.abortReason,
+				abortedAt: stateRef.current.abortedAt,
+			});
 
 			const runCtx = getLatestRunContext(ctx.sessionManager.getEntries());
 			if (runCtx) {

package/.pi/extensions/trace-recorder.ts

@@ -227,6 +227,7 @@ export default function traceRecorder(pi: ExtensionAPI) {
 			plan_id: activeRun.planId,
 			phase: activeRun.phase,
 			started_at: startedAt,
+			phase_started_at: startedAt,
 		});
 
 		const runCtx = getLatestRunContext(entries);

package/.pi/harness/agents.manifest.json

@@ -1,7 +1,7 @@
 {
 	"schema_version": "1.0.0",
 	"package": "ultimate-pi",
-	"package_version": "0.22.1",
+	"package_version": "0.25.0",
 	"generated_at": "2026-05-27T15:57:32.501Z",
 	"policy_sha256": "1a631333f1abed3b411961d3527bcae2d4fcd2f715b09a689b0b83b3ea0f54f3",
 	"agents": {

package/.pi/harness/docs/adrs/0056-agent-native-speed-wiring.md

@@ -0,0 +1,26 @@
+# ADR 0056: Agent-native speed wiring (v0.25.0)
+
+Status: Accepted  
+Date: 2026-06-06
+
+## Context
+
+ADR 0042 documented agent-native orchestration (parallel probes, synthesizer path, FSM). v0.24.0 shipped latency infrastructure but runtime wiring remained meeting-shaped: `harness_debate_open` ignored `parallel_probes`, gates fell back to threaded mode, and parents re-reasoned every turn.
+
+## Decision
+
+1. **parallel_probes end-to-end** — `review_gate_mode` includes `parallel_probes`; eligibility snapshot at `artifacts/plan-debate-eligibility.yaml`; `effectiveMinFocusRounds` caps bus checks to 1; focus coverage parses `review-round-parallel-probes.yaml`.
+2. **SSOT routing** — `planReviewGateModeForProfile`: fast→consolidated, standard→parallel_probes, light/full→threaded.
+3. **plan-synthesizer default** — low/med route via `harness_plan_route`; readiness waives separate decompose/hypothesis when all three synthesizer artifacts exist.
+4. **Auto-approve** — `HARNESS_PLAN_AUTO_APPROVE` with `canAutoApprovePlan` / audit artifact; requires non-interactive or `force`.
+5. **Plan FSM** — `derivePlanNextAction` + `harness_plan_next_action` tool.
+6. **Spawn budget enforce** — per-phase caps when `HARNESS_BUDGET_ENFORCE=1` (plan 12, execute 3, evaluate 6).
+7. **Review parallel default** — evaluator∥adversary on by default unless `HARNESS_REVIEW_PARALLEL=0`, `--quick`, or steer_attempt ≥ 2.
+8. **Auto-compact 50%** — `harness-auto-compact` extension with hysteresis; subagent compact off by default.
+9. **Phase worker spike** — `HARNESS_PHASE_WORKER=1` env only; no cross evaluator/adversary resume.
+
+## Consequences
+
+- Med-risk plans complete Review Gate in ≤4 debate spawns (validator, parallel evaluator∥adversary, integrator, submit).
+- `HARNESS_REVIEW_PARALLEL=0` remains CI escape hatch.
+- Amend ADR 0030 for 50% harness compact gate.

package/.pi/harness/env.harness.template

@@ -52,3 +52,17 @@ VAULT_WIKI_PATH=vault/wiki
 # --- Sentrux fitness functions ---
 # Require sentrux check + run signal (or CI stub) in harness-verify
 HARNESS_SENTRUX_REQUIRED=true
+# HARNESS_SENTRUX_TIMEOUT_MS=300000
+# HARNESS_SUBAGENT_TIMEOUT_PLAN_MS=1800000
+# HARNESS_SUBAGENT_TIMEOUT_EXECUTE_MS=2700000
+# HARNESS_SUBAGENT_TIMEOUT_REVIEW_MS=1200000
+# HARNESS_SUBAGENT_TIMEOUT_DISABLE=0
+# HARNESS_DEBATE_WALL_CLOCK_MS=1200000
+# HARNESS_REVIEW_PARALLEL=0  # unset = parallel evaluator∥adversary default on (med/high, non-quick)
+# HARNESS_PLAN_AUTO_APPROVE=1  # requires HARNESS_NON_INTERACTIVE=1 or =force
+# HARNESS_COMPACT_THRESHOLD_PERCENT=50
+# HARNESS_COMPACT_REARM_PERCENT=40
+# HARNESS_COMPACT_AUTO=true
+# HARNESS_COMPACT_SUBAGENTS=false
+# HARNESS_PHASE_WORKER=1
+# HARNESS_COCOINDEX_REFRESH_DEBOUNCE_MS=300000

package/.pi/harness/specs/harness-posthog-event.schema.json

@@ -27,8 +27,10 @@
 				"harness_observation",
 				"harness_subagent_spawned",
 				"harness_subagent_completed",
+				"harness_subagent_timeout",
 				"harness_subagent_result_wait",
 				"harness_subagent_setup",
+				"harness_phase_completed",
 				"harness_blackboard_op"
 			]
 		},

package/.pi/harness/specs/sentrux-signal.schema.json

@@ -26,7 +26,7 @@
 		},
 		"gate_status": {
 			"type": "string",
-			"enum": ["pass", "degraded", "skipped", "not_installed"]
+			"enum": ["pass", "degraded", "skipped", "not_installed", "timeout"]
 		},
 		"quality_signal_summary": {
 			"type": "string"

package/.pi/lib/harness-auto-approve.ts

@@ -0,0 +1,140 @@
+/**
+ * Deterministic plan auto-approve when gates pass (HARNESS_PLAN_AUTO_APPROVE).
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { isHarnessNonInteractive } from "./ask-user/policy.js";
+import type { PlanApprovalReadiness } from "./plan-approval-readiness.js";
+import { loadPlanDebateEligibilitySnapshot } from "./plan-debate-eligibility-snapshot.js";
+import type { PlanDebateGateResult } from "./plan-debate-gate.js";
+import { readTaskClarificationDoc } from "./plan-task-clarification.js";
+
+function missingPlanningContextReadinessError(error: string): boolean {
+	return (
+		error.includes("planning-context.yaml") ||
+		error.includes("missing artifacts/planning-context.yaml") ||
+		error.includes("missing:planning-reconnaissance")
+	);
+}
+
+function missingPhase35ReadinessError(error: string): boolean {
+	return (
+		error.includes("implementation-research.yaml") ||
+		error.includes("stack.yaml") ||
+		error.includes("Phase 3.5")
+	);
+}
+
+export const PLAN_APPROVAL_AUDIT_ARTIFACT =
+	"artifacts/plan-approval-audit.yaml";
+
+export function isHarnessPlanAutoApproveForce(): boolean {
+	return (
+		process.env.HARNESS_PLAN_AUTO_APPROVE?.trim().toLowerCase() === "force"
+	);
+}
+
+export function isHarnessPlanAutoApproveEnabled(): boolean {
+	const raw = process.env.HARNESS_PLAN_AUTO_APPROVE?.trim().toLowerCase();
+	if (!raw || raw === "0" || raw === "false" || raw === "off") return false;
+	if (raw === "force") return true;
+	return raw === "1" || raw === "true" || raw === "on";
+}
+
+export interface AutoApprovePolicyInput {
+	projectRoot: string;
+	runId: string;
+	riskLevel: string;
+	readiness: PlanApprovalReadiness;
+	debateGate: PlanDebateGateResult;
+	dagPass?: boolean;
+}
+
+export interface AutoApprovePolicyResult {
+	allowed: boolean;
+	reasons: string[];
+}
+
+export async function canAutoApprovePlan(
+	input: AutoApprovePolicyInput,
+): Promise<AutoApprovePolicyResult> {
+	const reasons: string[] = [];
+	if (!isHarnessPlanAutoApproveEnabled()) {
+		return { allowed: false, reasons: ["HARNESS_PLAN_AUTO_APPROVE not set"] };
+	}
+	if (!isHarnessPlanAutoApproveForce() && !isHarnessNonInteractive()) {
+		reasons.push(
+			"interactive session — set HARNESS_NON_INTERACTIVE=1 or HARNESS_PLAN_AUTO_APPROVE=force",
+		);
+	}
+	const risk = String(input.riskLevel ?? "med").toLowerCase();
+	const qaSmoke =
+		process.env.HARNESS_QA_SMOKE === "1" && isHarnessNonInteractive();
+	if (risk === "high" && !qaSmoke)
+		reasons.push("high risk requires human approval");
+	if (!input.readiness.ok) {
+		for (const err of input.readiness.errors) {
+			if (
+				qaSmoke &&
+				risk === "low" &&
+				(missingPlanningContextReadinessError(err) ||
+					missingPhase35ReadinessError(err))
+			) {
+				continue;
+			}
+			reasons.push(`readiness: ${err}`);
+		}
+	}
+	if (!input.debateGate.ok) {
+		reasons.push(...input.debateGate.errors.map((e) => `debate: ${e}`));
+	}
+	if (input.debateGate.warnings.some((w) => /block/i.test(w))) {
+		reasons.push("debate gate warnings include blocker");
+	}
+	const runDir = join(input.projectRoot, ".pi", "harness", "runs", input.runId);
+	const eligibility = await loadPlanDebateEligibilitySnapshot(runDir);
+	if (eligibility?.human_required) {
+		reasons.push("eligibility human_required=true");
+	}
+	const clar = await readTaskClarificationDoc(runDir);
+	if (clar?.needs_clarification === true) {
+		reasons.push("task-clarification needs_clarification");
+	}
+	if (input.dagPass === false) {
+		reasons.push("DAG validation not passed");
+	}
+	return { allowed: reasons.length === 0, reasons };
+}
+
+export async function writePlanApprovalAudit(
+	runDir: string,
+	doc: Record<string, unknown>,
+): Promise<void> {
+	const abs = join(runDir, PLAN_APPROVAL_AUDIT_ARTIFACT);
+	await mkdir(join(runDir, "artifacts"), { recursive: true });
+	await writeFile(abs, stringifyYaml(doc), "utf-8");
+}
+
+export interface AutoApproveOutcome {
+	approved: boolean;
+	reasons: string[];
+}
+
+/** Returns whether auto-approve was applied (caller skips dialog when true). */
+export async function tryAutoApprovePlan(
+	input: AutoApprovePolicyInput,
+): Promise<AutoApproveOutcome> {
+	const policy = await canAutoApprovePlan(input);
+	const runDir = join(input.projectRoot, ".pi", "harness", "runs", input.runId);
+	await writePlanApprovalAudit(runDir, {
+		schema_version: "1.0.0",
+		source: policy.allowed ? "auto" : "blocked",
+		captured_at: new Date().toISOString(),
+		allowed: policy.allowed,
+		reasons: policy.reasons,
+		risk_level: input.riskLevel,
+	});
+	return { approved: policy.allowed, reasons: policy.reasons };
+}

package/.pi/lib/harness-auto-compact-policy.ts

@@ -0,0 +1,85 @@
+/**
+ * Harness 50% auto-compact gate policy (testable without pi runtime).
+ */
+
+import {
+	resolveCompactAuto,
+	resolveCompactRearmPercent,
+	resolveCompactSubagents,
+	resolveCompactThresholdPercent,
+} from "./harness-vcc-settings.js";
+
+export interface CompactUsage {
+	percent: number | null;
+	tokens?: number;
+	contextWindow?: number;
+}
+
+export interface CompactGateState {
+	armed: boolean;
+	inFlight: boolean;
+	cooldownTurns: number;
+	subagentSpawnPending: boolean;
+}
+
+export interface CompactGateDecision {
+	shouldCompact: boolean;
+	reason?: string;
+}
+
+export function createCompactGateState(): CompactGateState {
+	return {
+		armed: true,
+		inFlight: false,
+		cooldownTurns: 0,
+		subagentSpawnPending: false,
+	};
+}
+
+export function evaluateAutoCompactGate(
+	usage: CompactUsage,
+	state: CompactGateState,
+	opts?: { isSubagent?: boolean },
+): CompactGateDecision {
+	if (!resolveCompactAuto()) {
+		return { shouldCompact: false, reason: "HARNESS_COMPACT_AUTO=false" };
+	}
+	if (opts?.isSubagent && !resolveCompactSubagents()) {
+		return { shouldCompact: false, reason: "subagent compact disabled" };
+	}
+	if (state.subagentSpawnPending) {
+		return { shouldCompact: false, reason: "defer until subagent idle" };
+	}
+	if (state.inFlight) {
+		return { shouldCompact: false, reason: "compaction in flight" };
+	}
+	if (state.cooldownTurns > 0) {
+		return { shouldCompact: false, reason: "VCC cancel cooldown" };
+	}
+	if (!state.armed) {
+		const rearm = resolveCompactRearmPercent();
+		if (usage.percent != null && usage.percent < rearm) {
+			state.armed = true;
+		} else {
+			return { shouldCompact: false, reason: "hysteresis disarmed" };
+		}
+	}
+	const threshold = resolveCompactThresholdPercent();
+	if (usage.percent == null) {
+		return { shouldCompact: false, reason: "usage percent null" };
+	}
+	if (usage.percent < threshold) {
+		return { shouldCompact: false, reason: "below threshold" };
+	}
+	return { shouldCompact: true };
+}
+
+export function onSessionCompact(state: CompactGateState): void {
+	state.armed = false;
+	state.inFlight = false;
+}
+
+export function onCompactCancel(state: CompactGateState): void {
+	state.inFlight = false;
+	state.cooldownTurns = 2;
+}

package/.pi/lib/harness-cocoindex-refresh.ts

@@ -4,12 +4,82 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
+const MARKER_REL = join(".cocoindex_code", ".harness-last-index.json");
 
-export function refreshHarnessCocoindexIndex(cwd: string): string | undefined {
+interface IndexMarker {
+	indexed_at_ms: number;
+	git_head: string | null;
+	porcelain_empty: boolean;
+}
+
+function readMarker(cwd: string): IndexMarker | null {
+	const path = join(cwd, MARKER_REL);
+	try {
+		return JSON.parse(readFileSync(path, "utf8")) as IndexMarker;
+	} catch {
+		return null;
+	}
+}
+
+function writeMarker(cwd: string, marker: IndexMarker): void {
+	const path = join(cwd, MARKER_REL);
+	writeFileSync(path, `${JSON.stringify(marker, null, 2)}\n`, "utf8");
+}
+
+function gitHead(cwd: string): string | null {
+	const r = spawnSync("git", ["rev-parse", "HEAD"], {
+		cwd,
+		encoding: "utf8",
+		stdio: "pipe",
+	});
+	if (r.status !== 0) return null;
+	return (r.stdout ?? "").trim() || null;
+}
+
+function gitPorcelainEmpty(cwd: string): boolean {
+	const r = spawnSync("git", ["status", "--porcelain"], {
+		cwd,
+		encoding: "utf8",
+		stdio: "pipe",
+	});
+	if (r.status !== 0) return false;
+	return !(r.stdout ?? "").trim();
+}
+
+function shouldSkipIndex(cwd: string, forceExecuteRefresh: boolean): boolean {
+	if (forceExecuteRefresh) return false;
+	if (process.env.HARNESS_COCOINDEX_REFRESH === "0") return true;
+
+	const debounceMs = Number(
+		process.env.HARNESS_COCOINDEX_REFRESH_DEBOUNCE_MS ?? 300_000,
+	);
+	if (!Number.isFinite(debounceMs) || debounceMs <= 0) return false;
+
+	const marker = readMarker(cwd);
+	if (!marker) return false;
+
+	const age = Date.now() - marker.indexed_at_ms;
+	if (age >= debounceMs) return false;
+
+	const head = gitHead(cwd);
+	const porcelainEmpty = gitPorcelainEmpty(cwd);
+	if (!porcelainEmpty) return false;
+	if (head && marker.git_head && head !== marker.git_head) return false;
+
+	console.error(
+		`harness-cocoindex: skip ccc index (debounced ${Math.round(age / 1000)}s ago, git clean)`,
+	);
+	return true;
+}
+
+export function refreshHarnessCocoindexIndex(
+	cwd: string,
+	opts?: { forceExecuteRefresh?: boolean },
+): string | undefined {
 	if (process.env.HARNESS_COCOINDEX_REFRESH === "0") {
 		return undefined;
 	}
@@ -18,6 +88,10 @@ export function refreshHarnessCocoindexIndex(cwd: string): string | undefined {
 		return undefined;
 	}
 
+	if (shouldSkipIndex(cwd, opts?.forceExecuteRefresh === true)) {
+		return undefined;
+	}
+
 	const timeoutMs = Number(
 		process.env.HARNESS_COCOINDEX_REFRESH_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS,
 	);
@@ -45,5 +119,11 @@ export function refreshHarnessCocoindexIndex(cwd: string): string | undefined {
 		return `${msg} — continuing`;
 	}
 
+	writeMarker(cwd, {
+		indexed_at_ms: Date.now(),
+		git_head: gitHead(cwd),
+		porcelain_empty: gitPorcelainEmpty(cwd),
+	});
+
 	return undefined;
 }

package/.pi/lib/harness-phase-telemetry.ts

@@ -0,0 +1,81 @@
+/**
+ * Phase boundary telemetry helpers (harness_phase_completed, phase_started_at).
+ */
+
+import type { HarnessPhase } from "./harness-run-context.js";
+
+const phaseStartedAt = new Map<string, number>();
+const phaseCompletedKeys = new Set<string>();
+const phaseSubagentCounts = new Map<string, number>();
+
+function phaseKey(runId: string, phase: HarnessPhase): string {
+	return `${runId}:${phase}`;
+}
+
+export function recordHarnessPhaseStart(
+	runId: string,
+	phase: HarnessPhase,
+): void {
+	const key = phaseKey(runId, phase);
+	if (!phaseStartedAt.has(key)) {
+		phaseStartedAt.set(key, Date.now());
+	}
+}
+
+export function incrementHarnessPhaseSubagentCount(
+	runId: string,
+	phase: HarnessPhase,
+	delta = 1,
+): void {
+	const key = phaseKey(runId, phase);
+	phaseSubagentCounts.set(key, (phaseSubagentCounts.get(key) ?? 0) + delta);
+}
+
+export function phaseTerminalArtifact(
+	artifactPath: string,
+): HarnessPhase | null {
+	const norm = artifactPath.replace(/\\/g, "/");
+	if (norm === "artifacts/task-clarification.yaml") return "plan";
+	if (norm === "plan-packet.yaml") return "plan";
+	if (norm === "handoff/executor-summary.yaml") return "execute";
+	if (norm === "artifacts/review-outcome.yaml") return "evaluate";
+	return null;
+}
+
+export function buildPhaseCompletedPayload(
+	runId: string,
+	phase: HarnessPhase,
+): {
+	harness_run_id: string;
+	run_id: string;
+	harness_phase: HarnessPhase;
+	duration_ms: number;
+	subagent_count: number;
+} | null {
+	const key = phaseKey(runId, phase);
+	if (phaseCompletedKeys.has(key)) return null;
+
+	const started = phaseStartedAt.get(key) ?? Date.now();
+	phaseCompletedKeys.add(key);
+
+	return {
+		harness_run_id: runId,
+		run_id: runId,
+		harness_phase: phase,
+		duration_ms: Math.max(0, Date.now() - started),
+		subagent_count: phaseSubagentCounts.get(key) ?? 0,
+	};
+}
+
+export function resetHarnessPhaseTelemetryForTests(): void {
+	phaseStartedAt.clear();
+	phaseCompletedKeys.clear();
+	phaseSubagentCounts.clear();
+}
+
+export function getHarnessPhaseSubagentCount(
+	runId: string,
+	phase: HarnessPhase,
+): number {
+	return phaseSubagentCounts.get(phaseKey(runId, phase)) ?? 0;
+}

package/.pi/lib/harness-phase-worker.ts

@@ -0,0 +1,23 @@
+/**
+ * Phase worker resume eligibility (HARNESS_PHASE_WORKER=1 spike).
+ * Never resume across evaluator ↔ adversary — preserves generator–evaluator isolation.
+ */
+
+const DEBATE_ISOLATION_PAIRS = new Set([
+	"harness/planning/plan-evaluator",
+	"harness/planning/plan-adversary",
+]);
+
+export function isHarnessPhaseWorkerEnabled(): boolean {
+	return process.env.HARNESS_PHASE_WORKER === "1";
+}
+
+export function phaseWorkerResumeEligible(
+	priorAgent: string | null,
+	nextAgent: string,
+): boolean {
+	if (!isHarnessPhaseWorkerEnabled()) return false;
+	if (!priorAgent || priorAgent !== nextAgent) return false;
+	if (DEBATE_ISOLATION_PAIRS.has(nextAgent)) return false;
+	return true;
+}