@tea-agent/loop-agent 0.44.0-next.1 → 0.44.0-next.11

package/dist/application/task-lifecycle/observe.js

@@ -198,6 +198,10 @@ export async function listExplicitlyAssociatedRuns(repoRoot, taskId) {
     const recorded = new Map((record?.runAssociations ?? []).map((entry) => [entry.runId, entry.source]));
     const entries = await listAllDagRunEntries(repoRoot);
     const related = [];
+    // Recency key per run. `runId` is NOT chronological (a later recovery run can
+    // sort before an earlier one lexicographically, e.g. `dag-…` vs `2026…`), so
+    // ordering by runId alone reports a superseded run as the latest.
+    const startedAtByRunId = new Map();
     for (const entry of entries) {
         let source = recorded.get(entry.runId) ?? null;
         let stateStatus;
@@ -207,6 +211,9 @@ export async function listExplicitlyAssociatedRuns(repoRoot, taskId) {
         try {
             const state = await readDagRunState(entry.runDir);
             stateStatus = state.status;
+            if (typeof state.startedAt === "string") {
+                startedAtByRunId.set(entry.runId, state.startedAt);
+            }
             const liveness = assessDagRunLiveness({ state });
             const activeNode = Object.values(state.nodes ?? {}).find((node) => node.status === "RUNNING");
             lastMeaningfulProgressAt =
@@ -266,7 +273,25 @@ export async function listExplicitlyAssociatedRuns(repoRoot, taskId) {
             contractBinding,
         });
     }
-    return related.sort((a, b) => a.runId.localeCompare(b.runId));
+    // Chronological order by run start time; runs without a readable start time
+    // sort first so a run with real timing is never displaced by an unknown.
+    // runId breaks ties deterministically.
+    return related.sort((a, b) => {
+        const aStarted = startedAtByRunId.get(a.runId);
+        const bStarted = startedAtByRunId.get(b.runId);
+        if (aStarted !== bStarted) {
+            if (aStarted === undefined)
+                return -1;
+            if (bStarted === undefined)
+                return 1;
+            const aTime = Date.parse(aStarted);
+            const bTime = Date.parse(bStarted);
+            if (Number.isFinite(aTime) && Number.isFinite(bTime) && aTime !== bTime) {
+                return aTime - bTime;
+            }
+        }
+        return a.runId.localeCompare(b.runId);
+    });
 }
 function deriveLifecycleState(input) {
     if (!input.exists)

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.44.0-next.1",
-  "gitSha": "5c5e91b6ac584b0361b78363ee95483cd37564a5",
-  "builtAt": "2026-09-14T02:24:23.093Z"
+  "version": "0.44.0-next.11",
+  "gitSha": "332db6a894b640eef5c495e3a3ba92b383fcf259",
+  "builtAt": "2026-09-17T05:51:06.283Z"
 }

package/dist/cli/command-definitions.js

@@ -1,4 +1,5 @@
 import { runDoctor } from "../commands/doctor.js";
+import { runPromoteRun } from "../commands/promote-run.js";
 import { runDocsArchive } from "../commands/docs-archive.js";
 import { runDocsAudit } from "../commands/docs-audit.js";
 import { runEval } from "../commands/eval.js";
@@ -197,6 +198,16 @@ export const COMMAND_DEFINITIONS = [
             await runDoctor(adapter, repoRoot, rest.filter((arg) => Boolean(arg)));
         },
     },
