@shgroup/dsh-serenity-hooks 1.37.0 → 1.38.0

package/lib/wake-scheduler-Ebdyvzuq.js

@@ -0,0 +1,798 @@
+import { r as hostService, t as hostAgents } from "./access-fiehjxV6.js";
+import { o as listCccs } from "./ccc-roots-Bd_SjEs7.js";
+import { _ as sessionsRoot, n as listBoundSessionIds, u as findSession } from "./trajectory-bound-U3ZU_mI6.js";
+import { t as readSimpleSettings } from "./settings-section-DMDUoQum.js";
+import { basename, dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+//#region src/wake-registry.ts
+/**
+* wake-registry.ts — trajectory 唤醒注册表（D58，S142 2026-09-13）
+*
+* 需求（用户原话）：一个 CCC 内允许多个 trajectory 任意形态并行；某个 trajectory 可以
+* **预定未来唤醒自己或别人**，本质上是一次「未来时刻 + 一条 message」的投递；「周期自唤醒」
+* 曾是它的特例（原 ACC autopilot / D59，该机制已于 2026-09-15 整段退场）。协作边界：
+* 互相可见、**无阻塞无等待**。
+*
+* 本模块只负责**注册表本身**（纯数据层，无宿主依赖，可单测）：
+*  - 落点：CCC 内 `AGENT_SESSIONS/wake-registry.json`（随 CCC git，人可读可审计）
+*  - 状态机：`pending` →（投递成功）`delivered`｜（超补跑窗口）`missed`｜（`wake rm` 物理移除）
+*  - 投递即终结：一次性，不重投（无回执语义——发起方不 await，见设计文档 §2）
+*
+* 调度与投递在 `wake-scheduler.ts`（需要 ctx），本模块保持纯净。
+*/
+/** 注册表相对 CCC 根的路径（与 `.bindings.json` 同居 AGENT_SESSIONS/） */
+const WAKE_REGISTRY_REL_PATH = "AGENT_SESSIONS/wake-registry.json";
+/** 注册表格式版本（结构变更时 +1；读取端只接受本版本） */
+const WAKE_REGISTRY_VERSION = 1;
+/**
+* 补跑窗口（缺省 2h）：dsh 停机期间到期的条目，若迟到不超过本窗口则补投，
+* 超过则置 `missed` 留痕（不补投——避免"半夜该做的事早上突然连环跑"）。
+*/
+const WAKE_CATCH_UP_MS = 72e5;
+/** 注册表绝对路径 */
+function wakeRegistryPath(root) {
+	return join(root, WAKE_REGISTRY_REL_PATH);
+}
+/** 空注册表 */
+function emptyRegistry() {
+	return {
+		version: WAKE_REGISTRY_VERSION,
+		entries: []
+	};
+}
+/** 条目形状校验（容忍手改：字段缺失/类型不符 → 丢弃该条，不阻断整表） */
+function asEntry(value) {
+	const e = value;
+	if (!e || typeof e.id !== "string" || typeof e.target !== "string") return null;
+	if (typeof e.at !== "string" || typeof e.message !== "string") return null;
+	const state = e.state === "delivered" || e.state === "missed" || e.state === "cancelled" ? e.state : "pending";
+	return {
+		id: e.id,
+		target: e.target,
+		at: e.at,
+		message: e.message,
+		state,
+		createdBy: typeof e.createdBy === "string" ? e.createdBy : "",
+		createdAt: typeof e.createdAt === "string" ? e.createdAt : "",
+		attempts: typeof e.attempts === "number" && Number.isFinite(e.attempts) ? e.attempts : 0,
+		lastResult: typeof e.lastResult === "string" ? e.lastResult : null,
+		deliveredAt: typeof e.deliveredAt === "string" ? e.deliveredAt : null
+	};
+}
+/**
+* 读注册表。文件缺失 → 空表；损坏 → 空表 + error（不抛错，调用方决定是否告警）。
+* @param root CCC 根
+* @returns 注册表与读取错误（无错为 null）
+*/
+function loadWakeRegistry(root) {
+	const path = wakeRegistryPath(root);
+	if (!existsSync(path)) return {
+		registry: emptyRegistry(),
+		error: null
+	};
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8"));
+		const raw = Array.isArray(parsed.entries) ? parsed.entries : [];
+		const entries = [];
+		for (const item of raw) {
+			const e = asEntry(item);
+			if (e) entries.push(e);
+		}
+		return {
+			registry: {
+				version: WAKE_REGISTRY_VERSION,
+				entries
+			},
+			error: null
+		};
+	} catch (err) {
+		return {
+			registry: emptyRegistry(),
+			error: `唤醒注册表解析失败（${String(err?.message ?? err)}）`
+		};
+	}
+}
+/** 原子写（tmp + rename；与 .bindings.json 同款形态） */
+function saveWakeRegistry(root, registry) {
+	const path = wakeRegistryPath(root);
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		const tmp = `${path}.tmp`;
+		writeFileSync(tmp, `${JSON.stringify({
+			version: WAKE_REGISTRY_VERSION,
+			entries: registry.entries
+		}, null, 2)}\n`, "utf-8");
+		renameSync(tmp, path);
+		return {
+			ok: true,
+			error: null
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			error: `唤醒注册表写入失败（${String(err?.message ?? err)}）`
+		};
+	}
+}
+/** 条目 id：`w-<UTC 到分钟>-<4 hex>`（可读 + 低碰撞；不复用由"物理移除"保证） */
+function newWakeId(nowMs, rand = Math.random) {
+	const iso = new Date(nowMs).toISOString();
+	return `w-${`${iso.slice(0, 10).replace(/-/g, "")}-${iso.slice(11, 16).replace(":", "")}`}-${Math.floor(rand() * 65536).toString(16).padStart(4, "0")}`;
+}
+/**
+* 解析唤醒时刻。接受两种写法（设计文档 §7）：
+*  - 绝对：RFC3339（含时区偏移，如 `2026-09-14T09:00:00+08:00`）
+*  - 相对：`+30m` / `+2h`（便于 agent 直接登记"半小时后"）
+* @param input 用户/agent 传入的时刻串
+* @param nowMs 当前时刻（相对写法基准）
+* @returns `{ ok, ms }` 或 `{ ok: false, error }`
+*/
+function parseWakeAt(input, nowMs) {
+	const raw = input.trim();
+	if (raw === "") return {
+		ok: false,
+		error: "时刻为空"
+	};
+	const rel = /^\+(\d+(?:\.\d+)?)([mhd])$/.exec(raw);
+	if (rel) {
+		const n = Number(rel[1]);
+		const unit = rel[2];
+		return {
+			ok: true,
+			ms: nowMs + n * (unit === "m" ? 6e4 : unit === "h" ? 36e5 : 864e5)
+		};
+	}
+	const ms = Date.parse(raw);
+	if (!Number.isFinite(ms)) return {
+		ok: false,
+		error: `时刻无法解析（须 RFC3339 或 +30m/+2h）: ${raw}`
+	};
+	return {
+		ok: true,
+		ms
+	};
+}
+/**
+* 登记一条唤醒。
+* @param root CCC 根
+* @param input 目标 trajectory / 时刻串 / message / 发起者 / 当前时刻
+* @returns 成功返回条目，失败返回稳定错误文案（不抛错）
+*/
+function addWake(root, input) {
+	const target = input.target.trim();
+	if (target === "") return {
+		ok: false,
+		error: "target 为空（须 S### 或 AGENT_SESSIONS 目录名）"
+	};
+	const message = input.message.trim();
+	if (message === "") return {
+		ok: false,
+		error: "message 为空（唤醒必须携带一条信息）"
+	};
+	const parsed = parseWakeAt(input.at, input.nowMs);
+	if (!parsed.ok) return {
+		ok: false,
+		error: parsed.error
+	};
+	if (parsed.ms <= input.nowMs) return {
+		ok: false,
+		error: "时刻必须在未来（唤醒只允许可预期的未来）"
+	};
+	const { registry, error } = loadWakeRegistry(root);
+	if (error) return {
+		ok: false,
+		error
+	};
+	const entry = {
+		id: newWakeId(input.nowMs),
+		target,
+		at: new Date(parsed.ms).toISOString(),
+		message,
+		state: "pending",
+		createdBy: input.createdBy,
+		createdAt: new Date(input.nowMs).toISOString(),
+		attempts: 0,
+		lastResult: null,
+		deliveredAt: null
+	};
+	registry.entries.push(entry);
+	const saved = saveWakeRegistry(root, registry);
+	if (!saved.ok) return {
+		ok: false,
+		error: saved.error ?? "写入失败"
+	};
+	return {
+		ok: true,
+		entry
+	};
+}
+/**
+* 到期切分（纯函数，可单测）：
+*  - `due`：`state === 'pending'` 且 `now >= at`（在补跑窗口内）→ 应投递
+*  - `expired`：`state === 'pending'` 且 `now - at > catchUpMs` → 应置 missed（不投递）
+* @param registry 注册表
+* @param nowMs 当前时刻
+* @param catchUpMs 补跑窗口
+*/
+function splitDueWakes(registry, nowMs, catchUpMs = WAKE_CATCH_UP_MS) {
+	const due = [];
+	const expired = [];
+	for (const e of registry.entries) {
+		if (e.state !== "pending") continue;
+		const at = Date.parse(e.at);
+		if (!Number.isFinite(at) || nowMs < at) continue;
+		if (nowMs - at > catchUpMs) expired.push(e);
+		else due.push(e);
+	}
+	return {
+		due,
+		expired
+	};
+}
+/**
+* 更新一条（状态推进；调用方给最终状态与结果文案）。
+* @param root CCC 根
+* @param id 条目 id
+* @param patch 要写入的字段
+* @returns 写入结果
+*/
+function updateWake(root, id, patch) {
+	const { registry, error } = loadWakeRegistry(root);
+	if (error) return {
+		ok: false,
+		error
+	};
+	const entry = registry.entries.find((e) => e.id === id);
+	if (!entry) return {
+		ok: false,
+		error: `wake_not_found: ${id}`
+	};
+	Object.assign(entry, patch);
+	return saveWakeRegistry(root, registry);
+}
+/** 列条目（默认全量；`pendingOnly` 只列在办项——面板/工具用） */
+function listWakes(root, opts = {}) {
+	const { registry, error } = loadWakeRegistry(root);
+	return {
+		entries: [...opts.pendingOnly ? registry.entries.filter((e) => e.state === "pending") : registry.entries].sort((a, b) => Date.parse(a.at) - Date.parse(b.at)),
+		error
+	};
+}
+//#endregion
+//#region src/host/effect.ts
+/** 已告警的标签（进程级去重：重复装配/多测试替身不刷屏，但绝不静默） */
+const warnedLabels = /* @__PURE__ */ new Set();
+/**
+* 登记一个卸载时执行的清理。
+* @param ctx 宿主插件上下文
+* @param label 日志标签（定位是哪个资源未装配）
+* @param cleanup 卸载时执行；抛错被吞掉（不阻断其它清理）
+* @returns 是否成功装配（false = 宿主无 `ctx.effect`，已告警）
+*/
+function registerDisposer(ctx, label, cleanup) {
+	const effect = ctx?.effect;
+	if (typeof effect !== "function") {
+		if (!warnedLabels.has(label)) {
+			warnedLabels.add(label);
+			console.warn(`[serenity-hooks] ✗ 资源拆卸未装配（${label}）：ctx.effect 不可用（宿主契约缺失）`);
+		}
+		return false;
+	}
+	try {
+		effect.call(ctx, () => () => {
+			try {
+				cleanup();
+			} catch (err) {
+				console.warn(`[serenity-hooks] ✗ 资源清理失败（${label}）: ${String(err?.message ?? err)}`);
+			}
+		}, `dsh-serenity-hooks: ${label}`);
+		return true;
+	} catch (err) {
+		console.warn(`[serenity-hooks] ✗ 资源拆卸注册失败（${label}）: ${String(err?.message ?? err)}`);
+		return false;
+	}
+}
+//#endregion
+//#region src/clock-runtime.ts
+/**
+* clock-runtime.ts — **时钟运行时工厂**（S142 §38 复审候选 C6b，路径 **P2**）
+*
+* 本仓有**两条各自独立运行**的 5min 时钟：
+*   · 唤醒调度器（`wake-scheduler.ts`，一次性唤醒，D58）
+*   · autopilot 时钟（`autopilot-trajectory.ts`，周期自唤醒，D59）
+* 二者的**业务判据完全不同**（谁来扫 / 扫什么 / 投递给谁 / 按什么周期），但**引擎骨架逐字同形**
+* ——进程态 + 快照 + 复位 + `startTimer` + tick 外壳 + 事件接线 + disposer + `timer.unref()`。
+* 本条把**引擎**抽到本工厂，**各钟仍各持自己的定时器与自己的串行链**。
+*
+* ───────────────────────────────────────────────────────────────────────────
+* 🔴 硬约束一：**两条时钟绝不可共用"排队执行"的链**（这是 P2 与 P1 的分界判据）
+*
+* autopilot 每轮要跑该 CCC 的**偏见脚本**（`fetchBiasContent`，超时 60s），可能阻塞数十秒；
+* 若与唤醒调度器共用一条串行链，会把另一条一起**卡住**（一次性唤醒被无关的偏见脚本拖住）。
+* ⇒ 本工厂把 `chain` 作为**每实例私有状态**：`createClock()` 调用一次 = 一条独立的串行域。
+*    实例之间**零共享**（无模块级单例、无共享 Promise、无共享 map）。
+* ⚠️ 若日后有人把 `chain` 提到模块级"省一次分配"，**两条时钟的隔离即刻失效**——不许。
+*
+* 🔴 硬约束二：**武装门只判全局闸**（`gate()`），**不判"本次有无目标"**
+*
+* 2026-09-14 F 段实测缺陷：旧实现把"有 live CCC"当**武装前置条件**，而宿主刚重启时 live 会话
+* 必为空，且**"恢复旧会话"不触发 `session/created`**（只有新建会）⇒ 启动瞬间判定落空 =
+* **时钟永久不武装**（实测 6.6h 零 tick）。⇒ 现在「**全局闸开即武装**」，"有无目标"降级为
+* tick 内的廉价判定。**武装与"本次有无目标"是两件事，本工厂不得把二者耦合。**
+*
+* 🔴 硬约束三：**两条闸必须继续分开传**（v1.34 S-1 解耦）
+*
+* 唤醒调度器 `wakeSchedulerEnabled`（**缺省开**）｜autopilot `autopilotWakeEnabled`
+* （**缺省关**）——取值方向相反。工厂取 `gate` **回调**（每次现读），**不做**任何合并或缓存。
+*
+* ───────────────────────────────────────────────────────────────────────────
+* 两条时钟**逐项语义差**（`ClockOptions` 的每个可配项都对应下表一行，不是随意的灵活性）：
+*
+* | 项 | 唤醒调度器 | autopilot | 工厂表达 |
+* |----|-----------|-----------|---------|
+* | `chain` | 有（全局串行） | 有（全局串行） | **总是私有**（硬约束一） |
+* | `lastTickLog` | 有（逐行摘要） | **无** | `logFrom` 不给 = 不记 |
+* | `ticks` 记账 | 工厂在 body **完成后**记 | **本钟**在同步段记 | `bodyCountsTick` + `begin` |
+* | body 返回类型 | `string[]`（人读摘要） | `void` | 泛型 `T` |
+* | 启动日志 | 固定串 | 含启用 CCC 计数 | `startLog: () => string` |
+* | body 异常兜底 | 留痕 + `console.warn` | 同 | 工厂统一（**吞异常不改语义**） |
+*
+* ───────────────────────────────────────────────────────────────────────────
+* **本工厂是"加法式"重构**（P2 的性质）：不新增任何判定逻辑，只把同形骨架收成一份代码；
+* 两个模块仍各自导出 `wakeSchedulerState()` / `autopilotClockState()` 与各自的
+* `__reset…ForTest()`，**对外可观测面（字段名与语义）零变化**——`acc-diag` ①b 段、
+* `container-status.ts:containerClocks()` 与面板都在读它们（见该文件 :225–250 的设计红线）。
+*
+* 为什么**不**取 P1（真合并成一个 `setInterval` + 两条策略）——2026-09-15 所有者裁决：
+* P1 只多省 ~20 行，却要把 `armed` 拆成"宿主 + 每策略"两层、并强行分开串行域，
+* 即**动两条正在跑的时钟的骨架**；**不值当**（裁决原文见 SESSION §12.8②）。
+*/
+/**
+* tick 周期（**5 分钟**）。
+*
+* 2026-09-15 S142「ACC 侧 autopilot 退场」：本值原从 `autopilot-core.ts` 导入（`TICK_MS`），
+* 但该模块随 autopilot 退场，而**本模块的唯一消费者是唤醒调度器**（`wake-scheduler`）——
+* 值本身与 autopilot 无关 ⇒ 随消费者归位到本模块（不再依赖 autopilot 判据层）。
+*
+* ⚠️ 语义不得变：该值同时是**报告文案的来源**（"等下个 Nmin tick"），历史上曾因文案写死
+* 10min 与实现 5min 不符而误导排查（§12.7 文案纠错）。
+*/
+const TICK_MS = 3e5;
+/**
+* 挂事件 → 触发 `start()`（**每个事件一次 try/catch 吞异常**：事件通道缺失不阻断时钟）。
+*
+* 为什么吞异常：宿主（headless profile 等）可能没有事件通道；**启动时已 `start()` 过一次**，
+* 事件只是"跟上面板开关 / 新会话"的热启动补丁，缺它不该让整个装配抛错。
+* @param on 宿主的 `on`（可能不存在）
+* @param ctx `on` 的 `this`（宿主 API 常要求绑定）
+* @param clock 目标时钟
+* @param events 事件名列表（回调恒为 `() => clock.start()`）
+*/
+function attachClockEvents(ctx, clock, events) {
+	const on = ctx?.on;
+	if (typeof on !== "function") return;
+	for (const name of events) try {
+		on.call(ctx, name, () => clock.start());
+	} catch {}
+}
+/**
+* 建一条时钟（**每钟各调一次**——本工厂**不是**单例，调用次数 = 时钟条数）。
+*
+* 顺序忠实于既有实现：`start()` 先武装并立即跑一次 tick → 再挂事件。
+* 拆卸由调用方经 `registerDisposer(ctx, label, clock.dispose)` 落到宿主的 `ctx.effect`。
+* @param opts 见 {@link ClockOptions}（每项对应一条既有的语义差）
+* @returns 该钟的 `{start, dispose, snapshot, reset}`
+*/
+function createClock(opts) {
+	const runtime = {
+		armed: false,
+		armedAt: null,
+		lastTickAt: null,
+		ticks: 0,
+		lastSkipReason: null
+	};
+	if (opts.logFrom) runtime.lastTickLog = [];
+	const st = {
+		timer: null,
+		chain: Promise.resolve(),
+		runtime,
+		wired: false,
+		opts
+	};
+	/** 记一次 tick（工厂内部与 body 共用同一实现——只有一处会计逻辑） */
+	const countTick = () => {
+		runtime.lastTickAt = Date.now();
+		runtime.ticks += 1;
+	};
+	/** 逐行打印（`logFrom` 缺省 ⇒ 本钟无 tick 日志，整段为死代码路径） */
+	const emit = (lines) => {
+		if (!opts.logFrom) return;
+		for (const line of lines) console.log(`${opts.logFrom.prefix}${line}`);
+	};
+	const tick = () => {
+		if (!opts.gate()) {
+			runtime.lastSkipReason = opts.gateOffReason;
+			return;
+		}
+		if (opts.begin) try {
+			opts.begin();
+		} catch (err) {
+			console.warn(`[serenity-hooks] ✗ tick 前置异常: ${String(err?.message ?? err)}（${opts.label}）`);
+			return;
+		}
+		st.chain = st.chain.then(async () => {
+			try {
+				const value = await opts.body();
+				if (!opts.bodyCountsTick) countTick();
+				if (opts.logFrom) {
+					runtime.lastTickLog = opts.logFrom.lines(value);
+					emit(runtime.lastTickLog);
+				}
+			} catch (err) {
+				const msg = `✗ tick 异常: ${String(err?.message ?? err)}`;
+				if (opts.logFrom) runtime.lastTickLog = [msg];
+				console.warn(`[serenity-hooks] ${msg}（${opts.label}）`);
+			}
+		});
+	};
+	/**
+	* 幂等启动 + 武装门：**已武装 → 原样返回**（防重复起定时器）；
+	* **闸关 → 不武装**（零资源占用）；闸开则**无条件**武装（硬约束二：不判"有无目标"）。
+	*/
+	const start = () => {
+		if (st.timer) return;
+		if (opts.events && !st.wired) {
+			st.wired = true;
+			attachClockEvents(opts.ctx, api, opts.events);
+		}
+		if (!opts.gate()) return;
+		st.timer = setInterval(tick, TICK_MS);
+		st.timer.unref();
+		runtime.armed = true;
+		runtime.armedAt = Date.now();
+		console.log(opts.startLog());
+		if (opts.immediate !== false) tick();
+	};
+	const dispose = () => {
+		if (st.timer) {
+			clearInterval(st.timer);
+			st.timer = null;
+		}
+		runtime.armed = false;
+		runtime.armedAt = null;
+		opts.onDispose?.();
+	};
+	const api = {
+		start,
+		dispose,
+		snapshot: () => ({
+			enabled: opts.gate(),
+			...runtime,
+			...runtime.lastTickLog ? { lastTickLog: [...runtime.lastTickLog] } : {}
+		}),
+		noteSkipReason: (reason) => {
+			runtime.lastSkipReason = reason;
+		},
+		countTick,
+		enqueue: (work) => {
+			st.chain = st.chain.then(work, () => void 0).then(() => void 0, (err) => {
+				console.warn(`[serenity-hooks] ✗ 串行任务异常（${opts.label}）: ${String(err?.message ?? err)}`);
+			});
+		},
+		reset: () => {
+			if (st.timer) {
+				clearInterval(st.timer);
+				st.timer = null;
+			}
+			runtime.armed = false;
+			runtime.armedAt = null;
+			runtime.lastTickAt = null;
+			runtime.ticks = 0;
+			runtime.lastSkipReason = null;
+			if (opts.logFrom) runtime.lastTickLog = [];
+			st.wired = false;
+			opts.onReset?.();
+		}
+	};
+	return api;
+}
+//#endregion
+//#region src/wake-scheduler.ts
+const PLUGIN_SOURCE = {
+	kind: "plugin",
+	plugin: "dsh-serenity-hooks"
+};
+/**
+* 解析条目的 target（`S###` 或完整目录名）→ 目录名 + SESSION.md 路径。
+* @param root CCC 根
+* @param target 条目里的目标标识
+* @returns 命中返回目录信息，未命中 null
+*/
+function resolveWakeTarget(root, target) {
+	const found = findSession(sessionsRoot(root), target);
+	if (!found) return null;
+	const mdPath = join(found.path, "SESSION.md");
+	if (!existsSync(mdPath)) return null;
+	return {
+		dirName: basename(found.path),
+		mdPath
+	};
+}
+/**
+* 全局闸：**只看 `wakeSchedulerEnabled`**（缺省**开**；显式 `false` 才关）。
+*
+* ⚠️ 2026-09-15 用户裁决（S-1 **解耦**）：「auto-trajectory 的开关**只关闭 auto-trajectory 唤醒**」。
+* ⇒ 本函数**不得**再把 `autopilotEnabled`（周期自唤醒闸）作为回退键 —— 旧实现是
+* `trajectoryEnabled === true || autopilotEnabled === true`，后果实测：所有者关掉 auto-trajectory 后，
+* **一次性唤醒 `wake-later` 被连带关掉**，注册表条目静默滞留（当日 6.6h 零 tick）。
+* 缺省由 false 改 true 的理由：唤醒注册表已是一等机制（D58），条目**全部由人类/agent 显式登记**
+* 未来时刻（无环境自主性），不需要"默认关"的实验保护；代价 = 一个 unref 的 5min 空检查。
+*
+* 设置服务不可用 → 关（保守；异常由日志与 `dashboard health` 响亮暴露，不静默）。
+*/
+function wakeSchedulerEnabled() {
+	try {
+		return readSimpleSettings().wakeSchedulerEnabled !== false;
+	} catch {
+		return false;
+	}
+}
+/**
+* 🔴 **本钟的串行域**（C6b 硬约束）：`clock.chain` 是**本实例私有**的——
+* 与 autopilot 的串行链**零共享**。autopilot 每轮跑 CCC 偏见脚本可能阻塞数十秒，
+* 共用链会把一次性唤醒一起卡住（这正是 P1 被否、取 P2 的理由，见 SESSION §12.8②）。
+*
+* **为什么这里是模块级常量**（而不是 `registerWakeScheduler` 的局部量）：本钟的进程态是
+* **进程级可观测面**（`acc-diag` ①b / `containerClocks` 在读），且 `wakeSchedulerState()` /
+* `__resetWakeSchedulerStateForTest()` 是**公开导出**、可在未装配时被调用 ⇒ 实例必须**恒在**
+* （旧实现的 `schedulerRuntime` 也正是模块级常量）。装配只做 `clock.start()`。
+*/
+/** 本钟的装配项（`ctx` 由 {@link registerWakeScheduler} 在装配点填入） */
+const clockOpts = {
+	label: "trajectory 唤醒调度器",
+	ctx: void 0,
+	events: ["session/created", "serenity/settings-changed"],
+	gate: wakeSchedulerEnabled,
+	gateOffReason: "唤醒调度器闸关闭（wakeSchedulerEnabled=false）",
+	body: () => runWakeTick(clockOpts.ctx),
+	logFrom: {
+		prefix: "[serenity-hooks] trajectory 唤醒 ",
+		lines: (lines) => lines
+	},
+	startLog: () => "[serenity-hooks] ✓ trajectory 唤醒调度器启动（5min tick）"
+};
+const clock = createClock(clockOpts);
+/** 调度器进程态快照（只读；`enabled` = 全局闸**当前**值，便于区分"未武装"与"闸关"） */
+function wakeSchedulerState() {
+	return clock.snapshot();
+}
+/**
+* 取目标 agent：live 优先 → 冷会话走 sessionController.resolveAgent → 标题回退。
+* @param ctx 插件上下文
+* @param root CCC 根
+* @param dirName 目标 trajectory 目录名
+* @returns 命中返回 agent 与取得方式（how 进 lastResult，便于诊断）；未命中返回原因
+*/
+async function acquireWakeAgent(ctx, root, dirName) {
+	const agents = hostAgents(ctx);
+	const ids = listBoundSessionIds(root, dirName);
+	for (const id of ids) {
+		const live = agents?.get?.(id);
+		if (live) return {
+			agent: live,
+			how: `live(bound ${id})`
+		};
+	}
+	if (ids.length > 0) {
+		const sc = hostService(ctx, "sessionController");
+		const resolved = sc?.resolveAgent;
+		if (typeof resolved !== "function") return { error: `目标会话未加载且 sessionController 不可用（headless profile？）——绑定 id: ${ids[0]}` };
+		const id = ids[0];
+		try {
+			const out = await resolved.call(sc, id);
+			if (out?.agent) return {
+				agent: out.agent,
+				how: `cold-resume(${id})`
+			};
+			return { error: `sessionController.resolveAgent 未返回 agent（${id}）: ${String(out?.error ?? "未知原因")}` };
+		} catch (err) {
+			return { error: `冷会话载入失败（${id}）: ${String(err?.message ?? err)}` };
+		}
+	}
+	return { error: `无绑定会话记录（AGENT_SESSIONS/.bindings.json 中无 ${dirName}）——目标轨迹需先被 container_trajectory use 激活过` };
+}
+/** 唤醒消息（唤起即投递正文：身份锚定 + 唤醒信息 + 任务） */
+function buildWakeText(entry, target) {
+	return [
+		`[trajectory 唤醒] 到点（登记于 ${entry.createdAt}，发起者 ${entry.createdBy || "未知"}，id ${entry.id}）。`,
+		"",
+		`身份锚定：继续 ${target.dirName} 的 trajectory（SESSION.md: ${target.mdPath}）。`,
+		"",
+		"唤醒信息：",
+		entry.message,
+		"",
+		"任务：按上述唤醒信息继续本轨迹的工作；完成后把进展写入 SESSION.md。"
+	].join("\n");
+}
+/**
+* 投递一条唤醒（fire-and-forget：`followup` 入队即返回，不等模型结果）。
+* @param ctx 插件上下文
+* @param root CCC 根
+* @param entry 唤醒条目
+* @returns 投递结果（写回 lastResult）
+*/
+async function deliverWake(ctx, root, entry) {
+	const target = resolveWakeTarget(root, entry.target);
+	if (!target) return {
+		ok: false,
+		detail: `目标 trajectory 未命中（${entry.target}）`
+	};
+	const acquired = await acquireWakeAgent(ctx, root, target.dirName);
+	if ("error" in acquired) return {
+		ok: false,
+		detail: acquired.error
+	};
+	try {
+		acquired.agent.followup(createUserMessage({
+			content: [{
+				type: "text",
+				text: buildWakeText(entry, target)
+			}],
+			source: PLUGIN_SOURCE
+		}));
+	} catch (err) {
+		return {
+			ok: false,
+			detail: `投递失败（${acquired.how}）: ${String(err?.message ?? err)}`
+		};
+	}
+	return {
+		ok: true,
+		detail: `已投递 ${target.dirName}（${acquired.how}）`
+	};
+}
+/**
+* 即时消息正文（**刻意不复用** {@link buildWakeText}）：唤醒文本以「**到点**（登记于…）」开头，
+* 对即时投递那是**错的事实**。本函数显式区分"这是即时消息、不是到点唤醒"，
+* 并写明"消息已入队、若此前在跑轮次则本轮结束后生效"（防目标误判时序）。
+* @param target 目标轨迹（目录名 + SESSION.md）
+* @param message 递送正文
+* @param sender 发起者轨迹标识（供目标与人类识别来源）
+*/
+function buildSendText(target, message, sender) {
+	return [
+		`[即时消息] 来自 ${sender || "未知轨迹"}。`,
+		"",
+		`身份锚定：继续 ${target.dirName} 的 trajectory（SESSION.md: ${target.mdPath}）。`,
+		"",
+		"消息：",
+		message,
+		"",
+		"说明：这是**即时投递**（不是到点唤醒）——消息已进入你的队列；你此前若正在跑轮次，它在本轮结束后生效。处理完照常把进展写入 SESSION.md。"
+	].join("\n");
+}
+/**
+* 即时投递（`container_trajectory send-message`）——与唤醒**共用取用通路**，
+* 区别只在**时刻**（现在 vs 未来）与**回执**（有 vs 无）：
+*   · `wake-later`：未来时刻 + 一条 message → 落注册表 → 本文件的调度器到点投递（**fire-and-forget，无回执**）
+*   · `send-message`：**此刻**把一条 message 递进目标队列 → **同步回执** → **不落注册表**
+*
+* **为什么冷路径落在这里（R↓，2026-09-16 所有者裁决）**：`addWake` 显式拒绝 `at ≤ now`
+* （"时刻必须在未来"——那是"**预约**"语义的地基，不许放宽）⇒ 即时投递**不能**靠一条
+* `at=now` 的注册表条目实现（那还会让调度器把一次性即时投递当 `pending` **每 tick 重试**）。
+* 必须直接走 {@link acquireWakeAgent}（live 优先 → `sessionController.resolveAgent` 冷载入）。
+* 这正对应所有者要的「**会话不活跃则等效于直接 wake**」：**同一条冷载入通路**，只是**不等 tick**。
+*
+* ⚠️ **承诺边界（不许含糊）**：回执只到「**已入队**」（`followup` 未抛错），
+* **到不了**"目标已执行/已答复" —— 与 `deliverWake` 同一层。目标若正在跑轮次，
+* 消息**排在轮次边界**（**不打断当前轮**）。判"目标真的动了"必须用**文件级判据**
+* （它自己的 SESSION.md），**不得凭回执结案**（§12.B 的 `delivered ≠ 跑了一轮`）。
+*
+* **归属**：本函数放在调度器侧而非工具侧 —— "怎么把一句话送到一条轨迹"是**调度器的知识**，
+* 工具只该知道"有这个动作"。这样 `trajectory.ts` 完全不碰调度器内部（v1.35.0 硬约束①：
+* `wake-later` 链路**一行为不动**，本次改动 = **纯新增**）。
+*
+* @param ctx 插件上下文
+* @param root CCC 根
+* @param target `S###` 或 AGENT_SESSIONS 目录名
+* @param message 递送正文
+* @param sender 发起者轨迹标识
+* @returns 投递结果（**同步**返回给调用方）
+*/
+async function sendToTrajectory(ctx, root, target, message, sender) {
+	const t = resolveWakeTarget(root, target);
+	if (!t) return {
+		ok: false,
+		detail: `目标 trajectory 未命中（${target}）`
+	};
+	const acquired = await acquireWakeAgent(ctx, root, t.dirName);
+	if ("error" in acquired) return {
+		ok: false,
+		detail: acquired.error
+	};
+	try {
+		acquired.agent.followup(createUserMessage({
+			content: [{
+				type: "text",
+				text: buildSendText(t, message, sender)
+			}],
+			source: PLUGIN_SOURCE
+		}));
+	} catch (err) {
+		return {
+			ok: false,
+			detail: `投递失败（${acquired.how}）: ${String(err?.message ?? err)}`
+		};
+	}
+	return {
+		ok: true,
+		detail: `已即时投递 ${t.dirName}（${acquired.how}）`
+	};
+}
+/**
+* 本 tick 要扫的 CCC 根集合（**并集**）。
+*
+* C2（S142 2026-09-15 Q5）：原实现是 `collectLiveCccs`——**只认 live 会话** ⇒
+* "完全冷掉的 CCC 不能自唤醒自己"（已知边界）。现改为 `ccc-roots.listCccs` 的并集枚举
+* （工作区注册表 ∪ 持久化会话 ∪ live 会话）：**没有 live 会话的 CCC 也会被扫到**。
+*
+* ⚠️ 边界（本步**只**改"枚举哪些 CCC"，**不改**"怎么找到要交付的 agent"）：
+* 把 message 交给某条 trajectory 仍必须靠 **live 会话**解析（见本文件
+* `acquireWakeAgent`）；无 live 会话时该 CCC 只是**被扫到、
+* 无交付对象** ⇒ `deliverWake` 返回 `无绑定会话记录…`，条目回 `pending` 并留痕。
+* 因此本函数**不得**让 tick 抛错（异常一律由调用方 tick 兜住，见 `runWakeTick` 的 try）。
+* @param ctx 插件上下文
+* @returns CCC 根列表（无任何来源 → `[]`）
+*/
+async function collectWakeCccs(ctx) {
+	return (await listCccs(ctx)).map((e) => e.root);
+}
+/** 一次调度 tick：遍历已知 CCC → 到期项串行投递 / 超窗项置 missed；返回人读摘要 */
+async function runWakeTick(ctx) {
+	const log = [];
+	const roots = await collectWakeCccs(ctx).catch(() => []);
+	if (roots.length === 0) {
+		clock.noteSkipReason("无已知 CCC 可扫（等某个会话/工作区出现）");
+		return log;
+	}
+	clock.noteSkipReason(null);
+	for (const root of roots) {
+		const { registry, error } = loadWakeRegistry(root);
+		if (error) {
+			log.push(`✗ ${root}: ${error}`);
+			continue;
+		}
+		const { due, expired } = splitDueWakes(registry, Date.now(), WAKE_CATCH_UP_MS);
+		for (const e of expired) {
+			updateWake(root, e.id, {
+				state: "missed",
+				lastResult: `超过补跑窗口（${WAKE_CATCH_UP_MS / 36e5}h）未投递`
+			});
+			log.push(`· ${root}: ${e.id} → missed（超补跑窗口）`);
+		}
+		for (const e of due) {
+			const res = await deliverWake(ctx, root, e);
+			updateWake(root, e.id, {
+				state: res.ok ? "delivered" : "pending",
+				attempts: e.attempts + 1,
+				lastResult: res.detail,
+				deliveredAt: res.ok ? (/* @__PURE__ */ new Date()).toISOString() : null
+			});
+			log.push(`· ${root}: ${e.id} → ${res.ok ? "delivered" : `重试（${res.detail}）`}`);
+		}
+	}
+	return log;
+}
+/**
+* 装配调度器（index.ts apply 调用）：5min tick + 生命周期 disposer +
+* 会话出现/settings 变化时热启动（与 autopilot 同款触发面，互不干扰）。
+* @param ctx 插件上下文
+*/
+function registerWakeScheduler(ctx) {
+	clockOpts.ctx = ctx;
+	clock.start();
+	registerDisposer(ctx, "trajectory 唤醒调度器", () => clock.dispose());
+}
+//#endregion
+export { WAKE_CATCH_UP_MS as a, registerDisposer as i, sendToTrajectory as n, addWake as o, wakeSchedulerState as r, listWakes as s, registerWakeScheduler as t };