@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/orchestration/__tests__/worker-script-builder-runtime.test.ts

@@ -53,6 +53,12 @@ interface ErrorMsg {
   error: string;
   workerLogs?: unknown[];
 }
+/** log 消息：脚本 log() 全局发出的独立诊断消息（协议见 worker-script-builder 头注释）。 */
+interface LogMsg {
+  type: "log";
+  phase?: string;
+  message?: string;
+}
 
 // ── 类型守卫：从 unknown 收窄到判别联合 ──
 // 共享 hasType 辅助：避免每个守卫重复 `(m as {type?:string})` 断言（taste/no-unsafe-catch）。
@@ -74,16 +80,23 @@ function isReturn(m: unknown): m is ReturnMsg {
 function isError(m: unknown): m is ErrorMsg {
   return hasType(m, "error");
 }
+function isLog(m: unknown): m is LogMsg {
+  return hasType(m, "log");
+}
 
 // ── 测试辅助：起一个真实 Worker 跑 buildWorkerScript 产物 ──────────────
 
 interface RunResult {
   /** 收到的 return 消息的 result 字段（脚本正常结束时）。 */
   returnValue?: unknown;
+  /** return 消息带回的 workerLogs（[B-3] 起只含 console.* 捕获条目，log() 不再走此通路）。 */
+  returnWorkerLogs?: unknown[];
   /** 收到的 error 消息的 error 字段（脚本 throw 时）。 */
   errorMessage?: string;
   /** error 消息带回的 workerLogs（验证诊断不丢）。 */
   errorWorkerLogs?: unknown[];
+  /** 收到的 {type:"log"} 独立消息列表（[B-3] 起 log() 的唯一通路）。 */
+  logMessages: LogMsg[];
   /** Worker exit code（0=正常，1=崩溃）。 */
   exitCode?: number;
   /** Worker 'error' 事件的错误消息（uncaught exception，正常应为 undefined）。 */
@@ -94,6 +107,15 @@ interface RunResult {
   workflowCalls: WorkflowCallMsg[];
 }
 
+/** workerLogs 条目守卫收窄 + message 包含判定（元素类型 unknown，断言前先收窄）。 */
+function someLogMessageContains(logs: unknown[] | undefined, text: string): boolean {
+  return (logs ?? []).some((l) => {
+    if (typeof l !== "object" || l === null) return false;
+    const message = (l as { message?: unknown }).message;
+    return typeof message === "string" && message.includes(text);
+  });
+}
+
 interface RunOptions {
   /** $ARGS。 */
   args?: Record<string, unknown>;
@@ -144,7 +166,7 @@ function runWorker(userScript: string, opts: RunOptions = {}): Promise<RunResult
     // S8：创建后立即登记，afterEach 兜底清理（防止 promise 泄漏导致 Worker 未终止）
     createdWorkers.push(worker);
 
-    const result: RunResult = { agentCalls: [], workflowCalls: [] };
+    const result: RunResult = { agentCalls: [], workflowCalls: [], logMessages: [] };
     let agentCallIdx = 0;
     let resolved = false;
     const timer = setTimeout(() => {
@@ -181,8 +203,13 @@ function runWorker(userScript: string, opts: RunOptions = {}): Promise<RunResult
         result.workflowCalls.push(raw);
         const wfResult = opts.handleWorkflowCall ? opts.handleWorkflowCall(raw) : { ok: true };
         worker.postMessage({ type: "workflow-result", callId: raw.callId, result: wfResult });
+      } else if (isLog(raw)) {
+        // [OR-6/T7④] 独立 log 消息收集（主线程真实 runtime 当前无消费 case，测试
+        // harness 收集以断言「协议消息仍发出」通路不被回退）。
+        result.logMessages.push(raw);
       } else if (isReturn(raw)) {
         result.returnValue = raw.result;
+        result.returnWorkerLogs = raw.workerLogs;
         finish(result);
       } else if (isError(raw)) {
         result.errorMessage = raw.error;
@@ -382,6 +409,56 @@ describe("buildWorkerScript runtime — 之前缺失的路径覆盖", () => {
   });
 });
 
+// ── [B-3] log() 单通路可观测性 ─────────────────────────────────────
+// 旧双通路（log() 同时 post 独立消息 + 记入 _workerLogs 随 return/error 带回）让
+// 同一日志在主线程 errorLogs 占两格、TUI 双份。修复后 log() 只发独立 {type:"log"}
+// 消息，主线程 handleWorkerLog 即时消费（error-recovery.ts）；崩溃场景丢 log 条目
+// 可接受（log 是 T7 补充可观测）。
+
+describe("buildWorkerScript runtime — [B-3] log() 单通路", () => {
+  it("log() 发出独立 {type:\"log\"} 消息且携带 phase（主线程即时消费的唯一通路）", async () => {
+    const script = `
+      phase("build");
+      log("hello from script");
+      return { ok: true };
+    `;
+    const res = await runWorker(script);
+    expect(res.workerError).toBeUndefined();
+    expect(res.logMessages).toEqual([{ type: "log", phase: "build", message: "hello from script" }]);
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("log() 内容不再随 return 消息的 workerLogs 带回（双份入账已退役）", async () => {
+    const script = `
+      phase("build");
+      log("hello from script");
+      return { ok: true };
+    `;
+    const res = await runWorker(script);
+    expect(res.workerError).toBeUndefined();
+    // workerLogs 中不得出现 log() 的条目（否则主线程 log case + workerLogs 双份入账）
+    expect(someLogMessageContains(res.returnWorkerLogs, "hello from script")).toBe(false);
+  });
+
+  it("log() 内容不再随 error 消息的 workerLogs 带回（console.* 捕获通路不受影响）", async () => {
+    const script = `
+      log("before-crash");
+      console.error("crash-context");
+      throw new Error("boom");
+    `;
+    const res = await runWorker(script);
+    expect(res.errorMessage).toBe("boom");
+    // log() 的条目不在 error workerLogs（单通路）
+    expect(someLogMessageContains(res.errorWorkerLogs, "before-crash")).toBe(false);
+    // console.* 捕获通路保持（workerLogs 仍带回 console.error 条目）
+    expect(res.errorWorkerLogs).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ level: "error", message: "crash-context" }),
+      ]),
+    );
+  });
+});
+
 // ── W2: agent() returnMeta 模式运行时验证 ───────────────────────────
 // 现有 worker-script-builder.test.ts 的 16 条 returnMeta 断言全是字符串 toContain，
 // 无法验证「真实 Worker 线程执行时 agent({returnMeta:true}) resolve 出对象、

