@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/workflows/scatter-gather.js

@@ -8,7 +8,8 @@
 // 适用于"任务太大需要先拆分再并行处理"的场景。
 //
 // 用法：
-//   workflow run scatter-gather --args task="重构认证模块，涉及 session/jwt/oauth 三块"
+//   workflow run scatter-gather --args task="重构认证模块，涉及 session/jwt/oauth 三块"（pi 宿主语法）
+//   zsw workflow --workflow scatter-gather --task "<大任务描述>" --workdir <绝对路径>（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际执行以 SessionStart 注入段的 node "<绝对路径>/bin/zsw.js" 形态为准；per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 //
 // ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口（兼 agent 嵌套），禁止 bare IIFE
 
@@ -26,7 +27,8 @@ usage: |
   ## 使用说明
   - scatter 拆解大任务 → process 并行处理 → gather 聚合结果
   - agents：逗号分隔的 agent .md 绝对路径，按顺序对应 scatter/process/gather 三段
-  - 示例：workflow run scatter-gather --args task="<大任务描述>" agents="/path/splitter.md,/path/processor.md"
+  - 示例（pi 宿主语法）：workflow run scatter-gather --args task="<大任务描述>" agents="/path/splitter.md,/path/processor.md"
+  - 示例（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际以注入段 node "<绝对路径>/bin/zsw.js" 形态为准）：zsw workflow --workflow scatter-gather --task "<大任务描述>" --workdir <绝对路径>（per-workflow 参数用 zsw 专属 flag，语义见 @pi-meta parameters）
 */
 
 // ── 入参（$ARGS）──────────────────────────────────────────────────

package/dist/chunk-3VOERJPJ.js

@@ -1,22 +0,0 @@
-// src/execution/engine/engines/zcode/constants.ts
-var ZCODE_ENGINE_ID = "zcode";
-var ZCODE_ADAPTER_VERSION = "1.0.0";
-var ZCODE_CLI_DEFAULT_PATH = "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
-var ZCODE_V2_CONFIG_PATH_SUFFIX = [".zcode", "v2", "config.json"];
-var ZCODE_POOL_CONFIG_SUFFIX = [".zcode", "cli", "config.json"];
-var ZCODE_POOL_DB_RELATIVE_PATH = ".zcode/cli/db/db.sqlite";
-var ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
-var ZCODE_KILL_GRACE_MS = 5e3;
-var ZCODE_ERROR_TAIL_CHARS = 2e3;
-
-export {
-  ZCODE_ENGINE_ID,
-  ZCODE_ADAPTER_VERSION,
-  ZCODE_CLI_DEFAULT_PATH,
-  ZCODE_V2_CONFIG_PATH_SUFFIX,
-  ZCODE_POOL_CONFIG_SUFFIX,
-  ZCODE_POOL_DB_RELATIVE_PATH,
-  ZCODE_FALLBACK_DEFAULT_MODEL,
-  ZCODE_KILL_GRACE_MS,
-  ZCODE_ERROR_TAIL_CHARS
-};

package/src/execution/__tests__/execute-options-mapper.test.ts

@@ -1,200 +0,0 @@
-// src/execution/__tests__/execute-options-mapper.test.ts
-//
-// T3.4 (边界): cwd 透传（非 git worktree）
-// T3.5 (边界): model 填底——opts.model 空 → ctxModel（D-008）
-// T3.9 (边界): schemaEnv 透传——opts.schemaEnv → ExecuteOptions.schemaEnv
-// T3.6 (异常): timeoutMs 超时 → 合并 signal abort → T3.17 listener 清理
-//
-// 测试范围: mapToExecuteOptions 全字段映射 + mergeTimeoutSignal 行为
-
-import { describe, expect, it, vi } from "vitest";
-
-import type { AgentCallOpts } from "../../orchestration/models/types.ts";
-import { mapToExecuteOptions, mergeTimeoutSignal } from "../execute-options-mapper.ts";
-import type { ModelInfo } from "../model-resolver.ts";
-
-describe("mapToExecuteOptions (D-A2)", () => {
-  const baseOpts: AgentCallOpts = {
-    prompt: "test task",
-    agent: "worker",
-    schema: { type: "object" },
-    cwd: "/tmp/work",
-    skillPath: "/path/to/skill.md",
-  };
-
-  it("T3.10 slug 截断: description > SLUG_MAX_LENGTH(35) → 截断到 35", () => {
-    const opts: AgentCallOpts = { ...baseOpts, description: "a".repeat(36) };
-    const result = mapToExecuteOptions(opts);
-    expect(result.slug).toHaveLength(35);
-    expect(result.slug).toBe("a".repeat(35));
-  });
-
-  it("T3.10 slug 边界: description = 35 → 不截断", () => {
-    const opts: AgentCallOpts = { ...baseOpts, description: "a".repeat(35) };
-    const result = mapToExecuteOptions(opts);
-    expect(result.slug).toHaveLength(35);
-    expect(result.slug).toBe("a".repeat(35));
-  });
-
-  it("T3.10 slug 回落: 无 description → agentName", () => {
-    const result = mapToExecuteOptions(baseOpts);
-    expect(result.slug).toBe("worker");
-  });
-
-  it("T3.4 基本映射: prompt→task, agent→agent, cwd→cwd", () => {
-    const result = mapToExecuteOptions(baseOpts);
-    expect(result.task).toBe("test task");
-    expect(result.agent).toBe("worker");
-    expect(result.cwd).toBe("/tmp/work");
-  });
-
-  it("T3.4 schema 透传", () => {
-    const result = mapToExecuteOptions(baseOpts);
-    expect(result.schema).toEqual({ type: "object" });
-  });
-
-  it("T3.9 schemaEnv 透传 (D-A6 bridge)", () => {
-    const opts: AgentCallOpts = { ...baseOpts, schemaEnv: '{"type":"object"}' };
-    const result = mapToExecuteOptions(opts);
-    expect(result.schemaEnv).toBe('{"type":"object"}');
-  });
-
-  it("T3.9 schemaEnv 不传 → schemaEnv undefined", () => {
-    const result = mapToExecuteOptions(baseOpts);
-    expect(result.schemaEnv).toBeUndefined();
-  });
-
-  it("T3.5 model: opts.model 优先（显式 override 透传，不与 ctxModel 混合）", () => {
-    const opts: AgentCallOpts = { ...baseOpts, model: "explicit-model" };
-    const ctxModel: ModelInfo = { id: "ctx-model", provider: "test", input: [] } as ModelInfo;
-    const result = mapToExecuteOptions(opts, ctxModel);
-    expect(result.model).toBe("explicit-model");
-  });
-
-  it("T3.5 model: opts.model 空 → model undefined（不再从 ctxModel.id 填底）", () => {
-    const ctxModel: ModelInfo = { id: "ctx-model", provider: "test", input: [] } as ModelInfo;
-    const result = mapToExecuteOptions(baseOpts, ctxModel);
-    expect(result.model).toBeUndefined();
-  });
-
-  it("T3.5 ctxModel 透传: opts.model 空时 ctxModel 作为完整 ModelInfo 对象传入 ExecuteOptions.ctxModel", () => {
-    const ctxModel: ModelInfo = { id: "mimo-v2.5-pro", provider: "router-openai", input: [] } as ModelInfo;
-    const result = mapToExecuteOptions(baseOpts, ctxModel);
-    expect(result.ctxModel).toBe(ctxModel);
-    expect(result.ctxModel?.id).toBe("mimo-v2.5-pro");
-    expect(result.ctxModel?.provider).toBe("router-openai");
-  });
-
-  it("T3.5 ctxModel 透传: opts.model 有值时 ctxModel 仍透传（双层可用）", () => {
-    const opts: AgentCallOpts = { ...baseOpts, model: "explicit-model" };
-    const ctxModel: ModelInfo = { id: "ctx-model", provider: "test", input: [] } as ModelInfo;
-    const result = mapToExecuteOptions(opts, ctxModel);
-    expect(result.model).toBe("explicit-model");
-    expect(result.ctxModel).toBe(ctxModel);
-  });
-
-  it("T3.5 ctxModel: 两层均空 → model/ctxModel 都 undefined", () => {
-    const result = mapToExecuteOptions(baseOpts);
-    expect(result.model).toBeUndefined();
-    expect(result.ctxModel).toBeUndefined();
-  });
-
-  it("skillPath 透传", () => {
-    const result = mapToExecuteOptions(baseOpts);
-    expect(result.skillPath).toBe("/path/to/skill.md");
-  });
-
-  it("thinkingLevel 透传 (M1)", () => {
-    const opts: AgentCallOpts = { ...baseOpts, thinkingLevel: "high" };
-    const result = mapToExecuteOptions(opts);
-    expect(result.thinkingLevel).toBe("high");
-  });
-
-  it("thinkingLevel 不传 → thinkingLevel undefined", () => {
-    const result = mapToExecuteOptions(baseOpts);
-    expect(result.thinkingLevel).toBeUndefined();
-  });
-
-  it("appendSystemPrompt → appendSystemPrompt 透传", () => {
-    const opts: AgentCallOpts = { ...baseOpts, appendSystemPrompt: ["SO instruction content"] };
-    const result = mapToExecuteOptions(opts);
-    expect(result.appendSystemPrompt).toEqual(["SO instruction content"]);
-  });
-
-  it("appendSystemPrompt 不传 → appendSystemPrompt undefined", () => {
-    const result = mapToExecuteOptions(baseOpts);
-    expect(result.appendSystemPrompt).toBeUndefined();
-  });
-
-  it("maxTurns 透传（预算语义对齐：workflow agent() 可显式传 turn 上限）", () => {
-    const opts: AgentCallOpts = { ...baseOpts, maxTurns: 20 };
-    const result = mapToExecuteOptions(opts);
-    expect(result.maxTurns).toBe(20);
-  });
-
-  it("maxTurns 不传 → undefined（不限 turn，不挂 turns 估算 watchdog）", () => {
-    const result = mapToExecuteOptions(baseOpts);
-    expect(result.maxTurns).toBeUndefined();
-  });
-});
-
-describe("mergeTimeoutSignal (D-A9)", () => {
-  it("T3.6 timeoutMs===undefined → 原样返回 external signal", () => {
-    const ctrl = new AbortController();
-    const result = mergeTimeoutSignal(ctrl.signal, undefined);
-    expect(result).toBe(ctrl.signal);
-  });
-
-  it("T3.6 timeoutMs<=0 → 原样返回 external signal", () => {
-    const ctrl = new AbortController();
-    const result = mergeTimeoutSignal(ctrl.signal, 0);
-    expect(result).toBe(ctrl.signal);
-  });
-
-  it("T3.6 timeoutMs>0 → 返回新 signal（合并外部+超时两路）", () => {
-    const ctrl = new AbortController();
-    const result = mergeTimeoutSignal(ctrl.signal, 50);
-    expect(result).not.toBe(ctrl.signal);
-    expect(result.aborted).toBe(false);
-  });
-
-  it("T3.6 timeoutMs 到期 → merged signal abort", async () => {
-    vi.useFakeTimers();
-    const ctrl = new AbortController();
-    const merged = mergeTimeoutSignal(ctrl.signal, 50);
-
-    expect(merged.aborted).toBe(false);
-    vi.advanceTimersByTime(51);
-    expect(merged.aborted).toBe(true);
-    vi.useRealTimers();
-  });
-
-  it("T3.6 外部 signal abort → merged signal abort", () => {
-    const ctrl = new AbortController();
-    const merged = mergeTimeoutSignal(ctrl.signal, 5000);
-    ctrl.abort();
-    expect(merged.aborted).toBe(true);
-  });
-
-  it("T3.6 外部 signal 已 abort → 返回已 abort 的 signal", () => {
-    const ctrl = new AbortController();
-    ctrl.abort();
-    const merged = mergeTimeoutSignal(ctrl.signal, 5000);
-    expect(merged.aborted).toBe(true);
-  });
-
-  it("T3.17 NFR: merged signal abort → timeout timer 清理", () => {
-    vi.useFakeTimers();
-    const ctrl = new AbortController();
-    const merged = mergeTimeoutSignal(ctrl.signal, 50);
-
-    ctrl.abort(); // 外部 abort → merged 也 abort
-    expect(merged.aborted).toBe(true);
-
-    // 推进时间，不应再有副作用
-    vi.advanceTimersByTime(100);
-    // timer 应被清理（通过 abort event listener）
-    // 无异常 = timer 已正确清理
-    vi.useRealTimers();
-  });
-});

