server: failed plugin reload on config change silently drops custom agents and commands until restart #49982

Activity

1. Nuokfish commented on Sep 19, 2026

   

   Nuokfish

   on Sep 19, 2026

   Author

   More actions

   Workaround applied on the reporting machine: opencode service restart at 2026-09-19 21:55:57 CST; will attach post-restart catalog verification shortly.
2. Nuokfish commented on Sep 19, 2026

   

   Nuokfish

   on Sep 19, 2026

   Author

   More actions

   Post-restart verification on the reporting machine: agents = build, compaction, explore, general, plan, review, summary, title; commands = 26 commands: archive-project, check-work, deliver-closeout, force, generate-prd, generate-report, generate-spc, grill-me, init, log-time, log-work, migrate-log, next-step, quick-log, refresh-daily-insights, refresh-dashboard-insights, review, review-all, review-artifact, review-evolution, review-project, start-project, startup, suspend-project, switch-project, sync-company-dictionary; verdict = PASS (review agent restored, project commands restored).
3. holny commented on Sep 20, 2026

   

   holny

   on Sep 20, 2026

   Contributor

   More actions

   Dug into the plugin supervisor after seeing this. The TypeError: pe is not a function side looks like the legacy-export problem already tracked in #50021, but the durable defect is that a failed activation takes down the whole generation - file-discovered agents and commands included - and supervisor.ts:229 only logs the die, so with nothing watching the agent/command dirs there's no way back until restart. Happy to take this one. Plan: keep the last-good generation on a failed activation (treat the bad entry as a per-plugin failure like the duplicate-ID path already does) and add a regression test for the reload-failure path. Should have a PR in a day or two.
4. holny commented on Sep 21, 2026

   

   holny

   on Sep 21, 2026

   Contributor

   More actions

   Quick update before opening the PR: keeping the last-good generation on a failed activation turns out to collide with semantics the registry tests pin down on purpose. disables plugins after replay failures discovered during setup without restoring the old generation (packages/core/test/plugin.test.ts:349) asserts that a failing revision tears the previous activation down, and the lifecycle tests require stops to fire before starts, which a keep-previous fallback breaks. So a naive fallback contradicts existing tested behavior rather than filling a gap. Would you rather see failed reloads retain the previous generation (revisiting those tests), or should the fix stay narrower — supervisor retrying from the last good packages while the registry semantics stay as-is?
5. holny commented on Sep 24, 2026

   

   holny

   on Sep 24, 2026

   Contributor

   More actions

   Following up on my question above — either answer works for me: keep-last-good if that's the intended semantics (I'll revisit the registry test that pins removal), or I'll go with the narrow fix (keep 61dce72334's applySafe + a regression test that the catalog survives a failed reload). Just don't want to guess wrong on intent before opening the PR.
6. holny commented on Sep 26, 2026

   

   holny

   on Sep 26, 2026

   Contributor

   More actions

   Still happy to take this in whichever direction you prefer — the narrow fix (applySafe + catalog-survival regression test, commit already on my branch) is a day of latency away from a PR, and the keep-last-good route is fine too if that's the intended semantics. Otherwise I'll go with the narrow fix when I next pick this up.
