Proposal: fix dual-instance bootstrapIncludes failure + misleading "root Include entry" error (with patch sketches)

[ArvinDevel]

Proposal: fix the dual-instance bootstrapIncludes failure + its misleading error message

@tianyicui @LegGasai @imccyu — tagging the top contributors for visibility. Happy to provide more probe data or test repos if useful.

Background

A cluster of "settings can never be saved" reports (#8928, #11853, #9579, #11321, #10282, #9750, #10407, #7675, #9542, #10532…) share one failure signature:

dsh: profile reload requires the root Include entry
{"code":"settings/rejected","message":"dsh: profile reload requires the root Include entry"}

I hit this on 0.2.1-rc.5 (Linux/WSL-like path, Intel macOS) and root-caused it with runtime instrumentation. The root Include is actually registered fine — mountRootInclude() and reconcileProfilePatches()→recompose() were simply executing against two different module instances of dsh-app-boot, each holding its own module-level bootstrapIncludes WeakMap. Registration lands in copy A's map; the lookup reads copy B's map; the get misses; the write path (settings/mutate → writeFileAtomic → reconcileProfilePatches) catches, rolls back the file on disk, and surfaces the error above — which claims the root Include is missing. It isn't.

Instrumented proof (two real copies loaded in one process):

[installation copy]  mountRootInclude: ctxId=ctx#1   ← registered in A
[profile copy]       recompose MISS                  ← looked up in B → throws

Moving the profile's duplicated node_modules away (30-second test) makes the error vanish and settings/mutate immediately works, with revisions and the optimistic lock behaving correctly — confirming the read-back validation and the optimistic lock are not involved (contrary to earlier hypotheses in #7959/#9299, which describe a different code path that passes on rc.5).

Known triggers for dual instances:

1. Windows path-case mismatch ([根源已确认·可规避][Windows][Desktop 0.2.0-rc.2] 安装路径大小写不一致导致 dsh-app-boot 双实例 → 设置页保存必失败 #8928 — not user error)
2. Profile dependencies declaring installation-shipped bundles (my case: manual pnpm add of dsh-base/dsh-web-app — user error, but nothing warns or blocks it, and initProfile() emits dependencies: {} so the tooling itself never writes this shape)
3. pnpm/link projection residue

---

Fix 1 (root cause): share the registry across module instances via Symbol.for

The failure exists because the registry is module-scoped. Hanging it off globalThis under a Symbol.for key merges all copies in-process (Node workers each boot their own tree, so they're unaffected):

// packages/boot/app-boot/src/index.ts
const BOOTSTRAP_INCLUDES_KEY = Symbol.for('dsh.app-boot.bootstrapIncludes')
const BOOT_RUNTIME_VERSION = '1' // bump when the Entry shape changes

interface BootstrapRegistry { version: string; map: WeakMap<Context, Entry> }

function getBootstrapRegistry(): BootstrapRegistry {
  const holder = globalThis as typeof globalThis & { [BOOTSTRAP_INCLUDES_KEY]?: BootstrapRegistry }
  const existing = holder[BOOTSTRAP_INCLUDES_KEY]
  if (existing !== undefined) {
    if (existing.version !== BOOT_RUNTIME_VERSION) {
      console.warn(`dsh: multiple dsh-app-boot versions in one process ` +
        `(registry v${existing.version} vs v${BOOT_RUNTIME_VERSION}); using the first-loaded registry`)
    }
    return existing
  }
  const created: BootstrapRegistry = { version: BOOT_RUNTIME_VERSION, map: new WeakMap() }
  holder[BOOTSTRAP_INCLUDES_KEY] = created
  return created
}

// replace bootstrapIncludes.set/get call sites with getBootstrapRegistry().map.set/get

Compatibility: packages/boot/app-boot/tests/user-patches.spec.ts:351-358 ("rejects a context without the launcher root Include") still passes — globalizing merges the module-instance dimension, not the Context dimension. A context that never mounted still throws.

Trade-off: cross-copy version skew is tolerated with a warning rather than a hard failure. A hard DI refactor (pass the root entry explicitly into ConfigEditor) is architecturally cleaner but touches cross-package signatures — probably too costly for preview stage.

Fix 2 (defense): make the error tell the truth + self-diagnose

Even with Fix 1, a get miss can legitimately mean "never mounted" (e.g. config-editor attached to a non-root ctx). The message should distinguish the two and hand the user an actionable hint:

const entry = bootstrapIncludes.get(ctx)
if (entry === undefined) {
  const duplicates = findDuplicateBootPackages(ctx) // probe <profile>/node_modules/@deepseek-ai via realpathSync
  throw new Error([
    `${binName}: settings persistence is unavailable — boot root Include not found in this module's registry.`,
    `thrown from: ${import.meta.url}`,
    duplicates.length > 0
      ? `likely cause: multiple copies of boot packages in this process:\n  ${duplicates.join('\n  ')}\n` +
        `fix: remove duplicated @deepseek-ai packages from the profile's node_modules ` +
        `(bundles must come from the installation, not the profile dependencies)`
      : `likely cause: config-editor is not attached to the boot root context`,
  ].join('\n'))
}

This is the highest value-per-line change: it doesn't eliminate the fault, but it turns "hours of misdirected debugging" (which misled #11853's original analysis and mine) into a 30-second diagnosis. If only one fix lands, land this one.

Fix 3 (prevention): block installation-shipped bundles at plugin add

listBundles() already computes shipped = Object.hasOwn(installation.dependencies ?? {}, name). Hoist that check into the add/install entry point:

const shipped = Object.hasOwn(this.installation.dependencies ?? {}, name)
if (shipped && !options.force) {
  throw new Error(`"${name}" is shipped with this dsh installation; it must not be added to the profile ` +
    `dependencies. Bundles are provided by the installation automatically. ` +
    `Pass --force only for deliberate local overrides (dual module instances will break settings persistence).`)
}

Hard-block with a --force escape hatch beats today's behavior (silent install → runtime explosion with an unrelated error message) for both normal and advanced users.

---

Suggested tests

1. Dual-instance injection: mount, then clear the module cache and reload the recompose copy; assert the write still succeeds (Fix 1) or at least the new diagnostic fires (Fix 2).
2. Keep user-patches.spec.ts:351-358 green.
3. Add/install guard: adding a shipped name → rejected by default; --force → allowed + boot warning about duplicates.

Priority

Fix	Value	Cost
2: honest message + self-diagnosis	very high	~1 throw + 1 probe helper
1: Symbol.for shared registry	high (eliminates the failure class)	~20 lines
3: add-time guard	medium-high	small branch, reuses shipped

Note: master and 0.2.2-alpha.3 still carry the original message at packages/boot/app-boot/src/index.ts:334-335.