@shgroup/dsh-serenity-hooks 1.64.0 → 1.66.0

package/lib/{trajectory-ops.d.ts → cognitive-trajectory-ops.d.ts}

@@ -1,18 +1,41 @@
 /**
- * trajectory-ops.ts — 轨迹工具纯操作层（零 DSH 依赖，可独立单测）
+ * cognitive-trajectory-ops.ts — 轨迹工具纯操作层（零 DSH 依赖，可独立单测）
  *
  * 行为对齐 osp（opencode-serenity-plugin/src/session/lib.ts）——osp 是 ACC 工具 spec。
  *
- * v1.33 收敛（S142 §32）：本文件只服务 `container_trajectory` 的动作面
+ * v1.33 收敛（S142 §32）：本文件只服务 `cognitive_trajectory` 的动作面
  * （现行 **8 个**：list / show / create / use / rebuild / **send-now** / **send-later** / **cro-guide**）。旧 `logbook` 面里
  * **close / archive / health / qa 四个动作已删**（用户裁决「功能上废弃，实际上没用」），
  * 其函数（closeSession / archiveSessions / healthCheck / qaCheck）**同批删除**——
  * 保留下来的只有：create（--desc / --issue 二选一、dry-run 预览）、
  * list（含 summarize 仪表盘）、show、use（激活 + 绑定）、以及供 list 用的 summarize。
- * 「完成」不再由 close 写入，而是从 SESSION.md 的 `[x]` 推导；归档走 `container_fs mv`。
+ *
+ * ## 🔴 2026-10-18（owner 令）：**认知轨迹没有生命周期**
+ *
+ * owner 原话要点：*"我需要允许永存的认知轨迹……我希望该生命周期足够简单，即没有生命周期，
+ * 但允许轨迹本身被操作为归档"*。据此**删除**了以下全部"生命周期"语义：
+ *
+ * | 被删的 | 为什么它属于生命周期 |
+ * |---|---|
+ * | `completed` 解析（SESSION.md 里的方括号小写 x） | "完成"是一个**终态**；没有生命周期就没有终态 |
+ * | `summarize` 的 Active / Completed / Stale / Ghost 四项计数 | 四项全部在给轨迹分"阶段" |
+ * | `advisoryHint` 的「N 天未更新」告警 | 老化告警的前提是"旧轨迹该退休了"——现在**旧不是问题** |
+ * | `findLatestActiveSessionMd`（**全仓零消费者**，纯死代码） | 它的语义是"最新的**未完成**轨迹"，前提已不存在 |
+ *
+ * **保留**：SESSION.md 头部的状态行**照旧生成**（`- 状态: [ ] 进行中`），但**不再被任何代码解析**。
+ * 理由（owner 裁决）：格式最小变动、老文件完全不用改。⇒ 它从"机器契约"降为**惰性文本**，
+ * 且"进行中"对永存轨迹**恒为真**，因此不构成谎言。
+ *
+ * **新增唯一的操作**：`archiveSession()` —— 单向移入 `_archived/`。
+ * 归档是**唯一的"变化"**，且它不属于轨迹自身：轨迹本体（目录 ＋ SESSION.md）**永不被改**，
+ * 只是**换了个存放位置**、从清单里消失。恢复 = 手工 `container_fs mv` 移回（owner 裁决：不设 unarchive）。
+ *
+ * ⚠️ 由此产生一条**必须成立**的配套：`readAllSessions` **跳过 `_` 前缀目录**。
+ * 否则归档后的轨迹会继续出现在清单里，"归档"就不是归档了（历史 bug：`_weixin-logs` /
+ * `_skiff-logs` / `_corpus` 曾被当成轨迹列出来）。
  */
 /**
- * `container_trajectory` 工具的动作集合（v1.33，S142 §32 用户裁决后的收敛结果）。
+ * `cognitive_trajectory` 工具的动作集合（v1.33，S142 §32 用户裁决后的收敛结果）。
  *
  * 为什么收敛到这 8 个（R↓；v1.33 收敛时为 **6 个** —— 其后追加 `send-now`（09-16）
  * 与 `cro-guide`（09-20），🔴 2026-09-25 更正计数，勿再写成"6 个"）：旧面是 `logbook`（11）+ `trajectory`（12）两个工具，用户裁决
@@ -24,7 +47,7 @@
  * wake-add/list/rm 收敛为 wake-later（**2026-09-17 更名 `send-later`**）。
  * 2026-09-16（所有者裁决）：新增 **send-message**（**2026-09-17 更名 `send-now`**）—— 即时投递
  *   （与 wake-later 共用取用通路，差别只在时刻"现在 vs 未来"与回执"有 vs 无"）。
- *   设计稿 docs/trajectory-send-message-design.md。
+ *   设计稿 docs/cognitive-trajectory-send-message-design.md。
  * 2026-09-17（所有者裁决 · 命名 A 案）：**两个投递动作更名** —— `wake-later` → **`send-later`**、
  *   `send-message` → **`send-now`**。判据（R↓）：两者是**同一条投递通路**（同取用机制 / 同载荷 /
  *   同落点语义），只差**时刻**；而「唤醒（冷载入）」是**两条路径共有**的属性，不配做区分
@@ -37,8 +60,8 @@
  *   而**管轨迹的人正是用本工具的人**；挂这儿 = 设计 §9-5 的"**既有 guide 位置、不新增域**"。
  *   ⚠️ 本动作**纯读**（输出指南正文，不碰 fs、不碰注册表）。
  */
