@shgroup/dsh-serenity-hooks 1.32.0 → 1.34.1

package/lib/trajectory-ops-mrXK0H0I.js

@@ -0,0 +1,410 @@
+import { basename, dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+//#region src/trajectory-ops.ts
+/**
+* trajectory-ops.ts — 轨迹工具纯操作层（零 DSH 依赖，可独立单测）
+*
+* 行为对齐 osp（opencode-serenity-plugin/src/session/lib.ts）——osp 是 ACC 工具 spec。
+*
+* v1.33 收敛（S142 §32）：本文件只服务 `container_trajectory` 的 6 个动作
+* （list / show / create / use / rebuild / wake-later）。旧 `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`。
+*/
+const TRAJECTORY_ACTIONS = [
+	"list",
+	"show",
+	"create",
+	"use",
+	"rebuild",
+	"wake-later"
+];
+/**
+* 读取 Session 事件序列（v1.28.1 适配 0.1.2-rc.1 补齐）：rc.1 起官方 Session 类
+* 移除 `.events` 属性 → `snapshotEvents()` 方法（dsh-session/src/session.ts：
+* `snapshotEvents(fromSeq, toSeqExclusive)`）。插件早期代码多处裸读 `.events`
+* （经 `as unknown as { events? }` 断言绕过 typecheck），运行时静默 undefined——
+* 造成 first-anchor 每轮重插 / SESSION 激活恢复失效 / rebuild 定位错乱。
+* 统一收敛到本 helper：snapshotEvents() 优先（rc.1 真实形态），`.events` 兜底
+* （测试替身/旧运行时）。所有消费方一律经此读取，禁止再裸读 `.events`。
+* 泛型 T：调用方按需声明事件形状（如 `SessionEvent`），unknown 默认。
+*/
+function sessionEvents(session) {
+	const s = session;
+	if (!s) return [];
+	if (typeof s.snapshotEvents === "function") try {
+		return s.snapshotEvents() ?? [];
+	} catch {}
+	return s.events ?? [];
+}
+const SESSION_MD = "SESSION.md";
+const HEALTH_STALE_DAYS = 7;
+const DAY = 864e5;
+function sessionsRoot(root) {
+	return join(root, "AGENT_SESSIONS");
+}
+/** 解析 SESSION.md 状态元数据（对齐 osp parseSessionMd） */
+function parseSessionMd(filePath) {
+	try {
+		const content = readFileSync(filePath, "utf-8");
+		return {
+			hasSessionMd: true,
+			completed: /\[\s*x\s*\]/i.test(content)
+		};
+	} catch {
+		return {
+			hasSessionMd: false,
+			completed: false
+		};
+	}
+}
+function readSessionEntry(dirPath) {
+	try {
+		const st = statSync(dirPath);
+		if (!st.isDirectory()) return null;
+		const dirName = basename(dirPath);
+		const mdPath = join(dirPath, SESSION_MD);
+		const status = existsSync(mdPath) ? parseSessionMd(mdPath) : {
+			hasSessionMd: false,
+			completed: false
+		};
+		return {
+			dirName,
+			path: dirPath,
+			mtime: st.mtime,
+			status
+		};
+	} catch {
+		return null;
+	}
+}
+/** 读取 AGENT_SESSIONS 中所有会话，活跃（未完成）排前（对齐 osp readAllSessions） */
+function readAllSessions(sessionsDir) {
+	try {
+		return readdirSync(sessionsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => readSessionEntry(join(sessionsDir, e.name))).filter((s) => s !== null).sort((a, b) => {
+			if (!a.status.completed && b.status.completed) return -1;
+			if (a.status.completed && !b.status.completed) return 1;
+			return b.mtime.getTime() - a.mtime.getTime();
+		});
+	} catch {
+		return [];
+	}
+}
+/** 提取目录名中的会话 ID（S### 或 issue 名）；无匹配返回 '' */
+function extractSessionId(dirName) {
+	const m = dirName.match(/--S(\d{3,})--/);
+	return m ? `S${m[1]}` : "";
+}
+/**
+* 根据 key 查找会话（对齐 osp findSession）：
+* 精确目录名 → S### ID（允许 S31→031）→ 唯一模糊子串匹配（多个则报错）
+*/
+function findSession(sessionsDir, key) {
+	const all = readAllSessions(sessionsDir);
+	const byName = all.find((s) => s.dirName === key);
+	if (byName) return byName;
+	const searchId = key.replace(/^S/, "").padStart(3, "0");
+	const byId = all.find((s) => {
+		const m = s.dirName.match(/--S(\d{3,})--/);
+		return m && m[1] === searchId;
+	});
+	if (byId) return byId;
+	const lower = key.toLowerCase();
+	const fuzzy = all.filter((s) => s.dirName.toLowerCase().includes(lower));
+	if (fuzzy.length === 1) return fuzzy[0] ?? null;
+	if (fuzzy.length > 1) throw new Error(`Found ${fuzzy.length} sessions matching "${key}": ` + fuzzy.map((s) => s.dirName).join(", ") + ". Use a more specific query.");
+	return null;
+}
+/** list 子命令（对齐 osp listSessions 文本格式 + active 标记） */
+function listSessions(root, activeId) {
+	const sessions = readAllSessions(sessionsRoot(root));
+	if (sessions.length === 0) return "(no sessions in AGENT_SESSIONS/)";
+	const lines = sessions.map((s) => {
+		const age = Math.floor((Date.now() - s.mtime.getTime()) / DAY);
+		const sessionId = extractSessionId(s.dirName);
+		return `${activeId !== void 0 && sessionId !== "" && sessionId === activeId ? "●" : s.status.completed ? "✓" : "○"} ${s.dirName} (${age}d ago)`;
+	});
+	return `AGENT_SESSIONS/ (${sessions.length} sessions)\n` + lines.join("\n");
+}
+/** show 子命令（对齐 osp showSession：`# dirName\n\n` + SESSION.md 内容） */
+function showSession(root, key) {
+	const session = findSession(sessionsRoot(root), key);
+	if (!session) throw new Error(`Session not found: "${key}". Use "list" to see available sessions.`);
+	const mdPath = join(session.path, SESSION_MD);
+	if (!existsSync(mdPath)) return `Session ${session.dirName} (no SESSION.md — directory exists but is empty)`;
+	const content = readFileSync(mdPath, "utf-8");
+	return `# ${session.dirName}\n\n${content}`;
+}
+/** 生成 SESSION.md 模板（对齐 osp：goal 写入目标段，时间戳 YYYY-MM-DD HH:mm） */
+function sessionMdTemplate(title, id, goal, now) {
+	const ts = now.toISOString().slice(0, 16).replace("T", " ");
+	return `# SESSION: ${title}\n- ID: ${id}\n\n## 目标\n${goal ?? "（待补充）"}\n\n## 状态\n- [ ] 进行中\n\n## 关键决策\n| # | 决策 | 理由 |\n|---|------|------|\n| 1 | | |\n\n## 进度记录\n- ${ts} — 创建\n\n## 产出物\n- \n\n## 未解决的问题\n- \n`;
+}
+/** create 子命令（对齐 osp createSession：--desc/--issue 二选一 + dry-run + 长度限制） */
+/** 目录名脱敏（Windows 审计问题 10）：非法字符 → '-', 去尾点/空格, 保留名（CON/NUL 等）加前缀 */
+function sanitizeDirName(s) {
+	const cleaned = s.replace(/[<>:"/\\|?*\u0000-\u001f]/g, "-").replace(/[ .]+$/g, "");
+	if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(cleaned)) return `_${cleaned}`;
+	return cleaned;
+}
+function createSession(opts) {
+	const { root, desc, issue, goal, dryRun } = opts;
+	const sessionsDir = sessionsRoot(root);
+	const now = /* @__PURE__ */ new Date();
+	const datePrefix = now.toISOString().slice(0, 10);
+	if (!desc && !issue) throw new Error("create requires either --desc or --issue");
+	if (desc && issue) throw new Error("--desc and --issue are mutually exclusive");
+	if (issue) {
+		if (issue.length > 100) throw new Error(`issue too long: ${issue.length} chars (max 100)`);
+		const dirName = `${datePrefix}--${sanitizeDirName(issue)}`;
+		const sessionPath = join(sessionsDir, dirName);
+		if (!dryRun && existsSync(sessionPath)) throw new Error(`Session directory already exists: "${dirName}"`);
+		if (dryRun) return {
+			message: `[dry-run] Would create: ${dirName}/`,
+			dirName,
+			sessionPath,
+			sessionId: issue
+		};
+		mkdirSync(sessionPath, { recursive: true });
+		writeFileSync(join(sessionPath, SESSION_MD), sessionMdTemplate(issue, issue, goal, now), "utf-8");
+		return {
+			message: `Created: ${dirName}/`,
+			dirName,
+			sessionPath,
+			sessionId: issue
+		};
+	}
+	if (!desc || desc.length === 0) throw new Error("description cannot be empty");
+	if (desc.length > 200) throw new Error(`description too long: ${desc.length} chars (max 200)`);
+	const sessions = readAllSessions(sessionsDir);
+	let maxId = 0;
+	for (const s of sessions) {
+		const m = s.dirName.match(/--S(\d{3,})--/);
+		if (m) {
+			const num = parseInt(m[1], 10);
+			if (num > maxId) maxId = num;
+		}
+	}
+	const nextId = String(maxId + 1).padStart(3, "0");
+	const dirName = `${datePrefix}--S${nextId}--${sanitizeDirName(desc)}`;
+	const sessionPath = join(sessionsDir, dirName);
+	if (!dryRun && existsSync(sessionPath)) throw new Error(`Session directory already exists: "${dirName}"`);
+	if (dryRun) return {
+		message: `[dry-run] Would create: ${dirName}/\n  goal=${goal ?? "(none)"}`,
+		dirName,
+		sessionPath,
+		sessionId: `S${nextId}`
+	};
+	mkdirSync(sessionPath, { recursive: true });
+	writeFileSync(join(sessionPath, SESSION_MD), sessionMdTemplate(desc, `S${nextId}`, goal, now), "utf-8");
+	return {
+		message: `Created: ${dirName}/ (S${nextId})`,
+		dirName,
+		sessionPath,
+		sessionId: `S${nextId}`
+	};
+}
+/**
+* 活动会话跟踪（S134 v1.16.14 内存化，对齐 osp active-state）：
+* **不落盘**——活跃会话状态在内存 Map（key = scope = dsh 会话 id），避免落盘标记
+* 文件累积与跨会话串台（落盘版 `.dsh/active-sessions/<scope>` 已被此方案取代）。
+* 进程重启恢复：从**当前会话历史（events）**解析 `[SESSION CONTEXT]` 标记（use 时注入），
+* 只扫自己会话——无全局扫描、无跨会话污染。
+*/
+const DEFAULT_SESSION_SCOPE = "default";
+/** [SESSION CONTEXT] 恢复标记（use 时注入 events 历史；进程重启后从 events 解析） */
+const SESSION_CONTEXT_MARKER = "[SESSION CONTEXT] Activated:";
+/** 内存活跃会话：scope（dsh 会话 id）→ 会话信息（不落盘；并行多会话各自 key 隔离） */
+const activeStore = /* @__PURE__ */ new Map();
+/** 全局最近活跃（对齐 osp lastActive；供无 scope 上下文使用） */
+let lastActive = null;
+function getActiveSessionInfo(scope) {
+	return activeStore.get(scope) ?? null;
+}
+function getLastActiveSessionInfo() {
+	return lastActive;
+}
+function setActiveSessionInfo(scope, info) {
+	activeStore.set(scope, info);
+	lastActive = info;
+}
+function clearActiveSessionInfo(scope) {
+	activeStore.delete(scope);
+	if (lastActive && ![...activeStore.values()].some((v) => v === lastActive)) lastActive = null;
+}
+/** 当前 scope 的活跃会话 SESSION.md 绝对路径；无激活返回 null（读内存，不落盘） */
+function readActiveSessionMd(_root, scope = DEFAULT_SESSION_SCOPE) {
+	return getActiveSessionInfo(scope)?.mdPath ?? null;
+}
+/**
+* use 子命令：激活会话（写内存 Map）+ 返回对齐 osp 的输出文本
+* （含 [SESSION CONTEXT] 标记 + todowrite 指令；标记随工具结果进 events 历史，
+*  进程重启后从当前会话 events 解析恢复）。
+*/
+function useSession(root, key, scope = DEFAULT_SESSION_SCOPE) {
+	const session = findSession(sessionsRoot(root), key);
+	if (!session) throw new Error(`Session not found: "${key}". Use "list" to see available sessions.`);
+	const mdPath = join(session.path, SESSION_MD);
+	if (!existsSync(mdPath)) throw new Error(`Session "${session.dirName}" has no SESSION.md — nothing to load.`);
+	const sessionId = extractSessionId(session.dirName) || basename(session.dirName);
+	const dirName = session.dirName;
+	const shortName = dirName.replace(/^\d{4}-\d{2}-\d{2}--/, "");
+	setActiveSessionInfo(scope, {
+		sessionId,
+		dirName,
+		mdPath
+	});
+	return {
+		dir: dirName,
+		mdPath,
+		context: [
+			`───────────────────────────────────────────────────────────────`,
+			`${SESSION_CONTEXT_MARKER} ${dirName}`,
+			`───────────────────────────────────────────────────────────────`,
+			`Use "session show ${sessionId}" to view session details.`,
+			`SESSION.md path: ${mdPath}`,
+			``,
+			`→ All subsequent work should refer back to this session.`,
+			`  Use "session show ${sessionId}" to check current progress.`,
+			`  After advancing work, update the "进度记录" (progress) section in SESSION.md.`,
+			``,
+			`→ BEFORE responding to the user, you MUST call todowrite immediately`,
+			`  with the session todo list. The first item MUST be:`,
+			`    content: "SESSION: ${sessionId} — ${shortName}"`,
+			`    status: "completed", priority: "low"`,
+			`  Follow with any tasks parsed from SESSION.md.`,
+			`───────────────────────────────────────────────────────────────`
+		].join("\n")
+	};
+}
+/**
+* 从会话历史（events）解析会话身份（进程重启恢复；只扫**当前会话**自己的历史——无跨会话串台）。
+*
+* v1.24.11 稳固化（S142 用户需求：重建后新会话必须准确知道从哪个 SESSION 恢复）：
+* **路径规范行即可，不再要求 [SESSION CONTEXT] 标记**——`session use` 上下文与重建锚点
+* （buildRebuildAnchor 的 `- Persistent trajectory — SESSION.md path: <rel>` 行）同格式，
+* 因此**仅靠重建锚点的会话（从未显式 use）同样可恢复**。从**尾到头**扫描，最后一条
+* 合法路径胜出（时间序最新）；会话目录名/ID 从路径本身派生（单一真相源，不猜）。
+* 路径可为相对（重建锚点存 rel）——绝对化与存在性校验在调用方（知道 root）执行。
+*/
+function parseSessionContextFromEvents(events) {
+	for (let i = events.length - 1; i >= 0; i--) {
+		const strs = [];
+		collectStrings(events[i], strs);
+		for (const s of strs) {
+			const md = extractSessionMdPathFromText(s);
+			if (!md) continue;
+			let dirName;
+			let filePath;
+			if (basename(md) === SESSION_MD) {
+				dirName = basename(dirname(md));
+				filePath = md;
+			} else if (isSessionDirName(basename(md))) {
+				dirName = basename(md);
+				filePath = join(md, SESSION_MD);
+			} else continue;
+			if (!isSessionDirName(dirName)) continue;
+			const idMatch = dirName.match(/--S(\d{3,})--/);
+			return {
+				sessionId: idMatch ? `S${idMatch[1]}` : dirName,
+				dirName,
+				mdPath: filePath
+			};
+		}
+	}
+	return null;
+}
+/** 递归收集对象/数组/字符串中的全部字符串（保留原文，无 JSON 转义） */
+function collectStrings(v, out) {
+	if (typeof v === "string") {
+		out.push(v);
+		return;
+	}
+	if (v && typeof v === "object") for (const val of Object.values(v)) collectStrings(val, out);
+}
+/** 规范行正则：`SESSION.md path: <路径>`（路径可含空格 → [^\r\n]+ 整行匹配） */
+const SESSION_MD_PATH_RE = /SESSION\.md path:\s*([^\r\n]+)/;
+/** 从文本提取 SESSION.md 路径（use 上下文 / 重建锚点规范行通用；无匹配返回 null）。
+*  同行已知尾注（如系统提示词 Session 块的 persistent-body 注释）剥除——规范行只取路径本体。 */
+function extractSessionMdPathFromText(text) {
+	const m = text.match(SESSION_MD_PATH_RE);
+	if (!m) return null;
+	let p = m[1].trim();
+	const suffix = p.search(/ \(the trajectory's persistent body/);
+	if (suffix > 0) p = p.slice(0, suffix).trim();
+	return p;
+}
+/** 会话目录名形态校验（createSession 恒带日期前缀 `YYYY-MM-DD--`） */
+function isSessionDirName(dirName) {
+	return /^\d{4}-\d{2}-\d{2}--/.test(dirName) && dirName.length > 11;
+}
+/**
+* 从 dsh 会话标题解析 SESSION 目录（编码无关 best-match，U3/U4）——
+* 标题不假设 S### 前缀（CCC 可自定义编码：apaas-xxx / P### / 完整目录名等）。
+* 匹配优先级（全部对 AGENT_SESSIONS 现有目录 best-match，不猜）：
+*   ① 标题即完整目录名（含日期前缀 `YYYY-MM-DD--`）→ 精确命中
+*   ② 标题含 `--<code>--` 段（如完整目录名被截断为 `<code>-日期-概括` 前段）→
+*      按 code 段匹配：取标题首 token（`-` 前），与各目录 `--<code>--`/`--<code>` 尾段比对
+*   ③ 唯一模糊子串匹配（多个则返回 null 防误猜）
+* @param title dsh 会话标题（如 `S142-2026-08-24-概括` / `apaas-26116-…` / 完整目录名）
+* @param sessionsDir AGENT_SESSIONS 绝对路径
+* @returns 命中目录的绝对路径（SESSION.md）；无/歧义返回 null
+*/
+function resolveSessionByTitle(title, sessionsDir) {
+	const t = (title ?? "").trim();
+	if (!t) return null;
+	const all = readAllSessions(sessionsDir);
+	if (all.length === 0) return null;
+	if (isSessionDirName(t)) {
+		const exact = all.find((s) => s.dirName === t);
+		if (exact) return join(exact.path, SESSION_MD);
+	}
+	const codeToken = t.split("-")[0]?.trim() ?? "";
+	if (codeToken) {
+		const byCode = all.filter((s) => {
+			const m = s.dirName.match(/--([^--]+)--/);
+			const code = m ? m[1] : null;
+			const tailMatch = s.dirName.match(/--([^--]+)$/);
+			const tailCode = tailMatch && !s.dirName.includes("--", s.dirName.lastIndexOf("--") + 3) ? tailMatch[1] : null;
+			return code === codeToken || tailCode === codeToken || s.dirName === codeToken || s.dirName.includes(`--${codeToken}`);
+		});
+		if (byCode.length === 1) return join(byCode[0].path, SESSION_MD);
+		if (byCode.length > 1) return null;
+	}
+	const fuzzy = all.filter((s) => s.dirName.toLowerCase().includes(t.toLowerCase()));
+	if (fuzzy.length === 1) return join(fuzzy[0].path, SESSION_MD);
+	return null;
+}
+/** summary 仪表盘（供 `list` 动作拼接；v1.33 起独立 `summary` 动作已撤，并入 list） */
+function summarize(root) {
+	const sessions = readAllSessions(sessionsRoot(root));
+	if (sessions.length === 0) return "AGENT_SESSIONS/ is empty.";
+	const now = Date.now();
+	const completed = sessions.filter((s) => s.status.completed).length;
+	const active = sessions.length - completed;
+	const stale = sessions.filter((s) => !s.status.completed && (now - s.mtime.getTime()) / DAY > HEALTH_STALE_DAYS).length;
+	const ghost = sessions.filter((s) => !s.status.hasSessionMd).length;
+	const recent = sessions.slice(0, 5);
+	const lines = [
+		`AGENT_SESSIONS Summary`,
+		`────────────────────────`,
+		`Total:    ${sessions.length}`,
+		`Active:   ${active}`,
+		`Completed: ${completed}`,
+		`Stale:    ${stale}`,
+		`Ghost:    ${ghost}`,
+		``,
+		`Recent activity (top 5):`,
+		...recent.map((s) => {
+			const age = Math.floor((now - s.mtime.getTime()) / DAY);
+			return `  ${s.status.completed ? "✓" : "○"} ${s.dirName} (${age}d ago)`;
+		})
+	];
+	if (stale > 0) lines.push("", "⚠ Warning: stale trajectories present (no activity > 7d) — see the list above for detail.");
+	return lines.join("\n");
+}
+//#endregion
+export { summarize as _, extractSessionMdPathFromText as a, getLastActiveSessionInfo as c, readActiveSessionMd as d, resolveSessionByTitle as f, showSession as g, setActiveSessionInfo as h, createSession as i, listSessions as l, sessionsRoot as m, TRAJECTORY_ACTIONS as n, findSession as o, sessionEvents as p, clearActiveSessionInfo as r, getActiveSessionInfo as s, DEFAULT_SESSION_SCOPE as t, parseSessionContextFromEvents as u, useSession as v };

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

@@ -1,17 +1,28 @@
 /**
- * session-ops.ts — session 工具纯操作层（零 DSH 依赖，可独立单测）
+ * trajectory-ops.ts — 轨迹工具纯操作层（零 DSH 依赖，可独立单测）
  *
- * 行为对齐 osp（opencode-serenity-plugin/src/session/lib.ts）——osp 是 ACC 工具 spec：
- *   - create：--desc / --issue 二选一（互斥、缺省报错）；issue 模式目录 YYYY-MM-DD--<issue>
- *     （无 S###，sessionId=issue）；desc 模式 YYYY-MM-DD--S###--<desc>；goal 写入目标段；dry-run 预览
- *   - close：需 name + confirm=true；标记 [x] 已完成+已关闭 + 进度记录"关闭"
- *   - archive：name 缺省 → 批量归档（completed + ≥7 天 → 移动 _archived/）；单会话需 completed + grace
- *   - list/show/health/qa/summary：文本输出格式与 osp 一致
- * 保留 dsp S134 活跃会话机制（内存 Map + events 恢复，不落盘）——osp 同为内存 active-state。
+ * 行为对齐 osp（opencode-serenity-plugin/src/session/lib.ts）——osp 是 ACC 工具 spec。
+ *
+ * v1.33 收敛（S142 §32）：本文件只服务 `container_trajectory` 的 6 个动作
+ * （list / show / create / use / rebuild / wake-later）。旧 `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`。
+ */
+/**
+ * `container_trajectory` 工具的动作集合（v1.33，S142 §32 用户裁决后的收敛结果）。
+ *
+ * 为什么只有 6 个（R↓）：旧面是 `logbook`（11）+ `trajectory`（12）两个工具，用户裁决
+ * 「都合并成 trajectory，废除 logbook 这个词」并逐条删并 ——
+ * summary 并进 list｜health/qa 淘汰（判据＝旧模板，EAP 已取代；仅"空壳/长期无活动"并入 use）｜
+ * close/archive 删（completed 由 SESSION.md 的 `[x]` 推导；归档走 container_fs mv）｜
+ * hook-develop-guide 并进 container_admin msm guide｜autopilot 面归 container_admin 的 autopilot 域｜
+ * wake-add/list/rm 收敛为 wake-later。
  */
-import type { JsonValue } from './json.js';
-export type SessionAction = 'list' | 'show' | 'create' | 'use' | 'close' | 'health' | 'qa' | 'archive' | 'summary' | 'hook-develop-guide' | 'rebuild';
-export declare const SESSION_ACTIONS: readonly SessionAction[];
+type TrajectoryAction = 'list' | 'show' | 'create' | 'use' | 'rebuild' | 'wake-later';
+export declare const TRAJECTORY_ACTIONS: readonly TrajectoryAction[];
 /**
  * 读取 Session 事件序列（v1.28.1 适配 0.1.2-rc.1 补齐）：rc.1 起官方 Session 类
  * 移除 `.events` 属性 → `snapshotEvents()` 方法（dsh-session/src/session.ts：
@@ -26,12 +37,10 @@ export declare function sessionEvents<T = unknown>(session: unknown): readonly T
 export declare function sessionsRoot(root: string): string;
 interface SessionStatus {
     hasSessionMd: boolean;
+    /** 「完成」的判据 = SESSION.md 里出现 `[x]`（v1.33 起不再由 close 动作写入） */
     completed: boolean;
-    completedCount: number;
-    pendingCount: number;
-    unresolvedCount: number;
 }
-export interface SessionEntry {
+interface SessionEntry {
     dirName: string;
     path: string;
     mtime: Date;
@@ -46,7 +55,7 @@ export declare function findSession(sessionsDir: string, key: string): SessionEn
 export declare function listSessions(root: string, activeId?: string): string;
 /** show 子命令（对齐 osp showSession：`# dirName\n\n` + SESSION.md 内容） */
 export declare function showSession(root: string, key: string): string;
-export interface CreateSessionOptions {
+interface CreateSessionOptions {
     root: string;
     /** --desc 模式的描述（与 issue 互斥） */
     desc?: string;
@@ -61,9 +70,6 @@ export interface CreateSessionResult {
     sessionPath: string;
     sessionId: string;
 }
-/** create 子命令（对齐 osp createSession：--desc/--issue 二选一 + dry-run + 长度限制） */
-/** 目录名脱敏（Windows 审计问题 10）：非法字符 → '-', 去尾点/空格, 保留名（CON/NUL 等）加前缀 */
-export declare function sanitizeDirName(s: string): string;
 export declare function createSession(opts: CreateSessionOptions): CreateSessionResult;
 /**
  * 活动会话跟踪（S134 v1.16.14 内存化，对齐 osp active-state）：
@@ -98,11 +104,6 @@ export declare function useSession(root: string, key: string, scope?: string): {
     mdPath: string;
     context: string;
 };
-/**
- * close 子命令（对齐 osp closeSession）：需 name + confirm=true；
- * 标记 SESSION.md 为 [x] 已完成 + [x] 已关闭 + 进度记录"关闭"；清除该会话的活跃状态。
- */
-export declare function closeSession(root: string, key: string, confirm: boolean, scope?: string): string;
 /**
  * 从会话历史（events）解析会话身份（进程重启恢复；只扫**当前会话**自己的历史——无跨会话串台）。
  *
@@ -136,16 +137,6 @@ export declare function resolveSessionByTitle(title: string, sessionsDir: string
  * 只作最后手段（内存/events/锚点全缺时），保证重建锚点至少指向一个真实存在的轨迹。
  */
 export declare function findLatestActiveSessionMd(root: string): string | null;
-/** health 子命令（对齐 osp healthCheck：stale/stalled/ghost/drift 四类检查，文本输出） */
-export declare function healthCheck(root: string): string;
-/** archive 子命令（对齐 osp archiveSessions：移动 _archived/；name 缺省批量） */
-export declare function archiveSessions(root: string, opts: {
-    name?: string;
-    dryRun: boolean;
-}): string;
-/** summary 子命令（对齐 osp sessionSummary 文本仪表盘） */
+/** summary 仪表盘（供 `list` 动作拼接；v1.33 起独立 `summary` 动作已撤，并入 list） */
 export declare function summarize(root: string): string;
-/** 事实核对：SESSION.md 声明 vs 实际情况（结构/一致性/新鲜度/决策质量/产出物） */
-export declare function qaCheck(root: string, key: string): string;
-export type SessionInfo = SessionEntry;
-export type { JsonValue };
+export {};

package/lib/trajectory-skills.d.ts

@@ -0,0 +1,71 @@
+/**
+ * trajectory-skills.ts — 轨迹 skill 声明解析 + 注入内容装配（纯逻辑，零 DSH 依赖）
+ *
+ * 接口真相源：`docs/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` = **宿主接入层**
+ *     （per-agent `ctx.systemPrompt.section`），只做门与注册，不再解析文本。
+ *
+ * 边界（规格 §2.2）：**不解析** `skills` 以外任何键的语义（CCC 可自由使用，ACC 视而不见）；
+ * **不改写** frontmatter（ACC 只读）。
+ */
+/** 全文注入总长上限（字符数；规格 §3「缺省 32 KB」——防上下文爆炸） */
+export declare const TRAJECTORY_SKILLS_MAX_CHARS: number;
+/** 缺失标记（规格 §3/§6-3 的验收锚点：任何"拿不到全文"的情况都必须带它，绝不静默） */
+export declare const SKILL_MISSING_MARK = "[\u7F3A\u5931]";
+/**
+ * 抽取文件顶部 YAML frontmatter 区（规格 §2.1）。
+ *
+ * 规则：**第一行必须是 `---`**；到下一个 `---` 行为止是 frontmatter 区。
+ * 首行不是 `---`，或没有闭合 `---` ⇒ 视为**无 frontmatter**（返回 null）。
+ * 边界判断（R↓）：未闭合块按"无 frontmatter"处理而非吞掉整个文件——半个声明块是格式错误，
+ * 猜它的意图等于把坏数据当好消息（宁可零注入，也不注入来路不明的半截列表）。
+ *
+ * @param content SESSION.md 全文
+ * @returns frontmatter 区各行（不含两条 `---` 定界行）；无 → null
+ */
+export declare function extractFrontmatter(content: string): string[] | null;
+/**
+ * 解析声明（规格 §2.1，**最小实现，不引 YAML 依赖**）。
+ *
+ * 只认 `skills:` 键；未知键一律忽略（向前兼容，不报错）。两种值形态都支持：
+ *   ① 行内数组 `skills: [home-rhetoric, acc-eap]`
+ *   ② 缩进列表（`skills:` 后各起一行 `  - a`）
+ * 名字：去首尾空白、空项丢弃、**保持书写顺序**（注入顺序 = 书写顺序）、同名去重（保留首次位置）。
+ *
+ * 未定义形态（不在规格的两种值形态内，如 `skills: a` 裸标量）⇒ **视为无声明**：
+ * 本函数只认契约里写明的两种形态，猜第三种等于自造契约（规格 §2.1 只列了 ①②）。
+ *
+ * @param sessionMd SESSION.md 全文
+ * @returns 声明的 skill 名（按书写顺序去重）；无 frontmatter / 无 `skills` 键 / 值为空 → `[]`
+ */
+export declare function parseDeclaredSkills(sessionMd: string): string[];
+/**
+ * 注册门（规格 §3「无绑定 / 无声明 ⇒ 完全不注册该 section」）。
+ *
+ * 返回 true 的两种情况：
+ *   · 文件在且**有非空声明** → 注册（有内容可注入）
+ *   · 文件**不在 / 读不到** → 同样注册——此时 section 文本是响亮的 `[缺失]` 提示
+ *     （规格 §6-6 要求"不静默"；不注册就等于静默）
+ * 其余（文件在但无 frontmatter / 无 `skills` 键 / 值为空）⇒ false，不注册、不产生噪声。
+ */
+export declare function hasTrajectorySkillsDeclaration(root: string, mdPath: string): boolean;
+/**
+ * 装配注入正文（规格 §3）：按声明顺序拼接各 skill 的 `SKILL.md` 全文，每段带来源抬头
+ * `=== skill: <name> ===`；拿不到全文的一律以 `[缺失]` 响亮提示占位（**不静默**）。
+ *
+ * 安全（规格 §3 🔒）：名字来自 CCC 数据（frontmatter）⇒ **先过 `isSafeSkillName`**；
+ * 不安全 ⇒ 按缺失处理，且不调用 `findSkillMd` ⇒ **不发生任何以该名拼出的 fs 访问**。
+ *
+ * 长度守卫：复用已导出的 `truncateContent`，超限截断并在末尾写明 `truncated`。
+ *
+ * @param root CCC 根
+ * @param mdPath 轨迹的 SESSION.md 路径（**来自绑定的 `mdPath`**，不用 label 拼）
+ * @param maxChars 总长上限（字符）
+ * @returns 注入正文；无声明 → `''`（空串 = 宿主不产出该 section 块）；SESSION.md 缺失 → 响亮提示
+ */
+export declare function buildTrajectorySkillsSection(root: string, mdPath: string, maxChars?: number): string;