@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/worker/observe/routes.js

@@ -0,0 +1,1077 @@
+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 { fileURLToPath } from "node:url";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
+import { parseWorkerEventLine } from "../observability/events.js";
+import { isSafeObservabilityIdentifier } from "../observability/event-store.js";
+import { clampEventHistoryLimit, listBatchEventHistory, listPoolEventHistory, } from "../observability/event-history.js";
+import { buildGlobalSnapshot, clampDagRunHistoryPageSize, clampTaskRunHistoryLimit, listDagRunHistoryFromSnapshot, listTaskRunHistory, resolveLegacyTask, } from "../observability/read-model.js";
+import { loadDagRunExecutionTrajectory } from "../observability/dag-execution-trajectory.js";
+import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { dagSourceBindingSchema } from "../../workflows/dag/types.js";
+import { getTaskPoolRoot } from "../pool/run-store.js";
+import { isAllowedArtifactTextPath, resolveArtifactPath, resolveRepoFilePreview, toRepoRelativeArtifactPath, } from "./paths.js";
+import { extractSpecEvidence, extractSpecReadContent, } from "./spec-evidence.js";
+import { buildDagNodeInput } from "./node-input.js";
+import { loadDagNodeExecutionOutput } from "./dag-node-execution-output.js";
+import { buildObserveHealthV1 } from "./health.js";
+import { buildNightJobDetail, buildNightJobsDoctor, buildNightJobsList, buildNightJobsMorning, } from "./night-jobs.js";
+const ARTIFACT_PREVIEW_MAX_BYTES = 64 * 1024;
+export function createObserveSnapshotCache() {
+    return { expiresAt: 0 };
+}
+export function defaultObserveStaticDir(fromFileUrl = import.meta.url) {
+    return path.join(path.dirname(fileURLToPath(fromFileUrl)), "static");
+}
+export function createObserveRouteContext(repoRoot, options = {}) {
+    return {
+        repoRoot: path.resolve(repoRoot),
+        pollIntervalMs: options.pollIntervalMs ?? 1000,
+        staticDir: options.staticDir ?? defaultObserveStaticDir(),
+        snapshotCache: options.snapshotCache ?? createObserveSnapshotCache(),
+    };
+}
+export const ROUTES = [
+    { method: "GET", pattern: /^\/api\/health$/, handler: handleHealth },
+    { method: "GET", pattern: /^\/api\/snapshot$/, handler: handleSnapshot },
+    { method: "GET", pattern: /^\/api\/batches$/, handler: handleBatches },
+    {
+        method: "GET",
+        pattern: /^\/api\/batches\/([^/]+)\/events$/,
+        handler: handleBatchEvents,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/batches\/([^/]+)$/,
+        handler: handleBatchById,
+    },
+    /**
+     * Pool bounded event history (cursor/limit). Distinct from SSE `/api/events/stream`
+     * and from run/session `?after=<line-offset>` integer offsets.
+     */
+    { method: "GET", pattern: /^\/api\/events$/, handler: handlePoolEvents },
+    { method: "GET", pattern: /^\/api\/tasks$/, handler: handleTasks },
+    // Canonical feature-scoped task routes (must precede legacy /api/tasks/:id).
+    {
+        method: "GET",
+        pattern: /^\/api\/features\/([^/]+)\/tasks\/([^/]+)\/runs$/,
+        handler: handleFeatureTaskRuns,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/features\/([^/]+)\/tasks\/([^/]+)$/,
+        handler: handleFeatureTaskById,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/tasks\/([^/]+)\/runs$/,
+        handler: handleTaskRuns,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/tasks\/([^/]+)$/,
+        handler: handleTaskById,
+    },
+    { method: "GET", pattern: /^\/api\/runs\/([^/]+)$/, handler: handleRunById },
+    {
+        method: "GET",
+        pattern: /^\/api\/runs\/([^/]+)\/events$/,
+        handler: handleRunEvents,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/runs\/([^/]+)\/artifacts$/,
+        handler: handleRunArtifacts,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/session-events$/,
+        handler: handleDagNodeSessionEvents,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/input$/,
+        handler: handleDagNodeInput,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/execution-output$/,
+        handler: handleDagNodeExecutionOutput,
+    },
+    {
+        method: "GET",
+        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\/([^/]+)$/,
+        handler: handleDagRunById,
+    },
+    // List route must be registered after /api/dag-runs/:id so detail keeps priority;
+    // matchObserveGetRoute scans in order and this path has no capture group.
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs$/,
+        handler: handleDagRuns,
+    },
+    { method: "GET", pattern: /^\/api\/artifacts$/, handler: handleArtifactRead },
+    {
+        method: "GET",
+        pattern: /^\/api\/events\/stream$/,
+        handler: handleEventStream,
+    },
+    // Night Scheduler Inspect (Phase 5) — read-only projections over scheduler facts.
+    { method: "GET", pattern: /^\/api\/night-jobs$/, handler: handleNightJobs },
+    {
+        method: "GET",
+        pattern: /^\/api\/night-jobs\/morning$/,
+        handler: handleNightJobsMorning,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/night-jobs\/doctor$/,
+        handler: handleNightJobsDoctor,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/night-jobs\/([^/]+)$/,
+        handler: handleNightJobById,
+    },
+];
+export function matchObserveGetRoute(pathname) {
+    for (const route of ROUTES) {
+        if (route.method !== "GET")
+            continue;
+        const match = route.pattern.exec(pathname);
+        if (!match)
+            continue;
+        const params = {};
+        if (match[1])
+            params.id = match[1];
+        if (match[2])
+            params.sub = match[2];
+        return { params, query: new URLSearchParams(), handler: route.handler };
+    }
+    return null;
+}
+export async function handleMatchedObserveRoute(req, res, match, ctx) {
+    try {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        await match.handler(req, res, { ...match, query: url.searchParams }, ctx);
+    }
+    catch (error) {
+        if (!res.headersSent) {
+            sendJson(res, 500, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
+export async function handleRequest(req, res, ctx) {
+    const method = req.method ?? "GET";
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const pathname = decodeURIComponent(url.pathname);
+    if (method !== "GET") {
+        sendJson(res, 405, { error: "Method not allowed" });
+        return true;
+    }
+    const match = matchObserveGetRoute(pathname);
+    if (match) {
+        await handleMatchedObserveRoute(req, res, match, ctx);
+        return true;
+    }
+    if (pathname.startsWith("/api/")) {
+        sendJson(res, 404, { error: "Not found" });
+        return true;
+    }
+    return false;
+}
+export async function serveStatic(req, res, staticDir) {
+    await serveObserveStatic(req, res, staticDir);
+}
+export async function serveObserveStatic(req, res, staticDir, options = {}) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    let pathname = decodeURIComponent(url.pathname);
+    const urlPrefix = options.urlPrefix?.replace(/\/$/, "");
+    const withinPrefix = Boolean(urlPrefix) &&
+        (pathname === urlPrefix || pathname.startsWith(`${urlPrefix}/`));
+    if (urlPrefix && withinPrefix) {
+        pathname = pathname.slice(urlPrefix.length) || "/";
+    }
+    if (pathname === "/") {
+        pathname = "/index.html";
+    }
+    const filePath = path.join(staticDir, pathname);
+    const resolvedStatic = path.resolve(staticDir);
+    const resolvedFile = path.resolve(filePath);
+    if (!resolvedFile.startsWith(resolvedStatic + path.sep) &&
+        resolvedFile !== resolvedStatic) {
+        sendJson(res, 404, { error: "Not found" });
+        return;
+    }
+    if (!existsSync(resolvedFile)) {
+        sendJson(res, 404, { error: "Not found" });
+        return;
+    }
+    const content = await readFile(resolvedFile);
+    const contentType = contentTypeFor(pathname);
+    res.writeHead(200, {
+        "Content-Type": contentType,
+        "Content-Length": content.byteLength,
+        "X-Content-Type-Options": "nosniff",
+        "X-Frame-Options": "SAMEORIGIN",
+    });
+    res.end(content);
+}
+async function handleHealth(_req, res, _match, ctx) {
+    sendJson(res, 200, buildObserveHealthV1({
+        repoRoot: ctx.repoRoot,
+        routes: ROUTES,
+    }));
+}
+async function getSnapshot(ctx) {
+    const now = Date.now();
+    if (ctx.snapshotCache.snapshot && now < ctx.snapshotCache.expiresAt) {
+        return ctx.snapshotCache.snapshot;
+    }
+    if (ctx.snapshotCache.inFlight) {
+        return ctx.snapshotCache.inFlight;
+    }
+    const inFlight = buildGlobalSnapshot({ repoRoot: ctx.repoRoot });
+    ctx.snapshotCache.inFlight = inFlight;
+    try {
+        const snapshot = await inFlight;
+        ctx.snapshotCache.snapshot = snapshot;
+        ctx.snapshotCache.expiresAt = Date.now() + ctx.pollIntervalMs;
+        return snapshot;
+    }
+    finally {
+        if (ctx.snapshotCache.inFlight === inFlight) {
+            ctx.snapshotCache.inFlight = undefined;
+        }
+    }
+}
+async function handleSnapshot(_req, res, _match, ctx) {
+    const snapshot = await getSnapshot(ctx);
+    sendJson(res, 200, snapshot);
+}
+async function handleNightJobs(_req, res, _match, ctx) {
+    const body = await buildNightJobsList(ctx.repoRoot);
+    sendJson(res, 200, body);
+}
+async function handleNightJobsMorning(_req, res, match, ctx) {
+    const date = match.query.get("date") ?? undefined;
+    const timezone = match.query.get("timezone") ?? match.query.get("tz") ?? undefined;
+    const body = await buildNightJobsMorning(ctx.repoRoot, {
+        ...(date ? { date } : {}),
+        ...(timezone ? { timezone } : {}),
+    });
+    sendJson(res, 200, body);
+}
+async function handleNightJobsDoctor(_req, res, _match, ctx) {
+    const body = await buildNightJobsDoctor(ctx.repoRoot);
+    sendJson(res, 200, body);
+}
+async function handleNightJobById(_req, res, match, ctx) {
+    const scheduleId = match.params.id;
+    if (!scheduleId) {
+        sendJson(res, 400, { error: "schedule id required" });
+        return;
+    }
+    const body = await buildNightJobDetail(ctx.repoRoot, scheduleId);
+    if (!body) {
+        sendJson(res, 404, { error: "Night schedule not found" });
+        return;
+    }
+    sendJson(res, 200, body);
+}
+async function handleBatches(_req, res, _match, ctx) {
+    const snapshot = await getSnapshot(ctx);
+    sendJson(res, 200, snapshot.batches);
+}
+async function handleBatchById(_req, res, match, ctx) {
+    const snapshot = await getSnapshot(ctx);
+    const batch = snapshot.batches.find((b) => b.batchRunId === match.params.id);
+    if (!batch) {
+        sendJson(res, 404, { error: "Batch not found" });
+        return;
+    }
+    sendJson(res, 200, batch);
+}
+/**
+ * Bounded batch event history. Query: `limit` (default 50, max 200), `cursor`
+ * (opaque history cursor). Not the same as run/SSE `after` line offsets.
+ */
+async function handleBatchEvents(_req, res, match, ctx) {
+    const batchRunId = match.params.id;
+    if (!isSafeObservabilityIdentifier(batchRunId)) {
+        sendJson(res, 404, { error: "Batch not found" });
+        return;
+    }
+    const limit = clampEventHistoryLimit(parsePositiveInt(match.query.get("limit"), NaN));
+    const cursor = match.query.get("cursor") ?? undefined;
+    const page = await listBatchEventHistory(ctx.repoRoot, batchRunId, {
+        limit,
+        cursor,
+    });
+    sendJson(res, 200, page);
+}
+/**
+ * Bounded pool-wide event history. Path is `/api/events` (JSON page), not
+ * `/api/events/stream` (SSE). Uses `cursor`/`limit`, not integer `after`.
+ */
+async function handlePoolEvents(_req, res, match, ctx) {
+    const limit = clampEventHistoryLimit(parsePositiveInt(match.query.get("limit"), NaN));
+    const cursor = match.query.get("cursor") ?? undefined;
+    const page = await listPoolEventHistory(ctx.repoRoot, { limit, cursor });
+    sendJson(res, 200, page);
+}
+async function handleTasks(_req, res, _match, ctx) {
+    const snapshot = await getSnapshot(ctx);
+    sendJson(res, 200, snapshot.tasks);
+}
+async function handleFeatureTaskById(_req, res, match, ctx) {
+    const resolved = resolveFeatureTaskParams(match);
+    if (!resolved) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    if (!isSafeObservabilityIdentifier(resolved.featureId) ||
+        !isSafeObservabilityIdentifier(resolved.taskId)) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    const snapshot = await getSnapshot(ctx);
+    const task = snapshot.tasks.find((t) => t.featureId === resolved.featureId && t.taskId === resolved.taskId);
+    if (!task) {
+        sendJson(res, 404, { error: "Task not found" });
+        return;
+    }
+    sendJson(res, 200, task);
+}
+async function handleFeatureTaskRuns(_req, res, match, ctx) {
+    const resolved = resolveFeatureTaskParams(match);
+    if (!resolved) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    if (!isSafeObservabilityIdentifier(resolved.featureId) ||
+        !isSafeObservabilityIdentifier(resolved.taskId)) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    const limit = clampTaskRunHistoryLimit(parsePositiveInt(match.query.get("limit"), 0) || undefined);
+    const before = match.query.get("before");
+    const page = await listTaskRunHistory(ctx.repoRoot, resolved.featureId, resolved.taskId, {
+        limit,
+        before: before && before.length > 0 ? before : null,
+    });
+    // 404 only when neither snapshot row nor ledger history exists for this composite id.
+    if (page.runs.length === 0) {
+        const snapshot = await getSnapshot(ctx);
+        const known = snapshot.tasks.some((t) => t.featureId === resolved.featureId && t.taskId === resolved.taskId);
+        if (!known) {
+            sendJson(res, 404, { error: "Task not found" });
+            return;
+        }
+    }
+    sendJson(res, 200, page);
+}
+async function handleTaskById(_req, res, match, ctx) {
+    const taskId = match.params.id;
+    if (!isSafeObservabilityIdentifier(taskId)) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    const snapshot = await getSnapshot(ctx);
+    const resolved = resolveLegacyTask(snapshot.tasks, taskId);
+    if (resolved.kind === "missing") {
+        sendJson(res, 404, { error: "Task not found" });
+        return;
+    }
+    if (resolved.kind === "ambiguous") {
+        sendJson(res, 409, ambiguousTaskBody(taskId, resolved.candidates));
+        return;
+    }
+    sendJson(res, 200, resolved.task);
+}
+async function handleTaskRuns(_req, res, match, ctx) {
+    const taskId = match.params.id;
+    if (!isSafeObservabilityIdentifier(taskId)) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    const snapshot = await getSnapshot(ctx);
+    const resolved = resolveLegacyTask(snapshot.tasks, taskId);
+    if (resolved.kind === "ambiguous") {
+        sendJson(res, 409, ambiguousTaskBody(taskId, resolved.candidates));
+        return;
+    }
+    if (resolved.kind === "missing") {
+        // No snapshot row: do not guess featureId for history.
+        sendJson(res, 404, { error: "Task not found" });
+        return;
+    }
+    const featureId = resolved.task.featureId;
+    if (!featureId) {
+        sendJson(res, 404, { error: "Task not found" });
+        return;
+    }
+    const limit = clampTaskRunHistoryLimit(parsePositiveInt(match.query.get("limit"), 0) || undefined);
+    const before = match.query.get("before");
+    const page = await listTaskRunHistory(ctx.repoRoot, featureId, taskId, {
+        limit,
+        before: before && before.length > 0 ? before : null,
+    });
+    sendJson(res, 200, page);
+}
+function ambiguousTaskBody(taskId, candidates) {
+    return {
+        error: "Task identity ambiguous",
+        taskId,
+        candidates,
+    };
+}
+/** Extract featureId/taskId from /api/features/:featureId/tasks/:taskId[...]. */
+function resolveFeatureTaskParams(match) {
+    // handleRequest maps capture groups to params.id (group 1) and params.sub (group 2).
+    const featureId = match.params.featureId ?? match.params.id;
+    const taskId = match.params.taskId ?? match.params.sub;
+    if (!featureId || !taskId)
+        return null;
+    return { featureId, taskId };
+}
+async function handleRunById(_req, res, match, ctx) {
+    if (!isSafeObservabilityIdentifier(match.params.id)) {
+        sendJson(res, 400, { error: "Invalid run identifier" });
+        return;
+    }
+    const snapshot = await getSnapshot(ctx);
+    const task = findRunByWorkerRunId(snapshot.tasks, snapshot.batches, match.params.id);
+    if (!task) {
+        sendJson(res, 404, { error: "Run not found" });
+        return;
+    }
+    sendJson(res, 200, task);
+}
+async function handleRunEvents(_req, res, match, ctx) {
+    const workerRunId = match.params.id;
+    if (!isSafeObservabilityIdentifier(workerRunId)) {
+        sendJson(res, 400, { error: "Invalid run identifier" });
+        return;
+    }
+    const after = parseNonNegativeInt(match.query.get("after"), 0);
+    const eventsPath = path.join(getTaskPoolRoot(ctx.repoRoot), "observability", "runs", workerRunId, "events.jsonl");
+    const events = (await readJsonlLines(eventsPath, after)).map((event) => normalizeEventArtifactRefs(ctx.repoRoot, event));
+    sendJson(res, 200, { events });
+}
+async function handleRunArtifacts(_req, res, match, ctx) {
+    const workerRunId = match.params.id;
+    if (!isSafeObservabilityIdentifier(workerRunId)) {
+        sendJson(res, 400, { error: "Invalid run identifier" });
+        return;
+    }
+    const snapshot = await getSnapshot(ctx);
+    const task = findRunByWorkerRunId(snapshot.tasks, snapshot.batches, workerRunId);
+    const artifacts = [];
+    const seen = new Set();
+    if (task?.artifactRefs) {
+        for (const [label, artifactPath] of Object.entries(task.artifactRefs)) {
+            if (!artifactPath || seen.has(artifactPath))
+                continue;
+            seen.add(artifactPath);
+            artifacts.push({ path: artifactPath, label });
+        }
+    }
+    const eventsPath = path.join(getTaskPoolRoot(ctx.repoRoot), "observability", "runs", workerRunId, "events.jsonl");
+    const runEvents = await readJsonlLines(eventsPath, 0);
+    for (const event of runEvents) {
+        const parsed = event;
+        if (parsed.workerRunId && parsed.workerRunId !== workerRunId)
+            continue;
+        if (!parsed.artifactRefs)
+            continue;
+        for (const [label, artifactPath] of Object.entries(parsed.artifactRefs)) {
+            const relativePath = toRepoRelativeArtifactPath(ctx.repoRoot, artifactPath);
+            if (!relativePath || seen.has(relativePath))
+                continue;
+            seen.add(relativePath);
+            artifacts.push({ path: relativePath, label });
+        }
+    }
+    sendJson(res, 200, { artifacts });
+}
+/**
+ * GET /api/dag-runs?page=&pageSize=
+ * Lightweight formal DAG history page (schemaVersion 1).
+ */
+async function handleDagRuns(_req, res, match, ctx) {
+    const snapshot = await getSnapshot(ctx);
+    const page = parsePositiveInt(match.query.get("page"), 1);
+    const pageSize = clampDagRunHistoryPageSize(parsePositiveInt(match.query.get("pageSize"), 0) || undefined);
+    const body = listDagRunHistoryFromSnapshot(snapshot, { page, pageSize });
+    sendJson(res, 200, body);
+}
+export async function handleDagRunById(_req, res, match, ctx) {
+    const snapshot = await getSnapshot(ctx);
+    const dagRun = snapshot.dagRuns.find((d) => d.dagRunId === match.params.id);
+    if (!dagRun) {
+        sendJson(res, 404, { error: "DAG run not found" });
+        return;
+    }
+    const payload = { ...dagRun };
+    // P1 契约：在 detail 响应中内嵌有界 executionTrajectory（不新增端点、
+    // 不接收客户端 artifact path）。仅当存在真实执行证据/警告/投影异常时附加；
+    // legacy 或纯事件 run 省略该字段，前端据此显示「本次运行没有可展开的执行轨迹」。
+    const trajectory = await loadDagRunExecutionTrajectory(ctx.repoRoot, dagRun.dagRunId);
+    if (trajectory &&
+        (trajectory.occurrences.length > 0 ||
+            trajectory.projectionError === true ||
+            trajectory.warnings.length > 0)) {
+        payload.executionTrajectory = trajectory;
+    }
+    sendJson(res, 200, payload);
+}
+async function handleDagNodeInput(_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 result = await buildDagNodeInput(ctx.repoRoot, dagRunId, nodeId);
+    sendJson(res, result.status, result.body);
+}
+/**
+ * Read-only execution body by attempt-N / pass-N key only.
+ * Clients must never submit artifact paths; server maps key → run-dir segments.
+ */
+async function handleDagNodeExecutionOutput(_req, res, match, ctx) {
+    const dagRunId = match.params.id;
+    const nodeId = match.params.sub;
+    const key = match.query.get("key");
+    // Reject path-shaped inputs even if smuggled via key/query aliases.
+    if (match.query.has("path") || match.query.has("artifactPath")) {
+        sendJson(res, 400, {
+            error: "Artifact path is not accepted; use key=attempt-N|pass-N",
+            reason: "path-not-allowed",
+        });
+        return;
+    }
+    const result = await loadDagNodeExecutionOutput(ctx.repoRoot, dagRunId, nodeId, key);
+    sendJson(res, result.status, result.body);
+}
+async function handleDagNodeSessionEvents(_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 after = parseNonNegativeInt(match.query.get("after"), 0);
+    const snapshot = await getSnapshot(ctx);
+    const dagRun = snapshot.dagRuns.find((d) => d.dagRunId === dagRunId);
+    const eventsPath = resolveSessionEventsPath(ctx.repoRoot, dagRunId, nodeId, dagRun?.dagPath);
+    if (!eventsPath) {
+        sendJson(res, 400, { error: "Invalid session events path" });
+        return;
+    }
+    if (!existsSync(eventsPath)) {
+        sendJson(res, 200, { events: [], nextOffset: 0 });
+        return;
+    }
+    const page = await readJsonlPage(eventsPath, after);
+    sendJson(res, 200, page);
+}
+async function handleArtifactRead(_req, res, match, ctx) {
+    const relativePath = match.query.get("path") ?? "";
+    const resolved = resolveArtifactPath(ctx.repoRoot, relativePath);
+    if (!resolved || !isAllowedArtifactTextPath(relativePath)) {
+        sendJson(res, 400, { error: "Invalid artifact path" });
+        return;
+    }
+    if (!existsSync(resolved)) {
+        sendJson(res, 404, { error: "Artifact not found" });
+        return;
+    }
+    const artifactStat = await stat(resolved);
+    if (!artifactStat.isFile()) {
+        sendJson(res, 400, { error: "Artifact is not a readable text file" });
+        return;
+    }
+    const sourceBytes = artifactStat.size;
+    const start = Math.max(0, sourceBytes - ARTIFACT_PREVIEW_MAX_BYTES);
+    const length = Math.min(sourceBytes, ARTIFACT_PREVIEW_MAX_BYTES);
+    const buffer = Buffer.alloc(length);
+    const handle = await openFile(resolved, "r");
+    let bytesRead = 0;
+    try {
+        ({ bytesRead } = await handle.read(buffer, 0, length, start));
+    }
+    finally {
+        await handle.close();
+    }
+    let raw = buffer.subarray(0, bytesRead).toString("utf-8");
+    let truncated = start > 0;
+    if (truncated) {
+        const firstCompleteLine = raw.indexOf("\n");
+        raw = firstCompleteLine >= 0 ? raw.slice(firstCompleteLine + 1) : "";
+    }
+    const tail = match.query.get("tail");
+    if (tail !== null) {
+        const tailLines = parsePositiveInt(tail, 0);
+        if (tailLines > 0) {
+            const lines = raw.replace(/\n$/, "").split("\n");
+            truncated = truncated || lines.length > tailLines;
+            raw = lines.slice(-tailLines).join("\n");
+        }
+    }
+    const redacted = redactSecrets(raw);
+    const content = truncateUtf8Preview(redacted, ARTIFACT_PREVIEW_MAX_BYTES);
+    truncated = truncated || content !== redacted;
+    sendJson(res, 200, {
+        content,
+        truncated,
+        sourceBytes,
+        maxBytes: ARTIFACT_PREVIEW_MAX_BYTES,
+    });
+}
+async function handleEventStream(req, res, match, ctx) {
+    const batchRunId = match.query.get("batchRunId");
+    if (!batchRunId) {
+        sendJson(res, 400, { error: "batchRunId is required" });
+        return;
+    }
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+        // Disable proxy buffering (nginx) so heartbeats reach the client.
+        "X-Accel-Buffering": "no",
+    });
+    // Flush headers immediately for proxies that wait on first body byte.
+    if (typeof res.flushHeaders === "function") {
+        res.flushHeaders();
+    }
+    const observabilityRoot = path.join(getTaskPoolRoot(ctx.repoRoot), "observability");
+    const eventsPath = path.join(observabilityRoot, "events.jsonl");
+    let offset = 0;
+    let knownFileSize;
+    let timer;
+    let closed = false;
+    let lastHeartbeatAt = 0;
+    const heartbeatEveryMs = Math.max(15_000, ctx.pollIntervalMs * 10);
+    const writeHeartbeat = () => {
+        if (closed || res.writableEnded)
+            return;
+        const now = Date.now();
+        if (now - lastHeartbeatAt < heartbeatEveryMs)
+            return;
+        lastHeartbeatAt = now;
+        res.write(`: keepalive ${new Date(now).toISOString()}\n\n`);
+    };
+    const sendMatchingEvents = async (initial) => {
+        writeHeartbeat();
+        let currentFileSize;
+        try {
+            currentFileSize = (await stat(eventsPath)).size;
+        }
+        catch {
+            knownFileSize = undefined;
+            offset = 0;
+            return;
+        }
+        if (!shouldReadSseEventFile(knownFileSize, currentFileSize))
+            return;
+        if (knownFileSize !== undefined && currentFileSize < knownFileSize) {
+            offset = 0;
+        }
+        const page = await readFilteredEvents(eventsPath, offset, batchRunId, ctx.repoRoot);
+        if (!page.ok)
+            return;
+        offset = page.nextOffset;
+        knownFileSize = currentFileSize;
+        for (const event of page.events) {
+            if (initial || !res.writableEnded) {
+                res.write(`data: ${JSON.stringify(event)}\n\n`);
+            }
+        }
+    };
+    await sendMatchingEvents(true);
+    const scheduleNextPoll = () => {
+        if (closed)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void sendMatchingEvents(false)
+                .then(scheduleNextPoll)
+                .catch(() => {
+                closed = true;
+                if (!res.writableEnded)
+                    res.end();
+            });
+        }, ctx.pollIntervalMs);
+    };
+    scheduleNextPoll();
+    req.on("close", () => {
+        closed = true;
+        if (timer)
+            clearTimeout(timer);
+        if (!res.writableEnded)
+            res.end();
+    });
+}
+function findRunByWorkerRunId(tasks, batches, workerRunId) {
+    return (tasks.find((task) => task.workerRunId === workerRunId) ??
+        batches
+            .flatMap((batch) => batch.tasks)
+            .find((task) => task.workerRunId === workerRunId));
+}
+async function readJsonlLines(filePath, after) {
+    const page = await readJsonlPage(filePath, after);
+    return page.events;
+}
+async function readJsonlPage(filePath, after) {
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        const lines = raw
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean);
+        const events = lines
+            .slice(after)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return undefined;
+            }
+        })
+            .filter((line) => line !== undefined);
+        return { events, nextOffset: lines.length };
+    }
+    catch {
+        return { events: [], nextOffset: after };
+    }
+}
+const DAG_RUN_LIFECYCLE_DIRS = ["active", "completed", "paused"];
+function resolveSessionEventsPath(repoRoot, dagRunId, nodeId, dagRunDir) {
+    if (!isSafeObservabilityIdentifier(dagRunId) ||
+        !isSafeObservabilityIdentifier(nodeId)) {
+        return null;
+    }
+    const dagRunsRoot = path.resolve(repoRoot, ".harness", "dag-runs");
+    const candidates = [];
+    if (dagRunDir) {
+        candidates.push(path.join(dagRunDir, nodeId, "session-events.jsonl"));
+    }
+    for (const lifecycle of DAG_RUN_LIFECYCLE_DIRS) {
+        candidates.push(path.join(dagRunsRoot, lifecycle, dagRunId, nodeId, "session-events.jsonl"));
+    }
+    for (const candidate of candidates) {
+        const resolved = path.resolve(candidate);
+        if (!isPathInside(dagRunsRoot, resolved))
+            continue;
+        if (!isExpectedSessionEventsRelativePath(dagRunsRoot, resolved, dagRunId, nodeId)) {
+            continue;
+        }
+        if (existsSync(resolved))
+            return resolved;
+    }
+    const fallback = path.resolve(dagRunsRoot, "active", dagRunId, nodeId, "session-events.jsonl");
+    if (isPathInside(dagRunsRoot, fallback) &&
+        isExpectedSessionEventsRelativePath(dagRunsRoot, fallback, dagRunId, nodeId)) {
+        return fallback;
+    }
+    return null;
+}
+function isExpectedSessionEventsRelativePath(dagRunsRoot, resolvedPath, dagRunId, nodeId) {
+    const relative = path.relative(dagRunsRoot, resolvedPath);
+    const parts = relative.split(path.sep).filter(Boolean);
+    return (parts.length === 4 &&
+        DAG_RUN_LIFECYCLE_DIRS.includes(parts[0]) &&
+        parts[1] === dagRunId &&
+        parts[2] === nodeId &&
+        parts[3] === "session-events.jsonl");
+}
+function isPathInside(root, target) {
+    const normalizedRoot = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+    const normalizedTarget = path.normalize(target);
+    return (normalizedTarget === root || normalizedTarget.startsWith(normalizedRoot));
+}
+async function readFilteredEvents(filePath, offset, batchRunId, repoRoot) {
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        const lines = raw
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean);
+        const events = [];
+        for (let i = offset; i < lines.length; i++) {
+            const event = parseWorkerEventLine(lines[i]);
+            if (event && event.batchRunId === batchRunId) {
+                events.push(normalizeEventArtifactRefs(repoRoot, event));
+            }
+        }
+        return { events, nextOffset: lines.length, ok: true };
+    }
+    catch {
+        return { events: [], nextOffset: offset, ok: false };
+    }
+}
+export function shouldReadSseEventFile(previousSize, currentSize) {
+    return previousSize !== currentSize;
+}
+function normalizeEventArtifactRefs(repoRoot, value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const event = value;
+    if (!event.artifactRefs)
+        return event;
+    const artifactRefs = {};
+    for (const [key, artifactPath] of Object.entries(event.artifactRefs)) {
+        const relativePath = toRepoRelativeArtifactPath(repoRoot, artifactPath);
+        if (relativePath)
+            artifactRefs[key] = relativePath;
+    }
+    return {
+        ...event,
+        artifactRefs,
+    };
+}
+function parseNonNegativeInt(value, fallback) {
+    if (value === null)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+function parsePositiveInt(value, fallback) {
+    if (value === null)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(payload),
+    });
+    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;
+        }
+        if (!isSafeObservabilityIdentifier(sourceBinding.taskId)) {
+            sendJson(res, 400, { error: "Invalid or unsafe path" });
+            return;
+        }
+        let resolved;
+        try {
+            const sourcePath = resolveDagTaskSourcePath({
+                workspaceRoot: ctx.repoRoot,
+                taskId: sourceBinding.taskId,
+                sourcePath: member.path,
+            });
+            const repoRelativePath = path.relative(ctx.repoRoot, sourcePath);
+            resolved = await resolveRepoFilePreview(ctx.repoRoot, repoRelativePath);
+        }
+        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;
+    if (!isSafeObservabilityIdentifier(dagRunId) ||
+        !isSafeObservabilityIdentifier(nodeId)) {
+        sendJson(res, 400, { error: "Invalid dag run or node identifier" });
+        return;
+    }
+    // Extract skill injection info from the DAG run spec (run.json)
+    const skillInjection = {
+        skills: [],
+        references: [],
+    };
+    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
+            }
+        }
+    }
+    const evidence = await extractSpecEvidence(ctx.repoRoot, dagRunId, nodeId);
+    if (!evidence) {
+        const hasSourceBinding = Boolean(sourceBinding);
+        sendJson(res, 200, {
+            dagRunId,
+            nodeId,
+            status: hasSourceBinding ? "source-bound" : "no-evidence",
+            skillInjection,
+            sourceBinding,
+            specReads: [],
+            specSearches: [],
+            knowledgeBaseQueries: [],
+            summary: hasSourceBinding
+                ? `已绑定 ${sourceBinding.sources.length} 个任务源文件和 ${sourceBinding.requirementIds.length} 个显式需求编号；未观察到 read 工具调用。`
+                : "未找到该节点的 session events 记录。",
+        });
+        return;
+    }
+    evidence.skillInjection = skillInjection;
+    evidence.sourceBinding = sourceBinding;
+    // Recompute status considering skill injection
+    if (evidence.specReads.length === 0 &&
+        evidence.knowledgeBaseQueries.length === 0) {
+        if (evidence.specSearches.length > 0) {
+            evidence.status = "search-only";
+        }
+        else if (sourceBinding) {
+            evidence.status = "source-bound";
+            evidence.summary = `已绑定 ${sourceBinding.sources.length} 个任务源文件和 ${sourceBinding.requirementIds.length} 个显式需求编号；未观察到 read 工具调用。`;
+        }
+        else if (skillInjection.skills.length > 0) {
+            evidence.status = "spec-injected";
+            evidence.summary =
+                "规范 skill 已注入但未观察到规范文件读取或知识库查询。";
+        }
+    }
+    sendJson(res, 200, evidence);
+}
+function contentTypeFor(pathname) {
+    const lower = pathname.toLowerCase();
+    if (lower.endsWith(".html"))
+        return "text/html; charset=utf-8";
+    if (lower.endsWith(".js") || lower.endsWith(".mjs")) {
+        return "text/javascript; charset=utf-8";
+    }
+    if (lower.endsWith(".css"))
+        return "text/css; charset=utf-8";
+    if (lower.endsWith(".json"))
+        return "application/json; charset=utf-8";
+    if (lower.endsWith(".svg"))
+        return "image/svg+xml";
+    if (lower.endsWith(".png"))
+        return "image/png";
+    if (lower.endsWith(".ico"))
+        return "image/x-icon";
+    if (lower.endsWith(".woff2"))
+        return "font/woff2";
+    return "application/octet-stream";
+}