dsh-engineering-ui 0.0.0-stage → 1.5.1

package/engineering/plugins/dsh-engineering-ui/lib/job-wait-guard.js

@@ -0,0 +1,236 @@
+/**
+ * job-wait-guard.js — 【卡死修复 · 宿主层】job_output 长等待的静默阻塞与整轮中断
+ * ==========================================================================
+ * 事故现场（会话 session-6019cd4b-1ade-4e1f-8850-93f5aec97960，2026-10-31）
+ *   · 22:45:32  父会话调用 job_output { job_id, timeout_ms: 270000, wait: true }
+ *   · 22:45:56  总计子代理调用 job_output { job_id, timeout_ms: 240000, wait: true }
+ *   · 22:46:58  两者【同一毫秒】失败：
+ *                 Error: cannot get required service "jobs" in inactive context
+ *                 turn/end { kind: "interrupted" }   ← 整轮结束
+ *   · 用户只能强退再发「继续，刚刚卡死了，我只能强制退出了」
+ *   · 22:49:03 / 22:49:34 重试（120000 / 330000）→ 22:50:42 再次一模一样地失败
+ *
+ * 根因（两层，缺一不可）
+ *   ①【静默长阻塞】job_output 的 wait 一次性阻塞几分钟，期间 GUI 没有任何反馈；
+ *      用户看到的就是"DSH 死机"，于是强制退出。这是用户可感知伤害的直接来源。
+ *   ②【异常冒到 turn 级】等待期间宿主若停机 / 该服务 fiber 失活，cordis 在解析
+ *      ctx.jobs 时抛 "cannot get required service ... in inactive context"；
+ *      该异常穿过工具边界冒到 agent loop，最终被记成 turn/end{interrupted}，
+ *      整轮对话直接作废。
+ *
+ * 本模块修的就是这两点，且【不依赖预设人设写没写对】：
+ *   A. 把 job_output 的单次等待切成若干【短窗口】（默认 45s）。窗口到点后照常
+ *      返回 "仍在运行" 给模型 —— 模型拿到进度、GUI 保持响应、用户随时能打断。
+ *   B. 任何异常（含上面的 inactive context）都转成**普通工具错误**（isError=true，
+ *      带可操作指引），绝不让框架异常终结整轮。
+ *
+ * 机制（官方契约，非 hack）
+ *   @deepseek-ai/dsh-tool-call-timeout-policy 使用的就是同一层：
+ *     ctx.on('tools/execute', async (exec, next) => ...)
+ *   这里只补"等待窗口 + 异常降级"，不改变 job_output 的任何正常语义。
+ *
+ * 关闭开关（写错配置也绝不会误关；非法值一律回落默认）
+ *   DSH_ENG_JOB_WAIT_GUARD=0         → 整个守卫关闭
+ *   DSH_ENG_JOB_WAIT_MAX_MS=<ms>     → 单次等待上限（默认 45000，最小 5000）
+ *
+ * ⚠️ 设计约束（每条都对应一次实测踩坑，勿随意简化）
+ *   1. 只处理 name === 'job_output' 且 wait:true 且请求超时超过窗口的调用，
+ *      其余工具一律原样透传。
+ *   2. 窗口未到点时必须原样返回 next() 的真实结果，不改变任何正常语义。
+ *   3. 窗口到点返回的是【正常成功结果】，不是 throw —— 绝不能用另一种方式
+ *      重新把对话打断。
+ *   4. 纯 JS 实现、零外部依赖：宿主层缺包会整块不加载，那样修复就白做了。
+ *   5. 守卫自身任何异常都要回落 next()，守卫坏了不能拖垮工具。
+ */
+
+/** 单次等待窗口上限（毫秒）。45s 覆盖一次 SW 建模步骤，又远低于"用户以为死机"的阈值。 */
+const DEFAULT_MAX_WAIT_MS = 45000;
+/** 下限：低于 5s 的等待会退化成忙轮询。 */
+const MIN_MAX_WAIT_MS = 5000;
+
+/** 守卫是否启用（默认启用；显式 0/false/off/no 才关闭）。 */
+function guardEnabled() {
+  try {
+    const raw = process.env.DSH_ENG_JOB_WAIT_GUARD;
+    if (raw === undefined || raw === null || String(raw).trim() === '') return true;
+    const v = String(raw).trim().toLowerCase();
+    return !(v === '0' || v === 'false' || v === 'off' || v === 'no');
+  } catch (e) {
+    return true;
+  }
+}
+
+/** 等待上限：环境变量可覆盖，非法值一律回落默认。 */
+function resolveMaxWaitMs() {
+  try {
+    const raw = process.env.DSH_ENG_JOB_WAIT_MAX_MS;
+    if (raw !== undefined && raw !== null && String(raw).trim() !== '') {
+      const v = Number(String(raw).trim());
+      if (Number.isFinite(v) && v >= MIN_MAX_WAIT_MS) return Math.floor(v);
+    }
+  } catch (e) {}
+  return DEFAULT_MAX_WAIT_MS;
+}
+
+/**
+ * 是否为"宿主上下文 / 服务已失活"这一类框架层拒绝。
+ * 命中后必须降级为可读工具错误，绝不能再让它冒到 turn 级。
+ */
+function isContextLostError(error) {
+  try {
+    const msg = String((error && error.message) || error || '');
+    return /inactive context/i.test(msg)
+        || /cannot get required service/i.test(msg);
+  } catch (e) {
+    return false;
+  }
+}
+
+/** 上下文失活时给模型的、可操作的错误结果。 */
+function contextLostResult(jobId) {
+  const message = 'job_output 等待失败：后台任务所属的宿主上下文已失效（DSH 可能被重启，或该服务已卸载）。'
+    + '这不代表任务本身失败。请改用磁盘 / 文件产物判断进度（例如 mode2_plan.json、room-board、reports/），'
+    + '或先用 job_list 确认该任务是否还在注册表中，再决定是否重新发起。';
+  return {
+    content: [{ type: 'text', text: 'Error: ' + message + (jobId ? '（job_id=' + jobId + '）' : '') }],
+    isError: true,
+    error: {
+      message: 'JOB_CONTEXT_LOST: ' + message,
+      info: { name: 'JobContextLostError', code: 'JOB_CONTEXT_LOST', jobId },
+    },
+  };
+}
+
+/** 等待窗口到点时给模型的"仍在运行"回执（正常成功返回，不是错误）。 */
+function waitWindowResult(jobId, waitedMs, sawStatus) {
+  const status = sawStatus ? '（当前状态：' + sawStatus + '）' : '';
+  const text = '[等待窗口已到 ' + Math.round(waitedMs / 1000) + 's] 后台任务 ' + jobId
+    + ' 仍在运行' + status + '。\n'
+    + '这是【正常的中途返回】，不是失败：任务继续在后台跑。\n'
+    + '要继续等待请再调一次 job_output（wait:true）；先做别的事就稍后再读；'
+    + '真的不需要了就 job_kill。建议同时用磁盘产物判断进度，别把整轮对话挂在等待上。';
+  return {
+    content: [{ type: 'text', text }],
+    isError: false,
+    meta: { jobWaitWindow: waitedMs },
+  };
+}
+
+/** 从一次 job_output 的结果里抽状态行，用于"仍在运行"回执。 */
+function statusOf(result) {
+  try {
+    const blocks = (result && result.content) || [];
+    for (const b of blocks) {
+      if (!b || b.type !== 'text' || typeof b.text !== 'string') continue;
+      const m = b.text.match(/\[status:\s*([^\]]+)\]/);
+      if (m) return m[1].trim();
+    }
+    const job = result && result.value && result.value.job;
+    if (job && job.status) return String(job.status);
+  } catch (e) {}
+  return '';
+}
+
+/** 该次调用是否属于本守卫要处理的长等待。 */
+function inspectsLongWait(exec, maxWaitMs) {
+  try {
+    if (!exec || exec.name !== 'job_output') return null;
+    const args = exec.arguments || {};
+    if (args.wait !== true) return null;
+    const requested = (typeof args.timeout_ms === 'number' && Number.isFinite(args.timeout_ms))
+      ? args.timeout_ms
+      : 30000;                                  // 与 dsh-tool-jobs 的 waitTimeoutMs 默认一致
+    if (requested <= maxWaitMs) return null;     // 本来就短，不必介入
+    return { jobId: String(args.job_id || ''), requested, effective: maxWaitMs };
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 装配守卫。返回 disposer。
+ * @param ctx 宿主插件上下文（需可监听 'tools/execute'）
+ * @returns {() => void}
+ */
+export function installJobWaitGuard(ctx) {
+  if (!guardEnabled() || !ctx || typeof ctx.on !== 'function') {
+    return () => {};
+  }
+  const maxWaitMs = resolveMaxWaitMs();
+
+  const listener = async (exec, next) => {
+    let plan = null;
+    try {
+      plan = inspectsLongWait(exec, maxWaitMs);
+    } catch (e) {
+      plan = null;
+    }
+
+    // ── 非长等待：原样透传；仅当是 job_output 且命中上下文失活时降级 ──
+    if (!plan) {
+      try {
+        return await next();
+      } catch (error) {
+        if (exec && exec.name === 'job_output' && isContextLostError(error)) {
+          return contextLostResult(exec.arguments && exec.arguments.job_id);
+        }
+        throw error;
+      }
+    }
+
+    // ── 长等待：用【窗口竞速】实现，绝不改写 exec.arguments ─────────────
+    //   ⚠️ 为什么不能改写参数（实测契约，别想当然）：
+    //     dsh-tools 在 createExecution 里就做了
+    //         arguments: deepFreeze(snapshotJsonValue(exec.arguments))
+    //     所以 tools/execute 包装层拿到的 exec.arguments 是【深冻结】的，
+    //     任何赋值都 throws（严格模式）。早先"把 timeout_ms 改小"的写法在这里
+    //     会被静默跳过 —— 看起来装上了守卫，实际一次都没生效。
+    //   因此这里改为：保留原始参数不动，自己给 next() 设一个截止时间；
+    //     到点后该工具调用立即返回（后台 job 继续跑，语义与 job_output 一致）。
+    const startedAt = Date.now();
+    let timer = null;
+    let finished = false;
+    const windowExpired = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        if (finished) return;
+        resolve('window');
+      }, maxWaitMs);
+      // 让定时器不阻塞进程退出（宿主关闭时立刻放行，不留悬挂 handle）
+      try { if (timer && typeof timer.unref === 'function') timer.unref(); } catch (e) {}
+    });
+
+    try {
+      const raced = await Promise.race([
+        Promise.resolve(next()).then((result) => ({ kind: 'done', result })),
+        windowExpired.then(() => ({ kind: 'window' })),
+      ]);
+      finished = true;
+      if (timer) { try { clearTimeout(timer); } catch (e) {} }
+      if (raced.kind === 'window') {
+        // 窗口到点：返回正常回执，任务仍在后台运行（不是失败、不打断对话）
+        return waitWindowResult(plan.jobId, Date.now() - startedAt, '');
+      }
+      const result = raced.result;
+      const st = statusOf(result);
+      // 任务已结束（completed / killed / failed）→ 真实结果原样返回
+      if (st && !/running|stopping/i.test(st)) return result;
+      return waitWindowResult(plan.jobId, Date.now() - startedAt, st);
+    } catch (error) {
+      finished = true;
+      if (timer) { try { clearTimeout(timer); } catch (e) {} }
+      if (isContextLostError(error)) return contextLostResult(plan.jobId);
+      throw error;
+    }
+  };
+
+  const off = ctx.on('tools/execute', listener);
+  return () => {
+    try { if (typeof off === 'function') off(); } catch (e) {}
+  };
+}
+
+export const JOB_WAIT_GUARD_DEFAULTS = Object.freeze({
+  enabled: true,
+  maxWaitMs: DEFAULT_MAX_WAIT_MS,
+  minWaitMs: MIN_MAX_WAIT_MS,
+});

