patchwarden 0.4.0 → 0.6.1

package/src/test/unit/path-guard.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import { strict as assert } from "node:assert";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { guardPath, guardWorkspacePath } from "../../security/pathGuard.js";
+import { PatchWardenError } from "../../errors.js";
+
+describe("guardPath", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "pw-pathguard-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("allows paths inside workspace", () => {
+    const result = guardPath("src/main.ts", tempDir);
+    assert.ok(result.startsWith(tempDir));
+    assert.ok(result.includes("src"));
+    assert.ok(result.includes("main.ts"));
+  });
+
+  it("allows root workspace path", () => {
+    const result = guardPath(".", tempDir);
+    assert.equal(result, resolve(tempDir));
+  });
+
+  it("allows empty path as workspace root", () => {
+    const result = guardPath("", tempDir);
+    assert.equal(result, resolve(tempDir));
+  });
+
+  it("rejects path traversal with ..", () => {
+    assert.throws(
+      () => guardPath("../../../etc/passwd", tempDir),
+      PatchWardenError
+    );
+  });
+
+  it("rejects path traversal nested with ..", () => {
+    assert.throws(
+      () => guardPath("src/../../../etc/passwd", tempDir),
+      PatchWardenError
+    );
+  });
+
+  it("rejects absolute path outside workspace", () => {
+    const outside = process.platform === "win32" ? "C:\\Windows\\System32" : "/etc";
+    assert.throws(
+      () => guardPath(outside, tempDir),
+      PatchWardenError
+    );
+  });
+
+  it("allows absolute path inside workspace", () => {
+    const insidePath = join(tempDir, "src", "main.ts");
+    mkdirSync(join(tempDir, "src"), { recursive: true });
+    writeFileSync(insidePath, "test", "utf-8");
+    const result = guardPath(insidePath, tempDir);
+    assert.equal(result, resolve(insidePath));
+  });
+
+  it("enforces allowedPrefix", () => {
+    mkdirSync(join(tempDir, "allowed"), { recursive: true });
+    mkdirSync(join(tempDir, "forbidden"), { recursive: true });
+    // Path inside allowed prefix works
+    const okResult = guardPath("allowed/file.ts", tempDir, "allowed");
+    assert.ok(okResult.includes("allowed"));
+    // Path outside allowed prefix fails
+    assert.throws(
+      () => guardPath("forbidden/file.ts", tempDir, "allowed"),
+      PatchWardenError
+    );
+  });
+
+  it("handles Windows mixed separators", () => {
+    const mixedPath = "src\\subdir/file.ts";
+    const result = guardPath(mixedPath, tempDir);
+    assert.ok(result.startsWith(tempDir));
+  });
+
+  it("rejects symlink escape", { skip: process.platform === "win32" ? "Windows symlink permissions unstable" : undefined }, () => {
+    const target = mkdtempSync(join(tmpdir(), "pw-symlink-target-"));
+    try {
+      const linkPath = join(tempDir, "escape-link");
+      symlinkSync(target, linkPath);
+      assert.throws(
+        () => guardPath("escape-link/secret.txt", tempDir),
+        PatchWardenError
+      );
+    } finally {
+      rmSync(target, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("guardWorkspacePath", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "pw-wspath-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("allows relative path inside workspace", () => {
+    const result = guardWorkspacePath("my-repo", tempDir);
+    assert.equal(result, resolve(tempDir, "my-repo"));
+  });
+
+  it("allows absolute path inside workspace", () => {
+    const absPath = join(tempDir, "my-repo");
+    const result = guardWorkspacePath(absPath, tempDir);
+    assert.equal(result, resolve(absPath));
+  });
+
+  it("rejects path outside workspace", () => {
+    assert.throws(
+      () => guardWorkspacePath("../../../etc", tempDir),
+      PatchWardenError
+    );
+  });
+
+  it("rejects different drive letter on Windows", { skip: process.platform !== "win32" ? "Windows-only test" : undefined }, () => {
+    // If workspace is on C:, a D: path should be rejected
+    const wsDrive = tempDir.match(/^([A-Za-z]):/);
+    if (!wsDrive) return;
+    const otherDrive = wsDrive[1].toLowerCase() === "c" ? "D" : "C";
+    assert.throws(
+      () => guardWorkspacePath(`${otherDrive}:\\some\\repo`, tempDir),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "workspace_path_escape"
+    );
+  });
+
+  it("defaults to workspace root for empty input", () => {
+    const result = guardWorkspacePath("", tempDir);
+    assert.equal(result, resolve(tempDir));
+  });
+
+  it("defaults to workspace root for dot input", () => {
+    const result = guardWorkspacePath(".", tempDir);
+    assert.equal(result, resolve(tempDir));
+  });
+});

package/src/test/unit/safe-status.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import { strict as assert } from "node:assert";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { safeStatus } from "../../tools/safeStatus.js";
+import type { PatchWardenConfig } from "../../config.js";
+
+function makeConfig(workspaceRoot: string): PatchWardenConfig {
+  return {
+    workspaceRoot,
+    plansDir: ".patchwarden/plans",
+    tasksDir: ".patchwarden/tasks",
+    assessmentsDir: ".patchwarden/assessments",
+    assessmentTtlSeconds: 3600,
+    agents: { codex: { command: "codex", args: ["exec", "{prompt}"] } },
+    allowedTestCommands: ["npm test"],
+    repoAllowedTestCommands: {},
+    maxReadFileBytes: 200_000,
+    defaultTaskTimeoutSeconds: 900,
+    maxTaskTimeoutSeconds: 3600,
+    watcherStaleSeconds: 30,
+    directSessionsDir: ".patchwarden/direct-sessions",
+    directSessionTtlSeconds: 3600,
+    directMaxPatchBytes: 200_000,
+    directMaxFileBytes: 500_000,
+  };
+}
+
+describe("safeStatus", () => {
+  let tempDir: string;
+  let config: PatchWardenConfig;
+  let tasksDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "pw-safestatus-"));
+    config = makeConfig(tempDir);
+    tasksDir = join(tempDir, ".patchwarden", "tasks");
+    mkdirSync(tasksDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function writeTaskStatus(taskId: string, status: Record<string, unknown>) {
+    const taskDir = join(tasksDir, taskId);
+    mkdirSync(taskDir, { recursive: true });
+    writeFileSync(join(taskDir, "status.json"), JSON.stringify(status, null, 2), "utf-8");
+    return taskDir;
+  }
+
+  function writeTaskRuntime(taskDir: string, runtime: Record<string, unknown>) {
+    writeFileSync(join(taskDir, "runtime.json"), JSON.stringify(runtime, null, 2), "utf-8");
+  }
+
+  it("returns not_found for non-existent task", () => {
+    const result = safeStatus("non-existent-task", config);
+    assert.equal(result.task_id, "non-existent-task");
+    assert.equal(result.status, "not_found");
+    assert.equal(result.phase, null);
+    assert.equal(result.error_code, null);
+    assert.equal(result.error_summary, null);
+  });
+
+  it("returns correct status for pending task", () => {
+    writeTaskStatus("task-pending-001", {
+      task_id: "task-pending-001",
+      status: "pending",
+      phase: "queued",
+      created_at: "2026-06-24T10:00:00Z",
+      updated_at: "2026-06-24T10:00:01Z",
+    });
+
+    const result = safeStatus("task-pending-001", config);
+    assert.equal(result.task_id, "task-pending-001");
+    assert.equal(result.status, "pending");
+    assert.equal(result.created_at, "2026-06-24T10:00:00Z");
+    assert.equal(result.error_code, null);
+    assert.equal(result.error_summary, null);
+  });
+
+  it("returns correct status for running task", () => {
+    const taskDir = writeTaskStatus("task-running-001", {
+      task_id: "task-running-001",
+      status: "running",
+      phase: "executing_agent",
+      created_at: "2026-06-24T10:00:00Z",
+      started_at: "2026-06-24T10:00:05Z",
+      updated_at: "2026-06-24T10:00:10Z",
+    });
+    writeTaskRuntime(taskDir, {
+      phase: "executing_agent",
+      last_heartbeat_at: "2026-06-24T10:00:12Z",
+      current_command: "codex exec",
+    });
+
+    const result = safeStatus("task-running-001", config);
+    assert.equal(result.status, "running");
+    assert.equal(result.phase, "executing_agent");
+    assert.equal(result.current_command, "codex exec");
+    assert.equal(result.last_heartbeat_at, "2026-06-24T10:00:12Z");
+    assert.equal(result.started_at, "2026-06-24T10:00:05Z");
+  });
+
+  it("returns correct status for done task", () => {
+    writeTaskStatus("task-done-001", {
+      task_id: "task-done-001",
+      status: "done",
+      phase: "completed",
+      created_at: "2026-06-24T10:00:00Z",
+      started_at: "2026-06-24T10:00:05Z",
+      finished_at: "2026-06-24T10:05:00Z",
+      verify_status: "passed",
+    });
+
+    const result = safeStatus("task-done-001", config);
+    assert.equal(result.status, "done");
+    assert.equal(result.phase, "completed");
+    assert.equal(result.finished_at, "2026-06-24T10:05:00Z");
+    assert.equal(result.verify_status, "passed");
+    assert.equal(result.error_code, null);
+  });
+
+  it("returns correct status for failed task", () => {
+    writeTaskStatus("task-failed-001", {
+      task_id: "task-failed-001",
+      status: "failed_verification",
+      phase: "failed_verification",
+      created_at: "2026-06-24T10:00:00Z",
+      started_at: "2026-06-24T10:00:05Z",
+      finished_at: "2026-06-24T10:05:00Z",
+      error: 'Verification command "npm test" exited with code 1.',
+      verify_status: "failed",
+    });
+
+    const result = safeStatus("task-failed-001", config);
+    assert.equal(result.status, "failed_verification");
+    assert.equal(result.error_code, "failed_verification");
+    assert.ok(result.error_summary);
+    assert.ok(result.error_summary!.includes("npm test"));
+  });
+
+  it("does not return diff or file content", () => {
+    const taskDir = writeTaskStatus("task-safe-001", {
+      task_id: "task-safe-001",
+      status: "done",
+      phase: "completed",
+      created_at: "2026-06-24T10:00:00Z",
+    });
+    writeFileSync(join(taskDir, "result.md"), "# Secret result content", "utf-8");
+    writeFileSync(join(taskDir, "git.diff"), "secret diff content", "utf-8");
+    writeFileSync(join(taskDir, "test.log"), "secret test log", "utf-8");
+
+    const result = safeStatus("task-safe-001", config);
+    const resultStr = JSON.stringify(result);
+    assert.ok(!resultStr.includes("Secret result content"));
+    assert.ok(!resultStr.includes("secret diff content"));
+    assert.ok(!resultStr.includes("secret test log"));
+  });
+
+  it("truncates long error messages", () => {
+    const longError = "x".repeat(300);
+    writeTaskStatus("task-longerror-001", {
+      task_id: "task-longerror-001",
+      status: "failed",
+      phase: "failed",
+      error: longError,
+    });
+
+    const result = safeStatus("task-longerror-001", config);
+    assert.ok(result.error_summary!.length < 300);
+    assert.ok(result.error_summary!.endsWith("..."));
+  });
+
+  it("returns artifact_status when present", () => {
+    writeTaskStatus("task-artifact-001", {
+      task_id: "task-artifact-001",
+      status: "done",
+      phase: "completed",
+      artifact_status: "collected",
+    });
+
+    const result = safeStatus("task-artifact-001", config);
+    assert.equal(result.artifact_status, "collected");
+  });
+});

