@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/orchestration/__tests__/skill-discovery.test.ts

@@ -0,0 +1,157 @@
+/**
+ * skill-discovery — resolveSkillPath 结果缓存（IF8/#14）+ 搜索序测试。
+ *
+ * 现状该文件此前零测试，本文件为首个测试（design IF8 契约）：
+ * - hit 不再 existsSync（计数 wrapper 观察，spyOn ESM namespace 不可配置的既有教训）
+ * - 未命中 undefined 也缓存（不存在的名字二次调用零 stat）
+ * - clearSkillPathCache 后重扫
+ * - project 优先于 user/npm 的搜索序
+ *
+ * [merge 注] main 侧同名文件（mock-fs 版）的 5 用例语义均已覆盖：搜索序三用例
+ * 同名等价；「npm 候选路径构造含 agentDir」= 本文件各用例断言 join(homeRoot,
+ * ".pi/agent/npm/...") 完整路径 + npm 兜底用例的多包枚举；「全 miss undefined 含
+ * readdirSync ENOENT 兜底」= 「未命中 undefined 也缓存」用例（homeRoot 无 npm 目录，
+ * 真实 fs 下 ENOENT 由实现 catch）。mock 版被本集成版取代。
+ *
+ * 隔离：node:fs 的 existsSync 用 vi.mock 包一层计数（委托真实实现）；
+ * getAgentDir 用 vi.mock 覆盖为临时 home（vitest alias 指向 mocks/pi-coding-agent.ts
+ * 的硬编码桩 "/home/user/.pi/agent"，桩不读 os.homedir——mock node:os 无法影响它）；
+ * process.cwd 用 spyOn。
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const { existsSyncCalls, osHome } = vi.hoisted(() => ({
+  existsSyncCalls: { count: 0 },
+  osHome: { dir: "/nonexistent-home-skill-tests" },
+}));
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  const realExistsSync = actual.existsSync;
+  // 计数 wrapper（委托真实实现）——vi.spyOn(fs, "existsSync") 在 ESM 模块
+  // 命名空间不可配置（record-store-index.test.ts:419 同款教训），改用 mock 工厂。
+  const countingExistsSync = ((p: string) => {
+    existsSyncCalls.count++;
+    return realExistsSync(p);
+  }) as typeof actual.existsSync;
+  return { ...actual, existsSync: countingExistsSync };
+});
+
+vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@earendil-works/pi-coding-agent")>();
+  const { join } = await import("node:path");
+  // 桩不读 os.homedir，必须在此把 agentDir 指向 hoisted 临时 home（beforeEach 注入 homeRoot）
+  return { ...actual, getAgentDir: () => join(osHome.dir, ".pi", "agent") };
+});
+
+import { clearSkillPathCache, resolveSkillPath } from "../skill-discovery.ts";
+
+// ── 临时目录工具 ──────────────────────────────────────────────
+
+let projRoot: string;
+let homeRoot: string;
+
+beforeEach(() => {
+  clearSkillPathCache();
+  existsSyncCalls.count = 0;
+  projRoot = mkdtempSync(join(tmpdir(), "skill-proj-"));
+  homeRoot = mkdtempSync(join(tmpdir(), "skill-home-"));
+  osHome.dir = homeRoot;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  rmSync(projRoot, { recursive: true, force: true });
+  rmSync(homeRoot, { recursive: true, force: true });
+});
+
+/** mkdir -p（目录存在即 resolveSkillPath 命中——检查的是目录而非 SKILL.md）。 */
+function mkdirp(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+describe("resolveSkillPath — 搜索序（project > user > npm）", () => {
+  it("project 优先：同名 skill 同时存在于 project/user/npm 时返回 project 路径", () => {
+    const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "dup-skill";
+    mkdirp(join(projRoot, ".agents/skills", name));
+    mkdirp(join(homeRoot, ".pi/agent/skills", name));
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/some-pkg/skills", name));
+
+    const resolved = resolveSkillPath(name);
+
+    expect(resolved).toBe(join(projRoot, ".agents/skills", name));
+    expect(cwdSpy).toHaveBeenCalled();
+  });
+
+  it("user 次之：仅 user/npm 存在时返回 user 路径", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "user-skill";
+    mkdirp(join(homeRoot, ".pi/agent/skills", name));
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/some-pkg/skills", name));
+
+    expect(resolveSkillPath(name)).toBe(join(homeRoot, ".pi/agent/skills", name));
+  });
+
+  it("npm 兜底：仅 npm 包内存在时返回包内 skills 路径（readdirSync 枚举多包候选）", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "npm-skill";
+    // 两个包并存：断言实现枚举 npm/node_modules 下每个包（S-6 语义，防只查首个包的回退）
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/pkg-a/other", "x"));
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/some-pkg/skills", name));
+
+    expect(resolveSkillPath(name)).toBe(
+      join(homeRoot, ".pi/agent/npm/node_modules/some-pkg/skills", name),
+    );
+  });
+});
+
+describe("resolveSkillPath — 结果缓存（IF8/DM3）", () => {
+  it("hit 不再 existsSync：二次调用零 stat", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "cache-hit";
+    const expected = join(projRoot, ".agents/skills", name);
+    mkdirp(expected);
+
+    const first = resolveSkillPath(name);
+    const callsAfterFirst = existsSyncCalls.count;
+    expect(first).toBe(expected);
+    expect(callsAfterFirst).toBeGreaterThan(0);
+
+    const second = resolveSkillPath(name);
+    expect(second).toBe(expected);
+    expect(existsSyncCalls.count).toBe(callsAfterFirst); // 零增量
+  });
+
+  it("未命中 undefined 也缓存：不存在的名字二次调用零 stat", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "no-such-skill-xyz";
+
+    const first = resolveSkillPath(name);
+    expect(first).toBeUndefined();
+    const callsAfterFirst = existsSyncCalls.count;
+    expect(callsAfterFirst).toBeGreaterThan(0);
+
+    const second = resolveSkillPath(name);
+    expect(second).toBeUndefined();
+    expect(existsSyncCalls.count).toBe(callsAfterFirst); // 零增量（未命中也缓存）
+  });
+
+  it("clearSkillPathCache 后重扫：计数恢复增长且结果一致", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "cache-clear";
+    const expected = join(projRoot, ".agents/skills", name);
+    mkdirp(expected);
+
+    expect(resolveSkillPath(name)).toBe(expected);
+    const callsAfterFirst = existsSyncCalls.count;
+    expect(callsAfterFirst).toBeGreaterThan(0);
+
+    clearSkillPathCache();
+    expect(resolveSkillPath(name)).toBe(expected);
+    expect(existsSyncCalls.count).toBeGreaterThan(callsAfterFirst); // 重扫发生
+  });
+});

