ultimate-pi 0.22.0 → 0.22.2

package/.pi/lib/harness-schema-validate.ts

@@ -2,7 +2,7 @@
  * JSON Schema validation for harness submit tools (Ajv draft 2020-12, offline).
  */
 
-import { appendFile, readFile } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
 import addFormats from "ajv-formats";
@@ -10,8 +10,9 @@ import addFormats from "ajv-formats";
 type ValidateFn = (data: unknown) => boolean;
 
 const compileCache = new Map<string, ValidateFn>();
-const DEBUG_LOG_PATH =
-	"/home/aryaniyaps/ai-projects/ultimate-pi/.cursor/debug-2ca12b.log";
+const registeredSchemaIds = new Set<string>();
+
+export const EXTERNAL_SCHEMA_REF = /^[a-z0-9._-]+\.schema\.json$/i;
 
 let ajvSingleton: InstanceType<typeof Ajv2020> | null = null;
 
@@ -27,28 +28,143 @@ function getAjv(): InstanceType<typeof Ajv2020> {
 	return ajvSingleton;
 }
 
-async function debugLog(
-	hypothesisId: string,
-	message: string,
-	data: Record<string, unknown>,
+/** Collect sibling `*.schema.json` $ref targets (not `#/$defs/...`). */
+export function collectExternalSchemaRefs(
+	node: unknown,
+	out: Set<string>,
+): void {
+	if (!node || typeof node !== "object") return;
+	if (Array.isArray(node)) {
+		for (const item of node) collectExternalSchemaRefs(item, out);
+		return;
+	}
+	const obj = node as Record<string, unknown>;
+	const ref = obj.$ref;
+	if (typeof ref === "string" && EXTERNAL_SCHEMA_REF.test(ref)) {
+		out.add(ref);
+	}
+	for (const value of Object.values(obj)) {
+		collectExternalSchemaRefs(value, out);
+	}
+}
+
+async function loadHarnessSchema(
+	specsDir: string,
+	schemaFile: string,
+): Promise<Record<string, unknown>> {
+	const schemaPath = join(specsDir, schemaFile);
+	const raw = await readFile(schemaPath, "utf-8");
+	return JSON.parse(raw) as Record<string, unknown>;
+}
+
+/** Register cross-file $ref targets only; root is registered by `compile()`. */
+async function ensureHarnessSchemaDependencies(
+	ajv: InstanceType<typeof Ajv2020>,
+	specsDir: string,
+	schemaFile: string,
+	loading: Set<string>,
 ): Promise<void> {
-	// #region agent log
+	if (loading.has(schemaFile)) return;
+	loading.add(schemaFile);
+
+	const schema = await loadHarnessSchema(specsDir, schemaFile);
+	const schemaId = String(schema.$id ?? schemaFile);
+
+	const externalRefs = new Set<string>();
+	collectExternalSchemaRefs(schema, externalRefs);
+	for (const refFile of externalRefs) {
+		await ensureHarnessSchemaDependencies(ajv, specsDir, refFile, loading);
+	}
+
+	if (!registeredSchemaIds.has(schemaId)) {
+		ajv.addSchema(schema, schemaId);
+		registeredSchemaIds.add(schemaId);
+	}
+
+	loading.delete(schemaFile);
+}
+
+/** Compile a harness schema (registers cross-file $ref targets first). */
+export async function compileHarnessSchema(
+	specsDir: string,
+	schemaFile: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+	const cacheKey = `${specsDir}:${schemaFile}`;
+	if (compileCache.has(cacheKey)) {
+		return { ok: true };
+	}
 	try {
-		await appendFile(
-			DEBUG_LOG_PATH,
-			`${JSON.stringify({
-				sessionId: "2ca12b",
-				hypothesisId,
-				location: "harness-schema-validate.ts",
-				message,
-				data,
-				timestamp: Date.now(),
-			})}\n`,
-		);
-	} catch {
-		/* ignore */
+		const schema = await loadHarnessSchema(specsDir, schemaFile);
+		const ajv = getAjv();
+		const externalRefs = new Set<string>();
+		collectExternalSchemaRefs(schema, externalRefs);
+		for (const refFile of externalRefs) {
+			await ensureHarnessSchemaDependencies(ajv, specsDir, refFile, new Set());
+		}
+		const schemaId = String(schema.$id ?? schemaFile);
+		let compiled: ValidateFn;
+		if (registeredSchemaIds.has(schemaId)) {
+			const existing = ajv.getSchema(schemaId);
+			if (!existing) {
+				return {
+					ok: false,
+					error: `schema ${schemaId} registered but not retrievable from Ajv`,
+				};
+			}
+			compiled = existing;
+		} else {
+			compiled = ajv.compile(schema);
+			registeredSchemaIds.add(schemaId);
+		}
+		compileCache.set(cacheKey, compiled);
+		return { ok: true };
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { ok: false, error: msg };
 	}
-	// #endregion
+}
+
+export async function listHarnessSpecSchemaFiles(
+	specsDir: string,
+): Promise<string[]> {
+	const names = await readdir(specsDir);
+	return names.filter((n) => n.endsWith(".schema.json")).sort();
+}
+
+/** Ensure every listed schema compiles; fails on missing cross-file $ref targets. */
+export async function verifyHarnessSchemasCompile(
+	specsDir: string,
+	schemaFiles: string[],
+): Promise<{ ok: true } | { ok: false; errors: string[] }> {
+	const errors: string[] = [];
+	for (const schemaFile of schemaFiles) {
+		const compiled = await compileHarnessSchema(specsDir, schemaFile);
+		if (!compiled.ok) {
+			errors.push(`${schemaFile}: schema compile failed: ${compiled.error}`);
+		}
+	}
+	return errors.length > 0 ? { ok: false, errors } : { ok: true };
+}
+
+/** Every `*.schema.json` $ref in specs must point at a file on disk. */
+export async function verifyHarnessSchemaRefIntegrity(
+	specsDir: string,
+): Promise<{ ok: true } | { ok: false; errors: string[] }> {
+	const errors: string[] = [];
+	const files = await listHarnessSpecSchemaFiles(specsDir);
+	for (const schemaFile of files) {
+		const schema = await loadHarnessSchema(specsDir, schemaFile);
+		const externalRefs = new Set<string>();
+		collectExternalSchemaRefs(schema, externalRefs);
+		for (const ref of externalRefs) {
+			try {
+				await loadHarnessSchema(specsDir, ref);
+			} catch {
+				errors.push(`${schemaFile}: missing $ref target ${ref}`);
+			}
+		}
+	}
+	return errors.length > 0 ? { ok: false, errors } : { ok: true };
 }
 
 export async function validateAgainstHarnessSchema(
@@ -56,23 +172,16 @@ export async function validateAgainstHarnessSchema(
 	schemaFile: string,
 	document: unknown,
 ): Promise<{ ok: true } | { ok: false; errors: string[] }> {
-	const cacheKey = `${specsDir}:${schemaFile}`;
-	let validate = compileCache.get(cacheKey);
+	const compiled = await compileHarnessSchema(specsDir, schemaFile);
+	if (!compiled.ok) {
+		return { ok: false, errors: [`schema compile failed: ${compiled.error}`] };
+	}
+	const validate = compileCache.get(`${specsDir}:${schemaFile}`);
 	if (!validate) {
-		const schemaPath = join(specsDir, schemaFile);
-		const raw = await readFile(schemaPath, "utf-8");
-		const schema = JSON.parse(raw) as Record<string, unknown>;
-		try {
-			const ajv = getAjv();
-			const compiled = ajv.compile(schema);
-			validate = compiled;
-			compileCache.set(cacheKey, compiled);
-			await debugLog("H3", "schema compile ok", { schemaFile });
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			await debugLog("H3", "schema compile failed", { schemaFile, error: msg });
-			return { ok: false, errors: [`schema compile failed: ${msg}`] };
-		}
+		return {
+			ok: false,
+			errors: [`schema compile failed: ${schemaFile} not in compile cache`],
+		};
 	}
 	const ok = validate(document);
 	if (ok) return { ok: true };

package/.pi/lib/harness-spawn-policy.ts

@@ -23,10 +23,19 @@ export interface ToolCallDecision {
 	newArgs?: Record<string, unknown>;
 }
 
+export interface EvaluateSubagentToolCallOptions {
+	/** Parent harness session — may spawn subagents; spawn policy applies only in subprocesses. */
+	isParentOrchestrator?: boolean;
+}
+
 export function evaluateSubagentToolCall(
 	toolName: string,
 	agentType?: string,
+	opts?: EvaluateSubagentToolCallOptions,
 ): ToolCallDecision {
+	if (opts?.isParentOrchestrator) {
+		return { action: "allow" };
+	}
 	if (SUBAGENT_BLOCKED_TOOLS.has(toolName)) {
 		return {
 			action: "block",

package/.pi/lib/harness-spawn-topology.ts

@@ -3,10 +3,12 @@
  */
 
 import { constants } from "node:fs";
-import { access } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { validateHarnessArtifactFile } from "./harness-artifact-gate.js";
 import type { HarnessPhase } from "./harness-run-context.js";
-import { isTaskClarificationReady } from "./plan-task-clarification.js";
+import { validateTaskClarificationReadyWithHumanGate } from "./plan-human-gates.js";
 
 export interface SpawnTopologyResult {
 	ok: boolean;
@@ -31,6 +33,21 @@ const PARALLEL_RESEARCH_AGENTS = new Set([
 	"harness/planning/stack-researcher",
 ]);
 
+/** Single-shot plan agents: one deliverable artifact per run (debate lanes excluded). */
+const PLANNING_AGENT_ARTIFACT: Record<string, string> = {
+	[PLANNING_CONTEXT_AGENT]: "artifacts/planning-context.yaml",
+	[DECOMPOSE_AGENT]: "artifacts/decomposition.yaml",
+	[HYPOTHESIS_AGENT]: "artifacts/hypothesis.yaml",
+	"harness/planning/implementation-researcher":
+		"artifacts/implementation-research.yaml",
+	"harness/planning/stack-researcher": "artifacts/stack.yaml",
+	"harness/planning/execution-plan-author":
+		"artifacts/execution-plan-draft.yaml",
+	"harness/planning/plan-synthesizer": "artifacts/execution-plan-draft.yaml",
+	"harness/sentrux-steward": "artifacts/sentrux-manifest-proposal.yaml",
+	"harness/ls-lint-steward": "artifacts/ls-lint-manifest-proposal.yaml",
+};
+
 const CLARIFICATION_GATED_AGENTS = new Set([
 	PLANNING_CONTEXT_AGENT,
 	DECOMPOSE_AGENT,
@@ -132,17 +149,32 @@ function validateParallelBatch(
 async function validateClarificationGate(
 	names: string[],
 	phase: HarnessPhase,
-	opts?: { projectRoot?: string; runId?: string | null },
+	opts?: {
+		projectRoot?: string;
+		runId?: string | null;
+		entries?: unknown[];
+		quick?: boolean;
+		taskSummary?: string;
+		lastOutcome?: string | null;
+	},
 ): Promise<string | null> {
 	if (!(phase === "plan" && opts?.projectRoot && opts?.runId)) return null;
 	const needsClar = names.some((n) => CLARIFICATION_GATED_AGENTS.has(n));
 	if (!needsClar) return null;
 	const runDir = join(opts.projectRoot, ".pi", "harness", "runs", opts.runId);
-	const clar = await isTaskClarificationReady(runDir);
+	const clar = await validateTaskClarificationReadyWithHumanGate(
+		runDir,
+		opts.entries ?? [],
+		{
+			quick: opts.quick,
+			taskSummary: opts.taskSummary,
+			lastOutcome: opts.lastOutcome,
+		},
+	);
 	if (clar.ok) return null;
 	return (
 		"Cannot spawn planning subagents before task clarification is ready. " +
-		`Complete Phase 0 and harness_artifact_ready on artifacts/task-clarification.yaml. ${clar.errors.join("; ")}`
+		`Complete Phase 0 (ask_user + harness_artifact_ready on artifacts/task-clarification.yaml). ${clar.errors.join("; ")}`
 	);
 }
 
@@ -171,6 +203,68 @@ function validatePlanPhaseMutations(
 	return `Plan phase: cannot spawn mutating subagents (${mutating.join(", ")}).`;
 }
 
+async function artifactAllowsRespawn(
+	runRoot: string,
+	artifactRel: string,
+): Promise<boolean> {
+	const abs = join(runRoot, artifactRel);
+	try {
+		await access(abs, constants.R_OK);
+	} catch {
+		return true;
+	}
+	try {
+		const raw = await readFile(abs, "utf-8");
+		const doc = parseYaml(raw) as Record<string, unknown>;
+		if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+			return true;
+		}
+		const status = String(doc.status ?? "ok").toLowerCase();
+		return status === "partial" || status === "failed" || status === "error";
+	} catch {
+		return true;
+	}
+}
+
+async function validateArtifactCompletionDedup(
+	names: string[],
+	phase: HarnessPhase,
+	opts?: {
+		projectRoot?: string;
+		runId?: string | null;
+		forceRespawn?: boolean;
+	},
+): Promise<string | null> {
+	if (phase !== "plan" || !opts?.projectRoot || !opts?.runId) return null;
+	if (opts.forceRespawn || process.env.HARNESS_FORCE_RESPAWN === "1") {
+		return null;
+	}
+
+	const runRoot = join(opts.projectRoot, ".pi", "harness", "runs", opts.runId);
+	const specsDir = join(opts.projectRoot, ".pi", "harness", "specs");
+
+	for (const name of names) {
+		const artifactRel = PLANNING_AGENT_ARTIFACT[name];
+		if (!artifactRel) continue;
+		if (await artifactAllowsRespawn(runRoot, artifactRel)) continue;
+
+		const gate = await validateHarnessArtifactFile(
+			runRoot,
+			artifactRel,
+			specsDir,
+			{ skipPrerequisites: true },
+		);
+		if (!gate.ok) continue;
+
+		return (
+			`Duplicate spawn blocked: ${name} already produced a valid ${artifactRel}. ` +
+			`Call harness_artifact_ready on that path and advance to the next plan phase instead of re-spawning. ` +
+			`To force a re-run, set HARNESS_FORCE_RESPAWN=1 or revise/delete the artifact.`
+		);
+	}
+	return null;
+}
+
 export async function validateHarnessSpawnTopology(
 	names: string[],
 	phase: HarnessPhase,
@@ -178,6 +272,11 @@ export async function validateHarnessSpawnTopology(
 		parallelTaskCount?: number;
 		projectRoot?: string;
 		runId?: string | null;
+		entries?: unknown[];
+		quick?: boolean;
+		taskSummary?: string;
+		lastOutcome?: string | null;
+		forceRespawn?: boolean;
 	},
 ): Promise<SpawnTopologyResult> {
 	const taskCount =
@@ -186,11 +285,14 @@ export async function validateHarnessSpawnTopology(
 	const parallelError = validateParallelBatch(names, taskCount);
 	if (parallelError) return { ok: false, message: parallelError };
 
+	const hypothesisError = await validateHypothesisDependency(names, opts);
+	if (hypothesisError) return { ok: false, message: hypothesisError };
+
 	const clarError = await validateClarificationGate(names, phase, opts);
 	if (clarError) return { ok: false, message: clarError };
 
-	const hypothesisError = await validateHypothesisDependency(names, opts);
-	if (hypothesisError) return { ok: false, message: hypothesisError };
+	const dedupError = await validateArtifactCompletionDedup(names, phase, opts);
+	if (dedupError) return { ok: false, message: dedupError };
 
 	const mutationError = validatePlanPhaseMutations(names, phase);
 	if (mutationError) return { ok: false, message: mutationError };

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

@@ -10,6 +10,7 @@ import { getAgentKind } from "./agents-policy.mjs";
 import { getHarnessPackageRoot } from "./harness-paths.js";
 import { type HarnessPhase, inferHarnessPhase } from "./harness-run-context.js";
 import { validateHarnessSpawnTopology } from "./harness-spawn-topology.js";
+import { shouldBlockSubagentForMissingPlanApproval } from "./plan-human-gates.js";
 
 export interface SubagentTaskRef {
 	agent: string;
@@ -23,6 +24,10 @@ export interface PrecheckResult {
 export interface PrecheckOptions {
 	projectRoot?: string;
 	runId?: string | null;
+	entries?: unknown[];
+	quick?: boolean;
+	taskSummary?: string;
+	lastOutcome?: string | null;
 }
 
 function collectAgents(params: {
@@ -98,11 +103,27 @@ export async function precheckHarnessSubagentSpawn(
 		parallelTaskCount,
 		projectRoot: opts?.projectRoot,
 		runId: opts?.runId,
+		entries: opts?.entries,
+		quick: opts?.quick,
+		taskSummary: opts?.taskSummary,
+		lastOutcome: opts?.lastOutcome,
 	});
 	if (!topology.ok) {
 		return topology;
 	}
 
+	if (phase === "plan" && opts?.projectRoot && opts?.runId && opts?.entries) {
+		const approvalBlock = await shouldBlockSubagentForMissingPlanApproval(
+			opts.projectRoot,
+			opts.runId,
+			opts.entries,
+			phase,
+		);
+		if (approvalBlock.block) {
+			return { ok: false, message: approvalBlock.reason };
+		}
+	}
+
 	const packageRoot = getHarnessPackageRoot(
 		// @ts-expect-error pi extensions run as ESM
 		import.meta.url,

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

@@ -4,13 +4,14 @@
 
 import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
 import { validateAgainstHarnessSchema } from "./harness-schema-validate.js";
 import { resolveGuardedRunDir } from "./harness-subagent-submit-path.js";
 import {
 	resolveArtifactRelPath,
 	type SubmitToolSpec,
 } from "./harness-subagent-submit-registry.js";
-import { writeYamlFile } from "./harness-yaml.js";
+import { stringifyYaml, writeYamlFile } from "./harness-yaml.js";
 import {
 	type ApplyDebateLaneResult,
 	applyDebateLaneFromDoc,
@@ -22,6 +23,34 @@ export interface SubmitPipelineResult {
 	validation_errors?: string[];
 	lane_result?: ApplyDebateLaneResult;
 	human_required?: boolean;
+	/** Artifact already passed gate with equivalent content — do not resubmit. */
+	idempotent?: boolean;
+}
+
+async function artifactBytesMatch(
+	absPath: string,
+	document: Record<string, unknown>,
+): Promise<boolean> {
+	try {
+		const existingDoc = await readYamlObject(absPath);
+		if (!existingDoc) return false;
+		return stringifyYaml(existingDoc).trim() === stringifyYaml(document).trim();
+	} catch {
+		return false;
+	}
+}
+
+async function readYamlObject(
+	absPath: string,
+): Promise<Record<string, unknown> | null> {
+	try {
+		const raw = await readFile(absPath, "utf-8");
+		const doc = parseYaml(raw) as Record<string, unknown>;
+		if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+		return doc;
+	} catch {
+		return null;
+	}
 }
 
 export async function loadSubmitDocument(opts: {
@@ -54,8 +83,7 @@ export async function loadSubmitDocument(opts: {
 	}
 	try {
 		const raw = await readFile(abs, "utf-8");
-		const { parse } = await import("yaml");
-		const doc = parse(raw) as Record<string, unknown>;
+		const doc = parseYaml(raw) as Record<string, unknown>;
 		if (!doc || typeof doc !== "object") {
 			return {
 				ok: false,
@@ -101,28 +129,50 @@ export async function executeSubmitPipeline(opts: {
 
 	const relPath = resolveArtifactRelPath(opts.spec, opts.document);
 	const absPath = join(runResolved.runDir, relPath);
-	await mkdir(dirname(absPath), { recursive: true });
-	await writeYamlFile(absPath, opts.document);
 
-	if (opts.spec.toolName === "submit_executor_handoff") {
-		const rollback = opts.document.rollback_refs;
-		if (rollback && typeof rollback === "object" && !Array.isArray(rollback)) {
-			const rollbackPath = join(
-				runResolved.runDir,
-				"artifacts",
-				"executor-rollback.yaml",
-			);
-			await mkdir(dirname(rollbackPath), { recursive: true });
-			await writeYamlFile(rollbackPath, {
-				schema_version: "1.0.0",
-				...(rollback as Record<string, unknown>),
-			});
+	const existingDoc = await readYamlObject(absPath);
+	if (existingDoc) {
+		const existingValidation = await validateAgainstHarnessSchema(
+			opts.specsDir,
+			opts.spec.schemaFile,
+			existingDoc,
+		);
+		if (
+			existingValidation.ok &&
+			(await artifactBytesMatch(absPath, opts.document))
+		) {
+			let laneResult: ApplyDebateLaneResult | undefined;
+			if (opts.spec.debateLane) {
+				laneResult = await applyDebateLaneFromDoc({
+					runDir: runResolved.runDir,
+					lane: opts.spec.debateLane,
+					doc: opts.document,
+					skipArtifactWrite: true,
+				});
+				if (!laneResult.ok) {
+					return {
+						ok: false,
+						artifact_path: relPath,
+						validation_errors: [
+							...laneResult.errors,
+							"Artifact already on disk with the same content; fix messenger/lane fields above and resubmit once (do not loop identical submits).",
+						],
+						lane_result: laneResult,
+					};
+				}
+			}
+			return {
+				ok: true,
+				artifact_path: relPath,
+				lane_result: laneResult,
+				human_required: opts.spec.humanRequired === true,
+				idempotent: true,
+			};
 		}
 	}
 
-	let laneResult: ApplyDebateLaneResult | undefined;
 	if (opts.spec.debateLane) {
-		laneResult = await applyDebateLaneFromDoc({
+		const laneResult = await applyDebateLaneFromDoc({
 			runDir: runResolved.runDir,
 			lane: opts.spec.debateLane,
 			doc: opts.document,
@@ -135,12 +185,36 @@ export async function executeSubmitPipeline(opts: {
 				lane_result: laneResult,
 			};
 		}
+		return {
+			ok: true,
+			artifact_path: relPath,
+			lane_result: laneResult,
+			human_required: opts.spec.humanRequired === true,
+		};
+	}
+
+	await mkdir(dirname(absPath), { recursive: true });
+	await writeYamlFile(absPath, opts.document);
+
+	if (opts.spec.toolName === "submit_executor_handoff") {
+		const rollback = opts.document.rollback_refs;
+		if (rollback && typeof rollback === "object" && !Array.isArray(rollback)) {
+			const rollbackPath = join(
+				runResolved.runDir,
+				"artifacts",
+				"executor-rollback.yaml",
+			);
+			await mkdir(dirname(rollbackPath), { recursive: true });
+			await writeYamlFile(rollbackPath, {
+				schema_version: "1.0.0",
+				...(rollback as Record<string, unknown>),
+			});
+		}
 	}
 
 	return {
 		ok: true,
 		artifact_path: relPath,
-		lane_result: laneResult,
 		human_required: opts.spec.humanRequired === true,
 	};
 }

package/.pi/lib/harness-subagent-submit-register.ts

@@ -146,7 +146,12 @@ export function registerHarnessSubagentSubmitTools(
 						details: result,
 					};
 				}
-				const lines = [`ok: wrote ${result.artifact_path}`];
+				const lines = result.idempotent
+					? [
+							`ok: idempotent — ${result.artifact_path} already valid with the same content`,
+							"Do NOT call this submit tool again; end the turn.",
+						]
+					: [`ok: wrote ${result.artifact_path}`];
 				if (result.lane_result?.messenger_posted) {
 					lines.push("messenger updated");
 				}

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

@@ -216,6 +216,9 @@ export function createHarnessSubagentsExtension(
 					{
 						projectRoot: ctx.cwd,
 						runId: runCtx?.run_id ?? null,
+						entries,
+						taskSummary: runCtx?.task_summary ?? undefined,
+						lastOutcome: runCtx?.last_outcome ?? undefined,
 					},
 				);
 				if (!pre.ok) {

package/.pi/lib/harness-yaml.ts

@@ -2,7 +2,8 @@
  * YAML read/write for harness plan artifacts (no JSON plan fallbacks).
  */
 
-import { readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import { parse, stringify } from "yaml";
 
 const CODE_FENCE_RE = /^```(?:ya?ml|json)?\s*\n?([\s\S]*?)```\s*$/im;
@@ -72,8 +73,15 @@ export async function writeYamlFile(
 ): Promise<void> {
 	const tmp = `${path}.tmp`;
 	const content = `${stringify(data, { indent: 2 })}\n`;
-	await writeFile(tmp, content, "utf-8");
-	await rename(tmp, path);
+	const parent = dirname(path);
+	await mkdir(parent, { recursive: true });
+	try {
+		await writeFile(tmp, content, "utf-8");
+		await rename(tmp, path);
+	} catch {
+		await mkdir(parent, { recursive: true });
+		await writeFile(path, content, "utf-8");
+	}
 }
 
 export function stringifyYaml(data: unknown): string {

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

@@ -106,12 +106,8 @@ export async function executeCreatePlan(
 		updated_at: new Date().toISOString(),
 	};
 
-	try {
-		await saveRunContextToDisk(updated);
-		await saveProjectActiveRun(updated);
-	} catch {
-		/* disk mirror best-effort */
-	}
+	await saveRunContextToDisk(updated);
+	await saveProjectActiveRun(updated);
 
 	await writePlanReviewMarkdown(deps.projectRoot, updated, planPacket, {
 		status: "committed",