package/src/execution/engine/engines/pi/__tests__/task-spec-mapper.test.ts

@@ -1,164 +0,0 @@
-// src/execution/engine/engines/pi/__tests__/task-spec-mapper.test.ts
-//
-// AgentTaskSpec ↔ ExecuteOptions 映射测试（P1 验收 3：往返保真）。
-// 覆盖：effort/thinkingLevel 双向映射、persona/skillPath 归并还原、
-// conversation/idleTimeoutMs 透传、schemaEnv 派生逐字节等值（D-A6 bridge）、
-// 运行期字段（signal/ctxModel/onComplete）不入任务声明。
-
-import { describe, expect, it } from "vitest";
-
-import type { ExecuteOptions } from "../../../../types.ts";
-import type { AgentTaskSpec } from "../../../types.ts";
-import { executeOptionsToTaskSpec, taskSpecToExecuteOptions } from "../task-spec-mapper.ts";
-
-describe("task-spec-mapper（ExecuteOptions ↔ AgentTaskSpec 往返保真）", () => {
-  /** 全字段样例（含全部泛化点）。 */
-  function makeFullOpts(): ExecuteOptions {
-    return {
-      task: "review the diff",
-      slug: "review-diff",
-      agent: "/agents/reviewer.md",
-      model: "zai-coding-cn/glm-5.2",
-      thinkingLevel: "high",
-      skillPath: "/skills/code-review/SKILL.md",
-      appendSystemPrompt: ["extra system prompt line"],
-      schema: { type: "object", properties: { verdict: { type: "string" } }, required: ["verdict"] },
-      maxTurns: 20,
-      graceTurns: 3,
-      fork: true,
-      worktree: true,
-      cwd: "/repo/worktree-x",
-      conversation: true,
-      idleTimeoutMs: 600_000,
-    };
-  }
-
-  it("全字段往返恒等（P1 行为零变化的映射层证据）", () => {
-    const opts = makeFullOpts();
-    const round = taskSpecToExecuteOptions(executeOptionsToTaskSpec(opts));
-    // schemaEnv 是派生字段（派生正确性单独断言），其余逐字段恒等
-    const { schemaEnv, ...rest } = round;
-    expect(rest).toEqual(opts);
-    expect(schemaEnv).toBe(JSON.stringify(opts.schema));
-  });
-
-  it("effort ↔ thinkingLevel 双向映射（pi 恒等透传，含 7 档外的缺省）", () => {
-    for (const level of ["off", "low", "medium", "high", "max", undefined]) {
-      const opts: ExecuteOptions = { task: "t", slug: "s", thinkingLevel: level };
-      const spec = executeOptionsToTaskSpec(opts);
-      expect(spec.effort).toBe(level);
-      expect(taskSpecToExecuteOptions(spec).thinkingLevel).toBe(level);
-    }
-  });
-
-  it("persona 归并：skillPath + appendSystemPrompt 收拢进 persona", () => {
-    const spec = executeOptionsToTaskSpec({
-      task: "t",
-      slug: "s",
-      skillPath: "/skills/x/SKILL.md",
-      appendSystemPrompt: ["line1", "line2"],
-    });
-    expect(spec.persona).toEqual({ skillPath: "/skills/x/SKILL.md", appendSystemPrompt: ["line1", "line2"] });
-    // 还原
-    const back = taskSpecToExecuteOptions(spec);
-    expect(back.skillPath).toBe("/skills/x/SKILL.md");
-    expect(back.appendSystemPrompt).toEqual(["line1", "line2"]);
-  });
-
-  it("persona 缺省：无 skillPath/appendSystemPrompt 时 persona 不存在（无空对象噪声）", () => {
-    const spec = executeOptionsToTaskSpec({ task: "t", slug: "s" });
-    expect(spec.persona).toBeUndefined();
-    expect(taskSpecToExecuteOptions(spec).skillPath).toBeUndefined();
-    expect(taskSpecToExecuteOptions(spec).appendSystemPrompt).toBeUndefined();
-  });
-
-  it("persona 单字段归并：仅 skillPath（appendSystemPrompt 保持 undefined）", () => {
-    const spec = executeOptionsToTaskSpec({ task: "t", slug: "s", skillPath: "/s" });
-    expect(spec.persona).toEqual({ skillPath: "/s" });
-    const back = taskSpecToExecuteOptions(spec);
-    expect(back.skillPath).toBe("/s");
-    expect(back.appendSystemPrompt).toBeUndefined();
-  });
-
-  it("conversation / idleTimeoutMs 原名透传（interact 控制面的 task 标志）", () => {
-    const opts: ExecuteOptions = { task: "t", slug: "s", conversation: true, idleTimeoutMs: 12345 };
-    const spec = executeOptionsToTaskSpec(opts);
-    expect(spec.conversation).toBe(true);
-    expect(spec.idleTimeoutMs).toBe(12345);
-    const back = taskSpecToExecuteOptions(spec);
-    expect(back.conversation).toBe(true);
-    expect(back.idleTimeoutMs).toBe(12345);
-  });
-
-  it("schemaEnv 派生：与 agent-opts-resolver 同函数（stringifySchemaCached compact），逐字节等值", () => {
-    const schema = { type: "object", properties: { a: { type: "number" } } };
-    const spec = executeOptionsToTaskSpec({ task: "t", slug: "s", schema });
-    // 无 schema 时 schemaEnv 不设（BC-6：childEnv 不注入）
-    expect(taskSpecToExecuteOptions({ task: "t", slug: "s" }).schemaEnv).toBeUndefined();
-    // 有 schema 时派生 = JSON.stringify(schema)（resolver 的 compact 形态）
-    expect(taskSpecToExecuteOptions(spec).schemaEnv).toBe(JSON.stringify(schema));
-    // 原 schemaEnv（resolver 产物）经往返后逐字节保持
-    const optsWithEnv: ExecuteOptions = {
-      task: "t",
-      slug: "s",
-      schema,
-      schemaEnv: JSON.stringify(schema),
-    };
-    const round = taskSpecToExecuteOptions(executeOptionsToTaskSpec(optsWithEnv));
-    expect(round.schemaEnv).toBe(optsWithEnv.schemaEnv);
-  });
-
-  it("解耦形态（有 schemaEnv 无 schema，生产不可达）：经 RunContext 兜底透传，派生优先", () => {
-    const spec = executeOptionsToTaskSpec({ task: "t", slug: "s", schemaEnv: '{"type":"object"}' });
-    // 声明侧无 schema（schemaEnv 不入任务声明，§3.3.5 删字段去向）
-    expect(spec.schema).toBeUndefined();
-    // 兜底通道（RunContext.schemaEnv → mapper schemaEnvFallback）
-    const back = taskSpecToExecuteOptions(spec, { schemaEnvFallback: '{"type":"object"}' });
-    expect(back.schemaEnv).toBe('{"type":"object"}');
-    // 派生优先：schema 存在时 fallback 被忽略（派生值 = JSON.stringify(schema)）
-    const coupled = { ...spec, schema: { type: "object" } };
-    expect(taskSpecToExecuteOptions(coupled, { schemaEnvFallback: "STALE" }).schemaEnv).toBe('{"type":"object"}');
-  });
-
-  it("运行期字段不入任务声明：signal/ctxModel/onComplete 从 ExecuteOptions 剥离（移入 RunContext）", () => {
-    const ctxModel = { id: "m", name: "Test Model", provider: "p", reasoning: false };
-    const opts: ExecuteOptions = {
-      task: "t",
-      slug: "s",
-      ctxModel,
-      onComplete: () => {},
-    };
-    const spec = executeOptionsToTaskSpec(opts);
-    expect("ctxModel" in spec).toBe(false);
-    expect("onComplete" in spec).toBe(false);
-    expect("signal" in spec).toBe(false);
-    // ctxModel 从 RunContext 回填（SAR 接线的 D-008 兼底链路）
-    expect(taskSpecToExecuteOptions(spec, { ctxModel }).ctxModel).toBe(ctxModel);
-    expect(taskSpecToExecuteOptions(spec).ctxModel).toBeUndefined();
-  });
-
-  it("中立新字段 denyTools/permissionMode：pi 侧映射回 ExecuteOptions 时忽略（无对应面）", () => {
-    const spec: AgentTaskSpec = { task: "t", slug: "s", denyTools: ["bash"], permissionMode: "yolo" };
-    const opts = taskSpecToExecuteOptions(spec);
-    expect("denyTools" in opts).toBe(false);
-    expect("permissionMode" in opts).toBe(false);
-    // 声明侧字段保真（不因 pi 不支持而丢弃——P2 公共层消费）
-    expect(spec.denyTools).toEqual(["bash"]);
-    expect(spec.permissionMode).toBe("yolo");
-  });
-
-  it("归一化：appendSystemPrompt: [] 与 undefined 往返后等价（下游 spread 空数组为 no-op）", () => {
-    const spec = executeOptionsToTaskSpec({ task: "t", slug: "s", appendSystemPrompt: [] });
-    expect(spec.persona).toEqual({ appendSystemPrompt: [] });
-    const back = taskSpecToExecuteOptions(spec);
-    expect(back.appendSystemPrompt).toEqual([]);
-  });
-
-  it("worktree 三态（true/false/handle）往返保持", () => {
-    const handle = { path: "/wt", branch: "b", baseCommit: "c", mainCwd: "/repo" };
-    for (const wt of [true, false, handle] as const) {
-      const opts: ExecuteOptions = { task: "t", slug: "s", worktree: wt };
-      expect(taskSpecToExecuteOptions(executeOptionsToTaskSpec(opts)).worktree).toBe(wt);
-    }
-  });
-});

