@zhushanwen/subagent-core 0.4.0 → 0.5.1

package/src/execution/engine/common/capability-gate.ts

@@ -0,0 +1,92 @@
+// src/execution/engine/common/capability-gate.ts
+//
+// [D3-④ 预检 capabilities 化] 调用前预检的唯一实现（capabilities 驱动，无引擎 id
+// 特判）。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-④ + r3 裁定
+// （EngineCapabilities 新增 maxTurns 能力位，不保留硬编码 shape 检查）+ §3.4 错误规格
+// 第 1 行（engine_capability_unsupported，既有错误族）。
+//
+// 判据形态：每个引擎拦截「自己 capabilities 声明不支持的能力」——
+//   - conversation → capabilities.conversation === 'unsupported'
+//   - fork/forkFromSessionFile → session 分叉通道族全缺（steer 与 conversation 均
+//     'unsupported'，见下方 fork 判据说明）
+//   - maxTurns → capabilities.maxTurns === false（r3 扩位）
+//   - worktree（boolean true 或 WorktreeHandle）→ capabilities.sandbox === 'none'
+//
+// 调用点仍是两处（单点的是实现，不是调用点）：
+//   - chat 域：executeViaEngine 同步段、record 创建前（engine.capabilities() 同步可得，
+//     承接「全部同步拒绝发生在 record 创建前、不产生孤儿 record」不变量）；
+//   - workflow 域：SAR.run 路由后、engine.run 前（同模块调用）。
+//
+// 行为变化声明（§3.4）：唯一有意行为变化 = workflow 域 zcode+worktree 由漏拦变拦截
+// （修复双轨清单 #7 的跨域缺口）；pi 的 maxTurns/fork/conversation/worktree 等既有
+// 合法能力零拦截（V4⑤ 反向守护——pi 声明 conversation='native'、sandbox='emulated'、
+// maxTurns=true，全数放行）。
+
+import { EngineError } from "./errors.ts";
+import type { EngineCapabilities } from "../types.ts";
+
+/**
+ * 预检输入的任务形状子集——ExecuteOptions（chat 域）与 AgentCallOpts（D6 合流后的
+ * 单一任务形状，workflow 域 SAR 直传）共有的能力相关字段面。结构子集而非具体类型：
+ * 两域的 opts 类型都能直接传入。
+ */
+export interface TaskShapeForGate {
+  conversation?: boolean;
+  fork?: boolean;
+  forkFromSessionFile?: string;
+  worktree?: boolean | { path: string };
+  maxTurns?: number;
+}
+
+/**
+ * 调用前预检：任务形状中的能力参数对引擎 capabilities 逐一对照，声明不支持即抛
+ * EngineError(engine_capability_unsupported)——同步 throw、进程/record 创建前，文案
+ * 含 capabilities 依据与恢复指引（换参数/换引擎）。
+ *
+ * fork 判据说明（借位裁定）：fork 依赖父 session 上下文继承（父会话文件作为分叉源），
+ * 引擎具备该语义的能力面信号 = 会话分叉/交互通道族（steer 或 conversation 任一非
+ * 'unsupported'）。pi conversation='native'（chatMode idle 复用）→ 放行；zcode 双
+ * 'unsupported'（argv-only spawn 单轮，无父 session 分叉通道）→ 拒绝。仅凭 steer 判
+ * 会误拦 pi（pi 的 steer 声明 'unsupported'——RPC 有但 spawn 链路未接通，与 fork 的
+ * 初始上下文继承是两条轴），故取通道族任一可用即支持的分寸。
+ */
+export function assertTaskShapeSupported(
+  engineId: string,
+  caps: EngineCapabilities,
+  task: TaskShapeForGate,
+): void {
+  if (task.conversation === true && caps.conversation === "unsupported") {
+    throw new EngineError(
+      "engine_capability_unsupported",
+      `engine '${engineId}' 不支持 conversation（capabilities.conversation = 'unsupported'，` +
+        `spawn 单轮模式无同进程 idle 复用，message/close 交互控制面不可用）`,
+      `改用 engine: pi（支持 conversation 续聊），或不传该参数（一次性任务默认形态）`,
+    );
+  }
+  if (task.fork === true || task.forkFromSessionFile !== undefined) {
+    if (caps.steer === "unsupported" && caps.conversation === "unsupported") {
+      throw new EngineError(
+        "engine_capability_unsupported",
+        `engine '${engineId}' 不支持 fork${task.forkFromSessionFile !== undefined ? "（fork-from 同为父 session 上下文继承）" : ""}（fork 依赖父 session 上下文继承，` +
+          `capabilities.steer = '${caps.steer}' / conversation = '${caps.conversation}'——引擎无父 session 分叉通道）`,
+        `把所需父上下文写进 task 正文后不传 fork，或改用 engine: pi`,
+      );
+    }
+  }
+  if (task.maxTurns !== undefined && caps.maxTurns === false) {
+    throw new EngineError(
+      "engine_capability_unsupported",
+      `engine '${engineId}' 不支持 maxTurns（capabilities.maxTurns = false，轮数上限依赖 turn_end 事件流，` +
+        `本引擎无此语义——静默丢弃会造成「传了上限却失控」的假象）`,
+      `去掉 maxTurns 参数重派，或改用 engine: pi（turn limiter 执行轮数上限）`,
+    );
+  }
+  if ((task.worktree === true || typeof task.worktree === "object") && caps.sandbox === "none") {
+    throw new EngineError(
+      "engine_capability_unsupported",
+      `engine '${engineId}' 不支持 worktree 隔离（capabilities.sandbox = 'none'，` +
+        `引擎未接文件系统隔离层）`,
+      `改用 engine: pi（worktree 隔离可用），或不传该参数（在 parent cwd 执行）`,
+    );
+  }
+}

