kcode-pi 0.1.24 → 0.1.27

package/docs/CHANGELOG.md

@@ -6,6 +6,42 @@
 
 - 暂无。
 
+## 0.1.27 - 2026-06-07
+
+### 修复
+
+- 强化 active run / RUN.json 读取容错，过滤异常 `questions`、`artifacts`、`riskAssessment`、`gate` 字段，避免旧状态或坏状态触发门禁崩溃。
+- Header 渲染门禁时增加兜底，门禁异常会显示为阻塞状态，不再导致 TUI 进程退出。
+- 阶段产物存在但不可读或误建为目录时，现在按缺失处理，不再在读取 `CONTEXT.md`、`PLAN.md`、`EXECUTION.md` 等文件时抛出异常。
+
+### 验证
+
+- `npm run smoke:harness` 通过，覆盖损坏 run state 和损坏 evidence index 的容错。
+
+## 0.1.26 - 2026-06-07
+
+### 修复
+
+- 修复已有项目的 `evidence/index.json` 中存在异常 entry 时，Header 门禁渲染可能因读取 `path` 崩溃的问题。
+- `readEvidenceIndex` 现在会过滤无效 evidence entry，`hasEvidenceEntry` 和 evidence 记录逻辑对坏数据保持容错。
+
+### 验证
+
+- `npm run smoke:harness` 通过，覆盖损坏 evidence index 不再触发崩溃。
+
+## 0.1.25 - 2026-06-07
+
+### 修复
+
+- 修复 `/kd-risk`、`/kd-product`、`/kd-answer`、`/kd-artifact` 等命令在解除门禁后不会自动尝试推进下一阶段的问题。
+- 修复 `kd_question` 回答阻断问题后只刷新门禁、不尝试推进的问题。
+- 修复 `kd_cosmic_config`、`kd_cosmic_metadata`、`kd_cosmic_api`、`kd_sdk_signature`、`kd_ksql_lint` 写入证据后不反馈自动推进结果的问题。
+- 修复官方 evidence 只要文件存在就可能满足门禁的问题；现在要求 evidence index 中记录的退出码为 `0`。
+
+### 验证
+
+- `npm run smoke:harness` 通过，覆盖阻断问题回答后的自动推进、风险更新后的自动推进尝试，以及失败 evidence 不能通过门禁。
+
 ## 0.1.24 - 2026-06-07
 
 ### 新增

package/extensions/kingdee-harness.ts

@@ -4,6 +4,7 @@ import { formatStatus } from "../src/harness/format.ts";
 import { PHASE_ORDER, isKdPhase, type KdPhase } from "../src/harness/types.ts";
 import {
 	advanceRun,
+	advanceRunIfReady,
 	addQuestion,
 	answerQuestion,
 	createActiveRun,
@@ -109,6 +110,26 @@ function sendWorkflowPrompt(pi: ExtensionAPI, ctx: ExtensionContext, run: NonNul
 	if (ctx.hasUI) ctx.ui.notify("KCode 工作流消息已排队。", "info");
 }
 
+function autoAdvanceCommand(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	run: NonNullable<ReturnType<typeof readActiveRun>>,
+	reason: string,
+): ReturnType<typeof advanceRunIfReady> {
+	const result = advanceRunIfReady(ctx.cwd, run);
+	if (result.advanced) {
+		if (ctx.hasUI) ctx.ui.notify(result.message, "info");
+		sendWorkflowPrompt(pi, ctx, result.run, `${reason}\n继续 KCode Harness run ${result.run.id}：${result.run.goal ?? "未知需求"}`);
+	} else if (!result.message.includes("最终阶段")) {
+		if (ctx.hasUI) ctx.ui.notify(`门禁仍阻塞：${result.message}`, "warning");
+	}
+	return result;
+}
+
+function autoAdvanceTool(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>): ReturnType<typeof advanceRunIfReady> {
+	return advanceRunIfReady(cwd, run);
+}
+
 function codeWriteBlockReason(cwd: string, path: string | undefined): string | undefined {
 	if (!path || !isSourceLikePath(path)) return undefined;
 
@@ -188,9 +209,10 @@ const kdQuestionTool = defineTool({
 				};
 			}
 			appendQuestionEventToArtifact(ctx.cwd, run, [`- 已回答 ${answered.id}：${answered.answer}`]);
+			const auto = autoAdvanceTool(ctx.cwd, run);
 			return {
-				content: [{ type: "text", text: `已记录 ${answered.id} 的答案，并刷新门禁。` }],
-				details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate },
+				content: [{ type: "text", text: `已记录 ${answered.id} 的答案。${auto.advanced ? auto.message : `门禁仍阻塞：${auto.message}`}` }],
+				details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate, autoAdvance: auto },
 			};
 		}
 
