@shgroup/dsh-serenity-hooks 1.32.0 → 1.34.1

package/lib/diag-ops.d.ts

@@ -0,0 +1,76 @@
+/**
+ * diag-ops.ts — `acc-diag` 报告装配（v1.33，S142 §32.11）
+ *
+ * 为什么单独成模块（R↓）：工具面（`tools/acc-diag.ts`）只做"取 CCC 根 + 渲染"，
+ * 装配逻辑放这里 ⇒ 纯函数可单测、不依赖 DSH 工具注册。
+ *
+ * 为什么**无动作参数**：诊断是低频动作（§32.9 收敛取向），一次调用即出全报告，
+ * 不需要子命令面；动作越多，模型选择成本越高。
+ *
+ * 四段内容（数据来源各自单一真相源，本模块只聚合不复制语义）：
+ *   ① live 运行态 —— 插件进程内 `diagLive(ctx)`（live 会话清单 + 各 autopilot CCC 的
+ *      目标命中 / agent 定位诊断）——**独立进程看不到运行时**，这正是本工具存在的理由
+ *   ② 面板解析 —— `diagLive.panelResolved`（无参面板请求会落到哪个 CCC）
+ *   ③ 唤醒注册表 —— `wake-registry.json` 全量条目（state / at / target / lastResult）+ 补跑窗口
+ *   ④ 唤起条件链 —— **进程内** {@link buildWakeChain}（⑥ C6a）：逐条件值 + 阻断点 + 修复建议
+ *      + 只有进程内能看到的三项事实（全局闸 / live 会话 / agent 可解析性）
+ *
+ * C5「观察面归一」（2026-09-15）：①/② 仍走 `diagLive`（那是**live 运行态**的独有取数，
+ * 没有第二个来源），但 ①b 时钟与 ③ 注册表改经 `container-status.ts` 取（唯一取数出口）——
+ * **投影仍在本文件**（诊断段不含 `message`，面板含；这是渲染差异，不是取数差异）。
+ *
+ * ⑥ C6a（2026-09-15）：④ 段由"spawn 包内脚本"改为**进程内计算**。旧实现是本报告里
+ * 唯一一条**跨进程**取数：脚本看不到全局闸/live/agent ⇒ 与本工具 ① 段自相矛盾
+ * （① 说"agent 未定位"，④ 却印"条件全部满足"）。现在 ④ 段与 ① 段读**同一份事实**
+ * （`autopilotRuntimeFacts`），且条件链**只有一份实现**（开发面 `dsh-develop diag` import 同一个）。
+ */
+import { type DiagLiveReport } from './autopilot-trajectory.js';
+import { type ClockSnapshot } from './container-status.js';
+import type { Context } from 'cordis';
+/** 进程内时钟状态（唤醒调度器 / autopilot 时钟；判据各自单一真相源） */
+type ClockState = ClockSnapshot;
+interface AccDiagReport {
+    /** 调用方会话所属 CCC 根（过程内诊断的目标） */
+    ccc: string;
+    live: DiagLiveReport;
+    /**
+     * 进程内两个时钟的武装状态（2026-09-14 F 段缺陷**新暴露面**）。
+     * 为什么必须有（R↓）：此前"条目为何滞留在 pending"无法从报告回答——④ 段只算**配置**条件，
+     * 而真正的原因可能在"时钟根本没在跑"这一层。有了它，同类故障一眼可判。
+     */
+    clocks: {
+        wake: ClockState;
+        autopilot: ClockState;
+    };
+    wakes: {
+        /** 注册表文件路径问题（读不到时非空——不得静默） */
+        error: string | null;
+        entries: Array<{
+            id: string;
+            target: string;
+            at: string;
+            state: string;
+            createdBy: string;
+            attempts: number;
+            lastResult: string | null;
+        }>;
+        pending: number;
+    };
+    /**
+     * 唤起条件链（进程内算出的渲染文本，含逐条件值 + 阻断点 + 修复建议）。
+     * **不是**子进程输出——判据唯一实现见 `autopilot-chain.ts`。
+     */
+    autopilotChain: string;
+    /** 条件链判决档（`ready`/`waiting`/`blocked`/`unknown`；供调用方/测试断言，不再解析文本） */
+    autopilotVerdict: string;
+}
+/**
+ * 装配报告（一次调用即全报告）。
+ * @param ctx 插件上下文（进程内读 sessions/agents）
+ * @param root 调用方 CCC 根（条件链诊断目标）
+ * @returns 结构化报告（渲染由 {@link renderAccDiag} 负责）
+ */
+export declare function runAccDiag(ctx: Context, root: string): Promise<AccDiagReport>;
+/** 人读渲染（四段；空段也要显式说明"无"，避免"沉默 = 一切正常"的误读） */
+export declare function renderAccDiag(r: AccDiagReport): string;
+export {};

