patchwarden 1.1.0 → 1.5.1

package/src/test/unit/direct-guards.test.ts

@@ -5,6 +5,7 @@ import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { guardDirectPath, guardDirectWritePath, guardDirectReadPath, guardDirectPatchSize, guardDirectFileSize, isBinaryFile } from "../../direct/directGuards.js";
 import { PatchWardenError } from "../../errors.js";
+import { reloadConfig } from "../../config.js";
 import type { PatchWardenConfig } from "../../config.js";
 
 function makeConfig(workspaceRoot: string): PatchWardenConfig {
@@ -199,30 +200,87 @@ describe("guardDirectPatchSize", () => {
 
   beforeEach(() => {
     tempDir = mkdtempSync(join(tmpdir(), "pw-patchsize-"));
-    process.env.PATCHWARDEN_CONFIG = "";
+    // Write a real config file so getConfig() picks it up
+    const configPath = join(tempDir, "patchwarden.config.json");
+    writeFileSync(configPath, JSON.stringify({
+      workspaceRoot: tempDir,
+      agents: { codex: { command: "codex", args: ["exec", "{prompt}"] } },
+      allowedTestCommands: ["npm test"],
+      directMaxPatchBytes: 1000,
+      directMaxFileBytes: 5000,
+    }), "utf-8");
+    process.env.PATCHWARDEN_CONFIG = configPath;
+    reloadConfig();
   });
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
     delete process.env.PATCHWARDEN_CONFIG;
+    reloadConfig();
   });
 
   it("allows patches within size limit", () => {
-    // We can't easily call this without a config, so just test the logic
-    // guardDirectPatchSize calls getConfig() internally
-    // We'll test it indirectly by checking it doesn't throw for small sizes
-    // when config is loaded with defaults
-    // Skip if no config available
+    assert.doesNotThrow(() => guardDirectPatchSize(500));
+    assert.doesNotThrow(() => guardDirectPatchSize(1000));
   });
 
   it("rejects patches exceeding size limit", () => {
-    // This test would need config setup; skip for now
+    assert.throws(
+      () => guardDirectPatchSize(1001),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "patch_too_large"
+    );
+    assert.throws(
+      () => guardDirectPatchSize(999999),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "patch_too_large"
+    );
+  });
+
+  it("allows zero-size patch", () => {
+    assert.doesNotThrow(() => guardDirectPatchSize(0));
   });
 });
 
 describe("guardDirectFileSize", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "pw-filesize-"));
+    const configPath = join(tempDir, "patchwarden.config.json");
+    writeFileSync(configPath, JSON.stringify({
+      workspaceRoot: tempDir,
+      agents: { codex: { command: "codex", args: ["exec", "{prompt}"] } },
+      allowedTestCommands: ["npm test"],
+      directMaxPatchBytes: 1000,
+      directMaxFileBytes: 5000,
+    }), "utf-8");
+    process.env.PATCHWARDEN_CONFIG = configPath;
+    reloadConfig();
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    delete process.env.PATCHWARDEN_CONFIG;
+    reloadConfig();
+  });
+
   it("allows files within size limit", () => {
-    // Similar to above, needs config
+    assert.doesNotThrow(() => guardDirectFileSize(100));
+    assert.doesNotThrow(() => guardDirectFileSize(5000));
+  });
+
+  it("rejects files exceeding size limit", () => {
+    assert.throws(
+      () => guardDirectFileSize(5001),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "file_too_large"
+    );
+    assert.throws(
+      () => guardDirectFileSize(9999999),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "file_too_large"
+    );
+  });
+
+  it("allows zero-size file", () => {
+    assert.doesNotThrow(() => guardDirectFileSize(0));
   });
 });
 
