ultimate-pi 0.14.0 → 0.16.0

package/.pi/harness/specs/plan-implementation-research-brief.schema.json

@@ -0,0 +1,128 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-implementation-research-brief.schema.json",
+	"title": "PlanImplementationResearchBrief",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"problem_framing",
+		"sub_problems",
+		"internal_references",
+		"external_references",
+		"solution_patterns",
+		"similar_implementations",
+		"recommended_approach",
+		"anti_patterns",
+		"open_questions"
+	],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"problem_framing": { "type": "string", "minLength": 1 },
+		"sub_problems": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"internal_references": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/internal_reference" }
+		},
+		"external_references": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/external_reference" }
+		},
+		"solution_patterns": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/solution_pattern" }
+		},
+		"similar_implementations": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/similar_implementation" }
+		},
+		"recommended_approach": { "$ref": "#/$defs/recommended_approach" },
+		"anti_patterns": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"open_questions": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"deep_research_recommended": { "type": "boolean" }
+	},
+	"$defs": {
+		"internal_reference": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["path", "relevance", "reuse_signal"],
+			"properties": {
+				"path": { "type": "string" },
+				"relevance": { "type": "string" },
+				"reuse_signal": {
+					"type": "string",
+					"enum": ["high", "med", "low", "none"]
+				}
+			}
+		},
+		"external_reference": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["url", "source_type", "summary", "evidence_grade"],
+			"properties": {
+				"url": { "type": "string" },
+				"source_type": { "type": "string" },
+				"summary": { "type": "string" },
+				"evidence_grade": {
+					"type": "string",
+					"enum": ["primary", "secondary", "anecdotal"]
+				}
+			}
+		},
+		"solution_pattern": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["name", "provenance", "fit", "tradeoffs", "risks"],
+			"properties": {
+				"name": { "type": "string" },
+				"provenance": { "type": "string" },
+				"fit": { "type": "string" },
+				"tradeoffs": {
+					"type": "object",
+					"required": ["pros", "cons"],
+					"properties": {
+						"pros": { "type": "array", "items": { "type": "string" } },
+						"cons": { "type": "array", "items": { "type": "string" } }
+					}
+				},
+				"risks": { "type": "array", "items": { "type": "string" } }
+			}
+		},
+		"similar_implementation": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["name", "what_it_solves", "gap_vs_us"],
+			"properties": {
+				"name": { "type": "string" },
+				"what_it_solves": { "type": "string" },
+				"gap_vs_us": { "type": "string" }
+			}
+		},
+		"recommended_approach": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["summary", "recommended_approach_confidence"],
+			"properties": {
+				"summary": { "type": "string", "minLength": 1 },
+				"recommended_approach_confidence": {
+					"type": "string",
+					"enum": ["low", "med", "high"]
+				},
+				"confidence_rationale": { "type": "string" },
+				"evidence_refs": {
+					"type": "array",
+					"items": { "type": "string" }
+				}
+			}
+		}
+	}
+}

package/.pi/harness/specs/plan-review-round-draft.schema.json

@@ -13,7 +13,7 @@
 	],
 	"properties": {
 		"schema_version": { "type": "string", "const": "1.0.0" },
-		"round_index": { "type": "integer", "minimum": 1, "maximum": 4 },
+		"round_index": { "type": "integer", "minimum": 1, "maximum": 12 },
 		"debate_round_focus": {
 			"type": "string",
 			"enum": ["spec", "wbs", "schedule", "quality"]

package/.pi/harness/specs/plan-scout-findings.schema.json

@@ -0,0 +1,19 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-scout-findings.schema.json",
+	"title": "PlanScoutFindings",
+	"type": "object",
+	"additionalProperties": true,
+	"required": ["schema_version", "lane", "summary"],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"lane": {
+			"type": "string",
+			"enum": ["graphify", "structure", "semantic"]
+		},
+		"scout_lane": { "type": "string" },
+		"summary": { "type": "string", "minLength": 1 },
+		"key_paths": { "type": "array", "items": { "type": "string" } },
+		"findings": { "type": "array" }
+	}
+}

package/.pi/harness/specs/round-result.schema.json

