@zhushanwen/extension-protocol 0.11.0

package/README.md

@@ -0,0 +1,43 @@
+# @zhushanwen/extension-protocol
+
+pi extension 跨层契约包：类型 + helper 函数 + 共享行为原语，零运行时依赖。覆盖双模式（TUI/GUI）渲染、session-manager / background-task / pending-entries 协议与跨端共享的行为原语（进程处置 / registry 文件 IO / output tail）。
+
+## 包结构
+
+- `core/` —— 通用协议层（所有 extension 共用：`GuiComponent` + 布局原语 + 传输编码 + 双模 widget helper）
+- `extensions/` —— 有运行时定制逻辑的 extension（marker + helper）
+  - `ask-user/` —— 富交互（select 通道 + marker）
+  - `session-manager/` —— agent-managed session 嵌套 `{action, params}` 契约（select 通道 + marker）
+  - `plugin-bridge/` —— plugin system bridge（插件工具/事件/拦截经 select 通道 + marker 桥接）
+  - `subagent-engine/` —— 引擎可发现性（`engines.json` 状态文件 + 引擎配置视图）
+- `pending-entries` —— pending 事件流差集核心（register 去重 + unregister 抵消，纯算法）
+- `background-task` —— base-tool-enhance 后台任务 `registry.json` 文件契约
+- 子出口 `@zhushanwen/extension-protocol/background-task` —— 后台任务行为原语（进程处置 / registry 文件 IO / output tail，含 node 内建依赖，不进 index 桶出口）
+
+## 设计原则
+
+- **core 只保留结构性、中性的通用原语**（card / stats-line / progress-bar / list-tree / columns / tab-bar / ansi-text）。特定 extension 的领域数据结构不进协议层——extension 用通用原语组合表达，形状太特殊时走 custom 通道。
+- **零运行时依赖**：纯类型 + 纯函数，两端（extension 与 renderer）共享同一契约。
+- **marker 通道**：GUI 能力协商经 `GUI_WIDGET_MARKER` / 各 extension 专属 marker（如 `ASK_USER_MARKER`）走 pi 消息流。
+
+## 使用
+
+```ts
+import { guiComponent, guiResult, extractGui, isGuiCapable } from '@zhushanwen/extension-protocol'
+
+// extension 侧：构造 GUI 组件渲染结果（guiResult 收单个 component，非数组）
+const result = guiResult(guiComponent('stats-line', { items: [{ label: 'turns', value: '12' }] }))
+
+// 宿主侧：从 tool result 的 details.__gui__ 字段提取 GUI 渲染结果
+const extracted = extractGui(toolResultDetails)
+```
+
+session-manager 嵌套 `{action, params}` 契约的类型（各 action 的 params/result 类型）同样从本包导出。
+
+## 开发
+
+```bash
+cd packages/extension-protocol
+npx vitest run        # 跑测试
+npx tsc --noEmit      # 类型检查
+```

package/dist/background-task-Cu0p02O-.d.ts

