fix(runtime): ship adapter-refresh guidance with MCP runtime deps

Deploy global-adapter-refresh-guidance alongside host-parity-scorecard and
soft-require it so partial runtimes no longer throw MODULE_NOT_FOUND.

Author: rockyshi1993

changelogs/unreleased.md

@@ -7,6 +7,7 @@
 
 - **GlobalOnly 全局 adapter 本地刷新 CLI（R1a）**：新增 `devcodex global-adapters apply [--dry-run] [--json]` 与 `npm run global-adapters:apply*`，从当前包根复用 `applyGlobalHostConfig` 刷新用户级五宿主 adapter（不 pack/不 publish）。nextStep/PC5/audit/V8/doctor/help/website intro 按源码 vs 已发布分流；次选 R1b `npm install -g .`、R2 pack+tarball、R3 `npm update -g`；bare `devcodex update` 仅 workspace。`package.json` files 已纳入 `global-adapters-cli` / guidance 模块，避免 pack 后 require 断裂。**Profile 01/02/04/05/06/07 已同步 R1a~R4**（PI-173）。任务：`bugs/GlobalOnly刷全局副本命令口径漂移修复`。
 - **R1a 复审收口**：`host-parity-scorecard` repairSteps / recommendedEntry / userVisibleSummary 接入 `describeGlobalAdapterRefresh*`（源码 → `global-adapters apply`，已发布 → `npm -g`）；`global-adapters apply` 在主机事务已提交但 Grok 集成失败时返回 `GLOBAL_ADAPTERS_HOSTS_COMMITTED_GROK_FAILED` + `partialState`；npm pack `files` 不再包含 `test-global-adapters-cli.js`。
+- **MCP runtime dep 防断**：将 `global-adapter-refresh-guidance.js` 纳入 `MCP_RUNTIME_DEPS` / `CLAUDE_MCP_RUNTIME_SCRIPT_DEPS`；`host-parity-scorecard` 对 guidance 模块 soft-require，避免精简 runtime 缺文件时 `MODULE_NOT_FOUND`。
 - **Dialogue-Primary Closeout B1+B2**：新增 `classifyDialogueNarrativeSample` / `hasReadableNarrativeSnippet`；`classifyAnalysisArtifactDeliverySample` 返回 `link-only-thin`；`lifecycle-visible-reply` Stop/PreCompact 有正文时写入 `dialogueNarrativeStatus`/`analysisDeliveryStatus` 并在 dev+reportTouched 时 reminder；无正文仍 unverified。同步 Skill/13-analyze/16-report/prompt/V102/单测。需求：`完成态对话内可读收口` CP2。
 - **文档站依赖审计加固**：Rspress 提升到 2.0.18，`brace-expansion` 提升到 5.0.8；`test:audit` 改为 fail-closed 结构化审计。当前唯一例外为仅影响 unstable RSC 的 `GHSA-qwww-vcr4-c8h2`，本站静态运行面禁止 RSC 标记，例外于 2026-08-15 到期；任何新 advisory、依赖链变化、RSC 使用或到期都会重新阻断。
 - **Grok 兼容导入去重**：Grok 原生会话兼容加载 `~/.claude/settings.json` 时，DevCodex Claude adapter 识别 Grok 的 camelCase payload 与 snake_case 事件并安全跳过重复 lifecycle；Grok 专用 plugin 保持唯一生命周期 owner，消除 `user_prompt_submit` / `stop` hook 报错和双重状态写入。

index.js

