@tea-agent/loop-agent 0.16.24 → 0.16.26

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ### 改进
 
+- Observe 节点检查器“规范证据”页签新增安全文件预览：已绑定任务源和已读取规范文件条目现以可聚焦按钮呈现，点击后在检查器内下钻查看内容（不新增弹窗），提供“返回规范证据”按钮并恢复触发行焦点。新增只读接口 `GET /api/dag-runs/:runId/nodes/:nodeId/spec-evidence/file?source=binding|read&path=...`，服务端重新校验证据成员身份（binding 必须在 `sourceBinding.sources`，read 必须有成功配对 read），拒 `..`/绝对/目录/二进制/仓库外符号链接；正文上限 64KB 并返回截断标志，统一走 Observe 脱敏规则；binding 返回 `sha256`/`currentSha256`/`hashMatch`，read 返回 session event 中实际读取正文与 `readAt`（不以当前工作区文件替代）。
+
+- 通用 standard/reviewed/supervised 实现 DAG 现在会在目标仓库存在 `AGENTS.md` 时，按本次 writer 的实际变更解析适用的根级/嵌套指令和仓库内代码规范索引：standard 复用 `verify-pi` 与条件 shell gate，reviewed/supervised 复用现有 `review-pi`/review gate，不新增模型节点；无 `AGENTS.md` 或无适用规范时保持原行为，审查节点只读且不会直接改代码。专用测试、前端和知识类 DAG 不受影响。
 - GitHub Actions CI 降低私有仓分钟消耗：合并为单 job（避免两次 `npm ci`）、同分支/`PR` concurrency 取消旧 run、Draft PR 跳过完整 CI，且仅忽略 `docs/reports/**`、`docs/progress/**`、`docs/design/archive/**`、`docs/exec-plans/completed/**` 等纯运营文档路径；治理文档与代码门禁仍全量跑。
 - 明确 **Compatibility / Operator Assist**：openCode 等主会话只编排已发布 `loop-agent` / `agent-worker` CLI 与只读诊断，不得绕过 CLI 直接改业务实现，失败只走 doctor / reconcile / human gate / CLI 重跑。`loop-agent init` 写入的 `AGENTS.md` managed block、包内 skills 与 website 快速开始/治理说明已对齐；架构决策见 `docs/decisions/0005-governed-operator-surface.md`（accepted）。已有目标项目用 `loop-agent init check-update` / `init update --apply-safe` 或 `init reconcile` 刷新 managed block。
 - 前端测试 DAG 收紧体验：execution preflight 仅硬校验绝对非生产 `baseUrl`；用例 map 缩短为优先用 `playwright-cli` 执行；复盘合并执行证据审查且不依赖 outcome=pass，失败也能出报告。
@@ -12,6 +15,10 @@
 - Backend Test Analysis、Case Manifest、Semantic Review 与 Classification 的严格 JSON 契约进一步对齐，生成节点明确字段白名单、`sourceBinding` 与 evidence gap 约束，避免模型自定义字段导致确定性门禁失败。
 - 新增升级后 init surface notifier：普通安全仓库命令结束后，当目标项目存在有效 `.harness/init-surface.json` 且 `controllerVersion` 与当前包版本不同时自动检测。surface 缺失/损坏、源仓库、未初始化目录与版本一致时直接跳过；`checkInitUpdate().ok` 时仅在无活跃运行时静默刷新 state；非 TTY 只向 stderr 输出 `loop-agent init reconcile --repo-root ...` 提示且不写入目标；TTY 且无 human decisions、无活跃 DAG/Worker 时可经明确 `y/yes` 同意后应用 deterministic safe actions；只有 model merge 时直接输出有边界指引，不询问“应用 0 个动作”。notifier 遵循全局 `--repo-root`、不写 stdout、不改变原命令退出码，CI、禁用环境变量、help/version、`--json`/`--markdown`、`init`、`run-dag`、`dag`、`loop`、`delegate`、`pi-prompt`、`cursor-prompt` 均跳过。
 - 新增统一命令 `loop-agent init reconcile --repo-root <target>`：surface 缺失返回 `needs-baseline` 且零写入，存在 human decisions 返回 `needs-human-decision` 且零写入，活跃 DAG/Worker 或 Worker 状态无法确认时返回 `blocked-active-runtime` 且零写入；其余情况复用现有 `applyInitUpdate({ applySafe: true })` 并复查返回 `clean`/`needs-model-merge`/`needs-safe-update`，支持 `--json`/`--markdown`。