@@ -294,4 +352,116 @@ describe("isBinaryFile", () => {
   it("returns false for non-existent files without binary extension", () => {
     assert.equal(isBinaryFile(join(tempDir, "nonexistent.txt")), false);
   });
+
+  // ── Adversarial: null byte beyond 8KB read window ──
+  it("detects null byte at position 8200 (beyond old 8KB window)", () => {
+    // Previously isBinaryFile only read the first 8192 bytes, so a null byte
+    // at position 8200 would bypass detection. Now we scan up to 1 MB.
+    const stealthBinary = join(tempDir, "stealth.txt");
+    const buffer = Buffer.alloc(8200, 0x41); // 8200 bytes of 'A'
+    buffer[8199] = 0; // null byte just beyond the old 8KB read window
+    writeFileSync(stealthBinary, buffer);
+    assert.equal(isBinaryFile(stealthBinary), true);
+  });
+
+  it("detects null byte at exactly position 8192 (first byte beyond old window)", () => {
+    const stealthBinary = join(tempDir, "boundary-plus.txt");
+    const buffer = Buffer.alloc(8193, 0x41);
+    buffer[8192] = 0; // first byte beyond the old 8KB read window
+    writeFileSync(stealthBinary, buffer);
+    assert.equal(isBinaryFile(stealthBinary), true);
+  });
+
+  it("detects null byte at 100KB offset", () => {
+    const deepBinary = join(tempDir, "deep.txt");
+    const buffer = Buffer.alloc(102400, 0x41);
+    buffer[102399] = 0;
+    writeFileSync(deepBinary, buffer);
+    assert.equal(isBinaryFile(deepBinary), true);
+  });
+
+  it("detects null byte at 1MB offset (scan limit boundary)", () => {
+    const limitBinary = join(tempDir, "limit.txt");
+    const buffer = Buffer.alloc(1_048_576, 0x41);
+    buffer[1_048_575] = 0;
+    writeFileSync(limitBinary, buffer);
+    assert.equal(isBinaryFile(limitBinary), true);
+  });
+
+  it("does not scan beyond 1MB limit", () => {
+    // A null byte just past the 1MB scan limit should NOT be detected.
+    // This documents the remaining scan boundary.
+    const overLimit = join(tempDir, "over-limit.txt");
+    const buffer = Buffer.alloc(1_048_577, 0x41);
+    buffer[1_048_576] = 0; // first byte beyond scan limit
+    writeFileSync(overLimit, buffer);
+    assert.equal(isBinaryFile(overLimit), false);
+  });
+});
+
+// ── Adversarial: Windows backslash prefix bypass attempts ──
+
+describe("guardDirectWritePath adversarial separator tests", () => {
+  let tempDir: string;
+  let repoPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "pw-directsep-"));
+    repoPath = join(tempDir, "my-repo");
+    mkdirSync(repoPath, { recursive: true });
+    mkdirSync(join(repoPath, "src"), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("blocks node_modules with backslash prefix", () => {
+    assert.throws(
+      () => guardDirectWritePath("node_modules\\evil\\index.js", repoPath, tempDir),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "blocked_artifact_path"
+    );
+  });
+
+  it("blocks dist with backslash prefix", () => {
+    assert.throws(
+      () => guardDirectWritePath("dist\\main.js", repoPath, tempDir),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "blocked_artifact_path"
+    );
+  });
+
+  it("blocks release with backslash prefix", () => {
+    assert.throws(
+      () => guardDirectWritePath("release\\app.exe", repoPath, tempDir),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "blocked_artifact_path"
+    );
+  });
+
+  it("blocks nested node_modules with mixed separators", () => {
+    assert.throws(
+      () => guardDirectWritePath("src\\node_modules/evil\\index.js", repoPath, tempDir),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "blocked_artifact_path"
+    );
+  });
+
+  it("blocks .patchwarden with backslash prefix", () => {
+    assert.throws(
+      () => guardDirectWritePath(".patchwarden\\tasks\\evil.json", repoPath, tempDir),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "internal_patchwarden_path_blocked"
+    );
+  });
+
+  it("blocks .env with backslash prefix", () => {
+    assert.throws(
+      () => guardDirectWritePath("path\\to\\.env", repoPath, tempDir),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "sensitive_path_blocked"
+    );
+  });
+
+  it("blocks config.json with backslash path", () => {
+    assert.throws(
+      () => guardDirectWritePath("subdir\\config.json", repoPath, tempDir),
+      (err: unknown) => err instanceof PatchWardenError && err.reason === "sensitive_path_blocked"
+    );
+  });
 });

