@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.4

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

@@ -1,14 +1,18 @@
 import path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { writeDagNodeJsonArtifact, writeTextArtifactFile, } from "../infrastructure/harness/artifact-store.js";
-import { executePiStep, } from "./pi-executor.js";
+import { writeJsonAtomic } from "../infrastructure/harness/atomic-write.js";
+import { mapContractBlockedOwner } from "../workflows/dag/frontend-human-decision.js";
+import { routeFrontendProviderCapability } from "../workflows/dag/frontend-provider-capability-matrix.js";
+import { executePiStep, resolvePiBackend, } from "./pi-executor.js";
+import { resolveDagPiExtensions, } from "./pi-extension-resolver.js";
 import { buildPiWriterToolPolicyContext, createPiWriterCustomTools, } from "./pi-writer-tool-policy.js";
 import { cleanupPlaywrightCliDefaultSession, createPlaywrightCliTool, PI_COMMAND_CAPABILITY_REGISTRY, resolveCaseIdFromWriteSet, resolveEvidenceDirFromWriteSet, } from "./pi-playwright-cli-tool.js";
 import { dagCommandPolicyAllows, resolveDagCommandPolicy, } from "../workflows/dag/types.js";
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
 import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelain, recoverRootNulArtifact, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
-import { isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
+import { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
 import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
 import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
@@ -163,6 +167,14 @@ function resolvePiExecutorStep(persona) {
 function isDagPiWriteTask(task) {
     return task.executor === "pi" && task.toolProfile === "write";
 }
+/**
+ * M4: `frontend-implement-pi` derives its status from mechanical facts instead
+ * of the IMPLEMENTATION_OUTCOME first line. Everything else (backend/README/
+ * module writers + frontend-repair-pi) keeps the legacy protocol face.
+ */
+export function isFrontendFactsWriter(task) {
+    return task.writerOutcomePolicy?.type === "frontend-facts-v1";
+}
 /** Map DAG `piStep` / `role` to a safe workflow step for read-only Pi or bounded write. */
 export function resolveDagPiStepName(task) {
     if (isDagPiWriteTask(task)) {
@@ -178,7 +190,94 @@ export function resolveDagPiStepName(task) {
     }
     return resolvePiExecutorStep(resolveDagPiPersona(task));
 }
+/** A+B: `frontend-contract-pi` incremental record tools (origin=contract). */
+export const FRONTEND_CONTRACT_RECORD_TOOL_NAMES = [
+    "record_requirement",
+    "record_constraint",
+    "record_evidence_expectation",
+    "record_handoff_intent",
+    "record_open_question",
+    "record_split_proposal",
+];
+export const FRONTEND_CONTRACT_TERMINAL_TOOL_NAMES = [
+    "finalize_contract",
+];
+/** A+B: `frontend-scout-pi` incremental evidence tools (origin=scout). */
+export const FRONTEND_SCOUT_EVIDENCE_TOOL_NAMES = [
+    "record_target_surface",
+    "record_design_evidence",
+];
+/** A+B: `frontend-plan-pi` incremental record tools (origin=plan). */
+export const FRONTEND_PLAN_RECORD_TOOL_NAMES = [
+    "record_target_surface",
+    "record_component_choice",
+    "record_state_flow",
+    "record_data_flow",
+    "record_mock_api",
+    "record_design_deviation",
+    "record_dependency",
+];
+export const FRONTEND_PLAN_TERMINAL_TOOL_NAMES = ["finalize_plan"];
+export const FRONTEND_PLAN_ADOPT_TOOL_NAMES = ["adopt_staged_fact"];
+/** M5: `frontend-review-pi` emits its authoritative terminal verdict through
+ * committed typed tools instead of the legacy JSON verdict parse. */
+export function isFrontendReviewTypedTerminalNode(task) {
+    return task.id === "frontend-review-pi";
+}
+/** M8: `frontend-design-review-pi` emits its authoritative terminal verdict
+ * through committed typed tools (`approve_design` / `request_design_changes`)
+ * instead of the legacy first-line `VERDICT: pass|request-revision` text. */
+export function isFrontendDesignTypedTerminalNode(task) {
+    return task.id === "frontend-design-review-pi";
+}
+/** A+B: `frontend-contract-pi` submits its contract through incremental typed
+ * tools + the `finalize_contract` terminal (origin=contract). */
+export function isFrontendContractTypedNode(task) {
+    return task.id === "frontend-contract-pi";
+}
+/** A+B: `frontend-scout-pi` submits target-surface/design-evidence through
+ * incremental evidence tools (origin=scout). */
+export function isFrontendScoutEvidenceNode(task) {
+    return task.id === "frontend-scout-pi";
+}
+/** A+B: `frontend-plan-pi` records its decision ledger through seven
+ * incremental `record_*` tools and closes with `finalize_plan`. */
+export function isFrontendPlanLedgerNode(task) {
+    return task.id === "frontend-plan-pi";
+}
 export function resolveDagPiToolNames(task) {
+    if (isFrontendReviewTypedTerminalNode(task)) {
+        return [
+            ...DAG_PI_READONLY_TOOLS,
+            "approve_review",
+            "request_review_changes",
+        ];
+    }
+    if (isFrontendDesignTypedTerminalNode(task)) {
+        return [
+            ...DAG_PI_READONLY_TOOLS,
+            "approve_design",
+            "request_design_changes",
+        ];
+    }
+    if (isFrontendContractTypedNode(task)) {
+        return [
+            ...DAG_PI_READONLY_TOOLS,
+            ...FRONTEND_CONTRACT_RECORD_TOOL_NAMES,
+            ...FRONTEND_CONTRACT_TERMINAL_TOOL_NAMES,
+        ];
+    }
+    if (isFrontendScoutEvidenceNode(task)) {
+        return [...DAG_PI_READONLY_TOOLS, ...FRONTEND_SCOUT_EVIDENCE_TOOL_NAMES];
+    }
+    if (isFrontendPlanLedgerNode(task)) {
+        return [
+            ...DAG_PI_READONLY_TOOLS,
+            ...FRONTEND_PLAN_RECORD_TOOL_NAMES,
+            ...FRONTEND_PLAN_TERMINAL_TOOL_NAMES,
+            ...FRONTEND_PLAN_ADOPT_TOOL_NAMES,
+        ];
+    }
     if (!isDagPiWriteTask(task))
         return [...DAG_PI_READONLY_TOOLS];
     const tools = [...DAG_PI_WRITE_TOOLS];
@@ -189,20 +288,1157 @@ export function resolveDagPiToolNames(task) {
     }
     return tools;
 }
+export const FRONTEND_REVIEW_TERMINAL_TOOL_NAMES = new Set([
+    "approve_review",
+    "request_review_changes",
+]);
+/**
+ * Fail-closed scanner for the two committed review terminal tools. Mirrors
+ * M4's `countWriteToolEventsFromSessionEvents` pattern: an unparseable line
+ * never counts as a terminal fact, so a corrupt/empty log cannot inflate the
+ * typed verdict.
+ */
+export function scanReviewTerminalKindsFromSessionEvents(content) {
+    const kinds = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event !== null &&
+            typeof event === "object" &&
+            event.type === "tool_execution_start" &&
+            typeof event.toolName === "string" &&
+            FRONTEND_REVIEW_TERMINAL_TOOL_NAMES.has(event.toolName)) {
+            kinds.push(event.toolName);
+        }
+    }
+    return kinds;
+}
+export const FRONTEND_DESIGN_TERMINAL_TOOL_NAMES = new Set([
+    "approve_design",
+    "request_design_changes",
+]);
+/**
+ * Fail-closed scanner for the two committed design terminal tools. Mirrors the
+ * review scanner: an unparseable line never counts as a terminal fact, so a
+ * corrupt/empty log cannot inflate the typed verdict.
+ */
+export function scanDesignTerminalKindsFromSessionEvents(content) {
+    const kinds = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event !== null &&
+            typeof event === "object" &&
+            event.type === "tool_execution_start" &&
+            typeof event.toolName === "string" &&
+            FRONTEND_DESIGN_TERMINAL_TOOL_NAMES.has(event.toolName)) {
+            kinds.push(event.toolName);
+        }
+    }
+    return kinds;
+}
+/**
+ * M5: build the two committed typed review terminal tools (approve_review /
+ * request_review_changes). Each tool validates its parameters with the review
+ * fact zod schemas, stages + adopts a terminal fact into the typed event
+ * store, and returns a structured receipt. Terminal conflicts (a second
+ * terminal commit) are caught inside execute and returned as an error receipt
+ * rather than crashing the node.
+ */
+export async function createFrontendReviewTerminalTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { approveReviewFactSchema, readCommittedEvents, requestReviewChangesFactSchema, writeTypedEventStoreJsonl, } = await import("../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    const findingSchema = Type.Object({
+        severity: Type.String({
+            description: "Critical | Important | Minor | Info",
+        }),
+        file: Type.Optional(Type.String({})),
+        line: Type.Optional(Type.Number({})),
+        issue: Type.String({}),
+        requiredChange: Type.Optional(Type.String({})),
+    }, { additionalProperties: false });
+    const approveParameters = Type.Object({
+        findings: Type.Array(findingSchema, {
+            description: "Optional informational findings (Minor/Info only; no Critical/Important on approval)",
+        }),
+    }, { additionalProperties: false });
+    const requestParameters = Type.Object({
+        issueCategory: Type.Enum({
+            "implementation-mismatch": "implementation-mismatch",
+            "approved-design-defect": "approved-design-defect",
+            "target-surface-defect": "target-surface-defect",
+            "contract-requirement-gap": "contract-requirement-gap",
+            "unknown": "unknown",
+        }, { description: "Typed issue category (five-value enum)" }),
+        evidenceRefs: Type.Array(Type.String({}), {
+            description: "Evidence refs (paths or artifact ids); at least one",
+        }),
+        findings: Type.Array(findingSchema, {
+            description: "At least one finding",
+        }),
+    }, { additionalProperties: false });
+    async function adoptReviewFact(kind, fact) {
+        const requestId = randomUUID();
+        try {
+            const parsed = kind === "approve_review"
+                ? approveReviewFactSchema.parse(fact)
+                : requestReviewChangesFactSchema.parse(fact);
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+            });
+            const adopted = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: true,
+                            kind,
+                            eventId: adopted.eventId,
+                            revision: adopted.revision,
+                        }),
+                    },
+                ],
+                details: {
+                    ok: true,
+                    kind,
+                    eventId: adopted.eventId,
+                    revision: adopted.revision,
+                },
+            };
+        }
+        catch (error) {
+            const code = error?.code;
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, kind, code, error: message }),
+                    },
+                ],
+                details: { ok: false, kind, code, error: message },
+            };
+        }
+    }
+    const approveReviewTool = defineTool({
+        name: "approve_review",
+        label: "approve_review",
+        description: "Commit the authoritative approve_review terminal fact. Use only when the implementation passes review with no Critical/Important findings.",
+        promptSnippet: "Commit the authoritative approve_review terminal verdict (no Critical/Important findings).",
+        parameters: approveParameters,
+        async execute(_toolCallId, params) {
+            return adoptReviewFact("approve_review", {
+                kind: "approve_review",
+                verdict: "approve_review",
+                findings: params?.findings ?? [],
+            });
+        },
+    });
+    const requestReviewChangesTool = defineTool({
+        name: "request_review_changes",
+        label: "request_review_changes",
+        description: "Commit the authoritative request_review_changes terminal fact. Requires a typed issueCategory, at least one evidenceRef, and non-empty findings.",
+        promptSnippet: "Commit the authoritative request_review_changes terminal verdict (issueCategory + evidenceRefs + findings required).",
+        parameters: requestParameters,
+        async execute(_toolCallId, params) {
+            return adoptReviewFact("request_review_changes", {
+                kind: "request_review_changes",
+                verdict: "request_review_changes",
+                issueCategory: params?.issueCategory,
+                evidenceRefs: params?.evidenceRefs,
+                findings: params?.findings,
+            });
+        },
+    });
+    return {
+        customTools: [approveReviewTool, requestReviewChangesTool],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "review-typed-facts.jsonl"), committed);
+        },
+    };
+}
+/**
+ * M8: build the two committed typed design terminal tools (approve_design /
+ * request_design_changes). Each tool validates its parameters with the design
+ * fact zod schemas, stages + adopts a terminal fact into the typed event
+ * store, and returns a structured receipt. Terminal conflicts are caught
+ * inside execute and returned as an error receipt rather than crashing the
+ * node.
+ */
+export async function createFrontendDesignTerminalTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { approveDesignFactSchema, readCommittedEvents, requestDesignChangesFactSchema, writeTypedEventStoreJsonl, } = await import("../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    const findingSchema = Type.Object({
+        severity: Type.String({
+            description: "Critical | Important | Minor | Info",
+        }),
+        file: Type.Optional(Type.String({})),
+        line: Type.Optional(Type.Number({})),
+        issue: Type.String({}),
+        requiredChange: Type.Optional(Type.String({})),
+    }, { additionalProperties: false });
+    const approveParameters = Type.Object({
+        findings: Type.Array(findingSchema, {
+            description: "Optional informational findings (Minor/Info only; no Critical/Important on approval)",
+        }),
+    }, { additionalProperties: false });
+    const requestParameters = Type.Object({
+        issueCategory: Type.Enum({
+            "implementation-mismatch": "implementation-mismatch",
+            "approved-design-defect": "approved-design-defect",
+            "target-surface-defect": "target-surface-defect",
+            "contract-requirement-gap": "contract-requirement-gap",
+            "unknown": "unknown",
+        }, { description: "Typed issue category (five-value enum)" }),
+        evidenceRefs: Type.Array(Type.String({}), {
+            description: "Evidence refs (paths or artifact ids); at least one",
+        }),
+        findings: Type.Array(findingSchema, {
+            description: "At least one finding",
+        }),
+    }, { additionalProperties: false });
+    async function adoptDesignFact(kind, fact) {
+        const requestId = randomUUID();
+        try {
+            const parsed = kind === "approve_design"
+                ? approveDesignFactSchema.parse(fact)
+                : requestDesignChangesFactSchema.parse(fact);
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+            });
+            const adopted = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: true,
+                            kind,
+                            eventId: adopted.eventId,
+                            revision: adopted.revision,
+                        }),
+                    },
+                ],
+                details: {
+                    ok: true,
+                    kind,
+                    eventId: adopted.eventId,
+                    revision: adopted.revision,
+                },
+            };
+        }
+        catch (error) {
+            const code = error?.code;
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, kind, code, error: message }),
+                    },
+                ],
+                details: { ok: false, kind, code, error: message },
+            };
+        }
+    }
+    const approveDesignTool = defineTool({
+        name: "approve_design",
+        label: "approve_design",
+        description: "Commit the authoritative approve_design terminal fact. Use only when the plan passes design review with no Critical/Important findings.",
+        promptSnippet: "Commit the authoritative approve_design terminal verdict (no Critical/Important findings).",
+        parameters: approveParameters,
+        async execute(_toolCallId, params) {
+            return adoptDesignFact("approve_design", {
+                kind: "approve_design",
+                verdict: "approve_design",
+                findings: params?.findings ?? [],
+            });
+        },
+    });
+    const requestDesignChangesTool = defineTool({
+        name: "request_design_changes",
+        label: "request_design_changes",
+        description: "Commit the authoritative request_design_changes terminal fact. Requires a typed issueCategory, at least one evidenceRef, and non-empty findings.",
+        promptSnippet: "Commit the authoritative request_design_changes terminal verdict (issueCategory + evidenceRefs + findings required).",
+        parameters: requestParameters,
+        async execute(_toolCallId, params) {
+            return adoptDesignFact("request_design_changes", {
+                kind: "request_design_changes",
+                verdict: "request_design_changes",
+                issueCategory: params?.issueCategory,
+                evidenceRefs: params?.evidenceRefs,
+                findings: params?.findings,
+            });
+        },
+    });
+    return {
+        customTools: [approveDesignTool, requestDesignChangesTool],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "design-typed-facts.jsonl"), committed);
+        },
+    };
+}
+/**
+ * A+B: `frontend-plan-pi` now records its decision ledger through seven
+ * incremental `record_*` tools (origin=plan) and closes with exactly one
+ * `finalize_plan` terminal. A later attempt may explicitly adopt a quarantined
+ * fact via `adopt_staged_fact`. Flush writes `plan-typed-facts.jsonl` for the
+ * node validator / compile authority.
+ */
+export async function createFrontendPlanLedgerTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { readCommittedEvents, writeTypedEventStoreJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
+    const { adoptStagedFact, adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
+    const { assemblePlanPatchFromCommittedFacts } = await import("../workflows/dag/frontend-shadow-dual-write.js");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    const stringArray = Type.Array(Type.String({}));
+    const optionalString = Type.Optional(Type.String({}));
+    const optionalStringArray = Type.Optional(stringArray);
+    const requirementSchema = Type.Object({
+        id: Type.String({}),
+        expectedOutcome: Type.String({}),
+        implementationTargets: stringArray,
+        verificationTargetIds: stringArray,
+        evidenceGap: Type.Optional(Type.Object({
+            requirementId: optionalString,
+            description: Type.String({}),
+            blocking: Type.Boolean(),
+        }, { additionalProperties: false })),
+    }, { additionalProperties: false });
+    const uiStateSchema = Type.Object({
+        name: Type.String({}),
+        applicable: Type.Boolean(),
+        expectedBehavior: optionalString,
+        implementationTargets: optionalStringArray,
+        verificationTargetIds: optionalStringArray,
+        notApplicableReason: optionalString,
+    }, { additionalProperties: false });
+    const interactionSchema = Type.Object({
+        name: Type.String({}),
+        trigger: Type.String({}),
+        expectedBehavior: Type.String({}),
+        implementationTargets: stringArray,
+        verificationTargetIds: stringArray,
+    }, { additionalProperties: false });
+    const mockEndpointSchema = Type.Object({
+        method: Type.String({
+            description: "GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS",
+        }),
+        path: Type.String({}),
+        fixture: optionalString,
+        consumer: optionalString,
+    }, { additionalProperties: false });
+    const mockApiSchema = Type.Object({
+        strategy: Type.String({
+            description: "native | browser-intercept | request-adapter | not-needed",
+        }),
+        activation: Type.String({}),
+        endpoints: Type.Array(mockEndpointSchema),
+    }, { additionalProperties: false });
+    const designEvidenceSchema = Type.Object({
+        source: Type.String({}),
+        paths: stringArray,
+        conflicts: stringArray,
+    }, { additionalProperties: false });
+    const verificationTargetSchema = Type.Object({
+        id: Type.String({}),
+        type: Type.String({
+            description: "static | unit | component | integration | mock",
+        }),
+        commandLabel: Type.String({}),
+        file: Type.String({}),
+        symbol: Type.Optional(Type.String({
+            description: "Real exported identifier or describe/it title in the target file. Forbidden for type=static (runtime strips it); required for non-static targets.",
+        })),
+        requirementIds: stringArray,
+        uiStates: stringArray,
+    }, { additionalProperties: false });
+    const evidenceGapSchema = Type.Object({
+        requirementId: optionalString,
+        description: Type.String({}),
+        blocking: Type.Boolean(),
+    }, { additionalProperties: false });
+    const uiComponentChoiceSchema = Type.Object({
+        purpose: Type.String({}),
+        component: Type.String({}),
+        decision: Type.String({
+            description: "specified | reuse-existing | new",
+        }),
+        specReference: Type.Optional(Type.Object({
+            path: Type.String({}),
+            section: Type.String({}),
+            line: Type.Optional(Type.Number({})),
+        }, { additionalProperties: false })),
+        rationale: Type.String({}),
+    }, { additionalProperties: false });
+    const targetsSchema = Type.Object({
+        routes: optionalStringArray,
+        publicApiChanges: optionalStringArray,
+    }, { additionalProperties: false });
+    const stringList = (value) => Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+    const planToolReceipt = (details) => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(details),
+            },
+        ],
+        details,
+    });
+    async function adoptPlanFact(kind, requestId, fact) {
+        // A+B (AC-005): a provider-capability fact kind reaching the plan ledger
+        // is out of route — it belongs to the shadow provider capability channel,
+        // not the plan decision ledger. Route it through the frozen seven-kind
+        // matrix and fail closed to `unsupported-provider-capability` instead of
+        // silently widening the plan catalog.
+        const capabilityRoute = routeFrontendProviderCapability({ factKind: kind });
+        if (capabilityRoute.ok) {
+            return {
+                ok: false,
+                kind,
+                code: "unsupported-provider-capability",
+                error: `plan ledger cannot adopt provider capability fact kind: ${kind}`,
+            };
+        }
+        try {
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+            });
+            const committed = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                ok: true,
+                kind,
+                eventId: committed.eventId,
+                revision: committed.revision,
+                error: "",
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                kind,
+                code: error?.code,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    const recordTargetSurfaceTool = defineTool({
+        name: "record_target_surface",
+        label: "record_target_surface",
+        description: "Record the plan target surface (routes + files) as an origin=plan target-surface fact.",
+        promptSnippet: "Record the plan target surface fact.",
+        parameters: Type.Object({ targets: Type.Optional(targetsSchema), files: stringArray }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const routes = stringList(params?.targets?.routes);
+            const files = stringList(params?.files);
+            const result = await adoptPlanFact("target-surface", `${attemptId}:record_target_surface:${randomUUID()}`, { kind: "target-surface", origin: "plan", files, routes });
+            return planToolReceipt(result);
+        },
+    });
+    const recordComponentChoiceTool = defineTool({
+        name: "record_component_choice",
+        label: "record_component_choice",
+        description: "Record component choices and styling strategy as an origin=plan component-choice fact.",
+        promptSnippet: "Record the plan component-choice fact.",
+        parameters: Type.Object({
+            uiComponentChoices: Type.Optional(Type.Array(uiComponentChoiceSchema)),
+            stylingStrategy: optionalString,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const uiComponentChoices = Array.isArray(params?.uiComponentChoices)
+                ? params.uiComponentChoices
+                : [];
+            const components = uiComponentChoices
+                .map((choice) => typeof choice?.component === "string" ? choice.component : "")
+                .filter(Boolean);
+            const result = await adoptPlanFact("component-choice", `${attemptId}:record_component_choice:${randomUUID()}`, {
+                kind: "component-choice",
+                origin: "plan",
+                components,
+                uiComponentChoices,
+                ...(params?.stylingStrategy
+                    ? { stylingStrategy: params.stylingStrategy }
+                    : {}),
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordStateFlowTool = defineTool({
+        name: "record_state_flow",
+        label: "record_state_flow",
+        description: "Record UI states and interactions as an origin=plan state-flow fact.",
+        promptSnippet: "Record the plan state-flow fact.",
+        parameters: Type.Object({
+            uiStates: Type.Array(uiStateSchema),
+            interactions: Type.Array(interactionSchema),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const uiStates = Array.isArray(params?.uiStates) ? params.uiStates : [];
+            const interactions = Array.isArray(params?.interactions)
+                ? params.interactions
+                : [];
+            const states = uiStates
+                .map((state) => (typeof state?.name === "string" ? state.name : ""))
+                .filter(Boolean);
+            const result = await adoptPlanFact("state-flow", `${attemptId}:record_state_flow:${randomUUID()}`, {
+                kind: "state-flow",
+                origin: "plan",
+                states,
+                uiStates,
+                interactions,
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordDataFlowTool = defineTool({
+        name: "record_data_flow",
+        label: "record_data_flow",
+        description: "Record interaction/endpoint data flow as an origin=plan data-flow fact.",
+        promptSnippet: "Record the plan data-flow fact.",
+        parameters: Type.Object({ interactions: stringArray, endpoints: stringArray }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const result = await adoptPlanFact("data-flow", `${attemptId}:record_data_flow:${randomUUID()}`, {
+                kind: "data-flow",
+                origin: "plan",
+                interactions: stringList(params?.interactions),
+                endpoints: stringList(params?.endpoints),
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordMockApiTool = defineTool({
+        name: "record_mock_api",
+        label: "record_mock_api",
+        description: "Record the Mock/API strategy as an origin=plan mock-api fact.",
+        promptSnippet: "Record the plan mock-api fact.",
+        parameters: Type.Object({ mockApi: mockApiSchema }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const mockApi = params?.mockApi ?? {
+                strategy: "not-needed",
+                activation: "",
+                endpoints: [],
+            };
+            const endpoints = stringList((Array.isArray(mockApi?.endpoints) ? mockApi.endpoints : []).map((endpoint) => `${typeof endpoint?.method === "string" ? endpoint.method : ""} ${typeof endpoint?.path === "string" ? endpoint.path : ""}`.trim()));
+            const result = await adoptPlanFact("mock-api", `${attemptId}:record_mock_api:${randomUUID()}`, {
+                kind: "mock-api",
+                origin: "plan",
+                strategy: typeof mockApi?.strategy === "string" ? mockApi.strategy : "",
+                endpoints,
+                mockApi,
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordDesignDeviationTool = defineTool({
+        name: "record_design_deviation",
+        label: "record_design_deviation",
+        description: "Record design evidence conflicts as an origin=plan design-deviation fact.",
+        promptSnippet: "Record the plan design-deviation fact.",
+        parameters: Type.Object({ designEvidence: designEvidenceSchema }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const conflicts = stringList(params?.designEvidence?.conflicts);
+            const result = await adoptPlanFact("design-deviation", `${attemptId}:record_design_deviation:${randomUUID()}`, { kind: "design-deviation", origin: "plan", conflicts });
+            return planToolReceipt(result);
+        },
+    });
+    const recordDependencyTool = defineTool({
+        name: "record_dependency",
+        label: "record_dependency",
+        description: "Record the dependency policy as an origin=plan dependency fact.",
+        promptSnippet: "Record the plan dependency fact.",
+        parameters: Type.Object({ policy: Type.String({}) }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const result = await adoptPlanFact("dependency", `${attemptId}:record_dependency:${randomUUID()}`, {
+                kind: "dependency",
+                origin: "plan",
+                policy: typeof params?.policy === "string" ? params.policy : "",
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const finalizePlanTool = defineTool({
+        name: "finalize_plan",
+        label: "finalize_plan",
+        description: "Assemble the canonical editable plan patch from committed record facts plus these remaining fields, publish it on a target-surface fact, and commit the finalize_plan terminal. Call exactly once.",
+        promptSnippet: "Assemble and commit the finalize_plan terminal (requirements + verificationTargets + evidenceGaps + optional fields).",
+        parameters: Type.Object({
+            requirements: Type.Array(requirementSchema),
+            verificationTargets: Type.Array(verificationTargetSchema),
+            evidenceGaps: Type.Array(evidenceGapSchema),
+            implementationSteps: optionalStringArray,
+            residualRisks: optionalStringArray,
+            realIntegrationGap: optionalString,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const committed = readCommittedEvents(store, attemptId);
+                const fragment = assemblePlanPatchFromCommittedFacts(committed) ?? {};
+                const patch = {
+                    ...fragment,
+                    requirements: params?.requirements ?? [],
+                    verificationTargets: params?.verificationTargets ?? [],
+                    evidenceGaps: params?.evidenceGaps ?? [],
+                    ...(params?.implementationSteps
+                        ? { implementationSteps: params.implementationSteps }
+                        : {}),
+                    ...(params?.residualRisks
+                        ? { residualRisks: params.residualRisks }
+                        : {}),
+                    ...(params?.realIntegrationGap
+                        ? { realIntegrationGap: params.realIntegrationGap }
+                        : {}),
+                };
+                const patchResult = await adoptPlanFact("target-surface", `${attemptId}:finalize_plan:patch:${randomUUID()}`, { kind: "target-surface", origin: "plan", patch });
+                if (!patchResult.ok) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "finalize_plan",
+                        error: patchResult.error,
+                        code: patchResult.code,
+                    });
+                }
+                const terminal = await adoptPlanFact("finalize_plan", `${attemptId}:finalize_plan:terminal:${randomUUID()}`, { kind: "finalize_plan", origin: "plan", patch });
+                return planToolReceipt(terminal);
+            }
+            catch (error) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "finalize_plan",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        },
+    });
+    const adoptStagedFactTool = defineTool({
+        name: "adopt_staged_fact",
+        label: "adopt_staged_fact",
+        description: "Explicitly adopt a quarantined fact from a prior attempt into the committed ledger (idempotent by requestId).",
+        promptSnippet: "Adopt a quarantined fact into the committed ledger.",
+        parameters: Type.Object({
+            requestId: Type.String({}),
+            eventId: Type.String({}),
+            expectedRevision: Type.Number({}),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const adopted = await adoptStagedFact({
+                    store,
+                    requestId: typeof params?.requestId === "string" ? params.requestId : "",
+                    attemptId,
+                    eventId: typeof params?.eventId === "string" ? params.eventId : "",
+                    expectedRevision: typeof params?.expectedRevision === "number"
+                        ? params.expectedRevision
+                        : store.revision,
+                });
+                return planToolReceipt({
+                    ok: true,
+                    kind: "adopt_staged_fact",
+                    eventId: adopted.eventId,
+                    revision: adopted.revision,
+                    error: "",
+                });
+            }
+            catch (error) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "adopt_staged_fact",
+                    error: error instanceof Error ? error.message : String(error),
+                    code: error?.code,
+                });
+            }
+        },
+    });
+    return {
+        customTools: [
+            recordTargetSurfaceTool,
+            recordComponentChoiceTool,
+            recordStateFlowTool,
+            recordDataFlowTool,
+            recordMockApiTool,
+            recordDesignDeviationTool,
+            recordDependencyTool,
+            adoptStagedFactTool,
+            finalizePlanTool,
+        ],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"), committed);
+        },
+    };
+}
+function isRecordObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A contract fact is source-mapped when it carries a non-empty `sourceSpan`
+ * (object or string), a non-empty `sourceRefs` array, or a non-empty `source`
+ * string. Anything else is an unmapped source segment (AC-001). */
+function contractFactSourceSpan(fact) {
+    if (isRecordObject(fact.sourceSpan) || typeof fact.sourceSpan === "string") {
+        return fact.sourceSpan;
+    }
+    if (Array.isArray(fact.sourceRefs) && fact.sourceRefs.length > 0) {
+        return fact.sourceRefs;
+    }
+    if (typeof fact.source === "string" && fact.source.trim().length > 0) {
+        return fact.source;
+    }
+    return undefined;
+}
+/**
+ * A+B (AC-001): deterministically assemble the read-only `frontend-task-contract-vNext`
+ * audit artifact from committed contract facts. It never rewrites the original
+ * task source: unmapped requirement/constraint segments are listed explicitly
+ * so Plan/Implement/Review keep binding to the raw source, not the model's
+ * summarized contract. The blocked disposition is projected through the frozen
+ * `mapContractBlockedOwner` mapping (AC-002).
+ */
+export function buildFrontendTaskContractVNext(records) {
+    const facts = records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter(isRecordObject);
+    const finalized = facts.find((fact) => fact.kind === "contract-finalized");
+    const disposition = typeof finalized?.disposition === "string" ? finalized.disposition : null;
+    const blockingOwner = typeof finalized?.blockingOwner === "string"
+        ? finalized.blockingOwner
+        : null;
+    const projected = mapContractBlockedOwner({
+        disposition: disposition ?? "",
+        blockingOwner: blockingOwner ?? undefined,
+    });
+    const byKind = (kind) => facts.filter((fact) => fact.kind === kind);
+    const requirements = byKind("requirement");
+    const unmappedSourceSegments = requirements
+        .filter((fact) => contractFactSourceSpan(fact) === undefined)
+        .map((fact) => ({
+        kind: "requirement",
+        id: typeof fact.id === "string"
+            ? fact.id
+            : typeof fact.text === "string"
+                ? fact.text
+                : undefined,
+    }))
+        .filter((segment) => segment.id !== undefined);
+    return {
+        schemaVersion: 1,
+        schemaId: "frontend-task-contract-vNext",
+        disposition,
+        blockingOwner,
+        blockedOwner: projected === "not-blocked" ? null : projected,
+        requirements,
+        constraints: byKind("constraint"),
+        evidenceExpectations: byKind("evidence-expectation"),
+        handoffIntents: byKind("handoff-intent"),
+        openQuestions: byKind("open-question"),
+        splitProposals: byKind("split-proposal"),
+        unmappedSourceSegments,
+    };
+}
+/**
+ * A+B: `frontend-contract-pi` incremental contract tools. Six `record_*` tools
+ * commit origin=contract facts and `finalize_contract` commits the terminal
+ * disposition (ready | ready-with-assumptions | blocked + blockingOwner).
+ */
+export async function createFrontendContractTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { readCommittedEvents, writeTypedEventStoreJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    const receipt = (details) => ({
+        content: [{ type: "text", text: JSON.stringify(details) }],
+        details,
+    });
+    async function adoptContractFact(kind, fact) {
+        try {
+            const requestId = `${attemptId}:${kind}:${randomUUID()}`;
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+            });
+            const committed = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                ok: true,
+                kind,
+                eventId: committed.eventId,
+                revision: committed.revision,
+                error: "",
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                kind,
+                code: error?.code,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    const recordKinds = {
+        record_requirement: "requirement",
+        record_constraint: "constraint",
+        record_evidence_expectation: "evidence-expectation",
+        record_handoff_intent: "handoff-intent",
+        record_open_question: "open-question",
+        record_split_proposal: "split-proposal",
+    };
+    const recordTools = Object.entries(recordKinds).map(([name, kind]) => defineTool({
+        name,
+        label: name,
+        description: `Commit an origin=contract ${kind} fact.`,
+        promptSnippet: `Commit an origin=contract ${kind} fact.`,
+        parameters: Type.Object({}, { additionalProperties: true }),
+        async execute(_toolCallId, params) {
+            const result = await adoptContractFact(kind, {
+                kind,
+                origin: "contract",
+                ...(params ?? {}),
+            });
+            return receipt(result);
+        },
+    }));
+    // OpenSpec selection committed as individual typed facts (one path per
+    // call) so a large candidate set never exceeds a single model output
+    // budget: each tool call carries exactly one {path, disposition,
+    // rationale} row and the ledger accumulates them across calls. Only
+    // positive classifications (required | relevant) are legal; unmentioned
+    // candidates default to irrelevant at the prewrite gate.
+    const recordOpenspecSelectionTool = defineTool({
+        name: "record_openspec_selection",
+        label: "record_openspec_selection",
+        description: "Commit one OpenSpec candidate classification (origin=contract openspec-selection fact). Call once per path you actually use or consult: required (must be read and cited) or relevant (informs planning). Never call it for irrelevant candidates — unmentioned candidates default to irrelevant. You may call it many times; one row per call.",
+        promptSnippet: "Commit one OpenSpec candidate classification (required | relevant); one path per call; skip irrelevant candidates.",
+        parameters: Type.Object({
+            path: Type.String({
+                description: "Repo-relative candidate spec path, e.g. openspec/project-specs/ui/ucp-components-md/AdvancedSearch.md",
+            }),
+            disposition: Type.Enum({
+                required: "required",
+                relevant: "relevant",
+            }),
+            rationale: Type.String({}),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const path = typeof params?.path === "string" ? params.path : "";
+            const disposition = params?.disposition;
+            const rationale = typeof params?.rationale === "string" ? params.rationale : "";
+            if (!path || !disposition || !rationale.trim()) {
+                return receipt({
+                    ok: false,
+                    kind: "openspec-selection",
+                    error: "record_openspec_selection requires non-empty path, disposition (required|relevant), and rationale",
+                });
+            }
+            const result = await adoptContractFact("openspec-selection", {
+                kind: "openspec-selection",
+                origin: "contract",
+                path,
+                disposition,
+                rationale,
+            });
+            return receipt(result);
+        },
+    });
+    const finalizeContractTool = defineTool({
+        name: "finalize_contract",
+        label: "finalize_contract",
+        description: "Commit the contract-finalized terminal fact with a disposition of ready | ready-with-assumptions | blocked (blocked requires blockingOwner). Call exactly once.",
+        promptSnippet: "Commit the contract-finalized terminal (disposition + optional blockingOwner).",
+        parameters: Type.Object({
+            disposition: Type.Enum({
+                ready: "ready",
+                "ready-with-assumptions": "ready-with-assumptions",
+                blocked: "blocked",
+            }),
+            blockingOwner: Type.Optional(Type.Enum({
+                "blocked-human": "blocked-human",
+                "blocked-external": "blocked-external",
+            })),
+            assumptions: Type.Optional(Type.Array(Type.String({}))),
+            summary: Type.Optional(Type.String({})),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const disposition = params?.disposition;
+            const blockingOwner = params?.blockingOwner;
+            if (disposition === "blocked" && !blockingOwner) {
+                return receipt({
+                    ok: false,
+                    kind: "finalize_contract",
+                    error: "blocked disposition requires blockingOwner (blocked-human | blocked-external)",
+                });
+            }
+            const blockedOwner = mapContractBlockedOwner({
+                disposition: disposition ?? "",
+                blockingOwner,
+            });
+            const result = await adoptContractFact("contract-finalized", {
+                kind: "contract-finalized",
+                origin: "contract",
+                disposition,
+                ...(blockingOwner ? { blockingOwner } : {}),
+                ...(blockedOwner !== "not-blocked" ? { blockedOwner } : {}),
+                ...(Array.isArray(params?.assumptions)
+                    ? { assumptions: params.assumptions }
+                    : {}),
+                ...(typeof params?.summary === "string"
+                    ? { summary: params.summary }
+                    : {}),
+            });
+            return receipt(result);
+        },
+    });
+    return {
+        customTools: [
+            ...recordTools,
+            recordOpenspecSelectionTool,
+            finalizeContractTool,
+        ],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "contract-typed-facts.jsonl"), committed);
+            await writeJsonAtomic(path.join(input.runDir, input.nodeId, "frontend-task-contract-vNext.json"), buildFrontendTaskContractVNext(committed));
+        },
+    };
+}
+/**
+ * A+B: `frontend-scout-pi` incremental evidence tools (origin=scout). Runtime
+ * enriches committed target-surface / design-evidence facts with hash/section/
+ * freshness from real read events; the tool itself never trusts model self-report.
+ */
+export async function createFrontendScoutEvidenceTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { readCommittedEvents, writeTypedEventStoreJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    const stringArray = Type.Array(Type.String({}));
+    const optionalString = Type.Optional(Type.String({}));
+    const receipt = (details) => ({
+        content: [{ type: "text", text: JSON.stringify(details) }],
+        details,
+    });
+    // A+B (AC-003): runtime enriches declared scout paths with hash/freshness
+    // from the real filesystem. The model's self-reported path list is never
+    // trusted for content identity; a missing file fails closed to fresh=false
+    // with a zero hash instead of inventing content.
+    const enrichScoutPathEvidence = async (paths) => {
+        if (!input.workspaceRoot)
+            return [];
+        const evidence = [];
+        for (const relative of new Set(paths)) {
+            try {
+                const bytes = await readFile(path.join(input.workspaceRoot, relative));
+                evidence.push({
+                    path: relative,
+                    sha256: createHash("sha256").update(bytes).digest("hex"),
+                    fresh: true,
+                });
+            }
+            catch {
+                evidence.push({ path: relative, sha256: "0".repeat(64), fresh: false });
+            }
+        }
+        return evidence;
+    };
+    async function adoptScoutFact(kind, fact) {
+        try {
+            const requestId = `${attemptId}:${kind}:${randomUUID()}`;
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+            });
+            const committed = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                ok: true,
+                kind,
+                eventId: committed.eventId,
+                revision: committed.revision,
+                error: "",
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                kind,
+                code: error?.code,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    const recordTargetSurfaceTool = defineTool({
+        name: "record_target_surface",
+        label: "record_target_surface",
+        description: "Commit an origin=scout target-surface fact (entrypoint, routeOrMount, implementationPaths, testPaths, dataSource, allowedPathConflicts).",
+        promptSnippet: "Commit an origin=scout target-surface fact.",
+        parameters: Type.Object({
+            entrypoint: optionalString,
+            routeOrMount: optionalString,
+            implementationPaths: stringArray,
+            testPaths: stringArray,
+            dataSource: optionalString,
+            allowedPathConflicts: stringArray,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const implementationPaths = params?.implementationPaths ?? [];
+            const testPaths = params?.testPaths ?? [];
+            const pathEvidence = await enrichScoutPathEvidence([
+                ...(params?.entrypoint ? [params.entrypoint] : []),
+                ...implementationPaths,
+                ...testPaths,
+            ]);
+            const result = await adoptScoutFact("target-surface", {
+                kind: "target-surface",
+                origin: "scout",
+                entrypoint: params?.entrypoint ?? "",
+                routeOrMount: params?.routeOrMount ?? "",
+                implementationPaths,
+                testPaths,
+                dataSource: params?.dataSource ?? "",
+                allowedPathConflicts: params?.allowedPathConflicts ?? [],
+                ...(pathEvidence.length > 0 ? { pathEvidence } : {}),
+            });
+            return receipt(result);
+        },
+    });
+    const recordDesignEvidenceTool = defineTool({
+        name: "record_design_evidence",
+        label: "record_design_evidence",
+        description: "Commit an origin=scout design-evidence fact (source, paths, conflicts).",
+        promptSnippet: "Commit an origin=scout design-evidence fact.",
+        parameters: Type.Object({ source: Type.String({}), paths: stringArray, conflicts: stringArray }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const paths = params?.paths ?? [];
+            const pathEvidence = await enrichScoutPathEvidence(paths);
+            const result = await adoptScoutFact("design-evidence", {
+                kind: "design-evidence",
+                origin: "scout",
+                source: params?.source ?? "",
+                paths,
+                conflicts: params?.conflicts ?? [],
+                ...(pathEvidence.length > 0 ? { pathEvidence } : {}),
+            });
+            return receipt(result);
+        },
+    });
+    return {
+        customTools: [recordTargetSurfaceTool, recordDesignEvidenceTool],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "scout-typed-facts.jsonl"), committed);
+        },
+    };
+}
 export function buildDagPiUserMessage(task, persona, step) {
     const role = task.role ?? "unspecified";
     const writePolicy = task.writePolicy ?? "read-only (default)";
     if (isDagPiWriteTask(task)) {
-        const outcomeInstruction = task.writerOutcomePolicy
+        const outcomeInstruction = isFrontendFactsWriter(task)
             ? [
-                "The first non-empty response line must be exactly IMPLEMENTATION_OUTCOME: changed, IMPLEMENTATION_OUTCOME: already-satisfied, or IMPLEMENTATION_OUTCOME: blocked. The runner measures your diff mechanically from git status snapshots taken before and after this node: code pasted into the response text is NOT an implementation and yields an empty diff. Use changed only after actually calling write/edit tools that persist files to disk; use already-satisfied only when the contract is already met and no file changed; use blocked when implementation cannot proceed. Claiming changed without a persisted diff fails this node as invalid-output.",
-                task.writerOutcomePolicy.requireChangedFiles
-                    ? "This generation node requires a non-empty bounded diff; already-satisfied cannot complete it successfully."
-                    : undefined,
+                "Your implementation status is derived by the executor from mechanical facts (persisted write-tool events, run delta, write guard, requirement coverage, focused-check failures) — never from an IMPLEMENTATION_OUTCOME first line. Do not emit an IMPLEMENTATION_OUTCOME first line. Make real write/edit tool calls that persist files to disk: a response-only change is an empty diff that fails this node. If the contract is already satisfied, prove it with concrete target/verification evidence; a bare self-report cannot authorize an empty implementation.",
             ]
                 .filter((value) => Boolean(value))
                 .join(" ")
-            : undefined;
+            : task.writerOutcomePolicy
+                ? [
+                    "The first non-empty response line must be exactly IMPLEMENTATION_OUTCOME: changed, IMPLEMENTATION_OUTCOME: already-satisfied, or IMPLEMENTATION_OUTCOME: blocked. The runner measures your diff mechanically from git status snapshots taken before and after this node: code pasted into the response text is NOT an implementation and yields an empty diff. Use changed only after actually calling write/edit tools that persist files to disk; use already-satisfied only when the contract is already met and no file changed; use blocked when implementation cannot proceed. Claiming changed without a persisted diff fails this node as invalid-output.",
+                    task.writerOutcomePolicy.requireChangedFiles
+                        ? "This generation node requires a non-empty bounded diff; already-satisfied cannot complete it successfully."
+                        : undefined,
+                ]
+                    .filter((value) => Boolean(value))
+                    .join(" ")
+                : undefined;
         return [
             `You are executing hybrid DAG node "${task.id}" (role=${role}, piStep=${step}, writePolicy=${writePolicy}).`,
             "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
@@ -327,6 +1563,36 @@ export async function writePiExecutorArtifacts(artifactsDir, input) {
     await writeTextArtifactFile(summaryPath, buildPiResultSummaryMarkdown(input));
     return { promptPath, summaryPath };
 }
+/**
+ * Run-owned per-node Pi extension facts (plan 2026-08-21): requested ids,
+ * resolved packages (with absolute entry paths), and degraded/missing ids.
+ * Written only for nodes that declare `piExtensions`; never into the repo-level
+ * DAG template. Best-effort: artifact failures never fail the node.
+ */
+async function writePiExtensionsArtifact(nodeArtifactsDir, requested, resolved, missing) {
+    try {
+        const runDir = path.dirname(nodeArtifactsDir);
+        const nodeId = path.basename(nodeArtifactsDir);
+        await writeDagNodeJsonArtifact(runDir, nodeId, "pi-extensions.json", {
+            schemaVersion: 1,
+            requested: [...requested],
+            resolved: resolved.map((entry) => ({
+                id: entry.id,
+                packageName: entry.packageName,
+                version: entry.version,
+                path: entry.entryPaths.join(", "),
+            })),
+            missing: missing.map((entry) => ({
+                id: entry.id,
+                reason: entry.reason,
+                ...(entry.detail ? { detail: entry.detail } : {}),
+            })),
+        });
+    }
+    catch {
+        // best-effort run fact; node execution continues
+    }
+}
 async function resolveValidatedFrontendBaseUrlFromContext(workspaceRoot, runDir) {
     try {
         const capability = JSON.parse(await readFile(path.join(runDir, "preflight-frontend-browser-tool-shell", "frontend-browser-capability.json"), "utf8"));
@@ -383,6 +1649,136 @@ const DEFAULT_DAG_PI_WRITE_GUARD_DEPENDENCIES = {
     readGitStatusPorcelain,
     recoverRootNulArtifact,
 };
+/**
+ * M5 shadow pass for `frontend-review-pi`: extract the committed typed terminal
+ * facts from session events, parse the legacy JSON verdict from the response
+ * text, compare them (audit-only), and persist the audit artifact. Missing
+ * typed terminal facts fail the node closed (AC-001); a shadow mismatch never
+ * blocks the node.
+ */
+async function runFrontendReviewTerminalShadow(input) {
+    const { compareTypedReviewToLegacyJsonVerdict } = await import("../workflows/dag/frontend-review-context.js");
+    const { parseJsonReviewVerdict } = await import("../workflows/dag/output-protocol.js");
+    const sessionEventsPath = path.join(input.meta.runDir, input.task.id, "session-events.jsonl");
+    let typedKinds = [];
+    try {
+        const content = await readFile(sessionEventsPath, "utf8");
+        typedKinds = scanReviewTerminalKindsFromSessionEvents(content);
+    }
+    catch {
+        // Missing/unreadable session log → fail-closed at zero terminal facts.
+        typedKinds = [];
+    }
+    let legacyVerdict;
+    try {
+        const parsed = parseJsonReviewVerdict(input.mapped.assistantText ?? input.mapped.stdout);
+        if (parsed.ok)
+            legacyVerdict = parsed.verdict;
+    }
+    catch {
+        legacyVerdict = undefined;
+    }
+    let comparison;
+    try {
+        comparison = compareTypedReviewToLegacyJsonVerdict({
+            typedKinds,
+            legacyVerdict,
+        });
+    }
+    catch (error) {
+        comparison = {
+            typedVerdict: undefined,
+            legacyVerdict: undefined,
+            match: false,
+            reason: `typed review equivalence comparison crashed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // Audit-only flush + artifact. Neither blocks the node.
+    try {
+        await input.tools?.flush?.();
+    }
+    catch {
+        // best-effort
+    }
+    try {
+        await writeDagNodeJsonArtifact(input.meta.runDir, input.task.id, "fact-review-status.json", {
+            schemaVersion: 1,
+            nodeId: input.task.id,
+            typedKinds,
+            legacyVerdict,
+            comparison,
+        });
+    }
+    catch {
+        // best-effort audit artifact
+    }
+    if (typedKinds.length === 0) {
+        return {
+            ...input.mapped,
+            ok: false,
+            failureCategory: "review-terminal-missing",
+            stderr: [
+                input.mapped.stderr,
+                "frontend review typed terminal fact missing: no approve_review/request_review_changes tool call was committed",
+            ]
+                .filter(Boolean)
+                .join("\n\n"),
+        };
+    }
+    return input.mapped;
+}
+/**
+ * M8 shadow pass for `frontend-design-review-pi`: extract the committed typed
+ * design terminal facts from session events, flush them, and persist the audit
+ * artifact. The design review's legacy output was a first-line
+ * `VERDICT: pass|request-revision` text protocol (not a JSON verdict), so
+ * there is no JSON equivalence comparison here. Missing typed terminal facts
+ * fail the node closed; writer admission later reads the committed
+ * `design-typed-facts.jsonl` as the only authoritative verdict.
+ */
+async function runFrontendDesignTerminalShadow(input) {
+    const sessionEventsPath = path.join(input.meta.runDir, input.task.id, "session-events.jsonl");
+    let typedKinds = [];
+    try {
+        const content = await readFile(sessionEventsPath, "utf8");
+        typedKinds = scanDesignTerminalKindsFromSessionEvents(content);
+    }
+    catch {
+        // Missing/unreadable session log → fail-closed at zero terminal facts.
+        typedKinds = [];
+    }
+    // Audit-only flush + artifact. Neither blocks the node.
+    try {
+        await input.tools?.flush?.();
+    }
+    catch {
+        // best-effort
+    }
+    try {
+        await writeDagNodeJsonArtifact(input.meta.runDir, input.task.id, "fact-design-status.json", {
+            schemaVersion: 1,
+            nodeId: input.task.id,
+            typedKinds,
+        });
+    }
+    catch {
+        // best-effort audit artifact
+    }
+    if (typedKinds.length === 0) {
+        return {
+            ...input.mapped,
+            ok: false,
+            failureCategory: "design-terminal-missing",
+            stderr: [
+                input.mapped.stderr,
+                "frontend design typed terminal fact missing: no approve_design/request_design_changes tool call was committed",
+            ]
+                .filter(Boolean)
+                .join("\n\n"),
+        };
+    }
+    return input.mapped;
+}
 export async function executeDagPiNode(input, meta, piStepFn = executePiStep, writeGuardDependencies = DEFAULT_DAG_PI_WRITE_GUARD_DEPENDENCIES) {
     const started = Date.now();
     const persona = resolveDagPiPersona(input.task);
@@ -453,6 +1849,11 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         }
         : undefined;
     let writerToolPolicy;
+    let reviewTerminalTools;
+    let designTerminalTools;
+    let planLedgerTools;
+    let contractTools;
+    let scoutEvidenceTools;
     const commandPolicy = resolveDagCommandPolicy(input.task.commandPolicy);
     const allowsPlaywrightCli = dagCommandPolicyAllows(input.task.commandPolicy, "playwright-cli");
     let playwrightToolContext;
@@ -521,6 +1922,133 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             };
         }
     }
+    if (isFrontendReviewTypedTerminalNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            reviewTerminalTools = await createFrontendReviewTerminalTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: reviewTerminalTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi review terminal tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (isFrontendDesignTypedTerminalNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            designTerminalTools = await createFrontendDesignTerminalTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: designTerminalTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi design terminal tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (isFrontendContractTypedNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            contractTools = await createFrontendContractTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: contractTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi contract tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (isFrontendScoutEvidenceNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            scoutEvidenceTools = await createFrontendScoutEvidenceTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+                workspaceRoot: input.cwd,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: scoutEvidenceTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi scout evidence tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (isFrontendPlanLedgerNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            planLedgerTools = await createFrontendPlanLedgerTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+                skeleton: input.task.structuredContractOutput?.skeleton,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: planLedgerTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi plan ledger tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
     let result;
     try {
         // Phase 5 (P1-9): capture the writeSet baseline BEFORE the writer provider
@@ -529,8 +2057,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         // hard fail (no baseline → no rollback → no recovery). Dynamic import avoids
         // an executor ↔ scheduler static cycle.
         if (isWriteTask &&
-            (input.task.id === "frontend-implement-pi" ||
-                input.task.id === "frontend-repair-pi") &&
+            input.task.id === "frontend-implement-pi" &&
             (input.task.writeSet?.length ?? 0) > 0) {
             try {
                 const { captureFrontendWriterAttemptIntent } = await import("../workflows/dag/frontend-writer-recovery.js");
@@ -550,6 +2077,29 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 };
             }
         }
+        // Plan 2026-08-21 D4/D6: resolve the node's explicit Pi extension
+        // allowlist against the settings inventory. Degrade on missing packages —
+        // never fail the node — and persist requested/resolved/missing facts.
+        const piExtensionsResolution = input.task.piExtensions
+            ? resolveDagPiExtensions({
+                repoRoot: input.cwd,
+                ids: input.task.piExtensions,
+            })
+            : undefined;
+        if (piExtensionsResolution) {
+            const piBackend = resolvePiBackend();
+            const cliDegraded = piBackend === "cli-only";
+            await writePiExtensionsArtifact(path.join(meta.runDir, input.task.id), input.task.piExtensions, cliDegraded ? [] : piExtensionsResolution.resolved, cliDegraded
+                ? input.task.piExtensions.map((id) => ({
+                    id,
+                    reason: "not-installed",
+                    detail: "cli backend does not load pi extensions (sdk-only v1)",
+                }))
+                : piExtensionsResolution.missing);
+        }
+        const piExtensionPaths = piExtensionsResolution && resolvePiBackend() !== "cli-only"
+            ? piExtensionsResolution.resolved.flatMap((entry) => entry.entryPaths)
+            : undefined;
         result = await piStepFn({
             attachedFiles: [],
             modelConfig: resolveDagPiModelConfig(input.model, input.thinking ? { thinking: input.thinking } : undefined),
@@ -564,6 +2114,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             stallTimeoutMs: input.stallTimeoutMs,
             abortGraceMs: input.abortGraceMs,
             ...(writerToolPolicy ? { writerToolPolicy } : {}),
+            ...(piExtensionPaths && piExtensionPaths.length > 0
+                ? { piExtensionPaths }
+                : {}),
             onActivity: bridgeActivity
                 ? (activity) => {
                     if (activity.kind === "lease" ||
@@ -608,9 +2161,51 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         persona,
         step,
     });
-    const mapped = mapPiResultToDagNodeResult(result, input.task.writerOutcomePolicy
-        ? WRITER_OUTCOME_PROTOCOL_LINE
-        : input.task.firstProtocolLine);
+    const mapped = mapPiResultToDagNodeResult(result, isFrontendFactsWriter(input.task)
+        ? undefined
+        : input.task.writerOutcomePolicy
+            ? WRITER_OUTCOME_PROTOCOL_LINE
+            : input.task.firstProtocolLine);
+    if (isFrontendReviewTypedTerminalNode(input.task)) {
+        return await runFrontendReviewTerminalShadow({
+            task: input.task,
+            meta,
+            mapped,
+            tools: reviewTerminalTools,
+        });
+    }
+    if (isFrontendDesignTypedTerminalNode(input.task)) {
+        return await runFrontendDesignTerminalShadow({
+            task: input.task,
+            meta,
+            mapped,
+            tools: designTerminalTools,
+        });
+    }
+    if (isFrontendContractTypedNode(input.task)) {
+        try {
+            await contractTools?.flush?.();
+        }
+        catch {
+            // best-effort flush
+        }
+    }
+    if (isFrontendScoutEvidenceNode(input.task)) {
+        try {
+            await scoutEvidenceTools?.flush?.();
+        }
+        catch {
+            // best-effort flush
+        }
+    }
+    if (isFrontendPlanLedgerNode(input.task)) {
+        try {
+            await planLedgerTools?.flush?.();
+        }
+        catch {
+            // best-effort flush; missing ledger still fails at the node validator
+        }
+    }
     if (!isWriteTask) {
         return mapped;
     }
@@ -723,8 +2318,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             changeManifestChangedFiles = changedFiles;
             // Phase 5: record the attempt changed paths/hashes into the rollback
             // intent so a transient partial write can be CAS-restored.
-            if ((input.task.id === "frontend-implement-pi" ||
-                input.task.id === "frontend-repair-pi") &&
+            if (input.task.id === "frontend-implement-pi" &&
                 (input.task.writeSet?.length ?? 0) > 0) {
                 try {
                     const { recordFrontendWriterAttempt } = await import("../workflows/dag/frontend-writer-recovery.js");
@@ -774,8 +2368,65 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         }
     }
     let writerOutcomeViolation;
+    let factDerivedStatus;
     if (mapped.ok && input.task.writerOutcomePolicy) {
-        if (changeManifestChangedFiles === undefined) {
+        if (isFrontendFactsWriter(input.task)) {
+            // AC-001/AC-003: facts-derived status. The first line is never read;
+            // the legacy validator still runs for the shadow comparison only.
+            try {
+                const { collectFrontendWriterFacts, deriveFrontendWriterStatus, computeFailureFingerprint, compareFactStatusToLegacyOutcome, } = await import("../workflows/dag/frontend-writer-status.js");
+                const facts = await collectFrontendWriterFacts({
+                    sessionEventsPath: path.join(meta.runDir, input.task.id, "session-events.jsonl"),
+                    changedFiles: changeManifestChangedFiles ?? [],
+                    writeGuard: { ok: writeGuardOk, violations: writeGuardViolations },
+                    requirementTargets: [],
+                    coveredRequirementIds: [],
+                    focusedCheckFailures: [],
+                    tokensUsed: result.tokensUsed,
+                    wallTimeMs: Date.now() - started,
+                    rounds: 1,
+                    writeAttempts: attempt,
+                    firstLineText: mapped.assistantText,
+                });
+                const derived = deriveFrontendWriterStatus(facts);
+                factDerivedStatus = derived.status;
+                const legacyValidation = validateWriterImplementationOutcome(mapped.assistantText || mapped.stdout, changeManifestChangedFiles ?? [], {
+                    requireChangedFiles: false,
+                    allowMissingChangedOutcomeWhenDiffPresent: false,
+                });
+                const legacyOutcome = legacyValidation.ok
+                    ? legacyValidation.outcome
+                    : legacyValidation.reason.includes("blocked")
+                        ? "blocked"
+                        : "missing";
+                await writeDagNodeJsonArtifact(meta.runDir, input.task.id, "fact-implementation-status.json", {
+                    schemaVersion: 1,
+                    nodeId: input.task.id,
+                    status: derived.status,
+                    reason: derived.reason,
+                    changedFiles: facts.changedFiles,
+                    writeToolEvents: facts.writeToolEvents,
+                    writeGuardOk: facts.writeGuardOk,
+                    writeGuardViolations: facts.writeGuardViolations,
+                    focusedCheckFailures: facts.focusedCheckFailures,
+                    alreadySatisfiedEvidence: facts.alreadySatisfiedEvidence,
+                    tokensUsed: facts.tokensUsed,
+                    wallTimeMs: facts.wallTimeMs,
+                    rounds: facts.rounds,
+                    writeAttempts: facts.writeAttempts,
+                    failureFingerprint: computeFailureFingerprint(facts),
+                    shadow: compareFactStatusToLegacyOutcome(derived.status, legacyOutcome),
+                });
+                if (derived.status !== "changed" &&
+                    derived.status !== "already-satisfied") {
+                    writerOutcomeViolation = `fact-derived status ${derived.status}: ${derived.reason}`;
+                }
+            }
+            catch (error) {
+                writerOutcomeViolation = `frontend facts derivation failed: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        else if (changeManifestChangedFiles === undefined) {
             writerOutcomeViolation =
                 "writer outcome validation failed: actual diff is unavailable";
         }
@@ -885,31 +2536,42 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     if (meta.writeGuardAttribution === "best-effort") {
         stderrParts.push("write guard note: concurrent rank writers use best-effort per-node attribution; keep same-rank writeSet entries disjoint");
     }
-    // Pure provider stall/timeout with zero workspace side effects is eligible
-    // for a single writer transport retry (implement-pi flake resilience).
-    // Partial writes, tool calls, or write-guard failures keep raw `timeout`.
-    const writerCleanTimeout = !mapped.ok &&
-        mapped.failureCategory === "timeout" &&
-        writeGuardOk &&
+    const rawFailureCategory = mapped.failureCategory;
+    const writeToolCallCount = readWriterThinkingExhaustionEvidence(result).writeToolCallCount;
+    const zeroSideEffects = writeGuardOk &&
         !completenessFailure &&
         !writerThinkingExhausted &&
-        isWriterTransportRetryCandidate(input.task) &&
+        !writerOutcomeViolation &&
         changeManifestChangedFiles !== undefined &&
         changeManifestChangedFiles.length === 0 &&
-        readWriterThinkingExhaustionEvidence(result).writeToolCallCount === 0;
+        writeToolCallCount === 0;
+    const targetCleanTransport = !mapped.ok &&
+        isTargetTemplateTransientRetryNode(input.task) &&
+        rawFailureCategory !== undefined &&
+        ["timeout", "network", "rate-limit", "unavailable"].includes(rawFailureCategory) &&
+        zeroSideEffects;
+    const frontendCleanTimeout = !mapped.ok &&
+        rawFailureCategory === "timeout" &&
+        isWriterTransportRetryCandidate(input.task) &&
+        !isTargetTemplateTransientRetryNode(input.task) &&
+        zeroSideEffects;
+    const writerCleanTimeout = targetCleanTransport || frontendCleanTimeout;
     return {
         ...mapped,
         ok: false,
         stderr: stderrParts.filter(Boolean).join("\n\n"),
+        ...(rawFailureCategory ? { rawFailureCategory } : {}),
         failureCategory: mapped.ok
             ? writeGuardOk
                 ? completenessFailure
                     ? completenessFailure.failureCategory
-                    : changeManifestChangedFiles?.length === 0 &&
-                        isWriterEmptyDiffRetryCandidate(input.task) &&
-                        isChangedWriterImplementationOutcome(mapped.assistantText || mapped.stdout)
+                    : factDerivedStatus === "empty-diff"
                         ? WRITER_EMPTY_DIFF_RETRY_CATEGORY
-                        : "invalid-output"
+                        : changeManifestChangedFiles?.length === 0 &&
+                            isWriterEmptyDiffRetryCandidate(input.task) &&
+                            isChangedWriterImplementationOutcome(mapped.assistantText || mapped.stdout)
+                            ? WRITER_EMPTY_DIFF_RETRY_CATEGORY
+                            : "invalid-output"
                 : "write-guard"
             : // When the attempt already failed with a writer-style category
                 // (empty-output / invalid-output / writer-empty-diff) but the workspace