[Bug] settings/describe crashes on Standard Schema Config with toJSON

[smastergg]

Environment

• DeepSeek Harness desktop: 0.2.1-rc.5
• macOS

Summary

A plugin whose Config implements Standard Schema validation and exposes toJSON(), but is not a Schemastery schema, can make settings/describe fail. In the desktop app this becomes a fatal desktop welcome: Web RPC failed, preventing startup.

Minimal shape

export const Config = {
  '~standard': {
    version: 1,
    vendor: 'example-plugin',
    validate: (value) => ({ value }),
  },
  toJSON() {
    return { type: 'object', properties: {} };
  },
};

Actual result

After the plugin is loaded, settings/describe returns:

{
  "ok": false,
  "error": {
    "code": "gateway/internal",
    "message": "Cannot read properties of undefined (reading 'volatile')"
  }
}

The desktop welcome then fails with Web RPC failed.

Cause

Settings.schema(entry) accepts any Config with toJSON(). Settings.describe() passes it to volatileForm(schema), which assumes Schemastery internals (schema.meta.volatile, schema.type, schema.dict). For a valid Standard Schema config, schema.meta may be absent, so enumeration throws before the settings RPC can respond.

Expected

A config schema that the host accepts for plugin configuration should not make settings enumeration crash. Please either validate that the object is a supported Schemastery schema before calling volatileForm, skip unsupported schemas safely, or adapt the supported Standard Schema/JSON Schema representation.

I reproduced this with a linked local plugin using a hand-written Standard Schema config (no Schemastery dependency). Adding Schemastery-shaped markers locally avoids the crash, but the host-side settings service should handle unsupported/non-Schemastery schemas defensively.

[PerryLink]

The crash is in the form builder, not the RPC layer.

Settings.schema() (packages/settings/settings/src/index.ts:426-429) accepts any Config object where 'toJSON' in schema holds, and casts it to the Schemastery type. describe() then hands it to volatileForm (:305, :308), whose first line is if (schema.meta.volatile) (packages/settings/settings/src/schema.ts:38). Your config has no meta, so that read is the TypeError you posted and the RPC returns gateway/internal instead of a descriptor list.

Why the window never appears: the welcome backend calls settings/describe itself, both for its state read (apps/desktop/src/welcome-backend.ts:73) and for the locale bootstrap (:133), and turns any non-ok envelope into Web RPC failed (:67). On desktop, a settings enumeration error is therefore a startup error.

Fix shape, smallest first:

1. if (schema.meta?.volatile) in volatileForm, returning undefined when meta is absent. describe() already skips entries with no volatile form (index.ts:309), so the plugin drops out of settings instead of taking the enumeration down.
2. Replace the duck-type at index.ts:428 with a real Schemastery check, so plainSchema's new z(schema.toJSON()) (schema.ts:20) cannot be reached with a foreign shape either.
3. If non-Schemastery configs are intended to work, describe() needs a per-entry try/catch: today one bad entry aborts the whole flatMap (index.ts:304-333), so a single plugin can blank every form in the app.

To confirm on your side: disable the plugin and check the welcome screen comes up, then re-enable it with Config as z.object({}). If both pass, plugin loading is fine and the failing step is settings enumeration.

What I did: read-only source inspection at master ce7073d5; I did not run your plugin, so the exact throw line is inferred from the message plus the first .meta read on this path.

[aturzone]

Confirmed on master @ 8bd073392e (root 0.2.2-alpha.3, Linux, Node 24.22.2, pnpm 11.28.5).

Root cause matches PerryLink's analysis. Reproduced deterministically without the desktop shell:

import { volatileForm } from 'packages/settings/settings/src/schema.ts'
const config = {
  '~standard': { version: 1, vendor: 'example', validate: (v: unknown) => ({ value: v }) },
  toJSON() { return { type: 'object', properties: {} } },
}
volatileForm(config as never) // TypeError: Cannot read properties of undefined (reading 'volatile')