@@ -0,0 +1,106 @@
+/**
+ * base-tool-enhance 后台任务 registry.json 契约（跨层 SSOT）。
+ *
+ * 契约两端：
+ *  - 写侧：@zhushanwen/pi-base-tool-enhance extension（pi 进程内，registry 权威）——
+ *    spawn 登记 running、bash_kill / 后台 timeout 标 killing、轮询器与 process-exit
+ *    guard 写 exited 终态。写入协议：原子写 temp+rename + 统一文件锁内 RMW；
+ *    解析失败/形状非法 → 重命名 .corrupt 保留现场 + 按空表重建。
+ *  - 读侧：taiji runtime 后台任务收殓器——按属主判定处置孤儿（见 ownerPiPid
+ *    字段注释），orphaned 终态由 runtime 写入（收殓下沉，设计 docs/design/
+ *    file-lock-unification-and-reaper-sink.md D2）。
+ *
+ * 目录布局（per-session 隔离）：
+ *   <agentDir>/base-tool-enhance/<sessionId>/registry.json
+ *   （agentDir = pi getAgentDir() 同源 dataDir，由调用方解析传入，不硬编码）
+ *
+ * 字段名/语义/枚举值与写侧现状逐字段一致（基线：extensions/universal/
+ * base-tool-enhance/src/background/types.ts + registry.ts），禁止在此单侧改名。
+ */
+/** registry 文件名（<agentDir>/base-tool-enhance/<sessionId>/ 下）。 */
+declare const BACKGROUND_TASK_REGISTRY_FILENAME: "registry.json";
+/** 后台任务根目录名（<agentDir>/ 下，内含 per-sessionId 子目录）。 */
+declare const BASE_TOOL_ENHANCE_DIRNAME: "base-tool-enhance";
+/**
+ * 任务 id 前缀（taskId 契约注释已约定：bt- 前缀，对账差集只认该前缀——区别于
+ * subagent-workflow 的 bg-/run-）。升级为导出常量：对账/守卫的前缀过滤从此引用
+ * 同一常量，禁止各侧字面量重写。
+ */
+declare const BACKGROUND_TASK_ID_PREFIX: "bt-";
+/** registry 文件格式版本（读侧 version 不匹配按损坏处理；未来结构变更时迁移判据）。 */
+declare const BACKGROUND_TASK_REGISTRY_VERSION: 1;
+/** 终态条目 LRU 上限（写侧合并时按 endedAt ?? startedAt 淘汰最老终态条目）。 */
+declare const MAX_TERMINAL_REGISTRY_ENTRIES = 50;
+/**
+ * 任务状态机：running → killing（intent 瞬态）→ exited；orphaned 由收殓侧写入。
+ *  - running   任务运行中（spawn 后登记的初始态）
+ *  - killing   终止已发令（bash_kill / 后台 timeout）、exit 边沿未确认的瞬态
+ *  - exited    终态：进程已退出（reason 说明成因）
+ *  - orphaned  终态：属主 pi 已死，任务被收殓（补杀或终态收尾）
+ */
+type BackgroundTaskState = 'running' | 'killing' | 'exited' | 'orphaned';
+/**
+ * 终态 reason 枚举（仅 exited 语义）：
+ *  - natural       进程自然退出（含外力终止——观测上不可区分）
+ *  - timeout       后台显式 timeout 定时器触发
+ *  - killed        bash_kill 发令
+ *  - process-exit  pi 进程退出收殓
+ * orphaned 终态不写 reason（成因「属主强杀遗留」不在本枚举内，保持字段缺省）。
+ */
+type BackgroundTaskEndReason = 'natural' | 'timeout' | 'killed' | 'process-exit';
+/** registry.json 文件形状（version 锁定 + 条目数组；序列化 JSON indent 2 + 尾部换行）。 */
+interface BackgroundTaskRegistryFile {
+    version: typeof BACKGROUND_TASK_REGISTRY_VERSION;
+    entries: BackgroundTaskRegistryEntry[];
+}
+/** registry.json 持久化条目（任务运行时对象剥离非持久字段后的形状）。 */
+interface BackgroundTaskRegistryEntry {
+    /** 任务 id（表内唯一键；`bt-` 前缀，对账差集只认该前缀）。 */
+    taskId: string;
+    /** 任务进程 pid（收殓补杀目标；判活用 kill(pid,0)，ESRCH = 死）。 */
+    pid: number;
+    /** 原始命令全文。 */
+    command: string;
+    /** stdout/stderr 重定向输出文件路径。 */
+    outputFile: string;
+    /** 任务登记时刻（epoch 毫秒）。 */
+    startedAt: number;
+    /** 状态机（见 BackgroundTaskState）。 */
+    state: BackgroundTaskState;
+    /**
+     * 属主判定依据：发起任务的 pi 进程 pid。pi 进程死亡（kill(ownerPiPid,0) 命中
+     * ESRCH）→ 其 detached 后台任务孤儿化，收殓器按属主判定处置（属主活 → 跳过，
+     * 宁漏杀勿误杀——桌面端并行 session 的合法任务靠此防线豁免）。
+     */
+    ownerPiPid: number;
+    /** 发起 session（registry 目录归属）。 */
+    sessionId: string;
+    /** 进程退出码（被 signal 终止时为 null；条目未终态时字段缺省）。 */
+    exitCode?: number | null;
+    /** 终态成因（仅 exited 语义；orphaned 保持缺省）。 */
+    reason?: BackgroundTaskEndReason;
+    /** 终态时刻（epoch 毫秒）。 */
+    endedAt?: number;
+    /** 存活时长 = endedAt - startedAt（毫秒）。 */
+    durationMs?: number;
+    /** exit 边沿组装的输出尾部摘要。 */
+    tailSummary?: string;
+    /**
+     * 任务进程 start time（epoch 秒，ps -o lstart= 解析值——勿与 startedAt 的毫秒
+     * 混用）：收殓前精确比较防 pid 复用误杀；字段缺省（旧条目 / spawn 时读取失败）
+     * 走 startedAt 秒级降级校验。
+     */
+    pidStartTime?: number;
+}
+/** 任务是否处于活跃态（收殓扫描的候选集；exited/orphaned 直接跳过）。 */
+declare function isActiveBackgroundTaskState(state: BackgroundTaskState): boolean;
+/** 任务是否处于终态（orphaned 同属终态——收殓二次扫描幂等 no-op 的构造性来源）。 */
+declare function isTerminalBackgroundTaskState(state: BackgroundTaskState): boolean;
+/**
+ * 条目形状运行时 guard（读侧防御，对齐写侧 isValidRegistryEntry 语义）：核心
+ * 标识字段（8 个必填字段）类型合法即放行，缺失/脏类型单条丢弃——不因单条脏数据
+ * 报废全表。可选字段不做深度校验（与写侧现状一致）。
+ */
+declare function isBackgroundTaskRegistryEntry(item: unknown): item is BackgroundTaskRegistryEntry;
+
+export { type BackgroundTaskState as B, MAX_TERMINAL_REGISTRY_ENTRIES as M, type BackgroundTaskRegistryEntry as a, BACKGROUND_TASK_ID_PREFIX as b, BACKGROUND_TASK_REGISTRY_FILENAME as c, BACKGROUND_TASK_REGISTRY_VERSION as d, BASE_TOOL_ENHANCE_DIRNAME as e, type BackgroundTaskEndReason as f, type BackgroundTaskRegistryFile as g, isBackgroundTaskRegistryEntry as h, isActiveBackgroundTaskState as i, isTerminalBackgroundTaskState as j };

