@zhushanwen/subagent-core 0.2.0

package/src/execution/agent-registry.ts

@@ -0,0 +1,199 @@
+// src/execution/agent-registry.ts
+//
+// agent .md 文件发现与解析。
+//
+// 发现逻辑统一走 shared/resource-discovery（ADR-031），与 workflow 共享同一套
+// 扫描源前缀 + manifest 校验。hot-reload：每次调用重扫（mtime 缓存跳过未变文件）。
+//
+// builtin agent（包内 agents/*.md）走 pi.agents manifest（与 npm 包内发现规则一致）。
+
+
+import * as path from "node:path";
+
+import { getLogger } from "../core/logger.ts";
+
+import {
+  getCachedFile,
+} from "../shared/resource-discovery.ts";
+import { normalizeRef, AGENT_REF_EXT } from "../shared/agent-ref.ts";
+import { parseResourceMeta } from "../shared/meta-parser.ts";
+import { lintAgentMeta } from "../orchestration/script-lint.ts";
+import type { AgentMeta } from "../shared/resource-meta.ts";
+import type { AgentConfig } from "./model-resolver.ts";
+import { hasEngine, listEngines, EngineNotFoundError } from "./engine/registry.ts";
+
+const logger = getLogger("subagents");
+
+/** mtime 缓存条目（跨 loadByPath 保留，靠 mtime 判失效）。 */
+interface FileCacheEntry {
+  mtimeMs: number;
+  config: AgentConfig;
+  /** AgentMeta（W4 lint 用——cache-miss 时 lint 一次，warn 随 mtime 变化刷）。 */
+  meta: AgentMeta | null;
+}
+
+// ============================================================
+// frontmatter 解析
+// ============================================================
+
+/** frontmatter 分隔符。 */
+const FM_DELIM = "---";
+
+/**
+ * 解析 .md frontmatter（name/tools/model/thinkingLevel/defaultBackground）+ body（systemPrompt）。
+ * 兼容简单 YAML（key: value 单行格式）。body 作为 systemPrompt。
+ */
+export function parseAgentFrontmatter(filePath: string, content: string): AgentConfig {
+  return parseAgentWithMeta(filePath, content).config;
+}
+
+/**
+ * 解析 agent .md → { config, meta } 二元组（m5 T2：W4 lint 需要 AgentMeta——
+ * AgentConfig 投影时 examples 被丢弃，meta 供 lintAgentMeta 使用）。
+ */
+export function parseAgentWithMeta(
+  filePath: string,
+  content: string,
+): { config: AgentConfig; meta: AgentMeta | null } {
+  const name = path.basename(filePath, ".md");
+
+  // 无 frontmatter → 整个内容作为 systemPrompt
+  if (!content.startsWith(FM_DELIM)) {
+    return { config: { name, systemPrompt: content.trim() }, meta: null };
+  }
+
+  const closeIdx = content.indexOf(FM_DELIM, FM_DELIM.length);
+  if (closeIdx === -1) {
+    // 未闭合 frontmatter：提取 name，其余作为 systemPrompt
+    const yamlBlock = content.slice(FM_DELIM.length);
+    return {
+      config: {
+        name: extractYamlField(yamlBlock, "name") ?? name,
+        systemPrompt: content.trim(),
+      },
+      meta: null,
+    };
+  }
+
+  const yamlBlock = content.slice(FM_DELIM.length, closeIdx);
+  const body = content.slice(closeIdx + FM_DELIM.length).trim();
+
+  // m2：结构化路由字段（name/model/tools）经 IF1 parseResourceMeta（统一 parser），
+  // 消灭本地 frontmatter parser 与 subagent-list-injector 的重复。thinkingLevel/defaultBackground
+  // 是执行配置（非 AgentMeta 路由字段），仍用 extractYamlField 取。
+  const meta = parseResourceMeta(content, "agent");
+  const agentMeta = meta?.kind === "agent" ? meta : null;
+  // MF-3 regression fix：agentMeta=null（IF1 要求 name/description 必填，缺则 parseResourceMeta
+  // 返 null）时，model/tools 不能静默丢失——fallback 用 extractYamlField 取（保留重构前行为）。
+  // 注入路由可见性由 discovery/injector 按 available 标志决定，与本处（direct-path loadByPath）无关。
+  const modelFallback = extractYamlField(yamlBlock, "model");
+  const toolsFallbackRaw = extractYamlField(yamlBlock, "tools");
+  const toolsFallback = toolsFallbackRaw
+    ? toolsFallbackRaw.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
+  if (!agentMeta && /^model:|^tools:/m.test(yamlBlock)) {
+    // m2 exec-review MINOR-2 + MF-3：IF1 未通过（缺 name/description）→ model/tools 经 legacy
+    // fallback 取（direct-path loadByPath 不丢配置，与重构前一致）；但结构化路由注入不可见，
+    // 建议 agent 作者补 description 以满足 IF1。
+    logger.warn(
+      `[agent-registry] ${filePath}: agent frontmatter 缺 name/description（IF1 必填），` +
+        "model/tools 经 legacy fallback 生效（直接路径不丢配置），但结构化路由不可见——请补充 description",
+    );
+  }
+  const defaultBackgroundRaw = extractYamlField(yamlBlock, "defaultBackground");
+  // engine 字段（D9）：结构化优先（IF1），legacy fallback 与 model/tools 同判——
+  // agentMeta 未通过 IF1 时配置不丢
+  const engine = agentMeta?.engine ?? extractYamlField(yamlBlock, "engine");
+  // 解析期校验（D9：未注册 id 前置暴露，不留到运行时神秘失败）。为什么在解析期而非
+  // 路由期：配置错误的根源在 .md 文件，越早报错定位越准（错误含文件路径 + 注册清单）
+  if (engine !== undefined && !hasEngine(engine)) {
+    throw new EngineNotFoundError(engine, listEngines(), filePath);
+  }
+
+  return {
+    config: {
+      name: agentMeta?.name ?? name,
+      systemPrompt: body,
+      model: agentMeta?.model ?? modelFallback ?? undefined,
+      thinkingLevel: extractYamlField(yamlBlock, "thinkingLevel") ?? undefined,
+      ...(engine !== undefined ? { engine } : {}),
+      tools: agentMeta?.tools && agentMeta.tools.length > 0
+        ? agentMeta.tools
+        : (toolsFallback && toolsFallback.length > 0 ? toolsFallback : undefined),
+      defaultBackground: defaultBackgroundRaw === "true" ? true : undefined,
+    },
+    meta: agentMeta,
+  };
+}
+
+/** 提取简单 `key: value` 字段，剥离引号。 */
+function extractYamlField(yaml: string, key: string): string | undefined {
+  const regex = new RegExp(`^${key}:\\s*(.+)$`, "m");
+  const match = yaml.match(regex);
+  if (!match) return undefined;
+  let value = match[1].trim();
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1);
+  }
+  return value || undefined;
+}
+
+// ============================================================
+// AgentRegistry
+// ============================================================
+
+export class AgentRegistry {
+  /** 文件级 mtime 缓存（key=绝对路径，跨 loadByPath 保留）。 */
+  private readonly fileCache = new Map<string, FileCacheEntry>();
+
+  /**
+   * 按绝对路径加载 agent（agentRef 统一解析入口——S2 路径统一）。
+   *
+   * - ~/ 前缀展开；相对路径/非 .md 引用返回 undefined（引用唯一形态 = 绝对路径）
+   * - 文件不可读/不存在 → 驱逐缓存 + 返回 undefined（调用方给错误指引）
+   * - mtime 未变复用 config 缓存；cache-miss 时 W4 lint 一次
+   *
+   * require 语义：require:true 时上述两类失败改为 throw（错误文案含
+   * <available_subagents> 恢复指引），供「用户显式点名 agent」的调用点使用——
+   * 显式 ref 失败是配置错误，必须显式报错而非静默降级（三通道对称审查）。
+   */
+  loadByPath(ref: string, require: true): AgentConfig;
+  loadByPath(ref: string, require?: boolean): AgentConfig | undefined;
+  loadByPath(ref: string, require?: boolean): AgentConfig | undefined {
+    const filePath = normalizeRef(ref, AGENT_REF_EXT);
+    if (filePath === null) {
+      if (require) {
+        throw new Error(
+          `Invalid agent ref: ${ref}. Agent refs must be absolute paths to .md files (use <location> from <available_subagents>).`,
+        );
+      }
+      return undefined;
+    }
+
+    const file = getCachedFile(filePath);
+    if (file === null) {
+      // ENOENT/不可读 → 驱逐（mtime 缓存下文件删除不自愈的修复）
+      this.fileCache.delete(filePath);
+      if (require) {
+        throw new Error(
+          `Agent file not found or unreadable: ${filePath}. Use an absolute path from <available_subagents> <location>.`,
+        );
+      }
+      return undefined;
+    }
+
+    const cached = this.fileCache.get(filePath);
+    if (cached && cached.mtimeMs === file.mtimeMs) {
+      return cached.config;
+    }
+
+    const { config, meta } = parseAgentWithMeta(filePath, file.content);
+    // W4 lint：cache-miss（parse 时一次）——warn 只随 mtime 变化刷
+    const lintFindings = meta ? lintAgentMeta(meta) : [];
+    for (const finding of lintFindings) {
+      logger.warn(`[agent-registry] ${filePath}: ${finding.message}`);
+    }
+    this.fileCache.set(filePath, { mtimeMs: file.mtimeMs, config, meta });
+    return config;
+  }
+}

