charness 3.2.0 → 3.3.0

package/dist/adapters/openCodeAdapter.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OpenCodeAdapter = exports.schedulerMcpRetryDelaysMs = exports.openCodeErrorMessageMaxLength = exports.providerRetryReplacementStartTimeoutMs = exports.criticalSseEventTypes = exports.openCodeRuntimeContextHydrationConcurrency = void 0;
+exports.OpenCodeAdapter = exports.openCodeServerRestartRetryBudgetMs = exports.openCodeServerRestartRetryDelaysMs = exports.schedulerMcpRetryDelaysMs = exports.openCodeErrorMessageMaxLength = exports.providerRetryReplacementStartTimeoutMs = exports.criticalSseEventTypes = exports.openCodeRuntimeContextHydrationConcurrency = void 0;
 exports.listSavedOpenCodeModelLabels = listSavedOpenCodeModelLabels;
 exports.normaliseOpenCodeSseEvent = normaliseOpenCodeSseEvent;
 exports.buildDirectoryScopedPath = buildDirectoryScopedPath;
@@ -45,6 +45,8 @@ exports.checkIsOpenCodeTurnInFlight = checkIsOpenCodeTurnInFlight;
 exports.summarizeProviderRetryReason = summarizeProviderRetryReason;
 exports.checkIsOpenCodeAbortError = checkIsOpenCodeAbortError;
 exports.getOpenCodeErrorMessage = getOpenCodeErrorMessage;
+exports.getOpenCodeErrorLogText = getOpenCodeErrorLogText;
+exports.getOpenCodeErrorRetryAfterAt = getOpenCodeErrorRetryAfterAt;
 exports.checkIsOpenCodeSessionBusy = checkIsOpenCodeSessionBusy;
 exports.applyOpenCodeStatusEvent = applyOpenCodeStatusEvent;
 exports.buildPromptBody = buildPromptBody;
@@ -53,6 +55,7 @@ exports.getLatestOpenCodeParentAssistantContext = getLatestOpenCodeParentAssista
 exports.buildProviderAuthPath = buildProviderAuthPath;
 exports.checkNeedsSchedulerMcpReregister = checkNeedsSchedulerMcpReregister;
 exports.getSchedulerMcpRetryDelayMs = getSchedulerMcpRetryDelayMs;
+exports.getOpenCodeServerRestartRetryDelayMs = getOpenCodeServerRestartRetryDelayMs;
 exports.buildProviderApiAuthPayload = buildProviderApiAuthPayload;
 exports.resetOpenCodeProviderCaches = resetOpenCodeProviderCaches;
 exports.parseProvidersResponse = parseProvidersResponse;
@@ -66,6 +69,8 @@ const apiErrorRetry_1 = require("../apiErrorRetry");
 const installManager_1 = require("../installManager");
 const state_1 = require("../state");
 const diagLog_1 = require("../diagLog");
+const utils_1 = require("../utils");
+const backendUnavailableError_1 = require("./backendUnavailableError");
 const openCodeSessionRouting_1 = require("../openCodeSessionRouting");
 const i18n_1 = require("../i18n");
 const resumeContext_1 = require("../resumeContext");
@@ -574,6 +579,8 @@ function checkIsOpenCodeAbortError(errorMsg) {
     return errorMsg.trim().toLowerCase() === 'aborted';
 }
 const genericOpenCodeErrorMessage = 'OpenCode request failed';
+/** The two channels OpenCode reports a turn's failure on, and the line each one posts. */
+const openCodeFailurePrefixes = { 'session.error': 'OpenCode error: ', 'message.error': 'Error: ' };
 /** Placeholder written over every redacted credential. */
 const openCodeErrorRedactedMarker = '[redacted]';
 /**
@@ -614,18 +621,45 @@ const openCodeErrorCredentialValueRe = /\bsk-[A-Za-z0-9_-]+|\bghp_[A-Za-z0-9]+|\
  * required: a bare `https://<token>@host` is just as much a credential.
  */
 const openCodeErrorUrlUserInfoRe = /(\w+:\/\/)[^\s/@]+@/g;
