patchwarden 1.5.1 → 1.6.2

package/scripts/release/desktop-preflight.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+const desktopRoot = join(root, "desktop");
+const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+const argv = process.argv.slice(2);
+const requireClean = argv.includes("--require-clean");
+const skipUiSmoke = argv.includes("--skip-ui-smoke");
+
+function option(name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+}
+
+function json(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function directoryStats(directory) {
+  let files = 0;
+  let bytes = 0;
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      const nested = directoryStats(path);
+      files += nested.files;
+      bytes += nested.bytes;
+    } else if (entry.isFile()) {
+      files += 1;
+      bytes += statSync(path).size;
+    }
+  }
+  return { files, bytes };
+}
+
+function spawnSpec(command, args) {
+  if (process.platform === "win32" && /\.cmd$/i.test(command)) {
+    return { command: process.env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", command, ...args] };
+  }
+  return { command, args };
+}
+
+function capture(command, args, cwd = root) {
+  const spec = spawnSpec(command, args);
+  const result = spawnSync(spec.command, spec.args, { cwd, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed: ${result.stderr || result.stdout || result.error?.message || "unknown error"}`);
+  return String(result.stdout || "").trim();
+}
+
+const rootPackage = json(join(root, "package.json"));
+const rootLock = json(join(root, "package-lock.json"));
+const desktopPackage = json(join(desktopRoot, "package.json"));
+const desktopLock = json(join(desktopRoot, "package-lock.json"));
+const versionSource = readFileSync(join(root, "src", "version.ts"), "utf8");
+const sourceVersion = versionSource.match(/PATCHWARDEN_VERSION\s*=\s*"([^"]+)"/)?.[1] || null;
+const versions = [rootPackage.version, rootLock.version, rootLock.packages?.[""]?.version, desktopPackage.version, desktopLock.version, desktopLock.packages?.[""]?.version, sourceVersion];
+if (versions.some((version) => version !== rootPackage.version)) throw new Error(`Version mismatch: ${versions.join(", ")}`);
+if (process.platform !== "win32") throw new Error("Desktop preflight requires Windows.");
+
+const gitStatus = capture("git", ["status", "--porcelain=v1", "-z"]);
+const changedFileCount = gitStatus ? gitStatus.split("\0").filter(Boolean).length : 0;
+if (requireClean && changedFileCount > 0) throw new Error(`Release preflight requires a clean worktree; found ${changedFileCount} changed paths.`);
+
+const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+const defaultOutput = join(root, "release", `desktop-preflight-${rootPackage.version}-${stamp}`);
+const outputRoot = resolve(option("--output") || defaultOutput);
+if (existsSync(outputRoot)) throw new Error(`Preflight output already exists: ${outputRoot}`);
+mkdirSync(outputRoot, { recursive: true });
+
+const report = {
+  schema_version: "patchwarden-desktop-preflight-v1",
+  status: "running",
+  started_at: new Date().toISOString(),
+  finished_at: null,
+  version: rootPackage.version,
+  output_directory: outputRoot,
+  source: {
+    branch: capture("git", ["branch", "--show-current"]),
+    head: capture("git", ["rev-parse", "HEAD"]),
+    dirty: changedFileCount > 0,
+    changed_path_count: changedFileCount,
+    status_sha256: sha256(gitStatus),
+    tracked_diff_sha256: sha256(capture("git", ["diff", "--binary", "HEAD"])),
+  },
+  environment: {
+    platform: process.platform,
+    arch: process.arch,
+    node: process.version,
+    npm: capture(npmCommand, ["--version"]),
+    electron: desktopPackage.devDependencies.electron,
+    electron_builder: desktopPackage.devDependencies["electron-builder"],
+  },
+  options: { require_clean: requireClean, skip_ui_smoke: skipUiSmoke },
+  checks: [],
+  package: null,
+  runtime_manifest: null,
+  ui_smoke: null,
+  artifact: null,
+  error: null,
+};
+
+function saveReport() {
+  writeFileSync(join(outputRoot, "preflight-report.json"), `${JSON.stringify(report, null, 2)}\n`, "utf8");
+  const lines = [
+    `# PatchWarden Desktop ${report.version} preflight`,
+    "",
+    `- Status: ${report.status}`,
+    `- Source: ${report.source.branch} @ ${report.source.head}`,
+    `- Dirty baseline: ${report.source.dirty} (${report.source.changed_path_count} paths, status SHA256 ${report.source.status_sha256})`,
+    `- Node/npm: ${report.environment.node} / ${report.environment.npm}`,
+    `- Electron: ${report.environment.electron}`,
+    `- Output: ${report.output_directory}`,
+    "",
+    "## Checks",
+    "",
+    ...report.checks.map((check) => `- ${check.ok ? "PASS" : "FAIL"} ${check.name} (${check.duration_ms} ms)`),
+    "",
+    report.runtime_manifest ? `Packaged runtime: ${report.runtime_manifest.tool_profile}, ${report.runtime_manifest.tool_count} tools, manifest SHA256 ${report.runtime_manifest.tool_manifest_sha256}.` : "Packaged runtime: not verified.",
+    report.ui_smoke ? `UI smoke: ${report.ui_smoke.ok ? "passed" : "failed"}.` : "UI smoke: not run.",
+    report.error ? `\nError: ${report.error}` : "",
+  ];
+  writeFileSync(join(outputRoot, "preflight-report.md"), `${lines.join("\n")}\n`, "utf8");
+}
+
+function run(name, command, args, cwd = root) {
+  const started = Date.now();
+  const spec = spawnSpec(command, args);
+  const result = spawnSync(spec.command, spec.args, { cwd, encoding: "utf8", windowsHide: true, maxBuffer: 128 * 1024 * 1024 });
+  const stdout = String(result.stdout || "");
+  const stderr = String(result.stderr || "");
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  const check = { name, ok: result.status === 0, exit_code: result.status, duration_ms: Date.now() - started };
+  report.checks.push(check);
+  saveReport();
+  if (!check.ok) throw new Error(`${name} failed with exit code ${result.status ?? "unknown"}: ${stderr || result.error?.message || "see command output"}`);
+  return stdout;
+}
+
+let isolatedRoot = null;
+try {
+  run("root clean build", npmCommand, ["run", "build"]);
+  run("build output contract", npmCommand, ["run", "check:build-output"]);
+  const unitOutput = run("root unit tests", npmCommand, ["run", "test:unit"]);
+  const desktopOutput = run("desktop tests", npmCommand, ["run", "desktop:test"]);
+  const packageOutput = run("npm package surface", npmCommand, ["run", "verify:package"]);
+  run("desktop staging", npmCommand, ["run", "desktop:stage"]);
+  run("Electron directory package", npmCommand, ["exec", "electron-builder", "--", "--win", "dir", "--x64", `--config.directories.output=${outputRoot}`], desktopRoot);
+
+  report.package = {
+    npm_file_count: Number(packageOutput.match(/OK:\s+(\d+) package files/)?.[1] || 0),
+    root_unit_tests: Number([...unitOutput.matchAll(/tests\s+(\d+)/g)].at(-1)?.[1] || 0),
+    desktop_tests: Number([...desktopOutput.matchAll(/tests\s+(\d+)/g)].at(-1)?.[1] || 0),
+  };
+
+  const unpackedRoot = join(outputRoot, "win-unpacked");
+  const executable = join(unpackedRoot, "PatchWarden.exe");
+  const packagedCore = join(unpackedRoot, "resources", "core");
+  if (!existsSync(executable) || !existsSync(packagedCore)) throw new Error("Electron directory package is missing its executable or core runtime.");
+  for (const forbidden of ["dist/test", "src/test", "docs/archive", "scripts/checks/doctor-smoke.js"]) {
+    if (existsSync(join(packagedCore, forbidden))) throw new Error(`Packaged core contains development-only path: ${forbidden}`);
+  }
+  const packagedChecks = readdirSync(join(packagedCore, "scripts", "checks")).sort();
+  if (JSON.stringify(packagedChecks) !== JSON.stringify(["mcp-manifest-check.js"])) {
+    throw new Error(`Packaged core has unexpected check scripts: ${packagedChecks.join(", ")}`);
+  }
+  const coreStats = directoryStats(packagedCore);
+  report.package.packaged_core_file_count = coreStats.files;
+  report.package.packaged_core_size_bytes = coreStats.bytes;
+
+  isolatedRoot = join(tmpdir(), `patchwarden-preflight-${process.pid}-${Date.now()}`);
+  cpSync(packagedCore, isolatedRoot, { recursive: true });
+  const manifestOutput = run("isolated packaged runtime manifest", process.execPath, ["scripts/checks/mcp-manifest-check.js", "--profile", "chatgpt_core"], isolatedRoot);
+  report.runtime_manifest = JSON.parse(manifestOutput);
+  if (!report.runtime_manifest.ok || report.runtime_manifest.server_version !== rootPackage.version || report.runtime_manifest.tool_count !== 26) {
+    throw new Error(`Packaged runtime manifest did not match the ${rootPackage.version} 26-tool contract.`);
+  }
+
+  if (!skipUiSmoke) {
+    const smokeOutput = run("unpacked desktop UI smoke", process.execPath, ["scripts/smoke-unpacked.mjs", "--exe", executable, "--output", join(outputRoot, "ui-smoke")], desktopRoot);
+    report.ui_smoke = JSON.parse(smokeOutput.trim().split(/\r?\n/).at(-1));
+    if (!report.ui_smoke.ok) throw new Error("Unpacked desktop UI smoke did not pass.");
+  }
+
+  report.artifact = {
+    name: basename(executable),
+    size_bytes: readFileSync(executable).length,
+    sha256: sha256(readFileSync(executable)),
+  };
+  report.status = "passed";
+} catch (error) {
+  report.status = "failed";
+  report.error = error instanceof Error ? error.message : String(error);
+  throw error;
+} finally {
+  if (isolatedRoot) rmSync(isolatedRoot, { recursive: true, force: true });
+  report.finished_at = new Date().toISOString();
+  saveReport();
+}
+
+console.log(`[desktop-preflight] PASS: ${outputRoot}`);

package/scripts/release/pack-clean.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import {
-  cpSync,
+  copyFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -16,7 +16,8 @@ import { fileURLToPath } from "node:url";
 
 const scriptDir = resolve(fileURLToPath(new URL(".", import.meta.url)));
 const root = resolve(scriptDir, "..", "..");
-const releaseDir = resolve(root, "release");
+const releaseRoot = resolve(root, "release");
+const releaseDir = resolve(releaseRoot, "package");
 const archivePath = resolve(root, "patchwarden-release.tar.gz");
 
 // Read version from package.json for zip naming
@@ -31,11 +32,6 @@ const include = [
   "src",
   "ui",
   "PatchWarden.cmd",
-  "PatchWarden-Control.cmd",
-  "PatchWarden-Control-Tray.cmd",
-  "PatchWarden-Desktop.cmd",
-  "Restart-PatchWarden-Control.cmd",
-  "Stop-PatchWarden.cmd",
   ".gitignore",
   "LICENSE",
   "README.md",
@@ -57,6 +53,8 @@ const forbidden = [
   /(^|[\\/])\.env$/,
   /\.log$/,
   /^docs[\\/]optimization-proposal\.md$/i,
+  /^docs[\\/]archive(?:[\\/]|$)/i,
+  /^(?:dist|src)[\\/]test(?:[\\/]|$)/i,
   /(^|[\\/])kill-patchwarden\.(cmd|ps1)$/i,
 ];
 
@@ -173,9 +171,15 @@ function readZipEntryNames(zipPath) {
   return names;
 }
 
+const stageRelativeToRoot = toPosix(relative(root, releaseDir));
+if (stageRelativeToRoot !== "release/package") {
+  throw new Error(`Refusing to clean non-isolated release staging path: ${stageRelativeToRoot}`);
+}
+
 console.log("[pack-clean] Preparing clean release directory...");
 rmSync(releaseDir, { recursive: true, force: true });
 rmSync(archivePath, { force: true });
+mkdirSync(releaseRoot, { recursive: true });
 mkdirSync(releaseDir, { recursive: true });
 
 for (const item of include) {
@@ -185,17 +189,26 @@ for (const item of include) {
     console.log(`  skip missing: ${item}`);
     continue;
   }
-  cpSync(source, target, {
-    recursive: true,
-    filter(sourcePath) {
-      const rel = toPosix(relative(root, sourcePath));
-      return !isForbidden(rel);
-    },
-  });
+  copyAllowedEntry(source, target);
   console.log(`  copied: ${item}`);
 }
 
+// Keep an independent second boundary before the fail-closed validation. This
+// protects package contents if a future copy implementation changes behavior.
+pruneForbiddenEntries(releaseDir);
+
 const releaseFiles = listFiles(releaseDir);
+const requiredReleaseEntries = ["package.json", "README.md", "dist/index.js"];
+const missingReleaseEntries = requiredReleaseEntries.filter(
+  (entry) => !existsSync(resolve(releaseDir, entry))
+);
+if (releaseFiles.length === 0 || missingReleaseEntries.length > 0) {
+  console.error("[pack-clean] Release directory is incomplete:");
+  for (const entry of missingReleaseEntries) {
+    console.error(`  missing: ${entry}`);
+  }
+  process.exit(1);
+}
 const badReleaseEntries = releaseFiles.filter((file) =>
   isForbidden(toPosix(relative(releaseDir, file)))
 );
@@ -296,6 +309,38 @@ function listFiles(dir) {
   return entries;
 }
 
+function copyAllowedEntry(source, target) {
+  const rel = toPosix(relative(root, source));
+  if (isForbidden(rel)) {
+    return;
+  }
+
+  const stat = statSync(source);
+  if (stat.isDirectory()) {
+    mkdirSync(target, { recursive: true });
+    for (const name of readdirSync(source)) {
+      copyAllowedEntry(join(source, name), join(target, name));
+    }
+    return;
+  }
+
+  copyFileSync(source, target);
+}
+
+function pruneForbiddenEntries(dir) {
+  for (const name of readdirSync(dir)) {
+    const fullPath = join(dir, name);
+    const rel = toPosix(relative(releaseDir, fullPath));
+    if (isForbidden(rel)) {
+      rmSync(fullPath, { recursive: true, force: true });
+      continue;
+    }
+    if (statSync(fullPath).isDirectory()) {
+      pruneForbiddenEntries(fullPath);
+    }
+  }
+}
+
 function isForbidden(value) {
   return forbidden.some((pattern) => pattern.test(value));
 }

package/src/assessments/agentAssessor.ts

@@ -1,10 +1,11 @@
-import { writeFileSync } from "node:fs";
-import { resolve, relative, isAbsolute } from "node:path";
+import { resolve, relative, isAbsolute, sep } from "node:path";
 import { PatchWardenConfig } from "../config.js";
 import { buildAgentInvocation, buildAssessmentPrompt } from "../runner/agentInvocation.js";
 import { runSimpleProcessSync } from "../runner/simpleProcess.js";
 import { captureRepoSnapshot, compareSnapshots, type RepoSnapshot, type ChangedFile } from "../runner/changeCapture.js";
 import type { AgentAssessmentOutput, AgentAssessmentSummary } from "./assessmentStore.js";
+import { atomicWriteFileSync, atomicWriteJsonFileSync } from "../utils/atomicFile.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
 
 const ASSESSMENT_MARKER = "===ASSESSMENT_JSON===";
 
@@ -45,9 +46,11 @@ export async function runAgentAssessment(input: AgentAssessorInput): Promise<Age
   };
 
   // ── 1. Build prompt and write to file for {prompt_file} support ──
-  const assessmentPrompt = buildAssessmentPrompt(input.goal, input.planContent, input.repoPath);
+  const safeGoal = redactSensitiveContent(input.goal).content.slice(0, 10_000);
+  const safePlan = redactSensitiveContent(input.planContent).content.slice(0, 1024 * 1024);
+  const assessmentPrompt = buildAssessmentPrompt(safeGoal, safePlan, input.repoPath);
   const promptFilePath = resolve(input.assessmentDir, "agent-assessment-prompt.md");
-  writeFileSync(promptFilePath, assessmentPrompt, "utf-8");
+  atomicWriteFileSync(promptFilePath, assessmentPrompt);
   logPaths.prompt = promptFilePath;
 
   // ── 2. Before snapshot (repo-scoped) ──
@@ -89,6 +92,8 @@ export async function runAgentAssessment(input: AgentAssessorInput): Promise<Age
     maxStderrBytes: Math.max(16384, Math.floor(input.maxOutputBytes / 4)),
     stdoutPath: logPaths.stdout,
     stderrPath: logPaths.stderr,
+    environmentVariableNames: invocation.environmentVariableNames,
+    blockedEnvironmentVariableNames: invocation.blockedEnvironmentVariableNames,
   });
 
   // ── 5. After snapshot + read-only violation check ──
@@ -123,11 +128,11 @@ export async function runAgentAssessment(input: AgentAssessorInput): Promise<Age
       stderr_truncated: result.stderrTruncated,
       log_paths: { ...logPaths, violation: resolve(input.assessmentDir, "agent-assessment-violation.json") },
     };
