@zhushanwen/pi-subagent-workflow 8.7.0 → 8.8.0

package/src/interface/subagent-tool-schema.ts

@@ -17,7 +17,7 @@
 // 反向 import 壳侧 interface，常量随之内化）——此处 re-export 保持既有 import 路径。
 
 import { StringEnum } from "@earendil-works/pi-ai";
-import { type Static, Type } from "typebox";
+import { Type } from "typebox";
 
 import { THINKING_ORDER } from "@zhushanwen/subagent-core/shared/model-ref.ts";
 
@@ -158,6 +158,3 @@ export const SubagentParams = Type.Object({
     })),
   })),
 });
-
-/** Params schema 的 Static 投影（消费方经 `Static<typeof SubagentParams>` 使用，见 subagent-tool.ts）。 */
-export type SubagentParamsStatic = Static<typeof SubagentParams>;

package/src/interface/subagent-tool.ts

@@ -63,7 +63,7 @@ type SubagentRenderResultCb = (
 // schema 常量经真实 typebox 编译校验（SW 自身 vitest 把 typebox alias 到 mock，
 // 丢 options——required/description 断言必须以真实构造为基准）。
 
-// extractAgentName 已上移到 ../tui/format.ts 共享（tool-render / subagent-tool 复用）。
+// extractAgentName 已上移到 ./format.ts 共享（tool-render / subagent-tool 复用）。
 
 /** exhaustiveness 承重 helper：default 分支把 action 收敛为 never，新增 action 时 tsc 报错。 */
 function assertNever(value: never): string {

package/src/interface/subagents.ts

@@ -1,4 +1,4 @@
-// src/commands/subagents.ts
+// src/interface/subagents.ts
 //
 // /subagents 命令。薄壳——打开 list overlay（等同原 /subagents list [<id>]）。
 //

package/src/interface/tool-render.ts

@@ -1,4 +1,4 @@
-// src/tui/tool-render.ts
+// src/interface/tool-render.ts
 //
 // 对话流 tool block 渲染。renderCall（标题行）+ renderResult（背景色 block）。
 //
@@ -28,9 +28,8 @@ import type {
 import { displayAgentName } from "@zhushanwen/subagent-core/shared/agent-ref.ts";
 import {
   extractAgentName,
-  firstLine,
+  firstLineSanitized,
   formatElapsedSeconds,
-  sanitizeLabel,
   statusGlyph,
   type ThemeLike,
   truncLine,
@@ -304,7 +303,7 @@ function shortSessionLabel(file: string): string {
  * execute 抛错（如 hub disposed / task 缺失）时，subagents handler 不 catch，
  * Pi 框架会把 error.message 塞进 result.content[0].text。renderResult 的 fallback
  * 分支用它把真实原因显示出来，避免只显「no details available」让 AI 盲猜。
- * content 可能多行，只取首行（用共享 firstLine 裁断 + sanitize）。
+ * content 可能多行，只取首行（共享 firstLineSanitized 裁断 + sanitize）。
  */
 function extractResultError(content: AgentToolResult<SubagentToolResult>["content"]): string | undefined {
   if (!Array.isArray(content)) return undefined;
@@ -322,15 +321,6 @@ function getStringText(item: unknown): string | undefined {
   return typeof val === "string" && val.trim().length > 0 ? val : undefined;
 }
 
-/**
- * 取文本首个非空行（多行压成首行展示），并 sanitize。
- * 用于 done/failed 的交付物预览。
- * 共享 firstLine（./format.ts）取首行，本 wrapper 叠加 sanitizeLabel。
- */
-function firstLineSanitized(text?: string): string {
-  return sanitizeLabel(firstLine(text));
-}
-
 // ============================================================
 // list 渲染 helper（action:"list" 分支）
 // ============================================================

package/src/interface/tool-workflow-script.ts

@@ -10,32 +10,40 @@
  * - delete: 删除脚本（前查 isRunning 防删运行中脚本）
  * - list: 列出可用脚本（调 registry.loadAll）
  *
+ * C5②（convergence D-6）：generate 五道闸校验管线 + tmp 写盘下沉 core
+ * generateWorkflowScript（报错文案逐字平移，CA2 前提）；save/delete 改调 core
+ * barrel（第三可选目录参数缺省即 pi 布局 .pi/workflows——pi 现两参调用形态零变化）。
+ * 结构化 {ok}|{error} → pi 的 execute-throw 契约转换在本层（pi 只对 execute throw
+ * 置 isError:true）；AbortSignal 的 aborted 检查留宿主层（C4 偏差 #4 已声明）。
+ *
  * 层归属：Interface。依赖 Pi SDK + engine script-lint + infra workflow-files。
  *
  * 参考：domain-models.md §FR-5（tool 收口 4→2）。
  */
 
-import { mkdirSync, writeFileSync } from "node:fs";
-import { resolve as pathResolve } from "node:path";
-
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
 
 import {
-  guiComponent,
-  type GuiContext,
-  type GuiRenderResult,
-  guiResult,
-  isGuiCapable,
+	guiComponent,
+	type GuiContext,
+	type GuiRenderResult,
+	guiResult,
+	isGuiCapable,
 } from "@xyz-agent/extension-protocol";
+// C5②/C5⑦：创作闭环统一走 core barrel（generateWorkflowScript/saveWorkflow/
+// deleteWorkflow/lintScript 均为 barrel 导出面；深路径在 npm/vendored 形态不可达）
+import {
+	deleteWorkflow,
+	generateWorkflowScript,
+	lintScript,
+	saveWorkflow,
+} from "@zhushanwen/subagent-core";
 import type { WorkflowScriptRegistry } from "@zhushanwen/subagent-core/orchestration/models/workflow-script-registry.ts";
-import { lintScript } from "@zhushanwen/subagent-core/orchestration/script-lint.ts";
-import { deleteWorkflow, saveWorkflow } from "@zhushanwen/subagent-core/orchestration/workflow-files.ts";
 import { toGuiCtx } from "./gui-mappers.ts";
 import { renderTextFallback } from "./views/format.ts";
-import { parseResourceMetaDetailed } from "@zhushanwen/subagent-core/shared/meta-parser.ts";
 
 // ── Parameter schema ─────────────────────────────────────────
 
@@ -242,73 +250,23 @@ export function registerWorkflowScriptTool(
 
 export function actionGenerate(params: ScriptParams, signal: AbortSignal | undefined): TextContent {
   if (signal?.aborted) {
-    // throw（W4b）：pi 只对 execute throw 置 isError:true（返回值 isError 被丢弃）
+    // throw（W4b）：pi 只对 execute throw 置 isError:true（返回值 isError 被丢弃）。
+    // AbortSignal 是 pi tool 契约层关注——core 管线不含 signal 检查，宿主自留（C4 偏差 #4）
     throw new Error("Operation aborted before start");
   }
-  const name = params.name;
-  const script = params.script;
-  if (!name || !script) {
-    throw new Error("generate requires 'name' and 'script' parameters");
-  }
-
- // 1. Reject ESM syntax (Worker runs CJS); 'export const meta' 例外
-  const stripped = script.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
-  if (/\bimport\s+(?:type\s+)?[\w{*]/.test(stripped)) {
-    throw new Error(
-      "Script uses ESM 'import' syntax. Workflow scripts run in a CJS Worker — use require() instead.",
-    );
-  }
-  const hasExportMeta = /\bexport\s+const\s+meta\s*=/.test(stripped);
-  const otherExports = stripped.match(/\bexport\s+(?:const|let|var|function|default|\{)/g);
-  if (otherExports && !hasExportMeta) {
-    throw new Error(
-      "Script uses ESM 'export' (non-meta). Use 'const meta = {...}' at top level instead.",
-    );
-  }
-
- // 2. Validate meta declaration (/* @pi-meta */ new format preferred; legacy const meta accepted during transition — m0)
-  const hasPiMeta = /\/\*\s*@pi-meta\s*\n/.test(script);
-  const hasLegacyMeta = script.includes("const meta") || script.includes("export const meta");
-  if (!hasPiMeta && !hasLegacyMeta) {
-    throw new Error(
-      "Script must contain a meta declaration: a /* @pi-meta */ YAML block comment (preferred) or legacy const meta = { ... }. The block has the form: a block comment starting with /* @pi-meta followed by YAML (name/description/phases/parameters?/usage?), closed by */ on its own line.",
-    );
-  }
-
- // 3. Check agent usage
-  if (!/\bagent\s*\(/.test(stripped)) {
-    throw new Error(
-      "Script does not contain any agent() calls. A workflow must call agent() at least once.",
-    );
-  }
-
- // 4. Syntax check (wrap in async IIFE like runtime)
-  const cjsScript = script.replace(/\bexport\s+const\s+meta\b/, "const meta");
-  try {
-    new Function(`(async () => { ${cjsScript} })();`);
-  } catch (err: unknown) {
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`Syntax error in script: ${msg}`);
-  }
-
- // 4b. Round-trip: validate /* @pi-meta */ YAML before writing (v5 §4.7 / ERR4 — report linePos, don't write bad files)
-  if (hasPiMeta) {
-    const detailed = parseResourceMetaDetailed(script, "workflow");
-    if (!detailed.ok) {
-      const loc = "linePos" in detailed && detailed.linePos
-        ? ` (line ${detailed.linePos.line}, col ${detailed.linePos.col})`
-        : "";
-      throw new Error(
-        `Generated /* @pi-meta */ YAML cannot be parsed${loc}: ${detailed.error}. Common causes: YAML indent errors, patternProperties regex must use double backslash (\\d not \d), or a stray star-slash inside the YAML body. Fix the meta block and retry.`,
-      );
-    }
+  const name = params.name ?? "";
+  const script = params.script ?? "";
+
+  // C5②：五道闸（ESM 拒/meta 必需/agent() 必需/语法/@pi-meta round-trip）+ tmp 写盘
+  // 全部在 core generateWorkflowScript（缺省 tmpDir 即 pi 布局 .pi/workflows/.tmp，
+  // 相对 cwd resolve——与旧本地实现一致）。结构化 {ok}|{error} → execute-throw 契约
+  // 转换在此（报错文案逐字平移自 pi 旧版，含 round-trip 行列信息）。
+  const result = generateWorkflowScript(name, script);
+  if (!result.ok) {
+    throw new Error(result.error);
   }
-
- // 5. Write to .tmp directory
-  const tmpDir = pathResolve(".pi/workflows/.tmp");
-  mkdirSync(tmpDir, { recursive: true });
-  const filePath = pathResolve(tmpDir, `${name}.js`);
-  writeFileSync(filePath, script, "utf-8");
+  // result.ok ⇒ name/script 非空（core 对空入参返回 error）
+  const filePath = result.path;
 
   return {
     content: [

package/src/interface/tool-workflow.ts

@@ -33,10 +33,16 @@ import { type Static, Type } from "typebox";
 
 import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core/execution/execute-options-mapper.ts";
 import { THINKING_ORDER } from "@zhushanwen/subagent-core/execution/model-resolver.ts";
+import { MAX_TIMER_DELAY_MS } from "@zhushanwen/subagent-core/shared/timer-delay.ts";
+import {
+  argKeysFromMeta,
+  findFlattenedArgKeys,
+} from "@zhushanwen/subagent-core/orchestration/args-meta.ts";
 import type { LauncherDeps } from "@zhushanwen/subagent-core/orchestration/launcher.ts";
 import { abortRun, runWorkflow } from "@zhushanwen/subagent-core/orchestration/lifecycle.ts";
 import type { RunStore } from "@zhushanwen/subagent-core/orchestration/models/ports.ts";
 import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
+import { runSummary } from "@zhushanwen/subagent-core/orchestration/workflow-run-summary.ts";
 import { mapRunIcon, mapRunStatus, toGuiCtx } from "./gui-mappers.ts";
 import {
   acquireReentryGuard,
@@ -63,7 +69,7 @@ const WORKFLOW_ACTIONS: readonly WorkflowAction[] = [
 const WorkflowParams = Type.Object({
   action: StringEnum(WORKFLOW_ACTIONS, { description: "Workflow action to execute" }),
   name: Type.Optional(
-    Type.String({ description: "Workflow ref: absolute path to the .js script (use <location> from <available_workflows>; run action)" }),
+    Type.String({ description: "Workflow ref: builtin/saved workflow name from <available_workflows> (C5: run accepts names), or absolute path to the .js script (use <location>; run action)" }),
   ),
   slug: Type.Optional(
     Type.String({
@@ -82,7 +88,7 @@ const WorkflowParams = Type.Object({
     }),
   ),
   tokens: Type.Optional(Type.Number({ description: "Max token budget — ONLY set when user explicitly requests a limit; omit = unlimited (default)" })),
-  time: Type.Optional(Type.Number({ description: "Max time budget in ms — ONLY set when user explicitly requests a limit; omit = unlimited (default)" })),
+  time: Type.Optional(Type.Number({ description: `Max time budget in ms — ONLY set when user explicitly requests a limit; omit = unlimited (default; hard ceiling ${MAX_TIMER_DELAY_MS} ms — larger values fail fast at entry)` })),
   error: Type.Optional(
     Type.String({ description: "Error/reason message (optional, used with abort)" }),
   ),
@@ -105,8 +111,12 @@ const RUNID_SHORT = 8;
  * tool 自身顶层键（workflow params schema 键）——workflow 参数名与 tool 键撞名时
  * （如 workflow 声明参数 name），顶层同名键是 tool 参数而非平铺（m6 评审 M-3）。
  * 未来新增 tool 顶层键需同步此集合。
+ *
+ * D9 下沉后作为 core args-meta 的 reservedKeys 注入（ArgMetaOptions）——core 缺省
+ * 空集，不注入则撞名保护失效（run 调用顶层必有 action/name，会被误判平铺）。
+ * export 供 detectors.test 复用同一集合防漂移。
  */
-const TOOL_TOP_LEVEL = new Set([
+export const TOOL_TOP_LEVEL = new Set([
   "action",
   "name",
   "slug",
@@ -124,76 +134,11 @@ const TOOL_TOP_LEVEL = new Set([
 ]);
 
 /**
- * 从 workflow 参数 schema 动态构建平铺检测的已知键集（m6：schema 即 SSOT——
- * 替代 21 键硬编码 KNOWN_ARG_KEYS，消除与参数定义的漂移面）。
- *
- * - exact：properties keys（精确匹配）
- * - patterns：patternProperties 原样转正则数组（如 /^batch\\d+$/——与旧
- *   KNOWN_ARG_KEY_PREFIXES 语义一致，自动兼容 \\d{2} 等变体；schema pattern 已是
- *   正则源码，直接 new RegExp 即可）
- * - 构建时排除 TOOL_TOP_LEVEL（撞名保护）
+ * core args-meta 的宿主差异注入项（D9 下沉）：reservedKeys = TOOL_TOP_LEVEL。
+ * core 版 argKeysFromMeta / findFlattenedArgKeys 缺省 reservedKeys 为空集（core
+ * 中性形态），不传此项则失去撞名保护、行为不等值——调用点必须携带（等值契约）。
  */
-export function argKeysFromMeta(
-  parameters: Record<string, unknown> | undefined,
-): { exact: ReadonlySet<string>; patterns: readonly RegExp[] } {
-  const exact = new Set<string>();
-  const patterns: RegExp[] = [];
-  if (parameters === undefined || parameters === null || typeof parameters !== "object") {
-    return { exact, patterns };
-  }
-  const props = parameters.properties;
-  if (props !== null && typeof props === "object") {
-    for (const k of Object.keys(props as Record<string, unknown>)) {
-      if (!TOOL_TOP_LEVEL.has(k)) exact.add(k);
-    }
-  }
-  const pp = parameters.patternProperties;
-  if (pp !== null && typeof pp === "object") {
-    for (const p of Object.keys(pp as Record<string, unknown>)) {
-      try {
-        const re = new RegExp(p); // schema pattern 已是正则源码
-        // S1（m6 exec-review）：跳过能命中 tool 顶层键的 pattern——否则
-        // ^run.*$ 类 pattern 会匹配 runId/name 等 tool 键，合法调用恒误报
-        if ([...TOOL_TOP_LEVEL].some((tk) => re.test(tk))) continue;
-        patterns.push(re);
-      } catch (err) {
-        // 非法 pattern（schema 校验 m3 已保证合法，双保险）——跳过并记录
-        logger.warn(`[tool-workflow] patternProperties 非法正则跳过: ${p}`, {
-          reason: err instanceof Error ? err.message : String(err),
-        });
-      }
-    }
-  }
-  return { exact, patterns };
-}
-
-/**
- * 检测弱模型把 args 子字段平铺到 workflow params 顶层（P0 静默失败防护）。
- * 返回被平铺的键名列表（空 = 未平铺）。export 供 behavioral 测试（trigger/no-trigger/edge）。
- * 参数取 unknown 以便测试构造任意对象、并解耦 WorkflowToolParams 的 index-signature 限制。
- *
- * knownKeys/knownPatterns 由 argKeysFromMeta 动态构建（m6）——匹配谓词：
- * knownKeys.has(k) || knownPatterns.some(re => re.test(k))（pattern 自带数字后缀
- * 语义——loose startsWith 会误报 batchl/target1）；保留 args-排除（顶层 + args
- * 内共存不算平铺）。
- */
-export function findFlattenedArgKeys(
-  params: unknown,
-  knownKeys: ReadonlySet<string>,
-  knownPatterns: readonly RegExp[],
-): string[] {
-  if (typeof params !== "object" || params === null) return [];
-  const p = params as Record<string, unknown>;
-  const args = typeof p.args === "object" && p.args !== null ? p.args : undefined;
-  const isKnownKey = (k: string) =>
-    knownKeys.has(k) || knownPatterns.some((re) => re.test(k));
-  // hasOwnProperty.call 而非 in（原型链——constructor/toString 类参数名不被继承键掩盖）
-  return Object.keys(p).filter(
-    (k) =>
-      isKnownKey(k) &&
-      !(args !== undefined && Object.prototype.hasOwnProperty.call(args, k)),
-  );
-}
+const ARGS_META_OPTIONS = { reservedKeys: TOOL_TOP_LEVEL };
 
 // ── Types ────────────────────────────────────────────────────
 
@@ -321,7 +266,7 @@ export function registerWorkflowTool(
       "<available_workflows> (injected each turn). For parameter details, read the <location> " +
       "script file (script header has @pi-meta parameters + usage + phases). Do NOT use " +
       "workflow-script generate for patterns already covered by available workflows.",
-      "run: pass the absolute .js path from <available_workflows> <location> as name, then start in background (no user confirmation needed).",
+      "run: pass the workflow ref as name — the listed <name> (builtin/saved workflow) or its <location> absolute .js path from <available_workflows> — then start in background (no user confirmation needed).",
       "Do NOT poll status after starting — results appear automatically via notifyDone.",
       "Runs are one-shot: there is no pause/resume — to stop a run early use abort; for a fresh result start a new run.",
       "Call shapes (JSON): " +
@@ -425,7 +370,17 @@ export async function actionRun(
   // 顶层（缺 args 嵌套）。args ?? {} 会静默 args={}，启动缺参 run 不报错——比 subagent
   // 平铺事故更严重。m6：先 registry.getPath（动态参数集来源——schema 即 SSOT），
   // not_found 优先返回；平铺检测报错带 Correct 正例纠正。
-  const script = await deps.registry.getPath(name);
+  //
+  // C5③（convergence D-4 pi 半边）：name 解析先查内置/已保存 workflow 名
+  // （registry.get——内置 chain/parallel/map-reduce/scatter-gather/review-fix-loop 或
+  // 用户 project/user 级脚本名，按 tmp>project>user>npm 优先级合并）——内置名命中
+  // 直接用内置脚本；未命中再走 getPath（绝对路径，~/ 展开——normalizeRef 既有）。
+  // 严格超集：现有路径用法零变化（路径串不会撞 workflow 名——名字是简单标识符），
+  // 两者都未命中仍走原 not_found 报错（建议清单不变）。
+  let script = await deps.registry.get(name);
+  if (!script) {
+    script = await deps.registry.getPath(name);
+  }
   // W4c：config-loader 的 toCachedMeta 对不可读/不存在文件返回 available:false 的
   // stub（非 undefined），仅判 !script 会绕过 not_found → 空 sourceCode 假启动
   //（W4b verifier 探针实测复现）。与下方 suggestions 分支的 wf.available 过滤口径对齐。
@@ -444,7 +399,10 @@ export async function actionRun(
 
   // m6：动态参数集（schema 即 SSOT）→ 平铺检测；无 parameters → 单次 warn + 跳过
   // （legacy const-meta 类永久无检测——D1 无 adapter 声明）
-  const { exact: knownKeys, patterns: knownPatterns } = argKeysFromMeta(script.meta.parameters);
+  const { exact: knownKeys, patterns: knownPatterns } = argKeysFromMeta(
+    script.meta.parameters,
+    ARGS_META_OPTIONS,
+  );
   if (knownKeys.size === 0 && knownPatterns.length === 0) {
     // M-2 显式信号：无参数契约（未声明/解析空）→ 单次 warn——静默退化变显式
     // （m6 exec-review M1：原实现排除 undefined 与设计相反）
@@ -452,7 +410,9 @@ export async function actionRun(
       `[tool-workflow] ${script.name}: 未声明参数契约（或解析为空）——平铺检测跳过，args 不校验`,
     );
   }
-  const flattened = findFlattenedArgKeys(params, knownKeys, knownPatterns);
+  // core 版接收 meta 内联构建键集（签名与本地版键集三参不同，判定谓词逐字同源）——
+  // 键集构建两次（此处 + core 内部）仅为 M-2 空契约信号，成本每 run 一次可忽略
+  const flattened = findFlattenedArgKeys(params, script.meta.parameters, ARGS_META_OPTIONS);
   if (flattened.length > 0) {
     throw new Error(
       `Detected ${flattened.join(", ")} at top level — they belong inside 'args'. ` +
@@ -468,6 +428,16 @@ export async function actionRun(
   const args = params.args ?? {};
   const tokens = params.tokens;
   const time = params.time;
+  // OR-1 入口 fail-fast（unbounded-wait-audit §7.2 T3①）：schema 的 time 是
+  // Type.Number 直通（无上界）——超 setTimeout 安全域的值会穿透到 lifecycle 内层
+  // 防线（assertSafeTimerDelay），而入口拦截让它永不进入副作用链。错误带合法上限
+  // 与实际传入值，LLM 可据消息自纠（clamp 或省略走 unlimited 语义）。
+  if (time !== undefined && time > MAX_TIMER_DELAY_MS) {
+    throw new Error(
+      `time budget ${time} ms exceeds the maximum of ${MAX_TIMER_DELAY_MS} ms (~24.8 days). ` +
+        `Retry with a smaller "time", or omit it for unlimited.`,
+    );
+  }
 
  // 构建 RunSpec + 启动（m3：parameters 从 script.meta 拷贝——chokepoint 校验用；
  // 校验失败 → ArgsValidationError 直接 throw 给 pi（W4：err.message 含 §5.3 指引，
@@ -568,19 +538,12 @@ async function actionLifecycle(
 
 // ── helpers ──────────────────────────────────────────────────
 
-/** WorkflowRun → 摘要（status action 用）。 */
+/** WorkflowRun → 摘要（status action 用）：core runSummary 单源投影 + 宿主扩展 stateFile。
+ *
+ * 字段集不再本地维护（runSummary 双投影分叉的收口点，D8/B5）；stateFile 依赖
+ * RunStore 实例，属宿主扩展——core 投影刻意不依赖具体 store。 */
 function toRunSummary(run: WorkflowRun, store: RunStore): RunSummary {
-  return {
-    runId: run.runId,
-    name: run.spec.scriptName,
-    slug: run.spec.slug,
-    status: run.state.status,
-    reason: run.state.reason,
-    startedAt: run.meta.startedAt,
-    completedAt: run.meta.completedAt,
-    error: run.state.error,
-    stateFile: store.stateFilePath(run.runId),
-  };
+  return { ...runSummary(run), stateFile: store.stateFilePath(run.runId) };
 }
 
 // W4b：原 textResult(text, isError) helper 已删除——23 处错误路径全部改 throw

package/src/interface/views/WorkflowsView.ts

@@ -57,16 +57,8 @@ import {
   visibleLen,
 } from "./format.ts";
 
-// L2 详情内容构建 + 滚动按键（纯函数）抽到 detail-content.ts；此处 re-export 保持
-// view 的对外 API 不变（测试仍从 WorkflowsView 导入）。
-export {
-  buildDetailContent,
-  detailContentLength,
-  type DetailKeyResult,
-  type DetailScrollContext,
-  processDetailKey,
-} from "./detail-content.ts";
-import { buildDetailContent, detailContentLength, type DetailScrollContext,processDetailKey } from "./detail-content.ts";
+// L2 详情内容构建 + 滚动按键（纯函数）抽到 detail-content.ts（view 与其测试直接 import）。
+import { buildDetailContent, detailContentLength, type DetailScrollContext, processDetailKey } from "./detail-content.ts";
 
 // ── TUI layout constants ──────────────────────────────────────
 
@@ -93,7 +85,7 @@ const PRINTABLE_CHAR_MIN = 32;
 function b(theme: ThemeLike, s: string): string {
   return theme.fg("borderMuted", s);
 }
-/** 着色单字符填充用的 ─（供 segFillColored 的 fillStyled）。 */
+/** 着色单字符填充用的 ─（本文件 dashes() 满宽填充复用）。 */
 function dash(theme: ThemeLike): string {
   return theme.fg("borderMuted", "─");
 }

package/src/interface/views/format.ts

@@ -12,6 +12,8 @@ import type { ExecutionTraceNode, ToolCallEntry } from "@zhushanwen/subagent-cor
 import type { DoneReason, RunStatus } from "@zhushanwen/subagent-core/orchestration/models/types.ts";
 import { displayAgentName } from "@zhushanwen/subagent-core/shared/agent-ref.ts";
 
+import type { ThemeLike as BaseThemeLike } from "../format.ts";
+
 // ── Constants ─────────────────────────────────────────────────
 
 export const SIDEBAR_WIDTH = 24;
@@ -53,10 +55,12 @@ type StatusText =
 
 // ── Theme interface (avoids importing Pi runtime) ─────────────
 
-export interface ThemeLike {
-  fg(token: string, text: string): string;
-  bold(text: string): string;
-}
+/**
+ * views 侧主题形状：仅 fg/bold——本文件所有函数只消费这两个方法。
+ * 单源派生自 src/interface/format.ts 的 ThemeLike（Pick 收窄），不再独立声明；
+ * 保留窄形状是为了让只有 fg/bold 的 duck-typed theme（含测试 stub）可直接传入。
+ */
+export type ThemeLike = Pick<BaseThemeLike, "fg" | "bold">;
 
 // ── Status helpers ────────────────────────────────────────────
 
@@ -128,17 +132,7 @@ export function formatElapsed(startedAt?: string, now: number = Date.now()): str
   return `${mins}m${remSecs}s`;
 }
 
-/**
- * Format elapsed time from integer seconds（live 路径用）。
- * 与 formatElapsed 输出格式一致，但输入是 computeElapsedSeconds 的秒数（非时间戳）。
- */
-export function formatElapsedSeconds(seconds: number): string {
-  if (seconds < 1) return "0s";
-  if (seconds < SECS_PER_MIN) return `${seconds}s`;
-  const mins = Math.floor(seconds / SECS_PER_MIN);
-  const remSecs = seconds % SECS_PER_MIN;
-  return `${mins}m${remSecs}s`;
-}
+// formatElapsedSeconds 单源自 src/interface/format.ts（见文末「单源折叠垫片」）。
 
 /**
  * Format a live eventLog entry（live 路径 Activity 区用）。
@@ -204,48 +198,15 @@ export function formatActivityLine(entry: ToolCallEntry, maxWidth: number): stri
   return `${entry.name}(${truncated})`;
 }
 
-// ── ANSI helpers ──────────────────────────────────────────────
-
-/** Measure visible width of a string (strips ANSI escapes, handles CJK/emoji).
- *  Delegates to pi-tui's visibleWidth for accurate width calculation.
- */
-export function visibleLen(s: string): number {
-  return visibleWidth(s);
-}
-
-/** Pad an ANSI-escaped string to a target *visible* width.
- *  只 pad 不截断：超宽时原样返回（调用方负责先截断）。
- *  对齐 subagents 的 padToVisible 语义。
- */
-export function padVisible(s: string, width: number): string {
-  const vl = visibleLen(s);
-  if (vl >= width) return s;
-  return s + " ".repeat(width - vl);
-}
-
-/**
- * 分段着色版填充：title 和 fill 都已着色（含 ANSI），拼接时各自 ANSI 延续。
- * 解决 ANSI 嵌套失色：若用 fg("c1", fill(title, "─", n))，
- * title 内的 \x1b[0m 会重置外层 c1，导致 title 之后的 ─ 失去 c1。
- * 改成 title + fill.repeat(后)，fill 整段保持自己的 ANSI，不依赖外层包裹。
- *
- * 对齐 subagents format.ts segFillColored（同源移植）。
- */
-export function segFillColored(
-  titleStyled: string | undefined,
-  fillStyled: string,
-  width: number,
-): string {
-  if (width <= 0) return "";
-  const fillW = visibleLen(fillStyled);
-  if (!titleStyled || fillW === 0) {
-    return fillStyled.repeat(width);
-  }
-  const tw = visibleLen(titleStyled);
-  if (tw >= width) return truncateToWidth(titleStyled, width);
-  const fillCount = width - tw;
-  return titleStyled + fillStyled.repeat(fillCount);
-}
+// ── 单源折叠垫片（设计 U11 宿主内合并）─────────────────────────
+// 通用文本 helper 已折叠单源到 src/interface/format.ts——truncLine 为自研
+// ANSI 安全实现（pi-tui truncateToWidth 会在省略号处插 \x1b[0m 断裂背景色，
+// 见 interface/format.ts truncLine 注释），统一取 interface 侧实现。
+// 此处按原名 re-export：WorkflowsView / detail-content（本 wave 只读）的
+// import 面不变即完成单源切换。segFillColored 无 views 侧消费方，直接删除。
+export { formatElapsedSeconds } from "../format.ts";
+export { padToVisible as padVisible } from "../format.ts";
+export { visibleWidth as visibleLen } from "@earendil-works/pi-tui";
 
 // ── Phase group (filters empty phases) ────────────────────────
 
@@ -290,7 +251,7 @@ export function formatPhaseLine(
  // pointer(2) + dot(1) + space(1)
   const PHASE_PREFIX_WIDTH = 4;
   const budget = maxWidth - PHASE_PREFIX_WIDTH;
-  const truncated = visibleLen(label) > budget
+  const truncated = visibleWidth(label) > budget
     ? truncateToWidth(label, budget - 1) + ELLIPSIS
     : label;
   return `${pointer}${dot} ${truncated}`;