@shgroup/dsh-serenity-hooks 1.31.4 → 1.31.8

package/README.md

@@ -3,7 +3,7 @@
 > **一句话**：装上这个插件，你在电脑上给 AI 划一块自己的工作区（就是一个普通目录），
 > AI 在里面干活时就有了**记忆、纪律、工具和边界**——中途换模型、重启电脑、第二天再来，都能接着干。
 >
-> 适用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（下称 DSH）0.1.2-rc.1 及以上。
+> 适用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（下称 DSH）0.1.5-rc.1 及以上。
 > 想了解背后的想法（为什么叫"认知容器"），看 [docs/cognitive-container-theory.md](https://github.com/tellmewhattodo/dsh-serenity-plugin/blob/master/docs/cognitive-container-theory.md)；本文只讲**能干什么、怎么用**。
 
 **几个词先说明白**（后面都用这几个词，不再解释）：
@@ -32,7 +32,7 @@
 
 ## 2. 快速开始（2 分钟）
 
-前置：Node ≥ 20（或 bun）、DSH 0.1.2-rc.1 及以上。
+前置：Node ≥ 20（或 bun）、DSH 0.1.5-rc.1 及以上。
 
 ```bash
 # 1. 装插件（自动加入 DSH 的 web profile）
@@ -111,6 +111,27 @@ dsh plugin --profile web add link:$(pwd)/hooks/dsh-serenity-hooks
 
 > 默认只监听 127.0.0.1 的入口，要暴露到公网由你自己决定（隧道 / 反代 / 端口映射都行），插件不绑定任何特定做法。
 
+### 3.4 省你一步：用 opencode 的模型
+
+想在 DSH 里用 opencode 的网关（`opencode.ai/zen`），本来除了配路由还得手抄一串请求头——
+这些头是 opencode 用来做**会话亲和路由**的，少写一个 `x-opencode-session`，`/zen/go` 面就直接 400 拒绝。
+**插件装好就自动配**，这一步你不用管：
+
+| 你的情况 | 插件做什么 |
+|---|---|
+| 已经配了 opencode 路由，但缺头 | 只补缺的那几个；**你手写过的值一律不动**（头名不分大小写，`X-Title` 和 `x-title` 一样算数） |
+| 一个 opencode 路由都没有，但环境里有 `OPENCODE_API_KEY` | 自动建 `opencode-go` 路由并带全头（没有 key 的人不受影响，不会平白多出一组模型） |
+
+- **只管"会话族"的头**：`x-opencode-session` / `X-Session-ID` / `x-opencode-client` / `x-opencode-project`。
+  前两个名字是**同一个值的两个别名**——你写了其中一个，就用**你的值**补上另一个，不会出现两个互相打架的会话 id
+- **不冒充 opencode 官方客户端**：`X-Title` / `HTTP-Referer` 这类"身份头"只在免费档的滥用判别里起作用，
+  插件不注入（替你骗额度不是我们该做的事，付费面本来也不需要它们）；`User-Agent` 是 DSH 的保留名，想注也注不了
+- **会话标识是固定的**（`dsh-serenity`）：DSH 的请求头在路由解析时一次算好，只能给静态值。
+  好处是同一台机器的请求稳定落同一个上游（对缓存友好）；代价是做不到"按会话分区"
+- **配的是你自己的文件**：写入 DSH 的 settings（`llm-pi-ai.providers.<路由>.headers`），随时可改可删。
+  不想要这个自动配置，就把本插件的 `opencodeProvider.autoConfigure` 关掉（关掉后一切回到手抄）
+- **密钥不碰**：插件只补路由和头，`OPENCODE_API_KEY` 放环境变量即可
+
 ---
 
 ## 4. 一个工作区长什么样
@@ -270,7 +291,7 @@ DSH 一个进程可以同时带多个工作区，每个工作区各自对接自
 
 | 层 | 位置 | 放什么 |
 |---|---|---|
-| DSH 原生设置 | DSH 的 settings.yaml | 简单开关：网关 / 重建 / 会话命名、重建阈值、子角色开关与调试端口、ACP 与问答页开关、**巡航总开关（默认关）** |
+| DSH 原生设置 | DSH 的 settings.yaml | 简单开关：网关 / 重建 / 会话命名、重建阈值、子角色开关与调试端口、ACP 与问答页开关、**巡航总开关（默认关）**、**opencode 路由自动配置（默认开）** |
 | 插件全局文件 | `~/.dsh/serenity-hooks.json`（权限 0600） | 网关账号（scrypt + TOTP）、监听地址与端口、工作区白名单、cookie 安全开关、问答页 key |
 | 工作区配置 | `.opencode/serenity.json` | 助手模型白名单、日志阈值、安全模式黑名单、子角色、**巡航（间隔/会话/焦点/窗口）**、**微信（账号/路由/开关）** |
 | 工作区凭据 | `localstore.json` | 密钥与本地偏好；微信机器人 token 也在这一层 |
@@ -296,7 +317,7 @@ AI 一次能"记住"的内容有上限。满了不用你手动开新会话：
 
 ```bash
 pnpm typecheck          # 类型检查（node + 浏览器端两套）
-pnpm test               # 全量测试（当前 75 个文件 / 1110 个用例）
+pnpm test               # 全量测试（当前 78 个文件 / 1169 个用例）
 pnpm build              # 打包（lib/index.js + client.js）
 ```
 
@@ -360,4 +381,4 @@ pnpm build              # 打包（lib/index.js + client.js）
 
 MIT（见 [LICENSE](https://github.com/tellmewhattodo/dsh-serenity-plugin/blob/master/LICENSE)）
 
-> **版本**：v1.31.1 ｜ **前置**：DSH 0.1.2-rc.1+ / Node ≥ 20 或 bun ｜ **测试**：75 个文件 / 1110 个用例
+> **版本**：v1.31.7 ｜ **前置**：DSH 0.1.5-rc.1+ / Node ≥ 20 或 bun ｜ **测试**：78 个文件 / 1169 个用例

package/dsh.plugin.json

@@ -1,10 +1,10 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.31.4",
+  "version": "1.31.8",
   "main": "lib/index.js",
-  "description": "宁静号 ACC harness（Native Cordis 插件）：给 DSH 装一个「AI 工作区」——11 个工具（container_fs/logbook/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/autopilot-trajectory/im-bridge）+ 机械约束（安全模式/工作区围墙/密钥守卫）+ 工作日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/自主巡航。适配 DSH 0.1.2-rc.1（deepseek-ai/deepseek-harness）。",
+  "description": "宁静号 ACC harness（Native Cordis 插件）：给 DSH 装一个「AI 工作区」——11 个工具（container_fs/logbook/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/autopilot-trajectory/im-bridge）+ 机械约束（安全模式/工作区围墙/密钥守卫）+ 工作日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/自主巡航。适配 DSH 0.1.5-rc.1（deepseek-ai/deepseek-harness）。",
   "engines": {
-    "dsh": ">=0.1.2-rc.1"
+    "dsh": ">=0.1.5-rc.1"
   },
   "contributes": {
     "tools": [

package/lib/client.js

@@ -419,15 +419,21 @@ window.__ModuleLoader__.load({
 		}
 		/**
 		* 取 rail 图片的浏览器 File。
-		* conversation.draftImages 是 root singleton 的公开方法（读 controller 的 draftAttachments Map，
+		*
+		* v1.31.6 适配 0.1.5-rc.1：`IConversation.draftImages(ids)` **已改名**
+		* `resolveDraftAttachments(ids)`（同语义同返回：ordered draft descriptors）。
+		* 这是**静默突破**——调用点用结构化断言隔离宿主（零宿主 import 策略），
+		* 类型检查看不见旧名消失，只会运行时 `=== undefined` → 静默返回 `[]`（兜底悄悄失效）。
+		*
+		* conversation 是 root singleton 的公开方法（读 controller 的 draftAttachments Map，
 		* 与调用 ctx 的作用域无关）——直接 ctx.get('conversation')。
-		* ⚠️ 必须作为方法调用（conversation.draftImages(ids)）：解构取出再调会丢失 this
-		* （draftImages 内部读 this.draftAttachments → "Cannot read properties of undefined"）。
+		* ⚠️ 必须作为方法调用（conversation.resolveDraftAttachments(ids)）：解构取出再调会丢失 this
+		* （内部读 this 的 draft registry → "Cannot read properties of undefined"）。
 		*/
 		async function getDraftFiles(ctx, _sessionId, ids) {
 			const conversation = ctx.get?.("conversation");
-			if (conversation?.draftImages === void 0) return [];
-			return (conversation.draftImages(ids) ?? []).map((a) => a.file);
+			if (conversation?.resolveDraftAttachments === void 0) return [];
+			return (conversation.resolveDraftAttachments(ids) ?? []).map((a) => a.file);
 		}
 		/**
 		* 纯文本重发（绕过图片门禁——不含 image part，模型永不触发 MODEL_DOES_NOT_SUPPORT_IMAGES）。
@@ -455,22 +461,22 @@ window.__ModuleLoader__.load({
 			const inputActions = props.inputActions;
 			const handlingRef = (0, react.useRef)(false);
 			const promptError = session?.promptError?.error;
-			const imageIds = input?.imageIds ?? [];
+			const attachmentIds = input?.attachmentIds ?? [];
 			(0, react.useEffect)(() => {
 				if (handlingRef.current || !isImageFallbackTrigger(promptError?.code, promptError?.details?.reason)) return;
-				if (imageIds.length === 0) return;
+				if (attachmentIds.length === 0) return;
 				handlingRef.current = true;
 				(async () => {
 					try {
-						const files = await getDraftFiles(String(sessionId), imageIds);
+						const files = await getDraftFiles(String(sessionId), attachmentIds);
 						if (files.length === 0) throw new Error("no draft image files");
 						const saved = [];
 						for (const file of files) saved.push(await uploadImage(file, String(sessionId)));
 						const note = imageNoteTemplate(saved);
 						const draft = input?.draft ?? "";
 						const text = draft === "" ? note : `${draft}\n${note}`;
-						if (inputActions?.removeImage !== void 0 && inputActions.setDraft !== void 0 && inputActions.submit !== void 0) {
-							for (const id of imageIds) inputActions.removeImage(String(id));
+						if (inputActions?.removeAttachment !== void 0 && inputActions.setDraft !== void 0 && inputActions.submit !== void 0) {
+							for (const id of attachmentIds) inputActions.removeAttachment(id);
 							inputActions.setDraft(text);
 							inputActions.submit();
 						} else await resendText(String(sessionId), text);
@@ -482,7 +488,7 @@ window.__ModuleLoader__.load({
 				})();
 			}, [
 				promptError,
-				imageIds,
+				attachmentIds,
 				sessionId,
 				uploadImage,
 				getDraftFiles,

package/lib/host/contract.d.ts

@@ -38,7 +38,7 @@ export interface HostServiceContract {
     /** 缺失是否致命 */
     required: boolean;
 }
-/** dsp 依赖的宿主服务与成员（对照 AI_LAB/dsh-harness-public @ 0.1.2-rc.1 逐一核对） */
+/** dsp 依赖的宿主服务与成员（对照 `_tmp/host-0.1.5-rc.1/`（`dsh-develop host-fetch` 产物）逐一核对） */
 export declare const HOST_SERVICES: readonly HostServiceContract[];
 export interface HostEventContract {
     name: HostEventName;
@@ -55,14 +55,14 @@ export interface HostEventContract {
  * 在名字写错/宿主改名时**编译失败**（v1.30.7，review F-04/F-05）。
  * 该 import 为 type-only，编译期擦除，不产生运行时依赖。
  */
-export declare const HOST_EVENT_NAMES: readonly ["agent/session-start", "agent/pre-step", "agent/turn-stopping", "agent/status", "agent/inbox/inserted", "session/event", "session/created", "tools/pre-execute", "tools/post-execute", "system-prompt/assemble"];
+export declare const HOST_EVENT_NAMES: readonly ["agent/session-start", "agent/pre-step", "agent/turn-stopping", "agent/status", "agent/inbox/inserted", "agent/disposed", "session/event", "session/created", "session/disposed", "settings/updated", "tools/pre-execute", "tools/post-execute", "system-prompt/assemble"];
 export type HostEventName = (typeof HOST_EVENT_NAMES)[number];
 /**
  * dsp 订阅的宿主事件清单（与 HOST_EVENT_NAMES 同源；impact/site 供 health 报告与文档）。
  */
 export declare const HOST_EVENTS: readonly HostEventContract[];
 /** dsp 被验证过的宿主版本范围（与 package.json peerDependencies 同源，单一真相源） */
-export declare const REQUIRED_HOST_RANGE = "^0.1.2-rc.1";
+export declare const REQUIRED_HOST_RANGE = "^0.1.5-rc.1";
 export interface HostContractIssue {
     id: string;
     kind: 'service' | 'member' | 'version';
@@ -80,8 +80,13 @@ export interface HostContractReport {
 /** 最小 semver 比较（无依赖）：返回 -1 / 0 / 1；解析失败返回 null */
 export declare function compareSemver(a: string, b: string): number | null;
 /**
- * 宿主版本是否落在 dsp 被验证的范围（`^0.1.2-rc.1`）。
+ * 宿主版本是否落在 dsp 被验证的范围（`REQUIRED_HOST_RANGE`）。
  * 无版本信息 → 视为未知（ok=false，detail 说明），不猜测。
+ *
+ * floor/ceiling **从 `REQUIRED_HOST_RANGE` 派生**（v1.31.6，0.1.5-rc.1 适配轮）：
+ * 此前 floor 是独立硬编码字面量——改 `REQUIRED_HOST_RANGE` 而忘改 floor 会造出
+ * "常量说 0.1.5、判定用 0.1.2" 的双真相源。ceiling 无法从 caret 语义机械派生（手写比较器
+ * 不实现 semver 的 caret 规则），故保留显式常量并在此声明其含义。
  */
 export declare function checkHostVersion(version: string | null): {
     ok: boolean;

package/lib/host/type-contract.d.ts

@@ -0,0 +1,44 @@
+/**
+ * host/type-contract.ts — 宿主**类型**契约（编译期反证层，v1.31.8，S142 全量 review 产物）
+ *
+ * ## 为什么存在（R↓）
+ *
+ * dsp 用**结构化断言**隔离宿主（手写 interface + `as` / `as never`，零宿主运行时 import），
+ * 换来 peer-only 打包与"不随宿主版本耦合"的灵活度；代价是**类型检查对宿主漂移失明**：
+ * 宿主把成员改名、改返回形状，dsp 侧拿不到任何编译期信号，只能靠**人读宿主源码**发现。
+ *
+ * 历史已三次静默失效：
+ *  - `Session.events` → `snapshotEvents()`（v1.28.0）
+ *  - `conversation.draftImages()` → `resolveDraftAttachments()`（v1.31.6）
+ *  - `sessionPersistence.list()` 返回形状 `SessionHeader[]`（`h.cwd`）→
+ *    `SessionPersistenceSnapshot[]`（`h.header.cwd`）（v1.31.6）
+ * 后两条是升级 0.1.5-rc.1 时**逐文件人读**才挖出来的——不是机制发现的。
+ *
+ * ## 既有三道防线的盲区（2026-09-10 全量 review 结论）
+ *
+ * | 防线 | 覆盖 | 盲区 |
+ * |------|------|------|
+ * | `contract.ts` 的 `satisfies keyof Events` | 事件**名** | payload 形状 |
+ * | `probeHostContract`（运行期） | 服务**名** + 成员**存在性** | 成员**签名**、**返回形状** |
+ * | `tests/**` | —— | **完全不参与类型检查**（tsconfig `include: ["src"]`）→ 写在测试里的"真实宿主类型断言"从未生效 |
+ *
+ * ## 本模块补的那一格：用宿主真实类型反证 dsp 的形状假设
+ *
+ * 机制：
+ *  ① `import type {} from '<宿主包>'` 把该包的 `declare module '@deepseek-ai/cordis'` 声明增强
+ *     拉进 program（**空类型 import，编译期擦除 → 零运行时依赖**，peer-only 打包不受影响；
+ *     与 `src/client/index.ts` 引 `dsh-client-ui-session` 同款手法）
+ *  ② 每条 `Expect<Extends<宿主真相, dsp 假设>>` 是一道**编译期闸门**：宿主改名/改形状 →
+ *     `dsh-develop typecheck` 当场红，升级当天报警，而不是等线上静默失效
+ *  ③ 换宿主版本时 `dsh-develop typecheck-host <ver>` 会对**解包的新宿主**跑同一批断言
+ *
+ * ## 维护纪律（强制）
+ *
+ * **新增一处对宿主的形状依赖 → 在此加一条对应闸门**（断言旁注明 dsp 消费点与后果）。
+ * 断言只表达 dsp **真正依赖**的那部分（不求与宿主全等）→ 宿主新增字段/放宽类型不会误报，
+ * 只有"dsp 依赖的东西没了或变了"才红。
+ *
+ * 注：本文件**没有任何运行时语句**，编译产物只有 `export {}`，不影响包体行为。
+ */
+/** 哨兵：确保本模块不是空文件被 tree-shake 掉（无运行时副作用，值为类型） */
+export type HostTypeContractSatisfied = true;

package/lib/index.d.ts

@@ -64,6 +64,14 @@ export interface Config {
     webFetch?: {
         enabled?: boolean;
     };
+    /**
+     * v1.31.7 opencode 路由自动配置（plugin 全局；S142 用户"省得用户配"）：
+     * 补 `llm-pi-ai.providers.<opencode 路由>.headers` 的路由头；环境有 OPENCODE_API_KEY 时建路由。
+     * 缺省开（`!== false` 判定）；关闭后一切回到"用户手抄"。
+     */
+    opencodeProvider?: {
+        autoConfigure?: boolean;
+    };
 }
 export declare const Config: z<Config>;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { a as findSerenityRoot, c as matchBlacklist, d as readCccName$2, f as readHandymanConfig, i as findGitRoot, l as pathInside, m as resolveInside, n as SAFE_MODE_MARKER, o as isSafeModeOn, r as classifyPath, s as loadSerenityConfig, t as DEFAULT_SERENITY_CONFIG_PATHS, u as readBlacklist } from "./ccc-DAsSHsub.js";
 import { a as readSkiffRoles, d as systemPromptSource, i as isSkiffSessionId, l as roleToolWhitelist, o as resolveRoleSystemPrompt } from "./skiff-role-BYvNnwv1.js";
-import { A as skiffRoleFor, C as listActiveHandymen, D as splitModel, E as requireWhitelistedModel, O as writeFailedStatus, S as handymanProgressPaths, T as readProgress, _ as unregisterSkiffSession, a as startSkiffDebugServer, b as HANDYMAN_GUIDE, c as askSkiff, d as ensureWorkspacePromptSection, f as getSkiffAgent, g as skiffTrajectoryEnabled, h as skiffSessionSnapshot, k as writeProgress, l as createSkiffAgent, m as skiffSessionInfo, n as jscSafeJsonText, o as stopSkiffDebugServer, p as skiffMsmGate, r as renderSkiffMarkdown, s as stripThink, t as discoverCccs, u as ensureSkiffSession, v as workspaceTrajectoryLine, w as newStopToken, x as buildRoundPrompt, y as waitAgentIdle } from "./skiff-debug-B445WY23.js";
-import { c as hostWebServer, i as hostSessions, n as hostInjected, o as hostSubagents, r as hostService, s as hostWeb, t as hostAgents } from "./access-fiehjxV6.js";
+import { A as skiffRoleFor, C as listActiveHandymen, D as splitModel, E as requireWhitelistedModel, O as writeFailedStatus, S as handymanProgressPaths, T as readProgress, _ as unregisterSkiffSession, a as startSkiffDebugServer, b as HANDYMAN_GUIDE, c as askSkiff, d as ensureWorkspacePromptSection, f as getSkiffAgent, g as skiffTrajectoryEnabled, h as skiffSessionSnapshot, k as writeProgress, l as createSkiffAgent, m as skiffSessionInfo, n as jscSafeJsonText, o as stopSkiffDebugServer, p as skiffMsmGate, r as renderSkiffMarkdown, s as stripThink, t as discoverCccs, u as ensureSkiffSession, v as workspaceTrajectoryLine, w as newStopToken, x as buildRoundPrompt, y as waitAgentIdle } from "./skiff-debug-w2c3UqQk.js";
+import { a as hostSettings, c as hostWebServer, i as hostSessions, n as hostInjected, o as hostSubagents, r as hostService, s as hostWeb, t as hostAgents } from "./access-fiehjxV6.js";
 import { a as readWeixinCredential, c as weixinInboundDir, d as LOCALSTORE_SCOPES, f as checkLocalstoreGitCompliance, g as runLocalStore, h as readStore, i as matchWeixinRoute, l as weixinSessionIdFor, m as readGitTrack, n as extractWeixinText, o as readWeixinSettings, p as localstorePath, r as hasVoiceItem, s as sanitizeFileName$1, t as extractWeixinMedia } from "./weixin-route-wWk4AIwV.js";
 import { C as useSession, S as summarize, _ as resolveSessionByTitle, a as archiveSessions, b as setActiveSessionInfo, c as createSession, d as getActiveSessionInfo, f as healthCheck, g as readActiveSessionMd, h as qaCheck, i as SESSION_ACTIONS, l as extractSessionMdPathFromText, m as parseSessionContextFromEvents, n as readLastBound, o as clearActiveSessionInfo, p as listSessions, r as DEFAULT_SESSION_SCOPE, s as closeSession, t as appendBound, u as findSession, v as sessionEvents, x as showSession, y as sessionsRoot } from "./session-bound-BpTayaIS.js";
 import { n as registerSettingsSection, t as readSimpleSettings } from "./settings-section-01rTVq6v.js";
@@ -1091,7 +1091,7 @@ function setSafeMode(root, on) {
 }
 //#endregion
 //#region src/host/contract.ts
-/** dsp 依赖的宿主服务与成员（对照 AI_LAB/dsh-harness-public @ 0.1.2-rc.1 逐一核对） */
+/** dsp 依赖的宿主服务与成员（对照 `_tmp/host-0.1.5-rc.1/`（`dsh-develop host-fetch` 产物）逐一核对） */
 const HOST_SERVICES = [
 	{
 		id: "tools",
@@ -1160,11 +1160,21 @@ const HOST_SERVICES = [
 		id: "settings",
 		name: "settings",
 		access: "injected",
-		members: [{
-			name: "installSection",
-			kind: "function"
-		}],
-		impact: "设置面板不安装 → 所有开关静默 no-op",
+		members: [
+			{
+				name: "installSection",
+				kind: "function"
+			},
+			{
+				name: "get",
+				kind: "function"
+			},
+			{
+				name: "update",
+				kind: "function"
+			}
+		],
+		impact: "设置面板不安装 → 所有开关静默 no-op；opencode 路由自动配置失效",
 		required: true
 	},
 	{
@@ -1292,7 +1302,11 @@ const HOST_SERVICES = [
 	}
 ];
 /** dsp 被验证过的宿主版本范围（与 package.json peerDependencies 同源，单一真相源） */
-const REQUIRED_HOST_RANGE = "^0.1.2-rc.1";
+const REQUIRED_HOST_RANGE = "^0.1.5-rc.1";
+/** 范围 floor：剥掉 caret/比较前缀（`^0.1.5-rc.1` → `0.1.5-rc.1`），供 {@link checkHostVersion} 使用 */
+const REQUIRED_HOST_FLOOR = REQUIRED_HOST_RANGE.replace(/^[\^~>=<\s]+/, "");
+/** 范围 ceiling：`^0.1.x` 的上界 = `<0.2.0`（显式常量，见 {@link checkHostVersion} 注释） */
+const REQUIRED_HOST_CEILING = "0.2.0";
 /** 最小 semver 比较（无依赖）：返回 -1 / 0 / 1；解析失败返回 null */
 function compareSemver(a, b) {
 	const parse = (v) => {
@@ -1317,16 +1331,21 @@ function compareSemver(a, b) {
 	return ra < rb ? -1 : 1;
 }
 /**
-* 宿主版本是否落在 dsp 被验证的范围（`^0.1.2-rc.1`）。
+* 宿主版本是否落在 dsp 被验证的范围（`REQUIRED_HOST_RANGE`）。
 * 无版本信息 → 视为未知（ok=false，detail 说明），不猜测。
+*
+* floor/ceiling **从 `REQUIRED_HOST_RANGE` 派生**（v1.31.6，0.1.5-rc.1 适配轮）：
+* 此前 floor 是独立硬编码字面量——改 `REQUIRED_HOST_RANGE` 而忘改 floor 会造出
+* "常量说 0.1.5、判定用 0.1.2" 的双真相源。ceiling 无法从 caret 语义机械派生（手写比较器
+* 不实现 semver 的 caret 规则），故保留显式常量并在此声明其含义。
 */
 function checkHostVersion(version) {
 	if (version === null) return {
 		ok: false,
 		detail: `host version unknown (required ${REQUIRED_HOST_RANGE})`
 	};
-	const floor = compareSemver(version, "0.1.2-rc.1");
-	const ceiling = compareSemver(version, "0.2.0");
+	const floor = compareSemver(version, REQUIRED_HOST_FLOOR);
+	const ceiling = compareSemver(version, REQUIRED_HOST_CEILING);
 	if (floor === null || ceiling === null) return {
 		ok: false,
 		detail: `host version "${version}" not parseable (required ${REQUIRED_HOST_RANGE})`
@@ -3065,13 +3084,15 @@ function subagentOutputText(output) {
 *  - 模型经 `agentOptions` 注入（spawn 后端能力位 `agentOptions: true`），因此**不依赖**
 *    宿主未放开的 `subagent-model-selection` 设置；
 *  - 不循环、不写进度文件、不做完成码校验——"一次调用一次结果"。
+*
+* 前置条件：`opts.parent` 必须是发起 agent（由调用方 `execute` 在解析 CCC 之前校验；
+* 本函数不再重复检查——单一真相源）。
 */
 async function runForegroundJob(ctx, opts) {
 	const { task, label, model, models, parent, signal } = opts;
 	requireWhitelistedModel(model, models);
 	const subagents = hostSubagents(ctx);
 	if (!subagents?.start) throw new Error("handyman foreground: host subagents service unavailable — neither ctx.subagents nor ctx.get(\"subagents\") yielded a start() function. Check `dashboard health` (host-contract section, service \"subagents\"); mode=\"background\" does not need this service and still works.");
-	if (!parent) throw new Error("handyman foreground: requires a calling agent (exec.agent was undefined)");
 	const { provider, model: modelName } = splitModel(model);
 	const run = await subagents.start("spawn", {
 		...label === void 0 ? {} : { label },
@@ -3278,6 +3299,7 @@ function createHandymanTool(ctx) {
 		},
 		async execute(args, exec) {
 			if (args.guide) return { guide: HANDYMAN_GUIDE };
+			if ((args.mode ?? "foreground") === "foreground" && !exec.agent) throw new Error("handyman foreground: requires a calling agent (exec.agent was undefined)");
 			const root = findSerenityRoot(agentCwd$6(exec));
 			if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 			const hc = readHandymanConfig(root, DEFAULT_SERENITY_CONFIG_PATHS);
@@ -6999,7 +7021,7 @@ function registerStatusApi(ctx, opts = {}) {
 					workspace: url.searchParams.get("workspace") ?? void 0
 				});
 				const root = findSerenityRoot(workspace) ?? "";
-				const { discoverCccs } = await import("./skiff-debug-B445WY23.js").then((n) => n.i);
+				const { discoverCccs } = await import("./skiff-debug-w2c3UqQk.js").then((n) => n.i);
 				sendJson$2(res, 200, { cccs: await discoverCccs(ctx, root) });
 			} catch (err) {
 				sendJson$2(res, 400, { error: err.message ?? String(err) });
@@ -8628,8 +8650,8 @@ function performRebuild(session, pending, meter) {
 	}, {
 		surfaceOp: {
 			op: "replace",
-			start: nodes[0],
-			end: nodes[nodes.length - 1]
+			startSeq: nodes[0],
+			endSeq: nodes[nodes.length - 1]
 		},
 		sourceEventSeqs: nodes
 	});
@@ -10604,7 +10626,7 @@ function matchCcc(input, candidates) {
 }
 /** 组装候选列表（discoverCccs 投影 + `.serenity` 名；动态 import 保持本模块静态依赖轻量） */
 async function collectCandidates(ctx) {
-	const { discoverCccs } = await import("./skiff-debug-B445WY23.js").then((n) => n.i);
+	const { discoverCccs } = await import("./skiff-debug-w2c3UqQk.js").then((n) => n.i);
 	const entries = await discoverCccs(ctx, process.cwd());
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
@@ -11077,6 +11099,270 @@ async function registerWebFetchProvider(ctx) {
 	}
 }
 //#endregion
+//#region src/opencode-provider.ts
+/** `llm-pi-ai` 的 settings 命名空间（宿主 `dsh-llm-pi-ai` 的 `NS`） */
+const LLM_PI_AI_NAMESPACE = "llm-pi-ai";
+/**
+* 本机安装的会话标识（静态；见文件头"已知局限"）。
+*
+* 为什么用常量而不是随机/uuid：`headers` 只在路由解析时求值一次，随机值等于每次进程启动换一个
+* 亲和键（缓存永远不命中），反而劣化。常量让"同一安装 → 同一亲和键"成立。
+*/
+const OPENCODE_SESSION_ID = "dsh-serenity";
+/** 视为 opencode 路由的路由名（pi-ai 目录里的两个 id） */
+const OPENCODE_ROUTE_IDS = ["opencode", "opencode-go"];
+/** 自动配置时创建的路由名（pi-ai 目录的 Go 面；用户选的是付费 `/zen/go`） */
+const OPENCODE_ROUTE_TO_CREATE = "opencode-go";
+/** 触发 L2 建路由的环境变量名（与 pi-ai 目录 provider 的 `envApiKeyAuth` 声明一致） */
+const OPENCODE_API_KEY_ENV = "OPENCODE_API_KEY";
+/**
+* 注入的头（"会话族"）——每次调用返回新对象（调用方会放进 patch，共享可变对象是坑）。
+*
+* 注：同一个值同时给 `x-opencode-session`（pi 与第三方代理用的名字）与 `X-Session-ID`
+* （OpenCode 自家客户端用的名字）——两处证据各自出现，都发才不会漏。
+* 头名大小写不敏感是 HTTP 语义，但**名字不同就是两个头**，故都要。
+*/
+function opencodeRouteHeaders() {
+	return {
+		"x-opencode-session": OPENCODE_SESSION_ID,
+		"X-Session-ID": OPENCODE_SESSION_ID,
+		"x-opencode-client": "dsh",
+		"x-opencode-project": "global"
+	};
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 该路由是否指向 opencode（按路由名，或按 baseURL 主机名——用户可能把路由改名） */
+function isOpencodeRoute(route, profile) {
+	if (OPENCODE_ROUTE_IDS.includes(route)) return true;
+	const baseURL = profile.baseURL;
+	if (typeof baseURL !== "string" || baseURL === "") return false;
+	try {
+		const host = new URL(baseURL).hostname.toLowerCase();
+		return host === "opencode.ai" || host.endsWith(".opencode.ai");
+	} catch {
+		return false;
+	}
+}
+/** HTTP 头名按大小写不敏感查找（HTTP 字段名语义；用户写 `x-title` 与 `X-Title` 等价） */
+function hasHeaderCaseInsensitive(headers, name) {
+	return headerValue(headers, name) !== void 0;
+}
+/** 按大小写不敏感取头值（取不到 → undefined） */
+function headerValue(headers, name) {
+	const want = name.toLowerCase();
+	for (const [k, v] of Object.entries(headers)) if (k.toLowerCase() === want && typeof v === "string") return v;
+}
+/**
+* 会话标识的两个头名是**同一逻辑值**的两个别名（两处独立证据各用一个：
+* Go 面 400 点名 `x-opencode-session`，OpenCode 自家客户端用 `X-Session-ID`）。
+*
+* 因此判定顺序是"先定值、再补名"：用户任写其一 → 用**他的值**补齐另一个；
+* 两个都没写 → 用本插件常量。**绝不出现两个互相矛盾的 id**（那会让上游按哪个路由都说不清）。
+*/
+function sessionIdentityValue(headers) {
+	return headerValue(headers, "x-opencode-session") ?? headerValue(headers, "X-Session-ID") ?? "dsh-serenity";
+}
+/**
+* 计算自动配置计划（**纯函数**：不读文件、不碰 ctx——便于穷举测试）。
+*
+* 判据顺序（R↓）：
+*   ① 命名空间未注册（`resolved === undefined`）→ idle，调用方负责重试（llm-pi-ai 可能后装载）
+*   ② 逐个已有 opencode 路由：只补缺失的键（用户的显式值一律不动）
+*   ③ 一个 opencode 路由都没有 + 环境有 `OPENCODE_API_KEY` → 建路由（带全头）
+*   ④ 其余 → idle `no-route`（含"没有 key 就不建路由"——不给不用 opencode 的人平白加模型）
+*/
+function planOpencodeAutoConfig(input) {
+	const actions = [];
+	if (input.resolved === void 0) return {
+		patch: {},
+		actions: [{
+			kind: "idle",
+			reason: "namespace-unregistered"
+		}]
+	};
+	const providers = isPlainObject(input.resolved) && isPlainObject(input.resolved.providers) ? input.resolved.providers : {};
+	const patchProviders = {};
+	let sawOpencodeRoute = false;
+	for (const [route, rawProfile] of Object.entries(providers)) {
+		const profile = isPlainObject(rawProfile) ? rawProfile : {};
+		if (!isOpencodeRoute(route, profile)) continue;
+		sawOpencodeRoute = true;
+		const existing = isPlainObject(profile.headers) ? profile.headers : {};
+		const sessionId = sessionIdentityValue(existing);
+		const wanted = {
+			...opencodeRouteHeaders(),
+			"x-opencode-session": sessionId,
+			"X-Session-ID": sessionId
+		};
+		const missing = {};
+		for (const [name, value] of Object.entries(wanted)) if (!hasHeaderCaseInsensitive(existing, name)) missing[name] = value;
+		const keys = Object.keys(missing);
+		if (keys.length === 0) {
+			actions.push({
+				kind: "skip-route",
+				route,
+				reason: "headers-complete"
+			});
+			continue;
+		}
+		patchProviders[route] = { headers: missing };
+		actions.push({
+			kind: "fill-headers",
+			route,
+			keys
+		});
+	}
+	if (!sawOpencodeRoute) {
+		const key = input.env[OPENCODE_API_KEY_ENV];
+		if (typeof key !== "string" || key === "") actions.push({
+			kind: "idle",
+			reason: "no-route"
+		});
+		else {
+			patchProviders[OPENCODE_ROUTE_TO_CREATE] = { headers: opencodeRouteHeaders() };
+			actions.push({
+				kind: "create-route",
+				route: OPENCODE_ROUTE_TO_CREATE
+			});
+		}
+	}
+	return {
+		patch: Object.keys(patchProviders).length > 0 ? { providers: patchProviders } : {},
+		actions
+	};
+}
+/** 动作 → 单行人读日志（无秘密） */
+function describeOpencodeAction(action) {
+	switch (action.kind) {
+		case "fill-headers": return `补齐 ${action.route} 的路由头（${action.keys.length} 项：${action.keys.join(", ")}）`;
+		case "create-route": return `创建 ${action.route} 路由（检测到 ${OPENCODE_API_KEY_ENV}）+ 路由头`;
+		case "skip-route": return `${action.route} 路由头已齐备（跳过）`;
+		case "idle": return `无需动作（${action.reason}）`;
+	}
+}
+/**
+* 执行一次自动配置。返回是否**写入了**（调用方据此决定是否停止重试）。
+*
+* 失败语义（F-08/F-07 纪律）：**任何失败都不抛给宿主**——apply 抛错 = 整个 dsh 启动失败。
+* 一律 try/catch + 响亮告警（用户能看到"没生效 + 为什么"），最坏情况退回"用户手抄头"。
+*/
+async function applyOpencodeAutoConfigOnce(ctx, env) {
+	const settings = hostSettings(ctx);
+	if (settings?.get === void 0 || settings.update === void 0) {
+		console.warn("[serenity-hooks] opencode 路由自动配置跳过：settings 服务不可用（未能读取/写入 llm-pi-ai 命名空间）");
+		return {
+			wrote: false,
+			registered: false
+		};
+	}
+	let resolved;
+	try {
+		resolved = settings.get.call(settings, LLM_PI_AI_NAMESPACE);
+	} catch (error) {
+		console.warn(`[serenity-hooks] opencode 路由自动配置跳过：读取 ${LLM_PI_AI_NAMESPACE} 失败: ${String(error?.message ?? error)}`);
+		return {
+			wrote: false,
+			registered: false
+		};
+	}
+	const plan = planOpencodeAutoConfig({
+		resolved,
+		env: env ?? process.env
+	});
+	if (Object.keys(plan.patch).length === 0) return {
+		wrote: false,
+		registered: resolved !== void 0
+	};
+	try {
+		await settings.update.call(settings, LLM_PI_AI_NAMESPACE, plan.patch);
+	} catch (error) {
+		console.warn(`[serenity-hooks] ✗ opencode 路由自动配置写入被拒: ${String(error?.message ?? error)}（可手动写入 llm-pi-ai.providers.<route>.headers；见本插件 README）`);
+		return {
+			wrote: false,
+			registered: true
+		};
+	}
+	for (const action of plan.actions) {
+		if (action.kind === "idle" || action.kind === "skip-route") continue;
+		console.log(`[serenity-hooks] ✓ opencode 路由：${describeOpencodeAction(action)}`);
+	}
+	return {
+		wrote: true,
+		registered: true
+	};
+}
+/**
+* 命名空间注册重试间隔（毫秒；累计 ~72s）。
+*
+* 为什么要重试：`llm-pi-ai` 只在**它自己的** `ctx.inject(['settings'])` 回调里注册命名空间，
+* 与本插件 apply **无先后保证**（两者都依赖 settings 服务）。首次读取拿到 undefined 是常态而非错误
+* （与 skiff 的 CCC root 重试同款问题、同款处置：v1.30.13 实证"只在 apply 时试一次 → 永不重试"）。
+*/
+const NAMESPACE_RETRY_DELAYS_MS = [
+	1e3,
+	3e3,
+	8e3,
+	2e4,
+	4e4
+];
+/**
+* 装配 opencode 路由自动配置。
+*
+* 触发面（三层，与 skiff 同款；R↓：单点触发在同装载竞态下必然漏）：
+*   ① apply 时立即试一次
+*   ② 命名空间尚未注册 → 退避重试（1s/3s/8s/20s/40s）
+*   ③ `settings/updated` → 再试（用户热改 settings.yaml 加路由时自愈；自身写入触发的复评是幂等空转）
+*
+* 不设"一次性完成"闸门：③ 必须能在之后继续生效（用户随时可能新增 opencode 路由）。
+*/
+function registerOpencodeAutoConfig(ctx) {
+	let settled = false;
+	let retryTimer = null;
+	let retries = 0;
+	const clearRetry = () => {
+		if (retryTimer !== null) {
+			clearTimeout(retryTimer);
+			retryTimer = null;
+		}
+	};
+	const scheduleRetry = () => {
+		if (retryTimer !== null || settled) return;
+		if (retries >= NAMESPACE_RETRY_DELAYS_MS.length) {
+			console.warn(`[serenity-hooks] opencode 路由自动配置放弃：重试 ${retries} 次仍等不到 ${LLM_PI_AI_NAMESPACE} 命名空间（未使用 pi-ai 适配器时正常；若要手配见 README）`);
+			settled = true;
+			return;
+		}
+		const delay = NAMESPACE_RETRY_DELAYS_MS[retries] ?? 0;
+		retryTimer = setTimeout(() => {
+			retryTimer = null;
+			retries += 1;
+			sync();
+		}, delay);
+		retryTimer.unref?.();
+	};
+	function sync() {
+		applyOpencodeAutoConfigOnce(ctx).then((result) => {
+			if (result.registered) {
+				settled = true;
+				clearRetry();
+			} else if (!settled) scheduleRetry();
+		}).catch((error) => {
+			console.warn(`[serenity-hooks] opencode 路由自动配置异常: ${String(error?.message ?? error)}`);
+			settled = true;
+			clearRetry();
+		});
+	}
+	try {
+		ctx.on?.call(ctx, "settings/updated", (ns) => {
+			if (ns === "llm-pi-ai") sync();
+		});
+	} catch {}
+	sync();
+	registerDisposer(ctx, "opencode provider auto-config retry timer", clearRetry);
+}
+//#endregion
 //#region src/im-weixin.ts
 /**
 * im-weixin.ts — 微信通道实现（`im-bridge` 的通道之一，v1.31.0）
@@ -11356,7 +11642,8 @@ const Config = z.object({
 		enabled: z.boolean().default(false),
 		httpPort: z.number().min(1024).max(65535).default(3100)
 	}),
-	webFetch: z.object({ enabled: z.boolean().default(true) })
+	webFetch: z.object({ enabled: z.boolean().default(true) }),
+	opencodeProvider: z.object({ autoConfigure: z.boolean().default(true) })
 });
 function apply(ctx, config) {
 	try {
@@ -11407,6 +11694,7 @@ function apply(ctx, config) {
 	registerWeixinOutputGuard(ctx);
 	registerLifecycle(ctx);
 	if (config.webFetch?.enabled !== false) registerWebFetchProvider(ctx);
+	if (config.opencodeProvider?.autoConfigure !== false) registerOpencodeAutoConfig(ctx);
 }
 /**
 * F4 Skiff 调试服务装配：启停 = 人工（设置面板 Skiff 区块开关，settings 持久化）。

package/lib/opencode-provider.d.ts

@@ -0,0 +1,134 @@
+/**
+ * opencode-provider.ts — opencode zen / go 路由的自动配置（v1.31.7，S142 用户需求）
+ *
+ * ## 为什么存在（R↓）
+ *
+ * opencode 的 zen / go 面按**请求头**做会话亲和路由：缺 `x-opencode-session` 时
+ * `/zen/go` 直接 400 `Request is missing x-opencode-session and cannot be routed efficiently`。
+ * 而 DSH 用的 **pi-ai 库本身不发这些头**（`@earendil-works/pi-ai@0.85.1` 全库 `x-opencode` 零命中；
+ * pi 的 CLI 是**应用层**自己在 `packages/coding-agent/src/core/sdk.ts` 加的）。
+ * → 用户要在 DSH 里用 opencode，除了配路由还得手抄一串头。本模块把这步自动化。
+ *
+ * ## 两层（S142 用户 2026-09-10 拍板：两层默认都开）
+ *
+ * - **L1 补头**：路由已存在（路由名 ∈ opencode/opencode-go，或 baseURL 命中 opencode.ai）且缺头
+ *   → 只补**缺失的键**。已存在的键（用户手写的）**一律不覆盖**——头名按 HTTP 语义**大小写不敏感**比较。
+ * - **L2 建路由**：环境里有 `OPENCODE_API_KEY` 且没有任何 opencode 路由 → 建 `opencode-go` 并带全头。
+ *   “有 key”就是用户意图的最强证据 → 不需要的人（没 key）零影响（不会平白多出一组模型）。
+ *
+ * ## 注入通道（唯一可用且是官方的）
+ *
+ * `ctx.settings.update('llm-pi-ai', patch)` —— `dsh-settings` 的官方写入面：
+ *   ① 深合并（`mergeLayers` 逐层递归，数组整体替换）→ 不会冲掉用户别的路由
+ *   ② **先校验后落盘**（pi-ai 注册时给的 `validate`）→ 坏补丁拒绝且不持久化
+ *   ③ `dsh-settings-file` 的 `writable` 恒 true → 写入用户 settings 文档（0600，用户可读可删）
+ *
+ * 被否掉的备选：① 本插件 `cordis.patch.yml` 直接改 `llm-pi-ai` 的 config —— 宿主 patch 语义是
+ * **整体替换 config（非深合并）**，会冲掉部署方在该条目上配的其它 provider；且无法按条件启用。
+ * ② 让用户手抄 —— 本次要消灭的正是这一步。
+ *
+ * ## 只注入"会话族"，**不注入身份族**（诚实边界，用户选了付费 /zen/go）
+ *
+ * - 注入：`x-opencode-session` / `X-Session-ID`（同一个稳定的本机安装标识）、
+ *   `x-opencode-client: dsh`、`x-opencode-project: global`
+ *   （证据：Trae 的 Go 面代理注入的正是这一族，且该项目 README 明列 "dsh 亲测有效"）
+ * - **不注入** `X-Title: opencode` / `HTTP-Referer: https://opencode.ai/` —— 那是**冒充 OpenCode 客户端**，
+ *   只在免费档的**滥用判别**中起作用（hermes #106495 实证）。冒充他人客户端去绕限额不是本插件该做的事。
+ * - **不注入** `User-Agent` —— 它是 `@deepseek-ai/dsh-llm` 的 attribution 保留名
+ *   （`APP_IDENTITY` 无配置缝），宿主层面就不可覆盖。
+ * - **不注入** `x-opencode-request` —— 它的语义是"会话内递增"（`msg_1`/`msg_2`…），
+ *   本模块只能给**静态**值，写个假的递增 id 比不写更糟。
+ *
+ * ## 已知局限（必须显式，不粉饰）
+ *
+ * DSH 的 provider `headers` 在路由解析时**一次性求值**（无 per-request 模板缝；pi-ai 支持
+ * `transformHeaders` 但 DSH 适配器未用）→ 会话标识只能是**静态**的。代价 = 跨会话共用同一亲和键：
+ * 对提示词缓存是利好（同机器请求恒定落同一上游 provider），对"按会话分区"是语义偏差。
+ * pi issue #4847 的报告者也点出该 workaround 的固有缺陷（"bound to the installation"）。
+ */
+import type { Context } from 'cordis';
+/** `llm-pi-ai` 的 settings 命名空间（宿主 `dsh-llm-pi-ai` 的 `NS`） */
+export declare const LLM_PI_AI_NAMESPACE = "llm-pi-ai";
+/**
+ * 本机安装的会话标识（静态；见文件头"已知局限"）。
+ *
+ * 为什么用常量而不是随机/uuid：`headers` 只在路由解析时求值一次，随机值等于每次进程启动换一个
+ * 亲和键（缓存永远不命中），反而劣化。常量让"同一安装 → 同一亲和键"成立。
+ */
+export declare const OPENCODE_SESSION_ID = "dsh-serenity";
+/** 视为 opencode 路由的路由名（pi-ai 目录里的两个 id） */
+export declare const OPENCODE_ROUTE_IDS: readonly string[];
+/** 自动配置时创建的路由名（pi-ai 目录的 Go 面；用户选的是付费 `/zen/go`） */
+export declare const OPENCODE_ROUTE_TO_CREATE = "opencode-go";
+/** 触发 L2 建路由的环境变量名（与 pi-ai 目录 provider 的 `envApiKeyAuth` 声明一致） */
+export declare const OPENCODE_API_KEY_ENV = "OPENCODE_API_KEY";
+/**
+ * 注入的头（"会话族"）——每次调用返回新对象（调用方会放进 patch，共享可变对象是坑）。
+ *
+ * 注：同一个值同时给 `x-opencode-session`（pi 与第三方代理用的名字）与 `X-Session-ID`
+ * （OpenCode 自家客户端用的名字）——两处证据各自出现，都发才不会漏。
+ * 头名大小写不敏感是 HTTP 语义，但**名字不同就是两个头**，故都要。
+ */
+export declare function opencodeRouteHeaders(): Record<string, string>;
+export interface OpencodeAutoConfigInput {
+    /** `llm-pi-ai` 命名空间**解析后**的值（`settings.get` 结果；undefined = 命名空间未注册） */
+    resolved: unknown;
+    /** 进程环境（注入以便测试） */
+    env: Readonly<Record<string, string | undefined>>;
+}
+/** 一条动作记录（日志 + 测试断言共用；不返回"秘密"、只返回做了什么） */
+export type OpencodeAutoConfigAction = {
+    kind: 'fill-headers';
+    route: string;
+    keys: readonly string[];
+} | {
+    kind: 'create-route';
+    route: string;
+} | {
+    kind: 'skip-route';
+    route: string;
+    reason: 'headers-complete';
+} | {
+    kind: 'idle';
+    reason: 'namespace-unregistered' | 'no-route';
+};
+export interface OpencodeAutoConfigPlan {
+    /** 传给 `settings.update` 的补丁；空对象 = 无事可做（**不写**，避免无谓触发 settings/updated） */
+    patch: Record<string, unknown>;
+    actions: readonly OpencodeAutoConfigAction[];
+}
+/** 该路由是否指向 opencode（按路由名，或按 baseURL 主机名——用户可能把路由改名） */
+export declare function isOpencodeRoute(route: string, profile: Record<string, unknown>): boolean;
+/**
+ * 计算自动配置计划（**纯函数**：不读文件、不碰 ctx——便于穷举测试）。
+ *
+ * 判据顺序（R↓）：
+ *   ① 命名空间未注册（`resolved === undefined`）→ idle，调用方负责重试（llm-pi-ai 可能后装载）
+ *   ② 逐个已有 opencode 路由：只补缺失的键（用户的显式值一律不动）
+ *   ③ 一个 opencode 路由都没有 + 环境有 `OPENCODE_API_KEY` → 建路由（带全头）
+ *   ④ 其余 → idle `no-route`（含"没有 key 就不建路由"——不给不用 opencode 的人平白加模型）
+ */
+export declare function planOpencodeAutoConfig(input: OpencodeAutoConfigInput): OpencodeAutoConfigPlan;
+/** 动作 → 单行人读日志（无秘密） */
+export declare function describeOpencodeAction(action: OpencodeAutoConfigAction): string;
+/**
+ * 执行一次自动配置。返回是否**写入了**（调用方据此决定是否停止重试）。
+ *
+ * 失败语义（F-08/F-07 纪律）：**任何失败都不抛给宿主**——apply 抛错 = 整个 dsh 启动失败。
+ * 一律 try/catch + 响亮告警（用户能看到"没生效 + 为什么"），最坏情况退回"用户手抄头"。
+ */
+export declare function applyOpencodeAutoConfigOnce(ctx: Context, env?: Readonly<Record<string, string | undefined>>): Promise<{
+    wrote: boolean;
+    registered: boolean;
+}>;
+/**
+ * 装配 opencode 路由自动配置。
+ *
+ * 触发面（三层，与 skiff 同款；R↓：单点触发在同装载竞态下必然漏）：
+ *   ① apply 时立即试一次
+ *   ② 命名空间尚未注册 → 退避重试（1s/3s/8s/20s/40s）
+ *   ③ `settings/updated` → 再试（用户热改 settings.yaml 加路由时自愈；自身写入触发的复评是幂等空转）
+ *
+ * 不设"一次性完成"闸门：③ 必须能在之后继续生效（用户随时可能新增 opencode 路由）。
+ */
+export declare function registerOpencodeAutoConfig(ctx: Context): void;

package/lib/{skiff-debug-B445WY23.js → skiff-debug-w2c3UqQk.js}

@@ -2445,7 +2445,7 @@ async function discoverCccs(ctx, defaultRoot) {
 	} catch {}
 	if (roots.length === 0) try {
 		const sp = hostService(ctx, "sessionPersistence");
-		for (const h of await sp?.list?.() ?? []) pushRoot(h?.cwd);
+		for (const h of await sp?.list?.() ?? []) pushRoot(h?.header?.cwd);
 	} catch {}
 	if (roots.length === 0) try {
 		const sessions = hostSessions(ctx);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shgroup/dsh-serenity-hooks",
-  "version": "1.31.4",
-  "description": "宁静号 ACC harness（Native Cordis 插件）——给 DeepSeek Harness 装一个「AI 工作区」：11 个工具（container_fs/logbook/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/autopilot-trajectory/im-bridge）+ 机械约束（安全模式/工作区围墙/密钥守卫/对外输出守卫）+ 工作日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/自主巡航。适配 DSH 0.1.2-rc.1。",
+  "version": "1.31.8",
+  "description": "宁静号 ACC harness（Native Cordis 插件）——给 DeepSeek Harness 装一个「AI 工作区」：11 个工具（container_fs/logbook/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/autopilot-trajectory/im-bridge）+ 机械约束（安全模式/工作区围墙/密钥守卫/对外输出守卫）+ 工作日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/自主巡航。适配 DSH 0.1.5-rc.1。",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -52,24 +52,24 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-compaction": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-title": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-shell": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-shell-env": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-skill": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-web": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-web-fetch-http": "^0.1.2-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "cordis": "^4.0.0-rc.7",
-    "@deepseek-ai/cordis": "^4.0.0-rc.7"
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-compaction": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-title": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell-env": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-web": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-web-fetch-http": "^0.1.5-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "cordis": "^4.0.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-host-webserver": {