paseo-req-kit 1.11.0-beta.1 → 1.12.0-beta.2

package/engine/src/pipeline.ts

@@ -36,8 +36,8 @@ import { dispatchNotifiers, type NotifierEventType } from "./notifiers.js";
 import { describeExternal, type IntegrationEvent, type Runner, syncIntegration } from "./integrations.js";
 import { cardSlug, planAppendix, publishCard, readSource } from "./card.js";
 import { principlesSection, projectAdditions, type PromptLocations, readToolPrompt } from "./prompts.js";
-import type { AgentRuntime, ManagedService, ServiceTarget, StepAgent } from "./runtime.js";
-import { type CheckOutcome, type GateRun, type JointRepo, type PhaseName, type PipelineState, type RunPhases, type StepRecord, writeState } from "./state.js";
+import type { AgentRuntime, ManagedService, ServiceTarget, StepAgent, WaitOutcome } from "./runtime.js";
+import { type CheckOutcome, type GateRun, type JointRepo, type PhaseName, type PipelineState, type Recovery, type RunPhases, type StepRecord, type StopKind, writeState } from "./state.js";
 import { type PanelStep, STEPS, type StepDef, type StepId, stepKey, validateResult, VERIFY_PHASE_STEPS } from "./steps.js";
 
 export interface PipelineContext {
@@ -124,6 +124,40 @@ class StepFailure extends Error {
   }
 }
 
