ultimate-pi 0.18.0 → 0.19.0

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

@@ -5,10 +5,20 @@
  * in before_agent_start so trace-recorder reuses it on agent_start.
  */
 
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import {
+	mkdir,
+	readdir,
+	readFile,
+	rename,
+	stat,
+	writeFile,
+} from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
+import { allowsAgentTool } from "../lib/agents-policy.mjs";
+import { claimHarnessGovernanceLoad } from "../lib/extension-load-guard.js";
+import { getHarnessPackageRoot } from "../lib/harness-paths.js";
 import {
 	canonicalPlanPath,
 	claimRunOwnership,
@@ -60,19 +70,16 @@ import {
 	validatePlanOverridePath,
 	validatePlanPacket,
 } from "../lib/harness-run-context.js";
+import { blockRunContextMessage } from "../lib/harness-run-context-responses.js";
+import { isSubmitToolName } from "../lib/harness-subagent-submit-registry.js";
+import { bootstrapHarnessSubprocessFromEnv } from "../lib/harness-subprocess-bootstrap.js";
 import {
 	normalizeHarnessYamlContent,
 	parseStructuredDocument,
 	writeYamlFile,
 } from "../lib/harness-yaml.js";
-import { claimExtensionLoad } from "./lib/extension-load-guard.js";
-import {
-	evaluateHarnessSubagentToolCall,
-	isSubmitToolName,
-} from "./lib/harness-subagent-policy.js";
-import { bootstrapHarnessSubprocessFromEnv } from "./lib/harness-subprocess-bootstrap.js";
-import { isReviewRoundArtifactPath } from "./lib/plan-debate-gate.js";
-import { isReviewRoundYamlWriteAllowed } from "./lib/plan-debate-write-guard.js";
+import { isReviewRoundArtifactPath } from "../lib/plan-debate-gate.js";
+import { isReviewRoundYamlWriteAllowed } from "../lib/plan-debate-write-guard.js";
 
 // @ts-expect-error pi extensions run as ESM
 const MODULE_URL = import.meta.url;
@@ -96,6 +103,136 @@ function persistContext(pi: ExtensionAPI, ctx: HarnessRunContext): void {
 	pi.events.emit("harness-run-context:updated", { run_id: ctx.run_id });
 }
 
+const PLAN_REVISION_ARTIFACT_FILES = new Set([
+	"planning-context.yaml",
+	"decomposition.yaml",
+	"hypothesis.yaml",
+	"implementation-research.yaml",
+	"stack.yaml",
+	"execution-plan-draft.yaml",
+	"plan-phase-status.yaml",
+	"plan-phase-waiver.yaml",
+	"sentrux-manifest-proposal.yaml",
+]);
+
+const PLAN_REVISION_ARTIFACT_PREFIXES = [
+	"hypothesis-validation-r",
+	"review-round-r",
+	"plan-evaluator-r",
+	"plan-adversary-r",
+	"sprint-contract-audit-r",
+	"adversary-brief-r",
+] as const;
+
+async function moveIfExists(from: string, to: string): Promise<boolean> {
+	try {
+		await stat(from);
+	} catch {
+		return false;
+	}
+	await mkdir(dirname(to), { recursive: true });
+	await rename(from, to);
+	return true;
+}
+
+function isPlanRevisionArtifactFile(name: string): boolean {
+	if (PLAN_REVISION_ARTIFACT_FILES.has(name)) return true;
+	if (name === "review-round-consolidated.yaml") return true;
+	return PLAN_REVISION_ARTIFACT_PREFIXES.some((prefix) =>
+		name.startsWith(prefix),
+	);
+}
+
+export async function archivePlanRevisionArtifacts(input: {
+	projectRoot: string;
+	runId: string;
+	reason: string;
+	recordedAt?: string;
+}): Promise<{ archiveDir: string; moved: string[] }> {
+	const recordedAt = input.recordedAt ?? nowIso();
+	const revisionId = recordedAt.replace(/[:.]/g, "-");
+	const runDir = join(input.projectRoot, ".pi", "harness", "runs", input.runId);
+	const artifactsDir = join(runDir, "artifacts");
+	const archiveDir = join(artifactsDir, "revisions", revisionId);
+	const moved: string[] = [];
+
+	async function archiveRel(rel: string): Promise<void> {
+		const ok = await moveIfExists(join(runDir, rel), join(archiveDir, rel));
+		if (ok) moved.push(rel);
+	}
+
+	await archiveRel("plan-packet.yaml");
+	await archiveRel("plan-review.md");
+	await archiveRel("research-brief.yaml");
+	await archiveRel("debate-messenger");
+
+	try {
+		const names = await readdir(artifactsDir);
+		for (const name of names) {
+			if (!isPlanRevisionArtifactFile(name)) continue;
+			await archiveRel(join("artifacts", name));
+		}
+	} catch {
+		// No artifacts yet.
+	}
+
+	const debateRel = join(
+		".pi",
+		"harness",
+		"debates",
+		`plan-${input.runId}.jsonl`,
+	);
+	const debateArchived = await moveIfExists(
+		join(input.projectRoot, debateRel),
+		join(archiveDir, "debates", basename(debateRel)),
+	);
+	if (debateArchived) moved.push(debateRel);
+
+	if (moved.length > 0) {
+		await mkdir(archiveDir, { recursive: true });
+		await writeFile(
+			join(archiveDir, "revision-reset.json"),
+			`${JSON.stringify(
+				{
+					schema_version: "1.0.0",
+					run_id: input.runId,
+					reason: input.reason,
+					recorded_at: recordedAt,
+					moved,
+				},
+				null,
+				2,
+			)}\n`,
+			"utf-8",
+		);
+	}
+
+	return { archiveDir, moved };
+}
+
+function shouldArchiveForPlanRevise(input: {
+	command: string;
+	mode: "create" | "revise" | null;
+	runCtx: HarnessRunContext;
+	reviewOutcome: Awaited<ReturnType<typeof readReviewOutcomeFromRun>>;
+	userPrompt: string;
+}): boolean {
+	if (input.command !== "harness-plan" && input.command !== "harness-auto") {
+		return false;
+	}
+	if (input.mode !== "revise") return false;
+	const next = (input.runCtx.next_recommended_command ?? "").toLowerCase();
+	const prompt = input.userPrompt.toLowerCase();
+	return (
+		input.reviewOutcome?.remediation_class === "plan_gap" ||
+		next.includes("/harness-plan") ||
+		next.includes("revise") ||
+		prompt.includes("--mode revise") ||
+		prompt.includes("--mode=revise") ||
+		prompt.includes("mode: revise")
+	);
+}
+
 function syncPolicyFromRunContext(
 	pi: ExtensionAPI,
 	entries: unknown[],
@@ -236,10 +373,7 @@ async function offerCrossSessionResume(
 		hasUI: boolean;
 		sessionManager: { getEntries(): unknown[] };
 		ui: {
-			notify(
-				message: string,
-				type?: "info" | "warning" | "error",
-			): void;
+			notify(message: string, type?: "info" | "warning" | "error"): void;
 		};
 	},
 ): Promise<void> {
@@ -271,182 +405,154 @@ async function offerCrossSessionResume(
 	});
 }
 