package/src/test/unit/sensitive-guard.test.ts

@@ -0,0 +1,124 @@
+import { describe, it } from "node:test";
+import { strict as assert } from "node:assert";
+import { isSensitivePath, guardSensitivePath } from "../../security/sensitiveGuard.js";
+import { PatchWardenError } from "../../errors.js";
+
+describe("isSensitivePath", () => {
+  it("blocks .env files", () => {
+    assert.equal(isSensitivePath(".env"), true);
+    assert.equal(isSensitivePath("path/to/.env"), true);
+    assert.equal(isSensitivePath(".env.production"), true);
+    assert.equal(isSensitivePath(".env.local"), true);
+  });
+
+  it("blocks .ENV case insensitive", () => {
+    assert.equal(isSensitivePath(".ENV"), true);
+    assert.equal(isSensitivePath("path/to/.ENV"), true);
+    assert.equal(isSensitivePath(".Env.Production"), true);
+  });
+
+  it("blocks config.json case insensitive", () => {
+    assert.equal(isSensitivePath("config.json"), true);
+    assert.equal(isSensitivePath("Config.json"), true);
+    assert.equal(isSensitivePath("CONFIG.JSON"), true);
+    assert.equal(isSensitivePath("path/to/Config.json"), true);
+  });
+
+  it("blocks SSH keys", () => {
+    assert.equal(isSensitivePath("id_rsa"), true);
+    assert.equal(isSensitivePath("id_ed25519"), true);
+    assert.equal(isSensitivePath("id_ecdsa"), true);
+    assert.equal(isSensitivePath("path/to/id_rsa"), true);
+    assert.equal(isSensitivePath(".ssh/id_rsa"), true);
+  });
+
+  it("blocks credentials and tokens", () => {
+    assert.equal(isSensitivePath("credentials"), true);
+    assert.equal(isSensitivePath("path/to/credentials.json"), true);
+    assert.equal(isSensitivePath("token.txt"), true);
+    // access_token does NOT match because the pattern requires token at start or after /
+    assert.equal(isSensitivePath("access_token"), false);
+    assert.equal(isSensitivePath("path/to/token"), true);
+    assert.equal(isSensitivePath(".netrc"), true);
+    assert.equal(isSensitivePath(".npmrc"), true);
+    assert.equal(isSensitivePath(".pypirc"), true);
+  });
+
+  it("blocks private key files", () => {
+    assert.equal(isSensitivePath("server.pem"), true);
+    assert.equal(isSensitivePath("private.key"), true);
+    assert.equal(isSensitivePath("cert.pfx"), true);
+    assert.equal(isSensitivePath("cert.p12"), true);
+  });
+
+  it("blocks browser data files", () => {
+    assert.equal(isSensitivePath("cookies"), true);
+    assert.equal(isSensitivePath("cookies.db"), true);
+    assert.equal(isSensitivePath("Web Data"), true);
+    assert.equal(isSensitivePath("Login Data"), true);
+    assert.equal(isSensitivePath("Local State"), true);
+  });
+
+  it("blocks .git-credentials", () => {
+    assert.equal(isSensitivePath(".git-credentials"), true);
+    assert.equal(isSensitivePath("path/to/.git-credentials"), true);
+  });
+
+  it("blocks docker and kube config", () => {
+    assert.equal(isSensitivePath(".docker/config.json"), true);
+    assert.equal(isSensitivePath(".kube/config"), true);
+  });
+
+  it("allows .patchwarden safe prefix", () => {
+    assert.equal(isSensitivePath(".patchwarden/tasks/task-001/status.json"), false);
+    assert.equal(isSensitivePath(".patchwarden/config.json"), false);
+    assert.equal(isSensitivePath(".patchwarden"), false);
+  });
+
+  it("allows non-sensitive files", () => {
+    assert.equal(isSensitivePath("src/main.ts"), false);
+    assert.equal(isSensitivePath("README.md"), false);
+    assert.equal(isSensitivePath("package.json"), false);
+    assert.equal(isSensitivePath("docs/guide.md"), false);
+  });
+
+  it("handles Windows backslash paths", () => {
+    assert.equal(isSensitivePath("path\\to\\.env"), true);
+    assert.equal(isSensitivePath("path\\to\\config.json"), true);
+    assert.equal(isSensitivePath(".patchwarden\\tasks\\status.json"), false);
+  });
+
+  it("handles null byte in path", () => {
+    // config.json with null byte appended — the $ anchor means this won't match
+    // because the string doesn't end with "config.json"
+    const nullPath = "config.json\x00.txt";
+    assert.equal(isSensitivePath(nullPath), false);
+    // But plain config.json still matches
+    assert.equal(isSensitivePath("config.json"), true);
+  });
+
+  it("handles Unicode lookalike characters", () => {
+    // Full-width dot (U+FF0E) should not match .env pattern
+    // This is expected behavior — Unicode lookalikes are NOT matched
+    const fullWidthPath = "\uFF0Eenv";
+    assert.equal(isSensitivePath(fullWidthPath), false);
+  });
+});
+
+describe("guardSensitivePath", () => {
+  it("throws PatchWardenError for sensitive paths", () => {
+    assert.throws(
+      () => guardSensitivePath(".env"),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "sensitive_path_blocked"
+    );
+  });
+
+  it("does not throw for non-sensitive paths", () => {
+    assert.doesNotThrow(() => guardSensitivePath("src/main.ts"));
+    assert.doesNotThrow(() => guardSensitivePath("README.md"));
+  });
+
+  it("does not throw for .patchwarden paths", () => {
+    assert.doesNotThrow(() => guardSensitivePath(".patchwarden/tasks/status.json"));
+  });
+});

