charness 0.0.0-stage → 3.0.0

package/dist/state.js

@@ -0,0 +1,1830 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._fsForTests = exports.StateStore = exports.KeyLock = exports.compactIdleTrackingPersistStepMs = exports.STATE_SCHEMA_VERSION = void 0;
+exports.writeFileAtomic = writeFileAtomic;
+exports.loadStateFile = loadStateFile;
+exports.migrateLegacyMessageIdsFile = migrateLegacyMessageIdsFile;
+exports.resolveDataDir = resolveDataDir;
+exports.getStateStore = getStateStore;
+exports._resetStateStoreSingletonForTests = _resetStateStoreSingletonForTests;
+const fs = __importStar(require("fs"));
+exports._fsForTests = fs;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const node_crypto_1 = require("node:crypto");
+const sessionKey_1 = require("./sessionKey");
+const displayVerbosity_1 = require("./utils/displayVerbosity");
+const topicView_1 = require("./utils/topicView");
+const compactOnIdle_1 = require("./utils/compactOnIdle");
+const autoContinueOnLimit_1 = require("./utils/autoContinueOnLimit");
+const requestGroup_1 = require("./requests/requestGroup");
+/**
+ * @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. */
+exports.STATE_SCHEMA_VERSION = 1;
+/** Default debounce window (ms) for batched saves. Overridable via the store constructor for tests. */
+const DEFAULT_SAVE_DEBOUNCE_MS = 500;
+/**
+ * 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.
+ */
+exports.compactIdleTrackingPersistStepMs = 60_000;
+/** Empty state used both for fresh installs and after a corruption-archive event. */
+function emptyState() {
+    return {
+        version: exports.STATE_SCHEMA_VERSION,
+        bindings: {},
+        agents: {},
+        messages: {},
+    };
+}
+/** Per-thread message-id cap — older ids beyond this are dropped to keep state small. */
+const MESSAGE_ID_RING_CAP = 500;
+/** Byte length of the lazily-minted scheduler MCP HMAC secret (32 bytes → 64 hex chars). */
+const schedulerMcpSecretByteLength = 32;
+/**
+ * @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).
+ */
+class KeyLock {
+    chains = new Map();
+    async withLock(keyStr, fn) {
+        const prev = this.chains.get(keyStr);
+        const run = async () => {
+            if (prev) {
+                try {
+                    await prev;
+                }
+                catch {
+                    // Swallow predecessor failures — they shouldn't cascade to followers.
+                }
+            }
+            return fn();
+        };
+        const current = run();
+        // Store a swallowed-error variant so this.chains.get() always resolves.
+        const tracked = current.then(() => undefined, () => undefined);
+        this.chains.set(keyStr, tracked);
+        try {
+            return await current;
+        }
+        finally {
+            // If no follower has overwritten our slot, drop the entry to avoid leaks.
+            if (this.chains.get(keyStr) === tracked) {
+                this.chains.delete(keyStr);
+            }
+        }
+    }
+}
+exports.KeyLock = KeyLock;
+/**
+ * @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.
+ */
+async function writeFileAtomic(finalPath, content, options = {}) {
+    const mode = options.mode ?? 0o600;
+    const dir = path.dirname(finalPath);
+    const tmp = path.join(dir, `.${path.basename(finalPath)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    // 1. write + fsync the tmp file
+    const fh = await fs_1.promises.open(tmp, 'w', mode);
+    try {
+        await fh.writeFile(content);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    // 2. atomic rename
+    try {
+        await fs_1.promises.rename(tmp, finalPath);
+    }
+    catch (e) {
+        // Try to clean up the tmp if rename fails so we don't litter the dir.
+        await fs_1.promises.unlink(tmp).catch(() => { });
+        throw e;
+    }
+    // 3. fsync the parent directory so the rename hits disk
+    try {
+        const dh = await fs_1.promises.open(dir, 'r');
+        try {
+            await dh.sync();
+        }
+        finally {
+            await dh.close();
+        }
+    }
+    catch (e) {
+        // EISDIR / ENOTSUP on Windows, AIX etc. We document Linux/Mac so this is benign.
+        const code = e.code;
+        if (code !== 'EISDIR' && code !== 'EPERM' && code !== 'ENOTSUP' && code !== 'EINVAL') {
+            console.warn(`[state] parent dir fsync failed (${code}):`, e);
+        }
+    }
+}
+/**
+ * @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).
+ */
+async function loadStateFile(filePath) {
+    let raw;
+    try {
+        raw = await fs_1.promises.readFile(filePath, 'utf-8');
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT')
+            return { ok: false, reason: 'missing' };
+        // Unreadable (perms, disk error) — treat like corruption so the bot can boot.
+        return {
+            ok: false,
+            reason: 'corrupted',
+            archivedTo: null,
+            error: `read failed (${code}): ${e.message}`,
+        };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // Light shape validation — full migrations would land here on a version bump.
+        if (typeof parsed === 'object' && parsed !== null &&
+            typeof parsed.version === 'number' &&
+            parsed.bindings && typeof parsed.bindings === 'object' &&
+            parsed.agents && typeof parsed.agents === 'object' &&
+            parsed.messages && typeof parsed.messages === 'object') {
+            return { ok: true, state: parsed };
+        }
+        throw new Error('shape mismatch');
+    }
+    catch (e) {
+        const archivedTo = await archiveCorruptedFile(filePath);
+        return {
+            ok: false,
+            reason: 'corrupted',
+            archivedTo,
+            error: e.message,
+        };
+    }
+}
+/**
+ * @description Rename a corrupted state file out of the way so the bot
+ * can boot with a fresh state without losing forensic evidence.
+ *
+ * Returns the archive path on success, `null` if archival itself failed
+ * (in which case we'll log and the caller proceeds with fresh state anyway).
+ */
+async function archiveCorruptedFile(filePath) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const archive = `${filePath}.corrupted-${ts}`;
+    try {
+        await fs_1.promises.rename(filePath, archive);
+        return archive;
+    }
+    catch (e) {
+        console.error(`[state] failed to archive corrupted file ${filePath}:`, e);
+        return null;
+    }
+}
+/**
+ * @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.
+ */
+async function migrateLegacyMessageIdsFile() {
+    const legacy = path.join(os.homedir(), '.telegram-bot-messages.json');
+    try {
+        await fs_1.promises.access(legacy);
+    }
+    catch {
+        return null;
+    }
+    const backup = `${legacy}.bak`;
+    try {
+        await fs_1.promises.rename(legacy, backup);
+        return backup;
+    }
+    catch (e) {
+        console.warn(`[state] failed to archive legacy ${legacy}:`, e);
+        return null;
+    }
+}
+/**
+ * @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.
+ */
+class StateStore {
+    dataDir;
+    statePath;
+    saveDebounceMs;
+    state = emptyState();
+    /** True if the previous on-disk state file was unreadable / corrupt. */
+    corruptedOnLoad = false;
+    /** Archive path if the previous on-disk state was corrupted. */
+    corruptedArchivePath = null;
+    /** Backup path if the legacy file was migrated. */
+    legacyMigrationPath = null;
+    saveTimer = null;
+    /** Tail of the chained writes so two flushes don't try to rename simultaneously. */
+    writeChain = Promise.resolve();
+    /**
+     * 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.
+     */
+    compactIdleTrackingSavedAt = new Map();
+    keyLock = new KeyLock();
+    constructor(dataDir, options = {}) {
+        this.dataDir = dataDir;
+        this.statePath = path.join(dataDir, 'state.json');
+        this.saveDebounceMs = options.saveDebounceMs ?? DEFAULT_SAVE_DEBOUNCE_MS;
+    }
+    /**
+     * @description One-shot boot. Creates `dataDir` if missing, performs
+     * legacy migration, loads the existing state file (or starts fresh on
+     * corruption).
+     */
+    async init() {
+        await fs_1.promises.mkdir(this.dataDir, { recursive: true, mode: 0o700 });
+        // `mkdir`'s mode applies only when the dir is CREATED — an existing deploy
+        // (or a dir created earlier in this boot by the console tap / trace writer)
+        // keeps its old bits. Heal to owner-only: DATA_DIR holds state.json, traces
+        // and console logs that quote prompts/session ids. Best-effort — an exotic
+        // filesystem may refuse chmod, which must not block boot.
+        try {
+            await fs_1.promises.chmod(this.dataDir, 0o700);
+        }
+        catch (e) {
+            console.warn(`[state] could not chmod DATA_DIR to owner-only:`, e instanceof Error ? e.message : e);
+        }
+        this.legacyMigrationPath = await migrateLegacyMessageIdsFile();
+        const loaded = await loadStateFile(this.statePath);
+        if (loaded.ok) {
+            this.state = loaded.state;
+            // Top up missing fields if loaded from an older v1 file.
+            this.state.bindings ??= {};
+            this.state.agents ??= {};
+            this.state.messages ??= {};
+        }
+        else if (loaded.reason === 'missing') {
+            this.state = emptyState();
+            // No save: nothing yet to persist. First setter will trigger a debounce.
+        }
+        else {
+            this.corruptedOnLoad = true;
+            this.corruptedArchivePath = loaded.archivedTo;
+            console.error(`[state] previous state.json was corrupted (${loaded.error}); ` +
+                `archived to ${loaded.archivedTo ?? '(archive failed)'}, starting fresh`);
+            this.state = emptyState();
+            await this.flush();
+        }
+    }
+    /** Path of the live state file (for logging / docs / smoke-tests). */
+    get stateFilePath() {
+        return this.statePath;
+    }
+    /** True iff the previous boot's state file was unreadable on this start. */
+    wasCorruptedOnLoad() {
+        return this.corruptedOnLoad;
+    }
+    /** Where the previous corrupted file was moved, if archival succeeded. */
+    getCorruptedArchivePath() {
+        return this.corruptedArchivePath;
+    }
+    /** Where the legacy `~/.telegram-bot-messages.json` was archived, if it existed. */
+    getLegacyMigrationPath() {
+        return this.legacyMigrationPath;
+    }
+    // ── locking ──
+    /**
+     * @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(key, fn) {
+        return this.keyLock.withLock((0, sessionKey_1.keyToString)(key), fn);
+    }
+    // ── bindings ──
+    getBinding(key) {
+        return this.state.bindings[(0, sessionKey_1.keyToString)(key)] ?? null;
+    }
+    async setBinding(key, subdir, options = {}) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.bindings[k];
+            // Audit S20 / #44: previous code path used `existing?.closed ? …`,
+            // which falsy-collapsed an explicit `closed: false` and dropped
+            // the field entirely. Now we carry `closed` through verbatim,
+            // letting `false` and `true` round-trip independently.
+            const next = {
+                subdir,
+                createdAt: existing?.createdAt ?? new Date().toISOString(),
+            };
+            if (options.closed !== undefined) {
+                next.closed = options.closed;
+            }
+            else if (existing?.closed !== undefined) {
+                next.closed = existing.closed;
+            }
+            if (existing?.pinnedStatusMessageId !== undefined) {
+                next.pinnedStatusMessageId = existing.pinnedStatusMessageId;
+            }
+            // Carry the known topic name through a re-bind. A caller that learned
+            // the name (e.g. `/new`, deferred pending-name copy) passes it
+            // explicitly; otherwise we keep whatever was already stored.
+            if (options.topicName !== undefined) {
+                next.topicName = options.topicName;
+            }
+            else if (existing?.topicName !== undefined) {
+                next.topicName = existing.topicName;
+            }
+            this.state.bindings[k] = next;
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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}.
+     */
+    async setBindingTopicName(key, topicName) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.bindings[k];
+            if (!existing)
+                return;
+            if (existing.topicName === topicName)
+                return;
+            this.state.bindings[k] = { ...existing, topicName };
+            this.scheduleSave();
+        });
+    }
+    async setBindingClosed(key, closed) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.bindings[k];
+            if (!existing)
+                return;
+            this.state.bindings[k] = { ...existing, closed };
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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.
+     */
+    async setBindingPinnedStatusMessageId(key, messageId) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.bindings[k];
+            if (!existing)
+                return;
+            if (messageId === null) {
+                if (existing.pinnedStatusMessageId === undefined)
+                    return;
+                const { pinnedStatusMessageId: _drop, ...rest } = existing;
+                this.state.bindings[k] = rest;
+            }
+            else {
+                if (existing.pinnedStatusMessageId === messageId)
+                    return;
+                this.state.bindings[k] = { ...existing, pinnedStatusMessageId: messageId };
+            }
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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).
+     */
+    async setBindingPinnedStatusText(key, text) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.bindings[k];
+            if (!existing)
+                return;
+            if (text === null) {
+                if (existing.pinnedStatusText === undefined)
+                    return;
+                const { pinnedStatusText: _drop, ...rest } = existing;
+                this.state.bindings[k] = rest;
+            }
+            else {
+                if (existing.pinnedStatusText === text)
+                    return;
+                this.state.bindings[k] = { ...existing, pinnedStatusText: text };
+            }
+            this.scheduleSave();
+        });
+    }
+    async removeBinding(key) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            delete this.state.bindings[k];
+            delete this.state.agents[k];
+            delete this.state.messages[k];
+            // The thread is gone (unbind / deleted topic) → so is anything a boot
+            // recovery could resume for it, and the record of its pinned answer.
+            this.dropLimitEpisodeRecovered(k);
+            this.dropOptionalMapEntry('answerPins', k);
+            this.scheduleSave();
+        });
+    }
+    listBindings() {
+        const out = [];
+        for (const [keyStr, data] of Object.entries(this.state.bindings)) {
+            const key = (0, sessionKey_1.tryKeyFromString)(keyStr);
+            if (key)
+                out.push({ key, data });
+        }
+        return out;
+    }
+    /**
+     * @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) {
+        const out = [];
+        for (const [keyStr, data] of Object.entries(this.state.bindings)) {
+            if (data.subdir === subdir) {
+                const key = (0, sessionKey_1.tryKeyFromString)(keyStr);
+                if (key)
+                    out.push(key);
+            }
+        }
+        return out;
+    }
+    // ── agents ──
+    getAgent(key) {
+        return this.state.agents[(0, sessionKey_1.keyToString)(key)] ?? 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.
+     */
+    async setAgent(key, data) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.agents[k];
+            this.state.agents[k] = { ...existing, ...data };
+            this.scheduleSave();
+        });
+    }
+    async removeAgent(key) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            delete this.state.agents[k];
+            this.scheduleSave();
+        });
+    }
+    getClaudeSessionId(key) {
+        return this.state.agents[(0, sessionKey_1.keyToString)(key)]?.claudeSessionId ?? 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`.
+     */
+    async setClaudeSessionId(key, uuid) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.agents[k];
+            this.state.agents[k] = existing
+                ? { ...existing, claudeSessionId: uuid }
+                : { name: 'claude', claudeSessionId: uuid };
+            this.scheduleSave();
+        });
+    }
+    getOpenCodeSessionId(key) {
+        return this.state.agents[(0, sessionKey_1.keyToString)(key)]?.opencodeSessionId ?? null;
+    }
+    /** Symmetric to {@link setClaudeSessionId} — does not flip `agent.name`. */
+    async setOpenCodeSessionId(key, id) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.agents[k];
+            this.state.agents[k] = existing
+                ? { ...existing, opencodeSessionId: id }
+                : { name: 'opencode', opencodeSessionId: id };
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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.
+     */
+    async setSeenWatermark(key, watermark) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.agents[k];
+            if (!existing)
+                return;
+            this.state.agents[k] = { ...existing, seenWatermark: watermark };
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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.
+     */
+    async setJsonStreamTail(key, tail) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.agents[k];
+            if (!existing)
+                return;
+            this.state.agents[k] = { ...existing, jsonStreamTail: tail };
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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.
+     */
+    async setAgentStartedAt(key, startedAt) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.agents[k];
+            if (!existing)
+                return;
+            this.state.agents[k] = { ...existing, startedAt };
+            this.scheduleSave();
+        });
+    }
+    /** Persist the tool digest a json-stream process was started with (see {@link AgentData.mcpToolDigest}); merge-only. */
+    async setAgentMcpToolDigest(key, mcpToolDigest) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.agents[k];
+            if (!existing)
+                return;
+            this.state.agents[k] = { ...existing, mcpToolDigest };
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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.
+     */
+    async clearAgentSessionIds(key) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            // A released session can never be the one a boot recovery resumes (it checks
+            // `checkIsActive` + the persisted session id), so its handled-limit-episode
+            // marker becomes a dead key — drop it with the ids instead of letting
+            // `state.json` accumulate one per retired session.
+            const droppedMarker = this.dropLimitEpisodeRecovered(k);
+            const existing = this.state.agents[k];
+            if (!existing) {
+                if (droppedMarker)
+                    this.scheduleSave();
+                return;
+            }
+            const { claudeSessionId, opencodeSessionId, jsonStreamTail, startedAt, mcpToolDigest, ...rest } = existing;
+            this.state.agents[k] = rest;
+            this.scheduleSave();
+        });
+    }
+    // ── messages (`/clear` support) ──
+    getMessageIds(key) {
+        return this.state.messages[(0, sessionKey_1.keyToString)(key)]?.slice() ?? [];
+    }
+    /** Append IDs to the bounded in-memory ring while the caller holds the key lock. */
+    appendMessageIds(keyStr, messageIds) {
+        const list = (this.state.messages[keyStr] ??= []);
+        list.push(...messageIds);
+        if (list.length > MESSAGE_ID_RING_CAP) {
+            this.state.messages[keyStr] = list.slice(-MESSAGE_ID_RING_CAP);
+        }
+    }
+    /**
+     * @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).
+     */
+    async pushMessageId(key, msgId) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            this.appendMessageIds(k, [msgId]);
+            this.scheduleSave();
+        });
+    }
+    /** Atomically append and durably persist one Telegram response's message IDs. */
+    async pushMessageIds(key, messageIds) {
+        if (messageIds.length === 0)
+            return;
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            this.appendMessageIds(k, messageIds);
+            await this.flush();
+        });
+    }
+    /** Atomically hand tracked IDs to `/clear_messages` while later pushes remain tracked. */
+    async takeMessageIds(key, additionalIds = []) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        return this.withLock(key, async () => {
+            const messageIds = [...(this.state.messages[k] ?? []), ...additionalIds];
+            if (this.state.messages[k] !== undefined) {
+                delete this.state.messages[k];
+                this.scheduleSave();
+            }
+            return messageIds;
+        });
+    }
+    // ── heartbeat (hot-reload vs cold-start detection) ──
+    /**
+     * @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 = Date.now()) {
+        this.state.lastHeartbeatAt = now;
+        this.scheduleSave();
+    }
+    /**
+     * @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 = Date.now()) {
+        const last = this.state.lastHeartbeatAt;
+        if (typeof last !== 'number' || !Number.isFinite(last))
+            return null;
+        return Math.max(0, now - last);
+    }
+    // ── paired group id (auto-pairing) ──
+    /** The auto-paired forum supergroup id, or `null` if never paired. */
+    getPairedGroupId() {
+        return this.state.pairedGroupId ?? 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.
+     */
+    async setPairedGroupId(groupId) {
+        this.state.pairedGroupId = groupId;
+        await this.flush();
+    }
+    // ── output-trace toggle (`/trace`) ──
+    /**
+     * @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() {
+        return {
+            allThreads: this.state.traceAllThreads ?? true,
+            threadKeys: this.state.tracedThreads?.slice() ?? [],
+        };
+    }
+    /**
+     * @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.
+     */
+    async setTraceConfig(config) {
+        const uniqueKeys = [...new Set(config.threadKeys)].sort();
+        if (uniqueKeys.length > 0)
+            this.state.tracedThreads = uniqueKeys;
+        else
+            delete this.state.tracedThreads;
+        this.state.traceAllThreads = config.allThreads;
+        this.scheduleSave();
+    }
+    // ── per-chat locale (`/language`) ──
+    getChatLocaleOverride(chatId) {
+        return this.state.chatLocaleOverrides?.[chatId.toString()] ?? null;
+    }
+    getChatTelegramLocale(chatId) {
+        return this.state.chatTelegramLocales?.[chatId.toString()] ?? null;
+    }
+    async setChatLocaleOverride(chatId, locale) {
+        const chatIdKey = chatId.toString();
+        if (locale === null) {
+            if (!this.state.chatLocaleOverrides?.[chatIdKey])
+                return;
+            delete this.state.chatLocaleOverrides[chatIdKey];
+            if (Object.keys(this.state.chatLocaleOverrides).length === 0) {
+                delete this.state.chatLocaleOverrides;
+            }
+            this.scheduleSave();
+            return;
+        }
+        if (this.state.chatLocaleOverrides?.[chatIdKey] === locale)
+            return;
+        (this.state.chatLocaleOverrides ??= {})[chatIdKey] = locale;
+        this.scheduleSave();
+    }
+    async setChatTelegramLocale(chatId, locale) {
+        const chatIdKey = chatId.toString();
+        if (this.state.chatTelegramLocales?.[chatIdKey] === locale)
+            return;
+        (this.state.chatTelegramLocales ??= {})[chatIdKey] = locale;
+        this.scheduleSave();
+    }
+    // ── per-thread prompt-timestamp toggle (`/timestamps`) ──
+    /**
+     * @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) {
+        return this.state.timestampThreads?.includes((0, sessionKey_1.keyToString)(key)) ?? false;
+    }
+    /**
+     * @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.
+     */
+    async setTimestampsEnabled(key, isEnabled) {
+        const keyStr = (0, sessionKey_1.keyToString)(key);
+        const current = new Set(this.state.timestampThreads ?? []);
+        if (isEnabled)
+            current.add(keyStr);
+        else
+            current.delete(keyStr);
+        const uniqueKeys = [...current].sort();
+        if (uniqueKeys.length > 0)
+            this.state.timestampThreads = uniqueKeys;
+        else
+            delete this.state.timestampThreads;
+        this.scheduleSave();
+    }
+    // ── hidden `/model` providers (global, not per-thread) ──
+    /**
+     * @description Providers currently hidden from the `/model` picker, in the
+     * stable sorted on-disk order. Empty when nothing is hidden (the default).
+     */
+    getHiddenModelProviders() {
+        return this.state.hiddenModelProviders?.slice() ?? [];
+    }
+    /**
+     * @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.
+     */
+    async setModelProviderHidden(provider, isHidden) {
+        const current = new Set(this.state.hiddenModelProviders ?? []);
+        if (isHidden)
+            current.add(provider);
+        else
+            current.delete(provider);
+        const uniqueProviders = [...current].sort();
+        if (uniqueProviders.length > 0)
+            this.state.hiddenModelProviders = uniqueProviders;
+        else
+            delete this.state.hiddenModelProviders;
+        this.scheduleSave();
+    }
+    // ── compact-on-idle toggle (`/compact_on_idle`) ──
+    /**
+     * @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() {
+        return this.state.compactOnIdleEnabled ?? true;
+    }
+    /**
+     * @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) {
+        return this.state.compactOnIdleOverrides?.[(0, sessionKey_1.keyToString)(key)];
+    }
+    /**
+     * @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) {
+        return (0, compactOnIdle_1.resolveCompactOnIdleEnabled)(this.state.compactOnIdleEnabled, this.getCompactOnIdleOverride(key));
+    }
+    /**
+     * @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).
+     */
+    async setCompactOnIdleGlobalDefault(enabled) {
+        if (this.state.compactOnIdleEnabled === enabled)
+            return;
+        this.state.compactOnIdleEnabled = enabled;
+        this.scheduleSave();
+    }
+    /**
+     * @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.
+     */
+    async setCompactOnIdleOverride(key, enabled) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            if (this.state.compactOnIdleOverrides?.[k] === enabled)
+                return;
+            (this.state.compactOnIdleOverrides ??= {})[k] = enabled;
+            this.scheduleSave();
+        });
+    }
+    // ── full-summary toggle (`/compact_summary`) ──
+    /**
+     * @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() {
+        return this.state.compactSummaryEnabled ?? false;
+    }
+    /**
+     * @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) {
+        return this.state.compactSummaryOverrides?.[(0, sessionKey_1.keyToString)(key)];
+    }
+    /**
+     * @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) {
+        return (0, compactOnIdle_1.resolveCompactSummaryEnabled)(this.state.compactSummaryEnabled, this.getCompactSummaryOverride(key));
+    }
+    /**
+     * @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}.
+     */
+    async setCompactSummaryGlobalDefault(enabled) {
+        if (this.state.compactSummaryEnabled === enabled)
+            return;
+        this.state.compactSummaryEnabled = enabled;
+        this.scheduleSave();
+    }
+    /**
+     * @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}.
+     */
+    async setCompactSummaryOverride(key, enabled) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            if (this.state.compactSummaryOverrides?.[k] === enabled)
+                return;
+            (this.state.compactSummaryOverrides ??= {})[k] = enabled;
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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) {
+        return this.state.compactIdleLatchedThreads?.includes((0, sessionKey_1.keyToString)(key)) ?? false;
+    }
+    /**
+     * @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.
+     */
+    async setCompactIdleLatched(key, isLatched) {
+        const keyStr = (0, sessionKey_1.keyToString)(key);
+        const current = new Set(this.state.compactIdleLatchedThreads ?? []);
+        if (isLatched)
+            current.add(keyStr);
+        else
+            current.delete(keyStr);
+        const uniqueKeys = [...current].sort();
+        if (uniqueKeys.length > 0)
+            this.state.compactIdleLatchedThreads = uniqueKeys;
+        else
+            delete this.state.compactIdleLatchedThreads;
+        this.scheduleSave();
+    }
+    // ── compact-on-idle per-thread bookkeeping (the countdown's restart guard) ──
+    /**
+     * @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) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        const entry = this.state.compactIdleTracking?.[k];
+        const sessionId = this.getAgentSessionId(k);
+        if (!entry || !sessionId || entry.sessionId !== sessionId) {
+            return { lastActivityAt: 0, lastTurnEndAt: 0, lastCompactionAt: 0 };
+        }
+        return {
+            lastActivityAt: entry.lastActivityAt ?? 0,
+            lastTurnEndAt: entry.lastTurnEndAt ?? 0,
+            lastCompactionAt: entry.lastCompactionAt ?? 0,
+        };
+    }
+    /**
+     * @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, now = Date.now()) {
+        this.stampCompactIdleTracking(key, 'lastActivityAt', now);
+    }
+    /**
+     * @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, now = Date.now()) {
+        this.stampCompactIdleTracking(key, 'lastTurnEndAt', now);
+    }
+    /**
+     * @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.
+     */
+    async setCompactIdleCompactedAt(key, now = Date.now()) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const sessionId = this.getAgentSessionId(k);
+            if (!sessionId)
+                return; // nothing to bind the marker to — see `getAgentSessionId`
+            const tracking = (this.state.compactIdleTracking ??= {});
+            const existing = tracking[k];
+            // A stamp under a DIFFERENT session starts the entry fresh: the previous
+            // session's instants describe a context this one no longer has.
+            const base = existing?.sessionId === sessionId ? existing : {};
+            tracking[k] = { ...base, sessionId, lastCompactionAt: now };
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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`.
+     */
+    async clearCompactIdleTracking(key) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        this.compactIdleTrackingSavedAt.delete(k);
+        await this.withLock(key, async () => {
+            if (!this.state.compactIdleTracking?.[k])
+                return;
+            delete this.state.compactIdleTracking[k];
+            if (Object.keys(this.state.compactIdleTracking).length === 0) {
+                delete this.state.compactIdleTracking;
+            }
+            this.scheduleSave();
+        });
+    }
+    /**
+     * 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.
+     */
+    stampCompactIdleTracking(key, field, now) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        const sessionId = this.getAgentSessionId(k);
+        if (!sessionId)
+            return; // nothing to bind the marker to — see `getAgentSessionId`
+        const tracking = (this.state.compactIdleTracking ??= {});
+        const existing = tracking[k];
+        // A stamp under a DIFFERENT session REPLACES the entry rather than merging
+        // into it — the old session's instants must not survive the swap.
+        const isFreshSession = !existing || existing.sessionId !== sessionId;
+        const entry = existing && !isFreshSession ? existing : { sessionId };
+        tracking[k] = entry;
+        entry[field] = now;
+        // A fresh session's first stamp always persists, so the new binding reaches
+        // disk instead of waiting out the coarse step behind a stale one.
+        const savedAt = isFreshSession ? 0 : this.compactIdleTrackingSavedAt.get(k) ?? 0;
+        if (now - savedAt < exports.compactIdleTrackingPersistStepMs)
+            return;
+        this.compactIdleTrackingSavedAt.set(k, now);
+        this.scheduleSave();
+    }
+    /**
+     * 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.
+     */
+    getAgentSessionId(keyStr) {
+        const agent = this.state.agents[keyStr];
+        return agent?.claudeSessionId ?? agent?.opencodeSessionId;
+    }
+    // ── limit auto-continue toggle (`/auto_continue_limits`) ──
+    /**
+     * @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() {
+        return this.state.autoContinueOnLimitEnabled ?? true;
+    }
+    /**
+     * @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) {
+        return this.state.autoContinueOnLimitOverrides?.[(0, sessionKey_1.keyToString)(key)];
+    }
+    /**
+     * @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) {
+        return (0, autoContinueOnLimit_1.resolveAutoContinueOnLimitEnabled)(this.state.autoContinueOnLimitEnabled, this.getAutoContinueOnLimitOverride(key));
+    }
+    /**
+     * @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).
+     */
+    async setAutoContinueOnLimitGlobalDefault(enabled) {
+        if (this.state.autoContinueOnLimitEnabled === enabled)
+            return;
+        this.state.autoContinueOnLimitEnabled = enabled;
+        this.scheduleSave();
+    }
+    /**
+     * @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.
+     */
+    async setAutoContinueOnLimitOverride(key, enabled) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            if (this.state.autoContinueOnLimitOverrides?.[k] === enabled) {
+                return;
+            }
+            (this.state.autoContinueOnLimitOverrides ??= {})[k] = enabled;
+            this.scheduleSave();
+        });
+    }
+    // ── instance-wide timezone (`/timezone`) ──
+    /**
+     * @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() {
+        return this.state.timezone ?? 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.
+     */
+    async setTimezone(timezone) {
+        if (timezone === null)
+            delete this.state.timezone;
+        else
+            this.state.timezone = timezone;
+        await this.flush();
+    }
+    // ── per-thread display preferences (`/thinking`, `/tool-results`, `/subagent`) ──
+    /**
+     * @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) {
+        const stored = this.state.displayPrefs?.[(0, sessionKey_1.keyToString)(key)];
+        return {
+            thinking: (0, displayVerbosity_1.normalizeDisplayVerbosityMode)(stored?.thinking) ?? displayVerbosity_1.defaultDisplayVerbosityMode,
+            toolResults: (0, displayVerbosity_1.normalizeDisplayVerbosityMode)(stored?.toolResults) ?? displayVerbosity_1.defaultDisplayVerbosityMode,
+            subagent: (0, displayVerbosity_1.normalizeDisplayVerbosityMode)(stored?.subagent) ?? displayVerbosity_1.defaultDisplayVerbosityMode,
+            view: (0, topicView_1.parseTopicView)(stored?.view) ?? topicView_1.defaultTopicView,
+        };
+    }
+    /**
+     * @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.
+     */
+    async setDisplayPref(key, field, value) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const isDefault = value === (field === 'view' ? topicView_1.defaultTopicView : displayVerbosity_1.defaultDisplayVerbosityMode);
+            const existing = this.state.displayPrefs?.[k];
+            if (isDefault) {
+                // Clear the override; drop the record (and the map) once empty so an
+                // all-defaults thread leaves no trace in state.json.
+                if (!existing || existing[field] === undefined)
+                    return;
+                const { [field]: _drop, ...rest } = existing;
+                if (Object.keys(rest).length === 0) {
+                    delete this.state.displayPrefs[k];
+                    if (Object.keys(this.state.displayPrefs).length === 0) {
+                        delete this.state.displayPrefs;
+                    }
+                }
+                else {
+                    this.state.displayPrefs[k] = rest;
+                }
+                this.scheduleSave();
+                return;
+            }
+            if (existing?.[field] === value)
+                return;
+            (this.state.displayPrefs ??= {})[k] = { ...existing, [field]: value };
+            this.scheduleSave();
+        });
+    }
+    // ── scheduled jobs (`/schedule`) ──
+    /**
+     * @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() {
+        return { ...(this.state.schedules ?? {}) };
+    }
+    /** Schedules owned by `key`, in insertion order. Empty array when none. */
+    getThreadSchedules(key) {
+        const target = (0, sessionKey_1.keyToString)(key);
+        const all = this.state.schedules ?? {};
+        return Object.values(all).filter(record => record.threadKey === target);
+    }
+    /**
+     * @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.
+     */
+    async upsertSchedule(record) {
+        const target = (0, sessionKey_1.tryKeyFromString)(record.threadKey);
+        if (!target)
+            return;
+        await this.withLock(target, async () => {
+            (this.state.schedules ??= {})[record.id] = record;
+            this.scheduleSave();
+        });
+    }
+    /** Remove a schedule by id. No-op (no save) when absent. */
+    async removeSchedule(id) {
+        const existing = this.state.schedules?.[id];
+        if (!existing)
+            return;
+        const owner = (0, sessionKey_1.tryKeyFromString)(existing.threadKey);
+        const run = async () => {
+            if (this.state.schedules) {
+                delete this.state.schedules[id];
+                if (Object.keys(this.state.schedules).length === 0)
+                    delete this.state.schedules;
+            }
+            this.scheduleSave();
+        };
+        if (owner)
+            await this.withLock(owner, run);
+        else
+            await run();
+    }
+    /**
+     * @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.
+     */
+    async setSchedulePaused(id, paused, reason) {
+        const existing = this.state.schedules?.[id];
+        if (!existing)
+            return;
+        const owner = (0, sessionKey_1.tryKeyFromString)(existing.threadKey);
+        const run = async () => {
+            const current = this.state.schedules?.[id];
+            if (!current)
+                return;
+            if (paused) {
+                current.isPaused = true;
+                if (reason !== undefined)
+                    current.pauseReason = reason;
+            }
+            else {
+                delete current.isPaused;
+                delete current.pauseReason;
+            }
+            current.updatedAt = new Date().toISOString();
+            this.scheduleSave();
+        };
+        if (owner)
+            await this.withLock(owner, run);
+        else
+            await run();
+    }
+    // ── scheduler MCP secret ──
+    /**
+     * @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.
+     */
+    async getSchedulerMcpSecret() {
+        if (this.state.schedulerMcpSecret)
+            return this.state.schedulerMcpSecret;
+        const secret = (0, node_crypto_1.randomBytes)(schedulerMcpSecretByteLength).toString('hex');
+        this.state.schedulerMcpSecret = secret;
+        await this.flush();
+        return secret;
+    }
+    // ── scheduler MCP port (reuse across restarts) ──
+    /**
+     * @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() {
+        return this.state.schedulerMcpPort;
+    }
+    /**
+     * @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.
+     */
+    async setSchedulerMcpPort(port) {
+        this.state.schedulerMcpPort = port;
+        await this.flush();
+    }
+    // ── pending interactive questions (restart survival) ──
+    /**
+     * @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() {
+        return { ...(this.state.pendingQuestions ?? {}) };
+    }
+    /**
+     * @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.
+     */
+    async setPendingQuestion(key, value) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            (this.state.pendingQuestions ??= {})[k] = value;
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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`.
+     */
+    async clearPendingQuestion(key) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            if (!this.state.pendingQuestions?.[k])
+                return;
+            delete this.state.pendingQuestions[k];
+            if (Object.keys(this.state.pendingQuestions).length === 0) {
+                delete this.state.pendingQuestions;
+            }
+            this.scheduleSave();
+        });
+    }
+    // ── armed API-error auto-retries (restart survival) ──
+    /**
+     * @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() {
+        return { ...(this.state.apiRetries ?? {}) };
+    }
+    /**
+     * @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`.
+     */
+    async setApiRetry(key, value) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            (this.state.apiRetries ??= {})[k] = value;
+            this.scheduleSave();
+        });
+    }
+    /**
+     * @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`.
+     */
+    async clearApiRetry(key) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            if (!this.state.apiRetries?.[k])
+                return;
+            delete this.state.apiRetries[k];
+            if (Object.keys(this.state.apiRetries).length === 0) {
+                delete this.state.apiRetries;
+            }
+            this.scheduleSave();
+        });
+    }
+    // ── prompts held during a usage-limit wait (R23) ──
+    /** @description The prompts held for `key`, oldest first; `[]` when none. A copy. */
+    getLimitHeldPrompts(key) {
+        return (this.state.limitHeldPrompts?.[(0, sessionKey_1.keyToString)(key)] ?? []).map((prompt) => ({ ...prompt }));
+    }
+    /**
+     * @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, prompts) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        if (prompts.length > 0) {
+            (this.state.limitHeldPrompts ??= {})[k] = prompts.map((prompt) => ({ ...prompt }));
+        }
+        else {
+            if (!this.state.limitHeldPrompts?.[k])
+                return;
+            delete this.state.limitHeldPrompts[k];
+            if (Object.keys(this.state.limitHeldPrompts).length === 0)
+                delete this.state.limitHeldPrompts;
+        }
+        this.scheduleSave();
+    }
+    // ── open requests (request ledger) ──
+    /**
+     * @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() {
+        return { ...(this.state.openRequests ?? {}) };
+    }
+    /** @description The open request of `group`, or `undefined`. */
+    getOpenRequest(group) {
+        return this.state.openRequests?.[(0, requestGroup_1.requestGroupKeyToString)(group)];
+    }
+    /**
+     * @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`.
+     */
+    async updateOpenRequest(group, mutate) {
+        const k = (0, requestGroup_1.requestGroupKeyToString)(group);
+        await this.withLock(group.conversation, async () => {
+            const current = this.state.openRequests?.[k];
+            const next = mutate(current);
+            if (next === current)
+                return;
+            if (next === undefined) {
+                if (!this.dropOptionalMapEntry('openRequests', k))
+                    return;
+            }
+            else {
+                (this.state.openRequests ??= {})[k] = next;
+            }
+            this.scheduleSave();
+        });
+    }
+    /** @description The alerts of closed requests still to release (a copy). */
+    getUnreleasedRequestAlerts() {
+        return { ...(this.state.unreleasedRequestAlerts ?? {}) };
+    }
+    /**
+     * @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, alert) {
+        (this.state.unreleasedRequestAlerts ??= {})[requestId] = alert;
+        this.scheduleSave();
+    }
+    /** @description The alert of `requestId` was released; forget it. */
+    removeUnreleasedRequestAlert(requestId) {
+        if (!this.state.unreleasedRequestAlerts?.[requestId])
+            return;
+        delete this.state.unreleasedRequestAlerts[requestId];
+        if (Object.keys(this.state.unreleasedRequestAlerts).length === 0)
+            delete this.state.unreleasedRequestAlerts;
+        this.scheduleSave();
+    }
+    // ── pinned answers (S8) ──
+    /** @description The message id of the latest pinned answer in `key`'s conversation, or `undefined`. */
+    getAnswerPinMessageId(key) {
+        return this.state.answerPins?.[(0, sessionKey_1.keyToString)(key)];
+    }
+    /**
+     * @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.
+     */
+    async setAnswerPinMessageId(key, messageId) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            if (this.state.answerPins?.[k] === messageId)
+                return;
+            (this.state.answerPins ??= {})[k] = messageId;
+            this.scheduleSave();
+        });
+    }
+    /**
+     * 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.
+     */
+    dropOptionalMapEntry(field, k) {
+        const map = this.state[field];
+        if (map?.[k] === undefined)
+            return false;
+        delete map[k];
+        if (Object.keys(map).length === 0)
+            delete this.state[field];
+        return true;
+    }
+    // ── handled limit episodes (boot-recovery marker) ──
+    /**
+     * @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) {
+        return this.state.limitEpisodesRecovered?.[(0, sessionKey_1.keyToString)(key)];
+    }
+    /**
+     * @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.
+     */
+    async setLimitEpisodeRecovered(key, value) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            (this.state.limitEpisodesRecovered ??= {})[k] = value;
+            this.scheduleSave();
+        });
+    }
+    /**
+     * Drop `keyStr`'s handled-episode marker (and the whole map once empty). Returns
+     * whether anything changed. Caller must hold the key lock.
+     */
+    dropLimitEpisodeRecovered(keyStr) {
+        return this.dropOptionalMapEntry('limitEpisodesRecovered', keyStr);
+    }
+    // ── transient status-frame ids (restart cleanup) ──
+    /**
+     * @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() {
+        return { ...(this.state.transientFrames ?? {}) };
+    }
+    /**
+     * @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.
+     */
+    async setTransientFrames(key, ids) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        await this.withLock(key, async () => {
+            const existing = this.state.transientFrames?.[k];
+            if (ids.length === 0) {
+                if (!existing)
+                    return;
+                delete this.state.transientFrames[k];
+                if (Object.keys(this.state.transientFrames).length === 0) {
+                    delete this.state.transientFrames;
+                }
+                this.scheduleSave();
+                return;
+            }
+            if (existing && existing.length === ids.length && existing.every((v, i) => v === ids[i])) {
+                return;
+            }
+            (this.state.transientFrames ??= {})[k] = ids.slice();
+            this.scheduleSave();
+        });
+    }
+    // ── persistence ──
+    /** Schedule a save in `saveDebounceMs`. Repeated calls reset the timer. */
+    scheduleSave() {
+        if (this.saveTimer)
+            clearTimeout(this.saveTimer);
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            // Errors are logged inside flush; we don't want to crash the timer chain.
+            this.flush().catch(e => console.error('[state] background flush failed:', e));
+        }, this.saveDebounceMs);
+    }
+    /**
+     * @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.
+     */
+    async flush() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        const snapshot = JSON.stringify(this.state, null, 2);
+        const writeNow = () => writeFileAtomic(this.statePath, snapshot);
+        const next = this.writeChain.then(writeNow, writeNow);
+        this.writeChain = next.catch(() => { });
+        await next;
+    }
+}
+exports.StateStore = StateStore;
+// ─── singleton wiring ────────────────────────────────────────────────
+let singleton = null;
+let singletonInFlight = null;
+/**
+ * @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.
+ */
+function resolveDataDir() {
+    return process.env.DATA_DIR || path.join(os.homedir(), '.telegramCode');
+}
+/**
+ * @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.
+ */
+async function getStateStore() {
+    if (singleton)
+        return singleton;
+    if (singletonInFlight)
+        return singletonInFlight;
+    singletonInFlight = (async () => {
+        const store = new StateStore(resolveDataDir());
+        await store.init();
+        singleton = store;
+        return store;
+    })();
+    try {
+        return await singletonInFlight;
+    }
+    finally {
+        singletonInFlight = null;
+    }
+}
+/**
+ * @description Reset the singleton — only for tests. Production code should
+ * never call this; doing so would leak in-flight write promises.
+ */
+function _resetStateStoreSingletonForTests() {
+    singleton = null;
+    singletonInFlight = null;
+}
+//# sourceMappingURL=state.js.map