ultimate-pi 0.17.0 → 0.18.1

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 { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import { resolveGuardedRunDir } from "../lib/harness-subagent-submit-path.js";
+import { claimHarnessGovernanceLoad } 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,10 +21,18 @@ const MODULE_URL = import.meta.url;
 
 const DocumentSchema = Type.Object(
 	{
-		document: Type.Record(Type.String(), Type.Unknown(), {
-			description:
-				"Plan artifact fields (validated via plan-*.schema.json, persisted as canonical YAML on disk)",
-		}),
+		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 },
 );
@@ -48,7 +60,8 @@ function isSubprocessHarness(): boolean {
 }
 
 export default function harnessSubagentSubmit(pi: ExtensionAPI) {
-	if (!claimExtensionLoad("harness-subagent-submit", MODULE_URL)) return;
+	if (!claimHarnessGovernanceLoad("harness-subagent-submit", MODULE_URL))
+		return;
 	// Option A: only load submit tools in subprocess (`-e` bundle), not parent discovery.
 	if (process.env.PI_HARNESS_SUBPROCESS !== "1") {
 		return;
@@ -118,21 +131,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-subagents.ts

@@ -6,13 +6,13 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import { claimHarnessGovernanceLoad } from "./lib/extension-load-guard.js";
 
 // @ts-expect-error pi extensions run as ESM
 const MODULE_URL = import.meta.url;
 
 async function loadHarnessSubagents(): Promise<(pi: ExtensionAPI) => void> {
-	if (!claimExtensionLoad("harness-subagents", MODULE_URL)) {
+	if (!claimHarnessGovernanceLoad("harness-subagents", MODULE_URL)) {
 		return () => {};
 	}
 	const { getHarnessPackageRoot } = await import("./lib/harness-paths.js");

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

@@ -9,6 +9,7 @@
 
 import { createHash } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isHarnessProjectEnabled } from "../lib/harness-project-config.js";
 import {
 	captureHarnessEvent,
 	type HarnessPostHogEventName,
@@ -338,6 +339,7 @@ function mapCustomEntry(
 }
 
 export default function harnessTelemetry(pi: ExtensionAPI) {
+	if (!isHarnessProjectEnabled()) return;
 	const flushedHashes = new Set<string>();
 	let lastPolicyPhase: HarnessPhase | null = null;
 

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

@@ -4,7 +4,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import { claimHarnessGovernanceLoad } from "./lib/extension-load-guard.js";
 import {
 	harnessWebContextLine,
 	readTextExcerpt,
@@ -98,7 +98,7 @@ function sessionCwd(ctx: { cwd?: string }): string {
 }
 
 export default function harnessWebTools(pi: ExtensionAPI) {
-	if (!claimExtensionLoad("harness-web-tools", MODULE_URL)) return;
+	if (!claimHarnessGovernanceLoad("harness-web-tools", MODULE_URL)) return;
 	pi.on("before_agent_start", async (event) => {
 		return {
 			systemPrompt: `${event.systemPrompt}\n\n${harnessWebContextLine()}`,

package/.pi/extensions/lib/extension-load-guard.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isHarnessProjectEnabled } from "../../lib/harness-project-config.js";
 
 const LOAD_GUARD_KEY = Symbol.for("ultimate-pi.extension-load-guard");
 
@@ -37,3 +38,12 @@ export function claimExtensionLoad(key: string, moduleUrl: string): boolean {
 	registry.add(key);
 	return true;
 }
+
+/** Skip duplicate loads and skip all governance extensions when harness is disabled. */
+export function claimHarnessGovernanceLoad(
+	key: string,
+	moduleUrl: string,
+): boolean {
+	if (!isHarnessProjectEnabled()) return false;
+	return claimExtensionLoad(key, moduleUrl);
+}

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

@@ -0,0 +1,172 @@
+/**
+ * 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/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 artifactStatusBad(doc: Record<string, unknown>): string | null {
+	const status = String(doc.status ?? "ok").toLowerCase();
+	if (status === "partial" || status === "failed" || status === "error") {
+		return `artifact 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 === "artifacts/planning-context.yaml") {
+		const statusErr = artifactStatusBad(doc);
+		if (statusErr) {
+			errors.push(`${normalized}: ${statusErr}`);
+		}
+		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,165 @@
+/**
+ * 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",
+]);
+
+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 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 planningContext = names.filter(
+			(n) => n === PLANNING_CONTEXT_AGENT,
+		).length;
+		const research = countInSet(names, PARALLEL_RESEARCH_AGENTS);
+		const recon = planningContext;
+
+		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 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/running/"));
+		if (mutating.length > 0) {
+			return {
+				ok: false,
+				message: `Plan phase: cannot spawn mutating subagents (${mutating.join(", ")}).`,
+			};
+		}
+	}
+
+	return { ok: true };
+}

package/.pi/extensions/lib/harness-subagent-auth.ts

@@ -51,8 +51,7 @@ const ROUTINE_PLANNING_AGENT_PATHS = new Set([
 	"harness/planning/review-integrator",
 	"harness/planning/hypothesis-validator",
 	"harness/planning/sprint-contract-auditor",
-	"harness/planning/scout-structure",
-	"harness/planning/scout-semantic",
+	"harness/planning/planning-context",
 	"harness/planning/decompose",
 	"harness/planning/hypothesis",
 	"harness/planning/stack-research",

package/.pi/extensions/lib/harness-subagent-policy.ts

@@ -2,6 +2,11 @@
  * Per-agent tool policy for harness/* subagents (defense in depth with frontmatter).
  */
 
+import {
+	evaluateContextModeMutation,
+	isMutatingBash,
+} from "../../lib/harness-context-mode-policy.js";
+import type { HarnessPhase } from "../../lib/harness-run-context.js";
 import {
 	isSubmitToolName,
 	SUBMIT_TOOLS_BY_AGENT,
@@ -40,21 +45,6 @@ const PLANNING_BASH_DENY_PATTERNS = [
 	/\buv\s+tool\s+install\b.*cocoindex/i,
 ];
 
-const BASH_MUTATION_PATTERNS = [
-	/\brm\s+-/i,
-	/\bmv\s+/i,
-	/\bcp\s+/i,
-	/\btouch\s+/i,
-	/\bmkdir\s+/i,
-	/\btee\s+/i,
-	/\bgit\s+(add|commit|push|reset|checkout|merge|rebase|cherry-pick|apply)\b/i,
-	/\bnpm\s+(install|uninstall|ci)\b/i,
-	/\bpnpm\s+(add|install|remove)\b/i,
-	/\byarn\s+(add|install|remove)\b/i,
-	/\bsed\s+-i\b/i,
-	/\bperl\s+-i\b/i,
-];
-
 const READ_ONLY_KINDS = new Set<HarnessAgentKind>([
 	"planner",
 	"evaluator",
@@ -76,13 +66,13 @@ export function classifyHarnessAgent(agentType: string): HarnessAgentKind {
 		return "planner";
 	}
 	switch (id) {
-		case "executor":
+		case "running/executor":
 			return "executor";
-		case "evaluator":
+		case "reviewing/evaluator":
 			return "evaluator";
-		case "adversary":
+		case "reviewing/adversary":
 			return "adversary";
-		case "tie-breaker":
+		case "reviewing/tie-breaker":
 			return "tie_breaker";
 		case "meta-optimizer":
 			return "meta";
@@ -95,10 +85,6 @@ export function classifyHarnessAgent(agentType: string): HarnessAgentKind {
 	}
 }
 
-function isMutatingBash(command: string): boolean {
-	return BASH_MUTATION_PATTERNS.some((pattern) => pattern.test(command));
-}
-
 export function isHarnessPackageAgent(agentType: string): boolean {
 	return agentType.startsWith("harness/");
 }
@@ -141,7 +127,7 @@ export function evaluateHarnessSubagentToolCall(
 				return {
 					action: "block",
 					reason:
-						"submit_human_required is not available for harness/executor.",
+						"submit_human_required is not available for harness/running/executor.",
 				};
 			}
 			return { action: "allow" };
@@ -207,6 +193,24 @@ export function evaluateHarnessSubagentToolCall(
 		}
 	}
 
+	const ctxPhase =
+		(harnessSubagentPhaseHint(agentType) as HarnessPhase | null) ?? "plan";
+	const ctxDecision = evaluateContextModeMutation(
+		toolName,
+		input ?? {},
+		ctxPhase,
+		{ aborted: false, readOnlyAgent: true },
+	);
+	if (ctxDecision.blocked) {
+		return {
+			action: "block",
+			reason: ctxDecision.reason.replace(
+				/^policy-gate:/,
+				"harness-subagent-policy:",
+			),
+		};
+	}
+
 	return { action: "allow" };
 }