dsh-config-manager 0.1.69 → 0.1.71

package/src/index.ts

@@ -11,7 +11,8 @@
  *   ctx.plugins            -> PluginsFacade       (官方 dsh plugin CLI 通道 + profile 文件，
  *                                                  见 src/core/plugin-cli.ts)
  *   ctx.workspaceRegistry  -> WorkspaceFacade     (@deepseek-ai/dsh-workspace)
- *   ~/.dsh/cordis.patch.yml-> PatchFileFacade     (js-yaml)
+ *   ~/.dsh/cordis.patch.yml-> PatchFileFacade     (js-yaml; home 层 + profiles/<p>/ 层)
+ *   ctx.skills             -> SkillStoreFacade    (@deepseek-ai/dsh-skill 注册表，技能备份用)
  *   $DSH_HOME files        -> FileSystemFacade    (node:fs, home-relative)
  *   resolveDshHome()       -> homeDir             (@deepseek-ai/dsh-home-paths)
  *
@@ -44,7 +45,7 @@ import { promisify } from 'node:util'
 
 import type { Context } from '@deepseek-ai/cordis'
 import * as dshSettings from '@deepseek-ai/dsh-settings'
-import type { SettingsProvider } from '@deepseek-ai/dsh-settings'
+import type { SettingsDescriptor, SettingsProvider } from '@deepseek-ai/dsh-settings'
 import * as dshCredentials from '@deepseek-ai/dsh-credentials'
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials'
 import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-home-paths'
@@ -77,9 +78,13 @@ import { registerModelTools } from './core/model-tools.ts'
 import { makeMsg, msgOf, zhMsg } from './core/messages.ts'
 import type { MsgFunc } from './core/messages.ts'
 import { cleanupAbortedInstall, hasDshBundlePatch, installAnchorFromProfileContext, installErrorFor, installSpecFor, listInstalledPlugins, profileNameFromProfileContext, resolveProcessProfileName, resolveProfileDir, readProfileManifest, runDshPlugin, validateProfileName } from './core/plugin-cli.ts'
-import type { ConfigAdapter, CredentialsFacade, ExportUnit, FileSystemFacade, HostContext, ImportDecisions, ImportPlan, NamespaceInfo, PatchFileFacade, PlanItemKind, PluginInfo, PluginsFacade, SessionMoveResult, SessionParentRelation, SessionRewriteResult, SessionStoreFacade, SettingsFacade, WorkspaceFacade } from './core/types.ts'
+import type { ConfigAdapter, CredentialsFacade, ExportUnit, FileSystemFacade, HostContext, ImportDecisions, ImportPlan, NamedNamespaceInfo, NamespaceInfo, PatchFileFacade, PlanItemKind, PluginInfo, PluginsFacade, SessionMoveResult, SessionParentRelation, SessionRewriteResult, SessionStoreFacade, SettingsFacade, SkillDefinitionView, SkillStoreFacade, SkillSummaryView, WorkspaceFacade } from './core/types.ts'
 import { ImportUserSkippedError } from './core/types.ts'
-import { createAdapters, USER_PATCH_FILE } from './adapters/index.ts'
+import { PLUGIN_NPM_PACKAGE } from './core/update-check.ts'
+import { planSelfUpdate, runSelfUpdate } from './core/self-update.ts'
+import type { SelfUpdateOutcome } from './core/self-update.ts'
+import { createAdapters } from './adapters/index.ts'
+import { isPatchLayerRel, profilePatchRel, readEffectivePatchLines, USER_PATCH_FILE } from './core/patch-layers.ts'
 import { createLocalPluginPackHook } from './core/local-plugin-host.ts'
 import { ENCRYPTED_CONTAINER_CODE, createEncryptionProvider, decryptCredentials, readContainerKind, SecurityError, encryptArchive } from './security/index.ts'
 import { createHardenedZipParser } from './security/zip-security.ts'
