fix(opencode): stop desktop recovery notices from triggering an extra provider turn

[iceteaSA]

On opencode 1.18 and newer, every Fable/Opus recovery notice delivered to OpenCode Desktop causes an extra, billed provider turn. The e2e suite catches this today — tool-prefix.test.ts "bridges back to a stale Opus cache after more than 20 Fable blocks" fails 2/2 on 1.18.18 — but CI never sees it, because CI pins opencode-ai@1.17.13.

Cause

opencode changed its run-loop exit condition in packages/opencode/src/session/prompt.ts:

1.17.13:  ... && !hasToolCalls && lastUser.id < lastAssistant.id
1.18.x:   ... && !hasToolCalls && lastAssistant.parentID === lastUser.id

The notice is created as a noReply, ignored user message. Three facts make that fatal under the new condition:

• MessageV2.latest() picks the newest user message via isAfter, which compares info.time.created first and only falls back to id ordering.
• createUserMessage stamps time: { created: Date.now() } regardless of a caller-supplied messageID.
• latest() does not skip messages whose parts are ignored.

So the notice always becomes lastUser, while lastAssistant.parentID still points at the original prompt. The condition is false, the loop does not exit, and opencode re-runs the provider on the same turn. The re-issued request body is byte-identical, since the notice is ignored and never reaches the model call — which is what makes this expensive rather than merely wrong.

The existing notificationMessageIdBeforeAssistant ordering trick cannot help: time.created dominates the comparison, so no choice of message id keeps the notice out of latest().

noReply is not implicated — opencode returns before loop() for those messages.

Why the existing deferral was not enough

Notices are already queued and flushed on session.status idle or on a completed assistant message.updated. Neither is safe: opencode awaits plugin event handlers before it evaluates the loop exit condition, so any flush performed inside a handler necessarily lands in the window before that check.

A status probe alone does not fix it either. GET /session/status returns {} for an idle session on both 1.17.13 and 1.18.18, and status.set(sessionID, { type: "busy" }) is the first statement of each loop iteration — so an empty map is also what you observe between iterations.

Fix

Deliver the notice only once the loop has demonstrably exited:

1. Arm on the session.updated that follows session.idle, rather than on session.idle or on an assistant message.updated.
2. Escape the awaited event handler before doing anything (setImmediate), so the work happens after opencode regains control.
3. Then probe session.status() outside that critical section, and re-arm up to four times if the session is busy rather than delivering into a live turn.
4. Clear the armed state on any non-idle session.status, so a new turn cannot inherit a stale "safe" mark.

sendIgnoredMessage no longer throws when assistant ordering is unavailable; the messageID placement is now best-effort, which is correct because the ordering only ever mattered while a loop was active.

CI pin

Bumped npm install -g opencode-ai@1.17.13 to 1.18.18 in .github/workflows/ci.yml. Without it CI cannot observe this class of bug at all. The suite is green on both versions, so the bump does not trade one blind spot for another.

Verification

• e2e on 1.18.18: 27/27, three consecutive runs.
• e2e on 1.17.13: 27/27, three consecutive runs.
• typecheck, build, lint, biome check clean; opencode 1023, core and pi suites pass.

Regression test added in packages/opencode/src/tests/index.test.ts: it asserts no notice is sent on a completed assistant message.updated, on session.status idle, or on session.idle, and that it is sent after the following session.updated. Reinstating any of the earlier flush points fails it (Expected number of calls: 0; Received number of calls: 1).

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Stops OpenCode Desktop recovery notices from triggering an extra, billed provider turn on opencode-ai ≥1.18 by delivering notices only after the run loop exits. Previously we flushed inside awaited handlers (idle or assistant completion) which made the notice the latest user message and kept the loop alive; now we arm on session.idle, mark safe on the next session.updated, escape the handler, probe status with bounded retries, and flush only when idle.

• Arm on session.idle, mark safe on the following session.updated; clear the safe mark on any non‑idle session.status; schedule a probe only when safe.
• Probe session.status() outside handlers with up to 4 attempts (25ms × attempt); re‑arm on errors, inconclusive payloads, or busy; do not flush on message.updated or idle status alone.
• Make notice placement best‑effort: set messageID only when available and never throw; cap queued notices per session.
• Update ARCHITECTURE.md and changelogs to document deferred delivery; CI now installs opencode-ai@1.18.18; e2e remains green on 1.17.13 and 1.18.18. No migration actions required.