package/src/orchestration/__tests__/test-mocks.ts

@@ -0,0 +1,191 @@
+// src/orchestration/__tests__/test-mocks.ts
+//
+// Pi ExtensionAPI / ExtensionContext 测试 mock 工厂（PR #173 review S8）。
+//
+// 为什么需要工厂：此前测试用 `as never` 注入残缺 mock（如 `{ appendEntry: vi.fn() }`
+// 直接塞进 `JsonlRunStoreOptions.pi`）。`as never` 是 bottom type 断言，mock 缺字段时
+// 编译期零报错，比 `as unknown as T` 更危险。工厂返回**类型完整**的对象——被 mock
+// 接口（真实 SDK 类型，tsc 按根 tsconfig 排除规则不检查 __tests__，但编辑器 LSP 与
+// 显式 tsc 文件级检查会检查）新增成员时，这里补默认值即暴露，用例侧不再有断言后门。
+//
+// 语义约定：
+// - 默认值贴近真实行为：sessionManager.getEntries 返回浅拷贝（真实 SessionManager
+//   契约）；appendEntry 捕获变体追加完整 CustomEntry（真实 pi.appendEntry 即向 session
+//   追加 CustomEntry）；isIdle → true、hasPendingMessages → false 等按真实语义取值。
+// - 测试真正消费的成员（jsonl-run-store 只读 ctx.sessionManager.getEntries 与
+//   pi.appendEntry）行为真实；其余成员为 no-op spy（vi.fn()），调用不炸但返回
+//   undefined——本包测试不消费它们。
+// - modelRegistry / ui.theme 是含 private 字段的 nominal class：真实构造需
+//   ModelRuntime.create()（async + 读用户级 models.json）/ loadTheme 读包文件，且
+//   vitest 把 @earendil-works/pi-coding-agent alias 到 mocks/（无这些值导出），结构
+//   构造又被 private 字段阻断。二者经 fail-loud Proxy 提供：误用时立即抛错（而非
+//   静默 undefined），把「缺 mock」变成显式失败。这是本文件仅有的两处断言收敛点。
+
+import { vi } from "vitest";
+
+import type {
+  CustomEntry,
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionUIContext,
+  ModelRegistry,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+
+/** 误用即抛错的占位成员：比静默返回 undefined 的 no-op 更早暴露「缺 mock」。 */
+function failLoud<T>(memberPath: string): T {
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        throw new Error(
+          `[test-mocks] ${memberPath}.${String(prop)} 未提供 mock 实现——` +
+            `本测试不应消费该成员；确需消费时经 overrides 显式提供`,
+        );
+      },
+    },
+  ) as unknown as T;
+}
+
+/**
+ * 构造类型完整的 ExtensionContext。
+ *
+ * @param entries sessionManager.getEntries 的返回源（浅拷贝返回）。与 mkPi(entries)
+ *   共享同一数组时可复现真实 pi 行为：appendEntry 写入 ↔ getEntries 读出。
+ * @param overrides 覆写任意 ctx 字段（浅合并，整体替换成员，最后应用）。
+ */
+export function mkCtx(
+  entries: CustomEntry[] = [],
+  overrides: Partial<ExtensionContext> = {},
+): ExtensionContext {
+  const ctx: ExtensionContext = {
+    ui: mkUi(),
+    // pi 在 xyz-agent 下以 rpc 子进程模式运行；rpc 模式 hasUI 为 true（SDK 契约注释）
+    mode: "rpc",
+    hasUI: true,
+    cwd: "/tmp",
+    sessionManager: {
+      getCwd: () => "/tmp",
+      getSessionDir: () => "/tmp/sessions-test",
+      getSessionId: () => "session-test",
+      // 真实语义：首条 assistant 消息前 session 文件未落盘，返回 undefined
+      getSessionFile: () => undefined,
+      getLeafId: () => null,
+      getLeafEntry: () => undefined,
+      getEntry: () => undefined,
+      getLabel: () => undefined,
+      getBranch: () => [],
+      buildContextEntries: () => [],
+      getHeader: () => null,
+      // 真实 SessionManager.getEntries 返回浅拷贝
+      getEntries: () => [...entries],
+      getTree: () => [],
+      getSessionName: () => undefined,
+    },
+    modelRegistry: failLoud<ModelRegistry>("ctx.modelRegistry"),
+    // SDK 契约：model / signal 在 agent 未流式输出时合法为 undefined
+    model: undefined,
+    isIdle: vi.fn(() => true),
+    isProjectTrusted: vi.fn(() => true),
+    signal: undefined,
+    abort: vi.fn(),
+    hasPendingMessages: vi.fn(() => false),
+    shutdown: vi.fn(),
+    getContextUsage: vi.fn(() => undefined),
+    compact: vi.fn(),
+    getSystemPrompt: vi.fn(() => ""),
+  };
+  return Object.assign(ctx, overrides);
+}
+
+/** ExtensionUIContext 完整 no-op mock（theme 为 fail-loud 占位，见文件头说明）。 */
+function mkUi(): ExtensionUIContext {
+  return {
+    select: vi.fn(async () => undefined),
+    confirm: vi.fn(async () => false),
+    input: vi.fn(async () => undefined),
+    notify: vi.fn(),
+    onTerminalInput: vi.fn(() => () => {}),
+    setStatus: vi.fn(),
+    setWorkingMessage: vi.fn(),
+    setWorkingVisible: vi.fn(),
+    setWorkingIndicator: vi.fn(),
+    setHiddenThinkingLabel: vi.fn(),
+    setWidget: vi.fn(),
+    setFooter: vi.fn(),
+    setHeader: vi.fn(),
+    setTitle: vi.fn(),
+    custom: vi.fn(),
+    pasteToEditor: vi.fn(),
+    setEditorText: vi.fn(),
+    getEditorText: vi.fn(() => ""),
+    editor: vi.fn(async () => undefined),
+    addAutocompleteProvider: vi.fn(),
+    setEditorComponent: vi.fn(),
+    getEditorComponent: vi.fn(() => undefined),
+    theme: failLoud<Theme>("ctx.ui.theme"),
+    getAllThemes: vi.fn(() => []),
+    getTheme: vi.fn(() => undefined),
+    setTheme: vi.fn(() => ({ success: true })),
+    getToolsExpanded: vi.fn(() => false),
+    setToolsExpanded: vi.fn(),
+  };
+}
+
+/**
+ * 构造类型完整的 ExtensionAPI。
+ *
+ * @param entries 给定时，appendEntry 追加完整 CustomEntry 到该数组（真实
+ *   pi.appendEntry 语义：向 session 追加 custom entry）；缺省为纯 spy（可断言
+ *   调用次数、无副作用）。
+ * @param overrides 覆写任意 pi 字段（浅合并，最后应用）。
+ */
+export function mkPi(
+  entries?: CustomEntry[],
+  overrides: Partial<ExtensionAPI> = {},
+): ExtensionAPI {
+  const appendEntry =
+    entries === undefined
+      ? vi.fn()
+      : vi.fn((customType: string, data?: unknown) => {
+          entries.push({
+            type: "custom",
+            customType,
+            data,
+            id: `entry-${entries.length}`,
+            parentId: null,
+            timestamp: new Date().toISOString(),
+          });
+        });
+  const pi: ExtensionAPI = {
+    on: vi.fn(),
+    registerTool: vi.fn(),
+    registerCommand: vi.fn(),
+    registerShortcut: vi.fn(),
+    registerFlag: vi.fn(),
+    getFlag: vi.fn(() => undefined),
+    registerMessageRenderer: vi.fn(),
+    registerEntryRenderer: vi.fn(),
+    sendMessage: vi.fn(),
+    sendUserMessage: vi.fn(),
+    appendEntry,
+    setSessionName: vi.fn(),
+    getSessionName: vi.fn(() => undefined),
+    setLabel: vi.fn(),
+    exec: vi.fn(),
+    getActiveTools: vi.fn(() => []),
+    getAllTools: vi.fn(() => []),
+    setActiveTools: vi.fn(),
+    getCommands: vi.fn(() => []),
+    setModel: vi.fn(async () => true),
+    getThinkingLevel: vi.fn(),
+    setThinkingLevel: vi.fn(),
+    registerProvider: vi.fn(),
+    unregisterProvider: vi.fn(),
+    events: {
+      emit: vi.fn(),
+      on: vi.fn(() => () => {}),
+    },
+  };
+  return Object.assign(pi, overrides);
+}

