@shgroup/dsh-serenity-hooks 1.47.1 → 1.47.3

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.47.1",
+  "version": "1.47.3",
   "main": "lib/index.js",
   "description": "宁静号 ACC harness（Native Cordis 插件）：给 DSH 装一个「AI 工作区」——11 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/im-bridge/acc-diag；后两个按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫）+ 轨迹日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.5-rc.2（deepseek-ai/deepseek-harness）。",
   "engines": {

package/lib/{access-fiehjxV6.js → access-CNccNtgf.js}

@@ -72,5 +72,8 @@ function hostWeb(ctx) {
 function hostSubagents(ctx) {
 	return hostInjected(ctx, "subagents");
 }
+function hostLlm(ctx) {
+	return hostInjected(ctx, "llm");
+}
 //#endregion
-export { hostSettings as a, hostWebServer as c, hostSessions as i, hostInjected as n, hostSubagents as o, hostService as r, hostWeb as s, hostAgents as t };
+export { hostSessions as a, hostWeb as c, hostService as i, hostWebServer as l, hostInjected as n, hostSettings as o, hostLlm as r, hostSubagents as s, hostAgents as t };

package/lib/{ccc-roots-FxWXuZPw.js → ccc-roots-NpTWo0-c.js}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { i as hostSessions, r as hostService } from "./access-fiehjxV6.js";
+import { a as hostSessions, i as hostService } from "./access-CNccNtgf.js";
 import { a as findSerenityRoot } from "./ccc-DG4Oc7I1.js";
 import { basename } from "node:path";
 //#region src/ccc-roots.ts

package/lib/handyman-ops.d.ts

@@ -39,6 +39,34 @@ export declare function splitModel(model: string): {
 };
 /** 校验模型在白名单内；不在 → 抛错（用户拍板：只能使用 CCC 配置的模型） */
 export declare function requireWhitelistedModel(model: string, models: string[]): void;
+/**
+ * providerAvailabilityError — 判定「**本机有没有该 provider 的 adapter**」，并产出**可执行**的错误文本。
+ * 返回 `null` = 全部可用（调用方照常继续）。
+ *
+ * 🔴 为什么需要它（S142 2026-09-25，owner 在 **Mac** 上实测）：`handyman` 的模型白名单写在
+ *   **CCC**（`.opencode/serenity.json`，**随 git 走**），而 provider adapter 由**每台机器的宿主**
+ *   注册（profile 配置 / settings 命名空间）⇒ 同一份白名单在一台机器可用、在另一台必失败。
+ *   实测症状：宿主抛 `no adapter registered for provider "<p>"`（`dsh-llm`，code `NO_ADAPTER`），
+ *   而**前台路径的 `diagnostic` 是空的** ⇒ 调用方（LLM）拿到 `stopReason:"error"` 却**不知道为什么**，
+ *   也就无法修正自己的配置 —— 本条把「沉默的失败」变成「可执行的错误」。
+ *
+ * 数据来源（宿主 `LlmRuntime`）：`listProviders()` = **有 adapter 的路由**；
+ * `listConfigurableProviders()` = **已声明但未必激活**的路由（含激活用的 settings 命名空间）。
+ *
+ * 判据边界：`model` 串里**没有 `/`** 时取不到 provider（沿用 agent 默认路由）⇒ **不判定**（跳过）。
+ */
+export declare function providerAvailabilityError(models: readonly string[], facts: {
+    registered: readonly {
+        id: string;
+        name?: string;
+    }[];
+    declared?: readonly {
+        provider: string;
+        displayName?: string;
+        settingsNs?: string;
+    }[];
+    configPath?: string;
+}): string | null;
 /** 轮次 prompt（对齐老 loop 结构：回顾进度 → 自由工作 → 汇报；S134 EAP 化：固定详尽） */
 export declare function buildRoundPrompt(opts: {
     root: string;
@@ -54,7 +82,7 @@ export declare function buildRoundPrompt(opts: {
  * 使用 handyman 前必须先加载 eap 设计方案；并行策略（jobs 编排）；提示词规范（详尽固定 EAP）；
  * 阅读/文字编写类 handyman 内部也加载 eap。
  */
-export declare const HANDYMAN_GUIDE = "# handyman \u2014 Scale-Up Usage Guide (guide)\n\n## Two modes (v1.31.3; default = foreground)\n| | foreground (default) | background |\n|---|---|---|\n| What | one serial child agent runs the task ONCE and returns its final text | loop-validated worker: hard while-loop + random completion code |\n| Use when | you need exactly one result back now (per-case testers, single conversions) | long/unattended work needing anti-early-finish, resumability, or parallel jobs |\n| Loop / validation | none | stop-token is the ONLY completion condition; round cap (default 100); auto-restart (\u2264100) |\n| Progress file | none | AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes) |\n| Parallel jobs | no (call once per task) | yes (jobs=[...], handyman.maxParallel default 10) |\n| Mechanism | host delegation service ctx.subagents.start(\"spawn\") + agentOptions | ctx.agents.create + internal while-loop |\n| Model source | CCC handyman.models whitelist (same for both) | same |\n\n## \u26A0\uFE0F Before using: load eap and design the plan\nBefore calling handyman, load eap (acc-eap skill) and design the \"scale-up handyman plan\" based on the EAP framework.\n\n### 1. Task decomposition (E\u2191 Explicit)\n- Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria\n- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel (background mode)\n\n### 2. Prompt design (handyman's task parameter)\n- task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria\n- foreground mode: the child does NOT share your conversation \u2014 restate everything it needs in task\n- Anti-example \"handle this file\" \u2014 ambiguous; good example \"read <path>, extract all rows of the\u300C\u5173\u952E\u51B3\u7B56\u300Dtable,\n  output a JSON array (fields id/conclusion/evidence), do not modify the original file\"\n- Reading/curating or text-writing work (extracting from files, summarizing, writing docs, generating text, etc.):\n  the handyman-internal agent is also required to load eap and organize output per the EAP standard\n\n### 3. Model whitelist (CCC-configured, mandatory)\n- handyman only uses models listed in .opencode/serenity.json \"handyman.models\" \u2014 never arbitrary models\n- The CCC is expected to point this whitelist at LOW-COST models: handyman is the bulk-execution channel\n- background mode: recursive subagents inside a worker inherit the worker's model automatically (DSH native)\n- foreground mode: the child is started through the host delegation service with the resolved model\n\n### 4. Parallel strategy (background mode only)\n- Independent subtasks can run in parallel via handyman(mode=\"background\", jobs=[...]): each job gets its own label + task + stop token + progress file\n- Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label\n  (AGENT_SESSIONS/handyman-<label>.json) \u2014 same label resumes, different labels never interfere\n- Parallel cap: handyman.maxParallel (default 10 \u2014 cheap models are cheap)\n- Aggregation: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)\n- For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead\n\n## Completion criteria\n- foreground: the child's run settles; done=true only when stopReason=\"completed\" (otherwise read diagnostic)\n- background (osp loop standard): the only completion condition = the worker echoes this round's random verification\n  code (stop token); dialogue round cap (default 100, osp fail-safe, forced stop beyond the cap, resumable);\n  automatic restart on abnormal agent stop (\u2264100 restarts, anti-infinite-loop)\n\n## Waiting UI\n- The WebUI session-header Serenity detail card shows running background handymen's progress\n  (label / round / last response), one line per parallel job, ~3s refresh (foreground mode writes no progress)\n";
+export declare const HANDYMAN_GUIDE = "# handyman \u2014 Scale-Up Usage Guide (guide)\n\n## Two modes (v1.31.3; default = foreground)\n| | foreground (default) | background |\n|---|---|---|\n| What | one serial child agent runs the task ONCE and returns its final text | loop-validated worker: hard while-loop + random completion code |\n| Use when | you need exactly one result back now (per-case testers, single conversions) | long/unattended work needing anti-early-finish, resumability, or parallel jobs |\n| Loop / validation | none | stop-token is the ONLY completion condition; round cap (default 100); auto-restart (\u2264100) |\n| Progress file | none | AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes) |\n| Parallel jobs | no (call once per task) | yes (jobs=[...], handyman.maxParallel default 10) |\n| Mechanism | host delegation service ctx.subagents.start(\"spawn\") + agentOptions | ctx.agents.create + internal while-loop |\n| Model source | CCC handyman.models whitelist (same for both) | same |\n\n## \u26A0\uFE0F Before using: load eap and design the plan\nBefore calling handyman, load eap (acc-eap skill) and design the \"scale-up handyman plan\" based on the EAP framework.\n\n### 1. Task decomposition (E\u2191 Explicit)\n- Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria\n- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel (background mode)\n\n### 2. Prompt design (handyman's task parameter)\n- task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria\n- foreground mode: the child does NOT share your conversation \u2014 restate everything it needs in task\n- Anti-example \"handle this file\" \u2014 ambiguous; good example \"read <path>, extract all rows of the\u300C\u5173\u952E\u51B3\u7B56\u300Dtable,\n  output a JSON array (fields id/conclusion/evidence), do not modify the original file\"\n- Reading/curating or text-writing work (extracting from files, summarizing, writing docs, generating text, etc.):\n  the handyman-internal agent is also required to load eap and organize output per the EAP standard\n\n### 3. Model whitelist (CCC-configured, mandatory)\n- handyman only uses models listed in .opencode/serenity.json \"handyman.models\" \u2014 never arbitrary models\n- The CCC is expected to point this whitelist at LOW-COST models: handyman is the bulk-execution channel\n- background mode: recursive subagents inside a worker inherit the worker's model automatically (DSH native)\n- foreground mode: the child is started through the host delegation service with the resolved model\n\n### 3b. \uD83D\uDD34 Provider availability (per-machine \u2014 the whitelist is NOT enough)\n- The whitelist lives in the **CCC** (\"serenity.json\", it **travels with the repository**), but provider\n  **adapters are registered per machine by the host** (profile config / settings namespace). An entry that\n  works on one machine can fail on another with: \"no adapter registered for provider <p>\".\n- Before spawning, handyman verifies the provider of the resolved model against the adapters registered\n  **on this machine**; if it is missing it reports the requested model, where it is configured, **the\n  providers that ARE available here**, any declared-but-dormant route (with its settings namespace), and the\n  exact fix \u2014 foreground puts this in \"diagnostic\", background throws it.\n- \u21D2 If you see \"has no adapter registered on this machine\": edit \".opencode/serenity.json\" \"handyman.models\"\n  (and \"handyman.defaultModel\") to a provider listed as available, or activate/register the provider on this\n  machine. **Do not retry the same call unchanged** \u2014 it fails identically.\n\n### 4. Parallel strategy (background mode only)\n- Independent subtasks can run in parallel via handyman(mode=\"background\", jobs=[...]): each job gets its own label + task + stop token + progress file\n- Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label\n  (AGENT_SESSIONS/handyman-<label>.json) \u2014 same label resumes, different labels never interfere\n- Parallel cap: handyman.maxParallel (default 10 \u2014 cheap models are cheap)\n- Aggregation: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)\n- For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead\n\n## Completion criteria\n- foreground: the child's run settles; done=true only when stopReason=\"completed\" (otherwise read diagnostic)\n- background (osp loop standard): the only completion condition = the worker echoes this round's random verification\n  code (stop token); dialogue round cap (default 100, osp fail-safe, forced stop beyond the cap, resumable);\n  automatic restart on abnormal agent stop (\u2264100 restarts, anti-infinite-loop)\n\n## Waiting UI\n- The WebUI session-header Serenity detail card shows running background handymen's progress\n  (label / round / last response), one line per parallel job, ~3s refresh (foreground mode writes no progress)\n";
 /** handyman 运行状态（进度文件摘要；WebUI 等待界面数据源） */
 interface HandymanRunInfo {
     label: string;

package/lib/host/access.d.ts

@@ -96,6 +96,27 @@ interface HostSubagents {
     start?: (name: string, request: unknown) => Promise<unknown>;
 }
 export declare function hostSubagents(ctx: unknown): HostSubagents | undefined;
+/**
+ * `ctx.llm`（`LlmRuntime`；v1.48：handyman 的 **provider 预检**取证面）。
+ *
+ * 形状对照宿主 rc.2（`@deepseek-ai/dsh-llm`）：
+ *   · `listProviders()` → `{ id, name }[]` —— **有 adapter** 的路由（"本机真能用"）
+ *   · `listConfigurableProviders()` → `{ provider, displayName, settingsNs, … }[]` ——
+ *     **已声明但未必激活**的路由（"可以激活"）
+ *
+ * 🔴 为什么走 `hostInjected` 而不是直接属性读：`llm` **不在** dsp 的 `inject` 列表内
+ *   （见 `src/index.ts` 的 `inject`）⇒ 真实 cordis 下直接属性读对未声明服务**会抛**
+ *   （`cannot get property "llm" without inject`），必须回落 `ctx.get`。
+ *
+ * 🔴 为什么**刻意不把 `llm` 加进 `inject`**：预检是**尽力而为**的增强，不是运行前提。
+ *   加进 `inject` 会让"没有 llm 服务的 profile"**整块不激活插件** —— 为了一条诊断信息
+ *   换来插件不上线，代价与收益倒挂。缺失一律 `undefined`，调用方**不得**因此抛错。
+ */
+interface HostLlm {
+    listProviders?: () => unknown;
+    listConfigurableProviders?: () => unknown;
+}
+export declare function hostLlm(ctx: unknown): HostLlm | undefined;
 /** 会话 cwd 列表（live 会话；形状不符时返回空数组而非抛错） */
 export declare function hostSessionCwds(ctx: unknown): string[];
 export {};

package/lib/index.d.ts

@@ -11,7 +11,7 @@
  *
  * 配置：进程级 Config（cordis.yml 提供）+ 运行时读取 CCC 的 .opencode/serenity.json（规范位置，.dsh 回退）。
  */
-import type { Context } from 'cordis';
+import type { Context, Volatile } from 'cordis';
 import z from '@deepseek-ai/schemastery';
 export declare const name = "dsh-serenity-hooks";
 /** 主动调用的服务；其余（agent 事件）随 harness 装配必然存在
@@ -83,25 +83,151 @@ export interface Config {
         enabled?: boolean;
     };
     /** F1 双端口网关总开关（面板层；部署层同义键 = `gateway.enabled`） */
-    gatewayEnabled?: boolean;
+    gatewayEnabled?: Volatile<boolean | undefined>;
     /** F2 超限重建总开关（面板层；部署层同义键 = `rebuild.enabled`） */
-    rebuildEnabled?: boolean;
+    rebuildEnabled?: Volatile<boolean | undefined>;
     /** F2 触发阈值（K token；面板层；部署层同义键 = `rebuild.thresholdK`） */
-    rebuildThresholdK?: number;
+    rebuildThresholdK?: Volatile<number | undefined>;
     /** F4 Skiff 调试服务总开关（面板层；部署层同义键 = `skiff.enabled`） */
-    skiffEnabled?: boolean;
+    skiffEnabled?: Volatile<boolean | undefined>;
     /** F4 Skiff 调试端口（面板层；部署层同义键 = `skiff.debugPort`） */
-    skiffDebugPort?: number;
+    skiffDebugPort?: Volatile<number | undefined>;
     /** F4c ACP HTTP 端点总开关（面板层；部署层同义键 = `acp.enabled`） */
-    acpEnabled?: boolean;
+    acpEnabled?: Volatile<boolean | undefined>;
     /** F4c ACP HTTP 端口（面板层；部署层同义键 = `acp.httpPort`） */
-    acpHttpPort?: number;
+    acpHttpPort?: Volatile<number | undefined>;
     /** F4d 建议问答页总开关（面板层；无部署层同义键） */
-    publicAskEnabled?: boolean;
+    publicAskEnabled?: Volatile<boolean | undefined>;
     /** CRO（轨迹自编程唤起）总闸（面板层；无部署层同义键；缺省开） */
-    croEnabled?: boolean;
+    croEnabled?: Volatile<boolean | undefined>;
     /** 无人值守代理回复总闸（面板层；无部署层同义键；缺省关） */
-    unattendedEnabled?: boolean;
+    unattendedEnabled?: Volatile<boolean | undefined>;
 }
-export declare const Config: z<Config>;
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    serenityConfigPaths: z<string[], string[], "defined">;
+    tools: z<boolean, boolean, "defined">;
+    guards: z<boolean, boolean, "defined">;
+    keeper: z<boolean, boolean, "defined">;
+    keeperThreshold: z<number, number, "defined">;
+    context: z<boolean, boolean, "defined">;
+    compactRetention: z<boolean, boolean, "defined">;
+    api: z<boolean, boolean, "defined">;
+    entrySkillMaxChars: z<number, number, "defined">;
+    env: z<boolean, boolean, "defined">;
+    opencodeSkills: z<boolean, boolean, "defined">;
+    gateway: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
+    rebuild: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        thresholdK: z<number, number, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        thresholdK: z<number, number, "defined">;
+    }>>, "plain">;
+    skiff: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        debugPort: z<number, number, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        debugPort: z<number, number, "defined">;
+    }>>, "plain">;
+    acp: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        httpPort: z<number, number, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        httpPort: z<number, number, "defined">;
+    }>>, "plain">;
+    webFetch: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
+    opencodeProvider: z<Schemastery.ObjectS<NoInfer<{
+        autoConfigure: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        autoConfigure: z<boolean, boolean, "defined">;
+    }>>, "plain">;
+    visionPatch: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
+    gatewayEnabled: z<boolean, boolean, "volatile">;
+    rebuildEnabled: z<boolean, boolean, "volatile">;
+    rebuildThresholdK: z<number, number, "volatile">;
+    skiffEnabled: z<boolean, boolean, "volatile">;
+    skiffDebugPort: z<number, number, "volatile">;
+    acpEnabled: z<boolean, boolean, "volatile">;
+    acpHttpPort: z<number, number, "volatile">;
+    publicAskEnabled: z<boolean, boolean, "volatile">;
+    croEnabled: z<boolean, boolean, "volatile">;
+    unattendedEnabled: z<boolean, boolean, "volatile">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    serenityConfigPaths: z<string[], string[], "defined">;
+    tools: z<boolean, boolean, "defined">;
+    guards: z<boolean, boolean, "defined">;
+    keeper: z<boolean, boolean, "defined">;
+    keeperThreshold: z<number, number, "defined">;
+    context: z<boolean, boolean, "defined">;
+    compactRetention: z<boolean, boolean, "defined">;
+    api: z<boolean, boolean, "defined">;
+    entrySkillMaxChars: z<number, number, "defined">;
+    env: z<boolean, boolean, "defined">;
+    opencodeSkills: z<boolean, boolean, "defined">;
+    gateway: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
+    rebuild: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        thresholdK: z<number, number, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        thresholdK: z<number, number, "defined">;
+    }>>, "plain">;
+    skiff: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        debugPort: z<number, number, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        debugPort: z<number, number, "defined">;
+    }>>, "plain">;
+    acp: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        httpPort: z<number, number, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        httpPort: z<number, number, "defined">;
+    }>>, "plain">;
+    webFetch: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
+    opencodeProvider: z<Schemastery.ObjectS<NoInfer<{
+        autoConfigure: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        autoConfigure: z<boolean, boolean, "defined">;
+    }>>, "plain">;
+    visionPatch: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
+    gatewayEnabled: z<boolean, boolean, "volatile">;
+    rebuildEnabled: z<boolean, boolean, "volatile">;
+    rebuildThresholdK: z<number, number, "volatile">;
+    skiffEnabled: z<boolean, boolean, "volatile">;
+    skiffDebugPort: z<number, number, "volatile">;
+    acpEnabled: z<boolean, boolean, "volatile">;
+    acpHttpPort: z<number, number, "volatile">;
+    publicAskEnabled: z<boolean, boolean, "volatile">;
+    croEnabled: z<boolean, boolean, "volatile">;
+    unattendedEnabled: z<boolean, boolean, "volatile">;
+}>>, "plain">;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -1,14 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.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 hostSessions, c as hostWeb, i as hostService, l as hostWebServer, n as hostInjected, o as hostSettings, r as hostLlm, s as hostSubagents, t as hostAgents } from "./access-CNccNtgf.js";
 import { a as findSerenityRoot, c as matchBlacklist, d as readCccName$1, f as readExclusiveTools, g as resolveInside, i as findGitRoot, l as pathInside, m as readTrajectorySkills, n as SAFE_MODE_MARKER, o as isSafeModeOn, p as readHandymanConfig, r as classifyPath, s as loadSerenityConfig, t as DEFAULT_SERENITY_CONFIG_PATHS, u as readBlacklist } from "./ccc-DG4Oc7I1.js";