^{Written for commit 0ee8cd1. Summary will update on new commits.}

Greptile Summary

The PR defers OpenCode Desktop recovery notices until after the post-idle session update and verifies session status outside the awaited event handler.

• Adds bounded, delayed status probes before delivering queued recovery notices.
• Clears delivery eligibility when a session becomes non-idle or is deleted.
• Makes assistant-relative message-ID placement best-effort.
• Updates regression coverage and pins CI to OpenCode 1.18.18.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/opencode/src/index.ts	Replaces in-handler notice flushing with post-idle arming, asynchronous status probes, bounded retries, and lifecycle cleanup.
packages/opencode/src/tests/index.test.ts	Updates recovery-notice tests to assert post-idle delivery and exercise transient, malformed, and busy status-probe results.
.github/workflows/ci.yml	Updates the globally installed OpenCode version from 1.17.13 to 1.18.18 so CI exercises the changed run-loop behavior.
ARCHITECTURE.md	Documents the post-idle notice-delivery sequence, retry behavior, and OpenCode 1.18 compatibility rationale.

Sequence Diagram

sequenceDiagram
  participant OC as OpenCode
  participant Plugin
  participant Status as session.status()
  participant Desktop
  OC->>Plugin: session.idle
  Plugin->>Plugin: Arm post-idle update
  OC->>Plugin: session.updated
  Plugin->>Plugin: setImmediate(probe)
  Plugin->>Status: Query session state
  alt Busy or inconclusive
    Plugin->>Plugin: Re-arm bounded delayed probe
  else Idle or omitted
    Plugin->>Desktop: promptAsync ignored/noReply notice
  end

Loading

_{Reviews (3): Last reviewed commit: "docs: describe deferred desktop notice d..." | Re-trigger Greptile}

Context used:

• Knowledge Base — opencode plugin startup and RPC subsystem
• Knowledge Base — OpenCode Supporting Utilities

[cubic-dev-ai]

All reported issues were addressed across 3 files

Architecture diagram

sequenceDiagram
    participant OC as OpenCode Loop
    participant Plugin as Auth Plugin
    participant Status as Session Status API
    participant Desktop as Desktop Recovery
    participant Prompt as Prompt API

    Note over OC,Plugin: Recovery Notice Queueing
    OC->>Plugin: recovery notice event
    Plugin->>Desktop: check TUI connected
    alt TUI offline
        Desktop->>Plugin: queue notice (max 4)
        Plugin->>Plugin: check safe session mark
        alt session marked safe
            Plugin->>Plugin: scheduleDesktopNoticeProbe()
        end
    end

    Note over OC,Plugin: Session Lifecycle Events
    OC->>Plugin: session.status (non-idle)
    Plugin->>Plugin: clear post-idle & safe marks
    Plugin->>Plugin: cancel pending probes

    OC->>Plugin: session.idle
    Plugin->>Plugin: mark session post-idle
    
    OC->>Plugin: session.updated
    alt post-idle mark present
        Plugin->>Plugin: mark session safe
        Plugin->>Plugin: scheduleDesktopNoticeProbe()
        Plugin->>Plugin: setImmediate(escape handler)
        Note over Plugin: Work happens after opencode regains control
    end

    Note over Plugin,Status: Bounded Status Probing (max 4 attempts)
    Plugin->>Status: session.status()
    alt session busy or undefined status
        Status-->>Plugin: busy
        Plugin->>Plugin: re-arm probe (attempt+1)
        Note over Plugin: Do NOT deliver into live turn
    else session idle
        Status-->>Plugin: idle
        Plugin->>Prompt: sendIgnoredMessage() with queued notice
        Prompt-->>Plugin: confirmation
    end

    Note over Plugin,Prompt: Message Placement (best-effort)
    Plugin->>Prompt: construct notice with messageID
    alt messageID available
        Prompt->>Prompt: set messageID (best-effort placement)
    else messageID unavailable
        Note over Prompt: No error - placement is optional
    end
    Prompt-->>Desktop: recovery notice delivered

    Note over OC,Plugin: Loop Exit Safety
    Note over OC: Exit condition checks lastAssistant.parentID === lastUser.id
    Note over Plugin: Deferred delivery avoids notice becoming lastUser
    Note over Plugin: ignored noReply notices never trigger extra provider turn

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>