@@ -39,7 +39,7 @@
 		"round_index": {
 			"type": "integer",
 			"minimum": 1,
-			"maximum": 6
+			"maximum": 12
 		},
 		"participants": {
 			"type": "array",
@@ -104,7 +104,9 @@
 			"additionalProperties": false,
 			"required": [
 				"name",
+				"min_focus_rounds",
 				"max_rounds",
+				"max_exchanges_per_round",
 				"round_token_cap",
 				"debate_global_cap"
 			],
@@ -113,8 +115,19 @@
 					"type": "string",
 					"enum": ["aggressive", "plan"]
 				},
+				"min_focus_rounds": {
+					"type": "integer",
+					"minimum": 1
+				},
 				"max_rounds": {
-					"type": "integer"
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 12
+				},
+				"max_exchanges_per_round": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 6
 				},
 				"round_token_cap": {
 					"type": "integer"

package/.pi/lib/harness-agent-output.ts

@@ -21,6 +21,51 @@ export function extractJsonBlock(text: string): string | null {
 	return null;
 }
 
+export interface ToolCallPartLike {
+	type?: string;
+	name?: string;
+	arguments?: Record<string, unknown>;
+}
+
+export interface MessageLike {
+	role?: string;
+	content?: ToolCallPartLike[] | unknown;
+}
+
+/** Last matching submit_* tool call in subprocess messages (chain-safe). */
+export function extractLastSubmitCall(
+	messages: MessageLike[],
+	toolNames: string | string[],
+): { toolName: string; document: Record<string, unknown> } | null {
+	const allowed = new Set(
+		(Array.isArray(toolNames) ? toolNames : [toolNames]).map((n) => n.trim()),
+	);
+	let last: { toolName: string; document: Record<string, unknown> } | null =
+		null;
+	for (const msg of messages) {
+		if (msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
+		for (const part of msg.content) {
+			if (part.type !== "toolCall" || !part.name) continue;
+			if (!allowed.has(part.name)) continue;
+			const doc = part.arguments?.document;
+			if (doc && typeof doc === "object" && !Array.isArray(doc)) {
+				last = {
+					toolName: part.name,
+					document: doc as Record<string, unknown>,
+				};
+			}
+		}
+	}
+	return last;
+}
+
+export function extractLastSubmitCallForAgent(
+	messages: MessageLike[],
+	agentToolNames: readonly string[],
+): { toolName: string; document: Record<string, unknown> } | null {
+	return extractLastSubmitCall(messages, [...agentToolNames]);
+}
+
 export function parseHarnessAgentJson<T extends Record<string, unknown>>(
 	text: string,
 ): { ok: true; value: T } | { ok: false; error: string } {

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

@@ -0,0 +1,18 @@
+/**
+ * Central switch for harness token/debate budget enforcement.
+ * Default: telemetry-only (HARNESS_BUDGET_ENFORCE off).
+ */
+
+export function isHarnessBudgetEnforceOn(): boolean {
+	const raw = (process.env.HARNESS_BUDGET_ENFORCE ?? "off").toLowerCase();
+	return raw === "1" || raw === "true" || raw === "on";
+}
+
+/** When false, soft-limit and debate telemetry must not block UI or gates. */
+export function shouldEmitBlockingBudgetExhausted(): boolean {
+	if (!isHarnessBudgetEnforceOn()) return false;
+	return (
+		process.env.HARNESS_BUDGET_HARD_STOP === "true" ||
+		process.env.HARNESS_DEBATE_HARD_STOP === "true"
+	);
+}

package/.pi/lib/harness-schema-validate.ts

@@ -0,0 +1,89 @@
+/**
+ * JSON Schema validation for harness submit tools (Ajv draft 2020-12, offline).
+ */
+
+import { appendFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import addFormats from "ajv-formats";
+
+type ValidateFn = (data: unknown) => boolean;
+
+const compileCache = new Map<string, ValidateFn>();
+const DEBUG_LOG_PATH =
+	"/home/aryaniyaps/ai-projects/ultimate-pi/.cursor/debug-2ca12b.log";
+
+let ajvSingleton: InstanceType<typeof Ajv2020> | null = null;
+
+function getAjv(): InstanceType<typeof Ajv2020> {
+	if (!ajvSingleton) {
+		ajvSingleton = new Ajv2020({
+			allErrors: true,
+			strict: false,
+			validateSchema: false,
+		});
+		addFormats(ajvSingleton);
+	}
+	return ajvSingleton;
+}
+
+async function debugLog(
+	hypothesisId: string,
+	message: string,
+	data: Record<string, unknown>,
+): Promise<void> {
+	// #region agent log
+	try {
+		await appendFile(
+			DEBUG_LOG_PATH,
+			`${JSON.stringify({
+				sessionId: "2ca12b",
+				hypothesisId,
+				location: "harness-schema-validate.ts",
+				message,
+				data,
+				timestamp: Date.now(),
+			})}\n`,
+		);
+	} catch {
+		/* ignore */
+	}
+	// #endregion
+}
+
+export async function validateAgainstHarnessSchema(
+	specsDir: string,
+	schemaFile: string,
+	document: unknown,
+): Promise<{ ok: true } | { ok: false; errors: string[] }> {
+	const cacheKey = `${specsDir}:${schemaFile}`;
+	let validate = compileCache.get(cacheKey);
+	if (!validate) {
+		const schemaPath = join(specsDir, schemaFile);
+		const raw = await readFile(schemaPath, "utf-8");
+		const schema = JSON.parse(raw) as Record<string, unknown>;
+		try {
+			const ajv = getAjv();
+			const compiled = ajv.compile(schema);
+			validate = compiled;
+			compileCache.set(cacheKey, compiled);
+			await debugLog("H3", "schema compile ok", { schemaFile });
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			await debugLog("H3", "schema compile failed", { schemaFile, error: msg });
+			return { ok: false, errors: [`schema compile failed: ${msg}`] };
+		}
+	}
+	const ok = validate(document);
+	if (ok) return { ok: true };
+	const errors = (
+		(
+			validate as {
+				errors?: Array<{ instancePath?: string; message?: string }>;
+			}
+		).errors ?? []
+	).map((e: { instancePath?: string; message?: string }) =>
+		`${e.instancePath || "/"} ${e.message ?? "invalid"}`.trim(),
+	);
+	return { ok: false, errors };
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Parse HarnessSpawnContext embedded in subagent task strings.
+ */
+
+const SPAWN_CTX_EQ_RE = /HarnessSpawnContext\s*=\s*(\{[\s\S]*?\})(?:\s|$|\.)/;
+
+export interface ParsedSpawnContext {
+	run_id?: string;
+	run_dir?: string;
+	agent?: string;
+	plan_packet_path?: string;
+}
+
+function extractBalancedJsonObject(s: string, start: number): string | null {
+	if (s[start] !== "{") return null;
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < s.length; i++) {
+		const ch = s[i];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === '"') inString = false;
+			continue;
+		}
+		if (ch === '"') {
+			inString = true;
+			continue;
+		}
+		if (ch === "{") depth++;
+		else if (ch === "}") {
+			depth--;
+			if (depth === 0) return s.slice(start, i + 1);
+		}
+	}
+	return null;
+}
+
+function normalizeSpawnContext(parsed: unknown): ParsedSpawnContext | null {
+	if (!parsed || typeof parsed !== "object") return null;
+	const o = parsed as Record<string, unknown>;
+	const run_id = typeof o.run_id === "string" ? o.run_id : undefined;
+	const run_dir = typeof o.run_dir === "string" ? o.run_dir : undefined;
+	const agent = typeof o.agent === "string" ? o.agent : undefined;
+	const plan_packet_path =
+		typeof o.plan_packet_path === "string" ? o.plan_packet_path : undefined;
+	if (!run_id && !run_dir) return null;
+	return { run_id, run_dir, agent, plan_packet_path };
+}
+
+export function parseSpawnContextFromTask(
+	task: string,
+): ParsedSpawnContext | null {
+	const eqMatch = SPAWN_CTX_EQ_RE.exec(task);
+	if (eqMatch?.[1]) {
+		try {
+			return normalizeSpawnContext(JSON.parse(eqMatch[1]));
+		} catch {
+			// fall through to JSON-object forms
+		}
+	}
+
+	const firstBrace = task.indexOf("{");
+	if (firstBrace >= 0) {
+		const blob = extractBalancedJsonObject(task, firstBrace);
+		if (blob) {
+			try {
+				const outer = JSON.parse(blob) as Record<string, unknown>;
+				if (
+					outer.HarnessSpawnContext &&
+					typeof outer.HarnessSpawnContext === "object"
+				) {
+					return normalizeSpawnContext(outer.HarnessSpawnContext);
+				}
+				if (typeof outer.run_id === "string") {
+					return normalizeSpawnContext(outer);
+				}
+			} catch {
+				// ignore
+			}
+		}
+	}
+
+	return null;
+}

package/.pi/lib/harness-subagent-submit-path.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolve and guard harness run directories for subagent submit tools.
+ */
+
+import { realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+export function harnessRunsRoot(projectRoot: string): string {
+	return join(projectRoot, ".pi", "harness", "runs");
+}
+
+export async function resolveGuardedRunDir(opts: {
+	projectRoot: string;
+	runId: string;
+	runDirEnv?: string;
+}): Promise<{ ok: true; runDir: string } | { ok: false; error: string }> {
+	const { projectRoot, runId } = opts;
+	if (!runId.trim()) {
+		return { ok: false, error: "run_id is required" };
+	}
+	const expected = join(harnessRunsRoot(projectRoot), runId);
+	let candidate = opts.runDirEnv?.trim()
+		? resolve(projectRoot, opts.runDirEnv)
+		: expected;
+	try {
+		candidate = await realpath(candidate);
+		const expectedReal = await realpath(expected);
+		if (
+			candidate !== expectedReal &&
+			!candidate.startsWith(`${expectedReal}/`)
+		) {
+			return {
+				ok: false,
+				error: `run_dir must stay under ${expectedReal}`,
+			};
+		}
+		return { ok: true, runDir: candidate };
+	} catch {
+		return { ok: false, error: `run directory not found for run_id=${runId}` };
+	}
+}

package/.pi/lib/harness-ui-state.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { shouldEmitBlockingBudgetExhausted } from "./harness-budget-enforce.js";
 
 export type HarnessPhase =
 	| "plan"
@@ -133,6 +134,9 @@ const RELEVANT_CUSTOM_TYPES = new Set([
 	"harness-consensus-packet",
 	"harness-round-result",
 	"harness-budget-exhausted",
+	"harness-budget-soft-limit",
+	"harness-budget-telemetry",
+	"harness-debate-budget-telemetry",
 	"harness-review-integrity",
 	"harness-test-integrity-flag",
 	"harness-run-trace",
@@ -189,7 +193,7 @@ function deriveFlowSubstate(state: HarnessUiState): HarnessFlowSubstate {
 	return "idle";
 }
 
-function createStateFromEntries(entries: unknown[]): HarnessUiState {
+export function createStateFromEntries(entries: unknown[]): HarnessUiState {
 	const latest = pickLatestCustomEntries(entries);
 	const state: HarnessUiState = {
 		...DEFAULT_STATE,
@@ -212,7 +216,7 @@ function createStateFromEntries(entries: unknown[]): HarnessUiState {
 	const budget = latest.get("harness-budget-exhausted") as
 		| BudgetExhaustedLike
 		| undefined;
-	if (budget) {
+	if (budget && shouldEmitBlockingBudgetExhausted()) {
 		state.budgetExhausted = true;
 		state.budgetReason =
 			typeof budget.exhaustion_reason === "string"
@@ -223,6 +227,15 @@ function createStateFromEntries(entries: unknown[]): HarnessUiState {
 		const cap = asNumber(budget.caps?.debate_global_cap);
 		if (cap != null) state.debateBudgetCap = cap;
 	}
+	const telemetry = latest.get("harness-budget-telemetry") as
+		| BudgetExhaustedLike
+		| undefined;
+	if (telemetry && !state.budgetExhausted) {
+		const budgetUsed = asNumber(telemetry.budget_used);
+		if (budgetUsed != null) state.debateBudgetUsed = budgetUsed;
+		const cap = asNumber(telemetry.caps?.debate_global_cap);
+		if (cap != null) state.debateBudgetCap = cap;
+	}
 
 	const testIntegrity = latest.get("harness-test-integrity-flag") as
 		| TestIntegrityLike
@@ -299,6 +312,98 @@ function createStateFromEntries(entries: unknown[]): HarnessUiState {
 	return state;
 }
 
+export type HarnessStatusSeverity =
+	| "accent"
+	| "warning"
+	| "error"
+	| "success"
+	| "muted";
+
+export const HARNESS_PHASE_ORDER: readonly HarnessPhase[] = [
+	"plan",
+	"execute",
+	"evaluate",
+	"adversary",
+	"merge",
+] as const;
+
+export function formatHarnessPhaseLabel(phase: HarnessPhase): string {
+	switch (phase) {
+		case "plan":
+			return "plan";
+		case "execute":
+			return "build";
+		case "evaluate":
+			return "eval";
+		case "adversary":
+			return "review";
+		case "merge":
+			return "merge";
+	}
+}
+
+export function nextHarnessPhase(phase: HarnessPhase): HarnessPhase | null {
+	const index = HARNESS_PHASE_ORDER.indexOf(phase);
+	if (index < 0 || index >= HARNESS_PHASE_ORDER.length - 1) return null;
+	return HARNESS_PHASE_ORDER[index + 1] ?? null;
+}
+
+function truncateStatusCommand(command: string, maxLen = 40): string {
+	if (command.length <= maxLen) return command;
+	return `${command.slice(0, maxLen - 3)}...`;
+}
+
+export function deriveHarnessStatusHint(state: HarnessUiState): {
+	text: string;
+	severity: HarnessStatusSeverity;
+} {
+	if (state.budgetExhausted) {
+		return { text: "Budget limit reached", severity: "error" };
+	}
+	if (state.testIntegritySeverity === "high") {
+		return { text: "Test integrity issue", severity: "error" };
+	}
+	if (state.policyDecision === "block") {
+		return { text: "Blocked — fix issues first", severity: "error" };
+	}
+	if (
+		state.policyDecision === "human_required" ||
+		state.flowSubstate === "human-required"
+	) {
+		return { text: "Waiting for your input", severity: "warning" };
+	}
+	if (state.nextRecommendedCommand) {
+		return {
+			text: `Next: ${truncateStatusCommand(state.nextRecommendedCommand)}`,
+			severity: "accent",
+		};
+	}
+	if (state.phase === "plan") {
+		if (!state.planApproved) {
+			return { text: "Approve plan to continue", severity: "warning" };
+		}
+		return { text: "Plan approved", severity: "success" };
+	}
+	if (state.policyDecision === "pass") {
+		return { text: "Checks passed", severity: "success" };
+	}
+	if (state.policyDecision === "conditional_pass") {
+		return { text: "Passed with notes", severity: "warning" };
+	}
+	switch (state.phase) {
+		case "execute":
+			return { text: "Implementing changes", severity: "accent" };
+		case "evaluate":
+			return { text: "Running checks", severity: "accent" };
+		case "adversary":
+			return { text: "Review gate", severity: "accent" };
+		case "merge":
+			return { text: "Ready to finish", severity: "accent" };
+		default:
+			return { text: "Planning", severity: "muted" };
+	}
+}
+
 export class HarnessUiStateStore {
 	private lastEntriesLen = -1;
 	private cachedState: HarnessUiState = {

package/.pi/prompts/harness-auto.md

@@ -1,6 +1,6 @@
 ---
 description: Full strict harness pipeline with locked governance decisions.
-argument-hint: "\"<task>\" [--quick] [--risk low|med|high] [--budget <amount>]"
+argument-hint: "\"<task>\" [--quick] [--risk low|med|high]"
 ---
 
 # harness-auto
@@ -10,7 +10,7 @@ Pipeline orchestrator — one session, sequential phase handoffs. Invoke **harne
 ## Step 0 — Parse arguments
 
 - required task (quoted or first token)
-- optional: `--quick`, `--risk`, `--budget`
+- optional: `--quick`, `--risk` (`--budget` reserved/no-op)
 
 If task missing: