@tea-agent/loop-agent 0.16.26 → 0.17.0

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

@@ -25,6 +25,23 @@ export function buildNodePrompt(spec, task, upstream, options) {
         projectGovernanceContext: options?.projectGovernanceContext,
     });
 }
+function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory) {
+    if (attemptNumber <= 1 ||
+        task.outputMode !== "structured-required" ||
+        previousFailureCategory !== "output-too-large") {
+        return basePrompt;
+    }
+    return [
+        basePrompt,
+        "",
+        "<retry_instruction>",
+        "Previous attempt exceeded the structured output size limit.",
+        "Return only the compact structured artifact required by this node's output contract.",
+        "Do not include explanatory prose, duplicated upstream context, long evidence excerpts, or additional markdown sections.",
+        "If a fenced JSON object is required, output exactly one fenced json block and nothing else.",
+        "</retry_instruction>",
+    ].join("\n");
+}
 export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd, options) {
     const policy = resolveContextPolicy(spec);
     const skillNames = policy.resolveSkills(spec, task);
@@ -283,6 +300,7 @@ export async function executeDagNode(input) {
     const attempts = [];
     let totalBackoffMs = 0;
     let terminalResult;
+    let previousFailureCategory;
     for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
         const attemptStartedAt = new Date().toISOString();
         const attemptStarted = Date.now();
@@ -293,7 +311,12 @@ export async function executeDagNode(input) {
                 tasksById,
                 state,
             });
-            result = await executeNode({ task, cwd, model, prompt });
+            result = await executeNode({
+                task,
+                cwd,
+                model,
+                prompt: buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory),
+            });
         }
         catch (error) {
             result = {
@@ -356,6 +379,7 @@ export async function executeDagNode(input) {
             await input.persistState();
         }
         terminalResult = result;
+        previousFailureCategory = result.failureCategory;
         if (result.ok)
             break;
         const canRetry = retryPolicy !== undefined && attemptNumber < maxAttempts;

package/dist/workflows/dag/retry-policy.js

@@ -16,6 +16,11 @@ export const DEFAULT_DAG_RETRY_CATEGORIES = [
     "rate-limit",
     "unavailable",
 ];
+export const STRUCTURED_OUTPUT_RETRY_CATEGORY = "output-too-large";
+export const STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES = [
+    ...DEFAULT_DAG_RETRY_CATEGORIES,
+    STRUCTURED_OUTPUT_RETRY_CATEGORY,
+];
 const RETRY_SAFE_PI_ROLES = new Set([
     "planner",
     "scout",
@@ -23,7 +28,7 @@ const RETRY_SAFE_PI_ROLES = new Set([
     "verifier",
     "closeout",
 ]);
-export const dagRetryCategorySchema = z.enum(DEFAULT_DAG_RETRY_CATEGORIES);
+export const dagRetryCategorySchema = z.enum(STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES);
 export const dagRetryBackoffSchema = z.enum(["exponential"]);
 /**
  * Opt-in retry policy for a DagTask. Generated only for safe read-only Pi
@@ -71,6 +76,16 @@ export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
     maxDelayMs: 30000,
     retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES],
 };
+/**
+ * Structured planner nodes may retry with a compact-output instruction
+ * when the model produced an oversized assistant response. This category is
+ * not part of the default read-only retry set because report/review nodes
+ * should not silently learn new output semantics.
+ */
+export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
+    ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+    retryCategories: [...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES],
+};
 /**
  * Deterministic helper: is this raw failure category eligible for retry under
  * the given policy? Pure function; executor never decides retry eligibility.

package/dist/workflows/dag/runner.js

@@ -117,6 +117,7 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
             status: "PENDING",
             executor: task.executor,
             complexity: task.complexity,
+            ...(task.outputMode ? { outputMode: task.outputMode } : {}),
             ...(resolveModelForTask(task, spec.executorModels)
                 ? { model: resolveModelForTask(task, spec.executorModels) }
                 : {}),
@@ -178,6 +179,10 @@ export async function runDag(spec, opts) {
     assertValidDagSpec(spec);
     // Candidate identity is validated before run-id allocation or directory creation.
     await assertEvaluationBindingPreflight(opts.cwd, spec.evaluation);
+    // Phase 0.5: new writer execution requires DagSpec v4 + live taskContractBinding match.
+    const { assertDagSpecAllowsNewWriterExecution, assertTaskContractBindingConsistent } = await import("./task-contract-binding.js");
+    assertDagSpecAllowsNewWriterExecution(spec);
+    await assertTaskContractBindingConsistent({ repoRoot: opts.cwd, spec });
     const runningIdentity = resolveRunningControllerIdentity();
     if (!runningIdentity) {
         throw new Error("running controller identity could not be resolved; refuse to create an unpinned DAG run");
@@ -273,6 +278,10 @@ export async function resumeDagRun(opts) {
     }
     assertFrozenEvaluationBinding(spec, state);
     assertFrozenBudget(spec.budget, state.budget, state.runId);
+    // Phase 0.5: refuse resume of pre-v4 writer DAGs; revalidate live binding.
+    const { assertDagSpecAllowsNewWriterExecution, assertTaskContractBindingConsistent } = await import("./task-contract-binding.js");
+    assertDagSpecAllowsNewWriterExecution(spec);
+    await assertTaskContractBindingConsistent({ repoRoot: opts.cwd, spec });
     // Runtime contract + controller identity must be re-verified before executing
     // any remaining node on resume; drift fails closed.
     const runningIdentity = resolveRunningControllerIdentity();

package/dist/workflows/dag/task-contract-binding.js

@@ -0,0 +1,138 @@
+import { observeTaskContract } from "../../task/contract/observe.js";
+export async function readCurrentTaskContractBinding(input) {
+    const state = await observeTaskContract({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+    });
+    if (state.effectiveStatus !== "managed" || !state.ref) {
+        return {
+            ok: false,
+            code: "BINDING_DRIFT",
+            message: `task ${input.taskId} is not managed (effectiveStatus=${state.effectiveStatus}); adopt/apply before DAG generate/run`,
+        };
+    }
+    const ref = state.ref;
+    return {
+        ok: true,
+        current: {
+            schemaVersion: 1,
+            taskId: ref.taskId,
+            revision: ref.revision,
+            projectionVersion: ref.projectionVersion,
+            canonicalizerVersion: ref.canonicalizerVersion,
+            taskConfigSchemaVersion: ref.taskConfigSchemaVersion,
+            canonicalHash: ref.canonicalHash,
+            taskConfigSha256: ref.taskConfigSha256,
+        },
+    };
+}
+export function compareTaskContractBinding(declared, current) {
+    if (declared.taskId !== current.taskId ||
+        declared.revision !== current.revision ||
+        declared.canonicalHash !== current.canonicalHash ||
+        declared.taskConfigSha256 !== current.taskConfigSha256 ||
+        declared.projectionVersion !== current.projectionVersion ||
+        declared.canonicalizerVersion !== current.canonicalizerVersion ||
+        declared.taskConfigSchemaVersion !== current.taskConfigSchemaVersion) {
+        return {
+            ok: false,
+            code: "BINDING_DRIFT",
+            message: `taskContractBinding drift for ${declared.taskId}: declared revision=${declared.revision} hash=${declared.canonicalHash}, current revision=${current.revision} hash=${current.canonicalHash}`,
+            declared,
+            current,
+        };
+    }
+    return { ok: true, declared, current };
+}
+/**
+ * Fail closed when a v4 DAG's frozen binding does not match current managed ref.
+ * Historical v3 specs without binding are left to migration matrix callers.
+ */
+export async function assertTaskContractBindingConsistent(input) {
+    if (input.spec.version !== 4) {
+        return;
+    }
+    const declared = input.spec.taskContractBinding;
+    if (!declared) {
+        const err = new Error("DagSpec version 4 missing taskContractBinding");
+        err.code = "BINDING_DRIFT";
+        throw err;
+    }
+    const current = await readCurrentTaskContractBinding({
+        repoRoot: input.repoRoot,
+        taskId: declared.taskId,
+    });
+    if (!current.ok || !current.current) {
+        const err = new Error(current.message ?? "task contract binding unavailable");
+        err.code = current.code ?? "BINDING_DRIFT";
+        throw err;
+    }
+    const cmp = compareTaskContractBinding(declared, current.current);
+    if (!cmp.ok) {
+        const err = new Error(cmp.message ?? "taskContractBinding drift");
+        err.code = "BINDING_DRIFT";
+        throw err;
+    }
+}
+/**
+ * v3 migration matrix: historical DAGs may remain readable/executable only
+ * when they contain no exclusive writer. Terminal report/doctor never call
+ * this helper.
+ */
+export function dagHasWriterExecution(spec) {
+    return spec.tasks.some((task) => (task.writePolicy ?? spec.defaults?.writePolicy) === "exclusive");
+}
+export function assertDagSpecAllowsNewWriterExecution(spec) {
+    if (!dagHasWriterExecution(spec))
+        return;
+    // Migration matrix (design §5.3.10):
+    // - New writer start/approve/resume requires DagSpec v4 + taskContractBinding.
+    // - Historical read-only/static/shell DAGs remain executable; they cannot
+    //   introduce repository writer execution and remain useful for diagnostics,
+    //   saved workflows, and deterministic verification.
+    // - v3 DAGs containing an exclusive writer must regenerate before execution.
+    if (spec.version !== 4) {
+        const err = new Error(`DagSpec version ${spec.version} cannot start/approve/resume new writer execution; regenerate as version 4 with taskContractBinding`);
+        err.code = "BINDING_DRIFT";
+        throw err;
+    }
+}
+/** Result-form API used by some callers; wraps assertTaskContractBindingConsistent. */
+export async function assertTaskContractBindingFresh(input) {
+    const action = input.action ?? "dag-action";
+    if (input.rejectHistoricalV3ForWriter && input.spec.version === 3) {
+        return {
+            ok: false,
+            code: "BINDING_DRIFT",
+            message: `${action}: DagSpec version 3 cannot start/approve/resume new writers; regenerate as v4`,
+        };
+    }
+    if (input.spec.version !== 4) {
+        return {
+            ok: true,
+            binding: input.spec.taskContractBinding,
+            current: input.spec.taskContractBinding,
+        };
+    }
+    try {
+        await assertTaskContractBindingConsistent({
+            repoRoot: input.repoRoot,
+            spec: input.spec,
+        });
+        return {
+            ok: true,
+            binding: input.spec.taskContractBinding,
+            current: input.spec.taskContractBinding,
+        };
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : "BINDING_DRIFT";
+        return {
+            ok: false,
+            code,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/workflows/dag/types.js

@@ -7,6 +7,7 @@ export const dagNodeExecutorSchema = z.enum(["pi", "shell", "static"]);
 export const CURSOR_DAG_EXECUTOR_REMOVED_ERROR = 'executor "cursor" is no longer supported; regenerate the DAG with Pi-only writers (implement-pi / repair-pi)';
 export const CURSOR_EXECUTOR_MODELS_REMOVED_ERROR = "executorModels.cursor is no longer supported; use executorModels.pi only";
 export const dagToolProfileSchema = z.enum(["read-only", "write"]);
+export const dagOutputModeSchema = z.enum(["default", "structured-required"]);
 export const dagShellPresetSchema = z.enum(["loop-agent-standard-verify"]);
 export const dagVerifyQuotaSchema = z.enum(["1", "3", "full"]);
 export const dagVerifyStrategySchema = z
@@ -75,6 +76,12 @@ export const dagRequirementCoverageGateSchema = z.object({
     fromNodeIds: z
         .array(z.string().regex(/^[a-z][a-z0-9-]*$/, "fromNodeIds must be kebab-case"))
         .min(1),
+    fallbackFromNodeIds: z
+        .array(z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "fallbackFromNodeIds must be kebab-case"))
+        .min(1)
+        .optional(),
     requiredIds: z
         .array(z
         .string()
@@ -95,6 +102,12 @@ export const dagJsonArtifactSchemaIdSchema = z.enum([
 ]);
 export const dagJsonArtifactGateSchema = z.object({
     fromNodeId: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    fallbackFromNodeIds: z
+        .array(z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "fallbackFromNodeIds must be kebab-case"))
+        .min(1)
+        .optional(),
     schemaId: dagJsonArtifactSchemaIdSchema,
     artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
@@ -102,8 +115,25 @@ export const dagJsonArtifactGateSchema = z.object({
 });
 export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 export const dagVersionSchema = z
-    .union([z.literal(1), z.literal(2), z.literal(3)])
+    .union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)])
     .default(1);
+/** DagSpec v4 binding to managed TaskContractRefV1 (design §5.3.10). */
+export const dagTaskContractBindingSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    taskId: z.string().min(1),
+    revision: z.number().int().nonnegative(),
+    projectionVersion: z.literal(1),
+    canonicalizerVersion: z.literal(1),
+    taskConfigSchemaVersion: z.literal(1),
+    canonicalHash: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/, "canonicalHash must be lowercase hex"),
+    taskConfigSha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/, "taskConfigSha256 must be lowercase hex"),
+})
+    .strict();
 export const dagRoleSchema = z.enum([
     "planner",
     "scout",
@@ -313,6 +343,7 @@ export const dagTaskSchema = z.object({
     shell: dagShellConfigSchema.optional(),
     static: dagStaticConfigSchema.optional(),
     outputContract: z.string().optional(),
+    outputMode: dagOutputModeSchema.optional(),
     firstProtocolLine: z.string().min(1).optional(),
     /**
      * Explicit opt-in for the deterministic project governance context resolver
@@ -376,9 +407,11 @@ export const dagSpecSchema = z
     title: z.string().min(1),
     runtimeContract: dagRuntimeContractSchema.optional(),
     evaluation: dagEvaluationBindingSchema.optional(),
-    /** Optional hard/record-only budget; requires version 3. */
+    /** Optional hard/record-only budget; requires version 3 or 4. */
     budget: dagBudgetSchema.optional(),
     sourceBinding: dagSourceBindingSchema.optional(),
+    /** v4 managed Task Contract binding; only valid on version 4. */
+    taskContractBinding: dagTaskContractBindingSchema.optional(),
     outputLanguage: dagOutputLanguageSchema.optional(),
     objective: z.string().optional(),
     successCriteria: z.array(z.string()).optional(),
@@ -391,34 +424,65 @@ export const dagSpecSchema = z
     tasks: z.array(dagTaskSchema).min(1),
 })
     .superRefine((spec, ctx) => {
-    if (spec.evaluation && spec.version !== 3) {
+    const supportsV3Fields = spec.version === 3 || spec.version === 4;
+    if (spec.evaluation && !supportsV3Fields) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "evaluation requires DagSpec version 3",
+            message: "evaluation requires DagSpec version 3 or 4",
             path: ["evaluation"],
         });
     }
-    if (spec.budget && spec.version !== 3) {
+    if (spec.budget && !supportsV3Fields) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "budget requires DagSpec version 3",
+            message: "budget requires DagSpec version 3 or 4",
             path: ["budget"],
         });
     }
-    if (spec.runtimeContract && spec.version !== 3) {
+    if (spec.runtimeContract && !supportsV3Fields) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "runtimeContract requires DagSpec version 3",
+            message: "runtimeContract requires DagSpec version 3 or 4",
             path: ["version"],
         });
     }
