@zmzai/agent-framework 0.5.2 → 0.9.0

package/dist/core/runtime/runner.js

@@ -1,5 +1,5 @@
 import { Agent } from "@earendil-works/pi-agent-core";
-import { validateAttachments, attachmentContent } from "./attachments.js";
+import { validateAttachments, validateAttachmentRefs, attachmentContent, attachmentRefContent, } from "./attachments.js";
 import { leaseDurationMs } from "../../adapters/index.js";
 import { notifyEventLogListeners } from "../events/bus.js";
 import { PermissionEngine, RejectedError } from "../permission/engine.js";
@@ -10,10 +10,17 @@ import { newPartId, newSessionId } from "../session/ids.js";
 import { adaptAnyTool, permissionForCall } from "../tools/adapter.js";
 import { builtinTools } from "../tools/builtins.js";
 import { isExternalToolDef } from "../tools/def.js";
+import { TASK_BLOCK_TOOL_ID, readTaskBlock } from "../tools/task-block.js";
+import { TASK_DELIVER_TOOL_ID, readTaskDelivery } from "../tools/task-deliver.js";
 import { fireRunStart, firstToolBlock, fireAfterToolCall, fireRunEnd } from "./lifecycle.js";
 import { extractRunTranscript, RETRY_PLACEHOLDER_TEXT } from "./run-transcript.js";
 import { noopSandboxExecutor } from "../../adapters/index.js";
 import { randomUUID } from "node:crypto";
+import { DEFAULT_MAX_ATTEMPTS, durationBudgetBlocker, evaluateTaskCompletion, lifecycleForBlocker, normalizeMaxDurationMs, } from "../task/completion.js";
+import { advanceProgress } from "../task/progress.js";
+import { appendEvidence, applyDelivery, evidenceKindForTool, projectTodos, pruneEvidenceRefs, } from "../task/plan.js";
+import { fallbackResult, renderResult, taskContractText } from "../task/contract.js";
+import { isTerminalStatus, isWaitingStatus } from "../task/types.js";
 /** 事件的 sessionId 提取：能自带的自带（message/part/session），其余
  *  （message.part.delta 等）用发起 run 的会话 id 兜底。 */
 function sessionIdOf(event, fallbackSessionId) {
@@ -86,6 +93,27 @@ function defaultToolContext(input) {
         },
     };
 }