7. opencodejr commented on Oct 28, 2026

   

   opencodejrBot

   on Oct 28, 2026

   Contributor

   More actions

   Thanks for the detailed report. I could reproduce this on 2.0.9 with a plain opencode serve; --service, the desktop app and active sessions aren't needed. It still happens on the latest dev (62ae125).

   What triggers it here: a local plugin whose setup returns an object instead of a cleanup function, e.g. setup: async () => ({}).

   1. Add the plugin to opencode.json. Custom agents and commands are still listed.
   2. Remove it from the config. Unloading it tries to call that object as the cleanup. The log shows failed to reload plugins … TypeError: … is not a function. (In '…()', '…' is an instance of Object), which matches your error. On dev the unminified name is cleanup.
   3. Afterwards, /api/agent no longer has the custom review agent and /api/command returns only init and review, in every booted location. Nothing else is logged.

   The script below reproduces it. One difference from what you saw: here, a later unrelated config edit restored the agents and commands without a restart.

   The transient plugins you registered may have returned an object from setup, for example a hooks object. If so, that would explain the error.

   Closely related: #48121, where a different reload error also leaves agents unavailable until restart.

   Reproduction script (repro.sh)

   #!/usr/bin/env bash
   # Repro for #49982: failed plugin reloads under a live server, then check agent/command catalogs.
   # Usage: OC="opencode" bash repro.sh   (or OC="bun ... packages/cli/src/index.ts")
   set -u
   OC=${OC:-opencode}
   R=${R:-/tmp/opencode/r49982}; rm -rf $R; mkdir -p $R/h/.config/opencode/{agent,commands} $R/proj/.opencode/commands $R/plug
   export HOME=$R/h XDG_CONFIG_HOME=$R/h/.config XDG_DATA_HOME=$R/h/.local/share XDG_STATE_HOME=$R/h/.local/state XDG_CACHE_HOME=$R/h/.cache
   printf -- '---\ndescription: review agent\nmode: subagent\n---\nReview code.\n' > $R/h/.config/opencode/agent/review.md
   printf -- '---\ndescription: g\n---\nglobal cmd\n' > $R/h/.config/opencode/commands/gcmd.md
   for i in 1 2 3; do printf -- "---\ndescription: p$i\n---\nproj $i\n" > $R/proj/.opencode/commands/p$i.md; done
   echo '{}' > $R/h/.config/opencode/opencode.json
   (cd $R/proj && git init -q)
   mkplug(){ mkdir -p $R/plug/$1; cat > $R/plug/$1/index.ts <<P
   // v1-style habit: setup returns an object (hooks) instead of a cleanup function
   export default { id: "$1", setup: async () => ({}) }
   P
   }
   PORT=${PORT:-4211}
   q(){ curl -s -u opencode:pw -H "x-opencode-directory: $2" localhost:$PORT/api/$1 | jq -c '[.data[].name]'; }
   (cd $R/proj && OPENCODE_SERVER_PASSWORD=pw $OC serve --port $PORT --print-logs --log-level info > $R/serve.log 2>&1) &
   SRV=$!; for i in $(seq 40); do sleep 1; [ "$(q agent $R/proj 2>/dev/null)" != "[]" ] && [ -n "$(q agent $R/proj 2>/dev/null)" ] && break; done
   check(){ echo "[$1] proj agents=$(q agent $R/proj) cmds=$(q command $R/proj)"; echo "[$1] home agents=$(q agent $R/h) cmds=$(q command $R/h)"; }
   check before
   CFG=$R/h/.config/opencode/opencode.json
   mkplug canary
   echo "{\"plugin\":[\"$R/plug/canary\"]}" > $CFG; sleep 3
   check "plugin added"
   echo '{}' > $CFG   # remove plugin: unloading it calls the returned object as a cleanup
   sleep 4
   check after
   echo '{"username":"x"}' > $CFG; sleep 4   # another, unrelated config edit
   check "after another edit"
   grep -E 'ERROR|failed to (re)?load' $R/serve.log | cut -c1-300 | sort | uniq -c | head -20
   kill $SRV

   Run it: bash repro.sh
8. opencodejr

   added

   reproduced

   on Oct 28, 2026
9. holny commented on Nov 10, 2026

   

   holny

   on Nov 10, 2026

   Contributor

   More actions

   PR #57775 fixes this trigger: the plugin teardown was calling whatever setup() returned as a cleanup function, and the repro's setup: async () => ({}) plugin is exactly the case it guards — the value is now ignored unless it's an actual function, so the reload no longer aborts and the agent/command catalogs stay intact. Once it merges this repro should pass without the restart.
10. opencodejr

    marked Agent selection lost outside Orca too: "Agent not found" after a failed reload (2.2.7, MATE Terminal) — same as #62002 #63528 as a duplicate of this issue on Nov 12, 2026
