@zzclub/pipeline 0.10.2 → 0.12.0

package/src/commands/wechat-export.ts

@@ -2,6 +2,8 @@ import { spawn } from "child_process";
 import { resolve } from "path";
 import { flagArg, optionalArg, parseArgs, requireArg } from "../args";
 import { printResult, renderWechatExport } from "../output";
+import { commandError, type CommandOutcome } from "../command-outcome";
+import { reportProgress } from "../monitor/recorder";
 import { loadConfig, resolveConfigRelativePath } from "../config";
 import { resolveMarkdownRenderer } from "../adapter-loader";
 import { WechatExportError } from "../wechat-preview";
@@ -54,7 +56,7 @@ async function openUrl(url: string): Promise<void> {
   }
 }
 
-export async function wechatExport(args: string[]): Promise<void> {
+export async function wechatExport(args: string[]): Promise<void | CommandOutcome> {
   const parsed = parseArgs(args);
 
   if (parsed.help) {
@@ -114,6 +116,7 @@ ${CSS_DEMO}
 
   try {
     const result = await markdownRenderer.render({
+      onProgress: reportProgress,
       markdownPath,
       outPath,
       account,
@@ -154,6 +157,7 @@ ${CSS_DEMO}
         if (open && preview_url) await openUrl(preview_url);
       } else {
         preview_register_error = reg.error;
+        console.warn(`微信预览登记失败：${reg.error || "未知原因"}`);
       }
     }
 
@@ -197,8 +201,7 @@ ${CSS_DEMO}
           renderWechatExport,
         );
         if (open && reg.preview_url) await openUrl(reg.preview_url);
-        process.exitCode = 1;
-        return;
+        return { status: "failed", errors: [commandError(error, error.kind)] };
       }
     }
     throw error;

package/src/config.ts

@@ -43,6 +43,15 @@ export interface ResolvedWorkspacePaths {
 
 const DEFAULT_WX_ACCOUNT_NAME = "default";
 
+/**
+ * Soft display names for known account keys when `name` is missing/empty.
+ * Never overrides a user-set name.
+ */
+export const SUGGESTED_ACCOUNT_NAMES: Record<string, string> = {
+  default: "大号（早早集市）",
+  ancientone: "小号（古一）",
+};
+
 export const DEFAULT_CONFIG: PipelineConfig = PipelineConfigSchema.parse({});
 
 const PIPELINE_CONFIG_DIR = "zzhub-pipeline";
@@ -104,8 +113,9 @@ export function getLegacyZCliConfigPath(): string {
 /**
  * Merge source config with legacy config, then normalize through Zod schema.
  * Legacy values fill gaps where source has nothing.
+ * Soft-fills known account display `name` only when missing/empty.
  */
-function normalizeConfig(value: unknown, legacyValue?: unknown): PipelineConfig {
+export function normalizeConfig(value: unknown, legacyValue?: unknown): PipelineConfig {
   const source = isPlainObject(value) ? value : {};
   const legacy = isPlainObject(legacyValue) ? legacyValue : {};
 
@@ -122,7 +132,16 @@ function normalizeConfig(value: unknown, legacyValue?: unknown): PipelineConfig
     if (!accountName) continue;
     const legacyAccount = isPlainObject(legacyAccounts[accountName]) ? legacyAccounts[accountName] : {};
     const sourceAccount = isPlainObject(sourceAccounts[accountName]) ? sourceAccounts[accountName] : {};
-    mergedAccounts[accountName] = { ...legacyAccount, ...sourceAccount };
+    const merged = { ...legacyAccount, ...sourceAccount };
+    // Trim + soft-fill display name for known keys only when missing/empty (never override user-set name).
+    if (typeof merged.name === "string") {
+      merged.name = merged.name.trim();
+    }
+    const existingName = typeof merged.name === "string" ? merged.name : "";
+    if (!existingName && SUGGESTED_ACCOUNT_NAMES[accountName]) {
+      merged.name = SUGGESTED_ACCOUNT_NAMES[accountName];
+    }
+    mergedAccounts[accountName] = merged;
   }
 
   // Merge wx config: source wins, legacy fills gaps

package/src/imgx/render-article.ts

@@ -29,6 +29,8 @@ import {
 } from "./runtime";
 import { layoutNextLineRange, prepareWithSegments } from "./pretext-adapter";
 import { ensurePretextRuntime } from "./pretext-runtime";
+import { notifyProgress } from "../monitor/recorder";
+import type { MonitorProgress } from "../monitor/types";
 
 const DEFAULT_CONTENT_WIDTH = getLongformGeometry(getLongformTheme("paper-sage")).contentWidth;
 
@@ -1170,7 +1172,8 @@ function renderPage(params: {
   });
 }
 
-export function runRenderArticleCli(argv: string[]): RenderArticleResult {
+export function runRenderArticleCli(argv: string[], onProgress?: (progress: MonitorProgress) => void): RenderArticleResult {
+  notifyProgress(onProgress, { stage: "render.layout", message: "正在计算分页" });
   const parsed = parseArgs(argv);
   const title = getArg(parsed, "title");
   if (title.length === 0) throw new Error("需要 --title");
@@ -1312,6 +1315,7 @@ export function runRenderArticleCli(argv: string[]): RenderArticleResult {
   };
 
   if (outPath.length > 0) {
+    notifyProgress(onProgress, { stage: "render.pages", current: 0, total: 1, unit: "pages" });
     const requestedPage = pageNum > 0 ? pageNum : 1;
     const page = pages[Math.max(0, Math.min(requestedPage - 1, pages.length - 1))]!;
     const total = pageTotal > 0 ? pageTotal : pages.length;
@@ -1328,6 +1332,7 @@ export function runRenderArticleCli(argv: string[]): RenderArticleResult {
       highlightWords,
     });
     printSaved(outPath);
+    notifyProgress(onProgress, { stage: "render.pages", current: 1, total: 1, unit: "pages" });
     return result;
   }
 
@@ -1336,6 +1341,7 @@ export function runRenderArticleCli(argv: string[]): RenderArticleResult {
     throw new Error("需要 --out (单页模式) 或 --out-dir (批量模式)");
   }
   for (let index = 0; index < pages.length; index++) {
+    notifyProgress(onProgress, { stage: "render.pages", message: `正在渲染第 ${index + 1} 页`, current: index, total: pages.length, unit: "pages" });
     const pageOut = join(outDir, `article-${String(index + 1).padStart(2, "0")}.png`);
     // DEBUG: dump layout coordinates
     const dbgPage = pages[index]!;
@@ -1355,6 +1361,7 @@ export function runRenderArticleCli(argv: string[]): RenderArticleResult {
       highlightWords,
     });
     printSaved(pageOut);
+    notifyProgress(onProgress, { stage: "render.pages", current: index + 1, total: pages.length, unit: "pages" });
   }
   return result;
 }

package/src/imgx/render-card.ts

@@ -19,6 +19,8 @@ import {
   screenshotHtml,
   TEMPLATES_DIR,
 } from "./runtime";
+import { notifyProgress } from "../monitor/recorder";
+import type { MonitorProgress } from "../monitor/types";
 
 const SIZE_MAP: Record<string, { width: number; height: number }> = {
   "poster-3-4": { width: 900, height: 1200 },
@@ -100,7 +102,8 @@ function splitWechatTitle(text: string): { line1: string; line2: string } {
   };
 }
 
-export function runRenderCardCli(argv: string[]): void {
+export function runRenderCardCli(argv: string[], onProgress?: (progress: MonitorProgress) => void): void {
+  notifyProgress(onProgress, { stage: "render.cover", message: "正在生成封面", current: 0, total: 1, unit: "pages" });
   const parsed = parseArgs(argv);
   const template = getArg(parsed, "template", "poster-3-4");
   const outPath = requireArg(parsed, "out");
@@ -209,6 +212,7 @@ export function runRenderCardCli(argv: string[]): void {
     });
     rmSync(rawPath, { force: true });
     printSaved(outPath);
+    notifyProgress(onProgress, { stage: "render.cover", current: 1, total: 1, unit: "pages" });
     return;
   }
 
@@ -221,6 +225,7 @@ export function runRenderCardCli(argv: string[]): void {
     virtualTimeBudgetMs: usesPretext ? PRETEXT_SCREENSHOT_VIRTUAL_TIME_BUDGET_MS : undefined,
   });
   printSaved(outPath);
+  notifyProgress(onProgress, { stage: "render.cover", current: 1, total: 1, unit: "pages" });
 }
 
 if (import.meta.main) {

package/src/imgx/runtime.ts

@@ -407,7 +407,7 @@ export function resolveInputPath(path: string): string {
 }
 
 export function printSaved(outPath: string): void {
-  console.log(`✅ Saved to ${outPath}`);
+  console.error(`✅ Saved to ${outPath}`);
 }
 
 export function readImageSize(path: string): { width: number; height: number } | null {

package/src/logger.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -6,9 +6,13 @@ import { getDailyLogPath, getLogDir, runWithCommandLog } from "./logger";
 
 describe("pipeline daily logger", () => {
   const previousLogDir = process.env.ZZHUB_PIPELINE_LOG_DIR;
+  const previousMonitor = process.env.ZZHUB_PIPELINE_MONITOR;
+  beforeEach(() => { process.env.ZZHUB_PIPELINE_MONITOR = "0"; });
   let tempDir: string | null = null;
 
   afterEach(() => {
+    if (previousMonitor === undefined) delete process.env.ZZHUB_PIPELINE_MONITOR;
+    else process.env.ZZHUB_PIPELINE_MONITOR = previousMonitor;
     if (previousLogDir === undefined) {
       delete process.env.ZZHUB_PIPELINE_LOG_DIR;
     } else {
@@ -20,6 +24,29 @@ describe("pipeline daily logger", () => {
     }
   });
 
+  test("logs returned business failures as FAIL without throwing or exiting the host", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "zzhub-pipeline-log-"));
+    process.env.ZZHUB_PIPELINE_LOG_DIR = tempDir;
+    const outcome = await runWithCommandLog("publish", [], async () => ({ status: "failed", errors: [{ code: "PUBLISH_FAILED", message: "upload failed" }] }));
+    expect(outcome.status).toBe("failed");
+    expect(readFileSync(getDailyLogPath(), "utf8")).toContain("=== FAIL command=publish");
+  });
+
+  test("an explicit nonzero exit code cannot be logged as success", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "zzhub-pipeline-log-"));
+    process.env.ZZHUB_PIPELINE_LOG_DIR = tempDir;
+    // Bun 需要显式恢复 0；写回 undefined 不会清除已经设置的退出码。
+    const previousCode = process.exitCode ?? 0;
+    try {
+      const outcome = await runWithCommandLog("legacy", [], async () => {
+        process.exitCode = 1;
+        return { status: "success" };
+      });
+      expect(outcome.status).toBe("failed");
+      expect(readFileSync(getDailyLogPath(), "utf8")).toContain("=== FAIL command=legacy");
+    } finally { process.exitCode = previousCode; }
+  });
+
   test("writes command start/ok markers and console output to the daily log", async () => {
     tempDir = mkdtempSync(join(tmpdir(), "zzhub-pipeline-log-"));
     process.env.ZZHUB_PIPELINE_LOG_DIR = tempDir;

package/src/logger.ts

@@ -12,6 +12,8 @@
 import { appendFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
+import { outcomeExitCode, type CommandOutcome } from "./command-outcome";
+import { observeCommand, reportLog } from "./monitor/recorder";
 
 const APP_DIR = "zzhub-pipeline";
 const LOG_DIR_NAME = "logs";
@@ -118,6 +120,7 @@ function installConsoleTee(write: (chunk: string) => void): () => void {
         const text = args
           .map((arg) => {
             if (typeof arg === "string") return arg;
+            if (arg instanceof Error) return formatError(arg);
             try {
               return JSON.stringify(arg);
             } catch {
@@ -126,6 +129,8 @@ function installConsoleTee(write: (chunk: string) => void): () => void {
           })
           .join(" ");
         write(`[console.${method}] ${text}`);
+        // stdout 包含完整业务 JSON；只采集诊断通道，避免正文或配置进入监控。
+        if (method !== "log") reportLog(method, text);
       } catch {
         // ignore
       }
@@ -147,32 +152,40 @@ function installConsoleTee(write: (chunk: string) => void): () => void {
 export async function runWithCommandLog(
   command: string,
   args: string[],
-  handler: () => Promise<void>,
-): Promise<void> {
-  const startedAt = new Date();
-  const startedMs = Date.now();
-  const logPath = getDailyLogPath(startedAt);
-  const write = (message: string) => {
-    appendLogLine(`[${new Date().toISOString()}] ${message}`, startedAt);
-  };
+  handler: () => Promise<void | CommandOutcome>,
+): Promise<CommandOutcome> {
+  return observeCommand(command, async () => {
+    const startedAt = new Date();
+    const startedMs = Date.now();
+    const logPath = getDailyLogPath(startedAt);
+    const write = (message: string) => {
+      appendLogLine(`[${new Date().toISOString()}] ${message}`, startedAt);
+    };
 
-  write(`=== START command=${command} ===`);
-  write(`log_file=${logPath}`);
-  write(`cwd=${process.cwd()}`);
-  write(`argv=${JSON.stringify(args)}`);
-  if (process.env.ZZHUB_PIPELINE_ROOT) {
-    write(`ZZHUB_PIPELINE_ROOT=${process.env.ZZHUB_PIPELINE_ROOT}`);
-  }
+    write(`=== START command=${command} ===`);
+    write(`log_file=${logPath}`);
+    write(`cwd=${process.cwd()}`);
+    write(`argv=${JSON.stringify(args)}`);
+    if (process.env.ZZHUB_PIPELINE_ROOT) {
+      write(`ZZHUB_PIPELINE_ROOT=${process.env.ZZHUB_PIPELINE_ROOT}`);
+    }
 
-  const restoreConsole = installConsoleTee(write);
-  try {
-    await handler();
-    write(`=== OK command=${command} duration_ms=${Date.now() - startedMs} ===`);
-  } catch (err) {
-    write(`=== FAIL command=${command} duration_ms=${Date.now() - startedMs} ===`);
-    write(formatError(err));
-    throw err;
-  } finally {
-    restoreConsole();
-  }
+    const restoreConsole = installConsoleTee(write);
+    try {
+      let outcome: CommandOutcome = await handler() ?? { status: "success" };
+      if (Number(process.exitCode || 0) !== 0 && !outcomeExitCode(outcome)) {
+        outcome = { status: "failed", errors: [{ code: "PROCESS_EXIT", message: `进程退出：${process.exitCode}` }] };
+      }
+      const label = outcomeExitCode(outcome) ? "FAIL" : outcome.status === "success" ? "OK" : outcome.status.toUpperCase();
+      write(`=== ${label} command=${command} duration_ms=${Date.now() - startedMs} ===`);
+      for (const error of outcome.errors ?? []) write(`${error.code}: ${error.message}${error.cause ? `\n${error.cause}` : ""}`);
+      return outcome;
+    } catch (err) {
+      write(`=== FAIL command=${command} duration_ms=${Date.now() - startedMs} ===`);
+      write(formatError(err));
+      throw err;
+    } finally {
+      restoreConsole();
+    }
+  });
 }

package/src/monitor/client.ts

@@ -0,0 +1,60 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { PACKAGE_ROOT } from "../runtime-paths";
+import { resolveBunBinary } from "../spawn";
+import { monitorDir } from "./runtime";
+import type { MonitorDescriptor } from "./types";
+
+/** 本机描述文件严格限制协议和地址，不能借其访问远程服务。 */
+export function readMonitorDescriptor(root = monitorDir()): MonitorDescriptor | null {
+  try {
+    const descriptor = JSON.parse(readFileSync(join(root, "server.json"), "utf8")) as MonitorDescriptor;
+    const url = new URL(descriptor.url);
+    if (descriptor.version !== 1 || url.protocol !== "http:" || url.hostname !== "127.0.0.1"
+      || !url.port || url.username || url.password || !/^[0-9a-f]{64}$/.test(descriptor.token)
+      || typeof descriptor.instance_id !== "string" || !Number.isSafeInteger(descriptor.pid)) return null;
+    return descriptor;
+  } catch { return null; }
+}
+
+export async function monitorHealth(descriptor: MonitorDescriptor): Promise<boolean> {
+  try {
+    const response = await fetch(`${descriptor.url}/v1/health`, {
+      headers: { Authorization: `Bearer ${descriptor.token}` }, signal: AbortSignal.timeout(500),
+    });
+    const health = await response.json() as { service?: string; instance_id?: string; ready?: boolean };
+    return response.ok && health.service === "zzhub-pipeline-monitor" && health.instance_id === descriptor.instance_id && health.ready === true;
+  } catch { return false; }
+}
+
+/** 只有显式 monitor start 才拉起进程，普通业务命令永不等待服务。 */
+export async function startMonitor(): Promise<MonitorDescriptor> {
+  const existing = readMonitorDescriptor();
+  if (existing && await monitorHealth(existing)) return existing;
+  mkdirSync(monitorDir(), { recursive: true, mode: 0o700 });
+  const child = spawn(resolveBunBinary(), [resolve(PACKAGE_ROOT, "src/cli.ts"), "monitor", "serve"], {
+    detached: true, stdio: "ignore", env: { ...process.env, ZZHUB_PIPELINE_MONITOR: "0" },
+  });
+  let spawnError: Error | null = null;
+  child.on("error", (error) => { spawnError = error; });
+  child.unref();
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    if (spawnError) throw spawnError;
+    const descriptor = readMonitorDescriptor();
+    if (descriptor && await monitorHealth(descriptor)) return descriptor;
+    await new Promise((done) => setTimeout(done, 100));
+  }
+  throw new Error("监控服务启动超时；可运行 zzp monitor serve 查看错误。");
+}
+
+export async function stopMonitor(): Promise<boolean> {
+  const descriptor = readMonitorDescriptor();
+  if (!descriptor || !await monitorHealth(descriptor)) return false;
+  const response = await fetch(`${descriptor.url}/v1/stop`, {
+    method: "POST", headers: { Authorization: `Bearer ${descriptor.token}` }, signal: AbortSignal.timeout(2000),
+  });
+  if (!response.ok) throw new Error(`停止监控失败：HTTP ${response.status}`);
+  return true;
+}

package/src/monitor/recorder.ts

@@ -0,0 +1,142 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { commandError, outcomeExitCode, type CommandOutcome } from "../command-outcome";
+import type { WorkflowState } from "../state";
+import { canonicalPath, LOG_LIMIT, monitorDir, processIdentity, redact, taskId } from "./runtime";
+import type { MonitorEvent, MonitorProgress } from "./types";
+
+interface Recording {
+  id: string;
+  file: string;
+  seq: number;
+  disabled: boolean;
+  logBytes: number;
+  truncated: boolean;
+  lastProgressAt: number;
+  progressKey: string;
+  progressRoute?: string;
+  progressAccount?: string;
+  ended?: boolean;
+  tasks: Set<string>;
+}
+
+/** 调用上下文自动穿过内置异步流程，不要求业务函数传监控对象。 */
+const recording = new AsyncLocalStorage<Recording>();
+const queryCommands = new Set(["status", "tasks", "find-run", "checkpoint", "doctor", "config", "wx-drafts", "hermes-metrics"]);
+
+function emit(type: MonitorEvent["type"], data: Record<string, unknown>): void {
+  const current = recording.getStore();
+  if (!current || current.disabled || current.ended) return;
+  try {
+    const event: MonitorEvent = { version: 1, execution_id: current.id, seq: ++current.seq, at: new Date().toISOString(), type, data };
+    appendFileSync(current.file, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600 });
+  } catch {
+    // 只停用本次记录，不重试、不递归写日志，也不影响业务结果。
+    current.disabled = true;
+  }
+}
+
+export function reportLog(level: string, message: string): void {
+  const current = recording.getStore();
+  if (!current || current.disabled || current.truncated) return;
+  try {
+    const safe = redact(message);
+    current.logBytes += Buffer.byteLength(safe, "utf8");
+    if (current.logBytes > LOG_LIMIT) {
+      current.truncated = true;
+      emit("log", { level: "warn", message: "普通日志达到 10MB 上限，后续日志已截断；进度、错误和终态仍记录。", truncated: true });
+      return;
+    }
+    emit("log", { level, message: safe });
+  } catch { /* 日志不得影响调用。 */ }
+}
+
+export function reportProgress(progress: MonitorProgress): void {
+  const current = recording.getStore();
+  if (!current || current.disabled) return;
+  try {
+    current.progressRoute = progress.route ?? current.progressRoute;
+    current.progressAccount = progress.account ?? current.progressAccount;
+    const key = `${progress.stage}:${current.progressRoute || ""}:${current.progressAccount || ""}`;
+    const complete = progress.total !== undefined && progress.current === progress.total;
+    if (key === current.progressKey && !complete && Date.now() - current.lastProgressAt < 200) return;
+    current.progressKey = key;
+    current.lastProgressAt = Date.now();
+    emit("progress", {
+      stage: redact(progress.stage),
+      ...(progress.message ? { message: redact(progress.message) } : {}),
+      ...(Number.isFinite(progress.current) && progress.current! >= 0 ? { current: progress.current } : {}),
+      ...(Number.isFinite(progress.total) && progress.total! >= 0 ? { total: progress.total } : {}),
+      ...(progress.unit ? { unit: progress.unit } : {}),
+      ...(current.progressRoute ? { route: redact(current.progressRoute) } : {}),
+      ...(current.progressAccount ? { account: redact(current.progressAccount) } : {}),
+    });
+  } catch { /* 进度采集不得改变业务路径。 */ }
+}
+
+/** 插件进度回调失败不能让已经执行的渲染失败。 */
+export function notifyProgress(callback: ((progress: MonitorProgress) => void) | undefined, progress: MonitorProgress): void {
+  try { (callback || reportProgress)(progress); } catch { /* 可选观测回调失败时继续执行。 */ }
+}
+
+/** 只记录身份和状态引用，正文和业务配置不进入事件文件。 */
+export function observeState(state: WorkflowState, path: string): void {
+  const current = recording.getStore();
+  if (!current || current.disabled || !state.run_id || !state.workspace_root) return;
+  try {
+    const workspace = canonicalPath(state.workspace_root);
+    const id = taskId(workspace, state.run_id);
+    const key = `${id}:${path}:${state.updated_at}`;
+    if (current.tasks.has(key)) return;
+    current.tasks.add(key);
+    emit("task", { id, workspace, run_id: state.run_id, state_path: canonicalPath(path), title: redact(state.metadata.title) || null });
+  } catch { /* 状态落盘不依赖观测成功。 */ }
+}
+
+function safeOutcome(outcome: CommandOutcome): CommandOutcome {
+  return {
+    status: outcome.status,
+    errors: outcome.errors?.map((error) => ({
+      code: redact(error.code), message: redact(error.message),
+      ...(error.stage ? { stage: redact(error.stage) } : {}),
+      ...(error.route ? { route: redact(error.route) } : {}),
+      ...(error.account ? { account: redact(error.account) } : {}),
+      ...(error.cause ? { cause: redact(error.cause) } : {}),
+    })),
+  };
+}
+
+/** 服务未运行时也独立记录；强制退出仅尽力补充终态。 */
+export async function observeCommand(command: string, handler: () => Promise<CommandOutcome>): Promise<CommandOutcome> {
+  if (process.env.ZZHUB_PIPELINE_MONITOR === "0") return handler();
+  let context: Recording;
+  try {
+    const dir = join(monitorDir(), "events");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const id = crypto.randomUUID();
+    context = { id, file: join(dir, `${id}.jsonl`), seq: 0, disabled: false, logBytes: 0, truncated: false, lastProgressAt: 0, progressKey: "", tasks: new Set() };
+  } catch { return handler(); }
+
+  return recording.run(context, async () => {
+    emit("started", { command, pid: process.pid, process_identity: processIdentity(process.pid), is_query: queryCommands.has(command) });
+    const finish = (outcome: CommandOutcome, exitCode = outcomeExitCode(outcome)) => {
+      try { emit("finished", { outcome: safeOutcome(outcome), exit_code: exitCode }); } catch { /* 尽力记录终态。 */ }
+      context.ended = true;
+    };
+    const onExit = (code: number) => recording.run(context, () => finish(
+      code === 0 ? { status: "success" } : { status: "failed", errors: [{ code: "PROCESS_EXIT", message: `进程退出：${code}` }] }, code,
+    ));
+    process.once("exit", onExit);
+    try {
+      const outcome = await handler();
+      finish(outcome);
+      return outcome;
+    } catch (error) {
+      finish({ status: "failed", errors: [commandError(error)] });
+      throw error;
+    } finally {
+      process.removeListener("exit", onExit);
+    }
+  });
+}

package/src/monitor/runtime.ts

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const LOG_LIMIT = 10 * 1024 * 1024;
+export const RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+export const STORAGE_LIMIT = 512 * 1024 * 1024;
+
+/** 独立于业务配置文件，保证同一用户的多个工作区共享监控。 */
+export function monitorDir(): string {
+  if (process.env.ZZHUB_PIPELINE_MONITOR_DIR) return resolve(process.env.ZZHUB_PIPELINE_MONITOR_DIR);
+  const base = platform() === "darwin" ? join(homedir(), "Library", "Application Support")
+    : platform() === "win32" ? process.env.APPDATA || join(homedir(), "AppData", "Roaming")
+      : process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "zzhub-pipeline", "monitor");
+}
+
+export function canonicalPath(path: string): string {
+  try { return realpathSync(path); } catch { return resolve(path); }
+}
+
+export function taskId(workspace: string, runId: string): string {
+  return createHash("sha256").update(`${canonicalPath(workspace)}\n${runId}`).digest("hex");
+}
+
+/** 过滤常见凭据和正文参数；监控从不采集完整 argv、环境或结果正文。 */
+export function redact(value: string): string {
+  return value
+    .replace(/Bearer\s+[^\s"',}]+/gi, "Bearer [redacted]")
+    .replace(/((?:[?&]|["']?)(?:access[_-]?token|refresh[_-]?token|token|pat|password|secret(?:key)?|appsecret|authorization|cookie)["']?\s*[:=]\s*)["']?[^\s"'&,}\r\n]+["']?/gi, "$1[redacted]")
+    .replace(/(--(?:pat|token|password|secret|body-text|text|intent-text)(?:=|\s+))(?:"[^"]*"|'[^']*'|\S+)/gi, "$1[redacted]")
+    .slice(0, 4096);
+}
+
+/** PID 加系统启动指纹，避免 PID 复用造成错误的运行中判断。 */
+export function processIdentity(pid: number): string | null {
+  try {
+    if (platform() === "linux") {
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+      return `${readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19]}`;
+    }
+    if (platform() === "darwin") {
+      const result = spawnSync("/bin/ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf8", timeout: 1000 });
+      return result.status === 0 ? result.stdout.trim() || null : null;
+    }
+  } catch { /* 身份查询失败不影响 CLI。 */ }
+  return null;
+}
+
+export function processStatus(pid: number, identity: string | null): "running" | "interrupted" | "unknown" {
+  try { process.kill(pid, 0); } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ESRCH" ? "interrupted" : "unknown";
+  }
+  const current = processIdentity(pid);
+  return identity && current ? (identity === current ? "running" : "interrupted") : "unknown";
+}