+/** The step gave up on its agent while the agent may still be working (1.11). */
+class AgentLeftRunning extends StepFailure {
+  constructor(
+    stepTitle: string,
+    message: string,
+    readonly timedOut: boolean,
+  ) {
+    super(stepTitle, message);
+  }
+}
+
+/** The agent's turn ended with an error status (1.12). */
+class AgentErrored extends StepFailure {}
+
+/** The agent did not write a valid result file, even after the reminders (1.12). */
+class ResultInvalid extends StepFailure {}
+
+/** Notes something the pipeline handled by itself (state.recoveries, the log). */
+function recover(ctx: PipelineContext, key: string, kind: Recovery["kind"], detail: string): void {
+  ctx.state.recoveries = [...(ctx.state.recoveries ?? []), { at: new Date().toISOString(), key, kind, detail: detail.slice(0, 300) }].slice(-200);
+  save(ctx);
+  ctx.log(`自动处理（${key}）：${detail}`);
+}
+
+/** Why a run stopped, as a code for the usage record (1.12). */
+function failureKind(error: unknown): StopKind {
+  if (error instanceof AgentLeftRunning) return error.timedOut ? "timeout" : "transient";
+  const message = (error as Error).message ?? "";
+  if (error instanceof StepFailure && isTransientError(message)) return "transient";
+  if (error instanceof AgentErrored) return "agent_error";
+  if (error instanceof ResultInvalid) return "invalid_result";
+  return "other";
+}
+
 /**
  * Errors that usually go away by themselves: provider rate limits and overload,
  * dropped connections, a restarting daemon. A step that fails this way is started
@@ -484,15 +518,31 @@ async function milestone(ctx: PipelineContext, id: string, text: string): Promis
   await notifyExternal(ctx, "milestone", text, { milestone: id });
 }
 
-async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef, agentTitle: string, deadline: number): Promise<AgentUsage | null> {
+/** A step's time limit; `extended` once it was given a second period (selfHeal). */
+interface Deadline {
+  at: number;
+  extended: boolean;
+  key: string;
+}
+
+async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef, agentTitle: string, deadline: Deadline): Promise<AgentUsage | null> {
   const notifiedPermissions = new Set<string>();
   let consecutiveErrors = 0;
   for (;;) {
-    const remaining = deadline - Date.now();
+    let remaining = deadline.at - Date.now();
+    if (remaining <= 0 && ctx.config.selfHeal && !deadline.extended) {
+      // Usually a big step, not a stuck one: the agent keeps its progress and gets as long again.
+      deadline.extended = true;
+      deadline.at = Date.now() + ctx.config.stepTimeoutMinutes[def.id] * 60_000;
+      remaining = deadline.at - Date.now();
+      recover(ctx, deadline.key, "extend_timeout", `超过 ${ctx.config.stepTimeoutMinutes[def.id]} 分钟仍未完成，agent 还在做，再给它同样长的时间`);
+    }
     if (remaining <= 0) {
-      throw new StepFailure(
+      const total = ctx.config.stepTimeoutMinutes[def.id] * (deadline.extended ? 2 : 1);
+      throw new AgentLeftRunning(
         def.title,
-        `超过 ${ctx.config.stepTimeoutMinutes[def.id]} 分钟仍未完成。该 agent 可能仍在运行，可以在 Paseo 中查看「${agentTitle}」。`,
+        `超过 ${total} 分钟仍未完成。agent「${agentTitle}」还在运行，没有停止它；继续时会先看它的情况：做完了就用它的结果，还在做就接着等它，不会另起一个 agent 重复做。`,
+        true,
       );
     }
     let outcome;
@@ -503,7 +553,7 @@ async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef,
       consecutiveErrors += 1;
       ctx.log(`等待 ${agentTitle} 时出错（第 ${consecutiveErrors} 次）：${(error as Error).message}`);
       if (consecutiveErrors >= 5) {
-        throw new StepFailure(def.title, `连续 ${consecutiveErrors} 次无法获取 agent 状态：${(error as Error).message}`);
+        throw new AgentLeftRunning(def.title, `连续 ${consecutiveErrors} 次无法获取 agent 状态：${(error as Error).message}`, false);
       }
       await ctx.sleep(Math.min(60_000, 5_000 * consecutiveErrors));
       continue;
@@ -514,7 +564,7 @@ async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef,
       case "timeout":
         continue;
       case "error":
-        throw new StepFailure(def.title, `agent 报告错误：${outcome.error ?? "未知错误"}`);
+        throw new AgentErrored(def.title, `agent 报告错误：${outcome.error ?? "未知错误"}`);
       case "permission": {
         const fresh = outcome.pendingPermissions.filter((p) => !notifiedPermissions.has(p.id));
         if (fresh.length > 0) {
@@ -559,31 +609,63 @@ async function runStep(
   extras: StepExtras = {},
 ): Promise<Record<string, unknown>> {
   const { attempts, backoffSeconds } = ctx.config.retry;
+  const key = extras.key ?? keyFor(stepKey(id, round), extras.target);
+  const fallback = ctx.config.agents.fallback ?? null;
+  let redone = false;
+  let usedFallback = false;
   for (let retry = 0; ; retry += 1) {
     try {
       return await runStepOnce(ctx, id, round, maxRounds, extras);
     } catch (error) {
       const message = (error as Error).message;
-      if (!(error instanceof StepFailure) || !isTransientError(message) || retry >= attempts) {
+      const transient = error instanceof StepFailure && isTransientError(message);
+      const healable = error instanceof AgentErrored || error instanceof ResultInvalid;
+      // 1.12: a step whose agent errored or wrote no valid result is redone once with a new
+      // agent; one that keeps hitting rate limits gets the fallback model, when there is one.
+      if (error instanceof StepFailure && ctx.config.selfHeal && !transient && healable && !redone) {
+        redone = true;
+        const switchModel = fallback !== null && !usedFallback && error instanceof AgentErrored;
+        if (switchModel) usedFallback = true;
+        recover(
+          ctx,
+          key,
+          switchModel ? "fallback" : "redo",
+          `${message.slice(0, 160)}；${switchModel ? "换备用模型" : "新开一个 agent"}重做这一步`,
+        );
+        extras = withRetryNote({ ...extras, ...(switchModel ? { profile: fallback } : {}) }, message);
+        continue;
+      }
+      if (error instanceof StepFailure && transient && retry >= attempts && fallback !== null && !usedFallback && !(error instanceof AgentLeftRunning)) {
+        usedFallback = true;
+        recover(ctx, key, "fallback", `重试 ${retry} 次后仍然${message.slice(0, 120)}；换备用模型继续这一步`);
+        extras = withRetryNote({ ...extras, profile: fallback }, message);
+        continue;
+      }
+      if (!(error instanceof StepFailure) || !transient || retry >= attempts) {
         if (error instanceof StepFailure && retry > 0) {
-          throw new StepFailure(error.stepTitle, `${message}（已自动重试 ${retry} 次）`);
+          throw new (error.constructor as typeof StepFailure)(error.stepTitle, `${message}（已自动重试 ${retry} 次）`);
         }
         throw error;
       }
       const wait = backoffSeconds.at(Math.min(retry, backoffSeconds.length - 1)) ?? 60;
-      ctx.log(`${error.stepTitle} 遇到临时错误：${message}。${wait} 秒后自动重试（第 ${retry + 1} 次，最多 ${attempts} 次）`);
+      recover(ctx, key, "retry", `遇到临时错误：${message.slice(0, 160)}。${wait} 秒后自动重试（第 ${retry + 1} 次，最多 ${attempts} 次）`);
       await ctx.sleep(wait * 1000);
-      extras = {
-        ...extras,
-        contextLines: [
-          ...(extras.contextLines ?? []).filter((l) => !l.startsWith("自动重试：")),
-          `自动重试：本步骤上一次因临时错误中断（${message.slice(0, 200)}）。工作区里可能留有上一次没做完的改动，先用 git status 和 git diff 查看，在此基础上继续，不要重复提交`,
-        ],
-      };
+      extras = withRetryNote(extras, message);
     }
   }
 }
 
+/** Tells the next agent of a step that an earlier one stopped part way. */
+function withRetryNote(extras: StepExtras, message: string): StepExtras {
+  return {
+    ...extras,
+    contextLines: [
+      ...(extras.contextLines ?? []).filter((l) => !l.startsWith("自动重试：")),
+      `自动重试：本步骤上一次中断了（${message.slice(0, 200)}）。工作区里可能留有上一次没做完的改动，先用 git status 和 git diff 查看，在此基础上继续，不要重复提交`,
+    ],
+  };
+}
+
 async function runStepOnce(
   ctx: PipelineContext,
   id: StepId,
@@ -604,7 +686,11 @@ async function runStepOnce(
   const resultRel = `${ctx.featureDir}/.pipeline/results/${key}.json`;
   const resultAbs = path.join(stepRepo, resultRel);
   fs.mkdirSync(path.dirname(resultAbs), { recursive: true });
-  fs.rmSync(resultAbs, { force: true });
+
+  // An earlier run of this step may have left its agent working: use it, never run a second one.
+  const leftover = await checkLeftover(ctx, key, def, resultAbs);
+  if (leftover.done) return leftover.done;
+  if (!leftover.agent) fs.rmSync(resultAbs, { force: true });
 
   // Services, the browser and the deployed environment belong to the steps in this repository.
   const managed = target
@@ -638,10 +724,14 @@ async function runStepOnce(
     error: null,
     phase: phaseOf(ctx),
   };
-  ctx.log(`开始 ${key}（${def.title}）`);
+  if (leftover.agent) {
+    record.agentId = leftover.agent.id;
+    record.reattached = leftover.reattached;
+  }
+  ctx.log(leftover.agent ? `继续等待 ${key}（${def.title}）上一次的 agent ${leftover.agent.id}` : `开始 ${key}（${def.title}）`);
 
   try {
-    const agent = await ctx.runtime.startAgent({
+    const agent = leftover.agent ?? await ctx.runtime.startAgent({
       role: def.role,
       title: agentTitle,
       prompt: buildPrompt(ctx, def, round, maxRounds, resultRel, extras),
@@ -660,7 +750,7 @@ async function runStepOnce(
     ctx.state.history.push(record);
     save(ctx);
 
-    const deadline = Date.now() + ctx.config.stepTimeoutMinutes[id] * 60_000;
+    const deadline: Deadline = { at: Date.now() + ctx.config.stepTimeoutMinutes[id] * 60_000, extended: false, key };
     record.usage = (await waitForTurn(ctx, agent, def, agentTitle, deadline)) ?? record.usage ?? null;
     let validation = readResultFile(resultAbs, def);
     while (!validation.ok && record.followUps < ctx.config.resultFollowUps) {
@@ -672,7 +762,7 @@ async function runStepOnce(
       validation = readResultFile(resultAbs, def);
     }
     if (!validation.ok) {
-      throw new StepFailure(def.title, `提醒 ${record.followUps} 次后仍没有得到有效的结果文件：${validation.error}`);
+      throw new ResultInvalid(def.title, `提醒 ${record.followUps} 次后仍没有得到有效的结果文件：${validation.error}`);
     }
 
     if (extras.gate) {
@@ -699,6 +789,7 @@ async function runStepOnce(
     record.outcome = "failed";
     record.endedAt = new Date().toISOString();
     record.error = (error as Error).message;
+    if (error instanceof AgentLeftRunning) record.leftRunning = true;
     if (!ctx.state.history.includes(record)) ctx.state.history.push(record);
     save(ctx);
     if (error instanceof StepFailure) throw error;
@@ -706,6 +797,72 @@ async function runStepOnce(
   }
 }
 
+/**
+ * Before a step starts an agent, looks at the agent an earlier run of the same step left
+ * working (a timeout, unreadable status, or a pipeline process that died mid-step):
+ * - it has finished and written a valid result: that result is the step's result;
+ * - it is still working: the step waits for it again (once); the second time it is stopped
+ *   and a new agent starts, so a stuck agent does not hold the step forever;
+ * - it cannot be reached, or finished without a valid result: a new agent starts.
+ * Two agents on one step would edit the same files, commit in the same worktree and write
+ * the same result file, so a new one never starts while the old one may be working.
+ */
+async function checkLeftover(
+  ctx: PipelineContext,
+  key: string,
+  def: StepDef,
+  resultAbs: string,
+): Promise<{ done?: Record<string, unknown>; agent?: StepAgent; reattached?: number }> {
+  const last = [...ctx.state.history].reverse().find((h) => h.key === key);
+  if (!last?.agentId || last.outcome === "completed") return {};
+  if (last.outcome !== "running" && !last.leftRunning) return {};
+  last.leftRunning = false;
+  if (last.outcome === "running") {
+    last.outcome = "failed";
+    last.endedAt = new Date().toISOString();
+    last.error ??= "流水线进程在这一步运行时退出";
+  }
+  save(ctx);
+  const agent = ctx.runtime.attachAgent(last.agentId);
+  let status: WaitOutcome["status"] | "unreachable";
+  try {
+    status = (await agent.wait(Math.min(5_000, ctx.config.waitChunkSeconds * 1000))).status;
+  } catch (error) {
+    ctx.log(`无法读取 ${key} 上一次的 agent ${last.agentId} 的状态（${(error as Error).message}），新建一个 agent`);
+    status = "unreachable";
+  }
+  if (status === "idle") {
+    const validation = readResultFile(resultAbs, def);
+    if (validation.ok) {
+      last.outcome = "completed";
+      last.endedAt = new Date().toISOString();
+      last.error = null;
+      last.result = validation.value;
+      ctx.state.results[key] = validation.value;
+      save(ctx);
+      recover(ctx, key, "reuse_result", `上一次的 agent ${last.agentId} 已经做完，沿用它的结果`);
+      if (ctx.config.archiveStepAgents) await agent.archive().catch(() => undefined);
+      return { done: validation.value };
+    }
+    ctx.log(`${key} 上一次的 agent ${last.agentId} 已经停下，但没有有效的结果文件（${validation.error}），新建一个 agent`);
+    return {};
+  }
+  if (status === "timeout" || status === "permission") {
+    if ((last.reattached ?? 0) < 1) {
+      recover(ctx, key, "reattach", `上一次的 agent ${last.agentId} 还在做，接着等它，不另起一个`);
+      return { agent, reattached: (last.reattached ?? 0) + 1 };
+    }
+    ctx.log(`${key} 上一次的 agent ${last.agentId} 已经等过两轮仍未完成，停止它并新建一个 agent`);
+    await ctx.runtime
+      .interruptAgent(last.agentId, "这一步已超时，流水线会另起一个 agent 重做。请立即停止当前工作，不要再修改任何文件，也不要写结果文件，直接结束。")
+      .catch((error: Error) => ctx.log(`无法停止 agent ${last.agentId}：${error.message}`));
+    // Give it a moment to wind down before the new agent touches the same files.
+    await agent.wait(Math.min(60_000, ctx.config.waitChunkSeconds * 1000 * 2)).catch(() => undefined);
+    return {};
+  }
+  return {};
+}
+
 /** phases.verify.agents applies to the verify-phase steps. */
 function phaseAgent(ctx: PipelineContext, id: StepId): AgentProfile | undefined {
   if (!VERIFY_PHASE_STEPS.includes(id)) return undefined;
@@ -948,6 +1105,26 @@ async function scheduleApprovalContinue(ctx: PipelineContext): Promise<string |
 }
 
 /** A Paseo schedule that has the chat continue the run later; returns the time as text, or null. */
+/** Rate limits and used-up subscriptions, as opposed to network trouble. */
+const QUOTA_ERROR = /rate.?limit|too many requests|\b429\b|quota|usage limit|额度|限流/i;
+
+/**
+ * 1.12: when a step stopped on rate limits and Paseo says when a used-up subscription window
+ * resets, the time to continue (5 minutes after the reset, within 24 hours); null otherwise.
+ */
+async function quotaResetTime(ctx: PipelineContext, reason: string): Promise<Date | null> {
+  if (!QUOTA_ERROR.test(reason)) return null;
+  const profiles = [ctx.config.agents.builder, ctx.config.agents.reviewer, ...(ctx.config.agents.fallback ? [ctx.config.agents.fallback] : [])];
+  const providers = [...new Set(profiles.map((p) => (p.provider ?? "").split("/")[0]).filter(Boolean))];
+  const quotas = await ctx.runtime.providerQuota(providers).catch(() => null);
+  const now = Date.now();
+  const resets = (quotas ?? [])
+    .filter((q) => q.resetsAt && ((q.usedPct !== null && q.usedPct >= 95) || q.tone === "danger"))
+    .map((q) => new Date(q.resetsAt!).getTime())
+    .filter((t) => t > now && t < now + 24 * 3600_000);
+  return resets.length === 0 ? null : new Date(Math.max(...resets) + 5 * 60_000);
+}
+
 async function scheduleAutoResume(ctx: PipelineContext, reason: string): Promise<string | null> {
   const minutes = ctx.config.autoResumeMinutes;
   const origin = ctx.state.originAgentId;
@@ -957,7 +1134,8 @@ async function scheduleAutoResume(ctx: PipelineContext, reason: string): Promise
     ctx.log(`这次尝试已经自动继续过 ${used} 次，不再预约`);
     return null;
   }
-  const at = new Date(Date.now() + minutes * 60_000);
+  const reset = await quotaResetTime(ctx, reason);
+  const at = reset ?? new Date(Date.now() + minutes * 60_000);
   try {
     const id = await ctx.runtime.scheduleMessage({
       agentId: origin,
@@ -974,7 +1152,9 @@ async function scheduleAutoResume(ctx: PipelineContext, reason: string): Promise
     ctx.state.schedules = [...(ctx.state.schedules ?? []), { id, kind: "auto-resume", at: at.toISOString() }];
     ctx.state.autoResumes = { attempt: ctx.state.attempt, count: used + 1 };
     save(ctx);
-    ctx.log(`已预约 ${minutes} 分钟后自动继续（Paseo 定时任务 ${id}）`);
+    const when = at.toLocaleString("zh-CN", { hour12: false });
+    if (reset) recover(ctx, "pipeline", "quota_wait", `额度用完，Paseo 显示会恢复；已预约在 ${when} 自动继续（Paseo 定时任务 ${id}）`);
+    else recover(ctx, "pipeline", "auto_resume", `已预约 ${minutes} 分钟后自动继续（Paseo 定时任务 ${id}）`);
     return at.toLocaleString("zh-CN", { hour12: false, month: "numeric", day: "numeric", hour: "2-digit", minute: "2-digit" });
   } catch (error) {
     ctx.log(`预约自动继续失败：${(error as Error).message}`);
@@ -1005,7 +1185,7 @@ async function checkQuota(ctx: PipelineContext): Promise<void> {
     [
       "【需求开发流水线通知】这条消息来自后台流水线，不是用户发的。",
       `额度提醒：${items.join("；")}。`,
-      "流水线照常进行；额度用完时会遇到限流，流水线会自动等待重试，重试用完会中断，之后可以继续。如果希望等额度恢复后再开发，请转告用户，用户同意的话可以先暂停。",
+      `流水线照常进行；额度用完时会遇到限流，流水线会先重试${ctx.config.agents.fallback ? "、再换备用模型" : ""}，仍不行就预约在额度恢复后自动继续，不需要人处理。如果希望等额度恢复后再开发，请转告用户，用户同意的话可以先暂停，再预约在恢复时间开始。`,
     ].join("\n"),
   );
 }
@@ -1492,11 +1672,33 @@ async function assessmentPhase(ctx: PipelineContext): Promise<void> {
   for (let r = 1; r <= rounds.designReview; r++) {
     const review = await runReview(ctx, "design_review", r, rounds.designReview);
     if (review.verdict === "approved") break;
-    if (review.verdict === "blocked") throw new BusinessDecisionNeeded(review.questions as string[]);
+    if (review.verdict === "blocked") {
+      await answerFirst(ctx, review, r, rounds.designReview);
+      continue;
+    }
     await runStep(ctx, "design_revise", r, rounds.designReview);
   }
 }
 
+/**
+ * The review says only the requester can decide (1.12): the builder first answers what the
+ * code, the documents and the spec settle, in a revision of the design; what is left goes to
+ * the requester, each with a recommended answer.
+ */
+async function answerFirst(ctx: PipelineContext, review: Record<string, unknown>, round: number, maxRounds: number): Promise<void> {
+  const questions = (review.questions as string[]) ?? [];
+  if (!ctx.config.answerQuestionsFirst) throw new BusinessDecisionNeeded(questions);
+  const revised = await runStep(ctx, "design_revise", round, maxRounds, {
+    contextLines: [`审核结论：需要需求方决定（${questions.length} 个问题，见 design-review.md）。按本步骤说明中"审核要求需求方决定时"一节，先自己找答案`],
+  });
+  const left = Array.isArray(revised.business_questions) ? (revised.business_questions as string[]).map((q) => q.trim()).filter(Boolean) : [];
+  const answered = Math.max(0, questions.length - left.length);
+  if (answered > 0) {
+    recover(ctx, `design_revise-r${round}`, "self_answer", `方案审核提出的 ${questions.length} 个问题中，${answered} 个由 builder 从代码和文档中确定了答案${left.length > 0 ? `，${left.length} 个交给需求方` : "，不用等需求方"}`);
+  }
+  if (left.length > 0) throw new BusinessDecisionNeeded(left);
+}
+
 /** Develop phase: design → design review ⇄ revise → implement → code review ⇄ fix → handoff. Returns the design result. */
 async function developPhase(ctx: PipelineContext): Promise<Record<string, unknown>> {
   const rounds = ctx.config.profiles[ctx.state.profile].rounds;
@@ -1527,7 +1729,10 @@ async function developPhase(ctx: PipelineContext): Promise<Record<string, unknow
     const review = await runReview(ctx, "design_review", r, rounds.designReview);
     designRounds = r;
     if (review.verdict === "approved") break;
-    if (review.verdict === "blocked") throw new BusinessDecisionNeeded(review.questions as string[]);
+    if (review.verdict === "blocked") {
+      await answerFirst(ctx, review, r, rounds.designReview);
+      continue;
+    }
     // changes_required. The last round's revision goes straight to implementation;
     // the implementer reads both the review and the revision record.
     await runStep(ctx, "design_revise", r, rounds.designReview);
@@ -1801,6 +2006,7 @@ async function flow(ctx: PipelineContext): Promise<Record<string, unknown>> {
 export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome> {
   ctx.state.status = "running";
   ctx.state.stopReason = null;
+  ctx.state.stopKind = null;
   save(ctx);
   await integrate(ctx, phaseOf(ctx) === "verify" ? "verify" : "started");
   try {
@@ -1842,6 +2048,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
     if (error instanceof PhaseGate) {
       ctx.state.status = "phase_done";
       ctx.state.stopReason = null;
+      ctx.state.stopKind = "phase_gate";
       save(ctx);
       await stopManagedServices(ctx);
       const verifyAt = await scheduleVerifyStart(ctx);
@@ -1872,6 +2079,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
     if (error instanceof ApprovalNeeded) {
       ctx.state.status = "waiting_for_approval";
       ctx.state.stopReason = null;
+      ctx.state.stopKind = "approval";
       save(ctx);
       const autoContinueAt = await scheduleApprovalContinue(ctx);
       const reminderHours = await scheduleReminder(ctx, "approval");
@@ -1899,6 +2107,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
     if (error instanceof BusinessDecisionNeeded) {
       const reproduce = error.source === "reproduce";
       ctx.state.status = "waiting_for_business";
+      ctx.state.stopKind = reproduce ? "reproduce" : "business";
       ctx.state.stopReason = `${reproduce ? "没能复现缺陷，需要需求方补充信息" : "方案审核需要需求方决定"}：${error.questions.join("；")}`;
       save(ctx);
       const reminderHours = await scheduleReminder(ctx, error.questions);
@@ -1919,6 +2128,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
     const stepTitle = error instanceof StepFailure ? error.stepTitle : "流水线";
     ctx.state.status = "failed";
     ctx.state.stopReason = `${stepTitle}：${(error as Error).message}`;
+    ctx.state.stopKind = failureKind(error);
     save(ctx);
     const autoResumeAt =
       error instanceof StepFailure && isTransientError((error as Error).message) ? await scheduleAutoResume(ctx, (error as Error).message) : null;

package/engine/src/records.ts

@@ -165,6 +165,10 @@ export interface RunRecord {
     /** The report's verdict when the run completed (completed, completed_with_issues, not_completed). */
     outcome: string | null;
     stopReason: string | null;
+    /** 1.12: why the run stopped for a person, as a code (absent in older records). */
+    stopKind?: string | null;
+    /** 1.12: what the pipeline handled by itself during the run, by kind (absent in older records). */
+    recoveries?: Record<string, number>;
   };
   agents: { builder: string | null; reviewer: string | null };
   steps: StepUsageRecord[];
@@ -241,6 +245,10 @@ export function runRecord(input: {
       status: state.status,
       outcome: state.status === "completed" ? state.outcome : null,
       stopReason: state.stopReason,
+      stopKind: state.status === "completed" || state.status === "running" ? null : (state.stopKind ?? null),
+      recoveries: (state.recoveries ?? [])
+        .filter((r) => new Date(r.at).getTime() >= since)
+        .reduce<Record<string, number>>((m, r) => ({ ...m, [r.kind]: (m[r.kind] ?? 0) + 1 }), {}),
     },
     agents: input.agents,
     steps,

package/engine/src/runtime.ts

@@ -111,6 +111,8 @@ export interface AgentRuntime {
    */
   verifyOrigin(agentId: string, cwd: string): Promise<void>;
   startAgent(input: StartAgentInput): Promise<StepAgent>;
+  /** An agent started earlier (possibly by another pipeline process), to check on, wait for or follow up. */
+  attachAgent(agentId: string): StepAgent;
   /**
    * Starts a requirement's own chat (1.10): a top-level agent working in the repository, given
    * `prompt` and not waited for. It is the chat the requirement's pipeline is later launched

package/engine/src/state.ts

@@ -27,6 +27,32 @@ export interface RunPhases {
   defects: DefectHandling;
 }
 
+/**
+ * Why a run stopped for a person (1.12). Necessary decisions: approval (the plan), business
+ * (a question only the requester can answer), reproduce (a defect that could not be reproduced),
+ * phase_gate (development done, waiting for testing). The rest are interruptions.
+ */
+export type StopKind =
+  | "approval"
+  | "business"
+  | "reproduce"
+  | "phase_gate"
+  | "timeout"
+  | "agent_error"
+  | "invalid_result"
+  | "transient"
+  | "stopped"
+  | "process_exit"
+  | "other";
+
+/** Something the pipeline handled by itself (1.12). */
+export interface Recovery {
+  at: string;
+  key: string;
+  kind: "retry" | "reattach" | "reuse_result" | "extend_timeout" | "redo" | "fallback" | "auto_resume" | "quota_wait" | "self_answer";
+  detail: string;
+}
+
 export interface StepRecord {
   key: string;
   stepId: StepId;
@@ -43,6 +69,13 @@ export interface StepRecord {
   usage?: AgentUsage | null;
   /** Phase the step ran in; absent before 1.7 (develop or verify by step). */
   phase?: PhaseName;
+  /**
+   * 1.11: the step failed while its agent was still at work (timed out, or its status could
+   * not be read). The next run of the step checks that agent before starting another one.
+   */
+  leftRunning?: boolean;
+  /** 1.11: how many times a later run went on waiting for this record's agent instead of starting a new one. */
+  reattached?: number;
 }
 
 export interface PipelineState {
@@ -62,6 +95,10 @@ export interface PipelineState {
   results: Record<string, Record<string, unknown>>;
   history: StepRecord[];
   stopReason: string | null;
+  /** 1.12: why the run stopped for a person, as a code (contracts/usage-record.md); null while running or done. */
+  stopKind?: StopKind | null;
+  /** 1.12: what the pipeline handled by itself instead of stopping (retries, waiting longer, a fallback model…). */
+  recoveries?: Recovery[];
   outcome: string | null;
   /** "quick" or "standard"; decides loop rounds and optional steps. */
   profile: ProfileName;

package/engine/src/stats.ts

@@ -109,6 +109,35 @@ function waitKind(status: string): WaitKind {
   return "other";
 }
 
+/** Why runs stopped for a person (1.12, state.stopKind). */
+export const STOP_LABELS: Record<string, string> = {
+  approval: "确认方案",
+  phase_gate: "研发完成，等待测试",
+  business: "方案审核的问题等需求方决定",
+  reproduce: "缺陷复现不了，等需求方补充",
+  timeout: "步骤超时",
+  agent_error: "agent 报错",
+  invalid_result: "结果文件无效",
+  transient: "限流、网络等临时错误（自动重试用完）",
+  stopped: "被手动停止",
+  process_exit: "后台进程意外退出",
+  other: "其他中断",
+};
+
+/** Stops that are the decisions people are meant to make; the rest are what 1.12 works to remove. */
+export const NECESSARY_STOPS = ["approval", "phase_gate"];
+
+/** The stop code of a run; older records (before 1.12) are inferred from the status. */
+export function stopKindOf(r: RunRecord): string | null {
+  if (r.run.stopKind !== undefined) return r.run.stopKind;
+  if (r.run.status === "waiting_for_approval") return "approval";
+  if (r.run.status === "waiting_for_business") return "business";
+  if (r.run.status === "phase_done") return "phase_gate";
+  if (r.run.status === "failed") return /手动停止|被 SIG/.test(r.run.stopReason ?? "") ? "stopped" : "other";
+  if (r.run.status === "running") return "process_exit";
+  return null;
+}
+
 /** Records of the same run seen twice (merged exports) count once. */
 export function dedupe(runs: RunRecord[]): RunRecord[] {
   const seen = new Map<string, RunRecord>();
@@ -208,6 +237,19 @@ export interface StatsSummary {
   waits: Array<{ kind: WaitKind; label: string; requirements: number; averageMinutes: number }>;
   usage: { agentMinutes: number; inputTokens: number | null; outputTokens: number | null; costUsd: number | null };
   byBuilder: Array<{ builder: string; requirements: number; averageReviewRounds: number | null; averageCostUsd: number | null }>;
+  /** 1.12: why the period's runs stopped for a person, most frequent first. */
+  stops: Array<{ kind: string; label: string; necessary: boolean; runs: number }>;
+  /** 1.12: how much went without a person. */
+  automation: {
+    /** Of the requirements that reached testing (or completion) in the period, the share with no stop other than the necessary ones. */
+    unattendedShare: number | null;
+    /** Problems the pipeline handled by itself in the period's runs, by kind. */
+    recovered: Record<string, number>;
+    /** Runs that ended in an interruption (not a necessary decision). */
+    interrupted: number;
+    /** recovered / (recovered + interrupted). */
+    autoRecoveryShare: number | null;
+  };
   /** Requirements that started from cards, by who asked for them (1.10); empty when there are none. */
   byRequester: Array<{ requester: string; requirements: number; completed: number; medianCycleHours: number | null }>;
   requirements: RequirementStats[];
@@ -257,6 +299,24 @@ export function summarizeRuns(all: RunRecord[], period: Period): StatsSummary {
   const requesters = new Map<string, RequirementStats[]>();
   for (const q of active) if (q.card) requesters.set(q.requester ?? "（未记录）", [...(requesters.get(q.requester ?? "（未记录）") ?? []), q]);
 
+  const stopCounts = count(periodRuns.flatMap((r) => (stopKindOf(r) ? [stopKindOf(r)!] : [])));
+  const recovered: Record<string, number> = {};
+  for (const r of periodRuns) for (const [k, v] of Object.entries(r.run.recoveries ?? {})) recovered[k] = (recovered[k] ?? 0) + v;
+  const recoveredTotal = Object.values(recovered).reduce((a, b) => a + b, 0);
+  const interrupted = periodRuns.filter((r) => {
+    const k = stopKindOf(r);
+    return k !== null && !NECESSARY_STOPS.includes(k) && k !== "business" && k !== "reproduce";
+  }).length;
+  const reachedTesting = active.filter((q) => q.status === "completed" || q.status === "phase_done");
+  const unattended = reachedTesting.filter((q) =>
+    runs
+      .filter((r) => r.requirement.key === q.key && r.requirement.project === q.project)
+      .every((r) => {
+        const k = stopKindOf(r);
+        return k === null || NECESSARY_STOPS.includes(k);
+      }),
+  );
+
   return {
     schema: 1,
     period: { from: period.from?.toISOString() ?? null, to: period.to?.toISOString() ?? null, label: period.label },
@@ -287,6 +347,15 @@ export function summarizeRuns(all: RunRecord[], period: Period): StatsSummary {
       averageReviewRounds: avg(qs.map((q) => q.reviewRounds)),
       averageCostUsd: avg(qs.flatMap((q) => (q.costUsd === null ? [] : [q.costUsd]))),
     })),
+    stops: Object.entries(stopCounts)
+      .map(([kind, n]) => ({ kind, label: STOP_LABELS[kind] ?? kind, necessary: NECESSARY_STOPS.includes(kind), runs: n }))
+      .sort((a, b) => b.runs - a.runs || a.kind.localeCompare(b.kind)),
+    automation: {
+      unattendedShare: reachedTesting.length === 0 ? null : Math.round((unattended.length / reachedTesting.length) * 100) / 100,
+      recovered,
+      interrupted,
+      autoRecoveryShare: recoveredTotal + interrupted === 0 ? null : Math.round((recoveredTotal / (recoveredTotal + interrupted)) * 100) / 100,
+    },
     byRequester: [...requesters.entries()]
       .map(([requester, qs]) => {
         const finished = qs.filter((q) => done.includes(q));
@@ -349,6 +418,27 @@ export function describeStats(s: StatsSummary): string {
     `- 需要缺陷修复的需求占比：${s.rework.withDefectRounds === null ? "无数据" : `${Math.round(s.rework.withDefectRounds * 100)}%`}`,
     `- 质量门：运行 ${s.rework.gateRuns} 次，其中发现新失败 ${s.rework.gateFailed} 次`,
   );
+  const RECOVERY_LABELS: Record<string, string> = {
+    retry: "临时错误重试",
+    reattach: "接着等还在做的 agent",
+    reuse_result: "沿用旧 agent 的结果",
+    extend_timeout: "超时后多等一轮",
+    redo: "新开 agent 重做",
+    fallback: "换备用模型",
+    auto_resume: "自动继续",
+    quota_wait: "等额度恢复后继续",
+  };
+  lines.push(
+    "",
+    "## 人工介入",
+    "",
+    `- 到达提测（或完成）的需求中，除了确认方案外没有停下等人的：${s.automation.unattendedShare === null ? "无数据" : `${Math.round(s.automation.unattendedShare * 100)}%`}`,
+    `- 自动处理的问题 ${Object.values(s.automation.recovered).reduce((a, b) => a + b, 0)} 次（${list(s.automation.recovered, RECOVERY_LABELS)}），中断等人 ${s.automation.interrupted} 次${s.automation.autoRecoveryShare === null ? "" : `，自动处理的比例 ${Math.round(s.automation.autoRecoveryShare * 100)}%`}`,
+  );
+  if (s.stops.length > 0) {
+    lines.push("", "| 停下等人的原因 | 次数 | 必要的决定 |", "| --- | --- | --- |");
+    for (const st of s.stops) lines.push(`| ${st.label} | ${st.runs} | ${st.necessary ? "是" : "否"} |`);
+  }
   if (s.waits.length > 0) {
     lines.push("", "## 等待", "", "| 等待 | 需求数 | 平均 |", "| --- | --- | --- |");
     for (const w of s.waits) lines.push(`| ${w.label} | ${w.requirements} | ${hours(w.averageMinutes)} |`);