+- 测试报告新增 L-5 指标消费与 Python coverage.py JSON、Java JaCoCo XML 的统一 Code Coverage v1 报告入口，覆盖通过率、AC/自动化覆盖率、稳定性、失败原因、缺陷、风险和回归建议；缺失覆盖率证据保持 `unavailable`，不改变 backend-test outcome gate。
+- 现有 backend-test DAG 在 retrospective 之后新增独立的 `l5-metrics-pi` 指标节点；它基于前序测试报告和 run-owned 证据输出 `L-5 ready/not-ready`，不创建独立 L-5 DAG，也不改变 Result v1 outcome gate。
+- 后端测试 DAG 从 38 个收敛为 24 个真实顶层节点；使用 fail-closed `runIf` 和复合 Shell capability 减少调度，同时保留双合同、Manifest、语义评审、JUnit、Result、分类、修复安全、追踪和最终 outcome 证据。三条可选修订/修复分支仍各最多执行一次。
+- Backend Test Analysis、Case Manifest、Semantic Review 与 Classification 的严格 JSON 契约进一步对齐，生成和修订节点明确字段白名单、`sourceBinding` 与 evidence gap 约束，避免模型自定义字段导致确定性门禁失败。
 
 ### 修复
 
@@ -35,6 +42,19 @@
 - Pi SDK 执行长推理或大段结构化输出时不再把高频流式增量事件无界累积到内存；同一响应在多个生命周期事件中重复出现的 Token 用量只统计一次，避免 `Invalid string length` 和成本数据虚高。
 - 后端测试复合执行节点继续保持 clean environment、失败分类和 fail-closed outcome，并为唯一 JUnit/initial Result、canonical Result、traceability 与 Observe 投影保留结构化运行证据。
 
+## [0.16.26] - 2026-07-22
+
+### 修复
+
+- Git checkpoint 对 `allowed_paths` 内的 **gitignored 证据文件**（如 dogfood `reports/welcome/final/*.json`）执行 `git add -f` 纳入 checkpoint；敏感路径与范围外 ignored 文件仍 fail-closed。修复 FINAL-VERIFY DAG/report 已绿却因 ignored evidence 记 `record-error`、Task Pool 卡 Running 的 Delivery 阻断。
+
+## [0.16.25] - 2026-07-22
+
+### 修复
+
+- Backend-test pytest preflight 与执行体改为 `&&` fail-closed：preflight 失败不再因 `;` 继续跑 pytest（I27 曾出现 preflight 报 `WELCOME_BASE_URL`/testRoot 错配仍执行用例）。
+- 本地 `npm start` / `node server.js` 类 `managed-command` 在 materialize 时降级为 `in-process`，清空 requiredEnv、seed server fixture，并把 scout `testRoot` 收敛到冻结根 `testcase/`；generate-pytest 提示要求 fixture 内启动服务，不再依赖 clean-env 注入 base URL。
+
 ## [0.16.24] - 2026-07-21
 
 ### 改进

package/dist/cli/command-definitions.js

@@ -3,6 +3,7 @@ import { runDocsArchive } from "../commands/docs-archive.js";
 import { runDocsAudit } from "../commands/docs-audit.js";
 import { runEval } from "../commands/eval.js";
 import { runCoverageAudit } from "../commands/coverage-audit.js";
+import { runCoverageReport } from "../commands/coverage-report.js";
 import { runExamples } from "../commands/examples.js";
 import { runCloseout } from "../commands/closeout.js";
 import { runHandoffCheck } from "../commands/handoff-check.js";
@@ -101,6 +102,7 @@ const PLAN_SUBCOMMANDS = ["list", "create", "complete", "check"];
 const SPINE_SUBCOMMANDS = ["audit"];
 const HANDOFF_SUBCOMMANDS = ["check", "coverage"];
 const HANDOFF_USAGE = "handoff <check|coverage> [taskId]";
+const COVERAGE_SUBCOMMANDS = ["report"];
 const REFERENCE_SUBCOMMANDS = ["index"];
 const STUDY_SUBCOMMANDS = ["init"];
 const WORKTREE_SUBCOMMANDS = ["create", "list", "remove"];
@@ -378,6 +380,17 @@ export const COMMAND_DEFINITIONS = [
             throw new Error(`usage: ${HANDOFF_USAGE}`);
         },
     },