-    writeFileSync(summary.log_paths.violation!, JSON.stringify({
+    atomicWriteJsonFileSync(summary.log_paths.violation!, {
       violation: "read_only_violation",
       files: violationFiles,
       exit_code: result.exitCode,
-    }, null, 2), "utf-8");
+    });
     writeSummary(logPaths.assessment, summary);
     return summary;
   }
@@ -253,12 +258,16 @@ function parseAssessmentJson(stdout: string, repoPath: string): ParsedAssessment
   const jsonEnd = jsonText.lastIndexOf("}");
   if (jsonStart < 0 || jsonEnd < 0 || jsonEnd <= jsonStart) return { output: null, sanitized_reasons };
 
-  let parsed: any;
+  let parsedValue: unknown;
   try {
-    parsed = JSON.parse(jsonText.slice(jsonStart, jsonEnd + 1));
+    parsedValue = JSON.parse(jsonText.slice(jsonStart, jsonEnd + 1));
   } catch {
     return { output: null, sanitized_reasons };
   }
+  if (!parsedValue || typeof parsedValue !== "object" || Array.isArray(parsedValue)) {
+    return { output: null, sanitized_reasons };
+  }
+  const parsed = parsedValue as Record<string, unknown>;
 
   // ── Strict validation ──
   if (parsed.risk_level !== "low" && parsed.risk_level !== "medium" && parsed.risk_level !== "high") {
@@ -272,7 +281,9 @@ function parseAssessmentJson(stdout: string, repoPath: string): ParsedAssessment
 
   if (!Array.isArray(parsed.reason_codes)) return { output: null, sanitized_reasons };
   if (parsed.reason_codes.length > 50) return { output: null, sanitized_reasons };
-  const reasonCodes = parsed.reason_codes.filter((r: any) => typeof r === "string" && r.length <= 100);
+  const reasonCodes = parsed.reason_codes.filter((reason): reason is string =>
+    typeof reason === "string" && reason.length <= 100
+  );
   if (reasonCodes.length !== parsed.reason_codes.length) {
     sanitized_reasons.push("reason_codes_filtered");
   }
@@ -287,7 +298,10 @@ function parseAssessmentJson(stdout: string, repoPath: string): ParsedAssessment
     if (isAbsolute(p)) { pathsSanitized = true; continue; }
     const resolved = resolve(repoPath, p);
     const rel = relative(repoPath, resolved);
-    if (rel.startsWith("..")) { pathsSanitized = true; continue; }
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+      pathsSanitized = true;
+      continue;
+    }
     affectedPaths.push(p);
   }
   if (pathsSanitized) {
@@ -297,7 +311,7 @@ function parseAssessmentJson(stdout: string, repoPath: string): ParsedAssessment
   if (!Array.isArray(parsed.destructive_actions)) return { output: null, sanitized_reasons };
   if (parsed.destructive_actions.length > 20) return { output: null, sanitized_reasons };
   const destructiveActions = parsed.destructive_actions.filter(
-    (d: any) => typeof d === "string" && d.length <= 200
+    (action): action is string => typeof action === "string" && action.length <= 200
   );
 
   if (typeof parsed.requires_user_confirm !== "boolean") return { output: null, sanitized_reasons };
@@ -320,5 +334,5 @@ function parseAssessmentJson(stdout: string, repoPath: string): ParsedAssessment
 }
 
 function writeSummary(path: string, summary: AgentAssessmentSummary): void {
-  writeFileSync(path, JSON.stringify(summary, null, 2), "utf-8");
+  atomicWriteJsonFileSync(path, summary);
 }