-export default function harnessRunContext(pi: ExtensionAPI) {
-	if (!claimExtensionLoad("harness-run-context", MODULE_URL)) return;
-	let activeCtx: HarnessRunContext | null = null;
+async function applyAbortSignal(input: {
+	pi: ExtensionAPI;
+	activeCtx: HarnessRunContext | null;
+	sessionId: string;
+	projectRoot: string;
+	entries: unknown[];
+	userPrompt: string;
+}): Promise<HarnessRunContext | null> {
+	if (!input.userPrompt.toLowerCase().includes("harness-abort")) {
+		return input.activeCtx;
+	}
+	const nextCtx =
+		input.activeCtx ??
+		(await hydrateFromDisk(input.sessionId, input.projectRoot, input.entries));
+	if (!nextCtx) return nextCtx;
+	nextCtx.status = "aborted";
+	nextCtx.plan_ready = false;
+	nextCtx.last_outcome = "aborted";
+	nextCtx.last_completed_step = "abort";
+	nextCtx.next_recommended_command = nextCtx.task_summary
+		? `/harness-plan "${nextCtx.task_summary}"`
+		: '/harness-plan "<task>"';
+	persistContext(input.pi, nextCtx);
+	return nextCtx;
+}
 
-	pi.on("session_start", async (_event, ctx) => {
-		const entries = getEntries(ctx);
-		activeCtx = hydrateFromSession(entries);
-		const booted = await bootstrapHarnessSubprocessFromEnv(pi, ctx);
-		if (booted) activeCtx = booted;
-		if (!booted) await offerCrossSessionResume(pi, ctx);
-	});
+async function maybeHandleClarificationFollowUp(input: {
+	pi: ExtensionAPI;
+	activeCtx: HarnessRunContext;
+	entries: unknown[];
+	systemPrompt: string;
+}) {
+	input.activeCtx.phase = "plan";
+	input.activeCtx.last_outcome = "needs_clarification";
+	const packet = input.activeCtx.plan_packet_path
+		? await readPlanPacketFromPath(input.activeCtx.plan_packet_path)
+		: null;
+	const planPath = input.activeCtx.plan_packet_path;
+	const summary =
+		packet && planPath
+			? planPacketSummary(packet, planPath, "needs_clarification")
+			: null;
+	syncPolicyFromPlan(
+		input.pi,
+		input.entries,
+		input.activeCtx.plan_id ?? "plan-pending",
+		"plan",
+		false,
+	);
+	persistContext(input.pi, input.activeCtx);
+	return {
+		systemPrompt: `${input.systemPrompt}\n\n${formatPlanContextBlock(input.activeCtx)}\n\n${formatActivePlanBlock(input.activeCtx, "revise", summary)}\n\nReply with clarification answers; the harness will treat this as plan amend.`,
+	};
+}
 
-	pi.on("input", async (event) => {
-		if (event.source === "extension") {
-			return { action: "continue" as const };
-		}
-		const parsed = parseHarnessSlashInput(event.text);
-		if (!parsed) {
-			return { action: "continue" as const };
-		}
-		appendHarnessTurn(pi, {
-			schema_version: "1.0.0",
-			command: parsed.command,
-			args: parsed.args,
-			source: "slash",
-			invoked_at: nowIso(),
-		});
-		return { action: "continue" as const };
+function startFreshPlanAttempt(input: {
+	pi: ExtensionAPI;
+	activeCtx: HarnessRunContext;
+	command: string;
+	turn: HarnessTurnEntry | null;
+}): void {
+	input.activeCtx.plan_ready = false;
+	input.activeCtx.phase = "plan";
+	input.activeCtx.status = "active";
+	input.pi.appendEntry("harness-plan-attempt", {
+		run_id: input.activeCtx.run_id,
+		command: input.command,
+		started_at: input.turn?.invoked_at ?? nowIso(),
 	});
+}
 
-	pi.on("before_agent_start", async (event, ctx) => {
-		const sessionId = ctx.sessionManager.getSessionId();
-		const projectRoot = process.cwd();
-		const entries = getEntries(ctx);
-		const userPrompt = userVisiblePromptSlice(event.prompt);
-		const turn = getLatestHarnessTurn(entries);
-		const parsed = turn
-			? { command: turn.command, args: turn.args }
-			: parseHarnessSlashInput(userPrompt);
-		const harnessTurn =
-			Boolean(turn) || Boolean(parsed) || needsClarificationFollowUp(activeCtx);
-
-		if (
-			userPrompt.toLowerCase().includes("/harness-abort") ||
-			userPrompt.toLowerCase().includes("harness-abort")
-		) {
-			if (!activeCtx) {
-				activeCtx = await hydrateFromDisk(sessionId, projectRoot, entries);
-			}
-			if (activeCtx) {
-				activeCtx.status = "aborted";
-				activeCtx.plan_ready = false;
-				activeCtx.last_outcome = "aborted";
-				activeCtx.last_completed_step = "abort";
-				activeCtx.next_recommended_command = activeCtx.task_summary
-					? `/harness-plan "${activeCtx.task_summary}"`
-					: '/harness-plan "<task>"';
-				persistContext(pi, activeCtx);
-			}
-		}
-
-		if (!harnessTurn) {
-			return undefined;
-		}
-
-		if (!activeCtx) {
-			activeCtx = await hydrateFromDisk(sessionId, projectRoot, entries);
-		}
-
-		const policyPhase =
-			inferHarnessPhase(entries, userPrompt) ??
-			getLatestPolicyPhase(entries) ??
-			activeCtx?.phase ??
-			"plan";
-		const driftActive = driftGateActive(entries);
-
-		// Plain-language follow-up after needs_clarification
-		if (!parsed && needsClarificationFollowUp(activeCtx) && activeCtx) {
-			activeCtx.phase = "plan";
-			activeCtx.last_outcome = "needs_clarification";
-			const packet = activeCtx.plan_packet_path
-				? await readPlanPacketFromPath(activeCtx.plan_packet_path)
-				: null;
-			const planPath = activeCtx.plan_packet_path;
-			const summary =
-				packet && planPath
-					? planPacketSummary(packet, planPath, "needs_clarification")
-					: null;
-			syncPolicyFromPlan(
-				pi,
-				entries,
-				activeCtx.plan_id ?? "plan-pending",
-				"plan",
-				false,
-			);
-			persistContext(pi, activeCtx);
-			return {
-				systemPrompt: `${event.systemPrompt}\n\n${formatPlanContextBlock(activeCtx)}\n\n${formatActivePlanBlock(activeCtx, "revise", summary)}\n\nReply with clarification answers; the harness will treat this as plan amend.`,
-			};
-		}
-
-		if (!parsed) return undefined;
-
-		const { command, args } = parsed;
-
-		if (
-			!isHarnessBootstrapPrompt(userPrompt) &&
-			!hasHarnessAbortSignal(userPrompt)
-		) {
-			const policyBlock = getPolicyTransitionBlock(userPrompt, entries);
-			if (policyBlock.blocked) {
-				return {
-					message: {
-						customType: "harness-run-context-block",
-						display: true,
-						content:
-							policyBlock.message ?? "Harness command blocked by policy phase.",
-					},
-				};
-			}
-		}
+function contextPrompt(systemPrompt: string, activeCtx: HarnessRunContext) {
+	return {
+		systemPrompt: `${systemPrompt}\n\n${formatPlanContextBlock(activeCtx)}`,
+	};
+}
 
-		if (command === "harness-new-run") {
-			if (activeCtx?.status === "active") {
-				activeCtx.status = "aborted";
-				activeCtx.plan_ready = false;
-				activeCtx.last_outcome = "abandoned";
-				persistContext(pi, activeCtx);
-			}
-			const task = extractTaskSummary(args, userPrompt);
-			activeCtx = createFreshRunContext(sessionId, projectRoot, task);
-			persistContext(pi, activeCtx);
-			return {
-				systemPrompt: `${event.systemPrompt}\n\n${formatPlanContextBlock(activeCtx)}\n\n${formatActivePlanBlock(activeCtx, "create")}`,
-			};
-		}
+function createNewRunContextForCommand(input: {
+	pi: ExtensionAPI;
+	activeCtx: HarnessRunContext | null;
+	sessionId: string;
+	projectRoot: string;
+	args: string;
+	userPrompt: string;
+	systemPrompt: string;
+}) {
+	if (input.activeCtx?.status === "active") {
+		input.activeCtx.status = "aborted";
+		input.activeCtx.plan_ready = false;
+		input.activeCtx.last_outcome = "abandoned";
+		persistContext(input.pi, input.activeCtx);
+	}
+	const task = extractTaskSummary(input.args, input.userPrompt);
+	const activeCtx = createFreshRunContext(
+		input.sessionId,
+		input.projectRoot,
+		task,
+	);
+	persistContext(input.pi, activeCtx);
+	return {
+		activeCtx,
+		response: {
+			systemPrompt: `${input.systemPrompt}\n\n${formatPlanContextBlock(activeCtx)}\n\n${formatActivePlanBlock(activeCtx, "create")}`,
+		},
+	};
+}
 
-		if (command === "harness-use-run") {
-			const parsed = parseHarnessUseRunArgs(args);
-			if (!parsed.runId) {
-				return {
-					message: {
-						customType: "harness-run-context-block",
-						display: true,
-						content: "Usage: /harness-use-run <run-id> [--claim] [--readonly]",
-					},
-				};
-			}
-			const disk = await loadRunContextFromDisk(parsed.runId, projectRoot);
-			if (!disk) {
-				return {
-					message: {
-						customType: "harness-run-context-block",
-						display: true,
-						content: `No run directory for ${parsed.runId}. Check .pi/harness/runs/.`,
-					},
-				};
-			}
-			activeCtx = {
-				...disk,
-				pi_session_id: sessionId,
-				turn_override_run_id: parsed.runId,
-			};
-			if (parsed.claim) {
-				activeCtx = claimRunOwnership(activeCtx, sessionId);
-			}
-			const statuses = await resolveCompletionStatuses(
-				getEntries(ctx),
-				activeCtx.run_id,
-				projectRoot,
-			);
-			if (activeCtx.owner_pi_session_id !== sessionId && !parsed.claim) {
-				activeCtx.next_recommended_command =
-					"Read-only: use /harness-use-run <run-id> --claim to take ownership, or /harness-new-run.";
-			} else {
-				activeCtx.next_recommended_command = nextStepAfterOutcome({
+async function bindExistingRunForCommand(input: {
+	pi: ExtensionAPI;
+	sessionId: string;
+	projectRoot: string;
+	entries: unknown[];
+	args: string;
+	systemPrompt: string;
+}) {
+	const parsed = parseHarnessUseRunArgs(input.args);
+	if (!parsed.runId) {
+		return {
+			activeCtx: null,
+			response: blockRunContextMessage(
+				"Usage: /harness-use-run <run-id> [--claim] [--readonly]",
+			),
+		};
+	}
+	const disk = await loadRunContextFromDisk(parsed.runId, input.projectRoot);
+	if (!disk) {
+		return {
+			activeCtx: null,
+			response: blockRunContextMessage(
+				`No run directory for ${parsed.runId}. Check .pi/harness/runs/.`,
+			),
+		};
+	}
+	let activeCtx: HarnessRunContext = {
+		...disk,
+		pi_session_id: input.sessionId,
+		turn_override_run_id: parsed.runId,
+	};
+	if (parsed.claim) activeCtx = claimRunOwnership(activeCtx, input.sessionId);
+	const statuses = await resolveCompletionStatuses(
+		input.entries,
+		activeCtx.run_id,
+		input.projectRoot,
+	);
+	activeCtx.next_recommended_command =
+		activeCtx.owner_pi_session_id !== input.sessionId && !parsed.claim
+			? "Read-only: use /harness-use-run <run-id> --claim to take ownership, or /harness-new-run."
+			: nextStepAfterOutcome({
 					phase: activeCtx.phase,
 					planStatus: activeCtx.plan_ready ? "ready" : null,
 					lastCompletedStep: activeCtx.last_completed_step,
@@ -456,436 +562,462 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 					adversaryComplete: statuses.adversaryComplete,
 					aborted: activeCtx.status === "aborted",
 				});
-			}
-			activeCtx.updated_at = nowIso();
-			persistContext(pi, activeCtx);
-			syncPolicyFromRunContext(pi, getEntries(ctx), activeCtx);
-			return {
-				systemPrompt: `${event.systemPrompt}\n\n${formatPlanContextBlock(activeCtx)}`,
-			};
-		}
-
-		if (command === "harness-run-status") {
-			return undefined;
-		}
-
-		if (
-			command === "harness-plan" &&
-			activeCtx &&
-			isNewTaskPlanBlocked(activeCtx, userPrompt) &&
-			!isAmendPlanAllowed(activeCtx, userPrompt, driftActive)
-		) {
-			return {
-				message: {
-					customType: "harness-run-context-block",
-					display: true,
-					content:
-						"Active harness run in progress. Use /harness-abort or /harness-new-run before starting a new task plan.",
-				},
-			};
-		}
+	activeCtx.updated_at = nowIso();
+	persistContext(input.pi, activeCtx);
+	syncPolicyFromRunContext(input.pi, input.entries, activeCtx);
+	return { activeCtx, response: contextPrompt(input.systemPrompt, activeCtx) };
+}
 
-		const resolved = resolveArgsForCommand(command, args, activeCtx);
-		if (resolved.overrideRun && resolved.runId) {
-			const disk = await loadRunContextFromDisk(resolved.runId, projectRoot);
-			if (disk) activeCtx = { ...disk, turn_override_run_id: resolved.runId };
-		}
+type ActiveContextAccess = {
+	get(): HarnessRunContext | null;
+	set(ctx: HarnessRunContext | null): void;
+};
 
-		if (
-			command === "harness-plan" ||
-			command === "harness-auto" ||
-			(!activeCtx && command !== "harness-abort")
-		) {
-			if (
-				!activeCtx ||
-				!shouldReuseHarnessRunId(userPrompt, activeCtx, command)
-			) {
-				const task = extractTaskSummary(args, userPrompt);
-				activeCtx = createFreshRunContext(sessionId, projectRoot, task);
-			}
-			activeCtx.plan_ready = false;
-			activeCtx.phase = "plan";
-			activeCtx.status = "active";
-			if (command === "harness-plan") {
-				const task = extractTaskSummary(args, userPrompt);
-				if (task) activeCtx.task_summary = task;
-			}
-			if (turn) {
-				pi.appendEntry("harness-plan-attempt", {
-					run_id: activeCtx.run_id,
-					command,
-					started_at: turn.invoked_at,
-				});
-			} else {
-				pi.appendEntry("harness-plan-attempt", {
-					run_id: activeCtx.run_id,
-					command,
-					started_at: nowIso(),
-				});
+function registerHarnessRunStatusCommand(
+	pi: ExtensionAPI,
+	active: ActiveContextAccess,
+): void {
+	pi.registerCommand("harness-run-status", {
+		description:
+			"Show harness phase, plan readiness, and next command (no run id)",
+		handler: async (_args, ctx) => {
+			const sessionId = ctx.sessionManager.getSessionId();
+			const projectRoot = process.cwd();
+			const entries = getEntries(ctx);
+			let ctxState = getLatestRunContext(entries) ?? active.get();
+			if (!ctxState)
+				ctxState = await hydrateFromDisk(sessionId, projectRoot, entries);
+			if (!ctxState) {
+				const msg = 'No active harness run. Start with /harness-plan "<task>".';
+				if (ctx.hasUI) ctx.ui.notify(msg, "warning");
+				return;
 			}
-		} else if (
-			activeCtx &&
-			shouldReuseHarnessRunId(userPrompt, activeCtx, command)
-		) {
-			activeCtx.turn_override_run_id = resolved.overrideRun
-				? resolved.runId
-				: null;
-		} else if (!activeCtx) {
-			const pointer = await loadProjectActiveRun(projectRoot);
-			if (pointer) {
-				if (isStaleActiveRunPointer(pointer, projectRoot)) {
-					const crossSessionCmd = new Set([
-						"harness-eval",
-						"harness-review",
-						"harness-steer",
-						"harness-critic",
-						"harness-trace",
-						"harness-incident",
-					]);
-					if (crossSessionCmd.has(command)) {
-						return {
-							message: {
-								customType: "harness-run-context-block",
-								display: true,
-								content:
-									'Project active-run pointer is stale or from another workspace. Run /harness-plan "<task>" or /harness-use-run <run-id> for recovery.',
-							},
-						};
-					}
-				} else {
-					const disk = await loadRunContextFromDisk(
-						pointer.run_id,
-						projectRoot,
-					);
-					if (disk) activeCtx = disk;
+			let summary: PlanPacketSummary | null = null;
+			for (let i = entries.length - 1; i >= 0; i--) {
+				const entry = entries[i] as SessionEntryLike;
+				if (
+					entry.type === "custom" &&
+					entry.customType === "harness-plan-packet"
+				) {
+					summary = entry.data as PlanPacketSummary;
+					break;
 				}
 			}
-		}
-
-		if (!activeCtx) {
-			return {
-				message: {
-					customType: "harness-run-context-block",
+			const text = [
+				"Harness run status:",
+				`  phase: ${ctxState.phase}`,
+				`  status: ${ctxState.status}`,
+				`  plan_ready: ${ctxState.plan_ready}`,
+				`  plan_id: ${ctxState.plan_id ?? "(none)"}`,
+				summary
+					? `  scope: ${summary.scope_one_liner}`
+					: "  scope: (no plan summary yet)",
+				`  last_step: ${ctxState.last_completed_step ?? "(none)"}`,
+				`  last_outcome: ${ctxState.last_outcome ?? "(none)"}`,
+				`  next: ${ctxState.next_recommended_command ?? "/harness-run-status"}`,
+			].join("\n");
+			if (ctx.hasUI) ctx.ui.notify(text, "info");
+			else
+				pi.sendMessage({
+					customType: "harness-run-status",
+					content: text,
 					display: true,
-					content:
-						'No active harness run. Run /harness-plan "<task>" first, or /harness-use-run <run-id> for recovery.',
-				},
-			};
-		}
-
-		activeCtx.phase = policyPhase;
-		activeCtx.updated_at = new Date().toISOString();
-		activeCtx.pi_session_id = sessionId;
-
-		if (
-			shouldAutoClaimHarnessRun(command, args) &&
-			activeCtx.owner_pi_session_id !== sessionId
-		) {
-			activeCtx = claimRunOwnership(activeCtx, sessionId);
-		}
+				});
+		},
+	});
+}
 
-		if (resolved.planPath && resolved.runId) {
-			const check = validatePlanOverridePath(
-				resolved.planPath,
-				resolved.runId,
-				projectRoot,
-			);
-			if (!check.ok) {
-				return {
-					message: {
-						customType: "harness-run-context-block",
-						display: true,
-						content: check.reason ?? "Invalid --plan override",
-					},
-				};
+function registerHarnessNewRunCommand(
+	pi: ExtensionAPI,
+	active: ActiveContextAccess,
+): void {
+	pi.registerCommand("harness-new-run", {
+		description: "Abandon current active run and start a fresh harness run",
+		handler: async (args, ctx) => {
+			const sessionId = ctx.sessionManager.getSessionId();
+			const projectRoot = process.cwd();
+			const current = active.get();
+			if (current?.status === "active") {
+				current.status = "aborted";
+				current.plan_ready = false;
+				persistContext(pi, current);
 			}
-			activeCtx.plan_packet_path = resolved.planPath;
-		}
-
-		if (command === "harness-run" && !activeCtx.plan_ready) {
-			return {
-				message: {
-					customType: "harness-run-context-block",
-					display: true,
-					content: "Plan not ready. Run /harness-plan first.",
-				},
-			};
-		}
-
-		if (
-			command === "harness-run" &&
-			activeCtx.plan_ready &&
-			activeCtx.last_completed_step === "execute" &&
-			activeCtx.last_outcome === "completed"
-		) {
-			return {
-				message: {
-					customType: "harness-run-context-block",
-					display: true,
-					content:
-						"Execute already completed for this run. Next: /harness-review (same session), or /harness-abort to replan.",
-				},
-			};
-		}
-
-		let planSummary: PlanPacketSummary | null = null;
-		let planPacketForSpawn: Awaited<ReturnType<typeof readPlanPacketFromPath>> =
-			null;
-		if (activeCtx.plan_packet_path) {
-			planPacketForSpawn = await readPlanPacketFromPath(
-				activeCtx.plan_packet_path,
+			const next = createFreshRunContext(
+				sessionId,
+				projectRoot,
+				args.trim() || null,
 			);
-			if (planPacketForSpawn) {
-				planSummary = planPacketSummary(
-					planPacketForSpawn,
-					activeCtx.plan_packet_path,
-					activeCtx.plan_ready ? "ready" : "draft",
+			active.set(next);
+			persistContext(pi, next);
+			if (ctx.hasUI) {
+				ctx.ui.notify(
+					'New harness run allocated. Next: /harness-plan "<your task>"',
+					"info",
 				);
-				activeCtx.plan_id = planPacketForSpawn.plan_id ?? activeCtx.plan_id;
 			}
-		}
+		},
+	});
+}
 
-		let contextSpawnOpts:
-			| Parameters<typeof formatPlanContextBlock>[1]
-			| undefined;
-		if (command === "harness-run" && planPacketForSpawn) {
-			const criticalIds =
-				criticalPathWorkItemIdsFromPlanPacket(planPacketForSpawn);
-			contextSpawnOpts = {
-				mode: "execute",
-				critical_path_work_item_ids: criticalIds,
-			};
-		}
-
-		let activePlanBlock = "";
-		if (command === "harness-plan" || command === "harness-auto") {
-			const mode =
-				activeCtx.plan_ready || activeCtx.status === "aborted"
-					? "revise"
-					: "create";
-			activePlanBlock = formatActivePlanBlock(activeCtx, mode, planSummary);
-		} else if (command === "harness-run") {
-			activePlanBlock = formatActivePlanBlock(
-				activeCtx,
-				"execute",
-				planSummary,
+function registerHarnessPlanCommitCommand(
+	pi: ExtensionAPI,
+	active: ActiveContextAccess,
+): void {
+	pi.registerCommand("harness-plan-commit", {
+		description:
+			"Write approved plan-packet.yaml to the active run (requires harness-plan-approval)",
+		handler: async (args, ctx) => {
+			const projectRoot = process.cwd();
+			const entries = getEntries(ctx);
+			let runCtx = getLatestRunContext(entries) ?? active.get();
+			if (!runCtx) {
+				runCtx = await hydrateFromDisk(
+					ctx.sessionManager.getSessionId(),
+					projectRoot,
+					entries,
+				);
+			}
+			if (!runCtx?.plan_packet_path) {
+				if (ctx.hasUI)
+					ctx.ui.notify(
+						"No active harness run. Run /harness-plan first.",
+						"warning",
+					);
+				return;
+			}
+			if (
+				!hasPlanUserApproval(entries, {
+					sincePlanCommand: true,
+					planId: runCtx.plan_id,
+				})
+			) {
+				if (ctx.hasUI)
+					ctx.ui.notify(
+						"Plan commit blocked: no user approval recorded. Approve via approve_plan in this session first.",
+						"warning",
+					);
+				return;
+			}
+			const pathArg = args.trim();
+			const packetPath = pathArg || runCtx.plan_packet_path;
+			const packet = await readPlanPacketFromPath(packetPath);
+			const validation = validatePlanPacket(packet);
+			if (!validation.valid || !packet) {
+				const msg = !packet
+					? "Plan packet file missing or unreadable."
+					: `Invalid plan packet: ${validation.errors.join("; ")}`;
+				if (ctx.hasUI) ctx.ui.notify(msg, "error");
+				return;
+			}
+			const target = runCtx.plan_packet_path;
+			if (!target) {
+				if (ctx.hasUI)
+					ctx.ui.notify("No plan_packet_path on active run.", "error");
+				return;
+			}
+			if (pathArg && pathArg !== target) {
+				await writeFile(target, await readFile(pathArg, "utf-8"), "utf-8");
+			}
+			runCtx.plan_id = packet.plan_id ?? runCtx.plan_id;
+			runCtx.plan_ready = true;
+			runCtx.phase = "plan";
+			runCtx.last_completed_step = "plan";
+			runCtx.last_outcome = "ready";
+			runCtx.next_recommended_command = "/harness-run";
+			runCtx.updated_at = nowIso();
+			active.set(runCtx);
+			persistContext(pi, runCtx);
+			syncPolicyFromPlan(
+				pi,
+				entries,
+				runCtx.plan_id ?? packet.plan_id ?? "plan-pending",
+				"plan",
+				true,
 			);
-		} else if (command === "harness-steer") {
-			activePlanBlock = formatActivePlanBlock(
-				activeCtx,
-				"execute",
-				planSummary,
+			pi.appendEntry(
+				"harness-plan-packet",
+				planPacketSummary(packet, target, "ready"),
 			);
-			contextSpawnOpts = {
-				mode: "repair",
-				repair_brief_path: "artifacts/repair-brief.yaml",
-			};
-		} else if (
-			command === "harness-eval" ||
-			command === "harness-review" ||
-			command === "harness-critic"
-		) {
-			activePlanBlock = formatActivePlanBlock(activeCtx, "read", planSummary);
-		}
-
-		persistContext(pi, activeCtx);
-
-		return {
-			systemPrompt: `${event.systemPrompt}\n\n${formatPlanContextBlock(activeCtx, contextSpawnOpts)}${activePlanBlock ? `\n\n${activePlanBlock}` : ""}`,
-		};
+			if (ctx.hasUI) ctx.ui.notify(`Plan committed: ${target}`, "info");
+		},
 	});
+}
 
-	pi.on("agent_end", async (_event, ctx) => {
-		const projectRoot = process.cwd();
-		const entries = getEntries(ctx);
-		if (!activeCtx) {
-			activeCtx = getLatestRunContext(entries);
-		}
-		if (!activeCtx) return;
-
-		const userEntries = entries.filter((e) => {
-			const entry = e as { type?: string; message?: { role?: string } };
-			return entry.type === "message" && entry.message?.role === "user";
-		});
-		const lastUser = userEntries[userEntries.length - 1] as
-			| { message?: { content?: string | unknown[] } }
-			| undefined;
-		let lastPrompt = "";
-		if (lastUser?.message?.content) {
-			lastPrompt =
-				typeof lastUser.message.content === "string"
-					? lastUser.message.content
-					: "";
-		}
-		const lastTurn = getLatestHarnessTurn(entries);
-		const parsed = lastTurn
-			? { command: lastTurn.command, args: lastTurn.args }
-			: parseHarnessSlashInput(userVisiblePromptSlice(lastPrompt));
-		if (!parsed && !needsClarificationFollowUp(activeCtx)) return;
-
-		if (parsed?.command === "harness-abort") {
-			activeCtx.status = "aborted";
-			activeCtx.plan_ready = false;
-			activeCtx.last_outcome = "aborted";
-			activeCtx.last_completed_step = "abort";
-			activeCtx.next_recommended_command = activeCtx.task_summary
-				? `/harness-plan "${activeCtx.task_summary}"`
-				: '/harness-plan "<task>"';
-			persistContext(pi, activeCtx);
-			const msg = `Harness aborted. Next: ${activeCtx.next_recommended_command}`;
-			if (ctx.hasUI) ctx.ui.notify(msg, "warning");
-			else
-				pi.sendMessage({
-					customType: "harness-step-handoff",
-					content: msg,
-					display: true,
-				});
-			return;
-		}
-
-		let planReady = activeCtx.plan_ready;
-		if (
-			(parsed?.command === "harness-plan" ||
-				parsed?.command === "harness-auto") &&
-			activeCtx.plan_packet_path
-		) {
-			const packet = await readPlanPacketFromPath(activeCtx.plan_packet_path);
-			const validation = validatePlanPacket(packet);
-			const approved = hasPlanUserApproval(entries, {
-				sincePlanCommand: true,
-				planId: packet?.plan_id ?? null,
-			});
-			planReady = validation.valid && approved;
-			if (validation.valid && !approved) {
-				activeCtx.last_outcome = "needs_clarification";
-				activeCtx.last_completed_step = "plan";
-				const msg =
-					"Plan file exists but user approval was not recorded. Planner must call approve_plan (or bridged ask_user Approve) before writing plan-packet.yaml.";
-				if (ctx.hasUI) ctx.ui.notify(msg, "warning");
-				else
-					pi.sendMessage({
-						customType: "harness-plan-packet",
-						content: msg,
-						display: true,
-					});
-			} else if (planReady && packet?.plan_id) {
-				activeCtx.plan_id = packet.plan_id;
-				syncPolicyFromPlan(pi, entries, packet.plan_id, "plan", true);
-				const summary = planPacketSummary(packet, activeCtx.plan_packet_path);
-				pi.appendEntry("harness-plan-packet", summary);
-				activeCtx.last_completed_step = "plan";
-				activeCtx.last_outcome = summary.plan_status;
-			} else if (!validation.valid) {
-				activeCtx.last_outcome = "needs_clarification";
-				activeCtx.last_completed_step = "plan";
+function registerHarnessUseRunCommand(
+	pi: ExtensionAPI,
+	active: ActiveContextAccess,
+): void {
+	pi.registerCommand("harness-use-run", {
+		description:
+			"Point this session at an existing run directory (recovery; --claim for write ownership)",
+		handler: async (args, ctx) => {
+			const parsed = parseHarnessUseRunArgs(args);
+			if (!parsed.runId) {
+				if (ctx.hasUI)
+					ctx.ui.notify(
+						"Usage: /harness-use-run <run-id> [--claim] [--readonly]",
+						"warning",
+					);
+				return;
 			}
-		}
-
-		activeCtx.plan_ready = planReady;
-
-		const statuses = await resolveCompletionStatuses(
-			entries,
-			activeCtx.run_id,
-			projectRoot,
-		);
-		if (parsed?.command === "harness-run") {
-			activeCtx.last_completed_step = "execute";
-			let execStatus = statuses.executionStatus;
-			if (!execStatus) {
-				const handoff = await readExecutorHandoffFromRun(
-					activeCtx.run_id,
-					projectRoot,
-				);
-				execStatus = handoff?.execution_status ?? null;
+			const projectRoot = process.cwd();
+			const sessionId = ctx.sessionManager.getSessionId();
+			const disk = await loadRunContextFromDisk(parsed.runId, projectRoot);
+			if (!disk) {
+				if (ctx.hasUI) ctx.ui.notify(`Run not found: ${parsed.runId}`, "error");
+				return;
 			}
-			activeCtx.last_outcome = execStatus ?? "completed";
-			activeCtx.phase = "evaluate";
-		}
-		if (parsed?.command === "harness-steer") {
-			activeCtx.last_completed_step = "steer";
-			activeCtx.steer_attempt = (activeCtx.steer_attempt ?? 0) + 1;
-			activeCtx.steer_max_attempts =
-				activeCtx.steer_max_attempts ?? steerMaxAttemptsFromEnv();
-			activeCtx.phase = "execute";
+			let activeCtx: HarnessRunContext = { ...disk, pi_session_id: sessionId };
+			if (parsed.claim) activeCtx = claimRunOwnership(activeCtx, sessionId);
+			const statuses = await resolveCompletionStatuses(
+				getEntries(ctx),
+				activeCtx.run_id,
+				projectRoot,
+			);
+			activeCtx.next_recommended_command =
+				activeCtx.owner_pi_session_id !== sessionId && !parsed.claim
+					? "Read-only: use /harness-use-run <run-id> --claim to take ownership."
+					: nextStepAfterOutcome({
+							phase: activeCtx.phase,
+							planStatus: activeCtx.plan_ready ? "ready" : null,
+							lastCompletedStep: activeCtx.last_completed_step,
+							lastOutcome: activeCtx.last_outcome,
+							executionStatus: statuses.executionStatus,
+							evalStatus: statuses.evalStatus,
+							adversaryComplete: statuses.adversaryComplete,
+							aborted: activeCtx.status === "aborted",
+						});
+			activeCtx.updated_at = nowIso();
+			active.set(activeCtx);
+			persistContext(pi, activeCtx);
 			syncPolicyFromRunContext(pi, getEntries(ctx), activeCtx);
-		}
-		if (
-			parsed?.command === "harness-eval" ||
-			parsed?.command === "harness-review" ||
-			parsed?.command === "harness-critic"
-		) {
-			activeCtx.last_completed_step =
-				parsed.command === "harness-critic" ? "adversary" : "review";
-			if (statuses.evalStatus) {
-				activeCtx.last_outcome = statuses.evalStatus;
-			}
-			if (statuses.adversaryComplete) {
-				activeCtx.phase = "adversary";
-				activeCtx.last_completed_step = "adversary";
-			} else if (statuses.evalStatus) {
-				activeCtx.phase = "evaluate";
+			if (ctx.hasUI) {
+				const mode = parsed.claim ? "claimed" : "bound (read-only)";
+				ctx.ui.notify(
+					`Session ${mode} to run ${parsed.runId}. See /harness-run-status.`,
+					"info",
+				);
 			}
-		}
+		},
+	});
+}
 
-		const reviewOutcome = await readReviewOutcomeFromRun(
-			activeCtx.run_id,
-			projectRoot,
+async function readPlanSpawnState(activeCtx: HarnessRunContext): Promise<{
+	planSummary: PlanPacketSummary | null;
+	planPacketForSpawn: Awaited<ReturnType<typeof readPlanPacketFromPath>>;
+}> {
+	let planSummary: PlanPacketSummary | null = null;
+	let planPacketForSpawn: Awaited<ReturnType<typeof readPlanPacketFromPath>> =
+		null;
+	if (!activeCtx.plan_packet_path) return { planSummary, planPacketForSpawn };
+	planPacketForSpawn = await readPlanPacketFromPath(activeCtx.plan_packet_path);
+	if (planPacketForSpawn) {
+		planSummary = planPacketSummary(
+			planPacketForSpawn,
+			activeCtx.plan_packet_path,
+			activeCtx.plan_ready ? "ready" : "draft",
 		);
-		const reviewComplete =
-			activeCtx.last_completed_step === "review" ||
-			activeCtx.last_completed_step === "adversary";
-		const next = nextStepAfterOutcome({
-			phase: activeCtx.phase,
-			planStatus: statuses.planStatus,
-			lastCompletedStep: activeCtx.last_completed_step,
-			lastOutcome: activeCtx.last_outcome,
-			executionStatus: statuses.executionStatus,
-			evalStatus: statuses.evalStatus,
-			adversaryComplete: statuses.adversaryComplete,
-			aborted: activeCtx.status === "aborted",
-			remediationClass: reviewOutcome?.remediation_class ?? null,
-			steerAttempt: activeCtx.steer_attempt ?? 0,
-			steerMaxAttempts:
-				activeCtx.steer_max_attempts ?? steerMaxAttemptsFromEnv(),
-			reviewComplete,
-		});
-		activeCtx.next_recommended_command = next;
-		activeCtx.updated_at = new Date().toISOString();
+		activeCtx.plan_id = planPacketForSpawn.plan_id ?? activeCtx.plan_id;
+	}
+	return { planSummary, planPacketForSpawn };
+}
 
-		if (
-			parsed?.command === "harness-run" &&
-			activeCtx.last_outcome === "completed"
-		) {
-			syncPolicyFromRunContext(pi, getEntries(ctx), activeCtx);
-		}
+function buildSpawnPromptBlocks(input: {
+	command: string;
+	activeCtx: HarnessRunContext;
+	planSummary: PlanPacketSummary | null;
+	planPacketForSpawn: Awaited<ReturnType<typeof readPlanPacketFromPath>>;
+}): {
+	activePlanBlock: string;
+	planMode: "create" | "revise" | null;
+	contextSpawnOpts: Parameters<typeof formatPlanContextBlock>[1] | undefined;
+} {
+	let activePlanBlock = "";
+	let planMode: "create" | "revise" | null = null;
+	let contextSpawnOpts:
+		| Parameters<typeof formatPlanContextBlock>[1]
+		| undefined;
+	if (input.command === "harness-run" && input.planPacketForSpawn) {
+		contextSpawnOpts = {
+			mode: "execute",
+			critical_path_work_item_ids: criticalPathWorkItemIdsFromPlanPacket(
+				input.planPacketForSpawn,
+			),
+		};
+	}
+	if (input.command === "harness-plan" || input.command === "harness-auto") {
+		planMode =
+			input.activeCtx.plan_id ||
+			input.activeCtx.plan_packet_path ||
+			input.activeCtx.status === "aborted"
+				? "revise"
+				: "create";
+		activePlanBlock = formatActivePlanBlock(
+			input.activeCtx,
+			planMode,
+			input.planSummary,
+		);
+	} else if (input.command === "harness-run") {
+		activePlanBlock = formatActivePlanBlock(
+			input.activeCtx,
+			"execute",
+			input.planSummary,
+		);
+	} else if (input.command === "harness-steer") {
+		activePlanBlock = formatActivePlanBlock(
+			input.activeCtx,
+			"execute",
+			input.planSummary,
+		);
+		contextSpawnOpts = {
+			mode: "repair",
+			repair_brief_path: "artifacts/repair-brief.yaml",
+		};
+	} else if (
+		["harness-eval", "harness-review", "harness-critic"].includes(input.command)
+	) {
+		activePlanBlock = formatActivePlanBlock(
+			input.activeCtx,
+			"read",
+			input.planSummary,
+		);
+	}
+	return { activePlanBlock, planMode, contextSpawnOpts };
+}
+
+async function archivePlanRevisionIfNeeded(input: {
+	pi: ExtensionAPI;
+	command: string;
+	planMode: "create" | "revise" | null;
+	activeCtx: HarnessRunContext;
+	projectRoot: string;
+	userPrompt: string;
+}): Promise<void> {
+	if (input.command !== "harness-plan" && input.command !== "harness-auto")
+		return;
+	const reviewOutcome = await readReviewOutcomeFromRun(
+		input.activeCtx.run_id,
+		input.projectRoot,
+	);
+	if (
+		!shouldArchiveForPlanRevise({
+			command: input.command,
+			mode: input.planMode,
+			runCtx: input.activeCtx,
+			reviewOutcome,
+			userPrompt: input.userPrompt,
+		})
+	)
+		return;
+	const reset = await archivePlanRevisionArtifacts({
+		projectRoot: input.projectRoot,
+		runId: input.activeCtx.run_id,
+		reason: "review_plan_gap_revise",
+	});
+	if (reset.moved.length === 0) return;
+	input.pi.appendEntry("harness-plan-revision-reset", {
+		run_id: input.activeCtx.run_id,
+		archive_dir: reset.archiveDir,
+		moved: reset.moved,
+		reason: "review_plan_gap_revise",
+		recorded_at: nowIso(),
+	});
+}
 
-		persistContext(pi, activeCtx);
+function latestParsedHarnessCommand(entries: unknown[]) {
+	const userEntries = entries.filter((e) => {
+		const entry = e as { type?: string; message?: { role?: string } };
+		return entry.type === "message" && entry.message?.role === "user";
+	});
+	const lastUser = userEntries[userEntries.length - 1] as
+		| { message?: { content?: string | unknown[] } }
+		| undefined;
+	const lastPrompt =
+		typeof lastUser?.message?.content === "string"
+			? lastUser.message.content
+			: "";
+	const lastTurn = getLatestHarnessTurn(entries);
+	return lastTurn
+		? { command: lastTurn.command, args: lastTurn.args }
+		: parseHarnessSlashInput(userVisiblePromptSlice(lastPrompt));
+}
 
-		pi.appendEntry("harness-step-handoff", {
-			next_command: next,
-			plan_status: statuses.planStatus,
-			execution_status: statuses.executionStatus,
-			eval_status: statuses.evalStatus,
-			phase: activeCtx.phase,
+function handleAgentEndAbort(input: {
+	pi: ExtensionAPI;
+	ctx: { hasUI: boolean; ui: { notify(message: string, type?: string): void } };
+	activeCtx: HarnessRunContext;
+}): void {
+	input.activeCtx.status = "aborted";
+	input.activeCtx.plan_ready = false;
+	input.activeCtx.last_outcome = "aborted";
+	input.activeCtx.last_completed_step = "abort";
+	input.activeCtx.next_recommended_command = input.activeCtx.task_summary
+		? `/harness-plan "${input.activeCtx.task_summary}"`
+		: '/harness-plan "<task>"';
+	persistContext(input.pi, input.activeCtx);
+	const msg = `Harness aborted. Next: ${input.activeCtx.next_recommended_command}`;
+	if (input.ctx.hasUI) input.ctx.ui.notify(msg, "warning");
+	else
+		input.pi.sendMessage({
+			customType: "harness-step-handoff",
+			content: msg,
+			display: true,
 		});
+}
 
-		if (next && parsed) {
-			const notify = `Next: ${next}`;
-			if (ctx.hasUI) ctx.ui.notify(notify, "info");
-			else
-				pi.sendMessage({
-					customType: "harness-step-handoff",
-					content: notify,
-					display: true,
-				});
-		}
+async function updatePlanReadinessAfterAgent(input: {
+	pi: ExtensionAPI;
+	ctx: { hasUI: boolean; ui: { notify(message: string, type?: string): void } };
+	entries: unknown[];
+	parsed: { command: string; args: string } | null;
+	activeCtx: HarnessRunContext;
+}): Promise<void> {
+	if (
+		input.parsed?.command !== "harness-plan" &&
+		input.parsed?.command !== "harness-auto"
+	)
+		return;
+	if (!input.activeCtx.plan_packet_path) return;
+	const packet = await readPlanPacketFromPath(input.activeCtx.plan_packet_path);
+	const validation = validatePlanPacket(packet);
+	const approved = hasPlanUserApproval(input.entries, {
+		sincePlanCommand: true,
+		planId: packet?.plan_id ?? null,
 	});
+	input.activeCtx.plan_ready = validation.valid && approved;
+	if (validation.valid && !approved) {
+		input.activeCtx.last_outcome = "needs_clarification";
+		input.activeCtx.last_completed_step = "plan";
+		const msg =
+			"Plan file exists but user approval was not recorded. Planner must call approve_plan (or bridged ask_user Approve) before writing plan-packet.yaml.";
+		if (input.ctx.hasUI) input.ctx.ui.notify(msg, "warning");
+		else
+			input.pi.sendMessage({
+				customType: "harness-plan-packet",
+				content: msg,
+				display: true,
+			});
+	} else if (input.activeCtx.plan_ready && packet?.plan_id) {
+		input.activeCtx.plan_id = packet.plan_id;
+		syncPolicyFromPlan(input.pi, input.entries, packet.plan_id, "plan", true);
+		const summary = planPacketSummary(packet, input.activeCtx.plan_packet_path);
+		input.pi.appendEntry("harness-plan-packet", summary);
+		input.activeCtx.last_completed_step = "plan";
+		input.activeCtx.last_outcome = summary.plan_status;
+	} else if (!validation.valid) {
+		input.activeCtx.last_outcome = "needs_clarification";
+		input.activeCtx.last_completed_step = "plan";
+	}
+}
 
+function registerPlanApprovalCapture(
+	pi: ExtensionAPI,
+	active: ActiveContextAccess,
+): void {
 	pi.on("tool_result", async (event, ctx) => {
 		if (event.isError) return;
-		if (event.toolName !== "ask_user" && event.toolName !== "approve_plan") {
+		if (event.toolName !== "ask_user" && event.toolName !== "approve_plan")
 			return;
-		}
 		const approval = parsePlanApprovalFromMessage({
 			toolName: event.toolName,
 			details: event.details,
@@ -893,7 +1025,7 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 		});
 		if (!approval) return;
 		const entries = getEntries(ctx);
-		const runCtx = getLatestRunContext(entries) ?? activeCtx;
+		const runCtx = getLatestRunContext(entries) ?? active.get();
 		if (!runCtx) return;
 		pi.appendEntry("harness-plan-approval", {
 			plan_id: approval.plan_id ?? runCtx.plan_id,
@@ -901,226 +1033,514 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 			source: approval.source,
 		});
 	});
+}
+
+async function guardToolCall(input: {
+	event: { toolName: string; input: unknown };
+	ctx: { sessionManager: { getEntries(): unknown[] } };
+	activeCtx: HarnessRunContext | null;
+}) {
+	const { isHarnessAgtPolicyEnabled } = await import("../lib/agt/config.js");
+	if (!isHarnessAgtPolicyEnabled()) {
+		if (isSubmitToolName(input.event.toolName)) {
+			const packageRoot = getHarnessPackageRoot(MODULE_URL);
+			const allowed = allowsAgentTool({
+				packageRoot,
+				projectRoot: process.cwd(),
+				agentId: "parent-orchestrator",
+				toolName: input.event.toolName,
+				toolInput: input.event.input as Record<string, unknown>,
+				isSubprocess: false,
+				isParentOrchestrator: true,
+			});
+			if (!allowed) {
+				return {
+					block: true,
+					reason: `agents-policy: ${input.event.toolName} blocked for parent-orchestrator`,
+				};
+			}
+		}
+	}
+	if (input.event.toolName === "write") {
+		const entries = getEntries(input.ctx);
+		const runCtx = getLatestRunContext(entries) ?? input.activeCtx;
+		if (runCtx) {
+			const blocked = await coerceScopedHarnessYamlWrite(
+				input.event as { toolName: string; input: Record<string, unknown> },
+				runCtx,
+				process.cwd(),
+			);
+			if (blocked) return blocked;
+		}
+	}
+	const activeCtx = input.activeCtx;
+	if (activeCtx?.plan_packet_path) {
+		const entries = getEntries(input.ctx);
+		if (hasPlanUserApproval(entries, { sincePlanCommand: true })) {
+			if (input.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 (input.event.toolName === "ask_user") {
+				const askInput = input.event.input as {
+					question?: string;
+					options?: unknown[];
+				};
+				if (isPlanApprovalAskUser(askInput)) {
+					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 (!isHarnessAgtPolicyEnabled()) {
+		if (!activeCtx?.plan_packet_path) return undefined;
+		const phase = activeCtx.phase;
+		if (phase !== "evaluate" && phase !== "adversary") return undefined;
+		if (input.event.toolName !== "write" && input.event.toolName !== "edit")
+			return undefined;
+		const target = String(
+			(input.event.input as { path?: string; filePath?: string }).path ??
+				(input.event.input as { filePath?: string }).filePath ??
+				"",
+		);
+		if (target.includes("plan-packet.yaml")) {
+			return {
+				block: true,
+				reason:
+					"harness-run-context: plan-packet.yaml is read-only in evaluate/adversary phases.",
+			};
+		}
+	}
+	return undefined;
+}
+
+function registerHarnessToolCallGuards(
+	pi: ExtensionAPI,
+	active: ActiveContextAccess,
+): void {
+	pi.on("tool_call", async (event, ctx) =>
+		guardToolCall({ event, ctx, activeCtx: active.get() }),
+	);
+}
+
+async function resolveCommandRunContext(input: {
+	pi: ExtensionAPI;
+	activeCtx: HarnessRunContext | null;
+	command: string;
+	args: string;
+	userPrompt: string;
+	sessionId: string;
+	projectRoot: string;
+	turn: HarnessTurnEntry | null;
+}) {
+	let activeCtx = input.activeCtx;
+	const resolved = resolveArgsForCommand(input.command, input.args, activeCtx);
+	if (resolved.overrideRun && resolved.runId) {
+		const disk = await loadRunContextFromDisk(
+			resolved.runId,
+			input.projectRoot,
+		);
+		if (disk) activeCtx = { ...disk, turn_override_run_id: resolved.runId };
+	}
+	if (
+		input.command === "harness-plan" ||
+		input.command === "harness-auto" ||
+		(!activeCtx && input.command !== "harness-abort")
+	) {
+		if (
+			!activeCtx ||
+			!shouldReuseHarnessRunId(input.userPrompt, activeCtx, input.command)
+		) {
+			activeCtx = createFreshRunContext(
+				input.sessionId,
+				input.projectRoot,
+				extractTaskSummary(input.args, input.userPrompt),
+			);
+		}
+		if (input.command === "harness-plan") {
+			const task = extractTaskSummary(input.args, input.userPrompt);
+			if (task) activeCtx.task_summary = task;
+		}
+		startFreshPlanAttempt({
+			pi: input.pi,
+			activeCtx,
+			command: input.command,
+			turn: input.turn,
+		});
+	} else if (
+		activeCtx &&
+		shouldReuseHarnessRunId(input.userPrompt, activeCtx, input.command)
+	) {
+		activeCtx.turn_override_run_id = resolved.overrideRun
+			? resolved.runId
+			: null;
+	} else if (!activeCtx) {
+		const pointer = await loadProjectActiveRun(input.projectRoot);
+		if (pointer && isStaleActiveRunPointer(pointer, input.projectRoot)) {
+			const crossSessionCmd = new Set([
+				"harness-eval",
+				"harness-review",
+				"harness-steer",
+				"harness-critic",
+				"harness-trace",
+				"harness-incident",
+			]);
+			if (crossSessionCmd.has(input.command)) {
+				return {
+					activeCtx,
+					resolved,
+					response: blockRunContextMessage(
+						'Project active-run pointer is stale or from another workspace. Run /harness-plan "<task>" or /harness-use-run <run-id> for recovery.',
+					),
+				};
+			}
+		} else if (pointer) {
+			const disk = await loadRunContextFromDisk(
+				pointer.run_id,
+				input.projectRoot,
+			);
+			if (disk) activeCtx = disk;
+		}
+	}
+	return { activeCtx, resolved, response: null };
+}
+
+async function handleBeforeAgentStart(input: {
+	pi: ExtensionAPI;
+	event: any;
+	ctx: any;
+	active: ActiveContextAccess;
+}) {
+	const sessionId = input.ctx.sessionManager.getSessionId();
+	const projectRoot = process.cwd();
+	const entries = getEntries(input.ctx);
+	const userPrompt = userVisiblePromptSlice(input.event.prompt);
+	const turn = getLatestHarnessTurn(entries);
+	const parsed = turn
+		? { command: turn.command, args: turn.args }
+		: parseHarnessSlashInput(userPrompt);
+	const harnessTurn =
+		Boolean(turn) ||
+		Boolean(parsed) ||
+		needsClarificationFollowUp(input.active.get());
+	let activeCtx = await applyAbortSignal({
+		pi: input.pi,
+		activeCtx: input.active.get(),
+		sessionId,
+		projectRoot,
+		entries,
+		userPrompt,
+	});
+	input.active.set(activeCtx);
+	if (!harnessTurn) return undefined;
+	if (!activeCtx) {
+		activeCtx = await hydrateFromDisk(sessionId, projectRoot, entries);
+		input.active.set(activeCtx);
+	}
+	const policyPhase =
+		inferHarnessPhase(entries, userPrompt) ??
+		getLatestPolicyPhase(entries) ??
+		activeCtx?.phase ??
+		"plan";
+	const driftActive = driftGateActive(entries);
+	if (!parsed && needsClarificationFollowUp(activeCtx) && activeCtx) {
+		return maybeHandleClarificationFollowUp({
+			pi: input.pi,
+			activeCtx,
+			entries,
+			systemPrompt: input.event.systemPrompt,
+		});
+	}
+	if (!parsed) return undefined;
+	const { command, args } = parsed;
+	if (
+		!isHarnessBootstrapPrompt(userPrompt) &&
+		!hasHarnessAbortSignal(userPrompt)
+	) {
+		const policyBlock = getPolicyTransitionBlock(userPrompt, entries);
+		if (policyBlock.blocked) {
+			return blockRunContextMessage(
+				policyBlock.message ?? "Harness command blocked by policy phase.",
+			);
+		}
+	}
+	if (command === "harness-new-run") {
+		const next = createNewRunContextForCommand({
+			pi: input.pi,
+			activeCtx,
+			sessionId,
+			projectRoot,
+			args,
+			userPrompt,
+			systemPrompt: input.event.systemPrompt,
+		});
+		input.active.set(next.activeCtx);
+		return next.response;
+	}
+	if (command === "harness-use-run") {
+		const next = await bindExistingRunForCommand({
+			pi: input.pi,
+			sessionId,
+			projectRoot,
+			entries,
+			args,
+			systemPrompt: input.event.systemPrompt,
+		});
+		if (next.activeCtx) input.active.set(next.activeCtx);
+		return next.response;
+	}
+	if (command === "harness-run-status") return undefined;
+	if (
+		command === "harness-plan" &&
+		activeCtx &&
+		isNewTaskPlanBlocked(activeCtx, userPrompt) &&
+		!isAmendPlanAllowed(activeCtx, userPrompt, driftActive)
+	) {
+		return blockRunContextMessage(
+			"Active harness run in progress. Use /harness-abort or /harness-new-run before starting a new task plan.",
+		);
+	}
+	const prepared = await resolveCommandRunContext({
+		pi: input.pi,
+		activeCtx,
+		command,
+		args,
+		userPrompt,
+		sessionId,
+		projectRoot,
+		turn,
+	});
+	activeCtx = prepared.activeCtx;
+	const { resolved } = prepared;
+	if (prepared.response) return prepared.response;
+	if (!activeCtx)
+		return blockRunContextMessage(
+			'No active harness run. Run /harness-plan "<task>" first, or /harness-use-run <run-id> for recovery.',
+		);
+	activeCtx.phase = policyPhase;
+	activeCtx.updated_at = new Date().toISOString();
+	activeCtx.pi_session_id = sessionId;
+	if (
+		shouldAutoClaimHarnessRun(command, args) &&
+		activeCtx.owner_pi_session_id !== sessionId
+	) {
+		activeCtx = claimRunOwnership(activeCtx, sessionId);
+	}
+	if (resolved.planPath && resolved.runId) {
+		const check = validatePlanOverridePath(
+			resolved.planPath,
+			resolved.runId,
+			projectRoot,
+		);
+		if (!check.ok)
+			return blockRunContextMessage(check.reason ?? "Invalid --plan override");
+		activeCtx.plan_packet_path = resolved.planPath;
+	}
+	if (command === "harness-run" && !activeCtx.plan_ready)
+		return blockRunContextMessage("Plan not ready. Run /harness-plan first.");
+	if (
+		command === "harness-run" &&
+		activeCtx.plan_ready &&
+		activeCtx.last_completed_step === "execute" &&
+		activeCtx.last_outcome === "completed"
+	) {
+		return blockRunContextMessage(
+			"Execute already completed for this run. Next: /harness-review (same session), or /harness-abort to replan.",
+		);
+	}
+	const { planSummary, planPacketForSpawn } =
+		await readPlanSpawnState(activeCtx);
+	const { activePlanBlock, planMode, contextSpawnOpts } =
+		buildSpawnPromptBlocks({
+			command,
+			activeCtx,
+			planSummary,
+			planPacketForSpawn,
+		});
+	await archivePlanRevisionIfNeeded({
+		pi: input.pi,
+		command,
+		planMode,
+		activeCtx,
+		projectRoot,
+		userPrompt,
+	});
+	input.active.set(activeCtx);
+	persistContext(input.pi, activeCtx);
+	return {
+		systemPrompt: `${input.event.systemPrompt}\n\n${formatPlanContextBlock(activeCtx, contextSpawnOpts)}${activePlanBlock ? `\n\n${activePlanBlock}` : ""}`,
+	};
+}
 
-	pi.on("tool_call", async (event, ctx) => {
-		if (isSubmitToolName(event.toolName)) {
-			const decision = evaluateHarnessSubagentToolCall(
-				event.toolName,
-				event.input as Record<string, unknown>,
-				"parent-orchestrator",
+async function handleAgentEnd(input: {
+	pi: ExtensionAPI;
+	ctx: any;
+	active: ActiveContextAccess;
+}): Promise<void> {
+	const projectRoot = process.cwd();
+	const entries = getEntries(input.ctx);
+	const activeCtx = input.active.get() ?? getLatestRunContext(entries);
+	if (!activeCtx) return;
+	input.active.set(activeCtx);
+	const parsed = latestParsedHarnessCommand(entries);
+	if (!parsed && !needsClarificationFollowUp(activeCtx)) return;
+	if (parsed?.command === "harness-abort") {
+		handleAgentEndAbort({ pi: input.pi, ctx: input.ctx, activeCtx });
+		return;
+	}
+	await updatePlanReadinessAfterAgent({
+		pi: input.pi,
+		ctx: input.ctx,
+		entries,
+		parsed,
+		activeCtx,
+	});
+	const statuses = await resolveCompletionStatuses(
+		entries,
+		activeCtx.run_id,
+		projectRoot,
+	);
+	if (parsed?.command === "harness-run") {
+		activeCtx.last_completed_step = "execute";
+		let execStatus = statuses.executionStatus;
+		if (!execStatus) {
+			const handoff = await readExecutorHandoffFromRun(
+				activeCtx.run_id,
+				projectRoot,
 			);
-			if (decision.action === "block") {
-				return { block: true, reason: decision.reason };
-			}
-		}
-		if (event.toolName === "write") {
-			const entries = getEntries(ctx);
-			const runCtx = getLatestRunContext(entries) ?? activeCtx;
-			if (runCtx) {
-				const blocked = await coerceScopedHarnessYamlWrite(
-					event,
-					runCtx,
-					process.cwd(),
-				);
-				if (blocked) return blocked;
-			}
-		}
-		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;
-		const phase = activeCtx.phase;
-		if (phase !== "evaluate" && phase !== "adversary") return undefined;
-		if (event.toolName !== "write" && event.toolName !== "edit") {
-			return undefined;
-		}
-		const target = String(
-			(event.input as { path?: string; filePath?: string }).path ??
-				(event.input as { filePath?: string }).filePath ??
-				"",
-		);
-		if (target.includes("plan-packet.yaml")) {
-			return {
-				block: true,
-				reason:
-					"harness-run-context: plan-packet.yaml is read-only in evaluate/adversary phases.",
-			};
+			execStatus = handoff?.execution_status ?? null;
 		}
-		return undefined;
+		activeCtx.last_outcome = execStatus ?? "completed";
+		activeCtx.phase = "evaluate";
+	}
+	if (parsed?.command === "harness-steer") {
+		activeCtx.last_completed_step = "steer";
+		activeCtx.steer_attempt = (activeCtx.steer_attempt ?? 0) + 1;
+		activeCtx.steer_max_attempts =
+			activeCtx.steer_max_attempts ?? steerMaxAttemptsFromEnv();
+		activeCtx.phase = "execute";
+		syncPolicyFromRunContext(input.pi, entries, activeCtx);
+	}
+	if (
+		["harness-eval", "harness-review", "harness-critic"].includes(
+			parsed?.command ?? "",
+		)
+	) {
+		activeCtx.last_completed_step =
+			parsed?.command === "harness-critic" ? "adversary" : "review";
+		if (statuses.evalStatus) activeCtx.last_outcome = statuses.evalStatus;
+		if (statuses.adversaryComplete) {
+			activeCtx.phase = "adversary";
+			activeCtx.last_completed_step = "adversary";
+		} else if (statuses.evalStatus) activeCtx.phase = "evaluate";
+	}
+	const reviewOutcome = await readReviewOutcomeFromRun(
+		activeCtx.run_id,
+		projectRoot,
+	);
+	const reviewComplete =
+		activeCtx.last_completed_step === "review" ||
+		activeCtx.last_completed_step === "adversary";
+	const next = nextStepAfterOutcome({
+		phase: activeCtx.phase,
+		planStatus: statuses.planStatus,
+		lastCompletedStep: activeCtx.last_completed_step,
+		lastOutcome: activeCtx.last_outcome,
+		executionStatus: statuses.executionStatus,
+		evalStatus: statuses.evalStatus,
+		adversaryComplete: statuses.adversaryComplete,
+		aborted: activeCtx.status === "aborted",
+		remediationClass: reviewOutcome?.remediation_class ?? null,
+		steerAttempt: activeCtx.steer_attempt ?? 0,
+		steerMaxAttempts: activeCtx.steer_max_attempts ?? steerMaxAttemptsFromEnv(),
+		reviewComplete,
+	});
+	activeCtx.next_recommended_command = next;
+	activeCtx.updated_at = new Date().toISOString();
+	if (
+		parsed?.command === "harness-run" &&
+		activeCtx.last_outcome === "completed"
+	) {
+		syncPolicyFromRunContext(input.pi, entries, activeCtx);
+	}
+	persistContext(input.pi, activeCtx);
+	input.pi.appendEntry("harness-step-handoff", {
+		next_command: next,
+		plan_status: statuses.planStatus,
+		execution_status: statuses.executionStatus,
+		eval_status: statuses.evalStatus,
+		phase: activeCtx.phase,
 	});
+	if (next && parsed) {
+		const notify = `Next: ${next}`;
+		if (input.ctx.hasUI) input.ctx.ui.notify(notify, "info");
+		else
+			input.pi.sendMessage({
+				customType: "harness-step-handoff",
+				content: notify,
+				display: true,
+			});
+	}
+}
 
-	pi.registerCommand("harness-run-status", {
-		description:
-			"Show harness phase, plan readiness, and next command (no run id)",
-		handler: async (_args, ctx) => {
-			const sessionId = ctx.sessionManager.getSessionId();
-			const projectRoot = process.cwd();
-			const entries = getEntries(ctx);
-			let ctxState = getLatestRunContext(entries) ?? activeCtx;
-			if (!ctxState) {
-				ctxState = await hydrateFromDisk(sessionId, projectRoot, entries);
-			}
-			if (!ctxState) {
-				const msg = 'No active harness run. Start with /harness-plan "<task>".';
-				if (ctx.hasUI) ctx.ui.notify(msg, "warning");
-				return;
-			}
-			let summary: PlanPacketSummary | null = null;
-			for (let i = entries.length - 1; i >= 0; i--) {
-				const entry = entries[i] as SessionEntryLike;
-				if (
-					entry.type !== "custom" ||
-					entry.customType !== "harness-plan-packet"
-				)
-					continue;
-				summary = entry.data as PlanPacketSummary;
-				break;
-			}
-			const lines = [
-				"Harness run status:",
-				`  phase: ${ctxState.phase}`,
-				`  status: ${ctxState.status}`,
-				`  plan_ready: ${ctxState.plan_ready}`,
-				`  plan_id: ${ctxState.plan_id ?? "(none)"}`,
-				summary
-					? `  scope: ${summary.scope_one_liner}`
-					: "  scope: (no plan summary yet)",
-				`  last_step: ${ctxState.last_completed_step ?? "(none)"}`,
-				`  last_outcome: ${ctxState.last_outcome ?? "(none)"}`,
-				`  next: ${ctxState.next_recommended_command ?? "/harness-run-status"}`,
-			];
-			const text = lines.join("\n");
-			if (ctx.hasUI) ctx.ui.notify(text, "info");
-			else
-				pi.sendMessage({
-					customType: "harness-run-status",
-					content: text,
-					display: true,
-				});
+export default function harnessRunContext(pi: ExtensionAPI) {
+	if (!claimHarnessGovernanceLoad("harness-run-context", MODULE_URL)) return;
+	let activeCtx: HarnessRunContext | null = null;
+	const activeAccess: ActiveContextAccess = {
+		get: () => activeCtx,
+		set: (ctx) => {
+			activeCtx = ctx;
 		},
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		const entries = getEntries(ctx);
+		activeCtx = hydrateFromSession(entries);
+		const booted = await bootstrapHarnessSubprocessFromEnv(pi, ctx);
+		if (booted) activeCtx = booted;
+		if (!booted) await offerCrossSessionResume(pi, ctx);
 	});
 
-	pi.registerCommand("harness-new-run", {
-		description: "Abandon current active run and start a fresh harness run",
-		handler: async (args, ctx) => {
-			const sessionId = ctx.sessionManager.getSessionId();
-			const projectRoot = process.cwd();
-			if (activeCtx?.status === "active") {
-				activeCtx.status = "aborted";
-				activeCtx.plan_ready = false;
-				persistContext(pi, activeCtx);
-			}
-			activeCtx = createFreshRunContext(
-				sessionId,
-				projectRoot,
-				args.trim() || null,
-			);
-			persistContext(pi, activeCtx);
-			const msg =
-				'New harness run allocated. Next: /harness-plan "<your task>"';
-			if (ctx.hasUI) ctx.ui.notify(msg, "info");
-		},
+	pi.on("input", async (event) => {
+		if (event.source === "extension") {
+			return { action: "continue" as const };
+		}
+		const parsed = parseHarnessSlashInput(event.text);
+		if (!parsed) {
+			return { action: "continue" as const };
+		}
+		appendHarnessTurn(pi, {
+			schema_version: "1.0.0",
+			command: parsed.command,
+			args: parsed.args,
+			source: "slash",
+			invoked_at: nowIso(),
+		});
+		return { action: "continue" as const };
 	});
 
-	pi.registerCommand("harness-plan-commit", {
-		description:
-			"Write approved plan-packet.yaml to the active run (requires harness-plan-approval)",
-		handler: async (args, ctx) => {
-			const projectRoot = process.cwd();
-			const entries = getEntries(ctx);
-			let runCtx = getLatestRunContext(entries) ?? activeCtx;
-			if (!runCtx) {
-				runCtx = await hydrateFromDisk(
-					ctx.sessionManager.getSessionId(),
-					projectRoot,
-					entries,
-				);
-			}
-			if (!runCtx?.plan_packet_path) {
-				const msg = "No active harness run. Run /harness-plan first.";
-				if (ctx.hasUI) ctx.ui.notify(msg, "warning");
-				return;
-			}
-			if (
-				!hasPlanUserApproval(entries, {
-					sincePlanCommand: true,
-					planId: runCtx.plan_id,
-				})
-			) {
-				const msg =
-					"Plan commit blocked: no user approval recorded. Approve via approve_plan in this session first.";
-				if (ctx.hasUI) ctx.ui.notify(msg, "warning");
-				return;
-			}
-			const pathArg = args.trim();
-			let packetPath = runCtx.plan_packet_path;
-			if (pathArg) {
-				packetPath = pathArg;
-			}
-			const packet = await readPlanPacketFromPath(packetPath);
-			const validation = validatePlanPacket(packet);
-			if (!validation.valid || !packet) {
-				const msg = !packet
-					? "Plan packet file missing or unreadable."
-					: `Invalid plan packet: ${validation.errors.join("; ")}`;
-				if (ctx.hasUI) ctx.ui.notify(msg, "error");
-				return;
-			}
-			const target = runCtx.plan_packet_path;
-			if (!target) {
-				if (ctx.hasUI)
-					ctx.ui.notify("No plan_packet_path on active run.", "error");
-				return;
-			}
-			if (pathArg && pathArg !== target) {
-				const raw = await readFile(pathArg, "utf-8");
-				await writeFile(target, raw, "utf-8");
-			}
-			runCtx.plan_id = packet.plan_id ?? runCtx.plan_id;
-			runCtx.plan_ready = true;
-			runCtx.phase = "plan";
-			runCtx.last_completed_step = "plan";
-			runCtx.last_outcome = "ready";
-			runCtx.next_recommended_command = "/harness-run";
-			runCtx.updated_at = nowIso();
-			activeCtx = runCtx;
-			persistContext(pi, runCtx);
-			syncPolicyFromPlan(
-				pi,
-				entries,
-				runCtx.plan_id ?? packet.plan_id ?? "plan-pending",
-				"plan",
-				true,
-			);
-			const summary = planPacketSummary(packet, target, "ready");
-			pi.appendEntry("harness-plan-packet", summary);
-			const msg = `Plan committed: ${target}`;
-			if (ctx.hasUI) ctx.ui.notify(msg, "info");
-		},
+	pi.on("before_agent_start", async (event, ctx) =>
+		handleBeforeAgentStart({ pi, event, ctx, active: activeAccess }),
+	);
+
+	pi.on("agent_end", async (_event, ctx) => {
+		await handleAgentEnd({ pi, ctx, active: activeAccess });
 	});
 
+	registerPlanApprovalCapture(pi, activeAccess);
+	registerHarnessToolCallGuards(pi, activeAccess);
+	registerHarnessRunStatusCommand(pi, activeAccess);
+	registerHarnessNewRunCommand(pi, activeAccess);
+
+	registerHarnessPlanCommitCommand(pi, activeAccess);
+
 	pi.registerTool({
 		name: "write_harness_yaml",
 		label: "Write Harness YAML",
@@ -1211,7 +1631,7 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 					content: [
 						{
 							type: "text",
-							text: `Path not allowed: ${pathArg}. Post-run verdicts must be written via submit_* in harness/evaluator or harness/adversary subagents; parent gates with harness_artifact_ready only.`,
+							text: `Path not allowed: ${pathArg}. Post-run verdicts must be written via submit_* in harness/reviewing/evaluator or harness/reviewing/adversary subagents; parent gates with harness_artifact_ready only.`,
 						},
 					],
 					details: { path: pathArg },
@@ -1534,7 +1954,7 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 			);
 			const specsDir = join(projectRoot, ".pi", "harness", "specs");
 			const { validateHarnessArtifactPaths } = await import(
-				"./lib/harness-artifact-gate.js"
+				"../lib/harness-artifact-gate.js"
 			);
 			const gate = await validateHarnessArtifactPaths(runRoot, paths, specsDir);
 			const text = gate.ok
@@ -1561,63 +1981,5 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerCommand("harness-use-run", {
-		description:
-			"Point this session at an existing run directory (recovery; --claim for write ownership)",
-		handler: async (args, ctx) => {
-			const parsed = parseHarnessUseRunArgs(args);
-			if (!parsed.runId) {
-				if (ctx.hasUI)
-					ctx.ui.notify(
-						"Usage: /harness-use-run <run-id> [--claim] [--readonly]",
-						"warning",
-					);
-				return;
-			}
-			const projectRoot = process.cwd();
-			const sessionId = ctx.sessionManager.getSessionId();
-			const disk = await loadRunContextFromDisk(parsed.runId, projectRoot);
-			if (!disk) {
-				if (ctx.hasUI) ctx.ui.notify(`Run not found: ${parsed.runId}`, "error");
-				return;
-			}
-			activeCtx = {
-				...disk,
-				pi_session_id: sessionId,
-			};
-			if (parsed.claim) {
-				activeCtx = claimRunOwnership(activeCtx, sessionId);
-			}
-			const statuses = await resolveCompletionStatuses(
-				getEntries(ctx),
-				activeCtx.run_id,
-				projectRoot,
-			);
-			if (activeCtx.owner_pi_session_id !== sessionId && !parsed.claim) {
-				activeCtx.next_recommended_command =
-					"Read-only: use /harness-use-run <run-id> --claim to take ownership.";
-			} else {
-				activeCtx.next_recommended_command = nextStepAfterOutcome({
-					phase: activeCtx.phase,
-					planStatus: activeCtx.plan_ready ? "ready" : null,
-					lastCompletedStep: activeCtx.last_completed_step,
-					lastOutcome: activeCtx.last_outcome,
-					executionStatus: statuses.executionStatus,
-					evalStatus: statuses.evalStatus,
-					adversaryComplete: statuses.adversaryComplete,
-					aborted: activeCtx.status === "aborted",
-				});
-			}
-			activeCtx.updated_at = nowIso();
-			persistContext(pi, activeCtx);
-			syncPolicyFromRunContext(pi, getEntries(ctx), activeCtx);
-			if (ctx.hasUI) {
-				const mode = parsed.claim ? "claimed" : "bound (read-only)";
-				ctx.ui.notify(
-					`Session ${mode} to run ${parsed.runId}. See /harness-run-status.`,
-					"info",
-				);
-			}
-		},
-	});
+	registerHarnessUseRunCommand(pi, activeAccess);
 }