@zhushanwen/extension-protocol 0.26.0 → 0.27.0

package/README.md

@@ -8,7 +8,7 @@ pi extension 跨层契约包：类型 + helper 函数 + 共享行为原语，零
 - `extensions/` —— 有运行时定制逻辑的 extension（marker + helper）
   - `ask-user/` —— 富交互（select 通道 + marker）
   - `plan/` —— plan 生命周期状态机 + 审阅回传值域契约 + 旧 entry legacy 读取（纯函数零 pi 依赖，扩展 / runtime / renderer 三层共用）
-  - `scheduler/` —— scheduler 任务条目契约 + entry 重放折叠（replayFoldEntries）+ 时间格式化（纯契约与纯函数，零 pi/node 依赖）
+  - `scheduler/` —— scheduler 任务条目契约 + 时间格式化（纯契约与纯函数，零 pi/node 依赖）；任务库快照文件契约 `store.ts`（含 node:fs/node:path，走独立子出口）
   - `scheduler-create/` —— scheduler 创建确认共享资产（ScheduleDraft / ScheduleFormResult 类型 + 形状与时间折叠检查 + marker）
   - `session-manager/` —— agent-managed session 嵌套 `{action, params}` 契约（select 通道 + marker）
   - `subagent-engine/` —— 引擎可发现性（`engines.json` 状态文件 + 引擎配置视图）
@@ -19,6 +19,7 @@ pi extension 跨层契约包：类型 + helper 函数 + 共享行为原语，零
 - `pending-entries` —— pending 事件流差集核心（register 去重 + unregister 抵消，纯算法）
 - `background-task` —— base-tool-enhance 后台任务 `registry.json` 文件契约
 - 子出口 `@zhushanwen/extension-protocol/background-task` —— 后台任务行为原语（进程处置 / registry 文件 IO / output tail，含 node 内建依赖，不进 index 桶出口）
+- 子出口 `@zhushanwen/extension-protocol/scheduler-store` —— scheduler 任务库快照文件契约（路径推导 `schedulerStoreFilePath` + 读改写原语，含 node 内建依赖，不进 index 桶出口）
 
 ## 设计原则
 

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

@@ -5,18 +5,21 @@ import { B as BackgroundTaskState, a as BackgroundTaskRegistryEntry } from './ba
  *
  * 契约两端（此前各持一份逐字同构实现，对齐手段是注释，已归一到本模块）：
  *  - extension 侧：@zhushanwen/pi-base-tool-enhance（bash_kill 前校验 / 后台 timeout
- *    到点校验 / 对账判死），原实现在其 kill-tree.ts
+ *    到点校验 / 对账判死），原实现在其 kill-tree.ts（归一前原仓库文件，本仓不可考）
  *  - runtime 侧：taiji background-task-reaper（孤儿收殓三分支判定），原实现在
- *    background-task-reaper.ts 原语区
+ *    background-task-reaper.ts 原语区（原语已归一迁出至本模块，该文件余部仍在 runtime）
  *
  * 分支语义（与 pi 实装对齐，勿单侧擅改）：Windows `taskkill /F /T`；POSIX 按进程组终止
- * `kill -- -<pgid>`（后台任务 detached spawn 自成进程组，pgid = pid）；按进程组终止不到时
- * 回退单 pid + `pgrep -P` 递归杀残留子进程。
+ * `kill -- -<pgid>`（后台任务 detached spawn 自成进程组，pgid = pid）；快路径落空时解析
+ * 目标真实 pgid（`ps -o pgid=`）按组杀——转后台任务组成员非组长形态（ADR-0184，组长
+ * 死后组仍有效）；解析出的组等于调用者自身进程组时跳过组杀（防自杀）落回退；均不可达
+ * 才回退单 pid + `pgrep -P` 递归杀残留子进程（先孙后子最后目标，防 reparent 逃逸枚举）。
  *
  * 日志通道：本模块零日志依赖（protocol 零运行时依赖纪律）——回退路径的诊断经可选
  * 回调 `onFallback(step, err)` 上报，extension 侧注入 logger.debug 适配、runtime 侧
  * 注入 console.debug 适配。step 为稳定短标识符：
  *  - 'process-group-kill-missed'      POSIX 进程组 kill 失败（组长已死），走回退
+ *  - 'resolved-group-kill-missed'     解析真实 pgid 的组 kill 失败，走回退（ADR-0184）
  *  - 'single-pid-kill-missed'         单 pid kill 失败（目标已死，幂等语义）
  *  - 'taskkill-failed'                Windows taskkill 失败
  *  - 'descendant-enumeration-failed'  pgrep 不可用/失败，放弃子孙枚举