package/engineering/plugins/dsh-engineering-ui/lib/mem-guard.js

@@ -0,0 +1,331 @@
+/**
+ * mem-guard.js — 【内存守卫】子代理并发限流 + 只回收工作集（不杀进程、不打断流程）
+ * ==========================================================================
+ * 为什么要有这个模块（两件事，一个来源）
+ *   ① 多屋并行时主对话会一口气 subagent_fork 出 8~12 个小屋：每个小屋是
+ *      一个独立 Agent + 独立上下文档，同时跑 SolidWorks 时把测试机内存打爆；
+ *   ② 用户要求「最多同时 3 个子代理」，且「清理系统运行内存但不要影响流程」。
+ *
+ * 结论（也是本模块的设计红线）
+ *   · 唯一安全的「清理内存」手段是 EmptyWorkingSet：它把进程工作集里的干净页
+ *     换出到 standby / pagefile，进程继续存活，下次访问时由缺页中断换回来 ——
+ *     **不杀进程、不断会话、不丢上下文**。
+ *   · 绝不使用杀 SLDWORKS / 杀 node / 清 standby list 这类会破坏流程的手段。
+ *     杀 SW 已由 sw_guard 负责（只在 CPU/内存 > 85% 的极端情况触发），
+ *     本模块只做低风险回收。
+ *   · 任何一步失败都静默降级（返回 ok:false + 原因），绝不抛、绝不影响主流程。
+ *
+ * 两条能力
+ *   A. 并发闸门：evaluateConcurrency() 是纯函数，输入 subagents.listDescendants
+ *      的结果，输出是否允许再 fork。真正的拦截点在 index.js 的 tools/pre-execute。
+ *   B. 工作集回收：reclaimWorkingSets() 只对本进程 + 会话相关进程调用
+ *      EmptyWorkingSet；memorySnapshot() 用 kernel32.GlobalMemoryStatusEx 读真实
+ *      可用内存，供阈值判定与报告。
+ *
+ * 环境开关（写错一律回落默认，绝不因配置把功能关死）
+ *   DSH_ENG_MEM_GUARD=0             → 关闭整个内存守卫（并发闸门 + 回收都停）
+ *   DSH_ENG_MAX_SUBAGENTS=3         → 并发子代理上限（默认 3，范围 1..12）
+ *   DSH_ENG_MEM_RECLAIM_PCT=85      → 内存占用超过该百分比才做工作集回收
+ *   DSH_ENG_MEM_RECLAIM_MS=90000    → 两次回收的最小间隔
+ *
+ * 依赖：只用 Node 内置模块（child_process）。EmptyWorkingSet 通过 PowerShell
+ *   一行 Add-Type 调 psapi.dll —— 不引入任何第三方包，宿主缺包也不会整块挂掉。
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/** 默认并发上限（用户明确要求：最多同时开 3 个子代理）。 */
+export const DEFAULT_MAX_SUBAGENTS = 3;
+/** 上限的硬边界：再大就等于没有闸门。 */
+const MAX_SUBAGENTS_CAP = 12;
+/** 默认内存占用阈值（百分比）。 */
+const DEFAULT_RECLAIM_PCT = 85;
+/** 两次回收的最小间隔。 */
+const DEFAULT_RECLAIM_MS = 90000;
+
+/** 守卫是否启用（默认启用；显式 0/false/off/no 才关闭）。 */
+export function memGuardEnabled() {
+  try {
+    const raw = process.env.DSH_ENG_MEM_GUARD;
+    if (raw === undefined || raw === null || String(raw).trim() === '') return true;
+    const v = String(raw).trim().toLowerCase();
+    return !(v === '0' || v === 'false' || v === 'off' || v === 'no');
+  } catch (e) {
+    return true;
+  }
+}
+
+/**
+ * 运行期覆盖（由宿主从 tools/mem_guard.json 读出来后注入）。
+ * 优先级：运行期覆盖 > 环境变量 > 内置默认。
+ * 之所以留这一层：设置页改完要【立刻生效】，而环境变量在宿主进程里改不动。
+ */
+let RUNTIME_OVERRIDES = {};
+
+/** 注入运行期覆盖（宿主在装配时调用；非法值一律忽略）。 */
+export function setMemGuardOverrides(obj) {
+  RUNTIME_OVERRIDES = (obj && typeof obj === 'object') ? { ...obj } : {};
+}
+
+/** 读当前运行期覆盖（只读副本，供状态路由回显）。 */
+export function memGuardOverrides() {
+  return { ...RUNTIME_OVERRIDES };
+}
+
+/** 取一个数：运行期覆盖 → 环境变量 → 默认。 */
+function pickInt(key, envName, fallback, min, max) {
+  const over = RUNTIME_OVERRIDES ? RUNTIME_OVERRIDES[key] : undefined;
+  if (over !== undefined && over !== null && String(over).trim() !== '') {
+    const n = Number(String(over).trim());
+    if (Number.isFinite(n)) {
+      const v = Math.floor(n);
+      if (v >= min) return Math.min(max, v);
+    }
+  }
+  return positiveInt(process.env[envName], fallback, min, max);
+}
+
+function positiveInt(raw, fallback, min, max) {
+  try {
+    if (raw === undefined || raw === null || String(raw).trim() === '') return fallback;
+    const v = Number(String(raw).trim());
+    if (!Number.isFinite(v)) return fallback;
+    const n = Math.floor(v);
+    if (n < min) return fallback;
+    return Math.min(max, n);
+  } catch (e) {
+    return fallback;
+  }
+}
+
+/** 并发子代理上限（默认 3）。 */
+export function maxActiveSubagents() {
+  return pickInt('max_subagents', 'DSH_ENG_MAX_SUBAGENTS', DEFAULT_MAX_SUBAGENTS, 1, MAX_SUBAGENTS_CAP);
+}
+
+/** 触发工作集回收的内存占用百分比。 */
+export function reclaimThresholdPct() {
+  return pickInt('reclaim_threshold_pct', 'DSH_ENG_MEM_RECLAIM_PCT', DEFAULT_RECLAIM_PCT, 50, 99);
+}
+
+/** 两次回收的最小间隔（毫秒）。 */
+export function reclaimIntervalMs() {
+  return pickInt('reclaim_interval_ms', 'DSH_ENG_MEM_RECLAIM_MS', DEFAULT_RECLAIM_MS, 5000, 3600000);
+}
+
+/**
+ * 该 root 当前「占着并发名额」的子代理 id 列表。
+ *
+ * ── 为什么统计孙代（实测坑）────────────────────────────────────────
+ * DSH 的子代理名额由每个 root 的 ActivationPool 统一计数，且只有子代理真正
+ * 结束（自然收敛或被 dispose）才释放。主对话 fork 出来、已经跑完但仍驻留的
+ * 小屋照样占名额 —— 只数「自己的直接子代理」会低估，于是闸门看起来放行了，
+ * 实际 fork 仍会被宿主拒绝（ACTIVATION_LIMIT_REACHED）。
+ *
+ * @param rows subagents.listDescendants(rootId) 的返回值
+ * @param rootId root 会话 id
+ */
+export function countOccupiedChildren(rows, rootId) {
+  const out = [];
+  const list = Array.isArray(rows) ? rows : [];
+  for (const row of list) {
+    if (!row || row.kind !== 'child' || !row.id) continue;
+    if (String(row.parentId || '') === String(rootId || '')) { out.push(String(row.id)); continue; }
+    if (row.hasChildren === true) out.push(String(row.id));
+  }
+  return { ids: out, hasChildren: list.some((r) => r && r.kind === 'child') };
+}
+
+/**
+ * 并发闸门判定（纯函数，便于单测）。
+ *
+ * @param rows listDescendants 结果
+ * @param rootId 当前 root 会话 id
+ * @param _agentId 想 fork 的那个 agent id（保留参数，便于日志）
+ * @param max 上限
+ */
+export function evaluateConcurrency(rows, rootId, _agentId, max) {
+  const limit = Number.isFinite(max) && max > 0 ? max : DEFAULT_MAX_SUBAGENTS;
+  const active = countOccupiedChildren(rows, rootId).ids.length;
+  if (active < limit) return { allowed: true, active, max: limit };
+  const message = '子代理并发已达上限（当前 ' + active + ' / 上限 ' + limit + '），本次 subagent_fork 已被拒绝。'
+    + '\n【为什么】每个子代理都常驻占用内存与一个 DSH 子代理名额；同批开太多会把内存打爆，整个工程模式一起卡死。'
+    + '上限可用 DSH_ENG_MAX_SUBAGENTS 调整（默认 3）。'
+    + '\n【现在怎么做】先等一个已在跑的小屋结束（或对它 room-fail / interrupt_agent 收尾），'
+    + '再用 mode_gate.py room-board 确认名额释放，然后重新 fork。'
+    + '\n【不要】把多的零件塞给同一个房间硬编 —— 那会让该房间的报告与门禁口径对不上。';
+  return { allowed: false, active, max: limit, reason: 'SUBAGENT_LIMIT_REACHED', message };
+}
+
+/** 会话相关进程：自己 + DSH 宿主 + SolidWorks。 */
+export function targetProcessNames() {
+  return ['node.exe', 'SLDWORKS.exe', 'DeepSeek Harness.exe'];
+}
+
+/**
+ * 生成读内存 + 回收工作集的 PowerShell 脚本。
+ *
+ * 只用 psapi.EmptyWorkingSet：把工作集里的干净页移出（standby），进程继续运行；
+ * 不做 SetProcessWorkingSetSize(-1,-1) 的硬修剪（x64 上参数会被截断，且会强制
+ * 把整个工作集刷到 pagefile，反而拖慢下一次访问）。
+ *
+ * @param pids 目标进程 id 列表（空数组 = 只读内存，不回收）
+ */
+export function buildWorkingSetScript(pids) {
+  const list = Array.isArray(pids)
+    ? pids.map((n) => Number(n)).filter((n) => Number.isFinite(n) && n > 0)
+    : [];
+  const arr = list.length ? list.join(',') : '';
+  return [
+    '$ErrorActionPreference = "SilentlyContinue"',
+    'Add-Type -Namespace DshMem -Name Native -MemberDefinition @"',
+    '[DllImport("kernel32.dll", SetLastError=true)] public static extern bool GlobalMemoryStatusEx(ref MEMORYSTATUSEX lpBuffer);',
+    '[DllImport("psapi.dll", SetLastError=true)] public static extern bool EmptyWorkingSet(IntPtr hProcess);',
+    '[DllImport("kernel32.dll", SetLastError=true)] public static extern IntPtr OpenProcess(uint access, bool inherit, uint pid);',
+    '[DllImport("kernel32.dll", SetLastError=true)] public static extern bool CloseHandle(IntPtr h);',
+    '[StructLayout(LayoutKind.Sequential)] public struct MEMORYSTATUSEX {',
+    '  public uint dwLength; public uint dwMemoryLoad;',
+    '  public ulong ullTotalPhys; public ulong ullAvailPhys;',
+    '  public ulong ullTotalPageFile; public ulong ullAvailPageFile;',
+    '  public ulong ullTotalVirtual; public ulong ullAvailVirtual;',
+    '  public ulong ullAvailExtendedVirtual;',
+    '}',
+    '"@',
+    '$m = New-Object DshMem.Native+MEMORYSTATUSEX',
+    '$m.dwLength = [System.Runtime.InteropServices.Marshal]::SizeOf($m)',
+    '[void][DshMem.Native]::GlobalMemoryStatusEx([ref]$m)',
+    '$before = [pscustomobject]@{',
+    '  load = [int]$m.dwMemoryLoad',
+    '  total_mb = [math]::Round($m.ullTotalPhys / 1MB)',
+    '  free_mb = [math]::Round($m.ullAvailPhys / 1MB)',
+    '}',
+    '$ok = 0',
+    '$failed = 0',
+    arr ? ('$targets = @(' + arr + ')') : '$targets = @()',
+    'foreach ($p in $targets) {',
+    '  $h = [DshMem.Native]::OpenProcess(0x1500, $false, [uint32]$p)',
+    '  if ($h -eq [IntPtr]::Zero) { $failed++; continue }',
+    '  try { if ([DshMem.Native]::EmptyWorkingSet($h)) { $ok++ } else { $failed++ } }',
+    '  finally { [void][DshMem.Native]::CloseHandle($h) }',
+    '}',
+    '[void][DshMem.Native]::GlobalMemoryStatusEx([ref]$m)',
+    '$after = [pscustomobject]@{',
+    '  load = [int]$m.dwMemoryLoad',
+    '  total_mb = [math]::Round($m.ullTotalPhys / 1MB)',
+    '  free_mb = [math]::Round($m.ullAvailPhys / 1MB)',
+    '}',
+    '[pscustomobject]@{ before = $before; after = $after; reclaimed = $ok; failed = $failed } | ConvertTo-Json -Compress -Depth 4',
+  ].join('\n');
+}
+
+/** PowerShell 可能带警告行，取最后一段 JSON。 */
+export function parseLastJson(text) {
+  const s = String(text || '').trim();
+  if (!s) return null;
+  try { return JSON.parse(s); } catch (e) { /* 继续 */ }
+  const i = s.indexOf('{');
+  const j = s.lastIndexOf('}');
+  if (i >= 0 && j > i) {
+    try { return JSON.parse(s.slice(i, j + 1)); } catch (e) { return null; }
+  }
+  return null;
+}
+
+/**
+ * 只读内存快照（不回收）。失败时返回 ok:false，绝不抛。
+ */
+export function memorySnapshot() {
+  try {
+    const r = spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', buildWorkingSetScript([])], {
+      encoding: 'utf8', windowsHide: true, timeout: 15000,
+    });
+    if (!r || typeof r.stdout !== 'string' || !r.stdout.trim()) {
+      return { ok: false, error: String((r && r.stderr) || 'powershell 无输出').slice(0, 400) };
+    }
+    const j = parseLastJson(r.stdout);
+    if (!j || !j.before) return { ok: false, error: '内存快照解析失败' };
+    return { ok: true, load: j.before.load, total_mb: j.before.total_mb, free_mb: j.before.free_mb };
+  } catch (e) {
+    return { ok: false, error: String((e && e.message) || e) };
+  }
+}
+
+/** 按进程名取 pid（tasklist /FO CSV 解析，失败返回空数组）。 */
+export function listPidsByName(names) {
+  const wanted = new Set((Array.isArray(names) ? names : []).map((n) => String(n).toLowerCase()));
+  if (!wanted.size) return [];
+  try {
+    const r = spawnSync('tasklist', ['/FO', 'CSV', '/NH'], { encoding: 'utf8', windowsHide: true, timeout: 15000 });
+    const out = String((r && r.stdout) || '');
+    const pids = [];
+    for (const line of out.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      const cols = line.split('","').map((c) => c.replace(/^"|"$/g, ''));
+      if (cols.length < 2) continue;
+      if (!wanted.has(String(cols[0] || '').toLowerCase())) continue;
+      const pid = Number(cols[1]);
+      if (Number.isFinite(pid) && pid > 0) pids.push(pid);
+    }
+    return pids;
+  } catch (e) {
+    return [];
+  }
+}
+
+/**
+ * 回收工作集并返回前后对比。
+ *
+ * @param options.pids 显式指定的进程 id（不传则按进程名匹配）
+ * @param options.force 忽略阈值与间隔（仍受 memGuardEnabled 控制）
+ */
+export function reclaimWorkingSets(options) {
+  const opts = options || {};
+  if (!memGuardEnabled()) return { ok: false, skipped: 'disabled' };
+  let pids = Array.isArray(opts.pids) ? opts.pids : null;
+  if (!pids || !pids.length) {
+    if (!opts.force) {
+      const snap = memorySnapshot();
+      if (!snap.ok) return { ok: false, error: snap.error };
+      if (typeof snap.load === 'number' && snap.load < reclaimThresholdPct()) {
+        return { ok: true, skipped: 'below-threshold', before: snap };
+      }
+    }
+    pids = listPidsByName(targetProcessNames());
+  }
+  if (!pids.length) return { ok: true, skipped: 'no-targets' };
+  try {
+    const r = spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', buildWorkingSetScript(pids)], {
+      encoding: 'utf8', windowsHide: true, timeout: 30000,
+    });
+    const j = parseLastJson(r && r.stdout);
+    if (!j || !j.before) {
+      return { ok: false, error: String((r && r.stderr) || 'powershell 无输出').slice(0, 400) };
+    }
+    return {
+      ok: true, before: j.before, after: j.after,
+      reclaimed: Number(j.reclaimed) || 0, failed: Number(j.failed) || 0, pids,
+    };
+  } catch (e) {
+    return { ok: false, error: String((e && e.message) || e) };
+  }
+}
+
+/**
+ * 节流回收器：同一进程内两次回收至少间隔 reclaimIntervalMs()。
+ * 供「每轮结束 / 每次 fork 之后」的轻量调用，避免频繁刷工作集。
+ */
+export function createReclaimer() {
+  let lastAt = 0;
+  let lastResult = null;
+  return function maybeReclaim(options) {
+    const opts = options || {};
+    const now = Date.now();
+    if (!opts.force && lastAt && (now - lastAt) < reclaimIntervalMs()) {
+      return { ok: true, skipped: 'throttled', last: lastResult };
+    }
+    const r = reclaimWorkingSets(opts);
+    lastAt = now;
+    lastResult = r;
+    return r;
+  };
+}