fix(workflow): 交付前复查分支并等待活跃写入报告

- 在查询 PR 后重新读取远端分支，在创建门禁内核对已记录提交；分支变化时交给后续轮询重新检查受保护文件。
- 共享分支仍有可写租约时继续等待报告，清除无人报告轮询计数，避免三次轮询误判交付失败。
- 新增查询期间已报告与未报告分支变化、连续六次轮询回归，修改前均失败；225 项相关单测、4 项 CLI 交付 E2E、构建、类型检查和 lint 通过。
- 保留维护者 efdaf68 的交付重构，仅作为独立交接提交提供，不更新维护者接管的 PR 分支。

Author: nateEc

docs/guide/workflow.md

@@ -236,6 +236,8 @@ A `deliver: pr` step that would run read-only fails validation, and so does a de
 
 When the step succeeds, its driver has already pushed the branch, as for any writable step, and the step is `delivering`. Steps that need it wait. The next `teamai workflow next`, from whichever driver calls it, looks for an open pull request from that branch into its target, and opens one only when there is none. A run that a crash stopped finds the pull request it opened before and opens no other. So does a run another machine took over, unless the machine that handed it over is still opening one at that moment. GitHub and GitLab reject such a duplicate. TeamAI opens pull requests on GitHub, GitLab, TGit, and GitCode origins, with the login the provider's CLI or token already has, and never starts a login prompt. On any other origin, such as a generic git host or CNB, it opens none, and the step fails naming its branch.
 
+If a sibling advances the shared branch while lookup is pending, TeamAI checks its new recorded tip on a later poll before opening a pull request. A pushed commit still awaiting an active writer's report keeps delivery pending.
+
 A pull request goes into the nearest branch its own branch grew from that already delivered one, or else into the branch the run started from. A branch grows first from its `for_each` item's `after` branches, then from its `needs` in order. The first step of a sub-workflow grows from the needs of the step that runs it. A skipped step wrote no branch, so it is passed over. Each pull request then shows only the work done since the branch it goes into.
 
 Each pass of a looped `workspace: new` step has its own `/p<pass>` branch, so it opens its own pull request. The earlier ones stay open, by design. A step that loops on one `continue` branch has one pull request.

docs/guide/zh-CN/workflow.md

@@ -236,6 +236,8 @@ steps:
 
 步骤成功时，驱动已经像对任何可写步骤一样推送了分支，步骤进入 `delivering` 状态，需要它的步骤会等待。下一次 `teamai workflow next`（无论哪个驱动调用）会查找从这条分支合入目标分支的已打开 pull request，没有时才新开一个。因崩溃而中断的运行，会找到之前开的 pull request，不会再开第二个。被另一台机器接管的运行也是如此，除非交出运行的机器此刻仍在开 pull request；GitHub 和 GitLab 会拒绝这样的重复请求。TeamAI 在 GitHub、GitLab、TGit 和 GitCode 的 origin 上开 pull request，使用 provider 的 CLI 或 token 已有的登录，从不弹出登录提示。在其他 origin 上（例如通用 Git 主机或 CNB），它不开 pull request，步骤失败并写明分支。
 
+如果同一分支上的另一步骤在查询期间推进分支，TeamAI 会在后续轮询中检查新记录的提交后再创建 pull request。已推送但仍在等待活跃写入步骤报告的提交会保持待交付状态。
+
 pull request 合入这条分支来源中最近一条已经交付过的分支，没有时合入运行开始时的分支。分支首先来自其 `for_each` item 的 `after` 分支，然后依次来自 `needs`。子工作流的第一个步骤来自运行它的步骤的 needs。跳过的步骤没有写分支，会被越过。因此每个 pull request 只显示它所合入的分支之后的工作。
 
 循环中 `workspace: new` 步骤的每个 pass 都有自己的 `/p<pass>` 分支，因此各开一个 pull request。之前的 pull request 保持打开，这是有意为之。在同一条 `continue` 分支上循环的步骤只有一个 pull request。

src/__tests__/workflow-delivery.test.ts

@@ -1054,6 +1054,31 @@ describe('retrying and cancelling a delivery', () => {
     expect(creates(gh)).toEqual([]);
   });
 