package/src/assessments/assessmentDiagnostics.ts

@@ -0,0 +1,172 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAssessmentsDir, getConfig } from "../config.js";
+import { guardPath } from "../security/pathGuard.js";
+import { atomicWriteJsonFileSync } from "../utils/atomicFile.js";
+import { readJsonObjectFileSync } from "../utils/lockedJsonFile.js";
+import type { AssessmentValidationResult } from "./assessmentStore.js";
+import { ASSESSMENT_SECURITY_SNAPSHOT_VERSION } from "./securitySnapshot.js";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
+
+const DIAGNOSTIC_VERSION = "assessment-validation-diagnostic-v2";
+const DIAGNOSTIC_FILE = "last-validation-failure.json";
+const VALIDATOR_MODULE_PATH = "dist/assessments/assessmentStore.js";
+const VALIDATOR_BUILD_ID = `patchwarden-${PATCHWARDEN_VERSION}:${TOOL_SCHEMA_EPOCH}:${ASSESSMENT_SECURITY_SNAPSHOT_VERSION}`;
+
+export interface AssessmentValidationFailureDiagnostic {
+  diagnostic_version: string;
+  error_code: string;
+  reason_code: string;
+  assessment_id: string | null;
+  assessment_config_sha256: string | null;
+  current_config_sha256: string | null;
+  assessment_config_hash: string | null;
+  current_config_hash: string | null;
+  snapshot_version: string | null;
+  assessment_fingerprint_version: string | null;
+  current_fingerprint_version: string;
+  assessment_schema_epoch: string | null;
+  current_schema_epoch: string;
+  assessment_created_at: string | null;
+  assessment_expires_at: string | null;
+  config_changed: boolean;
+  changed_field_names: string[];
+  changed_config_sections: string[];
+  validator_module_path: string;
+  validator_build_id: string;
+  watcher_instance_id: string | null;
+  observed_at: string;
+}
+
+export function buildAssessmentValidationFailureDiagnostic(
+  result: AssessmentValidationResult,
+): AssessmentValidationFailureDiagnostic | null {
+  if (result.valid || !result.failure_reason) return null;
+  const reasonCode = safeCode(result.failure_reason);
+  const assessmentHash = safeHash(result.expected_hash);
+  const currentHash = safeHash(result.actual_hash);
+  const changedSections = [...new Set((result.config_change_categories || [])
+    .map((name) => safeCode(name))
+    .filter(Boolean))]
+    .sort()
+    .slice(0, 32);
+  const assessmentVersion = safeText(result.assessment?.assessment_security_snapshot_version, 80);
+  return {
+    diagnostic_version: DIAGNOSTIC_VERSION,
+    error_code: reasonCode,
+    reason_code: reasonCode,
+    assessment_id: safeAssessmentId(result.assessment?.assessment_id),
+    assessment_config_sha256: assessmentHash,
+    current_config_sha256: currentHash,
+    assessment_config_hash: assessmentHash,
+    current_config_hash: currentHash,
+    snapshot_version: assessmentVersion,
+    assessment_fingerprint_version: assessmentVersion,
+    current_fingerprint_version: ASSESSMENT_SECURITY_SNAPSHOT_VERSION,
+    assessment_schema_epoch: safeText(result.assessment?.assessment_schema_epoch, 80),
+    current_schema_epoch: TOOL_SCHEMA_EPOCH,
+    assessment_created_at: safeTimestamp(result.assessment?.created_at),
+    assessment_expires_at: safeTimestamp(result.assessment?.expires_at),
+    config_changed: result.failure_reason === "assessment_stale_config",
+    changed_field_names: changedSections,
+    changed_config_sections: changedSections,
+    validator_module_path: VALIDATOR_MODULE_PATH,
+    validator_build_id: VALIDATOR_BUILD_ID,
+    watcher_instance_id: safeInstanceId(process.env.PATCHWARDEN_WATCHER_INSTANCE_ID),
+    observed_at: new Date().toISOString(),
+  };
+}
+
+/** Persist a bounded value-free failure summary without changing validation behavior. */
+export function recordAssessmentValidationFailure(result: AssessmentValidationResult): boolean {
+  const diagnostic = buildAssessmentValidationFailureDiagnostic(result);
+  if (!diagnostic) return false;
+  try {
+    const config = getConfig();
+    const assessmentsDir = getAssessmentsDir(config);
+    const file = guardPath(
+      join(assessmentsDir, DIAGNOSTIC_FILE),
+      config.workspaceRoot,
+      config.assessmentsDir,
+    );
+    mkdirSync(dirname(file), { recursive: true });
+    atomicWriteJsonFileSync(file, diagnostic);
+    return true;
+  } catch {
+    // Diagnostics must never replace the original fail-closed validation error.
+    return false;
+  }
+}
+
+export function readLastAssessmentValidationFailure(): AssessmentValidationFailureDiagnostic | null {
+  try {
+    const config = getConfig();
+    const file = guardPath(
+      join(getAssessmentsDir(config), DIAGNOSTIC_FILE),
+      config.workspaceRoot,
+      config.assessmentsDir,
+    );
+    if (!existsSync(file)) return null;
+    const raw = readJsonObjectFileSync<Record<string, unknown>>(file);
+    if (raw.diagnostic_version !== DIAGNOSTIC_VERSION) return null;
+    const changedSections = Array.isArray(raw.changed_config_sections)
+      ? [...new Set(raw.changed_config_sections.map(safeCode).filter(Boolean))].sort().slice(0, 32)
+      : [];
+    return {
+      diagnostic_version: DIAGNOSTIC_VERSION,
+      error_code: safeCode(raw.error_code),
+      reason_code: safeCode(raw.reason_code),
+      assessment_id: safeAssessmentId(raw.assessment_id),
+      assessment_config_sha256: safeHash(raw.assessment_config_sha256),
+      current_config_sha256: safeHash(raw.current_config_sha256),
+      assessment_config_hash: safeHash(raw.assessment_config_hash),
+      current_config_hash: safeHash(raw.current_config_hash),
+      snapshot_version: safeText(raw.snapshot_version, 80),
+      assessment_fingerprint_version: safeText(raw.assessment_fingerprint_version, 80),
+      current_fingerprint_version: safeText(raw.current_fingerprint_version, 80) || ASSESSMENT_SECURITY_SNAPSHOT_VERSION,
+      assessment_schema_epoch: safeText(raw.assessment_schema_epoch, 80),
+      current_schema_epoch: safeText(raw.current_schema_epoch, 80) || TOOL_SCHEMA_EPOCH,
+      assessment_created_at: safeTimestamp(raw.assessment_created_at),
+      assessment_expires_at: safeTimestamp(raw.assessment_expires_at),
+      config_changed: raw.config_changed === true,
+      changed_field_names: Array.isArray(raw.changed_field_names)
+        ? [...new Set(raw.changed_field_names.map(safeCode).filter(Boolean))].sort().slice(0, 32)
+        : [],
+      changed_config_sections: changedSections,
+      validator_module_path: safeText(raw.validator_module_path, 120) || VALIDATOR_MODULE_PATH,
+      validator_build_id: safeText(raw.validator_build_id, 160) || VALIDATOR_BUILD_ID,
+      watcher_instance_id: safeInstanceId(raw.watcher_instance_id),
+      observed_at: safeTimestamp(raw.observed_at) || new Date(0).toISOString(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function safeAssessmentId(value: unknown): string | null {
+  return typeof value === "string" && /^assessment_\d{8}_\d{6}_[0-9a-f]{32}$/.test(value) ? value : null;
+}
+
+function safeInstanceId(value: unknown): string | null {
+  return typeof value === "string" && /^[a-zA-Z0-9_-]{1,100}$/.test(value) ? value : null;
+}
+
+function safeCode(value: unknown): string {
+  return typeof value === "string" && /^[a-z0-9_]{1,80}$/.test(value) ? value : "";
+}
+
+function safeHash(value: unknown): string | null {
+  return typeof value === "string" && /^[0-9a-f]{64}$/.test(value) ? value : null;
+}
+
+function safeText(value: unknown, maxLength: number): string | null {
+  return typeof value === "string" && value.length > 0
+    ? value.replace(/[\r\n]+/g, " ").slice(0, maxLength)
+    : null;
+}
+
+function safeTimestamp(value: unknown): string | null {
+  return typeof value === "string" && Number.isFinite(Date.parse(value))
+    ? new Date(value).toISOString()
+    : null;
+}