dsh-settings: one plugin exporting Config = null crashes describe() for the whole runtime, and the failure surface is a misleading "inactive context" error

[newhdr]

TL;DR

SettingsForms.schema() checks schema !== undefined but not null. A plugin that exports Config = null — a legitimate JS-level fallback when an optional schema build fails — makes describe() throw TypeError: Cannot use 'in' operator to search for 'toJSON' in null. The throw aborts the entire describe() walk, so every consumer that calls ctx.settings.describe() during activation gets its fiber marked errored, and all subsequent settings reads/writes fail with:

cannot get required service "settings" in inactive context

The reported error points at Cordis lifecycle semantics, while the actual cause is a null-safety gap one function away. A one-line fix resolves it (verified on a live 0.1.7-rc.2 install).

Affected code

packages/settings/settings/src/index.ts (master, last touched 2026-09-21 in #4587):

private schema(entry: Entry): z | undefined {
    const schema = entry.fiber?.runtime?.Config
    return schema !== undefined && 'toJSON' in schema ? schema as z : undefined
    //           ^^^^^^^^^^^^^^ null passes this check, then "'toJSON' in null" throws
}

runtime.Config is typed z | undefined, so the type system says null can't occur. But Config is a plain JS module export — a plugin can legally produce null there. We hit this in the wild (see below), so the type assumption does not hold in practice.

Failure cascade

1. Plugin A exports Config = null and loads fine (its entry is ACTIVE).
2. Any plugin B whose activation path calls ctx.settings.describe() — in our case dsh-better-sidebar@0.21.1, whose inject(['settings']) callback calls describe() synchronously — receives the TypeError instead of a descriptor list.
3. Cordis marks B's inject sub-context errored; B's cached context still points at the now-dead fiber.
4. Every later settings operation through B (e.g. POST /sidebar/api/settings.get|update) fails: 500/400 with cannot get required service "settings" in inactive context.
5. The same TypeError also fires for dsh-api-settings-controller's describe() and the invalidation microtask inside SettingsForms.invalidate() — so the core settings UI is affected by the same walk, not just one plugin.

Notably this is deterministic and survives restarts: it is not a race, a peer-range mismatch, or a lifecycle timing issue — every boot with the offending plugin present reproduces it.

Why this was hard to diagnose (secondary issue)

The thrown TypeError is invisible to operators. The plugin callback's failure is caught by Cordis' _reload and routed to ctx.logger.error(...), but dsh's logger does not surface plugin-callback errors on stderr by default. The only externally visible artifact is the downstream "inactive context" message, which sends investigation toward Cordis activation timing. It took a bisect over 31 installed plugins plus instrumenting the victim plugin's callback to see the real throw. If plugin-callback errors were printed once (plugin name + error), this class of issue would be a five-minute diagnosis.

Minimal reproduction

# 1. fresh profile with just the settings consumer
dsh --profile repro --from-default-profile web
dsh plugin --profile repro add dsh-better-sidebar@0.21.1

# 2. add a plugin that statically exports Config = null.
#    Any package with `"dsh.bundle"` and `module.exports.Config = null` works;
#    the real-world trigger we hit is @weibaohui/dsh-smart-title@0.1.5 on Windows
#    (its optional schemastery probe fails there, and its documented
#    graceful-degradation path sets Config = null).
dsh plugin --profile repro add @weibaohui/dsh-smart-title@0.1.5

# 3. boot and call the plugin's settings route
dsh --profile repro --no-open --port 7800
curl -X POST http://127.0.0.1:7800/sidebar/api/settings.get
# → 500 {"ok":false,"error":{"code":"internal","message":"cannot get required service \"settings\" in inactive context"}}

Removing the offending plugin (or patching the one line below) immediately restores 200.

Real-world trigger

@weibaohui/dsh-smart-title@0.1.5 builds its Schemastery Config in a try/catch and intentionally degrades to Config = null when the schema library can't be resolved. On Windows its host-probe path pattern (<prefix>/lib/node_modules/...) never matches the npm-global layout (node_global\node_modules\...), so the fallback fires for every Windows user. That plugin's authors chose a reasonable JS-level fallback; the crash is on the consumer side. (Filed separately with the plugin.)

Suggested fix

   private schema(entry: Entry): z | undefined {
       const schema = entry.fiber?.runtime?.Config
-      return schema !== undefined && 'toJSON' in schema ? schema as z : undefined
+      return schema != null && 'toJSON' in schema ? schema as z : undefined
   }

!= null covers both undefined and null, matching the intent ("skip entries with no usable schema") without changing any other behavior.

Verified: applied to the installed @deepseek-ai/dsh-settings@0.1.7-rc.2 on a live profile, the previously failing settings.get/settings.update calls return 200, the full describe() walk completes, and all 31 installed plugins (including the null-Config one) keep working.

Optional hardening, if you want the type system to admit reality instead of fighting it: type runtime.Config as z | null | undefined, or treat any non-object Config as "no schema".

Environment

• dsh 0.1.7-rc.2 (npm next), Windows 11, Node 22
• dsh-better-sidebar@0.21.1, @weibaohui/dsh-smart-title@0.1.5
• Clean-profile repro also on 0.1.7-rc.2; master source still shows the unguarded check as of 2026-09-25

[PrithwishDas101]

The failure comes from the null check in "SettingsForms.schema()":

return schema !== undefined && 'toJSON' in schema
? schema as z
: undefined

The condition excludes "undefined" but still allows "null", so the "in" operator throws when a plugin exports "Config = null".

The minimal fix is to change "schema !== undefined" to "schema != null":

return schema != null && 'toJSON' in schema
? schema as z
: undefined

This excludes both "null" and "undefined", allowing the schema traversal to skip plugins without a usable schema instead of aborting the entire "describe()" call.

A regression test should cover all three cases: a valid schema, "undefined", and "null". The discussion author reports that the one-line fix restored the failing settings endpoints in a live installation.

Source location and reproduction: #7900