ultimate-pi 0.16.0 → 0.18.0

package/.pi/extensions/harness-subagent-submit.ts

@@ -6,10 +6,14 @@
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
+import { resolveGuardedRunDir } from "../lib/harness-subagent-submit-path.js";
 import { claimExtensionLoad } from "./lib/extension-load-guard.js";
 import { getHarnessPackageRoot } from "./lib/harness-paths.js";
 import { evaluateHarnessSubagentToolCall } from "./lib/harness-subagent-policy.js";
-import { executeSubmitPipeline } from "./lib/harness-subagent-submit-pipeline.js";
+import {
+	executeSubmitPipeline,
+	loadSubmitDocument,
+} from "./lib/harness-subagent-submit-pipeline.js";
 import { SUBMIT_TOOL_SPECS } from "./lib/harness-subagent-submit-registry.js";
 
 // @ts-expect-error pi extensions run as ESM
@@ -17,9 +21,18 @@ const MODULE_URL = import.meta.url;
 
 const DocumentSchema = Type.Object(
 	{
-		document: Type.Record(Type.String(), Type.Unknown(), {
-			description: "Full artifact document matching the harness JSON schema",
-		}),
+		document: Type.Optional(
+			Type.Record(Type.String(), Type.Unknown(), {
+				description:
+					"Artifact fields (deprecated when source_path is set; ADR 0043)",
+			}),
+		),
+		source_path: Type.Optional(
+			Type.String({
+				description:
+					"Relative path under run dir, e.g. artifacts/.draft/decomposition.yaml",
+			}),
+		),
 	},
 	{ additionalProperties: false },
 );