@@ -240,9 +262,10 @@ const kdQuestionTool = defineTool({
 			const answered = answerQuestion(ctx.cwd, run, question.id, interactiveAnswer);
 			if (answered) {
 				appendQuestionEventToArtifact(ctx.cwd, run, [`- 已回答 ${answered.id}：${answered.answer}`]);
+				const auto = autoAdvanceTool(ctx.cwd, run);
 				return {
-					content: [{ type: "text", text: `用户已回答 ${answered.id}：${answered.answer}` }],
-					details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate, answered: true },
+					content: [{ type: "text", text: `用户已回答 ${answered.id}：${answered.answer}。${auto.advanced ? auto.message : `门禁仍阻塞：${auto.message}`}` }],
+					details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate, answered: true, autoAdvance: auto },
 				};
 			}
 		}
@@ -427,6 +450,7 @@ export default function (pi: ExtensionAPI) {
 
 			const updated = updateProductProfile(ctx.cwd, run, parsed.product, parsed.version);
 			ctx.ui.notify(`产品画像：${updated.profile?.product}/${updated.profile?.techStack}/${updated.profile?.language}`, "info");
+			autoAdvanceCommand(pi, ctx, updated, "产品画像已更新。");
 		},
 	});
 
@@ -447,6 +471,7 @@ export default function (pi: ExtensionAPI) {
 
 			const updated = updateRisk(ctx.cwd, run, risk.risk, risk.reason);
 			ctx.ui.notify(`风险等级：${updated.riskAssessment?.level}（${updated.riskAssessment?.reason}）`, "info");
+			autoAdvanceCommand(pi, ctx, updated, "风险评估已更新。");
 		},
 	});
 
@@ -498,6 +523,7 @@ export default function (pi: ExtensionAPI) {
 				? updatePhaseArtifact(ctx.cwd, run, parsed.phase, parsed.content)
 				: ensurePhaseArtifact(ctx.cwd, run, parsed.phase);
 			ctx.ui.notify(`阶段文档已就绪：${path}`, "info");
+			autoAdvanceCommand(pi, ctx, readActiveRun(ctx.cwd) ?? run, `${parsed.phase} 阶段文档已更新。`);
 		},
 	});
 
@@ -522,6 +548,7 @@ export default function (pi: ExtensionAPI) {
 			}
 			appendQuestionEventToArtifact(ctx.cwd, run, [`- 已回答 ${answered.id}：${answered.answer}`]);
 			ctx.ui.notify(`已记录 ${answered.id} 的答案`, "info");
+			autoAdvanceCommand(pi, ctx, readActiveRun(ctx.cwd) ?? run, `${answered.id} 已回答。`);
 		},
 	});
 }

package/extensions/kingdee-header.ts

@@ -19,6 +19,19 @@ function formatGate(gate: GateResult | undefined): string {
 	return gate.passed ? "门禁：通过" : "门禁：阻塞";
 }
 
+function safeInspectGate(cwd: string, run: ActiveRun | undefined): GateResult | undefined {
+	if (!run) return undefined;
+	try {
+		return inspectGate(cwd, run);
+	} catch (error) {
+		return {
+			passed: false,
+			reason: error instanceof Error ? error.message : String(error),
+			checkedAt: new Date().toISOString(),
+		};
+	}
+}
+
 function riskLevel(run: ActiveRun | undefined): string {
 	return run?.riskAssessment?.level ?? "未知";
 }