package/src/execution/engine/common/journal-wiring.ts

@@ -0,0 +1,97 @@
+// src/execution/engine/common/journal-wiring.ts
+//
+// [D3-③ journal 接线合一] host 侧 event journal 接线的共享 helper（唯一实现，两调用
+// 点——SubagentService.runEngineTask（chat 域）与 SubprocessAgentRunner.run（workflow
+// 域））。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-③（writer +
+// retarget + handle 回填两份提为 common 层共享 helper）+ 双轨清单 #6。
+//
+// 收敛前形态（两份同构接线）：
+//   - subagent-service.ts：new JournalWriter（占位池 key 'shared'）+ retarget 闭包 +
+//     record.engineHandle.journalPath 回填；
+//   - subprocess-agent-runner.ts：new JournalWriter（占位 PI_POOL_KEY）+ retarget 闭包 +
+//     journalingOnEvent 包装（先落盘再转发 workflow liveRecord）+ handle.data.journalPath 回填。
+//
+// 机制语义（对齐点③：路径权威 = 引擎声明的池 key）：writer 初始用占位池 key 建路径，
+// 非池化稳定引擎（zcode）在 prepare 期经 RunContext.onPoolResolved 声明实际池 key →
+// retarget——保证 journal 落盘路径与 handle.poolKey 同源。run 终态后 close（flush +
+// fsync 一次，§3.3.6 写入纪律；写失败已由 writer 内部 warn + failed 收口，close 不抛，
+// journal 是②级尽力而为数据源）。
+
+import type { AgentEvent } from "../../../shared/agent-event.ts";
+import { getEngineDataDir } from "./data-dir.ts";
+import { JournalWriter } from "./event-journal.ts";
+import { resolveJournalPath } from "../paths.ts";
+import type { EngineHandle } from "../types.ts";
+
+/**
+ * journal 初始占位池 key（= pi 的恒定池 key 'shared'）。pi 无隔离池
+ * （PI_CODING_AGENT_DIR 全局一份，设计 §3.3.9），占位即终值；zcode 在 prepare 期
+ * retarget 到实际池 key。值与 RunContext.poolKey 的初始占位同源——本常量是该值在
+ * common 层的单一权威（原先 Service 用 'shared' 字面量、SAR 用 PI_POOL_KEY，等值异名）。
+ */
+export const JOURNAL_INITIAL_POOL_KEY = "shared";
+
+/** wireEventJournal 的参数。 */
+export interface JournalWiringOptions {
+  /** 实际执行引擎 id（journal 路径分段 + line 元数据）。 */
+  engineId: string;
+  /** 宿主侧任务标识（journal 文件名与池引用计数 key：chat 域 = record.id；workflow 域 = 'sa-' 前缀占位）。 */
+  taskId: string;
+  /**
+   * journal 落盘后的事件转发（workflow 域的 liveRecord 通道）。缺省不转发（chat 域
+   * 无下游 onEvent 消费者——journal 是事件唯一出口）。
+   */
+  forwardEvents?: (event: AgentEvent) => void;
+}
+
+/** wireEventJournal 的产物（喂给 RunContext 的回调簇 + 终态收口/回填面）。 */
+export interface JournalWiring {
+  /** journaling onEvent：先落盘再转发——RunContext.onEvent 的值。 */
+  onEvent: (event: AgentEvent) => void;
+  /** RunContext.onPoolResolved 的值（引擎声明实际池 key 后重定向落盘路径）。 */
+  onPoolResolved: (poolKey: string) => void;
+  /**
+   * 终态落盘路径（writer 是路径权威——retarget 后的实际路径）。read 第②级的自描述
+   * 定位符数据源：record.engineHandle.journalPath（chat 域）与 handle.data.journalPath
+   * （workflow 域 backfillHandle）都取本值。
+   */
+  readonly path: string;
+  /** run 终态收口（flush + fsync；幂等，不抛——见文件头）。 */
+  close(): Promise<void>;
+  /**
+   * handle 回填：EngineHandleData.journalPath = writer 终态路径（read ②级经
+   * handle.journalPath 自描述定位——运行期落盘路径权威在 writer）。
+   */
+  backfillHandle(handle: EngineHandle): void;
+}
+
+/**
+ * 接线 host 侧 event journal（两域共用）：创建 writer（占位池 key）+ retarget 回调 +
+ * journaling onEvent 包装 + 终态路径访问。close 在 run 终态（成功/失败路径均达）调用。
+ */
+export function wireEventJournal(opts: JournalWiringOptions): JournalWiring {
+  const journal = new JournalWriter({
+    path: resolveJournalPath(getEngineDataDir(), opts.engineId, JOURNAL_INITIAL_POOL_KEY, opts.taskId),
+    taskId: opts.taskId,
+    engineId: opts.engineId,
+  });
+  return {
+    // 先落盘再转发（原 onEvent 未传时也恒传包装版——下游 onEvent 通道是事件生成后的
+    // 纯转发，无行为分支，仅多一次入队）
+    onEvent: (event) => {
+      journal.append(event);
+      opts.forwardEvents?.(event);
+    },
+    onPoolResolved: (poolKey) => {
+      journal.retarget(resolveJournalPath(getEngineDataDir(), opts.engineId, poolKey, opts.taskId));
+    },
+    // getter 而非快照：retarget 后取实际落盘路径（writer 是路径权威）
+    get path() {
+      return journal.path;
+    },
+    close: () => journal.close(),
+    backfillHandle: (handle) => {
+      handle.data.journalPath = journal.path;
+    },
+  };
+}

