ultimate-pi 0.10.0 → 0.11.0

package/.pi/extensions/harness-live-widget.ts

@@ -329,6 +329,52 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 	let component: HarnessWidgetComponent | null = null;
 	let refreshQueued = false;
 	let lastRenderHash = "";
+	let mountCtx: ExtensionContext | null = null;
+
+	function mountHarnessWidget(ctx: ExtensionContext): void {
+		if (!ctx.hasUI) return;
+		const state = stateStore.refresh(ctx);
+		const inFlight: InFlightState = { toolCount: 0, lastToolName: null };
+		lastRenderHash = computeRenderHash(state, inFlight);
+
+		ctx.ui.setWidget(
+			"harness-live",
+			(tui, theme) => {
+				widgetMounted = true;
+				tuiHandle = tui;
+				component = new HarnessWidgetComponent(
+					stateStore.snapshot(),
+					inFlight,
+					theme,
+				);
+				return {
+					render(width: number): string[] {
+						component?.setTheme(theme);
+						return component?.render(width) ?? [];
+					},
+					invalidate(): void {
+						component?.invalidate();
+					},
+				};
+			},
+			{ placement: "aboveEditor" },
+		);
+		updateStatusFallback(ctx, state);
+	}
+
+	function remountHarnessLiveWidget(ctx: ExtensionContext): void {
+		if (!ctx.hasUI || !widgetMounted) return;
+		ctx.ui.setWidget("harness-live", undefined);
+		mountHarnessWidget(ctx);
+	}
+
+	pi.events.on("subagents:agents-widget-mounted", () => {
+		if (mountCtx) remountHarnessLiveWidget(mountCtx);
+	});
+
+	pi.events.on("plan-approval:mounted", () => {
+		if (mountCtx) remountHarnessLiveWidget(mountCtx);
+	});
 
 	function updateStatusFallback(
 		ctx: ExtensionContext,
@@ -385,34 +431,8 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 	}
 
 	pi.on("session_start", (_event, ctx) => {
-		if (!ctx.hasUI) return;
-		const state = stateStore.refresh(ctx);
-		const inFlight: InFlightState = { toolCount: 0, lastToolName: null };
-		lastRenderHash = computeRenderHash(state, inFlight);
-
-		ctx.ui.setWidget(
-			"harness-live",
-			(tui, theme) => {
-				widgetMounted = true;
-				tuiHandle = tui;
-				component = new HarnessWidgetComponent(
-					stateStore.snapshot(),
-					inFlight,
-					theme,
-				);
-				return {
-					render(width: number): string[] {
-						component?.setTheme(theme);
-						return component?.render(width) ?? [];
-					},
-					invalidate(): void {
-						component?.invalidate();
-					},
-				};
-			},
-			{ placement: "aboveEditor" },
-		);
-		updateStatusFallback(ctx, state);
+		mountCtx = ctx;
+		mountHarnessWidget(ctx);
 	});
 
 	pi.on("context", (_event, ctx) => {

package/.pi/extensions/harness-plan-approval.ts

@@ -4,13 +4,25 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+import type { PlanPacketLike } from "../lib/harness-run-context.js";
 import {
 	appendPlanApprovalIfNew,
 	getLatestRunContext,
+	hasPlanUserApproval,
 	parsePlanApprovalFromMessage,
+	planPacketSummary,
 } from "../lib/harness-run-context.js";
+import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import {
+	CREATE_PLAN_GUIDELINES,
+	CREATE_PLAN_SNIPPET,
+	executeCreatePlan,
+	formatCreatePlanResultText,
+} from "./lib/plan-approval/create-plan.js";
 import { runPlanApprovalDialog } from "./lib/plan-approval/dialog.js";
 import { runPlanApprovalFallback } from "./lib/plan-approval/fallback.js";
+import { writePlanReviewMarkdown } from "./lib/plan-approval/plan-review.js";
 import {
 	renderApprovePlanCall,
 	renderApprovePlanResult,
@@ -31,33 +43,50 @@ import {
 	validateApprovePlanParams,
 } from "./lib/plan-approval/validate.js";
 
+// @ts-expect-error pi extensions run as ESM
+const MODULE_URL = import.meta.url;
+
+const CreatePlanParamsSchema = Type.Object({
+	plan_packet: Type.Object(
+		{},
+		{
+			description:
+				"Approved PlanPacket to persist (same object as approve_plan).",
+		},
+	),
+});
+
 export default function harnessPlanApproval(pi: ExtensionAPI) {
-	pi.registerMessageRenderer("harness-plan-draft", (message, _options, theme) => {
-		const data = message.details as
-			| {
-					plan_packet?: unknown;
-					human_summary?: string | null;
-			  }
-			| undefined;
-		if (!data?.plan_packet) return undefined;
-		const lines = renderHarnessPlanDraft(
-			{
-				plan_packet: data.plan_packet as Parameters<
-					typeof renderHarnessPlanDraft
-				>[0]["plan_packet"],
-				human_summary: data.human_summary,
-			},
-			80,
-			theme,
-		);
-		return new Text(lines.join("\n"), 0, 0);
-	});
+	if (!claimExtensionLoad("harness-plan-approval", MODULE_URL)) return;
+	pi.registerMessageRenderer(
+		"harness-plan-draft",
+		(message, _options, theme) => {
+			const data = message.details as
+				| {
+						plan_packet?: unknown;
+						human_summary?: string | null;
+				  }
+				| undefined;
+			if (!data?.plan_packet) return undefined;
+			const lines = renderHarnessPlanDraft(
+				{
+					plan_packet: data.plan_packet as Parameters<
+						typeof renderHarnessPlanDraft
+					>[0]["plan_packet"],
+					human_summary: data.human_summary,
+				},
+				80,
+				theme,
+			);
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	);
 
 	pi.registerTool({
 		name: "approve_plan",
 		label: "Approve Plan",
 		description:
-			"Present a PlanPacket for user approval with a scrollable plan view. Planners should prefer the subagent bridge; this registers the tool on parent sessions for non-interactive fallback.",
+			"Present a PlanPacket for user approval with a scrollable plan view. Parent /harness-plan orchestrator calls this after decomposition, hypothesis, and parallel reviews.",
 		promptSnippet: PROMPT_SNIPPET,
 		promptGuidelines: PROMPT_GUIDELINES,
 		parameters: ApprovePlanParamsSchema,
@@ -76,25 +105,74 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				};
 			}
 
+			const entries = ctx.sessionManager.getEntries();
+			if (
+				hasPlanUserApproval(entries, {
+					sincePlanCommand: true,
+					planId: validated.plan_packet.plan_id ?? null,
+				})
+			) {
+				const planId = String(validated.plan_packet.plan_id ?? "plan");
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Plan ${planId} already approved in this harness run. Proceed with /harness-run.`,
+						},
+					],
+					details: {
+						plan_packet: validated.plan_packet,
+						options: validated.options,
+						response: {
+							kind: "selection",
+							selections: ["Approve"],
+						},
+						cancelled: false,
+					},
+				};
+			}
+
 			const planId = String(validated.plan_packet.plan_id ?? "plan");
 			const summary =
 				validated.human_summary?.trim() ||
 				`Plan ${planId} — pending your approval`;
+			const runCtx = getLatestRunContext(entries);
+			const projectRoot = process.cwd();
+			const reviewPath = await writePlanReviewMarkdown(
+				projectRoot,
+				runCtx,
+				validated.plan_packet,
+				{
+					human_summary: validated.human_summary,
+					research_brief: validated.research_brief,
+					status: "draft",
+				},
+			);
+			const draftContent =
+				reviewPath != null
+					? `${summary}\nEditor review: ${reviewPath}`
+					: summary;
 			pi.sendMessage({
 				customType: "harness-plan-draft",
-				content: summary,
+				content: draftContent,
 				display: true,
 				details: {
 					schema_version: "1.0.0",
 					plan_packet: validated.plan_packet,
 					human_summary: validated.human_summary ?? null,
+					research_brief: validated.research_brief ?? null,
+					plan_review_path: reviewPath,
 					shown_at: new Date().toISOString(),
 				},
 			});
 
 			let outcome: PlanApprovalDialogResult;
 			if (ctx.hasUI) {
-				outcome = await runPlanApprovalDialog(ctx.ui, validated);
+				outcome = await runPlanApprovalDialog(ctx.ui, validated, {
+					onMounted: () => {
+						pi.events.emit("plan-approval:mounted", {});
+					},
+				});
 			} else {
 				outcome = await runPlanApprovalFallback(ctx.ui, validated);
 			}
@@ -109,7 +187,6 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				details,
 			});
 			if (approval) {
-				const entries = ctx.sessionManager.getEntries();
 				const runCtx = getLatestRunContext(entries);
 				appendPlanApprovalIfNew(
 					(type, data) => pi.appendEntry(type, data),
@@ -119,6 +196,23 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				);
 			}
 
+			const approved =
+				!outcome.cancelled &&
+				outcome.response?.kind === "selection" &&
+				/^approve/i.test(outcome.response.selections[0] ?? "");
+			if (approved && runCtx) {
+				await writePlanReviewMarkdown(
+					projectRoot,
+					runCtx,
+					validated.plan_packet,
+					{
+						human_summary: validated.human_summary,
+						research_brief: validated.research_brief,
+						status: "approved",
+					},
+				);
+			}
+
 			const text = formatApprovePlanResultText(
 				outcome.response,
 				outcome.cancelled,
@@ -137,4 +231,78 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 			return renderApprovePlanResult(result, options, theme);
 		},
 	});
+
+	pi.registerTool({
+		name: "create_plan",
+		label: "Create Plan",
+		description:
+			"Write the approved PlanPacket to plan-packet.json for this harness run. Call only after approve_plan (Approve). Do not use write/edit.",
+		promptSnippet: CREATE_PLAN_SNIPPET,
+		promptGuidelines: CREATE_PLAN_GUIDELINES,
+		parameters: CreatePlanParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const validated = validateApprovePlanParams(params as ApprovePlanParams);
+			if (typeof validated === "string") {
+				return {
+					content: [{ type: "text", text: validated }],
+					details: { error: validated },
+					isError: true,
+				};
+			}
+
+			const entries = ctx.sessionManager.getEntries();
+			const runCtx = getLatestRunContext(entries);
+			const projectRoot = process.cwd();
+			const result = await executeCreatePlan(validated.plan_packet, {
+				projectRoot,
+				getParentEntries: () => entries,
+				getSubagentEntries: () => entries,
+				getParentRunContext: () => runCtx,
+				onCommitted: (updated, packet, planPath) => {
+					pi.appendEntry("harness-run-context", updated);
+					pi.appendEntry(
+						"harness-plan-packet",
+						planPacketSummary(packet, planPath, "ready"),
+					);
+				},
+			});
+
+			const text = formatCreatePlanResultText(result);
+			return {
+				content: [{ type: "text", text }],
+				details: result.ok
+					? { plan_path: result.planPath, plan_id: result.planId }
+					: { error: result.error },
+				isError: !result.ok,
+			};
+		},
+
+		renderCall(args, theme) {
+			const packet = (args as { plan_packet?: PlanPacketLike }).plan_packet;
+			const id = packet?.plan_id ?? "?";
+			return new Text(theme.fg("accent", `create_plan: ${id}`), 0, 0);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as
+				| { plan_path?: string; error?: string }
+				| undefined;
+			if (details?.error) {
+				return new Text(
+					theme.fg("error", details.error ?? "create_plan failed"),
+					0,
+					0,
+				);
+			}
+			return new Text(
+				theme.fg(
+					"success",
+					`Wrote ${details?.plan_path ?? "plan-packet.json"}`,
+				),
+				0,
+				0,
+			);
+		},
+	});
 }

package/.pi/extensions/harness-run-context.ts

@@ -671,20 +671,29 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
-		if (event.toolName === "ask_user" && activeCtx?.plan_packet_path) {
-			const input = event.input as {
-				question?: string;
-				options?: unknown[];
-			};
-			if (
-				isPlanApprovalAskUser(input) &&
-				hasPlanUserApproval(getEntries(ctx), { sincePlanCommand: true })
-			) {
-				return {
-					block: true,
-					reason:
-						"harness-run-context: plan already approved via planner subagent; do not call ask_user for plan approval in the parent session.",
-				};
+		if (activeCtx?.plan_packet_path) {
+			const entries = getEntries(ctx);
+			if (hasPlanUserApproval(entries, { sincePlanCommand: true })) {
+				if (event.toolName === "approve_plan") {
+					return {
+						block: true,
+						reason:
+							"harness-run-context: plan already approved via planner subagent; do not call approve_plan again in the parent session.",
+					};
+				}
+				if (event.toolName === "ask_user") {
+					const input = event.input as {
+						question?: string;
+						options?: unknown[];
+					};
+					if (isPlanApprovalAskUser(input)) {
+						return {
+							block: true,
+							reason:
+								"harness-run-context: plan already approved via planner subagent; do not call ask_user for plan approval in the parent session.",
+						};
+					}
+				}
 			}
 		}
 		if (!activeCtx?.plan_packet_path) return undefined;
@@ -807,7 +816,7 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 				})
 			) {
 				const msg =
-					"Plan commit blocked: no user approval recorded. Approve via ask_user in the planner subagent first.";
+					"Plan commit blocked: no user approval recorded. Approve via approve_plan in this session first.";
 				if (ctx.hasUI) ctx.ui.notify(msg, "warning");
 				return;
 			}

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

@@ -1,9 +1,14 @@
 /**
  * harness-subagents — package-resolved agents, blackboard, observation-bus handoffs.
  */
+
+import { claimExtensionLoad } from "./lib/extension-load-guard.js";
 import { getHarnessPackageRoot } from "./lib/harness-paths.js";
 import { createHarnessSubagentsExtension } from "./lib/harness-subagents/vendored/index.js";
 
-export default createHarnessSubagentsExtension(
-	getHarnessPackageRoot(import.meta.url),
-);
+// @ts-expect-error pi extensions run as ESM
+const MODULE_URL = import.meta.url;
+
+export default claimExtensionLoad("harness-subagents", MODULE_URL)
+	? createHarnessSubagentsExtension(getHarnessPackageRoot(MODULE_URL))
+	: () => {};

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

@@ -4,6 +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 {
 	harnessWebContextLine,
 	readTextExcerpt,
@@ -97,6 +98,7 @@ function sessionCwd(ctx: { cwd?: string }): string {
 }
 
 export default function harnessWebTools(pi: ExtensionAPI) {
+	if (!claimExtensionLoad("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

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LOAD_GUARD_KEY = Symbol.for("ultimate-pi.extension-load-guard");
+
+type LoadGuardRegistry = Set<string>;
+
+function getRegistry(): LoadGuardRegistry {
+	const state = globalThis as typeof globalThis & {
+		[LOAD_GUARD_KEY]?: LoadGuardRegistry;
+	};
+	if (!state[LOAD_GUARD_KEY]) {
+		state[LOAD_GUARD_KEY] = new Set<string>();
+	}
+	return state[LOAD_GUARD_KEY];
+}
+
+function isSourceRepo(): boolean {
+	try {
+		const pkg = JSON.parse(
+			readFileSync(join(process.cwd(), "package.json"), "utf8"),
+		) as { name?: string };
+		return pkg.name === "ultimate-pi";
+	} catch {
+		return false;
+	}
+}
+
+export function claimExtensionLoad(key: string, moduleUrl: string): boolean {
+	const registry = getRegistry();
+	const modulePath = fileURLToPath(moduleUrl);
+	if (modulePath.includes("/node_modules/ultimate-pi/") && isSourceRepo()) {
+		return false;
+	}
+	if (registry.has(key)) return false;
+	registry.add(key);
+	return true;
+}

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

@@ -20,6 +20,15 @@ export type HarnessAgentKind =
 
 const MUTATING_TOOLS = new Set(["write", "edit"]);
 
+const PLANNING_BASH_DENY_PATTERNS = [
+	/\bgraphify\s+update\b/i,
+	/\bgraphify\s+extract\b/i,
+	/\bgraphify\s+install\b/i,
+	/\bpip\s+install\b/i,
+	/\buv\s+tool\s+install\b/i,
+	/\bnpm\s+install\b/i,
+];
+
 const BASH_MUTATION_PATTERNS = [
 	/\brm\s+-/i,
 	/\bmv\s+/i,
@@ -45,8 +54,16 @@ const READ_ONLY_KINDS = new Set<HarnessAgentKind>([
 	"meta",
 ]);
 
+export function isHarnessPlanningAgent(agentType: string): boolean {
+	const id = agentType.replace(/^harness\//, "");
+	return id === "planner" || id.startsWith("planning/");
+}
+
 export function classifyHarnessAgent(agentType: string): HarnessAgentKind {
 	const id = agentType.replace(/^harness\//, "");
+	if (id.startsWith("planning/") || id === "planner") {
+		return "planner";
+	}
 	switch (id) {
 		case "planner":
 			return "planner";
@@ -96,13 +113,10 @@ export function evaluateHarnessSubagentToolCall(
 		return { action: "allow" };
 	}
 
-	if (toolName === "create_plan") {
-		if (kind === "planner") {
-			return { action: "allow" };
-		}
+	if (toolName === "create_plan" || toolName === "approve_plan") {
 		return {
 			action: "block",
-			reason: `harness-subagent-policy: create_plan is only for harness/planner.`,
+			reason: `harness-subagent-policy: ${toolName} is parent-orchestrator only (not available in subagents).`,
 		};
 	}
 
@@ -121,6 +135,17 @@ export function evaluateHarnessSubagentToolCall(
 				reason: `harness-subagent-policy: mutating bash blocked for harness/${kind}.`,
 			};
 		}
+		if (
+			command &&
+			isHarnessPlanningAgent(agentType) &&
+			PLANNING_BASH_DENY_PATTERNS.some((p) => p.test(command))
+		) {
+			return {
+				action: "block",
+				reason:
+					"harness-subagent-policy: planning scouts may use read-only graphify/sg/ck commands only.",
+			};
+		}
 	}
 
 	return { action: "allow" };
@@ -128,6 +153,9 @@ export function evaluateHarnessSubagentToolCall(
 
 /** Policy phase hint seeded into subagent system prompt appendix when extensions load policy-gate. */
 export function harnessSubagentPhaseHint(agentType: string): string | null {
+	if (isHarnessPlanningAgent(agentType)) {
+		return "plan";
+	}
 	const kind = classifyHarnessAgent(agentType);
 	switch (kind) {
 		case "planner":