agent: frontmatter description starting with '[' silently drops the agent (AgentNotFoundError) #54200

Summary

In OpenCode 2, an agent Markdown file whose frontmatter description is an
unquoted plain scalar starting with [ (e.g. description: [Team] Does a thing)
is silently dropped from the agent registry. No warning or error is logged, the
agent is missing from GET /api/agent, and any session bound to it later dies
with Session.AgentNotFoundError. The same file loads correctly in OpenCode 1
and as soon as the value is quoted in V2, so this looks like a V1→V2 parser
strictness regression around frontmatter normalization.

Environment

• opencode version: 2.0.26
• OS: Darwin 27.0.0 (darwin arm64)
• Terminal: TERM_PROGRAM=vscode, TERM=xterm-256color, COLORTERM=truecolor
• Shell: /bin/zsh
• Install/channel: latest release
• Active plugins:
  • project-local .opencode/plugins/apstory-sync-agents.ts
  • global .config/openchamber/agent-tool (loaded from outside opencode config)
  • no plugins entries in opencode.json

Reproduction

1. Create .opencode/agent/zztest.md:

   ---
   description: [Test] unquoted description
   mode: subagent
   ---
   
   Reply with exactly: OK

2. Launch it with a fresh/private server:

   opencode run --standalone --agent zztest --model deepseek/deepseek-flash "go"

3. Observe: Error: Agent not found: "zztest".

4. GET /api/agent?location[directory]=<project> omits zztest entirely — no
   error, no warning.

5. Quote the same value (description: "[Test] unquoted description") and repeat
   step 2 → the agent loads and replies OK.

This is fully deterministic on a fresh server (not the stale-parse-cache case
from #53909): the unquoted value never loads, the quoted value always does. A
control test with two throwaway agents in the same directory reproduced it:

• description: [Test] unquoted description → Agent not found: "zztest-bracket"
• description: "[Test] quoted description" → runs and returns QUOTED_OK

Expected Behavior

Either:

• parse/normalize the value (as the frontmatter parser already does for
  descriptions containing an unquoted : per fix(core): bypass gray-matter content cache when parsing frontmatter #51245), or
• surface a frontmatter parse error/warning so the user knows the agent was not
  loaded.

An invalid YAML scalar should not make the agent disappear silently.

Actual Behavior

• The agent is dropped from the registry with no diagnostic of any kind.

• GET /api/agent simply lacks the entry.

• Sessions using that agent later fail at drain:

  level=ERROR message="Failed to drain Session"
  cause="Session.AgentNotFoundError: Agent not found: \"orchestration-agent\""
  

  (and, per Completed session marked failed, work reported lost, when its agent is missing at drain (Session.AgentNotFoundError) #53500, the session is then marked failed even though earlier work
  completed).

The frontmatter value is invalid YAML: a plain scalar cannot begin with [,
which YAML parses as a flow-sequence indicator, so [Test] unquoted description
becomes a sequence plus unexpected trailing scalar. OpenCode 1 loaded these
files; V2 does not.

Additional Context

• Cause is easy to miss because the failure is silent. Since these agents are
  generated from a wiki and copied into many projects, one bad description
  prefix takes out most of an agent suite at once.
• Related issues: agent: unquoted colon in description silently resolves mode as primary #53909 (unquoted : in description, auto-quoted after
  fix(core): bypass gray-matter content cache when parsing frontmatter #51245), permission.skill / tools.skill in standalone agent .md frontmatter is parsed but silently ignored at config resolution #41712 (frontmatter parsed but silently ignored), Completed session marked failed, work reported lost, when its agent is missing at drain (Session.AgentNotFoundError) #53500
  (AgentNotFoundError marked as a failed session at drain), Agent not found for an existing agent while plugins reload after a plugin file changes #54172 (agent
  missing while plugins reload).
• Workaround: quote any description value that starts with [ (or any special
  YAML indicator character).
• Request: please emit a warning (or reject the file loudly) when agent
  frontmatter fails to parse, and consider extending the existing auto-quote
  normalization to leading [.