serve: a config load error is cached per project instance — fixing/deleting the offending command file does not clear it until /global/dispose #50906

Description

On a long-lived opencode serve, configuration is loaded once per project instance and cached for the process lifetime. When that initial load fails validation, the failure is cached too: fixing (or even deleting) the offending file does not clear it. Every subsequent opencode attach --dir <project> keeps failing with the same error until /global/dispose is called or the server is restarted, with no in-product hint that this is stale state.

The concrete trigger I hit: a command file whose frontmatter has an empty value:

---
description:
agent: copilot
---

An empty YAML value parses to null. The command schema (packages/core/src/v1/config/command.ts) declares description: Schema.optional(Schema.String) = string | undefined, so null fails:

Configuration is invalid at /path/.opencode/commands/<name>.md: SchemaError: Expected string | undefined, got null
  at ["description"]

The user then fills in a description (or removes the file), retries, and gets the identical error — the server is still serving the cached failed load.

Steps to reproduce

1. Start a long-lived server in a scratch dir: opencode serve --port 4096
2. In a project, create .opencode/commands/foo.md:

   ---
   description:
   agent: copilot
   ---
   body

3. opencode attach http://127.0.0.1:4096 --dir <project> → SchemaError: Expected string | undefined, got null at ["description"]
4. Edit the file to give description a value — or delete the file entirely.
5. opencode attach http://127.0.0.1:4096 --dir <project> again → the same error, for the deleted file path.
6. POST http://127.0.0.1:4096/global/dispose (or a fresh opencode serve on another port, same --dir) → the project loads cleanly.

Actual

• The parse failure is cached in the per-project instance (InstanceStore); config is not re-read on file change.
• A transient authoring mistake becomes a sticky, unrecoverable-looking startup failure.
• The error message names the file but gives no hint that the file has already been fixed or that a reload is required.

Expected

Any of:

• The instance is invalidated when a config/command/agent file changes (or at least when a previous load failed), so the next use re-reads from disk; or
• A failed config load is not cached permanently; or
• At minimum, the error surfaces an explicit remediation hint (e.g. "config is cached; run /global/dispose / reload to retry").

Separately and trivially: since the field is optional, coercing an empty frontmatter value (null) to undefined for description/agent/model would prevent the most common form of this trap.

Root cause (v1.18.25)

• packages/opencode/src/config/command.ts — ConfigCommand.load() throws InvalidError on the first command that fails schema decode.
• packages/core/src/v1/config/command.ts — description: Schema.optional(Schema.String); empty YAML → null.
• packages/core/src/config/markdown.ts — gray-matter yields null for an empty value.
• Config is loaded once per instance in InstanceStore; the failed state persists until POST /global/dispose (Server.disposeAllInstances…).

Impact

Any persistent serve deployment (headless/multi-attach) is affected. A single bad frontmatter edit — including one made by another agent/build step — wedges the project's config until someone knows the undocumented dispose endpoint. This is the same class of "rewrite a config file under a live server and state never recovers" as #46245 (agents), but here it manifests as a hard validation error rather than empty responses.

Related

• serve: rewriting an agent file under a live server poisons sessions — asks return empty text (200 OK, zero tokens) until restart #46245 — rewriting an agent file under a live server poisons sessions until restart (same cached-config root cause)
• skills: project .agents created after startup is not discovered until config reload #42478 — project .agents created after startup not discovered until reload
• Slash skill commands do not reload edited SKILL.md content #49451 — edited SKILL.md content not reloaded
• [FEATURE]: /reload slash command with auto-resume #43454 / [FEATURE]: slash command for reload #6719 / [FEATURE]: Will 2.0 config hot-reload expose an HTTP/SDK trigger for headless serve? #43698 — hot-reload / reload trigger feature requests

Environment

• OpenCode 1.18.25
• Linux Mint 22.1 (Debian-based), kernel 6.8.0-107
• Long-lived opencode serve --port 4096 + multiple opencode attach --dir . clients
• Plugins: opencode-notify; local worktree/mcp-daemon/browser-safety plugins