[Bug] 0.1.7-alpha.1 and alpha.2: a failed startup still consumes settings.yaml - legacy sections import into a disposed context and are lost permanently

[ruttybob]

Summary

Upgrading 0.1.6-alpha.2 → 0.1.7-alpha.1, the first launch consumed ~/.dsh/settings.yaml although that launch had failed its startup audit. @deepseek-ai/dsh-app-boot disposes the plugin tree when the audit rejects a required entry, and the one-shot legacy import is a continuation of the same loader-settled moment, so all 10 sections were written into an already-disposed context:

settings-forms: settings: section %s of %s was not imported into entry %s
  'ui-onboarding', '$HOME/.dsh/settings.yaml.imported', 'ui-settings-general'

settings-forms: Error: cannot get required service "configEditor" in inactive context
    at SettingsForms.write (packages/settings/settings/src/index.ts:382:37)
    at SettingsForms.update (packages/settings/settings/src/index.ts:349:16)
    at SettingsForms.importLegacyDocument (packages/settings/settings/src/index.ts:251:20)

The document is renamed to settings.yaml.imported before the first write (index.ts:245-246, described in packages/settings/settings/README.md:35), and the import returns early whenever settings.yaml is absent (index.ts:244), so no later launch retries. The operator-visible result: the settings page comes up with defaults — LLM providers, theme, permission preset, default agent preset, default model, subagent model selection all reverted — and the only surviving copy of those values is the renamed file.

This matters beyond one deployment because the import path is new in this release (601d6761e4, "feat(settings): project volatile Config through profile-backed forms (#4587)", contained in dsh-v0.1.7-alpha.1): every user upgrading from ≤0.1.6 goes through it exactly once. The same upgrade also makes a failing first launch likely, since 0.1.7 refuses to activate entries whose artifacts are stale (web-app frontend dist, client-modules bundles), and the documented upgrade step is a rebuild — one launch before the rebuild finishes is enough to lose the settings. The import path is unchanged in dsh-v0.1.7-alpha.2: between the two tags this package differs only in its package.json, so the failure reproduces there as well.

Environment

• dsh 0.1.7-alpha.1 (c36a83ff6b), source launch, macOS 15 (arm64), Node v24.18.0
• profile web; its patch enables HMR (- id: hmr, disabled: false)
• also checked on dsh 0.1.7-alpha.2 (00102833df): the settings package differs between alpha.1 and alpha.2 only in its package.json, so this reproduces there too
• $HOME/.dsh/settings.yaml left by 0.1.6-alpha.2, 10 sections: ui-onboarding, ui-theme, agent-presets, permission, agent-default-model, llm-pi-ai, provider-quotas, dsh-better-sidebar, glance-theme, subagent-model-selection

Timeline

From the startup diagnostics dump of that launch ($HOME/.dsh/logs/startup-2026-09-22T14-06-35.304Z-<uuid>.log):

ts 1790085985630 = 14:06:25.630Z  launch: 2 required plugins did not activate
                                  (stale frontend dist / client bundles — an understood, separate failure;
                                   the loader needs ~10 s to settle the pending entries)
ts 1790085995278 = 14:06:35.278Z  hmr: 'config reload at %C failed', '$HOME/.dsh/profiles/web/package.json'
ts 1790085995278 = 14:06:35.278Z  hmr: Error: HMR is disposed            (packages/boot/hmr/src/index.ts:142)
ts 1790085995288 = 14:06:35.288Z  settings-forms: 'section ui-onboarding … was not imported'
ts 1790085995288 = 14:06:35.288Z  settings-forms: Error: cannot get required service "configEditor" in inactive context
… 10 sections, all at ts …288

settings: imported %s into profile %s (index.ts:257) appears in no log of any launch.

Root cause

1. packages/settings/settings/src/index.ts:235 — the import is a one-shot continuation of Loader settlement:
   void ctx.root.loader.await().then(() => this.importLegacyDocument()).catch((error) => { ctx.logger.error(error) }).
2. packages/boot/app-boot/src/index.ts:971-977 — the startup audit is a continuation of the same moment: await ctx.get('loader')?.await(), then await auditStartupEntries(ctx, binName) throws StartupError for inactive required entries, and the catch disposes the tree with await ctx.fiber.dispose(). On a failed launch, the import and the disposal of its own fiber therefore start from the same settled Loader.
3. index.ts:382 — every write resolves this.ownerContext.configEditor on the context captured in the constructor. After disposal that is cannot get required service "configEditor" in inactive context (vendor/cordis/src/reflect.ts:160).
4. index.ts:248-256 — the per-section try/catch downgrades that to a warning and the loop continues; the same catch is the intended path for "the running composition rejects this section" (README:35), so a dead service and a rejected section are indistinguishable here.
5. index.ts:245-246 renames the document before any write — deliberate, so that a partial import never repeats; index.ts:244 then skips everything on later launches because settings.yaml no longer exists. The values survive only in settings.yaml.imported, and nothing tells the operator.
6. this.closed already exists (set by the effect disposer, index.ts:227) but importLegacyDocument never consults it, so the service keeps writing after its own disposal. Note also that index.ts:257 logs settings: imported … unconditionally after the loop: a launch that imported nothing can still report success.

The hmr: config reload … failed / HMR is disposed pair in the same 10 ms window is a symptom of that teardown (closing is only set when the HMR service itself is disposed), not a second cause; a profile recomposition during the same window would fail in exactly the same way.

Minimal reproduction

# a harness home holding a legacy document
printf 'ui-theme:\n  preference: dark\n' > "$HOME/.dsh/settings.yaml"

# start a profile whose startup audit must fail: e.g. leave lib/ or dist/ older than
# sources so @deepseek-ai/dsh-client-modules or @deepseek-ai/dsh-web-app refuses to activate
dsh --profile web --no-open
# ⇒ settings.yaml becomes settings.yaml.imported; one warning per section:
#    cannot get required service "configEditor" in inactive context

dsh --profile web --no-open        # this launch succeeds
# ⇒ no import attempt, no warning; the value stays in settings.yaml.imported forever

Suggested fixes