package/src/orchestration/__tests__/worker-script-template-snapshot.test.ts

@@ -0,0 +1,98 @@
+/**
+ * buildWorkerScript 模板 hoisting（IF5/IF6）— byte-identical 快照锚定。
+ *
+ * ES8：快照先行——fixture 由「改造前实现」生成落盘（本文件同 commit），
+ * 断言重构后输出与 fixture 逐字节一致，锁定 PRE/POST 边界换行与 userScript
+ * 缩进语义（AC-4「逐字保留」不变式）。IF6（_KNOWN_FIELDS 提升至生成源
+ * module scope）落地时基线已按设计在同一 commit 内更新为最终形态。
+ *
+ * 样例脚本覆盖 $ARGS / schema / parallel / pipeline / workflow / phase / log 特性。
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { buildWorkerScript } from "../worker-script-builder.ts";
+
+const sampleScript = [
+  "// sample exercising template features",
+  'const name = $ARGS.name ?? "default";',
+  'phase("build");',
+  'const spec = await agent("build it", { label: "builder", schema: { type: "object" } });',
+  "const results = await parallel([",
+  '  agent({ task: "unit tests", agent: "./tester.md" }),',
+  '  agent({ task: "lint", agent: "./linter.md", skill: "lint-skill" }),',
+  "]);",
+  "await pipeline([(x) => x, (x) => x]);",
+  'await workflow("deploy", { env: "prod" });',
+  'log("done " + name + " " + $WORKSPACE + " " + $BUDGET.remaining());',
+  "module.exports = { execute: async (ctx) => ctx.agent(\"finalize\") };",
+].join("\n");
+
+function loadFixture(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return readFileSync(join(here, "__fixtures__", "worker-template.snapshot.txt"), "utf8");
+}
+
+describe("buildWorkerScript — 模板 hoisting byte-identical 快照（IF5）", () => {
+  it("特性全量样例的输出与 fixture 逐字节一致", () => {
+    const out = buildWorkerScript(sampleScript);
+    expect(out).toBe(loadFixture());
+  });
+
+  it("首尾边界锚定：use strict 开头 + error handler 结尾 + userScript 缩进注入", () => {
+    const out = buildWorkerScript(sampleScript);
+    // PRE 边界：第一行 use strict（无前导换行）
+    expect(out.startsWith('"use strict";\n')).toBe(true);
+    // userScript 段：两空格缩进注入（AC-4 拼接语义）
+    expect(out).toContain("\n  // sample exercising template features\n");
+    // userScript 段结束后一个空行再接 auto-invoke 段（POST 首部换行语义）
+    expect(out).toContain("ctx.agent(\"finalize\") };\n\n  // ── Auto-invoke execute() for module.exports pattern ──");
+    // POST 边界：以 error handler 的 "});" 结尾（无尾随换行）
+    expect(out.endsWith('_safePost({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs }, "error");\n});')).toBe(true);
+  });
+
+  it("空 userScript 与任意脚本的拼接语义稳定（PRE/POST 不含 userScript 状态）", () => {
+    const a = buildWorkerScript("x");
+    const b = buildWorkerScript("y");
+    // 除 userScript 段外完全一致：以 userScript 行为界切割比对
+    const [preA] = a.split("\n  x\n");
+    const [preB] = b.split("\n  y\n");
+    expect(preA).toBe(preB);
+  });
+});
+
+describe("buildWorkerScript — _KNOWN_FIELDS module scope 提升（IF6）", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  it("生成源含 module 级 _KNOWN_FIELDS 声明（与 _workerLogs 同级，IIFE 外）", () => {
+    // 声明在 IIFE 开始之前（module scope）：const _KNOWN_FIELDS 必须出现在 "(async () => {" 前
+    const iifePos = script.indexOf("(async () => {");
+    const knownPos = script.indexOf("const _KNOWN_FIELDS = new Set([");
+    expect(knownPos).toBeGreaterThan(-1);
+    expect(knownPos).toBeLessThan(iifePos);
+    // 紧随 _workerLogs 声明之后（design IF6：与 _workerLogs/:62 同级）
+    expect(script.indexOf("const _workerLogs = [];")).toBeLessThan(knownPos);
+  });
+
+  it("agent() 体内不再重建 Set（引用 _KNOWN_FIELDS，无 new Set）", () => {
+    // agent() 函数体（到 parallel 声明前）内不得有 new Set 构造
+    const agentPos = script.indexOf("async function agent(firstArg, secondArg)");
+    const parallelPos = script.indexOf("async function parallel(calls)");
+    expect(agentPos).toBeGreaterThan(-1);
+    expect(parallelPos).toBeGreaterThan(agentPos);
+    const agentBody = script.slice(agentPos, parallelPos);
+    expect(agentBody).not.toContain("new Set(");
+    expect(agentBody).toContain("_KNOWN_FIELDS.has(k)");
+  });
+
+  it("字段集合内容逐字段一致（16 known fields 不丢失）", () => {
+    expect(script).toContain(
+      'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
+    );
+    // unknown-fields 警告文案不变（known 列表仍全量）
+    expect(script).toMatch(/Known fields:.*returnMeta.*thinkingLevel/);
+  });
+});

package/src/orchestration/__tests__/workflow-nesting-e2e.test.ts

@@ -21,8 +21,6 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 vi.mock("../lifecycle.ts", () => ({
   runWorkflow: vi.fn(),
   abortRun: vi.fn(async () => {}),
-  pauseRun: vi.fn(async () => {}),
-  resumeRun: vi.fn(async () => {}),
   scheduleTimeBudget: vi.fn(() => undefined),
 }));
 

package/src/orchestration/__tests__/workflow-script-lint-memo.test.ts

@@ -0,0 +1,110 @@
+/**
+ * WorkflowScript.validate lint memo（IF9/#15，TC9/DM2）— 引用相等键缓存测试。
+ *
+ * vi.mock script-lint 模块统计 lintScript 调用次数（design IF9 测试面）：
+ * - 同 path + sourceCode 相等（含等值异字面量）→ 二次 validate 只 1 次 lint 调用
+ * - 【设计修正】design 原文「异引用等值 miss」在 JS 不可构造：字符串 === 是值相等
+ *   （实测等值异字面量命中）。lintScript 是纯函数，值相等 ⟹ 结果相同，值键 memo
+ *   语义严格正确且是引用键意图的超集（registry 等值重建实例同样命中）。
+ * - 同 path 新内容（值不等）→ 重 lint 并更新条目
+ * - clearLintMemo → 重 lint（config-loader.invalidateCache 挂载点）
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const lintCalls = vi.hoisted(() => ({ count: 0 }));
+
+vi.mock("../script-lint.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../script-lint.ts")>();
+  const realLintScript = actual.lintScript;
+  const countingLintScript = ((source: string) => {
+    lintCalls.count++;
+    return realLintScript(source);
+  }) as typeof actual.lintScript;
+  return { ...actual, lintScript: countingLintScript };
+});
+
+import { WorkflowScript, clearLintMemo, type WorkflowMeta } from "../models/workflow-script.ts";
+
+const meta: WorkflowMeta = {
+  kind: "workflow",
+  name: "w",
+  description: "",
+  phases: [],
+};
+
+function makeScript(path: string, sourceCode: string): WorkflowScript {
+  return new WorkflowScript({
+    name: "w",
+    source: "saved",
+    path,
+    sourceCode,
+    meta,
+    available: true,
+  });
+}
+
+const VALID = '/* @pi-meta name: w */\nagent({ prompt: "x" });\n';
+
+beforeEach(() => {
+  clearLintMemo();
+  lintCalls.count = 0;
+});
+
+describe("WorkflowScript.validate — lintMemo（IF9）", () => {
+  it("同 sourceCode 引用：二次 validate 只 1 次 lint 调用", () => {
+    const src = VALID;
+    const a = makeScript("/ws/.pi/workflows/w.js", src);
+    const b = makeScript("/ws/.pi/workflows/w.js", src); // registry 重建实例场景
+
+    const ra = a.validate();
+    const rb = b.validate();
+
+    expect(lintCalls.count).toBe(1);
+    expect(rb).toEqual(ra); // 缓存返回同一 lint 结果
+  });
+
+  it("等值异字面量同样命中（JS === 值相等；lintScript 纯函数 ⟹ 值键 memo 正确）", () => {
+    const a = makeScript("/ws/.pi/workflows/w.js", VALID);
+    const b = makeScript("/ws/.pi/workflows/w.js", `/* @pi-meta name: w */\nagent({ prompt: "x" });\n`);
+
+    a.validate();
+    b.validate();
+
+    // 设计原文预期「异引用 miss → 2 次」，但字符串 === 是值相等，等值必命中；
+    // lintScript(source) 纯函数，同值同结果，缓存正确性不受影响（实测锚定）。
+    expect(lintCalls.count).toBe(1);
+  });
+
+  it("同 path 新内容（值不等）：重 lint 并更新条目", () => {
+    const path = "/ws/.pi/workflows/w.js";
+    const old = makeScript(path, VALID);
+    old.validate();
+    expect(lintCalls.count).toBe(1);
+
+    const edited = makeScript(path, '/* @pi-meta name: w */\nagent({ prompt: "y", outputSchema: {} });\n');
+    edited.validate();
+    expect(lintCalls.count).toBe(2); // 新引用 → miss → 重 lint
+
+    // 新条目已覆写：再以 edited 同引用 validate 命中缓存
+    const replay = makeScript(path, edited.sourceCode);
+    replay.validate();
+    expect(lintCalls.count).toBe(2);
+  });
+
+  it("clearLintMemo 后重 lint（invalidateCache 挂载点）", () => {
+    const a = makeScript("/ws/.pi/workflows/w.js", VALID);
+    a.validate();
+    expect(lintCalls.count).toBe(1);
+
+    clearLintMemo();
+    a.validate();
+    expect(lintCalls.count).toBe(2);
+  });
+
+  it("不同 path 互不共享条目", () => {
+    const src = VALID;
+    makeScript("/ws/.pi/workflows/a.js", src).validate();
+    makeScript("/ws/.pi/workflows/b.js", src).validate();
+    expect(lintCalls.count).toBe(2);
+  });
+});