-import { i as cccRootForExec, n as agentCwdFor, o as listCccs, r as cccRootForCwd, t as NO_CCC_FROM_AGENT_CWD } from "./ccc-roots-FxWXuZPw.js";
-import { C as showSession, D as localFileStamp, E as isoLocal, S as setActiveSessionInfo, T as useSession, _ as parseSessionContextFromEvents, a as pruneMissingBindings, b as sessionEvents$1, c as setBindingStore, d as clearActiveSessionInfo, f as createSession, g as listSessions, h as getActiveSessionInfo, l as DEFAULT_SESSION_SCOPE, m as findSession, n as PLUGIN_SOURCE, o as readLastBound, p as extractSessionMdPathFromText, r as appendBound, s as resolveSessionTrajectoryLabel, t as ACC_MESSAGE_KIND, u as TRAJECTORY_ACTIONS, v as readActiveSessionMd, w as summarize, x as sessionsRoot, y as resolveSessionByTitle } from "./message-source-Boc-AbHs.js";
+import { i as cccRootForExec, n as agentCwdFor, o as listCccs, r as cccRootForCwd, t as NO_CCC_FROM_AGENT_CWD } from "./ccc-roots-NpTWo0-c.js";
+import { C as showSession, D as localFileStamp, E as isoLocal, S as setActiveSessionInfo, T as useSession, _ as parseSessionContextFromEvents, a as pruneMissingBindings, b as sessionEvents$1, c as setBindingStore, d as clearActiveSessionInfo, f as createSession, g as listSessions, h as getActiveSessionInfo, l as DEFAULT_SESSION_SCOPE, m as findSession, n as PLUGIN_SOURCE, o as readLastBound, p as extractSessionMdPathFromText, r as appendBound, s as resolveSessionTrajectoryLabel, t as ACC_MESSAGE_KIND, u as TRAJECTORY_ACTIONS, v as readActiveSessionMd, w as summarize, x as sessionsRoot, y as resolveSessionByTitle } from "./message-source-aR-FJ38L.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-CWMRa36W.js";
 import { a as unregisterSkiffSession$1, i as skiffSessionSnapshot$1, n as skiffRoleFor$1, o as ACC_VERSION, r as skiffSessionInfo$1, t as registerSkiffSession$1 } from "./skiff-registry-BjIX_KD1.js";
 import { a as readSkiffRoles, c as roleMsmWhitelist, d as systemPromptSource, f as trajectorySubset, i as isSkiffSessionId, l as roleToolWhitelist, n as buildSkiffBasePrompt, o as resolveRoleSystemPrompt, r as createRolePromptReader, s as resolveSkiffKind } from "./skiff-role-KqQA6pkr.js";
