@tea-agent/loop-agent 0.43.0-next.1 → 0.43.0-next.10

package/dist/workflows/dag/node-execution.js

@@ -1,3 +1,5 @@
+import { collectFrontendExecutionGroups } from "./frontend-execution-groups.js";
+import { reserveDagProviderRequest } from "./budget-enforcement.js";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
@@ -297,6 +299,12 @@ export function buildContextOverflowRetryPrompt(task, basePrompt) {
             compactRetrySection(basePrompt, "task", COMPACT_RETRY_TASK_MAX_CHARS),
             "</task>",
         ].join("\n"),
+        // Plan still needs the complete frozen obligations for ledger ownership
+        // and scoped projection. Its executor packs this block before dispatch;
+        // dropping or character-truncating it prevents safe progress recovery.
+        ...(isFrontendPlanLadderTask(task)
+            ? [basePrompt.match(/<frontend_plan_input>[\s\S]*?<\/frontend_plan_input>/)?.[0] ?? ""]
+            : []),
     ].join("\n\n");
 }
 function isFrontendPlanLadderTask(task) {
@@ -380,27 +388,14 @@ async function readFrontendPlanCommittedSnapshot(runDir, nodeId) {
 function planInputRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function planInputText(value, maxChars = 240) {
-    if (typeof value !== "string" || value.trim().length === 0)
-        return undefined;
-    const normalized = value.trim();
-    return normalized.length <= maxChars
-        ? normalized
-        : `${normalized.slice(0, maxChars - 1)}…`;
+function planInputText(value, _maxChars) {
+    return typeof value === "string" && value.trim().length ? value.trim() : undefined;
 }
 function planInputStrings(value) {
     return Array.isArray(value)
         ? value.filter((item) => typeof item === "string")
         : [];
 }
-/** Input bound for the planner evidence block; protects the model input budget. */
-const FRONTEND_PLAN_INPUT_MAX_CHARS = 12_000;
-const FRONTEND_PLAN_INPUT_CAP_LADDER = [
-    { text: 240, array: 40 },
-    { text: 120, array: 20 },
-    { text: 60, array: 10 },
-    { text: 24, array: 4 },
-];
 /**
  * Frozen requirement→PRD citation map for the plan review checklist: lets the
  * model declare sourceRequirementIds whose section/line match the component
@@ -446,78 +441,19 @@ async function resolveComponentSourceCitations(spec, cwd) {
         return new Map();
     }
 }
-/** Input bound for the contract node's compiled ledger block. */
-const FRONTEND_CONTRACT_INPUT_MAX_CHARS = 12_000;
 /**
- * Render the contract node's complete-but-bounded ledger handoff. The
+ * Render the contract node's complete semantic ledger handoff. The
  * source-fidelity ledger already extracted canonical requirements with source
  * spans; the contract node confirms and commits them incrementally through
  * record_requirement instead of re-reading the raw source (extreme-environment:
  * a small output window cannot absorb a full source re-read).
  *
- * Same shape guarantees as the plan input block: always valid JSON under the
- * char bound, ids never drop, texts degrade through the cap ladder.
+ * Whole obligations are retained here; the executor selects complete scopes
+ * before dispatch. References and conditions are never clipped.
  */
 export function renderFrontendContractInputContext(input) {
-    // Fragment bindings are ids, not prose: they are the one thing the contract
-    // must never lose. r6 regression — the last-resort degradation dropped
-    // sourceFragmentIds entirely, the model (correctly refusing to invent ids)
-    // committed empty bindings, and the plan compile failed the ledger-binding
-    // gate for every requirement. Bindings therefore bypass the cap ladder and
-    // every degradation level; only requirement TEXTS and fragment CONTEXT
-    // (path/headingPath) may degrade. Fragment context is rendered only for
-    // fragments actually referenced by a requirement and shrinks first.
-    const referencedFragmentIds = new Set(input.canonicalRequirements.flatMap((requirement) => planInputStrings(requirement.sourceFragmentIds)));
-    const referencedFragments = input.fragments.filter((fragment) => referencedFragmentIds.has(fragment.id));
-    const serializeAtCap = (cap) => JSON.stringify({
-        requirements: input.canonicalRequirements.map((requirement) => ({
-            id: requirement.id,
-            text: planInputText(requirement.text, cap.text),
-            sourceFragmentIds: planInputStrings(requirement.sourceFragmentIds),
-        })),
-        fragments: referencedFragments.map((fragment) => ({
-            id: fragment.id,
-            path: planInputText(fragment.path, 200),
-            headingPath: planInputText(fragment.headingPath, 120),
-            lineRange: fragment.lineRange,
-        })),
-    });
-    let serialized = serializeAtCap(FRONTEND_PLAN_INPUT_CAP_LADDER[0]);
-    for (const cap of FRONTEND_PLAN_INPUT_CAP_LADDER.slice(1)) {
-        if (serialized.length <= FRONTEND_CONTRACT_INPUT_MAX_CHARS)
-            break;
-        serialized = serializeAtCap(cap);
-    }
-    if (serialized.length > FRONTEND_CONTRACT_INPUT_MAX_CHARS) {
-        // Last resort: keep every requirement id AND its fragment bindings,
-        // degrade texts, and shrink referenced fragment context first (halve,
-        // then drop context fields, then drop the fragment list entirely).
-        // Requirement ids and sourceFragmentIds are never dropped.
-        let fragments = referencedFragments.map((fragment) => ({
-            id: fragment.id,
-            path: planInputText(fragment.path, 120),
-        }));
-        let requirements = input.canonicalRequirements.map((requirement) => {
-            const sourceFragmentIds = planInputStrings(requirement.sourceFragmentIds);
-            return {
-                id: requirement.id,
-                text: "(truncated)",
-                // Empty bindings carry no information; omit them so the payload
-                // stays inside the char bound when no requirement is bound.
-                ...(sourceFragmentIds.length > 0 ? { sourceFragmentIds } : {}),
-            };
-        });
-        let bounded = JSON.stringify({ degraded: "requirement-texts-truncated", requirements, fragments });
-        while (bounded.length > FRONTEND_CONTRACT_INPUT_MAX_CHARS && fragments.length > 0) {
-            fragments = fragments.slice(0, Math.floor(fragments.length / 2));
-            bounded = JSON.stringify({
-                degraded: "requirement-texts-truncated",
-                requirements,
-                fragments,
-            });
-        }
-        serialized = bounded;
-    }
+    const referenced = new Set(input.canonicalRequirements.flatMap(r => r.sourceFragmentIds));
+    const serialized = JSON.stringify({ requirements: input.canonicalRequirements, fragments: input.fragments.filter(f => referenced.has(f.id)) });
     return [
         "<frontend_contract_input>",
         "Canonical requirements extracted by the source-fidelity ledger, compiled by the runner. Treat them as the authoritative requirement inventory: confirm and commit each requirement through record_requirement (one per tool call); the ledger already binds source fragments, so do NOT re-read the raw source files.",
@@ -542,16 +478,13 @@ export async function buildFrontendContractInputContext(input) {
     });
 }
 /**
- * Render the planner's complete-but-bounded evidence handoff from committed
+ * Render the planner's complete semantic evidence handoff from committed
  * typed facts. It deliberately excludes upstream response prose and artifact
  * paths: Contract and Scout have already established these facts, so Plan
  * should decide and commit rather than spend another model turn reading them.
  *
- * The block is always valid JSON under the char bound: field texts shrink
- * through a cap ladder before any fact is dropped, and the last-resort
- * fallback keeps every requirement id (with `text: "(truncated)"`) while
- * declaring the degradation, so the planner records targeted evidence gaps
- * instead of receiving a silently corrupted tail.
+ * Whole obligations are retained. Session packing and scoped projection happen
+ * in the executor before dispatch, without dropping text or source identities.
  */
 export function renderFrontendPlanInputContext(input) {
     const committedFacts = (records) => records.flatMap((record) => record.phase === "committed" && planInputRecord(record.fact)
@@ -610,77 +543,12 @@ export function renderFrontendPlanInputContext(input) {
     const behaviorRequiredIds = requirementFacts
         .filter((requirement) => requirement.evidence.behavior === "required")
         .map((requirement) => requirement.id);
-    const serializeAtCap = (cap) => JSON.stringify({
-        requirements: requirements.map((requirement) => ({
-            id: requirement.id,
-            text: planInputText(requirement.text, cap.text),
-            sourceFragmentIds: planInputStrings(requirement.sourceFragmentIds).slice(0, cap.array),
-        })),
-        requiredDeliverables,
-        targetSurface: targetSurface.map((surface) => ({
-            completeness: planInputText(surface.completeness, 32),
-            entrypoint: planInputText(surface.entrypoint, cap.text),
-            routeOrMount: planInputText(surface.routeOrMount, cap.text),
-            implementationPaths: planInputStrings(surface.implementationPaths).slice(0, cap.array),
-            testPaths: planInputStrings(surface.testPaths).slice(0, cap.array),
-            dataSource: planInputText(surface.dataSource, cap.text),
-            allowedPathConflicts: planInputStrings(surface.allowedPathConflicts).slice(0, cap.array),
-            unresolvedPaths: planInputStrings(surface.unresolvedPaths).slice(0, cap.array),
-        })),
-        designEvidence: designEvidence.map((evidence) => ({
-            source: planInputText(evidence.source, cap.text),
-            paths: planInputStrings(evidence.paths).slice(0, cap.array),
-            conflicts: planInputStrings(evidence.conflicts).slice(0, cap.array),
-        })),
-        declaredUiStates: declaredUiStates.map((state) => ({
-            id: state.id,
-            trigger: planInputText(state.trigger, cap.text),
-            observableOutcome: planInputText(state.observableOutcome, cap.text),
-        })),
-        committedUx: committedUiStateNames.length > 0 ||
-            committedInteractionNames.length > 0
-            ? {
-                uiStateNames: committedUiStateNames,
-                interactionNames: committedInteractionNames,
-            }
-            : undefined,
+    const serialized = JSON.stringify({
+        requirements, requiredDeliverables, targetSurface, designEvidence, declaredUiStates,
+        executionGroups: collectFrontendExecutionGroups(contractFacts.filter(f => f.kind === "requirement").map(f => ({ id: String(f.id), execution: f.execution }))),
+        constraints: contractFacts.filter(f => ["constraint", "open-question", "split-proposal", "handoff-intent"].includes(String(f.kind))),
+        committedUx: committedUiStateNames.length || committedInteractionNames.length ? { uiStateNames: committedUiStateNames, interactionNames: committedInteractionNames } : undefined,
     });
-    let serialized = serializeAtCap(FRONTEND_PLAN_INPUT_CAP_LADDER[0]);
-    for (const cap of FRONTEND_PLAN_INPUT_CAP_LADDER.slice(1)) {
-        if (serialized.length <= FRONTEND_PLAN_INPUT_MAX_CHARS)
-            break;
-        serialized = serializeAtCap(cap);
-    }
-    if (serialized.length > FRONTEND_PLAN_INPUT_MAX_CHARS) {
-        // Last resort: keep every requirement id (ids are short and the plan
-        // prompt separately lists them) but drop their texts, shrink scout facts
-        // to the minimum, and declare the degradation instead of corrupting JSON.
-        let fallback = {
-            degraded: "requirement-texts-truncated",
-            requiredDeliverables,
-            requirements: requirements.map((requirement) => ({
-                id: requirement.id,
-                text: "(truncated)",
-            })),
-            targetSurface: targetSurface.map((surface) => ({
-                completeness: planInputText(surface.completeness, 32),
-                implementationPaths: planInputStrings(surface.implementationPaths).slice(0, FRONTEND_PLAN_INPUT_CAP_LADDER[3].array),
-            })),
-            designEvidence: [],
-        };
-        let bounded = JSON.stringify(fallback);
-        let keep = fallback.requirements.length;
-        while (bounded.length > FRONTEND_PLAN_INPUT_MAX_CHARS &&
-            keep > 0) {
-            keep = Math.max(0, Math.floor(keep / 2));
-            fallback = { ...fallback, requirements: fallback.requirements.slice(0, keep) };
-            bounded = JSON.stringify({
-                ...fallback,
-                requirementIdsTruncated: keep < requirements.length,
-            });
-        }
-        serialized = bounded;
-    }
     const checklistLines = [
         "1. Record the GLOBAL UX vocabulary with record_state_registry BEFORE any record_state_flow: one stable behavior-domain name per state/interaction (e.g. planner-task-edit), never one name per AC number, and never a rename of an already-recorded concept. Coverage slices by AC; UX does not.",
         "2. Every recorded interaction/uiState name must be in that registry, and uiState names must use the contract's declared authoritative ids (declaredUiStates below) when present.",
@@ -1583,6 +1451,20 @@ export async function executeDagNode(input) {
             return;
         }
     }
+    if (task.id === "frontend-scout-pi") {
+        try {
+            const { readTypedEventStoreFromJsonl } = await import("./frontend-typed-event-store.js");
+            const facts = (await readTypedEventStoreFromJsonl(path.join(runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"))).filter(r => r.phase === "committed").map(r => r.fact);
+            const requirements = [...new Map(facts.filter(f => f.kind === "requirement").map(f => [String(f.id), f])).values()];
+            if (!requirements.length)
+                throw Error("FRONTEND_INPUT_MISSING: Scout needs committed Contract obligations");
+            prompt += `\n<frontend_scout_input>\n${JSON.stringify({ requirements, sharedFacts: facts.filter(f => !["requirement", "contract-scope-completed", "contract-finalized"].includes(String(f.kind))) })}\n</frontend_scout_input>`;
+        }
+        catch (error) {
+            await failBeforePrompt(error, "frontend-scout-input-unavailable");
+            return;
+        }
+    }
     if (FRONTEND_WRITER_NODE_IDS.includes(nodeId)) {
         // Design-review findings are not reliable in the provider's prose output
         // (typed terminal nodes commonly return an empty assistant message). Inject
@@ -1770,6 +1652,7 @@ export async function executeDagNode(input) {
                 attemptPrompt,
             });
             result = await executeNode({
+                ...(state.budgetLedger?.mode === "hard" && state.budgetLedger.limits.maxProviderRequests !== undefined ? { reserveProviderRequest: () => reserveDagProviderRequest({ state, nodeId, attempt: attemptNumber, persist: input.persistState }) } : {}),
                 task,
                 cwd,
                 model,

package/dist/workflows/dag/prompt.js

@@ -136,6 +136,10 @@ export function buildUpstreamContext(task, upstream, maxChars = MAX_UPSTREAM_CHA
     const consumedArtifactIds = new Set((task.consumesArtifacts ?? []).map((binding) => binding.artifactId));
     for (const depId of task.depends_on) {
         const record = upstream[depId];
+        if (task.id === "frontend-scout-pi" && depId === "frontend-contract-pi" && record?.status === "FINISHED") {
+            sections.push(`## Upstream output: ${depId}\nCommitted Contract obligations are supplied in frontend_scout_input. Do not reconstruct them from prose or reread the source.`);
+            continue;
+        }
         const stdout = record?.stdout?.trim() ? record.stdout : "";
         const assistantText = record?.assistantText?.trim()
             ? record.assistantText

package/dist/workflows/dag/rerun-plan.js

@@ -46,6 +46,7 @@ const highRiskContinuationAuthorityV1Schema = z
             tokens: z.number().int().nonnegative().nullable(),
             wallTimeMs: z.number().nonnegative(),
             executorCalls: z.number().int().nonnegative(),
+            providerRequests: z.number().int().nonnegative().optional(),
             repairPasses: z.number().int().nonnegative(),
             peakContextChars: z.number().int().nonnegative(),
             missingTokenNodeIds: z.array(z.string()),
@@ -1300,7 +1301,12 @@ export async function evaluateDagRerunPlan(input) {
             const task = tasksByIdForPlan.get(nodeId);
             return task?.readSet ?? [];
         });
-        const scopedDrift = driftedPaths !== undefined &&
+        // An omitted or empty readSet is unrestricted, not proof that an
+        // imported node read nothing. Localize drift only when every reused
+        // node has an explicit reading boundary.
+        const importedReadSetsKnown = importedNodeIds.every((nodeId) => (tasksByIdForPlan.get(nodeId)?.readSet?.length ?? 0) > 0);
+        const scopedDrift = importedReadSetsKnown &&
+            driftedPaths !== undefined &&
             driftedPaths.length > 0 &&
             driftedPaths.every((driftPath) => !importedReadPaths.some((pattern) => pathMatchesWorkspacePattern(driftPath, pattern)) &&
                 resetNodeIds.some((nodeId) => {

package/dist/workflows/dag/runner.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { isHardBudgetBreached, resolveEffectiveMaxConcurrent, } from "../../application/evaluation/budget.js";
 import { readCandidateRecord } from "../../infrastructure/evaluation/candidate-store.js";
 import { CANONICAL_TASK_ID_PATTERN, formatLocalCompactDate, } from "../../task/runtime.js";
-import { assertFrozenBudget, initRunBudgetLedger, preflightBudgetOrBreach, recordFinishedNodeBudget, writeBudgetLedgerArtifacts, } from "./budget-enforcement.js";
+import { assertFrozenBudget, initRunBudgetLedger, preflightBudgetOrBreach, recordFinishedNodeBudget, validateCumulativeBudgetSuccessor, writeBudgetLedgerArtifacts, } from "./budget-enforcement.js";
 import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readHumanApprovalArtifact, readDagRunState, requireActiveDagRun, } from "./lifecycle.js";
 import { markInterruptNeedsReconcile, mergeAbortSignals, readInterruptRequest, runnerIdentityFromState, settleDagInterrupt, startInterruptWatcher, } from "./interrupt-request.js";
 import { moveToCompletedRunDir, moveToPausedRunDir, prepareRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
@@ -887,6 +887,31 @@ async function executeDagCheckpoint(input) {
                         observeOnly: created.kind === "observed",
                         deps: {
                             ...input.recovery,
+                            budget: input.recovery.budget ?? state.budget,
+                            readLedgers: input.recovery.readLedgers ?? (async () => {
+                                if (!state.budget)
+                                    return [];
+                                const location = await locateDagRun(cwd, state.runId);
+                                let current = await readDagRunState(location?.runDir ?? runDir);
+                                const visited = new Set([current.runId]);
+                                while (current.frontendRecoveryState?.parentRunId === current.runId && current.frontendRecoveryState.childRunId && current.frontendRecoveryState.childRunId !== current.runId) {
+                                    if (["child-staging", "child-activating"].includes(current.frontendRecoveryState.phase))
+                                        break;
+                                    const childId = current.frontendRecoveryState.childRunId;
+                                    if (visited.has(childId))
+                                        throw Error("FRONTEND_PROVIDER_BUDGET_LINEAGE_INVALID: cyclic recovery");
+                                    visited.add(childId);
+                                    const childLocation = await locateDagRun(cwd, childId);
+                                    if (!childLocation)
+                                        throw Error("FRONTEND_PROVIDER_BUDGET_LINEAGE_INVALID: missing recovery child");
+                                    const child = await readDagRunState(childLocation.runDir);
+                                    validateCumulativeBudgetSuccessor(current, child);
+                                    current = child;
+                                }
+                                if (!current.budgetLedger)
+                                    throw Error("FRONTEND_PROVIDER_BUDGET_INVALID: recovery ledger missing");
+                                return [current.budgetLedger];
+                            }),
                             failureOwner: input.recovery.failureOwner ??
                                 recoveryTrigger.failureOwner,
                             protocolFailureReason: input.recovery.protocolFailureReason ??

package/dist/workflows/dag/types.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { frontendExecutionPolicySchema } from "../../shared/frontend-execution-policy.js";
 import { DEFAULT_FRONTEND_SPEC_ROOTS, isFrontendSpecFilePath, isValidFrontendSpecRoot, OPENSPEC_SPEC_EXT_RE, } from "../../shared/openspec-spec.js";
 import { campaignBudgetSchema, } from "../../application/evaluation/budget.js";
 import { assertDagPromptSourceRule } from "./prompt-source.js";
@@ -1385,6 +1386,7 @@ export const dagSpecSchema = z
     evaluation: dagEvaluationBindingSchema.optional(),
     /** Optional hard/record-only budget; requires version 3 or 4. */
     budget: dagBudgetSchema.optional(),
+    frontendExecutionPolicy: frontendExecutionPolicySchema.optional(),
     sourceBinding: dagSourceBindingSchema.optional(),
     /** v4 managed Task Contract binding; only valid on version 4. */
     taskContractBinding: dagTaskContractBindingSchema.optional(),
@@ -1567,6 +1569,10 @@ export const frontendRecoveryStateSchema = z
     recoveryRootRunId: z.string().min(1),
     parentRunId: z.string().min(1),
     childRunId: z.string().min(1).optional(),
+    budgetLineage: z.object({
+        parentLedgerSha256: z.string().regex(/^[a-f0-9]{64}$/), inheritedAt: z.string().datetime(),
+        inheritedConsumed: z.object({ tokens: z.number().nonnegative().nullable(), wallTimeMs: z.number().nonnegative(), executorCalls: z.number().int().nonnegative(), providerRequests: z.number().int().nonnegative().optional(), repairPasses: z.number().int().nonnegative(), peakContextChars: z.number().int().nonnegative(), missingTokenNodeIds: z.array(z.string()) }).strict(),
+    }).strict().optional(),
     attemptId: z.string().min(1),
     attemptIndex: z.number().int().min(0).max(5),
     continuationCount: z.number().int().min(0).max(5),

package/docs/operations/README.md

@@ -9,6 +9,7 @@
 - [`github-collaboration.md`](github-collaboration.md)：仓库内 GitHub 协作约定及发布通道。
 - [`version-and-release-management.md`](version-and-release-management.md)：版本发布管理——next / release-x.y / latest 渠道、移动式 `npm-next` ref、`inspect next` 查询入口、workflow 与 promote 手册。
 - [`production-readiness.md`](production-readiness.md)：交付前的生产就绪判断。
+- [`frontend-reliability-canary-runbook.md`](frontend-reliability-canary-runbook.md)：frontend 可靠性修复的 live canary 内网执行手册（协议冻结自 exec-plan §17；配对矩阵、证据注册与人工晋升门）。
 - [`agent-worker-production-readiness.md`](agent-worker-production-readiness.md)：agent-worker Feature/Task Pool 外层编排的 Production Readiness v1 操作合同。
 - [`backend-test-jacoco-coverage.md`](backend-test-jacoco-coverage.md)：Java 被测服务挂载 JaCoCo tcpserver agent 的 Maven、`java -jar` 与 Docker 操作手册。
 - [`console-chat-dogfood-playbook.md`](console-chat-dogfood-playbook.md)：Operator Chat（含 Explore 子 Agent）真实模型 dogfood 的 CLI 驱动步骤、mutation 双 token / SSE 超时 / question 应答等已知陷阱与验证方式。

package/docs/templates/frontend-design-contract.md

@@ -61,8 +61,8 @@
 - **DAG 如何消费**：进入 `evidenceGaps[]` 与 Non-goals，`frontend-review-pi`/closeout 据它保留风险与后续项。
 - **缺失/冲突时 fail-closed**：范围与需求非目标冲突、或风险被隐藏时阻塞。
 
-## OpenSpec 引用块（openspec-citations）
+## OpenSpec 来源与引用
 
-- **要写什么**：在 fenced `json` 契约块之后追加**恰好一个** fenced `openspec-citations` 块，每行一个 JSON `{"path","section","line"}`（`section` 可空串、`line` 为 int 或 null），逐条列出本计划实际读取并应用的每个 openspec 规范文件。
-- **DAG 如何消费**：`frontend-prewrite-gate-shell` 按 fence 语言标签解析该块，并与生效 plan/review 节点的成功 read 事件核验；`cited` 模式下候选未引用 → `openspec-not-cited`，引用无 read 背书 → `openspec-citation-not-read`，块缺失/不可解析 → `openspec-citation-block-unparseable`。
-- **缺失/冲突时 fail-closed**：候选非空而引用块缺失/不可解析、候选未引用、或引用未真实读取时，prewrite gate 以 `retryable-invalid` fail-closed；不要引用未读取的路径，也不要遗漏已读取的 openspec 文件。
+- Contract 用 `record_openspec_selection` 声明实际使用的 required/relevant 来源，未提及候选不自动升级为 required。
+- Plan 通过 typed tools 引用冻结来源；runtime 从绑定来源与真实读取证据物化引用和 canonical JSON。模型不再输出 JSON 契约块或 `openspec-citations` fence。
+- 来源未绑定、引用不可解析或缺少真实读取背书时，由确定性 gate 阻断；不得伪造读取或引用。

package/docs/templates/frontend-implementation-contract.schema.json

@@ -115,6 +115,32 @@
             "items": {
               "$ref": "#/$defs/path"
             }
+          },
+          "execution": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "groupId",
+              "kind",
+              "summary"
+            ],
+            "properties": {
+              "groupId": {
+                "type": "string",
+                "minLength": 1
+              },
+              "kind": {
+                "enum": [
+                  "behavior",
+                  "constraint",
+                  "exclusion"
+                ]
+              },
+              "summary": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
           }
         }
       }
@@ -644,10 +670,16 @@
       "allOf": [
         {
           "if": {
-            "required": ["ledgerPath"]
+            "required": [
+              "ledgerPath"
+            ]
           },
           "then": {
-            "required": ["ledgerSha256", "inputDigest", "requirementToFragments"]
+            "required": [
+              "ledgerSha256",
+              "inputDigest",
+              "requirementToFragments"
+            ]
           }
         }
       ],

package/docs/templates/frontend-implementation-dag.json

@@ -27,17 +27,17 @@
   "tasks": [
     {
       "id":"frontend-contract-pi", "depends_on":[], "complexity":"MED", "executor":"pi", "role":"planner", "writePolicy":"read-only", "allowedPaths":["**"], "forbiddenPaths":[".harness/**","artifacts/**"],
-      "outputContract":"Plain Markdown frontend contract: required behavior, states, interactions, non-goals, concrete verification expectations, and unresolved gaps; no file writes.",
+      "outputContract":"Incremental Contract typed facts from complete input scopes; complete_contract_scope after all decisions, then one successful finalize_contract. Runtime owns canonical text and source bindings. No file writes.",
       "subtask_prompt":"Read the task inputs. Produce a concise frontend contract that maps each required behavior, UI state, and interaction to observable outcomes. Identify missing or conflicting requirements as blockers; do not infer them and do not edit files."
     },
     {
       "id":"frontend-scout-pi", "depends_on":["frontend-contract-pi"], "complexity":"LOW", "executor":"pi", "role":"scout", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/SOURCE/PATH/**","REPLACE/WITH/FRONTEND/TEST/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
-      "outputContract":"Plain Markdown source and verification reconnaissance: relevant routes, components, styles, state patterns, focused tests, and risks; no file writes.",
+      "outputContract":"Scout typed target-surface and design-evidence facts backed by fresh read evidence; durable receipts only. No file writes.",
       "subtask_prompt":"Inspect only the declared frontend source and test paths. Report reusable component, styling, accessibility, state-management, and verification patterns that satisfy the contract. Do not edit files or broaden the allowed paths."
     },
     {
       "id":"frontend-plan-pi", "depends_on":["frontend-scout-pi"], "complexity":"MED", "executor":"pi", "role":"planner", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/SOURCE/PATH/**","REPLACE/WITH/FRONTEND/TEST/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
-      "outputContract":"Plain Markdown implementation plan: ordered changes, concrete target files, behavior/state/interaction coverage, and focused verification mapping; no file writes.",
+      "outputContract":"Plan record_* tools for scoped coverage, shared execution groups and UX, one mock endpoint per record, then one successful finalize_plan. Runtime derives canonical JSON and Markdown. No file writes.",
       "subtask_prompt":"Turn the contract and reconnaissance into a minimal implementation plan. Every target file and verification step must be concrete. Preserve existing design and accessibility conventions. If any behavior lacks a verifiable target, report it as blocked instead of guessing."
     },
     {
@@ -48,7 +48,7 @@
     },
     {
       "id":"frontend-design-review-pi", "depends_on":["frontend-design-policy-shell"], "complexity":"MED", "executor":"pi", "role":"reviewer", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/SOURCE/PATH/**","REPLACE/WITH/FRONTEND/TEST/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
-      "outputContract":"Plain Markdown design review: approved plan or explicit blocking findings for behavior, state, interaction, design-system, and accessibility coverage; no file writes.",
+      "outputContract":"record_design_finding for individual findings; approve_design or request_design_changes provides the sole committed terminal. Independently review execution-group member differences. No file writes.",
       "subtask_prompt":"Review the approved plan against the frontend contract and design-policy result. Reject missing visible states, interaction behavior, accessibility obligations, or unsupported design claims. Do not edit files."
     },
     {
@@ -76,7 +76,7 @@
     },
     {
       "id":"frontend-review-pi", "depends_on":["frontend-review-context-shell"], "complexity":"MED", "executor":"pi", "role":"reviewer", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/TARGET/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
-      "outputContract":"Plain Markdown final review: approved result or explicit findings for contract coverage, regression risk, accessibility, and verification gaps; no file writes.",
+      "outputContract":"record_review_finding for individual findings; approve_review or request_review_changes provides the sole committed terminal. No file writes.",
       "subtask_prompt":"Review the actual diff and archived verification evidence against the frontend contract. Do not treat missing, weak, mock-only, or not-run evidence as passed. Report explicit residual risks; do not edit files."
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.43.0-next.1",
+  "version": "0.43.0-next.10",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -78,9 +78,12 @@
     "@deepseek-ai/dsh-invariants": "0.1.1-rc.2",
     "@earendil-works/pi-ai": "0.83.0",
     "@earendil-works/pi-coding-agent": "0.83.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
     "commander": "^12.1.0",
     "katex": "^0.16.47",
     "mermaid": "^11.16.1",
+    "node-pty": "^1.2.0-beta.15",
     "rehype-highlight": "^7.0.2",
     "rehype-katex": "^7.0.1",
     "remark-math": "^6.0.0",
@@ -90,8 +93,8 @@
     "zod": "^3.25.76"
   },
   "optionalDependencies": {
-    "@cursor/sdk": "^1.0.7",
-    "@agent-context/sift": "0.0.1-alpha.7"
+    "@agent-context/sift": "0.0.1-alpha.7",
+    "@cursor/sdk": "^1.0.7"
   },
   "devDependencies": {
     "@remixicon/react": "^4.9.0",

package/skills/frontend-contract/SKILL.md

@@ -15,7 +15,8 @@ language. Do not inspect implementation files or choose components, routes, Mock
 mechanisms, dependencies, or target code as requirement facts.
 
 Submit confirmed facts incrementally with the contract `record_*` tools and finish
-with exactly one `finalize_contract`. Start recording as soon as a requirement or
+with one successful `finalize_contract`. Complete each input scope with
+`complete_contract_scope` after all its decisions; correct rejected calls and retry. Start recording as soon as a requirement or
 constraint is confirmed; do not accumulate the whole contract in one response.
 
 Missing product semantics may be explicit assumptions only when they do not change

package/skills/frontend-contract/references/contract-protocol.md

@@ -8,8 +8,8 @@
   source-fidelity ledger. Do not infer fragment IDs from prose.
 - Record observable outcomes, applicable UI states, runtime/environment constraints,
   non-goals, risks, and verification expectations without choosing implementation.
-- Classify each requirement as `explicit`, `repository-resolvable`, `assumption`, or
-  `blocking`. Blocking facts name their owner and evidence.
+- Runtime owns requirement text, source binding and disposition. Use typed questions
+  and constraints for uncertainties; blocked terminal facts name their owner.
 
 ## Evidence and handoff
 
@@ -29,6 +29,22 @@ enumerate or downgrade them.
 
 ## Terminal
 
-Commit facts in small batches and call `finalize_contract` exactly once with
+Commit facts from the complete current scope, then `complete_contract_scope` only
+after its evidence, constraints and source-bound deliverables are recorded. Scope
+checkpoints survive interruption; confirming an ID alone is not completion.
+Call `finalize_contract` with
 `ready`, `ready-with-assumptions`, or `blocked`. If the task is too large for one
 bounded writer, record a split proposal instead of broadening the contract.
+
+A successful receipt means the fact was saved durably. Replays are idempotent;
+changed facts require explicit `replace:true`. Correct rejected calls and retry,
+but do not mutate after a successful terminal. Never drop tail conditions to fit.
+
+## Execution ownership
+
+`record_requirement` may include `execution:{groupId,kind,summary}`. Use `behavior`,
+`constraint`, or `exclusion`; reuse an existing group only when semantics agree.
+Keep permission, threshold and failure-path differences separate. Do not merge
+source IDs or independent acceptance conditions. Unclassified requirements remain
+independent. Later scopes receive the shared group index. A group is a planning
+proposal; independent design review must check every member's complete text.

package/skills/frontend-design-review/SKILL.md

@@ -9,26 +9,27 @@ references:
 
 # Frontend Design Review
 
-For frontend design review nodes. Read the checklist and the non-blocking contract
-capacity diagnostic first. Audit either the canonical contract or, when the
-diagnostic recommends indexed reading, its hash-bound field sections. Check the
-bound Mock strategy, task bounds, and traceable design evidence supplied by the
-upstream context. Do not rediscover task sources, search specification roots, or
-replace frozen evidence with nearby-code conventions. Use only exact, bound evidence
-paths when additional reading is necessary; never invent connector results.
+Audit the canonical contract or its hash-bound indexed sections, guided by the
+capacity diagnostic. Check Mock strategy, task bounds and exact bound evidence.
+Do not rediscover sources, search specification roots or invent connector results.
 
 ## Authoritative Terminal
 
-Complete the review with exactly one committed typed tool call:
+Submit findings one at a time with `record_design_finding` using stable IDs.
+Use `replace:true` for revisions. The terminal automatically includes saved findings;
+do not repeat their array. Correct rejected calls, then commit one successful terminal:
 
 - `approve_design` when no blocking design defect remains;
 - `request_design_changes` when a blocker exists. It must include a typed
-  `issueCategory`, at least one `evidenceRef`, and non-empty findings.
+  `issueCategory`, at least one `evidenceRef`, and non-empty findings (saved or supplied).
 
 The typed terminal is the only authoritative outcome. Do not require or emit a
 `VERDICT:` line, JSON verdict, revision patch, or a second final-design-review
-verdict. A requested design change ends this run; the recovery controller creates
-any bounded follow-up run from the appropriate phase.
+verdict. Requested changes end this run; recovery owns the bounded follow-up.
+
+Check every execution group against its members' complete outcomes. Permissions,
+thresholds and error paths remain independent ACs; a shared VT must prove them all.
+Constraint/exclusion labels never waive source-required behavior evidence.
 
 ## Blocking Conditions