@shgroup/dsh-serenity-hooks 1.29.0 → 1.29.1

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.29.0",
+  "version": "1.29.1",
   "main": "lib/index.js",
   "description": "宁静号 ACC harness（Native Cordis 插件）：真实 DSH 工具 cc_fs/session/acc_msm/eap/neat/cce/handyman/session_rebuild/skiff_admin + 拦截缝机械约束（safe-mode/路径守卫）+ 高级设定面板（双端口网关/账号管理）+ Skiff 认知子集角色（实验性）。适配 DSH 公开版（0.1.0-rc，deepseek-ai/deepseek-harness）。",
   "engines": {

package/lib/index.js

@@ -2919,6 +2919,43 @@ 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;
+}
+/**
 * 约定回退（v1.24.11）：AGENT_SESSIONS 下最新修改的**未完成**会话的 SESSION.md。
 * readAllSessions 已按「未完成优先 + mtime 降序」排序 → 首个未完成且含 SESSION.md 即最新活动。
 * 只作最后手段（内存/events/锚点全缺时），保证重建锚点至少指向一个真实存在的轨迹。
@@ -3179,6 +3216,56 @@ function qaCheck(root, key) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/session-bound.ts
+/** 事件 type 常量（声明 + 读取共用） */
+const SESSION_BOUND_EVENT = "serenity/bound";
+/** 事件形状归一（运行时数据经 session.append 深冻结，此处仅类型收窄） */
+function asBoundEvent(e) {
+	const ev = e;
+	if (!ev || ev.type !== "serenity/bound") return null;
+	const d = ev.data;
+	if (!d || typeof d.dirName !== "string" || typeof d.mdPath !== "string") return null;
+	return d;
+}
+/**
+* 读取会话日志中**最后一条** `serenity/bound`（权威绑定，latest-wins）。
+* 尾到头扫描（时间序最新在后）；无 bound 事件返回 null。
+* 纯逻辑零 DSH 依赖（经 sessionEvents helper 读 snapshotEvents/events 兜底）。
+*/
+function readLastBound(session) {
+	const events = sessionEvents(session);
+	for (let i = events.length - 1; i >= 0; i--) {
+		const b = asBoundEvent(events[i]);
+		if (b) return b;
+	}
+	return null;
+}
+/**
+* append 一条 `serenity/bound` 绑定事件（log-only，无 surfaceOp——元数据不进模型可见面）。
+* @param session 目标 dsh 会话（真实 Session；append 泛型经内部断言兼容——类型由
+*   `serenity/bound` 声明面保证，append 接受已声明事件）
+* @param action 绑定动作
+* @param rec 绑定记录（dirName + mdPath 必填；sessionId 可选展示码）
+* @returns 是否成功（append 抛错/会话不可用时 false——绑定失败不阻断主流程）
+*/
+function appendBound(session, action, rec) {
+	if (!session || typeof session.append !== "function") return false;
+	try {
+		const append = session.append;
+		append(SESSION_BOUND_EVENT, {
+			dirName: rec.dirName,
+			mdPath: rec.mdPath,
+			...rec.sessionId ? { sessionId: rec.sessionId } : {},
+			action,
+			at: Date.now(),
+			...rec.note ? { note: rec.note } : {}
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/tools/session.ts
 /**
 * session.ts — session 真实 DSH 工具定义（defineTool）
@@ -3203,6 +3290,21 @@ function agentCwd$5(exec) {
 function agentScope$2(exec) {
 	return exec.agent?.session?.id ?? "default";
 }
+/** 当前 dsh 会话对象（append bound 用）；无 → null */
+function agentDshSession(exec) {
+	const s = exec.agent?.session;
+	return s && typeof s.append === "function" ? { append: s.append } : null;
+}
+/**
+* 当前绑定的权威 dirName（优先持久化 bound——防内存被误 use 污染；无 bound 回退内存 active）。
+* 供 G1 守卫对比目标会话是否切换。
+*/
+function currentBoundDirName(exec, scope) {
+	const dsh = agentDshSession(exec);
+	const bound = dsh ? readLastBound(dsh) : null;
+	if (bound) return bound.dirName;
+	return getActiveSessionInfo(scope)?.dirName ?? null;
+}
 /**
 * 清洗 + 截断会话概括（需求② S142 用户拍板：编号日期后加 ≤20 字内容概括）。
 * 规则（服务端统一，不信任 LLM 输入）：
@@ -3275,18 +3377,6 @@ function renameDshSessionOnUse(deps, session, titles, active, summary) {
 	}
 }
 /**
-* 从 create 结果构造命名用 ActiveSessionInfo（v1.25.11，S142 用户：create 也要命名）：
-* createSession 返回的 result 已含 sessionId（S###/issue）与 dirName——无需等待 use 激活，
-* 直接构造（mdPath = sessionPath/SESSION.md，与 use 时一致）即可驱动 renameDshSessionOnUse。
-*/
-function activeInfoFromCreate(result) {
-	return {
-		sessionId: result.sessionId,
-		dirName: result.dirName,
-		mdPath: join(result.sessionPath, "SESSION.md")
-	};
-}
-/**
 * 把当前 dsh 会话重命名为指定 SESSION 的命名标题（use/create 共用；v1.25.11）。
 * 需求②：summary 参数（≤20 字概括）透传——标题带概括（编号日期固定派生）。
 * 门控/失败可见性与 renameDshSessionOnUse 一致（不静默：成功 log / 失败 warn）。
@@ -3440,6 +3530,10 @@ function createSessionTool(ctx) {
 				type: "boolean",
 				description: "close must be true (prevents accidental close)"
 			},
+			force: {
+				type: "boolean",
+				description: "use: allow switching away from the currently-bound session (binding guard override)"
+			},
 			dryRun: {
 				type: "boolean",
 				description: "create/archive preview mode (no actual changes)"
@@ -3474,7 +3568,12 @@ function createSessionTool(ctx) {
 						dryRun: isDryRun
 					});
 					let message = result.message;
-					if (!isDryRun) renameDshSessionForActive(ctx, exec, activeInfoFromCreate(result), args.summary ?? args.issue);
+					if (!isDryRun) appendBound(agentDshSession(exec), "create", {
+						dirName: result.dirName,
+						mdPath: join(result.sessionPath, "SESSION.md"),
+						sessionId: result.sessionId,
+						note: "created (binding unchanged until explicit use)"
+					});
 					if (!isDryRun && cccHooks.includes("create-transform")) try {
 						const hookResult = await runMsmAsync(root, {
 							action: "exec",
@@ -3492,14 +3591,47 @@ function createSessionTool(ctx) {
 					if (!args.name) throw new Error("use requires name (S### or directory name)");
 					if (!args.summary || args.summary.trim() === "") throw new Error("use requires --summary <content summary ≤20 chars> (appended to the dsh session title as S###-YYYY-MM-DD-<summary>; id and date stay server-derived)");
 					const scope = agentScope$2(exec);
+					const targetEntry = findSession(join(root, "AGENT_SESSIONS"), args.name);
+					if (!targetEntry) throw new Error(`Session not found: "${args.name}". Use "list" to see available sessions.`);
+					const targetDirName = targetEntry.dirName;
+					const currentDir = currentBoundDirName(exec, scope);
+					const switching = currentDir !== null && targetDirName !== currentDir;
+					const force = args.force === true;
+					if (switching && !force) throw new Error(`Session is bound to ${currentDir}. Switching to ${targetDirName} would orphan the current trajectory. Re-run with --force to switch (or close the current session first).`);
 					const active = useSession(root, args.name, scope);
 					const info = getActiveSessionInfo(scope);
 					if (info) renameDshSessionForActive(ctx, exec, info, args.summary);
+					const dsh = agentDshSession(exec);
+					if (dsh && info) {
+						const prevBound = readLastBound(dsh);
+						appendBound(dsh, switching && prevBound ? "switch" : "activate", {
+							dirName: info.dirName,
+							mdPath: info.mdPath,
+							sessionId: info.sessionId,
+							...switching ? { note: "forced switch" } : {}
+						});
+					}
 					return active;
 				}
-				case "close":
-					if (!args.name) throw new Error("close requires name (S### or directory name)");
-					return closeSession(root, args.name, args.confirm ?? false, agentScope$2(exec));
+				case "close": {
+					const scope = agentScope$2(exec);
+					const requested = args.name?.trim() ?? "";
+					const boundDir = currentBoundDirName(exec, scope);
+					if (boundDir && requested) {
+						if ((findSession(join(root, "AGENT_SESSIONS"), requested)?.dirName ?? requested) !== boundDir) throw new Error(`Session is bound to ${boundDir}. close targets the bound session — pass the bound session (or omit name) to close it; closing ${requested} while bound to another session is not allowed.`);
+					}
+					if (!boundDir && !requested) throw new Error("close requires name (no active binding to close) — pass the session to close.");
+					const closed = closeSession(root, boundDir ? boundDir : requested, args.confirm ?? false, scope);
+					const dsh = agentDshSession(exec);
+					const bound = dsh ? readLastBound(dsh) : null;
+					if (bound) appendBound(dsh, "release", {
+						dirName: bound.dirName,
+						mdPath: bound.mdPath,
+						sessionId: bound.sessionId,
+						note: "session closed"
+					});
+					return closed;
+				}
 				case "archive": return archiveSessions(root, {
 					name: args.name,
 					dryRun: args.dryRun ?? false
@@ -3988,7 +4120,14 @@ async function queueRebuild(ctx, opts) {
 	if (!session) throw new Error(`Unable to locate dsh session ${dshSessionId} (session may be closed)`);
 	const mdPath = resolveSessionMdPath(root, dshSessionId, session);
 	if (!mdPath) throw new Error("Unable to determine the active SESSION.md — no session context found in this conversation. Run \"session use <S###> --summary <内容概括 ≤20 字>\" first to activate the trajectory to resume, then retry session_rebuild.");
-	const anchor = buildRebuildAnchor(root, getActiveSessionInfo(dshSessionId)?.sessionId ?? sessionNameFromMdPath(mdPath), mdPath);
+	const sessionName = getActiveSessionInfo(dshSessionId)?.sessionId ?? sessionNameFromMdPath(mdPath);
+	const anchor = buildRebuildAnchor(root, sessionName, mdPath);
+	appendBound(session, "rebuild", {
+		dirName: basename(dirname(mdPath)),
+		mdPath,
+		sessionId: sessionName.startsWith("S") ? sessionName : void 0,
+		note: "rebuild queued"
+	});
 	pendingRebuilds.set(dshSessionId, {
 		anchor,
 		summary,
@@ -6281,6 +6420,17 @@ function registerEntrySkillSection(agent, root) {
 //#endregion
 //#region src/seams/context.ts
 const DEFAULT_ENTRY_SKILL_MAX_CHARS = 3e4;
+/** 从 dsh 会话日志读标题（latest-wins `session/title` 事件；无返回 null）——供标题 reconcile（U3） */
+function readDshSessionTitle(session) {
+	try {
+		const events = sessionEvents(session);
+		for (let i = events.length - 1; i >= 0; i--) {
+			const e = events[i];
+			if (e?.type === "session/title" && typeof e.data?.title === "string" && e.data.title.trim() !== "") return e.data.title.trim();
+		}
+	} catch {}
+	return null;
+}
 function accIdentityText(root, configPaths = DEFAULT_SERENITY_CONFIG_PATHS, entrySkillMaxChars = DEFAULT_ENTRY_SKILL_MAX_CHARS) {
 	loadSerenityConfig(root, configPaths);
 	const defaultModel = readHandymanConfig(root, configPaths)?.defaultModel;
@@ -6368,17 +6518,56 @@ function registerContext(ctx, opts = {}) {
 		const scope = agentScope(agent);
 		if (shouldRestoreActive(agent) && getActiveSessionInfo(scope) === null) try {
 			if (loadSerenityConfig(root, configPaths).hooks?.autoRestoreSession ?? true) {
-				const info = parseSessionContextFromEvents(sessionEvents(agent.session));
-				if (info) {
-					const abs = info.mdPath.startsWith(root) ? info.mdPath : resolve(root, info.mdPath);
-					if (existsSync(abs)) {
-						setActiveSessionInfo(scope, {
-							...info,
-							mdPath: abs
-						});
-						console.log(`[serenity-hooks] ↻ 从历史恢复激活会话: ${info.dirName}`);
+				const dshSession = agent.session;
+				let restored = null;
+				const bound = readLastBound(dshSession);
+				if (bound) {
+					const abs = bound.mdPath.startsWith(root) ? bound.mdPath : resolve(root, bound.mdPath);
+					if (existsSync(abs)) restored = {
+						dirName: bound.dirName,
+						mdPath: abs,
+						sessionId: bound.sessionId
+					};
+				}
+				if (!restored) {
+					const info = parseSessionContextFromEvents(sessionEvents(dshSession));
+					if (info) {
+						const abs = info.mdPath.startsWith(root) ? info.mdPath : resolve(root, info.mdPath);
+						if (existsSync(abs)) restored = {
+							dirName: info.dirName,
+							mdPath: abs,
+							sessionId: info.sessionId
+						};
 					}
 				}
+				if (!restored) {
+					const title = readDshSessionTitle(dshSession);
+					if (title) {
+						const md = resolveSessionByTitle(title, sessionsRoot(root));
+						if (md && existsSync(md)) {
+							const dirName = basename(dirname(md));
+							restored = {
+								dirName,
+								mdPath: md,
+								sessionId: void 0
+							};
+							appendBound(dshSession, "reconcile", {
+								dirName,
+								mdPath: md,
+								note: "auto from title"
+							});
+							console.log(`[serenity-hooks] ↻ 标题兼容持久化绑定: ${title} → ${dirName}`);
+						}
+					}
+				}
+				if (restored) {
+					const derived = restored.sessionId ?? (restored.dirName.match(/--([^--]+)--/) ? restored.dirName.match(/--([^--]+)--/)[1] : void 0) ?? restored.dirName;
+					setActiveSessionInfo(scope, {
+						...restored,
+						sessionId: derived
+					});
+					console.log(`[serenity-hooks] ↻ 从历史恢复激活会话: ${restored.dirName}`);
+				}
 			}
 		} catch {}
 		if (injected.has(key)) return;

package/lib/seams/context.d.ts

@@ -13,6 +13,8 @@ import type { Context } from 'cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { UserMessage } from '@deepseek-ai/dsh-session';
 export declare const DEFAULT_ENTRY_SKILL_MAX_CHARS = 30000;
+/** 从 dsh 会话日志读标题（latest-wins `session/title` 事件；无返回 null）——供标题 reconcile（U3） */
+export declare function readDshSessionTitle(session: unknown): string | null;
 export declare function accIdentityText(root: string, configPaths?: string[], entrySkillMaxChars?: number): string;
 /**
  * ACC 注入消息（S134 去重）：**只含简短身份锚点**（[ACC] 已激活 + CCC 根 + 约束 + handyman 模型 + Phase 2）。

package/lib/session-bound.d.ts

@@ -0,0 +1,80 @@
+/**
+ * session-bound.ts — SESSION 绑定持久化（serenity/bound 会话事件）
+ *
+ * 目标（S142 用户拍板，方案 v1.0）：让「dsh 会话（载体）↔ SESSION（宁静号轨迹）」
+ * 的绑定坚固——LLM 不能因智力因素（幻觉/理解偏差）在过程中或 session_rebuild 后
+ * 自行更换 SESSION。
+ *
+ * 机制（DSH 原生，零改 harness）：
+ *   `SessionEventMap` 是 merge-extensible（先例：dsh-compaction 扩展 compaction/*；
+ *   dsp 已在 append compaction/prune）——插件可 declare module 自定义事件，
+ *   `Session.append(type, data)` 将其写入会话 append-only 日志，随 session.jsonl
+ *   持久化落盘，进程重启后 snapshotEvents() 可完整读取。
+ *
+ * 权威绑定 = 会话日志中**最后一条** `serenity/bound`（append-only latest-wins）。
+ * 本事件是 log-only 元数据（无 surfaceOp——永不上模型可见面，不进系统提示词）。
+ *
+ * 编码无关（U4）：绑定锚 = **完整 AGENT_SESSIONS 目录名**（磁盘唯一存在），
+ * sessionId（S###/apaas-xxx/自定义）仅是派生展示字段——绝不假设 S 前缀。
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionEventMap } from '@deepseek-ai/dsh-session/types';
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * Serenity SESSION binding — authoritative; appended on every binding change.
+         * Code-agnostic (keyed by full dir name), log-only (no surfaceOp).
+         */
+        'serenity/bound': {
+            /** Full AGENT_SESSIONS dir name — the ONLY hard identity. */
+            dirName: string;
+            /** SESSION.md absolute path. */
+            mdPath: string;
+            /** Display code when parseable (S142 / apaas-26116 / custom); informational. */
+            sessionId?: string;
+            /** Why this binding record was written. */
+            action: 'activate' | 'switch' | 'create' | 'rebuild' | 'reconcile' | 'release';
+            /** Epoch ms. */
+            at: number;
+            /** Optional reason (e.g. 'auto from title'). */
+            note?: string;
+        };
+    }
+}
+export type SessionBoundAction = SessionEventMap['serenity/bound']['action'];
+export interface SessionBoundRecord {
+    dirName: string;
+    mdPath: string;
+    sessionId?: string;
+    action: SessionBoundAction;
+    at: number;
+    note?: string;
+}
+/** 事件 type 常量（声明 + 读取共用） */
+export declare const SESSION_BOUND_EVENT: "serenity/bound";
+/**
+ * 读取会话日志中**最后一条** `serenity/bound`（权威绑定，latest-wins）。
+ * 尾到头扫描（时间序最新在后）；无 bound 事件返回 null。
+ * 纯逻辑零 DSH 依赖（经 sessionEvents helper 读 snapshotEvents/events 兜底）。
+ */
+export declare function readLastBound(session: unknown): SessionBoundRecord | null;
+/**
+ * 判定会话日志是否已有任何 bound 事件（供 reconcile 判定：无绑定才标题升级）。
+ */
+export declare function hasAnyBound(session: unknown): boolean;
+/**
+ * append 一条 `serenity/bound` 绑定事件（log-only，无 surfaceOp——元数据不进模型可见面）。
+ * @param session 目标 dsh 会话（真实 Session；append 泛型经内部断言兼容——类型由
+ *   `serenity/bound` 声明面保证，append 接受已声明事件）
+ * @param action 绑定动作
+ * @param rec 绑定记录（dirName + mdPath 必填；sessionId 可选展示码）
+ * @returns 是否成功（append 抛错/会话不可用时 false——绑定失败不阻断主流程）
+ */
+export declare function appendBound(session: Session | {
+    append: (type: string, data: unknown) => unknown;
+} | null | undefined, action: SessionBoundAction, rec: {
+    dirName: string;
+    mdPath: string;
+    sessionId?: string;
+    note?: string;
+}): boolean;

package/lib/session-ops.d.ts

@@ -117,6 +117,19 @@ export declare function parseSessionContextFromEvents(events: readonly unknown[]
 /** 从文本提取 SESSION.md 路径（use 上下文 / 重建锚点规范行通用；无匹配返回 null）。
  *  同行已知尾注（如系统提示词 Session 块的 persistent-body 注释）剥除——规范行只取路径本体。 */
 export declare function extractSessionMdPathFromText(text: string): string | null;
+/**
+ * 从 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
+ */
+export declare function resolveSessionByTitle(title: string, sessionsDir: string): string | null;
 /**
  * 约定回退（v1.24.11）：AGENT_SESSIONS 下最新修改的**未完成**会话的 SESSION.md。
  * readAllSessions 已按「未完成优先 + mtime 降序」排序 → 首个未完成且含 SESSION.md 即最新活动。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shgroup/dsh-serenity-hooks",
-  "version": "1.29.0",
+  "version": "1.29.1",
   "description": "宁静号 ACC harness — Native Cordis 插件（DeepSeek Harness 运行时）。真实 DSH 工具注册（cc_fs/session/acc_msm 等 9 工具）+ 拦截缝机械约束（safe-mode/路径守卫/会话落盘）+ 系统提示词注入（ACC/CCE/Constraints/SKILL/Session 五块）。适配 DSH 公开版（deepseek-ai/deepseek-harness 0.1.0-rc）。",
   "license": "MIT",
   "repository": {