ultimate-pi 0.14.0 → 0.16.0

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

@@ -3,12 +3,14 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import {
+	deriveHarnessStatusHint,
+	formatHarnessPhaseLabel,
+	type HarnessStatusSeverity,
 	type HarnessUiState,
 	HarnessUiStateStore,
+	nextHarnessPhase,
 } from "../lib/harness-ui-state";
 
-type Severity = "accent" | "warning" | "error";
-
 type TuiLike = { requestRender(): void };
 type ThemeLike = {
 	fg(
@@ -164,31 +166,25 @@ function composeZones(left: string, right: string, width: number): string {
 	return fitToWidth(`${leftFit}${" ".repeat(minGap)}${rightFit}`, width);
 }
 
-type InFlightState = {
-	toolCount: number;
-	lastToolName: string | null;
-};
+function themeSeverityColor(
+	severity: HarnessStatusSeverity,
+): "accent" | "warning" | "error" | "success" | "muted" {
+	return severity;
+}
 
 class HarnessWidgetComponent {
 	private widthCache?: number;
 	private linesCache?: string[];
 	private state: HarnessUiState;
-	private inFlight: InFlightState;
 	private themeRef: ThemeLike;
 
-	constructor(
-		state: HarnessUiState,
-		inFlight: InFlightState,
-		theme: ThemeLike,
-	) {
+	constructor(state: HarnessUiState, theme: ThemeLike) {
 		this.state = state;
-		this.inFlight = inFlight;
 		this.themeRef = theme;
 	}
 
-	public setData(state: HarnessUiState, inFlight: InFlightState): void {
+	public setData(state: HarnessUiState): void {
 		this.state = state;
-		this.inFlight = inFlight;
 		this.invalidate();
 	}
 
@@ -201,109 +197,23 @@ class HarnessWidgetComponent {
 		if (this.linesCache && this.widthCache === width) return this.linesCache;
 		const theme = this.themeRef;
 		const rowWidth = Math.max(1, width - TERMINAL_WIDTH_SAFETY_MARGIN);
-		const showDebateRow =
-			this.state.phase === "adversary" || this.state.phase === "merge";
-
-		const substateColor: Severity =
-			this.state.flowSubstate === "blocked"
-				? "error"
-				: this.state.flowSubstate === "severity-policy" ||
-						this.state.flowSubstate === "human-required"
-					? "warning"
-					: "accent";
-		const policyColor =
-			this.state.policyDecision === "pass"
-				? "success"
-				: this.state.policyDecision === "conditional_pass"
-					? "warning"
-					: this.state.policyDecision === "block" ||
-							this.state.policyDecision === "human_required"
-						? "error"
-						: "muted";
-
-		const policyDisplay = this.state.policyDecision ?? "pending";
-
-		const phaseToken = `${theme.fg("dim", "phase:")}${theme.fg("accent", this.state.phase)}`;
-		const flowToken = `${theme.fg("dim", "flow:")}${theme.fg(substateColor, this.state.flowSubstate)}`;
-		const policyToken = `${theme.fg("dim", "policy:")}${theme.fg(policyColor, policyDisplay)}`;
-		const row1 = composeZones(
-			`${theme.bold("Harness")} ${phaseToken} ${flowToken}`,
-			policyToken,
-			rowWidth,
-		);
 
-		const debateProgress =
-			this.state.debateMaxRounds != null
-				? `${this.state.debateRound}/${this.state.debateMaxRounds}`
-				: String(this.state.debateRound);
-		const budgetDisplay =
-			this.state.debateBudgetUsed != null && this.state.debateBudgetCap != null
-				? `${this.state.debateBudgetUsed}/${this.state.debateBudgetCap}`
-				: this.state.debateBudgetUsed != null
-					? String(this.state.debateBudgetUsed)
-					: "n/a";
-		const consensusTrend =
-			this.state.consensusDelta == null
-				? "flat"
-				: this.state.consensusDelta > 0
-					? "up"
-					: this.state.consensusDelta < 0
-						? "down"
-						: "flat";
-		const trendColor =
-			consensusTrend === "up"
-				? "success"
-				: consensusTrend === "down"
-					? "warning"
-					: "muted";
-
-		const sev = this.state.severity;
-		const severityCompact =
-			sev.correctness == null &&
-			sev.security == null &&
-			sev.architecture == null &&
-			sev.testIntegrity == null
-				? theme.fg("muted", "sev:n/a")
-				: `${theme.fg("dim", "sev")} ${theme.fg("accent", `c:${sev.correctness ?? "-"}`)} ${theme.fg("accent", `s:${sev.security ?? "-"}`)} ${theme.fg("accent", `a:${sev.architecture ?? "-"}`)} ${theme.fg("accent", `t:${sev.testIntegrity ?? "-"}`)}`;
-
-		const planFlag = this.state.planApproved
-			? `${theme.fg("dim", "📋 Plan:")}${theme.fg("success", "OK")}`
-			: `${theme.fg("dim", "📋 Plan:")}${theme.fg("error", "NO")}`;
-		const reviewFlag = this.state.reviewIsolationOk
-			? `${theme.fg("dim", "🧪 Review:")}${theme.fg("success", "OK")}`
-			: `${theme.fg("dim", "🧪 Review:")}${theme.fg("warning", "ISO")}`;
-		const budgetFlag = this.state.budgetExhausted
-			? `${theme.fg("dim", "💰 Budget:")}${theme.fg("error", "HIT")}`
-			: `${theme.fg("dim", "💰 Budget:")}${theme.fg("success", "OK")}`;
-		const testsFlag =
-			this.state.testIntegritySeverity === "high"
-				? `${theme.fg("dim", "🛡 Tests:")}${theme.fg("error", "HIGH")}`
-				: this.state.testIntegritySeverity === "medium"
-					? `${theme.fg("dim", "🛡 Tests:")}${theme.fg("warning", "MED")}`
-					: `${theme.fg("dim", "🛡 Tests:")}${theme.fg("success", "OK")}`;
-
-		const toolDisplay = this.inFlight.lastToolName
-			? `${this.inFlight.toolCount}:${this.inFlight.lastToolName}`
-			: String(this.inFlight.toolCount);
-		const nextDisplay =
-			this.state.nextRecommendedCommand != null
-				? this.state.nextRecommendedCommand.length > 36
-					? `${this.state.nextRecommendedCommand.slice(0, 33)}...`
-					: this.state.nextRecommendedCommand
-				: null;
-		const row3Left = `${planFlag} ${reviewFlag} ${budgetFlag} ${testsFlag}`;
-		const row3Right = nextDisplay
-			? `${theme.fg("dim", "inFlight:")}${theme.fg("accent", toolDisplay)} ${theme.fg("dim", "next:")}${theme.fg("accent", nextDisplay)}`
-			: `${theme.fg("dim", "inFlight:")}${theme.fg("accent", toolDisplay)}`;
-		const row3 = composeZones(row3Left, row3Right, rowWidth);
-
-		const lines: string[] = [truncateToWidth(row1, rowWidth)];
-		if (showDebateRow) {
-			const debateLeft = `${theme.fg("dim", "Debate")} ${theme.fg("accent", `rounds:${debateProgress}`)} ${theme.fg("dim", "trend:")}${theme.fg(trendColor, consensusTrend)} ${theme.fg("dim", "budget:")}${theme.fg("accent", budgetDisplay)}`;
-			const row2 = composeZones(debateLeft, severityCompact, rowWidth);
-			lines.push(truncateToWidth(row2, rowWidth));
-		}
-		lines.push(truncateToWidth(row3, rowWidth));
+		const currentLabel = formatHarnessPhaseLabel(this.state.phase);
+		const nextPhase = nextHarnessPhase(this.state.phase);
+		const nowToken = `${theme.fg("dim", "now:")}${theme.fg("accent", currentLabel)}`;
+		const phaseToken =
+			nextPhase != null
+				? `${nowToken} ${theme.fg("dim", "→")} ${theme.fg("accent", formatHarnessPhaseLabel(nextPhase))}`
+				: nowToken;
+
+		const status = deriveHarnessStatusHint(this.state);
+		const statusColor = themeSeverityColor(status.severity);
+		const statusToken = theme.fg(statusColor, status.text);
+
+		const left = `${theme.bold("Harness")} ${phaseToken}`;
+		const row = composeZones(left, statusToken, rowWidth);
+
+		const lines = [truncateToWidth(row, rowWidth)];
 		this.widthCache = width;
 		this.linesCache = lines;
 		return lines;
@@ -316,14 +226,16 @@ class HarnessWidgetComponent {
 }
 
 function statusToken(state: HarnessUiState): string {
-	const decision = state.policyDecision ?? "pending";
-	return `h:${state.phase}/${state.flowSubstate}/${decision}`;
+	const current = formatHarnessPhaseLabel(state.phase);
+	const next = nextHarnessPhase(state.phase);
+	const phasePart =
+		next != null ? `${current}→${formatHarnessPhaseLabel(next)}` : current;
+	const hint = deriveHarnessStatusHint(state).text;
+	return `h:${phasePart}|${hint}`;
 }
 
 export default function harnessLiveWidget(pi: ExtensionAPI) {
 	const stateStore = new HarnessUiStateStore();
-	const inFlightCalls = new Set<string>();
-	let lastToolName: string | null = null;
 	let widgetMounted = false;
 	let tuiHandle: TuiLike | null = null;
 	let component: HarnessWidgetComponent | null = null;
@@ -334,19 +246,14 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 	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);
+		lastRenderHash = computeRenderHash(state);
 
 		ctx.ui.setWidget(
 			"harness-live",
 			(tui, theme) => {
 				widgetMounted = true;
 				tuiHandle = tui;
-				component = new HarnessWidgetComponent(
-					stateStore.snapshot(),
-					inFlight,
-					theme,
-				);
+				component = new HarnessWidgetComponent(stateStore.snapshot(), theme);
 				return {
 					render(width: number): string[] {
 						component?.setTheme(theme);
@@ -388,26 +295,15 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 		ctx.ui.setStatus("harness-mode", undefined);
 	}
 
-	function computeRenderHash(
-		state: HarnessUiState,
-		inFlight: InFlightState,
-	): string {
+	function computeRenderHash(state: HarnessUiState): string {
 		return JSON.stringify({
 			phase: state.phase,
-			flowSubstate: state.flowSubstate,
 			planApproved: state.planApproved,
-			reviewIsolationOk: state.reviewIsolationOk,
 			budgetExhausted: state.budgetExhausted,
 			testIntegritySeverity: state.testIntegritySeverity,
-			debateRound: state.debateRound,
-			debateMaxRounds: state.debateMaxRounds,
-			debateBudgetUsed: state.debateBudgetUsed,
-			debateBudgetCap: state.debateBudgetCap,
 			policyDecision: state.policyDecision,
-			consensusDelta: state.consensusDelta,
-			severity: state.severity,
+			flowSubstate: state.flowSubstate,
 			nextRecommendedCommand: state.nextRecommendedCommand,
-			inFlight,
 		});
 	}
 
@@ -417,15 +313,11 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 		queueMicrotask(() => {
 			refreshQueued = false;
 			const state = stateStore.refresh(ctx);
-			const inFlight: InFlightState = {
-				toolCount: inFlightCalls.size,
-				lastToolName,
-			};
-			const hash = computeRenderHash(state, inFlight);
+			const hash = computeRenderHash(state);
 			updateStatusFallback(ctx, state);
 			if (hash === lastRenderHash) return;
 			lastRenderHash = hash;
-			if (component) component.setData(state, inFlight);
+			if (component) component.setData(state);
 			tuiHandle?.requestRender();
 		});
 	}
@@ -450,16 +342,4 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 	pi.on("agent_end", (_event, ctx) => {
 		scheduleRefresh(ctx);
 	});
-
-	pi.on("tool_execution_start", (event, ctx) => {
-		inFlightCalls.add(event.toolCallId);
-		lastToolName = event.toolName;
-		scheduleRefresh(ctx);
-	});
-
-	pi.on("tool_result", (event, ctx) => {
-		inFlightCalls.delete(event.toolCallId);
-		if (inFlightCalls.size === 0) lastToolName = null;
-		scheduleRefresh(ctx);
-	});
 }

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

@@ -2,6 +2,9 @@
  * harness-plan-approval — PlanPacket approval UI and transcript renderer for parent sessions.
  */
 
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -146,6 +149,43 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				`Plan ${planId} — pending your approval`;
 			const runCtx = getLatestRunContext(entries);
 			const projectRoot = process.cwd();
+			const implWarnings: string[] = [];
+			if (runCtx?.run_id) {
+				const implPath = join(
+					projectRoot,
+					".pi",
+					"harness",
+					"runs",
+					runCtx.run_id,
+					"artifacts",
+					"implementation-research.yaml",
+				);
+				let implExists = false;
+				try {
+					await access(implPath, constants.R_OK);
+					implExists = true;
+				} catch {
+					implExists = false;
+				}
+				const risk = String(
+					validated.plan_packet.risk_level ?? "med",
+				).toLowerCase();
+				if (!implExists) {
+					const msg =
+						"approve_plan: missing artifacts/implementation-research.yaml (Phase 3.5 required)";
+					if (risk === "high") {
+						return {
+							content: [{ type: "text", text: msg }],
+							details: {
+								plan_packet: validated.plan_packet,
+								cancelled: true,
+							},
+							isError: true,
+						};
+					}
+					implWarnings.push(msg);
+				}
+			}
 			if (runCtx?.run_id) {
 				const gate = await validatePlanDebateGate(projectRoot, runCtx.run_id);
 				if (!gate.ok) {
@@ -237,13 +277,15 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				);
 			}
 
-			const text = formatApprovePlanResultText(
-				outcome.response,
-				outcome.cancelled,
-			);
+			const text = [
+				formatApprovePlanResultText(outcome.response, outcome.cancelled),
+				...implWarnings,
+			]
+				.filter(Boolean)
+				.join("\n\n");
 			return {
 				content: [{ type: "text", text }],
-				details,
+				details: { ...details, implementation_warnings: implWarnings },
 			};
 		},
 

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

@@ -5,8 +5,9 @@
  * in before_agent_start so trace-recorder reuses it on agent_start.
  */
 
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { constants } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import {
@@ -56,6 +57,10 @@ import {
 	writeYamlFile,
 } from "../lib/harness-yaml.js";
 import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import {
+	evaluateHarnessSubagentToolCall,
+	isSubmitToolName,
+} from "./lib/harness-subagent-policy.js";
 import { isReviewRoundArtifactPath } from "./lib/plan-debate-gate.js";
 import { isReviewRoundYamlWriteAllowed } from "./lib/plan-debate-write-guard.js";
 
@@ -714,6 +719,36 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
+		// #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",
+				location: "harness-run-context.ts:tool_call",
+				message: "submit policy hook",
+				data: {
+					toolName: event.toolName,
+					typeofIsSubmitToolName: typeof isSubmitToolName,
+				},
+				timestamp: Date.now(),
+				hypothesisId: "H1",
+			}),
+		}).catch(() => {});
+		// #endregion
+		if (isSubmitToolName(event.toolName)) {
+			const decision = evaluateHarnessSubagentToolCall(
+				event.toolName,
+				event.input as Record<string, unknown>,
+				"parent-orchestrator",
+			);
+			if (decision.action === "block") {
+				return { block: true, reason: decision.reason };
+			}
+		}
 		if (event.toolName === "write") {
 			const entries = getEntries(ctx);
 			const runCtx = getLatestRunContext(entries) ?? activeCtx;
@@ -1030,6 +1065,65 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool({
+		name: "harness_artifact_ready",
+		label: "Harness Artifact Ready",
+		description:
+			"Check that harness artifact paths exist under the active run (no JSON parsing).",
+		parameters: Type.Object({
+			paths: Type.Array(Type.String(), {
+				minItems: 1,
+				description:
+					"Relative paths under the run dir, e.g. artifacts/decomposition.yaml",
+			}),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const entries = getEntries(ctx);
+			const runCtx = getLatestRunContext(entries) ?? activeCtx;
+			if (!runCtx?.run_id) {
+				return {
+					content: [{ type: "text", text: "No active harness run." }],
+					details: {},
+					isError: true,
+				};
+			}
+			const paths = (params as { paths?: string[] }).paths ?? [];
+			const projectRoot = process.cwd();
+			const runRoot = join(
+				projectRoot,
+				".pi",
+				"harness",
+				"runs",
+				runCtx.run_id,
+			);
+			const missing: string[] = [];
+			const present: string[] = [];
+			for (const rel of paths) {
+				const normalized = rel.replace(/\\/g, "/");
+				const abs = join(runRoot, normalized);
+				try {
+					await access(abs, constants.R_OK);
+					present.push(normalized);
+				} catch {
+					missing.push(normalized);
+				}
+			}
+			const ok = missing.length === 0;
+			return {
+				content: [
+					{
+						type: "text",
+						text: ok
+							? `All ${present.length} artifact(s) present.`
+							: `Missing: ${missing.join(", ")}`,
+					},
+				],
+				details: { ok, present, missing, run_id: runCtx.run_id },
+				isError: !ok,
+			};
+		},
+	});
+
 	pi.registerCommand("harness-use-run", {
 		description: "Point this session at an existing run directory (recovery)",
 		handler: async (args, ctx) => {

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

@@ -0,0 +1,195 @@
+/**
+ * Subprocess-only harness submit tools — validate + write artifacts under run_dir.
+ * Loaded via `pi --no-extensions -e harness-subagent-submit.ts` for harness agents.
+ */
+
+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 { getHarnessPackageRoot } from "./lib/harness-paths.js";
+import { evaluateHarnessSubagentToolCall } from "./lib/harness-subagent-policy.js";
+import { executeSubmitPipeline } 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
+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",
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+function resolveRunContext(): {
+	projectRoot: string;
+	specsDir: string;
+	runId: string;
+	runDirEnv?: string;
+	agentId: string;
+} {
+	const projectRoot = process.env.HARNESS_PKG_ROOT ?? process.cwd();
+	const specsDir = join(projectRoot, ".pi", "harness", "specs");
+	const runId = process.env.HARNESS_RUN_ID?.trim() ?? "";
+	const runDirEnv = process.env.HARNESS_RUN_DIR?.trim();
+	const agentId = process.env.HARNESS_AGENT_ID?.trim() ?? "";
+	return { projectRoot, specsDir, runId, runDirEnv, agentId };
+}
+
+function isSubprocessHarness(): boolean {
+	return (
+		process.env.PI_HARNESS_SUBPROCESS === "1" &&
+		Boolean(process.env.HARNESS_RUN_ID?.trim())
+	);
+}
+
+export default function harnessSubagentSubmit(pi: ExtensionAPI) {
+	if (!claimExtensionLoad("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;
+	}
+
+	const _packageRoot = getHarnessPackageRoot(MODULE_URL);
+
+	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,
+				reason:
+					"harness-subagent-submit: submit_* tools are only available in harness subagent subprocesses.",
+			};
+		}
+		const { agentId } = resolveRunContext();
+		if (!agentId) {
+			return {
+				block: true,
+				reason:
+					"harness-subagent-submit: HARNESS_AGENT_ID is required for submit tools.",
+			};
+		}
+		const decision = evaluateHarnessSubagentToolCall(
+			event.toolName,
+			event.input as Record<string, unknown>,
+			agentId,
+		);
+		if (decision.action === "block") {
+			return { block: true, reason: decision.reason };
+		}
+		return undefined;
+	});
+
+	for (const spec of SUBMIT_TOOL_SPECS) {
+		pi.registerTool({
+			name: spec.toolName,
+			label: spec.toolName.replace(/^submit_/, "Submit "),
+			description: `Terminal harness artifact submit for ${spec.agents.join(", ")}. Call once with the full schema document before ending the turn.`,
+			parameters: DocumentSchema,
+			async execute(_id, params, _signal, _onUpdate, _ctx) {
+				if (!isSubprocessHarness()) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: "submit tools require PI_HARNESS_SUBPROCESS and HARNESS_RUN_ID",
+							},
+						],
+						details: {},
+						isError: true,
+					};
+				}
+				const { projectRoot, specsDir, runId, runDirEnv, agentId } =
+					resolveRunContext();
+				if (!spec.agents.includes(agentId)) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `${spec.toolName} is not allowed for agent ${agentId}`,
+							},
+						],
+						details: { agentId, tool: spec.toolName },
+						isError: true,
+					};
+				}
+				const document = (params as { document?: Record<string, unknown> })
+					.document;
+				if (!document || typeof document !== "object") {
+					return {
+						content: [{ type: "text", text: "document object is required" }],
+						details: {},
+						isError: true,
+					};
+				}
+				const result = await executeSubmitPipeline({
+					projectRoot,
+					specsDir,
+					spec,
+					agentId,
+					document,
+					runId,
+					runDirEnv,
+				});
+				if (!result.ok) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Validation failed:\n${(result.validation_errors ?? []).join("\n")}`,
+							},
+						],
+						isError: true,
+						details: result,
+					};
+				}
+				const lines = [`ok: wrote ${result.artifact_path}`];
+				if (result.lane_result?.messenger_posted) {
+					lines.push("messenger updated");
+				}
+				if (result.human_required) {
+					lines.push("human_required: parent must call ask_user");
+				}
+				return {
+					content: [{ type: "text", text: lines.join("\n") }],
+					details: result as unknown,
+				};
+			},
+		});
+	}
+}
+
+/** Absolute path to the subprocess submit extension (Option A). */
+export function harnessSubagentSubmitExtensionPath(
+	packageRoot: string,
+): string {
+	return join(packageRoot, ".pi", "extensions", "harness-subagent-submit.ts");
+}