package/lib/face-host.d.ts

@@ -0,0 +1,110 @@
+/**
+ * face-host.ts — **面宿主**：插件自起 HTTP listener 的唯一生命周期处（C4 块 A，S142 2026-09-15）
+ *
+ * ## 现状 → 本模块要收掉什么（取证：`…/acc-c4c5-current-state.md` §①/§③ 3.1）
+ *
+ * 插件自己 spawn 了**四个** node:http 监听器（B 3081 网关 / C 3082 微信发送 / D 3099 Skiff 调试
+ * / E 3100 ACP+问答）。此前四处各写一份同款样板：`createServer` + `server.once('error')` +
+ * `listen(port, host)` + 模块级 `active` 变量 + `close()`；拆卸也分裂成**两套**——
+ * `seams/lifecycle.ts` 有一个聚合 disposer，而 `gateway.ts` 与 `weixin-send-api.ts`
+ * **各自另注册**一个（D/E 干脆没有自己的 disposer）。
+ *
+ * 本模块把"listener 生命周期"收成一处：**active 表 + 统一 listen/close + 统一错误与端口占用
+ * 处理**。四个面各自只提供 `{ name, port, host, enabled, handler }`。
+ *
+ * ## 🔴 共享的是「生命周期与样板」，**绝不是**「路由 / 监听器 / 鉴权」
+ *
+ * 每个面**保留自己的 listener、自己的路由、自己的鉴权**（`handler` 内部原样不动）：
+ *   · **A ↔ C 解耦**（`weixin-send-api.ts:4-7`）：3080 会被 3081 原样反代（连请求头），
+ *     把 3082 的端点挂到 3080 上 = 已登录的外部家庭账号即可冒充 bot 发消息
+ *     ⇒ 本模块**不提供**"把面挂到别的面"的能力，也不共享路由表；
+ *   · **E ↔ D** 共用会话核心（acp-core → skiff-core）但各自独立 listener + 独立路由/HTML；
+ *   · **B 是 A 的代理宿主**（把请求打到 `127.0.0.1:<主端口>`），不是另一个路由面。
+ *
+ * ## 面 A（3080）不在本模块之列
+ * 它是**宿主 DSH 主 WebUI**，插件只往上挂 `/serenity/*` 路由（`ctx.webServer.register`），
+ * **插件不起这个 listener** ⇒ 面宿主只持有 B/C/D/E 四个自起面。
+ *
+ * ## 两个入口的分工（这是本模块唯一的"抽象决策"，别混）
+ *   · {@link startFace} —— **机械启动**：把一个 handler 绑到 `host:port` 上。同名面若已在监听，
+ *     **先停后起**（替换）；同名面正在启动中则**复用在飞的 Promise**（并发合并——这条替代了
+ *     `index.ts` 里手搓的 `starting` 在飞标志与随之而来的 `EADDRINUSE` 双绑）。
+ *     它**不读** `spec.enabled()`：调用方保证意图（测试/程序化直启也走这里）。
+ *   · {@link faceEnabled} —— **意图读取**：装配层据此判"该面此刻应否在监听"，替代各面 sync 里
+ *     手写的 `const want = <配置> && ...` 判据（判据本身只写在面的 {@link FaceSpec} 里一次）。
+ */
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+/** 面规格：**四个面各自只提供这 5 项**（路由/鉴权/响应体全部归面的 `handler`） */
+export interface FaceSpec {
+    /** 面名（日志/拆卸/幂等键；全进程唯一，建议用 `FACE_*` 常量） */
+    name: string;
+    /** 期望监听端口（0 = 内核分配；实际端口见 {@link FaceHandle.port}） */
+    port: number;
+    /** 监听地址（各面自定：`127.0.0.1` 或 `0.0.0.0`——**不因归一而改绑**） */
+    host: string;
+    /** 该面**此刻是否应处于监听状态**（面自己的配置意图；由 {@link faceEnabled} 读取） */
+    enabled: () => boolean;
+    /** 单请求处理（面自己的路由 / 鉴权 / 响应体，本模块不介入其语义） */
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+    /**
+     * **EADDRINUSE 重试预算**：每次重试前等待的毫秒数序列（长度 = 最多重试次数）。
+     * 缺省 = {@link DEFAULT_RETRY_DELAYS}（10 × 1000ms，**生产行为原样不变**）。
+     * 传空数组 = 零重试（一次 EADDRINUSE 即 reject）；测试用短预算证明"耗尽即 reject"。
+     *
+     * 🔒 不变量（v1.34.1 修 flake 时显式化）：重试预算**可见、可控、有界**——
+     * 绑定尝试绝不无声挂满整段预算；耗尽即 **reject**（调用方可见），不静默悬挂。
+     * 此前预算是模块内硬写的 10×1s，而 vitest 单测超时 5s ⇒ "快失败"被拉长成"挂死"，
+     * 调用方无从缩短 ⇒ 预算提到规格面上。
+     */
+    retryDelays?: readonly number[];
+    /**
+     * 绑上后 `server.unref()`（缺省 `false` = server 维持事件循环存活，**其余三面行为不变**）。
+     *
+     * 面 C（微信发送，`FACE_PORTS.weixinSend.defaultEnabled = true`）必须传 `true`：宿主若以
+     * **一次性命令**方式跑（`dsh <cmd>` 用完即退），未 unref 的 listener 会拖着进程不退出。
+     * 这是 C4 之前 `weixin-send-api.ts` 的原语义（C4 归一到面宿主时丢失），现逐字恢复。
+     */
+    unref?: boolean;
+}
+/** 一个在监听的面 */
+export interface FaceHandle {
+    readonly name: string;
+    /** **实际**绑定端口（`spec.port=0` 时为内核分配值） */
+    readonly port: number;
+    readonly host: string;
+    /** 原始 http server——面若需挂自己的 server 级事件（gateway 的 `'upgrade'`）在此挂 */
+    readonly server: Server;
+    /** 停止本面（幂等；只停这一实例，不会误停同名后继实例） */
+    dispose: () => void;
+}
+/** 启动被取消（拆卸发生在重试窗口内）——不是失败，调用方按"未启动"处理 */
+export declare class FaceStartCancelled extends Error {
+    constructor(name: string);
+}
+/** 面是否在监听 */
+export declare function faceActive(name: string): boolean;
+/** 面的实际监听端口（未在监听 → null） */
+export declare function facePort(name: string): number | null;
+/** 当前在监听的面名（日志/诊断/测试；顺序 = 启动顺序） */
+export declare function activeFaceNames(): string[];
+/**
+ * **机械启动**一个面（同名面已在监听 → 先停后起；正在启动中 → 复用同一 Promise）。
+ * 绑不上（非端口占用类的错误、或占用重试耗尽）→ **reject**，由调用方决定记日志/放弃。
+ */
+export declare function startFace(spec: FaceSpec): Promise<FaceHandle>;
+/**
+ * **意图读取**：该面此刻是否应处于监听状态（`spec.enabled()` 的安全求值——配置源抛错视为"不启用"）。
+ *
+ * 装配层用它替代此前散在各面 sync 里的 `const want = ...` 手写判据；**启动本身不读它**
+ * （`startFace` 是机械入口：调用方保证意图，测试/程序化直启即用）。
+ * 例：微信发送面的 sync = `faceEnabled(spec) ? startFace(spec) : stopWeixinSendApi()`。
+ */
+export declare function faceEnabled(spec: FaceSpec): boolean;
+/** 停止一个面（幂等）。返回"是否真的停了一个在监听的面"（取消在飞启动不计入）。 */
+export declare function stopFace(name: string): boolean;
+/**
+ * 停止**全部**在监听的面 + 取消全部在飞启动。
+ * 这是插件卸载/HMR 拆卸自起 listener 的**唯一入口**（`seams/lifecycle.ts` 的聚合 disposer 调用）。
+ * @returns 实际停掉的面名（顺序 = 启动顺序）
+ */
+export declare function stopAllFaces(): string[];

