@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/orchestration/script-generate.ts

@@ -0,0 +1,154 @@
+/**
+ * Workflow 脚本创作管线（generate）——pi-sw tool-workflow-script.ts actionGenerate
+ * 的校验管线下沉（convergence D-6 / W4）。
+ *
+ * 五道闸 + round-trip + tmp 写盘，闸序与 pi 现版一致：
+ * 1. ESM import 拒绝（Worker 跑 CJS）；'export const meta' 例外
+ * 2. 非 meta 的 export 拒绝
+ * 3. meta 声明必需（@pi-meta YAML 块注释或 legacy const meta，过渡期 m0）
+ * 4. agent() 调用必需
+ * 5. 语法检查（包 async IIFE，与 runtime 包裹形态一致）
+ * 6. round-trip：@pi-meta 存在时 parseResourceMetaDetailed 校验 YAML（报行列）
+ * 7. 通过全部校验 → tmp 目录写盘
+ *
+ * 与 pi 版的差异（均为宿主职责，不属纯函数边界）：
+ * - 不含 signal aborted 检查（AbortSignal 是 pi tool 契约层关注，宿主改接时自留）；
+ * - 返回结构化结果而非 throw——pi 只对 execute throw 置 isError:true 的契约
+ *   转换由宿主（C5 改接）负责，core 保持纯函数。
+ *
+ * 报错文案逐字平移自 pi 现版（含 round-trip 的 line/col 信息）——pi 侧行为
+ * 不变是 CA2 验收前提，任何文案改动必须同步两处。
+ *
+ * tmp 目录经 options.tmpDir 宿主注入（缺省 pi 布局，与 workflow-files.ts
+ * 同源常量——save/delete/generate 三入口共享同一目录参数化口径）。
+ *
+ * 层归属：orchestration（创作闭环，与 lintScript / workflow-files 同域）。
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { parseResourceMetaDetailed } from "../shared/meta-parser.ts";
+import { DEFAULT_WORKFLOW_TMP_DIR } from "./workflow-files.ts";
+
+/** generate 目录注入参数：tmp 落盘目录宿主注入（缺省 DEFAULT_WORKFLOW_TMP_DIR）。 */
+export interface GenerateWorkflowScriptOptions {
+  tmpDir?: string;
+}
+
+/**
+ * 管线结果：成功 = 落盘绝对路径；失败 = 报错文案（逐字对齐 pi 现版，
+ * 含 round-trip 的行列信息——供宿主转 throw 后 LLM 自纠正）。
+ */
+export type GenerateWorkflowScriptResult =
+  | { ok: true; path: string }
+  | { ok: false; error: string };
+
+// ── 校验闸（每闸返回 error 文案；undefined = 通过。文案逐字对齐 pi 现版） ──
+
+/** 闸 0：参数完备（缺 name/script 即拒）。 */
+function checkRequiredParams(name: string, script: string): string | undefined {
+  if (!name || !script) {
+    return "generate requires 'name' and 'script' parameters";
+  }
+  return undefined;
+}
+
+/** 闸 1：ESM 语法拒绝（Worker 跑 CJS）；'export const meta' 例外。stripped = 注释剥离后源码。 */
+function checkEsamSyntax(stripped: string): string | undefined {
+  if (/\bimport\s+(?:type\s+)?[\w{*]/.test(stripped)) {
+    return "Script uses ESM 'import' syntax. Workflow scripts run in a CJS Worker — use require() instead.";
+  }
+  const hasExportMeta = /\bexport\s+const\s+meta\s*=/.test(stripped);
+  const otherExports = stripped.match(/\bexport\s+(?:const|let|var|function|default|\{)/g);
+  if (otherExports && !hasExportMeta) {
+    return "Script uses ESM 'export' (non-meta). Use 'const meta = {...}' at top level instead.";
+  }
+  return undefined;
+}
+
+// 闸 2：meta 声明必需（/* @pi-meta */ YAML 块注释或 legacy const meta，过渡期 m0）
+function checkMetaDeclaration(script: string, hasPiMeta: boolean): string | undefined {
+  const hasLegacyMeta = script.includes("const meta") || script.includes("export const meta");
+  if (!hasPiMeta && !hasLegacyMeta) {
+    return "Script must contain a meta declaration: a /* @pi-meta */ YAML block comment (preferred) or legacy const meta = { ... }. The block has the form: a block comment starting with /* @pi-meta followed by YAML (name/description/phases/parameters?/usage?), closed by */ on its own line.";
+  }
+  return undefined;
+}
+
+/** 闸 3：agent() 调用必需。 */
+function checkAgentUsage(stripped: string): string | undefined {
+  if (!/\bagent\s*\(/.test(stripped)) {
+    return "Script does not contain any agent() calls. A workflow must call agent() at least once.";
+  }
+  return undefined;
+}
+
+/** 闸 4：语法检查（包 async IIFE，与 runtime 包裹形态一致）。 */
+function checkSyntax(script: string): string | undefined {
+  const cjsScript = script.replace(/\bexport\s+const\s+meta\b/, "const meta");
+  try {
+    new Function(`(async () => { ${cjsScript} })();`);
+    return undefined;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `Syntax error in script: ${msg}`;
+  }
+}
+
+/** 闸 4b：round-trip——@pi-meta 存在时 parseResourceMetaDetailed 校验 YAML（报行列）。 */
+function checkMetaRoundTrip(script: string, hasPiMeta: boolean): string | undefined {
+  if (!hasPiMeta) return undefined;
+  const detailed = parseResourceMetaDetailed(script, "workflow");
+  if (detailed.ok) return undefined;
+  const loc = "linePos" in detailed && detailed.linePos
+    ? ` (line ${detailed.linePos.line}, col ${detailed.linePos.col})`
+    : "";
+  return `Generated /* @pi-meta */ YAML cannot be parsed${loc}: ${detailed.error}. Common causes: YAML indent errors, patternProperties regex must use double backslash (\\d not \d), or a stray star-slash inside the YAML body. Fix the meta block and retry.`;
+}
+
+/**
+ * 校验并落盘一个 AI 生成的 workflow 临时脚本。
+ *
+ * @param name 脚本名（落盘 <tmpDir>/{name}.js）
+ * @param script 完整脚本源码
+ * @param options 目录注入（tmpDir 缺省 pi 布局，相对 cwd resolve）
+ */
+export function generateWorkflowScript(
+  name: string,
+  script: string,
+  options?: GenerateWorkflowScriptOptions,
+): GenerateWorkflowScriptResult {
+  const paramError = checkRequiredParams(name, script);
+  if (paramError) return { ok: false, error: paramError };
+
+  // 1. Reject ESM syntax (Worker runs CJS); 'export const meta' 例外
+  const stripped = script.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+  const esamError = checkEsamSyntax(stripped);
+  if (esamError) return { ok: false, error: esamError };
+
+  // 2. Validate meta declaration (/* @pi-meta */ new format preferred; legacy const meta accepted during transition — m0)
+  const hasPiMeta = /\/\*\s*@pi-meta\s*\n/.test(script);
+  const metaError = checkMetaDeclaration(script, hasPiMeta);
+  if (metaError) return { ok: false, error: metaError };
+
+  // 3. Check agent usage
+  const agentError = checkAgentUsage(stripped);
+  if (agentError) return { ok: false, error: agentError };
+
+  // 4. Syntax check (wrap in async IIFE like runtime)
+  const syntaxError = checkSyntax(script);
+  if (syntaxError) return { ok: false, error: syntaxError };
+
+  // 4b. Round-trip: validate /* @pi-meta */ YAML before writing (v5 §4.7 / ERR4 — report linePos, don't write bad files)
+  const roundTripError = checkMetaRoundTrip(script, hasPiMeta);
+  if (roundTripError) return { ok: false, error: roundTripError };
+
+  // 5. Write to tmp directory
+  const tmpDir = resolve(options?.tmpDir ?? DEFAULT_WORKFLOW_TMP_DIR);
+  mkdirSync(tmpDir, { recursive: true });
+  const filePath = resolve(tmpDir, `${name}.js`);
+  writeFileSync(filePath, script, "utf-8");
+
+  return { ok: true, path: filePath };
+}

package/src/orchestration/script-lint.ts

@@ -76,13 +76,13 @@ function checkEntryPoint(source: string): LintFinding[] {
 function checkLine(lineText: string, lineNum: number): LintFinding[] {
   const results: LintFinding[] = [];
 
- // 跳过注释行
+  // 跳过注释行
   const trimmed = lineText.trim();
   if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
     return results;
   }
 
- // result.output / result.parsedOutput / result.content
+  // result.output / result.parsedOutput / result.content
   const resultAccessPatterns: Array<{ regex: RegExp; field: string }> = [
     { regex: /\bresult\s*\.\s*output\b/, field: "output" },
     { regex: /\bresult\s*\.\s*parsedOutput\b/, field: "parsedOutput" },
@@ -99,7 +99,7 @@ function checkLine(lineText: string, lineNum: number): LintFinding[] {
     }
   }
 
- // 文件传状态（readFileSync of STATE）
+  // 文件传状态（readFileSync of STATE）
   if (/readFileSync\(.*STATE.*\)|readFileSync\(.*state.*\.json/i.test(lineText)) {
     results.push({
       severity: "warning",
@@ -109,7 +109,7 @@ function checkLine(lineText: string, lineNum: number): LintFinding[] {
     });
   }
 
- // unlinkSync 清理状态
+  // unlinkSync 清理状态
   if (/unlinkSync.*state/i.test(lineText)) {
     results.push({
       severity: "warning",
@@ -169,7 +169,7 @@ function forEachAgentCallRange(
     const line = lines[i];
     const trimmed = line.trim();
 
- // 跳过注释
+    // 跳过注释
     if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
       continue;
     }
@@ -177,12 +177,12 @@ function forEachAgentCallRange(
     // 匹配/计括号都用剔除字符串与注释后的行，避免字面量内容干扰
     const codeLine = stripStringsAndComments(line);
 
- // 检测 agent 调用开始
+    // 检测 agent 调用开始
     if (!inAgentCall && /\bagent\s*\(/.test(codeLine)) {
       inAgentCall = true;
       depth = 0;
       agentStartLine = i;
- // 从 agent( 开始计括号
+      // 从 agent( 开始计括号
       const afterAgent = codeLine.replace(/^.*?\bagent\s*\(/, "(");
       // 非字面量实参（agent(callVar) / agent(expr)）→ 跳过（见函数头注释）。
       // 形如 `agent(` 换行 `{` 的多行字面量调用（argTail 为空）保留原追踪行为。
@@ -196,7 +196,7 @@ function forEachAgentCallRange(
         if (ch === ")" || ch === "}" || ch === "]") depth--;
       }
       if (depth <= 0) {
- // 单行 agent 调用
+        // 单行 agent 调用
         callback(agentStartLine, i);
         inAgentCall = false;
       }
@@ -247,15 +247,15 @@ function checkAgentCallOptions(
   for (let i = startLine; i <= endLine; i++) {
     const line = lines[i];
 
- // 跳过变量声明（const/let/var outputSchema = ...）
+    // 跳过变量声明（const/let/var outputSchema = ...）
     if (/\b(?:const|let|var)\s+outputSchema\b/.test(line)) {
       continue;
     }
 
- // 匹配：outputSchema 作为对象 key（简写或显式）
+    // 匹配：outputSchema 作为对象 key（简写或显式）
     if (/\boutputSchema\s*[,\}]/.test(line) || /\boutputSchema\s*:/.test(line)) {
- // 排除：outputSchema 作为 value（在另一个 key 的冒号后）
- // e.g. "schema: outputSchema," — outputSchema 前是冒号
+      // 排除：outputSchema 作为 value（在另一个 key 的冒号后）
+      // e.g. "schema: outputSchema," — outputSchema 前是冒号
       const beforeOutput = line.substring(0, line.indexOf("outputSchema"));
       if (/:\s*$/.test(beforeOutput)) {
         continue; // outputSchema 是 value，不是 key
@@ -329,7 +329,7 @@ function checkAgentDescription(source: string): LintFinding[] {
     // 对象以展开开头（agent({ ...call, ... })）：description 来自运行时对象、调用点静态
     // 不可见——无法验证即不报（review-fix-loop 的 agent({ ...call, agent: ... }) 即此形态）。
     if (/\{\s*\.\.\./.test(range)) return;
- // 匹配 description 或 label 作为对象 key（后跟冒号）
+    // 匹配 description 或 label 作为对象 key（后跟冒号）
     if (!/\b(description|label)\s*:/.test(range)) {
       findings.push({
         severity: "warning",
@@ -416,7 +416,7 @@ function isIIFEAwaited(source: string, iifeStart: number): boolean {
 function checkBareAsyncIIFE(source: string): LintFinding[] {
   if (!ENTRY_POINT_PATTERNS.some((p) => p.test(source))) return [];
 
- // 用 matchAll 检查所有 IIFE（脚本可能有多个，每个都需独立判断）
+  // 用 matchAll 检查所有 IIFE（脚本可能有多个，每个都需独立判断）
   const findings: LintFinding[] = [];
   for (const match of source.matchAll(BARE_ASYNC_IIFE_PATTERN)) {
     const iifeStart = match.index ?? 0;
@@ -519,13 +519,13 @@ function checkMetaPhases(source: string): LintFinding[] {
 function checkPhaseConsistency(source: string): LintFinding[] {
   const findings: LintFinding[] = [];
 
- // 提取 meta.phases 声明的字符串 + 声明所在行号
+  // 提取 meta.phases 声明的字符串 + 声明所在行号
   const declared = new Map<string, number>();
   const phasesArrayMatch = source.match(/phases\s*:\s*\[[^\]]*\]/);
   if (phasesArrayMatch && phasesArrayMatch.index !== undefined) {
     const inner = phasesArrayMatch[0];
- // 对象数组（如 [{title,detail}]）由 checkMetaPhases 单独报，这里跳过提取，
- // 避免从对象字段里误抽出字符串作 declared。
+    // 对象数组（如 [{title,detail}]）由 checkMetaPhases 单独报，这里跳过提取，
+    // 避免从对象字段里误抽出字符串作 declared。
     if (!/\[\s*\{/.test(inner)) {
       const phasesLine = source.slice(0, phasesArrayMatch.index).split("\n").length;
       for (const m of inner.matchAll(/['"]([^'"]+)['"]/g)) {
@@ -534,7 +534,7 @@ function checkPhaseConsistency(source: string): LintFinding[] {
     }
   }
 
- // 提取所有 phase() 调用实参 + 首次出现的行号
+  // 提取所有 phase() 调用实参 + 首次出现的行号
   const called = new Map<string, number>();
   for (const m of source.matchAll(/\bphase\s*\(\s*['"]([^'"]+)['"]/g)) {
     if (m.index === undefined) continue;
@@ -542,10 +542,10 @@ function checkPhaseConsistency(source: string): LintFinding[] {
     if (!called.has(m[1])) called.set(m[1], lineNum);
   }
 
- // 两者都为空 → 跳过（脚本不使用 phase 机制）
+  // 两者都为空 → 跳过（脚本不使用 phase 机制）
   if (declared.size === 0 && called.size === 0) return [];
 
- // 声明了但从未 phase() 调用
+  // 声明了但从未 phase() 调用
   for (const [name, line] of declared) {
     if (!called.has(name)) {
       findings.push({
@@ -557,7 +557,7 @@ function checkPhaseConsistency(source: string): LintFinding[] {
     }
   }
 
- // 调用了但未声明
+  // 调用了但未声明
   for (const [name, line] of called) {
     if (!declared.has(name)) {
       findings.push({
@@ -724,10 +724,10 @@ export function lintScript(source: string): LintResult {
   const lines = source.split("\n");
   const findings: LintFinding[] = [];
 
- // 入口检查（必须有 agent/parallel/pipeline 之一）
+  // 入口检查（必须有 agent/parallel/pipeline 之一）
   findings.push(...checkEntryPoint(source));
 
- // 逐行检查（result.output、文件传状态等）
+  // 逐行检查（result.output、文件传状态等）
   for (let i = 0; i < lines.length; i++) {
     findings.push(...checkLine(lines[i], i + 1));
   }
@@ -735,23 +735,23 @@ export function lintScript(source: string): LintResult {
   // agent 调用上下文检查（outputSchema 作为 key）
   findings.push(...checkAgentCalls(source));
 
- // [HISTORICAL] 顶层未 await 的异步 IIFE + 内部调 agent——子进程被提前 kill。
- // 教训来源：daily-news-impact.js 用 (async function main(){...})();() 包裹整个脚本，
- // worker 外层 IIFE 不等内层 IIFE 就 postMessage("return")，主线程 transition done
- // → release runtime → controller.abort() → spawn 后 2ms SIGKILL 子进程。
- // 诊断耗时 4 轮：先后误判为 model 故障 / 工具缺失 / turn-signal abort / 并发门闩 gate 异常，
- // 最终靠 worker-host → handleReturn → release → abort 的调用栈定位。
+  // [HISTORICAL] 顶层未 await 的异步 IIFE + 内部调 agent——子进程被提前 kill。
+  // 教训来源：daily-news-impact.js 用 (async function main(){...})();() 包裹整个脚本，
+  // worker 外层 IIFE 不等内层 IIFE 就 postMessage("return")，主线程 transition done
+  // → release runtime → controller.abort() → spawn 后 2ms SIGKILL 子进程。
+  // 诊断耗时 4 轮：先后误判为 model 故障 / 工具缺失 / turn-signal abort / 并发门闩 gate 异常，
+  // 最终靠 worker-host → handleReturn → release → abort 的调用栈定位。
   findings.push(...checkBareAsyncIIFE(source));
 
- // m4 W1-W3：meta 质量（description/when/notFor 短单句 + 不含已声明参数名）。
- // 仅对 IF1 解析成功的 @pi-meta 执行——旧 const meta 格式（D1 无 adapter）不检查。
+  // m4 W1-W3：meta 质量（description/when/notFor 短单句 + 不含已声明参数名）。
+  // 仅对 IF1 解析成功的 @pi-meta 执行——旧 const meta 格式（D1 无 adapter）不检查。
   const meta = parseResourceMeta(source, "workflow");
   if (meta && meta.kind === "workflow") {
     findings.push(...checkMetaQuality(meta));
   }
 
- // 显示性检查（warning）：agent 缺 description / meta.phases 形式 / phase 一致性。
- // 目的：让 TUI /workflows 视图避免 unnamed agent 与 (unnamed) phase 分组。
+  // 显示性检查（warning）：agent 缺 description / meta.phases 形式 / phase 一致性。
+  // 目的：让 TUI /workflows 视图避免 unnamed agent 与 (unnamed) phase 分组。
   findings.push(...checkAgentDescription(source));
   findings.push(...checkMetaPhases(source));
   findings.push(...checkPhaseConsistency(source));

package/src/orchestration/worker-handle.ts

@@ -29,7 +29,7 @@ export type WorkerExitHandler = (code: number) => void;
 
 export class WorkerHandle {
   private readonly worker: Worker;
- /**
+  /**
  * 竞态守卫。true = 此 handle 仍是当前活动 handle；false = 已 terminate，
  * 后续事件（已终止 worker 延迟触发的 message/error/exit）必须忽略。
  *
@@ -42,17 +42,17 @@ export class WorkerHandle {
     this.worker = worker;
   }
 
- /** 此 handle 是否仍是当前活动 handle（terminate 后 false，G-025）。 */
+  /** 此 handle 是否仍是当前活动 handle（terminate 后 false，G-025）。 */
   get isCurrent(): boolean {
     return this.current;
   }
 
- /** 底层 Worker（WorkerHost/RunRuntime 偶尔需要直接访问，如 ref/href）。 */
+  /** 底层 Worker（WorkerHost/RunRuntime 偶尔需要直接访问，如 ref/href）。 */
   get raw(): Worker {
     return this.worker;
   }
 
- /**
+  /**
  * 向 worker 发送消息。terminate 后 no-op（已终止 handle 的 postMessage 无意义）。
  */
   postMessage(msg: unknown): void {
@@ -60,7 +60,7 @@ export class WorkerHandle {
     this.worker.postMessage(msg);
   }
 
- /**
+  /**
  * 终止 worker 线程。幂等——重复调用安全，第二次起 no-op。
  * 置 isCurrent=false 后再 await worker.terminate，确保并发 exit 事件
  * 在 terminate resolve 之前到达时也被守卫拦下。
@@ -71,13 +71,13 @@ export class WorkerHandle {
     try {
       await this.worker.terminate();
     } catch (err) {
- // terminate 失败不阻断（worker 可能已退出）。current 已 false，安全。
- // 不向上抛——调用方（RunRuntime.release）不应被底层线程错误打断。
+      // terminate 失败不阻断（worker 可能已退出）。current 已 false，安全。
+      // 不向上抛——调用方（RunRuntime.release）不应被底层线程错误打断。
       void err;
     }
   }
 
- /**
+  /**
  * 绑定 message 回调。仅当 isCurrent 时触发——已终止 handle 的事件被吞掉。
  * 返回 this 便于链式 onMessage(...).onError(...).onExit(...)。
  */
@@ -89,7 +89,7 @@ export class WorkerHandle {
     return this;
   }
 
- /**
+  /**
  * 绑定 error 回调。仅当 isCurrent 时触发。
  */
   onError(handler: WorkerErrorHandler): this {
@@ -100,7 +100,7 @@ export class WorkerHandle {
     return this;
   }
 
- /**
+  /**
  * 绑定 exit 回调。仅当 isCurrent 时触发——这是 G-025 的关键守卫：
  * terminate(old) → startWorker(new) → old exit 触发时，old handle.current
  * 已为 false，回调 no-op，不会误删 new worker。

package/src/orchestration/worker-host.ts

@@ -28,7 +28,7 @@ import { buildWorkerScript } from "./worker-script-builder.ts";
 // ── WorkerHostImpl ───────────────────────────────────────────
 
 export class WorkerHostImpl implements WorkerHost {
- /**
+  /**
  * 启动一个 Worker thread 运行 workflow 脚本。
  *
  * 1. 用 buildWorkerScript(spec.scriptSource) 包装用户脚本（注入 agent/parallel/
@@ -59,9 +59,9 @@ export class WorkerHostImpl implements WorkerHost {
           name: spec.scriptName,
           description: spec.description,
         },
- // D-12 regression fix (round-2 #1)：注入 budget，否则 worker 内 $BUDGET.total 恒为 0。
- // 旧 agent-call-handler.ts 删除时同时丢失了 budget 注入和 budget-update 发送方，
- // 导致依赖 $BUDGET 做动态预算分支的脚本静默得到全 0。
+        // D-12 regression fix (round-2 #1)：注入 budget，否则 worker 内 $BUDGET.total 恒为 0。
+        // 旧 agent-call-handler.ts 删除时同时丢失了 budget 注入和 budget-update 发送方，
+        // 导致依赖 $BUDGET 做动态预算分支的脚本静默得到全 0。
         budget: {
           maxTokens: spec.budgetTokens,
           usedTokens: 0,
@@ -77,9 +77,9 @@ export class WorkerHostImpl implements WorkerHost {
 
     const handle = new WorkerHandle(worker);
 
- // 绑定事件——WorkerHandle 内部用 isCurrent 守卫，terminate 后回调 no-op（G-025）。
- // handlers 的 onMessage/onError/onExit 都是 async，这里 void 掉 promise（worker 事件
- // 不能 await，且 handler 内部错误由 lifecycle 统一捕获）。
+    // 绑定事件——WorkerHandle 内部用 isCurrent 守卫，terminate 后回调 no-op（G-025）。
+    // handlers 的 onMessage/onError/onExit 都是 async，这里 void 掉 promise（worker 事件
+    // 不能 await，且 handler 内部错误由 lifecycle 统一捕获）。
     handle.onMessage((raw) => {
       void handlers.onMessage(raw);
     });
@@ -87,9 +87,9 @@ export class WorkerHostImpl implements WorkerHost {
       void handlers.onError(err);
     });
     handle.onExit((code) => {
- // C.3 修复：传 handle 给 onExit，调用方用 handle.isCurrent 做竞态防护。
- // 注意：此时 handle.isCurrent 仍为 true（onExit 回调仅在 isCurrent 时触发，
- // WorkerHandle 的内部守卫已过滤掉 terminate 后的 stale exit）。
+      // C.3 修复：传 handle 给 onExit，调用方用 handle.isCurrent 做竞态防护。
+      // 注意：此时 handle.isCurrent 仍为 true（onExit 回调仅在 isCurrent 时触发，
+      // WorkerHandle 的内部守卫已过滤掉 terminate 后的 stale exit）。
       void handlers.onExit(code, handle);
     });