@tea-agent/loop-agent 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-08-08
+
+### 重点更新
+
+- Observe 看板新增 DAG 执行轨迹视图，支持按初始执行、修复轮次和最终收敛分车道展开真实的调度执行过程
+- DAG 节点新增轻量执行历史摘要，在逻辑图卡片、节点表和 Inspector 中直观展示多次尝试与恢复记录
+- 统一执行轨迹与 Inspector 的业务文案为自然中文映射，主界面不再显示难以理解的裸英文状态标识
+- 优化 DAG 拓扑依赖边的路由算法，实现结构化避障正交路由，并恢复平滑的视觉线条样式
+
+### 新增
+
+- Observe DAG 详情新增执行轨迹视图，默认展示逻辑拓扑，支持键盘切换，点击轨迹卡片可联动 Inspector
+- 为 DAG 节点投影并展示轻量执行历史摘要，包含执行次数叙事及 Inspector 分次选择器
+- 新增纯函数模块统一执行轨迹与 Inspector 的业务文案中文映射，规范展示失败原因与状态转换
+- Console 与 Observe 共享统一的品牌 favicon，并支持通过同步脚本保持资源一致
+
+### 改进
+
+- DAG 拓扑依赖边采用结构化避障正交路由，支持长边避障与控制回环独立展示，提升复杂拓扑的可读性
+- 恢复相邻层级普通依赖边的平滑视觉样式，控制回环标签视觉更轻量，避免掩盖主链路
+- DAG 详情响应内嵌有界的执行轨迹投影，在历史证据缺失时安全降级并保持逻辑拓扑始终可用
+- 主 UI 业务术语优化，图卡与工具栏摘要改用自然的中文轮次描述，原始内部编号仅保留在诊断提示中
+
+### 修复
+
+- 修复 Console 与 Observe 未共享 favicon 的问题，现统一使用同一品牌资源并兼容嵌入模式
+- 修复 Observe 逻辑拓扑中同一行 DAG 边未能保持水平的问题，确保同逻辑行混合高度边正确展示
+- 修复执行轨迹车道归类错误，修正收敛开启时节点错误归入最终收敛道的问题，确保各节点按真实位置归类
+- 恢复 DAG Pi writer 节点的 bash 工具权限，同时保持只读节点无 bash 且 edit/write 仍受安全策略约束
+
 ## [0.30.0] - 2026-08-08
 
 ### 重点更新

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