package/dist/background-task-entry.d.ts

@@ -0,0 +1,159 @@
+import { B as BackgroundTaskState, a as BackgroundTaskRegistryEntry } from './background-task-Cu0p02O-.js';
+
+/**
+ * 后台任务进程原语（pid 判活 / 进程树处置 / start time 身份判据）——跨端单一实现。
+ *
+ * 契约两端（此前各持一份逐字同构实现，对齐手段是注释，已归一到本模块）：
+ *  - extension 侧：@zhushanwen/pi-base-tool-enhance（bash_kill 前校验 / 后台 timeout
+ *    到点校验 / 对账判死），原实现在其 kill-tree.ts
+ *  - runtime 侧：taiji background-task-reaper（孤儿收殓三分支判定），原实现在
+ *    background-task-reaper.ts 原语区
+ *
+ * 分支语义（与 pi 实装对齐，勿单侧擅改）：Windows `taskkill /F /T`；POSIX 杀进程组
+ * `kill -- -<pgid>`（后台任务 detached spawn 自成进程组，pgid = pid）；进程组杀不到时
+ * 回退单 pid + `pgrep -P` 递归杀残留子进程。
+ *
+ * 日志通道：本模块零日志依赖（protocol 零运行时依赖纪律）——回退路径的诊断经可选
+ * 回调 `onFallback(step, err)` 上报，extension 侧注入 logger.debug 适配、runtime 侧
+ * 注入 console.debug 适配。step 为稳定短标识符：
+ *  - 'process-group-kill-missed'      POSIX 进程组 kill 失败（组长已死），走回退
+ *  - 'single-pid-kill-missed'         单 pid kill 失败（目标已死，幂等语义）
+ *  - 'taskkill-failed'                Windows taskkill 失败
+ *  - 'descendant-enumeration-failed'  pgrep 不可用/失败，放弃子孙枚举
+ *  - 'descendant-kill-missed'         子孙 kill 失败（已死，幂等语义）
+ */
+/** killProcessTree 回退路径诊断回调（落盘/console 通道由调用方适配注入）。 */
+type ProcessFallbackLogger = (step: string, err: unknown) => void;
+/**
+ * pid 判活：kill(pid, 0) 不发信号只做存在性/权限校验。
+ * ESRCH = 已死（含被 reap 后）；EPERM = 进程存在但属其他用户，仍视为活。
+ */
+declare function isPidAlive(pid: number): boolean;
+/**
+ * 杀整棵进程树（同步；收殓路径在 process.on("exit") 里跑，必须同步）。
+ * POSIX 杀进程组（pgid = pid）一次性覆盖全部子孙；进程组杀不到（组长已死）回退
+ * 单 pid + pgrep -P 递归清理残留子进程（先杀孙辈再杀子辈，防孙辈在父死后被
+ * reparent 逃逸枚举）。Windows taskkill /F /T。幂等：目标已死时静默成功
+ * （回退路径的诊断经 onFallback 上报，无回调则静默）。
+ */
+declare function killProcessTree(pid: number, onFallback?: ProcessFallbackLogger): void;
+/**
+ * 取进程 start time（epoch 秒）。ps -o lstart= 跨 macOS/Linux（= 号去表头；Linux
+ * /proc/<pid>/stat 精度更高但 macOS 无 /proc，统一 ps 保跨平台一致）。
+ * 返回 undefined：进程不存在 / ps 不可用（Windows）/ 输出不可解析——调用方一律按
+ * 「无法校验 → 保守跳过」处理。
+ */
+declare function getProcessStartTimeSec(pid: number): number | undefined;
+/**
+ * pid 身份判据（「宁不杀勿误杀」的唯一判定点）。
+ * true = 当前占用该 pid 的进程 start time 与登记值匹配，可安全 kill。
+ *  - 有登记 start time（spawn 时 ps 读取成功）→ 精确比较（同单位 epoch 秒）
+ *  - 缺登记 start time（旧条目 / ps 不可用平台登记）→ startedAtMs 秒级降级：
+ *    登记发生在 spawn 之后（进程先启动、条目后登记），原进程 start time 必然
+ *    ≤ floor(startedAtMs/1000)（floor 单调性，零误跳）
+ */
+declare function pidStartMatchesRegistered(actualStartSec: number, registeredStartSec: number | undefined, startedAtMs: number): boolean;
+
+/**
+ * registry.json 文件行为原语（解析防御 / corrupt 隔离 / 原子写 / 终态 LRU 裁剪 /
+ * 序列化）——跨端单一实现。
+ *
+ * 契约两端（此前各持一份同构实现，对齐手段是注释）：
+ *  - extension 侧：@zhushanwen/pi-base-tool-enhance background/registry.ts（bte 的
+ *    readRegistry 返回 Map、锁壳用 pi-file-lock）
+ *  - runtime 侧：taiji background-task-reaper / services/background-task/
+ *    registry-write.ts（数组形态、锁壳用统一锁）
+ *
+ * 本模块只提供无锁原语与纯函数；锁壳（withFileLockSync RMW 编排）留在各侧——
+ * 两侧锁实现不同（pi-file-lock vs runtime 统一锁）是产品决策，不下沉。
+ *
+ * 日志通道：本模块零日志依赖——warn 级诊断（registry 读失败 / corrupt 隔离 /
+ * tmp 清理失败）经可选回调 `onLog('warn', event, detail)` 上报，extension 侧注入
+ * extension-logger 适配、runtime 侧注入 console 适配。corrupt 隔离 warn 是排障
+ * 生命线，两侧适配必接。锁壳层的「registry write failed」warn 属各侧锁壳职责
+ * （写失败时条目停留 running 的降级决策在锁壳），不在本模块。
+ */
+
+/** registry 文件原语日志回调（落盘/console 通道由调用方适配注入）。 */
+type RegistryFileLogFn = (level: 'warn' | 'debug', event: string, detail?: unknown) => void;
+/** 终态裁剪入参的最小结构约束（泛型透传，保留调用方条目类型）。 */
+interface TrimTerminalEntryLike {
+    taskId: string;
+    startedAt: number;
+    endedAt?: number;
+    state: BackgroundTaskState;
+}
+/**
+ * 校验并归一化 registry 文件内容；形状非法返回 undefined（走 corrupt 隔离路径）。
+ * version 不匹配 / entries 非数组 → 整体非法；单条脏数据丢弃、不报废全表
+ * （契约 guard isBackgroundTaskRegistryEntry 复用）。
+ */
+declare function parseRegistryContent(raw: string): BackgroundTaskRegistryEntry[] | undefined;
+/** .corrupt 落点：固定名优先；已存在则带时间戳，不覆盖前一份现场。 */
+declare function corruptPathFor(registryPath: string): string;
+/**
+ * 读取 registry 全量条目 + 损坏标记（runtime 现形态为超集；extension 侧 Map 形态
+ * 由各侧薄壳投影）。UI 读侧需要区分「真的空表」与「损坏被隔离的空表」。
+ *
+ * 文件不存在 / 读失败 → 空表 + corrupted:false（常态/降级，非损坏）；解析失败 →
+ * 重命名 .corrupt 保留现场 + onLog warn + 空表 + corrupted:true（「空表重建」由
+ * 后续写入自然完成，不立即写空文件）。
+ */
+declare function readRegistry(registryPath: string, onLog?: RegistryFileLogFn): {
+    entries: BackgroundTaskRegistryEntry[];
+    corrupted: boolean;
+};
+/**
+ * registry 文件序列化（字节契约单点：version 锁定 + JSON indent 2 + 尾部换行）。
+ * 两侧写路径共用本函数——文件字节形态归一是 V4/P2 验收的前提。
+ */
+declare function serializeRegistryFile(entries: BackgroundTaskRegistryEntry[]): string;
+/**
+ * 原子写：tmp（pid+随机段唯一化防并发碰撞）+ rename（POSIX/Windows 均原子）；
+ * 失败清理 tmp 后向上抛原错误（锁壳层决定降级语义）。tmp 清理失败不掩盖原错误，
+ * 仅经 onLog 上报诊断。
+ */
+declare function atomicWriteRegistry(registryPath: string, content: string, onLog?: RegistryFileLogFn): void;
+/**
+ * 终态条目 LRU 裁剪（纯函数）：终态（exited/orphaned）按 `endedAt ?? startedAt`
+ * 升序、超上限淘汰最老；活跃条目（running/killing）永不淘汰；未超上限原样保留。
+ * 入参数组不被修改（sort 作用于 filter 产生的新数组），返回保留集新数组。
+ * extension task-store 与 registry 写侧、runtime registry-write 共用（max 由各侧
+ * 传参，上限值不变）。
+ */
+declare function trimTerminalEntries<T extends TrimTerminalEntryLike>(entries: T[], max: number): T[];
+
+/**
+ * 输出文件 tail 读取原语（末尾字节窗口 + 行/字节双上限）——跨端单一实现。
+ *
+ * 此前两侧各持一份逐行同构实现且签名已实际漂移（bte `(file, maxLines, maxBytes)`
+ * vs runtime `(file, maxBytes, maxLines)`；返回字段 `output` vs `text`）——本模块
+ * 定型单一签名：`(file, opts: { maxBytes, maxLines })` → `{ text, truncated }`
+ * （字段名取 runtime 的 `text`，比 `output` 中性且不与「输出文件」混淆）。
+ *
+ * 默认上限（bte 50KB / runtime 32KB）是各自产品决策，**留在各调用方**传参，
+ * 本模块不设默认值。
+ *
+ * 日志通道：零日志依赖——close 失败（已读完内容，不影响结果）的 debug 诊断经可选
+ * 回调 `onLog('debug', event, detail)` 上报，调用方不适配则静默。
+ */
+/** output-tail 日志回调（落盘/console 通道由调用方适配注入；close debug 可选）。 */
+type OutputTailLogFn = (level: 'warn' | 'debug', event: string, detail?: unknown) => void;
+/** tail 读取上限（字节/行双上限，先到为准；由调用方按产品口径传参）。 */
+interface OutputTailOptions {
+    maxBytes: number;
+    maxLines: number;
+}
+interface OutputTailResult {
+    text: string;
+    /** 读取窗口被截断（内容超任一上限）时 true。 */
+    truncated: boolean;
+}
+/**
+ * 读文件尾部（行/字节双上限）。文件不存在/不可读返回 undefined——调用方按
+ * 「输出丢失」降级，不崩溃。实现从文件末尾按字节窗口读（不整读大文件，
+ * O(maxBytes) 而非 O(fileSize)）。
+ */
+declare function readOutputTail(outputFile: string, opts: OutputTailOptions, onLog?: OutputTailLogFn): OutputTailResult | undefined;
+
+export { type OutputTailLogFn, type OutputTailOptions, type OutputTailResult, type ProcessFallbackLogger, type RegistryFileLogFn, type TrimTerminalEntryLike, atomicWriteRegistry, corruptPathFor, getProcessStartTimeSec, isPidAlive, killProcessTree, parseRegistryContent, pidStartMatchesRegistered, readOutputTail, readRegistry, serializeRegistryFile, trimTerminalEntries };