package/src/orchestration/__tests__/workflows-e2e.test.ts

@@ -279,7 +279,7 @@ interface ScriptOutcome {
 /**
  * 断言 runAndWait 返回成功完成的终态。
  *
- * - result.status === "done"（runAndWait 恒 done）
+ * - result.status === "closed"（runAndWait 恒 done）
  * - result.reason === "completed"（脚本正常 return，非 failed/aborted/time_limited）
  * - result.scriptResult.status 是 "ok" 或 "partial"（脚本层 outcome，非 "error"）
  * - result.error 为 undefined

package/src/orchestration/agent-opts-resolver.ts

@@ -21,6 +21,7 @@
 
 import type { AgentCallOpts } from "./models/types.ts";
 import { resolveSkillPath } from "./skill-discovery.ts";
+import { stringifySchemaCached } from "../shared/schema-jsonify.ts";
 
 export interface ResolveResult {
   opts: AgentCallOpts;
@@ -59,7 +60,9 @@ export function resolveAgentOpts(opts: AgentCallOpts): ResolveResult {
  // which got concatenated into the final append file as path garbage — the SO instruction
  // never reached the subprocess. Now the instruction content is pushed directly.
   if (opts.schema) {
-    const schemaJson = JSON.stringify(opts.schema);
+    // IF7(#13)：同 schema 对象引用的 compact stringify 走 WeakMap 缓存
+    // （与 session-runner formatSchemaInstruction 的 pretty 版共享缓存条目）
+    const schemaJson = stringifySchemaCached(opts.schema, "compact");
     const content = [
       "## MANDATORY: Structured Output Requirement",
       "",

package/src/orchestration/args-validator.ts

@@ -62,8 +62,8 @@ function formatMessage(name: string, errors: readonly unknown[]): string {
  * 校验 spec.parameters（JSON Schema draft-07）对 spec.args 的约束。
  *
  * - spec.parameters === undefined → 跳过（安全退化：漏拷 parameters 退化是「不校验」非「校验错」）
- * - coerceTypes 原地规范化 spec.args（worker 启动 + pause/resume 重建共用同一对象，
- *   run.spec === spec，保证恢复路径参数一致）
+ * - coerceTypes 原地规范化 spec.args（worker 启动 + 崩溃重建重跑共用同一对象，
+ *   run.spec === spec，保证重跑路径参数一致）
  * - 失败 throw ArgsValidationError（非原始 ajv 错误）
  *
  * @throws ArgsValidationError 参数不合法或 schema 无效

package/src/orchestration/config-loader.ts

@@ -16,6 +16,7 @@ import { resolve } from "node:path";
 
 // WorkflowMeta 规范来源是 shared/resource-meta.ts（m1 DM1）；WorkflowSource 来自 workflow-script
 import type { WorkflowSource } from "./models/workflow-script.ts";
+import { clearLintMemo } from "./models/workflow-script.ts";
 import type { WorkflowMeta } from "../shared/resource-meta.ts";
 import { getCachedFile, getCachedFileContent, clearFileCache } from "../shared/resource-discovery.ts";
 import { parseResourceMeta } from "../shared/meta-parser.ts";
@@ -93,6 +94,20 @@ function toWorkflowSource(source: ResourceSource): WorkflowSource {
   return source === "project-pi-tmp" ? "tmp" : "saved";
 }
 
+/**
+ * 按路径推导 ResourceSource（IF4/外部 #5 残留）。
+ *
+ * getWorkflowByPath 可加载任意绝对路径（不限扫描源），此前硬编码 "user-pi"
+ * 使 workspaceRoot/.pi/workflows/.tmp/ 下的临时脚本按路径加载被错标 saved
+ * （discoverWorkflows 对同文件正确标 tmp，两路径不一致）。修正：路径落在
+ * tmp 目录前缀内 → "project-pi-tmp"，其余 → "user-pi"（非 tmp 路径输出不变，DS4）。
+ */
+function deriveResourceSource(filePath: string, workspaceRoot: string): ResourceSource {
+  const tmpDir = resolve(workspaceRoot, ".pi/workflows/.tmp");
+  const normalized = resolve(filePath);
+  return normalized === tmpDir || normalized.startsWith(`${tmpDir}/`) ? "project-pi-tmp" : "user-pi";
+}
+
 // ── 单文件 → CachedWorkflowMeta（IF1 parseResourceMeta + 整对象透传）──
 
 /**
@@ -264,11 +279,23 @@ export async function getWorkflow(name: string): Promise<CachedWorkflowMeta | un
  * - ~/ 前缀展开；相对路径/非 .js 引用返回 undefined（引用唯一形态 = 绝对路径）
  * - 任意路径（不限扫描源）：内置包内脚本、用户任意位置脚本均可执行
  * - meta 提取失败/文件不可读 → available=false（fail-safe，不抛）
+ * - [perf] 与 getWorkflow(name) 对称走 bucket 缓存（key=绝对路径，与 stem 名不冲突），
+ *   消除 workflow tool 主路径每次 run 的全文 regex + YAML.parse（mtime 判变失效）
  */
 export async function getWorkflowByPath(ref: string): Promise<CachedWorkflowMeta | undefined> {
   const filePath = normalizeRef(ref, WORKFLOW_REF_EXT);
   if (filePath === null) return undefined;
-  return toCachedMeta(filePath, "user-pi");
+  const workspaceRoot = findWorkspaceRoot();
+  const bucket = getCacheBucket(workspaceRoot);
+  const cached = bucket.get(filePath);
+  if (cached && isCacheValid(cached)) {
+    return cached.meta;
+  }
+  // IF4：source 按路径推导——.tmp 前缀 → project-pi-tmp（→ "tmp"），其余 user-pi 维持现值
+  const meta = await toCachedMeta(filePath, deriveResourceSource(filePath, workspaceRoot));
+  const file = getCachedFile(filePath);
+  if (file) bucket.set(filePath, { meta, mtimeMs: file.mtimeMs });
+  return meta;
 }
 
 /**
@@ -277,6 +304,8 @@ export async function getWorkflowByPath(ref: string): Promise<CachedWorkflowMeta
  */
 export function invalidateCache(): void {
   // m5：清统一 mtime 缓存层 + bucket（测试隔离 + mtime 漏判场景手动刷新兜底）
+  // IF9：连带清 workflow-script validate 的 lint memo（同源文件缓存，测试隔离统一走它）
   clearFileCache();
   cache.clear();
+  clearLintMemo();
 }