patchwarden 1.5.1 → 1.6.2

package/src/tools/{auditSession.ts → diagnostics/auditSession.ts}

@@ -1,8 +1,8 @@
 import {
   auditDirectSession,
   type DirectSessionAuditOutput,
-} from "../direct/directAudit.js";
-import { updateDirectSession } from "../direct/directSessionStore.js";
+} from "../../direct/directAudit.js";
+import { updateDirectSession } from "../../direct/directSessionStore.js";
 
 // ── Types ──────────────────────────────────────────────────────────
 

package/src/tools/{auditTask.ts → diagnostics/auditTask.ts}

@@ -31,14 +31,20 @@ export interface AuditTaskOutput {
   manual_verification_items: string[];
   recommended_next_actions: string[];
 }
-import { readFileSync, existsSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, existsSync, opendirSync, statSync } from "node:fs";
 import { join, resolve, relative, basename, sep, isAbsolute } from "node:path";
-import { getTasksDir, getConfig } from "../config.js";
-import { guardReadPath, guardWorkspacePath } from "../security/pathGuard.js";
-import { guardSensitivePath, isSensitivePath } from "../security/sensitiveGuard.js";
-import { evaluateAcceptance } from "../goal/acceptanceEngine.js";
-import { renderAcceptanceMarkdown } from "../goal/acceptanceTemplate.js";
-import type { ChangedFile } from "../runner/changeCapture.js";
+import { getTasksDir, getConfig } from "../../config.js";
+import { guardReadPath, guardWorkspacePath } from "../../security/pathGuard.js";
+import { guardSensitivePath, isSensitivePath } from "../../security/sensitiveGuard.js";
+import { evaluateAcceptance } from "../../goal/acceptanceEngine.js";
+import { renderAcceptanceMarkdown } from "../../goal/acceptanceTemplate.js";
+import type { ChangedFile } from "../../runner/changeCapture.js";
+import { atomicWriteFileSync } from "../../utils/atomicFile.js";
+import { mutateTaskStatus } from "../../runner/taskStatusStore.js";
+import {
+  readTextFilePrefixSync,
+  readTextFileTailLinesSync,
+} from "../../utils/boundedFile.js";
 
 interface ExtractedCommand {
   type: "npm-run" | "npm-bare" | "node" | "npx" | "python";
@@ -86,6 +92,10 @@ const RELEASE_PATTERNS = [
     /npm\s+publish\s+completed/i,
     /deploy(ed|ment)?\s+(to|on)\s+(npm|registry|github)/i,
 ];
+const MAX_AUDIT_DOC_FILES = 200;
+const MAX_AUDIT_DOC_FILE_BYTES = 512 * 1024;
+const MAX_AUDIT_DOC_TOTAL_BYTES = 4 * 1024 * 1024;
+const MAX_AUDIT_EVIDENCE_BYTES = 1024 * 1024;
 function scanForReleaseClaims(text: string): string[] {
     const found: string[] = [];
     for (const pattern of RELEASE_PATTERNS) {
@@ -95,24 +105,84 @@ function scanForReleaseClaims(text: string): string[] {
     }
     return found;
 }
-function findMdFiles(dir: string, maxDepth = 3): string[] {
+function findMdFiles(
+    dir: string,
+    maxDepth = 3,
+    maxFiles = MAX_AUDIT_DOC_FILES,
+): { files: string[]; truncated: boolean } {
     const results: string[] = [];
-    if (!existsSync(dir) || maxDepth <= 0)
-        return results;
-    try {
-        const entries = readdirSync(dir, { withFileTypes: true });
-        for (const e of entries) {
-            const full = join(dir, e.name);
-            if (e.isDirectory() && !e.name.startsWith(".") && e.name !== "node_modules") {
-                results.push(...findMdFiles(full, maxDepth - 1));
-            }
-            else if (e.isFile() && e.name.endsWith(".md")) {
-                results.push(full);
+    const pending = [{ path: dir, depth: maxDepth }];
+    const maxDirectories = maxFiles * 4;
+    let visitedDirectories = 0;
+    let truncated = false;
+    while (pending.length > 0 && results.length < maxFiles && visitedDirectories < maxDirectories) {
+        const current = pending.pop()!;
+        if (!existsSync(current.path) || current.depth <= 0) continue;
+        visitedDirectories += 1;
+        let handle;
+        try {
+            handle = opendirSync(current.path);
+            while (results.length < maxFiles) {
+                const entry = handle.readSync();
+                if (!entry) break;
+                const full = join(current.path, entry.name);
+                if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+                    if (pending.length < maxDirectories) pending.push({ path: full, depth: current.depth - 1 });
+                    else truncated = true;
+                } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+                    results.push(full);
+                }
             }
-        }
+        } catch { /* skip unreadable dirs */ }
+        finally { try { handle?.closeSync(); } catch { /* best effort */ } }
+    }
+    truncated ||= pending.length > 0 || results.length >= maxFiles || visitedDirectories >= maxDirectories;
+    return { files: results, truncated };
+}
+
+export function extractNpmRunScriptNames(content: string): string[] {
+  const names = new Set<string>();
+  const collectCommands = (text: string) => {
+    const pattern = /\bnpm(?:\.cmd)?\s+run\s+([a-zA-Z0-9:_-]+)/gi;
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(text)) !== null) {
+      if (match[1]) names.add(match[1]);
     }
-    catch { /* skip unreadable dirs */ }
-    return results;
+  };
+
+  // Markdown code blocks are explicit command-bearing regions. Keep their
+  // content separate from prose so token boundaries cannot be concatenated.
+  const withoutFences = content.replace(/(?:```|~~~)[^\r\n]*\r?\n([\s\S]*?)(?:```|~~~)/g, (_whole, body: string) => {
+    collectCommands(body);
+    return "\n";
+  });
+
+  // Inline code is also explicit. Remove it from the prose pass afterward to
+  // avoid double-counting and accidental cross-node matches.
+  const withoutInlineCode = withoutFences.replace(/`([^`\r\n]+)`/g, (_whole, body: string) => {
+    collectCommands(body);
+    return " ";
+  });
+
+  // In ordinary text, accept only a standalone command line (optionally a
+  // list item, shell prompt, or Run:/Command: label). Narrative mentions such
+  // as "this guide discusses npm run deploy" are not executable evidence.
+  const explicitPlainCommand = /^\s*(?:(?:[-*+]\s+|\d+[.)]\s+|>\s*|\$\s*|PS>\s*)|(?:(?:run|command|命令)\s*[:：]\s*))?npm(?:\.cmd)?\s+run\s+[a-zA-Z0-9:_-]+(?:\s+(?:--[^\r\n#]*|#[^\r\n]*))?\s*$/i;
+  for (const line of withoutInlineCode.split(/\r?\n/)) {
+    if (explicitPlainCommand.test(line)) collectCommands(line);
+  }
+  return [...names];
+}
+
+function readAuditEvidence(path: string): { content: string; truncated: boolean } {
+    const half = Math.floor(MAX_AUDIT_EVIDENCE_BYTES / 2);
+    const prefix = readTextFilePrefixSync(path, half);
+    if (!prefix.truncated) return { content: prefix.content, truncated: false };
+    const tail = readTextFileTailLinesSync(path, 1000, half);
+    return {
+        content: `${prefix.content}\n[...audit evidence truncated...]\n${tail}`,
+        truncated: true,
+    };
 }
 // ── v0.7.2: New audit checks (exported for testing) ────────────────
 /**
@@ -479,7 +549,7 @@ export function auditTask(taskId: string): AuditTaskOutput {
     };
     // ── 1. Task status ──
     const taskStatus = statusData.status || "unknown";
-    const failedStatuses = new Set(["failed", "failed_verification", "failed_scope_violation", "failed_policy_violation", "canceled"]);
+    const failedStatuses = new Set(["failed", "failed_verification", "failed_scope_violation", "failed_policy_violation", "canceled", "timeout"]);
     const doneStatuses = new Set(["done", "done_by_agent"]);
     checks.push({
         name: "task_status",
@@ -659,36 +729,55 @@ export function auditTask(taskId: string): AuditTaskOutput {
     if (existsSync(readmePath))
         docsToScan.push(readmePath);
     const docsDir = join(repoPathSafe, "docs");
+    let markdownEnumerationTruncated = false;
     if (existsSync(docsDir)) {
-        docsToScan.push(...findMdFiles(docsDir));
+        const markdown = findMdFiles(docsDir);
+        docsToScan.push(...markdown.files);
+        markdownEnumerationTruncated = markdown.truncated;
     }
     // Collect all npm run references from all docs
     const allNpmRunRefs = new Set<string>();
     const allReleaseClaims: string[] = [];
+    let remainingDocBytes = MAX_AUDIT_DOC_TOTAL_BYTES;
+    let documentScanTruncated = markdownEnumerationTruncated || docsToScan.length > MAX_AUDIT_DOC_FILES;
     for (const docPath of docsToScan) {
+        if (remainingDocBytes <= 0) {
+            documentScanTruncated = true;
+            break;
+        }
         let content: string;
         try {
             if (docPath !== resultFile) {
                 guardReadPath(docPath, config.workspaceRoot);
                 guardSensitivePath(docPath);
             }
-            content = readFileSync(docPath, "utf-8");
+            const bounded = readTextFilePrefixSync(
+                docPath,
+                Math.min(MAX_AUDIT_DOC_FILE_BYTES, remainingDocBytes),
+            );
+            content = bounded.content;
+            remainingDocBytes -= Buffer.byteLength(content, "utf-8");
+            documentScanTruncated ||= bounded.truncated;
         }
         catch {
             continue;
         }
         // Extract npm run xxx
-        const refs = content.match(/npm(?:\.cmd)?\s+run\s+([a-zA-Z0-9:_-]+)/gi) || [];
-        for (const ref of refs) {
-            const scriptName = ref.replace(/npm\s+run\s+/i, "").replace(/[^a-zA-Z0-9:_-]/g, "");
-            if (scriptName)
-                allNpmRunRefs.add(scriptName);
-        }
+        for (const scriptName of extractNpmRunScriptNames(content))
+            allNpmRunRefs.add(scriptName);
         // Check release claims
         const claims = scanForReleaseClaims(content);
         for (const c of claims)
             allReleaseClaims.push(`[${relative(repoPathSafe, docPath) || docPath}] ${c}`);
     }
+    if (documentScanTruncated) {
+        checks.push({
+            name: "documentation_scan_bounded",
+            result: "warn",
+            detail: `Documentation scan reached its ${MAX_AUDIT_DOC_FILES}-file or ${MAX_AUDIT_DOC_TOTAL_BYTES}-byte safety budget.`,
+        });
+        addManualVerification("Review documentation omitted by the bounded audit scan.");
+    }
     // Cross-check npm run refs against package.json scripts
     for (const scriptName of allNpmRunRefs) {
         if (pkgScripts.length > 0 && !pkgScripts.includes(scriptName)) {
@@ -735,7 +824,9 @@ export function auditTask(taskId: string): AuditTaskOutput {
     if (hasTestLog) {
         let logContent: string;
         try {
-            logContent = readFileSync(testLogFile, "utf-8");
+            const evidence = readAuditEvidence(testLogFile);
+            logContent = evidence.content;
+            if (evidence.truncated) addManualVerification("test.log exceeded the audit read budget; inspect the complete local artifact.");
         }
         catch {
             logContent = "";
@@ -773,7 +864,9 @@ export function auditTask(taskId: string): AuditTaskOutput {
     let resultMdContent: string | null = null;
     if (hasResult) {
         try {
-            resultMdContent = readFileSync(resultFile, "utf-8");
+            const evidence = readAuditEvidence(resultFile);
+            resultMdContent = evidence.content;
+            if (evidence.truncated) addManualVerification("result.md exceeded the audit read budget; inspect the complete local artifact.");
         }
         catch {
             resultMdContent = null;
@@ -841,7 +934,7 @@ export function auditTask(taskId: string): AuditTaskOutput {
         "## Recommended Actions",
         ...actions.map((a) => `- ${a}`),
     ].join("\n");
-    writeFileSync(join(taskDir, "independent-review.md"), reviewMd, "utf-8");
+    atomicWriteFileSync(join(taskDir, "independent-review.md"), reviewMd);
     // ── v0.7.2: 集成 acceptanceEngine ──
     const releaseClaimsUnverified = allReleaseClaims.length > 0;
     const acceptanceEvidence = {
@@ -878,16 +971,20 @@ export function auditTask(taskId: string): AuditTaskOutput {
     const acceptanceResult = evaluateAcceptance(acceptanceEvidence);
     // 回写 status.json 的 acceptance_status（仅对 done_by_agent 有意义）
     if (taskStatus === "done_by_agent") {
-        const updatedStatus = {
-            ...statusData,
+        const statusPatch = {
             acceptance_status: acceptanceResult.acceptance_status,
-            updated_at: new Date().toISOString(),
         };
-        writeFileSync(statusFile, JSON.stringify(updatedStatus, null, 2), "utf-8");
+        mutateTaskStatus(statusFile, (current) => {
+            if (current.status !== "done_by_agent") {
+                return { result: current };
+            }
+            const next = { ...current, ...statusPatch, updated_at: new Date().toISOString() };
+            return { next, result: next };
+        });
     }
     // 导出 ACCEPTANCE.md
     const acceptanceMd = renderAcceptanceMarkdown(taskId, acceptanceResult, acceptanceEvidence);
-    writeFileSync(join(taskDir, "ACCEPTANCE.md"), acceptanceMd, "utf-8");
+    atomicWriteFileSync(join(taskDir, "ACCEPTANCE.md"), acceptanceMd);
     return {
         task_id: taskId,
         verdict,

package/src/tools/{healthCheck.ts → diagnostics/healthCheck.ts}

@@ -1,14 +1,15 @@
 import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { getConfig, getTasksDir, getDirectSessionsDir, resolveWorkspaceRoot } from "../config.js";
-import { listAgents } from "./listAgents.js";
-import { redactSensitiveContent, redactSensitiveValue } from "../security/contentRedaction.js";
-import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
-import type { ToolCatalogSnapshot } from "./toolCatalog.js";
-import { CHATGPT_CORE_TOOL_NAMES, CHATGPT_DIRECT_TOOL_NAMES, CHATGPT_SEARCH_TOOL_NAMES, resolveToolProfile } from "./toolCatalog.js";
-import { readWatcherStatus } from "../watcherStatus.js";
-import { listTasks } from "./listTasks.js";
+import { getConfig, getTasksDir, getDirectSessionsDir, resolveWorkspaceRoot } from "../../config.js";
+import { listAgents } from "../workspace/listAgents.js";
+import { redactSensitiveContent, redactSensitiveValue } from "../../security/contentRedaction.js";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../../version.js";
+import type { ToolCatalogSnapshot } from "../catalog/toolCatalog.js";
+import { CHATGPT_CORE_TOOL_NAMES, CHATGPT_DIRECT_TOOL_NAMES, CHATGPT_SEARCH_TOOL_NAMES, resolveToolProfile } from "../catalog/toolCatalog.js";
+import { readWatcherStatus } from "../../watcherStatus.js";
+import { listTasks } from "../tasks/listTasks.js";
+import { readLastAssessmentValidationFailure } from "../../assessments/assessmentDiagnostics.js";
 
 const SERVER_STARTED_AT = Date.now();
 
@@ -130,8 +131,23 @@ export function healthCheck(catalog?: ToolCatalogSnapshot, input: HealthCheckInp
     workspace_root: workspace,
     tasks_dir: tasks,
     tunnel,
+    config_path: agents.config_path,
+    runtime_build_layout: typeof watcher.supervisor?.runtime_build_layout === "string"
+      ? watcher.supervisor.runtime_build_layout
+      : null,
+    watcher_entry_path: typeof watcher.supervisor?.watcher_entry_path === "string"
+      ? watcher.supervisor.watcher_entry_path
+      : null,
+    validator_module_path: typeof watcher.supervisor?.validator_module_path === "string"
+      ? watcher.supervisor.validator_module_path
+      : null,
     agents: agents.agents,
     agent_status: Object.fromEntries(agents.agents.map((agent) => [agent.name, agent.available ? "ok" : "missing"])),
+    agent_readiness: Object.fromEntries(agents.agents.map((agent) => [agent.name, {
+      executable_available: agent.available,
+      provider_status: agent.provider_status,
+      availability_scope: agent.availability_scope,
+    }])),
     ...(input.detail === "self_diagnostic" ? { self_diagnostic: buildSelfDiagnostic(config) } : {}),
     last_error: tunnel.last_error || (!watcher.available ? watcher.reason : null) || mismatchReport[0] || null,
   };
@@ -140,7 +156,7 @@ export function healthCheck(catalog?: ToolCatalogSnapshot, input: HealthCheckInp
 function buildSelfDiagnostic(config: ReturnType<typeof getConfig>) {
   const recent = listTasks({ limit: 20 });
   const failures = recent.tasks
-    .filter((task) => task.status.startsWith("failed") || task.status === "canceled")
+    .filter((task) => task.status.startsWith("failed") || task.status === "canceled" || task.status === "timeout")
     .slice(0, 10)
     .map((task) => ({
       task_id: task.task_id,
@@ -156,6 +172,7 @@ function buildSelfDiagnostic(config: ReturnType<typeof getConfig>) {
     configured_agents: Object.keys(config.agents),
     recent_tasks_returned: recent.tasks.length,
     recent_failures: failures,
+    last_assessment_validation_failure: readLastAssessmentValidationFailure(),
   };
   const safe = redactSensitiveValue(diagnostic);
   return {
@@ -182,6 +199,11 @@ function readWatcherSupervisorStatus(): Record<string, unknown> {
       restart_attempts: Number.isInteger(Number(raw.restart_attempts)) ? Number(raw.restart_attempts) : 0,
       last_error: safeText(raw.last_error, 500) || null,
       checked_at: safeText(raw.checked_at, 80) || null,
+      project_root: safeText(raw.project_root, 500) || null,
+      config_path: safeText(raw.config_path, 500) || null,
+      watcher_entry_path: safeText(raw.watcher_entry_path, 500) || null,
+      validator_module_path: safeText(raw.validator_module_path, 500) || null,
+      runtime_build_layout: safeText(raw.runtime_build_layout, 80) || null,
     };
   } catch {
     return { observed: true, managed: false, status: "invalid_status_file" };
@@ -242,6 +264,12 @@ function readTunnelStatus(): Record<string, unknown> & { last_error: string | nu
         : [],
       tool_manifest_sha256: safeText(raw.tool_manifest_sha256, 80) || null,
       core_tools_ready: Boolean(raw.core_tools_ready),
+      project_root: safeText(raw.project_root, 500) || null,
+      config_path: safeText(raw.config_path, 500) || null,
+      mcp_entry_path: safeText(raw.mcp_entry_path, 500) || null,
+      watcher_entry_path: safeText(raw.watcher_entry_path, 500) || null,
+      validator_module_path: safeText(raw.validator_module_path, 500) || null,
+      runtime_build_layout: safeText(raw.runtime_build_layout, 80) || null,
     };
     const redacted = redactSensitiveContent(JSON.stringify(allowed));
     return JSON.parse(redacted.content);

package/src/tools/diagnostics/index.ts

@@ -0,0 +1,6 @@
+export * from "./auditSession.js";
+export * from "./auditTask.js";
+export * from "./healthCheck.js";
+export * from "./safeStatus.js";
+export * from "./safeViews.js";
+export * from "./schemaDriftCheck.js";

package/src/tools/{safeStatus.ts → diagnostics/safeStatus.ts}

@@ -1,12 +1,12 @@
 import { readFileSync, existsSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { getTasksDir, getConfig, type PatchWardenConfig } from "../config.js";
-import { guardReadPath } from "../security/pathGuard.js";
-import { guardSensitivePath } from "../security/sensitiveGuard.js";
-import type { TaskStatus, TaskPhase, AcceptanceStatus } from "./createTask.js";
-import { readTaskRuntime } from "../taskRuntime.js";
-import { readWatcherStatus } from "../watcherStatus.js";
-import { diagnoseTask, type DiagnosisType, type DiagnosisConfidence } from "./diagnoseTask.js";
+import { getTasksDir, getConfig, type PatchWardenConfig } from "../../config.js";
+import { guardReadPath } from "../../security/pathGuard.js";
+import { guardSensitivePath } from "../../security/sensitiveGuard.js";
+import type { TaskStatus, TaskPhase, AcceptanceStatus } from "../tasks/createTask.js";
+import { readTaskRuntime } from "../../runner/taskRuntime.js";
+import { readWatcherStatus } from "../../watcherStatus.js";
+import { diagnoseTask, type DiagnosisType, type DiagnosisConfidence } from "../tasks/diagnoseTask.js";
 
 export interface SafeStatusOutput {
   task_id: string;

package/src/tools/{safeViews.ts → diagnostics/safeViews.ts}

@@ -1,14 +1,15 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { getConfig, getTasksDir } from "../config.js";
+import { getConfig, getTasksDir } from "../../config.js";
 import { auditSession } from "./auditSession.js";
 import { auditTask, type AuditTaskOutput } from "./auditTask.js";
-import { finalizeDirectSession } from "./finalizeDirectSession.js";
-import { getTaskSummary } from "./getTaskSummary.js";
-import { guardReadPath } from "../security/pathGuard.js";
-import { redactSensitiveValue } from "../security/contentRedaction.js";
-import { readDirectSession, type DirectSessionRecord, type DirectSessionVerificationRun } from "../direct/directSessionStore.js";
-import type { ChangedFile, ClassifiedChange } from "../runner/changeCapture.js";
+import { finalizeDirectSession } from "../direct/finalizeDirectSession.js";
+import { getTaskSummary } from "../tasks/getTaskSummary.js";
+import { guardReadPath } from "../../security/pathGuard.js";
+import { redactSensitiveValue } from "../../security/contentRedaction.js";
+import { readDirectSession, type DirectSessionRecord, type DirectSessionVerificationRun } from "../../direct/directSessionStore.js";
+import type { ChangedFile, ClassifiedChange } from "../../runner/changeCapture.js";
+import { ARTIFACT_SCHEMA_VERSION } from "../../version.js";
 
 export interface SafeViewOptions {
   max_items?: number;
@@ -18,6 +19,7 @@ export function safeResult(taskId: string, options: SafeViewOptions = {}) {
   const maxItems = normalizeMaxItems(options.max_items);
   const summary = getTaskSummary(taskId, { view: "compact", max_items: maxItems });
   return redact({
+    schema_version: ARTIFACT_SCHEMA_VERSION,
     task_id: summary.task_id,
     status: summary.status,
     terminal: summary.terminal,
@@ -46,13 +48,17 @@ export function safeTestSummary(taskId: string) {
   const { taskDir, config } = getTaskDir(taskId);
   const verify = readJson(join(taskDir, "verify.json"), config);
   const summary = getTaskSummary(taskId, { view: "compact", max_items: 8 });
-  const commands = asArray(verify.commands).map((entry: any) => ({
-    command: String(entry.command || ""),
-    status: String(entry.status || "unknown"),
-    exit_code: entry.exit_code ?? null,
-    duration_ms: Number(entry.duration_ms || 0),
-  }));
+  const commands = asArray(verify.commands).map((entry) => {
+    const command = asRecord(entry);
+    return {
+      command: String(command.command || ""),
+      status: String(command.status || "unknown"),
+      exit_code: command.exit_code ?? null,
+      duration_ms: Number(command.duration_ms || 0),
+    };
+  });
   return redact({
+    schema_version: ARTIFACT_SCHEMA_VERSION,
     task_id: taskId,
     status: String(verify.status || summary.verification_summary.status || "not_available"),
     command_count: commands.length,
@@ -71,6 +77,7 @@ export function safeDiffSummary(taskId: string, options: SafeViewOptions = {}) {
   const changedFiles = asArray(changes.changed_files) as ChangedFile[];
   const hygiene = asRecord(changes.artifact_hygiene);
   return redact({
+    schema_version: ARTIFACT_SCHEMA_VERSION,
     task_id: taskId,
     changed_files_total: changedFiles.length,
     additions: Number(changes.additions || 0),
@@ -141,6 +148,7 @@ function auditToSafe(audit: AuditTaskOutput, maxItems: number) {
     detail: truncate(check.detail, 240),
   }));
   return redact({
+    schema_version: ARTIFACT_SCHEMA_VERSION,
     task_id: audit.task_id,
     verdict: audit.verdict,
     acceptance: {
@@ -233,7 +241,7 @@ function getTaskDir(taskId: string) {
   return { config, taskDir };
 }
 
-function readJson(path: string, config: ReturnType<typeof getConfig>): Record<string, any> {
+function readJson(path: string, config: ReturnType<typeof getConfig>): Record<string, unknown> {
   guardReadPath(path, config.workspaceRoot, config.tasksDir);
   if (!existsSync(path)) return {};
   try {
@@ -252,12 +260,14 @@ function normalizeMaxItems(value: number | undefined): number {
   return value;
 }
 
-function asArray(value: unknown): any[] {
+function asArray(value: unknown): unknown[] {
   return Array.isArray(value) ? value : [];
 }
 
-function asRecord(value: unknown): Record<string, any> {
-  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {};
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
 }
 
 function limitStrings(values: string[], maxItems: number): string[] {

package/src/tools/{schemaDriftCheck.ts → diagnostics/schemaDriftCheck.ts}

@@ -7,9 +7,9 @@
  * 本模块只做检测和报告，不做运行时阻断。
  */
 
-import { computeSchemaDigest } from "./toolRegistry.js";
-import type { PatchWardenToolMeta } from "./toolRegistry.js";
-import { CHATGPT_CORE_TOOL_NAMES } from "./toolCatalog.js";
+import { computeSchemaDigest } from "../catalog/toolRegistry.js";
+import type { PatchWardenToolMeta } from "../catalog/toolRegistry.js";
+import { CHATGPT_CORE_TOOL_NAMES } from "../catalog/toolCatalog.js";
 
 // ── 结果类型 ──────────────────────────────────────────────────────
 

package/src/tools/{createDirectSession.ts → direct/createDirectSession.ts}

@@ -1,12 +1,12 @@
 import { existsSync, statSync } from "node:fs";
-import { getConfig } from "../config.js";
-import { PatchWardenError } from "../errors.js";
-import { guardWorkspacePath } from "../security/pathGuard.js";
-import { guardRuntimeSelfModification } from "../security/runtimeGuard.js";
-import { captureRepoSnapshot } from "../runner/changeCapture.js";
+import { getConfig } from "../../config.js";
+import { PatchWardenError } from "../../errors.js";
+import { guardWorkspacePath } from "../../security/pathGuard.js";
+import { guardRuntimeSelfModification } from "../../security/runtimeGuard.js";
+import { captureRepoSnapshot } from "../../runner/changeCapture.js";
 import {
   createDirectSession as createDirectSessionRecord,
-} from "../direct/directSessionStore.js";
+} from "../../direct/directSessionStore.js";
 
 // ── Types ──────────────────────────────────────────────────────────
 

package/src/tools/{finalizeDirectSession.ts → direct/finalizeDirectSession.ts}

@@ -1,18 +1,18 @@
 import { join, resolve, relative, isAbsolute } from "node:path";
 import {
   readDirectSession,
-  updateDirectSession,
   finalizeDirectSessionRecord,
   getDirectSessionDir,
-} from "../direct/directSessionStore.js";
-import { guardDirectSessionActive } from "../direct/directGuards.js";
+  withDirectSessionMutationLockAsync,
+} from "../../direct/directSessionStore.js";
+import { guardDirectSessionActive } from "../../direct/directGuards.js";
 import {
   captureRepoSnapshot,
   buildChangeArtifacts,
   type ChangeArtifacts,
   type ClassifiedChange,
   type ChangedFile,
-} from "../runner/changeCapture.js";
+} from "../../runner/changeCapture.js";
 
 // ── Types ──────────────────────────────────────────────────────────
 
@@ -41,6 +41,7 @@ export async function finalizeDirectSession(
   input: FinalizeDirectSessionInput
 ): Promise<FinalizeDirectSessionOutput> {
   const { session_id } = input;
+  return withDirectSessionMutationLockAsync(session_id, async () => {
 
   // 1. Read session and guard active (not expired, not finalized)
   const session = readDirectSession(session_id);
@@ -58,7 +59,7 @@ export async function finalizeDirectSession(
 
   // 4. Finalize session record — writes changed-files.json, diff.patch,
   //    summary.json, summary.md and marks the session as finalized.
-  finalizeDirectSessionRecord(session_id, afterSnapshot, changeArtifacts);
+  finalizeDirectSessionRecord(session_id, changeArtifacts);
 
   // 5. Build verification summary from session.verification_runs
   const verification_summary: Record<string, "passed" | "failed"> = {};
@@ -91,6 +92,7 @@ export async function finalizeDirectSession(
     finalized: true,
     next_action: "Call audit_session to independently review the changes.",
   };
+  });
 }
 
 // ── Helpers ────────────────────────────────────────────────────────

package/src/tools/direct/index.ts

@@ -0,0 +1,3 @@
+export * from "./createDirectSession.js";
+export * from "./finalizeDirectSession.js";
+export * from "./runDirectVerificationBundle.js";

package/src/tools/{runDirectVerificationBundle.ts → direct/runDirectVerificationBundle.ts}

@@ -1,5 +1,5 @@
-import { getConfig } from "../config.js";
-import { runVerification } from "./runVerification.js";
+import { getConfig } from "../../config.js";
+import { runVerification } from "../tasks/runVerification.js";
 
 export interface RunDirectVerificationBundleInput {
   session_id: string;

package/src/tools/{discoverTools.ts → discovery/discoverTools.ts}

@@ -8,12 +8,12 @@
  */
 
 import { join } from "node:path";
-import type { ToolDef } from "./registry.js";
-import { buildToolRegistry, type PatchWardenToolMeta } from "./toolRegistry.js";
-import { discoverTools as searchDiscover, type DiscoverToolsInput } from "./toolSearch.js";
-import { issueToken } from "../security/discoveryTokenStore.js";
-import { aggregateUsageStats, type ToolUsageStats } from "./toolUsageStats.js";
-import { getConfig } from "../config.js";
+import type { ToolDef } from "../registry.js";
+import { buildToolRegistry, type PatchWardenToolMeta } from "../catalog/toolRegistry.js";
+import { discoverTools as searchDiscover, type DiscoverToolsInput } from "../catalog/toolSearch.js";
+import { issueToken } from "../../security/discoveryTokenStore.js";
+import { aggregateUsageStats, type ToolUsageStats } from "../catalog/toolUsageStats.js";
+import { getConfig } from "../../config.js";
 
 export function discoverTools(
   input: DiscoverToolsInput,

package/src/tools/{explainTool.ts → discovery/explainTool.ts}

@@ -7,9 +7,9 @@
  *         检测 registry 与实际 toolDef 之间的 schema drift。
  */
 
-import type { ToolDef } from "./registry.js";
-import { buildToolRegistry, computeSchemaDigest, type PatchWardenToolMeta } from "./toolRegistry.js";
-import { explainTool as searchExplain, type ExplainToolInput } from "./toolSearch.js";
+import type { ToolDef } from "../registry.js";
+import { buildToolRegistry, computeSchemaDigest, type PatchWardenToolMeta } from "../catalog/toolRegistry.js";
+import { explainTool as searchExplain, type ExplainToolInput } from "../catalog/toolSearch.js";
 
 export function explainTool(
   input: ExplainToolInput,

package/src/tools/discovery/index.ts

@@ -0,0 +1,3 @@
+export * from "./discoverTools.js";
+export * from "./explainTool.js";
+export * from "./invokeDiscoveredTool.js";