@zhushanwen/subagent-core 0.2.0

package/src/execution/finalize-record.ts

@@ -0,0 +1,254 @@
+// src/execution/finalize-record.ts
+//
+// 时序收尾逻辑（从 subagent-service.ts 提取，降低主文件行数 < 1000 上限）。
+//
+// D-017 时序：collectPatch → completeRecord → archive → cleanup(finalized+worktree+
+// aliveMarker+pending注销) → manifest(最后 best-effort)。
+//
+// [Critical #1 / PR #85] cleanup 全部在 manifest 写之前执行——manifest 是诊断辅助
+//（orphan recovery），写失败仅记录不阻断。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup，
+// 导致磁盘满/权限错时 worktree 泄漏 + finalized marker 不写 + alive marker 残留 +
+// pending 记账错乱。现 manifest 写移到 Step 4（最后），best-effort（console.error +
+// appendEntry，不 throw）。
+//
+// B9 兜底：completeRecord/archive 抛错→后续 cleanup/manifest 仍执行。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { getLogger } from "../core/logger.ts";
+
+import { removeAliveMarker } from "./alive-store.ts";
+import { bestEffort } from "./best-effort.ts";
+import { completeRecord } from "./execution-record.ts";
+import { writeFinalized } from "./finalized-marker.ts";
+import type { ManifestStore } from "./manifest-store.ts";
+import type { ModelConfigService } from "./model-config-service.ts";
+import { getSubagentSessionDir } from "./path-encoding.ts";
+import type { RecordStore } from "./record-store.ts";
+import { writeCancelledTombstone } from "./tombstone-store.ts";
+import type { AgentResult, ClosedReason, ExecutionRecord } from "./types.ts";
+import type { WorktreeManager } from "./worktree-manager.ts";
+
+const logger = getLogger("subagents");
+
+/** doFinalizeRecord 的依赖（从 SubagentService 注入，避免 this 绑定 + 解耦可测试）。 */
+export interface FinalizeDeps {
+  manifestStore: ManifestStore;
+  worktreeManager: WorktreeManager;
+  store: RecordStore;
+  modelService: ModelConfigService;
+  /** Pi ExtensionAPI（仅用 appendEntry 记录 manifest 写失败事件）。null 在 dispose 后。 */
+  pi: { appendEntry?: (type: string, data: unknown) => void } | null;
+  /** pending-notifications 终态注销（绑定 pi.events.emit，由调用方闭包提供）。 */
+  emitUnregister(id: string, status: string): void;
+  // [review 修复] 已删除 redeliverPending 回调（MF-1 消费确认制补投）：pendingMessages
+  // 三段消费链随 deliverToRunning 一并移除（无生产调用方，死机制）。
+}
+
+/**
+ * 时序收尾（D-017）。步骤 0→4 全部 best-effort 互不阻断（除 manifest 外都幂等）。
+ *
+ * [Critical #1] Step 3 cleanup 全部在 Step 4 manifest 之前——manifest 写失败仅 console.error +
+ * appendEntry，不 throw 不跳过 cleanup。task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord
+ * 补字段），manifestToSubagent 投影真实值而非硬编码空串。
+ */
+export async function doFinalizeRecord(
+  deps: FinalizeDeps,
+  record: ExecutionRecord,
+  result: AgentResult,
+  status: "closed",
+  closedReason?: ClosedReason,
+): Promise<void> {
+  // ── Step 0: collectPatch（best-effort）──
+  // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
+  //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
+  if (record.worktreeHandle) {
+    try {
+      const sessionsDir = getSubagentSessionDir(
+        deps.modelService.getAgentDir(),
+        record.worktreeHandle.mainCwd,
+      );
+      fs.mkdirSync(sessionsDir, { recursive: true });
+      const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
+      const patch = await deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
+      if (patch.written) record.patchFile = patchFile;
+    } catch (pe: unknown) {
+      bestEffort(pe, "collectPatch (finalizeRecord Step0)");
+    }
+  }
+
+  // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
+  try {
+    completeRecord(record, result, status, closedReason);
+  } catch (err) {
+    bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 2: archive（B9: 抛错→后续仍执行）──
+  try {
+    deps.store.archive(record);
+  } catch (err) {
+    bestEffort(err, "store.archive (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 3: finalized + cleanup + aliveMarker + pending注销（全部先执行，幂等）──
+  // [Critical] 清理必须在 manifest 写入之前：worktree cleanup / finalized marker / aliveMarker
+  //   都是幂等且不可跳过的副作用。绝不能因 manifest 写失败而跳过 worktree cleanup
+  //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
+  if (record.sessionFile) {
+    try {
+      // MF-1 fix / v4 B-1: cancelled（closedReason='cancelled'）写 tombstone 而非 finalized，防重建丢失 cancelled
+      if (closedReason === "cancelled") {
+        writeCancelledTombstone(record.sessionFile, {
+          id: record.id,
+          status: "cancelled",
+          agent: record.agent,
+          startedAt: record.startedAt,
+          endedAt: record.endedAt ?? Date.now(),
+        });
+      } else {
+        // [v8.5 A2] 真实 reason 写入 sidecar 内容（旧格式是空文件）：磁盘重建时用它
+        // 还原 closedReason，不再一律硬编码 gc。cancelled 之外的全部原因（gc /
+        // user-close / parent-*）都经此路径持久化。
+        writeFinalized(record.sessionFile, closedReason);
+      }
+    } catch (err) {
+      bestEffort(err, "writeFinalized/tombstone (finalizeRecord Step3)");
+    }
+  }
+  if (record.worktreeHandle) {
+    try {
+      await deps.worktreeManager.cleanup(record.worktreeHandle);
+    } catch (err) {
+      bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
+    }
+  }
+  if (record.sessionFile) {
+    try {
+      removeAliveMarker(record.sessionFile);
+    } catch (err) {
+      bestEffort(err, "removeAliveMarker (finalizeRecord Step3)");
+    }
+  }
+
+  // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
+  deps.emitUnregister(record.id, status);
+
+  // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
+  // [Critical #1] manifest 是诊断辅助（orphan recovery），不是正确性依赖。写失败时
+  //   仅记录（console.error + appendEntry），绝不让 manifest 写失败跳过上面的 worktree
+  //   cleanup 或抛出打断 finalize 链。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup。
+  //   task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord 补字段），
+  //   manifestToSubagent 投影时用真实值而非硬编码空串。
+  try {
+    await deps.manifestStore.writeManifest({
+      id: record.id,
+      rootSessionId: record.rootSessionId ?? "",
+      parentRecordId: record.parentRecordId,
+      agentName: record.agent,
+      // v4 B-1: manifest status 统一为 closed（cancelled 折入 closed，区分靠 tombstone sidecar）
+      status: "closed",
+      createdAt: record.startedAt,
+      completedAt: record.endedAt ?? Date.now(),
+      sessionFile: record.sessionFile,
+      task: record.task,
+      slug: record.slug,
+      model: record.model,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.error(`[subagent] manifest 写入失败 (record=${record.id}): ${msg}`);
+    deps.pi?.appendEntry?.("subagent:manifest-write-failed", {
+      id: record.id,
+      error: msg,
+    });
+  }
+}
+
+/**
+ * 对话模式轮次完成收尾：record 进 idle 态（非终态化，等待续聊）。
+ *
+ * 与 doFinalizeRecord 的关键区别（M2-A idle 语义）：
+ *   - 不调 completeRecord（record 不冻结，保留 turns[] 等运行时状态供续聊累积）
+ *   - 不调 store.archive（record 留内存，getMutable 可查、list 可见）
+ *   - 不 cleanup worktree（保留对话模式工作目录）
+ *   - 不写 manifest（idle 非终态，manifest 是终态诊断辅助）
+ *   - 删 .alive marker（进程已 SIGTERM 回收，不再是活进程）
+ *   - emitUnregister（进程已死，从 pending 活跃后代差集移除；record 留内存不 archive）
+ *
+ * MF-2：设 record.result = result.text（否则 notifier idle 回复正文恒为 "(empty)"，
+ *   G1/G2 多轮回复送达不成立）。失败轮次（result.success=false，MF-6 回退 idle 路径）
+ *   的 result.text 可能为空，用 result.error 兜底让 notify 可读。
+ *
+ * 状态：record.status = "idle"（覆盖 tryTransition 设的 done/failed），record.round += 1。
+ * 各步骤 best-effort 互不阻断（参照 doFinalizeRecord 的 bestEffort 用法）。
+ *
+ * @param deps 与 doFinalizeRecord 同源（从 SubagentService 注入）
+ * @param result 本轮 AgentResult（MF-2：result.text 写入 record.result 供 notifier idle 回复）
+ */
+export async function doFinalizeRoundToIdle(
+  deps: FinalizeDeps,
+  record: ExecutionRecord,
+  result: AgentResult,
+): Promise<void> {
+  // MF-2：设 record.result 供 notifier idle 回复正文（否则恒 "(empty)"，G1/G2 不成立）。
+  // MF-6 兜底：失败轮次（success=false）的 result.text 可能为空，用 error 让 notify 可读。
+  // [R2-1] 轮终写点恒写非空：one-shot 空文本成功完成（collectResult getFullText 返回 ""、
+  // success=true、真实可达，本写点被 subagent-service runAndFinalize 的成功分支共用）首轮
+  // result 前值 undefined，兜底补 "(empty)" 占位——措辞与 notifier buildLlmContent 的
+  // `record.result ?? "(empty)"` 兜底同款，通知文案逐字节不变（[增量 G2] G4 取舍保持）。
+  // 轮终信号优先：record.result 非 undefined 是 renderer hasRunning 排除「轮终
+  // running-resumable」的判据（shared SubagentRecord.result 契约），保持 undefined 会让
+  // 完成注入后末位 turn 永久「工作中」。续轮（前值存在）沿用前值：one-shot 无增量语义，
+  // record.result = 该 subagent 最终输出。chatMode 空增量轮 → 固定占位
+  // "(no output this round)"（D5：增量语义下沿用旧 record.result = 上一轮增量，本轮通知
+  // 正文 = 上一轮内容，父 agent 误读为原样重复回复）。
+  let nextResult: string | undefined;
+  if (result.text) {
+    nextResult = result.text;
+  } else if (result.error) {
+    nextResult = `round did not complete: ${result.error}`;
+  } else if (record.chatMode) {
+    nextResult = "(no output this round)";
+  } else {
+    nextResult = record.result ?? "(empty)";
+  }
+  record.result = nextResult;
+
+  // 删 .alive marker（进程已 SIGTERM 回收）。
+  // sessionFile 窗口期可能 undefined（极少——对话模式轮次完成意味着 session 已跑过），
+  // 缺失时跳过但仍设内存 idle（重启后磁盘重建会落到 crashed，边界可接受）。
+  if (record.sessionFile) {
+    try {
+      removeAliveMarker(record.sessionFile);
+    } catch (err) {
+      bestEffort(err, "removeAliveMarker (doFinalizeRoundToIdle)");
+    }
+  }
+
+  // pending-notifications：进程已死，从活跃后代差集移除（record 留内存不 archive，
+  // v4 B-1：record 现为 running-resumable，但 pending 注册的是进程活跃性，进程死了需注销）。
+  deps.emitUnregister(record.id, "running");
+
+  // 状态机（v4 B-1）：record 保持 running（旧 idle 折入 running，覆盖 tryTransition 设的 closed，
+  // 可冷路径 resume），轮次计数 +1。idleSince 时间戳独立保留供 GC 判据。
+  // [S10] closedReason 同步清除：调用方（runAndFinalize catch / MF-6 分支）先 tryTransition
+  // 设了 closed+closedReason 再回退 running——不清则 "gc"/"cancelled" 残留在 running record 上，
+  // 泄漏进 list 投影与后续 notify 载荷（toNotifyRecord 透传 record.closedReason），让一个
+  // 活跃 record 看起来像已被某原因关闭过。
+  record.status = "running";
+  record.closedReason = undefined;
+  record.round = (record.round ?? 0) + 1;
+  record.idleSince = Date.now();
+  // 执行态信号（residual-fixes）：轮终回 running-resumable = 无活进程驱动（idle timer
+  // 回收/保活等待续聊），GUI 侧据此判 waiting（非 streaming）。冷路径续轮（进程启动）清除。
+  record.resumable = true;
+
+  // W16 [D4]：轮终回 running-resumable 是类外状态写点（record 留内存不走 archive），
+  // 显式上报迁移——entry 携带新 round 与本轮 result，pi 文件的重建源不滞后。
+  deps.store.reportRecordTransition(record);
+
+  // [review 修复] 已删除残留 pendingMessages 的 redeliverPending 补投段（MF-1 消费
+  // 确认安全网）：三段消费链随 deliverToRunning 一并移除，本段不可达。
+}

package/src/execution/finalized-marker.ts

@@ -0,0 +1,70 @@
+// src/runtime/execution/finalized-marker.ts
+//
+// Finalized 状态的 sidecar 持久化。
+//
+// 背景：subagent 执行完成（done/failed）后，session.jsonl 的最终写入可能因进程
+// 异常终止而丢失。`.finalized` sidecar 标记该 session 已正常结束，collectRecords
+// 重建时可用它区分「正常结束但文件截断」与「执行中断」。
+//
+// 设计：对称 cancelled sidecar（tombstone-store.ts）。`.finalized` 内容为可选的
+// 关闭原因字符串（v8.5 起 writeFinalized 第二参数写入），旧格式为空文件——空内容
+// 表示死因不可考，磁盘重建兜底 closedReason=disconnected（不再误导为 gc）。
+// 与 `.cancelled` 互斥——一个 session 要么 finalized 要么 cancelled，不可能两者兼有。
+//
+// best-effort：写 IO 错静默，不阻断主流程。
+
+import * as fs from "node:fs";
+
+// ============================================================
+// 公开函数
+// ============================================================
+
+/**
+ * 在 session.jsonl 旁写 `.finalized` sidecar。
+ * best-effort：任何 I/O 错误静默（finalize 标记是次要信号，status 已在内存 record 上设好）。
+ *
+ * 与 `.cancelled` 互斥（BC-4）：写前删除 `.cancelled`（如存在），确保不会两者共存。
+ *
+ * @param sessionFile session.jsonl 绝对路径
+ * @param reason 可选的 L2 关闭原因写入 sidecar 内容（v8.5 起）：磁盘重建时用它区分
+ *        真实死因（user-close / parent-* 等），替代旧的「一律 gc」误导标签。传
+ *        undefined = 空文件（旧格式兼容：未知死因，重建兜底 disconnected）。
+ */
+export function writeFinalized(sessionFile: string, reason?: string): void {
+  try {
+    // BC-4 互斥：清理可能存在的 .cancelled。force:true 静默 ENOENT——
+    // 未 cancel 过的 session（done/failed/aborted）本就无 .cancelled，属正常路径。
+    // 此前用 unlinkSync+bestEffort 记 console.debug，取消嵌套链条时每层 ENOENT 刷屏。
+    fs.rmSync(`${sessionFile}.cancelled`, { force: true });
+    fs.writeFileSync(`${sessionFile}.finalized`, reason ?? "", "utf-8");
+  } catch (_e) {
+    void _e; // 静默：写失败不阻断 finalize 主流程。
+  }
+}
+
+/**
+ * 读 session.jsonl 旁的 `.finalized` sidecar 内容携带的关闭原因。
+ * 返回 trim 后的字符串：sidecar 存在时可能为空串（旧格式空文件 / 未携 reason）。
+ * 返回 undefined：sidecar 不存在 / 读取失败（与空串区分「没正常结束过」）。
+ */
+export function readFinalizedReason(sessionFile: string): string | undefined {
+  try {
+    return fs.readFileSync(`${sessionFile}.finalized`, "utf-8").trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 读 session.jsonl 旁的 `.finalized` sidecar 是否存在。
+ * 返回 true：sidecar 存在（内容不校验，存在性即信号）。
+ * 返回 false：sidecar 不存在 / 读取失败。
+ */
+export function readFinalized(sessionFile: string): boolean {
+  try {
+    fs.accessSync(`${sessionFile}.finalized`);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/execution/get-state-handshake.ts

@@ -0,0 +1,104 @@
+// src/execution/get-state-handshake.ts
+//
+// FR-4: get_state RPC 握手逻辑。
+//
+// 从 session-runner.ts 提取（保持文件 < 1000 行）。职责单一：通过 get_state RPC
+// 查询子进程 sessionFile/sessionId，带超时重试。session-runner spawn 后无条件调用。
+//
+// 设计要点：
+//   - 重试节奏：单次超时 GET_STATE_TIMEOUT_MS（2s）后，等 GET_STATE_RETRY_INTERVAL_MS（500ms）
+//     再发起下一次 get_state，最多 GET_STATE_MAX_RETRIES（3）次。修复点：旧实现超时后
+//     立即递归 tryOnce()，GET_STATE_RETRY_INTERVAL_MS 声明了却从未使用（eslint error 阻断），
+//     现在让常量名与行为一致——重试前真的等间隔。
+//   - 加速路径：sessionFile 一旦拿到立即 resolve（不等剩余重试）。
+//   - 全部超时：resolve 空对象（调用方走兜底查找）。
+
+import type { ChildProcess } from "node:child_process";
+
+import { sendGetStateCommand } from "./stdin-writer.ts";
+
+/** FR-4: get_state RPC 握手最大重试次数。 */
+const GET_STATE_MAX_RETRIES = 3;
+/** FR-4: get_state RPC 握手重试间隔（ms）——单次超时后等待此间隔再重试。 */
+const GET_STATE_RETRY_INTERVAL_MS = 500;
+/** FR-4: get_state RPC 握手单次超时（ms）。 */
+const GET_STATE_TIMEOUT_MS = 2000;
+
+/** get_state 握手结果。 */
+export interface GetStateResult {
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+/**
+ * FR-4: 通过 get_state RPC 查询子进程获取 sessionFile/sessionId。
+ *
+ * 当 stdout header 未获取到 sessionFile 时，尝试通过 get_state RPC 查询。
+ * 最多重试 GET_STATE_MAX_RETRIES 次，单次超时 GET_STATE_TIMEOUT_MS 后等待
+ * GET_STATE_RETRY_INTERVAL_MS 再发起下一次重试。
+ *
+ * @param child 子进程（stdin 写入 get_state 命令）
+ * @param addResponseListener 注册 response 监听器的函数（stdout pump 中调用）
+ * @returns 握手结果（可能为空——所有重试均超时/失败）
+ */
+export function performGetStateHandshake(
+  child: ChildProcess,
+  addResponseListener: (id: string, resolver: (data: unknown) => void) => void,
+): Promise<GetStateResult> {
+  return new Promise<GetStateResult>((resolve) => {
+    const collected: GetStateResult = {};
+    let attempts = 0;
+    let resolved = false;
+
+    function tryOnce(): void {
+      if (resolved) return;
+      attempts++;
+      const reqId = sendGetStateCommand(child);
+
+      // [#15] 本次 tryOnce 私有的 timer（2s 超时 + 超时后派生的 retry）。
+      // 关键：response 回调通过闭包引用的是"本次 tryOnce 对应的 timer"，而非某个
+      // 外层共享变量——即便后续 tryOnce(#2) 重新发起请求，旧 reqId 的迟到 response 回调
+      // 闭包仍指向它自己那次 tryOnce 的 timer，不会误清新 reqId 的 timer。retry 句柄也
+      // 一并捕获，response 到达时同步取消"已在排队但尚未触发的下一次重试"。
+      let pendingRetry: ReturnType<typeof setTimeout> | undefined;
+      const timer: ReturnType<typeof setTimeout> = setTimeout(() => {
+        pendingRetry = undefined;
+        // 单次超时：等待间隔后重试，或放弃
+        if (attempts < GET_STATE_MAX_RETRIES && !resolved) {
+          // [Bug fix] 旧实现直接 tryOnce() 立即重试，GET_STATE_RETRY_INTERVAL_MS 声明却
+          // 从未使用（eslint error 阻断 commit）。现在重试前等待间隔，让常量名与行为一致。
+          pendingRetry = setTimeout(() => tryOnce(), GET_STATE_RETRY_INTERVAL_MS);
+          pendingRetry.unref();
+        } else if (!resolved) {
+          resolved = true;
+          resolve(collected);
+        }
+      }, GET_STATE_TIMEOUT_MS);
+      timer.unref();
+
+      addResponseListener(reqId, (data: unknown) => {
+        if (resolved) return;
+        // [#15] 闭包清理本次 tryOnce 的 timer（2s 超时 + 排队中的 retry），不碰其他 reqId 的 timer。
+        clearTimeout(timer);
+        if (pendingRetry) clearTimeout(pendingRetry);
+        if (data && typeof data === "object") {
+          const d = data as Record<string, unknown>;
+          if (typeof d.sessionFile === "string" && d.sessionFile.length > 0) {
+            collected.sessionFile = d.sessionFile;
+          }
+          if (typeof d.sessionId === "string" && d.sessionId.length > 0) {
+            collected.sessionId = d.sessionId;
+          }
+        }
+        // sessionFile 已获取——立即 resolve（无需更多重试）
+        if (collected.sessionFile) {
+          resolved = true;
+          resolve(collected);
+        }
+        // 否则等待超时重试
+      });
+    }
+
+    tryOnce();
+  });
+}

package/src/execution/host-mode.ts

@@ -0,0 +1,56 @@
+// src/execution/host-mode.ts
+//
+// 主进程运行模式分类工具。
+//
+// 将 Pi 的 ExtensionMode（"tui"|"rpc"|"json"|"print"）聚合为业务语义的
+// HostMode（"tui"|"gui"|"headless"），供 session-runner 的 W4 提示词守卫、
+// handler 工厂分流、stdio 选择等消费点统一调用。
+//
+// 判定依据见 AGENTS.md「运行时环境区分」章节 +
+// docs/extensions/pi-tui-development-guide.md 第四部分第 8 节。
+// ExtensionMode 来自 Pi 源码 packages/coding-agent/src/core/extensions/types.ts:299
+// （dist 中 core/extensions/types.d.ts:207）。
+//
+// 设计动机（.fix-plans/00-master-summary.md §一冲突 4）：
+//   - 把散落多处的 `ctx.mode === "tui" || ctx.mode === "rpc"` 字面量比较
+//     集中到单一修改点，未来 Pi 新增 mode 值时只改本文件。
+//   - 业务语义命名（"gui"/"headless"）比原始枚举值更清晰表达意图。
+
+// ExtensionMode 在 Pi SDK 的 core/extensions/types.d.ts 中定义为
+// `"tui" | "rpc" | "json" | "print"`（ExtensionContext.mode 的类型），但未从包根
+// 导出。这里定义与 SDK 同构的本地别名（ctx.mode 的字面量联合），由同包其他模块复用，
+// 避免依赖未导出的内部类型。
+export type ExtensionMode = "tui" | "rpc" | "json" | "print";
+
+/** 主进程运行模式分类。基于 ExtensionMode 聚合为业务语义。
+ *  - "tui"：纯 Pi TUI，ctx.ui.custom 可用，用户在终端交互
+ *  - "gui"：xyz-agent GUI，通过 rpc sidecar 通道与前端 Vue 组件交互
+ *  - "headless"：无交互 UI 通道（json/print 输出模式，或 mode 未穿透） */
+export type HostMode = "tui" | "gui" | "headless";
+
+/** 从 ExtensionContext.mode 解析主进程模式分类。
+ *  - "tui" → tui（纯 Pi TUI，ctx.ui.custom 可用）
+ *  - "rpc" → gui（xyz-agent GUI，sidecar 通道可用）
+ *  - "json"/"print"/undefined → headless（无交互通道）
+ *
+ *  undefined 归入 headless 是向后兼容：mode 未穿透 SessionRunnerContext 时
+ *  按「无 UI」保守处理，避免误注入依赖 UI 的逻辑。 */
+export function resolveHostMode(mode: ExtensionMode | undefined): HostMode {
+  if (mode === "tui") return "tui";
+  if (mode === "rpc") return "gui";
+  return "headless"; // json/print/undefined
+}
+
+/** 主进程是否会响应子进程的 ask_user（UI 透传）。
+ *  tui + gui 都会（冲突 3 裁决：TUI 必须注入 handler；GUI 透传所有 UI），
+ *  headless 不会（无 UI 通道，注入 W4 提示词会误导 LLM）。 */
+export function willRespondToAskUser(mode: ExtensionMode | undefined): boolean {
+  const host = resolveHostMode(mode);
+  return host === "tui" || host === "gui";
+}
+
+/** 主进程是否有交互 UI 通道（TUI 组件 / GUI sidecar）。
+ *  非 headless 即有。用于 stdio 选择等不区分 tui/gui 的决策点。 */
+export function hasInteractiveUI(mode: ExtensionMode | undefined): boolean {
+  return resolveHostMode(mode) !== "headless";
+}

package/src/execution/idle-gc.ts

@@ -0,0 +1,47 @@
+/**
+ * SP-4 idle record GC：30 天 TTL 定时归档，防 idle record 永久驻留内存。
+ * 从 subagent-service.ts 抽出（文件超 max-lines；逻辑自包含：interval + TTL 扫描）。
+ * 启动幂等由调用方（service.startGcTimer）守卫；返回 stop 函数供 dispose 清理。
+ */
+import { getLogger } from "../core/logger.ts";
+import { bestEffort } from "./best-effort.ts";
+import { isResumable } from "./lifecycle-predicates.ts";
+import type { RecordStore } from "./record-store.ts";
+
+const logger = getLogger("subagents");
+
+/** GC 扫描间隔：1 小时。 */
+// eslint-disable-next-line no-magic-numbers -- 60*60*1000 = 1h 的毫秒换算常数
+const GC_INTERVAL_MS = 60 * 60 * 1000;
+/** idle record TTL：30 天（超龄归档）。 */
+// eslint-disable-next-line no-magic-numbers -- 30*24*60*60*1000 = 30d 的毫秒换算常数
+const IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** 毫秒/天（GC 日志的 d 换算）。 */
+// eslint-disable-next-line no-magic-numbers -- 24*60*60*1000 = 1d 的毫秒换算常数
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * 启动 idle record GC 定时器，返回 stop 函数（清理 interval；幂等）。
+ * 每个扫描周期：对 store 内全部 active record 中 resumable 且带 idleSince 的，
+ * 超过 IDLE_TTL_MS 的归档（archive 单条失败不阻断其余，bestEffort 留痕）。
+ */
+export function startIdleGc(store: RecordStore): () => void {
+  const timer = setInterval(() => {
+    const now = Date.now();
+    for (const record of store.listAllActive()) {
+      if (isResumable(record) && record.idleSince) {
+        const age = now - record.idleSince;
+        if (age > IDLE_TTL_MS) {
+          logger.warn(`[subagents] GC: archiving idle record ${record.id} (idle for ${Math.round(age / MS_PER_DAY)}d)`);
+          try {
+            store.archive(record);
+          } catch (err) {
+            bestEffort(err, `GC archive record ${record.id}`);
+          }
+        }
+      }
+    }
+  }, GC_INTERVAL_MS);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}