package/src/test/unit/evidence-pack.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import { strict as assert } from "node:assert";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { reloadConfig } from "../../config.js";
+import { recommendAgentForTask } from "../../tools/recommendAgentForTask.js";
+import { exportTaskEvidencePack, listEvidencePacks, readEvidencePack } from "../../tools/evidencePack.js";
+import { writeTaskLineage } from "../../tools/taskLineage.js";
+
+let tempDir: string;
+let prevConfigEnv: string | undefined;
+
+function writeConfig() {
+  const configPath = join(tempDir, "patchwarden.config.json");
+  writeFileSync(
+    configPath,
+    JSON.stringify({
+      workspaceRoot: tempDir,
+      tasksDir: ".patchwarden/tasks",
+      plansDir: ".patchwarden/plans",
+      assessmentsDir: ".patchwarden/assessments",
+      agents: {
+        codex: { command: "codex", args: [] },
+        opencode: { command: "opencode", args: [] },
+      },
+      allowedTestCommands: ["npm test", "npm run build"],
+      defaultTaskTimeoutSeconds: 30,
+      maxTaskTimeoutSeconds: 120,
+    }),
+    "utf-8"
+  );
+  prevConfigEnv = process.env.PATCHWARDEN_CONFIG;
+  process.env.PATCHWARDEN_CONFIG = configPath;
+  reloadConfig();
+}
+
+describe("v1.5 evidence packs and agent recommendations", () => {
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "pw-evidence-"));
+    writeConfig();
+  });
+
+  afterEach(() => {
+    if (prevConfigEnv === undefined) delete process.env.PATCHWARDEN_CONFIG;
+    else process.env.PATCHWARDEN_CONFIG = prevConfigEnv;
+    reloadConfig();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("recommends an agent without creating task evidence", () => {
+    const recommendation = recommendAgentForTask({
+      repo_path: ".",
+      goal: "Refactor two modules safely",
+      scope_files: ["src/a.ts", "src/b.ts"],
+    });
+
+    assert.equal(recommendation.bounded, true);
+    assert.ok(["codex", "opencode"].includes(recommendation.recommended_agent));
+    assert.ok(Array.isArray(recommendation.suggested_verify_commands));
+    const payload = JSON.stringify(recommendation);
+    assert.ok(!payload.includes("stdout"));
+    assert.ok(!payload.includes("stderr"));
+    assert.ok(!payload.includes("diff"));
+  });
+
+  it("exports bounded BOM-free evidence pack from lineage", () => {
+    writeTaskLineage({
+      lineage_id: "lineage_v15_pack",
+      goal: "Export evidence",
+      repo_path: ".",
+      created_at: "2026-07-05T12:00:00.000Z",
+      updated_at: "2026-07-05T12:01:00.000Z",
+      final_status: "accepted",
+      stop_reason: "success",
+      next_action: "accept",
+      main_task: "task-main",
+      fix_tasks: [],
+      cleanup_tasks: [],
+      direct_sessions: [{
+        session_id: "direct-one",
+        status: "passed",
+        command_count: 1,
+        passed_commands: 1,
+        failed_commands: 0,
+        timed_out_commands: 0,
+        audit_decision: "pass",
+        changed_files_total: 0,
+        next_action: "accept",
+      }],
+      rounds: [{
+        iteration: 1,
+        task_id: "task-main",
+        role: "main",
+        status: "done_by_agent",
+        terminal: true,
+        verification_status: "passed",
+        audit_verdict: "pass",
+        fail_checks: [],
+        warn_checks: [],
+        next_action: "accept",
+      }],
+      warnings: [],
+      errors: [],
+      worktree: {
+        isolation_mode: "worktree",
+        worktree_id: "wt-one",
+        worktree_path: join(tempDir, "_workspacetrees", "wt-one"),
+        branch: "pw-test",
+        cleanup: "keep",
+        status: "active",
+        next_action: "merge or discard explicitly",
+      },
+      agent_routing: {
+        requested_agent: "auto",
+        selected_agent: "codex",
+        reason: "test route",
+        fallback: false,
+      },
+    });
+
+    const pack = exportTaskEvidencePack({ lineage_id: "lineage_v15_pack" });
+    assert.equal(pack.bounded, true);
+    assert.equal(pack.lineage.worktree.worktree_id, "wt-one");
+    assert.equal(pack.lineage.agent_routing?.selected_agent, "codex");
+    const raw = readFileSync(pack.files.json);
+    assert.notEqual(raw[0], 0xef);
+    JSON.parse(raw.toString("utf-8"));
+
+    const payload = JSON.stringify(pack);
+    assert.ok(!payload.includes("stdout_tail"));
+    assert.ok(!payload.includes("stderr_tail"));
+    assert.ok(!payload.includes("diff.patch"));
+    assert.ok(!payload.includes("verification.log"));
+
+    const readBack = readEvidencePack("lineage_v15_pack");
+    assert.equal(readBack?.lineage_id, "lineage_v15_pack");
+    const listed = listEvidencePacks();
+    assert.equal(listed.total, 1);
+    assert.equal(listed.evidence_packs[0].lineage_id, "lineage_v15_pack");
+
+    // v2: all six structured artifact files should exist.
+    for (const key of ["risk", "verify", "diffstat", "lineage", "attestation", "redactions"] as const) {
+      assert.ok(existsSync(pack.files[key]), `${key} file should exist`);
+    }
+
+    // v2: attestation.json must carry the required provenance fields.
+    const attestation = JSON.parse(readFileSync(pack.files.attestation, "utf-8"));
+    assert.ok(attestation.patchwarden_version, "attestation should have patchwarden_version");
+    assert.ok(attestation.package_version, "attestation should have package_version");
+    assert.ok(attestation.commit, "attestation should have commit");
+    assert.ok(attestation.node_version, "attestation should have node_version");
+    assert.ok(attestation.os, "attestation should have os");
+    assert.ok(attestation.schema_epoch, "attestation should have schema_epoch");
+
+    // v2: redactions.json must have the audit structure even when empty.
+    const redactions = JSON.parse(readFileSync(pack.files.redactions, "utf-8"));
+    assert.ok(Array.isArray(redactions.redactions), "redactions should be an array");
+    assert.equal(typeof redactions.total_redacted, "number", "total_redacted should be a number");
+  });
+
+  it("exports v2 structured artifacts and redacts secrets in diffstat", () => {
+    const secretValue = "ghp_1234567890abcdefghijklmnop";
+    // Create a task directory with file-stats.json containing a secret in a file path.
+    const taskDir = join(tempDir, ".patchwarden", "tasks", "task-v2-secret");
+    mkdirSync(taskDir, { recursive: true });
+    writeFileSync(join(taskDir, "file-stats.json"), JSON.stringify({
+      task_id: "task-v2-secret",
+      additions: 5,
+      deletions: 2,
+      files: [{
+        path: `secrets/${secretValue}.json`,
+        status: "modified",
+        additions: 5,
+        deletions: 2,
+      }],
+    }), "utf-8");
+
+    writeTaskLineage({
+      lineage_id: "lineage_v2_secret",
+      goal: "Export v2 evidence with diffstat",
+      repo_path: ".",
+      created_at: "2026-07-09T12:00:00.000Z",
+      updated_at: "2026-07-09T12:01:00.000Z",
+      final_status: "accepted",
+      stop_reason: "success",
+      next_action: "accept",
+      main_task: "task-v2-secret",
+      fix_tasks: [],
+      cleanup_tasks: [],
+      direct_sessions: [],
+      rounds: [{
+        iteration: 1,
+        task_id: "task-v2-secret",
+        role: "main",
+        status: "done_by_agent",
+        terminal: true,
+        verification_status: "passed",
+        audit_verdict: "pass",
+        fail_checks: [],
+        warn_checks: ["minor scope drift"],
+        next_action: "accept",
+      }],
+      warnings: [],
+      errors: [],
+      worktree: {
+        isolation_mode: "current_repo",
+        cleanup: "keep",
+        status: "not_used",
+        next_action: "none",
+      },
+    });
+
+    const pack = exportTaskEvidencePack({ lineage_id: "lineage_v2_secret" });
+
+    // All six v2 files should exist.
+    for (const key of ["risk", "verify", "diffstat", "lineage", "attestation", "redactions"] as const) {
+      assert.ok(existsSync(pack.files[key]), `${key} file should exist`);
+    }
+
+    // The original secret must not appear in any v2 file.
+    for (const key of ["risk", "verify", "diffstat", "lineage", "attestation", "redactions"] as const) {
+      const content = readFileSync(pack.files[key], "utf-8");
+      assert.ok(!content.includes(secretValue), `${key} should not contain the original secret value`);
+    }
+
+    // redactions.json should have detected the secret via diffstat aggregation.
+    const redactions = JSON.parse(readFileSync(pack.files.redactions, "utf-8"));
+    assert.ok(redactions.total_redacted > 0, "redactions.json should have detected the secret");
+    assert.ok(
+      !JSON.stringify(redactions).includes(secretValue),
+      "redactions.json should not contain the original secret value"
+    );
+
+    // risk.json should carry the warn_check as a medium-severity risk.
+    const risk = JSON.parse(readFileSync(pack.files.risk, "utf-8"));
+    assert.ok(risk.count > 0, "risk.json should have at least one risk item");
+    assert.equal(risk.by_severity.medium, 1, "should have one medium-severity risk");
+
+    // verify.json should carry the round verification record.
+    const verify = JSON.parse(readFileSync(pack.files.verify, "utf-8"));
+    assert.ok(verify.count > 0, "verify.json should have at least one record");
+    assert.equal(verify.records[0].verification_status, "passed");
+
+    // lineage.json should carry the bounded summary.
+    const lineageSummary = JSON.parse(readFileSync(pack.files.lineage, "utf-8"));
+    assert.equal(lineageSummary.lineage_id, "lineage_v2_secret");
+    assert.equal(lineageSummary.iterations_count, 1);
+    assert.equal(lineageSummary.final_status, "accepted");
+  });
+});