package/src/execution/engine/common/kill-chain.ts

@@ -10,8 +10,10 @@
 import { getLogger } from "../../../core/logger.ts";
 
 import { engineTimeoutDetail } from "./errors.ts";
-import type { AgentOutcome, AgentTaskSpec } from "../types.ts";
+import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
+import type { AgentOutcome } from "../types.ts";
 import { DEFAULT_ENGINE_ID } from "../registry.ts";
+import { toErrorMessage } from "../../../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
@@ -34,6 +36,11 @@ export interface KillableChild {
   once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
 }
 
+// 毫秒→秒换算（SIGKILL 升级 warn 日志的秒数显示）。文件内私有定义：工程内 MS_PER_SECOND
+// 惯例是各使用文件私有常量（execution-record / lifecycle-manager / session-file-gc /
+// session-runner 四处先例），无共享导出源可 import，保持同惯例不另立导出点。
+const MS_PER_SECOND = 1_000;
+
 /** SIGTERM 优雅窗口默认值（ms）。实测校准点：设计 §5 待验证检查点⑤（zcode 对 SIGTERM 的响应时序）。 */
 export const DEFAULT_KILL_GRACE_MS = 5_000;
 
@@ -47,6 +54,25 @@ const SIGKILL_REAP_TIMEOUT_MS = 10_000;
  */
 export const HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
 
