@unifan/pi-review-zh 1.0.0

package/src/report.ts

@@ -0,0 +1,399 @@
+import type {
+	GateDisposition,
+	GateRunResult,
+	Issue,
+	IssueSeverity,
+	ReviewReport,
+	ReviewerRunResult,
+	Verdict,
+} from "./types.js";
+
+const EMPTY_SEVERITY: Record<IssueSeverity, number> = {
+	blocker: 0,
+	major: 0,
+	minor: 0,
+	nit: 0,
+};
+
+export interface ReviewerWorkflowResult {
+	key: string;
+	ok: boolean;
+	error?: string;
+	output?: string;
+	structuredOutput?: unknown;
+}
+
+export interface WorkflowReturnValue {
+	reviewers?: ReviewerWorkflowResult[];
+	gate?: { ok: boolean; error?: string; output?: string; structuredOutput?: unknown } | null;
+}
+
+export function coerceReviewerOutput(r: ReviewerWorkflowResult): {
+	status: "ok" | "limited" | "skipped" | "failed";
+	issues: Issue[];
+	summary: string;
+	coverage: { filesChecked: string[]; commandsRun: string[]; limitations: string[] };
+} {
+	if (!r.ok) {
+		return {
+			status: "failed",
+			issues: [],
+			summary: r.error ?? "审查专家执行失败",
+			coverage: { filesChecked: [], commandsRun: [], limitations: [r.error ?? "审查专家执行失败"] },
+		};
+	}
+	const md = r.output ?? "";
+	const skipped = /^\s*##\s*Summary\s*\n+\s*SKIPPED:/im.test(md) || /^\s*SKIPPED:/m.test(md);
+	return {
+		status: skipped ? "skipped" : "ok",
+		issues: [],
+		summary: md,
+		coverage: { filesChecked: [], commandsRun: [], limitations: [] },
+	};
+}
+
+export function coerceGateOutput(gate: WorkflowReturnValue["gate"]): {
+	status: "ok" | "limited" | "skipped" | "failed";
+	verdict?: Verdict;
+	issues: Issue[];
+	dispositions: GateDisposition[];
+	reason: string;
+} {
+	if (!gate || !gate.ok) {
+		return {
+			status: "failed",
+			issues: [],
+			dispositions: [],
+			reason: gate?.error ?? "门禁裁判执行失败",
+		};
+	}
+	const so = gate.structuredOutput;
+	if (!so || typeof so !== "object") {
+		return {
+			status: "limited",
+			issues: [],
+			dispositions: [],
+			reason: "门禁裁判未返回结构化输出",
+		};
+	}
+	const obj = so as {
+		status?: string;
+		verdict?: Verdict;
+		issues?: Issue[];
+		dispositions?: GateDisposition[];
+		reason?: string;
+	};
+	return {
+		status: obj.status === "ok" || obj.status === "limited" || obj.status === "skipped" ? obj.status : "ok",
+		verdict: obj.verdict,
+		issues: Array.isArray(obj.issues) ? obj.issues : [],
+		dispositions: Array.isArray(obj.dispositions) ? obj.dispositions : [],
+		reason: typeof obj.reason === "string" ? obj.reason : "",
+	};
+}
+
+export function reviewerRow(
+	id: string,
+	label: string,
+	res: ReviewerWorkflowResult,
+	durationMs: number,
+): ReviewerRunResult {
+	const coerced = coerceReviewerOutput(res);
+	return {
+		id,
+		label,
+		model: "(见工作流配置)",
+		ok: res.ok,
+		output: {
+			status: coerced.status,
+			issues: coerced.issues,
+			summary: coerced.summary,
+			coverage: coerced.coverage,
+		},
+		error: res.error,
+		durationMs,
+	};
+}
+
+export function computeTotals(issues: Issue[]): {
+	issues: number;
+	bySeverity: Record<IssueSeverity, number>;
+} {
+	const bySeverity = { ...EMPTY_SEVERITY };
+	for (const i of issues) bySeverity[i.severity]++;
+	return { issues: issues.length, bySeverity };
+}
+
+export function reportVerdict(
+	reviewers: ReviewerWorkflowResult[],
+	gate: { ok: boolean; structuredOutput?: unknown; error?: string } | null | undefined,
+	enforcedVerdict?: Verdict,
+): Verdict | "no-gate" | "error" | "partial" {
+	if (reviewers.length > 0 && reviewers.every((r) => coerceReviewerOutput(r).status === "failed")) return "error";
+	if (!gate || !gate.ok) return "no-gate";
+	const so = gate.structuredOutput as { status?: string } | null;
+	if (so?.status && so.status !== "ok") return "partial";
+	if (reviewers.length > 0 && reviewers.every((r) => coerceReviewerOutput(r).status === "skipped")) {
+		return enforcedVerdict === "approve" ? "comment" : enforcedVerdict ?? "comment";
+	}
+	return enforcedVerdict ?? "comment";
+}
+
+export type ReportVerdictKind = Verdict | "no-gate" | "error" | "partial";
+
+export interface ReportInput {
+	startedAt: number;
+	manifest: {
+		runId: string;
+		targetLabel: string;
+		targetKind: string;
+		prRef?: string;
+		diffSha256: string;
+		workspacePath: string;
+		workspaceHeadSha?: string;
+		workspaceWarning?: string;
+		diffWarning?: string;
+		mode?: string;
+		docsOnly: boolean;
+		rulePaths: string[];
+		historyAvailable: boolean;
+		changedFiles: string[];
+		baseSha?: string;
+		headSha?: string;
+		skippedReviewers?: Array<{ id: string; reason: string }>;
+	};
+	workflowReturn: WorkflowReturnValue;
+	threshold: number;
+	policy: "strict" | "legacy";
+	enforcedVerdict: Verdict;
+	enforcedIssues: Issue[];
+	enforcedDispositions: GateDisposition[];
+	enforcedReason: string;
+}
+
+export interface BuiltReport extends Omit<ReviewReport, "verdict"> {
+	manifest: ReportInput["manifest"];
+	dispositions: GateDisposition[];
+	reviewerStatus: Array<{ id: string; status: string; limitations: string[] }>;
+	gateStatus: "ok" | "limited" | "skipped" | "failed";
+	verdict: Verdict | "no-gate" | "error" | "partial";
+}
+
+export function buildReportFromWorkflow(input: ReportInput): BuiltReport {
+	const durationMs = Date.now() - input.startedAt;
+	const reviewerResults = (input.workflowReturn.reviewers ?? []).map((r) =>
+		reviewerRow(r.key, r.key, r, 0),
+	);
+	const reviewerStatus = (input.workflowReturn.reviewers ?? []).map((r) => {
+		const c = coerceReviewerOutput(r);
+		return { id: r.key, status: c.status, limitations: c.coverage.limitations };
+	});
+	const gateRaw = input.workflowReturn.gate ?? null;
+	const coercedGate = coerceGateOutput(gateRaw);
+	const gateResult: GateRunResult = {
+		ok: !!gateRaw?.ok,
+		verdict: {
+			verdict: input.enforcedVerdict,
+			issues: input.enforcedIssues,
+			dispositions: input.enforcedDispositions,
+			status: coercedGate.status,
+			reason: input.enforcedReason,
+		},
+		error: gateRaw?.error,
+		durationMs: 0,
+		model: "(见工作流配置)",
+	};
+	const totals = computeTotals(input.enforcedIssues);
+	const verdict = reportVerdict(input.workflowReturn.reviewers ?? [], gateRaw, input.enforcedVerdict);
+
+	return {
+		startedAt: input.startedAt,
+		durationMs,
+		input: {
+			kind: input.manifest.targetKind as ReviewReport["input"]["kind"],
+			label: input.manifest.targetLabel,
+			prRef: input.manifest.prRef,
+		},
+		reviewers: reviewerResults,
+		gate: gateResult,
+		totals,
+		verdict,
+		manifest: input.manifest,
+		dispositions: input.enforcedDispositions,
+		reviewerStatus,
+		gateStatus: coercedGate.status,
+	};
+}
+
+export function renderReport(report: BuiltReport): string {
+	const lines: string[] = [];
+	lines.push(`## 🔍 AI 代码审查报告 — ${report.input.label}`);
+	lines.push("");
+	lines.push(renderVerdictLine(report));
+	lines.push(renderSummaryLine(report));
+	lines.push("");
+	lines.push(renderRunLine(report));
+	if (report.manifest.prRef) {
+		lines.push(`- PR: ${report.manifest.prRef}`);
+	}
+	if (report.manifest.mode) {
+		lines.push(`- Diff 模式: ${report.manifest.mode}`);
+	}
+	if (report.manifest.baseSha && report.manifest.headSha) {
+		lines.push(`- 基础版本 Base: ${report.manifest.baseSha.slice(0, 12)} · 目标版本 Head: ${report.manifest.headSha.slice(0, 12)}`);
+	}
+	if (report.manifest.workspaceHeadSha) {
+		if (report.manifest.headSha) {
+			const matched = report.manifest.workspaceHeadSha === report.manifest.headSha;
+			lines.push(
+				`- 工作区 HEAD: ${report.manifest.workspaceHeadSha.slice(0, 12)}${matched ? " (与 Diff HEAD 匹配)" : " (与 Diff HEAD 不一致)"}`,
+			);
+		} else {
+			lines.push(`- 工作区 HEAD: ${report.manifest.workspaceHeadSha.slice(0, 12)}`);
+		}
+	}
+	if (report.manifest.workspaceWarning) {
+		lines.push(`- 工作区提示: ${report.manifest.workspaceWarning}`);
+	}
+	if (report.manifest.diffWarning) {
+		lines.push(`- Diff 提示: ${report.manifest.diffWarning}`);
+	}
+	lines.push(`- Diff 哈希: ${report.manifest.diffSha256.slice(0, 16)}…`);
+	lines.push(`- 工作区路径: ${report.manifest.workspacePath}`);
+	lines.push(`- Git 历史可用: ${report.manifest.historyAvailable ? "是" : "否"}`);
+	lines.push(`- 纯文档变更: ${report.manifest.docsOnly ? "是" : "否"}`);
+	if (report.manifest.rulePaths.length > 0) {
+		lines.push(`- 项目规范文件: ${report.manifest.rulePaths.join(", ")}`);
+	} else {
+		lines.push(`- 项目规范文件: (无)`);
+	}
+	lines.push("");
+
+	if (report.manifest.skippedReviewers && report.manifest.skippedReviewers.length > 0) {
+		lines.push("### ⚡ 自适应跳过的专家");
+		for (const s of report.manifest.skippedReviewers) {
+			lines.push(`- ${s.id}: ${s.reason}`);
+		}
+		lines.push("");
+	}
+
+	if (report.reviewerStatus.length > 0) {
+		lines.push("### 📊 专家审查覆盖率");
+		for (const s of report.reviewerStatus) {
+			const limit = s.limitations.length > 0 ? ` (${s.limitations.join("; ")})` : "";
+			lines.push(`- ${s.id}: ${s.status}${limit}`);
+		}
+		lines.push("");
+	}
+
+	if (report.reviewers.length > 0) {
+		lines.push("### 🕵️ 专家详细发现");
+		for (const r of report.reviewers) {
+			lines.push(renderReviewerSection(r));
+		}
+	}
+
+	if (report.gate) {
+		lines.push(renderGateSection(report.gate));
+	}
+
+	if (report.dispositions.length > 0) {
+		lines.push(renderDispositions(report.dispositions));
+	}
+
+	return lines.join("\n");
+}
+
+function renderVerdictLine(report: BuiltReport): string {
+	const v = report.verdict;
+	const label =
+		v === "no-gate"
+			? "NO GATE (无门禁)"
+			: v === "error"
+				? "ERROR (异常)"
+				: v === "partial"
+					? "PARTIAL (部分完成)"
+					: v === "approve"
+						? "APPROVE (审核通过)"
+						: v === "request_changes"
+							? "REQUEST_CHANGES (需要修改)"
+							: "COMMENT (普通建议)";
+	const t = report.totals.bySeverity;
+	return `**审查裁决: ${label}** (${t.blocker} 致命阻断 · ${t.major} 严重 · ${t.minor} 次要 · ${t.nit} 细节优化)`;
+}
+
+function renderSummaryLine(report: BuiltReport): string {
+	const dur = (report.durationMs / 1000).toFixed(1);
+	const reviewerCount = report.reviewers.length;
+	const gateCount = report.gate ? 1 : 0;
+	return `审查耗时 ${dur}s · ${reviewerCount} 个审查专家 · ${gateCount} 个门禁裁判`;
+}
+
+function renderRunLine(report: BuiltReport): string {
+	return `- 审查编号: ${report.manifest.runId}`;
+}
+
+export function renderReviewerSection(r: ReviewerRunResult): string {
+	const status = r.ok ? "已完成" : "失败";
+	const dur = (r.durationMs / 1000).toFixed(1);
+	const head = `#### ${r.id} — ${status} · 耗时 ${dur}s`;
+	if (!r.ok) {
+		return [head, "", `- ${r.error ?? "未知错误"}`, ""].join("\n");
+	}
+	const md = r.output?.summary ?? "";
+	const body: string[] = [head, ""];
+	if (md.trim()) {
+		body.push(md.trim());
+	} else {
+		body.push("- (无输出内容)");
+	}
+	body.push("");
+	return body.join("\n");
+}
+
+function renderGateSection(g: GateRunResult): string {
+	if (!g.ok) {
+		return [`### ⚖️ 门禁裁判长 (Gate) — 执行失败`, "", `- ${g.error ?? "未知错误"}`, ""].join("\n");
+	}
+	const v = g.verdict;
+	if (!v) {
+		return [`### ⚖️ 门禁裁判长 (Gate) — 完成 · 未产生裁决`, ""].join("\n");
+	}
+	const issues = v.issues;
+	return [
+		`### ⚖️ 门禁裁判长 (Gate) 综合裁决 · 耗时 ${(g.durationMs / 1000).toFixed(1)}s`,
+		"",
+		`- 最终裁决: ${v.verdict}`,
+		`- 裁决理由: ${v.reason}`,
+		`- 去重与置信度过滤后共计: ${issues.length} 个关键问题`,
+		"",
+	]
+		.concat(
+			issues.map((issue) => {
+				const loc = issue.line !== undefined ? `${issue.file}:${issue.line}` : issue.file;
+				return `- [${issue.severity.toUpperCase()} · ${issue.category} · 置信度 ${issue.confidence}] \`${loc}\` — ${issue.evidence}`;
+			}),
+		)
+		.concat([""])
+		.join("\n");
+}
+
+function renderDispositions(dispositions: GateDisposition[]): string {
+	const lines: string[] = ["### 🎯 高严重级别问题判定清单", ""];
+	const sorted = [...dispositions].sort((a, b) => {
+		if (a.decision === b.decision) return b.originalConfidence - a.originalConfidence;
+		const order = { dropped: 0, merged: 1, kept: 2 } as const;
+		return order[a.decision] - order[b.decision];
+	});
+	for (const d of sorted.slice(0, 25)) {
+		const action = d.decision === "kept" ? "保留" : d.decision === "merged" ? "合并" : "过滤/丢弃";
+		lines.push(
+			`- ${action} \`${d.fingerprint}\` · 置信度 ${d.originalConfidence}→${d.finalConfidence} · ${d.reason}`,
+		);
+	}
+	if (dispositions.length > 25) {
+		lines.push(`- … 另有 ${dispositions.length - 25} 条判定记录`);
+	}
+	lines.push("");
+	return lines.join("\n");
+}

