multi-tasks 3.2.3 → 3.4.0

package/README.md

@@ -255,7 +255,7 @@ multiTasks.restart({ taskFolder: `/myworks/my_scan_tasks/my-task` }); //deletes
 
 ```
 
-Unlike `retry_fails` (which re-runs only the failed tasks), `restart` re-runs **all the initial tasks** — tasks created dynamically via `helper.createNewTasks` are not restored and will not be re-run. Fields you pass (e.g. `processTask`) override the snapshot and are written back into it; the same self-contained-function note as in Resuming applies. (**Breaking change:** the name `restart` was the old name of `retry_fails` in v2 and in the published v3.0–v3.1.x releases; this is a different API — calling it no longer retries failed tasks, it wipes the folder and re-runs everything.)
+Unlike `retry_fails` (which re-runs only the failed tasks), `restart` re-runs **all the initial tasks** — tasks created dynamically via `helper.createNewTasks` are not restored and will not be re-run. Fields you pass (e.g. `processTask`) override the snapshot and are written back into it; the same self-contained-function note as in Resuming applies.
 
 ### Real-Time Monitoring
 
@@ -264,13 +264,11 @@ Monitor your running tasks with [multi-tasks-monitor](https://www.npmjs.com/pack
 Quick start (requires multi-tasks >=3.2.0): once your multi-tasks run has started, the startup log prints the monitor command with the task folder path already filled in — just copy-paste it into another terminal:
 
 ```text