+/** killChain 的参数形状。 */
+export interface KillChainOptions {
+  /**
+   * SIGTERM 优雅窗口（ms）。grace 窗口按引擎参数化（D3-① 杀链合一）：pi 传 30s
+   * （[race-F4] 现状值）、zcode 传 5s（ZCODE_KILL_GRACE_MS）——两引擎现状逐字节保持。
+   */
+  graceMs: number;
+  /**
+   * [D3-①] 内部 timer unref。pi 路径现状 = 升级 timer unref（不阻止主进程退出，dispose
+   * killAll 兜底）；zcode 现状 = ref'd（timer 挂起时进程等待收尸）——各引擎按现状传。
+   */
+  unrefTimers?: boolean;
+  /**
+   * SIGKILL 升级时的 warn 留痕载体（如 `child sa-xxx (source: spawn watchdog)`）。
+   * 不传则升级静默（zcode 现状）——pi 侧现状有 warn，由调用方组装完整语境。
+   */
+  escalationNote?: string;
+}
+
 /**
  * 杀链：SIGTERM → 等待 graceMs → 仍存活则 SIGKILL。
  *
@@ -54,7 +80,7 @@ export const HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
  */
 export async function killChain(
   child: KillableChild,
-  opts: { graceMs: number },
+  opts: KillChainOptions,
 ): Promise<"terminated" | "killed"> {
   // 已退出（自然/已被杀）→ 无需发信号，按优雅终止口径返回
   if (child.exitCode !== null || child.signalCode !== null) return "terminated";
@@ -62,14 +88,19 @@ export async function killChain(
   const exited = waitForExit(child);
   safeKill(child, "SIGTERM");
 
-  const graceful = await raceTimeout(exited, opts.graceMs);
+  const graceful = await raceTimeout(exited, opts.graceMs, opts.unrefTimers === true);
   if (graceful === "settled") return "terminated";
   // grace 超时后进程可能恰好在检查前一刻退出——复核退出态，避免误杀已死进程
   if (child.exitCode !== null || child.signalCode !== null) return "terminated";
 
+  if (opts.escalationNote !== undefined) {
+    logger.warn(
+      `[kill-chain] ${opts.escalationNote} still alive ${opts.graceMs / MS_PER_SECOND}s after SIGTERM, escalating to SIGKILL`,
+    );
+  }
   safeKill(child, "SIGKILL");
   // 有界收尸：无论等到与否都返回 'killed'（信号已发出，返回值表达「走了 SIGKILL」）
-  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS);
+  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS, opts.unrefTimers === true);
   return "killed";
 }
 
@@ -83,7 +114,7 @@ function safeKill(child: KillableChild, signal: NodeJS.Signals): void {
     child.kill(signal);
   } catch (err) {
     logger.debug(
-      `[kill-chain] ${signal} on exited process: ${err instanceof Error ? err.message : String(err)}`,
+      `[kill-chain] ${signal} on exited process: ${toErrorMessage(err)}`,
     );
   }
 }
