@zhushanwen/subagent-core 0.2.0

package/src/execution/worktree-registry.ts

@@ -0,0 +1,279 @@
+// src/runtime/worktree-registry.ts
+//
+// 全局 worktree 注册表：跨 repo 记录所有活 pi-sub-* worktree。
+//
+// 取代旧的 per-cwd 扫描 + .session mapping sidecar 链。
+// 旧 reaper 的两个根本缺陷由此消除：
+//   1. 触发覆盖：旧 scan 扫「当前 cwd 对应的 repo」，workspace 根 / 非 git 目录启动时
+//      rev-parse 报错整个挂掉；且 tmpdir 下的 checkout 永远不会被 pi cwd "看到"。
+//      → 新 scan 遍历全局注册表，不依赖 cwd 是否 git repo。
+//   2. 判据脆弱：旧 scan 用 .finalized/.cancelled 终态 marker 作主判据，进程崩溃时
+//      无人写终态 → 孤儿永久泄漏。→ 新判据：pid 死活一条判到底。
+//
+// 并发模型：
+//   - 跨进程互斥（D5a）：add/updatePid/remove 的 load→mutate→save 全程持
+//     proper-lockfile 异步锁（<worktrees.json>.lock，协议登记 data-source-registry.md §6）。
+//     锁不可用（重试耗尽）时降级为无锁 RMW + warn——注册表是 best-effort 数据，
+//     降级不比锁前更差，条目丢失由 reaper 对账兜底（worktree-manager scan 的
+//     双向 diff，见 reconcileWithPhysical）。
+//   - 同步 IO（readFileSync/writeFileSync）持锁执行：锁内临界区毫秒级，
+//     async 锁 + sync IO 组合在单线程 event loop 内无 interleaving。
+//   - 原子写：写 .tmp → rename，防写一半崩溃产生损坏 JSON。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { getLogger } from "../core/logger.ts";
+import lockfile from "proper-lockfile";
+
+import { bestEffort } from "./best-effort.ts";
+
+const logger = getLogger("subagents");
+
+/** create→spawn 宽限期（ms）：pid=0 条目超过此阈值判 create 后崩溃。 */
+export const SPAWN_GRACE_MS = 60_000;
+
+/** JSON 缩进空格数（可读性 + diff 友好）。 */
+const JSON_INDENT = 2;
+
+/** tmp 随机段：36 进制取 8 字符（跳过 "0." 前缀），与 pid 组合保证并发唯一。 */
+const TMP_RANDOM_BASE = 36;
+const TMP_RANDOM_SLICE_START = 2; // 跳过 Math.random 字符串的 "0." 前缀
+const TMP_RANDOM_SLICE_END = 10;
+
+/**
+ * 锁参数：逐项对齐 extensions/shared/file-lock/src/file-lock.ts 的 withFileLock
+ * 包装默认值（stale 30s / retries 10）。两侧参数漂移会破坏「同一把
+ * <worktrees.json>.lock」的跨进程互斥语义（协议登记 data-source-registry.md §6），
+ * 与旧包装共存/替换期间尤其如此。
+ */
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRIES = 10;
+
+/** 注册表 JSON 顶层结构的运行时类型守卫。 */
+function isRegistryData(value: unknown): value is { entries: WorktreeEntry[] } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "entries" in value &&
+    Array.isArray(value.entries)
+  );
+}
+
+/**
+ * 注册表条目：一条 = 一个活 worktree。
+ * 字段全部来自 WorktreeHandle + session-runner 已捕获的 child.pid，零新数据源。
+ */
+export interface WorktreeEntry {
+  /** 主仓库根目录（git -C <repo> 操作目标）。 */
+  readonly repo: string;
+  /** 分支名（"pi-sub-<recordId>"）。 */
+  readonly branch: string;
+  /** checkout 目录（tmpdir 下，= WorktreeHandle.path）。 */
+  readonly checkout: string;
+  /** 子进程 pid（0 = create-spawn 窗口，尚未拿到 pid）。 */
+  readonly pid: number;
+  /** 创建时间戳（ms，SPAWN_GRACE 判据 + 调试用）。 */
+  readonly createdAt: number;
+  /**
+   * 对应 subagent session jsonl 文件全路径（诊断/兼容字段，reaper 据 pid 死活判孤儿）。
+   * session-runner first header 拿到 pid 时补全（create 时 record.sessionFile 尚未确定）。
+   * 可选：旧 worktrees.json / 非 worktree 模式无此字段，向后兼容（undefined 时 reaper 走原 pid 判据）。
+   */
+  readonly sessionFile?: string;
+}
+
+/**
+ * 全局 worktree 注册表。
+ *
+ * 文件位置：<agentDir>/subagents/worktrees.json（repo 无关层级，跨 repo 共享）
+ * 格式：{ "entries": WorktreeEntry[] }
+ */
+export class WorktreeRegistry {
+  private readonly filePath: string;
+
+  constructor(agentDir: string) {
+    this.filePath = path.join(agentDir, "subagents", "worktrees.json");
+  }
+
+  /**
+   * 新增条目（create 成功后调，pid=0 占位）。
+   * 同 branch 已存在则覆盖（防残留覆盖）。
+   * 跨进程锁内 RMW（D5a）；锁降级路径见 mutate。
+   */
+  async add(entry: WorktreeEntry): Promise<void> {
+    await this.mutate((entries) => {
+      const idx = entries.findIndex((e) => e.branch === entry.branch);
+      if (idx >= 0) {
+        entries[idx] = entry;
+      } else {
+        entries.push(entry);
+      }
+    });
+  }
+
+  /**
+   * 更新 pid（runSpawn spawn() 返回后同步调）。
+   * branch 不存在则忽略（create 后崩溃 + reaper 已清的竞态）。
+   * sessionFile 可选补全：传入时填入 entry（reaper 据 pid 死活判孤儿，不读本字段）。
+   */
+  async updatePid(branch: string, pid: number, sessionFile?: string): Promise<void> {
+    await this.mutate(
+      (entries) => {
+        const idx = entries.findIndex((e) => e.branch === branch);
+        if (idx >= 0) {
+          entries[idx] = {
+            ...entries[idx],
+            pid,
+            ...(sessionFile !== undefined ? { sessionFile } : {}),
+          };
+        }
+      },
+      { branch, pid },
+    );
+  }
+
+  /**
+   * 移除条目（cleanup/reaper 清理后调）。
+   * branch 不存在则忽略（幂等）。
+   */
+  async remove(branch: string): Promise<void> {
+    await this.mutate(
+      (entries) => {
+        const filtered = entries.filter((e) => e.branch !== branch);
+        if (filtered.length !== entries.length) {
+          entries.length = 0;
+          entries.push(...filtered);
+        }
+      },
+      { branch },
+    );
+  }
+
+  /**
+   * 锁内 RMW 统一入口：withLock(load → mutate → save)。
+   *
+   * 降级语义（对齐本类既有 best-effort 约定——注册表写失败不阻断 create/cleanup
+   * 主流程）：锁获取失败（重试耗尽 ELOCKED 等）→ warn + 无锁执行同一段 RMW
+   * （= D5a 之前的 last-write-wins 行为，条目丢失由 reaper 对账兜底），
+   * 不抛错、永不 reject（调用方含 session-runner 的 fire-and-forget 回调）。
+   */
+  private async mutate(
+    mutate: (entries: WorktreeEntry[]) => void,
+    context?: { branch?: string; pid?: number },
+  ): Promise<void> {
+    const run = (): void => {
+      const entries = this.load();
+      mutate(entries);
+      this.save(entries, context);
+    };
+    try {
+      await this.withLock(() => {
+        run();
+      });
+    } catch (lockErr) {
+      // 锁不可用（ELOCKED 重试耗尽 / 锁目录损坏等）：降级无锁 RMW。
+      // 竞争窗口内可能丢条目（旧缺陷形态），由 reaper 对账（scan 双向 diff）收敛。
+      logger.warn("[worktree] registry lock unavailable, degraded to lock-free RMW", {
+        ...(context ?? {}),
+        err: lockErr instanceof Error ? lockErr.message : String(lockErr),
+      });
+      try {
+        run();
+      } catch (err) {
+        bestEffort(err, "worktree registry degraded RMW");
+      }
+    }
+  }
+
+  /**
+   * proper-lockfile 直用的跨进程锁（取代已删除的共享 file-lock 包装，抽包去依赖）。
+   * 锁协议逐项对齐 extensions/shared/file-lock/src/file-lock.ts 的 withFileLock：
+   *   - lockfile 路径 = <目标文件>.lock（proper-lockfile 默认，与包装/runtime 侧
+   *     同一路径才互斥）
+   *   - realpath:false —— 目标文件不存在也可锁（realpath 默认 true 时 ENOENT）
+   *   - stale 30s：持锁进程崩溃后锁可被夺取
+   *   - async retries 指数退避：10 次 / factor 2 / 100ms~10s / randomize，耗尽抛
+   *     ELOCKED（调用方 mutate 的 catch 决定降级路径）
+   *   - onCompromised：锁被 stale 夺取时标记，fn 执行前抛错——防止在失去互斥
+   *     保证的锁下写盘（对齐 pi throwIfCompromised 语义）
+   * 锁参数值由 LOCK_STALE_MS / LOCK_RETRIES 常量承载（防漂移说明见常量注释）。
+   */
+  private async withLock(fn: () => void): Promise<void> {
+    // 锁前确保父目录存在：proper-lockfile 创建 lockfile（<目标>.lock）需要目录在
+    const dir = path.dirname(this.filePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    let compromised: Error | undefined;
+    const release = await lockfile.lock(this.filePath, {
+      realpath: false,
+      stale: LOCK_STALE_MS,
+      retries: {
+        retries: LOCK_RETRIES,
+        factor: 2,
+        minTimeout: 100,
+        maxTimeout: 10_000,
+        randomize: true,
+      },
+      onCompromised: (err: Error) => {
+        compromised = err;
+      },
+    });
+    try {
+      if (compromised) throw compromised;
+      fn();
+    } finally {
+      try {
+        await release();
+      } catch (unlockErr) {
+        // 锁已 compromised（被 stale 夺取）时 unlock 必然失败且可忽略——记录留痕
+        // 不外抛（对齐被替换的 file-lock 包装 finally catch 语义）。
+        logger.debug("unlock failed after compromise (ignorable)", {
+          detail: { err: unlockErr instanceof Error ? unlockErr.message : String(unlockErr) },
+        });
+      }
+    }
+  }
+
+  /**
+   * 加载全部条目（reaper 遍历用）。
+   * 文件不存在 / 解析失败 / IO 错误 → 返回空数组（视为无活 worktree）。
+   */
+  load(): WorktreeEntry[] {
+    try {
+      const raw = fs.readFileSync(this.filePath, "utf-8");
+      const parsed = JSON.parse(raw) as unknown;
+      if (isRegistryData(parsed)) {
+        return parsed.entries;
+      }
+      return [];
+    } catch {
+      // 文件不存在（首次运行）/ 解析失败（损坏）/ IO 错误 → 空注册表
+      return [];
+    }
+  }
+
+  /**
+   * 原子写入全部条目。
+   * best-effort：写入失败不阻断主流程（create/cleanup 的 git 操作已执行，
+   * 注册表与 git 状态的短暂不一致靠下次 reaper 对账收敛）。
+   * 写盘失败时 warn 日志（带 branch/pid 上下文，补全失败可观测闭环）。
+   */
+  private save(entries: WorktreeEntry[], context?: { branch?: string; pid?: number }): void {
+    try {
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+      // tmp 名带 pid + 随机段：锁降级（无锁并发 RMW）时多进程 tmp 互不覆盖
+      const tmp = `${this.filePath}.tmp_${process.pid}_${Math.random().toString(TMP_RANDOM_BASE).slice(TMP_RANDOM_SLICE_START, TMP_RANDOM_SLICE_END)}`;
+      fs.writeFileSync(tmp, JSON.stringify({ entries }, null, JSON_INDENT), "utf-8");
+      fs.renameSync(tmp, this.filePath);
+    } catch (err) {
+      bestEffort(err, "worktree registry save");
+      // [worktree-reaper-fix] 补全写盘失败静默吞错时，条目 pid 恒 0、60s 后被 reaper 误删
+      // 活 worktree 且无诊断线索。此 warn 与 reaper scan 的 pid=0 warn 呼应，形成闭环。
+      logger.warn(
+        "[worktree] registry save failed; pid may stay 0 and be reaped by orphan reaper",
+        { ...(context ?? {}), err: err instanceof Error ? err.message : String(err) },
+      );
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * @zhushanwen/subagent-core — 公共 API barrel（D5 定稿）
+ *
+ * 公共 API 面 = 本文件导出 + package.json exports 的语义子入口
+ * （./engines/zcode/reader、./engines/zcode/constants、./engine/paths、./relay-env）
+ * + ./workflows/* 资产子入口。exports 面即 semver 契约（D5）：收窄不放宽——
+ * 新增导出走 minor，本文件刻意不使用 `export *`，逐名列出以使 diff 可审。
+ * 内部实现细节（registry / error-recovery / execution 编排件等）不经 barrel 导出，
+ * 仓内壳侧深路径消费（`./*` -> src 通配）不受本文件约束。
+ *
+ * 设计权威源：docs/design/subagent-core-package-extraction.md §3.3 D5；
+ * 宿主接入示例见包 README（§3.4 core_host_not_configured 恢复指引的落点）。
+ */
+
+export const CORE_PACKAGE_VERSION = "0.2.0";
+
+// ── 宿主端口接线面（core/）────────────────────────────────────
+// HostServices：dataRoot / log / discoveryRoots 端口 + configureCore 注入；
+// 未 configureCore 即消费 dataRoot 抛 core_host_not_configured（§3.4 错误规格，
+// 恢复指引指向 README 接入示例）。DEFAULT_DATA_ROOT 显式导出供宿主选用——
+// 消除「缺省静默漂目录」。
+export {
+  configureCore,
+  DEFAULT_DATA_ROOT,
+  type DiscoveryRoot,
+  type HostServices,
+} from "./core/host-services.ts";
+
+// getLogger：facade 代理 logger——每次 log 调用时动态解析当前宿主实现，
+// 模块顶层缓存惯例（`const logger = getLogger(...)`）下 configureCore 前后透明切换。
+// LogLevel 是 HostServices.log 契约的成员类型（宿主实现必读）。
+export { getLogger, type CoreLogger, type LogLevel } from "./core/logger.ts";
+
+// NotifyDomainPorts：通知域窄端口（投递内核工厂 + pending 活跃计数），
+// 两成员可选，缺席降级（投递直发 / pending 计零）。
+export {
+  configureNotifyDomain,
+  type NotifyDomainPorts,
+} from "./core/notify-ports.ts";
+
+// ── 引擎契约面（execution/engine）────────────────────────────
+// EnginePort：subagent 执行引擎的唯一契约点（run / interact / read / probe 四能力面）。
+// types.ts：引擎中立类型（宿主与引擎适配器共同消费，宿主不感知具体引擎）。
+export type {
+  EnginePort,
+  EngineRunResult,
+  RunContext,
+} from "./execution/engine/port.ts";
+export type {
+  AgentEvent,
+  AgentOutcome,
+  AgentTaskSpec,
+  EngineCapabilities,
+  EngineHandle,
+  EngineHandleData,
+  InteractAction,
+  InteractResult,
+  PersonaSpec,
+  ProbeReport,
+  ReplayedTurn,
+  SessionView,
+} from "./execution/engine/types.ts";
+// RunContext 的成员类型（ctxModel / stream）——类型闭包随 EnginePort 必然公开，
+// 显式导出免宿主深路径兜圈；type-only（SubagentStream 是 execution 内部实现，禁 new）。
+export type { ModelInfo } from "./execution/model-resolver.ts";
+export type { SubagentStream } from "./execution/stream-sink.ts";
+
+// routeEngine：三层路由（调用参数 > frontmatter > 全局默认）+ probe fallback 编排
+// 的单一权威点（engine-abstraction D9/D7）。宿主按 error.code（engine_* 错误族）
+// 判别失败形态，无需导入错误类。
+export {
+  routeEngine,
+  type EngineRouteOptions,
+  type EngineRouteResult,
+  type EngineRouting,
+  type EngineRoutingInput,
+  type EngineRoutingSource,
+} from "./execution/engine/routing.ts";
+
+// ── workflow 编排入口（orchestration）────────────────────────
+// runWorkflow / abortRun：run 生命周期 free functions（D-12）——orchestration 的
+// 最小宿主入口。更细粒度编排（terminateRunningRuns / evictDoneRunsBeyondCap /
+// scheduleTimeBudget）与 launcher 层（runAndWait 等）暂不进 barrel：
+// 无宿主触点证据前不放宽（端口演进纪律②）；壳侧现经深路径消费，不受影响。
+export { abortRun, runWorkflow } from "./orchestration/lifecycle.ts";
+export type { RunSpec } from "./orchestration/models/run-spec.ts";
+export type { LifecycleDeps } from "./orchestration/models/ports.ts";