package/src/execution/engine/engines/pi/task-spec-mapper.ts

@@ -1,100 +0,0 @@
-// src/execution/engine/engines/pi/task-spec-mapper.ts
-//
-// AgentTaskSpec ↔ ExecuteOptions 映射（P1 回填）。pi 专有语义的隔离点（设计 §3.3.5
-// 删字段去向 + P1 行「ExecuteOptions→AgentTaskSpec 映射层」）：
-//   - effort ↔ thinkingLevel：pi 的 7 档枚举是引擎私有语义，中立层只透传字符串——
-//     pi 侧恒等映射（不识别的档位与现状一致：交 resolveModel 层处理）；
-//   - persona ↔ skillPath + appendSystemPrompt：skillPath 并入 persona 语义（D2），
-//     pi 侧原样还原（pi 的 persona 注入通道 = --skill/--append-system-prompt flag）；
-//   - schemaEnv 内化：中立层无此字段，PiEngine 从 task.schema 派生（stringifySchemaCached
-//     compact——与 agent-opts-resolver 同一函数同一缓存，逐字节等值，D-A6 bridge 保真）；
-//   - conversation/idleTimeoutMs：interact 控制面的 task 标志，原名透传。
-//
-// 往返保真（验收 A1 的映射层证据）：executeOptionsToTaskSpec ∘ taskSpecToExecuteOptions
-// 对全部 ExecuteOptions 字段恒等（schemaEnv 由 schema 派生后逐字节等于原值——resolver
-// 与本 mapper 共用 WeakMap 缓存的同一 compact 串）。唯一归一化：appendSystemPrompt: []
-// 归一为 persona 缺省（下游 spread 空数组与 undefined 均为 no-op，行为等价）。
-
-import type { ModelInfo } from "../../../model-resolver.ts";
-import type { ExecuteOptions } from "../../../types.ts";
-import { stringifySchemaCached } from "../../../../shared/schema-jsonify.ts";
-import type { AgentTaskSpec, PersonaSpec } from "../../types.ts";
-
-/**
- * ExecuteOptions → AgentTaskSpec（宿主侧声明 → 引擎中立声明）。
- * 纯函数、无副作用——同一 opts 可重复转换（幂等）。
- */
-export function executeOptionsToTaskSpec(opts: ExecuteOptions): AgentTaskSpec {
-  // persona 归并：skillPath / appendSystemPrompt 有其一即建 persona，避免空对象噪声。
-  const persona: PersonaSpec | undefined =
-    opts.skillPath !== undefined || opts.appendSystemPrompt !== undefined
-      ? {
-          ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
-          ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
-        }
-      : undefined;
-  return {
-    task: opts.task,
-    slug: opts.slug,
-    agent: opts.agent,
-    model: opts.model,
-    // pi 7 档枚举 → 引擎无关 effort（恒等：档位集合是 pi 私有语义，中立层透传）
-    effort: opts.thinkingLevel,
-    ...(persona !== undefined ? { persona } : {}),
-    schema: opts.schema,
-    maxTurns: opts.maxTurns,
-    graceTurns: opts.graceTurns,
-    fork: opts.fork,
-    worktree: opts.worktree,
-    cwd: opts.cwd,
-    conversation: opts.conversation,
-    idleTimeoutMs: opts.idleTimeoutMs,
-    // ExecuteOptions 不携带的运行期字段（signal/ctxModel/onComplete）归 RunContext；
-    // schemaEnv 由 taskSpecToExecuteOptions 从 schema 派生。
-  };
-}
-
-/**
- * AgentTaskSpec → ExecuteOptions（pi 引擎侧还原）。
- *
- * @param spec 中立任务声明
- * @param runCtx 运行期上下文：ctxModel 是 ExecuteOptions 的运行期字段（从 RunContext
- *               回填）；schemaEnvFallback 是解耦形态（有 schemaEnv 无 schema，生产
- *               不可达）的兜底透传——schema 可派生时派生优先（逐字节等值）
- */
-export function taskSpecToExecuteOptions(
-  spec: AgentTaskSpec,
-  runCtx?: { ctxModel?: ModelInfo; schemaEnvFallback?: string },
-): ExecuteOptions {
-  return {
-    task: spec.task,
-    slug: spec.slug,
-    // 身份解析键：spec.agent 优先；persona.agentRef 是 persona 注入通道的定位符，
-    // 仅在 spec.agent 缺失时兜底（flag/file 通道引擎的主路径；pi 恒走 spec.agent）
-    agent: spec.agent ?? spec.persona?.agentRef,
-    model: spec.model,
-    // effort → pi thinkingLevel（恒等映射）
-    thinkingLevel: spec.effort,
-    // persona 还原：pi 的注入通道是 --skill / --append-system-prompt flag
-    skillPath: spec.persona?.skillPath,
-    appendSystemPrompt: spec.persona?.appendSystemPrompt,
-    schema: spec.schema,
-    // schemaEnv 内化派生（D-A6 bridge）：与 agent-opts-resolver 共用 stringifySchemaCached
-    // compact 缓存，输出逐字节等值。schema 缺失（无法派生）且调用方持有预编码值时兜底
-    // 透传（解耦形态，生产不可达）；无 schema 亦无兜底时不设（BC-6：childEnv 不注入）。
-    schemaEnv: spec.schema !== undefined
-      ? stringifySchemaCached(spec.schema, "compact")
-      : runCtx?.schemaEnvFallback,
-    maxTurns: spec.maxTurns,
-    graceTurns: spec.graceTurns,
-    ctxModel: runCtx?.ctxModel,
-    fork: spec.fork,
-    worktree: spec.worktree,
-    cwd: spec.cwd,
-    conversation: spec.conversation,
-    idleTimeoutMs: spec.idleTimeoutMs,
-    // signal 不入 opts（PiEngine 直接传给 executeAndAwait 第 2 参，与 SAR 现行为一致）；
-    // onComplete 不经引擎（workflow 路径从不设置；background 完成通知走 service 内部 notifier）。
-    // denyTools/permissionMode：中立新字段，pi 链路暂无对应面（P2 公共层接 denylist 映射）。
-  };
-}