package/src/execution/agent-result-mapper.ts

@@ -0,0 +1,90 @@
+// src/execution/agent-result-mapper.ts
+//
+// D-A10: subagents AgentResult → workflow AgentResult 映射。
+// 纯 DTO 映射函数——executeAndAwait 出口调，SAR 不感知形状差异。
+//
+// 接线层级：[模块内直调] —— SubagentService.executeAndAwait 出口调。
+
+import type { AgentResult as WorkflowAgentResult, AgentUsage as WorkflowAgentUsage, ToolCallEntry } from "../orchestration/models/types.ts";
+import type { AgentResult as SubagentsAgentResult, AgentUsageTotal, ToolCall } from "./types.ts";
+
+/** safeStringify 的 JSON 截断长度（字符），防大对象拼进 toolCalls 挤爆 trace。 */
+const TOOL_ARGS_JSON_MAX_CHARS = 500;
+
+/**
+ * D-A10: subagents AgentResult → workflow AgentResult 映射。
+ *
+ * 字段映射表：
+ *   subagents                         → workflow
+ *   ─────────────────────────────────────────────
+ *   text                              → content
+ *   parsedOutput                      → parsedOutput（structured-output 契约，BC-8）
+ *   !success && error                 → error（失败时填，成功时 undefined）
+ *   !success && !error                → error fallback（abort 路径：session-runner 设 success=false,error=undefined，
+ *                                      若直接透传 undefined 则 executeAgentCall 的 `error===undefined` 误判 completed。H4 修复：synthesize fallback）
+ *   durationMs                        → durationMs
+ *   sessionId                         → sessionId
+ *   usage (AgentUsageTotal)           → usage (AgentUsage: input/output/cacheRead/cacheWrite/cost/contextTokens/turns)
+ *   toolCalls (ToolCall[])            → toolCalls (ToolCallEntry[]: name/input)
+ *
+ * @param r subagents 管道产出的 AgentResult（runSpawn/collectResult 出口形状）
+ * @returns workflow 编排层消费的 AgentResult（executeAgentCall/finalizeCall 入参形状）
+ */
+export function mapToWorkflowAgentResult(
+  r: SubagentsAgentResult,
+): WorkflowAgentResult {
+  return {
+    content: r.text,
+    parsedOutput: r.parsedOutput,
+    error: r.success ? undefined : (r.error || "Agent call failed (aborted or unknown error)"),
+    durationMs: r.durationMs,
+    sessionId: r.sessionId,
+    sessionFile: r.sessionFile,
+    usage: r.usage ? mapUsage(r.usage, r.turns) : undefined,
+    toolCalls: r.toolCalls ? mapToolCalls(r.toolCalls) : undefined,
+  };
+}
+
+/**
+ * AgentUsageTotal（subagents）→ AgentUsage（workflow）映射。
+ *
+ * subagents AgentUsageTotal: { input, output, cacheRead, cacheWrite, total, cost }
+ * workflow AgentUsage:       { input, output, cacheRead, cacheWrite, cost, contextTokens, turns }
+ *
+ * contextTokens ≈ total（subagents 的四项之和，近似上下文 token 量）。
+ * turns 来自 AgentResult.turns（非 usage 内字段）。
+ */
+function mapUsage(u: AgentUsageTotal, turns: number): WorkflowAgentUsage {
+  return {
+    input: u.input,
+    output: u.output,
+    cacheRead: u.cacheRead,
+    cacheWrite: u.cacheWrite,
+    cost: u.cost,
+    contextTokens: u.total,
+    turns,
+  };
+}
+
+/**
+ * ToolCall（subagents）→ ToolCallEntry（workflow）映射。
+ *
+ * subagents ToolCall:     { toolName, args?, result?, isError? }
+ * workflow ToolCallEntry: { name, input }
+ */
+function mapToolCalls(calls: ToolCall[]): ToolCallEntry[] {
+  return calls.map((c) => ({
+    name: c.toolName,
+    input: c.args === undefined ? "" : safeStringify(c.args),
+  }));
+}
+
+/** 安全序列化（args 可能含循环引用或大对象，截断防 OOM）。 */
+function safeStringify(value: unknown): string {
+  try {
+    const s = JSON.stringify(value);
+    return s.length > TOOL_ARGS_JSON_MAX_CHARS ? `${s.slice(0, TOOL_ARGS_JSON_MAX_CHARS)}...` : s;
+  } catch {
+    return String(value);
+  }
+}

