patchwarden 1.5.0 → 1.6.1

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/{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/{listAgents.d.ts → workspace/listAgents.d.ts}

@@ -5,6 +5,11 @@ export interface AgentAvailability {
     command: string;
     reason: string | null;
     checked_at: string;
+    adapter: string | null;
+    model: string | null;
+    capabilities: {
+        model_override: boolean;
+    };
 }
 export declare function listAgents(): {
     agents: AgentAvailability[];

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

@@ -1,13 +1,14 @@
 import { existsSync, statSync } from "node:fs";
 import { basename, delimiter, extname, isAbsolute, join } from "node:path";
-import { getConfig } from "../config.js";
+import { getConfig } from "../../config.js";
+import { sanitizeTrustedPath } from "../../runner/processSecurity.js";
 export function listAgents() {
     const config = getConfig();
     const checkedAt = new Date().toISOString();
     const agents = Object.entries(config.agents)
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([name, agent]) => {
-        const available = commandExists(agent.command);
+        const available = commandExists(agent.command, config.workspaceRoot);
         return {
             name,
             configured: true,
@@ -15,15 +16,18 @@ export function listAgents() {
             command: basename(agent.command),
             reason: available ? null : "Configured executable was not found on disk or PATH.",
             checked_at: checkedAt,
+            adapter: typeof agent.adapter === "string" ? agent.adapter : ["codex", "opencode"].includes(name) ? name : null,
+            model: typeof agent.model === "string" ? agent.model : null,
+            capabilities: { model_override: typeof agent.adapter === "string" || ["codex", "opencode"].includes(name) },
         };
     });
     return { agents, total: agents.length };
 }
-function commandExists(command) {
+function commandExists(command, workspaceRoot) {
     if (isAbsolute(command) || command.includes("/") || command.includes("\\")) {
         return isFile(command);
     }
-    const pathEntries = (process.env.PATH || "").split(delimiter).filter(Boolean);
+    const pathEntries = sanitizeTrustedPath(process.env.PATH || "", workspaceRoot).split(delimiter).filter(Boolean);
     const extensions = process.platform === "win32"
         ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";")
         : [""];

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

@@ -1,8 +1,8 @@
 import { readdirSync, statSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { getConfig } from "../config.js";
-import { guardPath } from "../security/pathGuard.js";
-import { guardSensitivePath } from "../security/sensitiveGuard.js";
+import { getConfig } from "../../config.js";
+import { guardPath } from "../../security/pathGuard.js";
+import { guardSensitivePath } from "../../security/sensitiveGuard.js";
 const MAX_LIST_FILES = 200;
 export function listWorkspace(relativePath) {
     const config = getConfig();

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

@@ -4,9 +4,9 @@
  *
  * 参考 src/tools/auditTask.ts 的导出/返回风格。
  */
-import { getConfig } from "../config.js";
-import { guardWorkspacePath } from "../security/pathGuard.js";
-import { mergeWorktree } from "../goal/worktreeManager.js";
+import { getConfig } from "../../config.js";
+import { guardWorkspacePath } from "../../security/pathGuard.js";
+import { mergeWorktree } from "../../goal/worktreeManager.js";
 /**
  * 合并指定 worktree 的 branch 回 repo_path（主工作区）。
  *

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

@@ -1,13 +1,13 @@
 import { readFileSync, statSync, existsSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { getConfig } from "../config.js";
-import { guardReadPath } from "../security/pathGuard.js";
-import { guardSensitivePath } from "../security/sensitiveGuard.js";
-import { redactSensitiveContent } from "../security/contentRedaction.js";
-import { PatchWardenError } from "../errors.js";
-import { readDirectSession } from "../direct/directSessionStore.js";
-import { guardDirectSessionActive, guardDirectReadPath, isBinaryFile, guardDirectFileSize } from "../direct/directGuards.js";
-import { resolveToolProfile } from "./toolCatalog.js";
+import { getConfig } from "../../config.js";
+import { guardReadPath } from "../../security/pathGuard.js";
+import { guardSensitivePath } from "../../security/sensitiveGuard.js";
+import { redactSensitiveContent } from "../../security/contentRedaction.js";
+import { PatchWardenError } from "../../errors.js";
+import { readDirectSession } from "../../direct/directSessionStore.js";
+import { guardDirectSessionActive, guardDirectReadPath, isBinaryFile, guardDirectFileSize } from "../../direct/directGuards.js";
+import { resolveToolProfile } from "../catalog/toolCatalog.js";
 export function readWorkspaceFile(input) {
     const config = getConfig();
     // Support both old string API and new object API

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

@@ -1,6 +1,6 @@
-import { getConfig } from "../config.js";
-import { guardWorkspacePath } from "../security/pathGuard.js";
-import { routeAgent } from "../agents/agentRouter.js";
+import { getConfig } from "../../config.js";
+import { guardWorkspacePath } from "../../security/pathGuard.js";
+import { routeAgent } from "../../agents/agentRouter.js";
 export function recommendAgentForTask(input) {
     const config = getConfig();
     const repoPath = String(input.repo_path || "").trim();

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

@@ -1,10 +1,10 @@
 import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
 import { relative, join, extname } from "node:path";
-import { getConfig } from "../config.js";
-import { PatchWardenError } from "../errors.js";
-import { isSensitivePath } from "../security/sensitiveGuard.js";
-import { validateDirectSessionFreshness, } from "../direct/directSessionStore.js";
-import { guardDirectSessionActive } from "../direct/directGuards.js";
+import { getConfig } from "../../config.js";
+import { PatchWardenError } from "../../errors.js";
+import { isSensitivePath } from "../../security/sensitiveGuard.js";
+import { validateDirectSessionFreshness, } from "../../direct/directSessionStore.js";
+import { guardDirectSessionActive } from "../../direct/directGuards.js";
 // ── Constants ──────────────────────────────────────────────────────
 const SKIP_DIRECTORIES = new Set([
     ".git",

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

@@ -1,4 +1,4 @@
-import { type PatchWardenConfig } from "../config.js";
+import { type PatchWardenConfig } from "../../config.js";
 export interface SyncFileResult {
     source_path: string;
     target_path: string;

package/dist/tools/workspace/syncFile.js

@@ -0,0 +1,134 @@
+import { readFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname } from "node:path";
+import { PatchWardenError } from "../../errors.js";
+import { getConfig } from "../../config.js";
+import { guardDirectReadPath, guardDirectFileSize, guardDirectSessionActive, guardDirectWritePath, } from "../../direct/directGuards.js";
+import { appendDirectSessionOperation, readDirectSession, withDirectSessionMutationLock, } from "../../direct/directSessionStore.js";
+import { computeFileSha256 } from "../../direct/directPatch.js";
+import { atomicWriteFileSync } from "../../utils/atomicFile.js";
+import { redactSensitiveContent } from "../../security/contentRedaction.js";
+/**
+ * Copy a file from source to target within the same session repo.
+ * Both source and target must be inside the session's repo_path.
+ */
+export function syncFile(sessionId, sourcePath, targetPath, options, config) {
+    const cfg = config || getConfig();
+    return withDirectSessionMutationLock(sessionId, () => {
+        const session = readDirectSession(sessionId, cfg);
+        guardDirectSessionActive(session);
+        const repoPath = session.resolved_repo_path;
+        const workspaceRoot = cfg.workspaceRoot;
+        // Guard source path — must be inside repo and not internal/sensitive/binary.
+        const resolvedSource = guardDirectReadPath(sourcePath, repoPath, workspaceRoot);
+        if (!existsSync(resolvedSource)) {
+            throw new PatchWardenError("source_file_not_found", `Source file does not exist: "${sourcePath}".`, "Ensure the source path is correct.", true, { source_path: sourcePath });
+        }
+        // Guard target path — must be inside repo, not in blocked dirs
+        const resolvedTarget = guardDirectWritePath(targetPath, repoPath, workspaceRoot);
+        const sourceMetadata = statSync(resolvedSource);
+        if (!sourceMetadata.isFile()) {
+            throw new PatchWardenError("direct_source_not_file", `Source path is not a regular file: "${sourcePath}".`, "Choose an existing text file inside the Direct session repository.", true, { source_path: sourcePath });
+        }
+        guardDirectFileSize(sourceMetadata.size, cfg);
+        // Read once, then hash the exact bytes that will be copied.
+        const sourceContent = readFileSync(resolvedSource);
+        guardDirectFileSize(sourceContent.length, cfg);
+        const sourceText = sourceContent.toString("utf-8");
+        if (!Buffer.from(sourceText, "utf-8").equals(sourceContent)) {
+            throw new PatchWardenError("unsupported_text_encoding", `Source file "${sourcePath}" is not valid UTF-8 text.`, "Use a normal task or convert the file to UTF-8 before Direct sync.", true, { source_path: sourcePath });
+        }
+        const sensitive = redactSensitiveContent(sourceText);
+        if (sensitive.redacted) {
+            throw new PatchWardenError("sensitive_content_blocked", `Source file contains credential-like content (${sensitive.redaction_categories.join(", ")}).`, "Remove the sensitive value and retry with placeholders or environment-variable references.", true, { source_path: sourcePath, redaction_categories: sensitive.redaction_categories });
+        }
+        const sourceSha256 = createHash("sha256").update(sourceContent).digest("hex");
+        if (options?.expected_source_sha256 && options.expected_source_sha256 !== sourceSha256) {
+            throw new PatchWardenError("source_hash_mismatch", `Source file hash mismatch. Expected "${options.expected_source_sha256}" but got "${sourceSha256}".`, "Re-read the source file to get the current sha256.", true, { expected_sha256: options.expected_source_sha256, actual_sha256: sourceSha256 });
+        }
+        // Get target sha256 before copy
+        let beforeTargetSha256 = null;
+        if (existsSync(resolvedTarget)) {
+            const targetMetadata = statSync(resolvedTarget);
+            if (!targetMetadata.isFile()) {
+                throw new PatchWardenError("direct_target_not_file", `Target path is not a regular file: "${targetPath}".`, "Choose a text-file target inside the Direct session repository.", true, { target_path: targetPath });
+            }
+            guardDirectFileSize(targetMetadata.size, cfg);
+            beforeTargetSha256 = computeFileSha256(resolvedTarget);
+            // Verify target sha256 if provided
+            if (options?.expected_target_sha256 && options.expected_target_sha256 !== beforeTargetSha256) {
+                throw new PatchWardenError("target_hash_mismatch", `Target file hash mismatch. Expected "${options.expected_target_sha256}" but got "${beforeTargetSha256}".`, "Re-read the target file to get the current sha256.", true, { expected_sha256: options.expected_target_sha256, actual_sha256: beforeTargetSha256 });
+            }
+        }
+        const copiedBytes = sourceContent.length;
+        if (beforeTargetSha256 === sourceSha256) {
+            assertSourceUnchanged(sourcePath, resolvedSource, sourceSha256, repoPath, workspaceRoot);
+            appendSyncOperation(sessionId, sourcePath, targetPath, beforeTargetSha256, sourceSha256, 0, 0, cfg);
+            return buildSyncResult(sourcePath, targetPath, beforeTargetSha256, sourceSha256, copiedBytes, false);
+        }
+        // Create target directory if needed
+        mkdirSync(dirname(resolvedTarget), { recursive: true });
+        // Re-resolve after directory creation so a newly exposed link/reparse point
+        // cannot reuse the earlier lexical decision. Replace atomically in the
+        // validated target directory and preserve an existing file's permissions.
+        const revalidatedTarget = guardDirectWritePath(resolvedTarget, repoPath, workspaceRoot);
+        const currentTargetSha256 = existsSync(revalidatedTarget)
+            ? computeFileSha256(revalidatedTarget)
+            : null;
+        if (currentTargetSha256 !== beforeTargetSha256) {
+            throw new PatchWardenError("direct_target_changed_during_sync", `Target file "${targetPath}" changed while sync_file was preparing the copy.`, "Re-read the target file and retry after concurrent filesystem changes stop.", true, {
+                path: targetPath,
+                before_sha256: beforeTargetSha256,
+                current_sha256: currentTargetSha256,
+            });
+        }
+        assertSourceUnchanged(sourcePath, resolvedSource, sourceSha256, repoPath, workspaceRoot);
+        const existingMode = existsSync(revalidatedTarget) ? statSync(revalidatedTarget).mode : undefined;
+        atomicWriteFileSync(revalidatedTarget, sourceContent, { mode: existingMode });
+        const finalTarget = guardDirectWritePath(revalidatedTarget, repoPath, workspaceRoot);
+        if (finalTarget !== revalidatedTarget) {
+            throw new PatchWardenError("direct_path_changed_during_write", `Target path "${targetPath}" changed while sync_file was writing it.`, "Inspect the repository path and retry only after concurrent filesystem changes stop.", true, { path: targetPath, operation: "sync_file" });
+        }
+        // Compute after hash
+        const afterTargetSha256 = computeFileSha256(finalTarget);
+        const changed = beforeTargetSha256 !== afterTargetSha256;
+        appendSyncOperation(sessionId, sourcePath, targetPath, beforeTargetSha256, afterTargetSha256, 1, copiedBytes, cfg);
+        return buildSyncResult(sourcePath, targetPath, beforeTargetSha256, afterTargetSha256, copiedBytes, changed);
+    }, cfg);
+}
+function assertSourceUnchanged(sourcePath, resolvedSource, expectedSha256, repoPath, workspaceRoot) {
+    const currentPath = guardDirectReadPath(sourcePath, repoPath, workspaceRoot);
+    const samePath = process.platform === "win32"
+        ? currentPath.toLowerCase() === resolvedSource.toLowerCase()
+        : currentPath === resolvedSource;
+    const currentSha256 = samePath && existsSync(currentPath)
+        ? computeFileSha256(currentPath)
+        : null;
+    if (!samePath || currentSha256 !== expectedSha256) {
+        throw new PatchWardenError("direct_source_changed_during_sync", `Source file "${sourcePath}" changed while sync_file was preparing the copy.`, "Re-read the source file and retry after concurrent filesystem changes stop.", true, { source_path: sourcePath, expected_sha256: expectedSha256, actual_sha256: currentSha256 });
+    }
+}
+function appendSyncOperation(sessionId, sourcePath, targetPath, beforeSha256, afterSha256, operationsApplied, bytesChanged, config) {
+    appendDirectSessionOperation(sessionId, {
+        index: 0,
+        timestamp: new Date().toISOString(),
+        path: targetPath,
+        source_path: sourcePath,
+        operation_type: "sync",
+        before_sha256: beforeSha256,
+        after_sha256: afterSha256,
+        operations_applied: operationsApplied,
+        bytes_changed: bytesChanged,
+    }, config);
+}
+function buildSyncResult(sourcePath, targetPath, beforeSha256, afterSha256, copiedBytes, changed) {
+    return {
+        source_path: sourcePath,
+        target_path: targetPath,
+        before_target_sha256: beforeSha256,
+        after_target_sha256: afterSha256,
+        source_sha256: afterSha256,
+        copied_bytes: copiedBytes,
+        changed,
+    };
+}

package/dist/utils/atomicFile.d.ts

@@ -0,0 +1,7 @@
+export interface AtomicWriteOptions {
+    encoding?: BufferEncoding;
+    mode?: number;
+}
+/** Replace a file from a complete same-directory temporary file. */
+export declare function atomicWriteFileSync(path: string, content: string | NodeJS.ArrayBufferView, options?: AtomicWriteOptions): void;
+export declare function atomicWriteJsonFileSync(path: string, value: unknown, mode?: number): void;

package/dist/utils/atomicFile.js

@@ -0,0 +1,48 @@
+import { randomBytes } from "node:crypto";
+import { renameSync, rmSync, writeFileSync } from "node:fs";
+const transientWindowsRenameErrors = new Set(["EACCES", "EBUSY", "EPERM"]);
+const renameRetryDeadlineMs = 1_000;
+const renameRetryDelayMs = 10;
+const waitArray = new Int32Array(new SharedArrayBuffer(4));
+/** Replace a file from a complete same-directory temporary file. */
+export function atomicWriteFileSync(path, content, options = {}) {
+    const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        writeFileSync(temporaryPath, content, {
+            encoding: options.encoding ?? "utf-8",
+            flag: "wx",
+            ...(options.mode === undefined ? {} : { mode: options.mode }),
+        });
+        replaceFileSync(temporaryPath, path);
+    }
+    catch (error) {
+        try {
+            rmSync(temporaryPath, { force: true });
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function replaceFileSync(temporaryPath, path) {
+    const deadline = Date.now() + renameRetryDeadlineMs;
+    while (true) {
+        try {
+            renameSync(temporaryPath, path);
+            return;
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? String(error.code || "")
+                : "";
+            if (process.platform !== "win32" ||
+                !transientWindowsRenameErrors.has(code) ||
+                Date.now() >= deadline) {
+                throw error;
+            }
+            Atomics.wait(waitArray, 0, 0, renameRetryDelayMs);
+        }
+    }
+}
+export function atomicWriteJsonFileSync(path, value, mode = 0o600) {
+    atomicWriteFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { mode });
+}

package/dist/utils/boundedFile.d.ts

@@ -0,0 +1,8 @@
+export interface BoundedTextRead {
+    content: string;
+    totalBytes: number;
+    truncated: boolean;
+}
+export declare function readTextFilePrefixSync(path: string, maxBytes: number): BoundedTextRead;
+export declare function readTextFileTailLinesSync(path: string, lines: number, maxBytes?: number): string;
+export declare function appendBoundedTextFileSync(path: string, content: string, maxBytes?: number): void;