package/src/test/unit/sync-file.test.ts

@@ -0,0 +1,231 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import { strict as assert } from "node:assert";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { syncFile } from "../../tools/syncFile.js";
+import { computeFileSha256 } from "../../direct/directPatch.js";
+import type { PatchWardenConfig } from "../../config.js";
+
+function makeConfig(workspaceRoot: string): PatchWardenConfig {
+  return {
+    workspaceRoot,
+    plansDir: ".patchwarden/plans",
+    tasksDir: ".patchwarden/tasks",
+    assessmentsDir: ".patchwarden/assessments",
+    assessmentTtlSeconds: 3600,
+    agents: { codex: { command: "codex", args: ["exec", "{prompt}"] } },
+    allowedTestCommands: ["npm test"],
+    repoAllowedTestCommands: {},
+    maxReadFileBytes: 200_000,
+    defaultTaskTimeoutSeconds: 900,
+    maxTaskTimeoutSeconds: 3600,
+    watcherStaleSeconds: 30,
+    directSessionsDir: ".patchwarden/direct-sessions",
+    directSessionTtlSeconds: 3600,
+    directMaxPatchBytes: 200_000,
+    directMaxFileBytes: 500_000,
+  };
+}
+
+describe("syncFile", () => {
+  let tempDir: string;
+  let config: PatchWardenConfig;
+  let repoPath: string;
+  let sessionsDir: string;
+  let sessionId: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "pw-syncfile-"));
+    config = makeConfig(tempDir);
+    repoPath = join(tempDir, "my-repo");
+    sessionsDir = join(tempDir, ".patchwarden", "direct-sessions");
+    sessionId = "test-session-001";
+
+    mkdirSync(repoPath, { recursive: true });
+    mkdirSync(join(sessionsDir, sessionId), { recursive: true });
+
+    writeFileSync(
+      join(sessionsDir, sessionId, "session.json"),
+      JSON.stringify({
+        session_id: sessionId,
+        repo_path: repoPath,
+        status: "active",
+        created_at: new Date().toISOString(),
+      }),
+      "utf-8"
+    );
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("copies a file from source to target", () => {
+    const sourceContent = "console.log('hello world');";
+    mkdirSync(join(repoPath, "mobile_app"), { recursive: true });
+    writeFileSync(join(repoPath, "mobile_app", "app.js"), sourceContent, "utf-8");
+
+    const result = syncFile(sessionId, "mobile_app/app.js", "windows_app/app/app.js", undefined, config);
+
+    assert.equal(result.changed, true);
+    assert.equal(result.copied_bytes, sourceContent.length);
+    assert.equal(result.before_target_sha256, null);
+    assert.ok(result.after_target_sha256);
+
+    const targetContent = readFileSync(join(repoPath, "windows_app", "app", "app.js"), "utf-8");
+    assert.equal(targetContent, sourceContent);
+  });
+
+  it("returns changed=false when target already has same content", () => {
+    const sourceContent = "same content";
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    mkdirSync(join(repoPath, "dst"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), sourceContent, "utf-8");
+    writeFileSync(join(repoPath, "dst", "file.ts"), sourceContent, "utf-8");
+
+    const result = syncFile(sessionId, "src/file.ts", "dst/file.ts", undefined, config);
+
+    assert.equal(result.changed, false);
+    assert.ok(result.before_target_sha256);
+    assert.equal(result.before_target_sha256, result.after_target_sha256);
+  });
+
+  it("returns changed=true when target has different content", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    mkdirSync(join(repoPath, "dst"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "new content", "utf-8");
+    writeFileSync(join(repoPath, "dst", "file.ts"), "old content", "utf-8");
+
+    const result = syncFile(sessionId, "src/file.ts", "dst/file.ts", undefined, config);
+
+    assert.equal(result.changed, true);
+    assert.notEqual(result.before_target_sha256, result.after_target_sha256);
+  });
+
+  it("rejects source path outside repo", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "content", "utf-8");
+
+    assert.throws(
+      () => syncFile(sessionId, "../../../etc/passwd", "dst/file.ts", undefined, config),
+      Error
+    );
+  });
+
+  it("rejects target path outside repo", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "content", "utf-8");
+
+    assert.throws(
+      () => syncFile(sessionId, "src/file.ts", "../../../etc/evil", undefined, config),
+      Error
+    );
+  });
+
+  it("rejects sensitive source files", () => {
+    writeFileSync(join(repoPath, ".env"), "SECRET=abc123", "utf-8");
+
+    assert.throws(
+      () => syncFile(sessionId, ".env", "dst/.env", undefined, config),
+      Error
+    );
+  });
+
+  it("rejects sensitive target files", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "content", "utf-8");
+
+    assert.throws(
+      () => syncFile(sessionId, "src/file.ts", "config.json", undefined, config),
+      Error
+    );
+  });
+
+  it("rejects writing to node_modules", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "content", "utf-8");
+
+    assert.throws(
+      () => syncFile(sessionId, "src/file.ts", "node_modules/evil/index.js", undefined, config),
+      Error
+    );
+  });
+
+  it("rejects writing to dist", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "content", "utf-8");
+
+    assert.throws(
+      () => syncFile(sessionId, "src/file.ts", "dist/main.js", undefined, config),
+      Error
+    );
+  });
+
+  it("rejects non-existent session", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "content", "utf-8");
+
+    assert.throws(
+      () => syncFile("non-existent-session", "src/file.ts", "dst/file.ts", undefined, config),
+      Error
+    );
+  });
+
+  it("rejects non-existent source file", () => {
+    assert.throws(
+      () => syncFile(sessionId, "non-existent/file.ts", "dst/file.ts", undefined, config),
+      Error
+    );
+  });
+
+  it("validates expected_source_sha256", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "content", "utf-8");
+
+    const correctHash = computeFileSha256(join(repoPath, "src", "file.ts"));
+
+    const result = syncFile(sessionId, "src/file.ts", "dst/file.ts", {
+      expected_source_sha256: correctHash,
+    }, config);
+    assert.equal(result.source_sha256, correctHash);
+
+    assert.throws(
+      () => syncFile(sessionId, "src/file.ts", "dst2/file.ts", {
+        expected_source_sha256: "wronghash",
+      }, config),
+      Error
+    );
+  });
+
+  it("validates expected_target_sha256", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    mkdirSync(join(repoPath, "dst"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "new content", "utf-8");
+    writeFileSync(join(repoPath, "dst", "file.ts"), "old content", "utf-8");
+
+    const correctTargetHash = computeFileSha256(join(repoPath, "dst", "file.ts"));
+
+    const result = syncFile(sessionId, "src/file.ts", "dst/file.ts", {
+      expected_target_sha256: correctTargetHash,
+    }, config);
+    assert.equal(result.before_target_sha256, correctTargetHash);
+
+    assert.throws(
+      () => syncFile(sessionId, "src/file.ts", "dst/file.ts", {
+        expected_target_sha256: "wronghash",
+      }, config),
+      Error
+    );
+  });
+
+  it("creates target directory if it doesn't exist", () => {
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+    writeFileSync(join(repoPath, "src", "file.ts"), "content", "utf-8");
+
+    const result = syncFile(sessionId, "src/file.ts", "deep/nested/path/file.ts", undefined, config);
+
+    assert.equal(result.changed, true);
+    assert.ok(existsSync(join(repoPath, "deep", "nested", "path", "file.ts")));
+  });
+});