@@ -54,7 +67,7 @@ export default function (pi: ExtensionAPI) {
 			return {
 				render(width: number): string[] {
 					const run = readActiveRun(ctx.cwd);
-					const gateState = run ? inspectGate(ctx.cwd, run) : undefined;
+					const gateState = safeInspectGate(ctx.cwd, run);
 					const phase = formatPhase(run?.phase);
 					const product = formatProduct(run);
 					const gate = formatGate(gateState);

package/extensions/kingdee-tools.ts

@@ -22,7 +22,7 @@ import {
 	writeOfficialEvidence,
 } from "../src/official/kingdee-skills.ts";
 import { resolveWorkspacePath } from "../src/platform/path.ts";
-import { readActiveRun } from "../src/harness/state.ts";
+import { advanceRunIfReady, readActiveRun } from "../src/harness/state.ts";
 import { writeEvidenceFile } from "../src/harness/evidence.ts";
 import { SDK_SIGNATURE_EVIDENCE } from "../src/harness/sdk-policy.ts";
 
@@ -97,12 +97,25 @@ async function runOrDryRun(
 
 	const result = await runOfficialCommand(command);
 	const evidencePath = evidenceFile ? writeOfficialEvidence(ctx.cwd, evidenceFile, result) : undefined;
+	const autoAdvance = evidencePath ? autoAdvanceAfterEvidence(ctx.cwd) : undefined;
 	return {
-		content: [{ type: "text" as const, text: formatCommandResult(result) }],
-		details: { command: result.command, exitCode: result.exitCode, evidencePath },
+		content: [{ type: "text" as const, text: [formatCommandResult(result), evidencePath ? `已写入证据：${evidencePath}` : undefined, autoAdvance?.text].filter(Boolean).join("\n\n") }],
+		details: { command: result.command, exitCode: result.exitCode, evidencePath, autoAdvance: autoAdvance?.details },
 	};
 }
 
+function autoAdvanceAfterEvidence(cwd: string): { text: string; details: ReturnType<typeof advanceRunIfReady> } | undefined {
+	const run = readActiveRun(cwd);
+	if (!run) return undefined;
+
+	const result = advanceRunIfReady(cwd, run);
+	if (result.advanced) {
+		return { text: result.message, details: result };
+	}
+	if (result.message.includes("最终阶段")) return undefined;
+	return { text: `门禁仍阻塞：${result.message}`, details: result };
+}
+
 const kdSearchTool = defineTool({
 	name: "kd_search",
 	label: "KD 搜索",
@@ -334,9 +347,10 @@ const kdSdkSignatureTool = defineTool({
 		});
 		const text = formatSdkSignatureResult(result);
 		const evidencePath = result.exitCode === 0 ? writeSdkSignatureEvidence(ctx.cwd, text) : undefined;
+		const autoAdvance = evidencePath ? autoAdvanceAfterEvidence(ctx.cwd) : undefined;
 		return {
-			content: [{ type: "text", text: evidencePath ? `${text}\n\n已写入 SDK 签名证据：${evidencePath}` : text }],
-			details: { product: profile.product, evidencePath, ...result },
+			content: [{ type: "text", text: [text, evidencePath ? `已写入 SDK 签名证据：${evidencePath}` : undefined, autoAdvance?.text].filter(Boolean).join("\n\n") }],
+			details: { product: profile.product, evidencePath, autoAdvance: autoAdvance?.details, ...result },
 		};
 	},
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.24",
+  "version": "0.1.27",
   "description": "面向金蝶开发的 Pi Coding Agent 启动器、工具包和 Harness 工作流",
   "type": "module",
   "private": false,

package/src/harness/artifacts.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import type { ActiveRun, KdPhase } from "./types.ts";
 import { PHASE_ARTIFACTS } from "./types.ts";
 import { runArtifactPath, runRoot } from "./paths.ts";
@@ -10,7 +10,11 @@ export function ensureRunDirectories(cwd: string, run: ActiveRun): void {
 }
 
 export function artifactExists(cwd: string, run: ActiveRun, artifactName: string): boolean {
-	return existsSync(runArtifactPath(cwd, run, artifactName));
+	try {
+		return statSync(runArtifactPath(cwd, run, artifactName)).isFile();
+	} catch {
+		return false;
+	}
 }
 
 export function phaseArtifactPath(cwd: string, run: ActiveRun, phase: KdPhase): string {
@@ -19,7 +23,11 @@ export function phaseArtifactPath(cwd: string, run: ActiveRun, phase: KdPhase):
 
 export function readArtifact(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
 	const path = phaseArtifactPath(cwd, run, phase);
-	return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+	try {
+		return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+	} catch {
+		return undefined;
+	}
 }
 
 export function writeArtifact(cwd: string, run: ActiveRun, phase: KdPhase, content: string): string {

package/src/harness/evidence.ts

@@ -28,8 +28,9 @@ export function readEvidenceIndex(cwd: string, run: ActiveRun): EvidenceIndex {
 	const path = evidenceIndexPath(cwd, run);
 	if (!existsSync(path)) return { version: 1, entries: [] };
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf8")) as EvidenceIndex;
-		return parsed.version === 1 && Array.isArray(parsed.entries) ? parsed : { version: 1, entries: [] };
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<EvidenceIndex>;
+		if (parsed.version !== 1 || !Array.isArray(parsed.entries)) return { version: 1, entries: [] };
+		return { version: 1, entries: parsed.entries.filter(isEvidenceEntry) };
 	} catch {
 		return { version: 1, entries: [] };
 	}
@@ -37,6 +38,7 @@ export function readEvidenceIndex(cwd: string, run: ActiveRun): EvidenceIndex {
 
 export function hasEvidenceEntry(cwd: string, run: ActiveRun, path: string): boolean {
 	const normalized = normalizeEvidencePath(path);
+	if (!normalized) return false;
 	return readEvidenceIndex(cwd, run).entries.some((entry) => normalizeEvidencePath(entry.path) === normalized);
 }
 
@@ -48,7 +50,7 @@ export function writeEvidenceFile(
 	options: { kind?: string; command?: string; exitCode?: number } = {},
 ): string {
 	const normalized = normalizeEvidencePath(path);
-	if (!normalized.startsWith("evidence/") || normalized === EVIDENCE_INDEX) {
+	if (!normalized || !normalized.startsWith("evidence/") || normalized === EVIDENCE_INDEX) {
 		throw new Error(`非法 evidence 路径：${path}`);
 	}
 
@@ -66,6 +68,7 @@ export function recordEvidence(
 	options: { kind?: string; command?: string; exitCode?: number } = {},
 ): void {
 	const normalized = normalizeEvidencePath(path);
+	if (!normalized) return;
 	const absolutePath = join(runRoot(cwd, run), normalized);
 	if (!existsSync(absolutePath)) return;
 
@@ -96,11 +99,19 @@ export function recordEvidence(
 	writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`, "utf8");
 }
 
+function isEvidenceEntry(value: unknown): value is EvidenceEntry {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const entry = value as Partial<EvidenceEntry>;
+	return typeof entry.path === "string" && entry.path.trim().length > 0;
+}
+
 function inferKind(path: string): string {
 	const name = path.split("/").at(-1) ?? path;
 	return name.replace(/\.(md|txt|json)$/i, "");
 }
 
-function normalizeEvidencePath(path: string): string {
-	return path.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^\.\//, "");
+function normalizeEvidencePath(path: unknown): string | undefined {
+	if (typeof path !== "string") return undefined;
+	const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^\.\//, "");
+	return normalized.trim() || undefined;
 }

package/src/harness/gates.ts

@@ -9,7 +9,7 @@ import { executionStepsBlockReason, planStepsBlockReason } from "./plan-steps.ts
 import { tddPlanBlockReason, tddVerifyBlockReason } from "./tdd-policy.ts";
 import { SDK_SIGNATURE_EVIDENCE, hasValidSdkSignatureEvidence, requiresSdkSignatureEvidence } from "./sdk-policy.ts";
 import { runRoot } from "./paths.ts";
-import { EVIDENCE_INDEX, hasEvidenceEntry } from "./evidence.ts";
+import { EVIDENCE_INDEX, readEvidenceIndex } from "./evidence.ts";
 import {
 	missingArtifactsReason,
 	missingEvidenceReason,
@@ -129,7 +129,7 @@ function productImplementationDeclaration(cwd: string, run: ActiveRun): boolean
 function hasRiskAssessment(cwd: string, run: ActiveRun): boolean {
 	const level = run.riskAssessment?.level;
 	if (!level) return false;
-	if (run.riskAssessment?.reason.trim()) return true;
+	if (typeof run.riskAssessment?.reason === "string" && run.riskAssessment.reason.trim()) return true;
 	return riskSectionHasContent(readArtifact(cwd, run, "verify") ?? "") || riskSectionHasContent(readArtifact(cwd, run, "ship") ?? "");
 }
 
@@ -143,7 +143,7 @@ function riskSectionHasContent(content: string): boolean {
 }
 
 function inspectOpenQuestions(run: ActiveRun): string | undefined {
-	const open = (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
+	const open = Array.isArray(run.questions) ? run.questions.filter((question) => question.status === "open" && question.blocking) : [];
 	if (open.length === 0) return undefined;
 	return openQuestionsReason(open);
 }
@@ -212,7 +212,13 @@ function requiredEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase):
 function evidenceArtifactSatisfied(cwd: string, run: ActiveRun, artifact: string): boolean {
 	if (artifact === SDK_SIGNATURE_EVIDENCE) return hasValidSdkSignatureEvidence(cwd, run);
 	if (artifact === EVIDENCE_INDEX) return existsSync(join(runRoot(cwd, run), artifact));
-	return existsSync(join(runRoot(cwd, run), artifact)) && hasEvidenceEntry(cwd, run, artifact);
+	return existsSync(join(runRoot(cwd, run), artifact)) && hasSuccessfulEvidenceEntry(cwd, run, artifact);
+}
+
+function hasSuccessfulEvidenceEntry(cwd: string, run: ActiveRun, artifact: string): boolean {
+	const normalized = artifact.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^\.\//, "");
+	const entry = readEvidenceIndex(cwd, run).entries.find((item) => typeof item.path === "string" && item.path.replace(/\\/g, "/") === normalized);
+	return Boolean(entry && entry.exitCode === 0);
 }
 
 function planHasMetadataRequirement(cwd: string, run: ActiveRun): boolean {

package/src/harness/state.ts

@@ -100,7 +100,7 @@ export function addQuestion(
 	run: ActiveRun,
 	input: { question: string; reason?: string; choices?: string[]; blocking?: boolean },
 ): KdQuestion {
-	const existing = run.questions ?? [];
+	const existing = Array.isArray(run.questions) ? run.questions : [];
 	const question: KdQuestion = {
 		id: createQuestionId(existing.length + 1),
 		phase: run.phase,
@@ -118,7 +118,7 @@ export function addQuestion(
 }
 
 export function answerQuestion(cwd: string, run: ActiveRun, id: string, answer: string): KdQuestion | undefined {
-	const question = (run.questions ?? []).find((item) => item.id === id);
+	const question = (Array.isArray(run.questions) ? run.questions : []).find((item) => item.id === id);
 	if (!question) return undefined;
 	question.status = "answered";
 	question.answer = answer.trim();
@@ -129,7 +129,7 @@ export function answerQuestion(cwd: string, run: ActiveRun, id: string, answer:
 }
 
 export function openBlockingQuestions(run: ActiveRun): KdQuestion[] {
-	return (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
+	return (Array.isArray(run.questions) ? run.questions : []).filter((question) => question.status === "open" && question.blocking);
 }
 
 export function updateProductProfile(cwd: string, run: ActiveRun, productInput: string, version?: string): ActiveRun {
@@ -189,6 +189,21 @@ export function advanceRun(cwd: string, run: ActiveRun, requestedPhase?: KdPhase
 	return { run, message: `已推进 Kingdee run 到阶段：${target}` };
 }
 
+export function advanceRunIfReady(cwd: string, run: ActiveRun): { run: ActiveRun; advanced: boolean; message: string } {
+	const current = readRun(cwd, run.id) ?? run;
+	const target = nextPhase(current.phase);
+	if (!target) {
+		return { run: current, advanced: false, message: `Run 已处于最终阶段：${current.phase}` };
+	}
+
+	const result = advanceRun(cwd, current, target);
+	return {
+		run: result.run,
+		advanced: result.run.phase === target,
+		message: result.message,
+	};
+}
+
 export function refreshGate(cwd: string, run: ActiveRun): ActiveRun {
 	run.gate = inspectGate(cwd, run);
 	writeActiveRun(cwd, run);
@@ -202,19 +217,75 @@ function writeRunState(cwd: string, run: ActiveRun): void {
 }
 
 function hydrateRun(parsed: ActiveRun): ActiveRun | undefined {
-	if (!parsed.id || !isKdPhase(parsed.phase)) return undefined;
-	parsed.artifacts ??= {};
-	parsed.questions ??= [];
-	parsed.status ??= "active";
-	parsed.createdAt ??= parsed.updatedAt;
-	parsed.updatedAt ??= parsed.createdAt;
+	if (!parsed || typeof parsed !== "object") return undefined;
+	if (typeof parsed.id !== "string" || !parsed.id.trim()) return undefined;
+	if (typeof parsed.phase !== "string" || !isKdPhase(parsed.phase)) return undefined;
+	parsed.id = parsed.id.trim();
+	parsed.artifacts = isPlainObject(parsed.artifacts) ? sanitizeArtifacts(parsed.artifacts) : {};
+	parsed.questions = Array.isArray(parsed.questions) ? parsed.questions.map(sanitizeQuestion).filter((question): question is KdQuestion => Boolean(question)) : [];
+	parsed.status = parsed.status === "paused" || parsed.status === "done" ? parsed.status : "active";
+	parsed.goal = typeof parsed.goal === "string" ? parsed.goal : undefined;
+	parsed.version = typeof parsed.version === "string" ? parsed.version : undefined;
+	parsed.createdAt = typeof parsed.createdAt === "string" ? parsed.createdAt : typeof parsed.updatedAt === "string" ? parsed.updatedAt : undefined;
+	parsed.updatedAt = typeof parsed.updatedAt === "string" ? parsed.updatedAt : parsed.createdAt;
 	const legacyEdition = (parsed as ActiveRun & { edition?: string }).edition;
-	parsed.profile = parsed.profile ?? profileForProduct(parsed.product ?? resolveProductProfile(legacyEdition).product);
+	const product = typeof parsed.profile?.product === "string" ? parsed.profile.product : typeof parsed.product === "string" ? parsed.product : resolveProductProfile(typeof legacyEdition === "string" ? legacyEdition : undefined).product;
+	parsed.profile = profileForProduct(product);
 	parsed.product = parsed.profile.product;
-	parsed.gate ??= { passed: false, checkedAt: new Date().toISOString() };
+	parsed.riskAssessment = sanitizeRiskAssessment(parsed.riskAssessment);
+	parsed.gate = sanitizeGate(parsed.gate);
 	return parsed;
 }
 
+function sanitizeArtifacts(value: Record<string, unknown>): Record<string, string> {
+	return Object.fromEntries(Object.entries(value).filter((entry): entry is [string, string] => typeof entry[0] === "string" && typeof entry[1] === "string"));
+}
+
+function sanitizeQuestion(value: unknown): KdQuestion | undefined {
+	if (!isPlainObject(value)) return undefined;
+	const phase = typeof value.phase === "string" && isKdPhase(value.phase) ? value.phase : undefined;
+	const question = typeof value.question === "string" ? value.question.trim() : "";
+	if (!phase || !question) return undefined;
+	const id = typeof value.id === "string" && value.id.trim() ? value.id.trim() : createQuestionId(1);
+	return {
+		id,
+		phase,
+		question,
+		reason: typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : undefined,
+		choices: Array.isArray(value.choices) ? value.choices.filter((choice): choice is string => typeof choice === "string" && Boolean(choice.trim())).map((choice) => choice.trim()) : undefined,
+		blocking: value.blocking !== false,
+		status: value.status === "answered" ? "answered" : "open",
+		answer: typeof value.answer === "string" ? value.answer : undefined,
+		createdAt: typeof value.createdAt === "string" ? value.createdAt : new Date().toISOString(),
+		answeredAt: typeof value.answeredAt === "string" ? value.answeredAt : undefined,
+	};
+}
+
+function sanitizeRiskAssessment(value: unknown): ActiveRun["riskAssessment"] {
+	if (!isPlainObject(value)) return undefined;
+	const level = value.level;
+	if (level !== "low" && level !== "medium" && level !== "high") return undefined;
+	return {
+		level,
+		reason: typeof value.reason === "string" ? value.reason : "",
+		source: value.source === "verify" || value.source === "ship" ? value.source : "manual",
+		updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : new Date().toISOString(),
+	};
+}
+
+function sanitizeGate(value: unknown): ActiveRun["gate"] {
+	if (!isPlainObject(value)) return { passed: false, checkedAt: new Date().toISOString() };
+	return {
+		passed: value.passed === true,
+		reason: typeof value.reason === "string" ? value.reason : undefined,
+		checkedAt: typeof value.checkedAt === "string" ? value.checkedAt : new Date().toISOString(),
+	};
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 function createRunId(goal: string): string {
 	const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "").replace("T", "-");
 	const slug = goal