package/src/execution/engine/engines/zcode/__tests__/__fixtures__/zcode-golden-spawn.json

@@ -1,39 +0,0 @@
-{
-  "_meta": {
-    "description": "zcode CLI spawn 单轮模式 golden 实录（2026-08-25 验收前置门）",
-    "engineVersion": "0.16.5",
-    "recordedAt": "2026-08-25T01:41:43Z",
-    "recordedOn": "macOS arm64, node v24.11.1",
-    "argv": [
-      "node",
-      "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
-      "--json",
-      "--cwd",
-      "<临时目录>",
-      "--mode",
-      "yolo",
-      "--prompt",
-      "Reply with the single word: ok"
-    ],
-    "envSummary": {
-      "HOME": "<隔离池目录>（config.json = model.main + 目标 provider 条目，无 plugins 块）",
-      "stdin": "/dev/null（stdio ignore——CLI 不读 stdin，否则挂起）",
-      "XYZ_AGENT_SUBAGENT": "实录未注入；引擎实现注入 =1"
-    },
-    "exitCode": 0,
-    "durationMs": 4914,
-    "fieldStructure": {
-      "sessionId": "string，sess_<uuid>",
-      "traceId": "string（诊断用）",
-      "turnId": "string，turn_<uuid>",
-      "response": "string——assistant 全文",
-      "usage": "object：source/modelRequestCount/inputTokens/outputTokens/totalTokens/cacheReadTokens/cacheWriteTokens/reasoningTokens/webFetchRequests/webSearchRequests",
-      "eventCount": "number",
-      "projection": "object：status/turnCount/totalTokenCount/contextUsed/contextWindow"
-    },
-    "usageMapping": "inputTokens→input、outputTokens→output、cacheReadTokens→cacheRead、cacheWriteTokens→cacheWrite；cost 无来源（cost 回传 ❌ 与调研一致）",
-    "credentialNote": "stdout 不含凭据；凭据只存在于池内 config.json（此处不收录）。隔离 HOME 的凭据源用 ~/.zcode/v2/config.json（桌面登录态）——本机 ~/.zcode/cli/config.json 的 router provider 指向局域网网关 192.168.1.202:9981，实录时不可达",
-    "sigtermTiming": "SIGTERM → exit 实测 103ms（exit code 143，stderr \"Turn was cancelled\"）；引擎杀链 grace 取 5000ms（zsub 同构，保守）"
-  },
-  "stdoutRaw": "{\n  \"sessionId\": \"sess_35852a0f-1302-4e20-9e48-87f47527abe3\",\n  \"traceId\": \"9fffaebd-749e-468b-af3f-2a89e3347785\",\n  \"turnId\": \"turn_99879260-1c9b-4e97-afe1-c2e7abeaf5b9\",\n  \"response\": \"ok\",\n  \"usage\": {\n    \"source\": \"provider\",\n    \"modelRequestCount\": 1,\n    \"inputTokens\": 12599,\n    \"outputTokens\": 17,\n    \"totalTokens\": 12616,\n    \"cacheReadTokens\": 512,\n    \"cacheWriteTokens\": 0,\n    \"reasoningTokens\": 0,\n    \"webFetchRequests\": 0,\n    \"webSearchRequests\": 0\n  },\n  \"eventCount\": 17,\n  \"projection\": {\n    \"status\": \"idle\",\n    \"turnCount\": 1,\n    \"totalTokenCount\": 12616,\n    \"contextUsed\": 12616,\n    \"contextWindow\": 1000000\n  }\n}\n"
-}