charness 0.0.0-stage → 3.0.0

package/dist/adapters/openCodeAdapter.d.ts

@@ -0,0 +1,1446 @@
+import { EventEmitter } from 'events';
+import type { AgentAdapter, AgentRuntimeInfo, AgentSession, CompactionResult, DisplayPrefsReader, OpenCodePendingQuestion, ReattachRecap, RecentTurn, ResumeSessionOptions, SeenWatermark, SeenWatermarkWriter, ThreadLocaleReader } from '../types';
+import type { SessionKey } from '../sessionKey';
+import { type OpenCodeAuthMethod } from '../utils/openCodeAuthLogin';
+interface OpenCodeModelOverride {
+    providerID: string;
+    modelID: string;
+}
+export interface OpenCodeSession {
+    key: SessionKey;
+    sessionId: string;
+    workDir: string;
+    isActive: boolean;
+    /** Accumulated text parts for current response */
+    currentResponseText: string;
+    /**
+     * Length (chars) of {@link currentResponseText} that has already been
+     * emitted as an `output` event. Both emit sites (the debounce timer in
+     * `handleTextDelta` and `flushOutput`) send only the unsent tail
+     * `currentResponseText.slice(lastEmittedLength)` and advance this, so the
+     * full response reaches Telegram exactly once. Reset to 0 wherever
+     * `currentResponseText` is reset to `''`.
+     */
+    lastEmittedLength: number;
+    /** Timer for batching SSE deltas before emitting output */
+    outputTimer: NodeJS.Timeout | null;
+    /** Id of the newest compaction summary message (`message.updated` with `summary: true`), learned
+     *  before its text streams, so its parts can be told apart from an ordinary answer. */
+    compactionSummaryMessageId: string | null;
+    /** {@link currentResponseText} holds that summary: its tails carry `isCompactionSummary`. Reset alongside it. */
+    isResponseCompactionSummary: boolean;
+    /**
+     * Accumulated SUB-AGENT (child session) text for the current turn, streamed
+     * only in `/subagent full` mode. Kept strictly SEPARATE from
+     * {@link currentResponseText}: a child transcript must never advance the
+     * parent's emit cursor / continuation accounting. Reset wherever
+     * `currentResponseText` is reset.
+     */
+    childResponseText: string;
+    /** Emit cursor over {@link childResponseText} (same tail-emit discipline as
+     * {@link lastEmittedLength}). Reset alongside it. */
+    childLastEmittedLength: number;
+    /** Debounce timer for child text deltas — mirrors {@link outputTimer} but
+     * over the child accumulator, so the two streams never share a flush. */
+    childOutputTimer: NodeJS.Timeout | null;
+    /**
+     * Title of the delegation currently running in a child session, recorded
+     * from the parent's `task` tool part (`state.title` / `state.input.description`)
+     * while it is pending/running and cleared when it completes/errors. Drives
+     * the status-only-mode "🤖 sub-agent: <title> …" status (S4) and is the field
+     * the S5 "Delegating" activity status will reuse. v1 tracks ONE delegation —
+     * parallel tasks are last-writer-wins and the first completion clears.
+     */
+    activeSubagentTitle: string | null;
+    /** Whether model info has been shown to the user (shown once on first response) */
+    isModelInfoShown: boolean;
+    /** Model override for this session (passed with each prompt) */
+    modelOverride: OpenCodeModelOverride | null;
+    /** Last known model label from SSE events */
+    currentModelLabel: string | null;
+    /** Latest valid parent-assistant context observation, kept as an atomic tuple. */
+    latestParentRuntimeContext: OpenCodeParentAssistantContext | null;
+    /** Increments for each live parent-assistant observation from SSE. */
+    parentAssistantObservationVersion: number;
+    /** Map partID -> part type for resolving delta events */
+    partTypes: Map<string, string>;
+    /** Timer for debouncing status (tool/reasoning) updates */
+    statusDebounceTimer: NodeJS.Timeout | null;
+    /** Latest status text pending emission */
+    pendingStatus: string | null;
+    /**
+     * Accumulated reasoning (chain-of-thought) text for the CURRENT response,
+     * kept strictly SEPARATE from {@link currentResponseText} so it never leaks
+     * into the answer (or its continuation accounting). Reset to `''` when a new
+     * reasoning stream starts or the response's reasoning ends.
+     */
+    reasoningText: string;
+    /**
+     * Epoch ms of the FIRST reasoning delta of the current response, or `null`
+     * when no reasoning is in flight. Drives the "thought for {N}s" duration on
+     * the `thinking` `done` emit; reset on reasoning end.
+     */
+    reasoningStartedAt: number | null;
+    /**
+     * Debounce timer for the live `thinking` emit — the reasoning delta stream is
+     * chatty, so live emits are coalesced the same way text deltas are.
+     */
+    reasoningTimer: NodeJS.Timeout | null;
+    /**
+     * Part ids whose completed tool OUTPUT has already been emitted as a
+     * `toolResult` event — OpenCode re-sends a part on every state change (and
+     * may re-deliver the completed shape), so without this guard one result
+     * would reach the topic several times. Cleared on the NEXT prompt (not on
+     * the turn flush): part re-deliveries can straddle the finish/idle flush,
+     * and since part ids are unique a late clear can never suppress a genuine
+     * new result — while an early clear would re-open the double-emit window.
+     */
+    emittedToolResultPartIds: Set<string>;
+    /** Pending question awaiting user's answer */
+    pendingQuestion: OpenCodePendingQuestion | null;
+    /**
+     * Currently selected reasoning-effort level (a model variant) for this
+     * thread, or `null` if none has been chosen. Applied per-prompt by
+     * `sendPromptAsync` as `body.variant` on the prompt request.
+     */
+    effortLevel: string | null;
+    /**
+     * Whether this session is mid-generation. Tracked from SSE `session.status`
+     * (and cleared on `session.idle`); set optimistically when a prompt is sent.
+     * Drives {@link checkIsOpenCodeSessionBusy} (the scheduler's wait-for-idle
+     * probe). A normal busy turn queues new prompts, but a provider-managed
+     * `retry` is different: OpenCode will not read the queue until its retry time,
+     * so the next user prompt aborts that stale turn before using the current
+     * model override.
+     */
+    isBusy: boolean;
+    /**
+     * Whether a prompt was sent and we are still waiting for the turn it started
+     * to resolve at the next own-session `session.idle`. Reset on each prompt send;
+     * cleared on the resolving idle. With {@link sawTurnActivity} it drives the
+     * "prompt delivered but the agent never ran a turn" detector (a WEDGED session
+     * accepts the prompt then idles with no assistant activity — live 2026-08-15).
+     */
+    awaitingTurnResponse: boolean;
+    /**
+     * Prompts sent that OpenCode has not yet shown as a NEW user message on the
+     * event stream (a prompt sent while a turn runs is queued into it), and the
+     * user message ids already counted. See `checkHasUnconsumedInput`.
+     */
+    unconsumedInputCount: number;
+    seenUserMessageIds: Set<string>;
+    /**
+     * Whether ANY assistant activity (message.updated / part, own OR sub-agent
+     * child) was observed since the last prompt was sent. Reset false on prompt
+     * send; a healthy turn always sets it. Its absence at idle is the wedge signal.
+     */
+    sawTurnActivity: boolean;
+    /**
+     * Signature of the current provider-managed `session.status=retry`, or null.
+     * Doubles as the one-notice-per-retry dedup key and the signal that the next
+     * user prompt must interrupt the wait instead of queueing behind it.
+     */
+    providerRetrySignature: string | null;
+    /** Ignore stale model updates until the post-abort selected-model turn starts. */
+    isAwaitingModelAfterProviderRetryAbort: boolean;
+    /** Consume the idle emitted by an aborted provider-retry turn before handling the replacement turn. */
+    isAwaitingProviderRetryAbortIdle: boolean;
+    /**
+     * Wait for the post-abort replacement's own `busy` status before arming wedge
+     * detection. Never open-ended — {@link providerRetryReplacementStartTimer}
+     * bounds it, because while this is set the idle handler swallows every own idle.
+     */
+    isAwaitingProviderRetryReplacementStart: boolean;
+    /**
+     * Bound on that wait, or `null` when no replacement boundary is armed. A
+     * wedged session accepts the replacement prompt and never runs it, so its
+     * `busy` never arrives and the boundary would latch forever — swallowing every
+     * later idle, pinning {@link isBusy}, and disarming wedge detection. On expiry
+     * the adapter ends the episode and emits `noResponse` so the bot's recovery
+     * escalation runs. Cleared whenever the boundary resolves or the session is
+     * torn down; `unref`ed so it can never hold the process open.
+     */
+    providerRetryReplacementStartTimer: NodeJS.Timeout | null;
+    /** Shared abort request so concurrent prompts cannot race abort-after-prompt. */
+    providerRetryAbortPromise: Promise<void> | null;
+    /**
+     * Whether context compaction is in flight (between
+     * `session.next.compaction.started` and `…ended` / `session.compacted`).
+     * Counts as busy for {@link checkIsOpenCodeSessionBusy}.
+     */
+    isCompacting: boolean;
+    /**
+     * Child (sub-agent) session ids currently busy, learned from routed
+     * `session.status` events. A running sub-agent counts as busy for
+     * {@link checkIsOpenCodeSessionBusy}. Cleared per-child when that child
+     * goes idle.
+     */
+    busyChildSessionIds: Set<string>;
+    /**
+     * Id of the LAST completed parent assistant message of the turn, captured from
+     * the message events (no extra HTTP). Advanced to the persisted
+     * {@link SeenWatermark} on each parent-message `finish` (S7 — so a mid-turn
+     * restart re-counts nothing already relayed) and again on `session.idle` (the
+     * safety net), so a bot restart can count only the assistant messages produced
+     * after it (the reattach recap). `undefined` until the first assistant message
+     * finishes.
+     */
+    lastMessageId?: string;
+    /**
+     * Whether this session may still be renamed by the bot-side fallback. Set
+     * `true` only for sessions the bot created WITHOUT explicit `/opencode args`
+     * (those rely on opencode's native auto-title — R1). Cleared on the first
+     * meaningful prompt once the fallback has run (or decided auto-title already
+     * named it), so the bot never overwrites a real name and PATCHes at most
+     * once. Resumed / args-titled sessions start `false` — never auto-renamed.
+     */
+    isAutoNamePending: boolean;
+}
+/**
+ * @description SSE event envelope from OpenCode server.
+ * All SSE messages are `data:` lines containing JSON with { type, properties }.
+ * There are no `event:` lines — the event type is inside the JSON payload.
+ */
+interface OpenCodeSseEvent {
+    type: string;
+    properties: Record<string, unknown>;
+    /**
+     * Owning project-instance directory from the `/global/event` envelope
+     * (`{ directory, payload }`). The server multiplexes one PROJECT INSTANCE
+     * per directory, and instance-local state (pending questions, permissions)
+     * is only reachable when the request selects that instance via
+     * `?directory=` — a reply sent without it lands in the serve-cwd default
+     * instance and 404s (`QuestionNotFoundError`). Absent on the bare
+     * `/event` shape, which is instance-local by construction.
+     */
+    directory?: string;
+}
+/**
+ * OpenCode `/global/event` wraps the real event in `payload`, while `/event`
+ * emits it directly. Normalise both shapes before dispatching.
+ */
+export declare function normaliseOpenCodeSseEvent(raw: unknown): OpenCodeSseEvent | null;
+/**
+ * @description Append the `?directory=` instance selector to an API path when
+ * the owning instance is known. Without it the server resolves its serve-cwd
+ * default instance, whose in-memory state (questions, permissions) does not
+ * contain requests raised in other project instances — the reply then fails
+ * with 404 even though the request is alive in its own instance.
+ */
+export declare function buildDirectoryScopedPath(basePath: string, directory: string | undefined): string;
+export type { OpenCodeQuestionOption, OpenCodeQuestion, OpenCodePendingQuestion, } from '../types';
+export interface OpenCodeParentAssistantContext {
+    messageId: string;
+    /** Omitted when OpenCode did not report a usable provider/model reference. */
+    model?: OpenCodeModelOverride;
+    contextUsedTokens: number;
+}
+/**
+ * @description Map raw `GET /session/:id/message` records to the last `limit`
+ * conversational turns (oldest→newest) for the resume context block.
+ *
+ * Pure + exported (no I/O) so it is unit-testable. For each record it joins the
+ * text of every `{ type: 'text' }` part (skipping tool / step / empty parts),
+ * trims, and emits a {@link RecentTurn} only when the role is user/assistant
+ * AND the joined text is non-empty. Every field is guarded with `typeof` /
+ * `Array.isArray` so a malformed record is skipped, never crashes — no casts.
+ * Keeps only the last `limit` turns.
+ */
+export declare function mapOpenCodeMessagesToTurns(records: unknown, limit: number): RecentTurn[];
+/**
+ * @description Count the renderable assistant messages that appear AFTER the
+ * watermark message in a `GET /session/:id/message` payload — the OpenCode side
+ * of "how many agent messages did the user miss while the bot was down".
+ *
+ * Pure + exported (no I/O) so it is unit-testable against a records array. Walks
+ * the chronological records (oldest→newest), skipping everything up to and
+ * including the message whose `info.id === watermarkId`, then counts each later
+ * `assistant`-role record that carries at least one non-empty text part (the
+ * same renderability rule as {@link mapOpenCodeMessagesToTurns}, so the count
+ * matches what a turn body would show).
+ *
+ * `isWatermarkKnown` is `false` — and `missedCount` `0` — when the payload is
+ * not an array, no `watermarkId` was given, or the id is absent from the records
+ * (pruned / different session). The caller treats that as the fallback
+ * (no-count) recap, never a crash.
+ */
+export declare function countOpenCodeAssistantMessagesSinceId(records: unknown, watermarkId: string | undefined): {
+    missedCount: number;
+    isWatermarkKnown: boolean;
+};
+/**
+ * @description Last assistant message `id` in a `GET /session/:id/message`
+ * payload — the OpenCode reattach-recap HEAD watermark ("everything currently in
+ * the record is accounted for"). Pure + exported (no I/O) so it is unit-testable.
+ *
+ * Walks the chronological records and returns the `info.id` of the LAST record
+ * whose `info.role === 'assistant'` and whose `info.id` is a string; returns
+ * `undefined` for a non-array payload or when no assistant message carries an id
+ * (head unknown → the caller omits the watermark and retries next reattach).
+ *
+ * Anchors on the last ASSISTANT message (not the last record of any role) to
+ * mirror the live-advance watermark ({@link OpenCodeSession.lastMessageId}, set
+ * on the parent turn's final assistant message) and the count keyed off it in
+ * {@link countOpenCodeAssistantMessagesSinceId} — so the next reattach's
+ * `[watermark, …)` window starts at the true tail and yields 0 on a clean
+ * reattach. Unlike the missed-count it does NOT require renderable text: the
+ * watermark must advance past every assistant message seen, tool-only ones too.
+ */
+export declare function getLatestOpenCodeAssistantMessageId(records: unknown): string | undefined;
+/**
+ * @description Text of the NEWEST compaction summary in a `GET /session/:id/message`
+ * payload — the assistant message the fork stored with `info.summary === true`.
+ * Joins its renderable text parts (same rule as {@link mapOpenCodeMessagesToTurns}).
+ * Pure + exported (no I/O) so it is unit-testable. Returns `null` for a non-array
+ * payload or when no summary message with text is present, so F2's notice omits
+ * the closing block rather than posting an empty one.
+ */
+export declare function getLatestOpenCodeCompactionSummary(records: unknown): string | null;
+/**
+ * @description Best-effort "the turn is still in flight" signal for the reattach
+ * recap, derived from the already-fetched `GET /session/:id/message` payload —
+ * NO extra HTTP probe. True only when the LAST record is an `assistant` message
+ * with no `finish` reason yet (a turn the agent was mid-way through when the bot
+ * went down). Any uncertainty (empty / non-array payload, last record not a
+ * finished-less assistant message) → `false`, so the trailing "still working"
+ * line is never shown on a guess.
+ */
+export declare function checkIsOpenCodeTurnInFlight(records: unknown): boolean;
+/** Bound silent-restart metadata reads so many active sessions do not overload OpenCode. */
+export declare const openCodeRuntimeContextHydrationConcurrency = 3;
+/**
+ * SSE event types whose loss makes a turn silently hang — diag-logged on drop.
+ * `question.asked` / `permission.asked` are here so an unrouted one is LOGGED
+ * (the user's question vanishing silently was the worst failure mode): they DO
+ * carry a real top-level `sessionID` in the current OpenCode build (verified
+ * live 2026-06-08), so they resolve like any other event — by sessionID, with a
+ * directory fallback — and a genuine miss is loud, never a no-op.
+ */
+export declare const criticalSseEventTypes: Set<string>;
+/**
+ * @description How long a post-provider-retry replacement prompt may take to
+ * produce its first `busy` status before the adapter declares that it never
+ * started a turn. Derived from the SSE bounds rather than a flat number: the
+ * `busy` arrives sub-second on the happy path, but it is DELIVERED over the
+ * event stream, so a stall detected at {@link sseStallTimeoutMs} followed by a
+ * fully backed-off reconnect ({@link maxSseReconnectDelayMs}) can hide it for
+ * their sum. A flat 60s sat inside that window, so a stream hiccup would have
+ * been read as a dead turn and forked/restarted a session that was answering.
+ * Waiting only delays recovery; firing early discards live work.
+ */
+export declare const providerRetryReplacementStartTimeoutMs: number;
+/**
+ * @description Whether a `session.error` message is the bot-issued abort of a
+ * running generation (`POST /session/:id/abort`) — the ONLY source of an
+ * "Aborted" error in OpenCode (the user has no other abort trigger). It fires
+ * on the question-cancel SIGINT, `/esc`, and the provider-retry interrupt, and
+ * must be SWALLOWED rather than surfaced as "OpenCode error: Aborted" — that
+ * bogus line was the third message on the question-cancel path (parity with the
+ * json-stream "Claude error: API error" swallow). Matched as the exact bare
+ * word so a real provider error that merely quotes "aborted" still surfaces.
+ */
+export declare function checkIsOpenCodeAbortError(errorMsg: string): boolean;
+/**
+ * Cap for a surfaced error string. A provider can attach a whole
+ * request/response dump; the head carries the readable reason, the tail is
+ * noise that would flood the topic.
+ */
+export declare const openCodeErrorMessageMaxLength = 500;
+/**
+ * @description Extract the readable, SAFE-TO-SURFACE error form from OpenCode's
+ * persisted and SSE payload shapes. Every return value of this function reaches
+ * a Telegram topic and the console log, so a payload whose shape carries no
+ * known message field yields the fixed {@link genericOpenCodeErrorMessage}: such
+ * a payload is an arbitrary provider dump (a rejected request body, a header
+ * list, a response echo) and `/connect` PUTs the user's provider key, so
+ * rendering it is a credential-leak path that name-based redaction cannot close.
+ * The retry classifier reads {@link getOpenCodeErrorClassificationText} instead.
+ */
+export declare function getOpenCodeErrorMessage(error: unknown): string;
+/**
+ * @description Live busy-relevant state of an OpenCode session, derived from
+ * SSE events (not an HTTP poll — the stream catches sub-100 ms busy/idle
+ * transitions an HTTP poll races past).
+ */
+export interface OpenCodeBusyState {
+    /** Own session is mid-generation (`session.status` = busy). */
+    isBusy: boolean;
+    /** Context compaction is in flight. */
+    isCompacting: boolean;
+    /** Number of child (sub-agent) sessions currently busy. */
+    busyChildCount: number;
+}
+/**
+ * @description Sync "is this session occupied with a turn?" decision for the
+ * scheduler's wait-for-idle loop ({@link AgentAdapter.checkIsBusy}): busy when
+ * its own generation runs, a sub-agent runs, or context is compacting. This is
+ * a read-only probe — a new prompt to a busy session is never aborted; OpenCode
+ * queues it via `prompt_async` and reads it promptly, so unlike the Claude TUI
+ * there is no interrupt-before-prompt (user decision 2026-06-06). Pure +
+ * exported for unit testing.
+ */
+export declare function checkIsOpenCodeSessionBusy(state: OpenCodeBusyState): boolean;
+/** Mutable busy-tracking slice of a session, updated from SSE status/idle events. */
+export interface OpenCodeBusyTracking {
+    isBusy: boolean;
+    busyChildSessionIds: Set<string>;
+}
+/**
+ * @description Apply a busy/idle transition (from `session.status` or
+ * `session.idle`) to a session's busy-tracking state. The own session's status
+ * drives `isBusy`; a lineage-VERIFIED descendant's (sub-agent child session's)
+ * status maintains `busyChildSessionIds` — a child going idle must NOT clear
+ * the parent's `isBusy`. A foreign non-descendant id (e.g. a wedged sibling
+ * top-level session routed in via the directory fallback) is never recorded:
+ * its busy=true is ignored — recording it would pin the thread busy forever,
+ * since a wedged session never goes idle (live incident 2026-06-10) — while
+ * its busy=false still deletes, self-healing ids that slipped in before
+ * verification existed. Pure + exported so the routing is unit-testable.
+ *
+ * @returns `true` when a foreign non-descendant busy=true was ignored, so the
+ * caller can diag-log it (throttled — never per event).
+ */
+export declare function applyOpenCodeStatusEvent(tracking: OpenCodeBusyTracking, ownSessionId: string, eventSessionId: string | null, isBusy: boolean, isVerifiedDescendant: boolean): boolean;
+/**
+ * @description Provider → model configuration map. Keys are provider ids
+ * (e.g. `"anthropic"`, `"openai"`), values are model ids (e.g.
+ * `"claude-3-5-sonnet"`) mapping to its variants and context limit. A model
+ * with no `variants` entry maps to `[]`, which the picker treats as "this model
+ * has no effort concept".
+ */
+export interface ParsedProvidersConfig {
+    providers: Map<string, Map<string, OpenCodeProviderModel>>;
+}
+export interface OpenCodeProviderModel {
+    variants: string[];
+    contextWindowTokens: number | null;
+}
+/**
+ * @description Build the JSON body for a `prompt_async` POST. Pure + exported
+ * so the two per-prompt overrides — the model selector and the reasoning-effort
+ * `variant` — can be unit-tested without a live session. Both are optional and
+ * ride the same body, parallel to each other.
+ *
+ * @returns Body with `parts` always present; `model` only when a model override
+ * is set; `variant` only when an effort level is set.
+ */
+export declare function buildPromptBody(input: string, modelOverride: {
+    providerID: string;
+    modelID: string;
+} | null, effortLevel: string | null): Record<string, unknown>;
+export declare function checkIsValidProviderId(providerId: string): boolean;
+/**
+ * @description Return the newest parent assistant message with a valid complete
+ * input-context usage total from a session-history payload. A malformed or
+ * foreign record is ignored rather than making a previous valid observation
+ * unusable.
+ */
+export declare function getLatestOpenCodeParentAssistantContext(records: unknown, sessionId: string): OpenCodeParentAssistantContext | null;
+export declare function buildProviderAuthPath(providerId: string): string;
+/**
+ * @description Pure decision for the boot self-heal: given opencode's live
+ * `GET /mcp` status map (`{ <serverName>: { status, error? }, … }`), does the
+ * bot-owned `telegramBot` server need a (re)registration? True when the entry is
+ * ABSENT (never registered on this server generation) or its `status` is
+ * anything other than `connected` (e.g. `failed` — a stale registration to a
+ * dead port left by a previous bot generation). A malformed/empty response is
+ * treated as "needs register": a redundant POST is a harmless overwrite on the
+ * server, whereas skipping a real failure would leave agents without the tools.
+ */
+export declare function checkNeedsSchedulerMcpReregister(mcpStatus: unknown): boolean;
+/**
+ * Pauses before each retry of a failed scheduler-MCP registration. A server that
+ * was just (re)started can take longer than the request timeout to create a
+ * folder's instance — live, the first POST after a restart timed out at 30 s and
+ * the folder's agent ran without the bot's tools until the next bot boot. After
+ * the last pause the bot stops; the next session start or bot boot tries again.
+ */
+export declare const schedulerMcpRetryDelaysMs: readonly number[];
+/** @description The pause before retry number `attempt` (0-based), or `null` once the retries are used up. */
+export declare function getSchedulerMcpRetryDelayMs(attempt: number): number | null;
+export declare function buildProviderApiAuthPayload(apiKey: string): Record<string, string>;
+/**
+ * @description Drop the cached model list + provider config so the next read
+ * re-fetches. Called after a credential change (`/connect`), which can change
+ * which providers/models the server exposes; also the isolation seam tests use
+ * to keep the module-level cache from leaking between cases.
+ */
+export declare function resetOpenCodeProviderCaches(): void;
+export declare function parseProvidersResponse(raw: unknown): ParsedProvidersConfig;
+export declare class OpenCodeAdapter extends EventEmitter implements AgentAdapter {
+    readonly name = "opencode";
+    readonly label = "OpenCode";
+    /**
+     * `summarize` produces a real assistant message, which rides the SSE stream into
+     * the topic as agent output marked `isCompactionSummary` — so the bot must not
+     * post its own copy of the summary here, or the operator would read it twice.
+     */
+    readonly streamsCompactionSummary = true;
+    /**
+     * Map of serialised `SessionKey` (`"<chatId>:<threadId>"`) → live session.
+     * Keyed by string rather than `SessionKey` object so map lookups work — JS
+     * `Map` compares object identity, not structural equality.
+     */
+    private sessions;
+    /**
+     * The ONE `/global/event` SSE stream for the whole adapter (plan 2026-06-17).
+     * It multiplexes every project instance's events, each tagged with a top-level
+     * `directory` field, so a single reader parses each event once and routes it
+     * by envelope `directory` + `sessionID`. Opened when the FIRST active session
+     * (any folder) appears, closed when the LAST one goes away. `null` while no
+     * session is active.
+     */
+    private globalStream;
+    /**
+     * Directories whose OpenCode instance already has the bot's scheduler MCP
+     * server registered for the CURRENT server generation (plan 2026-06-17 S3).
+     * Registration is now per directory on session start (decoupled from the
+     * stream, which is no longer per-folder); the Set gates it to once per
+     * directory per generation and is cleared on `restartServer` so each dir is
+     * re-registered after the server (and its in-memory MCP table) restarts.
+     */
+    private registeredSchedulerMcpDirs;
+    /**
+     * Directories whose scheduler-MCP registration failed and is waiting for a
+     * retry: the number of retries already scheduled, and the pending timer (null
+     * while the retry itself runs). Cleared by a registration that succeeds.
+     */
+    private schedulerMcpRetries;
+    /**
+     * child sessionID → parent sessionID, learned from `session.updated` events.
+     * OpenCode runs subagents (e.g. `@explore`) in child sessions whose SSE
+     * events carry the child id; this map routes them back to the topic bound to
+     * the parent. Bounded by `maxTrackedSessionLineageEntries`.
+     */
+    private sessionLineage;
+    /**
+     * Last diag-log timestamp per `"<eventType>|<eventSessionId>"`, so a flood of
+     * dropped events for an orphaned session logs at most once per
+     * `sseDropLogThrottleMs` instead of once per delta per bound thread (B19).
+     */
+    private sseDropLogThrottle;
+    private baseUrl;
+    private authHeader;
+    /**
+     * Grace period (ms) the fallback rename waits for opencode's native
+     * auto-title before stepping in. Instance field (initialised from
+     * {@link fallbackRenameGraceMs}) purely so the naming test can drive it to 0
+     * and assert the PATCH path deterministically — production never changes it.
+     */
+    private fallbackRenameGraceMs;
+    /**
+     * @description Per-key start/stop serialisation queue (audit S8 / #13).
+     * Two near-simultaneous `startSession(key, …)` calls otherwise both
+     * progress through `POST /session`; the second's `stopSession(key)`
+     * (line 529) clears whatever the first inserted into `this.sessions`,
+     * but the losing thread still has its SSE stream and a server-side
+     * session id with no owner.
+     */
+    private lifecycleChains;
+    /** Number of in-flight optional history reads used to hydrate `/status` metadata. */
+    private runtimeContextHydrationCount;
+    /** Callers waiting for one of the bounded runtime-context hydration slots. */
+    private runtimeContextHydrationWaiters;
+    /** Whether a server restart is already in progress (prevents concurrent restart attempts) */
+    private isServerRestarting;
+    /**
+     * Per-thread display-prefs reader, injected by the bot at boot via
+     * `createAdapter.registerDisplayPrefsReader` (S4). DELIBERATE deviation from
+     * the S2/S3 "adapter stays mode-agnostic" pattern: the sub-agent branch
+     * decides WHAT to accumulate (non-`full` = refresh a status, `full` = stream
+     * into the separate child accumulator), which cannot be deferred to the
+     * bot's render time. `null` until wired → reads fall back to all-`minimal`.
+     */
+    private displayPrefsReader;
+    /** @description Inject the per-thread display-prefs reader (see the field's JSDoc). */
+    setDisplayPrefsReader(reader: DisplayPrefsReader): void;
+    /** Per-thread locale reader, injected at boot via `createAdapter.registerThreadLocaleReader`. */
+    private threadLocaleReader;
+    /** @description Inject the per-thread locale reader (for adapter-side `t(...)` calls). */
+    setThreadLocaleReader(reader: ThreadLocaleReader): void;
+    /** @description Run `fn` inside the thread's locale context so `t(...)` resolves correctly. */
+    private tl;
+    /**
+     * Per-thread seen-watermark writer, injected by the bot at boot via
+     * `createAdapter.registerSeenWatermarkWriter`. Called at turn end
+     * (`session.idle`) to persist how far the live relay had shown the record.
+     * `null` until wired → {@link advanceSeenWatermark} is a no-op.
+     */
+    private seenWatermarkWriter;
+    /** @description Inject the per-thread seen-watermark writer (see the field's JSDoc). */
+    setSeenWatermarkWriter(writer: SeenWatermarkWriter): void;
+    /** @description Advance the persisted seen-watermark for `key` (no-op until the
+     * writer is wired). Skips a watermark with no anchor id so the bot's recap
+     * cleanly falls back to its no-count path. */
+    private advanceSeenWatermark;
+    /** @description Resolve the thread's full display prefs, defaulting every
+     * field to `minimal` for any read before the bot wires the reader at boot. */
+    private getDisplayPrefs;
+    /** @description Resolve the thread's `/subagent` mode (the only pref the
+     * OpenCode adapter consults today), via the full prefs reader. */
+    private getSubagentMode;
+    constructor();
+    private restoreSavedModel;
+    /**
+     * @description Handle unexpected server process death.
+     * Notifies all active users and attempts to restart the server.
+     * SSE reconnect loop will detect the restart and recover automatically.
+     */
+    private handleServerCrash;
+    /**
+     * @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.
+     */
+    private restartServer;
+    /**
+     * @description Reload credentials written by the out-of-band `opencode auth
+     * login` CLI. The CLI updates auth.json directly, but a running OpenCode
+     * server retains its prior provider credential in memory until restarted.
+     * Reuses the normal restart + active-session restoration path.
+     */
+    reloadProviderAuth(): Promise<boolean>;
+    private getHeaders;
+    private apiRequest;
+    /**
+     * @description Serialise start/stop ops per key. Returns the queued
+     * promise so callers still see the original result/throw. Audit S8.
+     */
+    private withLifecycleLock;
+    startSession(key: SessionKey, workDir: string, args?: string, _sessionId?: string): Promise<void>;
+    stopSession(key: SessionKey): void;
+    /** Lock-free body of `stopSession`; safe to call from start/resume paths
+     * that already hold the lifecycle lock. */
+    private stopSessionInner;
+    checkIsActive(key: SessionKey): boolean;
+    checkHasUnconsumedInput(key: SessionKey): boolean;
+    /**
+     * Count a parent-session user message the first time it shows up: OpenCode
+     * re-sends `message.updated` for one message, so ids are de-duplicated (the set
+     * is bounded — only recent ids can still repeat).
+     */
+    private noteUserMessageSeen;
+    checkIsBusy(key: SessionKey): boolean;
+    sendInput(key: SessionKey, input: string): void;
+    /**
+     * @description Send message via async endpoint (returns 204, response streams via SSE).
+     * Fire-and-forget — errors are logged but don't block.
+     *
+     * A normal busy turn is preserved and receives the prompt through OpenCode's
+     * queue. A provider-managed retry is interrupted first: otherwise a model
+     * switch plus "continue" is accepted into the transcript but remains unread
+     * behind the old provider's retry window.
+     *
+     * **Per-prompt effort apply:** if the thread has a stored effort level
+     * (a model variant), it's sent as `body.variant` alongside `body.model`
+     * — the same per-prompt override the prompt endpoint already uses for the
+     * model selector. No separate request, no env configuration.
+     */
+    private sendPromptAsync;
+    /**
+     * @description Return the one shared abort request for a provider-managed
+     * retry. Concurrent prompts await the same request, preventing a later abort
+     * from cancelling a prompt that an earlier caller already posted.
+     */
+    private getProviderRetryAbortPromise;
+    /**
+     * @description Arm the post-abort replacement boundary together with the bound
+     * on how long that boundary may stay armed.
+     *
+     * The boundary exists because `session.status` carries no turn identifier: the
+     * first observed `busy` is taken as the replacement turn's start. A wedged
+     * session never produces that `busy`, so without a bound the boundary latches
+     * forever and the topic hangs with nothing able to recover it.
+     */
+    private armProviderRetryReplacementStart;
+    /** Drop a pending replacement-start bound (teardown, or before re-arming). */
+    private clearProviderRetryReplacementStartTimer;
+    /**
+     * @description Resolve the replacement boundary: the flag and its bound are
+     * cleared together so the invariant "boundary disarmed ⇒ no pending timer"
+     * holds at every site, and a resolved boundary can never fire a late
+     * `noResponse` against a turn that did start.
+     */
+    private clearProviderRetryReplacementBoundary;
+    /**
+     * @description The single emit point for "the delivered prompt produced no
+     * turn". Both detectors watch the SAME prompt from different angles — the
+     * idle-time wedge check and the replacement-start bound — so every trigger is
+     * disarmed here before emitting, and one prompt can never reach the bot's
+     * recovery escalation twice.
+     */
+    private reportNoTurnResponse;
+    /**
+     * @description Bot-side fallback for naming an untitled session (R1 safety
+     * net). The primary mechanism is opencode's own LLM auto-title; this runs
+     * ONLY if that never lands.
+     *
+     * On the first MEANINGFUL prompt of an eligible (untitled, not-yet-renamed)
+     * session it clears the pending flag — so it tries at most once — then, after
+     * a grace period that lets auto-title land, reads the live title and PATCHes a
+     * snippet ONLY when the title is still the bare placeholder. The snippet
+     * derives from the RAW user text (preamble stripped) so it can never carry the
+     * thread-context header. Fire-and-forget; a failure leaves the placeholder.
+     */
+    private maybeScheduleFallbackRename;
+    sendSignal(key: SessionKey, signal: string): void;
+    /**
+     * @description Connect an OpenCode provider through the same API-key auth
+     * endpoint the OpenCode UI uses (`PUT /auth/{providerID}`). Providers with a
+     * custom auth entry must expose a one-field API method; ordinary providers
+     * (including OpenRouter) use the generic API-key method synthesized from the
+     * full `/provider` catalog.
+     */
+    connectProvider(_key: SessionKey, providerId: string, apiKey: string): Promise<string | null>;
+    /**
+     * @description Disconnect a provider through the same auth endpoint
+     * `/connect` writes to (`DELETE /auth/{providerID}`), then report what the
+     * delete actually achieved.
+     *
+     * `DELETE /auth` only clears OpenCode's own credential store. A provider
+     * OpenCode enables from an ENVIRONMENT VARIABLE (`openrouter` ←
+     * `OPENROUTER_API_KEY`) is still fully active afterwards, so we re-read
+     * `GET /config/providers` (caches dropped first, exactly like
+     * `connectProvider` does after a credential change) and hand the still-active
+     * provider ids to {@link getProviderDisconnectOutcome}. Claiming a clean
+     * disconnect there would be a lie — that case is what the bot-side "hide
+     * provider" toggle in `/model` exists for.
+     */
+    disconnectProvider(_key: SessionKey, providerId: string): Promise<string | null>;
+    private ensureProviderAuthServerReady;
+    /**
+     * @description Fetch a provider's auth methods for the `/connect` picker.
+     * Custom OAuth/multi-step methods come from `/provider/auth`; a provider that
+     * only appears in the full `/provider` catalog gets OpenCode's ordinary
+     * one-field API-key method. Throws on a server/transport error.
+     */
+    fetchProviderAuthMethods(providerId: string): Promise<OpenCodeAuthMethod[]>;
+    /**
+     * @description Set model override for the current session.
+     * Accepts either "provider/modelId" format or partial name to search.
+     * @returns Error message if model not found, null on success
+     */
+    setModel(key: SessionKey, modelId: string): Promise<string | null>;
+    /**
+     * @description Get list of available models from OpenCode CLI.
+     */
+    getAvailableModels(): Promise<string[]>;
+    getCurrentModel(key: SessionKey): string | null;
+    getRuntimeInfo(key: SessionKey): Promise<AgentRuntimeInfo>;
+    /**
+     * @description Fetch + cache the provider/variant config
+     * (`GET /config/providers`). 5-minute TTL — variant maps change about as
+     * often as the model list. The response is not logged because provider
+     * configuration can contain credentials.
+     */
+    private getProvidersConfig;
+    /**
+     * @description Variant names a `{providerID, modelID}` model exposes, or
+     * `[]` when the ref is incomplete or the model declares no variants.
+     *
+     * Takes a model ref (not a session) so the no-session `setModel` path can
+     * validate a freshly-picked model's variants before any session exists —
+     * `getAvailableEffortLevels` resolves the ref from the live session.
+     */
+    private getModelVariants;
+    /**
+     * @description Resolve the live session's current model into a
+     * `{providerID, modelID}` ref from the override (preferred) or the label.
+     */
+    private getSessionModelRef;
+    /**
+     * @description Seed the bot's default reasoning effort onto a freshly
+     * 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
+     * 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.
+     *
+     * Never persisted: the default stays a derived fallback, the prefs file
+     * remains "explicit choices only".
+     */
+    private applyDefaultEffortIfUnset;
+    /**
+     * @description Resolve the model the thread's effort applies to, WITHOUT
+     * requiring a live session — the prospective model the NEXT session will
+     * use. Priority mirrors `fetchModelInfo`'s resolution order so the
+     * pre-session effort surface lines up with what a started session would
+     * actually run:
+     *   1. live session's model ref (active session wins), else
+     *   2. the thread's saved `/model` pref (`loadSavedModel`), else
+     *   3. the OpenCode server's default model (`GET /config`
+     *      `defaultModel` / `model`).
+     * Returns `null` only when none of these yield a complete `{providerID,
+     * modelID}` ref, so `/effort` pre-session validates against the same model
+     * `/model` would persist.
+     */
+    private getProspectiveModelRef;
+    /**
+     * @description Effort levels the thread can use: exactly the variants its
+     * model declares. Works pre-session too — with no live session it resolves
+     * the PROSPECTIVE model (saved `/model` pref → server default) so the
+     * `/effort` picker can list the next session's variants before `/opencode`,
+     * mirroring how `/model` works pre-session. Empty when the (live or
+     * prospective) model declares no variants or can't be resolved.
+     */
+    getAvailableEffortLevels(key: SessionKey): Promise<string[]>;
+    getEffort(key: SessionKey): string | null;
+    /**
+     * @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.
+     *
+     * Mirrors `setModel`'s persist-first symmetry (no `'No active session'`
+     * hard-fail): a level picked BEFORE `/opencode` is saved and replayed by the
+     * next session, instead of being lost — same intent as the model pref.
+     */
+    setEffort(key: SessionKey, level: string): Promise<string | null>;
+    /**
+     * @description Human label for the model the thread's effort validates
+     * against — the live session's label when active, else the prospective
+     * model's `provider/model` — for the `effort.not_supported` notice. `'?'`
+     * only when no model can be resolved at all.
+     */
+    private getEffortModelLabel;
+    /**
+     * @description Manually rename the live session via `PATCH /session/:id
+     * { title }`, scoped to the session's owning project instance
+     * (`?directory=<workDir>`) so it hits the same instance the session was
+     * created in. Reuses {@link apiRequest} — no duplicate HTTP code.
+     *
+     * A manual rename is final: it clears `isAutoNamePending` so the bot-side
+     * auto-name fallback can never overwrite the user's title later (the
+     * fallback only fires while that flag is set — see
+     * {@link maybeScheduleFallbackRename}).
+     */
+    renameSession(key: SessionKey, title: string): Promise<string | null>;
+    /**
+     * @description Compact the live session's context via `POST /session/:id/
+     * summarize`, scoped to the session's owning project instance
+     * (`?directory=<workDir>`) so it hits the same instance the session was
+     * created in. Reuses {@link apiRequest} — no duplicate HTTP code.
+     *
+     * This is the REAL compaction path. `prompt_async` (the only other transport)
+     * does no slash-command parsing server-side, so forwarding the literal
+     * `/compact` text there just burned a model turn answering a two-word prompt
+     * — the bug this method fixes.
+     *
+     * `summarize` runs a summarisation turn, so it REQUIRES a complete model ref:
+     * the session's `modelOverride` (populated from the server default at session
+     * start) wins, else {@link getProspectiveModelRef} resolves it exactly the way
+     * `/effort` does (saved `/model` pref → server `defaultModel`). Unresolvable →
+     * a notice, never a partial/empty `providerID`/`modelID`.
+     *
+     * `auto` is deliberately omitted: this is a MANUAL compaction and the server
+     * defaults the flag to false (the automatic, overflow-triggered compaction is
+     * server-side and untouched by this).
+     */
+    compactContext(key: SessionKey, instruction?: string): Promise<CompactionResult>;
+    /**
+     * @description Whether this thread's directory instance loaded the bot's
+     * compaction plugin, read from its merged config (`GET /config`, directory
+     * scoped). An instance created before the plugin was installed lacks it until
+     * it is recreated, and then the bot must keep sending the skills guidance
+     * itself. A read failure answers `false`: the guidance then appears twice,
+     * which beats not at all.
+     */
+    checkHasCompactionSkillsHook(key: SessionKey): Promise<boolean>;
+    /**
+     * @description Read the newest compaction summary for the live session via
+     * `GET /session/:id/message` (directory-scoped) and lift its text out with the
+     * pure {@link getLatestOpenCodeCompactionSummary}. Used by F2 to surface the
+     * appended "Where we stopped" closing section in the idle-compaction notice. A
+     * read failure / no summary yields `null` (the notice then omits the block).
+     */
+    getLatestCompactionSummary(key: SessionKey): Promise<string | null>;
+    getOpenCodeSessionId(key: SessionKey): string | null;
+    getSessions(_key: SessionKey, workDir: string): Promise<AgentSession[]>;
+    /**
+     * @description Read the last `limit` conversational turns of a session for the
+     * resume context block via `GET /session/:id/message`. `key`/`workDir` are
+     * unused — OpenCode scopes messages by session id, server-side. Maps the raw
+     * records with the pure {@link mapOpenCodeMessagesToTurns}; a request failure
+     * yields `[]`, so the caller posts no context block.
+     */
+    getRecentTurns(_key: SessionKey, _workDir: string, sessionId: string, limit: number): Promise<RecentTurn[]>;
+    /**
+     * @description Assemble the silent-reattach recap for OpenCode: ONE
+     * `GET /session/:id/message` read serves both the missed-message count (since
+     * the watermark id) and the last-{@link resumeContextTurnLimit} turns. A read
+     * failure degrades to an empty, watermark-unknown recap (the caller posts
+     * nothing). The watermark only counts when its `sessionId` matches the session
+     * being recapped — a stale watermark from a different session (`/new`,
+     * `/sessions` resume keep the agent row) is treated as unknown. `isActive` is
+     * derived from the fetched records (last record = an unfinished assistant
+     * turn), never a blocking server probe.
+     */
+    getReattachRecap(_key: SessionKey, _workDir: string, sessionId: string, watermark: SeenWatermark | null): Promise<ReattachRecap>;
+    resumeSession(key: SessionKey, workDir: string, sessionId: string, options?: ResumeSessionOptions): Promise<void>;
+    /**
+     * @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
+     * recovery (tier 2) to restore the last dialog into a fresh, unwedged session
+     * before replaying the prompt — so a stuck session doesn't lose context. The
+     * new session's id is exposed via {@link getOpenCodeSessionId}, so the bot
+     * persists it with the shared `persistAdapterSessionIds`. Returns the new
+     * session id, or null when there is no active session or the fork failed.
+     */
+    forkSession(key: SessionKey): Promise<string | null>;
+    /**
+     * @description Detach any RUNNING sub-agent that is synchronously blocking the
+     * thread's session, so a new prompt can be answered while the sub-agent keeps
+     * working in the background (OpenCode injects its result back when it finishes).
+     * No-op (returns false) when the session is inactive or has no busy sub-agent.
+     * Needs the server started with `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`
+     * (the bot always sets it); if not enabled the endpoint 400s and we swallow it.
+     * Best-effort — a failure must never block the prompt that follows it.
+     */
+    detachRunningSubagents(key: SessionKey): Promise<boolean>;
+    private resumeSessionInner;
+    /**
+     * @description Best-effort hydration for an idle resumed session's context
+     * usage. A live SSE observation wins over this historical read even when the
+     * history request resolves later.
+     */
+    private hydrateLatestParentAssistantContext;
+    /** @description Wait for a bounded slot before fetching optional history metadata. */
+    private acquireRuntimeContextHydrationSlot;
+    /** @description Hand a completed metadata-read slot to the next queued session. */
+    private releaseRuntimeContextHydrationSlot;
+    /**
+     * @description Ensure the single global SSE stream is open and the session's
+     * directory has its scheduler MCP registered (plan 2026-06-17). Called after
+     * a session is inserted active into `this.sessions` (start / resume / restart).
+     * The stream is shared by ALL sessions, so it opens only for the FIRST active
+     * session anywhere; later calls reuse it. Scheduler-MCP registration is per
+     * directory (decoupled from the stream), gated to once per dir per server
+     * generation. Keeps the `(key)` signature so the lifecycle paths and tests
+     * (which stub `connectSse` / `pollSseStream`) are unchanged.
+     */
+    private connectSse;
+    /**
+     * Re-register active directories once the bot scheduler listener is ready,
+     * for sessions that connected while injection was still inert. Boot binds
+     * the listener before re-attaching sessions, so it does not call this.
+     */
+    registerSchedulerMcpForActiveSessions(): void;
+    /**
+     * @description Boot self-heal for the adopt path. When the bot restarts and
+     * ADOPTS an already-running opencode (the server outlived the bot), that
+     * server still holds the PREVIOUS bot generation's `telegramBot` registration
+     * pointing at a now-dead ephemeral port — so every session in the directory
+     * reports the MCP `failed` and loses its scheduling / file-send tools. For
+     * each active session's directory (de-duped — a folder can host several
+     * threads), read the LIVE `GET /mcp` status and, when the `telegramBot` entry
+     * is missing or not `connected`, drop the Set gate and force a fresh POST (the
+     * server overwrites a same-name registration with the current port). A dir
+     * already `connected` is left untouched. Best-effort per directory: a read /
+     * registration error is logged and swallowed — it must never throw out of
+     * boot. Supersedes {@link registerSchedulerMcpForActiveSessions} at the boot
+     * call site (a not-yet-registered dir has no entry → treated as needing one).
+     */
+    reconcileSchedulerMcpForActiveSessions(): Promise<void>;
+    /**
+     * @description Boot step that makes every active directory's instance load the
+     * bot's compaction plugin. OpenCode reads plugins once per directory instance,
+     * so an instance created before the plugin file existed (a server that outlived
+     * the bot, actagent's included) never gets it on its own. Installs the file,
+     * then per directory (de-duped, concurrently) recreates the instance when it
+     * lacks the plugin and nothing in it is running. A recreated directory loses
+     * its runtime `telegramBot` registration, so its Set gate is dropped here and
+     * the boot caller reconciles the MCP right after.
+     */
+    activateCompactionPluginForActiveSessions(): Promise<void>;
+    /**
+     * @description One directory of {@link activateCompactionPluginForActiveSessions}:
+     * read its instance's plugin list and session status, and recreate it
+     * (`POST /instance/dispose`) only when the plugin is missing and every session
+     * is idle. Best-effort — errors are logged and swallowed.
+     */
+    private activateCompactionPluginForDirectory;
+    /**
+     * @description Reconcile ONE directory: read the live `GET /mcp` status and,
+     * when `telegramBot` is missing or not `connected`, drop the Set gate and
+     * force a fresh POST. Best-effort — a read/registration error is logged,
+     * scheduled for a retry, and swallowed so it never rejects out of
+     * {@link reconcileSchedulerMcpForActiveSessions}.
+     */
+    private reconcileSchedulerMcpForDirectory;
+    /**
+     * @description Retry a failed scheduler-MCP registration for `directory` after
+     * the next pause of {@link schedulerMcpRetryDelaysMs}. The retry runs the
+     * reconcile rather than a bare POST: a registration that timed out may have
+     * landed after all, and then nothing needs sending. A retry already pending
+     * covers a second failure, and one that fires after the folder's last session
+     * ended does nothing.
+     */
+    private scheduleSchedulerMcpRetry;
+    /** @description Forget `directory`'s pending registration retry: it is registered now. */
+    private clearSchedulerMcpRetry;
+    /**
+     * @description Mark a session inactive and tear down the global SSE stream IFF
+     * it was the LAST active session anywhere. The stream is reference-counted by
+     * the TOTAL active-session count (recomputed from `this.sessions` so it can
+     * never drift): any other active session — in any folder — keeps it open.
+     *
+     * Order-independent: callers vary in whether they pre-set `isActive = false`
+     * (`stopSessionInner` does, before calling here), so the decision counts OTHER
+     * active sessions and treats this one as departing. `before = other + 1`,
+     * `after = other` → `close` exactly when no sibling keeps the stream alive.
+     */
+    private disconnectSse;
+    /**
+     * @description Total count of currently-active sessions, optionally excluding
+     * one key (the departing session in a teardown decision) — the reference count
+     * the single global stream's lifecycle keys on.
+     */
+    private countActiveSessions;
+    /**
+     * @description Open the single `/global/event` stream if it is not already
+     * open (plan 2026-06-17). Idempotent — a second active session finds the
+     * stream present and no-ops. The reader runs detached; a fatal start error
+     * surfaces to every active session so the user isn't left with a silently-dead
+     * session (audit S10 / #43).
+     */
+    private ensureGlobalStream;
+    /**
+     * @description Register the bot's scheduler MCP server for `directory`'s
+     * OpenCode instance via the runtime `POST /mcp?directory=` endpoint (plan
+     * 2026-06-17 S3). Idempotent on the server (re-POSTing the same `name`
+     * overwrites/no-ops) and gated by `registeredSchedulerMcpDirs` so it runs once
+     * per directory per server generation — `restartServer` clears the Set so a
+     * dir is re-registered after the server's MCP table is wiped. Inert until
+     * injection is configured — the builder returns `null` and this no-ops. A
+     * registration FAILURE is logged, scheduled for a retry, and swallowed:
+     * scheduling tools are an enhancement, the session must still start.
+     */
+    private registerSchedulerMcpForDirectory;
+    /**
+     * @description Tear down the global SSE stream: latch it closed, abort the
+     * in-flight reader (unblocks `reader.read()` immediately — audit S7 / #12),
+     * cancel its stall + reconnect timers, and drop the reference.
+     */
+    private closeGlobalStream;
+    /** Emit an event to every active session. */
+    private emitToAllActiveSessions;
+    /**
+     * @description Resolve model for the session. Priority:
+     * 1. Thread's saved preference (from previous /model selection)
+     * 2. OpenCode server's defaultModel (config.model -> model.json recent -> first provider)
+     * 3. "not set"
+     *
+     * `emitOutput` controls whether the resolved `Model: <label>` line is sent to
+     * the topic. A fresh `startSession` emits it (the user just opened the
+     * session); a `resumeSession` after a bot restart re-resolves the SAME model
+     * silently — the label is already in the topic from the previous run, so
+     * re-emitting on every hot-restart is noise (B17). Resolution must still run
+     * to repopulate `modelOverride`/`currentModelLabel` so `/effort` can read them.
+     */
+    private fetchModelInfo;
+    /**
+     * @description Fetch-based SSE reader for the single `/global/event` stream
+     * (plan 2026-06-17). OpenCode sends every event as a `data:` line with a JSON
+     * envelope `{ directory, payload: { type, properties } }`; this one stream
+     * multiplexes every project instance, so each line is parsed once here and
+     * routed by the envelope `directory` + `sessionID` to its owning session.
+     *
+     * On connection failure: checks if the server is alive, attempts a restart if
+     * dead, and retries forever with capped exponential backoff until reconnect
+     * succeeds — as long as the stream is still wanted (not closed).
+     */
+    private pollSseStream;
+    /**
+     * @description (Re)arm a stream's stall watchdog. OpenCode emits a
+     * `server.heartbeat` every ~10 s, so a live stream always delivers bytes
+     * within `sseStallTimeoutMs`; if none arrive the socket is silently dead
+     * (open TCP, no FIN/RST) and `reader.read()` would park forever. Aborting the
+     * controller unblocks the reader so `pollSseStream`'s catch path reconnects.
+     * Re-armed on every chunk, so heartbeats keep a healthy stream alive.
+     */
+    private armSseStallWatchdog;
+    /** Cancel a stream's stall watchdog if armed. Idempotent. */
+    private clearStreamStallTimer;
+    /**
+     * @description Handle reconnection for the single global stream with server
+     * health check, auto-restart, and exponential backoff. If the server is dead,
+     * attempts a restart before reconnecting. Never gives up while the stream is
+     * still wanted — reconnects until success — with backoff capped at
+     * `maxSseReconnectDelayMs`. The only exits are an unrestartable server
+     * (handled by `restartServer`) or a closed stream.
+     */
+    private handleSseReconnect;
+    /**
+     * @description Route a single raw SSE `data:` line from the global stream
+     * (plan 2026-06-17). The JSON is parsed ONCE here, the owning session is
+     * resolved from its sessionID/lineage (with an envelope-directory fallback),
+     * and the event is dispatched to that session. The owning project instance
+     * comes from the event ENVELOPE'S `directory` field — `/global/event` tags
+     * every session event with it — so instance-local replies
+     * (questions/permissions) target the right instance.
+     *
+     * Also the entry the SSE unit tests drive (a session injected into the map +
+     * synthesized payload-wrapped envelope), so the real parse→route→dispatch
+     * path is exercised end to end.
+     */
+    private routeSseData;
+    /**
+     * @description Resolve which thread (if any) should process `event`, applying
+     * the single-owner invariant (B20) and recording subagent lineage. Owner
+     * resolution is by sessionID (direct id, else lineage ancestor) with a
+     * DIRECTORY fallback off the event ENVELOPE'S `directory` when both miss
+     * (plan 2026-06-17). Returns:
+     *   - the owning thread's serialised key for a per-session event;
+     *   - `null` for a session-less event (`server.connected`/`heartbeat`) that
+     *     every reader handles directly;
+     *   - `undefined` to signal "do not dispatch" (missing sessionID, or no bound
+     *     thread owns the session — a genuine drop, loud-logged for every critical
+     *     type incl. question/permission, so a routable event is never a no-op).
+     *     Events for directories the bot does not own (the user's by-hand opencode
+     *     in other folders, now visible on the global stream) drop here cheaply.
+     */
+    private resolveSseEventOwner;
+    /**
+     * @description Handle a session-less event (`server.connected` /
+     * `server.heartbeat`) — server-wide by design, with no owning topic. Kept
+     * separate from {@link dispatchSseEvent} so the latter always has a real
+     * owner key.
+     */
+    private dispatchSessionLessEvent;
+    /**
+     * @description Dispatch a normalised, OWNED SSE event to its owning session's
+     * handlers. `key` is the resolved single owner (B20); `directory` is the
+     * owning project instance (the event envelope's `directory`), used for
+     * instance-scoped question / permission replies.
+     */
+    private dispatchSseEvent;
+    private getSessionIdFromEvent;
+    /**
+     * @description Record a child→parent session link from ANY event that exposes
+     * `parentID`, so subagent (child-session) events route to the topic bound to
+     * the parent. Reliably populated by `session.updated` (its `info` carries the
+     * child id + `parentID`); also reads a top-level `properties.parentID`
+     * (paired with the event's session id) when a build emits it on other events,
+     * so a child's link is known BEFORE its first routed event instead of dropping
+     * "no owner" until the next `session.updated` beat (S2 durability). Root
+     * sessions (no `parentID`) and non-session ids are ignored by
+     * {@link updateSessionLineage}; the map is bounded by
+     * `maxTrackedSessionLineageEntries`.
+     */
+    private trackSessionLineage;
+    /** @description Store one child→parent link and diag-log it when it is new. */
+    private recordSessionLineageLink;
+    /**
+     * @description Tear down any OTHER active thread already bound to
+     * `sessionId` before `keyStr` adopts it (B20 prevention). One server-side
+     * OpenCode session belongs to exactly one thread; if two threads held the
+     * same id (e.g. resuming a session already live in another topic), the
+     * server's multiplexed events would match BOTH and the same answer would
+     * land in two topics. Detaching the stale owner keeps the single-owner
+     * invariant true at the source, not just in dispatch.
+     */
+    private detachDuplicateSessionOwners;
+    /**
+     * @description Tear down a thread's local session tracking WITHOUT aborting
+     * the server-side session. Used when another thread is adopting the same
+     * server session (B20 prevention) — a normal `stopSessionInner` would abort
+     * the shared generation. Mirrors `stopSessionInner` minus the abort POST.
+     */
+    private softDetachSession;
+    /**
+     * @description Resolve the SINGLE active thread that owns an SSE event for
+     * `eventSessionId` (single-owner delivery, B20). Direct session-id match wins
+     * over lineage descent; ties resolve deterministically. Returns the owning
+     * thread's serialised key, or `null` if no active thread owns it.
+     *
+     * `refreshLineageOnUse` marks the lineage links walked to reach the owner as
+     * most-recently-used, so an actively-routing child can never be the eviction
+     * victim of the bounded lineage map (S2 durability) — only set on the live
+     * routing path, never when merely probing.
+     */
+    private resolveEventOwnerKey;
+    /** @description Every currently-active session as a routing `BoundSessionRef`. */
+    private getActiveBoundSessions;
+    /**
+     * @description Directory fallback (plan 2026-06-17): resolve an owner from the
+     * event envelope's `directory` when id/lineage resolution already failed.
+     * `/global/event` tags every session event with its owning folder, so an event
+     * provably belongs to a thread bound to that folder — and an event for a
+     * directory with no active bound session (the user's by-hand opencode
+     * elsewhere) resolves to `null` and is dropped. SYNC — uses only in-memory
+     * session state, NEVER an HTTP call on the per-event hot path. Delegates the
+     * decision to the pure {@link resolveOwnerByDirectoryFallbackPure}; the wiring
+     * here is just selecting the directory's active sessions.
+     */
+    private resolveOwnerByDirectoryFallback;
+    /**
+     * @description Diag-log one "sse drop" line for an event no thread owns,
+     * throttled to at most once per (eventType, eventSessionId) per
+     * `sseDropLogThrottleMs`. Without throttling an orphaned session's delta
+     * firehose floods the diag log — once per delta per bound thread (B19).
+     */
+    private logSseDropOncePerWindow;
+    /**
+     * @description Handle streaming part updates from assistant response.
+     * Two event formats:
+     *   message.part.updated: { part: OpenCodePart, delta?: string }
+     *   message.part.delta:   { sessionID, messageID, partID, field, delta }
+     *
+     * Text parts are accumulated and emitted as 'output' (permanent messages).
+     * Tool, reasoning, step-* parts are emitted as 'status' (transient messages).
+     *
+     * `isSubagent` (resolved ONCE in `dispatchSseEvent`) marks parts streamed by
+     * a CHILD session (sub-agent); they are routed per the
+     * {@link getSubagentPartAction} matrix instead of the parent's handlers, so
+     * a child transcript can never merge unmarked into the parent's reply (S4).
+     */
+    private handlePartUpdate;
+    /**
+     * @description Handle text delta — accumulate and emit as 'output'. Text of the
+     * compaction summary message marks the accumulated response as that summary.
+     */
+    private handleTextDelta;
+    /**
+     * @description Emit only the part of `currentResponseText` not yet sent as
+     * an `output` event, then advance `lastEmittedLength`. The bot does not
+     * delta-render OpenCode output (`outputsDeltas` is unset), so each emit is a
+     * raw tail of the in-flight response — possibly cut mid-word.
+     *
+     * Every tail except the FIRST of a response carries `isContinuation: true`
+     * (a {@link OutboundHints}). The bot appends a continuation tail to the
+     * same growing Telegram message instead of starting a new one, so the long
+     * reply reads as one message rather than each edit replacing the previous
+     * text. `lastEmittedLength === 0` means this is the first tail of a fresh
+     * response (nothing emitted yet), so it is NOT a continuation. `flushOutput`
+     * resets `lastEmittedLength` to 0 after the final tail, so the next response
+     * again starts with a non-continuation first tail.
+     */
+    private emitResponseTail;
+    /**
+     * @description Handle a SUB-AGENT (child session) text part per the
+     * mode×kind matrix ({@link getSubagentPartAction}):
+     *
+     * - `compact` → never touch any accumulator; signal the dedicated
+     *   `subagentStatus` event instead (the bot owns a single self-updating
+     *   "🤖 sub-agent: <title> · m:ss" message + elapsed timer). This replaced
+     *   the old shared-status refresh, whose lost single-message identity between
+     *   sparse bursts re-`sendMessage`d a new message each time (the flood bug).
+     * - `full` → accumulate into the SEPARATE child accumulator and flush via
+     *   the same debounce discipline as {@link handleTextDelta} — never through
+     *   `currentResponseText` (a child transcript in the parent accumulator
+     *   would corrupt the parent reply's continuation accounting).
+     */
+    private handleSubagentTextPart;
+    /**
+     * @description Emit the unsent tail of the CHILD (sub-agent) accumulator as
+     * a marked `output` event (`meta.isSubagent`, `/subagent full` mode only).
+     * Mirrors {@link emitResponseTail} over the dedicated child fields so the
+     * parent's emit cursor is never advanced by child text. Carries NO
+     * `isContinuation`: the bot renders every sub-agent chunk as its own marked
+     * message outside the parent's edit-in-place chain (acceptable v1 — `full`
+     * is opt-in). The empty-string guard doubles as runtime tolerance for test
+     * fixtures that inject minimal session shapes.
+     */
+    private emitChildResponseTail;
+    /**
+     * @description Is this part the delegation (`task`) tool still in flight
+     * (pending/running)? Drives both the delegation-title tracking and the
+     * dedicated "🤖 Delegating: <title> …" activity status (S5) — once the
+     * delegation completes/errors the generic ✅/❌ status forms take over.
+     */
+    private checkIsDelegationInFlight;
+    /**
+     * @description Read the delegation's title off a `task` tool part's state:
+     * the explicit `title` when present, else the prompt `description` from the
+     * tool input. `null` when the part carries neither (the status builders fall
+     * back to a localized generic label).
+     */
+    private getDelegationTitle;
+    /**
+     * @description Record / clear the CURRENT delegation's title from the
+     * PARENT's `task` tool part: stored while the delegation is pending/running
+     * (feeds the dedicated sub-agent status message; S5's "Delegating" activity
+     * status reuses this field), cleared once it completes/errors. Only ever
+     * called for the parent's own parts — a child's nested `task` must not
+     * overwrite the parent-level title.
+     *
+     * The title is STICKY (D2 fix): while in-flight we only OVERWRITE it with a
+     * non-null title — a beat where the `task` part momentarily lacks
+     * title/description leaves the last known title intact, instead of clobbering
+     * it to `null` mid-run (which made the line read "sub-agent: sub-agent").
+     * It is cleared to `null` only on the terminal (completed/error) part.
+     */
+    private trackDelegationTitle;
+    /**
+     * @description Handle tool part — format and emit as 'status'.
+     */
+    private handleToolPart;
+    /**
+     * @description Emit the dedicated MODE-AGNOSTIC `toolResult` event once a
+     * tool part reaches `completed` with a non-empty output (S3). The bot
+     * resolves the per-thread tool-results mode (`minimal` drops it there) — the
+     * adapter emits every result exactly once, guarded by
+     * {@link OpenCodeSession.emittedToolResultPartIds} against the re-sent part
+     * shapes. The output is kept strictly OUT of `currentResponseText` so it can
+     * never pollute the answer or its continuation accounting.
+     */
+    private maybeEmitToolResult;
+    /** Debounce delay (ms) for live `thinking` emits — the reasoning delta
+     * stream is chatty, so live frames are coalesced like text deltas. */
+    private static readonly reasoningLiveEmitMs;
+    /**
+     * @description Handle a reasoning (chain-of-thought) part.
+     *
+     * Reasoning text is accumulated into {@link OpenCodeSession.reasoningText}
+     * — kept STRICTLY separate from `currentResponseText` so it never leaks into
+     * the answer — and surfaced through the DEDICATED `thinking` event (not the
+     * generic `status` coalescer), so the thinking indicator can persist
+     * independently of tool status. The adapter stays MODE-AGNOSTIC: it emits the
+     * raw accumulated text + phase, and the bot applies the per-thread mode.
+     *
+     * On the FIRST reasoning delta of a response we record `reasoningStartedAt`
+     * (drives the "thought for {N}s" duration on the eventual `done` emit). Live
+     * emits are debounced.
+     */
+    private handleReasoningPart;
+    /**
+     * @description Emit the `thinking` event for the current phase. `live` carries
+     * the accumulated reasoning text so far; `done` adds the elapsed `durationMs`.
+     */
+    private emitThinking;
+    /**
+     * @description End the current response's reasoning stream, if one is active.
+     * Flushes any pending live frame, emits the `thinking` `done` event (so the
+     * bot can collapse / persist per mode), and resets the per-response reasoning
+     * accumulator. Idempotent — a no-op when no reasoning is in flight, so it can
+     * be called from every "reasoning end" signal (first non-reasoning part,
+     * `message.updated` finish, `session.idle`) without double-emitting.
+     */
+    private endReasoning;
+    /** Debounce delay (ms) for status updates to avoid Telegram rate limits */
+    private static readonly statusDebounceMs;
+    /**
+     * @description Debounced emit of 'status' event.
+     * Rapid status updates (e.g. multiple tool state changes) are batched —
+     * only the latest status text is emitted after a quiet period.
+     */
+    private emitStatus;
+    /**
+     * @description Handle message completion.
+     * Event properties: { info: OpenCodeMessageInfo }
+     */
+    private handleMessageUpdate;
+    /**
+     * @description Handle session becoming idle (AI done processing).
+     * Flush any remaining accumulated output.
+     */
+    private handleSessionIdle;
+    /**
+     * @description Track live busy/idle/retry from `session.status`. The own
+     * session's status drives {@link OpenCodeSession.isBusy}; provider-managed
+     * retry remains busy and is surfaced once, because OpenCode otherwise accepts
+     * later prompts into an unread queue with no user-visible explanation. A
+     * lineage-verified child
+     * (sub-agent) status maintains {@link OpenCodeSession.busyChildSessionIds}
+     * so a new prompt never aborts a running sub-agent. A foreign non-descendant
+     * session's busy=true (dir-fallback-routed wedged sibling) is ignored —
+     * see {@link applyOpenCodeStatusEvent}.
+     */
+    private handleSessionStatus;
+    /**
+     * @description Strict-descendant verification for busy tracking: `true` only
+     * when `eventSessionId` walks up the lineage map to `ownSessionId` — never
+     * for the own id itself or a foreign sibling. Distinct from
+     * {@link checkIsEventForSession} (own-or-descendant), which routing uses.
+     */
+    private checkIsVerifiedDescendant;
+    /**
+     * @description Diag-log one "busy-ignored" line for a foreign non-descendant
+     * busy=true that busy tracking refused to record, throttled per session id
+     * like {@link logSseDropOncePerWindow} — a wedged sibling re-emits
+     * `session.status` every ~30 s and would otherwise flood the diag log.
+     */
+    private logForeignBusyIgnoredOncePerWindow;
+    /**
+     * @description Flip the compaction flag from `session.next.compaction.*` /
+     * `session.compacted` events. While set, a new prompt queues instead of
+     * aborting (an abort would discard the in-progress summary).
+     */
+    private setCompacting;
+    private handleSessionError;
+    private handlePermissionAsked;
+    /**
+     * @description Handle question.asked events from OpenCode.
+     * Stores the pending question and emits a 'question' event so the bot
+     * can display it to the user with interactive buttons.
+     *
+     * Event properties: { id, sessionID, questions: QuestionInfo[], tool? }
+     */
+    private handleQuestionAsked;
+    /**
+     * @description Re-surface a question that was still open on the server when
+     * the bot lost track of it — the reattach/resume path rebuilds the session
+     * with `pendingQuestion: null`, so after ANY bot restart an unanswered
+     * question would otherwise be forgotten and the topic hangs forever (the
+     * break-out that turns a user message into the ANSWER never fires, and a
+     * fresh prompt just queues behind the still-blocked turn).
+     *
+     * `GET /question?directory=<workDir>` returns the instance's live open
+     * questions; we pick the entry owned by this session, rebuild
+     * `session.pendingQuestion`, and emit `question` so the existing bot handler
+     * re-posts the option buttons and repopulates (and persists) its pending map.
+     * Reply id is the entry's top-level `id` (`que_…`), resolved by the pure
+     * {@link getOpenQuestionForSession} helper.
+     *
+     * Best-effort: a read/parse failure is logged and swallowed — it must never
+     * throw out of reattach. Only meaningful on the resume/reattach path; a
+     * brand-new session (startSession) has no history and thus no open question,
+     * so it is deliberately NOT called there.
+     */
+    private restoreOpenQuestion;
+    /**
+     * @description Backstop predicate (G2): is this session's turn wedged behind
+     * an open interactive question? The authoritative signal is the server's own
+     * `GET /question?directory=<workDir>` returning an entry for this session —
+     * a turn that is merely streaming text / running a normal tool / has a live
+     * sub-agent has NO open question, so it is never reported wedged (no
+     * regression: an arriving prompt still queues-and-is-picked-up for a healthy
+     * busy turn). The bot consults this only when a fresh prompt would otherwise
+     * queue behind a busy session with no known pending question; on `true` it
+     * aborts the dead turn before forwarding instead of queueing forever.
+     *
+     * Best-effort: a read/parse failure returns `false` (don't abort on doubt).
+     */
+    checkIsWedgedOnQuestion(key: SessionKey): Promise<boolean>;
+    /**
+     * @description Reply to a pending question with user-selected answers.
+     * Called by the bot when the user clicks an inline button or types a custom answer.
+     */
+    answerQuestion(key: SessionKey, answers: string[][]): void;
+    /**
+     * @description Reject a pending question server-side WITHOUT answering it —
+     * called when the user ABANDONS the question (sends a fresh prompt instead of
+     * answering, or the session is torn down while it is pending). Mirrors
+     * {@link answerQuestion} but POSTs to `/question/:id/reject` (empty body)
+     * instead of `/reply`. Without it the question stays "open" in the server's
+     * registry and {@link restoreOpenQuestion} re-surfaces it on every reattach.
+     * No-op if no active session / no pending question.
+     */
+    rejectQuestion(key: SessionKey): void;
+    private flushOutput;
+    /**
+     * @description Defensive close of the dedicated sub-agent status when the
+     * PARENT's own turn ends (its assistant message finishes, or its session goes
+     * idle) so a dangling "working" indicator can't outlive the turn if the
+     * terminal `task` part was missed. Strictly parent-only: a CHILD (sub-agent)
+     * message finishing / going idle must NOT close it — the delegation is still
+     * in flight (its child events route here via lineage). The bot no-ops the
+     * close when nothing is open.
+     */
+    private closeSubagentStatusOnParentTurnEnd;
+}
+//# sourceMappingURL=openCodeAdapter.d.ts.map