patchwarden 1.5.1 → 1.6.2

package/dist/tools/{runTaskLoop.js → tasks/runTaskLoop.js}

@@ -1,13 +1,14 @@
 import { setTimeout as sleep } from "node:timers/promises";
-import { getConfig } from "../config.js";
-import { createWorktree } from "../goal/worktreeManager.js";
-import { guardWorkspacePath } from "../security/pathGuard.js";
-import { createDirectSession } from "./createDirectSession.js";
+import { getConfig } from "../../config.js";
+import { createWorktree } from "../../goal/worktreeManager.js";
+import { guardWorkspacePath } from "../../security/pathGuard.js";
+import { createDirectSession } from "../direct/createDirectSession.js";
 import { createTask } from "./createTask.js";
-import { recommendAgentForTask } from "./recommendAgentForTask.js";
-import { runDirectVerificationBundle } from "./runDirectVerificationBundle.js";
+import { recommendAgentForTask } from "../workspace/recommendAgentForTask.js";
+import { runDirectVerificationBundle } from "../direct/runDirectVerificationBundle.js";
 import { waitForTask } from "./waitForTask.js";
-import { safeAudit, safeAuditDirectSession, safeFinalizeDirectSession, safeResult, safeTestSummary } from "./safeViews.js";
+import { safeAudit, safeAuditDirectSession, safeFinalizeDirectSession, safeResult, safeTestSummary } from "../diagnostics/safeViews.js";
+import { isTerminalTaskStatus } from "./taskStates.js";
 import { createLineageId, writeTaskLineage, } from "./taskLineage.js";
 const DEFAULT_DEPS = {
     createTask,
@@ -26,15 +27,6 @@ const DEFAULT_DEPS = {
     now: () => new Date(),
     sleep,
 };
-const TERMINAL_STATUSES = new Set([
-    "done",
-    "done_by_agent",
-    "failed",
-    "failed_verification",
-    "failed_scope_violation",
-    "failed_policy_violation",
-    "canceled",
-]);
 export async function runTaskLoop(input) {
     return runTaskLoopWithDeps(input, DEFAULT_DEPS);
 }
@@ -130,17 +122,17 @@ export async function runTaskLoopWithDeps(input, deps) {
             timeout_seconds: normalized.task_timeout_seconds,
             execution_mode: "assess_only",
         };
-        const assessment = await deps.createTask(assessmentInput);
+        const assessment = asRecord(await deps.createTask(assessmentInput));
         if (assessment.decision === "blocked") {
-            return finalize("blocked", "high_risk_blocked", "Risk assessment blocked task execution.", assessment.reason_codes?.join(", "));
+            return finalize("blocked", "high_risk_blocked", "Risk assessment blocked task execution.", asArray(assessment.reason_codes).map(String).join(", "));
         }
         if (assessment.decision === "needs_confirm") {
             return finalize("blocked", "user_confirmation_required", "Ask the user to confirm the assessment before executing the loop.");
         }
-        const created = await deps.createTask({
+        const created = asRecord(await deps.createTask({
             execution_mode: "execute",
             assessment_id: String(assessment.assessment_id || ""),
-        });
+        }));
         const taskId = String(created.task_id || "");
         if (!taskId) {
             return finalize("failed", "policy_blocked", "create_task returned no task_id.", "create_task returned no task_id");
@@ -153,9 +145,9 @@ export async function runTaskLoopWithDeps(input, deps) {
         if (wait.stop_reason) {
             return finalize("blocked", wait.stop_reason, wait.next_action, wait.error);
         }
-        const result = deps.safeResult(taskId, { max_items: 8 });
-        const tests = deps.safeTestSummary(taskId);
-        const audit = deps.safeAudit(taskId, { max_items: 8 });
+        const result = asRecord(deps.safeResult(taskId, { max_items: 8 }));
+        const tests = asRecord(deps.safeTestSummary(taskId));
+        const audit = asRecord(deps.safeAudit(taskId, { max_items: 8 }));
         const round = buildRound(iteration, taskId, role, result, tests, audit);
         lineage.rounds.push(round);
         lineage.updated_at = deps.now().toISOString();
@@ -186,7 +178,7 @@ async function waitUntilTerminal(taskId, timeoutSeconds, deps) {
     const deadline = Date.now() + timeoutSeconds * 1000;
     while (Date.now() < deadline) {
         const waited = await deps.waitForTask(taskId, 30);
-        if (waited.terminal || TERMINAL_STATUSES.has(String(waited.status))) {
+        if (waited.terminal || isTerminalTaskStatus(String(waited.status))) {
             return { next_action: waited.next_action || "safe_audit" };
         }
         if (waited.next_tool_call?.name === "health_check" || waited.continuation_required === false) {
@@ -204,20 +196,32 @@ async function waitUntilTerminal(taskId, timeoutSeconds, deps) {
         error: `Task loop timed out waiting for ${taskId}.`,
     };
 }
-function buildRound(iteration, taskId, role, result, tests, audit) {
-    const failChecks = Array.isArray(audit.fail_checks) ? audit.fail_checks.map((entry) => String(entry.name || entry)) : [];
-    const warnChecks = Array.isArray(audit.warn_checks) ? audit.warn_checks.map((entry) => String(entry.name || entry)) : [];
+function buildRound(iteration, taskId, role, resultValue, testsValue, auditValue) {
+    const result = asRecord(resultValue);
+    const tests = asRecord(testsValue);
+    const audit = asRecord(auditValue);
+    const resultVerification = asRecord(result.verification);
+    const auditAcceptance = asRecord(audit.acceptance);
+    const failChecks = asArray(audit.fail_checks).map((entry) => {
+        const check = asRecord(entry);
+        return String(check.name || entry);
+    });
+    const warnChecks = asArray(audit.warn_checks).map((entry) => {
+        const check = asRecord(entry);
+        return String(check.name || entry);
+    });
+    const recommendedActions = asArray(audit.recommended_next_actions);
     return {
         iteration,
         task_id: taskId,
         role,
         status: String(result.status || "unknown"),
         terminal: Boolean(result.terminal),
-        verification_status: String(tests.status || result.verification?.status || "not_available"),
-        audit_verdict: String(audit.verdict || audit.acceptance?.verdict || "unknown"),
+        verification_status: String(tests.status || resultVerification.status || "not_available"),
+        audit_verdict: String(audit.verdict || auditAcceptance.verdict || "unknown"),
         fail_checks: failChecks,
         warn_checks: warnChecks,
-        next_action: String(result.next_action || audit.recommended_next_actions?.[0] || "review_task"),
+        next_action: String(result.next_action || recommendedActions[0] || "review_task"),
     };
 }
 function isSuccessfulRound(round) {
@@ -228,23 +232,29 @@ function isSuccessfulRound(round) {
         round.warn_checks.length === 0 &&
         round.audit_verdict === "pass");
 }
-function isHardStop(round, result, audit, stopOnHighRisk) {
-    if (["failed_scope_violation", "failed_policy_violation", "canceled"].includes(round.status))
+function isHardStop(round, resultValue, auditValue, stopOnHighRisk) {
+    if (["failed_scope_violation", "failed_policy_violation", "canceled", "timeout"].includes(round.status))
         return true;
     if (!stopOnHighRisk)
         return false;
     const checkNames = [...round.fail_checks, ...round.warn_checks].join(" ").toLowerCase();
-    const reason = String(result.failure_reason || audit.acceptance?.reason || "").toLowerCase();
+    const result = asRecord(resultValue);
+    const audit = asRecord(auditValue);
+    const reason = String(result.failure_reason || asRecord(audit.acceptance).reason || "").toLowerCase();
     return /scope|secret|sensitive|publish|release|policy|push/.test(`${checkNames} ${reason}`);
 }
-function hardStopReason(round, result) {
+function hardStopReason(round, resultValue) {
+    const result = asRecord(resultValue);
     if (round.status === "failed_scope_violation" || round.status === "failed_policy_violation")
         return "policy_blocked";
+    if (round.status === "timeout")
+        return "agent_timeout";
     if (String(result.failure_reason || "").toLowerCase().includes("timeout"))
         return "agent_timeout";
     return "high_risk_blocked";
 }
-function buildFixGoal(originalGoal, result, round) {
+function buildFixGoal(originalGoal, resultValue, round) {
+    const result = asRecord(resultValue);
     const failedCommand = result.failed_command ? ` Failed command: ${result.failed_command}.` : "";
     return [
         `Fix the failing verification for this PatchWarden loop without changing unrelated behavior.`,
@@ -303,8 +313,12 @@ async function runDirectVerification(lineageId, normalized, repoPath, deps) {
             commands: normalized.direct_verify_commands,
             timeout_seconds: normalized.direct_verify_timeout_seconds,
         });
-        const finalized = await deps.safeFinalizeDirectSession(sessionId, { max_items: 8 });
-        const audit = deps.safeAuditDirectSession(sessionId, { max_items: 8 });
+        const finalized = asRecord(await deps.safeFinalizeDirectSession(sessionId, { max_items: 8 }));
+        const audit = asRecord(deps.safeAuditDirectSession(sessionId, { max_items: 8 }));
+        const auditEvidence = asRecord(audit.evidence);
+        const auditDecision = audit.decision === "pass" || audit.decision === "warn" || audit.decision === "fail"
+            ? audit.decision
+            : "not_run";
         const evidence = {
             session_id: sessionId,
             status: bundle.status,
@@ -312,8 +326,8 @@ async function runDirectVerification(lineageId, normalized, repoPath, deps) {
             passed_commands: bundle.passed_commands,
             failed_commands: bundle.failed_commands,
             timed_out_commands: bundle.timed_out_commands,
-            audit_decision: audit.decision || "not_run",
-            changed_files_total: Number(finalized.changed_files_total || audit.evidence?.changed_files_total || 0),
+            audit_decision: auditDecision,
+            changed_files_total: Number(finalized.changed_files_total || auditEvidence.changed_files_total || 0),
             next_action: String(audit.next_action || bundle.next_action || "review_direct_session"),
         };
         if (bundle.status !== "passed") {
@@ -325,7 +339,7 @@ async function runDirectVerification(lineageId, normalized, repoPath, deps) {
                 error: "Direct verification failed.",
             };
         }
-        if (audit.decision === "fail") {
+        if (auditDecision === "fail") {
             return {
                 evidence,
                 stop_reason: "direct_audit_failed",
@@ -338,7 +352,7 @@ async function runDirectVerification(lineageId, normalized, repoPath, deps) {
             evidence,
             final_status: "accepted",
             next_action: "accept",
-            warning: audit.decision === "warn" ? "Direct audit completed with warnings." : undefined,
+            warning: auditDecision === "warn" ? "Direct audit completed with warnings." : undefined,
         };
     }
     catch (err) {
@@ -357,6 +371,14 @@ async function runDirectVerification(lineageId, normalized, repoPath, deps) {
         };
     }
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
 function normalizeInput(input) {
     const config = getConfig();
     const repoPath = String(input.repo_path || "").trim();

package/dist/tools/tasks/runVerification.js

@@ -0,0 +1,38 @@
+import { readDirectSession, appendDirectSessionVerificationRun, withDirectSessionMutationLockAsync, } from "../../direct/directSessionStore.js";
+import { guardDirectSessionActive } from "../../direct/directGuards.js";
+import { runDirectVerification } from "../../direct/directVerification.js";
+export async function runVerification(input) {
+    return withDirectSessionMutationLockAsync(input.session_id, async () => {
+        // 1. Read session and guard active
+        const session = readDirectSession(input.session_id);
+        guardDirectSessionActive(session);
+        // 2. Call runDirectVerification with command, resolvedRepoPath,
+        //    sessionId, and timeoutSeconds
+        const timeoutSeconds = input.timeout_seconds ?? 120;
+        const result = await runDirectVerification({
+            command: input.command,
+            resolvedRepoPath: session.resolved_repo_path,
+            sessionId: input.session_id,
+            timeoutSeconds,
+        });
+        // 3. Append verification run to session
+        appendDirectSessionVerificationRun(input.session_id, result.run);
+        // 4. Return result
+        return {
+            command: result.run.command,
+            exit_code: result.run.exit_code,
+            passed: result.run.passed,
+            timed_out: result.run.timed_out,
+            redacted: Boolean(result.run.redacted),
+            redaction_categories: result.run.redaction_categories || [],
+            started_at: result.run.started_at,
+            finished_at: result.run.finished_at,
+            stdout_tail: result.run.stdout_tail,
+            stderr_tail: result.run.stderr_tail,
+            log_path: result.run.log_path,
+            next_action: result.run.passed
+                ? "Call finalize_direct_session to complete the session."
+                : "Review the verification output and apply_patch to fix issues.",
+        };
+    });
+}

package/dist/tools/{taskLineage.js → tasks/taskLineage.js}

@@ -1,10 +1,11 @@
 import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { getConfig } from "../config.js";
-import { guardReadPath } from "../security/pathGuard.js";
-import { redactSensitiveValue } from "../security/contentRedaction.js";
-import { PatchWardenError } from "../errors.js";
+import { getConfig } from "../../config.js";
+import { guardReadPath } from "../../security/pathGuard.js";
+import { redactSensitiveValue } from "../../security/contentRedaction.js";
+import { PatchWardenError } from "../../errors.js";
+import { atomicWriteFileSync, atomicWriteJsonFileSync } from "../../utils/atomicFile.js";
 export function createLineageId(now = new Date()) {
     const stamp = now.toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
     return `lineage_${stamp}_${randomBytes(4).toString("hex")}`;
@@ -14,8 +15,8 @@ export function writeTaskLineage(record) {
     const lineageDir = resolve(config.workspaceRoot, ".patchwarden", "lineages", record.lineage_id);
     mkdirSync(lineageDir, { recursive: true });
     const safeRecord = redactSensitiveValue(record).value;
-    writeFileSync(join(lineageDir, "lineage.json"), JSON.stringify(safeRecord, null, 2) + "\n", "utf-8");
-    writeFileSync(join(lineageDir, "SUMMARY.md"), buildSummaryMarkdown(safeRecord), "utf-8");
+    atomicWriteJsonFileSync(join(lineageDir, "lineage.json"), safeRecord);
+    atomicWriteFileSync(join(lineageDir, "SUMMARY.md"), buildSummaryMarkdown(safeRecord));
     return toSafeTaskLineage(safeRecord);
 }
 export function getTaskLineage(lineageId, options = {}) {

package/dist/tools/{taskOutputs.d.ts → tasks/taskOutputs.d.ts}

@@ -14,7 +14,7 @@ export declare function getTaskLogTail(taskId: string, file: "stdout" | "stderr"
     lines?: number;
     redact?: boolean;
 }): {
-    file: "test" | "stdout" | "stderr" | "verify";
+    file: "stdout" | "stderr" | "test" | "verify";
     lines: number;
     total_bytes: number;
     task_id: string;
@@ -37,7 +37,7 @@ export declare function getTaskLogTail(taskId: string, file: "stdout" | "stderr"
     truncated?: undefined;
 } | {
     task_id: string;
-    file: "test" | "stdout" | "stderr" | "verify";
+    file: "stdout" | "stderr" | "test" | "verify";
     filename: string;
     content: string;
     available: boolean;

package/dist/tools/{taskOutputs.js → tasks/taskOutputs.js}

@@ -1,9 +1,10 @@
 import { getTaskFile } from "./getTaskFile.js";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { getConfig, getTasksDir } from "../config.js";
-import { guardPath } from "../security/pathGuard.js";
-import { redactSensitiveContent } from "../security/contentRedaction.js";
+import { getConfig, getTasksDir } from "../../config.js";
+import { guardPath } from "../../security/pathGuard.js";
+import { redactSensitiveContent } from "../../security/contentRedaction.js";
+import { readTextFilePrefixSync, readTextFileTailLinesSync, } from "../../utils/boundedFile.js";
 export function getResult(taskId) {
     return getTaskFile(taskId, "result.md");
 }
@@ -20,10 +21,9 @@ export function getDiff(taskId) {
     }
     const filePath = existsSync(preferred) ? preferred : fallback;
     guardPath(filePath, config.workspaceRoot, config.tasksDir);
-    const size = statSync(filePath).size;
-    const raw = readFileSync(filePath, "utf-8");
-    const patchHead = raw.slice(0, config.maxReadFileBytes);
-    const rawReturnedBytes = Buffer.byteLength(patchHead, "utf-8");
+    const bounded = readTextFilePrefixSync(filePath, config.maxReadFileBytes);
+    const size = bounded.totalBytes;
+    const patchHead = bounded.content;
     const redaction = redactSensitiveContent(patchHead);
     const content = redaction.content;
     const diff = {
@@ -32,7 +32,7 @@ export function getDiff(taskId) {
         content,
         path: filePath,
         available: true,
-        truncated: size > rawReturnedBytes,
+        truncated: bounded.truncated,
         total_bytes: size,
         returned_bytes: Buffer.byteLength(content, "utf-8"),
         patch_head: content,
@@ -90,8 +90,7 @@ export function getTaskLogTail(taskId, file, options) {
     }
     const stat = statSync(filePath);
     const totalBytes = stat.size;
-    const raw = readFileSync(filePath, "utf-8");
-    const tail = raw.split("\n").slice(-maxLines).join("\n");
+    const tail = readTextFileTailLinesSync(filePath, maxLines);
     const content = applyRedact ? redactSensitiveContent(tail) : { content: tail, redacted: false, redaction_categories: [] };
     return {
         task_id: taskId,
@@ -115,13 +114,15 @@ function getTaskFileTail(taskId, filename, options) {
         return getTaskFile(taskId, filename);
     }
     const stat = statSync(filePath);
-    const raw = readFileSync(filePath, "utf-8");
-    let content = raw;
+    const maxBytes = options.maxBytes > 0
+        ? Math.min(options.maxBytes, config.maxReadFileBytes)
+        : config.maxReadFileBytes;
+    let content;
     if (options.tailLines > 0) {
-        content = raw.split("\n").slice(-options.tailLines).join("\n");
+        content = readTextFileTailLinesSync(filePath, Math.min(Math.max(1, options.tailLines), 1000), maxBytes);
     }
-    if (options.maxBytes > 0 && Buffer.byteLength(content, "utf-8") > options.maxBytes) {
-        content = content.slice(0, options.maxBytes);
+    else {
+        content = readTextFilePrefixSync(filePath, maxBytes).content;
     }
     const redaction = redactSensitiveContent(content);
     return {

package/dist/tools/tasks/taskStates.d.ts

@@ -0,0 +1,6 @@
+export declare const ACTIVE_TASK_STATUSES: Set<string>;
+export declare const TERMINAL_TASK_STATUSES: Set<string>;
+export declare function isTerminalTaskStatus(status: string): boolean;
+export declare function isActiveTaskStatus(status: string): boolean;
+/** Terminal states are immutable; active states may only advance or terminate. */
+export declare function isAllowedTaskStatusTransition(from: string, to: string): boolean;

package/dist/tools/tasks/taskStates.js

@@ -0,0 +1,52 @@
+export const ACTIVE_TASK_STATUSES = new Set([
+    "pending",
+    "running",
+    "executing_agent",
+    "verifying",
+    "collecting_artifacts",
+    "cancel_requested",
+]);
+export const TERMINAL_TASK_STATUSES = new Set([
+    "done",
+    "done_by_agent",
+    "accepted",
+    "rejected",
+    "needs_fix",
+    "blocked",
+    "failed",
+    "failed_verification",
+    "failed_scope_violation",
+    "failed_policy_violation",
+    "failed_stale",
+    "orphaned",
+    "timeout",
+    "canceled",
+]);
+export function isTerminalTaskStatus(status) {
+    return TERMINAL_TASK_STATUSES.has(status);
+}
+export function isActiveTaskStatus(status) {
+    return ACTIVE_TASK_STATUSES.has(status);
+}
+/** Terminal states are immutable; active states may only advance or terminate. */
+export function isAllowedTaskStatusTransition(from, to) {
+    if (from === to)
+        return true;
+    if (isTerminalTaskStatus(from))
+        return false;
+    if (!isActiveTaskStatus(from) || !isActiveTaskStatus(to) && !isTerminalTaskStatus(to))
+        return false;
+    if (from === "pending") {
+        return to === "running" || isTerminalTaskStatus(to);
+    }
+    if (to === "pending")
+        return false;
+    const forwardActive = {
+        running: new Set(["executing_agent", "verifying", "collecting_artifacts", "cancel_requested"]),
+        executing_agent: new Set(["verifying", "collecting_artifacts", "cancel_requested"]),
+        verifying: new Set(["collecting_artifacts", "cancel_requested"]),
+        collecting_artifacts: new Set(["cancel_requested"]),
+        cancel_requested: new Set(),
+    };
+    return isTerminalTaskStatus(to) || Boolean(forwardActive[from]?.has(to));
+}

package/dist/tools/{waitForTask.js → tasks/waitForTask.js}

@@ -1,15 +1,7 @@
 import { setTimeout as sleep } from "node:timers/promises";
 import { getTaskStatus } from "./getTaskStatus.js";
 import { getTaskSummary } from "./getTaskSummary.js";
-const TERMINAL_STATUSES = new Set([
-    "done",
-    "done_by_agent",
-    "failed",
-    "failed_verification",
-    "failed_scope_violation",
-    "failed_policy_violation",
-    "canceled",
-]);
+import { isTerminalTaskStatus } from "./taskStates.js";
 export async function waitForTask(taskId, waitSeconds = 25) {
     if (!Number.isInteger(waitSeconds) || waitSeconds < 1 || waitSeconds > 30) {
         throw new Error("wait_seconds must be an integer from 1 to 30.");
@@ -17,11 +9,11 @@ export async function waitForTask(taskId, waitSeconds = 25) {
     const started = Date.now();
     const deadline = started + waitSeconds * 1000;
     let status = getTaskStatus(taskId);
-    while (!TERMINAL_STATUSES.has(status.status) && Date.now() < deadline) {
+    while (!isTerminalTaskStatus(status.status) && Date.now() < deadline) {
         await sleep(Math.min(500, Math.max(1, deadline - Date.now())));
         status = getTaskStatus(taskId);
     }
-    const terminal = TERMINAL_STATUSES.has(status.status);
+    const terminal = isTerminalTaskStatus(status.status);
     const executionBlocked = !terminal && status.execution_blocked;
     const elapsed = Math.round((Date.now() - started) / 1000);
     const progressSummary = {

package/dist/tools/{androidDoctor.js → workspace/androidDoctor.js}

@@ -7,9 +7,9 @@
  * and never installs global dependencies. It only runs `java -version` (read-only)
  * and inspects files/directories/env vars that already exist.
  */
-import { execSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { runSimpleProcessSync } from "../../runner/simpleProcess.js";
 // ── Constants ──────────────────────────────────────────────────────
 /**
  * Required explanatory sentence emitted whenever the Android SDK is missing.
@@ -18,17 +18,23 @@ import { join } from "node:path";
 const SDK_MISSING_REASON = "Android project exists, APK not built because Android SDK is missing.";
 // ── Helpers ────────────────────────────────────────────────────────
 /**
- * Run a shell command and return its trimmed combined stdout/stderr output.
+ * Run a shell-free command and return its trimmed combined stdout/stderr output.
  * Returns an empty string when the command is missing or fails so callers can
  * treat absence gracefully. A timeout guards against hanging processes.
  */
-function runCmd(cmdStr) {
+function runCmd(command, args, cwd = process.cwd()) {
     try {
-        return execSync(cmdStr, {
-            encoding: "utf-8",
-            timeout: 8000,
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
+        const result = runSimpleProcessSync({
+            command,
+            args: [...args],
+            cwd,
+            timeoutMs: 8000,
+            maxStdoutBytes: 64 * 1024,
+            maxStderrBytes: 64 * 1024,
+        });
+        if (result.exitCode !== 0)
+            return "";
+        return `${result.stdout}\n${result.stderr}`.trim();
     }
     catch {
         return "";
@@ -95,8 +101,8 @@ export function diagnoseAndroidBuild(repoPath) {
     const sdkRoot = androidHomeEnv || androidSdkRootEnv;
     const sdkExists = sdkRoot !== "" && isDirectory(sdkRoot);
     // 1. java -version ------------------------------------------------------
-    // `java -version` writes to stderr; redirect with 2>&1 so execSync captures it.
-    const javaOutput = runCmd("java -version 2>&1");
+    // `java -version` normally writes to stderr; runSimpleProcessSync captures both.
+    const javaOutput = runCmd("java", ["-version"], repoPath);
     const javaVersion = parseJavaVersion(javaOutput);
     if (javaVersion) {
         const major = parseJavaMajor(javaVersion);

package/dist/tools/{applyPatch.d.ts → workspace/applyPatch.d.ts}

@@ -1,4 +1,4 @@
-import { type PatchOperation } from "../direct/directPatch.js";
+import { type PatchOperation } from "../../direct/directPatch.js";
 export interface ApplyPatchInput {
     session_id: string;
     path: string;

package/dist/tools/workspace/applyPatch.js

@@ -0,0 +1,53 @@
+import { getConfig } from "../../config.js";
+import { PatchWardenError } from "../../errors.js";
+import { readDirectSession, appendDirectSessionOperation, withDirectSessionMutationLock, } from "../../direct/directSessionStore.js";
+import { guardDirectSessionActive, guardDirectWritePath, guardDirectPatchSize, } from "../../direct/directGuards.js";
+import { applyPatchOperations, computeFileSha256, } from "../../direct/directPatch.js";
+export function applyPatch(input) {
+    const config = getConfig();
+    return withDirectSessionMutationLock(input.session_id, () => {
+        // 1. Read session and guard active (not expired, not finalized)
+        const session = readDirectSession(input.session_id);
+        guardDirectSessionActive(session);
+        // 2. Guard write path (inside repo, not sensitive, not binary,
+        //    not node_modules/release/dist)
+        const resolvedPath = guardDirectWritePath(input.path, session.resolved_repo_path, config.workspaceRoot);
+        // 3. Calculate patch size and guard against directMaxPatchBytes
+        const patchBytes = Buffer.byteLength(JSON.stringify(input.operations), "utf-8");
+        guardDirectPatchSize(patchBytes);
+        // 4. Apply against the same bytes whose hash is validated. Re-resolve the
+        // target immediately before replacement to detect link/reparse-point swaps.
+        const patchResult = applyPatchOperations(resolvedPath, input.operations, {
+            expectedSha256: input.expected_sha256,
+            maxFileBytes: config.directMaxFileBytes,
+            revalidatePath: () => guardDirectWritePath(input.path, session.resolved_repo_path, config.workspaceRoot),
+        });
+        const beforeSha256 = patchResult.before_sha256;
+        // Re-read the file from disk to compute the authoritative after_sha256
+        const finalPath = guardDirectWritePath(input.path, session.resolved_repo_path, config.workspaceRoot);
+        const afterSha256 = computeFileSha256(finalPath);
+        if (afterSha256 !== patchResult.after_sha256) {
+            throw new PatchWardenError("direct_target_changed_after_write", `Patch target "${input.path}" changed before the operation could be recorded.`, "Inspect the file and retry only after concurrent filesystem changes stop.", true, { path: input.path, expected_sha256: patchResult.after_sha256, actual_sha256: afterSha256 });
+        }
+        // 6. Append operation record to session
+        appendDirectSessionOperation(input.session_id, {
+            index: 0,
+            timestamp: new Date().toISOString(),
+            path: input.path,
+            operation_type: "patch",
+            before_sha256: beforeSha256,
+            after_sha256: afterSha256,
+            operations_applied: patchResult.operations_applied,
+            bytes_changed: patchResult.bytes_changed,
+        });
+        // 7. Return result
+        return {
+            path: input.path,
+            before_sha256: beforeSha256,
+            after_sha256: afterSha256,
+            operations_applied: patchResult.operations_applied,
+            bytes_changed: patchResult.bytes_changed,
+            next_action: "Call run_verification to test the changes, or apply_patch for more edits.",
+        };
+    }, config);
+}

package/dist/tools/{discardWorktree.js → workspace/discardWorktree.js}

@@ -4,9 +4,9 @@
  *
  * 参考 src/tools/auditTask.ts 的导出/返回风格。
  */
-import { getConfig } from "../config.js";
-import { guardWorkspacePath } from "../security/pathGuard.js";
-import { discardWorktree } from "../goal/worktreeManager.js";
+import { getConfig } from "../../config.js";
+import { guardWorkspacePath } from "../../security/pathGuard.js";
+import { discardWorktree } from "../../goal/worktreeManager.js";
 /**
  * 丢弃指定 worktree：移除 worktree 目录、删除临时 branch、归档状态。
  *

package/dist/tools/workspace/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./androidDoctor.js";
+export * from "./applyPatch.js";
+export * from "./discardWorktree.js";
+export * from "./listAgents.js";
+export * from "./listWorkspace.js";
+export * from "./mergeWorktree.js";
+export * from "./readWorkspaceFile.js";
+export * from "./recommendAgentForTask.js";
+export * from "./searchWorkspace.js";
+export * from "./syncFile.js";

package/dist/tools/workspace/index.js

@@ -0,0 +1,10 @@
+export * from "./androidDoctor.js";
+export * from "./applyPatch.js";
+export * from "./discardWorktree.js";
+export * from "./listAgents.js";
+export * from "./listWorkspace.js";
+export * from "./mergeWorktree.js";
+export * from "./readWorkspaceFile.js";
+export * from "./recommendAgentForTask.js";
+export * from "./searchWorkspace.js";
+export * from "./syncFile.js";

package/dist/tools/workspace/listAgents.d.ts

@@ -0,0 +1,23 @@
+export interface AgentAvailability {
+    name: string;
+    configured: true;
+    available: boolean;
+    command: string;
+    reason: string | null;
+    checked_at: string;
+    adapter: string | null;
+    model: string | null;
+    capabilities: {
+        model_override: boolean;
+    };
+    availability_scope: "executable_only";
+    provider_status: "not_checked";
+    invocation_ready?: boolean;
+    model_argument_present?: boolean;
+}
+export declare function listAgents(): {
+    agents: AgentAvailability[];
+    total: number;
+    config_path: string;
+    workspace_root: string;
+};