serve: rewriting an agent file under a live server poisons sessions — asks return empty text (200 OK, zero tokens) until restart #46245

Environment

• opencode 1.18.23 and 1.18.25 (verified on both)
• opencode serve --port 4200 --hostname 127.0.0.1 on Linux
• custom project agents in .opencode/agents/*.md (tools as an object map, e.g. read: true)
• API use: POST /session/{id}/message with agent: <id>

Reproduction

1. Start opencode serve in a project that defines a custom agent (.opencode/agents/my-agent.md).
2. Create a session and send a message with "agent": "my-agent" — answers normally.
3. While the server is LIVE, rewrite the agent file (any change — e.g. regenerating it from a build step).
4. Send another message with "agent": "my-agent".

Actual

Every subsequent ask returns HTTP 200 with empty text and zero output tokens, indefinitely. No error is logged server-side, no error surfaces to the client, and the state never recovers. The only remedy is a full server restart (verified: new pid required — killing by a stale pid file while the old listener still holds the port silently keeps the poisoned state).

Expected

Either the rewritten agent definition takes effect, or the previous one keeps serving — not a permanent silent empty-response state.

Why this matters

The empty-200-with-zero-tokens signature is indistinguishable from the provider-error-swallowing symptom already tracked in #41469 (session silently stops on empty LLM response), which makes diagnosing this state much harder than it should be — a poisoned agent looks exactly like a dead provider key. We run a 35-agent fleet against one shared opencode serve (agents generated from a build pipeline), and an agent regeneration mid-flight silently zeroed a whole evaluation run before we traced it to this.

Workaround we adopted: byte-compare before writing agent files (no change, no write) and do a verified restart (real listener resolved via ss, port actually freed, new pid != old pid) after any agent-file change.

Related

• feat: hot-reload skills, commands, agents and config on file change #43538 (feat: hot-reload skills, commands, agents and config on file change) — the current partial watcher behavior actively breaks serving; worth fixing before/with that work
• plugins: hot reload makes the server unavailable #42898 (plugins: hot reload makes the server unavailable) — cousin behavior for plugins
• skills: project .agents created after startup is not discovered until config reload #42478 (agents not discovered until config reload) — discovery side of the same lifecycle

Happy to provide more detail (request/response captures, agent frontmatter, server logs) if useful.