11. gandb commented on Nov 12, 2026

    

    gandb

    on Nov 12, 2026

    Last edited by gandb

    More actions

    Confirming this on 2.2.7, Linux, plain opencode in MATE Terminal (VTE 0.76.0, TERM_PROGRAM unset) — no Orca, no desktop app. Same signature, and one thing broader than the file-discovered case described above.

    The agents are defined inline, in the agents block of ~/.config/opencode/opencode.json — there is no ~/.config/opencode/agent/ORACLE.md on this machine. So the loss is not limited to file-discovered agents: agents that live in the config file itself are dropped by the failed reload as well, and nothing re-reads them afterwards.

    Nine occurrences today (2026-11-12), each within seconds of a failed reload:

    ERROR message="failed to reload plugins" cause="Cause([Die(TypeError: o is not a function. (In 'o()', 'o' is an instance of Object))])"
    ERROR message="Failed to drain Session"
      cause="Session.AgentNotFoundError: Agent not found: \"ORACLE\""
        at SessionContext.select
        at SessionRunner.prepareContext
        at SessionRunner.advanceToStep
        at SessionRunner.drain
        at ServerProcess.start
    

    reload event (local time)	failure
    10:21:43 failed to reload plugins	10:21:43 · 10:23:57
    10:59:34 failed to reload plugins	10:59:36 · 10:59:59 · 11:00:35
    11:04:21 failed to reload plugins	11:04:22
    11:40:27 plugin reconciliation	11:40:27 · 11:41:17
    11:47:57 failed to reload plugins	11:48:16

    A second inline agent (ORCHESTRATOR) fails identically, so it is not one agent name.

    The part that matters most, and matches the expected behaviour here. The trigger was momentary: the config file was briefly bad (a backup restored over ~/.config/opencode/ replaces opencode.json as a whole), the reload failed, and the open sessions lost their agent. The file then came back to a perfectly valid copy — and nothing recovered: the sessions stayed without their agent, and the TUI kept showing ORACLE · <model> in the status bar while the server answered Agent not found. Only a restart brought it back.

    Expected, as the reporter put it:

    • a config file that is momentarily unreadable or invalid must not change the agent a running session uses;
    • once the file is valid again, the session must recover the configured default_agent by itself, with no restart;
    • restoring a backup over the config folder must not silently wipe the configuration of the windows that are already open.

    Previously reported as #62002 and closed as not planned with an Orca-only explanation; this is the same defect, reproduced without Orca.

    Close-up from the MATE Terminal session — Error: Agent not found: "ORACLE" (marked 1) with the status bar still reading ORACLE · DeepSeek V4.1 Flash 1017:

    
12. opencodejr

    unmarked Agent selection lost outside Orca too: "Agent not found" after a failed reload (2.2.7, MATE Terminal) — same as #62002 #63528 as a duplicate of this issue on Nov 12, 2026
13. neriousy

    marked Agent selection lost outside Orca too: "Agent not found" after a failed reload (2.2.7, MATE Terminal) — same as #62002 #63528 as a duplicate of this issue on Nov 12, 2026
14. neriousy

    closed this as completedin #63548on Nov 12, 2026
15. gandb commented on Nov 13, 2026

    

    gandb

    on Nov 13, 2026

    More actions

    Tested on Linux (x64) with v2.3.0 (tag a6b15d33), which includes ec263d62b6 (#63548). Confirmed by ancestry: the fix commit is an ancestor of the release tag (58 commits ahead, 0 behind).

    Before — a failed plugin reload (TypeError: o is not a function) left the running service without its custom agents. Every following turn failed with Session.InternalError: Session.AgentNotFoundError: Agent not found: "ORACLE" until a full restart. Reproduced two ways:

    • inside an Orca terminal (Orca runs opencode serve --service and the TUI attaches);
    • in a plain terminal with no Orca at all, with the agents defined inline in opencode.json.

    After upgrading to v2.3.0 — the agents survive the reload:

    • no restart needed anymore, neither inside Orca nor in the plain TUI;
    • no AgentNotFoundError in the log;
    • the session keeps working normally after an invalid config file is written and then restored.

    So the failing-finalizer path is gone for me. Thanks for the fix.

    For the record: #62002 was closed by triage as not_planned because the earlier repro depended on reload timing, but the non-recovering case was this same failing-finalizer bug — the "restore agents/ORACLE.md" workaround from that thread did not apply to agents defined inline in opencode.json.