package/src/execution/alive-store.ts

@@ -0,0 +1,119 @@
+// src/runtime/execution/alive-store.ts
+//
+// .alive sidecar 生产者 + pid 探活。
+//
+// 子进程启动时写 .alive（pid+id+startedAt），心跳检测时读它 + isProcessAlive
+// 判活。finalize/cancel 收尾时 remove。与 .cancelled/.finalized 构成三件套。
+//
+// 设计对齐 tombstone-store：单文件 sidecar、best-effort I/O、无全局 index。
+
+import * as fs from "node:fs";
+
+import type { AliveMarker } from "./types.ts";
+
+// ============================================================
+// 常量
+// ============================================================
+
+/**
+ * .alive marker 的软超时（1h，自 record-store.ts 迁移为共享常量）：超过此时长的
+ * alive 视为陈旧——pid 复用窗口有限（[防] 缩短窗口降误判），且长时间 marker 多半
+ * 是异常退出后的残留。v8.5 D 透明重生的异进程探针复用同一判据（findForeignLiveInstance）。
+ */
+export const ALIVE_SOFT_TIMEOUT_MS = 3_600_000;
+
+// ============================================================
+// 公开函数
+// ============================================================
+
+/**
+ * 在 sessionFile 旁写 .alive sidecar（单行 JSON）。
+ * 覆盖写——同一 sessionFile 只有最后一个 alive marker 有意义。
+ */
+export function writeAliveMarker(sessionFile: string, marker: AliveMarker): void {
+  const alivePath = `${sessionFile}.alive`;
+  fs.writeFileSync(alivePath, `${JSON.stringify(marker)}\n`, "utf-8");
+}
+
+/**
+ * 读 sessionFile 旁的 .alive sidecar。
+ * 返回 undefined：不存在 / 损坏 / 解析失败。
+ */
+export function readAliveMarker(sessionFile: string): AliveMarker | undefined {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(`${sessionFile}.alive`, "utf-8");
+  } catch {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<AliveMarker>;
+    if (
+      typeof parsed.pid === "number" &&
+      typeof parsed.id === "string" &&
+      typeof parsed.startedAt === "number"
+    ) {
+      return parsed as AliveMarker;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 删除 sessionFile 旁的 .alive sidecar。
+ * best-effort：不存在不抛（finalize/cancel 收尾调，sidecar 可能已被清理）。
+ */
+export function removeAliveMarker(sessionFile: string): void {
+  try {
+    fs.unlinkSync(`${sessionFile}.alive`);
+  } catch {
+    void 0; // best-effort
+  }
+}
+
+/**
+ * 检测 pid 是否存活。
+ *
+ * process.kill(pid, 0) 语义：不发信号，仅检查进程是否存在。
+ *   - 无异常 → 存活
+ *   - ESRCH（No such process）→ 死
+ *   - EPERM（Process exists but no permission）→ 存活（保守）
+ *   - 其他异常 → 保守判死 false，避免误删活进程
+ */
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: unknown) {
+    if (isErrnoException(err) && err.code === "EPERM") {
+      return true; // 存在但无权限发信号 → 判活
+    }
+    return false; // ESRCH 或其他异常 → 保守判死
+  }
+}
+
+/**
+ * [v8.5 D] 异进程活实例探针：sessionFile 是否仍有「另一进程」的活跃实例。
+ *
+ * 三判据与 record-store buildRecord 分支 3 同源（readAliveMarker + isProcessAlive +
+ * 软超时）：marker 存在 && pid 存活 && 未超软超时才返回 marker；其余返回 undefined
+ * （视为确死/陈旧，允许透明重生）。调用方在 resurrect 前必须经此确认源进程确死，
+ * 防双写同一 session jsonl。
+ */
+export function findForeignLiveInstance(sessionFile: string, now: number = Date.now()): AliveMarker | undefined {
+  const marker = readAliveMarker(sessionFile);
+  if (!marker) return undefined;
+  if (!isProcessAlive(marker.pid)) return undefined;
+  if (now - marker.startedAt >= ALIVE_SOFT_TIMEOUT_MS) return undefined;
+  return marker;
+}
+
+// ============================================================
+// 内部工具
+// ============================================================
+
+function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
+  return err instanceof Error && "code" in err;
+}