-    if (spec.version === 3 && !spec.runtimeContract) {
+    if (supportsV3Fields && !spec.runtimeContract) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "DagSpec version 3 requires runtimeContract",
+            message: `DagSpec version ${spec.version} requires runtimeContract`,
             path: ["runtimeContract"],
         });
     }
+    if (spec.taskContractBinding && spec.version !== 4) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "taskContractBinding requires DagSpec version 4",
+            path: ["taskContractBinding"],
+        });
+    }
+    if (spec.version === 4) {
+        if (!spec.sourceBinding) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "DagSpec version 4 requires sourceBinding",
+                path: ["sourceBinding"],
+            });
+        }
+        if (!spec.taskContractBinding) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "DagSpec version 4 requires taskContractBinding",
+                path: ["taskContractBinding"],
+            });
+        }
+        if (!spec.runtimeContract) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "DagSpec version 4 requires runtimeContract",
+                path: ["runtimeContract"],
+            });
+        }
+    }
     // Catch raw cursor keys that Zod .strict() on nested objects already rejects when parsed
     // via parseDagSpec; this refine covers typed object construction paths.
     const models = spec.executorModels;

package/dist/workflows/dag/validate.js

@@ -256,10 +256,20 @@ function validateRequirementCoverageGateConfig(task, spec, issues) {
         issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate requires executor=shell` });
         return;
     }
+    if (gate.fallbackFromNodeIds?.length && gate.fromNodeIds.length !== 1) {
+        issues.push({
+            type: "invalid-requirement-coverage-gate-config",
+            message: `task ${task.id} shell.requirementCoverageGate with fallbackFromNodeIds requires exactly one fromNodeIds entry`,
+        });
+    }
     const dependencyIds = new Set(task.depends_on);
-    for (const fromNodeId of gate.fromNodeIds) {
+    const sourceNodeIds = [
+        ...gate.fromNodeIds,
+        ...(gate.fallbackFromNodeIds ?? []),
+    ];
+    for (const fromNodeId of new Set(sourceNodeIds)) {
         if (!dependencyIds.has(fromNodeId)) {
-            issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate.fromNodeIds entry "${fromNodeId}" must appear in depends_on` });
+            issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate source "${fromNodeId}" must appear in depends_on` });
         }
         const upstream = spec.tasks.find((candidate) => candidate.id === fromNodeId);
         if (upstream?.executor === "shell") {
@@ -493,11 +503,19 @@ function validateShellTaskConfig(task, spec, issues) {
     }
     validateVerdictGateConfig(task, spec, issues);
     validateRequirementCoverageGateConfig(task, spec, issues);
-    if (shell.jsonArtifactGate && !task.depends_on.includes(shell.jsonArtifactGate.fromNodeId)) {
-        issues.push({
-            type: "missing-dependency",
-            message: `shell task ${task.id} jsonArtifactGate source ${shell.jsonArtifactGate.fromNodeId} must be a direct dependency`,
-        });
+    if (shell.jsonArtifactGate) {
+        const sourceNodeIds = [
+            shell.jsonArtifactGate.fromNodeId,
+            ...(shell.jsonArtifactGate.fallbackFromNodeIds ?? []),
+        ];
+        for (const sourceNodeId of new Set(sourceNodeIds)) {
+            if (!task.depends_on.includes(sourceNodeId)) {
+                issues.push({
+                    type: "missing-dependency",
+                    message: `shell task ${task.id} jsonArtifactGate source ${sourceNodeId} must be a direct dependency`,
+                });
+            }
+        }
     }
     validateRepairArtifactGateConfig(task, spec, issues);
     validateShellVerdictGateGovernance(task, commands, issues);

package/docs/README.md

@@ -31,6 +31,8 @@
 - `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
 - `design/backend-test-workflow.md` — 已实现的 backend-test 15 节点单次执行全流程、pass-only 评审门禁、run-owned artifacts 与最终 outcome
 - `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
+- `design/agent-worker-fullstack-workflow-integration.md` — 已实现的 workflow routing、Task Outcome、artifact-aware Ready、`fullstack-v1` 与 Verification Bundle，以及后续 failure routing / execute-existing 领域设计
+- `design/fullstack-end-to-end-delivery-optimization-roadmap.md` — 当前全栈端到端优化的收敛路线图：先完成 release train / Delivery，再冻结 Final Verification 权威、Environment Contract、分类恢复与 Observe 指标
 - `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
 - `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
 

package/docs/architecture/evolution.md

@@ -40,6 +40,8 @@
 | Loop 与 Dynamic Workflow 更深的双向集成、稳定化与自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action，不应误写为完全缺失 |
 
 > 本地 Loop Operator Console 已在 `docs/design/local-operator-console-from-pi-web.md` 作为独立设计输入：单仓库、loopback、随 `@tea-agent/loop-agent` 同包发布、canonical mutation 只经 sibling CLI；它不是本表中的远端 Web Console，也不能把远端多租户/云编排需求偷渡进本地 MVP。
+>
+> **Phase 3 落地（Unreleased）**：versioned Observe `/api/health`、Console `observeLink` fail-closed、recovery CTA 矩阵；Console 与 Observe 仍分进程。Phase 4 General Operator Chat 与合服仍属后续，未实现。
 
 > 注意：`ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md` 是 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
 

package/docs/architecture/system-overview.md

@@ -59,6 +59,12 @@ workflow runtime（调度 Pi / shell / static 节点）
 
 `agent-worker` 位于核心 runtime 的**上游调用侧**，不是 DAG 执行完成后的必经下游。Observe 可以在任一路径后读取现有事实，但不会改变执行结果。
 
+### 本地 Operator Console（Official，与 Observe 协作）
+
+- `agent-worker console serve` 提供 loopback Operator Console；canonical mutation 只经 sibling 已发布 `loop-agent`（`LoopAgentClient`），不 in-process 跑 DAG kernel。
+- Observe 保持**独立**只读进程；Console 通过 versioned Observe `/api/health`（`schemaVersion`、`repoFingerprint`、route capabilities）做深链 fail-closed，**不** mount / proxy。
+- openCode 等主会话仍是 Compatibility / Operator Assist，与 Official Console **不等同**。设计锚点：ADR 0005、`docs/design/local-operator-console-from-pi-web.md`。
+
 ## 外部边界
 
 - npm 发布包：`@tea-agent/loop-agent`，包含两个 bin 与静态能力资料。

package/docs/architecture/worker-and-feature.md

@@ -73,6 +73,13 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 - 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
 - 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
 - Observe 是本地只读暖白控制台；snapshot 投影失败返回安全错误摘要而非全零健康状态（见 `CHANGELOG.md [0.9.0]`）。
+- Phase 3：`GET /api/health` 为 versioned DTO（`schemaVersion: 1`、`repoFingerprint` 复用 Console `repoFingerprintV1`、package 元数据、由 ROUTES 派生的 `routeCapabilities`）。Console 深链 fail-closed 依赖该合同；Observe 仍独立进程、不经 Console proxy。
+
+### Loop Operator Console（Official 控制面骨架）
+
+- 模块：`src/worker/console/`（loopback serve、doctor、operator API、Vite SPA）。
+- 与 Observe 协作：`observeLink` + recovery CTA 矩阵；无 Cancel / 无主 CTA「直接改代码」。
+- 写入路径仍只经 `LoopAgentClient` → 已发布 `loop-agent`；不与 Observe 合服。
 
 ## 版本化自举的 deterministic canary
 

package/docs/templates/agent-dag.schema.json

@@ -255,12 +255,54 @@
         "requirementCoverageGate": {
           "type": "object", "additionalProperties": false,
           "required": ["fromNodeIds", "requiredIds"],
+          "allOf": [
+            {
+              "if": { "required": ["fallbackFromNodeIds"] },
+              "then": { "properties": { "fromNodeIds": { "maxItems": 1 } } }
+            }
+          ],
           "properties": {
             "fromNodeIds": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" } },
+            "fallbackFromNodeIds": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+              "description": "Optional effective-source fallbacks tried in order only when the single primary node output is absent. Each source must also appear in depends_on."
+            },
             "requiredIds": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$" } },
             "label": { "type": "string", "minLength": 1 }
           }
         },
+        "jsonArtifactGate": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["fromNodeId", "schemaId", "artifactName", "outputDir"],
+          "properties": {
+            "fromNodeId": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "fallbackFromNodeIds": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+              "description": "Optional effective-source fallbacks tried in order only when the primary current-run node output is absent. Existing malformed or schema-invalid primary output fails closed. Each source must also appear in depends_on."
+            },
+            "schemaId": {
+              "enum": [
+                "backend-test-analysis-v1",
+                "backend-test-analysis-v2",
+                "backend-test-execution-v1",
+                "backend-test-result-v1",
+                "backend-test-classification-v1",
+                "backend-test-semantic-review-v1",
+                "backend-test-case-manifest-v1",
+                "frontend-implementation-contract-v1",
+                "frontend-test-result-v1"
+              ]
+            },
+            "artifactName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.json$" },
+            "outputDir": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+            "junitRelativePath": { "type": "string", "minLength": 1 }
+          }
+        },
         "backendTestPipeline": {
           "enum": ["contracts", "semantic-initial", "execute-parse-initial", "classification-result-context"]
         },
@@ -281,6 +323,7 @@
         { "required": ["preset"] },
         { "required": ["verdictGate"] },
         { "required": ["requirementCoverageGate"] },
+        { "required": ["jsonArtifactGate"] },
         { "required": ["backendTestPipeline"] }
       ]
     },
@@ -319,10 +362,10 @@
         "retryCategories": {
           "type": "array",
           "items": {
-            "enum": ["timeout", "network", "rate-limit", "unavailable"]
+            "enum": ["timeout", "network", "rate-limit", "unavailable", "output-too-large"]
           },
           "default": ["timeout", "network", "rate-limit", "unavailable"],
-          "description": "Failure categories eligible for retry. quota is never eligible."
+          "description": "Failure categories eligible for retry. quota is never eligible. output-too-large is reserved for explicit structured-required nodes and is not part of the default retry set."
         }
       }
     },
@@ -404,6 +447,10 @@
           "type": "string",
           "minLength": 1
         },
+        "outputMode": {
+          "enum": ["default", "structured-required"],
+          "description": "Optional output semantics for Pi nodes. structured-required means oversized assistant output must not be accepted as a truncated success; eligible read-only nodes may compact-retry and downstream gates should rely on canonical structured artifacts."
+        },
         "firstProtocolLine": {
           "type": "string",
           "minLength": 1,

package/docs/templates/backend-test-dag.classify.prompt.md

@@ -71,5 +71,5 @@ Do **not** invent pass rates or failure lists from raw logs when Result v1 is pr
 ### Non-goals
 
 - Do not rewrite Result v1.
-- Do not decide final DAG success/failure (that is `backend-test-outcome-gate-shell`).
+- Do not decide pipeline completion or L-5 readiness; classification is interpretive evidence only.
 - Do not implement M3 case manifest / Task Pool auto follow-up.

package/docs/templates/backend-test-dag.generate-pytest.prompt.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Use this prompt for a **pytest code generation** node: `executor: "pi"`, `role: "implementer"`, `toolProfile: "write"`, `writePolicy: "exclusive"`. The implementer converts reviewed backend functional test cases into pytest automation code with 1:1 traceability.
+Use this prompt for a **pytest code generation** node: `executor: "pi"`, `role: "implementer"`, `toolProfile: "write"`, `writePolicy: "exclusive"`. The implementer converts validated backend functional test cases into pytest automation code with 1:1 traceability. The independent case review is advisory evidence and does not authorize this writer.
 
 Do **not** create a new executor type. This is a standard `executor: pi` writer node.
 
@@ -11,7 +11,7 @@ Do **not** create a new executor type. This is a standard `executor: pi` writer
 ```json
 {
   "id": "generate-backend-pytest-pi",
-  "depends_on": ["review-backend-cases-gate-shell", "backend-test-execution-contract-shell"],
+  "depends_on": ["backend-test-case-manifest-shell", "validate-backend-test-contracts-shell"],
   "complexity": "HIGH",
   "executor": "pi",
   "role": "implementer",
@@ -38,12 +38,12 @@ Your job is to convert reviewed test cases under `testcase/md/` into pytest auto
 
 ### Inputs
 
-1. **Reviewed test cases** — files under `testcase/md/` (approved by `review-backend-cases-pi` / `review-backend-cases-gate-shell`).
-2. **Validated Backend Test Analysis v1** — run-owned `contracts/backend-test-analysis.json` from `backend-test-analysis-contract-shell`.
+1. **Validated test cases and manifest** — files under `testcase/md/` plus run-owned `contracts/backend-test-case-manifest.json`. The case review runs independently as advisory evidence.
+2. **Validated Backend Test Analysis v2** — run-owned `contracts/backend-test-analysis.json`.
 3. **Validated Backend Test Execution Contract v1** — run-owned `contracts/backend-test-execution.json` from `backend-test-execution-contract-shell` (fixtures, env *names*, `testRoot`, `targetMode`, authenticationMode).
 4. **Target project conventions** — read `conftest.py`, `pytest.ini` / `pyproject.toml` to understand conventions, but do NOT modify them.
 
-Do NOT re-read source documents for free-form analysis. Use only reviewed cases and the validated contracts. Use only fixture/env/testRoot facts already present in the execution contract; never invent production credentials or secret values.
+Do NOT re-read source documents for free-form analysis. Use only validated cases, manifest, and contracts. Use only fixture/env/testRoot facts already present in the execution contract; never invent production credentials or secret values.
 
 When `targetMode` is `in-process` (including demoted local npm/node managed servers): bootstrap the service inside function-scoped pytest fixtures under `testcase/**` (for example subprocess `node server.js` / `startWelcomeServer` with `PORT=0`). Never require host-injected base URL env vars such as `WELCOME_BASE_URL` / `API_BASE_URL` — the clean-env pytest shell will not provide them.