@tea-agent/loop-agent 0.16.25 → 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，失败也能出报告。
@@ -39,6 +42,12 @@
 - 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
 
 ### 修复

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 };
+}

package/dist/worker/observe/routes.js

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { open as openFile, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
@@ -8,8 +9,8 @@ import { clampEventHistoryLimit, listBatchEventHistory, listPoolEventHistory, }
 import { buildGlobalSnapshot, clampTaskRunHistoryLimit, listTaskRunHistory, resolveLegacyTask, } from "../observability/read-model.js";
 import { dagSourceBindingSchema } from "../../workflows/dag/types.js";
 import { getTaskPoolRoot } from "../pool/run-store.js";
-import { isAllowedArtifactTextPath, resolveArtifactPath, toRepoRelativeArtifactPath, } from "./paths.js";
-import { extractSpecEvidence, } from "./spec-evidence.js";
+import { isAllowedArtifactTextPath, resolveArtifactPath, resolveRepoFilePreview, toRepoRelativeArtifactPath, } from "./paths.js";
+import { extractSpecEvidence, extractSpecReadContent, } from "./spec-evidence.js";
 const ARTIFACT_PREVIEW_MAX_BYTES = 64 * 1024;
 export function createObserveSnapshotCache() {
     return { expiresAt: 0 };
@@ -76,6 +77,11 @@ const ROUTES = [
         pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/spec-evidence$/,
         handler: handleDagNodeSpecEvidence,
     },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/spec-evidence\/file$/,
+        handler: handleDagNodeSpecEvidenceFile,
+    },
     {
         method: "GET",
         pattern: /^\/api\/dag-runs\/([^/]+)$/,
@@ -706,6 +712,109 @@ function sendJson(res, status, body) {
     });
     res.end(payload);
 }