@@ -58,30 +71,6 @@ export default function harnessSubagentSubmit(pi: ExtensionAPI) {
 	pi.on("tool_call", async (event) => {
 		if (!event.toolName.startsWith("submit_")) return undefined;
 		const subprocessOk = isSubprocessHarness();
-		// #region agent log
-		fetch("http://127.0.0.1:7928/ingest/a5d40896-34cb-4f12-97db-df7ada0b22f0", {
-			method: "POST",
-			headers: {
-				"Content-Type": "application/json",
-				"X-Debug-Session-Id": "2ca12b",
-			},
-			body: JSON.stringify({
-				sessionId: "2ca12b",
-				hypothesisId: "H2",
-				location: "harness-subagent-submit.ts:tool_call",
-				message: "submit tool_call gate",
-				data: {
-					toolName: event.toolName,
-					PI_HARNESS_SUBPROCESS: process.env.PI_HARNESS_SUBPROCESS,
-					HARNESS_RUN_ID: process.env.HARNESS_RUN_ID ?? null,
-					HARNESS_RUN_DIR: process.env.HARNESS_RUN_DIR ?? null,
-					HARNESS_AGENT_ID: process.env.HARNESS_AGENT_ID ?? null,
-					subprocessOk,
-				},
-				timestamp: Date.now(),
-			}),
-		}).catch(() => {});
-		// #endregion
 		if (!subprocessOk) {
 			return {
 				block: true,
@@ -141,21 +130,42 @@ export default function harnessSubagentSubmit(pi: ExtensionAPI) {
 						isError: true,
 					};
 				}
-				const document = (params as { document?: Record<string, unknown> })
-					.document;
-				if (!document || typeof document !== "object") {
+				const runResolved = await resolveGuardedRunDir({
+					projectRoot,
+					runId,
+					runDirEnv,
+				});
+				if (!runResolved.ok) {
 					return {
-						content: [{ type: "text", text: "document object is required" }],
+						content: [{ type: "text", text: runResolved.error }],
 						details: {},
 						isError: true,
 					};
 				}
+				const loaded = await loadSubmitDocument({
+					projectRoot,
+					runDir: runResolved.runDir,
+					document: (params as { document?: Record<string, unknown> }).document,
+					source_path: (params as { source_path?: string }).source_path,
+				});
+				if (!loaded.ok) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Validation failed:\n${loaded.validation_errors.join("\n")}`,
+							},
+						],
+						isError: true,
+						details: loaded,
+					};
+				}
 				const result = await executeSubmitPipeline({
 					projectRoot,
 					specsDir,
 					spec,
 					agentId,
-					document,
+					document: loaded.document,
 					runId,
 					runDirEnv,
 				});

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

@@ -127,6 +127,7 @@ function propsFromRun(
 ): Record<string, unknown> {
 	return {
 		harness_run_id: runId,
+		run_id: runId,
 		harness_plan_id: planId,
 		harness_phase: phase,
 		pi_session_id: distinctId,
@@ -134,6 +135,28 @@ function propsFromRun(
 	};
 }
 
+function normalizedRunId(
+	data: Record<string, unknown>,
+	trace: TraceState | null,
+	distinctId: string,
+): string {
+	const fromData = [
+		data.harness_run_id,
+		data.run_id,
+		data.runId,
+		data.debate_id,
+	];
+	for (const candidate of fromData) {
+		if (typeof candidate === "string" && candidate.trim().length > 0) {
+			return candidate;
+		}
+	}
+	if (typeof trace?.run_id === "string" && trace.run_id.length > 0) {
+		return trace.run_id;
+	}
+	return distinctId;
+}
+
 function mapCustomEntry(
 	customType: string,
 	data: Record<string, unknown>,
@@ -144,11 +167,9 @@ function mapCustomEntry(
 	event: HarnessPostHogEventName;
 	properties: Record<string, unknown>;
 } | null {
-	const runId =
-		(typeof data.run_id === "string" && data.run_id) ||
-		trace?.run_id ||
-		distinctId;
+	const runId = normalizedRunId(data, trace, distinctId);
 	const planId =
+		(typeof data.harness_plan_id === "string" && data.harness_plan_id) ||
 		(typeof data.plan_id === "string" && data.plan_id) ||
 		policy?.planId ||
 		trace?.plan_id ||
@@ -185,6 +206,7 @@ function mapCustomEntry(
 				event: "harness_debate_consensus",
 				properties: {
 					...base,
+					debate_id: String(data.debate_id ?? runId),
 					consensus_id:
 						typeof data.debate_id === "string" ? data.debate_id : runId,
 					outcome: String(kind),
@@ -195,6 +217,8 @@ function mapCustomEntry(
 			event: "harness_debate_round",
 			properties: {
 				...base,
+				debate_id: String(data.debate_id ?? runId),
+				round_index: Number(data.round_index ?? data.round ?? 0),
 				round: Number(data.round_index ?? data.round ?? 0),
 				outcome: String(kind ?? "round"),
 			},
@@ -206,6 +230,7 @@ function mapCustomEntry(
 			event: "harness_debate_consensus",
 			properties: {
 				...base,
+				debate_id: String(data.debate_id ?? runId),
 				consensus_id:
 					typeof data.consensus_id === "string"
 						? data.consensus_id

package/.pi/extensions/lib/debate-bus-core.ts

@@ -25,6 +25,7 @@ import {
 } from "./debate-bus-state.js";
 import {
 	type DebateProfile,
+	PLAN_BUDGET_FAST,
 	PLAN_BUDGET_LIGHT,
 	PLAN_BUDGET_STANDARD,
 } from "./plan-debate-eligibility.js";
@@ -113,15 +114,20 @@ export function capsForDebate(
 } {
 	if (isPlanDebateId(debateId)) {
 		const active = profile ?? getDebateState()?.debate_profile ?? "standard";
-		const budget = active === "light" ? PLAN_BUDGET_LIGHT : PLAN_BUDGET;
+		const budget =
+			active === "light"
+				? PLAN_BUDGET_LIGHT
+				: active === "fast"
+					? PLAN_BUDGET_FAST
+					: PLAN_BUDGET;
 		const caps = { name: "plan" as const, ...budget };
 		if (!isHarnessBudgetEnforceOn()) {
 			return {
 				...caps,
-				max_rounds: 999,
-				max_exchanges_per_round: 99,
-				round_token_cap: caps.round_token_cap * 100,
-				debate_global_cap: caps.debate_global_cap * 100,
+				max_rounds: caps.max_rounds,
+				max_exchanges_per_round: Math.max(caps.max_exchanges_per_round, 2),
+				round_token_cap: caps.round_token_cap * 2,
+				debate_global_cap: caps.debate_global_cap * 2,
 			};
 		}
 		return caps;
@@ -135,10 +141,10 @@ export function capsForDebate(
 	if (!isHarnessBudgetEnforceOn()) {
 		return {
 			...caps,
-			max_rounds: 999,
-			max_exchanges_per_round: 99,
-			round_token_cap: caps.round_token_cap * 100,
-			debate_global_cap: caps.debate_global_cap * 100,
+			max_rounds: caps.max_rounds,
+			max_exchanges_per_round: Math.max(caps.max_exchanges_per_round, 2),
+			round_token_cap: caps.round_token_cap * 2,
+			debate_global_cap: caps.debate_global_cap * 2,
 		};
 	}
 	return caps;

package/.pi/extensions/lib/harness-artifact-gate.ts

@@ -0,0 +1,182 @@
+/**
+ * Content-aware gates for harness_artifact_ready (existence + minimal validity).
+ */
+
+import { constants } from "node:fs";
+import { access, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { validateAgainstHarnessSchema } from "../../lib/harness-schema-validate.js";
+
+export interface ArtifactGateResult {
+	ok: boolean;
+	errors: string[];
+}
+
+const ARTIFACT_SCHEMA: Record<string, string> = {
+	"artifacts/decomposition.yaml": "plan-decomposition-brief.schema.json",
+	"artifacts/hypothesis.yaml": "plan-hypothesis-brief.schema.json",
+	"artifacts/implementation-research.yaml":
+		"plan-implementation-research-brief.schema.json",
+	"artifacts/stack.yaml": "plan-stack-brief.schema.json",
+	"artifacts/planning-context.yaml": "plan-planning-context.schema.json",
+	"artifacts/scout-graphify.yaml": "plan-scout-findings.schema.json",
+	"artifacts/scout-structure.yaml": "plan-scout-findings.schema.json",
+	"artifacts/scout-semantic.yaml": "plan-scout-findings.schema.json",
+	"artifacts/eval-verdict.yaml": "eval-verdict.schema.json",
+	"artifacts/adversary-report.yaml": "adversary-report.schema.json",
+};
+
+const PREREQUISITE_ORDER: Record<string, string[]> = {
+	"artifacts/hypothesis.yaml": ["artifacts/decomposition.yaml"],
+	"artifacts/implementation-research.yaml": [
+		"artifacts/decomposition.yaml",
+		"artifacts/hypothesis.yaml",
+	],
+	"artifacts/stack.yaml": [
+		"artifacts/decomposition.yaml",
+		"artifacts/hypothesis.yaml",
+	],
+};
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function scoutStatusBad(doc: Record<string, unknown>): string | null {
+	const status = String(doc.status ?? "ok").toLowerCase();
+	if (status === "partial" || status === "failed" || status === "error") {
+		return `scout status is "${status}"`;
+	}
+	return null;
+}
+
+export async function validateHarnessArtifactFile(
+	runRoot: string,
+	relPath: string,
+	specsDir: string,
+): Promise<ArtifactGateResult> {
+	const normalized = relPath.replace(/\\/g, "/");
+	const abs = join(runRoot, normalized);
+	const errors: string[] = [];
+
+	if (!(await fileExists(abs))) {
+		return { ok: false, errors: [`missing file: ${normalized}`] };
+	}
+
+	const st = await stat(abs);
+	if (st.size < 8) {
+		errors.push(`${normalized}: file too small (${st.size} bytes)`);
+	}
+
+	let doc: Record<string, unknown> | null = null;
+	try {
+		const raw = await readFile(abs, "utf-8");
+		if (!raw.trim()) {
+			errors.push(`${normalized}: empty file`);
+		} else {
+			doc = parseYaml(raw) as Record<string, unknown>;
+			if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+				errors.push(`${normalized}: root must be a YAML object`);
+			}
+		}
+	} catch (e) {
+		errors.push(
+			`${normalized}: invalid YAML (${e instanceof Error ? e.message : String(e)})`,
+		);
+	}
+
+	const schemaFile = ARTIFACT_SCHEMA[normalized];
+	if (doc && schemaFile) {
+		const validation = await validateAgainstHarnessSchema(
+			specsDir,
+			schemaFile,
+			doc,
+		);
+		if (!validation.ok) {
+			errors.push(
+				`${normalized}: schema validation failed — ${validation.errors.join("; ")}`,
+			);
+		}
+	}
+
+	if (doc && normalized.startsWith("artifacts/scout-")) {
+		const scoutErr = scoutStatusBad(doc);
+		if (scoutErr) {
+			errors.push(`${normalized}: ${scoutErr}`);
+		}
+	}
+
+	if (doc && normalized === "artifacts/planning-context.yaml") {
+		const scoutErr = scoutStatusBad(doc);
+		if (scoutErr) {
+			errors.push(`${normalized}: ${scoutErr}`);
+		}
+		const coverage = doc.coverage as Record<string, unknown> | undefined;
+		if (coverage && typeof coverage === "object") {
+			for (const lane of ["architecture", "structure"] as const) {
+				const laneDoc = coverage[lane] as Record<string, unknown> | undefined;
+				const laneStatus = String(laneDoc?.status ?? "").toLowerCase();
+				if (laneStatus !== "ok" && laneStatus !== "partial") {
+					errors.push(
+						`${normalized}: coverage.${lane}.status must be ok or partial (got "${laneStatus || "missing"}")`,
+					);
+				}
+			}
+		}
+	}
+
+	const prereqs = PREREQUISITE_ORDER[normalized] ?? [];
+	for (const prereq of prereqs) {
+		if (!(await fileExists(join(runRoot, prereq)))) {
+			errors.push(`${normalized}: prerequisite missing (${prereq})`);
+		}
+	}
+
+	return { ok: errors.length === 0, errors };
+}
+
+export async function validateHarnessArtifactPaths(
+	runRoot: string,
+	paths: string[],
+	specsDir: string,
+): Promise<{
+	ok: boolean;
+	present: string[];
+	missing: string[];
+	errors: string[];
+}> {
+	const present: string[] = [];
+	const missing: string[] = [];
+	const errors: string[] = [];
+
+	for (const rel of paths) {
+		const normalized = rel.replace(/\\/g, "/");
+		const gate = await validateHarnessArtifactFile(
+			runRoot,
+			normalized,
+			specsDir,
+		);
+		if (gate.errors.some((e) => e.startsWith("missing file"))) {
+			missing.push(normalized);
+			continue;
+		}
+		if (!gate.ok) {
+			errors.push(...gate.errors);
+			continue;
+		}
+		present.push(normalized);
+	}
+
+	return {
+		ok: missing.length === 0 && errors.length === 0,
+		present,
+		missing,
+		errors,
+	};
+}

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

@@ -6,6 +6,7 @@
  */
 
 import { PostHog } from "posthog-node";
+import { getPostHogClientOptions } from "./posthog-client.js";
 
 export type HarnessPostHogEventName =
 	| "harness_run_started"
@@ -48,9 +49,7 @@ function getClient(): PostHog | null {
 	if (client) return client;
 	const apiKey = process.env.POSTHOG_API_KEY?.trim();
 	if (!apiKey) return null;
-	client = new PostHog(apiKey, {
-		host: process.env.POSTHOG_HOST?.trim() || "https://us.i.posthog.com",
-	});
+	client = new PostHog(apiKey, getPostHogClientOptions());
 	return client;
 }
 
@@ -109,6 +108,11 @@ export function captureHarnessEvent(
 
 export async function shutdownHarnessPostHog(): Promise<void> {
 	if (!client) return;
-	await client.shutdown();
-	client = null;
+	try {
+		await client.shutdown();
+	} catch {
+		// Best-effort telemetry — avoid noisy flush errors when offline / WSL DNS broken.
+	} finally {
+		client = null;
+	}
 }

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

@@ -0,0 +1,188 @@
+/**
+ * Harness subagent spawn topology rules (no vendor imports — testable in isolation).
+ */
+
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import type { HarnessPhase } from "../../lib/harness-run-context.js";
+
+export interface SpawnTopologyResult {
+	ok: boolean;
+	message?: string;
+}
+
+const DECOMPOSE_AGENT = "harness/planning/decompose";
+const HYPOTHESIS_AGENT = "harness/planning/hypothesis";
+
+const DEBATE_LANE_AGENTS = new Set([
+	"harness/planning/hypothesis-validator",
+	"harness/planning/plan-evaluator",
+	"harness/planning/plan-adversary",
+	"harness/planning/sprint-contract-auditor",
+	"harness/planning/review-integrator",
+]);
+
+/** @deprecated Legacy tool-tied scouts — prefer parent tools + planning-context.yaml (ADR 0041). */
+const LEGACY_SCOUT_AGENTS = new Set([
+	"harness/planning/scout-graphify",
+	"harness/planning/scout-structure",
+	"harness/planning/scout-semantic",
+]);
+
+const PLANNING_CONTEXT_AGENT = "harness/planning/planning-context";
+
+const PARALLEL_RESEARCH_AGENTS = new Set([
+	"harness/planning/implementation-researcher",
+	"harness/planning/stack-researcher",
+]);
+
+function countInSet(names: string[], allowed: Set<string>): number {
+	return names.filter((n) => allowed.has(n)).length;
+}
+
+function isReconnaissanceAgent(name: string): boolean {
+	return LEGACY_SCOUT_AGENTS.has(name) || name === PLANNING_CONTEXT_AGENT;
+}
+
+async function decompositionReady(
+	projectRoot: string,
+	runId: string,
+): Promise<boolean> {
+	const path = join(
+		projectRoot,
+		".pi",
+		"harness",
+		"runs",
+		runId,
+		"artifacts",
+		"decomposition.yaml",
+	);
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function validateHarnessSpawnTopology(
+	names: string[],
+	phase: HarnessPhase,
+	opts?: {
+		parallelTaskCount?: number;
+		projectRoot?: string;
+		runId?: string | null;
+	},
+): Promise<SpawnTopologyResult> {
+	const taskCount =
+		opts?.parallelTaskCount ?? (names.length > 1 ? names.length : 1);
+
+	if (taskCount > 1) {
+		const hasDecompose = names.includes(DECOMPOSE_AGENT);
+		const hasHypothesis = names.includes(HYPOTHESIS_AGENT);
+		if (hasDecompose && hasHypothesis) {
+			return {
+				ok: false,
+				message:
+					"Cannot spawn decompose and hypothesis in the same parallel batch. " +
+					"Gate artifacts/decomposition.yaml, then spawn hypothesis sequentially.",
+			};
+		}
+
+		const debateCount = countInSet(names, DEBATE_LANE_AGENTS);
+		const debateNames = names.filter((n) => DEBATE_LANE_AGENTS.has(n));
+		const parallelProbePair =
+			debateCount === 2 &&
+			debateNames.includes("harness/planning/plan-evaluator") &&
+			debateNames.includes("harness/planning/plan-adversary");
+		if (debateCount > 1 && !parallelProbePair) {
+			return {
+				ok: false,
+				message: `Review Gate: spawn one debate lane agent per subagent call (got ${debateCount}: ${debateNames.join(", ")}). Exception: plan-evaluator ∥ plan-adversary for parallel_probes.`,
+			};
+		}
+
+		const legacyScouts = countInSet(names, LEGACY_SCOUT_AGENTS);
+		const planningContext = names.filter(
+			(n) => n === PLANNING_CONTEXT_AGENT,
+		).length;
+		const research = countInSet(names, PARALLEL_RESEARCH_AGENTS);
+		const recon = legacyScouts + planningContext;
+
+		if (legacyScouts > 0 && planningContext > 0) {
+			return {
+				ok: false,
+				message:
+					"Do not mix legacy scout-* subagents with planning-context in one batch. " +
+					"Prefer parent tool use + planning-context.yaml, or a single planning-context subagent.",
+			};
+		}
+		if (legacyScouts > 3) {
+			return {
+				ok: false,
+				message:
+					"At most 3 legacy planning scouts per parallel batch (deprecated — use planning-context).",
+			};
+		}
+		if (planningContext > 1) {
+			return {
+				ok: false,
+				message: "At most one planning-context subagent per parallel batch.",
+			};
+		}
+
+		const otherHarness = names.filter(
+			(n) =>
+				n.startsWith("harness/") &&
+				!isReconnaissanceAgent(n) &&
+				!PARALLEL_RESEARCH_AGENTS.has(n) &&
+				!DEBATE_LANE_AGENTS.has(n) &&
+				n !== DECOMPOSE_AGENT &&
+				n !== HYPOTHESIS_AGENT,
+		);
+		if (
+			(recon > 0 && (research > 0 || otherHarness.length > 0)) ||
+			(research > 0 && otherHarness.length > 0)
+		) {
+			return {
+				ok: false,
+				message:
+					"Parallel batches may include only one independent group: " +
+					"research (≤2 lanes), optional legacy scouts (≤3), optional single planning-context, " +
+					"or a single sequential lane agent.",
+			};
+		}
+		if (research > 2) {
+			return {
+				ok: false,
+				message:
+					"At most 2 research lanes (implementation-researcher, stack-researcher) per parallel batch.",
+			};
+		}
+	}
+
+	if (names.includes(HYPOTHESIS_AGENT) && opts?.projectRoot && opts?.runId) {
+		const ready = await decompositionReady(opts.projectRoot, opts.runId);
+		if (!ready) {
+			return {
+				ok: false,
+				message:
+					"Cannot spawn hypothesis before artifacts/decomposition.yaml exists. " +
+					"Complete decompose and harness_artifact_ready on decomposition first.",
+			};
+		}
+	}
+
+	if (phase === "plan") {
+		const mutating = names.filter((n) => n.startsWith("harness/executor"));
+		if (mutating.length > 0) {
+			return {
+				ok: false,
+				message: `Plan phase: cannot spawn mutating subagents (${mutating.join(", ")}).`,
+			};
+		}
+	}
+
+	return { ok: true };
+}