@x-otto/schedule 0.0.1-alpha.2 → 0.0.1-alpha.4

package/dist/index.d.ts

@@ -1,6 +1,23 @@
 import { Migration, Persistence } from "@x-otto/persistence";
 import { AgentJobRegistry } from "@x-otto/runtime";
 
+//#region ../interchange/dist/index.d.ts
+//#endregion
+//#region src/model.d.ts
+/**
+ * 推理投入档（reasoning effort）——RFC-235 对齐 Claude Code 词表：`low/medium/high/xhigh/max`。
+ * 去除历史遗留的 `minimal`（无对应厂商语义，存量配置载入时迁移为 `low`），新增 `max`（Claude
+ * Code 最高档 + DeepSeek `reasoning_effort:'max'` 顶档）。各模型真实支持的子集由 manifest 的
+ * `Model.thinkingLevels` 声明，provider 组装请求体时按"≤该档最高支持档"降级（见 RFC-235 §3.3）。
+ */
+type ThinkingLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/**
+ * 模型能力优势标签（供大模型为 subagent 选型）。非 /models API 返回——由
+ * model-capabilities 据「精选家族图 + 启发式」推导。
+ *  planning=方案/架构 · knowledge=知识/通识 · coding=编码 · reasoning=深度推理
+ *  · vision=视觉 · speed=低延迟 · long-context=长上下文
+ */
+//#endregion
 //#region src/types.d.ts
 /** A scheduled task persisted to ${OTTO_HOME}/schedules/<id>.json */
 interface ScheduledTask {
@@ -49,6 +66,37 @@ interface ScheduledTask {
    * 时不使用。
    */
   boundSessionId?: string;
+  /**
+   * RFC-423 D2：事件触发描述。存在时任务由进程内事件驱动而非 cron 驱动
+   * （cronExpression 被忽略，任务不进 tick 的 findDue）。缺省 = cron 驱动（既有语义，零变化）。
+   */
+  eventTrigger?: EventTriggerSpec;
+  /**
+   * RFC-438：到点执行时使用的模型 id（缺省 = 当前会话模型/默认）。
+   * 只存 id 字符串——modelRegistry 是唯一真源，schedule 不持有 Model 对象。
+   */
+  modelId?: string;
+  /** RFC-438：思考档位（配 modelId 使用）。缺省 = provider 默认（detached-run 实际 ?? 'medium'）。 */
+  thinkingLevel?: ThinkingLevel;
+}
+/**
+ * RFC-423 D2：事件触发描述。
+ *
+ * MVP 只支持进程内事件源（source: 'job'，监听 AgentJobRegistry 终态）。
+ * git commit / file watch 等进程外源列为后续 RFC，架构预留 source 开放为 string。
+ */
+interface EventTriggerSpec {
+  /** 事件源类型（MVP：'job'——AgentJobRegistry 终态事件） */
+  source: string;
+  /** 事件名（source='job' 时为 AgentJobStatus：'applied' | 'failed' | 'canceled'） */
+  event: string;
+  /**
+   * 可选过滤器（如只对特定 sessionId 的 job 触发）。死循环闸门之一（D4）：
+   * 缺省不过滤 sessionId 时，闸门2（默认拒绝 job 投递）+ debounce（闸门3）承担防护。
+   */
+  filter?: {
+    sessionId?: string;
+  };
 }
 /** RFC-229 M1: structured result from SchedulerService.cancel() */
 interface CancelResult {
@@ -67,7 +115,7 @@ interface CancelResult {
  * 整套调度设施，正是 RFC 列为"放弃方案"的路径。
  */
 interface ScheduleSubscriber {
-  kind: 'plugin-service';
+  kind: string;
   pluginId: string;
   serviceId: string;
 }
@@ -86,6 +134,12 @@ interface ScheduledTaskInput {
   target?: 'job' | 'session';
   /** RFC-357 D2：`target==='session'` 时必填，调用方（scheduler.add()）从当前 sessionRef 取值填充。 */
   boundSessionId?: string;
+  /** RFC-423 D2：事件触发描述。存在时任务由进程内事件驱动，cronExpression 仅作占位。 */
+  eventTrigger?: EventTriggerSpec;
+  /** RFC-438：到点执行时使用的模型 id（缺省 = 当前会话模型/默认）。 */
+  modelId?: string;
+  /** RFC-438：思考档位（配 modelId 使用）。 */
+  thinkingLevel?: ThinkingLevel;
 }
 //#endregion
 //#region src/registry.d.ts
@@ -101,35 +155,16 @@ declare class ScheduleRegistry {
    * Find tasks that are due for execution.
    * Returns all enabled tasks (recurring or one-shot) whose nextFireAt <= now.
    * The 'firing' guard is a scheduler concern (managed via a separate Set).
+   *
+   * RFC-423：eventTrigger 任务永不由时间"到点"——它们由进程内事件驱动（InProcessEventTrigger
+   * arm 监听），不进 cron 轮询。此处排除，使 cron 轮询（tick）与事件监听（arm）
+   * 两条路径互斥（D5）。
    */
   findDue(now: number): ScheduledTask[];
   count(): number;
   has(id: string): boolean;
 }
 //#endregion
-//#region src/cron-parser.d.ts
-/**
- * Parse a 5-field cron expression (minute hour dom month dow) and return the next
- * fire time >= from (inclusive). All times in local timezone.
- *
- * Throws on invalid expressions.
- *
- * Field syntax: wildcard (*), single value (5), step (e.g. \*\/15 or 5\/15),
- * range (1-5), list (1,15,30), range with step (1-10\/2).
- *
- * Unsupported: L, W, ?, #, name aliases (MON, JAN).
- *
- * ## DoM∧DoW semantics
- *
- * If both day-of-month and day-of-week are constrained (not a bare *),
- * a date matches if **EITHER** field matches (standard vixie-cron OR behaviour).
- *
- * ## Day-of-week mapping
- *
- * 0 = Sunday, 1–6 = Monday–Saturday, 7 = also Sunday.
- */
-declare function parseCron(expr: string, from?: Date): Date;
-//#endregion
 //#region src/schedule-store.d.ts
 interface ScheduleStore {
   saveTask(task: ScheduledTask): Promise<void>;
@@ -159,6 +194,18 @@ interface FireOwnership {
   renew(): Promise<void>;
   release(): Promise<void>;
   lastFailureReason?(): 'occupied' | 'network-error' | undefined;
+  /**
+   * 当前锁持有者的可读描述（诊断用，非语义判定）。返回 `undefined` 表示无法确定
+   * （旧格式锁文件、锁已消失、或远程实现——服务端仲裁没有本地 pid 概念）。
+   *
+   * 为什么是可选端口：`FireOwnership` 是本地 O_EXCL 与远程 HTTP 双实现的公共接口
+   * （RFC-169 D3/D3b），"谁持有"只在本地实现里有确切答案。消费方必须按可选处理，
+   * 拿不到就退回不带主体的提示文案，不得据此做任何准入判定。
+   */
+  describeOwner?(): {
+    pid?: number;
+    host?: string;
+  } | undefined;
   /** Whether this process currently holds the lock (verified against the token). */
   isOwner(): boolean;
 }
@@ -168,327 +215,474 @@ interface FireOwnership {
  */
 declare function createLocalFireOwnership(workspaceKey: string): FireOwnership;
 //#endregion
-//#region src/schedule-lease-migrations.d.ts
-declare const SCHEDULE_LEASE_MIGRATIONS: Migration[];
+//#region src/schedule-config.d.ts
+/**
+ * schedule-config.ts —— RFC-406 D4：常量配置化。
+ *
+ * 之前散落在 scheduler.ts 顶部的硬编码常量，提取为可注入的配置接口。
+ * 不同部署场景（单用户 vs 团队共享、高频 vs 低频）可调整参数，不需改源码。
+ *
+ * **不纳入本接口的常量**（刻意游离，非遗漏）：
+ * - `fire-ownership.ts` 的 `STALE_MS`（5 分钟）——本地锁过期阈值，有不变量约束
+ *   （必须超过 tick renew 间隔，否则锁在 renew 周期间被误判过期），调错会致
+ *   多进程重复 fire。它是 fire-ownership 的领域常量，不是可调运维参数。
+ * - `remote-fire-ownership.ts` 的 `HEARTBEAT_MS`（30s）/ `STALE_MS`（180s）——
+ *   远程租约心跳与过期，有 1:6 比例约束（过期 > 6 倍心跳，防网络抖动误夺锁）。
+ *   调错同样致多终端重复 fire 或锁饥饿。两者已通过模块 export 暴露
+ *   （`REMOTE_FIRE_OWNERSHIP_HEARTBEAT_MS` / `REMOTE_FIRE_OWNERSHIP_STALE_MS`），
+ *   不进 ScheduleConfig 以免暗示可随意调。
+ */
+interface ScheduleConfig {
+  /** 最大任务数 */
+  maxTasks: number;
+  /** recurring 任务过期阈值（超过此时间未触发则清除） */
+  recurringEvictionMs: number;
+  /** recurring 任务 jitter 窗口 */
+  recurringJitterWindowMs: number;
+  /** one-shot 任务 jitter 窗口 */
+  oneShotJitterWindowMs: number;
+  /** 默认单次执行超时 */
+  defaultMaxDurationMs: number;
+  /** 默认重试次数 */
+  defaultMaxRetries: number;
+  /** ticker 间隔 */
+  tickIntervalMs: number;
+  /** needs_input 硬上限倍数 */
+  needsInputMaxExtensionFactor: number;
+  /** 每任务最大 fire log 条数 */
+  maxFireLogsPerTask: number;
+  /** owner 从 store 重新同步的间隔（tick 数） */
+  reloadIntervalTicks: number;
+  /** recovery 模式重试间隔 */
+  recoveryRetryIntervalMs: number;
+}
+declare const DEFAULT_SCHEDULE_CONFIG: ScheduleConfig;
 //#endregion
-//#region src/remote-schedule-store.d.ts
-interface RemoteScheduleStoreOptions {
+//#region src/fire-target.d.ts
+interface FireTarget {
+  /** 唯一标识（'job' | 'session' | 'plugin-service'） */
+  readonly type: string;
+  /** 判断此 handler 是否能处理该 task。注册顺序决定优先级——先注册的先匹配。 */
+  canHandle(task: ScheduledTask): boolean;
   /**
-   * `--session-url` 的原始值（如 `http://host:3001/api/storage/sessions`）——**不是**裸
-   * origin，该值本身是完整资源路径（对齐 `otto serve` 后端约定）。内部用
-   * `new URL(sessionUrl).origin` 提取协议+主机+端口，再拼接 `/api/storage/schedules`——
-   * 与 `remote-fire-ownership.ts` 的同一提取逻辑保持一致，不能直接拿 sessionUrl 当前缀用。
+   * 执行投递。返回 FireResult——scheduler 不关心 handler 内部如何实现，
+   * 只根据 outcome 决定后续行为（one-shot 清理 / recurring 记账）。
    */
-  sessionUrl: string;
-  getAuth: () => Promise<{
-    token: string;
-  }>;
-  fetch?: typeof globalThis.fetch;
-  timeoutMs?: number;
-  wsKey?: string | (() => string | undefined);
+  fire(task: ScheduledTask, ctx: FireContext): Promise<FireResult>;
+  /**
+   * fire() 退出保障钩子（M1 修复①）：无论 fire 正常返回、抛错还是早退，executor 的
+   * finally 块都会调用。handler 必须在此清理本次 fire 的运行态记账
+   * （runningJobs / cancelRequested 等）——漏清会导致 cancel 意图残留、
+   * recurring 任务被永久跳过、运行态 Map 无界泄漏。
+   */
+  cleanup?(taskId: string): void;
+  /**
+   * 可选能力：支持取消正在运行的投递（job 路径实现）。
+   * SchedulerService.cancel() 路由到当前 fire 该任务的 handler。
+   */
+  requestCancel?(taskId: string): CancelResult;
+  /** 可选能力：当前有并发运行态的 handler（job 路径）暴露运行中的 task id 集合。 */
+  getRunningTaskIds?(): Set<string>;
+  /**
+   * 可选能力：session 投递 handler 暴露"创建任务时绑定的当前 sessionId"端口，
+   * scheduler.add() 经此填充 boundSessionId（RFC-406 D6）。
+   */
+  getSessionId?(): string;
+}
+interface FireContext {
+  /** 本次计划触发时刻（ticker 路径传入，runNow 用实际时刻）。用于 occurrenceId 派生。 */
+  scheduledFor?: number;
+  now: () => number;
+  logger?: {
+    error: (msg: string | Error, ...args: unknown[]) => void;
+  };
+}
+interface FireResult {
+  outcome: 'success' | 'failed';
+  /** cancel 信号——JobFireTarget 在 cancel() 路径设置 */
+  cancelled?: boolean;
+  error?: string;
+  /** job-specific 信号（JobFireTarget 附加，用于 runningJobsByTaskId 记账） */
+  jobId?: string;
 }
+//#endregion
+//#region src/trigger.d.ts
 /**
- * Create a ScheduleStore backed by the persistenced `/api/storage/schedules` namespace's
- * generic storage route (`storage.ts`, `namespace='schedules'`) — distinct from the
- * lease sub-route (`schedule-lease.ts`, `/api/schedules/...`) which handles fire-ownership
- * arbitration only.
+ * 事件监听型触发器。`arm()` 建立订阅、返回退订函数——退订由
+ * `SchedulerService.terminate()` 咽喉点统一调用（→ RFC-433 §4 R2），
+ * 实现方不必自行管理生命周期。
  */
-declare function createRemoteScheduleStore(options: RemoteScheduleStoreOptions): ScheduleStore;
-//#endregion
-//#region src/remote-fire-ownership.d.ts
-interface RemoteFireOwnershipOptions {
+interface EventDrivenTrigger {
+  /** 唯一标识（当前仅 `'in-process-event'`）。 */
+  readonly type: string;
+  /** 判断此 Trigger 是否负责该任务的触发。 */
+  canHandle(task: ScheduledTask): boolean;
   /**
-   * `--session-url` 的原始值（如 `http://host:3001/api/storage/sessions`）——**不是**裸
-   * origin。该值本身是完整资源路径（对齐 `otto serve` 后端约定，见 RFC-146 §1.3 两条远程
-   * 产品线对照表），本构造函数内部用 `new URL(sessionUrl).origin` 提取协议+主机+端口，
-   * 再拼接 `/api/schedules/...` lease 路径——不能直接拿 `sessionUrl` 当 baseUrl 使用。
+   * 为一个任务建立事件订阅。触发条件满足时调用 `fire(task)`。
+   * 返回退订函数——`SchedulerService` 在任务终结、stop、重新 arm 时调用，防监听泄漏。
    */
-  sessionUrl: string;
-  wsKey: string;
-  getAuth: () => Promise<{
-    token: string;
-  }>;
-  fetch?: typeof globalThis.fetch;
-  timeoutMs?: number;
-  now?: () => number;
+  arm(task: ScheduledTask, fire: (task: ScheduledTask) => void): () => void;
 }
-/** Create a server-arbitrated FireOwnership backed by persistenced's lease endpoints. */
-declare function createRemoteFireOwnership(options: RemoteFireOwnershipOptions): FireOwnership;
 //#endregion
 //#region src/scheduler.d.ts
+/**
+ * RFC-433 D1：任务终结的来源。仅用于诊断/日志语义——终结动作本身对三者一致
+ * （退订 → 删快照 → 删 registry），区分来源是为了让调用点自我说明。
+ */
+type TerminationReason = /** 用户经 `/schedule remove`、面板或 `schedule_delete` 工具删除。 */'user-removed' /** one-shot 任务成功执行完毕（FireExecutor 终态处理）。 */ | 'one-shot-complete' /** recurring cron 任务 7 天未触发，被 TickLoop 判为滞留清除。 */ | 'stale-evicted';
 interface SchedulerDeps {
   registry: ScheduleRegistry;
   store: ScheduleStore;
   ownership: FireOwnership;
-  jobRegistry: AgentJobRegistry;
   /**
-   * Dispatch an agent job. Mirrors AgentJobService.start() shape:
-   * synchronously returns a record with at least { id }.
-   */
-  startJob: (input: {
-    title: string;
-    prompt: string;
-    sessionId: string;
-    origin: 'user' | 'main';
-  }) => {
-    id: string;
-  };
-  getSessionId: () => string;
-  /**
-   * RFC-327 D2：向订阅者投递到点通知的窄端口（缺省 = 不支持订阅者，此类任务 fire 时
-   * 记日志跳过而非崩溃）。
+   * FireTarget handler 列表。内置 handler（job/session/subscriber）由消费方构造并传入，
+   * SchedulerService 不自动注册——消费方完全控制 handler 集合和优先级。
    *
-   * 返回是否真的送达——`false` 表示服务未运行/已停机。scheduler 据此写 fire 日志，
-   * 但**不重试、不报错**：定时通知是尽力而为的旁路信号（at-least-once 的"至少"由
-   * 下一次 cron 周期保证，不是靠即时重试）。
-   *
-   * 端口刻意只接受纯数据标识：scheduler 不知道插件服务的存在形式，也不持有其句柄。
+   * 如果传入空数组，fire() 会找不到 handler 并记日志跳过——不会崩溃。
    */
-  notifySubscriber?: (subscriber: ScheduleSubscriber, tick: {
-    scheduleId: string;
-    occurrenceId: string;
-    occurredAt: number;
-  }) => boolean;
+  fireTargets: FireTarget[];
   /**
-   * RFC-357 D1/D2：`target==='session'` 任务到点后的投递端口——把 `prompt` 注入
-   * `boundSessionId` 对应的当前会话（经 `AgentSession.prompt(text,{streamingBehavior:'followUp'})`，
-   * busy 时排队、idle 时直接起新回合）。缺省 = 不支持 session 投递（此类任务 fire 时记日志
-   * 跳过而非崩溃，同 `notifySubscriber` 缺省行为的纹理）。
-   *
-   * 返回值语义（调用方——CLI wiring——必须自行捕获全部失效原因，统一收敛为 boolean）：
-   * `true` = 已成功注入；`false` = 失效（会话身份不匹配/已销毁/archived/paused 等），
-   * scheduler 不重试、不报错——同 notifySubscriber 一样是尽力而为的旁路信号。
+   * RFC-423：事件驱动 Trigger 列表（如 InProcessEventTrigger）。缺省空数组——只有 cron
+   * 触发（cron 任务由 TickLoop 轮询驱动，无需消费方传入）。消费方传入事件 trigger
+   * 即启用事件触发能力。
    */
-  followUpCurrentSession?: (task: {
-    prompt: string;
-    boundSessionId: string;
-    name: string;
-    origin: 'user' | 'model';
-  }) => boolean;
+  triggers?: EventDrivenTrigger[];
+  /** 可选配置覆盖（常量配置化，RFC-406 D4） */
+  config?: Partial<ScheduleConfig>;
   now?: () => number;
+  /**
+   * `debug` 可选——生产装配（`interactive-schedule.ts`）注入的 logger 只有 `error`；
+   * 有 `debug` 的实现能拿到任务终结的来源（user-removed / one-shot-complete /
+   * stale-evicted），排查"任务怎么没了"时不必猜。
+   */
   logger?: {
     error: (msg: string | Error, ...args: unknown[]) => void;
+    debug?: (msg: string, ...args: unknown[]) => void;
   };
-  /**
-   * RFC-230：任务失败重试之间的固定延迟（ms）注入端口。缺省真实 `setTimeout`，测试可注入假
-   * 实现避免真实等待。`retryBackoffMs`（见下）为 0 时仍会调用（`sleep(0)`，一次微任务调度
-   * 点而非跳过——与当前"循环内无 await 直接进下一轮"存在细微时序差异，但不影响任何可观察
-   * 行为，见 RFC-230 §3 D6 Scheduler 小节）。
-   */
-  sleep?: (ms: number) => Promise<void>;
-  /**
-   * RFC-230：每次重试之间的固定延迟（ms）。默认 0（保持现状：不改变既有 per-task 重试
-   * 节奏，除非显式配置非零值）。真实值来自 `app.getResilienceConfig().schedule.retryBackoffMs`，
-   * 由真实构造点（`packages/cli/src/commands/interactive-schedule.ts`）注入——不是
-   * `packages/coding` App 内部构造 `SchedulerService`（二轮评审 P2 修正的装配点误解）。
-   */
-  retryBackoffMs?: number;
 }
 declare class SchedulerService {
   private readonly deps;
   private readonly registry;
-  private ticker;
+  private readonly persistence;
+  private readonly fireExecutor;
+  private readonly fireLogger;
+  private readonly tickLoop;
+  private readonly config;
   private recoveryTimer;
-  private readonly firing;
-  private tickInProgress;
+  /** RFC-435 D4：从未当过 owner 的非 owner 进程的 acquire 重试循环（TUI 释放锁后本进程可接管）。 */
+  private ensureOwnershipTimer;
   private running;
-  private tickCount;
-  private readonly runningJobsByTaskId;
-  private readonly cancelRequested;
-  private _nextFireToken;
+  /** RFC-423：事件驱动 trigger 列表（消费方传入）。 */
+  private readonly triggers;
+  /** RFC-423：已 arm 的事件任务 → 退订函数（remove/stop 时调用，防监听泄漏）。 */
+  private readonly armedTriggers;
   constructor(deps: SchedulerDeps);
-  /**
-   * RFC-169 D3d: whether this process currently holds fire ownership (ticker actively
-   * fires due tasks) vs read-only (loaded the task list but a different live process —
-   * local: another workspace-scoped otto instance; remote: another terminal sharing the
-   * same wsKey — is the one that will actually fire). Consumed by `/schedule list` to show
-   * a "read-only, another terminal holds fire ownership" hint (RFC-169 D3d TUI indicator).
-   */
   isFireOwner(): boolean;
-  /**
-   * F2 (RFC-169 终局 review 2026-07-15): when `isFireOwner()` is false, why. `undefined`
-   * from the underlying `FireOwnership` (e.g. the local O_EXCL implementation, which never
-   * has a "can't reach the lock" failure mode — fs ops either succeed or throw) means the
-   * distinction genuinely doesn't apply; callers should fall back to the generic
-   * "another terminal holds it" wording. Only the remote implementation can return
-   * `'network-error'`.
-   */
   fireOwnerFailureReason(): 'occupied' | 'network-error' | undefined;
   /** Load persisted tasks and start the ticker (if fire owner). */
   start(): Promise<void>;
   /**
-   * review S5: incremental re-sync from the store — add tasks the owner doesn't know about
-   * yet (created by a non-owner process), remove tasks that vanished from the store
-   * (deleted by a non-owner process), and pick up field edits (enable/disable, cron, prompt)
-   * made elsewhere. Never touches a task currently `firing` (avoid clobbering in-flight
-   * dispatch state) and never re-applies jitter to tasks the owner already knows about
-   * (their nextFireAt is the owner's own scheduling decision, not the store's).
+   * 任务终结的**唯一入口**（RFC-433 D1 / R2）。三条删除路径——用户 `remove()`、
+   * one-shot 完成、7 天滞留驱逐——全部经此，否则事件监听会泄漏：任务从 registry
+   * 消失后，`armedTriggers` 里的退订函数仍在，而 arm 回调闭包捕获的是 **task 对象
+   * 引用本身**（见 `armIfEventDriven`），registry 里有没有它根本不影响 fire。
+   *
+   * **三步顺序不可调换（R2b 不变量）**：`persistence.deleteOne()` 内部要
+   * `registry.get(id)` 判 session-local（`schedule-persistence.ts:37`）——registry
+   * 先删会让它读不到 task、判不出 session-local，对本就不落盘的任务白发一次 store IO。
    */
-  private reloadFromStore;
-  /** Clear ticker, release ownership, and persist current state. */
-  stop(): Promise<void>;
+  private terminate;
   /**
-   * N1 (RFC-169 终局复审 2026-07-23): when S4 detects ownership loss mid-session, stop
-   * the ticker (prevents double-fire) but enter recovery mode — a low-frequency
-   * re-acquire loop that can reclaim ownership when a network partition heals or the
-   * competing process exits. Without this, a single transient heartbeat failure in
-   * remote mode permanently degrades the process to read-only (contradicting D3d's
-   * auto-recovery promise) and local suspend-then-resume recovery requires a full
-   * process restart.
+   * 只从内存移除、**保留** store 快照——`reloadFromStore` 的差量同步用（store 里
+   * 本来就已经没有它了，是别的进程删的；再发一次 delete 是多余 IO）。
+   * 同样必须退订，理由同 `terminate()`。
    */
+  private evictFromMemory;
+  /** Clear ticker, release ownership, and persist current state. */
+  stop(): Promise<void>;
   private startRecovery;
   private recoveryAttempt;
   private stopRecovery;
   /**
-   * Create a scheduled task.
-   *
-   * - Generates an 8-char id via crypto.randomUUID()
-   * - Parses the cron expression to compute nextFireAt + jitter
-   * - Enforces a max of 50 tasks (throws if exceeded)
+   * 非 owner 进程的低频 acquire 重试。TUI 先开持锁 → daemon 后起（acquire 失败，
+   * 本循环待机）→ TUI 关闭释放锁 → 本循环在下一次 tick 接管。锁的原子性
+   * （O_EXCL / 服务端 CAS）保证任一时刻只有一个 owner——重试不会造成双主。
    */
+  private startEnsureOwnership;
+  private ensureOwnershipAttempt;
+  private stopEnsureOwnership;
   add(input: ScheduledTaskInput): ScheduledTask;
-  /** Remove a task by id. Returns true if the task existed and was removed. */
   remove(id: string): boolean;
-  /**
-   * Update mutable fields of a task.
-   *
-   * If cronExpression changes, nextFireAt is recalculated with jitter.
-   * Fields not in the patch are left unchanged.
-   */
   update(id: string, patch: Partial<Pick<ScheduledTask, 'name' | 'prompt' | 'cronExpression' | 'enabled'>>): boolean;
-  /** Return all tasks, ordered by nextFireAt ascending. */
   list(): ScheduledTask[];
-  /**
-   * RFC-229 M2: return the set of task IDs that currently have a running job.
-   * Used by the plugin panel to show [R] status indicators.
-   */
   getRunningTaskIds(): Set<string>;
-  /**
-   * RFC-229 M3: read the most recent fire log entries for a task.
-   * Returns up to `maxEntries` lines, newest first. Each entry is { timestamp, status }.
-   */
   readFireLogs(taskId: string, maxEntries?: number): Array<{
     timestamp: string;
     status: string;
   }>;
+  runNow(id: string): void;
+  cancel(taskId: string): CancelResult;
   /**
-   * Force-execute a task immediately, regardless of its nextFireAt.
-   * Does NOT advance nextFireAt — this is an extra execution.
+   * 若任务是事件驱动（eventTrigger 存在），用匹配的 EventDrivenTrigger arm 监听。
+   * fire 回调复用既有 fireExecutor 路径——Trigger 只决定"何时"，FireTarget 决定"投哪"。
    *
-   * review S3: guarded against a concurrent tick-driven fire() for the same task — without
-   * this, a manual runNow() while tick's fire() await is in flight (fire() only adds to
-   * `firing` synchronously before awaiting startJob) could dispatch two jobs for one task.
+   * 死循环闸门2（D4）：事件驱动任务默认拒绝 JobFireTarget 投递——只有 subscriber/session
+   * 目标（不产生新 job）才放行。配 job 会产生新 job → 高死循环风险，在此拒绝而非静默。
    */
-  runNow(id: string): void;
+  private armIfEventDriven;
+  private disarmIfArmed;
+  private disarmAll;
   /**
-   * RFC-229 M1: cancel the currently running job for a schedule task.
+   * 非 owner 进程拒绝创建 session-local 任务时的诊断文案（RFC-357 D2 R3 的执行面）。
    *
-   * Only cancels jobs in `running` or `needs_input` status — a job that has already
-   * produced a diff (`ready`) is deliberately left untouched so the user can `/job apply`.
+   * **拒绝本身不放宽**——它防的是"任务出现在列表里却永远不触发"的静默失效：非 owner
+   * 进程不跑 ticker，任务又 durable:false 不落盘，owner 进程 loadAllTasks 也看不见它。
+   * 本方法只解决"用户知道被拒了，但不知道该怎么办"：补上**谁持有**（本地实现可从锁
+   * 文件解出 pid/host）与**多久能好**（RFC-435 D4 的非 owner acquire 重试会在锁释放后
+   * 自动接管，无需重启进程）。
    *
-   * Does NOT delete the task definition or alter the cron schedule. The task will fire
-   * again at its next cron-triggered time.
-   *
-   * Sets a cancel intent in `cancelRequested` so the in-flight `fire()` loop stops
-   * retrying — it does NOT prematurely remove the task from `firing` (that belongs to
-   * `fire().finally`), avoiding a race window where the task appears idle but `fire()` is
-   * still running (RFC-229 R10).
+   * 三态退化：远程实现无本地 pid 概念 → 无主体文案；`network-error` 时不能说"另一终端
+   * 持有"（可能压根没连上服务端，让用户去找一个不存在的第二终端是更糟的误导）——这条
+   * 三态区分沿用 `handlers/schedule.ts:105-109` 既有 readOnlyHint 范式，不另造一套判据。
    */
-  cancel(taskId: string): CancelResult;
+  private describeSessionOwnershipRefusal;
   /**
-   * Heartbeat: evict expired recurring tasks, find & fire due tasks.
-   * Reentry guard (MF-1) prevents overlapping ticks.
-   */
-  private tick;
-  /**
-   * Execute a task: start a job, monitor completion via registry events,
-   * retry on failure up to maxRetries. Handles one-shot cleanup.
+   * session-local 任务创建时绑定的 sessionId。
+   * RFC-406 D6：从 SessionFireTarget handler 的 getSessionId() 端口读取（旧 SchedulerDeps.getSessionId
+   * 语义迁入此 handler）。add() 用它来设置 boundSessionId。
    *
-   * review S4 residual risk (accepted): fire() runs independent of the ticker — if this
-   * process is suspended mid-fire and loses ownership (S4 stops the ticker on the next
-   * tick, but does not abort in-flight fire() calls), this in-flight call can still resolve
-   * and write a stale lastFiredAt/nextFireAt back to the store after a successor process
-   * has taken over. Harmless one-time overwrite (this process's ticker is already stopped,
-   * so no repeated corruption) — needs 5-min suspend + in-flight fire + a same-window write
-   * race with the new owner to manifest. Revisit if it proves to matter in practice.
+   * 找不到 SessionFireTarget（消费方未装配 session 投递）时回退空字符串——此时 add() 的
+   * wantsSession 分支不会命中（session 任务无 handler 可 fire），boundSessionId 也无意义。
    */
+  private getSessionIdForTask;
+}
+//#endregion
+//#region src/cron-parser.d.ts
+/**
+ * Parse a 5-field cron expression (minute hour dom month dow) and return the next
+ * fire time >= from (inclusive). All times in local timezone.
+ *
+ * Throws on invalid expressions.
+ *
+ * Field syntax: wildcard (*), single value (5), step (e.g. \*\/15 or 5\/15),
+ * range (1-5), list (1,15,30), range with step (1-10\/2).
+ *
+ * Unsupported: L, W, ?, #, name aliases (MON, JAN).
+ *
+ * ## DoM∧DoW semantics
+ *
+ * If both day-of-month and day-of-week are constrained (not a bare *),
+ * a date matches if **EITHER** field matches (standard vixie-cron OR behaviour).
+ *
+ * ## Day-of-week mapping
+ *
+ * 0 = Sunday, 1–6 = Monday–Saturday, 7 = also Sunday.
+ */
+declare function parseCron(expr: string, from?: Date): Date;
+//#endregion
+//#region src/remote-schedule-store.d.ts
+interface RemoteScheduleStoreOptions {
   /**
-   * RFC-327 D2：向订阅者投递一次到点通知。
-   *
-   * `occurrenceId` 由 `{taskId, 本次计划触发时刻}` 派生——**同一次计划触发的重复投递
-   * 得到同一个 id**，这正是幂等键的意义：service 重启后收到重投也能识别"这次我处理过"。
-   * 若用随机 id，重复投递会被当成两次不同触发，幂等失效。
-   *
-   * 返回是否送达；未送达（服务未运行/宿主未接线）只记日志，不抛错、不重试。
+   * `--session-url` 的原始值（如 `http://host:3001/api/storage/sessions`）——**不是**裸
+   * origin，该值本身是完整资源路径（对齐 `otto serve` 后端约定）。内部用
+   * `new URL(sessionUrl).origin` 提取协议+主机+端口，再拼接 `/api/storage/schedules`——
+   * 与 `remote-fire-ownership.ts` 的同一提取逻辑保持一致，不能直接拿 sessionUrl 当前缀用。
    */
-  private fireSubscriber;
+  sessionUrl: string;
+  getAuth: () => Promise<{
+    token: string;
+  }>;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+  wsKey?: string | (() => string | undefined);
+}
+/**
+ * Create a ScheduleStore backed by the persistenced `/api/storage/schedules` namespace's
+ * generic storage route (`storage.ts`, `namespace='schedules'`) — distinct from the
+ * lease sub-route (`schedule-lease.ts`, `/api/schedules/...`) which handles fire-ownership
+ * arbitration only.
+ */
+declare function createRemoteScheduleStore(options: RemoteScheduleStoreOptions): ScheduleStore;
+//#endregion
+//#region src/schedule-lease-migrations.d.ts
+declare const SCHEDULE_LEASE_MIGRATIONS: Migration[];
+//#endregion
+//#region src/remote-fire-ownership.d.ts
+interface RemoteFireOwnershipOptions {
   /**
-   * RFC-357 D1/D2：把一个 `target==='session'` 任务的 `prompt` 注入其 `boundSessionId`
-   * 对应的当前会话。不建 worktree、不派 AgentJob、不进 `runningJobsByTaskId`/重试循环
-   * （`cancel()` 对 session-local 任务的行为见 `cancel()` 自身的 not_running 分支）。
-   *
-   * 返回是否注入成功；失败（无注入端口/会话身份不匹配/会话已销毁等——由端口内部判断并
-   * 折叠为 boolean）只记日志，不抛错、不重试——同 `fireSubscriber` 的旁路信号纪律。
+   * `--session-url` 的原始值（如 `http://host:3001/api/storage/sessions`）——**不是**裸
+   * origin。该值本身是完整资源路径（对齐 `otto serve` 后端约定，见 RFC-146 §1.3 两条远程
+   * 产品线对照表），本构造函数内部用 `new URL(sessionUrl).origin` 提取协议+主机+端口，
+   * 再拼接 `/api/schedules/...` lease 路径——不能直接拿 `sessionUrl` 当 baseUrl 使用。
    */
-  private fireSession;
-  private fire;
+  sessionUrl: string;
+  wsKey: string;
+  getAuth: () => Promise<{
+    token: string;
+  }>;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+  now?: () => number;
+}
+/** Create a server-arbitrated FireOwnership backed by persistenced's lease endpoints. */
+declare function createRemoteFireOwnership(options: RemoteFireOwnershipOptions): FireOwnership;
+//#endregion
+//#region src/fire-logger.d.ts
+declare class FireLogger {
+  private config;
+  constructor(config: ScheduleConfig);
   /**
-   * Subscribe to AgentJobRegistry onUpdate / onExit and resolve when the
-   * job reaches a conclusion:
-   *
-   *   'success':  ready (diff produced) or applied
-   *   'failed':   failed
-   *   'timeout':  maxDurationMs elapsed while still running (triggers cancel)
-   *   'canceled': the job was canceled (deliberately, by user via cancel(), not a failure)
-   *
-   * ready is NOT terminal in the engine, but for the schedule it's a success
-   * (the diff exists, the user can /job apply later).
+   * 写一行 fire log 到 ${OTTO_HOME}/schedule-logs/<taskId>-<epoch>.log，然后清理超出
+   * maxFireLogsPerTask 的旧日志。best-effort——错误静默吞。
    *
-   * needs_input extends the timeout — the agent is blocked on user input
-   * and should not be killed while waiting.
+   * RFC-345：影子态零磁盘写入——fire log 是纯本机持久化产物，影子进程跳过。
    */
-  private waitForCompletion;
+  write(taskId: string, status: string): void;
+  /** 保留最新 maxFireLogsPerTask 条日志文件。 */
+  private prune;
   /**
-   * Apply a deterministic per-task jitter to spread cron fires. Recurring tasks use a
-   * 30-min window (spreads periodic load); one-shot tasks use a 90s window (review S2 —
-   * RFC-087 §D3 intends one-shot "in ~30s/~90s", not "delayed by up to 30 min"; a 30-min
-   * window made "remind me in 30 minutes" arrive up to ~61 minutes later).
-   * Uses djb2 hash of the task id for reproducibility across restarts.
+   * 读取最近的 fire log 条目。返回最新 maxEntries 条，每条 { timestamp, status }。
    */
-  private applyJitter;
+  read(taskId: string, maxEntries?: number): Array<{
+    timestamp: string;
+    status: string;
+  }>;
+}
+//#endregion
+//#region src/fire-targets/job-fire-target.d.ts
+interface JobFireTargetDeps {
+  jobRegistry: AgentJobRegistry;
   /**
-   * Persist a single task (fire-and-forget). Snapshot-per-id means we never
-   * rewrite the whole collection and never delete-by-diff — that would let one
-   * process delete another process's schedules (A2).
+   * Dispatch an agent job. Mirrors AgentJobService.start() shape:
+   * synchronously returns a record with at least { id }.
    */
+  startJob: (input: {
+    title: string;
+    prompt: string;
+    sessionId: string;
+    origin: 'user' | 'main'; /** RFC-438：per-job 指定模型与思考档位（task.modelId/thinkingLevel 透传）。 */
+    model?: {
+      id: string;
+      thinkingLevel?: ThinkingLevel;
+    };
+  }) => {
+    id: string;
+  };
   /**
-   * RFC-357 D2（独立评审 R2 命中的咽喉点方案）：`target==='session'` 任务永不落盘——
-   * 这是唯一的判断点，`add()`/`update()`/tick 推进/fire 成功/fire 失败-取消/`flushAll()`
-   * 全部调用点共享此拦截，不逐点打补丁（否则新增调用点时会漏防，正是原设计的漏洞）。
+   * RFC-435 D1：绑定会话 id 端口。serve/daemon 无人值守装配可缺省——
+   * job-only 模式无会话，fire 时 sessionId 用空串（无会话绑定，notify 不投递）。
    */
-  private saveOne;
+  getSessionId?: () => string;
+  /** RFC-230：重试之间的固定延迟（ms）。默认 0。 */
+  retryBackoffMs?: number;
+  /** 测试可注入假 sleep 避免真实等待。 */
+  sleep?: (ms: number) => Promise<void>;
+  /** FireLogger 实例（写 fire 日志） */
+  fireLogger: FireLogger;
+  /** needs_input 硬上限倍数（对齐 ScheduleConfig.needsInputMaxExtensionFactor，默认 3）。 */
+  needsInputMaxExtensionFactor?: number;
+}
+declare class JobFireTarget implements FireTarget {
+  private deps;
+  readonly type = "job";
+  private readonly runningJobsByTaskId;
+  private readonly cancelRequested;
+  private _nextFireToken;
+  constructor(deps: JobFireTargetDeps);
+  canHandle(task: ScheduledTask): boolean;
+  fire(task: ScheduledTask, ctx: FireContext): Promise<FireResult>;
+  /**
+   * 设置 cancel 意图——fire() 循环在下次 attempt 前检查并停止。
+   * 同时调用 jobRegistry.cancel() 终止当前正在运行的 job。
+   * 返回 CancelResult（与 SchedulerService.cancel() 的返回类型对齐）。
+   */
+  requestCancel(taskId: string): CancelResult;
+  /** 清理 fire 完成后的记账状态。由 FireExecutor 在 fire().finally 中调用。 */
+  cleanup(taskId: string): void;
+  /** 当前有正在运行的 job 的 task id 集合。 */
+  getRunningTaskIds(): Set<string>;
+  private waitForCompletion;
+}
+//#endregion
+//#region src/fire-targets/session-fire-target.d.ts
+interface SessionFireTargetDeps {
   /**
-   * Delete a single task snapshot (awaited — must confirm removal to prevent zombies on
-   * store reload). RFC-357 D2：session-local 任务从不落盘，删除时直接视为成功（无需真的
-   * 调用 store——它本就不在 store 里），避免对不存在的记录发起一次多余的 IO。
+   * 把 prompt 注入 boundSessionId 对应的当前会话。
+   * 返回 true=已成功注入；false=失效（会话身份不匹配/已销毁/archived/paused 等）。
    */
-  private deleteOne;
+  followUp: (task: {
+    prompt: string;
+    boundSessionId: string;
+    name: string;
+    origin: 'user' | 'model';
+  }) => boolean;
   /**
-   * Flush every in-memory task to the store (used on stop; bounded, no diff-delete).
-   * RFC-357 D2（独立评审 R2）：跳过 `target==='session'` 任务——否则进程正常退出时会把
-   * 内存中的 session-local 任务写进 store，下次 `start()` 从 store 加载后在**新进程的新
-   * sessionRef** 上"复活"，直接击穿"不落盘"这条防线（本 RFC 最初设计遗漏的关键路径）。
+   * RFC-406 D6：session-local 任务创建时绑定的当前 sessionId 端口。
+   * scheduler.add() 经 SchedulerService.getSessionIdForTask() 读取此值填充 boundSessionId。
+   * （旧 SchedulerDeps.getSessionId 的语义迁入此 handler。）
    */
-  private flushAll;
+  getSessionId: () => string;
+  /** FireLogger 实例（写 fire 日志） */
+  fireLogger: FireLogger;
+}
+declare class SessionFireTarget implements FireTarget {
+  private deps;
+  readonly type = "session";
+  constructor(deps: SessionFireTargetDeps);
+  canHandle(task: ScheduledTask): boolean;
+  /** RFC-406 D6：暴露当前 sessionId 供 scheduler.add() 绑定 boundSessionId。 */
+  getSessionId(): string;
+  fire(task: ScheduledTask, _ctx: FireContext): Promise<FireResult>;
+}
+//#endregion
+//#region src/fire-targets/subscriber-fire-target.d.ts
+interface SubscriberFireTargetDeps {
   /**
-   * Write a one-line fire log to ${OTTO_HOME}/schedule-logs/<taskId>-<epoch>.log, then prune
-   * older logs for this task beyond MAX_FIRE_LOGS_PER_TASK (review S7: a `* * * * *` task
-   * fires 1440 times/day with no prior retention — the directory grew unbounded). Best-effort
-   * throughout — swallows errors silently (logging is non-critical).
+   * 向订阅者投递到点通知的窄端口。返回是否真的送达——false 表示服务未运行/已停机。
+   * 端口刻意只接受纯数据标识：handler 不知道插件服务的存在形式，也不持有其句柄。
    */
-  private writeFireLog;
-  /** Keep only the newest MAX_FIRE_LOGS_PER_TASK log files for a given taskId. */
-  private pruneFireLogs;
+  notify: (subscriber: ScheduleSubscriber, tick: {
+    scheduleId: string;
+    occurrenceId: string;
+    occurredAt: number;
+  }) => boolean;
+  /** FireLogger 实例（写 fire 日志） */
+  fireLogger: FireLogger;
+}
+declare class SubscriberFireTarget implements FireTarget {
+  private deps;
+  readonly type = "plugin-service";
+  constructor(deps: SubscriberFireTargetDeps);
+  canHandle(task: ScheduledTask): boolean;
+  fire(task: ScheduledTask, ctx: FireContext): Promise<FireResult>;
+}
+//#endregion
+//#region src/triggers/in-process-event-trigger.d.ts
+interface InProcessEventTriggerDeps {
+  jobRegistry: AgentJobRegistry;
+  now?: () => number;
+  logger?: {
+    error: (msg: string | Error, ...args: unknown[]) => void;
+  };
+  /** 闸门B：debounce 窗口（ms）。缺省 60s。 */
+  debounceWindowMs?: number;
+  /** 闸门B：窗口内最大触发次数。缺省 5。 */
+  maxFiresPerWindow?: number;
+}
+declare class InProcessEventTrigger implements EventDrivenTrigger {
+  private deps;
+  readonly type = "in-process-event";
+  /** 闸门B：每任务的触发时刻队列（滑动窗口）。 */
+  private readonly fireTimestamps;
+  private readonly now;
+  private readonly debounceWindowMs;
+  private readonly maxFiresPerWindow;
+  constructor(deps: InProcessEventTriggerDeps);
+  canHandle(task: ScheduledTask): boolean;
+  arm(task: ScheduledTask, fire: (task: ScheduledTask) => void): () => void;
+  private matches;
+  /** 闸门B：滑动窗口频率检查。返回 true=放行，false=超限拦截。 */
+  private passesDebounce;
 }
 //#endregion
 //#region src/schedule-capability.d.ts
@@ -506,6 +700,19 @@ interface ScheduleCapability {
      * the model-facing guidance on when to pick which.
      */
     target?: 'job' | 'session';
+    /**
+     * RFC-423：进程内事件触发。存在时任务由事件驱动（如 job diff applied）而非 cron。
+     * 必须配 target:'session'（或 subscriber）——事件触发不允许 job 投递（死循环闸门）。
+     */
+    eventTrigger?: {
+      source: string;
+      event: string;
+      filter?: {
+        sessionId?: string;
+      };
+    }; /** RFC-438：到点执行时使用的模型 id（如 "deepseek/deepseek-v4-flash"）。缺省 = 当前会话模型。 */
+    modelId?: string; /** RFC-438：思考档位（配 modelId 使用）。 */
+    thinkingLevel?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
   }) => {
     taskId: string;
     nextFireAt: number;
@@ -531,7 +738,14 @@ interface ScheduleCapability {
     reason?: string;
   };
 }
-declare function createScheduleCapability(getScheduler: () => SchedulerService | undefined): ScheduleCapability;
+interface ScheduleCapabilityDeps {
+  /**
+   * RFC-438 D3b：create 时校验模型 id。返回错误信息或 undefined（合法）。
+   * 缺省 = 不校验（运行时 fail-closed 兜底——fire 时 resolveJobModel 抛错）。
+   */
+  validateModelId?: (id: string) => string | undefined;
+}
+declare function createScheduleCapability(getScheduler: () => SchedulerService | undefined, deps?: ScheduleCapabilityDeps): ScheduleCapability;
 //#endregion
-export { type CancelResult, type FireOwnership, type RemoteFireOwnershipOptions, type RemoteScheduleStoreOptions, SCHEDULE_LEASE_MIGRATIONS, type ScheduleCapability, ScheduleRegistry, type ScheduleStore, type ScheduleSubscriber, type ScheduledTask, type ScheduledTaskInput, type SchedulerDeps, SchedulerService, createLocalFireOwnership, createRemoteFireOwnership, createRemoteScheduleStore, createScheduleCapability, createScheduleStore, parseCron };
+export { DEFAULT_SCHEDULE_CONFIG, type EventDrivenTrigger, type EventTriggerSpec, FireLogger, type FireOwnership, type FireTarget, InProcessEventTrigger, JobFireTarget, SCHEDULE_LEASE_MIGRATIONS, ScheduleRegistry, type ScheduleStore, type ScheduleSubscriber, type ScheduledTask, type ScheduledTaskInput, type SchedulerDeps, SchedulerService, SessionFireTarget, SubscriberFireTarget, type TerminationReason, createLocalFireOwnership, createRemoteFireOwnership, createRemoteScheduleStore, createScheduleCapability, createScheduleStore, parseCron };
 //# sourceMappingURL=index.d.ts.map