ultimate-pi 0.15.0 → 0.16.0

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

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:
 

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

@@ -1,13 +1,13 @@
 ---
 description: PM-grade harness plan — scouts, implementation research, ExecutionPlan, DAG validation, selective Review Gate debate, approval.
-argument-hint: "\"<task>\" [--risk low|med|high] [--budget <amount>] [--quick]"
+argument-hint: "\"<task>\" [--risk low|med|high] [--quick]"
 ---
 
 # harness-plan
 
 You are the **planning PM** for this harness run. Produce an execution baseline (`plan-packet.yaml` + `plan-review.md`), not strategy theater. Parent owns `ask_user`, `approve_plan`, `create_plan`, debate bus commands, and YAML writes under `.pi/harness/runs/<run_id>/`.
 
-Never `write`/`edit` the final canonical packet except via **`write_harness_yaml`** for run artifacts and **`create_plan`** after approval. Do not paste JSON into `.yaml` files — subagents emit JSON; you convert via `write_harness_yaml`.
+Subagents persist artifacts via scoped **`submit_*`** tools (deterministic YAML under the run dir). Parent uses **`harness_artifact_ready`** to gate phases (no JSON parsing). Parent merges still use **`write_harness_yaml`** for `research-brief.yaml`, `plan-packet.yaml` shell, and integrator patches only.
 
 ## Allowed subagents
 
@@ -33,12 +33,12 @@ Read **harness-debate-plan** skill before Review Gate rounds.
 2. Each `subagent` call blocks until subprocesses finish — batch parallel scouts in one `tasks` array.
 3. Do **not** set `timeoutMs` unless the user explicitly requests a cap — subagents run until natural completion (optional backstop: `PI_SUBAGENT_TIMEOUT_MS`).
 4. No harness subagent spawn cap — run the full scout + research + debate pipeline without skipping lanes for budget.
-5. Compact task text: embed `HarnessSpawnContext` JSON + lane-specific instructions only.
+5. Compact task text: embed spawn context + lane instructions. Prefer `HarnessSpawnContext={"run_id":"…","plan_packet_path":"…",…}` or a JSON object with `"HarnessSpawnContext":{…}` — both parse; `run_id` is required so subprocess submit tools get `HARNESS_RUN_ID`.
 
 ## Step 0 — Parse `$ARGUMENTS`
 
 - task (required)
-- `--risk low|med|high`, `--budget`, `--quick`
+- `--risk low|med|high`, `--quick` (`--budget` is reserved/no-op; token budgets are telemetry-only unless `HARNESS_BUDGET_ENFORCE=1`)
 
 `--quick` skips **scout-semantic** and post-run adversary only — **never** skip graphify, structure, decompose, hypothesis, **Phase 3.5 implementation research**, stack research, execution plan, DAG validation, or **Review Gate debate**.
 
@@ -64,9 +64,11 @@ Do **not** run `ccc index` or `ccc search --refresh`. The harness runs increment
 
 Add `harness/planning/scout-semantic` to `tasks` unless `--quick`. Require graphify + structure success. Semantic lane uses `ccc search` only (see `scout-semantic` agent).
 
+After scouts: `harness_artifact_ready({ paths: ["artifacts/scout-graphify.yaml", "artifacts/scout-structure.yaml", ...] })`.
+
 ## Phase 2 & 3 — Decompose + hypothesis (parallel)
 
-One `subagent` call with `tasks` for `harness/planning/decompose` and `harness/planning/hypothesis`. Parse `PlanDecompositionBrief` and `PlanHypothesisBrief` from outputs. Persist with `write_harness_yaml` → `artifacts/decomposition.yaml` and `artifacts/hypothesis.yaml`.
+One `subagent` call with `tasks` for `harness/planning/decompose` and `harness/planning/hypothesis` (include scout YAML paths in task text). Gate with `harness_artifact_ready` on `artifacts/decomposition.yaml` and `artifacts/hypothesis.yaml`.
 
 Decompose **prior_art** is **internal only** (from scouts). External prior art arrives in Phase 3.5.
 
