@tea-agent/loop-agent 0.28.7 → 0.28.9

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

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHumanEscalationArtifacts, } from "./decision-envelope.js";
 import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
 import { resolveContextPolicy } from "./context-policy.js";
@@ -18,6 +19,100 @@ import { parseRepairArtifactFromText, resolveRepairTaskForGate, validateRepairAr
 import { resolveModelForTask, } from "./types.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
 import { resolveExecutorThinkingMatrix } from "../../executors/model-routing.js";
+function canonicalApprovalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalApprovalJson(entry)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalApprovalJson(record[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+export function parseAndValidateFinalWriteSetApproval(input) {
+    const binding = input.task.finalWriteSetApproval;
+    if (!binding) {
+        return { ok: false, reason: "missing final write-set approval binding", approvalSourceNodeId: "(missing)" };
+    }
+    const source = input.state.nodes[binding.approvalSourceNodeId];
+    if (source?.status !== "FINISHED" || parseProcessVerdict(source) !== "pass") {
+        return {
+            ok: false,
+            reason: "final write-set approval source did not finish with VERDICT: pass",
+            approvalSourceNodeId: binding.approvalSourceNodeId,
+        };
+    }
+    const raw = canonicalNodeOutput(source);
+    const blocks = [...raw.matchAll(/```FINAL_WRITE_SET_APPROVAL_JSON\s*\r?\n([\s\S]*?)\r?\n```/g)];
+    if (blocks.length !== 1) {
+        return { ok: false, reason: `expected exactly one FINAL_WRITE_SET_APPROVAL_JSON block, found ${blocks.length}`, approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    let approval;
+    try {
+        approval = JSON.parse(blocks[0][1]);
+    }
+    catch {
+        return { ok: false, reason: "final write-set approval is not valid JSON", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const required = ["schemaVersion", "writerNodeId", "approvalSourceNodeId", "auditedPlanNodeId", "approvedWriteSet", "taskContractSha256", "auditedPlanSha256", "approvalDigest"];
+    if (Object.keys(approval).length !== required.length || required.some((key) => !(key in approval))) {
+        return { ok: false, reason: "final write-set approval has an invalid schema", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const approved = approval.approvedWriteSet;
+    if (approval.schemaVersion !== 1 ||
+        approval.writerNodeId !== binding.writerNodeId ||
+        approval.writerNodeId !== input.task.id ||
+        approval.approvalSourceNodeId !== binding.approvalSourceNodeId ||
+        approval.auditedPlanNodeId !== binding.auditedPlanNodeId ||
+        !Array.isArray(approved) ||
+        !approved.every((entry) => typeof entry === "string") ||
+        typeof approval.taskContractSha256 !== "string" ||
+        typeof approval.auditedPlanSha256 !== "string" ||
+        typeof approval.approvalDigest !== "string") {
+        return { ok: false, reason: "final write-set approval binding or field types are invalid", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    if (!/^[a-f0-9]{64}$/.test(approval.taskContractSha256) ||
+        !/^[a-f0-9]{64}$/.test(approval.auditedPlanSha256) ||
+        !/^[a-f0-9]{64}$/.test(approval.approvalDigest)) {
+        return { ok: false, reason: "final write-set approval digest fields are invalid", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const canonicalPayload = { ...approval };
+    delete canonicalPayload.approvalDigest;
+    const expectedDigest = createHash("sha256")
+        .update(canonicalApprovalJson(canonicalPayload))
+        .digest("hex");
+    if (approval.approvalDigest !== expectedDigest) {
+        return { ok: false, reason: "final write-set approval digest mismatch", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const expectedTaskDigest = input.spec.taskContractBinding?.canonicalHash;
+    const plan = input.state.nodes[binding.auditedPlanNodeId];
+    const expectedPlanDigest = createHash("sha256")
+        .update(canonicalNodeOutput(plan))
+        .digest("hex");
+    if (!expectedTaskDigest || approval.taskContractSha256 !== expectedTaskDigest || approval.auditedPlanSha256 !== expectedPlanDigest) {
+        return { ok: false, reason: "final write-set approval is stale for the task contract or audited plan", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const effectiveWriteSet = approved;
+    if (effectiveWriteSet.length === 0 || new Set(effectiveWriteSet).size !== effectiveWriteSet.length) {
+        return { ok: false, reason: "final write-set approval must contain a non-empty ordered unique path set", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    for (const entry of effectiveWriteSet) {
+        const normalized = entry.replace(/\\/g, "/").replace(/^\.\//, "");
+        if (!normalized || normalized === "." || normalized === ".." || normalized.includes("*") || normalized.includes("?") || normalized.includes("REPLACE/") || normalized.includes("PLACEHOLDER")) {
+            return { ok: false, reason: `final write-set approval contains a broad or placeholder path: ${entry}`, approvalSourceNodeId: binding.approvalSourceNodeId };
+        }
+        if (!input.task.allowedPaths.some((allowed) => pathMatchesPattern(normalized, allowed))) {
+            return { ok: false, reason: `final write-set approval exceeds allowedPaths: ${entry}`, approvalSourceNodeId: binding.approvalSourceNodeId };
+        }
+        if (input.task.forbiddenPaths.some((forbidden) => pathMatchesPattern(normalized, forbidden))) {
+            return { ok: false, reason: `final write-set approval overlaps forbiddenPaths: ${entry}`, approvalSourceNodeId: binding.approvalSourceNodeId };
+        }
+    }
+    return { ok: true, effectiveWriteSet, approvalDigest: approval.approvalDigest };
+}
 export function buildNodePrompt(spec, task, upstream, options) {
     const policy = resolveContextPolicy(spec);
     return buildDagNodePromptEnvelope({
@@ -193,6 +288,13 @@ function recordRepairArtifactForSupervisorNode(input) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function durationBetween(startedAt, finishedAt) {
+    const started = startedAt ? new Date(startedAt).getTime() : Number.NaN;
+    const finished = finishedAt ? new Date(finishedAt).getTime() : Number.NaN;
+    return Number.isFinite(started) && Number.isFinite(finished)
+        ? Math.max(0, finished - started)
+        : 0;
+}
 function sumAttemptMetric(attempts, select) {
     const values = attempts.map(select).filter((value) => value !== undefined);
     return values.length > 0
@@ -213,7 +315,7 @@ async function notifyNodeObserver(observer, event, nodeId, state, chunk) {
 }
 export async function executeDagNode(input) {
     const { nodeId, tasksById, state, spec, cwd, runDir, executeNode } = input;
-    const task = tasksById.get(nodeId);
+    let task = tasksById.get(nodeId);
     const node = state.nodes[nodeId];
     const failBeforePrompt = async (error, failureCategory) => {
         const failedAt = new Date().toISOString();
@@ -223,13 +325,42 @@ export async function executeDagNode(input) {
         node.failureCategory = failureCategory;
         node.finishedAt = failedAt;
         node.lastActivityAt = node.finishedAt;
-        node.durationMs = Math.max(0, Date.now() - new Date(node.startedAt).getTime());
+        node.durationMs = durationBetween(node.startedAt, node.finishedAt);
+        node.timing = { retryBackoffMs: 0, settlementCleanupMs: 0 };
         state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
         await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
         await input.persistState();
         await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
     };
     const failSkillSnapshot = (error) => failBeforePrompt(error, "skill-snapshot-integrity");
+    if (task.finalWriteSetApproval) {
+        const authorization = parseAndValidateFinalWriteSetApproval({ task, spec, state });
+        if (!authorization.ok) {
+            node.runtimeWriteAuthorization = {
+                schemaVersion: 1,
+                status: "rejected",
+                approvalSourceNodeId: authorization.approvalSourceNodeId,
+                reason: authorization.reason,
+            };
+            await failBeforePrompt(new Error(`final-write-set-approval-invalid: ${authorization.reason}`), "final-write-set-approval-invalid");
+            return;
+        }
+        task = {
+            ...task,
+            writeSet: authorization.effectiveWriteSet,
+            resolvedFinalWriteSetApproval: {
+                approvalDigest: authorization.approvalDigest,
+                approvalSourceNodeId: task.finalWriteSetApproval.approvalSourceNodeId,
+            },
+        };
+        node.runtimeWriteAuthorization = {
+            schemaVersion: 1,
+            status: "validated",
+            approvalSourceNodeId: task.finalWriteSetApproval.approvalSourceNodeId,
+            approvalDigest: authorization.approvalDigest,
+            effectiveWriteSet: [...authorization.effectiveWriteSet],
+        };
+    }
     let projectGovernanceContext;
     if (task.governanceStandardReview) {
         try {
@@ -301,7 +432,7 @@ export async function executeDagNode(input) {
     await input.persistState();
     await notifyNodeObserver(input.observer, "onNodeStart", nodeId, state);
     if (isDynamicTask) {
-        const started = Date.now();
+        const dynamicExecutionStartedAt = new Date().toISOString();
         try {
             const result = await input.executeDynamicNode({
                 task,
@@ -314,20 +445,17 @@ export async function executeDagNode(input) {
                 observer: input.observer,
                 persistState: input.persistState,
             });
-            node.durationMs = result.durationMs ?? Date.now() - started;
             node.stdout = result.stdout;
             node.stderr = result.stderr;
             node.failureCategory = result.failureCategory;
-            node.finishedAt = new Date().toISOString();
-            node.lastActivityAt = node.finishedAt;
             node.status = result.ok ? "FINISHED" : "ERROR";
         }
         catch (error) {
             node.status = "ERROR";
             node.stderr = error instanceof Error ? error.message : String(error);
-            node.finishedAt = new Date().toISOString();
-            node.durationMs = Date.now() - started;
         }
+        const dynamicExecutionFinishedAt = new Date().toISOString();
+        const dynamicExecutionWallDurationMs = durationBetween(dynamicExecutionStartedAt, dynamicExecutionFinishedAt);
         if (node.status === "FINISHED") {
             const artifactMeta = await persistLongNodeOutputArtifacts({
                 runDir,
@@ -337,6 +465,14 @@ export async function executeDagNode(input) {
             });
             Object.assign(node, artifactMeta);
         }
+        const dynamicFinishedAt = new Date().toISOString();
+        node.finishedAt = dynamicFinishedAt;
+        node.lastActivityAt = dynamicFinishedAt;
+        node.durationMs = durationBetween(node.startedAt, dynamicFinishedAt);
+        node.timing = {
+            retryBackoffMs: 0,
+            settlementCleanupMs: Math.max(0, node.durationMs - dynamicExecutionWallDurationMs),
+        };
         state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
         await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
         await input.persistState();
@@ -382,6 +518,7 @@ export async function executeDagNode(input) {
         : undefined;
     const maxAttempts = retryPolicy?.maxAttempts ?? 1;
     const attempts = [];
+    let totalAttemptWallDurationMs = 0;
     let totalBackoffMs = 0;
     const livenessPolicy = resolveLivenessPolicy(spec.defaults?.livenessPolicy, task.livenessPolicy);
     /**
@@ -422,7 +559,6 @@ export async function executeDagNode(input) {
     let previousProtocolReason;
     for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
         const attemptStartedAt = new Date().toISOString();
-        const attemptStarted = Date.now();
         node.currentAttempt = attemptNumber;
         node.livenessStatus = "active";
         let result;
@@ -450,7 +586,7 @@ export async function executeDagNode(input) {
                 ok: false,
                 stdout: "",
                 stderr: error instanceof Error ? error.message : String(error),
-                durationMs: Date.now() - attemptStarted,
+                durationMs: 0,
             };
         }
         // R0: executor ok=true still fails closed when outputProtocol is violated.
@@ -474,11 +610,14 @@ export async function executeDagNode(input) {
             }
         }
         const attemptFinishedAt = new Date().toISOString();
+        const attemptWallDurationMs = durationBetween(attemptStartedAt, attemptFinishedAt);
+        totalAttemptWallDurationMs += attemptWallDurationMs;
         const attemptRecord = {
             attempt: attemptNumber,
             startedAt: attemptStartedAt,
             finishedAt: attemptFinishedAt,
-            durationMs: result.durationMs ?? Date.now() - attemptStarted,
+            durationMs: attemptWallDurationMs,
+            timing: { executorDurationMs: result.durationMs },
             ok: result.ok,
             stdout: result.stdout,
             stderr: result.stderr,
@@ -500,10 +639,7 @@ export async function executeDagNode(input) {
         }
         // Reflect the latest attempt on the node so progress is observable,
         // but keep node.status RUNNING while retry is still possible.
-        node.durationMs =
-            retryPolicy === undefined
-                ? attemptRecord.durationMs
-                : attempts.reduce((sum, attempt) => sum + (attempt.durationMs ?? 0), 0) + totalBackoffMs;
+        node.durationMs = durationBetween(node.startedAt, attemptFinishedAt);
         node.stdout = result.stdout;
         node.stderr = result.stderr;
         node.failureCategory = result.failureCategory;
@@ -543,8 +679,10 @@ export async function executeDagNode(input) {
             break;
         const delayMs = computeBackoffDelayMs(attemptNumber + 1, retryPolicy);
         if (delayMs > 0) {
-            totalBackoffMs += delayMs;
+            const backoffStartedAt = new Date().toISOString();
             await sleep(delayMs);
+            const backoffFinishedAt = new Date().toISOString();
+            totalBackoffMs += durationBetween(backoffStartedAt, backoffFinishedAt);
             // Keep lastActivityAt fresh so backoff wait is not misread as node-quiet.
             node.lastActivityAt = new Date().toISOString();
             state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
@@ -591,7 +729,6 @@ export async function executeDagNode(input) {
         }
     }
     const result = terminalResult;
-    const started = Date.now();
     try {
         recordRepairArtifactForSupervisorNode({
             task,
@@ -602,8 +739,6 @@ export async function executeDagNode(input) {
         if (outputChunk.trim()) {
             await notifyNodeObserver(input.observer, "onNodeOutput", nodeId, state, outputChunk);
         }
-        node.finishedAt = new Date().toISOString();
-        node.lastActivityAt = node.finishedAt;
         node.status = result.ok ? "FINISHED" : "ERROR";
         if (result.ok) {
             const decisionRecord = await recordDecisionEnvelopeForNode({
@@ -645,9 +780,19 @@ export async function executeDagNode(input) {
     catch (error) {
         node.status = "ERROR";
         node.stderr = error instanceof Error ? error.message : String(error);
-        node.finishedAt = new Date().toISOString();
-        node.durationMs = Date.now() - started;
     }
+    // Attempt artifacts must observe their own persisted boundaries before the
+    // potentially asynchronous artifact write; post-attempt work belongs to node timing.
+    const terminalFinishedAt = new Date().toISOString();
+    node.finishedAt = terminalFinishedAt;
+    node.lastActivityAt = terminalFinishedAt;
+    node.durationMs = durationBetween(node.startedAt, terminalFinishedAt);
+    node.timing = {
+        retryBackoffMs: totalBackoffMs,
+        settlementCleanupMs: Math.max(0, durationBetween(node.startedAt, terminalFinishedAt) -
+            totalAttemptWallDurationMs -
+            totalBackoffMs),
+    };
     if (node.status === "FINISHED") {
         const artifactMeta = await persistLongNodeOutputArtifacts({
             runDir,
@@ -681,6 +826,16 @@ export async function executeDagNode(input) {
             }
         }
     }
+    const finishedAt = new Date().toISOString();
+    node.finishedAt = finishedAt;
+    node.lastActivityAt = finishedAt;
+    node.durationMs = durationBetween(node.startedAt, finishedAt);
+    node.timing = {
+        ...node.timing,
+        settlementCleanupMs: Math.max(0, durationBetween(node.startedAt, finishedAt) -
+            totalAttemptWallDurationMs -
+            totalBackoffMs),
+    };
     state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
     await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
     await input.persistState();

package/dist/workflows/dag/types.js

@@ -48,6 +48,28 @@ export const dagShellVerifyEvidenceSchema = z.object({
     commandCount: z.number().int().nonnegative(),
     commandLabels: z.array(z.string()).default([]),
     commandTexts: z.array(z.string()).default([]),
+    /** Semantic command identities in the same deterministic order as commandTexts. */
+    canonicalKeys: z.array(z.string()).default([]),
+    /** Commands merged into a retained semantic command, keyed by canonical identity. */
+    mergedCommands: z
+        .array(z.object({
+        canonicalKey: z.string(),
+        keptLabel: z.string(),
+        mergedLabels: z.array(z.string()),
+        /** Retained timeout after semantic duplicates merge, or null when unspecified. */
+        effectiveTimeoutMs: z.number().int().positive().nullable(),
+    }))
+        .default([]),
+    /** Commands omitted only because a retained aggregate is known to cover them. */
+    coveredCommands: z
+        .array(z.object({ aggregateLabel: z.string(), coveredLabel: z.string() }))
+        .default([]),
+    /** Why a command was retained or deferred from the intermediate verify node. */
+    selectionReasons: z.array(z.string()).default([]),
+    /** Non-executing generation-time cwd/local-script validation evidence. */
+    preflight: z
+        .array(z.object({ label: z.string(), status: z.enum(["ok", "future-delivery-script"]) }))
+        .default([]),
     /** Effective timeout applied independently to each shell command. */
     commandTimeoutMs: z.number().int().positive().optional(),
     /** Worst-case serial budget: commandCount * commandTimeoutMs. */
@@ -344,6 +366,13 @@ export const dagFrontendBrowserToolPreflightSchema = z.object({}).strict();
 export const dagFrontendTestEvidenceValidationSchema = z.object({}).strict();
 export const dagFrontendTestCaseChecklistSchema = z.object({}).strict();
 export const dagFrontendTestHtmlReportSchema = z.object({}).strict();
+export const dagFinalWriteSetApprovalGateSchema = z
+    .object({
+    writerNodeId: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "writerNodeId must be kebab-case"),
+})
+    .strict();
 export const dagMavenWorkspaceManifestSchema = z.object({
     files: z.array(z.object({
         path: z.string(),
@@ -393,6 +422,7 @@ export const dagShellConfigSchema = z.object({
     frontendTestCaseChecklist: dagFrontendTestCaseChecklistSchema.optional(),
     frontendBrowserToolPreflight: dagFrontendBrowserToolPreflightSchema.optional(),
     frontendTestEvidenceValidation: dagFrontendTestEvidenceValidationSchema.optional(),
+    finalWriteSetApprovalGate: dagFinalWriteSetApprovalGateSchema.optional(),
     frontendTestL5Report: z.object({}).strict().optional(),
     frontendTestHtmlReport: dagFrontendTestHtmlReportSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
@@ -541,6 +571,24 @@ export const dagWriterOutcomePolicySchema = z
     requireChangedFiles: z.boolean().optional(),
 })
     .strict();
+/**
+ * The final supervised audit is the sole runtime write authority for its
+ * writer. `allowedPaths` remains a ceiling; it is never a writer fallback.
+ */
+export const dagFinalWriteSetApprovalBindingSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    writerNodeId: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "writerNodeId must be kebab-case"),
+    approvalSourceNodeId: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "approvalSourceNodeId must be kebab-case"),
+    auditedPlanNodeId: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "auditedPlanNodeId must be kebab-case"),
+})
+    .strict();
 export const dagConvergenceSpecSchema = z
     .object({
     enabled: z.boolean().optional().default(false),
@@ -608,6 +656,16 @@ export const dagTaskSchema = z.object({
      * run-attributed diff.
      */
     writerOutcomePolicy: dagWriterOutcomePolicySchema.optional(),
+    /** Required for supervised writers that consume a final audited writeSet. */
+    finalWriteSetApproval: dagFinalWriteSetApprovalBindingSchema.optional(),
+    /** Runtime-only authorization facts injected after final approval validation. */
+    resolvedFinalWriteSetApproval: z
+        .object({
+        approvalDigest: z.string().regex(/^[a-f0-9]{64}$/),
+        approvalSourceNodeId: z.string().min(1),
+    })
+        .strict()
+        .optional(),
     /**
      * Explicit opt-in for the deterministic project governance context resolver
      * (AGENTS.md chain + referenced code standards). Only tasks that set this

package/docs/governance/README.md

@@ -5,7 +5,7 @@
 ## 入口
 
 - [`development-principles.md`](development-principles.md)：工程原则与完成纪律。
-- [`feature-workflow.md`](feature-workflow.md)：会话治理、taskKind、profile 与 Agent DAG 路径。
+- [`feature-workflow.md`](feature-workflow.md)：会话治理、taskKind、profile、Agent DAG 路径，以及 managed contract 的边界更新与恢复语法。
 - [`verification-matrix.md`](verification-matrix.md)：按变更类型选择验证命令。
 - [`harness-methodology-tdd.md`](harness-methodology-tdd.md)：测试先行的方法与边界。
 - [`harness-methodology-verification.md`](harness-methodology-verification.md)：如何用新鲜命令结果支持完成声明。

package/docs/templates/harness.schema.json

@@ -282,8 +282,8 @@
     },
     "executors": {
       "type": "object",
-      "description": "按 executor id 分组的执行器配置。受治理 runtime 仅支持 pi；Cursor 仅通过 cursor-prompt sidecar 使用，不得配置在 executors 中。",
-      "additionalProperties": { "$ref": "#/$defs/executor" },
+      "description": "受治理 runtime 仅支持 pi；Cursor 仅通过 cursor-prompt sidecar 使用，不得配置在 executors 中。",
+      "additionalProperties": false,
       "properties": {
         "pi": { "$ref": "#/$defs/executor" }
       }
@@ -319,13 +319,13 @@
     "executor": {
       "type": "object",
       "additionalProperties": false,
-      "description": "executor 设置。DAG 模型选择优先读取 LOW/MED/HIGH，其次读取 defaultModel，最后回退到 loop-agent runtime 默认矩阵。字面值 default 表示不覆盖。LOW/MED/HIGH 可为字符串或 { model, thinking? } 对象。",
+      "description": "Pi executor 设置。DAG 模型选择优先读取 LOW/MED/HIGH，其次读取 defaultModel，最后回退到 loop-agent runtime 默认矩阵。fresh init 只写 LOW/MED/HIGH；三档有效值齐全时不保留 defaultModel。defaultModel 仅兼容旧项目。字面值 default 表示不覆盖。LOW/MED/HIGH 可为字符串或 { model, thinking? } 对象。",
       "properties": {
         "description": { "type": "string" },
         "enabled": { "type": "boolean" },
         "defaultModel": {
           "type": "string",
-          "description": "executor 默认模型。设置为 default 或省略时，会继续回退到 loop-agent runtime 默认值。",
+          "description": "旧项目兼容默认模型。fresh init 不输出该字段；设置为 default 或省略时，会继续回退到 loop-agent runtime 默认值。",
           "default": "default"
         },
         "LOW": {
@@ -339,10 +339,6 @@
         "HIGH": {
           "$ref": "#/$defs/executorTierModel",
           "description": "HIGH 复杂度 DAG task 的模型覆盖值，优先级高于 defaultModel。可为模型字符串，或 { model, thinking? } 对象。"
-        },
-        "requiresApiKey": {
-          "type": "string",
-          "description": "该 executor 需要的环境变量名，通常用于 Cursor 等可选外部 executor。init update 会剥离过时的 pi.requiresApiKey。"
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.28.7",
+  "version": "0.28.9",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/loop-agent/references/command-reference.md

@@ -128,7 +128,8 @@ SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback
 
 ```bash
 loop-agent init instructions --repo-root <target-repo>
-loop-agent init --repo-root <target-repo> --profile full --merge
+loop-agent init --repo-root <target-repo> --profile full --merge \
+  --provider deepseek --model deepseek/deepseek-v4-flash
 loop-agent init doctor --repo-root <target-repo>
 loop-agent init check-update --repo-root <target-repo> --json
 loop-agent init check-update --repo-root <target-repo> --markdown
@@ -141,9 +142,11 @@ loop-agent init upgrade --repo-root <target-repo> --run-id <run-id> --continue -
 loop-agent init upgrade --repo-root <target-repo> --run-id <run-id> --report --markdown
 ```
 
+fresh init 将精确引用写到 `executors.pi.LOW/MED/HIGH`。fresh `loop-agent init` 会将合格且完整的 `provider/model` 引用投影到 `executors.pi.LOW/MED/HIGH`，即 `executors.pi.LOW`、`executors.pi.MED` 和 `executors.pi.HIGH`。三个 tier 齐全时不会写入 `defaultModel`，也不会恢复或建议旧顶层 routing 字段。
+
 `init check-update` 是只读升级报告，用于发现目标项目是否落后于当前包内初始化 surface。输出会区分 deterministic actions、model merge tasks、human decisions 和 recommended next。`--markdown` 会渲染可直接交给模型执行的合并指引，包含 `allowedPaths`、`forbiddenPaths`、`mergeRules` 和 `verification`。
 
-`init update --bootstrap-surface` 为旧项目写入 `.harness/init-surface.json` 的 `inferred-baseline`，不伪装成历史 recorded baseline。`init update --apply-safe` 只执行确定性安全动作：补缺失文件、创建目录、刷新 managed block；已有但无法确认与当前包一致的文件会进入 model merge tasks，不会被覆盖。
+`init update --bootstrap-surface` 为旧项目写入 `.harness/init-surface.json` 的 `inferred-baseline`，不伪装成历史 recorded baseline。`init update --apply-safe` 只执行确定性安全动作：补缺失文件、创建目录、刷新 managed block；已有但无法确认与当前包一致的文件会进入 model merge tasks，不会被覆盖。模型 merge 只会自动展开不含 tier 或其他旧字段的唯一、完整且可证明等价的旧 `defaultModel: "provider/model"`；顶层 `model`、`models`、`modelProfiles`、`modelRouting`、`verify`、`sequentialWorkflowRole`、部分/对象 tier、bare model、冲突 provider 或未知语义均 fail closed，并保留原始 `harness.json`。
 
 `init upgrade` 是写入型升级入口：首次运行冻结 controller identity、检查 npm latest、扫描 surface、自动执行安全动作，并把 run facts 持久化到 `.harness/init-upgrades/<run-id>/`。`--status` 与 `--report` 严格只读；`--continue` 会重新核验 identity、当前 hash 与不变量。版本选择、无法判定冲突、凭据、破坏性删除或 active writer 才进入 human decision。普通语义冲突返回具体单文件 `allowedPaths` merge task，主会话必须合并后继续，不能把 `needs-model-merge` 作为完成。默认管理项目级 OpenCode/Pi recovery 与 `.pi/settings.json` nested merge，保留显式 disabled，Pi trust 后才加载；默认不读写 `~/.pi/agent/settings.json`。旧 `init reconcile` 保留为兼容低层诊断。
 

package/skills/loop-agent/references/model-routing.md

@@ -4,22 +4,29 @@
 
 ## 模型配置
 
-模型设置来自 repo `harness.json`。历史 `models.<step>` 只作为旧 task metadata 兼容读取；新 DAG work 不从这里路由模型。
+模型设置来自 repo `harness.json.executors.pi.LOW|MED|HIGH`。新 DAG 不读取顶层 `model`、`models`、`modelProfiles`、`modelRouting`、`verify` 或 `sequentialWorkflowRole`；JSON Schema 与 runtime Zod 都拒绝这些字段。
 
-示例模型记录：
+fresh init 的完整三档示例：
 
 ```json
 {
-  "provider": "wizard-local",
-  "model": "gpt-5.3-codex-spark"
+  "executors": {
+    "pi": {
+      "LOW": "wizard-local/gpt-5.3-codex-spark",
+      "MED": "deepseek/deepseek-v4-flash",
+      "HIGH": "provider/high-reasoning-model"
+    }
+  }
 }
 ```
 
+三档齐全时不得保留 `defaultModel`。该字段仅为旧项目的 runtime fallback 兼容保留，不是 fresh-init 输出。旧项目只有不含 tier 或其他旧字段的单一完整 `defaultModel` 可自动展开；对象/部分 tier、旧顶层字段、bare model、冲突或未知 Pi 语义一律保留原始 `harness.json`，进入 model merge/human decision。
+
 Agent DAG node 的模型来自 DAG JSON 中的 `executorModels`，并由 `dag validate --strict-models` 检查 canonical matrix 漂移。若变更模型配置，须同步更新 `harness.json`、相关测试、repo docs 与本 skill。
 
-`executorModels.pi` 的每档值支持两种形式：裸模型名继续走内置映射或默认 `wizard-local`；`provider/model` 限定引用则显式选择 Pi provider，只在第一个 `/` 处分割并保留模型 ID 的剩余部分。provider 定义与凭证仍归 Pi 的 `~/.pi/agent/models.json` 和环境配置所有。例如不同档可分别写 `wizard-local/glm-5.2` 与 `deepseek/deepseek-v4-flash`。
+`executors.pi` 的每档值支持字符串或 `{ model, thinking? }`。CLI 显式配置必须使用 `--model provider/model`，或成对使用 `--provider provider --model model`；空值、仅 provider、裸 `--model` 与冲突的重复 provider 限定会被拒绝。`provider/model` 只在第一个 `/` 处分割并保留模型 ID 的剩余部分。provider 定义与凭证仍归 Pi 的 `~/.pi/agent/models.json` 和环境配置所有。
 
-`pi-prompt` 是独立 one-shot helper，不使用 `harness.json.models` 或 DAG `executorModels`。当前默认是 `wizard-local/glm-5.2`；高复杂度 one-shot 显式传 `--model gpt-5.5`。Agent DAG `pi` executor 的 canonical matrix 保持；读写 profile 共用同一矩阵：
+`pi-prompt` 是独立 one-shot helper，不使用 harness Pi tier matrix 或 DAG `executorModels`。当前默认是 `wizard-local/glm-5.2`；高复杂度 one-shot 显式传 `--model gpt-5.5`。Agent DAG `pi` executor 的 canonical matrix 保持；运行时优先级仍为 `LOW|MED|HIGH → defaultModel → DEFAULT_DAG_EXECUTOR_MODELS`：
 
 ```json
 {
@@ -33,6 +40,6 @@ Agent DAG node 的模型来自 DAG JSON 中的 `executorModels`，并由 `dag va
 ```bash
 loop-agent inspect
 ```
-并在输出中核对 `models` 与 Agent DAG 文档中的 `executorModels` 约定。
+并在输出中核对 `executors.pi.LOW/MED/HIGH` 与 Agent DAG 文档中的 `executorModels` 约定。
 
 Pi SDK runtime reuse 仍为 **default-off**（`CODE_AGENT_PI_REUSE_RUNTIME` 未设/`off`/未知）。opt-in 须显式 `auto-run`；`CODE_AGENT_PI_BACKEND=cli-only` 绕过 reuse。无 live call 的确定性 M2/M3 decision 摘要用 `pi-reuse-benchmark`（见 `command-reference.md`）。