@zhushanwen/pi-subagent-workflow 9.4.0 → 9.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "9.4.0",
+  "version": "9.4.1",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -58,22 +58,22 @@
     ]
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.19.0",
+    "@zhushanwen/extension-protocol": "0.20.0",
     "@zhushanwen/session-delivery": "1.1.0",
-    "@zhushanwen/pi-ext-guards": "0.4.3",
+    "@zhushanwen/pi-ext-guards": "0.4.4",
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/pi-notify-ledger-host": "0.3.1",
-    "@zhushanwen/pi-subagent-cli": "0.7.0",
-    "@zhushanwen/zcode-subagent-cli": "0.6.0",
-    "@zhushanwen/subagent-core": "1.4.0"
+    "@zhushanwen/pi-notify-ledger-host": "0.3.2",
+    "@zhushanwen/subagent-core": "1.5.0",
+    "@zhushanwen/pi-subagent-cli": "0.7.1",
+    "@zhushanwen/zcode-subagent-cli": "0.7.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^1.0.0",
     "@earendil-works/pi-coding-agent": "^1.0.0",
     "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27",
-    "@zhushanwen/pi-structured-output": "6.1.0",
-    "@zhushanwen/pi-pending-notifications": "0.8.3"
+    "@zhushanwen/pi-pending-notifications": "0.8.4",
+    "@zhushanwen/pi-structured-output": "6.1.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -87,7 +87,7 @@
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-engine-sdk": "0.10.0"
+    "@zhushanwen/subagent-engine-sdk": "0.10.1"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/src/host/pi-host.ts

@@ -107,12 +107,15 @@ export function corePackageNpmRoot(moduleUrl: string = import.meta.url): string
  * `<Resources>/extensions/@zhushanwen/pi-subagent-workflow/index.js`），其**父目录**
  * 正是 `@zhushanwen` scope 目录——npm 槽语义（"一级子项 = 包目录"）恰好成立，
  * 于是可直接当 npm 槽根用：约定目录扫描即命中
- * `pi-subagent-workflow/{workflows,agents}`（两目录由 `scripts/bundle-extensions.mjs`
- * 随包拷贝；`pi.agents`/`pi.workflows` manifest 约定及其"声明路径不存在 → 整包失败
- * 占位"语义是 subagent-core resource-discovery 的 taiji 自建规则，权威源 =
- * resource-discovery.ts processPackage——pi 上游 manifest 只有
- * extensions/skills/prompts/themes 四字段，无 agents/workflows 概念。已核仓内无任何
- * 包声明该字段，故扫描面内所有包都走约定目录分支，不进 manifest 失败分支）。
+	 * `pi-subagent-workflow/{workflows,agents}`（两目录由 `scripts/bundle-extensions.mjs`
+	 * 随包拷贝；`pi.agents`/`pi.workflows` manifest 约定及其"声明路径不存在 → 整包失败
+	 * 占位"语义是 subagent-core resource-discovery 的 taiji 自建规则，权威源 =
+	 * resource-discovery.ts processPackage——pi 上游 manifest 只有
+	 * extensions/skills/prompts/themes 四字段（锚 = pi-coding-agent
+	 * dist/core/pi-manifest.js:3 RESOURCE_FIELDS，pi@1.0.0 已核；同源登记见
+	 * docs/extensions/extension-conventions.md「readPiManifest」条），无 agents/workflows
+	 * 概念。已核仓内无任何包声明该字段，故扫描面内所有包都走约定目录分支，不进
+	 * manifest 失败分支）。
  *
  * 与 dev/npm 形态的既有语义一致：npm 槽根扫的就是 scope 下全部包目录（因此本包自带
  * 的 workflows/agents 在 dev/npm 形态同样入发现面），非新增语义。

package/src/interface/command/commands.ts