package/src/test/unit/get-task-status.test.ts

@@ -0,0 +1,203 @@
+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 } from "node:path";
+import { tmpdir } from "node:os";
+import { reloadConfig } from "../../config.js";
+import { getTaskStatus } from "../../tools/getTaskStatus.js";
+
+let tempDir: string;
+let tasksDir: string;
+let prevConfigEnv: string | undefined;
+
+function writeConfig(): void {
+  const configPath = join(tempDir, "patchwarden.config.json");
+  writeFileSync(
+    configPath,
+    JSON.stringify({
+      workspaceRoot: tempDir,
+      tasksDir: ".patchwarden/tasks",
+      plansDir: ".patchwarden/plans",
+      assessmentsDir: ".patchwarden/assessments",
+      directSessionsDir: ".patchwarden/direct-sessions",
+      agents: { codex: { command: "codex", args: ["exec", "{prompt}"] } },
+      allowedTestCommands: ["npm test"],
+    }),
+    "utf-8"
+  );
+  prevConfigEnv = process.env.PATCHWARDEN_CONFIG;
+  process.env.PATCHWARDEN_CONFIG = configPath;
+  reloadConfig();
+}
+
+function writeTaskStatus(taskId: string, status: Record<string, unknown>): string {
+  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>): void {
+  writeFileSync(join(taskDir, "runtime.json"), JSON.stringify(runtime, null, 2), "utf-8");
+}
+
+describe("getTaskStatus", () => {
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "pw-getstatus-"));
+    tasksDir = join(tempDir, ".patchwarden", "tasks");
+    mkdirSync(tasksDir, { recursive: true });
+    writeConfig();
+  });
+
+  afterEach(() => {
+    if (prevConfigEnv === undefined) delete process.env.PATCHWARDEN_CONFIG;
+    else process.env.PATCHWARDEN_CONFIG = prevConfigEnv;
+    reloadConfig();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  // ── pending ──
+  it("reads pending status task", () => {
+    writeTaskStatus("task-pending-001", {
+      task_id: "task-pending-001",
+      plan_id: "plan-001",
+      agent: "codex",
+      workspace_root: tempDir,
+      repo_path: "repo",
+      resolved_repo_path: join(tempDir, "repo"),
+      status: "pending",
+      phase: "queued",
+      created_at: "2026-07-12T10:00:00Z",
+      updated_at: "2026-07-12T10:00:01Z",
+      timeout_seconds: 900,
+      error: null,
+    });
+
+    const result = getTaskStatus("task-pending-001");
+
+    assert.equal(result.task_id, "task-pending-001");
+    assert.equal(result.status, "pending");
+    assert.equal(result.phase, "queued");
+    assert.equal(result.agent, "codex");
+    assert.equal(result.plan_id, "plan-001");
+    assert.equal(result.error, null);
+    // No watcher heartbeat → watcher missing → pending task is execution_blocked
+    assert.equal(result.execution_blocked, true);
+    assert.equal(result.watcher_status, "missing");
+    assert.equal(result.pending_reason, "queued_but_watcher_missing");
+  });
+
+  // ── running ──
+  it("reads running status task and merges runtime.json", () => {
+    const taskDir = writeTaskStatus("task-running-001", {
+      task_id: "task-running-001",
+      plan_id: "plan-001",
+      agent: "codex",
+      workspace_root: tempDir,
+      repo_path: "repo",
+      resolved_repo_path: join(tempDir, "repo"),
+      status: "running",
+      phase: "executing_agent",
+      created_at: "2026-07-12T10:00:00Z",
+      started_at: "2026-07-12T10:00:05Z",
+      updated_at: "2026-07-12T10:00:10Z",
+      timeout_seconds: 900,
+      error: null,
+    });
+    writeTaskRuntime(taskDir, {
+      phase: "executing_agent",
+      last_heartbeat_at: "2026-07-12T10:00:12Z",
+      current_command: "codex exec --prompt",
+    });
+
+    const result = getTaskStatus("task-running-001");
+
+    assert.equal(result.status, "running");
+    assert.equal(result.phase, "executing_agent");
+    assert.equal(result.current_command, "codex exec --prompt");
+    assert.equal(result.last_heartbeat_at, "2026-07-12T10:00:12Z");
+    assert.equal(result.started_at, "2026-07-12T10:00:05Z");
+    // running (not pending) → execution_blocked is false
+    assert.equal(result.execution_blocked, false);
+    assert.equal(result.pending_reason, "agent_running");
+  });
+
+  // ── done ──
+  it("reads done status task", () => {
+    writeTaskStatus("task-done-001", {
+      task_id: "task-done-001",
+      plan_id: "plan-001",
+      agent: "codex",
+      workspace_root: tempDir,
+      repo_path: "repo",
+      resolved_repo_path: join(tempDir, "repo"),
+      status: "done",
+      phase: "completed",
+      created_at: "2026-07-12T10:00:00Z",
+      started_at: "2026-07-12T10:00:05Z",
+      finished_at: "2026-07-12T10:05:00Z",
+      updated_at: "2026-07-12T10:05:00Z",
+      timeout_seconds: 900,
+      verify_status: "passed",
+      error: null,
+    });
+
+    const result = getTaskStatus("task-done-001");
+
+    assert.equal(result.status, "done");
+    assert.equal(result.phase, "completed");
+    assert.equal(result.finished_at, "2026-07-12T10:05:00Z");
+    assert.equal(result.verify_status, "passed");
+    assert.equal(result.execution_blocked, false);
+    assert.equal(result.pending_reason, null);
+  });
+
+  // ── failed ──
+  it("reads failed status task", () => {
+    writeTaskStatus("task-failed-001", {
+      task_id: "task-failed-001",
+      plan_id: "plan-001",
+      agent: "codex",
+      workspace_root: tempDir,
+      repo_path: "repo",
+      resolved_repo_path: join(tempDir, "repo"),
+      status: "failed",
+      phase: "failed",
+      created_at: "2026-07-12T10:00:00Z",
+      started_at: "2026-07-12T10:00:05Z",
+      finished_at: "2026-07-12T10:05:00Z",
+      updated_at: "2026-07-12T10:05:00Z",
+      timeout_seconds: 900,
+      error: "Agent exited with code 1",
+    });
+
+    const result = getTaskStatus("task-failed-001");
+
+    assert.equal(result.status, "failed");
+    assert.equal(result.phase, "failed");
+    assert.equal(result.error, "Agent exited with code 1");
+    assert.equal(result.finished_at, "2026-07-12T10:05:00Z");
+    assert.equal(result.execution_blocked, false);
+  });
+
+  // ── status.json missing ──
+  it("throws when status.json is missing (task not found)", () => {
+    // guardReadPath throws "File not found" before the existsSync "Task not found" check
+    assert.throws(
+      () => getTaskStatus("non-existent-task"),
+      /(File not found|Task not found)/
+    );
+  });
+
+  // ── status.json corrupt ──
+  it("throws when status.json is corrupt", () => {
+    const taskDir = join(tasksDir, "task-corrupt-001");
+    mkdirSync(taskDir, { recursive: true });
+    writeFileSync(join(taskDir, "status.json"), "{not valid json", "utf-8");
+
+    assert.throws(
+      () => getTaskStatus("task-corrupt-001"),
+      SyntaxError
+    );
+  });
+});