-type TrajectoryAction = 'list' | 'show' | 'create' | 'use' | 'rebuild' | 'send-now' | 'send-later' | 'cro-guide';
-export declare const TRAJECTORY_ACTIONS: readonly TrajectoryAction[];
+type CognitiveTrajectoryAction = 'list' | 'show' | 'create' | 'use' | 'rebuild' | 'archive' | 'send-now' | 'send-later' | 'cro-guide';
+export declare const COGNITIVE_TRAJECTORY_ACTIONS: readonly CognitiveTrajectoryAction[];
 /**
  * 读取 Session 事件序列（v1.28.1 适配 0.1.2-rc.1 补齐）：rc.1 起官方 Session 类
  * 移除 `.events` 属性 → `snapshotEvents()` 方法（dsh-session/src/session.ts：
@@ -50,15 +73,17 @@ export declare const TRAJECTORY_ACTIONS: readonly TrajectoryAction[];
  * 泛型 T：调用方按需声明事件形状（如 `SessionEvent`），unknown 默认。
  */
 export declare function sessionEvents<T = unknown>(session: unknown): readonly T[];
+/** 归档区目录名（`_` 前缀 ⇒ 不是轨迹，见 readAllSessions 的跳过判据） */
+export declare const ARCHIVED_DIR = "_archived";
 export declare function sessionsRoot(root: string): string;
