@tea-agent/loop-agent 0.35.1-beta.0 → 0.35.1-beta.2

package/dist/workflows/dag/scheduler.js

@@ -1,5 +1,10 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 import { isPauseOnHumanDecisionGate } from "./decision-envelope.js";
 import { evaluateConditionExpression } from "./dynamic-runtime/condition.js";
+import { sha256Hex } from "./frontend-implementation-contract.js";
+import { frontendPrewriteResultV1Schema, FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME, } from "./frontend-prewrite-gate.js";
+import { FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, FRONTEND_RECOVERY_INTENT_REL_DIR, } from "./frontend-recovery-plan.js";
 export function isConditionSkippedReason(reason) {
     return Boolean(reason?.startsWith("condition "));
 }
@@ -104,6 +109,58 @@ async function mapConcurrent(items, limit, fn) {
     }
     await Promise.all(executing);
 }
+export const FRONTEND_WRITER_NODE_IDS = [
+    "frontend-implement-pi",
+    "frontend-repair-pi",
+];
+/** Run-relative artifact location written by the prewrite gate generator. */
+export const FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT = path.posix.join("contracts", FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME);
+/**
+ * Read and validate the frontend-prewrite-result-v1 artifact. Fail-closed:
+ * a missing file or invalid payload returns ok:false and never throws.
+ */
+export async function readFrontendPrewriteResult(runDir) {
+    const artifactPath = path.join(runDir, "contracts", FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME);
+    let raw;
+    try {
+        raw = await readFile(artifactPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {
+                ok: false,
+                reason: `frontend prewrite result artifact missing: ${artifactPath}`,
+            };
+        }
+        throw error;
+    }
+    const artifactHash = sha256Hex(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `frontend prewrite result artifact is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const result = frontendPrewriteResultV1Schema.safeParse(parsed);
+    if (!result.success) {
+        return {
+            ok: false,
+            reason: "frontend prewrite result artifact failed schema validation",
+        };
+    }
+    return { ok: true, result: result.data, artifactHash };
+}
+/** Authorize only accepted / accepted-normalized classifications. */
+export function isFrontendWriterAuthorized(result) {
+    return result.classification === "accepted" ||
+        result.classification === "accepted-normalized"
+        ? "authorized"
+        : "denied";
+}
 /** Fail-closed: leave no PENDING nodes that look "still scheduled" after abort. */
 export function markPendingNodesControllerInterrupted(state, reason = "run aborted by controller (abortSignal)") {
     const affected = [];
@@ -122,8 +179,166 @@ export function markPendingNodesControllerInterrupted(state, reason = "run abort
     }
     return affected;
 }
+/**
+ * True when this run is a candidate-continuation child: it has a recovery
+ * lineage whose attemptIndex is >= 1 and whose recovery root is another run.
+ * The root/parent keeps `recoveryRootRunId === state.runId`.
+ */
+export function isFrontendRecoveryChild(state) {
+    const recovery = state.frontendRecoveryState;
+    return Boolean(recovery &&
+        recovery.attemptIndex >= 1 &&
+        recovery.recoveryRootRunId !== state.runId);
+}
+function isValidFrontendRecoveryActivationMarker(raw) {
+    return (raw.schemaVersion === 1 &&
+        typeof raw.requestId === "string" &&
+        raw.requestId.length > 0 &&
+        typeof raw.parentRunId === "string" &&
+        raw.parentRunId.length > 0 &&
+        typeof raw.recoveryRootRunId === "string" &&
+        raw.recoveryRootRunId.length > 0 &&
+        typeof raw.childRunId === "string" &&
+        raw.childRunId.length > 0 &&
+        typeof raw.importManifestSha256 === "string" &&
+        /^[a-f0-9]{64}$/.test(raw.importManifestSha256));
+}
+/**
+ * Activation marker gate (phase 3c AC-1). Fail-closed: an active child is only
+ * executable when its parent is `child-running`, points at this child, carries
+ * a structurally valid activation marker whose lineage matches, and the marker
+ * hash matches the child's import manifest. Read-only and never throws.
+ */
+export async function checkFrontendRecoveryActivation(state, childRunDir) {
+    if (!isFrontendRecoveryChild(state)) {
+        return { applicable: false };
+    }
+    const recovery = state.frontendRecoveryState;
+    const parentRunId = recovery.parentRunId;
+    const parentRunDir = path.join(path.dirname(childRunDir), parentRunId);
+    let parentState;
+    try {
+        parentState = JSON.parse(await readFile(path.join(parentRunDir, "state.json"), "utf8"));
+    }
+    catch {
+        return { applicable: true, ok: false, reason: "parent state unreadable" };
+    }
+    const parentRecovery = parentState.frontendRecoveryState;
+    if (parentRecovery?.phase !== "child-running") {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "parent phase not child-running",
+        };
+    }
+    if (parentRecovery.childRunId !== state.runId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "parent childRunId mismatch",
+        };
+    }
+    const markerPath = path.join(parentRunDir, FRONTEND_RECOVERY_INTENT_REL_DIR, `${recovery.requestId}.json`);
+    let markerRaw;
+    try {
+        markerRaw = JSON.parse(await readFile(markerPath, "utf8"));
+    }
+    catch {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "activation marker missing",
+        };
+    }
+    if (typeof markerRaw !== "object" ||
+        markerRaw === null ||
+        !isValidFrontendRecoveryActivationMarker(markerRaw)) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "activation marker invalid",
+        };
+    }
+    const marker = markerRaw;
+    if (marker.requestId !== recovery.requestId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker requestId mismatch",
+        };
+    }
+    if (marker.parentRunId !== parentRunId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker parentRunId mismatch",
+        };
+    }
+    if (marker.recoveryRootRunId !== recovery.recoveryRootRunId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker recoveryRootRunId mismatch",
+        };
+    }
+    if (marker.childRunId !== state.runId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker childRunId mismatch",
+        };
+    }
+    let manifestSha256;
+    try {
+        manifestSha256 = sha256Hex(await readFile(path.join(childRunDir, FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH), "utf8"));
+    }
+    catch {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "import manifest unreadable",
+        };
+    }
+    if (manifestSha256 !== marker.importManifestSha256) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "import manifest sha256 mismatch",
+        };
+    }
+    return {
+        applicable: true,
+        ok: true,
+        requestId: recovery.requestId,
+        childRunId: state.runId,
+    };
+}
 export async function executeDagRanksOnce(input) {
     let pausedByNodeId;
+    // Activation marker gate (phase 3c AC-1): a recovery child without a valid
+    // activation marker must never be scheduled or executed. Fail-closed before
+    // any executeScheduledNode call, so zero writer/provider invocations happen.
+    if (input.runDir) {
+        const hasPending = Object.values(input.state.nodes).some((node) => node.status === "PENDING");
+        if (hasPending) {
+            const activation = await checkFrontendRecoveryActivation(input.state, input.runDir);
+            if (activation.applicable && !activation.ok) {
+                const finishedAt = new Date().toISOString();
+                let affected = 0;
+                for (const node of Object.values(input.state.nodes)) {
+                    if (node.status !== "PENDING")
+                        continue;
+                    node.status = "SKIPPED";
+                    node.skippedReason = "frontend-recovery-child-not-activated";
+                    node.finishedAt = finishedAt;
+                    affected += 1;
+                }
+                if (affected > 0)
+                    await input.persistState();
+                return undefined;
+            }
+        }
+    }
     for (const rank of input.ranks) {
         if (input.abortSignal?.aborted) {
             const marked = markPendingNodesControllerInterrupted(input.state, input.abortSignal.reason
@@ -168,6 +383,45 @@ export async function executeDagRanksOnce(input) {
             await input.persistState();
         const conditionSkippedSet = new Set(conditionSettled);
         const actuallyRunnable = runnable.filter((id) => !conditionSkippedSet.has(id));
+        const frontendAdmissionSettled = [];
+        if (input.runDir) {
+            for (const id of actuallyRunnable) {
+                if (!FRONTEND_WRITER_NODE_IDS.includes(id))
+                    continue;
+                const node = input.state.nodes[id];
+                const checkedAt = new Date().toISOString();
+                const admission = await readFrontendPrewriteResult(input.runDir);
+                if (!admission.ok) {
+                    node.status = "SKIPPED";
+                    node.skippedReason = "frontend-prewrite-not-authorized";
+                    node.finishedAt = checkedAt;
+                    frontendAdmissionSettled.push(id);
+                    continue;
+                }
+                const decision = isFrontendWriterAuthorized(admission.result);
+                node.frontendWriterAdmission = {
+                    schemaVersion: 1,
+                    writerNodeId: id,
+                    decision,
+                    sourceArtifact: FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT,
+                    artifactHash: admission.artifactHash,
+                    checkedAt,
+                    reason: decision === "denied"
+                        ? `classification: ${admission.result.classification}`
+                        : null,
+                };
+                if (decision === "denied") {
+                    node.status = "SKIPPED";
+                    node.skippedReason = "frontend-prewrite-not-authorized";
+                    node.finishedAt = checkedAt;
+                    frontendAdmissionSettled.push(id);
+                }
+            }
+            if (frontendAdmissionSettled.length > 0)
+                await input.persistState();
+        }
+        const frontendAdmissionSkippedSet = new Set(frontendAdmissionSettled);
+        const runnableAfterAdmission = actuallyRunnable.filter((id) => !frontendAdmissionSkippedSet.has(id));
         const blocked = pending.filter((id) => {
             const task = input.tasksById.get(id);
             return (dependencyReadiness(task, input.state.nodes, input.tasksById) === "skip");
@@ -182,12 +436,12 @@ export async function executeDagRanksOnce(input) {
         if (blocked.length > 0) {
             await input.persistState();
         }
-        const pauseGateRunnable = actuallyRunnable.filter((id) => {
+        const pauseGateRunnable = runnableAfterAdmission.filter((id) => {
             const task = input.tasksById.get(id);
             return isPauseOnHumanDecisionGate(task);
         });
-        const regularRunnable = actuallyRunnable.filter((id) => !pauseGateRunnable.includes(id));
-        const rankWriterNodeIds = actuallyRunnable.filter((id) => {
+        const regularRunnable = runnableAfterAdmission.filter((id) => !pauseGateRunnable.includes(id));
+        const rankWriterNodeIds = runnableAfterAdmission.filter((id) => {
             const task = input.tasksById.get(id);
             return (task?.executor === "pi" &&
                 task.toolProfile === "write" &&

package/dist/workflows/dag/types.js

@@ -654,8 +654,15 @@ export const dagConvergenceSpecSchema = z
     chainNodeIds: z.array(z.string()).optional(),
 })
     .optional();
-export const dagTaskSchema = z.object({
-    id: z.string().regex(/^[a-z][a-z0-9-]*$/, "task id must be kebab-case"),
+/**
+ * Schema ids that may opt a node into producing-node structured contract
+ * self-validation. Validators are registered in the contract output registry
+ * (src/workflows/dag/contract-output-registry.ts).
+ */
+export const structuredContractOutputSchemaIds = [
+    "frontend-implementation-contract-v1",
+];
+export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/, "task id must be kebab-case"),
     depends_on: z.array(z.string()).default([]),
     /**
      * How SKIPPED upstreams affect readiness.
@@ -704,6 +711,20 @@ export const dagTaskSchema = z.object({
      * on safe read-only Pi nodes before the node becomes ERROR.
      */
     outputProtocol: dagOutputProtocolSchema.optional(),
+    /**
+     * Node-level structured contract self-check: after the Pi output is
+     * produced, validate it against the named contract schema at the node so
+     * schema/typo/null violations become invalid-output (retryable on the node)
+     * instead of failing later at a downstream deterministic gate. Validators
+     * are resolved via the contract output registry keyed by schemaId.
+     */
+    structuredContractOutput: z
+        .object({
+        schemaId: z.enum(structuredContractOutputSchemaIds),
+        retryOnInvalid: z.boolean().default(true),
+    })
+        .strict()
+        .optional(),
     /**
      * Fail-closed outcome/diff consistency contract for bounded Pi writers.
      * The writer must begin with IMPLEMENTATION_OUTCOME: changed,
@@ -874,6 +895,113 @@ export const dagSpecSchema = z
         });
     }
 });
+export const FRONTEND_RECOVERY_STATE_SCHEMA_VERSION = 1;
+export const FRONTEND_RECOVERY_RESULT_SCHEMA_VERSION = 1;
+/**
+ * Frontend candidate-continuation recovery phase (decision B, phase-3 subset).
+ * Phase 3a parents converge first, so `rollback-pending` is not produced and
+ * was removed by AC-1; the phase starts at `child-staging` and ends at
+ * `settled`.
+ */
+export const frontendRecoveryPhaseSchema = z.enum([
+    "child-staging",
+    "child-activating",
+    "child-running",
+    "settled",
+]);
+/**
+ * Single-writer recovery intent/lineage stored on `DagRunState`. The parent run
+ * owns the authoritative copy and advances it via revision-guarded CAS writes;
+ * the child carries a frozen lineage snapshot so the activation gate can prove
+ * it is the reserved child of a child-running parent.
+ *
+ * Invariants: `attemptIndex ∈ {0,1}`; `continuationCount ∈ {0,1}`; a child's
+ * `recoveryRootRunId` always equals the root runId; `revision` is the CAS
+ * pre-comparison counter. `revision` monotonicity is enforced at runtime by the
+ * runner's `(existing?.revision ?? 0) + 1` CAS write (the schema only bounds it
+ * non-negative). `childRunId` may be absent through `child-activating` and must
+ * be non-empty from `child-running` onward.
+ */
+export const frontendRecoveryStateSchema = z
+    .object({
+    schemaVersion: z.literal(FRONTEND_RECOVERY_STATE_SCHEMA_VERSION),
+    phase: frontendRecoveryPhaseSchema,
+    requestId: z.string().min(1),
+    recoveryRootRunId: z.string().min(1),
+    parentRunId: z.string().min(1),
+    childRunId: z.string().min(1).optional(),
+    attemptId: z.string().min(1),
+    attemptIndex: z.number().int().min(0).max(1),
+    continuationCount: z.number().int().min(0).max(1),
+    /** Node id of the reset-closure root: frontend-plan-pi /
+     *  frontend-plan-revision-pi / frontend-prewrite-gate-shell /
+     *  frontend-implement-pi (writer partial write). */
+    failureSource: z.string().min(1).optional(),
+    revision: z.number().int().nonnegative(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const requiresChild = value.phase === "child-running" || value.phase === "settled";
+    if (requiresChild && !value.childRunId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `phase ${value.phase} requires a non-empty childRunId`,
+            path: ["childRunId"],
+        });
+    }
+});
+export const frontendRecoveryOutcomeSchema = z.enum([
+    "none",
+    "recovered",
+    "candidate-contract-invalid",
+    "prewrite-blocked",
+    "repair-exhausted",
+    "auto-recovery-blocked",
+]);
+export const frontendRecoveryOriginSchema = z
+    .object({
+    kind: z.enum(["frontend-prewrite-gate", "frontend-writer"]),
+    parentRunId: z.string().min(1),
+    childRunId: z.string().min(1).optional(),
+    requestId: z.string().min(1),
+    failedNodeId: z.string(),
+})
+    .strict();
+export const frontendRecoveryFailureClassSchema = z
+    .object({
+    code: z.enum([
+        "candidate-contract-invalid",
+        "prewrite-blocked",
+        "staging-failed",
+        "writer-transient-partial-write",
+    ]),
+    classification: z.string(),
+    reason: z.string(),
+})
+    .strict();
+export const frontendRecoveryEvidenceRefSchema = z
+    .object({
+    runId: z.string().min(1),
+    relativePath: z.string().min(1),
+    sha256: z.string().min(1),
+})
+    .strict();
+/**
+ * Terminal frontend recovery result. `failureClass` is absent for `none`,
+ * `recovered` and `auto-recovery-blocked` outcomes. The schema intentionally
+ * stays permissive (failureClass optional, evidenceRefs may be empty) so it
+ * accepts the runner's actual phase-3a products, which do not always carry a
+ * failure class or evidence reference.
+ */
+export const frontendRecoveryResultSchema = z
+    .object({
+    schemaVersion: z.literal(FRONTEND_RECOVERY_RESULT_SCHEMA_VERSION),
+    outcome: frontendRecoveryOutcomeSchema,
+    origin: frontendRecoveryOriginSchema,
+    failureClass: frontendRecoveryFailureClassSchema.optional(),
+    evidenceRefs: z.array(frontendRecoveryEvidenceRefSchema),
+})
+    .strict();
 export const DEFAULT_DAG_EXECUTOR_MODELS = {
     pi: {
         LOW: "gpt-5.3-codex-spark",

package/docs/architecture/evolution.md

@@ -1,73 +1,73 @@
-# 架构演进：当前 vs 未来
-
-本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0005、`docs/exec-plans/completed/` 与 `docs/exec-plans/active/`。
-
-**对照版本：`@tea-agent/loop-agent@0.24.0`（2026-07-27）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
-
-## 当前已实现（累计至 0.24.0）
-
-| 域 | 现状 | 权威入口 |
-| --- | --- | --- |
-| 受治理 Agent runtime | **Pi-only**；`cursor-prompt` 仅显式 one-shot sidecar | ADR 0001、`CHANGELOG.md [0.10.0]` |
-| Agent DAG 主链 | `dag run-task` → generate → validate → `run-dag`；report/doctor/reconcile-run | `dag-execution.md`、`test/cli-contract.test.ts` |
-| Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/**`、`website/docs/guides/dynamic-workflow.md` |
-| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/feature/2026-07-13-versioned-self-hosting-bootstrap.md` |
-| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/feature/2026-07-12-m2-completion-audit.md`、`CHANGELOG.md [0.10.0]` |
-| Task Pool | 唯一根 `.harness/task-pool/`；**feature-scoped** state v2（`TaskPoolTaskRef`） | ADR 0002、ADR 0004、`CHANGELOG.md [0.13.0]` |
-| Ready Planner | priority 选择；`batch plan-ready` 零写入；`run-ready` 冻结 plan；产物门禁 | `CHANGELOG.md [0.13.0]` / `[0.16.0]` |
-| TaskSpec → workflow | 可选 `execution.workflow` → `taskKind`；typed Outcome；`fullstack-v1` Verification Bundle | completed `2026-07-19-taskspec-workflow-routing.md`、`CHANGELOG.md [0.16.0]` |
-| 专用 taskKind DAG | `frontend-implementation` / `frontend-test` / `backend-test` / knowledge* | `website/docs/guides/agent-dag.md`、`CHANGELOG.md [0.12.0]`–`[0.17.x]` |
-| Backend-test | **Markdown-first 8 节点**；Markdown 映射限定 pytest 执行，生成 Markdown 与分层 HTML/脱敏请求响应详情 | completed `2026-07-24-backend-test-scoped-execution-report-ui.md`；`CHANGELOG.md [0.21.0]` / `[0.22.0]` |
-| Frontend-test | 默认 short-chain RAG；内容/evidence 质量进入 advisory findings，路径与安全边界仍 fail-closed | `CHANGELOG.md [0.21.0]` / `[0.22.0]` |
-| Frontend-implementation | Contract / trace / repair / Mock assess；`ai_workspace` + 知识库 + `openspec` 规范发现；lint 基线债务隔离 | `CHANGELOG.md [0.22.0]` |
-| Inspect（原 Observe） | 统一 Console 的 `/inspect/` 只读运营面与富时间线；独立 `observe serve` 已硬下线 | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [Unreleased]` |
-| Local Operator Console | `agent-worker console\|doctor`（loopback；默认打开系统浏览器，`--no-open` 禁止）；Operate + Inspect、Happy Path / Interview / split view / recovery CTA；**0.23.x 起含 General Operator Chat**（Pi SDK services session、operator-only tool surface）；**非**远端多用户 Console | unify design；ADR 0005；completed `2026-07-25-console-phase-4-general-operator-chat.md` |
-| Task Contract / operator surface | journaled `task contract *`；machine envelope；**DagSpec v4 `taskContractBinding`**（exclusive writer 强制） | `CHANGELOG.md [0.17.0]`–`[0.17.2]`；ADR 0005 |
-| DagSpec / repair | v3 `runtimeContract` + 显式 `repairNodeId`；新 writer 生成默认 v4 binding | `dag-execution.md`、`CHANGELOG.md [0.11.0]` / `[0.17.0]` |
-| 自适应 liveness | runner lease、Provider/tool/output 活动与 meaningful progress 分离；静默 stall 受控终止，退出未确认时禁止自动重试 | `dag-execution.md`、active `2026-07-23-dag-adaptive-liveness.md` |
-| 运行恢复 | 节点内协议纠错重试、`dag rerun` 安全子图续跑、`dag rerun-task` 完整任务重跑与 Console Recovery | `CHANGELOG.md [0.20.1]`、active `2026-07-23-operator-rerun-hardening.md` |
-| Eval Lab | corpus / campaign / promote（人工门禁）；`autoPromote=false`；**非** RSI Level 1 | `CHANGELOG.md [0.15.0]`；active plan 可归档 |
-| 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
-| 文档治理 | 任务式 Start Here、机器可读身份清单、目录默认身份与版本/索引语义检查 | 本目录 README、`docs/README.md`、`docs/document-catalog.json` |
-
-### 受治理 runtime 的边界（已实现、不变式）
-
-- DAG writer 固定 `implement-pi` / `repair-pi`；`executor: "cursor"`、`implement-cursor` / `repair-cursor`、Cursor worker、`cursor-fix` 已从受治理路径移除。
-- 完成权威 = shell verification；model verdict / Observe / 报告是 derived/advisory。
-- Worker 通过已发布 `loop-agent` 子进程执行，不 in-process import runtime kernel（governance 机器校验）。
-- Console / Compatibility 主会话不得绕过 CLI 直接改业务实现（ADR 0005）。
-
-## 未来规划（第 3–6 月，**未实现**）
-
-以下能力来自 `docs/design/active/六个月规划.md` 与相关设计输入（页首校准条之后的未交付 phase 为**设计输入**）。它们**当前不存在于产品声称的线上形态**，或仅有本地/部分替代：
-
-| 未来方向 | 状态 | 规划来源 |
-| --- | --- | --- |
-| 远程 PR / CI 自动创建与写回 | 规划 / 未实现 | `docs/design/active/六个月规划.md`（第 3 个月起） |
-| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
-| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
-| 多仓库平台 | 规划 / 未实现 | 同上 |
-| 组织级服务 | 规划 / 未实现 | 同上 |
-| Web Console（远端多用户） | 规划 / 未实现；**不等于**已发布的本地 loopback Operator Console | 同上；对照 `docs/design/archive/2026-07-21-local-operator-console-from-pi-web.md` |
-| fullstack Delivery / Final Verification live 闭环 | 进行中（active train） | `docs/exec-plans/active/2026-07-19-fullstack-dogfood-016x-release-train.md` |
-| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/active/dynamic-workflow-dag-engine-roadmap.md` |
-| Loop 与 Dynamic Workflow 更深双向集成 / 自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action |
-| Operator Chat 作为主操作会话（裸 bash 收敛、真 human gate、durable session/turn、Operation 闭环、完整 CLI action coverage、默认入口切换） | 设计输入 / 未达主会话门槛 | `docs/design/active/operator-chat-primary-session-roadmap.md`；Phase 4 General Operator Chat 本体已实现归档（`docs/exec-plans/completed/2026-07-25-console-phase-4-general-operator-chat.md`） |
-| Eval Lab auto-promote / RSI Level 1 产品声称 | **禁止**写成已交付 | Eval Lab design + active plan |
-
-> 本地 Operator Console 统一面（实际首发 0.19.0）已发布：单仓库、loopback、随 `@tea-agent/loop-agent` 同包、canonical mutation 只经 sibling CLI，Inspect 复用 GET-only Observe read model。它不是远端 Web Console，也不能把多租户/云编排需求偷渡进本地 Console。
-
-> 注意：`docs/design/active/dynamic-workflow-dag-engine-roadmap.md` 含 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
-
-## 已收敛为 archive / 历史基线（非未来）
-
-- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`docs/design/archive/2026-07-12-第二月规划.md`。
-- `docs/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**（允许有限再采样），不当第二 CHANGELOG。
-- 活能力短摘要在 `docs/reports/current-capability-summary.md`。
-- 专题证据按类型落在 `docs/reports/{feature,init-evolution,merge,fullstack-dogfood,dogfood}/`。
-
-## 文档本体的演进边界
-
-- 本目录新增文档随发布包发布（`package.json` `files` + manifest `packageRequired` 显式条目），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
-- `runtime-boundaries.md` 是边界真源；本目录其他文档交叉引用，不复制其 import 方向表 / governance-hook 表 / 版本化自举边界表。
-- 未来如有能力落地，应先改 `src/` / CLI / ADR / completed plan，再回写本目录的「已实现」表与站上 `website/docs/overview/*` 短索引。
+# 架构演进：当前 vs 未来
+
+本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0005、`docs/exec-plans/completed/` 与 `docs/exec-plans/active/`。
+
+**对照版本：`@tea-agent/loop-agent@0.24.0`（2026-07-27）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
+
+## 当前已实现（累计至 0.24.0）
+
+| 域 | 现状 | 权威入口 |
+| --- | --- | --- |
+| 受治理 Agent runtime | **Pi-only**；`cursor-prompt` 仅显式 one-shot sidecar | ADR 0001、`CHANGELOG.md [0.10.0]` |
+| Agent DAG 主链 | `dag run-task` → generate → validate → `run-dag`；report/doctor/reconcile-run | `dag-execution.md`、`test/cli-contract.test.ts` |
+| Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/**`、`website/docs/guides/dynamic-workflow.md` |
+| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/feature/2026-07-13-versioned-self-hosting-bootstrap.md` |
+| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/feature/2026-07-12-m2-completion-audit.md`、`CHANGELOG.md [0.10.0]` |
+| Task Pool | 唯一根 `.harness/task-pool/`；**feature-scoped** state v2（`TaskPoolTaskRef`） | ADR 0002、ADR 0004、`CHANGELOG.md [0.13.0]` |
+| Ready Planner | priority 选择；`batch plan-ready` 零写入；`run-ready` 冻结 plan；产物门禁 | `CHANGELOG.md [0.13.0]` / `[0.16.0]` |
+| TaskSpec → workflow | 可选 `execution.workflow` → `taskKind`；typed Outcome；`fullstack-v1` Verification Bundle | completed `2026-07-19-taskspec-workflow-routing.md`、`CHANGELOG.md [0.16.0]` |
+| 专用 taskKind DAG | `frontend-implementation` / `frontend-test` / `backend-test` / knowledge* | `website/docs/guides/agent-dag.md`、`CHANGELOG.md [0.12.0]`–`[0.17.x]` |
+| Backend-test | **Markdown-first 8 节点**；Markdown 映射限定 pytest 执行，生成 Markdown 与分层 HTML/脱敏请求响应详情 | completed `2026-07-24-backend-test-scoped-execution-report-ui.md`；`CHANGELOG.md [0.21.0]` / `[0.22.0]` |
+| Frontend-test | 默认 short-chain RAG；内容/evidence 质量进入 advisory findings，路径与安全边界仍 fail-closed | `CHANGELOG.md [0.21.0]` / `[0.22.0]` |
+| Frontend-implementation | Contract / trace / repair / Mock assess；`ai_workspace` + 知识库 + `openspec` 规范发现；lint 基线债务隔离 | `CHANGELOG.md [0.22.0]` |
+| Inspect（原 Observe） | 统一 Console 的 `/inspect/` 只读运营面与富时间线；独立 `observe serve` 已硬下线 | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [Unreleased]` |
+| Local Operator Console | `agent-worker console\|doctor`（loopback；默认打开系统浏览器，`--no-open` 禁止）；Operate + Inspect、Happy Path / Interview / split view / recovery CTA；**0.23.x 起含 General Operator Chat**（Pi SDK services session、operator-only tool surface）；**非**远端多用户 Console | unify design；ADR 0005；completed `2026-07-25-console-phase-4-general-operator-chat.md` |
+| Task Contract / operator surface | journaled `task contract *`；machine envelope；**DagSpec v4 `taskContractBinding`**（exclusive writer 强制） | `CHANGELOG.md [0.17.0]`–`[0.17.2]`；ADR 0005 |
+| DagSpec / repair | v3 `runtimeContract` + 显式 `repairNodeId`；新 writer 生成默认 v4 binding | `dag-execution.md`、`CHANGELOG.md [0.11.0]` / `[0.17.0]` |
+| 自适应 liveness | runner lease、Provider/tool/output 活动与 meaningful progress 分离；静默 stall 受控终止，退出未确认时禁止自动重试 | `dag-execution.md`、active `2026-07-23-dag-adaptive-liveness.md` |
+| 运行恢复 | 节点内协议纠错重试、`dag rerun` 安全子图续跑、`dag rerun-task` 完整任务重跑与 Console Recovery | `CHANGELOG.md [0.20.1]`、active `2026-07-23-operator-rerun-hardening.md` |
+| Eval Lab | corpus / campaign / promote（人工门禁）；`autoPromote=false`；**非** RSI Level 1 | `CHANGELOG.md [0.15.0]`；active plan 可归档 |
+| 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
+| 文档治理 | 任务式 Start Here、机器可读身份清单、目录默认身份与版本/索引语义检查 | 本目录 README、`docs/README.md`、`docs/document-catalog.json` |
+
+### 受治理 runtime 的边界（已实现、不变式）
+
+- DAG writer 固定 `implement-pi` / `repair-pi`；`executor: "cursor"`、`implement-cursor` / `repair-cursor`、Cursor worker、`cursor-fix` 已从受治理路径移除。
+- 完成权威 = shell verification；model verdict / Observe / 报告是 derived/advisory。
+- Worker 通过已发布 `loop-agent` 子进程执行，不 in-process import runtime kernel（governance 机器校验）。
+- Console / Compatibility 主会话不得绕过 CLI 直接改业务实现（ADR 0005）。
+
+## 未来规划（第 3–6 月，**未实现**）
+
+以下能力来自 `docs/design/active/六个月规划.md` 与相关设计输入（页首校准条之后的未交付 phase 为**设计输入**）。它们**当前不存在于产品声称的线上形态**，或仅有本地/部分替代：
+
+| 未来方向 | 状态 | 规划来源 |
+| --- | --- | --- |
+| 远程 PR / CI 自动创建与写回 | 规划 / 未实现 | `docs/design/active/六个月规划.md`（第 3 个月起） |
+| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
+| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
+| 多仓库平台 | 规划 / 未实现 | 同上 |
+| 组织级服务 | 规划 / 未实现 | 同上 |
+| Web Console（远端多用户） | 规划 / 未实现；**不等于**已发布的本地 loopback Operator Console | 同上；对照 `docs/design/archive/2026-07-21-local-operator-console-from-pi-web.md` |
+| fullstack Delivery / Final Verification live 闭环 | 进行中（active train） | `docs/exec-plans/active/2026-07-19-fullstack-dogfood-016x-release-train.md` |
+| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/active/dynamic-workflow-dag-engine-roadmap.md` |
+| Loop 与 Dynamic Workflow 更深双向集成 / 自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action |
+| Operator Chat 作为主操作会话（裸 bash 收敛、真 human gate、durable session/turn、Operation 闭环、完整 CLI action coverage、默认入口切换） | 设计输入 / 未达主会话门槛 | `docs/design/active/operator-chat-primary-session-roadmap.md`；Phase 4 General Operator Chat 本体已实现归档（`docs/exec-plans/completed/2026-07-25-console-phase-4-general-operator-chat.md`） |
+| Eval Lab auto-promote / RSI Level 1 产品声称 | **禁止**写成已交付 | Eval Lab design + active plan |
+
+> 本地 Operator Console 统一面（实际首发 0.19.0）已发布：单仓库、loopback、随 `@tea-agent/loop-agent` 同包、canonical mutation 只经 sibling CLI，Inspect 复用 GET-only Observe read model。它不是远端 Web Console，也不能把多租户/云编排需求偷渡进本地 Console。
+
+> 注意：`docs/design/active/dynamic-workflow-dag-engine-roadmap.md` 含 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
+
+## 已收敛为 archive / 历史基线（非未来）
+
+- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`docs/design/archive/2026-07-12-第二月规划.md`。
+- `docs/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**（允许有限再采样），不当第二 CHANGELOG。
+- 活能力短摘要在 `docs/reports/current-capability-summary.md`。
+- 专题证据按类型落在 `docs/reports/{feature,init-evolution,merge,fullstack-dogfood,dogfood}/`。
+
+## 文档本体的演进边界
+
+- 本目录新增文档随发布包发布（`package.json` `files` + manifest `packageRequired` 显式条目），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+- `runtime-boundaries.md` 是边界真源；本目录其他文档交叉引用，不复制其 import 方向表 / governance-hook 表 / 版本化自举边界表。
+- 未来如有能力落地，应先改 `src/` / CLI / ADR / completed plan，再回写本目录的「已实现」表与站上 `website/docs/overview/*` 短索引。