ultimate-pi 0.17.0 → 0.18.1

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,13 +57,14 @@ 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);
 		return cfg
 			? agentAllowsMutatingTools(cfg)
-			: n.startsWith("harness/executor");
+			: n.startsWith("harness/running/");
 	});
 
 	if (phase === "plan" && mutating.length > 0) {
@@ -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/reviewing/evaluator") &&
+		params.tasks?.some((t) => t.agent === "harness/reviewing/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 };

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

@@ -2,8 +2,8 @@
  * Shared write pipeline for harness subagent submit tools.
  */
 
-import { mkdir } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
 import { validateAgainstHarnessSchema } from "../../lib/harness-schema-validate.js";
 import { resolveGuardedRunDir } from "../../lib/harness-subagent-submit-path.js";
 import { writeYamlFile } from "../../lib/harness-yaml.js";
@@ -24,6 +24,54 @@ export interface SubmitPipelineResult {
 	human_required?: boolean;
 }
 
+export async function loadSubmitDocument(opts: {
+	projectRoot: string;
+	runDir: string;
+	document?: Record<string, unknown>;
+	source_path?: string;
+}): Promise<
+	| { ok: true; document: Record<string, unknown> }
+	| { ok: false; validation_errors: string[] }
+> {
+	if (opts.document && typeof opts.document === "object") {
+		return { ok: true, document: opts.document };
+	}
+	const rel = opts.source_path?.trim();
+	if (!rel) {
+		return {
+			ok: false,
+			validation_errors: ["submit_* requires document or source_path"],
+		};
+	}
+	const abs = resolve(opts.runDir, rel.replace(/^\//, ""));
+	if (!abs.startsWith(resolve(opts.runDir))) {
+		return {
+			ok: false,
+			validation_errors: [
+				"source_path must stay under the active run directory",
+			],
+		};
+	}
+	try {
+		const raw = await readFile(abs, "utf-8");
+		const { parse } = await import("yaml");
+		const doc = parse(raw) as Record<string, unknown>;
+		if (!doc || typeof doc !== "object") {
+			return {
+				ok: false,
+				validation_errors: ["source_path did not parse to an object"],
+			};
+		}
+		return { ok: true, document: doc };
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		return {
+			ok: false,
+			validation_errors: [`source_path read failed: ${msg}`],
+		};
+	}
+}
+
 export async function executeSubmitPipeline(opts: {
 	projectRoot: string;
 	specsDir: string;
@@ -56,6 +104,22 @@ export async function executeSubmitPipeline(opts: {
 	await mkdir(dirname(absPath), { recursive: true });
 	await writeYamlFile(absPath, opts.document);
 
+	if (opts.spec.toolName === "submit_executor_handoff") {
+		const rollback = opts.document.rollback_refs;
+		if (rollback && typeof rollback === "object" && !Array.isArray(rollback)) {
+			const rollbackPath = join(
+				runResolved.runDir,
+				"artifacts",
+				"executor-rollback.yaml",
+			);
+			await mkdir(dirname(rollbackPath), { recursive: true });
+			await writeYamlFile(rollbackPath, {
+				schema_version: "1.0.0",
+				...(rollback as Record<string, unknown>),
+			});
+		}
+	}
+
 	let laneResult: ApplyDebateLaneResult | undefined;
 	if (opts.spec.debateLane) {
 		laneResult = await applyDebateLaneFromDoc({

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

@@ -23,32 +23,23 @@ function roundPath(prefix: string, doc: Record<string, unknown>): string {
 
 export const SUBMIT_TOOL_SPECS: readonly SubmitToolSpec[] = [
 	{
-		toolName: "submit_scout_findings",
-		agents: [
-			"harness/planning/scout-graphify",
-			"harness/planning/scout-structure",
-			"harness/planning/scout-semantic",
-		],
-		schemaFile: "plan-scout-findings.schema.json",
-		artifactPath: (doc) => {
-			const lane =
-				typeof doc.lane === "string"
-					? doc.lane
-					: typeof doc.scout_lane === "string"
-						? doc.scout_lane
-						: "graphify";
-			return `artifacts/scout-${lane}.yaml`;
-		},
+		toolName: "submit_planning_context",
+		agents: ["harness/planning/planning-context"],
+		schemaFile: "plan-planning-context.schema.json",
+		artifactPath: "artifacts/planning-context.yaml",
 	},
 	{
 		toolName: "submit_decomposition_brief",
-		agents: ["harness/planning/decompose"],
+		agents: ["harness/planning/decompose", "harness/planning/plan-synthesizer"],
 		schemaFile: "plan-decomposition-brief.schema.json",
 		artifactPath: "artifacts/decomposition.yaml",
 	},
 	{
 		toolName: "submit_hypothesis_brief",
-		agents: ["harness/planning/hypothesis"],
+		agents: [
+			"harness/planning/hypothesis",
+			"harness/planning/plan-synthesizer",
+		],
 		schemaFile: "plan-hypothesis-brief.schema.json",
 		artifactPath: "artifacts/hypothesis.yaml",
 	},
@@ -66,7 +57,10 @@ export const SUBMIT_TOOL_SPECS: readonly SubmitToolSpec[] = [
 	},
 	{
 		toolName: "submit_execution_plan_brief",
-		agents: ["harness/planning/execution-plan-author"],
+		agents: [
+			"harness/planning/execution-plan-author",
+			"harness/planning/plan-synthesizer",
+		],
 		schemaFile: "plan-execution-plan-brief.schema.json",
 		artifactPath: "artifacts/execution-plan-draft.yaml",
 	},
@@ -106,19 +100,19 @@ export const SUBMIT_TOOL_SPECS: readonly SubmitToolSpec[] = [
 	},
 	{
 		toolName: "submit_executor_handoff",
-		agents: ["harness/executor"],
+		agents: ["harness/running/executor"],
 		schemaFile: "harness-executor-handoff.schema.json",
 		artifactPath: "handoff/executor-summary.yaml",
 	},
 	{
 		toolName: "submit_eval_verdict",
-		agents: ["harness/evaluator"],
+		agents: ["harness/reviewing/evaluator"],
 		schemaFile: "eval-verdict.schema.json",
 		artifactPath: "artifacts/eval-verdict.yaml",
 	},
 	{
 		toolName: "submit_adversary_report",
-		agents: ["harness/adversary"],
+		agents: ["harness/reviewing/adversary"],
 		schemaFile: "adversary-report.schema.json",
 		artifactPath: "artifacts/adversary-report.yaml",
 	},
@@ -129,6 +123,12 @@ export const SUBMIT_TOOL_SPECS: readonly SubmitToolSpec[] = [
 		artifactPath: "artifacts/human-required.yaml",
 		humanRequired: true,
 	},
+	{
+		toolName: "submit_sentrux_manifest_proposal",
+		agents: ["harness/sentrux-steward"],
+		schemaFile: "sentrux-manifest-proposal.schema.json",
+		artifactPath: "artifacts/sentrux-manifest-proposal.yaml",
+	},
 ] as const;
 
 export const SUBMIT_TOOLS_BY_AGENT: Readonly<

package/.pi/extensions/lib/harness-subagents-bridge.ts

@@ -118,32 +118,6 @@ export function createHarnessSubagentsExtension(
 		resolveSubprocessEnv: (task, agent) => {
 			if (!agent.name.startsWith("harness/")) return undefined;
 			const ctx = parseSpawnContextFromTask(task);
-			// #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: "H1",
-						location: "harness-subagents-bridge.ts:resolveSubprocessEnv",
-						message: "parsed spawn context for subprocess env",
-						data: {
-							agent: agent.name,
-							hasCtx: Boolean(ctx?.run_id),
-							run_id: ctx?.run_id ?? null,
-							run_dir: ctx?.run_dir ?? null,
-							taskPrefix: task.slice(0, 160),
-						},
-						timestamp: Date.now(),
-					}),
-				},
-			).catch(() => {});
-			// #endregion
 			if (!ctx?.run_id) return undefined;
 			return {
 				HARNESS_RUN_ID: ctx.run_id,
@@ -168,11 +142,16 @@ export function createHarnessSubagentsExtension(
 					return { ok: false, message: budget.message };
 				}
 				const entries = ctx.sessionManager.getEntries();
-				const phase = inferPhaseForPrecheck(ctx.sessionManager.getEntries());
-				const pre = precheckHarnessSubagentSpawn(
+				const runCtx = getLatestRunContext(entries);
+				const phase = inferPhaseForPrecheck(entries);
+				const pre = await precheckHarnessSubagentSpawn(
 					params as Parameters<typeof precheckHarnessSubagentSpawn>[0],
 					agents,
 					phase,
+					{
+						projectRoot: ctx.cwd,
+						runId: runCtx?.run_id ?? null,
+					},
 				);
 				if (!pre.ok) {
 					return { ok: false, message: pre.message };
@@ -185,7 +164,6 @@ export function createHarnessSubagentsExtension(
 						return { ok: false, message: refreshMsg };
 					}
 				}
-				const runCtx = getLatestRunContext(entries);
 				const runId =
 					runCtx?.run_id ??
 					getRunIdFromSession(entries, lastSessionId) ??

package/.pi/extensions/lib/harness-subprocess-bootstrap.ts

@@ -0,0 +1,73 @@
+/**
+ * Seed harness-run-context + policy-gate session entries in subagent subprocesses.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	getLatestRunContext,
+	type HarnessRunContext,
+	isHarnessSubprocess,
+	loadRunContextForSubprocess,
+	nowIso,
+	policyBootstrapFromRunContext,
+} from "../../lib/harness-run-context.js";
+
+type PolicyState = {
+	phase: "plan" | "execute" | "evaluate" | "adversary" | "merge";
+	approvedPlan: boolean;
+	planId: string | null;
+	budgetBypass: boolean;
+	aborted: boolean;
+	abortReason: string | null;
+	abortedAt: string | null;
+	updatedAt: string;
+};
+
+function defaultPolicyState(): PolicyState {
+	return {
+		phase: "plan",
+		approvedPlan: false,
+		planId: null,
+		budgetBypass: false,
+		aborted: false,
+		abortReason: null,
+		abortedAt: null,
+		updatedAt: nowIso(),
+	};
+}
+
+/** Append disk-backed run + policy entries when subprocess has no session context yet. */
+export async function bootstrapHarnessSubprocessFromEnv(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+): Promise<HarnessRunContext | null> {
+	if (!isHarnessSubprocess()) return null;
+	const entries = ctx.sessionManager.getEntries();
+	if (getLatestRunContext(entries)) return getLatestRunContext(entries);
+
+	const projectRoot = ctx.cwd;
+	const sessionId = ctx.sessionManager.getSessionId();
+	const disk = await loadRunContextForSubprocess(projectRoot);
+	if (!disk?.plan_ready) return null;
+
+	const runCtx: HarnessRunContext = {
+		...disk,
+		pi_session_id: sessionId,
+	};
+	pi.appendEntry("harness-run-context", runCtx);
+
+	const boot = policyBootstrapFromRunContext(runCtx);
+	const policy: PolicyState = {
+		...defaultPolicyState(),
+		phase: boot.phase,
+		approvedPlan: boot.approvedPlan,
+		planId: boot.planId,
+		updatedAt: nowIso(),
+	};
+	pi.appendEntry("harness-policy-state", policy);
+
+	return runCtx;
+}

package/.pi/extensions/lib/plan-approval/create-plan.ts

@@ -12,12 +12,11 @@ import {
 import { writeYamlFile } from "../../../lib/harness-yaml.js";
 import { writePlanReviewMarkdown } from "./plan-review.js";
 
-export const CREATE_PLAN_SNIPPET =
-	"create_plan({ plan_packet: { ...approved PlanPacket } })";
+export const CREATE_PLAN_SNIPPET = "create_plan()";
 
 export const CREATE_PLAN_GUIDELINES = [
 	"Call create_plan only after the user approves via approve_plan (Approve selection).",
-	"Pass the same plan_packet you showed in approve_plan — path is resolved automatically.",
+	"Uses plan-packet.yaml on disk at plan_packet_path (path-first; no inline packet).",
 	"Never use write or edit for plan-packet.yaml; create_plan is the only allowed plan write.",
 ];
 

package/.pi/extensions/lib/plan-approval/resolve-disk.ts

@@ -0,0 +1,102 @@
+import { join } from "node:path";
+import {
+	canonicalPlanPath,
+	getLatestRunContext,
+	harnessRunsRoot,
+	type PlanPacketLike,
+	RESEARCH_BRIEF_BASENAME,
+	readPlanPacketFromPath,
+	validatePlanPacket,
+} from "../../../lib/harness-run-context.js";
+import { readYamlFile } from "../../../lib/harness-yaml.js";
+import type { ApprovePlanParams, PlanResearchBrief } from "./types.js";
+
+function isNonEmptyPacket(
+	packet: PlanPacketLike | null | undefined,
+): packet is PlanPacketLike {
+	return Boolean(
+		packet &&
+			typeof packet === "object" &&
+			Object.keys(packet).length > 0 &&
+			packet.plan_id,
+	);
+}
+
+export async function loadResearchBriefFromRun(
+	runId: string,
+	projectRoot: string,
+): Promise<PlanResearchBrief | undefined> {
+	try {
+		const path = join(
+			harnessRunsRoot(projectRoot),
+			runId,
+			RESEARCH_BRIEF_BASENAME,
+		);
+		return (await readYamlFile(
+			path,
+			RESEARCH_BRIEF_BASENAME,
+		)) as PlanResearchBrief;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Path-first approve_plan: load packet + research brief from active run dir. */
+export async function resolveApprovePlanParamsFromDisk(
+	params: ApprovePlanParams,
+	entries: unknown[],
+	projectRoot: string,
+): Promise<
+	| {
+			ok: true;
+			plan_packet: PlanPacketLike;
+			research_brief?: PlanResearchBrief;
+	  }
+	| { ok: false; error: string }
+> {
+	const inline = params.plan_packet;
+	if (isNonEmptyPacket(inline)) {
+		const validation = validatePlanPacket(inline);
+		if (!validation.valid) {
+			return {
+				ok: false,
+				error: `approve_plan: invalid plan_packet — ${validation.errors.join("; ")}`,
+			};
+		}
+		return {
+			ok: true,
+			plan_packet: inline,
+			research_brief: params.research_brief ?? undefined,
+		};
+	}
+
+	const runCtx = getLatestRunContext(entries);
+	if (!runCtx?.run_id) {
+		return {
+			ok: false,
+			error:
+				'approve_plan: no active harness run. Run /harness-plan "<task>" first.',
+		};
+	}
+	const planPath =
+		runCtx.plan_packet_path ?? canonicalPlanPath(runCtx.run_id, projectRoot);
+	const packet = await readPlanPacketFromPath(planPath);
+	if (!isNonEmptyPacket(packet)) {
+		return {
+			ok: false,
+			error:
+				"approve_plan: plan_packet missing on disk. Write plan-packet.yaml draft before approve_plan.",
+		};
+	}
+	const validation = validatePlanPacket(packet);
+	if (!validation.valid) {
+		return {
+			ok: false,
+			error: `approve_plan: invalid plan_packet on disk — ${validation.errors.join("; ")}`,
+		};
+	}
+	const research_brief =
+		params.research_brief ??
+		(await loadResearchBriefFromRun(runCtx.run_id, projectRoot));
+	return { ok: true, plan_packet: packet, research_brief };
+}

package/.pi/extensions/lib/plan-approval/schema.ts

@@ -1,12 +1,14 @@
 import { Type } from "@sinclair/typebox";
 
 export const ApprovePlanParamsSchema = Type.Object({
-	plan_packet: Type.Object(
-		{},
-		{
-			description:
-				"Full PlanPacket object (schema_version, plan_id, task_id, scope, assumptions, risk_level, acceptance_checks, rollback_plan).",
-		},
+	plan_packet: Type.Optional(
+		Type.Object(
+			{},
+			{
+				description:
+					"Optional inline PlanPacket (deprecated). Default: read plan-packet.yaml from active run (ADR 0043).",
+			},
+		),
 	),
 	human_summary: Type.Optional(
 		Type.String({
@@ -45,10 +47,22 @@ export const ApprovePlanParamsSchema = Type.Object({
 });
 
 export const PROMPT_SNIPPET =
-	"approve_plan({ plan_packet: { ...PlanPacket fields... }, human_summary?: string, research_brief?: { decomposition, hypothesis, eval } })";
+	"approve_plan({ human_summary?: string }) — loads plan-packet.yaml from active run";
 
 export const PROMPT_GUIDELINES = [
-	"Call approve_plan once with the complete plan_packet when ready for user approval.",
+	"Call approve_plan once when plan-packet.yaml is on disk (path-first; do not embed full packet in tool args).",
 	"Use ask_user only for clarification — not for final plan approval.",
 	"On Request changes, revise the plan and call approve_plan again.",
 ];
+
+export const CreatePlanParamsSchema = Type.Object({
+	plan_packet: Type.Optional(
+		Type.Object(
+			{},
+			{
+				description:
+					"Optional inline packet (deprecated). Default: read approved plan from plan_packet_path.",
+			},
+		),
+	),
+});

package/.pi/extensions/lib/plan-approval/types.ts

@@ -22,7 +22,7 @@ export interface PlanResearchBrief {
 }
 
 export interface ApprovePlanParams {
-	plan_packet: PlanPacketLike;
+	plan_packet?: PlanPacketLike;
 	human_summary?: string;
 	research_brief?: PlanResearchBrief | null;
 	options?: Array<string | { title: string; description?: string }>;

package/.pi/extensions/lib/plan-approval/validate.ts

@@ -15,8 +15,8 @@ export function validateApprovePlanParams(
 	params: ApprovePlanParams,
 ): ValidatedApprovePlanParams | string {
 	const packet = params.plan_packet;
-	if (!packet || typeof packet !== "object") {
-		return "approve_plan: plan_packet object is required.";
+	if (!packet || typeof packet !== "object" || !packet.plan_id) {
+		return "approve_plan: plan_packet must be resolved from disk before validate (use resolveApprovePlanParamsFromDisk).";
 	}
 	const validation = validatePlanPacket(packet as PlanPacketLike);
 	if (!validation.valid) {