@tea-agent/loop-agent 0.27.1 → 0.28.0

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

@@ -4,9 +4,9 @@ import path from "node:path";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
 import { readControllerIdentityArtifact, captureControllerIdentity } from "./controller-identity.js";
-import { DAG_RUNS_DIR, getDagRunDir, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
+import { DAG_RUNS_DIR, getDagRunDir, isDagNonExecutionLifecycle, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
 import { buildDagRunId, runDagContinuation, } from "./runner.js";
-import { evaluateDagRerunPlan, evaluateLiveDagRerunBindings, } from "./rerun-plan.js";
+import { computePlanHash, evaluateDagRerunPlan, evaluateLiveDagRerunBindings, } from "./rerun-plan.js";
 import { prepareActiveRunDir, writeNodeRecord, writeRunSpec, writeRunState, } from "./run-store.js";
 import { cloneParentSkillSnapshotForContinuation, readSkillSnapshot, } from "./skill-snapshot.js";
 import { topoSortToRanks } from "./topo.js";
@@ -123,6 +123,65 @@ export async function planDagRerun(input) {
         const nonCompletedSpec = await readDagRunSpec(located.runDir);
         const nonCompletedState = await readDagRunState(located.runDir);
         const nonCompletedWorkerHints = await detectWorkerManagedRun(located.runDir, nonCompletedState, nonCompletedSpec);
+        // evaluateDagRerunPlan only accepts execution lifecycles. Audit parents must
+        // not be cast to "active" (reconcile) or "paused" (resume). Also avoid routing
+        // audit through evaluate: missing workspace checkpoint would surface as
+        // standalone-task-rerun instead of the required fail-closed manual action.
+        if (isDagNonExecutionLifecycle(located.lifecycle)) {
+            const bindingStatus = await evaluateLiveDagRerunBindings({
+                cwd: input.cwd,
+                parentSpec: nonCompletedSpec,
+            });
+            const workerAssociation = nonCompletedWorkerHints.workerManaged
+                ? {
+                    kind: "worker-managed",
+                    ...(nonCompletedWorkerHints.featureId
+                        ? { featureId: nonCompletedWorkerHints.featureId }
+                        : {}),
+                    ...(nonCompletedWorkerHints.taskId
+                        ? { taskId: nonCompletedWorkerHints.taskId }
+                        : {}),
+                    ...(nonCompletedWorkerHints.workerRunId
+                        ? { workerRunId: nonCompletedWorkerHints.workerRunId }
+                        : {}),
+                }
+                : { kind: "standalone" };
+            const planWithoutHash = {
+                schemaVersion: 1,
+                eligible: false,
+                parentRunId: input.parentRunId,
+                parentLifecycle: located.lifecycle,
+                selectedNodeId: input.selectedNodeId,
+                rewriteApplied: false,
+                resetNodeIds: [],
+                importedNodeIds: [],
+                blockingNodes: [],
+                reasonCodes: ["parent-lifecycle-ineligible"],
+                blockedReasons: ["parent-lifecycle-ineligible"],
+                risk: "high",
+                bindings: {
+                    sourceBindingMatched: bindingStatus.sourceBindingMatched,
+                    taskContractBindingMatched: bindingStatus.taskContractBindingMatched,
+                    controllerIdentityMatched: true,
+                    skillSnapshotVerified: true,
+                    workspaceMatched: false,
+                },
+                workerAssociation,
+                estimatedExecution: {
+                    nodeCount: 0,
+                    piCallCount: 0,
+                    shellNodeCount: 0,
+                    avoidedNodeCount: 0,
+                    avoidedPiCallCount: 0,
+                },
+                suggestedAction: "manual",
+            };
+            return {
+                ...planWithoutHash,
+                planHash: computePlanHash(planWithoutHash),
+            };
+        }
+        const parentLifecycle = located.lifecycle === "active" ? "active" : "paused";
         return evaluateDagRerunPlan({
             cwd: input.cwd,
             parentRunId: input.parentRunId,
@@ -130,7 +189,7 @@ export async function planDagRerun(input) {
             parentRunDir: located.runDir,
             parentSpec: nonCompletedSpec,
             parentState: nonCompletedState,
-            parentLifecycle: located.lifecycle,
+            parentLifecycle,
             workerManaged: nonCompletedWorkerHints.workerManaged,
             workerAssociation: nonCompletedWorkerHints.workerManaged
                 ? {

package/dist/workflows/dag/run-store.js

@@ -11,10 +11,15 @@ export async function writeRunState(runDir, state, options) {
 export async function readRunSpec(runDir) {
     return readDagRunSpec(runDir);
 }
-export async function prepareActiveRunDir(runDir) {
+/** Prepare any lifecycle run directory (active / dry-run / init-only / …). */
+export async function prepareRunDir(runDir) {
     await rm(runDir, { recursive: true, force: true });
     await mkdir(runDir, { recursive: true });
 }
+/** @deprecated Prefer prepareRunDir; kept as thin alias for execute callers. */
+export async function prepareActiveRunDir(runDir) {
+    await prepareRunDir(runDir);
+}
 export async function writeRunSpec(runDir, spec) {
     await writeJsonAtomic(path.join(runDir, "run.json"), spec);
 }

package/dist/workflows/dag/runner.js

@@ -7,7 +7,7 @@ import { readCandidateRecord } from "../../infrastructure/evaluation/candidate-s
 import { CANONICAL_TASK_ID_PATTERN, formatLocalCompactDate, } from "../../task/runtime.js";
 import { assertFrozenBudget, initRunBudgetLedger, preflightBudgetOrBreach, recordFinishedNodeBudget, writeBudgetLedgerArtifacts, } from "./budget-enforcement.js";
 import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readHumanApprovalArtifact, requireActiveDagRun, } from "./lifecycle.js";
-import { moveToCompletedRunDir, moveToPausedRunDir, prepareActiveRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
+import { moveToCompletedRunDir, moveToPausedRunDir, prepareRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
 import { evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
 import { createDagNodeExecutor } from "./executor-registry.js";
 import { executeDagPiNode } from "../../executors/dag-pi-executor.js";
@@ -126,12 +126,18 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
                 : {}),
         };
     }
+    const executionMode = opts.dryRun
+        ? "dry-run"
+        : opts.initOnly
+            ? "init-only"
+            : "execute";
     const state = {
         version: 1,
         title: spec.title,
         runId,
         cwd: opts.cwd,
         startedAt: new Date().toISOString(),
+        executionMode,
         runner: {
             pid: process.pid,
             hostname: hostname(),
@@ -212,8 +218,14 @@ export async function runDag(spec, opts) {
     const activeRunDir = getDagRunDir(opts.cwd, "active", state.runId);
     const completedRunDir = getDagRunDir(opts.cwd, "completed", state.runId);
     const pausedRunDir = getDagRunDir(opts.cwd, "paused", state.runId);
-    const runDir = activeRunDir;
-    await prepareActiveRunDir(runDir);
+    // R-A2: non-execution modes use dedicated lifecycles; only execute enters active/.
+    const lifecycleDir = state.executionMode === "dry-run"
+        ? "dry-run"
+        : state.executionMode === "init-only"
+            ? "init-only"
+            : "active";
+    const runDir = getDagRunDir(opts.cwd, lifecycleDir, state.runId);
+    await prepareRunDir(runDir);
     await writeRunSpec(runDir, spec);
     // Freeze the running controller identity as a run-owned fact before the
     // first canonical state write, reusing the identity resolved for preflight.

package/dist/workflows/dag/types.js

@@ -10,6 +10,27 @@ 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"]);
+/** Static command capabilities only; tasks cannot inject executables or shell prefixes. */
+export const dagCommandCapabilitySchema = z.enum(["playwright-cli"]);
+export const dagCommandPolicySchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("deny") }).strict(),
+    z
+        .object({
+        mode: z.literal("capability-allowlist"),
+        capabilities: z.array(dagCommandCapabilitySchema).min(1),
+    })
+        .strict(),
+]);
+/** Undefined / omitted commandPolicy is treated as deny by executors and validators. */
+export function resolveDagCommandPolicy(policy) {
+    return policy ?? { mode: "deny" };
+}
+export function dagCommandPolicyAllows(policy, capability) {
+    const resolved = resolveDagCommandPolicy(policy);
+    if (resolved.mode !== "capability-allowlist")
+        return false;
+    return resolved.capabilities.includes(capability);
+}
 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"]);
@@ -319,6 +340,7 @@ export const dagBackendTestPipelineSchema = z.enum([
     "markdown-execute-html",
     "markdown-manifest",
 ]);
+export const dagFrontendBrowserToolPreflightSchema = z.object({}).strict();
 export const dagFrontendTestEvidenceValidationSchema = z.object({}).strict();
 export const dagFrontendTestCaseChecklistSchema = z.object({}).strict();
 export const dagFrontendTestHtmlReportSchema = z.object({}).strict();
@@ -369,6 +391,7 @@ export const dagShellConfigSchema = z.object({
     frontendVerificationBundle: dagFrontendVerificationBundleSchema.optional(),
     frontendReviewContext: dagFrontendReviewContextSchema.optional(),
     frontendTestCaseChecklist: dagFrontendTestCaseChecklistSchema.optional(),
+    frontendBrowserToolPreflight: dagFrontendBrowserToolPreflightSchema.optional(),
     frontendTestEvidenceValidation: dagFrontendTestEvidenceValidationSchema.optional(),
     frontendTestL5Report: z.object({}).strict().optional(),
     frontendTestHtmlReport: dagFrontendTestHtmlReportSchema.optional(),
@@ -416,6 +439,7 @@ export const dagDynamicExpansionChildTaskSchema = z.object({
     outputContract: z.string().optional(),
     staticResultTemplate: z.string().optional(),
     toolProfile: dagToolProfileSchema.optional(),
+    commandPolicy: dagCommandPolicySchema.optional(),
     writePolicy: dagWritePolicySchema.optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
@@ -487,6 +511,7 @@ export const dagDynamicLoopBodyTaskSchema = z.object({
     outputContract: z.string().optional(),
     staticResultTemplate: z.string().optional(),
     toolProfile: dagToolProfileSchema.optional(),
+    commandPolicy: dagCommandPolicySchema.optional(),
     writePolicy: dagWritePolicySchema.optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
@@ -558,6 +583,8 @@ export const dagTaskSchema = z.object({
     role: dagRoleSchema.optional(),
     skills: z.array(z.string()).optional(),
     toolProfile: dagToolProfileSchema.optional(),
+    /** Default deny: file write (toolProfile=write) does not grant command execution. */
+    commandPolicy: dagCommandPolicySchema.optional(),
     writePolicy: dagWritePolicySchema.optional(),
     writeSet: z.array(z.string()).optional(),
     piStep: z.string().optional(),

package/dist/workflows/dag/validate.js

@@ -1,4 +1,4 @@
-import { DEFAULT_DAG_EXECUTOR_MODELS, ENV_VAR_NAME_PATTERN, } from "./types.js";
+import { DEFAULT_DAG_EXECUTOR_MODELS, ENV_VAR_NAME_PATTERN, dagCommandPolicyAllows, resolveDagCommandPolicy, } from "./types.js";
 import { resolveShellCommands } from "../../executors/shell-executor.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { resolveRepairTaskForGate } from "./repair-artifact.js";
@@ -461,6 +461,7 @@ function validateShellTaskConfig(task, spec, issues) {
         !shell.jsonArtifactGate &&
         !shell.backendTestPipeline &&
         !shell.frontendPrewriteGate &&
+        !shell.frontendBrowserToolPreflight &&
         !shell.frontendVerificationBundle &&
         !shell.frontendReviewContext &&
         !shell.frontendTestCaseChecklist &&
@@ -623,6 +624,104 @@ function validateWriterOutcomePolicyTaskConfig(task, issues) {
         });
     }
 }
+function isFrontendEvidenceWriteSet(writeSet) {
+    const entries = writeSet ?? [];
+    if (entries.length === 0)
+        return false;
+    return entries.every((entry) => {
+        const normalized = entry.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+        return (normalized === "testcase/frontend/evidence/**" ||
+            normalized.startsWith("testcase/frontend/evidence/"));
+    });
+}
+function isFrontendBrowserExecutorTask(task) {
+    const skills = task.skills ?? [];
+    return (task.executor === "pi" &&
+        task.toolProfile === "write" &&
+        skills.includes("playwright-cli") &&
+        isFrontendEvidenceWriteSet(task.writeSet));
+}
+function taskMentionsPlaywrightCliContract(task) {
+    const prompt = `${task.subtask_prompt}\n${task.outputContract ?? ""}`;
+    return /playwright[_-]?cli/i.test(prompt);
+}
+/**
+ * Command capability is orthogonal to file write. Fail closed when:
+ * - frontend browser executors lack playwright-cli capability
+ * - capability is granted without skill/prompt contract or outside evidence writeSet
+ * - non-browser nodes receive command capability
+ */
+function validateCommandPolicyTaskConfig(task, issues) {
+    const policy = resolveDagCommandPolicy(task.commandPolicy);
+    const allowsPlaywright = dagCommandPolicyAllows(task.commandPolicy, "playwright-cli");
+    const isBrowserExecutor = isFrontendBrowserExecutorTask(task);
+    if (isBrowserExecutor && !allowsPlaywright) {
+        issues.push({
+            type: "invalid-command-policy",
+            message: `frontend-test browser executor requires playwright-cli command capability (task ${task.id})`,
+        });
+    }
+    if (policy.mode === "deny") {
+        return;
+    }
+    if (task.executor !== "pi") {
+        issues.push({
+            type: "invalid-command-policy",
+            message: `task ${task.id} commandPolicy requires executor=pi`,
+        });
+        return;
+    }
+    if (allowsPlaywright) {
+        const skills = task.skills ?? [];
+        if (!skills.includes("playwright-cli")) {
+            issues.push({
+                type: "invalid-command-policy",
+                message: `task ${task.id} playwright-cli command capability requires skills to include playwright-cli`,
+            });
+        }
+        if (!taskMentionsPlaywrightCliContract(task)) {
+            issues.push({
+                type: "invalid-command-policy",
+                message: `task ${task.id} playwright-cli command capability requires prompt/outputContract to reference playwright_cli`,
+            });
+        }
+        if (!isFrontendEvidenceWriteSet(task.writeSet)) {
+            issues.push({
+                type: "invalid-command-policy",
+                message: `task ${task.id} playwright-cli command capability requires frontend evidence writeSet under testcase/frontend/evidence/`,
+            });
+        }
+        if (task.toolProfile !== "write") {
+            issues.push({
+                type: "invalid-command-policy",
+                message: `task ${task.id} playwright-cli command capability requires toolProfile=write for evidence mutation`,
+            });
+        }
+    }
+}
+function validateDynamicChildCommandPolicy(task, issues) {
+    const expansion = task.dynamicExpansion;
+    if (!expansion)
+        return;
+    const child = expansion.childTask;
+    const synthetic = {
+        id: `${task.id}-child-template`,
+        depends_on: [],
+        complexity: child.complexity,
+        subtask_prompt: child.subtaskPromptTemplate,
+        executor: child.executor,
+        role: child.role,
+        skills: child.skills,
+        toolProfile: child.toolProfile,
+        commandPolicy: child.commandPolicy,
+        writePolicy: child.writePolicy,
+        allowedPaths: child.allowedPaths,
+        forbiddenPaths: child.forbiddenPaths,
+        writeSet: child.writeSet,
+        outputContract: child.outputContract,
+    };
+    validateCommandPolicyTaskConfig(synthetic, issues);
+}
 function validateDecisionGateTaskConfig(task, issues) {
     if (!task.decisionGate?.enabled) {
         return;
@@ -727,6 +826,25 @@ export function collectForbiddenExecutorIssues(spec, forbiddenExecutors) {
         implicitDefault: rawTasks[index]?.executor === undefined,
     }));
 }
+/** Revalidate a rendered dynamic child before it enters state or executes. */
+export function assertValidMaterializedDagTask(task) {
+    const issues = [];
+    // A minimal v2 carrier makes write-policy validation strict while avoiding
+    // unrelated parent graph/rank checks.  Dynamic templates are validated at
+    // init; this guards values introduced by {{item}} rendering.
+    const spec = { version: 2, tasks: [task] };
+    validateTaskWritePolicy(task, spec, issues);
+    validateShellTaskConfig(task, spec, issues);
+    validateStaticTaskConfig(task, issues);
+    validateDecisionGateTaskConfig(task, issues);
+    validateRetryPolicyTaskConfig(task, issues);
+    validateOutputProtocolTaskConfig(task, issues);
+    validateWriterOutcomePolicyTaskConfig(task, issues);
+    validateCommandPolicyTaskConfig(task, issues);
+    if (issues.length > 0) {
+        throw new Error(`invalid materialized dynamic child ${task.id}: ${issues.map((issue) => issue.message).join("; ")}`);
+    }
+}
 export function validateDagSpec(spec) {
     const issues = [];
     if (spec.tasks.length === 0) {
@@ -778,6 +896,8 @@ export function validateDagSpec(spec) {
         validateRetryPolicyTaskConfig(task, issues);
         validateOutputProtocolTaskConfig(task, issues);
         validateWriterOutcomePolicyTaskConfig(task, issues);
+        validateCommandPolicyTaskConfig(task, issues);
+        validateDynamicChildCommandPolicy(task, issues);
         validateProjectGovernanceTaskConfig(task, spec, issues);
         validateFailureAwareDependsOn(task, spec, issues);
     }

package/docs/architecture/runtime-boundaries.md

@@ -141,7 +141,7 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 版本化自举包含两个不同的冻结层，不能用其中一个替代另一个：
 
 | 层 | 冻结对象 | 生命周期 | 权威证据 |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | Controller identity | 实际发布包、entry/realEntry、launch spec、binary hash、portable package fingerprint | Feature/batch/Task/final verification | Worker、Task Pool、batch/Feature、QA/final evidence 中的 `controllerIdentity` |
 | DAG skill snapshot | 某个 run 实际注入 prompt 的 ordered skill profiles、learned flag、budgets 与 dynamic bindings | 单个 DAG run，包括 pause/resume | `state.skillSnapshotRef` + `<runDir>/.runtime/skill-snapshot.json` |
 
@@ -150,7 +150,7 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 **规则摘要**
 
 | From | May import | Must not import |
-|------|------------|-----------------|
+| ------ | ------------ | ----------------- |
 | `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
 | `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
 | `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
@@ -169,7 +169,7 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
 
 | Script | 检查内容 | 失败条件 |
-|--------|----------|----------|
+| -------- | ---------- | ---------- |
 | `scripts/check-architecture-boundaries.sh` | workflow/executor forbidden import，及 Worker → CLI/commands/application import | 新的未 allowlist violation |
 | `scripts/check-command-registry-drift.sh` | `command-reference.md` 中的 top-level command vs `src/cli/catalog.ts` | 文档引用未注册 command |
 | `scripts/check-exec-plan-index-sync.sh` | `ai_workspace/loop-agent/exec-plans/{active,completed}` 目录文件 vs 对应 `README.md` 索引 | 任一 plan 文件未在索引登记 |
@@ -190,23 +190,25 @@ bash scripts/check-skill-entry.sh
 
 Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
 
-## Client session 瞬态恢复边界
+## Client session 恢复边界
 
-主会话模型偶尔会返回非标准 502 / `LLMRequestError` / 网络抖动 / 超时响应；OpenCode 可能先解析为 `TypeValidationError` 再落成 `UnknownError`，导致内置 APIError 重试不命中。loop-agent 通过 **项目级 OpenCode 插件补偿** 与 **Pi 用户级配置显式启用** 处理该缺口，不修改 OpenCode/Pi 上游，也不引入外部监督器。
+主会话模型有两类常见缺口：**瞬态 UnknownError**（非标准 502 / `LLMRequestError` / 网络抖动 / 超时经 TypeValidation 落入 UnknownError，内置 APIError 重试不命中）与 **上下文过大**（含内网中文「请求上下文过大」及常见英文 overflow 文案，默认 overflow 识别不全）。loop-agent 通过 **职责分离的项目级产物** 补偿，不修改 OpenCode/Pi 上游，也不引入外部监督器，不改默认模型 `contextWindow`。
 
 | 面 | 路径 / 入口 | 边界 |
-|---|---|---|
-| OpenCode 项目插件 | `.opencode/plugins/loop-agent-transient-retry.js`（init surface `generated`） | 直接返回真实 `Hooks.event`，分发 `session.error` / `session.status` / `session.idle` / `message.updated`；每个 session 保存 pending error，busy/retry/unknown/status API 失败只暂停恢复，后续 idle 事件重新驱动单一 worker。`client.session.status({ throwOnError: true })` 在退避前后确认 idle，`client.session.promptAsync(..., throwOnError: true)` 仅在 1.18.9 的 204 响应明确返回对象型 `data` 时计入一次 attempt 并续接同一 session；只有成功完成的 assistant message 清零连续失败计数。认证/权限/配额/上下文溢出/取消/业务错误走 `plugin-ignore-permanent-error` |
+| --- | --- | --- |
+| OpenCode transient-retry | `.opencode/plugins/loop-agent-transient-retry.js`（init surface `generated`） | 仅瞬态 UnknownError resume；busy/retry 门控 + backoff；overflow/401/配额/取消/业务标 permanent（`plugin-ignore-permanent-error`），**不** compact |
+| OpenCode overflow-compact | `.opencode/plugins/loop-agent-context-overflow-compact.js`（init surface `generated`） | 仅 context overflow → `session.compact`（无则 `summarize`）+ 有限 `promptAsync` 续接；`MAX_OVERFLOW_RECOVERIES ≤ 2`；session 锁；非 overflow 不动作 |
+| Pi project extension | `.pi/extensions/loop-agent-context-overflow.js`（init surface `generated`） | `message_end` 上将 overflow `errorMessage` 幂等改写为 `context_length_exceeded:` 前缀，触发 Pi 原生 compact/retry；**不**写 `~/.pi` settings / compaction / 模型窗口 |
 | Pi 用户配置 | `~/.pi/agent/settings.json` | **不**进入项目 `.harness/init-surface.json` hash；仅 `--client-recovery=user` 可字段级补缺并原子写；`auto`/`project`/`off` 与 `check-update` 默认零写 home；读取时只有 `ENOENT` 视为缺文件，其他 I/O 错误 fail closed |
-| CLI mode | `--client-recovery=auto\|project\|user\|off`（默认 `auto`） | `auto`/`project` 只装项目插件；`user` = 项目插件 + 显式 Pi 合并；`off` 全跳过 |
-| Ownership | recorded sha256 + apply-safe | 插件缺失可补、与 recorded hash 一致可升级；用户改过 → model merge / human decision，禁止静默覆盖 |
+| CLI mode | `--client-recovery=auto\|project\|user\|off`（默认 `auto`） | `auto`/`project` 安装上述三份项目产物；`user` = 三产物 + 显式 Pi retry 合并；`off` 全跳过 |
+| Ownership | recorded sha256 + apply-safe | 三份 generated 缺失可补、与 recorded hash 一致可升级；用户改过 → model merge / human decision，禁止静默覆盖 |
 
-实现落点：`src/commands/client-recovery.ts`（纯逻辑与生成器）+ `src/commands/init.ts`（编排）。
+实现落点：`src/commands/client-recovery.ts`（共享 `isContextOverflow`、生成器与 install）+ `src/commands/init.ts`（surface 编排与 `written` 投影）。
 
 ## 演进里程碑
 
 | Phase | 边界变化 |
-|-------|----------|
+| ------- | ---------- |
 | 0（当前） | 文档 + 机器 guard；已知 loop/actions.ts 耦合 advisory |
 | 1 | CLI command definition 单源 |
 | 2 | Skill entry 瘦身 + frontmatter references |

package/docs/init-surface.manifest.json

@@ -166,7 +166,9 @@
     "docs/templates/backend-test-execution.schema.json",
     "docs/templates/backend-test-result.schema.json",
     "docs/templates/backend-test-case-manifest.schema.json",
-    ".opencode/plugins/loop-agent-transient-retry.js"
+    ".opencode/plugins/loop-agent-transient-retry.js",
+    ".opencode/plugins/loop-agent-context-overflow-compact.js",
+    ".pi/extensions/loop-agent-context-overflow.js"
   ],
   "initSurface": {
     "README.md": "managed-block",
@@ -247,7 +249,9 @@
     "docs/templates/backend-test-execution.schema.json": "copied",
     "docs/templates/backend-test-result.schema.json": "copied",
     "docs/templates/backend-test-case-manifest.schema.json": "copied",
-    ".opencode/plugins/loop-agent-transient-retry.js": "generated"
+    ".opencode/plugins/loop-agent-transient-retry.js": "generated",
+    ".opencode/plugins/loop-agent-context-overflow-compact.js": "generated",
+    ".pi/extensions/loop-agent-context-overflow.js": "generated"
   },
   "packageExcluded": [
     "docs/progress/20*.md",

package/docs/templates/README.md

@@ -37,7 +37,15 @@
 
 - `frontend-task-requirement.md`、`frontend-task-constraints.md`、`frontend-design-contract.md` — 前端任务输入与设计合同。
 - `frontend-implementation-contract.schema.json` — 前端实现合同 schema。
-- `frontend-test-dag.json` — frontend-test DAG 模板。
+- `frontend-test-dag.json` — frontend-test DAG 模板；其 deterministic checklist 会拒绝 alternative executable instructions，仅允许 allowlisted `playwright-cli` command。Pi generator/reviser 的 runtime writeSet 仅授权下列目标项目生成路径（不是本仓库文档索引目标）：
+
+  ~~~text
+  testcase/frontend/cases/FE-*.md
+  testcase/frontend/cases/index.md
+  testcase/frontend/cases/manifest.draft.json
+  ~~~
+
+  Pi writer writeSet 不包含 final manifest（文件名 manifest.json）。依赖 checklist 的 exclusive shell materializer 是 final manifest 的唯一写入者，以 temp+rename 原子生成 final，后续 map 只消费该 materializer 输出。
 - `frontend-test-dag.retrieve-context.prompt.md`、`frontend-test-dag.generate-cases.prompt.md`、`frontend-test-dag.review-cases.prompt.md`、`frontend-test-dag.review-execution.prompt.md`、`frontend-test-dag.retrospect.prompt.md` — 上下文、用例、审查、执行审查和复盘提示。
 - `frontend-test-case-checklist.md` — 前端测试用例检查清单。
 

package/docs/templates/frontend-test-dag.generate-cases.prompt.md

@@ -14,15 +14,22 @@ Use `playwright-cli-case-generator`. Read only `testcase/frontend/rag/context.md
 - `casePath` must be `testcase/frontend/cases/<caseId>.md`.
 - `evidenceDir` must be `testcase/frontend/evidence/<caseId>/`.
 
-Each case is independently executable and includes AC mapping (`acIds`), preconditions, cleanup, UI assertions, and its isolated evidence path. Use dimensions `core`, `boundary`, `flow`, or `backend`. Never guess API fields, constraints, SLA, credentials, or unrecorded data.
+Each case is independently executable and includes AC mapping (`acIds`), preconditions, cleanup, a semantic assertion, and its isolated evidence path. Use dimensions `core`, `boundary`, `flow`, or `backend`. Never guess API fields, constraints, SLA, credentials, or unrecorded data. For passed authority, include a successful `playwright-cli find ...` after `open` and before controller post-execution cleanup; `snapshot`, `goto`, `screenshot`, `request`/`console`, and ordinary interactions are not assertions.
 
-Every case must use the **resolved** absolute base URL from `testcase/frontend/rag/context.md` (field `baseUrl` / base URL line). Do not leave a `<base-url>` placeholder. Resolution policy (already applied by retrieve-context): prefer `config.md` frontend URL; else default `http://localhost:5173`.
+Every case must copy the **controller-frozen** absolute base URL supplied by the DAG. `testcase/frontend/rag/context.md` may reference that value, but model-authored context/case prose cannot establish or override the origin. Do not leave a base-url placeholder.
 
-Every case must use this exact browser-start command prefix with that concrete URL:
+Every case must start with `playwright-cli open --browser=chrome --headed` followed by the concrete controller-frozen URL supplied by the DAG. Do not copy an angle-bracket URL placeholder into a generated executable case line.
 
-```text
-playwright-cli open --browser=chrome --headed <resolved-base-url-from-context.md>
-```
+### Dynamic element refs (hard)
+
+- Executable `playwright-cli` lines must never contain angle-bracket dynamic-ref tokens such as `<fresh-ref>` or descriptive `<...>` placeholders.
+- Use only shell-safe documentation placeholders `eX`, `eY`, ... for dynamic element refs. Each placeholder means the real `eNN` ref parsed from the immediately preceding latest `snapshot` output.
+- Before each element interaction, write a fresh `snapshot` step. A later snapshot invalidates earlier refs: do not reuse a stale ref.
+- `eX`/`eY` are documentation placeholders, not literal structured-tool arguments; the browser child resolves them to the current real `eNN` before its tool call.
+
+At execution time the browser child translates each `playwright-cli` line into one structured `playwright_cli` tool call (no Bash). Keep Markdown steps as CLI lines so the executor can map them 1:1.
+
+For file evidence, use canonical `--filename` only. For screenshots, use `playwright-cli screenshot --filename final.png`; when a real ref from the latest `snapshot` is needed, use `playwright-cli screenshot e5 --filename final.png`. For PDF use `playwright-cli pdf --filename final.pdf`. A `snapshot` without filename is response-only; for a file use `playwright-cli snapshot --filename snapshot.txt`. Never write `playwright-cli screenshot <path>`, use `--path`, `--output`, or `--file`, or put an output path in a positional target slot.
 
 Do not put a session flag before `open`. Every later Playwright CLI command must stay in that same default browser session: do **not** emit `-s=<case-id>`, `-s=...`, or assume an undocumented named-session binding.
 
@@ -45,4 +52,4 @@ Each case must require the executor to persist, even when blocked:
 - `testcase/frontend/evidence/<case-id>/execution.md`
 - `testcase/frontend/evidence/<case-id>/case-result.json`
 
-`case-result.json` must be valid JSON containing the matching `caseId`, `status` (`passed`, `failed`, or `blocked`), and an `evidencePaths` array. A blocked result must include a non-empty `blockedReason`, such as `isolated-test-environment-unavailable` or `token-budget-exhausted`, and must never claim or imply a pass. `execution.md` records attempted or blocked steps, base-URL safety decision, fixture/reset and request-observation availability, timestamps, and the evidence-file list. Screenshots, snapshots, traces, videos, and logs are required only when actually available and must stay under the same case evidence directory.
+`case-result.json` must be valid JSON containing the matching `caseId`, `status` (`passed`, `failed`, or `blocked`), and an `evidencePaths` array. A blocked result must include a non-empty `blockedReason`, such as `isolated-test-environment-unavailable` or `token-budget-exhausted`, and must never claim or imply a pass. `execution.md` records attempted or blocked steps, base-URL safety decision, fixture/reset and request-observation availability, timestamps, and the evidence-file list. Available evidence files are required only when actually produced and must stay under the same case evidence directory.