1. Import only after a healthy startup. Schedule importLegacyDocument from application readiness (appReady / the app-boot/config-reload path) rather than from loader.await(); a launch that failed its audit then leaves the document untouched for the next launch.
2. Make the rename a postcondition. Import first, rename afterwards (or record per-section completion, or delete imported sections from the source), so a pass that wrote nothing can be retried.
3. Treat a disposed service as a failure, not as a section rejection. Check this.closed / context liveness before each write and abort the loop with an error that keeps the document, instead of 10 warnings and a success line.
4. Report loudly when nothing was imported. A boot that could not import any section should say so (settings: 0 of N sections imported; values remain in <path>.imported), so providers do not vanish without a trace.

Our workaround (no data was lost)

We restored all restorable sections by hand: each one became a config override row in $HOME/.dsh/profiles/web/cordis.patch.yml (- id: <entry id> plus config: …), validated against the 0.1.7 Config schemas; provider-quotas needed no restore because that plugin now keeps its own storage. Two sections could not be restored by configuration at all and are third-party plugin work: glance-theme (the plugin still calls the removed ctx.settings.register) and dsh-better-sidebar (not mounted any more).

Test to extend

packages/settings/settings/tests/configuration.spec.ts:310 ("imports the removed settings.yaml into the profile once and keeps rejected sections in the renamed file") covers rename-first and rejected sections, but never disposes the settings fiber while the import is in flight. A case that disposes the tree between start() and the first write — or that makes configEditor unavailable — would pin the ordering.

[ruttybob]

Patch for the two fixes that matter for this report: the readiness gate, and never consuming a document the composition could not import. It applies as-is to dsh-v0.1.7-alpha.1 (master too — the settings service is unchanged since the tag), and the failure reproduces in dsh-v0.1.7-alpha.2 as well: the only difference in this package between the two tags is its package.json.

What changes (packages/settings/settings/src/index.ts)

1. The one-shot import waits for the launcher's appReady — the signal whose own contract already says "a failed or externally terminated startup never calls it" (packages/boot/cmdline/src/index.ts:45). A host that provides no readiness signal keeps the Loader-settled timing, so nothing regresses there.
2. The document is read before the rename, and the owning fiber must be active to consume it: a service disposed while the read is in flight imports nothing instead of renaming the only copy.
3. The closing log line reports how many sections were restored and how many were rejected, instead of reporting a successful import after a pass that wrote nothing.

The rest of the patch is the three tests and the two READMEs (with the bilingual pairing record re-recorded).

Verification

Check	Result
pnpm exec vitest run packages/settings/settings packages/api/settings-controller	62 passed; packages/settings/settings/src/index.ts at 100% statements, branches, functions and lines
The two readiness tests against the unpatched source	both fail with expected false to be true — the document was consumed
pnpm exec tsc -b packages/settings/settings/tsconfig.json	clean
oxlint, verify-doc-budgets, verify-export-jsdoc, verify-translation-pairing	clean

The tests cover a startup that never commits readiness, a startup disposed while the pending import waits, and a host with no readiness signal at all.

Full patch (diff against dsh-v0.1.7-alpha.1)

diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index cf7563a580..f248245eee 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/settings/settings/README.md
-README.md: a44dd50a4614401afa6e05bb5d55313a8b833732
-README.zh.md: 0f7df0dec04159eaca4e143e10b4a8e6f81452a0
+README.md: b3265dea4cbc15fa791c233f72af73879f5a3093
+README.zh.md: 0607d35684f183dd1299ed0c481d8ddd2732bdf1
diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md
index a44dd50a46..b3265dea4c 100644
--- a/packages/settings/settings/README.md
+++ b/packages/settings/settings/README.md
@@ -32,7 +32,7 @@ Mount this plugin with Loader and [config-editor](../../boot/config-editor/READM
 
 This plugin has no configuration fields. Forms expose only volatile fields from active, uniquely addressed profile entries. Ordinary configuration remains editable through Cordis configuration files.
 
-Once the Loader has settled every entry after Settings starts, a `settings.yaml` left in the harness home by earlier releases is imported once: each section is written into the entry of the same id (`ui-developer-tools` → `ui-settings`, `ui-onboarding` → `ui-settings-general`, `shell` → the platform's shell executor entry), the file is renamed to `settings.yaml.imported` before the first write, and a section the running composition rejects is logged and stays only in the renamed file.
+Once the launcher commits startup — or, in a host that provides no readiness signal, once the Loader has settled every entry — a `settings.yaml` left in the harness home by earlier releases is imported once: each section is written into the entry of the same id (`ui-developer-tools` → `ui-settings`, `ui-onboarding` → `ui-settings-general`, `shell` → the platform's shell executor entry), the file is renamed to `settings.yaml.imported` before the first write, and a section the running composition rejects is logged and stays only in the renamed file. A startup that never commits, or that is disposed while the document is read, consumes nothing and leaves the document for the next launch.
 
 Reset restores the value beneath the profile override, including schema defaults. Home patches and command-line overlays take precedence; a form write that they would override is refused.
 
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index 0f7df0dec0..0607d35684 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -32,7 +32,7 @@ kind: "package-reference"
 
 此插件没有配置字段。表单只展示活动且可唯一定位的 profile 条目中的 volatile 字段。普通配置仍通过 Cordis 配置文件编辑。
 
-Settings 启动后、Loader 完成所有条目的加载时，早期版本留在 harness home 中的 `settings.yaml` 会被导入一次：每个 section 写入同名条目（`ui-developer-tools` → `ui-settings`、`ui-onboarding` → `ui-settings-general`、`shell` → 当前平台的 shell 执行器条目），文件在第一次写入前改名为 `settings.yaml.imported`，被当前组合拒绝的 section 会记录日志并只保留在改名后的文件中。
+启动提交后（宿主未提供就绪信号时则在 Loader 完成所有条目的加载后），早期版本留在 harness home 中的 `settings.yaml` 会被导入一次：每个 section 写入同名条目（`ui-developer-tools` → `ui-settings`、`ui-onboarding` → `ui-settings-general`、`shell` → 当前平台的 shell 执行器条目），文件在第一次写入前改名为 `settings.yaml.imported`，被当前组合拒绝的 section 会记录日志并只保留在改名后的文件中。从未提交、或在读取文档期间被释放的启动不会消耗该文档，会把它留给下一次启动。
 
 重置恢复 profile 覆盖层以下的值，包括 schema 默认值。Home patch 和命令行 overlay 优先级更高；表单写入若会被它们覆盖，则被拒绝。
 
diff --git a/packages/settings/settings/src/index.ts b/packages/settings/settings/src/index.ts
index e0586ecb24..6a93b1389a 100644
--- a/packages/settings/settings/src/index.ts
+++ b/packages/settings/settings/src/index.ts
@@ -232,29 +232,54 @@ export class SettingsForms extends Service {
     const ctx = ownerContext
     ctx.effect(() => () => { this.closed = true })
     ctx.on('app-boot/config-reload', () => { this.invalidate() })
-    void ctx.root.loader.await().then(() => this.importLegacyDocument()).catch((error: unknown) => { ctx.logger.error(error) })
+    void this.importLegacyDocumentAfterStartup().catch((error: unknown) => { ctx.logger.error(error) })
   }
 
-  /** Move the sections of the removed `settings.yaml` into the active profile once the Loader has settled every entry.
-   * The document is renamed before the first write, so a partial import never repeats; a section the running
-   * composition rejects is logged and remains only in the renamed file. */
+  /** Wait for a startup the launcher committed before touching the removed `settings.yaml`.
+   * A startup that fails disposes this service with the composition, and the document must survive it;
+   * a host that provides no readiness signal keeps the Loader-settled timing. */
+  private async importLegacyDocumentAfterStartup(): Promise<void> {
+    const ctx = this.ownerContext
+    const ready = ctx.get('appReady')
+    if (ready === undefined) {
+      await ctx.root.loader.await()
+    } else {
+      const committed = Promise.withResolvers<void>()
+      const cancel = ready.onReady(() => { committed.resolve() })
+      // A startup that never commits disposes this service; settle the wait so the import is not left pending.
+      ctx.effect(() => () => { cancel(); committed.resolve() })
+      await committed.promise
+    }
+    if (this.closed) return
+    await this.importLegacyDocument()
+  }
+
+  /** Move the sections of the removed `settings.yaml` into the active profile after a committed startup.
+   * The document is read before the rename and renamed before the first write, so a partial import never
+   * repeats; a section the running composition rejects is logged and remains only in the renamed file. */
   private async importLegacyDocument(): Promise<void> {
     const profile = this.ownerContext.profileContext
     const path = join(profile.home, 'settings.yaml')
     if (!existsSync(path)) return
+    const sections = parse(await readFile(path, 'utf8')) as Record<string, object> | null
+    // A composition disposed while the document was read imports nothing, so the document must survive it.
+    this.ownerContext.fiber.assertActive()
     const imported = `${path}.imported`
     await rename(path, imported)
-    const sections = parse(await readFile(imported, 'utf8')) as Record<string, object> | null
+    let restored = 0
+    let rejected = 0
     for (const [section, values] of Object.entries(sections ?? {})) {
       const ns = LEGACY_SECTION_ENTRIES[section] ?? section
       try {
         await this.update(ns, values)
+        restored += 1
       } catch (error) {
+        rejected += 1
         this.ownerContext.logger.warn('settings: section %s of %s was not imported into entry %s', section, imported, ns)
         this.ownerContext.logger.warn(error)
       }
     }
-    this.ownerContext.logger.info('settings: imported %s into profile %s', imported, profile.name)
+    this.ownerContext.logger.info('settings: imported %s of %s sections from %s into profile %s', restored, restored + rejected, imported, profile.name)
   }
 
   /** Register the calling plugin instance's page policy without changing its Config.
diff --git a/packages/settings/settings/tests/configuration-fixture.ts b/packages/settings/settings/tests/configuration-fixture.ts
index 4f81ec8d90..87187a9845 100644
--- a/packages/settings/settings/tests/configuration-fixture.ts
+++ b/packages/settings/settings/tests/configuration-fixture.ts
@@ -12,10 +12,30 @@ import Hmr from '@deepseek-ai/dsh-hmr'
 import DefaultModel from '@deepseek-ai/dsh-agent-default-model'
 import Settings from '../src/index.ts'
 
-export async function configurationFixture(options: { schema?: z; apply?: (ctx: Context, config: unknown) => void; hmr?: boolean } = {}) {
+export async function configurationFixture(options: { schema?: z; apply?: (ctx: Context, config: unknown) => void; hmr?: boolean; ready?: 'immediate' | 'manual' | 'absent' } = {}) {
   const home = realpathSync(mkdtempSync(join(tmpdir(), 'settings-config-')))
   const dir = join(home, 'profiles', 'test')
   onTestFinished(() => { rmSync(home, { recursive: true, force: true }) })
+  const readyListeners: (() => void)[] = []
+  let readyCommitted = options.ready !== 'manual'
+  const appReady = {
+    onReady: (listener: () => void): (() => void) => {
+      if (readyCommitted) {
+        listener()
+        return () => {}
+      }
+      readyListeners.push(listener)
+      return () => {
+        const pending = readyListeners.indexOf(listener)
+        if (pending >= 0) readyListeners.splice(pending, 1)
+      }
+    },
+  }
+  /** Commit the startup the way a launcher does once its startup audit passed. */
+  const commitReady = (): void => {
+    readyCommitted = true
+    for (const listener of readyListeners.splice(0)) listener()
+  }
   initProfile(dir, ['test-bundle'])
   const bundle = join(dir, 'node_modules', 'test-bundle')
   mkdirSync(bundle, { recursive: true })
@@ -40,7 +60,7 @@ export async function configurationFixture(options: { schema?: z; apply?: (ctx:
   const start = async (): Promise<Context> => {
     const ctx = await boot('test', join(dir, 'cordis.yml'), readProfilePatches('test', profile), (ctx) => {
       ctx.provide('profileContext', profile)
-      ctx.provide('appReady', { onReady: (listener: () => void) => { listener(); return () => {} } })
+      if (options.ready !== 'absent') ctx.provide('appReady', appReady)
       Object.assign(ctx.loader.builtins, {
         editor: ConfigEditor, settings: Settings, model: DefaultModel, probe: Probe,
       })
@@ -54,5 +74,5 @@ export async function configurationFixture(options: { schema?: z; apply?: (ctx:
     }
     return ctx
   }
-  return { ctx: await start(), profile, home, start }
+  return { ctx: await start(), profile, home, start, commitReady }
 }
diff --git a/packages/settings/settings/tests/configuration.spec.ts b/packages/settings/settings/tests/configuration.spec.ts
index 5bafea1e5b..d8c4fe38dc 100644
--- a/packages/settings/settings/tests/configuration.spec.ts
+++ b/packages/settings/settings/tests/configuration.spec.ts
@@ -1,11 +1,18 @@
 /** Real profile patch behavior and reference lifetime. */
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { setImmediate } from 'node:timers/promises'
 import { expect, it, vi } from 'vitest'
 import { parse } from 'yaml'
 import z from '@deepseek-ai/schemastery'
 import { configurationFixture as fixture } from './configuration-fixture.ts'
 
+/** Let pending filesystem callbacks run without a wall-clock wait. */
+async function settleIo(): Promise<void> {
+  await setImmediate()
+  await setImmediate()
+}
+
 it('persists a model edit, updates the real consumer without remounting, and restores it at restart', async () => {
   const { ctx, profile, start } = await fixture()
   const consumer = ctx.agentDefaultModel
@@ -339,6 +346,45 @@ it('imports the removed settings.yaml into the profile once and keeps rejected s
   expect(blocked.agentDefaultModel.currentSelection().model).toBe('legacy')
 })
 
+it('imports the legacy document only after the launcher commits startup', async () => {
+  const { ctx, home, start, commitReady } = await fixture({ ready: 'manual', hmr: false })
+  const legacy = join(home, 'settings.yaml')
+  writeFileSync(legacy, 'default-model:\n  model: legacy\n')
+  await ctx.fiber.dispose()
+  const next = await start()
+  await settleIo()
+  expect(existsSync(legacy)).toBe(true)
+  expect(existsSync(`${legacy}.imported`)).toBe(false)
+  expect(next.agentDefaultModel.currentSelection().model).toBe('original')
+  commitReady()
+  await vi.waitFor(() => { expect(existsSync(`${legacy}.imported`)).toBe(true) })
+  await vi.waitFor(() => { expect(next.agentDefaultModel.currentSelection().model).toBe('legacy') })
+})
+
+it('leaves the legacy document for the next launch when startup never commits', async () => {
+  const { ctx, home, start, commitReady } = await fixture({ ready: 'manual', hmr: false })
+  const legacy = join(home, 'settings.yaml')
+  writeFileSync(legacy, 'default-model:\n  model: legacy\n')
+  await ctx.fiber.dispose()
+  const next = await start()
+  await next.fiber.dispose()
+  await settleIo()
+  expect(existsSync(legacy)).toBe(true)
+  expect(existsSync(`${legacy}.imported`)).toBe(false)
+  const again = await start()
+  commitReady()
+  await vi.waitFor(() => { expect(again.agentDefaultModel.currentSelection().model).toBe('legacy') })
+})
+
+it('imports the legacy document after Loader settlement in a host without a readiness signal', async () => {
+  const { ctx, home, start } = await fixture({ ready: 'absent', hmr: false })
+  const legacy = join(home, 'settings.yaml')
+  writeFileSync(legacy, 'default-model:\n  model: legacy\n')
+  await ctx.fiber.dispose()
+  const next = await start()
+  await vi.waitFor(() => { expect(next.agentDefaultModel.currentSelection().model).toBe('legacy') })
+})
+
 it('describes an entry whose required field only the profile supplies, and reports a failed refresh instead of crashing', async () => {
   const { ctx, profile, start } = await fixture({
     schema: z.object({ ordinary: z.string(), required: z.string().required(), count: z.number().default(2).volatile() }),

Happy to open this as a PR from a fork if that is easier to review than a patch in a comment.

[argszero]

I reproduced your version claims independently, verified the mechanism anchor by anchor, and read the patch. The diagnosis is exact and the readiness gate is the right fix. Two things I would want closed before it lands, both supported by code already in the tree — one of them decides whether the fix is complete or conditional.

Your version claims, independently confirmed

• 601d6761e4 is feat(settings): project volatile Config through profile-backed forms (#4587), and git tag --contains lists both dsh-v0.1.7-alpha.1 and dsh-v0.1.7-alpha.2.
• git diff --stat dsh-v0.1.7-alpha.1 dsh-v0.1.7-alpha.2 -- packages/settings/settings/ → package.json | 38 +++---, one file, exactly as you said.
• git diff --stat dsh-v0.1.7-alpha.2 HEAD -- packages/settings/settings/src/ → empty: the source is unchanged at HEAD, so your patch targets current master and the defect is live there.

Mechanism anchors all hold at HEAD: the one-shot continuation (§1) is index.ts:235; the document read happens before the first write and after the rename (§5) is index.ts:244-246; the per-section try/catch that makes a dead service and a rejected section indistinguishable (§4) is index.ts:248-256; the unconditional success line (§6) is index.ts:257; this.closed is set at index.ts:231-233 and never consulted; the write resolves configEditor at index.ts:382. Your app-boot citation is :971-977 on alpha.1 and :994/:1001 at HEAD (audit, then await ctx.fiber.dispose() in the catch) — that ordering is what makes the readiness gate sound, because appReady.commit() in apps/cli/src/profile-boot.ts:311-315 sits after boot() returns and is therefore skipped when the audit rejects.

1. The fallback branch is where the loss survives, and the file next door already decided differently

Your fallback — no appReady ⇒ await ctx.root.loader.await() — reinstates the original schedule for exactly the hosts that can still lose the document. That is not hypothetical in this tree:

• packages/experimental/webworker-runtime/src/worker-host.ts:242-245 calls provideCmdline(hostCtx, { args, exit }) with no ready, so ctx.get('appReady') is undefined there and your branch takes the Loader-settled timing. Since that host boots a caller-supplied profile (:236), any profile that mounts settings through it keeps the data-loss path — silently, because nothing in the fallback reports that it took it.
• packages/boot/hmr/src/index.ts:208-209 answers the same question the other way: const ready = this.ownerContext.get('appReady'); if (ready === undefined) throw new Error('Profile HMR requires application readiness'). It refuses to run rather than quietly reverting to the unsafe schedule.

So the choice is already made once in this family, and the fallback is the one place where an absent readiness signal silently keeps the bug. It is also why your third test reads the way it does — 'imports the legacy document after Loader settlement in a host without a readiness signal' asserts the fallback imports. The assertion is correct for the behaviour you implemented; the point is that it pins the residual exposure rather than surfacing it. Either matching HMR (refuse, or at minimum warn once that readiness is absent and the import is taking the Loader-settled path), or closing the launcher contract by passing ready in worker-host.ts, would make the completeness of the fix checkable instead of dependent on every host remembering.

2. The rename is still not a postcondition — the guard is a single instant

Your suggestion 2 is not implemented by the patch. Order today is: read → assertActive() → rename → loop (index.ts:241-257 in your version). The liveness check runs once, before the rename; nothing re-checks during the loop. A disposal that lands between the rename and the last write throws cannot get required service "configEditor" in inactive context per remaining section, each caught as a rejection, so the loop completes and the document is already consumed. Your restored/rejected counters improve the report but not the outcome: restored: 0, rejected: 10 is the same operator-visible result as the bug, only described.

That window is reachable from the event your own timeline already contains — the hmr: config reload … failed pair lands in the same 10 ms. A profile reload or recomposition that arrives after readiness commits but during the import reproduces the loss with the readiness gate in place.

The small delta that closes the class: keep the gate, then move the rename after the loop (flush-to-imported, not rename-then-import). The objection you might expect — "a partial import would then repeat" — does not apply here, because update merges rather than replaces: mergeLayers(current, input) at index.ts:347-350. Re-applying the same sections is idempotent, so the failure direction becomes retry instead of loss; the cost is that a crash mid-import leaves both files until the next launch reconciles them. That trade is the one worth arguing about, and it is a much smaller argument than losing ten sections.

One smaller point in the same area: with the counters in place, restored === 0 && rejected > 0 still logs at info. That is the one case where the operator must act, and your suggestion 4 asks for it to be loud — a warn on that branch would close it.

Prevention is core; recovery is mountable, and it is what your workaround did by hand

Prevention is not a plugin surface: the import is scheduled inside the SettingsForms constructor (index.ts:235, :232-234), which runs during Loader mount, and a plugin cannot intercept it. Watching is equally closed — the failure is only ever a logger.warn, and the success line is emitted regardless. Core/upstream, as your report concludes.

Recovery is a different story, and it maps onto what you had to do manually. ctx.settings (packages/settings/settings/src/index.ts:38-42) is a public context service whose write path is public and is the same one the failed import calls: update(ns, patch) (:347), replace (:357), mutate (:367), plus describe() (:302) for reading live values, and the document path from <profile.home>/settings.yaml.imported. So a plugin can re-apply a consumed settings.yaml.imported through the supported API, with the same per-section warnings, instead of an operator reconstructing eight sections as cordis.patch.yml rows by hand and validating each against the 0.1.7 schemas.

One boundary worth naming, since it decides how clean that plugin can be: LEGACY_SECTION_ENTRIES (index.ts:201-206) is module-private, so an out-of-tree recovery plugin has to duplicate the three documented aliases (ui-developer-tools → ui-settings, ui-onboarding → ui-settings-general, the platform shell entry; README:35 documents all three) or drop the aliasing and re-apply only identity-named sections. Exporting that map would make the recovery path exactly as capable as the import it recovers. I am treating that as the next thing to build on my side: the round-trip you had to perform by hand is a good plugin-sized hole, and its only real design question is how it decides when to re-apply — an explicit invocation is the honest answer, because silently re-applying an old document over the user's later edits would be its own bug.

Thanks — this is the clearest write-up I have read of the 0.1.7 upgrade path; the timeline and the "same settled Loader" framing are what made it possible to locate the window precisely.

[ruttybob]

Both points are addressed in the updated patch below.

1. The fallback now announces itself. When appReady is absent, the import logs settings: no launcher readiness signal; the removed settings.yaml imports on Loader settlement, where a failed startup can dispose this service mid-import, and the no-readiness test asserts the warning. I kept the Loader-settled path rather than refusing: worker-host boots a caller-supplied profile but produces no readiness signal of its own today, so refusing would strand the import there entirely — the honest completion on your side is giving that host a readiness signal to commit, and the warning then becomes unnecessary. Point taken that the third test previously pinned the residual exposure; it now pins the warning plus the import.

2. The rename is a postcondition now. Order is read → assertActive → section loop → rename. The failure direction is retry instead of loss, exactly for the mergeLayers reason you gave. One upstream assertion had to move with it: the case where .imported is a directory used to assert the pre-write value of the model; the sections are now written before the rename fails, so the test asserts the applied value, and a pass that cannot rename re-imports on the next launch — idempotent, and loud about it.

3. restored === 0 && rejected > 0 logs at warn (asserted by a new test).

One trivia your review flushed out, for anyone asserting warnings in tests: the vendored logger's default exporter level is INFO, and WARN is less severe in that scale, so warns silently never reach logger.buffer (or a levels-less exporter) — the fixture now registers levels: { default: 2 } to capture them.

Verification

Check	Result
pnpm exec vitest run packages/settings/settings packages/api/settings-controller	63 passed; packages/settings/settings/src/index.ts at 100% statements, branches, functions and lines
pnpm exec tsc -b packages/settings/settings/tsconfig.json, oxlint, verify-doc-budgets, verify-export-jsdoc, verify-translation-pairing	clean

On recovery: agreed on explicit invocation as the only honest trigger, and exporting LEGACY_SECTION_ENTRIES (or moving the aliases somewhere importable) is a one-line addition to this patch if you want it bundled with the recovery plugin work — say the word.

Full updated patch (diff against dsh-v0.1.7-alpha.1; applies to master)

diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index cf7563a580..60adc15841 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/settings/settings/README.md
-README.md: a44dd50a4614401afa6e05bb5d55313a8b833732
-README.zh.md: 0f7df0dec04159eaca4e143e10b4a8e6f81452a0
+README.md: c7b1a0c04fb873fa93a02b63fea16a1781642c62
+README.zh.md: f7d0fd05019e6f72e029137d1c3f9cbc3af1e583
diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md
index a44dd50a46..c7b1a0c04f 100644
--- a/packages/settings/settings/README.md
+++ b/packages/settings/settings/README.md
@@ -32,7 +32,7 @@ Mount this plugin with Loader and [config-editor](../../boot/config-editor/READM
 
 This plugin has no configuration fields. Forms expose only volatile fields from active, uniquely addressed profile entries. Ordinary configuration remains editable through Cordis configuration files.
 
-Once the Loader has settled every entry after Settings starts, a `settings.yaml` left in the harness home by earlier releases is imported once: each section is written into the entry of the same id (`ui-developer-tools` → `ui-settings`, `ui-onboarding` → `ui-settings-general`, `shell` → the platform's shell executor entry), the file is renamed to `settings.yaml.imported` before the first write, and a section the running composition rejects is logged and stays only in the renamed file.
+Once the launcher commits startup — or, in a host that provides no readiness signal, once the Loader has settled every entry, which is logged as a warning — a `settings.yaml` left in the harness home by earlier releases is imported once: each section is written into the entry of the same id (`ui-developer-tools` → `ui-settings`, `ui-onboarding` → `ui-settings-general`, `shell` → the platform's shell executor entry), and a section the running composition rejects is logged. The document is renamed to `settings.yaml.imported` after the pass, not before it: section updates merge rather than replace, so an interrupted pass repeats on the next launch instead of consuming the document. A startup that never commits, or that is disposed while the document is read, consumes nothing and leaves the document for the next launch.
 
 Reset restores the value beneath the profile override, including schema defaults. Home patches and command-line overlays take precedence; a form write that they would override is refused.
 
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index 0f7df0dec0..f7d0fd0501 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -32,7 +32,7 @@ kind: "package-reference"
 
 此插件没有配置字段。表单只展示活动且可唯一定位的 profile 条目中的 volatile 字段。普通配置仍通过 Cordis 配置文件编辑。
 
-Settings 启动后、Loader 完成所有条目的加载时，早期版本留在 harness home 中的 `settings.yaml` 会被导入一次：每个 section 写入同名条目（`ui-developer-tools` → `ui-settings`、`ui-onboarding` → `ui-settings-general`、`shell` → 当前平台的 shell 执行器条目），文件在第一次写入前改名为 `settings.yaml.imported`，被当前组合拒绝的 section 会记录日志并只保留在改名后的文件中。
+启动提交后（宿主未提供就绪信号时则在 Loader 完成所有条目的加载后，并记录警告），早期版本留在 harness home 中的 `settings.yaml` 会被导入一次：每个 section 写入同名条目（`ui-developer-tools` → `ui-settings`、`ui-onboarding` → `ui-settings-general`、`shell` → 当前平台的 shell 执行器条目），被当前组合拒绝的 section 会记录日志。文档在整轮导入完成后才改名为 `settings.yaml.imported`：section 更新是合并而非替换，因此被打断的一轮会在下次启动时重试，而不是消耗掉文档。从未提交、或在读取文档期间被释放的启动不会消耗该文档，会把它留给下一次启动。
 
 重置恢复 profile 覆盖层以下的值，包括 schema 默认值。Home patch 和命令行 overlay 优先级更高；表单写入若会被它们覆盖，则被拒绝。
 
diff --git a/packages/settings/settings/src/index.ts b/packages/settings/settings/src/index.ts
index e0586ecb24..57aac3fe4a 100644
--- a/packages/settings/settings/src/index.ts
+++ b/packages/settings/settings/src/index.ts
@@ -232,29 +232,63 @@ export class SettingsForms extends Service {
     const ctx = ownerContext
     ctx.effect(() => () => { this.closed = true })
     ctx.on('app-boot/config-reload', () => { this.invalidate() })
-    void ctx.root.loader.await().then(() => this.importLegacyDocument()).catch((error: unknown) => { ctx.logger.error(error) })
+    void this.importLegacyDocumentAfterStartup().catch((error: unknown) => { ctx.logger.error(error) })
   }
 
-  /** Move the sections of the removed `settings.yaml` into the active profile once the Loader has settled every entry.
-   * The document is renamed before the first write, so a partial import never repeats; a section the running
-   * composition rejects is logged and remains only in the renamed file. */
+  /** Wait for a startup the launcher committed before touching the removed `settings.yaml`.
+   * A startup that fails disposes this service with the composition, and the document must survive it;
+   * a host that provides no readiness signal keeps the Loader-settled timing and logs that it did. */
+  private async importLegacyDocumentAfterStartup(): Promise<void> {
+    const ctx = this.ownerContext
+    const ready = ctx.get('appReady')
+    if (ready === undefined) {
+      await ctx.root.loader.await()
+    } else {
+      const committed = Promise.withResolvers<void>()
+      const cancel = ready.onReady(() => { committed.resolve() })
+      // A startup that never commits disposes this service; settle the wait so the import is not left pending.
+      ctx.effect(() => () => { cancel(); committed.resolve() })
+      await committed.promise
+    }
+    if (this.closed) return
+    // Logged after the wait so a consuming logger records it: this schedule is the one a failed startup can
+    // still dispose mid-import.
+    if (ready === undefined) {
+      ctx.logger.warn('settings: no launcher readiness signal; the removed settings.yaml imports on Loader settlement, where a failed startup can dispose this service mid-import')
+    }
+    await this.importLegacyDocument()
+  }
+
+  /** Move the sections of the removed `settings.yaml` into the active profile after a committed startup.
+   * Section updates merge rather than replace, so the pass runs before the rename and an interrupted pass
+   * repeats on the next launch instead of consuming the document; a section the running composition rejects
+   * is logged and remains only in the renamed file. */
   private async importLegacyDocument(): Promise<void> {
     const profile = this.ownerContext.profileContext
     const path = join(profile.home, 'settings.yaml')
     if (!existsSync(path)) return
-    const imported = `${path}.imported`
-    await rename(path, imported)
-    const sections = parse(await readFile(imported, 'utf8')) as Record<string, object> | null
+    const sections = parse(await readFile(path, 'utf8')) as Record<string, object> | null
+    // A composition disposed while the document was read imports nothing, so the document must survive it.
+    this.ownerContext.fiber.assertActive()
+    let restored = 0
+    let rejected = 0
     for (const [section, values] of Object.entries(sections ?? {})) {
       const ns = LEGACY_SECTION_ENTRIES[section] ?? section
       try {
         await this.update(ns, values)
+        restored += 1
       } catch (error) {
-        this.ownerContext.logger.warn('settings: section %s of %s was not imported into entry %s', section, imported, ns)
+        rejected += 1
+        this.ownerContext.logger.warn('settings: section %s of %s was not imported into entry %s', section, path, ns)
         this.ownerContext.logger.warn(error)
       }
     }
-    this.ownerContext.logger.info('settings: imported %s into profile %s', imported, profile.name)
+    if (restored === 0 && rejected > 0) {
+      this.ownerContext.logger.warn('settings: none of %s sections of %s were imported; the values remain in the renamed document', rejected, path)
+    }
+    const imported = `${path}.imported`
+    await rename(path, imported)
+    this.ownerContext.logger.info('settings: imported %s of %s sections from %s into profile %s', restored, restored + rejected, imported, profile.name)
   }
 
   /** Register the calling plugin instance's page policy without changing its Config.
diff --git a/packages/settings/settings/tests/configuration-fixture.ts b/packages/settings/settings/tests/configuration-fixture.ts
index 4f81ec8d90..e2f6d4e6ac 100644
--- a/packages/settings/settings/tests/configuration-fixture.ts
+++ b/packages/settings/settings/tests/configuration-fixture.ts
@@ -12,10 +12,32 @@ import Hmr from '@deepseek-ai/dsh-hmr'
 import DefaultModel from '@deepseek-ai/dsh-agent-default-model'
 import Settings from '../src/index.ts'
 
-export async function configurationFixture(options: { schema?: z; apply?: (ctx: Context, config: unknown) => void; hmr?: boolean } = {}) {
+export async function configurationFixture(options: { schema?: z; apply?: (ctx: Context, config: unknown) => void; hmr?: boolean; ready?: 'immediate' | 'manual' | 'absent' } = {}) {
   const home = realpathSync(mkdtempSync(join(tmpdir(), 'settings-config-')))
   const dir = join(home, 'profiles', 'test')
   onTestFinished(() => { rmSync(home, { recursive: true, force: true }) })
+  const readyListeners: (() => void)[] = []
+  let readyCommitted = options.ready !== 'manual'
+  const appReady = {
+    onReady: (listener: () => void): (() => void) => {
+      if (readyCommitted) {
+        listener()
+        return () => {}
+      }
+      readyListeners.push(listener)
+      return () => {
+        const pending = readyListeners.indexOf(listener)
+        if (pending >= 0) readyListeners.splice(pending, 1)
+      }
+    },
+  }
+  /** Commit the startup the way a launcher does once its startup audit passed. */
+  const commitReady = (): void => {
+    readyCommitted = true
+    for (const listener of readyListeners.splice(0)) listener()
+  }
+  /** Boot-time warnings, captured through the logger exporter so boot-time messages stay observable. */
+  const warnings: string[] = []
   initProfile(dir, ['test-bundle'])
   const bundle = join(dir, 'node_modules', 'test-bundle')
   mkdirSync(bundle, { recursive: true })
@@ -40,7 +62,9 @@ export async function configurationFixture(options: { schema?: z; apply?: (ctx:
   const start = async (): Promise<Context> => {
     const ctx = await boot('test', join(dir, 'cordis.yml'), readProfilePatches('test', profile), (ctx) => {
       ctx.provide('profileContext', profile)
-      ctx.provide('appReady', { onReady: (listener: () => void) => { listener(); return () => {} } })
+      if (options.ready !== 'absent') ctx.provide('appReady', appReady)
+      // The logger's default exporter level is INFO, and WARN is less severe in this scheme, so warns need an explicit level.
+      ctx.logger.exporter({ levels: { default: 2 }, export: (message) => { if (message.type === 'warn') warnings.push(String(message.args[0])) } })
       Object.assign(ctx.loader.builtins, {
         editor: ConfigEditor, settings: Settings, model: DefaultModel, probe: Probe,
       })
@@ -54,5 +78,5 @@ export async function configurationFixture(options: { schema?: z; apply?: (ctx:
     }
     return ctx
   }
-  return { ctx: await start(), profile, home, start }
+  return { ctx: await start(), profile, home, start, commitReady, warnings }
 }
diff --git a/packages/settings/settings/tests/configuration.spec.ts b/packages/settings/settings/tests/configuration.spec.ts
index 5bafea1e5b..42461099c9 100644
--- a/packages/settings/settings/tests/configuration.spec.ts
+++ b/packages/settings/settings/tests/configuration.spec.ts
@@ -1,11 +1,18 @@
 /** Real profile patch behavior and reference lifetime. */
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { setImmediate } from 'node:timers/promises'
 import { expect, it, vi } from 'vitest'
 import { parse } from 'yaml'
 import z from '@deepseek-ai/schemastery'
 import { configurationFixture as fixture } from './configuration-fixture.ts'
 
+/** Let pending filesystem callbacks run without a wall-clock wait. */
+async function settleIo(): Promise<void> {
+  await setImmediate()
+  await setImmediate()
+}
+
 it('persists a model edit, updates the real consumer without remounting, and restores it at restart', async () => {
   const { ctx, profile, start } = await fixture()
   const consumer = ctx.agentDefaultModel
@@ -318,7 +325,8 @@ it('imports the removed settings.yaml into the profile once and keeps rejected s
   const legacy = join(home, 'settings.yaml')
   writeFileSync(legacy, 'default-model:\n  model: legacy\nfirst:\n  ordinary: rejected\nmissing:\n  count: 1\n')
   const restored = await start()
-  await vi.waitFor(() => { expect(restored.agentDefaultModel.currentSelection().model).toBe('legacy') })
+  await vi.waitFor(() => { expect(existsSync(`${legacy}.imported`)).toBe(true) })
+  expect(restored.agentDefaultModel.currentSelection().model).toBe('legacy')
   expect(parse(readFileSync(profile.patchPath, 'utf8'))).toContainEqual({ id: 'default-model', name: 'cordis:model', config: { provider: 'test', model: 'legacy' } })
   expect(restored.settings.describe({ redactSecrets: true }).find(row => row.ns === 'first')!.value).toEqual({ count: 2, list: [] })
   expect(existsSync(legacy)).toBe(false)
@@ -334,9 +342,60 @@ it('imports the removed settings.yaml into the profile once and keeps rejected s
   mkdirSync(join(home, 'settings.yaml.imported', 'occupied'), { recursive: true })
   const blocked = await start()
   const failures = (): unknown[] => blocked.logger.buffer.filter(message => message.type === 'error').map((message): unknown => message.args[0])
-  // The rename fails with EISDIR on POSIX and EPERM on Windows; the reported error names the rename either way.
+  // The rename fails with EISDIR on POSIX and EPERM on Windows; the reported error names the rename either
+  // way, and the sections were already written by the time it does.
   await vi.waitFor(() => { expect(failures().some(failure => failure instanceof Error && failure.message.includes('rename'))).toBe(true) })
-  expect(blocked.agentDefaultModel.currentSelection().model).toBe('legacy')
+  expect(blocked.agentDefaultModel.currentSelection().model).toBe('blocked')
+})
+
+it('imports the legacy document only after the launcher commits startup', async () => {
+  const { ctx, home, start, commitReady } = await fixture({ ready: 'manual', hmr: false })
+  const legacy = join(home, 'settings.yaml')
+  writeFileSync(legacy, 'default-model:\n  model: legacy\n')
+  await ctx.fiber.dispose()
+  const next = await start()
+  await settleIo()
+  expect(existsSync(legacy)).toBe(true)
+  expect(existsSync(`${legacy}.imported`)).toBe(false)
+  expect(next.agentDefaultModel.currentSelection().model).toBe('original')
+  commitReady()
+  await vi.waitFor(() => { expect(existsSync(`${legacy}.imported`)).toBe(true) })
+  await vi.waitFor(() => { expect(next.agentDefaultModel.currentSelection().model).toBe('legacy') })
+})
+
+it('leaves the legacy document for the next launch when startup never commits', async () => {
+  const { ctx, home, start, commitReady } = await fixture({ ready: 'manual', hmr: false })
+  const legacy = join(home, 'settings.yaml')
+  writeFileSync(legacy, 'default-model:\n  model: legacy\n')
+  await ctx.fiber.dispose()
+  const next = await start()
+  await next.fiber.dispose()
+  await settleIo()
+  expect(existsSync(legacy)).toBe(true)
+  expect(existsSync(`${legacy}.imported`)).toBe(false)
+  const again = await start()
+  commitReady()
+  await vi.waitFor(() => { expect(again.agentDefaultModel.currentSelection().model).toBe('legacy') })
+})
+
+it('imports the legacy document after Loader settlement in a host without a readiness signal', async () => {
+  const { ctx, home, start, warnings } = await fixture({ ready: 'absent', hmr: false })
+  const legacy = join(home, 'settings.yaml')
+  writeFileSync(legacy, 'default-model:\n  model: legacy\n')
+  await ctx.fiber.dispose()
+  const next = await start()
+  expect(warnings.some(text => text.includes('no launcher readiness signal'))).toBe(true)
+  await vi.waitFor(() => { expect(next.agentDefaultModel.currentSelection().model).toBe('legacy') })
+})
+
+it('warns when no section of the legacy document could be imported', async () => {
+  const { ctx, home, start, warnings } = await fixture()
+  const legacy = join(home, 'settings.yaml')
+  writeFileSync(legacy, 'missing:\n  count: 1\n')
+  await ctx.fiber.dispose()
+  await start()
+  await vi.waitFor(() => { expect(existsSync(`${legacy}.imported`)).toBe(true) })
+  expect(warnings.some(text => text.includes('none of'))).toBe(true)
 })
 
 it('describes an entry whose required field only the profile supplies, and reports a failed refresh instead of crashing', async () => {

[ruttybob]

Hi, Dear @argszero

Could you tell me whether this fix will be in the next release, or whether it should be replaced with something more correct?

[shaoqing404]

Additional macOS field report; this may overlap the migration issue, but I cannot attribute the writer to Desktop from the available evidence.

• Desktop app version: 0.2.0-rc.2. Global npm CLI version: @deepseek-ai/dsh 0.1.5-rc.2.
• The populated settings document survives as ~/.dsh/settings.yaml.imported (2,959 bytes; modified 2026-09-29 15:30 CST). It contains three provider routes and 15 models.
• The Desktop app bundle directory was modified at 17:55 CST. The account grant record in ~/.dsh/.credentials.yaml was modified at 22:39 CST. The active ~/.dsh/settings.yaml was a zero-byte file modified at 22:46 CST. Copying the imported document back restored the prior settings.
• Important caveat: settings.yaml.imported predates the Desktop app bundle timestamp, and file metadata does not identify which process later emptied settings.yaml. This report documents the data-loss symptom and version combination; it does not claim that Desktop sign-in conclusively caused it.

The user-visible failure is that shared Harness state can appear wiped after using the Desktop and CLI installations, with no migration or recovery warning. Expected behavior: preserve a last-known-good backup, migrate using an atomic write only after the destination accepts the entries, surface rejected sections in the UI, and never silently replace recoverable settings with an empty document. Could you identify which migration or write path can leave settings.yaml empty in this version combination?

[DDDFXYqiming]

我这个case和settings.yaml一次性导入被吞掉不是同一个机制，但在"配置看着没了"这个现象上撞了墙，供参考。

我的情况是跨版本抄配置。web 侧 runtime 是 rc.1，Desktop 内嵌是 rc.2，我把 web profile 的 cordis.patch.yml 整份搬给 Desktop，结构上六个 provider 都在，用官方 dump-config 加载也能正常组合，但 Desktop 设置页只显示内置的 DeepSeek。读源码确认设置页对 provider 完全不做过滤，llm-pi-ai 一挂载就把整份目录注册成可配置项，所以页面空说明插件没挂上而不是没填密钥。

顺带记一个 YAML 的坑。YAML 1.1 会把裸键 off 解析成布尔 false，再序列化就写成 false:。llm-pi-ai 的 resolveModelReasoning 只遍历 THINKING_LEVELS 取值，多出来的 "false" 键既不报错也不告警，直接被忽略，于是模型的关闭思考档凭空消失，其余档位照常工作，肉眼很难发现。判断标准是跑 dump-config，键正确时输出带引号显示 'off': none，被污染时显示 false: none。这条跟版本无关，任何一次配置重写都可能踩到。