@@ -12,7 +12,7 @@ import { isWriterEmptyDiffRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, W
 import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
 import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
 export const DAG_PI_READONLY_TOOLS = ["read", "grep", "find", "ls"];
-/** Bounded writer tools: no unrestricted bash; edit/write are policy-wrapped via SDK customTools. */
+/** Bounded writer tools include bash; edit/write remain policy-wrapped via SDK customTools. */
 export const DAG_PI_WRITE_TOOLS = [
     "read",
     "edit",
@@ -20,6 +20,7 @@ export const DAG_PI_WRITE_TOOLS = [
     "grep",
     "find",
     "ls",
+    "bash",
 ];
 export const DEFAULT_DAG_PI_PROVIDER = "wizard-local";
 const WRITER_OUTCOME_PROTOCOL_LINE = "IMPLEMENTATION_OUTCOME:";
@@ -132,7 +133,7 @@ export function resolveDagPiToolNames(task) {
         return [...DAG_PI_READONLY_TOOLS];
     const tools = [...DAG_PI_WRITE_TOOLS];
     // Pi SDK activates custom tools only when they are in this explicit list.
-    // Do not add a command capability to ordinary writers or read-only nodes.
+    // Command capabilities (playwright_cli) stay capability-gated; read-only nodes never get command tools.
     if (dagCommandPolicyAllows(task.commandPolicy, "playwright-cli")) {
         tools.push("playwright_cli");
     }

package/dist/worker/observability/dag-execution-trajectory.js

@@ -0,0 +1,591 @@
+/**
+ * Bounded execution-trajectory projection (Observe P1, AC-004/AC-006).
+ *
+ * Read-only: derives a compact storyboard of real scheduler executions
+ * (initial execution + convergence passes + final converged state) from
+ * run-owned state facts. The projection never embeds full stdout/stderr/
+ * assistant text or session messages — the detail API stays compact.
+ *
+ * Fact rules:
+ * - Archived `convergence.passHistory[].artifactRefs` project one occurrence
+ *   per executed node (pass 1 = 初始执行, later passes = 修复轮次 N).
+ * - `convergence.supersededFailures` mark the matching pass occurrence as
+ *   recovered/superseded while preserving the original ERROR status fact.
+ * - The convergence segment [segmentMinRank, segmentMaxRank] is derived from
+ *   archived convergence facts: chain node ids observed in passHistory refs /
+ *   supersededFailures, projected through state ranks. Live `state.nodes` are
+ *   classified by rank vs the segment: rank < segmentMin → base (@base),
+ *   rank > segmentMax → final (@pass-<effectiveCurrentPass>), in-segment →
+ *   projected by effectiveCurrentPass (pass=1 → base, pass>=2 →
+ *   convergence-pass). Live occurrences dedupe against the archived
+ *   occurrence for the same node+projected pass: only lightweight attempt
+ *   metadata (attempts/attemptCount, attemptRecovered, and missing
+ *   failureCategory/durationMs) is merged; the archived
+ *   status/semanticVerdict/recovery facts stay authoritative.
+ * - When the segment boundary is not derivable (no passHistory /
+ *   supersededFailures chain node ranks) or an individual live node lacks a
+ *   rank fact, the projection degrades to base classification with a
+ *   deterministic Chinese warning — live nodes are never faked as final.
+ * - `availability=partial` when an archived artifactRef lacks preserved path
+ *   facts (no disk existence probing per snapshot — evidence gap AC-006).
+ */
+import { readFile, stat } from "node:fs/promises";
+import { resolveDagRunArtifact } from "../observe/dag-run-artifacts.js";
+/** Hard cap on state.json size for a single trajectory read (bounded API). */
+const TRAJECTORY_STATE_MAX_BYTES = 32 * 1024 * 1024;
+const TRAJECTORY_MAX_OCCURRENCES = 300;
+const TRAJECTORY_MAX_WARNINGS = 20;
+/** Statuses that count as a real scheduler execution (D3: no PENDING/skip). */
+const EXECUTED_STATUSES = new Set([
+    "running",
+    "started",
+    "paused",
+    "finished",
+    "completed",
+    "succeeded",
+    "done",
+    "error",
+    "failed",
+    "partial_failed",
+    "partial-failed",
+    "superseded",
+]);
+const FAILURE_STATUSES = new Set([
+    "error",
+    "failed",
+    "partial_failed",
+    "partial-failed",
+    "interrupted",
+    "superseded",
+]);
+const REVIEW_NODE_IDS = new Set([
+    "initial-review-pi",
+    "initial-review-gate-shell",
+    "initial-review-pass-shell",
+    "review-pi",
+    "review-gate-shell",
+    "review-verdict-recovery-pi",
+]);
+function readString(value, key) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value[key];
+    return typeof raw === "string" && raw ? raw : undefined;
+}
+function readNumber(value, key) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value[key];
+    return typeof raw === "number" && Number.isFinite(raw) ? raw : undefined;
+}
+function readBoolean(value, key) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value[key];
+    return typeof raw === "boolean" ? raw : undefined;
+}
+function readArray(value, key) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [];
+    const raw = value[key];
+    return Array.isArray(raw) ? raw : [];
+}
+function parsePassRecord(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const record = raw;
+    const pass = readNumber(record, "pass");
+    if (pass === undefined || !Number.isFinite(pass) || pass < 1)
+        return null;
+    const refs = [];
+    for (const refRaw of readArray(record, "artifactRefs")) {
+        if (!refRaw || typeof refRaw !== "object" || Array.isArray(refRaw))
+            continue;
+        const ref = refRaw;
+        const nodeId = readString(ref, "nodeId");
+        if (!nodeId)
+            continue;
+        refs.push({
+            nodeId,
+            status: readString(ref, "status"),
+            failureCategory: readString(ref, "failureCategory"),
+            preservedNodeRecordPath: readString(ref, "preservedNodeRecordPath"),
+            preservedNodeDir: readString(ref, "preservedNodeDir"),
+        });
+    }
+    return {
+        pass,
+        reason: readString(record, "reason"),
+        reviewVerdict: readString(record, "reviewVerdict"),
+        hardVerifyStatus: readString(record, "hardVerifyStatus"),
+        artifactRefs: refs,
+    };
+}
+function parseSupersededFailure(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const record = raw;
+    const supersededRaw = readArray(record, "supersededBy");
+    return {
+        nodeId: readString(record, "nodeId"),
+        pass: readNumber(record, "pass"),
+        supersededBy: supersededRaw
+            .filter((entry) => typeof entry === "string")
+            .slice(0, TRAJECTORY_MAX_WARNINGS),
+        reason: readString(record, "reason"),
+    };
+}
+function refSemanticVerdict(nodeId, refStatus, passRecord) {
+    const normalized = (refStatus ?? "").toLowerCase();
+    if (FAILURE_STATUSES.has(normalized))
+        return "失败";
+    if (REVIEW_NODE_IDS.has(nodeId)) {
+        if (passRecord.reviewVerdict === "request-revision")
+            return "request-revision";
+        if (passRecord.reviewVerdict === "pass")
+            return "pass";
+    }
+    // hard-verify 失败语义判定只投影到 hard-verify-shell：仅当该 ref 自身技术
+    // status 非失败（FINISHED）而 pass 级 hardVerifyStatus 命中失败状态时附加；
+    // process-supervisor-pi / process-gate-shell 即使技术 FINISHED 也不再携带
+    // 该 verdict（只展示自身技术状态，AC-001/AC-002）。
+    if (nodeId === "hard-verify-shell" &&
+        passRecord.hardVerifyStatus &&
+        FAILURE_STATUSES.has(passRecord.hardVerifyStatus.toLowerCase())) {
+        return "hard-verify 失败";
+    }
+    return undefined;
+}
+function isExecutedStatus(status) {
+    return Boolean(status && EXECUTED_STATUSES.has(status.toLowerCase()));
+}
+/**
+ * Project the bounded execution trajectory from run state facts. Pure and
+ * deterministic; never throws on legacy or malformed shapes.
+ */
+export function projectDagExecutionTrajectory(state) {
+    const dagRunId = state.runId ?? "";
+    const occurrences = [];
+    const warnings = [];
+    const pushWarning = (message) => {
+        if (warnings.length < TRAJECTORY_MAX_WARNINGS)
+            warnings.push(message);
+    };
+    const convergence = state.convergence;
+    const convergenceEnabled = Boolean(readBoolean(convergence, "enabled"));
+    const currentPassRaw = readNumber(convergence, "currentPass");
+    const currentPass = currentPassRaw !== undefined && currentPassRaw >= 1
+        ? Math.floor(currentPassRaw)
+        : undefined;
+    const passRecords = [];
+    for (const raw of readArray(convergence, "passHistory")) {
+        const record = parsePassRecord(raw);
+        if (record)
+            passRecords.push(record);
+    }
+    passRecords.sort((a, b) => a.pass - b.pass);
+    const maxArchivedPass = passRecords.length > 0 ? passRecords[passRecords.length - 1].pass : 0;
+    const effectiveCurrentPass = currentPass ?? (convergenceEnabled ? Math.max(1, maxArchivedPass) : 0);
+    // Rank index for deterministic within-lane ordering of live nodes.
+    const rankIndex = new Map();
+    (state.ranks ?? []).forEach((rank, index) => {
+        if (!Array.isArray(rank))
+            return;
+        for (const nodeId of rank) {
+            if (typeof nodeId === "string" && !rankIndex.has(nodeId)) {
+                rankIndex.set(nodeId, index);
+            }
+        }
+    });
+    // Convergence segment boundary, derived from archived convergence facts:
+    // chain node ids observed in passHistory refs / supersededFailures whose
+    // rank is known. Live nodes below segmentMin → base, above segmentMax →
+    // final, inside → projected by effectiveCurrentPass.
+    const chainNodeIds = new Set();
+    for (const passRecord of passRecords) {
+        for (const ref of passRecord.artifactRefs) {
+            if (ref.nodeId)
+                chainNodeIds.add(ref.nodeId);
+        }
+    }
+    for (const raw of readArray(convergence, "supersededFailures")) {
+        const sup = parseSupersededFailure(raw);
+        if (sup.nodeId)
+            chainNodeIds.add(sup.nodeId);
+    }
+    let segmentMinRank;
+    let segmentMaxRank;
+    for (const nodeId of chainNodeIds) {
+        const rank = rankIndex.get(nodeId);
+        if (rank === undefined)
+            continue;
+        segmentMinRank =
+            segmentMinRank === undefined
+                ? rank
+                : Math.min(segmentMinRank, rank);
+        segmentMaxRank =
+            segmentMaxRank === undefined
+                ? rank
+                : Math.max(segmentMaxRank, rank);
+    }
+    const segmentDerivable = convergenceEnabled &&
+        chainNodeIds.size > 0 &&
+        segmentMinRank !== undefined &&
+        segmentMaxRank !== undefined;
+    if (convergenceEnabled && !segmentDerivable) {
+        pushWarning("convergence 段边界不可推导（缺少 passHistory/supersededFailures 链节点 rank），live 节点按初始执行归类");
+    }
+    // 1) Archived convergence pass occurrences.
+    for (const passRecord of passRecords) {
+        const pass = passRecord.pass;
+        const scope = pass === 1 ? "base" : "convergence-pass";
+        passRecord.artifactRefs.forEach((ref, index) => {
+            if (!isExecutedStatus(ref.status))
+                return;
+            const preserved = Boolean(ref.preservedNodeRecordPath || ref.preservedNodeDir);
+            const occurrence = {
+                executionId: `${ref.nodeId}@pass-${pass}`,
+                nodeId: ref.nodeId,
+                pass,
+                scope,
+                sequence: index,
+                status: ref.status ?? "UNKNOWN",
+                availability: preserved ? "complete" : "partial",
+                ...(ref.failureCategory
+                    ? { failureCategory: ref.failureCategory }
+                    : {}),
+                ...(() => {
+                    const verdict = refSemanticVerdict(ref.nodeId, ref.status, passRecord);
+                    return verdict ? { semanticVerdict: verdict } : {};
+                })(),
+                ...(passRecord.reason ? { nextReason: passRecord.reason } : {}),
+            };
+            if (!preserved) {
+                pushWarning(`pass ${pass} 节点 ${ref.nodeId} 历史证据不完整（缺少 preserved 路径事实）`);
+            }
+            occurrences.push(occurrence);
+            if (occurrences.length >= TRAJECTORY_MAX_OCCURRENCES) {
+                pushWarning(`执行轨迹已截断至 ${TRAJECTORY_MAX_OCCURRENCES} 条 occurrence（容量上限）`);
+                return;
+            }
+        });
+        if (occurrences.length >= TRAJECTORY_MAX_OCCURRENCES) {
+            pushWarning(`执行轨迹已截断至 ${TRAJECTORY_MAX_OCCURRENCES} 条 occurrence（容量上限）`);
+            break;
+        }
+    }
+    // 2) Superseded historical failures: mark matching occurrences; preserve
+    // the ERROR fact even when the archived artifactRef is missing.
+    for (const raw of readArray(convergence, "supersededFailures")) {
+        const sup = parseSupersededFailure(raw);
+        if (!sup.nodeId || sup.pass === undefined || sup.pass < 1)
+            continue;
+        const match = occurrences.find((o) => o.nodeId === sup.nodeId && o.pass === sup.pass);
+        if (match) {
+            match.recovered = true;
+            match.supersededBy = sup.supersededBy;
+            continue;
+        }
+        occurrences.push({
+            executionId: `${sup.nodeId}@pass-${sup.pass}`,
+            nodeId: sup.nodeId,
+            pass: sup.pass,
+            scope: sup.pass === 1 ? "base" : "convergence-pass",
+            sequence: 0,
+            status: "ERROR",
+            recovered: true,
+            supersededBy: sup.supersededBy,
+            availability: "partial",
+            ...(sup.reason ? { semanticVerdict: sup.reason } : {}),
+        });
+        pushWarning(`节点 ${sup.nodeId} pass ${sup.pass} 历史失败已覆盖，但归档 evidence 不完整`);
+        if (occurrences.length >= TRAJECTORY_MAX_OCCURRENCES) {
+            pushWarning(`执行轨迹已截断至 ${TRAJECTORY_MAX_OCCURRENCES} 条 occurrence（容量上限）`);
+            break;
+        }
+    }
+    // 3) Live node records → lane by rank vs the convergence segment:
+    // rank < segmentMin → base (@base), in-segment → projected by
+    // effectiveCurrentPass (pass=1 → base, pass>=2 → convergence-pass),
+    // rank > segmentMax → final (@pass-<effectiveCurrentPass>). Degradation:
+    // convergence enabled without a derivable segment boundary or without a
+    // node rank fact degrades to base classification (never faked final).
+    // Attempt-recovered nodes keep their recovered flag.
+    const nodes = state.nodes ?? {};
+    const liveEntries = Object.entries(nodes).filter(([, raw]) => raw && typeof raw === "object" && !Array.isArray(raw));
+    liveEntries.sort((a, b) => {
+        const ra = rankIndex.get(a[0]) ?? Number.MAX_SAFE_INTEGER;
+        const rb = rankIndex.get(b[0]) ?? Number.MAX_SAFE_INTEGER;
+        if (ra !== rb)
+            return ra - rb;
+        return a[0].localeCompare(b[0]);
+    });
+    const projectedPass = convergenceEnabled
+        ? Math.max(1, effectiveCurrentPass ?? 1)
+        : 1;
+    for (const [nodeId, raw] of liveEntries) {
+        const record = raw;
+        const status = readString(record, "status");
+        if (!isExecutedStatus(status))
+            continue;
+        const rank = rankIndex.get(nodeId);
+        let scope;
+        let pass;
+        let executionId;
+        if (!convergenceEnabled) {
+            scope = "base";
+            pass = null;
+            executionId = `${nodeId}@base`;
+        }
+        else if (!segmentDerivable) {
+            scope = "base";
+            pass = null;
+            executionId = `${nodeId}@base`;
+        }
+        else if (rank === undefined) {
+            scope = "base";
+            pass = null;
+            executionId = `${nodeId}@base`;
+            pushWarning(`节点 ${nodeId} 缺少 rank 事实，按初始执行归类（不伪装最终收敛）`);
+        }
+        else if (rank < segmentMinRank) {
+            scope = "base";
+            pass = null;
+            executionId = `${nodeId}@base`;
+        }
+        else if (rank > segmentMaxRank) {
+            scope = "final";
+            pass = projectedPass;
+            executionId = `${nodeId}@pass-${projectedPass}`;
+        }
+        else if (projectedPass <= 1) {
+            scope = "base";
+            pass = 1;
+            executionId = `${nodeId}@pass-1`;
+        }
+        else {
+            scope = "convergence-pass";
+            pass = projectedPass;
+            executionId = `${nodeId}@pass-${projectedPass}`;
+        }
+        // Lightweight live attempt metadata — merged into the archived
+        // occurrence on a dedupe hit (AC-001), attached to the live
+        // occurrence otherwise.
+        const attemptsRaw = readArray(record, "attempts");
+        const attempts = [];
+        for (const attemptRaw of attemptsRaw) {
+            if (!attemptRaw ||
+                typeof attemptRaw !== "object" ||
+                Array.isArray(attemptRaw)) {
+                continue;
+            }
+            const attemptRecord = attemptRaw;
+            const attempt = readNumber(attemptRecord, "attempt");
+            if (attempt === undefined || attempt < 1)
+                continue;
+            const ok = readBoolean(attemptRecord, "ok");
+            if (ok === undefined)
+                continue;
+            attempts.push({
+                attempt: Math.floor(attempt),
+                status: ok ? "success" : "failure",
+                ...(readString(attemptRecord, "failureCategory")
+                    ? { failureCategory: readString(attemptRecord, "failureCategory") }
+                    : {}),
+                ...(readNumber(attemptRecord, "durationMs") !== undefined
+                    ? { durationMs: readNumber(attemptRecord, "durationMs") }
+                    : {}),
+            });
+        }
+        // 合并后的 attempts 按 attempt 升序（确定性输出，AC-001）。
+        attempts.sort((a, b) => a.attempt - b.attempt);
+        const attemptRecovered = attempts.length > 1 &&
+            attempts[0].status === "failure" &&
+            attempts[attempts.length - 1].status === "success";
+        const recovered = attemptRecovered || (status ?? "").toLowerCase() === "superseded";
+        if (pass !== null) {
+            const archived = occurrences.find((o) => o.nodeId === nodeId && o.pass === pass);
+            if (archived) {
+                // 去重合并（dedupe key: nodeId + projected pass）：归档 pass record
+                // 权威，只合并轻量 attempts 元数据；归档 status/semanticVerdict/
+                // recovered/supersededBy 原样保留（AC-001）。
+                if (attempts.length > 0) {
+                    archived.attemptCount = attempts.length;
+                    archived.attempts = attempts;
+                }
+                // live 首败末成派生的 attemptRecovered 仅当归档 occurrence 无
+                // recovery 事实（recovered 非 true 且 supersededBy 为空）时附加
+                // recovered: true；绝不写入 supersededBy（AC-002）。
+                if (attemptRecovered &&
+                    archived.recovered !== true &&
+                    !(archived.supersededBy && archived.supersededBy.length > 0)) {
+                    archived.recovered = true;
+                }
+                // live failureCategory/durationMs 仅在归档缺失时补充（AC-001）。
+                if (archived.failureCategory === undefined) {
+                    const liveFailureCategory = readString(record, "failureCategory");
+                    if (liveFailureCategory) {
+                        archived.failureCategory = liveFailureCategory;
+                    }
+                }
+                if (archived.durationMs === undefined) {
+                    const liveDurationMs = readNumber(record, "durationMs");
+                    if (liveDurationMs !== undefined) {
+                        archived.durationMs = liveDurationMs;
+                    }
+                }
+                continue;
+            }
+        }
+        const decisionEnvelope = record
+            .decisionEnvelope;
+        const decisionVerdict = decisionEnvelope &&
+            typeof decisionEnvelope === "object" &&
+            !Array.isArray(decisionEnvelope)
+            ? readString(decisionEnvelope, "decision")
+            : undefined;
+        occurrences.push({
+            executionId,
+            nodeId,
+            pass,
+            scope,
+            sequence: occurrences.length,
+            status: status,
+            availability: "complete",
+            ...(recovered ? { recovered: true } : {}),
+            ...(attempts.length > 0
+                ? {
+                    attemptCount: attempts.length,
+                    attempts,
+                }
+                : {}),
+            ...(decisionVerdict ? { semanticVerdict: decisionVerdict } : {}),
+            ...(readString(record, "failureCategory")
+                ? { failureCategory: readString(record, "failureCategory") }
+                : {}),
+            ...(readNumber(record, "durationMs") !== undefined
+                ? { durationMs: readNumber(record, "durationMs") }
+                : {}),
+        });
+        if (occurrences.length >= TRAJECTORY_MAX_OCCURRENCES) {
+            pushWarning(`执行轨迹已截断至 ${TRAJECTORY_MAX_OCCURRENCES} 条 occurrence（容量上限）`);
+            break;
+        }
+    }
+    // Deterministic lane order: base(0) → convergence pass N(N) → final(last);
+    // within a lane rankIndex ascending (unknown rank at lane end), then
+    // stable nodeId tiebreak, then executionId tiebreak for same-node
+    // occurrences (archived pass-N refs and live @base occurrences can share
+    // a nodeId inside the base lane).
+    const laneOrder = (occurrence) => {
+        if (occurrence.scope === "final")
+            return Number.MAX_SAFE_INTEGER;
+        if (occurrence.scope === "base")
+            return 0;
+        return occurrence.pass ?? 0;
+    };
+    occurrences.sort((a, b) => {
+        const la = laneOrder(a);
+        const lb = laneOrder(b);
+        if (la !== lb)
+            return la - lb;
+        const ra = rankIndex.get(a.nodeId) ?? Number.MAX_SAFE_INTEGER;
+        const rb = rankIndex.get(b.nodeId) ?? Number.MAX_SAFE_INTEGER;
+        if (ra !== rb)
+            return ra - rb;
+        const nodeCompare = a.nodeId.localeCompare(b.nodeId);
+        if (nodeCompare !== 0)
+            return nodeCompare;
+        return a.executionId.localeCompare(b.executionId);
+    });
+    // Renumber within-lane sequence after sorting.
+    const laneSeq = new Map();
+    for (const occurrence of occurrences) {
+        const laneKey = occurrence.scope === "final"
+            ? "final"
+            : occurrence.scope === "base"
+                ? "base"
+                : `pass-${occurrence.pass}`;
+        const next = (laneSeq.get(laneKey) ?? 0) + 1;
+        laneSeq.set(laneKey, next);
+        occurrence.sequence = next - 1;
+    }
+    return {
+        dagRunId,
+        occurrences,
+        warnings,
+    };
+}
+/**
+ * Load + project the execution trajectory for one DAG run. Returns null when
+ * no run-owned state.json exists (legacy/event-only runs → UI empty state).
+ * Never throws: projection failures degrade to a projectionError trajectory
+ * so the logical topology keeps rendering (AC-006).
+ */
+export async function loadDagRunExecutionTrajectory(repoRoot, dagRunId) {
+    try {
+        const resolved = resolveDagRunArtifact(repoRoot, dagRunId, ["state.json"]);
+        if (!resolved.ok)
+            return null;
+        const stateInfo = await stat(resolved.result.absolutePath);
+        if (stateInfo.size > TRAJECTORY_STATE_MAX_BYTES) {
+            return {
+                dagRunId,
+                occurrences: [],
+                warnings: [
+                    `state.json 超出 ${TRAJECTORY_STATE_MAX_BYTES} 字节读取上限，执行轨迹暂不可用`,
+                ],
+                projectionError: true,
+            };
+        }
+        const handle = await readFile(resolved.result.absolutePath);
+        let parsed;
+        try {
+            parsed = JSON.parse(handle.toString("utf-8"));
+        }
+        catch {
+            return {
+                dagRunId,
+                occurrences: [],
+                warnings: ["state.json 解析失败，执行历史暂不可用"],
+                projectionError: true,
+            };
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {
+                dagRunId,
+                occurrences: [],
+                warnings: ["state.json 结构异常，执行历史暂不可用"],
+                projectionError: true,
+            };
+        }
+        const state = parsed;
+        const convergenceRaw = state.convergence;
+        const input = {
+            runId: dagRunId,
+            status: readString(state, "status"),
+            ranks: Array.isArray(state.ranks)
+                ? state.ranks
+                : undefined,
+            nodes: state.nodes &&
+                typeof state.nodes === "object" &&
+                !Array.isArray(state.nodes)
+                ? state.nodes
+                : undefined,
+            convergence: convergenceRaw &&
+                typeof convergenceRaw === "object" &&
+                !Array.isArray(convergenceRaw)
+                ? convergenceRaw
+                : undefined,
+        };
+        return projectDagExecutionTrajectory(input);
+    }
+    catch {
+        return {
+            dagRunId,
+            occurrences: [],
+            warnings: ["执行历史投影失败"],
+            projectionError: true,
+        };
+    }
+}