@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/agents-assembly.ts

@@ -0,0 +1,88 @@
+// src/execution/agents-assembly.ts
+//
+// agent 装配函数（sink 设计 U2 / A6）：发现 → parseAgentProfile → frontmatter name
+// 去重 → 码点序，warn 口径内聚。workflow 侧 discoverWorkflows（config-loader）的
+// 对称面——第三宿主仅凭该函数即可「列 agents」（G3/S5），无需复刻装配循环。
+//
+// 与 pi 壳装配循环（subagent-list-injector.discoverAllAgents）的等值口径：
+// - 清单可见性 = IF1 严格层（profile.meta !== null）——缺 name/description 的资产
+//   不进清单（注入投影「路由可见性」双轨语义，D3 定稿；宽容解析只服务执行消费面）；
+// - warn 口径内聚：仅「有 frontmatter 但严格校验未通过」才 warn——README 等无
+//   frontmatter 的 .md 静默跳过（每 turn 扫描不刷屏，pi m5 评审先例）；
+// - 扫描 / 遮蔽语义归 shared/resource-discovery（ADR-031），本文件零扫描逻辑。
+
+import type { AgentEntry } from "../shared/injection-render.ts";
+import { sortByCodepoint } from "../shared/injection-render.ts";
+import { discoverResources, getCachedFileContent } from "../shared/resource-discovery.ts";
+import type { DiscoveryRoot } from "../core/host-services.ts";
+import { getLogger } from "../core/logger.ts";
+import { parseAgentProfile } from "./agent-registry.ts";
+
+const logger = getLogger("agents-assembly");
+
+/**
+ * 发现并列出全部可用 agent（U2/A6 装配函数）。
+ *
+ * 流程：discoverResources（按优先级低→高，last-writer-wins）→ 逐文件
+ * parseAgentProfile → 仅 IF1 严格层通过（profile.meta !== null）的条目进清单 →
+ * 按 frontmatter name 去重（高优先级靠后覆盖，Map 后写胜）→ name 码点序输出
+ * （KV-cache 契约：顺序与 readdir 枚举序解耦，重建结果逐字节一致）。
+ *
+ * 抛错面（如实声明）：单文件读失败仅记日志跳过；目录不存在返回空列表；但底层
+ * discoverResources 的不可恢复扫描错误会原样向上传播（readdir 遇权限拒绝、
+ * EMFILE 竞态等——resource-discovery 自述 "Throws on unrecoverable scan errors"，
+ * Promise.all 首个 reject 即整体拒绝），调用方需自行兜底。
+ *
+ * @param workspaceRoot 项目根（findWorkspaceRoot 推导结果）
+ * @param hostRoots 宿主注入发现根（pi 壳 = getAgentDir 三根；无则传 []——
+ *                  user-agents/project-agents 硬编码槽仍生效，与 ScanConfig 语义一致）。
+ *                  注意：hostRoots 之外还有四个硬编码根恒进入扫描，无法经参数关闭——
+ *                  `~/.agents/agents`、`<workspaceRoot>/.pi/agents`、
+ *                  `<workspaceRoot>/.agents/agents` 与 `XYZ_EXTENSION_PATHS`
+ *                  环境变量展开的扩展源码路径（resource-discovery buildScanTargets
+ *                  固定槽位，注入 hostRoots 只是增列而非替换扫描面）
+ */
+export async function discoverAgents(
+  workspaceRoot: string,
+  hostRoots: DiscoveryRoot[],
+): Promise<AgentEntry[]> {
+  const resources = await discoverResources({
+    kind: "agents",
+    workspaceRoot,
+    hostRoots,
+  });
+
+  const agentMap = new Map<string, AgentEntry>();
+  for (const resource of resources) {
+    // manifest 校验失败的包整体占位（available=false），不进清单
+    if (!resource.available) continue;
+
+    const content = getCachedFileContent(resource.path);
+    if (content === null) {
+      // 单文件读失败不阻断整条 agent 列表装配
+      logger.error(`[agents-assembly] skip unreadable agent file ${resource.path}`);
+      continue;
+    }
+
+    // 宽容解析（执行消费面单点）；清单可见性按严格层 meta 判定
+    const profile = parseAgentProfile(content, resource.path);
+    if (profile.meta !== null) {
+      agentMap.set(profile.name, {
+        name: profile.name,
+        description: profile.description,
+        ...(profile.when !== undefined ? { when: profile.when } : {}),
+        ...(profile.examples !== undefined ? { examples: profile.examples } : {}),
+        path: resource.path,
+      });
+    } else if (content.trimStart().startsWith("---")) {
+      // 仅「有 frontmatter 但严格校验未通过」才 warn——无 frontmatter 的 README 等
+      // 普通 .md 静默跳过（pi m5 评审先例：缺 name/description 或单条 examples 非法
+      // 致整体 reject 时作者需要知道，普通文档不需要）。
+      logger.warn(
+        `[agents-assembly] ${resource.path}: agent frontmatter 解析失败（IF1 校验不通过）——agent 未进清单`,
+      );
+    }
+  }
+
+  return sortByCodepoint([...agentMap.values()], (a) => a.name);
+}

