@shgroup/dsh-serenity-hooks 1.34.0 → 1.34.2

package/lib/autopilot-trajectory.d.ts

@@ -26,69 +26,20 @@
  *   · **默认关**：serenity.json autopilotTrajectory.enabled=false → 定时器不启动，零资源占用。
  */
 import type { Context } from 'cordis';
-import { type AutopilotTrajectorySettings } from './ccc.js';
-/** 偏见内容提供者脚本缺省名（CCC 根目录下；正式版 autopilot-bias.ts） */
-export declare const DEFAULT_BIAS_PROVIDER = "autopilot-bias.ts";
-/** 旧默认偏见脚本名（autotrajectory 时代；未显式配置时回退——pangu 等已配置 CCC 零迁移） */
-export declare const LEGACY_BIAS_PROVIDER = "autotrajectory-bias.ts";
-/** 自主轨迹会话目录后缀标志（--auto 保留——简短且历史会话 S060--auto 已存在） */
-export declare const AUTO_DIR_SUFFIX = "--auto";
-/** 调度 tick 周期（5min——用户"tick改为5分钟吧"；0.01h 间隔下每 5min 评估一次） */
-export declare const TICK_MS: number;
-/** 间隔下限（支持小数——用户"让它支持小数行吗，这样可以配0.01"；0.01h ≈ 36s） */
-export declare const MIN_INTERVAL_HOURS = 0.01;
-/** SESSION.md 内「下一轮动机」段标记（自生偏见载体——轨迹预设自己的未来） */
-export declare const MOTIVATION_MARKER = "\u4E0B\u4E00\u8F6E\u52A8\u673A";
-/** 缺省避开的高峰时段（北京时间 [start, end) 不唤起——用量峰谷省钱） */
-export declare const DEFAULT_AVOID_HOURS: {
-    start: number;
-    end: number;
-};
-/** 偏见脚本输出上限（沙箱：截断防失控——正式版 v1.27.4） */
-export declare const BIAS_OUTPUT_MAX: number;
-/** 偏见脚本执行超时（正式版沙箱；原 600s 过长阻塞 tick） */
-export declare const BIAS_RUN_TIMEOUT_MS = 60000;
-/** 审计历史 ring 上限（每 CCC 保留最近 N 条唤起记录） */
-export declare const AUDIT_HISTORY_MAX = 50;
-/** 读配置：`trajectory.autopilot`（D58 新键）优先 → 旧键 autopilotTrajectory → 旧键 autotrajectory */
-export declare function readAutopilotSettings(root: string): AutopilotTrajectorySettings | null;
-/**
- * 北京时间（UTC+8）当前小时——不依赖服务器时区（服务器可能 UTC/本地任意）。
- */
-export declare function beijingHour(nowMs: number): number;
-/**
- * 唤起窗口判定：北京时间 [avoidStart, avoidEnd) 内不唤起（缺省 8~18）。
- * 单段避开（start<=end）：窗口 = [0,start) ∪ [end,24)；跨零点避开（start>end）：窗口 = [end,start)。
- */
-export declare function inAllowedWakeWindow(nowMs: number, avoid?: {
-    start?: number;
-    end?: number;
-}): boolean;
-/** 标志位判定：SESSION.md 所在目录名以 --auto 结尾 → 自主轨迹形态 */
-export declare function isAutopilotSession(mdPath: string): boolean;
-/**
- * 目标会话定位：**必须配置 cfg.session**（S###/目录名）——CCC 日常有多条 trajectory 在跑，
- * 绝不默认唤起（缺省最近活跃会误伤其他正在运行的轨迹；用户拍板：必须配置才生效）。
- * 未配置 session 或未命中 → null（不唤起）。
- */
-export declare function resolveTargetMd(root: string, cfg: AutopilotTrajectorySettings): string | null;
-/**
- * 唤起条件（纯逻辑，可测）：enabled + 未在运行 + 目录标志 + mtime 超间隔 + 窗口允许。
- * v1.27.12：移除每日唤起预算上限（用户"把这个上限删了吧，没意义"——高频实验不受限）。
- */
-export declare function shouldWake(settings: AutopilotTrajectorySettings, mdPath: string | null, nowMs: number, running: boolean, _history?: readonly WakeRecord[]): boolean;
-/** 自生动机读取：SESSION.md「下一轮动机」段内容（到下一个二级标题或文件尾；无 → null） */
-export declare function readSelfGeneratedMotivation(mdPath: string): string | null;
+import type { AutopilotTrajectorySettings } from './ccc.js';
+import { type WakeRecord } from './autopilot-core.js';
+import { type ClockRuntime } from './clock-runtime.js';
+import type { WakeChainFacts } from './autopilot-chain.js';
 /**
- * 偏见内容：直接运行 CCC 根目录下偏见提供者脚本（biasProvider，缺省 autopilot-bias.ts；
- * 未显式配置且新默认缺失 → 回退旧默认 autotrajectory-bias.ts——pangu 兼容）→ stdout。
- * 脚本缺失 → 返回 { text: null, error: 提示实现 }（唤起侧报错要求实现，不静默跳过）。
- * 路径逃逸校验（resolveInside）；bun 优先，node 兜底；**60s 超时 + 8KB 输出截断（沙箱）**。
+ * 判据原语（`readAutopilotSettings` / `beijingHour` / `inAllowedWakeWindow` /
+ * `isAutopilotSession` / `resolveTargetMd` / `judgeWake` / `shouldWake` /
+ * `readSelfGeneratedMotivation` / `fetchBiasContent` / 常量）**已提取至
+ * `autopilot-core.ts`**（S142 §12.13 ⑥ C6a）——本文件是它们的**组合方之一**
+ * （tick + 面板 + agent 定位），不再自持判据副本。
+ * 提取理由与"三处消费方共用一份判据"的约束见该文件头部注释。
  */