+    {
+        name: "promote-run",
+        adapter: "required",
+        tier: "operator",
+        intent: "Promote deterministic evidence from a completed DAG or one-shot run into task artifacts (修改记录.md, 验证结果.md).",
+        usage: "promote-run <task-id> --run-id <run-id>",
+        handler: async ({ adapter, repoRoot, rest }) => {
+            await runPromoteRun(repoRoot, rest.filter((arg) => Boolean(arg)));
+        },
+    },
     {
         name: "docs",
         adapter: "required",

package/dist/cli/program.js

@@ -29,6 +29,7 @@ import { runDocsArchive } from "../commands/docs-archive.js";
 import { runDocsAudit } from "../commands/docs-audit.js";
 import { runEval } from "../commands/eval.js";
 import { runDoctor } from "../commands/doctor.js";
+import { runPromoteRun } from "../commands/promote-run.js";
 import { runExamples } from "../commands/examples.js";
 import { runGoal } from "../commands/goal.js";
 import { runHandoffCheck } from "../commands/handoff-check.js";
@@ -149,6 +150,9 @@ async function runCommanderAction(ctx, command, subcommand, rest) {
         case "doctor":
             await runDoctor(ctx.adapter, ctx.repoRoot, compactArgs([subcommand, ...rest]));
             return;
+        case "promote-run":
+            await runPromoteRun(ctx.repoRoot, compactArgs([subcommand, ...rest]));
+            return;
         case "docs":
             await runDocsCommand(ctx.repoRoot, subcommand, rest);
             return;

package/dist/commands/task-advance.js

@@ -1,3 +1,4 @@
+import { capabilityBoundarySchema } from "../task/config-types.js";
 import { advanceTaskLifecycle, } from "../application/task-lifecycle/index.js";
 import { backendTestConfigSchema, } from "../task/config-types.js";
 import { buildOperatorResult, operatorFailed, processExitCodeForOutcome, writeOperatorJson, } from "../shared/operator/index.js";
@@ -145,13 +146,10 @@ export function parseTaskAdvanceArgs(args) {
         if (token === "--capability-boundary") {
             try {
                 const parsed = JSON.parse(next());
-                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-                    throw new Error("not an object");
-                }
-                options.capabilityBoundary = parsed;
+                options.capabilityBoundary = capabilityBoundarySchema.parse(parsed);
             }
             catch (error) {
-                throw new Error(`--capability-boundary must be a JSON object {allowed?, forbidden?}: ${error.message}`);
+                throw new Error(`--capability-boundary must be a JSON object {allowed?, forbidden?, requiredClauses?}: ${error.message}`);
             }
             continue;
         }

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

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { stdin as stdinStream } from "node:process";
-import { parseAcceptanceFlag, parseVerifyFlag, parseVerifyTimeoutFlag, prepareTaskSource, PREPARE_MAX_FILE_BYTES, } from "../task/source-prepare/index.js";
+import { parseAcceptanceFlag, parseVerifyFlag, parseVerifyLaneFlag, parseVerifyTimeoutFlag, prepareTaskSource, PREPARE_MAX_FILE_BYTES, } from "../task/source-prepare/index.js";
 import { parseTaskContractDraft } from "../task/contract/schema.js";
 import { buildOperatorResult, operatorFailed, processExitCodeForOutcome, writeOperatorJson, } from "../shared/operator/index.js";
 const COMMAND = "task source prepare";
@@ -28,6 +28,7 @@ const USAGE = `usage:
     [--open-question <text>]...
     [--verify <label:command>]...
     [--verify-timeout <label:timeoutMs>]...
+    [--verify-lane <label:static|behavior>]...
     [--request-id <id>]
     [--dry-run | --apply]
     [--force-overwrite-source]
@@ -157,6 +158,10 @@ export function parseTaskSourcePrepareArgs(args) {
             options.verifyTimeout = pushList(options.verifyTimeout, next());
             continue;
         }
+        if (token === "--verify-lane") {
+            options.verifyLane = pushList(options.verifyLane, next());
+            continue;
+        }
         if (token === "--request-id") {
             options.requestId = next();
             continue;
@@ -287,13 +292,20 @@ function buildFlags(options) {
             const parsed = parseVerifyTimeoutFlag(raw);
             timeouts.set(parsed.label, parsed.timeoutMs);
         }
+        const lanes = new Map();
+        for (const raw of options.verifyLane ?? []) {
+            const parsed = parseVerifyLaneFlag(raw);
+            lanes.set(parsed.label, parsed.mode);
+        }
         const commands = (options.verify ?? []).map((raw) => {
             const parsed = parseVerifyFlag(raw);
             const timeoutMs = timeouts.get(parsed.label);
+            const mode = lanes.get(parsed.label);
             return {
                 label: parsed.label,
                 command: parsed.command,
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                ...(mode !== undefined ? { mode } : {}),
             };
         });
         // If only timeouts provided without verify, treat as empty explicit list? No — only set when --verify appears.

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

@@ -0,0 +1,4 @@
+/** DAG Pi 共享类型守卫：纯叶子模块，零依赖，禁止反向依赖执行器入口。 */
+export function isRecordObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/executors/dag-pi/model-config.js

@@ -0,0 +1,30 @@
+/** DAG Pi 模型引用解析：纯配置叶子模块，零依赖，禁止反向依赖执行器入口。 */
+export const DEFAULT_DAG_PI_PROVIDER = "wizard-local";
+export const DAG_PI_MODEL_PROVIDERS = {
+    "gpt-5.3-codex-spark": "wizard-local",
+    "gpt-5.5": "wizard-local",
+    "glm-5.2": "wizard-local",
+    "deepseek-v4-flash": "deepseek",
+    "deepseek-v4-pro": "deepseek",
+};
+export function resolveDagPiModelConfig(modelReference, options) {
+    const separatorIndex = modelReference.indexOf("/");
+    const qualified = separatorIndex >= 0;
+    const provider = qualified
+        ? modelReference.slice(0, separatorIndex)
+        : (DAG_PI_MODEL_PROVIDERS[modelReference] ?? DEFAULT_DAG_PI_PROVIDER);
+    const model = qualified
+        ? modelReference.slice(separatorIndex + 1)
+        : modelReference;
+    if (!provider || !model) {
+        throw new Error(`invalid DAG Pi model reference "${modelReference}": expected non-empty provider/model`);
+    }
+    const explicitThinking = options?.thinking?.trim();
+    const thinking = explicitThinking ??
+        (provider === "wizard-local" && model === "gpt-5.5" ? "low" : undefined);
+    return {
+        provider,
+        model,
+        ...(thinking ? { thinking } : {}),
+    };
+}

package/dist/executors/dag-pi/plan/fact-adoption.js

@@ -0,0 +1,55 @@
+import { routeFrontendProviderCapability } from "../../../workflows/dag/frontend-provider-capability-matrix.js";
+/**
+ * 构建 plan ledger 的 fact adopter。`deps.session` 必须传会话对象本身：adopter 会在**调用时**
+ * 读取 `session.store`（createDurableFrontendTools 每次域工具调用前后会换入 structuredClone 草稿，
+ * 构建时快照会写到过期 store）。
+ */
+export function createPlanFactAdopter(deps) {
+    return 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 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 = deps.stageTypedEventFact({
+                store: deps.session.store,
+                requestId,
+                attemptId: deps.session.attemptId,
+                fact: fact,
+            });
+            const committed = await deps.adoptTypedEventFact({
+                store: deps.session.store,
+                requestId,
+                attemptId: deps.session.attemptId,
+                fact: fact,
+                eventId: staged.eventId,
+                expectedRevision: deps.session.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),
+            };
+        }
+    };
+}

package/dist/{workflows/dag/frontend-plan-completeness.js → executors/dag-pi/plan/facts.js}

@@ -1,4 +1,5 @@
-import { collectCanonicalStateFlowNames } from "./frontend-contract-facts.js";
+/** DAG Pi plan ledger 完整性事实计算：纯类型与纯函数，禁止反向依赖执行器入口。 */
+import { collectCanonicalStateFlowNames } from "../../../workflows/dag/frontend-contract-facts.js";
 export function committedFactFromPlanRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return undefined;
@@ -66,9 +67,16 @@ export function collectFrontendPlanMissingFacts(input) {
             });
             continue;
         }
-        const targetIds = Array.isArray(entry.verificationTargetIds)
+        // Verification targets are the single authoritative direction. The
+        // legacy requirement-side list is accepted only as a fallback while
+        // resuming older ledgers; new plans derive it from target.requirementIds.
+        const derivedTargetIds = [...verificationTargetRequirements.entries()]
+            .filter(([, requirementIds]) => requirementIds.has(id))
+            .map(([targetId]) => targetId);
+        const legacyTargetIds = Array.isArray(entry.verificationTargetIds)
             ? entry.verificationTargetIds.filter((value) => typeof value === "string" && value.trim().length > 0)
             : [];
+        const targetIds = derivedTargetIds.length > 0 ? derivedTargetIds : legacyTargetIds;
         const gap = entry.evidenceGap && typeof entry.evidenceGap === "object"
             ? entry.evidenceGap
             : undefined;
@@ -113,44 +121,31 @@ export function collectFrontendPlanPhaseMissingFacts(input) {
             ];
     }
     if (input.phase === "ux-local") {
-        // One snapshot per check: no cross-revision cache to invalidate.
-        const required = new Set(input.behaviorRequiredRequirementIds ?? []);
-        const requested = new Set(input.requirementIds.filter(id => required.has(id)));
-        if (!requested.size)
-            return [];
-        const byRequirement = new Map();
-        for (const fact of facts) {
-            for (const id of new Set(planFactStringList(fact.scopeRequirementIds))) {
-                if (!requested.has(id))
-                    continue;
-                const entries = byRequirement.get(id) ?? [];
-                entries.push(fact);
-                byRequirement.set(id, entries);
-            }
-        }
-        const liveStateFlow = collectCanonicalStateFlowNames(facts);
         const missing = [];
-        for (const id of input.requirementIds) {
-            if (!required.has(id))
+        // Evaluate each behaviour requirement independently. A fact scoped to AC-1
+        // must not accidentally satisfy AC-2 merely because both ids share one
+        // UX session; shared facts remain valid when they explicitly list both ids.
+        for (const requirementId of input.requirementIds) {
+            if (!input.behaviorRequiredRequirementIds?.includes(requirementId))
                 continue;
-            const scopedFacts = byRequirement.get(id) ?? [];
+            const scopedFacts = facts.filter((fact) => planFactScopeIntersects(fact, new Set([requirementId])));
             const hasChoice = scopedFacts.some((fact) => fact.kind === "component-choice" &&
                 Array.isArray(fact.uiComponentChoices) &&
                 fact.uiComponentChoices.length > 0);
             const canonicalStateFlow = collectCanonicalStateFlowNames(scopedFacts);
-            const hasStateFlow = [...canonicalStateFlow.uiStateNames].some(name => liveStateFlow.uiStateNames.has(name)) ||
-                [...canonicalStateFlow.interactionNames].some(name => liveStateFlow.interactionNames.has(name));
+            const hasStateFlow = canonicalStateFlow.uiStateNames.size > 0 ||
+                canonicalStateFlow.interactionNames.size > 0;
             if (!hasChoice) {
                 missing.push({
                     kind: "component-choice",
-                    requirementIds: [id],
+                    requirementIds: [requirementId],
                     reason: "behaviour-required UX slice has no committed component-choice fact",
                 });
             }
             if (!hasStateFlow) {
                 missing.push({
                     kind: "state-flow",
-                    requirementIds: [id],
+                    requirementIds: [requirementId],
                     reason: "behaviour-required UX slice has no committed state-flow fact",
                 });
             }
@@ -158,9 +153,8 @@ export function collectFrontendPlanPhaseMissingFacts(input) {
         return missing;
     }
     const hasMockApi = facts.some((fact) => fact.kind === "mock-api");
-    const allInteractions = collectCanonicalStateFlowNames(facts).interactionNames;
-    const requested = new Set(input.requirementIds);
-    const liveInteractions = new Set([...collectCanonicalStateFlowNames(facts.filter(f => !planFactStringList(f.scopeRequirementIds).length || planFactScopeIntersects(f, requested))).interactionNames].filter(name => allInteractions.has(name)));
+    const allInteractions = collectCanonicalStateFlowNames(input.committedFacts).interactionNames;
+    const liveInteractions = new Set([...collectCanonicalStateFlowNames(facts.filter(f => !planFactStringList(f.scopeRequirementIds).length || planFactScopeIntersects(f, new Set(input.requirementIds)))).interactionNames].filter(name => allInteractions.has(name)));
     const coveredInteractions = new Set(facts
         .filter((fact) => fact.kind === "data-flow")
         .flatMap((fact) => planFactStringList(fact.interactions)));

package/dist/executors/dag-pi/plan/finalize-tools.js

@@ -0,0 +1,259 @@
+import { loadContractRequirementInheritance } from "./ledger-contract.js";
+import { collectFrontendPlanPhaseMissingFacts } from "./facts.js";
+import { planToolReceipt, stringList } from "./tool-helpers.js";
+import { collectCanonicalStateFlowNames } from "../../../workflows/dag/frontend-contract-facts.js";
+import { isRecordObject } from "../guards.js";
+import { randomUUID } from "node:crypto";
+export function buildPlanFinalizeTools(ctx) {
+    const { Type, defineTool, session, schemas, input, readCommittedEvents, assemblePlanPatchFromCommittedFacts, contractInheritance, adoptStagedFact, adoptPlanFact } = ctx;
+    const { optionalString, optionalStringArray } = ctx.schemas;
+    const finalizePlanTool = defineTool({
+        name: "finalize_plan",
+        label: "finalize_plan",
+        description: "Commit the finalize_plan terminal. Requirements, verification targets, and evidence gaps (optional) were already committed incrementally through record_plan_requirement / record_plan_verification_target / record_plan_evidence_gap; finalize_plan assembles them from the ledger together with these optional remaining fields, publishes the canonical editable patch on a target-surface fact, and commits the terminal. A successful terminal commit occurs exactly once. If validation fails, correct only the reported facts and retry finalize.",
+        promptSnippet: "Commit the finalize_plan terminal (ledger fields + optional residualRisks / realIntegrationGap).",
+        parameters: Type.Object({
+            residualRisks: optionalStringArray,
+            realIntegrationGap: optionalString,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const committed = readCommittedEvents(session.store, session.attemptId);
+                // Source fidelity ledger (AC-005/AC-006): inherit the contract
+                // node's declared requirement→fragment provenance so the compiled
+                // canonical contract carries sourceFragmentIds/sourceRefs even
+                // when the plan did not re-declare them. The contract node is the
+                // sole synthesis point; the plan inherits by requirement id.
+                const contractInheritance = await loadContractRequirementInheritance(input.runDir);
+                const missingData = collectFrontendPlanPhaseMissingFacts({ phase: "global-mock-data", requirementIds: input.requirementIds ?? [...contractInheritance.keys()], committedFacts: committed }).filter(f => f.kind === "data-flow");
+                if (missingData.length)
+                    return planToolReceipt({ ok: false, kind: "finalize_plan", code: "PLAN_DATA_FLOW_INCOMPLETE", error: missingData.map(f => f.reason).join("; ") });
+                const fragment = assemblePlanPatchFromCommittedFacts(committed, contractInheritance) ?? {};
+                const patch = {
+                    ...fragment,
+                    ...(params?.residualRisks
+                        ? { residualRisks: params.residualRisks }
+                        : {}),
+                    ...(params?.realIntegrationGap
+                        ? { realIntegrationGap: params.realIntegrationGap }
+                        : {}),
+                };
+                const latestRegistry = [...committed]
+                    .reverse()
+                    .map((record) => record.fact)
+                    .find((fact) => isRecordObject(fact) && fact.kind === "state-registry");
+                if (latestRegistry) {
+                    const registryUiStates = new Set(stringList(latestRegistry.uiStateNames));
+                    const registryInteractions = new Set(stringList(latestRegistry.interactionNames));
+                    const live = collectCanonicalStateFlowNames(committed);
+                    const missingUiStates = [...registryUiStates].filter((name) => !live.uiStateNames.has(name));
+                    const missingInteractions = [...registryInteractions].filter((name) => !live.interactionNames.has(name));
+                    const undeclaredUiStates = [...live.uiStateNames].filter((name) => !registryUiStates.has(name));
+                    const undeclaredInteractions = [...live.interactionNames].filter((name) => !registryInteractions.has(name));
+                    if (missingUiStates.length > 0 ||
+                        missingInteractions.length > 0 ||
+                        undeclaredUiStates.length > 0 ||
+                        undeclaredInteractions.length > 0) {
+                        return planToolReceipt({
+                            ok: false,
+                            kind: "finalize_plan",
+                            error: `finalize_plan UX registry mismatch: every registered name must have one live state-flow entry and every live entry must be registered (missing uiStates: ${missingUiStates.join(", ") || "none"}; missing interactions: ${missingInteractions.join(", ") || "none"}; undeclared uiStates: ${undeclaredUiStates.join(", ") || "none"}; undeclared interactions: ${undeclaredInteractions.join(", ") || "none"})`,
+                        });
+                    }
+                }
+                // Front-load the node's compile + policy gates into the finalize
+                // receipt (same pipeline the design-policy shell and the node
+                // self-check run: merge the patch onto the runtime skeleton,
+                // then the full analyze). A failing gate used to burn an entire
+                // attempt per finding (r8/r9: ui-design-coverage, verification
+                // targets, UI-state shape, one attempt each); surfaced here the
+                // model fixes the facts and re-calls finalize_plan in-node.
+                if (input.skeleton && input.sourceBinding) {
+                    // Front-load the exact pipeline the design-policy shell and
+                    // the node self-check run (patch ⊕ skeleton -> analyze ->
+                    // policy pre-checks) into the finalize receipt. Findings
+                    // come back as fixable receipt errors instead of burning
+                    // an attempt per gate (r8/r9: coverage, verification
+                    // targets, UI-state shape each cost a full attempt).
+                    const { analyzeFrontendPlanPatchCandidate, applyFrontendContractMergePatch, FrontendContractFailure, PlanPolicyPrecheckFailure, serializeDeterministicJson, } = await import("../../../workflows/dag/frontend-implementation-contract.js");
+                    try {
+                        const merged = applyFrontendContractMergePatch(input.skeleton, patch);
+                        await analyzeFrontendPlanPatchCandidate({
+                            runDir: input.runDir,
+                            rawContractText: serializeDeterministicJson(merged),
+                            sourceBinding: input.sourceBinding,
+                        });
+                    }
+                    catch (error) {
+                        if (error instanceof PlanPolicyPrecheckFailure) {
+                            // Template the fix: every uncovered interaction / state
+                            // maps to a record_component_choice skeleton. Reuse is
+                            // never implied: the operator/model must fill an existing
+                            // evidencePath or switch the choice to decision=new with
+                            // the required frozen source citation.
+                            const suggestions = error.findings
+                                .filter((finding) => finding.code === "ui-design-coverage-missing" &&
+                                finding.path)
+                                .map((finding) => ({
+                                tool: "record_component_choice",
+                                args: {
+                                    choice: {
+                                        purpose: finding.path,
+                                        component: "<name the existing or new component>",
+                                        decision: "reuse-existing",
+                                        evidencePath: "<existing repo file that proves this reuse>",
+                                    },
+                                },
+                            }));
+                            const suggestionBlock = suggestions.length > 0
+                                ? ` Suggested record_* calls (copy, fill component, submit): ${JSON.stringify(suggestions)}`
+                                : "";
+                            return planToolReceipt({
+                                ok: false,
+                                kind: "finalize_plan",
+                                error: `finalize_plan pre-validation failed (fix the listed plan facts with record_* tools, then call finalize_plan again): ${error.message}${suggestionBlock}`,
+                            });
+                        }
+                        if (!(error instanceof FrontendContractFailure))
+                            throw error;
+                        return planToolReceipt({
+                            ok: false,
+                            kind: "finalize_plan",
+                            error: `finalize_plan pre-validation failed (fix the listed plan facts with record_* tools, then call finalize_plan again): ${error.message}`,
+                        });
+                    }
+                }
+                const patchResult = await adoptPlanFact("target-surface", `${session.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", `${session.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: session.store,
+                    requestId: typeof params?.requestId === "string" ? params.requestId : "",
+                    attemptId: session.attemptId,
+                    eventId: typeof params?.eventId === "string" ? params.eventId : "",
+                    expectedRevision: typeof params?.expectedRevision === "number"
+                        ? params.expectedRevision
+                        : session.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,
+                });
+            }
+        },
+    });
+    const readPlanFactsTool = defineTool({
+        name: "read_plan_facts",
+        label: "read_plan_facts",
+        description: "Read the LIVE committed plan ledger without repository access. Filter by kind and optional entryId or eventId. Use field (dot path, e.g. entry.requirementIds or uiStates) to page large arrays/strings. offset/limit paginate results; follow nextOffset until null before replacing any full-array fact. expectedRevision pins all pages to one ledger revision; restart if it changes. No writes.",
+        parameters: Type.Object({
+            kind: Type.String(), entryId: Type.Optional(Type.String()), eventId: Type.Optional(Type.String()),
+            field: Type.Optional(Type.String()), offset: Type.Optional(Type.Integer({ minimum: 0 })),
+            limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+            stringOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+            expectedRevision: Type.Optional(Type.Integer({ minimum: 0 })),
+        }, { additionalProperties: false }),
+        async execute(_id, params) {
+            const reply = (details) => ({ content: [{ type: "text", text: JSON.stringify(details) }], details });
+            if (params.expectedRevision !== undefined && params.expectedRevision !== session.store.revision) {
+                return reply({ ok: false, revision: session.store.revision, error: "ledger revision changed; restart pagination" });
+            }
+            let records = readCommittedEvents(session.store, session.attemptId).filter(record => {
+                const fact = record.fact;
+                return fact.kind === params.kind && (!params.eventId || record.eventId === params.eventId) &&
+                    (!params.entryId || fact.entry?.id === params.entryId);
+            });
+            // Full-entry corrections and registries are last-wins. Other kinds
+            // remain an ordered event log (state removals must remain visible).
+            if (params.entryId || params.kind === "state-registry")
+                records = records.slice(-1);
+            let values = records.map(record => ({ eventId: record.eventId, ...record.fact }));
+            if (params.field) {
+                values = records.flatMap(record => {
+                    let value = record.fact;
+                    for (const key of params.field.split(".")) {
+                        if (!value || typeof value !== "object" || !Object.hasOwn(value, key))
+                            return [];
+                        value = value[key];
+                    }
+                    return Array.isArray(value) ? value : [value];
+                });
+            }
+            const offset = params.offset ?? 0;
+            if (params.stringOffset !== undefined) {
+                const value = values[offset];
+                if (typeof value !== "string")
+                    return reply({ ok: false, error: "stringOffset requires a string field item" });
+                // Unicode code points prevent a page boundary splitting a surrogate pair.
+                const characters = Array.from(value);
+                const chunk = characters.slice(params.stringOffset, params.stringOffset + 1000).join("");
+                const next = params.stringOffset + Array.from(chunk).length;
+                return reply({ ok: true, revision: session.store.revision, offset, stringOffset: params.stringOffset,
+                    chunk, totalCharacters: characters.length, nextStringOffset: next < characters.length ? next : null });
+            }
+            const items = [];
+            let bytes = 0;
+            for (const value of values.slice(offset, offset + (params.limit ?? 10))) {
+                const size = Buffer.byteLength(JSON.stringify(value));
+                if (bytes + size > 12_000)
+                    break;
+                bytes += size;
+                items.push(value);
+            }
+            if (!items.length && offset < values.length)
+                return reply({
+                    ok: false, revision: session.store.revision, total: values.length, offset,
+                    error: "item exceeds the page budget; select an eventId/entryId and a narrower field path; for a string item set stringOffset: 0 and follow nextStringOffset",
+                    fields: typeof values[offset] === "object" && values[offset] !== null ? Object.keys(values[offset]) : [],
+                });
+            return reply({ ok: true, revision: session.store.revision, total: values.length, offset, items,
+                nextOffset: offset + items.length < values.length ? offset + items.length : null });
+        },
+    });
+    return {
+        finalizePlanTool,
+        adoptStagedFactTool,
+        readPlanFactsTool,
+    };
+}