package/src/execution/argv-mirror.ts

@@ -0,0 +1,113 @@
+/**
+ * 从主进程 argv 解析可镜像给子进程的 flag。
+ *
+ * 独立模块：argv 解析是独立职责，从 session-runner.ts 拆出避免该文件超行数上限。
+ */
+
+/**
+ * 镜像 flag 集合：从主进程 argv 解析出的可透传给子进程的 flag。
+ * 面向 buildSpawnArgs 的入参形态（解析后）。undefined 字段语义与解析为空一致。
+ */
+export interface MirrorFlags {
+  noExtensions: boolean;
+  approve: boolean;
+  extensionPaths: string[];
+  noContextFiles: boolean;
+}
+
+/**
+ * 有值 flag 的解析规则表：成员是「后跟一个值」的 flag 名（含长短形式）。
+ * 用于 mirrorMainProcessFlags 跳过其他 flag 的值时不误吃。
+ */
+const VALUED_FLAGS = new Set<string>([
+  "--extension", "-e",
+  "--skill",
+  "--model", "--system-prompt", "--append-system-prompt",
+  "--tools", "-t", "--exclude-tools", "-xt",
+  "--fork", "--session-dir", "--mode",
+  "--thinking", "--models",
+]);
+
+/** argv 中 flag 的起始索引：argv[0]=runtime, argv[1]=binary 路径。 */
+const ARGV_FLAG_START = 2;
+
+/**
+ * 从主进程 argv 解析可镜像的 flag（--no-extensions/--approve/--extension/--no-context-files）。
+ *
+ * 数据源是主 pi 进程的 process.argv：子进程 spawn 的父就是主进程，
+ * 主进程 argv 完整保留启动时收到的全部 flag（已运行时验证）。这让子进程
+ * extension/approve 加载行为与主进程一致，且对任意 pi 宿主通用（不止 xyz-agent）。
+ *
+ * 解析规则：
+ * - --no-extensions / -ne、--approve / -a：布尔 flag
+ * - --no-context-files / -nc：布尔 flag（镜像理由：--extension 镜像会把
+ *   @zhushanwen/pi-system-prompt 带进每个 subagent，该扩展靠子进程自己的
+ *   argv 检测此 flag 决定是否注入全局 AGENTS.md——不镜像则用户 opt-out
+ *   在 subagent 路径失效）
+ * - --extension / -e：支持 `--extension <path>`（空格）与 `--extension=<path>`（等号）
+ * - 其他 flag（在 VALUED_FLAGS 中）的值不被误当 extension 路径
+ * - positional 参数被忽略
+ * - argv[0]/argv[1] 是 bun/pi binary 路径，从 argv[2:] 开始扫
+ */
+// [perf] 进程内 process.argv 引用恒定（唯一调用点 session-runner 每次 spawn 传同一引用），
+// 解析结果按 argv 引用相等 memo——每次 spawn 免重复扫描/正则。测试传新数组引用不命中。
+let memoArgv: readonly string[] | undefined;
+let memoResult: MirrorFlags | undefined;
+
+export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
+  if (memoResult !== undefined && memoArgv === argv) return memoResult;
+  let hasNoExtensions = false;
+  let hasApprove = false;
+  let hasNoContextFiles = false;
+  const extensionPaths: string[] = [];
+
+  // argv[0]=runtime(bun), argv[1]=pi binary 路径；flag 从 argv[2] 起
+  const flagArgs = argv.length > ARGV_FLAG_START ? argv.slice(ARGV_FLAG_START) : [];
+
+  for (let i = 0; i < flagArgs.length; i++) {
+    const tok = flagArgs[i];
+    if (tok === "--no-extensions" || tok === "-ne") {
+      hasNoExtensions = true;
+      continue;
+    }
+    if (tok === "--approve" || tok === "-a") {
+      hasApprove = true;
+      continue;
+    }
+    if (tok === "--no-context-files" || tok === "-nc") {
+      hasNoContextFiles = true;
+      continue;
+    }
+    // 等号形式 --extension=path / -e=path
+    const eqMatch = /^(--extension|-e)=(.*)$/.exec(tok);
+    if (eqMatch) {
+      const val = eqMatch[2];
+      if (val) extensionPaths.push(val);
+      continue;
+    }
+    // 空格形式 --extension <path> / -e <path>：值在下一个 token
+    // [MF-7a] flag 判定收窄为 startsWith("--")：守卫原为 !startsWith("-")，把以单个
+    // - 开头的合法路径（如相对路径 -weird-dir/x.md）误判为 flag 跳过——extension 路径
+    // 静默丢失。pi CLI 的多字符长 flag 一律 -- 前缀，单 - 只接单字符短 flag（-e 本身），
+    // 故「-- 开头才算 flag」不误吃真 flag 且放行 - 开头路径。
+    if (tok === "--extension" || tok === "-e") {
+      const next = flagArgs[i + 1];
+      if (next !== undefined && !next.startsWith("--") && next.length > 0) {
+        extensionPaths.push(next);
+        i++; // 跳过值
+      }
+      continue;
+    }
+    // 其他有值 flag：跳过其值，避免误吃（如 --skill /a 的 /a）
+    if (VALUED_FLAGS.has(tok)) {
+      i++;
+      continue;
+    }
+    // 其他情况（未知 flag、--flag=val 形式、positional）忽略
+  }
+
+  const result = { noExtensions: hasNoExtensions, approve: hasApprove, extensionPaths, noContextFiles: hasNoContextFiles };
+  memoArgv = argv;
+  memoResult = result;
+  return result;
+}