package/src/execution/cold-resurrect.ts

@@ -0,0 +1,199 @@
+// [D4-③ 冷路径复活职责轴] message action 冷查/复活链（原 SubagentService 私有的
+// findColdLookupCandidate / assertReconnectAllowed / resurrectColdRecord /
+// coldLookupForAction + isReconnectableClosed 判定）整体搬移至 record-store 邻接处
+// （行为逐字节等价：搬移 + 依赖注入，不重写逻辑）。变化轴：改跨重启重建 /
+// 透明重生回边 / 可重连守卫语义，只改本文件；Service 的 getRecordForAction 保留
+// 归属校验编排（内存未命中分支委托 coldLookupForAction）。
+
+import * as fs from "node:fs";
+
+import { findForeignLiveInstance, writeAliveMarker } from "./alive-store.ts";
+import { createRecord, resurrectClosed } from "./execution-record.ts";
+import type { StatusFilter } from "./record-store.ts";
+import type { ExecutionRecord, SubagentRecord } from "./types.ts";
+import { isReconnectableFinalReason, ResurrectDeniedError } from "./types.ts";
+
+/** SP-2 冷路径按 id 查 record 的 collectRecords 扫描上限（全扫兜底的容量 cap）。
+ *  原定义于 subagent-service.ts，随冷查链搬移；Service.lookupRecordAnyState
+ *  （全态查询）同样消费本常量。 */
+export const COLD_LOOKUP_SCAN_LIMIT = 1000;
+
+/** 冷查/复活的依赖注入（Service 侧供给，store 查询 + 归属上下文）。 */
+export interface ColdResurrectDeps {
+  /** store 的 idToFile 索引直查（light 快照）。 */
+  findLightById: (id: string) => SubagentRecord | undefined;
+  /** store 的磁盘全扫（内存未命中 / 索引未热时兜底）。rootFilter 恒 undefined
+   *  （冷查不做 root 过滤——归属校验在候选定位之后，见 coldLookupForAction）。 */
+  collectRecords: (limit: number, statusFilter: StatusFilter, rootFilter: undefined) => SubagentRecord[];
+  /** 重建 record 注册进内存 store。 */
+  register: (record: ExecutionRecord) => void;
+  /** 重建后的 transition entry 上报（live ≡ reload 等价性）。 */
+  reportRecordTransition: (record: ExecutionRecord) => void;
+  /** 当前所属根 session id（归属校验用，运行时可变——initSession 建立）。 */
+  getSessionRootId: () => string | null;
+  /** 本进程嵌套基线 recordId（直接父校验用；根进程 undefined）。 */
+  getBaselineRecordId: () => string | undefined;
+}
+
+/** 冷查候选定位（coldLookupForAction 步骤 1）：idToFile 索引直查 running 命中，
+ *  未命中再全目录 collectRecords 兜底（running，或 allowReconnect 且可重连 closed）。
+ *
+ *  [T5③ / PS-7b] running 候选异进程活实例守卫：冷查 running 候选（跨重启 / 内存重建）
+ *  此前不经任何探针直接 resurrect + resume spawn——若其 .alive marker 仍指向活着的
+ *  异进程实例（父进程重启后旧子进程尚存的窗口），resume 会 spawn 第二个 pi 子进程
+ *  写同一 session JSONL（本代码最忌惮的双写者形态，v4 A-5/P7 事故模式）。closed 候选
+ *  的同款守卫已在 assertReconnectAllowed（v8.5 D）；本守卫闭合 running 候选的防御
+ *  不对称。marker 的 pid 是子进程 pi 的 pid（非父进程），本进程持有的 running record
+ *  恒在内存（archive 才移出），可达本冷查分支的 running 候选必然来自磁盘重建——
+ *  探针命中即拒绝（ResurrectDeniedError，与 closed 候选守卫同异常类型，错误含 pid
+ *  与恢复指引）。 */
+function findColdLookupCandidate(
+  deps: ColdResurrectDeps,
+  id: string,
+  allowReconnect: boolean,
+): SubagentRecord | undefined {
+  const direct = deps.findLightById(id);
+  const found =
+    (direct?.status === "running" ? direct : undefined) ??
+    deps
+      .collectRecords(COLD_LOOKUP_SCAN_LIMIT, "all", undefined)
+      .find((r) => r.id === id && (r.status === "running" || (allowReconnect && isReconnectableClosed(r))));
+  if (found?.status === "running" && found.sessionFile) {
+    const foreign = findForeignLiveInstance(found.sessionFile);
+    if (foreign) {
+      throw new ResurrectDeniedError(
+        `subagent ${id} is currently running in another process instance (pid ${foreign.pid}, ` +
+          `startedAt=${new Date(foreign.startedAt).toISOString()}); resuming here would double-write ${found.sessionFile}. ` +
+          `Recovery: retry once that process exits; if it never exits, action:'close' this subagent, then action:'start' a fresh one.`,
+      );
+    }
+  }
+  return found;
+}
+
+/** [v8.5 D] 冷查候选过滤：closed 且死因落在可重连集。判定源 = closedReason（buildRecord
+ *  归一化后的对外字段：A 档真实死因直通、旧空 sidecar 兑底 disconnected——SubagentRecord
+ *  不暴露 raw finalizedReason）；cancelled/user-close/gc 等主动关闭与自然完成死因天然不在集合内。
+ *  防线在集合本身而非调用点。 */
+function isReconnectableClosed(r: SubagentRecord): boolean {
+  return isReconnectableFinalReason(r.closedReason);
+}
+
+/** 可重连守卫（coldLookupForAction 步骤 2，[v8.5 D]）：先于任何状态突变与注册。
+ *  worktree 绑定丢失 / 异进程活实例以 ResurrectDeniedError 抛出（endedMessageGuard
+ *  必须原样透传，不得改写为 fork-from 指引误导 agent 走已被判死的通道）；拒绝时
+ *  内存不得残留该记录（findRecord 契约）。 */
+function assertReconnectAllowed(found: SubagentRecord, id: string): void {
+  if (found.status !== "closed") return;
+  if (found.worktree === true) {
+    throw new ResurrectDeniedError(
+      `subagent ${id} cannot be transparently resumed: it was created with worktree isolation, ` +
+        `and its worktree checkout no longer exists after restart (resuming in place would make spawn cwd fall back to the main repo). ` +
+        `Recovery: action:'start' a fresh subagent (with a new worktree if isolation is still needed); ` +
+        `its conversation history remains intact at ${found.sessionFile}.`,
+    );
+  }
+  const foreign = found.sessionFile ? findForeignLiveInstance(found.sessionFile) : undefined;
+  if (foreign) {
+    throw new ResurrectDeniedError(
+      `subagent ${id} is not transparently resumable: its previous instance still finishing in another process ` +
+        `(pid ${foreign.pid}, startedAt=${new Date(foreign.startedAt).toISOString()}). ` +
+        `Resuming in place would double-write ${found.sessionFile}. ` +
+        `Recovery: retry once that process exits; if it never exits, action:'start' a fresh subagent and treat the history at ${found.sessionFile} as read-only reference.`,
+    );
+  }
+}
+
+/** 磁盘候选重建为可变 record 并 register + 上报（coldLookupForAction 步骤 4）。 */
+function resurrectColdRecord(
+  deps: ColdResurrectDeps,
+  found: SubagentRecord,
+  id: string,
+): ExecutionRecord {
+  const record = createRecord(id, {
+    agent: found.agent,
+    model: found.model,
+    thinkingLevel: found.thinkingLevel,
+    mode: found.mode,
+    task: found.task,
+    slug: found.slug,
+    startedAt: found.startedAt,
+    rootSessionId: found.rootSessionId,
+    parentRecordId: found.parentRecordId,
+    depth: found.depth,
+    // [v4 A-3] 跨重启恢复入口——message 路径磁盘重建无条件置 chatMode=true（现状机制，
+    // V3 方案 A 方向兑现）。改动此处必须带 S3 回归场景（跨重启 message 续聊验证）。
+    // V3 SP-5 探针定案：机制已存在，本注释即定案，不再悬置。
+    chatMode: true,
+    controller: new AbortController(),
+  });
+  record.sessionFile = found.sessionFile;
+  record.round = found.round;
+  // [review round2] 跨重启 worktree 绑定丢失防护：原 record 创建时启用了 worktree 隔离
+  //（session entry 的 worktree 标志），但 WorktreeHandle 不可序列化、重建后恒缺失。
+  // 标记 hadWorktree，冷路径续轮守卫据此拒绝续聊（防 spawn cwd 静默回落主 repo 破坏
+  // 隔离——正是 worktree 要防的并发写冲突场景）。close 不受影响（closeChatIdle 走
+  // doFinalizeRecord，泄漏的 worktree 由 reaper 兜底回收）。
+  record.hadWorktree = found.worktree === true;
+  // [v8.5 D] 透明重生回边：独立函数不走 tryTransition 单向语义（closed 单向性对正常
+  // 执行流完整保留）；准入唯一依据 = A 档 sidecar 真实死因 ∈ 可重连集。死亡语义位由
+  // resurrectClosed 清除；register 后立刻上报 transition entry，live/reload 视图同步
+  // 翻回 running（等价性由 applyEntry reducer 保证，对齐 SP-2 重建即报告先例）。
+  const wasClosed = found.status !== "running";
+  if (wasClosed) {
+    // [review MF-8] 磁盘终态位同步翻转：record-store buildRecord 分支 2（.finalized
+    // 存在 → closed）优先级高于 .alive 活态分支 3，重生若不删 sidecar，任何磁盘扫描
+    // （异进程 / reload / session-reader）都会把本进程内存里 running 的 record 报成
+    // closed/disconnected——破坏 live ≡ reload，且为跨进程二次 resurrect 开门。
+    // best-effort 对齐 BC-4 语义；.alive 刷新为当前进程（后续 resume spawn 会覆盖写）。
+    if (record.sessionFile) {
+      try {
+        fs.rmSync(`${record.sessionFile}.finalized`, { force: true });
+        writeAliveMarker(record.sessionFile, { pid: process.pid, id, startedAt: Date.now() });
+      } catch (_e) {
+        void _e; // best-effort：sidecar 翻转失败不阻断重生主流程
+      }
+    }
+    resurrectClosed(record);
+  }
+  deps.register(record);
+  if (wasClosed) {
+    deps.reportRecordTransition(record);
+  }
+  return record;
+}
+
+/** [D4-③] 冷查编排（原 Service.coldLookupForAction）：getRecordForAction 内存未命中
+ *  分支——候选定位 → 可重连守卫 → 归属/直接父校验 → 重建注册。
+ *  @returns 重建的 record；磁盘也无则 undefined
+ *  @throws ResurrectDeniedError 可重连候选被 worktree/异进程活实例守卫拦截
+ *  @throws Error parentRecordId 跨层不匹配（direct parent 错误，与外层校验同文案） */
+export function coldLookupForAction(
+  deps: ColdResurrectDeps,
+  id: string,
+  allowReconnect: boolean,
+): ExecutionRecord | undefined {
+  const found = findColdLookupCandidate(deps, id, allowReconnect);
+  if (!found) return undefined;
+  // [v8.5 D] 可重连候选的守卫先于任何状态突变与注册（细节见 assertReconnectAllowed）
+  assertReconnectAllowed(found, id);
+  // [review MF-9] 归属校验先于任何持久化副作用：coldLookup 是 getRecordForAction 的
+  // 内存未命中分支，若先 resurrect/register/report 再由调用方抛归属错误，会在磁盘/
+  // 内存留下幽灵 running record + running transition entry（跨进程双 resurrect 窗口）。
+  // rootSessionId 不匹配 → 返回 undefined，由 getRecordForAction 抛统一「not found or
+  // not owned」（不区分失败形态，防跨 session 探测）；parentRecordId 跨层不匹配 →
+  // 原样抛 direct parent 错误（与外层校验同文案，保留跨层导航指引）。
+  if (found.rootSessionId !== deps.getSessionRootId()) {
+    return undefined;
+  }
+  const baselineRecordId = deps.getBaselineRecordId();
+  if (found.parentRecordId !== baselineRecordId) {
+    throw new Error(
+      `subagent ${id} is owned by its direct parent; message it through that parent ` +
+        `(see /subagents list, parent=${found.parentRecordId ?? "(root layer)"}). [v4 A-5] cross-layer ` +
+        `ownership guard: this process's baseline=${baselineRecordId ?? "(root)"} is not the direct parent of ${id}; ` +
+        `operating here would race the owning child process's handle and double-write the session file.`,
+    );
+  }
+  return resurrectColdRecord(deps, found, id);
+}