+  it.each([true, false])('rechecks a shared branch changed during lookup before creation (reported: %s)', async (reported) => {
+    const { config, root, runId } = await fixture(IMPL_AND_DOCS);
+    const impl = await take(config, runId);
+    await succeed(config, runId, impl, { to: pushWork(root, impl) });
+    const lock = deliveryLockPath(config, runId);
+    expect(await acquireLock(lock)).toBe(true);
+    const docs = await take(config, runId);
+    await releaseLock(lock);
+    let changed = false;
+    const create = providerDouble(async () => {
+      if (!changed) {
+        changed = true;
+        const to = pushOnto(root, docs.workspace!.branch, { '.github/workflows/ci.yml': 'on: push' });
+        if (reported) await succeed(config, runId, docs, { to });
+      }
+      return undefined;
+    }, async () => 'https://github.com/fixture/app/pull/1');
+    await leaseNext(config, runId, remote, { ...writable, running: [docs.attempt] });
+    expect(create).not.toHaveBeenCalled();
+    if (reported) {
+      await leaseNext(config, runId, remote, writable);
+      expect((await state(config, runId)).steps.find(step => step.id === 'work.impl')).toMatchObject({ status: 'failed', failure: { message: expect.stringContaining('protected paths') } });
+    }
+  });
+
   it('keeps a step delivering while origin\'s branch is ahead of what the run recorded, and delivers it once a report records that commit', async () => {
     const { config, root, runId } = await fixture(IMPL_AND_DOCS);
     const gh = fakeGh(path.join(root, 'gh'));
@@ -1066,7 +1091,9 @@ describe('retrying and cancelling a delivery', () => {
     const branch = docs.workspace?.branch ?? '';
     const ahead = pushOnto(root, branch, { 'docs.txt': 'docs' });
 
-    expect(await leaseNext(config, runId, remote, { ...writable, running: [docs.attempt] })).toMatchObject({ data: { wait: { delivering: ['work.impl'] } } });
+    for (let poll = 0; poll < 6; poll += 1) {
+      expect(await leaseNext(config, runId, remote, { ...writable, running: [docs.attempt] })).toMatchObject({ data: { wait: { delivering: ['work.impl'] } } });
+    }
     expect(creates(gh)).toEqual([]);
     await succeed(config, runId, docs, { to: ahead });
     expect(await leaseNext(config, runId, remote, writable)).toMatchObject({ data: { done: { outcome: 'succeeded' } } });

src/workflow/delivery-ledger.ts

@@ -81,26 +81,30 @@ function recordReceipt(run: RunState, key: DeliveryKey, target: string, url: PrU
  * while origin's branch is ahead of the recorded commit and a report of it may still come.
  * `requeueEnd` is set when the receipt reached a run that already ended, whose end record must go out again to list it.
  */
-export function completeDelivery(run: RunState, job: DeliveryJob, outcome: DeliveryOutcome, reconcile: (run: RunState) => unknown): { requeueEnd: boolean } {
+export function completeDelivery(run: RunState, job: DeliveryJob, outcome: DeliveryOutcome, reconcile: (run: RunState) => unknown, hasActiveWriter = false): { requeueEnd: boolean } {
   const receipted = outcome.ok && recordReceipt(run, job.key, job.target, outcome.pr);
   if (outcome.ok) forgetCreate(run, { ...job.key, target: job.target });
   if (run.status === 'running') reconcile(run);
   const step = deliveringStep(run, job.key);
   if (step && outcome.ok) delivered(step);
-  else if (step && !outcome.ok && !(outcome.fault.kind === 'branch_ahead' && awaitsReport(step, outcome.fault.tip))) {
+  else if (step && !outcome.ok && !(outcome.fault.kind === 'branch_ahead' && awaitsReport(step, outcome.fault.tip, hasActiveWriter))) {
     deliveryFailed(step, deliveryFailure(job, outcome.fault));
   }
   return { requeueEnd: receipted && run.status !== 'running' };
 }
 
-/** How many drains in a row may find origin's branch ahead of the recorded commit, at one commit, before delivery fails. */
+/** How many drains without an active writer in a row may find origin's branch ahead of the recorded commit, at one commit, before delivery fails. */
 const AHEAD_DRAINS = 3;
 
 /**
  * Whether `step` still waits for a report of `tip`, the commit origin's branch is ahead at: one may be on its way, from a
- * step of the same branch that pushed before it reported. The drain that finds it there a third time fails the step.
+ * step of the same branch that pushed before it reported. Without an active writer, the drain that finds it there a third time fails the step.
  */
-function awaitsReport(step: DeliveringStep, tip: string): boolean {
+function awaitsReport(step: DeliveringStep, tip: string, hasActiveWriter: boolean): boolean {
+  if (hasActiveWriter) {
+    delete step.unrecordedTip;
+    return true;
+  }
   const drains = step.unrecordedTip?.commit === tip ? step.unrecordedTip.drains + 1 : 1;
   if (drains >= AHEAD_DRAINS) return false;
   step.unrecordedTip = { commit: tip, drains };

src/workflow/engine.ts

@@ -889,11 +889,13 @@ export interface NextOptions {
  * is looked up, whatever becomes of the step, rather than lost.
  */
 async function markCreating(config: LocalConfig, runId: string, job: DeliveryJob): Promise<'open' | 'refused' | 'busy'> {
-  const marked = await updateRun(config, runId, async (run): Promise<{ value: 'open' | 'refused'; write?: RunState }> => {
+  const marked = await updateRun(config, runId, async (run): Promise<{ value: 'open' | 'refused' | 'busy'; write?: RunState }> => {
     if (run === 'missing' || run.status !== 'running') return { value: 'refused' };
     const settledRun = reconcileRun(run);
     const step = 'unreadable' in settledRun || 'outcome' in settledRun ? undefined : deliveringStep(run, job.key);
     if (!step) return { value: 'refused' };
+    // A report may have advanced this shared branch while the provider lookup was pending.
+    if (run.copies?.[job.key.branch]?.commit !== job.recordedHead) return { value: 'busy' };
     const create = { ...job.key, target: job.target };
     const listed = run.creating?.find((item) => sameCreate(item, create));
     // A request listed before is asked again now, so its lookups count from this create.
@@ -938,7 +940,13 @@ async function drainDeliveries(config: LocalConfig, runId: string): Promise<void
         // As when the pick is busy: the step still delivers, and a later call delivers it.
         if (outcome === 'busy') return requeued;
         if (!outcome.ok && outcome.fault.kind === 'branch_ahead') waiting.push(job.key);
-        apply = (run) => completeDelivery(run, job, outcome, reconcileRun);
+        apply = (run) => completeDelivery(run, job, outcome, reconcileRun, run.steps.some((step) => {
+          if (step.status !== 'leased') return false;
+          const located = locateStep(run, step.id);
+          if (!located) return false;
+          const plan = planWorkspace(run, located.scope, step, located.step, { driver: step.lease.driver, base: run.base }, true);
+          return plan.mode !== 'read-only' && plan.contract?.branch === job.key.branch;
+        }));
       } else {
         const { create, checkout } = picked.value;
         tried.push(create);

src/workflow/pr-delivery.ts

@@ -106,9 +106,13 @@ export async function deliverPr(job: DeliveryJob, gate: CreateGate): Promise<Del
   const { provider, repo } = origin;
   const ref: PullRequestRef = { repo, source: job.key.branch, target: job.target, timeoutMs: DELIVERY_TIMEOUT_MS };
   const found = await findOpen(origin, ref);
-  if (found.kind === 'found') return { ok: true, pr: found.pr };
   if (found.kind === 'failed') return failed({ kind: 'lookup_failed', provider: provider.name });
   if (found.kind === 'unsafe') return failed({ kind: 'unsafe_url', provider: provider.name });
+  // Lookup can take long enough for a sibling to push. Re-pick and check the new tip on a later drain.
+  const latest = await originTip(job.checkout, job.key.branch);
+  if (latest.kind === 'unreadable') return failed({ kind: 'branch_unreadable' });
+  if (latest.commit !== tip.commit) return 'busy';
+  if (found.kind === 'found') return { ok: true, pr: found.pr };
   const gated = await gate();
   if (gated === 'busy') return 'busy';
   if (gated === 'refused') return failed({ kind: 'withdrawn' });