@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/execution/ui-request-handler-factory.ts

@@ -20,7 +20,13 @@
 
 import { getLogger } from "../core/logger.ts";
 
-import { DialogGlobalQueue, type UiRequest, type UiRequestHandler, type UiResponse } from "./dialog-queue.ts";
+import {
+  DialogGlobalQueue,
+  isValidDialogTimeout,
+  type UiRequest,
+  type UiRequestHandler,
+  type UiResponse,
+} from "./dialog-queue.ts";
 import { type HostMode, resolveHostMode } from "./host-mode.ts";
 import type { UiChannelRegistry } from "./ui-channels.ts";
 import { isDialogMethod } from "./ui-interaction-model.ts";
@@ -157,10 +163,27 @@ function coerceUiResponse(raw: unknown, reqId: string): UiResponse {
  *    input(title: string, placeholder?: string, opts?): Promise<string | undefined>
  *    editor(title: string, prefill?: string): Promise<string | undefined>
  *  注意：SDK 是位置参数（非对象参数）；返回 undefined 表示用户取消。
+ *  opts 为 ExtensionUIDialogOptions（signal?/timeout?，timeout 毫秒，SDK auto-dismiss
+ *  带倒计时展示）——LC-3/T2⑦ 协同：请求方显式传 timeout 时透传给 SDK，SDK 层超时
+ *  （正常路径，用户可见倒计时）先于队列级兜底 settle；队列级上界（dialog-queue，
+ *  未传挂 30min 默认）兜住 SDK timeout 未生效的形态（host 实现不完整 / channel handler
+ *  路径不经 SDK）。两层取先到，settle 恰一次由 DialogGlobalQueue 的 settled 标志保证。
+ *  editor 的 SDK 签名无 opts，不透传（其上界只由队列级兜底承担）。
  *
  *  Stage 4 风险点：TUI 下 ask_user channel 未注册时，select 会以普通列表渲染
  *  （title 可能含 marker）。channel 注册后由 createRealHandler 优先走 channel handler，
  *  不进这里。editor 不可用/抛错时降级 cancelled + warn，不卡队列。 */
+/** select/confirm/input 的 SDK 第三参（opts）：请求方传了**合法** timeout（>0 且有限，
+ *  判定源 = dialog-queue 的 isValidDialogTimeout，与队列层上界同一权威）才透传——
+ *  未传或非法（0/负数/NaN/±Infinity）时不加第三参，参数个数与旧调用完全一致（严格
+ *  additive）。非法值透传会让 SDK 收到语义反转的 opts（<=0 可能立即 auto-dismiss），
+ *  且与队列层「非法回落默认上界」的判定不一致（A2-3）；不透传时数组为空，SDK 无界
+ *  由队列层默认上界（30min）兜底。
+ *  返回元组联合以支持 spread 到固定签名（TS2556）。 */
+function sdkTimeoutArg(req: UiRequest): [] | [{ timeout: number }] {
+  return isValidDialogTimeout(req.timeout) ? [{ timeout: req.timeout }] : [];
+}
+
 async function defaultDialogForward(
   req: UiRequest,
   ctx: HostUIContext,
@@ -168,16 +191,16 @@ async function defaultDialogForward(
   const ui = ctx.ui;
   switch (req.method) {
     case "select": {
-      const selected = await ui.select(req.title ?? "", req.options ?? []);
+      const selected = await ui.select(req.title ?? "", req.options ?? [], ...sdkTimeoutArg(req));
       return selected === undefined ? { cancelled: true } : { value: selected };
     }
     case "confirm": {
       // SDK confirm 必传 message（req.message 缺失时降级空串，不报错阻塞）
-      const confirmed = await ui.confirm(req.title ?? "", req.message ?? "");
+      const confirmed = await ui.confirm(req.title ?? "", req.message ?? "", ...sdkTimeoutArg(req));
       return { confirmed };
     }
     case "input": {
-      const text = await ui.input(req.title ?? "", req.placeholder);
+      const text = await ui.input(req.title ?? "", req.placeholder, ...sdkTimeoutArg(req));
       return text === undefined ? { cancelled: true } : { value: text };
     }
     case "editor": {

package/src/execution/worktree-git-ops.ts

@@ -0,0 +1,397 @@
+// src/execution/worktree-git-ops.ts
+//
+// worktree git 内核纯函数（sink 设计 U5 / D5 裁决全量）。
+// 设计权威源：docs/design/subagent-core-sink-design.md §3.3 D5 + 错误规格表
+// collectWorktreePatch 两行 + §5.4 ⛔3。
+//
+// 提取源：execution/worktree-manager.ts（gitRunAsync / GitRunError / SAFE_ID_RE /
+// collectPatch 的 add+diff 基线机制 / cleanup 三步容错 / create 的脏树校验）。
+// 本模块是 git 语义新单源；worktree-manager.ts 的同语义内联实现待其收缩单元切换
+// 消费（本单元领地约束不改提取源，两处短暂并存由各自测试锚定等价）。
+//
+// [D5 基线锚点抽象] collectWorktreePatch 的基线二选一注入：
+//   - { kind: "commit" }      内存 baseCommit（core WorktreeHandle.baseCommit，本就
+//     持久化于 worktrees.json 注册表——worktree-manager.ts create() 注册路径）
+//   - { kind: "anchor-file" } 宿主持久锚点文件（zsw sidecar 语义，内容 = base commit）
+//
+// [⛔3 两条降级路径显式化]（不做 fail-fast——任务已完成的执行工作不应因 patch
+// 收集作废；也不做纯静默——静默丢已提交改动使上层拿到残缺 patch 无法察觉）：
+//   ① 锚点缺失/损坏 → 显著 warn + 降级裸 diff（仅未提交改动）+ patchIncomplete: true
+//   ② add 步骤失败 → 非致命继续 diff（裸 diff）+ warn + patchIncomplete: true
+// 降级裸 diff 以 HEAD 为基线：较 zsw 现状 `diff <base>` 多丢已提交改动，损失面差异
+// 由 patchIncomplete 留痕判断（D5 原文裁决，非等值平移）。
+//
+// 目录布局与孤儿判定策略留宿主（D5）；per-repo 写命令串行队列是宿主/manager 编排
+// 职责，不在纯内核复刻——git index.lock 冲突瞬时态正好落降级路径②，而非内核故障。
+
+import { execFile } from "node:child_process";
+import * as fs from "node:fs";
+
+import { getLogger } from "../core/logger.ts";
+import { bestEffort } from "./best-effort.ts";
+import { DirtyWorktreeError } from "./types.ts";
+
+const logger = getLogger("subagents");
+
+// 默认 git 命令超时（ms），对齐提取源 worktree-manager.ts
+const GIT_TIMEOUT_MS = 30_000;
+
+/**
+ * gitRun 的包装错误：message 格式与提取源 gitRunAsync 逐字一致；exitCode/stderr/
+ * timedOut 为诊断属性（P-errshape 实测 Node 24：execFile 的 err.stderr 为
+ * undefined——stderr 在 callback 第三参；退出码在 err.code，数字时）。
+ */
+export class GitRunError extends Error {
+  readonly exitCode?: number;
+  readonly stderr?: string;
+  readonly timedOut?: boolean;
+
+  constructor(
+    message: string,
+    props: { exitCode?: number; stderr?: string; timedOut?: boolean },
+  ) {
+    super(message);
+    this.name = "GitRunError";
+    this.exitCode = props.exitCode;
+    this.stderr = props.stderr;
+    this.timedOut = props.timedOut;
+  }
+}
+
+// recordId 白名单：字母数字下划线短横线（防路径注入；与提取源 SAFE_ID_RE 同式）
+export const SAFE_ID_RE = /^[\w-]+$/;
+
+/** recordId 是否匹配安全白名单 `^[\w-]+$`。 */
+export function isSafeId(id: string): boolean {
+  return SAFE_ID_RE.test(id);
+}
+
+/**
+ * 断言 recordId 匹配安全白名单，不合法抛 DirtyWorktreeError（与提取源 create()
+ * 的拒绝语义一致，供 manager 收缩后无缝切换）。
+ *
+ * @throws DirtyWorktreeError（消息含白名单说明，可操作）
+ */
+export function assertSafeId(id: string, label = "recordId"): void {
+  if (!SAFE_ID_RE.test(id)) {
+    throw new DirtyWorktreeError(
+      `${label} contains unsafe characters: "${id}" (must match ^[\\w-]+$)`,
+    );
+  }
+}
+
+/**
+ * dirty 谓词：`git status --porcelain` 输出 trim 后非空即脏树。
+ * 提取源 create() 的内联判定（「消费点自行 trim」的干净文本消费点之一）。
+ */
+export function isTreeDirty(statusPorcelain: string): boolean {
+  return statusPorcelain.trim().length > 0;
+}
+
+/**
+ * git 命令执行器。stdout 保真返回（不 trim）：diff 输出原样落盘为 patch 文件，
+ * 裁掉尾换行会产出 `git apply` 拒绝的 corrupt patch（worktree-manager.ts 头注释
+ * 2026-08-16 门 4 实测）。需要干净文本的消费点自行 trim。
+ *
+ * maxBuffer（execFile stdout 上限）：不传 = Node execFile 缺省 1MB（1024 * 1024），
+ * 超限以 ERR_CHILD_PROCESS_STDIO_MAXBUFFER 失败（reject GitRunError）。大输出命令
+ * （如批量重构的大 diff）由调用方显式提高，宿主建议 32 * 1024 * 1024（对齐旧 zsw
+ * 宿主 GIT_MAX_BUFFER）。以条件展开实现而非 `maxBuffer: opts.maxBuffer` 直透：
+ * Node 先铺缺省再展开 options，显式 undefined 会覆盖缺省为无界（实测探针），
+ * 与「不传即 1MB 缺省」相悖。
+ *
+ * 失败 reject GitRunError。无 per-repo 写串行（编排职责留宿主，见文件头注释）。
+ */
+export function gitRun(
+  args: string[],
+  opts: { cwd: string; timeout?: number; maxBuffer?: number },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      "git",
+      args,
+      {
+        cwd: opts.cwd,
+        timeout: opts.timeout ?? GIT_TIMEOUT_MS,
+        ...(opts.maxBuffer !== undefined ? { maxBuffer: opts.maxBuffer } : {}),
+        encoding: "utf-8",
+      },
+      (err, stdout, stderr) => {
+        if (err) {
+          const execErr = err as Error & { code?: unknown; killed?: boolean; signal?: string };
+          reject(
+            new GitRunError(`git ${args[0]} failed: ${execErr.message}`, {
+              exitCode: typeof execErr.code === "number" ? execErr.code : undefined,
+              stderr: typeof stderr === "string" ? stderr : undefined,
+              timedOut: execErr.killed === true && execErr.signal === "SIGTERM",
+            }),
+          );
+          return;
+        }
+        resolve(stdout);
+      },
+    );
+  });
+}
+
+// ============================================================
+// collectWorktreePatch（D5 统一 add + diff 基线机制）
+// ============================================================
+
+/** patch 基线锚点抽象（D5）：内存 baseCommit 或宿主持久锚点文件，二选一注入。 */
+export type PatchBaselineAnchor =
+  | { readonly kind: "commit"; readonly baseCommit: string }
+  | { readonly kind: "anchor-file"; readonly path: string };
+
+export interface CollectWorktreePatchOptions {
+  /** worktree checkout 目录（add / diff 的 cwd）。 */
+  readonly worktreePath: string;
+  /** patch 输出绝对路径（须在 worktree 之外——cleanup 不会删除）。 */
+  readonly patchFile: string;
+  /**
+   * 基线锚点。anchor-file 形态的 path 须在 worktree 之外（同 patchFile 约束）：
+   * 落在 worktree 内会被本机制的 `git add -A` 一并暂存、混入 diff 产物——patch
+   * 被锚点文件自身污染（路径与内容进入 patch），且该形态无任何 warn 或
+   * patchIncomplete 留痕（不在 ⛔3 降级规格内，属静默污染）。
+   */
+  readonly anchor: PatchBaselineAnchor;
+  /** git 命令超时（ms），缺省 30_000。 */
+  readonly timeout?: number;
+  /**
+   * execFile maxBuffer（字节）＝ diff 输出上限，缺省 1MB（1024 * 1024，Node execFile
+   * 缺省）。超限即 GitRunError（先经 ⛔3① git 层触发降级 warn，降级裸 diff 同样
+   * 超限后原样上抛——实测形态，见 worktree-git-ops.test.ts 大 diff 用例）。批量
+   * 重构等大 diff 场景宿主建议 32 * 1024 * 1024（对齐旧 zsw 宿主 GIT_MAX_BUFFER）。
+   * 仅透传至产生大输出的 diff 调用（`diff --cached` 与降级裸 diff）；`add -A`
+   * 等小输出命令不透传。
+   */
+  readonly maxBuffer?: number;
+}
+
+/**
+ * patch 收集结果。`patchIncomplete` 即 ⛔3 留痕载体：true 表示 patch 相对完整
+ * 机制有已知损失（丢已提交改动 / 丢新文件），宿主透传至 record/summary 的责任
+ * 在姊妹文档 V6。缺省（undefined）= 完整机制产物。
+ */
+export interface WorktreePatchResult {
+  readonly patchFile: string;
+  /** true = diff 非空且写盘成功；false = 空 diff（不写文件，避免悬空路径）。 */
+  readonly written: boolean;
+  readonly patchIncomplete?: boolean;
+}
+
+/**
+ * 收集 worktree 改动为 patch（统一 add + diff 基线机制）。
+ *
+ * 完整形态：`git add -A`（暂存全部改动，含未跟踪新文件）→ `git diff --cached
+ * <baseline>`（暂存区 vs 基线锚点）。旧形态 `git diff HEAD <base>` 是树 vs 树对比：
+ * worktree HEAD 初始即 baseCommit，子 agent 不提交时 diff 恒空 → 改动丢失（提取源
+ * collectPatch [MF#2] 注释）。
+ *
+ * ⛔3 降级路径（均非致命、显著 warn、patchIncomplete 留痕）：
+ *   ① 锚点缺失（anchor-file 不存在/不可读）、损坏（内容空白，或内容不被 git 认）
+ *      → 裸 diff HEAD（仅未提交改动，丢已提交改动）。
+ *   ② add 失败（如索引锁冲突瞬时态）→ 裸 diff HEAD（untracked 新文件不进 patch）。
+ *      按 D5 裁决以 HEAD 为基线重定义降级形态（非 zsw `diff <base>` 等值平移），
+ *      损失面差异由 patchIncomplete 留痕判断。
+ *
+ * 写盘失败（磁盘满/权限）不在 ⛔3 降级规格内：环境级故障不与「空 diff written=false」
+ * 混淆（否则宿主把磁盘故障当无改动，patch 静默丢失），原样上抛由宿主处置。
+ */
+export async function collectWorktreePatch(
+  opts: CollectWorktreePatchOptions,
+): Promise<WorktreePatchResult> {
+  const { worktreePath, patchFile, anchor } = opts;
+  let patchIncomplete = false;
+
+  // ── 基线锚点解析（⛔3 路径①的读取层：缺失 / 不可读 / 空白）──
+  let baseline: string | undefined;
+  if (anchor.kind === "commit") {
+    const commit = anchor.baseCommit.trim();
+    if (commit.length === 0) {
+      patchIncomplete = true;
+      logger.warn(
+        "[worktree-git-ops] patch baseline anchor commit is empty, degrading to bare diff (uncommitted changes only); patch marked incomplete",
+        { worktreePath },
+      );
+    } else {
+      baseline = commit;
+    }
+  } else {
+    try {
+      const commit = fs.readFileSync(anchor.path, "utf-8").trim();
+      if (commit.length === 0) {
+        patchIncomplete = true;
+        logger.warn(
+          "[worktree-git-ops] patch baseline anchor file is empty or blank, degrading to bare diff (uncommitted changes only); patch marked incomplete",
+          { worktreePath, anchorFile: anchor.path },
+        );
+      } else {
+        baseline = commit;
+      }
+    } catch (err) {
+      patchIncomplete = true;
+      logger.warn(
+        "[worktree-git-ops] patch baseline anchor file missing or unreadable, degrading to bare diff (uncommitted changes only); patch marked incomplete",
+        {
+          worktreePath,
+          anchorFile: anchor.path,
+          detail: err instanceof Error ? err.message : String(err),
+        },
+      );
+    }
+  }
+
+  // ── git add -A（统一机制第一步；⛔3 路径②：失败非致命，继续 diff）──
+  let addFailed = false;
+  try {
+    await gitRun(["add", "-A"], { cwd: worktreePath, timeout: opts.timeout });
+  } catch (err) {
+    addFailed = true;
+    patchIncomplete = true;
+    logger.warn(
+      "[worktree-git-ops] git add -A failed, continuing with bare diff (tracked uncommitted changes only); patch marked incomplete",
+      {
+        worktreePath,
+        detail: err instanceof Error ? err.message : String(err),
+      },
+    );
+  }
+
+  // ── diff 基线机制 ──
+  if (baseline !== undefined && !addFailed) {
+    let diff: string;
+    try {
+      diff = await gitRun(["diff", "--cached", baseline], {
+        cwd: worktreePath,
+        timeout: opts.timeout,
+        maxBuffer: opts.maxBuffer,
+      });
+    } catch (err) {
+      // ⛔3 路径①的 git 层：锚点内容不被 git 认（损坏形态二：文件在、内容非合法
+      // commit）→ 同样降级裸 diff。裸 diff 再失败 = 真 git 故障，原样上抛。
+      patchIncomplete = true;
+      logger.warn(
+        "[worktree-git-ops] patch baseline anchor rejected by git (corrupted?), degrading to bare diff (uncommitted changes only); patch marked incomplete",
+        {
+          worktreePath,
+          baseline,
+          detail: err instanceof Error ? err.message : String(err),
+        },
+      );
+      diff = await gitRun(["diff", "HEAD"], {
+        cwd: worktreePath,
+        timeout: opts.timeout,
+        maxBuffer: opts.maxBuffer,
+      });
+      return finishPatch(diff, patchFile, patchIncomplete);
+    }
+    return finishPatch(diff, patchFile, patchIncomplete);
+  }
+
+  // 降级形态（⛔3①/②）：裸 diff HEAD，仅未提交改动（add 成功时含已暂存新文件；
+  // add 失败时 untracked 新文件不进 patch——两条路径损失面不同，留痕同一标记）。
+  const diff = await gitRun(["diff", "HEAD"], {
+    cwd: worktreePath,
+    timeout: opts.timeout,
+    maxBuffer: opts.maxBuffer,
+  });
+  return finishPatch(diff, patchFile, patchIncomplete);
+}
+
+/** diff 出口收敛：空 diff 不写文件（written=false，避免悬空路径）；写盘失败上抛。 */
+function finishPatch(
+  diff: string,
+  patchFile: string,
+  patchIncomplete: boolean,
+): WorktreePatchResult {
+  if (diff.length === 0) {
+    return {
+      patchFile,
+      written: false,
+      ...(patchIncomplete ? { patchIncomplete: true } : {}),
+    };
+  }
+  fs.writeFileSync(patchFile, diff, "utf-8");
+  return {
+    patchFile,
+    written: true,
+    ...(patchIncomplete ? { patchIncomplete: true } : {}),
+  };
+}
+
+// ============================================================
+// cleanupWorktree（三步容错清理）
+// ============================================================
+
+export interface CleanupWorktreeOptions {
+  /** 主仓库根目录（git -C 目标）。 */
+  readonly repo: string;
+  /** worktree checkout 绝对路径。 */
+  readonly worktreePath: string;
+  /** 分支名。 */
+  readonly branch: string;
+  /** 第三步宿主钩子（如 worktrees.json 注册表移除）。注册表归宿主（D5 目录布局
+   *  与孤儿判定留宿主），内核经回调解耦；抛错仅 warn 不阻断（三步各自容错）。 */
+  readonly onRemoved?: () => Promise<void> | void;
+  /** git 命令超时（ms），缺省 30_000。 */
+  readonly timeout?: number;
+}
+
+/**
+ * 清理 worktree：worktree remove --force → branch -D → onRemoved 宿主钩子。
+ * 三步各自独立容错——任一步失败不阻断其余（如 remove 失败仍尝试 branch -D +
+ * 宿主钩子），避免单步失败导致后续资源泄漏（提取源 cleanup 的容错结构）。
+ * 前两步失败 debug 留痕（best-effort 惯例）；宿主钩子失败 warn（宿主态漂移值得
+ * 显著，孤儿收敛兜底在宿主 reaper/对账）。本函数永不 reject。
+ */
+export async function cleanupWorktree(opts: CleanupWorktreeOptions): Promise<void> {
+  try {
+    await gitRun(["worktree", "remove", "--force", opts.worktreePath], {
+      cwd: opts.repo,
+      timeout: opts.timeout,
+    });
+  } catch (err) {
+    bestEffort(err, "worktree remove (cleanup)");
+  }
+
+  try {
+    await gitRun(["branch", "-D", opts.branch], {
+      cwd: opts.repo,
+      timeout: opts.timeout,
+    });
+  } catch (err) {
+    bestEffort(err, "branch delete (cleanup)");
+  }
+
+  if (opts.onRemoved) {
+    try {
+      await opts.onRemoved();
+    } catch (err) {
+      logger.warn("[worktree-git-ops] cleanup onRemoved host hook failed (worktree/branch already cleaned)", {
+        branch: opts.branch,
+        detail: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+}
+
+// ============================================================
+// listWorktreePorcelain（原始形态输出）
+// ============================================================
+
+export interface ListWorktreePorcelainOptions {
+  /** 主仓库根目录（git -C 目标）。 */
+  readonly repo: string;
+  /** git 命令超时（ms），缺省 30_000。 */
+  readonly timeout?: number;
+}
+
+/**
+ * `git worktree list --porcelain` 原始 stdout 保真返回（不 trim / 不 split / 不
+ * 逐行加工）。宿主 realpath 对账依赖原始行文（zsw 的 /var→/private/var 归账）。
+ * 失败 reject GitRunError（读类命令失败 = 真故障，处置策略归宿主）。
+ */
+export async function listWorktreePorcelain(opts: ListWorktreePorcelainOptions): Promise<string> {
+  return gitRun(["worktree", "list", "--porcelain"], { cwd: opts.repo, timeout: opts.timeout });
+}

package/src/execution/worktree-manager.ts

@@ -49,6 +49,15 @@ const WORKTREE_TMP_ROOT = "pi-subagents";
 /** 分支名前缀（create() 生成 `pi-sub-<recordId>`）。 */
 const BRANCH_PREFIX = "pi-sub-";
 
+/**
+ * 对账「歧义跳过」的老化升级阈值（PS-12 措施⑤）：同一物理残留连续 N 轮 scan
+ * 仍无法建立 branch↔pid 对应 → 升级为含磁盘路径与人工清理指引的强 warn，
+ * 终结「仅周期性低信息 warn、有界资源永无终局」的滞留形态。导出供测试与
+ * 运维文档对齐阈值。N 是周期数不是绝对时长——scan 由 session_start 触发，
+ * 频率随使用节奏，按周期计数避免与时钟假设耦合。
+ */
+export const RECONCILE_SKIP_ESCALATION_CYCLES = 4;
+
 /**
  * 物理面发现的 worktree（tmpdir checkout 目录存在，无论注册表是否登记）。
  * repo 从 checkout/.git 指针文件推导（普通 repo 与 bare+worktree 均覆盖）；
@@ -132,6 +141,12 @@ export class WorktreeManager {
   // 不继承前驱错误（否则 1 个 worktree add 失败会传染同 repo 后续全部写命令，
   // 替代旧同步版单线程天然全局串行的「各命令独立失败」语义）。
   private readonly writeQueues = new Map<string, Promise<void>>();
+  // [PS-12 措施⑤] 对账歧义跳过的 per-checkout 连续计数（老化判据）。
+  // key = checkout 绝对路径；每轮 reconcileWithPhysical 末尾收敛为「本轮实际
+  // 进入歧义分支」的路径集（自愈/判死清理/注册表收编/物理消失的一律清零，
+  // 见该方法尾部），条目数 ≤ 单轮歧义残留数，无泄漏面。内存态：进程重启后
+  // 重新起数——老化是人工介入的提醒信号，不值得为此引入持久化状态。
+  private readonly ambiguousSkipCycles = new Map<string, number>();
 
   constructor(agentDir: string) {
     this.agentDir = agentDir;
@@ -373,7 +388,14 @@ export class WorktreeManager {
 
     // ── 方向二：物理有 → 注册无 ──
     const orphans = physical.filter((pt) => !registeredBranches.has(pt.branch));
-    await this.reconcileUnregisteredWorktrees(orphans);
+    const ambiguousNow = await this.reconcileUnregisteredWorktrees(orphans);
+
+    // [PS-12 措施⑤] 老化计数收敛（「出现对应后清零」）：本轮未进入歧义跳过的
+    // 路径——自愈补写 / 判死清理 / 注册表收编 / 物理消失——计数删除，重现时
+    // 重新起数；升级 warn 因此只在「连续无对应」时出现，不因历史陈账误触发。
+    for (const checkout of [...this.ambiguousSkipCycles.keys()]) {
+      if (!ambiguousNow.has(checkout)) this.ambiguousSkipCycles.delete(checkout);
+    }
   }
 
   /** 对账方向一（注册有 → 物理无）：条目的分支与 checkout 目录都已不存在 → 条目指向
@@ -408,9 +430,13 @@ export class WorktreeManager {
    *      并发覆盖丢条目场景，补写后回归标准 pid 判据路径）；
    *    - 多活 pid 或多残留无法建立 branch↔pid 对应：跳过 + warn——宁延迟勿误删；
    *      活体自身 cleanup 路径正常（registry.remove 幂等），死体等活 pid 全灭后
-   *      下一周期收敛。 */
-  private async reconcileUnregisteredWorktrees(orphans: PhysicalWorktree[]): Promise<void> {
+   *      下一周期收敛。
+   *
+   *  返回本轮实际进入「歧义跳过」的 checkout 路径集（PS-12 老化计数收敛依据，
+   *  见 reconcileWithPhysical 尾部）。 */
+  private async reconcileUnregisteredWorktrees(orphans: PhysicalWorktree[]): Promise<Set<string>> {
     // 按 enc 段聚合处理（活信号以 enc 段为粒度——.alive 在 <enc>/sessions/ 下）
+    const ambiguous = new Set<string>();
     const orphansByEnc = new Map<string, PhysicalWorktree[]>();
     for (const pt of orphans) {
       const list = orphansByEnc.get(pt.enc) ?? [];
@@ -418,12 +444,17 @@ export class WorktreeManager {
       orphansByEnc.set(pt.enc, list);
     }
     for (const [enc, list] of orphansByEnc) {
-      await this.reconcileEncSegment(enc, list);
+      await this.reconcileEncSegment(enc, list, ambiguous);
     }
+    return ambiguous;
   }
 
   /** 单 enc 段的残留处置三分支：无活 pid 判死清理 / 唯一对应自愈补写 / 多对应保守跳过。 */
-  private async reconcileEncSegment(enc: string, list: PhysicalWorktree[]): Promise<void> {
+  private async reconcileEncSegment(
+    enc: string,
+    list: PhysicalWorktree[],
+    ambiguous: Set<string>,
+  ): Promise<void> {
     const alivePids = this.collectAlivePids(enc);
     if (alivePids.length === 0) {
       await this.cleanupDeadSegment(list);
@@ -449,11 +480,42 @@ export class WorktreeManager {
       return;
     }
     // 多活 pid / 多残留：无法建立 branch↔pid 对应，保守跳过待下周期。
-    logger.warn("[worktree] reconcile: unregistered physical worktrees present but alive-pid mapping ambiguous, skipping this cycle", {
-      enc,
-      orphans: list.length,
-      alivePids: alivePids.length,
-    });
+    // [PS-12 措施⑤] 保守跳过加老化：同一 checkout 连续 {@link
+    // RECONCILE_SKIP_ESCALATION_CYCLES} 轮仍无对应 → 升级为含磁盘路径与人工
+    // 清理指引的强 warn（有界资源泄漏不能永远停在低信息周期 warn 上）。计数
+    // 清零由 reconcileWithPhysical 统一编排——凡本轮未进入本分支的路径一律重置。
+    let escalated = 0;
+    for (const pt of list) {
+      const cycles = (this.ambiguousSkipCycles.get(pt.checkout) ?? 0) + 1;
+      this.ambiguousSkipCycles.set(pt.checkout, cycles);
+      ambiguous.add(pt.checkout); // 本轮实际进入歧义跳过（老化收敛依据，见调用方）
+      if (cycles < RECONCILE_SKIP_ESCALATION_CYCLES) continue;
+      escalated++;
+      // repo 未知（无主残留）时指引里用 <main-repo> 占位，data.repo 同步标注
+      const repoHint = pt.repo ?? "<main-repo>";
+      logger.warn(
+        `[worktree] reconcile: unregistered physical worktree skipped for ${cycles} consecutive cycles ` +
+          `(alive-pid mapping still ambiguous) — manual cleanup may be needed. ` +
+          `Inspect: git -C ${repoHint} worktree list. ` +
+          `If no live process owns it: git -C ${repoHint} worktree remove --force ${pt.checkout} && git -C ${repoHint} branch -D ${pt.branch}. ` +
+          `Ownerless checkout (repo unknown, delete the directory directly): rm -rf ${pt.checkout}`,
+        {
+          branch: pt.branch,
+          checkout: pt.checkout,
+          repo: pt.repo,
+          skippedCycles: cycles,
+        },
+      );
+    }
+    // 未达升级阈值的残留维持既有低信息聚合 warn（数量只含本周期未升级部分；
+    // 全部升级时不再发本条，避免每周期双份噪音）
+    if (escalated < list.length) {
+      logger.warn("[worktree] reconcile: unregistered physical worktrees present but alive-pid mapping ambiguous, skipping this cycle", {
+        enc,
+        orphans: list.length - escalated,
+        alivePids: alivePids.length,
+      });
+    }
   }
 
   /** 无活 pid 段：残留判死清理——checkout mtime 超 SPAWN_GRACE_MS 才清（防误清另一

package/src/execution/worktree-registry.ts

@@ -18,12 +18,13 @@
 //     双向 diff，见 reconcileWithPhysical）。
 //   - 同步 IO（readFileSync/writeFileSync）持锁执行：锁内临界区毫秒级，
 //     async 锁 + sync IO 组合在单线程 event loop 内无 interleaving。
-//   - 原子写：写 .tmp → rename，防写一半崩溃产生损坏 JSON。
+//   - 原子写：tmp+rename 统一走 shared/atomic-write（U6b），防写一半崩溃产生损坏 JSON。
 
 import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { getLogger } from "../core/logger.ts";
+import { writeAtomicFileSync } from "../shared/atomic-write.ts";
 import lockfile from "proper-lockfile";
 
 import { bestEffort } from "./best-effort.ts";
@@ -36,11 +37,6 @@ export const SPAWN_GRACE_MS = 60_000;
 /** JSON 缩进空格数（可读性 + diff 友好）。 */
 const JSON_INDENT = 2;
 
-/** tmp 随机段：36 进制取 8 字符（跳过 "0." 前缀），与 pid 组合保证并发唯一。 */
-const TMP_RANDOM_BASE = 36;
-const TMP_RANDOM_SLICE_START = 2; // 跳过 Math.random 字符串的 "0." 前缀
-const TMP_RANDOM_SLICE_END = 10;
-
 /**
  * 锁参数：逐项对齐 extensions/shared/file-lock/src/file-lock.ts 的 withFileLock
  * 包装默认值（stale 30s / retries 10）。两侧参数漂移会破坏「同一把
@@ -254,18 +250,16 @@ export class WorktreeRegistry {
   }
 
   /**
-   * 原子写入全部条目。
+   * 原子写入全部条目（shared/atomic-write 统一原语，U6b 迁移——sync 档
+   * writeAtomicFileSync；写失败时原语清理残留 tmp，消除旧实现「write 成功但
+   * rename 失败漏清 tmp」缺陷）。
    * best-effort：写入失败不阻断主流程（create/cleanup 的 git 操作已执行，
    * 注册表与 git 状态的短暂不一致靠下次 reaper 对账收敛）。
    * 写盘失败时 warn 日志（带 branch/pid 上下文，补全失败可观测闭环）。
    */
   private save(entries: WorktreeEntry[], context?: { branch?: string; pid?: number }): void {
     try {
-      fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
-      // tmp 名带 pid + 随机段：锁降级（无锁并发 RMW）时多进程 tmp 互不覆盖
-      const tmp = `${this.filePath}.tmp_${process.pid}_${Math.random().toString(TMP_RANDOM_BASE).slice(TMP_RANDOM_SLICE_START, TMP_RANDOM_SLICE_END)}`;
-      fs.writeFileSync(tmp, JSON.stringify({ entries }, null, JSON_INDENT), "utf-8");
-      fs.renameSync(tmp, this.filePath);
+      writeAtomicFileSync(this.filePath, JSON.stringify({ entries }, null, JSON_INDENT));
     } catch (err) {
       bestEffort(err, "worktree registry save");
       // [worktree-reaper-fix] 补全写盘失败静默吞错时，条目 pid 恒 0、60s 后被 reaper 误删