-import { a as FACE_PORTS, c as MECHANISM_PORTS, i as ACP_HTTP_PORT, l as SKIFF_DEBUG_PORT, n as registerSettingsSection, o as GATEWAY_PORT, s as MAIN_WEB_PORT, t as readSimpleSettings, u as WEIXIN_SEND_PORT } from "./settings-section-DTJW4smh.js";
+import { a as FACE_PORTS, c as MECHANISM_PORTS, i as ACP_HTTP_PORT, l as SKIFF_DEBUG_PORT, n as registerSettingsSection, o as GATEWAY_PORT, s as MAIN_WEB_PORT, t as readSimpleSettings, u as WEIXIN_SEND_PORT } from "./settings-section-DxMwlCv9.js";
 import { r as sessionsRootDir, t as hasSessionLogById } from "./session-cleanup-BtkSmry8.js";
-import { a as registerDisposer, c as WAKE_CATCH_UP_MS, i as registerCroTurnTracking, l as addWake, n as sendToTrajectory, o as CRO_FILENAME, r as wakeSchedulerState, s as buildCroSnapshot, t as registerWakeScheduler, u as listWakes } from "./wake-scheduler-DdaRNofO.js";
+import { a as registerDisposer, c as WAKE_CATCH_UP_MS, i as registerCroTurnTracking, l as addWake, n as sendToTrajectory, o as CRO_FILENAME, r as wakeSchedulerState, s as buildCroSnapshot, t as registerWakeScheduler, u as listWakes } from "./wake-scheduler-BR4hD8Vj.js";
 import { a as markdownToPlainText, c as sendTyping, i as getUpdates, l as sniffImageExt, n as downloadMedia, o as sendFileMessage, r as getConfig, s as sendTextMessage, t as TypingStatus } from "./weixin-api-CtFYm53S.js";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
