@humwick/server 0.0.0-stage → 0.130.0

package/runner/src/adapters/opencode.ts

@@ -0,0 +1,2264 @@
+import { relayEnv } from "@humwick/sdk/env";
+import { chmodSync, writeFileSync } from "node:fs";
+import { assertOpenCodeApprovalMode, buildOpenCodeSpawnArgs } from "./opencode-spawn";
+export { assertOpenCodeApprovalMode, assertOpenCodeManagedServerArgs, assertOpenCodeSafeModel, resolveGhConfigDir } from "./opencode-spawn";
+import { subscribeOpenCodeEvents } from "./opencode-subscribe";
+import { terminateProviderProcesses } from "../provider-processes";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { errMessage, isRecord, stringValue, type ContextState, type Message, type ProviderState } from "@humwick/sdk";
+import { killPid } from "@humwick/sdk/process-utils";
+import { shellEscape } from "@humwick/sdk/shell-utils";
+import { logger } from "../logger";
+import { fireAndForget } from "../async-guard";
+import { buildProviderRefusalHold, buildRateLimitProviderState, isProviderOverload, isProviderThrottle, isProviderUsageLimit } from "../rate-limit";
+import { PromptAcceptedError, providerMessageText, type DeliverResult, type ManagedProcess, type PromptOfferOptions, type ProviderAdapter, type ProviderConfig, type ProviderDeliverContext, type ProviderInputObserver, type ProviderSessionEvent, type ProviderSessionTurnContext, type ProviderStatusUpdate, type ProviderTokenUsageReporter, type RunnerSpawnConfig, type ShutdownOutcome, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { freshContextState } from "../transcript-context";
+import { partitionMidTurnDelivery, resolveActiveTurnMessageDelivery } from "../mid-turn-delivery";
+import { isOpenCodeServerRetryWall, openCodeServerRetryState, parseOpenCodeServerRetry, type OpenCodeServerRetry } from "./opencode-server-retry";
+import { consumeOpenCodeContextAcceptance, openCodeContextState, prepareOpenCodeRelayContext, sendOpenCodeRelayTurn } from "./opencode-context";
+import { captureOpenCodeApiUsage, spawnOpenCodeServer, openCodeApiKey, OpenCodeApiBudget } from "./opencode-api";
+import { OpenCodeTokenUsagePoster, openCodeMessageFinished, openCodeMessageModel, openCodeMessageObservedAt, scheduleOpenCodeTokenUsage } from "./opencode-token-usage-capture";
+import { decodeOpenCodeReasoningPart, decodeOpenCodeToolPart, openCodeAssistantReasoningSteps, openCodeAssistantText, openCodeReasoningSessionEvent, openCodeToolSessionEvent, openCodeToolStatusRank, openCodeTurnFinalEvents, type OpenCodeReasoningStep } from "./opencode-tool-events";
+import { openCodeBackend, openCodeContextThreshold, openCodeContextWindowTokens, openCodeLaunchModel, openCodeOnLaunchModel, openCodeModelRecord, openCodeQualifiedModel, openCodeTurnDescriptor } from "./opencode-provider";
+import { adoptOpenCodeTerminalModel, resolveOpenCodeLaunchModel } from "./opencode-model-registry";
+import { OPENCODE_SOFT_STEER_POST_TIMEOUT_MS, OPENCODE_SOFT_STEER_RECONCILE_TIMEOUT_MS, OPENCODE_SOFT_STEER_WAKE_TEXT, OpenCodeSoftSteerLedger, composeSoftSteerText, newSoftSteerMessageID } from "./opencode-soft-steer";
+
+export { openCodeContextThreshold, openCodeContextWindowTokens, openCodeModelDescriptor, openCodeModelRecord, openCodeQualifiedModel } from "./opencode-provider";
+
+/**
+ * #2459 — the non-secret attachment generation for a web-terminal guest: a short one-way
+ * digest of the ACTIVE OpenCode session id. It changes exactly when the session rotates
+ * (clearContext / the #2397 retry re-roll) and lets the orchestrator detect a stale guest
+ * TUI — attached to a dead conversation — WITHOUT ever seeing the session id itself or any
+ * credential (a digest of a 122-bit-random uuid is not reversible in practice). Rides the
+ * attach spec, the runner's GET /terminal/generation, and the orchestrator's guest registry;
+ * never persisted by Relay, never logged, never sent to the dashboard.
+ */
+export function openCodeTerminalGeneration(sessionId: string): string {
+  return createHash("sha256").update("opencode-attach-generation\0").update(sessionId).digest("hex").slice(0, 16);
+}
+
+export interface OpenCodeServerEvent {
+  type: string;
+  properties?: Record<string, unknown>;
+}
+
+type OpenCodeFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * #2428 — Bun extends its fetch init with a per-request `timeout` field that the standard
+ * RequestInit type does not declare (`number | false`; `false` disables Bun's native HTTP idle
+ * watchdog for that one request). Neither @types/node's nor bun-types 1.3.14's ambient
+ * RequestInit/BunFetchRequestInit declares the field, so it is declared here rather than reached
+ * through a cast. Verified empirically against this repo's Bun 1.3.14: with
+ * BUN_CONFIG_HTTP_IDLE_TIMEOUT compressed, a plain fetch to a server that sends no bytes dies with
+ * TimeoutError "The operation timed out" while the identical request plus `timeout: false`
+ * completes — and an explicit AbortSignal still fires on its own schedule either way, so the two
+ * mechanisms compose.
+ */
+export type OpenCodeRequestInit = RequestInit & { timeout?: number | false };
+
+/**
+ * #2425 — whole-turn budget for `OpenCodeClient.sendMessage`'s synchronous POST (see its doc).
+ * Env-tunable so an operator can trade a tighter bound for faster abandonment-detection on a
+ * flaky network, or a longer one for a model/workload that legitimately runs longer than an hour.
+ * The default is intentionally large rather than unbounded — `AbortSignal.timeout` requires a
+ * finite duration — and is far above the ~294s limit the incident was cut off at.
+ */
+export const OPENCODE_TURN_TIMEOUT_DEFAULT_MS = 60 * 60 * 1000;
+
+export function openCodeTurnTimeoutMsFromEnv(): number {
+  const parsed = Number(process.env.OPENCODE_TURN_TIMEOUT_MS);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : OPENCODE_TURN_TIMEOUT_DEFAULT_MS;
+}
+
+/** Small, pinned-protocol client for the v1.18.21 loopback server. */
+export class OpenCodeClient {
+  constructor(
+    readonly baseUrl: string,
+    private readonly password: string,
+    private readonly fetchImpl: OpenCodeFetch = fetch,
+    private readonly provider = "opencode",
+    private readonly retryDelay?: (ms: number, signal: AbortSignal) => Promise<unknown>,
+  ) {}
+
+  private headers(extra: HeadersInit = {}): Headers {
+    const headers = new Headers(extra);
+    headers.set("Authorization", `Basic ${Buffer.from(`opencode:${this.password}`).toString("base64")}`);
+    return headers;
+  }
+
+  private async request(path: string, init: OpenCodeRequestInit = {}): Promise<Response> {
+    const response = await this.fetchImpl(new URL(path, this.baseUrl), {
+      ...init,
+      headers: this.headers(init.headers),
+    });
+    if (!response.ok) throw new Error(`OpenCode server ${path} failed: HTTP ${response.status}`);
+    return response;
+  }
+
+  /**
+   * The loopback server logs "listening" as soon as its socket is bound, well before the
+   * Basic-auth-gated HTTP handler is actually wired up. A request that lands in that window is
+   * neither refused nor answered — the connection is accepted and then left open, so an
+   * unbounded fetch can hang far longer than any overall deadline (reproduced: a single such
+   * request outlived a 40s wait). Each attempt therefore gets its own short-lived AbortSignal so
+   * a stuck connection can never swallow the whole retry budget — only a real, authenticated
+   * `/global/health` 200 resolves the wait.
+   */
+  async waitForReady(timeoutMs = 20_000, attemptTimeoutMs = 2_000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    let lastError: unknown;
+    while (Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      try {
+        await this.request("/global/health", { signal: AbortSignal.timeout(Math.min(attemptTimeoutMs, remaining)) });
+        return;
+      } catch (error) {
+        lastError = error;
+        await Bun.sleep(Math.min(100, Math.max(0, deadline - Date.now())));
+      }
+    }
+    throw new Error(`OpenCode server did not become ready within ${timeoutMs}ms${lastError instanceof Error ? `: ${lastError.message}` : ""}`);
+  }
+
+  async createSession(title: string): Promise<string> {
+    const response = await this.request("/session", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title }),
+    });
+    const body = await response.json().catch(() => undefined);
+    const id = isRecord(body) ? stringValue(body.id) : undefined;
+    if (!id) throw new Error("OpenCode server created a session without an id");
+    return id;
+  }
+
+  /**
+   * #2389 — this POST is the SYNCHRONOUS endpoint: it returns only once the assistant message is
+   * complete, so its status and duration describe the whole turn, not just the hand-off.
+   *
+   * It used to be entirely silent on success — no status, no timing, no access log — so when a
+   * spawned agent idled forever there was no way to establish whether its first prompt had even
+   * been accepted; that took reading the provider's own retained SQLite. Log it.
+   *
+   * #2425 — this call used to carry NO abort signal at all, yet a live, still-running turn was
+   * observed being cut off client-side at roughly 294s regardless. Combined with the old PERMANENT
+   * idle suppression, that stranded the agent's status at "idle" forever even though the server
+   * kept working — see the `suppressProviderIdle` field doc on `OpenCodeAdapter`. Passing an
+   * EXPLICIT, much longer bound (`openCodeTurnTimeoutMsFromEnv`) means a legitimate long turn is
+   * never the thing that trips it, and gives `send()` a deterministic abandonment point to recover
+   * from if it ever does.
+   *
+   * #2428 — ROOT CAUSED (Bun repro): that ~294s cutoff is Bun's native HTTP idle watchdog — a
+   * fetch whose response sends no bytes for BUN_CONFIG_HTTP_IDLE_TIMEOUT (default 300s) dies
+   * client-side with TimeoutError "The operation timed out" INDEPENDENTLY of the AbortSignal
+   * above, which bounds only its own much longer duration. This endpoint is synchronous, so any
+   * turn longer than that window was aborted client-side while the server kept working (and
+   * RunnerCore's retry re-POSTed into the still-running turn). The fix passes Bun-only
+   * `timeout: false` on exactly this request (see OpenCodeRequestInit): verified empirically that
+   * it disables only that watchdog while the explicit deadline above keeps bounding the whole
+   * call. Deliberately NOT set globally (no BUN_CONFIG_HTTP_IDLE_TIMEOUT env change) and not on
+   * the short bounded calls — waitForReady/createSession/abort keep their default watchdog plus
+   * their own signals.
+   */
+  async sendMessage(sessionId: string, text: string, model: string, timeoutMs: number = openCodeTurnTimeoutMsFromEnv()): Promise<OpenCodeCompletion> {
+    const startedAt = Date.now();
+    try {
+      const response = await this.request(`/session/${encodeURIComponent(sessionId)}/message`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: openCodeTurnDescriptor(model, this.provider), parts: [{ type: "text", text }] }),
+        signal: AbortSignal.timeout(timeoutMs),
+        // #2428 — disable Bun's native HTTP idle watchdog for this whole-turn request only; the
+        // signal above remains the sole deadline. See OpenCodeRequestInit for the verified semantics.
+        timeout: false,
+      });
+      const completion = openCodeCompletion(await response.json().catch(() => undefined));
+      logger.info("opencode", `session ${sessionId} message accepted: HTTP ${response.status} (${text.length} chars, ${Date.now() - startedAt}ms)${describeCompletion(completion)}`);
+      return completion;
+    } catch (error) {
+      logger.error("opencode", `session ${sessionId} message failed after ${Date.now() - startedAt}ms (${text.length} chars): ${errMessage(error)}`);
+      throw error;
+    }
+  }
+
+  /**
+   * #2534 — bounded read of a session's persisted messages, used ONLY by the acceptance
+   * reconciliation when a context-carrying turn's completion await failed: a user message whose
+   * persisted text equals the outbound prompt is positive proof the server ACCEPTED it, even
+   * though the await never resolved. Kept on a short, explicit deadline — this runs on a failure
+   * path and must never stretch the caller's own recovery by more than a few seconds.
+   */
+  async sessionMessages(sessionId: string, timeoutMs = 5_000): Promise<unknown> {
+    const response = await this.request(`/session/${encodeURIComponent(sessionId)}/message`, { signal: AbortSignal.timeout(timeoutMs) });
+    return response.json().catch(() => undefined);
+  }
+
+  /**
+   * #2539 Phase B — the soft-steer persist primitive: POST /session/:id/message with a CALLER
+   * messageID + noReply:true. LIVE-PROVEN on pinned 1.18.21: persists the user row in single-digit
+   * milliseconds WITHOUT joining/cancelling an in-flight run (does not touch the runner effect that
+   * prompt_async would join), and the response body IS the persisted user message — so
+   * `info.id === messageID` is positive persistence identity straight from the POST, with no
+   * reconcile read on the clean path. Tri-state outcome: "persisted" (row exists, identity
+   * confirmed), "absent" (the server DEFINITIVELY refused — 4xx; the row does not exist), or
+   * "unknown" (timeout/transport/5xx — the POST may or may not have landed; the caller must
+   * reconcile by exact id via {@link hasMessageWithId} and never blind-retry). Bounded deadline
+   * (5s default) — a soft steer must never hang on the whole-turn budget.
+   */
+  async sendMessageNoReply(sessionId: string, text: string, messageID: string, timeoutMs = 5_000): Promise<"persisted" | "absent" | "unknown"> {
+    try {
+      const response = await this.fetchImpl(new URL(`/session/${encodeURIComponent(sessionId)}/message`, this.baseUrl), {
+        method: "POST",
+        headers: this.headers({ "Content-Type": "application/json" }),
+        body: JSON.stringify({ parts: [{ type: "text", text }], messageID, noReply: true }),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (response.status >= 500) return "unknown";
+      if (!response.ok) return "absent";
+      const body = await response.json().catch(() => undefined);
+      const id = isRecord(body) && isRecord(body.info) ? stringValue(body.info.id) : undefined;
+      return id === messageID ? "persisted" : "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+
+  /**
+   * #2539 Phase B — the ambiguous-outcome reconcile: does the session's persisted message list
+   * contain EXACTLY this caller messageID? true/false are definitive (the GET succeeded and the
+   * full session listing either has the row or does not); undefined means the listing itself was
+   * unavailable — still ambiguous. Matching is by exact id, never by text (a resend must never
+   * pass reconciliation by colliding with its own previous attempt's text).
+   */
+  async hasMessageWithId(sessionId: string, messageID: string, timeoutMs = 5_000): Promise<boolean | undefined> {
+    try {
+      const messages = await this.sessionMessages(sessionId, timeoutMs);
+      if (!Array.isArray(messages)) return undefined;
+      return messages.some((entry) => isRecord(entry) && isRecord(entry.info) && stringValue(entry.info.id) === messageID);
+    } catch {
+      return undefined;
+    }
+  }
+
+  async abort(sessionId: string): Promise<void> {
+    await this.request(`/session/${encodeURIComponent(sessionId)}/abort`, { method: "POST" });
+  }
+
+  /**
+   * #2440 — OpenCode's own native session-compaction endpoint (a prior effort, #2431, wrongly
+   * concluded it did not exist and shipped clear-inject only). Like `sendMessage`, this may run
+   * long server-side, so it gets the same Bun idle-watchdog bypass (`timeout: false`) plus an
+   * explicit bounded `AbortSignal` — see `sendMessage`'s doc for the verified #2428 semantics.
+   * A session-not-found / compact-already-in-progress / server error all surface as the same
+   * `request()`-thrown `HTTP <status>` error; the adapter's caller resets its busy hold on catch.
+   */
+  async compact(sessionId: string, timeoutMs: number = openCodeTurnTimeoutMsFromEnv()): Promise<void> {
+    const startedAt = Date.now();
+    try {
+      const response = await this.request(`/session/${encodeURIComponent(sessionId)}/compact`, {
+        method: "POST",
+        signal: AbortSignal.timeout(timeoutMs),
+        timeout: false,
+      });
+      logger.info("opencode", `session ${sessionId} compact accepted: HTTP ${response.status} (${Date.now() - startedAt}ms)`);
+    } catch (error) {
+      logger.error("opencode", `session ${sessionId} compact failed after ${Date.now() - startedAt}ms: ${errMessage(error)}`);
+      throw error;
+    }
+  }
+
+  /** Consume SSE without assuming every event shape is stable outside the pinned version. */
+  async subscribe(signal: AbortSignal, onEvent: (event: OpenCodeServerEvent) => void): Promise<void> {
+    return subscribeOpenCodeEvents(() => this.request("/event", { headers: { Accept: "text/event-stream" }, signal }), signal, onEvent, this.retryDelay);
+  }
+
+}
+
+/**
+ * Retry/re-roll policy for a retryable turn-ending provider error (#2397). Direct measurement
+ * (issue #2397 comment) showed these failures are BIMODAL per OpenCode session — a session either
+ * succeeds on every attempt or fails on every attempt for its whole life — so retrying harder
+ * into the SAME session eventually accomplishes nothing. Bound the in-session retry tightly, then
+ * re-roll to a fresh session (new session id, same server process) exactly once before giving up.
+ */
+const OPENCODE_ERROR_RETRY_MAX_ATTEMPTS = 3;
+const OPENCODE_ERROR_RETRY_BASE_DELAY_MS = 1_000;
+
+/** Exponential backoff for retry attempt N (1-indexed): 1s, 2s, 4s at the defaults above. Driven
+ *  entirely by our own policy — OpenRouter sends neither `retry-after` nor `x-ratelimit-*` for
+ *  this error class (confirmed live, #2397), so there is nothing external to read. */
+export function openCodeErrorRetryDelayMs(attempt: number): number {
+  return OPENCODE_ERROR_RETRY_BASE_DELAY_MS * 2 ** Math.max(0, attempt - 1);
+}
+
+/**
+ * #2397 — a parsed assistant-message error off the pinned v1.18.21 wire.
+ *
+ * `AssistantMessage.error` is a union (ProviderAuthError | UnknownError |
+ * MessageOutputLengthError | MessageAbortedError | ApiError — see @opencode-ai/sdk's generated
+ * types). Only `ApiError` carries a structured `statusCode`/`isRetryable`; OpenCode falls back to
+ * `UnknownError` for anything it doesn't recognize. Verified live (#2397): a real OpenRouter 429
+ * arrived as `UnknownError` with the raw provider response embedded as a JSON STRING in
+ * `data.message` (`{"code":429,"message":"...","metadata":{"error_type":"rate_limit_exceeded"}}`),
+ * not as a structured ApiError. So this parses defensively — peeling that nested JSON when
+ * present — rather than trusting a shape that is usually absent for the errors that matter most.
+ */
+/** #2619 — how one `send()` turn ended; see its doc. */
+type OpenCodeSendOutcome = "ok" | "failed" | "held";
+
+export interface OpenCodeAssistantError {
+  name: string;
+  statusCode?: number;
+  errorType?: string;
+  message: string;
+  isRetryable: boolean;
+}
+
+export function parseOpenCodeAssistantError(raw: unknown): OpenCodeAssistantError | undefined {
+  if (!isRecord(raw)) return undefined;
+  const name = stringValue(raw.name) ?? "UnknownError";
+  const data = isRecord(raw.data) ? raw.data : {};
+  let statusCode = typeof data.statusCode === "number" ? data.statusCode : undefined;
+  let message = stringValue(data.message) ?? "";
+  let errorType: string | undefined;
+  const trimmed = message.trim();
+  if (trimmed.startsWith("{")) {
+    try {
+      const nested = JSON.parse(trimmed) as unknown;
+      if (isRecord(nested)) {
+        if (statusCode === undefined && typeof nested.code === "number") statusCode = nested.code;
+        if (typeof nested.message === "string" && nested.message) message = nested.message;
+        if (isRecord(nested.metadata) && typeof nested.metadata.error_type === "string") errorType = nested.metadata.error_type;
+      }
+    } catch { /* not JSON — keep the raw (already-human) message */ }
+  }
+  const isRetryable = data.isRetryable === true
+    || statusCode === 429
+    || (typeof statusCode === "number" && statusCode >= 500)
+    || errorType === "rate_limit_exceeded";
+  return {
+    name,
+    ...(statusCode !== undefined ? { statusCode } : {}),
+    ...(errorType ? { errorType } : {}),
+    message: message || `OpenCode reported ${name}`,
+    isRetryable,
+  };
+}
+
+/**
+ * #2443 — a 404 from OpenCode's own session-message endpoint means OpenRouter has no route for
+ * the requested provider/model at all (retired, mistyped, or never released) — generic across
+ * ANY OpenRouter-routed model, never a specific one. Classifying it as the SDK's canonical
+ * `model-unavailable` reason (already used by the Claude adapter for its own "model doesn't
+ * exist" stop-failure) instead of the catch-all `opencode-provider-error` is what lets a terminal
+ * failure surface as "model unavailable" rather than an undifferentiated provider error.
+ */
+export function openCodeTerminalFailureReason(error: Pick<OpenCodeAssistantError, "statusCode">): string {
+  return error.statusCode === 404 ? "model-unavailable" : "opencode-provider-error";
+}
+
+/**
+ * #2397 — the operator-visible providerState for "still trying" (retrying in-session, or
+ * re-rolled to a fresh session and retrying), reusing `buildRateLimitProviderState`'s shape
+ * (label/kind/source/errorType/timestamps) rather than a bespoke one. `reason` is overridden away
+ * from `RATE_LIMIT_BLOCK_REASON` ("rate_limit") deliberately: that reason is special-cased in
+ * runner-core.ts for Claude's idle+blocked usage-limit hold (and is unconditionally cleared by any
+ * `status: "busy"` update — "forward progress lifts the hold"), which would erase this state on
+ * the very same busy event that carries it. A distinct reason avoids that collision while the
+ * `state: "blocked"` + `providerState` metadata still surfaces normally through the adapter's
+ * ordinary busy-claim path (the same path `permission.asked` already uses below).
+ */
+export function openCodeUpstreamRetryState(input: { attempt: number; rerolled: boolean; message: string; errorType?: string }): ProviderState {
+  // #2397 round 2 (F7) — only call it a rate limit when the parsed error actually said so.
+  // `errorType` used to default to "rate_limit_exceeded" here, and the label was hardcoded to
+  // "Rate-limited upstream" regardless of cause, so a 500/503 (isRetryable via the >=500 branch
+  // in parseOpenCodeAssistantError, with no errorType at all) was misreported as a rate limit.
+  const rateLimited = input.errorType === "rate_limit_exceeded";
+  const base = buildRateLimitProviderState({
+    kind: "transient_overload",
+    errorType: input.errorType ?? "provider_error",
+    message: input.message,
+    source: "opencode",
+  });
+  const upstream = rateLimited ? "Rate-limited upstream" : "OpenCode upstream provider error";
+  return {
+    ...base,
+    reason: "provider-error",
+    label: input.rerolled
+      ? input.attempt > 0
+        ? `${upstream} — re-rolled to a new OpenCode session, retrying (attempt ${input.attempt}/${OPENCODE_ERROR_RETRY_MAX_ATTEMPTS})…`
+        : `${upstream} — re-rolled to a new OpenCode session, retrying…`
+      : `${upstream}, retrying (attempt ${input.attempt}/${OPENCODE_ERROR_RETRY_MAX_ATTEMPTS})…`,
+    resumeAttempt: input.attempt,
+  };
+}
+
+/**
+ * #2389 — what the synchronous `/message` POST hands back: the completed assistant message.
+ *
+ * This is ground truth for the incident and needs no inference at all. The stranded agent's turn
+ * came back `finish=stop` with no text part, no tool part and zero tokens — an empty completion the
+ * runner then reported as a clean idle. The response body carrying exactly that was being discarded.
+ *
+ * Read defensively: OpenCode's wire is only pinned at v1.18.21, so an unrecognised shape yields
+ * `undefined` counts and simply contributes no signal, leaving the cross-provider ledger to decide.
+ *
+ * #2397 — also carries the assistant message's `error`, when positively parseable. This is a
+ * STRONGER signal than `empty`: a turn can end with a non-empty `parts` count (the live incident's
+ * completion carried one bare step-start part) and still be a turn-ending PROVIDER failure, so
+ * `error` is checked ahead of (and independently of) the `empty` heuristic by every reader.
+ */
+export interface OpenCodeCompletion {
+  parts?: number;
+  /**
+   * #2397 round 3 (HIGH-1) — `parts` count MINUS bookkeeping-only parts (`step-start`,
+   * `step-finish`), which the server emits on every turn — including one that produced nothing
+   * but a provider error. The live incident this issue was filed on captured exactly that shape:
+   * one bare `step-start` part, zero tokens, a 429. `parts` alone is 1, which reads as "the model
+   * produced output"; `outputParts` is 0, which correctly does not. Present whenever `parts` is.
+   */
+  outputParts?: number;
+  tokens?: number;
+  finish?: string;
+  error?: OpenCodeAssistantError;
+  /**
+   * #2413 — the terminal assistant message's TEXT, concatenated from its text parts. This
+   * synchronous POST returns the completed assistant message (ground truth, #2389), so the
+   * turn-final response is read from it directly rather than reconstructed from a possibly-late
+   * or lost SSE frame. Present only when the completed message carried assistant text; absent for
+   * a tools-only or empty turn.
+   */
+  text?: string;
+  /** True only when the shape WAS understood and it says the model produced nothing. */
+  empty: boolean;
+  /**
+   * #2605 — the terminal assistant message's REASONING as per-part steps (`{stepId, body}[]`,
+   * wire order). Present only when the completed message carried non-empty reasoning; absent
+   * for text/tools-only or empty turns. Per-part identity (not a joined string) is what lets
+   * the turn-final emit upsert the live SSE rows instead of duplicating them — the server keys
+   * step rows on stepId ONLY. Read from the same POST body as `text`, so a turn whose SSE
+   * reasoning frames were never observed still surfaces its thinking in the trace.
+   */
+  reasoningSteps?: OpenCodeReasoningStep[];
+  /**
+   * #2605 — the same reasoning as one joined string (the steps' bodies, `\n\n` join mirroring
+   * `text`). Kept for the completion log line only — the EMIT path reads `reasoningSteps`.
+   */
+  reasoning?: string;
+}
+
+/** #2397 round 3 (HIGH-1) — a bookkeeping marker the server emits around every turn regardless of
+ *  outcome, never evidence the model produced anything. An unrecognised part shape is counted as
+ *  output (the conservative default): under-counting risks re-treating real work as empty and
+ *  re-executing it, which is the worse failure. */
+function isOutputPart(part: unknown): boolean {
+  if (!isRecord(part)) return true;
+  const type = stringValue(part.type);
+  return type !== "step-start" && type !== "step-finish";
+}
+
+/** Whether a parsed completion is proof the model produced something — the ONE predicate both the
+ *  error branch (HIGH-1) and the ordinary success branch must agree on, so a step-start-only body
+ *  can never read as "produced output" from either path. */
+function completionProducedOutput(completion: OpenCodeCompletion): boolean {
+  return (completion.outputParts ?? completion.parts ?? 0) > 0 || (completion.tokens ?? 0) > 0;
+}
+
+function countTokens(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (!isRecord(value)) return undefined;
+  // `{ input, output, reasoning, cache: {...} }` on the pinned version, plus — confirmed against a
+  // real captured v1.18.21 session (#2355) — a top-level `total` that is ALREADY the sum of every
+  // other leaf here (`input + output + reasoning + cache.read + cache.write`). When present it is
+  // authoritative and must be returned directly: falling through to the leaf sum below as well
+  // would double-count it (`total` + its own constituent parts).
+  if (typeof value.total === "number" && Number.isFinite(value.total)) return value.total;
+  // Sum the numeric leaves so a renamed or added field neither breaks the read nor silently zeroes
+  // it.
+  let total: number | undefined;
+  for (const entry of Object.values(value)) {
+    const nested = countTokens(entry);
+    if (nested !== undefined) total = (total ?? 0) + nested;
+  }
+  return total;
+}
+
+export function openCodeCompletion(body: unknown): OpenCodeCompletion {
+  if (!isRecord(body)) return { empty: false };
+  // Either `{ info, parts }` or the message object itself, depending on the endpoint's mood.
+  const info = isRecord(body.info) ? body.info : body;
+  const parts = Array.isArray(body.parts) ? body.parts : Array.isArray(info.parts) ? info.parts : undefined;
+  const tokens = countTokens(info.tokens);
+  // `info.time` is ALWAYS present on an AssistantMessage, so guarding the read on its absence made
+  // this always yield undefined. The result was that the one log line written to capture
+  // `finish=stop` never printed it.
+  const finish = stringValue(info.finish);
+  const error = parseOpenCodeAssistantError(info.error);
+  const outputParts = parts?.filter(isOutputPart).length;
+  const text = openCodeAssistantText(parts);
+  const reasoningSteps = openCodeAssistantReasoningSteps(parts);
+  const reasoning = reasoningSteps.length ? reasoningSteps.map((step) => step.body).join("\n\n") : undefined;
+  return {
+    ...(parts ? { parts: parts.length, outputParts: outputParts! } : {}),
+    ...(tokens !== undefined ? { tokens } : {}),
+    ...(finish ? { finish } : {}),
+    ...(error ? { error } : {}),
+    ...(text ? { text } : {}),
+    ...(reasoningSteps.length ? { reasoningSteps } : {}),
+    ...(reasoning ? { reasoning } : {}),
+    // Only claim emptiness when the shape was actually understood: a body we could not parse must
+    // never be reported as an empty completion.
+    // #2397 round 3 review (LOW-4r) — must agree with `completionProducedOutput`'s `outputParts`,
+    // not raw `parts`, or a bookkeeping-only body (step-start, tokens:0, no error) slips past BOTH
+    // predicates in send(): not `producedOutput` (correctly), but also not `empty` — landing on
+    // "if (!completion.empty) return true" with no turnActivityCb, no retry-hold clear, and no
+    // deterministic idle close.
+    empty: outputParts !== undefined && outputParts === 0 && tokens !== undefined && tokens === 0,
+  };
+}
+
+function describeCompletion(completion: OpenCodeCompletion): string {
+  const bits: string[] = [];
+  if (completion.parts !== undefined) bits.push(`${completion.parts} part(s)${completion.outputParts !== undefined && completion.outputParts !== completion.parts ? ` (${completion.outputParts} output)` : ""}${completion.reasoningSteps?.length ? ` (${completion.reasoningSteps.length} reasoning)` : ""}`);
+  if (completion.tokens !== undefined) bits.push(`${completion.tokens} token(s)`);
+  if (completion.finish) bits.push(`finish=${completion.finish}`);
+  if (completion.error) bits.push(`error=${completion.error.name}${completion.error.statusCode !== undefined ? ` ${completion.error.statusCode}` : ""}`);
+  if (!bits.length) return "";
+  return ` → ${bits.join(", ")}${completion.empty ? " — EMPTY COMPLETION" : ""}`;
+}
+
+/** Bound on the live per-session bookkeeping in `OpenCodeAdapter` (#2347): a headless agent can
+ *  run for days across many turns, so unbounded maps keyed by message/part id would leak. Both
+ *  `messageRoles` and `emittedTextParts` are pruned back to this size, oldest first, whenever a
+ *  write would exceed it. */
+const OPENCODE_EVENT_STATE_LIMIT = 500;
+
+function pruneToLimit(map: Map<string, unknown> | Set<string>, limit: number): void {
+  const overflow = map.size - limit;
+  if (overflow <= 0) return;
+  const it = map.keys();
+  for (let i = 0; i < overflow; i++) {
+    const next = it.next();
+    if (next.done) break;
+    map.delete(next.value);
+  }
+}
+
+export class OpenCodeAdapter implements ProviderAdapter {
+  readonly reportsContextResets = true;
+  readonly provider: string;
+  readonly statusSourceId: string;
+  // #2440 — unlocks `context.resume = "native"` capability advertisement (see
+  // runtimeProviderContextCapabilities). `opts.instructions` is deliberately NOT threaded into the
+  // `/compact` HTTP call itself (see `performCompact`'s doc) — the relay's own reactive
+  // continuation inject already delivers it as a follow-up message either way, exactly like
+  // Codex's own compact() (also instructions-blind) relies on for its forced-resume path.
+  // IMPORTANT semantic gap this flag papers over: unlike Claude's real `/compact <instructions>`,
+  // OpenCode's `/compact` endpoint is NOT instruction-steerable — `performCompact` never sends the
+  // continuation on the wire at all, so the summarizer itself never sees it. Setting this flag true
+  // is what makes `resume:"native"` selectable; the actual delivery guarantee comes entirely from
+  // the reactive inject, not from this flag. Follow-up #2442 tracks a cleaner capability bit that
+  // distinguishes "native resume is offered" from "the compact call itself accepts steering text",
+  // so a future reader doesn't read this as "the summary is instructable" when it is not.
+  readonly compactSupportsInstructions = true;
+  private statusCb: (status: ProviderStatusUpdate) => void = () => {};
+  private sessionEventCb: (event: ProviderSessionEvent) => void = () => {};
+  private turnActivityCb: () => void = () => {};
+  // `message.updated` (role) always precedes that message's `message.part.updated` events on the
+  // real v1.18.21 wire (verified live against OpenRouter meta/muse-spark-1.3-contributor, #2347) — spawn()
+  // subscribes before any prompt is sent, so there is no race for the normal launch flow.
+  private readonly messageRoles = new Map<string, string>();
+  private readonly emittedTextParts = new Set<string>();
+  // #2354 — stepId → highest lifecycle rank already emitted for that tool part, so a duplicate or
+  // reordered `message.part.updated` (a late `running` after `completed`, a repeated frame) never
+  // regresses or double-emits the step. Pruned to OPENCODE_EVENT_STATE_LIMIT like the maps above.
+  private readonly emittedToolSteps = new Map<string, number>();
+  // #2437 — the ToolPart wire shape only carries `input` while `running`; a `completed` decode has
+  // none. Cache the redacted params captured at running, keyed by stepId, and carry them forward
+  // onto the terminal event so the row's params don't vanish when the server upserts it in place
+  // (upsertSessionStepInPlace replaces the whole payload with the incoming one, not a merge).
+  private readonly toolStepParams = new Map<string, unknown>();
+  // #2605 — reasoning part id → full body already emitted for that part, so a repeated or
+  // finalized `message.part.updated` frame for the same reasoning part emits the CURRENT full
+  // text (the server upserts the trace row in place by stepId) instead of appending a duplicate
+  // row. Pruned to OPENCODE_EVENT_STATE_LIMIT like the maps above.
+  private readonly emittedReasoningParts = new Map<string, string>();
+  // #2413 review (HIGH-1) — a genuinely PER-SEND turn id, minted at the top of each `send()` and
+  // used for the busy edge, narration, tool steps, and the turn-final response alike. Was
+  // `process.meta.sessionId`, which PERSISTS across sends: two turns in one session then shared a
+  // turnId, so lineage dedup (promoteLineageCapturedResponse/flushWorkFinalReports) forwarded the
+  // FIRST turn's body and dropped the SECOND — the real final report never reached the coordinator.
+  private sendTurnId: string | undefined;
+  // #2397 round 2 (F3/F4) — live-confirmed: the real server emits its OWN busy/idle
+  // session.status pair around EVERY attempt, including failed ones (two `idle` events for one
+  // errored turn). Left alone, each failed attempt's idle looks like a real provider-turn close
+  // to runner-core's #2389 seam: it clears `currentTurnId` and judges that blip as an empty turn,
+  // then the next attempt's busy mints a brand-new turn id — up to
+  // `OPENCODE_ERROR_RETRY_MAX_ATTEMPTS * 2` extra empty-turn closes the operator sees, and a
+  // premature nudge/escalation mid-retry. Raised for the WHOLE `send()` call (see the loop entry),
+  // this swallows every transient idle for the call's own turn so the whole retry sequence stays
+  // ONE turn from the runner's view.
+  // #2397 round 5 review (MED-1) — this is now a STICKY suppression, not cleared at close time:
+  // `closeSuppressedTurn` used to lower it as it fired, so a HEALTHY turn's own trailing real SSE
+  // idle — if processed after the POST already resolved — sailed through unsuppressed and closed
+  // the same turn a SECOND time (duplicate reInjectPendingObligation, duplicate
+  // completeObservedTaskClaims/Task-done). The invariant that actually holds: an idle belonging to
+  // a turn `send()` already closed must stay swallowed; only an idle for a turn that STARTS AFTER
+  // that close may pass.
+  // #2397 round 6 review (MED-1r) — round 5 had `handleEvent`'s BUSY door lower this flag whenever
+  // `turnInFlight` was false, on the assumption that such a busy edge could only be a genuinely new
+  // turn. That is a timing assumption, not an invariant: `subscribe()` dispatches a whole SSE chunk
+  // synchronously in one loop, and the SSE/POST sockets have no cross-ordering guarantee, so a late
+  // own-turn busy+idle pair batched together AFTER the POST resolves cleared suppression via the
+  // busy half and then let the idle half sail straight through — double-closing the turn.
+  // #2397 round 7 review (MED-1/MED-2/LOW-1) — round 6 only made the reopen one-shot (the FIRST
+  // post-close idle lowered this flag again), which still let a SECOND trailing idle in the same
+  // window (two late idles; a 429-retry where both attempts' own idles land after send() returns;
+  // a foreign child session's busy+idle, since `handleEvent` never filters `properties.sessionID`)
+  // double-close. There is no legitimate case this flag ever needs to go back to `false` FOR A
+  // DETERMINISTIC turn outcome: OpenCode is headless with no server-initiated turns, and every
+  // real turn-boundary transition for a turn `send()` actually SAW END is already emitted
+  // EXPLICITLY by `send()` (its own `busy` at each attempt's start) and by
+  // `closeSuppressedTurn`/`failTurn` (their own `idle`/`error`) — never by this SSE echo.
+  // #2425 — that reasoning has exactly one hole: it assumes `send()` always learns how its own
+  // turn ended. `sendMessage`'s POST can instead THROW with the server-side turn's outcome
+  // unknown (a client-side timeout on a turn that keeps running upstream) — see `turnAbandoned`
+  // below. In that one case ONLY, staying permanent forever would swallow every subsequent real
+  // busy/idle for the rest of this adapter instance's life, freezing status at whatever
+  // `send()`'s own `finally` guessed. Both SSE doors below therefore also check `turnAbandoned`
+  // — the per-session filter (also added for #2425) is what makes that safe: a foreign session's
+  // busy/idle can never reach here regardless of `turnAbandoned`, so lifting suppression for OUR
+  // OWN session's real events reopens no hazard round 7 was guarding against.
+  private suppressProviderIdle = false;
+  // #2425 — true once THIS call's own `finally` closed the turn WITHOUT any deterministic
+  // success/failure branch having run first (i.e. `sendMessage` or something else in the retry
+  // loop threw — a client-side timeout being the motivating case, #2425's incident). The server-
+  // side outcome is genuinely unknown in that case, unlike a normal completion or `failTurn`
+  // (both of which set `turnClosed` themselves before the `finally` runs, so `turnAbandoned` stays
+  // false for them — see the `finally` block). While true, the two SSE doors above stop enforcing
+  // the sticky `suppressProviderIdle` for this session's real events, letting the server's own
+  // busy/idle re-open and then close the turn — self-healing instead of freezing idle forever.
+  // Reset to `false` at the top of every `send()` call: once a NEW call takes over the turn
+  // boundary, its own explicit busy/idle is authoritative again, and any stray leftover event from
+  // a truly-abandoned previous turn must stay suppressed rather than corrupt the new turn's state.
+  private turnAbandoned = false;
+  // #2619 — a session re-roll already spent in the current provider-hold episode; cleared by the
+  // first turn that goes through (send() → "ok"). Bounds a long wall to ONE history-dropping re-roll.
+  private rerolledThisHoldEpisode = false;
+  // #2775 — a wall OpenCode's own retry hit during this send(); the session is aborted and send() holds.
+  private serverRetryWall?: OpenCodeServerRetry;
+  // #2397 round 5 review (MED-1/LOW-2) — true from the moment `send()` is actually about to run an
+  // attempt (past the readiness guard, so a "session not ready" throw never sets it) through the
+  // call's `finally`.
+  // #2397 round 7 review — no longer read by either SSE door (both now key only on the permanent
+  // `suppressProviderIdle` above). Still captured by `send()`'s `finally` (round 6, MED-2r) to
+  // decide whether THIS call ever actually started an attempt, so a "session not ready" throw
+  // never triggers a close for a turn that never began.
+  private turnInFlight = false;
+  // #2397 round 5 review (MED-1) — true once THIS call's own close has already fired (via
+  // `closeSuppressedTurn` or `failTurn`), reset at the top of every `send()` call. Distinct from
+  // `suppressProviderIdle` (which deliberately stays raised after firing, per above): this is the
+  // idempotency guard that stops the SAME call's multiple close sites — an explicit branch call
+  // plus the `finally` fallback — from emitting a second idle for one call.
+  // #2425 — also doubles as the double-close guard for the `turnAbandoned` escape hatch: once
+  // abandonment force-closes a turn, this stays true until a genuine same-session busy re-arms it
+  // (see the busy door), so a stray trailing idle for the SAME abandoned turn finds it already
+  // closed and is a no-op rather than a second `idle` dispatch.
+  private turnClosed = false;
+  // #2431 round 1 (HIGH) — FIFO serializer making `clearContext()` safe against an IN-FLIGHT turn.
+  // `agent.clearContext` is dispatched fire-and-forget (dispatchCommand holds no provider-input
+  // ticket for it — PROVIDER_INPUT_COMMAND_TYPES is inject-only) and OpenCode's `/message` POST is
+  // SYNCHRONOUS (#2389), so the model calling relay_compact_and_resume from within its own turn
+  // means the command genuinely runs WHILE send() is still awaiting that POST. send()'s retry loop
+  // re-reads process.meta.sessionId every iteration and cannot tell its own #2397 reroll from an
+  // external swap, so an unserialized clear redirected the live turn's retries/rerolls — and their
+  // reportContextUsage writes — straight into the freshly cleared session. Every writer of that
+  // per-call state therefore goes through this queue: both send() call sites (deliverInitialPrompt/
+  // deliver — already mutually serialized upstream via providerInput.run, so uncontended between
+  // themselves) and clearContext() itself, so a clear lands strictly BETWEEN turns: the live turn
+  // completes or fails wholly on the session it started with, then the swap happens, then the next
+  // delivery — the reactive continuation inject included — starts on the new session. The wait is
+  // bounded by the in-flight turn's own AbortSignal deadline (openCodeTurnTimeoutMsFromEnv), the
+  // same bound every turn already carries; there is deliberately no separate timer to fail the
+  // command early, because "clear anyway on timeout" would reintroduce exactly this bug.
+  private turnQueue: Promise<unknown> = Promise.resolve();
+
+  // ─── #2539 Phase B — non-destructive soft-steer lane (default-OFF kill switch) ───
+  // Durable-until-consumed ledger for positively-persisted soft batches (persistence != delivery).
+  private readonly softSteer = new OpenCodeSoftSteerLedger();
+  // The soft lane's OWN one-in-flight FIFO (fast loopback POSTs) — deliberately NOT turnQueue:
+  // serializing soft steers behind whole turns is the 84-minute #2539 delay this lane exists to
+  // remove. Only the POST+reconcile run here; the wake turn (rare, fallback) goes through
+  // turnQueue like any normal turn so it owns a real busy/idle pair.
+  private softSteerQueue: Promise<unknown> = Promise.resolve();
+  // Most recent live process, retained so the turn-close wake hook can reach the session without
+  // threading a process through closeSuppressedTurn/closeEventTurn. Best-effort only: a stale
+  // process fails safely in send()'s own readiness guard.
+  private softSteerProcess: ManagedProcess | undefined;
+
+  /**
+   * #2544 — the operator-facing capability bit. DEFAULT-ON since the review-gated flip: the
+   * deployed-fleet canary soak (one opencode/zai agent, 2026-09-11) proved the end-to-end path
+   * through A's seam — fold-in, durable-until-consumed settlement, no dup/loss/hot-loop, no run
+   * disruption. The per-offer policy reads `ProviderConfig.activeTurnMessageDelivery` via
+   * resolveActiveTurnMessageDelivery (the shared config seam; this adapter's default is "steer",
+   * an explicit "defer" stays the per-agent kill switch). Both opencode and zai inherit — one
+   * switch, no per-provider settings (A's design A: advertise only enabled+proven).
+   */
+  readonly supportsMidTurnSteer = true;
+
+  // #2459 — event-driven turn identity for TERMINAL-origin turns. OpenCode is headless with no
+  // server-initiated turns (the #2397 round-7 invariant), so a session.status:busy arriving for
+  // the active session OUTSIDE send() can only be a prompt typed into an attached web-terminal
+  // TUI. send() is not running then, so its sticky `suppressProviderIdle` would otherwise swallow
+  // the whole turn, and the events would fall back to the STALE `sendTurnId` of the last headless
+  // turn — mislabeled grouping. Instead: mint a provider turn id on that busy, associate the
+  // turn's user/assistant/tool message ids with it, and close it on the matching idle.
+  private eventTurnId: string | undefined;
+  // Assistant text accumulated (finalized text parts, active session) while the event turn is
+  // open, so its close can emit the turn-final response exactly like send()'s POST path does.
+  private eventTurnText: string[] = [];
+  // #2605 — reasoning observed this event turn, keyed by part id to the LATEST body seen. The
+  // terminal-origin path has no completed-message POST to read back from, so the close must
+  // reconcile from what the live door saw — but keyed per part (not a body pool): a growth
+  // frame for an already-emitted part only needs the newest snapshot, and an identical body in
+  // a LATER turn must never read as already-seen. Cleared with eventTurnText on mint/close.
+  // Bounded: part ids are server-unique per turn and the map is reset every turn, so it holds
+  // at most one entry per reasoning part of the CURRENT turn — no prefix scan, no growth.
+  private eventTurnReasoning = new Map<string, string>();
+  // #2459 round 1 (review D) — the EVENT-SOURCE discriminator replacing the round-0 time
+  // window. A terminal-origin turn is always PRECEDED by its prompt: the attached TUI's
+  // POST creates the user message on the active session before/while the turn's busy edge
+  // flows, so the message.updated(role=user) door arms this flag. The busy door admits a
+  // terminal turn only when armed (or when no headless turn ever suppressed, or #2425
+  // abandonment). A HEADLESS echo — the buffered busy+idle pair of a turn send() just
+  // closed — has NO such fresh user message by construction, so it stays suppressed with NO
+  // time bound: a delayed echo of any age is indistinguishable from a stale one and both are
+  // dropped, restoring #2397 round-7 permanence positively instead of heuristically.
+  private pendingTerminalPrompt = false;
+  // #2459 round 2 (review D) — the terminal user prompt BUFFER. The [user message.updated →
+  // user part → busy] wire ordering means the prompt can arrive BEFORE the busy that mints
+  // the terminal turn id; buffering keeps the prompt from publishing a raw session id as its
+  // turnId and from splitting off from its trace/final. SINGLE SLOT (the bound): a newer
+  // prompt flushes the older one under the session pseudo-turn first. Flush points: busy
+  // admission (minted id — the primary path), first trace activity, any active-session idle,
+  // send() takeover, and the clear/re-roll swap — the fallback id is ALWAYS the session
+  // pseudo-turn or the minted id, never a stale headless sendTurnId.
+  private bufferedTerminalPrompt: { body: string; occurredAt: number } | undefined;
+  // #2459 round 1 (review D) — permanent marker that at least one headless turn ran on this
+  // process. Once true, the busy door admits a terminal-origin turn ONLY through the armed
+  // `pendingTerminalPrompt` (fresh first-seen user message), with NO time bound: a headless
+  // busy echo of any age stays suppressed. Fresh adapters (no headless turn yet) admit freely,
+  // preserving pure-terminal sessions whose busy arrives before any user-message echo.
+  private headlessTurnSeen = false;
+  // #2459 round 1 (review D) — user-message ids already observed on this process (bounded like
+  // the other event-state maps). A REPEAT user message.updated is a buffered duplicate of a
+  // turn that already ran (send()'s own POST echo delivered late) and must never re-arm the
+  // terminal gate; only a FIRST-SEEN user message is evidence of a freshly typed TUI prompt.
+  private seenUserMessageIds = new Set<string>();
+
+  private readonly sleepImpl: (ms: number) => Promise<void>;
+
+  // #2484 — the token-usage spine transport, wired by runner-core (Claude's #2482/#2491 seam).
+  private readonly apiBudgets = new WeakMap<ManagedProcess, OpenCodeApiBudget>();
+
+  private tokenUsageReporter?: ProviderTokenUsageReporter;
+  // #2484 round 1 review (F2/F3) — collapses the message.updated door's streaming echoes to one
+  // spine post per message; flushed early at real turn boundaries (see flushAll() call sites).
+  private readonly tokenUsagePoster = new OpenCodeTokenUsagePoster(() => this.tokenUsageReporter);
+
+  constructor(
+    providerOrSleep: string | ((ms: number) => Promise<void>) = "opencode",
+    sleepImpl: (ms: number) => Promise<void> = (ms) => Bun.sleep(ms),
+  ) {
+    this.provider = typeof providerOrSleep === "string" ? providerOrSleep : "opencode";
+    this.statusSourceId = this.provider;
+    this.sleepImpl = typeof providerOrSleep === "function" ? providerOrSleep : sleepImpl;
+    openCodeBackend(this.provider);
+  }
+
+  onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
+    this.statusCb = cb;
+  }
+
+  onTurnActivity(cb: () => void): void {
+    this.turnActivityCb = cb;
+  }
+
+  onSessionEvent(cb: (event: ProviderSessionEvent) => void): void {
+    this.sessionEventCb = cb;
+  }
+
+  configureTokenUsageReporter(reporter: ProviderTokenUsageReporter): void {
+    this.tokenUsageReporter = reporter;
+  }
+
+  // #2484 round 2 review (MED-1) — the runner's ONE awaited, time-boxed teardown seam
+  // (RunnerCore.settleTerminalTokenUsage, wired at stop() / restartUnexpectedProviderExit /
+  // runPreSessionDestroy) previously no-op'd for OpenCode because it bails on a falsy
+  // transcriptPath — a Claude-shaped precondition OpenCode never has (it has no transcript file
+  // to tail; #2484's capture is event-sourced from the message.updated SSE door). Owning that
+  // bail here — ignore transcriptPath, just settle the poster — means the crash-exit and
+  // pre-session-destroy paths (which never call adapter.shutdown()) now reach the same debounced
+  // report shutdown() already flushes, instead of losing the session's final token counts.
+  async captureFinalTokenUsage(_transcriptPath: string | undefined, _ctx: ProviderSessionTurnContext): Promise<void> {
+    await this.tokenUsagePoster.flushAll();
+  }
+
+  supportsUnexpectedExitRestart(): boolean {
+    return true;
+  }
+
+  async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    assertOpenCodeApprovalMode(config.approvalMode);
+    const launch = await resolveOpenCodeLaunchModel(config, config.providerConfig as ProviderConfig, this.provider);
+    openCodeApiKey(config, launch.qualified);
+    const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig, launch);
+    const apiBudget = launch.backendID === "openai" ? new OpenCodeApiBudget(config) : undefined;
+    await apiBudget?.start(relayEnv(config.env, "AGENT_RELAY_PROVIDER_SESSION_ID") ?? crypto.randomUUID());
+    const server = await spawnOpenCodeServer(args, apiBudget);
+    const password = args.env.OPENCODE_SERVER_PASSWORD!;
+    const client = new OpenCodeClient(args.env.OPENCODE_SERVER_URL!, password, fetch, this.provider);
+    try {
+      await client.waitForReady();
+      const sessionTitle = config.label ?? config.agentId;
+      const sessionId = await client.createSession(sessionTitle);
+      const events = new AbortController();
+      // sessionTitle is also read by a #2397 session re-roll (a fresh session created mid-flight
+      // after repeated retryable errors); sessionId is MUTATED IN PLACE there, so every other
+      // reader of process.meta.sessionId (send/interrupt/shutdown) picks the new session up too.
+      // #2459 — the launch metadata terminalAttachSpec() needs is retained here as well:
+      // resolved executable, loopback server URL, agent cwd and the server password. These live
+      // ONLY in this runner-local memory (and the password ONLY re-emerges as the guest process
+      // env inside the attach spec); they are never persisted, logged, or returned anywhere else.
+      // #2599 — the payload record (when present) pins meta.model to the server-computed
+      // qualified name, so later reportContextUsage calls keep payload precedence instead of
+      // re-deriving from a possibly-ambiguous alias. Manifest path unchanged when absent.
+      // #2659 — meta.model is the normalized launch model; turns split it verbatim, never re-resolve.
+      const process: ManagedProcess = { pid: server.pid, process: server, meta: { client, sessionId, events, model: launch.qualified, launchModel: launch.qualified, sessionTitle, config, relayContextSent: false, launchContextSent: false, attachCommand: args.command, cwd: args.cwd, serverUrl: args.env.OPENCODE_SERVER_URL!, serverPassword: password, stateDir: args.env.XDG_STATE_HOME } };
+      if (apiBudget) this.apiBudgets.set(process, apiBudget);
+      // #2443 — both used to be a bare `void promise.catch(...)`: a synchronous throw from
+      // `this.statusCb`/`handleEvent` inside the fulfillment or catch handler produced a SECOND,
+      // truly unhandled rejection nothing consumed (Bun exits(1) on that; nothing respawns the
+      // runner — #1618). `fireAndForget` guarantees the rejection — from either the initial call
+      // or the handler itself — is always logged, never escapes.
+      void fireAndForget(`opencode SSE subscribe (session ${sessionId})`, () => client.subscribe(events.signal, (event) => this.handleEvent(event, process)), (message) => logger.error("opencode", message));
+      void fireAndForget(`opencode server exit status callback (session ${sessionId})`, async () => {
+        const code = await server.exited;
+        await this.tokenUsagePoster.flushAll();
+        await apiBudget?.settle().catch(() => {});
+        this.statusCb(code === 0 ? "offline" : "error");
+      }, (message) => logger.error("opencode", message));
+      return process;
+    } catch (error) {
+      killPid(server.pid, "SIGKILL");
+      await server.exited;
+      await apiBudget?.settle().catch(() => {});
+      throw error;
+    }
+  }
+
+  // #2659 — spawn() passes the registry-normalized launch model; direct callers resolve statically.
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig, launch = openCodeLaunchModel(config.model, this.provider, openCodeModelRecord(config.modelRecord, this.provider))): SpawnArgs {
+    return buildOpenCodeSpawnArgs(config, providerConfig, this.provider, launch);
+  }
+
+  /**
+   * #2459 — the web-terminal attach spec for an interactive `opencode attach` guest TUI,
+   * reusing the codex guest-terminal path downstream (runner /terminal/attach-spec →
+   * orchestrator guest tmux → Relay's authenticated terminal proxy → dashboard xterm).
+   *
+   * Fail-closed BEFORE readiness/session: every input is read from the launch metadata
+   * retained at spawn() and a missing piece throws rather than degrading. The command is
+   * exactly the pinned-CLI seam the #2459 feasibility verified against v1.18.21:
+   * `opencode attach <loopback server URL> --session <active session id> --dir <agent cwd>
+   * --pure`. `--dir` MUST equal the server/session cwd — OpenCode sessions are
+   * project-directory scoped and attach fails (or silently diverges) when the client and
+   * server directories differ.
+   *
+   * SECRET HANDLING (round-1 review A): the generated server password NEVER travels in the
+   * spec — not as `--password`, not in the URL, and (since round 1) not in a response-body
+   * env record either. terminalAttachSpec() pre-stages it in a 0600 env file under the
+   * runner's own XDG state dir and the spec carries only that PATH (`envFile`); the
+   * orchestrator's guest wrapper sources the file into the guest process environment, so the
+   * secret materializes solely in the guest process env. The server URL is loopback-only.
+   */
+  async terminalAttachSpec(process: ManagedProcess): Promise<TerminalAttachSpec> {
+    const sessionId = stringValue(process.meta?.sessionId);
+    if (!sessionId) throw new Error("OpenCode session is not ready");
+    const serverUrl = typeof process.meta?.serverUrl === "string" && process.meta.serverUrl ? process.meta.serverUrl : "";
+    if (!serverUrl) throw new Error("OpenCode server URL is unavailable");
+    const serverPassword = typeof process.meta?.serverPassword === "string" && process.meta.serverPassword ? process.meta.serverPassword : "";
+    if (!serverPassword) throw new Error("OpenCode server password is unavailable");
+    const stateDir = typeof process.meta?.stateDir === "string" && process.meta.stateDir ? process.meta.stateDir : "";
+    if (!stateDir) throw new Error("OpenCode state dir is unavailable");
+    const attachCommand = typeof process.meta?.attachCommand === "string" && process.meta.attachCommand ? process.meta.attachCommand : "opencode";
+    const cwd = typeof process.meta?.cwd === "string" && process.meta.cwd ? process.meta.cwd : globalThis.process.cwd();
+    // Pre-stage the credential where the guest can read it: 0600 file in the runner-owned
+    // 0700 XDG state dir. Path-only propagation — the contents never leave this user's
+    // file system boundary, and nothing here lands in argv, HTTP bodies, logs, or persistence.
+    const envFile = join(stateDir, "terminal-env");
+    writeFileSync(envFile, `OPENCODE_SERVER_PASSWORD=${shellEscape(serverPassword)}\n`, { mode: 0o600 });
+    chmodSync(envFile, 0o600);
+    return {
+      mode: "guest",
+      provider: this.provider,
+      cwd,
+      command: [attachCommand, "attach", serverUrl, "--session", sessionId, "--dir", cwd, "--pure"],
+      envFile,
+      title: "OpenCode terminal",
+      ttlMs: 60 * 60 * 1000,
+      generation: openCodeTerminalGeneration(sessionId),
+    };
+  }
+
+  /**
+   * #2459 — the CURRENT attachment generation (derived from the active session id), read by
+   * the runner control server's GET /terminal/generation so the orchestrator can detect a
+   * session rotation without learning the session id or any credential. undefined when the
+   * session is not ready (nothing to check).
+   */
+  terminalAttachGeneration(process: ManagedProcess): string | undefined {
+    const sessionId = stringValue(process.meta?.sessionId);
+    return sessionId ? openCodeTerminalGeneration(sessionId) : undefined;
+  }
+
+  /**
+   * #2431 round 1 (HIGH) — run `operation` as the exclusive holder of the turn queue (see the
+   * `turnQueue` field doc for why this exists). FIFO: an operation enqueued while a turn is
+   * mid-flight starts only after that turn's promise settles, success or failure.
+   */
+  private enqueueTurn<T>(operation: () => Promise<T>): Promise<T> {
+    const settled = this.turnQueue.then(operation, operation);
+    this.turnQueue = settled.then(() => undefined, () => undefined);
+    return settled;
+  }
+
+  async deliverInitialPrompt(process: ManagedProcess, prompt: string, options?: PromptOfferOptions): Promise<void | "held"> {
+    // #2397 round 3 review (LOW-5r) — `send()`'s boolean is intentionally NOT surfaced as a throw
+    // here: this method's `Promise<void>` contract is shared by every adapter, and a throw would
+    // route into attemptInitialPromptDelivery's (runner-core.ts) generic retry-and-eventually-
+    // give-up path, re-sending the SAME prompt on top of the retry+reroll budget `send()` already
+    // exhausted. Instead, runner-core reads `this.terminalFailure` (set by failTurn's own `error`
+    // status, cleared by the `busy` edge this very call started with) right after this resolves, so
+    // it can log the terminal outcome correctly without inventing a second retry loop.
+    // #2619 — a refusal under a provider hold is surfaced ("held"): the runner parks the prompt.
+    if (await this.enqueueTurn(() => this.send(process, prompt, options?.inputObserver)) === "held") return "held";
+  }
+
+  async deliver(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<DeliverResult> {
+    // #2539 Phase B — the paste-instant soft-steer routing (Phase A's single-call-path pattern,
+    // codex.ts:435): a mid-turn offer with steerable content goes through the adapter's
+    // deliverMidTurn (noReply persist, settlement deferred through ctx); boundary-only classes
+    // and the lane-off/idle cases keep the turn-end path below. Policy resolves per offer from
+    // the spawn config; this adapter's default is "steer" (#2544 flip), "defer" the kill switch.
+    if (messages.length > 0 && this.softSteerPolicyFor(process) === "steer" && ctx?.isRecipientMidTurn?.() === true) {
+      // r3 HIGH — steer ONLY the steerable partition, never the whole batch: the omitted ids
+      // (claimables and synthetic memory/resume injections) stay in this
+      // call's un-acked tail, so the runner's settle requeues them untouched onto the turn-end
+      // path. Folding the full batch into the one noReply row would carry a claimable's claim
+      // lease into the hours-long awaiting-consumption window with no renewal (lease expiry →
+      // duplicate task delivery), reorder injections,  —
+      // violating partitionMidTurnDelivery's contract. (codex.ts does the same partition INSIDE
+      // its deliverMidTurn.)
+      const { steerable } = partitionMidTurnDelivery(messages);
+      if (steerable.length > 0) return this.deliverMidTurn(process, steerable, ctx);
+    }
+    // #2397 round 3 (MED-3) — only a message `send()` actually got through (no terminal failure)
+    // is acknowledged. runner-core marks every acknowledged id read and re-queues everything else
+    // (runner-core.ts ~969-995); returning ALL ids unconditionally — the old behavior — marked a
+    // message that provoked 8 failed POSTs and a terminal failure as delivered+read though the
+    // model never processed it: recorded delivered, silently lost. #2397 round 3 (MED-6) — once a
+    // message fails terminally the session is now `error`/offline, so stop rather than burn the
+    // same ~16-minute worst-case retry budget on every remaining queued message in this batch.
+    // #2397 round 3 review (MED-3r) — `terminalFailureIds` tells runner-core WHY this id was not
+    // acknowledged, so its re-drain paces with bounded exponential backoff instead of hammering an
+    // upstream that is already rate-limiting on the very next tick.
+    const acknowledgedIds: number[] = [];
+    const terminalFailureIds: number[] = [];
+    const providerHeldIds: number[] = [];
+    for (const message of messages) {
+      let disarmOpener: (() => void) | undefined; // #2840 — each send is its own turn, opened by this message
+      try {
+        const outcome = await this.enqueueTurn(() => { disarmOpener = ctx?.openTurnFor?.([message]); return this.send(process, providerMessageText([message]), ctx?.inputObserver); });
+        if (outcome !== "ok") disarmOpener?.();
+        if (outcome === "failed") {
+          terminalFailureIds.push(message.id);
+          break;
+        }
+        // #2619 — refused under a provider hold: neither delivered nor failed. Stop the batch and
+        // hand the refused id AND the untried tail to the runner to park — they would only hit
+        // the same wall; the runner redelivers them once a provider turn goes through again.
+        if (outcome === "held") {
+          for (const rest of messages.slice(messages.indexOf(message))) providerHeldIds.push(rest.id);
+          break;
+        }
+      } catch (error) {
+        // #2534 review (LOW-3) — symmetric with runner-core's attemptInitialPromptDelivery: a
+        // PromptAcceptedError means the provider ACCEPTED this queued message's POST and the
+        // completion await failed/aborted on a still-running turn. Propagating it reached
+        // runner-core's drain, which requeued the whole batch and double-POSTed into that live
+        // turn — acknowledge the accepted message instead (its output streams via the normal
+        // session events). Any other failure still propagates: nothing delivered, whole batch
+        // requeued.
+        if (!(error instanceof PromptAcceptedError)) { disarmOpener?.(); throw error; }
+      }
+      acknowledgedIds.push(message.id);
+    }
+    return { acknowledgedIds, terminalFailureIds, ...(providerHeldIds.length ? { providerHeldIds } : {}) };
+  }
+
+  /**
+   * #2539 Phase B — the soft-steer op (see the adapter-interface doc): persist the batch into
+   * the in-flight turn WITHOUT touching any send() turn state. Non-negotiable invariants:
+   * - send()/its instance fields stay non-reentrant: this path must not read or write
+   *   sendTurnId/turnInFlight/suppressProviderIdle/turnClosed/retry/reroll and must never emit a
+   *   second busy/idle (the ongoing turn's pair is the only truthful one).
+   * - ONE composed OpenCode user row per batch (sorted by Relay id), one caller messageID, one
+   *   loopback POST at a time (adapter-local FIFO, not turnQueue).
+  * - Session fencing from intent time: the sessionId is captured at entry and re-checked
+  *   immediately before AND after the POST — a pre-POST swap defers the batch (never acked onto
+  *   a session that is gone); a swap INSIDE the POST window (batch already persisted/tracked)
+  *   targeted-reoffers it to the normal queue — never stranded on the dead session, never
+  *   reposted into the new one.
+   * - Paste-instant authority: ctx.isRecipientMidTurn() is consulted at the actual POST instant;
+   *   a turn that already ended defers (or, when it ends inside the post-POST window, persists +
+   *   arms the one bounded idle wake) — never a claimed in-turn success from a stale precheck.
+   * - At-least-once with explicit ambiguity: one POST, then (only on ambiguity) ONE bounded
+   *   exact-id reconcile; a positive persistence is NEVER re-POSTed.
+   *
+   * #2539 Phase A reconciliation — the result speaks the shared DeliverResult vocabulary:
+   * persisted/ambiguous ids return as `awaitingConsumptionIds` (their settlement completes later
+   * through ctx.settleMidTurnConsumed / ctx.reofferMidTurnIds — persistence is not delivery);
+   * everything NOT accepted (lane off, boundary-only, cap overflow, pre-POST fencing loss) is
+   * simply omitted, so the runner's settle requeues it for turn-end delivery. A
+   * reconciled-ABSENT POST (definitive non-persistence) throws so the runner paces the retry.
+   */
+  async deliverMidTurn(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<DeliverResult> {
+    const nothingAccepted: DeliverResult = { acknowledgedIds: [], awaitingConsumptionIds: [], terminalFailureIds: [] };
+    const allIds = messages.map((message) => message.id);
+    if (this.softSteerPolicyFor(process) !== "steer" || messages.length === 0) {
+      return nothingAccepted;
+    }
+    const client = process.meta?.client as OpenCodeClient | undefined;
+    const sessionId = stringValue(process.meta?.sessionId);
+    if (!client || !sessionId) {
+      return nothingAccepted;
+    }
+    this.softSteerProcess = process;
+    this.softSteer.setCallbacks({ settleMidTurnConsumed: ctx?.settleMidTurnConsumed, reofferMidTurnIds: ctx?.reofferMidTurnIds });
+    const composed = composeSoftSteerText(messages);
+    if (composed.included.length === 0) {
+      return nothingAccepted;
+    }
+    const settled = this.softSteerQueue.then(
+      () => this.softSteerDeliverBatch(process, client, sessionId, ctx, composed),
+      () => this.softSteerDeliverBatch(process, client, sessionId, ctx, composed),
+    );
+    this.softSteerQueue = settled.then(() => undefined, () => undefined);
+    return settled;
+  }
+
+  private async softSteerDeliverBatch(process: ManagedProcess, client: OpenCodeClient, sessionIdAtIntent: string, ctx: ProviderDeliverContext | undefined, composed: ReturnType<typeof composeSoftSteerText>): Promise<DeliverResult> {
+    const nothingAccepted: DeliverResult = { acknowledgedIds: [], awaitingConsumptionIds: [], terminalFailureIds: [] };
+    const deferredOverflow = composed.deferred.map((message) => message.id);
+    const included = composed.included;
+    const includedIds = included.map((message) => message.id);
+    // Fencing from intent time: a clear/reroll swap between the seam's decision and this POST
+    // means the turn this batch was composed for is gone.
+    const sessionId = stringValue(process.meta?.sessionId);
+    if (sessionId !== sessionIdAtIntent || ctx?.isRecipientMidTurn?.() !== true) {
+      return nothingAccepted;
+    }
+    const messageID = newSoftSteerMessageID();
+    ctx?.inputObserver?.offered(Date.now(), true);
+    let outcome = await client.sendMessageNoReply(sessionId, composed.text, messageID, OPENCODE_SOFT_STEER_POST_TIMEOUT_MS);
+    if (outcome === "unknown") {
+      // One bounded exact-id reconcile before ANY reoffer decision; never double-POST after
+      // positive persistence.
+      const found = await client.hasMessageWithId(sessionId, messageID, OPENCODE_SOFT_STEER_RECONCILE_TIMEOUT_MS);
+      if (found === true) outcome = "persisted";
+      else if (found === false) outcome = "absent";
+    }
+    if (outcome === "persisted") {
+      const tracked = this.softSteer.noteBatch(messageID, includedIds, sessionId, { inputObserver: ctx?.inputObserver });
+      logger.info("opencode", `soft-steer batch ${messageID} persisted (${includedIds.length} relay id(s), ${composed.text.length} chars) on session ${sessionId}`);
+      if (tracked) {
+        // Post-POST race windows (the row is persisted either way):
+        // - Session swapped INSIDE the POST→noteBatch window: the swap's own sessionReplaced
+        //   scan ran before this noteBatch, so the batch is stranded on the dead session —
+        //   targeted reoffer now (see reofferStaleSessionBatches).
+        // - Turn ended on the SAME session: the row strands until the next turn (live-proven
+        //   at-stop behavior) — arm the bounded wake.
+        const sessionIdNow = stringValue(process.meta?.sessionId);
+        if (sessionIdNow !== sessionId) await this.reofferStaleSessionBatches(sessionIdNow, sessionId);
+        else if (ctx?.isRecipientMidTurn?.() !== true) this.maybeArmSoftSteerWake(process);
+        return { acknowledgedIds: [], awaitingConsumptionIds: [...includedIds], terminalFailureIds: [] };
+      }
+      // Over the ledger's backpressure cap: the row IS persisted, so it must not be re-posted,
+      // but the lane cannot track it to settlement — omit it from the result so the normal lane
+      // carries it (duplicate text at the next boundary is the designed degradation, not silent
+      // loss).
+      return nothingAccepted;
+    }
+    if (outcome === "absent") {
+      // Definitive non-persistence after the bounded reconcile: nothing was accepted, so throw —
+      // the runner's drain catch requeues the whole batch and paces the retry at its 1s failure
+      // cadence (the same defer-by-throw shape codex uses), instead of an unpaced drain-tick loop.
+      throw new Error(`opencode soft-steer POST ${messageID} did not persist (reconciled absent) on session ${sessionId}`);
+    }
+    // Unknown after POST + reconcile: hold the ids in the ledger (the row may exist) — resolved by
+    // the consumption door, session replacement, or shutdown reoffer. Never an immediate repost.
+    // Force-tracked even at the ledger cap: the cap gates new POSITIVE persists (backpressure to
+    // the normal queue), never the RESOLVABILITY of an already-attempted POST — an untracked
+    // unknown batch could never be resolved by any ledger exit while this contract reports it as
+    // held (silent orphan under exactly the long-turn + one-timeout scenario #2539 exists for).
+    this.softSteer.noteBatch(messageID, includedIds, sessionId, { force: true, inputObserver: ctx?.inputObserver });
+    // Same swap-inside-the-POST-window fence as the persisted path: a batch noted onto a dead
+    // session can never be resolved there (the same-session consumption door and the
+    // new-session wake both miss it), so reoffer immediately instead of holding it until the
+    // NEXT swap/shutdown — the delayed silent-loss shape for non-claimable messages. The row
+    // (if it exists) stays on the dead session, unconsumed — at-least-once holds.
+    const sessionIdAfterReconcile = stringValue(process.meta?.sessionId);
+    if (sessionIdAfterReconcile !== sessionId) await this.reofferStaleSessionBatches(sessionIdAfterReconcile, sessionId);
+    else logger.warn("opencode", `soft-steer batch ${messageID} outcome UNKNOWN after POST + reconcile; holding ${includedIds.length} relay id(s) until consumption or session end`);
+    return { acknowledgedIds: [], awaitingConsumptionIds: [...includedIds], terminalFailureIds: [] };
+  }
+
+  // The spawn config the adapter was launched with (meta.config is the RunnerSpawnConfig handed
+  // to spawn()); the steer policy reads its providerConfig — never a provider-name branch.
+  // Same shape as codex's spawnProviderConfig (kept per-adapter, matching the landed precedent).
+  // #2544: the absent-config default is "steer" (default-on); an explicit "defer" is the
+  // per-agent kill switch, resolved through the shared seam like codex's "steer" default.
+  private softSteerPolicyFor(process: ManagedProcess): "steer" | "defer" {
+    const config = (process.meta?.config as { providerConfig?: ProviderConfig } | undefined)?.providerConfig;
+    return resolveActiveTurnMessageDelivery(config, "steer");
+  }
+
+  /**
+   * Targeted post-POST reoffer for the swap-inside-the-POST-window race: the clear/reroll
+   * swap's own sessionReplaced(newId) scan ran BEFORE the just-attempted batch was noted, so
+   * that batch (and any other stale-session entry) would sit stranded on the dead session —
+   * invisible to the same-session consumption door, unarmable by the new-session wake. Reoffer
+   * everything not bound to the live session now (an empty live id reoffers all: nothing is
+   * consumable without a live session). NEVER a repost into the new session. The deliverMidTurn
+   * result still reports the POST's own truthful outcome; the onReoffer settlement is the
+   * authoritative resolution — the same interplay as the clear/reroll call sites, whose
+   * reoffers arrive after earlier results already reported persistedIds.
+   */
+  private async reofferStaleSessionBatches(liveSessionId: string | undefined, deadSessionId: string): Promise<number[]> {
+    // An undefined/empty live id reoffers ALL entries: nothing is consumable without a live session.
+    const reoffered = await this.softSteer.sessionReplaced(liveSessionId ?? "");
+    if (reoffered.length > 0) {
+      logger.info("opencode", `soft-steer: session swapped inside the POST window (${deadSessionId} → ${liveSessionId || "<none>"}); reoffered ${reoffered.length} relay id(s) to the normal queue`);
+    }
+    return reoffered;
+  }
+
+  /**
+   * #2539 Phase B — the bounded idle-wake fallback: the provider just went idle with
+   * positively-persisted-but-unconsumed soft batches (mid-run reload missed them — the live
+   * at-stop strand, or an unknown-outcome batch). Arm EXACTLY ONE content-free wake turn through
+   * turnQueue (a NORMAL send() turn: real busy/idle pair, full retry semantics — no second turn
+   * machinery, no resend of the steer payload). Event-driven only: armed from turn-close edges
+   * and the post-POST race check, never from a wall-clock timer. Its completion settles the
+   * batches it was armed for (their rows are provably in the session context by then); the
+   * consumption door remains the primary settle path and stays idempotent with this one.
+   */
+  private maybeArmSoftSteerWake(process?: ManagedProcess): void {
+    if (this.softSteer.isWakePending()) return;
+    const target = process ?? this.softSteerProcess;
+    const sessionId = stringValue(target?.meta?.sessionId);
+    if (!target || !sessionId || !this.softSteer.hasAwaiting(sessionId)) return;
+    const armed = this.softSteer.armWake(sessionId);
+    if (!armed) return;
+    logger.info("opencode", `soft-steer wake armed on session ${sessionId} for ${armed.targets.length} unconsumed batch(es)`);
+    void this.enqueueTurn(() => this.send(target, OPENCODE_SOFT_STEER_WAKE_TEXT))
+      .then(async (ok) => {
+        // Failed wake turn: leave the entries pending — session replacement / shutdown reoffer
+        // them to the normal queue (a failed session must not mark anything delivered, and the
+        // old delete-then-maybe-notify order here silently dropped them).
+        if (ok !== "ok") return;
+        const settled = await this.softSteer.settleWakeTargets(armed);
+        if (settled.length > 0) logger.info("opencode", `soft-steer wake settled ${settled.length} relay id(s) on session ${sessionId}`);
+      })
+      .catch((error) => logger.warn("opencode", `soft-steer wake turn failed: ${errMessage(error)}`))
+      .finally(() => this.softSteer.endWake());
+  }
+
+  async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as OpenCodeClient | undefined;
+    const sessionId = stringValue(process.meta?.sessionId);
+    if (!client || !sessionId) throw new Error("OpenCode session is not ready");
+    await client.abort(sessionId);
+    return { sessionId, method: "session.abort" };
+  }
+
+  /**
+   * #2431 — self-resume clear-inject support: mint a fresh, history-less session and make it the
+   * active one. This REUSES the proven #2397 re-roll seam (the same `POST /session` via
+   * `createSession`, which explicitly drops conversation history, and the same in-place
+   * `process.meta.sessionId` swap so every reader — send/interrupt/shutdown and the SSE doors'
+   * foreign-session filter — picks the new id up with no separate bookkeeping); it does not invent
+   * a second session-minting mechanism.
+   *
+   * Ordering/composition with the turn state machine (#2397/#2425/#2427/#2428) is ENFORCED, not
+   * assumed (round 1 HIGH): the whole swap runs inside `enqueueTurn`, so a clear that arrives while
+   * a turn is mid-flight — which DOES happen, since the model calls relay_compact_and_resume from
+   * within its own synchronous `/message` turn and dispatchCommand gives agent.clearContext no
+   * provider-input ticket — waits for that turn to settle and completes it wholly on the session
+   * it started with before minting anything. The reactive continuation inject is separately
+   * serialized behind deliveries through providerInput.run (`PROVIDER_INPUT_COMMAND_TYPES`), so the
+   * first thing that touches the new session is a delivery, never a half-swapped retry. The last
+   * closed turn left `turnClosed` set and `suppressProviderIdle` sticky per round-5 MED-1; those
+   * fields are deliberately NOT touched — resetting them could double-close an already-closed turn,
+   * and any trailing SSE event belonging to the PRE-clear turn carries the OLD sessionID, which the
+   * #2425 foreign-session filter now drops against the NEW active id. Same reasoning leaves
+   * `messageRoles`/`emittedTextParts`/`emittedToolSteps` alone: ids are server-global on this one
+   * process and pruned to OPENCODE_EVENT_STATE_LIMIT regardless (the #2397 re-roll leaves them
+   * too). The SSE subscription is per-server, not per-session, so the new session stays fully
+   * observable through the existing wiring.
+   *
+   * Only relayContextSent re-arms after the fresh session exists, so the first delivery carries
+   * the generic Relay context again. The systemPromptAppend launch block is intentionally NOT
+   * re-sent here: server startup-context and memory-injection seams own post-boundary charter
+   * and memory re-delivery.
+   * The fresh ContextState mirrors Codex's clearContext shape: utilization 0 IS ground truth
+   * immediately after a wipe.
+   */
+  async clearContext(process: ManagedProcess): Promise<Record<string, unknown>> {
+    return this.enqueueTurn(() => this.swapSessionForClear(process));
+  }
+
+  private async swapSessionForClear(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as OpenCodeClient | undefined;
+    const previousSessionId = stringValue(process.meta?.sessionId);
+    if (!client || !previousSessionId) throw new Error("OpenCode session is not ready");
+    // #2459 — the session swap is also an attachment-generation rotation: any open event-driven
+    // terminal turn belongs to the OLD session (its matching idle carries the old sessionID and
+    // would be dropped by the foreign-session filter, stranding runner-core busy). Close it on
+    // the old session's truth before the swap; the orchestrator's generation check kills the
+    // stale guest TUI on its next input/stream contact.
+    // #2459 round 2 (review D) — flush a buffered terminal prompt under the OLD session
+    // pseudo-turn before the swap (the operator typed there; the buffer must not leak into
+    // the new session), then close any open terminal turn as in send() takeover.
+    this.flushBufferedPrompt(previousSessionId || undefined);
+    if (this.eventTurnId) this.closeEventTurn();
+    this.statusCb({ status: "busy", reason: "provider-turn", timeline: { status: "clearing-context", timestamp: Date.now() } });
+    let newSessionId: string;
+    try {
+      newSessionId = await client.createSession(stringValue(process.meta?.sessionTitle) ?? "agent-relay");
+    } catch (error) {
+      // The old session is still intact and active — restore idle so the failed command doesn't
+      // strand a provider-turn busy hold (same recovery shape as Codex's clearContext).
+      this.statusCb({ status: "idle", reason: "provider-turn" });
+      throw error;
+    }
+    const clearedAt = Date.now();
+    if (process.meta) {
+      process.meta.sessionId = newSessionId;
+      // #2539 Phase B — soft-steer fencing: batches accepted-but-unconsumed on the replaced
+      // session can never be consumed on the fresh one; their relay ids go BACK to the runner's
+      // normal queue (the settlement callback fires inside sessionReplaced — never reposted into
+      // the cleared session).
+      const softSteerOrphans = await this.softSteer.sessionReplaced(newSessionId);
+      if (softSteerOrphans.length > 0) {
+        logger.info("opencode", `soft-steer: reoffering ${softSteerOrphans.length} relay id(s) after clear swapped session`);
+      }
+      process.meta.relayContextSent = false;
+      // Boundary charter/memory delivery belongs to the server inject seams.
+      process.meta.launchContextSent = true;
+      process.meta.context = freshContextState(clearedAt);
+    }
+    this.statusCb({ status: "idle", reason: "provider-turn", timeline: { status: "context-cleared", timestamp: clearedAt } });
+    return { previousSessionId, sessionId: newSessionId };
+  }
+
+  /**
+   * #2440 — native self-resume compaction via OpenCode's own `POST /session/{id}/compact`
+   * (mistakenly believed unavailable when #2431 shipped clear-inject only). Reuses the SAME
+   * turnQueue FIFO serializer clearContext() established: `agent.compact` is dispatched
+   * fire-and-forget with no provider-input ticket (like `agent.clearContext`), and OpenCode's
+   * `/message` POST is synchronous, so a compact triggered from inside the model's own turn
+   * (relay_compact_and_resume) genuinely races an in-flight send() without it. See the
+   * `turnQueue` field doc for the full race shape this closes off.
+   */
+  async compact(process: ManagedProcess, opts?: { instructions?: string }): Promise<Record<string, unknown>> {
+    await this.apiBudgets.get(process)?.prepare();
+    return this.enqueueTurn(() => this.performCompact(process, opts));
+  }
+
+  /**
+   * `opts.instructions` (the relay-built continuation note) is deliberately NOT threaded into the
+   * `/compact` request body: this pinned server version's wire shape for a steering instruction on
+   * that endpoint is unconfirmed, and guessing wrong risks a hard 4xx in place of a clean
+   * compaction. This is safe to skip — OpenCode does not couple continuation delivery in-process
+   * (no `couplesClearInjectContinuation`, same as its clear-inject path today), so the relay's own
+   * reactive continuation inject (`enqueueContinuationInjectionAfterSelfResume`, src/self-resume.ts)
+   * delivers the SAME continuation as a follow-up `agent.injectContext` once this command succeeds
+   * — the identical path clear-inject already relies on for OpenCode (see the #2431 test "the first
+   * post-clear delivery lands in the NEW session ... through the same deliver()/send() path").
+   */
+  private async performCompact(process: ManagedProcess, _opts?: { instructions?: string }): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as OpenCodeClient | undefined;
+    const sessionId = stringValue(process.meta?.sessionId);
+    if (!client || !sessionId) throw new Error("OpenCode session is not ready");
+    this.statusCb({ status: "busy", reason: "provider-turn", timeline: { status: "compacting", timestamp: Date.now() } });
+    try {
+      await client.compact(sessionId);
+    } catch (error) {
+      // The session is still intact and active — restore idle so a failed command doesn't strand
+      // a provider-turn busy hold (same recovery shape as clearContext's own catch above).
+      this.statusCb({ status: "idle", reason: "provider-turn" });
+      throw error;
+    }
+    const compactedAt = Date.now();
+    const currentContext = process.meta?.context as ContextState | undefined;
+    if (process.meta) {
+      // #2440 round 2 — stamp unconditionally, mirroring swapSessionForClear's shape: a compact
+      // that lands before any context state was ever reported (e.g. immediately after spawn) must
+      // still record the compaction rather than silently no-oping, exactly like clearContext's
+      // always-fresh stamp below. Falls back to clearContext's own baseline defaults (utilization
+      // 0, no warm topics/active memories, source "api"/confidence "reported") when there is no
+      // prior state to carry forward; lifecycleState is "cooling" (not "fresh") because — unlike a
+      // clear — compact does not wipe conversation history.
+      process.meta.context = {
+        ...(currentContext ?? { utilization: 0, warmTopics: [], source: "api" as const, confidence: "reported" as const }),
+        lifecycleState: "cooling",
+        tasksSinceCompact: 0,
+        lastCompactedAt: compactedAt,
+        lastUpdatedAt: compactedAt,
+      } satisfies ContextState;
+    }
+    this.statusCb({ status: "idle", reason: "provider-turn", timeline: { status: "compacted", timestamp: compactedAt } });
+    return { sessionId };
+  }
+
+  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
+    // #2539 Phase B — anything accepted-but-unconsumed goes back to the runner's normal queue via
+    // the settlement callback (inside reofferAll) before teardown; the ledger itself never drops
+    // an id silently — a failed callback re-inserts the entries for the next exit.
+    const softSteerLeftovers = await this.softSteer.reofferAll();
+    if (softSteerLeftovers.length > 0) logger.info("opencode", `soft-steer: shutdown reoffering ${softSteerLeftovers.length} relay id(s)`);
+    this.softSteerProcess = undefined;
+    // #2484 round 1 review (F2/F3) — session end: force any still-pending debounced token-usage
+    // report out now, rather than losing it to a timer that never gets to fire. Round 2 (MED-1)
+    // — awaited, not fire-and-forget: this covers the controlled-teardown paths that call
+    // adapter.shutdown() directly (restartProvider, shutdownProvider) without going through
+    // runner-core's settleTerminalTokenUsage seam first.
+    await this.tokenUsagePoster.flushAll();
+    (process.meta?.events as AbortController | undefined)?.abort();
+    if (opts.graceful) await this.interrupt(process).catch(() => {});
+    const outcome = await terminateProviderProcesses(process.process ? [process.process] : [], opts);
+    if ((process.process as Bun.Subprocess | undefined)?.exitCode !== null) await this.apiBudgets.get(process)?.settle().catch(() => {});
+    return outcome;
+  }
+
+  /**
+   * Exported behavior through the adapter so fixture contracts can pin the v1.18.21 event shapes.
+   *
+   * Reproduced live against a real server (#2347): the wire shapes here were captured directly
+   * off `/event`, not inferred from docs. Two things the previous implementation got wrong:
+   *
+   * 1. `session.status` carries a nested `{ status: { type: "busy" | "idle" } }`, not a bare
+   *    `properties.status` string — so idle was never detected and a finished turn never told
+   *    Relay it was done. `session.updated` never carries a status field at all; it no longer
+   *    needs to be treated as a status source.
+   * 2. `message.updated` only ever carries message metadata (`properties.info`, with `role`) —
+   *    never the reply text. The assistant's text streams separately as `message.part.updated`
+   *    events (`properties.part`), one per part, finalized once `part.time.end` is set. A
+   *    message's `message.updated` (role) event always arrives before that message's part
+   *    events, so `messageRoles` is populated before any part needs to look a role up.
+   */
+  handleEvent(event: OpenCodeServerEvent, process?: ManagedProcess): void {
+    const properties = event.properties ?? {};
+    if (event.type === "session.status") {
+      // #2425 — a foreign-session event must never affect this adapter's turn/idle state, full
+      // stop, regardless of suppression state. This is what makes it safe for the two doors below
+      // to stop enforcing PERMANENT suppression once `turnAbandoned`: an unfiltered foreign child
+      // session's busy/idle was exactly the hazard round 7 made suppression permanent to guard
+      // against, and this filter closes it directly instead.
+      // #2459 round 1 (review C) — FAIL CLOSED: whenever the active session id is known (a live
+      // spawn always carries one), an event WITHOUT a sessionID is rejected too — a session-
+      // less status cannot be positively attributed to the active conversation, and acting on
+      // it could open/close a turn for a dead session. Test-only call sites that pass no
+      // process (hence no active id) keep the lenient behavior.
+      const sessionID = stringValue(properties.sessionID);
+      const activeSessionId = stringValue(process?.meta?.sessionId);
+      if (activeSessionId && sessionID !== activeSessionId) return;
+      const statusValue = properties.status;
+      const status = stringValue(isRecord(statusValue) ? statusValue.type : statusValue);
+      if (status === "retry") {
+        this.onServerRetry(parseOpenCodeServerRetry(statusValue), process);
+        return;
+      }
+      if (status === "busy") {
+        // send() owns the turn boundary while a headless delivery is in flight — its own
+        // explicit busy (with its minted id) is authoritative, exactly as before #2459. Only
+        // busy events OUTSIDE send() can open a terminal-origin turn below.
+        if (this.turnInFlight) return;
+        // A terminal turn is already open — its matching idle owns the close; a duplicate
+        // busy must not re-mint.
+        if (this.eventTurnId) return;
+        // #2425 — re-arm the close guard: this real busy is evidence the turn (from
+        // `send()`'s perspective, already force-closed to idle by the abandonment path) is
+        // actually still running, so the eventual matching idle must be allowed to close it
+        // again.
+        if (this.turnAbandoned) this.turnClosed = false;
+        // #2459 round 1 (review D) — #2397 round-7 echo guard, restored to PERMANENT and made
+        // POSITIVE (no time heuristic): once any headless turn has run on this process, a busy
+        // is admitted ONLY when a fresh terminal user prompt armed `pendingTerminalPrompt` (the
+        // TUI's POST creates the user message before the turn's busy flows). The buffered
+        // own-turn echo has no fresh user message by construction — at ANY delay — so it stays
+        // swallowed. (#2425 abandonment keeps this door open — those server events are the only
+        // remaining proof of the turn's real state.)
+        if (!this.turnAbandoned && this.headlessTurnSeen && !this.pendingTerminalPrompt) return;
+        // #2459 round 1 (review D) — a genuinely new, terminal-origin turn: mint its provider turn id and hand it
+        // to runner-core (which keys currentTurnId off this busy), then associate every user/
+        // assistant/tool message id of the turn with it (see activeTurnId()) until the matching
+        // idle closes it. Un-stick the idle suppression so this turn's own idle can pass.
+        this.pendingTerminalPrompt = false; // consumed
+        this.eventTurnId = `opencode-turn-${crypto.randomUUID()}`;
+        this.eventTurnText = [];
+        this.eventTurnReasoning = new Map();
+        this.suppressProviderIdle = false;
+        // #2459 round 2 (review D) — a prompt buffered by the [user message → user part →
+        // busy] ordering is emitted NOW under the freshly minted id, so prompt → trace →
+        // final-response all share one opencode-turn-* id.
+        this.flushBufferedPrompt(this.eventTurnId);
+        this.statusCb({ status: "busy", reason: "provider-turn", id: this.eventTurnId });
+      }
+      if (status === "idle") {
+        // send() closes its own turn deterministically (closeSuppressedTurn / failTurn / the
+        // finally) — an SSE idle while a headless delivery is in flight stays swallowed, as
+        // since #2397 round 2.
+        if (this.turnInFlight) return;
+        // #2459 round 2 (review D) — bounded fallback: an active-session idle with a prompt
+        // still buffered means the turn ended without us seeing its busy (or it was itself an
+        // echo). Flush under the session pseudo-turn so the operator's input is never stranded
+        // in the buffer; RunnerCore's injection dedup guards the chat-echo case.
+        if (this.bufferedTerminalPrompt && !this.eventTurnId) {
+          this.flushBufferedPrompt(stringValue(process?.meta?.sessionId) || undefined);
+        }
+        // #2459 — the matching close of an event-driven (terminal) turn: emit the turn-final
+        // response accumulated from the turn's live assistant text parts (mirroring send()'s
+        // emitTurnFinalResponse → close ordering) and then the idle edge that closes
+        // runner-core's turn.
+        if (this.eventTurnId) {
+          this.closeEventTurn();
+          return;
+        }
+        // #2397 round 2 (F4) — a transient idle from a failed attempt, still mid-retry-loop.
+        // #2397 round 7 review (MED-2/LOW-1) — round 6's one-shot reopen (lower the flag on the
+        // FIRST post-close idle, keyed on `turnInFlight`) let a SECOND idle in the same trailing-
+        // echo window pass through and double-close. There is no legitimate turn boundary this SSE
+        // door needs to report that `send()`/`closeSuppressedTurn`/`failTurn` don't already emit
+        // explicitly for a DETERMINISTIC outcome (see the field comment) — so there is no reopen on
+        // that path: suppression stays permanent for any turn `send()` itself closed knowingly.
+        // #2459 — EXCEPT the terminal-origin path above: an idle outside send() with no event
+        // turn open is still an echo/stray (the busy that minted a turn would have set one), so
+        // the permanent suppression holds exactly as before for chat turns.
+        // #2425 — the one exception is the same `turnAbandoned` escape hatch as the busy door
+        // above; `turnClosed` (not `suppressProviderIdle`) is what still prevents a double-close
+        // here — either the abandonment path's own forced idle already closed it (this real idle
+        // is then a no-op confirmation), or a real busy re-armed it above and this is the genuine
+        // close.
+        if (this.suppressProviderIdle && !this.turnAbandoned) return;
+        if (this.turnClosed) return;
+        this.turnClosed = true;
+        this.statusCb({ status: "idle", reason: "provider-turn", clear: ["provider-turn"] });
+      }
+      return;
+    }
+    if (event.type === "permission.asked") {
+      if (!this.turnInFlight && !this.eventTurnId) return;
+      // `opencode.json` grants every permission for this open-only adapter. Keep the event
+      // observable in case a future server version ignores the config; never surface a misleading
+      // guarded approval form or silently reinterpret the session's requested policy.
+      this.statusCb({ status: "busy", reason: "provider-turn", providerState: { state: "active", reason: "openPermission", label: "OpenCode permission auto-allowed by approvalMode=open", source: "opencode", updatedAt: Date.now() } });
+      return;
+    }
+    if (event.type === "message.updated") {
+      const info = isRecord(properties.info) ? properties.info : undefined;
+      const id = info ? stringValue(info.id) : undefined;
+      const role = info ? stringValue(info.role) : undefined;
+      if (id && role) {
+        this.messageRoles.set(id, role);
+        pruneToLimit(this.messageRoles, OPENCODE_EVENT_STATE_LIMIT);
+      }
+      // #2427 — the SSE echo of a finalized assistant message carries the SAME per-message
+      // `tokens` totals the synchronous POST resolves with (send()'s #2355 report), but on a long
+      // turn that POST can die client-side or stay in-flight forever, so usage reported ONLY from
+      // it never lands (#2427's blank context-window). Report from this door instead: it fires
+      // DURING the turn regardless of POST survival, mirroring how Codex consumes its
+      // `thread/tokenUsage/updated` push. Idempotent with the POST path — last write wins and both
+      // doors feed the same openCodeContextState no-signal rules (0/unparsable → no-op), so neither
+      // can regress a good reading — and same-session-filtered like #2425's session.status door.
+      // #2459 round 1 (review C) — FAIL CLOSED: with the active session id known, a usage echo
+      // WITHOUT a sessionID is rejected too (an unattributable reading must never overwrite the
+      // active session's context state). Test-only process-less call sites keep the lenient path.
+      const sessionID = stringValue(properties.sessionID);
+      const activeSessionId = stringValue(process?.meta?.sessionId);
+      const tokens = countTokens(info?.tokens);
+      const sessionUnattributable = Boolean(activeSessionId && sessionID !== activeSessionId);
+      if (process && role === "assistant" && tokens !== undefined && !sessionUnattributable) {
+        const model = stringValue(process.meta?.model) ?? openCodeQualifiedModel(undefined, this.provider);
+        this.reportContextUsage(process, model, tokens);
+      }
+      // #2484 — same door, reused for the spine report: model/createdAt prefer the message's
+      // own info (round 1 review F5/F6) over the session's configured model / receipt time.
+      // #3351 — outside the context guard so a finished message without counts reports unknown.
+      if (process && role === "assistant" && id) captureOpenCodeApiUsage(this.apiBudgets.get(process), info, sessionID ?? activeSessionId, stringValue(process.meta?.model), id);
+      if (process && role === "assistant" && id && !sessionUnattributable) {
+        scheduleOpenCodeTokenUsage(this.tokenUsagePoster, {
+          provider: this.provider,
+          sessionId: activeSessionId ?? sessionID,
+          model: openCodeMessageModel(info) ?? stringValue(process.meta?.model) ?? openCodeQualifiedModel(undefined, this.provider),
+          messageId: id,
+          tokens: info?.tokens,
+          createdAt: openCodeMessageObservedAt(info),
+          finished: openCodeMessageFinished(info),
+        });
+      }
+      // #2459 round 1 (review D) — ARM the terminal-turn gate: a FIRST-SEEN user message on the
+      // ACTIVE session observed outside send() is the event-source proof that a human typed into
+      // the attached TUI. The next active-session busy is then admitted as terminal-origin even
+      // after a headless close (whose own buffered echo carries no fresh user message — its user
+      // echo was already seen live during send(), so the dedup set prevents the late duplicate
+      // from arming). Fail-closed session-filtered like the usage read above, never armed while
+      // send() is in flight (the chat delivery's own user echo must not open a terminal turn
+      // behind send()'s back) nor while a terminal turn is already open.
+      // #2539 Phase B — soft-steer consumption door: an assistant message whose info.parentID
+      // equals a soft batch's user row id is positive proof the active loop CONSUMED that batch
+      // (the loop reloads full messages each step and re-parents subsequent assistant steps to
+      // the newest user row — live-verified on pinned 1.18.21). FIFO settle: the matched batch
+      // plus every OLDER pending batch, ids marked once. Same-session fail-closed like the usage
+      // read above — a stale session's echo must never settle a live batch.
+      const parentID = isRecord(info) ? stringValue(info.parentID) : undefined;
+      if (process && role === "assistant" && activeSessionId && parentID) {
+        // Settlement callbacks fire inside consumeByParent (consumed → reoffer fallback on
+        // callback failure); this door only logs the outcome. Terminal .catch satisfies the
+        // unguarded-async ratchet (the settle path already never rejects).
+        void this.softSteer.consumeByParent(parentID, activeSessionId).then((consumed) => {
+          if (consumed.length > 0) logger.info("opencode", `soft-steer batch consumed on session ${activeSessionId}: settling ${consumed.length} relay id(s)`);
+        }).catch((error) => logger.warn("opencode", `soft-steer consumption door failed: ${errMessage(error)}`));
+      }
+      if (role === "user" && id) {
+        const firstSeen = !this.seenUserMessageIds.has(id);
+        this.seenUserMessageIds.add(id);
+        pruneToLimit(this.seenUserMessageIds, OPENCODE_EVENT_STATE_LIMIT);
+        // #2539 Phase B — relay's OWN soft-steer user rows never arm the terminal-origin gate:
+        // they are first-seen user messages OUTSIDE send() (the whole point of the lane), and
+        // arming here would misclassify the wake turn (or any user's next turn) as terminal.
+        const terminalOrigin = firstSeen && !this.turnInFlight && !this.eventTurnId && !sessionUnattributable && !this.softSteer.isTrackedUserId(id);
+        if (terminalOrigin) this.pendingTerminalPrompt = true;
+        if (terminalOrigin) adoptOpenCodeTerminalModel(process?.meta, info); // #2659 — keep a model picked in the TUI
+      }
+      return;
+    }
+    if (event.type === "message.part.updated") {
+      const part = isRecord(properties.part) ? properties.part : undefined;
+      if (!part) return;
+      // #2534 — acceptance door: a persisted user text part whose text equals the armed
+      // context-carrying outbound prompt is positive proof OpenCode ACCEPTED it. Consuming here
+      // marks the first-turn markers MID-TURN — seconds after dispatch — so a first turn that
+      // later runs past the whole-turn deadline can never leave them false (the await-then-mark
+      // flaw that re-prepended the ~48KB launch briefing to every queued message). Session and
+      // text identity are fail-closed inside consumeOpenCodeContextAcceptance: a stale-session
+      // echo or an operator-typed prompt never marks.
+      consumeOpenCodeContextAcceptance(process, stringValue(properties.sessionID), stringValue(part.text));
+      // #2389 — ANY part on an assistant message is proof the model produced something, including
+      // the tool parts this adapter does not mirror (their internal shape is not pinned, so they are
+      // reported as bare activity rather than published as a half-understood trace step). Without
+      // this a tools-only OpenCode turn emits no session events at all and reads as empty.
+      // #2397 round 3 review (HIGH-1r) — EXCEPT a bare step-start/step-finish bookkeeping part,
+      // which the server emits on every turn regardless of outcome. `isOutputPart` is the same
+      // predicate `completionProducedOutput` uses on the POST-body door (HIGH-1); this is the SSE
+      // door, and both must agree or the issue's own incident (a step-start-only turn) still
+      // discharges #2389's escalation through whichever door fires first. `noteOutput()` is called
+      // with no event here (onTurnActivity takes no args), so MED-5's `diagnostic` filter cannot
+      // see this path at all — it must be excluded at the source instead.
+      if (isOutputPart(part) && this.messageRoles.get(stringValue(part.messageID) ?? "") === "assistant") this.turnActivityCb();
+      // #2459 round 2 (review D) — no-busy-seen fallback, bounded: when trace activity
+      // (tool/narration/reasoning) arrives while a terminal prompt is still buffered and no
+      // terminal turn ever opened, flush the prompt FIRST under the same session pseudo-turn
+      // the trace will use, keeping prompt→trace grouped instead of stranding the buffer.
+      if (this.bufferedTerminalPrompt && !this.eventTurnId && !this.turnInFlight) {
+        this.flushBufferedPrompt(stringValue(process?.meta?.sessionId) || undefined);
+      }
+      // #2354 — surface tool calls in chat/timeline the way Codex does: decode the ToolPart and
+      // emit a running/completed/failed/cancelled session step (upserted in place by stepId). This
+      // must run before the text-only early-return below, which used to drop every non-text part.
+      if (stringValue(part.type) === "tool") {
+        this.emitToolStep(part, process);
+        return;
+      }
+      // #2605 — surface the model's thinking as a `reasoning` trace row the way Codex/Claude do:
+      // decode the ReasoningPart and emit it (upserted in place by stepId = stable part id). Runs
+      // before the text-only early-return below, which is also what used to drop these parts.
+      if (stringValue(part.type) === "reasoning") {
+        this.emitReasoningStep(part, process);
+        return;
+      }
+      if (stringValue(part.type) !== "text") return;
+      const partId = stringValue(part.id);
+      const messageId = stringValue(part.messageID);
+      const text = stringValue(part.text);
+      const finalized = isRecord(part.time) && part.time.end !== undefined;
+      if (!partId || !messageId || !text || !finalized) return;
+      // #2459 — a finalized role:user text part on the ACTIVE server session is a prompt typed
+      // into an attached web-terminal TUI: mirror it into chat as a terminal-origin prompt.
+      // RunnerCore's recordInjectedPrompt already consumes the echo of every Relay-injected
+      // prompt (chat deliveries), so terminal prompts appear once while dashboard-injected
+      // prompts do not duplicate. #2459 round 1 (review C) — FAIL CLOSED: with the active
+      // session id known, a part WITHOUT a sessionID is rejected too — after a clearContext()
+      // or retry re-roll an unattributable/old-session prompt belongs (at best) to a dead
+      // conversation, and the generation boundary kills that stale TUI anyway.
+      if (this.messageRoles.get(messageId) === "user") {
+        const eventSessionId = stringValue(properties.sessionID);
+        const activeSessionId = stringValue(process?.meta?.sessionId);
+        if (activeSessionId && eventSessionId !== activeSessionId) return;
+        if (this.emittedTextParts.has(partId)) return;
+        this.emittedTextParts.add(partId);
+        pruneToLimit(this.emittedTextParts, OPENCODE_EVENT_STATE_LIMIT);
+        // #2459 round 2 (review D) — turn-id ordering. While send() is in flight, emit
+        // immediately under send()'s id (RunnerCore dedups the chat-injection echo). While a
+        // terminal turn is open, emit under its minted id. Otherwise — the [user message →
+        // user part → busy] wire ordering, where the TUI's POST creates the user message
+        // BEFORE the busy edge mints the terminal turn id — BUFFER the prompt: emitting now
+        // would publish the raw session id as a turnId and split the prompt from its
+        // trace/final. The buffer is flushed under the minted id at busy admission, and the
+        // bounded no-busy fallbacks (trace activity, any active-session idle, chat delivery
+        // takeover, session swap) flush it under the session pseudo-turn — NEVER under a
+        // stale headless sendTurnId.
+        if (this.turnInFlight) {
+          const turnId = this.sendTurnId ?? activeSessionId;
+          this.sessionEventCb({ type: "prompt", origin: "terminal", body: text, ...(turnId ? { turnId } : {}) });
+          return;
+        }
+        if (this.eventTurnId) {
+          this.sessionEventCb({ type: "prompt", origin: "terminal", body: text, turnId: this.eventTurnId });
+          return;
+        }
+        if (this.bufferedTerminalPrompt) this.flushBufferedPrompt(activeSessionId || undefined);
+        this.bufferedTerminalPrompt = { body: text, occurredAt: Date.now() };
+        return;
+      }
+      if (this.messageRoles.get(messageId) !== "assistant") return;
+      if (this.emittedTextParts.has(partId)) return;
+      this.emittedTextParts.add(partId);
+      pruneToLimit(this.emittedTextParts, OPENCODE_EVENT_STATE_LIMIT);
+      // #2459 — while an event-driven terminal turn is open, its finalized assistant text also
+      // accumulates toward the turn-final response emitted by closeEventTurn().
+      if (this.eventTurnId) this.eventTurnText.push(text.trim());
+      const turnId = this.activeTurnId() ?? stringValue(process?.meta?.sessionId);
+      this.sessionEventCb({ type: "narration", origin: "provider", body: text, ...(turnId ? { turnId } : {}) });
+    }
+  }
+
+  /**
+   * #2605 — decode one ReasoningPart and emit its trace row, with in-place upsert semantics: a
+   * reasoning part GROWS as the model thinks (SSE emits the part repeatedly, each frame carrying
+   * the FULL text so far), so a frame for an already-emitted part id re-emits the current full
+   * body — the server upserts it into the same row by stepId. Only assistant-message reasoning
+   * parts are surfaced (same fail-closed role gate as emitToolStep). `streaming` stays true
+   * while the part is unfinished (`time.end` unset), false on finalize — mirroring the tool
+   * step's running→terminal upsert. Reasoning arriving while an event-driven terminal turn is
+   * open also accumulates toward the turn-final reasoning emitted by closeEventTurn().
+   */
+  private emitReasoningStep(part: Record<string, unknown>, process?: ManagedProcess): void {
+    const messageId = stringValue(part.messageID);
+    if (!messageId || this.messageRoles.get(messageId) !== "assistant") return;
+    const step = decodeOpenCodeReasoningPart(part);
+    // Empty reasoning text is backend muzak (the provider's own SQLite shows sessions whose
+    // first persisted reasoning part is `""`) — not operator signal. Dropping it here (rather
+    // than emitting an empty row) also keeps noteOutput's `!body.trim()` filter from ever
+    // seeing it. A part that STARTS empty still gets its row the moment text arrives.
+    if (!step) return;
+    const prev = this.emittedReasoningParts.get(step.stepId);
+    if (prev === step.body) return;
+    this.emittedReasoningParts.set(step.stepId, step.body);
+    pruneToLimit(this.emittedReasoningParts, OPENCODE_EVENT_STATE_LIMIT);
+    // #2605 — record the latest snapshot per part for the event-turn close below. Unconditional
+    // (not just on emit): the close's reconcile must see the newest body even for frames that
+    // were live-emitted, so it can compare per-part and emit nothing already traced.
+    if (this.eventTurnId) this.eventTurnReasoning.set(step.stepId, step.body);
+    const finalized = isRecord(part.time) && part.time.end !== undefined;
+    this.sessionEventCb(openCodeReasoningSessionEvent(step, this.activeTurnId() ?? stringValue(process?.meta?.sessionId), !finalized));
+  }
+
+  /**
+   * #2354 — decode one ToolPart and emit its session step, with dedup + terminal-lock: a
+   * duplicate frame or a reordered update (a late `running` after `completed`) is dropped rather
+   * than regressing or double-appending the row. Only assistant-message tool parts are surfaced.
+   * `stepId` = the stable part id, so the server upserts running→completed IN PLACE (one row),
+   * exactly like Codex's app-server item-id upsert.
+   */
+  private emitToolStep(part: Record<string, unknown>, process?: ManagedProcess): void {
+    // #2354 review (LOW) — fail CLOSED: a tool part lacking a messageID (so its role can't be
+    // confirmed assistant) is dropped, not surfaced.
+    const messageId = stringValue(part.messageID);
+    if (!messageId || this.messageRoles.get(messageId) !== "assistant") return;
+    const step = decodeOpenCodeToolPart(part);
+    if (!step) return;
+    const rank = openCodeToolStatusRank(step.status);
+    const prevRank = this.emittedToolSteps.get(step.stepId);
+    if (prevRank !== undefined && rank <= prevRank) return;
+    this.emittedToolSteps.set(step.stepId, rank);
+    pruneToLimit(this.emittedToolSteps, OPENCODE_EVENT_STATE_LIMIT);
+    if (step.params !== undefined) this.toolStepParams.set(step.stepId, step.params);
+    const params = step.params !== undefined ? step.params : this.toolStepParams.get(step.stepId);
+    pruneToLimit(this.toolStepParams, OPENCODE_EVENT_STATE_LIMIT);
+    // #2459 — tool steps attach to the live turn id (send()'s while a headless delivery runs,
+    // the event-driven terminal turn otherwise), never to a stale prior headless turn id.
+    this.sessionEventCb(openCodeToolSessionEvent({ ...step, params }, this.activeTurnId() ?? stringValue(process?.meta?.sessionId)));
+  }
+
+  /**
+   * #2413 — mark the turn-final assistant text as a `response` (not `narration`), so the runner's
+   * Final Response capture identifies it, auto-forwards an OpenCode child's report to its
+   * coordinator, and the chat styles it apart from reasoning — parity with Claude/Codex, which
+   * OpenCode lacked entirely (everything read as thinking, nothing auto-forwarded).
+   *
+   * #2605 — also emits the turn-final `reasoning` rows from the SAME completed assistant message
+   * (`completion.reasoningSteps`, via `openCodeTurnFinalEvents` in opencode-tool-events.ts), so
+   * the model's thinking survives in the trace even when the SSE reasoning frames were never
+   * observed (a POST-only reader, a dropped subscription, a turn whose frames raced the close):
+   * the completed message persists every part with its full text. Each row carries its OWN part
+   * id as stepId — the exact key the live SSE door already emitted — so the server upserts
+   * live+final into ONE row (the upsert keys on stepId ONLY); a merged body under a synthetic
+   * stepId would store the turn's thinking twice. The ledger below is the per-part
+   * emitted-body record the SSE door shares, scoped to part ids — never a global body pool.
+   *
+   * The text is read from the synchronous POST's completed assistant message (`completion.text`,
+   * ground truth per #2389) rather than reconstructed from SSE. `confidence:"definitive"` because
+   * the POST returning IS the provider-native turn-end edge; `final:true` is what makes it a
+   * turn-final capture downstream. The same text already streamed live as `narration` (per text
+   * part); the dashboard's per-turn narration/response dedup (keyed on the shared `turnId`)
+   * suppresses the duplicate, exactly as it does for Codex.
+   */
+  private emitTurnFinalResponse(process: ManagedProcess, completion: OpenCodeCompletion): void {
+    const turnId = this.sendTurnId ?? stringValue(process.meta?.sessionId);
+    const emittedBodies: Record<string, string> = {};
+    for (const [stepId, body] of this.emittedReasoningParts) emittedBodies[stepId] = body;
+    for (const event of openCodeTurnFinalEvents(completion, turnId, emittedBodies)) this.emitReasoningFinal(event);
+  }
+
+  /** #2605 — ledger write for a turn-final reasoning row, shared by both turn-close seams. */
+  private emitReasoningFinal(event: ProviderSessionEvent): void {
+    if (event.stepId) {
+      this.emittedReasoningParts.set(event.stepId, event.body);
+      pruneToLimit(this.emittedReasoningParts, OPENCODE_EVENT_STATE_LIMIT);
+    }
+    this.sessionEventCb(event);
+  }
+
+  /**
+   * #2397 — turn-ending PROVIDER errors (e.g. an OpenRouter 429 on a throttled preview model)
+   * are read off THIS synchronous POST's response body (`completion.error`, via
+   * `openCodeCompletion`), not off a separate SSE listener. #2389 already established that this
+   * response is ground truth and deterministic (no dependency on an SSE frame's timing); reusing
+   * that one seam here — instead of also inspecting `message.updated`'s `info.error` — keeps
+   * OpenCode's turn-outcome detection in exactly one place, as the standing one-seam rule in this
+   * repo's CLAUDE.md requires.
+   *
+   * Retry/re-roll runs entirely inside this loop (bounded: `OPENCODE_ERROR_RETRY_MAX_ATTEMPTS`
+   * retries per session, one session re-roll) so `deliverInitialPrompt`/`deliver` see one turn
+   * outcome regardless of how many attempts it took — matching this endpoint's existing contract
+   * of "does not return until the turn is over".
+   */
+  /**
+   * @returns `"ok"` when the turn ended in output (or a positively-parsed empty completion that
+   * is not itself a failure — #2389's normal empty-turn path), `"failed"` only when `failTurn` was
+   * called — i.e. the message provoked a terminal, unrecoverable failure — and `"held"` (#2619)
+   * when the provider refused the turn and it ended in the rate-limit hold: not delivered, not
+   * failed. #2397 round 3 (MED-3): the caller uses this to decide whether the message may be
+   * marked delivered/read.
+   *
+   * #2397 round 5 review (INFO) — this method is non-reentrant BY CONSTRUCTION, and the
+   * `suppressProviderIdle`/`turnInFlight`/`turnClosed`/`turnAbandoned` instance fields it owns
+   * assume that: every `adapter.deliver`/`deliverInitialPrompt` call site in runner-core runs inside
+   * `providerInput.run`, which serializes them, so a second `send()` call never starts before the
+   * previous one's promise has settled. If that ever changed, these fields would need to become
+   * per-call state instead of per-adapter-instance state.
+   */
+  private async send(process: ManagedProcess, text: string, inputObserver?: ProviderInputObserver): Promise<OpenCodeSendOutcome> {
+    await this.apiBudgets.get(process)?.prepare();
+    // #2539 Phase B — retain the live process for the soft-steer wake hook (see its doc).
+    this.softSteerProcess = process;
+    let attempt = 0;
+    let rerolled = false;
+    let lastFailureDetail: string | undefined;
+    let lastFailureErrorType: string | undefined;
+    // #2397 round 4 review (F1/F2) — round 3 only raised this flag on a failed, retryable attempt,
+    // so it stayed false while ATTEMPT 1's own POST was in flight. On a fast (e.g. loopback) server
+    // the FAILED-attempt idle SSE frame routinely beats that attempt's own POST response — the
+    // issue's own captured incident shape, a 429 on the very first attempt — so an unsuppressed
+    // attempt-1 idle still closed the turn early and, via runner-core's #2389 seam, marked the
+    // linked Task done while the retry loop was still running. Raised for the WHOLE call (below,
+    // past the readiness guard — round 5 LOW-2) so there is no "attempt 1 is unguarded" window.
+    // Every return path must therefore close the turn itself — `closeSuppressedTurn` does that,
+    // idempotently per call (`turnClosed`) — see the `finally`.
+    // #2459 — close a still-open event-driven terminal turn BEFORE the reset below: a chat
+    // delivery taking over the boundary must end the terminal turn first (its own SSE idle, if
+    // it even arrived, would be swallowed under this call's suppression), and closeEventTurn
+    // sets `turnClosed` — resetting it after the close keeps THIS call's deterministic close
+    // live. Order: terminal idle clears the terminal turn id, then this call's busy mints its own.
+    if (this.eventTurnId) this.closeEventTurn();
+    // #2459 round 1 (review D) — a chat delivery also consumes any armed terminal prompt: a
+    // stale arm surviving this call would wrongly admit this call's own buffered busy echo
+    // after the close. (This call's POST user echo is recorded in seenUserMessageIds live, so
+    // its late duplicate can never re-arm — see the message.updated door.)
+    this.pendingTerminalPrompt = false;
+    // #2459 round 2 (review D) — a buffered terminal prompt flushed under the session
+    // pseudo-turn BEFORE the delivery takes over: the operator typed first, and the buffer
+    // must never leak across the headless turn boundary. Fallback id is the session
+    // pseudo-turn — never this call's (or any prior headless) sendTurnId.
+    this.flushBufferedPrompt(stringValue(process.meta?.sessionId) || undefined);
+    this.turnClosed = false;
+    // #2425 — reset at the top of every call: a stray leftover event from a truly-abandoned
+    // PREVIOUS turn must not be allowed to affect THIS new call's turn boundary (see the field
+    // comment).
+    this.turnAbandoned = false;
+    this.serverRetryWall = undefined;
+    // #2413 review (HIGH-1) — one fresh turn id per send() (stable across this call's retries/
+    // rerolls, which are ONE logical turn), so every send is distinct and the busy edge below hands
+    // runner-core this exact id as its currentTurnId.
+    this.sendTurnId = `opencode-turn-${crypto.randomUUID()}`;
+    try {
+      for (const relayContextInput = prepareOpenCodeRelayContext(process, text);;) {
+        const client = process.meta?.client as OpenCodeClient | undefined;
+        const sessionId = stringValue(process.meta?.sessionId);
+        const model = stringValue(process.meta?.model) ?? openCodeQualifiedModel(undefined, this.provider);
+        if (!client || !sessionId) throw new Error("OpenCode session is not ready");
+        // #2397 round 5 review (LOW-2) — raised only once we're actually about to run an attempt
+        // (past the guard above), so a "session not ready" throw never emits a close for a turn
+        // that never started (never emitted its own busy edge below).
+        this.turnInFlight = true;
+        this.suppressProviderIdle = true;
+        // #2459 round 1 (review D) — a headless turn now exists on this process: from here on,
+        // terminal-origin busies are admitted only through the armed fresh-prompt gate.
+        this.headlessTurnSeen = true;
+        const providerState = attempt > 0 || rerolled
+          ? openCodeUpstreamRetryState({ attempt, rerolled, message: lastFailureDetail ?? "retrying", errorType: lastFailureErrorType })
+          : undefined;
+        this.statusCb({ status: "busy", reason: "provider-turn", ...(this.sendTurnId ? { id: this.sendTurnId } : {}), ...(providerState ? { providerState } : {}) });
+        // #2389 — this endpoint is synchronous: it returns the COMPLETED assistant message. That
+        // body is ground truth about whether the model produced anything, so it feeds the same
+        // evidence funnel the cross-provider ledger reads, rather than being discarded as it was
+        // during the incident. Only a positively-parsed non-empty completion counts; an
+        // unrecognised body says nothing.
+        // #2418/#2532 — compose once outside this retry loop, but the durable first-turn markers
+        // are consumed by PROOF OF ACCEPTANCE, not by this await's return: `sendOpenCodeRelayTurn`
+        // arms the SSE acceptance door before dispatch and reconciles against persisted session
+        // messages if the await itself fails, so an accepted-but-interrupted turn (e.g. the #2425
+        // whole-turn abort) still retains the consumed flags instead of re-prepending the briefing
+        // on every queued message. A readiness guard or rejected transport request has not reached
+        // the provider, so RunnerCore's retry must still include the briefing. Retryable resolved
+        // completions and the same-turn session re-roll reuse this exact immutable local input, so
+        // prefixes neither stack nor disappear mid-turn.
+        inputObserver?.offered(Date.now(), false);
+        let completion: OpenCodeCompletion;
+        try {
+          completion = await sendOpenCodeRelayTurn(client, process, sessionId, model, relayContextInput, (body) => this.sessionEventCb({ type: "narration", origin: "provider", diagnostic: true, body }));
+        } catch (error) {
+          if (this.holdOnServerRetryWall()) return "held";
+          throw error;
+        }
+        if (this.holdOnServerRetryWall()) return "held";
+        // #2355 — every completion (success, a produced-output error, or a still-retrying error)
+        // carries this turn's fresh token usage; report it to Relay's normal context telemetry path
+        // the same way Codex's `codexTokenUsageContext` does, rather than only on the happy path.
+        this.reportContextUsage(process, model, completion.tokens);
+        // MessageAbortedError is the intended outcome of an interrupt() (session.abort) WE issued
+        // (or the operator issued) — not a provider failure. Fall through to the ordinary
+        // empty/non-empty handling below rather than retrying or failing an intentional cancel.
+        if (completion.error && completion.error.name !== "MessageAbortedError") {
+          const error = completion.error;
+          const detail = `${error.name}${error.statusCode !== undefined ? ` ${error.statusCode}` : ""}: ${error.message}`;
+          // #2397 round 2 (F1/F2) — `completion.error` used to be checked independently of any
+          // output the turn already produced. A turn that ran tool steps (a commit, say) and THEN
+          // hit a retryable error was resent into a brand-new session with no memory of that work
+          // — re-executing it. And a non-retryable error on a turn that DID produce a reply (e.g.
+          // MessageOutputLengthError after a long, otherwise-successful answer) took a healthy
+          // agent offline. Retrying or failing must only ever happen when the turn produced
+          // NOTHING; with output present, report the error and let the turn end normally.
+          // #2397 round 3 (HIGH-1) — `completionProducedOutput` excludes bare step-start/finish
+          // bookkeeping parts. The issue's own captured incident (one bare step-start part, zero
+          // tokens, a 429) used to satisfy the old parts>0 check and take THIS branch — no retry,
+          // no error status, reported as a clean success. It must fall through to the retry path.
+          const producedOutput = completionProducedOutput(completion);
+          if (producedOutput) {
+            this.sessionEventCb({ type: "narration", origin: "provider", body: `OpenCode reported ${detail} after the turn had already produced output; not retrying — reporting the output instead.` });
+            this.clearUpstreamRetryState(attempt, rerolled);
+            this.emitTurnFinalResponse(process, completion);
+            this.closeSuppressedTurn();
+            this.turnActivityCb();
+            this.rerolledThisHoldEpisode = false; // #2619 — the provider took a turn: the hold episode is over
+            return "ok";
+          }
+          // #2619 — an explicit account usage/quota wall: in-session retries and a re-roll cannot
+          // clear it (the re-roll would only drop the conversation). Hold now on the same session;
+          // the relay resumes us. Checked BEFORE the non-retryable exit: a provider may send a
+          // quota wall as a non-retryable 403 ("Quota exceeded; limit will reset tomorrow").
+          if (isProviderUsageLimit(error)) {
+            this.holdTurnOnProviderLimit(error, detail);
+            return "held";
+          }
+          // #2619 — throttle wording is retryable whatever the provider flagged (zai sends a
+          // non-retryable 403 "Rate limit exceeded"): retry, then hold like any throttle. A real
+          // auth/model refusal still fails here.
+          if (!error.isRetryable && !isProviderThrottle(error)) {
+            this.failTurn(detail, openCodeTerminalFailureReason(error));
+            return "failed";
+          }
+          if (attempt < OPENCODE_ERROR_RETRY_MAX_ATTEMPTS) {
+            attempt += 1;
+            const delayMs = openCodeErrorRetryDelayMs(attempt);
+            lastFailureDetail = detail;
+            lastFailureErrorType = error.errorType;
+            // #2397 round 3 (MED-5) — `diagnostic: true`: this narrates the ADAPTER's own retry
+            // mechanics, not anything the model produced. Left uncredited it would let
+            // emptyTurns.noteOutput() (runner-core's onSessionEvent wiring) read a retry storm
+            // that ultimately fails as forward progress, cancelling #2389's input-armed escalation
+            // that is the only thing left to wake the spawn parent once failTurn takes the agent
+            // offline below.
+            this.sessionEventCb({ type: "narration", origin: "provider", diagnostic: true, body: `OpenCode turn failed (${detail}); retrying in ${Math.round(delayMs / 1000)}s (attempt ${attempt}/${OPENCODE_ERROR_RETRY_MAX_ATTEMPTS})…` });
+            // suppressProviderIdle is already raised for the whole call (see entry) — nothing to
+            // set here; this attempt's own leaked idle is suppressed same as attempt 1's.
+            await this.sleepImpl(delayMs);
+            continue;
+          }
+          // #2619 — a provider overload (5xx) is provider-wide, not a broken session: a re-roll
+          // would only drop the history before the same wall. Hold on the SAME session.
+          if (isProviderOverload(error)) {
+            this.holdTurnOnProviderLimit(error, `${detail} (after ${OPENCODE_ERROR_RETRY_MAX_ATTEMPTS} in-session retries)`);
+            return "held";
+          }
+          // Retry exhausted for the CURRENT session. Bimodal-per-session evidence (#2397 issue
+          // comment) says an ambiguous 429 can be a per-session failure — re-roll to a fresh one
+          // once. #2619 — at most ONCE PER HOLD EPISODE (until a turn goes through again), so a
+          // long wall re-rolls once and then holds: history loss stays bounded to one attempt.
+          if (!rerolled && !this.rerolledThisHoldEpisode) {
+            this.rerolledThisHoldEpisode = true;
+            // #2397 round 2 (F5) — say plainly that this drops the conversation: re-rolling
+            // mutates process.meta.sessionId to a brand-new, history-less session, which for a
+            // long-lived agent throws away everything said so far.
+            this.sessionEventCb({ type: "narration", origin: "provider", diagnostic: true, body: `OpenCode turn failed ${OPENCODE_ERROR_RETRY_MAX_ATTEMPTS} times in a row in this session (${detail}); re-rolling to a new OpenCode session (this drops the current conversation history) and retrying…` });
+            let newSessionId: string;
+            try {
+              newSessionId = await client.createSession(stringValue(process.meta?.sessionTitle) ?? "agent-relay");
+            } catch (createError) {
+              // #2619 — the original session is still intact; a failed re-roll during a
+              // provider outage is no reason to end the agent. Hold like the exhausted path.
+              this.holdTurnOnProviderLimit(error, `${detail} (session re-roll failed: ${errMessage(createError)})`);
+              return "held";
+            }
+            // Every other reader of the session id (send/interrupt/shutdown) goes through
+            // process.meta.sessionId, so mutating it in place re-routes the whole adapter to the
+            // new session — no separate "which session is active" bookkeeping needed.
+            if (process.meta) process.meta.sessionId = newSessionId;
+            // #2539 Phase B — soft-steer fencing on re-roll: same contract as the clear swap —
+            // accepted-but-unconsumed batches on the dead session reoffer to the normal queue
+            // (the settlement callback fires inside sessionReplaced).
+            const softSteerOrphans = await this.softSteer.sessionReplaced(newSessionId);
+            if (softSteerOrphans.length > 0) {
+              logger.info("opencode", `soft-steer: reoffering ${softSteerOrphans.length} relay id(s) after the retry budget re-rolled the session`);
+            }
+            rerolled = true;
+            attempt = 0;
+            lastFailureDetail = detail;
+            lastFailureErrorType = error.errorType;
+            // suppressProviderIdle is already raised for the whole call — see entry.
+            continue;
+          }
+          // #2619 — retries and the re-roll are exhausted on a RETRYABLE error: the provider is
+          // down or throttling, not the agent. This used to failTurn → terminal `error` → runner
+          // exit, killing every zai session ~10 min into a quota wall. Hold and let the relay's
+          // resume sweep back off and wake the agent, as it does for Claude.
+          this.holdTurnOnProviderLimit(error, `${detail} (after ${OPENCODE_ERROR_RETRY_MAX_ATTEMPTS} retries and a session re-roll)`);
+          return "held";
+        }
+        if (!completion.empty && completionProducedOutput(completion)) {
+          this.clearUpstreamRetryState(attempt, rerolled);
+          this.emitTurnFinalResponse(process, completion);
+          this.closeSuppressedTurn();
+          this.turnActivityCb();
+          this.rerolledThisHoldEpisode = false; // #2619 — the provider took a turn: the hold episode is over
+          return "ok";
+        }
+        // Either a non-empty completion with no positively-parsable output (an unrecognised body —
+        // says nothing either way), or a POSITIVELY parsed empty completion (#2389's normal
+        // empty-turn path, closed deterministically here rather than depending on a possibly late
+        // or lost SSE idle frame). Either way this POST returning is itself proof the turn is over
+        // — the endpoint is synchronous — so let the shared `finally` below perform the close
+        // instead of duplicating it at two near-identical return sites. #2397 round 4 review (F3):
+        // that exact duplication was unadjudicated — deleting either explicit call left every
+        // opencode test green, since `finally` already produces the identical close with no
+        // observable ordering difference from here (nothing else runs between this `return` and
+        // the `finally`).
+        this.rerolledThisHoldEpisode = false; // #2619 — the provider took a turn: the hold episode is over
+        return "ok";
+      }
+    } finally {
+      // #2397 round 4/5 review (F2) — the single deterministic close for this whole call. Some
+      // return paths above call `closeSuppressedTurn()` explicitly first (when something else in
+      // that branch — `turnActivityCb`, most notably — must run AFTER the close, so ordering
+      // matters); the rest fall straight through to here, since nothing runs between their
+      // `return` and this `finally` and an explicit call there would be a pure no-op duplicate
+      // (see F3 above). `failTurn`'s own unconditional close also marks `turnClosed`, so by the
+      // time ANY return path reaches here this is a no-op — EXCEPT when NONE of those ran: a throw
+      // from `client.sendMessage` (transport reset, socket drop) or the "session not ready" guard.
+      // #2397 round 6 review (MED-2r) — that guard throw must NOT fall through to
+      // `closeSuppressedTurn()`. The old comment here claimed `suppressProviderIdle` "was also
+      // never raised this call, so closeSuppressedTurn is a no-op there too" — true only on the
+      // FIRST call. `suppressProviderIdle` is STICKY (round 5, MED-1): on any later call, if the
+      // prior call's own trailing idle has not yet arrived to lower it back to false, it is still
+      // true when this guard throws — so the old code emitted a phantom `idle + clear` for a turn
+      // that never started, never emitted a busy, never reached the provider (verified: cold = 0
+      // closes, warm = 1). Gate on whether THIS call ever actually started an attempt
+      // (`turnInFlight` was raised past the guard), captured before resetting it below, instead of
+      // on the sticky flag. Before F2 (unrelated to this gate) that left `suppressProviderIdle`
+      // raised forever with no further idle to lower it — `currentTurnId` never cleared, the
+      // provider-turn claim stuck busy, queued mail never draining.
+      const turnStartedThisCall = this.turnInFlight;
+      this.turnInFlight = false;
+      // Closing here (when `turnStartedThisCall` is true — a genuine mid-attempt throw) trades a
+      // turn the server might still be running for a turn that reliably ends; the adapter has no
+      // other signal on a throw, and `failTurn` already makes that same trade unconditionally today.
+      // #2425 — `turnClosed` still being false at this point means NEITHER a success branch nor
+      // `failTurn` ran before we got here — the only way in is an uncaught throw (e.g. `sendMessage`
+      // aborting on the #2425 turn-timeout, or any other transport failure) whose actual server-side
+      // outcome is unknown. Mark the turn abandoned before force-closing it, so a genuine same-
+      // session busy/idle that arrives later can still self-heal the status instead of being
+      // swallowed forever by the otherwise-permanent `suppressProviderIdle` (see its field doc).
+      if (turnStartedThisCall) {
+        if (!this.turnClosed) this.turnAbandoned = true;
+        this.closeSuppressedTurn();
+      }
+    }
+  }
+
+  /**
+   * #2355 — the runner's `latestProcessContext()` (runner-core.ts) reads `process.meta.context`
+   * directly (the same fallback path Codex's `meta.context` sets from `thread/tokenUsage/updated`),
+   * feeding Relay's normal telemetry (dashboard/API/timeline) and the context-pressure warning /
+   * self-compaction advisory. A no-op whenever the turn carried no parsable token count or the
+   * model's window is unknown — silence here, not a fabricated 0/0 reading.
+   */
+  private reportContextUsage(process: ManagedProcess, model: string | undefined, tokensUsed: number | undefined): void {
+    // #2599 — precedence payload-record > legacy #2595 window > manifest. The record's qualified
+    // name is ALSO threaded through: meta.model is re-pinned to the server-computed qualified name
+    // when the record is present, so later reportContextUsage calls (which read meta.model) keep
+    // resolving against the payload instead of re-deriving from a possibly-ambiguous alias.
+    const config = process.meta?.config as RunnerSpawnConfig | undefined;
+    const record = openCodeModelRecord(config?.modelRecord, this.provider);
+    // #2659 — the configured window belongs to the LAUNCH model, not a terminal-switched one.
+    const configWindow = openCodeOnLaunchModel(process.meta, model) ? record?.contextWindowTokens ?? config?.contextWindowTokens : undefined;
+    const windowTokens = typeof configWindow === "number" && Number.isFinite(configWindow) && configWindow > 0
+      ? configWindow
+      : openCodeContextWindowTokens(model, this.provider);
+    const context = openCodeContextState({ tokensUsed, windowTokens });
+    if (context && process.meta) process.meta.context = context;
+  }
+
+  /**
+   * #2397 round 2 (F6) — once a retry (or the post-reroll retry) actually produces output, the
+   * operator-visible "retrying…"/blocked hold must not linger on screen until whatever SSE idle
+   * happens to arrive next — which `suppressProviderIdle` above can delay well past this turn.
+   * Clear it explicitly and immediately; a no-op when no retry hold was ever shown.
+   */
+  private clearUpstreamRetryState(attempt: number, rerolled: boolean): void {
+    if (attempt === 0 && !rerolled) return;
+    this.statusCb({
+      status: "busy",
+      reason: "provider-turn",
+      providerState: { state: "active", reason: "provider-error-recovered", label: "OpenCode recovered after a provider error", source: "opencode", updatedAt: Date.now() },
+    });
+  }
+
+  /**
+   * #2397 round 4/5 review (F1/F2/MED-1) — `suppressProviderIdle` is raised for the WHOLE `send()`
+   * call, from just past the readiness guard (see the loop entry), so every path that ends the
+   * turn — success, either failure, or the `finally`'s throw fallback — must close it
+   * deterministically itself; the synchronous POST returning (or the throw itself) is ground truth
+   * either way. `turnClosed` (NOT `suppressProviderIdle`) is the idempotency guard: it stops the
+   * SAME call's multiple close sites — an explicit branch call plus the `finally` fallback — from
+   * emitting a second idle for one call. `suppressProviderIdle` itself deliberately stays raised
+   * once this fires (round 5, MED-1): a healthy turn's own trailing real SSE idle can still arrive
+   * AFTER this close, and stays swallowed unless a genuine terminal turn or an abandoned turn
+   * admits its own events — see the field comments.
+   */
+  private closeSuppressedTurn(hold?: ProviderState): void {
+    if (this.turnClosed) return;
+    this.turnClosed = true;
+    // #2484 round 1 review (F2/F3) — turn close: flush the debounced token-usage report now
+    // rather than wait out its timer. Not awaited — a live turn boundary, not teardown; flush()
+    // already routes failures to reporter.reportFailure internally, so the `.catch(() => {})`
+    // here only satisfies the unguarded-async ratchet (#1665) — it never actually fires.
+    void this.tokenUsagePoster.flushAll().catch(() => {});
+    this.statusCb({ status: "idle", reason: "provider-turn", clear: ["provider-turn"], ...(hold ? { providerState: hold } : {}) });
+    // #2539 Phase B — idle edge with unconsumed soft batches: arm the one bounded wake. Never
+    // into a provider-limit hold: the wake would only hit the same wall; the relay's resume turn
+    // ends in a normal idle that arms it then.
+    if (!hold) this.maybeArmSoftSteerWake();
+  }
+
+  /**
+   * #2619 — end the turn in the shared rate-limit hold instead of a terminal failure: the turn
+   * closes (idle + provider-turn) carrying the `blocked/rate_limit` providerState, which
+   * runner-core keeps as its rateLimitHold until the relay's resume turn goes busy. The session
+   * (and its history, including the refused user message) stays alive.
+   */
+  private holdTurnOnProviderLimit(error: OpenCodeAssistantError, detail: string, resetAt?: number): void {
+    const hold = buildProviderRefusalHold({ ...error, detail, source: "opencode", ...(resetAt ? { resetAt } : {}) });
+    this.sessionEventCb({ type: "narration", origin: "provider", diagnostic: true, body: `OpenCode provider refused the turn (${detail}); holding the session — Humwick resumes it ${hold.kind === "usage_limit" ? "when the usage window resets" : "with bounded backoff"}.` });
+    this.closeSuppressedTurn(hold);
+  }
+
+  /**
+   * #2775 — OpenCode's own retry of an in-flight send(): a transient one is shown as "retrying"; a wall
+   * (usage/free-tier limit, far-off `next`, or an endless throttle) aborts the session so the POST
+   * returns and send() ends the turn in the shared rate-limit hold instead of waiting silently.
+   */
+  private onServerRetry(retry: OpenCodeServerRetry | undefined, process?: ManagedProcess): void {
+    if (!retry || !this.turnInFlight || this.serverRetryWall) return;
+    if (!isOpenCodeServerRetryWall(retry)) {
+      this.statusCb({ status: "busy", reason: "provider-turn", ...(this.sendTurnId ? { id: this.sendTurnId } : {}), providerState: openCodeServerRetryState(retry) });
+      return;
+    }
+    this.serverRetryWall = retry;
+    const client = process?.meta?.client as OpenCodeClient | undefined;
+    const sessionId = stringValue(process?.meta?.sessionId);
+    if (client && sessionId) void fireAndForget(`opencode abort on provider wall (session ${sessionId})`, () => client.abort(sessionId), (message) => logger.error("opencode", message));
+  }
+
+  private holdOnServerRetryWall(): boolean {
+    const wall = this.serverRetryWall;
+    if (!wall) return false;
+    this.serverRetryWall = undefined;
+    const error: OpenCodeAssistantError = { name: "OpenCodeRetry", message: wall.message, ...(wall.reason ? { errorType: wall.reason } : {}), isRetryable: true };
+    this.holdTurnOnProviderLimit(error, `${wall.message} (OpenCode retry attempt ${wall.attempt}${wall.reason ? `, ${wall.reason}` : ""})`, wall.next);
+    return true;
+  }
+
+  /**
+   * #2459 — close the event-driven (terminal-origin) turn on its matching SSE idle: emit the
+   * turn-final response accumulated from the turn's finalized assistant text parts (the same
+   * narration→final-response shape send()'s POST path produces, and the same turnId so the
+   * dashboard's per-turn narration/response dedup applies), then the idle edge that closes
+   * runner-core's turn. Completes the #2425 abandonment self-heal (the server's own truth for
+   * the abandoned turn has now arrived). Deliberately does NOT re-raise the sticky idle
+   * suppression or stamp the echo window: an event turn's busy+idle arrive LIVE — they DRIVE
+   * this state machine; there is no send()-POST await whose buffered chunk could replay them —
+   * so there is no trailing-echo shape to guard against, and a genuine follow-up terminal turn
+   * must be able to open immediately.
+   */
+  private closeEventTurn(): void {
+    const turnId = this.eventTurnId;
+    const text = this.eventTurnText.join("\n\n").trim();
+    // #2605 — reconcile the turn's reasoning parts against what the live door already emitted,
+    // per part id: a part whose latest snapshot EQUALS its last-emitted body needs no row (it is
+    // already traced); a part that GREW after its last live emit — or was never live-emitted
+    // (frames racing the close, a part observed only at close time) — gets one row under its OWN
+    // part id, so the server upserts rather than duplicates. Comparison is scoped to THIS turn's
+    // part ids (eventTurnReasoning) against their own ledger entries — never to a global body
+    // pool — so an identical body in a later turn is never misread as already-seen. Each entry
+    // is already the newest full snapshot for its part, so there is nothing to prefix-merge.
+    const unseen: OpenCodeReasoningStep[] = [];
+    for (const [stepId, body] of this.eventTurnReasoning) {
+      const trimmed = body.trim();
+      if (!trimmed) continue;
+      if (this.emittedReasoningParts.get(stepId) === trimmed) continue;
+      unseen.push({ stepId, body: trimmed });
+    }
+    this.eventTurnId = undefined;
+    this.eventTurnText = [];
+    this.eventTurnReasoning = new Map();
+    // Stray idles with no open event turn stay swallowed via the existing `turnClosed` guard.
+    this.turnClosed = true;
+    // #2425 self-heal completion: this idle close was the server's own truth for the abandoned
+    // turn. Round 1 (review D) — re-latch the sticky suppression it had bypassed (the #2425
+    // escape hatch exists only while the abandonment is unresolved), so post-heal strays stay
+    // swallowed under the same permanent suppression as every other send()-closed turn.
+    if (this.turnAbandoned) {
+      this.turnAbandoned = false;
+      this.suppressProviderIdle = true;
+    }
+    if (turnId) {
+      for (const step of unseen) this.emitReasoningFinal(openCodeReasoningSessionEvent(step, turnId, false));
+      for (const event of openCodeTurnFinalEvents({ text }, turnId)) this.sessionEventCb(event);
+    }
+    // #2484 round 1 review (F2/F3) — same flush as closeSuppressedTurn's turn close; the
+    // `.catch(() => {})` is the same ratchet-only no-op (flush() already self-catches).
+    void this.tokenUsagePoster.flushAll().catch(() => {});
+    this.statusCb({ status: "idle", reason: "provider-turn", clear: ["provider-turn"] });
+    // #2539 Phase B — a terminal-origin turn's close is an idle edge too: unconsumed soft
+    // batches get the same single bounded wake.
+    this.maybeArmSoftSteerWake();
+  }
+
+  /**
+   * #2459 round 2 (review D) — emit a buffered terminal prompt under `turnId` and clear the
+   * slot. `turnId` is the freshly minted terminal turn id (primary path — busy admission) or
+   * the session pseudo-turn (bounded no-busy fallbacks); it is NEVER a stale headless
+   * sendTurnId, which only exists while send() is in flight and is never passed here.
+   */
+  private flushBufferedPrompt(turnId: string | undefined): void {
+    const buffered = this.bufferedTerminalPrompt;
+    if (!buffered) return;
+    this.bufferedTerminalPrompt = undefined;
+    this.sessionEventCb({ type: "prompt", origin: "terminal", body: buffered.body, occurredAt: buffered.occurredAt, ...(turnId ? { turnId } : {}) });
+  }
+
+  /**
+   * #2459 — the turn id live session events should attach to: send()'s per-call id while a
+   * headless delivery is in flight, otherwise the event-driven terminal turn minted on the
+   * server's own busy edge. Deliberately NO fallback to a stale `sendTurnId` outside send() —
+   * that inheritance is exactly the contamination this replaces; callers fall back to the
+   * session pseudo-turn instead.
+   */
+  private activeTurnId(): string | undefined {
+    return this.turnInFlight ? this.sendTurnId : this.eventTurnId;
+  }
+
+  private failTurn(detail: string, terminalFailureReason: string): void {
+    // #2397 round 3 (MED-5) — diagnostic:true; see the retry-loop narration above for why.
+    this.sessionEventCb({ type: "narration", origin: "provider", diagnostic: true, body: `OpenCode turn failed: ${detail}` });
+    // #2397 round 2 (F3) — an "error" status alone is never treated as a turn boundary by
+    // #2389's seam in runner-core (only `idle && provider-turn` clears `currentTurnId` and notes
+    // the turn ended); without this, the next `busy` reuses the stale turn id and the empty-turn
+    // detector is blinded for the rest of the agent's life. Close the turn through that same seam
+    // first — exactly as the parsed-empty-completion path above already does — before marking the
+    // terminal failure. This close is unconditional (fires whether or not suppressProviderIdle was
+    // raised), so mark `turnClosed` here too — otherwise `send()`'s `finally` fallback would see it
+    // still unset and emit a second, out-of-order idle after the error status below.
+    this.turnClosed = true;
+    // #2484 round 1 review (F2/F3) — same flush as the other turn-close sites: a failed turn can
+    // still carry real (partial) usage worth persisting; the `.catch(() => {})` is the same
+    // ratchet-only no-op as the other two sites.
+    void this.tokenUsagePoster.flushAll().catch(() => {});
+    this.statusCb({ status: "idle", reason: "provider-turn", clear: ["provider-turn"] });
+    this.statusCb({
+      status: "error",
+      reason: "provider-turn",
+      clear: ["provider-turn"],
+      // #2443 — mirrors the Claude adapter's own "model-unavailable" stop-failure shape
+      // (providerState + an embedded timeline event) instead of leaving this error silent beyond
+      // the mirror log: a terminal failure used to reach runner-core with no timeline event and no
+      // classification, so an exit driven by this status surfaced nothing to the operator beyond
+      // "exited after Ns". `terminal: true` marks it as needing operator attention, same as Claude's.
+      providerState: { state: "failed", reason: terminalFailureReason, message: detail, source: "opencode-turn-failure", terminal: true },
+      metadata: { terminalFailureReason, terminalFailureMessage: detail },
+      timeline: {
+        status: "provider.restart_decision",
+        title: terminalFailureReason === "model-unavailable" ? "OpenCode model unavailable" : "OpenCode turn failed",
+        body: detail,
+        metadata: { eventType: "provider.restart_decision", decision: "stop-surface", reason: terminalFailureReason },
+      },
+    });
+  }
+}