-/**
- * @description Redact the credentials a surfaced error string is known to carry
- * and cap it. Redaction runs BEFORE the cap: capping first could cut a secret
- * assignment in half and leave the head of the credential visible.
- */
-function redactOpenCodeErrorMessage(message) {
+/** @description Redact the credentials an error string is known to carry (see the rules above). */
+function redactOpenCodeErrorCredentials(message) {
     return message
         .replace(openCodeErrorSecretAssignmentRe, `$1$2${openCodeErrorRedactedMarker}`)
         .replace(openCodeErrorAuthSchemeRe, `$1 ${openCodeErrorRedactedMarker}`)
         .replace(openCodeErrorCredentialValueRe, openCodeErrorRedactedMarker)
-        .replace(openCodeErrorUrlUserInfoRe, `$1${openCodeErrorRedactedMarker}@`)
-        .slice(0, exports.openCodeErrorMessageMaxLength);
+        .replace(openCodeErrorUrlUserInfoRe, `$1${openCodeErrorRedactedMarker}@`);
+}
+/**
+ * The start of the diagnostics block an auth plugin appends to every provider error it relays
+ * (opencode-antigravity-auth: `\n\n[Debug Info]\nRequested Model: …\nProject: …\nEndpoint: …\nTool Debug Payload: …`): the
+ * user's Google project id and part of the tool schema — nothing the person in the topic can act on, and it pushed the
+ * provider's own reason out of the capped line. Cut before the text is surfaced; the bot log keeps it
+ * ({@link getOpenCodeErrorLogText}).
+ */
+const openCodePluginDiagnosticsMarker = '\n\n[Debug Info]';
+/**
+ * @description The surfaced form of an error string: the plugin diagnostics cut ({@link openCodePluginDiagnosticsMarker}),
+ * the credentials redacted, the length capped. Redaction runs BEFORE the cap: capping first could cut a secret
+ * assignment in half and leave the head of the credential visible.
+ */
+function redactOpenCodeErrorMessage(message) {
+    const diagnosticsStart = message.indexOf(openCodePluginDiagnosticsMarker);
+    const reason = diagnosticsStart >= 0 ? message.slice(0, diagnosticsStart) : message;
+    return redactOpenCodeErrorCredentials(reason).slice(0, exports.openCodeErrorMessageMaxLength);
+}
+/** @description The message string of OpenCode's known error shapes (`{ data: { message } }`, `{ message }`, a string), else `null`. */
+function readOpenCodeErrorString(error) {
+    if (typeof error === 'string')
+        return error;
+    if (!error || typeof error !== 'object')
+        return null;
+    const errorRecord = error;
+    if (errorRecord.data && typeof errorRecord.data === 'object') {
+        const errorData = errorRecord.data;
+        if (typeof errorData.message === 'string')
+            return errorData.message;
+    }
+    return typeof errorRecord.message === 'string' ? errorRecord.message : null;
 }
 /**
  * @description Extract the readable, SAFE-TO-SURFACE error form from OpenCode's
@@ -638,19 +672,16 @@ function redactOpenCodeErrorMessage(message) {
  * The retry classifier reads {@link getOpenCodeErrorClassificationText} instead.
  */
 function getOpenCodeErrorMessage(error) {
-    if (typeof error === 'string')
-        return redactOpenCodeErrorMessage(error);
-    if (!error || typeof error !== 'object')
-        return genericOpenCodeErrorMessage;
-    const errorRecord = error;
-    if (errorRecord.data && typeof errorRecord.data === 'object') {
-        const errorData = errorRecord.data;
-        if (typeof errorData.message === 'string')
-            return redactOpenCodeErrorMessage(errorData.message);
-    }
-    if (typeof errorRecord.message === 'string')
-        return redactOpenCodeErrorMessage(errorRecord.message);
-    return genericOpenCodeErrorMessage;
+    const errorString = readOpenCodeErrorString(error);
+    return errorString === null ? genericOpenCodeErrorMessage : redactOpenCodeErrorMessage(errorString);
+}
+/**
+ * @description The bot-log form of an error: the whole message string, plugin diagnostics included, credentials
+ * redacted — what {@link getOpenCodeErrorMessage} cuts for the topic stays findable in the log.
+ */
+function getOpenCodeErrorLogText(error) {
+    const errorString = readOpenCodeErrorString(error);
+    return errorString === null ? genericOpenCodeErrorMessage : redactOpenCodeErrorCredentials(errorString);
 }
 /**
  * @description Serialise an error payload FOR CLASSIFICATION ONLY. The result
@@ -664,7 +695,10 @@ function getOpenCodeErrorMessage(error) {
  * shape to a constant, and the classifier reads text to decide whether an error
  * is an auto-retryable rate-limit / usage-limit. Feeding it that constant
  * silently cancelled the retry of a real rate limit, so the two paths are split:
- * the user gets the constant, the classifier gets the full payload.
+ * the user gets the constant, the classifier gets the payload's text. For
+ * OpenCode's own `{ name, data }` provider error that text is the message, the
+ * response body and the status code only — never its headers or metadata (see
+ * the inline note); an unrecognised shape is serialized whole.
  */
 function getOpenCodeErrorClassificationText(error) {
     if (typeof error === 'string')
@@ -673,6 +707,17 @@ function getOpenCodeErrorClassificationText(error) {
         return error.message;
     if (!error || typeof error !== 'object')
         return '';
+    const apiErrorData = getOpenCodeApiErrorData(error);
+    if (apiErrorData) {
+        // OpenCode's own shape: what the PROVIDER said — its message, its response body, the status code. Never the
+        // response headers or the metadata: they name limits and resets of their own (`x-…-limit-…`, a per-minute
+        // counter's `…-reset: <ISO>`), which read as a usage window that is not there.
+        return [
+            apiErrorData.message,
+            apiErrorData.responseBody,
+            typeof apiErrorData.statusCode === 'number' ? `HTTP ${apiErrorData.statusCode}` : undefined,
+        ].filter((part) => typeof part === 'string' && part !== '').join('\n');
+    }
     try {
         // A payload whose `toJSON` opts out yields undefined rather than text.
         const serialized = JSON.stringify(error);
@@ -683,6 +728,39 @@ function getOpenCodeErrorClassificationText(error) {
         return '';
     }
 }
+const msPerSecond = 1000;
+/** @description The `data` of an OpenCode `{ name, data: { message, … } }` error, or `null` for any other shape. */
+function getOpenCodeApiErrorData(error) {
+    const data = 'data' in error && error.data && typeof error.data === 'object' ? error.data : undefined;
+    return data && typeof data.message === 'string' ? data : null;
+}
+/**
+ * @description The reset a provider states as a FIELD: the `retry-after-ms` / `retry-after` response header of an
+ * OpenCode provider error (seconds, or an HTTP date), as epoch ms; `undefined` when there is none. The one header the
+ * bot reads — the others name limits and counters of their own.
+ */
+function getOpenCodeErrorRetryAfterAt(error, now) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const headers = getOpenCodeApiErrorData(error)?.responseHeaders;
+    if (!headers || typeof headers !== 'object')
+        return undefined;
+    const readHeader = (name) => {
+        const entry = Object.entries(headers).find(([headerName]) => headerName.toLowerCase() === name);
+        return typeof entry?.[1] === 'string' ? entry[1] : undefined;
+    };
+    const retryAfterMs = Number.parseFloat(readHeader('retry-after-ms') ?? '');
+    if (Number.isFinite(retryAfterMs))
+        return now + retryAfterMs;
+    const retryAfter = readHeader('retry-after');
+    if (retryAfter === undefined)
+        return undefined;
+    const retryAfterSeconds = Number.parseFloat(retryAfter);
+    if (Number.isFinite(retryAfterSeconds))
+        return now + retryAfterSeconds * msPerSecond;
+    const retryAfterDateMs = Date.parse(retryAfter);
+    return Number.isNaN(retryAfterDateMs) ? undefined : retryAfterDateMs;
+}
 /**
  * @description Sync "is this session occupied with a turn?" decision for the
  * scheduler's wait-for-idle loop ({@link AgentAdapter.checkIsBusy}): busy when
@@ -915,6 +993,39 @@ exports.schedulerMcpRetryDelaysMs = [15_000, 60_000, 5 * 60_000, 15 * 60_000];
 function getSchedulerMcpRetryDelayMs(attempt) {
     return exports.schedulerMcpRetryDelaysMs[attempt] ?? null;
 }
+/**
+ * Pauses before each retry of a failed attempt to bring the OpenCode server up
+ * (a restart, or a session start / resume that finds it down). An attempt can
+ * fail transiently — the binary missing (`spawn opencode ENOENT`), a server not
+ * ready in time on a loaded machine; one attempt used to tear every active
+ * session down and show the raw error.
+ */
+exports.openCodeServerRestartRetryDelaysMs = [2_000, 5_000, 10_000, 15_000, 20_000];
+/**
+ * The bound on the retries, counted from the first attempt: no retry is paused
+ * for once it would start past this. An attempt that waits out the server
+ * readiness probe takes ~15 s, so the bound — not the pause list — is what keeps
+ * a hopeless start from holding the topics for minutes.
+ */
+exports.openCodeServerRestartRetryBudgetMs = 60_000;
+/**
+ * @description The pause before retry number `retryIndex` (0-based), or
+ * `null` once the pauses are used up or the retry would start past `budgetMs`
+ * after the first attempt began (`elapsedMs` ago).
+ */
+function getOpenCodeServerRestartRetryDelayMs(retryIndex, elapsedMs, delaysMs = exports.openCodeServerRestartRetryDelaysMs, budgetMs = exports.openCodeServerRestartRetryBudgetMs) {
+    const delayMs = delaysMs[retryIndex];
+    if (delayMs === undefined || elapsedMs + delayMs > budgetMs)
+        return null;
+    return delayMs;
+}
+const defaultOpenCodeServerRestartOps = {
+    checkIsInstalled: () => (0, installManager_1.checkIsInstalled)('opencode'),
+    installTool: () => (0, installManager_1.installTool)('opencode'),
+    checkIsServerRunning: installManager_1.checkIsOpenCodeServerRunning,
+    ensureServer: installManager_1.ensureOpenCodeServer,
+    restartServer: installManager_1.restartOpenCodeServer,
+};
 function buildProviderApiAuthPayload(apiKey) {
     return { type: 'api', key: apiKey };
 }
@@ -930,6 +1041,17 @@ function resetOpenCodeProviderCaches() {
     cachedProviders = null;
     providersCacheTime = 0;
 }
+/**
+ * @description The variants the LAST providers snapshot lists for `model`, however old: a model's variants hardly
+ * change, and the synchronous effort display must not wait for a request. `[]` is a model the snapshot lists with
+ * no variants (KNOWN to have none); `null` is a model the display cannot judge — no model, no snapshot yet, or a
+ * model the snapshot does not list.
+ */
+function getKnownModelVariants(model) {
+    if (!model)
+        return null;
+    return cachedProviders?.providers.get(model.providerID)?.get(model.modelID)?.variants ?? null;
+}
 function getFreshProvidersConfig(now = Date.now()) {
     if (!cachedProviders || now - providersCacheTime >= providersCacheTtlMs)
         return null;
@@ -1129,8 +1251,20 @@ class OpenCodeAdapter extends events_1.EventEmitter {
     runtimeContextHydrationCount = 0;
     /** Callers waiting for one of the bounded runtime-context hydration slots. */
     runtimeContextHydrationWaiters = [];
-    /** Whether a server restart is already in progress (prevents concurrent restart attempts) */
-    isServerRestarting = false;
+    /**
+     * The server restart in progress, `null` when none: a second caller shares it
+     * instead of starting another, and a prompt sent meanwhile waits for it
+     * ({@link sendPromptAsync}) rather than posting to a server that is down.
+     */
+    serverRestart = null;
+    /**
+     * The installManager calls of an attempt to bring the server up and its retry
+     * schedule. Instance fields (initialised from the module defaults) only so the
+     * tests can fail attempts and shrink the pauses — production never changes them.
+     */
+    serverRestartOps = defaultOpenCodeServerRestartOps;
+    serverRestartRetryDelaysMs = exports.openCodeServerRestartRetryDelaysMs;
+    serverRestartRetryBudgetMs = exports.openCodeServerRestartRetryBudgetMs;
     /**
      * Per-thread display-prefs reader, injected by the bot at boot via
      * `createAdapter.registerDisplayPrefsReader` (S4). DELIBERATE deviation from
@@ -1215,45 +1349,44 @@ class OpenCodeAdapter extends events_1.EventEmitter {
         return true;
     }
     /**
-     * @description Handle unexpected server process death.
-     * Notifies all active users and attempts to restart the server.
+     * @description Handle unexpected server process death: restart it. The topics
+     * hear nothing unless it matters to them — a turn that was in flight, a session
+     * the new server no longer has, or a restart that failed ({@link restartServer}).
      * SSE reconnect loop will detect the restart and recover automatically.
      */
     handleServerCrash(code, signal) {
         const reason = code === 137 ? 'out of memory (OOM killed)' :
             signal ? `signal ${signal}` : `exit code ${code}`;
-        // Notify all active session threads about the crash
-        for (const session of this.sessions.values()) {
-            if (session.isActive) {
-                this.emit('output', session.key, `OpenCode server crashed (${reason}). Restarting...`);
-            }
-        }
-        // Auto-restart the server (SSE reconnect loop will pick it up)
-        this.restartServer();
+        console.error(`[OpenCode] Server stopped (${reason}), restarting it`);
+        void this.restartServer();
     }
     /**
-     * @description Restart the OpenCode server process.
-     * Prevents concurrent restart attempts. If restart is already in progress,
-     * waits for it to complete and returns its result.
+     * @description Restart the OpenCode server process. A restart already in
+     * progress is shared: its result is the caller's.
      */
-    async restartServer(force = false) {
-        if (this.isServerRestarting) {
-            console.log(`[OpenCode] Server restart already in progress, waiting...`);
-            // Wait for the in-progress restart to complete
-            while (this.isServerRestarting) {
-                await new Promise(resolve => setTimeout(resolve, 500));
-            }
-            // Check if server is now running
-            return (0, installManager_1.checkIsOpenCodeServerRunning)();
-        }
-        this.isServerRestarting = true;
+    restartServer(force = false) {
+        if (this.serverRestart) {
+            console.log(`[OpenCode] Server restart already in progress, waiting for it`);
+            return this.serverRestart;
+        }
+        const restart = this.runServerRestart(force).finally(() => {
+            if (this.serverRestart === restart)
+                this.serverRestart = null;
+        });
+        this.serverRestart = restart;
+        return restart;
+    }
+    /**
+     * @description The body of {@link restartServer}. Bringing the server back is
+     * retried ({@link ensureServerWithRetries}) and silent: a topic whose session
+     * is restored hears about it only when its turn was in flight — that reply is
+     * lost and has to be asked again.
+     */
+    async runServerRestart(force) {
+        // Read before the restore loop: resuming rebuilds every session object.
+        const turnInFlightKeys = new Set(Array.from(this.sessions.entries()).filter(([, session]) => session.isActive && session.isBusy).map(([k]) => k));
         try {
-            console.log(`[OpenCode] Attempting server restart...`);
-            if (force)
-                await (0, installManager_1.restartOpenCodeServer)();
-            else
-                await (0, installManager_1.ensureOpenCodeServer)();
-            console.log(`[OpenCode] Server restarted successfully`);
+            await this.ensureServerWithRetries(force ? 'replace' : 'adopt');
             // Close the global stream up front: its reader points at the crashed
             // server's connection. The resume loop below re-opens the (idempotent)
             // single stream via connectSse (plan 2026-06-17 S4). Without this the
@@ -1281,7 +1414,9 @@ class OpenCodeAdapter extends events_1.EventEmitter {
                     // lifecycle lock here exactly like the public resumeSession does, so
                     // the lock is taken once (no double-acquire from the crash handler).
                     await this.withLifecycleLock(k, () => this.resumeSessionInner(sessionKey, workDir, sessionId));
-                    this.emit('output', sessionKey, `OpenCode server restarted; session restored. In-flight reply was lost — resend if needed.`);
+                    if (turnInFlightKeys.has(k)) {
+                        this.emit('output', sessionKey, this.tl(sessionKey, () => (0, i18n_1.t)('openCodeServer.restartedSessionRestoredNotice')));
+                    }
                 }
                 catch (e) {
                     // The id is gone on the restarted server (or resume otherwise
@@ -1290,7 +1425,7 @@ class OpenCodeAdapter extends events_1.EventEmitter {
                     // wipes the persisted session id too — otherwise the next bot
                     // restart would try to resume an id the server no longer has.
                     console.error(`[OpenCode] Could not restore session ${sessionId} after restart:`, e);
-                    this.emit('output', sessionKey, `OpenCode server restarted; previous session lost. Starting a fresh one with /opencode (or /quit to release).`);
+                    this.emit('output', sessionKey, this.tl(sessionKey, () => (0, i18n_1.t)('openCodeServer.restartedSessionLostNotice')));
                     this.stopSessionInner(sessionKey);
                     this.emit('closed', sessionKey);
                     // Defensive: stopSessionInner deletes from `this.sessions`, but
@@ -1301,13 +1436,16 @@ class OpenCodeAdapter extends events_1.EventEmitter {
             return true;
         }
         catch (e) {
-            console.error(`[OpenCode] Server restart failed:`, e);
+            // The technical detail stays in the log; the topic gets one short
+            // localized line — a raw exception (`spawn opencode ENOENT`) tells the
+            // person in the topic nothing they can act on.
+            console.error(`[OpenCode] Server restart failed, giving up:`, e);
             // Notify threads about the failure and tear them down
             // Take a snapshot first so we can safely mutate `this.sessions` inside the loop.
             const snapshot = Array.from(this.sessions.entries());
             for (const [k, session] of snapshot) {
                 if (session.isActive) {
-                    this.emit('output', session.key, `Failed to restart OpenCode server: ${e instanceof Error ? e.message : String(e)}`);
+                    this.emit('output', session.key, this.tl(session.key, () => (0, i18n_1.t)('agent.serverUnavailableNotice', { label: this.label })));
                     // Mark session as inactive — no point keeping it alive
                     session.isActive = false;
                     // This teardown bypasses stopSessionInner, so the replacement bound
@@ -1319,10 +1457,61 @@ class OpenCodeAdapter extends events_1.EventEmitter {
             }
             return false;
         }
-        finally {
-            this.isServerRestarting = false;
+    }
+    /**
+     * @description The ONE way the adapter brings the server up — a restart, a
+     * session start or resume, the provider sign-in: each attempt first makes sure
+     * the binary is installed, then starts (or adopts) the server per `mode`; a
+     * failed attempt is retried on the {@link openCodeServerRestartRetryDelaysMs}
+     * pauses within {@link openCodeServerRestartRetryBudgetMs}. `onStep` tells a
+     * waiting person what is happening (a start or resume; a restart passes none
+     * and stays silent). Throws {@link AgentBackendUnavailableError} once the
+     * retries are used up — the attempts' errors stay in the log.
+     */
+    async ensureServerWithRetries(mode, onStep) {
+        const firstAttemptStartedAt = Date.now();
+        for (let retryIndex = 0;; retryIndex++) {
+            try {
+                if (mode === 'ifDown' && await this.serverRestartOps.checkIsServerRunning())
+                    return;
+                console.log(`[OpenCode] Bringing the server up (${mode}, attempt ${retryIndex + 1})...`);
+                if (!this.serverRestartOps.checkIsInstalled()) {
+                    console.log(`[OpenCode] opencode binary not found, installing it first...`);
+                    if (retryIndex === 0)
+                        onStep?.('installing');
+                    await this.serverRestartOps.installTool();
+                }
+                if (retryIndex === 0)
+                    onStep?.('starting');
+                if (mode === 'replace')
+                    await this.serverRestartOps.restartServer();
+                else
+                    await this.serverRestartOps.ensureServer();
+                console.log(`[OpenCode] Server is up`);
+                return;
+            }
+            catch (e) {
+                const delayMs = getOpenCodeServerRestartRetryDelayMs(retryIndex, Date.now() - firstAttemptStartedAt, this.serverRestartRetryDelaysMs, this.serverRestartRetryBudgetMs);
+                if (delayMs === null) {
+                    console.error(`[OpenCode] The server could not be brought up after ${retryIndex + 1} attempts:`, e);
+                    throw new backendUnavailableError_1.AgentBackendUnavailableError(this.label, e);
+                }
+                console.warn(`[OpenCode] Attempt ${retryIndex + 1} to bring the server up failed, retrying in ${Math.round(delayMs / 1000)}s:`, e instanceof Error ? e.message : e);
+                await (0, utils_1.sleep)(delayMs);
+            }
         }
     }
+    /**
+     * @description {@link ensureServerWithRetries} for a session start or resume of
+     * `key`: the server is brought up only when it is down, and the topic is told
+     * (in its language) that OpenCode is being installed or started.
+     */
+    ensureServerForSession(key) {
+        return this.ensureServerWithRetries('ifDown', (step) => {
+            const noticeKey = step === 'installing' ? 'openCodeServer.installingNotice' : 'openCodeServer.startingNotice';
+            this.emit('output', key, this.tl(key, () => (0, i18n_1.t)(noticeKey)));
+        });
+    }
     /**
      * @description Reload credentials written by the out-of-band `opencode auth
      * login` CLI. The CLI updates auth.json directly, but a running OpenCode
@@ -1432,16 +1621,10 @@ class OpenCodeAdapter extends events_1.EventEmitter {
         // mapping `SessionKey → opencodeSessionId` in state.json (plan §13.19) so
         // resumes after a restart go through `resumeSession()`, not startSession.
         const k = (0, sessionKey_1.keyToString)(key);
+        await this.waitForServerRestart();
         return this.withLifecycleLock(k, async () => {
             this.stopSessionInner(key);
-            if (!(0, installManager_1.checkIsInstalled)('opencode')) {
-                this.emit('output', key, 'Installing OpenCode...');
-                await (0, installManager_1.installTool)('opencode');
-            }
-            if (!await (0, installManager_1.checkIsOpenCodeServerRunning)()) {
-                this.emit('output', key, 'Starting OpenCode server...');
-                await (0, installManager_1.ensureOpenCodeServer)();
-            }
+            await this.ensureServerForSession(key);
             console.log(`[OpenCode] Starting session for ${k} in ${workDir}`);
             try {
                 // R1 (verified live 2026-06-04): a session created WITHOUT a title is
@@ -1490,6 +1673,7 @@ class OpenCodeAdapter extends events_1.EventEmitter {
                     isBusy: false,
                     awaitingTurnResponse: false,
                     sawTurnActivity: false,
+                    handledTurnErrorTexts: new Set(),
                     unconsumedInputCount: 0,
                     seenUserMessageIds: new Set(),
                     providerRetrySignature: null,
@@ -1646,6 +1830,14 @@ class OpenCodeAdapter extends events_1.EventEmitter {
      * model selector. No separate request, no env configuration.
      */
     sendPromptAsync(key, input) {
+        if (this.serverRestart) {
+            // Posted now, the prompt would hit the server that is down and be lost with
+            // a raw `fetch failed`; it goes out once the restart has restored the session.
+            // A restart that failed has stopped the session: the topic was told to send again.
+            console.log(`[OpenCode] holding a prompt for ${(0, sessionKey_1.keyToString)(key)} until the server restart ends`);
+            void this.serverRestart.then(() => this.sendPromptAsync(key, input));
+            return;
+        }
         const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
         if (!session?.isActive) {
             console.log(`[OpenCode] sendInput: no active session for ${(0, sessionKey_1.keyToString)(key)}`);
@@ -1671,6 +1863,7 @@ class OpenCodeAdapter extends events_1.EventEmitter {
         // New turn → previous turn's tool-result dedup ids can no longer matter
         // (see the field's JSDoc for why the turn flush is too early to clear).
         session.emittedToolResultPartIds.clear();
+        session.handledTurnErrorTexts.clear();
         // Mark busy optimistically so an immediately-following message correctly
         // sees a turn in flight; the `session.status` stream corrects/confirms it.
         session.isBusy = true;
@@ -1960,13 +2153,8 @@ class OpenCodeAdapter extends events_1.EventEmitter {
             return (0, i18n_1.t)('disconnect.failed', { provider: normalizedProviderId, reason });
         }
     }
-    async ensureProviderAuthServerReady() {
-        if (!(0, installManager_1.checkIsInstalled)('opencode')) {
-            await (0, installManager_1.installTool)('opencode');
-        }
-        if (!await (0, installManager_1.checkIsOpenCodeServerRunning)()) {
-            await (0, installManager_1.ensureOpenCodeServer)();
-        }
+    ensureProviderAuthServerReady() {
+        return this.ensureServerWithRetries('ifDown');
     }
     /**
      * @description Fetch a provider's auth methods for the `/connect` picker.
@@ -2026,7 +2214,7 @@ class OpenCodeAdapter extends events_1.EventEmitter {
                 }
             }
             else {
-                session.effortLevel = (0, effortLevels_1.clampEffortToAvailable)(effortLevels_1.defaultEffortLevel, await this.getModelVariants(resolved));
+                session.effortLevel = (0, effortLevels_1.clampEffortToAvailable)((0, effortLevels_1.getInstanceDefaultEffort)(), await this.getModelVariants(resolved));
             }
             return null;
         }
@@ -2154,7 +2342,7 @@ class OpenCodeAdapter extends events_1.EventEmitter {
      * started/resumed session that has NO explicit per-thread `/effort` pref.
      *
      * Explicit prefs always win and are left untouched (early return). With no
-     * pref, the default (`defaultEffortLevel`) is clamped to the resolved
+     * pref, the instance default (`getInstanceDefaultEffort`) is clamped to the resolved
      * model's variants — OpenCode effort is a model variant and not every model
      * ships `xhigh`, so an unclamped value would POST an invalid `body.variant`.
      * A model with no variants resolves to `null` (no effort), which is correct.
@@ -2169,7 +2357,7 @@ class OpenCodeAdapter extends events_1.EventEmitter {
         if (loadSavedEffort(key) !== null)
             return; // explicit pref wins
         const variants = await this.getModelVariants(this.getSessionModelRef(session));
-        session.effortLevel = (0, effortLevels_1.clampEffortToAvailable)(effortLevels_1.defaultEffortLevel, variants);
+        session.effortLevel = (0, effortLevels_1.clampEffortToAvailable)((0, effortLevels_1.getInstanceDefaultEffort)(), variants);
     }
     /**
      * @description Resolve the model the thread's effort applies to, WITHOUT
@@ -2234,19 +2422,57 @@ class OpenCodeAdapter extends events_1.EventEmitter {
         }
         return this.getModelVariants(await this.getProspectiveModelRef(key));
     }
+    async getProspectiveModelLabel(key) {
+        const ref = await this.getProspectiveModelRef(key);
+        return ref ? `${ref.providerID}/${ref.modelID}` : null;
+    }
     getEffort(key) {
         const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
         if (session)
             return session.effortLevel;
         return loadSavedEffort(key);
     }
+    /** Only the persisted pick: a live session's `effortLevel` may be the clamped default (see {@link getEffort}). */
+    getOwnEffort(key) {
+        return loadSavedEffort(key);
+    }
+    /**
+     * The live session sends its `effortLevel` with every prompt (a model variant, or none for `auto` / a model
+     * without variants). The next session seeds the pick, else the default rounded to the variants of the model it
+     * will run (the live one, else the topic's saved `/model`) — read from the last providers snapshot, so this stays
+     * synchronous (the banner needs it); unknown variants (the server's default model, no snapshot yet) leave the
+     * default as it is. A model KNOWN to have no variants runs without any level, so there is no state to show
+     * (`null`, as `/effort` answers «not available» for it).
+     */
+    getEffortState(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        const liveSession = session?.isActive ? session : null;
+        const pick = loadSavedEffort(key);
+        const defaultLevel = (0, effortLevels_1.getInstanceDefaultEffort)();
+        const variants = getKnownModelVariants(liveSession ? this.getSessionModelRef(liveSession) : loadSavedModel(key));
+        if (variants !== null && variants.length === 0)
+            return null;
+        return {
+            running: liveSession ? liveSession.effortLevel : null,
+            nextStart: pick ?? (0, effortLevels_1.clampEffortToAvailable)(defaultLevel, variants ?? []) ?? defaultLevel,
+        };
+    }
+    /**
+     * @description Forget the thread's own pick; a live session takes the clamped instance default for its next
+     * prompt ({@link applyDefaultEffortIfUnset}), a later one seeds it at creation.
+     */
+    async clearEffort(key) {
+        clearEffortPref(key);
+        await this.applyDefaultEffortIfUnset(key);
+    }
     /**
      * @description Set the per-thread effort (variant). Validates against the
      * thread's available variants — live model when a session is running, the
      * PROSPECTIVE model (saved `/model` pref → server default) when not — then
      * persists on success (applied per-prompt by `sendPromptAsync`, plan D3; a
-     * later session seeds `effortLevel` from this pref at creation). Returns a
-     * user-facing notice string on any non-success, `null` on success.
+     * later session seeds `effortLevel` from this pref at creation). `refused` with a
+     * user-facing reason on any non-success, `applied` on success — also with no
+     * session: there is nothing left to do, a later session seeds the pick.
      *
      * Mirrors `setModel`'s persist-first symmetry (no `'No active session'`
      * hard-fail): a level picked BEFORE `/opencode` is saved and replayed by the
@@ -2261,10 +2487,10 @@ class OpenCodeAdapter extends events_1.EventEmitter {
             // session is up, else the prospective model — so the notice is correct
             // pre-session (the live `currentModelLabel` is null then).
             const modelLabel = await this.getEffortModelLabel(key);
-            return (0, i18n_1.t)('effort.not_supported', { model: modelLabel });
+            return { status: 'refused', reason: (0, i18n_1.t)('effort.not_supported', { model: modelLabel }) };
         }
         if (!available.includes(level)) {
-            return (0, i18n_1.t)('effort.invalid_level', { level, valid: available.join(', ') });
+            return { status: 'refused', reason: (0, i18n_1.t)('effort.invalid_level', { level, valid: available.join(', ') }) };
         }
         // Persist unconditionally (like `setModel`'s `saveModelPref`): a session
         // started later seeds `effortLevel: loadSavedEffort(key)` at creation.
@@ -2275,7 +2501,7 @@ class OpenCodeAdapter extends events_1.EventEmitter {
         if (session?.isActive)
             session.effortLevel = level;
         console.log(`[OpenCode] Effort set to: ${level}`);
-        return null;
+        return { status: 'applied' };
     }
     /**
      * @description Human label for the model the thread's effort validates
@@ -2494,8 +2720,20 @@ class OpenCodeAdapter extends events_1.EventEmitter {
         // resumes to the wrong folder as soon as the bot started managing
         // multiple bindings (plan §10.3, fix to old openCodeAdapter.ts:599).
         const k = (0, sessionKey_1.keyToString)(key);
+        await this.waitForServerRestart();
         return this.withLifecycleLock(k, () => this.resumeSessionInner(key, workDir, sessionId, options));
     }
+    /**
+     * @description Let a server restart in progress finish before a session start
+     * or resume brings the server up on its own (it would race the restart's
+     * attempts). Its outcome does not matter here: a failed restart leaves the
+     * server down, and the caller's own attempts follow. Never called from inside
+     * the restart, whose restore loop resumes through the inner body.
+     */
+    async waitForServerRestart() {
+        if (this.serverRestart)
+            await this.serverRestart;
+    }
     /**
      * @description Fork the thread's CURRENT session into a new one that carries
      * the full conversation, and attach to it. Used by the bot's wedged-turn
@@ -2554,14 +2792,7 @@ class OpenCodeAdapter extends events_1.EventEmitter {
     async resumeSessionInner(key, workDir, sessionId, options) {
         this.stopSessionInner(key);
         const k = (0, sessionKey_1.keyToString)(key);
-        if (!(0, installManager_1.checkIsInstalled)('opencode')) {
-            this.emit('output', key, 'Installing OpenCode...');
-            await (0, installManager_1.installTool)('opencode');
-        }
-        if (!await (0, installManager_1.checkIsOpenCodeServerRunning)()) {
-            this.emit('output', key, 'Starting OpenCode server...');
-            await (0, installManager_1.ensureOpenCodeServer)();
-        }
+        await this.ensureServerForSession(key);
         console.log(`[OpenCode] Resuming session ${sessionId} for ${k} in ${workDir}`);
         try {
             // Verify session exists
@@ -2597,6 +2828,7 @@ class OpenCodeAdapter extends events_1.EventEmitter {
                 isBusy: false,
                 awaitingTurnResponse: false,
                 sawTurnActivity: false,
+                handledTurnErrorTexts: new Set(),
                 unconsumedInputCount: 0,
                 seenUserMessageIds: new Set(),
                 providerRetrySignature: null,
@@ -4134,12 +4366,60 @@ class OpenCodeAdapter extends events_1.EventEmitter {
             if (checkIsOpenCodeAbortError(errorMsg)) {
                 console.log(`[OpenCode] Swallowed bot-issued abort (message.error "Aborted") for ${(0, sessionKey_1.keyToString)(key)}`);
             }
+            else if (info.sessionID && info.sessionID !== session.sessionId) {
+                // A sub-agent's failed step reaches the parent as a failed tool call; it is not the topic's failure.
+                console.log(`[OpenCode] ${(0, sessionKey_1.keyToString)(key)}: message error of session ${info.sessionID}, not the topic's own:`, getOpenCodeErrorLogText(info.error));
+            }
             else {
-                console.error(`[OpenCode] Message error:`, errorMsg);
-                this.emit('output', key, `Error: ${errorMsg}`);
+                this.handleOwnTurnFailure(key, info.error, 'message.error');
             }
         }
     }
+    /**
+     * @description One failure of the topic's OWN turn, from either channel OpenCode reports it on: `session.error` and the
+     * failed assistant message (`message.updated` with `info.error`). OpenCode publishes most failures on both, in either
+     * order, and may update the message more than once — so a failure is handled ONCE per turn
+     * ({@link OpenCodeSession.handledTurnErrorTexts}); one that comes only on the message (a compaction, a structured-output
+     * step) is handled all the same. Handled = posted (`OpenCode error: …` / `Error: …` by the channel that came first)
+     * and, when the classifier knows it, handed to the
+     * bot's auto-retry (`apiError`). A conversation-tail refusal is not posted: the retry's own notice is its one line.
+     *
+     * Classified from the RAW payload, not from the surfaced text: that collapses an unrecognised shape to a constant
+     * that carries no marker to classify. The raw text stops here — the classifier returns only a class.
+     */
+    handleOwnTurnFailure(key, error, channel) {
+        const errorMsg = getOpenCodeErrorMessage(error);
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (session?.handledTurnErrorTexts.has(errorMsg)) {
+            console.log(`[OpenCode] ${(0, sessionKey_1.keyToString)(key)}: the turn's failure came again on ${channel} — already handled, not posted again`);
+            return;
+        }
+        session?.handledTurnErrorTexts.add(errorMsg);
+        console.error(`[OpenCode] ${(0, sessionKey_1.keyToString)(key)}: turn failure (${channel}):`, getOpenCodeErrorLogText(error));
+        // A PARENT-session error aborts the current turn/generation, so the
+        // delegation the dedicated sub-agent status describes is no longer running:
+        // close it defensively (mirrors the parent-idle / parent-finish closes) so
+        // an error that never reaches a clean idle can't leave the "working" frame
+        // and its self-re-arming tick wedged, flooding the topic (live 2026-08-03).
+        // If an auto-retry re-delegates, a fresh `subagentStatus{active:true}` re-opens it.
+        if (session?.isActive)
+            this.closeSubagentStatusOnParentTurnEnd(key);
+        // Provider-side API error at the proxy boundary → emit `apiError`. transient / usageLimit / conversationTail arm
+        // the auto-retry (the session stays active after the error, so the kick reuses it); `auth` (logged out / bad
+        // credentials) is SURFACED as a pinned notice by the bot, never retried. Unrecognised errors classify to `null`.
+        const now = Date.now();
+        const apiError = (0, apiErrorRetry_1.classifyAgentApiError)(getOpenCodeErrorClassificationText(error), now);
+        if (apiError?.kind !== 'conversationTail')
+            this.emit('output', key, `${openCodeFailurePrefixes[channel]}${errorMsg}`);
+        if (!apiError)
+            return;
+        // A usage limit whose text names no reset takes the provider's Retry-After, read as a field — unless it is a
+        // short retry hint (a daily quota comes with Google's 40-second one), which is not the window's reset.
+        const retryAfterAt = apiError.kind === 'usageLimit' && apiError.resetAt === undefined ? getOpenCodeErrorRetryAfterAt(error, now) : undefined;
+        const limitRetryAfterAt = retryAfterAt !== undefined && !(0, apiErrorRetry_1.checkIsShortStatedReset)(retryAfterAt, now) ? retryAfterAt : undefined;
+        const resetAt = apiError.kind === 'usageLimit' ? apiError.resetAt ?? limitRetryAfterAt : undefined;
+        this.emit('apiError', key, apiError.kind === 'usageLimit' ? { ...apiError, resetAt } : apiError);
+    }
     /**
      * @description Handle session becoming idle (AI done processing).
      * Flush any remaining accumulated output.
@@ -4387,32 +4667,18 @@ class OpenCodeAdapter extends events_1.EventEmitter {
             }
             return;
         }
-        console.error(`[OpenCode] Session error:`, errorMsg);
-        this.emit('output', key, `OpenCode error: ${errorMsg}`);
-        // A PARENT-session error aborts the current turn/generation, so the
-        // delegation the dedicated sub-agent status describes is no longer running:
-        // close it defensively (mirrors the parent-idle / parent-finish closes) so
-        // an error that never reaches a clean idle can't leave the "working" frame
-        // and its self-re-arming tick wedged, flooding the topic (live 2026-08-03).
-        // A CHILD (sub-agent) error must NOT close it — the parent delegation is
-        // still in flight (guarded the same way as `handleSessionIdle`). If an
-        // auto-retry re-delegates, a fresh `subagentStatus{active:true}` re-opens it.
-        if (session?.isActive && isOwnSession) {
-            this.closeSubagentStatusOnParentTurnEnd(key);
-        }
-        // Provider-side API error at the proxy boundary → emit `apiError`. transient
-        // / usageLimit arm the auto-retry (the session stays active after
-        // `session.error`, so the kick reuses it); `auth` (logged out / bad
-        // credentials) is SURFACED as a pinned notice by the bot, never retried.
-        // Unrecognised errors classify to `null` and emit nothing.
-        //
-        // Classified from the RAW payload, not from `errorMsg`: the surfaced text
-        // collapses an unrecognised shape to a constant that carries no marker to
-        // classify. The raw text stops here — the classifier returns only a class.
-        const apiError = (0, apiErrorRetry_1.classifyAgentApiError)(getOpenCodeErrorClassificationText(properties.error), Date.now());
-        if (apiError) {
-            this.emit('apiError', key, apiError);
+        // Only the topic's OWN session's error is the topic's: a sub-agent's child session (often on another model or
+        // provider) and a foreign session routed here by the folder report limits that are not this conversation's —
+        // armed, they held a parent that was still working and marked its model limited. A child's real limit reaches the
+        // parent as a failed tool call; if it is the parent's too, the parent's own retry or error says so. Such an error is
+        // still shown, but never closes the parent's sub-agent status (its delegation is still in flight).
+        if (!isOwnSession) {
+            console.error(`[OpenCode] Session error:`, getOpenCodeErrorLogText(properties.error));
+            this.emit('output', key, `OpenCode error: ${errorMsg}`);
+            console.log(`[OpenCode] ${(0, sessionKey_1.keyToString)(key)}: session.error of session ${eventSessionId}, not the topic's own — no retry armed`);
+            return;
         }
+        this.handleOwnTurnFailure(key, properties.error, 'session.error');
     }
     handlePermissionAsked(_key, properties, directory) {
         console.log(`[OpenCode] Permission requested:`, JSON.stringify(properties));