@shgroup/dsh-serenity-hooks 1.41.0 → 1.43.0

package/lib/{wake-scheduler-BRnPUnER.js → wake-scheduler-DC4-imVO.js}

@@ -1,9 +1,11 @@
 import { r as hostService, t as hostAgents } from "./access-fiehjxV6.js";
+import { h as resolveInside } from "./ccc-NlLr_sxy.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 { D as localHuman, O as localIdStamp, T as isoLocal, b as sessionsRoot, n as listBoundSessionIds, p as findSession } from "./trajectory-bound-kxvMuCui.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
 /**
@@ -230,7 +232,109 @@ function splitDueWakes(registry, nowMs, catchUpMs = WAKE_CATCH_UP_MS) {
 	};
 }
 /**
+* 🔴 结案并**移除**一条（owner 2026-09-19 裁定「**直接删**」，S142 §0Q 甲案）。
+*
+* ## 为什么删（R↓）
+*
+* 本模块原本是「`pending` → 终态」但**终态条目永不移除** ⇒ 文件**只增**（实测 308 KB / 143+ 条）。
+* owner 明令「应当**唤醒后就清理**的」⇒ 终态即删。
+*
+* **审计不丢**：由 **SESSION.md 与工具输出**承担——这正是本文件 `removeWake` 的既有注释承诺
+* （*"审计由 SESSION.md 与工具输出承担——注册表只保留在办项"*）。
+* ⚠️ 此前该承诺**并未兑现**（`updateWake` 只改 state 从不删行）⇒ 本次是**把承诺做实**。
+*
+* ## 与 `updateWake` 的分工（**别混用**）
+*
+* - `updateWake`：**仍在办**的推进（失败重试 `state:'pending'` + `attempts+1`）⇒ **保留行**；
+* - `finalizeWake`：**不再办**的归宿（投递成功 / 超窗 missed）⇒ 写终态后**同一笔事务里删掉**。
+*
+* 🔴 **为什么两个动作要同一次写盘**：若先 `updateWake(delivered)` 再 `removeWake`，
+* 中间被打断会留下一条"已终结但没删"的条目 ⇒ 又回到只增。
+* 故本函数**读一次、改一次、删一次、写一次**（单次原子落盘）。
+*
+* @param root CCC 根
+* @param id 条目 id
+* @param terminal 终态（`delivered` / `missed` / `cancelled`）——写入仅用于**日志文案**，
+*                 随即整行移除；保留该参数是为了让调用点语义自明（"它归到哪一档了"）。
+* @param result 人读结果（进日志，不进表）
+* @returns `removed` = 被移除的条目（供调用方打印"它是什么"）；不存在 → 稳定错误码
+*/
+function finalizeWake(root, id, terminal, result) {
+	const { registry, error } = loadWakeRegistry(root);
+	if (error) return {
+		ok: false,
+		error,
+		removed: null
+	};
+	const idx = registry.entries.findIndex((e) => e.id === id);
+	if (idx < 0) return {
+		ok: false,
+		error: `wake_not_found: ${id}`,
+		removed: null
+	};
+	const [removed] = registry.entries.splice(idx, 1);
+	const saved = saveWakeRegistry(root, registry);
+	if (!saved.ok) return {
+		ok: false,
+		error: saved.error,
+		removed: null
+	};
+	return {
+		ok: true,
+		error: null,
+		removed: {
+			...removed,
+			state: terminal,
+			lastResult: result
+		}
+	};
+}
+/**
+* 一次性清除**存量终态条目**（`delivered` / `missed` / `cancelled`）。
+*
+* ## 为什么需要（不是可选）
+*
+* 本函数上线前，表里已积压 143+ 条终态记录（308 KB）⇒ **只改行为不改存量 = 文件不再涨但仍很大**。
+* 故首次运行须清一次。**幂等**（无终态条目时空转，不写盘）。
+*
+* 审计不丢：与 `finalizeWake` 同理（终态本就属性"已结案"，其史由 SESSION.md 承担）。
+* @param root CCC 根
+* @returns 清掉几条（0 = 本来就没有）
+*/
+function purgeFinalizedWakes(root) {
+	const { registry, error } = loadWakeRegistry(root);
+	if (error) return {
+		ok: false,
+		error,
+		purged: 0
+	};
+	const kept = registry.entries.filter((e) => e.state === "pending");
+	const purged = registry.entries.length - kept.length;
+	if (purged === 0) return {
+		ok: true,
+		error: null,
+		purged: 0
+	};
+	const saved = saveWakeRegistry(root, {
+		...registry,
+		entries: kept
+	});
+	if (!saved.ok) return {
+		ok: false,
+		error: saved.error,
+		purged: 0
+	};
+	return {
+		ok: true,
+		error: null,
+		purged
+	};
+}
+/**
 * 更新一条（状态推进；调用方给最终状态与结果文案）。
+*
+* ⚠️ **只用于"仍在办"的推进**（主要是失败重试）。**终态请用 `finalizeWake`**——
+* 否则该行会永远留下（这正是本表过去只增的根因，见 `finalizeWake` 注释）。
 * @param root CCC 根
 * @param id 条目 id
 * @param patch 要写入的字段
@@ -259,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();
@@ -293,6 +850,115 @@ 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/clock-runtime.ts
 /**
 * clock-runtime.ts — **时钟运行时工厂**（S142 §38 复审候选 C6b，路径 **P2**）
@@ -791,6 +1457,153 @@ 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}`}`);
+		} 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 = [];
@@ -801,18 +1614,18 @@ async function runWakeTick(ctx) {
 	}
 	clock.noteSkipReason(null);
 	for (const root of roots) {
+		const purged = purgeFinalizedWakes(root);
+		if (purged.ok && purged.purged > 0) log.push(`· ${root}: 清除 ${purged.purged} 条已结案记录（存量首清）`);
 		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);
 		for (const e of expired) {
-			updateWake(root, e.id, {
-				state: "missed",
-				lastResult: `超过补跑窗口（${WAKE_CATCH_UP_MS / 36e5}h）未投递`
-			});
-			log.push(`· ${root}: ${e.id} → missed（超补跑窗口）`);
+			finalizeWake(root, e.id, "missed", `超过补跑窗口（${WAKE_CATCH_UP_MS / 36e5}h）未投递`);
+			log.push(`· ${root}: ${e.id} → missed（超补跑窗口，已清除）`);
 		}
 		for (const e of due) {
 			const res = await deliverWake(ctx, root, e);
@@ -820,14 +1633,19 @@ async function runWakeTick(ctx) {
 				log.push(`· ${root}: ${e.id} → 跳过（宿主服务未就绪，下个 tick 再试；不计失败）`);
 				continue;
 			}
-			updateWake(root, e.id, {
-				state: res.ok ? "delivered" : "pending",
-				attempts: e.attempts + 1,
-				lastResult: res.detail,
-				deliveredAt: res.ok ? isoLocal() : null
-			});
-			log.push(`· ${root}: ${e.id} → ${res.ok ? "delivered" : `重试（${res.detail}）`}`);
+			if (res.ok) {
+				finalizeWake(root, e.id, "delivered", res.detail);
+				log.push(`· ${root}: ${e.id} → delivered（已清除）`);
+			} else {
+				updateWake(root, e.id, {
+					state: "pending",
+					attempts: e.attempts + 1,
+					lastResult: res.detail
+				});
+				log.push(`· ${root}: ${e.id} → 重试（${res.detail}）`);
+			}
 		}
+		await runCroPhase(ctx, root, registry.entries, log);
 	}
 	return log;
 }
@@ -842,4 +1660,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 };