package/src/execution/concurrency-pool.ts

@@ -14,9 +14,25 @@ interface QueueEntry {
   signal?: AbortSignal;
 }
 
+/**
+ * 排队策略（D7/U4）：release 时从等待队列放行哪个条目。策略差异是宿主声明的
+ * 有意决策（pi=priority / zsw=strict-fifo），保留为参数而非消灭（见 sink 设计
+ * subagent-core-sink-design.md §3.3 D7）。
+ *
+ * - `"priority"`（缺省）：priority 值最小（0=最高）者优先，同优先级按入队序（FIFO）。
+ *   与 pi 既有行为等值。
+ * - `"strict-fifo"`：忽略 priority，严格按入队顺序（seq）放行。纯 FIFO 语义，
+ *   供 zsw 侧等需要「先到先得、不许插队」语义的宿主消费。
+ */
+export type QueuePolicy = "priority" | "strict-fifo";
+
 /** 并发池接口（可注入，便于测试 mock）。 */
 export interface ConcurrencyPool {
-  /** 按优先级排队获取槽位（0=最高）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。可选 AbortSignal 在 abort 时 reject 排队条目。 */
+  /**
+   * 排队获取槽位（priority 0=最高；"strict-fifo" 策略下该值仅记录不参与出队选择，
+   * 见 createConcurrencyPool）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。
+   * 可选 AbortSignal 在 abort 时 reject 排队条目。
+   */
   acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void>;
   /** 归还槽位。必须无条件执行（finally）。 */
   release(): void;
@@ -27,27 +43,40 @@ export interface ConcurrencyPool {
 }
 
 /**
- * 默认实现：maxConcurrent 槽位 + 优先级队列。
+ * 默认实现：maxConcurrent 槽位 + 可策略化排队队列。
  *
  *   acquire(priority, effectiveMaxConcurrent?):
  *     effective = effectiveMaxConcurrent ?? maxConcurrent
  *     active < effective → active++, resolve
- *     否则 → 入队 { priority, resolve, seq }, 队列按 priority 升序 + seq FIFO
+ *     否则 → 入队 { priority, resolve, seq }
  *
  *   release():
- *     queue 非空 → 出队最高优先级 resolve（active 不变）
+ *     queue 非空 → 按 queuePolicy 选一个条目出队 resolve（active 不变）：
+ *       - "priority"：priority 升序 + 同优先级 seq FIFO
+ *       - "strict-fifo"：纯 seq FIFO（priority 仅记录）
  *     queue 空 → active--（防下溢）
+ *
+ *   已知契约边界（审查 S-2 登记）：分层配额（effectiveMaxConcurrent）仅在
+ *   acquire 时点判定；release 授予排队条目时不复查其 effective——即活跃数
+ *   仍 ≥ 条目 effective 时，单次释放也可能授予该条目（pi 运行时既有行为，
+ *   concurrency-pool.test T-A2 锚定）。需要严格分层隔离的宿主应在条目侧
+ *   自行保证，勿依赖 release 时点复查。
+ *
+ * 类保留内部消费（subagent-service 深路径）；对外导出面走 createConcurrencyPool
+ * 工厂（对象参数 + 策略枚举，不暴露本类名与位置参数构造——D7/U4 裁决）。
  */
 export class DefaultConcurrencyPool implements ConcurrencyPool {
   private _active = 0;
   private readonly queue: QueueEntry[] = [];
   private seqCounter = 0;
+  private readonly queuePolicy: QueuePolicy;
 
   /** 下限 1——maxConcurrent=0 会让 acquire 永久排队死锁（C3 修复）。 */
   readonly maxConcurrent: number;
 
-  constructor(maxConcurrent: number) {
+  constructor(maxConcurrent: number, queuePolicy: QueuePolicy = "priority") {
     this.maxConcurrent = Math.max(1, maxConcurrent);
+    this.queuePolicy = queuePolicy;
   }
 
   acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void> {
@@ -86,14 +115,24 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
     });
   }
 
+  /**
+   * 出队候选比较：cur 是否优于 best（release 时选谁获得释放的槽位）。
+   * 策略单一分派点——新增策略只需在此分支，acquire/abort/clamp 逻辑策略无关。
+   */
+  private isBetterCandidate(cur: QueueEntry, best: QueueEntry): boolean {
+    if (this.queuePolicy === "strict-fifo") {
+      // 纯 FIFO：seq 单调递增，先入队者 seq 必更小——priority 完全不参与
+      return cur.seq < best.seq;
+    }
+    // priority：取优先级最高（priority 最小）的；同优先级 FIFO（seq 最小）
+    return cur.priority < best.priority || (cur.priority === best.priority && cur.seq < best.seq);
+  }
+
   release(): void {
     if (this.queue.length > 0) {
-      // 取优先级最高（priority 最小）的；同优先级 FIFO（seq 最小）
       let bestIdx = 0;
       for (let i = 1; i < this.queue.length; i++) {
-        const cur = this.queue[i];
-        const best = this.queue[bestIdx];
-        if (cur.priority < best.priority || (cur.priority === best.priority && cur.seq < best.seq)) {
+        if (this.isBetterCandidate(this.queue[i], this.queue[bestIdx])) {
           bestIdx = i;
         }
       }
@@ -114,3 +153,26 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
     return this._active;
   }
 }
+
+/** createConcurrencyPool 选项（对象参数构造——导出面禁止位置参数歧义，D7/U4）。 */
+export interface CreateConcurrencyPoolOptions {
+  /** 实例级最大并发配额。0/负数 clamp 到 1（防 acquire 永久排队死锁，C3 修复语义）。 */
+  maxConcurrent: number;
+  /**
+   * 排队策略（见 QueuePolicy）。缺省 `"priority"`——与 pi 既有消费
+   * （`new DefaultConcurrencyPool(n)`）行为逐点等值，缺省即零回归。
+   */
+  queuePolicy?: QueuePolicy;
+}
+
+/**
+ * 并发池工厂（D7/U4 导出面）：宿主经此创建并发池，无需感知实现类。
+ *
+ * 返回 ConcurrencyPool 接口而非 DefaultConcurrencyPool——barrel 导出面只认
+ * 「对象参数 + 策略枚举」，实现类可内部替换，策略差异（pi=priority /
+ * zsw=strict-fifo）显式化为参数而非两份复刻实现（深度分层公式与下限常量单源，
+ * 公式见类注释与 slots 消费方）。
+ */
+export function createConcurrencyPool(options: CreateConcurrencyPoolOptions): ConcurrencyPool {
+  return new DefaultConcurrencyPool(options.maxConcurrent, options.queuePolicy ?? "priority");
+}

package/src/execution/dialog-queue.ts

@@ -20,8 +20,70 @@
 //   直接调 handler（见 ui-request-handler-factory.ts），不经过本队列。enqueue 内仍防御性兼容
 //   fire-and-forget（万一调用方未判）：直接调 handler 返回，不入队串行。调用方不应依赖此防御。
 
+import { getLogger } from "../core/logger.ts";
+import { MAX_TIMER_DELAY_MS } from "../shared/timer-delay.ts";
+
 import { isDialogMethod } from "./ui-interaction-model.ts";
 
+const logger = getLogger("subagents");
+
+// ── dialog 超时上界（LC-3 / T2⑦，设计 docs/design/subagent-core-unbounded-wait-audit.md）──
+
+/** 分钟/秒/毫秒换算常数（与 lifecycle-manager.ts 同款命名）。 */
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+
+/** dialog 默认超时上界（30 分钟）：请求方未传 timeout 时的回收层兜底。
+ *
+ * 30 分钟是裁决值（产品语义：ask_user 挂起 30 分钟无响应视为放弃），不随 P-T2
+ * （keep-alive 分布，等后代）标定——那是无关总体。请求方需要更长等待时在协议
+ * request 上显式传 timeout（毫秒，pi ExtensionUIDialogOptions.timeout 同义）覆盖。
+ *
+ * 「等用户无限久」改为默认有界是有意的行为变更：LC-3 的两种形态（host UI promise
+ * 挂死 / 用户永不回答）原都会把 L2 processing 永久占死 → 所有子进程 ask_user 全局
+ * 死锁 + 该 child L1 队列 head-of-line 阻塞。 */
+const DEFAULT_DIALOG_TIMEOUT_MINUTES = 30;
+export const DEFAULT_DIALOG_TIMEOUT_MS =
+  DEFAULT_DIALOG_TIMEOUT_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+/**
+ * 解析一个 dialog 项的队列级上界：请求方传了合法正数 timeout 用之，否则挂默认上界。
+ * 非法值（<=0 / NaN / ±Infinity）回落默认——不因脏参数把上界拆掉（拆掉即回到 LC-3 无界）。
+ *
+ * 这里 clamp 到 MAX_TIMER_DELAY_MS 而非 fail-fast（timer-delay.ts 的 assertSafeTimerDelay
+ * 惯例是配置入口 fail-fast）：timeout 是 per-request 运行时传值，fail-fast 会把整个
+ * dialog 处理路径炸成 cancelled（伤害正常请求）；超大 timeout 的调用方意图是「近乎不限时」，
+ * clamp 到 2^31-1（约 24.8 天）是该意图在 setTimeout 域内的安全语义近似——不 clamp 会被
+ * Node 塌缩为 1ms 立即触发（语义反转：刚入队就超时）。
+ */
+function resolveDialogTimeoutMs(timeout: number | undefined): number {
+  const resolved = isValidDialogTimeout(timeout) ? timeout : DEFAULT_DIALOG_TIMEOUT_MS;
+  return Math.min(resolved, MAX_TIMER_DELAY_MS);
+}
+
+/**
+ * dialog req.timeout 合法域判定（单一权威源，A2-3）：合法正数（finite 且 > 0）才参与
+ * 超时语义——队列层据此决定上界取值（非法回落 DEFAULT_DIALOG_TIMEOUT_MS），
+ * factory 层据此决定是否透传 SDK 第三参（非法不透传，数组为空，由队列层默认上界兜底）。
+ * 两处共用本函数，禁止各写一份判定（此前两处不一致：SDK 层把 0/负数/NaN 原样透传，
+ * 队列层判非法回落默认）。
+ */
+export function isValidDialogTimeout(timeout: number | undefined): timeout is number {
+  return typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0;
+}
+
+/** 超时 settle 的日志消息（恢复指引 + 已等待时长，父进程日志是完整错误消息的承载面——
+ * pi 协议 RpcExtensionUIResponse 是封闭联合（value/confirmed/cancelled），错误文本
+ * 无法进 stdin 响应体，子 agent 侧收到的是 cancelled 语义）。 */
+function dialogTimeoutLogMessage(req: UiRequest, waitedMs: number): string {
+  return (
+    `[subagents] dialog timed out after ${waitedMs}ms without response ` +
+    `(id=${req.id}, method=${req.method}) — settled as cancelled. ` +
+    "Recovery: the requesting agent can continue and re-issue the question (重新发起提问); " +
+    "to wait longer, pass an explicit timeout (ms) on the request."
+  );
+}
+
 // ── 类型定义（本模块是 UiRequest/UiResponse/UiRequestHandler 的规范来源） ──
 // session-runner.ts 和 ui-channels.ts 复用这些类型（session-runner 再导出供测试 import）。
 
@@ -118,6 +180,11 @@ interface QueueItem {
   childPid: number | undefined;
   /** 是否已 settle（防 handler 完成 / rejectChildDialogs 重复 resolve）。 */
   settled: boolean;
+  /** 队列级超时 timer 句柄（processNext 使 item 成为 current 时挂上）。
+   *  settleItem 统一 clearTimeout——handler 永挂时 processNext 的 await 永不 resume，
+   *  其内联 clearTimeout 不可达，reject/rejectAll 抢先 settle 的路径只能靠这里清理
+   *  （A2-2：否则 timer armed 到期触发虚假「dialog timed out」warn + 句柄滞留）。 */
+  timeoutTimer?: ReturnType<typeof setTimeout>;
 }
 
 /**
@@ -137,6 +204,10 @@ interface QueueItem {
  *   - FIFO 串行：前一个 handler settle 后才处理下一个
  *   - SR-4：rejectChildDialogs(child) 把该 child 的 pending 全部 resolve 为 {cancelled:true}
  *   - handler 抛错兜底：catch → {cancelled:true} → 继续下一个（队列不卡死）
+ *   - 超时上界（LC-3/T2⑦）：每个 dialog 项必有上界——req.timeout 显式传值优先，
+ *     未传挂 DEFAULT_DIALOG_TIMEOUT_MS（30min，裁决值）；到点 settle {cancelled:true}
+ *     并 warn（恢复指引见 dialogTimeoutLogMessage），L2 processing 释放、队列继续推进。
+ *     「等用户无限久」改为默认有界是有意的行为变更。
  *   - 调用方约定只对 dialog 类调 enqueue；fire-and-forget 由调用方直接调 handler 不入队
  *（enqueue 内仍防御性兼容 fire-and-forget，但不保证行为）
  *
@@ -201,18 +272,26 @@ export class DialogGlobalQueue {
   }
 
   /**
-   * settle 一个 item（幂等）。handler 完成 / rejectChildDialogs / rejectAll 都通过本方法，
-   * settled 标志保证只 settle 一次（防竞争）。
+   * settle 一个 item（幂等）。handler 完成 / rejectChildDialogs / rejectAll / 超时 timer
+   * 都通过本方法，settled 标志保证只 settle 一次（防竞争）。
    *
    * #19 单一推进点：本方法 settle Promise + 清状态后，**唯一**调 processNext 推进队列。
    * processNext 尾部不再调 processNext（旧代码双重推进，虽靠 processing 标志幂等，但语义混乱）。
    * 为什么推进必须在 settleItem 而非 processNext 尾部：rejectChildDialogs 取消一个永不 settle
    * 的 current（handler 等用户输入卡死）时，processNext 的 `await item.handler` 永不 resume，
    * 尾部不会执行；只有 settleItem 里的 processNext 才能打破死锁，推进下一个。
+   *
+   * [A2-2] 超时 timer 清理也统一收口在这里：任何路径抢先 settle（reject/rejectAll/超时
+   * 自身）都必须撤下 armed timer——handler 永挂时 processNext 内联的 clearTimeout 不可达，
+   * 不在这里清则 timer 到期触发虚假「dialog timed out」warn 且句柄滞留至超时点。
    */
   private settleItem(item: QueueItem, resp: UiResponse): void {
     if (item.settled) return;
     item.settled = true;
+    if (item.timeoutTimer) {
+      clearTimeout(item.timeoutTimer);
+      item.timeoutTimer = undefined;
+    }
     item.resolve(resp);
     // 若是正在处理的项，清空 current/processing 并推进队列（唯一推进点）。
     // 非当前项（队列中被 reject）只 settle Promise，不影响 current/推进。
@@ -263,6 +342,14 @@ export class DialogGlobalQueue {
    *
    * handler 抛错兜底（TC-E4 case 3）：catch → settle {cancelled:true} → 继续。
    * 不能让一个失败卡死队列（processing 永远 true）。
+   *
+   * LC-3/T2⑦ 超时上界：`await item.handler` 原本无上界——host UI promise 挂死或用户
+   * 永不回答时 processing 恒 true（全局 dialog 死锁）。现在每项挂队列级 timer：
+   * req.timeout（请求方显式传值）优先，未传/非法挂 DEFAULT_DIALOG_TIMEOUT_MS。
+   * 到点 settle {cancelled:true}（完整错误消息落父进程日志，含恢复指引与等待时长），
+   * settleItem 的 settled 标志保证与 handler 完成 / rejectChildDialogs 三方竞态下
+   * 恰 settle 一次。timer 回调闭包捕获 item（非读 this.current）：迟到触发时
+   * settled 标志已置位，直接 noop，不误伤后继项。
    */
   private async processNext(): Promise<void> {
     if (this.processing) return;
@@ -270,12 +357,23 @@ export class DialogGlobalQueue {
     this.processing = true;
     const item = this.queue.shift()!;
     this.current = item;
+    const timeoutMs = resolveDialogTimeoutMs(item.req.timeout);
+    const timer = setTimeout(() => {
+      // [A2-2] 已被抢先 settle（正常 settle 时 timer 已被 settleItem 清除，这里是防御性
+      // 兜底）：静默返回，不发虚假「dialog timed out」warn、不重复 settle。
+      if (item.settled) return;
+      logger.warn(dialogTimeoutLogMessage(item.req, timeoutMs));
+      this.settleItem(item, { cancelled: true });
+    }, timeoutMs);
+    item.timeoutTimer = timer;
     try {
       const resp = await item.handler(item.req);
-      // handler 完成：settle（若已被 rejectChildDialogs 抢先 settle 则 noop）。
+      clearTimeout(timer);
+      // handler 完成：settle（若已被超时 timer / rejectChildDialogs 抢先 settle 则 noop）。
       // settleItem 内会清 current/processing 并推进队列（#19 单一推进点）。
       this.settleItem(item, resp);
     } catch {
+      clearTimeout(timer);
       // handler 抛错兜底：回 cancelled，不向上抛（队列不能卡死）
       this.settleItem(item, { cancelled: true });
     }