package/src/execution/best-effort.ts

@@ -0,0 +1,38 @@
+// src/utils/best-effort.ts
+//
+// best-effort IO 清理的错误吞咽 helper。
+//
+// 用途：sidecar 写入 / worktree remove / alive marker 删除等次要 IO，失败不影响
+// 主流程（session 已完成或正在收尾）。这类 catch 故意吞错——但 taste/no-silent-catch
+// 规则禁止空 catch 或仅 console 的 catch。本 helper 提供一条「实质调用语句」让
+// catch 合规，同时把错误记录到 debug/error 便于排查。
+//
+// 规则绕过原理：taste/no-silent-catch 仅检查 CatchClause 直接 body 是否为空或仅
+// console 调用。本 helper 是普通函数调用（ExpressionStatement），既非空也非仅
+// console，故合规。helper 函数体内部经共享 logger 路由（不裸 console）。
+
+import { getLogger } from "../core/logger.ts";
+
+const logger = getLogger("subagents");
+
+/** 错误日志级别。debug = 次要清理（默认）；error = 关键步骤但需继续后续清理。 */
+export type BestEffortLevel = "debug" | "error";
+
+/**
+ * 吞咽 best-effort IO 的错误，按 level 经共享 logger 记录。
+ *
+ *   - debug（默认）：次要清理（sidecar/worktree/alive marker），失败属预期路径
+ *   - error：关键步骤抛错但需继续后续清理（如 finalizeRecord 的 B9 链：completeRecord
+ *     抛错后仍要执行 finalized/cleanup，错误需可见但不阻断）
+ *
+ * 错误对象优先取 message（避免打印巨大堆栈/对象），其他类型原样传入。
+ */
+export function bestEffort(err: unknown, context: string, level: BestEffortLevel = "debug"): void {
+  const detail = err instanceof Error ? err.message : err;
+  const msg = `[subagents] best-effort ${context} failed`;
+  if (level === "error") {
+    logger.error(msg, { detail });
+  } else {
+    logger.debug(msg, { detail });
+  }
+}