-****************************************************************
-[Master]: monitor this task with:
-    npx multi-tasks-monitor --task-dir "D:\tasks\multitasks20260806..." --port 3777
-****************************************************************
+monitor install cmd : npm install multi-tasks-monitor
+monitor start cmd   : npx multi-tasks-monitor --task-dir "D:\tasks\multitasks20260806..." --port 3777
 ```
 
-For installation, command-line options, and more, see the [multi-tasks-monitor](https://www.npmjs.com/package/multi-tasks-monitor) page.
+For command-line options and more, see the [multi-tasks-monitor](https://www.npmjs.com/package/multi-tasks-monitor) page.
 
 ### API:
 
@@ -286,20 +284,22 @@ The API has three parts: the entry functions, the config options, and the `helpe
 **Config options:**
 
 - **`initialTasks`** — array of task objects, a function returning the array (or a Promise of it — called only once, in the master process; worker processes never call it; see [Performance: runs only once, in the master process](#performance-runs-only-once-in-the-master-process)), or a folder path string to resume from.
-- **`processTask(task, helper)`** — required; return a value or a Promise.
+- **`processTask(task, helper)`** — required; return a result or a Promise with result. Results are stored as JSON in `results/succ/<subid>.json`; if a result cannot be saved because it is not JSON-serializable, the task still counts as succeeded, and a warning shows up in the command line and in monitor tools.
 - **`taskRootFolder`** — the task run folder (named by `taskId`) is created under this directory.
 - **`taskId`** — task folder name under `taskRootFolder`.
 - **`numberOfWorkers`** — how many worker processes run in parallel; a number, or a percentage string of CPU cores like `"50%"` (default).
 - **`taskTimeout`** — optional, milliseconds; an overdue task fails with a timeout error.
 - **`maxTaskRetries`** — optional, max times a failed task is auto-retried.
 - **`workerPriority`** — optional, OS scheduling priority for worker processes: `'low' | 'below_normal' | 'normal' | 'above_normal' | 'high'`, or a nice number (integer -20~19). Lower priority keeps the machine responsive while a long batch occupies all cores; invalid values throw before any task folder is created.
-- **`progressBar`** — `true` by default: shows a live single-line progress bar in the terminal (set `false` to disable); logs (including your own `console.*` calls) always go to `<taskFolder>/.sys/run.log`, and print to the console as well only when the bar is off or stdout is not a TTY.
+- **`progressBar`** — `true` by default: shows a live progress bar in the terminal; set `false` to fall back to plain log output.
+- **`worker_status_poll_ms`** — worker status poll interval in ms; default `2000`; `0` (or `false`) disables the worker status table; `true` means the default rate.
 - **`autoCloseAfterCompletion`** — set `true` to kill workers and exit the process when no tasks are left; default is `false`, i.e. workers stay alive waiting for dynamically created tasks.
-- **`shouldTerminate(info)`** — return `true` to terminate the whole process.
+- **`shouldTerminate(info)`** — return `true` to terminate the whole process. If it throws, the error is logged and the task is dispatched anyway (treated as "don't terminate").
 - **`setSysListener(event, payload, meta)`** — optional, handle custom system events (sent via `helper.emitSys`) on the master; `meta` has `fromWorkerId` and `fromWorkerPid`.
-- **`onFinish(report, helper)`** — called once after all workers exit (only when `autoCloseAfterCompletion` is `true`). `report` summarizes the run: `{ taskId, taskFolder, startTimestamp, endTimestamp, cost, total, succeeded, failed, failedTasks, workers }` — `cost` is the run duration in ms (a resumed run measures only the current round); `failedTasks` lists the failed tasks' subids; `workers` is `{ count, crashed }` — the configured worker count and how many workers crashed and were replaced. `helper` lets you walk every persisted task result:
-  - **`helper.foreachSuccResult((count, task, result) => {})`** — iterate all succeeded results (`results/succ`); `count` is a 0-based index, `task` is the original task object (`null` if its task file is missing or unparseable), `result` is the value returned by `processTask` (`undefined` when the task returned nothing).
-  - **`helper.foreachErrorResult((count, task, err) => {})`** — iterate all failed results (`results/errors`); `err` is the persisted error object as-is (`{ex}` / `{subTask, exception}` / `{type: 'timeout', ...}` / `{type: 'worker_crash', ...}`).
+- **`onFinish(report, helper)`** — called once after all workers exit (only when `autoCloseAfterCompletion` is `true`). `report` summarizes the run: `{ taskId, taskFolder, startTimestamp, endTimestamp, cost, total, succeeded, failed, failedTasks, succButSaveFailed, workers }` — `cost` is the run duration in ms (a resumed run measures only the current round); `failedTasks` lists the failed tasks' subids; `succButSaveFailed` counts tasks that ran fine but whose results could not be JSON-serialized (details in `<taskFolder>/.sys/user_messages/`); `workers` is `{ count, crashed }` — the configured worker count and how many workers crashed and were replaced. `helper` lets you walk every persisted task result:
+  - **`helper.foreachSuccResult((count, task, result) => {})`** — iterate all succeeded results (`results/succ`); `count` is a 0-based index, `task` is the original task object (`null` if its task file is missing or unparseable), `result` is the value returned by `processTask` (`undefined` when the task returned nothing; a `{type: 'result_serialize_error', message}` placeholder when the returned value could not be JSON-serialized).
+  - **`helper.foreachErrorResult((count, task, err) => {})`** — iterate all failed results (`results/errors`); `err` is the persisted error object as-is (`{ex}` / `{subTask, exception}` / `{type: 'timeout', ...}` / `{type: 'worker_crash', ...}`). A non-`Error` rejection value that is not JSON-serializable is persisted as `{ex: {type: 'unserializable_error_value', ...}}`.
+  - **`helper.foreachResult((count, task, result, succeeded) => {})`** — iterate all results regardless of outcome (succeeded first, then failed; `count` runs continuously across both); `succeeded` is `true` for results from `results/succ` and `false` for those from `results/errors` (where `result` is the persisted error object).
   - Iteration follows filesystem order (not sorted). `onFinish` runs synchronously at the very end and the master process exits shortly after it returns — don't `await` inside it.
 
 **Other options:**
@@ -315,6 +315,8 @@ The API has three parts: the entry functions, the config options, and the `helpe
 
 ### Changelog:
 
+- 3.4.0 Show per-worker load (ELU/CPU/memory) under progressBar; stability fixes
+- 3.3.0 Unserializable results still succeed; shouldTerminate throwing is safe; progressBar counters added
 - 3.2.3 Support workerPriority: set OS scheduling priority for worker processes
 - 3.2.2 initialTasks accepts a function (sync or async) that is called only once, in the master process
 - 3.2.1 Fix retry bug: user-defined taskCount/index no longer overwritten on task retries

package/package.json

@@ -1,36 +1,36 @@
-{
-  "name": "multi-tasks",
-  "version": "3.2.3",
-  "description": "Multi-process task scheduling based on Node.js cluster, with crash resume and failed-task restart support",
-  "main": "index.js",
-  "files": [
-    "index.js",
-    "workers",
-    "utils/*.js"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://gitee.com/zhanglei923/multi-tasks.git"
-  },
-  "directories": {
-    "example": "examples"
-  },
-  "engines": {
-    "node": ">=14.14"
-  },
-  "scripts": {
-    "test": "jest",
-    "prepublishOnly": "npm test"
-  },
-  "keywords": [
-    "multitask",
-    "worker",
-    "multithread"
-  ],
-  "author": "zhanglei923@gmail.com",
-  "license": "MIT",
-  "devDependencies": {
-    "cli-progress": "^3.12.0",
-    "jest": "^29.7.0"
-  }
-}
+{
+  "name": "multi-tasks",
+  "version": "3.4.0",
+  "description": "Multi-process task scheduling based on Node.js cluster, with crash resume and failed-task restart support",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "workers",
+    "utils/*.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/zhanglei923/multi-tasks.git"
+  },
+  "directories": {
+    "example": "examples"
+  },
+  "engines": {
+    "node": ">=14.14"
+  },
+  "scripts": {
+    "test": "jest",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "multitask",
+    "worker",
+    "multithread"
+  ],
+  "author": "zhanglei923@gmail.com",
+  "license": "MIT",
+  "devDependencies": {
+    "cli-progress": "^3.12.0",
+    "jest": "^29.7.0"
+  }
+}

package/utils/makedir.js

@@ -1,5 +1,4 @@
 const fs = require('fs');
-const path = require('path');
 
 function sync(directoryPath) {
     directoryPath = directoryPath.replace(/\\/g, '/');
@@ -12,24 +11,19 @@ function getDirectFiles(dir, callback) {
         console.log('FATAL: directory is missing:', dir);
         return process.exit(1);        
     }
-    fs.readdir(dir, (err, files) => {  
-        if (err) {  
-            console.error("Could not list the directory.", err);  
-            return callback([]);
+    let entries;
+    try{
+        entries = fs.readdirSync(dir, { withFileTypes: true });//一次拿齐 isFile, 省掉逐文件 statSync(大任务量启动/resume 显著)
+    }catch(err){
+        console.error("Could not list the directory.", err);
+        return callback([]);
+    }
+    entries.forEach((entry)=>{
+        if(entry.isFile()){
+            childrenfiles.push(entry.name);
         }
-        files.forEach(file => {  
-            const filePath = path.join(dir, file);
-            try{
-                let stats = fs.statSync(filePath);
-                if (stats.isFile()) {  
-                    childrenfiles.push(file); 
-                }  
-            }catch(e){
-                //
-            }
-        });
-        callback(childrenfiles);
-    });  
+    });
+    callback(childrenfiles);
 }  
 
 module.exports = {sync, getDirectFiles};

package/utils/progressCtl.js

@@ -1,118 +1,287 @@
-//progressBar master 端控制器(零依赖): 持有渲染器实例与忙碌表, 封装 TTY 判定与节流渲染,
-//Multithread 只调语义化方法(setup/workerStarted/taskAssigned/...), 不碰渲染细节。
-//纯 master 端运行时状态, 不进快照不进 IPC; 统计数据(getStats/getRemaining)由调用方注入, 本模块不依赖 TaskMgr。
-//console 劫持与 run.log 已与 progressBar 解耦(永久生效, 见 utils/runLog), 不再是本模块的职责。
-//单行进度条(progressView): worker 增删不体现在渲染上, 这里只维护 busyWorkers 计数 running。
-const progressView = require('./progressView');
-
-let RENDER_INTERVAL = 100;//渲染节流: 高频小任务场景避免每次事件都 readdirSync(getFinalStats) 造成 O(N²) 盘扫
-
-let view = null;//progressView 渲染器实例, 未开启为 null
-let progressOn = false;//progressBar 且 stdout 为 TTY 时为真(非 TTY 回退普通日志)
-let busyWorkers = {};//worker.id -> subid, master 端忙碌表
-let getStats = null;//() => TaskMgr.getFinalStats(), setup 注入
-let getRemaining = null;//() => new 目录任务数, setup 注入
-let lastRenderAt = 0;
-let renderTimer = null;
-
-const reset = () => {//master start 入口/同进程再跑一轮时调用: 清掉上一轮全部残留(含未发的节流帧)
-  if (renderTimer) {
-    clearTimeout(renderTimer);
-    renderTimer = null;
-  };
-  view = null;
-  progressOn = false;
-  busyWorkers = {};
-  lastRenderAt = 0;
-};
-
-//开启判定 + 初始化: 返回是否真正开启(显式 progressBar:false 关闭, 缺省默认开启;
-//非 TTY 一律回退普通日志, 仅显式 true 时打回退警告, 默认开启静默回退)
-const setup = ({ config, stream, getStats: statsFn, getRemaining: remainingFn }) => {
-  reset();
-  if (config.progressBar === false) {
-    return false;
-  };
-  if (!stream.isTTY) {//ANSI 控制码写进重定向输出是垃圾: 回退为现有控制台日志
-    if (config.progressBar === true) {
-      console.warn('[Master]: progressBar needs a TTY stdout, fallback to console logs');
-    };
-    return false;
-  };
-  progressOn = true;
-  getStats = statsFn;
-  getRemaining = remainingFn;
-  view = progressView.create({ stream, barWidth: 30 });
-  return true;
-};
-
-const isOn = () => {
-  return progressOn;
-};
-
-const doRender = () => {
-  //完成数按盘上结果目录统计: 重试/超时/崩溃各种路径天然正确, 无需在协议里额外计数
-  let stats = getStats();
-  let done = stats.succeeded + stats.failed;
-  let running = Object.keys(busyWorkers).length;
-  lastRenderAt = Date.now();
-  view.render({ done, running, remaining: getRemaining() });
-};
-
-const render = () => {
-  if (!view) {
-    return;
-  };
-  if (renderTimer) {
-    return;//已挂着一个尾随渲染, 合并掉中间帧
-  };
-  let wait = RENDER_INTERVAL - (Date.now() - lastRenderAt);
-  if (wait <= 0) {
-    doRender();
-    return;
-  };
-  renderTimer = setTimeout(() => {
-    renderTimer = null;
-    if (view) {
-      doRender();
-    };
-  }, wait);
-  renderTimer.unref();//不阻碍 master 退出(最后一帧可能因进程退出丢失, 可接受)
-};
-
-const workerStarted = (id, pid) => {//单行进度条不展示 worker 行: 仅保留语义入口, 无渲染动作
-};
-
-const taskAssigned = (id, subid) => {
-  busyWorkers[id] = subid;
-  render();
-};
-
-const taskCompleted = (id) => {
-  if (busyWorkers[id]) {
-    delete busyWorkers[id];
-  };
-};
-
-const workerExited = (id) => {
-  delete busyWorkers[id];
-  render();
-};
-
-const finish = () => {//收尾: 换行定格进度条行(master 退出前调用); 未开启为 no-op
-  if (view) {
-    view.end();
-  };
-};
-
-module.exports = {
-  setup,
-  reset,
-  isOn,
-  render,
-  workerStarted,
-  taskAssigned,
-  taskCompleted,
-  workerExited,
-  finish,
-};
+//progressBar master 端控制器(零依赖): 持有渲染器实例与忙碌表, 封装 TTY 判定与节流渲染,
+//Multithread 只调语义化方法(setup/workerStarted/taskAssigned/...), 不碰渲染细节。
+//纯 master 端运行时状态, 不进快照不进 IPC; 统计数据(getStats/getRemaining)由调用方注入, 本模块不依赖 TaskMgr。
+//console 劫持与 run.log 已与 progressBar 解耦(永久生效, 见 utils/runLog), 不再是本模块的职责。
+//N 行帧进度区(progressView): 首行 bar, 末行计数器行, 状态显示开启(worker_status_poll_ms 缺省 2000, <=0 关)时中间整组插入
+//ASCII 状态表(每组 6 行: id 表头/分隔横线/elu/cpu/rss/heap——去顶/底框、去列间隔符纯空格分栏(列间 1 空格), 列宽取各列内容最大宽,
+//每组列数按终端宽度自适应, 无数据单列 - 占位); worker 增删不体现在 bar/计数器行上, 这里只维护 busyWorkers 计数 running 与
+//workerStatuses 状态表(__workerStatus 消息更新, worker 退出删条目)。
+const progressView = require('./progressView');
+
+let RENDER_INTERVAL = 100;//渲染节流: 高频小任务场景避免每次事件都 readdirSync(getFinalStats) 造成 O(N²) 盘扫
+let STATS_CACHE_MS = 1000;//盘上统计缓存 TTL: doRender 每帧 getStats(3 次 readdirSync), 高频小任务下 O(N) 盘扫放大;
+//计数器行允许秒级滞后(完成数按盘上结果目录统计的口径不变), finish 收尾绕过缓存始终取最新
+
+let view = null;//progressView 渲染器实例, 未开启为 null
+let progressOn = false;//progressBar 且 stdout 为 TTY 时为真(非 TTY 回退普通日志)
+let busyWorkers = {};//worker.id -> subid, master 端忙碌表
+let workerStatuses = {};//worker.id -> {elu, cpu, rss, heapUsed}, worker 周期自报(__workerStatus 消息)的状态表
+let statusEnabled = false;//worker_status_poll_ms 缺省(默认 2000)或 >0 时为真; <=0 整个特性关闭(帧不带状态行)
+let getStats = null;//() => TaskMgr.getFinalStats(), setup 注入
+let getRemaining = null;//() => new 目录任务数, setup 注入
+let lastRenderAt = 0;
+let renderTimer = null;
+let resizeStream = null;//resize 监听挂载的 stream, reset 时摘除防累积
+let resizeListener = null;
+let outStream = null;//渲染目标 stream, 供列宽变化检测(resize 事件缺失的终端靠它轮询)
+let lastCols = 0;//上一帧使用的列宽, 0 = 尚未渲染
+let resizeSettleTimer = null;
+let lastExtraLineCount = 0;//上一帧状态区行数: 组数变化(帧行数变)时先 reanchor 抹除旧帧再重写, 原地重绘必错位
+let statsCache = null;//盘上统计缓存(TTL 见 STATS_CACHE_MS), reset 时清空
+let statsCachedAt = 0;
+
+const RESIZE_SETTLE = 200;//列宽变化防抖: 拖动窗口会连续变化, 等稳定再重锚定重绘一次(防连续重锚定刷屏)
+const MAX_COLS_PER_GROUP = 7;//每组列数上限(用户拍板): 列再多表也读不过来, 超出的分多组堆叠
+
+const currentCols = () => {
+  return (outStream && outStream.columns) || 80;
+};
+
+const reset = () => {//master start 入口/同进程再跑一轮时调用: 清掉上一轮全部残留(含未发的节流帧)
+  if (renderTimer) {
+    clearTimeout(renderTimer);
+    renderTimer = null;
+  };
+  if (resizeSettleTimer) {
+    clearTimeout(resizeSettleTimer);
+    resizeSettleTimer = null;
+  };
+  if (resizeStream && resizeListener) {
+    resizeStream.removeListener('resize', resizeListener);
+  };
+  resizeStream = null;
+  resizeListener = null;
+  outStream = null;
+  lastCols = 0;
+  lastExtraLineCount = 0;
+  view = null;
+  progressOn = false;
+  busyWorkers = {};
+  workerStatuses = {};
+  statusEnabled = false;
+  lastRenderAt = 0;
+  statsCache = null;
+  statsCachedAt = 0;
+};
+
+//开启判定 + 初始化: 返回是否真正开启(显式 progressBar:false 关闭, 缺省默认开启;
+//非 TTY 一律回退普通日志, 仅显式 true 时打回退警告, 默认开启静默回退)
+const setup = ({ config, stream, getStats: statsFn, getRemaining: remainingFn }) => {
+  reset();
+  if (config.progressBar === false) {
+    return false;
+  };
+  if (!stream.isTTY) {//ANSI 控制码写进重定向输出是垃圾: 回退为现有控制台日志
+    if (config.progressBar === true) {
+      console.warn('[Master]: progressBar needs a TTY stdout, fallback to console logs');
+    };
+    return false;
+  };
+  progressOn = true;
+  getStats = statsFn;
+  getRemaining = remainingFn;
+  //状态行开关与 worker 侧探针同口径: 缺省即开(默认间隔 2000ms), 显式 <=0 或 false 关闭, true 等价缺省;
+  //开启期间每帧都带状态表(无数据用占位)
+  let statusInterval = config.worker_status_poll_ms;
+  statusEnabled = (typeof statusInterval === 'undefined' || statusInterval === true) ? true : statusInterval > 0;
+  view = progressView.create({ stream });//N 行帧进度区: bar 行固定 36 列(见 progressView)
+  outStream = stream;
+  if (typeof stream.on === 'function') {//resize 事件仅作加速路径: 真正的检测在 render 时比对列宽(事件缺失的终端也自愈)
+    resizeStream = stream;
+    resizeListener = () => {
+      if (view) {
+        scheduleResizeSettle();
+      };
+    };
+    stream.on('resize', resizeListener);
+  };
+  return true;
+};
+
+const isOn = () => {
+  return progressOn;
+};
+
+const fmtMem = (bytes) => {//内存自适应单位(用户拍板): <1G 整数 MB(256M), >=1G 一位小数 GB(1.5G)
+  const mb = bytes / 1048576;
+  return mb >= 1024 ? `${(mb / 1024).toFixed(1)}G` : `${Math.round(mb)}M`;
+};
+
+const buildStatusLines = () => {//状态区是 ASCII 表, 每组 6 行(id 表头/分隔横线/elu/cpu/rss/heap):
+  //压缩拍板——去顶/底框、去列间隔符(纯空格分栏), 表头与数据间横线保留(连续虚线), 行尾空格 trim;
+  //每列宽取该列 id/elu/cpu/rss/heap 五格内容的最大宽, 最大数字(100%/1.5G)与长 worker id(#10/#100)都不会错位; 按数字 id 排序;
+  //每组列数按终端宽度自适应且封顶 MAX_COLS_PER_GROUP(用户拍板): 行预算 (cols-1) 减 label 段后每列占 列宽+1 字符(列间 1 空格, 用户拍板),
+  //能放几列放几列(保底 1 列)——宽终端少分组、帧行数大减(缓解帧行数超屏高), 窄终端少放列、不再把表截烂;
+  //超出分多组整组堆叠(组数变 = 帧行数变, doRender 检测后走 reanchor 抹除重绘, 不原地错位重绘);
+  //无数据时单列 '-' 占位表(行数恒定: 开即每帧至少一组 6 行)
+  let ids = Object.keys(workerStatuses).sort((a, b) => a - b);
+  let cells = ids.map((id) => ({
+    id: `#${id}`,
+    elu: `${Math.round(workerStatuses[id].elu * 100)}%`,
+    cpu: `${Math.round(workerStatuses[id].cpu)}%`,
+    rss: fmtMem(workerStatuses[id].rss),
+    heap: fmtMem(workerStatuses[id].heapUsed),
+  }));
+  if (cells.length === 0) {
+    cells = [{ id: '-', elu: '-', cpu: '-', rss: '-', heap: '-' }];
+  };
+  let labels = ['id', 'elu', 'cpu', 'rss', 'heap'];
+  let labelWidth = Math.max(...labels.map((s) => s.length));
+  let colWidths = cells.map((cell) => Math.max(cell.id.length, cell.elu.length, cell.cpu.length, cell.rss.length, cell.heap.length));
+  //按全局最大列宽定每组列数: 任一组行宽 = labelWidth+1 + Σ(w+1) <= labelWidth+1 + colsPerGroup*(maxCellWidth+1) <= cols-1, 恒不超宽
+  let maxCellWidth = Math.max(...colWidths);
+  //终端宽度自适应 + 封顶 MAX_COLS_PER_GROUP(用户拍板): 宽终端少分组, 窄终端少放列不截烂表, 保底 1 列
+  let colsPerGroup = Math.min(MAX_COLS_PER_GROUP, Math.max(1, Math.floor((currentCols() - 1 - (labelWidth + 1)) / (maxCellWidth + 1))));
+  let lines = [];
+  for (let g = 0; g < cells.length; g += colsPerGroup) {
+    let group = cells.slice(g, g + colsPerGroup);
+    let groupWidths = colWidths.slice(g, g + colsPerGroup);
+    let cellText = (content, w) => ` ${content.padEnd(w)}`;//列间 1 空格(前导), padEnd 保列对齐, 行尾由 join 后 trimEnd 收掉
+    let divider = [labelWidth, ...groupWidths].map((w) => '-'.repeat(w + 1)).join('');
+    let line = (label, key) => {
+      return (cellText(label, labelWidth) + group.map((cell, c) => cellText(cell[key], groupWidths[c])).join('')).trimEnd();
+    };
+    lines.push(line('id', 'id'), divider, line('elu', 'elu'), line('cpu', 'cpu'), line('rss', 'rss'), line('heap', 'heap'));
+  };
+  return lines;
+};
+
+const readStats = () => {//TTL 内命中缓存: 帧渲染不重复扫盘; 过期重新取(finish 不走这里, 直接 getStats)
+  if (statsCache && (Date.now() - statsCachedAt) < STATS_CACHE_MS) {
+    return statsCache;
+  };
+  statsCache = getStats();
+  statsCachedAt = Date.now();
+  return statsCache;
+};
+
+const doRender = () => {
+  //完成数按盘上结果目录统计: 重试/超时/崩溃各种路径天然正确, 无需在协议里额外计数;
+  //failed/succ-but-save-failed 同源实时挂在行尾, 全程可见
+  let stats = readStats();
+  let done = stats.succeeded + stats.failed;
+  let running = Object.keys(busyWorkers).length;
+  lastRenderAt = Date.now();
+  lastCols = currentCols();
+  let data = { done, succ: stats.succeeded, running, remaining: getRemaining(), failed: stats.failed, succButSaveFailed: stats.succButSaveFailed || 0 };
+  if (statusEnabled) {
+    data.extraLines = buildStatusLines();
+    if (lastExtraLineCount > 0 && data.extraLines.length !== lastExtraLineCount) {
+      view.reanchor();//状态表组数变化(第 7/13... 个 worker 上报)致帧行数变: ESC[nA 按新行数算必错位, 抹除旧帧从锚点重写(同 resize 路径)
+    };
+    lastExtraLineCount = data.extraLines.length;
+  };
+  view.render(data);
+};
+
+const scheduleResizeSettle = () => {//列宽变化(事件或 render 时检测): 防抖等宽度稳定, 再重锚定 + 重绘一次
+  if (resizeSettleTimer) {
+    clearTimeout(resizeSettleTimer);
+  };
+  resizeSettleTimer = setTimeout(() => {
+    resizeSettleTimer = null;
+    if (view) {
+      view.reanchor();
+      doRender();
+    };
+  }, RESIZE_SETTLE);
+  resizeSettleTimer.unref();//不阻碍 master 退出
+};
+
+const colsChanged = () => {//列宽变了 = 旧帧已被终端重排, 占用行数不可信: 任何光标序列重绘必错位
+  return lastCols > 0 && currentCols() !== lastCols;
+};
+
+const render = () => {
+  if (!view) {
+    return;
+  };
+  if (colsChanged()) {//原地重绘必错位, 走防抖重锚定
+    scheduleResizeSettle();
+    return;
+  };
+  if (renderTimer) {
+    return;//已挂着一个尾随渲染, 合并掉中间帧
+  };
+  let wait = RENDER_INTERVAL - (Date.now() - lastRenderAt);
+  if (wait <= 0) {
+    doRender();
+    return;
+  };
+  renderTimer = setTimeout(() => {
+    renderTimer = null;
+    if (!view) {
+      return;
+    };
+    if (colsChanged()) {//拖动期间尾随帧触发: 用旧列宽光标序列重绘是满屏碎片根因, 转防抖重锚定
+      scheduleResizeSettle();
+      return;
+    };
+    doRender();
+  }, wait);
+  renderTimer.unref();//不阻碍 master 退出(最后一帧可能因进程退出丢失, 可接受)
+};
+
+const workerStarted = (id, pid) => {//两行进度区不展示 worker 行: 仅保留语义入口, 无渲染动作
+};
+
+const taskAssigned = (id, subid) => {
+  busyWorkers[id] = subid;
+  render();
+};
+
+const taskCompleted = (id) => {
+  if (busyWorkers[id]) {
+    delete busyWorkers[id];
+  };
+};
+
+const workerExited = (id) => {
+  delete busyWorkers[id];
+  delete workerStatuses[id];
+  render();
+};
+
+//worker 周期自报的状态(__workerStatus 消息): 畸形 payload 忽略不进表; 特性关闭时同样忽略(帧本就不带状态行)
+const workerStatus = (id, payload) => {
+  if (!statusEnabled) {
+    return;
+  };
+  if (!payload || typeof payload !== 'object') {
+    return;
+  };
+  let { elu, cpu, rss, heapUsed } = payload;
+  let nums = [elu, cpu, rss, heapUsed];
+  if (nums.some((n) => typeof n !== 'number' || !isFinite(n))) {
+    return;
+  };
+  workerStatuses[`${id}`] = { elu, cpu, rss, heapUsed };
+  render();
+};
+
+const finish = () => {//收尾: 换行定格进度条行 + 输出计数器行(master 退出前调用); 未开启为 no-op
+  if (resizeSettleTimer) {//收尾后不再重锚定重绘: 防抖帧会落在计数器行之后
+    clearTimeout(resizeSettleTimer);
+    resizeSettleTimer = null;
+  };
+  if (view) {
+    view.end();
+    if (getStats) {
+      let stats = getStats();
+      view.writeLine(`[Tasks] succeeded=${stats.succeeded}, failed=${stats.failed}, succ-but-save-failed=${stats.succButSaveFailed || 0}`);
+    };
+  };
+};
+
+module.exports = {
+  setup,
+  reset,
+  isOn,
+  render,
+  workerStarted,
+  taskAssigned,
+  taskCompleted,
+  workerExited,
+  workerStatus,
+  finish,
+};