@zhushanwen/pi-subagent-workflow 8.0.0 → 8.1.0

package/src/index.ts

@@ -183,6 +183,24 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     return cachedMainSessionFile;
   }
 
+  /**
+   * 按 sessionId 解析主 session 文件路径（文件名约定 `<ISO 时间戳>_<sessionId>.jsonl`）。
+   * [E2E 实测] attach 场景下 ctx.sessionManager.getSessionFile() 会返回前一 session 的
+   * 文件（session_start(root=01a01bf5) 时仍返回刚新建 session 的路径）——恢复逻辑
+   * 读错文件会整段漏判。此处按 id 从 sessions 目录解析为准；新 session 文件未 flush
+   * 时（AGENTS.md 规则 6：首条 assistant 消息前可能不存在）返回 undefined，调用方
+   * （fork 解析 / 孤儿恢复）对该场景本就无 entry 可读。
+   */
+  function resolveMainSessionFileById(sessionId: string): string | undefined {
+    const sessionsDir = path.join(getAgentDir(), "..", "sessions");
+    try {
+      const match = fs.readdirSync(sessionsDir).find((f) => f.endsWith(`_${sessionId}.jsonl`));
+      return match === undefined ? undefined : path.join(sessionsDir, match);
+    } catch {
+      return undefined;
+    }
+  }
+
   // resources_discover：不再注入额外 skill 目录（ADR-031 废弃 discovery.json）。
   // pi 核心 auto-discovery 已覆盖 .agents/skills 等标准目录，子 session 的
   // --skill 由 agent({skill}) 调用方显式传入，无需 extension 额外补充。
@@ -381,9 +399,20 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     // SR-3: 无论 new 还是 existing（/resume /fork 复用），session_start 都必须注入 handler
     service.setUiRequestHandler(uiRequestHandler);
 
+    // 主 session 文件：按 sessionId 解析（getSessionFile() 在 attach 场景会返回前一
+    // session 的文件，E2E 实测），未 flush 的新 session 回退 getSessionFile()。
+    // 值直传 initSession——jiti 多实例分裂下闭包缓存（cachedMainSessionFile）不跨
+    // 实例共享，恢复逻辑经缓存读会拿到滞后一个事件的值（E2E 实测 ENOENT 漏判）；
+    // 缓存本身保留给既有 getter 消费者（fork source 解析）。
+    cachedMainSessionFile =
+      resolveMainSessionFileById(ctx.sessionManager.getSessionId()) ??
+      ctx.sessionManager.getSessionFile() ??
+      undefined;
+
     service.initSession({
       pi,
       sessionId: ctx.sessionManager.getSessionId(),
+      mainSessionFile: cachedMainSessionFile,
       // 注入 ctx.ui.setWidget 作为 streaming sink（只绑方法，不持有整个 ctx）。
       // background subagent 执行期间，text_delta 经 SubagentStream 合并后由此通道转发。
       // [W1 修复] ctx.mode === 'rpc' 守卫：TUI/json/print 下 streamSink = undefined（无 widget 噪音），
@@ -413,8 +442,6 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     // S-2: 启动 idle record GC 定时器（30 天 TTL，每小时检查一次）
     service.startGcTimer();
 
-    cachedMainSessionFile = ctx.sessionManager.getSessionFile() ?? undefined;
-
     try {
       maybeCleanupExpiredSessionFiles(agentDir, cwd);
     } catch (err) {
@@ -471,6 +498,19 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
             id: run.runId,
             reason: "failed",
           });
+          // 恢复终态必须落盘：save 走冷路径（done 绕过去抖）同步写 state 文件 +
+          // append 终态 workflow-record entry——entry_appended 事件驱动 runtime 派生
+          // 缓存失效重拉（无 triggerTurn 副作用）。不 save 则 entry/state 双双停留
+          // running，侧栏永久卡 running。失败仅记日志不阻断其余 run 的恢复（下次
+          // session_start 重开重试，恢复循环天然幂等）。
+          try {
+            await store.save(run);
+          } catch (err) {
+            logger.error("[subagent-workflow] kill-9 recovery store.save failed", {
+              runId: run.runId,
+              reason: err instanceof Error ? err.message : String(err),
+            });
+          }
         }
         runs.set(run.runId, run);
       }

