@shgroup/dsh-serenity-hooks 1.42.0 → 1.44.0

package/lib/{wake-scheduler-1AsvNQPW.js → wake-scheduler-C2GwdriD.js}

@@ -1,9 +1,11 @@
 import { r as hostService, t as hostAgents } from "./access-fiehjxV6.js";
-import { o as listCccs } from "./ccc-roots-Bd_SjEs7.js";
-import { D as localHuman, O as localIdStamp, T as isoLocal, b as sessionsRoot, n as listBoundSessionIds, p as findSession } from "./trajectory-bound-4xkZDfmO.js";
+import { g as resolveInside } from "./ccc-DG4Oc7I1.js";
+import { o as listCccs } from "./ccc-roots-FxWXuZPw.js";
+import { D as localHuman, O as localIdStamp, T as isoLocal, b as sessionsRoot, n as listBoundSessionIds, p as findSession } from "./trajectory-bound-BzdzsDPI.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 { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 //#region src/wake-registry.ts
 /**
@@ -42,7 +44,7 @@ function emptyRegistry() {
 	};
 }
 /** 条目形状校验（容忍手改：字段缺失/类型不符 → 丢弃该条，不阻断整表） */
-function asEntry(value) {
+function asEntry$1(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;
@@ -76,7 +78,7 @@ function loadWakeRegistry(root) {
 		const raw = Array.isArray(parsed.entries) ? parsed.entries : [];
 		const entries = [];
 		for (const item of raw) {
-			const e = asEntry(item);
+			const e = asEntry$1(item);
 			if (e) entries.push(e);
 		}
 		return {
@@ -361,6 +363,459 @@ function listWakes(root, opts = {}) {
 	};
 }
 //#endregion
+//#region src/cro.ts
+/**
+* cro.ts — CRO（Continuous Re-Occurrence · 持续再发生）机制层（S142 §7.8，2026-09-19）
+*
+* ## 这东西用来干什么（白话）
+*
+* 今天叫醒一条轨迹的方式是「几点几分叫我」。但**该不该醒，往往不是时间说了算**：
+* 比如 S185 应该「天亮 + 家里有人 + 非高峰」才醒；已经在干活就不该再叫；
+* 日志太大了，下次叫它时该让它先整理。
+*
+* CRO 让**一条轨迹自己带一段程序**，由 ACC 在每次检查时跑它，
+* **由这段程序决定「现在该不该叫我、叫我的时候说什么」**。
+*
+* ## 归属（所有者 2026-09-19 定：**机制属 ACC，CCC 是用户**）
+*
+* | 面 | 归谁 | 内容 |
+* |---|---|---|
+* | **机制** | 🔴 **ACC（本模块）** | 契约 / 调度 / 执行 / 状态暴露 / 容错 |
+* | **程序** | 🔴 **CCC（用户）** | 那段判定的 TS 代码，放**轨迹自己的目录**里 |
+*
+* ⇒ 与 `send-later` 同构：**工具在 ACC，用它在 CCC**。
+*
+* ## 命名（防混淆，写死）
+*
+* **`CRO` = 那段程序**（实体名），**不是** ACC 标准 §0.1 三环节（发生/存储/**再发生**）的第三环本身。
+* 命名来源 = §0.3「**Trajectory 在寻找 Agent**」——CRO 是「再发生」这一环的自动化。
+*
+* ## 位置与形态（设计 §2）
+*
+* `<CCC 根>/AGENT_SESSIONS/<轨迹目录>/continuous-re-occurrence.ts`
+* · **文件名全写**（所有者令）；· **程序只有一个**：**文件在 = 启用，不在 = 禁用**（无 enabled 字段、无注册表）。
+*
+* ## 🔴 运行契约 = B 案（**ACC 只 spawn，从不 import**）
+*
+* 所有者 2026-09-19：「**B 是设计，A 只是文档友好**」。
+* 若 ACC **import** 那段 TS，会出现两件事：
+*   ① ACC 依赖 CCC 的**源码路径**（npm 装机版在别处 ⇒ 两条路径都要活 = 两个真相源）；
+*   ② **用户程序语法错会让 ACC 启动失败** ⇒ **一个用户程序的错误放倒整个容器**。
+* ⇒ 进程边界把这两件事同时挡掉：**路径只需一个（文件系统），错误被隔离在子进程里**。
+*
+* ## 🔴 铁律：CRO 的任何失败，绝不影响既有机制（设计 §5）
+*
+* `send-later` / `send-now` / 唤醒表的投递**照常工作**。
+* 先例 = `weixin-hook.ts` 的**旁路容忍**（"超时 kill / 非 0 退出 / spawn 失败 → 仅日志返回，绝不抛"）。
+* ⇒ 本模块的**每一个**导出函数**都不抛错**（返回结构化失败）。
+*/
+/** 入口文件名（**全写**，所有者令 2026-09-19；不改缩写） */
+const CRO_FILENAME = "continuous-re-occurrence.ts";
+/** 硬超时（沿用 `biasProvider` 先例的 60s；设计 §5 情形 2） */
+const CRO_TIMEOUT_MS = 6e4;
+/** stdout 上限（防一个坏程序把日志撑爆；沿用 hook 截断思路） */
+const CRO_STDOUT_MAX = 65536;
+/** SESSION.md 文件名（与 `trajectory-ops.ts` 同值；此处本地常量避免反向依赖） */
+const SESSION_MD = "SESSION.md";
+/**
+* 展示码派生（**只用于展示**，不作识别依据 —— §0I U4：锚永远是 `dirName`）。
+*
+* 判据（设计 §1）：**编号不是固定格式，不同 CCC 格式不同**（本容器 `S###`，别处可能是 issue 号
+* 或自定义前缀）⇒ 这里只做**尽力而为的展示性提取**，取不到就返回空串。
+* 🔴 **绝不**因为取不到就拒绝服务——`dirName` 才是硬锚。
+* @param dirName 轨迹目录名
+* @returns `S###` 形态的展示码；取不到 ⇒ `''`
+*/
+function deriveCode(dirName) {
+	const m = /(?:^|--)S(\d{2,})(?:--|$)/.exec(dirName);
+	return m ? `S${m[1]}` : "";
+}
+/** epoch ms → 当地 ISO（不可解析 ⇒ null） */
+function isoOrNull(ms) {
+	return typeof ms === "number" && Number.isFinite(ms) ? isoLocal(ms) : null;
+}
+/**
+* 装配快照（**纯函数**：只做数据整形，不读 fs、不看 ctx）⇒ 可穷举测试。
+* @param input 已读好的原始数据
+* @returns 喂给 CRO 程序的快照
+*/
+function buildCroSnapshot(input) {
+	return {
+		version: 1,
+		identity: {
+			dirName: input.dirName,
+			code: deriveCode(input.dirName),
+			cccRoot: input.cccRoot
+		},
+		time: {
+			now: isoLocal(input.nowMs),
+			nowMs: input.nowMs,
+			nowLocal: new Date(input.nowMs).toString()
+		},
+		body: {
+			sessionMdPath: input.sessionMdPath,
+			sessionMdBytes: input.sessionMdBytes,
+			sessionMdMtime: isoOrNull(input.sessionMdMtimeMs),
+			references: input.references.map((r) => ({
+				name: r.name,
+				bytes: r.bytes,
+				mtime: isoLocal(r.mtimeMs)
+			}))
+		},
+		binding: {
+			boundSessionIds: input.boundSessionIds,
+			liveSessionIds: input.liveSessionIds,
+			runningSessionIds: input.runningSessionIds
+		},
+		scheduling: {
+			pendingWakes: input.pendingWakes,
+			scheduler: input.scheduler
+		}
+	};
+}
+/**
+* 解析 CRO 程序 stdout（**纯函数** ⇒ 可穷举测试）。
+*
+* ## 边界（设计 §4.1）
+* · `wake` 缺省 / `false` ⇒ **不唤起**（**这是常态**）——`prompt` 可省；
+* · `wake: true` 但 `prompt` 空 / 非串 ⇒ 🔴 **非法** ⇒ 返回错误（调用方**跳过本轮**，不投递空消息）；
+* · 非 JSON / 非对象 ⇒ 错误。
+*
+* ## 🔴 为什么 `reason` 重要（CCE：重建 > 保存）
+* 改成程序判定后，**「当时为什么叫了」不再能从时间表重建**（原因在程序肚子里：
+* 可能有随机、可能看了外部数据）⇒ 要求程序自报理由，把「决策依据」重新变成**可重建的**。
+* ⇒ **强烈建议但不强制**（强制会让简单程序难写；设计 §9-6 待裁，本版取"建议"）。
+*
+* @param stdout 程序标准输出（可含前后空白；允许多行 JSON 文本）
+* @returns 决策 或 结构化错误
+*/
+function parseCroOutput(stdout) {
+	const text = stdout.trim();
+	if (text === "") return {
+		ok: false,
+		error: "cro-empty-output",
+		detail: "程序没有输出（期望 stdout 一行 JSON）"
+	};
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		return {
+			ok: false,
+			error: "cro-bad-json",
+			detail: `输出不是合法 JSON: ${String(err?.message ?? err)}`
+		};
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		error: "cro-bad-json",
+		detail: "输出必须是 JSON 对象"
+	};
+	const obj = raw;
+	const wake = obj.wake === true;
+	const reason = typeof obj.reason === "string" && obj.reason.trim() !== "" ? obj.reason.trim() : null;
+	if (!wake) return {
+		ok: true,
+		decision: {
+			wake: false,
+			prompt: null,
+			reason
+		}
+	};
+	if (typeof obj.prompt !== "string" || obj.prompt.trim() === "") return {
+		ok: false,
+		error: "cro-missing-prompt",
+		detail: "wake=true 但 prompt 缺失或为空"
+	};
+	return {
+		ok: true,
+		decision: {
+			wake: true,
+			prompt: obj.prompt.trim(),
+			reason
+		}
+	};
+}
+/**
+* CRO 程序路径：`<CCC 根>/AGENT_SESSIONS/<dirName>/continuous-re-occurrence.ts`。
+*
+* ⚠️ 路径逃逸校验（`resolveInside`）：`dirName` 来自配置/工具入参，
+* 必须确保解析后仍在 CCC 根内（同 `weixin-hook.ts:160` 手法）。**抛错由调用方吞**。
+* @param root CCC 根
+* @param dirName 轨迹目录名
+* @returns 绝对路径
+*/
+function croScriptPath(root, dirName) {
+	return resolveInside(root, join("AGENT_SESSIONS", dirName, CRO_FILENAME));
+}
+/**
+* 列出**启用了 CRO 的轨迹目录名**（供调度器每 tick 扫描，设计 §6.1）。
+*
+* ## 判据与形态（R↓）
+* · 判据 = **文件在不在**（同 §2.1）——**没有注册表**，所以"谁启用了"只能靠**扫目录**：
+*   `AGENT_SESSIONS/` 下每个目录查一次 `<目录>/continuous-re-occurrence.ts`。
+* · **一次 readdir + 每个目录一次 existsSync**：N 条轨迹的代价是 O(N) 次 `stat`，
+*   每 5min 一次 —— 与既有 `listSessions` 同量级，可接受。
+* · 跳过 **`_` 前缀**（`_archived` / `_skiff-logs` / `_weixin-logs` = 系统与日志目录）
+*   与 **`.` 前缀**（隐藏）——它们**不是轨迹**，且扫它们纯属浪费。
+* · 🔴 **本函数绝不抛错**（返回 `[]`）——它跑在调度器 tick 内，任何异常都可能影响既有链路
+*   （设计 §5 铁律）。目录读不到（不存在 / 权限）⇒ `[]` = "没有轨迹启用 CRO"，语义正确。
+*
+* ⚠️ **为什么不做缓存**：缓存会引入"文件删了但缓存还在"的失效模式（本容器栽过的"第二真相源"），
+* 而这里省下的只是一次 `readdir`——**不值当**。
+*
+* @param root CCC 根
+* @returns 启用了 CRO 的轨迹目录名（**排序后**，保证同 tick 顺序稳定、便于日志比对）
+*/
+function listCroTrajectories(root) {
+	const rootDir = sessionsRoot(root);
+	let entries;
+	try {
+		entries = readdirSync(rootDir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const e of entries) {
+		if (!e.isDirectory()) continue;
+		if (e.name.startsWith("_") || e.name.startsWith(".")) continue;
+		try {
+			if (existsSync(join(rootDir, e.name, "continuous-re-occurrence.ts"))) out.push(e.name);
+		} catch {}
+	}
+	return out.sort();
+}
+/**
+* 执行一次 CRO 程序（**永不抛** —— 旁路容忍铁律）。
+*
+* runner 顺序（照 `weixin-hook.ts:171-174` 的 bun 优先 / node 兜底）：
+* `bun` → `process.execPath`（同运行时）。
+* 判据：`ENOENT`（二进制不存在）⇒ 试下一个；**其余失败视为最终结果**
+* （程序自己报错就是报错，不该用另一个 runner 掩盖——与 hook 一致）。
+* @param scriptAbs 程序绝对路径
+* @param stdinJson 喂给程序的快照 JSON
+* @param timeoutMs 硬超时
+* @returns 执行结果（含输出的解析交由 `parseCroOutput`）
+*/
+async function runCroProcess(scriptAbs, stdinJson, timeoutMs = CRO_TIMEOUT_MS) {
+	const runners = [["bun", [scriptAbs]], [process.execPath, [scriptAbs]]];
+	for (const [cmd, args] of runners) {
+		const res = await runCroOnce(cmd, args, stdinJson, timeoutMs);
+		if (!res.ok && res.code === "ENOENT") continue;
+		return res;
+	}
+	return {
+		ok: false,
+		stdout: "",
+		error: "CRO 执行失败（bun 与 node 均不可用）",
+		code: "cro-no-runner"
+	};
+}
+/** 单次 spawn（Promise 化 + 超时 kill + 输出截断 + **绝不抛**） */
+function runCroOnce(cmd, args, stdinJson, timeoutMs) {
+	return new Promise((resolvePromise) => {
+		let settled = false;
+		let stdout = "";
+		let stderr = "";
+		let child = null;
+		try {
+			child = spawn(cmd, args, {
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				],
+				env: { ...process.env }
+			});
+		} catch (err) {
+			return resolvePromise({
+				ok: false,
+				stdout: "",
+				error: String(err),
+				code: "SPAWN_ERR"
+			});
+		}
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			child?.kill("SIGKILL");
+			resolvePromise({
+				ok: false,
+				stdout,
+				error: `CRO 执行超时（>${Math.round(timeoutMs / 1e3)}s，已 kill）`,
+				code: "cro-timeout"
+			});
+		}, timeoutMs);
+		child.stdin?.on("error", () => {});
+		try {
+			child.stdin?.write(stdinJson);
+			child.stdin?.end();
+		} catch {}
+		child.stdout?.on("data", (d) => {
+			stdout = (stdout + d.toString()).slice(0, CRO_STDOUT_MAX);
+		});
+		child.stderr?.on("data", (d) => {
+			stderr = (stderr + d.toString()).slice(0, CRO_STDOUT_MAX);
+		});
+		child.on("error", (err) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolvePromise({
+				ok: false,
+				stdout,
+				error: String(err.message ?? err),
+				code: err.code
+			});
+		});
+		child.on("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			if (code === 0) resolvePromise({
+				ok: true,
+				stdout,
+				error: null
+			});
+			else {
+				const detail = stderr.trim().split("\n")[0] ?? "";
+				resolvePromise({
+					ok: false,
+					stdout,
+					error: `CRO 程序退出码 ${code}${detail ? `：${detail}` : ""}`,
+					code: "cro-exit-nonzero"
+				});
+			}
+		});
+	});
+}
+/** 读目录清单（不存在/读失败 ⇒ 空数组；**不回退抛错**） */
+function readDirEntries(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => {
+			const p = join(dir, e.name);
+			try {
+				const st = statSync(p);
+				return {
+					name: e.name,
+					bytes: st.size,
+					mtimeMs: st.mtimeMs
+				};
+			} catch {
+				return null;
+			}
+		}).filter((x) => x !== null);
+	} catch {
+		return [];
+	}
+}
+/** 读 SESSION.md 体积与 mtime（不存在/读失败 ⇒ null） */
+function readMdStat(mdPath) {
+	try {
+		const st = statSync(mdPath);
+		return {
+			bytes: st.size,
+			mtimeMs: st.mtimeMs
+		};
+	} catch {
+		return {
+			bytes: null,
+			mtimeMs: null
+		};
+	}
+}
+/** 读取快照所需的 fs 侧数据（**纯读取，不抛**） */
+function readCroSnapshotInput(root, dirName, nowMs, extras) {
+	const dir = join(sessionsRoot(root), dirName);
+	const mdPath = join(dir, SESSION_MD);
+	const md = readMdStat(mdPath);
+	return {
+		dirName,
+		cccRoot: root,
+		nowMs,
+		sessionMdPath: mdPath,
+		sessionMdBytes: md.bytes,
+		sessionMdMtimeMs: md.mtimeMs,
+		references: readDirEntries(join(dir, "references")),
+		boundSessionIds: extras.boundSessionIds,
+		liveSessionIds: extras.liveSessionIds,
+		runningSessionIds: extras.runningSessionIds,
+		pendingWakes: extras.pendingWakes,
+		scheduler: extras.scheduler
+	};
+}
+/**
+* 评估一条轨迹的 CRO 程序：**文件在 ⇒ 跑它；不在 ⇒ 未启用**（设计 §2.1）。
+*
+* 🔴 **本函数永不抛错**（旁路容忍铁律）：任何失败都返回 `{status:'skipped'}`，
+* 调用方据此**跳过本轮**、**不影响既有投递链路**。
+*
+* @param root CCC 根
+* @param dirName 轨迹目录名
+* @param snapshotInput 已读好的快照输入
+* @param deps 可注入依赖（测试用）
+* @returns 四态结果
+*/
+async function evaluateCro(root, dirName, snapshotInput, deps = {}) {
+	let scriptAbs;
+	try {
+		scriptAbs = croScriptPath(root, dirName);
+	} catch (err) {
+		return {
+			status: "disabled",
+			detail: `CRO 路径非法（须在 CCC 根内）：${String(err?.message ?? err)}`
+		};
+	}
+	if (!existsSync(scriptAbs)) return {
+		status: "disabled",
+		detail: `未启用（无 ${CRO_FILENAME}）`
+	};
+	const snapshot = buildCroSnapshot(snapshotInput);
+	let stdinJson;
+	try {
+		stdinJson = JSON.stringify(snapshot);
+	} catch (err) {
+		return {
+			status: "skipped",
+			detail: `快照序列化失败：${String(err?.message ?? err)}`,
+			code: "cro-snapshot"
+		};
+	}
+	const run = await (deps.runner ?? runCroProcess)(scriptAbs, stdinJson, deps.timeoutMs ?? 6e4);
+	if (!run.ok) return {
+		status: "skipped",
+		detail: run.error ?? "CRO 执行失败",
+		...run.code ? { code: run.code } : {}
+	};
+	const parsed = parseCroOutput(run.stdout);
+	if (!parsed.ok) return {
+		status: "skipped",
+		detail: parsed.detail ?? parsed.error,
+		code: parsed.error
+	};
+	const decision = parsed.decision;
+	if (!decision.wake) return {
+		status: "no-wake",
+		decision,
+		detail: decision.reason ?? "程序判定：不唤起"
+	};
+	return {
+		status: "wake",
+		decision,
+		prompt: decision.prompt,
+		detail: decision.reason ?? "程序判定：唤起"
+	};
+}
+/** 人读一行（日志用；`evaluateCro` 结果的稳定摘要） */
+function renderCroOutcome(dirName, outcome) {
+	switch (outcome.status) {
+		case "disabled": return `${dirName}: CRO ${outcome.detail}`;
+		case "skipped": return `${dirName}: CRO 跳过本轮（${outcome.detail}）`;
+		case "no-wake": return `${dirName}: CRO 不唤起（${outcome.detail}）`;
+		case "wake": return `${dirName}: CRO 唤起（${outcome.detail}）`;
+	}
+}
+//#endregion
 //#region src/host/effect.ts
 /** 已告警的标签（进程级去重：重复装配/多测试替身不刷屏，但绝不静默） */
 const warnedLabels = /* @__PURE__ */ new Set();