+/** 用户明确放行时重置的三个保护计数（新消息恢复、以及 `resumeTask`）。
+ *
+ *  【为什么必须重置】不重置的话「继续」是个死按钮：因为 no_progress 停下来的任务
+ *  计数仍是 3，下一次判定立刻再停；因为轮数预算停下来的任务第 N+1 轮开头就超过
+ *  上限，一步都不会跑；时间预算同理——已经烧满一小时的 `activeMs` 会让放行后的
+ *  第一轮连起点都过不去。用户点「继续」就是明确授权再做一些，那一刻起保护阈值
+ *  应当重新计时——由人来决定要不要继续，正是这类保护的设计前提（规格 §10.1 的
+ *  三档策略本来就以「用户可以再来一轮」为前提）。
+ *
+ *  这不会让任务无限跑：每一次重置都需要一次显式的人工动作，不存在自触发路径。 */
+const RESET_GUARDS_ON_RESUME = { noProgressCount: 0, attemptCount: 0, activeMs: 0 };
+/** 人工放行时喂给模型的驱动文本（与 `continuation` 那条同源但不同话术）。
+ *
+ *  它同样**不落库**：`resumeTask` 不经过 `prompt()`，没有 message、没有 workflow
+ *  receipt，`acceptedUserId` 为 undefined——但这里必须显式跳过投影，因为
+ *  `acceptedUserId` 为空正是「投影一条用户消息」的默认路径（见 runLoop）。
+ *  用一个专门的标记区分，才不会把「继续」画成用户说过的话。 */
+const RESUME_DRIVE_TEXT = "[继续执行任务] 用户已经核对过当前状态并授权继续。按上面的任务契约接着推进，不要从头再做一遍，也不要把控制权提前交回用户。";
+/** 单次任务 Attempt 数的硬上限（规格 §10.1 的要求：宿主调不到「永不拦截」）。
+ *  64 轮远超任何正常任务，同时挡住 `maxAttempts: 1e9` 这种把保护关掉的写法。 */
+const MAX_ATTEMPT_CEILING = 64;
 export class SessionRunner {
     deps;
     constructor(deps) {
@@ -93,35 +121,64 @@ export class SessionRunner {
     }
     draining = new Map();
     stopRequested = new Set();
+    /** 已被用户放行、等待驱动链接手推进的会话（见 `drain` 的第三条分支）。 */
+    resumeRequests = new Set();
     drain(sessionId) {
         if (this.draining.has(sessionId))
             return;
         const work = (async () => {
             while (true) {
                 const job = await this.deps.store.workflow.claimPrompt(sessionId, `node:${process.pid}`);
-                if (!job)
-                    return;
-                let outcome = "recovery_required";
-                try {
-                    if (this.stopRequested.has(sessionId)) {
-                        outcome = "cancelled";
-                    }
-                    else {
-                        const session = await this.deps.store.getSession(sessionId);
-                        if (!session) {
-                            outcome = "failed";
+                if (job) {
+                    let outcome = "recovery_required";
+                    try {
+                        if (this.stopRequested.has(sessionId)) {
+                            outcome = "cancelled";
                         }
                         else {
-                            outcome = await this.runLoop(session, job.input, job.receipt.userMessageId);
+                            const session = await this.deps.store.getSession(sessionId);
+                            if (!session) {
+                                outcome = "failed";
+                            }
+                            else {
+                                // 走任务层：一次 claim 之后可能跑多轮 Attempt（规格 §8.2）
+                                outcome = await this.runTask(session, job.input, job.receipt.userMessageId);
+                            }
                         }
                     }
+                    catch {
+                        // Setup or settlement may have failed after a tool ran. Do not replay.
+                    }
+                    try {
+                        await this.deps.store.workflow.finishPrompt(sessionId, job.receipt.runId, job.revision, outcome);
+                    }
+                    catch (error) {
+                        // revision 是这次 run 的所有权凭据。冲突说明这次 run 的归属已经在
+                        // 别处被改写过——最典型的就是进程崩溃后恢复扫描把它标成
+                        // `recovery_required`，而这一轮结算才姗姗来迟。那时这条结论不该由
+                        // 我们写（恢复扫描已经给出了它的判断），静默退出即可。把冲突往上抛
+                        // 只会炸掉 `abort()`——它正 await 着这条驱动链。
+                        if (!/RUN_REVISION_CONFLICT/.test(String(error?.message ?? "")))
+                            throw error;
+                        return;
+                    }
+                    if (outcome !== "completed")
+                        return;
+                    continue;
                 }
-                catch {
-                    // Setup or settlement may have failed after a tool ran. Do not replay.
-                }
-                await this.deps.store.workflow.finishPrompt(sessionId, job.receipt.runId, job.revision, outcome);
-                if (outcome !== "completed")
+                // 队列里没有 run 了。还有第三种可能要推进：**用户刚按了「继续」**。
+                // 这类任务停下的原因是预算/无进展/等待，而不是「排队等认领」——它那次
+                // 的 workflow run 早已 `completed`，`claimPrompt` 永远取不到它。没有这条
+                // 分支，`resumeTask` 把任务放回 queued 之后就再没有东西会碰它，
+                // 每个 blocker 里写的那句「确认后可以继续」就是一句系统接不住的承诺。
+                if (!this.resumeRequests.delete(sessionId))
                     return;
+                if (this.stopRequested.has(sessionId))
+                    return;
+                const resumed = await this.deps.store.getSession(sessionId);
+                if (!resumed)
+                    return;
+                await this.driveResumedTask(resumed);
             }
         })();
         this.draining.set(sessionId, work);
@@ -129,11 +186,40 @@ export class SessionRunner {
             this.draining.delete(sessionId);
             if (this.stopRequested.has(sessionId))
                 return;
+            // 有放行请求就在原地接着驱动。必须在这里再查一次：`resumeTask` 是在
+            // `draining.delete` 之前判断「有没有人在跑」的，上面那个 while 也可能
+            // 刚刚判定退出——两件事都发生在微任务队列里，中间只差一次 await。
+            // 少了这一查，一次恰好落在收尾窗口里的「继续」会被静默丢掉。
+            if (this.resumeRequests.has(sessionId)) {
+                this.drain(sessionId);
+                return;
+            }
             const queued = await this.deps.store.workflow.workflowRuns(sessionId).catch(() => []);
             if (queued.some(run => run.status === "queued") && !queued.some(run => run.status === "running" || run.status === "recovery_required"))
                 this.drain(sessionId);
         });
     }
+    /** 推进一个「用户已放行」的任务（规格 §11.2 / §13.2）。
+     *
+     *  不创建用户消息、不新建 workflow run：`resumeTask` 走的是 `runTask` 的直接
+     *  入口，绕过 `prompt()` 的整个提交链（投影消息 → resolveTaskForPrompt →
+     *  acceptPrompt）。这条路径上没有任何东西会落成「用户说过的话」——
+     *  `resume: true` 让 runLoop 连那条投影都跳过。
+     *
+     *  任务不处于「可推进」状态时什么都不做：用户可能连点两次，或者第二个请求
+     *  到达时第一轮已经把它跑完了。 */
+    async driveResumedTask(session) {
+        const store = this.deps.store.task;
+        if (!store)
+            return;
+        const task = await store.getActiveTask(session.id);
+        if (!task || isTerminalStatus(task.status) || isWaitingStatus(task.status))
+            return;
+        await this.runTask(session, 
+        // text 留空：放行话术由 runLoop 按 `resume` 补充。这里塞文本会顺着
+        // `fireRunStart` 的 text 流进宿主的标题生成，把会话标题写成一句系统指令。
+        { requestId: task.rootRequestId, text: "", taskId: task.id, model: session.model, resume: true }, undefined);
+    }
     #hooks = [];
     /** 供 runLoop 取归一化钩子数组（lazy：constructor 后仍可由 deps 引用共享）。 */
     get hooks() {
@@ -184,8 +270,76 @@ export class SessionRunner {
             return;
         await this.deps.leaseStore.clear(sessionId).catch(() => undefined);
     }
+    /** 为一条新消息决定它归属哪个任务，以及这次提交的处置（规格 §12 / §13.1）。
+     *
+     *  四种处置的判定依据是**任务当前状态**，不是模型对文本的猜测：
+     *  - 无活跃任务 → 开新任务；
+     *  - 任务在 waiting_permission / waiting_input / waiting_external / blocked
+     *    → 这条消息就是那个「用户动作」，任务恢复；
+     *  - 任务在 running → 这条消息是补充/纠正，并入约束。
+     *
+     *  【为什么不做「这是不是无关新目标」的语义分类】那需要模型判断，代价是一次
+     *  额外的往返，而且判错的后果不对称：把无关目标误并进当前任务，用户会看到
+     *  自己的话被当成补充说明；反过来把补充说明误判成新任务，则会产生两个抢同一
+     *  个工作区的任务（规格 §18.9 禁止的情况）。所以默认并入，并由约束文本明确
+     *  标注「这是用户在你执行期间补充的」，让模型自己决定是否改变方向。 */
+    async resolveTaskForPrompt(session, input, userMessageId) {
+        const store = this.deps.store.task;
+        if (!store)
+            return null;
+        const requestId = input.requestId;
+        // 幂等：同一 requestId 重复提交返回同一任务，不创建第二个（§13.1 / §17.1.11）
+        // 重放时 disposition 描述的是「这条消息与任务的关系」，那是稳定的：
+        // 一条消息一旦开启过某个任务，它永远是那个任务的开启者。
+        const prior = await store.findTaskByRequestId(session.id, requestId);
+        if (prior)
+            return { task: prior, disposition: "task_started", startedTask: false, previous: null };
+        const active = await store.getActiveTask(session.id);
+        if (active) {
+            const resuming = isWaitingStatus(active.status);
+            const text = input.text.trim();
+            const constraints = text ? [...active.constraints, text].slice(-8) : active.constraints;
+            const task = await this.casTask(active, {
+                constraints,
+                // 恢复：把任务放回可被认领的状态，drain 会接着推进它
+                ...(resuming ? { status: "queued" } : {}),
+                ...(resuming ? { blocker: undefined } : {}),
+                ...(resuming ? RESET_GUARDS_ON_RESUME : {}),
+            });
+            return { task, disposition: resuming ? "task_resumed" : "task_steered", startedTask: false, previous: active };
+        }
+        const goal = input.text.trim().slice(0, 500) || "（未命名任务）";
+        const task = await store.createTask({
+            sessionId: session.id,
+            rootRequestId: requestId,
+            rootUserMessageId: userMessageId,
+            goal,
+        });
+        return { task, disposition: "task_started", startedTask: true, previous: null };
+    }
+    /** 提交被拒时把任务改回这一步之前的样子（见 `prompt` 里的调用点）。
+     *
+     *  新建的任务**不回滚**：它是这个 requestId 的幂等锚点，删掉会让「同一 requestId
+     *  重试」失去依据。留着它没有代价——下一次同 requestId 的提交会命中
+     *  `findTaskByRequestId` 拿回同一个任务，别的消息则会被 `getActiveTask` 收编成
+     *  steering。 */
+    async rollbackTaskResolution(resolution) {
+        if (!resolution?.previous)
+            return;
+        const { previous, task } = resolution;
+        await this.casTask(task, {
+            status: previous.status,
+            constraints: previous.constraints,
+            // 计数也要一起还原：恢复路径把它们清零了，而这次提交并没有发生。
+            noProgressCount: previous.noProgressCount,
+            attemptCount: previous.attemptCount,
+            activeMs: previous.activeMs ?? 0,
+            // 显式区分「清空 blocker」与「保持原样」：undefined 是清除指令
+            ...(previous.blocker ? { blocker: previous.blocker } : { blocker: undefined }),
+        }).catch(() => undefined);
+    }
     async prompt(sessionId, input) {
-        input = { ...input, attachments: validateAttachments(input.attachments) };
+        input = { ...input, attachments: validateAttachments(input.attachments), attachmentRefs: validateAttachmentRefs(input.attachmentRefs) };
         const session = await this.deps.store.getSession(sessionId);
         if (!session)
             throw new Error("SESSION_NOT_FOUND");
@@ -196,18 +350,43 @@ export class SessionRunner {
             const message = projector.onUserPrompt(event => {
                 if (event.type === "message.part.updated")
                     parts.push(event.data.part);
-            }, input.text, input.images, input.skill, input.references, input.attachments);
-            const accepted = await this.deps.store.workflow.acceptPrompt(sessionId, input, { message, parts });
+            }, input.text, input.images, input.skill, input.references, input.attachments, input.attachmentRefs);
+            // 先建消息再建任务：TaskRecord.rootUserMessageId 需要真实的消息 id，
+            // 事后回填会多一次 CAS，也让「任务与首条消息同生」这条不变量出现空窗。
+            const resolution = await this.resolveTaskForPrompt(session, input, message.id);
+            if (resolution)
+                input = { ...input, taskId: resolution.task.id };
+            let accepted;
+            try {
+                accepted = await this.deps.store.workflow.acceptPrompt(sessionId, input, { message, parts });
+            }
+            catch (error) {
+                // 提交被拒（最常见的是 RECOVERY_REQUIRED）。必须把任务改回原样：
+                // resolveTaskForPrompt 可能已经清掉 blocker、把状态放回 queued，而这次
+                // prompt 根本没被接受——没被接受就没有任何 run 会去推进它，任务会停在
+                // queued 上永远等不到，而用户看到的只是一个 409。
+                await this.rollbackTaskResolution(resolution);
+                throw error;
+            }
             for (const event of accepted.events)
                 notifyEventLogListeners(event);
+            if (resolution?.startedTask) {
+                const task = resolution.task;
+                await this.publish({ type: "task.started", data: { taskId: task.id, revision: task.revision, goal: task.goal, steps: [], acceptanceCriteria: task.acceptanceCriteria.map((criterion) => ({ id: criterion.id, description: criterion.description, required: criterion.required, status: criterion.status })) } }, sessionId);
+            }
             if (accepted.events.length)
                 this.drain(sessionId);
-            return accepted.receipt;
+            return {
+                ...accepted.receipt,
+                ...(resolution ? { disposition: resolution.disposition, taskId: resolution.task.id } : {}),
+            };
         }
         if (activeRuns.has(sessionId)) {
             await this.deps.store.enqueuePrompt(sessionId, {
                 text: input.text,
                 attachments: input.attachments,
+                // 排队消息必须记住附件引用：真正执行时要按 id 重新确认附件仍存在且可读（规格 2 §11）
+                ...(input.attachmentRefs?.length ? { attachmentRefs: [...input.attachmentRefs] } : {}),
                 images: input.images,
                 model: input.model,
                 ...(input.agent ? { agent: input.agent } : {}),
@@ -227,6 +406,39 @@ export class SessionRunner {
             return false;
         return active.engine.reply(requestId, reply, feedback);
     }
+    /** 用户核对完之后让任务继续（规格 3 §11 / §13.2 的 `resume` 动作）。
+     *
+     *  【为什么必须有这条通路】每个 blocked / waiting 的 blocker 都写着一句
+     *  `requiredAction`（「先核对工作区与外部系统的实际状态，再决定继续或重做」）。
+     *  如果产品只能靠「再发一条消息」来继续，那句话就是在要求用户做一件系统接不住
+     *  的事；而更糟的是崩溃恢复后的那种任务——会话里还有一条 `recovery_required`
+     *  的 run，发消息会被 409 挡住，用户根本无路可走。
+     *
+     *  三步：放掉「副作用未确认」这道闸 → 任务回到 queued 并清 blocker →
+     *  登记一次放行请求，交给驱动链（`drain`）推进。
+     *  **不创建用户消息**（§11.2）：这是同一条指令的继续，不是新的一轮对话。
+     *  返回 false 表示没什么可继续的（没有活跃任务、已终态、或本来就在正常跑，
+     *  规格 §13.2：正常运行中的 task 不需要「继续」）。
+     *
+     *  【为什么不能靠 `drain` 自己发现这件事】`drain` 认领的是队列里的 workflow
+     *  run，而这类任务停下的原因是预算/无进展/等待，它那次 run 早就 `completed`
+     *  了——`claimPrompt` 取不到任何东西，任务会被放回 queued 而无人推进。所以
+     *  放行动作必须留下一个显式标记（`resumeRequests`），由驱动链认领。 */
+    async resumeTask(sessionId) {
+        const store = this.deps.store.task;
+        if (!store)
+            return false;
+        const task = await store.getActiveTask(sessionId);
+        if (!task || !isWaitingStatus(task.status))
+            return false;
+        // 闸先放：否则驱动链里的 claimPrompt 仍会因为 recovery_required 返回 null，
+        // 任务会被放回 queued 却没有任何东西去推进它。
+        await this.deps.store.workflow?.clearRecoveryRequired(sessionId).catch(() => 0);
+        await this.casTask(task, { status: "queued", blocker: undefined, ...RESET_GUARDS_ON_RESUME });
+        this.resumeRequests.add(sessionId);
+        this.drain(sessionId);
+        return true;
+    }
     /** Revokes matching session-scoped rules immediately for a live run and
      * removes their persisted continuation access. */
     async revokePermission(sessionId, permission, patterns) {
@@ -254,8 +466,31 @@ export class SessionRunner {
             await active.done;
         }
         await this.draining.get(sessionId);
+        await this.cancelResidualTask(sessionId);
+        // 停止会作废还没被认领的放行请求：留着它，驱动链下一次启动就会去推进一个
+        // 用户已经改主意（点了停止）的任务。
+        this.resumeRequests.delete(sessionId);
         this.stopRequested.delete(sessionId);
     }
+    /** 停止时把任务层也收干净（规格 3 §11「用户停止任务」）。
+     *
+     *  正在跑的 run 不用管：`RunOutcome.aborted` 会让 Completion Gate 判 `cancelled`，
+     *  任务由 `settleTask` 落终态。这里处理的是**没有活 run 却仍停在非终态**的任务——
+     *  上一步已经 `blocked` / `waiting_*`、用户此时点「停止」，没有任何运行在跑；
+     *  不补这一刀，任务会永远停在等待里，而界面上的「停止」看起来毫无作用。
+     *
+     *  位置刻意放在 `draining` 之后：先让结算路径写完自己的结论，避免两边各发一次
+     *  `task.cancelled`（revision 白跳两次，客户端投影也会收到重复终态）。 */
+    async cancelResidualTask(sessionId) {
+        const store = this.deps.store.task;
+        if (!store)
+            return;
+        const task = await store.getActiveTask(sessionId);
+        if (!task || isTerminalStatus(task.status))
+            return;
+        const updated = await this.casTask(task, { status: "cancelled", blocker: undefined });
+        await this.publish({ type: "task.cancelled", data: { taskId: updated.id, revision: updated.revision, reason: "用户已停止任务。" } }, sessionId);
+    }
     /** 手动触发一次上下文压缩（UI「压缩当前会话」）：无条件对当前历史跑一次
      *  摘要折叠，摘要通过 buildCompaction 的 onCompacted 落为 compaction part
      *  并发事件。与自动 compaction 共用同一套保护（膨胀拒绝/失败降级）。 */
@@ -355,7 +590,14 @@ export class SessionRunner {
             return null;
         }
     }
-    async runLoop(session, input, acceptedUserId) {
+    /** 一次 Attempt：从模型上下文构造到终态收尾的完整内部运行。
+     *
+     *  `taskContext` 存在时，任务契约会注入 systemPrompt（**不落成消息**，
+     *  规格 §19 禁止伪用户消息）。它同时携带 continuation 的 advisory，
+     *  保证「续跑指令」与「任务契约」在同一条系统指令里，不会互相矛盾。
+     *  它还携带 `loopGuard`：任务层自己持有一个跨 Attempt 的实例，避免每轮
+     *  重置循环防护的计数（见下方注释）。 */
+    async runLoop(session, input, acceptedUserId, taskContext) {
         const registry = await this.registryFor(session);
         const resolved = await this.resolvedAgentFor(session);
         const agentName = resolved ? resolved.agent.name : input.agent ?? session.agent;
@@ -373,14 +615,24 @@ export class SessionRunner {
             session = { ...session, model };
         }
         const agentRulesets = resolved ? [registry.rulesetsFor("default")[0], resolved.agent.permission] : registry.rulesetsFor(agentInfo?.name ?? "default");
+        /** 本轮模型最后投递的 todo 列表（步骤投影的输入）。 */
+        let latestTodos = null;
         const engine = new PermissionEngine(session.id, agentRulesets, session.permission, {
             onAsked: async (request) => {
                 await this.publish({ type: "session.status", data: { status: "waiting_permission" } }, session.id);
                 await this.publish({ type: "permission.asked", data: { request } }, session.id);
+                // 权限等待必须让任务层可见（规格 §11.1）。否则用户在盯着授权卡的时候，
+                // 任务状态还是「运行中」——「在跑」和「在等你点授权」对用户是两件事，
+                // 而任务 API 会给出一个错的答案。
+                await this.markPermissionWait(taskContext?.task.id, request.permission, request.patterns, true);
             },
             onReplied: async (request, reply) => {
                 await this.publish({ type: "permission.replied", data: { id: request.id, reply } }, session.id);
                 await this.publish({ type: "session.status", data: { status: "running" } }, session.id);
+                // 授权通过或拒绝都解除等待：规格 §11.3 要求把拒绝结果交回模型去试替代
+                // 方案，只有模型也没有替代方案时才判 blocked/failed。留在
+                // waiting_permission 会把「已经拒绝了」误报成「还在等你授权」。
+                await this.markPermissionWait(taskContext?.task.id, request.permission, request.patterns, false);
             },
             onSessionRuleAdded: async (sessionId, rule) => {
                 const latest = await this.deps.store.getSession(sessionId);
@@ -392,7 +644,21 @@ export class SessionRunner {
                 await this.deps.store.updateSession(sessionId, { permission: [...latest.permission, { ...rule, ...(expiresAt ? { expiresAt } : {}) }] });
             },
         });
+        /** 本轮事件的公共漏斗——**模型流通路和工具通路都必须经过它**。
+         *
+         *  【为什么必须是一个共享函数】曾经把 todo 捕获写在下面 `serializeEmit` 的
+         *  包装器里，注释还写着「事件流是所有路径的漏斗，不会漏」。那是错的：默认
+         *  tool context 的 `setTodos` 拿到的 emit 直接调 `publish`，根本不经过包装器。
+         *  结果是 `latestTodos` 永远是 null，步骤数组永远为空，任务于是按「没有步骤」
+         *  的分支判定——模型刚说完一句试点性的开场白就被判成「已交付」。这类 bug
+         *  的危险之处在于它不报错，只是悄悄把完成判定放宽到形同虚设。 */
+        const observeRunEvent = async (event) => {
+            if (event.type === "todo.updated") {
+                latestTodos = event.data.todos.map((todo) => ({ content: todo.content, status: todo.status }));
+            }
+        };
         const { emit, settled } = serializeEmit(async (event) => {
+            await observeRunEvent(event);
             await this.persist(event, session.id);
         });
         const projector = new PartProjector({ sessionId: session.id, agent: agentInfo?.name ?? "default", model });
@@ -415,6 +681,7 @@ export class SessionRunner {
         const rawWorkspace = this.deps.workspaceFor(session);
         const workspace = session.writePaths?.length ? confineWorkspaceFiles(rawWorkspace, session.writePaths) : rawWorkspace;
         const emitAsync = async (event) => {
+            await observeRunEvent(event);
             await this.publish(event, session.id);
         };
         const toolContext = (this.deps.buildToolContext ?? defaultToolContext)({ session, engine, workspace, sandbox, emit: emitAsync });
@@ -425,6 +692,24 @@ export class SessionRunner {
         }
         const piTools = [...toolDefs.values()].map((def) => adaptAnyTool(def, toolContext));
         let unknownSideEffect = false;
+        let sideEffectDetail = null;
+        /** 以 error 结束的工具调用摘要（最多留最近三条）。
+         *  只用于续跑提示，**不构成阻塞**——工具失败后模型换条路走通是常态。 */
+        const toolErrors = [];
+        /** 本轮**自己的**最后一条 assistant 文本（交付文本的来源）。
+         *
+         *  【为什么不用「会话里最后一条」】续跑时那会取到上一轮的文本：一轮「我先看看
+         *  文件」之后，下一轮只用工具调完了全部步骤，交付卡上就会出现一句跟本次交付
+         *  无关、甚至自相矛盾的正文。连带 `finalTextPresent` 也会用陈旧文本为一次
+         *  没说话的运行开绿灯。这里只认本轮新增的消息。 */
+        let attemptFinalText = "";
+        /** 本轮的证据候选。在工具热路径上只累积内存，Attempt 结束时一次性投影进
+         *  任务并落库——否则每次工具调用都要 CAS 写一次任务表。 */
+        const evidenceCandidates = [];
+        /** 本轮模型用 `task_block` 声明的阻塞（规格 3 §11）。见 `RunOutcome.taskBlock`。 */
+        let taskBlock = null;
+        /** 本轮模型用 `task_deliver` 提交的交付声明（规格 3 §9 条件 6）。见 `RunOutcome.delivery`。 */
+        let delivery = null;
         const compactionTransform = await this.buildCompaction(session, emit);
         // 记忆召回（spec §记忆）：单点注入 runLoop，天然覆盖正常 prompt/排队出
         // 队/automation/子代理触发四条路径。只进内存不落 store；抛错静默降级。
@@ -448,7 +733,14 @@ export class SessionRunner {
         const baseline = history.length;
         const agent = new Agent({
             initialState: {
-                systemPrompt: [agentInfo?.prompt ?? "", mandatorySkillContext, input.references?.length ? `<attached-resources>\nThe user attached these workspace paths. Read the relevant ones before acting:\n${input.references.join("\n")}\n</attached-resources>` : ""].filter(Boolean).join("\n\n"),
+                systemPrompt: [
+                    agentInfo?.prompt ?? "",
+                    mandatorySkillContext,
+                    // 任务契约（规格 3 §6 / §8.2）：每个 Attempt 重新注入一次，因此
+                    // 上下文被压缩掉也不影响任务目标的存续。续跑指令与它同源。
+                    taskContext ? taskContractText(taskContext.task, taskContext.advisory) : "",
+                    input.references?.length ? `<attached-resources>\nThe user attached these workspace paths. Read the relevant ones before acting:\n${input.references.join("\n")}\n</attached-resources>` : "",
+                ].filter(Boolean).join("\n\n"),
                 model: this.deps.modelFor(model),
                 // 推理力度（P1-8 复活）：relay 现已按模型白名单接受 reasoning_effort；
                 // 仅当调用方显式选择且非 off 时下发（默认不设 = 完全不带该字段）。
@@ -472,7 +764,11 @@ export class SessionRunner {
         if (this.stopRequested.has(session.id))
             abort();
         await this.stampLease(session.id);
-        const loopGuard = new LoopGuard();
+        // 循环防护在任务层跨 Attempt 复用（规格 3 §16 阶段 D）：一条任务会自己续跑
+        // 多轮，而「同一个工具一直以同样的方式失败」是不会因为换了一轮就消失的事实。
+        // 每轮新建一个 guard，会让上一轮的两次失败在这一轮从未发生，模型于是有机会
+        // 把同一个错误再撞一遍——续跑越多，这个洞越大。
+        const loopGuard = taskContext?.loopGuard ?? new LoopGuard();
         agent.beforeToolCall = async ({ toolCall, args }) => {
             if (unknownSideEffect) {
                 return { block: true, reason: "上一个可能产生副作用的动作结果不确定，已暂停执行。请先确认外部系统状态，再决定继续或重试。", terminate: true };
@@ -535,12 +831,44 @@ export class SessionRunner {
         // 只碰工具结果，不碰 F6 模型级重试路径。
         agent.afterToolCall = async ({ toolCall, args, result, isError }) => {
             const details = typeof result.details === "object" && result.details !== null ? result.details : null;
-            if (details?.outcome === "unknown")
+            if (details?.outcome === "unknown") {
                 unknownSideEffect = true;
+                sideEffectDetail ??= `${toolCall.name} 的结果不确定`;
+            }
             const resultText = (result.content ?? [])
                 .filter((block) => block.type === "text")
                 .map((block) => block.text)
                 .join("\n");
+            // 证据采集（规格 3 §9 条件 3）：只记**成功**的写 / 执行 / 外部核对类调用。
+            // 失败不是验证证据；读取类工具也不记（见 evidenceKindForTool 的说明）——
+            // 否则「有证据」会退化成「调过工具」。
+            if (isError) {
+                toolErrors.push(`${toolCall.name}: ${resultText.trim().slice(0, 160)}`);
+                if (toolErrors.length > 3)
+                    toolErrors.shift();
+            }
+            else {
+                // 模型声明「需要用户介入」（规格 §11）。只认成功的调用：一次被拒绝或
+                // 崩溃的 task_block 没有资格把任务停下来等用户。
+                if (toolCall.name === TASK_BLOCK_TOOL_ID)
+                    taskBlock = readTaskBlock(args);
+                // 模型声明「我交付了」（规格 §9 条件 6）。同样只认成功的调用——参数过不了
+                // schema 的交付声明必须当成「没有声明」，否则一次格式错误就能换来 delivered。
+                if (toolCall.name === TASK_DELIVER_TOOL_ID)
+                    delivery = readTaskDelivery(args);
+                const kind = evidenceKindForTool(toolCall.name);
+                if (kind) {
+                    const path = args?.path;
+                    const program = args?.program;
+                    const ref = typeof path === "string" ? path : typeof program === "string" ? program : undefined;
+                    const title = typeof details?.title === "string" ? details.title : undefined;
+                    evidenceCandidates.push({
+                        kind,
+                        summary: (title ?? resultText).trim().slice(0, 160) || toolCall.name,
+                        ...(ref ? { ref } : {}),
+                    });
+                }
+            }
             let advisory = loopGuard.onToolResult({ toolName: toolCall.name, isError, errorText: resultText });
             // 生命周期钩子（P0）：只读观测，不阻塞结果路径
             void Promise.all(fireAfterToolCall(this.hooks, {
@@ -631,6 +959,9 @@ export class SessionRunner {
             abortController.abort();
         }, 15_000);
         let runErrored = false;
+        /** 本轮失败的错误消息。用来区分「上游抖动（可重试）」与「确定没救」——
+         *  两者在 Completion Gate 里走完全不同的分支（续跑 vs failed）。 */
+        let runErrorMessage = null;
         const runStartedAt = Date.now();
         // N6 长任务中途 checkpoint：运行超过阈值后周期性发布进度快照（已执行工具数 /
         // 最后一步工具 / 耗时），崩溃/中断后前端据此提示「上次进行到哪」。终态收尾仍
@@ -654,13 +985,26 @@ export class SessionRunner {
             await this.publish({ type: "session.status", data: { status: "running" } }, session.id);
             if (abortController.signal.aborted)
                 throw new Error("Run cancelled during setup");
-            if (!acceptedUserId)
-                projector.onUserPrompt(emit, input.text, input.images, input.skill, input.references, input.attachments);
+            // `resume` 与 `acceptedUserId` 都表示「这一轮没有一个用户回合」：前者是用户
+            // 按了按钮，后者是任务自己接着跑。两条路径都不能投影用户消息（规格 §18.2）。
+            if (!acceptedUserId && !input.resume)
+                projector.onUserPrompt(emit, input.text, input.images, input.skill, input.references, input.attachments, input.attachmentRefs);
             const piImages = input.images?.map((img) => {
                 const match = img.url.match(/^data:([^;]+);base64,(.+)$/);
                 return match ? { type: "image", data: match[2], mimeType: match[1] } : null;
             }).filter((img) => img !== null);
-            await agent.prompt({ role: "user", content: [{ type: "text", text: input.text }, ...attachmentContent(input.attachments ?? []), ...(piImages ?? [])], timestamp: Date.now() });
+            const attachmentParts = await attachmentRefContent(this.deps.attachments, input.attachmentRefs ?? [], { sessionId: session.id });
+            // 内部续跑喂给模型的驱动文本（规格 3 §8.2）。它**不落库**：上面那条
+            // `if (!acceptedUserId) projector.onUserPrompt(...)` 已经跳过，所以聊天
+            // 记录里看不到它（§18.2 验收要求「没有合成用户消息」）。但驱动模型本身
+            // 必须有个输入——规格 §19 禁止的是把「继续」做成一条**持久化的伪用户
+            // 消息**，不是禁止给模型一个继续的由头。
+            const driveText = input.resume
+                ? RESUME_DRIVE_TEXT
+                : taskContext?.continuation
+                    ? "[继续执行任务] 上一轮结束时任务还没有完成。按上面的任务契约继续推进，不要中途把控制权交回用户。"
+                    : input.text;
+            await agent.prompt({ role: "user", content: [{ type: "text", text: driveText }, ...attachmentContent(input.attachments ?? []), ...attachmentParts, ...(piImages ?? [])], timestamp: Date.now() });
             await settled();
             let failed = agent.state.errorMessage;
             if (unknownSideEffect) {
@@ -696,6 +1040,7 @@ export class SessionRunner {
                 }
                 if (failed) {
                     runErrored = true;
+                    runErrorMessage = failed;
                     await this.publish({ type: "session.error", data: { name: "APIError", message: failed } }, session.id);
                 }
                 await this.publish({ type: "session.status", data: { status: "idle" } }, session.id);
@@ -704,8 +1049,10 @@ export class SessionRunner {
         catch (error) {
             await settled();
             const aborted = abortController.signal.aborted;
-            if (!aborted && !unknownSideEffect)
+            if (!aborted && !unknownSideEffect) {
                 runErrored = true;
+                runErrorMessage = error instanceof Error ? error.message : "Agent 运行失败";
+            }
             await this.publish(unknownSideEffect
                 ? { type: "session.status", data: { status: "waiting_input" } }
                 : aborted
@@ -723,6 +1070,7 @@ export class SessionRunner {
             if (!acceptedUserId)
                 await this.clearLease(session.id);
             const newMessages = extractRunTranscript(agent.state.messages, baseline);
+            attemptFinalText = [...newMessages].reverse().find((message) => message.role === "assistant")?.text ?? "";
             // 任务终态小结（N5）：终态 status 已发布后补一条 session.summary，
             // 让「任务完成」有明确收尾（AI 一句总结 + 结构化统计）。await 保证
             // 落库后再 resolveDone（中断/失败场景不阻塞——内部有静默降级）。
@@ -737,7 +1085,24 @@ export class SessionRunner {
             void Promise.all(fireRunEnd(this.hooks, { sessionId: session.id, agent: session.agent, ok: !runErrored, aborted: abortController.signal.aborted, workspaceId: session.workspaceId, newMessages }));
             resolveDone();
         }
-        const outcome = unknownSideEffect ? "recovery_required" : abortController.signal.aborted ? "cancelled" : runErrored ? "failed" : "completed";
+        const aborted = abortController.signal.aborted;
+        const outcome = {
+            state: unknownSideEffect ? "recovery_required" : aborted ? "cancelled" : runErrored ? "failed" : "completed",
+            settled: !aborted && !runErrored && !unknownSideEffect,
+            aborted,
+            unknownSideEffect,
+            sideEffectDetail,
+            filesEdited: [...summaryEditedFiles],
+            toolCalls: summaryToolCalls,
+            durationMs: Date.now() - runStartedAt,
+            toolErrors: [...toolErrors],
+            finalText: attemptFinalText,
+            todos: latestTodos,
+            taskBlock,
+            delivery,
+            evidenceCandidates: [...evidenceCandidates],
+            errorMessage: runErrorMessage,
+        };
         if (acceptedUserId || unknownSideEffect)
             return outcome;
         // FIFO queued prompts (spec §13.3): settle fully, then take the next one.
@@ -758,6 +1123,382 @@ export class SessionRunner {
         }
         return outcome;
     }
+    // ---- 持续任务执行（规格 3 §8）----------------------------------------------
+    /** 带重试的 CAS 写入。
+     *
+     *  【为什么不「冲突就返回 latest」】那会让调用方以为补丁生效了，而库里没变——
+     *  结算路径尤其致命：它会照常发出 `task.delivered`，于是客户端显示「已完成」
+     *  而持久化状态还是 `running`，重启后任务像个卡住的僵尸。写不进去就必须知道。
+     *  重试几次是给「恰好撞上另一个 drain 的收尾写」留余地；仍然失败就是真的有人
+     *  在并发改同一个任务，那种情况必须浮出来（drain 会把它落成 recovery_required）。 */
+    async casTask(task, patch) {
+        const store = this.deps.store.task;
+        let latest = task;
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                return await store.updateTask(latest.id, latest.revision, patch);
+            }
+            catch (error) {
+                if (!(error instanceof Error) || error.message !== "TASK_REVISION_CONFLICT")
+                    throw error;
+                const fresh = await store.getTask(latest.id);
+                if (!fresh)
+                    throw error;
+                latest = fresh;
+            }
+        }
+        throw new Error("TASK_REVISION_CONFLICT");
+    }
+    /** 权限等待的进入 / 退出（规格 3 §11.1 / §11.2）。
+     *
+     *  进入时把任务置 `waiting_permission` 并挂 permission blocker；退出（授权通过
+     *  或被拒）时置回 `running` 并清 blocker。
+     *
+     *  【为什么退出后不是 blocked/failed】这次 Attempt 根本没被中断——`engine.ask()`
+     *  只是在 `beforeToolCall` 里挂住，决定一到就接着跑同一个工具循环。所以既不发
+     *  `task.attempt.finished`，也不创建用户消息、不新建 workflow run（§11.2 明文）。
+     *  唯一例外是被拒：拒绝结果会作为工具错误交回模型去试替代方案（§11.3）。
+     *
+     *  【为什么挂在引擎回调上，而不是 beforeToolCall 里】规则表已经允许的调用不会
+     *  弹卡（`ask()` 在 undecided 为空时直接返回），挂在调用点会为这些「秒过」的
+     *  调用也标一次等待再撤回，产生成对的假 blocker 事件。`onAsked` 只在真的抛出
+     *  一张授权卡时触发。
+     *
+     *  【为什么按 taskId 重读而不是接一个快照】`runLoop` 会被子代理嵌套调用
+     *  （`spawnSubagent`），同一个 runner 实例上同时存在两轮运行。用实例字段记
+     *  「当前任务」会被嵌套那轮清掉，父轮的权限等待于是静默丢失。按 id 重读没有
+     *  这个共享状态，代价是一次读，而权限询问本来就不是热路径。 */
+    async markPermissionWait(taskId, permission, patterns, waiting) {
+        const store = this.deps.store.task;
+        if (!taskId || !store)
+            return;
+        const blocker = {
+            kind: "permission",
+            message: `需要你授权才能执行：${permission}${patterns.length ? `（${patterns.join("、")}）` : ""}`,
+            requiredAction: "在授权卡片上选择允许或拒绝；任务会带着你的决定接着跑。",
+            resumable: true,
+        };
+        try {
+            const task = await store.getTask(taskId);
+            if (!task || isTerminalStatus(task.status))
+                return;
+            const updated = await this.casTask(task, waiting ? { status: "waiting_permission", blocker } : { status: "running", blocker: undefined });
+            await this.publish(waiting
+                ? { type: "task.blocked", data: { taskId: updated.id, revision: updated.revision, blocker } }
+                : // 协议里没有 task.resumed；`task.recovery.started` 是唯一表示「任务离开
+                    // 等待、重新开始推进」的事件，用它并让 message 说清是哪一种。
+                    { type: "task.recovery.started", data: { taskId: updated.id, revision: updated.revision, message: "授权已处理，继续执行。", attempt: Math.max(1, updated.attemptCount) } }, updated.sessionId);
+        }
+        catch {
+            // 等待状态的记账失败不该打断一次正在跑的工具调用——权限本身已经问出去了，
+            // 用户点了允许就该让工具跑。任务状态退化成「running」，是保守的那一侧。
+        }
+    }
+    /** 完成判定用的运行时事实。全部来自本轮可观测结果，**不接受模型自述**。
+     *
+     *  权限等待不在此列：`beforeToolCall` 里的 `engine.ask()` 会一直挂到用户回复，
+     *  所以一次 Attempt 收尾时不会有悬空请求（`engine.dispose()` 也会兜底）。
+     *  这里仍读一次实际值，是为了覆盖 abort / 异常路径。
+     *
+     *  【`task_block` 是这条规则的例外吗】不是。它确实由模型发起，但**内容是结构化
+     *  的声明**，不是自述的结论：模型说的是「我缺 X」「请你在 A 和 B 之间选」
+     *  「你需要去登录」，而不是「我已完成」。前者是事实的输入（只有模型知道自己在
+     *  等什么），后者才是不能采信的东西——完成与否始终由 Completion Gate 按步骤、
+     *  验收条件与证据独立判定，模型无法用 task_block 换来一个 delivered。 */
+    completionStateOf(outcome, session) {
+        // 只有「重试已经耗尽、且错误不是上游抖动」才算真的没救（规格 §10.2）。
+        // runLoop 内部已对可重试错误做过 5 次退避重试，能走到这里说明它没救回来。
+        const fatal = outcome.state === "failed" && !!outcome.errorMessage && !isRetryableError(outcome.errorMessage);
+        // `choice` 与 `input` 都落在 waiting_input，但文案与界面动作不同（§14.2），
+        // 所以在这里分派而不是揉成一个字符串。
+        const block = outcome.taskBlock;
+        return {
+            attemptSettled: outcome.settled,
+            fatalError: fatal ? outcome.errorMessage : null,
+            lastError: outcome.errorMessage,
+            unknownSideEffect: outcome.unknownSideEffect ? (outcome.sideEffectDetail ?? "存在结果不确定的操作") : null,
+            pendingPermissions: isSessionAwaitingPermission(session.id) ? 1 : 0,
+            unsafeReplay: null,
+            budgetExhausted: null,
+            externalAuthRequired: block?.kind === "external_auth" ? { message: block.message, requiredAction: block.requiredAction } : null,
+            inputRequired: block?.kind === "input" ? { message: block.message, requiredAction: block.requiredAction } : null,
+            choiceRequired: block?.kind === "choice" ? { message: block.message, requiredAction: block.requiredAction } : null,
+            unresolvedToolErrors: outcome.toolErrors,
+            finalTextPresent: outcome.finalText.trim().length > 0,
+            cancelled: outcome.aborted,
+        };
+    }
+    /** 步骤变化 → 事件。粒度按「状态真的变了」算，重放时不会重复累计。 */
+    async publishStepEvents(previous, next, sessionId) {
+        const before = new Map(previous.map((step) => [step.id, step.status]));
+        const completed = next.steps.filter((step) => step.status === "completed").length;
+        for (const step of next.steps) {
+            if (before.get(step.id) === step.status)
+                continue;
+            const type = step.status === "completed" ? "task.step.completed" : step.status === "in_progress" ? "task.step.started" : null;
+            if (!type)
+                continue;
+            await this.publish({ type, data: { taskId: next.id, revision: next.revision, stepId: step.id, message: step.title, completedSteps: completed, totalSteps: next.steps.length } }, sessionId);
+        }
+        if (before.size !== next.steps.length) {
+            await this.publish({
+                type: "task.plan.updated",
+                data: {
+                    taskId: next.id,
+                    revision: next.revision,
+                    goal: next.goal,
+                    steps: next.steps.map((step) => ({ id: step.id, title: step.title, status: step.status })),
+                    completedSteps: completed,
+                    totalSteps: next.steps.length,
+                },
+            }, sessionId);
+        }
+    }
+    /** 把本轮的可观测事实投影进任务契约：步骤、证据、隐式验收条件、进度指纹。
+     *
+     *  顺序不能换：证据先于验收条件（条件要引用 evidence id），而指纹最后算
+     *  （它是对「投影后的完整状态」取摘要）。 */
+    async syncTaskFromAttempt(task, outcome, sessionId) {
+        const now = new Date().toISOString();
+        // 1) 步骤（来自模型的 todo 拆解）
+        const steps = outcome.todos
+            ? projectTodos({ taskId: task.id, steps: task.steps, todos: outcome.todos, now })
+            : task.steps;
+        // 2) 证据（只收成功的写/执行/外部核对）
+        let evidence = task.evidence;
+        const dropped = [];
+        for (const candidate of outcome.evidenceCandidates) {
+            const appended = appendEvidence({ evidence, kind: candidate.kind, summary: candidate.summary, ...(candidate.ref ? { ref: candidate.ref } : {}), now });
+            evidence = appended.evidence;
+            dropped.push(...appended.dropped);
+        }
+        // 2b) 交付声明必须留下可追溯的证据（规格 §9 条件 3 的口子，§9 末段）。
+        //
+        // 【这里原来是「本轮只要有最终文本就记一条 model_observation」】那条规则把
+        // 「文本非空」直接变成了「有证据」，而证据又是条件 3 的输入——两个弱事实串起来
+        // 就凑出了一次交付。删掉它之后，纯解释 / 写作 / 问答类任务（没有工具可跑，
+        // 最终内容本身是唯一可验证的东西）靠**交付声明**拿到那一条证据：声明里
+        // `verification` 至少一条是 schema 强制的，也就是说模型必须先说清「怎么验证的」，
+        // 才拿得到这个口子——从「说过话」变成「说清了验证方式」，这是那条放宽能成立的下限。
+        //
+        // 【ref 固定为 task_deliver】`appendEvidence` 的去重键是 (kind, ref)，固定 ref
+        // 让重复交付**更新同一条**而不是不断新增。这不是省空间：进度指纹里
+        // `criteria.evidenceIds.length` 参与计算，每次交付都新增一条会让「反复交付」
+        // 看起来像在推进，no-progress 保护就失效了。
+        //
+        // 【只在任务没有任何工具证据时补】有工具证据的任务不该靠模型的自述通过验证，
+        // 那会让「有证据」重新退化成「说过话」。
+        const hasToolEvidence = evidence.some((item) => item.kind !== "model_observation");
+        let declarationEvidenceId;
+        if (outcome.delivery && !hasToolEvidence) {
+            const appended = appendEvidence({
+                evidence,
+                kind: "model_observation",
+                summary: outcome.delivery.verification.join("；").slice(0, 160),
+                ref: TASK_DELIVER_TOOL_ID,
+                now,
+            });
+            evidence = appended.evidence;
+            dropped.push(...appended.dropped);
+            declarationEvidenceId = evidence.find((item) => item.kind === "model_observation" && item.ref === TASK_DELIVER_TOOL_ID)?.id;
+        }
+        // 3) 引用清理 + 验收条件。淘汰证据后必须同步清引用，否则条件会因为
+        //    悬空引用永远不满足（Completion Gate 的条件 3 只认能对上号的证据）。
+        const prunedSteps = pruneEvidenceRefs(steps, dropped);
+        const prunedCriteria = pruneEvidenceRefs(task.acceptanceCriteria, dropped);
+        // 验收条件的结论只有一个来源：模型在 `task_deliver` 里的显式声明。此前这里的
+        // `projectImplicitCriterion` 会从「模型这轮有没有输出文本」推导出结论——那次
+        // 推导就是「一句话停在冒号上也能交付」的成因（见 `plan.ts`）。
+        const projection = outcome.delivery
+            ? applyDelivery({
+                criteria: prunedCriteria,
+                delivery: outcome.delivery,
+                evidence,
+                ...(declarationEvidenceId ? { declarationEvidenceId } : {}),
+                observedChanges: outcome.filesEdited,
+            })
+            : null;
+        const acceptanceCriteria = projection?.criteria ?? prunedCriteria;
+        // 4) 进度指纹（含本轮的文件改动）
+        const projected = { ...task, steps: prunedSteps, evidence, acceptanceCriteria };
+        const progress = advanceProgress(projected, { editedFiles: outcome.filesEdited, toolCalls: outcome.toolCalls });
+        const updated = await this.casTask(task, {
+            steps: prunedSteps,
+            evidence,
+            acceptanceCriteria,
+            ...(projection ? { result: projection.result } : {}),
+            lastFingerprint: progress.fingerprint,
+            noProgressCount: progress.noProgressCount,
+            // 时间预算的累计口径：这一轮实际跑了多久（见 `TaskRecord.activeMs`）。
+            // 放在这里而不是 `settleTask`，是因为**每一轮**都要记账——只在结算时记，
+            // 一个连跑 20 轮才停的任务会把整段时间全部漏掉，预算永远不触发。
+            activeMs: (task.activeMs ?? 0) + outcome.durationMs,
+        });
+        await this.publishStepEvents(task.steps, updated, sessionId);
+        return updated;
+    }
+    /** 任务进入终态（或阻塞）：落库 + 发事件，返回这次 run 的 workflow 状态。
+     *
+     *  blocked 返回 `"completed"` 而不是 `"failed"`：这次运行本身正常结束了，
+     *  任务是在等外部动作。返回 failed 会让 workflow 层把它当成运行崩溃处理
+     *  （还会触发 recovery 路径），那是错的。 */
+    async settleTask(task, verdict, session, stats) {
+        const now = new Date().toISOString();
+        const taskId = task.id;
+        if (verdict.status === "delivered") {
+            const result = task.result ?? fallbackResult({ task, filesEdited: stats.filesEdited, toolCalls: stats.toolCalls });
+            const updated = await this.casTask(task, { status: "delivered", deliveredAt: now, result });
+            await this.publish({
+                type: "task.delivered",
+                data: {
+                    taskId,
+                    revision: updated.revision,
+                    // `result` 是渲染好的文本（通知、复制、旧客户端都在用它）；
+                    // `delivery` 是同一份信息的结构化形态，给交付卡按四问分别渲染。
+                    // 【为什么两份都给】把结构化数据塞进一个字符串再让客户端解析，是此前
+                    // 「剩余项」出现两次的原因（`lib/chat-projector.ts` 把整段文本当成
+                    // `outcome`，四问里剩下的位置自然全空）。发两份比让客户端做字符串解析稳。
+                    result: renderResult(result),
+                    delivery: {
+                        outcome: result.outcome,
+                        changes: [...result.changes],
+                        verification: [...result.verification],
+                        remaining: [...result.remaining],
+                    },
+                    // 交付卡上「验收 x/y · 证据 n 条」两个数字的**权威来源**。此前它们
+                    // 只能靠客户端从 task.started（那一刻的条件永远全是 pending）和证据
+                    // 数组（事件流里根本没有）拼出来，于是界面上恒显示「验收 0/1 · 证据
+                    // 0 条」，与实际相反——而这一行恰恰是规格 §18.4 给用户「不必相信这句
+                    // 完成」的核对依据，一个恒错的核对依据比没有更糟。
+                    criteria: updated.acceptanceCriteria.map((criterion) => ({
+                        id: criterion.id,
+                        description: criterion.description,
+                        required: criterion.required,
+                        status: criterion.status,
+                    })),
+                    evidenceCount: updated.evidence.length,
+                    evidenceIds: updated.evidence.map((item) => item.id),
+                    filesEdited: stats.filesEdited.length,
+                    toolCalls: stats.toolCalls,
+                    durationMs: stats.durationMs,
+                },
+            }, session.id);
+            return "completed";
+        }
+        if (verdict.status === "failed") {
+            const updated = await this.casTask(task, { status: "failed" });
+            await this.publish({ type: "task.failed", data: { taskId, revision: updated.revision, reason: verdict.reason } }, session.id);
+            return "failed";
+        }
+        if (verdict.status === "cancelled") {
+            const updated = await this.casTask(task, { status: "cancelled" });
+            await this.publish({ type: "task.cancelled", data: { taskId, revision: updated.revision, reason: verdict.reason } }, session.id);
+            return "cancelled";
+        }
+        // blocked / waiting_*：阻塞种类决定状态，UI 据此给对应按钮（规格 §14.2）
+        const status = lifecycleForBlocker(verdict.blocker.kind);
+        const updated = await this.casTask(task, { status, blocker: verdict.blocker });
+        await this.publish({ type: "task.blocked", data: { taskId, revision: updated.revision, blocker: verdict.blocker } }, session.id);
+        return "completed";
+    }
+    /** 一个持久任务的执行循环（规格 §8.1 总流程）。
+     *
+     *  【为什么续跑在同一次调用内循环，而不是每轮新建一个 workflow run】
+     *  1. lease 与串行队列：任务执行期间必须持有 session 的执行权。每轮重建 run
+     *     意味着每轮都要重新 claim/lease，中间会出现「谁都没持有」的窗口——那
+     *     正是两个 runner 并行改同一工作区的入口。
+     *  2. 规格 §8.2.5 要求「继续使用 session 级串行队列和 lease」，循环是最直接
+     *     的实现。轮次计数落在 `TaskRecord.attemptCount` 上，所以进程重启后恢复
+     *     扫描仍能知道跑到第几轮。
+     *
+     *  出口只有两个：任务进入终态，或需要用户/外部动作。单次模型停止、step 上限、
+     *  本轮没有工具调用，**都不是**出口（规格 §8.3 逐条列出）。 */
+    async runTask(session, input, acceptedUserId) {
+        const taskStore = this.deps.store.task;
+        // 没有 TaskStore：退化为一次性运行。工具、权限、事件全部照常，只是没有
+        // 「跨运行的目标」这层语义——这不是错误路径，而是宿主未启用该能力的降级。
+        if (!taskStore)
+            return (await this.runLoop(session, input, acceptedUserId)).state;
+        let task = input.taskId ? await taskStore.getTask(input.taskId) : await taskStore.getActiveTask(session.id);
+        if (!task)
+            return (await this.runLoop(session, input, acceptedUserId)).state;
+        // `waiting_*` / `blocked` 意味着「在等用户做一个具体动作」，唯一有权解除它的
+        // 是 `resolveTaskForPrompt`——那条新消息本身就是用户动作。这里再挡一道，是因为
+        // **排队中的补充消息可能在阻塞之后才被 drain 到**：用户写下它的时候还没看到
+        // 阻塞原因，把它当成「已经看过并响应了」会静默清掉用户根本没读到的提示。
+        // （那条消息的正文已经并进了 `constraints`，不会丢，用户真正回应时会被带上。）
+        if (isWaitingStatus(task.status))
+            return "completed";
+        const maxAttempts = Math.min(MAX_ATTEMPT_CEILING, Math.max(1, Math.floor(this.deps.taskPolicy?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS)));
+        const maxDurationMs = normalizeMaxDurationMs(this.deps.taskPolicy?.maxDurationMs);
+        const noProgressPolicy = this.deps.taskPolicy?.noProgress;
+        // 从第二轮起，驱动这台机器的是任务自己（`continuation`），不再是「用户按过
+        // 按钮」那件事。把 `resume` 摘掉，否则 driveText 会一路走放行话术，掩盖了
+        // 真正发生的事（系统在自动续跑）。
+        const { resume: _resume, ...strippedInput } = input;
+        let attemptInput = input;
+        let advisory;
+        let continuation = false;
+        // 整个任务共用一个循环防护实例（规格 §16 阶段 D「loop-guard 扩展为跨 Attempt」）
+        const loopGuard = new LoopGuard();
+        let stats = { filesEdited: [], toolCalls: 0, durationMs: 0 };
+        while (true) {
+            const attemptNumber = task.attemptCount + 1;
+            // 时间预算先于轮数预算：两者的消息都指向「看一眼轨迹、确认目标是否要收窄」，
+            // 但先报出的应该是**已经烧掉多少时间**——那是用户此刻最需要知道的事实，
+            // 而轮数只在所有轮都很快时才成为瓶颈。
+            const overTime = durationBudgetBlocker(task, maxDurationMs);
+            if (overTime)
+                return await this.settleTask(task, { status: "blocked", blocker: overTime }, session, stats);
+            if (attemptNumber > maxAttempts) {
+                return await this.settleTask(task, {
+                    status: "blocked",
+                    blocker: {
+                        kind: "budget",
+                        message: `已达单次任务的最大执行轮数（${maxAttempts} 轮）。`,
+                        requiredAction: "看一眼执行轨迹，确认目标是否需要收窄；确认后可以继续。",
+                        resumable: true,
+                    },
+                }, session, stats);
+            }
+            task = await this.casTask(task, { status: "running", attemptCount: attemptNumber, blocker: undefined });
+            // 续跑时明确告诉用户「系统在自己接着做」，而不是又开了一轮对话
+            if (continuation) {
+                await this.publish({ type: "task.recovery.started", data: { taskId: task.id, revision: task.revision, message: advisory ?? "继续推进任务", attempt: attemptNumber } }, session.id);
+            }
+            const outcome = await this.runLoop(session, attemptInput, acceptedUserId, {
+                task,
+                loopGuard,
+                ...(advisory ? { advisory } : {}),
+                ...(continuation ? { continuation: true } : {}),
+            });
+            stats = { filesEdited: outcome.filesEdited, toolCalls: outcome.toolCalls, durationMs: outcome.durationMs };
+            task = await this.syncTaskFromAttempt(task, outcome, session.id);
+            // 一次 Attempt 结束——**不是**任务完成（规格 §8.3）。UI 只能拿它画轨迹。
+            await this.publish({
+                type: "task.attempt.finished",
+                data: {
+                    taskId: task.id,
+                    revision: task.revision,
+                    attempt: attemptNumber,
+                    outcome: outcome.aborted ? "aborted" : outcome.state === "failed" ? "error" : "completed",
+                    toolCalls: outcome.toolCalls,
+                    filesEdited: outcome.filesEdited.length,
+                    durationMs: outcome.durationMs,
+                },
+            }, session.id);
+            const verdict = evaluateTaskCompletion(task, this.completionStateOf(outcome, session), noProgressPolicy);
+            if (verdict.status !== "continue")
+                return await this.settleTask(task, verdict, session, stats);
+            // ---- 内部续跑：不创建用户消息，不新建 workflow run ----
+            advisory = verdict.advisory;
+            continuation = true;
+            attemptInput = { ...strippedInput, continuation: { attempt: attemptNumber + 1, ...(advisory ? { advisory } : {}) } };
+            // 上一轮是上游抖动的话，立刻重打一次没有意义——给它一个短退避
+            if (outcome.state === "failed")
+                await new Promise((resolve) => setTimeout(resolve, 1_000));
+        }
+    }
     /** Spawns a subagent child session (spec §6.4): depth-capped, permission
      *  stamped from parent session + subagent preset, runs a nested PI loop to
      *  completion, and returns the child's final assistant text as the parent
@@ -939,9 +1680,29 @@ export class SessionRunner {
                     .filter((part) => part.type === "text")
                     .map((part) => part.text)
                     .join("\n");
-                const files = parts.filter((p) => p.type === "file" && p.url.startsWith("data:"));
-                const attachments = files.map((p) => ({ name: p.filename, mediaType: p.mime, data: p.url, size: Buffer.from(p.url.slice(p.url.indexOf(",") + 1), "base64").length }));
-                messages.push({ role: "user", content: [{ type: "text", text }, ...attachmentContent(attachments)], timestamp: Date.parse(info.time.created) || Date.now() });
+                const fileParts = parts.filter((p) => p.type === "file");
+                // 旧链路历史：data URL 内联部分保持原样重建，否则升级后老会话会「丢附件」。
+                const legacy = fileParts.flatMap((p) => {
+                    const url = p.url;
+                    if (typeof url !== "string" || !url.startsWith("data:"))
+                        return [];
+                    return [{ name: p.filename, mediaType: p.mime, data: url, size: Buffer.from(url.slice(url.indexOf(",") + 1), "base64").length }];
+                });
+                // 新链路：按描述符重建，正文经 provider 读取（图片→视觉输入、小文本→内联、其余→清单）。
+                // 因此重放历史**不会**把所有附件正文反复塞进后续每个 turn（规格 2 §11）。
+                // 用 AttachmentContentRef 而不是 InputAttachmentRef：part 里没有 sha256，
+                // 硬编一个假摘要会违反该类型的不变量。
+                const refs = fileParts.flatMap((p) => p.attachmentId
+                    ? [{
+                            id: p.attachmentId,
+                            name: p.filename,
+                            mediaType: p.mime,
+                            ...(typeof p.size === "number" ? { size: p.size } : {}),
+                            kind: p.kind ?? "text",
+                        }]
+                    : []);
+                const refParts = await attachmentRefContent(this.deps.attachments, refs, { sessionId });
+                messages.push({ role: "user", content: [{ type: "text", text }, ...attachmentContent(legacy), ...refParts], timestamp: Date.parse(info.time.created) || Date.now() });
             }
             else {
                 const text = parts