paseo-req-kit 1.11.0 → 1.12.0-beta.3

package/engine/src/paseo-profiles.ts

@@ -93,6 +93,7 @@ export function usesPaseoProfiles(config: PipelineConfig): boolean {
   return [
     config.agents.builder,
     config.agents.reviewer,
+    ...(config.agents.fallback ? [config.agents.fallback] : []),
     ...config.reviewPanel.members,
     ...config.designProposals.members,
     ...Object.values(config.phases.verify.agents),
@@ -108,6 +109,7 @@ export function resolveConfigProfiles(config: PipelineConfig, available: PaseoPr
     agents: {
       builder: resolveAgentProfile("agents.builder", config.agents.builder, available),
       reviewer: resolveAgentProfile("agents.reviewer", config.agents.reviewer, available),
+      ...(config.agents.fallback ? { fallback: resolveAgentProfile("agents.fallback", config.agents.fallback, available) } : {}),
     },
     reviewPanel: {
       ...config.reviewPanel,

package/engine/src/paseo-runtime.ts

@@ -352,6 +352,15 @@ export function createRuntimeWithClient(
       const api = await getScripts();
       if (api) await api.deleteSchedule(id);
     },
+    async providerStatus() {
+      if (!client.providers) return null;
+      try {
+        const snapshot = await client.providers.waitForReady({ timeoutMs: 15_000 });
+        return snapshot.entries.map((e) => ({ provider: e.provider, status: e.status }));
+      } catch {
+        return null;
+      }
+    },
     async capabilities() {
       if (!client.config) return null;
       try {

package/engine/src/pipeline.ts

@@ -32,12 +32,12 @@ import {
 } from "./messages.js";
 import { kitVersion } from "./locations.js";
 import { type AgentUsage, describeTotals, totals } from "./usage.js";
-import { dispatchNotifiers, type NotifierEventType } from "./notifiers.js";
-import { describeExternal, type IntegrationEvent, type Runner, syncIntegration } from "./integrations.js";
+import { dispatchNotifiers, type NotifierEventType, peopleOf } from "./notifiers.js";
+import { describeExternal, type IntegrationEvent, renderArgs, resolveCommand, 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, WaitOutcome } from "./runtime.js";
-import { type CheckOutcome, type GateRun, type JointRepo, type PhaseName, type PipelineState, type RunPhases, type StepRecord, writeState } from "./state.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 {
@@ -125,7 +125,38 @@ class StepFailure extends Error {
 }
 
 /** The step gave up on its agent while the agent may still be working (1.11). */
-class AgentLeftRunning extends StepFailure {}
+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,
@@ -386,6 +417,10 @@ async function notifyExternal(ctx: PipelineContext, type: NotifierEventType, tex
       originAgentId: ctx.state.originAgentId,
       text,
       details,
+      people: (() => {
+        const source = readSource(ctx.repo, ctx.featureDir);
+        return peopleOf(type, source?.author ?? null, source ? { system: source.system, id: source.id, url: source.url } : null, ctx.config.people);
+      })(),
     },
     ctx.log,
   );
@@ -438,16 +473,67 @@ function pushBranch(ctx: PipelineContext): void {
       const stderr = (e as { stderr?: Buffer | string }).stderr?.toString().trim();
       error = (stderr || (e as Error).message).split("\n").filter(Boolean).slice(-2).join(" ");
     }
-    ctx.state.pushed = [...(ctx.state.pushed ?? []).filter((p) => p.repo !== repo), { repo, remote: push.remote, branch, at, error }];
+    const before = ctx.state.pushed?.find((p) => p.repo === repo);
     ctx.log(error ? `推送 ${repo} 的分支到 ${push.remote}/${branch} 失败：${error}` : `已推送 ${repo} 的分支到 ${push.remote}/${branch}`);
+    // A merge request is made once; later pushes (after testing sent defects back) update it by themselves.
+    const mergeRequest = !error && push.mergeRequest && !before?.mergeRequest?.url ? makeMergeRequest(ctx, repo, branch, source) : (before?.mergeRequest ?? null);
+    ctx.state.pushed = [...(ctx.state.pushed ?? []).filter((p) => p.repo !== repo), { repo, remote: push.remote, branch, at, error, mergeRequest }];
   }
   save(ctx);
 }
 
+/** The remote's default branch (origin/HEAD), for the merge request's target; main when unknown. */
+function defaultBranch(repo: string, remote: string): string {
+  try {
+    const ref = execFileSync("git", ["symbolic-ref", "--short", `refs/remotes/${remote}/HEAD`], { cwd: repo, stdio: ["ignore", "pipe", "ignore"], windowsHide: true }).toString().trim();
+    return ref.startsWith(`${remote}/`) ? ref.slice(remote.length + 1) : ref || "main";
+  } catch {
+    return "main";
+  }
+}
+
+/**
+ * 1.12: a draft merge request for the pushed branch, with the machine's own command (push.mergeRequest).
+ * Its description is the handoff note and the card. Never merged here. Never throws.
+ */
+function makeMergeRequest(ctx: PipelineContext, repo: string, branch: string, source: NonNullable<ReturnType<typeof readSource>>): { url: string | null; at: string; error: string | null } {
+  const mr = ctx.config.push.mergeRequest!;
+  const at = new Date().toISOString();
+  const handoff = path.join(repo, ctx.featureDir, "handoff.md");
+  const note = fs.existsSync(handoff) ? fs.readFileSync(handoff, "utf8").trim() : "";
+  const cardLine = `需求卡片：${source.system} ${source.id}${source.url ? ` ${source.url}` : ""}`;
+  const values: Record<string, string> = {
+    branch,
+    target: mr.target || defaultBranch(repo, ctx.config.push.remote),
+    title: `[${source.id}] ${specTitle(ctx)}`,
+    description: [`> 由 req-kit 在研发完成后创建的草稿，合并前请人工评审。`, "", cardLine, "", note.slice(0, 20_000)].join("\n"),
+    card: source.id,
+    cardUrl: source.url ?? "",
+  };
+  try {
+    const { file, prefix } = resolveCommand(mr.command);
+    const output = execFileSync(file, [...prefix, ...renderArgs(mr.args, values)], {
+      cwd: repo,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: (mr.timeoutSeconds ?? 60) * 1000,
+      windowsHide: true,
+    }).toString();
+    const url = /https?:\/\/\S+/.exec(output)?.[0]?.replace(/[)。，,.]+$/, "") ?? null;
+    ctx.log(`已为 ${branch} 建草稿合并请求${url ? `：${url}` : "（输出中没有找到地址）"}`);
+    return { url, at, error: null };
+  } catch (e) {
+    const stderr = (e as { stderr?: Buffer | string }).stderr?.toString().trim();
+    const error = (stderr || (e as Error).message).split("\n").filter(Boolean).slice(-2).join(" ").slice(0, 300);
+    ctx.log(`为 ${branch} 建合并请求失败：${error}。分支已推送，可以手工建`);
+    return { url: null, at, error };
+  }
+}
+
 /** Where the requirement's code is, for the card: the pushed branch, or the local one. */
 function branchText(ctx: PipelineContext): string | null {
   const mine = ctx.state.pushed?.find((p) => p.repo === ctx.repo);
-  if (mine) return mine.error ? `分支 ${ctx.state.branch}（推送到 ${mine.remote}/${mine.branch} 失败：${mine.error}）` : `代码已推送到 ${mine.remote} 的分支 ${mine.branch}`;
+  if (mine?.error) return `分支 ${ctx.state.branch}（推送到 ${mine.remote}/${mine.branch} 失败：${mine.error}）`;
+  if (mine) return `代码已推送到 ${mine.remote} 的分支 ${mine.branch}${mine.mergeRequest?.url ? `，草稿合并请求 ${mine.mergeRequest.url}` : ""}`;
   return ctx.state.branch ? `分支 ${ctx.state.branch}` : null;
 }
 
@@ -487,15 +573,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) {
+      const total = ctx.config.stepTimeoutMinutes[def.id] * (deadline.extended ? 2 : 1);
       throw new AgentLeftRunning(
         def.title,
-        `超过 ${ctx.config.stepTimeoutMinutes[def.id]} 分钟仍未完成。agent「${agentTitle}」还在运行，没有停止它；继续时会先看它的情况：做完了就用它的结果，还在做就接着等它，不会另起一个 agent 重复做。`,
+        `超过 ${total} 分钟仍未完成。agent「${agentTitle}」还在运行，没有停止它；继续时会先看它的情况：做完了就用它的结果，还在做就接着等它，不会另起一个 agent 重复做。`,
+        true,
       );
     }
     let outcome;
@@ -506,7 +608,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 AgentLeftRunning(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;
@@ -517,7 +619,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) {
@@ -562,31 +664,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,
@@ -671,7 +805,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) {
@@ -683,7 +817,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) {
@@ -761,7 +895,7 @@ async function checkLeftover(
       last.result = validation.value;
       ctx.state.results[key] = validation.value;
       save(ctx);
-      ctx.log(`${key} 上一次的 agent ${last.agentId} 已经做完，沿用它的结果：${JSON.stringify(validation.value)}`);
+      recover(ctx, key, "reuse_result", `上一次的 agent ${last.agentId} 已经做完，沿用它的结果`);
       if (ctx.config.archiveStepAgents) await agent.archive().catch(() => undefined);
       return { done: validation.value };
     }
@@ -769,7 +903,10 @@ async function checkLeftover(
     return {};
   }
   if (status === "timeout" || status === "permission") {
-    if ((last.reattached ?? 0) < 1) return { agent, reattached: (last.reattached ?? 0) + 1 };
+    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 重做。请立即停止当前工作，不要再修改任何文件，也不要写结果文件，直接结束。")
@@ -1023,6 +1160,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;
@@ -1032,7 +1189,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,
@@ -1049,7 +1207,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}`);
@@ -1080,7 +1240,7 @@ async function checkQuota(ctx: PipelineContext): Promise<void> {
     [
       "【需求开发流水线通知】这条消息来自后台流水线，不是用户发的。",
       `额度提醒：${items.join("；")}。`,
-      "流水线照常进行；额度用完时会遇到限流，流水线会自动等待重试，重试用完会中断，之后可以继续。如果希望等额度恢复后再开发，请转告用户，用户同意的话可以先暂停。",
+      `流水线照常进行；额度用完时会遇到限流，流水线会先重试${ctx.config.agents.fallback ? "、再换备用模型" : ""}，仍不行就预约在额度恢复后自动继续，不需要人处理。如果希望等额度恢复后再开发，请转告用户，用户同意的话可以先暂停，再预约在恢复时间开始。`,
     ].join("\n"),
   );
 }
@@ -1567,11 +1727,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;
@@ -1602,7 +1784,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);
@@ -1876,6 +2061,8 @@ 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;
+  ctx.state.pendingQuestions = null;
   save(ctx);
   await integrate(ctx, phaseOf(ctx) === "verify" ? "verify" : "started");
   try {
@@ -1917,6 +2104,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);
@@ -1947,6 +2135,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");
@@ -1974,6 +2163,8 @@ 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.pendingQuestions = error.questions;
       ctx.state.stopReason = `${reproduce ? "没能复现缺陷，需要需求方补充信息" : "方案审核需要需求方决定"}：${error.questions.join("；")}`;
       save(ctx);
       const reminderHours = await scheduleReminder(ctx, error.questions);
@@ -1994,6 +2185,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/reply.ts

@@ -0,0 +1,59 @@
+// `req reply <需求> <回复>` (1.12): passes an answer written in the plugin's inbox to the
+// requirement's chat, which handles it as if the user had typed it there. Nothing else changes:
+// the chat updates the requirement and continues the pipeline itself.
+import { locate } from "./api.js";
+import { DEFAULT_CONFIG, loadConfig, type PipelineConfig } from "./config.js";
+import { defaultConfigPath } from "./locations.js";
+import { pluginReplyMessage } from "./messages.js";
+import { loadRuntimeFactory } from "./runtime-loader.js";
+import { readState, statePath } from "./state.js";
+
+async function main(argv: string[]): Promise<number> {
+  const [feature, ...words] = argv;
+  const text = words.join(" ").trim();
+  if (!feature || !text) {
+    console.error("用法：req reply <需求> <回复内容>");
+    return 2;
+  }
+  const { repo, featureDir } = locate(process.cwd(), feature);
+  const state = readState(statePath(repo, featureDir));
+  if (!state || (state.status !== "waiting_for_business" && state.status !== "waiting_for_approval")) {
+    console.error(`${featureDir} 现在没有在等待回答或确认，不用回复。`);
+    return 1;
+  }
+  if (!state.originAgentId) {
+    console.error("这个需求不是从 Paseo 对话中开始的，没有可以转达的对话。请在终端或卡片中处理。");
+    return 1;
+  }
+  let config: PipelineConfig;
+  try {
+    config = loadConfig(defaultConfigPath(), repo).config;
+  } catch {
+    // Only the daemon address is needed here.
+    config = DEFAULT_CONFIG;
+  }
+  const runtime = await (await loadRuntimeFactory())({ config, log: () => undefined });
+  try {
+    await runtime.notifyAgent(
+      state.originAgentId,
+      pluginReplyMessage({
+        featureDir,
+        waitingFor: state.status === "waiting_for_approval" ? "approval" : "business",
+        text: text.slice(0, 8000),
+        questions: state.pendingQuestions ?? [],
+      }),
+    );
+  } finally {
+    await runtime.close().catch(() => undefined);
+  }
+  console.log("已转给这个需求的对话，它会按回复更新需求说明并继续开发。");
+  return 0;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (error: Error) => {
+    console.error(`没有转达：${error.message}`);
+    process.exit(1);
+  },
+);

package/engine/src/runtime.ts

@@ -143,6 +143,8 @@ export interface AgentRuntime {
   recentActivity(agentId: string, limit: number): Promise<ActivityItem[] | null>;
   /** Which Paseo tools step agents get (Settings → Agents); null when unknown. */
   capabilities(): Promise<{ paseoTools: boolean; browser: boolean } | null>;
+  /** 1.12: whether each agent provider is installed and logged in ("ready"); null when the daemon does not say. */
+  providerStatus(): Promise<Array<{ provider: string; status: string }> | null>;
   /**
    * Paseo schedule that sends `prompt` into an existing agent's conversation (the chat):
    * once at `at`, or on `cron` (5 fields, local time zone). Returns the schedule ID, or

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;
@@ -69,6 +95,12 @@ 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[];
+  /** 1.12: the questions a run waiting for the requester (waiting_for_business) asks; cleared when it runs again. */
+  pendingQuestions?: string[] | null;
   outcome: string | null;
   /** "quick" or "standard"; decides loop rounds and optional steps. */
   profile: ProfileName;
@@ -120,7 +152,15 @@ export interface PipelineState {
    * Branches pushed for a requirement that started from a card (1.10, `push` config): one entry
    * per repository (the main one, then joint ones), the latest attempt. `error` is null when it worked.
    */
-  pushed?: Array<{ repo: string; remote: string; branch: string; at: string; error: string | null }> | null;
+  pushed?: Array<{
+    repo: string;
+    remote: string;
+    branch: string;
+    at: string;
+    error: string | null;
+    /** 1.12: the draft merge request made after the push (push.mergeRequest); made once per repository. */
+    mergeRequest?: { url: string | null; at: string; error: string | null } | null;
+  }> | null;
 }
 
 export interface JointRepo {