package/lib/fs-ops.d.ts

@@ -10,7 +10,7 @@
  * 保留 dsp 增强：win32 reveal 用 spawn+unref（explorer GUI 进程退出码不可靠，fire-and-forget）。
  */
 import type { JsonValue } from './json.js';
-export type CcFsAction = 'root' | 'resolve' | 'exists' | 'list' | 'tree' | 'relative' | 'mkdir' | 'rm' | 'mv' | 'cp' | 'touch' | 'append' | 'reveal' | 'info' | 'find';
+type CcFsAction = 'root' | 'resolve' | 'exists' | 'list' | 'tree' | 'relative' | 'mkdir' | 'rm' | 'mv' | 'cp' | 'touch' | 'append' | 'reveal' | 'info' | 'find';
 export declare const CC_FS_ACTIONS: readonly CcFsAction[];
 export interface CcFsArgs {
     action: CcFsAction;
@@ -32,5 +32,6 @@ export interface CcFsArgs {
     /** 对齐 osp：find 最大递归深度（缺省不限） */
     maxDepth?: number;
 }
-export type CcFsResult = JsonValue;
+type CcFsResult = JsonValue;
 export declare function runCcFs(root: string, args: CcFsArgs): CcFsResult;
+export {};

package/lib/gateway-auth.d.ts

@@ -37,7 +37,7 @@ export declare const FAIL_LOCK_THRESHOLD = 5;
 export declare const FAIL_LOCK_BASE_MS: number;
 /** 锁定时长指数退避上限 */
 export declare const FAIL_LOCK_MAX_MS: number;
-export interface FailState {
+interface FailState {
     /** 连续失败计数（成功登录后清零） */
     count: number;
     /** 当前锁定截止时间（0 = 未锁定） */
@@ -55,10 +55,6 @@ export declare function isAccountLocked(user: string): boolean;
 export declare function recordLoginFailure(user: string): number;
 /** 剩余锁定毫秒（0 = 未锁定） */
 export declare function accountLockRemaining(user: string): number;
-/** CSRF token 有效期（毫秒）：10 分钟窗口（扫码/多标签场景留足时间） */
-export declare const CSRF_TTL_MS: number;
-/** CSRF token 集合上限（防内存膨胀；超限清理最旧） */
-export declare const CSRF_MAX_TOKENS = 50;
 /** 生成 CSRF token（随机 32B hex）并入集合 */
 export declare function newCsrfToken(): string;
 /** token 是否有效（在集合且未过期；过期自动清理） */
@@ -87,3 +83,4 @@ export declare function cookieValue(header: string | undefined, name: string): s
  * @param csrf - CSRF token（隐藏字段随表单双提交；无 = 旧调用方兼容）
  */
 export declare function loginPageHtml(extra: string, csrf?: string): string;
+export {};

package/lib/gateway.d.ts

@@ -26,7 +26,6 @@
  * 保持既有 import 面兼容（tests/gateway.test.ts 直接 import 两模块导出）。
  */
 import type { Context } from 'cordis';
-import { type Server } from 'node:http';
 export { RANDOM_UUID_POLYFILL, injectPolyfillHtml, filterWorkspaceList, workspaceAllowed, workspaceDenyResponse, isWorkspaceCreatePath, parseWorkspaceCreateBody, buildProxyHeaders, transformHtmlForProxy, } from './gateway-proxy.js';
 export { loginPageHtml, verifyGatewayLogin, SESSION_TTL_MS, issueToken, revokeToken, validateToken, FAIL_LOCK_THRESHOLD, FAIL_LOCK_BASE_MS, FAIL_LOCK_MAX_MS, getFailState, resetFailState, isAccountLocked, recordLoginFailure, accountLockRemaining, newCsrfToken, isCsrfValid, csrfFromRequest, safeEqual, originAllowed, cookieValue, } from './gateway-auth.js';
 declare module 'cordis' {
@@ -37,39 +36,6 @@ declare module 'cordis' {
         'serenity/settings-changed'(): void;
     }
 }
-export interface GatewayConfig {
-    host: string;
-    port: number;
-    /** 登录态 cookie 名 */
-    cookieName: string;
-    /** 主端口（ctx.webServer.port） */
-    mainPort: number;
-    /** 登录失败后的重定向延迟（秒） */
-    loginDelayMs: number;
-    /** 外部可访问的工作区路径前缀白名单（v1.22；空 = 全部允许） */
-    allowWorkspaces?: string[];
-    /** Cookie Secure 属性（v1.22.4；反代 TLS 时开启；明文 HTTP 下必须关，否则 cookie 不落） */
-    cookieSecure?: boolean;
-    /** 允许外部新建工作区（v1.22.4；false = workspace.create 一律 403 RPC error） */
-    allowWorkspaceCreate?: boolean;
-    /** 启用 Authenticator 第二因素（v1.22.4；false = TOTP 完全禁用） */
-    totpEnabled?: boolean;
-}
-/**
- * 启动第二监听器。返回 { server, dispose }——dispose 关 server（**不清 token**：
- * token 模块级，进程重启自然清空；热重建清 token → 已登录用户 WS 断 + 重连 cookie 无效）。
- * @param config - 监听/代理配置。
- * @param getAccounts - 运行时读取账号列表（plugin 全局文件；gateway.enabled 开关在调用方判）。
- */
-export declare function startGateway(config: GatewayConfig, getAccounts: () => readonly {
-    id: string;
-    user: string;
-    passHash: string;
-    totpSecret?: string;
-}[], getDshCookie?: () => string | undefined): {
-    server: Server;
-    dispose: () => void;
-};
 /** 注册 gateway（index.ts apply 调用）。
  * 归属原则（v1.22）：gateway 是 plugin 全局能力——enabled 开关读 DSH settings
  * （readSimpleSettings().gatewayEnabled），host/port/accounts 读 plugin 全局文件

package/lib/git-ops.d.ts

@@ -11,9 +11,9 @@
  * 保留 dsp 增强：localstore git 合规联动（S134：deny 且 .gitignore 未覆盖 → status 提示 / commit 拒绝）。
  */
 import type { JsonValue } from './json.js';
-export type GitAction = 'status' | 'commit' | 'push' | 'log' | 'pull' | 'diff';
+type GitAction = 'status' | 'commit' | 'push' | 'log' | 'pull' | 'diff';
 export declare const GIT_ACTIONS: readonly GitAction[];
-export interface GitArgs {
+interface GitArgs {
     action: GitAction;
     message?: string;
     /** log 条数（对齐 osp 参数 n，默认 10，max 100） */
@@ -26,3 +26,4 @@ export interface GitArgs {
     path?: string;
 }
 export declare function runGit(root: string, args: GitArgs): JsonValue;
+export {};

package/lib/handyman-ops.d.ts

@@ -5,7 +5,7 @@
  * 进度文件（handyman-<label>.md/.json）、续跑、轮次 prompt 结构、stop token。
  * 不兼容旧 loop- 进度文件（用户拍板：仅新 handyman- 前缀）。
  */
-export interface HandymanProgress {
+interface HandymanProgress {
     round: number;
     done: boolean;
     label: string;
@@ -56,7 +56,7 @@ export declare function buildRoundPrompt(opts: {
  */
 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";
 /** handyman 运行状态（进度文件摘要；WebUI 等待界面数据源） */
-export interface HandymanRunInfo {
+interface HandymanRunInfo {
     label: string;
     round: number;
     done: boolean;
@@ -66,3 +66,4 @@ export interface HandymanRunInfo {
 }
 /** 列出 AGENT_SESSIONS/handyman-*.json 的全部进度（按 updated 倒序；坏文件跳过） */
 export declare function listActiveHandymen(root: string): HandymanRunInfo[];
+export {};

package/lib/handyman-preset-inherit.d.ts

@@ -20,7 +20,7 @@
  */
 import type { Context } from 'cordis';
 /** 从父 agent ctx 解析 preset 继承的创建期组合。 */
-export interface HandymanPresetInheritance {
+interface HandymanPresetInheritance {
     /** 父 agent 的 preset id（写入子 session meta.agentPreset，供持久化重建）；无则不写。 */
     readonly agentPreset?: string;
     /** 创建 setup 钩子：子 scope join 父的 standing preset + deny handyman 工具；无 preset 继承时仅 deny。 */
@@ -32,3 +32,4 @@ export interface HandymanPresetInheritance {
  * @returns 继承结果：meta 用的 agentPreset 与创建 setup 钩子。
  */
 export declare function handymanPresetInheritance(parentCtx: Context | undefined): HandymanPresetInheritance;
+export {};

package/lib/host/access.d.ts

@@ -33,7 +33,7 @@ export declare function hostService<T = unknown>(ctx: unknown, name: string): T
  * （宿主对插件 apply 抛错 = 整个 dsh 启动失败）。读取失败 = 服务不可用，等价于缺失。
  */
 export declare function hostInjected<T = unknown>(ctx: unknown, name: string): T | undefined;
-export interface HostSessionLike {
+interface HostSessionLike {
     id?: string;
     header?: {
         cwd?: string;
@@ -41,25 +41,25 @@ export interface HostSessionLike {
     };
     snapshotEvents?: () => unknown[];
 }
-export interface HostSessions {
+interface HostSessions {
     list?: () => HostSessionLike[];
     get?: (id: unknown) => HostSessionLike | undefined;
     create?: (...args: unknown[]) => unknown;
 }
-export interface HostAgents {
+interface HostAgents {
     create?: (...args: unknown[]) => unknown;
     get?: (id: string) => unknown;
     resume?: (...args: unknown[]) => unknown;
 }
-export interface HostWebServer {
+interface HostWebServer {
     register?: (registration: unknown) => unknown;
     port?: number;
 }
-export interface HostSettings {
+interface HostSettings {
     installSection?: (...args: unknown[]) => unknown;
 }
 /** `ctx.web`（injected；v1.30.12：fetch provider 注册通道） */
-export interface HostWeb {
+interface HostWeb {
     registerFetchProvider?: (provider: unknown) => unknown;
     registerSearchProvider?: (provider: unknown) => unknown;
 }
@@ -82,9 +82,10 @@ export declare function hostWeb(ctx: unknown): HostWeb | undefined;
  * 注（v1.31.4）：本服务**不在** dsp 的 `inject` 列表内，因此走 `hostInjected` 的
  * 回落分支（`ctx.get`）——见 `hostInjected` 的 v1.31.4 说明与真实 cordis 用例。
  */
-export interface HostSubagents {
+interface HostSubagents {
     start?: (name: string, request: unknown) => Promise<unknown>;
 }
 export declare function hostSubagents(ctx: unknown): HostSubagents | undefined;
 /** 会话 cwd 列表（live 会话；形状不符时返回空数组而非抛错） */
 export declare function hostSessionCwds(ctx: unknown): string[];
+export {};

package/lib/host/contract.d.ts

@@ -19,12 +19,12 @@
  *    宿主类型断言），此处只登记清单供文档/测试共用。
  *  - **缺失分级**：`required` = 缺失即 ACC 核心能力失效；否则为可降级能力。
  */
-export type HostAccess = 'injected' | 'lazy';
-export interface HostMember {
+type HostAccess = 'injected' | 'lazy';
+interface HostMember {
     name: string;
     kind: 'function' | 'value';
 }
-export interface HostServiceContract {
+interface HostServiceContract {
     /** 稳定标识（报告用） */
     id: string;
     /** 服务名（`ctx.get(name)` 或 `ctx.<name>`） */
@@ -40,7 +40,7 @@ export interface HostServiceContract {
 }
 /** dsp 依赖的宿主服务与成员（对照 `_tmp/host-0.1.5-rc.1/`（`dsh-develop host-fetch` 产物）逐一核对） */
 export declare const HOST_SERVICES: readonly HostServiceContract[];
-export interface HostEventContract {
+interface HostEventContract {
     name: HostEventName;
     /** 订阅方（文件） */
     site: string;
@@ -56,14 +56,14 @@ export interface HostEventContract {
  * 该 import 为 type-only，编译期擦除，不产生运行时依赖。
  */
 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];
+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.5-rc.2";
-export interface HostContractIssue {
+interface HostContractIssue {
     id: string;
     kind: 'service' | 'member' | 'version';
     detail: string;
@@ -100,5 +100,16 @@ export declare function checkHostVersion(version: string | null): {
  * @returns 报告（`ok:false` 时 `issues` 逐条给出缺失项与后果）
  */
 export declare function probeHostContract(ctx: unknown, hostVersion?: string | null): HostContractReport;
+/**
+ * 取宿主契约报告——**进程内唯一来源**。
+ *
+ * @param ctx 宿主上下文；**仅当快照尚未捕获时**用于跑探针（首见即捕获一次）
+ * @param hostVersion 运行中宿主版本（`readDshVersion()`；null = 未知）
+ * @returns 契约报告；快照未捕获且未给 `ctx` → `null`（不猜、不重算）
+ */
+export declare function hostContractReport(ctx?: unknown, hostVersion?: string | null): HostContractReport | null;
+/** 测试用：复位进程内快照（避免用例间串味；与 `__resetWakeSchedulerStateForTest` 同规格） */
+export declare function __resetHostContractForTest(): void;
 /** 单行摘要（启动告警用） */
 export declare function summarizeHostContract(report: HostContractReport): string;
+export {};

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

@@ -40,5 +40,4 @@
  *
  * 注：本文件**没有任何运行时语句**，编译产物只有 `export {}`，不影响包体行为。
  */
-/** 哨兵：确保本模块不是空文件被 tree-shake 掉（无运行时副作用，值为类型） */
-export type HostTypeContractSatisfied = true;
+export {};

package/lib/im-bridge.d.ts

@@ -32,7 +32,7 @@ export type ImUserEntry = {
     id: string;
 };
 /** 文本发送输入（通道实现负责凭据解析与记录） */
-export interface ImSendInput {
+interface ImSendInput {
     root: string;
     /** 通道内用户 id（别名已由本模块解析） */
     userId: string;
@@ -40,14 +40,14 @@ export interface ImSendInput {
     accountId?: string;
 }
 /** 文本发送结果（与既有主动发送返回一致，便于记录/诊断） */
-export interface ImSendResult {
+interface ImSendResult {
     accountId: string;
     userId: string;
     sessionId: string;
     role: string;
 }
 /** 文件发送输入（`data` 由本模块读盘并校验后传入——通道不碰 CCC 路径） */
-export interface ImSendFileInput {
+interface ImSendFileInput {
     root: string;
     userId: string;
     data: Buffer;
@@ -95,7 +95,7 @@ export type ImJson = null | boolean | number | string | ImJson[] | {
     [key: string]: ImJson;
 };
 /** 分发结果（工具面直接渲染；错误码稳定，便于模型与日志消费） */
-export type ImToolResult = {
+type ImToolResult = {
     ok: true;
     channel: string;
     action: string;
@@ -106,7 +106,7 @@ export type ImToolResult = {
     error: string;
     remediation?: string;
 };
-export interface ImToolRequest {
+interface ImToolRequest {
     channel?: string;
     action?: string;
     user?: string;
@@ -125,3 +125,4 @@ export interface ImToolRequest {
  * @param req 工具参数
  */
 export declare function runImBridge(root: string, req: ImToolRequest): Promise<ImToolResult>;
+export {};

package/lib/index.d.ts

@@ -4,7 +4,7 @@
  * 形态（DSH 官方 native hook 约定）：name / inject / Config / apply，无 default export。
  *
  * 能力：
- *   1. 真实 DSH 工具注册：container_fs（文件系统 15 子命令，含 reveal）、logbook（会话全周期含 rebuild）
+ *   1. 真实 DSH 工具注册：container_fs（文件系统 15 子命令，含 reveal）、container_trajectory（轨迹生命周期 + 一次性安排，含 rebuild）
  *   2. 拦截缝机械约束：tools/pre-execute + ctx.tools.guard（安全模式/黑名单/路径守卫）
  *
  * 加载：~/.dsh/config.yaml 加 insert 行（免改 DSH 源码），插件包装入 DSH node_modules。