@tea-agent/loop-agent 0.26.1 → 0.26.3

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

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { constants, createReadStream } from "node:fs";
-import { access, lstat, readlink } from "node:fs/promises";
+import { access, lstat, readlink, unlink } from "node:fs/promises";
 import path from "node:path";
 import { pathMatchesPattern } from "../shared/git-progress.js";
 async function sha256File(filePath) {
@@ -58,8 +58,7 @@ export async function snapshotGitStatusPathFingerprints(cwd, status) {
     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)) {
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
             return [filePath, "outside-repository"];
         }
         try {
@@ -72,10 +71,7 @@ export async function snapshotGitStatusPathFingerprints(cwd, status) {
                 ];
             }
             if (info.isFile()) {
-                return [
-                    filePath,
-                    `file:${await sha256File(candidate)}`,
-                ];
+                return [filePath, `file:${await sha256File(candidate)}`];
             }
             return [
                 filePath,
@@ -101,7 +97,8 @@ export function isEphemeralToolCachePath(filePath) {
     const normalized = normalizePath(filePath);
     if (!normalized)
         return false;
-    if (normalized === ".pytest_cache" || normalized.startsWith(".pytest_cache/")) {
+    if (normalized === ".pytest_cache" ||
+        normalized.startsWith(".pytest_cache/")) {
         return true;
     }
     if (normalized === ".mypy_cache" || normalized.startsWith(".mypy_cache/")) {
@@ -112,7 +109,8 @@ export function isEphemeralToolCachePath(filePath) {
     }
     // playwright-cli default session dumps (console/page/network) under repo cwd.
     // Real browser case evidence must still be written under testcase/** explicitly.
-    if (normalized === ".playwright-cli" || normalized.startsWith(".playwright-cli/")) {
+    if (normalized === ".playwright-cli" ||
+        normalized.startsWith(".playwright-cli/")) {
         return true;
     }
     if (normalized === ".coverage" || normalized.startsWith(".coverage.")) {
@@ -164,6 +162,136 @@ export function validateShellWriteGuard(input) {
     }
     return { ok: violations.length === 0, violations };
 }
+/** SHA-256 of an empty file, retained for fingerprint tests and diagnostics. */
+export const EMPTY_FILE_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/**
+ * A mistaken Git Bash `> nul` / `2> nul` target may contain bounded command
+ * output. Keep the recovery cap small enough that a material product artifact
+ * cannot be silently discarded while covering ordinary tool diagnostics.
+ */
+export const MAX_BENIGN_ROOT_NUL_BYTES = 1024 * 1024;
+/**
+ * Decide whether the exact repository-root `nul` entry is a benign tool
+ * artifact that may be removed. Every proof must hold: absent from the before
+ * snapshot, brand-new untracked (`??`) in the after snapshot, outside the
+ * writer's declared boundary, and currently inspected as a regular file no
+ * larger than {@link MAX_BENIGN_ROOT_NUL_BYTES}. Nested keys such as `src/nul`
+ * never match the exact root key; missing or unreadable facts stay fail-closed.
+ */
+export function evaluateRootNulCandidate(input) {
+    if (!input.afterSnapshot.has("nul")) {
+        return { action: "skip", candidatePath: "nul", reason: "nested-path" };
+    }
+    if (input.beforeSnapshot.has("nul")) {
+        return { action: "skip", candidatePath: "nul", reason: "pre-existing" };
+    }
+    if (input.afterSnapshot.get("nul") !== "??") {
+        return {
+            action: "skip",
+            candidatePath: "nul",
+            reason: "not-new-untracked",
+        };
+    }
+    if (input.candidateAuthorized === true) {
+        return {
+            action: "skip",
+            candidatePath: "nul",
+            reason: "authorized-by-write-boundary",
+        };
+    }
+    const fingerprint = input.afterPathFingerprints?.get("nul");
+    if (!fingerprint || fingerprint.startsWith("unreadable:")) {
+        return {
+            action: "skip",
+            candidatePath: "nul",
+            reason: "unreadable",
+        };
+    }
+    if (input.candidateIsRegularFile === false ||
+        !fingerprint.startsWith("file:")) {
+        return {
+            action: "skip",
+            candidatePath: "nul",
+            reason: "not-regular-file",
+        };
+    }
+    const observedSizeBytes = input.candidateSizeBytes ??
+        (fingerprint === `file:${EMPTY_FILE_SHA256}` ? 0 : undefined);
+    if (observedSizeBytes === undefined ||
+        !Number.isSafeInteger(observedSizeBytes) ||
+        observedSizeBytes < 0) {
+        return { action: "skip", candidatePath: "nul", reason: "unreadable" };
+    }
+    if (observedSizeBytes > MAX_BENIGN_ROOT_NUL_BYTES) {
+        return { action: "skip", candidatePath: "nul", reason: "too-large" };
+    }
+    return {
+        action: "remove",
+        candidatePath: "nul",
+        reason: "new-untracked-bounded-regular-file",
+        observedSizeBytes,
+    };
+}
+/**
+ * Remove a benign repository-root `nul` artifact with the Node file API only.
+ * On win32 libuv addresses the literal name through the `\\?\` NT path form, so
+ * a file literally named `nul` can be stat/unlink'ed precisely without shell
+ * redirection or `rm`. Non-matching candidates are left untouched; unlink
+ * failures surface as a bounded `failed` result so callers stay fail-closed.
+ */
+export async function recoverRootNulArtifact(input) {
+    let candidateSizeBytes;
+    let candidateIsRegularFile;
+    if (input.afterSnapshot.has("nul") &&
+        !input.beforeSnapshot.has("nul") &&
+        input.afterSnapshot.get("nul") === "??" &&
+        input.candidateAuthorized !== true) {
+        try {
+            const info = await lstat(path.resolve(input.rootCwd, "nul"));
+            candidateSizeBytes = info.size;
+            candidateIsRegularFile = info.isFile() && !info.isSymbolicLink();
+        }
+        catch {
+            candidateIsRegularFile = undefined;
+        }
+    }
+    const evaluation = evaluateRootNulCandidate({
+        beforeSnapshot: input.beforeSnapshot,
+        afterSnapshot: input.afterSnapshot,
+        afterPathFingerprints: input.afterPathFingerprints,
+        candidateSizeBytes,
+        candidateIsRegularFile,
+        candidateAuthorized: input.candidateAuthorized,
+    });
+    if (evaluation.action === "skip") {
+        return {
+            action: "skipped",
+            candidatePath: "nul",
+            reason: evaluation.reason,
+            ...(candidateSizeBytes === undefined ? {} : { observedSizeBytes: candidateSizeBytes }),
+        };
+    }
+    const removeFile = input.removeFile ?? ((filePath) => unlink(filePath));
+    try {
+        await removeFile(path.resolve(input.rootCwd, "nul"));
+        return {
+            action: "removed",
+            candidatePath: "nul",
+            reason: evaluation.reason,
+            observedSizeBytes: evaluation.observedSizeBytes,
+            removedAt: new Date().toISOString(),
+        };
+    }
+    catch (error) {
+        return {
+            action: "failed",
+            candidatePath: "nul",
+            reason: "removal-failed",
+            observedSizeBytes: evaluation.observedSizeBytes,
+            errorDetail: boundedErrorDetail(error),
+        };
+    }
+}
 export class GitStatusUnavailableError extends Error {
     diagnostics;
     constructor(input) {
@@ -179,7 +307,8 @@ export class GitStatusUnavailableError extends Error {
             cwd: path.resolve(input.cwd),
             platform: input.platform ?? process.platform,
             executableCandidates: input.executableCandidates ?? [],
-            requiredWindowsEnvironment: input.requiredWindowsEnvironment ?? requiredWindowsEnvironment(process.env),
+            requiredWindowsEnvironment: input.requiredWindowsEnvironment ??
+                requiredWindowsEnvironment(process.env),
             attempts: input.attempts,
         };
     }
@@ -216,11 +345,15 @@ function formatWindowsExitCode(exitCode) {
     return `0x${(exitCode >>> 0).toString(16).padStart(8, "0").toUpperCase()}`;
 }
 function isWindowsDllInitializationFailure(platform, exitCode) {
-    return platform === "win32" && exitCode !== undefined && (exitCode >>> 0) === 0xc0000142;
+    return (platform === "win32" &&
+        exitCode !== undefined &&
+        exitCode >>> 0 === 0xc0000142);
 }
 function boundedErrorDetail(error) {
     const detail = error instanceof Error ? error.message : String(error);
-    return detail.length <= 1000 ? detail : `${detail.slice(0, 1000)}...[truncated]`;
+    return detail.length <= 1000
+        ? detail
+        : `${detail.slice(0, 1000)}...[truncated]`;
 }
 export function deriveSameInstallationGitCandidates(primary) {
     const normalized = path.win32.normalize(primary);

package/dist/task/config-types.js

@@ -104,6 +104,12 @@ const taskConfigObjectSchema = z.object({
     referenceMaxFilesPerRepo: z.number().int().positive().optional(),
     referenceMaxTotalFiles: z.number().int().positive().optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
+    /**
+     * Coarse repository roots used only by the frontend preflight scout. Before
+     * DAG generation, the scout must resolve these into the narrower
+     * `allowedPaths` consumed by writer nodes.
+     */
+    allowedRoots: z.array(z.string()).optional(),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     hardConstraints: z.array(z.string()).optional().default([]),
     autoCommitAfterVerify: z.boolean().optional().default(true),

package/dist/task/contract/constants.js

@@ -13,6 +13,7 @@ export const MANAGED_TASK_CONFIG_FIELDS = [
     "taskKind",
     "featureId",
     "allowedPaths",
+    "allowedRoots",
     "forbiddenPaths",
     "hardConstraints",
     "verifyCommands",

package/dist/task/contract/project.js

@@ -107,6 +107,11 @@ export function projectConstraintsMarkdown(draft) {
             lines.push(`- ${item}`);
         }
     }
+    if (draft.constraints.allowedRoots?.length) {
+        lines.push("", "## Allowed roots (preflight only)", "");
+        for (const item of draft.constraints.allowedRoots)
+            lines.push(`- ${item}`);
+    }
     lines.push("", "## Expected verification", "");
     if (draft.verification.commands.length === 0) {
         lines.push("- (none)");
@@ -148,6 +153,9 @@ export function mergeManagedTaskConfigFields(existing, draft) {
         title: draft.title,
         taskKind: draft.taskKind,
         allowedPaths: canonicalizePathArray(draft.constraints.allowedPaths),
+        ...(draft.constraints.allowedRoots !== undefined
+            ? { allowedRoots: canonicalizePathArray(draft.constraints.allowedRoots) }
+            : {}),
         forbiddenPaths: canonicalizePathArray(draft.constraints.forbiddenPaths),
         hardConstraints,
         verifyCommands: draft.verification.commands.map((cmd) => ({

package/dist/task/contract/schema.js

@@ -23,6 +23,7 @@ export const taskContractDraftConstraintsSchema = z
     .object({
     invariants: z.array(z.string()),
     allowedPaths: z.array(z.string()),
+    allowedRoots: z.array(z.string()).optional(),
     forbiddenPaths: z.array(z.string()),
     protectedUserChanges: z.array(z.string()).optional(),
     expectedVerification: z.array(z.string()).optional(),

package/dist/task/frontend-preflight.js

@@ -0,0 +1,131 @@
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { executePiStep } from "../executors/pi-executor.js";
+import { resolveDagPiModelConfig } from "../executors/dag-pi-executor.js";
+import { writeJsonAtomic } from "../infrastructure/harness/atomic-write.js";
+import { pathMatchesPattern } from "../shared/git-progress.js";
+import { loadHarnessManifest } from "../governance/harness.js";
+import { resolveExecutorModelMatrices } from "../executors/model-routing.js";
+const frontendScopeSchema = z.object({
+    schemaVersion: z.literal(1),
+    entrypoint: z.string().min(1),
+    implementationPaths: z.array(z.string().min(1)).min(1),
+    testPaths: z.array(z.string().min(1)).min(1),
+    dataSource: z.string().min(1),
+});
+function isSafeRepositoryPath(value) {
+    return value.length > 0 &&
+        !path.isAbsolute(value) &&
+        !value.includes("\\") &&
+        !value.split("/").includes("..");
+}
+function parseScope(text) {
+    const candidates = [];
+    for (let start = text.indexOf("{"); start >= 0; start = text.indexOf("{", start + 1)) {
+        let depth = 0;
+        let quoted = false;
+        let escaped = false;
+        for (let index = start; index < text.length; index += 1) {
+            const char = text[index];
+            if (quoted) {
+                if (escaped)
+                    escaped = false;
+                else if (char === "\\")
+                    escaped = true;
+                else if (char === '"')
+                    quoted = false;
+                continue;
+            }
+            if (char === '"')
+                quoted = true;
+            else if (char === "{")
+                depth += 1;
+            else if (char === "}" && --depth === 0) {
+                try {
+                    candidates.push(JSON.parse(text.slice(start, index + 1)));
+                }
+                catch { /* continue */ }
+                break;
+            }
+        }
+    }
+    if (candidates.length === 0)
+        throw new Error("frontend preflight output contains no JSON object");
+    const parsed = frontendScopeSchema.parse(candidates.at(-1));
+    for (const candidate of [
+        parsed.entrypoint,
+        ...parsed.implementationPaths,
+        ...parsed.testPaths,
+    ]) {
+        if (!isSafeRepositoryPath(candidate)) {
+            throw new Error(`unsafe frontend preflight path: ${candidate}`);
+        }
+    }
+    return parsed;
+}
+function ensureWithinRoots(scope, roots) {
+    const candidates = [
+        scope.entrypoint,
+        ...scope.implementationPaths,
+        ...scope.testPaths,
+    ];
+    const outside = candidates.filter((candidate) => !roots.some((root) => pathMatchesPattern(candidate, root)));
+    if (outside.length > 0) {
+        throw new Error(`frontend preflight discovered paths outside allowedRoots: ${outside.join(", ")}`);
+    }
+}
+export async function runFrontendPreflight(input) {
+    if (input.taskConfig.taskKind !== "frontend-implementation" ||
+        (input.taskConfig.allowedRoots?.length ?? 0) === 0) {
+        return undefined;
+    }
+    const requirementPath = path.join(input.repoRoot, ".harness", "tasks", input.taskId, "source", "需求.md");
+    const requirement = await readFile(requirementPath, "utf8");
+    const manifest = await loadHarnessManifest(input.repoRoot);
+    const models = resolveExecutorModelMatrices(manifest);
+    const model = models.pi.MED;
+    const prompt = [
+        "You are a read-only frontend preflight scout. Inspect the target repository before its implementation DAG is generated.",
+        "Locate the existing UI surface that satisfies the requirement. Do not invent a new page when an existing surface exists.",
+        `Allowed roots: ${input.taskConfig.allowedRoots.join(", ")}`,
+        "Return exactly one JSON object and no Markdown or prose:",
+        '{"schemaVersion":1,"entrypoint":"relative/path","implementationPaths":["relative/glob-or-file"],"testPaths":["relative/glob-or-file"],"dataSource":"existing store/API/module"}',
+        "Every path must be repository-relative POSIX, must be inside allowed roots, and implementationPaths/testPaths must be the narrowest directories or files that own the existing behavior.",
+        "Requirement:",
+        requirement,
+    ].join("\n\n");
+    const result = await executePiStep({
+        attachedFiles: [requirementPath],
+        modelConfig: resolveDagPiModelConfig(model),
+        prompt,
+        repoRoot: input.repoRoot,
+        step: "analyze",
+        toolNames: ["read", "grep", "find", "ls"],
+        userMessage: "Perform the frontend preflight scout and return the required JSON.",
+        validateOutput: (assistantText) => {
+            try {
+                const scope = parseScope(assistantText);
+                ensureWithinRoots(scope, input.taskConfig.allowedRoots);
+                return [];
+            }
+            catch (error) {
+                return [error instanceof Error ? error.message : String(error)];
+            }
+        },
+    });
+    if (!result.ok) {
+        throw new Error(`frontend preflight failed: ${result.failureCategory}: ${result.stderr || result.assistantText}`);
+    }
+    const scope = parseScope(result.assistantText);
+    ensureWithinRoots(scope, input.taskConfig.allowedRoots);
+    const preflightDir = path.join(input.repoRoot, ".harness", "tasks", input.taskId, "preflight");
+    await mkdir(preflightDir, { recursive: true });
+    await writeJsonAtomic(path.join(preflightDir, "frontend-scope.json"), {
+        ...scope,
+        resolvedAt: new Date().toISOString(),
+        allowedRoots: input.taskConfig.allowedRoots,
+        model,
+    });
+    return scope;
+}

package/dist/task/runtime.js

@@ -201,10 +201,8 @@ export function parseTaskConfigForRuntime(rawConfig) {
     }
     return parsed;
 }
-export function deriveMaxFixLoops(complexity) {
-    if (complexity === 'small')
-        return 2;
-    return 3;
+export function deriveMaxFixLoops(_complexity) {
+    return 2;
 }
 export async function listTaskSourceFiles(repoRoot, taskId) {
     return listFilesRecursive(getTaskPaths(repoRoot, taskId).sourceDir);

package/dist/task/source-prepare/build-draft.js

@@ -65,6 +65,13 @@ function resolveAllowedPaths(input) {
         return n.ok ? n.value : raw.trim();
     });
 }
+function resolveAllowedRoots(input) {
+    const roots = input.flags.allowedRoots ?? input.baseDraft?.constraints.allowedRoots ?? input.existing?.allowedRoots;
+    return roots === undefined ? undefined : (cleanStringList(roots) ?? []).map((raw) => {
+        const normalized = normalizePreparePath(raw);
+        return normalized.ok ? normalized.value : raw.trim();
+    });
+}
 function resolveVerifyCommands(input) {
     if (input.flags.verifyCommands !== undefined) {
         return input.flags.verifyCommands.map((cmd) => ({
@@ -122,6 +129,7 @@ export function buildPrepareDraft(input) {
         baseDraft,
         existing: existingTaskConfig,
     });
+    const allowedRoots = resolveAllowedRoots({ flags, baseDraft, existing: existingTaskConfig });
     // D12: protected defaults always merge unless explicitly disabled.
     // Explicit --forbidden-path appends; does not replace defaults.
     const finalForbidden = mergeForbiddenPaths({
@@ -175,6 +183,7 @@ export function buildPrepareDraft(input) {
             forbiddenPaths: pathAssessment.forbidden.length > 0
                 ? pathAssessment.forbidden
                 : dedupeStable(finalForbidden),
+            ...(allowedRoots !== undefined ? { allowedRoots: dedupeStable(allowedRoots) } : {}),
         },
         verification: {
             commands: verifyCommands

package/dist/task/source-prepare/completeness.js

@@ -81,7 +81,7 @@ export function listPrepareGaps(input) {
             });
         }
     }
-    if (draft.constraints.allowedPaths.length === 0) {
+    if (draft.constraints.allowedPaths.length === 0 && !(draft.taskKind === "frontend-implementation" && (draft.constraints.allowedRoots?.length ?? 0) > 0)) {
         gaps.push({
             code: "EMPTY_ALLOWED_PATHS",
             level: "blocking",

package/dist/worker/observability/read-model.js

@@ -1287,6 +1287,12 @@ function mergeDagRun(existing, incoming) {
         ...(ranks && ranks.length > 0 ? { ranks } : {}),
         nodes: mergeDagNodes(existing.nodes, incoming.nodes),
         edges: incoming.edges.length > 0 ? incoming.edges : existing.edges,
+        ...((incoming.controlEdges ?? existing.controlEdges)
+            ? { controlEdges: incoming.controlEdges ?? existing.controlEdges }
+            : {}),
+        ...((incoming.convergence ?? existing.convergence)
+            ? { convergence: incoming.convergence ?? existing.convergence }
+            : {}),
         ...((incoming.dagPath ?? existing.dagPath)
             ? { dagPath: incoming.dagPath ?? existing.dagPath }
             : {}),
@@ -1321,6 +1327,10 @@ function mergeDagNode(existing, incoming) {
         finishedAt: incoming.finishedAt ?? existing.finishedAt,
         outputPreview: incoming.outputPreview ?? existing.outputPreview,
         errorPreview: incoming.errorPreview ?? existing.errorPreview,
+        attemptCount: incoming.attemptCount ?? existing.attemptCount,
+        failureCategory: incoming.failureCategory ?? existing.failureCategory,
+        originKind: incoming.originKind ?? existing.originKind,
+        passes: incoming.passes ?? existing.passes,
     };
 }
 function computeDurationMs(startedAt, finishedAt) {
@@ -1569,6 +1579,9 @@ async function parseDagStateFile(statePath, now) {
         const nodes = parseDagNodes(parsed, rankByNode, modelByNode);
         const edges = await parseDagEdges(runSpecPath, nodes);
         const state = parsed;
+        const controlEdges = await deriveControlLoopEdges(runSpecPath, nodes, state);
+        const convergence = projectConvergenceSummary(state);
+        applyNodePasses(nodes, state);
         const liveness = assessDagRunLiveness({ state, now });
         const effectiveStatus = lifecycle
             ? deriveDagRunEffectiveStatus({
@@ -1647,6 +1660,8 @@ async function parseDagStateFile(statePath, now) {
             ...(ranks.length > 0 ? { ranks } : {}),
             nodes,
             edges,
+            ...(controlEdges.length > 0 ? { controlEdges } : {}),
+            ...(convergence ? { convergence } : {}),
             dagPath: runDir,
             ...(continuation ? { continuation } : {}),
             ...(backendTest ? { backendTest } : {}),
@@ -1683,6 +1698,125 @@ async function parseDagEdges(runPath, nodes) {
     }
     return [...edges.values()].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
 }
+/**
+ * Derive presentation-only control-loop edges from the run spec's convergence
+ * chain. When the chain contains both `review-gate-shell` and `repair-pi`, the
+ * bounded repair-reverify-review loop exists at runtime and Observe renders it
+ * as a dashed feedback loop. The derived edge is never merged into `edges` or
+ * `ranks`, so DAG topological layout stays acyclic.
+ */
+async function deriveControlLoopEdges(runPath, nodes, state) {
+    const runtimeConvergence = state.convergence;
+    if (!runtimeConvergence?.enabled ||
+        runtimeConvergence.terminalReason === "feature-flag-off" ||
+        runtimeConvergence.terminalReason === "unsupported-dag-shape") {
+        return [];
+    }
+    const parsed = await safeReadJson(runPath);
+    if (!parsed)
+        return [];
+    const convergence = readObject(parsed, "convergence");
+    if (!convergence)
+        return [];
+    const chainNodeIds = readStringArray(convergence, "chainNodeIds");
+    if (chainNodeIds.length === 0)
+        return [];
+    if (!chainNodeIds.includes("review-gate-shell") ||
+        !chainNodeIds.includes("repair-pi")) {
+        return [];
+    }
+    const known = new Set(nodes.map((node) => node.nodeId));
+    if (!known.has("review-gate-shell") || !known.has("repair-pi")) {
+        return [];
+    }
+    return [{ from: "review-gate-shell", to: "repair-pi", kind: "control-loop" }];
+}
+/**
+ * Project `state.convergence` into the slim Observe summary. Keeps the budget
+ * envelope even when passHistory is empty.
+ */
+function projectConvergenceSummary(state) {
+    const convergence = state.convergence;
+    if (!convergence)
+        return undefined;
+    return {
+        enabled: convergence.enabled,
+        maxPasses: convergence.maxPasses,
+        currentPass: convergence.currentPass,
+        ...(convergence.terminalReason
+            ? { terminalReason: convergence.terminalReason }
+            : {}),
+        passHistory: convergence.passHistory.map((pass) => ({
+            pass: pass.pass,
+            ...(pass.reason ? { reason: pass.reason } : {}),
+            ...(pass.status ? { status: pass.status } : {}),
+            ...(pass.hardVerifyStatus
+                ? { hardVerifyStatus: pass.hardVerifyStatus }
+                : {}),
+            ...(pass.reviewVerdict ? { reviewVerdict: pass.reviewVerdict } : {}),
+            ...(pass.reviewGateStatus
+                ? { reviewGateStatus: pass.reviewGateStatus }
+                : {}),
+        })),
+    };
+}
+/**
+ * Record convergence participation from archived pass artifacts plus the live
+ * current pass. The controller archives only retry/terminal failures, so an
+ * active pass or a successful final pass must be derived from current node
+ * state to avoid dropping its pass marker from Observe.
+ */
+function applyNodePasses(nodes, state) {
+    const passesByNode = new Map();
+    const addPass = (nodeId, pass) => {
+        const passes = passesByNode.get(nodeId) ?? new Set();
+        passes.add(pass);
+        passesByNode.set(nodeId, passes);
+    };
+    for (const pass of state.convergence?.passHistory ?? []) {
+        for (const ref of pass.artifactRefs)
+            addPass(ref.nodeId, pass.pass);
+    }
+    const initialPassNodeIds = new Set([
+        "initial-review-pi",
+        "initial-review-gate-shell",
+        "initial-review-pass-shell",
+    ]);
+    for (const node of nodes) {
+        if (!initialPassNodeIds.has(node.nodeId))
+            continue;
+        const status = (node.status ?? "").toUpperCase();
+        if (["RUNNING", "FINISHED", "ERROR"].includes(status)) {
+            addPass(node.nodeId, 1);
+        }
+    }
+    const currentPass = state.convergence?.currentPass;
+    if (currentPass && currentPass > 0) {
+        const convergenceNodeIds = new Set([
+            "process-supervisor-pi",
+            "process-gate-shell",
+            "repair-pi",
+            "hard-verify-shell",
+            "review-pi",
+            "review-verdict-recovery-pi",
+            "review-gate-shell",
+        ]);
+        for (const node of nodes) {
+            if (!convergenceNodeIds.has(node.nodeId))
+                continue;
+            const status = (node.status ?? "").toUpperCase();
+            if (["RUNNING", "FINISHED", "ERROR"].includes(status)) {
+                addPass(node.nodeId, currentPass);
+            }
+        }
+    }
+    for (const node of nodes) {
+        const passes = passesByNode.get(node.nodeId);
+        if (passes && passes.size > 0) {
+            node.passes = [...passes].sort((left, right) => left - right);
+        }
+    }
+}
 function buildRankIndex(ranks) {
     const index = new Map();
     for (let i = 0; i < ranks.length; i++) {