@@ -395,6 +850,319 @@ function registerDisposer(ctx, label, cleanup) {
 	}
 }
 //#endregion
+//#region src/cro-turns.ts
+/** 一次「在跑」记录的 TTL（见文件头的方向性判据） */
+const TURN_TTL_MS = 18e5;
+/**
+* 进程内的「正在跑」表（键 = 载体 dsh 会话 id）。
+*
+* ⚠️ **仅内存**：进程重启即空 —— 这是**可接受的**，因为重启后宿主会重发
+* `session-start`（或至少下一次 `turn-stopping` 会清掉残留），且空表 = "没有在跑"，
+* 落到上面那条**便宜**的误判方向。
+*/
+const runningBySession = /* @__PURE__ */ new Map();
+/** 取载体 id（事件 payload 的 `agent` 面；取不到 ⇒ null） */
+function sessionIdOf(agent) {
+	const id = agent?.session?.id;
+	return typeof id === "string" && id !== "" ? id : null;
+}
+/** 标记「在跑」（`agent/session-start` + `agent/status=running` 调用） */
+function markTurnRunning(sessionId, nowMs, turn = null) {
+	if (!sessionId) return;
+	runningBySession.set(sessionId, {
+		at: nowMs,
+		turn
+	});
+}
+/** 清除「在跑」（`turn-stopping` / disposed 调用） */
+function clearTurnRunning(sessionId) {
+	if (!sessionId) return;
+	runningBySession.delete(sessionId);
+}
+/**
+* 列出**当前在跑**的载体 id（按 TTL 过滤 + **顺手清除过期项**）。
+*
+* 🔴 **本函数带副作用（清理）是刻意的**：它是"异常路径兜底"的唯一执行点——
+* 只过滤不清除会让表留下永不过期的僵尸项（正是"只增不清"病）。
+* @param nowMs 当前时刻
+* @param ttlMs TTL（缺省 {@link TURN_TTL_MS}）
+* @returns 在跑的载体 id 列表（顺序不保证）
+*/
+function listRunningSessionIds(nowMs, ttlMs = TURN_TTL_MS) {
+	const out = [];
+	for (const [id, rec] of runningBySession) {
+		if (nowMs - rec.at > ttlMs) {
+			runningBySession.delete(id);
+			continue;
+		}
+		out.push(id);
+	}
+	return out;
+}
+/**
+* 按轨迹聚合：该轨迹**是否有载体在跑**（`listBoundSessionIds` 给候选，再与在跑集求交）。
+* @param boundSessionIds 绑定该轨迹的载体 id
+* @param nowMs 当前时刻
+* @param ttlMs TTL
+* @returns 在跑的载体 id（**可能多条**；空数组 = 没有在跑）
+*/
+function runningCarriersOf(boundSessionIds, nowMs, ttlMs = TURN_TTL_MS) {
+	const running = new Set(listRunningSessionIds(nowMs, ttlMs));
+	return boundSessionIds.filter((id) => running.has(id));
+}
+/**
+* 装配追踪（`index.ts` apply 调用）：订阅四个既有事件 + 拆卸。
+*
+* **为什么订阅四个而不是两个**（R↓）：
+* · 前两个（`session-start` / `turn-stopping`）负责**语义**——"在不在跑"；
+* · 后两个（`agent/disposed` / `session/disposed`）负责**生命周期**——
+*   载体没了必须清项，否则表按载体只增（本模块的头号风险）。
+*
+* ⚠️ **失败不抛**：任一事件通道缺失 ⇒ 响亮日志 + 该订阅跳过（**apply 不可成为启动单点**，
+* 与 `registerDeepseekVisionPatch` 等既有装配同款纪律）。
+* @param ctx 插件上下文
+*/
+function registerCroTurnTracking(ctx) {
+	const on = (event, handler) => {
+		try {
+			ctx.on(event, handler);
+		} catch (err) {
+			console.log(`[serenity-hooks] ✗ CRO turn 追踪未装配（${event} 不可用）: ${String(err?.message ?? err)}`);
+		}
+	};
+	on("agent/session-start", (payload) => {
+		const id = sessionIdOf(payload?.agent);
+		if (id) markTurnRunning(id, Date.now());
+	});
+	on("agent/status", (payload) => {
+		const p = payload;
+		const id = sessionIdOf(p?.agent);
+		if (!id) return;
+		const turn = typeof p.turn === "number" ? p.turn : null;
+		if (p.status === "running") markTurnRunning(id, Date.now(), turn);
+		else if (p.status === "idle") clearTurnRunning(id);
+	});
+	on("agent/turn-stopping", (payload) => {
+		const id = sessionIdOf(payload?.agent);
+		if (id) clearTurnRunning(id);
+	});
+	on("agent/disposed", (payload) => {
+		const id = sessionIdOf(payload?.agent);
+		if (id) clearTurnRunning(id);
+	});
+	on("session/disposed", (payload) => {
+		const id = payload?.id;
+		if (typeof id === "string" && id !== "") clearTurnRunning(id);
+	});
+	registerDisposer(ctx, "cro turn tracking", () => {
+		runningBySession.clear();
+	});
+}
+//#endregion
+//#region src/cro-log.ts
+/**
+* cro-log.ts — CRO 唤起日志（**ACC 侧**，每轨迹一份固定名文件，2026-09-20 S142 §7.16）
+*
+* ## 所有者令（本模块的存在理由）
+*
+* 「S151 和 S185 的验证都说明，trajectory 倾向于自己做个结构化记录来记录自身 CRO 的执行情况，
+* 这是个结构化流水账；**我们 ACC 有必要进行 CRO 唤醒的日志记录**，当 CRO 存在时，每次**成功唤醒**
+* 写相关信息，但是保留数量要少，**只保留仅两日**的记录即可，**这个时间是程序化的**」
+* ＋「**这个日志写结构化文件到 trajectory 目录，文件名固定即可**」
+* ＋「**失败成功都记录**」。
+*
+* ## 它解决什么麻烦（白话）
+*
+* 在此之前「ACC 到底叫过谁、叫了几次、哪次**没叫成**」**ACC 自己一个字都不留** ——
+* 要查只能去读**被叫的那个程序**写的记录；程序没写 / 写坏 / 被换掉 ⇒ **这段历史就是空白**。
+* ⇒ 本模块让 ACC **自己那一侧**留一份只记两天的流水，使「唤起历史」**不再依赖被观测者是否老实**。
+*
+* ## 🔴 为什么**不是**第二真相源（本容器铁律，勿删此论证）
+*
+* 轨迹目录里因此**并排两个文件、主语各一**：
+*
+* | 文件 | 谁写 | 主语 | 回答 |
+* |---|---|---|---|
+* | `<轨迹目录>/cro-state.json`（CCC 侧程序自建，名字自定） | **CCC 的 CRO 程序** | 程序 | 「**我判了什么**」（含"没叫"的判定、心跳阈值、环境谓词） |
+* | `<轨迹目录>/cro-wake-log.json`（**本模块**） | **ACC** | ACC | 「**我把什么送出去了、送成没有**」 |
+*
+* **内容不重叠**：本模块**不复制**判定细节（不存 `lastDecision` / 阈值 / 谓词）；
+* 而程序**不可能**知道投递结果（CRO 投递是 fire-and-forget）。
+* ⇒ 两者**互补**：完整审计 = 两者合看（本模块 = 投递面｜程序状态 = 判定面）。
+*
+* ## 🔴 轮转（所有者明示「程序化的」）
+*
+* **写入时按窗裁剪**：每次落盘只保留 `at >= now - CRO_LOG_RETENTION_MS` 的条目，
+* 随后**原子写**（`tmp + rename`，与 `wake-registry.ts` 同款形态）。
+* ⇒ 清理与写入**是同一笔操作** ⇒ **结构上不存在"忘了清"的可能**（比"另设一个每 tick 的清理步"更硬：
+* 那多一个"可能忘了跑"的面）。窗宽是**常量**，**无配置键、无人工清理动作**。
+*
+* ## 🔴 铁律（与 `cro.ts` 同族）
+*
+* **本模块的每个导出函数都不抛错**：写盘 / 裁剪 / 解析失败一律返回结构化失败，
+* 由调用方只记一行 tick 日志 ⇒ **CRO 流水的问题绝不影响投递与既有链路**（设计 §5）。
+*
+* ## 保留量级（实测，非估计）
+*
+* 实测最高 = S185 的 40min 心跳（≈36 条/天）；两天窗 ⇒ **≤ ~80 条、< 20 KB**。
+* 最坏（某程序每 5min 都叫）⇒ 288 条/天 ⇒ 两天 **≤ ~600 条、< 100 KB** —— 轮转**自带上限**。
+*/
+/** 固定文件名（所有者令：「文件名固定即可」）——与程序自建的 `cro-state.json` 并排、主语分明 */
+const CRO_LOG_FILENAME = "cro-wake-log.json";
+/** 保留窗 = 2 日（所有者令「只保留仅两日」）；**常量** ⇒ 「这个时间是程序化的」 */
+const CRO_LOG_RETENTION_MS = 1728e5;
+const CRO_LOG_VERSION = 1;
+/** 日志绝对路径 */
+function croWakeLogPath(root, dirName) {
+	return join(sessionsRoot(root), dirName, CRO_LOG_FILENAME);
+}
+function emptyLog() {
+	return {
+		version: CRO_LOG_VERSION,
+		entries: []
+	};
+}
+/** 条目形状校验（容忍手改：字段缺失/类型不符 → 丢弃该条，不阻断整档） */
+function asEntry(value) {
+	const e = value;
+	if (!e || typeof e !== "object") return null;
+	if (typeof e.at !== "string" || e.at === "") return null;
+	if (typeof e.ok !== "boolean") return null;
+	if (typeof e.detail !== "string") return null;
+	const digest = e.promptDigest ?? {};
+	return {
+		at: e.at,
+		ok: e.ok,
+		detail: e.detail,
+		tick: typeof e.tick === "number" ? e.tick : 0,
+		reason: typeof e.reason === "string" ? e.reason : null,
+		promptDigest: {
+			length: typeof digest.length === "number" ? digest.length : 0,
+			head: typeof digest.head === "string" ? digest.head : ""
+		}
+	};
+}
+/** 提示词摘要（长度 + 前 N 字；超长不截断标记——长度字段本身就是信号） */
+function summarizeCroPrompt(prompt) {
+	const text = typeof prompt === "string" ? prompt : "";
+	return {
+		length: [...text].length,
+		head: [...text].slice(0, 80).join("")
+	};
+}
+/**
+* 读取日志（**永不抛**；读坏 ⇒ 当作空档 + 返回 error 文本）。
+* @param root CCC 根
+* @param dirName 轨迹目录名
+*/
+function loadCroWakeLog(root, dirName) {
+	const path = croWakeLogPath(root, dirName);
+	if (!existsSync(path)) return {
+		log: emptyLog(),
+		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 {
+			log: {
+				version: CRO_LOG_VERSION,
+				entries
+			},
+			error: null
+		};
+	} catch (err) {
+		return {
+			log: emptyLog(),
+			error: `CRO 流水解析失败（${String(err?.message ?? err)}）`
+		};
+	}
+}
+/**
+* 按窗裁剪（**纯函数** ⇒ 可穷举测试）。
+*
+* 判据：`Date.parse(at) >= nowMs - windowMs` 保留；反之丢弃。
+* 🔴 **`at` 不可解析者一律丢弃**（本模块只写 `isoLocal()` 产物 ⇒ 不可解析 = 被手改或损坏），
+* **并在返回值里报数**（`dropped`）——**不静默吞掉**（本容器反复栽的"安静失败"纪律）。
+*/
+function pruneCroLogEntries(entries, nowMs, windowMs = CRO_LOG_RETENTION_MS) {
+	const floor = nowMs - windowMs;
+	const kept = [];
+	let pruned = 0;
+	let dropped = 0;
+	for (const e of entries) {
+		const t = Date.parse(e.at);
+		if (Number.isNaN(t)) {
+			dropped += 1;
+			continue;
+		}
+		if (t >= floor) kept.push(e);
+		else pruned += 1;
+	}
+	return {
+		kept,
+		pruned,
+		dropped
+	};
+}
+/**
+* 追加一条唤起记录并按窗裁剪（**本模块主入口；永不抛**）。
+*
+* 顺序 = 读 → 追加 → 裁剪 → **原子写**。任一步失败 ⇒ `{ok:false, error}`，
+* **不抛**（调用方只记一行 tick 日志；**绝不影响投递**）。
+*
+* 无 CRO 的轨迹**不会**因本函数产生文件：只有真的发生过一次唤起尝试才会建/写该档
+* （所有者令「**当 CRO 存在时**」）。
+*
+* @param root CCC 根
+* @param dirName 轨迹目录名
+* @param input 本次唤起尝试（成败都记）
+* @param nowMs 当前毫秒（可注入 ⇒ 便于测裁剪边界）
+* @returns 写入结果与裁剪计数
+*/
+function appendCroWakeLog(root, dirName, input, nowMs = Date.now()) {
+	const path = croWakeLogPath(root, dirName);
+	try {
+		const loaded = loadCroWakeLog(root, dirName);
+		const entry = {
+			at: isoLocal(nowMs),
+			ok: input.ok,
+			detail: input.detail,
+			tick: input.tick,
+			reason: input.reason,
+			promptDigest: summarizeCroPrompt(input.prompt)
+		};
+		const { kept, pruned, dropped } = pruneCroLogEntries([...loaded.log.entries, entry], nowMs);
+		mkdirSync(dirname(path), { recursive: true });
+		const tmp = `${path}.tmp`;
+		writeFileSync(tmp, `${JSON.stringify({
+			version: CRO_LOG_VERSION,
+			entries: kept
+		}, null, 2)}\n`, "utf-8");
+		renameSync(tmp, path);
+		return {
+			ok: true,
+			error: null,
+			kept: kept.length,
+			pruned,
+			dropped
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			error: `CRO 流水写入失败（${String(err?.message ?? err)}）`,
+			kept: 0,
+			pruned: 0,
+			dropped: 0
+		};
+	}
+}
+//#endregion
 //#region src/clock-runtime.ts
 /**
 * clock-runtime.ts — **时钟运行时工厂**（S142 §38 复审候选 C6b，路径 **P2**）
@@ -893,6 +1661,163 @@ async function sendToTrajectory(ctx, root, target, message, sender) {
 async function collectWakeCccs(ctx) {
 	return (await listCccs(ctx)).map((e) => e.root);
 }
+/**
+* CRO 唤起消息正文（**刻意不复用** {@link buildWakeText} / {@link buildSendText}）。
+*
+* 三种唤起各有自己的**事实**；混用 = 注入一条假陈述（本容器栽过：`buildSendText` 里
+* 那句"消息已入队"就是一条假陈述，见该函数注释）：
+* · `buildWakeText` —— 「**到点**了」（登记过的未来时刻，人/agent 算好的）
+* · `buildSendText` —— 「**有人此刻给我发了一条消息**」
+* · 本函数         —— 「**我自己的程序**看情况判定该叫我了」（**没有到点、也没有人发消息**）
+*
+* 🔴 `reason` 的呈现（设计 §4.2）：**程序没写就明说没写**，不留空白 ——
+* 改成程序判定后，"当时为什么叫了"**不再能从时间表重建**（原因在程序肚子里）；
+* 留空白 = 连"丢在哪一环"都看不出来。写明"未提供"至少把缺口标出来了（CCE：重建 > 保存）。
+* @param dirName 目标轨迹目录名
+* @param mdPath 目标 SESSION.md 绝对路径
+* @param prompt 程序给的唤起提示词
+* @param reason 程序给的判定理由（可为 null）
+* @returns 投递正文
+*/
+function buildCroWakeText(dirName, mdPath, prompt, reason) {
+	return [
+		`[CRO 唤起] ${dirName} 自带的 continuous-re-occurrence.ts 判定：现在该唤起。`,
+		`当前时间：${localHuman()}（当地时区）。`,
+		"",
+		`身份锚定：继续 ${dirName} 的 trajectory（SESSION.md: ${mdPath}）。`,
+		"",
+		`判定理由：${reason ?? "（程序未提供 reason —— 见 CRO 编写指南 §7 坑 3）"}`,
+		"",
+		"唤起提示词：",
+		prompt,
+		"",
+		"说明：这是由**本轨迹自己的 CRO 程序**按当时情况做的判定（**不是**定时唤醒，**也不是**别人发的消息）。处理完照常把进展写入 SESSION.md。"
+	].join("\n");
+}
+/**
+* 投递一条 CRO 唤起（**fire-and-forget**，与 {@link deliverWake} 同层）。
+*
+* · **取用通路复用** {@link acquireWakeAgent}（live 优先 → 冷载入）：这是调度器侧唯一的
+*   "怎么把一句话送到一条轨迹"的知识 ⇒ 不另立第二条（设计 §9-2 的倾向：复用投递面）。
+* · 🔴 **不落唤醒表**（设计 §6.3）：CRO 是"**持续判定**"，不是"**某个未来时刻**"。
+*   落表会给 §0Q（投递即删、表只保在办）**增加一个新的写入源**。
+* · 用 `followup`（不用 `steer`）：CRO 由**调度器**发起，与 `send-later` 同层；
+*   `steer`（当场注入当前轮）是 `send-now` 的语义 —— 那是人类/agent 的**即时动作**。
+* · 🔴 **失败不回滚、不重试**（与条目投递不同）：下一 tick 会**重新判定**——
+*   CRO 的判据是"情况"，不是"这条消息还没送出去" ⇒ 自愈来自**重判**，不来自重投。
+* @param ctx 插件上下文
+* @param root CCC 根
+* @param dirName 目标轨迹目录名（= CRO 只能唤起**自己**，设计 §9-8 的倾向）
+* @param prompt 唤起提示词
+* @param reason 判定理由
+* @returns 投递结果（进 tick 日志；**不写注册表**）
+*/
+async function deliverCroWake(ctx, root, dirName, prompt, reason) {
+	const mdPath = join(sessionsRoot(root), dirName, "SESSION.md");
+	const acquired = await acquireWakeAgent(ctx, root, dirName);
+	if ("error" in acquired) return {
+		ok: false,
+		detail: acquired.error,
+		notReady: acquired.notReady === true
+	};
+	try {
+		acquired.agent.followup(createUserMessage({
+			content: [{
+				type: "text",
+				text: buildCroWakeText(dirName, mdPath, prompt, reason)
+			}],
+			source: PLUGIN_SOURCE
+		}));
+	} catch (err) {
+		return {
+			ok: false,
+			detail: `CRO 投递失败（${acquired.how}）: ${String(err?.message ?? err)}`
+		};
+	}
+	return {
+		ok: true,
+		detail: `已投递（${acquired.how}）`
+	};
+}
+/**
+* CRO 阶段：本 tick 对**每条启用了 CRO 的轨迹**跑一次它自带的程序，按判定投递。
+*
+* ## 为什么放在既有投递**之后**（R↓）
+* · 既有条目（`send-later`）**有到点承诺** ⇒ 优先级天然更高；
+* · CRO 是"看着情况叫"，**晚一拍无成本**（tick 粒度本就是 5min）；
+* · ⇒ 铁律（设计 §5）：**CRO 的任何失败都不影响既有链路** —— 整段由调用方兜住，
+*   且**每条轨迹各自 try/catch**（一条坏程序不得连累同 tick 的其它轨迹）。
+*
+* ## 日志口径（刻意与既有投递不同）
+* "每 tick × 每条轨迹"都写一行 ⇒ 对"**常态是不唤起**"的 CRO 就是刷屏。
+* ⇒ 逐条只记 **唤起**（`reason` 进日志 —— 设计 §4.2 要求可重建）与 **跳过**（异常，必须看见）；
+*   **不唤起只进汇总行**（`唤起 x，不唤起 y，跳过 z`）。
+* ⚠️ **诚实标注**：因此"某条轨迹当轮**为何没叫**"**不进 tick 日志**（它在程序肚子里）。
+*    要完整的逐次判定审计，须**程序自己**写状态文件（设计 §3.3）——ACC 给不了。
+* @param ctx 插件上下文
+* @param root CCC 根
+* @param registry 本 tick 已载入的唤醒注册表条目（供快照的 `pendingWakes`；读坏时传 `[]`）
+* @param log 本 tick 的人读摘要（就地追加）
+*/
+async function runCroPhase(ctx, root, registry, log) {
+	let dirs;
+	try {
+		dirs = listCroTrajectories(root);
+	} catch {
+		return;
+	}
+	if (dirs.length === 0) return;
+	const nowMs = Date.now();
+	const s = wakeSchedulerState();
+	const scheduler = {
+		armed: s.armed,
+		enabled: s.enabled,
+		ticks: s.ticks,
+		lastSkipReason: s.lastSkipReason
+	};
+	const agents = hostAgents(ctx);
+	let wakes = 0;
+	let quiet = 0;
+	let skips = 0;
+	for (const dirName of dirs) try {
+		const bound = listBoundSessionIds(root, dirName);
+		const running = runningCarriersOf(bound, nowMs);
+		const outcome = await evaluateCro(root, dirName, readCroSnapshotInput(root, dirName, nowMs, {
+			boundSessionIds: bound,
+			liveSessionIds: bound.filter((id) => Boolean(agents?.get?.(id))),
+			runningSessionIds: running,
+			pendingWakes: registry.filter((e) => e.state === "pending" && resolveWakeTarget(root, e.target)?.dirName === dirName).map((e) => ({
+				id: e.id,
+				at: e.at,
+				createdAt: e.createdAt,
+				createdBy: e.createdBy
+			})),
+			scheduler
+		}));
+		if (outcome.status === "wake") {
+			wakes += 1;
+			const res = await deliverCroWake(ctx, root, dirName, outcome.prompt, outcome.decision.reason);
+			log.push(`· ${root}: ${renderCroOutcome(dirName, outcome)} → ${res.ok ? "已投递" : `投递未成功：${res.detail}`}`);
+			if (!res.notReady) {
+				const rec = appendCroWakeLog(root, dirName, {
+					ok: res.ok,
+					detail: res.detail,
+					tick: s.ticks,
+					reason: outcome.decision.reason ?? null,
+					prompt: outcome.prompt
+				}, nowMs);
+				if (!rec.ok) log.push(`· ${root}: ${dirName}: CRO 流水写入失败（已忽略，不影响投递）: ${rec.error}`);
+			}
+		} else if (outcome.status === "skipped") {
+			skips += 1;
+			log.push(`· ${root}: ${renderCroOutcome(dirName, outcome)}`);
+		} else if (outcome.status === "no-wake") quiet += 1;
+	} catch (err) {
+		skips += 1;
+		log.push(`· ${root}: ${dirName}: CRO 内部异常（已忽略，不影响既有链路）: ${String(err?.message ?? err)}`);
+	}
+	log.push(`· ${root}: CRO 评估 ${dirs.length} 条（唤起 ${wakes}，不唤起 ${quiet}，跳过 ${skips}）`);
+}
 /** 一次调度 tick：遍历已知 CCC → 到期项串行投递 / 超窗项置 missed；返回人读摘要 */
 async function runWakeTick(ctx) {
 	const log = [];
@@ -908,6 +1833,7 @@ async function runWakeTick(ctx) {
 		const { registry, error } = loadWakeRegistry(root);
 		if (error) {
 			log.push(`✗ ${root}: ${error}`);
+			await runCroPhase(ctx, root, [], log);
 			continue;
 		}
 		const { due, expired } = splitDueWakes(registry, Date.now(), WAKE_CATCH_UP_MS);
@@ -933,6 +1859,7 @@ async function runWakeTick(ctx) {
 				log.push(`· ${root}: ${e.id} → 重试（${res.detail}）`);
 			}
 		}
+		await runCroPhase(ctx, root, registry.entries, log);
 	}
 	return log;
 }
@@ -947,4 +1874,4 @@ function registerWakeScheduler(ctx) {
 	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 };
+export { registerDisposer as a, addWake as c, registerCroTurnTracking as i, listWakes as l, sendToTrajectory as n, buildCroSnapshot as o, wakeSchedulerState as r, WAKE_CATCH_UP_MS as s, registerWakeScheduler as t };