-export declare function fetchBiasContent(root: string, providerRel: string): Promise<{
-    text: string | null;
-    error: string | null;
-}>;
+/** 审计历史 ring 上限（每 CCC 保留最近 N 条唤起记录） */
+export declare const AUDIT_HISTORY_MAX = 50;
 /** 唤起消息（四段式：轨迹焦点[CCC 定义，稳定] / 身份锚定 / 先验偏见[自生动机+偏见内容] / 任务）——注入前台会话，用户可见 */
 export declare function buildWakeMessage(opts: {
     sessionName: string;
@@ -99,13 +50,7 @@ export declare function buildWakeMessage(opts: {
     biasContent: string | null;
 }): string;
 /** 唤起结果（tick 日志 / 面板显示 / 审计记录共用） */
-export interface WakeResult {
-    ok: boolean;
-    detail: string;
-}
-/** 审计记录（每 CCC ring buffer——正式版 v1.27.4：可回看、可分析） */
-export interface WakeRecord {
-    time: number;
+interface WakeResult {
     ok: boolean;
     detail: string;
 }
@@ -134,25 +79,30 @@ export declare function performAutopilotWake(ctx: Context, root: string, setting
  * 读取顺序（迁移期，不回写）：`autopilotWakeEnabled`（新键）→ `autopilotEnabled`（旧键）→ false。
  * 用 `??` 而非 `||` 的理由：**新键显式 false 必须能覆盖旧键 true**（否则"关不掉"）。
  * 抽成模块级函数是为了让 {@link autopilotClockState}（诊断）与 tick 读**同一判据**。
+ *
+ * v1.34.1（⑥ C6a）：**导出**——CCC 工具面（`container_admin autopilot status`）与条件链
+ * （{@link autopilotRuntimeFacts}）必须读**这一份**闸值。旧独立脚本读不到它 ⇒ 闸关着也印
+ * 「✅ 唤起条件全部满足」（8 项分歧之首，见 SESSION §12.13 与现状稿 §4.4）。
  */
 export declare function autopilotGloballyEnabled(): boolean;
 /**
- * autopilot **进程态**（诊断用，模块级 = 进程级）。
- * 与 {@link wakeSchedulerState} 同规格：回答"时钟是否武装 / 上次 tick 何时 / 为何跳过"。
+ * autopilot **进程态**类型（诊断用，模块级 = 进程级）。
+ *
+ * C6b（P2）：字段由 {@link ClockRuntime}（**工厂那份**）提供，**字段名与语义一个字未改**。
+ * 与 {@link wakeSchedulerState} 的差别只有一项：本钟**没有** `lastTickLog`（结果进下方
+ * `wakeHistory` 审计 ring，不走 tick 日志）——故 `ClockRuntime.lastTickLog` 在工厂里是可选的。
  */
-interface AutopilotClockRuntime {
-    armed: boolean;
-    armedAt: number | null;
-    lastTickAt: number | null;
-    ticks: number;
-    lastSkipReason: string | null;
-}
-/** autopilot 时钟进程态快照（只读） */
-export declare function autopilotClockState(): AutopilotClockRuntime & {
-    enabled: boolean;
-};
-/** 测试用：复位进程态 */
+export type AutopilotClockRuntime = ClockRuntime;
+declare const clock: import("./clock-runtime.js").Clock;
+/**
+ * autopilot **进程态**快照（只读；`enabled` = 全局闸**当前**值）。
+ * ⚠️ 与 {@link wakeSchedulerState} 同规格，但**本钟无 `lastTickLog`**（见 {@link ClockOptions.logFrom}）。
+ */
+export declare function autopilotClockState(): ReturnType<typeof clock.snapshot>;
+/** 测试用：复位进程态（含 per-CCC 重入守卫，避免用例间串味） */
 export declare function __resetAutopilotClockStateForTest(): void;
+/** 该 CCC 是否有唤起轮正在进行中（tick 的 per-CCC 防重入判据；诊断读同一份） */
+export declare function autopilotWakeInFlight(root: string): boolean;
 /**
  * 装配（index.ts apply 调用）。时钟唤起（v1.26.14 修复 + v1.27.4 多 CCC 独立）：
  *
@@ -160,12 +110,12 @@ export declare function __resetAutopilotClockStateForTest(): void;
  * 修复：① 每次 tick 动态解析 root+settings ② 监听 session/created 启动定时器 ③ 优先实验 CCC。
  *
  * **v1.27.4 多 CCC 独立（用户"4个CCC能各自有autotrajectory吗"）**：
- * - 单定时器保留（TICK_MS 10min），每次 tick **遍历所有 live+enabled CCC**（collectAutopilotCccs）
+ * - 单定时器保留（TICK_MS 5min），每次 tick **遍历所有 live+enabled CCC**（collectAutopilotCccs）
  *   各自评估 shouldWake + 各自唤起——每 CCC 的 interval/session/bias/topPrompt/窗口独立
  * - `running` 守卫 **per-CCC**（不同 CCC 唤起互不阻塞）
  * - **全局串行化**（wakeChain：同 tick 多 CCC 到点 → 依次唤起，防模型并发挤兑）
  *
- * 零资源占用语义保留：无 enabled CCC → tick 内直接 return（定时器存在但每 10min 一次空检查，
+ * 零资源占用语义保留：无 enabled CCC → tick 内直接 return（定时器存在但每 5min 一次空检查，
  * unref 不阻塞进程退出）。
  */
 export declare function registerAutopilot(ctx: Context): void;
@@ -175,7 +125,7 @@ export declare function registerAutopilot(ctx: Context): void;
  * 命中/标志/空闲时长 + 当前窗口/可唤起判定 + 审计（最近唤起）。
  * 不运行偏见脚本（只报脚本是否就绪——运行验证走 trajectory random）。
  */
-export interface AutopilotTrajectoryStatus {
+interface AutopilotTrajectoryStatus {
     /** 是否配置了 trajectory.autopilot 段（.opencode/serenity.json；旧键 autopilotTrajectory / autotrajectory 回退） */
     configured: boolean;
     /** 总开关（缺省 false——未开零资源占用） */
@@ -213,13 +163,21 @@ export interface AutopilotTrajectoryStatus {
 }
 export declare function getAutopilotStatus(root: string): AutopilotTrajectoryStatus;
 /** live 会话条目（诊断/面板解析用；标题从 events 读） */
-export interface LiveSessionEntry {
+interface LiveSessionEntry {
     id: string;
     cwd: string | null;
     cccRoot: string | null;
     title: string | null;
 }
-/** 遍历 live 会话（sessions.list()）+ 补标题（events session/title latest-wins）+ ccc 归属 */
+/**
+ * live 会话清单（诊断/面板解析用；标题从 events 读）——**只枚举 live 会话本身**。
+ *
+ * C2：CCC 枚举（"本机有哪些 CCC"）**不在这里**，归 `ccc-roots.listCccs`（并集）。
+ * 本函数保留的是它**独有**的那部分：逐条 live 会话 + cwd 归属 + 标题 + id
+ * （诊断页需要"哪个会话属于哪个 CCC"，那是会话维度、不是 CCC 维度）。
+ * @param ctx 插件上下文
+ * @returns 逐条 live 会话（`cccRoot` = 该会话 cwd 的 CCC 归属，无 → null）
+ */
 export declare function listLiveSessions(ctx: Context): LiveSessionEntry[];
 /**
  * 收集所有「配置了 Autopilot Trajectory 的 live CCC」——**v1.27.4 多 CCC 独立**：
@@ -229,16 +187,6 @@ export declare function listLiveSessions(ctx: Context): LiveSessionEntry[];
 export declare function collectAutopilotCccs(ctx: Context, opts?: {
     includeDisabled?: boolean;
 }): string[];
-/**
- * 所有 live 会话所属的 CCC 根（去重，保持出现顺序）。
- *
- * 与 {@link collectAutopilotCccs} 的区别：**不要求该 CCC 配置 trajectory.autopilot**——
- * 唤醒注册表（wake-scheduler）的条目可以指向任何 CCC 的任何 trajectory。
- *
- * @param ctx 插件上下文
- * @returns CCC 根路径列表（无 live 会话 → `[]`）
- */
-export declare function collectLiveCccs(ctx: Context): string[];
 /**
  * 进程内诊断（trajectory diag-live 数据源；用户"排查访问不到 pangu 写个 msm"）——
  * 输出当前实例 live 会话清单（id/cwd/ccc/标题）+ 每个配置了 Autopilot 的 CCC
@@ -260,4 +208,23 @@ export interface DiagLiveReport {
     panelResolved: string | null;
 }
 export declare function diagLive(ctx: Context): DiagLiveReport;
+/**
+ * **条件链的运行态事实**（⑥ C6a 的核心出口）——把只有插件进程能看到的判据交给
+ * 条件链（{@link buildWakeChain} 的输入）：全局闸 / 重入守卫 / live 运行态。
+ *
+ * 为什么必须有（这是 C6 的动机本身）：旧独立脚本只能读文件 ⇒ 结构性地看不到这三样，
+ * 于是逐条件报告**必然**与实际唤起行为分歧（8 项，见 `acc-component-relations-current-state.md` §4.4）。
+ * 搬进进程内之后，`container_admin autopilot status` 与 `acc-diag` ④ 段读的就是**同一份事实**。
+ *
+ * `ctx` 可传 `null`（**不是**"三项全不可知"）：全局闸（`readSimpleSettings`）与重入守卫
+ * （模块级 `runningByRoot`）**都不需要 ctx**，无 ctx 时也应读出真值——只有 live 运行态
+ * （live 会话 / agent 可解析）依赖 ctx，那才是真正的"不可知"。
+ * 这条区分由 `autopilot-ops.test.ts` 的全局闸可见性用例逼出来（首版把三者一起降级为不可知，
+ * 使"闸关"在无 ctx 路径下隐形——正是本轮要消灭的那类假报告）。
+ *
+ * @param ctx 插件上下文（读 live 会话 + agent）；null = 无进程上下文（live 标不可知）
+ * @param root 目标 CCC 根
+ * @returns 条件链事实（`live` 为 null 表示"live 运行态不可知"）
+ */
+export declare function autopilotRuntimeFacts(ctx: Context | null, root: string): WakeChainFacts;
 export {};

package/lib/ccc-roots-Bd_SjEs7.js

@@ -0,0 +1,152 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { i as hostSessions, r as hostService } from "./access-fiehjxV6.js";
+import { a as findSerenityRoot } from "./ccc-NlLr_sxy.js";
+import { basename } from "node:path";
+//#region src/ccc-roots.ts
+/**
+* ccc-roots.ts — CCC 根解析的**唯一判断层**（L1 单根解析 + L2 全量枚举）
+*
+* 为什么存在（C2「CCC 发现面归一」，S142 2026-09-15 Q5 裁决）：
+* 「这个会话/路径属于哪个 CCC 根」（L1）与「本机有哪些 CCC」（L2）这两层判断此前被
+* 独立实现在 ~19 处，且互有分歧（同一进程内三个面可指向不同 CCC；"live CCC 列表"有三份
+* 不同答案；三层发现是**短路**而非合并 ⇒ 名单不全）。本模块把这两层**收成一个出口**：
+* 调用方只问本模块，不再各写各的上溯 + 兜底。
+*
+* 分层（唯一真相源边界，**不要**把下层搬进本模块）：
+*  - **L0 原语** `findSerenityRoot(cwd)`（`ccc.ts:16`）——**仍是唯一** L0 实现，本模块从它 import。
+*  - **L1 单根解析** —— 本模块：{@link agentCwdFor}（agent/exec → cwd）与
+*    {@link cccRootForCwd}/{@link cccRootForExec}（cwd → 根）。
+*  - **L2 全量枚举** —— 本模块：{@link listCccs}。
+*  - **L3 CCC 名解析** `readCccName`（`ccc.ts`）——不在本模块，也不与 `skills-discovery` 的
+*    第二份实现合并（那是另一条开放项）。
+*
+* 不新增持久状态（Q5 裁决：**不新增"本机 CCC 名单"**、不扫盘、不写路径假设）——
+* 枚举只读 **DSH 已有的三个来源**。
+*/
+var ccc_roots_exports = /* @__PURE__ */ __exportAll({
+	NO_CCC_FROM_AGENT_CWD: () => NO_CCC_FROM_AGENT_CWD,
+	agentCwdFor: () => agentCwdFor,
+	cccRootForCwd: () => cccRootForCwd,
+	cccRootForExec: () => cccRootForExec,
+	listCccs: () => listCccs
+});
+/**
+* 取调用方的工作目录（**语义逐字保留**自原先散落 10 份的工具内副本）：
+* `exec.agent?.session?.header?.cwd ?? process.cwd()`。
+*
+* ⚠️ 无 `exec.agent` 时回落进程 cwd —— "用服务启动目录冒充会话目录"是**既有语义**，
+* 不是本模块的选择（改它会动到 9 个工具的根解析行为）。已知副作用与规避见
+* `tools/handyman.ts` 的「调用形态检查前移」补偿（`?? process.cwd()` 会把真因
+* "exec.agent 不存在"盖成 `No CCC found`）。
+*/
+function agentCwdFor(execOrAgent) {
+	return execOrAgent.agent?.session?.header?.cwd ?? execOrAgent.session?.header?.cwd ?? process.cwd();
+}
+/**
+* cwd → CCC 根（L0 原语的唯一调用形态；`ccc.ts` 之外不要再各写一遍）。
+* @param cwd 起始路径（目录或文件；文件会靠 `dirname` 上溯）
+* @returns CCC 根绝对路径；不在任何 CCC 内 → `null`
+*/
+function cccRootForCwd(cwd) {
+	return findSerenityRoot(cwd);
+}
+/**
+* 工具/缝入口的根解析（L1 标准形态）：`agentCwdFor(...)` 再上溯。
+* @returns CCC 根；解析不到 → `null`（**不**回落假根——"回落进程 cwd 当根"是 `rebuild.ts`
+*   独有的另一条语义，见该处注释）
+*/
+function cccRootForExec(execOrAgent) {
+	return findSerenityRoot(agentCwdFor(execOrAgent));
+}
+/**
+* 工具根解析失败时抛出的**统一**错误文案。
+* 9 个工具原先各写一份字面量（内容完全相同）；抽成常量以保单一真相源，
+* **文案逐字不变**（外在行为不变）。
+*/
+const NO_CCC_FROM_AGENT_CWD = "No CCC found: no .serenity file from agent cwd";
+/** 起点路径集合会被逐条 `findSerenityRoot` 上溯并按根去重（保序） */
+function makeCollector() {
+	const roots = [];
+	return {
+		roots,
+		push(cwd) {
+			if (typeof cwd !== "string" || cwd === "") return;
+			const r = findSerenityRoot(cwd);
+			if (r && !roots.includes(r)) roots.push(r);
+		}
+	};
+}
+/**
+* ① **dsh 工作区注册表**（`workspaceRegistry.list`，持久化——所有工作目录即使无 live 会话）。
+* S142 用户 2026-08-29：应直接拉 dsh 工作区，且只列具体 CCC。
+*/
+function workspaceRegistryPaths(ctx) {
+	const out = [];
+	try {
+		const registry = hostService(ctx, "workspaceRegistry");
+		for (const ws of registry?.list?.() ?? []) if (typeof ws?.path === "string") out.push(ws.path);
+	} catch {}
+	return out;
+}
+/**
+* ② **dsh 持久化会话**（`sessionPersistence.list`，必装配服务——覆盖所有历史会话工作目录）。
+*
+* v1.31.6 适配 0.1.5-rc.1：`list()` 返回形状变了（**静默突破**——形状由本处断言自写，
+* 宿主改名/改形在类型检查里看不见）：
+*   0.1.2      → `Promise<SessionHeader[]>`             → `h.cwd`
+*   0.1.5-rc.1 → `Promise<SessionPersistenceSnapshot[]>` → `h.header.cwd`
+*/
+async function sessionPersistencePaths(ctx) {
+	const out = [];
+	try {
+		const sp = hostService(ctx, "sessionPersistence");
+		for (const h of await sp?.list?.() ?? []) if (typeof h?.header?.cwd === "string") out.push(h.header.cwd);
+	} catch {}
+	return out;
+}
+/** ③ **live 会话**（`sessions.list()` 的 cwd；`host/access.ts` 收口） */
+function liveSessionPaths(ctx) {
+	const out = [];
+	try {
+		for (const s of hostSessions(ctx)?.list?.() ?? []) {
+			const cwd = s?.header?.cwd;
+			if (typeof cwd === "string") out.push(cwd);
+		}
+	} catch {}
+	return out;
+}
+/**
+* 列出本机已知的 CCC 根（**L2 的唯一权威列举器**）。
+*
+* 三层来源**各自都跑、结果取并集**（来源顺序 `workspaceRegistry → sessionPersistence → live`，
+* 按 root 去重**保留首次出现**）。`defaultRoot` 若不在结果里则 unshift 到首位。
+*
+* ⚠️ **为什么是并集而不是短路**（C2 修正的核心，现状稿 §2.B E1 + §2.D 第 4 条）：
+* 旧实现是 `if (roots.length === 0)` 三层门控 ⇒ 只要工作区注册表里有**任意一条**，
+* 就永远不看 `sessionPersistence`/live；注册表里有一个 CCC 而另一 CCC 只存在于历史会话时，
+* **整个列表都不含后者**（"名单不全"）。并集修正它，且**不改**任何消费方的输入契约。
+*
+* @param ctx 插件上下文
+* @param opts.defaultRoot 默认根（不在列表 → 置首）；opts.withRoles 是否读 `skiff.roles`
+* @returns 按上述顺序去重的 CCC 条目（无任何来源 → 空数组 + 可选默认根）
+*/
+async function listCccs(ctx, opts = {}) {
+	const c = makeCollector();
+	for (const path of workspaceRegistryPaths(ctx)) c.push(path);
+	for (const path of await sessionPersistencePaths(ctx)) c.push(path);
+	for (const path of liveSessionPaths(ctx)) c.push(path);
+	const defaultRoot = opts.defaultRoot;
+	if (typeof defaultRoot === "string" && defaultRoot !== "" && !c.roots.includes(defaultRoot)) c.roots.unshift(defaultRoot);
+	let rolesOf = null;
+	if (opts.withRoles === true) {
+		const { readSkiffRoles } = await import("./skiff-role-CEHL5cek.js").then((n) => n.u);
+		rolesOf = (root) => [...readSkiffRoles(root).keys()];
+	}
+	return c.roots.map((root) => ({
+		root,
+		name: basename(root) || root,
+		roles: rolesOf ? rolesOf(root) : []
+	}));
+}
+//#endregion
+export { ccc_roots_exports as a, cccRootForExec as i, agentCwdFor as n, listCccs as o, cccRootForCwd as r, NO_CCC_FROM_AGENT_CWD as t };

package/lib/ccc-roots.d.ts

@@ -0,0 +1,105 @@
+/**
+ * ccc-roots.ts — CCC 根解析的**唯一判断层**（L1 单根解析 + L2 全量枚举）
+ *
+ * 为什么存在（C2「CCC 发现面归一」，S142 2026-09-15 Q5 裁决）：
+ * 「这个会话/路径属于哪个 CCC 根」（L1）与「本机有哪些 CCC」（L2）这两层判断此前被
+ * 独立实现在 ~19 处，且互有分歧（同一进程内三个面可指向不同 CCC；"live CCC 列表"有三份
+ * 不同答案；三层发现是**短路**而非合并 ⇒ 名单不全）。本模块把这两层**收成一个出口**：
+ * 调用方只问本模块，不再各写各的上溯 + 兜底。
+ *
+ * 分层（唯一真相源边界，**不要**把下层搬进本模块）：
+ *  - **L0 原语** `findSerenityRoot(cwd)`（`ccc.ts:16`）——**仍是唯一** L0 实现，本模块从它 import。
+ *  - **L1 单根解析** —— 本模块：{@link agentCwdFor}（agent/exec → cwd）与
+ *    {@link cccRootForCwd}/{@link cccRootForExec}（cwd → 根）。
+ *  - **L2 全量枚举** —— 本模块：{@link listCccs}。
+ *  - **L3 CCC 名解析** `readCccName`（`ccc.ts`）——不在本模块，也不与 `skills-discovery` 的
+ *    第二份实现合并（那是另一条开放项）。
+ *
+ * 不新增持久状态（Q5 裁决：**不新增"本机 CCC 名单"**、不扫盘、不写路径假设）——
+ * 枚举只读 **DSH 已有的三个来源**。
+ */
+import type { Context } from 'cordis';
+/**
+ * 工具/缝里"取会话工作目录"的那段形状的最小模型。
+ * 多数工具只带 `agent`（`exec.agent.session.header.cwd`）；少数缝把 agent 本身传进来。
+ */
+export interface ExecOrAgent {
+    agent?: {
+        session?: {
+            header?: {
+                cwd?: string;
+            };
+        };
+    };
+    session?: {
+        header?: {
+            cwd?: string;
+        };
+    };
+}
+/**
+ * 取调用方的工作目录（**语义逐字保留**自原先散落 10 份的工具内副本）：
+ * `exec.agent?.session?.header?.cwd ?? process.cwd()`。
+ *
+ * ⚠️ 无 `exec.agent` 时回落进程 cwd —— "用服务启动目录冒充会话目录"是**既有语义**，
+ * 不是本模块的选择（改它会动到 9 个工具的根解析行为）。已知副作用与规避见
+ * `tools/handyman.ts` 的「调用形态检查前移」补偿（`?? process.cwd()` 会把真因
+ * "exec.agent 不存在"盖成 `No CCC found`）。
+ */
+export declare function agentCwdFor(execOrAgent: ExecOrAgent): string;
+/**
+ * cwd → CCC 根（L0 原语的唯一调用形态；`ccc.ts` 之外不要再各写一遍）。
+ * @param cwd 起始路径（目录或文件；文件会靠 `dirname` 上溯）
+ * @returns CCC 根绝对路径；不在任何 CCC 内 → `null`
+ */
+export declare function cccRootForCwd(cwd: string): string | null;
+/**
+ * 工具/缝入口的根解析（L1 标准形态）：`agentCwdFor(...)` 再上溯。
+ * @returns CCC 根；解析不到 → `null`（**不**回落假根——"回落进程 cwd 当根"是 `rebuild.ts`
+ *   独有的另一条语义，见该处注释）
+ */
+export declare function cccRootForExec(execOrAgent: ExecOrAgent): string | null;
+/**
+ * 工具根解析失败时抛出的**统一**错误文案。
+ * 9 个工具原先各写一份字面量（内容完全相同）；抽成常量以保单一真相源，
+ * **文案逐字不变**（外在行为不变）。
+ */
+export declare const NO_CCC_FROM_AGENT_CWD = "No CCC found: no .serenity file from agent cwd";
+/** 候选 CCC 条目（调试页 CCC 切换器 / 微信桥 / ACP 问答页 / `/serenity/cccs` 共用数据形状） */
+export interface CccEntry {
+    /** CCC 根（绝对路径） */
+    root: string;
+    /** 目录名（展示用） */
+    name: string;
+    /**
+     * 该 CCC 的 skiff 角色名列表。
+     * ⚠️ **仅 `withRoles: true` 时非空**；缺省 `false` ⇒ 恒为 `[]` 且**不读任何
+     * `serenity.json`**（唤醒调度器每 tick 都要枚举，不该为角色付 IO；见 listCccs 说明）。
+     */
+    roles: string[];
+}
+export interface ListCccsOptions {
+    /**
+     * 默认根：不在结果里时 **unshift 到首位**（既有语义，逐字保留）。
+     * 传 `undefined`/`''` 表示没有默认根。
+     */
+    defaultRoot?: string;
+    /** 是否实时读取各 CCC 的 `skiff.roles`（缺省 false）。 */
+    withRoles?: boolean;
+}
+/**
+ * 列出本机已知的 CCC 根（**L2 的唯一权威列举器**）。
+ *
+ * 三层来源**各自都跑、结果取并集**（来源顺序 `workspaceRegistry → sessionPersistence → live`，
+ * 按 root 去重**保留首次出现**）。`defaultRoot` 若不在结果里则 unshift 到首位。
+ *
+ * ⚠️ **为什么是并集而不是短路**（C2 修正的核心，现状稿 §2.B E1 + §2.D 第 4 条）：
+ * 旧实现是 `if (roots.length === 0)` 三层门控 ⇒ 只要工作区注册表里有**任意一条**，
+ * 就永远不看 `sessionPersistence`/live；注册表里有一个 CCC 而另一 CCC 只存在于历史会话时，
+ * **整个列表都不含后者**（"名单不全"）。并集修正它，且**不改**任何消费方的输入契约。
+ *
+ * @param ctx 插件上下文
+ * @param opts.defaultRoot 默认根（不在列表 → 置首）；opts.withRoles 是否读 `skiff.roles`
+ * @returns 按上述顺序去重的 CCC 条目（无任何来源 → 空数组 + 可选默认根）
+ */
+export declare function listCccs(ctx: Context, opts?: ListCccsOptions): Promise<CccEntry[]>;

package/lib/ccc.d.ts

@@ -9,7 +9,7 @@
  */
 export declare function findSerenityRoot(cwd: string): string | null;
 export declare function findGitRoot(cwd: string): string | null;
-export type PathClass = 'inside' | 'outside' | 'same';
+type PathClass = 'inside' | 'outside' | 'same';
 /**
  * 前缀判定：abs 是否位于 rootAbs 之内。
  * caseInsensitive（Windows 盘符/路径大小写不敏感）由调用方按平台传入；
@@ -31,7 +31,7 @@ export declare function resolveInside(root: string, p: string): string;
  * @returns CCC 名；无标记/读失败/全注释空行 → null
  */
 export declare function readCccName(root: string): string | null;
-export interface SerenityConfig {
+interface SerenityConfig {
     /** handyman（杂工）配置：模型白名单（v1.24.0 取代 loop） */
     handyman?: {
         /** 可用模型白名单（provider/model 列表）——handyman 只能使用其中模型（用户拍板：CCC 配置控制） */
@@ -268,8 +268,6 @@ export declare const DEFAULT_SERENITY_CONFIG_PATHS: string[];
  * 写出的 BOM（\uFEFF）会让 JSON.parse 抛错（配置静默变空）或 frontmatter 检测失败（技能被丢弃）。
  */
 export declare function readUtf8(path: string): string;
-/** 测试辅助：清空"已告警"记忆（生产零调用） */
-export declare function __resetBrokenConfigWarningsForTest(): void;
 /**
  * 读取 CCC 配置（第一个存在且可解析的候选路径）。
  *
@@ -310,6 +308,5 @@ export interface BlacklistRule {
 export declare function readBlacklist(root: string, paths?: string[]): BlacklistRule[];
 /** 匹配黑名单规则；命中返回条目，未命中返回 null。前缀匹配 / regex: 前缀（对齐 osp）。Windows：规则反斜杠归一化为正斜杠与 rel 对齐 */
 export declare function matchBlacklist(relPath: string, rules: BlacklistRule[]): BlacklistRule | null;
-/** 写类工具名（safe-mode 下禁止） */
-export declare const WRITE_TOOLS: Set<string>;
 export declare function isWriteTool(toolName: string): boolean;
+export {};

package/lib/client.js

@@ -3844,7 +3844,7 @@ Instruction-following style:
 		*    （用户：配置处需能获取 key 和地址——管理员复制分享给使用者）。
 		*
 		* 数据通道（plugin 全局）：
-		*  - GET /serenity/cccs       候选容器（node half discoverCccs）
+		*  - GET /serenity/cccs       候选容器（node half listCccs）
 		*  - GET /serenity/public-ask key + 地址（x-serenity-ui 头）
 		*  - PUT /serenity/config     publicAsk.allowed 白名单保存（accounts-api saveConfig）
 		*/
@@ -4118,7 +4118,7 @@ Instruction-following style:
 		* WeixinBridgeEditor.tsx — 「微信桥」配置区块（F4c-3，v1.27.0 实验性）
 		*
 		* **CCC 级配置**（S142 用户拍板：dsh 一个进程含多个 CCC，每个 CCC 独立对接微信桥）：
-		* - 顶部 **CCC 选择器**（数据源 /serenity/cccs——discoverCccs 复用）——显式选择配置目标，
+		* - 顶部 **CCC 选择器**（数据源 /serenity/cccs——listCccs 复用）——显式选择配置目标，
 		*   不隐式依赖"当前活跃会话"（WebUI 顶层全局，微信桥是配置写入必须显式）
 		* - 选中 CCC 后：总开关 / 账号列表（扫码绑定）/ 路由表（user → role）
 		* - 扫码绑定：POST login-start → qrcode-generator 生成二维码 SVG（复用 v1.24.6 TOTP 同款机制）