SettingsForms.schema() accepts any Config with toJSON() and casts it to Schemastery; describe() then calls
volatileForm(), whose first line reads schema.meta.volatile — the Standard Schema object has no meta graph, so
enumeration throws and the RPC returns gateway/internal before the welcome window is served.

One correction for anyone fixing this: ~standard cannot be used to tell the two apart, because vendored Schemastery
implements Standard Schema itself (vendor/schemastery/lib/index.mjs:52, consumed by vendor/cordis/src/fiber.ts:53).
The safe structural discriminator is Schemastery's global symbol marker
(Symbol.for('schemastery') set on Schema.prototype, vendor/schemastery/lib/index.mjs:3,50) plus its injected
meta (:48); that also works across package copies.

Proposed minimal fix (tested locally on a branch):

• add isSchemasterySchema(value) in packages/settings/settings/src/schema.ts using that marker + meta;
• make SettingsForms.schema() return undefined for unsupported Configs, so describe() skips them instead of
  crashing (they had no renderable form before either — describe always threw);
• leave volatileForm/isVolatilePath untouched;
• regression tests: guard-level in schema.spec.ts and a real-composition describe() test with a Standard-Schema
  Config that asserts other entries still render and update() rejects with a clear error.

Verification: settings package tests 48/48, affected suites 855/855, pnpm run typecheck 5/5 gates, pnpm run test:docs 21/21 gates, oxlint clean. Both new tests fail on unfixed code with the exact TypeError above.

Patch: branch fix/dsh-bug-triage on my fork (commit e0df0c36ed), if useful as a starting point.

[PerryLink]

The discriminator point is right, and the code is unchanged.

I re-checked it at the current master fcc0ad46 (2026-11-04, dsh-v0.2.2-rc.1 released): packages/settings/settings/src/schema.ts is the same blob as when I answered (9d84e2e5), if (schema.meta.volatile) is still the first line of volatileForm (:38), and Settings.schema() still reads 'toJSON' in schema (index.ts:426-429, same blob 5e9a9cd5). So the report reproduces on the newest master, not only on 8bd0733.

On the fix: agreed that ~standard is not the separator, since vendored Schemastery is itself a Standard Schema implementation. The global symbol marker is the structural check that survives both. Two notes on top of it:

• Whatever the discriminator, the cheap guard is still schema.meta?.volatile returning undefined — describe() already skips entries with no volatile form (index.ts:309), so an unsupported config loses its settings form instead of blanking the enumeration.
• The duck-type and the form builder should not disagree: if schema() accepts a value, volatileForm() should be able to survive it. Right now the first is satisfied by any object with toJSON, and the second assumes a complete Schemastery node.

One thing your repro adds that the report did not: the failure is reproducible without the desktop shell, which makes it a unit test candidate for settings rather than a desktop fix.

Read-only source inspection at fcc0ad46; I did not run your snippet.

[aturzone]

Thanks — both points folded in.

1. Form-builder tolerance. volatileForm() and isVolatilePath() now read schema.meta?.volatile, so a Config that reaches projection without a meta graph degrades to "no form" instead of throwing; describe() already skips that. The regression test builds a real Schemastery node and removes its meta at runtime (no casts), then asserts projection still returns the live children — it fails on the old schema.meta.volatile read.

2. Duck type and builder agree. The discriminator stays at the Config boundary (Symbol.for('schemastery') + object meta), and the builder is now defensively tolerant, so neither side assumes the other's check.

Rebased onto fcc0ad46 (dsh-v0.2.2-rc.1) and re-verified (the schema.ts / index.ts blobs are still the old ones, as you noted; the unpatched repro still throws):

• branch fix/dsh-bug-triage: settings commit 8579a7f370, plus the PTC/session turn-scope fix 38618c55cf on the same branch
• settings tests: 48/48 in the package; schema + real-composition describe() regressions both pass
• pnpm run typecheck 5/5 gates; Oxlint clean; docs pairing recorded
• PTC/session fix rebased too (upstream changed tool-executor-ptc/src/ptc.ts for call budgets): session + PTC + settings suites 883/883

Branch: https://github.com/aturzone/deepseek-harness/tree/fix/dsh-bug-triage