ultimate-pi 0.17.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,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 },
 );
@@ -118,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/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 };
+}

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

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

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",
@@ -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/");
 }
@@ -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" };
 }
 

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

@@ -6,8 +6,11 @@ import {
 	type AgentConfig,
 	agentAllowsMutatingTools,
 } from "../../../vendor/pi-subagents/src/agents.js";
-import type { HarnessPhase } from "../../lib/harness-run-context.js";
-import { inferHarnessPhase } from "../../lib/harness-run-context.js";
+import {
+	type HarnessPhase,
+	inferHarnessPhase,
+} from "../../lib/harness-run-context.js";
+import { validateHarnessSpawnTopology } from "./harness-spawn-topology.js";
 import { classifyHarnessAgent } from "./harness-subagent-policy.js";
 
 export interface SubagentTaskRef {
@@ -19,6 +22,11 @@ export interface PrecheckResult {
 	message?: string;
 }
 
+export interface PrecheckOptions {
+	projectRoot?: string;
+	runId?: string | null;
+}
+
 function collectAgents(params: {
 	agent?: string;
 	tasks?: SubagentTaskRef[];
@@ -40,7 +48,7 @@ function resolveAgent(
 	return agents.find((a) => a.name === name);
 }
 
-export function precheckHarnessSubagentSpawn(
+export async function precheckHarnessSubagentSpawn(
 	params: {
 		agent?: string;
 		tasks?: SubagentTaskRef[];
@@ -49,7 +57,8 @@ export function precheckHarnessSubagentSpawn(
 	},
 	agents: AgentConfig[],
 	phase: HarnessPhase,
-): PrecheckResult {
+	opts?: PrecheckOptions,
+): Promise<PrecheckResult> {
 	const names = collectAgents(params);
 	const mutating = names.filter((n) => {
 		const cfg = resolveAgent(agents, n);
@@ -67,7 +76,17 @@ export function precheckHarnessSubagentSpawn(
 		};
 	}
 
-	if ((params.tasks?.length ?? 0) > 1 && mutating.length > 1) {
+	const parallelEvalAdversary =
+		(params.tasks?.length ?? 0) === 2 &&
+		params.tasks?.some((t) => t.agent === "harness/evaluator") &&
+		params.tasks?.some((t) => t.agent === "harness/adversary") &&
+		phase === "evaluate";
+
+	if (
+		(params.tasks?.length ?? 0) > 1 &&
+		mutating.length > 1 &&
+		!parallelEvalAdversary
+	) {
 		return {
 			ok: false,
 			message:
@@ -76,12 +95,19 @@ export function precheckHarnessSubagentSpawn(
 		};
 	}
 
+	const parallelTaskCount = params.tasks?.length ?? (params.agent ? 1 : 0);
+	const topology = await validateHarnessSpawnTopology(names, phase, {
+		parallelTaskCount,
+		projectRoot: opts?.projectRoot,
+		runId: opts?.runId,
+	});
+	if (!topology.ok) {
+		return topology;
+	}
+
 	for (const name of names) {
 		if (!name.startsWith("harness/")) continue;
-		const kind = classifyHarnessAgent(name);
-		if (kind === "planner" && phase !== "plan") {
-			// allowed — planning agents can run in plan only ideally
-		}
+		classifyHarnessAgent(name);
 	}
 
 	return { ok: true };