@@ -31,10 +34,13 @@ type ProcessFallbackLogger = (step: string, err: unknown) => void;
 declare function isPidAlive(pid: number): boolean;
 /**
  * 杀整棵进程树（同步；收殓路径在 process.on("exit") 里跑，必须同步）。
- * POSIX 按进程组终止（pgid = pid）一次性覆盖全部子孙；按进程组终止不到（组长已死）回退
- * 单 pid + pgrep -P 递归清理残留子进程（先杀孙辈再杀子辈，防孙辈在父死后被
- * reparent 逃逸枚举）。Windows taskkill /F /T。幂等：目标已死时静默成功
- * （回退路径的诊断经 onFallback 上报，无回调则静默）。
+ * POSIX：优先按进程组终止——detached spawn 形态（显式后台任务）pgid = pid，kill(-pid)
+ * 一次覆盖全部子孙；pid 非组长（前台转后台任务复用前台进程链，pgid ≠ pid）时解析真实
+ * pgid 按组杀（reparent 不换组，组长死后组仍在）；均不可达时回退单 pid + pgrep -P
+ * 递归清理（先枚举杀孙辈再杀子辈、最后杀目标本身——防目标死后子进程被 reparent 逃逸
+ * 枚举）。解析出的 pgid 等于调用者自身进程组时跳过组杀（防自杀），走回退。
+ * Windows taskkill /F /T。幂等：目标已死时静默成功（回退路径的诊断经 onFallback
+ * 上报，无回调则静默）。
  */
 declare function killProcessTree(pid: number, onFallback?: ProcessFallbackLogger): void;
 /**
@@ -95,9 +101,12 @@ declare function corruptPathFor(registryPath: string): string;
  * 读取 registry 全量条目 + 损坏标记（runtime 现形态为超集；extension 侧 Map 形态
  * 由各侧薄壳派生）。UI 读侧需要区分「真的空表」与「损坏被隔离的空表」。
  *
- * 文件不存在 / 读失败 → 空表 + corrupted:false（常态/降级，非损坏）；解析失败 →
- * 重命名 .corrupt 保留现场 + onLog warn + 空表 + corrupted:true（「空表重建」由
- * 后续写入自然完成，不立即写空文件）。
+ * 文件不存在 → 空表 + corrupted:false（合法空态）；读失败（权限等，文件存在但不可读）
+ * → onLog warn + 抛错（禁止折叠成空表——读改写按空表合并写回会以空表重建唯一登记
+ * 文件，静默丢失全部既有条目；降级决策归调用方：写侧锁壳 {success:false} 留待重试、
+ * 收殓器跳过本目录下轮重试、读侧工具上抛为显式失败）；解析失败 → 重命名 .corrupt
+ * 保留现场 + onLog warn + 空表 + corrupted:true（「空表重建」由后续写入自然完成，
+ * 不立即写空文件）。
  */
 declare function readRegistry(registryPath: string, onLog?: RegistryFileLogFn): {
     entries: BackgroundTaskRegistryEntry[];

package/dist/background-task-entry.js

@@ -29,12 +29,35 @@ function killProcessTree(pid, onFallback) {
   } catch (err) {
     onFallback?.("process-group-kill-missed", err);
   }
+  const ownPgid = readPgid(process.pid);
+  const pgid = readPgid(pid);
+  if (pgid !== null && pgid > 1 && pgid !== ownPgid) {
+    try {
+      process.kill(-pgid, "SIGKILL");
+      return;
+    } catch (err) {
+      onFallback?.("resolved-group-kill-missed", err);
+    }
+  }
+  killDescendantsRecursive(pid, onFallback);
   try {
     process.kill(pid, "SIGKILL");
   } catch (err) {
     onFallback?.("single-pid-kill-missed", err);
   }
-  killDescendantsRecursive(pid, onFallback);
+}
+function readPgid(pid) {
+  try {
+    const result = spawnSync("ps", ["-o", "pgid=", "-p", String(pid)], {
+      encoding: "utf8",
+      timeout: PS_TIMEOUT_MS
+    });
+    if (result.error || result.status !== 0 || !result.stdout) return null;
+    const pgid = Number.parseInt(result.stdout.trim(), 10);
+    return Number.isInteger(pgid) && pgid > 0 ? pgid : null;
+  } catch {
+    return null;
+  }
 }
 function killProcessTreeWindows(pid, onFallback) {
   try {
@@ -50,7 +73,7 @@ function killProcessTreeWindows(pid, onFallback) {
 function killDescendantsRecursive(pid, onFallback) {
   let stdout;
   try {
-    const result = spawnSync("pgrep", ["-P", String(pid)], { encoding: "utf8" });
+    const result = spawnSync("pgrep", ["-P", String(pid)], { encoding: "utf8", timeout: PS_TIMEOUT_MS });
     if (result.error || result.status !== 0 || !result.stdout) return;
     stdout = result.stdout;
   } catch (err) {
@@ -116,8 +139,8 @@ function readRegistry(registryPath, onLog) {
   try {
     raw = readFileSync(registryPath, "utf8");
   } catch (err) {
-    onLog?.("warn", "registry read failed, treating as empty", { path: registryPath, err });
-    return { entries: [], corrupted: false };
+    onLog?.("warn", "registry read failed; propagating to caller (not treated as empty)", { path: registryPath, err });
+    throw err;
   }
   const parsed = parseRegistryContent(raw);
   if (parsed === void 0) {

package/dist/chunk-TFO4NW5X.js

@@ -0,0 +1,23 @@
+// src/extensions/scheduler/types.ts
+var SCHEDULER_STORE_SCHEMA_VERSION = 2;
+function isSchedulerStoreFile(data) {
+  if (!data || typeof data !== "object") return false;
+  const record = data;
+  if (record.schemaVersion !== SCHEDULER_STORE_SCHEMA_VERSION) return false;
+  if (!Array.isArray(record.tasks)) return false;
+  return record.tasks.every((t) => t !== null && typeof t === "object");
+}
+var HISTORY_LIMIT = 20;
+function appendExecutionRecord(task, at, status) {
+  task.history.push({ at, status });
+  if (task.history.length > HISTORY_LIMIT) task.history.shift();
+}
+var SCHEDULER_MODAL_VIEW_ID = "modal-scheduler-manager-scheduler-manager.panel";
+
+export {
+  SCHEDULER_STORE_SCHEMA_VERSION,
+  isSchedulerStoreFile,
+  HISTORY_LIMIT,
+  appendExecutionRecord,
+  SCHEDULER_MODAL_VIEW_ID
+};

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { S as ScheduleSpec, T as TaskKind } from './types-DcAmuFZ2.js';
+export { E as ExecutionRecord, H as HISTORY_LIMIT, a as SCHEDULER_MODAL_VIEW_ID, b as SCHEDULER_STORE_SCHEMA_VERSION, c as ScheduledTask, d as SchedulerStoreFile, e as TaskStatus, f as appendExecutionRecord, i as isSchedulerStoreFile } from './types-DcAmuFZ2.js';
 export { b as BACKGROUND_TASK_ID_PREFIX, c as BACKGROUND_TASK_REGISTRY_FILENAME, d as BACKGROUND_TASK_REGISTRY_VERSION, e as BASE_TOOL_ENHANCE_DIRNAME, f as BackgroundTaskEndReason, a as BackgroundTaskRegistryEntry, g as BackgroundTaskRegistryFile, B as BackgroundTaskState, M as MAX_TERMINAL_REGISTRY_ENTRIES, i as isActiveBackgroundTaskState, h as isBackgroundTaskRegistryEntry, j as isTerminalBackgroundTaskState } from './background-task-B53rQ-4Q.js';
 
 /**
@@ -631,164 +633,6 @@ declare function getAskUserOther(answers: AskUserAnswers, question: AskUserQuest
  */
 declare function isAskUserQuestion(value: unknown): value is AskUserQuestion;
 
-type ScheduleSpec = {
-    mode: 'cron';
-    cronExpression: string;
-} | {
-    mode: 'interval';
-    intervalMs: number;
-};
-type TaskKind = 'once' | 'recurring';
-type TaskStatus = 'success' | 'failed';
-interface ScheduledTask {
-    id: string;
-    name: string;
-    prompt: string;
-    kind: TaskKind;
-    schedule: ScheduleSpec;
-    model?: string;
-    enabled: boolean;
-    createdAt: number;
-    nextRunAt: number;
-    expiresAt?: number;
-    runCount: number;
-    lastRunAt?: number;
-    lastStatus?: TaskStatus;
-    lastError?: string;
-    history: ExecutionRecord[];
-    ownerSessionFile?: string;
-    pending?: boolean;
-}
-interface ExecutionRecord {
-    at: number;
-    status: TaskStatus;
-}
-/**
- * history 裁剪上限（ext-simplify-08 L5 单点）：runtime 侧 dispatch 累积
- * （onDispatchSuccess）与 replay 侧 advance 折叠共用同一上限——
- * 双处各持字面量会漂移（曾 runtime.ts / replay.ts 各写一份 20），收敛到本文件单点导出。
- */
-declare const HISTORY_LIMIT = 20;
-/**
- * 追加执行记录并按 HISTORY_LIMIT 裁剪（ext-simplify-17 B4 单点）：runtime 侧 dispatch
- * 累积与 replay 侧 advance 折叠共用的 push+trim——三处内联时与上限字面量同源存在
- * 「漏改一处」漂移风险，随上限一并收敛。
- */
-declare function appendExecutionRecord(task: ScheduledTask, at: number, status: TaskStatus): void;
-/**
- * pi.appendEntry 写入的 custom entry customType 标识（ext-simplify-17 B1 单点）：
- * backend.appendEntry 写入 / replay 折叠过滤 / importer 旧 store 导入三处共用——
- * 各持字面量时「改一处漏两处」会使写入与重放识别脱节（写入新标识、重放不认，任务静默丢失）。
- */
-declare const TASK_ENTRY_TYPE = "pi-scheduler:task";
-/**
- * upsert op 携带的全量任务快照（不含 ownerSessionFile / pending）。
- * ownerSessionFile 放在 op 顶层（见 SchedulerEntryOp.upsert），
- * pending 是运行时标记不持久化。其余字段与 ScheduledTask 对齐。
- */
-interface TaskSnapshot {
-    id: string;
-    name: string;
-    prompt: string;
-    kind: TaskKind;
-    schedule: ScheduleSpec;
-    model?: string;
-    enabled: boolean;
-    createdAt: number;
-    nextRunAt: number;
-    expiresAt?: number;
-    runCount: number;
-    lastRunAt?: number;
-    lastStatus?: TaskStatus;
-    lastError?: string;
-    history: ExecutionRecord[];
-}
-/**
- * pi.appendEntry(TASK_ENTRY_TYPE, SchedulerEntryOp) 写入 session JSONL 的 op 联合类型。
- *
- * advance.status 固定为 'success'（CL8）：对齐现有 TaskStatus='success'|'failed'，
- * 而非继承的 DM-SCHEDULER-OP 词表 'ok'。唯一 emit 值——按 CL7，advance 仅在 dispatch
- * 成功（nextRunAt 实际推进）时 append，失败 dispatch 不 append（transient 失败重试语义）。
- * fold 的 `task.lastStatus = entry.status` 直接赋值合法（'success' 属 TaskStatus）。
- */
-type SchedulerEntryOp = {
-    op: 'upsert';
-    taskId: string;
-    ownerSessionFile: string;
-    task: TaskSnapshot;
-} | {
-    op: 'advance';
-    taskId: string;
-    nextRunAt: number;
-    at: number;
-    status: 'success';
-} | {
-    op: 'toggle';
-    taskId: string;
-    enabled: boolean;
-    nextRunAt?: number;
-} | {
-    op: 'delete';
-    taskId: string;
-};
-/**
- * TaskSnapshot → ScheduledTask（replay 侧重建）：pending 不持久化故不恢复，
- * ownerSessionFile 由调用方（replay applyUpsert）从 op 顶层补回。history 逐项深拷贝——
- * 避免恢复出的运行时 task 与快照共享数组/元素引用（task 后续被 mutate 时不污染快照）。
- */
-declare function snapshotToTask(snapshot: TaskSnapshot): ScheduledTask;
-/**
- * scheduler-manager 插件推树的 overlay 定时任务 tab ViewHost 分区键（历史命名
- * modal-<pluginId>-<modalId>，modal 链退役后原值保留）：插件 views.update 推树与
- * taiji renderer ViewHost 消费跨包共用本单源——双端各持字面量时任一端漂移即
- * ViewHost per-session 分区静默 miss（tab 空白无报错），收敛到本文件单点导出。
- */
-declare const SCHEDULER_MODAL_VIEW_ID = "modal-scheduler-manager-scheduler-manager.panel";
-
-/**
- * 折叠期降级日志注入点：包内不持有任何 logger 依赖（零 pi 依赖收敛），由调用方注入。
- * 省略时降级路径静默（折叠行为不受影响——返回值与注入无关）。
- */
-interface ReplayFoldOptions {
-    warn?: (message: string, context?: unknown) => void;
-}
-/**
- * CustomEntry 的最小可识别形状（duck-typed，不依赖 @earendil-works/pi-coding-agent 的
- * 具体 SessionEntry 类型）。与 pending-notifications/state.ts、goal/ports.ts 同款：
- * 纯函数可独立单测，调用方传入真实 SessionEntry[] 时按结构兼容。
- */
-interface SchedulerEntryLike {
-    type: string;
-    customType?: string;
-    data?: unknown;
-}
-/**
- * 从 CustomEntry 序列折叠恢复 per-task 末态（event sourcing）。
- *
- * 两类调用方：
- * - pi 扩展 session_start 重放：PiSchedulerBackend.loadTasks() 委托本函数，把当前 session 的
- *   TASK_ENTRY_TYPE custom entries 折叠成运行时任务 Map。
- * - taiji plugin 条目镜像：对 readEntries 拉取的累计 entries 调用本函数折叠出任务表
- *   （与扩展同一实现，插件与扩展折叠结果构造性一致）。
- *
- * 两步：
- * ① 全量折叠（foldEntries）——遍历 customType===TASK_ENTRY_TYPE 的 entries，按 op 类型折叠：
- *    - upsert → 用快照重建任务（ownerSessionFile 来自 op 顶层）
- *    - advance → nextRunAt=新值 / lastRunAt=at / runCount++ / history.push(裁20) / lastStatus=status（gap2）
- *    - toggle → enabled=新值
- *    - delete → 从 Map 移除（后续同 taskId 的 advance/toggle 对不存在 taskId 为 no-op，安全）
- *   advance/toggle/delete 对不存在的 taskId 为 no-op，因此 fork 继承的完整序列必须先全量折叠，
- *   不能在处理 upsert 时按 owner 跳过（否则后续无 owner 字段的 op 会作用于「不存在的 taskId」丢失）。
- * ② 折叠完成后按 task.ownerSessionFile !== currentSessionFile 整体过滤（gap1，filterNonOwnerTasks）：
- *   移除 fork 继承的非 owner 任务——fork 出的 session B 继承了 owner=A 的 upsert+advance 序列，
- *   但 B 不应拥有 A 的任务，重放后整体过滤掉。
- *
- * append-only 时序保证 nextRunAt 不回退（D1）：advance entry 按写入顺序折叠，自然取到最后推进值。
- *
- * getEntries 解析/迭代异常 → options.warn + 返回空 Map（gap4）：降级为无任务而非崩溃调用方。
- */
-declare function replayFoldEntries(entries: Iterable<SchedulerEntryLike>, currentSessionFile: string | undefined, options?: ReplayFoldOptions): Map<string, ScheduledTask>;
-
 declare const MS_PER_DAY = 86400000;
 declare const MS_PER_HOUR = 3600000;
 declare const MS_PER_MINUTE = 60000;
@@ -1733,6 +1577,34 @@ declare const SUBAGENT_BG_NOTIFY_CUSTOM_TYPE: "subagent-bg-notify";
  *  上下文 + renderer 定向气泡）。shared parseSubagentDirective / runtime display 覆写消费。 */
 declare const SUBAGENT_DIRECTIVE_CUSTOM_TYPE: "subagent-directive";
 
+/**
+ * smart-context 扩展通知通道的 custom_message customType 单源（subagent-notify 词表同款跨层契约）。
+ *
+ * 契约两端（值逐字节依赖，改名 = 跨侧破坏性变更）：
+ *   - 写侧：@zhushanwen/pi-smart-context extension（阈值/模型/压缩结果可见通知 +
+ *     后台压缩落盘信号，均经 pi.sendMessage 落 custom_message entry 进 session JSONL）；
+ *   - 读侧：taiji runtime event-interpreter（落盘信号分诊：customType + details.source
+ *     双判据，命中后合成分界行帧）。
+ *
+ * 历史上 customType 常量只在扩展本地定义（runtime 分诊引入前无跨层消费者），收敛本单源
+ * 后两侧 import 同一常量，值漂移结构性不可能（扩展侧 re-export 保持既有 import 路径不变）。
+ */
+/** smart-context 通知的送达 customType（对话流可见性由 display 字段区分，非 customType）。 */
+declare const SMART_CONTEXT_NOTICE_CUSTOM_TYPE: "smart-context";
+/** 后台压缩落盘信号的 details.source 取值：compaction entry 已 append 进 session 文件。 */
+declare const COMPACTION_ENTRY_APPENDED_SOURCE: "compaction-entry-appended";
+/** 落盘信号的判读结果（compactionId 缺失时 undefined，消费方走尾部兜底取最近 compaction entry）。 */
+interface CompactionPersistSignal {
+    compactionId?: string;
+}
+/**
+ * 防御性解析后台压缩落盘信号的 details（runtime 分诊判据，parseBgNotifyDetails 同款范式）。
+ *
+ * 命中 = source 为落盘信号词（customType 判定在消费方先行，本函数只裁 details）。
+ * 非对象形态 / source 不符 → null（非目标信号）；compactionId 非串 → undefined（降级尾部兜底）。
+ */
+declare function parseCompactionPersistSignal(details: unknown): CompactionPersistSignal | null;
+
 /**
  * 子代理引擎契约（U7 引擎可发现性 + GUI 引擎选择）。
  *
@@ -2687,4 +2559,47 @@ type ResolvedSettlementReason = SettlementReason | 'unknown';
  */
 declare function resolveSettlementReason(reason: string): ResolvedSettlementReason;
 
-export { ACTION_EVENT_MAP, ASK_USER_MARKER, type ArgumentMateriality, type ArgumentPolarity, type AskUserAnswers, type AskUserOption, type AskUserQuestion, CANVAS_ACTIONS, CANVAS_ACTOR_MATRIX, CANVAS_ERROR_CODES, CANVAS_ERROR_RECOVERY, CANVAS_EVENT_TYPES, CANVAS_MARKER, CANVAS_MARKER_ACTIONS, CANVAS_TOOL_NAMES, type CanvasAction, type CanvasActionParams, type CanvasActor, type CanvasComment, type CanvasCommentParams, type CanvasCommentRespondParams, type CanvasConvergeCheckParams, type CanvasCreateParams, type CanvasDecideDirectionParams, type CanvasDirectionDecision, type CanvasDispatchParams, type CanvasEdge, type CanvasEdgeType, type CanvasEnterParams, type CanvasError, type CanvasErrorCode, type CanvasEventType, type CanvasExportParams, type CanvasExportTarget, type CanvasGrowItem, type CanvasGrowParams, type CanvasListEntry, type CanvasListParams, type CanvasListReply, type CanvasMarkerAction, type CanvasMarkerParams, type CanvasMarkerRequest, type CanvasMutateReply, type CanvasMutateRequest, type CanvasNode, type CanvasNodeLifecycle, type CanvasNodeType, type CanvasPatchParams, type CanvasReadParams, type CanvasReadReply, type CanvasReviewAppendParams, type CanvasReviewEntryInput, type CanvasReviewRequestParams, type CanvasReviewResolveParams, type CanvasSelectParams, type CanvasState, type CanvasToolName, type CanvasTransitionParams, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type DualWidgetContent, type ExecutionRecord, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, HISTORY_LIMIT, type HostContainerAction, INFLIGHT_REPORT_ACK, JOURNAL_REPORT_ACK, MAPPED_PENDING_STATUSES, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, NON_TOOL_ACTIONS, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PERMISSION_APPROVAL_TITLE, PLAN_LIFECYCLE_EVENTS, PLAN_LIFECYCLE_STATES, PLAN_REVIEW_MARKER, PLAN_SELF_REVIEW_MAX_BYTES, PLAN_STATE_CUSTOM_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, type PendingFieldsScan, type PlanDocMeta, type PlanLifecycleEvent, type PlanLifecycleState, type PlanPhase, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type PlanReviewResponseEnvelope, type PlanTransitionResult, type ReplayFoldOptions, type ResolvedSettlementReason, type ReviewDimension, type ReviewEntry, type ReviewReport, type ReviewReportStatus, type ReviewResolutionDisposition, type ReviewSeverity, SCHEDULER_MODAL_VIEW_ID, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SETTLEMENT_REASONS, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, SUBAGENT_JOURNAL_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, type ScheduleSpec, type ScheduledTask, type SchedulerEntryLike, type SchedulerEntryOp, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerArchiveParams, type SessionManagerArchiveResult, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerDeleteParams, type SessionManagerDeleteResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type SettlementReason, type StatItem, type SubagentEngineConfigView, type SubagentEngineModelInfo, type SubagentEnginesFile, type SubagentFailureLike, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, type SubagentProjectionRecord, type SupportRating, TASK_ENTRY_TYPE, TOOL_ACTION_MAP, type TaskKind, type TaskSnapshot, type TaskStatus, type TextQuestion, type TreeItem, type TreeItemIcon, UI_FORM_MARKER, type UiFormInteractOptions, type UiFormInteractResult, WORKFLOW_RESULT_CUSTOM_TYPE, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, allCanvasActions, allToolActions, appendExecutionRecord, applyPendingDiff, callMarkerRpc, canvasError, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, failedRoundOf, failureCauseLabel, firstContentText, firstLine, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isActionAllowed, isArgumentMateriality, isArgumentPolarity, isAskUserQuestion, isCanvasCommentParams, isCanvasCommentRespondParams, isCanvasConvergeCheckParams, isCanvasCreateParams, isCanvasDecideDirectionParams, isCanvasDispatchParams, isCanvasEnterParams, isCanvasExportParams, isCanvasGrowParams, isCanvasListParams, isCanvasMarkerRequest, isCanvasPatchParams, isCanvasReadParams, isCanvasReviewAppendParams, isCanvasReviewRequestParams, isCanvasReviewResolveParams, isCanvasSelectParams, isCanvasTransitionParams, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isJournalReportAck, isPlanReviewRequest, isPlanReviewResponse, isRunningProjection, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerArchiveParams, isSessionManagerCreateParams, isSessionManagerDeleteParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSubagentJournalReport, mapReasonToStatus, onceCronToDate, parsePlanReviewResponse, readDetailsSummary, readLifecycleState, readResumeHint, replayFoldEntries, resolveSettlementReason, resultContentText, scanPendingEntries, scanPendingFields, setWidgetDual, snapshotToTask, toolOfAction, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };
+/**
+ * base-tool-enhance 空闲转后台阈值（idleBackgroundSec）跨层契约（跨层 SSOT）。
+ *
+ * 契约两端：
+ *  - 配置权威侧：@zhushanwen/pi-base-tool-enhance extension（config.ts
+ *    loadBaseToolEnhanceConfig；键级 warn/文案属扩展配置系统 UX，留扩展侧——
+ *    本文件只承载值语义，anomaly 字段供扩展侧生成 warn）。
+ *  - 消费侧 1：包装脚本 --idle 参数（bash 文本协议，只接受非负整数秒——小数放行会
+ *    使配置层值空间与执行层可接受值空间出现差集，差集配置下全部前台命令 exit 64，
+ *    故归一化收敛为整数且 floor 后 <1 抬到 1：--idle 0 语义是「首轮监控即转后台」，
+ *    不是亚秒阈值的合理近似）。
+ *  - 消费侧 2：taiji runtime 静默判定矩阵 T 公式（T = idleBackgroundSec + 300s，
+ *    packages/runtime event-interpreter-silence）——runtime 侧直 import 本实现，
+ *    禁止镜像副本（历史事故：两侧手抄归一化无机器绑定，超大值 clamp 语义漂移）。
+ *
+ * 显式 null 与 undefined 分流的理由：undefined = 未配置（默认开启 600）；显式 null =
+ * 用户关闭（透传 null，下游据此回落 pi 官方原生无限等待）；坏值 = 回退默认而非关闭
+ * （显式 null 是唯一关闭通道，坏值不得意外关闭机制）。
+ */
+/**
+ * idleBackgroundSec 默认值（秒）：正常工具调用分钟级、编译静默常见 1-5 分钟，10 分钟
+ * 输出静默在交互会话已是强异常信号。
+ */
+declare const DEFAULT_IDLE_BACKGROUND_SEC = 600;
+/**
+ * 归一化结果：value 恒为可直接消费的生效值（合法输入 = 非负整数秒；显式 null = null；
+ * undefined/坏值 = 默认 600）；anomaly 非空表示输入异常（调用方据此落 warn，不据此
+ * 改值——value 已是回退/截断后的生效值）。
+ *  - 'invalid'：类型错/负数/0/非有限 → 回退默认（value = DEFAULT_IDLE_BACKGROUND_SEC）
+ *  - 'clamped'：换算毫秒超 int32 上限 → 截断（value = floor(int32 ms 对应秒数)）
+ */
+interface IdleBackgroundSecNormalization {
+    value: number | null;
+    anomaly: 'invalid' | 'clamped' | null;
+}
+/**
+ * idleBackgroundSec 归一化（跨层唯一实现，禁镜像）：
+ * undefined → 默认 600（未配置）；null → null（显式关闭）；正有限数 → floor ≥ 1 的
+ * 整数秒（换算毫秒超 int32 上限先截断，anomaly = 'clamped'）；其余坏值 → 默认 600
+ * （anomaly = 'invalid'）。
+ */
+declare function normalizeIdleBackgroundSec(raw: unknown): IdleBackgroundSecNormalization;
+
+export { ACTION_EVENT_MAP, ASK_USER_MARKER, type ArgumentMateriality, type ArgumentPolarity, type AskUserAnswers, type AskUserOption, type AskUserQuestion, CANVAS_ACTIONS, CANVAS_ACTOR_MATRIX, CANVAS_ERROR_CODES, CANVAS_ERROR_RECOVERY, CANVAS_EVENT_TYPES, CANVAS_MARKER, CANVAS_MARKER_ACTIONS, CANVAS_TOOL_NAMES, COMPACTION_ENTRY_APPENDED_SOURCE, type CanvasAction, type CanvasActionParams, type CanvasActor, type CanvasComment, type CanvasCommentParams, type CanvasCommentRespondParams, type CanvasConvergeCheckParams, type CanvasCreateParams, type CanvasDecideDirectionParams, type CanvasDirectionDecision, type CanvasDispatchParams, type CanvasEdge, type CanvasEdgeType, type CanvasEnterParams, type CanvasError, type CanvasErrorCode, type CanvasEventType, type CanvasExportParams, type CanvasExportTarget, type CanvasGrowItem, type CanvasGrowParams, type CanvasListEntry, type CanvasListParams, type CanvasListReply, type CanvasMarkerAction, type CanvasMarkerParams, type CanvasMarkerRequest, type CanvasMutateReply, type CanvasMutateRequest, type CanvasNode, type CanvasNodeLifecycle, type CanvasNodeType, type CanvasPatchParams, type CanvasReadParams, type CanvasReadReply, type CanvasReviewAppendParams, type CanvasReviewEntryInput, type CanvasReviewRequestParams, type CanvasReviewResolveParams, type CanvasSelectParams, type CanvasState, type CanvasToolName, type CanvasTransitionParams, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type CompactionPersistSignal, DEFAULT_IDLE_BACKGROUND_SEC, type DualWidgetContent, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, type HostContainerAction, INFLIGHT_REPORT_ACK, type IdleBackgroundSecNormalization, JOURNAL_REPORT_ACK, MAPPED_PENDING_STATUSES, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, NON_TOOL_ACTIONS, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PERMISSION_APPROVAL_TITLE, PLAN_LIFECYCLE_EVENTS, PLAN_LIFECYCLE_STATES, PLAN_REVIEW_MARKER, PLAN_SELF_REVIEW_MAX_BYTES, PLAN_STATE_CUSTOM_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, type PendingFieldsScan, type PlanDocMeta, type PlanLifecycleEvent, type PlanLifecycleState, type PlanPhase, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type PlanReviewResponseEnvelope, type PlanTransitionResult, type ResolvedSettlementReason, type ReviewDimension, type ReviewEntry, type ReviewReport, type ReviewReportStatus, type ReviewResolutionDisposition, type ReviewSeverity, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SETTLEMENT_REASONS, SMART_CONTEXT_NOTICE_CUSTOM_TYPE, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, SUBAGENT_JOURNAL_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, ScheduleSpec, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerArchiveParams, type SessionManagerArchiveResult, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerDeleteParams, type SessionManagerDeleteResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type SettlementReason, type StatItem, type SubagentEngineConfigView, type SubagentEngineModelInfo, type SubagentEnginesFile, type SubagentFailureLike, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, type SubagentProjectionRecord, type SupportRating, TOOL_ACTION_MAP, TaskKind, type TextQuestion, type TreeItem, type TreeItemIcon, UI_FORM_MARKER, type UiFormInteractOptions, type UiFormInteractResult, WORKFLOW_RESULT_CUSTOM_TYPE, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, allCanvasActions, allToolActions, applyPendingDiff, callMarkerRpc, canvasError, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, failedRoundOf, failureCauseLabel, firstContentText, firstLine, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isActionAllowed, isArgumentMateriality, isArgumentPolarity, isAskUserQuestion, isCanvasCommentParams, isCanvasCommentRespondParams, isCanvasConvergeCheckParams, isCanvasCreateParams, isCanvasDecideDirectionParams, isCanvasDispatchParams, isCanvasEnterParams, isCanvasExportParams, isCanvasGrowParams, isCanvasListParams, isCanvasMarkerRequest, isCanvasPatchParams, isCanvasReadParams, isCanvasReviewAppendParams, isCanvasReviewRequestParams, isCanvasReviewResolveParams, isCanvasSelectParams, isCanvasTransitionParams, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isJournalReportAck, isPlanReviewRequest, isPlanReviewResponse, isRunningProjection, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerArchiveParams, isSessionManagerCreateParams, isSessionManagerDeleteParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSubagentJournalReport, mapReasonToStatus, normalizeIdleBackgroundSec, onceCronToDate, parseCompactionPersistSignal, parsePlanReviewResponse, readDetailsSummary, readLifecycleState, readResumeHint, resolveSettlementReason, resultContentText, scanPendingEntries, scanPendingFields, setWidgetDual, toolOfAction, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };

package/dist/index.js

@@ -8,6 +8,13 @@ import {
   isBackgroundTaskRegistryEntry,
   isTerminalBackgroundTaskState
 } from "./chunk-NJ3E4ISR.js";
+import {
+  HISTORY_LIMIT,
+  SCHEDULER_MODAL_VIEW_ID,
+  SCHEDULER_STORE_SCHEMA_VERSION,
+  appendExecutionRecord,
+  isSchedulerStoreFile
+} from "./chunk-TFO4NW5X.js";
 
 // src/core/types.ts
 var PROTOCOL_VERSION = 1;
@@ -206,125 +213,6 @@ function isAskUserQuestion(value) {
   return typeof q.question === "string" && (q.header === void 0 || typeof q.header === "string") && (q.options === void 0 || Array.isArray(q.options)) && (q.multiSelect === void 0 || typeof q.multiSelect === "boolean") && (q.allowOther === void 0 || typeof q.allowOther === "boolean");
 }
 
-// src/extensions/scheduler/types.ts
-var HISTORY_LIMIT = 20;
-function appendExecutionRecord(task, at, status) {
-  task.history.push({ at, status });
-  if (task.history.length > HISTORY_LIMIT) task.history.shift();
-}
-var TASK_ENTRY_TYPE = "pi-scheduler:task";
-function snapshotToTask(snapshot) {
-  return {
-    id: snapshot.id,
-    name: snapshot.name,
-    prompt: snapshot.prompt,
-    kind: snapshot.kind,
-    schedule: snapshot.schedule,
-    model: snapshot.model,
-    enabled: snapshot.enabled,
-    createdAt: snapshot.createdAt,
-    nextRunAt: snapshot.nextRunAt,
-    expiresAt: snapshot.expiresAt,
-    runCount: snapshot.runCount,
-    lastRunAt: snapshot.lastRunAt,
-    lastStatus: snapshot.lastStatus,
-    lastError: snapshot.lastError,
-    history: snapshot.history.map((h) => ({ ...h }))
-  };
-}
-var SCHEDULER_MODAL_VIEW_ID = "modal-scheduler-manager-scheduler-manager.panel";
-
-// src/extensions/scheduler/replay.ts
-function toErrorMessage(e) {
-  return e instanceof Error ? e.message : String(e);
-}
-function replayFoldEntries(entries, currentSessionFile, options) {
-  try {
-    const tasks = /* @__PURE__ */ new Map();
-    foldEntries(entries, tasks, options);
-    filterNonOwnerTasks(tasks, currentSessionFile);
-    return tasks;
-  } catch (err) {
-    options?.warn?.("replayFoldEntries failed", { error: toErrorMessage(err) });
-    return /* @__PURE__ */ new Map();
-  }
-}
-function foldEntries(entries, tasks, options) {
-  for (const entry of entries) {
-    if (entry.type !== "custom" || entry.customType !== TASK_ENTRY_TYPE) continue;
-    if (!isSchedulerEntryOp(entry.data)) continue;
-    const op = entry.data;
-    try {
-      applyOp(tasks, op);
-    } catch (err) {
-      options?.warn?.("skipping corrupted scheduler entry", { error: toErrorMessage(err) });
-      continue;
-    }
-  }
-}
-function applyOp(tasks, op) {
-  switch (op.op) {
-    case "upsert":
-      applyUpsert(tasks, op);
-      break;
-    case "advance":
-      applyAdvance(tasks, op);
-      break;
-    case "toggle":
-      applyToggle(tasks, op);
-      break;
-    case "delete":
-      applyDelete(tasks, op);
-      break;
-  }
-}
-function applyUpsert(tasks, op) {
-  tasks.set(op.taskId, { ...snapshotToTask(op.task), ownerSessionFile: op.ownerSessionFile });
-}
-function applyAdvance(tasks, op) {
-  const task = tasks.get(op.taskId);
-  if (!task) return;
-  task.nextRunAt = op.nextRunAt;
-  task.lastRunAt = op.at;
-  task.runCount += 1;
-  appendExecutionRecord(task, op.at, op.status);
-  task.lastStatus = op.status;
-}
-function applyToggle(tasks, op) {
-  const task = tasks.get(op.taskId);
-  if (!task) return;
-  task.enabled = op.enabled;
-  if (op.nextRunAt !== void 0) task.nextRunAt = op.nextRunAt;
-}
-function applyDelete(tasks, op) {
-  tasks.delete(op.taskId);
-}
-function filterNonOwnerTasks(tasks, currentSessionFile) {
-  for (const [id, task] of tasks) {
-    if (task.ownerSessionFile !== currentSessionFile) {
-      tasks.delete(id);
-    }
-  }
-}
-function isSchedulerEntryOp(data) {
-  if (!data || typeof data !== "object") return false;
-  const record = data;
-  const op = record.op;
-  if (op === "upsert") {
-    return typeof record.taskId === "string" && typeof record.task === "object" && record.task !== null;
-  }
-  if (op === "advance") {
-    return typeof record.taskId === "string" && typeof record.nextRunAt === "number" && typeof record.at === "number" && record.status === "success";
-  }
-  if (op === "toggle") {
-    return typeof record.taskId === "string" && typeof record.enabled === "boolean" && (record.nextRunAt === void 0 || typeof record.nextRunAt === "number");
-  }
-  if (op === "delete") {
-    return typeof record.taskId === "string";
-  }
-  return false;
-}
-
 // src/extensions/scheduler/format.ts
 var MS_PER_DAY = 864e5;
 var MS_PER_HOUR = 36e5;
@@ -851,6 +739,16 @@ var WORKFLOW_RESULT_CUSTOM_TYPE = "workflow-result";
 var SUBAGENT_BG_NOTIFY_CUSTOM_TYPE = "subagent-bg-notify";
 var SUBAGENT_DIRECTIVE_CUSTOM_TYPE = "subagent-directive";
 
+// src/extensions/smart-context/notify-types.ts
+var SMART_CONTEXT_NOTICE_CUSTOM_TYPE = "smart-context";
+var COMPACTION_ENTRY_APPENDED_SOURCE = "compaction-entry-appended";
+function parseCompactionPersistSignal(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) return null;
+  const d = details;
+  if (d.source !== COMPACTION_ENTRY_APPENDED_SOURCE) return null;
+  return { compactionId: typeof d.compactionId === "string" ? d.compactionId : void 0 };
+}
+
 // src/extensions/subagent-engine/contract.ts
 var SUBAGENTS_ENGINES_FILENAME = "engines.json";
 
@@ -1313,6 +1211,23 @@ function resolveSettlementReason(reason) {
   return SETTLEMENT_REASON_MAP[reason] ?? "unknown";
 }
 var SETTLEMENT_REASON_KEYS = new Set(Object.keys(SETTLEMENT_REASON_MAP));
+
+// src/background-idle-config.ts
+var INT32_MAX_MS = 2147483647;
+var MS_PER_SECOND2 = 1e3;
+var DEFAULT_IDLE_BACKGROUND_SEC = 600;
+function normalizeIdleBackgroundSec(raw) {
+  if (raw === null) return { value: null, anomaly: null };
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+    const ms = raw * MS_PER_SECOND2;
+    if (ms > INT32_MAX_MS) {
+      return { value: Math.floor(INT32_MAX_MS / MS_PER_SECOND2), anomaly: "clamped" };
+    }
+    return { value: Math.max(1, Math.floor(raw)), anomaly: null };
+  }
+  if (raw !== void 0) return { value: DEFAULT_IDLE_BACKGROUND_SEC, anomaly: "invalid" };
+  return { value: DEFAULT_IDLE_BACKGROUND_SEC, anomaly: null };
+}
 export {
   ACTION_EVENT_MAP,
   ASK_USER_MARKER,
@@ -1328,6 +1243,8 @@ export {
   CANVAS_MARKER,
   CANVAS_MARKER_ACTIONS,
   CANVAS_TOOL_NAMES,
+  COMPACTION_ENTRY_APPENDED_SOURCE,
+  DEFAULT_IDLE_BACKGROUND_SEC,
   GUI_WIDGET_MARKER,
   HISTORY_LIMIT,
   INFLIGHT_REPORT_ACK,
@@ -1349,16 +1266,17 @@ export {
   PLAN_STATE_CUSTOM_TYPE,
   PROTOCOL_VERSION,
   SCHEDULER_MODAL_VIEW_ID,
+  SCHEDULER_STORE_SCHEMA_VERSION,
   SCHEDULE_CREATE_MARKER,
   SESSION_MANAGER_ACTIONS,
   SESSION_MANAGER_MARKER,
   SETTLEMENT_REASONS,
+  SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
   SUBAGENTS_ENGINES_FILENAME,
   SUBAGENT_BG_NOTIFY_CUSTOM_TYPE,
   SUBAGENT_DIRECTIVE_CUSTOM_TYPE,
   SUBAGENT_INFLIGHT_MARKER,
   SUBAGENT_JOURNAL_MARKER,
-  TASK_ENTRY_TYPE,
   TOOL_ACTION_MAP,
   UI_FORM_MARKER,
   WORKFLOW_RESULT_CUSTOM_TYPE,
@@ -1422,6 +1340,7 @@ export {
   isRunningProjection,
   isScheduleDraft,
   isScheduleFormResult,
+  isSchedulerStoreFile,
   isSessionManagerAbortParams,
   isSessionManagerArchiveParams,
   isSessionManagerCreateParams,
@@ -1437,18 +1356,18 @@ export {
   isSubagentJournalReport,
   isTerminalBackgroundTaskState,
   mapReasonToStatus,
+  normalizeIdleBackgroundSec,
   onceCronToDate,
+  parseCompactionPersistSignal,
   parsePlanReviewResponse,
   readDetailsSummary,
   readLifecycleState,
   readResumeHint,
-  replayFoldEntries,
   resolveSettlementReason,
   resultContentText,
   scanPendingEntries,
   scanPendingFields,
   setWidgetDual,
-  snapshotToTask,
   toolOfAction,
   transition,
   truncateSelfReview,

package/dist/scheduler-store-entry.d.ts

@@ -0,0 +1,57 @@
+import { c as ScheduledTask, d as SchedulerStoreFile } from './types-DcAmuFZ2.js';
+export { b as SCHEDULER_STORE_SCHEMA_VERSION, i as isSchedulerStoreFile } from './types-DcAmuFZ2.js';
+
+/**
+ * 读结果三分支：
+ * - `ok`：解析成功，tasks 为任务集（可为空数组）
+ * - `missing`：文件不存在 = 空任务集（**正常路径而非异常**——新 session / fork / 从未建任务）
+ * - `corrupt`：文件存在但不可解析 → 已改名 `.corrupt-<ts>` 留证，调用方按空任务集启动
+ */
+type SchedulerStoreRead = {
+    kind: 'ok';
+    tasks: ScheduledTask[];
+} | {
+    kind: 'missing';
+} | {
+    kind: 'corrupt';
+    renamedTo: string;
+};
+/** 读写选项：降级日志 warn 注入点（包内零 logger 依赖；同构先例 = replay 折叠链的
+ *  ReplayFoldOptions.warn——该链已随方案 B 落地整体退役，见 commit 73073b169 删除的 replay.ts）。 */
+type SchedulerStoreOptions = {
+    warn?: (message: string, context?: unknown) => void;
+};
+/**
+ * 任务库分片文件路径：`<agentDir>/scheduler/<root>/<segments>/<sessionId>.json`。
+ *
+ * - `agentDir`：pi 的 getAgentDir() 值（扩展侧 pi 官方导出；taiji 面板侧 = shared
+ *   getPiAgentDir()，同一目录——runtime 注入 pi 进程的 PI_CODING_AGENT_DIR 即它）
+ * - `cwd`：owner session 工作目录（workspace 路径隔离键）
+ * - `sessionId`：pi SessionManager.getSessionId()（--no-session 等空值由调用方归一，
+ *   本函数对空/非法值 fail-fast——静默拼出错误路径会让任务「写到别处」不可见）
+ *
+ * 旧 store 文件（`scheduler.json`，v1）与新分片（`<sessionId>.json`）同目录不同名，
+ * 互不冲突；旧文件按用户裁决不迁移、留盘为孤儿。
+ */
+declare function schedulerStoreFilePath(agentDir: string, cwd: string, sessionId: string): string;
+/**
+ * 读快照：一次 JSON.parse 读整个文件重建任务集（无重放折叠——重放折叠 / fork owner
+ * 过滤 / 活跃路径裁剪三件套已随 event sourcing 退役）。
+ *
+ * 失败语义：
+ * - ENOENT → `missing`（空任务集正常路径）
+ * - 解析/形状失败 → 改名 `.corrupt-<ts>` 留证 + 返回 `corrupt`（调用方按空任务集继续，
+ *   调度不中断——与旧「恢复失败显式降级」语义一致）；改名自身失败（只读卷等）不抛，
+ *   仍返回 `corrupt` + warn——读侧永远不因留证失败而中断启动
+ * - 其他读错误（EACCES 等）→ 上抛，由调用方决定降级（扩展装配点 catch 显式降级）
+ */
+declare function readSchedulerStore(filePath: string, options?: SchedulerStoreOptions): SchedulerStoreRead;
+/**
+ * 写快照：全量序列化 + 原子替换（tmp 文件 → fsync → rename，POSIX rename 原子性）。
+ * 崩溃时要么旧文件完整、要么新文件完整，无半写形态。
+ * 目录不存在则递归创建（首写建目录）。写失败 throw——调用方（扩展 runtime 的
+ * persistTasks catch）负责 warn + 下写点重试，内存态照常推进。
+ */
+declare function writeSchedulerStore(filePath: string, file: Omit<SchedulerStoreFile, 'schemaVersion'>, options?: SchedulerStoreOptions): void;
+
+export { SchedulerStoreFile, type SchedulerStoreOptions, type SchedulerStoreRead, readSchedulerStore, schedulerStoreFilePath, writeSchedulerStore };

package/dist/scheduler-store-entry.js

@@ -0,0 +1,102 @@
+import {
+  SCHEDULER_STORE_SCHEMA_VERSION,
+  isSchedulerStoreFile
+} from "./chunk-TFO4NW5X.js";
+
+// src/extensions/scheduler/store.ts
+import * as fs from "fs";
+import * as path from "path";
+function schedulerStoreFilePath(agentDir, cwd, sessionId) {
+  if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) {
+    throw new Error(`Invalid sessionId for scheduler store path: ${JSON.stringify(sessionId)}`);
+  }
+  const resolved = path.resolve(cwd);
+  const parsed = path.parse(resolved);
+  const segments = resolved.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  const root = parsed.root.replaceAll(/[^a-zA-Z0-9]+/g, "-").replaceAll(/^-+|-+$/g, "").toLowerCase() || "root";
+  return path.join(agentDir, "scheduler", root, ...segments, `${sessionId}.json`);
+}
+function toStoreTask(task) {
+  const { pending: _p, history, ...rest } = task;
+  return { ...rest, history: history.map((h) => ({ ...h })) };
+}
+function readSchedulerStore(filePath, options) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch (err) {
+    if (isEnoent(err)) return { kind: "missing" };
+    throw err;
+  }
+  const corrupted = (renamedTo) => {
+    options?.warn?.("scheduler store corrupted; renamed for inspection, starting with empty task set", {
+      filePath,
+      renamedTo
+    });
+    return { kind: "corrupt", renamedTo };
+  };
+  let data;
+  try {
+    data = JSON.parse(content);
+  } catch {
+    return corrupted(renameCorrupt(filePath));
+  }
+  if (!isSchedulerStoreFile(data)) {
+    return corrupted(renameCorrupt(filePath));
+  }
+  return { kind: "ok", tasks: data.tasks };
+}
+var SNAPSHOT_INDENT = 2;
+function writeSchedulerStore(filePath, file, options) {
+  const payload = {
+    schemaVersion: SCHEDULER_STORE_SCHEMA_VERSION,
+    ...file.sessionFile !== void 0 && { sessionFile: file.sessionFile },
+    tasks: file.tasks.map(toStoreTask)
+  };
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    const fd = fs.openSync(tmp, "w");
+    try {
+      fs.writeFileSync(fd, JSON.stringify(payload, null, SNAPSHOT_INDENT) + "\n", "utf-8");
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (cleanupErr) {
+      if (!isEnoent(cleanupErr)) {
+        options?.warn?.("scheduler store tmp cleanup failed after write error", {
+          tmp,
+          error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)
+        });
+      }
+    }
+    throw err;
+  }
+}
+function renameCorrupt(filePath) {
+  const renamedTo = `${filePath}.corrupt-${Date.now()}`;
+  try {
+    fs.renameSync(filePath, renamedTo);
+    return renamedTo;
+  } catch {
+    return filePath;
+  }
+}
+function isEnoent(err) {
+  const code = err?.code;
+  if (code === "ENOENT") return true;
+  return err instanceof Error && /ENOENT/.test(err.message);
+}
+export {
+  SCHEDULER_STORE_SCHEMA_VERSION,
+  isSchedulerStoreFile,
+  readSchedulerStore,
+  schedulerStoreFilePath,
+  writeSchedulerStore
+};

package/dist/types-DcAmuFZ2.d.ts

@@ -0,0 +1,70 @@
+/** 快照 schema 版本（v2 = 任务库分离形态；v1 是 npm 0.1.1 旧 store，文件名不同不互读）。 */
+declare const SCHEDULER_STORE_SCHEMA_VERSION = 2;
+/**
+ * 快照文件形状（v2 任务库分离 schema；方案 B 设计原文未归档，裁决内容与背景
+ * 以 commit 73073b169 message 为溯源锚——同 store.ts 头注口径）。
+ * tasks 为内存任务集的全量快照：写入口统一剥离运行时标记（pending）并拷贝 history，
+ * 读方拿到的即干净的持久化形态。
+ */
+type SchedulerStoreFile = {
+    schemaVersion: typeof SCHEDULER_STORE_SCHEMA_VERSION;
+    /** owner session 的 JSONL 路径（冗余记录，供排障与对账；--no-session 时可缺省） */
+    sessionFile?: string;
+    tasks: ScheduledTask[];
+};
+/**
+ * 快照文件形状校验（M0 契约期由 @taiji/shared/execution 的 scheduler 小域契约单源
+ * re-export，U6 存量导入消费）：顶层 schemaVersion=2 + tasks 数组且逐项为对象
+ * （字段级信任唯一写者，不逐字段校验）。
+ */
+declare function isSchedulerStoreFile(data: unknown): data is SchedulerStoreFile;
+type ScheduleSpec = {
+    mode: 'cron';
+    cronExpression: string;
+} | {
+    mode: 'interval';
+    intervalMs: number;
+};
+type TaskKind = 'once' | 'recurring';
+type TaskStatus = 'success' | 'failed';
+type ScheduledTask = {
+    id: string;
+    name: string;
+    prompt: string;
+    kind: TaskKind;
+    schedule: ScheduleSpec;
+    model?: string;
+    enabled: boolean;
+    createdAt: number;
+    nextRunAt: number;
+    expiresAt?: number;
+    runCount: number;
+    lastRunAt?: number;
+    lastStatus?: TaskStatus;
+    lastError?: string;
+    history: ExecutionRecord[];
+    pending?: boolean;
+};
+type ExecutionRecord = {
+    at: number;
+    status: TaskStatus;
+};
+/**
+ * history 裁剪上限（单点）：由 `appendExecutionRecord` 在 runtime 记账侧执行裁剪；
+ * 快照写入口不裁剪（只逐项拷贝）——上限字面量只此一处，多处各持会漂移。
+ */
+declare const HISTORY_LIMIT = 20;
+/**
+ * 追加执行记录并按 HISTORY_LIMIT 裁剪（单点）：runtime 侧 dispatch 累积的
+ * push+trim——内联时与上限字面量同源存在「漏改一处」漂移风险，随上限一并收敛。
+ */
+declare function appendExecutionRecord(task: ScheduledTask, at: number, status: TaskStatus): void;
+/**
+ * scheduler-manager 插件推树的 overlay 定时任务 tab ViewHost 分区键（历史命名
+ * modal-<pluginId>-<modalId>，modal 链退役后原值保留）：插件 views.update 推树与
+ * taiji renderer ViewHost 消费跨包共用本单源——双端各持字面量时任一端漂移即
+ * ViewHost per-session 分区静默 miss（tab 空白无报错），收敛到本文件单点导出。
+ */
+declare const SCHEDULER_MODAL_VIEW_ID = "modal-scheduler-manager-scheduler-manager.panel";
+
+export { type ExecutionRecord as E, HISTORY_LIMIT as H, type ScheduleSpec as S, type TaskKind as T, SCHEDULER_MODAL_VIEW_ID as a, SCHEDULER_STORE_SCHEMA_VERSION as b, type ScheduledTask as c, type SchedulerStoreFile as d, type TaskStatus as e, appendExecutionRecord as f, isSchedulerStoreFile as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/extension-protocol",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Cross-layer pi extension contract package: dual-mode (TUI/GUI) rendering helpers, session/background-task/pending-entries protocols, and shared behavior primitives",
   "type": "module",
   "main": "dist/index.js",
@@ -14,6 +14,10 @@
     "./background-task": {
       "types": "./dist/background-task-entry.d.ts",
       "import": "./dist/background-task-entry.js"
+    },
+    "./scheduler-store": {
+      "types": "./dist/scheduler-store-entry.d.ts",
+      "import": "./dist/scheduler-store-entry.js"
     }
   },
   "files": [
@@ -22,7 +26,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@zhushanwen/state-machine": "0.2.0"
+    "@zhushanwen/state-machine": "0.2.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",