@shgroup/dsh-serenity-hooks 1.24.12 → 1.25.0

package/lib/index.js

@@ -510,10 +510,10 @@ function runCcFs(root, args) {
 * 进程内注册（取代 v0.1 的 bash spawn runner）：zod/schemastery 参数校验、
 * 规范 JSON 输出、纯 render 投影。逻辑在 fs-ops.ts（可单测）。
 */
-function agentCwd$8(exec) {
+function agentCwd$9(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
-function renderText$10(value) {
+function renderText$11(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -585,10 +585,10 @@ const ccFsTool = defineTool({
 	},
 	output: {
 		schema: { type: "json" },
-		render: (args, value) => renderText$10(value)
+		render: (args, value) => renderText$11(value)
 	},
 	async execute(args, exec) {
-		const root = findSerenityRoot(agentCwd$8(exec));
+		const root = findSerenityRoot(agentCwd$9(exec));
 		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 		return runCcFs(root, args);
 	}
@@ -609,6 +609,109 @@ const ACC_VERSION = (() => {
 	}
 })();
 //#endregion
+//#region src/skiff-role.ts
+/**
+* skiff-role.ts — Skiff（F4，v1.25.0 实验性）角色层纯逻辑（零 DSH 依赖，可独立单测）
+*
+* 概念（S142 用户拍板）：Skiff = 完整宁静号 trajectory（在宁静号内全知全能）的
+* **任意子集**——CCC 通过角色配置定义：能力面（tools 非 MSM 工具白名单 + msms
+* MSM 白名单，双白名单独立，白名单外全隐藏）+ 轨迹纪律面（trajectory 子集）+
+* 系统提示词（CCC 完整定义，dsp 只给基础部分）。
+*
+* 实验性质：未配置任何角色 → Skiff 完全零影响（无监听、无 agent 创建、guard 无规则）。
+*/
+/** Skiff agent 会话 id 前缀（agents.create 生成；seams 旁路/白名单判定用） */
+const SKIFF_SESSION_PREFIX = "skiff-";
+/** 判定 sessionId 是否为 Skiff 会话（仿 handyman- 前缀排除模式） */
+function isSkiffSessionId(sessionId) {
+	return typeof sessionId === "string" && sessionId.startsWith("skiff-");
+}
+/**
+* 读取 CCC 的 Skiff 角色配置（.opencode/serenity.json skiff.roles）。
+* @returns 名 → 角色配置 的 Map；未配置（无 skiff 段/空 roles）返回空 Map（Skiff 未启用）
+*/
+function readSkiffRoles(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const out = /* @__PURE__ */ new Map();
+	try {
+		const roles = loadSerenityConfig(root, paths).skiff?.roles;
+		if (!roles || typeof roles !== "object") return out;
+		for (const [name, role] of Object.entries(roles)) {
+			if (!role || typeof role !== "object") continue;
+			if (name.trim() === "") continue;
+			out.set(name.trim(), {
+				model: typeof role.model === "string" ? role.model : void 0,
+				msms: Array.isArray(role.msms) ? role.msms.filter((m) => typeof m === "string") : void 0,
+				tools: Array.isArray(role.tools) ? role.tools.filter((t) => typeof t === "string") : void 0,
+				trajectory: role.trajectory && typeof role.trajectory === "object" ? {
+					session: role.trajectory.session === true,
+					keeper: role.trajectory.keeper === true,
+					rebuild: role.trajectory.rebuild === true
+				} : void 0,
+				systemPrompt: typeof role.systemPrompt === "string" ? role.systemPrompt : void 0
+			});
+		}
+	} catch {}
+	return out;
+}
+function trajectorySubset(role) {
+	return {
+		session: role?.trajectory?.session === true,
+		keeper: role?.trajectory?.keeper === true,
+		rebuild: role?.trajectory?.rebuild === true
+	};
+}
+/** 角色可用工具面（白名单并集）：tools + acc_msm（msms 非空时作为 MSM 通道自动可用） */
+function roleToolWhitelist(role) {
+	const out = /* @__PURE__ */ new Set();
+	for (const t of role?.tools ?? []) out.add(t);
+	if ((role?.msms?.length ?? 0) > 0) out.add("acc_msm");
+	return out;
+}
+/** 角色允许的 MSM 白名单（acc_msm exec 校验 / msm_list 过滤用；独立于 tools 白名单） */
+function roleMsmWhitelist(role) {
+	return new Set(role?.msms ?? []);
+}
+/**
+* Skiff 基础提示词（dsp 只给这部分；CCC 的 systemPrompt 段由调用方拼接）：
+* 身份 + 可用 MSM/工具清单 + 调用协议 + 边界声明。动态生成（清单来自角色白名单）。
+*/
+function buildSkiffBasePrompt(roleName, role) {
+	const msms = role?.msms ?? [];
+	const tools = role?.tools ?? [];
+	const lines = [
+		"=== Serenity Skiff ===",
+		`Role: ${roleName} (defined by this CCC)`,
+		"You interact with this CCC ONLY through the exposed surface below:"
+	];
+	if (msms.length > 0) lines.push(`  MSMs: ${msms.join(", ")} (call acc_msm exec <name> [args...]; pass --help as the first arg for usage)`);
+	else lines.push("  MSMs: (none)");
+	lines.push(`  Tools: ${tools.length > 0 ? tools.join(", ") : "(none)"}`);
+	lines.push("No other tools are available. Your capability boundary is this surface.");
+	lines.push("");
+	lines.push("---");
+	lines.push("");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/skiff-registry.ts
+/**
+* skiff-registry.ts — Skiff 会话注册表（sessionId → role；零 DSH 依赖，可被任何 seams 安全 import）
+*
+* F4b 会话映射：Skiff agent 创建时注册（skiff-core），guards/seams 按 sessionId 查角色。
+* 独立成模块的原因：guards.ts 等拦截缝需要查角色而不引入 skiff-core 的运行时依赖
+* （skiff-core 依赖 @deepseek-ai/dsh-llm，测试/装配级联成本高）——注册表本身纯内存 Map。
+*
+* 生命周期：进程内存态；连接/页面关闭时 unregister；进程重启自然清空（skiff 会话不复存在）。
+*/
+const skiffSessions = /* @__PURE__ */ new Map();
+/** 查 sessionId 的 Skiff 角色名（无 → null） */
+function skiffRoleFor$1(sessionId) {
+	return skiffSessions.get(sessionId) ?? null;
+}
+function registerSkiffSession$1(sessionId, role) {
+	skiffSessions.set(sessionId, role);
+}
+//#endregion
 //#region src/seams/guards.ts
 /**
 * guards.ts — 拦截缝：安全模式 + 路径守卫（P3 语义的机械层）
@@ -652,6 +755,13 @@ function isWriteTool(toolName, action) {
 */
 function decideGuard(input) {
 	const { root, toolName, safeModeOn, blacklist, pathArg, action } = input;
+	if (input.skiffSessionId !== void 0 && isSkiffSessionId(input.skiffSessionId)) {
+		const roleName = input.skiffSessionId ? skiffRoleFor$1(input.skiffSessionId) : null;
+		if (!roleToolWhitelist(roleName ? readSkiffRoles(root).get(roleName) : void 0).has(toolName)) return {
+			deny: "tool not allowed in this skiff role",
+			kind: "deny"
+		};
+	}
 	if (safeModeOn && toolName === "bash") return {
 		deny: `bash: no such tool`,
 		kind: "deny"
@@ -783,13 +893,15 @@ function registerGuards(ctx, opts = {}) {
 		const blacklist = readBlacklist(root, configPaths);
 		const pathArg = extractPathArg(exec);
 		const action = extractAction(exec);
+		const sessionId = exec?.agent?.session?.id;
 		return decideGuard({
 			root,
 			toolName: exec.name,
 			safeModeOn,
 			blacklist,
 			pathArg,
-			action
+			action,
+			skiffSessionId: sessionId
 		});
 	};
 	ctx.on("tools/pre-execute", async (exec, next) => {
@@ -956,10 +1068,10 @@ async function runKit(root, args) {
 /**
 * kit.ts — acc_kit 真实 DSH 工具定义（defineTool）
 */
-function agentCwd$7(exec) {
+function agentCwd$8(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
-function renderText$9(value) {
+function renderText$10(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -982,10 +1094,10 @@ const kitTool = defineTool({
 	},
 	output: {
 		schema: { type: "json" },
-		render: (args, value) => renderText$9(value)
+		render: (args, value) => renderText$10(value)
 	},
 	async execute(args, exec) {
-		return await runKit(findSerenityRoot(agentCwd$7(exec)), args);
+		return await runKit(findSerenityRoot(agentCwd$8(exec)), args);
 	}
 });
 //#endregion
@@ -1445,10 +1557,10 @@ function runGit(root, args) {
 /**
 * git.ts — cc_git 真实 DSH 工具定义（defineTool）
 */
-function agentCwd$6(exec) {
+function agentCwd$7(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
-function renderText$8(value) {
+function renderText$9(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -1487,10 +1599,10 @@ const gitTool = defineTool({
 	},
 	output: {
 		schema: { type: "json" },
-		render: (args, value) => renderText$8(value)
+		render: (args, value) => renderText$9(value)
 	},
 	async execute(args, exec) {
-		const root = findSerenityRoot(agentCwd$6(exec));
+		const root = findSerenityRoot(agentCwd$7(exec));
 		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 		return runGit(root, args);
 	}
@@ -2055,118 +2167,482 @@ async function runMsmAsync(root, args) {
 	}
 }
 //#endregion
-//#region src/tools/msm.ts
+//#region src/handyman-ops.ts
 /**
-* msm.ts — acc_msm 真实 DSH 工具定义（defineTool）
+* handyman-ops.ts — handyman（杂工）纯逻辑层（零 DSH 依赖，可独立单测）
+*
+* v1.24.0：loop（牛马）→ handyman（杂工）重命名。语义对齐 osp loop：
+* 进度文件（handyman-<label>.md/.json）、续跑、轮次 prompt 结构、stop token。
+* 不兼容旧 loop- 进度文件（用户拍板：仅新 handyman- 前缀）。
 */
-function agentCwd$5(exec) {
-	return exec.agent?.session?.header?.cwd ?? process.cwd();
+/** label 脱敏（Windows 审计问题 17）：非法字符 → '-'，去尾点/空格，限长（按码点截断，修复代理对切散 U+FFFD） */
+function sanitizeLabel(label) {
+	return [...label.replace(/[<>:"/\\|?*\u0000-\u001f]/g, "-").replace(/[ .]+$/g, "")].slice(0, 50).join("");
 }
-function renderText$7(value) {
-	return [{
-		type: "text",
-		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
-	}];
+function handymanProgressPaths(root, label) {
+	const dir = join(root, "AGENT_SESSIONS");
+	const safe = sanitizeLabel(label);
+	return {
+		md: join(dir, `handyman-${safe}.md`),
+		json: join(dir, `handyman-${safe}.json`)
+	};
 }
-const msmTool = defineTool({
-	name: "acc_msm",
-	description: "MSM (Mech & Semi-Mech) framework: list lists registered MSMs (header+flags display); exec executes (600s timeout, path-escape + symlink blocking, injects SERENITY_ROOT/CCC/VERSION env, appends --help TIP on failure; first arg --list/--schema/--format=json is protocol); register/deregister manage the registry (path inside root + script exists + globally unique validation, auto git precision commit); check quality checks DC-M1~M4; guide development manual; ccc-config CCC config reference (handyman.models/sessionKeeper.threshold/localstore.gitTrack/hooks.autoRestoreSession). Reuses the CCC mech-registry.json.",
-	parameters: {
-		action: {
-			type: "string",
-			enum: [...MSM_ACTIONS],
-			required: true,
-			description: "Subcommand: list/exec/register/deregister/check/guide/ccc-config"
-		},
-		name: {
-			type: "string",
-			description: "MSM name (exec/register/deregister)"
-		},
-		args: {
-			type: "array",
-			items: { type: "string" },
-			description: "exec business args (first arg --list/--schema <n>/--format=json is protocol flag, rest passed through losslessly)"
-		},
-		skill: {
-			type: "string",
-			description: "register owning skill"
-		},
-		path: {
-			type: "string",
-			description: "register script relative path (must be inside root and exist)"
-		},
-		category: {
-			type: "string",
-			description: "register category (mech/semi-mech)"
-		},
-		description: {
-			type: "string",
-			description: "register description"
-		},
-		flags: {
-			type: "string",
-			description: "register flags JSON string (new-style object array; type:\"path\" enables escape validation)"
-		},
-		usage: {
-			type: "string",
-			description: "register custom usage (auto-generated by default)"
-		}
-	},
-	output: {
-		schema: { type: "json" },
-		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 runMsmAsync(root, args);
+/** 读取进度（续跑）；无文件返回 round 0 */
+function readProgress(root, label) {
+	const { json } = handymanProgressPaths(root, label);
+	if (!existsSync(json)) return null;
+	try {
+		return JSON.parse(readFileSync(json, "utf-8"));
+	} catch {
+		return null;
 	}
-});
-//#endregion
-//#region src/tools/eap.ts
-/**
-* eap.ts — EAP 认知质量框架工具（渐进式披露，ACC 标准工具化）
-*
-* 内嵌框架内容（自包含，不依赖已安装技能）；可选 section 参数聚焦某原则。
-*/
-const EAP_CONTENT = `# EAP Cognitive Quality Framework (Explicit Abstraction Principle)
-
-> "The functional value of a thought is proportional to its external reconstructability."
+}
+function writeProgress(root, label, p) {
+	const { md, json } = handymanProgressPaths(root, label);
+	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 = [
+		`# handyman: ${label}`,
+		`- Model: ${p.model}`,
+		`- Round: ${p.round}`,
+		`- Done: ${p.done}`,
+		"",
+		`## Latest response`,
+		"",
+		p.lastResponse,
+		""
+	];
+	writeFileSync(md, lines.join("\n"), "utf-8");
+}
+/** 失败状态落盘（对齐 osp writeFailedStatus：done=true / status=failed / errorCode） */
+function writeFailedStatus(root, label, info) {
+	const { json } = handymanProgressPaths(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_HANDYMAN_DONE_${randomBytes(8).toString("hex")}`;
+}
+/** 解析 model 字符串（provider/model）→ {provider, model}；无 / 视为 model-only */
+function splitModel(model) {
+	const idx = model.indexOf("/");
+	if (idx < 0) return {
+		provider: void 0,
+		model
+	};
+	return {
+		provider: model.slice(0, idx),
+		model: model.slice(idx + 1)
+	};
+}
+/** 校验模型在白名单内；不在 → 抛错（用户拍板：只能使用 CCC 配置的模型） */
+function requireWhitelistedModel(model, models) {
+	if (!models.includes(model)) throw new Error(`handyman: model "${model}" is not in the CCC whitelist. Configure .opencode/serenity.json "handyman.models" with one of: ${models.join(", ")}`);
+}
+/** 轮次 prompt（对齐老 loop 结构：回顾进度 → 自由工作 → 汇报；S134 EAP 化：固定详尽） */
+function buildRoundPrompt(opts) {
+	const { root, session, label, round, stopToken, progress, task } = opts;
+	const resumeNote = progress && progress.round > 0 ? `Previous round (round ${progress.round}) completed: ${progress.lastResponse.slice(0, 300)}\nAlways continue from where you left off; never redo completed work.` : "This is the first round.";
+	return `# ${label} — handyman round ${round}
 
-## Three Variables
-| Variable | Meaning | How to improve |
-|----------|---------|----------------|
-| E↑ Explicitness | Degree to which variables/entities/relations are clearly defined | Define variables, state relationship direction & cardinality, draw boundaries |
-| R↓ Reconstructability | Cost of rebuilding the original reasoning later | Record decision rationale, context, constraints, alternatives |
-| S↑ Stability | Degree to which the same input repeatedly produces consistent output | Fix structures, protocolize, avoid relying on implicit context |
+CCC root: ${root}
+${session ? `Work session: ${session} (progress recorded in AGENT_SESSIONS/${session}/SESSION.md)` : ""}
+${task ? `Task: ${task}` : `Task: follow the work corresponding to label "${label}" (if a work session exists, read SESSION.md first to clarify the goal)`}
+${resumeNote}
 
-## Pre-Output Self-Check Checklist
-- [ ] Variables/entities clearly defined (E↑)
-- [ ] Relationships state direction/cardinality (E↑)
-- [ ] Boundaries drawn — what is in scope / what is not (E↑)
-- [ ] No ambiguous words: "handle" "optimize" "problem" → be specific (E↑)
-- [ ] Key decisions record rationale and alternatives (R↓)
-- [ ] No level-skipping — align the upper layer before descending (R↓)
-- [ ] Structures can be regenerated repeatably (S↑)
+## Work rules (fixed every round, must follow)
+1. Work freely within this round: read files, modify code, execute commands — use every means to advance the task.
+2. If this task is **reading/curating or text-writing work** (extracting from files, summarizing, writing docs, generating text, etc.),
+   first load eap (acc-eap skill) and organize output per the EAP standard:
+   - E↑ Explicit: entities/variables clearly defined, relationships with direction and cardinality, boundaries drawn, no ambiguous words
+   - R↓ Reconstructable: key conclusions record sources and reasoning, rebuildable by later agents
+   - S↑ Stable: output structure regenerates repeatably, no reliance on implicit context
+3. Reports must be concrete and verifiable — no filler.
 
-## Relationship with ACC
-ACC (plugin/template) encodes structure as code (E↑); generating a CCC from ACC is deterministic (R↓); consistent across multiple CCCs (S↑).
-CCC (home-serenity etc.) encodes cognitive content as skills/SESSIONs/design docs. Use this checklist to self-check outputs.
+## Per-round report (fixed format, answer each item)
+1. What was done this round (concrete)
+2. Next-step plan
+3. Whether the task is complete (if complete, output only ${stopToken})
 
-## Reference
-https://github.com/tellmewhattodo/theory-eap`;
-function renderText$6(value) {
-	return [{
-		type: "text",
-		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
-	}];
+If the task is complete, output only ${stopToken}.`;
 }
-const eapTool = defineTool({
-	name: "eap",
-	description: "EAP cognitive quality framework (progressive disclosure): defines E↑ explicitness / R↓ reconstructability / S↑ stability + pre-output self-check checklist. No section returns the full framework; specify a section to focus.",
-	parameters: { section: {
-		type: "string",
-		enum: [
+/**
+* handyman 规模化使用指引（guide 子命令输出；S134 继承 + v1.24.0 更新）：
+* 使用 handyman 前必须先加载 eap 设计方案；并行策略（jobs 编排）；提示词规范（详尽固定 EAP）；
+* 阅读/文字编写类 handyman 内部也加载 eap。
+*/
+const HANDYMAN_GUIDE = `# handyman — Scale-Up Usage Guide (guide)
+
+## ⚠️ Before using: load eap and design the plan
+Before calling handyman, load eap (acc-eap skill) and design the "scale-up handyman plan" based on the EAP framework.
+
+### 1. Task decomposition (E↑ Explicit)
+- Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria
+- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel
+
+### 2. Prompt design (handyman's task parameter)
+- task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria
+- Anti-example "handle this file" — ambiguous; good example "read <path>, extract all rows of the「关键决策」table,
+  output a JSON array (fields id/conclusion/evidence), do not modify the original file"
+- Reading/curating or text-writing work (extracting from files, summarizing, writing docs, generating text, etc.):
+  the handyman-internal agent is also required to load eap and organize output per the EAP standard
+
+### 3. Model whitelist (CCC-configured, mandatory)
+- handyman only uses models listed in .opencode/serenity.json "handyman.models" — never arbitrary models
+- Recursive subagents inside a handyman inherit the handyman's model automatically (DSH native)
+- Keep the subagent tool instance free of a fixed agentOptions, or model inheritance breaks
+
+### 4. Parallel strategy (jobs orchestration, workflow capability)
+- Independent subtasks can run in parallel via handyman(jobs=[...]): each job gets its own label + task + stop token + progress file
+- Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label
+  (AGENT_SESSIONS/handyman-<label>.json) — same label resumes, different labels never interfere
+- Parallel cap: handyman.maxParallel (default 10 — cheap models are cheap)
+- Aggregation: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)
+- For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead
+
+## Completion criteria (osp loop standard)
+- The only completion condition = the handyman-internal agent echoes this round's random verification code (stop token); dialogue round cap (default 100, osp fail-safe, forced stop beyond the cap, resumable)
+- Automatic restart on abnormal agent stop (≤100 restarts, anti-infinite-loop)
+
+## Waiting UI
+- The WebUI session-header Serenity detail card shows running handymen's progress (label / round / last response), one line per parallel job, ~3s refresh
+`;
+/** 列出 AGENT_SESSIONS/handyman-*.json 的全部进度（按 updated 倒序；坏文件跳过） */
+function listActiveHandymen(root) {
+	const dir = join(root, "AGENT_SESSIONS");
+	if (!existsSync(dir)) return [];
+	const out = [];
+	for (const entry of readdirSync(dir)) {
+		if (!entry.startsWith("handyman-") || !entry.endsWith(".json")) continue;
+		try {
+			const data = JSON.parse(readFileSync(join(dir, entry), "utf-8"));
+			if (typeof data.label !== "string" || typeof data.round !== "number") continue;
+			out.push({
+				label: data.label,
+				round: data.round,
+				done: data.done === true,
+				model: typeof data.model === "string" ? data.model : "",
+				updated: typeof data.updated === "string" ? data.updated : "",
+				lastResponse: typeof data.lastResponse === "string" ? data.lastResponse : ""
+			});
+		} catch {}
+	}
+	out.sort((a, b) => a.updated < b.updated ? 1 : -1);
+	return out;
+}
+//#endregion
+//#region src/skiff-core.ts
+const PLUGIN_SOURCE$3 = {
+	kind: "plugin",
+	plugin: "dsh-serenity-hooks"
+};
+const skiffAgents = /* @__PURE__ */ new Map();
+/** 查 sessionId 的 Skiff 角色名（无 → null） */
+function skiffRoleFor(sessionId) {
+	return skiffRoleFor$1(sessionId);
+}
+function registerSkiffSession(sessionId, role, agent) {
+	skiffAgents.set(sessionId, agent);
+	registerSkiffSession$1(sessionId, role);
+}
+/**
+* 创建 Skiff agent：标准 DSH agent + cwd=CCC root + 角色模型 +
+* scoped 系统提示词（基础提示词 + CCC 定义段，全替换 ACC 默认注入）。
+*/
+async function createSkiffAgent(ctx, root, roleName, role, defaultModel) {
+	if (!ctx.agents) throw new Error("skiff: ctx.agents unavailable");
+	const model = role.model?.trim() || defaultModel || "";
+	const sessionId = `${SKIFF_SESSION_PREFIX}${roleName}-${randomUUID()}`;
+	const handle = await ctx.agents.create({
+		sessionId,
+		meta: { cwd: root },
+		...model ? { agentOptions: splitModel(model) } : {}
+	});
+	const agent = handle.agent;
+	try {
+		agent.ctx.systemPrompt.section({
+			name: "serenity-skiff",
+			order: -60,
+			text: () => [buildSkiffBasePrompt(roleName, role), role.systemPrompt ?? ""].filter(Boolean).join("\n")
+		});
+	} catch (err) {
+		console.warn(`[serenity-hooks] skiff 系统提示词注册失败: ${String(err?.message ?? err)}`);
+	}
+	registerSkiffSession(sessionId, roleName, agent);
+	return {
+		handle,
+		agent,
+		sessionId
+	};
+}
+/** 等待 agent 空闲（agent/status → idle）；无超时（agent 工作多久等多久，handyman 同款） */
+function waitIdle$1(ctx, agent) {
+	return new Promise((resolve) => {
+		let settled = false;
+		let dispose = () => {};
+		const finish = () => {
+			if (settled) return;
+			settled = true;
+			dispose();
+			resolve();
+		};
+		dispose = ctx.on("agent/status", (payload) => {
+			if (payload.agent === agent && payload.status === "idle") finish();
+		});
+	});
+}
+/** 读会话最后一个 assistant/message 文本（handyman 同款） */
+function lastAssistantText$1(agent) {
+	const events = agent.session.events;
+	for (let i = events.length - 1; i >= 0; i--) {
+		const e = events[i];
+		if (e && e.type === "assistant/message") {
+			const text = (e.data?.message?.content ?? e.data?.content ?? []).filter((b) => b.type === "text" && b.text).map((b) => b.text).join("\n");
+			if (text) return text;
+		}
+	}
+	return "";
+}
+/** events → 可读轨迹（user/assistant 文本 + 工具调用 + 工具结果；单条解析失败跳过） */
+function eventsToTrajectory(events) {
+	const out = [];
+	for (const raw of events) try {
+		const ev = raw;
+		if (ev.type === "user/message") {
+			const text = extractText(ev.data);
+			if (text) out.push({
+				role: "user",
+				text
+			});
+		} else if (ev.type === "assistant/message") {
+			const d = ev.data;
+			const text = (d?.message?.content ?? d?.content ?? []).filter((b) => b.type === "text" && b.text).map((b) => b.text).join("\n");
+			const calls = d?.message?.tool_calls ?? [];
+			if (text) out.push({
+				role: "assistant",
+				text
+			});
+			for (const c of calls ?? []) {
+				const args = typeof c.arguments === "string" ? c.arguments : JSON.stringify(c.arguments ?? {});
+				out.push({
+					role: "assistant",
+					text: `→ ${c.name ?? "(tool)"} ${truncate(args, 300)}`,
+					tool: c.name
+				});
+			}
+		} else if (ev.type === "tool/result") {
+			const outText = extractText(ev.data);
+			if (outText) out.push({
+				role: "tool",
+				text: truncate(outText, 500),
+				tool: String(ev.data?.name ?? "")
+			});
+		}
+	} catch {}
+	return out;
+}
+function extractText(data) {
+	const content = data?.content;
+	if (!Array.isArray(content)) return "";
+	return content.filter((b) => b.type === "text" && b.text).map((b) => b.text).join("\n");
+}
+function truncate(s, n) {
+	return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+/**
+* 提问一轮：followup → 等 idle → 读答案 + 本 turn 轨迹（增量 = followup 前 events 之后）。
+* @param eventsStart 本轮开始前的 events 长度（0 = 全量轨迹）
+*/
+async function askSkiff(ctx, agent, question, eventsStart = 0) {
+	const before = eventsStart > 0 ? eventsStart : agent.session.events.length;
+	agent.followup(createUserMessage({
+		content: [{
+			type: "text",
+			text: question
+		}],
+		source: PLUGIN_SOURCE$3
+	}));
+	await waitIdle$1(ctx, agent);
+	const answer = lastAssistantText$1(agent);
+	const trajectory = eventsToTrajectory(agent.session.events.slice(before));
+	return {
+		answer,
+		sessionId: String(agent.session.id ?? ""),
+		trajectory
+	};
+}
+/**
+* Skiff 会话的轨迹纪律参与判定：非 skiff 会话恒 true（正常参与）；
+* skiff 会话按角色 trajectory 子集（session/keeper/rebuild）决定；
+* 注册表缺失（进程重启遗留等）→ 保守旁路（false，完全独立）。
+*/
+function skiffTrajectoryEnabled(root, sessionId, key) {
+	if (!isSkiffSessionId(sessionId)) return true;
+	const roleName = sessionId ? skiffRoleFor(sessionId) : null;
+	if (!roleName) return false;
+	return trajectorySubset(readSkiffRoles(root).get(roleName))[key];
+}
+/**
+* acc_msm 的 Skiff 门控：非 skiff 会话恒放行；skiff 会话——
+* exec 非白名单 MSM 拒绝（不列名单）、register/deregister 必拒、
+* list 白名单过滤、check/guide/ccc-config 只读放行。
+*/
+function skiffMsmGate(root, sessionId, action, name) {
+	if (!isSkiffSessionId(sessionId)) return {};
+	const roleName = sessionId ? skiffRoleFor(sessionId) : null;
+	const role = roleName ? readSkiffRoles(root).get(roleName) : void 0;
+	if (!roleName || !role) return { reject: "MSM not allowed in this skiff session" };
+	if (action === "register" || action === "deregister") return { reject: "register/deregister is not allowed in skiff sessions" };
+	if (action === "exec") {
+		if (!name || !(role.msms ?? []).includes(name)) return { reject: "MSM not allowed" };
+		return {};
+	}
+	if (action === "list") return { whitelist: roleMsmWhitelist(role) };
+	return {};
+}
+//#endregion
+//#region src/tools/msm.ts
+/**
+* msm.ts — acc_msm 真实 DSH 工具定义（defineTool）
+*/
+function agentCwd$6(exec) {
+	return exec.agent?.session?.header?.cwd ?? process.cwd();
+}
+function agentSessionId$1(exec) {
+	return exec.agent?.session?.id ?? "";
+}
+function renderText$8(value) {
+	return [{
+		type: "text",
+		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+	}];
+}
+const msmTool = defineTool({
+	name: "acc_msm",
+	description: "MSM (Mech & Semi-Mech) framework: list lists registered MSMs (header+flags display); exec executes (600s timeout, path-escape + symlink blocking, injects SERENITY_ROOT/CCC/VERSION env, appends --help TIP on failure; first arg --list/--schema/--format=json is protocol); register/deregister manage the registry (path inside root + script exists + globally unique validation, auto git precision commit); check quality checks DC-M1~M4; guide development manual; ccc-config CCC config reference (handyman.models/sessionKeeper.threshold/localstore.gitTrack/hooks.autoRestoreSession). Reuses the CCC mech-registry.json.",
+	parameters: {
+		action: {
+			type: "string",
+			enum: [...MSM_ACTIONS],
+			required: true,
+			description: "Subcommand: list/exec/register/deregister/check/guide/ccc-config"
+		},
+		name: {
+			type: "string",
+			description: "MSM name (exec/register/deregister)"
+		},
+		args: {
+			type: "array",
+			items: { type: "string" },
+			description: "exec business args (first arg --list/--schema <n>/--format=json is protocol flag, rest passed through losslessly)"
+		},
+		skill: {
+			type: "string",
+			description: "register owning skill"
+		},
+		path: {
+			type: "string",
+			description: "register script relative path (must be inside root and exist)"
+		},
+		category: {
+			type: "string",
+			description: "register category (mech/semi-mech)"
+		},
+		description: {
+			type: "string",
+			description: "register description"
+		},
+		flags: {
+			type: "string",
+			description: "register flags JSON string (new-style object array; type:\"path\" enables escape validation)"
+		},
+		usage: {
+			type: "string",
+			description: "register custom usage (auto-generated by default)"
+		}
+	},
+	output: {
+		schema: { type: "json" },
+		render: (args, value) => renderText$8(value)
+	},
+	async execute(args, exec) {
+		const root = findSerenityRoot(agentCwd$6(exec));
+		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
+		const gate = skiffMsmGate(root, agentSessionId$1(exec), args.action, args.name);
+		if (gate.reject) throw new Error(gate.reject);
+		if (args.action === "list" && gate.whitelist) {
+			const out = runMsm(root, args);
+			const text = typeof out === "string" ? out : JSON.stringify(out);
+			const header = text.split("\n")[0] ?? "";
+			const lines = text.split("\n").slice(1).filter((line) => {
+				const name = line.split(" | ")[0]?.trim();
+				return name !== void 0 && name !== "" && gate.whitelist.has(name);
+			});
+			return `${header}\n${lines.length > 0 ? lines.join("\n") : "(no MSM allowed in this role)"}`;
+		}
+		return runMsmAsync(root, args);
+	}
+});
+//#endregion
+//#region src/tools/eap.ts
+/**
+* eap.ts — EAP 认知质量框架工具（渐进式披露，ACC 标准工具化）
+*
+* 内嵌框架内容（自包含，不依赖已安装技能）；可选 section 参数聚焦某原则。
+*/
+const EAP_CONTENT = `# EAP Cognitive Quality Framework (Explicit Abstraction Principle)
+
+> "The functional value of a thought is proportional to its external reconstructability."
+
+## Three Variables
+| Variable | Meaning | How to improve |
+|----------|---------|----------------|
+| E↑ Explicitness | Degree to which variables/entities/relations are clearly defined | Define variables, state relationship direction & cardinality, draw boundaries |
+| R↓ Reconstructability | Cost of rebuilding the original reasoning later | Record decision rationale, context, constraints, alternatives |
+| S↑ Stability | Degree to which the same input repeatedly produces consistent output | Fix structures, protocolize, avoid relying on implicit context |
+
+## Pre-Output Self-Check Checklist
+- [ ] Variables/entities clearly defined (E↑)
+- [ ] Relationships state direction/cardinality (E↑)
+- [ ] Boundaries drawn — what is in scope / what is not (E↑)
+- [ ] No ambiguous words: "handle" "optimize" "problem" → be specific (E↑)
+- [ ] Key decisions record rationale and alternatives (R↓)
+- [ ] No level-skipping — align the upper layer before descending (R↓)
+- [ ] Structures can be regenerated repeatably (S↑)
+
+## Relationship with ACC
+ACC (plugin/template) encodes structure as code (E↑); generating a CCC from ACC is deterministic (R↓); consistent across multiple CCCs (S↑).
+CCC (home-serenity etc.) encodes cognitive content as skills/SESSIONs/design docs. Use this checklist to self-check outputs.
+
+## Reference
+https://github.com/tellmewhattodo/theory-eap`;
+function renderText$7(value) {
+	return [{
+		type: "text",
+		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+	}];
+}
+const eapTool = defineTool({
+	name: "eap",
+	description: "EAP cognitive quality framework (progressive disclosure): defines E↑ explicitness / R↓ reconstructability / S↑ stability + pre-output self-check checklist. No section returns the full framework; specify a section to focus.",
+	parameters: { section: {
+		type: "string",
+		enum: [
 			"variables",
 			"checklist",
 			"acc"
@@ -2175,7 +2651,7 @@ const eapTool = defineTool({
 	} },
 	output: {
 		schema: { type: "string" },
-		render: (_args, value) => renderText$6(value)
+		render: (_args, value) => renderText$7(value)
 	},
 	async execute(args) {
 		if (args.section === "variables") return EAP_CONTENT.split("## Pre-Output Self-Check Checklist")[0];
@@ -2216,7 +2692,7 @@ Requirements → Scope → Solution → Interface → Implementation
 2. Wait for confirmation or correction (small step)
 3. After confirmation, record the decision (into session SESSION.md or a design doc)
 4. Move to the next decision point`;
-function renderText$5(value) {
+function renderText$6(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -2232,7 +2708,7 @@ const neatTool = defineTool({
 	} },
 	output: {
 		schema: { type: "string" },
-		render: (_args, value) => renderText$5(value)
+		render: (_args, value) => renderText$6(value)
 	},
 	async execute(args) {
 		if (args.section === "rules") return NEAT_CONTENT.match(/## Four Iron Rules[\s\S]*?(?=## )/)?.[0] ?? NEAT_CONTENT;
@@ -2274,275 +2750,96 @@ Does not measure total entropy (not operational); it measures only the **excess
 > H_op(C, t) = cost(task | C, t) − cost(task | ideal)
 Continuity condition: **H_op(C, t) ≤ H_critical** — agents can still complete tasks at reasonable cost
 
-## Continuity Maintenance Condition
-> **ΔH_org ≥ ΔH_in** — organization must at minimum keep pace with accumulation
-
-## Six-Phase Lifecycle
-Experience → Accumulation → Organization → Abstraction → Reconstruction → Evolution →（loop）
-| Phase | Engineering Concern |
-|-------|---------------------|
-| Experience | Does input carry enough structure |
-| Accumulation | Is information stored losslessly |
-| Organization | Entropy management — ΔH_org offsets ΔH_in |
-| Abstraction | Is abstraction explicitly encoded |
-| Reconstruction | Can reasoning structure be recovered from artifacts |
-| Evolution | Does evolution stay coherent or introduce drift |
-
-## Relationship with EAP
-EAP answers "how a piece of knowledge should be structured" (explicitness E↑ / reconstructability R↓ / stability S↑);
-CCE answers "how structured knowledge should keep evolving across time without losing coherence". They complement each other: EAP is static quality, CCE is dynamic persistence.
-
-## Relationship with Serenity
-Serenity's session system, session tracking, and entropy management mechanisms (SQC quality loop) are all engineering implementations of CCE;
-the behavioral constraints embedded in CCC system prompts come from CCE.`;
-function renderText$4(value) {
-	return [{
-		type: "text",
-		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
-	}];
-}
-const cceTool = defineTool({
-	name: "cce",
-	description: "CCE cognitive continuity engineering (progressive disclosure): the engineering discipline of maintaining a cognitive entity's identity/accessibility/evolution under bounded resources and irreversible uncertainty. No section returns the full framework; specify a section to focus.",
-	parameters: { section: {
-		type: "string",
-		enum: [
-			"container",
-			"entropy",
-			"lifecycle",
-			"eap"
-		],
-		description: "Focus section: container (5 cognitive-container properties) / entropy (operational entropy H_op) / lifecycle (six phases) / eap (relationship with EAP)"
-	} },
-	output: {
-		schema: { type: "string" },
-		render: (_args, value) => renderText$4(value)
-	},
-	async execute(args) {
-		const section = args.section;
-		const blocks = {
-			container: {
-				start: "## Cognitive Container",
-				end: "## Operational Cognitive Entropy"
-			},
-			entropy: {
-				start: "## Operational Cognitive Entropy (H_op)",
-				end: "## Continuity Maintenance Condition"
-			},
-			lifecycle: { start: "## Six-Phase Lifecycle" },
-			eap: { start: "## Relationship with EAP" }
-		};
-		if (section) {
-			const b = blocks[section];
-			if (b) {
-				const startIdx = CCE_CONTENT.indexOf(b.start);
-				if (startIdx >= 0) return (b.end ? CCE_CONTENT.slice(startIdx, CCE_CONTENT.indexOf(b.end, startIdx)) : CCE_CONTENT.slice(startIdx)).trim();
-			}
-		}
-		return CCE_CONTENT;
-	}
-});
-//#endregion
-//#region src/handyman-preset-inherit.ts
-/**
-* 解析 handyman worker 从父 agent 继承的 preset，并组装创建 setup 钩子。
-* @param parentCtx - 发起 handyman 的 agent 的 scope ctx；无（headless/非 agent 上下文）时为 undefined。
-* @returns 继承结果：meta 用的 agentPreset 与创建 setup 钩子。
-*/
-function handymanPresetInheritance(parentCtx) {
-	if (parentCtx === void 0) return { setup: (childCtx) => {
-		childCtx.tools.restrict({ deny: ["handyman"] });
-	} };
-	const agentPreset = parentCtx.get("agentPresets")?.composedPreset(parentCtx);
-	if (agentPreset === void 0) return { setup: (childCtx) => {
-		childCtx.tools.restrict({ deny: ["handyman"] });
-	} };
-	return {
-		agentPreset,
-		setup: (childCtx) => {
-			childCtx.get("agentPresets")?.composeFrom(childCtx, parentCtx);
-			childCtx.tools.restrict({ deny: ["handyman"] });
-		}
-	};
-}
-//#endregion
-//#region src/handyman-ops.ts
-/**
-* handyman-ops.ts — handyman（杂工）纯逻辑层（零 DSH 依赖，可独立单测）
-*
-* v1.24.0：loop（牛马）→ handyman（杂工）重命名。语义对齐 osp loop：
-* 进度文件（handyman-<label>.md/.json）、续跑、轮次 prompt 结构、stop token。
-* 不兼容旧 loop- 进度文件（用户拍板：仅新 handyman- 前缀）。
-*/
-/** label 脱敏（Windows 审计问题 17）：非法字符 → '-'，去尾点/空格，限长（按码点截断，修复代理对切散 U+FFFD） */
-function sanitizeLabel(label) {
-	return [...label.replace(/[<>:"/\\|?*\u0000-\u001f]/g, "-").replace(/[ .]+$/g, "")].slice(0, 50).join("");
-}
-function handymanProgressPaths(root, label) {
-	const dir = join(root, "AGENT_SESSIONS");
-	const safe = sanitizeLabel(label);
-	return {
-		md: join(dir, `handyman-${safe}.md`),
-		json: join(dir, `handyman-${safe}.json`)
-	};
-}
-/** 读取进度（续跑）；无文件返回 round 0 */
-function readProgress(root, label) {
-	const { json } = handymanProgressPaths(root, label);
-	if (!existsSync(json)) return null;
-	try {
-		return JSON.parse(readFileSync(json, "utf-8"));
-	} catch {
-		return null;
-	}
-}
-function writeProgress(root, label, p) {
-	const { md, json } = handymanProgressPaths(root, label);
-	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 = [
-		`# handyman: ${label}`,
-		`- Model: ${p.model}`,
-		`- Round: ${p.round}`,
-		`- Done: ${p.done}`,
-		"",
-		`## Latest response`,
-		"",
-		p.lastResponse,
-		""
-	];
-	writeFileSync(md, lines.join("\n"), "utf-8");
-}
-/** 失败状态落盘（对齐 osp writeFailedStatus：done=true / status=failed / errorCode） */
-function writeFailedStatus(root, label, info) {
-	const { json } = handymanProgressPaths(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_HANDYMAN_DONE_${randomBytes(8).toString("hex")}`;
-}
-/** 解析 model 字符串（provider/model）→ {provider, model}；无 / 视为 model-only */
-function splitModel(model) {
-	const idx = model.indexOf("/");
-	if (idx < 0) return {
-		provider: void 0,
-		model
-	};
-	return {
-		provider: model.slice(0, idx),
-		model: model.slice(idx + 1)
-	};
-}
-/** 校验模型在白名单内；不在 → 抛错（用户拍板：只能使用 CCC 配置的模型） */
-function requireWhitelistedModel(model, models) {
-	if (!models.includes(model)) throw new Error(`handyman: model "${model}" is not in the CCC whitelist. Configure .opencode/serenity.json "handyman.models" with one of: ${models.join(", ")}`);
-}
-/** 轮次 prompt（对齐老 loop 结构：回顾进度 → 自由工作 → 汇报；S134 EAP 化：固定详尽） */
-function buildRoundPrompt(opts) {
-	const { root, session, label, round, stopToken, progress, task } = opts;
-	const resumeNote = progress && progress.round > 0 ? `Previous round (round ${progress.round}) completed: ${progress.lastResponse.slice(0, 300)}\nAlways continue from where you left off; never redo completed work.` : "This is the first round.";
-	return `# ${label} — handyman round ${round}
-
-CCC root: ${root}
-${session ? `Work session: ${session} (progress recorded in AGENT_SESSIONS/${session}/SESSION.md)` : ""}
-${task ? `Task: ${task}` : `Task: follow the work corresponding to label "${label}" (if a work session exists, read SESSION.md first to clarify the goal)`}
-${resumeNote}
-
-## Work rules (fixed every round, must follow)
-1. Work freely within this round: read files, modify code, execute commands — use every means to advance the task.
-2. If this task is **reading/curating or text-writing work** (extracting from files, summarizing, writing docs, generating text, etc.),
-   first load eap (acc-eap skill) and organize output per the EAP standard:
-   - E↑ Explicit: entities/variables clearly defined, relationships with direction and cardinality, boundaries drawn, no ambiguous words
-   - R↓ Reconstructable: key conclusions record sources and reasoning, rebuildable by later agents
-   - S↑ Stable: output structure regenerates repeatably, no reliance on implicit context
-3. Reports must be concrete and verifiable — no filler.
-
-## Per-round report (fixed format, answer each item)
-1. What was done this round (concrete)
-2. Next-step plan
-3. Whether the task is complete (if complete, output only ${stopToken})
-
-If the task is complete, output only ${stopToken}.`;
-}
-/**
-* handyman 规模化使用指引（guide 子命令输出；S134 继承 + v1.24.0 更新）：
-* 使用 handyman 前必须先加载 eap 设计方案；并行策略（jobs 编排）；提示词规范（详尽固定 EAP）；
-* 阅读/文字编写类 handyman 内部也加载 eap。
-*/
-const HANDYMAN_GUIDE = `# handyman — Scale-Up Usage Guide (guide)
-
-## ⚠️ Before using: load eap and design the plan
-Before calling handyman, load eap (acc-eap skill) and design the "scale-up handyman plan" based on the EAP framework.
-
-### 1. Task decomposition (E↑ Explicit)
-- Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria
-- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel
-
-### 2. Prompt design (handyman's task parameter)
-- task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria
-- Anti-example "handle this file" — ambiguous; good example "read <path>, extract all rows of the「关键决策」table,
-  output a JSON array (fields id/conclusion/evidence), do not modify the original file"
-- Reading/curating or text-writing work (extracting from files, summarizing, writing docs, generating text, etc.):
-  the handyman-internal agent is also required to load eap and organize output per the EAP standard
-
-### 3. Model whitelist (CCC-configured, mandatory)
-- handyman only uses models listed in .opencode/serenity.json "handyman.models" — never arbitrary models
-- Recursive subagents inside a handyman inherit the handyman's model automatically (DSH native)
-- Keep the subagent tool instance free of a fixed agentOptions, or model inheritance breaks
-
-### 4. Parallel strategy (jobs orchestration, workflow capability)
-- Independent subtasks can run in parallel via handyman(jobs=[...]): each job gets its own label + task + stop token + progress file
-- Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label
-  (AGENT_SESSIONS/handyman-<label>.json) — same label resumes, different labels never interfere
-- Parallel cap: handyman.maxParallel (default 10 — cheap models are cheap)
-- Aggregation: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)
-- For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead
+## Continuity Maintenance Condition
+> **ΔH_org ≥ ΔH_in** — organization must at minimum keep pace with accumulation
 
-## Completion criteria (osp loop standard)
-- The only completion condition = the handyman-internal agent echoes this round's random verification code (stop token); dialogue round cap (default 100, osp fail-safe, forced stop beyond the cap, resumable)
-- Automatic restart on abnormal agent stop (≤100 restarts, anti-infinite-loop)
+## Six-Phase Lifecycle
+Experience → Accumulation → Organization → Abstraction → Reconstruction → Evolution →（loop）
+| Phase | Engineering Concern |
+|-------|---------------------|
+| Experience | Does input carry enough structure |
+| Accumulation | Is information stored losslessly |
+| Organization | Entropy management — ΔH_org offsets ΔH_in |
+| Abstraction | Is abstraction explicitly encoded |
+| Reconstruction | Can reasoning structure be recovered from artifacts |
+| Evolution | Does evolution stay coherent or introduce drift |
 
-## Waiting UI
-- The WebUI session-header Serenity detail card shows running handymen's progress (label / round / last response), one line per parallel job, ~3s refresh
-`;
-/** 列出 AGENT_SESSIONS/handyman-*.json 的全部进度（按 updated 倒序；坏文件跳过） */
-function listActiveHandymen(root) {
-	const dir = join(root, "AGENT_SESSIONS");
-	if (!existsSync(dir)) return [];
-	const out = [];
-	for (const entry of readdirSync(dir)) {
-		if (!entry.startsWith("handyman-") || !entry.endsWith(".json")) continue;
-		try {
-			const data = JSON.parse(readFileSync(join(dir, entry), "utf-8"));
-			if (typeof data.label !== "string" || typeof data.round !== "number") continue;
-			out.push({
-				label: data.label,
-				round: data.round,
-				done: data.done === true,
-				model: typeof data.model === "string" ? data.model : "",
-				updated: typeof data.updated === "string" ? data.updated : "",
-				lastResponse: typeof data.lastResponse === "string" ? data.lastResponse : ""
-			});
-		} catch {}
+## Relationship with EAP
+EAP answers "how a piece of knowledge should be structured" (explicitness E↑ / reconstructability R↓ / stability S↑);
+CCE answers "how structured knowledge should keep evolving across time without losing coherence". They complement each other: EAP is static quality, CCE is dynamic persistence.
+
+## Relationship with Serenity
+Serenity's session system, session tracking, and entropy management mechanisms (SQC quality loop) are all engineering implementations of CCE;
+the behavioral constraints embedded in CCC system prompts come from CCE.`;
+function renderText$5(value) {
+	return [{
+		type: "text",
+		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+	}];
+}
+const cceTool = defineTool({
+	name: "cce",
+	description: "CCE cognitive continuity engineering (progressive disclosure): the engineering discipline of maintaining a cognitive entity's identity/accessibility/evolution under bounded resources and irreversible uncertainty. No section returns the full framework; specify a section to focus.",
+	parameters: { section: {
+		type: "string",
+		enum: [
+			"container",
+			"entropy",
+			"lifecycle",
+			"eap"
+		],
+		description: "Focus section: container (5 cognitive-container properties) / entropy (operational entropy H_op) / lifecycle (six phases) / eap (relationship with EAP)"
+	} },
+	output: {
+		schema: { type: "string" },
+		render: (_args, value) => renderText$5(value)
+	},
+	async execute(args) {
+		const section = args.section;
+		const blocks = {
+			container: {
+				start: "## Cognitive Container",
+				end: "## Operational Cognitive Entropy"
+			},
+			entropy: {
+				start: "## Operational Cognitive Entropy (H_op)",
+				end: "## Continuity Maintenance Condition"
+			},
+			lifecycle: { start: "## Six-Phase Lifecycle" },
+			eap: { start: "## Relationship with EAP" }
+		};
+		if (section) {
+			const b = blocks[section];
+			if (b) {
+				const startIdx = CCE_CONTENT.indexOf(b.start);
+				if (startIdx >= 0) return (b.end ? CCE_CONTENT.slice(startIdx, CCE_CONTENT.indexOf(b.end, startIdx)) : CCE_CONTENT.slice(startIdx)).trim();
+			}
+		}
+		return CCE_CONTENT;
 	}
-	out.sort((a, b) => a.updated < b.updated ? 1 : -1);
-	return out;
+});
+//#endregion
+//#region src/handyman-preset-inherit.ts
+/**
+* 解析 handyman worker 从父 agent 继承的 preset，并组装创建 setup 钩子。
+* @param parentCtx - 发起 handyman 的 agent 的 scope ctx；无（headless/非 agent 上下文）时为 undefined。
+* @returns 继承结果：meta 用的 agentPreset 与创建 setup 钩子。
+*/
+function handymanPresetInheritance(parentCtx) {
+	if (parentCtx === void 0) return { setup: (childCtx) => {
+		childCtx.tools.restrict({ deny: ["handyman"] });
+	} };
+	const agentPreset = parentCtx.get("agentPresets")?.composedPreset(parentCtx);
+	if (agentPreset === void 0) return { setup: (childCtx) => {
+		childCtx.tools.restrict({ deny: ["handyman"] });
+	} };
+	return {
+		agentPreset,
+		setup: (childCtx) => {
+			childCtx.get("agentPresets")?.composeFrom(childCtx, parentCtx);
+			childCtx.tools.restrict({ deny: ["handyman"] });
+		}
+	};
 }
 //#endregion
 //#region src/tools/handyman.ts
@@ -2566,10 +2863,10 @@ function listActiveHandymen(root) {
 * preset 继承 + 工具收窄：setup 钩子里对子 agent 执行 agentPresets.composeFrom（对齐
 * subagent 先例）+ tools.restrict deny handyman（worker 内部看不到 handyman 工具）。
 */
-function agentCwd$4(exec) {
+function agentCwd$5(exec) {
 	return (exec.agent?.session)?.header?.cwd ?? process.cwd();
 }
-function renderText$3(value) {
+function renderText$4(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -2786,11 +3083,11 @@ function createHandymanTool(ctx) {
 		},
 		output: {
 			schema: { type: "json" },
-			render: (_args, value) => renderText$3(value)
+			render: (_args, value) => renderText$4(value)
 		},
 		async execute(args, exec) {
 			if (args.guide) return { guide: HANDYMAN_GUIDE };
-			const root = findSerenityRoot(agentCwd$4(exec));
+			const root = findSerenityRoot(agentCwd$5(exec));
 			if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 			const hc = readHandymanConfig(root, DEFAULT_SERENITY_CONFIG_PATHS);
 			if (hc === null) throw new Error("handyman requires a model whitelist: configure .opencode/serenity.json \"handyman.models\" (e.g. {\"handyman\": {\"models\": [\"minimax-cn-coding-plan/MiniMax-M3\"], \"defaultModel\": \"minimax-cn-coding-plan/MiniMax-M3\"}})");
@@ -4885,7 +5182,9 @@ const simpleSettingsSchema = z.object({
 	gatewayEnabled: z.boolean().default(false),
 	rebuildEnabled: z.boolean().default(true),
 	rebuildThreshold: z.number().min(.01).max(1).default(.9),
-	namingEnabled: z.boolean().default(true)
+	namingEnabled: z.boolean().default(true),
+	skiffEnabled: z.boolean().default(false),
+	skiffDebugPort: z.number().min(1024).max(65535).default(3099)
 });
 /** 从插件 Config 提取 entry 默认（settings base 层） */
 function entryDefaults(config) {
@@ -4893,7 +5192,9 @@ function entryDefaults(config) {
 		gatewayEnabled: config.gateway?.enabled ?? false,
 		rebuildEnabled: config.rebuild?.enabled ?? true,
 		rebuildThreshold: config.rebuild?.thresholdRatio ?? .9,
-		namingEnabled: config.naming?.enabled ?? true
+		namingEnabled: config.naming?.enabled ?? true,
+		skiffEnabled: config.skiff?.enabled ?? false,
+		skiffDebugPort: config.skiff?.debugPort ?? 3099
 	};
 }
 /** 运行时源（installSettingsSection 注入：settings scope 或 entry fallback） */
@@ -4904,7 +5205,9 @@ function defaultSimpleSettings() {
 		gatewayEnabled: false,
 		rebuildEnabled: true,
 		rebuildThreshold: .9,
-		namingEnabled: true
+		namingEnabled: true,
+		skiffEnabled: false,
+		skiffDebugPort: 3099
 	};
 }
 /**
@@ -5565,7 +5868,7 @@ function qaCheck(root, key) {
 * 同步把当前 dsh 会话重命名为该 SESSION 目录名**（sessionTitle.rename，user source
 * pin 住标题）。非创建时预命名。
 */
-function agentCwd$3(exec) {
+function agentCwd$4(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
 /** 当前 dsh 会话 id（use/close 按会话隔离的 scope） */
@@ -5628,7 +5931,7 @@ function renameDshSessionOnUse(deps, session, titles, active) {
 		};
 	}
 }
-function renderText$2(value) {
+function renderText$3(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -5762,10 +6065,10 @@ function createSessionTool(ctx) {
 		},
 		output: {
 			schema: { type: "json" },
-			render: (args, value) => renderText$2(value)
+			render: (args, value) => renderText$3(value)
 		},
 		async execute(args, exec) {
-			const root = findSerenityRoot(agentCwd$3(exec));
+			const root = findSerenityRoot(agentCwd$4(exec));
 			if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 			const entries = loadMsmEntries(root);
 			const hasSessionTool = entries.some((e) => e.name === "session-tool");
@@ -5934,7 +6237,7 @@ function createEpochPromotion(promoteEvents, requiredSignals = 1, maxRoundsFallb
 				promoted: true
 			};
 			const loopSid = session.id;
-			if (typeof loopSid === "string" && loopSid.startsWith("handyman-")) return {
+			if (typeof loopSid === "string" && (loopSid.startsWith("handyman-") || isSkiffSessionId(loopSid))) return {
 				boundary: -1,
 				promoted: true
 			};
@@ -6038,7 +6341,7 @@ function registerBootstrap(ctx) {
 			const session = agent.session;
 			const depth = session?.header?.delegationDepth ?? 0;
 			const sid = typeof session?.id === "string" ? session.id : void 0;
-			if (sid !== void 0 && sid.startsWith("handyman-")) return;
+			if (sid !== void 0 && (sid.startsWith("handyman-") || isSkiffSessionId(sid))) return;
 			if (depth === 0) {
 				if (session?.events?.some((event) => event.type === "user/message")) return;
 			} else if (sid !== void 0 && anchoredSessions.has(sid)) return;
@@ -6351,13 +6654,13 @@ function registerRebuildTurnHook(ctx) {
 * （turn 结束前所有 tool/result 已 append → 无孤儿；S141 INVALID_REQUEST 根治）。
 * 服务端逻辑在 ../rebuild.ts（queueRebuild/performRebuild/registerRebuildTurnHook）。
 */
-function agentCwd$2(exec) {
+function agentCwd$3(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
 function agentSessionId(exec) {
 	return exec.agent?.session?.id ?? "";
 }
-function renderText$1(value) {
+function renderText$2(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -6374,17 +6677,17 @@ function createRebuildTool(ctx) {
 		} },
 		output: {
 			schema: { type: "json" },
-			render: (args, value) => renderText$1(value)
+			render: (args, value) => renderText$2(value)
 		},
 		async execute(args, exec) {
-			const root = findSerenityRoot(agentCwd$2(exec));
+			const root = findSerenityRoot(agentCwd$3(exec));
 			if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 			const dshSessionId = agentSessionId(exec);
 			if (!dshSessionId) throw new Error("Unable to determine the current dsh session id");
 			const result = await queueRebuild(ctx, {
 				root,
 				note: args.note,
-				agentCwd: agentCwd$2(exec),
+				agentCwd: agentCwd$3(exec),
 				dshSessionId
 			});
 			return {
@@ -6414,10 +6717,10 @@ const ACTIONS = [
 	"show",
 	"doc"
 ];
-function agentCwd$1(exec) {
+function agentCwd$2(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
-function renderText(value) {
+function renderText$1(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -6447,6 +6750,139 @@ const localstoreTool = defineTool({
 			description: "Namespace credential|config (default credential)"
 		}
 	},
+	output: {
+		schema: { type: "json" },
+		render: (args, value) => renderText$1(value)
+	},
+	async execute(args, exec) {
+		const root = findSerenityRoot(agentCwd$2(exec));
+		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
+		return runLocalStore(root, args);
+	}
+});
+//#endregion
+//#region src/tools/skiff-admin.ts
+/**
+* skiff-admin.ts — skiff_admin ACC 工具（F4a'，v1.25.0 实验性，第 12 个工具）
+*
+* 教 CCC 如何定义 Skiff 角色（仿 session 工具 hook-develop-guide 的 SEP 教学模式，
+* 用户拍板 2026-08-28：guide 定义教程 / validate 配置校验 / list 角色摘要）。
+*
+* 归属：ACC 机制工具（教会 + 校验），角色内容仍归 CCC 配置（.opencode/serenity.json skiff.roles）。
+*/
+function agentCwd$1(exec) {
+	return exec.agent?.session?.header?.cwd ?? process.cwd();
+}
+function renderText(value) {
+	return [{
+		type: "text",
+		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+	}];
+}
+/** Skiff 定义教程（核心）：概念 / schema / 认知 MSM 写法 / 双白名单 / 轨迹纪律 / 示例角色 */
+const SKIFF_GUIDE = `═══ Skiff Definition Guide (F4, experimental) ═══
+
+Skiff = 宁静号放出的独立小艇——完整 trajectory（在宁静号内全知全能）的**任意子集角色**。
+由本 CCC（.opencode/serenity.json skiff.roles）定义：能力面（双白名单）+ 轨迹纪律子集 + 系统提示词。
+dsp 只提供机制（双白名单强制 + 基础提示词 + 调试问答页）；角色内容完全由 CCC 发挥。
+
+── 角色配置 schema ──
+  { "skiff": { "roles": {
+      "<role-name>": {
+        "model": "provider/model",             // 角色模型（CCC 直接指定，无白名单校验；缺省回退 handyman.defaultModel）
+        "msms": ["msm-a", "msm-b"],            // MSM 白名单（独立）：acc_msm exec 只能跑这些；register/deregister 必拒；list 只显示这些
+        "tools": ["read","grep","glob",...],   // 非 MSM 工具白名单（独立）：白名单外工具一律不可用（guard 强制）
+        "trajectory": { "session": false, "keeper": false, "rebuild": false },  // 轨迹纪律子集（缺省全关 = 完全独立）
+        "systemPrompt": "..."                  // 角色人格/认知边界/风格（CCC 完整定义；dsp 只给基础提示词）
+      }
+  } } }
+
+── 双白名单语义（全按白名单暴露，白名单外全隐藏）──
+  - tools 空 + msms 非空 = 纯 MSM 角色（认知问答典型形态）
+  - msms 非空 → acc_msm 工具自动可用（MSM 通道）
+  - 白名单外工具即使 DSH 未来新增也自动被挡（guard 按角色判定，不枚举工具名——完备性）
+
+── 认知 MSM 写法（读知识 / 操作能力）──
+  - 读知识：脚本读 CCC 内文件（SERENITY_ROOT env 注入）→ 输出答案/摘要（如 cognitive-qa）
+  - 操作能力：脚本调用既有家庭工具/服务（SSH/API/文件操作）——角色能力上限 = 白名单 MSM 的实际行为
+  - 例：cognitive-qa（读 docs/references 回答）、review-scan（读代码出审查意见）、review-fix（写修复）
+  - 注意：MSM 在脚本层执行（bun），文件访问不受 agent 工具面约束——"只读"语义靠 CCC 自写 MSM 自觉
+
+── 轨迹纪律子集（trajectory）──
+  - session/keeper/rebuild 默认 false：Skiff 完全独立（不建 SESSION.md、无 keeper 提醒、无 rebuild 压力检测）
+  - 开启某项 = 该角色参与对应轨迹机制（如 keeper=true 计分提醒按角色生效）
+
+── 示例角色 ──
+  qa-readonly: { "msms": ["cognitive-qa"], "tools": [], "trajectory": {} }
+      → 认知问答（仅 MSM 通道，无直接工具，完全独立）
+  code-review: { "msms": ["review-scan","review-fix"], "tools": ["read","grep","glob","write","edit"], "trajectory": { "keeper": true } }
+      → 有操作能力（可写修复），参与 keeper 轨迹机制
+
+── 运行 ──
+  调试：设置面板「Serenity」页 Skiff 区块开启 → http://127.0.0.1:<debugPort> 问答页实测
+  （v1.25.0 唯一客户端面；ACP stdio 协议 F4c 后续，与调试页共用同一会话核心）
+  启停 = 人工（设置面板开关，不随插件加载自动启动）；未开启零资源占用`;
+/** 校验当前 CCC 的 skiff 配置：roles schema 合法 / msms 均已注册 / model ∈ handyman.models / systemPrompt 非空 */
+function validateSkiffConfig(root) {
+	const roles = readSkiffRoles(root);
+	const issues = [];
+	if (roles.size === 0) return {
+		ok: true,
+		issues: [],
+		roleCount: 0,
+		note: "no skiff roles defined (skiff disabled — zero impact)"
+	};
+	const registered = new Set(loadMsmEntries(root).map((e) => e.name));
+	const hc = readHandymanConfig(root);
+	const allowedModels = hc ? new Set(hc.models) : null;
+	for (const [name, role] of roles) {
+		if (!role.systemPrompt?.trim()) issues.push(`role "${name}": systemPrompt is empty (CCC should fully define the role persona)`);
+		for (const m of role.msms ?? []) if (!registered.has(m)) issues.push(`role "${name}": msms "${m}" is not registered in mech-registry.json`);
+		if (role.model && allowedModels && !allowedModels.has(role.model)) issues.push(`role "${name}": model "${role.model}" not in handyman.models (${[...allowedModels].join(", ") || "(none)"})`);
+	}
+	return {
+		ok: issues.length === 0,
+		issues,
+		roleCount: roles.size
+	};
+}
+/** 列出当前 CCC 已定义角色（名 / 模型 / msms / tools / 轨迹纪律摘要） */
+function listSkiffRoles(root) {
+	const roles = readSkiffRoles(root);
+	if (roles.size === 0) return {
+		roles: [],
+		note: "no skiff roles defined (skiff disabled)"
+	};
+	const items = [...roles.entries()].map(([name, role]) => ({
+		name,
+		model: role.model ?? "(handyman default)",
+		msms: role.msms ?? [],
+		tools: role.tools ?? [],
+		trajectory: {
+			session: role.trajectory?.session === true,
+			keeper: role.trajectory?.keeper === true,
+			rebuild: role.trajectory?.rebuild === true
+		},
+		hasSystemPrompt: Boolean(role.systemPrompt?.trim())
+	}));
+	return {
+		roles: items,
+		count: items.length
+	};
+}
+const skiffAdminTool = defineTool({
+	name: "skiff_admin",
+	description: "Skiff (F4, experimental): CCC cognitive-subset roles (subsets of the full serenity trajectory). guide: definition tutorial (concept/role schema/cognitive MSM writing/dual whitelist/trajectory subset/examples); validate: check the CCC skiff config (roles schema legal / msms registered / model in handyman.models / systemPrompt non-empty); list: role summary (name/model/msms/tools/trajectory). Roles are defined by the CCC in .opencode/serenity.json skiff.roles.",
+	parameters: { action: {
+		type: "string",
+		enum: [
+			"guide",
+			"validate",
+			"list"
+		],
+		required: true,
+		description: "Subcommand: guide (definition tutorial) / validate (config check) / list (role summary)"
+	} },
 	output: {
 		schema: { type: "json" },
 		render: (args, value) => renderText(value)
@@ -6454,7 +6890,12 @@ const localstoreTool = defineTool({
 	async execute(args, exec) {
 		const root = findSerenityRoot(agentCwd$1(exec));
 		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
-		return runLocalStore(root, args);
+		switch (args.action) {
+			case "guide": return { guide: SKIFF_GUIDE };
+			case "validate": return validateSkiffConfig(root);
+			case "list": return listSkiffRoles(root);
+			default: throw new Error("skiff_admin requires action: guide | validate | list");
+		}
 	}
 });
 //#endregion
@@ -6563,9 +7004,13 @@ function registerKeeper(ctx, opts = {}) {
 	};
 	ctx.on("tools/post-execute", async (exec, _result, next) => {
 		if (!exec.agent) return next();
-		if (!findSerenityRoot(exec.agent?.session?.header?.cwd ?? process.cwd())) return next();
+		const root = findSerenityRoot(exec.agent?.session?.header?.cwd ?? process.cwd());
+		if (!root) return next();
+		const sessionId = exec.agent?.session?.id;
+		const skiffKeeper = skiffTrajectoryEnabled(root, sessionId, "keeper");
+		const skiffRebuild = skiffTrajectoryEnabled(root, sessionId, "rebuild");
 		const tracker = trackerFor(exec);
-		const shouldRemind = tracker.step(exec.name);
+		const shouldRemind = skiffKeeper ? tracker.step(exec.name) : false;
 		const downstream = await next();
 		const blocks = [];
 		if (shouldRemind) {
@@ -6575,7 +7020,7 @@ function registerKeeper(ctx, opts = {}) {
 				text: reminderText(code, tracker.currentScore)
 			});
 		}
-		if (readSimpleSettings().rebuildEnabled) {
+		if (skiffRebuild && readSimpleSettings().rebuildEnabled) {
 			const session = exec.agent?.session;
 			if (session) {
 				const pressure = readContextPressure(ctx, session);
@@ -7040,6 +7485,7 @@ function accBlock(root) {
 		"  handyman  — delegate a do-everything worker agent (CCC-whitelisted model) to run synchronously in rounds until done, recursing into same-model subagents; jobs=[] orchestrates parallel work",
 		"  session_rebuild — rebuild this conversation in place from SESSION.md when the trajectory-tracker trips",
 		"  localstore — ACC local credential/config storage (CCC-root localstore.json, JSON format; git policy localstore.gitTrack default deny); doc subcommand outputs the spec",
+		"  skiff_admin — Skiff (F4, experimental): CCC cognitive-subset roles — guide (definition tutorial) / validate (config check) / list (role summary)",
 		"",
 		"  ℹ️ Use relative paths from the CCC root for CCC-internal file operations (read/write/edit/glob/grep etc.), e.g. AGENT_SESSIONS/2026-08-14--S134--x/SESSION.md; Root / absolute SESSION.md paths are identifiers only, not tool arguments",
 		"",
@@ -7442,7 +7888,9 @@ function registerEntrySkillSectionGlobal(ctx) {
 				if (!cwd) return "";
 				const root = findSerenityRoot(cwd);
 				if (!root) return "";
-				const base = serenitySystemPrompt(root, agentScope$1(context));
+				const scope = agentScope$1(context);
+				if (isSkiffSessionId(scope)) return "";
+				const base = serenitySystemPrompt(root, scope);
 				const codeLine = codeModeAdaptationLine(ctx, context.scope);
 				return codeLine ? `${base}\n${codeLine}` : base;
 			}
@@ -7474,6 +7922,7 @@ function registerEntrySkillSection(agent, root) {
 			name: "serenity-entry",
 			order: -50,
 			text: (context) => {
+				if (isSkiffSessionId(scope)) return "";
 				const base = serenitySystemPrompt(root, scope);
 				const codeLine = codeModeAdaptationLine(agent.ctx, context.scope);
 				return codeLine ? `${base}\n${codeLine}` : base;
@@ -7550,6 +7999,7 @@ function shouldAutoRestore(agent) {
 	if (session.header?.origin === "subagent") return false;
 	if (session.header?.parentSession) return false;
 	if (session.id?.startsWith("handyman-")) return false;
+	if (isSkiffSessionId(session.id)) return false;
 	return true;
 }
 /**
@@ -7569,6 +8019,7 @@ function registerContext(ctx, opts = {}) {
 		const root = findSerenityRoot(agent.session?.header?.cwd ?? process.cwd());
 		if (!root) return;
 		const key = agentKey(agent);
+		if (isSkiffSessionId(key)) return;
 		registerEntrySkillSection(agent, root);
 		const scope = agentScope(agent);
 		if (shouldRestoreActive(agent) && getActiveSessionInfo(scope) === null) try {
@@ -7601,6 +8052,7 @@ function registerContext(ctx, opts = {}) {
 		const root = findSerenityRoot(agent.session?.header?.cwd ?? process.cwd());
 		const key = agentKey(agent);
 		const downstream = await next();
+		if (isSkiffSessionId(key)) return downstream;
 		if (root) {
 			try {
 				syncSafeModeRestriction(agent, root);
@@ -7631,6 +8083,7 @@ function registerCompactRetention(ctx, opts = {}) {
 	ctx.on("session/event", (session, event) => {
 		if (event.type !== "compaction/end") return;
 		if (event.data.error) return;
+		if (isSkiffSessionId(String(session.id ?? ""))) return;
 		const agent = ctx.agents.get(session.id);
 		if (!agent) return;
 		const root = findSerenityRoot(agent.session?.header?.cwd ?? process.cwd());
@@ -7729,7 +8182,7 @@ function saveFileToTmp(root, fileName, data) {
 	writeFileSync(join(dir, filename), bytes);
 	return `${FILE_UPLOAD_DIR}/${filename}`;
 }
-function readBody$1(req, maxBytes) {
+function readBody$2(req, maxBytes) {
 	return new Promise((resolve, reject) => {
 		let data = "";
 		req.on("data", (chunk) => {
@@ -7743,7 +8196,7 @@ function readBody$1(req, maxBytes) {
 		req.on("error", reject);
 	});
 }
-function sendJson(res, code, body) {
+function sendJson$1(res, code, body) {
 	const payload = JSON.stringify(body);
 	res.writeHead(code, {
 		"content-type": "application/json; charset=utf-8",
@@ -7781,7 +8234,7 @@ function registerStatusApi(ctx, opts = {}) {
 		handler: async (req, res) => {
 			try {
 				if (req.method !== "GET") {
-					sendJson(res, 405, { error: "method not allowed" });
+					sendJson$1(res, 405, { error: "method not allowed" });
 					return;
 				}
 				const url = new URL(req.url ?? "/", "http://127.0.0.1");
@@ -7790,12 +8243,12 @@ function registerStatusApi(ctx, opts = {}) {
 					workspace: url.searchParams.get("workspace") ?? void 0
 				}));
 				if (!root) {
-					sendJson(res, 200, { handymen: [] });
+					sendJson$1(res, 200, { handymen: [] });
 					return;
 				}
-				sendJson(res, 200, { handymen: listActiveHandymen(root) });
+				sendJson$1(res, 200, { handymen: listActiveHandymen(root) });
 			} catch (err) {
-				sendJson(res, 400, { error: err.message ?? String(err) });
+				sendJson$1(res, 400, { error: err.message ?? String(err) });
 			}
 		}
 	});
@@ -7805,14 +8258,14 @@ function registerStatusApi(ctx, opts = {}) {
 		handler: async (req, res) => {
 			try {
 				if (req.method !== "POST") {
-					sendJson(res, 405, { error: "method not allowed" });
+					sendJson$1(res, 405, { error: "method not allowed" });
 					return;
 				}
 				if (req.headers["x-serenity-ui"] !== "1") {
-					sendJson(res, 403, { error: "图片落盘仅限 WebUI（client 专用）" });
+					sendJson$1(res, 403, { error: "图片落盘仅限 WebUI（client 专用）" });
 					return;
 				}
-				const raw = await readBody$1(req, 20971520);
+				const raw = await readBody$2(req, 20971520);
 				const body = JSON.parse(raw);
 				const workspace = resolveWorkspace(ctx, {
 					sessionId: body.sessionId,
@@ -7820,12 +8273,12 @@ function registerStatusApi(ctx, opts = {}) {
 				});
 				const root = findSerenityRoot(workspace);
 				if (!root) {
-					sendJson(res, 404, { error: `no CCC found from workspace: ${workspace}` });
+					sendJson$1(res, 404, { error: `no CCC found from workspace: ${workspace}` });
 					return;
 				}
-				sendJson(res, 200, { path: saveImageToTmp(root, body.mediaType ?? "", body.data ?? "") });
+				sendJson$1(res, 200, { path: saveImageToTmp(root, body.mediaType ?? "", body.data ?? "") });
 			} catch (err) {
-				sendJson(res, 400, { error: err.message ?? String(err) });
+				sendJson$1(res, 400, { error: err.message ?? String(err) });
 			}
 		}
 	});
@@ -7835,14 +8288,14 @@ function registerStatusApi(ctx, opts = {}) {
 		handler: async (req, res) => {
 			try {
 				if (req.method !== "POST") {
-					sendJson(res, 405, { error: "method not allowed" });
+					sendJson$1(res, 405, { error: "method not allowed" });
 					return;
 				}
 				if (req.headers["x-serenity-ui"] !== "1") {
-					sendJson(res, 403, { error: "文件落盘仅限 WebUI（client 专用）" });
+					sendJson$1(res, 403, { error: "文件落盘仅限 WebUI（client 专用）" });
 					return;
 				}
-				const raw = await readBody$1(req, 20971520);
+				const raw = await readBody$2(req, 20971520);
 				const body = JSON.parse(raw);
 				const workspace = resolveWorkspace(ctx, {
 					sessionId: body.sessionId,
@@ -7850,12 +8303,12 @@ function registerStatusApi(ctx, opts = {}) {
 				});
 				const root = findSerenityRoot(workspace);
 				if (!root) {
-					sendJson(res, 404, { error: `no CCC found from workspace: ${workspace}` });
+					sendJson$1(res, 404, { error: `no CCC found from workspace: ${workspace}` });
 					return;
 				}
-				sendJson(res, 200, { path: saveFileToTmp(root, body.name ?? "", body.data ?? "") });
+				sendJson$1(res, 200, { path: saveFileToTmp(root, body.name ?? "", body.data ?? "") });
 			} catch (err) {
-				sendJson(res, 400, { error: err.message ?? String(err) });
+				sendJson$1(res, 400, { error: err.message ?? String(err) });
 			}
 		}
 	});
@@ -7871,7 +8324,7 @@ function registerStatusApi(ctx, opts = {}) {
 						workspace: url.searchParams.get("workspace") ?? void 0
 					}), configPaths);
 					const runtime = ctx.get("codeRuntime");
-					sendJson(res, 200, {
+					sendJson$1(res, 200, {
 						...status,
 						...runtime === void 0 ? { codeRuntime: null } : { codeRuntime: {
 							language: runtime.language,
@@ -7882,10 +8335,10 @@ function registerStatusApi(ctx, opts = {}) {
 				}
 				if (req.method === "POST") {
 					if (req.headers["x-serenity-ui"] !== "1") {
-						sendJson(res, 403, { error: "safe-mode 切换仅限 WebUI（agent 不可自行开关）" });
+						sendJson$1(res, 403, { error: "safe-mode 切换仅限 WebUI（agent 不可自行开关）" });
 						return;
 					}
-					const raw = await readBody$1(req, 65536);
+					const raw = await readBody$2(req, 65536);
 					const body = JSON.parse(raw);
 					const workspace = resolveWorkspace(ctx, {
 						sessionId: body.sessionId,
@@ -7893,19 +8346,19 @@ function registerStatusApi(ctx, opts = {}) {
 					});
 					const root = findSerenityRoot(workspace);
 					if (!root) {
-						sendJson(res, 404, { error: `no CCC found from workspace: ${workspace}` });
+						sendJson$1(res, 404, { error: `no CCC found from workspace: ${workspace}` });
 						return;
 					}
 					const result = setSafeMode(root, body.on === true);
-					sendJson(res, 200, {
+					sendJson$1(res, 200, {
 						...getStatus(workspace, configPaths),
 						...result
 					});
 					return;
 				}
-				sendJson(res, 405, { error: "method not allowed" });
+				sendJson$1(res, 405, { error: "method not allowed" });
 			} catch (err) {
-				sendJson(res, 400, { error: err.message ?? String(err) });
+				sendJson$1(res, 400, { error: err.message ?? String(err) });
 			}
 		}
 	});
@@ -7915,25 +8368,25 @@ function registerStatusApi(ctx, opts = {}) {
 		handler: async (req, res) => {
 			try {
 				if (req.headers["x-serenity-ui"] !== "1") {
-					sendJson(res, 403, { error: "高级设定仅限 WebUI（client 专用）" });
+					sendJson$1(res, 403, { error: "高级设定仅限 WebUI（client 专用）" });
 					return;
 				}
 				if (req.method === "GET") {
-					sendJson(res, 200, { config: toWire(readAdvancedSettings()) });
+					sendJson$1(res, 200, { config: toWire(readAdvancedSettings()) });
 					return;
 				}
 				if (req.method === "PUT") {
-					const raw = await readBody$1(req, 131072);
+					const raw = await readBody$2(req, 131072);
 					const saved = applyWirePatch(JSON.parse(raw).config ?? {});
 					try {
 						ctx.emit?.("serenity/config-updated");
 					} catch {}
-					sendJson(res, 200, { config: toWire(saved) });
+					sendJson$1(res, 200, { config: toWire(saved) });
 					return;
 				}
-				sendJson(res, 405, { error: "method not allowed" });
+				sendJson$1(res, 405, { error: "method not allowed" });
 			} catch (err) {
-				sendJson(res, 400, { error: err.message ?? String(err) });
+				sendJson$1(res, 400, { error: err.message ?? String(err) });
 			}
 		}
 	});
@@ -8389,7 +8842,7 @@ function buildProxyHeaders(reqHeaders, mainPort, bodyOverride) {
 //#endregion
 //#region src/gateway.ts
 /** 读取请求体（≤ maxBytes；超限 reject） */
-function readBody(req, maxBytes) {
+function readBody$1(req, maxBytes) {
 	return new Promise((resolve, reject) => {
 		let data = "";
 		req.on("data", (chunk) => {
@@ -8522,7 +8975,7 @@ function startGateway(config, getAccounts) {
 		if (session !== void 0) {
 			if (req.method === "POST" && url.pathname === "/api/workspace.create") {
 				if (!allowWorkspaceCreate) {
-					readBody(req, 131072).then((body) => {
+					readBody$1(req, 131072).then((body) => {
 						let rpcId = "unknown";
 						try {
 							const parsed = JSON.parse(body);
@@ -8558,7 +9011,7 @@ function startGateway(config, getAccounts) {
 					});
 					return;
 				}
-				readBody(req, 131072).then((body) => {
+				readBody$1(req, 131072).then((body) => {
 					let rpcId = "unknown";
 					let path;
 					try {
@@ -8839,6 +9292,214 @@ function registerGateway(ctx) {
 	});
 }
 //#endregion
+//#region src/skiff-debug.ts
+/**
+* skiff-debug.ts — Skiff 调试问答页（F4a'，v1.25.0 实验性）
+*
+* node:http 调试端口（默认关，仅监听 127.0.0.1；启停 = 人工——设置面板「Serenity」
+* 页 Skiff 区块开关，不随插件加载自动启动）。
+*
+* - GET  /        → 问答 HTML 页（角色下拉 + 输入框 + 答案区 + 轨迹区 + WebUI 链接）
+* - POST /ask     → {role, question} → 走会话核心（skiff-core）→ {answer, sessionId, trajectory}
+*
+* 与 ACP stdio 协议（F4c 后续）共用同一会话核心（createSkiffAgent + askSkiff），
+* 协议层后加不返工。轨迹 = session.events 结构化返回（与 dsh WebUI 同源数据），
+* 页面 JS 渲染成对话时间线；同时保留原生 WebUI 会话链接供完整交互。
+*
+* 实验性质：未开启时零资源占用（无监听、无 agent 创建）。
+*/
+/** 运行中的调试服务（单实例；进程级） */
+let active = null;
+function readBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		req.on("data", (c) => chunks.push(c));
+		req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+		req.on("error", reject);
+	});
+}
+function sendJson(res, status, payload) {
+	const body = JSON.stringify(payload);
+	res.writeHead(status, {
+		"Content-Type": "application/json; charset=utf-8",
+		"Cache-Control": "no-store"
+	});
+	res.end(body);
+}
+function sendHtml(res, html) {
+	res.writeHead(200, {
+		"Content-Type": "text/html; charset=utf-8",
+		"Cache-Control": "no-store"
+	});
+	res.end(html);
+}
+/** 问答页 HTML：角色下拉 + 输入 + 答案区 + 轨迹区（JS 渲染）+ WebUI 链接 */
+function skiffDebugPage(roles, webPort) {
+	const roleOptions = [...roles.entries()].map(([name, r]) => `<option value="${escapeHtml(name)}">${escapeHtml(name)}${r.model ? ` (${escapeHtml(r.model)})` : ""}</option>`).join("\n");
+	const webUrl = `http://127.0.0.1:${webPort}`;
+	return `<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Skiff Debug — CCC cognitive subset roles</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font-family: system-ui, -apple-system, sans-serif; margin: 0; padding: 24px; background: #f6f7f9; color: #1f2328; }
+  @media (prefers-color-scheme: dark) { body { background: #1a1b1e; color: #e6e6e6; } }
+  main { max-width: 720px; margin: 0 auto; }
+  h1 { font-size: 18px; margin: 0 0 4px; }
+  .sub { opacity: .65; font-size: 13px; margin-bottom: 16px; }
+  label { font-size: 13px; font-weight: 600; display: block; margin: 12px 0 4px; }
+  select, textarea { width: 100%; box-sizing: border-box; padding: 8px 10px; border-radius: 8px; border: 1px solid #d0d7de; background: #fff; color: inherit; font-size: 14px; }
+  @media (prefers-color-scheme: dark) { select, textarea { background: #26282c; border-color: #3a3d42; } }
+  textarea { min-height: 72px; resize: vertical; }
+  button { margin-top: 12px; padding: 9px 18px; border-radius: 8px; border: 0; background: #0ba875; color: #fff; font-size: 14px; font-weight: 600; cursor: pointer; }
+  button:disabled { opacity: .55; cursor: wait; }
+  #answer { white-space: pre-wrap; background: #fff; border: 1px solid #d0d7de; border-radius: 8px; padding: 12px; margin-top: 16px; font-size: 14px; line-height: 1.55; min-height: 48px; }
+  @media (prefers-color-scheme: dark) { #answer { background: #26282c; border-color: #3a3d42; } }
+  #trajectory { margin-top: 12px; font-size: 13px; }
+  .t-entry { border-left: 2px solid #d0d7de; padding: 6px 10px; margin: 6px 0; border-radius: 0 6px 6px 0; background: rgba(127,127,127,.06); white-space: pre-wrap; word-break: break-word; }
+  .t-user { border-left-color: #0ba875; }
+  .t-tool { border-left-color: #d29922; opacity: .85; font-family: ui-monospace, monospace; font-size: 12px; }
+  .t-role { font-weight: 600; font-size: 11px; text-transform: uppercase; letter-spacing: .04em; opacity: .6; margin-bottom: 2px; }
+  .muted { opacity: .6; font-size: 13px; }
+  a { color: #0ba875; }
+  .err { color: #cf222e; white-space: pre-wrap; }
+</style>
+</head>
+<body>
+<main>
+  <h1>Skiff Debug</h1>
+  <div class="sub">宁静号 trajectory 子集角色问答页（v1.25.0 实验性）— 走 DSH agent-loop 会话核心，轨迹与 WebUI 同源</div>
+  <label for="role">角色</label>
+  <select id="role">${roleOptions || "<option value=\"\">(未配置角色)</option>"}</select>
+  <label for="q">问题</label>
+  <textarea id="q" placeholder="向该角色提问…"></textarea>
+  <button id="ask">提问</button>
+  <div id="answer" class="muted">等待提问…</div>
+  <div id="trajectory"></div>
+  <p class="muted"><a href="${webUrl}" target="_blank" rel="noopener">在 dsh WebUI 查看完整会话</a>（会话列表搜索 sessionId；WebUI 有完整交互）</p>
+</main>
+<script>
+const btn = document.getElementById('ask')
+const answer = document.getElementById('answer')
+const traj = document.getElementById('trajectory')
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]))
+btn.addEventListener('click', async () => {
+  const role = document.getElementById('role').value
+  const q = document.getElementById('q').value.trim()
+  if (!role || !q) { answer.className = 'err'; answer.textContent = '请选择角色并输入问题'; return }
+  btn.disabled = true
+  answer.className = 'muted'
+  answer.textContent = '运行中…'
+  traj.innerHTML = ''
+  try {
+    const res = await fetch('/ask', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ role, question: q }) })
+    const data = await res.json()
+    if (!res.ok) throw new Error(data.error || ('HTTP ' + res.status))
+    answer.className = ''
+    answer.textContent = data.answer || '（空回答）'
+    renderTrajectory(data.trajectory || [], data.sessionId || '')
+  } catch (err) {
+    answer.className = 'err'
+    answer.textContent = String(err.message || err)
+  } finally {
+    btn.disabled = false
+  }
+})
+function renderTrajectory(entries, sessionId) {
+  if (entries.length === 0) { traj.innerHTML = '<div class="muted">（本轮无轨迹）</div>'; return }
+  traj.innerHTML = '<div class="sub">本轮轨迹 · ' + esc(sessionId) + '</div>' + entries.map((e) => {
+    const cls = e.role === 'user' ? 't-user' : (e.role === 'tool' ? 't-tool' : '')
+    const role = e.role === 'tool' ? 'tool' + (e.tool ? ' · ' + esc(e.tool) : '') : e.role
+    return '<div class="t-entry ' + cls + '"><div class="t-role">' + role + '</div>' + esc(e.text) + '</div>'
+  }).join('')
+}
+<\/script>
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+	return s.replace(/[&<>"']/g, (c) => ({
+		"&": "&amp;",
+		"<": "&lt;",
+		">": "&gt;",
+		"\"": "&quot;",
+		"'": "&#39;"
+	})[c] ?? c);
+}
+/**
+* 启动调试问答服务（单实例；重复启动幂等返回既有实例）。
+* @param root 当前 CCC 根（角色配置读取 + skiff agent cwd）
+* @param port 调试端口（仅 127.0.0.1）
+* @param webPort 主 WebUI 端口（WebUI 链接）
+*/
+async function startSkiffDebugServer(ctx, root, port, webPort) {
+	if (active) return;
+	const roles = readSkiffRoles(root);
+	const server = createServer((req, res) => {
+		handle(ctx, root, roles, webPort, req, res);
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, "127.0.0.1", () => resolve());
+	});
+	active = {
+		server,
+		port
+	};
+	console.log(`[serenity-hooks] ✓ Skiff 调试问答页: http://127.0.0.1:${port}（角色: ${roles.size}，WebUI: ${webPort}）`);
+}
+function stopSkiffDebugServer() {
+	if (!active) return;
+	try {
+		active.server.close();
+	} catch {}
+	active = null;
+}
+async function handle(ctx, root, roles, webPort, req, res) {
+	try {
+		const url = (req.url ?? "/").split("?")[0] ?? "/";
+		if (req.method === "GET" && url === "/") {
+			sendHtml(res, skiffDebugPage(roles, webPort));
+			return;
+		}
+		if (req.method === "POST" && url === "/ask") {
+			let body;
+			try {
+				const parsed = JSON.parse(await readBody(req));
+				if (parsed === null || typeof parsed !== "object") throw new Error("not an object");
+				body = parsed;
+			} catch {
+				sendJson(res, 400, { error: "invalid JSON body" });
+				return;
+			}
+			const roleName = typeof body.role === "string" ? body.role : "";
+			const question = typeof body.question === "string" ? body.question : "";
+			const role = roles.get(roleName);
+			if (!roleName || !role) {
+				sendJson(res, 400, { error: `unknown role: ${roleName}` });
+				return;
+			}
+			if (!question.trim()) {
+				sendJson(res, 400, { error: "empty question" });
+				return;
+			}
+			const result = await askSkiff(ctx, (await createSkiffAgent(ctx, root, roleName, role, readHandymanConfig(root)?.defaultModel)).agent, question);
+			sendJson(res, 200, {
+				answer: result.answer,
+				sessionId: result.sessionId,
+				trajectory: result.trajectory
+			});
+			return;
+		}
+		sendJson(res, 404, { error: "not found" });
+	} catch (err) {
+		sendJson(res, 500, { error: err?.message ?? String(err) });
+	}
+}
+//#endregion
 //#region src/index.ts
 const name = "dsh-serenity-hooks";
 /** 主动调用的服务；其余（agent 事件）随 harness 装配必然存在 */
@@ -8870,7 +9531,11 @@ const Config = z.object({
 		enabled: z.boolean().default(true),
 		thresholdRatio: z.number().min(.01).max(1).default(.9)
 	}),
-	naming: z.object({ enabled: z.boolean().default(true) })
+	naming: z.object({ enabled: z.boolean().default(true) }),
+	skiff: z.object({
+		enabled: z.boolean().default(false),
+		debugPort: z.number().min(1024).max(65535).default(3099)
+	})
 });
 function apply(ctx, config) {
 	if (config.tools) {
@@ -8885,6 +9550,7 @@ function apply(ctx, config) {
 		ctx.tools.register(createHandymanTool(ctx));
 		ctx.tools.register(createRebuildTool(ctx));
 		ctx.tools.register(localstoreTool);
+		ctx.tools.register(skiffAdminTool);
 	}
 	if (config.guards) registerGuards(ctx, { configPaths: config.serenityConfigPaths });
 	if (config.keeper) registerKeeper(ctx, {
@@ -8907,6 +9573,63 @@ function apply(ctx, config) {
 	if (config.env) registerEnv(ctx);
 	if (config.opencodeSkills) registerOpencodeSkills(ctx);
 	registerBootstrap(ctx);
+	registerSkiff(ctx);
+}
+/**
+* F4 Skiff 调试服务装配：启停 = 人工（设置面板 Skiff 区块开关，settings 持久化）。
+* settings-changed 事件触发同步（skiffEnabled 开 → 启动调试服务；关 → 停止）。
+* 角色配置（skiff.roles）从当前 CCC 根读取（进程 cwd 优先，live 会话兜底）。
+*/
+function registerSkiff(ctx) {
+	let started = false;
+	const sync = () => {
+		const s = readSimpleSettings();
+		if (s.skiffEnabled && !started) {
+			const root = resolveSkiffRoot(ctx);
+			if (!root) {
+				console.warn("[serenity-hooks] ✗ Skiff 调试服务未启动：无法定位 CCC root（进程 cwd 与 live 会话均无 .serenity）");
+				return;
+			}
+			const webPort = readWebPort(ctx);
+			startSkiffDebugServer(ctx, root, s.skiffDebugPort, webPort).then(() => {
+				started = true;
+			}).catch((err) => {
+				console.error(`[serenity-hooks] ✗ Skiff 调试服务启动失败: ${String(err?.message ?? err)}`);
+			});
+		} else if (!s.skiffEnabled && started) {
+			stopSkiffDebugServer();
+			started = false;
+		}
+	};
+	try {
+		ctx.on("serenity/settings-changed", sync);
+	} catch {}
+	sync();
+}
+/** 解析当前 CCC 根：进程 cwd 上溯 .serenity 优先，live 会话 cwd 兜底 */
+function resolveSkiffRoot(ctx) {
+	const fromCwd = findSerenityRoot(process.cwd());
+	if (fromCwd) return fromCwd;
+	try {
+		const sessions = ctx.sessions;
+		for (const s of sessions?.list?.() ?? []) {
+			const cwd = s?.header?.cwd;
+			if (typeof cwd === "string") {
+				const r = findSerenityRoot(cwd);
+				if (r) return r;
+			}
+		}
+	} catch {}
+	return null;
+}
+/** 主 WebUI 端口（WebUI 链接；webServer 未装配回退 3080） */
+function readWebPort(ctx) {
+	try {
+		const ws = ctx.webServer;
+		return typeof ws?.port === "number" ? ws.port : 3080;
+	} catch {
+		return 3080;
+	}
 }
 //#endregion
 export { Config, apply, inject, name };