@@ -88,7 +93,9 @@ import { applySessionMeta, applySessionMetaToPlanItems, applySessionParentLinks,
 import { projectKeyOf, sessionIdKey } from './core/session-select.ts'
 import { PROJECT_KEY_RE, readLogCwdFromBytes, rewriteSessionLogDir } from './utils/session-log.ts'
 import { probeSessionFormats, resolveSessionFormatVersion } from './utils/session-format.ts'
+import { describePatchYamlError, dumpPatchDocument, loadPatchDocument } from './utils/patch-yaml.ts'
 import { atomicCopyFile, atomicWriteFile } from './utils/atomic-write.ts'
+import { isENOENT } from './utils/guards.ts'
 import { EnvironmentLockManager, runWithMutationLock, EnvironmentLockUnavailableError, type MutationLockContext } from './utils/env-lock.ts'
 import { activeProxySummary } from './utils/proxy.ts'
 import { listRecursiveFollowingLinks } from './utils/recursive-walk.ts'
@@ -99,6 +106,8 @@ import type { MutationLockPort } from './utils/env-lock.ts'
 import type { RecursiveListing } from './utils/recursive-walk.ts'
 import { GitTransport } from './sync/git/git-transport.ts'
 import { WebDavTransport } from './sync/webdav/webdav-transport.ts'
+import { S3Transport } from './sync/s3/s3-transport.ts'
+import { GistTransport } from './sync/gist/gist-transport.ts'
 import { DeviceFlowStore, GitHubAuthClient } from './sync/github-auth.ts'
 import { SyncEngine } from './sync/sync-engine.ts'
 import { SyncSessionStore } from './sync/sync-session.ts'
@@ -114,7 +123,7 @@ import { readAllAutosyncConfigs, readAutosyncConfig } from './sync/autosync-conf
 import type { AutosyncInterval, AutosyncRunStatus } from './sync/autosync-config.ts'
 import { appendAutosyncEntry } from './sync/sync-history.ts'
 import { MigrationStore, type MigrationKind, type MigrationResult, MIGRATION_HISTORY_DIR } from './core/migration-history.ts'
-import { readSyncConfig, validateRepoUrl, validateWebDavUrl, isWebDavConfig, channelOf, parseSyncChannel, SYNC_CHANNELS } from './sync/sync-config.ts'
+import { readSyncConfig, validateRepoUrl, validateWebDavUrl, isWebDavConfig, isS3Config, isGistConfig, channelOf, parseSyncChannel, SYNC_CHANNELS, GIST_PROVIDER, isS3CompatProvider, validateCloudChannelInput, cloudSecretRef } from './sync/sync-config.ts'
 import {
   resolveSessionFormatDisposition,
   sessionFormatAbortResponse,
@@ -145,6 +154,7 @@ import { stringifyJsonSafe } from './utils/json.ts'
 import type { Manifest, SectionId, WorkspaceRecord } from './schema/types.ts'
 import { parseZip } from './utils/zip.ts'
 import { isSameOrChild } from './utils/paths.ts'
+import { isRecord } from './utils/guards.ts'
 import { createLogger, parseLogLevel, type Logger } from './utils/logger.ts'
 
 /* ---------------------------------------------------------------- identity */
@@ -156,7 +166,7 @@ export const name = 'config-manager'
 export const inject = ['settings', 'credentials']
 
 /** Plugin version, kept in sync with package.json ("version"). */
-export const PLUGIN_VERSION = '0.1.69'
+export const PLUGIN_VERSION = '0.1.71'
 
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager'
@@ -219,9 +229,9 @@ export interface Config {
 /* ---------------------------------------------------------------- constants */
 
 /**
- * 本文件保留的 8 条路由的路径（被源码级守卫按文件窗口钉住，见下方 routesList 注释）。
+ * 本文件保留的 7 条路由的路径（被源码级守卫按文件窗口钉住，见下方 routesList 注释）。
  *
- * 其余 57 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
+ * 其余 71 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
  * 新增一条 API 只需那一条声明，不再有「常量表 + 路由对象」两处要同步。
  */
 export const API = {
@@ -387,6 +397,69 @@ function readService<T>(ctx: Context, serviceName: string): T | undefined {
   return candidate === null || typeof candidate !== 'object' ? undefined : candidate as T
 }
 
+/**
+ * 把 DSH 的 `skills` 服务（@deepseek-ai/dsh-skill 的 SkillRegistry）适配成引擎的
+ * `SkillStoreFacade`（issue #71）。
+ *
+ * 为什么在这里做适配而不是让 adapter 直接调服务：架构边界测试禁止 core / adapters import
+ * `@deepseek-ai/*`（只有 src/index.ts 与 src/client/ 允许），所以适配层只能是宿主入口。
+ *
+ * 服务缺失（旧外壳）或形状不符 → 返回 undefined（skills 分区退回纯目录扫描，不报错）；
+ * 单个方法的异常不在这里吞 —— 由 adapter 决定「这一个技能跳过」还是「整路跳过」。
+ */
+function resolveSkillStore(ctx: Context): SkillStoreFacade | undefined {
+  const service = readService<{
+    list?: (options?: unknown) => Promise<unknown>
+    get?: (name: string, options?: unknown) => Promise<unknown>
+  }>(ctx, 'skills')
+  if (service === undefined || typeof service.list !== 'function' || typeof service.get !== 'function') {
+    return undefined
+  }
+  return {
+    // 不传 scope：外壳自身的技能 provider 都在 global 层（插件 apply 时注册、无 scope），
+    // 传 scope 反而会丢掉它们。范围参数只在调用方明确要「某次会话/某个 preset 的视图」时才需要。
+    async list(): Promise<SkillSummaryView[]> {
+      const raw = await service.list?.({})
+      if (!Array.isArray(raw)) return []
+      const out: SkillSummaryView[] = []
+      for (const item of raw) {
+        if (item === null || typeof item !== 'object') continue
+        const summary = item as Record<string, unknown>
+        if (typeof summary['name'] !== 'string') continue
+        out.push(toSkillSummaryView(summary))
+      }
+      return out
+    },
+    async get(name: string): Promise<SkillDefinitionView | undefined> {
+      const raw = await service.get?.(name, {})
+      if (raw === null || typeof raw !== 'object') return undefined
+      const definition = raw as Record<string, unknown>
+      if (typeof definition['name'] !== 'string' || typeof definition['content'] !== 'string') return undefined
+      return { ...toSkillSummaryView(definition), content: definition['content'] }
+    },
+  }
+}
+
+/** 技能摘要的结构适配（只取引擎声明过的字段；多余字段不落地，避免快照体积被未知字段撑大）。 */
+function toSkillSummaryView(source: Record<string, unknown>): SkillSummaryView {
+  const out: SkillSummaryView = {
+    name: source['name'] as string,
+    description: typeof source['description'] === 'string' ? source['description'] : '',
+  }
+  if (typeof source['whenToUse'] === 'string') out.whenToUse = source['whenToUse']
+  if (typeof source['source'] === 'string') out.source = source['source']
+  if (typeof source['provider'] === 'string') out.provider = source['provider']
+  const invocation = source['invocation']
+  if (invocation !== null && typeof invocation === 'object') {
+    const policy = invocation as Record<string, unknown>
+    const view: { modelInvocable?: boolean; userInvocable?: boolean } = {}
+    if (typeof policy['modelInvocable'] === 'boolean') view.modelInvocable = policy['modelInvocable']
+    if (typeof policy['userInvocable'] === 'boolean') view.userInvocable = policy['userInvocable']
+    out.invocation = view
+  }
+  return out
+}
+
 /** Safe settings namespace converter compatible across DSH 0.1.1 and 0.1.2-alpha.x */
 const SETTINGS_NAMESPACE_REGEX = /^[a-z][a-z0-9-]*$/
 function safeSettingsNamespace(namespace: string): any {
@@ -427,10 +500,8 @@ class DshSettingsFacade implements SettingsFacade {
     return this.ctx.settings
   }
 
-  async describe(namespace: string, opts?: { redactSecrets?: boolean }): Promise<NamespaceInfo> {
-    const all = this.provider().describe({ redactSecrets: opts?.redactSecrets ?? true })
-    const descriptor = all.find((d) => String(d.ns) === namespace)
-    if (!descriptor) throw new Error(`namespace not found: ${namespace}`)
+  /** DSH 描述符 → 核心 NamespaceInfo（describe/describeAll 共用，保证两条路径逐字段同口径） */
+  private toNamespaceInfo(descriptor: SettingsDescriptor): NamespaceInfo {
     return {
       value: descriptor.value,
       base: descriptor.base,
@@ -441,6 +512,25 @@ class DshSettingsFacade implements SettingsFacade {
     }
   }
 
+  async describe(namespace: string, opts?: { redactSecrets?: boolean }): Promise<NamespaceInfo> {
+    const found = (await this.describeAll(opts)).find((d) => d.ns === namespace)
+    if (!found) throw new Error(`namespace not found: ${namespace}`)
+    return found.info
+  }
+
+  /**
+   * 一次读回全部已注册 namespace。
+   *
+   * 真实服务侧 describe() 是「无参 = 全量」的：每次调用都对全部注册项重跑
+   * schema.toJSON + structuredClone + redactSecrets。逐名调用因此是 O(N²)
+   * （真机 24 个 namespace ≈1.7 s），调用方改用本方法后只需一次全量（≈70 ms）。
+   */
+  async describeAll(opts?: { redactSecrets?: boolean }): Promise<NamedNamespaceInfo[]> {
+    return this.provider()
+      .describe({ redactSecrets: opts?.redactSecrets ?? true })
+      .map((descriptor) => ({ ns: String(descriptor.ns), info: this.toNamespaceInfo(descriptor) }))
+  }
+
   async replace(namespace: string, value: unknown, expectedRevision?: number): Promise<void> {
     await this.provider().replace(safeSettingsNamespace(namespace), value as object, expectedRevision)
   }
@@ -489,13 +579,24 @@ export function patchRowActivates(raw: unknown, name: string): boolean {
  * 非 bundle 插件安装成功后，幂等补 profile cordis.patch.yml 激活行
  * （{id: pm-<slug>, name: <pkg>}，仿 marketplace ensureRow）。bundle 包不写行
  * （CLI 的 reconcile 已维护 dsh.profile.bundles）。
+ *
+ * 第 4 参 `profile`（issue #71）：patch 的层身份是**相对 homeDir 的路径**，
+ * 目标层 = `profiles/<profile>/cordis.patch.yml`。省略时按缺省档案名（web）—— 兼容旧调用方。
  */
-export async function ensureActivationRow(patchFile: PatchFileFacade, pkgDir: string, pkg: string): Promise<void> {
+export async function ensureActivationRow(
+  patchFile: PatchFileFacade,
+  pkgDir: string,
+  pkg: string,
+  profile?: string,
+): Promise<void> {
   if (hasDshBundlePatch(pkgDir)) return
-  const lines = await patchFile.readPatchLines(PROFILE_PATCH_FILE)
-  if (lines.some((l) => patchRowActivates(l.raw, pkg))) return
+  const file = profilePatchRel(profile)
+  // 幂等判定要看**两层**：home 层里的激活行同样会让 DSH 加载这个包（home 层合并在后、优先级更高），
+  // 只看目标层会在「用户已手工激活过」时多写一行重复激活。
+  const effective = await readEffectivePatchLines(patchFile, profile)
+  if (effective.lines.some((l) => patchRowActivates(l.raw, pkg))) return
   const id = `pm-${slugOf(pkg)}`
-  await patchFile.applyPatchChanges(PROFILE_PATCH_FILE, [
+  await patchFile.applyPatchChanges(file, [
     { lineId: id, raw: { id, name: pkg }, action: 'insert' },
   ])
 }
@@ -549,7 +650,7 @@ export class DshPluginsFacade implements PluginsFacade {
     // 非 bundle 插件：CLI 只维护 bundles，需补 profile patch 激活行才能加载。
     // 补写失败不吞：包已装但未激活，明确报错并允许重试（幂等补行）。
     try {
-      await ensureActivationRow(this.patchFile, join(profileDir, 'node_modules', pkg), pkg)
+      await ensureActivationRow(this.patchFile, join(profileDir, 'node_modules', pkg), pkg, this.profile)
     } catch (error) {
       const reason = error instanceof Error ? error.message : String(error)
       throw new Error(this.msg('host.activationRowFailed', { pkg, reason }))
@@ -624,12 +725,93 @@ class DshWorkspaceFacade implements WorkspaceFacade {
 // 字节级工具（projectKey 形状 / 首帧 cwd 读写 / 多 generation 改写）已抽到 utils/session-log.ts：
 // 宿主在线路径与 CLI 离线修复共用同一份实现（避免两处口径漂移）。
 
+/* --------------------------------------------- 会话存储读侧兼容（F-1） */
+
+/**
+ * 宿主 `sessionPersistence` 的 API 形状（**按 API 形状探测，绝不按 DSH 版本号猜**）。
+ *
+ * 为什么必须探测：DSH 的会话存储换过基线 —— 新基线有 `open()`（handle 形态，`list()` 的元素是
+ * 带 `header` 的 snapshot 对象），旧基线只有服务级的 `readFrom()` / `append()`（header 字段
+ * **平铺在元素上**）。本插件只读 `list()` 的结果，而两种形状里 header 的位置不同。
+ *
+ * 真机事故级的后果（F-1）：按写死的形状读，在另一种宿主上「一个都匹配不上」——
+ * `reindexSessionHeader` 恒 false、`parentRelations` 退化成**空 Map**（而空 Map 还会进 5 s 的
+ * TTL 缓存），于是「导出子代理会话时连带父对话」这条已经修好的能力在旧宿主上**静默失效**。
+ * 参照竞品 dsh-claude-move 的 isSessionHandle / storedSessionIdOf（index.mjs:88-154）。
+ */
+export type SessionPersistenceShape = 'handle' | 'legacy' | 'unknown'
+
+/** 会话存储**列举**接口的最小形状（两种基线都有 `list()`；本插件只读它，不写会话）。 */
+export interface SessionListService {
+  list(): Promise<readonly unknown[]>
+}
+
+/** 按 API 形状探测会话存储基线：有 `open` → handle；只有 `readFrom`/`append` → legacy；都没有 → unknown。 */
+export function sessionPersistenceShapeOf(service: unknown): SessionPersistenceShape {
+  if (!isRecord(service)) return 'unknown'
+  if (typeof service['open'] === 'function') return 'handle'
+  if (typeof service['readFrom'] === 'function' || typeof service['append'] === 'function') return 'legacy'
+  return 'unknown'
+}
+
+/** 归一后的列举元素 header 视图（只含本插件用到的字段）。 */
+export interface ListedSessionView {
+  id: string
+  /** 父会话 id（磁盘 header 名 `parentSession`；DSH 的 RPC 投影名 `parentSessionId` 一并认） */
+  parent?: string
+  /** header.origin（'subagent' = 子代理会话）——原样保留，不在这里做筛选 */
+  origin: unknown
+  /**
+   * **原样的 header 对象**（handle 形态 = `element.header`；legacy 形态 = 元素自身）。
+   * 回传给 DSH `WorkspaceRegistry.indexHeader()` 时必须用它 —— 绝不自己造一个 header。
+   */
+  raw: unknown
+}
+
+/**
+ * 把一个列举元素归一成 header 视图（**两种基线形状都认**）。
+ *
+ * 认不出 id → undefined：这是「读侧兼容失败」的唯一信号，调用方必须**响亮处理**
+ * （记日志 / 抛错），绝不当成「本机没有会话」。
+ */
+export function normalizeListedSession(element: unknown): ListedSessionView | undefined {
+  if (!isRecord(element)) return undefined
+  const nested = isRecord(element['header']) ? element['header'] : undefined
+  // handle 形态 = header 在 element.header；legacy 形态 = header 字段平铺在元素上。
+  // header 存在但取不出 id 时回落元素自身（两种都取不到才算解析失败 —— 不猜）。
+  const source = nested !== undefined && typeof nested['id'] === 'string' && nested['id'] !== '' ? nested : element
+  const id = source['id']
+  if (typeof id !== 'string' || id === '') return undefined
+  const rawParent = source['parentSession'] ?? source['parentSessionId']
+  const parent = typeof rawParent === 'string' && rawParent !== '' ? rawParent : undefined
+  return { id, origin: source['origin'], raw: source, ...(parent !== undefined ? { parent } : {}) }
+}
+
+/** 会话存储列举的结果（失败必须可区分，绝不与「本机没有会话」混淆）。 */
+type ListedSessions =
+  | { ok: true; items: readonly ListedSessionView[] }
+  /** unavailable = 服务/接口不可用（list 抛错或返回非数组）；shape-unknown = 元素形状一个都认不出 */
+  | { ok: false; reason: 'unavailable' | 'shape-unknown'; detail: string }
+
+/** 列举会话存储的用途（内部枚举；渲染时必须经字典键映射 —— **绝不把裸枚举塞进文案**）。 */
+type SessionStorePurpose = 'reindexSessionHeader' | 'parentRelations'
+
+/** 用途 → 字典键（本仓纪律：文案只做「原因 → 字典键」映射，禁止渲染裸枚举）。 */
+const SESSION_STORE_PURPOSE_KEY: Record<SessionStorePurpose, string> = {
+  reindexSessionHeader: 'host.sessionStorePurposeReindex',
+  parentRelations: 'host.sessionStorePurposeParentRelations',
+}
+
 /**
  * 父子关系缓存的 TTL（毫秒）。
  *
  * 取值依据：`sessionPersistence.list()` 在真机上约 **0.7 s**，而 `/export-preview` 每次都要它；
  * 父子关系只在「有新子代理会话」时变化，几秒陈旧对选择器的「勾父带子 / 勾子带父」联动毫无影响。
  * 取 5 s：连续打开/刷新选择器都在同一窗口内命中，同时保证新会话最多 5 s 后就能被联动识别。
+ *
+ * F-1：缓存里只放**成功结果** —— 列举失败/形状识别失败走 `parentRelations()` 的抛错路径，
+ * 由 ttl-cache 的「失败不缓存」语义保证下一次调用立刻重试；
+ * 不再把失败吞成空 Map（那会被缓存整整 5 s，正是「静默失效」的放大器）。
  */
 const PARENT_RELATIONS_CACHE_TTL_MS = 5_000
 
@@ -639,16 +821,25 @@ export class DshSessionStoreFacade implements SessionStoreFacade {
   private readonly root: string
   /**
    * 父子关系的短 TTL 缓存（见 `PARENT_RELATIONS_CACHE_TTL_MS`；同 key 并发合并成一次列举）。
-   * `parentRelations()` 把「列举失败」收成空 Map —— 那个空 Map 会进缓存 TTL（5 s），
-   * 对一个已经坏掉的服务连打不划算，且 5 s 后自然重试。
+   * F-1 后**只缓存成功结果**：列举失败/形状识别失败会让 `parentRelations()` 抛错，
+   * 而 ttl-cache 的语义是「失败不缓存」→ 下一次调用立刻重试（行为见 utils/ttl-cache.ts）。
    */
   private readonly parentRelationsCache = createTtlAsyncCache<Map<string, SessionParentRelation>>({
     ttlMs: PARENT_RELATIONS_CACHE_TTL_MS,
   })
+  /**
+   * 宿主日志（F-1）：会话存储的形状异常/列举异常必须**响亮**（绝不退化成空结果），
+   * 缺省不注入时用一个只输出 warn/error 的本地记录器（测试构造三参即可，行为不变）。
+   */
+  private readonly log: Logger
+  /** 文案翻译器（F-1 的形状异常诊断走字典，禁止硬编码用户可见字符串） */
+  private readonly msgFunc: MsgFunc
 
-  constructor(ctx: Context, homeDir: string, msg: MsgFunc = zhMsg) {
+  constructor(ctx: Context, homeDir: string, msg: MsgFunc = zhMsg, log?: Logger) {
     this.ctx = ctx
     this.root = join(homeDir, 'sessions')
+    this.log = log ?? createLogger({ level: 'warn' })
+    this.msgFunc = msg
   }
 
   /**
@@ -744,26 +935,101 @@ export class DshSessionStoreFacade implements SessionStoreFacade {
   async reindexSessionHeader(sessionId: string): Promise<boolean> {
     const registry = readService<{ indexHeader?: (header: unknown) => unknown }>(this.ctx, 'workspaceRegistry')
     // 会话存储服务：只用来取出该会话的最新 header（注册表内存里的那份可能已被改写作废）
-    const store = readService<{ list(): Promise<readonly { header?: { id?: unknown } }[]> }>(this.ctx, 'sessionPersistence')
+    const store = readService<SessionListService>(this.ctx, 'sessionPersistence')
     if (registry === undefined || typeof registry.indexHeader !== 'function' || store === undefined) return false
+    // F-1：按**形状**归一列举元素（handle / legacy 两种基线都认），不写死 element.header.id
+    const listed = await this.listSessionElements(store, 'reindexSessionHeader')
+    if (!listed.ok) {
+      // T8（F-1 收尾）：失败原因必须**可观测** —— 只返回 false 时它与「注册表不可用」无法区分，
+      // 排查只能看到「需重启 DSH 后再执行一次归位」，看不到「为什么」。
+      this.log.warn(listed.detail)
+      return false
+    }
+    const fresh = listed.items.find((item) => item.id === sessionId)
+    if (fresh === undefined) return false
     try {
-      const snapshots = await store.list()
-      const fresh = snapshots.find((snapshot) => snapshot.header?.id === sessionId)?.header
-      if (fresh === undefined) return false
-      await registry.indexHeader(fresh)
+      // 必须回传**原样的 header 对象**（handle = element.header；legacy = 元素自身）
+      await registry.indexHeader(fresh.raw)
       return true
-    } catch {
+    } catch (err) {
+      this.log.warn(`会话 header 重新索引失败（${sessionId}）：${err instanceof Error ? err.message : String(err)}`)
       return false
     }
   }
 
+  /**
+   * 列举宿主会话存储并**把两种元素形状归一**（F-1 唯一入口）。
+   *
+   * 返回 `ok:false` 的两种情形必须被调用方**响亮处理**（记日志 + 抛错/明确失败返回）：
+   *  - `unavailable`：服务或 `list()` 不可用（抛错 / 返回非数组）；
+   *  - `shape-unknown`：有元素、但**一个都解析不出 id**（宿主形状既不是 handle 也不是 legacy）。
+   * 这两种**绝不**降级成「本机没有会话 / 没有父子关系」的空结果 —— 那正是 F-1 的真机事故。
+   * 元素**部分**认不出时保留已认出的并记一条警告（部分可用比全丢好，但必须可见）。
+   */
+  private async listSessionElements(
+    store: SessionListService,
+    purpose: SessionStorePurpose,
+  ): Promise<ListedSessions> {
+    // T8-F1：purpose 是内部枚举 → 先经字典键映射成人类可读用途，**绝不渲染裸枚举**；
+    // 三条 detail/warn 一律走 this.msgFunc（本文件里唯一的用户可见文案出口），不硬编码中文。
+    const purposeLabel = this.msgFunc(SESSION_STORE_PURPOSE_KEY[purpose])
+    let elements: readonly unknown[]
+    try {
+      elements = await store.list()
+    } catch (err) {
+      return {
+        ok: false,
+        reason: 'unavailable',
+        detail: this.msgFunc('host.sessionStoreListFailed', { purpose: purposeLabel, reason: errorMessage(err) }),
+      }
+    }
+    if (!Array.isArray(elements)) {
+      return {
+        ok: false,
+        reason: 'unavailable',
+        detail: this.msgFunc('host.sessionStoreListNotArray', { purpose: purposeLabel }),
+      }
+    }
+    const items: ListedSessionView[] = []
+    let unresolved = 0
+    for (const element of elements) {
+      const view = normalizeListedSession(element)
+      if (view === undefined) unresolved += 1
+      else items.push(view)
+    }
+    if (items.length === 0 && elements.length > 0) {
+      const detail = this.msgFunc('host.sessionStoreShapeUnknown', {
+        shape: sessionPersistenceShapeOf(store),
+        count: String(elements.length),
+      })
+      this.log.error(detail)
+      return { ok: false, reason: 'shape-unknown', detail }
+    }
+    if (unresolved > 0) {
+      this.log.warn(
+        this.msgFunc('host.sessionStorePartialUnresolved', {
+          count: String(unresolved),
+          total: String(elements.length),
+          purpose: purposeLabel,
+        }),
+      )
+    }
+    return { ok: true, items }
+  }
+
   /**
    * 本机会话的父子关系（子会话 id → 父会话 id）。
    *
    * 实现走 DSH 会话存储的列举（与 `session/list` 同一数据源）：只取 header 的 `parentSession`，
    * 不解析任何日志字节 —— 让「导出父对话时连带子代理会话」不为此读一遍整棵会话树。
-   * 字段名以磁盘 header 为准（`parentSession`；DSH 的 RPC 投影才改名为 `parentSessionId`）。
-   * 服务缺失 / 列举失败 → 空 Map（调用方按「无法连带」处理，绝不假装带全）。
+   * 字段名以磁盘 header 为准（`parentSession`，两种写法都认；DSH 的 RPC 投影才改名为 `parentSessionId`）。
+   * 元素形状按 **API 形状探测**归一（handle 的 `element.header` 与 legacy 的平铺字段都认，F-1）。
+   *
+   * 失败语义（F-1，**不得放宽**）：
+   *  - 服务**未接线** → 空 Map（确定性事实：宿主没有会话存储，不是读失败）；
+   *  - 列举失败 / 元素形状一个都认不出 → **抛错**（带明确原因）。绝不返回空 Map ——
+   *    空 Map 会进 5 s TTL 缓存，且让「本机一条父子关系都没有」与「读不出来」无法区分，
+   *    「导出子代理会话连带父对话」就会再次静默失效。调用方各自有回退路径（见 `loadParentRelations`）。
    */
   async parentRelations(): Promise<Map<string, SessionParentRelation>> {
     return this.parentRelationsCache.resolve('local', () => this.loadParentRelations())
@@ -771,18 +1037,22 @@ export class DshSessionStoreFacade implements SessionStoreFacade {
 
   /** 真正列举一次 DSH 会话存储（语义见 `parentRelations()`；本方法不做缓存） */
   private async loadParentRelations(): Promise<Map<string, SessionParentRelation>> {
+    const store = readService<SessionListService>(this.ctx, 'sessionPersistence')
+    // 服务**未接线**（宿主不提供 sessionPersistence）→ 不猜，空 Map（与改造前一致，属确定性事实）
+    if (store === undefined) return new Map<string, SessionParentRelation>()
+    // F-1：形状归一（handle 的 element.header / legacy 的元素自身都认）
+    const listed = await this.listSessionElements(store, 'parentRelations')
+    if (!listed.ok) {
+      // 读不到 / 形状认不出 → **响亮抛错**，绝不退化成「本机没有父子关系」的空 Map
+      // （空 Map 既会被 5 s TTL 缓存放大，也让「导出少带父对话」没有任何提示）。
+      // 调用方各自有回退路径：/export-preview 只是不标父链接（预览照常），
+      // 会话体检退回 storages 缓存枚举。
+      throw new Error(listed.detail)
+    }
     const out = new Map<string, SessionParentRelation>()
-    const store = readService<{ list(): Promise<readonly { header?: { id?: unknown; parentSession?: unknown; origin?: unknown } }[]> }>(this.ctx, 'sessionPersistence')
-    if (store === undefined) return out
-    try {
-      for (const snapshot of await store.list()) {
-        const id = snapshot.header?.id
-        const parent = snapshot.header?.parentSession
-        if (typeof id !== 'string' || id === '' || typeof parent !== 'string' || parent === '') continue
-        out.set(id, { parent, subagent: snapshot.header?.origin === 'subagent' })
-      }
-    } catch {
-      return new Map<string, SessionParentRelation>()
+    for (const item of listed.items) {
+      if (item.parent === undefined) continue
+      out.set(item.id, { parent: item.parent, subagent: item.origin === 'subagent' })
     }
     return out
   }
@@ -797,12 +1067,20 @@ export class DshSessionStoreFacade implements SessionStoreFacade {
   }
 }
 
-/** Profile 目录内的 patch 文件（非 bundle 插件激活行写入处，marketplace 同款路径）。 */
-const PROFILE_PATCH_FILE = 'cordis.patch.yml'
-
-/** Patch-file facade：用户 patch 层（$DSH_HOME/cordis.patch.yml）+ profile patch 层
- * （$DSH_HOME/profiles/<name>/cordis.patch.yml），两者都在 home 根内。 */
-class DshPatchFileFacade implements PatchFileFacade {
+/**
+ * Patch-file facade：patch 的**两层**都在 home 根内 ——
+ *   - 用户（home）层：`$DSH_HOME/cordis.patch.yml`
+ *   - profile 层：`$DSH_HOME/profiles/<name>/cordis.patch.yml`
+ *
+ * `file` 参数是**相对 homeDir 的 POSIX 路径**（issue #71；层身份的定义见 core/patch-layers.ts）。
+ * 改造前这里是「拿文件名字符串当枚举」的两个分支，而两个分支比较的是同一个字面量
+ * `'cordis.patch.yml'` —— profile 分支永远不可达，于是 profile 层的 MCP / prompts 行
+ * 在备份里凭空消失（用户报告的「备份不到外壳 mcp」）。现在按路径解析，两层都能读写。
+ *
+ * YAML 侧一律走 `utils/patch-yaml.ts` 的 **DSH 方言**（issue #75）：`!!js` 必须能读写往返，
+ * 且原文件解析不了时**拒绝覆盖**（读不出来 ≠ 空文档）。
+ */
+export class DshPatchFileFacade implements PatchFileFacade {
   private readonly homeDir: string
   private readonly profile: string
   private readonly msg: MsgFunc
@@ -813,10 +1091,32 @@ class DshPatchFileFacade implements PatchFileFacade {
     this.msg = msg
   }
 
+  /**
+   * 层路径 → 绝对路径。
+   *
+   * 只接受**已知的层路径**（用户层 / 本 profile 的 profile 层），且解析结果必须落在 home 根内：
+   * 调用方传进来的是快照里存的字符串，跨机器恢复时不能让它变成任意路径写。
+   * 本 profile 之外的 profile 层同样拒绝 —— 一个档案的备份不该写另一个档案的 patch。
+   */
   private patchPath(file: string): string {
-    if (file === USER_PATCH_FILE) return join(this.homeDir, USER_PATCH_FILE)
-    if (file === PROFILE_PATCH_FILE) return join(this.homeDir, 'profiles', this.profile, PROFILE_PATCH_FILE)
-    throw new Error(this.msg('host.patchUnsupported', { user: USER_PATCH_FILE, profile: PROFILE_PATCH_FILE, file }))
+    const rel = file.replace(/\\/g, '/')
+    const allowed = rel === USER_PATCH_FILE || (isPatchLayerRel(rel) && rel === profilePatchRel(this.profile))
+    if (!allowed) {
+      throw new Error(this.msg('host.patchUnsupported', {
+        user: USER_PATCH_FILE,
+        profile: profilePatchRel(this.profile),
+        file,
+      }))
+    }
+    const abs = resolve(this.homeDir, rel)
+    if (!isSameOrChild(abs, this.homeDir)) {
+      throw new Error(this.msg('host.patchUnsupported', {
+        user: USER_PATCH_FILE,
+        profile: profilePatchRel(this.profile),
+        file,
+      }))
+    }
+    return abs
   }
 
   async readPatchLines(file: string): Promise<{ lineId: string; raw: unknown }[]> {
@@ -824,14 +1124,21 @@ class DshPatchFileFacade implements PatchFileFacade {
     let text: string
     try {
       text = await fs.readFile(p, 'utf8')
-    } catch {
-      return []
+    } catch (err) {
+      // 真不存在 = 「按需创建、本来就没有」→ 空层（既有语义）。
+      // 其余 errno（EACCES / EBUSY / …）**必须上抛**：读不到 ≠ 没有；静默返回空会让这一层的
+      // patch 行在导出/同步里无声消失（t23 口径；readEffectivePatchLines 的 failures 通道会转成
+      // 可见告警，三个适配器都会展示）。
+      if (isENOENT(err)) return []
+      throw new Error(this.msg('host.patchUnreadable', { file, reason: describePatchYamlError(err) }), { cause: err })
     }
     let doc: unknown
     try {
-      doc = yaml.load(text)
-    } catch {
-      return []
+      doc = loadPatchDocument(text)
+    } catch (err) {
+      // 解析失败同样上抛（issue #75）：`!!js` 这类 DSH 方言一旦读不出来，返回 [] 就等于把用户
+      // 手写的整层配置从导出/同步里抹掉（比「报错」糟得多）。
+      throw new Error(this.msg('host.patchUnreadable', { file, reason: describePatchYamlError(err) }), { cause: err })
     }
     if (!Array.isArray(doc)) return []
     const lines: { lineId: string; raw: unknown }[] = []
@@ -860,13 +1167,29 @@ class DshPatchFileFacade implements PatchFileFacade {
     const p = this.patchPath(file)
 
     // 1. Load the current document into an ordered lineId → raw table.
+    //
+    // 读不出来的既有内容**绝不能当作空文档**（issue #75 的数据丢失点）：重建后的文件只包含
+    // 本次写入的行，等于把用户手写的其余行整段删掉。三种情况分开处理：
+    //   - 真不存在（ENOENT）→ 空文档（首次创建，既有语义）；
+    //   - 存在但读不到（EACCES/EBUSY/…）→ 抛错，不改写；
+    //   - 存在但解析不了（含未知方言 / YAML 本身有错）→ 抛错，不改写。
     const rows = new Map<string, unknown>()
     const order: string[] = []
-    let doc: unknown
+    let existing: string | null = null
     try {
-      doc = yaml.load(await fs.readFile(p, 'utf8'))
-    } catch {
-      doc = undefined
+      existing = await fs.readFile(p, 'utf8')
+    } catch (err) {
+      if (!isENOENT(err)) {
+        throw new Error(this.msg('host.patchRefuseClobber', { file, reason: describePatchYamlError(err) }), { cause: err })
+      }
+    }
+    let doc: unknown
+    if (existing !== null && existing.trim() !== '') {
+      try {
+        doc = loadPatchDocument(existing)
+      } catch (err) {
+        throw new Error(this.msg('host.patchRefuseClobber', { file, reason: describePatchYamlError(err) }), { cause: err })
+      }
     }
     if (Array.isArray(doc)) {
       for (const item of doc) {
@@ -914,7 +1237,7 @@ class DshPatchFileFacade implements PatchFileFacade {
       if (raw !== undefined) out.push(raw)
     }
     const text = '# rewritten by dsh-config-manager import (original comments not preserved)\n'
-      + yaml.dump(out)
+      + dumpPatchDocument(out)
     await atomicWriteFile(p, text)
   }
 }
@@ -948,8 +1271,17 @@ export class DshFileSystemFacade implements FileSystemFacade {
     try {
       await fs.access(this.abs(relPath))
       return true
-    } catch {
-      return false
+    } catch (err) {
+      // t85 / t23 口径：**读不到 ≠ 没有**。只有 ENOENT 才是「按需创建、本来就没有」；
+      // EACCES / EPERM / EBUSY / EMFILE / ENOTDIR… 一律**按「存在」处理**（返回 true）。
+      //
+      // 为什么选「按存在处理」而不是上抛：本方法是 FileSystemFacade 的**布尔端口**，全部消费点
+      // 都按「exists() 恒返回布尔、不抛」来写（消费点清单见 t85 交付物），其中多处处于只读/预览
+      // 路径（backup / market / sync-ancestor / plugin-files）—— 上抛会把「探测失败」变成这些调用点
+      // 未预期的错误面；而 t23 立的规矩正是「判定『不存在』的探测自身失败时按『存在』处理」。
+      // 保守方向也是安全方向：true ⇒ 调用方不创建 / 不删除 / 不剔除声明，绝不造成有损副作用。
+      // ENOENT 必须仍为 false，否则会破坏「按需创建 / 本来就没有」的既有语义。
+      return !isENOENT(err)
     }
   }
 
@@ -1051,6 +1383,62 @@ export class DshFileSystemFacade implements FileSystemFacade {
     }
   }
 
+  /**
+   * 目录体积上界（只读预览：本地源插件的 `link:` 目录）。
+   *
+   * 与 realpathDir 同族的「绝对路径」方法：入参只可能是本机插件 spec 推导出的绝对路径
+   * （`link:` 常指向 $DSH_HOME 之外的桌面端 resources 目录），因此**不受 home 边界限制**。
+   *
+   * 约束（宁可低估，不可卡住预览）：
+   *  - 不跟随符号链接 / junction：`readdir(withFileTypes)` 对链接目录的 isDirectory() 恒 false，
+   *    按「既不是文件也不是目录」跳过，既不会绕圈也不会跑出该目录；
+   *  - 跳过 node_modules：`npm pack` 自身也排除它，数进去只会把量级抬高一个数量级；
+   *  - `maxEntries` 兜底（默认 20000）：超出即停并返回已累计值；
+   *  - 不是目录 / 读不到 → null（调用方对这类目录退回「体积按 0」）。
+   */
+  async dirSizeBytes(absPath: string, opts: { maxEntries?: number } = {}): Promise<number | null> {
+    const maxEntries = opts.maxEntries !== undefined && opts.maxEntries > 0 ? opts.maxEntries : 20000
+    const readEntries = async (dir: string): Promise<Array<{ name: string; isDirectory(): boolean; isFile(): boolean }>> => {
+      try {
+        return await fs.readdir(dir, { withFileTypes: true })
+      } catch {
+        return []
+      }
+    }
+    try {
+      const target = resolve(absPath)
+      const st = await fs.stat(target)
+      if (!st.isDirectory()) return null
+      const stack: string[] = [target]
+      let total = 0
+      let counted = 0
+      while (stack.length > 0) {
+        const dir = stack.pop()
+        if (dir === undefined) break
+        for (const ent of await readEntries(dir)) {
+          if (ent.name === 'node_modules') continue
+          const full = join(dir, ent.name)
+          if (ent.isDirectory()) {
+            stack.push(full)
+            continue
+          }
+          if (!ent.isFile()) continue
+          if (counted >= maxEntries) return total
+          counted += 1
+          try {
+            const fileStat = await fs.stat(full)
+            if (fileStat.isFile()) total += fileStat.size
+          } catch {
+            // 单个文件读不到就跳过：预览要的是量级，不值得为它失败
+          }
+        }
+      }
+      return total
+    } catch {
+      return null
+    }
+  }
+
   /**
    * 建缺失目录（issue #45：导入工作区记录前把缺失的项目目录建出来）。
    *
@@ -1106,6 +1494,15 @@ export class ConfigManagerHostContext implements HostContext {
   readonly fs: FileSystemFacade
   /** 会话存储端口（issue #45 会话归位；对 ctx.sessionPersistence 的薄适配） */
   readonly sessions: SessionStoreFacade
+  /**
+   * 技能服务端口（issue #71；对 ctx.skills 的薄适配）。
+   *
+   * 为什么需要：真机上 89 个 SKILL.md 全在 `profiles/<p>/node_modules` 里（技能 provider 由
+   * 插件注册），`$DSH_HOME/skills` 根本不存在 —— 只扫目录的分区必然是空的。
+   *
+   * 可选：宿主没有 skills 服务时（旧外壳）缺省 undefined，skills 分区退回纯目录扫描。
+   */
+  readonly skills: SkillStoreFacade | undefined
   /**
    * 本机 DSH 支持的**会话日志格式版本**（`SESSION_FORMAT_VERSION`；解析不到 = undefined）。
    *
@@ -1119,6 +1516,15 @@ export class ConfigManagerHostContext implements HostContext {
   safeModeIsBlocked?: () => boolean
   /** Phase 3 恢复/事务（JournalStore + reconcile + SAFE MODE + runJournaled）。apply() 注入。 */
   phase3Recovery?: import('./core/phase3-host.ts').Phase3Recovery
+  /**
+   * 本机自请求能力（F-2：官方 session.export 通道的探测与代理）。
+   *
+   * 只有「让 DSH 自己的 /api/session.export 说一遍它自己的状态」这一种用法 ——
+   * 绝不拿它去访问外部网络（插件对外的网络调用有各自的既有通道）。
+   */
+  fetch?: (input: string, init: RequestInit) => Promise<Response>
+  /** 本实例 web 监听端口（webServer 就绪前为 undefined → 探测不发请求、如实降级）。 */
+  webPort?: number
 
   constructor(ctx: Context, homeDir: string, profile: string) {
     this.homeDir = homeDir
@@ -1127,7 +1533,11 @@ export class ConfigManagerHostContext implements HostContext {
     const installAnchor = installAnchorFromProfileContext(readService<unknown>(ctx, 'profileContext'))
     this.dshVersion = resolveDshVersion(homeDir, profile, installAnchor)
     // 会话格式版本与 DSH 版本同源同候选（桌面端的运行时在 app.asar 内）。
-    this.sessionFormatVersion = resolveSessionFormatVersion(dshPackageJsonCandidates(homeDir, profile, installAnchor))
+    // tried 收集**所有尝试过的路径**：解析失败时写进日志 —— 「解析不到」这句话本身对排查没有价值
+    // （issue #74 的直接诉求），真机要的是「都试了哪几处」。
+    const sessionFormatTried: string[] = []
+    this.sessionFormatVersion = resolveSessionFormatVersion(
+      dshPackageJsonCandidates(homeDir, profile, installAnchor), sessionFormatTried)
     this.profile = profile
     this.profileDir = resolveProfileDir(homeDir, profile)
     this.language = resolveAppLanguage(ctx)
@@ -1137,8 +1547,13 @@ export class ConfigManagerHostContext implements HostContext {
     // 排查时 DSH_CONFIG_MANAGER_LOG_LEVEL=info|debug 恢复逐条输出。
     this.log = createLogger({ level: parseLogLevel(process.env.DSH_CONFIG_MANAGER_LOG_LEVEL) })
     if (this.sessionFormatVersion === undefined) {
-      // 绝不静默：解析不到就明说体检不可用（用户仍能导出/导入，只是拿不到格式告警）。
-      this.log.warn('无法解析本机 DSH 的会话格式版本：导入/同步不做「会话格式是否可读」体检')
+      // 绝不静默：解析不到就明说体检不可用（用户仍能导出/导入，只是拿不到格式告警），
+      // 并把已尝试的路径一并给出。
+      const triedText = sessionFormatTried.length > 6
+        ? sessionFormatTried.slice(0, 6).join('、') + ' 等'
+        : sessionFormatTried.join('、')
+      this.log.warn('无法解析本机 DSH 的会话格式版本：导入/同步不做「会话格式是否可读」体检'
+        + `（已尝试 ${sessionFormatTried.length} 处：${triedText}）`)
     }
     this.settings = new DshSettingsFacade(ctx)
     this.credentials = new DshCredentialsFacade(ctx)
@@ -1146,7 +1561,14 @@ export class ConfigManagerHostContext implements HostContext {
     this.plugins = new DshPluginsFacade(homeDir, profile, this.patchFile, undefined, this.msg)
     this.workspace = new DshWorkspaceFacade(ctx, this.msg)
     this.fs = new DshFileSystemFacade(homeDir, this.msg)
-    this.sessions = new DshSessionStoreFacade(ctx, homeDir, this.msg)
+    this.sessions = new DshSessionStoreFacade(ctx, homeDir, this.msg, this.log)
+    // F-2：Cordis 的 fetch 服务（DSH 自己在用它转发 /api）。缺省回落进程全局 fetch（Node ≥18 恒有）。
+    const fetchService = readService<unknown>(ctx, 'fetch')
+    const fetchImpl = typeof fetchService === 'function' ? fetchService : globalThis.fetch
+    if (typeof fetchImpl === 'function') {
+      this.fetch = (input, init) => fetchImpl(input, init) as Promise<Response>
+    }
+    this.skills = resolveSkillStore(ctx)
   }
 }
 
@@ -1216,11 +1638,15 @@ export async function tryDecryptCredentials(
   if (!archive.has('security/secrets.enc')) return undefined
   const blob = archive.readEntry('security/secrets.enc')
   const plaintext = await decryptCredentials(blob, manifest.security.encryption, password)
+  // e2e-F1：**解密成功**（GCM 已认证）之后的「没有可识别 ref」必须回**空 Map**，而不是 undefined ——
+  // undefined 是「没有解密 / 不适用」的语义，会被 analyzer 的安全阀判成「未提供密码」而拒绝导入
+  // （真机：导出机没有可导出的凭据值 → secrets.enc 明文 0 字节 → yaml.load('') 抛错 → undefined → 400）。
+  // 与同步侧 `fromYaml`（src/security/credentials-yaml.ts，其测试断言 fromYaml('').size === 0）同口径。
   let parsed: unknown
   try {
-    parsed = yaml.load(plaintext)
+    parsed = plaintext.trim() === '' ? null : yaml.load(plaintext)
   } catch {
-    return undefined
+    parsed = null
   }
   // 解析口径与同步引擎共用（security/credentials-yaml.ts）：顶层 refs 块（DSH v1 布局）
   // 与预发布扁平布局都认，records 等嵌套结构忽略（issue #39）。
@@ -1245,7 +1671,7 @@ export async function tryDecryptCredentials(
  * （见 W1 报告的重测配方），把结果落到这里；makeRoutes 里的 const routeEnv: RouteEnvInferred =
  * 注解保证两侧不漂移（新增依赖漏登记会在构造点报错）。
  */
-export type RouteEnvInferred = { adapters: ConfigAdapter<unknown>[]; sessionHealth: { homeDir: string; targetFormatVersion: () => number | undefined; workspaceKeys: () => Promise<ReadonlySet<string>>; knownSessionIds: () => Promise<ReadonlySet<string>>; }; backupScheduler: BackupScheduler; bootSafetyAudit: () => Promise<BootSafetyReport>; cancelDecisionTimeoutMs: number; buildMarketSummary: (e: { url: string; addedAt: string; }) => Promise<MarketSummary>; credentials: CredentialProvider; dataDir: string; exportsDir: string; githubAuth: GitHubAuthClient; githubClientId: string | undefined; githubClientSecret: string | undefined; githubFlows: DeviceFlowStore; history: MigrationStore; host: ConfigManagerHostContext; itemCached: (url: string, itemId: string) => Promise<boolean>; knownSyncSectionIds: Set<SectionId>; makeImporter: () => Importer; makeMarketReader: () => GitMarketReader; makeRecoveryExecutors: (runId: string) => RecoveryExecutorFns; makeSyncEngine: (cfg: SyncConfig, engineOpts?: { includeOptInSections?: boolean; }) => SyncEngine; marketBootAutoRefreshed: { value: boolean; }; marketCacheIndex: (url: string) => string; marketDir: string; marketCacheItemDir: (url: string) => string; marketStarCache: StarCache; marketWorkDir: (url: string) => string; meGitHubRest: GitHubAuthRest; meService: MyRepoService; meTokenProvider: () => Promise<string>; msg: MsgFunc; prepareSync: (body: Record<string, unknown>) => Promise<SyncConfig>; profileLauncher: DshProfileLauncher; profileRuntime: DshProfileRuntimeRegistry; profiles: DshProfileManager; pruneStagedMarketZips: () => Promise<void>; readCachedIndexObj: (url: string) => Promise<MarketIndex | null>; recoveryOrchestrator: RecoveryOrchestrator; resolveSyncPassword: (ref: string) => Promise<string | undefined>; roots: string[]; runAbortControllers: Map<string, AbortController>; runCancels: Map<string, { signal: AbortController; settle: (d: 'rollback' | 'keep') => void; decided: boolean }>; runs: RunRegistry; scheduler: AutoSyncScheduler; selectionCache: Partial<Record<"git" | "webdav", SyncSelection>>; selectionHasOptInSections: (channel: SyncTransportType) => boolean; selectionView: (channel: SyncTransportType) => Promise<SelectionView>; selectionViewByChannel: () => Promise<Record<SyncTransportType, SelectionView>>; snapshotEntrySections: (snapshotDir: string) => Promise<string[]>; snapshotsDir: string; syncCredentialsByChannelView: () => Promise<Record<SyncTransportType, { encryptPasswordConfigured: boolean; decryptPasswordConfigured: boolean; }>>; syncDir: string; syncPasswordConfigured: (ref: string) => Promise<boolean>; syncSectionCatalog: { id: SectionId; displayName: string; portability: Portability; defaultIncluded: boolean; }[]; syncSessions: SyncSessionStore; tmpDir: string; tryAppendHistory: (raw: { kind: MigrationKind; result: MigrationResult; sections: string[]; operationId?: string; snapshotId?: string; runId?: string; source: 'api' | 'autosync' | 'backup-scheduler' | 'recovery' | 'cli' | 'internal'; summary: string; error?: string; }) => Promise<string | undefined>; withMutationGate: (op: string, handler: (req: IncomingMessage, res: ServerResponse, lockCtx?: MutationLockContext, journalCtx?: JournalRunContext) => Promise<void>, opts?: { journaled?: boolean; deferredSnapshot?: boolean; }) => ((req: IncomingMessage, res: ServerResponse) => Promise<void>); writeItemCache: (url: string, itemId: string, manifestRaw: string, zipBytes: Uint8Array) => Promise<void>; }
+export type RouteEnvInferred = { sessionExportFetch: ((input: string, init: RequestInit) => Promise<Response>) | undefined; sessionExportPort: number | undefined; adapters: ConfigAdapter<unknown>[]; sessionHealth: { homeDir: string; targetFormatVersion: () => number | undefined; workspaceKeys: () => Promise<ReadonlySet<string>>; knownSessionIds: () => Promise<ReadonlySet<string>>; }; backupScheduler: BackupScheduler; bootSafetyAudit: () => Promise<BootSafetyReport>; cancelDecisionTimeoutMs: number; buildMarketSummary: (e: { url: string; addedAt: string; }) => Promise<MarketSummary>; credentials: CredentialProvider; dataDir: string; exportsDir: string; githubAuth: GitHubAuthClient; githubClientId: string | undefined; githubClientSecret: string | undefined; githubFlows: DeviceFlowStore; history: MigrationStore; host: ConfigManagerHostContext; itemCached: (url: string, itemId: string) => Promise<boolean>; knownSyncSectionIds: Set<SectionId>; makeImporter: () => Importer; makeMarketReader: () => GitMarketReader; makeRecoveryExecutors: (runId: string) => RecoveryExecutorFns; makeSyncEngine: (cfg: SyncConfig, engineOpts?: { includeOptInSections?: boolean; }) => SyncEngine; marketBootAutoRefreshed: { value: boolean; }; marketCacheIndex: (url: string) => string; marketDir: string; marketCacheItemDir: (url: string) => string; marketStarCache: StarCache; marketWorkDir: (url: string) => string; meGitHubRest: GitHubAuthRest; meService: MyRepoService; meTokenProvider: () => Promise<string>; msg: MsgFunc; prepareSync: (body: Record<string, unknown>) => Promise<SyncConfig>; profileLauncher: DshProfileLauncher; profileRuntime: DshProfileRuntimeRegistry; profiles: DshProfileManager; pruneStagedMarketZips: () => Promise<void>; readCachedIndexObj: (url: string) => Promise<MarketIndex | null>; recoveryOrchestrator: RecoveryOrchestrator; resolveSyncPassword: (ref: string) => Promise<string | undefined>; roots: string[]; runAbortControllers: Map<string, AbortController>; runCancels: Map<string, { signal: AbortController; settle: (d: 'rollback' | 'keep') => void; decided: boolean }>; runs: RunRegistry; scheduler: AutoSyncScheduler; selectionCache: Partial<Record<SyncTransportType, SyncSelection>>; selectionHasOptInSections: (channel: SyncTransportType) => boolean; selectionView: (channel: SyncTransportType) => Promise<SelectionView>; selectionViewByChannel: () => Promise<Record<SyncTransportType, SelectionView>>; snapshotEntrySections: (snapshotDir: string) => Promise<string[]>; snapshotsDir: string; syncCredentialsByChannelView: () => Promise<Record<SyncTransportType, { encryptPasswordConfigured: boolean; decryptPasswordConfigured: boolean; }>>; syncDir: string; syncPasswordConfigured: (ref: string) => Promise<boolean>; syncSectionCatalog: { id: SectionId; displayName: string; portability: Portability; defaultIncluded: boolean; }[]; syncSessions: SyncSessionStore; tmpDir: string; tryAppendHistory: (raw: { kind: MigrationKind; result: MigrationResult; sections: string[]; operationId?: string; snapshotId?: string; runId?: string; source: 'api' | 'autosync' | 'backup-scheduler' | 'recovery' | 'cli' | 'internal'; summary: string; error?: string; }) => Promise<string | undefined>; withMutationGate: (op: string, handler: (req: IncomingMessage, res: ServerResponse, lockCtx?: MutationLockContext, journalCtx?: JournalRunContext) => Promise<void>, opts?: { journaled?: boolean; deferredSnapshot?: boolean; }) => ((req: IncomingMessage, res: ServerResponse) => Promise<void>); selfUpdate: (targetVersion: string) => Promise<SelfUpdateOutcome>; writeItemCache: (url: string, itemId: string, manifestRaw: string, zipBytes: Uint8Array) => Promise<void>; }
 
 /** 解密错误 → 用户可读文本：BAD_PASSWORD 只报「密码错误」（不泄内部细节），其余原文 */
 export function decryptErrorText(error: unknown, msg: MsgFunc): string {
@@ -1294,8 +1720,9 @@ interface RoutesDeps {
 /** 同步路由可预期的请求级错误（status 缺省 400；引擎/传输失败走 500）。
  * 继承 kit 的 RouteError → 错误→HTTP 映射全仓只有 writeRouteError 一份。 */
 export class SyncRouteError extends RouteError {
-  constructor(message: string, status: number = 400) {
-    super(message, status)
+  /** code：稳定机器码（如 cloud.endpointRequired），由 UI 映射进字典；缺省 = 无码。 */
+  constructor(message: string, status: number = 400, code?: string) {
+    super(message, status, code)
     this.name = 'SyncRouteError'
   }
 }
@@ -1322,7 +1749,11 @@ export async function parseSyncBody(
   body: Record<string, unknown>,
   deps: ParseSyncBodyDeps,
 ): Promise<SyncConfig> {
-  const transport = parseSyncChannel(body['transport']) ?? 'git'
+  const rawTransport = body['transport']
+  // 通道值解析：接受通道名（s3/gist）；也接受**具体兼容商**（oss/cos/minio/kodo）直接落到 s3 通道
+  const transport = parseSyncChannel(rawTransport) ?? (isS3CompatProvider(rawTransport) ? 's3' : 'git')
+  if (transport === 's3') return parseCloudS3Body(body, rawTransport, deps)
+  if (transport === 'gist') return parseCloudGistBody(body, deps)
   if (transport === 'webdav') {
     const url = typeof body['url'] === 'string' ? body['url'].trim() : ''
     if (url === '') throw new SyncRouteError('url is required for webdav')
@@ -1369,6 +1800,115 @@ export async function parseSyncBody(
   }
 }
 
+/** 请求体字段 → 去空白字符串（非字符串 = 空）。 */
+function syncStr(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/** 云端点密钥写入失败 → 可操作错误（**含 ref 名、绝不含密钥值**）。 */
+function cloudCredentialWriteError(ref: string, kind: string, error: unknown): SyncRouteError {
+  const reason = error instanceof Error ? error.message : String(error)
+  return new SyncRouteError(
+    kind + ' 写入 DSH credentials 失败：' + reason + '（请在 DSH 凭据管理里配置 ' + ref + ' 后重试）',
+    400,
+    'cloud.credentialsWriteFailed',
+  )
+}
+
+/**
+ * s3 通道请求体 → SyncConfig（provider 必填或由 transport 直接给出）。
+ * 非密字段按 validateCloudChannelInput 校验（错误码 = HTTP body.code，由 UI 映射字典）；
+ * 密钥**只写**进 DSH credentials 的 cloudSecretRef(provider) 槽位，绝不进返回值 / 文件 / 日志。
+ */
+async function parseCloudS3Body(
+  body: Record<string, unknown>,
+  rawTransport: unknown,
+  deps: ParseSyncBodyDeps,
+): Promise<SyncConfig> {
+  const provider = isS3CompatProvider(body['provider'])
+    ? body['provider']
+    : (isS3CompatProvider(rawTransport) ? rawTransport : null)
+  if (provider === null) {
+    throw new SyncRouteError('provider is required for s3 (s3/oss/cos/minio/kodo)', 400, 'cloud.providerUnknown')
+  }
+  const endpoint = syncStr(body['endpoint']).replace(/\/+$/, '')
+  const region = syncStr(body['region'])
+  const bucket = syncStr(body['bucket'])
+  const accessKeyId = syncStr(body['accessKeyId'])
+  const prefix = syncStr(body['prefix'])
+  const pathStyle = typeof body['pathStyle'] === 'boolean' ? body['pathStyle'] : undefined
+  const dialectId = body['dialectId'] === 'aws4' || body['dialectId'] === 'oss4' ? body['dialectId'] : undefined
+  const issue = validateCloudChannelInput(provider, {
+    endpoint,
+    region,
+    bucket,
+    accessKeyId,
+    ...(prefix === '' ? {} : { prefix }),
+    ...(pathStyle === undefined ? {} : { pathStyle }),
+    ...(dialectId === undefined ? {} : { dialectId }),
+  })
+  if (issue !== null) throw new SyncRouteError(issue, 400, issue)
+  const secret = typeof body['secret'] === 'string' && body['secret'] !== '' ? body['secret'] : undefined
+  if (secret !== undefined) {
+    const ref = cloudSecretRef(provider)
+    try {
+      await deps.credentials.set(credentialRef(ref), secret)
+    } catch (error) {
+      throw cloudCredentialWriteError(ref, 'S3 密钥', error)
+    }
+  }
+  return {
+    schemaVersion: 2,
+    transport: 's3',
+    s3: {
+      provider,
+      endpoint,
+      region,
+      bucket,
+      accessKeyId,
+      ...(prefix === '' ? {} : { prefix }),
+      ...(pathStyle === undefined ? {} : { pathStyle }),
+      ...(dialectId === undefined ? {} : { dialectId }),
+    },
+  }
+}
+
+/**
+ * gist 通道请求体 → SyncConfig。token 只写进 cloudSecretRef('gist') 槽位
+ * （请求体字段名 token 或 secret 都接受；值绝不进返回值 / 文件 / 日志）。
+ */
+async function parseCloudGistBody(body: Record<string, unknown>, deps: ParseSyncBodyDeps): Promise<SyncConfig> {
+  const gistId = syncStr(body['gistId'])
+  const apiBaseUrl = syncStr(body['apiBaseUrl'])
+  const filePrefix = syncStr(body['filePrefix'])
+  const issue = validateCloudChannelInput(GIST_PROVIDER, {
+    gistId,
+    ...(apiBaseUrl === '' ? {} : { apiBaseUrl }),
+    ...(filePrefix === '' ? {} : { filePrefix }),
+  })
+  if (issue !== null) throw new SyncRouteError(issue, 400, issue)
+  const token = typeof body['token'] === 'string' && body['token'] !== ''
+    ? body['token']
+    : (typeof body['secret'] === 'string' && body['secret'] !== '' ? body['secret'] : undefined)
+  if (token !== undefined) {
+    const ref = cloudSecretRef(GIST_PROVIDER)
+    try {
+      await deps.credentials.set(credentialRef(ref), token)
+    } catch (error) {
+      throw cloudCredentialWriteError(ref, 'Gist token', error)
+    }
+  }
+  return {
+    schemaVersion: 2,
+    transport: 'gist',
+    gist: {
+      gistId,
+      ...(apiBaseUrl === '' ? {} : { apiBaseUrl }),
+      ...(filePrefix === '' ? {} : { filePrefix }),
+    },
+  }
+}
+
 /** 由 SyncConfig 合成 WebDAV 通道 baseUrl（webdav.url，尾部规范化带 '/'；git 通道返回 ''）。 */
 export function webdavBaseUrl(cfg: SyncConfig): string {
   if (!isWebDavConfig(cfg)) return ''
@@ -1901,8 +2441,15 @@ async function sessionHealthKnownIds(host: HostContext): Promise<ReadonlySet<str
         ids.add(sessionIdKey(childId))
         if (typeof relation.parent === 'string' && relation.parent !== '') ids.add(sessionIdKey(relation.parent))
       }
-    } catch {
-      /* 落回 storages 缓存 */
+    } catch (err) {
+      // T8-F2：**不许静默**。port 层刚刚改成「认不出形状就抛错」（F-1），调用点若把声响整吞，
+      // 用户看到的仍是「父子联动无缘无故不生效」。行为不变（不猜、落回下面的 storages 缓存），
+      // 但必须留下一条带机器可读 code 的 warn —— 这是本仓那条教训的正面形态：
+      // 注释承诺的防线，必须在运行时真的发生（可观测）。
+      host.log.warn(msgOf(host)('host.parentRelationsUnavailable', { reason: errorMessage(err) }), {
+        code: 'parent-relations-unavailable',
+        source: 'sessionHealthKnownIds',
+      })
     }
   }
   if (ids.size > 0) return ids
@@ -2044,7 +2591,10 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
     },
     writeText: async (relPath, text) => { await host.fs.writeFile(relPath, Buffer.from(text, 'utf8')) },
     resolveBundle: bundleResolvable,
-    parseYaml: (text) => yaml.load(text),
+    // 启动关键 yaml 里包含**两层 cordis.patch.yml**（BOOT_CRITICAL_RELS），它们是 DSH 的专用方言
+    // （`!!js`）。用缺省 schema 解析会把用户的 patch 层误报成「启动关键文件无法解析」——
+    // 与 issue #75 同一个根因，只是症状换成了假警报。其余设置类 yaml 用同一 schema 只会更宽松。
+    parseYaml: (text) => loadPatchDocument(text),
     msg,
   })
 
@@ -2189,8 +2739,7 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
    *  缺失通道 = 尚未加载（启动竞态窗口）；读取/使用处兜底 defaultSyncSelection。 */
   const selectionCache: Partial<Record<SyncTransportType, SyncSelection>> = {}
   void readAllSyncSelections(syncDir).then((all) => {
-    selectionCache.git = all.git
-    selectionCache.webdav = all.webdav
+    for (const channel of SYNC_CHANNELS) selectionCache[channel] = all[channel]
   }).catch(() => { /* 读失败保持缺省 */ })
 
   /** 确保指定通道缓存已加载（status/save 路由调用；启动竞态兜底）。 */
@@ -2251,11 +2800,15 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
 
   const selectionViewByChannel = async (): Promise<Record<SyncTransportType, SelectionView>> => {
     const all = await readAllSyncSelections(syncDir)
-    selectionCache.git = all.git
-    selectionCache.webdav = all.webdav
     const view = (sel: SyncSelection): SelectionView =>
       ({ mode: sel.mode, sections: sel.sections, sessionsLimit: sel.sessionsLimit, sessionsInclude: sel.sessionsInclude, encrypt: sel.encrypt, includeSecrets: sel.includeSecrets })
-    return { git: view(all.git), webdav: view(all.webdav) }
+    // 通道集合来自唯一枚举（SYNC_CHANNELS）；不得穷举字面量（漏一处即该通道状态静默缺失）
+    const out = {} as Record<SyncTransportType, SelectionView>
+    for (const channel of SYNC_CHANNELS) {
+      selectionCache[channel] = all[channel]
+      out[channel] = view(all[channel])
+    }
+    return out
   }
 
   /** 该通道的持久化选择是否显式勾选了「可选分区」（sessions）—— 决定用户驱动的拉取侧能否看见它。 */
@@ -2287,6 +2840,41 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
         timeoutMs: WEBDAV_TIMEOUT_MS,
         msg,
       })
+    } else if (isS3Config(cfg)) {
+      // S3 兼容系（s3/oss/cos/minio/kodo 共用同一实现 + 变体表）：AccessKey Secret 只经
+      // credentials 端口现取（永不落盘 / 永不出宿主）；endpoint/region 空串由变体模板兜底。
+      const provider = cfg.s3.provider
+      transport = new S3Transport({
+        provider,
+        bucket: cfg.s3.bucket,
+        accessKeyId: cfg.s3.accessKeyId,
+        credentials: {
+          getSecretAccessKey: async () => {
+            const resolved = await credentials.resolve(credentialRef(cloudSecretRef(provider)))
+            return resolved?.value ?? ''
+          },
+        },
+        ...(cfg.s3.endpoint === '' ? {} : { endpoint: cfg.s3.endpoint }),
+        ...(cfg.s3.region === '' ? {} : { region: cfg.s3.region }),
+        ...(cfg.s3.prefix === undefined ? {} : { prefix: cfg.s3.prefix }),
+        ...(cfg.s3.pathStyle === undefined ? {} : { pathStyle: cfg.s3.pathStyle }),
+        ...(cfg.s3.dialectId === undefined ? {} : { dialectId: cfg.s3.dialectId }),
+        msg,
+      })
+    } else if (isGistConfig(cfg)) {
+      // GitHub Gist：token 只经 credentials 端口现取（只写不回读）
+      transport = new GistTransport({
+        gistId: cfg.gist.gistId,
+        credentials: {
+          getToken: async () => {
+            const resolved = await credentials.resolve(credentialRef(cloudSecretRef(GIST_PROVIDER)))
+            return resolved?.value ?? ''
+          },
+        },
+        ...(cfg.gist.apiBaseUrl === undefined ? {} : { apiBaseUrl: cfg.gist.apiBaseUrl }),
+        ...(cfg.gist.filePrefix === undefined ? {} : { filePrefix: cfg.gist.filePrefix }),
+        msg,
+      })
     } else {
       transport = new GitTransport({
         repoUrl: cfg.git.repoUrl,
@@ -2522,6 +3110,9 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
       const restoreOpts = {
         snapshotDir: dir, homeDir: host.homeDir, profile: host.profile, settingsPath: undefined, msg,
         snapshotsRoot: snapshotsDir, environmentFingerprint: host.phase3Recovery?.recoveryEnvFingerprint ?? 'unknown', requireOperationBound: true,
+        // F-4：本机**权威**版本（拉起本宿主的运行时 = profileContext.installAnchor 解析出的 dshVersion）——
+        // 与快照记录的来源版本不同时产出一条可见告警动作（不阻断恢复）。
+        currentDshVersion: host.dshVersion,
       }
       const plan = await planRestore(restoreOpts)
       const report = await executeRestorePlan(plan, makeRestoreExecutor(dir, host, host.profile), (info) => {
@@ -2575,6 +3166,12 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
       profileLauncher,
       profileRuntime,
       profiles,
+      // F-2：官方 session.export 通道只需要「宿主自己能不能发一次本机请求」与「web 端口」。
+      // 后者在 apply() 里 webServer 就绪时才赋值，而本构造发生在它之前 —— 因此这里不能直接
+      // 抓 host.webPort 的值（那一刻恒 undefined）。改成读一个**活盒子**：apply() 往盒子里写，
+      // 路由表在请求期从同一个盒子取值（见 apply() 的 webServer 就绪段）。
+      get sessionExportFetch() { return host.fetch },
+      get sessionExportPort(): number | undefined { return host.webPort },
       // T4：会话体检（只读）。宿主侧注入「本机会话库扫描」的依赖来源 —— 路由不许自己读盘。
       sessionHealth: {
         // profileDir/dataDir 不在本作用域（apply() 的局部量），体检只认 homeDir 与两个事实来源
@@ -2604,6 +3201,20 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
       syncDir,
       syncPasswordConfigured,
       syncSectionCatalog,
+      // 关于页「立即更新」：用户显式点击后的写动作（官方 dsh plugin 通道，钉住精确版本）。
+      // 为什么经 env 注入而不是路由里直接 spawn：路由不持 profileDir/profile，也不该自己起
+      // 子进程（与 sessionHealth 同一条纪律：宿主注入依赖来源）。
+      selfUpdate: async (targetVersion: string): Promise<SelfUpdateOutcome> => {
+        const installedSpec = readProfileManifest(host.profileDir)?.dependencies?.[PLUGIN_NPM_PACKAGE]
+        const plan = planSelfUpdate({
+          current: PLUGIN_VERSION,
+          target: targetVersion,
+          profile: host.profile,
+          installedSpec,
+        })
+        if (!plan.ok) return plan
+        return await runSelfUpdate(plan, { runner: runDshPlugin, profileDir: host.profileDir, profile: host.profile })
+      },
       syncSessions,
       tmpDir,
       tryAppendHistory,
@@ -2613,9 +3224,9 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
   }
 
   /**
-   * 路由表：本文件只保留被源码级守卫按**文件窗口**钉住的 8 条（host-entry 审计 F-04 记录的
+   * 路由表：本文件只保留被源码级守卫按**文件窗口**钉住的 7 条（host-entry 审计 F-04 记录的
    * tests/host/**、src/core/model-tools.test.ts、src/core/phase1-wiring.test.ts 的窗口断言）。
-   * 其余 57 条已按域拆到 src/routes/*.ts，由 buildRoutes 组装。
+   * 其余 71 条已按域拆到 src/routes/*.ts，由 buildRoutes 组装。
    * 注册顺序不影响匹配：命名路由必须互不相同（webServer 契约）。
    */
   const routeEnv: RouteEnvInferred = makeRouteEnv()
@@ -2865,8 +3476,13 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
             if (facade?.parentRelations !== undefined) {
               try {
                 sessionsEntry.items = applySessionParentLinks(sessionsEntry.items, subagentParentMap(await facade.parentRelations()))
-              } catch {
-                /* 关系读不到 → 不标父对话（不猜），联动静默失效但预览不受影响 */
+              } catch (err) {
+                // T8-F2：行为不变（不标父对话、不猜、预览绝不打挂），但**必须记 warn**：
+                // 否则「选择器勾父带子静默不联动」对用户完全不可见（正是 F-1 想消除的那种失败形态）。
+                host.log.warn(msgOf(host)('host.parentRelationsUnavailable', { reason: errorMessage(err) }), {
+                  code: 'parent-relations-unavailable',
+                  source: 'exportPreview',
+                })
               }
             }
           }
@@ -3381,6 +3997,12 @@ export function apply(ctx: Context, config?: Config): void {
   }
   // 端口就绪 → 重新自报一次心跳（其它实例的「运行中」徽章与端口信息靠它；token 永不落盘）。
   webPort.value = webServer.port
+  // F-2：宿主自请求走这个端口（探测/代理 DSH 自己的 /api/session.export）——
+  // 必须在注册路由**之前**赋值，否则首次探测拿到 undefined 会如实降级成「拿不到状态码」。
+  // 注：本插件是 bundle 包、宿主半没有热重载，端口变化只有重启一次才可能发生。
+  // routeEnv 的 sessionExportPort 是**活 getter**（读 host.webPort），因此这里赋值对已构造好的
+  // 路由表同样生效 —— 不需要重建路由。
+  host.webPort = webServer.port
   profileRuntime.announce()
   ctx.effect(() => {
     const disposers = registerRoutes(webServer, routes)