+/**
+ * 轨迹的**存在形态**（🔴 **2026-10-18 起不再是"生命周期"**）。
+ *
+ * `hasSessionMd` 是唯一的判据，而且它**不是阶段**：它只说"这个目录里有没有正文"。
+ * 旧字段 `completed` 已删除（见文件头「认知轨迹没有生命周期」）。
+ */
 interface SessionStatus {
     hasSessionMd: boolean;
-    /**
-     * 「完成」的判据 = SESSION.md 里**出现 `[x]`**（v1.33 起不再由 close 动作写入）。
-     * 🔴 这是**全文匹配**、两代格式通用：新格式的状态行 `- 状态: [x] …` 与旧格式的
-     * `## 状态` 段内 `- [x] 已完成` 都能被识别 ⇒ **不可改成锚定某一行的正则**（会让旧会话永远"未完成"）。
-     */
-    completed: boolean;
 }
 interface SessionEntry {
     dirName: string;
@@ -174,11 +199,65 @@ export declare function extractSessionMdPathFromText(text: string): string | nul
  */
 export declare function resolveSessionByTitle(title: string, sessionsDir: string): string | null;
 /**
- * 约定回退（v1.24.11）：AGENT_SESSIONS 下最新修改的**未完成**会话的 SESSION.md。
- * readAllSessions 已按「未完成优先 + mtime 降序」排序 → 首个未完成且含 SESSION.md 即最新活动。
- * 只作最后手段（内存/events/锚点全缺时），保证重建锚点至少指向一个真实存在的轨迹。
+ * summary 仪表盘（供 `list` 动作拼接；v1.33 起独立 `summary` 动作已撤，并入 list）。
+ *
+ * 🔴 **2026-10-18：四项生命周期计数已删**（Active / Completed / Stale / Ghost）。
+ * 它们全都在给轨迹**分阶段**，而 owner 裁决「没有生命周期」⇒ 唯一有意义的总数是 `Total`。
+ * ⚠️ **`Ghost` 也被删了**（"目录在但没 SESSION.md"）—— 它不是阶段而是**损坏**，但：
+ *   · 真出现时 `use` 会在 `advisoryHint` 里**当场说清**（用到才发现，比长期挂一个计数更有效）；
+ *   · 挂一个恒 0 的计数只会钝化注意力。
+ * `Total` 现在 = **活跃轨迹数**（`_` 前缀的归档区与日志区已不在域内）。
  */
-export declare function findLatestActiveSessionMd(root: string): string | null;
-/** summary 仪表盘（供 `list` 动作拼接；v1.33 起独立 `summary` 动作已撤，并入 list） */
 export declare function summarize(root: string): string;
+/**
+ * 活跃轨迹的**结构化**清单（面板消费；owner 2026-10-18 需求二）。
+ *
+ * 🔴 为什么不在面板侧重新扫目录：**"哪些轨迹是活跃的"只有一个判据源** =
+ * `readAllSessions`（它已经实现 `_` 前缀跳过 = 归档区不在域内）。面板若自己扫一遍
+ * `AGENT_SESSIONS/`，就会长出**第二份会漂的实现** —— 归档之后面板仍会列出它，
+ * 而这种不一致**没有任何机械信号**（两边各自都"跑成功了"）。
+ *
+ * 字段都取自**文件系统事实**，不做任何推断：
+ * `dirName` / `sessionId`（S### ，无则 ''）/ `ageDays`（目录 mtime 距今天数）/ `hasSessionMd`。
+ * ⚠️ **没有 `completed`** —— 轨迹没有生命周期（见文件头）。
+ *
+ * @param root CCC 根
+ * @returns 按 mtime 降序的活跃轨迹（已排除 `_` 前缀目录）
+ */
+export interface TrajectorySummary {
+    dirName: string;
+    sessionId: string;
+    ageDays: number;
+    hasSessionMd: boolean;
+}
+export declare function listActiveTrajectories(root: string): TrajectorySummary[];
+export interface ArchiveResult {
+    message: string;
+    dirName: string;
+    from: string;
+    to: string;
+    dryRun: boolean;
+}
+/**
+ * 把一条轨迹**单向**归档到 `AGENT_SESSIONS/_archived/`（owner 2026-10-18 裁决）。
+ *
+ * ## 为什么这是"唯一"的状态变化
+ * 轨迹没有生命周期 ⇒ 它**不完成、不关闭、不衰老**。它只会**换个存放位置**：
+ * 从活跃区移到归档区。目录与 SESSION.md **逐字节不动**（纯 rename）——
+ * 「归档」在此**不是删除，也不是收尾**，只是"不再列在活跃清单里"。
+ *
+ * ## 判据（R↓）
+ * ① **单向**：owner 裁决不设 unarchive。恢复 = 手工 `container_fs mv` 移回。
+ *    ⇒ 不提供反向动作，避免"两个方向各自实现一遍、语义各自漂移"。
+ * ② **绝不覆盖**：目标已存在 ⇒ 报错，**不合并、不重命名、不删除**。归档是不可逆动作，
+ *    静默覆盖会**毁掉**先前那条轨迹（它的 SESSION.md 是唯一副本）。
+ * ③ **归档区不建在别处**：落点恒为 `<CCC>/AGENT_SESSIONS/_archived/`，
+ *    与 `readAllSessions` 的 `_` 跳过判据**成对**（换一处就要同时改两处 ⇒ 不换）。
+ * ④ `dryRun` 只报路径、不落盘。
+ *
+ * @param root CCC 根
+ * @param key 目录名 / S### / 唯一模糊串（同 findSession）
+ * @param dryRun 预览
+ */
+export declare function archiveSession(root: string, key: string, dryRun?: boolean): ArchiveResult;
 export {};

package/lib/{trajectory-skills.d.ts → cognitive-trajectory-skills.d.ts}

@@ -1,20 +1,20 @@
 /**
- * trajectory-skills.ts — 轨迹 skill 声明解析 + 注入内容装配（纯逻辑，零 DSH 依赖）
+ * cognitive-trajectory-skills.ts — 轨迹 skill 声明解析 + 注入内容装配（纯逻辑，零 DSH 依赖）
  *
- * 接口真相源：`docs/trajectory-skill-injection.md` v1.0（§2 数据契约 / §3 注入契约）。
+ * 接口真相源：`docs/cognitive-trajectory-skill-injection.md` v1.0（§2 数据契约 / §3 注入契约）。
  * 一句话：**轨迹自己声明它要挂哪些 skill**（`SESSION.md` 顶部 YAML frontmatter 的 `skills:`），
  * ACC 在**绑定期间**把这些 skill 的 `SKILL.md` 全文注入系统提示词。
  *
  * 分工（R↓：为什么解析与注册分开）：
  *   · 本模块 = **纯文本层**（解析 / 装配 / 安全判定）——可脱离 DSH 单测；
- *   · `seams/system-prompt.ts` 的 `registerTrajectorySkillSection` = **宿主接入层**
+ *   · `seams/system-prompt.ts` 的 `registerCognitiveTrajectorySkillSection` = **宿主接入层**
  *     （per-agent `ctx.systemPrompt.section`），只做门与注册，不再解析文本。
  *
  * 边界（规格 §2.2）：**不解析** `skills` 以外任何键的语义（CCC 可自由使用，ACC 视而不见）；
  * **不改写** frontmatter（ACC 只读）。
  */
 /** 全文注入总长上限（字符数；规格 §3「缺省 32 KB」——防上下文爆炸） */
-export declare const TRAJECTORY_SKILLS_MAX_CHARS: number;
+export declare const COGNITIVE_TRAJECTORY_SKILLS_MAX_CHARS: number;
 /**
  * 抽取文件顶部 YAML frontmatter 区（规格 §2.1）。
  *
@@ -51,12 +51,12 @@ export declare function parseDeclaredSkills(sessionMd: string): string[];
  *     （规格 §6-6 要求"不静默"；不注册就等于静默）
  * 其余（文件在但无 frontmatter / 无 `skills` 键 / 值为空）⇒ false，不注册、不产生噪声。
  */
-export declare function hasTrajectorySkillsDeclaration(root: string, mdPath: string): boolean;
+export declare function hasCognitiveTrajectorySkillsDeclaration(root: string, mdPath: string): boolean;
 /**
  * 合并两条声明来源（v1.44.0）：**CCC 级在前，轨迹级追加**，同名去重取首次位置。
  *
  * 两条来源（owner 令 2026-09-20）：
- *   · **CCC 级** = `.opencode/serenity.json` 的 `trajectory.skills`（本 CCC 所有轨迹共有的底座）；
+ *   · **CCC 级** = `.opencode/serenity.json` 的 `cognitiveTrajectory.skills`（本 CCC 所有轨迹共有的底座）；
  *   · **轨迹级** = 该轨迹 `SESSION.md` frontmatter 的 `skills:`（这条轨迹额外的）。
  *
  * 为什么是**并集**而不是二选一（R↓）：C1 设计当初否决"纯 CCC 全局"的理由是"会**丢掉
@@ -78,11 +78,11 @@ export declare function mergeSkillNames(cccSkills: readonly string[], trajSkills
  * @param root CCC 根
  * @param mdPath 轨迹的 SESSION.md 路径（**来自绑定的 `mdPath`**，不用 label 拼）
  * @param maxChars 总长上限（字符）
- * @param cccSkills CCC 级声明（`readTrajectorySkills`；缺省空 = 只有轨迹级，行为与 v1.43 一致）
+ * @param cccSkills CCC 级声明（`readCognitiveTrajectorySkills`；缺省空 = 只有轨迹级，行为与 v1.43 一致）
  * @param onInjectedNames 观测回调（本次请求实际带上的 skill 名；**纯观测**，供用量统计用——
  *        回调抛错被吞，**不影响注入正文**）
  * @returns 注入正文；两条来源皆无声明 → `''`（空串 = 宿主不产出该 section 块）；
  *          SESSION.md 缺失/读失败 → 响亮提示（若同时有 CCC 级声明，则提示在前、正文随后——
  *          **提示不因"别处有内容"而被吞掉**）
  */
-export declare function buildTrajectorySkillsSection(root: string, mdPath: string, maxChars?: number, cccSkills?: readonly string[], onInjectedNames?: (names: readonly string[]) => void): string;
+export declare function buildCognitiveTrajectorySkillsSection(root: string, mdPath: string, maxChars?: number, cccSkills?: readonly string[], onInjectedNames?: (names: readonly string[]) => void): string;

package/lib/cro-log.d.ts

@@ -3,10 +3,10 @@
  *
  * ## 所有者令（本模块的存在理由）
  *
- * 「S151 和 S185 的验证都说明，trajectory 倾向于自己做个结构化记录来记录自身 CRO 的执行情况，
+ * 「S151 和 S185 的验证都说明，认知轨迹倾向于自己做个结构化记录来记录自身 CRO 的执行情况，
  * 这是个结构化流水账；**我们 ACC 有必要进行 CRO 唤醒的日志记录**，当 CRO 存在时，每次**成功唤醒**
  * 写相关信息，但是保留数量要少，**只保留仅两日**的记录即可，**这个时间是程序化的**」
- * ＋「**这个日志写结构化文件到 trajectory 目录，文件名固定即可**」
+ * ＋「**这个日志写结构化文件到认知轨迹目录，文件名固定即可**」
  * ＋「**失败成功都记录**」。
  *
  * ## 它解决什么麻烦（白话）

package/lib/cro.d.ts

@@ -332,7 +332,7 @@ export declare function parseCroHostBinding(raw: string): string | null;
  * @param root CCC 根
  * @returns 启用了 CRO 的轨迹目录名（**排序后**，保证同 tick 顺序稳定、便于日志比对）
  */
-export declare function listCroTrajectories(root: string): string[];
+export declare function listCroCognitiveTrajectories(root: string): string[];
 /**
  * 执行一次 CRO 程序（**永不抛** —— 旁路容忍铁律）。
  *

package/lib/index.d.ts

@@ -4,7 +4,7 @@
  * 形态（DSH 官方 native hook 约定）：name / inject / Config / apply，无 default export。
  *
  * 能力：
- *   1. 真实 DSH 工具注册：container_fs（文件系统 15 子命令，含 reveal）、container_trajectory（轨迹生命周期 + 一次性安排，含 rebuild）
+ *   1. 真实 DSH 工具注册：container_fs（文件系统 15 子命令，含 reveal）、cognitive_trajectory（轨迹生命周期 + 一次性安排，含 rebuild）
  *   2. 拦截缝机械约束：tools/pre-execute + ctx.tools.guard（安全模式/黑名单/路径守卫）
  *
  * 加载：~/.dsh/config.yaml 加 insert 行（免改 DSH 源码），插件包装入 DSH node_modules。