@@ -98,14 +129,14 @@ function safeKill(child: KillableChild, signal: NodeJS.Signals): void {
  * exitCode: null = 被信号杀死（AgentOutcome 的杀链判据，§3.3.5）。
  */
 export function synthesizeTimeoutOutcome(
-  task: AgentTaskSpec,
+  task: AgentCallOpts,
   stdoutTail: string,
   engineId: string = DEFAULT_ENGINE_ID,
 ): AgentOutcome {
   return {
     content: "",
     // slug 进错误信息：单看 outcome（record 之外）也能定位是哪个任务超时
-    error: `engine_timeout: [slug=${task.slug}] ${engineTimeoutDetail(stdoutTail)}`,
+    error: `engine_timeout: [slug=${task.description ?? "unknown"}] ${engineTimeoutDetail(stdoutTail)}`,
     // 被信号杀死：退出码语义为 null（§3.3.5 AgentOutcome.exitCode 注释）
     exitCode: null,
     engineId,
@@ -161,7 +192,7 @@ export function abortWithFallback(
             // debug 级留诊断线索：这不是错误终态，只是该引擎优雅中断不可用
             logger.debug(
               `[kill-chain] native interrupt failed, falling back to kill chain: ${
-                err instanceof Error ? err.message : String(err)
+                toErrorMessage(err)
               }`,
             );
           }
@@ -202,10 +233,11 @@ function waitForExit(child: KillableChild): Promise<void> {
   });
 }
 
-/** promise vs 超时：超时先到返回 'timeout'（promise 继续但被放弃等待）。 */
-function raceTimeout(p: Promise<void>, ms: number): Promise<"settled" | "timeout"> {
+/** promise vs 超时：超时先到返回 'timeout'（promise 继续但被放弃等待）。unref 见 KillChainOptions。 */
+function raceTimeout(p: Promise<void>, ms: number, unref = false): Promise<"settled" | "timeout"> {
   return new Promise<"settled" | "timeout">((resolve) => {
     const timer = setTimeout(() => resolve("timeout"), ms);
+    if (unref) timer.unref();
     p.then(
       () => {
         clearTimeout(timer);

package/src/execution/engine/common/nesting-guard.ts

@@ -8,6 +8,13 @@
 //
 // 为什么 env 标记是唯一跨引擎可靠手段（被否方案见设计）：「隔离目录里不装扩展」
 // 依赖配置洁癖，且 opencode/CC 会吃项目级配置；env 由宿主显式控制，随 spawn 必达。
+//
+// [D3-⑤ 嵌套防护合一] 进程内执行嵌套上下文（原 SubagentService.execCtxAls，pi 路径
+// 私有）并入本文件——「嵌套防护」的两层机制（跨进程 env 标记 / 进程内 ALS 深度计数）
+// 单点于公共层。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-⑤
+// + 双轨清单 #10。
+
+import { AsyncLocalStorage } from "node:async_hooks";
 
 import { nestedSpawnRejectedError } from "./errors.ts";
 
@@ -48,3 +55,62 @@ export function assertNotNestedSpawn(env: SpawnEnv): void {
     throw nestedSpawnRejectedError();
   }
 }
+
+// ============================================================
+// [D3-⑤] 进程内执行嵌套上下文（原 SubagentService.execCtxAls 下沉）
+// ============================================================
+
+/** 执行嵌套状态：当前正在跑的 record 身份 + 递归深度（D-033 通用嵌套深度护栏的计数载体）。 */
+export interface ExecutionNestingState {
+  recordId: string | undefined;
+  depth: number;
+}
+
+/**
+ * 进程内执行嵌套上下文（[D3-⑤] 从 SubagentService 的 execCtxAls 私有字段并入公共层）。
+ *
+ * 机制（原样迁移，行为零变化）：
+ *   - ALS 按异步调用链传递当前 record 身份：B run() 期间包 this 上下文，B 内创建 C 时
+ *     读到 B → C.parentRecordId=B.id、C.depth=B.depth+1；主 session 链上无 store → 顶层。
+ *   - 进程级基线兜底 [ALS 断裂修复]：pi RPC mode 的 stdin JSONL 是事件回调式
+ *     （attachJsonlLineReader stream.on("data")），每个命令是独立异步链，enterWith 的
+ *     store 不会贯穿到后续 tool 调用事件（实测：递归第二层 parentRecordId/depth 丢失
+ *     而 rootSessionId 正确）。基线 = 本进程自己的身份（initSession 从 env 读取）：
+ *     读 ALS store 失败时兜底，保证「本进程派发的 subagent 都是本进程记录的孩子」。
+ *
+ * 实例归属：per-Service（基线随宿主进程身份而异），Service 构造时创建并持有。
+ * 深度上限判据（MAX_FORK_DEPTH）留在调用方——上限常量属 execution 层
+ * （session-context-resolver），公共层只提供状态存取单点。
+ */
+export class ExecutionNestingContext {
+  private readonly als = new AsyncLocalStorage<ExecutionNestingState>();
+  private baselineState: ExecutionNestingState | null = null;
+
+  /** 建立进程级基线（initSession：有 env 自我标记 → env 身份；根进程 → null 顶层）。 */
+  setBaseline(state: ExecutionNestingState | null): void {
+    this.baselineState = state;
+  }
+
+  /** 读当前嵌套状态：ALS store 优先，断裂时基线兜底（顶层 = null）。 */
+  current(): ExecutionNestingState | null {
+    return this.als.getStore() ?? this.baselineState;
+  }
+
+  /**
+   * 读进程级基线（与 current() 的差异：不看 ALS store——直接父归属校验等场景要的是
+   * 「本进程自己的身份」而非「当前异步链正在跑的 record 身份」）。
+   */
+  baseline(): ExecutionNestingState | null {
+    return this.baselineState;
+  }
+
+  /** 包裹执行（B run() 期间挂 B 身份——内层创建 C 时 current() 读到 B）。 */
+  run<T>(state: ExecutionNestingState, fn: () => T): T {
+    return this.als.run(state, fn);
+  }
+
+  /** 顶层 enterWith（initSession 建立基线身份后挂入当前异步链）。 */
+  enterWith(state: ExecutionNestingState): void {
+    this.als.enterWith(state);
+  }
+}

package/src/execution/engine/common/persona-router.ts

@@ -14,7 +14,18 @@
 //   - 'prompt'→ promptSegment 为带引导结构的人设段（拼进最终 prompt——zcode 形态）。
 
 import { promptTooLargeError } from "./errors.ts";
-import type { EngineCapabilities, PersonaSpec } from "../types.ts";
+import type { EngineCapabilities } from "../types.ts";
+
+/**
+ * 人设注入内容（[D6 合流] 原 PersonaSpec 的内容面——收拢层删除后 persona 路由
+ * 只需人设正文的两个来源字段，取合流形状 AgentCallOpts 的结构子集：appendSystemPrompt
+ * 是人设正文，skillPath 以引用提示行进文本。原 agentRef 字段随 PersonaSpec 裁撤
+ * （无生产写入方）。
+ */
+export interface PersonaContent {
+  appendSystemPrompt?: string[];
+  skillPath?: string;
+}
 
 // ============================================================
 // persona 三策略路由
@@ -35,10 +46,10 @@ const PERSONA_FILE_NAME = "persona.md";
  * 按 capabilities.personaInjection 路由 persona 的注入通道。
  *
  * router 不解析 agent .md / skill 文件内容（身份解析归宿主 resolveIdentity）——
- * 只把 PersonaSpec 声明的内容组装成通道载体：appendSystemPrompt 是人设正文，
- * agentRef/skillPath 以引用提示行进文本（prompt 通道）或正文头（file 通道）。
+ * 只把 PersonaContent 声明的内容组装成通道载体：appendSystemPrompt 是人设正文，
+ * skillPath 以引用提示行进文本（prompt 通道）或正文头（file 通道）。
  */
-export function applyPersona(persona: PersonaSpec, capabilities: EngineCapabilities): PersonaRouting {
+export function applyPersona(persona: PersonaContent, capabilities: EngineCapabilities): PersonaRouting {
   switch (capabilities.personaInjection) {
     case "file": {
       const content = buildPersonaBody(persona);
@@ -54,10 +65,9 @@ export function applyPersona(persona: PersonaSpec, capabilities: EngineCapabilit
   }
 }
 
-/** 人设正文：appendSystemPrompt join + agentRef/skillPath 头部引用行。 */
-function buildPersonaBody(persona: PersonaSpec): string {
+/** 人设正文：appendSystemPrompt join + skillPath 头部引用行。 */
+function buildPersonaBody(persona: PersonaContent): string {
   const parts: string[] = [];
-  if (persona.agentRef !== undefined) parts.push(`# Agent: ${persona.agentRef}`);
   if (persona.skillPath !== undefined) parts.push(`Skill context: ${persona.skillPath}`);
   const body = persona.appendSystemPrompt?.join("\n") ?? "";
   if (body !== "") parts.push(body);
@@ -65,7 +75,7 @@ function buildPersonaBody(persona: PersonaSpec): string {
 }
 
 /** prompt 通道的人设段（带结构头，拼进最终 prompt）。 */
-function buildPromptSegment(persona: PersonaSpec): string {
+function buildPromptSegment(persona: PersonaContent): string {
   const body = buildPersonaBody(persona);
   if (body === "") return "";
   return `## Persona\n${body}`;