package/src/review-report.ts

@@ -0,0 +1,279 @@
+/**
+ * Target workspace + run manifest prep.
+ *
+ * The extension owns diff acquisition + target repo checkout so the
+ * main-agent directive stays a single `subagent` call. Reviewer children
+ * share the prepared workspace as their cwd; git history, file lookups, and
+ * `gh pr diff` all work without the LLM re-fetching anything.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { PR_REF_REGEX } from "./pr-ref.js";
+import type { ReviewTarget } from "./types.js";
+
+/** Hard cap on prepared workspace age before pruning (ms). */
+export const WORKSPACE_TTL_MS = 24 * 60 * 60 * 1000;
+
+export interface RunManifest {
+	/** Stable id used in filenames, log lines, and the report entry. */
+	runId: string;
+	/** Target label (e.g. "PR 18689 (agent-fetch)"). */
+	targetLabel: string;
+	targetKind: ReviewTarget["kind"];
+	prRef?: string;
+	/** Absolute path to the reviewer-facing diff (already captured). */
+	diffPath: string;
+	/** SHA-256 of `diffPath` contents (lowercase hex). */
+	diffSha256: string;
+	/** Repo-relative changed paths (parsed from `diffPath`, not from cwd). */
+	changedFiles: string[];
+	/** Whether the diff is exclusively docs/markdown. */
+	docsOnly: boolean;
+	/** Repo-relative rule file paths (AGENTS.md / CLAUDE.md / .pi/rules/*). */
+	rulePaths: string[];
+	/** True when reviewer `git log`/`blame` will work in the workspace. */
+	historyAvailable: boolean;
+	/** Detection mode: which path produced the diff. `git-pr-fallback` is
+	 *  legacy-only (pre-0.7.1) — PR diffs now come exclusively from gh. */
+	mode: "gh-pr-diff" | "git-pr-fallback" | "local-uncommitted" | "local-vs-default";
+	/** Base + head SHA when known (PR mode or local-vs-default). */
+	baseSha?: string;
+	headSha?: string;
+	mergeBase?: string;
+	/** Absolute path to the prepared target workspace. */
+	workspacePath: string;
+	/** HEAD SHA actually checked out in the workspace, when determinable. */
+	workspaceHeadSha?: string;
+	/** Non-fatal workspace prep note surfaced in the report. */
+	workspaceWarning?: string;
+	/** True when the workspace is a plugin-owned tmpdir clone (safe to
+	 *  reclaim after the report renders); false = the user's cwd. */
+	workspaceCloned?: boolean;
+	/** Absolute path to the run directory (manifest + diff + history live here). */
+	runDir: string;
+	createdAt: number;
+	/** Lanes adaptive routing dropped up front (id + reason), for report coverage. */
+	skippedReviewers?: Array<{ id: string; reason: string }>;
+	/** Reviewer ids fanned out by THIS run — the report tool rejects findings from anything else. */
+	reviewerIds?: string[];
+	/** Non-fatal note about the acquired diff (e.g. stale-base fallback). */
+	diffWarning?: string;
+}
+
+export interface PrepInput {
+	cwd: string;
+	target: ReviewTarget;
+	prRepo?: { owner: string; repo: string };
+}
+
+/** Per-reviewer path inside `.pi/pi-review/runs/<runId>/`. */
+export function runDirFor(cwd: string, runId: string): string {
+	return join(cwd, ".pi", "pi-review", "runs", runId);
+}
+
+/** Create the prepared run dir + workspace. */
+export function ensureRunDir(cwd: string, runId: string): string {
+	const runDir = runDirFor(cwd, runId);
+	mkdirSync(runDir, { recursive: true });
+	return runDir;
+}
+
+/** Prune run dirs older than `WORKSPACE_TTL_MS`. */
+export function pruneStaleRuns(cwd: string, now = Date.now()): string[] {
+	const runsRoot = join(cwd, ".pi", "pi-review", "runs");
+	if (!existsSync(runsRoot)) return [];
+	const removed: string[] = [];
+	for (const entry of safeListDir(runsRoot)) {
+		const path = join(runsRoot, entry);
+		const stat = safeStat(path);
+		if (!stat) continue;
+		if (now - stat.mtimeMs > WORKSPACE_TTL_MS) {
+			try {
+				rmSync(path, { recursive: true, force: true });
+				removed.push(path);
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+	return removed;
+}
+
+function safeListDir(p: string): string[] {
+	try {
+		return readdirSync(p);
+	} catch {
+		return [];
+	}
+}
+void safeListDir; // keep tree-shaker honest
+
+function safeStat(p: string): { mtimeMs: number } | null {
+	try {
+		return statSync(p);
+	} catch {
+		return null;
+	}
+}
+void safeStat;
+
+/** Stable, URL-safe run id (timestamp + 6 random hex chars). */
+export function generateRunId(now = Date.now()): string {
+	const rand = Math.random().toString(16).slice(2, 8).padEnd(6, "0");
+	return `${now.toString(36)}-${rand}`;
+}
+
+export interface GhExec {
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+}
+
+/** Spawn `gh` (or `git`) and capture output. Tests inject a fake. */
+export type RunCmd = (
+	cmd: string,
+	args: string[],
+	opts: { cwd: string },
+) => Promise<GhExec>;
+
+let _runCmd: RunCmd = defaultRunCmd;
+export function setRunCmd(fn: RunCmd): void {
+	_runCmd = fn;
+}
+export function resetRunCmd(): void {
+	_runCmd = defaultRunCmd;
+}
+
+async function defaultRunCmd(cmd: string, args: string[], opts: { cwd: string }): Promise<GhExec> {
+	return new Promise((resolve) => {
+		try {
+			const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
+			let stdout = "";
+			let stderr = "";
+			child.stdout?.setEncoding("utf-8");
+			child.stderr?.setEncoding("utf-8");
+			child.stdout?.on("data", (d: string) => (stdout += d));
+			child.stderr?.on("data", (d: string) => (stderr += d));
+			child.on("error", () => resolve({ stdout, stderr, exitCode: 1 }));
+			child.on("close", (code) => resolve({ stdout, stderr, exitCode: code ?? 1 }));
+		} catch (err) {
+			resolve({ stdout: "", stderr: err instanceof Error ? err.message : "spawn failed", exitCode: 1 });
+		}
+	});
+}
+
+export function sha256Hex(buf: string | Buffer): string {
+	return createHash("sha256").update(buf).digest("hex");
+}
+
+/** Parse changed paths + docsOnly flag from a captured diff. */
+export function parseChangedFilesFromDiff(diff: string): {
+	files: string[];
+	docsOnly: boolean;
+	additions: number;
+	deletions: number;
+} {
+	const files: string[] = [];
+	const seen = new Set<string>();
+	let additions = 0;
+	let deletions = 0;
+	for (const line of diff.split("\n")) {
+		if (line.startsWith("diff --git ")) {
+			const m = line.match(/^diff --git a\/(.+) b\/(.+)$/);
+			const file = m?.[2] ?? "";
+			if (file && !seen.has(file)) {
+				seen.add(file);
+				files.push(file);
+			}
+		} else if (line.startsWith("+") && !line.startsWith("+++")) {
+			additions++;
+		} else if (line.startsWith("-") && !line.startsWith("---")) {
+			deletions++;
+		}
+	}
+	const docsOnly =
+		files.length > 0 &&
+		files.every((f) =>
+			/\.(md|mdx|txt|rst)$/i.test(f) ||
+			f.startsWith("docs/") ||
+			f.startsWith(".agents/") ||
+			f.startsWith(".pi/") ||
+			f.includes("/docs/") ||
+			/CHANGELOG|LICENSE|README/i.test(f),
+		);
+	return { files, docsOnly, additions, deletions };
+}
+
+export function discoverRulePathsLocal(cwd: string): string[] {
+	const candidates = ["AGENTS.md", "CLAUDE.md", "CONVENTIONS.md", ".pi/conventions.md"];
+	const found: string[] = [];
+	for (const name of candidates) {
+		if (existsSync(join(cwd, name))) found.push(name);
+	}
+	for (const rulesDir of [join(cwd, ".pi", "rules"), join(cwd, ".agents", "rules")]) {
+		if (!existsSync(rulesDir)) continue;
+	try {
+		const list = readdirSync(rulesDir) as string[];
+			for (const entry of list) {
+				if (typeof entry === "string" && entry.endsWith(".md")) {
+					found.push(
+						rulesDir.includes(".agents/rules") ? join(".agents/rules", entry) : join(".pi/rules", entry),
+					);
+				}
+			}
+		} catch {
+			/* ignore */
+		}
+	}
+	return [...new Set(found)];
+}
+
+/** Parse a GitHub PR URL or "owner/repo#number" into structured pieces. */
+export function parsePrRepo(prRef: string): { owner: string; repo: string; number: string } | null {
+	const m = prRef.match(PR_REF_REGEX);
+	if (!m) return null;
+	return { owner: m[1]!, repo: m[2]!, number: m[3]! };
+}
+
+void PR_REF_REGEX;
+
+/** Read a manifest from disk (paranoia: corrupted files throw). */
+export function readManifest(runDir: string): RunManifest {
+	const path = join(runDir, "manifest.json");
+	const raw = readFileSync(path, "utf-8");
+	return JSON.parse(raw) as RunManifest;
+}
+
+export function writeManifest(runDir: string, manifest: RunManifest): void {
+	writeFileSync(join(runDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+
+/** Write the diff body to a deterministic path inside the run dir. */
+export function writeDiff(runDir: string, diff: string): string {
+	const path = join(runDir, "change.diff");
+	writeFileSync(path, diff, "utf-8");
+	return path;
+}
+
+/** Cheap scratch path under tmp/ — never used by reviewers. */
+export function localScratchDir(prefix: string): string {
+	const dir = join(tmpdir(), `pi-review-${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+export const _INTERNAL = {
+	WORKSPACE_TTL_MS,
+};