package/src/interface/__tests__/tool-workflow-script-generate.test.ts

@@ -10,13 +10,19 @@ import { mkdirSync, writeFileSync } from "node:fs";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { actionGenerate, type ScriptParams, type TextContent } from "../tool-workflow-script.ts";
+import { actionGenerate, type ScriptParams, type TextContent, registerWorkflowScriptTool } from "../tool-workflow-script.ts";
+import { deleteWorkflow, saveWorkflow } from "../../orchestration/workflow-files.ts";
 
 vi.mock("node:fs", () => ({
   mkdirSync: vi.fn(),
   writeFileSync: vi.fn(),
 }));
 
+vi.mock("../../orchestration/workflow-files.ts", () => ({
+  saveWorkflow: vi.fn(),
+  deleteWorkflow: vi.fn(),
+}));
+
 const mockedWriteFileSync = vi.mocked(writeFileSync);
 const mockedMkdirSync = vi.mocked(mkdirSync);
 
@@ -106,6 +112,12 @@ describe("actionGenerate (m0: @pi-meta 认可 + round-trip)", () => {
     vi.clearAllMocks();
   });
 
+  /**
+   * W4b：generate 校验族错误路径从 return {isError:true} 改为 throw（pi 只对
+   * execute throw 置 isError:true，返回值 isError 被 agent-loop 丢弃）。
+   * actionGenerate 是同步函数——断言用同步 toThrow。
+   */
+
   it("TC1: 合法 @pi-meta → ready + writeFileSync 被调用", () => {
     const r = actionGenerate(gen(PI_META_VALID), undefined);
     expect(r.isError).toBeFalsy();
@@ -113,10 +125,10 @@ describe("actionGenerate (m0: @pi-meta 认可 + round-trip)", () => {
     expect(mockedWriteFileSync).toHaveBeenCalledTimes(1);
   });
 
-  it("TC2: malformed @pi-meta YAML → error + writeFileSync 未调用 [P-generate-roundtrip]", () => {
-    const r = actionGenerate(gen(PI_META_MALFORMED), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/cannot be parsed|无法解析|line/i);
+  it("TC2: malformed @pi-meta YAML → throw + writeFileSync 未调用 [P-generate-roundtrip]", () => {
+    expect(() => actionGenerate(gen(PI_META_MALFORMED), undefined)).toThrow(
+      /cannot be parsed/i,
+    );
     expect(mockedWriteFileSync).not.toHaveBeenCalled();
   });
 
@@ -126,38 +138,103 @@ describe("actionGenerate (m0: @pi-meta 认可 + round-trip)", () => {
     expect(mockedWriteFileSync).toHaveBeenCalledTimes(1);
   });
 
-  it("TC4: 无 meta → error 提及 @pi-meta 新格式", () => {
-    const r = actionGenerate(gen(NO_META), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/meta declaration/i);
-    expect(textOf(r)).toMatch(/pi-meta/i);
+  it("TC4: 无 meta → throw 提及 @pi-meta 新格式", () => {
+    expect(() => actionGenerate(gen(NO_META), undefined)).toThrow(/meta declaration/i);
     expect(mockedWriteFileSync).not.toHaveBeenCalled();
   });
 
-  it("TC5: @pi-meta 单反斜杠正则 → error（LLM 高频错）[P-generate-roundtrip]", () => {
-    const r = actionGenerate(gen(PI_META_REGEX_SINGLE_BS), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/escape|cannot be parsed|无法解析|line/i);
+  it("TC5: @pi-meta 单反斜杠正则 → throw（LLM 高频错）[P-generate-roundtrip]", () => {
+    expect(() => actionGenerate(gen(PI_META_REGEX_SINGLE_BS), undefined)).toThrow(
+      /escape|cannot be parsed/i,
+    );
     expect(mockedWriteFileSync).not.toHaveBeenCalled();
   });
 
-  it("TC6: ESM import → reject（保留现有行为）", () => {
-    const r = actionGenerate(gen(ESM_IMPORT), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/ESM|import/i);
+  it("TC6: ESM import → throw（保留现有行为）", () => {
+    expect(() => actionGenerate(gen(ESM_IMPORT), undefined)).toThrow(/ESM|import/i);
   });
 
-  it("TC7: 无 agent() → reject（保留现有行为）", () => {
-    const r = actionGenerate(gen(NO_AGENT), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/agent\(\)/i);
+  it("TC7: 无 agent() → throw（保留现有行为）", () => {
+    expect(() => actionGenerate(gen(NO_AGENT), undefined)).toThrow(/agent\(\)/i);
   });
 
-  it("TC8: signal aborted → reject（保留现有行为）", () => {
+  it("TC8: signal aborted → throw（保留现有行为）", () => {
     const controller = new AbortController();
     controller.abort();
-    const r = actionGenerate(gen(PI_META_VALID), controller.signal);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/abort/i);
+    expect(() => actionGenerate(gen(PI_META_VALID), controller.signal)).toThrow(/abort/i);
+  });
+
+  it("TC9: 缺 name/script 参数 → throw 'generate requires'（防御性，schema 先拦）", () => {
+    expect(() => actionGenerate({ action: "generate" } as ScriptParams, undefined)).toThrow(
+      "generate requires 'name' and 'script' parameters",
+    );
+  });
+
+  it("TC10: ESM export（非 meta）→ throw（W4b 收敛路径）", () => {
+    const script = `/* @pi-meta
+name: x
+description: d
+phases: [a]
+*/
+const agent = require("./agent");
+export const foo = 1;
+agent("w");
+`;
+    expect(() => actionGenerate(gen(script), undefined)).toThrow(/ESM 'export'/i);
+  });
+});
+
+describe("actionSave/actionDelete error paths (W4: throw 范式)", () => {
+  /**
+   * W4：save/delete 失败路径从 return {isError:true} 改为 throw——pi 只对 execute
+   * throw 置 isError:true（agent-loop.js:453-483 丢弃返回值里的 isError）。
+   * 经 registerWorkflowScriptTool 注册层测（mock workflow-files 的 FS 依赖）。
+   */
+  interface CapturedTool {
+    execute: (
+      toolCallId: string,
+      params: Record<string, unknown>,
+      signal: AbortSignal | undefined,
+      onUpdate: unknown,
+      ctx: unknown,
+    ) => Promise<TextContent>;
+  }
+  function captureTool(): CapturedTool {
+    const tools: CapturedTool[] = [];
+    const pi = { registerTool: (t: unknown) => tools.push(t as CapturedTool) };
+    // registry 最小 stub：delete 成功路径会调 invalidate（失败路径 throw 前不触达）
+    const registry = { invalidate: vi.fn() };
+    registerWorkflowScriptTool(pi as never, registry as never, () => false);
+    if (!tools[0]) throw new Error("registerWorkflowScriptTool did not register");
+    return tools[0];
+  }
+  const ctx = { mode: "tui" as const, hasUI: true };
+
+  it("save 失败 → throw 'Save failed: <原因>'（pi catch 后置 isError:true）", async () => {
+    vi.mocked(saveWorkflow).mockRejectedValueOnce(new Error("disk full"));
+    const tool = captureTool();
+    await expect(
+      tool.execute("id", { action: "save", name: "tmp-wf" }, undefined, undefined, ctx),
+    ).rejects.toThrow("Save failed: disk full");
+  });
+
+  it("delete 失败 → throw 'Delete failed: <原因>'", async () => {
+    // deleteWorkflow 是同步函数——mock 用同步 throw（mockRejectedValue 不会被
+    // actionDelete 的同步 try/catch 捕获）
+    vi.mocked(deleteWorkflow).mockImplementationOnce(() => {
+      throw new Error("script is running");
+    });
+    const tool = captureTool();
+    await expect(
+      tool.execute("id", { action: "delete", name: "tmp-wf" }, undefined, undefined, ctx),
+    ).rejects.toThrow("Delete failed: script is running");
+  });
+
+  it("save 成功路径不受影响（ok details 正常返回）", async () => {
+    vi.mocked(saveWorkflow).mockResolvedValueOnce("saved tmp-wf");
+    const tool = captureTool();
+    const r = await tool.execute("id", { action: "save", name: "tmp-wf" }, undefined, undefined, ctx);
+    expect(r.isError).toBeFalsy();
+    expect(r.details).toMatchObject({ action: "save", name: "tmp-wf", ok: true });
   });
 });

package/src/interface/__tests__/tool-workflow-throw-paths.test.ts

@@ -0,0 +1,179 @@
+/**
+ * W4b：workflow tool 错误路径 throw 语义（代表路径）。
+ *
+ * pi 只对 execute throw 置 isError:true——返回值里的 isError 被 agent-loop 丢弃
+ * （agent-loop.js:453-483），故错误路径必须 throw。本文件抽 4 个代表路径
+ * （W4b 验收交付物 3）：
+ * - not_found（abort 目标 runId 不存在）
+ * - reentry-busy（guard 占用，throw 前未 acquire）
+ * - 平铺检测（args 子字段平铺到顶层，LLM 常见错误）
+ * - slug 护栏（schema maxLength 之后的运行时第二道）
+ * generate 校验族（第 5 代表路径）见 tool-workflow-script-generate.test.ts。
+ *
+ * 经 registerWorkflowTool 注册层测（capture tool + 最小 deps stub），
+ * 与 W4 save/delete 测试同范式。框架：vitest。
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import { SLUG_MAX_LENGTH } from "../../execution/execute-options-mapper.ts";
+import { REENTRY_BUSY_MESSAGE, type ReentryGuardRef } from "../reentry-guard.ts";
+import { registerWorkflowTool } from "../tool-workflow.ts";
+
+// ── capture helper ──
+
+interface CapturedTool {
+  name: string;
+  execute: (
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<unknown>;
+}
+
+function captureTool(deps: unknown, reentryRef: ReentryGuardRef): CapturedTool {
+  const tools: CapturedTool[] = [];
+  const pi = { registerTool: (t: unknown) => tools.push(t as CapturedTool) };
+  registerWorkflowTool(pi as never, deps as never, reentryRef);
+  if (!tools[0] || tools[0].name !== "workflow") {
+    throw new Error("registerWorkflowTool did not register the workflow tool");
+  }
+  return tools[0];
+}
+
+/** 最小 LauncherDeps stub：被测路径只触 registry / runs。 */
+function makeDeps(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    runs: new Map(),
+    registry: {
+      getPath: vi.fn().mockResolvedValue(undefined),
+      loadAll: vi.fn().mockResolvedValue([]),
+    },
+    ...overrides,
+  };
+}
+
+/** 平铺检测 / slug 护栏路径的 registry script stub（meta.parameters 驱动已知键集）。 */
+function makeScript(parameters?: object): Record<string, unknown> {
+  return {
+    name: "demo-wf",
+    path: "/abs/demo-wf.js",
+    available: true,
+    sourceCode: "// demo",
+    meta: { description: "demo workflow", parameters },
+    toExecutable: () => "// demo",
+  };
+}
+
+// ── 代表路径 ──
+
+describe("W4b: workflow tool 错误路径 throw 语义", () => {
+  it("not_found：abort 目标 runId 不存在 → throw（pi catch 后置 isError:true）", async () => {
+    const tool = captureTool(makeDeps(), { isProcessing: false });
+    await expect(
+      tool.execute("id", { action: "abort", runId: "no-such-run" }, undefined, undefined, {}),
+    ).rejects.toThrow(
+      "Workflow 'no-such-run' not found. Use action:status to list active runs and their runIds.",
+    );
+  });
+
+  it("W4c not_found：run 目标路径不可读（getPath 返回 available:false stub 而非 undefined）→ throw，不假启动", async () => {
+    // config-loader.toCachedMeta 对不存在/不可读文件返回 available:false 的空壳实体
+    // （非 undefined）——旧判定仅 !script 绕过 not_found，空 sourceCode 的 run 假启动
+    // （W4b verifier 探针实测复现）。registry 层真行为见 config-loader.ts:143-151。
+    const deps = makeDeps({
+      registry: {
+        getPath: vi.fn().mockResolvedValue({
+          name: "ghost-wf",
+          path: "/tmp/no-such-workflow.js",
+          available: false,
+          sourceCode: "",
+          meta: { description: "", parameters: undefined },
+          toExecutable: () => "",
+        }),
+        loadAll: vi.fn().mockResolvedValue([]),
+      },
+    });
+    const tool = captureTool(deps, { isProcessing: false });
+    await expect(
+      tool.execute("id", { action: "run", name: "/tmp/no-such-workflow.js" }, undefined, undefined, {}),
+    ).rejects.toThrow("Workflow '/tmp/no-such-workflow.js' not found.");
+    // 未假启动：runs 注册表不出现该 run
+    expect(deps.runs).toBeInstanceOf(Map);
+    expect((deps.runs as Map<string, unknown>).size).toBe(0);
+  });
+
+  it("reentry-busy：guard 占用 → throw REENTRY_BUSY_MESSAGE，且 guard 状态不被污染", async () => {
+    const guard: ReentryGuardRef = { isProcessing: true };
+    const tool = captureTool(makeDeps(), guard);
+    await expect(
+      tool.execute("id", { action: "status" }, undefined, undefined, {}),
+    ).rejects.toThrow(REENTRY_BUSY_MESSAGE);
+    // throw 发生在 acquire 之前——占用方语义保持，不产生双重 release
+    expect(guard.isProcessing).toBe(true);
+  });
+
+  it("平铺检测：args 子字段提到顶层 → throw 'Detected ... at top level'（含 Correct 正例）", async () => {
+    const deps = makeDeps({
+      registry: {
+        getPath: vi.fn().mockResolvedValue(
+          makeScript({
+            type: "object",
+            properties: { task: { type: "string" }, items: { type: "array" } },
+            required: ["task"],
+          }),
+        ),
+      },
+    });
+    const tool = captureTool(deps, { isProcessing: false });
+    await expect(
+      tool.execute(
+        "id",
+        { action: "run", name: "/abs/demo-wf.js", task: "do work" },
+        undefined,
+        undefined,
+        {},
+      ),
+    ).rejects.toThrow(
+      /Detected task at top level — they belong inside 'args'\. Correct: \{"action":"run","name":"\/abs\/demo-wf\.js","args":\{"task": "<value>"\}\}/,
+    );
+  });
+
+  it("slug 护栏：slug 超 SLUG_MAX_LENGTH → throw 'slug exceeds ...'（运行时第二道）", async () => {
+    const deps = makeDeps({
+      registry: {
+        getPath: vi.fn().mockResolvedValue(
+          makeScript({
+            type: "object",
+            properties: { task: { type: "string" } },
+            required: ["task"],
+          }),
+        ),
+      },
+    });
+    const tool = captureTool(deps, { isProcessing: false });
+    const longSlug = "a".repeat(SLUG_MAX_LENGTH + 1);
+    await expect(
+      tool.execute(
+        "id",
+        { action: "run", name: "/abs/demo-wf.js", slug: longSlug, args: {} },
+        undefined,
+        undefined,
+        {},
+      ),
+    ).rejects.toThrow(
+      `slug exceeds ${SLUG_MAX_LENGTH} chars (got ${longSlug.length}). Shorten to a kebab-case label, e.g. "fix-login", "extract-urls".`,
+    );
+  });
+
+  it("throw 后 reentry guard 经 finally 正常释放（成功路径回归）", async () => {
+    // abort not_found throw 穿透 execute try/finally：guard 必须复位，否则后续命令全部 busy
+    const guard: ReentryGuardRef = { isProcessing: false };
+    const tool = captureTool(makeDeps(), guard);
+    await expect(
+      tool.execute("id", { action: "abort", runId: "no-such-run" }, undefined, undefined, {}),
+    ).rejects.toThrow(/not found/);
+    expect(guard.isProcessing).toBe(false);
+  });
+});

package/src/interface/format.ts

@@ -91,6 +91,12 @@ export function formatElapsedSeconds(seconds: number): string {
 const SHORT_ID_SYNC_SEGMENTS = 2;
 /** background id 取前 N 段（bg/${tag}/${seq}）。 */
 const SHORT_ID_BG_SEGMENTS = 3;
+/** subagent record id 的 `sa-` 前缀（前缀后接 UUID）。 */
+const SA_ID_PREFIX = "sa-";
+/** formatToolCall bash 分支 command 预览截断长度（字符）。 */
+const BASH_PREVIEW_MAX_CHARS = 60;
+/** formatToolCall default 分支 args JSON 预览截断长度（字符）。 */
+const ARGS_PREVIEW_MAX_CHARS = 50;
 
 /**
  * 从完整 record id 提取短编号用于列表展示.
@@ -105,8 +111,8 @@ const SHORT_ID_BG_SEGMENTS = 3;
  */
 export function shortId(id: string): string {
   // sa- 前缀的 subagent ID：保留前缀 + UUID 前 3 段（与纯 UUID 的 3 段信息量等价）
-  if (id.startsWith("sa-")) {
-    return "sa-" + id.slice(3).split("-").slice(0, SHORT_ID_BG_SEGMENTS).join("-");
+  if (id.startsWith(SA_ID_PREFIX)) {
+    return SA_ID_PREFIX + id.slice(SA_ID_PREFIX.length).split("-").slice(0, SHORT_ID_BG_SEGMENTS).join("-");
   }
   const segments = id.split("-");
   if (segments.length <= SHORT_ID_SYNC_SEGMENTS) return id;
@@ -310,7 +316,7 @@ export function formatToolCall(
   switch (toolName) {
     case "bash": {
       const command = (args.command as string) || "...";
-      const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
+      const preview = command.length > BASH_PREVIEW_MAX_CHARS ? `${command.slice(0, BASH_PREVIEW_MAX_CHARS)}...` : command;
       return theme.fg("muted", "$ ") + theme.fg("toolOutput", preview);
     }
     case "read": {
@@ -354,7 +360,7 @@ export function formatToolCall(
     }
     default: {
       const argsStr = JSON.stringify(args);
-      const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr;
+      const preview = argsStr.length > ARGS_PREVIEW_MAX_CHARS ? `${argsStr.slice(0, ARGS_PREVIEW_MAX_CHARS)}...` : argsStr;
       return theme.fg("accent", toolName) + theme.fg("dim", ` ${preview}`);
     }
   }

package/src/interface/tool-render.ts

@@ -46,13 +46,19 @@ const STREAM_PREFIX = "  ⎿ ";
 /** footer 用的纯空格缩进（与 STREAM_PREFIX 等宽 4 列，但不带 ⎿）。 */
 const FOOTER_PREFIX = "    ";
 
+/** process.stdout.columns 不可用（非 TTY 等）时的终端宽度兜底（列）。 */
+const DEFAULT_TERM_WIDTH_COLUMNS = 120;
+
+/** 终端宽度扣减（列）：Pi Box paddingX=1（左右各 1 列）+ 安全余量。 */
+const TERM_WIDTH_BOX_INSET_COLUMNS = 4;
+
 /**
  * 获取终端宽度（参照 nicobailon getTermWidth）。
  * truncLine 需要在创建 Text 之前执行——此时 Pi 的 Box.render(contentWidth) 还未调用，
- * 只能从 process.stdout 估算。-4 对应 Pi Box paddingX=1（左右各 1 列）+ 安全余量。
+ * 只能从 process.stdout 估算。
  */
 function getTermWidth(): number {
-  return (process.stdout.columns || 120) - 4;
+  return (process.stdout.columns || DEFAULT_TERM_WIDTH_COLUMNS) - TERM_WIDTH_BOX_INSET_COLUMNS;
 }
 
 // ============================================================
@@ -99,8 +105,9 @@ export function renderSubagentCall(
   // （displayAgentName）；extractAgentName 原值另被 subagent-tool 的 resolveModel 消费，不动。
   const agent = displayAgentName(extractAgentName(args));
   // slug：从顶层 args 提取（必填字段），非空时在 agent 后用 · 分隔展示。
+  // 断言目标含必填 slug 字段（in 守卫已确认存在），对齐 format.ts extractAgentName 先例。
   const slug = typeof args === "object" && args !== null && "slug" in args
-    ? (args as { slug?: unknown }).slug
+    ? (args as { slug: unknown }).slug
     : undefined;
   const slugStr = typeof slug === "string" ? slug.trim() : "";
   const parts = slugStr