package/dist/background-task-entry.js

@@ -0,0 +1,217 @@
+import {
+  BACKGROUND_TASK_REGISTRY_VERSION,
+  isBackgroundTaskRegistryEntry,
+  isTerminalBackgroundTaskState
+} from "./chunk-NJ3E4ISR.js";
+
+// src/background-task-process.ts
+import { spawnSync } from "child_process";
+var PS_TIMEOUT_MS = 5e3;
+var MS_PER_SECOND = 1e3;
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function killProcessTree(pid, onFallback) {
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  if (process.platform === "win32") {
+    killProcessTreeWindows(pid, onFallback);
+    return;
+  }
+  try {
+    process.kill(-pid, "SIGKILL");
+    return;
+  } catch (err) {
+    onFallback?.("process-group-kill-missed", err);
+  }
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch (err) {
+    onFallback?.("single-pid-kill-missed", err);
+  }
+  killDescendantsRecursive(pid, onFallback);
+}
+function killProcessTreeWindows(pid, onFallback) {
+  try {
+    const result = spawnSync("taskkill", ["/F", "/T", "/PID", String(pid)], {
+      stdio: "ignore",
+      windowsHide: true
+    });
+    if (result.error) throw result.error;
+  } catch (err) {
+    onFallback?.("taskkill-failed", err);
+  }
+}
+function killDescendantsRecursive(pid, onFallback) {
+  let stdout;
+  try {
+    const result = spawnSync("pgrep", ["-P", String(pid)], { encoding: "utf8" });
+    if (result.error || result.status !== 0 || !result.stdout) return;
+    stdout = result.stdout;
+  } catch (err) {
+    onFallback?.("descendant-enumeration-failed", err);
+    return;
+  }
+  for (const line of stdout.split("\n")) {
+    const childPid = Number.parseInt(line.trim(), 10);
+    if (Number.isInteger(childPid) && childPid > 0) {
+      killDescendantsRecursive(childPid, onFallback);
+      try {
+        process.kill(childPid, "SIGKILL");
+      } catch (err) {
+        onFallback?.("descendant-kill-missed", err);
+      }
+    }
+  }
+}
+function getProcessStartTimeSec(pid) {
+  let result;
+  try {
+    result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf8",
+      timeout: PS_TIMEOUT_MS
+    });
+  } catch {
+    return void 0;
+  }
+  if (result.error || result.status !== 0 || !result.stdout) return void 0;
+  const ms = Date.parse(result.stdout.trim());
+  return Number.isNaN(ms) ? void 0 : Math.floor(ms / MS_PER_SECOND);
+}
+function pidStartMatchesRegistered(actualStartSec, registeredStartSec, startedAtMs) {
+  return registeredStartSec !== void 0 ? actualStartSec === registeredStartSec : actualStartSec <= Math.floor(startedAtMs / MS_PER_SECOND);
+}
+
+// src/background-task-registry-file.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { dirname } from "path";
+var JSON_INDENT = 2;
+var TMP_RADIX = 36;
+var TMP_SLICE_START = 2;
+var TMP_SLICE_END = 10;
+function parseRegistryContent(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) return void 0;
+  const { version, entries } = parsed;
+  if (version !== BACKGROUND_TASK_REGISTRY_VERSION || !Array.isArray(entries)) return void 0;
+  return entries.filter(isBackgroundTaskRegistryEntry);
+}
+function corruptPathFor(registryPath) {
+  const base = `${registryPath}.corrupt`;
+  return existsSync(base) ? `${base}-${Date.now()}` : base;
+}
+function readRegistry(registryPath, onLog) {
+  if (!existsSync(registryPath)) return { entries: [], corrupted: false };
+  let raw;
+  try {
+    raw = readFileSync(registryPath, "utf8");
+  } catch (err) {
+    onLog?.("warn", "registry read failed, treating as empty", { path: registryPath, err });
+    return { entries: [], corrupted: false };
+  }
+  const parsed = parseRegistryContent(raw);
+  if (parsed === void 0) {
+    const corruptPath = corruptPathFor(registryPath);
+    try {
+      renameSync(registryPath, corruptPath);
+      onLog?.("warn", "registry corrupted, quarantined and continuing with empty table", {
+        path: registryPath,
+        corruptPath
+      });
+    } catch (err) {
+      onLog?.("warn", "registry corrupted and quarantine rename failed, continuing with empty table in place", {
+        path: registryPath,
+        err
+      });
+    }
+    return { entries: [], corrupted: true };
+  }
+  return { entries: parsed, corrupted: false };
+}
+function serializeRegistryFile(entries) {
+  const shape = { version: BACKGROUND_TASK_REGISTRY_VERSION, entries };
+  return `${JSON.stringify(shape, null, JSON_INDENT)}
+`;
+}
+function atomicWriteRegistry(registryPath, content, onLog) {
+  mkdirSync(dirname(registryPath), { recursive: true });
+  const tmpPath = `${registryPath}.tmp_${process.pid}_${Math.random().toString(TMP_RADIX).slice(TMP_SLICE_START, TMP_SLICE_END)}`;
+  try {
+    writeFileSync(tmpPath, content, "utf8");
+    renameSync(tmpPath, registryPath);
+  } catch (err) {
+    try {
+      if (existsSync(tmpPath)) unlinkSync(tmpPath);
+    } catch (cleanupErr) {
+      onLog?.("warn", "registry tmp cleanup failed", { tmpPath, err: cleanupErr });
+    }
+    throw err;
+  }
+}
+function trimTerminalEntries(entries, max) {
+  const terminal = entries.filter((e) => isTerminalBackgroundTaskState(e.state)).sort((a, b) => (a.endedAt ?? a.startedAt) - (b.endedAt ?? b.startedAt));
+  const excess = terminal.length - max;
+  if (excess <= 0) return [...entries];
+  const evicted = new Set(terminal.slice(0, excess).map((e) => e.taskId));
+  return entries.filter((e) => !evicted.has(e.taskId));
+}
+
+// src/output-tail.ts
+import { openSync, readSync, closeSync, statSync } from "fs";
+var TAIL_WINDOW_MARGIN_BYTES = 64;
+function readOutputTail(outputFile, opts, onLog) {
+  const { maxBytes, maxLines } = opts;
+  let size;
+  try {
+    size = statSync(outputFile).size;
+  } catch {
+    return void 0;
+  }
+  const windowSize = Math.min(size, maxBytes + TAIL_WINDOW_MARGIN_BYTES);
+  const buffer = Buffer.alloc(windowSize);
+  let fd;
+  try {
+    fd = openSync(outputFile, "r");
+    readSync(fd, buffer, 0, windowSize, size - windowSize);
+  } catch {
+    return void 0;
+  } finally {
+    if (fd !== void 0) {
+      try {
+        closeSync(fd);
+      } catch (err) {
+        onLog?.("debug", "output tail close failed", { outputFile, err });
+      }
+    }
+  }
+  const text = buffer.toString("utf8");
+  const lines = text.split("\n");
+  const firstLineIsPartial = windowSize < size && lines.length > 0;
+  const effectiveLines = firstLineIsPartial ? lines.slice(1) : lines;
+  const byteTruncated = size > maxBytes;
+  const shown = effectiveLines.slice(-maxLines).join("\n");
+  return { text: shown, truncated: byteTruncated || effectiveLines.length > maxLines };
+}
+export {
+  atomicWriteRegistry,
+  corruptPathFor,
+  getProcessStartTimeSec,
+  isPidAlive,
+  killProcessTree,
+  parseRegistryContent,
+  pidStartMatchesRegistered,
+  readOutputTail,
+  readRegistry,
+  serializeRegistryFile,
+  trimTerminalEntries
+};