@@ -76,6 +76,7 @@ const CLAUDE_SOURCES = [
 const CLAUDE_MCP_RUNTIME_SCRIPT_DEPS = Object.freeze([
   'scripts/lib/cp-digest.js',
   'scripts/lib/host-parity-scorecard.js',
+  'scripts/lib/global-adapter-refresh-guidance.js',
   'scripts/lib/global-host-target.js',
   'scripts/lib/derived-index-contract.js',
   'scripts/lib/memory-index.js',

scripts/lib/global-host-config.js

@@ -34,6 +34,7 @@ const GLOBAL_HOST_RECEIPT_SCHEMA = 'GlobalHostConfigReceiptV1'
 const MCP_RUNTIME_DEPS = Object.freeze([
   'scripts/lib/cp-digest.js',
   'scripts/lib/host-parity-scorecard.js',
+  'scripts/lib/global-adapter-refresh-guidance.js',
   'scripts/lib/global-host-target.js',
   'scripts/lib/derived-index-contract.js',
   'scripts/lib/memory-index.js',

scripts/lib/host-parity-scorecard.js

@@ -10,12 +10,18 @@ const crypto = require('crypto')
 const fs = require('fs')
 const path = require('path')
 const { resolveGlobalHostTarget } = require('./global-host-target.js')
-const {
-  describeGlobalAdapterRefreshForPackageRoot
-} = require('./global-adapter-refresh-guidance.js')
 
 const PACKAGE_ROOT = path.join(__dirname, '..', '..')
 
+function loadAdapterRefreshGuidanceModule() {
+  try {
+    return require('./global-adapter-refresh-guidance.js')
+  } catch {
+    // Deployed MCP runtime subsets may lag one file; fail soft with R3 defaults.
+    return null
+  }
+}
+
 /**
  * Repair command for missing/stale user-global adapters.
  * Source checkout → R1a `devcodex global-adapters apply`; published package → npm -g.
@@ -25,10 +31,22 @@ function resolveAdapterRefreshGuidance(options = {}) {
   const packageRoot = options.packageRoot
     ? path.resolve(options.packageRoot)
     : PACKAGE_ROOT
-  return describeGlobalAdapterRefreshForPackageRoot(packageRoot, {
-    packageVersion: options.packageVersion || null,
-    fs: options.fs || fs,
-    path: options.path || path
+  const mod = loadAdapterRefreshGuidanceModule()
+  if (mod && typeof mod.describeGlobalAdapterRefreshForPackageRoot === 'function') {
+    return mod.describeGlobalAdapterRefreshForPackageRoot(packageRoot, {
+      packageVersion: options.packageVersion || null,
+      fs: options.fs || fs,
+      path: options.path || path
+    })
+  }
+  return Object.freeze({
+    sourceCheckout: false,
+    primary: 'npm update -g devcodex',
+    installCommand: 'npm install -g devcodex',
+    updateCommand: 'npm update -g devcodex',
+    nextStepShort: 'npm update -g devcodex',
+    nextStepRefresh: 'Run npm update -g devcodex to refresh the managed receipt.',
+    nextStepInstall: 'Run npm install -g devcodex to create the user-global host receipt.'
   })
 }
 

scripts/test-host-installation.js

@@ -75,6 +75,7 @@ function deploymentOptions() {
     CLAUDE_MCP_RUNTIME_SCRIPT_DEPS: [
       'scripts/lib/cp-digest.js',
       'scripts/lib/host-parity-scorecard.js',
+      'scripts/lib/global-adapter-refresh-guidance.js',
       'scripts/lib/global-host-target.js',
       'scripts/lib/derived-index-contract.js',
       'scripts/lib/memory-index.js',
@@ -657,10 +658,11 @@ const claudeMcpScriptDeps = defaults.filter(item =>
   item.surface === 'claude' &&
   String(item.destination || '').replace(/\\/g, '/').startsWith('.claude/scripts/lib/')
 )
-assert.strictEqual(claudeMcpScriptDeps.length, 6, 'claude descriptors must include MCP scripts/lib runtime deps')
+assert.strictEqual(claudeMcpScriptDeps.length, 7, 'claude descriptors must include MCP scripts/lib runtime deps')
 for (const expected of [
   '.claude/scripts/lib/cp-digest.js',
   '.claude/scripts/lib/host-parity-scorecard.js',
+  '.claude/scripts/lib/global-adapter-refresh-guidance.js',
   '.claude/scripts/lib/global-host-target.js',
   '.claude/scripts/lib/derived-index-contract.js',
   '.claude/scripts/lib/memory-index.js',

scripts/test-mcp-servers.js

@@ -167,6 +167,7 @@ function setupConfiguredMcpTarget() {
   for (const rel of [
     'scripts/lib/cp-digest.js',
     'scripts/lib/host-parity-scorecard.js',
+    'scripts/lib/global-adapter-refresh-guidance.js',
     'scripts/lib/global-host-target.js',
     'scripts/lib/derived-index-contract.js',
     'scripts/lib/memory-index.js',