@shgroup/dsh-serenity-hooks 1.16.13 → 1.17.0

package/lib/index.js

@@ -1,6 +1,6 @@
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
 import { homedir, platform } from "node:os";
@@ -104,8 +104,13 @@ function matchBlacklist(relPath, rules) {
 /**
 * fs-ops.ts — cc_fs 纯操作层（零 DSH 依赖，可独立单测）
 *
-* 移植自 dsh-serenity-plugin v0.1 acc-fs runner（本项目自有代码）。
-* 每个操作返回规范 JSON 值（由工具层 render 成模型可见文本）。
+* 行为对齐 osp（opencode-serenity-plugin/src/fs/file-system-tool.ts）——osp 是 ACC 工具 spec：
+*   - rm：目录需 recursive 才删除；非空目录无 recursive → [SKIP]；保护 .serenity 与 CCC 根；dry-run 预览
+*   - cp：目录需 recursive；dst 已存在报错；自动建父目录
+*   - mv：dst 已存在报错；自动建父目录
+*   - list/tree/exists/info/find：输出结构与 osp 一致（JSON 元数据 / 嵌套树 / glob+fuzzy 搜索）
+*   - touch：存在更新 mtime、不存在创建（自动建父目录）；append：自动建父目录 + 返回字节数
+* 保留 dsp 增强：win32 reveal 用 spawn+unref（explorer GUI 进程退出码不可靠，fire-and-forget）。
 */
 const CC_FS_ACTIONS = [
 	"root",
@@ -124,9 +129,50 @@ const CC_FS_ACTIONS = [
 	"info",
 	"find"
 ];
+function detectFileType(stat) {
+	if (stat.isDirectory()) return "dir";
+	if (stat.isFile()) return "file";
+	if (stat.isSymbolicLink()) return "symlink";
+	return "other";
+}
+function humanSize(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / 1048576).toFixed(1)} MB`;
+}
+function getFileInfo(absPath, name) {
+	try {
+		const stat = statSync(absPath);
+		return {
+			name,
+			type: detectFileType(stat),
+			size: stat.size,
+			sizeHuman: humanSize(stat.size),
+			mtime: stat.mtime.toISOString()
+		};
+	} catch {
+		return {
+			name,
+			type: "other",
+			size: 0,
+			sizeHuman: "?",
+			mtime: "?"
+		};
+	}
+}
 function safeRel(root, abs) {
 	return relative(root, abs) || ".";
 }
+function validateWritePath(root, target) {
+	const absPath = target.startsWith("/") ? resolve(target) : resolveInside(root, target);
+	if (target.startsWith("/") && !absPath.startsWith(root)) throw new Error(`cc-fs: path "${target}" resolves to "${absPath}" which is outside serenity root "${root}"`);
+	if (absPath.endsWith("/mech-registry.json") && absPath.includes("/.opencode/skills/")) throw new Error(`cc-fs: refusing to directly modify mech-registry.json — use acc_msm register/deregister instead`);
+	return absPath;
+}
+function assertNotProtected(root, absPath, targetLabel) {
+	if (absPath === resolve(root, ".serenity")) throw new Error(`cc-fs: refusing to delete protected path: ${targetLabel} (.serenity is the CCC marker)`);
+	if (absPath === root) throw new Error(`cc-fs: refusing to delete the CCC root directory: ${targetLabel}`);
+}
 function runCcFs(root, args) {
 	const a = args.action;
 	switch (a) {
@@ -134,118 +180,177 @@ function runCcFs(root, args) {
 		case "resolve":
 			if (!args.path) throw new Error("resolve 需要 path");
 			return resolveInside(root, args.path);
-		case "exists":
+		case "exists": {
 			if (!args.path) throw new Error("exists 需要 path");
-			return existsSync(resolveInside(root, args.path));
+			const absPath = args.path.startsWith("/") ? resolve(args.path) : resolveInside(root, args.path);
+			return existsSync(absPath) ? "true" : "false";
+		}
 		case "list": {
-			const dir = args.path ? resolveInside(root, args.path) : root;
-			if (!existsSync(dir)) throw new Error(`no such dir: ${dir}`);
-			return readdirSync(dir, { withFileTypes: true }).map((e) => ({
-				name: e.name,
-				type: e.isDirectory() ? "dir" : e.isFile() ? "file" : "other"
-			}));
+			const relPath = args.path || ".";
+			const absPath = relPath.startsWith("/") ? resolve(relPath) : resolveInside(root, relPath);
+			if (!existsSync(absPath)) throw new Error(`list: path "${absPath}" does not exist`);
+			const entries = readdirSync(absPath).sort().map((name) => getFileInfo(join(absPath, name), name));
+			return {
+				path: absPath,
+				entries,
+				count: entries.length
+			};
 		}
 		case "tree": {
-			const dir = args.path ? resolveInside(root, args.path) : root;
-			const maxDepth = args.depth ?? Infinity;
-			if (!existsSync(dir)) throw new Error(`no such dir: ${dir}`);
-			const out = [];
-			const walk = (cur, depth) => {
-				if (depth > maxDepth) return;
-				for (const e of readdirSync(cur, { withFileTypes: true })) {
-					const full = join(cur, e.name);
-					out.push({
-						path: safeRel(root, full),
-						type: e.isDirectory() ? "dir" : "file"
-					});
-					if (e.isDirectory()) walk(full, depth + 1);
+			const relPath = args.path || ".";
+			const absPath = relPath.startsWith("/") ? resolve(relPath) : resolveInside(root, relPath);
+			if (!existsSync(absPath)) throw new Error(`tree: path "${absPath}" does not exist`);
+			const maxDepth = args.depth ?? 3;
+			const filesOnly = args.filesOnly ?? false;
+			const dirsOnly = args.dirsOnly ?? false;
+			if (filesOnly && dirsOnly) throw new Error("tree: files-only and dirs-only are mutually exclusive");
+			const filterTree = (entries, keepType) => entries.filter((e) => {
+				if (e.type === keepType) {
+					if (e.children) e.children = filterTree(e.children, keepType);
+					return true;
 				}
+				return false;
+			});
+			const walk = (dir, currentDepth) => {
+				if (currentDepth > maxDepth) return [];
+				return readdirSync(dir).sort().map((name) => {
+					const full = join(dir, name);
+					const stat = statSync(full);
+					const entry = {
+						name,
+						type: detectFileType(stat),
+						size: stat.size,
+						sizeHuman: humanSize(stat.size)
+					};
+					if (stat.isDirectory()) entry.children = walk(full, currentDepth + 1);
+					return entry;
+				});
+			};
+			let entries = walk(absPath, 1);
+			if (filesOnly) entries = filterTree(entries, "file");
+			if (dirsOnly) entries = filterTree(entries, "dir");
+			return {
+				path: absPath,
+				entries,
+				maxDepth
 			};
-			walk(dir, 0);
-			return out;
 		}
-		case "relative":
+		case "relative": {
 			if (!args.path) throw new Error("relative 需要 path");
-			return safeRel(root, resolveInside(root, args.path));
+			const absPath = args.path.startsWith("/") ? resolve(args.path) : resolveInside(root, args.path);
+			if (!absPath.startsWith(root)) throw new Error(`relative: path "${args.path}" resolves to "${absPath}" which is outside serenity root "${root}"`);
+			return safeRel(root, absPath);
+		}
 		case "mkdir": {
-			const targets = args.paths?.length ? args.paths : args.path ? [args.path] : [];
-			if (targets.length === 0) throw new Error("mkdir 需要 path(s)");
-			for (const t of targets) mkdirSync(resolveInside(root, t), { recursive: true });
-			return {
-				ok: true,
-				created: targets
-			};
+			if (!args.path) throw new Error("mkdir 需要 path");
+			const absPath = validateWritePath(root, args.path);
+			if (existsSync(absPath)) {
+				if (statSync(absPath).isDirectory()) return `directory already exists: ${args.path}`;
+				throw new Error(`mkdir: path "${args.path}" exists but is not a directory`);
+			}
+			mkdirSync(absPath, { recursive: true });
+			return `created directory: ${args.path}`;
 		}
 		case "rm": {
-			const targets = args.paths?.length ? args.paths : args.path ? [args.path] : [];
-			if (targets.length === 0) throw new Error("rm 需要 path(s)");
-			const removed = [];
-			for (const t of targets) {
-				const abs = resolveInside(root, t);
-				if (abs === root) throw new Error("拒绝删除 CCC 根本身");
-				if (!existsSync(abs)) continue;
-				if (args.dryRun) {
-					removed.push(`${t} [dry-run]`);
+			const targets = [...args.paths ?? []];
+			if (args.path) targets.push(args.path);
+			if (targets.length === 0) throw new Error("rm 需要至少一个 path 参数（path 或 paths）");
+			const dryRun = args.dryRun ?? false;
+			const recursive = args.recursive ?? false;
+			const results = [];
+			for (const target of targets) {
+				const absPath = validateWritePath(root, target);
+				if (!existsSync(absPath)) {
+					results.push(`[SKIP] not found: ${target}`);
+					continue;
+				}
+				const isDir = statSync(absPath).isDirectory();
+				try {
+					assertNotProtected(root, absPath, target);
+				} catch (e) {
+					results.push(`[SKIP] ${e.message}`);
+					continue;
+				}
+				const relLabel = safeRel(root, absPath);
+				if (dryRun) {
+					const extra = isDir ? recursive ? " (recursive)" : "" : "";
+					results.push(`[DRY-RUN] ${isDir ? "directory" : "file"}: ${relLabel}${extra}`);
 					continue;
 				}
-				rmSync(abs, {
+				if (isDir && !recursive) {
+					const entries = readdirSync(absPath);
+					if (entries.length > 0) {
+						results.push(`[SKIP] directory not empty (${entries.length} items), use recursive: ${relLabel}`);
+						continue;
+					}
+					rmdirSync(absPath);
+				} else if (isDir) rmSync(absPath, {
 					recursive: true,
-					force: true
+					force: false
 				});
-				removed.push(t);
+				else unlinkSync(absPath);
+				results.push(`[OK] deleted: ${relLabel}`);
 			}
-			return {
-				ok: true,
-				removed
-			};
+			return results.join("\n");
 		}
-		case "mv":
+		case "mv": {
 			if (!args.src || !args.dst) throw new Error("mv 需要 src + dst");
-			renameSync(resolveInside(root, args.src), resolveInside(root, args.dst));
-			return {
-				ok: true,
-				from: args.src,
-				to: args.dst
-			};
-		case "cp":
+			const srcAbs = validateWritePath(root, args.src);
+			const dstAbs = validateWritePath(root, args.dst);
+			if (!existsSync(srcAbs)) throw new Error(`mv: source not found: ${args.src}`);
+			if (existsSync(dstAbs)) throw new Error(`mv: destination already exists: ${args.dst}`);
+			const parentDir = dirname(dstAbs);
+			if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
+			renameSync(srcAbs, dstAbs);
+			return `moved: ${args.src} → ${args.dst}`;
+		}
+		case "cp": {
 			if (!args.src || !args.dst) throw new Error("cp 需要 src + dst");
-			cpSync(resolveInside(root, args.src), resolveInside(root, args.dst), { recursive: true });
-			return {
-				ok: true,
-				from: args.src,
-				to: args.dst
-			};
+			const srcAbs = validateWritePath(root, args.src);
+			const dstAbs = validateWritePath(root, args.dst);
+			if (!existsSync(srcAbs)) throw new Error(`cp: source not found: ${args.src}`);
+			if (existsSync(dstAbs)) throw new Error(`cp: destination already exists: ${args.dst}`);
+			if (statSync(srcAbs).isDirectory() && !(args.recursive ?? false)) throw new Error(`cp: source is a directory, use recursive to copy: ${args.src}`);
+			const parentDir = dirname(dstAbs);
+			if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
+			cpSync(srcAbs, dstAbs, { recursive: args.recursive ?? false });
+			return `copied: ${args.src} → ${args.dst}`;
+		}
 		case "touch": {
 			if (!args.path) throw new Error("touch 需要 path");
-			const abs = resolveInside(root, args.path);
-			if (!existsSync(abs)) writeFileSync(abs, "", "utf-8");
-			return {
-				ok: true,
-				path: safeRel(root, abs)
-			};
+			const absPath = validateWritePath(root, args.path);
+			if (existsSync(absPath)) {
+				const now = /* @__PURE__ */ new Date();
+				utimesSync(absPath, now, now);
+				return `updated timestamp: ${args.path}`;
+			}
+			const parentDir = dirname(absPath);
+			if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
+			writeFileSync(absPath, "", "utf-8");
+			return `created empty file: ${args.path}`;
 		}
 		case "append": {
 			if (!args.path || args.content === void 0) throw new Error("append 需要 path + content");
-			const abs = resolveInside(root, args.path);
-			appendFileSync(abs, args.content, "utf-8");
-			return {
-				ok: true,
-				path: safeRel(root, abs)
-			};
+			const absPath = validateWritePath(root, args.path);
+			const parentDir = dirname(absPath);
+			if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
+			const content = args.content;
+			appendFileSync(absPath, content, "utf-8");
+			return `appended ${Buffer.byteLength(content, "utf8")} bytes to ${args.path}`;
 		}
 		case "reveal": {
 			if (!args.path) throw new Error("reveal 需要 path");
-			const abs = resolveInside(root, args.path);
-			if (!existsSync(abs)) throw new Error(`no such path: ${abs}`);
+			const absPath = resolveInside(root, args.path);
+			if (!existsSync(absPath)) throw new Error(`no such path: ${absPath}`);
 			const os = platform();
 			try {
-				if (os === "darwin") execFileSync("open", ["-R", abs], { timeout: 1e4 });
+				if (os === "darwin") execFileSync("open", ["-R", absPath], { timeout: 1e4 });
 				else if (os === "linux") {
-					const revealPath = statSync(abs).isDirectory() ? abs : dirname(abs);
+					const revealPath = statSync(absPath).isDirectory() ? absPath : dirname(absPath);
 					execFileSync("xdg-open", [revealPath], { timeout: 1e4 });
 				} else if (os === "win32") {
-					const args = statSync(abs).isDirectory() ? [abs] : ["/select,", abs];
-					const child = spawn("explorer", args, {
+					const winArgs = statSync(absPath).isDirectory() ? [absPath] : ["/select,", absPath];
+					const child = spawn("explorer", winArgs, {
 						detached: true,
 						stdio: "ignore",
 						windowsHide: false
@@ -253,46 +358,78 @@ function runCcFs(root, args) {
 					child.on("error", () => {});
 					child.unref();
 				} else throw new Error(`unsupported platform: ${os}`);
-				return {
-					ok: true,
-					revealed: safeRel(root, abs)
-				};
+				return `revealed in file manager: ${args.path}`;
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
-				throw new Error(`reveal failed to open "${safeRel(root, abs)}": ${msg}`);
+				throw new Error(`reveal failed to open "${args.path}": ${msg}`);
 			}
 		}
 		case "info": {
 			if (!args.path) throw new Error("info 需要 path");
-			const abs = resolveInside(root, args.path);
-			if (!existsSync(abs)) return {
-				exists: false,
-				path: safeRel(root, abs)
-			};
-			const st = statSync(abs);
-			return {
-				exists: true,
-				path: safeRel(root, abs),
-				type: st.isDirectory() ? "dir" : st.isFile() ? "file" : "other",
-				size: st.size,
-				mtime: st.mtime.toISOString()
-			};
+			const absPath = args.path.startsWith("/") ? resolve(args.path) : resolveInside(root, args.path);
+			if (!existsSync(absPath)) throw new Error(`info: path "${absPath}" does not exist`);
+			const stat = statSync(absPath);
+			const fileType = detectFileType(stat);
+			const modeStr = stat.mode.toString(8).slice(-4);
+			return [
+				`path: ${safeRel(root, absPath)}`,
+				`type: ${fileType}`,
+				`size: ${stat.size} (${humanSize(stat.size)})`,
+				`mtime: ${stat.mtime.toISOString()}`,
+				`mode: ${modeStr}`,
+				`uid: ${stat.uid}`,
+				`gid: ${stat.gid}`
+			].join("\n");
 		}
 		case "find": {
 			if (!args.pattern) throw new Error("find 需要 pattern");
+			const relPath = args.path || ".";
+			const absPath = relPath.startsWith("/") ? resolve(relPath) : resolveInside(root, relPath);
+			if (!existsSync(absPath)) throw new Error(`find: path "${absPath}" does not exist`);
 			const pattern = args.pattern;
-			const isRegex = pattern.startsWith("regex:");
-			const re = isRegex ? new RegExp(pattern.slice(6)) : null;
-			const out = [];
-			const walk = (cur) => {
-				for (const e of readdirSync(cur, { withFileTypes: true })) {
-					const full = join(cur, e.name);
-					if (isRegex ? re.test(e.name) : e.name.includes(pattern)) out.push(safeRel(root, full));
-					if (e.isDirectory()) walk(full);
+			const absolutePaths = args.absolute ?? false;
+			const maxDepth = args.maxDepth ?? -1;
+			const hasGlobChars = /[*?]/.test(pattern);
+			const matchFilename = (name) => {
+				if (hasGlobChars) {
+					const regexStr = "^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$";
+					try {
+						return new RegExp(regexStr).test(name);
+					} catch {
+						return name.includes(pattern);
+					}
 				}
+				return name.toLowerCase().includes(pattern.toLowerCase());
+			};
+			const matches = [];
+			const walkFind = (dir, depth) => {
+				if (maxDepth >= 0 && depth > maxDepth) return;
+				let names;
+				try {
+					names = readdirSync(dir);
+				} catch {
+					return;
+				}
+				for (const name of names.sort()) {
+					const full = join(dir, name);
+					let stat;
+					try {
+						stat = statSync(full);
+					} catch {
+						continue;
+					}
+					if (matchFilename(name)) matches.push(absolutePaths ? full : safeRel(root, full));
+					if (stat.isDirectory()) walkFind(full, depth + 1);
+				}
+			};
+			walkFind(absPath, 1);
+			matches.sort();
+			return {
+				path: absPath,
+				pattern,
+				matches,
+				count: matches.length
 			};
-			walk(root);
-			return out;
 		}
 		default: throw new Error(`未知 action: ${a}`);
 	}
@@ -347,15 +484,35 @@ const ccFsTool = defineTool({
 		},
 		pattern: {
 			type: "string",
-			description: "find 匹配（名称包含；regex: 前缀为正则）"
+			description: "find 匹配（glob *? 或大小写不敏感子串）"
 		},
 		depth: {
 			type: "integer",
-			description: "tree 最大深度"
+			description: "tree 最大深度（1-10，默认 3）"
 		},
 		dryRun: {
 			type: "boolean",
-			description: "rm 预览模式"
+			description: "rm/archive 预览模式"
+		},
+		recursive: {
+			type: "boolean",
+			description: "rm 删目录 / cp 复制目录需 recursive"
+		},
+		filesOnly: {
+			type: "boolean",
+			description: "tree 只显示文件（与 dirsOnly 互斥）"
+		},
+		dirsOnly: {
+			type: "boolean",
+			description: "tree 只显示目录（与 filesOnly 互斥）"
+		},
+		absolute: {
+			type: "boolean",
+			description: "find 返回绝对路径"
+		},
+		maxDepth: {
+			type: "integer",
+			description: "find 最大递归深度（缺省不限）"
 		}
 	},
 	output: {
@@ -369,6 +526,21 @@ const ccFsTool = defineTool({
 	}
 });
 //#endregion
+//#region src/constants.ts
+/** 常量（纯模块，零 DSH 依赖） */
+/**
+* ACC 版本：自动从 package.json 读取（单一真相源，消除与 CHANGELOG 的漂移）。
+* 发布时只需改 package.json 的 version。
+*/
+const ACC_VERSION = (() => {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url));
+		return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+})();
+//#endregion
 //#region src/msm-ops.ts
 /**
 * msm-ops.ts — acc_msm 纯操作层（零 DSH 依赖）
@@ -378,6 +550,37 @@ const ccFsTool = defineTool({
 */
 const execFileAsync = promisify(execFile);
 const MSM_TIMEOUT_MS = 6e5;
+/** CCC 名：从 .serenity 首行解析（对齐 osp readSerenityCccName） */
+function readCccName$1(root) {
+	try {
+		return readFileSync(resolve(root, ".serenity"), "utf-8").trim().split("\n")[0]?.trim() || null;
+	} catch {
+		return null;
+	}
+}
+/**
+* path-arg 逃逸校验：根内 + symlink 防御（对齐 osp validatePathArgsFromTokens）。
+* symlink 指向根外 → 拒绝（realpath 解析后与根前缀比对）。
+*/
+function assertPathInsideRoot(root, value, flagName) {
+	const abs = resolve(root, value);
+	if (classifyPath(abs, root) === "outside") throw new Error(`Path escape blocked: --${flagName}=${value} 越出 CCC 根`);
+	if (existsSync(abs)) try {
+		const real = realpathSync(abs);
+		if (classifyPath(real, root) === "outside") throw new Error(`Path escape blocked: --${flagName}=${value} 经 symlink 指向根外 (${real})`);
+	} catch (e) {
+		if (e instanceof Error && e.message.includes("symlink")) throw e;
+	}
+}
+/** 业务子进程 env：注入 SERENITY_ROOT / SERENITY_CCC / SERENITY_VERSION（对齐 osp） */
+function buildMsmEnv(root) {
+	return {
+		...process.env,
+		SERENITY_ROOT: root,
+		SERENITY_CCC: readCccName$1(root) ?? "",
+		SERENITY_VERSION: ACC_VERSION
+	};
+}
 /**
 * Windows 兼容（审计观察点 A）：`.cmd` 不能直接被 CreateProcess 解析——
 * `execFile('npx')` / `spawnSync('npx')` 在 Windows 必 ENOENT（需 shell 或显式 .cmd）。
@@ -390,26 +593,91 @@ const MSM_ACTIONS = [
 	"register",
 	"deregister",
 	"check",
-	"guide"
+	"guide",
+	"ccc-config"
 ];
 const MSM_GUIDE = `MSM 开发手册（Mech & Semi-Mech 框架）
 
 ## 是什么
 MSM = 可执行单元层。Mech 纯 TS 零 LLM 推理；Semi-Mech TS 框架 + LLM 决策点。
+MSM 是 ACC 的确定性可执行单元层——所有 shell/exec 操作走 MSM，不可绕过。
 
 ## 注册新 MSM（acc_msm register）
 1. 在 <skill>/scripts/ 写脚本（tsx 可跑；必须带 main() CLI 守卫 import.meta.url 检查）
 2. acc_msm register <name> --skill <s> --path <脚本相对根路径> --category <mech|semi-mech> --description <desc>
-3. 自动写入 mech-registry.json + git commit
+3. 自动写入 mech-registry.json（保留原格式）+ git commit（只提交注册表文件）
+4. 校验：path 必须根内、脚本必须存在、name 全局唯一
+
+## flag schema（v1）
+flags 是 new-style 对象数组，用于参数校验与 path 逃逸守卫：
+  [{"name":"output","type":"string","description":"输出路径"},
+   {"name":"target","type":"path","description":"操作目标（type:path 启用根内校验 + symlink 防御）"},
+   {"name":"force","type":"boolean","description":"强制模式","default":false}]
+- {name, type} 格式 — new style，type:"path" 启用 path-escape 守卫
+- {flag, description} 格式 — old style，CLI flag 描述字符串
+- 注册时 flags 经 acc_msm register --flags '<json>' 传入（工具当前解析 name 风格）
 
 ## 脚本约定
 - 顶部文档：用途/用法/退出码
-- 退出码：0 成功 / 1 user / 2 system / 3 operator
-- flags 中 type:"path" 的参数会被逃逸校验（根内强制）
-- 配对 .test.ts（vitest）
+- 退出码：0 成功 / 1 user / 2 system / 3 operator（对齐 ACC 协议分类）
+- main() CLI 守卫（DC-M2）：脚本顶部必须有
+    if (import.meta.url === \`file://\${process.argv[1]}\`) { main() }
+  或等价 isMain / require.main === 判断——vitest import 时不触发顶层代码
+- 配对 .test.ts 或 .spec.ts（DC-M1，vitest）
+- 业务子进程环境：注入 SERENITY_ROOT / SERENITY_CCC / SERENITY_VERSION
+
+## 品质检查（acc_msm check，DC-M1~M4）
+DC-M1 有 .test.ts/.spec.ts；DC-M2 有 main() 守卫（function main( / isMain / require.main === / import.meta.url）；
+DC-M3 双向：脚本未注册 + 注册表引用脚本缺失；DC-M4 路径型 flag 标记 type:"path"
 
-## 品质检查（acc_msm check）
-DC-M1 有 .test.ts；DC-M2 有 main() 守卫；M3 脚本存在；M4 path flag 标记 type:"path"
+## 自描述（协议 flag，仅限参数首位）
+acc_msm exec <name> --list        — 列出全部 MSM
+acc_msm exec <name> --schema <n>   — 查看某 MSM 的参数 schema
+acc_msm exec <name> --format=json  — JSON 输出模式（其余参数无损透传）
+`;
+/** CCC 配置参考（对齐 osp ccc-config action） */
+const CCC_CONFIG_REFERENCE = `═══ CCC Configuration Reference ═══
+
+CCC-level features are configured in .opencode/serenity.json.
+Below are all available configuration sections.
+
+── 1. loop.defaultModel ──
+loop 工具缺省模型（未配置且未传 model 参数时 loop 报错）。
+
+  Config:
+    { "loop": { "defaultModel": "provider/model-name" } }
+
+  Example:
+    { "loop": { "defaultModel": "minimax-cn-coding-plan/MiniMax-M3" } }
+
+── 2. sessionKeeper.threshold ──
+SESSION-KEEPER 提醒机制的积分阈值（非 headless 主 agent）。
+按工具调用加权 + 耗时计分；达到阈值注入提醒，要求模型回复 ACK 码。
+
+  Config:
+    { "sessionKeeper": { "threshold": 150 } }
+
+  计分：write/edit = 3，task = 10，read/grep/glob/msm 等 = 1，时间 = 1/分钟
+  默认：150
+
+── 3. localstore.gitTrack ──
+localstore.json 的 git 策略：allow 可提交 / deny 禁提交（默认 deny）。
+deny 时写入自动确保 .gitignore 含该文件（物理保证），cc_git commit 会检查拒绝。
+
+  Config:
+    { "localstore": { "gitTrack": "allow" } }
+
+── 4. hooks.autoRestoreSession ──
+会话自动恢复（默认 true；受 events 门控——仅根会话 + 已有对话历史才恢复）。
+
+  Config:
+    { "hooks": { "autoRestoreSession": false } }
+
+── 5. safeMode / blacklist ──
+safe-mode 由 WebUI 开关控制（写 .serenity-safe-on 标记）；黑名单路径受 guards seam 拦截。
+
+  Config:
+    { "safeMode": { "blacklist": [".secrets/"] } }
 `;
 function parseRegistry(raw) {
 	const data = JSON.parse(raw);
@@ -437,28 +705,47 @@ function loadMsmEntries(root) {
 function findEntry(root, name) {
 	return loadMsmEntries(root).find((e) => e.name === name) ?? null;
 }
+/** 扫描各 skill scripts/ 下的非测试脚本（DC-M3 正向基准，对齐 osp） */
+function scanSkillScripts(root) {
+	const out = [];
+	const skillsDir = join(root, ".opencode", "skills");
+	if (!existsSync(skillsDir)) return out;
+	for (const skill of readdirSync(skillsDir)) {
+		const scriptsDir = join(skillsDir, skill, "scripts");
+		if (!existsSync(scriptsDir)) continue;
+		for (const f of readdirSync(scriptsDir)) if (/\.(ts|js|mjs)$/.test(f) && !/\.(test|spec)\./.test(f)) out.push(join(".opencode", "skills", skill, "scripts", f));
+	}
+	return out.sort();
+}
 function registryPathFor(root, skill) {
 	return skill ? join(root, ".opencode", "skills", skill, "references", "mech-registry.json") : join(root, "mech-registry.json");
 }
-function writeRegistry(path, entries) {
+function writeRegistry(path, entries, isV1Wrapped = true) {
 	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, JSON.stringify({
+	const payload = isV1Wrapped ? JSON.stringify({
 		version: 1,
 		description: "MSM registry (managed by acc-msm / dsh-serenity-hooks)",
 		entries
-	}, null, 2) + "\n", "utf-8");
+	}, null, 2) + "\n" : JSON.stringify(entries, null, 2) + "\n";
+	writeFileSync(path, payload, "utf-8");
 }
 function runMsm(root, args) {
 	switch (args.action) {
-		case "list": return loadMsmEntries(root).map((e) => ({
-			name: e.name,
-			skill: e.skill ?? null,
-			category: e.category ?? null,
-			description: e.description ?? ""
-		}));
+		case "list": {
+			const entries = loadMsmEntries(root);
+			const cccName = readCccName$1(root) ?? "unknown";
+			const header = `(serenity-plugin v${ACC_VERSION}) CCC:${cccName} Root:${root}`;
+			if (entries.length === 0) return `${header}\n(no MSM registered)`;
+			const lines = entries.map((e) => {
+				const base = `${e.name} | ${e.skill ?? "-"} | ${e.category ?? "-"} | ${e.description ?? ""}`;
+				if (e.flags && e.flags.length > 0) return `${base} [flags: ${e.flags.map((f) => `--${f.name} <${f.type ?? "string"}>`).join(", ")}]`;
+				return base;
+			});
+			return `${header}\n` + lines.join("\n");
+		}
 		case "guide": return { guide: MSM_GUIDE };
 		case "exec": {
-			const { entry, businessArgs, fmtJson, protocol } = prepareExec(root, args);
+			const { entry, businessArgs, fmtJson, hasHelp, protocol } = prepareExec(root, args);
 			const p = protocolResult(protocol);
 			if (p !== void 0) return p;
 			let r = spawnSync("bun", [entry.path, ...businessArgs], {
@@ -469,7 +756,8 @@ function runMsm(root, args) {
 					"pipe",
 					"pipe",
 					"pipe"
-				]
+				],
+				env: buildMsmEnv(root)
 			});
 			if (r.error && r.error.code === "ENOENT") r = spawnSync(NPX_BIN, [
 				"tsx",
@@ -483,36 +771,55 @@ function runMsm(root, args) {
 					"pipe",
 					"pipe",
 					"pipe"
-				]
+				],
+				env: buildMsmEnv(root)
 			});
-			return msmExecResult(entry.name, r.status ?? 2, r.stdout ?? "", r.stderr ?? "", fmtJson);
+			return msmExecResult(entry.name, r.status ?? 2, r.stdout ?? "", r.stderr ?? "", fmtJson, hasHelp);
 		}
 		case "register": {
 			const name = args.name ?? "";
 			const { skill, path, category, description } = args;
+			if (!name) throw new Error("register 需要 name");
 			if (!path || !category || !description) throw new Error("register 需要 path/category/description");
+			const scriptAbs = resolve(root, path);
+			if (classifyPath(scriptAbs, root) === "outside") throw new Error(`MSM register: path "${path}" escapes CCC root "${root}"`);
+			if (!existsSync(scriptAbs)) throw new Error(`MSM script not found: "${path}"`);
+			if (loadMsmEntries(root).some((e) => e.name === name)) throw new Error(`MSM already registered: "${name}"`);
 			const regPath = registryPathFor(root, skill);
+			const isV1Wrapped = existsSync(regPath) && !Array.isArray(JSON.parse(readFileSync(regPath, "utf-8")));
 			const entries = existsSync(regPath) ? parseRegistry(readFileSync(regPath, "utf-8")) : [];
-			if (entries.some((e) => e.name === name)) throw new Error(`MSM already registered: "${name}"`);
+			let flags;
+			if (args.flags) try {
+				const parsed = JSON.parse(args.flags);
+				if (!Array.isArray(parsed)) throw new Error("flags must be a JSON array");
+				flags = parsed;
+			} catch (e) {
+				throw new Error(`register flags 解析失败：${e instanceof Error ? e.message : String(e)}`);
+			}
 			entries.push({
 				name,
 				path,
 				skill,
 				category,
 				description,
-				usage: `msm_exec ${name} [args...]`,
-				flags: []
+				usage: args.usage ?? `acc_msm exec ${name} [args...]`,
+				flags: flags ?? []
 			});
-			writeRegistry(regPath, entries);
+			writeRegistry(regPath, entries, isV1Wrapped);
 			try {
-				execFileSync("git", ["add", "-A"], {
+				const relRegistry = relative(root, regPath);
+				execFileSync("git", [
+					"add",
+					"--",
+					relRegistry
+				], {
 					cwd: root,
 					stdio: "pipe"
 				});
 				execFileSync("git", [
 					"commit",
 					"-m",
-					`msm: register ${name}`
+					`chore(msm): register ${name}`
 				], {
 					cwd: root,
 					stdio: "pipe"
@@ -526,20 +833,26 @@ function runMsm(root, args) {
 		case "deregister": {
 			const name = args.name ?? "";
 			for (const regPath of findRegistries(root)) {
+				const isV1Wrapped = !Array.isArray(JSON.parse(readFileSync(regPath, "utf-8")));
 				const entries = parseRegistry(readFileSync(regPath, "utf-8"));
 				const idx = entries.findIndex((e) => e.name === name);
 				if (idx >= 0) {
 					entries.splice(idx, 1);
-					writeRegistry(regPath, entries);
+					writeRegistry(regPath, entries, isV1Wrapped);
 					try {
-						execFileSync("git", ["add", "-A"], {
+						const relRegistry = relative(root, regPath);
+						execFileSync("git", [
+							"add",
+							"--",
+							relRegistry
+						], {
 							cwd: root,
 							stdio: "pipe"
 						});
 						execFileSync("git", [
 							"commit",
 							"-m",
-							`msm: deregister ${name}`
+							`chore(msm): deregister ${name}`
 						], {
 							cwd: root,
 							stdio: "pipe"
@@ -550,9 +863,16 @@ function runMsm(root, args) {
 			}
 			throw new Error(`MSM not registered: "${name}"`);
 		}
+		case "ccc-config": return CCC_CONFIG_REFERENCE;
 		case "check": {
 			const entries = loadMsmEntries(root);
 			const issues = [];
+			const registeredPaths = new Set(entries.map((e) => e.path));
+			for (const scriptPath of scanSkillScripts(root)) if (!registeredPaths.has(scriptPath)) issues.push({
+				name: scriptPath,
+				check: "M3",
+				detail: "script not registered in mech-registry"
+			});
 			for (const e of entries) {
 				const script = join(root, e.path);
 				const scriptExists = existsSync(script);
@@ -561,16 +881,25 @@ function runMsm(root, args) {
 					check: "M3",
 					detail: `script missing (${e.path})`
 				});
-				const testFile = script.replace(/\.ts$/, ".test.ts");
-				if (!existsSync(testFile)) issues.push({
+				const testFileTs = script.replace(/\.ts$/, ".test.ts");
+				const testFileSpec = script.replace(/\.ts$/, ".spec.ts");
+				if (!existsSync(testFileTs) && !existsSync(testFileSpec)) issues.push({
 					name: e.name,
 					check: "M1",
-					detail: "no .test.ts"
+					detail: "no .test.ts / .spec.ts"
 				});
-				if (scriptExists && !readFileSync(script, "utf-8").includes("import.meta.url")) issues.push({
+				if (scriptExists) {
+					const src = readFileSync(script, "utf-8");
+					if (!(/function main\(/.test(src) || /\bisMain\b/.test(src) || /require\.main\s*===/.test(src) || /import\.meta\.url/.test(src))) issues.push({
+						name: e.name,
+						check: "M2",
+						detail: "no main() guard"
+					});
+				}
+				for (const f of e.flags ?? []) if ("name" in f && /path|file|dir/i.test(f.name) && f.type !== "path") issues.push({
 					name: e.name,
-					check: "M2",
-					detail: "no main() guard"
+					check: "M4",
+					detail: `flag --${f.name} should be type:"path"`
 				});
 			}
 			return {
@@ -586,24 +915,25 @@ function prepareExec(root, args) {
 	const entry = findEntry(root, name);
 	if (!entry) throw new Error(`MSM not registered: "${name}"`);
 	const business = args.args ?? [];
-	if (business.includes("--list")) return {
+	if (business[0] === "--list") return {
 		entry,
 		businessArgs: [],
 		fmtJson: false,
+		hasHelp: false,
 		protocol: { list: loadMsmEntries(root).map((e) => ({
 			name: e.name,
 			category: e.category ?? null
 		})) }
 	};
-	const schemaIdx = business.indexOf("--schema");
-	if (schemaIdx >= 0) {
-		const target = business[schemaIdx + 1];
+	if (business[0] === "--schema") {
+		const target = business[1];
 		const found = target ? loadMsmEntries(root).find((e) => e.name === target) : null;
 		if (!found) throw new Error(`MSM not registered: "${target}"`);
 		return {
 			entry,
 			businessArgs: [],
 			fmtJson: false,
+			hasHelp: false,
 			protocol: { schema: {
 				name: found.name,
 				path: found.path,
@@ -615,20 +945,16 @@ function prepareExec(root, args) {
 			} }
 		};
 	}
-	const fmtJson = business.includes("--format=json");
-	const businessArgs = business.filter((a) => a !== "--format=json");
+	const fmtJson = business[0] === "--format=json";
+	const businessArgs = fmtJson ? business.slice(1) : business;
+	const hasHelp = businessArgs.includes("--help") || businessArgs.includes("-h");
 	for (const flag of entry.flags ?? []) {
 		if (flag.type !== "path") continue;
 		const eq = businessArgs.find((a) => a.startsWith(`--${flag.name}=`));
-		if (eq) {
-			const value = eq.slice(flag.name.length + 3);
-			if (classifyPath(resolve(root, value), root) === "outside") throw new Error(`Path escape blocked: --${flag.name}=${value} 越出 CCC 根`);
-		} else {
+		if (eq) assertPathInsideRoot(root, eq.slice(flag.name.length + 3), flag.name);
+		else {
 			const idx = businessArgs.indexOf(`--${flag.name}`);
-			if (idx >= 0 && businessArgs[idx + 1]) {
-				const value = businessArgs[idx + 1];
-				if (classifyPath(resolve(root, value), root) === "outside") throw new Error(`Path escape blocked: --${flag.name} ${value} 越出 CCC 根`);
-			}
+			if (idx >= 0 && businessArgs[idx + 1]) assertPathInsideRoot(root, businessArgs[idx + 1], flag.name);
 		}
 	}
 	const script = resolve(root, entry.path);
@@ -640,7 +966,8 @@ function prepareExec(root, args) {
 			path: script
 		},
 		businessArgs,
-		fmtJson
+		fmtJson,
+		hasHelp
 	};
 }
 /** 协议结果扁平化：{list|schema} 包装 → 顶层值（兼容旧契约）；非协议返回 undefined */
@@ -649,7 +976,12 @@ function protocolResult(protocol) {
 	if ("list" in protocol) return protocol.list;
 	if ("schema" in protocol) return protocol.schema;
 }
-function msmExecResult(name, status, stdout, stderr, fmtJson) {
+/** 失败 TIP（对齐 osp：业务 exit≠0 且未传 --help 时追加提示） */
+function helpTip() {
+	return "\n[TIP] Pass \"--help\" as the first arg to see this MSM's usage and required flags.";
+}
+function msmExecResult(name, status, stdout, stderr, fmtJson, hasHelp = false) {
+	const tip = status !== 0 && !hasHelp ? helpTip() : "";
 	if (fmtJson) return status === 0 ? {
 		name,
 		exit: 0,
@@ -659,13 +991,13 @@ function msmExecResult(name, status, stdout, stderr, fmtJson) {
 		name,
 		exit: status,
 		ok: false,
-		error: stderr.trim() || stdout.trim()
+		error: (stderr.trim() || stdout.trim()) + tip
 	};
 	return {
 		name,
 		exit: status,
 		stdout,
-		stderr
+		stderr: stderr + tip
 	};
 }
 /**
@@ -675,7 +1007,7 @@ function msmExecResult(name, status, stdout, stderr, fmtJson) {
 */
 async function runMsmAsync(root, args) {
 	if (args.action !== "exec") return runMsm(root, args);
-	const { entry, businessArgs, fmtJson, protocol } = prepareExec(root, args);
+	const { entry, businessArgs, fmtJson, hasHelp, protocol } = prepareExec(root, args);
 	const p = protocolResult(protocol);
 	if (p !== void 0) return p;
 	try {
@@ -683,9 +1015,10 @@ async function runMsmAsync(root, args) {
 			cwd: root,
 			encoding: "utf-8",
 			timeout: MSM_TIMEOUT_MS,
-			maxBuffer: 67108864
+			maxBuffer: 67108864,
+			env: buildMsmEnv(root)
 		});
-		return msmExecResult(entry.name, 0, r.stdout, r.stderr, fmtJson);
+		return msmExecResult(entry.name, 0, r.stdout, r.stderr, fmtJson, hasHelp);
 	} catch (e) {
 		const err = e;
 		if (err.code === "ENOENT") try {
@@ -697,20 +1030,21 @@ async function runMsmAsync(root, args) {
 				cwd: root,
 				encoding: "utf-8",
 				timeout: MSM_TIMEOUT_MS,
-				maxBuffer: 67108864
+				maxBuffer: 67108864,
+				env: buildMsmEnv(root)
 			});
-			return msmExecResult(entry.name, 0, r.stdout, r.stderr, fmtJson);
+			return msmExecResult(entry.name, 0, r.stdout, r.stderr, fmtJson, hasHelp);
 		} catch (e2) {
 			const err2 = e2;
 			const status = err2.killed ? 124 : typeof err2.code === "number" ? err2.code : 2;
 			const stdout = err2.stdout ?? "";
 			const stderr = err2.killed ? `MSM timed out after ${MSM_TIMEOUT_MS}ms` : err2.stderr ?? err2.message ?? "";
-			return msmExecResult(entry.name, status, stdout, stderr, fmtJson);
+			return msmExecResult(entry.name, status, stdout, stderr, fmtJson, hasHelp);
 		}
 		const status = err.killed ? 124 : typeof err.code === "number" ? err.code : 2;
 		const stdout = err.stdout ?? "";
 		const stderr = err.killed ? `MSM timed out after ${MSM_TIMEOUT_MS}ms` : err.stderr ?? err.message ?? "";
-		return msmExecResult(entry.name, status, stdout, stderr, fmtJson);
+		return msmExecResult(entry.name, status, stdout, stderr, fmtJson, hasHelp);
 	}
 }
 //#endregion
@@ -718,8 +1052,13 @@ async function runMsmAsync(root, args) {
 /**
 * session-ops.ts — session 工具纯操作层（零 DSH 依赖，可独立单测）
 *
-* 移植自 dsh-serenity-plugin v0.1 acc-session runner（本项目自有代码）。
-* 操作 CCC 根的 AGENT_SESSIONS/ 目录，返回规范 JSON 值。
+* 行为对齐 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。
 */
 const SESSION_ACTIONS = [
 	"list",
@@ -730,245 +1069,551 @@ const SESSION_ACTIONS = [
 	"health",
 	"qa",
 	"archive",
-	"summary"
+	"summary",
+	"hook-develop-guide"
 ];
-const SESSION_DIR_RE = /^(\d{4}-\d{2}-\d{2})--(S\d{3})--(.+)$/;
+const SESSION_MD = "SESSION.md";
+const ARCHIVE_DIR_NAME = "_archived";
+const HEALTH_STALE_DAYS = 7;
+const HEALTH_STALLED_PCT = 30;
+const HEALTH_STALLED_DAYS = 3;
+const HEALTH_GHOST_DAYS = 2;
 const DAY = 864e5;
-function today() {
-	return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-}
 function sessionsRoot(root) {
 	return join(root, "AGENT_SESSIONS");
 }
-function listSessions(root) {
-	const sessRoot = sessionsRoot(root);
-	if (!existsSync(sessRoot)) return [];
-	const out = [];
-	for (const entry of readdirSync(sessRoot)) {
-		const full = join(sessRoot, entry);
-		if (!statSync(full).isDirectory()) continue;
-		const md = join(full, "SESSION.md");
-		const m = SESSION_DIR_RE.exec(entry);
-		let status = null;
-		if (existsSync(md)) status = /\[x\]|\[X\]/.test(readFileSync(md, "utf-8")) ? "done" : "open";
-		out.push({
-			dir: entry,
-			id: m?.[2] ?? null,
-			hasSessionMd: existsSync(md),
-			mtime: statSync(full).mtime.toISOString(),
+/** 解析 SESSION.md 状态元数据（对齐 osp parseSessionMd） */
+function parseSessionMd(filePath) {
+	try {
+		const content = readFileSync(filePath, "utf-8");
+		return {
+			hasSessionMd: true,
+			completed: /\[\s*x\s*\]/i.test(content),
+			completedCount: (content.match(/\[\s*x\s*\]/gi) ?? []).length,
+			pendingCount: (content.match(/\[\s*[ \t]\s*\]/g) ?? []).length,
+			unresolvedCount: (content.match(/(未解决|open|question|TODO)/gi) ?? []).length
+		};
+	} catch {
+		return {
+			hasSessionMd: false,
+			completed: false,
+			completedCount: 0,
+			pendingCount: 0,
+			unresolvedCount: 0
+		};
+	}
+}
+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,
+			completedCount: 0,
+			pendingCount: 0,
+			unresolvedCount: 0
+		};
+		return {
+			dirName,
+			path: dirPath,
+			mtime: st.mtime,
 			status
-		});
+		};
+	} catch {
+		return null;
 	}
-	out.sort((a, b) => a.dir < b.dir ? 1 : -1);
-	return out;
 }
-function nextSessionId(sessions) {
-	let max = 0;
-	for (const s of sessions) if (s.id) {
-		const n = Number(s.id.slice(1));
-		if (n > max) max = n;
+/** 读取 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 [];
 	}
-	return `S${String(max + 1).padStart(3, "0")}`;
 }
-function findSession(root, key) {
-	return listSessions(root).find((s) => s.dir.includes(key) || (s.id ?? "") === key.toUpperCase()) ?? null;
+/** 提取目录名中的会话 ID（S### 或 issue 名）；无匹配返回 '' */
+function extractSessionId(dirName) {
+	const m = dirName.match(/--S(\d{3,})--/);
+	return m ? `S${m[1]}` : "";
 }
-function createSession(root, name, title) {
-	const id = nextSessionId(listSessions(root));
-	const dirName = `${today()}--${id}--${name}`;
-	const dir = join(sessionsRoot(root), dirName);
-	mkdirSync(dir, { recursive: true });
-	const md = join(dir, "SESSION.md");
-	writeFileSync(md, `# SESSION: ${title}\n- ID: ${id}\n\n## 目标\n<一句话描述本次会话要完成的事情>\n\n## 状态\n- [ ] 进行中\n\n## 关键决策\n| # | 决策 | 理由 |\n|---|------|------|\n| 1 |  |  |\n\n## 进度记录\n- ${today()} — 会话创建\n\n## 产出物\n- \n\n## 未解决的问题\n- \n`, "utf-8");
-	return {
-		dir: dirName,
-		id,
-		sessionMd: md
-	};
+/**
+* 根据 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 target = findSession(root, key);
-	if (!target) {
-		for (const s of listSessions(root)) {
-			const md = join(sessionsRoot(root), s.dir, "SESSION.md");
-			if (existsSync(md) && readFileSync(md, "utf-8").includes(key)) return {
-				dir: s.dir,
-				content: readFileSync(md, "utf-8")
-			};
+	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 + 长度限制） */
+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}--${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;
 		}
-		throw new Error(`未找到会话: ${key}`);
 	}
-	const md = join(sessionsRoot(root), target.dir, "SESSION.md");
-	if (!existsSync(md)) throw new Error(`会话 ${target.dir} 缺少 SESSION.md`);
+	const nextId = String(maxId + 1).padStart(3, "0");
+	const dirName = `${datePrefix}--S${nextId}--${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 {
-		dir: target.dir,
-		content: readFileSync(md, "utf-8")
+		message: `Created: ${dirName}/ (S${nextId})`,
+		dirName,
+		sessionPath,
+		sessionId: `S${nextId}`
 	};
 }
 /**
-* 活动会话标记：按 DSH 会话（agent.session.id）隔离，不再使用 CCC 级全局单文件。
-* 每个 dsh 会话一个标记文件（.dsh/active-sessions/<scope>），系统提示词 Session 块
-* 只注入当前 dsh 会话 use 的活跃会话 —— 多开 conversation / subagent / loop 牛马互不泄露。
-*
-* 旧版全局标记 `.dsh/active-session`（v1.16.1 及以前）：use 时删除（迁移清理），
-* 读取不再回退（隔离优先；升级后重新 use 一次即可）。
+* 活动会话跟踪（S134 v1.16.14 内存化，对齐 osp active-state）：
+* **不落盘**——活跃会话状态在内存 Map（key = scope = dsh 会话 id），避免落盘标记
+* 文件累积与跨会话串台（落盘版 `.dsh/active-sessions/<scope>` 已被此方案取代）。
+* 进程重启恢复：从**当前会话历史（events）**解析 `[SESSION CONTEXT]` 标记（use 时注入），
+* 只扫自己会话——无全局扫描、无跨会话污染。
 */
-const ACTIVE_SESSIONS_DIR = join(".dsh", "active-sessions");
-/** 旧版全局标记路径（v1.16.1 及以前 use 写入；新版本仅清理不再读取） */
-const LEGACY_ACTIVE_SESSION_MARKER = join(".dsh", "active-session");
-/** 默认 scope（agent.session.id 缺失时） */
 const DEFAULT_SESSION_SCOPE = "default";
-/** scope 用作文件名：仅保留安全字符（agent.session.id 可能含 / 等；`.` 排除以杜绝 `..` 路径段穿越） */
-function sanitizeScope(scope) {
-	return scope.replace(/[^A-Za-z0-9_-]/g, "_") || "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 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;
 }
-/** scope 标记文件绝对路径 */
-function activeSessionMarker(root, scope) {
-	return resolve(root, ACTIVE_SESSIONS_DIR, sanitizeScope(scope));
-}
-/** 激活会话：写 <scope> 标记（内容 = 相对 CCC 根的 SESSION.md 路径）；顺带清理旧全局标记 */
+/**
+* use 子命令：激活会话（写内存 Map）+ 返回对齐 osp 的输出文本
+* （含 [SESSION CONTEXT] 标记 + todowrite 指令；标记随工具结果进 events 历史，
+*  进程重启后从当前会话 events 解析恢复）。
+*/
 function useSession(root, key, scope = DEFAULT_SESSION_SCOPE) {
-	const target = findSession(root, key);
-	if (!target) throw new Error(`未找到会话: ${key}`);
-	const md = join(sessionsRoot(root), target.dir, "SESSION.md");
-	if (!existsSync(md)) throw new Error(`会话 ${target.dir} 缺少 SESSION.md`);
-	const marker = activeSessionMarker(root, scope);
-	mkdirSync(resolve(root, ".dsh", "active-sessions"), { recursive: true });
-	const relMd = relative(root, md);
-	writeFileSync(marker, relMd, "utf-8");
-	const legacy = resolve(root, LEGACY_ACTIVE_SESSION_MARKER);
-	if (existsSync(legacy)) rmSync(legacy, { force: true });
+	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: target.dir,
-		mdPath: md
+		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")
 	};
 }
-/** 关闭活动会话：删除 <scope> 标记 + 旧全局标记 */
-function closeSession(root, scope = DEFAULT_SESSION_SCOPE) {
-	const marker = activeSessionMarker(root, scope);
-	if (existsSync(marker)) rmSync(marker, { force: true });
-	const legacy = resolve(root, LEGACY_ACTIVE_SESSION_MARKER);
-	if (existsSync(legacy)) rmSync(legacy, { force: true });
-	return { dir: "active-session cleared" };
-}
-/** 读取指定 scope 的活跃会话 SESSION.md 绝对路径；无标记/越界返回 null */
-function readActiveSessionMd(root, scope = DEFAULT_SESSION_SCOPE) {
-	const marker = activeSessionMarker(root, scope);
-	if (!existsSync(marker)) return null;
-	const rel = readFileSync(marker, "utf-8").trim();
-	if (!rel) return null;
-	const abs = resolve(root, rel);
-	if (!abs.startsWith(resolve(root))) return null;
-	return abs;
-}
-/** 列出全部 scope 的活动标记（含 scope / mdRel / mtime）；目录不存在返回空 */
-function listActiveMarkers(root) {
-	const dir = resolve(root, ACTIVE_SESSIONS_DIR);
-	if (!existsSync(dir)) return [];
-	const out = [];
-	for (const entry of readdirSync(dir)) {
-		const full = join(dir, entry);
-		if (!statSync(full).isFile()) continue;
-		try {
-			const rel = readFileSync(full, "utf-8").trim();
-			if (!rel) continue;
-			out.push({
-				scope: entry,
-				mdRel: rel,
-				mtime: statSync(full).mtimeMs
-			});
-		} catch {}
-	}
-	return out;
+/**
+* close 子命令（对齐 osp closeSession）：需 name + confirm=true；
+* 标记 SESSION.md 为 [x] 已完成 + [x] 已关闭 + 进度记录"关闭"；清除该会话的活跃状态。
+*/
+function closeSession(root, key, confirm, scope = DEFAULT_SESSION_SCOPE) {
+	if (!confirm) return "⚠ Close requires explicit confirmation.\n  Re-run with --confirm to confirm closing this session.";
+	const session = findSession(sessionsRoot(root), key);
+	if (!session) throw new Error(`Session not found: "${key}". Use "list" to see available sessions.`);
+	if (session.status.completed) return `Session "${session.dirName}" is already completed.`;
+	const mdPath = join(session.path, SESSION_MD);
+	if (!existsSync(mdPath)) throw new Error(`Session "${session.dirName}" has no SESSION.md — nothing to close.`);
+	let content = readFileSync(mdPath, "utf-8");
+	content = content.replace(/## 状态\n\n?- \[ \] 进行中/, "## 状态\n- [x] 已完成\n- [x] 已关闭");
+	const now = (/* @__PURE__ */ new Date()).toISOString().slice(0, 16).replace("T", " ");
+	if (!content.includes("-- 关闭")) content = content.replace(/(## 进度记录\n)/, `$1- ${now} — 关闭\n`);
+	writeFileSync(mdPath, content, "utf-8");
+	clearActiveSessionInfo(scope);
+	return `Session "${session.dirName}" closed and marked as completed.`;
 }
 /**
-* 重启恢复：当前 scope 无标记时，把"最近激活"（mtime 最新）且根内有效的标记
-* 复制为当前 scope 标记（激活语义延续：use = 激活，重启自动恢复 = 重新激活）。
-* 返回恢复的会话信息；已有标记 / 无候选 / 全部越界 → null。
-* 调用方负责根会话判定（subagent / loop 牛马不恢复——见 context.ts shouldAutoRestore）。
+* 从会话历史（events）解析最后一条 [SESSION CONTEXT] 标记（进程重启恢复；
+* 只扫**当前会话**自己的历史——无跨会话串台）。
 */
-function restoreActiveSession(root, scope = DEFAULT_SESSION_SCOPE) {
-	const marker = activeSessionMarker(root, scope);
-	if (existsSync(marker)) return null;
-	const scopeName = sanitizeScope(scope);
-	const candidates = listActiveMarkers(root).filter((m) => m.scope !== scopeName);
-	if (candidates.length === 0) return null;
-	const rootAbs = resolve(root);
-	const valid = candidates.filter((m) => pathInside(rootAbs, resolve(rootAbs, m.mdRel)));
-	if (valid.length === 0) return null;
-	const best = valid.sort((a, b) => b.mtime - a.mtime)[0];
-	mkdirSync(resolve(rootAbs, ACTIVE_SESSIONS_DIR), { recursive: true });
-	writeFileSync(marker, best.mdRel, "utf-8");
-	const mdPath = resolve(rootAbs, best.mdRel);
-	const dirName = basename(dirname(mdPath));
-	const idMatch = dirName.match(/S(\d{3,})/);
-	return {
-		dir: dirName,
-		id: idMatch ? `S${idMatch[1]}` : null,
-		mdPath,
-		restored: true,
-		from: best.scope
-	};
+function parseSessionContextFromEvents(events) {
+	for (let i = events.length - 1; i >= 0; i--) {
+		const strs = [];
+		collectStrings(events[i], strs);
+		for (const s of strs) {
+			const idx = s.indexOf(SESSION_CONTEXT_MARKER);
+			if (idx < 0) continue;
+			const dirName = s.slice(idx + 28).trim().split("\n")[0]?.trim() ?? "";
+			const mdMatch = s.match(/SESSION\.md path:\s*(\S+)/);
+			if (/^\d{4}-\d{2}-\d{2}--/.test(dirName) && mdMatch) {
+				const idMatch = dirName.match(/--S(\d{3,})--/);
+				return {
+					sessionId: idMatch ? `S${idMatch[1]}` : basename(dirName),
+					dirName,
+					mdPath: mdMatch[1]
+				};
+			}
+		}
+	}
+	return null;
 }
-function archiveSession(root, key) {
-	const target = findSession(root, key);
-	if (!target) throw new Error(`未找到会话: ${key}`);
-	const md = join(sessionsRoot(root), target.dir, "SESSION.md");
-	if (!existsSync(md)) throw new Error(`会话 ${target.dir} 缺少 SESSION.md`);
-	let content = readFileSync(md, "utf-8");
-	content = content.replace(/^-\s*\[ \]\s*进行中$/m, "- [x] 已完成").replace(/^-\s*\[ \]\s*已关闭（未完成）$/m, "- [x] 已关闭（未完成）");
-	if (!/\[x\]|\[X\]/.test(content)) content = content.replace(/^## 状态$/m, "## 状态\n- [x] 已完成");
-	writeFileSync(md, content, "utf-8");
-	appendFileSync(md, `\n> 已归档: ${today()}\n`, "utf-8");
-	return { dir: target.dir };
+/** 递归收集对象/数组/字符串中的全部字符串（保留原文，无 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);
 }
+/** health 子命令（对齐 osp healthCheck：stale/stalled/ghost/drift 四类检查，文本输出） */
 function healthCheck(root) {
-	const problems = [];
+	const sessions = readAllSessions(sessionsRoot(root));
+	if (sessions.length === 0) return "No sessions found — nothing to check.";
 	const now = Date.now();
-	for (const s of listSessions(root)) {
-		const age = (now - new Date(s.mtime).getTime()) / DAY;
-		if (!s.hasSessionMd) problems.push({
-			dir: s.dir,
-			kind: "missing-md",
-			detail: "缺少 SESSION.md"
+	const issues = [];
+	for (const s of sessions) {
+		const ageDays = (now - s.mtime.getTime()) / DAY;
+		const st = s.status;
+		if (ageDays > HEALTH_STALE_DAYS && !st.completed) issues.push({
+			dirName: s.dirName,
+			issue: `No activity for ${Math.floor(ageDays)}d`,
+			severity: "stale"
+		});
+		const totalTasks = st.completedCount + st.pendingCount;
+		if (totalTasks > 0) {
+			const pct = Math.round(st.completedCount / totalTasks * 100);
+			if (pct < HEALTH_STALLED_PCT && ageDays > HEALTH_STALLED_DAYS && !st.completed) issues.push({
+				dirName: s.dirName,
+				issue: `Only ${pct}% done after ${Math.floor(ageDays)}d`,
+				severity: "stalled"
+			});
+		}
+		if (!st.hasSessionMd && ageDays > HEALTH_GHOST_DAYS) issues.push({
+			dirName: s.dirName,
+			issue: "No SESSION.md (ghost directory)",
+			severity: "ghost"
 		});
-		else if (age > 14) problems.push({
-			dir: s.dir,
-			kind: "stale",
-			detail: `${Math.round(age)} 天未更新`
+		if (st.unresolvedCount > 3 && !st.completed) issues.push({
+			dirName: s.dirName,
+			issue: `${st.unresolvedCount} unresolved items`,
+			severity: "drift"
 		});
 	}
-	return problems;
+	if (issues.length === 0) return "All sessions healthy — no issues found.";
+	const lines = issues.map((i) => `[${i.severity.toUpperCase()}] ${i.dirName}: ${i.issue}`);
+	return `${issues.length} issue(s) found:\n` + lines.join("\n");
+}
+/** archive 子命令（对齐 osp archiveSessions：移动 _archived/；name 缺省批量） */
+function archiveSessions(root, opts) {
+	const { name, dryRun } = opts;
+	const sessionsDir = sessionsRoot(root);
+	const now = Date.now();
+	const archiveDir = join(sessionsDir, ARCHIVE_DIR_NAME);
+	if (name) {
+		const session = findSession(sessionsDir, name);
+		if (!session) throw new Error(`Session not found: "${name}"`);
+		if (!session.status.completed) return `Session "${session.dirName}" is not completed — skipping.`;
+		const ageDays = (now - session.mtime.getTime()) / DAY;
+		if (ageDays < 7) return `Session "${session.dirName}" completed ${Math.floor(ageDays)}d ago — needs ${7 - Math.floor(ageDays)} more days before archiving.`;
+		if (dryRun) return `[dry-run] Would archive: ${session.dirName} → ${ARCHIVE_DIR_NAME}/`;
+		if (!existsSync(archiveDir)) mkdirSync(archiveDir, { recursive: true });
+		renameSync(session.path, join(archiveDir, session.dirName));
+		return `Archived: ${session.dirName} → _archived/`;
+	}
+	const toArchive = readAllSessions(sessionsDir).filter((s) => {
+		if (!s.status.completed) return false;
+		return (now - s.mtime.getTime()) / DAY >= 7;
+	});
+	if (toArchive.length === 0) return "No sessions eligible for archiving.";
+	if (dryRun) return `[dry-run] Would archive ${toArchive.length} session(s):\n` + toArchive.map((s) => `  ${s.dirName}`).join("\n");
+	if (!existsSync(archiveDir)) mkdirSync(archiveDir, { recursive: true });
+	let count = 0;
+	for (const s of toArchive) {
+		renameSync(s.path, join(archiveDir, s.dirName));
+		count++;
+	}
+	return `Archived ${count} session(s) → _archived/`;
 }
+/** summary 子命令（对齐 osp sessionSummary 文本仪表盘） */
 function summarize(root) {
-	const sessions = listSessions(root);
-	const done = sessions.filter((s) => s.status === "done").length;
-	const stale = sessions.filter((s) => (Date.now() - new Date(s.mtime).getTime()) / DAY > 14).length;
-	return {
-		total: sessions.length,
-		open: sessions.length - done,
-		done,
-		stale,
-		recent: sessions.slice(0, 5)
-	};
+	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 sessions found — run \"session health\" for details.");
+	return lines.join("\n");
 }
-/** 事实核对：SESSION.md 中记录的产出物路径（- `path` — 说明 行）是否真实存在 */
+/** 事实核对：SESSION.md 声明 vs 实际情况（结构/一致性/新鲜度/决策质量/产出物） */
 function qaCheck(root, key) {
-	const { dir, content } = 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 `[ERROR] Session "${session.dirName}" has no SESSION.md — nothing to verify.`;
+	const content = readFileSync(mdPath, "utf-8");
 	const issues = [];
-	for (const line of content.split("\n")) {
-		const m = /^-\s*(`[^`]+`|[^\s|]+)\s*—/.exec(line.trim());
-		if (!m) continue;
-		const p = m[1].replace(/`/g, "");
-		if (!existsSync(resolve(root, p))) issues.push({
-			path: p,
-			kind: "missing"
+	for (const section of [
+		{
+			heading: "目标",
+			label: "目标 (goal)"
+		},
+		{
+			heading: "状态",
+			label: "状态 (status)"
+		},
+		{
+			heading: "关键决策",
+			label: "关键决策 (key decisions)"
+		},
+		{
+			heading: "进度记录",
+			label: "进度记录 (progress)"
+		},
+		{
+			heading: "产出物",
+			label: "产出物 (outputs)"
+		},
+		{
+			heading: "未解决的问题",
+			label: "未解决的问题 (unresolved)"
+		}
+	]) {
+		const headingRegex = new RegExp(`^##\\s*${section.heading}[\\s\\S]*?(?=^##|(?![\\s\\S]))`, "m");
+		const match = content.match(headingRegex);
+		if (!match) {
+			issues.push({
+				severity: "warning",
+				category: "structure",
+				message: `Missing section: ${section.label}`
+			});
+			continue;
+		}
+		const headingLineRegex = new RegExp(`^##\\s*${section.heading}\\s*$`, "m");
+		const body = match[0].replace(headingLineRegex, "").trim();
+		if (!body || /^[-*]\s*$/.test(body)) issues.push({
+			severity: "warning",
+			category: "structure",
+			message: `Section "${section.label}" is empty (only placeholder)`
 		});
 	}
-	return {
-		dir,
-		issues
-	};
+	const completedTasks = (content.match(/\[\s*x\s*\]/gi) ?? []).length;
+	const pendingTasks = (content.match(/\[\s*[ \t]\s*\]/gi) ?? []).length;
+	const statusSection = content.match(/^##\s*状态[\s\S]*?(?=^##|(?![^]))/im);
+	const statusBody = statusSection ? statusSection[0].replace(/^##\s*状态.*$/m, "").trim() : "";
+	const hasCompletionMark = statusBody ? /#+\s*(?:完成|done|completed|closed)\b/i.test(statusBody) || /(?:全部完成|已全部完成|所有.*任务.*完成|任务.*全部完成|已完成.*所有)/i.test(statusBody) : false;
+	const unresolvedSection = content.match(/^##\s*未解决的问题[\s\S]*?(?=^##|(?![^]))/im);
+	const unresolvedBody = unresolvedSection ? unresolvedSection[0].replace(/^##\s*未解决的问题.*$/m, "").trim() : "";
+	const unresolvedCount = unresolvedBody ? (unresolvedBody.match(/(?:未解决|open|question|TODO)/gi) ?? []).length : 0;
+	if (hasCompletionMark && pendingTasks > 0) issues.push({
+		severity: "error",
+		category: "consistency",
+		message: `Session marked as completed but has ${pendingTasks} pending task(s)`
+	});
+	if (hasCompletionMark && unresolvedCount > 0) issues.push({
+		severity: "warning",
+		category: "consistency",
+		message: `Session marked as completed but has ${unresolvedCount} unresolved item(s)`
+	});
+	if (completedTasks > 0 && pendingTasks === 0 && !hasCompletionMark) issues.push({
+		severity: "info",
+		category: "consistency",
+		message: `All ${completedTasks} task(s) completed but session not marked complete`
+	});
+	const progressSection = content.match(/##\s*进度记录[\s\S]*?(?=^##|\z)/m);
+	if (progressSection) {
+		const dateMatches = progressSection[0].match(/\b(\d{4}-\d{2}-\d{2})\b/g);
+		if (dateMatches && dateMatches.length > 0) {
+			const lastDateStr = dateMatches[dateMatches.length - 1];
+			const lastDate = new Date(lastDateStr);
+			const daysSince = Math.floor((Date.now() - lastDate.getTime()) / DAY);
+			if (daysSince > HEALTH_STALE_DAYS && pendingTasks > 0) issues.push({
+				severity: "warning",
+				category: "stale",
+				message: `No progress entry for ${daysSince} days (last: ${lastDateStr}), session still has ${pendingTasks} pending task(s)`
+			});
+		}
+	}
+	const decisionSection = content.match(/##\s*关键决策[\s\S]*?(?=^##|\z)/m);
+	if (decisionSection) {
+		const decisionLines = decisionSection[0].split("\n").filter((l) => /^\|\s*\d+\s*\|/.test(l));
+		if (decisionLines.length > 0) {
+			const emptyDecisions = decisionLines.filter((l) => {
+				const cells = l.split("|").map((c) => c.trim());
+				return cells.length >= 4 && (!cells[2] || !cells[3] || cells[2] === "-" || cells[3] === "-");
+			});
+			if (emptyDecisions.length > 0) issues.push({
+				severity: "info",
+				category: "quality",
+				message: `${emptyDecisions.length} decision(s) have empty reason — consider filling gaps`
+			});
+		} else if (!hasCompletionMark) issues.push({
+			severity: "info",
+			category: "quality",
+			message: "No decisions recorded yet — add key decisions as the session progresses"
+		});
+	}
+	const outputSection = content.match(/##\s*产出物[\s\S]*?(?=^##|\z)/m);
+	if (outputSection) {
+		const outputLines = outputSection[0].split("\n").filter((l) => /^\s*[-*]\s/.test(l));
+		const fileRefs = [];
+		for (const line of outputLines) {
+			const refs = line.match(/`[^`]+`/g) ?? [];
+			fileRefs.push(...refs.map((r) => r.replace(/`/g, "")));
+			const inlineRefs = line.match(/\b[\w./-]+\.[a-zA-Z]{1,5}\b/g) ?? [];
+			fileRefs.push(...inlineRefs.filter((r) => r.includes("/") || r.includes(".")));
+		}
+		if (fileRefs.length > 0) {
+			const missing = fileRefs.filter((ref) => !existsSync(join(root, ref)));
+			if (missing.length > 0 && completedTasks > 0) issues.push({
+				severity: "warning",
+				category: "outputs",
+				message: `${missing.length} referenced file(s) not found: ${missing.slice(0, 3).join(", ")}${missing.length > 3 ? `... (+${missing.length - 3} more)` : ""}`
+			});
+		}
+	}
+	const errorCount = issues.filter((i) => i.severity === "error").length;
+	const warningCount = issues.filter((i) => i.severity === "warning").length;
+	const infoCount = issues.filter((i) => i.severity === "info").length;
+	const verified = errorCount === 0 && warningCount === 0;
+	const lines = [
+		`QA Report: ${session.dirName}`,
+		`────────────────${"─".repeat(session.dirName.length)}`,
+		`Summary: ${issues.length} issue(s) found (${errorCount} error, ${warningCount} warning, ${infoCount} info)`,
+		`Status: ${verified ? "✓ Verified" : "⚠ Issues found"}`
+	];
+	if (issues.length > 0) {
+		lines.push("");
+		for (const issue of issues) {
+			const tag = issue.severity === "error" ? "ERR" : issue.severity === "warning" ? "WRN" : "INF";
+			lines.push(`  [${tag}:${issue.category}] ${issue.message}`);
+		}
+	}
+	lines.push("", "Recommendations:");
+	if (errorCount > 0) lines.push("  • Fix errors before closing the session (status vs content mismatch)");
+	if (warningCount > 0) lines.push("  • Review warnings — they may indicate incomplete or outdated information");
+	if (verified) lines.push("  • Session looks clean — no issues detected");
+	return lines.join("\n");
 }
 /** 追加会话心跳（turn-stopping 机械落盘用） */
 function appendHeartbeat(sessionMd) {
@@ -984,8 +1629,14 @@ function appendHeartbeat(sessionMd) {
 /**
 * session.ts — session 真实 DSH 工具定义（defineTool）
 *
-* AGENT_SESSIONS/ 全周期管理：list/show/create/health/qa/archive/summary。
-* 逻辑在 session-ops.ts（可单测）。
+* AGENT_SESSIONS/ 全周期管理：list/show/create/use/close/health/qa/archive/summary。
+* 行为对齐 osp（opencode-serenity-plugin/src/session/session-tool.ts）——osp 是 ACC 工具 spec：
+*   - create：--desc <desc> [--goal <goal>] 或 --issue <id>（二选一）
+*   - close：需 --confirm 防误关
+*   - archive：name 可缺省（批量归档）
+*   - hook-develop-guide 子命令 + CCC session-tool MSM 扩展提示（extHint）
+* CCC 扩展采用 osp 的"钩子后处理"模型（create-transform），而非整命令委派。
+* 活跃会话跟踪：写内存 Map（.dsh/active-sessions/<scope> 语义）+ events 恢复（S134）。
 */
 function agentCwd$6(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
@@ -1000,27 +1651,122 @@ function renderText$8(value) {
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
 	}];
 }
+/** 从 flags 中查找 name 匹配的 flag，仅在 new-style 对象上检查 */
+function findFlagByName(flags, name) {
+	if (!flags) return void 0;
+	for (const f of flags) if ("name" in f && f.name === name) return f;
+}
+/** 从 CCC 的 session-tool MSM flags 中提取支持的钩子名列表 */
+function discoverCccHooks(entries) {
+	const hookFlag = findFlagByName(entries.find((e) => e.name === "session-tool")?.flags, "hook");
+	if (!hookFlag?.description) return [];
+	return hookFlag.description.split("|").map((s) => s.trim()).filter(Boolean);
+}
+/** 从 CCC 的 session-tool MSM flags 中提取自定义子命令清单 */
+function discoverCccSubcommands(entries) {
+	const subFlag = findFlagByName(entries.find((e) => e.name === "session-tool")?.flags, "subcommand");
+	if (!subFlag?.description) return [];
+	return subFlag.description.split("|").map((s) => s.trim()).filter(Boolean);
+}
+/** 生成扩展提示（对齐 osp buildExtHint） */
+function buildExtHint(hasSessionTool, hooks, subcommands) {
+	if (!hasSessionTool) return "\n\n[CCC] 如需扩展会话能力，可注册 session-tool MSM (acc_msm register)，详见 session hook-develop-guide";
+	const parts = [];
+	if (hooks.length > 0) parts.push(`钩子: ${hooks.join(", ")}`);
+	if (subcommands.length > 0) parts.push(`扩展子命令 (acc_msm exec session-tool): ${subcommands.join(", ")}`);
+	return `\n\n[CCC] session-tool MSM 已注册${parts.length > 0 ? ` (${parts.join("; ")})` : ""}`;
+}
+/** hook-develop-guide 内容（对齐 osp getHookDevelopGuide） */
+function getHookDevelopGuide(hasSessionTool) {
+	return [
+		"═══ Session Extension Protocol (SEP) v1 — 开发指南 ═══",
+		"",
+		"CCC 可以通过注册 session-tool MSM 来扩展 ACC session 工具的能力，",
+		"而无需修改 plugin 代码。ACC 的行为不会缩水——CCC 只在 ACC 完成后做后处理。",
+		"",
+		"── 口子一：后处理钩子 (Hooks) ──",
+		"",
+		"ACC 的某些子命令执行完成后，会检查 CCC 的 session-tool MSM 是否",
+		"注册了对应的钩子。如果注册了，ACC 会调用 MSM 做后处理。",
+		"",
+		"可用钩子：",
+		"",
+		"  create-transform",
+		"    触发时机：create 写完默认 SESSION.md 后",
+		"    调用方式：acc_msm exec session-tool --hook=create-transform --session-dir=<path>",
+		"    允许行为：读取 SESSION.md，原地修改内容（追加字段、换模板、调 API 等）",
+		"    注意事项：ACC 已确保目录和 SESSION.md 存在，CCC 只做修改",
+		"",
+		"── 口子二：新子命令 (Custom Subcommands) ──",
+		"",
+		"LLM 可以直接调用 acc_msm exec session-tool <subcommand> 来执行 CCC 专属的子命令，",
+		"如 reindex、export、batch-create 等。这些子命令不走 ACC session tool 的 enum。",
+		"",
+		"── 如何注册 session-tool MSM ──",
+		"",
+		"1. 编写脚本，放在 CCC 的 skills 目录下：",
+		"     .opencode/skills/<ccc-name>/scripts/session-tool.ts",
+		"",
+		"2. 注册到 mech-registry.json：",
+		"     acc_msm register session-tool \\",
+		"       --skill <ccc-name> --path .opencode/skills/<ccc-name>/scripts/session-tool.ts \\",
+		"       --category semi-mech \\",
+		"       --description \"CCC session 扩展: 钩子 + 自定义子命令\" \\",
+		"       --flags '[",
+		"         {\"name\":\"hook\",\"type\":\"string\",\"description\":\"create-transform\"},",
+		"         {\"name\":\"subcommand\",\"type\":\"string\",\"description\":\"reindex | export\"},",
+		"         {\"name\":\"session-dir\",\"type\":\"path\",\"description\":\"session 目录路径\"},",
+		"         {\"name\":\"dry-run\",\"type\":\"boolean\",\"description\":\"预览模式\"}",
+		"       ]'",
+		"",
+		"3. 钩子声明约定：",
+		"     flags 中的 --hook description 字段按 | 分割枚举支持的钩子名。",
+		"     ACC 发现 create-transform 在列表中时，就会在 create 后调用。",
+		"",
+		"4. 子命令声明约定：",
+		"     flags 中的 --subcommand description 字段按 | 分割枚举支持的子命令名。",
+		"     LLM 看到提示后可调用 acc_msm exec session-tool <subcommand>。",
+		"",
+		hasSessionTool ? "✅ 当前 CCC 已注册 session-tool MSM" : "ℹ️  当前 CCC 尚未注册 session-tool MSM — 使用 acc_msm register 开始",
+		"",
+		"── 更多信息 ──",
+		"",
+		"参考 ACC 源码: src/tools/session.ts (hook 调用逻辑)"
+	].join("\n");
+}
 const sessionTool = defineTool({
 	name: "session",
-	description: "工作会话全周期管理（AGENT_SESSIONS/，home-session 约定）。list/show/create/use/close/health/qa/archive/summary。多步骤工作必须先 create 会话，use 激活当前 dsh 会话的活跃会话（写 .dsh/active-sessions/<scope> 标记 → 系统提示词 Session 块生效，按 dsh 会话隔离不泄露）。",
+	description: "工作会话全周期管理（AGENT_SESSIONS/，home-session 约定）。list/show/create/use/close/health/qa/archive/summary/hook-develop-guide。create 需 --desc <desc> [--goal] 或 --issue <工单号>（二选一）；close 需 --confirm；use 激活当前 dsh 会话的活跃会话（内存 + events 恢复，按 dsh 会话隔离不泄露）。",
 	parameters: {
 		action: {
 			type: "string",
 			enum: [...SESSION_ACTIONS],
 			required: true,
-			description: "子命令"
+			description: "子命令：list（状态摘要）/ show（S### 或目录名或模糊关键词）/ create（--desc 或 --issue）/ use（激活上下文，closed 可重开）/ close（需 --name + --confirm，不可撤销）/ health（stale/stalled/drift/ghost）/ qa（事实核对）/ archive（归档，name 缺省批量）/ summary（仪表盘）/ hook-develop-guide（CCC 扩展指南）"
 		},
-		key: {
+		name: {
 			type: "string",
-			description: "show/use/archive/qa 的会话标识（S### 或目录名或关键词）"
+			description: "show/use/close/archive/qa 的会话标识（S### 或目录名或关键词）"
 		},
-		name: {
+		desc: {
+			type: "string",
+			description: "create 的短描述（任意语言，≤5 词；与 issue 互斥）"
+		},
+		issue: {
 			type: "string",
-			description: "create 的短描述（小写英文连词符，≤5 词）"
+			description: "create 的工单号（如 apaas-26116；目录命名 YYYY-MM-DD--<issue>；与 desc 互斥）"
 		},
-		title: {
+		goal: {
 			type: "string",
-			description: "create 的标题"
+			description: "create 的一句话目标（可选）"
+		},
+		confirm: {
+			type: "boolean",
+			description: "close 必须为 true（防误关）"
+		},
+		dryRun: {
+			type: "boolean",
+			description: "create/archive 预览模式（不实际修改）"
 		}
 	},
 	output: {
@@ -1030,62 +1776,58 @@ const sessionTool = defineTool({
 	async execute(args, exec) {
 		const root = findSerenityRoot(agentCwd$6(exec));
 		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
-		if (findEntry(root, "session-tool")) {
-			const r = runMsm(root, {
-				action: "exec",
-				name: "session-tool",
-				args: [args.action, ...args.key ? [args.key] : []]
-			});
-			if (!(r.exit !== void 0 && r.exit !== 0 || r.ok === false)) {
-				const out = r.ok !== void 0 ? r.ok ? r.data : r.error : r.stdout;
-				return out !== void 0 ? {
-					delegated: true,
-					exit: r.exit ?? 0,
-					output: out
-				} : {
-					delegated: true,
-					exit: r.exit ?? 0
-				};
-			}
-		}
+		const entries = loadMsmEntries(root);
+		const hasSessionTool = entries.some((e) => e.name === "session-tool");
+		const cccHooks = discoverCccHooks(entries);
+		const extHint = buildExtHint(hasSessionTool, cccHooks, discoverCccSubcommands(entries));
+		if (args.action === "hook-develop-guide") return getHookDevelopGuide(hasSessionTool);
 		switch (args.action) {
-			case "list": return listSessions(root);
-			case "create": return createSession(root, args.name ?? "untitled", args.title ?? args.name ?? "untitled");
+			case "list": return listSessions(root) + extHint;
 			case "show":
-				if (!args.key) throw new Error("show 需要 key");
-				return showSession(root, args.key);
+				if (!args.name) throw new Error("show 需要 name（S### 或目录名）");
+				return showSession(root, args.name) + extHint;
+			case "create": {
+				const result = createSession({
+					root,
+					desc: args.desc,
+					issue: args.issue,
+					goal: args.goal,
+					dryRun: args.dryRun ?? false
+				});
+				let message = result.message;
+				if (!(args.dryRun ?? false) && cccHooks.includes("create-transform")) try {
+					const hookResult = await runMsmAsync(root, {
+						action: "exec",
+						name: "session-tool",
+						args: ["--hook=create-transform", `--session-dir=${result.sessionPath}`]
+					});
+					const hookOut = hookResult.ok !== void 0 && hookResult.ok === false ? hookResult.data ?? "" : hookResult.stdout ?? "";
+					message += `\n  [create-transform] ${hookOut.trim()}`;
+				} catch (err) {
+					message += `\n  [WARN] create-transform hook failed: ${err instanceof Error ? err.message : String(err)}`;
+				}
+				return message + extHint;
+			}
 			case "use":
-				if (!args.key) throw new Error("use 需要 key");
-				return useSession(root, args.key, agentScope$2(exec));
-			case "close": return closeSession(root, agentScope$2(exec));
-			case "archive":
-				if (!args.key) throw new Error("archive 需要 key");
-				return archiveSession(root, args.key);
-			case "health": return { problems: healthCheck(root) };
-			case "summary": return summarize(root);
+				if (!args.name) throw new Error("use 需要 name（S### 或目录名）");
+				return useSession(root, args.name, agentScope$2(exec));
+			case "close":
+				if (!args.name) throw new Error("close 需要 name（S### 或目录名）");
+				return closeSession(root, args.name, args.confirm ?? false, agentScope$2(exec));
+			case "archive": return archiveSessions(root, {
+				name: args.name,
+				dryRun: args.dryRun ?? false
+			}) + extHint;
+			case "health": return healthCheck(root) + extHint;
+			case "summary": return summarize(root) + extHint;
 			case "qa":
-				if (!args.key) throw new Error("qa 需要 key");
-				return qaCheck(root, args.key);
+				if (!args.name) throw new Error("qa 需要 name（S### 或目录名）");
+				return qaCheck(root, args.name) + extHint;
 			default: throw new Error(`未知 action: ${args.action}`);
 		}
 	}
 });
 //#endregion
-//#region src/constants.ts
-/** 常量（纯模块，零 DSH 依赖） */
-/**
-* ACC 版本：自动从 package.json 读取（单一真相源，消除与 CHANGELOG 的漂移）。
-* 发布时只需改 package.json 的 version。
-*/
-const ACC_VERSION = (() => {
-	try {
-		const here = dirname(fileURLToPath(import.meta.url));
-		return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8")).version ?? "0.0.0";
-	} catch {
-		return "0.0.0";
-	}
-})();
-//#endregion
 //#region src/seams/guards.ts
 /**
 * guards.ts — 拦截缝：安全模式 + 路径守卫（P3 语义的机械层）
@@ -1294,53 +2036,84 @@ function setSafeMode(root, on) {
 /**
 * kit-ops.ts — acc_kit 纯操作层（零 DSH 依赖）
 *
-* health: CCC 三原则检查（P1 .serenity / P2 git / 配置）
-* time: ISO 8601 时间戳
-* wait: 等待 N 秒（纯 Node setTimeout——不依赖外部 sleep 可执行文件，
-*       Windows 无 GNU coreutils sleep，spawn 必 ENOENT，见 Windows 兼容审计问题 3）
+* 行为对齐 osp（opencode-serenity-plugin/src/acc-kit.ts）——osp 是 ACC 工具 spec：
+*   - health：{ccc, root, version, status: healthy|degraded, principles: {P1_rooted, P2_git_managed, P3_binary_permissions}}
+*   - time：{now_iso, now_local, epoch_ms}
+*   - wait：缺省 1s（正整数秒），返回 'waited Ns' 文本
+* 平台适配：P3 在 osp 检查 opencode.json，DSH 无 opencode.json → 检查 DSH/opencode 配置路径
+* （.opencode/serenity.json / .dsh/serenity.json 等，见 DEFAULT_SERENITY_CONFIG_PATHS）。
+* CCC 缺失时返回 degraded 报告而非抛错（对齐 osp 未激活语义）。
+* 保留 dsp 增强：accVersion/dshVersion 版本自省字段。
+* wait 用纯 Node setTimeout——不依赖外部 sleep 可执行文件（Windows 无 GNU coreutils sleep）。
 */
 const KIT_ACTIONS = [
 	"health",
 	"time",
 	"wait"
 ];
+/** CCC 名：从 .serenity 首行解析（对齐 osp readSerenityCccName） */
+function readCccName(root) {
+	if (!root) return null;
+	try {
+		return readFileSync(resolve(root, ".serenity"), "utf-8").trim().split("\n")[0]?.trim() || null;
+	} catch {
+		return null;
+	}
+}
 async function runKit(root, args) {
 	switch (args.action) {
 		case "health": {
-			const gitRoot = findGitRoot(root);
-			let config = null;
-			let configPath = null;
-			for (const candidate of DEFAULT_SERENITY_CONFIG_PATHS) {
-				const p = resolve(root, candidate);
-				if (!existsSync(p)) continue;
-				try {
-					config = JSON.parse(readFileSync(p, "utf-8"));
-					configPath = p;
-				} catch {
-					config = { parseError: true };
-					configPath = p;
+			const cccName = readCccName(root);
+			const serenityPath = root ? resolve(root, ".serenity") : null;
+			const p1Pass = serenityPath !== null && existsSync(serenityPath) && statSync(serenityPath).size > 0;
+			const p2Pass = (root ? findGitRoot(root) : null) !== null;
+			let p3Pass = false;
+			let p3Detail = "config not found at CCC root";
+			if (root) {
+				for (const candidate of DEFAULT_SERENITY_CONFIG_PATHS) if (existsSync(resolve(root, candidate))) {
+					p3Pass = true;
+					p3Detail = `${candidate} found`;
+					break;
 				}
-				break;
 			}
+			const report = {
+				ccc: cccName,
+				root,
+				version: ACC_VERSION,
+				status: p1Pass && p2Pass && p3Pass ? "healthy" : "degraded",
+				principles: {
+					P1_rooted: {
+						pass: p1Pass,
+						detail: p1Pass ? ".serenity marker found" : ".serenity marker missing"
+					},
+					P2_git_managed: {
+						pass: p2Pass,
+						detail: p2Pass ? "git repository verified" : "not in a git repository"
+					},
+					P3_binary_permissions: {
+						pass: p3Pass,
+						detail: p3Detail
+					}
+				}
+			};
+			if (root) report.config = loadSerenityConfig(root);
+			report.accVersion = ACC_VERSION;
+			report.dshVersion = readDshVersion();
+			return report;
+		}
+		case "time": {
+			const now = /* @__PURE__ */ new Date();
 			return {
-				cwd: root,
-				serenityRoot: findSerenityRoot(root),
-				gitRoot,
-				config,
-				configPath,
-				p1: findSerenityRoot(root) !== null,
-				p2: gitRoot !== null,
-				p3: "enforced-by-dsh-fs-sandbox",
-				accVersion: ACC_VERSION,
-				dshVersion: readDshVersion()
+				now_iso: now.toISOString(),
+				now_local: now.toString(),
+				epoch_ms: now.getTime()
 			};
 		}
-		case "time": return (/* @__PURE__ */ new Date()).toISOString();
 		case "wait": {
-			const n = args.seconds ?? 0;
-			if (!Number.isFinite(n) || n < 0) throw new Error("wait 需要非负秒数");
-			await new Promise((r) => setTimeout(r, Math.round(n * 1e3)));
-			return { waited: n };
+			const seconds = args.seconds ?? 1;
+			if (!Number.isInteger(seconds) || seconds <= 0) throw new Error("wait 需要正整数秒数（缺省 1）");
+			await new Promise((r) => setTimeout(r, seconds * 1e3));
+			return `waited ${seconds}s`;
 		}
 		default: throw new Error(`未知 action: ${args.action}`);
 	}
@@ -1361,7 +2134,7 @@ function renderText$7(value) {
 }
 const kitTool = defineTool({
 	name: "acc_kit",
-	description: "ACC 通用能力工具包：health（CCC 三原则检查 P1/P2/配置）/ time（ISO 时间戳）/ wait（等待 N 秒）。进入 CCC 工作前的例行自检。",
+	description: "ACC 通用能力工具包：health（CCC 三原则检查 P1/P2/配置，healthy/degraded 报告）/ time（now_iso/now_local/epoch_ms）/ wait（等待 N 秒，缺省 1）。进入 CCC 工作前的例行自检。",
 	parameters: {
 		action: {
 			type: "string",
@@ -1370,8 +2143,8 @@ const kitTool = defineTool({
 			description: "子命令"
 		},
 		seconds: {
-			type: "number",
-			description: "wait 的秒数"
+			type: "integer",
+			description: "wait 的秒数（正整数，缺省 1）"
 		}
 	},
 	output: {
@@ -1379,9 +2152,7 @@ const kitTool = defineTool({
 		render: (args, value) => renderText$7(value)
 	},
 	async execute(args, exec) {
-		const root = findSerenityRoot(agentCwd$5(exec));
-		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
-		return await runKit(root, args);
+		return await runKit(findSerenityRoot(agentCwd$5(exec)), args);
 	}
 });
 //#endregion
@@ -1661,37 +2432,62 @@ function runLocalStore(root, args) {
 /**
 * git-ops.ts — cc_git 纯操作层（零 DSH 依赖）
 *
-* status / commit / push / log；push 非快进时输出操作建议（绝不自动 force）。
+* 行为对齐 osp（opencode-serenity-plugin/src/git/cc-git-tool.ts）——osp 是 ACC 工具 spec：
+*   - status：JSON {clean, files:[{status,file}], summary}
+*   - commit：git add -A + commit -m；clean 返回 '(nothing to commit — working tree clean)'
+*   - push：无 remote 报错；非快进 → [REJECTED] + 操作建议（绝不自动 force）
+*   - pull：git fetch + merge --ff-only；up-to-date / [REJECTED] 建议
+*   - log：--oneline [-n <count>]
+*   - diff：git diff [--cached] [<ref>] [-- <path>]
+* 保留 dsp 增强：localstore git 合规联动（S134：deny 且 .gitignore 未覆盖 → status 提示 / commit 拒绝）。
 */
 const GIT_ACTIONS = [
 	"status",
 	"commit",
 	"push",
-	"log"
+	"log",
+	"pull",
+	"diff"
 ];
 function git(root, args) {
 	try {
 		return {
-			ok: true,
 			stdout: execFileSync("git", args, {
 				cwd: root,
-				encoding: "utf-8",
+				encoding: "utf8",
 				stdio: [
-					"pipe",
+					"ignore",
 					"pipe",
 					"pipe"
-				]
-			}),
+				],
+				maxBuffer: 1048576
+			}).trimEnd(),
 			stderr: ""
 		};
 	} catch (err) {
 		return {
-			ok: false,
-			stdout: err.stdout?.toString() ?? "",
-			stderr: err.stderr?.toString() ?? ""
+			stdout: (err.stdout?.toString() ?? "").trimEnd(),
+			stderr: (err.stderr?.toString() ?? "").trimEnd()
 		};
 	}
 }
+function getCurrentBranch(root) {
+	const { stdout } = git(root, [
+		"rev-parse",
+		"--abbrev-ref",
+		"HEAD"
+	]);
+	if (!stdout) throw new Error("cc_git: cannot determine current branch");
+	return stdout;
+}
+function hasChanges(root) {
+	const { stdout } = git(root, ["status", "--porcelain"]);
+	return stdout.length > 0;
+}
+function hasRemote(root) {
+	const { stdout } = git(root, ["remote"]);
+	return stdout.length > 0;
+}
 function runGit(root, args) {
 	switch (args.action) {
 		case "status": {
@@ -1701,10 +2497,17 @@ function runGit(root, args) {
 				"status",
 				"--porcelain"
 			]);
-			if (!r.ok) throw new Error(`status 失败：${r.stderr.trim()}`);
+			if (r.stderr) throw new Error(`status 失败：${r.stderr.trim()}`);
+			const files = (r.stdout ? r.stdout.split("\n") : []).map((line) => {
+				return {
+					status: line.slice(0, 2).trim() || "??",
+					file: line.slice(3)
+				};
+			});
 			const out = {
-				clean: r.stdout.trim() === "",
-				entries: r.stdout.trim() ? r.stdout.trim().split("\n") : []
+				clean: files.length === 0,
+				files,
+				summary: files.length === 0 ? "(clean)" : `${files.length} file(s) with changes`
 			};
 			const ls = checkLocalstoreGitCompliance(root);
 			if (!ls.ok) out.warning = ls.reason;
@@ -1713,44 +2516,68 @@ function runGit(root, args) {
 		case "commit": {
 			const ls = checkLocalstoreGitCompliance(root);
 			if (!ls.ok) throw new Error(ls.reason);
-			if (!args.message) throw new Error("commit 需要 message");
-			const add = git(root, ["add", "-A"]);
-			if (!add.ok) throw new Error(`git add 失败：${add.stderr.trim()}`);
-			const commit = git(root, [
+			if (!args.message || args.message.trim() === "") throw new Error("cc_git commit: missing required arg \"message\"");
+			if (!hasChanges(root)) return "(nothing to commit — working tree clean)";
+			const addResult = git(root, ["add", "-A"]);
+			if (addResult.stderr) throw new Error(`cc_git commit: git add failed\n${addResult.stderr}`);
+			const commitResult = git(root, [
 				"commit",
 				"-m",
 				args.message
 			]);
-			if (!commit.ok) {
-				if (commit.stderr.includes("nothing to commit")) return {
-					committed: false,
-					reason: "nothing to commit"
-				};
-				throw new Error(`git commit 失败：${commit.stderr.trim()}`);
-			}
-			return {
-				committed: true,
-				message: args.message
-			};
+			if (commitResult.stderr && commitResult.stderr.includes("nothing to commit")) return "(nothing to commit — working tree clean)";
+			if (commitResult.stderr && !commitResult.stdout) throw new Error(`cc_git commit: git commit failed\n${commitResult.stderr}`);
+			return (commitResult.stdout || commitResult.stderr || "committed").trimEnd();
 		}
 		case "push": {
-			const r = git(root, [
+			if (!hasRemote(root)) throw new Error("cc_git push: no remote configured. Add one with:\n  git remote add origin <url>");
+			const branch = getCurrentBranch(root);
+			try {
+				git(root, [
+					"fetch",
+					"origin",
+					branch
+				]);
+			} catch {}
+			const { stdout, stderr } = git(root, [
 				"push",
 				"origin",
-				"HEAD"
+				branch
 			]);
-			if (r.ok) return { pushed: true };
-			const isNonFF = /non-fast-forward|rejected|fetch first|被拒绝/i.test(r.stderr);
-			const out = {
-				pushed: false,
-				nonFastForward: isNonFF,
-				stderr: r.stderr.trim()
-			};
-			if (isNonFF) out.suggestion = "1. git pull --rebase  # 先合并远程变更\n2. 重新 push\n3. 若确需覆盖远程：git push --force-with-lease（人工确认后）";
-			return out;
+			if (!stderr || stderr.includes("->") || stderr === "") return stdout || `Pushed to origin/${branch}`;
+			if (stderr.includes("non-fast-forward") || stderr.includes("rejected") || stderr.includes("[rejected]")) return `[REJECTED] Push to origin/${branch} was rejected (non-fast-forward).\n\n远程有新的提交，本地落后。操作建议：\n  1. 先用 bash: git fetch origin ${branch}\n  2. 查看远程变更: git log HEAD..origin/${branch}\n  3. 合并或变基: git merge origin/${branch} 或 git rebase origin/${branch}\n  4. 有冲突则手动解决后: git add ... && git commit\n  5. 再次推送: cc_git push`;
+			throw new Error(`cc_git push failed:\n${stderr}`);
+		}
+		case "pull": {
+			if (!hasRemote(root)) throw new Error("cc_git pull: no remote configured. Add one with:\n  git remote add origin <url>");
+			const branch = getCurrentBranch(root);
+			const fetchResult = git(root, [
+				"fetch",
+				"origin",
+				branch
+			]);
+			if (fetchResult.stderr) return `[WARN] fetch had stderr:\n${fetchResult.stderr}`;
+			const revResult = git(root, [
+				"rev-list",
+				"--count",
+				"HEAD..FETCH_HEAD"
+			]);
+			if (revResult.stderr) return `[WARN] cannot check ahead count:\n${revResult.stderr}`;
+			if (revResult.stdout === "0" || revResult.stdout === "") return "Already up to date.";
+			const mergeResult = git(root, [
+				"merge",
+				"--ff-only",
+				"FETCH_HEAD"
+			]);
+			if (!mergeResult.stderr) {
+				const msg = mergeResult.stdout || "Pulled successfully.";
+				return msg.endsWith("\n") ? msg.trimEnd() : msg;
+			}
+			if (mergeResult.stderr.includes("non-fast-forward") || mergeResult.stderr.includes("Not possible to fast-forward") || mergeResult.stderr.includes("rejected") || mergeResult.stderr.includes("could not be applied")) return `[REJECTED] Pull from origin/${branch} was rejected (non-fast-forward).\n\n远程有新的提交，本地的历史与远程产生了分歧（非快进）。操作建议：\n  1. 查看差异: cc_git log HEAD..origin/${branch}\n  2. 用 bash 手动合并: git merge origin/${branch}\n  3. 或用 rebase: git rebase origin/${branch}\n  4. 有冲突则手动解决后: git add <file> && git commit\n  5. 推送: cc_git push`;
+			throw new Error(`cc_git pull failed:\n${mergeResult.stderr}`);
 		}
 		case "log": {
-			const n = args.count ?? 10;
+			const n = Math.min(Math.max(args.count ?? 10, 1), 100);
 			const r = git(root, [
 				"-c",
 				"core.quotepath=false",
@@ -1759,8 +2586,19 @@ function runGit(root, args) {
 				"-n",
 				String(n)
 			]);
-			if (!r.ok) throw new Error(`git log 失败：${r.stderr.trim()}`);
-			return { entries: r.stdout.trim() ? r.stdout.trim().split("\n") : [] };
+			if (r.stderr) throw new Error(`git log 失败：${r.stderr.trim()}`);
+			if (!r.stdout) return "(no commits)";
+			return r.stdout;
+		}
+		case "diff": {
+			const diffArgs = ["diff"];
+			if (args.staged) diffArgs.push("--cached");
+			if (args.ref) diffArgs.push(args.ref);
+			if (args.path) diffArgs.push("--", args.path);
+			const { stdout, stderr } = git(root, diffArgs);
+			if (stderr) return `[WARN] git diff had stderr:\n${stderr}`;
+			if (!stdout) return "(no diff)";
+			return stdout;
 		}
 		default: throw new Error(`未知 action: ${args.action}`);
 	}
@@ -1781,21 +2619,35 @@ function renderText$6(value) {
 }
 const gitTool = defineTool({
 	name: "cc_git",
-	description: "CCC 内 git 操作（cc-git 语义）。status/commit/push/log；push 非快进时输出操作建议（绝不自动 force）。pull/merge/rebase/冲突解决走 bash。",
+	description: "CCC 内 git 操作（cc-git 语义，对齐 osp）。status/commit/push/log/pull/diff；push/pull 非快进时输出 [REJECTED] + 操作建议（绝不自动 force）。merge/rebase/冲突解决走 bash。",
 	parameters: {
 		action: {
 			type: "string",
 			enum: [...GIT_ACTIONS],
 			required: true,
-			description: "子命令"
+			description: "子命令：status/commit/push/log/pull/diff"
 		},
 		message: {
 			type: "string",
-			description: "commit 消息"
+			description: "commit 消息（commit 必填）"
 		},
 		count: {
 			type: "integer",
-			description: "log 条数（默认 10）"
+			minimum: 1,
+			maximum: 100,
+			description: "log 条数（默认 10，max 100）"
+		},
+		staged: {
+			type: "boolean",
+			description: "diff: 显示暂存区变更（--cached）"
+		},
+		ref: {
+			type: "string",
+			description: "diff: 对比 ref（如 HEAD~1 / main / origin/main）"
+		},
+		path: {
+			type: "string",
+			description: "diff: 限定路径（如 src/、package.json）"
 		}
 	},
 	output: {
@@ -1824,13 +2676,13 @@ function renderText$5(value) {
 }
 const msmTool = defineTool({
 	name: "acc_msm",
-	description: "MSM（Mech & Semi-Mech）框架：list 列出注册 MSM；exec 执行（600s 超时，path 逃逸阻断）；register/deregister 管理注册表（自动 git commit）；check 品质检查 DC-M1~M4。复用 CCC 的 mech-registry.json。",
+	description: "MSM（Mech & Semi-Mech）框架：list 列出注册 MSM（header+flags 展示）；exec 执行（600s 超时，path 逃逸+symlink 阻断，注入 SERENITY_ROOT/CCC/VERSION env，失败追加 --help TIP；参数首位 --list/--schema/--format=json 为协议）；register/deregister 管理注册表（path 根内+脚本存在+全局唯一校验，自动 git 精提交）；check 品质检查 DC-M1~M4；guide 开发手册；ccc-config CCC 配置参考（loop.defaultModel/sessionKeeper.threshold/localstore.gitTrack/hooks.autoRestoreSession）。复用 CCC 的 mech-registry.json。",
 	parameters: {
 		action: {
 			type: "string",
 			enum: [...MSM_ACTIONS],
 			required: true,
-			description: "子命令"
+			description: "子命令：list/exec/register/deregister/check/guide/ccc-config"
 		},
 		name: {
 			type: "string",
@@ -1839,7 +2691,7 @@ const msmTool = defineTool({
 		args: {
 			type: "array",
 			items: { type: "string" },
-			description: "exec 的业务参数"
+			description: "exec 的业务参数（参数首位 --list/--schema <n>/--format=json 为协议 flag，其余无损透传）"
 		},
 		skill: {
 			type: "string",
@@ -1847,7 +2699,7 @@ const msmTool = defineTool({
 		},
 		path: {
 			type: "string",
-			description: "register 的脚本相对路径"
+			description: "register 的脚本相对路径（必须根内且存在）"
 		},
 		category: {
 			type: "string",
@@ -1856,6 +2708,14 @@ const msmTool = defineTool({
 		description: {
 			type: "string",
 			description: "register 的描述"
+		},
+		flags: {
+			type: "string",
+			description: "register 的 flags JSON 字符串（new-style 对象数组，type:\"path\" 启用逃逸校验）"
+		},
+		usage: {
+			type: "string",
+			description: "register 的自定义 usage（缺省自动生成）"
 		}
 	},
 	output: {
@@ -2136,6 +2996,7 @@ function writeProgress(root, label, p) {
 	mkdirSync(join(root, "AGENT_SESSIONS"), { recursive: true });
 	writeFileSync(json, JSON.stringify({
 		...p,
+		status: p.status ?? "running",
 		updated: (/* @__PURE__ */ new Date()).toISOString()
 	}, null, 2) + "\n", "utf-8");
 	const lines = [
@@ -2151,6 +3012,23 @@ function writeProgress(root, label, p) {
 	];
 	writeFileSync(md, lines.join("\n"), "utf-8");
 }
+/** 失败状态落盘（对齐 osp writeFailedStatus：done=true / status=failed / errorCode） */
+function writeFailedStatus(root, label, info) {
+	const { json } = loopProgressPaths(root, label);
+	mkdirSync(join(root, "AGENT_SESSIONS"), { recursive: true });
+	const prev = readProgress(root, label);
+	writeFileSync(json, JSON.stringify({
+		round: prev?.round ?? 0,
+		done: true,
+		label,
+		model: prev?.model ?? "",
+		status: "failed",
+		errorCode: info.errorCode,
+		errorMessage: info.errorMessage,
+		updated: (/* @__PURE__ */ new Date()).toISOString(),
+		lastResponse: prev?.lastResponse ?? ""
+	}, null, 2) + "\n", "utf-8");
+}
 function newStopToken() {
 	return `SERENITY_LOOP_DONE_${randomBytes(8).toString("hex")}`;
 }
@@ -2224,7 +3102,7 @@ const LOOP_GUIDE = `# loop — 规模化使用指引（guide）
 - 汇总：并行 loop 各自产出进度后，主 agent 汇总合并（或再派一个汇总 loop）
 
 ## 完成判定
-- 唯一完成条件 = loop 内部 agent 精确回显本轮随机验证码（stop token）；对话轮次无上限（不完成不返回）
+- 唯一完成条件 = loop 内部 agent 精确回显本轮随机验证码（stop token）；对话轮次上限 100（对齐 osp 保险阀，超限强制结束可续跑）
 - agent 非正常停止时自动重启（≤100 次防死循环）
 
 ## 等待界面
@@ -2317,16 +3195,17 @@ function lastAssistantText(agent) {
 function createLoopTool(ctx) {
 	return defineTool({
 		name: "loop",
-		description: "牛马循环（老 loop 等效）：用指定模型创建专用 agent 反复执行任务直到完成。\n用法：loop guide（输出规模化使用指引——使用前先加载 eap 设计规模化方案）；loop 接受 task（要完成的目标）或依赖 session 上下文；模型缺省读 .opencode/serenity.json 的 loop.defaultModel（当前 minimax-cn-coding-plan/MiniMax-M3，廉价牛马）。\n行为：内部硬性 while 循环驱动 agent 逐轮推进任务，每轮等待无超时（agent 工作多久等多久）。唯一完成条件 = agent 精确回显本轮随机完成码（stop token），防止低智能模型提前结束。轮次不需要调用者指定——对话轮次**无上限**（不完成不返回），agent 非正常停止时自动重启（重启 ≤100 次，防死循环保险阀）。\n进度：写入 AGENT_SESSIONS/loop-<label>.md/.json；同 label 再次调用从上次轮次续跑（不重做）。\n约束：loop agent 受完整 Serenity 约束（ACC 身份/入口技能系统提示词/守卫/session-keeper）。\n示例：loop 执行「扫描 SQC 并修复 DC 问题」，label: sqc-scan；loop guide",
+		description: "牛马循环（老 loop 等效）：用指定模型创建专用 agent 反复执行任务直到完成。\n用法：loop guide（输出规模化使用指引——使用前先加载 eap 设计规模化方案）；loop 接受 task（要完成的目标）或依赖 session 上下文；模型缺省读 .opencode/serenity.json 的 loop.defaultModel（当前 minimax-cn-coding-plan/MiniMax-M3，廉价牛马）。\n行为：内部硬性 while 循环驱动 agent 逐轮推进任务，每轮等待无超时（agent 工作多久等多久）。唯一完成条件 = agent 精确回显本轮随机完成码（stop token），防止低智能模型提前结束。轮次不需要调用者指定——对话轮次上限 100（对齐 osp 保险阀，超限强制结束可续跑），agent 非正常停止时自动重启（重启 ≤100 次，防死循环保险阀）。\n进度：写入 AGENT_SESSIONS/loop-<label>.md/.json；同 label 再次调用从上次轮次续跑（不重做）。\n约束：loop agent 受完整 Serenity 约束（ACC 身份/入口技能系统提示词/守卫/session-keeper）。\n示例：loop 执行「扫描 SQC 并修复 DC 问题」，label: sqc-scan；loop guide",
 		parameters: {
 			task: {
 				type: "string",
-				description: "要完成的任务目标（必填语义：告诉 loop agent 做什么；缺省则从 session 上下文推断）"
+				required: true,
+				description: "要完成的任务目标（必填：告诉 loop agent 做什么）"
 			},
 			label: {
 				type: "string",
 				required: true,
-				description: "任务标签（进度文件命名 loop-<label>.md/.json）"
+				description: "任务标签（1-50 字符；进度文件命名 loop-<label>.md/.json）"
 			},
 			session: {
 				type: "string",
@@ -2387,9 +3266,14 @@ function createLoopTool(ctx) {
 			let lastResponse = progress?.lastResponse ?? "";
 			let finalRound = startRound - 1;
 			let restarts = 0;
+			let finishReason = "done";
 			try {
 				let round = startRound;
 				while (true) {
+					if (round > 100) {
+						finishReason = "max_rounds";
+						break;
+					}
 					finalRound = round;
 					const prompt = buildRoundPrompt({
 						root,
@@ -2415,7 +3299,10 @@ function createLoopTool(ctx) {
 						lastResponse = lastAssistantText(loopAgent);
 					} catch {
 						restarts++;
-						if (restarts > 100) break;
+						if (restarts > 100) {
+							finishReason = "restart_exceeded";
+							break;
+						}
 						await handle.dispose().catch(() => {});
 						await spawnAgent();
 						continue;
@@ -2431,6 +3318,7 @@ function createLoopTool(ctx) {
 					writeProgress(root, label, progress);
 					if (lastResponse.includes(stopToken)) {
 						done = true;
+						finishReason = "done";
 						break;
 					}
 					round++;
@@ -2441,7 +3329,12 @@ function createLoopTool(ctx) {
 					label,
 					model,
 					updated: (/* @__PURE__ */ new Date()).toISOString(),
-					lastResponse
+					lastResponse,
+					status: done ? "done" : "running"
+				});
+				if (finishReason !== "done") writeFailedStatus(root, label, {
+					errorCode: finishReason,
+					errorMessage: finishReason === "max_rounds" ? `Reached 100 rounds without completion — resume with same label to continue.` : `Agent restarted 100 times without progress — resume with same label to continue.`
 				});
 			} finally {
 				await handle.dispose().catch(() => {});
@@ -2450,16 +3343,17 @@ function createLoopTool(ctx) {
 			return {
 				done,
 				rounds: finalRound,
+				finishReason,
 				restarts,
 				model,
 				label,
 				progressFile: json,
 				lastResponse: lastResponse.slice(0, 2e3),
 				usage: {
-					how: "loop 内部硬性 while 驱动 agent 逐轮推进，agent 精确回显随机完成码即终止；对话轮次无上限（不完成不返回），agent 非正常停止时自动重启（≤100 次）",
+					how: `loop 内部硬性 while 驱动 agent 逐轮推进，agent 精确回显随机完成码即终止；对话轮次上限 100（对齐 osp 保险阀），agent 非正常停止时自动重启（≤100 次）`,
 					progress: `进度在 AGENT_SESSIONS/loop-${label}.md 与 .json；同 label 再调 loop 会从下一轮续跑（不重做）`,
 					constraints: "loop agent 受完整 Serenity 约束（ACC 身份/入口技能系统提示词/守卫）",
-					next: done ? "任务已完成；可查看进度文件收尾" : `任务未完成（已达内部 100 次重启保险阀）；可同 label 续跑`
+					next: done ? "任务已完成；可查看进度文件收尾" : `任务未完成（${finishReason}，已达 100 轮或 100 次重启保险阀）；可同 label 续跑`
 				}
 			};
 		}
@@ -3113,10 +4007,14 @@ function registerContext(ctx, opts = {}) {
 		if (!root) return;
 		const key = agentKey(agent);
 		registerEntrySkillSection(agent, root);
-		if (shouldRestoreActive(agent)) try {
+		const scope = agentScope(agent);
+		if (shouldRestoreActive(agent) && getActiveSessionInfo(scope) === null) try {
 			if (loadSerenityConfig(root, configPaths).hooks?.autoRestoreSession ?? true) {
-				const restored = restoreActiveSession(root, agentScope(agent));
-				if (restored) console.log(`[serenity-hooks] ↻ 自动恢复激活会话: ${restored.dir}（from scope ${restored.from}）`);
+				const info = parseSessionContextFromEvents(agent.session.events ?? []);
+				if (info) {
+					setActiveSessionInfo(scope, info);
+					console.log(`[serenity-hooks] ↻ 从历史恢复激活会话: ${info.dirName}`);
+				}
 			}
 		} catch {}
 		if (injected.has(key)) return;