@shgroup/dsh-serenity-hooks 1.76.0 → 1.77.1

package/lib/message-source-CYa8LbbM.js

@@ -0,0 +1,488 @@
+import { r as cccRootForCwd } from "./ccc-roots-rwgzt_0F.js";
+import { A as sessionsRoot, T as parseTrajectoryCode, b as getLastActiveSessionInfo, k as sessionEvents, y as getActiveSessionInfo } from "./profile-DplLGGqo.js";
+import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+//#region src/trajectory/bind-file.ts
+/**
+* trajectory/bind-file.ts — **当前载体绑定 = 认知轨迹目录里的自我交代**（判决 D172，owner 2026-10-20）
+*
+* ## owner 的原话（这是本模块的全部设计依据）
+*
+* > 「**认知轨迹自己交代永远是最好的交代**」
+* > 「绑定表是没有意义的，绑定关系必须**运行时按照规则探测**，绑定表本质就搞成**第二真相源**了」
+* > 「依赖文件系统，定义一个 `.dsh_session_bind` 后缀（加入 gitignore）；每个认知轨迹目录内放一个
+* >  `current.dsh_session_bind`，**以这个为绑定真相源**」
+*
+* ## 为什么这是对的（而不是又一张表）
+*
+* 旧的 `.bindings.json` ＋ 宿主存储域是**旁路索引**：它描述的对象（轨迹目录）与它自己**分离**，
+* ⇒ 一旦两者不一致就必须写代码去对账，而**对账失败没有任何机械信号**（本轨反复踩的形状）。
+*
+* 新形态把这条信息**放回它描述的对象的内部**：
+*
+* ```text
+* <轨迹目录>/
+*   SESSION.md                 ← 身体
+*   PROMPT.md                  ← 章程
+*   trajectory.json            ← 声明（约束面 / uid / cro.host）
+*   current.dsh_session_bind   ← 🆕 **此刻谁在承载它**（单个文件 ⇒ 结构上不可能有两个）
+* ```
+*
+* ## 🔴 两条不变量由**形态本身**保证，不靠记账
+*
+* | 不变量 | 保证方式 |
+* |---|---|
+* | 一条轨迹**至多一个**当前载体 | 它是**一个文件**，写入即整体覆盖（原子 rename） |
+* | 一个载体**至多一条**轨迹 | 写入前扫全部轨迹的 bind 文件，**该会话 id 已出现在别处 ⇒ 拒绝** |
+*
+* ⚠️ 旧形态靠 `supersededAt` 标记"退掉"，而**标记是可以忘的**；覆盖不会忘。
+*
+* ## 零依赖纪律（同 `policy/files.ts`）
+* 只用 `node:fs` / `node:path` ⇒ 谁 import 它都不会成环。每个读函数**永不抛**。
+*
+* ## 🔴 第三条不变量（owner 2026-10-20 追加）：「文件里写的 sessionId 可能已经不存在了
+* ——这个情况下就**视同没绑定**，就正确了」
+*
+* 这一条让整个设计**自洽**：**绑定的有效性由「那个会话真实存在」决定，不由「文件存在」决定。**
+*
+* ```text
+* 文件在 ＋ 会话在  ⇒ 有效绑定
+* 文件在 ＋ 会话没了 ⇒ **视同没绑定**（过期文件自动失效，不需要任何人来清理）
+* 文件不在         ⇒ 没绑定
+* ```
+*
+* ⇒ 因此**不需要**任何"清理陈旧绑定"的机制，也不需要 `reconcile` 去对账 —— 对账这件事本身消失。
+* 代价是**每次取用都要验一次会话是否还在**（`ctx.agents.get` 或 `sessionController.resolveAgent`
+* 或宿主会话清单），**这是运行时探测**，正是 owner 要的那种判据。
+*
+* ⚠️ 本模块**只负责读写文件**；"会话是否还在"必须由**调用方**（持有宿主上下文）来验 ——
+* 把那条判断放在这里会迫使本模块拿到 `ctx`，从而破坏零依赖与可单测性。
+* 调用方正确用法见 {@link isBindUsable}。
+*
+* ## 🔴 第四条：**完整生命周期**（owner 2026-10-20 追加：「调用 use 会覆盖掉这个文件，
+* 完整生命周期要实现，请注意」）
+*
+* 文件是**一个槽位**，不是追加日志。⇒ 每次改变归属都是一次**状态迁移**，
+* 四个动作必须**成对**出现，否则槽位会留下无法解释的残留：
+*
+* | 迁移 | 何时 | 必须做什么 |
+* |---|---|---|
+* | **acquire** | 会话首次认领轨迹 | 写槽位（该会话此前不持有任何轨迹） |
+* | **switch** | 会话从轨迹 A **改到** B | 🔴 **先清 A 的槽位，再写 B** —— 只写 B 会让 A 永远指着一个不再属于它的会话 |
+* | **release** | 会话主动解绑 / 会话将死 | **清掉槽位**（不是写空串，是删文件） |
+* | **takeover** | 载体换代（rebuild / 崩溃后重建） | 覆盖写：旧会话退位，新会话入位（**必须显式声明**） |
+*
+* 🔴 **最容易漏的是 switch 的"先清 A"**：旧实现（`.bindings.json`）天然支持"一个会话多条记录"，
+* 所以从来没暴露过这个问题；新形态是**单槽位**，不清 A 就会得到
+* 「A 与 B 都说这个会话属于自己」—— 正是 owner 要禁的"一个会话绑两条轨迹"，
+* 只不过这次是**残留**而不是**主动绑定**，更难发现。
+*
+* ⇒ 因此**不要**直接调 {@link writeBindDeclaration} 来改归属；一律走
+* {@link transitionBinding}（它把四条迁移的配对关系写死在一处）。
+*/
+/** 绑定文件的固定名（**owner 指定**：`current.dsh_session_bind`） */
+const BIND_FILENAME = "current.dsh_session_bind";
+/**
+* 绑定文件的**族**（认族不认名，D167 通用纪律）。
+*
+* 目前只有一代。留成数组是**为了下一次改名不重演历史**：本仓已在
+* `skiff.json → trajectory-constraint.json → trajectory.json` 上栽过两次
+* （上游改名、下游写死旧名 ⇒ 症状与真因在读数上完全不像）。
+*/
+const BIND_FILENAME_FAMILY = [BIND_FILENAME];
+/** 校验一条声明（容忍手改 / 部分字段缺失） */
+function asDeclaration(value) {
+	const d = value;
+	if (!d || typeof d !== "object") return null;
+	if (typeof d.sessionId !== "string" || d.sessionId === "") return null;
+	return {
+		sessionId: d.sessionId,
+		at: typeof d.at === "number" ? d.at : 0,
+		action: typeof d.action === "string" && d.action !== "" ? d.action : "activate",
+		...typeof d.note === "string" && d.note !== "" ? { note: d.note } : {},
+		...d.createdAsUser === true ? { createdAsUser: true } : {}
+	};
+}
+/** 某轨迹目录里绑定文件的绝对路径 */
+function bindFilePath(trajectoryDir) {
+	return join(trajectoryDir, BIND_FILENAME);
+}
+/**
+* 读一条轨迹的**当前载体声明**。
+*
+* @param trajectoryDir 轨迹目录绝对路径
+* @returns 声明；文件不存在 / 坏 JSON / 形状不符 ⇒ `null`（**永不抛**）
+*/
+function readBindDeclaration(trajectoryDir) {
+	for (const name of BIND_FILENAME_FAMILY) {
+		const p = join(trajectoryDir, name);
+		try {
+			if (!existsSync(p)) continue;
+			return asDeclaration(JSON.parse(readFileSync(p, "utf-8")));
+		} catch {}
+	}
+	return null;
+}
+/**
+* 写一条轨迹的**当前载体声明**（原子：同目录 tmp + rename）。
+*
+* 🔴 **不做唯一性检查** —— 那是 `claimBinding` 的职责。本函数只负责"这份文件长成什么样"。
+* 分开的理由：唯一性检查需要**扫全部轨迹**，而写只需要一个目录 ⇒ 让不扫盘的地方能便宜地写。
+*/
+function writeBindDeclaration(trajectoryDir, decl) {
+	const path = bindFilePath(trajectoryDir);
+	const tmp = `${path}.tmp`;
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(tmp, `${JSON.stringify(decl, null, 2)}\n`, "utf-8");
+		renameSync(tmp, path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* 清掉一条轨迹的当前载体声明（解绑）。
+* @returns 文件原本存在且已删除 ⇒ true
+*/
+function clearBindDeclaration(trajectoryDir) {
+	try {
+		const path = bindFilePath(trajectoryDir);
+		if (!existsSync(path)) return false;
+		renameSync(path, `${path}.del`);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* 列出某 CCC 下**全部轨迹的当前载体声明**（`dirName → 声明`）。
+*
+* 这是**反向查询**（会话 → 轨迹 / 轨迹 → 会话）的唯一入口，取代旧的旁路表扫描。
+* 跳过 `_` / `.` 前缀目录（归档区与运行时区不是轨迹，判据同 `activeTrajectoryDirNames`）。
+*
+* @param sessionsRoot `<CCC>/AGENT_SESSIONS`
+* @returns 有交代的轨迹；**永不抛**（目录读不到 ⇒ 空表）
+*/
+function listBindDeclarations(sessionsRoot) {
+	const out = [];
+	let names;
+	try {
+		names = readdirSync(sessionsRoot, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith("_") && !e.name.startsWith(".")).map((e) => e.name);
+	} catch {
+		return out;
+	}
+	for (const dirName of names) {
+		const decl = readBindDeclaration(join(sessionsRoot, dirName));
+		if (decl) out.push({
+			dirName,
+			decl
+		});
+	}
+	return out;
+}
+/**
+* **这条绑定还作数吗**（第三条不变量的机械形态）。
+*
+* 判据（owner 原话：「文件里写的 sessionId 可能已经不存在了，这个情况下就视同没绑定」）：
+*
+* | 文件 | 会话存在？ | 结论 |
+* |---|---|---|
+* | 无 | — | `absent` |
+* | 有 | 是 | **`usable`** |
+* | 有 | 否 | **`stale`** ⇒ **视同没绑定** |
+*
+* 🔴 **为什么"会话存在"必须由调用方给**：判断它要问宿主（`ctx.agents.get` /
+* `sessionController.resolveAgent` / 会话清单），而本模块是零依赖层。
+* ⇒ 这里只收一个 **`alive: (sessionId) => boolean`** 探针，把判断留在外面，本函数仍是纯逻辑、可单测。
+*
+* ⚠️ **`stale` 不删文件**：删除是写操作，而"视同没绑定"已经足够。
+* 留着过期文件反而有用 —— 它记录了"这条轨迹上一次由谁承载"（沿革不丢，同旧 `supersededAt` 的意图）。
+*
+* @param decl {@link readBindDeclaration} 的结果
+* @param alive 探针：该会话 id 此刻是否真实存在（**由调用方用宿主事实实现**）
+* @returns `absent` ／ `usable` ／ `stale`，以及（usable 时的）声明
+*/
+function isBindUsable(decl, alive) {
+	if (decl === null) return { state: "absent" };
+	try {
+		return alive(decl.sessionId) ? {
+			state: "usable",
+			decl
+		} : {
+			state: "stale",
+			decl
+		};
+	} catch {
+		return {
+			state: "stale",
+			decl
+		};
+	}
+}
+/**
+* 找出**已经占用**某个 dsh 会话 id 的那条轨迹（唯一性判据）。
+*
+* @param sessionsRoot `<CCC>/AGENT_SESSIONS`
+* @param sessionId 待检查的会话 id
+* @returns 占用它的轨迹目录名；无人占用 ⇒ `null`
+*/
+function findTrajectoryHolding(sessionsRoot, sessionId) {
+	for (const { dirName, decl } of listBindDeclarations(sessionsRoot)) if (decl.sessionId === sessionId) return dirName;
+	return null;
+}
+/**
+* **认领**：把某条轨迹的当前载体设成 `sessionId`，并**当场执行两条不变量**。
+*
+* 这是全仓**唯一**允许改变绑定关系的写入口：`appendBound` 与迁移脚本都走这里。
+* 集中成一处的理由 = 不变量只能有一个实现，否则迟早出现"某条路径忘了检查"（本仓已多次踩）。
+*
+* ## 判据（任一不成立即**拒绝**，不写）
+*
+* 1. **载体唯一**：`sessionId` 已安家在**另一条**轨迹 ⇒ 拒绝（一个会话不能绑两条轨迹）。
+*    ⚠️ 若它已安家在**本条**轨迹 ⇒ 幂等通过（重复 `use` 同一条轨迹是合法重入）。
+* 2. **轨迹唯一**：本条轨迹已由**另一个** `sessionId` 承载 ⇒ **拒绝**，除非 `takeover`。
+*    `takeover` = 载体换代（`rebuild` / 崩溃后新建），由调用方**显式**声明；
+*    绝不默认允许 —— 静默换代正是"一条轨迹长出两个载体"的成因。
+*
+* @param sessionsRoot `<CCC>/AGENT_SESSIONS`
+* @param dirName 目标轨迹目录名
+* @param decl 要写入的声明
+* @param opts.takeover 允许顶掉本条轨迹现有的另一个载体
+* @returns `{ ok: true }` 或 `{ ok: false, code, detail }`（**不抛**，由调用方决定如何呈现）
+*/
+function claimBinding(sessionsRoot, dirName, decl, opts = {}) {
+	const holder = findTrajectoryHolding(sessionsRoot, decl.sessionId);
+	if (holder !== null && holder !== dirName) return {
+		ok: false,
+		code: "SESSION_TAKEN",
+		detail: `会话 ${decl.sessionId} 已经承载轨迹「${holder}」，不能同时再承载「${dirName}」。一个会话只能属于一条认知轨迹 —— 要给「${dirName}」开一个载体，请新建一条会话。`
+	};
+	const cur = readBindDeclaration(join(sessionsRoot, dirName));
+	if (cur !== null && cur.sessionId !== decl.sessionId && opts.takeover !== true) return {
+		ok: false,
+		code: "TRAJECTORY_OCCUPIED",
+		detail: `轨迹「${dirName}」当前已由会话 ${cur.sessionId} 承载（${cur.action}，${new Date(cur.at).toISOString()}）。如需换代（rebuild / 重建载体），调用方必须显式声明 takeover —— 静默换代会让一条轨迹出现两个载体。`
+	};
+	let released;
+	if (holder !== null && holder !== dirName) {
+		if (clearBindDeclaration(join(sessionsRoot, holder))) released = holder;
+	}
+	if (!writeBindDeclaration(join(sessionsRoot, dirName), decl)) return {
+		ok: false,
+		code: "WRITE_FAILED",
+		detail: `写 ${BIND_FILENAME} 失败：${join(sessionsRoot, dirName)}`
+	};
+	return released === void 0 ? { ok: true } : {
+		ok: true,
+		released
+	};
+}
+//#endregion
+//#region src/trajectory/bound.ts
+/**
+* trajectory/bound.ts — 「会话 ↔ 认知轨迹」绑定（**2026-10-20 重做：归属 = 轨迹自己的交代**）
+*
+* ## 判决 D172（owner 2026-10-20 原话，这是整个文件的设计依据）
+*
+* > 「**认知轨迹自己交代永远是最好的交代**」
+* > 「绑定表是没有意义的，绑定关系必须**运行时按照规则探测**，绑定表本质就搞成**第二真相源**了」
+* > 「依赖文件系统…每个认知轨迹目录内放一个 `current.dsh_session_bind`，**以这个为绑定真相源**」
+* > 「文件里写的 sessionId **可能已经不存在了**，这个情况下就**视同没绑定**，就正确了」
+*
+* ## 旧形态为什么错（不是"性能不够"，是"真相源放错地方"）
+*
+* 旧实现用 **`.bindings.json` ＋ 宿主存储域** 两张旁路索引记录"谁承载谁"。
+* 它们是**旁路**：描述的对象（轨迹目录）与自己分离 ⇒ 一旦不一致就要写代码对账，
+* 而**对账失败没有任何机械信号**（本轨反复踩的形状：症状与真因在读数上完全不像）。
+*
+* 新形态：归属写在**轨迹目录自己里面**（`current.dsh_session_bind`）。
+* 判据不再是"表里有没有一条记录"，而是"**这一刻谁真的在承载它**"。
+*
+* ## 🔴 三条不变量（前两条由**形态**保证，第三条由**探针**保证）
+*
+* | # | 不变量 | 保证方式 |
+* |---|---|---|
+* | 1 | 一条轨迹**至多一个**当前载体 | 它是**一个文件**，写入即整体原子覆盖 |
+* | 2 | 一个载体**至多一条**轨迹 | 写入前扫全部轨迹的交代，该 id 已在别处 ⇒ **拒绝** |
+* | 3 | **会话不存在 ⇒ 视同没绑定** | `isBindUsable(decl, alive)`（探针由调用方给） |
+*
+* ⚠️ 旧的 `supersededAt`（"只留一条"靠标记退掉）**整条退役**：标记可以忘，覆盖不会忘。
+* 存量里带 `supersededAt` 的记录在迁移时**直接跳过**（它们本就不是"当前"）。
+*
+* ## 零依赖与不抛
+* 读函数**永不抛**；写函数返回布尔 / 结构化结果，由调用方决定如何呈现。
+*/
+/**
+* 从 dsh 会话对象取 `header.id` / `header.cwd`。
+* @returns 取不到 ⇒ `null`
+*/
+function sessionHeader(session) {
+	const header = session?.header;
+	if (!header || typeof header !== "object") return null;
+	return header;
+}
+/** 由会话对象定位 CCC 根（上溯 `.serenity`）；定位不到 ⇒ `null` */
+function rootOf(session) {
+	const cwd = sessionHeader(session)?.cwd;
+	if (typeof cwd !== "string") return null;
+	return cccRootForCwd(cwd);
+}
+/** 目录名 → 轨迹标签（固定位置编码；非本工具建的目录回退整名——编码无关 U4） */
+function cognitiveTrajectoryLabel(dirName) {
+	return parseTrajectoryCode(dirName) ?? dirName;
+}
+/**
+* 把一条「轨迹自我交代」投影成对外的 `SessionBoundRecord`。
+*
+* 🔴 **`sessionId` 的语义在这里对齐**：旧记录里 `sessionId` 是**展示码**（`S###`），
+* 新绑定文件里是**dsh 会话 id**（它是硬锚）。历史调用方有两类读法，故两个字段都给：
+*  · `sessionId` → **dsh 会话 id**（新语义，硬锚）
+*  · `sessionId2` → 展示码（由轨迹目录名派生；旧语义）
+* 这样"我要这个会话的 id"与"我要显示成 S###"各自有确定字段，不再靠猜。
+*/
+function toRecord(dirName, decl, root) {
+	return {
+		dirName,
+		mdPath: join(root, "AGENT_SESSIONS", dirName, "SESSION.md"),
+		sessionId: decl.sessionId,
+		sessionId2: cognitiveTrajectoryLabel(dirName),
+		at: decl.at,
+		action: decl.action,
+		...decl.note !== void 0 ? { note: decl.note } : {},
+		...decl.createdAsUser === true ? { createdAsUser: true } : {}
+	};
+}
+/** @deprecated D172：存储域已退役；保留为空实现，装载期调用点无需改动 */
+function setBindingStore(_store) {}
+/**
+* 读**这个会话**当前承载哪条轨迹（正向：会话 → 轨迹）。
+*
+* 判据（D172）：扫全部轨迹的自我交代，找 `sessionId === 本会话 id` 且**仍然 usable** 的那条。
+*
+* 🔴 为什么这里是"扫"而不是"查表"：**归属是算出来的，不是记下来的**。
+* 本 CCC 的轨迹数是**数十**量级，每次读盘只读每个目录里的一个小文件；比维护一份会漂的索引便宜。
+*
+* ⚠️ **不验"会话是否还活着"**：本函数回答的是"这个**活着的**会话属于谁"——
+* 调用方手里就拿着那个会话对象，它显然存在。`alive` 探针只在**反向**（轨迹 → 会话）才需要。
+*
+* @returns 记录（含 `dirName` / `mdPath` / dsh `sessionId`）；无 ⇒ `null`
+*/
+function readLastBound(session) {
+	const id = sessionHeader(session)?.id;
+	const root = rootOf(session);
+	if (typeof id !== "string" || id === "" || root === null) return readLegacyBoundFromEvents(session);
+	for (const { dirName, decl } of listBindDeclarations(sessionsRoot(root))) if (decl.sessionId === id) return toRecord(dirName, decl, root);
+	return readLegacyBoundFromEvents(session);
+}
+/** 旧形态事件类型（v1.29.1~v1.30.5 写入会话日志；只读兼容，**永不写**） */
+const SESSION_BOUND_EVENT = "serenity/bound";
+/** 从会话日志扫最后一条 `serenity/bound`（兼容存量；坏记录跳过） */
+function readLegacyBoundFromEvents(session) {
+	const events = sessionEvents(session);
+	for (let i = events.length - 1; i >= 0; i--) {
+		const ev = events[i];
+		if (!ev || ev.type !== SESSION_BOUND_EVENT) continue;
+		const d = ev.data;
+		if (!d || typeof d.dirName !== "string" || typeof d.mdPath !== "string") continue;
+		return {
+			dirName: d.dirName,
+			mdPath: d.mdPath,
+			sessionId: typeof d.sessionId === "string" ? d.sessionId : "",
+			at: typeof d.at === "number" ? d.at : 0,
+			action: typeof d.action === "string" ? d.action : "activate"
+		};
+	}
+	return null;
+}
+/**
+* **调用方自身**所属轨迹的标签（审计字段 `createdBy` 的唯一正解）。
+*
+* 三级来源（逐级回退，理由见旧实现注释与 S142 §30.12.1 实测）：
+*  1. `readLastBound(session)` —— 持久归属（重启存活）
+*  2. `getActiveSessionInfo(scope)` —— 本会话的内存激活（按 scope 隔离）
+*  3. `getLastActiveSessionInfo()` —— 全局最近激活指针（最后兜底）
+*/
+function resolveSessionCognitiveTrajectoryLabel(session, scope) {
+	const bound = session ? readLastBound(session) : null;
+	if (bound?.dirName) return cognitiveTrajectoryLabel(bound.dirName);
+	const scoped = scope !== "" ? getActiveSessionInfo(scope) : null;
+	if (scoped) return scoped.sessionId;
+	return getLastActiveSessionInfo()?.sessionId ?? "";
+}
+/**
+* 反向查：**此刻**承载某条轨迹的 dsh 会话 id（按 `at` 倒序，最新在前）。
+*
+* D172 起判据 = **轨迹自己的交代 ＋ "那个会话还在"**：
+*  · 文件不存在 ⇒ 没绑定
+*  · 文件在但 `alive` 说不存在 ⇒ **视同没绑定**（owner 原话），**不算候选**
+*
+* ⚠️ **`alive` 缺省时怎么判**：调用方没给探针 ⇒ 只能信文件（`usable`）。
+* 那是"读不到宿主事实"的降级，**不是**"会话一定在"。需要严格判的一方请显式传探针
+* （唤醒选人是这种：见 `wake/scheduler.ts`）。
+*
+* @param root CCC 根
+* @param dirName 轨迹目录名
+* @param alive 探针：该 dsh 会话 id 此刻是否真实存在
+* @returns 会话 id 列表（本形态**至多一条**——一个文件只装一个 id）；无 ⇒ `[]`
+*/
+function listBoundSessionIds(root, dirName, alive) {
+	const decl = readBindDeclaration(join(sessionsRoot(root), dirName));
+	if (decl === null) return [];
+	return (alive ? isBindUsable(decl, alive).state === "usable" : isBindUsable(decl, () => true).state === "usable") ? [decl.sessionId] : [];
+}
+/**
+* 把一条轨迹的当前载体写成 `sessionId`（**唯一写入口**，内部走 `claimBinding` 的两条不变量）。
+*
+* 旧签名 `appendBound(session, action, rec)` 保持不变：`session` 提供 `header.id` / `header.cwd`，
+* `rec.dirName` 指明写哪条轨迹的交代。
+*
+* @returns 写入成功 ⇒ true（**每条轨迹只有一个文件，没有"追加"语义，只有"覆盖"**）
+*/
+function appendBound(session, action, rec) {
+	const id = sessionHeader(session)?.id;
+	const root = rootOf(session);
+	if (typeof id !== "string" || id === "" || root === null) return false;
+	const result = claimBinding(sessionsRoot(root), rec.dirName, {
+		sessionId: id,
+		at: Date.now(),
+		action,
+		...rec.note !== void 0 ? { note: rec.note } : {},
+		...rec.createdAsUser === true ? { createdAsUser: true } : {}
+	}, { takeover: rec.takeover === true });
+	if (!result.ok) {
+		console.warn(`[serenity-hooks] ✗ 绑定未写入（${result.code}）：${result.detail}`);
+		return false;
+	}
+	return true;
+}
+/**
+* 这条轨迹**是否曾经有过载体**（判"要不要允许自建"）。
+*
+* 🔴 这是 owner 第 2 条的判据来源：**"绑定表空"≠"从未有过会话"**。
+* 旧实现拿"未退的绑定条目为空"当"没绑定"，于是一条轨迹的载体被退掉之后就
+* 又长出一个新的（实测：S196 在同一分钟出现第二个载体）。
+*
+* 新判据 = **轨迹目录里有没有交代文件**（哪怕它指向的会话已不存在 ⇒ 有过，就不再自动建）。
+*
+* @returns `'never'`（从未有过 ⇒ 允许自建）／`'occupied'`（有过 ⇒ 禁止自建）／`'live'`（此刻有效）
+*/
+function carrierState(root, dirName, alive) {
+	const decl = readBindDeclaration(join(sessionsRoot(root), dirName));
+	if (decl === null) return { state: "never" };
+	return isBindUsable(decl, alive).state === "usable" ? {
+		state: "live",
+		sessionId: decl.sessionId
+	} : {
+		state: "occupied",
+		sessionId: decl.sessionId
+	};
+}
+//#endregion
+//#region src/kernel/message-source.ts
+/** ACC 注入消息的 kind —— 唤醒 / 打回 / keeper 提醒 / 锚定轮 / rebuild 交接等一律同值。 */
+const ACC_MESSAGE_KIND = "plugin:dsh-serenity-hooks";
+/** ACC 注入消息的统一来源值（各缝共用；需要 `form` 时按 `ContextFormed` 另加字段）。 */
+const PLUGIN_SOURCE = { kind: ACC_MESSAGE_KIND };
+//#endregion
+export { listBoundSessionIds as a, setBindingStore as c, carrierState as i, PLUGIN_SOURCE as n, readLastBound as o, appendBound as r, resolveSessionCognitiveTrajectoryLabel as s, ACC_MESSAGE_KIND as t };

package/lib/tools/trajectory-constraint-admin.d.ts

@@ -13,7 +13,14 @@
  * 归属（D23）不变：ACC 提供机制（教程 + 校验 + 列表），**约束内容归 CCC**（写进 `trajectory-constraint.json`）。
  */
 import type { JsonValue } from '../kernel/json.js';
-/** 轨迹约束 定义教程：概念 ／ `trajectory.json` schema ／ 双白名单 ／ 轨迹纪律 ／ 微信路由 */
+/**
+ * 轨迹约束 定义教程：**只讲「限制面」**（约束面 / 双白名单 / 纪律参与项 / 路由）。
+ *
+ * 🔴 2026-10-20 拆分（owner 裁 Q2）：本章原先同时承载「描述自己」与「限制自己」。
+ * 两者读者与前提不同 —— **描述自己是所有轨迹的常态，限制自己才是特例** ——
+ * 故「章程 / 常驻 / 三个载体」已移入 `config docs trajectory-self`。
+ * ⛔ **本文件不再重复那份内容**（一个内容一个正文入口，v1.75.0 指针纪律）。
+ */
 export declare const TRAJECTORY_CONSTRAINT_GUIDE: string;
 /** 校验当前 CCC 的 轨迹约束面：msms 均已注册 ／ model ∈ cheap-worker.models ／ 提示词非空 */
 export declare function validateTrajectoryConstraint(root: string): JsonValue;

package/lib/tools/trajectory-self-docs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * tools/trajectory-self-docs.ts — 「一条认知轨迹如何描述自己」的**手册正文**
+ *
+ * ## 为什么这一章单独存在（owner 2026-10-20 原话）
+ *
+ * > 「例如某个认知轨迹想设定自己是**常驻**的，想给自己做**轨迹约束**，
+ * >   这种**说明性的内容**有吗，在哪里，**这是很重要的内容**，
+ * >   是认知轨迹感知理解这些**边界的重要手册**」
+ *
+ * ⇒ 此前「描述自己」与「限制自己」被混成一章（`trajectory-constraint`），
+ *   而那两件事的**读者与前提完全不同**：
+ *
+ * | 面 | 谁需要 | 性质 |
+ * |---|---|---|
+ * | **描述自己**（我是谁、我擅长什么、我是否欢迎来麻烦我） | **所有轨迹** | 常态 |
+ * | **限制自己**（工具白名单、模型、MSM 白名单） | 只有需要限权的轨迹 | 特例 |
+ *
+ * ⇒ 把「描述」独立成章。**普通轨迹不必为了写一段自述而变成受约束的轨迹** ——
+ *   这是本章存在的**唯一理由**，也是 D173「常驻 = 自我声明」的落点。
+ *
+ * ## 归属（D23）
+ * 机制在 ACC（有哪些载体文件、字段叫什么、怎么被读、何时生效）；
+ * **内容在 CCC**（这条轨迹具体写什么 —— 它的章程与自述是它自己的知识）。
+ *
+ * ## 与 `trajectory-constraint` 章的分工（一个内容一个正文入口）
+ * 本章 = **声明面（我是什么）**；那一章 = **约束面（我被限成什么）**。
+ * 两章互指，但**不复制**对方正文（本仓 v1.75.0 的指针纪律）。
+ */
+/**
+ * 一章的全文。
+ *
+ * ⚠️ 本函数是**纯常量拼接**（无 IO、无 ctx）：手册正文不随容器状态变化，
+ * 唯一随状态变的东西（"我现在是不是轨迹约束"）由 `config list` 回答，不写进正文。
+ */
+export declare const TRAJECTORY_SELF_GUIDE: string;