@@ -84,8 +86,8 @@ Decompose **prior_art** is **internal only** (from scouts). External prior art a
 }
 ```
 
-- `write_harness_yaml` → `artifacts/implementation-research.yaml` and `artifacts/stack.yaml`.
-- Merge both into `research-brief.yaml` (`implementation:` + `stack:`).
+- Subagents write via `submit_implementation_research` / `submit_stack_brief`; gate with `harness_artifact_ready` on both paths.
+- Merge both into `research-brief.yaml` (`implementation:` + `stack:`) via parent `write_harness_yaml`.
 - **Partial failure:** if one lane fails, re-spawn that lane once; if still failing set `plan_status: partial` and `human_required` via `ask_user`. Do not proceed to Phase 4b without both artifacts or explicit human waiver.
 - **Web dedup:** implementation owns patterns/repos; stack owns libraries/versions — no overlapping queries.
 

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

@@ -1,6 +1,6 @@
 ---
 description: Execute only against an approved PlanPacket with strict phase gates.
-argument-hint: "[--budget <amount>]"
+argument-hint: ""
 ---
 
 # harness-run
@@ -9,7 +9,7 @@ Orchestrator only — spawn `harness/executor`. Do **not** implement inline.
 
 ## Step 0 — Parse arguments
 
-- optional: `--budget <amount>`
+- `--budget` is reserved/no-op (telemetry-only budgets by default)
 - Do **not** use `--plan` on happy path — load from `[HarnessActivePlan]` / `plan_packet_path`.
 
 If plan not ready:

package/.pi/scripts/harness-verify.mjs

@@ -37,6 +37,8 @@ const REQUIRED_ADRS = [
 	"0009-sentrux-rules-lifecycle.md",
 	"0031-harness-run-context.md",
 	"0032-harness-command-orchestration.md",
+	"0037-subagent-submit-tools.md",
+	"0038-budget-telemetry-only.md",
 ];
 
 const REQUIRED_EXTENSIONS = [

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [v0.16.0] — 2026-05-19
+
+### ✨ Features
+
+- add submit pipeline and planning/debate updates
+
+### 🔧 Chores
+
+- refresh graph artifacts after harness updates
+
 ## [v0.15.0] — 2026-05-19
 
 ### ✨ Features

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.15.0",
+	"version": "0.16.0",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -84,7 +84,7 @@
 		"format": "biome format --write",
 		"format:check": "biome format",
 		"prepare": "lefthook install",
-		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/harness-subagent-precheck.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && node .pi/harness/evals/smoke/smoke-harness-plan.mjs --fixture && npx -y tsx --test test/harness-vcc-settings.test.ts test/harness-live-widget-status.test.ts test/harness-plan-phase-policy.test.mjs test/harness-subagent-policy.test.mjs test/harness-spawn-budget.test.mjs test/harness-turn-routing.test.mjs test/plan-approval-format.test.mjs test/plan-approval-dialog.test.mjs test/plan-approval-sync.test.mjs test/plan-create-plan.test.mjs test/plan-review-format.test.mjs test/debate-plan-phase.test.mjs test/plan-debate-eligibility.test.mjs test/plan-messenger-gate.test.mjs test/plan-debate-lane-apply.test.mjs",
+		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/harness-subagent-precheck.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && node .pi/harness/evals/smoke/smoke-harness-plan.mjs --fixture && npx -y tsx --test test/harness-vcc-settings.test.ts test/harness-live-widget-status.test.ts test/harness-plan-phase-policy.test.mjs test/harness-subagent-policy.test.mjs test/harness-spawn-budget.test.mjs test/harness-spawn-parse.test.mjs test/harness-schema-validate.test.mjs test/harness-turn-routing.test.mjs test/harness-budget-enforce.test.mjs test/harness-submit-policy.test.mjs test/plan-approval-format.test.mjs test/plan-approval-dialog.test.mjs test/plan-approval-sync.test.mjs test/plan-create-plan.test.mjs test/plan-review-format.test.mjs test/debate-plan-phase.test.mjs test/plan-debate-eligibility.test.mjs test/plan-messenger-gate.test.mjs test/plan-debate-lane-apply.test.mjs",
 		"test:vcc": "npx -y tsx --test vendor/pi-vcc/tests/*.test.ts",
 		"harness:sentrux-bootstrap": "node .pi/scripts/harness-sentrux-bootstrap.mjs",
 		"harness:sentrux-sync": "node .pi/scripts/sentrux-rules-sync.mjs --force",
@@ -103,6 +103,8 @@
 	},
 	"dependencies": {
 		"@posthog/pi": "latest",
+		"ajv": "^8.17.1",
+		"ajv-formats": "^3.0.1",
 		"croner": "^9.0.0",
 		"jimp": "^1.6.1",
 		"nanoid": "^5.1.5",

package/vendor/pi-subagents/src/subagents.ts

@@ -42,6 +42,13 @@ export interface SpawnAuthForward {
 
 export interface HarnessSubagentsOptions {
 	packageRoot?: string;
+	/** Absolute path to harness-subagent-submit.ts for subprocess-only extension loading (Option A). */
+	harnessSubprocessExtensionPath?: string;
+	/** Extra env vars per subprocess (e.g. HARNESS_RUN_ID, HARNESS_RUN_DIR). */
+	resolveSubprocessEnv?: (
+		task: string,
+		agent: AgentConfig,
+	) => Record<string, string> | undefined;
 	defaultAgentScope?: AgentScope;
 	defaultConfirmProjectAgents?: boolean;
 	beforeExecute?: (
@@ -388,8 +395,11 @@ function terminateProcess(proc: ReturnType<typeof spawn>) {
 
 type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
-function buildSpawnEnv(packageRoot?: string): NodeJS.ProcessEnv {
-	const env = { ...process.env };
+function buildSpawnEnv(
+	packageRoot?: string,
+	extra?: Record<string, string>,
+): NodeJS.ProcessEnv {
+	const env = { ...process.env, ...extra };
 	env.PI_HARNESS_SUBPROCESS = "1";
 	if (packageRoot) {
 		env.UP_PKG = packageRoot;
@@ -411,6 +421,7 @@ async function runSingleAgent(
 	makeDetails: (results: SingleResult[]) => SubagentDetails,
 	packageRoot?: string,
 	spawnAuth?: SpawnAuthForward,
+	subagentsOptions?: HarnessSubagentsOptions,
 ): Promise<SingleResult> {
 	const agent = agents.find((a) => a.name === agentName);
 
@@ -434,8 +445,15 @@ async function runSingleAgent(
 	else if (spawnAuth) args.push("--model", spawnAuth.modelRef);
 	if (spawnAuth?.apiKey) args.push("--api-key", spawnAuth.apiKey);
 	if (agent.thinking) args.push("--thinking", agent.thinking);
+	const harnessExt =
+		agent.extensionsOff &&
+		agent.name.startsWith("harness/") &&
+		subagentsOptions?.harnessSubprocessExtensionPath;
 	if (agent.extensionsOff) {
 		args.push("--no-extensions");
+		if (harnessExt) {
+			args.push("-e", harnessExt);
+		}
 		if (agent.skillsOff) args.push("--no-skills");
 	}
 	if (agent.tools && agent.tools.length > 0) {
@@ -443,7 +461,11 @@ async function runSingleAgent(
 	} else if (agent.extensionsOff) {
 		args.push("--no-tools");
 	}
-	const spawnEnv = buildSpawnEnv(packageRoot);
+	const extraEnv = subagentsOptions?.resolveSubprocessEnv?.(task, agent);
+	const spawnEnv = buildSpawnEnv(packageRoot, {
+		...extraEnv,
+		HARNESS_AGENT_ID: agent.name,
+	});
 
 	let tmpPromptDir: string | null = null;
 	let tmpPromptPath: string | null = null;
@@ -856,6 +878,7 @@ export function createSubagentsExtension(
 							makeDetails("chain"),
 							packageRoot,
 							await resolveSpawnAuth(step.agent),
+							options,
 						);
 						results.push(result);
 
@@ -950,6 +973,7 @@ export function createSubagentsExtension(
 							makeDetails("parallel"),
 							packageRoot,
 							await resolveSpawnAuth(t.agent),
+							options,
 						);
 						allResults[index] = result;
 						doneCount += 1;
@@ -987,6 +1011,7 @@ export function createSubagentsExtension(
 							makeDetails("parallel"),
 							packageRoot,
 							await resolveSpawnAuth(aggregator.agent),
+							options,
 						);
 					}
 
@@ -1038,6 +1063,7 @@ export function createSubagentsExtension(
 						makeDetails("single"),
 						packageRoot,
 						await resolveSpawnAuth(params.agent),
+						options,
 					);
 					const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
 					if (isError) {