package/src/orchestration/__tests__/workflow-files.test.ts

@@ -0,0 +1,186 @@
+// src/orchestration/__tests__/workflow-files.test.ts
+//
+// C4-core-script-pipeline（convergence W4 / D-6）目录参数化测试：
+// - saveWorkflow/deleteWorkflow 注入非 .pi 目录：真实落盘 / rename 迁移 / 删除；
+// - 既有语义回归（文案逐字）：tmp 不存在拒、目标已存在拒、运行中拒、
+//   两候选路径均无拒；
+// - 缺省目录 = pi 布局（相对 cwd resolve，pi 现两参调用形态行为不变）。
+// 设计权威源：docs/design/subagent-core-convergence.md §3.2 D-6。
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { deleteWorkflow, saveWorkflow } from "../workflow-files.ts";
+
+/** 构造注入布局（非 .pi）：{root}/host-tmp + {root}/host-saved（saved 不预创建，
+ * 覆盖 saveWorkflow 内 mkdirSync recursive 自动建目录路径）。 */
+function makeHostLayout(): { root: string; tmpDir: string; savedDir: string } {
+  const root = mkdtempSync(join(tmpdir(), "subagent-core-wf-"));
+  const tmpDir = join(root, "host-tmp");
+  const savedDir = join(root, "host-saved");
+  mkdirSync(tmpDir, { recursive: true });
+  return { root, tmpDir, savedDir };
+}
+
+function seedTmp(tmpDir: string, name: string, body = "// tmp body"): void {
+  writeFileSync(join(tmpDir, `${name}.js`), body);
+}
+
+// ============================================================
+// saveWorkflow（目录注入）
+// ============================================================
+
+describe("saveWorkflow 目录注入（非 .pi 布局）", () => {
+  it("注入 tmpDir/savedDir：tmp 落盘 → rename 迁移，savedDir 自动创建", async () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "alpha", "// alpha body");
+      const msg = await saveWorkflow("alpha", undefined, { tmpDir, savedDir });
+      expect(msg).toBe(`Saved 'alpha' → 'alpha' (${join(savedDir, "alpha.js")})`);
+      // rename 语义：tmp 文件保存后消失
+      expect(existsSync(join(tmpDir, "alpha.js"))).toBe(false);
+      expect(readFileSync(join(savedDir, "alpha.js"), "utf-8")).toBe("// alpha body");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("newName 改名：tmp/alpha.js → saved/beta.js", async () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "alpha", "// renamed body");
+      const msg = await saveWorkflow("alpha", "beta", { tmpDir, savedDir });
+      expect(msg).toBe(`Saved 'alpha' → 'beta' (${join(savedDir, "beta.js")})`);
+      expect(existsSync(join(savedDir, "alpha.js"))).toBe(false);
+      expect(existsSync(join(savedDir, "beta.js"))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("目标已存在 → 拒（文案逐字）", async () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "alpha");
+      mkdirSync(savedDir, { recursive: true });
+      writeFileSync(join(savedDir, "beta.js"), "// existing");
+      await expect(saveWorkflow("alpha", "beta", { tmpDir, savedDir })).rejects.toThrow(
+        "'beta' already exists in saved workflows. Use a different name.",
+      );
+      // 原文件不动
+      expect(existsSync(join(tmpDir, "alpha.js"))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("tmp 不存在 → 拒（文案逐字）", async () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      await expect(saveWorkflow("ghost", undefined, { tmpDir, savedDir })).rejects.toThrow(
+        "Temporary workflow 'ghost' not found",
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+// ============================================================
+// deleteWorkflow（目录注入）
+// ============================================================
+
+describe("deleteWorkflow 目录注入（非 .pi 布局）", () => {
+  it("注入目录：tmp 候选优先删除", () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "dup", "// tmp copy");
+      mkdirSync(savedDir, { recursive: true });
+      writeFileSync(join(savedDir, "dup.js"), "// saved copy");
+      const msg = deleteWorkflow("dup", () => false, { tmpDir, savedDir });
+      expect(msg).toBe(`Deleted workflow 'dup' (${join(tmpDir, "dup.js")})`);
+      expect(existsSync(join(tmpDir, "dup.js"))).toBe(false);
+      expect(existsSync(join(savedDir, "dup.js"))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("注入目录：tmp 无 → saved 候选删除", () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      mkdirSync(savedDir, { recursive: true });
+      writeFileSync(join(savedDir, "gamma.js"), "// saved body");
+      const msg = deleteWorkflow("gamma", () => false, { tmpDir, savedDir });
+      expect(msg).toBe(`Deleted workflow 'gamma' (${join(savedDir, "gamma.js")})`);
+      expect(existsSync(join(savedDir, "gamma.js"))).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("运行中 → 拒（文案逐字，防删运行中脚本）", () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "busy");
+      expect(() =>
+        deleteWorkflow("busy", (name) => name === "busy", { tmpDir, savedDir }),
+      ).toThrow("Cannot delete 'busy': workflow is currently running. Abort it first.");
+      expect(existsSync(join(tmpDir, "busy.js"))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("两候选均无 → 拒（文案逐字）", () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      expect(() => deleteWorkflow("void", () => false, { tmpDir, savedDir })).toThrow(
+        "Workflow file 'void' not found",
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+// ============================================================
+// 缺省目录（pi 布局回归——向后兼容：pi 现两参调用形态行为不变）
+// ============================================================
+
+describe("缺省目录 = pi 布局（向后兼容回归）", () => {
+  it("save 缺省：<cwd>/.pi/workflows/.tmp → <cwd>/.pi/workflows", async () => {
+    const fakeCwd = mkdtempSync(join(tmpdir(), "subagent-core-cwd-"));
+    const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(fakeCwd);
+    try {
+      const tmpDir = join(fakeCwd, ".pi", "workflows", ".tmp");
+      mkdirSync(tmpDir, { recursive: true });
+      seedTmp(tmpDir, "pi-wf", "// pi layout");
+      const msg = await saveWorkflow("pi-wf");
+      expect(msg).toBe(`Saved 'pi-wf' → 'pi-wf' (${join(fakeCwd, ".pi", "workflows", "pi-wf.js")})`);
+      expect(existsSync(join(tmpDir, "pi-wf.js"))).toBe(false);
+      expect(existsSync(join(fakeCwd, ".pi", "workflows", "pi-wf.js"))).toBe(true);
+    } finally {
+      cwdSpy.mockRestore();
+      rmSync(fakeCwd, { recursive: true, force: true });
+    }
+  });
+
+  it("delete 缺省：两候选 = .pi/workflows/.tmp 与 .pi/workflows", () => {
+    const fakeCwd = mkdtempSync(join(tmpdir(), "subagent-core-cwd-"));
+    const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(fakeCwd);
+    try {
+      const savedDir = join(fakeCwd, ".pi", "workflows");
+      mkdirSync(savedDir, { recursive: true });
+      writeFileSync(join(savedDir, "saved-only.js"), "// body");
+      const msg = deleteWorkflow("saved-only", () => false);
+      expect(msg).toBe(`Deleted workflow 'saved-only' (${join(savedDir, "saved-only.js")})`);
+      expect(existsSync(join(savedDir, "saved-only.js"))).toBe(false);
+    } finally {
+      cwdSpy.mockRestore();
+      rmSync(fakeCwd, { recursive: true, force: true });
+    }
+  });
+});

package/src/orchestration/__tests__/workflow-run-summary.test.ts

@@ -0,0 +1,119 @@
+// workflow-run-summary.test.ts —— runSummary 投影 + isScriptRunning 判定测试（U7/B5/D8）。
+//
+// 覆盖（验收条款③）：
+// - runSummary：字段投影全断言（running / done 两形态；slug/error/completedAt 缺省透传）
+// - isScriptRunning：真（同名 running）/ 假（同名 done、异名 running、空 Map）两分支
+import { describe, expect, it } from "vitest";
+
+import { isScriptRunning, runSummary } from "../workflow-run-summary.ts";
+import { Budget } from "../models/budget.ts";
+import type { RunSpec } from "../models/run-spec.ts";
+import { Trace } from "../models/trace.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+
+function makeSpec(scriptName: string, slug?: string): RunSpec {
+  return {
+    scriptSource: "execute() {}",
+    args: {},
+    scriptName,
+    ...(slug !== undefined ? { slug } : {}),
+    scriptPath: "/fake/test.js",
+  };
+}
+
+function makeRun(
+  runId: string,
+  opts: {
+    status?: "running" | "done";
+    scriptName?: string;
+    slug?: string;
+    reason?: "completed" | "failed" | "aborted" | "time_limited";
+    error?: string;
+    startedAt?: string;
+    completedAt?: string;
+  } = {},
+): WorkflowRun {
+  const status = opts.status ?? "running";
+  return WorkflowRun.reconstruct(
+    runId,
+    makeSpec(opts.scriptName ?? "deploy-site", opts.slug),
+    {
+      status,
+      ...(status === "done" ? { reason: opts.reason ?? "completed" } : {}),
+      budget: new Budget({ maxTokens: 1000 }),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+      ...(opts.error !== undefined ? { error: opts.error } : {}),
+    },
+    {
+      startedAt: opts.startedAt ?? "2026-08-30T00:00:00.000Z",
+      ...(opts.completedAt !== undefined ? { completedAt: opts.completedAt } : {}),
+    },
+  );
+}
+
+describe("runSummary — 字段投影（字段以 core WorkflowRun 为准）", () => {
+  it("running run：name=scriptName、slug、status、startedAt 投影；completedAt/reason 为 undefined", () => {
+    const run = makeRun("wf-r1", { status: "running", scriptName: "deploy-site", slug: "deploy" });
+
+    expect(runSummary(run)).toEqual({
+      runId: "wf-r1",
+      name: "deploy-site",
+      slug: "deploy",
+      status: "running",
+      reason: undefined,
+      startedAt: "2026-08-30T00:00:00.000Z",
+      completedAt: undefined,
+      error: undefined,
+    });
+  });
+
+  it("done run：reason/completedAt/error 投影（对齐 pi toRunSummary 字段集）", () => {
+    const run = makeRun("wf-d1", {
+      status: "done",
+      reason: "failed",
+      error: "agent timeout",
+      startedAt: "2026-08-30T10:00:00.000Z",
+      completedAt: "2026-08-30T10:05:00.000Z",
+    });
+
+    expect(runSummary(run)).toEqual({
+      runId: "wf-d1",
+      name: "deploy-site",
+      slug: undefined,
+      status: "done",
+      reason: "failed",
+      startedAt: "2026-08-30T10:00:00.000Z",
+      completedAt: "2026-08-30T10:05:00.000Z",
+      error: "agent timeout",
+    });
+  });
+});
+
+describe("isScriptRunning — 真假两分支", () => {
+  it("真：同名 script 仍在 running", () => {
+    const runs = new Map<string, WorkflowRun>([
+      ["wf-1", makeRun("wf-1", { status: "done", scriptName: "other-wf" })],
+      ["wf-2", makeRun("wf-2", { status: "running", scriptName: "deploy-site" })],
+    ]);
+
+    expect(isScriptRunning(runs, "deploy-site")).toBe(true);
+  });
+
+  it("假：同名但已 done（running 状态白名单）", () => {
+    const runs = new Map<string, WorkflowRun>([
+      ["wf-1", makeRun("wf-1", { status: "done", scriptName: "deploy-site" })],
+    ]);
+
+    expect(isScriptRunning(runs, "deploy-site")).toBe(false);
+  });
+
+  it("假：异名 running / 空 Map", () => {
+    const runs = new Map<string, WorkflowRun>([
+      ["wf-1", makeRun("wf-1", { status: "running", scriptName: "other-wf" })],
+    ]);
+    expect(isScriptRunning(runs, "deploy-site")).toBe(false);
+    expect(isScriptRunning(new Map(), "deploy-site")).toBe(false);
+  });
+});

package/src/orchestration/__tests__/workflow-script-registry-impl.test.ts

@@ -0,0 +1,124 @@
+/**
+ * workflow-script-registry-impl 测试：sink 设计 U1 导出形态。
+ *
+ * 覆盖：WorkflowScript 类 re-export 可用性 + loadWorkflowScriptByPath 工厂加载
+ * （真实临时脚本文件）、非法引用拒绝（含 ⛔2 `..` 段收紧对工厂生效）、
+ * available=false stub 语义。
+ *
+ * 策略对齐 config-loader.test.ts：真实临时目录 + 真实脚本文件（meta 提取走真实
+ * 文件读取），只 mock findWorkspaceRoot（缓存桶 key，耦合 process.cwd 难隔离）与
+ * homedir（`~/` 引用展开锚点）。
+ */
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return { ...actual, homedir: vi.fn(() => "/nonexistent-home-for-tests") };
+});
+
+vi.mock("../../shared/resource-discovery.ts", async (importOriginal) => {
+  const actual = await importOriginal<
+    typeof import("../../shared/resource-discovery.ts")
+  >();
+  return {
+    ...actual,
+    findWorkspaceRoot: vi.fn(() => "/unused-by-default"),
+  };
+});
+
+import { invalidateCache } from "../config-loader.ts";
+import { loadWorkflowScriptByPath, WorkflowScript } from "../workflow-script-registry-impl.ts";
+import { homedir } from "node:os";
+
+const mockedHomedir = vi.mocked(homedir);
+
+/** 有效 workflow 脚本内容（@pi-meta 块注释 + agent 入口，同 config-loader.test 范式；phases 须 YAML 数组）。 */
+const SCRIPT_SOURCE =
+  "/* @pi-meta\nname: factory-wf\ndescription: factory test\nphases: []\n*/\nagent({ prompt: \"x\" });\n";
+
+async function writeScript(content: string, fileName = "factory-wf.js"): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "wf-registry-impl-test-"));
+  const p = join(dir, fileName);
+  await writeFile(p, content, "utf-8");
+  return p;
+}
+
+describe("loadWorkflowScriptByPath / WorkflowScript 导出形态（U1）", () => {
+  let tempDirs: string[] = [];
+
+  beforeEach(() => {
+    invalidateCache();
+    // 重置 `~/` 用例留下的 homedir mock 残留（mockReturnValue 跨测试持续）
+    mockedHomedir.mockReturnValue("/nonexistent-home-for-tests");
+    tempDirs = [];
+  });
+
+  afterEach(async () => {
+    invalidateCache();
+    for (const dir of tempDirs) {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  async function trackedWrite(content: string, fileName?: string): Promise<string> {
+    const p = await writeScript(content, fileName);
+    tempDirs.push(join(p, ".."));
+    return p;
+  }
+
+  it("按绝对路径加载：返回 WorkflowScript 实例（meta/sourceCode 填充，available=true）", async () => {
+    const p = await trackedWrite(SCRIPT_SOURCE);
+    const script = await loadWorkflowScriptByPath(p);
+    expect(script).toBeInstanceOf(WorkflowScript);
+    expect(script!.name).toBe("factory-wf");
+    expect(script!.available).toBe(true);
+    expect(script!.path).toBe(p);
+    expect(script!.sourceCode).toBe(SCRIPT_SOURCE);
+    expect(script!.meta.description).toBe("factory test");
+  });
+
+  it("re-export 的 WorkflowScript 类与实例同源：validate/toExecutable 实体操作可用", async () => {
+    const p = await trackedWrite(SCRIPT_SOURCE);
+    const script = await loadWorkflowScriptByPath(p);
+    expect(script).toBeInstanceOf(WorkflowScript);
+    // 实体操作（validate 委托 lintScript / toExecutable 返回可执行源）经导出类实例可用
+    const lint = script!.validate();
+    expect(lint.valid).toBe(true);
+    expect(Array.isArray(lint.findings)).toBe(true);
+    expect(script!.toExecutable()).toBe(SCRIPT_SOURCE);
+  });
+
+  it("文件不可读/不存在：available=false 的 stub（非 undefined——loader never throws）", async () => {
+    const p = await trackedWrite(SCRIPT_SOURCE, "gone.js");
+    await rm(p);
+    const script = await loadWorkflowScriptByPath(p);
+    expect(script).toBeDefined();
+    expect(script!.available).toBe(false);
+  });
+
+  it("非法引用返回 undefined：相对路径 / 非 .js 扩展名", async () => {
+    await trackedWrite(SCRIPT_SOURCE);
+    expect(await loadWorkflowScriptByPath("relative/wf.js")).toBeUndefined();
+    expect(await loadWorkflowScriptByPath("/proj/wf.txt")).toBeUndefined();
+  });
+
+  it("⛔2：含 .. 段的路径引用被拒（undefined——收紧对工厂消费面生效）", async () => {
+    await trackedWrite(SCRIPT_SOURCE);
+    expect(await loadWorkflowScriptByPath("/x/../factory-wf.js")).toBeUndefined();
+  });
+
+  it("~/ 前缀引用：展开 homedir 后加载（barrel 消费面的合法引用形态）", async () => {
+    const fakeHome = await mkdtemp(join(tmpdir(), "wf-registry-impl-home-"));
+    tempDirs.push(fakeHome);
+    mockedHomedir.mockReturnValue(fakeHome);
+    const p = join(fakeHome, "home-wf.js");
+    await writeFile(p, SCRIPT_SOURCE, "utf-8");
+    const script = await loadWorkflowScriptByPath("~/home-wf.js");
+    expect(script).toBeInstanceOf(WorkflowScript);
+    expect(script!.name).toBe("factory-wf");
+    expect(script!.path).toBe(p);
+  });
+});

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

@@ -145,7 +145,7 @@ export function formatSchemaInstruction(schema: Record<string, unknown>): string
 export function resolveAgentOpts(opts: AgentCallOpts): ResolveResult {
   const appendSystemPrompt: string[] = [];
 
- // Resolve skill name to SKILL.md path
+  // Resolve skill name to SKILL.md path
   if (opts.skill) {
     const skillPath = resolveSkillPath(opts.skill);
     if (!skillPath) {
@@ -154,17 +154,17 @@ export function resolveAgentOpts(opts: AgentCallOpts): ResolveResult {
     opts = { ...opts, skillPath };
   }
 
- // Inject schema as structured-output instruction into appendSystemPrompt (content,
- // not temp file) and set environment variable for conditional tool + hook activation.
- // M2 fix: previously wrote the instruction to a temp file and pushed the FILE PATH,
- // 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.
+  // Inject schema as structured-output instruction into appendSystemPrompt (content,
+  // not temp file) and set environment variable for conditional tool + hook activation.
+  // M2 fix: previously wrote the instruction to a temp file and pushed the FILE PATH,
+  // 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) {
     // IF7(#13)：formatSchemaInstruction 与 schemaEnv 对同一 schema 对象引用共享
     // WeakMap 缓存条目（compact stringify 整个 dispatch 只发生一次）
     appendSystemPrompt.push(formatSchemaInstruction(opts.schema));
 
- // Set env var for structured-output extension to activate tool + hook
+    // Set env var for structured-output extension to activate tool + hook
     opts = { ...opts, schemaEnv: stringifySchemaCached(opts.schema, "compact") };
   }