@@ -51,6 +51,13 @@ const STATUS_ORDER: Record<string, number> = {
 /** 未知 status 的默认排序权重（排在已知 status 之后）。 */
 const UNKNOWN_STATUS_WEIGHT = 9;
 
+/** RPC 非 lifecycle 通知 action 词表（abort/resume 之外的三个纯 notify 分支——
+ *  rpcSideNotify 的穷举域；abort/resume 在 handleRpcMode 内 if 早退）。 */
+type WorkflowRpcSideAction = Extract<
+  WorkflowRpcAction,
+  { action: "lifecycle-removed" | "lifecycle-missing-id" | "noop" }
+>;
+
 // ── /workflows command ───────────────────────────────────────
 
 /**
@@ -129,41 +136,7 @@ export function registerWorkflowsCommand(
         return;
       }
 
-      // TUI 动词命令：/workflows resume <runId>——执行断点续跑后 notify，不打开面板
-      // （abort 动词在 TUI 侧无既有通道，不在此顺手扩——resume 是本批接入面）
-      const trimmedArgs = args.trim();
-      const [verb, ...rest] = trimmedArgs.split(/\s+/).filter(Boolean);
-      if (verb === "resume") {
-        const runId = rest[0];
-        if (!runId) {
-          ctx.ui.notify("Usage: /workflows resume <runId> [model]", "warning");
-          return;
-        }
-        // 可选第二参数 = 显式模型 canonical ref（'provider/modelId[:thinkingLevel]'）——
-        // 落统一覆盖记账（F1-26 后续项：与 setModel 补切同通道，resume 合一步表达）。
-        const model = rest[1];
-        try {
-          if (model !== undefined) assertResumeModelInCatalog(model);
-          await resumeRun(runId, deps, ...(model !== undefined ? [{ model }] : []));
-          ctx.ui.notify(
-            `Workflow ${runId}: resuming${model !== undefined ? ` with model ${model}` : ""} — completed calls replay at zero token cost, unfinished calls re-dispatched`,
-            "info",
-          );
-        } catch (err) {
-          ctx.ui.notify(`Failed to resume workflow ${runId}: ${toErrorMessage(err)}`, "warning");
-        }
-        return;
-      }
-
-      // 直接按 runId / 前缀匹配打开
-      const directRunId = trimmedArgs;
-      if (directRunId) {
-        await openByRunId(directRunId, getRuns, ctx, deps);
-        return;
-      }
-
-      // 无参——列表选择
-      await openFromList(getRuns, ctx, deps);
+      await handleTuiCommand(args, ctx, getRuns, deps);
     },
   });
 }
@@ -182,38 +155,36 @@ export function registerWorkflowsCommand(
  *   （F3 定稿——提示语义优先于 missing-id：run 一次性生命周期后不可挂起）
  * - lifecycle-missing-id → Usage 提示
  * - noop → 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
+ *
+ * 分派形态：两个 lifecycle 动作 if 早退（控制流收窄，零断言），其余三个纯
+ * notify action 收敛进 rpcSideNotify 的穷举 switch。
  */
 async function handleRpcMode(
   parsed: WorkflowRpcAction,
   ctx: ExtensionCommandContext,
   deps: LauncherDeps,
 ): Promise<void> {
+  if (parsed.action === "abort") {
+    await abortWithNotify(parsed.runId, deps, ctx);
+    return;
+  }
+  if (parsed.action === "resume") {
+    await resumeWithNotify(parsed.runId, parsed.model, deps, ctx);
+    return;
+  }
+  rpcSideNotify(parsed, ctx);
+}
+
+/**
+ * 非 lifecycle RPC action（lifecycle-removed / lifecycle-missing-id / noop）的
+ * 穷举 notify 分派。default 保留 exhaustiveness 断言：未来新增 action verb 忘加
+ * case 时 tsc 报错。
+ */
+function rpcSideNotify(
+  parsed: WorkflowRpcSideAction,
+  ctx: ExtensionCommandContext,
+): void {
   switch (parsed.action) {
-    case "abort": {
-      try {
-        await abortRun(parsed.runId, deps);
-        // abort 单态后 pastTense 固定（原三态拼接随 pause/resume 删除）
-        ctx.ui.notify(`Workflow ${parsed.runId}: aborted`, "info");
-      } catch (err) {
-        const msg = toErrorMessage(err);
-        ctx.ui.notify(`Failed to abort workflow ${parsed.runId}: ${msg}`, "warning");
-      }
-      return;
-    }
-    case "resume": {
-      try {
-        if (parsed.model !== undefined) assertResumeModelInCatalog(parsed.model);
-        await resumeRun(parsed.runId, deps, ...(parsed.model !== undefined ? [{ model: parsed.model }] : []));
-        ctx.ui.notify(
-          `Workflow ${parsed.runId}: resuming${parsed.model !== undefined ? ` with model ${parsed.model}` : ""} — completed calls replay at zero token cost, unfinished calls re-dispatched`,
-          "info",
-        );
-      } catch (err) {
-        const msg = toErrorMessage(err);
-        ctx.ui.notify(`Failed to resume workflow ${parsed.runId}: ${msg}`, "warning");
-      }
-      return;
-    }
     case "lifecycle-removed":
       ctx.ui.notify(
         `Workflow ${parsed.verb} has been removed — runs are one-shot. To stop a run early: /workflows abort <runId>`,
@@ -223,12 +194,7 @@ async function handleRpcMode(
     case "lifecycle-missing-id":
       // Usage 按 verb 区分（与 TUI verb 分支同文案——两模式统一）：resume 的可选
       // [model] 参数要出现在提示里，GUI 侧缺 runId 时得到的指引不指向旧用法。
-      ctx.ui.notify(
-        parsed.verb === "resume"
-          ? "Usage: /workflows resume <runId> [model]"
-          : `Usage: /workflows ${parsed.verb} <runId>`,
-        "warning",
-      );
+      ctx.ui.notify(missingIdUsageText(parsed.verb), "warning");
       return;
     case "noop":
       ctx.ui.notify("View workflows in the composer task tray", "info");
@@ -241,6 +207,100 @@ async function handleRpcMode(
   }
 }
 
+/** lifecycle-missing-id 的 Usage 文案：resume 带可选 [model] 参数，其余 verb 仅 runId。 */
+function missingIdUsageText(verb: "abort" | "resume"): string {
+  return verb === "resume" ? "Usage: /workflows resume <runId> [model]" : `Usage: /workflows ${verb} <runId>`;
+}
+
+/** abort 执行 + 结果通知（成功/失败均 notify，不向上抛——RPC 通道唯一 abort 入口）。 */
+async function abortWithNotify(
+  runId: string,
+  deps: LauncherDeps,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  try {
+    await abortRun(runId, deps);
+    // abort 单态后 pastTense 固定（原三态拼接随 pause/resume 删除）
+    ctx.ui.notify(`Workflow ${runId}: aborted`, "info");
+  } catch (err) {
+    ctx.ui.notify(`Failed to abort workflow ${runId}: ${toErrorMessage(err)}`, "warning");
+  }
+}
+
+/**
+ * resume 执行 + 结果通知（TUI verb / RPC verb 两通道共享——同语义同文案，防
+ * 双处文案漂移）。显式 model 先做目录预检（assertResumeModelInCatalog），成功/
+ * 失败均 notify（不向上抛）。
+ */
+async function resumeWithNotify(
+  runId: string,
+  model: string | undefined,
+  deps: LauncherDeps,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  try {
+    if (model !== undefined) assertResumeModelInCatalog(model);
+    await resumeRun(runId, deps, ...resumeModelArgs(model));
+    ctx.ui.notify(resumeStartedText(runId, model), "info");
+  } catch (err) {
+    ctx.ui.notify(`Failed to resume workflow ${runId}: ${toErrorMessage(err)}`, "warning");
+  }
+}
+
+/** 可选 model → resumeRun 变参（无覆盖 = 空变参，不造覆盖记账）。 */
+function resumeModelArgs(model: string | undefined): [] | [{ model: string }] {
+  return model !== undefined ? [{ model }] : [];
+}
+
+/** resume 启动通知文案（带显式 model 时回显模型，用户可确认覆盖生效）。 */
+function resumeStartedText(runId: string, model: string | undefined): string {
+  return `Workflow ${runId}: resuming${model !== undefined ? ` with model ${model}` : ""} — completed calls replay at zero token cost, unfinished calls re-dispatched`;
+}
+
+/**
+ * TUI 模式命令分派：resume verb → 断点续跑后 notify（不打开面板）；带参 → 按
+ * runId/前缀匹配打开；无参 → 列表选择。（abort 动词在 TUI 侧无既有通道，不在此
+ * 顺手扩——resume 是本批接入面）
+ */
+async function handleTuiCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  getRuns: () => Map<string, WorkflowRun>,
+  deps: LauncherDeps,
+): Promise<void> {
+  const trimmedArgs = args.trim();
+  const [verb, ...rest] = trimmedArgs.split(/\s+/).filter(Boolean);
+  if (verb === "resume") {
+    await resumeTuiVerb(rest, ctx, deps);
+    return;
+  }
+  // 直接按 runId / 前缀匹配打开
+  if (trimmedArgs) {
+    await openByRunId(trimmedArgs, getRuns, ctx, deps);
+    return;
+  }
+  // 无参——列表选择
+  await openFromList(getRuns, ctx, deps);
+}
+
+/**
+ * TUI resume verb：缺 runId 给 Usage 提示。可选第二参数 = 显式模型 canonical ref
+ * （'provider/modelId[:thinkingLevel]'）——落统一覆盖记账（F1-26 后续项：与
+ * setModel 补切同通道，resume 合一步表达）。执行与通知复用 RPC 同款 resumeWithNotify。
+ */
+async function resumeTuiVerb(
+  rest: string[],
+  ctx: ExtensionCommandContext,
+  deps: LauncherDeps,
+): Promise<void> {
+  const runId = rest[0];
+  if (!runId) {
+    ctx.ui.notify("Usage: /workflows resume <runId> [model]", "warning");
+    return;
+  }
+  await resumeWithNotify(runId, rest[1], deps, ctx);
+}
+
 /**
  * 命令通道显式 model 的目录预检（D8 拒单语义，与 tool 通道 run/resume action 同款
  * ——isModelRef 语法闸在 core resumeRun，此处补目录存在性：语法合法但目录查无

package/src/jsonl-run-store.ts

@@ -67,13 +67,17 @@ import {
   noteRebuiltSettlement,
   settlementRecordOfRunSettledFrame,
   type AgentResult,
+  type Budget,
   type ExecutionTraceNode,
   type RunEventLineIssue,
   type RunOutcome,
+  type RunSpec,
   type RunStore,
+  type WorkflowModelOverride,
   type WorkflowRecordRegisteredEntryData,
   type WorkflowRecordSettledEntryData,
   type WorkflowRunEvent,
+  type WorkerLogEntry,
 } from "@zhushanwen/subagent-core";
 import { WorkflowRun } from "@zhushanwen/subagent-core";
 import { errorLogsFromEvents, latestModelOverride, rebuildBudget, runAccountingFromEvents } from "@zhushanwen/subagent-core";
@@ -478,26 +482,32 @@ function rebuildRunSpecFromEntries(
   };
 }
 
-function foldRecordStreamToRun(
-  runId: string,
-  reg: WorkflowRecordRegisteredEntryData,
-  events: readonly WorkflowRunEvent[],
-  settled?: WorkflowRecordSettledEntryData,
-): WorkflowRun {
-  const created = events.find(
-    (e): e is Extract<WorkflowRunEvent, { type: "run-created" }> => e.type === "run-created",
-  );
-  const startedAtMs =
-    created?.ts ?? (Number.isFinite(reg.startedAt) ? reg.startedAt : Date.now());
-  const startedAtIso = new Date(startedAtMs).toISOString();
-  const spec = rebuildRunSpecFromEntries(created, reg, resolveSpecBudget(created, events));
-  // [§2.1b] 会计重建：v2 终态条目带活体口径 usedTokens/callCount → 真值优先；条目缺席
-  // 回落 agent-settled.result.usage 的同一加权口径（下界近似，含 usedCost）。
-  const budget = rebuildBudget(settled, events);
-  // [§2.1 errorLogs 持久化 / ADR-0093] 诊断日志重建：worker-log 帧 → errorLogs（与活体
-  // 写入同语义：按序 + 尾部上限裁剪）。此前无持久面、重启即空。
-  const errorLogs = errorLogsFromEvents(events);
+/**
+ * [foldRecordStreamToRun 拆分] 两分支 reconstruct 共用的 fold 产物（spec 之外的
+ * 快照/元数据公共字段）。
+ */
+interface FoldCommonParts {
+  budget: Budget;
+  errorLogs: WorkerLogEntry[];
+  startedAt: string;
+}
+
+/**
+ * [foldRecordStreamToRun 拆分] 两分支 reconstruct 共用的聚合重建块（trace + calls +
+ * 覆盖记账——原 fold 主干的公共块提取）。
+ */
+interface RebuiltRunAggregate {
+  calls: Map<number, AgentCall>;
+  trace: Trace;
+  /** 生效模型覆盖记账（无覆盖 undefined 不造键——语义见 rebuildRunAggregate 内注释）。 */
+  modelOverride: WorkflowModelOverride | undefined;
+}
 
+/**
+ * 聚合重建块：drafts → trace 节点 → Trace 副本 → call 集合（D-10 引用共享链）+
+ * 覆盖记账折叠。纯函数，零 IO。
+ */
+function rebuildRunAggregate(events: readonly WorkflowRunEvent[]): RebuiltRunAggregate {
   const drafts = collectRunCallDrafts(events);
 
   // Trace 先重建：call 的 traceNode 回链到 Trace 副本（D-10 引用共享；匹配不到
@@ -508,55 +518,123 @@ function foldRecordStreamToRun(
 
   const calls = draftsToAgentCalls(drafts, sharedNodes, nodes);
 
-  const settledEvent = lastRunSettledEvent(events);
   // [subagent-model-switch §6.6①/§7.4] 覆盖记账折叠（派生视图半边）：生效覆盖值 =
   // 最新一条（latestModelOverride core 单点——覆盖旧覆盖值不叠加，不变量 2）；
   // 无覆盖 undefined 不造键。fold 未跟时本行缺失 = 覆盖状态静默丢行——
   // jsonl-run-store-loadall 的 fold 消费用例是此丢行风险的机器防线（P8 第五道）。
   const modelOverride = latestModelOverride(events);
-  if (settledEvent === undefined) {
-    const interruptedAt = lastInterruptedAt(events);
-    return WorkflowRun.reconstruct(
-      runId,
-      spec,
-      {
-        budget,
-        calls,
-        trace,
-        errorLogs,
-      },
-      {
-        startedAt: startedAtIso,
-        // 中断标记（[D2] 中断态经 meta 投影表达）：末次 run-interrupted 后无
-        // run-resumed 复活 → meta.interruptedAt 置位，runSummary 投影 'interrupted'
-        //（CLI/TUI 不显示僵尸「运行中」；resume 资格判据在 core fold lifecycle，
-        // 不受本投影影响）。
-        ...(interruptedAt !== undefined ? { interruptedAt } : {}),
-        ...(modelOverride !== undefined ? { modelOverride } : {}),
-      },
-    );
-  }
+  return { calls, trace, modelOverride };
+}
+
+/**
+ * 非终局分支 reconstruct：无 run-settled 帧 = running（交恢复链收编）+ 中断标记
+ * 投影（[D2]）。
+ */
+function reconstructUnsettledRun(
+  runId: string,
+  spec: RunSpec,
+  aggregate: RebuiltRunAggregate,
+  parts: FoldCommonParts,
+  events: readonly WorkflowRunEvent[],
+): WorkflowRun {
+  const interruptedAt = lastInterruptedAt(events);
+  return WorkflowRun.reconstruct(
+    runId,
+    spec,
+    {
+      budget: parts.budget,
+      calls: aggregate.calls,
+      trace: aggregate.trace,
+      errorLogs: parts.errorLogs,
+    },
+    {
+      startedAt: parts.startedAt,
+      // 中断标记（[D2] 中断态经 meta 投影表达）：末次 run-interrupted 后无
+      // run-resumed 复活 → meta.interruptedAt 置位，runSummary 投影 'interrupted'
+      //（CLI/TUI 不显示僵尸「运行中」；resume 资格判据在 core fold lifecycle，
+      // 不受本投影影响）。
+      ...(interruptedAt !== undefined ? { interruptedAt } : {}),
+      ...(aggregate.modelOverride !== undefined ? { modelOverride: aggregate.modelOverride } : {}),
+    },
+  );
+}
+
+/**
+ * 终局分支 reconstruct：run-settled 帧派生 DoneReason + completedAt；失败终局带
+ * 帧 reason 文本（不落 generic 恢复文案）。
+ */
+function reconstructSettledRun(
+  runId: string,
+  spec: RunSpec,
+  aggregate: RebuiltRunAggregate,
+  parts: FoldCommonParts,
+  settledEvent: RunSettledFrame,
+): WorkflowRun {
   const reason = runSettledOutcomeToDoneReason(settledEvent.outcome, settledEvent.errorCode);
   return WorkflowRun.reconstruct(
     runId,
     spec,
     {
       reason,
-      budget,
-      calls,
-      trace,
-      errorLogs,
+      budget: parts.budget,
+      calls: aggregate.calls,
+      trace: aggregate.trace,
+      errorLogs: parts.errorLogs,
       // 成功终局无 error；失败终局带帧 reason 文本（不落 generic 恢复文案）
       ...(reason !== "completed" && settledEvent.reason !== undefined ? { error: settledEvent.reason } : {}),
     },
     {
-      startedAt: startedAtIso,
+      startedAt: parts.startedAt,
       completedAt: new Date(settledEvent.ts).toISOString(),
-      ...(modelOverride !== undefined ? { modelOverride } : {}),
+      ...(aggregate.modelOverride !== undefined ? { modelOverride: aggregate.modelOverride } : {}),
     },
   );
 }
 
+/**
+ * startedAt 毫秒锚：run-created 帧 ts 优先，回落注册条目 startedAt（非有限数值 =
+ * 兜底当前时刻，保 startedAt 恒有值）。
+ */
+function resolveStartedAtMs(
+  created: Extract<WorkflowRunEvent, { type: "run-created" }> | undefined,
+  reg: WorkflowRecordRegisteredEntryData,
+): number {
+  return created?.ts ?? (Number.isFinite(reg.startedAt) ? reg.startedAt : Date.now());
+}
+
+/**
+ * record 事件流 → WorkflowRun 聚合（纯函数，零 IO；fold 语义词表说明见文件头
+ * 「record 流 fold 重建」节）。主干只做产物编排：公共 fold 产物（budget/errorLogs/
+ * startedAt/spec）+ 聚合重建块（rebuildRunAggregate）+ 按终局帧有无分流到
+ * reconstructUnsettledRun / reconstructSettledRun。
+ */
+function foldRecordStreamToRun(
+  runId: string,
+  reg: WorkflowRecordRegisteredEntryData,
+  events: readonly WorkflowRunEvent[],
+  settled?: WorkflowRecordSettledEntryData,
+): WorkflowRun {
+  const created = events.find(
+    (e): e is Extract<WorkflowRunEvent, { type: "run-created" }> => e.type === "run-created",
+  );
+  const spec = rebuildRunSpecFromEntries(created, reg, resolveSpecBudget(created, events));
+  // [§2.1b] 会计重建：v2 终态条目带活体口径 usedTokens/callCount → 真值优先；条目缺席
+  // 回落 agent-settled.result.usage 的同一加权口径（下界近似，含 usedCost）。
+  // [§2.1 errorLogs 持久化 / ADR-0093] 诊断日志重建：worker-log 帧 → errorLogs（与活体
+  // 写入同语义：按序 + 尾部上限裁剪）。此前无持久面、重启即空。
+  const parts: FoldCommonParts = {
+    budget: rebuildBudget(settled, events),
+    errorLogs: errorLogsFromEvents(events),
+    startedAt: new Date(resolveStartedAtMs(created, reg)).toISOString(),
+  };
+  const aggregate = rebuildRunAggregate(events);
+  const settledEvent = lastRunSettledEvent(events);
+  if (settledEvent === undefined) {
+    return reconstructUnsettledRun(runId, spec, aggregate, parts, events);
+  }
+  return reconstructSettledRun(runId, spec, aggregate, parts, settledEvent);
+}
+
 // ── JsonlRunStore ────────────────────────────────────────────
 
 const logger = getLogger("subagents");

package/src/session-lifecycle.ts

@@ -42,7 +42,7 @@ import {
 import { bindNotifyLedgerHost, type NotifyLedgerHost } from "@zhushanwen/subagent-core";
 import { IDENTITY_CUSTOM_TYPE, type SubagentIdentityData } from "@zhushanwen/subagent-core";
 import type { ExecutionMode } from "@zhushanwen/subagent-core";
-import { maybeCleanupExpiredSessionFiles } from "@zhushanwen/subagent-core";
+import { startEngineJournalGcTimer } from "@zhushanwen/subagent-core";
 import { resolvePiSessionScopedDir } from "@zhushanwen/subagent-core";
 // [W1 / D5] session_start 兜底触发点的统一保留维护轮：入口 + record 域目录锚
 // （getSubagentRecordsDir 布局 + ENV_ROOT_CWD 贯穿 env 名单源）+ state 目录分量
@@ -557,7 +557,7 @@ export function bindLedgerHostAndRecover(pi: ExtensionAPI, ctx: ExtensionContext
 
 /**
  * 随迁块 4 的进程级维护三连（各 try-catch「失败记日志不阻断」，设计 §3.4）：
- * 过期 session 文件清理 / ADR-035 manifest tmp 恢复 / ADR-035 worktree reaper 扫描。
+ * 引擎 journal TTL 回收 / ADR-035 manifest tmp 恢复 / ADR-035 worktree reaper 扫描。
  * （[modeless 波5] 原 [E1] sync 批崩溃恢复接线已摘除；[collect 退役] core 侧
  * recoverSyncCollectBatch 方法本体已删——sync 批机制不存在，无恢复面可接线。）
  */
@@ -568,12 +568,16 @@ async function runProcessLevelMaintenance(
   deps: SessionLifecycleDeps,
 ): Promise<void> {
   try {
-    // 递归扫描 <agentDir>/subagents + unlink 超 TTL 跨 session 文件属进程级维护
-    // ——oncePerProcess 守卫防双跑（u-audit-fix）。
-    oncePerProcess("subagent-workflow:cleanup-expired-session-files", () =>
-      maybeCleanupExpiredSessionFiles(agentDir, ctx.cwd));
+    // 引擎 journal TTL 回收（30 天 mtime）+ worktree .patch 孤儿清扫（同 TTL，仅
+    // *.patch 两层枚举——按 branch 命名无会话锚，级联引用并集无锚可达，唯一 mtime
+    // 兜底通道）属进程级维护——oncePerProcess 守卫防双跑（u-audit-fix）。接线即扫
+    // 一次 + 24h 定时复扫（unref 不 hold 进程退出，对齐 main 侧 log-retention 形态）。
+    // 子代理会话文件（*.jsonl / sidecar / manifest / *.events）不在本维护面——回收归
+    // 删主会话级联（runtime session-content-cascade，2026-10-12 裁决）。
+    oncePerProcess("subagent-workflow:engine-journal-gc", () =>
+      startEngineJournalGcTimer(agentDir));
   } catch (err) {
-    logger.warn("[subagents] expired session file cleanup failed", {
+    logger.warn("[subagents] engine journal gc failed", {
       reason: toErrorMessage(err),
     });
   }