@@ -1762,6 +1762,61 @@ function splitModel(model) {
 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(", ")}`);
 }
+/**
+* providerAvailabilityError — 判定「**本机有没有该 provider 的 adapter**」，并产出**可执行**的错误文本。
+* 返回 `null` = 全部可用（调用方照常继续）。
+*
+* 🔴 为什么需要它（S142 2026-09-25，owner 在 **Mac** 上实测）：`handyman` 的模型白名单写在
+*   **CCC**（`.opencode/serenity.json`，**随 git 走**），而 provider adapter 由**每台机器的宿主**
+*   注册（profile 配置 / settings 命名空间）⇒ 同一份白名单在一台机器可用、在另一台必失败。
+*   实测症状：宿主抛 `no adapter registered for provider "<p>"`（`dsh-llm`，code `NO_ADAPTER`），
+*   而**前台路径的 `diagnostic` 是空的** ⇒ 调用方（LLM）拿到 `stopReason:"error"` 却**不知道为什么**，
+*   也就无法修正自己的配置 —— 本条把「沉默的失败」变成「可执行的错误」。
+*
+* 数据来源（宿主 `LlmRuntime`）：`listProviders()` = **有 adapter 的路由**；
+* `listConfigurableProviders()` = **已声明但未必激活**的路由（含激活用的 settings 命名空间）。
+*
+* 判据边界：`model` 串里**没有 `/`** 时取不到 provider（沿用 agent 默认路由）⇒ **不判定**（跳过）。
+*/
+function providerAvailabilityError(models, facts) {
+	const registered = new Set(facts.registered.map((r) => r.id));
+	const requested = models.map((m) => ({
+		raw: m,
+		provider: splitModel(m).provider
+	})).filter((e) => typeof e.provider === "string" && e.provider !== "");
+	const missing = [...new Set(requested.filter((e) => !registered.has(e.provider)).map((e) => e.provider))];
+	if (missing.length === 0) return null;
+	const list = (items, cap = 12) => items.length === 0 ? "  (none)" : items.slice(0, cap).map((s) => `  - ${s}`).join("\n") + (items.length > cap ? `\n  … and ${items.length - cap} more` : "");
+	const available = facts.registered.map((r) => r.name ? `${r.id} (${r.name})` : r.id).sort();
+	const declared = (facts.declared ?? []).filter((d) => missing.includes(d.provider));
+	const configPath = facts.configPath ?? "<ccc>/.opencode/serenity.json";
+	const missingList = missing.map((p) => `"${p}"`).join(", ");
+	return [
+		`handyman: provider ${missingList} has no adapter registered on this machine.`,
+		"",
+		"  Requested model(s) :",
+		...requested.map((e) => `    ${e.raw}`),
+		`  Configured in      : ${configPath} → "handyman.models" / "handyman.defaultModel"`,
+		"",
+		"  Why this happens   : the whitelist lives in the CCC (it travels with the repository), while",
+		"                       provider adapters are registered per machine by the host. An entry that",
+		"                       works on one machine can fail on another.",
+		"",
+		"  Available on this machine (registered adapters):",
+		list(available),
+		"",
+		"  Declared but NOT active here (activate via settings, then retry):",
+		list(declared.map((d) => `${d.provider}${d.displayName ? ` (${d.displayName})` : ""}${d.settingsNs ? ` — settings namespace "${d.settingsNs}"` : ""}`)),
+		"",
+		"  Fix (pick one, then retry):",
+		`    1. Point the whitelist at a provider that IS registered here — edit ${configPath}`,
+		"       (\"handyman.models\", and \"handyman.defaultModel\" if that is what you relied on).",
+		`    2. Register/activate provider ${missingList} on this machine (host profile config,`,
+		"       or the settings namespace listed above).",
+		"",
+		"  Do not retry unchanged — the same call fails identically."
+	].join("\n");
+}
 /** 轮次 prompt（对齐老 loop 结构：回顾进度 → 自由工作 → 汇报；S134 EAP 化：固定详尽） */
 function buildRoundPrompt(opts) {
 	const { root, session, label, round, stopToken, progress, task } = opts;
@@ -1828,6 +1883,18 @@ Before calling handyman, load eap (acc-eap skill) and design the "scale-up handy
 - background mode: recursive subagents inside a worker inherit the worker's model automatically (DSH native)
 - foreground mode: the child is started through the host delegation service with the resolved model
 
+### 3b. 🔴 Provider availability (per-machine — the whitelist is NOT enough)
+- The whitelist lives in the **CCC** ("serenity.json", it **travels with the repository**), but provider
+  **adapters are registered per machine by the host** (profile config / settings namespace). An entry that
+  works on one machine can fail on another with: "no adapter registered for provider <p>".
+- Before spawning, handyman verifies the provider of the resolved model against the adapters registered
+  **on this machine**; if it is missing it reports the requested model, where it is configured, **the
+  providers that ARE available here**, any declared-but-dormant route (with its settings namespace), and the
+  exact fix — foreground puts this in "diagnostic", background throws it.
+- ⇒ If you see "has no adapter registered on this machine": edit ".opencode/serenity.json" "handyman.models"
+  (and "handyman.defaultModel") to a provider listed as available, or activate/register the provider on this
+  machine. **Do not retry the same call unchanged** — it fails identically.
+
 ### 4. Parallel strategy (background mode only)
 - Independent subtasks can run in parallel via handyman(mode="background", 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
@@ -4252,6 +4319,38 @@ function subagentOutputText(output) {
 	return output.filter((b) => typeof b === "object" && b !== null).filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("");
 }
 /**
+* providerPreflight — 在**创建任何 worker 之前**判定「本机有没有该 provider 的 adapter」。
+*
+* 返回**可执行**的错误文本；`null` = 可用，**或无法取证**（服务缺失 / 形状不符 / 读取抛错
+* ⇒ 一律**不阻断**，保持旧行为 —— 增强不得变成新的失败源）。
+*
+* 为什么必须放在"创建之前"：宿主对未知 provider 抛 `no adapter registered for provider "…"`
+* （`dsh-llm`，code `NO_ADAPTER`）。若照常创建：前台只拿回 `stopReason:"error"` ＋ **空
+* `diagnostic`**（实测），后台整条失败且**不带原因** ⇒ 调用方（LLM）无法自我修正配置。
+*/
+function providerPreflight(ctx, model) {
+	const llm = hostLlm(ctx);
+	if (typeof llm?.listProviders !== "function") return null;
+	let registered;
+	try {
+		const raw = llm.listProviders();
+		if (!Array.isArray(raw)) return null;
+		registered = raw.filter((r) => typeof r === "object" && r !== null && typeof r.id === "string");
+	} catch {
+		return null;
+	}
+	let declared = [];
+	try {
+		const raw = llm.listConfigurableProviders?.();
+		if (Array.isArray(raw)) declared = raw.filter((d) => typeof d === "object" && d !== null && typeof d.provider === "string");
+	} catch {}
+	return providerAvailabilityError([model], {
+		registered,
+		declared,
+		configPath: ".opencode/serenity.json"
+	});
+}
+/**
 * foreground 模式：单次前台串行委派（用户裁决"本次所需的简单实现"）。
 *
 * 与 background 的差别（R↓）：
@@ -4269,6 +4368,15 @@ async function runForegroundJob(ctx, 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.");
+	const preflight = providerPreflight(ctx, model);
+	if (preflight !== null) return {
+		mode: "foreground",
+		done: false,
+		model,
+		stopReason: "error",
+		output: "",
+		diagnostic: preflight
+	};
 	const { provider, model: modelName } = splitModel(model);
 	const run = await subagents.start("spawn", {
 		...label === void 0 ? {} : { label },
@@ -4309,6 +4417,8 @@ async function runHandymanJob(ctx, opts) {
 	const label = job.label;
 	const model = job.model ?? defaultModel;
 	requireWhitelistedModel(model, models);
+	const preflightError = providerPreflight(ctx, model);
+	if (preflightError !== null) throw new Error(preflightError);
 	const { provider, model: modelName } = splitModel(model);
 	const stopToken = newStopToken();
 	let progress = readProgress(root, label);
@@ -4426,7 +4536,7 @@ async function runHandymanJob(ctx, opts) {
 function createHandymanTool(ctx) {
 	return defineTool({
 		name: "handyman",
-		description: "The handyman (杂工): delegate work to a worker agent on a CCC-configured model. Two modes (v1.31.3).\nMode \"foreground\" (DEFAULT): one serial child agent runs the task once and returns its final text — no loop, no completion-code validation, no progress file; use it for one-shot serial delegation (e.g. per-case testers that just gather evidence). Usage: handyman(task, [label], [model]).\nMode \"background\": the loop-validated worker — internal hard while-loop whose ONLY completion condition is the worker echoing this round's random completion code (stop token, prevents low-intelligence models from finishing early), round cap (default 100, resumable), automatic restart on abnormal stop (≤100), progress file AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes), and parallel jobs (handyman.maxParallel, default 10). Usage: handyman(mode=\"background\", task, label, [model]) or handyman(mode=\"background\", jobs=[{task,label,model?},...]).\nChoosing: need exactly one result back now → foreground; need anti-early-finish guarantees, resumability or parallel jobs → background.\nModel: only models whitelisted in .opencode/serenity.json \"handyman.models\" (missing config = error); default reads handyman.defaultModel. Both modes share the same whitelist and default.\nRecursion: a worker's tool set excludes handyman itself (orchestration belongs to the main agent).\nGuide: handyman(guide=true) prints the scale-up usage guide.",
+		description: "The handyman (杂工): delegate work to a worker agent on a CCC-configured model. Two modes (v1.31.3).\nMode \"foreground\" (DEFAULT): one serial child agent runs the task once and returns its final text — no loop, no completion-code validation, no progress file; use it for one-shot serial delegation (e.g. per-case testers that just gather evidence). Usage: handyman(task, [label], [model]).\nMode \"background\": the loop-validated worker — internal hard while-loop whose ONLY completion condition is the worker echoing this round's random completion code (stop token, prevents low-intelligence models from finishing early), round cap (default 100, resumable), automatic restart on abnormal stop (≤100), progress file AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes), and parallel jobs (handyman.maxParallel, default 10). Usage: handyman(mode=\"background\", task, label, [model]) or handyman(mode=\"background\", jobs=[{task,label,model?},...]).\nChoosing: need exactly one result back now → foreground; need anti-early-finish guarantees, resumability or parallel jobs → background.\nModel: only models whitelisted in .opencode/serenity.json \"handyman.models\" (missing config = error); default reads handyman.defaultModel. Both modes share the same whitelist and default.\nProvider check: the whitelist lives in the CCC (it travels with the repo) while provider adapters are registered per machine by the host — so before spawning, the provider of the resolved model is verified against the adapters present on THIS machine. If it is missing you get the available providers plus the exact fix (foreground: in `diagnostic`; background: thrown), never an opaque failure.\nRecursion: a worker's tool set excludes handyman itself (orchestration belongs to the main agent).\nGuide: handyman(guide=true) prints the scale-up usage guide.",
 		parameters: {
 			mode: {
 				type: "string",
@@ -4508,7 +4618,8 @@ function createHandymanTool(ctx) {
 				if (typeof args.task !== "string" || typeof args.label !== "string") throw new Error("handyman: task and label are required (single-job mode)");
 				return [{
 					task: args.task,
-					label: args.label
+					label: args.label,
+					...typeof args.model === "string" && args.model !== "" ? { model: args.model } : {}
 				}];
 			})();
 			if (jobs.length === 0) throw new Error("handyman: no jobs provided");
@@ -7779,7 +7890,7 @@ function registerStatusApi(ctx, opts = {}) {
 					return;
 				}
 				const settings = readAdvancedSettings();
-				const { readSimpleSettings } = await import("./settings-section-DTJW4smh.js").then((n) => n.r);
+				const { readSimpleSettings } = await import("./settings-section-DxMwlCv9.js").then((n) => n.r);
 				const simple = readSimpleSettings();
 				const allowed = settings.publicAsk.allowed;
 				const port = simple.acpHttpPort ?? ACP_HTTP_PORT;
@@ -14134,7 +14245,7 @@ function registerWeixinBridge(ctx) {
 	const syncFromLive = () => {
 		(async () => {
 			try {
-				const { listCccs } = await import("./ccc-roots-FxWXuZPw.js").then((n) => n.a);
+				const { listCccs } = await import("./ccc-roots-NpTWo0-c.js").then((n) => n.a);
 				for (const entry of await listCccs(ctx)) syncCccBridge(ctx, entry.root);
 			} catch {}
 		})();
@@ -14260,7 +14371,7 @@ function matchCcc(input, candidates) {
 }
 /** 组装候选列表（`ccc-roots.listCccs` 投影 + `.serenity` 名；动态 import 保持本模块静态依赖轻量） */
 async function collectCandidates(ctx) {
-	const { listCccs } = await import("./ccc-roots-FxWXuZPw.js").then((n) => n.a);
+	const { listCccs } = await import("./ccc-roots-NpTWo0-c.js").then((n) => n.a);
 	const entries = await listCccs(ctx, { defaultRoot: process.cwd() });
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
@@ -16081,16 +16192,16 @@ const Config = z.object({
 	webFetch: z.object({ enabled: z.boolean().default(true) }),
 	opencodeProvider: z.object({ autoConfigure: z.boolean().default(true) }),
 	visionPatch: z.object({ enabled: z.boolean().default(true) }),
-	gatewayEnabled: z.boolean(),
-	rebuildEnabled: z.boolean(),
-	rebuildThresholdK: z.number().min(50).max(4e3),
-	skiffEnabled: z.boolean(),
-	skiffDebugPort: z.number().min(1024).max(65535),
-	acpEnabled: z.boolean(),
-	acpHttpPort: z.number().min(1024).max(65535),
-	publicAskEnabled: z.boolean(),
-	croEnabled: z.boolean(),
-	unattendedEnabled: z.boolean()
+	gatewayEnabled: z.boolean().volatile(),
+	rebuildEnabled: z.boolean().volatile(),
+	rebuildThresholdK: z.number().min(50).max(4e3).volatile(),
+	skiffEnabled: z.boolean().volatile(),
+	skiffDebugPort: z.number().min(1024).max(65535).volatile(),
+	acpEnabled: z.boolean().volatile(),
+	acpHttpPort: z.number().min(1024).max(65535).volatile(),
+	publicAskEnabled: z.boolean().volatile(),
+	croEnabled: z.boolean().volatile(),
+	unattendedEnabled: z.boolean().volatile()
 });
 function apply(ctx, config) {
 	try {

package/lib/{message-source-Boc-AbHs.js → message-source-aR-FJ38L.js}

@@ -1,4 +1,4 @@
-import { r as cccRootForCwd } from "./ccc-roots-FxWXuZPw.js";
+import { r as cccRootForCwd } from "./ccc-roots-NpTWo0-c.js";
 import { basename, dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 //#region src/time.ts

package/lib/{settings-section-DTJW4smh.js → settings-section-DxMwlCv9.js}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { a as hostSettings } from "./access-fiehjxV6.js";
+import { o as hostSettings } from "./access-CNccNtgf.js";
 //#region src/ports.ts
 /**
 * 集中端口表。
@@ -63,7 +63,8 @@ var settings_section_exports = /* @__PURE__ */ __exportAll({
 	defaultSimpleSettings: () => defaultSimpleSettings,
 	readSimpleSettings: () => readSimpleSettings,
 	registerSettingsSection: () => registerSettingsSection,
-	simpleSettingsFromConfig: () => simpleSettingsFromConfig
+	simpleSettingsFromConfig: () => simpleSettingsFromConfig,
+	unwrapVolatile: () => unwrapVolatile
 });
 /** 进程级默认（无 Config 可读时的兜底；与 Config 各字段的缺省一致） */
 function defaultSimpleSettings() {
@@ -81,6 +82,30 @@ function defaultSimpleSettings() {
 	};
 }
 /**
+* volatile 字段的**结构化解包**（v1.47.2；本文件读取语义的第一道）。
+*
+* ## 为什么必须有它（两个事实的合成，缺一即错）
+* ① **0.1.7 的面板层字段必须标 `.volatile()`** —— 否则本插件命名空间整个不进宿主的
+*    `settings.describe()`（`volatileForm()` 只认 `meta.volatile`）⇒ **设置面板那一节消失**。
+* ② **标了之后，运行期拿到的是引用包装，不是裸值** —— schemastery 的 `Schema.resolve()` 对
+*    `meta.volatile` **无条件**包 `createVolatile(value)`，且该分支排在"缺省值回退"那一段
+*    **之前** ⇒ **"用户没设过"的字段也是恒真对象**（`.get()` 返回 `undefined`），**不是 `undefined`**。
+*
+* ⇒ 若这里不解包，下面十行的 `??` 链会**短路在这层包装上** ⇒ 网关 / Skiff / ACP 会被
+* **无意打开**（比"面板不显示"更坏：静默改变对外暴露面）。
+*
+* ## 为什么用结构判定
+* 可观察形状就是"有 `get()`"（cosmokit 的 `isVolatile` 也这么判）；本模块不引它的运行时依赖。
+*
+* @param value - volatile 引用 ｜ 裸值 ｜ undefined
+* @returns 解包后的裸值（引用 ⇒ `.get()`；裸值原样；缺省 ⇒ `undefined`）
+*/
+function unwrapVolatile(value) {
+	if (value === void 0 || value === null) return void 0;
+	if (typeof value.get === "function") return value.get();
+	return value;
+}
+/**
 * Config（宿主 Loader 校验后的解析值）→ 扁平简单配置。**本文件唯一的读取语义**。
 *
 * 优先级：**面板层（扁平键）> 部署层（嵌套段）> 内建缺省**。
@@ -90,16 +115,16 @@ function defaultSimpleSettings() {
 function simpleSettingsFromConfig(config) {
 	const d = defaultSimpleSettings();
 	return {
-		gatewayEnabled: config.gatewayEnabled ?? config.gateway?.enabled ?? d.gatewayEnabled,
-		rebuildEnabled: config.rebuildEnabled ?? config.rebuild?.enabled ?? d.rebuildEnabled,
-		rebuildThresholdK: config.rebuildThresholdK ?? config.rebuild?.thresholdK ?? d.rebuildThresholdK,
-		skiffEnabled: config.skiffEnabled ?? config.skiff?.enabled ?? d.skiffEnabled,
-		skiffDebugPort: config.skiffDebugPort ?? config.skiff?.debugPort ?? d.skiffDebugPort,
-		acpEnabled: config.acpEnabled ?? config.acp?.enabled ?? d.acpEnabled,
-		acpHttpPort: config.acpHttpPort ?? config.acp?.httpPort ?? d.acpHttpPort,
-		publicAskEnabled: config.publicAskEnabled ?? d.publicAskEnabled,
-		croEnabled: config.croEnabled ?? d.croEnabled,
-		unattendedEnabled: config.unattendedEnabled ?? d.unattendedEnabled
+		gatewayEnabled: unwrapVolatile(config.gatewayEnabled) ?? config.gateway?.enabled ?? d.gatewayEnabled,
+		rebuildEnabled: unwrapVolatile(config.rebuildEnabled) ?? config.rebuild?.enabled ?? d.rebuildEnabled,
+		rebuildThresholdK: unwrapVolatile(config.rebuildThresholdK) ?? config.rebuild?.thresholdK ?? d.rebuildThresholdK,
+		skiffEnabled: unwrapVolatile(config.skiffEnabled) ?? config.skiff?.enabled ?? d.skiffEnabled,
+		skiffDebugPort: unwrapVolatile(config.skiffDebugPort) ?? config.skiff?.debugPort ?? d.skiffDebugPort,
+		acpEnabled: unwrapVolatile(config.acpEnabled) ?? config.acp?.enabled ?? d.acpEnabled,
+		acpHttpPort: unwrapVolatile(config.acpHttpPort) ?? config.acp?.httpPort ?? d.acpHttpPort,
+		publicAskEnabled: unwrapVolatile(config.publicAskEnabled) ?? d.publicAskEnabled,
+		croEnabled: unwrapVolatile(config.croEnabled) ?? d.croEnabled,
+		unattendedEnabled: unwrapVolatile(config.unattendedEnabled) ?? d.unattendedEnabled
 	};
 }
 /** 运行时源（`registerSettingsSection` 装配：读本插件 fiber 的**当前** Config） */

package/lib/settings-section.d.ts

@@ -33,7 +33,16 @@
  * 🔴 面板层的键**故意不带 schemastery 默认值** —— 有默认值就永远非 `undefined`，
  * 部署层会被无声压死（"未设置"必须可观测）。
  */
-import type { Context } from 'cordis';
+import type { Context, Volatile } from 'cordis';
+/**
+ * 面板层布尔键的**两种来法**（v1.47.2）：
+ *  - 宿主 Loader 解析后的 Config ⇒ `Volatile<boolean | undefined>` **引用包装**（0.1.7 起面板字段必须 volatile）
+ *  - 手写 Config / 部署 bundle / 单测 ⇒ 裸布尔
+ * ⇒ 本层两种都收，**读取一律先 `unwrapVolatile()`**（否则包装对象恒真 ⇒ 开关被无意打开）。
+ */
+type PanelBoolean = boolean | Volatile<boolean | undefined>;
+/** 面板层数值键：同 `PanelBoolean`（两种来法） */
+type PanelNumber = number | Volatile<number | undefined>;
 /** 插件 Config 的简单配置片段（index.ts 的 Config 子集；面板层 + 部署层两种拼写） */
 interface SimpleConfigFragment {
     gateway?: {
@@ -53,16 +62,16 @@ interface SimpleConfigFragment {
         enabled?: boolean;
         httpPort?: number;
     };
-    gatewayEnabled?: boolean;
-    rebuildEnabled?: boolean;
-    rebuildThresholdK?: number;
-    skiffEnabled?: boolean;
-    skiffDebugPort?: number;
-    acpEnabled?: boolean;
-    acpHttpPort?: number;
-    publicAskEnabled?: boolean;
-    croEnabled?: boolean;
-    unattendedEnabled?: boolean;
+    gatewayEnabled?: PanelBoolean;
+    rebuildEnabled?: PanelBoolean;
+    rebuildThresholdK?: PanelNumber;
+    skiffEnabled?: PanelBoolean;
+    skiffDebugPort?: PanelNumber;
+    acpEnabled?: PanelBoolean;
+    acpHttpPort?: PanelNumber;
+    publicAskEnabled?: PanelBoolean;
+    croEnabled?: PanelBoolean;
+    unattendedEnabled?: PanelBoolean;
 }
 /**
  * 设置面板命名空间 = **profile 条目 id**（v0.1.7 起；与旧 `settings.yaml` 段名逐字相同）。
@@ -107,6 +116,30 @@ interface SerenitySimpleSettings {
 }
 /** 进程级默认（无 Config 可读时的兜底；与 Config 各字段的缺省一致） */
 export declare function defaultSimpleSettings(): SerenitySimpleSettings;
+/** volatile 引用的**可观察形状**（结构判定用；刻意不引 cosmokit —— 它是宿主内部包，不是我们的 peerDep） */
+interface VolatileRef<T> {
+    get(): T;
+}
+/**
+ * volatile 字段的**结构化解包**（v1.47.2；本文件读取语义的第一道）。
+ *
+ * ## 为什么必须有它（两个事实的合成，缺一即错）
+ * ① **0.1.7 的面板层字段必须标 `.volatile()`** —— 否则本插件命名空间整个不进宿主的
+ *    `settings.describe()`（`volatileForm()` 只认 `meta.volatile`）⇒ **设置面板那一节消失**。
+ * ② **标了之后，运行期拿到的是引用包装，不是裸值** —— schemastery 的 `Schema.resolve()` 对
+ *    `meta.volatile` **无条件**包 `createVolatile(value)`，且该分支排在"缺省值回退"那一段
+ *    **之前** ⇒ **"用户没设过"的字段也是恒真对象**（`.get()` 返回 `undefined`），**不是 `undefined`**。
+ *
+ * ⇒ 若这里不解包，下面十行的 `??` 链会**短路在这层包装上** ⇒ 网关 / Skiff / ACP 会被
+ * **无意打开**（比"面板不显示"更坏：静默改变对外暴露面）。
+ *
+ * ## 为什么用结构判定
+ * 可观察形状就是"有 `get()`"（cosmokit 的 `isVolatile` 也这么判）；本模块不引它的运行时依赖。
+ *
+ * @param value - volatile 引用 ｜ 裸值 ｜ undefined
+ * @returns 解包后的裸值（引用 ⇒ `.get()`；裸值原样；缺省 ⇒ `undefined`）
+ */
+export declare function unwrapVolatile<T>(value: T | VolatileRef<T> | undefined): T | undefined;
 /**
  * Config（宿主 Loader 校验后的解析值）→ 扁平简单配置。**本文件唯一的读取语义**。
  *

package/lib/{wake-scheduler-DdaRNofO.js → wake-scheduler-BR4hD8Vj.js}

@@ -1,8 +1,8 @@
-import { r as hostService, t as hostAgents } from "./access-fiehjxV6.js";
+import { i as hostService, t as hostAgents } from "./access-CNccNtgf.js";
 import { g as resolveInside } from "./ccc-DG4Oc7I1.js";
-import { o as listCccs } from "./ccc-roots-FxWXuZPw.js";
-import { E as isoLocal, O as localHuman, i as listBoundSessionIds, k as localIdStamp, m as findSession, n as PLUGIN_SOURCE, x as sessionsRoot } from "./message-source-Boc-AbHs.js";
-import { t as readSimpleSettings } from "./settings-section-DTJW4smh.js";
+import { o as listCccs } from "./ccc-roots-NpTWo0-c.js";
+import { E as isoLocal, O as localHuman, i as listBoundSessionIds, k as localIdStamp, m as findSession, n as PLUGIN_SOURCE, x as sessionsRoot } from "./message-source-aR-FJ38L.js";
+import { t as readSimpleSettings } from "./settings-section-DxMwlCv9.js";
 import { basename, dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shgroup/dsh-serenity-hooks",
-  "version": "1.47.1",
+  "version": "1.47.3",
   "description": "宁静号 ACC harness（Native Cordis 插件）——给 DeepSeek Harness 装一个「AI 工作区」：11 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/im-bridge/acc-diag）+ 机械约束（安全模式/工作区围墙/密钥守卫/对外输出守卫）+ 工作日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.7-rc.1。",
   "license": "MIT",
   "repository": {