package/dist/chunk-NJ3E4ISR.js

@@ -0,0 +1,28 @@
+// src/background-task.ts
+var BACKGROUND_TASK_REGISTRY_FILENAME = "registry.json";
+var BASE_TOOL_ENHANCE_DIRNAME = "base-tool-enhance";
+var BACKGROUND_TASK_ID_PREFIX = "bt-";
+var BACKGROUND_TASK_REGISTRY_VERSION = 1;
+var MAX_TERMINAL_REGISTRY_ENTRIES = 50;
+function isActiveBackgroundTaskState(state) {
+  return state === "running" || state === "killing";
+}
+function isTerminalBackgroundTaskState(state) {
+  return state === "exited" || state === "orphaned";
+}
+function isBackgroundTaskRegistryEntry(item) {
+  if (typeof item !== "object" || item === null) return false;
+  const e = item;
+  return typeof e.taskId === "string" && typeof e.pid === "number" && typeof e.command === "string" && typeof e.outputFile === "string" && typeof e.startedAt === "number" && typeof e.state === "string" && typeof e.ownerPiPid === "number" && typeof e.sessionId === "string";
+}
+
+export {
+  BACKGROUND_TASK_REGISTRY_FILENAME,
+  BASE_TOOL_ENHANCE_DIRNAME,
+  BACKGROUND_TASK_ID_PREFIX,
+  BACKGROUND_TASK_REGISTRY_VERSION,
+  MAX_TERMINAL_REGISTRY_ENTRIES,
+  isActiveBackgroundTaskState,
+  isTerminalBackgroundTaskState,
+  isBackgroundTaskRegistryEntry
+};