charness 0.0.0-stage → 3.0.0

package/dist/state.d.ts

@@ -0,0 +1,1245 @@
+import * as fs from 'fs';
+import { type ApiRetryState, type JsonStreamTailOffset, type LimitEpisodeMarker, type PendingQuestionState, type ResolvedThreadDisplayPrefs, type SeenWatermark, type ThreadDisplayPrefs } from './types';
+import { type SessionKey } from './sessionKey';
+import type { ScheduleRecord } from './scheduler/types';
+import type { OpenRequestState, UnreleasedRequestAlert } from './requests/types';
+import { type RequestGroupKey } from './requests/requestGroup';
+import type { Locale } from './i18n';
+import type { LimitHeldPrompt } from './utils/limitHeldPrompts';
+/**
+ * @description On-disk state for the multi-thread telegram bot.
+ *
+ * Replaces the legacy `~/.telegram-bot-messages.json` (which only persisted
+ * `messageIds` per user) with a richer per-`SessionKey` schema:
+ *
+ *   - `bindings[key]`  → thread is attached to a subdir under `WORK_ROOT`
+ *   - `agents[key]`    → which adapter the thread is using, model, session ids
+ *   - `messages[key]`  → message ids tracked by `/clear`
+ *
+ * Schema source: plan §9. Field additions for D14 (`claudeSessionId`), §13.19
+ * (`opencodeSessionId`) and D49 (`bindings[key].closed`) are inlined here.
+ *
+ * The file is rewritten atomically (`writeFile(tmp) → fsync(fd) → rename →
+ * fsync(parentDir)`, plan §13.14, T4). Concurrent mutations to the same
+ * `SessionKey` are serialised by a per-key async lock (plan §13.15, E3).
+ *
+ * **This module is intentionally NOT yet imported from `bot.ts`.** Plan §11
+ * Этап 2 wires state in only on the following commit (Этап 3) — keeping the
+ * landing surgical.
+ */
+/** Current schema version stamped into `state.json`. Bump on breaking layout changes. */
+export declare const STATE_SCHEMA_VERSION = 1;
+export interface BindingData {
+    /** Subdirectory under `WORK_ROOT` this thread is attached to. */
+    subdir: string;
+    /** ISO timestamp the binding was first created. */
+    createdAt: string;
+    /**
+     * Whether the forum topic is currently marked closed in Telegram.
+     * Toggled by `forum_topic_closed` / `forum_topic_reopened` events
+     * (plan §13.10, D49). Closed binding is preserved on purpose — closing
+     * is reversible, deletion isn't.
+     */
+    closed?: boolean;
+    /**
+     * Telegram message id of the per-thread pinned status banner, if any.
+     * Set on first `/bind`, edited on every agent state change, unpinned +
+     * cleared on `/unbind`. Plan §11 Этап 7 / §20.5 / D52 area. Persisting
+     * the id lets a bot restart re-find the pinned message instead of
+     * pinning a fresh banner above it (which Telegram allows, producing a
+     * stack of stale pins).
+     */
+    pinnedStatusMessageId?: number;
+    /**
+     * Last banner text we successfully sent/edited for {@link pinnedStatusMessageId}.
+     * The in-memory `pinnedStatusTextCache` is rebuilt from this at boot so the
+     * startup banner-refresh wave skips the `editMessageText` round-trip when the
+     * computed banner equals what is already displayed (B8) — every restart
+     * otherwise re-edits ~9 identical banners, each a wasted "message is not
+     * modified" 400 burning the chat-wide send budget. Cleared whenever the
+     * banner message is unpinned/deleted or its id is nulled, so a stale text
+     * can never suppress a needed edit for a fresh banner message.
+     */
+    pinnedStatusText?: string;
+    /**
+     * Forum-topic display name, when known. The Bot API can't query a topic
+     * title on demand — the bot only learns it from events (`forum_topic_created`
+     * / `forum_topic_edited`) or when it creates the topic itself (`/new`).
+     * Persisted so the thread-context preamble (see `threadContextPreamble.ts`)
+     * can tell the agent which topic it works in across restarts. Absent for
+     * pre-existing topics until a rename event reveals the name.
+     */
+    topicName?: string;
+}
+export interface AgentData {
+    /** Adapter name, e.g. `'claude'` or `'opencode'`. */
+    name: string;
+    /** Optional model override (e.g. `'sonnet'`, `'anthropic/claude-3-5-sonnet'`). */
+    model?: string;
+    /**
+     * UUID we pass via `claude --session-id <uuid>` on a fresh start and via
+     * `claude --resume <uuid>` on later attaches (plan §13.1, D14). Lets two
+     * threads share one `workDir` without their histories cross-contaminating.
+     */
+    claudeSessionId?: string;
+    /**
+     * Server-assigned OpenCode session id. Used to re-attach the SSE stream
+     * after a bot restart (plan §13.19).
+     */
+    opencodeSessionId?: string;
+    /**
+     * Per-thread "seen" watermark advanced at each turn end (see
+     * {@link SeenWatermark}). Lets a bot restart compute how much output the agent
+     * produced WHILE the bot was down and recover it via the reattach recap,
+     * instead of silently dropping it. Optional so older state files stay valid —
+     * a missing value means "watermark unknown" → the recap uses its fallback
+     * (no-count) path. Backend-specific representation; only one sub-field is set.
+     */
+    seenWatermark?: SeenWatermark;
+    /**
+     * The digest of the bot-MCP tool definitions the json-stream process was
+     * started with (`SchedulerMcpHandle.getToolDigest`). Compared at adopt after a
+     * bot restart: a process whose tools are stale is stopped at its next idle
+     * point and resumed with the current ones (lifecycle plan L4). Absent for a
+     * row written before the digest was tracked — read as stale.
+     */
+    mcpToolDigest?: string;
+    /**
+     * json-stream stdout tail position (line-boundary byte offset into the
+     * external session's `stdout.jsonl`), advanced as the tail consumes lines.
+     * Lets a restarted bot resume the surviving process's output exactly where
+     * processing stopped and replay only the downtime gap (plan
+     * 2026-07-05-jsonstream-restart-isolation). Optional so older state files
+     * stay valid — a missing value seeds the adopt tail to the current EOF.
+     * Cleared together with the session ids on explicit release.
+     */
+    jsonStreamTail?: JsonStreamTailOffset;
+    /**
+     * When THIS thread's current agent session began, as a local-offset ISO
+     * string (`2026-06-27T19:42:10+04:00`, same shape `/timestamps` uses — never
+     * `Z`). Set to "now" on a FRESH start (`startAgentSession`) and on a
+     * `/sessions` resume PICK (when the thread began using that session — the
+     * original transcript creation time isn't cheaply recoverable). PRESERVED
+     * across a bot restart (reattach never overwrites an existing value; only
+     * backfills a missing one, e.g. an older state file) and across an adapter
+     * switch (`/claude_mode`, same conversation). Cleared together with the
+     * session ids on explicit release (`/quit`, `/new`, `/unbind`). Surfaced by
+     * `/status`. Optional so older state files stay valid.
+     */
+    startedAt?: string;
+}
+/**
+ * Per-thread compact-on-idle bookkeeping (F2), persisted so a bot restart does
+ * not erase the evidence the idle watchdog reasons about. The three instants are
+ * epoch ms; each is optional and reads back as `0` when absent, so a state file
+ * written before this existed behaves exactly like an untracked thread.
+ *
+ * The entry is bound to the agent SESSION it describes (`sessionId`), not merely
+ * to the thread: the instants mean "THIS session has had a turn since ITS last
+ * compaction", so the moment the thread's session is replaced (`/new`, `/quit`
+ * then start, a backend switch to a different agent, a `/sessions` resume of an
+ * older session) the old marker is meaningless and must read as the initial state.
+ * Teardown DOES clear the entry, but that depends on a `stopped`/`closed` event
+ * actually firing — a killed or crashed process, or any future path that swaps a
+ * session without it, would silently inherit the previous session's marker.
+ * Keying on the session id makes the reset self-enforcing regardless of which
+ * lifecycle events fired. Deliberate consequence: `/claude_mode` switches the
+ * Claude backend by RESUMING the same conversation and keeps `claudeSessionId`, so
+ * the marker survives that switch — correct, since the context really is the same
+ * and really does have something to compress.
+ *
+ *  - `lastActivityAt`  — last REAL activity (user message, command, forwarded
+ *    prompt, agent output). The countdown is armed from this, so a restart
+ *    continues where it left off instead of re-arming a flat 55 minutes.
+ *  - `lastTurnEndAt`   — last agent turn that produced output, i.e. the proof
+ *    there is something to compress.
+ *  - `lastCompactionAt` — last compaction of this thread (any trigger: manual
+ *    `/compact`, the F1 tool, or an F2 idle fire).
+ *
+ * The fire guard is `lastTurnEndAt > lastCompactionAt`, which used to live in a
+ * process-local map: after a restart both were `0`, the comparison was false, and
+ * (there being no reschedule by D2) the feature stayed dead in every quiet topic
+ * until the operator wrote there.
+ */
+export interface CompactIdleTrackingEntry {
+    /**
+     * The agent session these instants describe (`claudeSessionId` /
+     * `opencodeSessionId` of the thread's {@link AgentData} at stamping time). A
+     * read whose current session id differs — or is unknown — yields all zeros.
+     */
+    sessionId?: string;
+    lastActivityAt?: number;
+    lastTurnEndAt?: number;
+    lastCompactionAt?: number;
+}
+/**
+ * Coarse step (ms) the activity/turn stamps must move past the last PERSISTED
+ * value before a save is scheduled. Load-bearing for cost, not correctness:
+ * those two stamps are written on EVERY agent output chunk, and `state.json` is
+ * rewritten WHOLE (atomically, with fsync) per save — so a `scheduleSave()` per
+ * chunk would turn a streaming turn into a debounced disk-rewrite loop. A
+ * 60-second granularity is irrelevant against the 55-minute idle threshold.
+ */
+export declare const compactIdleTrackingPersistStepMs = 60000;
+export interface StateV1 {
+    version: number;
+    bindings: Record<string, BindingData>;
+    agents: Record<string, AgentData>;
+    messages: Record<string, number[]>;
+    /**
+     * Numeric chat id of the forum supergroup discovered via auto-pairing,
+     * persisted so the operator doesn't have to look up the `-100…` id by
+     * hand. Only consulted when `ALLOWED_GROUP_ID` env is unset; a numeric
+     * env value always wins and disables pairing.
+     */
+    pairedGroupId?: number;
+    /**
+     * Epoch milliseconds of the last successful heartbeat write — the bot
+     * stamps this every ~10s while running. On boot we compare `now -
+     * lastHeartbeatAt` against {@link HOT_RELOAD_THRESHOLD_MS}: small gaps
+     * are a hot reload (quiet reattach, keep buffered updates), large gaps
+     * (or `undefined` for fresh installs / older state files) are a cold
+     * start (allow the per-thread reattach ERROR notice — workDir vanished —
+     * optionally drop the stale update backlog).
+     *
+     * Optional so old `state.json` files (created before heartbeats existed)
+     * remain valid — `loadStateFile`'s shape check doesn't require it, and
+     * a missing value is interpreted as "treat as cold start", which is the
+     * conservative default we want.
+     */
+    lastHeartbeatAt?: number;
+    /**
+     * Output-trace toggle (`/trace`). `tracedThreads` holds the {@link SessionKey}
+     * strings explicitly opted into tracing; `traceAllThreads` traces every
+     * thread (cross-thread forensics). Persisted so the toggle survives a hot
+     * rebuild mid-debug — the writer state in `outputTrace.ts` is re-seeded from
+     * these at boot. `traceAllThreads` defaults to ON when absent (always-on
+     * observability); it is stored EXPLICITLY (incl. `false`) so a `/trace off
+     * all` is durable and not re-enabled by the default on the next boot.
+     * Lifecycle-independent: only `/trace` mutates them, never session teardown.
+     */
+    tracedThreads?: string[];
+    traceAllThreads?: boolean;
+    /**
+     * Explicit `/language` overrides, keyed by Telegram chat id (DM chat or whole
+     * forum supergroup). These beat Telegram's `from.language_code` until changed
+     * or reset to auto. Optional so older state files stay valid.
+     */
+    chatLocaleOverrides?: Record<string, Locale>;
+    /**
+     * Last supported Telegram client language seen in each chat, keyed by chat id.
+     * Used for bot-originated async events (agent output, scheduled runs) where no
+     * live Telegram update carries `from.language_code`. Optional for old state.
+     */
+    chatTelegramLocales?: Record<string, Locale>;
+    /**
+     * Threads with the `/timestamps` prompt-injection toggle ON (default OFF —
+     * absent list means no thread injects). When ON, every forwarded prompt gets
+     * the send-time prepended as a local-offset ISO top line (agent-facing only,
+     * never posted to the topic). Same persistence shape as `tracedThreads`
+     * (deduped/sorted {@link SessionKey} strings, dropped when empty) and equally
+     * lifecycle-independent: only `/timestamps` mutates it, never session
+     * teardown. Optional so older state files stay valid.
+     */
+    timestampThreads?: string[];
+    /**
+     * The operator's timezone, GLOBAL for the whole bot instance (not per-chat —
+     * the mechanism is `process.env.TZ`, which is process-global by nature). Holds
+     * either an IANA name (`Europe/Moscow`) or a fixed offset (`+04:00`), as
+     * written by `/timezone`. Absent means "use the host zone", so an install that
+     * never ran `/timezone` behaves exactly as it did before the setting existed —
+     * which is why the field is optional rather than defaulted on disk.
+     * Lifecycle-independent: only `/timezone` mutates it, never session teardown.
+     */
+    timezone?: string;
+    /**
+     * Providers the operator hid from the `/model` picker, GLOBAL for the whole
+     * bot instance (not per-topic). The only lever that works for a provider
+     * OpenCode enables from an environment variable (`openrouter` ←
+     * `OPENROUTER_API_KEY`), which `DELETE /auth/:id` cannot remove. Hiding
+     * filters the PICKER only — an explicit `/model <provider/model>` still
+     * resolves a hidden provider, so a saved model pref never breaks. Same
+     * persistence shape as `tracedThreads` (deduped/sorted, dropped when empty)
+     * and equally lifecycle-independent: only `/model` mutates it, never session
+     * teardown. Optional so older state files stay valid.
+     */
+    hiddenModelProviders?: string[];
+    /**
+     * Compact-on-idle toggle (`/compact_on_idle`). `compactOnIdleEnabled` is the
+     * INSTANCE-WIDE default, driven from the General topic; absent ⇒ ON (the
+     * feature ships enabled, mirroring `traceAllThreads`), stored EXPLICITLY (incl.
+     * `false`) so a General «Disable» is durable and not re-enabled by the default
+     * on the next boot. `compactOnIdleOverrides` holds per-thread explicit
+     * overrides keyed by {@link SessionKey} string — a present entry (true OR false)
+     * wins over the global default; absent ⇒ follow the default. Both optional so
+     * older state files stay valid; lifecycle-independent (only `/compact_on_idle`
+     * mutates them, never session teardown).
+     */
+    compactOnIdleEnabled?: boolean;
+    compactOnIdleOverrides?: Record<string, boolean>;
+    /**
+     * Full-compaction-summary toggle (`/compact_summary`). Same shape and discipline
+     * as the `compactOnIdle*` pair above: `compactSummaryEnabled` is the
+     * INSTANCE-WIDE default driven from General (absent ⇒ OFF — the operator wants a
+     * compaction to end in one short line; stored EXPLICITLY incl. `false` so a General
+     * choice is durable), and `compactSummaryOverrides` holds per-thread explicit
+     * overrides keyed by {@link SessionKey} string, a present entry winning over the
+     * default. Both optional so older state files stay valid; lifecycle-independent
+     * (only `/compact_summary` mutates them, never session teardown).
+     */
+    compactSummaryEnabled?: boolean;
+    compactSummaryOverrides?: Record<string, boolean>;
+    /**
+     * Threads whose compact-on-idle user-LATCH is spent (D2). A thread lands here
+     * the instant an idle-compaction FIRES and is removed only by the next genuine
+     * USER message — so idle compaction runs at most once per user-active period,
+     * and (crucially) a bot restart cannot re-enable a second fire: the reattach
+     * re-arms the idle timer ONLY for threads absent from this set. Same
+     * deduped/sorted {@link SessionKey}-string shape as `timestampThreads` (dropped
+     * when empty), and equally lifecycle-independent — only a fire and a user
+     * message mutate it, never session teardown. Optional so older state files stay
+     * valid (a missing value = no thread latched).
+     */
+    compactIdleLatchedThreads?: string[];
+    /**
+     * Per-thread compact-on-idle bookkeeping keyed by {@link SessionKey} string —
+     * the idle COUNTDOWN's restart guard (see {@link CompactIdleTrackingEntry} for
+     * the three instants and why losing them disabled the feature after every
+     * restart). Entries are dropped on session teardown (a fresh session must get
+     * the full window) and the whole map is dropped once empty, so an idle bot
+     * leaves a clean `state.json`. Optional so older state files stay valid.
+     */
+    compactIdleTracking?: Record<string, CompactIdleTrackingEntry>;
+    /**
+     * Limit auto-continue toggle (`/auto_continue_limits`). `autoContinueOnLimitEnabled` is
+     * the INSTANCE-WIDE default, driven from the General topic; absent ⇒ ON (the
+     * behaviour was unconditional before the toggle existed), stored EXPLICITLY
+     * (incl. `false`) so a General «Disable» is durable and not re-enabled by the
+     * default on the next boot. `autoContinueOnLimitOverrides` holds per-thread
+     * explicit overrides keyed by {@link SessionKey} string — a present entry (true
+     * OR false) wins over the global default. Both optional so older state files
+     * stay valid; lifecycle-independent (only `/auto_continue_limits` mutates them, never
+     * session teardown). Same shape discipline as the `compactOnIdle*` pair.
+     */
+    autoContinueOnLimitEnabled?: boolean;
+    autoContinueOnLimitOverrides?: Record<string, boolean>;
+    /**
+     * Persisted scheduled jobs, keyed by {@link ScheduleRecord.id}. Optional so
+     * older state files (created before the scheduler feature) stay valid —
+     * `loadStateFile`'s shape check doesn't require it and a missing value is an
+     * empty schedule set. The crash-critical `nextRunAt` inside each record is
+     * why the engine calls {@link StateStore.flush} after every fire rather than
+     * relying on the debounced save.
+     */
+    schedules?: Record<string, ScheduleRecord>;
+    /**
+     * Secret keying the HMAC tokens the bot mints for its own scheduler MCP
+     * server (see `scheduler/mcpSurface.ts`). Generated once on first use
+     * (`getSchedulerMcpSecret`) and persisted so the tokens injected into agent
+     * sessions stay valid across restarts. Optional so older state files stay
+     * valid — a missing value is created lazily on the first read.
+     */
+    schedulerMcpSecret?: string;
+    /**
+     * The loopback port the bot's scheduler MCP server bound on a prior boot (see
+     * `scheduler/mcpSurface.ts`). The listen port is EPHEMERAL by default (`0` →
+     * an OS-assigned port), which changes on every restart; persisting the bound
+     * port lets a later boot reuse it so the `telegramBot` registrations injected
+     * into agent sessions (which embed `http://127.0.0.1:<port>/mcp`) stay valid
+     * across restarts instead of pointing at a dead port. Not written when the
+     * operator fixes the port via `SCHEDULER_MCP_PORT`. Optional so older state
+     * files stay valid — a missing value means "no port to reuse, pick fresh".
+     */
+    schedulerMcpPort?: number;
+    /**
+     * In-flight interactive agent questions, keyed by {@link SessionKey} string.
+     * Persisted so a pending question survives a bot restart / hot reload: the
+     * in-memory `pendingQuestions` map (see `bot.ts`) is otherwise lost, leaving
+     * the agent's question tool blocked forever and the posted Telegram option
+     * buttons dead ("no pending question"). The persisted `messageId` lets the
+     * OLD buttons resolve once the map is re-armed at boot, so no question is
+     * re-posted. Optional so older state files stay valid — a missing value is
+     * an empty set. Restored at boot only for threads whose session reattached
+     * and is active; otherwise dropped (the question is unreachable).
+     */
+    pendingQuestions?: Record<string, PendingQuestionState>;
+    /**
+     * Armed auto-retries after a provider-side API error, keyed by
+     * {@link SessionKey} string. Persisted so a pending retry survives a bot
+     * restart / hot reload: the in-memory `apiRetries` map (see `bot.ts`) is
+     * otherwise lost, so an agent that died on a rate-limit / usage-limit error
+     * would never get its scheduled nudge — especially a multi-hour usage-limit
+     * wait. The persisted `fireAt` lets boot re-arm the timer (or fire one
+     * immediate catch-up when the time already passed). A record means ARMED: it is
+     * cleared once the retry's kick has run its course (its nudge forwarded, or dropped
+     * for good), else every restart would fire the kick again — but kept while the nudge
+     * only waits in the in-memory startup buffer, which a restart loses. Optional so
+     * older state files stay valid — a missing value is an empty set. Restored at boot
+     * only after sessions are reattached, so the kick lands in a live session.
+     */
+    apiRetries?: Record<string, ApiRetryState>;
+    /**
+     * Prompts held during an armed usage-limit wait (Jira plan R23), keyed by
+     * {@link SessionKey} string, oldest first. Kept apart from `apiRetries`: the
+     * wait can end without its resume (the operator writes, skips or disables it,
+     * the session ends), and the prompts must outlive it until they reach a
+     * session (`utils/limitHeldPromptQueue.ts`). Optional — absent when empty.
+     */
+    limitHeldPrompts?: Record<string, LimitHeldPrompt[]>;
+    /**
+     * Open requests of the request ledger (`requests/requestLedger.ts`), keyed by
+     * the serialized request GROUP (conversation + requester, `requests/requestGroup.ts`)
+     * — at most ONE per group (a new request of the group supersedes the open one;
+     * another requester's request in the same conversation stays open beside it).
+     * Persisted so an unanswered request, its counters
+     * and its next wake-up survive a bot restart. Closed requests move to the
+     * append-only `DATA_DIR/requests.jsonl`. Optional so older state files stay
+     * valid — a missing value is an empty set.
+     */
+    openRequests?: Record<string, OpenRequestState>;
+    /**
+     * Per conversation (serialized {@link SessionKey}), the message id of the
+     * LATEST pinned `answer_request` answer (request/answer plan S8): a new answer
+     * unpins it and takes its place, so a topic never keeps two answers pinned —
+     * across restarts too. Optional, dropped when empty.
+     */
+    answerPins?: Record<string, number>;
+    /**
+     * Alerts of CLOSED requests that are not released yet (Telegram: still
+     * pinned), keyed by request id. A request that closes while it holds an alert
+     * lands here in the same save as its close, and leaves only once the release
+     * succeeded — so a crash between the close and the unpin re-releases at the
+     * next boot instead of leaving the pin forever. Optional — absent when empty.
+     */
+    unreleasedRequestAlerts?: Record<string, UnreleasedRequestAlert>;
+    /**
+     * Boot-recovery markers: per {@link SessionKey} string, the `stdout.jsonl`
+     * identity the recovery last armed a limit wait from (see
+     * {@link LimitEpisodeMarker}). It is what stops a hot reload from resurrecting a
+     * wait that was already settled — «⏭ Skip once», a user takeover, or a give-up
+     * all clear `apiRetries`, leaving the same trailing error in the log. Optional so
+     * older state files stay valid; dropped when the thread's session ids are
+     * released or its binding goes away.
+     */
+    limitEpisodesRecovered?: Record<string, LimitEpisodeMarker>;
+    /**
+     * Per-thread OpenCode output-verbosity rendering preferences (thinking /
+     * tool-results / sub-agent display), keyed by {@link SessionKey} string. Each
+     * record only stores NON-default overrides — an absent field (or absent
+     * record) means "use the locked default" (see {@link StateStore.getDisplayPrefs}),
+     * which keeps `state.json` clean (same delete-when-default idiom as `/trace`).
+     * Optional so older state files stay valid — a missing value is "all threads
+     * on defaults". Lifecycle-independent: only `/thinking` / `/tool-results` /
+     * `/subagent` mutate it, never session teardown. These are bot-side rendering
+     * concerns, NOT agent behavior — they never change what is sent to OpenCode.
+     */
+    displayPrefs?: Record<string, ThreadDisplayPrefs>;
+    /**
+     * Per-thread TRANSIENT status-frame message ids currently on screen (the
+     * "✽ working…" liveness frame, the live thinking indicator, the dedicated
+     * sub-agent status), keyed by {@link SessionKey} string. Persisted ONLY so an
+     * UNGRACEFUL exit (crash / SIGKILL — the graceful shutdown sweep in `bot.ts`
+     * never ran) can delete whatever frame was on screen on the NEXT boot, after
+     * reattach (the reattached session is idle, so a leftover frame is stale by
+     * definition). Cosmetic, so it rides the debounced save — losing the last
+     * <=500ms window before a crash just falls back to the pre-fix orphan for that
+     * one frame (S1 covers every graceful path exactly). Optional so older state
+     * files stay valid — a missing value is an empty set; an empty list drops the
+     * key so an idle bot leaves a clean `state.json`.
+     */
+    transientFrames?: Record<string, number[]>;
+}
+/**
+ * @description Promise-chain per-key lock. The map holds the tail of each
+ * key's queue; new callers attach to the tail and append themselves. Errors
+ * in one task don't poison followers — the chain only carries scheduling,
+ * not values. See plan §13.15 (E3).
+ *
+ * Exported for unit tests (plan §11 Этап 7, R5).
+ */
+export declare class KeyLock {
+    private chains;
+    withLock<T>(keyStr: string, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * @description Best-effort atomic write of `content` to `finalPath`.
+ *
+ * Sequence: `writeFile(tmp)` → `fsync(tmp)` → `rename(tmp, final)` →
+ * `fsync(parentDir)`. The last step is critical: without it, `rename`
+ * survives crashes but the new directory entry can be lost on a power
+ * cut on ext4 (plan §13.14, fix to T4).
+ *
+ * Tmp files are colocated with the final file so `rename` stays on the
+ * same filesystem (cross-fs rename would degrade to copy+unlink and break
+ * atomicity). Permissions on the tmp default to `0600` so a state file
+ * containing model preferences / session ids isn't world-readable on a
+ * shared host.
+ *
+ * Directory `fsync` is wrapped in a soft try/catch: on Windows opening a
+ * directory for read isn't supported and would throw. Our deployment
+ * target is Linux/Mac (plan §17.4 «Windows: not our case»), so logging
+ * and continuing is the right trade.
+ */
+export declare function writeFileAtomic(finalPath: string, content: string, options?: {
+    mode?: number;
+}): Promise<void>;
+/**
+ * @description Try to load the state file. On a successful parse return the
+ * structured state. On parse failure archive the broken file to
+ * `state.json.corrupted-<iso>` and return `null` so the caller can start fresh.
+ *
+ * Three cases the caller cares about:
+ *
+ *   1. File doesn't exist → `null`, no archive. Fresh install.
+ *   2. File exists, parses → state object.
+ *   3. File exists, parses fails → archived, `null` returned.
+ *      We also handle EPERM / EACCES on read here for completeness — same
+ *      treatment: archive (if possible) and start fresh.
+ *
+ * Exported for unit tests (plan §11 Этап 7, R6).
+ */
+export declare function loadStateFile(filePath: string): Promise<{
+    ok: true;
+    state: StateV1;
+} | {
+    ok: false;
+    reason: 'missing';
+} | {
+    ok: false;
+    reason: 'corrupted';
+    archivedTo: string | null;
+    error: string;
+}>;
+/**
+ * @description Migrate the legacy single-folder bot's message-id file.
+ *
+ * Old layout: `~/.telegram-bot-messages.json` keyed by raw user id.
+ * The 2.0 release intentionally doesn't try to merge those ids into the
+ * new `SessionKey`-keyed schema — the routing model changed too much for
+ * a clean mapping (plan §9). We just rename the file so it's preserved
+ * for the user's records and so it stops being read on every boot.
+ *
+ * Returns the archive path if migration happened, `null` otherwise.
+ */
+export declare function migrateLegacyMessageIdsFile(): Promise<string | null>;
+export interface StateStoreOptions {
+    /** Override the debounce window for tests. */
+    saveDebounceMs?: number;
+}
+/**
+ * @description Stateful, async-safe store for `state.json`.
+ *
+ * Construction is cheap (no I/O). Call `init()` once at boot before any
+ * setters fire; init loads or initialises the file, performs the legacy
+ * migration, and resolves. Setters return promises so callers can await
+ * the resulting persisted state when correctness matters more than
+ * throughput; non-critical writes are debounced.
+ */
+export declare class StateStore {
+    private readonly dataDir;
+    private readonly statePath;
+    private readonly saveDebounceMs;
+    private state;
+    /** True if the previous on-disk state file was unreadable / corrupt. */
+    private corruptedOnLoad;
+    /** Archive path if the previous on-disk state was corrupted. */
+    private corruptedArchivePath;
+    /** Backup path if the legacy file was migrated. */
+    private legacyMigrationPath;
+    private saveTimer;
+    /** Tail of the chained writes so two flushes don't try to rename simultaneously. */
+    private writeChain;
+    /**
+     * Last compact-on-idle activity/turn stamp each thread actually asked to
+     * PERSIST, used to apply {@link compactIdleTrackingPersistStepMs}. In-memory
+     * only and deliberately NOT written to disk — it is bookkeeping ABOUT the
+     * bookkeeping, and after a restart the first stamp simply schedules one save.
+     */
+    private readonly compactIdleTrackingSavedAt;
+    private readonly keyLock;
+    constructor(dataDir: string, options?: StateStoreOptions);
+    /**
+     * @description One-shot boot. Creates `dataDir` if missing, performs
+     * legacy migration, loads the existing state file (or starts fresh on
+     * corruption).
+     */
+    init(): Promise<void>;
+    /** Path of the live state file (for logging / docs / smoke-tests). */
+    get stateFilePath(): string;
+    /** True iff the previous boot's state file was unreadable on this start. */
+    wasCorruptedOnLoad(): boolean;
+    /** Where the previous corrupted file was moved, if archival succeeded. */
+    getCorruptedArchivePath(): string | null;
+    /** Where the legacy `~/.telegram-bot-messages.json` was archived, if it existed. */
+    getLegacyMigrationPath(): string | null;
+    /**
+     * @description Run `fn` while holding the per-key lock for `key`. Concurrent
+     * calls for the SAME key are serialised; calls for different keys run in
+     * parallel. Failure in one holder does NOT propagate to followers (the lock
+     * is for serialisation only; error handling is each caller's job).
+     */
+    withLock<T>(key: SessionKey, fn: () => Promise<T>): Promise<T>;
+    getBinding(key: SessionKey): BindingData | null;
+    setBinding(key: SessionKey, subdir: string, options?: {
+        closed?: boolean;
+        topicName?: string;
+    }): Promise<void>;
+    /**
+     * @description Persist the forum-topic display name for a thread. Used by
+     * `forum_topic_edited` (rename) when a binding already exists. No-op (no
+     * save) when the binding is absent or the name is unchanged — symmetric to
+     * {@link setBindingPinnedStatusText}.
+     */
+    setBindingTopicName(key: SessionKey, topicName: string): Promise<void>;
+    setBindingClosed(key: SessionKey, closed: boolean): Promise<void>;
+    /**
+     * @description Persist the pinned status banner's message id for a thread,
+     * or clear it (pass `null`). Skipped if the binding doesn't exist — we
+     * don't ever want a pinned-message row dangling without a parent binding.
+     *
+     * Caller is expected to actually pin / unpin in Telegram around this
+     * call; this method only updates the on-disk pointer. Plan §20.5.
+     */
+    setBindingPinnedStatusMessageId(key: SessionKey, messageId: number | null): Promise<void>;
+    /**
+     * @description Persist the last banner text sent/edited for a thread, or
+     * clear it (pass `null`). Mirrors {@link setBindingPinnedStatusMessageId}:
+     * skipped if the binding doesn't exist, and a no-op (no save) when the value
+     * is unchanged. Read back at boot to seed `pinnedStatusTextCache` so the
+     * startup refresh wave skips identical-banner edits (B8).
+     */
+    setBindingPinnedStatusText(key: SessionKey, text: string | null): Promise<void>;
+    removeBinding(key: SessionKey): Promise<void>;
+    listBindings(): Array<{
+        key: SessionKey;
+        data: BindingData;
+    }>;
+    /**
+     * @description Find every thread currently bound to a given subdir.
+     * Plan §10.6 names this for `/bind` UX warning «📁 уже работают треды: ...»
+     * — one folder may be reached from several threads (D7).
+     */
+    listKeysForSubdir(subdir: string): SessionKey[];
+    getAgent(key: SessionKey): AgentData | null;
+    /**
+     * @description Upsert agent state for a thread. `name` is required (we
+     * don't keep an agent record without a backend choice); the rest of the
+     * fields are patched onto whatever exists.
+     */
+    setAgent(key: SessionKey, data: {
+        name: string;
+    } & Partial<Omit<AgentData, 'name'>>): Promise<void>;
+    removeAgent(key: SessionKey): Promise<void>;
+    getClaudeSessionId(key: SessionKey): string | null;
+    /**
+     * @description Persist the Claude `--session-id` UUID for `key`.
+     *
+     * If the thread already has an agent record, only the `claudeSessionId`
+     * field is patched — we keep whatever `name` was previously chosen so a
+     * thread currently set to `opencode` doesn't get silently flipped to
+     * `claude` just because we recorded a UUID. The bot picks the adapter
+     * via {@link setAgent} or `setThreadAdapter` — those are the right
+     * places to change `name`.
+     */
+    setClaudeSessionId(key: SessionKey, uuid: string): Promise<void>;
+    getOpenCodeSessionId(key: SessionKey): string | null;
+    /** Symmetric to {@link setClaudeSessionId} — does not flip `agent.name`. */
+    setOpenCodeSessionId(key: SessionKey, id: string): Promise<void>;
+    /**
+     * @description Advance the per-thread {@link SeenWatermark} (set at each turn
+     * end by the adapters via the injected writer). Merges onto the EXISTING agent
+     * row only — never flips `agent.name` (symmetric to
+     * {@link setClaudeSessionId} / {@link setOpenCodeSessionId}) and, unlike them,
+     * never CREATES a row: a watermark is meaningless without a live agent session
+     * (which always recorded its row first), so a write for an unknown thread is a
+     * no-op, not a dangling agent row.
+     */
+    setSeenWatermark(key: SessionKey, watermark: SeenWatermark): Promise<void>;
+    /**
+     * @description Persist the json-stream stdout tail offset (advanced by the
+     * adapter's tail poller through the injected writer, sealed by the shutdown
+     * `flush()`). Merge-only like {@link setSeenWatermark}: never flips
+     * `agent.name` and never creates a row — an offset is meaningless without
+     * the agent row its session recorded first.
+     */
+    setJsonStreamTail(key: SessionKey, tail: JsonStreamTailOffset): Promise<void>;
+    /**
+     * @description Persist the session-start timestamp (a local-offset ISO string;
+     * see {@link AgentData.startedAt}). Merge-only like {@link setSeenWatermark}:
+     * never flips `agent.name` and never CREATES a row — the caller records the
+     * agent row (via `setAgent` / `persistAdapterSessionIds`) first, so a write
+     * for an unknown thread is a no-op rather than a dangling agent row.
+     */
+    setAgentStartedAt(key: SessionKey, startedAt: string): Promise<void>;
+    /** Persist the tool digest a json-stream process was started with (see {@link AgentData.mcpToolDigest}); merge-only. */
+    setAgentMcpToolDigest(key: SessionKey, mcpToolDigest: string): Promise<void>;
+    /**
+     * @description Release both persisted session ids (and the json-stream tail
+     * offset, which is meaningless without its session; plus the session-start
+     * timestamp, which belongs to the session going away) for `key` while keeping
+     * `name` / `model`. Called on explicit user stop (`/quit`, `/quit-all`,
+     * `/new`, `/unbind`) so a later bot restart won't auto-reattach a session
+     * the user deliberately ended. No-op when the thread has no agent record.
+     */
+    clearAgentSessionIds(key: SessionKey): Promise<void>;
+    getMessageIds(key: SessionKey): number[];
+    /** Append IDs to the bounded in-memory ring while the caller holds the key lock. */
+    private appendMessageIds;
+    /**
+     * @description Append a message id to the per-thread tracking list and
+     * trim to the most recent `MESSAGE_ID_RING_CAP`. Anything older falls off
+     * the end — Telegram won't let `deleteMessages` touch messages older than
+     * 48h anyway (plan §11 Этап 3, U2).
+     */
+    pushMessageId(key: SessionKey, msgId: number): Promise<void>;
+    /** Atomically append and durably persist one Telegram response's message IDs. */
+    pushMessageIds(key: SessionKey, messageIds: number[]): Promise<void>;
+    /** Atomically hand tracked IDs to `/clear_messages` while later pushes remain tracked. */
+    takeMessageIds(key: SessionKey, additionalIds?: number[]): Promise<number[]>;
+    /**
+     * @description Stamp `lastHeartbeatAt = now` (ms) and schedule a debounced
+     * save. Called by the bot on a ~10s interval while running so the next
+     * boot can tell a hot reload (gap < threshold) from a real cold start
+     * (gap large, or no stamp at all on a fresh install).
+     *
+     * Cheap by design: a one-field mutation that piggy-backs on the existing
+     * debounced save loop. We don't `flush()` here — losing the last 10s
+     * heartbeat on a hard crash just biases the next boot toward
+     * "cold start", which is the conservative direction.
+     */
+    touchHeartbeat(now?: number): void;
+    /**
+     * @description Time since the last persisted heartbeat in ms, or `null`
+     * if the state file has no heartbeat stamp (fresh install, or pre-feature
+     * state file). `null` should be treated as "unknown → assume cold start".
+     *
+     * Read at boot to decide hot-vs-cold-start, ideally BEFORE the first
+     * `touchHeartbeat()` call or `state.flush()` (otherwise the value
+     * compares against ourselves and always looks like a hot reload).
+     */
+    getDowntimeMs(now?: number): number | null;
+    /** The auto-paired forum supergroup id, or `null` if never paired. */
+    getPairedGroupId(): number | null;
+    /**
+     * @description Persist the auto-paired group id and flush immediately.
+     *
+     * Unlike per-thread mutations this is a rare, one-shot critical write:
+     * if the process dies right after pairing we must not lose the id and
+     * fall back into pairing mode on the next boot. So we `flush()` rather
+     * than debounce.
+     */
+    setPairedGroupId(groupId: number): Promise<void>;
+    /**
+     * @description Current persisted trace toggle. `threadKeys` are the
+     * {@link SessionKey} strings opted into tracing; `allThreads` traces
+     * everything. `allThreads` defaults to TRUE on a fresh or pre-feature state
+     * file (always-on observability — only an explicit `/trace off all` turns it
+     * off, stored as a durable `false`); `threadKeys` defaults empty. Read at boot
+     * to seed `outputTrace.ts`.
+     */
+    getTraceConfig(): {
+        allThreads: boolean;
+        threadKeys: string[];
+    };
+    /**
+     * @description Persist the trace toggle. Not crash-critical (a debug aid), so
+     * it rides the debounced save loop rather than an immediate `flush()`. The
+     * `tracedThreads` array is normalised to a deduped, sorted form so the
+     * on-disk shape is stable across toggles; an empty list is dropped.
+     *
+     * `traceAllThreads` is stored EXPLICITLY as a boolean (including `false`):
+     * the all-threads default is now ON ({@link getTraceConfig}), so a `/trace
+     * off all` must be DURABLE and distinguishable from "never set" (which reads
+     * back as the ON default). Dropping it on `false` would silently re-enable
+     * tracing on the next boot.
+     */
+    setTraceConfig(config: {
+        allThreads: boolean;
+        threadKeys: string[];
+    }): Promise<void>;
+    getChatLocaleOverride(chatId: number): Locale | null;
+    getChatTelegramLocale(chatId: number): Locale | null;
+    setChatLocaleOverride(chatId: number, locale: Locale | null): Promise<void>;
+    setChatTelegramLocale(chatId: number, locale: Locale): Promise<void>;
+    /**
+     * @description Whether `/timestamps` is ON for `key` (default OFF). When ON,
+     * `forwardPromptToAgent` prepends the send-time as a local-offset ISO top
+     * line to every forwarded prompt.
+     */
+    checkIsTimestampsEnabled(key: SessionKey): boolean;
+    /**
+     * @description Persist the per-thread `/timestamps` toggle. Mirrors
+     * {@link setTraceConfig}'s shape discipline: the list is deduped + sorted so
+     * the on-disk form is stable, and an empty list is dropped (an all-defaults
+     * install leaves no trace in `state.json`). Not crash-critical, so it rides
+     * the debounced save loop.
+     */
+    setTimestampsEnabled(key: SessionKey, isEnabled: boolean): Promise<void>;
+    /**
+     * @description Providers currently hidden from the `/model` picker, in the
+     * stable sorted on-disk order. Empty when nothing is hidden (the default).
+     */
+    getHiddenModelProviders(): string[];
+    /**
+     * @description Hide/show one provider in the `/model` picker. Mirrors
+     * {@link setTimestampsEnabled}'s shape discipline: deduped + sorted so the
+     * on-disk form is stable across toggles, and an empty list is dropped (a
+     * default install leaves no trace in `state.json`). A picker preference is
+     * not crash-critical, so it rides the debounced save loop.
+     */
+    setModelProviderHidden(provider: string, isHidden: boolean): Promise<void>;
+    /**
+     * @description The instance-wide compact-on-idle default (driven from the
+     * General topic). ON when unset — same always-on default as
+     * {@link getTraceConfig}'s `allThreads`.
+     */
+    getCompactOnIdleGlobalDefault(): boolean;
+    /**
+     * @description The per-thread compact-on-idle override, or `undefined` when the
+     * thread follows the instance default. A present value (true OR false) wins.
+     */
+    getCompactOnIdleOverride(key: SessionKey): boolean | undefined;
+    /**
+     * @description Whether compact-on-idle is effectively enabled for `key`: the
+     * per-thread override if set, else the instance default (OFF when unset).
+     */
+    checkIsCompactOnIdleEnabled(key: SessionKey): boolean;
+    /**
+     * @description Set the instance-wide compact-on-idle default (from General).
+     * Stored EXPLICITLY as a boolean (incl. `false`) so a «Disable» is durable and
+     * distinguishable from "never set" (which reads back as the ON default) —
+     * mirrors {@link setTraceConfig}'s `traceAllThreads` discipline. Debounced (a
+     * preference, not crash-critical).
+     */
+    setCompactOnIdleGlobalDefault(enabled: boolean): Promise<void>;
+    /**
+     * @description Set the per-thread compact-on-idle override (from a regular
+     * topic). Stored explicitly (a present true/false wins over the global
+     * default); the whole map is dropped once empty so an all-default instance
+     * leaves a clean `state.json`. Debounced.
+     */
+    setCompactOnIdleOverride(key: SessionKey, enabled: boolean): Promise<void>;
+    /**
+     * @description The instance-wide full-compaction-summary default (driven from the
+     * General topic). OFF when unset, unlike {@link getCompactOnIdleGlobalDefault}:
+     * a compaction ends in one short line unless the summary is turned on.
+     */
+    getCompactSummaryGlobalDefault(): boolean;
+    /**
+     * @description The per-thread full-summary override, or `undefined` when the
+     * thread follows the instance default. A present value (true OR false) wins.
+     */
+    getCompactSummaryOverride(key: SessionKey): boolean | undefined;
+    /**
+     * @description Whether the full compaction summary is posted for `key`: the
+     * per-thread override if set, else the instance default (ON when unset).
+     */
+    checkIsCompactSummaryEnabled(key: SessionKey): boolean;
+    /**
+     * @description Set the instance-wide full-summary default (from General). Stored
+     * EXPLICITLY as a boolean (incl. `false`) so a choice is durable and
+     * distinguishable from "never set", which reads back as the OFF default. Debounced
+     * (a preference, not crash-critical) — mirrors
+     * {@link setCompactOnIdleGlobalDefault}.
+     */
+    setCompactSummaryGlobalDefault(enabled: boolean): Promise<void>;
+    /**
+     * @description Set the per-thread full-summary override (from a regular topic).
+     * Stored explicitly (a present true/false wins over the global default).
+     * Debounced — mirrors {@link setCompactOnIdleOverride}.
+     */
+    setCompactSummaryOverride(key: SessionKey, enabled: boolean): Promise<void>;
+    /**
+     * @description Whether `key`'s compact-on-idle user-latch is spent (D2): an
+     * idle-compaction already fired this user-active period and no genuine USER
+     * message has re-armed it since. Read by the idle watchdog's fire guard and by
+     * the timer-arming path (a latched thread never re-arms — so a restart can't
+     * re-fire). Default `false` (never latched).
+     */
+    checkIsCompactIdleLatched(key: SessionKey): boolean;
+    /**
+     * @description Set/clear `key`'s compact-on-idle user-latch (D2). Set on a
+     * fire, cleared on a genuine USER message / fresh session start. Mirrors
+     * {@link setTimestampsEnabled}'s shape discipline (deduped + sorted, dropped
+     * when empty) and rides the debounced save loop — the persistence is only a
+     * restart guard, so losing the last <=500ms is at worst one extra fire.
+     */
+    setCompactIdleLatched(key: SessionKey, isLatched: boolean): Promise<void>;
+    /**
+     * @description `key`'s persisted compact-on-idle instants, with every absent
+     * field read back as `0`. `0` is the explicit "no history" value both readers
+     * rely on: the arming path takes it as "use the full idle window" and the fire
+     * guard's `lastTurnEndAt > lastCompactionAt` as "nothing to compress" — so a
+     * pre-feature state file behaves exactly like an untracked thread.
+     *
+     * All zeros are ALSO returned whenever the entry does not belong to the thread's
+     * CURRENT agent session (a different `sessionId`, or either id unknown): the
+     * instants describe one session's context, so a session swap must reset the
+     * marker, and deciding that here — rather than in a teardown handler — makes it
+     * true regardless of which lifecycle events fired (a killed process emits none).
+     * Unknown-means-zero is conservative in the right direction: at worst the topic
+     * waits one more full idle window.
+     */
+    getCompactIdleTracking(key: SessionKey): {
+        lastActivityAt: number;
+        lastTurnEndAt: number;
+        lastCompactionAt: number;
+    };
+    /**
+     * @description Stamp `key`'s last REAL activity — the instant the idle
+     * countdown is measured from. Called on every agent output chunk, so the write
+     * is COARSE: the in-memory value is always assigned (readers are exact), but a
+     * save is scheduled only once the value has moved a full
+     * {@link compactIdleTrackingPersistStepMs} past what was last persisted. The
+     * assigned value also rides along for free on the next save the ~10s
+     * {@link touchHeartbeat} loop schedules, so the coarse step costs nothing in
+     * correctness — at worst the persisted stamp trails the live one by under a
+     * minute, against a 55-minute threshold.
+     */
+    noteCompactIdleActivity(key: SessionKey, now?: number): void;
+    /**
+     * @description Stamp that an agent turn produced output for `key` — the proof
+     * there is something to compress (the fire guard compares this against
+     * `lastCompactionAt`). Same per-chunk call frequency and therefore the same
+     * coarse-save rule as {@link noteCompactIdleActivity}.
+     */
+    noteCompactIdleTurnEnd(key: SessionKey, now?: number): void;
+    /**
+     * @description Stamp that `key` was just compacted (any trigger: manual
+     * `/compact`, the F1 tool, an F2 idle fire), closing the fire guard until the
+     * next turn produces output. Rare, so it always schedules a save — persisting it
+     * is what stops a restart from re-compacting a session nothing has touched
+     * since.
+     */
+    setCompactIdleCompactedAt(key: SessionKey, now?: number): Promise<void>;
+    /**
+     * @description Drop `key`'s compact-on-idle bookkeeping (session teardown:
+     * `/new`, `/quit`, unbind). Deliberately a full delete rather than a reset —
+     * with no entry the next session start finds `lastActivityAt === 0` and gets
+     * the FULL idle window, which is exactly the wanted behaviour for a fresh
+     * session, so no special case is needed on the start path. The whole map is
+     * dropped once empty so an idle bot leaves a clean `state.json`.
+     */
+    clearCompactIdleTracking(key: SessionKey): Promise<void>;
+    /**
+     * Assign one high-frequency compact-on-idle stamp in memory and schedule a save
+     * only past the coarse step (see {@link noteCompactIdleActivity}). Synchronous
+     * (no key lock) on purpose: it runs on the output hot path, and a single-field
+     * assignment cannot interleave with another write the way a read-modify-write
+     * of a whole record can.
+     */
+    private stampCompactIdleTracking;
+    /**
+     * The thread's CURRENT agent session id — `claudeSessionId` else
+     * `opencodeSessionId` from the persisted {@link AgentData} — or `undefined` when
+     * the thread has neither. A raw `/terminal` shell has no session id and cannot be
+     * compacted anyway, so "no id" means the compact-on-idle marker has nothing to
+     * bind to: reads return zeros and stamps are skipped, keeping `state.json` clean.
+     */
+    private getAgentSessionId;
+    /**
+     * @description The instance-wide limit-auto-continue default (driven from the
+     * General topic). ON when unset — the auto-resume was unconditional before the
+     * toggle, so the default must preserve it.
+     */
+    getAutoContinueOnLimitGlobalDefault(): boolean;
+    /**
+     * @description The per-thread limit-auto-continue override, or `undefined` when
+     * the thread follows the instance default. A present value (true OR false) wins.
+     */
+    getAutoContinueOnLimitOverride(key: SessionKey): boolean | undefined;
+    /**
+     * @description Whether limit auto-continue is effectively enabled for `key`: the
+     * per-thread override if set, else the instance default (ON when unset).
+     */
+    checkIsAutoContinueOnLimitEnabled(key: SessionKey): boolean;
+    /**
+     * @description Set the instance-wide limit-auto-continue default (from General).
+     * Stored EXPLICITLY as a boolean (incl. `false`) so a «Disable» is durable and
+     * distinguishable from "never set" (which reads back as the ON default) —
+     * mirrors {@link setCompactOnIdleGlobalDefault}. Debounced (a preference, not
+     * crash-critical).
+     */
+    setAutoContinueOnLimitGlobalDefault(enabled: boolean): Promise<void>;
+    /**
+     * @description Set the per-thread limit-auto-continue override (from a regular
+     * topic). Stored explicitly (a present true/false wins over the global
+     * default); the map is created lazily on the first override, so an all-default
+     * instance leaves a clean `state.json`. Debounced.
+     */
+    setAutoContinueOnLimitOverride(key: SessionKey, enabled: boolean): Promise<void>;
+    /**
+     * @description The stored operator timezone, or `null` when none is set (the
+     * caller then falls back to the host zone — see `utils/timezone.ts`
+     * `getEffectiveTimezone`). Deliberately NOT defaulted here: the store reports
+     * what is on disk, the resolution rule lives in one place outside it.
+     */
+    getTimezone(): string | null;
+    /**
+     * @description Store the operator timezone, or drop the field on `null`
+     * (reset to the host zone) so a default install leaves no trace in
+     * `state.json` — same shape discipline as {@link setModelProviderHidden}.
+     *
+     * Flushed eagerly rather than riding the debounced save loop: a zone change
+     * immediately recomputes every schedule's `nextRunAt`, and losing the zone
+     * while keeping the recomputed fire times would leave the two disagreeing
+     * after a crash.
+     */
+    setTimezone(timezone: string | null): Promise<void>;
+    /**
+     * @description Fully-resolved display preferences for `key`: every field is
+     * present because the locked default (`minimal` for all three) is applied
+     * wherever the persisted record omits it. The SSE hot path reads this, so it
+     * must never hand back an `undefined` field.
+     *
+     * Read-time normalization: a `state.json` written before the vocabulary was
+     * unified may still hold legacy names (`detailed`/`brief`/`hide`/`compact`)
+     * — those map onto the new vocabulary here, and an unrecognized value falls
+     * back to the default, so old files keep working without a migration pass.
+     */
+    getDisplayPrefs(key: SessionKey): ResolvedThreadDisplayPrefs;
+    /**
+     * @description Persist one display-preference field for `key`. Setting a
+     * field to its locked default DELETES the override (and drops the whole
+     * record / map once empty) so an all-defaults thread leaves a clean
+     * `state.json` — same delete-when-default idiom as {@link setTraceConfig}.
+     * Not crash-critical (a rendering preference), so it rides the debounced
+     * save loop rather than an immediate `flush()`. Callers pass an
+     * already-normalized value — legacy names never reach the store on the write
+     * path. The `view` field (S6) rides the same record and the same idiom, with
+     * its own locked default.
+     */
+    setDisplayPref<TField extends keyof ThreadDisplayPrefs>(key: SessionKey, field: TField, value: NonNullable<ThreadDisplayPrefs[TField]>): Promise<void>;
+    /**
+     * @description Every persisted schedule across all threads, keyed by id.
+     * Read at boot by the engine to re-arm timers. Returns a shallow copy of the
+     * map so callers can't mutate the live state object.
+     */
+    getSchedules(): Record<string, ScheduleRecord>;
+    /** Schedules owned by `key`, in insertion order. Empty array when none. */
+    getThreadSchedules(key: SessionKey): ScheduleRecord[];
+    /**
+     * @description Upsert a schedule by its id. The record's `threadKey` is the
+     * source of truth for ownership; callers build it via the scheduler module's
+     * `createScheduleRecord`. Crash-critical fields (`nextRunAt`) ride the
+     * debounced save like every other mutation — the engine calls
+     * {@link flush} explicitly after a fire when the new `nextRunAt` must hit disk
+     * before the process can die.
+     */
+    upsertSchedule(record: ScheduleRecord): Promise<void>;
+    /** Remove a schedule by id. No-op (no save) when absent. */
+    removeSchedule(id: string): Promise<void>;
+    /**
+     * @description Set the paused flag for a schedule (used by /unbind pause and
+     * /bind resume in S8). Clearing the pause drops both `isPaused` and
+     * `pauseReason` so the on-disk shape stays clean. No-op when the id is absent.
+     */
+    setSchedulePaused(id: string, paused: boolean, reason?: ScheduleRecord['pauseReason']): Promise<void>;
+    /**
+     * @description The HMAC secret keying the scheduler MCP tokens, created lazily
+     * on first read and persisted immediately. Generated once with
+     * `crypto.randomBytes` (32 bytes, hex) so the tokens the bot injects into
+     * agent sessions survive restarts. The first-time write is flushed eagerly
+     * (not debounced) so a crash right after minting the first token can't lose
+     * the secret that token was signed with.
+     */
+    getSchedulerMcpSecret(): Promise<string>;
+    /**
+     * @description The scheduler MCP listen port persisted from a prior boot, or
+     * `undefined` if never persisted (fresh / pre-feature state file). Reused so an
+     * ephemeral port keeps its value across restarts (see
+     * {@link StateV1.schedulerMcpPort}).
+     */
+    getPersistedSchedulerMcpPort(): number | undefined;
+    /**
+     * @description Persist the actually-bound scheduler MCP port and flush eagerly.
+     * Eager (not debounced) mirrors {@link getSchedulerMcpSecret}: the injected
+     * registrations point at this port, so a crash right after binding must not lose
+     * it and hand the next boot a stale port. Called once at boot, only when the
+     * value changed and the operator did not fix the port via env.
+     */
+    setSchedulerMcpPort(port: number): Promise<void>;
+    /**
+     * @description Every persisted pending question across all threads, keyed by
+     * {@link SessionKey} string. Read at boot to re-arm the in-memory map for
+     * threads whose session reattached. Returns a shallow copy so callers can't
+     * mutate the live state object.
+     */
+    getPendingQuestions(): Record<string, PendingQuestionState>;
+    /**
+     * @description Persist (upsert) the pending question for `key`, mirroring the
+     * in-memory `pendingQuestions.set(...)` in `bot.ts` so memory and disk never
+     * drift. Crash-window is acceptable on the debounced save: the worst case
+     * (process dies in the <=500ms before the flush) just falls back to the
+     * pre-fix behaviour for that one question. The `messageId` patch goes through
+     * here too, so the persisted record always carries the live button message.
+     */
+    setPendingQuestion(key: SessionKey, value: PendingQuestionState): Promise<void>;
+    /**
+     * @description Remove the pending question for `key`. Mirrors every in-memory
+     * `pendingQuestions.delete(...)` in `bot.ts`. No-op (no save) when absent. The
+     * whole map is dropped once empty so an idle bot leaves a clean `state.json`.
+     */
+    clearPendingQuestion(key: SessionKey): Promise<void>;
+    /**
+     * @description Every persisted armed auto-retry across all threads, keyed by
+     * {@link SessionKey} string. Read at boot to re-arm the in-memory map after
+     * sessions reattach. Returns a shallow copy so callers can't mutate the live
+     * state object.
+     */
+    getApiRetries(): Record<string, ApiRetryState>;
+    /**
+     * @description Persist (upsert) the armed retry for `key`, mirroring the
+     * in-memory `apiRetries.set(...)` in `bot.ts` so memory and disk never drift.
+     * Crash-window is acceptable on the debounced save: the worst case (process
+     * dies in the <=500ms before the flush) just loses that one armed retry, which
+     * falls back to the pre-fix behaviour for that thread. Each re-arm (next
+     * attempt) goes through here too, so the persisted record always carries the
+     * latest attempt and `fireAt`.
+     */
+    setApiRetry(key: SessionKey, value: ApiRetryState): Promise<void>;
+    /**
+     * @description Remove the armed retry for `key`. Mirrors every in-memory
+     * `apiRetries.delete(...)` in `bot.ts`. No-op (no save) when absent. The whole
+     * map is dropped once empty so an idle bot leaves a clean `state.json`.
+     */
+    clearApiRetry(key: SessionKey): Promise<void>;
+    /** @description The prompts held for `key`, oldest first; `[]` when none. A copy. */
+    getLimitHeldPrompts(key: SessionKey): LimitHeldPrompt[];
+    /**
+     * @description Replace the prompts held for `key`; `[]` drops the entry (and
+     * the map once empty). Synchronous in memory — a take must be atomic against
+     * a concurrent hold — and saved debounced like the retry record it outlives.
+     */
+    setLimitHeldPrompts(key: SessionKey, prompts: readonly LimitHeldPrompt[]): void;
+    /**
+     * @description Every open request across all conversations, keyed by the
+     * serialized {@link RequestGroupKey}. Returns a shallow copy so callers can't
+     * mutate the live state object.
+     */
+    getOpenRequests(): Record<string, OpenRequestState>;
+    /** @description The open request of `group`, or `undefined`. */
+    getOpenRequest(group: RequestGroupKey): OpenRequestState | undefined;
+    /**
+     * @description Replace the open request of `group` with what `mutate` returns
+     * for the current one (`undefined` removes it), under the lock of the group's
+     * CONVERSATION — so a read-decide-write (supersede, close, counter update) is
+     * atomic against a concurrent one for the same conversation, whichever of its
+     * groups it touches. `mutate` runs
+     * synchronously inside the lock; a side effect it performs (the ledger's
+     * history append) therefore happens before any other writer sees the result.
+     * The whole map is dropped once empty so an idle bot leaves a clean
+     * `state.json`.
+     */
+    updateOpenRequest(group: RequestGroupKey, mutate: (current: OpenRequestState | undefined) => OpenRequestState | undefined): Promise<void>;
+    /** @description The alerts of closed requests still to release (a copy). */
+    getUnreleasedRequestAlerts(): Record<string, UnreleasedRequestAlert>;
+    /**
+     * @description Record that a closed request's alert still needs releasing.
+     * Synchronous on purpose: the ledger calls it inside the close's own locked
+     * step, so it rides the same save as the close.
+     */
+    addUnreleasedRequestAlert(requestId: string, alert: UnreleasedRequestAlert): void;
+    /** @description The alert of `requestId` was released; forget it. */
+    removeUnreleasedRequestAlert(requestId: string): void;
+    /** @description The message id of the latest pinned answer in `key`'s conversation, or `undefined`. */
+    getAnswerPinMessageId(key: SessionKey): number | undefined;
+    /**
+     * @description Remember the latest pinned answer of `key`'s conversation; the
+     * record goes away with the thread's binding. Rides the debounced save: a lost
+     * write leaves one extra pinned answer behind, never a wrong unpin.
+     */
+    setAnswerPinMessageId(key: SessionKey, messageId: number): Promise<void>;
+    /**
+     * Drop `k` from one of the optional per-conversation maps, and the map itself
+     * with its last entry (an idle bot leaves a clean `state.json`). `false` when
+     * there was no entry. Caller must hold the key lock.
+     */
+    private dropOptionalMapEntry;
+    /**
+     * @description The `stdout.jsonl` identity recorded when the boot recovery last
+     * armed a limit wait for `key`, or `undefined` when it never did. Compared
+     * against the live stat so an UNCHANGED log is not recovered twice — see
+     * {@link LimitEpisodeMarker}.
+     */
+    getLimitEpisodeRecovered(key: SessionKey): LimitEpisodeMarker | undefined;
+    /**
+     * @description Record the log identity the boot recovery just armed from.
+     * Debounced (a restart guard, not crash-critical: losing the last <=500ms costs
+     * at worst one repeated recovery). NOT cleared by `cancelApiRetry` on purpose —
+     * that fires on «⏭ Skip once» and on every inbound message, which is exactly the
+     * settled-episode case the marker has to outlive.
+     */
+    setLimitEpisodeRecovered(key: SessionKey, value: LimitEpisodeMarker): Promise<void>;
+    /**
+     * Drop `keyStr`'s handled-episode marker (and the whole map once empty). Returns
+     * whether anything changed. Caller must hold the key lock.
+     */
+    private dropLimitEpisodeRecovered;
+    /**
+     * @description Every persisted transient status-frame id list across all
+     * threads, keyed by {@link SessionKey} string. Read at boot (after reattach) to
+     * delete any frame left on screen by an UNGRACEFUL exit. Returns a shallow copy
+     * so callers can't mutate the live state object.
+     */
+    getTransientFrames(): Record<string, number[]>;
+    /**
+     * @description Replace the persisted transient status-frame ids for `key`
+     * (the live "✽ working…" status frame, the thinking indicator, the sub-agent
+     * status — whichever are currently on screen). Mirrors the in-memory
+     * `ThreadMessageState` write in `bot.ts`'s frame-id setters so disk can clean
+     * up what the graceful sweep would have. Debounced (NOT flushed): the frames
+     * are cosmetic. An empty list drops the key (and the whole map once empty) so an
+     * idle bot leaves a clean `state.json`. A no-op (no save) when the id list is
+     * unchanged, so the per-turn create/delete churn doesn't reset the save timer
+     * on every identical re-persist.
+     */
+    setTransientFrames(key: SessionKey, ids: number[]): Promise<void>;
+    /** Schedule a save in `saveDebounceMs`. Repeated calls reset the timer. */
+    private scheduleSave;
+    /**
+     * @description Force a save right now and await on-disk persistence.
+     *
+     * Used by:
+     *   - shutdown handlers — to guarantee no in-memory state is lost,
+     *   - critical paths (initial corruption-archived fresh-start),
+     *   - tests.
+     *
+     * Internally serialises against any in-flight write — only one rename
+     * happens at a time per store.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * @description Resolve the default `DATA_DIR` for the running bot.
+ *
+ * Priority:
+ *   1. `process.env.DATA_DIR` (set by the operator — required for the
+ *      two-instance setup, plan §10.7).
+ *   2. `~/.telegramCode` — single-instance default.
+ *
+ * Two bots on the same host MUST set distinct `DATA_DIR` values, otherwise
+ * they'd silently share `state.json` and corrupt each other. Plan §16.2
+ * adds a startup `.lock` check; that lives in `bot.ts` (Этап 3), not here.
+ */
+export declare function resolveDataDir(): string;
+/**
+ * @description Create-or-fetch the singleton store. The first call performs
+ * `init()` and persists archival/migration side-effects; subsequent calls
+ * just return the cached instance.
+ *
+ * The in-flight promise is cached to keep concurrent first-callers from
+ * each constructing a separate `StateStore` (two stores → two competing
+ * write chains → corrupted JSON). Production triggers only one call from
+ * `startBot()`, but the cost of the guard is trivial.
+ *
+ * Tests should instantiate `new StateStore(...)` directly instead.
+ */
+export declare function getStateStore(): Promise<StateStore>;
+/**
+ * @description Reset the singleton — only for tests. Production code should
+ * never call this; doing so would leak in-flight write promises.
+ */
+export declare function _resetStateStoreSingletonForTests(): void;
+export { fs as _fsForTests };
+//# sourceMappingURL=state.d.ts.map