+async function loadDagRunSourceBinding(repoRoot, dagRunId) {
+    const dagRunsRoot = path.resolve(repoRoot, ".harness", "dag-runs");
+    for (const lifecycle of ["active", "completed", "paused"]) {
+        const runJsonPath = path.join(dagRunsRoot, lifecycle, dagRunId, "run.json");
+        try {
+            const runRaw = await readFile(runJsonPath, "utf-8");
+            const runSpec = JSON.parse(runRaw);
+            const parsed = dagSourceBindingSchema.safeParse(runSpec.sourceBinding);
+            if (parsed.success)
+                return parsed.data;
+            return undefined;
+        }
+        catch {
+            // run.json may not exist; continue to next lifecycle
+        }
+    }
+    return undefined;
+}
+/**
+ * Read-only spec-evidence file preview (AC-001..AC-005). Re-validates evidence
+ * membership server-side: binding paths must be in sourceBinding.sources, read
+ * paths must have a successful paired read in session events. Enforces AC-003
+ * path safety and AC-004 truncation + redaction.
+ */
+async function handleDagNodeSpecEvidenceFile(_req, res, match, ctx) {
+    const dagRunId = match.params.id;
+    const nodeId = match.params.sub;
+    if (!isSafeObservabilityIdentifier(dagRunId) || !isSafeObservabilityIdentifier(nodeId)) {
+        sendJson(res, 400, { error: "Invalid dag run or node identifier" });
+        return;
+    }
+    const source = match.query.get("source");
+    const rawPath = match.query.get("path");
+    if (source !== "binding" && source !== "read") {
+        sendJson(res, 400, { error: "Invalid source" });
+        return;
+    }
+    if (!rawPath) {
+        sendJson(res, 400, { error: "path is required" });
+        return;
+    }
+    const maxBytes = ARTIFACT_PREVIEW_MAX_BYTES;
+    if (source === "binding") {
+        const sourceBinding = await loadDagRunSourceBinding(ctx.repoRoot, dagRunId);
+        const member = sourceBinding?.sources?.find((s) => s.path === rawPath);
+        if (!sourceBinding || !member) {
+            sendJson(res, 404, { error: "Path is not a bound source" });
+            return;
+        }
+        let resolved;
+        try {
+            resolved = await resolveRepoFilePreview(ctx.repoRoot, rawPath);
+        }
+        catch {
+            sendJson(res, 400, { error: "Invalid or unsafe path" });
+            return;
+        }
+        let raw;
+        try {
+            raw = await readFile(resolved.absPath, "utf-8");
+        }
+        catch {
+            sendJson(res, 404, { error: "File not found" });
+            return;
+        }
+        const redacted = redactSecrets(raw);
+        const content = truncateUtf8Preview(redacted, maxBytes);
+        const truncated = content !== redacted;
+        const currentSha256 = createHash("sha256")
+            .update(raw, "utf-8")
+            .digest("hex");
+        sendJson(res, 200, {
+            source: "binding",
+            path: rawPath,
+            sha256: member.sha256,
+            currentSha256,
+            hashMatch: currentSha256 === member.sha256,
+            content,
+            truncated,
+            contentBytes: Buffer.byteLength(content, "utf-8"),
+            maxBytes,
+        });
+        return;
+    }
+    // source === "read"
+    const record = await extractSpecReadContent(ctx.repoRoot, dagRunId, nodeId, rawPath);
+    if (!record) {
+        sendJson(res, 404, { error: "Path was not successfully read" });
+        return;
+    }
+    const redacted = redactSecrets(record.content);
+    const content = truncateUtf8Preview(redacted, maxBytes);
+    const truncated = content !== redacted;
+    sendJson(res, 200, {
+        source: "read",
+        path: rawPath,
+        content,
+        truncated,
+        contentBytes: Buffer.byteLength(content, "utf-8"),
+        maxBytes,
+        readAt: record.timestamp ?? null,
+    });
+}
 async function handleDagNodeSpecEvidence(_req, res, match, ctx) {
     const dagRunId = match.params.id;
     const nodeId = match.params.sub;
@@ -715,24 +824,23 @@ async function handleDagNodeSpecEvidence(_req, res, match, ctx) {
     }
     // Extract skill injection info from the DAG run spec (run.json)
     const skillInjection = { skills: [], references: [] };
-    let sourceBinding;
-    const dagRunsRoot = path.resolve(ctx.repoRoot, ".harness", "dag-runs");
-    for (const lifecycle of ["active", "completed", "paused"]) {
-        const runJsonPath = path.join(dagRunsRoot, lifecycle, dagRunId, "run.json");
-        try {
-            const runRaw = await readFile(runJsonPath, "utf-8");
-            const runSpec = JSON.parse(runRaw);
-            const parsedSourceBinding = dagSourceBindingSchema.safeParse(runSpec.sourceBinding);
-            if (parsedSourceBinding.success)
-                sourceBinding = parsedSourceBinding.data;
-            const task = runSpec.tasks?.find((t) => t.id === nodeId);
-            if (task?.skills && Array.isArray(task.skills)) {
-                skillInjection.skills = task.skills;
+    const sourceBinding = await loadDagRunSourceBinding(ctx.repoRoot, dagRunId);
+    {
+        const dagRunsRoot = path.resolve(ctx.repoRoot, ".harness", "dag-runs");
+        for (const lifecycle of ["active", "completed", "paused"]) {
+            const runJsonPath = path.join(dagRunsRoot, lifecycle, dagRunId, "run.json");
+            try {
+                const runRaw = await readFile(runJsonPath, "utf-8");
+                const runSpec = JSON.parse(runRaw);
+                const task = runSpec.tasks?.find((t) => t.id === nodeId);
+                if (task?.skills && Array.isArray(task.skills)) {
+                    skillInjection.skills = task.skills;
+                }
+                break;
+            }
+            catch {
+                // run.json may not exist; continue to next lifecycle
             }
-            break;
-        }
-        catch {
-            // run.json may not exist; continue to next lifecycle
         }
     }
     const evidence = await extractSpecEvidence(ctx.repoRoot, dagRunId, nodeId);