+    {
+        name: "coverage",
+        adapter: "required",
+        tier: "operator",
+        intent: "Normalize Python coverage.py JSON or Java JaCoCo XML for test reports.",
+        usage: "coverage report --language python|java --input <path> [options]",
+        subcommands: [...COVERAGE_SUBCOMMANDS],
+        handler: async ({ repoRoot, subcommand, rest }) => {
+            await runCoverageReport(repoRoot, [subcommand, ...rest].filter(Boolean));
+        },
+    },
     {
         name: "goal",
         adapter: "required",

package/dist/cli/program.js

@@ -5,6 +5,7 @@ import { readPackageVersion } from "../shared/package-metadata.js";
 import { resolveAdapter } from "../adapters/index.js";
 import { runCloseout } from "../commands/closeout.js";
 import { runCoverageAudit } from "../commands/coverage-audit.js";
+import { runCoverageReport } from "../commands/coverage-report.js";
 import { parseCursorPromptArgs, printCursorPromptUsage, runCursorPrompt, } from "../commands/cursor-prompt.js";
 import { runDagApprove } from "../commands/dag-approve.js";
 import { runDagFinalVerification } from "../commands/dag-final-verification.js";
@@ -205,6 +206,9 @@ async function runCommanderAction(ctx, command, subcommand, rest) {
                 return;
             }
             throw new Error("usage: handoff <check|coverage> [taskId]");
+        case "coverage":
+            await runCoverageReport(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
         case "goal":
             await runGoal(ctx.repoRoot, subcommand, rest);
             return;

package/dist/commands/coverage-report.js

@@ -0,0 +1,50 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { formatCoverageMarkdown, readCoverageArtifact } from "../workflows/dag/backend-test-coverage-contract.js";
+function value(args, flag) {
+    const index = args.findIndex((arg) => arg === flag || arg.startsWith(`${flag}=`));
+    if (index < 0)
+        return undefined;
+    const token = args[index];
+    return token.startsWith(`${flag}=`) ? token.slice(flag.length + 1) : args[index + 1];
+}
+function values(args, flag) {
+    return args.flatMap((arg, index) => {
+        if (arg === flag)
+            return args[index + 1] ? [args[index + 1]] : [];
+        return arg.startsWith(`${flag}=`) ? [arg.slice(flag.length + 1)] : [];
+    });
+}
+export async function runCoverageReport(repoRoot, args) {
+    if (args[0] !== "report" || args.includes("--help")) {
+        console.log("usage: coverage report --language python|java --input <coverage.json|jacoco.xml> [--output <path>] [--json|--markdown] --requirement-id <AC-id> --source-scope <path[,path]> [--commit <sha>] [--expected-sha256 <sha256>]");
+        return;
+    }
+    const input = value(args, "--input");
+    const language = value(args, "--language");
+    if (!input || (language !== "python" && language !== "java"))
+        throw new Error("coverage report requires --language python|java and --input");
+    const expectedSha = value(args, "--expected-sha256");
+    const sourcePaths = (value(args, "--source-scope") ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+    const contract = await readCoverageArtifact(path.resolve(repoRoot, input), {
+        sourceScope: { requirementIds: values(args, "--requirement-id"), paths: sourcePaths },
+        commitSha: value(args, "--commit") ?? null,
+        toolVersion: value(args, "--tool-version") ?? null,
+        artifactPath: input,
+    });
+    if ((language === "python" && contract.language !== "python") || (language === "java" && contract.language !== "java"))
+        throw new Error("coverage artifact format does not match --language");
+    if (expectedSha && expectedSha !== contract.artifact.sha256)
+        throw new Error(`artifact SHA-256 mismatch: expected ${expectedSha}, got ${contract.artifact.sha256}`);
+    const markdown = args.includes("--markdown");
+    const output = value(args, "--output");
+    const rendered = markdown ? formatCoverageMarkdown(contract) : `${JSON.stringify(contract, null, 2)}\n`;
+    if (output) {
+        const outputPath = path.resolve(repoRoot, output);
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, rendered, "utf8");
+    }
+    else {
+        process.stdout.write(rendered);
+    }
+}

package/dist/executors/dag-pi-executor.js

@@ -1,8 +1,9 @@
 import path from "node:path";
-import { writeTextArtifactFile } from "../infrastructure/harness/artifact-store.js";
+import { createHash } from "node:crypto";
+import { writeDagNodeJsonArtifact, writeTextArtifactFile, } from "../infrastructure/harness/artifact-store.js";
 import { executePiStep, } from "./pi-executor.js";
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
-import { readGitStatusPorcelain, runPostRunWriteGuard, } from "./shell-write-guard.js";
+import { pathsChangedDuringRun, readGitStatusPorcelain, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 export const DAG_PI_READONLY_TOOLS = ["read", "grep", "find", "ls"];
 export const DAG_PI_WRITE_TOOLS = [
     "read",
@@ -240,12 +241,15 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
         };
     }
     let beforeStatus;
+    let beforePathFingerprints;
     if (isWriteTask) {
         try {
             beforeStatus = await readGitStatusPorcelain(input.cwd);
+            beforePathFingerprints = await snapshotGitStatusPathFingerprints(input.cwd, snapshotGitStatusPorcelain(beforeStatus));
         }
         catch {
             beforeStatus = undefined;
+            beforePathFingerprints = undefined;
         }
     }
     const result = await piStepFn({
@@ -278,15 +282,19 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
     }
     let writeGuardOk = true;
     let writeGuardViolations = [];
+    let changeManifestAfterStatus;
+    let changeManifestChangedFiles;
     if (beforeStatus !== undefined) {
         try {
-            const guard = await runPostRunWriteGuard({
-                rootCwd: input.cwd,
-                beforeStatus,
-                writePolicy: input.task.writePolicy,
-                writeSet: input.task.writeSet,
-                allowedPaths: input.task.allowedPaths,
-                forbiddenPaths: input.task.forbiddenPaths,
+            const afterStatus = await readGitStatusPorcelain(input.cwd);
+            const afterSnapshot = snapshotGitStatusPorcelain(afterStatus);
+            const afterPathFingerprints = await snapshotGitStatusPathFingerprints(input.cwd, afterSnapshot);
+            const changedFiles = pathsChangedDuringRun(snapshotGitStatusPorcelain(beforeStatus), afterSnapshot, beforePathFingerprints, afterPathFingerprints);
+            changeManifestAfterStatus = afterStatus;
+            changeManifestChangedFiles = changedFiles;
+            const guard = validateShellWriteGuardFromDiff({
+                changedFiles,
+                task: input.task,
                 concurrentSiblingWriteSets: meta.concurrentSiblingWriteSets,
             });
             writeGuardOk = guard.ok;
@@ -300,6 +308,16 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
         }
     }
     if (writeGuardOk) {
+        if (beforeStatus !== undefined && changeManifestChangedFiles !== undefined) {
+            await persistWriterChangeManifest({
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+                writerNodeId: input.task.id,
+                changedFiles: changeManifestChangedFiles,
+                beforeStatus,
+                afterStatus: changeManifestAfterStatus ?? "",
+            });
+        }
         return mapped;
     }
     const stderrParts = [mapped.stderr];
@@ -369,3 +387,39 @@ function normalizeProtocolLine(line) {
     const emphasized = trimmed.match(/^(\*{1,3})\s*(.*?)\s*\1$/);
     return (emphasized?.[2] ?? trimmed).trim();
 }
+/**
+ * Validate the writer's observed diff against its declared write boundary.
+ * Inlined mirror of runPostRunWriteGuard that reuses the already-computed diff
+ * so the change manifest and the guard share one source of truth.
+ */
+function validateShellWriteGuardFromDiff(input) {
+    return validateShellWriteGuard({
+        changedPaths: input.changedFiles,
+        writePolicy: input.task.writePolicy,
+        writeSet: input.task.writeSet,
+        allowedPaths: input.task.allowedPaths,
+        forbiddenPaths: input.task.forbiddenPaths,
+        concurrentSiblingWriteSets: input.concurrentSiblingWriteSets,
+        allowSiblingWriteSetAttribution: input.task.writePolicy === "exclusive" &&
+            (input.concurrentSiblingWriteSets?.length ?? 0) > 0,
+    });
+}
+/**
+ * Persist the writer's actual changeset as a run-owned artifact so the
+ * project governance context resolver can attribute exactly this run's
+ * writes (not final `git status`, which may include pre-existing changes).
+ */
+async function persistWriterChangeManifest(input) {
+    const manifest = {
+        schemaVersion: 1,
+        writerNodeId: input.writerNodeId,
+        changedFiles: input.changedFiles,
+        beforeStatusSha256: createHash("sha256")
+            .update(input.beforeStatus)
+            .digest("hex"),
+        afterStatusSha256: createHash("sha256")
+            .update(input.afterStatus)
+            .digest("hex"),
+    };
+    await writeDagNodeJsonArtifact(input.runDir, input.nodeId, "change-manifest.json", manifest);
+}

package/dist/executors/shell-executor.js

@@ -19,6 +19,8 @@ import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBack
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
 import { pathsChangedDuringRun, readGitStatusPorcelain, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 import { buildShellProcessEnv } from "./shell-verification.js";
+import { readRunState } from "../workflows/dag/run-store.js";
+import { readProjectGovernanceContext } from "../workflows/dag/project-governance-context.js";
 const DEFAULT_SHELL_TIMEOUT_MS = 300_000;
 const SUMMARY_STDOUT_MAX = 4_000;
 const SUMMARY_STDERR_MAX = 2_000;
@@ -733,6 +735,34 @@ export async function executeDagShellNode(input, meta) {
             };
         }
     }
+    if (shell?.projectGovernanceGate) {
+        const started = Date.now();
+        try {
+            const state = await readRunState(meta.runDir);
+            if (!state.projectGovernanceContextRef) {
+                throw new Error("project governance gate requires projectGovernanceContextRef in run state");
+            }
+            const context = await readProjectGovernanceContext(meta.runDir, state.projectGovernanceContextRef, { expectedRunId: meta.runId });
+            if (!context.applicable) {
+                return {
+                    ok: true,
+                    stdout: "Project governance gate: not applicable for this writer changeset.",
+                    stderr: "",
+                    failureCategory: "success",
+                    durationMs: Date.now() - started,
+                };
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: error instanceof Error ? error.message : String(error),
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
     const commands = shell ? resolveShellCommands(shell) : [];
     if (!shell || commands.length === 0) {
         throw new Error(`shell task ${input.task.id} requires shell.preset, shell.verdictGate, and/or non-empty shell.commands`);

package/dist/executors/shell-write-guard.js

@@ -1,5 +1,16 @@
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readlink } from "node:fs/promises";
+import path from "node:path";
 import { pathMatchesPattern } from "../shared/git-progress.js";
+async function sha256File(filePath) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
 export function snapshotGitStatusPorcelain(porcelain) {
     const snapshot = new Map();
     for (const line of porcelain.split("\n")) {
@@ -14,11 +25,15 @@ export function snapshotGitStatusPorcelain(porcelain) {
     }
     return snapshot;
 }
-export function pathsChangedDuringRun(before, after) {
+export function pathsChangedDuringRun(before, after, beforeFingerprints, afterFingerprints) {
     const changed = new Set();
     for (const [filePath, afterCode] of after) {
         const beforeCode = before.get(filePath);
-        if (beforeCode === undefined || beforeCode !== afterCode) {
+        if (beforeCode === undefined ||
+            beforeCode !== afterCode ||
+            (beforeFingerprints !== undefined &&
+                afterFingerprints !== undefined &&
+                beforeFingerprints.get(filePath) !== afterFingerprints.get(filePath))) {
             changed.add(filePath);
         }
     }
@@ -29,6 +44,53 @@ export function pathsChangedDuringRun(before, after) {
     }
     return Array.from(changed).sort();
 }
+/**
+ * Capture content-aware fingerprints for every path already present in a
+ * porcelain snapshot. Status codes alone cannot detect a writer editing a file
+ * that was `M` or `??` before the node and remains so afterwards.
+ *
+ * Symlinks are hashed by link target without following them, keeping the
+ * snapshot repository-contained. Missing paths and non-files receive stable
+ * sentinels so deletions and type changes remain observable.
+ */
+export async function snapshotGitStatusPathFingerprints(cwd, status) {
+    const root = path.resolve(cwd);
+    const entries = await Promise.all([...status.keys()].map(async (filePath) => {
+        const candidate = path.resolve(root, filePath);
+        const relative = path.relative(root, candidate);
+        if (relative.startsWith("..") ||
+            path.isAbsolute(relative)) {
+            return [filePath, "outside-repository"];
+        }
+        try {
+            const info = await lstat(candidate);
+            if (info.isSymbolicLink()) {
+                const target = await readlink(candidate);
+                return [
+                    filePath,
+                    `symlink:${createHash("sha256").update(target).digest("hex")}`,
+                ];
+            }
+            if (info.isFile()) {
+                return [
+                    filePath,
+                    `file:${await sha256File(candidate)}`,
+                ];
+            }
+            return [
+                filePath,
+                `other:${info.mode}:${info.size}:${info.mtimeMs}`,
+            ];
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? String(error.code)
+                : "unknown";
+            return [filePath, `unreadable:${code}`];
+        }
+    }));
+    return new Map(entries);
+}
 const DAG_RUNS_PREFIX = ".harness/dag-runs/";
 /**
  * Ephemeral interpreter/tool caches that writers may create while drafting tests.

package/dist/worker/delivery/git-transaction.js

@@ -122,22 +122,51 @@ export async function finalizeGitTask(transaction, outcome) {
     const changes = await readChanges(transaction.repoRoot);
     const newIgnored = currentIgnored.map((entry) => entry.path).filter((entry) => !ignoredBaselineByPath.has(entry));
     if (outcome.status === "succeeded") {
-        if (changes.length === 0)
+        const allowedPaths = expandAllowedPathsForWorkflow(resolveWorkflow(outcome.taskSpec).workflow, outcome.taskSpec.constraints.allowed_paths);
+        // Evidence under allowed_paths may be gitignored for local convenience (e.g.
+        // reports/welcome/** smoke JSON) but must still checkpoint for Task Pool Done.
+        // Sensitive / out-of-scope ignored files remain fail-closed; ephemeral tool
+        // caches neither block nor force-add.
+        const forceAddIgnored = [];
+        const blockedIgnored = [];
+        for (const entry of newIgnored) {
+            if (isEphemeralToolCachePath(entry))
+                continue;
+            if (isSensitivePath(entry)) {
+                blockedIgnored.push(entry);
+                continue;
+            }
+            if (allowedPaths.some((glob) => matchesGlob(entry, glob))) {
+                forceAddIgnored.push(entry);
+            }
+            else {
+                blockedIgnored.push(entry);
+            }
+        }
+        if (blockedIgnored.length > 0) {
+            throw new Error(`task created ignored files outside the Git checkpoint: ${blockedIgnored.join(", ")}`);
+        }
+        const checkpointFiles = [...changes, ...forceAddIgnored];
+        if (checkpointFiles.length === 0) {
             throw new Error(`successful task produced no checkpointable changes: ${outcome.taskSpec.id}`);
-        if (newIgnored.length > 0)
-            throw new Error(`task created ignored files outside the Git checkpoint: ${newIgnored.join(", ")}`);
-        auditChangedPaths(changes, outcome.taskSpec);
-        await git(transaction.repoRoot, ["add", "--", ...changes]);
+        }
+        auditChangedPaths(checkpointFiles, outcome.taskSpec);
+        if (changes.length > 0) {
+            await git(transaction.repoRoot, ["add", "--", ...changes]);
+        }
+        if (forceAddIgnored.length > 0) {
+            await git(transaction.repoRoot, ["add", "-f", "--", ...forceAddIgnored]);
+        }
         const message = commitMessage(outcome.taskSpec, outcome.workerRunId);
         await git(transaction.repoRoot, ["commit", "-m", message]);
         const commit = await git(transaction.repoRoot, ["rev-parse", "HEAD"]);
-        const checkpoint = { taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, commit, changedFiles: changes, createdAt: (outcome.now ?? new Date()).toISOString() };
+        const checkpoint = { taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, commit, changedFiles: checkpointFiles, createdAt: (outcome.now ?? new Date()).toISOString() };
         const previousCheckpoint = current.lastCheckpoint;
         try {
             await assertTransactionPosition(transaction.repoRoot, { ...current, lastCheckpoint: commit });
             await assertCheckpointMetadata(transaction.repoRoot, commit, outcome.taskSpec, outcome.workerRunId);
             const afterCommitIgnored = await readIgnoredBaseline(transaction.repoRoot);
-            assertIgnoredBaselineUnchanged(current.ignoredBaseline, afterCommitIgnored);
+            assertIgnoredBaselineUnchanged(current.ignoredBaseline.filter((entry) => !isEphemeralToolCachePath(entry.path)), afterCommitIgnored.filter((entry) => !isEphemeralToolCachePath(entry.path)));
         }
         catch (error) {
             const branch = await git(transaction.repoRoot, ["branch", "--show-current"]).catch(() => "");
@@ -162,7 +191,13 @@ export async function finalizeGitTask(transaction, outcome) {
         }
         transaction.record = current;
         await assertClean(transaction.repoRoot);
-        return { status: "checkpointed", taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, commit, changedFiles: changes };
+        return {
+            status: "checkpointed",
+            taskId: outcome.taskSpec.id,
+            workerRunId: outcome.workerRunId,
+            commit,
+            changedFiles: checkpointFiles,
+        };
     }
     const artifactDir = path.join(path.dirname(transaction.recordPath), "failures", outcome.workerRunId);
     await captureFailureArtifacts(transaction.repoRoot, artifactDir, changes, newIgnored, outcome);

package/dist/worker/observe/paths.js

@@ -1,4 +1,5 @@
 import { existsSync, realpathSync } from "node:fs";
+import { open, stat } from "node:fs/promises";
 import path from "node:path";
 const ALLOWED_ARTIFACT_EXTENSIONS = new Set([
     ".csv",
@@ -91,3 +92,83 @@ function isPathInside(root, target) {
     const normalizedTarget = path.normalize(target);
     return normalizedTarget === root || normalizedTarget.startsWith(normalizedRoot);
 }
+/**
+ * Safe repo-relative file resolver for spec-evidence previews (binding sources).
+ *
+ * Enforces AC-003: rejects `..`, absolute paths (POSIX + Windows drive),
+ * directory, binary content, and symlink escape via realpath re-check.
+ *
+ * Unlike resolveArtifactPath (which only allows .harness artifact roots), this
+ * allows any repo-relative text file that was already validated as an evidence
+ * member by the caller. Returns { absPath, size } on success, throws otherwise.
+ */
+export async function resolveRepoFilePreview(repoRoot, relPath) {
+    if (!relPath || typeof relPath !== "string") {
+        throw new Error("Invalid path");
+    }
+    if (path.isAbsolute(relPath)) {
+        throw new Error("Absolute paths are not allowed");
+    }
+    // Windows drive letters (e.g. C:\) or POSIX absolute already covered, plus
+    // explicit backslash-drive form used in tests.
+    if (/^[A-Za-z]:[\\/]/.test(relPath)) {
+        throw new Error("Absolute paths are not allowed");
+    }
+    // Reject any path segment that is ".." (handles ../, nested .., ./..).
+    const preSegments = relPath.split(/[\\/]/).filter(Boolean);
+    if (preSegments.includes("..")) {
+        throw new Error("Path traversal is not allowed");
+    }
+    if (!isAllowedArtifactTextPath(relPath)) {
+        throw new Error("Binary or disallowed file type");
+    }
+    const resolvedRepoRoot = path.resolve(repoRoot);
+    let realRepoRoot;
+    try {
+        realRepoRoot = realpathSync(resolvedRepoRoot);
+    }
+    catch {
+        realRepoRoot = resolvedRepoRoot;
+    }
+    const candidate = path.resolve(realRepoRoot, relPath);
+    const relative = path.relative(realRepoRoot, candidate);
+    if (relative === "" ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        throw new Error("Path escapes repo root");
+    }
+    if (!existsSync(candidate)) {
+        throw new Error("File not found");
+    }
+    let realCandidate;
+    try {
+        realCandidate = realpathSync(candidate);
+    }
+    catch {
+        throw new Error("File not found");
+    }
+    if (!isPathInside(realRepoRoot, realCandidate)) {
+        throw new Error("Symlink escapes repo root");
+    }
+    const fileStat = await stat(realCandidate);
+    if (!fileStat.isFile()) {
+        throw new Error("Path is not a regular file");
+    }
+    const sampleLength = Math.min(fileStat.size, 8 * 1024);
+    if (sampleLength > 0) {
+        const sample = Buffer.alloc(sampleLength);
+        const handle = await open(realCandidate, "r");
+        let bytesRead = 0;
+        try {
+            ({ bytesRead } = await handle.read(sample, 0, sampleLength, 0));
+        }
+        finally {
+            await handle.close();
+        }
+        if (sample.subarray(0, bytesRead).includes(0)) {
+            throw new Error("Binary file content is not allowed");
+        }
+    }
+    return { absPath: realCandidate, size: fileStat.size };
+}